Annotation of mandoc/mandoc.db.5, Revision 1.5
1.5 ! schwarze 1: .\" $Id: mandoc.db.5,v 1.4 2016/07/07 14:35:48 schwarze Exp $
1.1 schwarze 2: .\"
1.5 ! schwarze 3: .\" Copyright (c) 2014, 2016 Ingo Schwarze <schwarze@openbsd.org>
1.1 schwarze 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: .\"
1.5 ! schwarze 17: .Dd $Mdocdate: July 7 2016 $
1.1 schwarze 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
1.5 ! schwarze 26: file format is used to store information about installed manual
1.1 schwarze 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
1.5 ! schwarze 37: .Xr man 1 ,
1.1 schwarze 38: .Xr apropos 1
39: and
40: .Xr whatis 1 .
41: .Pp
1.5 ! schwarze 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
1.1 schwarze 139: .Xr mdoc 7
140: or
1.5 ! schwarze 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
1.1 schwarze 158: .Xr apropos 1 .
1.5 ! schwarze 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.
1.1 schwarze 187: .El
188: .Sh FILES
1.3 schwarze 189: .Bl -tag -width /usr/share/man/mandoc.db -compact
190: .It Pa /usr/share/man/mandoc.db
1.1 schwarze 191: The manual page database for the base system.
1.3 schwarze 192: .It Pa /usr/X11R6/man/mandoc.db
1.1 schwarze 193: The same for the
194: .Xr X 7
195: Window System.
1.3 schwarze 196: .It Pa /usr/local/man/mandoc.db
1.1 schwarze 197: The same for
198: .Xr packages 7 .
199: .El
1.5 ! schwarze 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/ .
1.1 schwarze 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
1.5 ! schwarze 218: .Ox 6.1 .
1.1 schwarze 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
1.5 ! schwarze 228: in 2016.
CVSweb