View Source: man(1) - Waikato Linux Users Group

Edit PageHistory Diff Info LikePages
man
!!!man
NAME
SYNOPSIS
DESCRIPTION
EXAMPLES
OVERVIEW
DEFAULTS
OPTIONS
EXIT STATUS
ENVIRONMENT
FILES
SEE ALSO
HISTORY
----
!!NAME


man - an interface to the on-line reference manuals
!!SYNOPSIS


__man__ [[__-c__|__-w__|__-tZHT__ ''device'']
[[__-adhu7V__] [[__-m__ ''system''[[,...]] [[__-L__
''locale''] [[__-p__ ''string''] [[__-M__
''path''] [[__-P__ ''pager''] [[__-r__
''prompt''] [[__-S__ ''list''] [[__-e__
''extension''] [[[[''section''] ''page'' ...]
...__
man -l__ [[__-7__] [[__-tZHT__ ''device'']
[[__-p__ ''string''] [[__-P__ ''pager'']
[[__-r__ ''prompt''] ''file'' ...__
man -k__ [[''apropos options''] ''regexp'' ...__
man -f__ [[''whatis options''] ''page''
...
!!DESCRIPTION


__man__ is the system's manual pager. Each ''page''
argument given to __man__ is normally the name of a
program, utility or function. The ''manual page''
associated with each of these arguments is then found and
displayed. A ''section'', if provided, will direct
__man__ to look only in that ''section'' of the
manual. The default action is to search in all of the
available ''sections'', following a pre-defined order and
to show only the first ''page'' found, even if
''page'' exists in several ''sections''.


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


A manual ''page'' consists of several parts.


They may be labelled __NAME__, __SYNOPSIS__,
__DESCRIPTION__, __OPTIONS__, __FILES__, __SEE
ALSO__, __BUGS__, and __AUTHOR__.


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


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 __SYNOPSIS__ section of this manual page.
!!EXAMPLES


__man__ ''ls''


Display the manual page for the ''item'' (program)
''ls''.


__man -a__ ''intro''


Display, in succession, all of the available ''intro''
manual pages contained within the manual. It is possible to
quit between successive displays or skip any of
them.


__man -t__ ''alias'' | ''lpr -Pps''


Format the manual page referenced by `''alias''', usually
a shell manual page, into the default __troff__ or
__groff__ format and pipe it to the printer named
''ps''. The default output for __groff__ is usually
!PostScript. __man --help__ should advise as to which
processor is bound to the __-t__ option.


__man -l -T__''dvi ./foo.1x.gz'' ____
''./foo.1x.dvi''


This command will decompress and format the nroff source
manual page ''./foo.1x.gz'' into a __device independent
(dvi)__ file. The redirection is necessary as the
__-T__ flag causes output to be directed to __stdout__
with no pager. The output could be viewed with a program
such as __xdvi__ or further processed into !PostScript
using a program such as __dvips.__


__man -k__ ''printf''


Search the short descriptions and manual page names for the
keyword ''printf'' as regular expression. Print out any
matches. Equivalent to __apropos -r__
''printf''__.__


__man -f__ ''smail''


Lookup the manual pages referenced by ''smail'' and print
out the short descriptions of any found. Equivalent to
__whatis -r__ ''smail''__.__
!!OVERVIEW


Many options are available to __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 __man__. It is possible to set
the `catch all' variable $__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). __man__ will parse $__MANOPT__ prior to
parsing its 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
$__MANOPT__, __-D__ can be specified as the initial
command line option. This will allow man to `forget' about
the options specified in $__MANOPT__ although they must
still have been valid.


The manual pager utilities packaged as __man_db__ make
extensive use of __index__ database caches. These caches
contain information such as where each manual page can be
found on the filesystem and what its ''whatis'' (short
one line description of the man page) contains, and allow
__man__ to run faster than if it had to search the
filesystem each time to find the appropriate manual page. If
requested using the __-u__ option, __man__ will ensure
that the caches remain consistent, which can obviate the
need to manually run software to update traditional
''whatis'' text databases.


If __man__ cannot find a __mandb__ initiated
__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 __whatis__ or __apropos__
fails to find an __index__ it will try to extract
information from a traditional ''whatis'' database
instead.


These utilities support compressed source nroff files
having, by default, the extensions of __.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 __gzip__. Each `global' manual page
hierarchy such as ''/usr/share/man'' or
''/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 __File Hierarchy Standard (FHS)__,
it may be better to store them elsewhere. For details on how
to do this, please read 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 ''locale'' functions. To activate such
support, it is necessary to set either $__LC_MESSAGES__,
$__LANG__ or another system dependent environment
variable to your language locale, usually specified in the
__POSIX 1003.1__ based format:


language''''_____territory''''.____character-set'''',____version''''


If the desired page is available in your ''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 maintainer 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.
!!DEFAULTS


__man__ will search for the desired manual pages within
the ''index'' database caches. If the __-u__ option is
given, a cache consistency check is performed to ensure the
databases accurately reflect the filesystem. If this option
is always given, it is not generally necessary to run
__mandb__ after the caches are initially created, unless
a cache becomes corrupt. However, the cache consistency
check can be slow on systems with many manual pages
installed, so it is not performed by default, and system
administrators may wish to run __mandb__ every week or so
to keep the database caches fresh. To forestall problems
caused by outdated caches, __man__ will fall back to file
globbing if a cache lookup fails, just as it would if no
cache was present.


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 else will fall back to a default is
used (see option __-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), __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 __-p__ or the environment
variable $__MANROFFSEQ__ is interrogated. If __-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


__'__ __string____


where __string__ can be any combination of letters
described by option __-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 (__nroff__ or [[__tg__]__roff__
with __-t__) and executed. Alternatively, if an
executable program ''mandb_nfmt'' (or ''mandb_tfmt''
with __-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 __-T__ as arguments.
!!OPTIONS


Non argument options that are duplicated either on the
command line, in $__MANOPT__, or both, are not harmful.
For options that require an argument, each duplication will
override the previous argument value.


__-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. No cat file is produced.
If '-' is listed as one of the arguments, input will be
taken from stdin. When this option is not used, and man
fails to find the page required, before displaying the error
message, it attempts to act as if this option was supplied,
using the name as a filename and looking for an exact
match.


__-L__ ''locale''__,
--locale=__''locale''


__man__ will normally determine your current locale by a
call to the C function setlocale(3) which
interrogates various environment variables, possibly
including $__LC_MESSAGES__ and $__LANG__. To
temporarily override the determined value, use this option
to supply a ''locale'' string directly to __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.


__-D, --default__


This option is normally issued as the very first option and
resets __man's__ behaviour to its default. Its use is to
reset those options that may have been set in
$__MANOPT__. Any options that follow __-D__ will have
their usual effect.


__-M__ ''path''__,
--manpath=__''path''


Specify an alternate manpath to use. By default, __man__
uses __manpath__ derived code to determine the path to
search. This option overrides the $__MANPATH__
environment variable and causes option __-m__ to be
ignored.


A path specified as a manpath must be the root of a manual
page hierarchy structured into sections as described in the
man_db manual (under
-l__ option.


__-P__ ''pager''__,
--pager=__''pager''


Specify which output pager to use. By default, __man__
uses __exec /usr/bin/pager -s__. This option overrides
the $__PAGER__ environment variable and is not used in
conjunction with __-f__ or __-k__.


__-r__ ''prompt''__,
--prompt=__''prompt''


If a recent version of __less__ is used as the pager,
__man__ will attempt to set its prompt and some sensible
options. The default prompt looks like


__Manual page__ ''name''__(__''sec''__)
line__ ''x''


where ''name'' denotes the manual page name, ''sec''
denotes the section it was found under and ''x'' the
current line number. This is achieved by using the
$__LESS__ environment variable.


Supplying __-r__ with a string will override this
default. The string may contain the text __$MAN_PN__
which will be expanded to the name of the current manual
page and its section name surrounded by `(' and `)'. The
string used to produce the default could be expressed
as


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


It is broken into two lines here for the sake of readability
only. For its meaning see the 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 __man__ sets the __-ix8__
options.


__-7, --ascii__


When viewing a pure ascii(7) manual page on a 7 bit
terminal or terminal emulator, some characters may not
display correctly when using the ''latin1''(7) device
description with __GNU nroff__. This option allows pure
''ascii'' manual pages to be displayed in ''ascii''
with the ''latin1'' device. It will not translate any
''latin1'' text. The following table shows the
translations performed.


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


This option is ignored when using options __-t__,
__-H__, __-T__, or __-Z__ and may be useless for
__nroff__ other than __GNU's__.


__-S__ ''list''__,
--sections=__''list''


List is a colon-separated list of `order specific' manual
sections to search. This option overrides the
$__MANSECT__ environment variable.


__-a, --all__


By default, __man__ will exit after displaying the most
suitable manual page it finds. Using this option forces
__man__ to display all the manual pages with names that
match the search criteria.


__-c, --catman__


This option is not for general use and should only be used
by the __catman__ program.


__-d, --debug__


Don't actually display any manual pages, but do print lots
of debugging information.


__-e__ ''sub-extension''__,
--extension=__''sub-extension''


Some systems incorporate large packages of manual pages,
such as those that accompany the __Tcl__ package, into
the main manual page hierarchy. To get around the problem of
having two manual pages with the same name such as
exit(3), the __Tcl__ pages were usually all
assigned to section __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,
exit(3tcl). Under normal operation, __man__ will
display exit(3) in preference to 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 __man__ a string indicating which
package the page must belong to. Using the above example,
supplying the option __-e tcl__ to __man__ will
restrict the search to pages having an extension of
__*tcl__.


__-f, --whatis__


Equivalent to __whatis__. Display a short description
from the manual page, if available. See whatis(1) for
details.


__-h, --help__


Print a help message and exit.


__-k, --apropos__


Equivalent to __apropos__. Search the short manual page
descriptions for keywords and display any matches. See
apropos(1) for details.


__-m__ ''system''[[,...]__,
--systems=__''system''[[,...]


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 __-m NewOS__.


The ''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 __man__ in the argument string. This option will
override the $__SYSTEM__ environment
variable.


__-p__ ''string''__,
--preprocessor=__''string''


Specify the sequence of preprocessors to run before
__nroff__ or __troff__/__groff__. Not all
installations will have a full set of preprocessors. Some of
the preprocessors and the letters used to designate them
are: __eqn__ (__e__), __grap__ (__g__),
__pic__ (__p__), __tbl__ (__t__), __vgrind__
(__v__), __refer__ (__r__). This option overrides
the $__MANROFFSEQ__ environment variable. __zsoelim__
is always run as the very first preprocessor.


__-u, --update__


This option causes __man__ to perform an `inode level'
consistency check on its database caches to ensure that they
are an accurate representation of the filesystem. It will
only have a useful effect if __man__ is installed with
the setuid bit set.


__-t, --troff__


Use ''/usr/bin/groff -mandoc'' to format the manual page
to stdout. This option is not required in conjunction with
__-H__, __-T__, or __-Z__.


__-T__ ''device''__, --troff-device__
[[''=device'']


This option is used to change __groff__ (or possibly
__troff's__) output to be suitable for a device other
than the default. It implies __-t__. Examples (provided
with Groff-1.09) include __dvi__, __latin1__,
__X75__ and __X100__.


__-Z, --ditroff__


__groff__ will run __troff__ and then use an
appropriate post-processor to produce output suitable for
the chosen device. If ''/usr/bin/groff -mandoc'' is
__groff__, this option is passed to __groff__ and will
suppress the use of a post-processor. It implies
__-t__.


__-H, --html__


This option will cause __groff__ to produce HTML output,
and will display that output in a web browser. The choice of
browser is determined by the $__BROWSER__ environment
variable, or by a compile-time default if that is unset
(usually __lynx__). This option implies __-t__, and
will only work with __GNU troff__.


__-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.


__-V, --version__


Display version information.
!!EXIT STATUS


__0__


Successful program execution.


__1__


Usage, syntax or configuration file error.


__2__


Operational error.


__3__


A child process returned a non-zero exit
status.


__16__


At least one of the pages/files/keywords didn't exist or
wasn't matched.
!!ENVIRONMENT


__MANPATH__


If $__MANPATH__ is set, its value is used as the path to
search for manual pages.


__MANROFFSEQ__


If $__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.


__MANSECT__


If $__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.


__PAGER__


If $__PAGER__ is set, its value is used as the name of
the program used to display the manual page. By default,
__exec /usr/bin/pager -s__ is used.


__BROWSER__


If $__BROWSER__ is set, its value is a colon-delimited
list of commands, each of which in turn is used to try to
start a web browser for __man --html__. In each command,
''%s'' is replaced by a filename containing the HTML
output from __groff__, ''%%'' is replaced by a single
percent sign (%), and ''%c'' is replaced by a colon
(:).


__SYSTEM__


If $__SYSTEM__ is set, it will have the same effect as
option __-m string__ where string will be taken as
$__SYSTEM__'s contents.


__MANOPT__


If $__MANOPT__ is set, it will be parsed prior to
__man's__ command line and is expected to be in a similar
format. As all of the other __man__ specific environment
variables can be expressed as command line options, and are
thus candidates for being included in $__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.


__MANWIDTH__


If $__MANWIDTH__ is set, its value is used as the line
length for which manual pages should be formatted. If it is
not set, manual pages will be formatted with a line length
appropriate to the current terminal (using an
ioctl(2) if available, the value of $__COLUMNS__,
or falling back to 80 characters if neither is available).
Cat pages will only be saved when the default formatting can
be used, that is when the terminal line length is between 66
and 80 characters.


__LANG__, __LC_MESSAGES__


Depending on system and implementation, either or both of
$__LANG__ and $__LC_MESSAGES__ will be interrogated
for the current message locale. __man__ will display its
messages in that locale (if available). See
setlocale(3) for precise details.
!!FILES


''/etc/manpath.config''


man_db configuration file.


''/usr/share/man''


A global manual page hierarchy.


''/usr/share/man/index.(bt|db|dir|pag)''


A traditional global ''index'' database
cache.


''/var/cache/man/index.(bt|db|dir|pag)''


An alternate or FHS compliant global ''index'' database
cache.
!!SEE ALSO


mandb(8), manpath(1), manpath(5),
apropos(1), whatis(1), catman(8),
less(1), nroff(1), troff(1),
groff(1), zsoelim(1), setlocale(3),
man(7), ascii(7), latin1(7), the man_db
package manual, __FSSTND__.
!!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).


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


30th October 1996 - 30th March 2001: Fabrizio Polacco


31st March 2001 - 07 September 2001: Colin Watson
----
28 pages link to man(1):
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
Last edited on Tuesday, June 4, 2002 12:22:19 am by "perry"
Edit PageHistory Diff Info LikePages