initial import

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