* Add this nice filesystem testing tool that I've recently
[dragonfly.git] / contrib / com_err / com_err.3
1 .\" Copyright (c) 1988 Massachusetts Institute of Technology,
2 .\" Student Information Processing Board.  All rights reserved.
3 .\"
4 .\" $FreeBSD: src/contrib/com_err/com_err.3,v 1.1 1999/09/04 09:48:58 markm Exp $
5 .\" $DragonFly: src/contrib/com_err/com_err.3,v 1.2 2003/06/17 04:23:58 dillon Exp $
6 .\"
7 .TH COM_ERR 3 "22 Nov 1988" SIPB
8 .SH NAME
9 com_err \- common error display routine
10 .SH SYNOPSIS
11 .nf
12  #include <com_err.h>
13 .PP
14 void com_err (whoami, code, format, ...);
15         const char *whoami;
16         long code;
17         const char *format;
18 .PP
19 proc = set_com_err_hook (proc);
20 .fi
21 void (*
22 .I proc
23 ) (const char *, long, const char *, va_list);
24 .nf
25 .PP
26 proc = reset_com_err_hook ();
27 .PP
28 void initialize_XXXX_error_table ();
29 .fi
30 .SH DESCRIPTION
31 .I Com_err
32 displays an error message on the standard error stream
33 .I stderr
34 (see
35 .IR stdio (3S))
36 composed of the
37 .I whoami
38 string, which should specify the program name or some subportion of
39 a program, followed by an error message generated from the
40 .I code
41 value (derived from
42 .IR compile_et (1)),
43 and a string produced using the
44 .I format
45 string and any following arguments, in the same style as
46 .IR fprintf (3).
47
48 The behavior of
49 .I com_err
50 can be modified using
51 .I set_com_err_hook;
52 this defines a procedure which is called with the arguments passed to
53 .I com_err,
54 instead of the default internal procedure which sends the formatted
55 text to error output.  Thus the error messages from a program can all
56 easily be diverted to another form of diagnostic logging, such as
57 .IR syslog (3).
58 .I Reset_com_err_hook
59 may be used to restore the behavior of
60 .I com_err
61 to its default form.  Both procedures return the previous ``hook''
62 value.  These ``hook'' procedures must have the declaration given for
63 .I proc
64 above in the synopsis.
65
66 The
67 .I initialize_XXXX_error_table
68 routine is generated mechanically by
69 .IR compile_et (1)
70 from a source file containing names and associated strings.  Each
71 table has a name of up to four characters, which is used in place of
72 the
73 .B XXXX
74 in the name of the routine.  These routines should be called before
75 any of the corresponding error codes are used, so that the
76 .I com_err
77 library will recognize error codes from these tables when they are
78 used.
79
80 The
81 .B com_err.h
82 header file should be included in any source file that uses routines
83 from the
84 .I com_err
85 library; executable files must be linked using
86 .I ``-lcom_err''
87 in order to cause the
88 .I com_err
89 library to be included.
90
91 .\" .IR for manual entries
92 .\" .PP for paragraph breaks
93
94 .SH "SEE ALSO"
95 compile_et (1), syslog (3).
96
97 Ken Raeburn, "A Common Error Description Library for UNIX".