'\" t
.\" ** The above line should force tbl to be a preprocessor **
.\" Man page for man
.\"
.\" Copyright (C), 1994, 1995, Graeme W. Wilford. (Wilf.)
.\"
.\" You may distribute under the terms of the GNU General Public
.\" License as specified in the file COPYING that comes with the
.\" man_db distribution.
.\"
.\" Sat Oct 29 13:09:31 GMT 1994  Wilf. (G.Wilford@ee.surrey.ac.uk) 
.\" 
.TH man 1 "July 12th, 1995" "2.3.10" "Manual pager utils"
.SH NAME
man \- an interface to the on-line reference manuals
.SH SYNOPSIS
.\" The general command line
.B man 
.RB [\| \-c \||\| \-w \||\| \-tZT 
.IR device \|]
.RB [\| \-adhu7V \|]
.RB [\| \-m
.IR system \|[\|,.\|.\|.\|]\|]
.RB [\| \-L 
.IR locale \|]
.RB [\| \-p 
.IR string \|] 
.RB [\| \-M 
.IR path \|] 
.RB [\| \-P 
.IR pager \|] 
.RB [\| \-r
.IR prompt \|] 
.RB [\| \-S
.IR list \|] 
.RB [\| \-e
.IR extension \|] 
.RI [\|[\| section \|]
.IR page \ .\|.\|.\|]\ .\|.\|.
.\" The --local command line
.br
.B man 
.B \-l
.RB [\| \-7 \|]
.RB [\| \-tZT
.IR device \|]
.RB [\| \-p
.IR string \|]
.RB [\| \-P
.IR pager \|]
.RB [\| \-r
.IR prompt \|]
.I file
\&.\|.\|.
.\" The apropos command line
.br
.B man 
.B \-k
.RB [\| \-M
.IR path \|]
.I keyword
\&.\|.\|.
.\" The whatis command line
.br
.B man 
.B \-f
.RB [\| \-M
.IR path \|]
.I page
\&.\|.\|.
.SH DESCRIPTION
.B man
is the system's manual pager. Each
.I page
argument given to 
.B man
is normally the name of a program, utility or function. 
The 
.I manual page 
associated with each of these arguments is then found and
displayed. A 
.IR section ,
if provided, will direct
.B man
to look 
only in that
.I section
of the manual.
The default action is to search in all of the available 
.IR sections , 
following a pre-defined order and to show only the first 
.I page
found, even if 
.I page
exists in several
.IR sections .

The table below shows the
.I section
numbers of the manual followed by the types of pages they contain.

.TS
tab (@);
l l.
1@Executable programs or shell commands
2@System calls (functions provided by the kernel)
3@Library calls (functions within system libraries)
4@Special files (usually found in \fI/dev\fR)
5@File formats and conventions eg \fI/etc/passwd\fR
6@Games
7@Macro packages and conventions eg \fBman\fR(7), \fBgroff\fR(7).
8@System administration commands (usually only for root)
9@Kernel routines [\|Non standard\|]
n@new [\|obsolete\|]
l@local [\|obsolete\|]
p@public [\|obsolete\|]
o@old [\|obsolete\|]
.TE

A manual 
.I page 
consists of several parts. 

They may be labelled 
.BR NAME ,
.BR SYNOPSIS ,
.BR DESCRIPTION ,
.BR OPTIONS ,
.BR FILES ,
.BR SEE\ ALSO ,
.BR BUGS ,
and
.BR AUTHOR .

The following conventions apply to the 
.B SYNOPSIS
section and can be used as a guide in other sections.

.TS
tab (@);
l l.
\fBbold text\fR@type exactly as shown.
\fIitalic text\fR@replace with appropriate argument.
[\|\fB\-abc\fR\|]@any or all arguments within [ ] are optional.
\fB\-a\|\fR|\|\fB\-b\fR@options delimited by | cannot be used together.
\fIargument\fB .\|.\|.@\fIargument\fR is repeatable.
[\|\fIexpression\fR\|]\fB .\|.\|.@\fRentire \fIexpression\fR\ within [ ] is repeatable. 
.TE

The command or function illustration is a pattern that should match all 
possible invocations. In some cases it is advisable to illustrate 
several exclusive invocations as is shown in the 
.B SYNOPSIS
section of this manual page.
.SH EXAMPLES
.TP \w'man\ 'u
.BI man \ ls 
Display the manual page for the 
.I item
(program)
.IR ls .
.TP
.BI man\ \-a \ intro
Display, in succession, all of the available 
.I intro
manual pages contained within the manual. It is possible to quit between
successive displays or skip any of them.
.TP
\fBman \-t \fIalias \fR|\fI lpr -Pps
Format the manual page referenced by 
.RI ` alias ',
usually a shell manual page, into the default 
.B troff
or
.B groff
format and pipe it to the printer named 
.IR ps .
The default output for 
.B groff
is usually PostScript. 
.B man \-\-help
should advise as to which processor is bound to the 
.B \-t
option.  
.TP
.BI man\ \-l\ \-T dvi\ ./foo.1x.gz \ >\  ./foo.1x.dvi
This command will decompress and format the nroff source manual page
.I ./foo.1x.gz 
into a 
.B device independent (dvi)
file. The redirection is necessary as the
.B \-T
flag causes output to be directed to 
.B stdout
with no pager. The output could be viewed with a program such as 
.B xdvi 
or further processed into PostScript using a program such as 
.BR dvips.
.TP
.BI man\ \-k \ printf
Search the short descriptions and manual page names for the 
.I keyword 
.IR printf .
Print out any matches.
.TP
.BI man\ \-f \ smail
Lookup the manual pages referenced by 
.I smail
and print out the short descriptions of any found.
.SH OVERVIEW  
Many options are available to 
.B man
in order to give as much
flexibility as possible to the user. Changes can be made to the search 
path, section order, output processor, and other behaviours and operations 
detailed below.

If set, various environment variables are interrogated to determine 
the operation of 
.BR man . 
It is possible to set the `catch all' variable
.RB $ MANOPT
to any string in command line format with the exception that any spaces 
used as part of an option's argument must be escaped (preceded by a
backslash).
.B man 
will parse 
.RB $ MANOPT
prior to parsing
it's own command line. Those options requiring an argument,
will be overridden by the same options found on the command line.
To reset all of the options set in 
.RB $ MANOPT , 
.B \-D
can be specified as the initial command line option.
This will allow man to
`forget' about the options specified in
.RB $ MANOPT
although they must still have been valid.

The manual pager utilities packaged as 
.B man_db 
make extensive use of 
.B index
database caches. These caches contain information such
as where each manual page can be found on the filesystem and what its 
.I whatis
(short one line description of the man page) contains. One of 
.B man's
jobs is to ensure that the caches remain consistent.
These database caches obviate the need for having to manually run software 
to update traditional 
.I whatis
text databases, and also allow 
.B man 
to run faster than if it had to
search the filesystem each time to find the appropriate manual page.

If 
.B man
cannot find a
.B mandb
initiated 
.B index
database for a particular manual page hierarchy, it will still 
search for the requested manual pages although file globbing will be
necessary to search within that hierarchy.
If 
.B whatis
or
.B apropos
fails to find an 
.B index 
it will try to extract information from a
traditional 
.I whatis 
database instead.
.\"`User' manual page hierarchies will have 
.\".B index
.\"caches created `on the fly'.

These utilities support compressed source nroff files having, by default, the 
extensions of 
.BR .Z ", " .z " and " .gz .
It is possible to deal with any compression extension, but this information 
must be known at compile time. 
Also, by default, any cat pages produced are compressed using
.BR gzip .
Each `global' manual page hierarchy such as
.I /usr/man
or
.I /usr/X11R6/man
may have any directory as its cat page hierarchy. 
Traditionally the cat pages are
stored under the same hierarchy as the man pages, but for reasons such as
those specified in the 
.BR "Linux File System Standard (FSSTND)" ,
it may be better to store them elsewhere. 
For details on how to do this, please read
.BR manpath (5).
For details on why to do this, read the standard.

International support is available with this package. Native language
manual pages are accessible (if available on your system) via use of 
.I locale
functions.
To activate such support, it is necessary to set either
.RB $ LC_MESSAGES , 
.RB $ LANG
or another system dependent environment variable
to your language locale, usually specified in the 
.B POSIX 1003.1
based format:

.\"
.\" Need a \c to make sure we don't get a space where we don't want one
.\"
.RI < language >[\|\c
.B _\c 
.RI < territory >\|[\|\c
.B .\c
.RI < character-set >\|[\|\c
.B ,\c
.RI < version >\|]\|]\|]

If the desired page is available in your 
.IR locale,
it will be displayed in lieu of the standard (usually American English)
page. 

Support for international message catalogues is also featured in this
package and can be activated in the same way, again if available. 
If you find that the manual pages and message catalogues supplied with this
package are not available in your native language and you would like to 
supply them, please contact the author who will be coordinating such
activity.

For information regarding other features and extensions available with this 
manual pager, please read the documents supplied with the package.
.SH DEFAULTS
.B man
will search for the desired manual pages within the
.I index
database caches. If the `lookup' is unsuccessful, a cache consistency check
is performed to ensure the databases accurately reflect the filesystem. It
is not generally necessary to run 
.B mandb
after the caches are initially created, unless a cache becomes corrupt.

Once a manual page has been located, a check is performed to find out if a
relative preformatted `cat' file already exists and is newer than the nroff 
file. If it does and is, this preformatted file is (usually) decompressed 
and then displayed, via use of a pager. The pager can be specified in a 
number of ways or the default is used (see option
.B \-P
for details).
If no cat is found or is older than the nroff file, the nroff is filtered
through various programs and is shown immediately.

If a cat file can be produced (a relative cat directory exists and has
appropriate permissions), 
.B man
will compress and store the cat file in the background. 

The filters are deciphered by a number of means. Firstly, the command
line option
.B \-p
or the environment variable 
.RB $ MANROFFSEQ
is interrogated. If 
.B \-p 
was not used and the environment variable was not set, the initial line of
the nroff file is parsed for a preprocessor string. To contain a valid
preprocessor string, the first line must resemble

.B '\e" 
.RB < string >  

where 
.B string 
can be any combination of letters described by option
.B \-p
below.

If none of the above methods provide any filter information, a default set
is used. 

A formatting pipeline is formed from the filters and the primary
formatter
.RB ( nroff 
or 
.RB [ tg ] roff 
with 
.BR \-t )
and executed.
Alternatively, if an executable program 
.I mandb_nfmt 
(or 
.I mandb_tfmt
with 
.BR \-t ) 
exists in the man tree root, it is executed instead.  It
gets passed the manual source file, the preprocessor string, and
optionally the device specified with 
.B \-T 
as arguments.
.\" ********************************************************************
.SH OPTIONS
Non argument options that are duplicated either on the command line, in 
.RB $ MANOPT ,
or both, are not harmful. For options that require an 
argument, each duplication will override the previous argument value.
.TP
.B \-l, \-\-local-file
Activate `local' mode. Format and display local manual files instead of 
searching through the system's manual collection.
Each manual page argument will be interpreted as an nroff source file in the
correct format. 
.\" Compressed nroff source files with a supported compression.
.\" extension will be decompressed by man prior to being displaying via the
.\" usual filters. 
No cat 
file is produced. If '\-' is listed as one of the arguments, input will be
taken from stdin.
.TP
.BI \-L\  locale ,\ \-\-locale= locale
.B man
will normally determine your current locale by a call to the C function
.BR setlocale (3)
which interrogates various environment variables, possibly including
.RB $ LC_MESSAGES
and
.RB $ LANG .
To temporarily override the determined value, use this option to supply a 
.I locale
string directly to 
.BR man . 
Note that it will not take effect until the search for pages actually
begins.
Output such as the help message will always be displayed in the initially
determined locale.
.TP
.B \-D, \-\-default
This option is normally issued as the very first option and resets 
.B man's
behaviour to it's default. It's use is to reset those options that may have
been set in
.RB $ MANOPT .
Any options that follow
.B \-D
will have their usual effect.
.TP
.BI \-M\  path ,\ \-\-manpath= path
Specify an alternate manpath to use. By default, 
.B man 
uses
.B manpath
derived code to determine the path to search. This option overrides the
.RB $ MANPATH
environment variable and causes option
.B \-m
to be ignored. 
.TP
.BI \-P\  pager ,\ \-\-pager= pager
Specify which output pager to use.  By default, 
.B man 
uses
.BR "less -s" .
This option overrides the
.RB $ PAGER
environment variable and is not used in conjunction with 
.B \-f
or 
.BR \-k .
.TP
.BI \-r\  prompt ,\ \-\-prompt= prompt
If a recent version of 
.B less
is used as the pager, 
.B man
will attempt to set it's prompt
and some sensible options.
The default prompt looks like 

.B \ Manual page\c
.IB \ name ( sec )\c 
.BI \ line \ x

where 
.I name 
denotes the manual page name,
.I sec
denotes the section it was found under
and
.IR x ,
the current line number. 
.\"The default options are
.\".BR \-six8 .
This is achieved by using the
.RB $ LESS
environment variable. 
.\"The actual default will depend on your chosen 
.\".BR locale .  

Supplying 
.B \-r
with a string will override this default. 
.\"You may need to do this if your
.\"version of 
.\".B less
.\"rejects the default options or if you prefer a different prompt.
The string may contain the text
.B $MAN_PN
which will be expanded to the name of the current manual page and it's
section name encompassed by `(' and `)'. The string used to produce the
default could be expressed as

.B \e\ Manual\e\ page\e\ \e$MAN_PN\e\ ?ltline\e\ %lt?L/%L.:
.br
.B byte\e\ %bB?s/%s..?\e\ (END):?pB\ %pB\e\e%..

It is broken into two lines here for the sake of readability only. 
For it's meaning see the 
.BR less (1)
manual page. The prompt string is first evaluated by
the shell.
All double quotes, back-quotes and
backslashes in the prompt must be escaped by a preceding backslash. The
prompt string may end in an escaped $ which may be followed by further
options for less. By default
.B man
sets the 
.B \-ix8 
options.
.TP
.B \-7, \-\-ascii
When viewing a pure 
.IR ascii (7) 
manual page on a 7 bit terminal or terminal
emulator, some characters may not display correctly when using the 
.IR latin1 (7)
device description with 
.B GNU 
.BR nroff . 
This option allows pure 
.I ascii 
manual pages to
be displayed in 
.I ascii 
with the 
.I latin1 
device. It will not translate any
.I latin1 
text. The following table shows the translations performed. 

.TS
tab (@);
l c c c.
Description@Octal@latin1@ascii
_
continuation hyphen@255@\[char173]@-
bullet (middle dot)@267@\(bu@o
acute accent@264@\(aa@'
multiplication sign@327@\(mu@x
.TE

If the 
.I latin1
column displays correctly, your terminal may be set up for 
.I latin1
characters and this option is not necessary. 
If the 
.I latin1
and 
.I ascii 
columns are identical, you are reading this page 
using this option or 
.B man 
did not format this page using the 
.I latin1
device description.
If the
.I latin1 
column is missing or corrupt, 
you may need to view manual pages with this option.

This option is ignored when using options
.BR \-t , 
.B \-T
or
.B \-Z
and may be useless for 
.B nroff
other than 
.BR GNU's .
.TP
.BI \-S\  list ,\ \-\-sections= list
List is a colon separated list of `order specific' manual sections to search.
This option overrides the
.RB $ MANSECT
environment variable.
.TP
.B \-a, \-\-all
By default, 
.B man 
will exit after displaying the most suitable manual page it
finds. Using this option forces 
.B man 
to display all the manual pages with 
names that match the search criteria.  
.TP 
.B \-c, \-\-catman
This option is not for general use and should only be used by the 
.B catman
program.
.TP
.B \-d, \-\-debug
Don't actually display any manual pages, but do print lots of debugging
information.
.TP
.BI \-e\  sub-extension ,\ \-\-extension= sub-extension
Some systems incorporate large packages of manual pages, such as those that
accompany the
.B Tcl
package, into the main manual page hierarchy. To get around the problem of
having two manual pages with the same name such as
.BR exit (3),
the 
.B Tcl 
pages were usually all assigned to section
.BR l .
As this is unfortunate, it is now possible to put the pages in the correct
section, and to assign a specific `extension' to them, in this case,
.BR exit (3tcl).
Under normal operation,
.B man
will display 
.BR exit (3)
in preference to 
.BR exit (3tcl).
To negotiate this situation and to avoid having to know which section the page
you require resides in, it is now possible to give 
.B man 
a 
.l sub-extension
string indicating which package the page must belong to. Using the above
example, supplying
the option
.B \-e\ tcl
to
.B man
will restrict the search to pages having an extension of 
.BR *tcl .
.TP
.B \-f, \-\-whatis
Equivalent to
.BR whatis .
Display a short description from the manual page, if available. See
.BR whatis (1)
for details. 
.TP
.B \-h, \-\-help
Print a help message and exit.
.TP
.B \-k, \-\-apropos
Equivalent to
.BR apropos .
Search the short manual page descriptions for keywords and display any
matches. See 
.BR apropos (1)
for details. 
.\"
.\" Due to the rather silly limit of 6 args per request in some `native'
.\" *roff compilers, we have do the following to get the two-line
.\" hanging tag on one line. .PP to begin a new paragraph, then the 
.\" tag, then .RS (start relative indent), the text, finally .RE 
.\" (end relative indent).
.\"
.PP
.B \-m 
.I system\c 
.RB \|[\|,.\|.\|.\|]\| ,
.BI \-\-systems= system\c 
\|[\|,.\|.\|.\|]
.RS
If this system has access to other operating system's manual pages, they can
be accessed using this option.
To search for a manual page from NewOS's manual page collection,
use the option
.B \-m
.BR NewOS .

The
.I system
specified can be a combination of comma delimited operating
system names.
To include a search of the native operating system's
manual pages, include the system name
.B man
in the argument string.
This option will override the
.RB $ SYSTEM
environment variable.
.RE
.TP
.BI \-p\  string ,\ \-\-preprocessor= string
Specify the sequence of preprocessors to run before 
.B nroff 
or 
.BR troff / groff .
Not all installations will have a full set of preprocessors.
Some of the preprocessors and the letters used to designate them are: 
.BR eqn " (" e ), 
.BR grap " (" g ),  
.BR pic " (" p ),
.BR tbl " (" t ),
.BR vgrind " (" v ),
.BR refer " (" r ).
This option overrides the
.RB $ MANROFFSEQ
environment variable.
.B zsoelim
is always run as the very first preprocessor.
.TP
.B \-u, \-\-update
The 
.B index
database caches are updated `on the fly', that is, they do not require 
.B mandb
to be run periodically to be kept consistent. If your chosen manual page is
not located within the cache or the 
.B \-a
option is used, 
.B man
will do a `directory level' consistency check to ensure that it's caches 
are an accurate representation of the filesystem. 
To force an `inode level' consistency check prior to
finding any manual pages, use option
.BR \-u .
.TP
.B \-t, \-\-troff
Use
.I "/usr/bin/groff -mandoc" 
to format the manual page to stdout.
This option is not required in conjunction with either
.B \-T
or
.BR \-Z .
.PP
.BI \-T\  device ,\ \-\-troff-device 
.RI [\| =device \|]
.RS
This option is used
to change
.B groff 
(or possibly 
.BR troff's ) 
output to be suitable for a device 
other than the default.
It implies 
.BR \-t .
Examples (provided with Groff-1.09) include 
.BR dvi ", " latin1 , 
.BR X75 " and " X100 .
.RE
.TP
.B \-Z, \-\-ditroff
.B groff 
will run 
.B troff 
and then use an appropriate post-processor to produce output suitable for
the chosen device. If 
.I "/usr/bin/groff -mandoc" 
is 
.BR groff , 
this option is passed to
.B groff 
and will suppress the use of a post-processor.
It implies
.BR \-t .
.TP
.B \-w, \-\-where, \-\-location
Don't actually display the manual pages, but do print the location(s) of
the files that would be formatted or displayed. If the file is a cat
file, also show the location of its source nroff file.
.TP
.B \-V, \-\-version
Display version and author information.
.SH "EXIT STATUS"
.TP
.B 0
Successful program execution.
.TP
.B 1
Usage, syntax or configuration file error.
.TP
.B 2
Operational error.
.TP
.B 3
A child process returned a non-zero exit status.
.TP
.B 16
At least one of the pages/files/keywords didn't exist or wasn't
matched.
.SH ENVIRONMENT
.\".TP \w'MANROFFSEQ\ \ 'u
.TP
.B MANPATH
If
.RB $ MANPATH
is set, its value is used as the path to search for manual pages.
.TP
.B MANROFFSEQ
If
.RB $ MANROFFSEQ
is set, its value is used to determine the set of preprocessors to pass
each manual page through.
The default preprocessor list is system dependent.
.TP
.B MANSECT
If
.RB $ MANSECT
is set, its value is a colon delimited list of sections and it is used to 
determine which manual sections to search and in what order.
.TP
.B PAGER
If
.RB $ PAGER
is set, its value is used as the name of the program used to display
the manual page. By default,
.B "less -s"
is used.
.TP 
.B SYSTEM
If
.RB $ SYSTEM
is set, it will have the same effect as option
.B \-m "string"
where string will be taken as 
.RB $ SYSTEM 's 
contents.
.TP 
.B MANOPT
If 
.RB $ MANOPT
is set, it will be parsed prior to 
.B man's
command line and is expected to be in a similar format. As all of the
other 
.B man
specific environment variables can be expressed as command line options, and
are thus candidates for being included in 
.RB $ MANOPT
it is expected that they will become obsolete.
N.B. All spaces that should be interpreted as part of an option's argument 
must be escaped.
.TP
.BR LANG , " LC_MESSAGES"
Depending on system and implementation, either or both of
.RB $ LANG
and
.RB $ LC_MESSAGES
will be interrogated for the current message locale. 
.B man
will display it's messages in that locale (if available). See 
.BR setlocale (3)
for precise details.
.SH FILES
.TP
.I /usr/local/etc/man_db.config
man_db configuration file.
.TP
.I /usr/man
A global manual page hierarchy.
.TP
.I /usr/man/index.(bt|db|dir|pag)
A traditional global
.I index
database cache.
.TP
.I /var/catman/index.(bt|db|dir|pag)
An alternate or FSSTND 
compliant global 
.I index 
database cache.
.TP
.I /usr/man/mandb_nfmt
Example of an optional per-hierarchy 
.B nroff 
based formatter script.
.TP
.I /usr/man/mandb_tfmt
Example of an optional per-hierarchy
.RB [ tg ] roff
based formatter script used with 
.BR \-t .
.SH "SEE ALSO"
.BR mandb (8), 
.BR manpath (1),
.BR manpath (5),
.BR apropos (1), 
.BR whatis (1),
.BR catman (8), 
.BR less (1),
.BR nroff (1),
.BR troff (1),
.BR groff (1), 
.BR zsoelim (1), 
.BR setlocale (3),
.BR ascii (7),
.BR latin1 (7),
.BR FSSTND .
.SH HISTORY
1990, 1991 \- Originally written by John W. Eaton (jwe@che.utexas.edu).

Dec 23 1992: Rik Faith (faith@cs.unc.edu) applied bug fixes 
supplied by Willem Kasdorp (wkasdo@nikhefk.nikef.nl).

April 30th, 1994 - July 12th, 1995: Wilf. 
(G.Wilford@ee.surrey.ac.uk) has been developing and maintaining this package
with the help of a few dedicated people.