.\" 2006-02-09 Kurt Wall, mtk
.\" Added non-POSIX errors
.\"
-.TH ERRNO 3 2016-12-12 "" "Linux Programmer's Manual"
+.TH ERRNO 3 2018-02-02 "" "Linux Programmer's Manual"
.SH NAME
errno \- number of last error
.SH SYNOPSIS
.IR 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 return value of
+.\"
+.SS errno
+The value in
+.I errno
+is significant only when the return value of
the call indicated an error
(i.e., \-1 from most system calls;
\-1 or NULL from most library functions);
.I is
allowed to change
.IR errno .
-.PP
-Valid error numbers are all nonzero;
+The value of
.I errno
-is never set to zero
-by any system call or library function.
+is never set to zero by any system call or library function.
.PP
For some system calls and library functions (e.g.,
.BR getpriority (2)),
.I errno
is thread-local; setting it in one thread
does not affect its value in any other thread.
+.\"
+.SS Error numbers and names
+Valid error numbers are all positive numbers.
+The
+.I <errno.h>
+header file defines symbolic names for each
+of the possible error numbers that may appear in
+.IR errno .
.PP
All the error names specified by POSIX.1
must have distinct values, with the exception of
.BR EWOULDBLOCK ,
which may be the same.
.PP
-.\" The following is now
+The error numbers that correspond to each symbolic name
+vary across UNIX systems,
+and even across different architectures on Linux.
+Therefore, numeric values are not included as part of the list of
+error names below.
+The
+.BR perror (3)
+and
+.BR strerror (3)
+functions can be used to convert these names to
+corresponding textual error messages.
+.PP
+On any particular Linux system,
+one can obtain a list of all symbolic error names and
+the corresponding error numbers using the
+.BR errno (1)
+command (part of the
+.I moreutils
+package):
+.PP
+.in +4n
+.EX
+$ \fBerrno \-l\fP
+EPERM 1 Operation not permitted
+ENOENT 2 No such file or directory
+ESRCH 3 No such process
+EINTR 4 Interrupted system call
+EIO 5 Input/output error
+\&...
+.EE
+.in
+.PP
+The
+.BR errno (1)
+command can also be used to look up individual error numbers and names,
+and to search for errors using strings from the error description,
+as in the following examples:
+.PP
+.in +4n
+.EX
+$ \fBerrno 2\fP
+ENOENT 2 No such file or directory
+$ \fBerrno ESRCH\fP
+ESRCH 3 No such process
+$ \fBerrno \-s permission\fP
+EACCES 13 Permission denied
+.EE
+.in
+.PP
.\" POSIX.1 (2001 edition) lists the following symbolic error names. Of
.\" these, \fBEDOM\fP and \fBERANGE\fP are in the ISO C standard. ISO C
.\" Amendment 1 defines the additional error number \fBEILSEQ\fP for
.\" coding errors in multibyte or wide characters.
.\"
-Below is a list of the symbolic error names that are defined on Linux.
-Some of these are marked
-.IR POSIX.1 ,
-indicating that the name is defined by POSIX.1-2001, or
-.\" FIXME This list should be updated for POSIX.1-2008
-.IR C99 ,
-indicating that the name is defined by C99.
+.SS List of error names
+In the list of the symbolic error names below,
+various names are marked as follows:
+.IP * 3
+.IR POSIX.1-2001 :
+The name is defined by POSIX.1-2001,
+and is defined in later POSIX.1 versions, unless otherwise indicated.
+.IP *
+.IR POSIX.1-2008 :
+The name is defined in POSIX.1-2008,
+but was not present in earlier POSIX.1 standards.
+.IP *
+.IR C99 :
+The name is defined by C99.
+Below is a list of the symbolic error names that are defined on Linux:
.TP 16
.B E2BIG
-Argument list too long (POSIX.1).
+Argument list too long (POSIX.1-2001).
.TP
.B EACCES
-Permission denied (POSIX.1).
+Permission denied (POSIX.1-2001).
.TP
.B EADDRINUSE
-Address already in use (POSIX.1).
+Address already in use (POSIX.1-2001).
.TP
.B EADDRNOTAVAIL
-Address not available (POSIX.1).
+Address not available (POSIX.1-2001).
.\" EADV is only an error on HURD(?)
.TP
.B EAFNOSUPPORT
-Address family not supported (POSIX.1).
+Address family not supported (POSIX.1-2001).
.TP
.B EAGAIN
Resource temporarily unavailable (may be the same value as
.BR EWOULDBLOCK )
-(POSIX.1).
+(POSIX.1-2001).
.TP
.B EALREADY
-Connection already in progress (POSIX.1).
+Connection already in progress (POSIX.1-2001).
.TP
.B EBADE
Invalid exchange.
.TP
.B EBADF
-Bad file descriptor (POSIX.1).
+Bad file descriptor (POSIX.1-2001).
.TP
.B EBADFD
File descriptor in bad state.
.TP
.B EBADMSG
-Bad message (POSIX.1).
+Bad message (POSIX.1-2001).
.TP
.B EBADR
Invalid request descriptor.
.\" EBFONT is defined but appears not to be used by kernel or glibc.
.TP
.B EBUSY
-Device or resource busy (POSIX.1).
+Device or resource busy (POSIX.1-2001).
.TP
.B ECANCELED
-Operation canceled (POSIX.1).
+Operation canceled (POSIX.1-2001).
.TP
.B ECHILD
-No child processes (POSIX.1).
+No child processes (POSIX.1-2001).
.TP
.B ECHRNG
Channel number out of range.
Communication error on send.
.TP
.B ECONNABORTED
-Connection aborted (POSIX.1).
+Connection aborted (POSIX.1-2001).
.TP
.B ECONNREFUSED
-Connection refused (POSIX.1).
+Connection refused (POSIX.1-2001).
.TP
.B ECONNRESET
-Connection reset (POSIX.1).
+Connection reset (POSIX.1-2001).
.TP
.B EDEADLK
-Resource deadlock avoided (POSIX.1).
+Resource deadlock avoided (POSIX.1-2001).
.TP
.B EDEADLOCK
Synonym for
.BR EDEADLK .
.TP
.B EDESTADDRREQ
-Destination address required (POSIX.1).
+Destination address required (POSIX.1-2001).
.TP
.B EDOM
Mathematics argument out of domain of function (POSIX.1, C99).
.TP
.B EDQUOT
.\" POSIX just says "Reserved"
-Disk quota exceeded (POSIX.1).
+Disk quota exceeded (POSIX.1-2001).
.TP
.B EEXIST
-File exists (POSIX.1).
+File exists (POSIX.1-2001).
.TP
.B EFAULT
-Bad address (POSIX.1).
+Bad address (POSIX.1-2001).
.TP
.B EFBIG
-File too large (POSIX.1).
+File too large (POSIX.1-2001).
.TP
.B EHOSTDOWN
Host is down.
.TP
.B EHOSTUNREACH
-Host is unreachable (POSIX.1).
+Host is unreachable (POSIX.1-2001).
+.TP
+.B EHWPOISON
+Memory page has hardware error.
.TP
.B EIDRM
-Identifier removed (POSIX.1).
+Identifier removed (POSIX.1-2001).
.TP
.B EILSEQ
Invalid or incomplete multibyte or wide character (POSIX.1, C99).
in POSIX.1, this error is described as "Illegal byte sequence".
.TP
.B EINPROGRESS
-Operation in progress (POSIX.1).
+Operation in progress (POSIX.1-2001).
.TP
.B EINTR
-Interrupted function call (POSIX.1); see
+Interrupted function call (POSIX.1-2001); see
.BR signal (7).
.TP
.B EINVAL
-Invalid argument (POSIX.1).
+Invalid argument (POSIX.1-2001).
.TP
.B EIO
-Input/output error (POSIX.1).
+Input/output error (POSIX.1-2001).
.TP
.B EISCONN
-Socket is connected (POSIX.1).
+Socket is connected (POSIX.1-2001).
.TP
.B EISDIR
-Is a directory (POSIX.1).
+Is a directory (POSIX.1-2001).
.TP
.B EISNAM
Is a named type file.
.B ELIBEXEC
Cannot exec a shared library directly.
.TP
+.B ELNRANGE
+.\" ELNRNG appears to be used by a few drivers
+Link number out of range.
+.TP
.B ELOOP
-Too many levels of symbolic links (POSIX.1).
-.\" ELNRNG is defined but appears to be unused
+Too many levels of symbolic links (POSIX.1-2001).
.TP
.B EMEDIUMTYPE
Wrong medium type.
.TP
.B EMFILE
-Too many open files (POSIX.1).
+Too many open files (POSIX.1-2001).
Commonly caused by exceeding the
.BR RLIMIT_NOFILE
resource limit described in
.BR getrlimit (2).
.TP
.B EMLINK
-Too many links (POSIX.1).
+Too many links (POSIX.1-2001).
.TP
.B EMSGSIZE
-Message too long (POSIX.1).
+Message too long (POSIX.1-2001).
.TP
.B EMULTIHOP
.\" POSIX says "Reserved"
-Multihop attempted (POSIX.1).
+Multihop attempted (POSIX.1-2001).
.TP
.B ENAMETOOLONG
-Filename too long (POSIX.1).
+Filename too long (POSIX.1-2001).
.\" ENAVAIL is defined, but appears not to be used
.TP
.B ENETDOWN
-Network is down (POSIX.1).
+Network is down (POSIX.1-2001).
.TP
.B ENETRESET
-Connection aborted by network (POSIX.1).
+Connection aborted by network (POSIX.1-2001).
.TP
.B ENETUNREACH
-Network unreachable (POSIX.1).
+Network unreachable (POSIX.1-2001).
.TP
.B ENFILE
-Too many open files in system (POSIX.1).
+Too many open files in system (POSIX.1-2001).
On Linux, this is probably a result of encountering the
.IR /proc/sys/fs/file-max
limit (see
.BR proc (5)).
-.\" ENOANO is defined but appears to be unused.
+.TP
+.B ENOANO
+.\" ENOANO appears to be used by a few drivers
+No anode.
.TP
.B ENOBUFS
No buffer space available (POSIX.1 (XSI STREAMS option)).
.\" ENOCSI is defined but appears to be unused.
.TP
.B ENODATA
-No message is available on the STREAM head read queue (POSIX.1).
+No message is available on the STREAM head read queue (POSIX.1-2001).
.TP
.B ENODEV
-No such device (POSIX.1).
+No such device (POSIX.1-2001).
.TP
.B ENOENT
-No such file or directory (POSIX.1).
+No such file or directory (POSIX.1-2001).
.IP
Typically, this error results when a specified pathname does not exist,
or one of the components in the directory prefix of a pathname does not exist,
or the specified pathname is a dangling symbolic link.
.TP
.B ENOEXEC
-Exec format error (POSIX.1).
+Exec format error (POSIX.1-2001).
.TP
.B ENOKEY
Required key not available.
.TP
.B ENOLCK
-No locks available (POSIX.1).
+No locks available (POSIX.1-2001).
.TP
.B ENOLINK
.\" POSIX says "Reserved"
-Link has been severed (POSIX.1).
+Link has been severed (POSIX.1-2001).
.TP
.B ENOMEDIUM
No medium found.
.TP
.B ENOMEM
-Not enough space (POSIX.1).
+Not enough space/cannot allocate memory (POSIX.1-2001).
.TP
.B ENOMSG
-No message of the desired type (POSIX.1).
+No message of the desired type (POSIX.1-2001).
.TP
.B ENONET
Machine is not on the network.
Package not installed.
.TP
.B ENOPROTOOPT
-Protocol not available (POSIX.1).
+Protocol not available (POSIX.1-2001).
.TP
.B ENOSPC
-No space left on device (POSIX.1).
+No space left on device (POSIX.1-2001).
.TP
.B ENOSR
No STREAM resources (POSIX.1 (XSI STREAMS option)).
Not a STREAM (POSIX.1 (XSI STREAMS option)).
.TP
.B ENOSYS
-Function not implemented (POSIX.1).
+Function not implemented (POSIX.1-2001).
.TP
.B ENOTBLK
Block device required.
.TP
.B ENOTCONN
-The socket is not connected (POSIX.1).
+The socket is not connected (POSIX.1-2001).
.TP
.B ENOTDIR
-Not a directory (POSIX.1).
+Not a directory (POSIX.1-2001).
.TP
.B ENOTEMPTY
-Directory not empty (POSIX.1).
+Directory not empty (POSIX.1-2001).
.\" ENOTNAM is defined but appears to be unused.
.TP
+.B ENOTRECOVERABLE
+State not recoverable (POSIX.1-2008).
+.TP
.B ENOTSOCK
-Not a socket (POSIX.1).
+Not a socket (POSIX.1-2001).
.TP
.B ENOTSUP
-Operation not supported (POSIX.1).
+Operation not supported (POSIX.1-2001).
.TP
.B ENOTTY
-Inappropriate I/O control operation (POSIX.1).
+Inappropriate I/O control operation (POSIX.1-2001).
.TP
.B ENOTUNIQ
Name not unique on network.
.TP
.B ENXIO
-No such device or address (POSIX.1).
+No such device or address (POSIX.1-2001).
.TP
.B EOPNOTSUPP
-Operation not supported on socket (POSIX.1).
-.sp
+Operation not supported on socket (POSIX.1-2001).
+.IP
.RB ( ENOTSUP
and
.B EOPNOTSUPP
according to POSIX.1 these error values should be distinct.)
.TP
.B EOVERFLOW
-Value too large to be stored in data type (POSIX.1).
+Value too large to be stored in data type (POSIX.1-2001).
+.TP
+.B EOWNERDEAD
+.\" Used at least by the user-space side of rubost mutexes
+Owner died (POSIX.1-2008).
.TP
.B EPERM
-Operation not permitted (POSIX.1).
+Operation not permitted (POSIX.1-2001).
.TP
.B EPFNOSUPPORT
Protocol family not supported.
.TP
.B EPIPE
-Broken pipe (POSIX.1).
+Broken pipe (POSIX.1-2001).
.TP
.B EPROTO
-Protocol error (POSIX.1).
+Protocol error (POSIX.1-2001).
.TP
.B EPROTONOSUPPORT
-Protocol not supported (POSIX.1).
+Protocol not supported (POSIX.1-2001).
.TP
.B EPROTOTYPE
-Protocol wrong type for socket (POSIX.1).
+Protocol wrong type for socket (POSIX.1-2001).
.TP
.B ERANGE
Result too large (POSIX.1, C99).
.B ERESTART
Interrupted system call should be restarted.
.TP
+.B ERFKILL
+.\" ERFKILL appears to be used by various drivers
+Operation not possible due to RF-kill.
+.TP
.B EROFS
-Read-only filesystem (POSIX.1).
+Read-only filesystem (POSIX.1-2001).
.TP
.B ESHUTDOWN
Cannot send after transport endpoint shutdown.
.TP
.B ESPIPE
-Invalid seek (POSIX.1).
+Invalid seek (POSIX.1-2001).
.TP
.B ESOCKTNOSUPPORT
Socket type not supported.
.TP
.B ESRCH
-No such process (POSIX.1).
+No such process (POSIX.1-2001).
.\" ESRMNT is defined but appears not to be used
.TP
.B ESTALE
-Stale file handle (POSIX.1).
-.sp
+Stale file handle (POSIX.1-2001).
+.IP
This error can occur for NFS and for other filesystems.
.TP
.B ESTRPIPE
Streams pipe error.
.TP
.B ETIME
-Timer expired.
-(POSIX.1 (XSI STREAMS option))
-.sp
+Timer expired
+(POSIX.1 (XSI STREAMS option)).
+.IP
(POSIX.1 says "STREAM
.BR ioctl (2)
-timeout")
+timeout".)
.TP
.B ETIMEDOUT
-Connection timed out (POSIX.1).
-.\" ETOOMANYREFS is defined, but appears not to be used.
+Connection timed out (POSIX.1-2001).
+.TP
+.B ETOOMANYREFS
+.\" ETOOMANYREFS seems to be used in net/unix/af_unix.c
+Too many references: cannot splice.
.TP
.B ETXTBSY
-Text file busy (POSIX.1).
+Text file busy (POSIX.1-2001).
.TP
.B EUCLEAN
Structure needs cleaning.
.B EWOULDBLOCK
Operation would block (may be same value as
.BR EAGAIN )
-(POSIX.1).
+(POSIX.1-2001).
.TP
.B EXDEV
-Improper link (POSIX.1).
+Improper link (POSIX.1-2001).
.TP
.B EXFULL
Exchange full.
.SH NOTES
A common mistake is to do
+.PP
.in +4n
-.nf
-
+.EX
if (somecall() == \-1) {
printf("somecall() failed\en");
if (errno == ...) { ... }
}
-
-.fi
+.EE
.in
+.PP
where
.I errno
no longer needs to have the value it had upon return from
If the value of
.I errno
should be preserved across a library call, it must be saved:
+.PP
.in +4n
-.nf
-
+.EX
if (somecall() == \-1) {
int errsv = errno;
printf("somecall() failed\en");
if (errsv == ...) { ... }
}
-.fi
+.EE
.in
.PP
-It was common in traditional C to declare
+On some ancient systems,
+.I <errno.h>
+was not present or did not declare
+.IR errno ,
+so that it was necessary to declare
.I errno
manually
(i.e.,
-.IR "extern int errno" )
-instead of including
-.IR <errno.h> .
+.IR "extern int errno" ).
.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.
+It long ago ceased to be necessary,
+and it will cause problems with modern versions of the C library.
.SH SEE ALSO
.BR errno (1), \" In the moreutils package
.BR err (3),