229 lines
5.7 KiB
Groff
229 lines
5.7 KiB
Groff
.\" $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.
|