MAN(1) Commands and Applications MAN(1)
NAME
man - display reference manual pages; find reference pages by keyword
SYNOPSIS
man [-] [-t] [-M path] [-T macro-package] [section] title
man [-M path] -k keyword ...
man [-M path] -f filename ...
DESCRIPTION
This manual page documents man version 3.0.
man displays information from the reference manuals. It can display
complete manual pages that you select by title, or one-line summaries
selected either by keyword (-k), or by the name of an associated file
(-f).
A section, when given, applies to the title that follows it on the com‐
mand line. man looks in the indicated section of the manual for that
title. section is either a digit (perhaps followed by a single letter
indicating the type of manual page), or one of the words new, local,
old, or public. The abbreviations n, l, o and p are also allowed. If
section is omitted, man searches all reference sections (giving prefer‐
ence to commands over functions). If more than one manual page exists
for the specified title, each page is displayed in the order in which
it is found. The user is given the option of exiting after each page
is displayed. If no manual page is located, man prints an error mes‐
sage.
The reference page sources are typically located in the /usr/man/man?
directories. If there are preformatted, up-to-date versions in corre‐
sponding cat? or fmt? directories, man simply displays or prints
those versions. If the preformatted version of interest is out of date
or missing, man reformats it prior to display. If directories for the
preformatted versions are not provided, man 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(1V). Otherwise, man pipes its output
through more(1) to handle paging and underlining on the screen.
OPTIONS
-t man arranges for the specified manual pages to be troffed to a
suitable raster output device (see troff(1) or vtroff(1)). If
both the - and -t flags are given, man updates the troffed ver‐
sions of each named title (if necessary), but does not display
them.
-M path
Change the search path for manual pages. path is a colon- or
space-separated list of directories that contain manual page di‐
rectory subtrees. For example, /usr/man/u_man:/usr/man/a_man
makes man search in the standard System V locations. The space
delimiter is provided for compatibility with GS/OS's use of the
colon as a pathname component delimiter. If the search path
contains no spaces nor / characters (such as :usr:local:man), it
is assumed to be a single path, not a list of paths. If spaces
are used as delimiters, remember to quote path from the shell.
Each directory in the path is assumed to contain subdirectories
of the form man[1-8l-p].
-T macro-package
man uses macro-package rather than the standard -man macros de‐
fined in /usr/lib/tmac/tmac.an for formatting manual pages.
-k keyword ...
man prints out one-line summaries from the whatis database (ta‐
ble of contents) that contain any of the given keywords. The
whatis database is created using the makewhatis(8) command.
-f filename ...
man attempts to locate manual pages related to any of the given
filenames. It strips the leading pathname components from each
filename, and then prints one-line summaries containing the re‐
sulting basename or names. This option also uses the whatis
database.
MANUAL PAGES
Manual pages are either nroff(1)/troff(1) source files prepared with
the -man macro package, or aroff(1) source files prepared with Apple
works GS (tm) or a compatible word processor.
Referring to Other Manual Pages
Other manual pages can be referenced in one of two ways, depending on
whether the target manual page is an aroff or nroff source file.
For aroff source files, a "link" may be made by creating a file ending
in .l (that's a dot-ell). The file must contain a single line consist‐
ing of the pathname of the target aroff source file. An intentional
design limitation was made that disallows this form of "link" in the
manl (that's man-ell) subdirectory.
For nroff source files, a "link" may be made by creating a file con‐
taining the nroff source (.so) command. This file should have the same
suffix as the target nroff source file. man does not itself do any
processing of the source command.
With both types of "links" the pathname may be either a full- or par‐
tial-pathname. In the latter case, the pathname must be relative to
the root of the manual page directory subtree.
man processes the indicated file in place of the current one. The ref‐
erence must be expressed as a pathname relative to the root of the man‐
ual page directory subtree.
Preprocessing Manual Pages
If the first line is a string of the form:
'\" X
where X is separated from the `"' by a single SPACE and consists of any
combination of characters in the following list, man pipes its input to
troff(1) or nroff(1) through the corresponding preprocessors.
e eqn(1), or neqn for nroff
r refer(1)
t tbl(1)
v vgrind(1)
If eqn or neqn is invoked, it will automatically read the file
/usr/pub/eqnchar (see eqnchar(7)). If nroff(1) is invoked, col(1V) is
automatically used.
COMPRESSED MANUAL PAGES
man allows its manual pages to be compressed by either compress,
freeze, or gzip, in which case the manual page must have the suffix .Z,
.F, or .gz, respectively. Note that the test for these suffixes is
case sensitive and if the incorrect case is used then the compressed
file will be passed to nroff with unpredictable results.
Compression may be used on files in either (or both) of the man? and
cat? subdirectories. Do not compress aroff(1) source files since com‐
pressed files in the man? subdirectory are always assumed to be
nroff(1) source.
ENVIRONMENT
MANPATH
If set, its value overrides /usr/man as the default search path.
(The -M flag, in turn, overrides this value.) See the descrip‐
tion of the -M flag for syntax details.
USRMAN If MANPATH is not set, then the value of USRMAN (if set) over‐
rides /usr/man as the default search path. (The -M flag, in
turn, overrides this value.) See the description of the -M flag
for syntax details.
MANDIR If neither MANPATH nor USRMAN is set, then the value of MANDIR
(if set) overrides /usr/man as the default search path. (The -M
flag, in turn, overrides this value.) See the description of
the -M flag for syntax details.
PAGER A program to use for interactively delivering man's output to
the screen. If not set, `/bin/more' (see more(1)) is used.
TCAT The name of the program to use to display troffed manual pages.
If not set, `lpr -t' (see lpr(1)) is used.
TROFF The name of the formatter to use when the -t flag is given. If
not set, `troff -t' is used.
FILES
/usr/[share]/man
root of the standard manual page directory subtree
/usr/[share]/man/man?/*
unformatted manual entries
/usr/[share]/man/cat?/*
nroffed manual entries
/usr/[share]/man/fmt?/*
troffed manual entries
/usr/[share]/man/whatis
table of contents and keyword database
/usr/[share]/lib/tmac/tmac.an
standard -man macro package
/usr/pub/eqnchar
SEE ALSO
apropos(1), aroff(1), cat(1V), col(1V), compress(1), eqn(1), freeze(1),
gzip(1), less(1), lpr(1), more(1), nroff(1), refer(1), tbl(1),
troff(1), vgrind(1), vtroff(1), whatis(1), whereis(1), eqnchar(7),
man(7), catman(8)
NOTES
Because troff is not 8-bit clean, man has not been made 8-bit clean.
The -f and -k options use the whatis database, which is created by
makewhatis(8).
Although this version of man allows USRMAN and MANDIR to be each a
colon- or space-separated list of pathnames, other versions of man
treat the values of these environment variables as a single pathname.
For compatibility reasons, the use of these two environment variables
is discouraged; use MANPATH instead.
BUGS
The manual is supposed to be reproducible either on a phototypesetter
or on an ASCII terminal. However, on a terminal some information (in‐
dicated by font changes, for instance) is necessarily lost.
Some dumb terminals cannot process the vertical motions produced by the
e (eqn(1)) preprocessing flag. To prevent garbled output on these ter‐
minals, when you use e also use t, to invoke col(1V) implicitly. This
workaround has the disadvantage of eliminating superscripts and sub‐
scripts — even on those terminals that can display them. CTRL-Q will
clear a terminal that gets confused by eqn(1) output.
The code which calls the eqn(1), refer(1), tbl(1), and vgrind(1) pre‐
processors is not yet implemented. Since these preprocessors do not as
yet exist for GNO, this is not too much of a problem.
Please report any other bugs to Devin Reade, <gdr@trenco.gno.org>.
HISTORY
The GNO version of man first appeared in GNO version 1.0 and was writ‐
ten by Mike Horwath. This version was rewritten from scratch by Devin
Reade.
GNO 28 March 1998 MAN(1)
Man(1) output converted with
man2html