contrib/com_err/com_err.3

   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 <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