MAN(1)

NAME
man - find manual information by keywords; print out the manual

SYNOPSIS
man [ - ] [ -q ] [ -r ] [ -M path ] [ section ] title ...
man -k keyword ...
man -f file ...

DESCRIPTION
Man is a program which gives information from the programmers manual. It can be asked for one line descriptions of commands specified by name, or for all commands whose description contains any of a set of keywords. It can also provide on-line access to the sections of the printed manual.

When given the option -k and a set of keywords, man prints out a one line synopsis of each manual section whose listing in the table of contents contains one of those keywords.

When given the option -f and a list of file names, man attempts to locate manual sections related to those files, printing out the table of contents lines for those sections.

When neither -k nor -f is specified, man formats a specified set of manual pages. If a section specifier is given man looks in that section of the manual for the given titles. Section is either an Arabic section number (3 for instance), or one of the words “new,” “local,” “old,” or “public.” A section number may be followed by a single letter classifier (for instance, 1g, indicating a graphics program in section 1). If section is omitted, man searches all sections of the manual, giving preference to commands over subroutines in system libraries, and printing the first section it finds, if any.

Normally, when man formats a manual page, it filters the input through the text preprocessors tbl(1) and neqn(1). The -q option can be used to suppress this behaviour, and pass the input directly to nroff(1).

If the standard output is a teletype man pipes its output through more(1) with the option -s to crush out useless blank lines and to stop after each page on the screen. Hit a space to continue, a control-D to scroll 11 more lines when the output stops.

If the standard output is not a teletype, or the - flag is given, man pipes its output through cat(1). If - is specified the -s option is used to remove consecutive blank lines.

Normally man checks in a standard location for manual information (/usr/share/man). This can be changed by supplying a search path (like the sh(1) command search path) with the -M flag. The search path is a colon (“:”) separated list of directories in which manual subdirectories may be found; e.g. “/usr/local:/usr/share/man” If the environment variable “MANPATH” is set, its value is used for the default path. If a search path is supplied with the -k or -f options, it must be specified first.

Man will look for the manual page in one of three forms: the nroff source, preformatted pages, or a man archive generated by arcat(8). If any version is available, the manual page will be displayed. If the preformatted version is available, and it has a more recent modify time than the nroff source, it will be promptly displayed. Otherwise, the manual page will be formatted with nroff and displayed. If neither preformatted nor nroff source versions are available and there is an entry in the archive this will be used. If the user has permission, the formatted manual page will be deposited in the proper place, so that later invocations of man will not need to format the page again.

Any file on the current search path of the form filename.A is assumed to be a man archive. Note that filename.pag and filename.dir also form part of the archive.

Normally each manual page should have either an nroff source version or an archive entry - there is no point having both, the archive entry will simply be ignored.

The man pages archive and the preformatted versions of the man pages contain vt100 escape sequences - if they are displayed on a terminal (or by a program) which expects different escapes, the results are unpredictable. This can be avoided by using the -r option which forces man to only use the nroff source, and to re-format the manual page for the current terminal type given by the “TERM” environment variable.

FILES
/usr/share/man	standard manual area
/usr/share/man/man?/*	directories containing source for manuals
/usr/share/man/cat?/*	directories containing preformatted pages
/usr/share/man/*.A man	page archive and contents list
/usr/share/man/whatis	keyword database

SEE ALSO
apropos(1), more(1), whereis(1), catman(8), arcat(8)

BUGS
The manual is supposed to be reproducible either on the phototypesetter or on a typewriter. However, on a typewriter some information is necessarily lost.