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
|
.\" Copyright (c) 1988 Massachusetts Institute of Technology,
.\" Student Information Processing Board. All rights reserved.
.\"
.\" $Header: /mit/zephyr/repository/zephyr/lib/et/com_err.3,v 1.2 1995/06/30 22:01:39 ghudson Exp $
.\"
.TH COM_ERR 3 "22 Nov 1988" SIPB
.SH NAME
com_err \- common error display routine
.SH SYNOPSIS
.nf
#include <com_err.h>
.PP
void initialize_XXXX_error_table(void);
.PP
void com_err(const char *\fIwhoami\fP, long \fIcode\fP,
const char *\fIformat\fP, ...);
.PP
const char *error_message(long \fIcode\fP);
.PP
const char *error_message_r(long \fIcode\fP, char *\fIbuf\fP);
.PP
typedef void(*error_handler_t)(const char *\fIwhoami\fP,
long \fIcode\fP, const char *\fIformat\fP, va_list \fIargs\fP);
.PP
error_handler_t set_com_err_hook(error_handler_t \fIproc\fP);
.PP
error_handler_t reset_com_err_hook(void);
.fi
.SH DESCRIPTION
\fICom_err\fP displays an error message on the standard error stream
\fIstderr\fP (see
.IR stdio (3S))
composed of the \fIwhoami\fP string, which should specify the program
name or some subportion of a program, followed by an error message
generated from the \fIcode\fP value (derived from
.IR compile_et (1)),
and a string produced using the \fIformat\fP string and any following
arguments, in the same style as
.IR fprintf (3).
The behavior of \fIcom_err\fP can be modified using
\fIset_com_err_hook\fP; this defines a procedure which is called with
the arguments passed to \fIcom_err\fP, instead of the default internal
procedure which sends the formatted text to error output. Thus the
error messages from a program can all easily be diverted to another
form of diagnostic logging, such as
.IR syslog (3).
\fIReset_com_err_hook\fP may be used to restore the behavior of
\fIcom_err\fP to its default form. Both procedures return the
previous ``hook'' value. These ``hook'' procedures must have the
declaration given for \fIproc\fP above in the synopsis.
The \fIinitialize_XXXX_error_table\fP routine is generated
mechanically by
.IR compile_et (1)
from a source file containing names and associated strings. Each
table has a name of up to four characters, which is used in place of
the \fBXXXX\fP in the name of the routine. These routines should be
called before any of the corresponding error codes are used, so that
the \fIcom_err\fP library will recognize error codes from these tables
when they are used.
The functions \fIerror_message\fP and \fIerror_message_r\fP return the
error message for an error code. \fIerror_message\fP may return its
error message inside a static buffer, and therefore is not reentrant;
\fIerror_message_r\fP will in these cases use the storage provided in
\fIbuf\fP, which should be at least \fBCOM_ERR_BUF_LEN\fP bytes long.
The \fBcom_err.h\fP header file should be included in any source file
that uses routines from the \fIcom_err\fP library; executable files
must be linked using \fI``-lcom_err''\fP in order to cause the
\fIcom_err\fP library to be included.
Multithreaded programs must perform all of the
\fIinitialize_XXXX_error_table\fP calls serially, but may perform them
in parallel with \fIcom_err\fP, \fIerror_message\fP, and
\fIerror_mesesage_r\fP calls as long as the call to
\fIinitialize_XXX_error_table\fP for a given table has completed
before any corresponding error codes are used. Calls to
\fIset_com_err_hook\fP and \fIreset_com_err_hook\fP must also be
performed serially or they may return the wrong old hook value.
.\" .IR for manual entries
.\" .PP for paragraph breaks
.SH "SEE ALSO"
compile_et (1), syslog (3).
Ken Raeburn, "A Common Error Description Library for UNIX".
|
