diff options
Diffstat (limited to 'man/man3/errno.3')
| -rw-r--r-- | man/man3/errno.3 | 655 |
1 files changed, 655 insertions, 0 deletions
diff --git a/man/man3/errno.3 b/man/man3/errno.3 new file mode 100644 index 000000000..786dec824 --- /dev/null +++ b/man/man3/errno.3 @@ -0,0 +1,655 @@ +.\" Copyright (c) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 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 (date) "Linux man-pages (unreleased)" +.SH NAME +errno \- number of last error +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <errno.h> +.\".P +.\".BI "extern int " errno ; +.fi +.SH DESCRIPTION +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. +.P +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. +.P +.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. +.\" +.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 . +.P +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. +On Linux, these two have the same value on all architectures. +.P +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. +.P +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): +.P +.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 +.P +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: +.P +.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 +.\".P +.\" 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: +.TP +.I POSIX.1-2001 +The name is defined by POSIX.1-2001, +and is defined in later POSIX.1 versions, unless otherwise indicated. +.TP +.I POSIX.1-2008 +The name is defined in POSIX.1-2008, +but was not present in earlier POSIX.1 standards. +.TP +.I C99 +The name is defined by C99. +.P +Below is a list of the symbolic error names that are defined on Linux: +.TP 16 +.B E2BIG +Argument list too long (POSIX.1-2001). +.TP +.B EACCES +Permission denied (POSIX.1-2001). +.TP +.B EADDRINUSE +Address already in use (POSIX.1-2001). +.TP +.B EADDRNOTAVAIL +Address not available (POSIX.1-2001). +.\" EADV is only an error on HURD(?) +.TP +.B EAFNOSUPPORT +Address family not supported (POSIX.1-2001). +.TP +.B EAGAIN +Resource temporarily unavailable (may be the same value as +.BR EWOULDBLOCK ) +(POSIX.1-2001). +.TP +.B EALREADY +Connection already in progress (POSIX.1-2001). +.TP +.B EBADE +Invalid exchange. +.TP +.B EBADF +Bad file descriptor (POSIX.1-2001). +.TP +.B EBADFD +File descriptor in bad state. +.TP +.B EBADMSG +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 +Device or resource busy (POSIX.1-2001). +.TP +.B ECANCELED +Operation canceled (POSIX.1-2001). +.TP +.B ECHILD +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 (POSIX.1-2001). +.TP +.B ECONNREFUSED +Connection refused (POSIX.1-2001). +.TP +.B ECONNRESET +Connection reset (POSIX.1-2001). +.TP +.B EDEADLK +Resource deadlock avoided (POSIX.1-2001). +.TP +.B EDEADLOCK +On most architectures, a synonym for +.BR EDEADLK . +On some architectures (e.g., Linux MIPS, PowerPC, SPARC), +it is a separate error code "File locking deadlock error". +.TP +.B EDESTADDRREQ +Destination address required (POSIX.1-2001). +.TP +.B EDOM +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-2001). +.TP +.B EEXIST +File exists (POSIX.1-2001). +.TP +.B EFAULT +Bad address (POSIX.1-2001). +.TP +.B EFBIG +File too large (POSIX.1-2001). +.TP +.B EHOSTDOWN +Host is down. +.TP +.B EHOSTUNREACH +Host is unreachable (POSIX.1-2001). +.TP +.B EHWPOISON +Memory page has hardware error. +.TP +.B EIDRM +Identifier removed (POSIX.1-2001). +.TP +.B EILSEQ +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-2001). +.TP +.B EINTR +Interrupted function call (POSIX.1-2001); see +.BR signal (7). +.TP +.B EINVAL +Invalid argument (POSIX.1-2001). +.TP +.B EIO +Input/output error (POSIX.1-2001). +.TP +.B EISCONN +Socket is connected (POSIX.1-2001). +.TP +.B EISDIR +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 ELNRNG +.\" 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-2001). +.TP +.B EMEDIUMTYPE +Wrong medium type. +.TP +.B EMFILE +Too many open files (POSIX.1-2001). +Commonly caused by exceeding the +.B RLIMIT_NOFILE +resource limit described in +.BR getrlimit (2). +Can also be caused by exceeding the limit specified in +.IR /proc/sys/fs/nr_open . +.TP +.B EMLINK +Too many links (POSIX.1-2001). +.TP +.B EMSGSIZE +Message too long (POSIX.1-2001). +.TP +.B EMULTIHOP +.\" POSIX says "Reserved" +Multihop attempted (POSIX.1-2001). +.TP +.B ENAMETOOLONG +Filename too long (POSIX.1-2001). +.\" ENAVAIL is defined, but appears not to be used +.TP +.B ENETDOWN +Network is down (POSIX.1-2001). +.TP +.B ENETRESET +Connection aborted by network (POSIX.1-2001). +.TP +.B ENETUNREACH +Network unreachable (POSIX.1-2001). +.TP +.B ENFILE +Too many open files in system (POSIX.1-2001). +On Linux, this is probably a result of encountering the +.I /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 (POSIX.1 (XSI STREAMS option)). +.\" ENOCSI is defined but appears to be unused. +.TP +.B ENODATA +The named attribute does not exist, +or the process has no access to this attribute; see +.BR xattr (7). +.IP +In POSIX.1-2001 (XSI STREAMS option), +this error was described as +"No message is available on the STREAM head read queue". +.TP +.B ENODEV +No such device (POSIX.1-2001). +.TP +.B ENOENT +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-2001). +.TP +.B ENOKEY +Required key not available. +.TP +.B ENOLCK +No locks available (POSIX.1-2001). +.TP +.B ENOLINK +.\" POSIX says "Reserved" +Link has been severed (POSIX.1-2001). +.TP +.B ENOMEDIUM +No medium found. +.TP +.B ENOMEM +Not enough space/cannot allocate memory (POSIX.1-2001). +.TP +.B ENOMSG +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 (POSIX.1-2001). +.TP +.B ENOSPC +No space left on device (POSIX.1-2001). +.TP +.B ENOSR +No STREAM resources (POSIX.1 (XSI STREAMS option)). +.TP +.B ENOSTR +Not a STREAM (POSIX.1 (XSI STREAMS option)). +.TP +.B ENOSYS +Function not implemented (POSIX.1-2001). +.TP +.B ENOTBLK +Block device required. +.TP +.B ENOTCONN +The socket is not connected (POSIX.1-2001). +.TP +.B ENOTDIR +Not a directory (POSIX.1-2001). +.TP +.B ENOTEMPTY +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-2001). +.TP +.B ENOTSUP +Operation not supported (POSIX.1-2001). +.TP +.B ENOTTY +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-2001). +.TP +.B EOPNOTSUPP +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 (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-2001). +.TP +.B EPFNOSUPPORT +Protocol family not supported. +.TP +.B EPIPE +Broken pipe (POSIX.1-2001). +.TP +.B EPROTO +Protocol error (POSIX.1-2001). +.TP +.B EPROTONOSUPPORT +Protocol not supported (POSIX.1-2001). +.TP +.B EPROTOTYPE +Protocol wrong type for socket (POSIX.1-2001). +.TP +.B ERANGE +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 filesystem (POSIX.1-2001). +.TP +.B ESHUTDOWN +Cannot send after transport endpoint shutdown. +.TP +.B ESPIPE +Invalid seek (POSIX.1-2001). +.TP +.B ESOCKTNOSUPPORT +Socket type not supported. +.TP +.B ESRCH +No such process (POSIX.1-2001). +.\" ESRMNT is defined but appears not to be used +.TP +.B ESTALE +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)). +.IP +(POSIX.1 says "STREAM +.BR ioctl (2) +timeout".) +.TP +.B ETIMEDOUT +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-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 +Invalid cross-device link (POSIX.1-2001). +.TP +.B EXFULL +Exchange full. +.SH NOTES +A common mistake is to do +.P +.in +4n +.EX +if (somecall() == \-1) { + printf("somecall() failed\en"); + if (errno == ...) { ... } +} +.EE +.in +.P +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 (3)). +If the value of +.I errno +should be preserved across a library call, it must be saved: +.P +.in +4n +.EX +if (somecall() == \-1) { + int errsv = errno; + printf("somecall() failed\en"); + if (errsv == ...) { ... } +} +.EE +.in +.P +Note that the POSIX threads APIs do +.I not +set +.I errno +on error. +Instead, on failure they return an error number as the function result. +These error numbers have the same meanings as the error numbers returned in +.I errno +by other APIs. +.P +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) |