## SYNOPSIS

           mandb [-dqsuc|-h|-V] [manpath]

## DESCRIPTION

           mandb  is  used  to  initialise  or  manually update index
           database caches that are usually maintained by  man.   The
           caches  contain  information relevant to the current state
           of the manual  page  system  and  the  information  stored
           within  them  is  used  by the man_db utilities to enhance
           their speed and functionality.

           When creating or updating an index, mandb will warn of bad
           ROFF  .so requests, bogus manual page filenames and manual
           pages from which the whatis cannot be parsed.

           Supplying mandb with an optional colon-delimited path will
           override  the internal system manual page hierarchy search
           path, determined from information found within the  man_db
           configuration file.

## DATABASE CACHES

           mandb can be compiled with support for any one of the fol
           lowing database types.

           Name                Type          Async   Filename
           ----------------------------------------------------------
           Berkeley db         Binary tree   Yes     index.bt
           GNU gdbm v >= 1.6   Hashed        Yes     index.db
           GNU gdbm v <  1.6   Hashed        No      index.db
           UNIX ndbm           Hashed        No      index.(dir|pag)

           Those database types  that  support  asynchronous  updates
           provide  enhanced speed at the cost of possible corruption
           in the event of unusual termination.  In an  unusual  case
           where this has occured, it may be necessary to rerun mandb
           with  the  -c  option  to  re-create  the  databases  from
           scratch.

## OPTIONS

           -d, --debug
                  Produce debugging information.

           -q, --quiet
                  Produce no warnings.

           -s, --no-straycats
                  Do not spend time looking for or adding information
                  to the databases regarding stray cats.

           -p, --no-purge
                  Do not spend time checking for deleted manual pages
                  and purging them from the databases.

           -t, --test
                  Perform correctness checks on manual pages  in  the
                  hierarchy  search  path.   With  this option, mandb
                  will not alter existing databases.

           -h, --help
                  Show the usage message, then exit.

           -V, --version
                  Show the version, then exit.

## DIAGNOSTICS

           The following  warning  messages  can  be  emitted  during
           database building.

           <filename>: whatis parse for page(sec) failed
                  An attempt to extract whatis line(s) from the given
                  <filename> failed.  This is usually due to a poorly
                  written  manual page, but if many such messages are
                  emitted it is likely that the system contains  non-
                  standard  manual  pages which are incompatible with
                  the man_db whatis parser.  See the  WHATIS  PARSING
                  section for more information.

           <filename>: is a dangling symlink
                  <filename>  does  not  exist but is referenced by a
                  symbolic link.   Further  diagnostics  are  usually
                  emitted to identify the <filename> of the offending
                  link.

           <filename>: bad symlink or ROFF `.so' request
                  <filename> is either a symbolic link  to,  or  con
                  tains  a  ROFF  include  request to, a non existent
                  file.

           <filename>: ignoring bogus filename
                  The <filename> may or may not  be  a  valid  manual
                  page  but its name is invalid.  This is usually due
                  to a manual page with sectional extension <x> being
                  put in manual page section <y>.

           <filename_mask>: competing extensions
                  The  wildcard  <filename_mask> is not unique.  This
                  is usually caused by the existence of both  a  com
                  pressed and uncompressed version of the same manual
                  page.  All but the most recent are ignored.

## WHATIS PARSING

           mandb parses the NAME section at the top  of  each  manual
           page  looking  for  names and descriptions of the features
           documented in each.  While the parser is  quite  tolerant,
           as  it  has  to cope with a number of different forms that
           rated by commas.  The text on the right-hand side is free-
           form, and may be spread over multiple lines.   If  several
           features  with different descriptions are being documented
           in the same manual page, the following form  is  therefore
           used:

                  .SH NAME
                  foo, bar \- programs to do something
                  .br
                  baz \- program to do nothing

           (A  macro  which  starts a new paragraph, like .PP, may be
           used instead of the break macro .br.)

           There are several common reasons why whatis parsing fails.
           Sometimes  authors of manual pages replace `.SH NAME' with
           `.SH MYPROGRAM', and then mandb cannot  find  the  section
           from which to extract the information it needs.  Sometimes
           authors include a NAME section, but place  free-form  text
           there  rather  than  `name  \- description'.  However, any
           syntax resembling the above should be accepted.

## FILES

           /etc/manpath.config
                  man_db configuration file.

           /usr/man/index.(bt|db|dir|pag)
                  A traditional global index database cache.

           /var/catman/index.(bt|db|dir|pag)
                  An  alternate  or  FSSTND  compliant  global  index
                  database cache.

           /var/cache/man/index.(bt|db|dir|pag)
                  An FHS compliant global index database cache.

## SEE ALSO

           man(1), manpath(5), catman(8).

## AUTHOR

           Wilf. (G.Wilford@ee.surrey.ac.uk).
           Fabrizio Polacco (fpolacco@debian.org).
           Colin Watson (cjwatson@debian.org).

    2.3.19                     14 May 2001                   mandb(8)