## SYNOPSIS

           man  [-c|-w|-tZT  device]  [-adhu7V] [-m system[,...]] [-L
           locale] [-p string] [-M path] [-P pager] [-r  prompt]  [-S
           list] [-e extension] [[section] page ...] ...
           man  -l  [-7]  [-tZT  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 func
           tion.  The manual page associated with each of these argu
           ments is then found and displayed. A section, if provided,
           will direct man to look only in that section of  the  man
           ual.  The default action is to search in all of the avail
           able 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.

           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 /dev)
           5   File formats and conventions eg /etc/passwd
           6   Games
           7   Macro packages and conventions eg man(7), groff(7).
           8   System administration commands (usually only for root)
           9   Kernel routines [Non standard]

           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.

           bold text          type exactly as shown.
           italic text        replace with appropriate argument.
           [-abc]             any or all arguments within [ ] are optional.
           -a|-b              options delimited by | cannot be used together.
           argument ...       argument is repeatable.
           [expression] ...   entire expression within [ ] is repeatable.

           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.
               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 -Tdvi ./foo.1x.gz > ./foo.1x.dvi
               This command will  decompress  and  format  the  nroff
               source  manual page ./foo.1x.gz into a device indepen
               dent (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 back
           slash).  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  exten
           sive  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
           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 fea
           tured 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  docu
           ments 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
           $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 con
           tain 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  informa
           tion, a default set is used.

           A  formatting  pipeline is formed from the filters and the
           primary formatter (nroff or [tg]roff  with  -t)  and  exe
           cuted.  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  speci
           fied 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 sys
                  tem'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 inter
                  rogates  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  deter
                  mined locale.

                  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 "The manual
                  page system").  To view manual pages  outside  such
                  hierarchies, see the -l option.

           -P pager, --pager=pager
                  Specify which output pager to use.  By default, man
                  uses exec /usr/bin/less -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 sensi
                  ble 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 pre
                  ceding  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  trans
                  late  any  latin1  text.  The following table shows
                  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, -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  pack
                  age,  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 situa
                  tion 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
                  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 pre
                  processors and the letters used to  designate  them
                  are:  eqn  (e),  grap (g), pic (p), tbl (t), vgrind
                  (v), refer (r).  This option  overrides  the  $MAN
                  ROFFSEQ  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 either -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  (pro
                  vided 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.

           -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

                  to search for manual pages.

           MANROFFSEQ
                  If  $MANROFFSEQ is set, its value is used to deter
                  mine 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/less -s is used.

           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  environ
                  ment  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  inter
                  preted  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 ter
                  minal (using an ioctl(2) if available, the value of
                  $COLUMNS,  or falling back to 80 characters if nei
                  ther 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
           catman(8),  less(1),  nroff(1),  troff(1), groff(1), zsoe
           lim(1),  setlocale(3),  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.Wil
           ford@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
           <fpolacco@debian.org> maintained and enhanced this package
           for the Debian project, with the help of  all  the  commu
           nity.

           31st  March  2001  -  14  May  2001:  Colin Watson <cjwat
           son@debian.org> is now developing and maintaining  man-db.

    2.3.19                     14 May 2001                     man(1)