













[4mGraeme[24m [4mW.[24m [4mWilford[24m [4m<eep2gw@ee.surrey.ac.uk>[0m
[4mColin[24m [4mWatson[24m [4m<cjwatson@debian.org>[0m




This  document  describes  the  setup, maintenance and use of a generic online
manual page system with special reference to the man-db package  and  its  ad-
vanced features.











































[1mUNIX [22mis 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 e.g.  variable strings (usually path components) enclosed  within  <>
and in eg.  program names in eg.  commands that can be typed at a shell prompt
in a eg.  environment variables denoted as follows: $Copyright (C) 1995 Graeme
W. Wilford
Copyright (C) 2001, 2002, 2003, 2007 Colin Watson

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

Permission  is granted to copy and distribute modified versions of this manual
under the conditions for verbatim copying, provided that the entire  resulting
derived work is distributed 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 conditions  for  modified  versions,  except
that  this  permission  notice  may be stated in a translation approved by the
copyright holder.














































































































0.  Introduction
    0.0  man-db
    man-db is a package that is designed to provide users with online informa-
    tion  in a fast and friendly manner while at the same time offering flexi-
    bility to the system administrator.
    It is made up of several user programs:
             [1m+o man       [22m- an interface to the on-line reference manuals
             [1m+o whatis    [22m- search the manual page names
             [1m+o apropos   [22m- search the manual page names and descriptions
             [1m+o manpath   [22m- determine search path for manual pages
             [1m+o lexgrog   [22m- directly read header information in manual pages
    several maintenance programs:
             [1m+o mandb     [22m- create or update the manual page index caches
             [1m+o catman    [22m- create or update the pre-formatted manual pages
    and a special pre-formatter that knows about compressed manual pages:
             [1m+o zsoelim   [22m- satisfy .so requests in roff input

    In addition to these compiled programs, there are two shell  scripts,  and
    in  the  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.
    and
         0.0.0  The concept
         man-db 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's most innovative feature: the database cache scheme
          originally conceived after observing the actions of  the  Perl-based
         manual  pager suite, man-pl written by Tom Christiansen <tchrist@con-
         vex.com> has been significantly developed. The basic idea was to  re-
         duce  manual  page  search times to a minimum. 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?

         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?

         OR

         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
         scheme has evolved greatly.  Every manual page and stray cat page  on
         the  system  is  registered in an database cache which stores various
         details about the file including the timestamp, the location and  the
         whatis
          one  line description of the manual page information.  This informa-
         tion is kept up to date by regular runs of In some configurations al-
         so  looks for filesystem changes each time it is invoked and helps to
         keep the database cache current, but this imposes a penalty on manual
         page search times.
    0.0  The manual page system
    The  simplest manual page system will have a single manual page hierarchy.
    This will typically be beneath which will be several subdirectories of the
    form where is or These are referred to as of the manual.  Others may exist
    and they are not restricted to single character names.  eg.   is  a  valid
    section subdirectory.  Other common sections include and Within these sec-
    tion subdirectories reside the manual pages  themselves.  Their  filenames
    follow  the pattern where in most cases is an empty string.  An example is
    manual page which resides in and has no special
    0.0  Sections of the manual
    The manual is split up into sections to ease access and to cater for manu-
    al  pages  that share the same name.  It is common for a program and func-
    tion to share the same name.  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
    and  respectively.   Thus,  sections  are used to separate out the program
    manual pages from the function manual pages and so on.   The  table  below
    shows  the  numbers 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 [4m/dev[24m)                |
         |   5    | file formats and conventions eg. [4m/etc/passwd[24m         |
         |   6    | games                                                |
         |   7    | macro packages and conventions eg. [1mman[22m(7), [1mgroff[22m(7). |
         |   8    | system administration commands                       |
         |   9    | kernel routines [Non-standard]                       |
         |   n    | new [obsolete]                                       |
         |   l    | local [obsolete]                                     |
         |   p    | public [obsolete]                                    |
         |   o    | old [obsolete]                                       |
         +--------+------------------------------------------------------+
    0.0  The format of manual pages
    The format in which manual pages are stored is [1mNROFF[22m/[1mTROFF [22mor more  gener-
    ally ROFF.  This is a typesetter style language
     similar in some aspects to which requires formatting before being viewed.
    In fact some manual pages require pre-format processing to correctly  for-
    mat  tables or equations.  If the page is to be viewed on screen in a text
    environment, [1mNROFF [22mis used as the primary formatter. If the page is to  be
    printed or displayed in a graphical environment, [1mTROFF [22mis used. Tradition-
    ally, [1mTROFF [22mformatted files for a (Computer aided Typesetter) which is now
    obsolete.

    The [1mGNU [22mROFF ([1mGROFF[22m)
     Written by James Clark <jjc@jclark.com> and now maintained by Ted Harding
    <ted.harding@nessie.mcc.ac.uk> and Werner Lemberg  <wl@gnu.org>  suite  of
    programs  offer  a  choice  of output types including and When configuring
    man-db, the preference is to use [1mGROFF [22mrather than [1mTROFF[22m.
    0.0  Arguments to configure
    To allow the configuration program,  to  be  non-interactive,  it  can  be
    passed various options to alter the default settings.  Generic options are
    discussed in Options that are specific to the man-db package are described
    below.   By  default,  system-wide  cache files will be owned by user man.
    Use this option with an argument to change the cache file owner.  Use this
    option  to  leave  the ownership of system-wide cache files unconstrained.
    Users will be allowed to modify them.  By default, will be installed as  a
    setuid  program  to  the  user that owns the system-wide cache files.  Use
    this option to install as  a  non-setuid  program  instead.   By  default,
    man-db  supports manual page directories in any of several layouts used by
    free and proprietary versions of [1mUNIX[22m.  However, in  certain  cases,  this
    can  cause  man-db  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, IRIX, Solaris, or BSD (or more than one of
    these, separated by commas) to support only the layouts typically used  on
    each of those systems.  Note that man-db is not currently capable of writ-
    ing cat pages in the proper BSD layout.  Use this flag to  alter  the  de-
    fault  output  device used by [1mNROFF[22m. DEVICE is passed to [1mNROFF [22mwith the -T
    option.  will test that [1mNROFF [22mwill run with the supplied device  argument.
    configure  will  look  for database interface libraries in the order gdbm,
    Berkeley DB and finally ndbm and will #define appropriate variables  rela-
    tive  to the first one found.  To override the built-in order on platforms
    having a choice of interface library, use this option to specify which li-
    brary to use.  If this flag is used, will automatically create index data-
    bases for users' private manual page hierarchies.  Normally,  will  update
    entries  in  index  databases if it finds newly installed manual pages (if
    the flag is used) or delete entries if manual  pages  are  removed.   This
    flag  suppresses this behaviour.  Normally, will automatically try to cre-
    ate cat files corresponding to manual files when a manual  page  is  read.
    This flag suppresses this behaviour.





























































0.  The specifics of Sections
    0.0  Package specific manual page sections
    The  use  of package specific manual page sections is discouraged as pack-
    ages large enough to warrant their own  section  probably  contain  manual
    pages  that span other sections.  An example might be package that has its
    own section which contains manual pages describing its programs,  the  li-
    brary  routines  it  offers and the format of several of its configuration
    files.  These pages would normally be allocated to  sections  and  respec-
    tively  and  thus  combining them all under section is misleading.  Subtle
    problems will arise if there are any base name-space clashes with standard
    manual  pages,  e.g.   and the order in which they should be shown.  There
    are two standard solutions to this problem.  Create a separate manual page
    hierarchy  for  the  package's  manual  pages such as Install the pages in
    their relevant sections, with a unique extension appended to the  filename
    such  that  would instead be installed as Only (2) offers a complete solu-
    tion to manual page ordering problems and allows users to access  the  de-
    sired page directly.
    0.0  Selecting a section type
         0.0.0  Specifying a section
         This  is done via use of the section argument to man will look for in
         section of the manual.  If exists, it will be displayed in preference
         to  will  look for in section of the manual.  The asterisk (*) repre-
         sents 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  stan-
         dard  section list.  The default section list is defined in to be and
         This should be modified in order and content to meet the  local  con-
         ventions.   It  may be altered at run-time using the directive in the
         man-db configuration file.  Every subdirectory section  name  in  the
         entire  system  must  be in the list, including sections found in im-
         ported manual page hierarchies.  It is not necessary to list sections
         with extensions unless a special ordering for those extensions is de-
         sired.  The order is important because in normal operation, will only
         display  the  first manual page it finds that meets the search crite-
         ria. Using the argument will cause to attempt to display  all  manual
         pages that meet the criteria. See for further information.  Having an
         excess of sections listed will not slow down.
         0.0.0  Specifying an extension
         If the section is unknown, but the package extension is, it is possi-
         ble to use the extension argument to search in all sections for manu-
         al pages named from package

























0.  Filesystem structure
    0.0  Manual page hierarchies
    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 global-
    ly accessible hierarchies /usr/man
    /usr/local/man
    /usr/local/tex/man
    /usr/local/pbm/man
    /usr/X11R6/man
    /usr/openwin/man
    /usr/local/packages/pvm/man A full system $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 $environ-
    ment  variable,  and should be set on a per user basis, or not set at all.
    If a user's $causes to be executed in preference to it is  essential  that
    displays  the manual page located within rather than within To ensure cor-
    rect order, the program may be used to set the $environment variable.  See
    and for details.
    0.0  Setting the MANPATH
    If using a Bourne style login shell such as or the commands export MANPATH
    MANPATH=`manpath  -q`  can be added to If using a C style login shell such
    as or the commands setenv MANPATH `manpath -q` can be added to N.B.  $must
    be  set  prior  to  using  The  setting of $is actually unnecessary as the
    man-db utilities will dynamically determine the manpath if $is unset.
    0.0  Determination of the internal manpath
    All man-db utilities, included, will use the user's $environment  variable
    if set and not equal to "".  Otherwise the user's $environment variable is
    queried.  If this is unset or is set to "", the  determined  manpath  will
    simply be any elements defined in the man-db config file.  Assuming that a
    $exists, each path element it contains is scanned for in the config  file.
    If  found,  the  corresponding manpath element is appended to the internal
    manpath.  However, if the element is not mentioned in the config  file,  a
    man  directory relative to it will be sought.  The subdirectories or rela-
    tive to the path component are appended to the internal  manpath  if  they
    exist.   Finally,  the internal manpath is stripped of duplicate paths be-
    fore being processed by the and `Other OS' routines.  These may add to  or
    modify  the  separate path elements giving priority to manual pages or add
    OS-relative manpaths.
    0.0  Other OS's manual pages
    It is common to have collections of heterogeneous computer systems  linked
    together in a network.  In some circumstances
     writing  portable  software instantly comes to mind 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 ac-
    cepted way to setup this support is to NFS mount the  respective  systems'
    manual  page hierarchies under the native manual page hierarchies.  An ex-
    ample:

                        +--------+-----------------------+
                        |System  | Manual page hierarchy |
                        +--------+-----------------------+
                        |<local> | /usr/share/man        |
                        |newOS   | /usr/share/man/newOS  |
                        |userix  | /usr/share/man/userix |
                        |<local> | /usr/local/man        |
                        |newOS   | /usr/local/man/newOS  |
                        |userix  | /usr/local/man/userix |
                        +--------+-----------------------+
    Rather than have multiple NFS mounts from a single machine,  this  may  be
    accomplished  by NFS mounting somewhere on the local system and using sym-
    bolic links within the manual hierarchies.  To access these using use  the
    or  option,  eg.   would  provide manual pages showing the structure of on
    systems and in that order.  A manual page would be displayed about the lo-
    cal systems conventions.  Please read the relevant man-db utility's manual
    page for further and more specific information.
    0.0  NLS manual pages
    NLS manual pages should be installed in NLS subdirectories of  a  standard
    manual  page  hierarchy.  The subdirectory names should be made up of lan-
    guage, territory, and character set components as necessary to specify the
    locale  of the manual page.  The character set component describes the en-
    coding of the manual page itself, and not the encoding in use by the user;
    a  manual page installed under the subdirectory will be used in the locale
    as well as and converted between encodings as necessary.  If no  character
    set  is  specified in the subdirectory name, man-db will attempt to detect
    whether each page is encoded using UTF-8 or a legacy character set  appro-
    priate  for  the  language.   Accordingly,  the recommended scheme for in-
    stalling manual pages is to encode them in UTF-8 (or, if that is not prac-
    tical,  in  the  legacy  character  set) and install them in directories a
    character set component in their names.  The territory should normally  be
    omitted  unless it is necessary to describe the manual page text.  For ex-
    ample, Brazilian Portuguese is  quite  distinct  from  Portuguese  and  so
    should  be  installed  under  the subdirectory, but a single German manual
    page will typically suffice in Austria as well as in Germany and so should
    be installed under the subdirectory.  The following table gives some exam-
    ples.

   +---------+-------------+-----------------+---------------------------------+
   |Language | Territory   | Character Set   | Directory                       |
   +---------+-------------+-----------------+---------------------------------+
   |French   | any         | UTF-8 or        | /usr/share/man/fr               |
   |         |             | ISO-8859-1      |                                 |
   |French   | Canada      | ISO 8859-1      | /usr/share/man/fr_CA            |
   |French   | any         | UTF-8           | /usr/share/man/fr.UTF-8         |
   |German   | Germany     | UTF-8           | /usr/share/man/de_DE.UTF-8      |
   |German   | Switzerland | ISO 8859-1      | /usr/share/man/de_CH.ISO-8859-1 |
   |Japanese | Japan       | UTF-8 or EUC-JP | /usr/share/man/ja_JP            |
   |Japanese | Japan       | EUC-JP          | /usr/share/man/ja_JP.EUC-JP     |
   |Japanese | any         | UTF-8           | /usr/share/man/ja.UTF-8         |
   +---------+-------------+-----------------+---------------------------------+
    On  systems  supporting  UTF-8, it is recommended that all manual pages be
    encoded using UTF-8 where possible, in order to simplify the task of edit-
    ing a variety of pages without reconfiguring editors and terminals and the
    like.  Each of these directories are then interpreted as manual page hier-
    archies  themselves and may contain the usual section subdirectories.  Ac-
    cess to NLS manual pages is achieved via use of the 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  ele-
    ment and the resultant NLS manpath element is searched before the standard
    manpath element.  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 $consists of or is determined as and  their  locale  is
    set to the command would produce the following internal man-db manpath el-
    ements
    /usr/local/man/userix/de_DE
    /usr/local/man/userix/de
    /usr/local/man/userix
    /usr/share/man/userix/de_DE
    /usr/share/man/userix/de
    /usr/share/man/userix
    /usr/X11R6/man/userix/de_DE
    /usr/X11R6/man/userix/de
    /usr/X11R6/man/userix
    /usr/local/man/de_DE
    /usr/local/man/de
    /usr/local/man
    /usr/share/man/de_DE
    /usr/share/man/de
    /usr/share/man
    /usr/X11R6/man/de_DE
    /usr/X11R6/man/de
    /usr/X11R6/man
    would be searched for in the order of manual page hierarchies listed.  Ad-
    ditional  directories  corresponding  to manual pages encoded in different
    character sets would be used if present.
         0.0.0  ISO 8859-1 (latin1) manual pages
         By default [1mNROFF [22mwill format manual pages into a form suitable for  a
         typewriter style device, e.g. a terminal screen. [1mGNU NROFF [22mis capable
          see  for the output device formats available with your [1mNROFF [22mof for-
         matting ROFF into a form suitable for 8-bit latin1 capable output de-
         vices.  To  enable output for such a device, give the option to where
         DEVICE is the suitable and supported output format, in this case
         0.0.0  Displaying non-ASCII characters on a Linux virtual terminal
         To view non-ASCII characters at the Linux console, you must have  one
         of the kbd and console-tools packages installed.
          written  and  maintained  by  Andries Brouwer <aeb@cwi.nl>.  If your
         system does not come with suitable configuration already, then please
         see the documentation in the kbd or console-tools package for details
         on how to configure the console for your locale.  On modern  systems,
         the best choice is likely to be to use the UTF-8 encoding with a font
         suitable for your language.  Make sure that your  locale  environment
         variables  match  the encoding displayed by the console.  For display
         under the a suitable 8-bit-clean terminal emulator is required.
         0.0.0  Viewing ASCII pages formatted for latin1 output device
         When formatting an ASCII manual page for a latin1 output device,  [1mGNU[0m
         [1mNROFF  [22mwill take advantage of the extra characters available and will
         always produce a text page containing some  latin1  (8-bit)  symbols.
         The table
          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  [1mNROFF  [22min  its native mode.  below, taken from illustrates the
         differences.

                  +--------------------+-------+------------+-------+
                  |Description         | Octal | ISO 8859-1 | ASCII |
                  +--------------------+-------+------------+-------+
                  |continuation hyphen |  255  |            |   -   |
                  |bullet (middle dot) |  267  |     +o      |   o   |
                  |acute accent        |  264  |     '      |   '   |
                  |multiplication sign |  327  |     x      |   x   |
                  +--------------------+-------+------------+-------+
         To display such symbols on a 7 bit  terminal  or  terminal  emulator,
         they  must  be  translated back into standard ASCII.  The option with
         will enable this simple reverse translation.  This option may be use-
         ful  if  your  site  has  both 7 and 8-bit capable output devices and
         nroff is using the latin1 output device to format manual pages.
    0.0  Cat pages
    It has become standard practice to store the  formatted  manual  pages  on
    disk  so  that  subsequent requests for the manual page do not have to in-
    volve the formatting process.  These pre-formatted manual pages are  known
    as  pages.   Although  cat  pages require additional disk storage require-
    ments, they provide a substantial speed increase and their use  is  recom-
    mended.   The automatic support for storing and using cat pages is brought
    about by simply creating suitable directories for them.
    0.0  Cat page hierarchies
    Traditionally, cat pages were stored under the same  manual  hierarchy  as
    their source manual pages, in subdirectories rather than This situation is
    rather limiting in several situations: When it is advantageous to mount as
    a  read-only  filesystem.  Cat pages cannot be supported in this situation
    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 cats,
     cat files that have no source manual page, i.e. they cannot be recreated.
    it  is very difficult to periodically 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.
    0.0  Local cat page directory caches
    Any location for cat page hierarchy may be specified in the man-db config-
    uration file.  The location of the database  cache  associated  with  each
    manual  page  hierarchy will always be at the root of the cat page hierar-
    chy.  By default, the cat page hierarchy shadows the manual  page  hierar-
    chy.   The  [1mFHS  [22mproposes  as  the location for such directories, although
    man-db allows any directory hierarchy to be used.  The [1mFHS [22mpath  transfor-
    mation rule is as follows: should be formatted into the cat file where the
    directory component may be missing and may be an empty string.   The  sug-
    gestion  is that stray cats are located in the traditional hierarchy under
    whereas re-creatable cat pages are stored under the local writable hierar-
    chy  follows  strict  rules in determining which file is displayed.  As an
    example, the following route is taken if all  three  files  exist.   Check
    relative  modification  time stamps of the manual file and the traditional
    cat file.  If the cat file is up to date (has an equal time  stamp),  dis-
    play  it.   The  traditional cat file is out of date.  Check relative time
    stamps of the manual file and the alternate cat file.  If the cat file  is
    up  to  date,  display it.  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 background.  When a cat file is created, its
    time stamp is set to that of the corresponding manual file.  Manual  files
    are  often stored in archives, and time stamps may be preserved when these
    archives are unpacked.  Simply checking whether  the  cat  file  is  newer
    would  sometimes  cause  to  display an out-of-date cat file in this case,
    when it should have reformatted the manual file instead.






































0.  Compression
    0.0  Compressed manual pages
    It is possible to maintain a system of compressed manual pages.  This  im-
    poses a small overhead on the formatting process, but is nevertheless usu-
    ally reasonable in order to avoid unnecessary consumption of  disk  space.
    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:

                            +----------+--------------+
                            |Extension | Decompressor |
                            +----------+--------------+
                            |gz        | gzip -dc     |
                            |z         | gzip -dc     |
                            |Z         | compress -dc |
                            +----------+--------------+
    It  is a relatively easy operation to include further pairs in this struc-
    ture.  See for details and an  example.   Support  for  compressed  manual
    pages  is  compiled  into  the man-db utilities by default.  To completely
    disable this support, edit and comment  out  the  following  line  #define
    COMP_SRC  1 This will enable a minor speed increase, but note that support
    for stray cats with any compression extension other than the default  will
    also be disabled.
    0.0  Compressed cat pages
    man-db compresses cat files by default.  During configuration, will try to
    find and, if found, all cat files produced by will be compressed with  and
    have a extension appended.  If is not found, is used as the compressor and
    the extension is appended.  To store cat files in  an  uncompressed  state
    and  to  disable compressed extension processing completely, edit and com-
    ment out the following line #define COMP_CAT 1
         0.0.0  Stray cats
         Normally, will only look for cat files with the  default  compression
         extension.  The default compression extension is dependent on the de-
         fault compressor and may be an empty string if the support  for  com-
         pressed 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  circum-
         stances, stray cat files will be accepted with any compression exten-
         sion that is also supported for manual pages.  This special treatment
         of  stray cat pages is removed if support for compressed manual pages
         is turned off or not available.
























0.  Formatting
As already pointed out in the introduction, there are two  primary  formatters
common  to  [1mUNIX[22m:  [1mNROFF [22mand [1mTROFF[22m.  In the following sections, I will use the
term [1mTROFF [22mto describe the typesetter formatter  and  [1mNROFF  [22mto  describe  the
typewriter  formatter.   The term ROFF will be used to describe a generic for-
matter.
    0.0  [1mGROFF[0m
    If using the [1mGROFF [22mpackage, there is a further choice, [1mGROFF [22mitself.   Es-
    sentially,  [1mGROFF  [22mforms  a  pipeline of processors including [1mTROFF [22mand an
    output processor which translates the ditroff produced by [1mTROFF  [22minto  the
    appropriate  output  format.   The  default  output format, or device, for
    [1mGROFF [22mis PostScript.  Anything else must be specified using the device ar-
    gument.  To illustrate [1mGROFF[22m, the command will form the following pipeline
    troff -Tdvi /dev/null | grodvi If [1mGROFF [22mis tied to  option,  it  is  still
    possible  for  to  produce  ditroff via use of the option.  In [1mGROFF [22m1.09,
    [1mNROFF [22mis bundled as a shell script that calls [1mGROFF[22m, which in  turn  calls
    [1mTROFF [22mwith the default options passing the result through before it final-
    ly reaches the screen.  It is imperative that the  script  does  not  pass
    pre-processing options to [1mGROFF[22m's command line as takes care of this sepa-
    rately.
    0.0  Devices
    Both [1mNROFF [22mand [1mGROFF [22mmay allow output device selection.  As mentioned pre-
    viously,  classic  [1mNROFF [22mproduces output suitable for a typewriter device,
    classic [1mTROFF [22mproduces output suitable for a  and  [1mGROFF  [22mproduces  output
    suitable for a PostScript interpreting device by default.
    0.0  Macros
    There are several ROFF macro sets in existence that are suitable for manu-
    al pages.  Unfortunately, they tend to be incompatible  with  each  other.
    During  configuration,  will attempt to determine a suitable macro set for
    the local system's manual page collection.  It attempts to use [1mNROFF  [22mwith
    the following three macro packages:

            +--------------+--------------------------+---------------+
            |macro package | macro filename           | nroff command |
            +--------------+--------------------------+---------------+
            |andoc         | tmac.andoc or andoc.tmac | nroff -mandoc |
            |an            | tmac.an or an.tmac       | nroff -man    |
            |doc           | tmac.doc or doc.tmac     | nroff -mdoc   |
            +--------------+--------------------------+---------------+
    The  first  that  succeeds  is used.  The macro set is suitable for manual
    pages written using either or macro commands, but  not  a  combination  of
    both.
    0.0  Pre-format processors (pre-processors)
    Manual pages may require pre-processing by any of the following

                        +--------+----+------------------+
                        |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 and un-comment the follow-
    ing line /* #define DEFAULT_MANROFFSEQ   "t" */ which will enable process-
    ing by default.  To change the list, replace the with a suitable string of
    processor ID's.  Pre-process options may be provided at run time in  vari-
    ous  forms, but in general the pre-processors required by each manual page
    is indicated in the first line of the manual page  itself.   See  for  de-
    tails.   If  a  manual page does not contain a pre-processor string in its
    first line, it will be scanned for well-known ROFF requests used  to  pass
    input  to certain pre-processors.  Thus, the pre-processor string is often
    unnecessary for correct output, but should nevertheless  be  included  for
    efficiency.
    0.0  Format scripts
    It  is  very  likely  that alternate systems manual pages may require non-
    standard macro packages or possibly even special pre-processors.  To tack-
    le  such  problems,  special format scripts may be created on a per manual
    hierarchy basis.  If the file exists and is executable, it is expected  to
    be able to correctly format a manual page originating from to its standard
    output.  It will be supplied with either two or three arguments: +o  manual
    page filename +o pre-processor string +o output device (optional) Similarly,
    if the option or was supplied to and the file 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 The script can be used as both an [1mNROFF[0m
    and [1mTROFF[22m/[1mGROFF [22mformat script and can be installed as and hard  linked  to
    after modification appropriate for your particular site.


















































0.  The index database caches
As  mentioned  in the introduction, man-db uses database lookups to search for
manual page locations and information.  When performing a manual  page  lookup
or  a  basic search, the databases are searched in mode and are as fast as the
underlying databases can be.  When performing or special searches,  the  data-
bases  are  searched  in a linear way, which, although far more expensive than
lookup, is no worse than traditional text based file searching.
    0.0  index database location
    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 data-
    bases reside on a local filesystem since file locking across NFS  filesys-
    tems may be unavailable or flaky.  To avoid such problems, can be compiled
    without database maintenance support.  See the section  titled  "Modes  of
    operation" for details.
         0.0.0  Manual hierarchies with no index database
         It  is  possible for the man-db 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 tra-
         ditional whatis text databases that may exist.  Only the  traditional
         cat hierarchy is searched for cat files.
         0.0.0  User manual page hierarchies
         A user may have any number of personal manual page hierarchies listed
         in their $By default, will maintain created databases at the root  of
         user  manual page hierarchies.  The definition of a user manual hier-
         archy is that it does not have an entry in the  man-db  configuration
         file.  See for details.
    0.0  Contents of an index database
    There  are  four  kinds of entry in an index database.  A direct entry re-
    garding 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.  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 exten-
    sions available.  An indirect entry that has a pointer to the real  entry.
    Manual pages that are whatis references to a particular page do not physi-
    cally exist so they have a pointer to the entry containing the location of
    the  real manual page.  Special identification entries.  There is one spe-
    cial key name, that identifies the database storage  scheme  version.   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.
    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: Common name index entries take the form: and common name  direct  or
    indirect entries take the form: where in each case the filename being rep-
    resented is formed as in the case of a manual page, or in the  case  of  a
    stray cat.  If any of the fields would be empty, a single is stored in its
    place.  represents the compression extension, is an  integer  representing
    the  seconds  part of the last modification time of the manual page, is an
    integer representing the nanoseconds part of the last modification time of
    the  manual  page, points to the entry containing the location of the real
    page, is one of the following identification letters, and  represents  any
    preprocessors that are needed to display the page.







    +---+------------+--------------------------------------------------------+
    |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  illustrates  the precedence.  Some types of manual page can be refer-
    enced 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.
         0.0.0  Favouring stray cats
         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  instead  of
         the page referenced by edit and un-comment the following line /* #de-
         fine FAVOUR_STRAYCATS */
         0.0.0  Accessdb
         A simple program, is included with man-db.  It will output  the  data
         contained  within a man-db database in a human readable form.  By de-
         fault, it will the data from where is dependent on the  database  li-
         brary  in  use.  Supplying an argument to will override this default.
         Tabs are replaced in the output by a tilde in the field and a  single
         space in the field.
         0.0.0  Example database
         As  an example of both and the database storage method, the output of
         after first running from the top level build  directory  is  included
         below.
         $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 on-line 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"
    0.0  Database types
    man-db  has  support  for various low level database libraries commonly in
    use today.  The interfaces to the libraries are known as ndbm ([1mUNIX[22m)  gdbm
    ([1mGNU[22m)  btree  (Berkeley  DB)  man-db currently does not hold more than one
    database open at any time, so dbm ([1mUNIX[22m) support could be added in the fu-
    ture.
    0.0  Limitations
    The general differences and limitations are best compared in a table.

   +------+-------------+----------+-----------------+--------------+-----------+
   |      |             |   File   | Content memory  |  Concurrent  |           |
   |Name  |    Type     |          +---------+-------+              | Shareable |
   |      |             |   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       |
   +------+-------------+----------+---------+-------+--------------+-----------+
     ndbm  databases  are physically represented by two files, and but are re-
    ferred to simply as by the interface routines.  Those types that  have  no
    built  in  concurrent access strategy are provided with based file locking
    by man-db.  Berkeley DB initializes its databases  very  quickly,  so  may
    have  some  performance  advantages  when  doing 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 man-db
    needs, so the preferred library interface is now will look  for  and  then
    finally routines when configuring man-db.
    0.0  Sharing databases in a heterogeneous environment
    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 directo-
    ry 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  ma-
    chines.   There are at least two ways to deal with this problem.  Hack the
    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 in-
    terface 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.

















































0.  Miscellaneous
    0.0  Modes of operation
    The man-db utilities can operate in many different modes, allowing varying
    degrees of freedom, functionality and security.  No mode requires that the
    manual  page  hierarchies  be  writable.   is setuid to the user MAN_OWNER
    which is `man' by default and is changeable via options to if run  by  the
    superuser  or MAN_OWNER, creates globally accessible index databases owned
    by MAN_OWNER.  Once the databases are created, will update entries in them
    if  it  finds newly installed manual pages (if the flag is used) or delete
    entries if manual pages are removed.  In this mode it is  possible  for  a
    malicious  user  to deliberately lock a database as a writer, thus denying
    read access to other users.
    If cat directories exist and have the correct permissions, will take  care
    of  producing  cat  files.  These will be owned by MAN_OWNER.  The default
    permissions of both cat files and databases are 0644.  This mode also  re-
    quires  to be setuid, but is favoured where databases must be shared in an
    environment unfriendly to kernel locking procedures,  eg.  NFS.   It  also
    prevents  possible attacks by malicious users as never opens the databases
    as a writer in this mode.  To replace the functionality lost by  disallow-
    ing  write  access  to  the databases, should be rerun whenever new manual
    pages are installed.  Otherwise, 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 cre-
    ated in the same way as for mode (1) above.
    To use the man-db utilities in this mode, give the option `--disable-auto-
    matic-update' to 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 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 whenever new manual files are installed.  will  be  completely
    passive  in  its action, i.e. 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  options  `--dis-
    able-cache-owner    --disable-setuid   --disable-automatic-update   --dis-
    able-cats' to or build man-db as in mode  (1)  and  install  the  binaries
    without  the setuid bit set.  is installed not setuid.  This mode is simi-
    lar 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 arbitrary user who maintains them using does  not  update  the
    databases.  Cat files are produced and stored in world writable cat direc-
    tories and have world write access themselves.
    To use the man-db utilities in  this  mode,  supply  the  options  `--dis-
    able-cache-owner  --disable-setuid --disable-automatic-update' to edit and
    change the definition of CATMODE from 0644 to 0666.  Other variations  can
    also  be  used.  In fact it is possible for to actually create index data-
    bases, usually the job of for  users'  private  manual  page  hierarchies.
    This  is  enabled  by  giving the option `--enable-automatic-create' to In
    summary, contains definitions for CATMODE DBMODE the  setuid  installation
    and  operation of is modified by supplying either of the following options
    to --enable-setuid --disable-setuid and other  aspects  of  behaviour  are
    controlled  by  the  following options to --enable-automatic-create --dis-
    able-automatic-update --disable-cats
    0.0  NFS root squash
    If is installed setuid to an arbitrary user and is run by root, instead of
    gaining the effective user id of the setuid user, is run with both uid and
    euid as root.  This is neccesary due to  infelicities  with  the  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 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 prob-
    lem, the root user must first attain the ID of the cat hierarchy or  data-
    base  owner  before  running  whenever  the databases need updating or cat
    files are to be produced.
    0.0  NLS message catalogues
    man-db has built in support for native language message 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 undertak-
    ing  a translation, please contact the Translation Project (https://trans-
    lationproject.org/) who are coordinating such activities.
    0.0  Credits
    The authors would like to thank the following people for their  time,  ef-
    fort,  support,  ideas  and code which went into man-db: 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@yg-
    gdrasil.com> Fabrizio Polacco  <fpolacco@debian.org>  Gordon  Sadler  <gb-
    sadler1@lcisp.com>   Colin   Phipps  <cph@cph.demon.co.uk>  Paul  Slootman
    <paul@wurtel.net>  Jose   Rodriguez   <boriel@airtel.net>   Eirik   Fuller
    <eirik@hackrat.com>  Matej  Vela <vela@debian.org> Clint Adams <schizo@de-
    bian.org>  Jeremy  C.  Reed  <reed@reedmedia.net>  Erik  Andersen  <ander-
    sen@codepoet.org>  Giuseppe  Sacco  <eppesuig@debian.org>  David Weinehall
    <tao@debian.org> Ralph Corderoy <ralph@inputplus.co.uk> Yuri  Kozlov  <ko-
    zlov.y@gmail.com>  Henning  Makholm  <henning@makholm.net>  Lars Wirzenius
    <liw@iki.fi>  Nicolas  Fran,cois  <nicolas.francois@centraliens.net>   Ivan
    Shmakov   <oneingray@gmail.com>   Peter  Breitenlohner  <peb@mppmu.mpg.de>
    Robert Luberda <robert@debian.org> Chusslove Illich  <caslav.ilic@gmx.net>
    and all those translators listed in the file.








































                                     Glossary

    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 sec-
    tion that it resides in, optionally followed by an extension.  The  format
    of  the file is [1mNROFF [22mand may be compressed, having a suitable compression
    extension appended.  A formatted manual page suitable  for  viewing  on  a
    vt100-type terminal.  A cat page that does not have a relative manual page
    on the system, i.e. only the cat page was supplied or the manual page  was
    removed after the cat page had been created.  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'.  A package may provide manual pages with filenames ending 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.  A directory tree divided  into  manual
    page  sections, each containing a collection of manual pages.  A directory
    tree divided into cat page sections, each containing a collection  of  cat
    pages.   The same location as the manual page hierarchy.  A separate loca-
    tion to that of the traditional cat page hierarchy.  A cat page located in
    a  traditional cat page hierarchy.  A cat page located in an alternate cat
    page hierarchy.










































                                     Contents

































































