(openlog): Describe possible problems with string passed as first parameter.
[kopensolaris-gnu/glibc.git] / manual / errno.texi
1 @node Error Reporting, Memory, Introduction, Top
2 @chapter Error Reporting
3 @c %MENU% How library functions report errors
4 @cindex error reporting
5 @cindex reporting errors
6 @cindex error codes
7 @cindex status codes
8
9 Many functions in the GNU C library detect and report error conditions,
10 and sometimes your programs need to check for these error conditions.
11 For example, when you open an input file, you should verify that the
12 file was actually opened correctly, and print an error message or take
13 other appropriate action if the call to the library function failed.
14
15 This chapter describes how the error reporting facility works.  Your
16 program should include the header file @file{errno.h} to use this
17 facility.
18 @pindex errno.h
19
20 @menu
21 * Checking for Errors::         How errors are reported by library functions.
22 * Error Codes::                 Error code macros; all of these expand
23                                  into integer constant values.
24 * Error Messages::              Mapping error codes onto error messages.
25 @end menu
26
27 @node Checking for Errors, Error Codes,  , Error Reporting
28 @section Checking for Errors
29
30 Most library functions return a special value to indicate that they have
31 failed.  The special value is typically @code{-1}, a null pointer, or a
32 constant such as @code{EOF} that is defined for that purpose.  But this
33 return value tells you only that an error has occurred.  To find out
34 what kind of error it was, you need to look at the error code stored in the
35 variable @code{errno}.  This variable is declared in the header file
36 @file{errno.h}.
37 @pindex errno.h
38
39 @comment errno.h
40 @comment ISO
41 @deftypevr {Variable} {volatile int} errno
42 The variable @code{errno} contains the system error number.  You can
43 change the value of @code{errno}.
44
45 Since @code{errno} is declared @code{volatile}, it might be changed
46 asynchronously by a signal handler; see @ref{Defining Handlers}.
47 However, a properly written signal handler saves and restores the value
48 of @code{errno}, so you generally do not need to worry about this
49 possibility except when writing signal handlers.
50
51 The initial value of @code{errno} at program startup is zero.  Many
52 library functions are guaranteed to set it to certain nonzero values
53 when they encounter certain kinds of errors.  These error conditions are
54 listed for each function.  These functions do not change @code{errno}
55 when they succeed; thus, the value of @code{errno} after a successful
56 call is not necessarily zero, and you should not use @code{errno} to
57 determine @emph{whether} a call failed.  The proper way to do that is
58 documented for each function.  @emph{If} the call failed, you can
59 examine @code{errno}.
60
61 Many library functions can set @code{errno} to a nonzero value as a
62 result of calling other library functions which might fail.  You should
63 assume that any library function might alter @code{errno} when the
64 function returns an error.
65
66 @strong{Portability Note:} @w{ISO C} specifies @code{errno} as a
67 ``modifiable lvalue'' rather than as a variable, permitting it to be
68 implemented as a macro.  For example, its expansion might involve a
69 function call, like @w{@code{*_errno ()}}.  In fact, that is what it is
70 on the GNU system itself.  The GNU library, on non-GNU systems, does
71 whatever is right for the particular system.
72
73 There are a few library functions, like @code{sqrt} and @code{atan},
74 that return a perfectly legitimate value in case of an error, but also
75 set @code{errno}.  For these functions, if you want to check to see
76 whether an error occurred, the recommended method is to set @code{errno}
77 to zero before calling the function, and then check its value afterward.
78 @end deftypevr
79
80 @pindex errno.h
81 All the error codes have symbolic names; they are macros defined in
82 @file{errno.h}.  The names start with @samp{E} and an upper-case
83 letter or digit; you should consider names of this form to be
84 reserved names.  @xref{Reserved Names}.
85
86 The error code values are all positive integers and are all distinct,
87 with one exception: @code{EWOULDBLOCK} and @code{EAGAIN} are the same.
88 Since the values are distinct, you can use them as labels in a
89 @code{switch} statement; just don't use both @code{EWOULDBLOCK} and
90 @code{EAGAIN}.  Your program should not make any other assumptions about
91 the specific values of these symbolic constants.
92
93 The value of @code{errno} doesn't necessarily have to correspond to any
94 of these macros, since some library functions might return other error
95 codes of their own for other situations.  The only values that are
96 guaranteed to be meaningful for a particular library function are the
97 ones that this manual lists for that function.
98
99 On non-GNU systems, almost any system call can return @code{EFAULT} if
100 it is given an invalid pointer as an argument.  Since this could only
101 happen as a result of a bug in your program, and since it will not
102 happen on the GNU system, we have saved space by not mentioning
103 @code{EFAULT} in the descriptions of individual functions.
104
105 In some Unix systems, many system calls can also return @code{EFAULT} if
106 given as an argument a pointer into the stack, and the kernel for some
107 obscure reason fails in its attempt to extend the stack.  If this ever
108 happens, you should probably try using statically or dynamically
109 allocated memory instead of stack memory on that system.
110
111 @node Error Codes, Error Messages, Checking for Errors, Error Reporting
112 @section Error Codes
113
114 @pindex errno.h
115 The error code macros are defined in the header file @file{errno.h}.
116 All of them expand into integer constant values.  Some of these error
117 codes can't occur on the GNU system, but they can occur using the GNU
118 library on other systems.
119
120 @comment errno.h
121 @comment POSIX.1: Operation not permitted
122 @deftypevr Macro int EPERM
123 @comment errno 1 @c DO NOT REMOVE
124 Operation not permitted; only the owner of the file (or other resource)
125 or processes with special privileges can perform the operation.
126 @end deftypevr
127
128 @comment errno.h
129 @comment POSIX.1: No such file or directory
130 @deftypevr Macro int ENOENT
131 @comment errno 2 @c DO NOT REMOVE
132 No such file or directory.  This is a ``file doesn't exist'' error
133 for ordinary files that are referenced in contexts where they are
134 expected to already exist.
135 @end deftypevr
136
137 @comment errno.h
138 @comment POSIX.1: No such process
139 @deftypevr Macro int ESRCH
140 @comment errno 3 @c DO NOT REMOVE
141 No process matches the specified process ID.
142 @end deftypevr
143
144 @comment errno.h
145 @comment POSIX.1: Interrupted system call
146 @deftypevr Macro int EINTR
147 @comment errno 4 @c DO NOT REMOVE
148 Interrupted function call; an asynchronous signal occurred and prevented
149 completion of the call.  When this happens, you should try the call
150 again.
151
152 You can choose to have functions resume after a signal that is handled,
153 rather than failing with @code{EINTR}; see @ref{Interrupted
154 Primitives}.
155 @end deftypevr
156
157 @comment errno.h
158 @comment POSIX.1: Input/output error
159 @deftypevr Macro int EIO
160 @comment errno 5 @c DO NOT REMOVE
161 Input/output error; usually used for physical read or write errors.
162 @end deftypevr
163
164 @comment errno.h
165 @comment POSIX.1: No such device or address
166 @deftypevr Macro int ENXIO
167 @comment errno 6 @c DO NOT REMOVE
168 No such device or address.  The system tried to use the device
169 represented by a file you specified, and it couldn't find the device.
170 This can mean that the device file was installed incorrectly, or that
171 the physical device is missing or not correctly attached to the
172 computer.
173 @end deftypevr
174
175 @comment errno.h
176 @comment POSIX.1: Argument list too long
177 @deftypevr Macro int E2BIG
178 @comment errno 7 @c DO NOT REMOVE
179 Argument list too long; used when the arguments passed to a new program
180 being executed with one of the @code{exec} functions (@pxref{Executing a
181 File}) occupy too much memory space.  This condition never arises in the
182 GNU system.
183 @end deftypevr
184
185 @comment errno.h
186 @comment POSIX.1: Exec format error
187 @deftypevr Macro int ENOEXEC
188 @comment errno 8 @c DO NOT REMOVE
189 Invalid executable file format.  This condition is detected by the
190 @code{exec} functions; see @ref{Executing a File}.
191 @end deftypevr
192
193 @comment errno.h
194 @comment POSIX.1: Bad file descriptor
195 @deftypevr Macro int EBADF
196 @comment errno 9 @c DO NOT REMOVE
197 Bad file descriptor; for example, I/O on a descriptor that has been
198 closed or reading from a descriptor open only for writing (or vice
199 versa).
200 @end deftypevr
201
202 @comment errno.h
203 @comment POSIX.1: No child processes
204 @deftypevr Macro int ECHILD
205 @comment errno 10 @c DO NOT REMOVE
206 There are no child processes.  This error happens on operations that are
207 supposed to manipulate child processes, when there aren't any processes
208 to manipulate.
209 @end deftypevr
210
211 @comment errno.h
212 @comment POSIX.1: Resource deadlock avoided
213 @deftypevr Macro int EDEADLK
214 @comment errno 11 @c DO NOT REMOVE
215 Deadlock avoided; allocating a system resource would have resulted in a
216 deadlock situation.  The system does not guarantee that it will notice
217 all such situations.  This error means you got lucky and the system
218 noticed; it might just hang.  @xref{File Locks}, for an example.
219 @end deftypevr
220
221 @comment errno.h
222 @comment POSIX.1: Cannot allocate memory
223 @deftypevr Macro int ENOMEM
224 @comment errno 12 @c DO NOT REMOVE
225 No memory available.  The system cannot allocate more virtual memory
226 because its capacity is full.
227 @end deftypevr
228
229 @comment errno.h
230 @comment POSIX.1: Permission denied
231 @deftypevr Macro int EACCES
232 @comment errno 13 @c DO NOT REMOVE
233 Permission denied; the file permissions do not allow the attempted operation.
234 @end deftypevr
235
236 @comment errno.h
237 @comment POSIX.1: Bad address
238 @deftypevr Macro int EFAULT
239 @comment errno 14 @c DO NOT REMOVE
240 Bad address; an invalid pointer was detected.
241 In the GNU system, this error never happens; you get a signal instead.
242 @end deftypevr
243
244 @comment errno.h
245 @comment BSD: Block device required
246 @deftypevr Macro int ENOTBLK
247 @comment errno 15 @c DO NOT REMOVE
248 A file that isn't a block special file was given in a situation that
249 requires one.  For example, trying to mount an ordinary file as a file
250 system in Unix gives this error.
251 @end deftypevr
252
253 @comment errno.h
254 @comment POSIX.1: Device or resource busy
255 @deftypevr Macro int EBUSY
256 @comment errno 16 @c DO NOT REMOVE
257 Resource busy; a system resource that can't be shared is already in use.
258 For example, if you try to delete a file that is the root of a currently
259 mounted filesystem, you get this error.
260 @end deftypevr
261
262 @comment errno.h
263 @comment POSIX.1: File exists
264 @deftypevr Macro int EEXIST
265 @comment errno 17 @c DO NOT REMOVE
266 File exists; an existing file was specified in a context where it only
267 makes sense to specify a new file.
268 @end deftypevr
269
270 @comment errno.h
271 @comment POSIX.1: Invalid cross-device link
272 @deftypevr Macro int EXDEV
273 @comment errno 18 @c DO NOT REMOVE
274 An attempt to make an improper link across file systems was detected.
275 This happens not only when you use @code{link} (@pxref{Hard Links}) but
276 also when you rename a file with @code{rename} (@pxref{Renaming Files}).
277 @end deftypevr
278
279 @comment errno.h
280 @comment POSIX.1: No such device
281 @deftypevr Macro int ENODEV
282 @comment errno 19 @c DO NOT REMOVE
283 The wrong type of device was given to a function that expects a
284 particular sort of device.
285 @end deftypevr
286
287 @comment errno.h
288 @comment POSIX.1: Not a directory
289 @deftypevr Macro int ENOTDIR
290 @comment errno 20 @c DO NOT REMOVE
291 A file that isn't a directory was specified when a directory is required.
292 @end deftypevr
293
294 @comment errno.h
295 @comment POSIX.1: Is a directory
296 @deftypevr Macro int EISDIR
297 @comment errno 21 @c DO NOT REMOVE
298 File is a directory; you cannot open a directory for writing,
299 or create or remove hard links to it.
300 @end deftypevr
301
302 @comment errno.h
303 @comment POSIX.1: Invalid argument
304 @deftypevr Macro int EINVAL
305 @comment errno 22 @c DO NOT REMOVE
306 Invalid argument.  This is used to indicate various kinds of problems
307 with passing the wrong argument to a library function.
308 @end deftypevr
309
310 @comment errno.h
311 @comment POSIX.1: Too many open files
312 @deftypevr Macro int EMFILE
313 @comment errno 24 @c DO NOT REMOVE
314 The current process has too many files open and can't open any more.
315 Duplicate descriptors do count toward this limit.
316
317 In BSD and GNU, the number of open files is controlled by a resource
318 limit that can usually be increased.  If you get this error, you might
319 want to increase the @code{RLIMIT_NOFILE} limit or make it unlimited;
320 @pxref{Limits on Resources}.
321 @end deftypevr
322
323 @comment errno.h
324 @comment POSIX.1: Too many open files in system
325 @deftypevr Macro int ENFILE
326 @comment errno 23 @c DO NOT REMOVE
327 There are too many distinct file openings in the entire system.  Note
328 that any number of linked channels count as just one file opening; see
329 @ref{Linked Channels}.  This error never occurs in the GNU system.
330 @end deftypevr
331
332 @comment errno.h
333 @comment POSIX.1: Inappropriate ioctl for device
334 @deftypevr Macro int ENOTTY
335 @comment errno 25 @c DO NOT REMOVE
336 Inappropriate I/O control operation, such as trying to set terminal
337 modes on an ordinary file.
338 @end deftypevr
339
340 @comment errno.h
341 @comment BSD: Text file busy
342 @deftypevr Macro int ETXTBSY
343 @comment errno 26 @c DO NOT REMOVE
344 An attempt to execute a file that is currently open for writing, or
345 write to a file that is currently being executed.  Often using a
346 debugger to run a program is considered having it open for writing and
347 will cause this error.  (The name stands for ``text file busy''.)  This
348 is not an error in the GNU system; the text is copied as necessary.
349 @end deftypevr
350
351 @comment errno.h
352 @comment POSIX.1: File too large
353 @deftypevr Macro int EFBIG
354 @comment errno 27 @c DO NOT REMOVE
355 File too big; the size of a file would be larger than allowed by the system.
356 @end deftypevr
357
358 @comment errno.h
359 @comment POSIX.1: No space left on device
360 @deftypevr Macro int ENOSPC
361 @comment errno 28 @c DO NOT REMOVE
362 No space left on device; write operation on a file failed because the
363 disk is full.
364 @end deftypevr
365
366 @comment errno.h
367 @comment POSIX.1: Illegal seek
368 @deftypevr Macro int ESPIPE
369 @comment errno 29 @c DO NOT REMOVE
370 Invalid seek operation (such as on a pipe).
371 @end deftypevr
372
373 @comment errno.h
374 @comment POSIX.1: Read-only file system
375 @deftypevr Macro int EROFS
376 @comment errno 30 @c DO NOT REMOVE
377 An attempt was made to modify something on a read-only file system.
378 @end deftypevr
379
380 @comment errno.h
381 @comment POSIX.1: Too many links
382 @deftypevr Macro int EMLINK
383 @comment errno 31 @c DO NOT REMOVE
384 Too many links; the link count of a single file would become too large.
385 @code{rename} can cause this error if the file being renamed already has
386 as many links as it can take (@pxref{Renaming Files}).
387 @end deftypevr
388
389 @comment errno.h
390 @comment POSIX.1: Broken pipe
391 @deftypevr Macro int EPIPE
392 @comment errno 32 @c DO NOT REMOVE
393 Broken pipe; there is no process reading from the other end of a pipe.
394 Every library function that returns this error code also generates a
395 @code{SIGPIPE} signal; this signal terminates the program if not handled
396 or blocked.  Thus, your program will never actually see @code{EPIPE}
397 unless it has handled or blocked @code{SIGPIPE}.
398 @end deftypevr
399
400 @comment errno.h
401 @comment ISO: Numerical argument out of domain
402 @deftypevr Macro int EDOM
403 @comment errno 33 @c DO NOT REMOVE
404 Domain error; used by mathematical functions when an argument value does
405 not fall into the domain over which the function is defined.
406 @end deftypevr
407
408 @comment errno.h
409 @comment ISO: Numerical result out of range
410 @deftypevr Macro int ERANGE
411 @comment errno 34 @c DO NOT REMOVE
412 Range error; used by mathematical functions when the result value is
413 not representable because of overflow or underflow.
414 @end deftypevr
415
416 @comment errno.h
417 @comment POSIX.1: Resource temporarily unavailable
418 @deftypevr Macro int EAGAIN
419 @comment errno 35 @c DO NOT REMOVE
420 Resource temporarily unavailable; the call might work if you try again
421 later.  The macro @code{EWOULDBLOCK} is another name for @code{EAGAIN};
422 they are always the same in the GNU C library.
423
424 This error can happen in a few different situations:
425
426 @itemize @bullet
427 @item
428 An operation that would block was attempted on an object that has
429 non-blocking mode selected.  Trying the same operation again will block
430 until some external condition makes it possible to read, write, or
431 connect (whatever the operation).  You can use @code{select} to find out
432 when the operation will be possible; @pxref{Waiting for I/O}.
433
434 @strong{Portability Note:} In many older Unix systems, this condition
435 was indicated by @code{EWOULDBLOCK}, which was a distinct error code
436 different from @code{EAGAIN}.  To make your program portable, you should
437 check for both codes and treat them the same.
438
439 @item
440 A temporary resource shortage made an operation impossible.  @code{fork}
441 can return this error.  It indicates that the shortage is expected to
442 pass, so your program can try the call again later and it may succeed.
443 It is probably a good idea to delay for a few seconds before trying it
444 again, to allow time for other processes to release scarce resources.
445 Such shortages are usually fairly serious and affect the whole system,
446 so usually an interactive program should report the error to the user
447 and return to its command loop.
448 @end itemize
449 @end deftypevr
450
451 @comment errno.h
452 @comment BSD: Operation would block
453 @deftypevr Macro int EWOULDBLOCK
454 @comment errno EAGAIN @c DO NOT REMOVE
455 In the GNU C library, this is another name for @code{EAGAIN} (above).
456 The values are always the same, on every operating system.
457
458 C libraries in many older Unix systems have @code{EWOULDBLOCK} as a
459 separate error code.
460 @end deftypevr
461
462 @comment errno.h
463 @comment BSD: Operation now in progress
464 @deftypevr Macro int EINPROGRESS
465 @comment errno 36 @c DO NOT REMOVE
466 An operation that cannot complete immediately was initiated on an object
467 that has non-blocking mode selected.  Some functions that must always
468 block (such as @code{connect}; @pxref{Connecting}) never return
469 @code{EAGAIN}.  Instead, they return @code{EINPROGRESS} to indicate that
470 the operation has begun and will take some time.  Attempts to manipulate
471 the object before the call completes return @code{EALREADY}.  You can
472 use the @code{select} function to find out when the pending operation
473 has completed; @pxref{Waiting for I/O}.
474 @end deftypevr
475
476 @comment errno.h
477 @comment BSD: Operation already in progress
478 @deftypevr Macro int EALREADY
479 @comment errno 37 @c DO NOT REMOVE
480 An operation is already in progress on an object that has non-blocking
481 mode selected.
482 @end deftypevr
483
484 @comment errno.h
485 @comment BSD: Socket operation on non-socket
486 @deftypevr Macro int ENOTSOCK
487 @comment errno 38 @c DO NOT REMOVE
488 A file that isn't a socket was specified when a socket is required.
489 @end deftypevr
490
491 @comment errno.h
492 @comment BSD: Message too long
493 @deftypevr Macro int EMSGSIZE
494 @comment errno 40 @c DO NOT REMOVE
495 The size of a message sent on a socket was larger than the supported
496 maximum size.
497 @end deftypevr
498
499 @comment errno.h
500 @comment BSD: Protocol wrong type for socket
501 @deftypevr Macro int EPROTOTYPE
502 @comment errno 41 @c DO NOT REMOVE
503 The socket type does not support the requested communications protocol.
504 @end deftypevr
505
506 @comment errno.h
507 @comment BSD: Protocol not available
508 @deftypevr Macro int ENOPROTOOPT
509 @comment errno 42 @c DO NOT REMOVE
510 You specified a socket option that doesn't make sense for the
511 particular protocol being used by the socket.  @xref{Socket Options}.
512 @end deftypevr
513
514 @comment errno.h
515 @comment BSD: Protocol not supported
516 @deftypevr Macro int EPROTONOSUPPORT
517 @comment errno 43 @c DO NOT REMOVE
518 The socket domain does not support the requested communications protocol
519 (perhaps because the requested protocol is completely invalid).
520 @xref{Creating a Socket}.
521 @end deftypevr
522
523 @comment errno.h
524 @comment BSD: Socket type not supported
525 @deftypevr Macro int ESOCKTNOSUPPORT
526 @comment errno 44 @c DO NOT REMOVE
527 The socket type is not supported.
528 @end deftypevr
529
530 @comment errno.h
531 @comment BSD: Operation not supported
532 @deftypevr Macro int EOPNOTSUPP
533 @comment errno 45 @c DO NOT REMOVE
534 The operation you requested is not supported.  Some socket functions
535 don't make sense for all types of sockets, and others may not be
536 implemented for all communications protocols.  In the GNU system, this
537 error can happen for many calls when the object does not support the
538 particular operation; it is a generic indication that the server knows
539 nothing to do for that call.
540 @end deftypevr
541
542 @comment errno.h
543 @comment BSD: Protocol family not supported
544 @deftypevr Macro int EPFNOSUPPORT
545 @comment errno 46 @c DO NOT REMOVE
546 The socket communications protocol family you requested is not supported.
547 @end deftypevr
548
549 @comment errno.h
550 @comment BSD: Address family not supported by protocol
551 @deftypevr Macro int EAFNOSUPPORT
552 @comment errno 47 @c DO NOT REMOVE
553 The address family specified for a socket is not supported; it is
554 inconsistent with the protocol being used on the socket.  @xref{Sockets}.
555 @end deftypevr
556
557 @comment errno.h
558 @comment BSD: Address already in use
559 @deftypevr Macro int EADDRINUSE
560 @comment errno 48 @c DO NOT REMOVE
561 The requested socket address is already in use.  @xref{Socket Addresses}.
562 @end deftypevr
563
564 @comment errno.h
565 @comment BSD: Cannot assign requested address
566 @deftypevr Macro int EADDRNOTAVAIL
567 @comment errno 49 @c DO NOT REMOVE
568 The requested socket address is not available; for example, you tried
569 to give a socket a name that doesn't match the local host name.
570 @xref{Socket Addresses}.
571 @end deftypevr
572
573 @comment errno.h
574 @comment BSD: Network is down
575 @deftypevr Macro int ENETDOWN
576 @comment errno 50 @c DO NOT REMOVE
577 A socket operation failed because the network was down.
578 @end deftypevr
579
580 @comment errno.h
581 @comment BSD: Network is unreachable
582 @deftypevr Macro int ENETUNREACH
583 @comment errno 51 @c DO NOT REMOVE
584 A socket operation failed because the subnet containing the remote host
585 was unreachable.
586 @end deftypevr
587
588 @comment errno.h
589 @comment BSD: Network dropped connection on reset
590 @deftypevr Macro int ENETRESET
591 @comment errno 52 @c DO NOT REMOVE
592 A network connection was reset because the remote host crashed.
593 @end deftypevr
594
595 @comment errno.h
596 @comment BSD: Software caused connection abort
597 @deftypevr Macro int ECONNABORTED
598 @comment errno 53 @c DO NOT REMOVE
599 A network connection was aborted locally.
600 @end deftypevr
601
602 @comment errno.h
603 @comment BSD: Connection reset by peer
604 @deftypevr Macro int ECONNRESET
605 @comment errno 54 @c DO NOT REMOVE
606 A network connection was closed for reasons outside the control of the
607 local host, such as by the remote machine rebooting or an unrecoverable
608 protocol violation.
609 @end deftypevr
610
611 @comment errno.h
612 @comment BSD: No buffer space available
613 @deftypevr Macro int ENOBUFS
614 @comment errno 55 @c DO NOT REMOVE
615 The kernel's buffers for I/O operations are all in use.  In GNU, this
616 error is always synonymous with @code{ENOMEM}; you may get one or the
617 other from network operations.
618 @end deftypevr
619
620 @comment errno.h
621 @comment BSD: Transport endpoint is already connected
622 @deftypevr Macro int EISCONN
623 @comment errno 56 @c DO NOT REMOVE
624 You tried to connect a socket that is already connected.
625 @xref{Connecting}.
626 @end deftypevr
627
628 @comment errno.h
629 @comment BSD: Transport endpoint is not connected
630 @deftypevr Macro int ENOTCONN
631 @comment errno 57 @c DO NOT REMOVE
632 The socket is not connected to anything.  You get this error when you
633 try to transmit data over a socket, without first specifying a
634 destination for the data.  For a connectionless socket (for datagram
635 protocols, such as UDP), you get @code{EDESTADDRREQ} instead.
636 @end deftypevr
637
638 @comment errno.h
639 @comment BSD: Destination address required
640 @deftypevr Macro int EDESTADDRREQ
641 @comment errno 39 @c DO NOT REMOVE
642 No default destination address was set for the socket.  You get this
643 error when you try to transmit data over a connectionless socket,
644 without first specifying a destination for the data with @code{connect}.
645 @end deftypevr
646
647 @comment errno.h
648 @comment BSD: Cannot send after transport endpoint shutdown
649 @deftypevr Macro int ESHUTDOWN
650 @comment errno 58 @c DO NOT REMOVE
651 The socket has already been shut down.
652 @end deftypevr
653
654 @comment errno.h
655 @comment BSD: Too many references: cannot splice
656 @deftypevr Macro int ETOOMANYREFS
657 @comment errno 59 @c DO NOT REMOVE
658 ???
659 @end deftypevr
660
661 @comment errno.h
662 @comment BSD: Connection timed out
663 @deftypevr Macro int ETIMEDOUT
664 @comment errno 60 @c DO NOT REMOVE
665 A socket operation with a specified timeout received no response during
666 the timeout period.
667 @end deftypevr
668
669 @comment errno.h
670 @comment BSD: Connection refused
671 @deftypevr Macro int ECONNREFUSED
672 @comment errno 61 @c DO NOT REMOVE
673 A remote host refused to allow the network connection (typically because
674 it is not running the requested service).
675 @end deftypevr
676
677 @comment errno.h
678 @comment BSD: Too many levels of symbolic links
679 @deftypevr Macro int ELOOP
680 @comment errno 62 @c DO NOT REMOVE
681 Too many levels of symbolic links were encountered in looking up a file name.
682 This often indicates a cycle of symbolic links.
683 @end deftypevr
684
685 @comment errno.h
686 @comment POSIX.1: File name too long
687 @deftypevr Macro int ENAMETOOLONG
688 @comment errno 63 @c DO NOT REMOVE
689 Filename too long (longer than @code{PATH_MAX}; @pxref{Limits for
690 Files}) or host name too long (in @code{gethostname} or
691 @code{sethostname}; @pxref{Host Identification}).
692 @end deftypevr
693
694 @comment errno.h
695 @comment BSD: Host is down
696 @deftypevr Macro int EHOSTDOWN
697 @comment errno 64 @c DO NOT REMOVE
698 The remote host for a requested network connection is down.
699 @end deftypevr
700
701 @comment errno.h
702 @comment BSD: No route to host
703 @deftypevr Macro int EHOSTUNREACH
704 @comment errno 65 @c DO NOT REMOVE
705 The remote host for a requested network connection is not reachable.
706 @end deftypevr
707
708 @comment errno.h
709 @comment POSIX.1: Directory not empty
710 @deftypevr Macro int ENOTEMPTY
711 @comment errno 66 @c DO NOT REMOVE
712 Directory not empty, where an empty directory was expected.  Typically,
713 this error occurs when you are trying to delete a directory.
714 @end deftypevr
715
716 @comment errno.h
717 @comment BSD: Too many processes
718 @deftypevr Macro int EPROCLIM
719 @comment errno 67 @c DO NOT REMOVE
720 This means that the per-user limit on new process would be exceeded by
721 an attempted @code{fork}.  @xref{Limits on Resources}, for details on
722 the @code{RLIMIT_NPROC} limit.
723 @end deftypevr
724
725 @comment errno.h
726 @comment BSD: Too many users
727 @deftypevr Macro int EUSERS
728 @comment errno 68 @c DO NOT REMOVE
729 The file quota system is confused because there are too many users.
730 @c This can probably happen in a GNU system when using NFS.
731 @end deftypevr
732
733 @comment errno.h
734 @comment BSD: Disk quota exceeded
735 @deftypevr Macro int EDQUOT
736 @comment errno 69 @c DO NOT REMOVE
737 The user's disk quota was exceeded.
738 @end deftypevr
739
740 @comment errno.h
741 @comment BSD: Stale NFS file handle
742 @deftypevr Macro int ESTALE
743 @comment errno 70 @c DO NOT REMOVE
744 Stale NFS file handle.  This indicates an internal confusion in the NFS
745 system which is due to file system rearrangements on the server host.
746 Repairing this condition usually requires unmounting and remounting
747 the NFS file system on the local host.
748 @end deftypevr
749
750 @comment errno.h
751 @comment BSD: Object is remote
752 @deftypevr Macro int EREMOTE
753 @comment errno 71 @c DO NOT REMOVE
754 An attempt was made to NFS-mount a remote file system with a file name that
755 already specifies an NFS-mounted file.
756 (This is an error on some operating systems, but we expect it to work
757 properly on the GNU system, making this error code impossible.)
758 @end deftypevr
759
760 @comment errno.h
761 @comment BSD: RPC struct is bad
762 @deftypevr Macro int EBADRPC
763 @comment errno 72 @c DO NOT REMOVE
764 ???
765 @end deftypevr
766
767 @comment errno.h
768 @comment BSD: RPC version wrong
769 @deftypevr Macro int ERPCMISMATCH
770 @comment errno 73 @c DO NOT REMOVE
771 ???
772 @end deftypevr
773
774 @comment errno.h
775 @comment BSD: RPC program not available
776 @deftypevr Macro int EPROGUNAVAIL
777 @comment errno 74 @c DO NOT REMOVE
778 ???
779 @end deftypevr
780
781 @comment errno.h
782 @comment BSD: RPC program version wrong
783 @deftypevr Macro int EPROGMISMATCH
784 @comment errno 75 @c DO NOT REMOVE
785 ???
786 @end deftypevr
787
788 @comment errno.h
789 @comment BSD: RPC bad procedure for program
790 @deftypevr Macro int EPROCUNAVAIL
791 @comment errno 76 @c DO NOT REMOVE
792 ???
793 @end deftypevr
794
795 @comment errno.h
796 @comment POSIX.1: No locks available
797 @deftypevr Macro int ENOLCK
798 @comment errno 77 @c DO NOT REMOVE
799 No locks available.  This is used by the file locking facilities; see
800 @ref{File Locks}.  This error is never generated by the GNU system, but
801 it can result from an operation to an NFS server running another
802 operating system.
803 @end deftypevr
804
805 @comment errno.h
806 @comment BSD: Inappropriate file type or format
807 @deftypevr Macro int EFTYPE
808 @comment errno 79 @c DO NOT REMOVE
809 Inappropriate file type or format.  The file was the wrong type for the
810 operation, or a data file had the wrong format.
811
812 On some systems @code{chmod} returns this error if you try to set the
813 sticky bit on a non-directory file; @pxref{Setting Permissions}.
814 @end deftypevr
815
816 @comment errno.h
817 @comment BSD: Authentication error
818 @deftypevr Macro int EAUTH
819 @comment errno 80 @c DO NOT REMOVE
820 ???
821 @end deftypevr
822
823 @comment errno.h
824 @comment BSD: Need authenticator
825 @deftypevr Macro int ENEEDAUTH
826 @comment errno 81 @c DO NOT REMOVE
827 ???
828 @end deftypevr
829
830 @comment errno.h
831 @comment POSIX.1: Function not implemented
832 @deftypevr Macro int ENOSYS
833 @comment errno 78 @c DO NOT REMOVE
834 Function not implemented.  This indicates that the function called is
835 not implemented at all, either in the C library itself or in the
836 operating system.  When you get this error, you can be sure that this
837 particular function will always fail with @code{ENOSYS} unless you
838 install a new version of the C library or the operating system.
839 @end deftypevr
840
841 @comment errno.h
842 @comment POSIX.1: Not supported
843 @deftypevr Macro int ENOTSUP
844 @comment errno 118 @c DO NOT REMOVE
845 Not supported.  A function returns this error when certain parameter
846 values are valid, but the functionality they request is not available.
847 This can mean that the function does not implement a particular command
848 or option value or flag bit at all.  For functions that operate on some
849 object given in a parameter, such as a file descriptor or a port, it
850 might instead mean that only @emph{that specific object} (file
851 descriptor, port, etc.) is unable to support the other parameters given;
852 different file descriptors might support different ranges of parameter
853 values.
854
855 If the entire function is not available at all in the implementation,
856 it returns @code{ENOSYS} instead.
857 @end deftypevr
858
859 @comment errno.h
860 @comment ISO: Invalid or incomplete multibyte or wide character
861 @deftypevr Macro int EILSEQ
862 @comment errno 106 @c DO NOT REMOVE
863 While decoding a multibyte character the function came along an invalid
864 or an incomplete sequence of bytes or the given wide character is invalid.
865 @end deftypevr
866
867 @comment errno.h
868 @comment GNU: Inappropriate operation for background process
869 @deftypevr Macro int EBACKGROUND
870 @comment errno 100 @c DO NOT REMOVE
871 In the GNU system, servers supporting the @code{term} protocol return
872 this error for certain operations when the caller is not in the
873 foreground process group of the terminal.  Users do not usually see this
874 error because functions such as @code{read} and @code{write} translate
875 it into a @code{SIGTTIN} or @code{SIGTTOU} signal.  @xref{Job Control},
876 for information on process groups and these signals.
877 @end deftypevr
878
879 @comment errno.h
880 @comment GNU: Translator died
881 @deftypevr Macro int EDIED
882 @comment errno 101 @c DO NOT REMOVE
883 In the GNU system, opening a file returns this error when the file is
884 translated by a program and the translator program dies while starting
885 up, before it has connected to the file.
886 @end deftypevr
887
888 @comment errno.h
889 @comment GNU: ?
890 @deftypevr Macro int ED
891 @comment errno 102 @c DO NOT REMOVE
892 The experienced user will know what is wrong.
893 @c This error code is a joke.  Its perror text is part of the joke.
894 @c Don't change it.
895 @end deftypevr
896
897 @comment errno.h
898 @comment GNU: You really blew it this time
899 @deftypevr Macro int EGREGIOUS
900 @comment errno 103 @c DO NOT REMOVE
901 You did @strong{what}?
902 @end deftypevr
903
904 @comment errno.h
905 @comment GNU: Computer bought the farm
906 @deftypevr Macro int EIEIO
907 @comment errno 104 @c DO NOT REMOVE
908 Go home and have a glass of warm, dairy-fresh milk.
909 @end deftypevr
910
911 @comment errno.h
912 @comment GNU: Gratuitous error
913 @deftypevr Macro int EGRATUITOUS
914 @comment errno 105 @c DO NOT REMOVE
915 This error code has no purpose.
916 @end deftypevr
917
918 @comment errno.h
919 @comment XOPEN: Bad message
920 @deftypevr Macro int EBADMSG
921 @comment errno 107
922 @end deftypevr
923
924 @comment errno.h
925 @comment XOPEN: Identifier removed
926 @deftypevr Macro int EIDRM
927 @comment errno 108
928 @end deftypevr
929
930 @comment errno.h
931 @comment XOPEN: Multihop attempted
932 @deftypevr Macro int EMULTIHOP
933 @comment errno 109
934 @end deftypevr
935
936 @comment errno.h
937 @comment XOPEN: No data available
938 @deftypevr Macro int ENODATA
939 @comment errno 110
940 @end deftypevr
941
942 @comment errno.h
943 @comment XOPEN: Link has been severed
944 @deftypevr Macro int ENOLINK
945 @comment errno 111
946 @end deftypevr
947
948 @comment errno.h
949 @comment XOPEN: No message of desired type
950 @deftypevr Macro int ENOMSG
951 @comment errno 112
952 @end deftypevr
953
954 @comment errno.h
955 @comment XOPEN: Out of streams resources
956 @deftypevr Macro int ENOSR
957 @comment errno 113
958 @end deftypevr
959
960 @comment errno.h
961 @comment XOPEN: Device not a stream
962 @deftypevr Macro int ENOSTR
963 @comment errno 114
964 @end deftypevr
965
966 @comment errno.h
967 @comment XOPEN: Value too large for defined data type
968 @deftypevr Macro int EOVERFLOW
969 @comment errno 115
970 @end deftypevr
971
972 @comment errno.h
973 @comment XOPEN: Protocol error
974 @deftypevr Macro int EPROTO
975 @comment errno 116
976 @end deftypevr
977
978 @comment errno.h
979 @comment XOPEN: Timer expired
980 @deftypevr Macro int ETIME
981 @comment errno 117
982 @end deftypevr
983
984
985 @emph{The following error codes are defined by the Linux/i386 kernel.
986 They are not yet documented.}
987
988 @comment errno.h
989 @comment Linux???: Interrupted system call should be restarted
990 @deftypevr Macro int ERESTART
991 @comment errno ???/85
992 @end deftypevr
993
994 @comment errno.h
995 @comment Linux???: Channel number out of range
996 @deftypevr Macro int ECHRNG
997 @comment errno ???/44
998 @end deftypevr
999
1000 @comment errno.h
1001 @comment Obsolete: Level 2 not synchronized
1002 @deftypevr Macro int EL2NSYNC
1003 @comment errno ???/45
1004 @end deftypevr
1005
1006 @comment errno.h
1007 @comment Obsolete: Level 3 halted
1008 @deftypevr Macro int EL3HLT
1009 @comment errno ???/46
1010 @end deftypevr
1011
1012 @comment errno.h
1013 @comment Obsolete: Level 3 reset
1014 @deftypevr Macro int EL3RST
1015 @comment errno ???/47
1016 @end deftypevr
1017
1018 @comment errno.h
1019 @comment Linux???: Link number out of range
1020 @deftypevr Macro int ELNRNG
1021 @comment errno ???/48
1022 @end deftypevr
1023
1024 @comment errno.h
1025 @comment Linux???: Protocol driver not attached
1026 @deftypevr Macro int EUNATCH
1027 @comment errno ???/49
1028 @end deftypevr
1029
1030 @comment errno.h
1031 @comment Linux???: No CSI structure available
1032 @deftypevr Macro int ENOCSI
1033 @comment errno ???/50
1034 @end deftypevr
1035
1036 @comment errno.h
1037 @comment Obsolete: Level 2 halted
1038 @deftypevr Macro int EL2HLT
1039 @comment errno ???/51
1040 @end deftypevr
1041
1042 @comment errno.h
1043 @comment Linux???: Invalid exchange
1044 @deftypevr Macro int EBADE
1045 @comment errno ???/52
1046 @end deftypevr
1047
1048 @comment errno.h
1049 @comment Linux???: Invalid request descriptor
1050 @deftypevr Macro int EBADR
1051 @comment errno ???/53
1052 @end deftypevr
1053
1054 @comment errno.h
1055 @comment Linux???: Exchange full
1056 @deftypevr Macro int EXFULL
1057 @comment errno ???/54
1058 @end deftypevr
1059
1060 @comment errno.h
1061 @comment Linux???: No anode
1062 @deftypevr Macro int ENOANO
1063 @comment errno ???/55
1064 @end deftypevr
1065
1066 @comment errno.h
1067 @comment Linux???: Invalid request code
1068 @deftypevr Macro int EBADRQC
1069 @comment errno ???/56
1070 @end deftypevr
1071
1072 @comment errno.h
1073 @comment Linux???: Invalid slot
1074 @deftypevr Macro int EBADSLT
1075 @comment errno ???/57
1076 @end deftypevr
1077
1078 @comment errno.h
1079 @comment Linux???: File locking deadlock error
1080 @deftypevr Macro int EDEADLOCK
1081 @comment errno ???/58
1082 @end deftypevr
1083
1084 @comment errno.h
1085 @comment Linux???: Bad font file format
1086 @deftypevr Macro int EBFONT
1087 @comment errno ???/59
1088 @end deftypevr
1089
1090 @comment errno.h
1091 @comment Linux???: Machine is not on the network
1092 @deftypevr Macro int ENONET
1093 @comment errno ???/64
1094 @end deftypevr
1095
1096 @comment errno.h
1097 @comment Linux???: Package not installed
1098 @deftypevr Macro int ENOPKG
1099 @comment errno ???/65
1100 @end deftypevr
1101
1102 @comment errno.h
1103 @comment Linux???: Advertise error
1104 @deftypevr Macro int EADV
1105 @comment errno ???/68
1106 @end deftypevr
1107
1108 @comment errno.h
1109 @comment Linux???: Srmount error
1110 @deftypevr Macro int ESRMNT
1111 @comment errno ???/69
1112 @end deftypevr
1113
1114 @comment errno.h
1115 @comment Linux???: Communication error on send
1116 @deftypevr Macro int ECOMM
1117 @comment errno ???/70
1118 @end deftypevr
1119
1120 @comment errno.h
1121 @comment Linux???: RFS specific error
1122 @deftypevr Macro int EDOTDOT
1123 @comment errno ???/73
1124 @end deftypevr
1125
1126 @comment errno.h
1127 @comment Linux???: Name not unique on network
1128 @deftypevr Macro int ENOTUNIQ
1129 @comment errno ???/76
1130 @end deftypevr
1131
1132 @comment errno.h
1133 @comment Linux???: File descriptor in bad state
1134 @deftypevr Macro int EBADFD
1135 @comment errno ???/77
1136 @end deftypevr
1137
1138 @comment errno.h
1139 @comment Linux???: Remote address changed
1140 @deftypevr Macro int EREMCHG
1141 @comment errno ???/78
1142 @end deftypevr
1143
1144 @comment errno.h
1145 @comment Linux???: Can not access a needed shared library
1146 @deftypevr Macro int ELIBACC
1147 @comment errno ???/79
1148 @end deftypevr
1149
1150 @comment errno.h
1151 @comment Linux???: Accessing a corrupted shared library
1152 @deftypevr Macro int ELIBBAD
1153 @comment errno ???/80
1154 @end deftypevr
1155
1156 @comment errno.h
1157 @comment Linux???: .lib section in a.out corrupted
1158 @deftypevr Macro int ELIBSCN
1159 @comment errno ???/81
1160 @end deftypevr
1161
1162 @comment errno.h
1163 @comment Linux???: Attempting to link in too many shared libraries
1164 @deftypevr Macro int ELIBMAX
1165 @comment errno ???/82
1166 @end deftypevr
1167
1168 @comment errno.h
1169 @comment Linux???: Cannot exec a shared library directly
1170 @deftypevr Macro int ELIBEXEC
1171 @comment errno ???/83
1172 @end deftypevr
1173
1174 @comment errno.h
1175 @comment Linux???: Streams pipe error
1176 @deftypevr Macro int ESTRPIPE
1177 @comment errno ???/86
1178 @end deftypevr
1179
1180 @comment errno.h
1181 @comment Linux???: Structure needs cleaning
1182 @deftypevr Macro int EUCLEAN
1183 @comment errno ???/117
1184 @end deftypevr
1185
1186 @comment errno.h
1187 @comment Linux???: Not a XENIX named type file
1188 @deftypevr Macro int ENOTNAM
1189 @comment errno ???/118
1190 @end deftypevr
1191
1192 @comment errno.h
1193 @comment Linux???: No XENIX semaphores available
1194 @deftypevr Macro int ENAVAIL
1195 @comment errno ???/119
1196 @end deftypevr
1197
1198 @comment errno.h
1199 @comment Linux???: Is a named type file
1200 @deftypevr Macro int EISNAM
1201 @comment errno ???/120
1202 @end deftypevr
1203
1204 @comment errno.h
1205 @comment Linux???: Remote I/O error
1206 @deftypevr Macro int EREMOTEIO
1207 @comment errno ???/121
1208 @end deftypevr
1209
1210 @comment errno.h
1211 @comment Linux???: No medium found
1212 @deftypevr Macro int ENOMEDIUM
1213 @comment errno ???/???
1214 @end deftypevr
1215
1216 @comment errno.h
1217 @comment Linux???: Wrong medium type
1218 @deftypevr Macro int EMEDIUMTYPE
1219 @comment errno ???/???
1220 @end deftypevr
1221
1222 @node Error Messages,  , Error Codes, Error Reporting
1223 @section Error Messages
1224
1225 The library has functions and variables designed to make it easy for
1226 your program to report informative error messages in the customary
1227 format about the failure of a library call.  The functions
1228 @code{strerror} and @code{perror} give you the standard error message
1229 for a given error code; the variable
1230 @w{@code{program_invocation_short_name}} gives you convenient access to the
1231 name of the program that encountered the error.
1232
1233 @comment string.h
1234 @comment ISO
1235 @deftypefun {char *} strerror (int @var{errnum})
1236 The @code{strerror} function maps the error code (@pxref{Checking for
1237 Errors}) specified by the @var{errnum} argument to a descriptive error
1238 message string.  The return value is a pointer to this string.
1239
1240 The value @var{errnum} normally comes from the variable @code{errno}.
1241
1242 You should not modify the string returned by @code{strerror}.  Also, if
1243 you make subsequent calls to @code{strerror}, the string might be
1244 overwritten.  (But it's guaranteed that no library function ever calls
1245 @code{strerror} behind your back.)
1246
1247 The function @code{strerror} is declared in @file{string.h}.
1248 @end deftypefun
1249
1250 @comment string.h
1251 @comment GNU
1252 @deftypefun {char *} strerror_r (int @var{errnum}, char *@var{buf}, size_t @var{n})
1253 The @code{strerror_r} function works like @code{strerror} but instead of
1254 returning the error message in a statically allocated buffer shared by
1255 all threads in the process, it returns a private copy for the
1256 thread. This might be either some permanent global data or a message
1257 string in the user supplied buffer starting at @var{buf} with the
1258 length of @var{n} bytes.
1259
1260 At most @var{n} characters are written (including the NUL byte) so it is
1261 up to the user to select the buffer large enough.
1262
1263 This function should always be used in multi-threaded programs since
1264 there is no way to guarantee the string returned by @code{strerror}
1265 really belongs to the last call of the current thread.
1266
1267 This function @code{strerror_r} is a GNU extension and it is declared in
1268 @file{string.h}.
1269 @end deftypefun
1270
1271 @comment stdio.h
1272 @comment ISO
1273 @deftypefun void perror (const char *@var{message})
1274 This function prints an error message to the stream @code{stderr};
1275 see @ref{Standard Streams}.  The orientation of @code{stderr} is not
1276 changed.
1277
1278 If you call @code{perror} with a @var{message} that is either a null
1279 pointer or an empty string, @code{perror} just prints the error message
1280 corresponding to @code{errno}, adding a trailing newline.
1281
1282 If you supply a non-null @var{message} argument, then @code{perror}
1283 prefixes its output with this string.  It adds a colon and a space
1284 character to separate the @var{message} from the error string corresponding
1285 to @code{errno}.
1286
1287 The function @code{perror} is declared in @file{stdio.h}.
1288 @end deftypefun
1289
1290 @code{strerror} and @code{perror} produce the exact same message for any
1291 given error code; the precise text varies from system to system.  On the
1292 GNU system, the messages are fairly short; there are no multi-line
1293 messages or embedded newlines.  Each error message begins with a capital
1294 letter and does not include any terminating punctuation.
1295
1296 @strong{Compatibility Note:} The @code{strerror} function was introduced
1297 in @w{ISO C89}.  Many older C systems do not support this function yet.
1298
1299 @cindex program name
1300 @cindex name of running program
1301 Many programs that don't read input from the terminal are designed to
1302 exit if any system call fails.  By convention, the error message from
1303 such a program should start with the program's name, sans directories.
1304 You can find that name in the variable
1305 @code{program_invocation_short_name}; the full file name is stored the
1306 variable @code{program_invocation_name}.
1307
1308 @comment errno.h
1309 @comment GNU
1310 @deftypevar {char *} program_invocation_name
1311 This variable's value is the name that was used to invoke the program
1312 running in the current process.  It is the same as @code{argv[0]}.  Note
1313 that this is not necessarily a useful file name; often it contains no
1314 directory names.  @xref{Program Arguments}.
1315 @end deftypevar
1316
1317 @comment errno.h
1318 @comment GNU
1319 @deftypevar {char *} program_invocation_short_name
1320 This variable's value is the name that was used to invoke the program
1321 running in the current process, with directory names removed.  (That is
1322 to say, it is the same as @code{program_invocation_name} minus
1323 everything up to the last slash, if any.)
1324 @end deftypevar
1325
1326 The library initialization code sets up both of these variables before
1327 calling @code{main}.
1328
1329 @strong{Portability Note:} These two variables are GNU extensions.  If
1330 you want your program to work with non-GNU libraries, you must save the
1331 value of @code{argv[0]} in @code{main}, and then strip off the directory
1332 names yourself.  We added these extensions to make it possible to write
1333 self-contained error-reporting subroutines that require no explicit
1334 cooperation from @code{main}.
1335
1336 Here is an example showing how to handle failure to open a file
1337 correctly.  The function @code{open_sesame} tries to open the named file
1338 for reading and returns a stream if successful.  The @code{fopen}
1339 library function returns a null pointer if it couldn't open the file for
1340 some reason.  In that situation, @code{open_sesame} constructs an
1341 appropriate error message using the @code{strerror} function, and
1342 terminates the program.  If we were going to make some other library
1343 calls before passing the error code to @code{strerror}, we'd have to
1344 save it in a local variable instead, because those other library
1345 functions might overwrite @code{errno} in the meantime.
1346
1347 @smallexample
1348 #include <errno.h>
1349 #include <stdio.h>
1350 #include <stdlib.h>
1351 #include <string.h>
1352
1353 FILE *
1354 open_sesame (char *name)
1355 @{
1356   FILE *stream;
1357
1358   errno = 0;
1359   stream = fopen (name, "r");
1360   if (stream == NULL)
1361     @{
1362       fprintf (stderr, "%s: Couldn't open file %s; %s\n",
1363                program_invocation_short_name, name, strerror (errno));
1364       exit (EXIT_FAILURE);
1365     @}
1366   else
1367     return stream;
1368 @}
1369 @end smallexample
1370
1371 Using @code{perror} has the advantage that the function is portable and
1372 available on all systems implementing @w{ISO C}.  But often the text
1373 @code{perror} generates is not what is wanted and there is no way to
1374 extend or change what @code{perror} does.  The GNU coding standard, for
1375 instance, requires error messages to be preceded by the program name and
1376 programs which read some input files should should provide information
1377 about the input file name and the line number in case an error is
1378 encountered while reading the file.  For these occasions there are two
1379 functions available which are widely used throughout the GNU project.
1380 These functions are declared in @file{error.h}.
1381
1382 @comment error.h
1383 @comment GNU
1384 @deftypefun void error (int @var{status}, int @var{errnum}, const char *@var{format}, @dots{})
1385 The @code{error} function can be used to report general problems during
1386 program execution.  The @var{format} argument is a format string just
1387 like those given to the @code{printf} family of functions.  The
1388 arguments required for the format can follow the @var{format} parameter.
1389 Just like @code{perror}, @code{error} also can report an error code in
1390 textual form.  But unlike @code{perror} the error value is explicitly
1391 passed to the function in the @var{errnum} parameter.  This elimintates
1392 the problem mentioned above that the error reporting function must be
1393 called immediately after the function causing the error since otherwise
1394 @code{errno} might have a different value.
1395
1396 The @code{error} prints first the program name.  If the application
1397 defined a global variable @code{error_print_progname} and points it to a
1398 function this function will be called to print the program name.
1399 Otherwise the string from the global variable @code{program_name} is
1400 used.  The program name is followed by a colon and a space which in turn
1401 is followed by the output produced by the format string.  If the
1402 @var{errnum} parameter is non-zero the format string output is followed
1403 by a colon and a space, followed by the error message for the error code
1404 @var{errnum}.  In any case is the output terminated with a newline.
1405
1406 The output is directed to the @code{stderr} stream.  If the
1407 @code{stderr} wasn't oriented before the call it will be narrow-oriented
1408 afterwards.
1409
1410 The function will return unless the @var{status} parameter has a
1411 non-zero value.  In this case the function will call @code{exit} with
1412 the @var{status} value for its parameter and therefore never return.  If
1413 @code{error} returns the global variable @code{error_message_count} is
1414 incremented by one to keep track of the number of errors reported.
1415 @end deftypefun
1416
1417 @comment error.h
1418 @comment GNU
1419 @deftypefun void error_at_line (int @var{status}, int @var{errnum}, const char *@var{fname}, unsigned int @var{lineno}, const char *@var{format}, @dots{})
1420
1421 The @code{error_at_line} function is very similar to the @code{error}
1422 function.  The only difference are the additional parameters @var{fname}
1423 and @var{lineno}.  The handling of the other parameters is identical to
1424 that of @code{error} except that between the program name and the string
1425 generated by the format string additional text is inserted.
1426
1427 Directly following the program name a colon, followed by the file name
1428 pointer to by @var{fname}, another colon, and a value of @var{lineno} is
1429 printed.
1430
1431 This additional output of course is meant to be used to locate an error
1432 in an input file (like a programming language source code file etc).
1433
1434 If the global variable @code{error_one_per_line} is set to a non-zero
1435 value @code{error_at_line} will avoid printing consecutive messages for
1436 the same file anem line.  Repetition which are not directly following
1437 each other are not caught.
1438
1439 Just like @code{error} this function only returned if @var{status} is
1440 zero.  Otherwise @code{exit} is called with the non-zero value.  If
1441 @code{error} returns the global variable @code{error_message_count} is
1442 incremented by one to keep track of the number of errors reported.
1443 @end deftypefun
1444
1445 As mentioned above the @code{error} and @code{error_at_line} functions
1446 can be customized by defining a variable named
1447 @code{error_print_progname}.
1448
1449 @comment error.h
1450 @comment GNU
1451 @deftypevar {void (*} error_print_progname ) (void)
1452 If the @code{error_print_progname} variable is defined to a non-zero
1453 value the function pointed to is called by @code{error} or
1454 @code{error_at_line}.  It is expected to print the program name or do
1455 something similarly useful.
1456
1457 The function is expected to be print to the @code{stderr} stream and
1458 must be able to handle whatever orientation the stream has.
1459
1460 The variable is global and shared by all threads.
1461 @end deftypevar
1462
1463 @comment error.h
1464 @comment GNU
1465 @deftypevar {unsigned int} error_message_count
1466 The @code{error_message_count} variable is incremented whenever one of
1467 the functions @code{error} or @code{error_at_line} returns.  The
1468 variable is global and shared by all threads.
1469 @end deftypevar
1470
1471 @comment error.h
1472 @comment GNU
1473 @deftypevar int error_one_per_line
1474 The @code{error_one_per_line} variable influences only
1475 @code{error_at_line}.  Normally the @code{error_at_line} function
1476 creates output for every invocation.  If @code{error_one_per_line} is
1477 set to a non-zero value @code{error_at_line} keeps track of the last
1478 file name and line number for which an error was reported and avoid
1479 directly following messages for the same file and line.  This variable
1480 is global and shared by all threads.
1481 @end deftypevar
1482
1483 @noindent
1484 A program which read some input file and reports errors in it could look
1485 like this:
1486
1487 @smallexample
1488 @{
1489   char *line = NULL;
1490   size_t len = 0;
1491   unsigned int lineno = 0;
1492
1493   error_message_count = 0;
1494   while (! feof_unlocked (fp))
1495     @{
1496       ssize_t n = getline (&line, &len, fp);
1497       if (n <= 0)
1498         /* @r{End of file or error.}  */
1499         break;
1500       ++lineno;
1501
1502       /* @r{Process the line.}  */
1503       @dots{}
1504
1505       if (@r{Detect error in line})
1506         error_at_line (0, errval, filename, lineno,
1507                        "some error text %s", some_variable);
1508     @}
1509
1510   if (error_message_count != 0)
1511     error (EXIT_FAILURE, 0, "%u errors found", error_message_count);
1512 @}
1513 @end smallexample
1514
1515 @code{error} and @code{error_at_line} are clearly the functions of
1516 choice and enable the programmer to write applications which follow the
1517 GNU coding standard.  The GNU libc additionally contains functions which
1518 are used in BSD for the same purpose.  These functions are declared in
1519 @file{err.h}.  It is generally advised to not use these functions.  They
1520 are included only for compatibility.
1521
1522 @comment err.h
1523 @comment BSD
1524 @deftypefun void warn (const char *@var{format}, @dots{})
1525 The @code{warn} function is roughly equivalent to a call like
1526 @smallexample
1527   error (0, errno, format, @r{the parameters})
1528 @end smallexample
1529 @noindent
1530 except that the global variables @code{error} respects and modifies
1531 are not used.
1532 @end deftypefun
1533
1534 @comment err.h
1535 @comment BSD
1536 @deftypefun void vwarn (const char *@var{format}, va_list)
1537 The @code{vwarn} function is just like @code{warn} except that the
1538 parameters for the handling of the format string @var{format} are passed
1539 in as an value of type @code{va_list}.
1540 @end deftypefun
1541
1542 @comment err.h
1543 @comment BSD
1544 @deftypefun void warnx (const char *@var{format}, @dots{})
1545 The @code{warnx} function is roughly equivalent to a call like
1546 @smallexample
1547   error (0, 0, format, @r{the parameters})
1548 @end smallexample
1549 @noindent
1550 except that the global variables @code{error} respects and modifies
1551 are not used.  The difference to @code{warn} is that no error number
1552 string is printed.
1553 @end deftypefun
1554
1555 @comment err.h
1556 @comment BSD
1557 @deftypefun void vwarnx (const char *@var{format}, va_list)
1558 The @code{vwarnx} function is just like @code{warnx} except that the
1559 parameters for the handling of the format string @var{format} are passed
1560 in as an value of type @code{va_list}.
1561 @end deftypefun
1562
1563 @comment err.h
1564 @comment BSD
1565 @deftypefun void err (int @var{status}, const char *@var{format}, @dots{})
1566 The @code{err} function is roughly equivalent to a call like
1567 @smallexample
1568   error (status, errno, format, @r{the parameters})
1569 @end smallexample
1570 @noindent
1571 except that the global variables @code{error} respects and modifies
1572 are not used and that the program is exited even if @var{status} is zero.
1573 @end deftypefun
1574
1575 @comment err.h
1576 @comment BSD
1577 @deftypefun void verr (int @var{status}, const char *@var{format}, va_list)
1578 The @code{verr} function is just like @code{err} except that the
1579 parameters for the handling of the format string @var{format} are passed
1580 in as an value of type @code{va_list}.
1581 @end deftypefun
1582
1583 @comment err.h
1584 @comment BSD
1585 @deftypefun void errx (int @var{status}, const char *@var{format}, @dots{})
1586 The @code{errx} function is roughly equivalent to a call like
1587 @smallexample
1588   error (status, 0, format, @r{the parameters})
1589 @end smallexample
1590 @noindent
1591 except that the global variables @code{error} respects and modifies
1592 are not used and that the program is exited even if @var{status}
1593 is zero.  The difference to @code{err} is that no error number
1594 string is printed.
1595 @end deftypefun
1596
1597 @comment err.h
1598 @comment BSD
1599 @deftypefun void verrx (int @var{status}, const char *@var{format}, va_list)
1600 The @code{verrx} function is just like @code{errx} except that the
1601 parameters for the handling of the format string @var{format} are passed
1602 in as an value of type @code{va_list}.
1603 @end deftypefun