MAN(1)                     Commands and Applications                    MAN(1)




NAME

       man - display reference manual pages; find reference pages by keyword


SYNOPSIS

       man [-] [-t] [-M path] [-T macro-package] [section] title
       man [-M path] -k keyword ...
       man [-M path] -f filename ...


DESCRIPTION

       This manual page documents man version 3.0.

       man  displays  information  from the reference manuals.  It can display
       complete manual pages that you select by title, or  one-line  summaries
       selected  either  by keyword (-k), or by the name of an associated file
       (-f).

       A section, when given, applies to the title that follows it on the com-
       mand  line.   man looks in the indicated section of the manual for that
       title.  section is either a digit (perhaps followed by a single  letter
       indicating  the  type  of manual page), or one of the words new, local,
       old, or public.  The abbreviations n, l, o and p are also allowed.   If
       section is omitted, man searches all reference sections (giving prefer-
       ence to commands over functions).  If more than one manual page  exists
       for  the  specified title, each page is displayed in the order in which
       it is found.  The user is given the option of exiting after  each  page
       is  displayed.   If no manual page is located, man prints an error mes-
       sage.

       The reference page sources are typically located in  the  /usr/man/man?
       directories.   If there are preformatted, up-to-date versions in corre-
       sponding cat?  or fmt?  directories,  man  simply  displays  or  prints
       those versions.  If the preformatted version of interest is out of date
       or missing, man reformats it prior to display.  If directories for  the
       preformatted  versions  are not provided, man reformats a page whenever
       it is requested.

       If the standard output is not a terminal, or if the '-' flag is  given,
       man  pipes its output through cat(1V).  Otherwise, man pipes its output
       through more(1) to handle paging and underlining on the screen.


OPTIONS

       -t     man arranges for the specified manual pages to be troffed  to  a
              suitable  raster  output device (see troff(1) or vtroff(1)).  If
              both the - and -t flags are given, man updates the troffed  ver-
              sions  of  each named title (if necessary), but does not display
              them.

       -M path
              Change the search path for manual pages.  path is  a  colon-  or
              space-separated  list  of  directories  that contain manual page
              directory subtrees.  For example,  /usr/man/u_man:/usr/man/a_man
              makes  man search in the standard System V locations.  The space
              delimiter is provided for compatibility with GS/OS's use of  the
              colon  as  a  pathname  component delimiter.  If the search path
              contains no spaces nor / characters (such as :usr:local:man), it
              is  assumed to be a single path, not a list of paths.  If spaces
              are used as delimiters, remember to quote path from  the  shell.
              Each  directory in the path is assumed to contain subdirectories
              of the form man[1-8l-p].

       -T macro-package
              man uses macro-package rather  than  the  standard  -man  macros
              defined in /usr/lib/tmac/tmac.an for formatting manual pages.

       -k keyword ...
              man  prints out one-line summaries from the whatis database (ta-
              ble of contents) that contain any of the  given  keywords.   The
              whatis database is created using the makewhatis(8) command.

       -f filename ...
              man  attempts to locate manual pages related to any of the given
              filenames.  It strips the leading pathname components from  each
              filename,  and  then  prints  one-line  summaries containing the
              resulting basename or names.  This option also uses  the  whatis
              database.


MANUAL PAGES

       Manual  pages  are  either nroff(1)/troff(1) source files prepared with
       the -man macro package, or aroff(1) source files prepared  with  Apple-
       works GS (tm) or a compatible word processor.

   Referring to Other Manual Pages
       Other  manual  pages can be referenced in one of two ways, depending on
       whether the target manual page is an aroff or nroff source file.

       For aroff source files, a "link" may be made by creating a file  ending
       in .l (that's a dot-ell).  The file must contain a single line consist-
       ing of the pathname of the target aroff source  file.   An  intentional
       design  limitation  was  made that disallows this form of "link" in the
       manl (that's man-ell) subdirectory.

       For nroff source files, a "link" may be made by creating  a  file  con-
       taining the nroff source (.so) command.  This file should have the same
       suffix as the target nroff source file.  man does  not  itself  do  any
       processing of the source command.

       With  both  types of "links" the pathname may be either a full- or par-
       tial-pathname.  In the latter case, the pathname must  be  relative  to
       the root of the manual page directory subtree.

       man processes the indicated file in place of the current one.  The ref-
       erence must be expressed as a pathname relative to the root of the man-
       ual page directory subtree.

   Preprocessing Manual Pages
       If the first line is a string of the form:

            '\"  X

       where X is separated from the '"' by a single SPACE and consists of any
       combination of characters in the following list, man pipes its input to
       troff(1) or nroff(1) through the corresponding preprocessors.

            e     eqn(1), or neqn for nroff
            r     refer(1)
            t     tbl(1)
            v     vgrind(1)


       If  eqn  or  neqn  is  invoked,  it  will  automatically  read the file
       /usr/pub/eqnchar (see eqnchar(7)).  If nroff(1) is invoked, col(1V)  is
       automatically used.


COMPRESSED MANUAL PAGES

       man  allows  its  manual  pages  to  be  compressed by either compress,
       freeze, or gzip, in which case the manual page must have the suffix .Z,
       .F,  or  .gz,  respectively.   Note that the test for these suffixes is
       case sensitive and if the incorrect case is used  then  the  compressed
       file will be passed to nroff with unpredictable results.

       Compression  may  be  used on files in either (or both) of the man? and
       cat?  subdirectories.  Do not compress aroff(1) source files since com-
       pressed  files  in  the  man?   subdirectory  are  always assumed to be
       nroff(1) source.


ENVIRONMENT

       MANPATH
              If set, its value overrides /usr/man as the default search path.
              (The  -M flag, in turn, overrides this value.)  See the descrip-
              tion of the -M flag for syntax details.

       USRMAN If MANPATH is not set, then the value of USRMAN (if  set)  over-
              rides  /usr/man  as  the  default search path.  (The -M flag, in
              turn, overrides this value.)  See the description of the -M flag
              for syntax details.

       MANDIR If  neither  MANPATH nor USRMAN is set, then the value of MANDIR
              (if set) overrides /usr/man as the default search path.  (The -M
              flag,  in  turn,  overrides this value.)  See the description of
              the -M flag for syntax details.

       PAGER  A program to use for interactively delivering  man's  output  to
              the screen.  If not set, '/bin/more' (see more(1)) is used.

       TCAT   The  name of the program to use to display troffed manual pages.
              If not set, 'lpr -t' (see lpr(1)) is used.

       TROFF  The name of the formatter to use when the -t flag is given.   If
              not set, 'troff -t' is used.


FILES

       /usr/[share]/man
              root of the standard manual page directory subtree

       /usr/[share]/man/man?/*
              unformatted manual entries

       /usr/[share]/man/cat?/*
              nroffed manual entries

       /usr/[share]/man/fmt?/*
              troffed manual entries

       /usr/[share]/man/whatis
              table of contents and keyword database

       /usr/[share]/lib/tmac/tmac.an
              standard -man macro package

       /usr/pub/eqnchar


SEE ALSO

       apropos(1), aroff(1), cat(1V), col(1V), compress(1), eqn(1), freeze(1),
       gzip(1),  less(1),  lpr(1),  more(1),   nroff(1),   refer(1),   tbl(1),
       troff(1),  vgrind(1),  vtroff(1),  whatis(1),  whereis(1),  eqnchar(7),
       man(7), catman(8)


NOTES

       Because troff is not 8-bit clean, man has not been made 8-bit clean.

       The -f and -k options use the whatis  database,  which  is  created  by
       makewhatis(8).

       Although  this  version  of  man  allows USRMAN and MANDIR to be each a
       colon- or space-separated list of  pathnames,  other  versions  of  man
       treat  the  values of these environment variables as a single pathname.
       For compatibility reasons, the use of these two  environment  variables
       is discouraged; use MANPATH instead.


BUGS

       The  manual  is supposed to be reproducible either on a phototypesetter
       or on an ASCII terminal.   However,  on  a  terminal  some  information
       (indicated by font changes, for instance) is necessarily lost.

       Some dumb terminals cannot process the vertical motions produced by the
       e (eqn(1)) preprocessing flag.  To prevent garbled output on these ter-
       minals,  when you use e also use t, to invoke col(1V) implicitly.  This
       workaround has the disadvantage of eliminating  superscripts  and  sub-
       scripts  --  even on those terminals that can display them.  CTRL-Q will
       clear a terminal that gets confused by eqn(1) output.

       The code which calls the eqn(1), refer(1), tbl(1), and  vgrind(1)  pre-
       processors is not yet implemented.  Since these preprocessors do not as
       yet exist for GNO, this is not too much of a problem.

       Please report any other bugs to Devin Reade, <gdr@trenco.gno.org>.


HISTORY

       The GNO version of man first appeared in GNO version 1.0 and was  writ-
       ten  by Mike Horwath.  This version was rewritten from scratch by Devin
       Reade.



GNO                              28 March 1998                          MAN(1)

Man(1) output converted with man2html