(Tools for Compilation): Grammar fixes.
[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 @comment errno.h
985 @comment POSIX.1: Operation canceled
986 @deftypevr Macro int ECANCELED
987 @comment errno 118
988 Operation canceled; an asynchronous operation was canceled before it
989 completed.  @xref{Asynchronous I/O}.  When you call @code{aio_cancel},
990 the normal result is for the operations affected to complete with this
991 error; @pxref{Cancel AIO Operations}.
992 @end deftypevr
993
994
995 @emph{The following error codes are defined by the Linux/i386 kernel.
996 They are not yet documented.}
997
998 @comment errno.h
999 @comment Linux???: Interrupted system call should be restarted
1000 @deftypevr Macro int ERESTART
1001 @comment errno ???/85
1002 @end deftypevr
1003
1004 @comment errno.h
1005 @comment Linux???: Channel number out of range
1006 @deftypevr Macro int ECHRNG
1007 @comment errno ???/44
1008 @end deftypevr
1009
1010 @comment errno.h
1011 @comment Obsolete: Level 2 not synchronized
1012 @deftypevr Macro int EL2NSYNC
1013 @comment errno ???/45
1014 @end deftypevr
1015
1016 @comment errno.h
1017 @comment Obsolete: Level 3 halted
1018 @deftypevr Macro int EL3HLT
1019 @comment errno ???/46
1020 @end deftypevr
1021
1022 @comment errno.h
1023 @comment Obsolete: Level 3 reset
1024 @deftypevr Macro int EL3RST
1025 @comment errno ???/47
1026 @end deftypevr
1027
1028 @comment errno.h
1029 @comment Linux???: Link number out of range
1030 @deftypevr Macro int ELNRNG
1031 @comment errno ???/48
1032 @end deftypevr
1033
1034 @comment errno.h
1035 @comment Linux???: Protocol driver not attached
1036 @deftypevr Macro int EUNATCH
1037 @comment errno ???/49
1038 @end deftypevr
1039
1040 @comment errno.h
1041 @comment Linux???: No CSI structure available
1042 @deftypevr Macro int ENOCSI
1043 @comment errno ???/50
1044 @end deftypevr
1045
1046 @comment errno.h
1047 @comment Obsolete: Level 2 halted
1048 @deftypevr Macro int EL2HLT
1049 @comment errno ???/51
1050 @end deftypevr
1051
1052 @comment errno.h
1053 @comment Linux???: Invalid exchange
1054 @deftypevr Macro int EBADE
1055 @comment errno ???/52
1056 @end deftypevr
1057
1058 @comment errno.h
1059 @comment Linux???: Invalid request descriptor
1060 @deftypevr Macro int EBADR
1061 @comment errno ???/53
1062 @end deftypevr
1063
1064 @comment errno.h
1065 @comment Linux???: Exchange full
1066 @deftypevr Macro int EXFULL
1067 @comment errno ???/54
1068 @end deftypevr
1069
1070 @comment errno.h
1071 @comment Linux???: No anode
1072 @deftypevr Macro int ENOANO
1073 @comment errno ???/55
1074 @end deftypevr
1075
1076 @comment errno.h
1077 @comment Linux???: Invalid request code
1078 @deftypevr Macro int EBADRQC
1079 @comment errno ???/56
1080 @end deftypevr
1081
1082 @comment errno.h
1083 @comment Linux???: Invalid slot
1084 @deftypevr Macro int EBADSLT
1085 @comment errno ???/57
1086 @end deftypevr
1087
1088 @comment errno.h
1089 @comment Linux???: File locking deadlock error
1090 @deftypevr Macro int EDEADLOCK
1091 @comment errno ???/58
1092 @end deftypevr
1093
1094 @comment errno.h
1095 @comment Linux???: Bad font file format
1096 @deftypevr Macro int EBFONT
1097 @comment errno ???/59
1098 @end deftypevr
1099
1100 @comment errno.h
1101 @comment Linux???: Machine is not on the network
1102 @deftypevr Macro int ENONET
1103 @comment errno ???/64
1104 @end deftypevr
1105
1106 @comment errno.h
1107 @comment Linux???: Package not installed
1108 @deftypevr Macro int ENOPKG
1109 @comment errno ???/65
1110 @end deftypevr
1111
1112 @comment errno.h
1113 @comment Linux???: Advertise error
1114 @deftypevr Macro int EADV
1115 @comment errno ???/68
1116 @end deftypevr
1117
1118 @comment errno.h
1119 @comment Linux???: Srmount error
1120 @deftypevr Macro int ESRMNT
1121 @comment errno ???/69
1122 @end deftypevr
1123
1124 @comment errno.h
1125 @comment Linux???: Communication error on send
1126 @deftypevr Macro int ECOMM
1127 @comment errno ???/70
1128 @end deftypevr
1129
1130 @comment errno.h
1131 @comment Linux???: RFS specific error
1132 @deftypevr Macro int EDOTDOT
1133 @comment errno ???/73
1134 @end deftypevr
1135
1136 @comment errno.h
1137 @comment Linux???: Name not unique on network
1138 @deftypevr Macro int ENOTUNIQ
1139 @comment errno ???/76
1140 @end deftypevr
1141
1142 @comment errno.h
1143 @comment Linux???: File descriptor in bad state
1144 @deftypevr Macro int EBADFD
1145 @comment errno ???/77
1146 @end deftypevr
1147
1148 @comment errno.h
1149 @comment Linux???: Remote address changed
1150 @deftypevr Macro int EREMCHG
1151 @comment errno ???/78
1152 @end deftypevr
1153
1154 @comment errno.h
1155 @comment Linux???: Can not access a needed shared library
1156 @deftypevr Macro int ELIBACC
1157 @comment errno ???/79
1158 @end deftypevr
1159
1160 @comment errno.h
1161 @comment Linux???: Accessing a corrupted shared library
1162 @deftypevr Macro int ELIBBAD
1163 @comment errno ???/80
1164 @end deftypevr
1165
1166 @comment errno.h
1167 @comment Linux???: .lib section in a.out corrupted
1168 @deftypevr Macro int ELIBSCN
1169 @comment errno ???/81
1170 @end deftypevr
1171
1172 @comment errno.h
1173 @comment Linux???: Attempting to link in too many shared libraries
1174 @deftypevr Macro int ELIBMAX
1175 @comment errno ???/82
1176 @end deftypevr
1177
1178 @comment errno.h
1179 @comment Linux???: Cannot exec a shared library directly
1180 @deftypevr Macro int ELIBEXEC
1181 @comment errno ???/83
1182 @end deftypevr
1183
1184 @comment errno.h
1185 @comment Linux???: Streams pipe error
1186 @deftypevr Macro int ESTRPIPE
1187 @comment errno ???/86
1188 @end deftypevr
1189
1190 @comment errno.h
1191 @comment Linux???: Structure needs cleaning
1192 @deftypevr Macro int EUCLEAN
1193 @comment errno ???/117
1194 @end deftypevr
1195
1196 @comment errno.h
1197 @comment Linux???: Not a XENIX named type file
1198 @deftypevr Macro int ENOTNAM
1199 @comment errno ???/118
1200 @end deftypevr
1201
1202 @comment errno.h
1203 @comment Linux???: No XENIX semaphores available
1204 @deftypevr Macro int ENAVAIL
1205 @comment errno ???/119
1206 @end deftypevr
1207
1208 @comment errno.h
1209 @comment Linux???: Is a named type file
1210 @deftypevr Macro int EISNAM
1211 @comment errno ???/120
1212 @end deftypevr
1213
1214 @comment errno.h
1215 @comment Linux???: Remote I/O error
1216 @deftypevr Macro int EREMOTEIO
1217 @comment errno ???/121
1218 @end deftypevr
1219
1220 @comment errno.h
1221 @comment Linux???: No medium found
1222 @deftypevr Macro int ENOMEDIUM
1223 @comment errno ???/???
1224 @end deftypevr
1225
1226 @comment errno.h
1227 @comment Linux???: Wrong medium type
1228 @deftypevr Macro int EMEDIUMTYPE
1229 @comment errno ???/???
1230 @end deftypevr
1231
1232 @node Error Messages,  , Error Codes, Error Reporting
1233 @section Error Messages
1234
1235 The library has functions and variables designed to make it easy for
1236 your program to report informative error messages in the customary
1237 format about the failure of a library call.  The functions
1238 @code{strerror} and @code{perror} give you the standard error message
1239 for a given error code; the variable
1240 @w{@code{program_invocation_short_name}} gives you convenient access to the
1241 name of the program that encountered the error.
1242
1243 @comment string.h
1244 @comment ISO
1245 @deftypefun {char *} strerror (int @var{errnum})
1246 The @code{strerror} function maps the error code (@pxref{Checking for
1247 Errors}) specified by the @var{errnum} argument to a descriptive error
1248 message string.  The return value is a pointer to this string.
1249
1250 The value @var{errnum} normally comes from the variable @code{errno}.
1251
1252 You should not modify the string returned by @code{strerror}.  Also, if
1253 you make subsequent calls to @code{strerror}, the string might be
1254 overwritten.  (But it's guaranteed that no library function ever calls
1255 @code{strerror} behind your back.)
1256
1257 The function @code{strerror} is declared in @file{string.h}.
1258 @end deftypefun
1259
1260 @comment string.h
1261 @comment GNU
1262 @deftypefun {char *} strerror_r (int @var{errnum}, char *@var{buf}, size_t @var{n})
1263 The @code{strerror_r} function works like @code{strerror} but instead of
1264 returning the error message in a statically allocated buffer shared by
1265 all threads in the process, it returns a private copy for the
1266 thread. This might be either some permanent global data or a message
1267 string in the user supplied buffer starting at @var{buf} with the
1268 length of @var{n} bytes.
1269
1270 At most @var{n} characters are written (including the NUL byte) so it is
1271 up to the user to select the buffer large enough.
1272
1273 This function should always be used in multi-threaded programs since
1274 there is no way to guarantee the string returned by @code{strerror}
1275 really belongs to the last call of the current thread.
1276
1277 This function @code{strerror_r} is a GNU extension and it is declared in
1278 @file{string.h}.
1279 @end deftypefun
1280
1281 @comment stdio.h
1282 @comment ISO
1283 @deftypefun void perror (const char *@var{message})
1284 This function prints an error message to the stream @code{stderr};
1285 see @ref{Standard Streams}.  The orientation of @code{stderr} is not
1286 changed.
1287
1288 If you call @code{perror} with a @var{message} that is either a null
1289 pointer or an empty string, @code{perror} just prints the error message
1290 corresponding to @code{errno}, adding a trailing newline.
1291
1292 If you supply a non-null @var{message} argument, then @code{perror}
1293 prefixes its output with this string.  It adds a colon and a space
1294 character to separate the @var{message} from the error string corresponding
1295 to @code{errno}.
1296
1297 The function @code{perror} is declared in @file{stdio.h}.
1298 @end deftypefun
1299
1300 @code{strerror} and @code{perror} produce the exact same message for any
1301 given error code; the precise text varies from system to system.  On the
1302 GNU system, the messages are fairly short; there are no multi-line
1303 messages or embedded newlines.  Each error message begins with a capital
1304 letter and does not include any terminating punctuation.
1305
1306 @strong{Compatibility Note:} The @code{strerror} function was introduced
1307 in @w{ISO C89}.  Many older C systems do not support this function yet.
1308
1309 @cindex program name
1310 @cindex name of running program
1311 Many programs that don't read input from the terminal are designed to
1312 exit if any system call fails.  By convention, the error message from
1313 such a program should start with the program's name, sans directories.
1314 You can find that name in the variable
1315 @code{program_invocation_short_name}; the full file name is stored the
1316 variable @code{program_invocation_name}.
1317
1318 @comment errno.h
1319 @comment GNU
1320 @deftypevar {char *} program_invocation_name
1321 This variable's value is the name that was used to invoke the program
1322 running in the current process.  It is the same as @code{argv[0]}.  Note
1323 that this is not necessarily a useful file name; often it contains no
1324 directory names.  @xref{Program Arguments}.
1325 @end deftypevar
1326
1327 @comment errno.h
1328 @comment GNU
1329 @deftypevar {char *} program_invocation_short_name
1330 This variable's value is the name that was used to invoke the program
1331 running in the current process, with directory names removed.  (That is
1332 to say, it is the same as @code{program_invocation_name} minus
1333 everything up to the last slash, if any.)
1334 @end deftypevar
1335
1336 The library initialization code sets up both of these variables before
1337 calling @code{main}.
1338
1339 @strong{Portability Note:} These two variables are GNU extensions.  If
1340 you want your program to work with non-GNU libraries, you must save the
1341 value of @code{argv[0]} in @code{main}, and then strip off the directory
1342 names yourself.  We added these extensions to make it possible to write
1343 self-contained error-reporting subroutines that require no explicit
1344 cooperation from @code{main}.
1345
1346 Here is an example showing how to handle failure to open a file
1347 correctly.  The function @code{open_sesame} tries to open the named file
1348 for reading and returns a stream if successful.  The @code{fopen}
1349 library function returns a null pointer if it couldn't open the file for
1350 some reason.  In that situation, @code{open_sesame} constructs an
1351 appropriate error message using the @code{strerror} function, and
1352 terminates the program.  If we were going to make some other library
1353 calls before passing the error code to @code{strerror}, we'd have to
1354 save it in a local variable instead, because those other library
1355 functions might overwrite @code{errno} in the meantime.
1356
1357 @smallexample
1358 #include <errno.h>
1359 #include <stdio.h>
1360 #include <stdlib.h>
1361 #include <string.h>
1362
1363 FILE *
1364 open_sesame (char *name)
1365 @{
1366   FILE *stream;
1367
1368   errno = 0;
1369   stream = fopen (name, "r");
1370   if (stream == NULL)
1371     @{
1372       fprintf (stderr, "%s: Couldn't open file %s; %s\n",
1373                program_invocation_short_name, name, strerror (errno));
1374       exit (EXIT_FAILURE);
1375     @}
1376   else
1377     return stream;
1378 @}
1379 @end smallexample
1380
1381 Using @code{perror} has the advantage that the function is portable and
1382 available on all systems implementing @w{ISO C}.  But often the text
1383 @code{perror} generates is not what is wanted and there is no way to
1384 extend or change what @code{perror} does.  The GNU coding standard, for
1385 instance, requires error messages to be preceded by the program name and
1386 programs which read some input files should should provide information
1387 about the input file name and the line number in case an error is
1388 encountered while reading the file.  For these occasions there are two
1389 functions available which are widely used throughout the GNU project.
1390 These functions are declared in @file{error.h}.
1391
1392 @comment error.h
1393 @comment GNU
1394 @deftypefun void error (int @var{status}, int @var{errnum}, const char *@var{format}, @dots{})
1395 The @code{error} function can be used to report general problems during
1396 program execution.  The @var{format} argument is a format string just
1397 like those given to the @code{printf} family of functions.  The
1398 arguments required for the format can follow the @var{format} parameter.
1399 Just like @code{perror}, @code{error} also can report an error code in
1400 textual form.  But unlike @code{perror} the error value is explicitly
1401 passed to the function in the @var{errnum} parameter.  This elimintates
1402 the problem mentioned above that the error reporting function must be
1403 called immediately after the function causing the error since otherwise
1404 @code{errno} might have a different value.
1405
1406 The @code{error} prints first the program name.  If the application
1407 defined a global variable @code{error_print_progname} and points it to a
1408 function this function will be called to print the program name.
1409 Otherwise the string from the global variable @code{program_name} is
1410 used.  The program name is followed by a colon and a space which in turn
1411 is followed by the output produced by the format string.  If the
1412 @var{errnum} parameter is non-zero the format string output is followed
1413 by a colon and a space, followed by the error message for the error code
1414 @var{errnum}.  In any case is the output terminated with a newline.
1415
1416 The output is directed to the @code{stderr} stream.  If the
1417 @code{stderr} wasn't oriented before the call it will be narrow-oriented
1418 afterwards.
1419
1420 The function will return unless the @var{status} parameter has a
1421 non-zero value.  In this case the function will call @code{exit} with
1422 the @var{status} value for its parameter and therefore never return.  If
1423 @code{error} returns the global variable @code{error_message_count} is
1424 incremented by one to keep track of the number of errors reported.
1425 @end deftypefun
1426
1427 @comment error.h
1428 @comment GNU
1429 @deftypefun void error_at_line (int @var{status}, int @var{errnum}, const char *@var{fname}, unsigned int @var{lineno}, const char *@var{format}, @dots{})
1430
1431 The @code{error_at_line} function is very similar to the @code{error}
1432 function.  The only difference are the additional parameters @var{fname}
1433 and @var{lineno}.  The handling of the other parameters is identical to
1434 that of @code{error} except that between the program name and the string
1435 generated by the format string additional text is inserted.
1436
1437 Directly following the program name a colon, followed by the file name
1438 pointer to by @var{fname}, another colon, and a value of @var{lineno} is
1439 printed.
1440
1441 This additional output of course is meant to be used to locate an error
1442 in an input file (like a programming language source code file etc).
1443
1444 If the global variable @code{error_one_per_line} is set to a non-zero
1445 value @code{error_at_line} will avoid printing consecutive messages for
1446 the same file anem line.  Repetition which are not directly following
1447 each other are not caught.
1448
1449 Just like @code{error} this function only returned if @var{status} is
1450 zero.  Otherwise @code{exit} is called with the non-zero value.  If
1451 @code{error} returns the global variable @code{error_message_count} is
1452 incremented by one to keep track of the number of errors reported.
1453 @end deftypefun
1454
1455 As mentioned above the @code{error} and @code{error_at_line} functions
1456 can be customized by defining a variable named
1457 @code{error_print_progname}.
1458
1459 @comment error.h
1460 @comment GNU
1461 @deftypevar {void (*} error_print_progname ) (void)
1462 If the @code{error_print_progname} variable is defined to a non-zero
1463 value the function pointed to is called by @code{error} or
1464 @code{error_at_line}.  It is expected to print the program name or do
1465 something similarly useful.
1466
1467 The function is expected to be print to the @code{stderr} stream and
1468 must be able to handle whatever orientation the stream has.
1469
1470 The variable is global and shared by all threads.
1471 @end deftypevar
1472
1473 @comment error.h
1474 @comment GNU
1475 @deftypevar {unsigned int} error_message_count
1476 The @code{error_message_count} variable is incremented whenever one of
1477 the functions @code{error} or @code{error_at_line} returns.  The
1478 variable is global and shared by all threads.
1479 @end deftypevar
1480
1481 @comment error.h
1482 @comment GNU
1483 @deftypevar int error_one_per_line
1484 The @code{error_one_per_line} variable influences only
1485 @code{error_at_line}.  Normally the @code{error_at_line} function
1486 creates output for every invocation.  If @code{error_one_per_line} is
1487 set to a non-zero value @code{error_at_line} keeps track of the last
1488 file name and line number for which an error was reported and avoid
1489 directly following messages for the same file and line.  This variable
1490 is global and shared by all threads.
1491 @end deftypevar
1492
1493 @noindent
1494 A program which read some input file and reports errors in it could look
1495 like this:
1496
1497 @smallexample
1498 @{
1499   char *line = NULL;
1500   size_t len = 0;
1501   unsigned int lineno = 0;
1502
1503   error_message_count = 0;
1504   while (! feof_unlocked (fp))
1505     @{
1506       ssize_t n = getline (&line, &len, fp);
1507       if (n <= 0)
1508         /* @r{End of file or error.}  */
1509         break;
1510       ++lineno;
1511
1512       /* @r{Process the line.}  */
1513       @dots{}
1514
1515       if (@r{Detect error in line})
1516         error_at_line (0, errval, filename, lineno,
1517                        "some error text %s", some_variable);
1518     @}
1519
1520   if (error_message_count != 0)
1521     error (EXIT_FAILURE, 0, "%u errors found", error_message_count);
1522 @}
1523 @end smallexample
1524
1525 @code{error} and @code{error_at_line} are clearly the functions of
1526 choice and enable the programmer to write applications which follow the
1527 GNU coding standard.  The GNU libc additionally contains functions which
1528 are used in BSD for the same purpose.  These functions are declared in
1529 @file{err.h}.  It is generally advised to not use these functions.  They
1530 are included only for compatibility.
1531
1532 @comment err.h
1533 @comment BSD
1534 @deftypefun void warn (const char *@var{format}, @dots{})
1535 The @code{warn} function is roughly equivalent to a call like
1536 @smallexample
1537   error (0, errno, format, @r{the parameters})
1538 @end smallexample
1539 @noindent
1540 except that the global variables @code{error} respects and modifies
1541 are not used.
1542 @end deftypefun
1543
1544 @comment err.h
1545 @comment BSD
1546 @deftypefun void vwarn (const char *@var{format}, va_list)
1547 The @code{vwarn} function is just like @code{warn} except that the
1548 parameters for the handling of the format string @var{format} are passed
1549 in as an value of type @code{va_list}.
1550 @end deftypefun
1551
1552 @comment err.h
1553 @comment BSD
1554 @deftypefun void warnx (const char *@var{format}, @dots{})
1555 The @code{warnx} function is roughly equivalent to a call like
1556 @smallexample
1557   error (0, 0, format, @r{the parameters})
1558 @end smallexample
1559 @noindent
1560 except that the global variables @code{error} respects and modifies
1561 are not used.  The difference to @code{warn} is that no error number
1562 string is printed.
1563 @end deftypefun
1564
1565 @comment err.h
1566 @comment BSD
1567 @deftypefun void vwarnx (const char *@var{format}, va_list)
1568 The @code{vwarnx} function is just like @code{warnx} except that the
1569 parameters for the handling of the format string @var{format} are passed
1570 in as an value of type @code{va_list}.
1571 @end deftypefun
1572
1573 @comment err.h
1574 @comment BSD
1575 @deftypefun void err (int @var{status}, const char *@var{format}, @dots{})
1576 The @code{err} function is roughly equivalent to a call like
1577 @smallexample
1578   error (status, errno, format, @r{the parameters})
1579 @end smallexample
1580 @noindent
1581 except that the global variables @code{error} respects and modifies
1582 are not used and that the program is exited even if @var{status} is zero.
1583 @end deftypefun
1584
1585 @comment err.h
1586 @comment BSD
1587 @deftypefun void verr (int @var{status}, const char *@var{format}, va_list)
1588 The @code{verr} function is just like @code{err} except that the
1589 parameters for the handling of the format string @var{format} are passed
1590 in as an value of type @code{va_list}.
1591 @end deftypefun
1592
1593 @comment err.h
1594 @comment BSD
1595 @deftypefun void errx (int @var{status}, const char *@var{format}, @dots{})
1596 The @code{errx} function is roughly equivalent to a call like
1597 @smallexample
1598   error (status, 0, format, @r{the parameters})
1599 @end smallexample
1600 @noindent
1601 except that the global variables @code{error} respects and modifies
1602 are not used and that the program is exited even if @var{status}
1603 is zero.  The difference to @code{err} is that no error number
1604 string is printed.
1605 @end deftypefun
1606
1607 @comment err.h
1608 @comment BSD
1609 @deftypefun void verrx (int @var{status}, const char *@var{format}, va_list)
1610 The @code{verrx} function is just like @code{errx} except that the
1611 parameters for the handling of the format string @var{format} are passed
1612 in as an value of type @code{va_list}.
1613 @end deftypefun