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