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