| blob | 26907d139f4174b0f7ba598d8cc0c9b118092d90 |
1 .\" $Id: mandoc.db.5,v 1.5 2016/08/01 12:27:15 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2014, 2016 Ingo Schwarze <schwarze@openbsd.org>
4 .\"
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
8 .\"
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 .\"
17 .Dd $Mdocdate: August 1 2016 $
18 .Dt MANDOC.DB 5
19 .Os
20 .Sh NAME
21 .Nm mandoc.db
22 .Nd manual page database
23 .Sh DESCRIPTION
24 The
25 .Nm
26 file format is used to store information about installed manual
27 pages to facilitate semantic searching for manuals.
28 Each manual page tree contains its own
29 .Nm
30 file; see
31 .Sx FILES
32 for examples.
33 .Pp
34 Such database files are generated by
35 .Xr makewhatis 8
36 and used by
37 .Xr man 1 ,
38 .Xr apropos 1
39 and
40 .Xr whatis 1 .
41 .Pp
42 The file format uses three datatypes:
43 .Pp
44 .Bl -dash -compact -offset 2n -width 1n
45 .It
46 32-bit signed integer numbers in big endian (network) byte ordering
47 .It
48 NUL-terminated strings
49 .It
50 lists of NUL-terminated strings, terminated by a second NUL character
51 .El
52 .Pp
53 Numbers are aligned to four-byte boundaries; where they follow
54 strings or lists of strings, padding with additional NUL characters
55 occurs.
56 Some, but not all, numbers point to positions in the file.
57 These pointers are measured in bytes, and the first byte of the
58 file is considered to be byte 0.
59 .Pp
60 Each file consists of:
61 .Pp
62 .Bl -dash -compact -offset 2n -width 1n
63 .It
64 One magic number, 0x3a7d0cdb.
65 .It
66 One version number, currently 1.
67 .It
68 One pointer to the macros table.
69 .It
70 One pointer to the final magic number.
71 .It
72 The pages table (variable length).
73 .It
74 The macros table (variable length).
75 .It
76 The magic number once again, 0x3a7d0cdb.
77 .El
78 .Pp
79 The pages table contains one entry for each physical manual page
80 file, no matter how many hard and soft links it may have in the
81 file system.
82 The pages table consists of:
83 .Pp
84 .Bl -dash -compact -offset 2n -width 1n
85 .It
86 The number of pages in the database.
87 .It
88 For each page:
89 .Bl -dash -compact -offset 2n -width 1n
90 .It
91 One pointer to the list of names.
92 .It
93 One pointer to the list of sections.
94 .It
95 One pointer to the list of architectures
96 or 0 if the page is machine-independent.
97 .It
98 One pointer to the one-line description string.
99 .It
100 One pointer to the list of filenames.
101 .El
102 .It
103 For each page, the list of names.
104 Each name is preceded by a single byte indicating the sources of the name.
105 The meaning of the bits is:
106 .Bl -dash -compact -offset 2n -width 1n
107 .It
108 0x10: The name appears in a filename.
109 .It
110 0x08: The name appears in a header line, i.e. in a .Dt or .TH macro.
111 .It
112 0x04: The name is the first one in the title line, i.e. it appears
113 in the first .Nm macro in the NAME section.
114 .It
115 0x02: The name appears in any .Nm macro in the NAME section.
116 .It
117 0x01: The name appears in an .Nm block in the SYNOPSIS section.
118 .El
119 .It
120 For each page, the list of sections.
121 Each section is given as a string, not as a number.
122 .It
123 For each architecture-dependent page, the list of architectures.
124 .It
125 For each page, the one-line description string taken from the .Nd macro.
126 .It
127 For each page, the list of filenames relative to the root of the
128 respective manpath.
129 This list includes hard links, soft links, and links simulated
130 with .so
131 .Xr roff 7
132 requests.
133 The first filename is preceded by a single byte
134 having the following significance:
135 .Bl -dash -compact -offset 2n -width 1n
136 .It
137 .Dv FORM_SRC No = 0x01 :
138 The file format is
139 .Xr mdoc 7
140 or
141 .Xr man 7 .
142 .It
143 .Dv FORM_CAT No = 0x02 :
144 The manual page is preformatted.
145 .El
146 .It
147 Zero to three NUL bytes for padding.
148 .El
149 .Pp
150 The macros table consists of:
151 .Pp
152 .Bl -dash -compact -offset 2n -width 1n
153 .It
154 The number of different macro keys, currently 36.
155 The ordering of macros is defined in
156 .In mansearch.h
157 and the significance of the macro keys is documented in
158 .Xr apropos 1 .
159 .It
160 For each macro key, one pointer to the respective macro table.
161 .It
162 For each macro key, the macro table (variable length).
163 .El
164 .Pp
165 Each macro table consists of:
166 .Pp
167 .Bl -dash -compact -offset 2n -width 1n
168 .It
169 The number of entries in the table.
170 .It
171 For each entry:
172 .Bl -dash -compact -offset 2n -width 1n
173 .It
174 One pointer to the value of the macro key.
175 Each value is a string of text taken from some macro invocation.
176 .It
177 One pointer to the list of pages.
178 .El
179 .It
180 For each entry, the value of the macro key.
181 .It
182 Zero to three NUL bytes for padding.
183 .It
184 For each entry, one or more pointers to pages in the pages table,
185 pointing to the pointer to the list of names,
186 followed by the number 0.
187 .El
188 .Sh FILES
189 .Bl -tag -width /usr/share/man/mandoc.db -compact
190 .It Pa /usr/share/man/mandoc.db
191 The manual page database for the base system.
192 .It Pa /usr/X11R6/man/mandoc.db
193 The same for the
194 .Xr X 7
195 Window System.
196 .It Pa /usr/local/man/mandoc.db
197 The same for
198 .Xr packages 7 .
199 .El
200 .Pp
201 A program to dump
202 .Nm
203 files in a human-readable format suitable for
204 .Xr diff 1
205 is provided in the directory
206 .Pa /usr/src/regress/usr.bin/mandoc/db/dbm_dump/ .
207 .Sh SEE ALSO
208 .Xr apropos 1 ,
209 .Xr man 1 ,
210 .Xr whatis 1 ,
211 .Xr makewhatis 8
212 .Sh HISTORY
213 A manual page database
214 .Pa /usr/lib/whatis
215 first appeared in
216 .Bx 2 .
217 The present format first appeared in
218 .Ox 6.1 .
219 .Sh AUTHORS
220 .An -nosplit
221 The original version of
222 .Xr makewhatis 8
223 was written by
224 .An Bill Joy
225 in 1979.
226 The present database format was designed by
227 .An Ingo Schwarze Aq Mt schwarze@openbsd.org
228 in 2016.