man(1)								       man(1)



NAME

  man - Displays reference pages

SYNOPSIS

  man [-] [-M | -P pathname] [-t] [ section[suffix] ] title ...

  man [-] [-M | -P pathname] [-t] [ section[suffix] title ...]...

  man [-M | -P pathname] pathname] -f title ...

  man [-M | -P pathname] -k keyword ...

PARAMETERS

  section[suffix]
	  Specifies the section and optional suffix identifiers for the
	  reference page

	  The section parameter is either a number (0-9) or one of the
	  letters C, L, F, n, l, p, or o.  The numbers 1 to 8 are most com-
	  mon. You usually specify section to identify a reference page that
	  has the same title as another reference page in a different sec-
	  tion.

	  The suffix parameter is a string of one or more characters, start-
	  ing with a letter. You usually specify suffix in addition to sec-
	  tion to identify a reference page that has the same title as
	  another reference page in the same section.

  title	  Specifies the name of the reference page.

FLAGS

  -	  Does not pipe output through more for display

  -f title ...
	  Describes the specified command, call, function, or file name if
	  the whatis keyword database exists.  Performs the same function as
	  the whatis command.  You can specify more than one title.

  -k keyword ...
	  Locates reference pages whose NAME section contains the specified
	  keyword if the whatis database exists.  Performs the same function
	  as the apropos command.  You can specify more than one keyword.

  -M pathname[:pathname]...
	  Specifies an alternative search path. The pathname argument must be
	  the pathname of a directory that contains section directories
	  (directories named man1, man2, man3, and so forth) where reference
	  pages reside.	 Use a colon (:) to separate multiple pathnames. By
	  default, the man command searches for section directories in
	  /usr/share/locale_name/man (if it exists), /usr/share/man, and
	  /usr/local/man (if it exists) in that order.	The
	  /usr/share/locale_name/man directory is created when reference page
	  translations for a particular locale are installed. The man command
	  determines locale_name from the setting of the LANG environment
	  variable.

  -P pathname
	  Specifies an alternative search path.	 (Performs the same function
	  as -M pathname and is provided for compatibility with other sys-
	  tems.)

  -t	  Uses troff instead of nroff to format the reference page if troff
	  is available on your system.

DESCRIPTION

  The man command provides online access to the system's reference pages,
  which usually reside in section directories subordinate to /usr/share/man.
  Your system manager can optionally create the /usr/local/man area as a
  location for site-specific reference pages.  When the /usr/local/man area
  exists, the default behavior of the man command is to search for reference
  pages first in the /usr/share/man area and then in the /usr/local/man area.

  If you specify section, the man command looks for the specified titles only
  in the directories for the specified sections. The exception to this rule
  is that if you specify the section as the number 1 or letter C, the man
  command searches sections C, n, l, p, o, and 1 in that order.	 When you do
  not include section, the command searches sections in the order 1, 8, 2, 3,
  4, 5, 6, 7, C, L, F, n, l, p, o.  You need to specify section if either of
  the following conditions is true:

    +  The reference page is in section 0 or 9.

    +  There are two reference pages with the same name (title) in different
       sections and the reference page you want to see is not the one that
       the man command will find first.

  If you also specify suffix, the man command looks only for reference pages
  whose section identifier includes the specified suffix.  If you omit sec-
  tion or specify section without a suffix, the man command sorts reference
  pages with matching titles according to section alone, and then alphabeti-
  cally according to suffix. You need to specify suffix in addition to sec-
  tion only when both of the following conditions are true:

    +  There is more than one reference page with the same title in the same
       section

    +  The reference page you want to see is not the one that the man command
       will find first.

       For example, if both abort(3) and abort(3f) reside in section 3, the
       command man 3 abort displays abort(3). In this case, you need to enter
       the command man 3f abort to display abort(3f).

  If you specify the lowercase letter l by itself or followed by a letter
  suffix, you identify reference pages in section l (for local). This sec-
  tion, which can be created by your system manager in the /usr/share/man
  area, is an alternative to creating an entirely separate location
  (/usr/local/man) for site-specific reference pages.  To identify a section
  of reference pages in the /usr/local/man area, you specify the letter l
  with a number. For example, the command man l print results in a search for
  the print(l) reference page; however, the command man l5 print results in a
  search for a print(5) reference page that resides in /usr/local/man/man5.


  The section and title arguments can be paired so that a series of pages can
  be searched for in a section or multiple sections can be searched for a
  page or pages.



  Changing the man Command's Search Path


  By default, the man command checks in standard areas (first in
  /usr/share/man and then /usr/local/man) for reference information.  You can
  change this behavior by supplying a search path with the -M or -P flag.
  The search path is a colon-separated list of directories in which man
  expects to find the section subdirectories (for example,
  /usr/share/%L/man:/usr/local/man represents the default search path).	 This
  search path can also be set by defining the MANPATH environment variable.
  When you set the search path using the -P flag, the -M flag, or the MANPATH
  variable, you can include the following directives in pathname to be
  replaced by the associated locale value:

  %L	    The current locale name (for example, zh_CN.dechanzi@radical)
	    that is the value of the LC_MESSAGES environment variable

  %P	    The same as %L except that the @ suffix is removed if the locale
	    name has such a suffix (for example, zh_CN.dechanzi)

	    Some locales have one or more variants to support different col-
	    lating orders and these variants include an @ suffix.  Users may
	    assign a locale variant name to the LANG or LC_ALL variable
	    rather than specifically to the LC_COLLATE variable. In this
	    case, the LC_MESSAGES variable would inherit its value from the
	    LANG or LC_ALL variable. The %P ensures that the man command does
	    not expect to find a reference page directory whose name includes
	    the @ suffix.

  %l	    The language element of the locale name currently assigned to the
	    LC_MESSAGES variable (for example, zh)

  %t	    The territory element of the locale name currently assigned to
	    the LC_MESSAGES variable (for example, CN)

  %c	    The codeset element of the locale name currently assigned to the
	    LC_MESSAGES variable (for example, dechanzi)

  %%	    A single percent sign (%) character

  The following search path reverses the order of pathnames in the default
  search path and also allows reference page translations for different
  locales to reside in the site-specific area:

       % setenv MANPATH /usr/local/%P/man:/usr/share/%P/man

  Controlling the Pager Used by the man Command


  By default, if the standard output is a teletype and the - (single minus
  sign) flag is not provided, man uses the more -svf command to display for-
  matted output.  The -vf flags are present in case the lp nroff device
  driver generates special device control codes.  The following conditions
  also affect how the man command displays output:

    +  If the MORE environment variable is defined, the the man command uses
       the defined command line in place of more -svf.	If the -v and -f
       flags are missing, reference pages may not display properly.

    +  If another pager is defined for the PAGER environment variable, the
       man command uses that pager in place of the more command.

  Formatted Reference Pages



  A reference page area may or may not contain cat? directories with format-
  ted reference pages. Your system administrator can create these directories
  and preformat reference page source files by using the catman command (see
  catman(8)).  The man command checks to see if a preformatted version of a
  reference page exists and, if it does and has a more recent date than the
  corresponding source file, the command simply displays the preformatted
  file using the more command or the defined pager.

  If the specified reference page exists only as a source file, the man com-
  mand processes the file through a pipeline of commands.  This pipeline
  includes:

    +  The tbl and neqn commands to preprocess source markup for tables and
       equations

    +  The nroff command to create formatted output

    +  The more command or an alternative pager command (if defined) to
       display the file

       This last step does not occur if you specify the - flag on the man
       command line or if standard output is not a teletype device (for exam-
       ple, if you pipe man command output to another command or redirect it
       to a file).

  When processing the reference page through nroff, the man command specifies
  the -m flag with the name of the macro package described in man(5).  Most
  DEC OSF/1 reference pages require not only this macro package but also
  those described in rsml(5). The additional macro packages are applied using
  .so entries in the reference page source files and not through the  nroff
  command line invoked by the man command.

  The nroff command invoked by man also includes the -Tdevice flag. The value
  for device differs, depending on whether cat? directories are present or
  absent when the source file is formatted.  When the appropriate
  /usr/share/man/cat?, /usr/local/man/cat?, or $MANPATH/cat? directory is
  present and does not contain a formatted version of the reference page, the
  man command formats source by creating output for the nroff lp device.  It
  also saves the formatted output in the cat? directory. If the cat? direc-
  tory is absent, the man command formats a reference page by creating output
  for the nroff lpr device and does not save the formatted output.

  If the specified reference page is preformatted, but the source also exists
  and is more recent than the preformatted file, the man command does not use
  the preformatted file. The command formats the source file and replaces the
  preformatted file with a new version.

  When a specified reference page is not formatted or is being formatted
  again, the man command displays an appropriate status message, unless the
  standard output is not a teletype device. For example, the status message
  is not displayed when output from the man command is redirected to a file
  or piped to another command.

  Cross-Reference Files


  If the source file for the specified reference page exists and the first
  line of the file is one of the following two lines, the man command
  displays the title2 reference page, assuming it exists:

  .so man?/title2.section

  .soman?/title2.section

  The man command will reformat the title2 reference page, if necessary, and
  save the output in the file title2.section in the appropriate cat?
  directory, assuming the cat? directory exists.  Reference page files that
  contain a .so line to include another file are are known as cross-
  reference, or pointer, files. They exist to support reference pages that
  list multiple commands, functions, or files in the NAME line.

  Reference Pages in Packed Format


  If the specified reference page is available only as a preformatted file in
  the cat? directory and is stored in a "packed" format (a .z file created by
  the pack command), the man command unpacks the file by using the pcat com-
  mand and displays the unpacked output using more or the default pager.  The
  unpacked output is not saved.

  Using the pack command to reduce the size of preformatted reference page
  files is an option of the system administrator. In order for the packed
  preformatted files to be used by the man command, the corresponding source
  files must be deleted.  The man command does not recognize a reference page
  source file in packed format and ignores a preformatted file in packed for-
  mat when the corresponding source file is present.

RESTRICTIONS

  This section contains restrictions that apply to the man command and the
  files that it processes.

  Pathnames in Cross-Reference Files Must Start With man?


  The man command changes directory to /usr/share/man, /usr/local/man, or any
  directories specified with the -M or -P flag or the MANPATH variable.	 Some
  reference pages assume this change of directory.  Therefore, an attempt to
  format some reference pages can fail if any .so directives specifying par-
  tial pathnames do not start with man?/.  For example, a cross-reference
  file that includes the cat(1) reference page must specify man1 in the path-
  name:

       .so man1/cat.1

  Backwards Scrolling in man Displays Requires Preformatted Files


  If a matching source reference page exists, but there is no matching pre-
  formatted reference page and the appropriate man/cat? directory does not
  exist, nroff will format the source file, but you will not be able to
  scroll backwards in the display.

  Directories for Optional Sections May Not Exist

  The /usr/share/man/man? directories for sections C, L, F, n, l, p, o, 0,
  and 9 are optional.  Only your system administrator can create them.

  The cat? Directories May Not Exist


  The .../man/cat? directories are not required. It is the option of the sys-
  tem administrator to create the directories and preformat reference page
  source files using the catman command.  If you are creating reference pages
  to be installed on multiple systems, be sure to supply the files in source
  file format so they can reside in the man? directories.

  The whatis Database Is Required for Some Commands


  The man -f (whatis) and man -k (apropos) commands fail unless a whatis key-
  word database exists for one of the reference page areas in the man command
  search path.	A default whatis database is included in the DEC OSF/1 pro-
  duct for the /usr/share/man area and can be optionally installed by your
  system administrator.	 Your system administrator can update the whatis
  database after installation of layered product reference pages by invoking
  catman with the -w flag.

  The troff Formatter Is Not Provided


  Using the -t flag requires the installation of a troff formatter not pro-
  vided by Digital.  Digital makes no guarantees about using such software.

  Changing Setting for lp Device Affects Preformatted Reference Pages


  When cat? directories are present, source reference pages are formatted for
  the nroff lp device rather than the nroff lpr device.	 The nroff lp device
  driver supplied with DEC OSF/1 is set to generate output for Digital Equip-
  ment Corporation devices as specified in term(4).  If your system adminis-
  trator changes the supplied setting for the nroff lp device, all preformat-
  ted reference page files created by man or catman should be deleted and
  reformatted for the new setting.

  Preformatted Reference Pages May Not Be Suitable for Printing


  Preformatted reference pages may not be in a format suitable for printing
  on your hardcopy printers because of embedded control characters that the
  printers do not recognize.  To format a reference page for a specific
  printer, move to the reference page directory and issue commands such as
  the following:

       % cd /usr/share/man
       % tbl man1/ls.1 |neqn |nroff -Tdevice -man | lpr -Pmyprinter

  Replace the device argument with /usr/share/lib/term/tabdevice, where dev-
  ice is the name of a device listed in term(4).  Specify lpr for device when
  producing output suitable for a lineprinter.

  When cat? directories are absent, the man command invokes nroff by specify-
  ing the lpr device. In this case, you can usually pipe man command output
  directly to a printer or redirect the output to a file that you can print.
  For example:

       % man 1 ls | lpr -Pmyprinter
       % man 1 ls > ~harry/ls.1.txt

  If the reference page has tables and the hardcopy device is not capable of
  reverse line movements, the reference page may not print properly. There is
  no workaround for this problem.

  Non-Digital Terminals May Not Display Preformatted Files Correctly


  Preformatted reference pages may not be in a format suitable for display on
  non-Digital terminals.  To format a reference page for a specific terminal,
  move to the reference page directory and issue commands such as the follow-
  ing:


       % cd /usr/share/man
       % tbl man1/ls.1 |neqn |nroff -Tdevice -man -h | more -svf

  Replace the device argument with /usr/share/lib/term/tabdevice, where dev-
  ice is the name of a device listed in term(4) and is one appropriate for
  your terminal.

  DEC OSF/1 contains no nroff support for non-Digital terminals or printers.

  Nondefault Tab Settings Can Corrupt man Command Displays


  You can view reference pages only on devices for which default tab boun-
  daries are in effect.

  To format reference page source files, the man and catman commands invoke
  nroff with the -h flag. This flag causes nroff to substitute a a tab char-
  acter for each string of one or more spaces that ends on a default tab
  boundary. This operation reduces the number of characters sent to devices
  for printing or display and also reduces the size of files saved in the
  cat? directories.

  Default tab boundaries are set after every eight character positions.	 If
  nondefault tab boundaries have been set on the device or system on which
  reference pages are displayed, the tab characters embedded by nroff corrupt
  reference page displays with inappropriate sequences of spaces. If you
  encounter this problem after using the man command, enter the command tabs
  (to restore default tab boundaries on your display device) and then enter
  the man command again.

EXAMPLES

   1.  Display the printf(1) reference page:


	    % man printf

   2.  Display the printf(3) reference page:


	    % man 3 printf

   3.  Display the mgr_helper(8) reference page that you created in a man8
       section directory under $HOME/mgr:


	    % man -M $HOME/mgr mgr_helper

   4.  Display reference pages with the title locale in sections 1 and 4:


	    % man 1 locale 4 locale

   5.  Query the whatis database for reference pages whose NAME sections
       include the string "core:"


	    % man -k core

FILES

  /usr/share/man
	       Standard location for reference page section directories.

  /usr/share/man/man?
	       Section directories containing nroff source files for
	       reference pages.

  /usr/share/man/cat?
	       Section directories containing formatted files for reference
	       pages.

  /usr/share/man/cat?/.z
	       Packed formatted reference pages (if any).

  /usr/local/man
	       Location of section directories for site-specific, or local,
	       reference pages.

  /usr/local/man/man?
	       Section directories containing nroff source files for local
	       reference pages.

  /usr/local/man/cat?
	       Section directories containing formatted files for local
	       reference pages.

  /usr/share/man/whatis
	       The standard whatis keyword database maintained by using cat-
	       man.

  /usr/local/man/whatis
	       The local whatis keyword database created and maintained by
	       using catman.

RELATED INFORMATION

  Commands:  apropos(1), locale(1), more(1), neqn(1), nroff(1), pcat(1),
  tbl(1), whatis(1), whereis(1), catman(8).

  Files:  man(5), rsml(5).