path: root/man3/errno.3

.\" Copyright (c) 1996 Andries Brouwer (aeb@cwi.nl)
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
.\" USA.
.\"
.\" 5 Oct 2002, Modified by Michael Kerrisk <mtk-manpages@gmx.net>
.\" 	Updated for POSIX 1003.1 2001
.\" 2004-12-17 Martin Schulze <joey@infodrom.org>, mtk
.\"	Removed errno declaration prototype, added notes
.\"
.TH ERRNO 3 2004-12-17 "" "Library functions"
.SH NAME
errno \- number of last error
.SH SYNOPSIS
.B #include <errno.h>
.\".sp
.\".BI "extern int " errno ;
.SH DESCRIPTION
The 
.I <errno.h>
header file defines the integer variable
.BR errno ,
which is set by system calls and some library functions in the event
of an error to indicate what went wrong.
Its value is significant only when the call
returned an error (usually \-1), and a function that does succeed
is allowed to change
.BR errno .

Sometimes, when \-1 is also a valid successful return value
one has to zero
.B errno
before the call in order to detect possible errors.

\fBerrno\fR is defined by the ISO C standard to be a modifiable lvalue
of type \fBint\fR, and must not be explicitly declared; \fBerrno\fR
may be a macro.  \fBerrno\fR is thread-local; setting it in one thread
does not affect its value in any other thread.

Valid error numbers are all non-zero; \fBerrno\fR is never set to zero
by any library function.  All the error names specified by POSIX.1
must have distinct values, with the exception of
.B EAGAIN
and 
.BR EWOULDBLOCK ,
which may be the same.

.\" FIXME EILSEQ is in C99.
POSIX.1 (2001 edition) lists the following symbolic error names.  Of
these, \fBEDOM\fR and \fBERANGE\fR are in the ISO C standard.  ISO C
Amendment 1 defines the additional error number \fBEILSEQ\fR for
coding errors in multibyte or wide characters.

.\" FIXME The following list is far from complete
.TP
.B E2BIG
Arg list too long
.TP
.B EACCES
Permission denied
.TP
.B EADDRINUSE
Address in use
.TP
.B EADDRNOTAVAIL
Address not available
.TP
.B EAFNOSUPPORT
Address family not supported
.TP
.B EAGAIN
Resource temporarily unavailable
.TP
.B EALREADY
Connection already in progress
.TP
.B EBADF
Bad file descriptor
.TP
.B EBADMSG
Bad message
.TP
.B EBUSY
Resource busy
.TP
.B ECANCELED
Operation canceled
.TP
.B ECHILD
No child processes
.TP
.B ECONNABORTED
Connection aborted
.TP
.B ECONNREFUSED
Connection refused
.TP
.B ECONNRESET
Connection reset
.TP
.B EDEADLK
Resource deadlock avoided
.TP
.B EDESTADDRREQ
Destination address required
.TP
.B EDOM
Domain error
.TP
.B EDQUOT
Reserved
.TP
.B EEXIST
File exists
.TP
.B EFAULT
Bad address
.TP
.B EFBIG
File too large
.TP
.B EHOSTUNREACH
Host is unreachable
.TP
.B EIDRM
Identifier removed
.TP
.B EILSEQ
Illegal byte sequence
.TP
.B EINPROGRESS
Operation in progress
.TP
.B EINTR
Interrupted function call
.TP
.B EINVAL
Invalid argument
.TP
.B EIO
Input/output error
.TP
.B EISCONN
Socket is connected
.TP
.B EISDIR
Is a directory
.TP
.B ELOOP
Too many levels of symbolic links
.TP
.B EMFILE
Too many open files
.TP
.B EMLINK
Too many links
.TP
.B EMSGSIZE
Inappropriate message buffer length
.TP
.B EMULTIHOP
Reserved
.TP
.B ENAMETOOLONG
Filename too long
.TP
.B ENETDOWN
Network is down
.TP
.B ENETRESET
Connection aborted by network
.TP
.B ENETUNREACH
Network unreachable
.TP
.B ENFILE
Too many open files in system
.TP
.B ENOBUFS
No buffer space available
.\" ENODATA is part of XSR option
.TP
.B ENODATA
No message is available on the STREAM head read queue
.TP
.B ENODEV
No such device
.TP
.B ENOENT
No such file or directory
.TP
.B ENOEXEC
Exec format error
.TP
.B ENOLCK
No locks available
.TP
.B ENOLINK
Reserved
.TP
.B ENOMEM
Not enough space
.TP
.B ENOMSG
No message of the desired type
.TP
.B ENOPROTOOPT
Protocol not available
.TP
.B ENOSPC
No space left on device
.\" ENOSR is part of XSR option
.TP
.B ENOSR
No STREAM resources
.\" ENOSTR is part of XSR option
.TP
.B ENOSTR
Not a STREAM
.TP
.B ENOSYS
Function not implemented
.TP
.B ENOTCONN
The socket is not connected
.TP
.B ENOTDIR
Not a directory
.TP
.B ENOTEMPTY
Directory not empty
.TP
.B ENOTSOCK
Not a socket
.TP
.B ENOTSUP
Not supported
.TP
.B ENOTTY
Inappropriate I/O control operation
.TP
.B ENXIO
No such device or address
.TP
.B EOPNOTSUPP
Operation not supported on socket
.TP
.B EOVERFLOW
Value too large to be stored in data type
.TP
.B EPERM
Operation not permitted
.TP
.B EPIPE
Broken pipe
.TP
.B EPROTO
Protocol error
.TP
.B EPROTONOSUPPORT
Protocol not supported
.TP
.B EPROTOTYPE
Protocol wrong type for socket
.TP
.B ERANGE
Result too large
.TP
.B EROFS
Read-only file system
.TP
.B ESPIPE
Invalid seek
.TP
.B ESRCH
No such process
.TP
.B ESTALE
Stale file handle
.\" Can occur for NFS and for other file systems
.\" ETIME is part of XSR option
.TP
.B ETIME
STREAM 
.BR ioctl () 
timeout
.TP
.B ETIMEDOUT
Operation timed out
.TP
.B ETXTBSY
Text file busy
.TP
.B EWOULDBLOCK
Operation would block (may be same value as
.BR EAGAIN )
.TP
.B EXDEV
Improper link
.SH NOTES
A common mistake is to do
.RS
.nf

if (somecall() == \-1) {
    printf("somecall() failed\en");
    if (errno == ...) { ... }
}

.fi
.RE
where
.I errno
no longer needs to have the value it had upon return from
.IR somecall ()
(i.e., it may have been changed by the
.BR printf ()).
If the value of
.I errno
should be preserved across a library call, it must be saved:
.RS
.nf

if (somecall() == \-1) {
    int errsv = errno;
    printf("somecall() failed\en");
    if (errsv == ...) { ... }
}
.fi
.RE
.PP
It was common in traditional C to declare
.I errno
manually
(i.e., 
.IR "extern int errno" )
instead of including
.IR <errno.h> .
.BR "Do not do this" .
It will not work with modern versions of the C library.
However, on (very) old Unix systems, there may be no
.I <errno.h>
and the declaration is needed.
.SH "SEE ALSO"
.BR perror (3),
.BR strerror (3)