mmaann__ddbb--22..33..xx -- tthhee ddaattaabbaassee ccaacchheedd mma...

mmaann__ddbb--22..33..xx -- tthhee ddaattaabbaassee ccaacchheedd mmaannuuaall ppaaggeerr ssuuiittee

_G_r_a_e_m_e _W_. _W_i_l_f_o_r_d _<_e_e_p_2_g_w_@_e_e_._s_u_r_r_e_y_._a_c_._u_k_>

This document describes the setup, maintenance and
use of a generic online manual page system with spe□ cial reference to the man_db-2.3.x package and its
advanced features.

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

UUNNIIXX is a registered trademark of the X/Open Company, Ltd.
NFS is a registered trademark of Sun Microsystems, Inc.
PostScript is a registered trademark of Adobe in the United
States.

The general conventions used throughout this manual include

□file names and paths in _i_t_a_l_i_c, e.g. _/_u_s_r_/_s_h_a_r_e_/_m_a_n.
□variable strings (usually path components) enclosed
within <> and in _i_t_a_l_i_c, eg. _<_s_e_c_>,
□program names in bboolldd, eg. mmaann.
□commands that can be typed at a shell prompt in a |□_b□_o□_x□_|□_,
eg. |□_m□_a□_n□_□_f□_o□_o□_b□_a□_r□_|□_.
□environment variables denoted as follows: $EENNVV__VVAARR

Permission is granted to make and distribute verbatim copies
of this manual provided the copyright notice and this per□mission notice are preserved on all copies.

Permission is granted to copy and distribute modified ver□sions of this manual under the conditions for verbatim copy□ing, provided that the entire resulting derived work is dis□tributed under the terms of a notice identical to this one.

Permission is granted to copy and distribute translations of
this manual into another language, under the above condi□tions for modified versions, except that this permission no□tice may be stated in a translation approved by the copy□right holder.

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

11.. IInnttrroodduuccttiioonn

11..11.. mmaann__ddbb--22..33..xx

man_db-2.3.x is a package that is designed to provide users
with online information in a fast and friendly manner while
at the same time offering flexibility to the system adminis□trator.

It is made up of several user programs:
□□mmaann - an interface to the on-line reference manuals
□□wwhhaattiiss - search the manual page names
□□aapprrooppooss - search the manual page names and descriptions
□□mmaannppaatthh - determine search path for manual pages
several maintenance programs:
□□mmaannddbb - create or update the manual page index caches
□□ccaattmmaann - create or update the pre-formatted manual pages
and a special pre-formatter that knows about compressed manual pages
□□zzssooeelliimm - satisfy .so requests in roff input

In addition to these compiled programs, there are two shell
scripts, mmkkccaattddiirrss and cchheecckkmmaann in the _t_o_o_l_s subdirectory.
These scripts aid the creation of cat directories and check
for duplicated manual pages, respectively.

The following manual pages are provided with this package to
explain correct format and usage. mmaann(1), wwhhaattiiss(1), aapprroo□□ppooss(1), mmaannppaatthh(1), mmaannppaatthh(5), mmaannddbb(8), ccaattmmaann(8) and
zzssooeelliimm(1).

11..11..11.. TThhee ccoonncceepptt

man_db-2.3.x originally started out life as program suite
man-1.1B, written by John W. Eaton <jwe@che.utexas.edu> and
maintained by Rik Faith <faith@cs.unc.edu> to which support
proposed by the newly formed FSSTND committee regarding cat
directories was added.

Since then, man_db-2.3.x's most innovative feature: the
database cache scheme1 has been significantly developed. The
basic idea was to reduce manual page search times to a mini□mum. The following piece of text is included from the
man_db-2.2 distribution:

The theory: If you go to a library to take a book
out, what do you do?
____________________
1 originally conceived after observing the actions of the
perl based manual pager suite, man-pl written by Tom Chris□tiansen <tchrist@convex.com>

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

a) Go and look where it might be on a micro-
fiche/terminal, take a look
where it is supposed to be on the shelf, and then
go look at the new
arrivals if it's not where it's supposed to be?

b) Start at one end of the ground floor, look along
every bookshelf
until you've completed that floor, then go up a
level and start again
until you've found what you're looking for?

Since then the database iinnddeexx scheme has evolved greatly.
Every manual page and stray cat page on the system is regis□tered in an iinnddeexx database cache which stores various
details about the file including the timestamp, the location
and the whatis2 information. This information is kept up to
date by mmaann which looks for filesystem changes each time it
is invoked.

11..22.. TThhee mmaannuuaall ppaaggee ssyysstteemm

The simplest manual page system will have a single manual
page hierarchy. This will typically be

_/_u_s_r_/_m_a_n

beneath which will be several subdirectories of the form
_m_a_n_<_s_e_c_> where _<_s_e_c_> is 11, 22, 33, 44, 55, 66, 77 or 88. These are
referred to as _s_e_c_t_i_o_n_s of the manual. Others may exist and
they are not restricted to single character names. eg.

_/_u_s_r_/_m_a_n_/_m_a_n_f_o_o

is a valid section subdirectory. Other common sections
include 99, nn, ll, pp and oo.

Within these section subdirectories reside the manual pages
themselves. Their filenames follow the pattern

_/_u_s_r_/_m_a_n_/_m_a_n_<_s_e_c_>_/_<_n_a_m_e_>_._<_s_e_c_>_<_e_x_t_>

where in most cases _<_e_x_t_> is an empty string. An example is
manual page ccpp

____________________
2 one line description of the manual page

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

_/_u_s_r_/_m_a_n_/_m_a_n_1_/_c_p_._1

which resides in _s_e_c_t_i_o_n 11 and has no special _e_x_t_e_n_s_i_o_n.

11..33.. SSeeccttiioonnss ooff tthhee mmaannuuaall

The manual is split up into sections to ease access and to
cater for manual pages that share the same name. It is com□mon for a program and function to share the same name. kkiillll
is a good example. This is both a program which can be used
to send a process a signal and an operating system call with
similar functionality. Their manual pages are stored under
sections 11 and 22 respectively. Thus, sections are used to
separate out the program manual pages from the function man□ual pages and so on. The table below shows the _s_e_c_t_i_o_n num□bers of the manual followed by the types of pages they con□tain.

+--------+------------------------------------------------------+
|Section | Section contents |
+--------+------------------------------------------------------+
| 1 | user executable programs or shell commands |
| 2 | system calls (functions provided by the kernel) |
| 3 | library calls (functions within system libraries) |
| 4 | special files (usually found in _/_d_e_v) |
| 5 | file formats and conventions eg. _/_e_t_c_/_p_a_s_s_w_d |
| 6 | games |
| 7 | macro packages and conventions eg. mmaann(7), ggrrooffff(7). |
| 8 | system administration commands |
| 9 | kernel routines [Non standard] |
| n | new [obsolete] |
| l | local [obsolete] |
| p | public [obsolete] |
| o | old [obsolete] |
+--------+------------------------------------------------------+

11..44.. TThhee ffoorrmmaatt ooff mmaannuuaall ppaaggeess

The format in which manual pages are stored is NNRROOFFFF/TTRROOFFFF
or more generally ROFF. This is a typesetter style
language3 which requires formatting before being viewed. In
fact some manual pages require pre-format processing to cor□rectly format tables or equations.

If the page is to be viewed on screen in a text environment,
NNRROOFFFF is used as the primary formatter. If the page is to be
printed or displayed in a graphical environment, TTRROOFFFF is
____________________
3 similar in some aspects to TTeeXX

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

used. Traditionally, TTRROOFFFF formatted files for a CC//AA//TT (Com□puter aided Typesetter) which is now obsolete.

The GGNNUU ROFF (GGRROOFFFF4) suite of programs offer a choice of
output types including XX, ddvvii and ppoossttssccrriipptt. When config□uring man_db-2.3.x, the preference is to use GGRROOFFFF rather
than TTRROOFFFF.

11..55.. AArrgguummeennttss ttoo ccoonnffiigguurree

To allow the configuration program, ccoonnffiigguurree, to be non-
interactive, it can be passed various options to alter the
default settings. Generic ccoonnffiigguurree options are discussed
in _d_o_c_s_/_I_N_S_T_A_L_L. Options that are specific to the
man_db-2.3.x package are described below.

--enable-debug
By default, the configuration process creates produc□ tion quality Makefiles. This option, which takes no
argument, changes certain values to aid in debugging
man_db-2.3.x. It does not alter the physical behaviour
of any of the programs.

--enable-setuid[=ARG]
By default, mmaann will be installed as a setuid program
to user man. Use this option with an argument to
change the setuid owner.

--disable-setuid
Use this option to install mmaann as a non-setuid program
and to change the default cat and database files'
access flags to allow users to modify them.

--enable-mandirs=OS
By default, man_db-2.3.x supports manual page directo□ ries in any of several layouts used by free and propri□ etary versions of UUNNIIXX. However, in certain cases,
this can cause man_db-2.3.x to find the wrong page by
mistake, especially when the names of some manual pages
on the system contain periods. Use this option with an
argument of GNU, HPUX, Solaris, or IRIX (or more than
one of these, separated by commas) to support only the
layouts typically used on each of those systems.

--with-device=DEVICE
Use this flag to alter the default output device used
by NNRROOFFFF. DEVICE is passed to NNRROOFFFF with the -T option.
ccoonnffiigguurree will test that NNRROOFFFF will run with the sup□ plied device argument.
____________________
4 Written and maintained by James Clark <jjc@jclark.com>

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

--with-db=LIBRARY
configure will look for database interface libraries in
the order Berkeley DB, gdbm and finally ndbm and will
#define appropriate variables relative to the first one
found. To override the built in order on platforms hav□ ing a choice of interface library, use this option to
specify which library to use.

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

22.. TThhee ssppeecciiffiiccss ooff SSeeccttiioonnss

22..11.. PPaacckkaaggee ssppeecciiffiicc mmaannuuaall ppaaggee sseeccttiioonnss

The use of package specific manual page sections is discour□aged as packages large enough to warrant their own section
probably contain manual pages that span other sections. An
example might be package ffoooo that has its own section

_/_u_s_r_/_m_a_n_/_m_a_n_f_o_o

which contains manual pages describing its programs, the
library routines it offers and the format of several of its
configuration files. These pages would normally be allocated
to sections 11, 33 and 55 respectively and thus combining them
all under section ffoooo is misleading. Subtle problems will
arise if there are any base name-space clashes with standard
manual pages, eg. eexxiitt(3), eexxiitt(foo) and the order in which
they should be shown.

There are two standard solutions to this problem.

(1) Create a separate manual page hierarchy for the pack□ age's manual pages such as

_/_u_s_r_/_l_o_c_a_l_/_p_a_c_k_a_g_e_s_/_f_o_o_/_m_a_n

(2) Install the pages in their relevant sections, with a
unique extension appended to the filename such that

_/_u_s_r_/_m_a_n_/_m_a_n_f_o_o_/_e_x_i_t_._f_o_o

would instead be installed as

_/_u_s_r_/_m_a_n_/_m_a_n_1_/_e_x_i_t_._1_f_o_o

Only (2) offers a complete solution to manual page ordering
problems and allows users to access the desired page
directly.

22..22.. SSeelleeccttiinngg aa sseeccttiioonn ttyyppee

22..22..11.. SSppeecciiffyyiinngg aa sseeccttiioonn

This is done via use of the section argument to man

|□_m□_a□_n□_□_1□_□_e□_x□_i□_t□_|□_

will look for _e_x_i_t_._1_* in section 11 of the manual. If _e_x_i_t_._1
exists, it will be displayed in preference to _e_x_i_t_._1_f_o_o

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

|□_m□_a□_n□_□_1□_f□_o□_o□_□_e□_x□_i□_t□_|□_

will look for _e_x_i_t_._1_f_o_o_* in section 11 of the manual. The
asterisk (*) represents a wild-card of any type or length,
including length zero.

For an argument to be interpreted as a section name rather
than a page name, it must either begin with a digit, or be
included in the standard section list. The default section
list is defined in _i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h to be 11, nn, ll, 88, 33,
22, 55, 44, 99, 66 and 77. This should be modified in order and
content to meet the local conventions.

Every subdirectory section name in the entire system must be
in the list, including sections found in imported manual
page hierarchies. The order is important because in normal
operation, mmaann will only display the first manual page it
finds that meets the search criteria. Using the ----aallll argu□ment will cause mmaann to attempt to display all manual pages
that meet the criteria. See mmaann(1) for further information.

Having an excess of sections listed will not slow mmaann down.

22..22..22.. SSppeecciiffyyiinngg aann eexxtteennssiioonn

If the section is unknown, but the package extension is, it
is possible to use the extension argument

|□_m□_a□_n□_□_-□_e□_□_f□_o□_o□_□_e□_x□_i□_t□_|□_

to search in all sections for manual pages named _e_x_i_t from
package _f_o_o.

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

33.. FFiilleessyysstteemm ssttrruuccttuurree

33..11.. MMaannuuaall ppaaggee hhiieerraarrcchhiieess

It is often common for manual page systems to have more than
one manual page hierarchy. Indeed one of the systems I use
has the following globally accessible hierarchies

_/_u_s_r_/_m_a_n
_/_u_s_r_/_l_o_c_a_l_/_m_a_n
_/_u_s_r_/_l_o_c_a_l_/_t_e_x_/_m_a_n
_/_u_s_r_/_l_o_c_a_l_/_p_b_m_/_m_a_n
_/_u_s_r_/_X_1_1_R_6_/_m_a_n
_/_u_s_r_/_o_p_e_n_w_i_n_/_m_a_n
_/_u_s_r_/_l_o_c_a_l_/_p_a_c_k_a_g_e_s_/_p_v_m_/_m_a_n

A full system $MMAANNPPAATTHH would be a colon separated list of
these directories. The order is important, and is observed
by man_db's search algorithms. The order is very much
related to the user's $PPAATTHH environment variable, and should
be set on a per user basis, or not set at all. If a user's
$PPAATTHH causes

_/_u_s_r_/_l_o_c_a_l_/_p_a_c_k_a_g_e_s_/_b_i_n_/_f_o_o_b_a_r

to be executed in preference to

_/_u_s_r_/_b_i_n_/_f_o_o_b_a_r,

it is essential that

|□_m□_a□_n□_□_f□_o□_o□_b□_a□_r□_|□_

displays the manual page located within

_/_u_s_r_/_l_o_c_a_l_/_p_a_c_k_a_g_e_s_/_m_a_n

rather than within

_/_u_s_r_/_m_a_n

To ensure correct order, the program mmaannppaatthh may be used to
set the $MMAANNPPAATTHH environment variable. See mmaannppaatthh(1) and
mmaannppaatthh(5) for details.

33..22.. SSeettttiinngg tthhee MMAANNPPAATTHH

If using a Bourne style login shell such as bbaasshh, kksshh, or
zzsshh, the commands

export MANPATH
MANPATH=`manpath -q`

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

can be added to $$HHOOMMEE_/_._p_r_o_f_i_l_e

If using a C style login shell such as ccsshh or ttccsshh, the com□mands

setenv MANPATH `manpath -q`

can be added to $$HHOOMMEE_/_._l_o_g_i_n

N.B. $PPAATTHH must be set prior to using mmaannppaatthh. The setting
of $MMAANNPPAATTHH is actually unnecessary as the man_db-2.3.x
utilities will dynamically determine the manpath if $MMAANNPPAATTHH
is unset.

33..33.. DDeetteerrmmiinnaattiioonn ooff tthhee iinntteerrnnaall mmaannppaatthh

All man_db utilities, mmaannppaatthh included, will use the user's
$MMAANNPPAATTHH environment variable if set and not equal to "".
Otherwise the user's $PPAATTHH environment variable is queried.
If this is unset or is set to "", the determined manpath
will simply be any

MMAANNDDAATTOORRYY__MMAANNPPAATTHH

elements defined in the man_db config file.

Assuming that a $PPAATTHH exists, each path element it contains
is scanned for in the config file. If found, the relative
manpath element is appended to the internal manpath. How□ever, if the element is not mentioned in the config file, a
man directory relative to it will be sought. The subdirec□tories _._._/_m_a_n or _m_a_n relative to the path component are
appended to the internal manpath if they exist. Finally,
the internal manpath is stripped of duplicate paths before
being processed by the NNLLSS and `Other OS' routines. These
may add to or modify the separate path elements giving pri□ority to NNLLSS manual pages or add OS-relative manpaths.

33..44.. OOtthheerr OOSS''ss mmaannuuaall ppaaggeess

It is common to have collections of heterogeneous computer
systems linked together in a network. In some circumstances5
it is advantageous to be able to access the manual pages of
these other systems directly from your system. This feature
is known as alternate system support. The accepted way to
setup this support is to NFS mount the respective systems'
manual page hierarchies under the native manual page hierar□chies. An example:

____________________
5 writing portable software instantly comes to mind

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

Rather than have multiple NFS mounts from a single machine,
this may be accomplished by NFS mounting

_<_o_t_h_e_r_-_s_y_s_>_:_/_u_s_r

somewhere on the local system and using symbolic links
within the manual hierarchies. To access these _a_l_t_e_r_n_a_t_e
_s_y_s_t_e_m_s using mmaann use the --mm option, eg.

|□_m□_a□_n□_□_-□_-□_a□_l□_l□_□_-□_-□_s□_y□_s□_t□_e□_m□_□_u□_s□_e□_r□_i□_x□_:□_n□_e□_w□_O□_S□_□_5□_□_p□_a□_s□_s□_w□_d□_|□_

would provide manual pages showing the structure of
_/_e_t_c_/_p_a_s_s_w_d on systems uusseerriixx and nneewwOOSS in that order. A
manual page would _n_o_t be displayed about the local systems
conventions. Please read the relevant man_db utility's man□ual page for further and more specific information.

33..55.. NNLLSS mmaannuuaall ppaaggeess

NLS manual pages should be put in NLS subdirectories of a
standard manual page hierarchy. A table illustrating the
concept is reproduced from the "Filesystem Hierarchy Stan□dard"6 (FFHHSS) manual from which further information may be
obtained.

____________________
6 written and maintained by Daniel Quinlan <quinlan@yg□gdrasil.com>

1100

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

Each of these directories are then interpreted as manual
page hierarchies themselves and may contain the usual sec□tion subdirectories. Access to NLS manual pages is achieved
via use of the sseettllooccaallee(3) function which queries user
environment variables to determine the current locale.
Internally to the man_db utilities, this locale string is
appended to each manpath element and the resultant NLS man□path element is searched before the standard manpath ele□ment. In this way, an NLS manual page that matches the
search criteria will be shown before or in place of the
standard American English page.

If a user's $MMAANNPPAATTHH consists of or is determined as

_/_u_s_r_/_l_o_c_a_l_/_m_a_n_:_/_u_s_r_/_m_a_n_:_/_u_s_r_/_X_1_1_R_6_/_m_a_n

and their locale is set to ddee__DDEE, the command

|□_m□_a□_n□_□_-□_-□_s□_y□_s□_t□_e□_m□_□_u□_s□_e□_r□_i□_x□_:□_m□_a□_n□_□_f□_o□_o□_b□_a□_r□_|□_

would produce the following internal man_db manpath elements

_/_u_s_r_/_l_o_c_a_l_/_m_a_n_/_u_s_e_r_i_x_/_d_e___D_E
_/_u_s_r_/_l_o_c_a_l_/_m_a_n_/_u_s_e_r_i_x
_/_u_s_r_/_m_a_n_/_u_s_e_r_i_x_/_d_e___D_E
_/_u_s_r_/_m_a_n_/_u_s_e_r_i_x
_/_u_s_r_/_X_1_1_R_6_/_m_a_n_/_u_s_e_r_i_x_/_d_e___D_E
_/_u_s_r_/_X_1_1_R_6_/_m_a_n_/_u_s_e_r_i_x
_/_u_s_r_/_l_o_c_a_l_/_m_a_n_/_d_e___D_E
_/_u_s_r_/_l_o_c_a_l_/_m_a_n
_/_u_s_r_/_m_a_n_/_d_e___D_E
_/_u_s_r_/_m_a_n_/_m_a_n
_/_u_s_r_/_X_1_1_R_6_/_m_a_n_/_d_e___D_E
_/_u_s_r_/_X_1_1_R_6_/_m_a_n

1111

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

ffoooobbaarr would be searched for in the order of manual page
hierarchies listed.

33..55..11.. IISSOO 88885599--11 ((llaattiinn11)) mmaannuuaall ppaaggeess

By default NNRROOFFFF will format manual pages into a form suit□able for a typewriter style device, e.g. a terminal screen.
GGNNUU NNRROOFFFF is capable7 of formatting ROFF into a form suit□able for 8-bit latin1 capable output devices. To enable out□put for such a device, give the option

--with-device=DEVICE

to ccoonnffiigguurree where DEVICE is the suitable and supported out□put format, in this case llaattiinn11.

33..55..22.. DDiissppllaayyiinngg llaattiinn11 cchhaarraacctteerrss oonn aa LLiinnuuxx vviirrttuuaall tteerr□□mmiinnaall

To enable console based viewing of latin1 characters on a
Linux system, you must have the kbd8 package installed. The
following commands included within an initialisation file
such as _/_e_t_c_/_r_c_._d_/_r_c_._l_o_c_a_l will enable the display of latin1
fonts on the first 5 virtual terminals.

---< part of /etc/rc.d/rc.local >---
# sort out the vt font
if [ -x /bin/setfont ]; then
/bin/setfont /etc/kbd/consolefonts/lat1-16.psf
fi

# load the keymap transformation to do when activating new font
if [ -x /bin/mapscrn ]; then
/bin/mapscrn /etc/kbd/consoletrans/trivial
fi

# enable new font
for t in 1 2 3 4 5; do
echo -n -e "\033(K" > /dev/tty$t
done
---< part of /etc/rc.d/rc.local >---

For display under the "X Window System", a suitable 8 bit
clean terminal emulator is required.

____________________
7 see nnrrooffff(5) for the output device formats available
with your NNRROOFFFF
8 written and maintained by Andries Brouwer <aeb@cwi.nl>.
Version 0.90 and above does not require the use of mmaappssccrrnn
as illustrated in the script.

1122

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

33..55..33.. VViieewwiinngg AASSCCIIII ppaaggeess ffoorrmmaatttteedd ffoorr llaattiinn11 oouuttppuutt
ddeevviiccee

When formatting an ASCII manual page for a latin1 output
device, GGNNUU NNRROOFFFF will take advantage of the extra charac□ters available and will always produce a text page contain□ing some latin1 (8-bit) symbols. The table9 below, taken
from mmaann(1) illustrates the differences.

+--------------------+-------+------------+-------+
|Description | Octal | ISO 8859-1 | ASCII |
+--------------------+-------+------------+-------+
|continuation hyphen | 255 | □ | - |
|bullet (middle dot) | 267 | □ | o |
|acute accent | 264 | □ | ' |
|multiplication sign | 327 | □ | x |
+--------------------+-------+------------+-------+

To display such symbols on a 7 bit terminal or terminal emu□lator, they must be translated back into standard ASCII. The
--77 option with mmaann will enable this simple reverse transla□tion.

This option may be useful if your site has both 7 and 8-bit
capable output devices and nroff is using the latin1 output
device to format manual pages.

33..66.. CCaatt ppaaggeess

It has become standard practice to store the formatted man□ual pages on disk so that subsequent requests for the manual
page do not have to involve the formatting process. These
pre-formatted manual pages are known as _c_a_t pages. Although
cat pages require additional disk storage requirements, they
provide a substantial speed increase and their use is recom□mended.

The automatic support of storing and using cat pages is
brought about by simply creating suitable directories for
them.

33..77.. CCaatt ppaaggee hhiieerraarrcchhiieess

Traditionally, cat pages were stored under the same manual
hierarchy as their source manual pages, in _c_a_t_<_s_e_c_> subdi□rectories rather than _m_a_n_<_s_e_c_>. This situation is rather
____________________
9 The ISO 8859-1 and ASCII columns of this table will be
identical if this manual was formatted for an ASCII based
typewriter display, i.e. using NNRROOFFFF in its native mode.

1133

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

limiting in several situations

□When it is advantageous to mount _/_u_s_r as a read-only
filesystem. Cat pages cannot be supported in this situa□ tion without use of symbolic links to various other areas
of the filesystem. This situation is a greater problem if
the media itself is read-only, such as CD-ROM.
□When NFS mounting alternate OS's manual page hierarchies.
The alternate system may be under someone else's control
and they may not want cat pages stored on their system.
In fact it is usually a good idea to export the manual
page filesystems read-only, or import them that way. It
is possible to avoid the problems, this time with even
more symbolic links that may need periodic updating.
□If there is a mixture of normal cat files and stray
cats10, it is very difficult to periodically _t_r_i_m the cat
space disk usage by removing seldom accessed cat files.

To avoid all of these problems simultaneously, it was
decided to support local cat page directory caches.

33..88.. LLooccaall ccaatt ppaaggee ddiirreeccttoorryy ccaacchheess

Any location for cat page hierarchy may be specified in the
man_db configuration file. The location of the database
cache associated with each manual page hierarchy will always
be at the root of the cat page hierarchy. By default, the
cat page hierarchy shadows the manual page hierarchy. The
FFHHSS proposes _/_v_a_r_/_c_a_c_h_e_/_m_a_n as the location for such direc□tories although man_db-2.3.x allows any directory hierarchy
to be used. The FFHHSS path transformation rule is as follows

_/_u_s_r_/_<_h_i_e_r_a_r_□ _c_h_y_>_/_s_h_a_r_e_/_m_a_n_/_<_l_o_c_a_l_e_>_/_m_a_n_<_s_e_c_>_/_p_a_g_e_._<_s_e_c_>_<_e_x_t_>

should be formatted into the cat file

_/_v_a_r_/_c_a_c_h_e_/_m_a_n_/_<_h_i_e_r_a_r_□ _c_h_y_>_/_<_l_o_c_a_l_e_>_/_c_a_t_<_s_e_c_>_/_p_a_g_e_._<_s_e_c_>_<_e_x_t_>

where the _<_l_o_c_a_l_e_> directory component may be missing and
_<_e_x_t_> may be an empty string.

The suggestion is that stray cats are located in the tradi□tional hierarchy under _/_u_s_r whereas re-creatable cat pages
are stored under the local writable hierarchy
_/_v_a_r_/_c_a_c_h_e_/_m_a_n_. mmaann follows strict rules in determining
which file is displayed.
____________________
10 cat files that have no source manual page, i.e. they
cannot be recreated.

1144

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

As an example, the following route is taken if all three
files exist.

(1) Check relative time stamps of the manual file and the
traditional cat file. If the cat file is up to date
(has a more recent time stamp), display it.

(2) The traditional cat file is out of date. Check rela□ tive time stamps of the manual file and the alternate
cat file. If the cat file is up to date, display it.

(3) The alternate cat file is out of date. Format the
manual file and display the result in the foreground,
while updating the alternate cat file in the back□ ground.

1155

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

44.. CCoommpprreessssiioonn

44..11.. CCoommpprreesssseedd mmaannuuaall ppaaggeess

It is possible to maintain a system of compressed manual
pages. The use of this feature is not recommended for sys□tems that have adequate disk space to store their manual
pages uncompressed. Subsequent decompression of these manual
pages will cause several bottlenecks in the formatting pro□cess.

Presently, the compression extension/decompressor pairs must
be known at compile time although any number may be defined
and used. The following structure is predefined in
man_db-2.3.x

+----------+--------------+
|Extension | Decompressor |
+----------+--------------+
|gz | gzip -dc |
|z | gzip -dc |
|Z | compress -dc |
+----------+--------------+

It is a relatively easy operation to include further pairs
in this structure. See _i_n_c_l_u_d_e_/_c_o_m_p___s_r_c_._h for details and an
example.

Support for compressed manual pages is compiled into the
man_db-2.3.x utilities by default. To completely disable
this support, edit _i_n_c_l_u_d_e_/_c_o_n_f_i_g_._h and comment out the fol□lowing line

#define COMP_SRC 1

This will enable a minor speed increase, but note that sup□port for stray cats with any compression extension other
than the default will also be disabled.

44..22.. CCoommpprreesssseedd ccaatt ppaaggeess

man_db-2.3.x compresses cat files by default. During config□uration, ccoonnffiigguurree will try to find ggzziipp and if so, all cat
files produced by mmaann will be compressed with

ggzziipp --77cc

and have a ..ggzz extension appended. If ggzziipp is not found,

ccoommpprreessss --cc

1166

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

is used as the compressor and the extension ..ZZ is appended.

To store cat files in an uncompressed state and to disable
compressed extension processing completely, edit
_i_n_c_l_u_d_e_/_c_o_n_f_i_g_._h and comment out the following line

#define COMP_CAT 1

44..22..11.. SSttrraayy ccaattss

Normally, mmaann will only look for cat files with the default
compression extension. The default compression extension is
dependent on the default compressor and may be an empty
string if the support for compressed cats is disabled.

It is possible for a system to be supplied with stray cat
files located in the traditional cat page hierarchy. To make
matters worse, they may have compression extensions other
than the default and reside on read-only media. In such
circumstances, stray cat files will be accepted with any
compression extension that is also supported for manual
pages.

This special treatment of stray cat pages is removed if sup□port for compressed manual pages is turned off or not avail□able.

1177

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

55.. FFoorrmmaattttiinngg

As already pointed out in the introduction, there are two
primary formatters common to UUNNIIXX: NNRROOFFFF and TTRROOFFFF.

In the following sections, I will use the term TTRROOFFFF to
describe the typesetter formatter and NNRROOFFFF to describe the
typewriter formatter. The term ROFF will be used to describe
a generic formatter.

55..11.. GGRROOFFFF

If using the GGRROOFFFF package, there is a further choice, GGRROOFFFF
itself. Essentially, GGRROOFFFF forms a pipeline of processors
including TTRROOFFFF and an output processor which translates the
ditroff produced by TTRROOFFFF into the appropriate output for□mat. The default output format, or device, for GGRROOFFFF is
PostScript. Anything else must be specified using the
device argument. To illustrate GGRROOFFFF, the command

|□_g□_r□_o□_f□_f□_□_-□_T□_d□_v□_i□_□_/□_d□_e□_v□_/□_n□_u□_l□_l□_|□_

will form the following pipeline

troff -Tdvi /dev/null | grodvi

If GGRROOFFFF is tied to mmaann''ss --TT option, it is still possible
for mmaann to produce ditroff via use of the --ZZ option.

In GGRROOFFFF 1.09, NNRROOFFFF is bundled as a shell script that calls
GGRROOFFFF, which in turn calls TTRROOFFFF with the default options
--WWaallll --mmttttyy--cchhaarr --TTaasscciiii, passing the result through ggrroottttyy
before it finally reaches the screen.

It is imperative that the script does not pass pre-process□ing options to GGRROOFFFF command line as mmaann takes care of this
separately. The file _t_o_o_l_s_/_n_r_o_f_f___s_c_r_i_p_t may be used as a
basis for an NNRROOFFFF script if your system is without one.

55..22.. DDeevviicceess

Both NNRROOFFFF and GGRROOFFFF may allow output device selection. As
mentioned previously, classic NNRROOFFFF produces output suitable
for a typewriter device, classic TTRROOFFFF produces output suit□able for a CC//AA//TT and GGRROOFFFF produces output suitable for a
PostScript interpreting device.

55..33.. MMaaccrrooss

There are several ROFF macros in existence that are suitable
for manual pages. Unfortunately, they tend to be incompati□ble with each other.

1188

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

During configuration, ccoonnffiigguurree will attempt to determine a
suitable macro for the local system's manual page collec□tion. It attempts to use NNRROOFFFF with the following three
macro packages:

The first that succeeds is used. Macro aannddoocc is suitable for
manual pages written using either aann or ddoocc macro commands,
but not a combination of both.

55..44.. PPrree--ffoorrmmaatt pprroocceessssoorrss ((pprree--pprroocceessssoorrss))

Manual pages may require pre-processing by any of the fol□lowing

+--------+----+------------------+
|Program | ID | Pre-processes |
+--------+----+------------------+
|eqn | e | equations |
|tbl | t | tables |
|grap | g | graphs |
|pic | p | pictures |
|refer | r | A bibliography |
|vgrind | v | program listings |
+--------+----+------------------+

It is possible to assign a default pre-processor list that
all manual pages will be passed through prior to the primary
formatter. By default, this is empty. To define a default
list, edit _i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h and un-comment the following
line

/* #define DEFAULT_MANROFFSEQ "t" */

which will enable ttbbll processing by default. To change the
list, replace the tt with a suitable string of processor
ID's.

Pre-process options may be provided at run time in various
forms, but in general the pre-processors required by each
manual page is indicated in the first line of the manual
page itself. See mmaann(1) for details.

1199

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

55..55.. FFoorrmmaatt ssccrriippttss

It is very likely that alternate systems manual pages may
require non-standard macro packages or possibly even special
pre-processors. To tackle such problems, special format
scripts may be created on a per manual hierarchy basis.

If the file

_<_m_a_n_u_a_l___h_i_e_r_a_r_c_h_y_>_/_m_a_n_d_b___n_f_m_t

exists and is executable, it is expected to be able to cor□rectly format a manual page originating from _<_m_a_n_u_a_l___h_i_e_r_a_r_□_c_h_y_> to its standard output. It will be supplied with either
two or three arguments:

□manual page filename
□pre-processor string
□ouput device (optional)

Similarly, if the option --TT_<_d_e_v_i_c_e_> or --tt was supplied to
mmaann and the file

_<_m_a_n_u_a_l___h_i_e_r_a_r_c_h_y_>_/_m_a_n_d_b___t_f_m_t

exists and is executable, it will be used in the same way.

An example of such a script, supplied by Markus Armbruster
<armbru@pond.sub.org>, who provided support for external
formatter scripts, can be found as _t_o_o_l_s_/_m_a_n_d_b___[_n_t_]_f_m_t

The script can be used as both a NNRROOFFFF and TTRROOFFFF/GGRROOFFFF for□mat script and can be installed as _m_a_n_d_b___n_f_m_t and hard
linked to _m_a_n_d_b___t_f_m_t after modification appropriate for your
particular site.

2200

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

66.. TThhee iinnddeexx ddaattaabbaassee ccaacchheess

As mentioned in the introduction, man_db-2.3.x uses database
lookups to search for manual page locations and information.
When performing a manual page lookup or a basic wwhhaattiiss
search, the databases are searched in

_k_e_y _-_> _c_o_n_t_e_n_t

mode and are as fast as the underlying databases can be.
When performing aapprrooppooss or special wwhhaattiiss searches, the
databases are searched in a linear way, which although far
more expensive than _k_e_y_e_d lookup, is no worse than tradi□tional text based file searching.

66..11.. iinnddeexx ddaattaabbaassee llooccaattiioonn

The databases are always located at the root of the cat page
hierarchy, whether this is the same as the manual page hier□archy 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 prob□lems, mmaann can be compiled without database maintenance sup□port. See the section titled "Modes of operation" for
details.

66..11..11.. MMaannuuaall hhiieerraarrcchhiieess wwiitthh nnoo iinnddeexx ddaattaabbaassee

It is possible for the man_db-2.3.x utilities to operate
without aid from an index database. Under such circum□stances, search methods will resort to 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.

66..11..22.. UUsseerr mmaannuuaall ppaaggee hhiieerraarrcchhiieess

A user may have any number of personal manual page hierar□chies listed in their $MMAANNPPAATTHH. By default, mmaann will main□tain mmaannddbb 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 man_db configuration
file. See mmaannppaatthh(5) for details.

66..22.. CCoonntteennttss ooff aann iinnddeexx ddaattaabbaassee

There are four kinds of entry in an index database.

(1) 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

2211

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

up by simply using the name as the key.

(2) 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 com□ mon name index entry that informs of the extensions
available.

(3) 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.

(4) Special identification entries. There are two special
key names, "$mtime$" that references an integer
describing the last modification time of the database
and "$version$" that identifies the database storage
scheme version.

In the following entries, the character "|" will be used to
separate the fields. In reality a tab is used. Direct and
indirect entries takes the form:

_<_n_a_m_e_> _-_>
_<_e_x_t_>_|_<_s_e_c_>_|_<_m_t_i_m_e_>_|_<_I_D_>_|_<_r_e_f_>_|_<_c_o_m_p_>_|_<_w_h_a_t_i_s_>

Common name index entries take the form:

_<_n_a_m_e_> _-_> _|_<_e_x_t_1_>_|_<_e_x_t_2_>_|_<_e_x_t_3_>_| _._._. _<_e_x_t_n_>

and common name direct or indirect entries take the form:

where in each case the filename being represented is formed
as

_<_m_a_n_u_a_l___h_i_e_r_a_r_c_h_y_>_/_m_a_n_<_s_e_c_>_/_<_n_a_m_e_>_._<_e_x_t_>_._<_c_o_m_p_>

in the case of a manual page, or

_<_c_a_t___h_i_e_r_a_r_c_h_y_>_/_c_a_t_<_s_e_c_>_/_<_n_a_m_e_>_._<_e_x_t_>_._<_c_o_m_p_>

in the case of a stray cat.

If any of the fields would be empty, a single "-" is stored
in its place. _<_c_o_m_p_> represents the compression extension.

2222

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

_<_m_t_i_m_e_> is an integer representing the last modification
time of the manual page, _<_r_e_f_> points to the entry contain□ing the location of the real page and _<_I_D_> is one of the
following identification letters.

+---+------------+--------------------------------------------------------+
|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 |
+---+------------+--------------------------------------------------------+

The _I_D 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.

66..22..11.. FFaavvoouurriinngg ssttrraayy ccaattss

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.

If you would like to see the stray cat page kkiillll(1) instead
of the bbaasshh__bbuuiillttiinnss(1) page referenced by kkiillll(1) edit
_i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h and un-comment the following line

/* #define FAVOUR_STRAYCATS */

66..22..22.. AAcccceessssddbb

A simple program, aacccceessssddbb is included with man_db-2.3.x. It
will output the data contained within a man_db database in a
human readable form. By default, it will _d_u_m_p the data from
_/_v_a_r_/_c_a_c_h_e_/_m_a_n_/_i_n_d_e_x_._<_d_b_-_t_y_p_e_>, where _<_d_b_-_t_y_p_e_> is dependent
on the database library in use.

Supplying an argument to aacccceessssddbb will override this
default. Tabs are replaced in the output by a tilde "~" in
the _k_e_y field and a single space in the _c_o_n_t_e_n_t field

aacccceessssddbb is not compiled by default. Type

|□_m□_a□_k□_e□_□_a□_c□_c□_e□_s□_s□_d□_b□_|□_

in the src directory to compile it.

2233

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

66..22..33.. EExxaammppllee ddaattaabbaassee

As an example of both aacccceessssddbb and the database storage
method, the output of

|□_s□_r□_c□_/□_a□_c□_c□_e□_s□_s□_d□_b□_□_m□_a□_n□_/□_i□_n□_d□_e□_x□_.□_b□_t□_|□_

after first running

|□_s□_r□_c□_/□_m□_a□_n□_d□_b□_□_m□_a□_n□_|□_

from the top level build directory is included below.

$mtime$ -> "795987034"
$version$ -> "2.3.1"
apropos -> "1 1 795981542 A - - search the manual page names and descriptions"
catman -> "8 8 795981544 A - - create or update the pre-formatted manual pages"
man -> "1 1 795981542 A - - an interface to the on-line reference manuals"
mandb -> "8 8 795981544 A - - create or update the manual page index caches"
manpath -> " 1 5"
manpath~1 -> "1 1 795981542 A - - determine search path for manual pages"
manpath~5 -> "5 5 795981543 A - - format of the /etc/man_db.config file"
whatis -> "1 1 795981543 A - - search the manual page names"
zsoelim -> "1 1 795981543 A - - satisfy .so requests in roff input"

66..33.. DDaattaabbaassee ttyyppeess

man_db-2.3.x has support for various low level database
libraries commonly in use today. The interfaces to the
libraries are known as

□ndbm (UUNNIIXX)
□gdbm (GGNNUU)
□btree (Berkeley DB)

man_db-2.3.x currently does not hold more than one database
open at any time, so

□dbm (UUNNIIXX)

support could be added in the future.

66..44.. lliimmiittaattiioonnss

The general differences and limitations are best compared in
a table.

2244

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

Those types that have no built in concurrent access strat□egy, are provided with fflloocckk(2) based file locking by
man_db-2.3.x.

As bbttrreeee is noticeably faster when doing mmaann searches,
mainly due to the fast initialization of the databases, it
is the preferred library interface. ccoonnffiigguurree will look for
bbttrreeee, ggddbbmm and then finally nnddbbmm routines when configuring
man_db-2.3.x.

66..55.. SShhaarriinngg ddaattaabbaasseess iinn aa hheetteerrooggeenneeoouuss eennvviirroonnmmeenntt
It may be necessary or advantageous to share databases
across platforms, regardless of the potential file locking
problems.

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.

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.

□Hack the _i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h file on each platform to
provide a unique database name for each system. No
databases will be shared.
□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.

____________________
11 ndbm databases are physically represented by two
files: _i_n_d_e_x_._d_i_r and _i_n_d_e_x_._p_a_g but are referred to simply as
_i_n_d_e_x by the interface routines.

2255

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

77.. MMiisscceellllaanneeoouuss

77..11.. MMooddeess ooff ooppeerraattiioonn

The man_db utilities can operate in many different modes,
allowing varying degrees of freedom, functionality and secu□rity. No mode requires that the manual page hierarchies be
writable.

(1) Default mode
mmaann is setuid to the user MAN_OWNER which is `man' by
default and is changeable via options to ccoonnffiigguurree.
mmaannddbb, if run by the superuser or MAN_OWNER, creates
globally accessible index databases owned by MAN_OWNER.
Once the databases are created, mmaann will update entries
in them if it finds newly installed manual pages (if
the ----uuppddaattee flag is used) or delete entries if manual
pages are removed. In this mode it is possible for a
malicious mmaann user to deliberately lock a database as a
writer, thus denying read access to other users.
If cat directories exist and have the correct permis□ sions, mmaann will take care of producing cat files.
These will be owned by MAN_OWNER. The default permis□ sions of both cat files and databases are 0644.

(2) No man database updates
This mode also requires mmaann to be setuid, but is
favoured where databases must be shared in an environ□ ment unfriendly to kernel locking procedures, eg. NFS.
It also prevents possible `denial of service' attacks
by malicious mmaann users as mmaann never opens the databases
as a writer in this mode. To replace the functionality
lost by disallowing mmaann write access to the databases,
mmaannddbb should be rerun whenever new manual pages are
installed. Otherwise, mmaann will not be able to use the
database to find and display the newly added manual
pages, and will have to use the filesystem instead.
Each index database may be owned by an arbitrary user
who will have subsequent write access to the database.
Cat files are created in the same way as for mode (1)
above.
To use the man_db utilities in this mode, edit
_i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h and comment out `#define
MAN_DB_UPDATES'.

(3) No man database updates or cat production
mmaann is installed not setuid. This mode of operation
probably offers the highest level of security but it
requires higher levels of maintenance than other modes
due to the restrictions imposed upon mmaann. Each
database is owned by an arbitrary user as in mode (2).
Each cat hierarchy is also owned by an arbitrary user
who is responsible for creating cat files using ccaattmmaann

2266

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

whenever new manual files are installed. mmaann will be
completely passive in its action, ie. no index
databases will be written to and no cat files are ever
produced.
To use the man_db utilities in this mode, supply the
option `--disable-setuid' to ccoonnffiigguurree and edit
_i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h, commenting out `#define
MAN_DB_UPDATES' and `#define MAN_CATS' after running
ccoonnffiigguurree, or build man_db as in mode (1) and install
the binaries without the setuid bit set.

(4) Wide open
mmaann is installed not setuid. This mode is similar in
operation to the majority of vendor supplied, non
setuid, cat file supporting manual pager suites. It is
not recommended. The databases are owned by an arbi□ trary user who maintains them using mmaannddbb. mmaann does
not update the databases. Cat files are produced and
stored in world writable cat directories and have world
write access themselves.
To use the man_db utilities in this mode, supply the
option `--disable-setuid' to ccoonnffiigguurree, edit
_i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h and comment out `#define
MAN_DB_UPDATES' and change the definition of CATMODE
from 0644 to 0666.

Other variations can also be used. In fact it is possible
for mmaann to actually create index databases, usually the job
of mmaannddbb, for users private manual page hierarchies. This is
enabled by editing _i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h and un-commenting the
`/* #define MAN_DB_CREATES */' line. man_db-2.2 operated in
this manner.

In summary, _i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h contains definitions for

□MAN_DB_CREATES
□MAN_DB_UPDATES
□MAN_CATS
□CATMODE
□DBMODE

and the setuid installation and operation of mmaann is modified
by supplying either of the following options to ccoonnffiigguurree:

□--enable-setuid=USER
□--disable-setuid

77..22.. NNFFSS rroooott ssqquuaasshh

If mmaann is installed setuid to an arbitrary user and is run
by root, instead of gaining the effective user id of the
setuid user, mmaann is run with both uid and euid as root.
This is neccesary due to infelicities with the PPOOSSIIXX

2277

mmaann__ddbb--22..33..xx mmaannuuaall vv00..66 MMaarrcchh 1155,, 22000022

setuid() function call: All users except root may change to
and from the effective (setuid) user, however once root has
setuid(user), there is no way back.

A side effect of this is that NNFFSS mounted cat hierarchies or
databases will be unwritable if the following conditions
exist:

□man/catman/mandb is run by root
□The NFS mount has the root squash flag set

To get around this problem, the root user must first attain
the ID of the cat hierarchy or database owner before running
mmaann//ccaattmmaann//mmaannddbb whenever the databases need updating or cat
files are to be produced.

77..33.. NNLLSS mmeessssaaggee ccaattaalloogguueess

man_db-2.3.x has built in support for native language mes□sage catalogues. That is, it can issue messages in the
locale of the user's choice. This will only occur if the
locale's translation has been written. Before undertaking a
translation, please contact the author who will be maintain□ing a list of such activity.

Currently, the following translations exist

□de_DE.88591

77..44.. CCrreeddiittss

I would like to thank the following people for their time,
effort, support, ideas and code which went into man_db-2.3.x

Markus Armbruster <armbru@pond.sub.org>
Lionel Cons & colleages <cons@dxcern.cern.ch>
Carl Edman <cedman@princeton.edu>
Caleb Epstein <epstein_caleb@jpmorgan.com>
Lars Fenneberg <lf@gimli.comlink.de>
Zoltan Hidvegi <hzoli@cs.elte.hu>
Nils Magnus <magnus@unix-ag.uni-kl.de>
Daniel Quinlan <quinlan@yggdrasil.com>
Fabrizio Polacco <fpolacco@debian.org>

2288

Glossary

manual page
A file containing descriptions related to the use of a
function or program or the structure of a file. The
name of the file is formed from the title of the manual
page followed by a period followed by the name of the
section that it resides in, optionally followed by an
extension. The format of the file is NNRROOFFFF and may be
compressed, having a suitable compression extension
appended.

cat page
A formatted manual page suitable for viewing on a
vt100-type terminal.

stray cat page
A cat page that does not have a relative manual page on
the system, ie. only the cat page was supplied or the
manual page was removed after the cat page had been
created.

section
Each manual page or cat page hierarchy is divided into
sections, each section having its own directory. Manual
page hierarchy section names begin with `man' and cat
page sections with `cat'.

extension
A package may provide manual pages with filenames end□ ing in a package-specific extension name. This allows
manual pages with the same title to coexist in the same
manual page hierarchy and section without sharing the
same filename. It also provides a further mechanism
for man to select the correct manual page.

manual page hierarchy
A directory tree divided into manual page sections,
each containing a collection of manual pages.

cat page hierarchy
A directory tree divided into cat page sections, each
containing a collection of cat pages.

traditional cat page hierarchy
The same location as the manual page hierarchy.

alternate cat page hierarchy
A separate location to that of the traditional cat page
hierarchy.

traditional cat page
A cat page located in a traditional cat page hierarchy.

alternate cat page
A cat page located in an alternate cat page hierarchy.

iiii

Contents

1. Introduction ...................................... 1
1.1 man_db-2.3.x ................................. 1
1.1.1 The concept ........................... 1
1.2 The manual page system ....................... 2
1.3 Sections of the manual ....................... 3
1.4 The format of manual pages ................... 3
1.5 Arguments to configure ....................... 4

2. The specifics of Sections ......................... 6
2.1 Package specific manual page sections ........ 6
2.2 Selecting a section type ..................... 6
2.2.1 Specifying a section .................. 6
2.2.2 Specifying an extension ............... 7

3. Filesystem structure .............................. 8
3.1 Manual page hierarchies ...................... 8
3.2 Setting the MANPATH .......................... 8
3.3 Determination of the internal manpath ........ 9
3.4 Other OS's manual pages ...................... 9
3.5 NLS manual pages ............................. 10
3.5.1 ISO 8859-1 (latin1) manual pages ...... 12
3.5.2 Displaying latin1 characters on a
Linux virtual terminal ....................... 12
3.5.3 Viewing ASCII pages formatted for
latin1 output device ......................... 13
3.6 Cat pages .................................... 13
3.7 Cat page hierarchies ......................... 13
3.8 Local cat page directory caches .............. 14

4. Compression ....................................... 16
4.1 Compressed manual pages ...................... 16
4.2 Compressed cat pages ......................... 16
4.2.1 Stray cats ............................ 17

5. Formatting ........................................ 18
5.1 GGRROOFFFF ........................................ 18
5.2 Devices ...................................... 18
5.3 Macros ....................................... 18
5.4 Pre-format processors (pre-processors) ....... 19
5.5 Format scripts ............................... 20

6. The index database caches ......................... 21
6.1 index database location ...................... 21
6.1.1 Manual hierarchies with no index
database ..................................... 21
6.1.2 User manual page hierarchies .......... 21
6.2 Contents of an index database ................ 21
6.2.1 Favouring stray cats .................. 23
6.2.2 Accessdb .............................. 23
6.2.3 Example database ...................... 24

6.3 Database types ............................... 24
6.4 limitations .................................. 24
6.5 Sharing databases in a heterogeneous envi□ ronment ........................................... 25

7. Miscellaneous ..................................... 26
7.1 Modes of operation ........................... 26
7.2 NFS root squash .............................. 27
7.3 NLS message catalogues ....................... 28
7.4 Credits ...................................... 28

iiii

about this index... about Greenstone...