.\"     $NetBSD: com_err.3,v 1.2 2008/04/30 13:10:51 martin Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Gregory McGarry.
.\"
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
.\"
.Dd November 21, 2001
.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
.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"
.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
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 associate 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.
.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.
.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