man(1)								   User Commands							    man(1)

NAME

       man - find and display reference manual pages

SYNOPSIS

       man [-] [-adFlrt] [-M path] [-T macro-package] [-s section] name...

       man [-M path] -k keyword...

       man [-M path] -f file...

DESCRIPTION

       The  man  command  displays  information from the reference manuals. It displays complete manual pages that you select by name, or one-line
       summaries selected either by keyword (-k), or by the name of an associated file (-f). If no manual page is located,  man  prints  an  error
       message.

   Source Format
       Reference  Manual  pages  are marked up with either nroff (see nroff(1)) or SGML (Standard Generalized Markup Language) tags (see sgml(5)).
       The man command recognizes the type of markup and processes the file accordingly. The various source files are kept in separate directories
       depending on the type of markup.

   Location of Manual Pages
       The  online  Reference  Manual  page  directories  are  conventionally  located	in  /usr/share/man.  The  nroff sources are located in the
       /usr/share/man/man* directories. The SGML sources are located in the /usr/share/man/sman* directories. Each directory corresponds to a sec-
       tion  of  the  manual.  Since  these  directories  are  optionally  installed,  they might not reside on your host. You might have to mount
       /usr/share/man from a host on which they do reside.

       If there are preformatted, up-to-date versions in the corresponding cat* or fmt* directories, man simply displays or prints those versions.
       If the preformatted version of interest is out of date or missing, man reformats it prior to display and stores the preformatted version if
       cat* or fmt* is writable. The windex database is not updated. See catman(1M). If directories for the preformatted  versions  are  not  pro-
       vided, man reformats a page whenever it is requested. man uses a temporary file to store the formatted text during display.

       If the standard output is not a terminal, or if the `-' flag is given, man pipes its output through cat(1). Otherwise, man pipes its output
       through more(1) to handle paging and underlining on the screen.

OPTIONS

       The following options are supported:

       -a		   Shows all manual pages matching name within the MANPATH search path. Manual pages are displayed in the order found.

       -d		   Debugs. Displays what a section-specifier evaluates to, method used for searching, and paths searched by man.

       -f file ...	   man attempts to locate manual pages related to any of the given files. It strips the leading path name components  from
			   each  file,	and  then  prints one-line summaries containing the resulting basename or names. This option also uses the
			   windex database.

       -F		   Forces man to search all directories specified by MANPATH or the man.cf file, rather than using the windex lookup data-
			   base. This option is useful if the database is not up to date and it has been made the default behavior of the man com-
			   mand. The option therefore does not have to be invoked and is documented here for reference only.

       -k keyword ...	   Prints out one-line summaries from the windex database (table of contents) that contain any of the given keywords.  The
			   windex database is created using catman(1M).

       -l		   Lists all manual pages found matching name within the search path.

       -M path		   Specifies  an alternate search path for manual pages. path is a colon-separated list of directories that contain manual
			   page directory subtrees. For example, if path is /usr/share/man:/usr/local/man, man searches for name in  the  standard
			   location, and then /usr/local/man. When used with the -k or -f options, the -M option must appear first. Each directory
			   in the path is assumed to contain subdirectories of the form man* or sman* , one for each section.  This  option  over-
			   rides the MANPATH environment variable.

       -r		   Reformats the manual page, but does not display it. This replaces the man - -t name combination.

       -s section ...	   Specifies sections of the manual for man to search. The directories searched for name are limited to those specified by
			   section. section can be a numerical digit, perhaps followed by one or more letters to match the desired section of  the
			   manual,  for example, "3libucb". Also, section can be a word, for example, local, new, old, public. section can also be
			   a letter. To specify multiple sections, separate each section with a comma. This option overrides the MANPATH  environ-
			   ment variable and the man.cf file. See Search Path below for an explanation of how man conducts its search.

       -t		   man	arranges  for  the specified manual pages to be troffed to a suitable raster output device (see troff(1)). If both
			   the - and -t flags are given, man updates the troffed versions of each named name (if necessary), but does not  display
			   them.

       -T macro-package    Formats  manual  pages  using macro-package rather than the standard -man macros defined in /usr/share/lib/tmac/an. See
			   Search Path under USAGE for a complete explanation of the default search path order.

OPERANDS

       The following operand is supported:

       name    The name of a standard utility or a keyword.

USAGE

       The usage of man is described below:

   Manual Page Sections
       Entries in the reference manuals are organized into sections. A section name consists of a major section name, typically  a  single  digit,
       optionally followed by a subsection name, typically one or more letters. An unadorned major section name, for example, "9", does not act as
       an abbreviation for the subsections of that name, such as "9e", "9f", or "9s". That is, each subsection must be searched separately by  man
       -s.  Each  section  contains descriptions apropos to a particular reference category, with subsections refining these distinctions. See the
       intro manual pages for an explanation of the classification used in this release.

   Search Path
       Before searching for a given name, man constructs a list of candidate directories and sections. man searches for name  in  the  directories
       specified by the MANPATH environment variable.

       In  the	absence of MANPATH, man constructs its search path based upon the PATH environment variable, primarily by substituting man for the
       last component of the PATH element. Special provisions are added to account for	unique	characteristics  of  directories  such	as  /sbin,
       /usr/ucb,  /usr/xpg4/bin,  and others. If the file argument contains a / character, the dirname portion of the argument is used in place of
       PATH elements to construct the search path.

       Within the manual page directories, man confines its search to the sections specified in the following order:

	   o	  sections specified on the command line with the -s option

	   o	  sections embedded in the MANPATH environment variable

	   o	  sections specified in the man.cf file for each directory specified in the MANPATH environment variable

       If none of the above exist, man searches each directory in the manual page path, and displays the first matching manual page found.

       The man.cf file has the following format:

	 MANSECTS=section[,section]...

       Lines beginning with `#' and blank lines are considered comments, and are ignored. Each directory specified in MANPATH can contain a manual
       page configuration file, specifying the default search order for that directory.

FORMATTING MANUAL PAGES

       Manual  pages  are  marked up in nroff(1) or sgml(5). Nroff manual pages are processed by nroff(1) or troff(1) with the -man macro package.
       Please refer to man(5) for information on macro usage. SGML--tagged manual pages are processed by an SGML parser and passed to the  format-
       ter.

   Preprocessing Nroff Manual Pages
       When formatting an nroff manual page, man examines the first line to determine whether it requires special processing. If the first line is
       a string of the form:

	 '" X

       where X is separated from the `"' by a single SPACE and consists of any combination of characters in the  following  list,  man	pipes  its
       input to troff(1) or nroff(1) through the corresponding preprocessors.

       e    eqn(1), or neqn for nroff

       r    refer(1)

       t    tbl(1)

       v    vgrind(1)

       If  eqn	or neqn is invoked, it automatically reads the file /usr/pub/eqnchar (see eqnchar(5)). If nroff(1) is invoked, col(1) is automati-
       cally used.

   Referring to Other nroff Manual Pages
       If the first line of the nroff manual page is a reference to another manual page entry fitting the pattern:

	 .so man*/sourcefile

       man processes the indicated file in place of the current one. The reference must be expressed as a path name relative to the  root  of  the
       manual page directory subtree.

       When the second or any subsequent line starts with .so, man ignores it; troff(1) or nroff(1) processes the request in the usual manner.

   Processing SGML Manual Pages
       Manual  pages  are  identified  as  being  marked  up in SGML by the presence of the string <!DOCTYPE. If the file also contains the string
       SHADOW_PAGE, the file refers to another manual page for the content. The reference is made with a file entity reference to the manual  page
       that contains the text. This is similar to the .so mechanism used in the nroff formatted man pages.

ENVIRONMENT VARIABLES

       See  environ(5)	for  descriptions of the following environment variables that affect the execution of man: LANG, LC_ALL, LC_CTYPE, LC_MES-
       SAGES, and NLSPATH.

       MANPATH	  A colon-separated list of directories; each directory can be followed by a comma-separated list of sections. If set,	its  value
		  overrides  /usr/share/man  as  the default directory search path, and the man.cf file as the default section search path. The -M
		  and -s flags, in turn, override these values.)

       PAGER	  A program to use for interactively delivering man's output to the screen. If not set, `more -s' is used. See more(1).

       TCAT	  The name of the program to use to display troffed manual pages.

       TROFF	  The name of the formatter to use when the -t flag is given. If not set, troff(1) is used.

EXAMPLES

       Example 1 Creating a PostScript Version of a man page

       The following example creates the pipe(2) man page in postscript for csh, tcsh, ksh and sh users:

	      % env TCAT=/usr/lib/lp/postscript/dpost man -t -s 2 pipe > pipe.ps

       This is an alternative to using man -t, which sends the man page to the default printer, if the user wants a postscript file version of the
       man page.

       Example 2 Creating a Text Version of a man page

       The following example creates the pipe(2) man page in ascii text:

	 man pipe.2 | col -x -b > pipe.text

       This  is  an alternative to using man -t, which sends the man page to the default printer, if the user wants a text file version of the man
       page.

EXIT STATUS

       The following exit values are returned:

       0     Successful completion.

       >0    An error occurred.

FILES

       /usr/share/man

	   Root of the standard manual page directory subtree

       /usr/share/man/man?/*

	   Unformatted nroff manual entries

       /usr/share/man/sman?/*

	   Unformatted SGML manual entries

       /usr/share/man/cat?/*

	   nroffed manual entries

       /usr/share/man/fmt?/*

	   troffed manual entries

       /usr/share/man/windex

	   Table of contents and keyword database

       /usr/share/lib/tmac/an

	   Standard -man macro package

       /usr/share/lib/sgml/locale/C/dtd/*

	   SGML document type definition files

       /usr/share/lib/sgml/locale/C/solbook/*

	   SGML style sheet and entity definitions directories

       /usr/share/lib/pub/eqnchar

	   Standard definitions for eqn and neqn

       man.cf

	   Default search order by section

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWdoc			   |
       +-----------------------------+-----------------------------+
       |CSI			     |Enabled, see NOTES.	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Committed 		   |
       +-----------------------------+-----------------------------+
       |Standard		     |See standards(5). 	   |
       +-----------------------------+-----------------------------+

SEE ALSO

       apropos(1),  cat(1),  col(1),  dpost(1),  eqn(1),  more(1),  nroff(1),  refer(1),  tbl(1),  troff(1),  vgrind(1),  whatis(1),   catman(1M),
       attributes(5), environ(5), eqnchar(5), man(5), sgml(5), standards(5)

NOTES

       The -f and -k options use the windex database, which is created by catman(1M).

       The  man  command is CSI-capable. However, some utilities invoked by the man command, namely, troff, eqn, neqn, refer, tbl, and vgrind, are
       not verified to be CSI-capable. Because of this, the man command with the -t option can not handle non-EUC data. Also, using the  man  com-
       mand to display man pages that require special processing through eqn, neqn, refer, tbl, or vgrind can not be CSI-capable.

BUGS

       The  manual  is	supposed  to  be reproducible either on a phototypesetter or on an ASCII terminal. However, on a terminal some information
       (indicated by font changes, for instance) is lost.

       Some dumb terminals cannot process the vertical motions produced by the e (see eqn(1)) preprocessing flag. To  prevent  garbled	output	on
       these  terminals, when you use e, also use t, to invoke col(1) implicitly. This workaround has the disadvantage of eliminating superscripts
       and subscripts, even on those terminals that can display them. Control-q clears a terminal that gets confused by eqn(1) output.

SunOS 5.11							    8 May 2008								    man(1)