diff options
Diffstat (limited to 'contrib/com_err/com_err.3')
| -rw-r--r-- | contrib/com_err/com_err.3 | 325 |
1 files changed, 237 insertions, 88 deletions
diff --git a/contrib/com_err/com_err.3 b/contrib/com_err/com_err.3 index e6eeea1..b71203a 100644 --- a/contrib/com_err/com_err.3 +++ b/contrib/com_err/com_err.3 @@ -1,96 +1,245 @@ -.\" Copyright (c) 1988 Massachusetts Institute of Technology, -.\" Student Information Processing Board. All rights reserved. +.\" Copyright (c) 2005 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. .\" -.\" $FreeBSD$ +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: .\" -.TH COM_ERR 3 "22 Nov 1988" SIPB -.SH NAME -com_err \- common error display routine -.SH SYNOPSIS -.nf - #include <com_err.h> -.PP -void com_err (whoami, code, format, ...); - const char *whoami; - long code; - const char *format; -.PP -proc = set_com_err_hook (proc); -.fi -void (* -.I proc -) (const char *, long, const char *, va_list); -.nf -.PP -proc = reset_com_err_hook (); -.PP -void initialize_XXXX_error_table (); -.fi -.SH DESCRIPTION -.I Com_err -displays an error message on the standard error stream -.I stderr -(see -.IR stdio (3S)) -composed of the -.I whoami -string, which should specify the program name or some subportion of -a program, followed by an error message generated from the -.I code -value (derived from -.IR compile_et (1)), +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Id$ +.\" +.\" This manpage was contributed by Gregory McGarry. +.\" +.Dd July 7, 2005 +.Dt COM_ERR 3 +.Os +.Sh NAME +.Nm com_err , +.Nm com_err_va , +.Nm error_message , +.Nm error_table_name , +.Nm init_error_table , +.Nm set_com_err_hook , +.Nm reset_com_err_hook , +.Nm add_to_error_table , +.Nm initialize_error_table_r +.Nm free_error_table , +.Nm com_right +.Nd common error display library +.Sh LIBRARY +Common Error Library (libcom_err, -lcom_err) +.Sh SYNOPSIS +.Fd #include <stdio.h> +.Fd #include <stdarg.h> +.Fd #include <krb5/com_err.h> +.Fd #include \&"XXX_err.h\&" +.Pp +typedef void (*errf)(const char *, long, const char *, ...); +.Ft void +.Fn com_err "const char *whoami" "long code" "const char *format" "..." +.Ft void +.Fn com_err_va "const char *whoami" "long code" "const char *format" "..." +.Ft const char * +.Fn error_message "long code" +.Ft const char * +.Fn error_table_name "int num" +.Ft int +.Fn init_error_table "const char **msgs" "long base" "int count" +.Ft errf +.Fn set_com_err_hook "errf func" +.Ft errf +.Fn reset_com_err_hook "" +.Ft void +.Fn add_to_error_table "struct et_list *new_table" +.Ft void +.Fn initialize_error_table_r "struct et_list **et_list" "const char **msgs" "int base" "long count" +.Ft void +.Fn free_error_table "struct et_list *" +.Ft const char * +.Fn com_right "struct et_list *list" long code" +.Sh DESCRIPTION +The +.Nm +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 +.Xr compile_et 1 . +.Pp +The error table is registered with the +.Nm +library by calling its initialisation function defined in its header +file. The initialisation function is generally defined as +.Fn initialize_<name>_error_table , +where +.Em name +is the name of the error table. +.Pp +If a thread-safe version of the library is needed +.Fn initialize_<name>_error_table_r +that internally calls +.Fn initialize_error_table_r +instead be used. +.Pp +Any variable which is to contain an error code should be declared +.Em <name>_error_number +where +.Em name +is the name of the error table. +.Sh FUNCTIONS +The following functions are available to the application developer: +.Bl -tag -width compact +.It Fn com_err "whoami" "code" "format" "..." +Displays an error message on standard error composed of the +.Fa whoami +string, which should specify the program name, followed by an error +message generated from +.Fa code , and a string produced using the -.I format -string and any following arguments, in the same style as -.IR fprintf (3). +.Xr printf 3 +.Fa format +string and any following arguments. If +.Fa format +is NULL, the formatted message will not be +printed. The argument +.Fa format +may not be omitted. +.It Fn com_err_va "whoami" "code" "format" "va_list args" +This routine provides an interface, equivalent to +.Fn com_err , +which may be used by higher-level variadic functions (functions which +accept variable numbers of arguments). +.It Fn error_message "code" +Returns the character string error message associate with +.Fa code . +If +.Fa code is associated with an unknown error table, or if +.Fa 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. +.Pp +Although this routine is available for use when needed, its use should +be left to circumstances which render +.Fn com_err +unusable. +.Pp +.Fn com_right +returns the error string just like +.Fa com_err +but in a thread-safe way. +.Pp +.It Fn error_table_name "num" +Convert a machine-independent error table number +.Fa num +into an error table name. +.It Fn init_error_table "msgs" "base" "count" +Initialise the internal error table with the array of character string +error messages in +.Fa msgs +of length +.Fa count . +The error codes are assigned incrementally from +.Fa base . +This function is useful for using the error-reporting mechanism with +custom error tables that have not been generated with +.Xr compile_et 1 . +Although this routine is available for use when needed, its use should +be restricted. +.Pp +.Fn initialize_error_table_r +initialize the +.Fa et_list +in the same way as +.Fn init_error_table , +but in a thread-safe way. +.Pp +.It Fn set_com_err_hook "func" +Provides a hook into the +.Nm +library to allow the routine +.Fa func +to be dynamically substituted for +.Fn com_err . +After +.Fn set_com_err_hook + has been called, calls to +.Fn 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 +.Xr syslog 3 , +or in a window system application to pop up a dialogue box. +.It Fn reset_com_err_hook "" +Turns off the hook set in +.Fn set_com_err_hook . +.It Fn add_to_error_table "new_table" +Add the error table, its messages strings and error codes in +.Fa new_table +to the internal error table. +.El +.Sh EXAMPLES +The following is an example using the table defined in +.Xr compile_et 1 : +.Pp +.Bd -literal + #include <stdio.h> + #include <stdarg.h> + #include <syslog.h> -The behavior of -.I com_err -can be modified using -.I set_com_err_hook; -this defines a procedure which is called with the arguments passed to -.I com_err, -instead of the default internal procedure which sends the formatted -text to error output. Thus the error messages from a program can all -easily be diverted to another form of diagnostic logging, such as -.IR syslog (3). -.I Reset_com_err_hook -may be used to restore the behavior of -.I com_err -to its default form. Both procedures return the previous ``hook'' -value. These ``hook'' procedures must have the declaration given for -.I proc -above in the synopsis. + #include "test_err.h" -The -.I initialize_XXXX_error_table -routine is generated mechanically by -.IR compile_et (1) -from a source file containing names and associated strings. Each -table has a name of up to four characters, which is used in place of -the -.B XXXX -in the name of the routine. These routines should be called before -any of the corresponding error codes are used, so that the -.I com_err -library will recognize error codes from these tables when they are -used. - -The -.B com_err.h -header file should be included in any source file that uses routines -from the -.I com_err -library; executable files must be linked using -.I ``-lcom_err'' -in order to cause the -.I com_err -library to be included. + void + hook(const char *whoami, long code, + const char *format, va_list args) + { + char buffer[BUFSIZ]; + static int initialized = 0; -.\" .IR for manual entries -.\" .PP for paragraph breaks + if (!initialized) { + openlog(whoami, LOG_NOWAIT, LOG_DAEMON); + initialized = 1; + } + vsprintf(buffer, format, args); + syslog(LOG_ERR, "%s %s", error_message(code), buffer); + } -.SH "SEE ALSO" -compile_et (1), syslog (3). + int + main(int argc, char *argv[]) + { + char *whoami = argv[0]; -Ken Raeburn, "A Common Error Description Library for UNIX". + 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); + } +.Ed +.Sh SEE ALSO +.Xr compile_et 1 |
