mandoc.db.5 (5874B)
- .\" $Id: mandoc.db.5,v 1.5 2016/08/01 12:27:15 schwarze Exp $
- .\"
- .\" Copyright (c) 2014, 2016 Ingo Schwarze <schwarze@openbsd.org>
- .\"
- .\" Permission to use, copy, modify, and distribute this software for any
- .\" purpose with or without fee is hereby granted, provided that the above
- .\" copyright notice and this permission notice appear in all copies.
- .\"
- .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
- .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
- .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
- .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
- .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
- .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
- .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
- .\"
- .Dd $Mdocdate: August 1 2016 $
- .Dt MANDOC.DB 5
- .Os
- .Sh NAME
- .Nm mandoc.db
- .Nd manual page database
- .Sh DESCRIPTION
- The
- .Nm
- file format is used to store information about installed manual
- pages to facilitate semantic searching for manuals.
- Each manual page tree contains its own
- .Nm
- file; see
- .Sx FILES
- for examples.
- .Pp
- Such database files are generated by
- .Xr makewhatis 8
- and used by
- .Xr man 1 ,
- .Xr apropos 1
- and
- .Xr whatis 1 .
- .Pp
- The file format uses three datatypes:
- .Pp
- .Bl -dash -compact -offset 2n -width 1n
- .It
- 32-bit signed integer numbers in big endian (network) byte ordering
- .It
- NUL-terminated strings
- .It
- lists of NUL-terminated strings, terminated by a second NUL character
- .El
- .Pp
- Numbers are aligned to four-byte boundaries; where they follow
- strings or lists of strings, padding with additional NUL characters
- occurs.
- Some, but not all, numbers point to positions in the file.
- These pointers are measured in bytes, and the first byte of the
- file is considered to be byte 0.
- .Pp
- Each file consists of:
- .Pp
- .Bl -dash -compact -offset 2n -width 1n
- .It
- One magic number, 0x3a7d0cdb.
- .It
- One version number, currently 1.
- .It
- One pointer to the macros table.
- .It
- One pointer to the final magic number.
- .It
- The pages table (variable length).
- .It
- The macros table (variable length).
- .It
- The magic number once again, 0x3a7d0cdb.
- .El
- .Pp
- The pages table contains one entry for each physical manual page
- file, no matter how many hard and soft links it may have in the
- file system.
- The pages table consists of:
- .Pp
- .Bl -dash -compact -offset 2n -width 1n
- .It
- The number of pages in the database.
- .It
- For each page:
- .Bl -dash -compact -offset 2n -width 1n
- .It
- One pointer to the list of names.
- .It
- One pointer to the list of sections.
- .It
- One pointer to the list of architectures
- or 0 if the page is machine-independent.
- .It
- One pointer to the one-line description string.
- .It
- One pointer to the list of filenames.
- .El
- .It
- For each page, the list of names.
- Each name is preceded by a single byte indicating the sources of the name.
- The meaning of the bits is:
- .Bl -dash -compact -offset 2n -width 1n
- .It
- 0x10: The name appears in a filename.
- .It
- 0x08: The name appears in a header line, i.e. in a .Dt or .TH macro.
- .It
- 0x04: The name is the first one in the title line, i.e. it appears
- in the first .Nm macro in the NAME section.
- .It
- 0x02: The name appears in any .Nm macro in the NAME section.
- .It
- 0x01: The name appears in an .Nm block in the SYNOPSIS section.
- .El
- .It
- For each page, the list of sections.
- Each section is given as a string, not as a number.
- .It
- For each architecture-dependent page, the list of architectures.
- .It
- For each page, the one-line description string taken from the .Nd macro.
- .It
- For each page, the list of filenames relative to the root of the
- respective manpath.
- This list includes hard links, soft links, and links simulated
- with .so
- .Xr roff 7
- requests.
- The first filename is preceded by a single byte
- having the following significance:
- .Bl -dash -compact -offset 2n -width 1n
- .It
- .Dv FORM_SRC No = 0x01 :
- The file format is
- .Xr mdoc 7
- or
- .Xr man 7 .
- .It
- .Dv FORM_CAT No = 0x02 :
- The manual page is preformatted.
- .El
- .It
- Zero to three NUL bytes for padding.
- .El
- .Pp
- The macros table consists of:
- .Pp
- .Bl -dash -compact -offset 2n -width 1n
- .It
- The number of different macro keys, currently 36.
- The ordering of macros is defined in
- .In mansearch.h
- and the significance of the macro keys is documented in
- .Xr apropos 1 .
- .It
- For each macro key, one pointer to the respective macro table.
- .It
- For each macro key, the macro table (variable length).
- .El
- .Pp
- Each macro table consists of:
- .Pp
- .Bl -dash -compact -offset 2n -width 1n
- .It
- The number of entries in the table.
- .It
- For each entry:
- .Bl -dash -compact -offset 2n -width 1n
- .It
- One pointer to the value of the macro key.
- Each value is a string of text taken from some macro invocation.
- .It
- One pointer to the list of pages.
- .El
- .It
- For each entry, the value of the macro key.
- .It
- Zero to three NUL bytes for padding.
- .It
- For each entry, one or more pointers to pages in the pages table,
- pointing to the pointer to the list of names,
- followed by the number 0.
- .El
- .Sh FILES
- .Bl -tag -width /usr/share/man/mandoc.db -compact
- .It Pa /usr/share/man/mandoc.db
- The manual page database for the base system.
- .It Pa /usr/X11R6/man/mandoc.db
- The same for the
- .Xr X 7
- Window System.
- .It Pa /usr/local/man/mandoc.db
- The same for
- .Xr packages 7 .
- .El
- .Pp
- A program to dump
- .Nm
- files in a human-readable format suitable for
- .Xr diff 1
- is provided in the directory
- .Pa /usr/src/regress/usr.bin/mandoc/db/dbm_dump/ .
- .Sh SEE ALSO
- .Xr apropos 1 ,
- .Xr man 1 ,
- .Xr whatis 1 ,
- .Xr makewhatis 8
- .Sh HISTORY
- A manual page database
- .Pa /usr/lib/whatis
- first appeared in
- .Bx 2 .
- The present format first appeared in
- .Ox 6.1 .
- .Sh AUTHORS
- .An -nosplit
- The original version of
- .Xr makewhatis 8
- was written by
- .An Bill Joy
- in 1979.
- The present database format was designed by
- .An Ingo Schwarze Aq Mt schwarze@openbsd.org
- in 2016.