*** UNIX MANUAL PAGE BROWSER ***

man(1) General Commands Manual man(1) NAME man - Displays reference pages SYNOPSIS man [-] [-M | -P search_path] [-l] {[section[suffix]] title...}... man [-M | -P search_path] -f title ... man [-M | -P search_path] -k keyword ... STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: man: POSIX.2, XPG4, XPG4-UNIX Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. FLAGS [Digital] Does not pipe output through more for display [Digital] De- scribes 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. Locates refer- ence pages whose NAME section contains the specified keyword if the whatis database exists. Performs the same function as the apropos com- mand. You can specify more than one keyword. [Digital] Specifies that the reference page resides in a section directory subordinate to the /usr/local/man area rather than one subordinate to the /usr/share/man or /usr/dt/share/man area. [Digital] Specifies an al- ternative search path. The search_path argument contains one or more pathnames for directories that contain 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, /usr/dt/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 LC_MESSAGES environment variable. [Digital] Specifies an alterna- tive search path. (Performs the same function as -M search_path and is provided for compatibility with other systems.) PARAMETERS [Digital] Specifies the optional section and suffix identifiers for the reference page. [Digital] The section parameter is either a number (0-9), the number/letter combination 1m, or one of the letters C, L, F, n, l, p, or o. The numbers 1 to 8 and the number/letter combina- tion 1m are most appropriate to use with reference pages in- stalled for the DIGITAL UNIX product. You usually specify sec- tion to identify a reference page that has the same title as an- other reference page in a different section. [Digital] The suffix parameter is a string of one or more char- acters, 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. Spec- ifies the name of the reference page. DESCRIPTION The man command provides online access to the system's reference pages. For example, if reference pages are available on your system, the fol- lowing command displays the first screenful of reference information for the ls command: % man ls You can press the space bar to see the next screen or press other keys to control or search the display. For more information, see the subsec- tion entitled "Controlling the Pager Used by the man Command." The industry standards listed in the STANDARDS section specify the man command's exit values and require the command to support the -k flag, one or more title parameters, and certain environment variables. Much of the command's behavior is implementation defined, as indicated by the [Digital] tag that precedes most of the information on this refer- ence page. [Digital] Most reference pages reside in section directories subordi- nate to /usr/share/man. Your system manager can optionally create the /usr/local/man area as a location for site-specific reference pages. In addition, the area for reference pages provided for the Common Desk- top Environment (CDE) is /usr/dt/share/man. When all three areas exist on a system, the default behavior of the man command is to search for reference pages first in /usr/share/man, then in /usr/dt/share/man, and finally in /usr/local/man. [Digital] Within a given reference page area, multiple reference pages can have the same title. Duplicate titles can be encountered across section directories, within section directories, or both. When two ref- erence pages have the same title within a section directory, one or both reference pages include a suffix in the section identifier. [Digital] If you specify only title in the man command, it displays the first title encountered in the section order 1, 8, 6, 2, 3, 4, 5, 7, C, L, F, n, l, p, o, 1m. If there is more than one title in the same section, the reference page without a section suffix has prece- dence over reference pages that have section suffixes. When duplicate titles are encountered with the same section and different suffixes, suffixes are ordered alphabetically. In this case, the reference page whose suffix occurs earliest in alphabetical order has precedence. The section and suffix parameters are available to specify which reference page you want to see when more than one instance of titles is avail- able. [Digital] If you specify section, the man command looks for the speci- fied titles only in the directories for the specified sections. For all number sections and all but one of the letter section identifiers, the command must find the title in a directory that corresponds to the specified section. For example, when you enter the command man 3 printf, the command looks for the printf title only in a man3 direc- tory. 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. [Digital] A section identifier corresponds to a particular category of information and, with the exception of C, to only one corresponding di- rectory. In the following list, an asterisk (*) follows the section de- scription when it applies to reference pages installed for the DIGITAL UNIX product: Not used. Reference pages for commands that all users can enter (*). Reference pages for commands related to system mainte- nance and operation (*, for Common Desktop Environment only). Refer- ence pages for system calls, or program interfaces to the operating system kernel (*). Reference pages for program interfaces found in various libraries (*). Reference pages for include files, program out- put files, and some system files (*). Reference pages on miscellaneous topics, such as text-processing macro packages (*). Reference pages for games. Reference pages for device special files, related driver functions, and networking support (*). Reference pages for commands related to system maintenance and operation (*). Use varies. Refer- ence pages for commands. Reference pages for files. Reference pages for libraries. Reference pages with local (site-specific) information. New reference pages. Old reference pages. Public reference pages. Almost all implementations of a UNIX operating system use reference page sections 4, 5, and 7 to describe different types of files. How- ever, the type of file described in each section varies from one imple- mentation to another. For example, on ULTRIX and some other UNIX imple- mentations, Section 4 describes device special files rather than in- clude files, Section 5 describes include files rather than macro pack- ages, and Section 7 describes macro packages rather than device special files. [Digital] You need to specify section only 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 com- mand displays by default. [Digital] If you specify suffix along with section, the man command looks only for the reference page that has both the specified section and the specified 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 displays by default. For example, if both abort(3) and abort(3f) exist in a man3 di- rectory, the command man 3 abort displays abort(3). In this case, you would need to enter the command man 3f abort to dis- play abort(3f). [Digital] In the man command's default search path are two locations intended for site-specific reference pages: A section directory named manl (l for local) in the /usr/share/man area Section directories sub- ordinate to the /usr/local/man area [Digital] One, both, or neither of these locations may exist on your system. They are created by the system administrator. [Digital] If you include the -l flag in the man command, you specify reference pages in the /usr/local/man area. If you include the l sec- tion identifier, you specify reference pages in a manl section direc- tory. For example, the command man -l 5 print specifies print(5), whose file resides in /usr/local/man/man5. The command man l print specifies print(l), whose file resides in /usr/share/man/manl. [Digital] The man command's section and title arguments can be paired so that a series of titles can be searched for in a section, or multi- ple sections can be searched for one or more titles. Changing the man Command's Search Path [Digital] By default, the man command checks for reference pages first in the /usr/share/man area, then in the /usr/dt/share/man area, and fi- nally in the /usr/local/man area. You can change this behavior by sup- plying a search path with the -M or -P flag or by defining the MANPATH variable. The search path is a colon-separated list of directories in which man expects to find the section subdirectories. The string /usr/share/%L/man:/usr/dt/share/man:/usr/local/man represents the de- fault search path. The default path includes %L, which is one of the following locale directives that can be included in pathnames: The cur- rent locale name (for example, zh_CN.dechanzi@radical) that is the value of the LC_MESSAGES environment variable The same as %L except that the @ suffix is removed if the locale name has such a suffix (for example, zh_CN.dechanzi) A few 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. The language element of the locale name currently assigned to the LC_MESSAGES variable (for example, zh) The territory element of the locale name currently assigned to the LC_MESSAGES variable (for example, CN) The codeset element of the locale name currently assigned to the LC_MESSAGES vari- able (for example, dechanzi) A single percent sign (%) character [Digital] The following search path example changes the order in which reference page areas are searched. It also adds support for installa- tions of reference page translations within the CDE and site-specific areas: % setenv MANPATH /usr/lo- cal/%L/man:/usr/dt/share/%L/man:/usr/share/%L/man Enabling Codeset Conversion of Translated Reference Pages [Digital] The man command can automatically invoke the iconv utility to perform codeset conversion of reference page files. This capability allows you to install one set of reference pages to support locales that have the same language and territory but different codesets, thereby reducing file redundancy on the system. To enable codeset con- version, the following conditions must be met: The LC_MESSAGES locale category of the process running the man command must be set to the lo- cale name to which the reference pages will be converted. The underly- ing iconv utility must have a converter available for the source and destination codesets. Refer to the iconv(1) reference page for more in- formation about codeset converters. An appropriate locale mapping file must exist in the /usr/share directory. A locale mapping file is a hidden file whose name has the format .man_conv-locale_name, where locale_name is a complete locale name that includes the name of the destination codeset. The content of the locale mapping file is the locale with the source codeset for which translated manpages are available. [Digital] For example, after installing DIGITAL UNIX subsets of soft- ware and translated reference pages for Japanese, the eucJP_SJIS code- set converter is installed in the /usr/lib/nls/loc/iconv directory, manpages for the ja_JP.eucJP locale are installed in the /usr/share/ja_JP.eucJP/man directory, and the .man_conv-ja_JP.SJIS file, which contains the ja_JP.ja_JP.eucJP locale name, is moved to the /usr/share directory. When users set locale to ja_JP.SJIS and run the man command, it accesses the reference pages in the /usr/share/ja_JP.eucJP/man directory and converts them to the SJIS codeset for display. Controlling the Pager Used by the man Command [Digital] By default, you can use the following keys to control and navigate the reference page display: Advances the display by one line. Advances the display by one screen. Backs up the display by one half screen. Searches for the first instance of the specified string. Searches for the next instance of the string specified by a preceding /string directive. Stops the display. [Digital] Refer to the more(1) reference page for a complete discus- sion of pager subcommands. [Digital] By default, if the standard output is a teletype and the - (single minus sign) flag is not provided, man uses the more -svf com- mand 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 out- put: If the MORE environment variable is defined, 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 [Digital] A reference page area may or may not contain cat? directo- ries with formatted reference pages. Your system administrator can cre- ate these directories and preformat reference page source files by us- ing 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 com- mand simply displays the preformatted file using the more command or the defined pager. [Digital] If the specified reference page exists only as a source file, the man command processes the file through a pipeline of com- mands. This pipeline includes: [Digital] If the file is compressed, the gunzip command to uncompress the file [Digital] The tbl and neqn commands to preprocess source markup for tables and equations [Digi- tal] The nroff command to create formatted output The more command or an alternative pager command (if defined) to display the file [Digital] 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). [Digital] When processing the reference page through nroff, the man command specifies the -m flag with the name of the macro package de- scribed in man(5). Most DIGITAL UNIX 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. [Digital] The nroff command invoked by man also includes the -Tdevice flag. The value for device differs, depending on whether cat? directo- ries are present when the source file is formatted. When the appropri- ate cat? directory is present and does not contain a formatted version of the reference page, the man command formats source by creating out- put for the nroff lp device. It also saves the formatted output in the cat? directory. If the cat? directory is absent, the man command for- mats a reference page by creating output for the nroff lpr device and does not save the formatted output. [Digital] If a preformatted version of the reference page exists, but the source version is more recent than the preformatted one, the man command does not use the preformatted file. The command formats the source file and replaces the preformatted file with a new version. [Digital] When a specified reference page is not formatted or is being formatted again, the man command displays an appropriate status mes- sage, 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. Reference Pages in Compressed Format [Digital] The man command supports reference page files in either com- pressed or uncompressed format. Compressed files can save a signifi- cant amount of disk space in the file system where reference page sub- sets are installed. The reference page files for the operating system product are installed as created by the gzip command. [Digital] To display a compressed reference page, the man command tem- porarily uncompresses the file by invoking the gunzip utility with the -c flag before invoking other commands to format (if necessary) and display the reference page. [Digital] There are a number of requirements and restrictions that ap- ply to reference pages in compressed format. For more information, re- fer to both the Reference Page Pointers section in this DESCRIPTION and the RESTRICTIONS section. Reference Page Pointers [Digital] Reference page directories can contain cross-reference (pointer) reference pages. Pointers, which invoke another reference page, support those reference page files that contain multiple names in the NAME section. The pointers allow users to invoke a reference page by specifying any of the names in the NAME section, not only the name of the reference page itself. [Digital] The man command supports different kinds of pointers, de- pending on whether reference page files are compressed or uncompressed, source files, or preformatted files. [Digital] When reference page files are compressed (either source files in man? directories or preformatted files in cat? directories), their associated pointers must be implemented as hard links. Further- more, each pointer file name must end with the same compression exten- sion as the file that the pointer invokes. For example, if a reference page was compressed by the gzip command, both the reference page file name and those of its pointers, must end in .gz. [Digital] When uncompressed reference pages reside in cat? directo- ries, pointers are symbolic links to the files that the command dis- plays. When uncompressed reference pages reside in man? directories, pointers are one-line files. The one line is an nroff include direc- tive that has one of the following formats: [Digital] In this case, the man command will reformat the title2 ref- erence page, if necessary, and save the output in the file title2.sec- tion in the appropriate cat? directory, assuming the cat? directory exists. ENVIRONMENT VARIABLES The following environment variables affect the behavior of the man com- mand: Provides a default value for other locale variables when these are unset or null. If set to a non-empty string, overrides the values of all other locale variables, including LANG. Determines the locale for the interpretation of byte sequences as characters in text data. Determines the locale used for text written to standard error or stan- dard output. Determines the root directory for message catalogs con- taining informational, diagnostic, and other messages returned by the command. The NLSPATH value, in combination with the setting of LC_MES- SAGES, specifies the directory in which a locale-specific message cata- log is found. Determines the command (pager) that man invokes to fil- ter output when writing output to a terminal. A default pager must exist and is implementation defined. On DIGITAL UNIX systems, the default pager used by man is the more command. RESTRICTIONS This section contains restrictions that apply to the man command and the files that it processes. Pathnames in Uncompressed Pointer Files Must Start With man? [Digital] The man command changes directory to /usr/share/man, /usr/dt/share/man, /usr/local/man, or to those directories specified with the MANPATH variable, the -M flag, or -P flag. Some reference pages assume this change of directory. Therefore, an attempt to format uncompressed reference pages can fail if any .so directives specifying partial pathnames do not start with man?/. For example, a cross-refer- ence file that includes the cat(1) reference page must specify man1 in the pathname: .so man1/cat.1 Pointers Must Reside in Same Area as Related Files [Digital] The man command does not support cross-references to files outside the current reference page area. For example, a pointer that resides in the /usr/local/man area cannot include or invoke a file that resides in the /usr/share/man area. Compressed Pointers Cannot Be Copied Across File Systems [Digital] A pointer associated with a compressed reference page is a hard link, which is not a file but an alternative entry in a file sys- tem table for a particular file. Hard links cannot be transferred from one file system to another by using commands, such as cp, rcp, or mv. These commands cannot determine which entries in a file system table point to the same file, and so copy the file that is pointed to into the destination area each time a hard link is encountered. Reference pages can have many associated pointers. Therefore, an operation that moves directories of compressed reference pages from one file system to another consumes far more disk space in the destination area than was required in the source area. The cat? Directories May Not Exist [Digital] The .../man/cat? directories are not required. It is the op- tion of the system administrator to create these directories and pre- format 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. Most Commands Cannot Work Directly on Compressed Files [Digital] Most reference page files are installed in compressed for- mat, which means that they cannot be processed directly by most com- mands. However, you can use the gunzip -c (or gzip -u -c) command to uncompress the files and direct the result to standard output for addi- tional processing. [Digital] The following examples search the man8 directory to find reference pages that contain the string "install". For POSIX (including Korn) and Bourne shells: $ cd /usr/share/man/man8 $ for i in *.gz; do > gunzip -c $i | grep 'in- stall' >&- && echo "*** $i" > gunzip -c $i | grep 'install' > done For C shell: % cd /usr/share/man/man8 % foreach i (*.gz) > gunzip -c $i | grep 'in- stall' >/dev/null && echo "*** $i" > gunzip -c $i | grep 'install' > end The whatis Database Is Required for Some Commands [Digital] The man -f (whatis) and man -k (apropos) commands fail un- less a whatis keyword database exists in one or more of the reference page areas in the man command search path. A default whatis database is included in the DIGITAL UNIX product and can be optionally installed by your system administrator. This database is copied to the /usr/share/man directory and includes entries for all the DIGITAL UNIX reference page subsets that are installed on the system. [Digital] The whatis database is not updated automatically when refer- ence pages for layered products and other kinds of optional software are installed. Therefore, your system administrator should rebuild the whatis database after installation of reference pages for optional products by invoking catman with the -w flag. Changing Setting for lp Device Affects Preformatted Reference Pages [Digital] 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 DIGITAL UNIX is set to gener- ate 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 [Digital] 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 % gunzip -c man1/ls.1.gz |tbl |neqn |nroff -Tdevice -man | \ lpr -Pmyprinter [Digital] Replace the device argument with /usr/share/lib/term/tabde- vice, where device is the name of a device listed in term(4). Specify lpr for device when producing output suitable for a lineprinter. For example: % cd /usr/share/man % gunzip -c man1/ls.1.gz |tbl |neqn |nroff -Tlpr -man | \ lpr -Pmyprinter [Digital] 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 [Digital] 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 [Digital] 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 com- mands such as the following: % cd /usr/share/man % gunzip -c man1/ls.1.gz |tbl |neqn |nroff -Tdevice -man -h | more -svf [Digital] Replace the device argument with /usr/share/lib/term/tabde- vice, where device is the name of a device listed in term(4) and is one appropriate for your terminal. Nondefault Tab Settings Can Corrupt man Command Displays [Digital] You can view reference pages only on devices for which de- fault tab boundaries are in effect. [Digital] To format reference page source files, the man and catman commands invoke nroff with the -h flag. This flag causes nroff to sub- stitute 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. [Digital] 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 em- bedded by nroff corrupt reference page displays with inappropriate se- quences 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. EXIT VALUES The man command returns 0 (zero) on success and >0 (greater than zero) on failure. EXAMPLES Display the printf(1) reference page: % man printf [Digital] Display the printf(3) reference page: % man 3 printf [Digital] Display the mgr_helper(8) reference page that you created in a man8 section directory under $HOME/mgr: % man -M $HOME/mgr mgr_helper [Digital] Display reference pages with the title locale in sections 1 and 4: % man 1 locale 4 locale Query the whatis database for reference pages whose NAME sections include the string "core": % man -k core FILES [Digital] Standard location for reference page section directories [Digital] Section directories containing nroff source files for refer- ence pages [Digital] Section directories containing formatted files for reference pages [Digital] Standard location for CDE reference page section directories [Digital] Section directories containing nroff source files for CDE reference pages [Digital] Section directories containing formatted files for CDE reference pages [Digital] Location of section directories for site-specific, or local, reference pages [Digital] Section directories containing nroff source files for local reference pages [Digital] Section directories containing formatted files for local reference pages [Digital] The default whatis keyword database maintained by using catman RELATED INFORMATION Commands: apropos(1), gzip(1), iconv(1), locale(1), more(1), neqn(1), nroff(1), pcat(1), tbl(1), whatis(1), catman(8) Files: man(5), rsml(5) delim off man(1)