illumos: manual page: man.1

MAN(1) User Commands MAN(1)

NAME

man - find and display reference manual pages

SYNOPSIS

man [-] [-adFlrt] [-T macro-package] [-M path] [-s section] name ...
man [-M path] [-s section] -k keyword ...
man [-M path] [-s section] -f file ...
man [-M path] -w

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 man(7), or mdoc(7)
language tags. The man command recognizes the type of markup and processes
the file accordingly.

Location of Manual Pages

The online Reference Manual page directories are conventionally located in
/usr/share/man. Each directory corresponds to a section 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. The man command reformats a page whenever it is requested.

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 a
pager such as 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 ...
Attempts to locate manual pages related to any of the given file
names. 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 whatis database.

-F This option is present for backwards compatibility and is
documented here for reference only. It performs no function.

-k keyword ...
Prints out one-line summaries from the whatis database (table of
contents) that contain any of the given keyword. The whatis
database is created using the -w option.

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

-M path
Specifies an alternate search path for manual pages. The 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,
-f, or -w options, the -M option must appear first. Each directory
in the path is assumed to contain subdirectories of the form man*,
one for each section. This option overrides the MANPATH
environment variable.

-r Reformats the manual page, checking for formatting errors, but does
not display it.

-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, 3head. 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 Arranges for the specified manual pages to be sent to the default
printer as PostScript.

-T macro-package
This option is present for backwards compatibility and is
documented here for reference only. It performs no function.

-w Updates the whatis database.

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. It 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.

Referring to Other Manual Pages
If the first line of the 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.

ENVIRONMENT VARIABLES

See environ(7) 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.

MANWIDTH Width of the output. If set to the special value "TTY" (or
"tty"), and output is to terminal, auto-detect terminal width.

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

FILES

/usr/share/man
Root of the standard manual page directory subtree

/usr/share/man/man?/*
Unformatted manual entries

/usr/share/man/whatis
Table of contents and keyword database

man.cf Default search order by section

EXIT STATUS

The man utility exits 0 on success, and >0 if an error occurs.

EXAMPLES

Example 1: Creating a PostScript Version of a man page
The following example spools the pipe(2) man page in PostScript to the
default printer:

% man -t -s 2 pipe

Note that mandoc(1) can be used to obtain the PostScript content directly.

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

CODE SET INDEPENDENCE

Enabled.

INTERFACE STABILITY

Committed.

NOTES

The -f and -k options use the whatis database, which is created with the -w
option.

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.

illumos May 13, 2017 illumos