.\" Copyright (c) 1996 Andries Brouwer (aeb@cwi.nl)
.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" 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
.\" 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.
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
.\"
-.\" 5 Oct 2002, Modified by Michael Kerrisk <mtk-manpages@gmx.net>
-.\" Updated for POSIX 1003.1 2001
+.\" 5 Oct 2002, Modified by Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Updated for POSIX.1 2001
+.\" 2004-12-17 Martin Schulze <joey@infodrom.org>, mtk
+.\" Removed errno declaration prototype, added notes
+.\" 2006-02-09 Kurt Wall, mtk
+.\" Added non-POSIX errors
.\"
-.TH ERRNO 3 2002-10-05 "" "Library functions"
+.TH ERRNO 3 2018-02-02 "" "Linux Programmer's Manual"
.SH NAME
errno \- number of last error
.SH SYNOPSIS
.B #include <errno.h>
-.sp
-.BI "extern int " errno ;
+.\".PP
+.\".BI "extern int " errno ;
.SH DESCRIPTION
-The integer
-.B errno
-is set by system calls (and some library functions) to indicate
-what went wrong. Its value is significant only when the call
-returned an error (usually \-1), and a library function that does succeed
-is allowed to change
-.BR errno .
-
-Sometimes, when \-1 is also a legal 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
+The
+.I <errno.h>
+header file defines the integer variable
+.IR errno ,
+which is set by system calls and some library functions in the event
+of an error to indicate what went wrong.
+.\"
+.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);
+a function that succeeds
+.I is
+allowed to change
+.IR errno .
+The value of
+.I errno
+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.
+In such cases, a successful return can be distinguished from an error
+return by setting
+.I errno
+to zero before the call, and then,
+if the call returns a status that indicates that an error
+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
+.IR int ,
+and must not be explicitly declared;
+.I errno
+may be a macro.
+.I errno
+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.
-
-.\" 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.
-
-.TP
+.\"
+.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.
+.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.
+.\"
+.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
-Arg list too long
+Argument list too long (POSIX.1-2001).
.TP
.B EACCES
-Permission denied
+Permission denied (POSIX.1-2001).
.TP
.B EADDRINUSE
-Address in use
+Address already in use (POSIX.1-2001).
.TP
.B EADDRNOTAVAIL
-Address not available
+Address not available (POSIX.1-2001).
+.\" EADV is only an error on HURD(?)
.TP
.B EAFNOSUPPORT
-Address family not supported
+Address family not supported (POSIX.1-2001).
.TP
.B EAGAIN
-Resource temporarily unavailable
+Resource temporarily unavailable (may be the same value as
+.BR EWOULDBLOCK )
+(POSIX.1-2001).
.TP
.B EALREADY
-Connection already in progress
+Connection already in progress (POSIX.1-2001).
+.TP
+.B EBADE
+Invalid exchange.
.TP
.B EBADF
-Bad file descriptor
+Bad file descriptor (POSIX.1-2001).
+.TP
+.B EBADFD
+File descriptor in bad state.
.TP
.B EBADMSG
-Bad message
+Bad message (POSIX.1-2001).
+.TP
+.B EBADR
+Invalid request descriptor.
+.TP
+.B EBADRQC
+Invalid request code.
+.TP
+.B EBADSLT
+Invalid slot.
+.\" EBFONT is defined but appears not to be used by kernel or glibc.
.TP
.B EBUSY
-Resource busy
+Device or resource busy (POSIX.1-2001).
.TP
.B ECANCELED
-Operation canceled
+Operation canceled (POSIX.1-2001).
.TP
.B ECHILD
-No child processes
+No child processes (POSIX.1-2001).
+.TP
+.B ECHRNG
+Channel number out of range.
+.TP
+.B ECOMM
+Communication error on send.
.TP
.B ECONNABORTED
-Connection aborted
+Connection aborted (POSIX.1-2001).
.TP
.B ECONNREFUSED
-Connection refused
+Connection refused (POSIX.1-2001).
.TP
.B ECONNRESET
-Connection reset
+Connection reset (POSIX.1-2001).
.TP
.B EDEADLK
-Resource deadlock avoided
+Resource deadlock avoided (POSIX.1-2001).
+.TP
+.B EDEADLOCK
+Synonym for
+.BR EDEADLK .
.TP
.B EDESTADDRREQ
-Destination address required
+Destination address required (POSIX.1-2001).
.TP
.B EDOM
-Domain error
+Mathematics argument out of domain of function (POSIX.1, C99).
+.\" EDOTDOT is defined but appears to be unused
.TP
.B EDQUOT
-Reserved
+.\" POSIX just says "Reserved"
+Disk quota exceeded (POSIX.1-2001).
.TP
.B EEXIST
-File exists
+File exists (POSIX.1-2001).
.TP
.B EFAULT
-Bad address
+Bad address (POSIX.1-2001).
.TP
.B EFBIG
-File too large
+File too large (POSIX.1-2001).
+.TP
+.B EHOSTDOWN
+Host is down.
.TP
.B EHOSTUNREACH
-Host is unreachable
+Host is unreachable (POSIX.1-2001).
+.TP
+.B EHWPOISON
+Memory page has hardware error.
.TP
.B EIDRM
-Identifier removed
+Identifier removed (POSIX.1-2001).
.TP
.B EILSEQ
-Illegal byte sequence
+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
+Operation in progress (POSIX.1-2001).
.TP
.B EINTR
-Interrupted function call
+Interrupted function call (POSIX.1-2001); see
+.BR signal (7).
.TP
.B EINVAL
-Invalid argument
+Invalid argument (POSIX.1-2001).
.TP
.B EIO
-Input/output error
+Input/output error (POSIX.1-2001).
.TP
.B EISCONN
-Socket is connected
+Socket is connected (POSIX.1-2001).
.TP
.B EISDIR
-Is a directory
+Is a directory (POSIX.1-2001).
+.TP
+.B EISNAM
+Is a named type file.
+.TP
+.B EKEYEXPIRED
+Key has expired.
+.TP
+.B EKEYREJECTED
+Key was rejected by service.
+.TP
+.B EKEYREVOKED
+Key has been revoked.
+.TP
+.B EL2HLT
+Level 2 halted.
+.TP
+.B EL2NSYNC
+Level 2 not synchronized.
+.TP
+.B EL3HLT
+Level 3 halted.
+.TP
+.B EL3RST
+Level 3 reset.
+.TP
+.B ELIBACC
+Cannot access a needed shared library.
+.TP
+.B ELIBBAD
+Accessing a corrupted shared library.
+.TP
+.B ELIBMAX
+Attempting to link in too many shared libraries.
+.TP
+.B ELIBSCN
+\&.lib section in a.out corrupted
+.TP
+.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
+Too many levels of symbolic links (POSIX.1-2001).
+.TP
+.B EMEDIUMTYPE
+Wrong medium type.
.TP
.B EMFILE
-Too many open files
+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
+Too many links (POSIX.1-2001).
.TP
.B EMSGSIZE
-Inappropriate message buffer length
+Message too long (POSIX.1-2001).
.TP
.B EMULTIHOP
-Reserved
+.\" POSIX says "Reserved"
+Multihop attempted (POSIX.1-2001).
.TP
.B ENAMETOOLONG
-Filename too long
+Filename too long (POSIX.1-2001).
+.\" ENAVAIL is defined, but appears not to be used
.TP
.B ENETDOWN
-Network is down
+Network is down (POSIX.1-2001).
.TP
.B ENETRESET
-Connection aborted by network
+Connection aborted by network (POSIX.1-2001).
.TP
.B ENETUNREACH
-Network unreachable
+Network unreachable (POSIX.1-2001).
.TP
.B ENFILE
-Too many open files in system
+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)).
+.TP
+.B ENOANO
+.\" ENOANO appears to be used by a few drivers
+No anode.
.TP
.B ENOBUFS
-No buffer space available
-.\" ENODATA is part of XSR 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
+No message is available on the STREAM head read queue (POSIX.1-2001).
.TP
.B ENODEV
-No such device
+No such device (POSIX.1-2001).
.TP
.B ENOENT
-No such file or directory
+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
+Exec format error (POSIX.1-2001).
+.TP
+.B ENOKEY
+Required key not available.
.TP
.B ENOLCK
-No locks available
+No locks available (POSIX.1-2001).
.TP
.B ENOLINK
-Reserved
+.\" POSIX says "Reserved"
+Link has been severed (POSIX.1-2001).
+.TP
+.B ENOMEDIUM
+No medium found.
.TP
.B ENOMEM
-Not enough space
+Not enough space/cannot allocate memory (POSIX.1-2001).
.TP
.B ENOMSG
-No message of the desired type
+No message of the desired type (POSIX.1-2001).
+.TP
+.B ENONET
+Machine is not on the network.
+.TP
+.B ENOPKG
+Package not installed.
.TP
.B ENOPROTOOPT
-Protocol not available
+Protocol not available (POSIX.1-2001).
.TP
.B ENOSPC
-No space left on device
-.\" ENOSR is part of XSR option
+No space left on device (POSIX.1-2001).
.TP
.B ENOSR
-No STREAM resources
-.\" ENOSTR is part of XSR option
+No STREAM resources (POSIX.1 (XSI STREAMS option)).
.TP
.B ENOSTR
-Not a STREAM
+Not a STREAM (POSIX.1 (XSI STREAMS option)).
.TP
.B ENOSYS
-Function not implemented
+Function not implemented (POSIX.1-2001).
+.TP
+.B ENOTBLK
+Block device required.
.TP
.B ENOTCONN
-The socket is not connected
+The socket is not connected (POSIX.1-2001).
.TP
.B ENOTDIR
-Not a directory
+Not a directory (POSIX.1-2001).
.TP
.B ENOTEMPTY
-Directory not empty
+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
+Not a socket (POSIX.1-2001).
.TP
.B ENOTSUP
-Not supported
+Operation not supported (POSIX.1-2001).
.TP
.B ENOTTY
-Inappropriate I/O control operation
+Inappropriate I/O control operation (POSIX.1-2001).
+.TP
+.B ENOTUNIQ
+Name not unique on network.
.TP
.B ENXIO
-No such device or address
+No such device or address (POSIX.1-2001).
.TP
.B EOPNOTSUPP
-Operation not supported on socket
+Operation not supported on socket (POSIX.1-2001).
+.IP
+.RB ( ENOTSUP
+and
+.B EOPNOTSUPP
+have the same value on Linux, but
+according to POSIX.1 these error values should be distinct.)
.TP
.B EOVERFLOW
-Value too large to be stored in data type
+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
+Operation not permitted (POSIX.1-2001).
+.TP
+.B EPFNOSUPPORT
+Protocol family not supported.
.TP
.B EPIPE
-Broken pipe
+Broken pipe (POSIX.1-2001).
.TP
.B EPROTO
-Protocol error
+Protocol error (POSIX.1-2001).
.TP
.B EPROTONOSUPPORT
-Protocol not supported
+Protocol not supported (POSIX.1-2001).
.TP
.B EPROTOTYPE
-Protocol wrong type for socket
+Protocol wrong type for socket (POSIX.1-2001).
.TP
.B ERANGE
-Result too large
+Result too large (POSIX.1, C99).
+.TP
+.B EREMCHG
+Remote address changed.
+.TP
+.B EREMOTE
+Object is remote.
+.TP
+.B EREMOTEIO
+Remote I/O error.
+.TP
+.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 file system
+Read-only filesystem (POSIX.1-2001).
+.TP
+.B ESHUTDOWN
+Cannot send after transport endpoint shutdown.
.TP
.B ESPIPE
-Invalid seek
+Invalid seek (POSIX.1-2001).
+.TP
+.B ESOCKTNOSUPPORT
+Socket type not supported.
.TP
.B ESRCH
-No such process
+No such process (POSIX.1-2001).
+.\" ESRMNT is defined but appears not to be used
.TP
.B ESTALE
-Reserved
-.\" ETIME is part of XSR option
+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
-STREAM ioctl() timeout
+Timer expired
+(POSIX.1 (XSI STREAMS option)).
+.IP
+(POSIX.1 says "STREAM
+.BR ioctl (2)
+timeout".)
.TP
.B ETIMEDOUT
-Operation timed out
+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
-Test file busy
+Text file busy (POSIX.1-2001).
+.TP
+.B EUCLEAN
+Structure needs cleaning.
+.TP
+.B EUNATCH
+Protocol driver not attached.
+.TP
+.B EUSERS
+Too many users.
.TP
.B EWOULDBLOCK
Operation would block (may be same value as
.BR EAGAIN )
+(POSIX.1-2001).
.TP
.B EXDEV
-Improper link
-.SH NOTE
+Improper link (POSIX.1-2001).
+.TP
+.B EXFULL
+Exchange full.
+.SH NOTES
A common mistake is to do
-.RS
-.nf
-
-if (somecall() == -1) {
+.PP
+.in +4n
+.EX
+if (somecall() == \-1) {
printf("somecall() failed\en");
if (errno == ...) { ... }
}
-
-.fi
-.RE
+.EE
+.in
+.PP
where
.I errno
no longer needs to have the value it had upon return from
-.IR somecall() .
+.IR somecall ()
+(i.e., it may have been changed by the
+.BR printf (3)).
If the value of
.I errno
should be preserved across a library call, it must be saved:
-.RS
-.nf
-
-if (somecall() == -1) {
+.PP
+.in +4n
+.EX
+if (somecall() == \-1) {
int errsv = errno;
printf("somecall() failed\en");
if (errsv == ...) { ... }
}
-
-.fi
-.RE
-.SH "SEE ALSO"
+.EE
+.in
+.PP
+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" ).
+.BR "Do not do this" .
+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),
+.BR error (3),
.BR perror (3),
.BR strerror (3)
projects / thirdparty / man-pages.git / blobdiff