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)

Man(1) output converted with man2html