1 @node Error Reporting, Memory Allocation, Introduction, Top
2 @chapter Error Reporting
3 @cindex error reporting
4 @cindex reporting errors
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.
14 This chapter describes how the error reporting facility works. Your
15 program should include the header file @file{errno.h} to use this
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.
26 @node Checking for Errors, Error Codes, , Error Reporting
27 @section Checking for Errors
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
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}.
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.
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
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.
65 @strong{Portability Note:} ANSI 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.
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.
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}.
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.
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.
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.
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.
110 @node Error Codes, Error Messages, Checking for Errors, Error Reporting
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.
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.
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.
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.
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 occured and prevented
148 completion of the call. When this happens, you should try the call
151 You can choose to have functions resume after a signal that is handled,
152 rather than failing with @code{EINTR}; see @ref{Interrupted
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.
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
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
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}.
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
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
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.
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.
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.
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.
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.
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.
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.
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}).
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.
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.
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.
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.
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.
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}.
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.
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.
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.
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.
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
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).
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.
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}).
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}.
400 @comment ANSI: 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.
408 @comment ANSI: 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.
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.
423 This error can happen in a few different situations:
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}.
433 @strong{Portability Note:} In older Unix many 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.
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.
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.
457 C libraries in many older Unix systems have @code{EWOULDBLOCK} as a
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}.
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
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.
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
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.
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}.
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}.
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.
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.
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.
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}.
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}.
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}.
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.
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
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.
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.
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
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.
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.
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.
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}.
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.
654 @comment BSD: Too many references: cannot splice
655 @deftypevr Macro int ETOOMANYREFS
656 @comment errno 59 @c DO NOT REMOVE
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
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).
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.
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}).
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.
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.
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.
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.
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.
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.
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.
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.)
760 @comment BSD: RPC struct is bad
761 @deftypevr Macro int EBADRPC
762 @comment errno 72 @c DO NOT REMOVE
767 @comment BSD: RPC version wrong
768 @deftypevr Macro int ERPCMISMATCH
769 @comment errno 73 @c DO NOT REMOVE
774 @comment BSD: RPC program not available
775 @deftypevr Macro int EPROGUNAVAIL
776 @comment errno 74 @c DO NOT REMOVE
781 @comment BSD: RPC program version wrong
782 @deftypevr Macro int EPROGMISMATCH
783 @comment errno 75 @c DO NOT REMOVE
788 @comment BSD: RPC bad procedure for program
789 @deftypevr Macro int EPROCUNAVAIL
790 @comment errno 76 @c DO NOT REMOVE
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
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.
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}.
816 @comment BSD: Authentication error
817 @deftypevr Macro int EAUTH
818 @comment errno 80 @c DO NOT REMOVE
823 @comment BSD: Need authenticator
824 @deftypevr Macro int ENEEDAUTH
825 @comment errno 81 @c DO NOT REMOVE
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.
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.
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.
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.
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.
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}?
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.
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.
898 @comment XOPEN: Bad message
899 @deftypevr Macro int EBADMSG
904 @comment XOPEN: Identifier removed
905 @deftypevr Macro int EIDRM
910 @comment XOPEN: Multihop attempted
911 @deftypevr Macro int EMULTIHOP
916 @comment XOPEN: No data available
917 @deftypevr Macro int ENODATA
922 @comment XOPEN: Link has been severed
923 @deftypevr Macro int ENOLINK
928 @comment XOPEN: No message of desired type
929 @deftypevr Macro int ENOMSG
934 @comment XOPEN: Out of streams resources
935 @deftypevr Macro int ENOSR
940 @comment XOPEN: Device not a stream
941 @deftypevr Macro int ENOSTR
946 @comment XOPEN: Value too large for defined data type
947 @deftypevr Macro int EOVERFLOW
952 @comment XOPEN: Protocol error
953 @deftypevr Macro int EPROTO
958 @comment XOPEN: Timer expired
959 @deftypevr Macro int ETIME
964 @emph{The following error codes are defined by the Linux/i386 kernel.
965 They are not yet documented.}
968 @comment Linux???: Interrupted system call should be restarted
969 @deftypevr Macro int ERESTART
970 @comment errno ???/85
974 @comment Linux???: Channel number out of range
975 @deftypevr Macro int ECHRNG
976 @comment errno ???/44
980 @comment Linux???: Level 2 not synchronized
981 @deftypevr Macro int EL2NSYNC
982 @comment errno ???/45
986 @comment Linux???: Level 3 halted
987 @deftypevr Macro int EL3HLT
988 @comment errno ???/46
992 @comment Linux???: Level 3 reset
993 @deftypevr Macro int EL3RST
994 @comment errno ???/47
998 @comment Linux???: Link number out of range
999 @deftypevr Macro int ELNRNG
1000 @comment errno ???/48
1004 @comment Linux???: Protocol driver not attached
1005 @deftypevr Macro int EUNATCH
1006 @comment errno ???/49
1010 @comment Linux???: No CSI structure available
1011 @deftypevr Macro int ENOCSI
1012 @comment errno ???/50
1016 @comment Linux???: Level 2 halted
1017 @deftypevr Macro int EL2HLT
1018 @comment errno ???/51
1022 @comment Linux???: Invalid exchange
1023 @deftypevr Macro int EBADE
1024 @comment errno ???/52
1028 @comment Linux???: Invalid request descriptor
1029 @deftypevr Macro int EBADR
1030 @comment errno ???/53
1034 @comment Linux???: Exchange full
1035 @deftypevr Macro int EXFULL
1036 @comment errno ???/54
1040 @comment Linux???: No anode
1041 @deftypevr Macro int ENOANO
1042 @comment errno ???/55
1046 @comment Linux???: Invalid request code
1047 @deftypevr Macro int EBADRQC
1048 @comment errno ???/56
1052 @comment Linux???: Invalid slot
1053 @deftypevr Macro int EBADSLT
1054 @comment errno ???/57
1058 @comment Linux???: File locking deadlock error
1059 @deftypevr Macro int EDEADLOCK
1060 @comment errno ???/58
1064 @comment Linux???: Bad font file format
1065 @deftypevr Macro int EBFONT
1066 @comment errno ???/59
1070 @comment Linux???: Machine is not on the network
1071 @deftypevr Macro int ENONET
1072 @comment errno ???/64
1076 @comment Linux???: Package not installed
1077 @deftypevr Macro int ENOPKG
1078 @comment errno ???/65
1082 @comment Linux???: Advertise error
1083 @deftypevr Macro int EADV
1084 @comment errno ???/68
1088 @comment Linux???: Srmount error
1089 @deftypevr Macro int ESRMNT
1090 @comment errno ???/69
1094 @comment Linux???: Communication error on send
1095 @deftypevr Macro int ECOMM
1096 @comment errno ???/70
1100 @comment Linux???: RFS specific error
1101 @deftypevr Macro int EDOTDOT
1102 @comment errno ???/73
1106 @comment Linux???: Name not unique on network
1107 @deftypevr Macro int ENOTUNIQ
1108 @comment errno ???/76
1112 @comment Linux???: File descriptor in bad state
1113 @deftypevr Macro int EBADFD
1114 @comment errno ???/77
1118 @comment Linux???: Remote address changed
1119 @deftypevr Macro int EREMCHG
1120 @comment errno ???/78
1124 @comment Linux???: Can not access a needed shared library
1125 @deftypevr Macro int ELIBACC
1126 @comment errno ???/79
1130 @comment Linux???: Accessing a corrupted shared library
1131 @deftypevr Macro int ELIBBAD
1132 @comment errno ???/80
1136 @comment Linux???: .lib section in a.out corrupted
1137 @deftypevr Macro int ELIBSCN
1138 @comment errno ???/81
1142 @comment Linux???: Attempting to link in too many shared libraries
1143 @deftypevr Macro int ELIBMAX
1144 @comment errno ???/82
1148 @comment Linux???: Cannot exec a shared library directly
1149 @deftypevr Macro int ELIBEXEC
1150 @comment errno ???/83
1154 @comment Linux???: Streams pipe error
1155 @deftypevr Macro int ESTRPIPE
1156 @comment errno ???/86
1160 @comment Linux???: Structure needs cleaning
1161 @deftypevr Macro int EUCLEAN
1162 @comment errno ???/117
1166 @comment Linux???: Not a XENIX named type file
1167 @deftypevr Macro int ENOTNAM
1168 @comment errno ???/118
1172 @comment Linux???: No XENIX semaphores available
1173 @deftypevr Macro int ENAVAIL
1174 @comment errno ???/119
1178 @comment Linux???: Is a named type file
1179 @deftypevr Macro int EISNAM
1180 @comment errno ???/120
1184 @comment Linux???: Remote I/O error
1185 @deftypevr Macro int EREMOTEIO
1186 @comment errno ???/121
1189 @node Error Messages, , Error Codes, Error Reporting
1190 @section Error Messages
1192 The library has functions and variables designed to make it easy for
1193 your program to report informative error messages in the customary
1194 format about the failure of a library call. The functions
1195 @code{strerror} and @code{perror} give you the standard error message
1196 for a given error code; the variable
1197 @w{@code{program_invocation_short_name}} gives you convenient access to the
1198 name of the program that encountered the error.
1202 @deftypefun {char *} strerror (int @var{errnum})
1203 The @code{strerror} function maps the error code (@pxref{Checking for
1204 Errors}) specified by the @var{errnum} argument to a descriptive error
1205 message string. The return value is a pointer to this string.
1207 The value @var{errnum} normally comes from the variable @code{errno}.
1209 You should not modify the string returned by @code{strerror}. Also, if
1210 you make subsequent calls to @code{strerror}, the string might be
1211 overwritten. (But it's guaranteed that no library function ever calls
1212 @code{strerror} behind your back.)
1214 The function @code{strerror} is declared in @file{string.h}.
1219 @deftypefun void perror (const char *@var{message})
1220 This function prints an error message to the stream @code{stderr};
1221 see @ref{Standard Streams}.
1223 If you call @code{perror} with a @var{message} that is either a null
1224 pointer or an empty string, @code{perror} just prints the error message
1225 corresponding to @code{errno}, adding a trailing newline.
1227 If you supply a non-null @var{message} argument, then @code{perror}
1228 prefixes its output with this string. It adds a colon and a space
1229 character to separate the @var{message} from the error string corresponding
1232 The function @code{perror} is declared in @file{stdio.h}.
1235 @code{strerror} and @code{perror} produce the exact same message for any
1236 given error code; the precise text varies from system to system. On the
1237 GNU system, the messages are fairly short; there are no multi-line
1238 messages or embedded newlines. Each error message begins with a capital
1239 letter and does not include any terminating punctuation.
1241 @strong{Compatibility Note:} The @code{strerror} function is a new
1242 feature of ANSI C. Many older C systems do not support this function
1245 @cindex program name
1246 @cindex name of running program
1247 Many programs that don't read input from the terminal are designed to
1248 exit if any system call fails. By convention, the error message from
1249 such a program should start with the program's name, sans directories.
1250 You can find that name in the variable
1251 @code{program_invocation_short_name}; the full file name is stored the
1252 variable @code{program_invocation_name}:
1256 @deftypevar {char *} program_invocation_name
1257 This variable's value is the name that was used to invoke the program
1258 running in the current process. It is the same as @code{argv[0]}. Note
1259 that this is not necessarily a useful file name; often it contains no
1260 directory names. @xref{Program Arguments}.
1265 @deftypevar {char *} program_invocation_short_name
1266 This variable's value is the name that was used to invoke the program
1267 running in the current process, with directory names removed. (That is
1268 to say, it is the same as @code{program_invocation_name} minus
1269 everything up to the last slash, if any.)
1272 The library initialization code sets up both of these variables before
1273 calling @code{main}.
1275 @strong{Portability Note:} These two variables are GNU extensions. If
1276 you want your program to work with non-GNU libraries, you must save the
1277 value of @code{argv[0]} in @code{main}, and then strip off the directory
1278 names yourself. We added these extensions to make it possible to write
1279 self-contained error-reporting subroutines that require no explicit
1280 cooperation from @code{main}.
1282 Here is an example showing how to handle failure to open a file
1283 correctly. The function @code{open_sesame} tries to open the named file
1284 for reading and returns a stream if successful. The @code{fopen}
1285 library function returns a null pointer if it couldn't open the file for
1286 some reason. In that situation, @code{open_sesame} constructs an
1287 appropriate error message using the @code{strerror} function, and
1288 terminates the program. If we were going to make some other library
1289 calls before passing the error code to @code{strerror}, we'd have to
1290 save it in a local variable instead, because those other library
1291 functions might overwrite @code{errno} in the meantime.
1300 open_sesame (char *name)
1305 stream = fopen (name, "r");
1308 fprintf (stderr, "%s: Couldn't open file %s; %s\n",
1309 program_invocation_short_name, name, strerror (errno));
1310 exit (EXIT_FAILURE);