diff options
Diffstat (limited to 'REORG.TODO/manual/errno.texi')
| -rw-r--r-- | REORG.TODO/manual/errno.texi | 1701 |
1 files changed, 1701 insertions, 0 deletions
diff --git a/REORG.TODO/manual/errno.texi b/REORG.TODO/manual/errno.texi new file mode 100644 index 0000000000..f4c07f0683 --- /dev/null +++ b/REORG.TODO/manual/errno.texi @@ -0,0 +1,1701 @@ +@node Error Reporting, Memory, Introduction, Top +@chapter Error Reporting +@c %MENU% How library functions report errors +@cindex error reporting +@cindex reporting errors +@cindex error codes +@cindex status codes + +Many functions in @theglibc{} 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 ISO +@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 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:} @w{ISO 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_location ()}}. In fact, that is +what it is +on @gnulinuxhurdsystems{}. @Theglibc{}, on each system, 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. + +Except on @gnuhurdsystems{}, 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 @gnuhurdsystems{}, 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 @gnusystems{}, but they can occur using @theglibc{} +on other systems. + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int EPERM +@errno{EPERM, 1, 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 +@deftypevr Macro int ENOENT +@errno{ENOENT, 2, 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 +@deftypevr Macro int ESRCH +@errno{ESRCH, 3, No such process} +No process matches the specified process ID. +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int EINTR +@errno{EINTR, 4, Interrupted system call} +An asynchronous signal occurred 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 +@deftypevr Macro int EIO +@errno{EIO, 5, Input/output error} +Usually used for physical read or write errors. +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int ENXIO +@errno{ENXIO, 6, 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 +@deftypevr Macro int E2BIG +@errno{E2BIG, 7, 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 on +@gnuhurdsystems{}. +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int ENOEXEC +@errno{ENOEXEC, 8, Exec format error} +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 +@deftypevr Macro int EBADF +@errno{EBADF, 9, 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 +@deftypevr Macro int ECHILD +@errno{ECHILD, 10, 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 +@deftypevr Macro int EDEADLK +@errno{EDEADLK, 11, Resource 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 +@deftypevr Macro int ENOMEM +@errno{ENOMEM, 12, Cannot allocate memory} +The system cannot allocate more virtual memory +because its capacity is full. +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int EACCES +@errno{EACCES, 13, Permission denied} +The file permissions do not allow the attempted operation. +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int EFAULT +@errno{EFAULT, 14, Bad address} +An invalid pointer was detected. +On @gnuhurdsystems{}, this error never happens; you get a signal instead. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int ENOTBLK +@errno{ENOTBLK, 15, Block device required} +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 +@deftypevr Macro int EBUSY +@errno{EBUSY, 16, Device or 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 +@deftypevr Macro int EEXIST +@errno{EEXIST, 17, 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 +@deftypevr Macro int EXDEV +@errno{EXDEV, 18, Invalid cross-device link} +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 +@deftypevr Macro int ENODEV +@errno{ENODEV, 19, No such device} +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 +@deftypevr Macro int ENOTDIR +@errno{ENOTDIR, 20, Not a directory} +A file that isn't a directory was specified when a directory is required. +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int EISDIR +@errno{EISDIR, 21, 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 +@deftypevr Macro int EINVAL +@errno{EINVAL, 22, 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 +@deftypevr Macro int EMFILE +@errno{EMFILE, 24, Too many open files} +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 +@deftypevr Macro int ENFILE +@errno{ENFILE, 23, Too many open files in system} +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 on @gnuhurdsystems{}. +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int ENOTTY +@errno{ENOTTY, 25, Inappropriate ioctl for device} +Inappropriate I/O control operation, such as trying to set terminal +modes on an ordinary file. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int ETXTBSY +@errno{ETXTBSY, 26, Text file busy} +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 on @gnuhurdsystems{}; the text is copied as necessary. +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int EFBIG +@errno{EFBIG, 27, File too large} +The size of a file would be larger than allowed by the system. +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int ENOSPC +@errno{ENOSPC, 28, No space left on device} +Write operation on a file failed because the +disk is full. +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int ESPIPE +@errno{ESPIPE, 29, Illegal seek} +Invalid seek operation (such as on a pipe). +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int EROFS +@errno{EROFS, 30, Read-only file system} +An attempt was made to modify something on a read-only file system. +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int EMLINK +@errno{EMLINK, 31, 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 +@deftypevr Macro int EPIPE +@errno{EPIPE, 32, 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 ISO +@deftypevr Macro int EDOM +@errno{EDOM, 33, Numerical argument out of domain} +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 ISO +@deftypevr Macro int ERANGE +@errno{ERANGE, 34, Numerical result out of range} +Used by mathematical functions when the result value is +not representable because of overflow or underflow. +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int EAGAIN +@errno{EAGAIN, 35, 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 @theglibc{}. + +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 many older Unix 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 +@deftypevr Macro int EWOULDBLOCK +@errno{EWOULDBLOCK, EAGAIN, Operation would block} +In @theglibc{}, 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 +@deftypevr Macro int EINPROGRESS +@errno{EINPROGRESS, 36, Operation now in progress} +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 +@deftypevr Macro int EALREADY +@errno{EALREADY, 37, Operation already in progress} +An operation is already in progress on an object that has non-blocking +mode selected. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int ENOTSOCK +@errno{ENOTSOCK, 38, Socket operation on non-socket} +A file that isn't a socket was specified when a socket is required. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int EMSGSIZE +@errno{EMSGSIZE, 40, Message too long} +The size of a message sent on a socket was larger than the supported +maximum size. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int EPROTOTYPE +@errno{EPROTOTYPE, 41, Protocol wrong type for socket} +The socket type does not support the requested communications protocol. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int ENOPROTOOPT +@errno{ENOPROTOOPT, 42, Protocol not available} +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 +@deftypevr Macro int EPROTONOSUPPORT +@errno{EPROTONOSUPPORT, 43, Protocol not supported} +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 +@deftypevr Macro int ESOCKTNOSUPPORT +@errno{ESOCKTNOSUPPORT, 44, Socket type not supported} +The socket type is not supported. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int EOPNOTSUPP +@errno{EOPNOTSUPP, 45, Operation not supported} +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. On @gnuhurdsystems{}, 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 +@deftypevr Macro int EPFNOSUPPORT +@errno{EPFNOSUPPORT, 46, Protocol family not supported} +The socket communications protocol family you requested is not supported. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int EAFNOSUPPORT +@errno{EAFNOSUPPORT, 47, Address family not supported by protocol} +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 +@deftypevr Macro int EADDRINUSE +@errno{EADDRINUSE, 48, Address already in use} +The requested socket address is already in use. @xref{Socket Addresses}. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int EADDRNOTAVAIL +@errno{EADDRNOTAVAIL, 49, Cannot assign requested address} +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 +@deftypevr Macro int ENETDOWN +@errno{ENETDOWN, 50, Network is down} +A socket operation failed because the network was down. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int ENETUNREACH +@errno{ENETUNREACH, 51, Network is unreachable} +A socket operation failed because the subnet containing the remote host +was unreachable. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int ENETRESET +@errno{ENETRESET, 52, Network dropped connection on reset} +A network connection was reset because the remote host crashed. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int ECONNABORTED +@errno{ECONNABORTED, 53, Software caused connection abort} +A network connection was aborted locally. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int ECONNRESET +@errno{ECONNRESET, 54, Connection reset by peer} +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 +@deftypevr Macro int ENOBUFS +@errno{ENOBUFS, 55, No buffer space available} +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 +@deftypevr Macro int EISCONN +@errno{EISCONN, 56, Transport endpoint is already connected} +You tried to connect a socket that is already connected. +@xref{Connecting}. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int ENOTCONN +@errno{ENOTCONN, 57, Transport endpoint is not connected} +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 +@deftypevr Macro int EDESTADDRREQ +@errno{EDESTADDRREQ, 39, Destination address required} +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 +@deftypevr Macro int ESHUTDOWN +@errno{ESHUTDOWN, 58, Cannot send after transport endpoint shutdown} +The socket has already been shut down. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int ETOOMANYREFS +@errno{ETOOMANYREFS, 59, Too many references: cannot splice} +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int ETIMEDOUT +@errno{ETIMEDOUT, 60, Connection timed out} +A socket operation with a specified timeout received no response during +the timeout period. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int ECONNREFUSED +@errno{ECONNREFUSED, 61, Connection refused} +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 +@deftypevr Macro int ELOOP +@errno{ELOOP, 62, Too many levels of symbolic links} +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 +@deftypevr Macro int ENAMETOOLONG +@errno{ENAMETOOLONG, 63, File name too long} +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 +@deftypevr Macro int EHOSTDOWN +@errno{EHOSTDOWN, 64, Host is down} +The remote host for a requested network connection is down. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int EHOSTUNREACH +@errno{EHOSTUNREACH, 65, No route to host} +The remote host for a requested network connection is not reachable. +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int ENOTEMPTY +@errno{ENOTEMPTY, 66, Directory not empty} +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 +@deftypevr Macro int EPROCLIM +@errno{EPROCLIM, 67, Too many processes} +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 +@deftypevr Macro int EUSERS +@errno{EUSERS, 68, Too many users} +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 +@deftypevr Macro int EDQUOT +@errno{EDQUOT, 69, Disk quota exceeded} +The user's disk quota was exceeded. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int ESTALE +@errno{ESTALE, 70, Stale file handle} +This indicates an internal confusion in the +file system which is due to file system rearrangements on the server host +for NFS file systems or corruption in other file systems. +Repairing this condition usually requires unmounting, possibly repairing +and remounting the file system. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int EREMOTE +@errno{EREMOTE, 71, Object is remote} +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 @gnuhurdsystems{}, making this error code impossible.) +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int EBADRPC +@errno{EBADRPC, 72, RPC struct is bad} +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int ERPCMISMATCH +@errno{ERPCMISMATCH, 73, RPC version wrong} +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int EPROGUNAVAIL +@errno{EPROGUNAVAIL, 74, RPC program not available} +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int EPROGMISMATCH +@errno{EPROGMISMATCH, 75, RPC program version wrong} +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int EPROCUNAVAIL +@errno{EPROCUNAVAIL, 76, RPC bad procedure for program} +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int ENOLCK +@errno{ENOLCK, 77, No locks available} +This is used by the file locking facilities; see +@ref{File Locks}. This error is never generated by @gnuhurdsystems{}, but +it can result from an operation to an NFS server running another +operating system. +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int EFTYPE +@errno{EFTYPE, 79, 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 +@deftypevr Macro int EAUTH +@errno{EAUTH, 80, Authentication error} +@end deftypevr + +@comment errno.h +@comment BSD +@deftypevr Macro int ENEEDAUTH +@errno{ENEEDAUTH, 81, Need authenticator} +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int ENOSYS +@errno{ENOSYS, 78, Function not implemented} +This indicates that the function called is +not implemented at all, either in the C library itself or in the +operating system. When you get this error, you can be sure that this +particular function will always fail with @code{ENOSYS} unless you +install a new version of the C library or the operating system. +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int ENOTSUP +@errno{ENOTSUP, 118, Not supported} +A function returns this error when certain parameter +values are valid, but the functionality they request is not available. +This can mean that the function does not implement a particular command +or option value or flag bit at all. For functions that operate on some +object given in a parameter, such as a file descriptor or a port, it +might instead mean that only @emph{that specific object} (file +descriptor, port, etc.) is unable to support the other parameters given; +different file descriptors might support different ranges of parameter +values. + +If the entire function is not available at all in the implementation, +it returns @code{ENOSYS} instead. +@end deftypevr + +@comment errno.h +@comment ISO +@deftypevr Macro int EILSEQ +@errno{EILSEQ, 106, Invalid or incomplete multibyte or wide character} +While decoding a multibyte character the function came along an invalid +or an incomplete sequence of bytes or the given wide character is invalid. +@end deftypevr + +@comment errno.h +@comment GNU +@deftypevr Macro int EBACKGROUND +@errno{EBACKGROUND, 100, Inappropriate operation for background process} +On @gnuhurdsystems{}, 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 +@deftypevr Macro int EDIED +@errno{EDIED, 101, Translator died} +On @gnuhurdsystems{}, 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 +@errno{ED, 102, ?} +The experienced user will know what is wrong. +@c This error code is a joke. Its perror text is part of the joke. +@c Don't change it. +@end deftypevr + +@comment errno.h +@comment GNU +@deftypevr Macro int EGREGIOUS +@errno{EGREGIOUS, 103, You really blew it this time} +You did @strong{what}? +@end deftypevr + +@comment errno.h +@comment GNU +@deftypevr Macro int EIEIO +@errno{EIEIO, 104, Computer bought the farm} +Go home and have a glass of warm, dairy-fresh milk. +@end deftypevr + +@comment errno.h +@comment GNU +@deftypevr Macro int EGRATUITOUS +@errno{EGRATUITOUS, 105, Gratuitous error} +This error code has no purpose. +@end deftypevr + +@comment errno.h +@comment XOPEN +@deftypevr Macro int EBADMSG +@errno{EBADMSG, 107, Bad message} +@end deftypevr + +@comment errno.h +@comment XOPEN +@deftypevr Macro int EIDRM +@errno{EIDRM, 108, Identifier removed} +@end deftypevr + +@comment errno.h +@comment XOPEN +@deftypevr Macro int EMULTIHOP +@errno{EMULTIHOP, 109, Multihop attempted} +@end deftypevr + +@comment errno.h +@comment XOPEN +@deftypevr Macro int ENODATA +@errno{ENODATA, 110, No data available} +@end deftypevr + +@comment errno.h +@comment XOPEN +@deftypevr Macro int ENOLINK +@errno{ENOLINK, 111, Link has been severed} +@end deftypevr + +@comment errno.h +@comment XOPEN +@deftypevr Macro int ENOMSG +@errno{ENOMSG, 112, No message of desired type} +@end deftypevr + +@comment errno.h +@comment XOPEN +@deftypevr Macro int ENOSR +@errno{ENOSR, 113, Out of streams resources} +@end deftypevr + +@comment errno.h +@comment XOPEN +@deftypevr Macro int ENOSTR +@errno{ENOSTR, 114, Device not a stream} +@end deftypevr + +@comment errno.h +@comment XOPEN +@deftypevr Macro int EOVERFLOW +@errno{EOVERFLOW, 115, Value too large for defined data type} +@end deftypevr + +@comment errno.h +@comment XOPEN +@deftypevr Macro int EPROTO +@errno{EPROTO, 116, Protocol error} +@end deftypevr + +@comment errno.h +@comment XOPEN +@deftypevr Macro int ETIME +@errno{ETIME, 117, Timer expired} +@end deftypevr + +@comment errno.h +@comment POSIX.1 +@deftypevr Macro int ECANCELED +@errno{ECANCELED, 119, Operation canceled} +An asynchronous operation was canceled before it +completed. @xref{Asynchronous I/O}. When you call @code{aio_cancel}, +the normal result is for the operations affected to complete with this +error; @pxref{Cancel AIO Operations}. +@end deftypevr + + +@emph{The following error codes are defined by the Linux/i386 kernel. +They are not yet documented.} + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ERESTART +@errno{ERESTART, ???/85, Interrupted system call should be restarted} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ECHRNG +@errno{ECHRNG, ???/44, Channel number out of range} +@end deftypevr + +@comment errno.h +@comment Obsolete +@deftypevr Macro int EL2NSYNC +@errno{EL2NSYNC, ???/45, Level 2 not synchronized} +@end deftypevr + +@comment errno.h +@comment Obsolete +@deftypevr Macro int EL3HLT +@errno{EL3HLT, ???/46, Level 3 halted} +@end deftypevr + +@comment errno.h +@comment Obsolete +@deftypevr Macro int EL3RST +@errno{EL3RST, ???/47, Level 3 reset} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ELNRNG +@errno{ELNRNG, ???/48, Link number out of range} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int EUNATCH +@errno{EUNATCH, ???/49, Protocol driver not attached} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ENOCSI +@errno{ENOCSI, ???/50, No CSI structure available} +@end deftypevr + +@comment errno.h +@comment Obsolete +@deftypevr Macro int EL2HLT +@errno{EL2HLT, ???/51, Level 2 halted} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int EBADE +@errno{EBADE, ???/52, Invalid exchange} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int EBADR +@errno{EBADR, ???/53, Invalid request descriptor} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int EXFULL +@errno{EXFULL, ???/54, Exchange full} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ENOANO +@errno{ENOANO, ???/55, No anode} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int EBADRQC +@errno{EBADRQC, ???/56, Invalid request code} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int EBADSLT +@errno{EBADSLT, ???/57, Invalid slot} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int EDEADLOCK +@errno{EDEADLOCK, ???/58, File locking deadlock error} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int EBFONT +@errno{EBFONT, ???/59, Bad font file format} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ENONET +@errno{ENONET, ???/64, Machine is not on the network} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ENOPKG +@errno{ENOPKG, ???/65, Package not installed} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int EADV +@errno{EADV, ???/68, Advertise error} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ESRMNT +@errno{ESRMNT, ???/69, Srmount error} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ECOMM +@errno{ECOMM, ???/70, Communication error on send} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int EDOTDOT +@errno{EDOTDOT, ???/73, RFS specific error} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ENOTUNIQ +@errno{ENOTUNIQ, ???/76, Name not unique on network} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int EBADFD +@errno{EBADFD, ???/77, File descriptor in bad state} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int EREMCHG +@errno{EREMCHG, ???/78, Remote address changed} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ELIBACC +@errno{ELIBACC, ???/79, Can not access a needed shared library} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ELIBBAD +@errno{ELIBBAD, ???/80, Accessing a corrupted shared library} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ELIBSCN +@errno{ELIBSCN, ???/81, .lib section in a.out corrupted} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ELIBMAX +@errno{ELIBMAX, ???/82, Attempting to link in too many shared libraries} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ELIBEXEC +@errno{ELIBEXEC, ???/83, Cannot exec a shared library directly} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ESTRPIPE +@errno{ESTRPIPE, ???/86, Streams pipe error} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int EUCLEAN +@errno{EUCLEAN, ???/117, Structure needs cleaning} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ENOTNAM +@errno{ENOTNAM, ???/118, Not a XENIX named type file} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ENAVAIL +@errno{ENAVAIL, ???/119, No XENIX semaphores available} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int EISNAM +@errno{EISNAM, ???/120, Is a named type file} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int EREMOTEIO +@errno{EREMOTEIO, ???/121, Remote I/O error} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int ENOMEDIUM +@errno{ENOMEDIUM, ???/???, No medium found} +@end deftypevr + +@comment errno.h +@comment Linux??? +@deftypevr Macro int EMEDIUMTYPE +@errno{EMEDIUMTYPE, ???/???, Wrong medium type} +@end deftypevr + +@comment errno.h +@comment Linux +@deftypevr Macro int ENOKEY +@errno{ENOKEY, ???/???, Required key not available} +@end deftypevr + +@comment errno.h +@comment Linux +@deftypevr Macro int EKEYEXPIRED +@errno{EKEYEXPIRED, ???/???, Key has expired} +@end deftypevr + +@comment errno.h +@comment Linux +@deftypevr Macro int EKEYREVOKED +@errno{EKEYREVOKED, ???/???, Key has been revoked} +@end deftypevr + +@comment errno.h +@comment Linux +@deftypevr Macro int EKEYREJECTED +@errno{EKEYREJECTED, ???/???, Key was rejected by service} +@end deftypevr + +@comment errno.h +@comment Linux +@deftypevr Macro int EOWNERDEAD +@errno{EOWNERDEAD, ???/???, Owner died} +@end deftypevr + +@comment errno.h +@comment Linux +@deftypevr Macro int ENOTRECOVERABLE +@errno{ENOTRECOVERABLE, ???/???, State not recoverable} +@end deftypevr + +@comment errno.h +@comment Linux +@deftypevr Macro int ERFKILL +@errno{ERFKILL, ???/???, Operation not possible due to RF-kill} +@end deftypevr + +@comment errno.h +@comment Linux +@deftypevr Macro int EHWPOISON +@errno{EHWPOISON, ???/???, Memory page has hardware error} +@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 ISO +@deftypefun {char *} strerror (int @var{errnum}) +@safety{@prelim{}@mtunsafe{@mtasurace{:strerror}}@asunsafe{@ascuheap{} @ascuintl{}}@acunsafe{@acsmem{}}} +@c Calls strerror_r with a static buffer allocated with malloc on the +@c first use. +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 string.h +@comment GNU +@deftypefun {char *} strerror_r (int @var{errnum}, char *@var{buf}, size_t @var{n}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuintl{}}@acunsafe{}} +The @code{strerror_r} function works like @code{strerror} but instead of +returning the error message in a statically allocated buffer shared by +all threads in the process, it returns a private copy for the +thread. This might be either some permanent global data or a message +string in the user supplied buffer starting at @var{buf} with the +length of @var{n} bytes. + +At most @var{n} characters are written (including the NUL byte) so it is +up to the user to select a buffer large enough. + +This function should always be used in multi-threaded programs since +there is no way to guarantee the string returned by @code{strerror} +really belongs to the last call of the current thread. + +The function @code{strerror_r} is a GNU extension and it is declared in +@file{string.h}. +@end deftypefun + +@comment stdio.h +@comment ISO +@deftypefun void perror (const char *@var{message}) +@safety{@prelim{}@mtsafe{@mtasurace{:stderr}}@asunsafe{@asucorrupt{} @ascuintl{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} +@c Besides strerror_r's and some of fprintf's issues, if stderr is not +@c oriented yet, create a new stream with a dup of stderr's fd and write +@c to that instead of stderr, to avoid orienting it. +This function prints an error message to the stream @code{stderr}; +see @ref{Standard Streams}. The orientation of @code{stderr} is not +changed. + +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. With +@theglibc{}, 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. + +@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}. + +This variable is a GNU extension and is declared in @file{errno.h}. +@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.) + +This variable is a GNU extension and is declared in @file{errno.h}. +@end deftypevar + +The library initialization code sets up both of these variables before +calling @code{main}. + +@strong{Portability Note:} 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 +#define _GNU_SOURCE + +#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 + +Using @code{perror} has the advantage that the function is portable and +available on all systems implementing @w{ISO C}. But often the text +@code{perror} generates is not what is wanted and there is no way to +extend or change what @code{perror} does. The GNU coding standard, for +instance, requires error messages to be preceded by the program name and +programs which read some input files should provide information +about the input file name and the line number in case an error is +encountered while reading the file. For these occasions there are two +functions available which are widely used throughout the GNU project. +These functions are declared in @file{error.h}. + +@comment error.h +@comment GNU +@deftypefun void error (int @var{status}, int @var{errnum}, const char *@var{format}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @asuheap{} @asuintl{}}@acsafe{}} +@c Cancellation is disabled throughout the execution. It flushes stdout +@c and then holds a lock on stderr while printing the program name and +@c then running error_tail. The non-wide case just runs vfprintf; the +@c wide case converts the message to an alloca/malloc-allocated buffer +@c with mbsrtowcs, then prints it with vfwprintf. Afterwards, +@c print_errno_message calls strerror_r and fxprintf. +The @code{error} function can be used to report general problems during +program execution. The @var{format} argument is a format string just +like those given to the @code{printf} family of functions. The +arguments required for the format can follow the @var{format} parameter. +Just like @code{perror}, @code{error} also can report an error code in +textual form. But unlike @code{perror} the error value is explicitly +passed to the function in the @var{errnum} parameter. This eliminates +the problem mentioned above that the error reporting function must be +called immediately after the function causing the error since otherwise +@code{errno} might have a different value. + +@code{error} prints first the program name. If the application +defined a global variable @code{error_print_progname} and points it to a +function this function will be called to print the program name. +Otherwise the string from the global variable @code{program_name} is +used. The program name is followed by a colon and a space which in turn +is followed by the output produced by the format string. If the +@var{errnum} parameter is non-zero the format string output is followed +by a colon and a space, followed by the error message for the error code +@var{errnum}. In any case is the output terminated with a newline. + +The output is directed to the @code{stderr} stream. If the +@code{stderr} wasn't oriented before the call it will be narrow-oriented +afterwards. + +The function will return unless the @var{status} parameter has a +non-zero value. In this case the function will call @code{exit} with +the @var{status} value for its parameter and therefore never return. If +@code{error} returns, the global variable @code{error_message_count} is +incremented by one to keep track of the number of errors reported. +@end deftypefun + +@comment error.h +@comment GNU +@deftypefun void error_at_line (int @var{status}, int @var{errnum}, const char *@var{fname}, unsigned int @var{lineno}, const char *@var{format}, @dots{}) +@safety{@prelim{}@mtunsafe{@mtasurace{:error_at_line/error_one_per_line} @mtslocale{}}@asunsafe{@asucorrupt{} @asuheap{} @asuintl{}}@acunsafe{@acucorrupt{/error_one_per_line}}} +@c The error_one_per_line variable is accessed (without any form of +@c synchronization, but since it's an int used once, it should be safe +@c enough) and, if this mode is enabled, static variables used to hold +@c the last printed file name and line number are accessed and modified +@c without synchronization; the update is not atomic and it occurs +@c before disabling cancellation, so it can be interrupted after only +@c one of the two variables is modified. After that, it's very much +@c like error. + +The @code{error_at_line} function is very similar to the @code{error} +function. The only differences are the additional parameters @var{fname} +and @var{lineno}. The handling of the other parameters is identical to +that of @code{error} except that between the program name and the string +generated by the format string additional text is inserted. + +Directly following the program name a colon, followed by the file name +pointed to by @var{fname}, another colon, and the value of @var{lineno} is +printed. + +This additional output of course is meant to be used to locate an error +in an input file (like a programming language source code file etc). + +If the global variable @code{error_one_per_line} is set to a non-zero +value @code{error_at_line} will avoid printing consecutive messages for +the same file and line. Repetition which are not directly following +each other are not caught. + +Just like @code{error} this function only returns if @var{status} is +zero. Otherwise @code{exit} is called with the non-zero value. If +@code{error} returns, the global variable @code{error_message_count} is +incremented by one to keep track of the number of errors reported. +@end deftypefun + +As mentioned above, the @code{error} and @code{error_at_line} functions +can be customized by defining a variable named +@code{error_print_progname}. + +@comment error.h +@comment GNU +@deftypevar {void (*error_print_progname)} (void) +If the @code{error_print_progname} variable is defined to a non-zero +value the function pointed to is called by @code{error} or +@code{error_at_line}. It is expected to print the program name or do +something similarly useful. + +The function is expected to print to the @code{stderr} stream and +must be able to handle whatever orientation the stream has. + +The variable is global and shared by all threads. +@end deftypevar + +@comment error.h +@comment GNU +@deftypevar {unsigned int} error_message_count +The @code{error_message_count} variable is incremented whenever one of +the functions @code{error} or @code{error_at_line} returns. The +variable is global and shared by all threads. +@end deftypevar + +@comment error.h +@comment GNU +@deftypevar int error_one_per_line +The @code{error_one_per_line} variable influences only +@code{error_at_line}. Normally the @code{error_at_line} function +creates output for every invocation. If @code{error_one_per_line} is +set to a non-zero value @code{error_at_line} keeps track of the last +file name and line number for which an error was reported and avoids +directly following messages for the same file and line. This variable +is global and shared by all threads. +@end deftypevar + +@noindent +A program which read some input file and reports errors in it could look +like this: + +@smallexample +@{ + char *line = NULL; + size_t len = 0; + unsigned int lineno = 0; + + error_message_count = 0; + while (! feof_unlocked (fp)) + @{ + ssize_t n = getline (&line, &len, fp); + if (n <= 0) + /* @r{End of file or error.} */ + break; + ++lineno; + + /* @r{Process the line.} */ + @dots{} + + if (@r{Detect error in line}) + error_at_line (0, errval, filename, lineno, + "some error text %s", some_variable); + @} + + if (error_message_count != 0) + error (EXIT_FAILURE, 0, "%u errors found", error_message_count); +@} +@end smallexample + +@code{error} and @code{error_at_line} are clearly the functions of +choice and enable the programmer to write applications which follow the +GNU coding standard. @Theglibc{} additionally contains functions which +are used in BSD for the same purpose. These functions are declared in +@file{err.h}. It is generally advised to not use these functions. They +are included only for compatibility. + +@comment err.h +@comment BSD +@deftypefun void warn (const char *@var{format}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c Just calls vwarn with the va_list. +The @code{warn} function is roughly equivalent to a call like +@smallexample + error (0, errno, format, @r{the parameters}) +@end smallexample +@noindent +except that the global variables @code{error} respects and modifies +are not used. +@end deftypefun + +@comment err.h +@comment BSD +@deftypefun void vwarn (const char *@var{format}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c While holding stderr's recursive lock, it prints the programname, the +@c given message, and the error string with fw?printf's %m. When the +@c stream is wide, convert_and_print converts the format string to an +@c alloca/malloc-created buffer using mbsrtowcs and then calls fwprintf. +The @code{vwarn} function is just like @code{warn} except that the +parameters for the handling of the format string @var{format} are passed +in as a value of type @code{va_list}. +@end deftypefun + +@comment err.h +@comment BSD +@deftypefun void warnx (const char *@var{format}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c Same as warn, but without the strerror translation issues. +The @code{warnx} function is roughly equivalent to a call like +@smallexample + error (0, 0, format, @r{the parameters}) +@end smallexample +@noindent +except that the global variables @code{error} respects and modifies +are not used. The difference to @code{warn} is that no error number +string is printed. +@end deftypefun + +@comment err.h +@comment BSD +@deftypefun void vwarnx (const char *@var{format}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c Same as vwarn, but without the strerror translation issues. +The @code{vwarnx} function is just like @code{warnx} except that the +parameters for the handling of the format string @var{format} are passed +in as a value of type @code{va_list}. +@end deftypefun + +@comment err.h +@comment BSD +@deftypefun void err (int @var{status}, const char *@var{format}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c Same as warn followed by exit. +The @code{err} function is roughly equivalent to a call like +@smallexample + error (status, errno, format, @r{the parameters}) +@end smallexample +@noindent +except that the global variables @code{error} respects and modifies +are not used and that the program is exited even if @var{status} is zero. +@end deftypefun + +@comment err.h +@comment BSD +@deftypefun void verr (int @var{status}, const char *@var{format}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c Same as vwarn followed by exit. +The @code{verr} function is just like @code{err} except that the +parameters for the handling of the format string @var{format} are passed +in as a value of type @code{va_list}. +@end deftypefun + +@comment err.h +@comment BSD +@deftypefun void errx (int @var{status}, const char *@var{format}, @dots{}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c Same as warnx followed by exit. +The @code{errx} function is roughly equivalent to a call like +@smallexample + error (status, 0, format, @r{the parameters}) +@end smallexample +@noindent +except that the global variables @code{error} respects and modifies +are not used and that the program is exited even if @var{status} +is zero. The difference to @code{err} is that no error number +string is printed. +@end deftypefun + +@comment err.h +@comment BSD +@deftypefun void verrx (int @var{status}, const char *@var{format}, va_list @var{ap}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}} +@c Same as vwarnx followed by exit. +The @code{verrx} function is just like @code{errx} except that the +parameters for the handling of the format string @var{format} are passed +in as a value of type @code{va_list}. +@end deftypefun |