aboutsummaryrefslogtreecommitdiffstats
path: root/doc/info/chap/error-reporting.texinfo
blob: cc256cd22316ee20311e96585d3afdcc80453fe2 (plain) (blame)
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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
@node Error reporting
@chapter Error reporting

Many functions, especially those involving
system calls, detect and report exceptional
conditions, including error conditions and
interruptions. Exception conditions must often
be checked and handled, often by retrying,
doing something else, or reporting the error
to the user and exit.

Unless otherwise specified, exceptional
conditions are reporting using the facilities
described in this chapter.


@menu
* Error checking::                            Checking whether an exception condition occurred.
* Error codes::                               Values for @code{errno}.
* Error messages::                            Reporting errors to the user.
@end menu



@node Error checking
@section Error checking

@cpindex Checking for errors
@cpindex Errors checking
@cpindex Exception checking
Most functions return a sentinel value when an
exceptional condition occurs, typically a negative
value (actually @code{-1}), a constant such as
@code{EOF}, or @code{NULL}. This return value only
tells you that an exeception condition has occurred.

@hfindex errno.h
@lvindex errno
By including the header file @file{<errno.h>}, the
modifiable lvalue @code{errno} is made available.
@sc{ISO}@tie{}C specifies that @code{errno} is not
necessarily a variable, but rather just an modifiable
lvalue. In fact, must @code{libc}:s, including
@code{slibc} defines it as a macro that calls a
function and uses the unary @code{*}-operator on the
return.

@code{errno} is often thought of as a variable
declared as @code{int errno}, or @code{volatile int errno}.
But the value is thread-local, and is thus more
like @code{_Thread_local volatile int errno}. Because
of this, the @code{errno} is defined as a macro that
calls a function. Otherwise, it would not be
implementable without @sc{ISO}@tie{}C11.

The value of @code{errno} is describes the error,
if and only if the function returned a value indicating
an error. Some, function can return the sentinel
value both on success and error. Therefore, the value
@code{0} on @code{errno} means that the function
returned after successful completion rather than on
failure. Exceptional conditions are describe by
non-zero values listed in @ref{Error codes}.

The state of @code{errno} is undefined unless otherwise
specified after a succesful completion of a function call.
This means that you, generally, cannot check whether an
error has occurred by checking the value of @code{errno}
rather than the return value.



@node Error codes
@section Error codes

TODO: The list of error codes have not be added to slibc yet.



@node Error messages
@section Error messages

@cpindex Error messages
@cpindex Printing errors
@cpindex Errors, printing
The C standard library provides a several mechanisms
for reporting errors to the user, spread out over
a few header files.

@table @code
@item void perror(const char* prefix)
@fnindex perror
@hfindex stdio.h
The @sc{POSIX}.1-2001 standard
(@code{_POSIX_C_SOURCE >= 200112L}), the
@sc{ISO}@tie{}C89 standard, and 4.3 @sc{BSD}
(@code{_BSD_SOURCE}) added this function
to the header file @file{<stdio.h>}.

This function prints an error message
for the current value on @code{errno},
to stderr. If @code{prefix} is neither
@code{NULL} or an empty string, @code{prefix}
followed by a colon and a blank space,
is prepended to the ouput. The function
will also (always) add a line feed to
the end of the message.

This function does not detect or report
errors. Thus, you should not use this
function if you want to be able to tell
whether the messages was actually printed.
Of course, if it was not, your only option
is to print it to another file descriptor
which you normally do not want to do.

This function is subject to race condition
over @code{stderr}.

Because successful function calls may change
the value on @code{errno}, its value must
be saved if there are function calls between
the failure and the call to @code{perror}.

@lvindex program_invocation_name
@lvindex program_invocation_short_name
It is customary to set @code{prefix} to
a value equivalent to @code{program_invocation_name},
or alternatively @code{program_invocation_short_name}.
Sometiems, the name of the called function is
used, this is to simplify debugging. But the
standard is that programs shall print there
them when reporting an error so that the user
knows that program failed.

TODO: Not implemented.

@item char* strerror(int errnum)
@fnindex strerror
@hfindex string.h
The @sc{POSIX}.1-2001 standard
(@code{_POSIX_C_SOURCE >= 200112L}) and
@sc{ISO}@tie{}C89 standard, defines this
function in the header file @file{<string.h>}.

@vrindex LC_MESSAGES
This function returns a description of
the error code whose number is @code{errnum}.
Description may or may not (it is in @command{slibc})
be localised using the @env{LC_MESSAGES} part of
the current locale.

The returned value must not be modified the
the program, by it may be modified by subsequent
calls to @code{strerror}-functions. If the error
code is not recognised some implementations
will return @code{NULL}, other implementations,
such as @command{slibc}'s, will return a message
that states to number of the error code.

According to @sc{POSIX}, @code{errno} must not
be modified if the call is successful. It may
however set @code{errno} on failure. However,
the @command{slibc} implementation cannot fail.

@command{slibc}'s implementation of this function
is threadsafe, this is however not true for
all implementions.

@item int strerror_r(int errnum, char* buffer, size_t size)
@fnindex strerror_r
@hfindex string.h
The @sc{POSIX}.1-2001 standard added this function
to the header file @file{<string.h>}. It is a
reenterant variant fo @code{strerror}. Instead of
returning the error message, it saves it to
@code{buffer}. The allocation size of @code{buffer}
is pass to the function via the argument @code{size}.
If it is too small, @code{ERANGE} is returned.

The function returns a positive value, that is
appropriate for @code{errno}, on error, rather than
setting the value of @code{errno}. Upon successful
completion, @code{0} is returned.

This function is not available if @code{_PORTABLE_SOURCE}
or @code{_LIBRARY_HEADER} is defined, because it is
conflicting with the @sc{GNU}-version. Without knowning
which version that is used, it is impossible to
check for errors.

This function is also non-portable even if the
@sc{GNU}-version is not used, that is, if
@code{_GNU_SOURCE} is not defined and
@code{(_POSIX_C_SOURCE >= 200112L) || (_XOPEN_SOURCE >= 600)}.
Old versions of @sc{GNU} C Library, returned @code{-1}
on failure and set @code{errno}, instead of returned
a value for @code{errno}.

Whilst @code{strerror_r} is not portable, the most
portable use of @code{strerror_r} is
@example
int r;
r = strerror_r(errnum, buffer, size);
if (r > 0 ? (errno = r) : r)
  goto fail;
@end example

Note that, unlike @code{strerror}, there is no
restriction against @code{strerror_r} to set
@code{errno} on success.

@item char* strerror_r(int errnum, char* buffer, size_t size)
@fnindex strerror_r
@hfindex string.h
This is a @sc{GNU} extension, defined in the header file
@file{<string.h>} and is available, instead of the
@sc{XSI}-compliant version, if @code{_GNU_SOURCE} is
defined or if
@code{(_POSIX_C_SOURCE < 200112L) && (_XOPEN_SOURCE < 600)}.
It is identical to the @sc{XSI}-compliant version,
except, rather than returning an error code, it
will set @code{errno} and return @code{NULL} on
failure. On successful completion, @code{buffer}
is returned.

This function is not available if @code{_PORTABLE_SOURCE}
or @code{_LIBRARY_HEADER} is defined, because it is
conflicting with the @sc{XSI}-compliant version. Without
knowning which version that is used, it is impossible
to check for errors.

@item char* strerror_l(int errnum, locale_t locale)
@fnindex strerror_l
@hfindex string.h
The @sc{POSIX}.1-2008 standard
(@code{_POSIX_C_SOURCE >= 200809L}),
defines this function in the header file
@file{<string.h>}. It is identical to
@code{strerror_l} with two exceptions:
it is thread save, and it uses a specified
locale.

@lvindex LC_GLOBAL_LOCALE
The behaviour of this function is undefined
if @code{locale} is @code{LC_GLOBAL_LOCALE}.

@item const char* const sys_errlist[]
This variable is defined in the header files
@file{<errno.h>} (derived from @sc{BSD}
@code{libc}) and @file{<stdio.h>} (derived
from @sc{GNU} @code{libc}) if @code{_BSD_SOURCE}
is defined.

This is a list, index by error codes, of
error messages.

This list is deprecated, and all error codes
may not have been added in all @code{libc}
implementations.

TODO: Not implemented.

@item int sys_nerr
This variable is defined in the header files
@file{<errno.h>} (derived from @sc{BSD}
@code{libc}) and @file{<stdio.h>} (derived
from @sc{GNU} @code{libc}) if @code{_BSD_SOURCE}
is defined.

This is the number of error codes that are
defined, including @code{0} (successful completion.)
That is, the value of the error code with
highest value, plus 1.

TODO: Not implemented.

@item char* program_invocation_name
@lvindex program_invocation_name
@hfindex errno.h
@cpindex Process name
This variable is defined in the header file
@file{<errno.h>}, if @code{_GNU_SOURCE} or
@code{_SLIBC_SOURCE} is defined.

This is the name that was used to invoke the
program running in the current process. This
is the value @code{argv[0]} from the @code{main}
function (where @code{argv} is the second parameter.)
If @code{argc} (the first parameter) is zero, this
variable will have the value @code{NULL}. This is
not necessarily a proper command name. For example,
login shells are usually prefixes with a dash,
for example @code{-bash}, despite that there is
no such command. Often, but not always, this will
not contain directory.

It is recommended for portable programs
to saved the value of @code{argv[0]} from
@code{main} to a global variable (often
named @code{argv0}) instead of using this
variable.

@item char* program_invocation_short_name
@lvindex program_invocation_short_name
@hfindex errno.h
@cpindex Process name
This variable is defined in the header file
@file{<errno.h>}, if @code{_GNU_SOURCE} is
defined. It is similar to @code{program_invocation_name},
but it only contains the basename, that is,
the part after the last slash.

If @code{program_invocation_name} is edited,
@code{program_invocation_short_name} may be
modified too.

@item void warn(const char* format, ...)
@fnindex warn
@hfindex err.h
This function is a non-standard @sc{BSD}
extension, and requires that @code{_BSD_SOURCE}
is defined. It is made available by including
the header file @file{<err.h>}. It is similar
to @code{printf} except it prints the message
to stderr, and a description of the error
specified by the current value on @code{errno}
is also printed.

@item void vwarn(const char* format, va_list args)
@fnindex vwarn
@hfindex err.h
This function is a non-standard @sc{BSD}
extension, and requires that @code{_BSD_SOURCE}
is defined. It is made available by including
the header file @file{<err.h>}. It is identical
to @code{warn} except it uses @code{va_list}
instead of being a variadic function.

@item void warnx(const char* format, ...)
@fnindex warnx
@hfindex err.h
This function is a non-standard @sc{BSD}
extension, and requires that @code{_BSD_SOURCE}
is defined. It is made available by including
the header file @file{<err.h>}. It is identical
to @code{warn} except it does not print a
description of the value of @code{errno}.

@item void vwarnx(const char* format, va_list args)
@fnindex vwarnx
@hfindex err.h
This function is a non-standard @sc{BSD}
extension, and requires that @code{_BSD_SOURCE}
is defined. It is made available by including
the header file @file{<err.h>}. It is identical
to @code{warnx} except it uses @code{va_list}
instead of being a variadic function.

@item noreturn void err(int status, const char* format, ...)
@fnindex err
@hfindex err.h
This function is a non-standard @sc{BSD}
extension, and requires that @code{_BSD_SOURCE}
is defined. It is made available by including
the header file @file{<err.h>}. It is identical
to @code{warn} except will return with the
exit value @code{status & 255}.

@item noreturn void verr(int status, const char* format, va_list args)
@fnindex verr
@hfindex err.h
This function is a non-standard @sc{BSD}
extension, and requires that @code{_BSD_SOURCE}
is defined. It is made available by including
the header file @file{<err.h>}. It is identical
to @code{err} except it uses @code{va_list}
instead of being a variadic function.

@item noreturn void errx(int status, const char* format, ...)
@fnindex errx
@hfindex err.h
This function is a non-standard @sc{BSD}
extension, and requires that @code{_BSD_SOURCE}
is defined. It is made available by including
the header file @file{<err.h>}. It is identical
to @code{err} except it does not print a
description of the value of @code{errno}.

@item noreturn void verrx(int status, const char* format, va_list args)
@fnindex verrx
@hfindex err.h
This function is a non-standard @sc{BSD}
extension, and requires that @code{_BSD_SOURCE}
is defined. It is made available by including
the header file @file{<err.h>}. It is identical
to @code{errx} except it uses @code{va_list}
instead of being a variadic function.

@end table