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