*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> catman (8)              



NAME    [Toc]    [Back]

       catman - Creates or rebuilds formatted reference pages and
       the whatis database

SYNOPSIS    [Toc]    [Back]

       /usr/sbin/catman [-M search_path] [-cnpvw] [section...]

OPTIONS    [Toc]    [Back]

       Creates formatted versions of reference pages only in  the
       set   of   directories   specified  by  search_path.   The
       search_path argument has the  form  of  a  colon-separated
       list of directory names. The default search path (assuming
       MANPATH has not been set) is the following:


              The -M option, unlike the  MANPATH  setting,  overrides
  the default placement of the whatis database
              (in  /usr/share/man).   When  the  -M   option   is
              included  in  a  command  that  builds  the  whatis
              database, catman creates the database in the  first
              directory included in search_path.

              Refer  to the man(1) reference page for more information
 on the MANPATH variable. See DESCRIPTION for
              a list of locale directives that can be included in
              search_path.  Uses the  gzip  command  to  compress
              preformatted  output  files.  The  -c option has no
              effect when used with the -w option.  Prevents creation
  of the whatis database.  Displays what would
              be done instead of doing it.  Displays the name  of
              each  reference page file as it is being processed.
              Causes only the whatis database to be created.   No
              reformatting is done.

OPERANDS    [Toc]    [Back]

       Specifies one or more reference page sections whose corresponding
 directories are to be searched for files. If  you
       do  not  specify  this parameter, the command searches for
       reference page source files  in  all  section  directories
       encountered in its search path.

              The  section operand affects creation of preformatted
 files, not the  whatis  database.   The  catman
              command  always searches all section directories in
              its search path when creating the whatis  database.

DESCRIPTION    [Toc]    [Back]

       The  catman  command  creates  formatted  versions  of the
       online reference pages from the nroff  source  files.  The
       command also creates from the NAME entries in source files
       the whatis database that is used by the whatis and apropos

       When  catman  is  invoked, each reference page is examined
       and those whose preformatted versions are missing  or  out
       of date are created by nroff using the -man macro package.
       See man(5).

       An argument not starting with a - (single minus  sign)  is
       assumed to be a list of the reference sections to look in.
       If you do not specify a list, catman formats all reference
       pages in the search path.  In general, sections are referenced
 by a single digit in the range 1  through  8.   But,
       you  can  use any section allowed by the man command.  The
       list of sections is applied to all reference page areas in
       the search path.

       If a .../man/cat?  directory does not exist for a section,
       catman creates the directory.

       The command recognizes and appropriately processes  either
       compressed  or uncompressed source files.  By default, the
       command creates formatted files in uncompressed form; however,
  you  can  specify the -c option to direct catman to
       compress its output files. When catman processes an uncompressed
 source file, any corresponding pointers are generated
 as symbolic links.   When  catman  processes  a  compressed
 source file, any corresponding pointers are generated
 as hard links. Refer to man(1) for more  information,
       including  restrictions,  that  apply to pointers and compressed

       A reference page source file can include a  multicharacter
       7-bit  ASCII  subsection suffix appended to its name, following
 the section character. The subsection suffix, if it
       exists, must start with a letter.  The formatted reference
       page file also includes the subsection suffix in its name.

       The  catman  command  assumes  that  reference page source
       files  can  contain  unprocessed  tables  and   equations.
       Therefore, it automatically processes source files through
       tbl and neqn before invoking nroff.  When catman processes
       a  compressed file, the command automatically executes the
       gunzip -c command to uncompress  the  file  before  piping
       output to the other commands.

       Processing  reference  pages always invokes nroff with the
       -Tlp option to format output for the  term(4)  lp  device.
       See  RESTRICTIONS for information appropriate for printers
       and some display devices.

       When you view preformatted reference page  files  directly
       with  the  more  command,  you should invoke more with the
       -svf options. The vf options ensure that the pages display
       properly  in cases where the nroff lp device driver generates
 special device control codes.

       The following locale directives can  be  included  in  the
       pathnames  in  search_path:  The  current locale name, for
       example, ja_JP.eucJP, that is defined for the  LC_MESSAGES
       environment  variable.  The same as %L except that any "@"
       modifier on the locale name is removed.  The language element
  of  the  current  locale name, for example, ja.  The
       territory element of the current locale name, for example,
       JP.  The codeset element from the current locale name, for
       example, eucJP.  A single % (percent sign) character.

              These directives allow catman to  use  the  current
              locale  setting to find translated source files and
              create translated output files  in  an  appropriate
              and    predictable    location.    Refer   to   the
              i18n_intro(5) reference page for  more  information
              about locales and associated environment variables.

RESTRICTIONS    [Toc]    [Back]

       The following subsections discuss restrictions  associated
       with both catman and its input and output files.

   Reference Page Pointers    [Toc]    [Back]
       Refer  to man(1) for introductory information on reference
       page pointers and general pointer restrictions.

       When processing reference page files, the  catman  command
       changes  its  directory to each reference page area in the
       search path.  Some reference pages assume this  change  of
       directory.   Therefore,  an attempt to format uncompressed
       reference pages can fail if any directives specifying partial
 pathnames do not start with man?/.

   Optional Section Directories    [Toc]    [Back]
       The /usr/share/man/man?  directories for sections C, L, F,
       n, l, p, o, and 0 are optional.  Only your system administrator
  can  create them.  Once they are created, however,
       catman will create the corresponding .../man/cat?   directories
  whenever it receives a request to format reference
       pages in one of those sections.

   The whatis Database    [Toc]    [Back]
       The whatis (man -f) and apropos  (man  -k)  commands  fail
       unless  the  whatis  database exists in the /usr/share/man
       directory or, if the command includes the  -M  option,  in
       the search path specified with that option.

       The    operating   system   can   optionally   install   a
       /usr/share/man/whatis file that is  useful  during  system
       configuration  tasks. However, you must recreate this file
       manually if you  install  reference  pages  that  are  not
       included in subsets for the operating system product; otherwise,
 entries for the additional reference pages are not
       included in the whatis database.

       You  create  or  recreate  the whatis file when you invoke
       catman without specifying the  -n  option.  You  can  also
       specify  the  -w  option to create the whatis file without
       creating or updating preformatted reference pages  in  the
       cat?  directories.

       An  update  installation procedure or a setld command that
       processes reference page subsets for the operating  system
       itself  may  selectively  remove  or  add  specific whatis
       database entries to help keep the  database  up  to  date.
       However,  this  feature  is  of limited use in making sure
       that the whatis database remains current with  respect  to
       the  reference  pages  that  are actually available on the
       system.  As already mentioned,  selective  update  is  not
       supported  by  most of the optional software products that
       can load reference  pages  to  the  system.   Furthermore,
       selective  update  has database location dependencies. For
       selective update to work, the whatis entries for all operating
  system product reference pages (including those for
       CDE)  must  reside  in  /usr/share/man/whatis.   In  other
       words,  automatic  and  selective  revision  of the whatis
       database does not work correctly if the whatis database is
       rebuilt in a directory other than /usr/share/man or if the
       system  administrator  creates   a   CDE-specific   whatis
       database in the /usr/dt/share/man directory.

       Therefore,  do  not rely on automatic update of the whatis
       database to ensure that its entries  reflect  the  current
       set  of  reference  pages  installed  on the system. It is
       strongly recommended that you always use the  catman  command
  to  manually  rebuild  the database as the last task
       following a completed series of software product installations.

   Default Formatting Is Not Appropriate for All Devices    [Toc]    [Back]
       The  catman  command formats reference pages for the nroff
       lp device. The lp device driver, as supplied by the  operating
  system,  is  set  to  generate  output for HewlettPackard
 Company video terminals, but not for all  printers
       or  third-party  terminals.  If  your system administrator
       changes the supplied setting for the lp device,  all  preformatted
  reference  page  files created by man or catman
       should be deleted and then  reformatted  for  the  new  lp

       Preformatted  reference pages may not be in a format suitable
 for printing on your hardcopy printers.  To format  a
       reference  page for a specific printer, move to the reference
 page area and issue a command such as the  following:
       %  cd  /usr/share/man  % gunzip -c man1/ls.1.gz |tbl |neqn
       |nroff -Tdevice -man -h | lpr \ -Pmyprinter

       Replace the device argument with  /usr/share/lib/term/tabdevice,
  where  device  is  the name of a device listed in
       term(4). The lpr device setting, because it supports primitive
  line  printers,  is  least likely to cause problems
       that are related to escape sequences that the device  cannot
  handle.  On the other hand, if the reference page has
       tables and the device is not capable of reverse line movements,
  column  entries intended to be in the same row may
       not align correctly.

       Preformatted reference pages also might not be in a format
       suitable  for  display  on video terminals from other vendors.
  To format a reference page for a  specific  display
       device,  move  to the reference page directory and issue a
       command such as the following: % cd /usr/share/man %  gunzip
 -c man1/ls.1 |tbl |neqn |nroff -Tdevice -man -h | more

       Replace the device argument with  /usr/share/lib/term/tabdevice,
  where  device  is  the name of a device listed in

EXIT STATUS    [Toc]    [Back]

       Success.  An error occurred.

EXAMPLES    [Toc]    [Back]

       To create or update compressed preformatted files for reference
  pages  and  also  create  or  rebuild  the  whatis
       database, enter: catman -c To create uncompressed  preformatted
  files only for sections 1, 2, and 3, enter: catman

              This command also creates or  rebuilds  the  whatis
              database.  The  new  database  contains entries for
              reference pages in all sections (not just 1, 2, and
              3) that are found in the search path.  To create or
              rebuild the whatis  database  without  creating  or
              updating  formatted files, enter: catman -w To create
 compressed preformatted files for all reference
              pages in the search path but not rebuild the whatis
              database, enter: catman -c -n

FILES    [Toc]    [Back]

       Main reference page  area  Directories  containing  source
       files for most reference pages Directories containing preformatted
 files for most reference  pages  Reference  page
       area  for the Common Desktop Environment (CDE) Directories
       containing source files for CDE reference  pages  Directories
 containing preformatted files for CDE reference pages
       Local (site-specific) reference page area Directories containing
 source files for local reference pages Directories
       containing preformatted files for  local  reference  pages
       The  whatis  database created or modified by catman unless
       the -M option is specified  Command  script  to  make  the
       whatis  database  Program  used by the mkwhatis command to
       extract data from reference pages

SEE ALSO    [Toc]    [Back]

       Commands: man(1), neqn(1), nroff(1), tbl(1)

       Files: term(4), man(5), rsml(5)

[ Back ]
 Similar pages
Name OS Title
newaliases HP-UX rebuilds the database for the mail aliases file
man Tru64 Displays reference pages
intro Tru64 Introduction to miscellaneous reference pages
man Tru64 The man macro packages for reference pages
man.page Tru64 The man macro packages for reference pages
apropos Tru64 Locates reference pages by keyword
makewhatis FreeBSD create whatis database
makewhatis OpenBSD create a whatis.db database
apropos FreeBSD search the whatis database
whatis FreeBSD search the whatis database
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service