Tribblix: 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