version 1.4, 2016/07/07 14:35:48 |
version 1.5, 2016/08/01 12:27:15 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2014, 2016 Ingo Schwarze <schwarze@openbsd.org> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
|
|
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
.Nm |
.Nm |
SQLite3 file format is used to store information about installed manual |
file format is used to store information about installed manual |
pages to facilitate semantic searching for manuals. |
pages to facilitate semantic searching for manuals. |
Each manual page tree contains its own |
Each manual page tree contains its own |
.Nm |
.Nm |
|
|
Such database files are generated by |
Such database files are generated by |
.Xr makewhatis 8 |
.Xr makewhatis 8 |
and used by |
and used by |
|
.Xr man 1 , |
.Xr apropos 1 |
.Xr apropos 1 |
and |
and |
.Xr whatis 1 . |
.Xr whatis 1 . |
.Pp |
.Pp |
One line in the following tables describes: |
The file format uses three datatypes: |
.Bl -tag -width Ds |
.Pp |
.It Sy mpages |
.Bl -dash -compact -offset 2n -width 1n |
One physical manual page file, no matter how many times and under which |
.It |
names it may appear in the file system. |
32-bit signed integer numbers in big endian (network) byte ordering |
.It Sy mlinks |
.It |
One entry in the file system, no matter which content it points to. |
NUL-terminated strings |
.It Sy names |
.It |
One manual page name, no matter whether it appears in a page header, |
lists of NUL-terminated strings, terminated by a second NUL character |
in a NAME or SYNOPSIS section, or as a file name. |
|
.It Sy keys |
|
One chunk of text from some macro invocation. |
|
.El |
.El |
.Pp |
.Pp |
Each record in the latter three tables uses its |
Numbers are aligned to four-byte boundaries; where they follow |
.Va pageid |
strings or lists of strings, padding with additional NUL characters |
column to point to a record in the |
occurs. |
.Sy mpages |
Some, but not all, numbers point to positions in the file. |
table. |
These pointers are measured in bytes, and the first byte of the |
|
file is considered to be byte 0. |
.Pp |
.Pp |
The other columns are as follows; unless stated otherwise, they are |
Each file consists of: |
of type |
.Pp |
.Vt TEXT . |
.Bl -dash -compact -offset 2n -width 1n |
.Bl -tag -width mpages.desc |
.It |
.It Sy mpages.desc |
One magic number, 0x3a7d0cdb. |
The description line |
.It |
.Pq Sq \&Nd |
One version number, currently 1. |
of the page. |
.It |
.It Sy mpages.form |
One pointer to the macros table. |
An |
.It |
.Vt INTEGER |
One pointer to the final magic number. |
bit field. |
.It |
If bit |
The pages table (variable length). |
.Dv FORM_GZ |
.It |
is set, the page is compressed and requires |
The macros table (variable length). |
.Xr gunzip 1 |
.It |
for display. |
The magic number once again, 0x3a7d0cdb. |
If bit |
.El |
.Dv FORM_SRC |
.Pp |
is set, the page is unformatted, that is in |
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 |
.Xr mdoc 7 |
or |
or |
.Xr man 7 |
.Xr man 7 . |
format, and requires |
.It |
.Xr mandoc 1 |
.Dv FORM_CAT No = 0x02 : |
for display. |
The manual page is preformatted. |
If bit |
.El |
.Dv FORM_SRC |
.It |
is not set, the page is formatted, i.e. a |
Zero to three NUL bytes for padding. |
.Sq cat |
.El |
page. |
.Pp |
.It Sy mlinks.sec |
The macros table consists of: |
The manual section as found in the subdirectory name. |
.Pp |
.It Sy mlinks.arch |
.Bl -dash -compact -offset 2n -width 1n |
The manual architecture as found in the subdirectory name, or |
.It |
.Qq any . |
The number of different macro keys, currently 36. |
.It Sy mlinks.name |
The ordering of macros is defined in |
The manual name as found in the file name. |
.In mansearch.h |
.It Sy names.bits |
and the significance of the macro keys is documented in |
An |
|
.Vt INTEGER |
|
bit mask telling whether the name came from a header line, from the |
|
NAME or SYNOPSIS section, or from a file name. |
|
Bits are defined in |
|
.In mansearch.h . |
|
.It Sy names.name |
|
The name itself. |
|
.It Sy keys.bits |
|
An |
|
.Vt INTEGER |
|
bit mask telling which semantic contexts the key was found in; |
|
defined in |
|
.In mansearch.h , |
|
documented in |
|
.Xr apropos 1 . |
.Xr apropos 1 . |
.It Sy keys.key |
.It |
The string found in those contexts. |
For each macro key, one pointer to the respective macro table. |
|
.It |
|
For each macro key, the macro table (variable length). |
.El |
.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 |
.Sh FILES |
.Bl -tag -width /usr/share/man/mandoc.db -compact |
.Bl -tag -width /usr/share/man/mandoc.db -compact |
.It Pa /usr/share/man/mandoc.db |
.It Pa /usr/share/man/mandoc.db |
|
|
The same for |
The same for |
.Xr packages 7 . |
.Xr packages 7 . |
.El |
.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 |
.Sh SEE ALSO |
.Xr apropos 1 , |
.Xr apropos 1 , |
.Xr man 1 , |
.Xr man 1 , |
.Xr sqlite3 1 , |
|
.Xr whatis 1 , |
.Xr whatis 1 , |
.Xr makewhatis 8 |
.Xr makewhatis 8 |
.Sh HISTORY |
.Sh HISTORY |
Line 140 A manual page database |
|
Line 215 A manual page database |
|
first appeared in |
first appeared in |
.Bx 2 . |
.Bx 2 . |
The present format first appeared in |
The present format first appeared in |
.Ox 5.6 . |
.Ox 6.1 . |
.Sh AUTHORS |
.Sh AUTHORS |
.An -nosplit |
.An -nosplit |
The original version of |
The original version of |
Line 148 The original version of |
|
Line 223 The original version of |
|
was written by |
was written by |
.An Bill Joy |
.An Bill Joy |
in 1979. |
in 1979. |
An SQLite3 version was first implemented by |
|
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv |
|
in 2012. |
|
The present database format was designed by |
The present database format was designed by |
.An Ingo Schwarze Aq Mt schwarze@openbsd.org |
.An Ingo Schwarze Aq Mt schwarze@openbsd.org |
in 2014. |
in 2016. |