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 24The 25.Nm 26file format is used to store information about installed manual 27pages to facilitate semantic searching for manuals. 28Each manual page tree contains its own 29.Nm 30file; see 31.Sx FILES 32for examples. 33.Pp 34Such database files are generated by 35.Xr makewhatis 8 36and used by 37.Xr man 1 , 38.Xr apropos 1 39and 40.Xr whatis 1 . 41.Pp 42The file format uses three datatypes: 43.Pp 44.Bl -dash -compact -offset 2n -width 1n 45.It 4632-bit signed integer numbers in big endian (network) byte ordering 47.It 48NUL-terminated strings 49.It 50lists of NUL-terminated strings, terminated by a second NUL character 51.El 52.Pp 53Numbers are aligned to four-byte boundaries; where they follow 54strings or lists of strings, padding with additional NUL characters 55occurs. 56Some, but not all, numbers point to positions in the file. 57These pointers are measured in bytes, and the first byte of the 58file is considered to be byte 0. 59.Pp 60Each file consists of: 61.Pp 62.Bl -dash -compact -offset 2n -width 1n 63.It 64One magic number, 0x3a7d0cdb. 65.It 66One version number, currently 1. 67.It 68One pointer to the macros table. 69.It 70One pointer to the final magic number. 71.It 72The pages table (variable length). 73.It 74The macros table (variable length). 75.It 76The magic number once again, 0x3a7d0cdb. 77.El 78.Pp 79The pages table contains one entry for each physical manual page 80file, no matter how many hard and soft links it may have in the 81file system. 82The pages table consists of: 83.Pp 84.Bl -dash -compact -offset 2n -width 1n 85.It 86The number of pages in the database. 87.It 88For each page: 89.Bl -dash -compact -offset 2n -width 1n 90.It 91One pointer to the list of names. 92.It 93One pointer to the list of sections. 94.It 95One pointer to the list of architectures 96or 0 if the page is machine-independent. 97.It 98One pointer to the one-line description string. 99.It 100One pointer to the list of filenames. 101.El 102.It 103For each page, the list of names. 104Each name is preceded by a single byte indicating the sources of the name. 105The meaning of the bits is: 106.Bl -dash -compact -offset 2n -width 1n 107.It 1080x10: The name appears in a filename. 109.It 1100x08: The name appears in a header line, i.e. in a .Dt or .TH macro. 111.It 1120x04: The name is the first one in the title line, i.e. it appears 113in the first .Nm macro in the NAME section. 114.It 1150x02: The name appears in any .Nm macro in the NAME section. 116.It 1170x01: The name appears in an .Nm block in the SYNOPSIS section. 118.El 119.It 120For each page, the list of sections. 121Each section is given as a string, not as a number. 122.It 123For each architecture-dependent page, the list of architectures. 124.It 125For each page, the one-line description string taken from the .Nd macro. 126.It 127For each page, the list of filenames relative to the root of the 128respective manpath. 129This list includes hard links, soft links, and links simulated 130with .so 131.Xr roff 7 132requests. 133The first filename is preceded by a single byte 134having the following significance: 135.Bl -dash -compact -offset 2n -width 1n 136.It 137.Dv FORM_SRC No = 0x01 : 138The file format is 139.Xr mdoc 7 140or 141.Xr man 7 . 142.It 143.Dv FORM_CAT No = 0x02 : 144The manual page is preformatted. 145.El 146.It 147Zero to three NUL bytes for padding. 148.El 149.Pp 150The macros table consists of: 151.Pp 152.Bl -dash -compact -offset 2n -width 1n 153.It 154The number of different macro keys, currently 36. 155The ordering of macros is defined in 156.In mansearch.h 157and the significance of the macro keys is documented in 158.Xr apropos 1 . 159.It 160For each macro key, one pointer to the respective macro table. 161.It 162For each macro key, the macro table (variable length). 163.El 164.Pp 165Each macro table consists of: 166.Pp 167.Bl -dash -compact -offset 2n -width 1n 168.It 169The number of entries in the table. 170.It 171For each entry: 172.Bl -dash -compact -offset 2n -width 1n 173.It 174One pointer to the value of the macro key. 175Each value is a string of text taken from some macro invocation. 176.It 177One pointer to the list of pages. 178.El 179.It 180For each entry, the value of the macro key. 181.It 182Zero to three NUL bytes for padding. 183.It 184For each entry, one or more pointers to pages in the pages table, 185pointing to the pointer to the list of names, 186followed 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 191The manual page database for the base system. 192.It Pa /usr/X11R6/man/mandoc.db 193The same for the 194.Xr X 7 195Window System. 196.It Pa /usr/local/man/mandoc.db 197The same for 198.Xr packages 7 . 199.El 200.Pp 201A program to dump 202.Nm 203files in a human-readable format suitable for 204.Xr diff 1 205is 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 213A manual page database 214.Pa /usr/lib/whatis 215first appeared in 216.Bx 2 . 217The present format first appeared in 218.Ox 6.1 . 219.Sh AUTHORS 220.An -nosplit 221The original version of 222.Xr makewhatis 8 223was written by 224.An Bill Joy 225in 1979. 226The present database format was designed by 227.An Ingo Schwarze Aq Mt schwarze@openbsd.org 228in 2016. 229