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