man - find and display reference manual pages
Synopsis
Description
Manual Structure
Configuration
Environment Variables
Files
See Also
man [-] [-M path] [-T macro-package] [-adlptw] [-m system] [-s section] [[section] title . . .] title . . .man [-M path] -k keyword . . .
man [-M path] -f file . . .
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:
-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. -k keyword Prints one-line summaries matching any of the given keywords. This also needs a windex database. -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. -t If an entry is in troff(1) source format, it is preformatted for a typesetter instead of a terminal. -T macset Use the specified troff(1) macro package instead of the standard -man set. The following options are accepted as extensions: -a Finds and displays all entries for each given title, not just the first one. -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. -l Lists the titles of all matching entries instead of manual page contents. -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. -p Prints debugging messages instead of the formatted manual page. -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. -w Prints the full path name of the respective manual page(s) instead of their contents.
The manual is divided into eight sections: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 binary programs). These directories are usually searched automatically by the command interpreter, see sh(1).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
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.The description subsection discusses in detail the subject at hand.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 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.
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.
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.
/etc/default/man Configuration file.
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)
| Heirloom Toolchest | MAN (1) | 2/5/05 |