third_party/heimdal/lib/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 <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 associated with
 138 .Fa code .
 139 If
 140 .Fa code
 141 is associated with an unknown error table, or if
 142 .Fa code
 143 is associated with a known error table but is not in the table, a
 144 string of the form `Unknown code XXXX NN' is returned, where XXXX is
 145 the error table name produced by reversing the compaction performed on
 146 the error table number implied by that error code, and NN is the
 147 offset from that base value.
 148 .Pp
 149 Although this routine is available for use when needed, its use should
 150 be left to circumstances which render
 151 .Fn com_err
 152 unusable.
 153 .Pp
 154 .Fn com_right
 155 returns the error string just like
 156 .Fa com_err
 157 but in a thread-safe way.
 158 .Pp
 159 .It Fn error_table_name "num"
 160 Convert a machine-independent error table number
 161 .Fa num
 162 into an error table name.
 163 .It Fn init_error_table "msgs" "base" "count"
 164 Initialise the internal error table with the array of character string
 165 error messages in
 166 .Fa msgs
 167 of length
 168 .Fa count .
 169 The error codes are assigned incrementally from
 170 .Fa base .
 171 This function is useful for using the error-reporting mechanism with
 172 custom error tables that have not been generated with
 173 .Xr compile_et 1 .
 174 Although this routine is available for use when needed, its use should
 175 be restricted.
 176 .Pp
 177 .Fn initialize_error_table_r
 178 initialize the
 179 .Fa et_list
 180 in the same way as
 181 .Fn init_error_table ,
 182 but in a thread-safe way.
 183 .Pp
 184 .It Fn set_com_err_hook "func"
 185 Provides a hook into the
 186 .Nm
 187 library to allow the routine
 188 .Fa func
 189 to be dynamically substituted for
 190 .Fn com_err .
 191 After
 192 .Fn set_com_err_hook
 193  has been called, calls to
 194 .Fn com_err
 195 will turn into calls to the new hook routine.  This function is
 196 intended to be used in daemons to use a routine which calls
 197 .Xr syslog 3 ,
 198 or in a window system application to pop up a dialogue box.
 199 .It Fn reset_com_err_hook ""
 200 Turns off the hook set in
 201 .Fn set_com_err_hook .
 202 .It Fn add_to_error_table "new_table"
 203 Add the error table, its messages strings and error codes in
 204 .Fa new_table
 205 to the internal error table.
 206 .El
 207 .Sh EXAMPLES
 208 The following is an example using the table defined in
 209 .Xr compile_et 1 :
 210 .Pp
 211 .Bd -literal
 212         #include <stdio.h>
 213         #include <stdarg.h>
 214         #include <syslog.h>
 215
 216         #include "test_err.h"
 217
 218         void
 219         hook(const char *whoami, long code,
 220                 const char *format, va_list args)
 221         {
 222                 char buffer[BUFSIZ];
 223                 static int initialized = 0;
 224
 225                 if (!initialized) {
 226                         openlog(whoami, LOG_NOWAIT, LOG_DAEMON);
 227                         initialized = 1;
 228                 }
 229                 vsprintf(buffer, format, args);
 230                 syslog(LOG_ERR, "%s %s", error_message(code), buffer);
 231         }
 232
 233         int
 234         main(int argc, char *argv[])
 235         {
 236                 char *whoami = argv[0];
 237
 238                 initialize_test_error_table();
 239                 com_err(whoami, TEST_INVAL, "before hook");
 240                 set_com_err_hook(hook);
 241                 com_err(whoami, TEST_IO, "after hook");
 242                 return (0);
 243         }
 244 .Ed
 245 .Sh SEE ALSO
 246 .Xr compile_et 1