MAN
Section: User Commands (1)
Index
Return to Main Contents
NAME
man, apropos, whatis - display on-line reference manual information
SYNOPSIS
man
[
-ltfikwuvthaAdgK
]
[
-M
manpath
]
[
-Ssections
]
[
-Ttroffproc
]
[
hwtype
]
[
section
]
topic[/index]
...
apropos
[
-uvdDK
]
[
-M
manpath
]
[
hwtype
]
keyword
whatis
[
-uvdhD
]
[
-M
manpath
]
[
hwtype
]
topic
...
DESCRIPTION
The
man
program (and its links,
apropos
and
whatis) formats and displays information from the on-line Programmer's
Reference Manual. It can display complete entries selected
by topic or brief one-line summaries selected by keyword
(as
apropos
or with the
-k
or
-K
flags) or by topic
(as
whatis
or with
the
-f
flag).
When invoked in the simplest way, without any options and with a topic,
it displays
the corresponding manual page formatted with
If the
standard output is to a terminal,
the man page is piped by default through
or else through
the program specified in the user's
PAGER
environment variable if set.
Man pages are stored on-line as
nroff
source files and are reformatted
whenever the formatted
version is missing or has a newer modification date than the unformatted version.
The formatted version of the man page stored in
the corresponding
cat*/
directory if it exists
and is writable by the current user.
Thus
man1/stty.1
once formatted
is stored in
cat1/stty.1.
Otherwise manual pages must be reformatted each time a user wishes
to view them.
If the root of the man tree from which the man page is taken contains
the file
tmac.an, then this file is used in lieu of the
standard
macros to reformat the page. Appropriate calls to
and either
or
are automatically
inserted as needed.
Section Selection
Some topics occur in more than one section of the manual.
To select a man page from a particular section, put the section name
in front of the topic, as in
``man 4 tty
''
.
For backwards compatibility with other
man
programs, certain
non-numeric sections are recognized by longer aliases:
local
means section
l,
new
means section
n,
public
means section
p, and
old
means section
o.
In other words,
``man new csh
''
on the command line will search for a man page on the
csh
in section
n
of the manual.
The applicable topics for each component in the current
MANPATH
are sorted according to their section.
The default ordering is
ln16823457po. Thus,
would be displayed before
This ordering can be
overridden on a site-wide basis by the system manager (see
NOTES
section below), a per-user basis using the
MANSECT
environment variable,
or a per-command basis using the -S sections switch. Programmers
may prefer a default ordering beginning
231
so that when they type
``man wait
''
they see the man page for the system call rather than the one for the shell command
of the same name.
If multi-character sections exist (e.g. some systems have a
man1m
section)
or subsection ordering is desired, then colons must be used to separate
the sections. A FORTRAN programmer might prefer to set his
MANSECT
to
3f:2:3:1:6:8, so that when he asks for the
manual page for
system, he gets
rather than the
C function of the same name.
Case is significant for
the topic itself, but not for the section. This allows
you to make a distinction between
the C compiler,
and
the C++ translator. However, section
3S
is interpreted as section
3s
to accommodate users
who see a reference to the man page for
and don't realize that it's stored in the file
printf.3s.
Search Strategy
The
man
program by default consults the
MANPATH
environment variable for a list of complete man trees.
If this variable is not set, then the user's
PATH
environment variable will be consulted instead. This way, if
/usr/local/bin
is before
/usr/bin
in the PATH variable, then
/usr/local/man
will be before
/usr/man
in the dynamically determined
MANPATH
variable. This is nice because it means the user need only add a
PATH
component, and the
MANPATH
will be automatically updated appropriately.
This search
order can be overridden on a site-wide basis by the system manager (see
NOTES
section below) or on a per-user basis by setting the
environment variable
MANPATH .
This is a colon-separated
list of directory names that contains subdirectories
of the form
man*/. A user keeping his own man pages under his home directory
might place a line like the following in his
~/.cshrc
file:
``setenv MANPATH $HOME/man:/usr/local/man:/usr/man
''
The
MANPATH
may also be set on a per-command basis by using the
-M
command-line.
It is possible to install several complete sets
of man pages on one host. These alternate sets are
assumed to be installed in
MANALT/subdir, where
MANALT
is an environment variable defaulting to
/usr/local/man
and
subdir
is assumed to be a complete man tree.
If at least non-switch two arguments are supplied,
then the
MANALT
directory is consulted
to see whether it contains a sub-directory whose names is the
first argument. This makes it easy to say things like
``man sun csh
''
to read the
csh
man page from the installed set of
sun
man pages. This is equivalent to saying
``man -M /usr/local/man/sun csh
'' (assuming
MANALT
is not set).
Indexing
Very long man pages are often broken up into several major
subsections, whose tables of contents can be listed with the
-i
switch.
To access one of these subsections directly,
specify /index,
where
/index
is the name of the subsection.
For example,
to see the section on expressions in the
man page, use
``man csh/expr
''
to skip to that section first.
If
index
is not a valid section or
subsection header, or if none is given,
a list of all valid section
headers is displayed and the user is prompted
to select one. The special form of a missing subsection
after the slash means to go into continuous menu mode, returning to the
section menu after the manual page has been displayed.
The match against the index entries is not case-sensitive,
nor is it required to be at the beginning
of the string. For example, this allows
``/expr
''
to be
used to look up the
``Regular Expressions
''
section.
However, matches that
do
start at the front of the
header are selected before those that do not. A
numeric section index as listed by the
-i
flag may also be given, with an index of
0
meaning the whole page.
Man page indices (tables of contents) are generated automatically when needed.
To save time,
if a writable
idx*/
subdirectory exists in the root
of the man tree, the index is left there under the
same name as its man page for quicker
access in the future. Indices older than their
parent man page are rebuilt upon demand.
As a special case of indexing, the form
//string
starts the
PAGER
at an arbitrary
string
in the text of the man page
rather than at a subsection index.
Note that the
/index
feature may not be used in conjunction with the
-l
(local file) switch. The
-i
switch may still
be used with local files.
Online Problem Reports
Some vendors provide their customers with electronically
readable problem reports; also, some sites may wish to
maintain their own list of known problems.
To support inclusion of these in
the man pages, the
man
program knows to look in a set of
pr*
subdirectories for additional source. For example, if you
are reading the man page contained in
/usr/man/man1/foo.1,
then if there exists a file called
/usr/man/pr1/foo.1, this will be appended to the
data passed to
nroff
or
troff
as an additional
"KNOWN PROBLEMS"
section. These files should be in
nroff
format.
OPTIONS
- -Mmanpath
-
Changes the search path for finding man pages for just
this command, overriding the current
MANPATH
environment variable or system default.
See the section on
"Search Strategy"
for further details.
- -Ssections
-
sets the section and subsection ordering for just
this command, overriding the
current
MANSECT
environment variables or system default.
See the
Section Selection
for further details.
- -f
-
directs
man
to print out the applicable one-line descriptions
for each corresponding
topic.
These one-line descriptions are stored in separate
whatis
files for each component in the
specified
MANPATH
. If
versions of these
databases exist, these are used for more rapid location of manual
pages. See
for directions on generating the
whatis
databases.
This switch is automatically enabled if
man
is invoked as
whatis.
- -k
-
direct
man
to search the
whatis
databases for any entry
matching the given
keyword.
This is useful when the precise topic is unknown; it reports
the topics that have to do with the given keywords, according
to their
whatis
descriptions.
Output will be sent to the user's
PAGER .
This switch is automatically enabled if
man
is invoked as
apropos.
- -K
-
same as
-k
except regular expressions as in
may be used in the
keywords.
- -g
-
Grep through all man pages for one or more
perl
expressions. Compressed man pages will be
correctly processed
by
- -t
-
is used to typeset the manual pages, usually
using
or a front-end for the same.
If the
default system typesetter is not desired, it can be overridden
either with the
TROFF
environment variable or the
-T
flag.
- -Ttroffproc
-
selects an alternate typesetting program, overriding
the current
TROFF
environment variable or system default.
It is most
often used to select a previewer
for workstations that support previewing of
troff
output.
- -l
-
is used with specific file names rather than with
topics. The same processing as
man
would perform on a system
manual page will be performed on the given file. This is useful
when first writing new manual pages or viewing ones not yet installed.
It may be used in conjunction with other switches, such as
-t. The indexing feature is not available for local man pages except
via the
-i
switch.
- -w
-
is used to determine the full pathnames of
the files that
man
would display for the given topic. This is useful
when the same topic occurs in more than one section of the manual or
in more than one of the components in the supplied
MANPATH .
The files are listed in the order in which they would be presented
to the user.
- -a
-
displays all man pages for all possible matches for a given
topic. Its effect is similar to calling
man
on all the files returned by the
-w
switch.
- -A
-
prompts the user to select which man page is desired if
more than one are found. A selection of 0 is effectively
the same as having used the
-a
option in the first place.
- -i
-
displays
the complete section and subsection index
for a given topic.
- -v
-
prints out the current revision of the program
as stored by
- -u
-
displays a long usage message, piped through the user's
PAGER .
It includes the current defaults for
PAGER ,
MANPATH ,
MANSECT ,
MANALT ,
and
TROFF .
- -h
-
forces
man
to ignore the
whatis
databases and search for its manual pages the slow way. This is the
default behavior if no
whatis
database has been created for
a particular man tree.
- -d
-
triggers debugging output. All externally invoked programs
such as
nroff
and
egrep
will have their arguments displayed
before they are called. Certain other debugging information is also printed.
- -D
-
causes embedded backspaces and their preceding characters
in cat pages to be stripped upon
output. This is useful for producing utterly clean output,
such as when being viewed in an
window.
EXAMPLES
man stty # show me the first stty man page
man -w stty # which stty man pages are there?
man 3 stty # show me the one from section 3
man -a tty # show all man pages on tty
man old makewhatis # show me the makewhatis man page from mano
man new csh # show me the csh man page from mann
man sun csh # show me the csh man page for suns
(assumes $MANALT/sun contains sun man pages)
man -i uucp # get list of sections in uucp man page
man -ai tty # give list of sections on all tty pages
man adb/bugs # check for BUGS section of adb man page
man man/exam # start at this example section
man ksh/ # select from section menu for ksh man page
man sun cron/files # go to the FILES section of the sun cron man page
man -f rcs # what is rcs?
whatis rcs # same as previous
whatis vax rcs # same as previous, but only vax man pages
man -k rcs # what knows about rcs?
apropos rcs # same as previous
apropos sun rcs # same as previous, but only sun man pages
man -g 'file[-\s]*system' # find pages referencing file systems
man -S231 wait # override system section ordering
man -S3f:3s:3:2:1 system# subsection ordering
man -M ~/man hack # use ~/man as only man tree
man -t 4 tty # troff tty(4) man page
man -at tty # troff all tty pages
man -Tpnitroff perl # preview perl man page
man -lTpnitroff ../foo.1# preview local file as man page
man -l file.x # run man on local file
man -tl file.x # print local file as man would
man -il file.x # get section index on local page
ENVIRONMENT
Man
explicitly checks for the following environment variables; if they are
present, they
will override its internal defaults:
- MANPATH
-
The colon-separated list of man trees for locating man pages. This
may itself be overridden by the command line flags
-M
or by
specifying an alternate hardware type.
- MANSECT
-
The default ordering for section and subsection sorting. It need only
be separated by colons if multi-character sections such as
man1m
exist
or if subsection ordering is desired, such as to place subsection
3f
in front of section
3 .
- MANALT
-
The directory to check for alternate sets of man trees. This is useful
for storing the man pages for several different machine architectures or
versions of the operating system. See the
Search Strategy
section
for details.
- PAGER
-
The user's preferred viewer of paged output. Note that often the pager
itself will consult the environment; for example,
more
looks for a
MORE
variable
and
less
looks for a
LESS
variable
in the environment.
- TROFF
-
The preferred typesetter program. It should recognize
troff
input and switches.
This may be overridden using the
-T
command line flag.
FILES
/usr/man default man tree
/usr/man/man*/*.* unformatted (nroff source) man pages
/usr/man/cat*/*.* formatted man pages
/usr/man/idx*/*.* indices for section headers
/usr/man/whatis default whatis database, text version
/usr/man/whatis.dir dbm index file for default whatis database
/usr/man/whatis.pag dbm data file for default whatis database
/usr/lib/perl/getopts.pl required perl library file
/usr/lib/perl/stat.pl required perl library file
SEE ALSO
NOTES
This version of
man
is written entirely in the
programming language
and thus requires that
perl
be properly installed on your system to run.
Because
man
is distributed in a script, it can be easily
reconfigured by the system managers to suit their site's particular style.
This is good, as some of the default settings are somewhat
idiosyncratic to the set-up at the CONVEX home office.
Be sure to save a copy of the
original man
program before any modification.
Things that can be configured include:
- *
-
the default
PAGER
and its flags (alternate flags can be provided for
less)
- *
-
system defaults for
MANPATH ,
MANSECT ,
MANALT ,
and
TROFF .
- *
-
paths for
troff,
nroff,
tbl,
eqn,
neqn,
ul,
col,
egrep, and
compress
- *
-
whether you have compressed man pages and how they are stored
- *
-
which section aliases you want (as in
public
being recognized
as section p)
- *
-
whether to recognize man pages whose
NAME
sections don't mention their
own names
To save disk space at the expense of execution time, a site may
wish to run
on the manual entries where available. The
man
program
understands how to read compressed man
pages, and knows to create a compressed cat page if the source
man page was compressed to start with.
When running on slow CPUs, the start-up time for parsing the
script may be annoying. These sites can skip this parsing phase
at each invocation of
by using perl's
-u
flag to dump a binary image of the interpreter.
DIAGNOSTICS
Several self-explanatory diagnostics are possible, such as
``No manual entry for xyzzy
'',
but the following warnings may not be intuitive:
``But what do you want from section %s?
''
A section was specified but no topic.
``No dbm file for %s: %m
''
This means that the named man tree does not have an
accessible
dbm
version
of its
whatis
database and that
should be run on it. This only shows up when
-d
option is used. %m is the appropriate
message.
``%s has disappeared -- rerun makewhatis
''
A man page has been removed since
makewhatis
was last run.
Note that new man pages being added will NOT be detected.
``nroff of %s failed
''
For some reason
nroff
did not exit correctly. The disk may
be mounted read-only, it might be full, or
nroff
may
not be installed on your system. Contact your system manager.
``%s was length 0; disk full?
''
A cat page was empty.
The
man
program
unlinks the useless cat page,
issues this warning, and exits non-zero. Rerun the command and
if the problem persists, contact your system manager.
``/tmp not writable
''
The
/tmp
and
/usr/man/cat*
directories are not writable by you. Contact your system manager.
``No whatis databases found, please run makewhatis
''
The
man
program was unable to find a
whatis
database for use with
apropos
or
man -k
in any of the directories listed in the
MANPATH.
Have your system manager run
makewhatis
on the system manual page directories, and run
makewhatis
on any personal manual page directories.
``bad eval: %s
''
``can't eval %s: %s
''
These are internal errors that should never occur. Contact
your system manager, who should submit a problem report.
RESTRICTIONS
Once a
whatis
database has been created for a particular man root,
new man pages will not be found unless the
-h
flag is
used or until
makewhatis
is rerun.
If your
PAGER
is
bold text shows up in the normal font;
however,
does display bold text in your terminal's bold font.
BUGS
The manual is supposed to be reproducible either on the phototypesetter
or on an ASCII terminal.
However, on a terminal, some information is necessarily lost.
The
-t
flag for
man
only works if the host system supports
troff.
Not all systems have
compress
installed on them.
AUTHOR
Tom Christiansen
<tchrist@convex.com>
COPYRIGHT
Copyright 1990
CONVEX Computer Corporation.
You are free to use, modify, and redistribute these scripts
as you wish for non-commercial purposes provided that this
notice remains intact.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- Section Selection
-
- Search Strategy
-
- Indexing
-
- Online Problem Reports
-
- OPTIONS
-
- EXAMPLES
-
- ENVIRONMENT
-
- FILES
-
- SEE ALSO
-
- NOTES
-
- DIAGNOSTICS
-
- RESTRICTIONS
-
- BUGS
-
- AUTHOR
-
- COPYRIGHT
-
This document was created by
man2html,
using the manual pages.
Time: 08:45:49 GMT, May 19, 2025