Run-time support routines
=========================

   Any source file which uses the routines supplied with or produced by
the com_err package should include the header file `<com_err.h>'.  It
contains declarations and definitions which may be needed on some
systems.  (Some functions cannot be referenced properly without the
return type declarations in this file.  Some functions may work
properly on most architectures even without the header file, but
relying on this is not recommended.)

   The run-time support routines and variables provided via this package
include the following:

     void initialize_XXXX_error_table (void);

   One of these routines is built by the error compiler for each error
table.  It makes the XXXX error table "known" to the error reporting
system.  By convention, this routine should be called in the
initialization routine of the XXXX library.  If the library has no
initialization routine, some combination of routines which form the
core of the library should ensure that this routine is called.  It is
not advised to leave it the caller to make this call.

   There is no harm in calling this routine more than once.

     #define ERROR_TABLE_BASE_XXXX NNNNNL

   This symbol contains the value of the first error code entry in the
specified table.  This rarely needs be used by the programmer.

     const char *error_message (long code);

   This routine returns the character string error message associated
with `code'; if this is associated with an unknown error table, or if
the code is associated with a known error table but the code is not in
the table, a string of the form `Unknown code XXXX NN' is returned,
where XXXX is the error table name produced by reversing the compaction
performed on the error table number implied by that error code, and NN
is the offset from that base value.

   Although this routine is available for use when needed, its use
should be left to circumstances which render `com_err' (below) unusable.

     void com_err (const char *whoami,  /* module reporting error */
                   long code,           /* error code */
                   const char *format,  /* format for additional detail */
                   ...);                /*  (extra parameters) */

   This routine provides an alternate way to print error messages to
standard error; it allows the error message to be passed in as a
parameter, rather than in an external variable.  *Provide grammatical
context for "message."*

   If FORMAT is `(char *)NULL', the formatted message will not be
printed.  FORMAT may not be omitted.

     #include <stdarg.h>
     
     void com_err_va (const char *whoami,
                      long code,
                      const char *format,
                      va_list args);

   This routine provides an interface, equivalent to `com_err' above,
which may be used by higher-level variadic functions (functions which
accept variable numbers of arguments).

     #include <stdarg.h>
     
     void (*set_com_err_hook (void (*proc) ())) ();
     
     void (*PROC) (const char *whoami, long code, va_list args);
     
     void reset_com_err_hook ();

   These two routines allow a routine to be dynamically substituted for
`com_err'.  After `set_com_err_hook' has been called, calls to
`com_err' will turn into calls to the new hook routine.
`reset_com_err_hook' turns off this hook.  This may intended to be used
in daemons (to use a routine which calls SYSLOG(3)), or in a window
system application (which could pop up a dialogue box).

   If a program is to be used in an environment in which simply printing
messages to the `stderr' stream would be inappropriate (such as in a
daemon program which runs without a terminal attached),
`set_com_err_hook' may be used to redirect output from `com_err'.  The
following is an example of an error handler which uses SYSLOG(3) as
supplied in BSD 4.3:

     #include <stdio.h>
     #include <stdarg.h>
     #include <syslog.h>
     
     /* extern openlog (const char * name, int logopt, int facility); */
     /* extern syslog (int priority, char * message, ...); */
     
     void hook (const char * whoami, long code,
                const char * format, va_list args)
     {
         char buffer[BUFSIZ];
         static int initialized = 0;
         if (!initialized) {
             openlog (whoami,
                      LOG_NOWAIT|LOG_CONS|LOG_PID|LOG_NDELAY,
                      LOG_DAEMON);
             initialized = 1;
         }
         vsprintf (buffer, format, args);
         syslog (LOG_ERR, "%s %s", error_message (code), buffer);
     }

   After making the call `set_com_err_hook (hook);', any calls to
`com_err' will result in messages being sent to the SYSLOGD daemon for
logging.  The name of the program, `whoami', is supplied to the
`openlog()' call, and the message is formatted into a buffer and passed
to `syslog'.

   Note that since the extra arguments to `com_err' are passed by
reference via the `va_list' value `args', the hook routine may place
any form of interpretation on them, including ignoring them.  For
consistency, `printf'-style interpretation is suggested, via `vsprintf'
(or `_doprnt' on BSD systems without full support for the ANSI C
library).