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