catman - Creates or rebuilds formatted reference pages and the whatis data-
/usr/sbin/catman [-M search_path] [-cnpvw] [section...]
Creates formatted versions of reference pages only in the set of direc-
tories specified by search_path. The search_path argument has the form
of a colon-separated list of directory names. The default search path
(assuming MANPATH has not been set) is the following:
The -M option, unlike the MANPATH setting, overrides the default place-
ment of the whatis database (in /usr/share/man). When the -M option is
included in a command that builds the whatis database, catman creates
the database in the first directory included in search_path.
Refer to the man(1) reference page for more information on the MANPATH
variable. See DESCRIPTION for a list of locale directives that can be
included in search_path.
-c Uses the gzip command to compress preformatted output files. The -c
option has no effect when used with the -w option.
-n Prevents creation of the whatis database.
-p Displays what would be done instead of doing it.
-v Displays the name of each reference page file as it is being processed.
-w Causes only the whatis database to be created. No reformatting is
Specifies one or more reference page sections whose corresponding
directories are to be searched for files. If you do not specify this
parameter, the command searches for reference page source files in all
section directories encountered in its search path.
The section operand affects creation of preformatted files, not the
whatis database. The catman command always searches all section direc-
tories in its search path when creating the whatis database.
The catman command creates formatted versions of the online reference pages
from the nroff source files. The command also creates from the NAME entries
in source files the whatis database that is used by the whatis and apropos
When catman is invoked, each reference page is examined and those whose
preformatted versions are missing or out of date are created by nroff using
the -man macro package. See man(5).
An argument not starting with a - (single minus sign) is assumed to be a
list of the reference sections to look in. If you do not specify a list,
catman formats all reference pages in the search path. In general, sec-
tions are referenced by a single digit in the range 1 through 8. But, you
can use any section allowed by the man command. The list of sections is
applied to all reference page areas in the search path.
If a .../man/cat? directory does not exist for a section, catman creates
The command recognizes and appropriately processes either compressed or
uncompressed source files. By default, the command creates formatted files
in uncompressed form; however, you can specify the -c option to direct cat-
man to compress its output files. When catman processes an uncompressed
source file, any corresponding pointers are generated as symbolic links.
When catman processes a compressed source file, any corresponding pointers
are generated as hard links. Refer to man(1) for more information, includ-
ing restrictions, that apply to pointers and compressed files.
A reference page source file can include a multicharacter 7-bit ASCII sub-
section suffix appended to its name, following the section character. The
subsection suffix, if it exists, must start with a letter. The formatted
reference page file also includes the subsection suffix in its name.
The catman command assumes that reference page source files can contain
unprocessed tables and equations. Therefore, it automatically processes
source files through tbl and neqn before invoking nroff. When catman
processes a compressed file, the command automatically executes the gunzip
-c command to uncompress the file before piping output to the other com-
Processing reference pages always invokes nroff with the -Tlp option to
format output for the term(4) lp device. See RESTRICTIONS for information
appropriate for printers and some display devices.
When you view preformatted reference page files directly with the more com-
mand, you should invoke more with the -svf options. The vf options ensure
that the pages display properly in cases where the nroff lp device driver
generates special device control codes.
The following locale directives can be included in the pathnames in
%L The current locale name, for example, ja_JP.eucJP, that is defined for
the LC_MESSAGES environment variable.
%P The same as %L except that any "@" modifier on the locale name is
%l The language element of the current locale name, for example, ja.
%t The territory element of the current locale name, for example, JP.
%c The codeset element from the current locale name, for example, eucJP.
%% A single % (percent sign) character.
These directives allow catman to use the current locale setting to find
translated source files and create translated output files in an
appropriate and predictable location. Refer to the i18n_intro(5)
reference page for more information about locales and associated
The following subsections discuss restrictions associated with both catman
and its input and output files.
Reference Page Pointers
Refer to man(1) for introductory information on reference page pointers and
general pointer restrictions.
When processing reference page files, the catman command changes its direc-
tory to each reference page area in the search path. Some reference pages
assume this change of directory. Therefore, an attempt to format
uncompressed reference pages can fail if any .so directives specifying par-
tial pathnames do not start with man?/.
Optional Section Directories
The /usr/share/man/man? directories for sections C, L, F, n, l, p, o, and 0
are optional. Only your system administrator can create them. Once they
are created, however, catman will create the corresponding .../man/cat?
directories whenever it receives a request to format reference pages in one
of those sections.
The whatis Database
The whatis (man -f) and apropos (man -k) commands fail unless the whatis
database exists in the /usr/share/man directory or, if the command includes
the -M option, in the search path specified with that option.
The operating system can optionally install a /usr/share/man/whatis file
that is useful during system configuration tasks. However, you must
recreate this file manually if you install reference pages that are not
included in subsets for the operating system product; otherwise, entries
for the additional reference pages are not included in the whatis database.
You create or recreate the whatis file when you invoke catman without
specifying the -n option. You can also specify the -w option to create the
whatis file without creating or updating preformatted reference pages in
the cat? directories.
An update installation procedure or a setld command that processes refer-
ence page subsets for the operating system itself may selectively remove or
add specific whatis database entries to help keep the database up to date.
However, this feature is of limited use in making sure that the whatis
database remains current with respect to the reference pages that are actu-
ally available on the system. As already mentioned, selective update is
not supported by most of the optional software products that can load
reference pages to the system. Furthermore, selective update has database
location dependencies. For selective update to work, the whatis entries for
all operating system product reference pages (including those for CDE) must
reside in /usr/share/man/whatis. In other words, automatic and selective
revision of the whatis database does not work correctly if the whatis data-
base is rebuilt in a directory other than /usr/share/man or if the system
administrator creates a CDE-specific whatis database in the
Therefore, do not rely on automatic update of the whatis database to ensure
that its entries reflect the current set of reference pages installed on
the system. It is strongly recommended that you always use the catman
command to manually rebuild the database as the last task following a com-
pleted series of software product installations.
Default Formatting Is Not Appropriate for All Devices
The catman command formats reference pages for the nroff lp device. The lp
device driver, as supplied by the operating system, is set to generate out-
put for Compaq Computer Corporation video terminals, but not for all
printers or third-party terminals. If your system administrator changes the
supplied setting for the lp device, all preformatted reference page files
created by man or catman should be deleted and then reformatted for the new
Preformatted reference pages may not be in a format suitable for printing
on your hardcopy printers. To format a reference page for a specific
printer, move to the reference page area and issue a command such as the
% cd /usr/share/man
% gunzip -c man1/ls.1.gz |tbl |neqn |nroff -Tdevice -man -h | lpr \
Replace the device argument with /usr/share/lib/term/tabdevice, where dev-
ice is the name of a device listed in term(4). The lpr device setting,
because it supports primitive line printers, is least likely to cause prob-
lems that are related to escape sequences that the device cannot handle.
On the other hand, if the reference page has tables and the device is not
capable of reverse line movements, column entries intended to be in the
same row may not align correctly.
Preformatted reference pages also might not be in a format suitable for
display on video terminals from other vendors. To format a reference page
for a specific display device, move to the reference page directory and
issue a command such as the following:
% cd /usr/share/man
% gunzip -c man1/ls.1 |tbl |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).
>>0 An error occurred.
1. To create or update compressed preformatted files for reference pages
and also create or rebuild the whatis database, enter:
2. To create uncompressed preformatted files only for sections 1, 2, and
This command also creates or rebuilds the whatis database. The new
database contains entries for reference pages in all sections (not
just 1, 2, and 3) that are found in the search path.
3. To create or rebuild the whatis database without creating or updating
formatted files, enter:
4. To create compressed preformatted files for all reference pages in the
search path but not rebuild the whatis database, enter:
catman -c -n
Main reference page area
Directories containing source files for most reference pages
Directories containing preformatted files for most reference pages
Reference page area for the Common Desktop Environment (CDE)
Directories containing source files for CDE reference pages
Directories containing preformatted files for CDE reference pages
Local (site-specific) reference page area
Directories containing source files for local reference pages
Directories containing preformatted files for local reference pages
The whatis database created or modified by catman unless the -M option
Command script to make the whatis database
Program used by the mkwhatis command to extract data from reference
Commands: man(1), neqn(1), nroff(1), tbl(1)
Files: term(4), man(5), rsml(5)