.\" 2006-02-09 Kurt Wall, mtk
.\" Added non-POSIX errors
.\"
-.TH ERRNO 3 2016-03-15 "" "Linux Programmer's Manual"
+.TH ERRNO 3 2018-02-02 "" "Linux Programmer's Manual"
.SH NAME
errno \- number of last error
.SH SYNOPSIS
.B #include <errno.h>
-.\".sp
+.\".PP
.\".BI "extern int " errno ;
.SH DESCRIPTION
The
.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 .
-
-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)),
\-1 is a valid return on success.
may have occurred, checking to see if
.I errno
has a nonzero value.
-
+.PP
.I errno
is defined by the ISO C standard to be a modifiable lvalue
of type
.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
.B EAGAIN
and
.BR EWOULDBLOCK ,
which may be the same.
-
-.\" The following is now
+.PP
+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
+Invalid exchange.
.TP
.B EBADF
-Bad file descriptor (POSIX.1)
+Bad file descriptor (POSIX.1-2001).
.TP
.B EBADFD
-File descriptor in bad state
+File descriptor in bad state.
.TP
.B EBADMSG
-Bad message (POSIX.1)
+Bad message (POSIX.1-2001).
.TP
.B EBADR
-Invalid request descriptor
+Invalid request descriptor.
.TP
.B EBADRQC
-Invalid request code
+Invalid request code.
.TP
.B EBADSLT
-Invalid slot
+Invalid slot.
.\" 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
+Channel number out of range.
.TP
.B ECOMM
-Communication error on send
+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
-.B EDEADLK
+.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)
+Mathematics argument out of domain of function (POSIX.1, C99).
.\" EDOTDOT is defined but appears to be unused
.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
+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
-Illegal byte sequence (POSIX.1, C99)
+Invalid or incomplete multibyte or wide character (POSIX.1, C99).
+.IP
+The text shown here is the glibc error description;
+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
+Is a named type file.
.TP
.B EKEYEXPIRED
-Key has expired
+Key has expired.
.TP
.B EKEYREJECTED
-Key was rejected by service
+Key was rejected by service.
.TP
.B EKEYREVOKED
-Key has been revoked
+Key has been revoked.
.TP
.B EL2HLT
-Level 2 halted
+Level 2 halted.
.TP
.B EL2NSYNC
-Level 2 not synchronized
+Level 2 not synchronized.
.TP
.B EL3HLT
-Level 3 halted
+Level 3 halted.
.TP
.B EL3RST
-Level 3 halted
+Level 3 reset.
.TP
.B ELIBACC
-Cannot access a needed shared library
+Cannot access a needed shared library.
.TP
.B ELIBBAD
-Accessing a corrupted shared library
+Accessing a corrupted shared library.
.TP
.B ELIBMAX
-Attempting to link in too many shared libraries
+Attempting to link in too many shared libraries.
.TP
.B ELIBSCN
-lib section in a.out corrupted
+\&.lib section in a.out corrupted
.TP
.B ELIBEXEC
-Cannot exec a shared library directly
+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
+Wrong medium type.
.TP
.B EMFILE
-Too many open files (POSIX.1);
-commonly caused by exceeding the
+Too many open files (POSIX.1-2001).
+Commonly caused by exceeding the
.BR RLIMIT_NOFILE
resource limit described in
-.BR getrlimit (2)
+.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);
-on Linux, this is probably a result of encountering the
+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))
+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
+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
+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
+Machine is not on the network.
.TP
.B ENOPKG
-Package not installed
+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))
+No STREAM resources (POSIX.1 (XSI STREAMS option)).
.TP
.B ENOSTR
-Not a STREAM (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
+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
+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
+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)
+Result too large (POSIX.1, C99).
.TP
.B EREMCHG
-Remote address changed
+Remote address changed.
.TP
.B EREMOTE
-Object is remote
+Object is remote.
.TP
.B EREMOTEIO
-Remote I/O error
+Remote I/O error.
.TP
.B ERESTART
-Interrupted system call should be restarted
+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
+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
+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
-This error can occur for NFS and for other filesystems
+Stale file handle (POSIX.1-2001).
+.IP
+This error can occur for NFS and for other filesystems.
.TP
.B ESTRPIPE
-Streams pipe error
+Streams pipe error.
.TP
.B ETIME
Timer expired
-(POSIX.1 (XSI STREAMS option))
-.sp
+(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
+Structure needs cleaning.
.TP
.B EUNATCH
-Protocol driver not attached
+Protocol driver not attached.
.TP
.B EUSERS
-Too many users
+Too many users.
.TP
.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
+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),
projects / thirdparty / man-pages.git / blobdiff