5. 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).

This document was generated by Build Daemon user on March 17, 2011 using texi2html 1.82.