Sccsid @(#)man.1 1.18 (gritter) 2/5/05
 Parts taken from intro(0), Unix 7th edition:
 Copyright(C) Caldera International Inc. 2001-2002. All rights reserved.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 Redistributions of source code and documentation must retain the
 above copyright notice, this list of conditions and the following
 disclaimer.
 Redistributions in binary form must reproduce the above copyright
 notice, this list of conditions and the following disclaimer in the
 documentation and/or other materials provided with the distribution.
 All advertising materials mentioning features or use of this software
 must display the following acknowledgement:
 This product includes software developed or owned by Caldera
 International, Inc.
 Neither the name of Caldera International, Inc. nor the names of
 other contributors may be used to endorse or promote products
 derived from this software without specific prior written permission.

 USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
 INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 ARE DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE
 LIABLE FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 MAN 1 "2/5/05" "Heirloom Toolchest" "User Commands"
 NAME
man - find and display reference manual pages

 SYNOPSIS

man [-] [-M path]
[-T macro-package] [-adlptw]
[-m system]
[-s section]
[[section] title . . .]
title . . .


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


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



 DESCRIPTION
The
 man command shows information from the system reference manuals.
For each given
 title , the manual path is searched for the first matching entry,
which is formatted if appropriate.
When printing to a terminal,
or if the
 - flag is given, the
 man command will invoke a pager to display the documentation,
else,
 cat (1) is used.


The
 section argument, if present,
restricts the search to the given section of the manual.
 section consists of a single digit,
optionally followed by a single letter,
or one of
 new ,  local ,  old , or
 public . Multiple
 section arguments may be present in the argument list,
each applies to the 
 titles positioned behind.


The
 man command accepts the following options:

 12
 -f  file Searches for manual entries related to the given
 files and print one-line summaries of them.
Only the basename component of each
 file is used.
A
 windex database as created by the
 catman (8) command must exist for this operation.

 12
 -k  keyword Prints one-line summaries matching any of the given
 keywords . This also needs a
 windex database.

 12
 -M  path Uses the given
 path as the manual search path, overriding both the configuration file
and the environment. The format of this path is described below.

 12
 -t If an entry is in
 troff (1) source format, it is preformatted for a typesetter instead of a terminal.

 12
 -T  macset Use the specified
 troff (1) macro package instead of the standard
 -man set.


The following options are accepted as extensions:

 12
 -a Finds and displays all entries for each given
 title , not just the first one.

 12
 -d Uses a file name relative to current directory as the location
of the manual page
instead of searching in the manual search path.
The complete file name of a manual page source in troff format
must be specified with this option
instead of the page title.

 12
 -l Lists the titles of all matching entries instead of manual page
contents.

 12
-m system
For each entry in the manual search path,
a directory named
 system below it is searched for manual pages.
Thus to make the manual pages of other systems accessible,
they can be put into separate subdirectories
within the system default manual directory.

 12
 -p Prints debugging messages instead of the formatted manual page.

 12
 -s  section Provides an alternate method to restrict the search
to specific sections of the manual.
This is useful if the section name
would otherwise be interpreted as a page name.
Multiple section names may be specified, separated by commas;
the order in which matches are displayed is not necessarily the
one given at this point.

 12
 -w Prints the full path name of the respective manual page(s)
instead of their contents.

 "Manual Structure"
The manual is divided into
eight sections:


1. User commands


2. System calls


3. Subroutines


4. Special files


5. File formats and conventions


6. Games


7. Macro packages and language conventions


8. Maintenance commands


Commands are programs intended to be invoked directly by
the user, in contradistinction to subroutines, which are
intended to be called by the user's programs.
Commands generally reside in a directory
 .\|.\|.\|/bin (for
 bin \|ary programs).
These directories are usually searched automatically
by the command interpreter, see
 sh (1). 

System calls are entries into the
kernel.
Every system call has one or more C language interfaces
described in section 2.


An assortment
of subroutines is available;
they are described in section 3.
The primary libraries in which they are kept are described in
 intro (3). The functions are described in terms of C, but most will
work with Fortran as well.


The special files section 4 discusses the characteristics of
each system `file' that actually refers to an I/O device.
The names in this
section may refer to the manufacturer device names for the
hardware,
instead of the names of
the special files themselves.


The file formats and conventions section 5 documents the structure of particular
kinds of files; for example, the form of the output of the loader and
assembler is given. Excluded are files used by only one command,
for example the assembler's intermediate files.


Games have been relegated to section 6 to keep them from contaminating
the more staid information of section 1.


Section 7 is a miscellaneous collection of information necessary to
writing in various specialized languages:
character codes, 
macro packages for typesetting,
etc.


The maintenance 
section 8 discusses procedures not intended
for use by the ordinary user.
These procedures often involve use of commands
of section 1, where an attempt has been made to
single out peculiarly maintenance-flavored commands
by marking them 1M.


Each section consists of a number of independent
entries of a page or so each.
The name of the entry is in the upper corners of its pages,
together with the section number, and sometimes a
letter characteristic of a subcategory, e.g. graphics is 1G,
and the math library is 3M.


All entries are based on a common format,
not all of whose subsections will always appear.




The
 name subsection lists the exact names of the commands and subroutines
covered under the entry and gives
a very short description of their purpose.


The
 synopsis "" summarizes the use of the
program being described.
A few conventions are used, particularly in the
Commands subsection:




 Boldface words are considered literals, and
are typed just as they appear.


Square brackets [ ] around an argument
indicate that the argument is optional.
When an argument is given as `name', it always
refers to a file name.


Ellipses `.\|.\|.' are used to show that the previous argument-prototype
may be repeated.


A final convention is used by the commands themselves.
An argument beginning with a minus sign `-'
is often taken to mean some sort of option-specifying argument
even if it appears in a position where a file name
could appear. Therefore, it is unwise to have files
whose names begin with `-'.




The
 description "" subsection discusses in detail the subject at hand.


The
 files "" subsection gives the names of files which are
built into the program.


A
 see also subsection gives pointers to related information.


A
 diagnostics subsection discusses
the diagnostic indications which may be produced.
Messages which are intended to be self-explanatory
are not listed.


The
 bugs "" or
 notes "" subsection gives remarks,
known bugs and sometimes deficiencies.
Occasionally also the suggested fix is
described.



 Configuration
The
 man command reads the configuration file
 /etc/default/man on startup. Lines containing the following strings are interpreted:


 MANPATH= path Sets the manual search path, formatted as a colon-separated list of
directories.
The default is
 /usr/local/share/man:/usr/share/man . 

 TROFF= command This command is invoked if the
 -t option is given, usually
 troff . 

 NROFF= command Sets the command used to preformat manual pages for a terminal,
defaults to
 "nroff -Tlp" . 

 EQN= command The eqn command for formatting mathematics on a typesetter, normally
 eqn . 

 NEQN= command The neqn command for formatting mathematics on a terminal, normally
 neqn . 

 TBL= command The tbl command for formatting tables, usually
 tbl . 

 REFER= command The refer command for formatting bibliographic references,
usually
 refer . 

 VGRIND= command The vgrind command for formatting program listings,
normally
 vgrind . 

 MACSET= macro-package The
 troff (1) macro set to be used, normally
 -man . 

 COL= command The command used to filter
 nroff (1) output, normally
 col (1) with the option
 -x . 

 PAGER= command The pager command that is used to display pages on a terminal instead of
 pg . 

 TCAT= command Used to display pages if the
 -t option is present, defaults to
 cat . 

In addition, each directory within the manual search path may contain
a file named
 man.cf with the following content:


 MANSECTS= sections Section search order for this directory. Multiple section names may
be specified, separated by commas.


If no
 man.cf file is present, sections are searched in lexicographical order.

 "ENVIRONMENT VARIABLES"
If any of the strings described in the global configuration file format
above is present within the environment, the latter setting is used.


 MANPATH If the value of this variable contains the string
``::'',
the manual path specified in the configuration file is
inserted at this point.

 FILES

 /etc/default/man Configuration file.

 "SEE ALSO"
apropos(1),
cat(1),
col(1),
eqn(1),
nroff(1),
pg(1),
refer(1),
tbl(1),
troff(1),
vgrind(1),
whatis(1),
man(7),
catman(8)