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)

Man(1) output converted with man2html