MANDOCDB(8) System Manager's Manual MANDOCDB(8)

NAME

mandocdbindex UNIX manuals

SYNOPSIS

mandocdb [-avW] [-C file]

mandocdb [-avW] dir ...

mandocdb [-vW] -d dir [file ...]

mandocdb [-vW] -u dir [file ...]

mandocdb -t file ...

DESCRIPTION

The mandocdb utility extracts keywords from UNIX manuals and indexes them in a Keyword Database and Index Database for fast retrieval by apropos(1), whatis(1), and man(1)'s -k option.

By default, mandocdb creates databases in each dir using the files mansection/[arch/]title.section and catsection/[arch/]title.0 in that directory; existing databases are truncated. If dir is not provided, mandocdb uses the default paths stipulated by man(1).

The arguments are as follows:

-a
Use all directories and files found below dir ....
-C file
Specify an alternative configuration file in man.conf(5) format.
-d dir
Merge (remove and re-add) file ... to the database in dir without truncating it.
-t file ...
Check the given files for potential problems. No databases are modified. Implies -a and -W. All diagnostic messages are printed to the standard output; the standard error output is not used.
-u dir
Remove file ... from the database in dir without truncating it.
-v
Display all files added or removed to the index.
-W
Print warnings about potential problems with manual pages to the standard error output.

If fatal parse errors are encountered while parsing, the offending file is printed to stderr, omitted from the index, and the parse continues with the next input file.

Index Database

The index database, mandoc.index, is a recno(3) database with record values consisting of

  1. the character d, a, or c to indicate the file type (mdoc(7), man(7), and post-formatted, respectively),
  2. the filename relative to the databases' path,
  3. the manual section,
  4. the manual title,
  5. the architecture (often empty),
  6. and the description.

Each of the above is NUL-terminated.

If the record value is zero-length, it is unassigned.

Keyword Database

The keyword database, mandoc.db, is a btree(3) database of NUL-terminated keywords (record length is non-zero string length plus one) mapping to a 16-byte binary field consisting of the 64-bit keyword type and the 64-bit Index Database record number, both in network-byte order.

The type bit-mask consists of the following values mapping into mdoc(7) macro identifiers:

0x0000000000000001ULL An
0x0000000000000002ULL Ar
0x0000000000000004ULL At
0x0000000000000008ULL Bsx
0x0000000000000010ULL Bx
0x0000000000000020ULL Cd
0x0000000000000040ULL Cm
0x0000000000000080ULL Dv
0x0000000000000100ULL Dx
0x0000000000000200ULL Em
0x0000000000000400ULL Er
0x0000000000000800ULL Ev
0x0000000000001000ULL Fa
0x0000000000002000ULL Fl
0x0000000000004000ULL Fn
0x0000000000008000ULL Ft
0x0000000000010000ULL Fx
0x0000000000020000ULL Ic
0x0000000000040000ULL In
0x0000000000080000ULL Lb
0x0000000000100000ULL Li
0x0000000000200000ULL Lk
0x0000000000400000ULL Ms
0x0000000000800000ULL Mt
0x0000000001000000ULL Nd
0x0000000002000000ULL Nm
0x0000000004000000ULL Nx
0x0000000008000000ULL Ox
0x0000000010000000ULL Pa
0x0000000020000000ULL Rs
0x0000000040000000ULL Sh
0x0000000080000000ULL Ss
0x0000000100000000ULL St
0x0000000200000000ULL Sy
0x0000000400000000ULL Tn
0x0000000800000000ULL Va
0x0000001000000000ULL Vt
0x0000002000000000ULL Xr

IMPLEMENTATION NOTES

The time to construct a new database pair grows linearly with the number of keywords in the input files. However, removing or updating entries with -u or -d, respectively, grows as a multiple of the index length and input size.

FILES

mandoc.db
A btree(3) keyword database mapping keywords to a type and file reference in mandoc.index.
mandoc.index
A recno(3) database of indexed file-names.
/etc/man.conf
The default man(1) configuration file.

EXIT STATUS

The mandocdb utility exits with one of the following values:

0
No errors occurred.
5
Invalid command line arguments were specified. No input files have been read.
6
An operating system error occurred, for example memory exhaustion or an error accessing input files. Such errors cause mandocdb to exit at once, possibly in the middle of parsing or formatting a file. The output databases are corrupt and should be removed.

DIAGNOSTICS

If the following errors occur, the mandocdb databases should be rebuilt.
%s: Corrupt database
The keyword database file indicated by %s is unreadable.
%s: Corrupt index
The index database file indicated by %s is unreadable.
%s: Path too long
The file %s is too long. This usually indicates database corruption or invalid command-line arguments.

SEE ALSO

apropos(1), man(1), whatis(1), btree(3), recno(3), man.conf(5)

HISTORY

A makewhatis utility first appeared in 2BSD. It was rewritten in perl(1) for OpenBSD 2.7 and in C for OpenBSD 5.1.

The dir argument first appeared in NetBSD 1.0; the options -dtu in OpenBSD 2.7; and the options -aCvW in OpenBSD 5.1.

AUTHORS

Bill Joy wrote the original BSD makewhatis in February 1979, Marc Espie started the Perl version in 2000, and the current version of mandocdb was written by Kristaps Dzonsons <kristaps@bsd.lv>.
September 18, 2013 OpenBSD 5.4