diff options
Diffstat (limited to 'manual/errno.texi')
| -rw-r--r-- | manual/errno.texi | 1015 |
1 files changed, 1015 insertions, 0 deletions
diff --git a/manual/errno.texi b/manual/errno.texi new file mode 100644 index 0000000000..836fff3bf2 --- /dev/null +++ b/manual/errno.texi @@ -0,0 +1,1015 @@ +@node Error Reporting, Memory Allocation, Introduction, Top +@chapter Error Reporting +@cindex error reporting +@cindex reporting errors +@cindex error codes +@cindex status codes + +Many functions in the GNU C library detect and report error conditions, +and sometimes your programs need to check for these error conditions. +For example, when you open an input file, you should verify that the +file was actually opened correctly, and print an error message or take +other appropriate action if the call to the library function failed. + +This chapter describes how the error reporting facility works. Your +program should include the header file @file{errno.h} to use this +facility. +@pindex errno.h + +@menu +* Checking for Errors:: How errors are reported by library functions. +* Error Codes:: Error code macros; all of these expand + into integer constant values. +* Error Messages:: Mapping error codes onto error messages. +@end menu + +@node Checking for Errors, Error Codes, , Error Reporting +@section Checking for Errors + +Most library functions return a special value to indicate that they have +failed. The special value is typically @code{-1}, a null pointer, or a +constant such as @code{EOF} that is defined for that purpose. But this +return value tells you only that an error has occurred. To find out +what kind of error it was, you need to look at the error code stored in the +variable @code{errno}. This variable is declared in the header file +@file{errno.h}. +@pindex errno.h + +@comment errno.h +@comment ANSI +@deftypevr {Variable} {volatile int} errno +The variable @code{errno} contains the system error number. You can +change the value of @code{errno}. + +Since @code{errno} is declared @code{volatile}, it might be changed +asynchronously by a signal handler; see @ref{Defining Handlers}. +However, a properly written signal handler saves and restores the value +of @code{errno}, so you generally do not need to worry about this +possibility except when writing signal handlers. + +The initial value of @code{errno} at program startup is zero. Many +library functions are guaranteed to set it to certain nonzero values +when they encounter certain kinds of errors. These error conditions are +listed for each function. These functions do not change @code{errno} +when they succeed; thus, the value of @code{errno} after a successful +call is not necessarily zero, and you should not use @code{errno} to +determine @emph{whether} a call failed. The proper way to do that is +documented for each function. @emph{If} the call the failed, you can +examine @code{errno}. + +Many library functions can set @code{errno} to a nonzero value as a +result of calling other library functions which might fail. You should +assume that any library function might alter @code{errno} when the +function returns an error. + +@strong{Portability Note:} ANSI C specifies @code{errno} as a +``modifiable lvalue'' rather than as a variable, permitting it to be +implemented as a macro. For example, its expansion might involve a +function call, like @w{@code{*_errno ()}}. In fact, that is what it is +on the GNU system itself. The GNU library, on non-GNU systems, does +whatever is right for the particular system. + +There are a few library functions, like @code{sqrt} and @code{atan}, +that return a perfectly legitimate value in case of an error, but also +set @code{errno}. For these functions, if you want to check to see +whether an error occurred, the recommended method is to set @code{errno} +to zero before calling the function, and then check its value afterward. +@end deftypevr + +@pindex errno.h +All the error codes have symbolic names; they are macros defined in +@file{errno.h}. The names start with @samp{E} and an upper-case +letter or digit; you should consider names of this form to be +reserved names. @xref{Reserved Names}. + +The error code values are all positive integers and are all distinct, +with one exception: @code{EWOULDBLOCK} and @code{EAGAIN} are the same. +Since the values are distinct, you can use them as labels in a +@code{switch} statement; just don't use both @code{EWOULDBLOCK} and +@code{EAGAIN}. Your program should not make any other assumptions about +the specific values of these symbolic constants. + +The value of @code{errno} doesn't necessarily have to correspond to any +of these macros, since some library functions might return other error +codes of their own for other situations. The only values that are +guaranteed to be meaningful for a particular library function are the +ones that this manual lists for that function. + +On non-GNU systems, almost any system call can return @code{EFAULT} if +it is given an invalid pointer as an argument. Since this could only +happen as a result of a bug in your program, and since it will not +happen on the GNU system, we have saved space by not mentioning +@code{EFAULT} in the descriptions of individual functions. + +In some Unix systems, many system calls can also return @code{EFAULT} if +given as an argument a pointer into the stack, and the kernel for some +obscure reason fails in its attempt to extend the stack. If this ever +happens, you should probably try using statically or dynamically +allocated memory instead of stack memory on that system. + +@node Error Codes, Error Messages, Checking for Errors, Error Reporting +@section Error Codes + +@pindex errno.h +The error code macros are defined in the header file @file{errno.h}. +All of them expand into integer constant values. Some of these error +codes can't occur on the GNU system, but they can occur using the GNU +library on other systems. + +@comment errno.h +@comment POSIX.1: Operation not permitted +@deftypevr Macro int EPERM +@comment errno 1 @c DO NOT REMOVE +Operation not permitted; only the owner of the file (or other resource) +or processes with special privileges can perform the operation. +@end deftypevr + +@comment errno.h +@comment POSIX.1: No such file or directory +@deftypevr Macro int ENOENT +@comment errno 2 @c DO NOT REMOVE +No such file or directory. This is a ``file doesn't exist'' error +for ordinary files that are referenced in contexts where they are +expected to already exist. +@end deftypevr + +@comment errno.h +@comment POSIX.1: No such process +@deftypevr Macro int ESRCH +@comment errno 3 @c DO NOT REMOVE +No process matches the specified process ID. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Interrupted system call +@deftypevr Macro int EINTR +@comment errno 4 @c DO NOT REMOVE +Interrupted function call; an asynchronous signal occured and prevented +completion of the call. When this happens, you should try the call +again. + +You can choose to have functions resume after a signal that is handled, +rather than failing with @code{EINTR}; see @ref{Interrupted +Primitives}. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Input/output error +@deftypevr Macro int EIO +@comment errno 5 @c DO NOT REMOVE +Input/output error; usually used for physical read or write errors. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Device not configured +@deftypevr Macro int ENXIO +@comment errno 6 @c DO NOT REMOVE +No such device or address. The system tried to use the device +represented by a file you specified, and it couldn't find the device. +This can mean that the device file was installed incorrectly, or that +the physical device is missing or not correctly attached to the +computer. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Argument list too long +@deftypevr Macro int E2BIG +@comment errno 7 @c DO NOT REMOVE +Argument list too long; used when the arguments passed to a new program +being executed with one of the @code{exec} functions (@pxref{Executing a +File}) occupy too much memory space. This condition never arises in the +GNU system. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Exec format error +@deftypevr Macro int ENOEXEC +@comment errno 8 @c DO NOT REMOVE +Invalid executable file format. This condition is detected by the +@code{exec} functions; see @ref{Executing a File}. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Bad file descriptor +@deftypevr Macro int EBADF +@comment errno 9 @c DO NOT REMOVE +Bad file descriptor; for example, I/O on a descriptor that has been +closed or reading from a descriptor open only for writing (or vice +versa). +@end deftypevr + +@comment errno.h +@comment POSIX.1: No child processes +@deftypevr Macro int ECHILD +@comment errno 10 @c DO NOT REMOVE +There are no child processes. This error happens on operations that are +supposed to manipulate child processes, when there aren't any processes +to manipulate. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Resource deadlock avoided +@deftypevr Macro int EDEADLK +@comment errno 11 @c DO NOT REMOVE +Deadlock avoided; allocating a system resource would have resulted in a +deadlock situation. The system does not guarantee that it will notice +all such situations. This error means you got lucky and the system +noticed; it might just hang. @xref{File Locks}, for an example. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Cannot allocate memory +@deftypevr Macro int ENOMEM +@comment errno 12 @c DO NOT REMOVE +No memory available. The system cannot allocate more virtual memory +because its capacity is full. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Permission denied +@deftypevr Macro int EACCES +@comment errno 13 @c DO NOT REMOVE +Permission denied; the file permissions do not allow the attempted operation. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Bad address +@deftypevr Macro int EFAULT +@comment errno 14 @c DO NOT REMOVE +Bad address; an invalid pointer was detected. +In the GNU system, this error never happens; you get a signal instead. +@end deftypevr + +@comment errno.h +@comment BSD: Block device required +@deftypevr Macro int ENOTBLK +@comment errno 15 @c DO NOT REMOVE +A file that isn't a block special file was given in a situation that +requires one. For example, trying to mount an ordinary file as a file +system in Unix gives this error. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Device busy +@deftypevr Macro int EBUSY +@comment errno 16 @c DO NOT REMOVE +Resource busy; a system resource that can't be shared is already in use. +For example, if you try to delete a file that is the root of a currently +mounted filesystem, you get this error. +@end deftypevr + +@comment errno.h +@comment POSIX.1: File exists +@deftypevr Macro int EEXIST +@comment errno 17 @c DO NOT REMOVE +File exists; an existing file was specified in a context where it only +makes sense to specify a new file. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Invalid cross-device link +@deftypevr Macro int EXDEV +@comment errno 18 @c DO NOT REMOVE +An attempt to make an improper link across file systems was detected. +This happens not only when you use @code{link} (@pxref{Hard Links}) but +also when you rename a file with @code{rename} (@pxref{Renaming Files}). +@end deftypevr + +@comment errno.h +@comment POSIX.1: Operation not supported by device +@deftypevr Macro int ENODEV +@comment errno 19 @c DO NOT REMOVE +The wrong type of device was given to a function that expects a +particular sort of device. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Not a directory +@deftypevr Macro int ENOTDIR +@comment errno 20 @c DO NOT REMOVE +A file that isn't a directory was specified when a directory is required. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Is a directory +@deftypevr Macro int EISDIR +@comment errno 21 @c DO NOT REMOVE +File is a directory; you cannot open a directory for writing, +or create or remove hard links to it. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Invalid argument +@deftypevr Macro int EINVAL +@comment errno 22 @c DO NOT REMOVE +Invalid argument. This is used to indicate various kinds of problems +with passing the wrong argument to a library function. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Too many open files +@deftypevr Macro int EMFILE +@comment errno 24 @c DO NOT REMOVE +The current process has too many files open and can't open any more. +Duplicate descriptors do count toward this limit. + +In BSD and GNU, the number of open files is controlled by a resource +limit that can usually be increased. If you get this error, you might +want to increase the @code{RLIMIT_NOFILE} limit or make it unlimited; +@pxref{Limits on Resources}. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Too many open files in system +@deftypevr Macro int ENFILE +@comment errno 23 @c DO NOT REMOVE +There are too many distinct file openings in the entire system. Note +that any number of linked channels count as just one file opening; see +@ref{Linked Channels}. This error never occurs in the GNU system. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Inappropriate ioctl for device +@deftypevr Macro int ENOTTY +@comment errno 25 @c DO NOT REMOVE +Inappropriate I/O control operation, such as trying to set terminal +modes on an ordinary file. +@end deftypevr + +@comment errno.h +@comment BSD: Text file busy +@deftypevr Macro int ETXTBSY +@comment errno 26 @c DO NOT REMOVE +An attempt to execute a file that is currently open for writing, or +write to a file that is currently being executed. Often using a +debugger to run a program is considered having it open for writing and +will cause this error. (The name stands for ``text file busy''.) This +is not an error in the GNU system; the text is copied as necessary. +@end deftypevr + +@comment errno.h +@comment POSIX.1: File too large +@deftypevr Macro int EFBIG +@comment errno 27 @c DO NOT REMOVE +File too big; the size of a file would be larger than allowed by the system. +@end deftypevr + +@comment errno.h +@comment POSIX.1: No space left on device +@deftypevr Macro int ENOSPC +@comment errno 28 @c DO NOT REMOVE +No space left on device; write operation on a file failed because the +disk is full. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Illegal seek +@deftypevr Macro int ESPIPE +@comment errno 29 @c DO NOT REMOVE +Invalid seek operation (such as on a pipe). +@end deftypevr + +@comment errno.h +@comment POSIX.1: Read-only file system +@deftypevr Macro int EROFS +@comment errno 30 @c DO NOT REMOVE +An attempt was made to modify something on a read-only file system. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Too many links +@deftypevr Macro int EMLINK +@comment errno 31 @c DO NOT REMOVE +Too many links; the link count of a single file would become too large. +@code{rename} can cause this error if the file being renamed already has +as many links as it can take (@pxref{Renaming Files}). +@end deftypevr + +@comment errno.h +@comment POSIX.1: Broken pipe +@deftypevr Macro int EPIPE +@comment errno 32 @c DO NOT REMOVE +Broken pipe; there is no process reading from the other end of a pipe. +Every library function that returns this error code also generates a +@code{SIGPIPE} signal; this signal terminates the program if not handled +or blocked. Thus, your program will never actually see @code{EPIPE} +unless it has handled or blocked @code{SIGPIPE}. +@end deftypevr + +@comment errno.h +@comment ANSI: Numerical argument out of domain +@deftypevr Macro int EDOM +@comment errno 33 @c DO NOT REMOVE +Domain error; used by mathematical functions when an argument value does +not fall into the domain over which the function is defined. +@end deftypevr + +@comment errno.h +@comment ANSI: Numerical result out of range +@deftypevr Macro int ERANGE +@comment errno 34 @c DO NOT REMOVE +Range error; used by mathematical functions when the result value is +not representable because of overflow or underflow. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Resource temporarily unavailable +@deftypevr Macro int EAGAIN +@comment errno 35 @c DO NOT REMOVE +Resource temporarily unavailable; the call might work if you try again +later. The macro @code{EWOULDBLOCK} is another name for @code{EAGAIN}; +they are always the same in the GNU C library. + +This error can happen in a few different situations: + +@itemize @bullet +@item +An operation that would block was attempted on an object that has +non-blocking mode selected. Trying the same operation again will block +until some external condition makes it possible to read, write, or +connect (whatever the operation). You can use @code{select} to find out +when the operation will be possible; @pxref{Waiting for I/O}. + +@strong{Portability Note:} In older Unix many systems, this condition +was indicated by @code{EWOULDBLOCK}, which was a distinct error code +different from @code{EAGAIN}. To make your program portable, you should +check for both codes and treat them the same. + +@item +A temporary resource shortage made an operation impossible. @code{fork} +can return this error. It indicates that the shortage is expected to +pass, so your program can try the call again later and it may succeed. +It is probably a good idea to delay for a few seconds before trying it +again, to allow time for other processes to release scarce resources. +Such shortages are usually fairly serious and affect the whole system, +so usually an interactive program should report the error to the user +and return to its command loop. +@end itemize +@end deftypevr + +@comment errno.h +@comment BSD: Operation would block +@deftypevr Macro int EWOULDBLOCK +@comment errno EAGAIN @c DO NOT REMOVE +In the GNU C library, this is another name for @code{EAGAIN} (above). +The values are always the same, on every operating system. + +C libraries in many older Unix systems have @code{EWOULDBLOCK} as a +separate error code. +@end deftypevr + +@comment errno.h +@comment BSD: Operation now in progress +@deftypevr Macro int EINPROGRESS +@comment errno 36 @c DO NOT REMOVE +An operation that cannot complete immediately was initiated on an object +that has non-blocking mode selected. Some functions that must always +block (such as @code{connect}; @pxref{Connecting}) never return +@code{EAGAIN}. Instead, they return @code{EINPROGRESS} to indicate that +the operation has begun and will take some time. Attempts to manipulate +the object before the call completes return @code{EALREADY}. You can +use the @code{select} function to find out when the pending operation +has completed; @pxref{Waiting for I/O}. +@end deftypevr + +@comment errno.h +@comment BSD: Operation already in progress +@deftypevr Macro int EALREADY +@comment errno 37 @c DO NOT REMOVE +An operation is already in progress on an object that has non-blocking +mode selected. +@end deftypevr + +@comment errno.h +@comment BSD: Socket operation on non-socket +@deftypevr Macro int ENOTSOCK +@comment errno 38 @c DO NOT REMOVE +A file that isn't a socket was specified when a socket is required. +@end deftypevr + +@comment errno.h +@comment BSD: Message too long +@deftypevr Macro int EMSGSIZE +@comment errno 40 @c DO NOT REMOVE +The size of a message sent on a socket was larger than the supported +maximum size. +@end deftypevr + +@comment errno.h +@comment BSD: Protocol wrong type for socket +@deftypevr Macro int EPROTOTYPE +@comment errno 41 @c DO NOT REMOVE +The socket type does not support the requested communications protocol. +@end deftypevr + +@comment errno.h +@comment BSD: Protocol not available +@deftypevr Macro int ENOPROTOOPT +@comment errno 42 @c DO NOT REMOVE +You specified a socket option that doesn't make sense for the +particular protocol being used by the socket. @xref{Socket Options}. +@end deftypevr + +@comment errno.h +@comment BSD: Protocol not supported +@deftypevr Macro int EPROTONOSUPPORT +@comment errno 43 @c DO NOT REMOVE +The socket domain does not support the requested communications protocol +(perhaps because the requested protocol is completely invalid.) +@xref{Creating a Socket}. +@end deftypevr + +@comment errno.h +@comment BSD: Socket type not supported +@deftypevr Macro int ESOCKTNOSUPPORT +@comment errno 44 @c DO NOT REMOVE +The socket type is not supported. +@end deftypevr + +@comment errno.h +@comment BSD: Operation not supported +@deftypevr Macro int EOPNOTSUPP +@comment errno 45 @c DO NOT REMOVE +The operation you requested is not supported. Some socket functions +don't make sense for all types of sockets, and others may not be +implemented for all communications protocols. In the GNU system, this +error can happen for many calls when the object does not support the +particular operation; it is a generic indication that the server knows +nothing to do for that call. +@end deftypevr + +@comment errno.h +@comment BSD: Protocol family not supported +@deftypevr Macro int EPFNOSUPPORT +@comment errno 46 @c DO NOT REMOVE +The socket communications protocol family you requested is not supported. +@end deftypevr + +@comment errno.h +@comment BSD: Address family not supported by protocol family +@deftypevr Macro int EAFNOSUPPORT +@comment errno 47 @c DO NOT REMOVE +The address family specified for a socket is not supported; it is +inconsistent with the protocol being used on the socket. @xref{Sockets}. +@end deftypevr + +@comment errno.h +@comment BSD: Address already in use +@deftypevr Macro int EADDRINUSE +@comment errno 48 @c DO NOT REMOVE +The requested socket address is already in use. @xref{Socket Addresses}. +@end deftypevr + +@comment errno.h +@comment BSD: Can't assign requested address +@deftypevr Macro int EADDRNOTAVAIL +@comment errno 49 @c DO NOT REMOVE +The requested socket address is not available; for example, you tried +to give a socket a name that doesn't match the local host name. +@xref{Socket Addresses}. +@end deftypevr + +@comment errno.h +@comment BSD: Network is down +@deftypevr Macro int ENETDOWN +@comment errno 50 @c DO NOT REMOVE +A socket operation failed because the network was down. +@end deftypevr + +@comment errno.h +@comment BSD: Network is unreachable +@deftypevr Macro int ENETUNREACH +@comment errno 51 @c DO NOT REMOVE +A socket operation failed because the subnet containing the remote host +was unreachable. +@end deftypevr + +@comment errno.h +@comment BSD: Network dropped connection on reset +@deftypevr Macro int ENETRESET +@comment errno 52 @c DO NOT REMOVE +A network connection was reset because the remote host crashed. +@end deftypevr + +@comment errno.h +@comment BSD: Software caused connection abort +@deftypevr Macro int ECONNABORTED +@comment errno 53 @c DO NOT REMOVE +A network connection was aborted locally. +@end deftypevr + +@comment errno.h +@comment BSD: Connection reset by peer +@deftypevr Macro int ECONNRESET +@comment errno 54 @c DO NOT REMOVE +A network connection was closed for reasons outside the control of the +local host, such as by the remote machine rebooting or an unrecoverable +protocol violation. +@end deftypevr + +@comment errno.h +@comment BSD: No buffer space available +@deftypevr Macro int ENOBUFS +@comment errno 55 @c DO NOT REMOVE +The kernel's buffers for I/O operations are all in use. In GNU, this +error is always synonymous with @code{ENOMEM}; you may get one or the +other from network operations. +@end deftypevr + +@comment errno.h +@comment BSD: Socket is already connected +@deftypevr Macro int EISCONN +@comment errno 56 @c DO NOT REMOVE +You tried to connect a socket that is already connected. +@xref{Connecting}. +@end deftypevr + +@comment errno.h +@comment BSD: Socket is not connected +@deftypevr Macro int ENOTCONN +@comment errno 57 @c DO NOT REMOVE +The socket is not connected to anything. You get this error when you +try to transmit data over a socket, without first specifying a +destination for the data. For a connectionless socket (for datagram +protocols, such as UDP), you get @code{EDESTADDRREQ} instead. +@end deftypevr + +@comment errno.h +@comment BSD: Destination address required +@deftypevr Macro int EDESTADDRREQ +@comment errno 39 @c DO NOT REMOVE +No default destination address was set for the socket. You get this +error when you try to transmit data over a connectionless socket, +without first specifying a destination for the data with @code{connect}. +@end deftypevr + +@comment errno.h +@comment BSD: Can't send after socket shutdown +@deftypevr Macro int ESHUTDOWN +@comment errno 58 @c DO NOT REMOVE +The socket has already been shut down. +@end deftypevr + +@comment errno.h +@comment BSD: Too many references: can't splice +@deftypevr Macro int ETOOMANYREFS +@comment errno 59 @c DO NOT REMOVE +??? +@end deftypevr + +@comment errno.h +@comment BSD: Connection timed out +@deftypevr Macro int ETIMEDOUT +@comment errno 60 @c DO NOT REMOVE +A socket operation with a specified timeout received no response during +the timeout period. +@end deftypevr + +@comment errno.h +@comment BSD: Connection refused +@deftypevr Macro int ECONNREFUSED +@comment errno 61 @c DO NOT REMOVE +A remote host refused to allow the network connection (typically because +it is not running the requested service). +@end deftypevr + +@comment errno.h +@comment BSD: Too many levels of symbolic links +@deftypevr Macro int ELOOP +@comment errno 62 @c DO NOT REMOVE +Too many levels of symbolic links were encountered in looking up a file name. +This often indicates a cycle of symbolic links. +@end deftypevr + +@comment errno.h +@comment POSIX.1: File name too long +@deftypevr Macro int ENAMETOOLONG +@comment errno 63 @c DO NOT REMOVE +Filename too long (longer than @code{PATH_MAX}; @pxref{Limits for +Files}) or host name too long (in @code{gethostname} or +@code{sethostname}; @pxref{Host Identification}). +@end deftypevr + +@comment errno.h +@comment BSD: Host is down +@deftypevr Macro int EHOSTDOWN +@comment errno 64 @c DO NOT REMOVE +The remote host for a requested network connection is down. +@end deftypevr + +@comment errno.h +@comment BSD: No route to host +@deftypevr Macro int EHOSTUNREACH +@comment errno 65 @c DO NOT REMOVE +The remote host for a requested network connection is not reachable. +@end deftypevr + +@comment errno.h +@comment POSIX.1: Directory not empty +@deftypevr Macro int ENOTEMPTY +@comment errno 66 @c DO NOT REMOVE +Directory not empty, where an empty directory was expected. Typically, +this error occurs when you are trying to delete a directory. +@end deftypevr + +@comment errno.h +@comment BSD: Too many processes +@deftypevr Macro int EPROCLIM +@comment errno 67 @c DO NOT REMOVE +This means that the per-user limit on new process would be exceeded by +an attempted @code{fork}. @xref{Limits on Resources}, for details on +the @code{RLIMIT_NPROC} limit. +@end deftypevr + +@comment errno.h +@comment BSD: Too many users +@deftypevr Macro int EUSERS +@comment errno 68 @c DO NOT REMOVE +The file quota system is confused because there are too many users. +@c This can probably happen in a GNU system when using NFS. +@end deftypevr + +@comment errno.h +@comment BSD: Disc quota exceeded +@deftypevr Macro int EDQUOT +@comment errno 69 @c DO NOT REMOVE +The user's disk quota was exceeded. +@end deftypevr + +@comment errno.h +@comment BSD: Stale NFS file handle +@deftypevr Macro int ESTALE +@comment errno 70 @c DO NOT REMOVE +Stale NFS file handle. This indicates an internal confusion in the NFS +system which is due to file system rearrangements on the server host. +Repairing this condition usually requires unmounting and remounting +the NFS file system on the local host. +@end deftypevr + +@comment errno.h +@comment BSD: Too many levels of remote in path +@deftypevr Macro int EREMOTE +@comment errno 71 @c DO NOT REMOVE +An attempt was made to NFS-mount a remote file system with a file name that +already specifies an NFS-mounted file. +(This is an error on some operating systems, but we expect it to work +properly on the GNU system, making this error code impossible.) +@end deftypevr + +@comment errno.h +@comment BSD: RPC struct is bad +@deftypevr Macro int EBADRPC +@comment errno 72 @c DO NOT REMOVE +??? +@end deftypevr + +@comment errno.h +@comment BSD: RPC version wrong +@deftypevr Macro int ERPCMISMATCH +@comment errno 73 @c DO NOT REMOVE +??? +@end deftypevr + +@comment errno.h +@comment BSD: RPC program not available +@deftypevr Macro int EPROGUNAVAIL +@comment errno 74 @c DO NOT REMOVE +??? +@end deftypevr + +@comment errno.h +@comment BSD: RPC program version wrong +@deftypevr Macro int EPROGMISMATCH +@comment errno 75 @c DO NOT REMOVE +??? +@end deftypevr + +@comment errno.h +@comment BSD: RPC bad procedure for program +@deftypevr Macro int EPROCUNAVAIL +@comment errno 76 @c DO NOT REMOVE +??? +@end deftypevr + +@comment errno.h +@comment POSIX.1: No locks available +@deftypevr Macro int ENOLCK +@comment errno 77 @c DO NOT REMOVE +No locks available. This is used by the file locking facilities; see +@ref{File Locks}. This error is never generated by the GNU system, but +it can result from an operation to an NFS server running another +operating system. +@end deftypevr + +@comment errno.h +@comment BSD: Inappropriate file type or format +@deftypevr Macro int EFTYPE +@comment errno 79 @c DO NOT REMOVE +Inappropriate file type or format. The file was the wrong type for the +operation, or a data file had the wrong format. + +On some systems @code{chmod} returns this error if you try to set the +sticky bit on a non-directory file; @pxref{Setting Permissions}. +@end deftypevr + +@comment errno.h +@comment BSD: Authentication error +@deftypevr Macro int EAUTH +@comment errno 80 @c DO NOT REMOVE +??? +@end deftypevr + +@comment errno.h +@comment BSD: Need authenticator +@deftypevr Macro int ENEEDAUTH +@comment errno 81 @c DO NOT REMOVE +??? +@end deftypevr + +@comment errno.h +@comment POSIX.1: Function not implemented +@deftypevr Macro int ENOSYS +@comment errno 78 @c DO NOT REMOVE +Function not implemented. Some functions have commands or options defined +that might not be supported in all implementations, and this is the kind +of error you get if you request them and they are not supported. +@end deftypevr + +@comment errno.h +@comment GNU: Inappropriate operation for background process +@deftypevr Macro int EBACKGROUND +@comment errno 100 @c DO NOT REMOVE +In the GNU system, servers supporting the @code{term} protocol return +this error for certain operations when the caller is not in the +foreground process group of the terminal. Users do not usually see this +error because functions such as @code{read} and @code{write} translate +it into a @code{SIGTTIN} or @code{SIGTTOU} signal. @xref{Job Control}, +for information on process groups and these signals. +@end deftypevr + +@comment errno.h +@comment GNU: Translator died +@deftypevr Macro int EDIED +@comment errno 101 @c DO NOT REMOVE +In the GNU system, opening a file returns this error when the file is +translated by a program and the translator program dies while starting +up, before it has connected to the file. +@end deftypevr + +@comment errno.h +@comment GNU: ? +@deftypevr Macro int ED +@comment errno 102 @c DO NOT REMOVE +The experienced user will know what is wrong. +@end deftypevr + +@comment errno.h +@comment GNU: You really blew it this time +@deftypevr Macro int EGREGIOUS +@comment errno 103 @c DO NOT REMOVE +You did @strong{what}? +@end deftypevr + +@comment errno.h +@comment GNU: Computer bought the farm +@deftypevr Macro int EIEIO +@comment errno 104 @c DO NOT REMOVE +Go home and have a glass of warm, dairy-fresh milk. +@end deftypevr + +@comment errno.h +@comment GNU: Gratuitous error +@deftypevr Macro int EGRATUITOUS +@comment errno 105 @c DO NOT REMOVE +This error code has no purpose. +@end deftypevr + + +@node Error Messages, , Error Codes, Error Reporting +@section Error Messages + +The library has functions and variables designed to make it easy for +your program to report informative error messages in the customary +format about the failure of a library call. The functions +@code{strerror} and @code{perror} give you the standard error message +for a given error code; the variable +@w{@code{program_invocation_short_name}} gives you convenient access to the +name of the program that encountered the error. + +@comment string.h +@comment ANSI +@deftypefun {char *} strerror (int @var{errnum}) +The @code{strerror} function maps the error code (@pxref{Checking for +Errors}) specified by the @var{errnum} argument to a descriptive error +message string. The return value is a pointer to this string. + +The value @var{errnum} normally comes from the variable @code{errno}. + +You should not modify the string returned by @code{strerror}. Also, if +you make subsequent calls to @code{strerror}, the string might be +overwritten. (But it's guaranteed that no library function ever calls +@code{strerror} behind your back.) + +The function @code{strerror} is declared in @file{string.h}. +@end deftypefun + +@comment stdio.h +@comment ANSI +@deftypefun void perror (const char *@var{message}) +This function prints an error message to the stream @code{stderr}; +see @ref{Standard Streams}. + +If you call @code{perror} with a @var{message} that is either a null +pointer or an empty string, @code{perror} just prints the error message +corresponding to @code{errno}, adding a trailing newline. + +If you supply a non-null @var{message} argument, then @code{perror} +prefixes its output with this string. It adds a colon and a space +character to separate the @var{message} from the error string corresponding +to @code{errno}. + +The function @code{perror} is declared in @file{stdio.h}. +@end deftypefun + +@code{strerror} and @code{perror} produce the exact same message for any +given error code; the precise text varies from system to system. On the +GNU system, the messages are fairly short; there are no multi-line +messages or embedded newlines. Each error message begins with a capital +letter and does not include any terminating punctuation. + +@strong{Compatibility Note:} The @code{strerror} function is a new +feature of ANSI C. Many older C systems do not support this function +yet. + +@cindex program name +@cindex name of running program +Many programs that don't read input from the terminal are designed to +exit if any system call fails. By convention, the error message from +such a program should start with the program's name, sans directories. +You can find that name in the variable +@code{program_invocation_short_name}; the full file name is stored the +variable @code{program_invocation_name}: + +@comment errno.h +@comment GNU +@deftypevar {char *} program_invocation_name +This variable's value is the name that was used to invoke the program +running in the current process. It is the same as @code{argv[0]}. Note +that this is not necessarily a useful file name; often it contains no +directory names. @xref{Program Arguments}. +@end deftypevar + +@comment errno.h +@comment GNU +@deftypevar {char *} program_invocation_short_name +This variable's value is the name that was used to invoke the program +running in the current process, with directory names removed. (That is +to say, it is the same as @code{program_invocation_name} minus +everything up to the last slash, if any.) +@end deftypevar + +The library initialization code sets up both of these variables before +calling @code{main}. + +@strong{Portability Note:} These two variables are GNU extensions. If +you want your program to work with non-GNU libraries, you must save the +value of @code{argv[0]} in @code{main}, and then strip off the directory +names yourself. We added these extensions to make it possible to write +self-contained error-reporting subroutines that require no explicit +cooperation from @code{main}. + +Here is an example showing how to handle failure to open a file +correctly. The function @code{open_sesame} tries to open the named file +for reading and returns a stream if successful. The @code{fopen} +library function returns a null pointer if it couldn't open the file for +some reason. In that situation, @code{open_sesame} constructs an +appropriate error message using the @code{strerror} function, and +terminates the program. If we were going to make some other library +calls before passing the error code to @code{strerror}, we'd have to +save it in a local variable instead, because those other library +functions might overwrite @code{errno} in the meantime. + +@smallexample +#include <errno.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> + +FILE * +open_sesame (char *name) +@{ + FILE *stream; + + errno = 0; + stream = fopen (name, "r"); + if (stream == NULL) + @{ + fprintf (stderr, "%s: Couldn't open file %s; %s\n", + program_invocation_short_name, name, strerror (errno)); + exit (EXIT_FAILURE); + @} + else + return stream; +@} +@end smallexample + |