MAKEWHATIS(8) System Administration MAKEWHATIS(8)
makewhatis - generate the whatis database file
makewhatis [ -c | -C ] [ -f outfile ] [ -l logfile ] [ -o dbfile ] [ -p
path ] [ -v n ] [ -V ]
This manual page documents makewhatis version 3.1.
makewhatis generates the whatis database for apropos(1), man(1), and
whatis(1). This database is a text file containing line oriented
records. Each record contains a man page name, the section number, and
the brief description.
Makewhatis makes use of one of the environment variables MANPATH, USR-
MAN, or MANDIR, in the listed order of preference. It will use this
environment variable to determine for which manual pages the whatis
database should be built. If the environment variable contains more
than one path (delimited by either colons or spaces), then whatis
databases will be generated in all of the specified paths. This may be
overridden by the -p flag.
By default, makewhatis will generate its database from manual pages
existing in the manpath_component/manX subdirectories (where X is the
section number) that are either aroff or nroff source files. However,
since many GNO programmers are providing only preformatted text ver-
sions of their man pages, using the -c flag will cause makewhatis to
also use manual pages in the manpath_component/catX subdirectories when
building the database. If there is a corresponding manual page in both
the manX and catX subdirectory, then only the page in the manX subdi-
rectory will be used.
Manual pages which are nroff source files in the manX subdirectory, or
are preformatted text in the catX subdirectory may be compressed by
either compress(1), freeze(1), or gzip(1), provided that the suffixes
on the compressed file are .Z, .F, and .gz, respectively. The case of
the suffix is significant. Aroff source files must not be compressed
by any method.
All aroff link files are ignored. A file is assumed to be an aroff
link file if it ends in .l (dot lower-case ell) and is not within a
manl (man-ell) or a catl (cat-ell) subdirectory.
Note that the lines in the whatis database file are created in the
order that the man pages are found. It is suggested that the database
files be sorted after makewhatis is finished. See sort(1) or msort(1).
-c will check catX subdirectories as well as manX subdirectories.
-C will check only catX subdirectories, not manX subdirectories.
causes the makewhatis status output to be placed in outfile.
Invoking -f without -v2 produces no output.
will cause any error messages to be printed to logfile. Invok-
ing -l without either -v1 or -v2 produces no output.
will make makewhatis use dbfile as the name for the generated
whatis databases. While it is possible to use a full pathname
for dbfile, this will result in that file being overwritten for
each colon- or space-delimited entry in MANPATH.
overrides the environment variables MANPATH et al for determin-
ing for which manual page hierarchies the databases must be gen-
-v n creates verbose status messages during execution. For n=1 only
major error messages are printed out. For n=2, the names of
processed files are also printed. For n=3, the output becomes
very verbose with excessive status information, including list-
ing any missing subdirectores.
-V will show version and usage information, then exit.
Unless the -p flag is used, makewhatis will use the first that
it finds of these environment variables for determining where
database files should be generated. The search is done in the
order shown. While makewhatis will correctly handle '~' and '.'
being part of these paths, it will not correctly handle '..'.
Either colons or spaces can be used to delimit the individual
paths. If the value of the selected environment variable con-
tains no spaces nor / characters (such as :usr:local:man), it is
assumed to be a single path, not a list of paths.
Although makewhatis allows USRMAN and MANDIR to be each a colon-
or space-separated list of pathnames, it is recommended that for
compatibility with man (version 2.1 and earlier) these vari-
ables, if used, should be a single pathname.
Makewhatis assumes that the programs aroff, compress, freeze, and gzip
are available to the executing shell via the system(2) call. Nroff is
not used and need not be available.
Because makewhatis looks for the string NAME and one of .SH, SYNOPSIS,
or DESCRIPTION when processing files, it can be confused by missing
fields or some methods of formatting. For example, if in a preformat-
ted manual page NAME is underlined by repeated backspace-_ sequences,
then the generated description for that particular man page is unpre-
dictable, though usually blank. When parsing preformatted manual
pages, makewhatis will understand the common double- and quadruple-
boldfaced subheadings, provided that the backspace character (control-
H) is used to achieve this effect.
Similarily, makewhatis expects the subheading NAME to be in the format:
command_name [...] - brief description
If this is not so (ignoring whitespace), then the output is unpre-
Man pages must be CR-delimited (ASCII 015, or control-M).
Where unpredictable output has been mentioned above, this means that
the description in the database file will either be blank or random
text from the man page. It does not mean that system integrity or that
the remainder of the database file has been affected.
Any text appearing after NAME on the NAME header line will be ignored.
Makewhatis reads files in blocks of 1024 characters. If formatting
information is split by the end of the input buffer, you may see
formatting infomation such as .BR in the output. This was not fixed
due to the overhead of having to check for such a condition.
Please report any additional bugs to Devin Reade, <email@example.com>.
/usr/[share/]man/whatis -- the whatis database
apropos(1), aroff(1), catman(1), compress(1), freeze(1), gzip(1),
man(1), nroff(1), whatis(1)
GNO 28 March 1998 MAKEWHATIS(8)
Man(1) output converted with