aboutsummaryrefslogtreecommitdiff
path: root/com_err.3
diff options
context:
space:
mode:
authorStanislav Sedov <stas@FreeBSD.org>2011-10-06 07:54:28 +0000
committerStanislav Sedov <stas@FreeBSD.org>2011-10-06 07:54:28 +0000
commit011e35136d0dfc3508fd15c6f0c4db46a7682b7e (patch)
treea7540baba97f129269b8f8fbc2eb8532a8669eb8 /com_err.3
parent3a4f1ef479cb07533f2f416fe125ebd8521b3038 (diff)
downloadsrc-vendor/com_err.tar.gz
src-vendor/com_err.zip
- Import com_err from heimdal 1.5.1 distribution. I used sources from GITvendor/com_err/1.5.1vendor/com_err
as we don't need autogenerated files, and for some reason the actual distribution tarball is missing the com_err.3 manpage.
Notes
Notes: svn path=/vendor/com_err/dist/; revision=226052 svn path=/vendor/com_err/1.5.1/; revision=226053; tag=vendor/com_err/1.5.1
Diffstat (limited to 'com_err.3')
-rw-r--r--com_err.3245
1 files changed, 245 insertions, 0 deletions
diff --git a/com_err.3 b/com_err.3
new file mode 100644
index 000000000000..b71203aa11b5
--- /dev/null
+++ b/com_err.3
@@ -0,0 +1,245 @@
+.\" 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 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.
+.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