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_xxxxnnnnnL
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.
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.
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:
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).