| blob | df47d342ba8cb8df85ae0a6159fd1e36bac0dce7 |
1 .fp 5 CW
2 .de Af
3 .ds ;G \\*(;G\\f\\$1\\$3\\f\\$2
5 ..
6 .de aF
8 .el \{\
9 .ds ;G \&
10 .nr ;G \\n(.f
11 .Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
12 \\*(;G
13 .ft \\n(;G \}
14 ..
15 .de L
16 .aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
17 ..
18 .de LR
19 .aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
20 ..
21 .de RL
22 .aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
23 ..
24 .de EX \" start example
25 .ta 1i 2i 3i 4i 5i 6i
26 .PP
27 .RS
28 .PD 0
29 .ft 5
30 .nf
31 ..
32 .de EE \" end example
33 .fi
34 .ft
35 .PD
36 .RE
37 .PP
38 ..
39 .TH ERROR 3
40 .SH NAME
41 error \- error and debug trace message formatter
42 .SH SYNOPSIS
43 .EX
44 #include <error.h>
46 Error_info_t error_info;
48 void error(int \fIlevel\fP, ...);
49 void errorv(const char* \fIlibrary\fP, int \fIlevel\fP, va_alist \fIargs\fP);
50 void liberror(const char* \fIlibrary\fP, int \fIlevel\fP, ...);
52 #include <debug.h>
54 debug(\fIstatement\fP)
55 message((int \fIlevel\fP, ...))
56 libmessage((const char* \fIlibrary\fI, int \fIlevel\fP, ...))
57 .EE
58 .SH DESCRIPTION
59 .L error
60 is the error and debug trace message formatter.
61 .I level
62 is the severity level.
63 Messages with
64 .I "level < error_info.trace"
65 are suppressed.
66 .I error_info.trace
67 is initially
68 .LR 0 .
69 The remaining arguments are passed on to
70 .LR printf .
71 A
72 .I newline
73 is appended to the message text, so none should appear in the
74 .L printf
75 format.
76 If
77 .I error_info.id
78 is not
79 .L 0
80 then messages with
81 .I "level > 0"
82 are prefixed by
83 .IR error_info.id: .
84 .PP
85 Before the message text is output to standard error
86 it is passed to the function
87 .LR "char* ERROR_translate(const char* \fItext\fP, int \fIflag\fP)" .
88 By default
89 .L ERROR_translate
90 returns the
91 .L text
92 argument, but on some systems it may do language translation via lookup
93 on the original source text.
94 .RL ( error
95 calls
96 .L ERROR_translate
97 with a 0
98 .L flag
99 argument).
100 .PP
101 .I level
102 may be one of:
103 .TP
104 .B <0
105 Negative values are for debug tracing.
106 Debug messages are prefixed with
107 .BI debug level.
108 If
109 .I "errno != error_info.last_errno"
110 then
111 .I error_info.last_errno
112 is set to
113 .I errno
114 and the error text for errno is appended to the message.
115 .TP
116 .B "ERROR_INFO [0]"
117 Information only; no prefixes are added to the message.
118 .TP
119 .B "ERROR_WARNING [1]"
120 .L "warning:"
121 is added after
122 .L error_info.id
123 and
124 .I error_info.warnings
125 is incremented.
126 .TP
127 .I "ERROR_ERROR [2]"
128 (soft error)
129 .I error_info.errors
130 is incremented.
131 .TP
132 .B ">= ERROR_FATAL [3]"
133 (hard error)
134 .I error_info.errors
135 is incremented and
136 .L exit(\fIlevel\fP\-2)
137 is called after the message is emitted.
138 .TP
139 .B "ERROR_PANIC [77]"
140 (unrecoverable internal error)
141 .L "panic:"
142 is added after
143 .IR error_info.id .
144 .PP
145 The following may be inclusive-or'd into
146 .I level
147 for alternate behavior:
148 .TP
149 .L ERROR_SYSTEM
150 The error text for
151 .I errno
152 is appended to the message.
153 .TP
154 .L ERROR_OUTPUT
155 The next argument is the file descriptor where the error message
156 should be emitted.
157 .TP
158 .L ERROR_SOURCE
159 Then next two arguments are a file name and line number that are added
160 to the message after
161 .IR error_info.id .
162 .TP
163 .L ERROR_USAGE
164 A usage message is emitted.
165 .TP
166 .L ERROR_PROMPT
167 The trailing
168 .I newline
169 is suppressed.
170 .TP
171 .L ERROR_NOID
172 The
173 .I error_info.id
174 prefix is suppressed.
175 .TP
176 .L ERROR_LIBRARY
177 The message is from a library routine.
178 .SH ENVIRONMENT
179 The elements of the global struct
180 .I error_info
181 control error output and actions.
182 Parts of
183 .I error_info
184 can be initialized from the
185 .L ERROR_OPTIONS
186 environment variable.
187 .L ERROR_OPTIONS
188 contains space separated
189 .IR name [ =value ]
190 options, described below.
191 .TP
192 .I "int core"
193 If
194 .I "error_info.core != 0"
195 then
196 .I "level >= error_info.core"
197 generates a core dump.
198 Initialized by
199 .EX
200 ERROR_OPTIONS="core=\fIlevel\fP"
201 .EE
202 where
203 .I level
204 can be a number or one of
205 .LR error ,
206 .LR fatal ,
207 or
208 .LR panic .
209 .I error_info.core
210 is a handy way to get a stack trace at the exact point of error.
211 .TP
212 .I "int error_info.trace"
213 If
214 .I "error_info.trace != 0"
215 and
216 .I "level < error_info.trace"
217 then the error message text is suppressed.
218 .L exit()
219 may still be called if appropriate for
220 .IR level .
221 Initialized by
222 .EX
223 ERROR_OPTIONS="trace=\fIlevel\fP"
224 .EE
225 where
226 .I error_info.trace
227 is set to the negative of
228 .IR level .
229 .PP
230 Library error messages, suppressed by default, are enabled by
231 .EX
232 ERROR_OPTIONS="library"
233 .EE
234 The system
235 .I errno
236 message text can be forced for each message by
237 .EX
238 ERROR_OPTIONS="system"
239 .EE
240 .SH "EXTENDED DESCRIPTION"
241 .L "<debug.h>"
242 provides debugging message macros when
243 .L DEBUG
244 or
245 .L _TRACE_
246 are defined
247 .RL ( _TRACE_
248 is defined by
249 .I makerules
250 when
251 .L CCFLAGS
252 contains
253 .LR \-g ).
254 All of the macros expand to nothing when both
255 .L DEBUG
256 and
257 .L _TRACE_
258 are not defined.
259 Otherwise
260 .L debug
261 expands its arg and
262 .L libmessage
263 and
264 .L message
265 call
266 .L liberror
267 and
268 .L error
269 respectively if
270 .IR "error_info.trace<0" .
271 Notice that
272 .L libmessage
273 and
274 .L message
275 are macro hacks that require double parentheses ((...)) around the
276 arguments.
277 .SH EXAMPLE
278 To enable debugging message level -3, library messages, and system
279 .I errno
280 text for all commands:
281 .EX
282 export ERROR_OPTIONS="trace=3 library system"
283 .EE