1 files changed, 317 insertions, 0 deletions

diff --git a/manual/db.me b/manual/db.me
new file mode 100644
index 0000000..e5b0fbf
--- /dev/null
+++ b/manual/db.me
@@ -0,0 +1,317 @@
+.\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.)
+.\" Copyright (c) 2002 Colin Watson.
+.\"
+.\" You may distribute under the terms of the GNU General Public
+.\" License as specified in the file docs/COPYING.GPLv2 that comes with the
+.\" man-db distribution.
+.\"
+.\" Thu Sep 21 19:22:47 BST 1995  Wilf. (G.Wilford@ee.surrey.ac.uk)
+.\"
+.BS 1 "The index database caches"
+.lp
+As mentioned in the introduction, \*M uses database lookups to search for
+manual page locations and information.
+When performing a manual page lookup or a basic
+.b whatis
+search, the databases are searched in
+.ip
+.i "key \(-> content"
+.lp
+mode and are as fast as the underlying databases can be.
+When performing
+.b apropos
+or special
+.b whatis
+searches, the databases are searched in a linear way, which, although far
+more expensive than
+.i keyed
+lookup, is no worse than traditional text based file searching.
+.BS 2 "index database location"
+.lp
+The databases are always located at the root of the cat page hierarchy,
+whether this is the same as the manual page hierarchy or not.
+As file locking mechanisms are employed to ensure that concurrent
+processes do not update a database simultaneously, it is almost imperative
+that the databases reside on a local filesystem since file locking across
+NFS filesystems may be unavailable or flaky.
+To avoid such problems,
+.b man
+can be compiled without database maintenance support.
+See the section titled "Modes of operation" for details.
+.BS 3 "Manual hierarchies with no index database"
+.lp
+It is possible for the \*M utilities to operate without aid from an index
+database.
+Under such circumstances, search methods will use only file
+globbing and whatis type searches are performed on any traditional whatis
+text databases that may exist.
+Only the traditional cat hierarchy is searched for cat files.
+.BS 3 "User manual page hierarchies"
+.lp
+A user may have any number of personal manual page hierarchies listed in
+their
+.EV MANPATH\c
+.r .
+.r
+By default,
+.b man
+will maintain
+.b mandb
+created databases at the root of user manual page
+hierarchies.
+The definition of a user manual hierarchy is that it
+does not have an entry in the \*M configuration file.
+See
+.b manpath (5)
+for details.
+.BS 2 "Contents of an index database"
+.lp
+There are four kinds of entry in an index database.
+.np
+A direct entry regarding a particular manual page.
+Manual pages that are unique in terms of name use just a single entry
+in the database and can be looked up by simply using the name as the key.
+.np
+A common name index entry that lists the extensions of all of the manual
+pages sharing the common index entry name.
+Manual pages that share common names but have differing extensions each
+have a single database entry, but this time they are looked up with a key
+comprised of their name and their extension.
+The entire set of common named
+pages also has an common name index entry that informs of the extensions
+available.
+.np
+An indirect entry that has a pointer to the real entry.
+Manual pages that are whatis references to a particular page do not
+physically exist so they have a pointer to the entry containing the location
+of the real manual page.
+.np
+Special identification entries.
+There is one special key name,
+.q $version$
+that identifies the database storage scheme version.
+.lp
+In order to support looking up manual pages in a case-insensitive fashion,
+keys are stored in lower case.
+If the name of the page was not already in lower case, its true case is also
+stored in the common name index entry.
+.lp
+In the following entries, the character
+.q |
+will be used to separate the fields. In reality a tab is used.
+Direct and indirect entries takes the form:
+.ip
+.i "<name> \(-> <realname>|\:<ext>|\:<sec>|\:<mtime.sec>|\:<mtime.nsec>|\:<ID>|\:<ref>|\:<filter>|\:<comp>|\:<whatis>"
+.lp
+Common name index entries take the form:
+.ip
+.i "<name> \(-> |<realname1>|\:<ext1>|\:<realname2>|\:<ext2>|\:<realname3>|\:<ext3>| .\|.\|. <realnamen>|\:<extn>"
+.lp
+and common name direct or indirect entries take the form:
+.ip
+.i "<name>|<ext> \(-> <realname>|\:<ext>|\:<sec>|\:<mtime.sec>|\:<mtime.nsec>|\:\:<ID>|\:<ref>|\:<filter>|\:<comp>|\:<whatis>"
+.lp
+where in each case the filename being represented is formed as
+.ip
+.i <manual_hierarchy>/man<sec>/<name>.<ext>.<comp>
+.lp
+in the case of a manual page, or
+.ip
+.i <cat_hierarchy>/cat<sec>/<name>.<ext>.<comp>
+.lp
+in the case of a stray cat.
+.lp
+If any of the fields would be empty, a single
+.q \-
+is stored in its place.
+.i <comp>
+represents the compression extension,
+.i <mtime.sec>
+is an integer representing the seconds part of the last modification
+time of the manual page,
+.i <mtime.nsec>
+is an integer representing the nanoseconds part of the last modification
+time of the manual page,
+.i <ref>
+points to the entry containing the location of the real page,
+.i <ID>
+is one of the following identification letters, and
+.i <filter>
+represents any preprocessors that are needed to display the page.
+
+.TS
+center box tab (@);
+l | l | l .
+ID@#define@Description
+_
+A@ULT_MAN@ultimate manual page, the full source nroff file
+B@SO_MAN@manual page containing a .so request to an ULT_MAN
+C@WHATIS_MAN@virtual whatis referenced page pointing to an ULT_MAN
+D@STRAY_CAT@cat page with no source manual page
+E@WHATIS_CAT@virtual whatis referenced page pointing to a STRAY_CAT
+.TE
+
+The
+.i ID
+illustrates the precedence.
+Some types of manual page can be referenced by
+several means, e.g. .so requested and whatis referred.
+In such a case, only one reference must be stored in the database,
+the precedence level decides which.
+.BS 3 "Favouring stray cats"
+.lp
+With the above rules of precedence, it is possible for a valid stray cat page
+to be replaced by a whatis referred page sharing identical name-space.
+.lp
+If you would like to see the stray cat page
+.b kill (1)
+instead of the
+.b bash_builtins (1)
+page referenced by
+.b kill (1),
+edit
+.i include/manconfig.h
+and un-comment the following line
+.lp
+/* #define FAVOUR_STRAYCATS */
+.BS 3 "Accessdb"
+.lp
+A simple program,
+.b accessdb
+is included with \*M.
+It will output the data contained within a \*M
+database in a human readable form.
+By default, it will
+.i dump
+the data from
+.i /var/cache/man/index.<db-type> ,
+where
+.i <db-type>
+is dependent on the database library in use.
+.lp
+Supplying an argument to
+.b accessdb
+will override this default.
+Tabs are replaced in the output by a tilde
+.q ~
+in the
+.i key
+field and a single space in the
+.i content
+field.
+.BS 3 "Example database"
+.lp
+As an example of both
+.b accessdb
+and the database storage method, the output of
+.ip
+.bx "src/accessdb man/index.bt"
+.lp
+after first running
+.ip
+.bx "src/mandb man"
+.lp
+from the top level build directory is included below.
+.lp
+.nf
+$version$ -> "2.5.0"
+accessdb -> "- 8 8 1410381979 324541691 A - - - dumps the content of a man-db database in a human readable format"
+apropos -> "- 1 1 1410381979 268541692 A - - - search the manual page names and descriptions"
+catman -> "- 8 8 1410381979 328541691 A - - - create or update the pre-formatted manual pages"
+lexgrog -> "- 1 1 1410381979 268541692 A - - - parse header information in man pages"
+man -> "- 1 1 1410381979 280541692 A - t - an interface to the system reference manuals"
+manconv -> "- 1 1 1410381979 272541692 A - - - convert manual page from one encoding to another"
+mandb -> "- 8 8 1410381979 324541691 A - t - create or update the manual page index caches"
+manpath -> " manpath 5 manpath 1"
+manpath~1 -> "- 1 1 1410381979 300541691 A - - - determine search path for manual pages"
+manpath~5 -> "- 5 5 1410381979 304541691 A - - - format of the /etc/manpath.config file"
+whatis -> "- 1 1 1410381979 300541691 A - - - display one-line manual page descriptions"
+zsoelim -> "- 1 1 1410381979 304541691 A - - - satisfy .so requests in roff input"
+.fi
+.BS 2 "Database types"
+.lp
+\*M has support for various low level database libraries commonly in use
+today.
+The interfaces to the libraries are known as
+.bu
+ndbm (\*U)
+.bu
+gdbm (\*(GN)
+.bu
+btree (Berkeley DB)
+.lp
+\*M currently does not hold more than one database open at any time, so
+.bu
+dbm (\*U)
+.lp
+support could be added in the future.
+.BS 2 "Limitations"
+.lp
+The general differences and limitations are best compared in a table.
+
+.TS
+center box tab(@);
+c | c | c | c  s | c | c .
+Name@Type@File@Content memory@Concurrent@Shareable
+\^@\^@\^@_@\^@\^
+.T&
+c | c | c | c | c | c | c
+l | l | l | l | l | l | l .
+\^@\^@name@type@limit@access@\^
+_
+ndbm@hash@index\**@static@1Kb@none@no
+gdbm@hash@index.db@dynamic@\-@file locking@no
+btree@binary tree@index.bt@static@\-@none@yes
+.TE
+
+.(f
+\** ndbm databases are physically represented by two files,
+.i index.dir
+and
+.i index.pag ,
+but are referred to simply as
+.i index
+by the interface routines.
+.)f
+Those types that have no built in concurrent access strategy are provided
+with
+.b flock (2)
+based file locking by \*M.
+.lp
+Berkeley DB initializes its databases very quickly, so
+.b btree
+may have some performance advantages when doing
+.b man
+searches.
+However, it is quite heavyweight and its library SONAME and on-disk formats
+have changed a number of times to provide features considerably beyond what
+\*M needs, so the preferred library interface is now
+.b gdbm .
+.b configure
+will look for
+.b gdbm ,
+.b btree
+and then finally
+.b ndbm
+routines when configuring \*M.
+.BS 2 "Sharing databases in a heterogeneous environment"
+It may be necessary or advantageous to share databases across
+platforms, regardless of the potential file locking problems.
+.lp
+An example would be a user having a personal manual page hierarchy in an NFS
+based home directory environment, whereby the home directory is held on and
+mounted from a single machine in a heterogeneous network.
+.lp
+In this context, the database cache will have the same name and reside in
+the same place on all machines.
+There are at least two ways to deal with this problem.
+.bu
+Hack the
+.i include/manconfig.h
+file on each platform to provide a unique database name for each system.
+No databases will be shared.
+.bu
+Install and use the Berkeley DB database interface library on each platform.
+These databases can be shared across big-endian/little-endian platforms
+although a database created on a big-endian platform will suffer a small
+access penalty when used by a litle-endian machine and vice-versa.