1  .\" Copyright (c) 2005 Kungliga Tekniska Högskolan
  2  .\" (Royal Institute of Technology, Stockholm, Sweden).
  3  .\" All rights reserved.
  4  .\"
  5  .\" Redistribution and use in source and binary forms, with or without
  6  .\" modification, are permitted provided that the following conditions
  7  .\" are met:
  8  .\"
  9  .\" 1. Redistributions of source code must retain the above copyright
 10  .\"    notice, this list of conditions and the following disclaimer.
 11  .\"
 12  .\" 2. Redistributions in binary form must reproduce the above copyright
 13  .\"    notice, this list of conditions and the following disclaimer in the
 14  .\"    documentation and/or other materials provided with the distribution.
 15  .\"
 16  .\" 3. Neither the name of the Institute nor the names of its contributors
 17  .\"    may be used to endorse or promote products derived from this software
 18  .\"    without specific prior written permission.
 19  .\"
 20  .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
 21  .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 22  .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 23  .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
 24  .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 25  .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 26  .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 27  .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 28  .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 29  .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 30  .\" SUCH DAMAGE.
 31  .\"
 32  .\" $Id$
 33  .\"
 34  .\" This manpage was contributed by Gregory McGarry.
 35  .\"
 36  .Dd July  7, 2005
 37  .Dt COM_ERR 3
 38  .Os
 39  .Sh NAME
 40  .Nm com_err ,
 41  .Nm com_err_va ,
 42  .Nm error_message ,
 43  .Nm error_table_name ,
 44  .Nm init_error_table ,
 45  .Nm set_com_err_hook ,
 46  .Nm reset_com_err_hook ,
 47  .Nm add_to_error_table ,
 48  .Nm initialize_error_table_r
 49  .Nm free_error_table ,
 50  .Nm com_right
 51  .Nd common error display library
 52  .Sh LIBRARY
 53  Common Error Library (libcom_err, -lcom_err)
 54  .Sh SYNOPSIS
 55  .Fd #include <stdio.h>
 56  .Fd #include <stdarg.h>
 57  .Fd #include <krb5/com_err.h>
 58  .Fd #include \&"XXX_err.h\&"
 59  .Pp
 60  typedef void (*errf)(const char *, long, const char *, ...);
 61  .Ft void
 62  .Fn com_err "const char *whoami" "long code" "const char *format" "..."
 63  .Ft void
 64  .Fn com_err_va "const char *whoami" "long code" "const char *format" "..."
 65  .Ft const char *
 66  .Fn error_message "long code"
 67  .Ft const char *
 68  .Fn error_table_name "int num"
 69  .Ft int
 70  .Fn init_error_table "const char **msgs" "long base" "int count"
 71  .Ft errf
 72  .Fn set_com_err_hook "errf func"
 73  .Ft errf
 74  .Fn reset_com_err_hook ""
 75  .Ft void
 76  .Fn add_to_error_table "struct et_list *new_table"
 77  .Ft void
 78  .Fn initialize_error_table_r "struct et_list **et_list" "const char **msgs" "int base" "long count"
 79  .Ft void
 80  .Fn free_error_table "struct et_list *"
 81  .Ft const char *
 82  .Fn com_right "struct et_list *list" long code"
 83  .Sh DESCRIPTION
 84  The
 85  .Nm
 86  library provides a common error-reporting mechanism for defining and
 87  accessing error codes and descriptions for application software
 88  packages.  Error descriptions are defined in a table and error codes
 89  are used to index the table.  The error table, the descriptions and
 90  the error codes are generated using
 91  .Xr compile_et 1 .
 92  .Pp
 93  The error table is registered with the
 94  .Nm
 95  library by calling its initialisation function defined in its header
 96  file.  The initialisation function is generally defined as
 97  .Fn initialize_<name>_error_table ,
 98  where
 99  .Em name
100  is the name of the error table.
101  .Pp
102  If a thread-safe version of the library is needed
103  .Fn initialize_<name>_error_table_r
104  that internally calls
105  .Fn initialize_error_table_r
106  instead be used.
107  .Pp
108  Any variable which is to contain an error code should be declared
109  .Em <name>_error_number
110  where
111  .Em name
112  is the name of the error table.
113  .Sh FUNCTIONS
114  The following functions are available to the application developer:
115  .Bl -tag -width compact
116  .It Fn com_err "whoami" "code" "format" "..."
117  Displays an error message on standard error composed of the
118  .Fa whoami
119  string, which should specify the program name, followed by an error
120  message generated from
121  .Fa code ,
122  and a string produced using the
123  .Xr printf 3
124  .Fa format
125  string and any following arguments.  If
126  .Fa format
127  is NULL, the formatted message will not be
128  printed.  The argument
129  .Fa format
130  may not be omitted.
131  .It Fn com_err_va "whoami" "code" "format" "va_list args"
132  This routine provides an interface, equivalent to
133  .Fn com_err ,
134  which may be used by higher-level variadic functions (functions which
135  accept variable numbers of arguments).
136  .It Fn error_message "code"
137  Returns the character string error message associate with
138  .Fa code .
139  If
140  .Fa code is associated with an unknown error table, or if
141  .Fa code
142  is associated with a known error table but is not in the table, a
143  string of the form `Unknown code XXXX NN' is returned, where XXXX is
144  the error table name produced by reversing the compaction performed on
145  the error table number implied by that error code, and NN is the
146  offset from that base value.
147  .Pp
148  Although this routine is available for use when needed, its use should
149  be left to circumstances which render
150  .Fn com_err
151  unusable.
152  .Pp
153  .Fn com_right
154  returns the error string just like
155  .Fa com_err
156  but in a thread-safe way.
157  .Pp
158  .It Fn error_table_name "num"
159  Convert a machine-independent error table number
160  .Fa num
161  into an error table name.
162  .It Fn init_error_table "msgs" "base" "count"
163  Initialise the internal error table with the array of character string
164  error messages in
165  .Fa msgs
166  of length
167  .Fa count .
168  The error codes are assigned incrementally from
169  .Fa base .
170  This function is useful for using the error-reporting mechanism with
171  custom error tables that have not been generated with
172  .Xr compile_et 1 .
173  Although this routine is available for use when needed, its use should
174  be restricted.
175  .Pp
176  .Fn initialize_error_table_r
177  initialize the
178  .Fa et_list
179  in the same way as
180  .Fn init_error_table ,
181  but in a thread-safe way.
182  .Pp
183  .It Fn set_com_err_hook "func"
184  Provides a hook into the
185  .Nm
186  library to allow the routine
187  .Fa func
188  to be dynamically substituted for
189  .Fn com_err .
190  After
191  .Fn set_com_err_hook
192   has been called, calls to
193  .Fn com_err
194  will turn into calls to the new hook routine.  This function is
195  intended to be used in daemons to use a routine which calls
196  .Xr syslog 3 ,
197  or in a window system application to pop up a dialogue box.
198  .It Fn reset_com_err_hook ""
199  Turns off the hook set in
200  .Fn set_com_err_hook .
201  .It Fn add_to_error_table "new_table"
202  Add the error table, its messages strings and error codes in
203  .Fa new_table
204  to the internal error table.
205  .El
206  .Sh EXAMPLES
207  The following is an example using the table defined in
208  .Xr compile_et 1 :
209  .Pp
210  .Bd -literal
211  	#include <stdio.h>
212  	#include <stdarg.h>
213  	#include <syslog.h>
214  
215  	#include "test_err.h"
216  
217  	void
218  	hook(const char *whoami, long code,
219  		const char *format, va_list args)
220  	{
221  		char buffer[BUFSIZ];
222  		static int initialized = 0;
223  
224  		if (!initialized) {
225  			openlog(whoami, LOG_NOWAIT, LOG_DAEMON);
226  			initialized = 1;
227  		}
228  		vsprintf(buffer, format, args);
229  		syslog(LOG_ERR, "%s %s", error_message(code), buffer);
230  	}
231  
232  	int
233  	main(int argc, char *argv[])
234  	{
235  		char *whoami = argv[0];
236  
237  		initialize_test_error_table();
238  		com_err(whoami, TEST_INVAL, "before hook");
239  		set_com_err_hook(hook);
240  		com_err(whoami, TEST_IO, "after hook");
241  		return (0);
242  	}
243  .Ed
244  .Sh SEE ALSO
245  .Xr compile_et 1