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 53Common Error Library (libcom_err, -lcom_err) 54.Sh SYNOPSIS 55.Fd #include <stdio.h> 56.Fd #include <stdarg.h> 57.Fd #include <com_err.h> 58.Fd #include \&"XXX_err.h\&" 59.Pp 60typedef 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 84The 85.Nm 86library provides a common error-reporting mechanism for defining and 87accessing error codes and descriptions for application software 88packages. Error descriptions are defined in a table and error codes 89are used to index the table. The error table, the descriptions and 90the error codes are generated using 91.Xr compile_et 1 . 92.Pp 93The error table is registered with the 94.Nm 95library by calling its initialisation function defined in its header 96file. The initialisation function is generally defined as 97.Fn initialize_<name>_error_table , 98where 99.Em name 100is the name of the error table. 101.Pp 102If a thread-safe version of the library is needed 103.Fn initialize_<name>_error_table_r 104that internally calls 105.Fn initialize_error_table_r 106instead be used. 107.Pp 108Any variable which is to contain an error code should be declared 109.Em <name>_error_number 110where 111.Em name 112is the name of the error table. 113.Sh FUNCTIONS 114The following functions are available to the application developer: 115.Bl -tag -width compact 116.It Fn com_err "whoami" "code" "format" "..." 117Displays an error message on standard error composed of the 118.Fa whoami 119string, which should specify the program name, followed by an error 120message generated from 121.Fa code , 122and a string produced using the 123.Xr printf 3 124.Fa format 125string and any following arguments. If 126.Fa format 127is NULL, the formatted message will not be 128printed. The argument 129.Fa format 130may not be omitted. 131.It Fn com_err_va "whoami" "code" "format" "va_list args" 132This routine provides an interface, equivalent to 133.Fn com_err , 134which may be used by higher-level variadic functions (functions which 135accept variable numbers of arguments). 136.It Fn error_message "code" 137Returns the character string error message associate with 138.Fa code . 139If 140.Fa code is associated with an unknown error table, or if 141.Fa code 142is associated with a known error table but is not in the table, a 143string of the form `Unknown code XXXX NN' is returned, where XXXX is 144the error table name produced by reversing the compaction performed on 145the error table number implied by that error code, and NN is the 146offset from that base value. 147.Pp 148Although this routine is available for use when needed, its use should 149be left to circumstances which render 150.Fn com_err 151unusable. 152.Pp 153.Fn com_right 154returns the error string just like 155.Fa com_err 156but in a thread-safe way. 157.Pp 158.It Fn error_table_name "num" 159Convert a machine-independent error table number 160.Fa num 161into an error table name. 162.It Fn init_error_table "msgs" "base" "count" 163Initialise the internal error table with the array of character string 164error messages in 165.Fa msgs 166of length 167.Fa count . 168The error codes are assigned incrementally from 169.Fa base . 170This function is useful for using the error-reporting mechanism with 171custom error tables that have not been generated with 172.Xr compile_et 1 . 173Although this routine is available for use when needed, its use should 174be restricted. 175.Pp 176.Fn initialize_error_table_r 177initialize the 178.Fa et_list 179in the same way as 180.Fn init_error_table , 181but in a thread-safe way. 182.Pp 183.It Fn set_com_err_hook "func" 184Provides a hook into the 185.Nm 186library to allow the routine 187.Fa func 188to be dynamically substituted for 189.Fn com_err . 190After 191.Fn set_com_err_hook 192 has been called, calls to 193.Fn com_err 194will turn into calls to the new hook routine. This function is 195intended to be used in daemons to use a routine which calls 196.Xr syslog 3 , 197or in a window system application to pop up a dialogue box. 198.It Fn reset_com_err_hook "" 199Turns off the hook set in 200.Fn set_com_err_hook . 201.It Fn add_to_error_table "new_table" 202Add the error table, its messages strings and error codes in 203.Fa new_table 204to the internal error table. 205.El 206.Sh EXAMPLES 207The 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 246