man(1) User Commands man(1)NAMEman - find and display reference manual pages
SYNOPSISman [-] [-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 associ‐
ated file (-f). If no manual page is located, man prints an error mes‐
sage.
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 cat‐
man(1M). If directories for the preformatted versions are not provided,
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 database. This option is useful if
the database is not up to date and it has been made
the default behavior of the man command. The option
therefore does not have to be invoked and is docu‐
mented here for reference only.
-k keyword ... Prints out one-line summaries from the windex data‐
base (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 directo‐
ries 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 subdi‐
rectories of the form man* or sman* , one for each
section. This option overrides the MANPATH environ‐
ment 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 numer‐
ical digit, perhaps followed by one or more letters
to match the desired section of the manual, for
example, "3lib". 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 environment variable and the man.cf
file. See Search Path below for an explanation of
how man conducts its search.
-tman 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 let‐
ters. 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 ref‐
erence 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 sec‐
tions 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 man‐
ual pages are processed by an SGML parser and passed to the formatter.
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
automatically 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 ref‐
erence 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_MESSAGES,
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 │text/doctools │
├─────────────────────────────┼─────────────────────────────┤
│CSI │Enabled, see NOTES. │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Committed │
├─────────────────────────────┼─────────────────────────────┤
│Standard │See standards(5). │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOapropos(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 cat‐
man(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 command 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 (indi‐
cated 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)
