| blob | d864e0ea1716eaac02191782285c139d54ea076b |
1 .\" $Vendor-Id: mandocdb.8,v 1.17 2011/12/25 21:00:23 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
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 December 25, 2011
18 .Dt MANDOCDB 8
19 .Os
20 .Sh NAME
21 .Nm mandocdb
22 .Nd index UNIX manuals
23 .Sh SYNOPSIS
24 .Nm
25 .Op Fl avW
26 .Op Fl C Ar file
27 .Nm
28 .Op Fl avW
29 .Ar dir ...
30 .Nm
31 .Op Fl vW
32 .Fl d Ar dir
33 .Op Ar
34 .Nm
35 .Op Fl vW
36 .Fl u Ar dir
37 .Op Ar
38 .Nm
39 .Fl t Ar
40 .Sh DESCRIPTION
41 The
42 .Nm
43 utility extracts keywords from
44 .Ux
45 manuals and indexes them in a
46 .Sx Keyword Database
47 and
48 .Sx Index Database
49 for fast retrieval by
50 .Xr apropos 1 ,
51 .Xr whatis 1 ,
52 and
53 .Xr man 1 Ns 's
54 .Fl k
55 option.
56 .Pp
57 By default,
58 .Nm
59 creates databases in each
60 .Ar dir
61 using the files
62 .Sm off
63 .Sy man Ar section Li /
64 .Op Ar arch Li /
65 .Ar title . section
66 .Sm on
67 and
68 .Sm off
69 .Sy cat Ar section Li /
70 .Op Ar arch Li /
71 .Ar title . Sy 0
72 .Sm on
73 in that directory;
74 existing databases are truncated.
75 If
76 .Ar dir
77 is not provided,
78 .Nm
79 uses the default paths stipulated by
80 .Xr man 1 .
81 .Pp
82 The arguments are as follows:
83 .Bl -tag -width "-C file"
84 .It Fl a
85 Use all directories and files found below
86 .Ar dir ... .
87 .It Fl C Ar file
88 Specify an alternative configuration
89 .Ar file
90 in
91 .Xr man.conf 5
92 format.
93 .It Fl d Ar dir
94 Merge (remove and re-add)
95 .Ar
96 to the database in
97 .Ar dir
98 without truncating it.
99 .It Fl t Ar
100 Check the given
101 .Ar files
102 for potential problems.
103 No databases are modified.
104 Implies
105 .Fl a
106 and
107 .Fl W .
108 All diagnostic messages are printed to the standard output;
109 the standard error output is not used.
110 .It Fl u Ar dir
111 Remove
112 .Ar
113 from the database in
114 .Ar dir
115 without truncating it.
116 .It Fl v
117 Display all files added or removed to the index.
118 .It Fl W
119 Print warnings about potential problems with manual pages
120 to the standard error output.
121 .El
122 .Pp
123 If fatal parse errors are encountered while parsing, the offending file
124 is printed to stderr, omitted from the index, and the parse continues
125 with the next input file.
126 .Ss Index Database
127 The index database,
128 .Pa whatis.index ,
129 is a
130 .Xr recno 3
131 database with record values consisting of
132 .Pp
133 .Bl -enum -compact
134 .It
135 the character
136 .Cm d ,
137 .Cm a ,
138 or
139 .Cm c
140 to indicate the file type
141 .Po
142 .Xr mdoc 7 ,
143 .Xr man 7 ,
144 and post-formatted, respectively
145 .Pc ,
146 .It
147 the filename relative to the databases' path,
148 .It
149 the manual section,
150 .It
151 the manual title,
152 .It
153 the architecture
154 .Pq often empty ,
155 .It
156 and the description.
157 .El
158 .Pp
159 Each of the above is NUL-terminated.
160 .Pp
161 If the record value is zero-length, it is unassigned.
162 .Ss Keyword Database
163 The keyword database,
164 .Pa whatis.db ,
165 is a
166 .Xr btree 3
167 database of NUL-terminated keywords (record length is non-zero string
168 length plus one) mapping to a 16-byte binary field consisting of the
169 64-bit keyword type and the 64-bit
170 .Sx Index Database
171 record number, both in network-byte order.
172 .Pp
173 The type bit-mask consists of the following
174 values mapping into
175 .Xr mdoc 7
176 macro identifiers:
177 .Pp
178 .Bl -column "x0x0000000000000001ULLx" "xLix" -offset indent -compact
179 .It Li 0x0000000000000001ULL Ta \&An
180 .It Li 0x0000000000000002ULL Ta \&Ar
181 .It Li 0x0000000000000004ULL Ta \&At
182 .It Li 0x0000000000000008ULL Ta \&Bsx
183 .It Li 0x0000000000000010ULL Ta \&Bx
184 .It Li 0x0000000000000020ULL Ta \&Cd
185 .It Li 0x0000000000000040ULL Ta \&Cm
186 .It Li 0x0000000000000080ULL Ta \&Dv
187 .It Li 0x0000000000000100ULL Ta \&Dx
188 .It Li 0x0000000000000200ULL Ta \&Em
189 .It Li 0x0000000000000400ULL Ta \&Er
190 .It Li 0x0000000000000800ULL Ta \&Ev
191 .It Li 0x0000000000001000ULL Ta \&Fa
192 .It Li 0x0000000000002000ULL Ta \&Fl
193 .It Li 0x0000000000004000ULL Ta \&Fn
194 .It Li 0x0000000000008000ULL Ta \&Ft
195 .It Li 0x0000000000010000ULL Ta \&Fx
196 .It Li 0x0000000000020000ULL Ta \&Ic
197 .It Li 0x0000000000040000ULL Ta \&In
198 .It Li 0x0000000000080000ULL Ta \&Lb
199 .It Li 0x0000000000100000ULL Ta \&Li
200 .It Li 0x0000000000200000ULL Ta \&Lk
201 .It Li 0x0000000000400000ULL Ta \&Ms
202 .It Li 0x0000000000800000ULL Ta \&Mt
203 .It Li 0x0000000001000000ULL Ta \&Nd
204 .It Li 0x0000000002000000ULL Ta \&Nm
205 .It Li 0x0000000004000000ULL Ta \&Nx
206 .It Li 0x0000000008000000ULL Ta \&Ox
207 .It Li 0x0000000010000000ULL Ta \&Pa
208 .It Li 0x0000000020000000ULL Ta \&Rs
209 .It Li 0x0000000040000000ULL Ta \&Sh
210 .It Li 0x0000000080000000ULL Ta \&Ss
211 .It Li 0x0000000100000000ULL Ta \&St
212 .It Li 0x0000000200000000ULL Ta \&Sy
213 .It Li 0x0000000400000000ULL Ta \&Tn
214 .It Li 0x0000000800000000ULL Ta \&Va
215 .It Li 0x0000001000000000ULL Ta \&Vt
216 .It Li 0x0000002000000000ULL Ta \&Xr
217 .El
218 .Sh IMPLEMENTATION NOTES
219 The time to construct a new database pair grows linearly with the
220 number of keywords in the input files.
221 However, removing or updating entries with
222 .Fl u
223 or
224 .Fl d ,
225 respectively, grows as a multiple of the index length and input size.
226 .Sh FILES
227 .Bl -tag -width Ds
228 .It Pa whatis.db
229 A
230 .Xr btree 3
231 keyword database mapping keywords to a type and file reference in
232 .Pa whatis.index .
233 .It Pa whatis.index
234 A
235 .Xr recno 3
236 database of indexed file-names.
237 .It Pa /etc/man.conf
238 The default
239 .Xr man 1
240 configuration file.
241 .El
242 .Sh EXIT STATUS
243 The
244 .Nm
245 utility exits with one of the following values:
246 .Pp
247 .Bl -tag -width Ds -compact
248 .It 0
249 No errors occurred.
250 .It 5
251 Invalid command line arguments were specified.
252 No input files have been read.
253 .It 6
254 An operating system error occurred, for example memory exhaustion or an
255 error accessing input files.
256 Such errors cause
257 .Nm
258 to exit at once, possibly in the middle of parsing or formatting a file.
259 The output databases are corrupt and should be removed.
260 .El
261 .Sh DIAGNOSTICS
262 If the following errors occur, the
263 .Nm
264 databases should be rebuilt.
265 .Bl -diag
266 .It "%s: Corrupt database"
267 The keyword database file indicated by
268 .Pa %s
269 is unreadable.
270 .It "%s: Corrupt index"
271 The index database file indicated by
272 .Pa %s
273 is unreadable.
274 .It "%s: Path too long"
275 The file
276 .Pa %s
277 is too long.
278 This usually indicates database corruption or invalid command-line
279 arguments.
280 .El
281 .Sh SEE ALSO
282 .Xr apropos 1 ,
283 .Xr man 1 ,
284 .Xr whatis 1 ,
285 .Xr btree 3 ,
286 .Xr recno 3 ,
287 .Xr man.conf 5
288 .Sh AUTHORS
289 The
290 .Nm
291 utility was written by
292 .An Kristaps Dzonsons ,
293 .Mt kristaps@bsd.lv .