GNU Info

Info Node: (com_err.info)Run-time support routines

(com_err.info)Run-time support routines


Next: Coding Conventions Prev: The error-table compiler Up: Top
Enter node , (file) or (file)node

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.

 - Function: 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.


 - Function:
     void com_err (const char *WHOAMI, long ERROR_CODE,
     const char *FORMAT, ...);

     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."_

     The module reporting the error should be passed in via WHOAMI.  If
     FORMAT is `(char *)NULL', the formatted message will not be
     printed.  FORMAT may not be omitted.


 - Function:
     void com_err_va (const char *WHOAMI, long ERROR_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).


 - Function: void (*set_com_err_hook (void (*PROC) (const char *WHOAMI,
          long ERROR_CODE, va_list ARGS))) (const char *WHOAMI, long
          ERROR_CODE, va_list ARGS);
 - Function: 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).



automatically generated by info2www version 1.2.2.9