1.\" Copyright (c) 1988 Massachusetts Institute of Technology,
2.\" Student Information Processing Board. All rights reserved.
| 1.\" Copyright (c) 2005 Kungliga Tekniska H��gskolan
2.\" (Royal Institute of Technology, Stockholm, Sweden).
3.\" All rights reserved.
|
3.\"
| 4.\"
|
4.\" $FreeBSD: head/contrib/com_err/com_err.3 50880 1999-09-04 09:49:02Z markm $
| 5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
|
5.\"
| 8.\"
|
6.TH COM_ERR 3 "22 Nov 1988" SIPB
7.SH NAME
8com_err \- common error display routine
9.SH SYNOPSIS
10.nf
11 #include <com_err.h>
12.PP
13void com_err (whoami, code, format, ...);
14 const char *whoami;
15 long code;
16 const char *format;
17.PP
18proc = set_com_err_hook (proc);
19.fi
20void (*
21.I proc
22) (const char *, long, const char *, va_list);
23.nf
24.PP
25proc = reset_com_err_hook ();
26.PP
27void initialize_XXXX_error_table ();
28.fi
29.SH DESCRIPTION
30.I Com_err
31displays an error message on the standard error stream
32.I stderr
33(see
34.IR stdio (3S))
35composed of the
36.I whoami
37string, which should specify the program name or some subportion of
38a program, followed by an error message generated from the
39.I code
40value (derived from
41.IR compile_et (1)),
| 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
53Common 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
60typedef 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
84The
85.Nm
86library provides a common error-reporting mechanism for defining and
87accessing error codes and descriptions for application software
88packages. Error descriptions are defined in a table and error codes
89are used to index the table. The error table, the descriptions and
90the error codes are generated using
91.Xr compile_et 1 .
92.Pp
93The error table is registered with the
94.Nm
95library by calling its initialisation function defined in its header
96file. The initialisation function is generally defined as
97.Fn initialize_<name>_error_table ,
98where
99.Em name
100is the name of the error table.
101.Pp
102If a thread-safe version of the library is needed
103.Fn initialize_<name>_error_table_r
104that internally calls
105.Fn initialize_error_table_r
106instead be used.
107.Pp
108Any variable which is to contain an error code should be declared
109.Em <name>_error_number
110where
111.Em name
112is the name of the error table.
113.Sh FUNCTIONS
114The following functions are available to the application developer:
115.Bl -tag -width compact
116.It Fn com_err "whoami" "code" "format" "..."
117Displays an error message on standard error composed of the
118.Fa whoami
119string, which should specify the program name, followed by an error
120message generated from
121.Fa code ,
|
42and a string produced using the
| 122and a string produced using the
|
43.I format
44string and any following arguments, in the same style as
45.IR fprintf (3).
| 123.Xr printf 3
124.Fa format
125string and any following arguments. If
126.Fa format
127is NULL, the formatted message will not be
128printed. The argument
129.Fa format
130may not be omitted.
131.It Fn com_err_va "whoami" "code" "format" "va_list args"
132This routine provides an interface, equivalent to
133.Fn com_err ,
134which may be used by higher-level variadic functions (functions which
135accept variable numbers of arguments).
136.It Fn error_message "code"
137Returns the character string error message associate with
138.Fa code .
139If
140.Fa code is associated with an unknown error table, or if
141.Fa code
142is associated with a known error table but is not in the table, a
143string of the form `Unknown code XXXX NN' is returned, where XXXX is
144the error table name produced by reversing the compaction performed on
145the error table number implied by that error code, and NN is the
146offset from that base value.
147.Pp
148Although this routine is available for use when needed, its use should
149be left to circumstances which render
150.Fn com_err
151unusable.
152.Pp
153.Fn com_right
154returns the error string just like
155.Fa com_err
156but in a thread-safe way.
157.Pp
158.It Fn error_table_name "num"
159Convert a machine-independent error table number
160.Fa num
161into an error table name.
162.It Fn init_error_table "msgs" "base" "count"
163Initialise the internal error table with the array of character string
164error messages in
165.Fa msgs
166of length
167.Fa count .
168The error codes are assigned incrementally from
169.Fa base .
170This function is useful for using the error-reporting mechanism with
171custom error tables that have not been generated with
172.Xr compile_et 1 .
173Although this routine is available for use when needed, its use should
174be restricted.
175.Pp
176.Fn initialize_error_table_r
177initialize the
178.Fa et_list
179in the same way as
180.Fn init_error_table ,
181but in a thread-safe way.
182.Pp
183.It Fn set_com_err_hook "func"
184Provides a hook into the
185.Nm
186library to allow the routine
187.Fa func
188to be dynamically substituted for
189.Fn com_err .
190After
191.Fn set_com_err_hook
192 has been called, calls to
193.Fn com_err
194will turn into calls to the new hook routine. This function is
195intended to be used in daemons to use a routine which calls
196.Xr syslog 3 ,
197or in a window system application to pop up a dialogue box.
198.It Fn reset_com_err_hook ""
199Turns off the hook set in
200.Fn set_com_err_hook .
201.It Fn add_to_error_table "new_table"
202Add the error table, its messages strings and error codes in
203.Fa new_table
204to the internal error table.
205.El
206.Sh EXAMPLES
207The 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>
|
46
| 214
|
47The behavior of
48.I com_err
49can be modified using
50.I set_com_err_hook;
51this defines a procedure which is called with the arguments passed to
52.I com_err,
53instead of the default internal procedure which sends the formatted
54text to error output. Thus the error messages from a program can all
55easily be diverted to another form of diagnostic logging, such as
56.IR syslog (3).
57.I Reset_com_err_hook
58may be used to restore the behavior of
59.I com_err
60to its default form. Both procedures return the previous ``hook''
61value. These ``hook'' procedures must have the declaration given for
62.I proc
63above in the synopsis.
| 215 #include "test_err.h"
|
64
| 216
|
65The
66.I initialize_XXXX_error_table
67routine is generated mechanically by
68.IR compile_et (1)
69from a source file containing names and associated strings. Each
70table has a name of up to four characters, which is used in place of
71the
72.B XXXX
73in the name of the routine. These routines should be called before
74any of the corresponding error codes are used, so that the
75.I com_err
76library will recognize error codes from these tables when they are
77used.
| 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;
|
78
| 223
|
79The
80.B com_err.h
81header file should be included in any source file that uses routines
82from the
83.I com_err
84library; executable files must be linked using
85.I ``-lcom_err''
86in order to cause the
87.I com_err
88library to be included.
| 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 }
|
89
| 231
|
90.\" .IR for manual entries
91.\" .PP for paragraph breaks
| 232 int
233 main(int argc, char *argv[])
234 {
235 char *whoami = argv[0];
|
92
| 236
|
93.SH "SEE ALSO"
94compile_et (1), syslog (3).
95
96Ken Raeburn, "A Common Error Description Library for UNIX".
| 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
|
| |