[BACK]Return to mandoc.db.5 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

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