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 convention-
ally 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 section of the manual. Since
these directories are optionally installed, they may not
reside on your host. You may 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 will store the preformatted version if cat*
or fmt* is writable. The windex database is not updated.
See catman(1M). If directories for the preformatted ver-
sions 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 MAN-
PATH 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 com-
ponents from each file, and then prints one-line sum-
maries containing the resulting basename or names.
This option also uses the windex database.
-F Forces man to search all directories specified by MAN-
PATH 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 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 key-
words. 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
overrides 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
environment 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 A keyword or the name of a standard utility.
USAGE
The usage of man is described below:
Manual Page Sections
Entries in the reference manuals are organized into sec-
tions. A section name consists of a major section name, typ-
ically a single digit, optionally followed by a subsection
name, typically one or more letters. An unadorned major sec-
tion 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 expla-
nation 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 vari-
able. If this variable is not set, /usr/share/man is
searched by default.
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 direc-
tory 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 com-
ments, 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 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 will automatically read 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 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 con-
tains 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.
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 attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWdoc |
|_____________________________|_____________________________|
| CSI | Enabled (see NOTES) |
|_____________________________|_____________________________|
| Interface Stability | Standard |
|_____________________________|_____________________________|
SEE ALSO
apropos(1), cat(1), col(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 may 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 may not be CSI-capable.
BUGS
The manual is supposed to be reproducible either on a photo-
typesetter 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 pro-
duced 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>
will clear a terminal that gets confused by eqn(1) output.
Man(1) output converted with
man2html