catman(8)catman(8)NAMEcatman - Creates or rebuilds formatted reference pages and the whatis
database
SYNOPSIS
/usr/sbin/catman [-M search_path] [-cnpvw] [section...]
OPTIONS
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:
/usr/share/man:/usr/dt/share/man:/usr/local/man
The -M option, unlike the MANPATH setting, overrides the default
placement of the whatis database (in /usr/share/man). When the
-M option is included in a command that builds the whatis data‐
base, 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 direc‐
tives that can be included in search_path. Uses the gzip com‐
mand to compress preformatted output files. The -c option has no
effect when used with the -w option. Prevents creation of the
whatis database. Displays what would be done instead of doing
it. Displays the name of each reference page file as it is
being processed. Causes only the whatis database to be created.
No reformatting is done.
OPERANDS
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 directories in its search path when creating the whatis
database.
DESCRIPTION
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 commands.
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 gen‐
eral, sections 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 cre‐
ates the directory.
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 catman 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, including restrictions, that apply to pointers and
compressed files.
A reference page source file can include a multicharacter 7-bit ASCII
subsection suffix appended to its name, following the section charac‐
ter. 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 pro‐
cesses 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 commands.
Processing reference pages always invokes nroff with the -Tlp option to
format output for the term(4) lp device. See RESTRICTIONS for informa‐
tion appropriate for printers and some display devices.
When you view preformatted reference page files directly with the more
command, 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
search_path: The current locale name, for example, ja_JP.eucJP, that is
defined for the LC_MESSAGES environment variable. The same as %L
except that any “@” modifier on the locale name is removed. The lan‐
guage element of the current locale name, for example, ja. The terri‐
tory element of the current locale name, for example, JP. 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 environment variables.
RESTRICTIONS
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
directory to each reference page area in the search path. Some refer‐
ence pages assume this change of directory. Therefore, an attempt to
format uncompressed reference pages can fail if any directives specify‐
ing partial 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 ref‐
erence 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 com‐
mand 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; other‐
wise, 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 ref‐
erence page subsets for the operating system itself may selectively
remove or add specific whatis database entries to help keep the data‐
base up to date. However, this feature is of limited use in making
sure that the whatis database remains current with respect to the ref‐
erence pages that are actually 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. Fur‐
thermore, 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 revi‐
sion 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 sys‐
tem administrator creates a CDE-specific whatis database in the
/usr/dt/share/man directory.
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 completed 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 gener‐
ate output for Hewlett-Packard Company 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 lp device.
Preformatted reference pages may not be in a format suitable for print‐
ing on your hardcopy printers. To format a reference page for a spe‐
cific printer, move to the reference page area and issue a command such
as the following: % cd /usr/share/man % gunzip -c man1/ls.1.gz |tbl
|neqn |nroff -Tdevice -man -h | lpr \ -Pmyprinter
Replace the device argument with /usr/share/lib/term/tabdevice, where
device is the name of a device listed in term(4). The lpr device set‐
ting, because it supports primitive line printers, is least likely to
cause problems 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 direc‐
tory 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
device is the name of a device listed in term(4).
EXIT STATUS
Success. An error occurred.
EXAMPLES
To create or update compressed preformatted files for reference pages
and also create or rebuild the whatis database, enter: catman-c To
create uncompressed preformatted files only for sections 1, 2, and 3,
enter: catman 123
This command also creates or rebuilds the whatis database. The
new database contains entries for reference pages in all sec‐
tions (not just 1, 2, and 3) that are found in the search path.
To create or rebuild the whatis database without creating or
updating formatted files, enter: catman-w To create compressed
preformatted files for all reference pages in the search path
but not rebuild the whatis database, enter: catman-c -n
FILES
Main reference page area Directories containing source files for most
reference pages Directories containing preformatted files for most ref‐
erence 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 is specified Command script to make the whatis
database Program used by the mkwhatis command to extract data from ref‐
erence pages
SEE ALSO
Commands: man(1), neqn(1), nroff(1), tbl(1)
Files: term(4), man(5), rsml(5)catman(8)