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