logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

mandoc.db.5 (5874B)


  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.