man -- display online reference pages

man display online reference pages	Command

SYNOPSIS

man [-wx] [-M path] [type] entry ...

man [-wx] [-T txt_indexes] [type] entry ...

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

DESCRIPTION

The man command either displays online reference pages or searches for reference pages that have specified keywords associated with them.

Normally, man displays the reference page for each specified entry. To display only a reference page of a given type, specify type on the command line. type is a number representing which type of reference pages to search. Reference pages come in the following types:

1	Commands and Utilities
3	Functions
4	File Formats
5	Miscellaneous

When output is sent to the terminal, man invokes a pager command to filter and display the reference pages. If MANPAGER is defined, it is used. If not, and if PAGER is defined, it is used. If neither is defined, man defaults to using the command more -A -s.

Options

-k: searches a precomputed database of synopsis lines for information on keywords.
-M path: searches the directories indicated by path for reference pages. If -M is not specified, man uses the path specified in the MANPATH environment variable if it is set; otherwise man searches /etc. All reference pages are found by searching similarly structured file trees rooted at one or more places. See the FILES section for a description of the files and directories man should find in each directory that it searches.
-T filelist: specifies a list of .idx files to search before searching the files listed in MAN_TXT_INDEX when looking for a text version of a reference page.
-w: displays only the file name of the file containing the specified entry.
-x: displays the files that man is searching as it tries to find the entry.

Search Rules

To find a given entry, man follows a set of search rules. When you specify a type, man searches for the appropriate page amongst pages of that type; otherwise, man looks for the first page named entry regardless of the type.

man takes the following steps to find the entry. Once a step results in finding the entry, man displays the reference page and exits.

man searches the .idx files listed in the MAN_TXT_INDEX environment variable for an entry matching the request entry which indicates the text (.txt) reference page to display.
man checks each directory in MANPATH for a file named man.dbz. If it exists, man looks for the requested entry in its index (see man.dbz File Format).
For each possible type (that is, type if you specified it, or all types in order from 1 through 9, then 0 if you did not):
- man checks each directory in MANPATH for a file named catn/entry.n[l] where n is the type number, and l is the optional letter code. If it exists, man checks to see if it was compressed with pack or compress, and uncompresses it (calling pcat if the file was packed).
- man checks each directory in MANPATH for a file named mann/entry.n[l].

man.dbz File Format

Sometimes, the reference pages are kept in a single large file, called man.dbz. The file starts with a magic text string:

!<man database compressed>\n

and continues with the index:

14 bytes formatted reference page name
9 bytes seek pointer
9 bytes length

The name is simply the page name, followed by a dot and the type number. For example, this reference page would be named man.1. When man finds a matching entry, it seeks to the point in the file specified by the given seek pointer, and uncompresses for length bytes. Each reference page is compressed separately.

EXAMPLES

To find the utilities that do comparisons, type:

man -k compar

ENVIRONMENT VARIABLES

MAN_TXT_INDEX: contains a semicolon separated list of .idx files to search for entry when the -h is not specified.
MANPATH: contains a semicolon separated list of paths to search for reference pages.
MANPAGER, PAGER: contains an output filtering command for use when displaying reference pages on a terminal.
TMPDIR: identifies the directory where temporary files reside.

FILES

/etc: is the default directory for the online reference pages. The rest of the files listed here reside in this directory.
cat[0-9]/*.[0-9]: pre-formatted reference pages in normal, compressed, or packed form.
man[0-9]/*.[0-9]: unformatted reference pages.
whatis: is a database used by -k option.
*.idx: index files that man how to find HTML Help and text versions of individual reference files. The .idx files to search are indicated by the MAN_TXT_INDEX environment variable.
man.dbz: is a master file containing all reference pages.

DIAGNOSTICS

Possible exit status values are:

0

Successful completion.

1

Failure due to any of the following:

— unknown command line option

— missing path after an -M option

— no information available on the desired subject

— unable to create a child process to format reference page

— child process returned with non-zero exit status

PORTABILITY

POSIX.2. x/OPEN Portability Guide 4.0.

The -M, -T, -w, and -x options, the MANPAGER, and MAN_TXT_INDEX environment variables, the default pager, the ability to specify type on the command line, and the ability to display reference pages in HTML Help format are all extensions to the POSIX and XPG standards.