lib/libcom_err/com_err.3

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