NAME
com_err,
com_err_va,
error_message,
error_table_name,
init_error_table,
set_com_err_hook,
reset_com_err_hook,
add_to_error_table,
initialize_error_table_r free_error_table,
com_right —
common error display
library
LIBRARY
Common Error Library (libcom_err, -lcom_err)
SYNOPSIS
#include <stdio.h>
#include <stdarg.h>
#include <krb5/com_err.h>
#include "XXX_err.h"
typedef void (*errf)(const char *, long, const char *, ...);
void
com_err(
const
char *whoami,
long
code,
const char
*format,
...);
void
com_err_va(
const
char *whoami,
long
code,
const char
*format,
...);
const char *
error_message(
long
code);
const char *
error_table_name(
int
num);
int
init_error_table(
const
char **msgs,
long
base,
int count);
errf
set_com_err_hook(
errf
func);
errf
reset_com_err_hook(
);
void
add_to_error_table(
struct
et_list *new_table);
void
initialize_error_table_r(
struct
et_list **et_list,
const
char **msgs,
int
base,
long count);
void
free_error_table(
struct
et_list *);
const char *
com_right(
struct
et_list *list,
long,
code");
DESCRIPTION
The
com_err library provides a common error-reporting
mechanism for defining and accessing error codes and descriptions for
application software packages. Error descriptions are defined in a table and
error codes are used to index the table. The error table, the descriptions and
the error codes are generated using
compile_et(1).
The error table is registered with the
com_err library by
calling its initialisation function defined in its header file. The
initialisation function is generally defined as
initialize_<name>_error_table(), where
name is the name of the error table.
If a thread-safe version of the library is needed
initialize_<name>_error_table_r() that internally
calls
initialize_error_table_r() instead be used.
Any variable which is to contain an error code should be declared
<name>_error_number where
name is
the name of the error table.
FUNCTIONS
The following functions are available to the application developer:
-
-
- com_err(whoami,
code, format,
...)
- Displays an error message on standard error composed of the
whoami string, which should specify the program
name, followed by an error message generated from
code, and a string produced using the
printf(3)
format string and any following arguments. If
format is NULL, the formatted message will not be
printed. The argument format may not be
omitted.
-
-
- com_err_va(whoami,
code, format,
va_list args)
- This routine provides an interface, equivalent to
com_err(), which may be used by higher-level variadic
functions (functions which accept variable numbers of arguments).
-
-
- error_message(code)
- Returns the character string error message associated with
code. If code is associated
with an unknown error table, or if code is
associated with a known error table but 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() unusable.
com_right() returns the error string just like
com_err but in a thread-safe way.
-
-
- error_table_name(num)
- Convert a machine-independent error table number
num into an error table name.
-
-
- init_error_table(msgs,
base, count)
- Initialise the internal error table with the array of
character string error messages in msgs of length
count. The error codes are assigned incrementally
from base. This function is useful for using the
error-reporting mechanism with custom error tables that have not been
generated with
compile_et(1). Although
this routine is available for use when needed, its use should be
restricted.
initialize_error_table_r() initialize the
et_list in the same way as
init_error_table(), but in a thread-safe way.
-
-
- set_com_err_hook(func)
- Provides a hook into the com_err library
to allow the routine func 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. This function is intended to be used in daemons
to use a routine which calls
syslog(3), or in a window
system application to pop up a dialogue box.
-
-
- reset_com_err_hook()
- Turns off the hook set in
set_com_err_hook().
-
-
- add_to_error_table(new_table)
- Add the error table, its messages strings and error codes
in new_table to the internal error table.
EXAMPLES
The following is an example using the table defined in
compile_et(1):
#include <stdio.h>
#include <stdarg.h>
#include <syslog.h>
#include "test_err.h"
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_DAEMON);
initialized = 1;
}
vsprintf(buffer, format, args);
syslog(LOG_ERR, "%s %s", error_message(code), buffer);
}
int
main(int argc, char *argv[])
{
char *whoami = argv[0];
initialize_test_error_table();
com_err(whoami, TEST_INVAL, "before hook");
set_com_err_hook(hook);
com_err(whoami, TEST_IO, "after hook");
return (0);
}
SEE ALSO
compile_et(1)