SYNOPSIS
mandb [-dqsuc|-h|-V] [manpath]
DESCRIPTION
mandb is used to initialise or manually update index
database caches that are usually maintained by man. The
caches contain information relevant to the current state
of the manual page system and the information stored
within them is used by the man_db utilities to enhance
their speed and functionality.
When creating or updating an index, mandb will warn of bad
ROFF .so requests, bogus manual page filenames and manual
pages from which the whatis cannot be parsed.
Supplying mandb with an optional colon-delimited path will
override the internal system manual page hierarchy search
path, determined from information found within the man_db
configuration file.
DATABASE CACHES
mandb can be compiled with support for any one of the fol
lowing database types.
Name Type Async Filename
----------------------------------------------------------
Berkeley db Binary tree Yes index.bt
GNU gdbm v >= 1.6 Hashed Yes index.db
GNU gdbm v < 1.6 Hashed No index.db
UNIX ndbm Hashed No index.(dir|pag)
Those database types that support asynchronous updates
provide enhanced speed at the cost of possible corruption
in the event of unusual termination. In an unusual case
where this has occured, it may be necessary to rerun mandb
with the -c option to re-create the databases from
scratch.
OPTIONS
-d, --debug
Produce debugging information.
-q, --quiet
Produce no warnings.
-s, --no-straycats
Do not spend time looking for or adding information
to the databases regarding stray cats.
-p, --no-purge
Do not spend time checking for deleted manual pages
and purging them from the databases.
-t, --test
Perform correctness checks on manual pages in the
hierarchy search path. With this option, mandb
will not alter existing databases.
-h, --help
Show the usage message, then exit.
-V, --version
Show the version, then exit.
DIAGNOSTICS
The following warning messages can be emitted during
database building.
<filename>: whatis parse for page(sec) failed
An attempt to extract whatis line(s) from the given
<filename> failed. This is usually due to a poorly
written manual page, but if many such messages are
emitted it is likely that the system contains non-
standard manual pages which are incompatible with
the man_db whatis parser. See the WHATIS PARSING
section for more information.
<filename>: is a dangling symlink
<filename> does not exist but is referenced by a
symbolic link. Further diagnostics are usually
emitted to identify the <filename> of the offending
link.
<filename>: bad symlink or ROFF `.so' request
<filename> is either a symbolic link to, or con
tains a ROFF include request to, a non existent
file.
<filename>: ignoring bogus filename
The <filename> may or may not be a valid manual
page but its name is invalid. This is usually due
to a manual page with sectional extension <x> being
put in manual page section <y>.
<filename_mask>: competing extensions
The wildcard <filename_mask> is not unique. This
is usually caused by the existence of both a com
pressed and uncompressed version of the same manual
page. All but the most recent are ignored.
WHATIS PARSING
mandb parses the NAME section at the top of each manual
page looking for names and descriptions of the features
documented in each. While the parser is quite tolerant,
as it has to cope with a number of different forms that
rated by commas. The text on the right-hand side is free-
form, and may be spread over multiple lines. If several
features with different descriptions are being documented
in the same manual page, the following form is therefore
used:
.SH NAME
foo, bar \- programs to do something
.br
baz \- program to do nothing
(A macro which starts a new paragraph, like .PP, may be
used instead of the break macro .br.)
There are several common reasons why whatis parsing fails.
Sometimes authors of manual pages replace `.SH NAME' with
`.SH MYPROGRAM', and then mandb cannot find the section
from which to extract the information it needs. Sometimes
authors include a NAME section, but place free-form text
there rather than `name \- description'. However, any
syntax resembling the above should be accepted.
FILES
/etc/manpath.config
man_db configuration file.
/usr/man/index.(bt|db|dir|pag)
A traditional global index database cache.
/var/catman/index.(bt|db|dir|pag)
An alternate or FSSTND compliant global index
database cache.
/var/cache/man/index.(bt|db|dir|pag)
An FHS compliant global index database cache.
SEE ALSO
man(1), manpath(5), catman(8).
AUTHOR
Wilf. (G.Wilford@ee.surrey.ac.uk).
Fabrizio Polacco (fpolacco@debian.org).
Colin Watson (cjwatson@debian.org).
2.3.19 14 May 2001 mandb(8)
Man(1) output converted with
man2html