unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

man(1)                           User Commands                          man(1)



NAME
       man - find and display reference manual pages

SYNOPSIS
       man [-] [-adFlrt] [-M path] [-T macro-package] [-s section] name...

       man [-M path] -k keyword...

       man [-M path] -f file...

DESCRIPTION
       The  man  command  displays  information from the reference manuals. It
       displays complete manual pages that you select  by  name,  or  one-line
       summaries selected either by keyword (-k), or by the name of an associ-
       ated file (-f). If no manual page is located, man prints an error  mes-
       sage.

   Source Format
       Reference  Manual  pages are marked up with either nroff (see nroff(1))
       or SGML (Standard Generalized Markup Language) tags (see sgml(5)).  The
       man  command  recognizes  the  type  of  markup  and processes the file
       accordingly. The various source files are kept in separate  directories
       depending on the type of markup.

   Location of Manual Pages
       The online Reference Manual page directories are conventionally located
       in   /usr/share/man.   The   nroff   sources   are   located   in   the
       /usr/share/man/man*  directories.  The  SGML sources are located in the
       /usr/share/man/sman* directories. Each directory corresponds to a  sec-
       tion  of  the manual. Since these directories are optionally installed,
       they  might  not  reside  on  your  host.  You  might  have  to   mount
       /usr/share/man from a host on which they do reside.

       If  there  are  preformatted,  up-to-date versions in the corresponding
       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 and stores the  preformatted  version  if
       cat*  or   fmt* is writable.   The  windex database is not updated. See
       catman(1M). If directories for the preformatted versions are  not  pro-
       vided,   man reformats a page whenever it is requested. man uses a tem-
       porary file to store the formatted text during display.

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

OPTIONS
       The following options are supported:

       -a              Shows all manual pages matching  name within  the  MAN-
                       PATH  search  path.  Manual  pages are displayed in the
                       order found.



       -d              Debugs. Displays what a section-specifier evaluates to,
                       method used for searching, and paths searched by man.



       -f file ...     man  attempts  to locate manual pages related to any of
                       the given files. It strips the leading path name compo-
                       nents  from  each  file,  and then prints one-line sum-
                       maries containing the resulting basename or names. This
                       option also uses the windex database.



       -F              Forces  man to search all directories specified by MAN-
                       PATH or the man.cf file, rather than using  the  windex
                       lookup  database. This option is useful if the database
                       is not up to date and it  has  been  made  the  default
                       behavior  of the man command. The option therefore does
                       not have to be invoked and is documented here for  ref-
                       erence only.



       -k keyword ...  Prints  out one-line summaries from the windex database
                       (table of contents) that contain any of the given  key-
                       words. The windex database is created using catman(1M).



       -l              Lists  all  manual pages found matching name within the
                       search path.



       -M path         Specifies an alternate search path  for  manual  pages.
                       path is a colon-separated list of directories that con-
                       tain manual page directory subtrees.  For  example,  if
                       path is /usr/share/man:/usr/local/man, man searches for
                       name in the standard location, and then /usr/local/man.
                       When used with the -k or -f options, the -M option must
                       appear first. Each directory in the path is assumed  to
                       contain  subdirectories of the form man* or sman* , one
                       for each section. This  option  overrides  the  MANPATH
                       environment variable.



       -r              Reformats  the  manual  page,  but does not display it.
                       This replaces the man - -t name combination.



       -s section ...  Specifies sections of the manual for man to search. The
                       directories  searched  for  name  are  limited to those
                       specified by section. section can be a numerical digit,
                       perhaps  followed  by  one or more letters to match the
                       desired section of the manual, for example,  "3libucb".
                       Also,  section  can be a word, for example, local, new,
                       old, public. section can also be a letter.  To  specify
                       multiple  sections, separate each section with a comma.
                       This option overrides the MANPATH environment  variable
                       and  the  man.cf  file.  See  Search  Path below for an
                       explanation of how man conducts its search.



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



       -T macro-packageFormats manual pages using  macro-package  rather  than
                       the     standard     -man     macros     defined     in
                       /usr/share/lib/tmac/an. See  Search  Path  under  USAGE
                       for  a  complete explanation of the default search path
                       order.



OPERANDS
       The following operand is supported:

       name            A keyword or the name of a standard utility.



USAGE
       The usage of man is described below:

   Manual Page Sections
       Entries in the reference manuals are organized into sections. A section
       name  consists  of  a  major  section  name,  typically a single digit,
       optionally followed by a subsection name, typically one  or  more  let-
       ters.  An  unadorned major section name, for example, "9", does not act
       as an abbreviation for the subsections of  that  name,  such  as  "9e",
       "9f",  or "9s". That is, each subsection must be searched separately by
       man -s.  Each section contains descriptions  apropos  to  a  particular
       reference  category,  with subsections refining these distinctions. See
       the intro manual pages for an explanation of the classification used in
       this release.

   Search Path
       Before  searching  for a given name, man constructs a list of candidate
       directories and sections. man searches  for  name  in  the  directories
       specified  by the MANPATH environment variable. If this variable is not
       set, /usr/share/man is searched by default.

       Within the manual page directories, man confines its search to the sec-
       tions specified in the following order:

         o  sections specified on the command line with the -s option

         o  sections embedded in the MANPATH environment variable

         o  sections specified in the man.cf file for each directory specified
            in the MANPATH environment variable


       If none of the above exist, man searches each directory in  the  manual
       page path, and displays the first matching manual page found.

       The man.cf file has the following format:

       MANSECTS=section[,section]...

       Lines  beginning  with `#' and blank lines are considered comments, and
       are ignored. Each directory specified in MANPATH can contain  a  manual
       page  configuration  file, specifying the default search order for that
       directory.

Formatting Manual Pages
       Manual pages are marked up in nroff(1) or sgml(5).  Nroff manual  pages
       are  processed  by  nroff(1)  or  troff(1) with the -man macro package.
       Please refer to man(5) for information  on  macro  usage.  SGML--tagged
       manual pages are processed by an  SGML parser and passed to the format-
       ter.

   Preprocessing Nroff Manual Pages
       When formatting an nroff manual page, man examines the  first  line  to
       determine  whether it requires special processing. If the first line is
       a string of the form:

       '\" X

       where X is separated from the `"' by a single <&lt;SPACE>&gt; 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  automatically   reads   the   file
       /usr/pub/eqnchar  (see  eqnchar(5)).  If nroff(1) is invoked, col(1) is
       automatically used.

   Referring to Other nroff Manual Pages
       If the first line of the nroff manual page is a  reference  to  another
       manual page entry fitting the pattern:

       .so man*/sourcefile

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

       When the second or any subsequent line starts with .so, man ignores it;
       troff(1) or nroff(1) processes the request in the usual manner.

   Processing SGML Manual Pages
       Manual pages are identified as being marked up in SGML by the  presence
       of  the  string  <&lt;!DOCTYPE.  If  the  file  also  contains  the  string
       SHADOW_PAGE, the file refers to another manual page  for  the  content.
       The  reference  is made with a file entity reference to the manual page
       that contains the text. This is similar to the  .so mechanism  used  in
       the nroff formatted man pages.

ENVIRONMENT VARIABLES
       See  environ(5) for descriptions of the following environment variables
       that affect the execution of man: LANG, LC_ALL, LC_CTYPE,  LC_MESSAGES,
       and NLSPATH.

       MANPATH         A  colon-separated  list of directories; each directory
                       can be followed by a comma-separated list of  sections.
                       If  set,  its  value  overrides  /usr/share/man  as the
                       default directory search path, and the man.cf  file  as
                       the  default section search path. The -M and  -s flags,
                       in turn, override these values.)



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



       TCAT            The name of the program to use to display troffed  man-
                       ual pages.



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



EXAMPLES
       Example 1: Creating a PostScript Version of a man page

       The following example creates the pipe(2) man page in postscript:

            % setenv 'TROFF troff -Tpost'
            % setenv TCAT '/usr/lib/lp/postscript/dpost'
            % man -t -s 2 pipe > /tmp/output.ps

       This is an alternative to  using man -t, which sends the  man  page  to
       the  default  printer,  if the user  wants a postscript file version of
       the man page.

       Example 2: Creating a Text Version of a man page

       The following example creates the pipe(2) man page in ascii text:

       man pipe.2 | col -x -b  >  pipe.text

       This is an alternative to  using man -t, which sends the  man  page  to
       the  default printer, if the user  wants a text file version of the man
       page.

EXIT STATUS
       The following exit values are returned:

       0               Successful completion.



       >&gt;0              An error occurred.



FILES
       /usr/share/man

           Root of the standard manual page directory subtree



       /usr/share/man/man?/*

           Unformatted nroff manual entries



       /usr/share/man/sman?/*

           Unformatted  SGML manual entries



       /usr/share/man/cat?/*

           nroffed manual entries



       /usr/share/man/fmt?/*

           troffed manual entries



       /usr/share/man/windex

           Table of contents and keyword database



       /usr/share/lib/tmac/an

           Standard -man macro package



       /usr/share/lib/sgml/locale/C/dtd/*

           SGML document type definition files



       /usr/share/lib/sgml/locale/C/solbook/*

           SGML style sheet and entity definitions directories



       /usr/share/lib/pub/eqnchar

           Standard definitions for eqn and neqn



       man.cf

           Default search order by section



ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).    ATTRIBUTE   TYPEATTRIBUTE  VALUE  AvailabilitySUNWdoc
       CSIEnabled, see NOTES.  Interface StabilityStandard


SEE ALSO
       apropos(1),  cat(1),  col(1),  dpost(1),  eqn(1),  more(1),   nroff(1),
       refer(1),   tbl(1),   troff(1),   vgrind(1),   whatis(1),   catman(1M),
       attributes(5), environ(5), eqnchar(5), man(5), sgml(5), standards(5)

NOTES
       The -f and -k options use the windex database, which is created by cat-
       man(1M).

       The  man command is CSI-capable. However, some utilities invoked by the
       man command, namely, troff, eqn, neqn, refer, tbl, and vgrind, are  not
       verified  to  be CSI-capable. Because of this, the man command with the
       -t option can not handle non-EUC data. Also, using the man  command  to
       display  man  pages  that require special processing through eqn, neqn,
       refer, tbl, or vgrind can not be CSI-capable.

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

       Some dumb terminals cannot process the vertical motions produced by the
       e  (see  eqn(1)) preprocessing flag. To prevent garbled output on these
       terminals, when you use e, also use t,  to  invoke  col(1)  implicitly.
       This  workaround  has  the disadvantage of eliminating superscripts and
       subscripts, even on those terminals that can display them.  <&lt;Control-q>&gt;
       clears a terminal that gets confused by eqn(1) output.



SunOS 5.10                        4 Jun 2004                            man(1)