man(1) — Commands
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 common. You usually specify section to identify a reference page that has the same title as another reference page in a different section.
The suffix parameter is a string of one or more characters, starting with a letter. You usually specify suffix in addition to section to identify a reference page that has the same title as another reference page in the same section.
titleSpecifies 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 pathnameSpecifies an alternative search path. (Performs the same function as -M pathname and is provided for compatibility with other systems.)
-tUses 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 section or specify section without a suffix, the man command sorts reference pages with matching titles according to section alone, and then alphabetically according to suffix. You need to specify suffix in addition to section 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 section, 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:
%LThe current locale name (for example, zh_CN.dechanzi@radical) that is the value of the LC_MESSAGES environment variable
%PThe 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 collating 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.
%lThe language element of the locale name currently assigned to the LC_MESSAGES variable (for example, zh)
%tThe territory element of the locale name currently assigned to the LC_MESSAGES variable (for example, CN)
%cThe 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 formatted 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 formatted 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 command 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 example, 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? directory 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 command 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 format 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 partial pathnames do not start with man?/. For example, a cross-reference file that includes the cat(1) reference page must specify man1 in the pathname:
.so man1/cat.1
Backwards Scrolling in man Displays Requires Preformatted Files
If a matching source reference page exists, but there is no matching preformatted 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 system 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 keyword 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 product 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 provided 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 Equipment Corporation devices as specified in term(4). If your system administrator changes the supplied setting for the nroff lp device, all preformatted 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 device 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 specifying 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 following:
% 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 device 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 boundaries 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 character 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/manStandard 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?/.zPacked formatted reference pages (if any).
/usr/local/manLocation 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/whatisThe standard whatis keyword database maintained by using catman.
/usr/local/man/whatisThe 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).