Quick ?s
Cheat Sheets
Man Pages
The Lynx
Software
MAN(1)			      Manual pager utils			MAN(1)



NAME
       man - an interface to the on-line reference manuals

SYNOPSIS
       man  [-c|-w|-tZ]  [-H[browser]] [-T[device]] [-adhu7V] [-i|-I] [-m sys
       tem[,...]] [-L locale] [-p string] [-C file] [-M path] [-P  pager]  [-r
       prompt] [-S list] [-e extension] [[section] page ...] ...
       man -l [-7] [-tZ] [-H[browser]] [-T[device]] [-p string] [-P pager] [-r
       prompt] file ...
       man -k [apropos options] regexp ...
       man -f [whatis options] page ...

DESCRIPTION
       man is the systems 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.


       1   Executable programs or shell commands
       2   System calls (functions provided by the kernel)
       3   Library calls (functions within program libraries)
       4   Special files (usually found in /dev)
       5   File formats and conventions eg /etc/passwd
       6   Games
       7   Miscellaneous  (including  macro  packages and conven
	   tions), e.g. 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 sev
       eral 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 man
	   ual 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 -Tdvi ./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  redi
	   rection 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,  sec
       tion  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 options argument must be escaped (pre
       ceded 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 com
       pile 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  Hierar
       chy  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:

       [_[.[,]]]

       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 coordi
       nating 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 per
       formed 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 ini
       tial line of the nroff file is parsed for a  preprocessor  string.   To
       contain a valid preprocessor string, the first line must resemble

       \" 

       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 for
       matter (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 or -E 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 argu
       ment, 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 systems 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  tem
	      porarily	override the determined value, use this option to sup
	      ply 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 mans 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.

       -C file, --config-file=file
	      Use this user configuration file	rather	than  the  default  of
	      ~/.manpath.

       -M path, --manpath=path
	      Specify  an alternate manpath to use.  By default, man uses man
	      path 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 "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
	      /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 sur
	      rounded 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.

	      If  you  want  to  override  mans prompt string processing com
	      pletely, use the $MANLESS environment variable described	below.

       -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:
	      some  parts  of it may only be displayed properly when using GNU
	      nroffs latin1(7) device.


	      Description	    Octal   latin1   ascii
	      ---------------------------------------------
	      continuation hyphen    255	      -
	      bullet (middle dot)    267	      o
	      acute accent	     264
	      multiplication sign    327	      x

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

       -S list, --sections=list
	      List  is	a colon-separated list of order specific manual sec
	      tions 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
	      Dont  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 exten
	      sion of *tcl.

       -f, --whatis
	      Equivalent to whatis.  Display a short description from the man
	      ual page, if available. See whatis(1) for details.

       -h, --help
	      Print a help message and exit.

       -i, --ignore-case
	      Ignore case when	searching  for	manual	pages.	 This  is  the
	      default.

       -I, --match-case
	      Search for manual pages case-sensitively.

       -k, --apropos
	      Equivalent  to  apropos.	 Search the short manual page descrip
	      tions for keywords and display any matches.  See apropos(1)  for
	      details.

       -m system[,...], --systems=system[,...]
	      If  this	system	has  access to other operating systems manual
	      pages, they can be accessed using this option.  To search for  a
	      manual  page from NewOSs 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 oper
	      ating systems manual pages, include the system name man in  the
	      argument string.	This option will override the $SYSTEM environ
	      ment 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 pre
	      processors.  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  environ
	      ment  variable.  zsoelim is always run as the very first prepro
	      cessor.

       -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 troffs) output
	      to  be suitable for a device other than the default.  It implies
	      -t.  Examples (provided with Groff-1.17)	include  dvi,  latin1,
	      ps, utf8, 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[browser], --html[=browser]
	      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 optional browser argument if one is  provided,
	      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.

       -E device, --encoding=device
	      Generate output for a character encoding other than the default.
	      Due to the way nroff is currently designed, the argument to this
	      function must be an nroff device such as ascii, latin1, or utf8.

       -w, --where, --location
	      Dont actually display the manual pages, but do print the	loca
	      tion(s) of the source nroff files that would be formatted.

       -W, --where-cat, --location-cat
	      Dont  actually display the manual pages, but do print the loca
	      tion(s) of the cat files that would be displayed.  If -w and  -W
	      are both specified, print both separated by a space.

       -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 didnt exist or wasnt
	      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 sec
	      tions 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, /usr/bin/pager  -s
	      is used.

       MANLESS
	      If  $MANLESS  is set, man will not perform any of its usual pro
	      cessing to set up a prompt string for the less pager.   Instead,
	      the  value  of $MANLESS will be copied verbatim into $LESS.  For
	      example, if you want to set the prompt string unconditionally to
	      my prompt string, set $MANLESS to -Psmy prompt string.

       BROWSER
	      If  $BROWSER is set, its value is a colon-delimited list of com
	      mands, 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 $SYSTEMs contents.

       MANOPT If $MANOPT is set, it will be parsed prior to mans 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  options	argu
	      ment 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,  man
	      ual  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  for
	      matting  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 avail
	      able).  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   maintained and enhanced this package for  the	Debian
       project, with the help of all the community.

       31st  March  2001  - present day: Colin Watson  is
       now developing and maintaining man-db.



2.4.3				  2005-07-03				MAN(1)




Yals.net is © 1999-2009 Crescendo Communications
Sharing tech info on the web for more than a decade!
This page was generated Thu Apr 30 17:05:19 2009