Copyright (C) 2000-2012 |
GNU Info (com_err.info)Run-time support routinesRun-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 |