crypto/external/bsd/heimdal/dist/lib/com_err/com_err.3

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