errno - error code reporting
Standard C Library (libc, -lc)
#include <errno.h>
extern int errno;
When system calls, and sometimes other functions, fail, a code representing or describing the error condition is placed in the global variable errno.
When an operation succeeds, errno is not explicitly changed; however, operations that succeed are also not required to preserve the pre-existing value of errno. In general one must first check whether the operation failed, and only then interrogate errno.
A handful of functions in Standard C and POSIX are explicitly defined to preserve errno on success. These are typically functions with not-entirely-satisfactory interfaces where the only reliable way to detect failure is to clear errno to zero beforehand and check it afterwards. The most common/notable example (not currently available in OS/161's library) is strtol.
errno may be a macro. In a multithreaded process it is almost invariably a macro. However, it is always an lvalue, that is, it may be assigned to.
Each numeric code has a symbolic name and a textual expansion. The symbolic names are used in source code; the textual expansions are printed out when errors are reported to users.
The textual expansions can be retrieved with strerror or printed with err or warn.
The following symbolic errors are defined in the OS/161 base system. You may add more at your pleasure; but be sure to read the notes in the file kern/errno.h that defines them.
| ENOSYS | Function not implemented: the action requested required functionality not yet implemented. This is also the error produced by attempting to make nonexistent system calls. | |
| ENOMEM | Out of memory: a memory allocation failed. This normally means that a process has used up all the memory available to it. (This may be due to limits or because it has used up all the memory available to the system.) It may also mean that memory allocation within the kernel has failed. | |
| EAGAIN | Operation would block: some resource is temporarily unavailable, or a non-blocking I/O operation (if such things exist) could not be completed without waiting. Historically, the message was "Try again later"; in 4.4BSD EAGAIN and the old EWOULDBLOCK error code were folded together. | |
| EINTR | Interrupted system call: handling of a system call was interrupted by the delivery of a signal. (If you have signals.) | |
| EFAULT | Bad memory reference: a pointer passed as an argument was not valid. Within the kernel, the copyin family of functions produces this error when given an invalid pointer. | |
| ENAMETOOLONG | String too long: a string passed as an argument was too long to process. | |
| EINVAL | Invalid argument: an argument passed to a command or system call was badly formed, invalid, or nonsensical, in a way for which no more specific error code is defined. | |
| EPERM | Operation not permitted: the requested operation is restricted to privileged users, or, in some cases, prohibited entirely. Note that "permission denied" is not EPERM. | |
| EACCES | Permission denied: the current process's credentials do not allow the desired form of access to the target object according to its permission settings. Note that "permission denied" is not EPERM. | |
| EMPROC | Too many processes: the current user ID has reached its limit of simultaneous running processes. In Unix, this is spelled EPROCLIM. | |
| ENPROC | Too many processes on system: the system process table is full. (Void where impossible or prohibited by law.) | |
| ENOEXEC | File is not executable: an execv operation was attempted but the kernel was unable to run the requested program. | |
| E2BIG | Argument list too long: the space taken up by the argv[] strings (and environment strings, where applicable) passed to a newly started program is larger than the system allows. The limit on this space is given by the symbol ARG_MAX. | |
| ESRCH | No such process: the supplied process ID does not name any of the currently running processes. | |
| ECHILD | No child processes: the current process has no exited child processes whose exit status has not yet been collected with waitpid. | |
| ENOTDIR | Not a directory: a directory was expected and a non-directory filesystem object was found. | |
| EISDIR | Is a directory: a non-directory was expected and a directory was found. | |
| ENOENT | No such file or directory: the requested filesystem object does/did not exist. | |
| ELOOP | Too many levels of symbolic links: pathname lookup crossed more than the maximum allowed number of symbolic links. Usually means a link points to itself, or a family of links has been arranged into a loop. (If you have symbolic links.) | |
| ENOTEMPTY | Directory not empty: a directory must be empty of everything (except . and ..) before it may be removed. | |
| EEXIST | File exists: a filesystem object that was expected not to exist did in fact already exist. | |
| EMLINK | Too many hard links: the maximum number of hard links to the target file already exist. | |
| EXDEV | Cross-device link: an attempt was made to instruct one filesystem to handle files on another filesystem. | |
| ENODEV | No such device: the requested device or device driver does not exist. | |
| ENXIO | Device not available: the requested device exists but is not available (is not mounted, is powered off, etc.) | |
| EBUSY | Device busy: the requested object cannot be used (or, perhaps, released) because something else is using it. | |
| EMFILE | Too many open files: the process file table is full, so the process cannot open more files. | |
| ENFILE | Too many open files in system: a system-wide limit of some sort, if any exists, on the number of open files has been reached. Void where not possible. | |
| EBADF | Bad file number: a file operation was requested on an illegal file handle, or a file handle that was not open. Or, a write operation was attempted on a file handle that was open only for read or vice-versa. | |
| EIOCTL | Invalid or inappropriate ioctl: an operation requested via the ioctl system call was not defined or could not be performed on the indicated object. In Unix, for historical reasons, this is spelled ENOTTY, with the historic message "Not a typewriter". | |
| EIO | Input/output error: a hardware-level error occured on a device. Media errors on disks fall into this category. | |
| ESPIPE | Illegal seek: a seek operation was attempted on a sequential object where seeking makes no sense, like a pipe or terminal. | |
| EPIPE | Broken pipe: a write was made to a pipe or socket object with nobody to read it. | |
| EROFS | Read-only file system: an attempt was made to modify a filesystem that was mounted read-only. (If you have read-only mounts.) | |
| ENOSPC | No space left on device: the target filesystem is full. | |
| EDQUOT | Disc(sic) quota exceeded: the current user ID's quota (of space or number of files) on the target filesystem has been used up. (If you have disk quotas.) | |
| EFBIG | File too large: an attempt was made to exceed the target filesystem's maximum file size, or a per-user limit on maximum file size was reached, if such a thing exists. | |
| EFTYPE | Invalid file type or format: the file provided was the wrong kind of file or contained invalid syntax. | |
| EDOM | Argument out of range: the (numeric) argument provided was outside the values upon which the operation is defined. For example, attempting to evaluate the logarithm of zero produces this error. It is sometimes also used for non-numeric arguments where the idea of being "out of range" still makes sense. | |
| ERANGE | Result out of range: the result of an operation did not fit in the space provided or could not be represented. Usually used with numeric values. String values that don't fit usually result in ENAMETOOLONG, or in its specific case, E2BIG. | |
| EILSEQ | Invalid multibyte character sequence: the input string contained a byte sequence whose value is undefined or whose use is restricted. Only applicable when a multibyte character set is in use, and if someone has added locale support. | |
| ENOTSOCK | Not a socket: the file handle in question does not refer to a socket, but a socket was expected. | |
| EISSOCK | Is a socket: the file handle in question refers to a socket, but a socket was not expected. In Unix this is spelled EOPNOTSUPP, and prints as "Operation not supported on socket". | |
| EISCONN | Socket is already connected: given the protocol in use, the operation requires a socket that has not yet been connected, but the socket provided is in fact connected. | |
| ENOTCONN | Socket is not connected: given the protocol in use, the operation requires a connected socket, but no connection has yet been made. | |
| ESHUTDOWN | Socket has been shut down: the operation requires a running socket, but the socket provided has been closed down. | |
| EPFNOSUPPORT | Protocol family not supported: the requested protocol family (PF_INET, PF_LOCAL, etc.) is not supported by the system. | |
| ESOCKTNOSUPPORT | Socket type not supported: the requested socket type (SOCK_STREAM, SOCK_DGRAM, etc.) is not supported by the system. | |
| EPROTONOSUPPORT | Protocol not supported: the protocol requested for a socket was not one supported by the system. | |
| EPROTOTYPE | Protocol wrong type for socket: the protocol requested for a socket was not one supported by the requested socket type and protocol family. | |
| EAFNOSUPPORT | Address family not supported by protocol family: the address family named in a struct sockaddr (AF_INET, AF_LOCAL, etc.) is not supported by the protocol family used to create the socket (PF_INET, PF_LOCAL, etc.). In practice each protocol family has exactly one address family and the values of AF_* and PF_* are often, if incorrectly, used interchangeably. If you run into this error in real life, it usually means you didn't initialize your sockaddr structures correctly. | |
| ENOPROTOOPT | Protocol option not available: the protocol option that was requested is not supported or cannot be activated. | |
| EADDRINUSE | Address already in use: the requested socket address is already in use by another socket somewhere on the system. | |
| EADDRNOTAVAIL | Cannot assign requested address: the requested socket address is unavailable. Usually caused by attempting to bind a socket to the IP address of another machine. | |
| ENETDOWN | Network is down: the network or subnet needed is offline. | |
| ENETUNREACH | Network is unreachable: the network or subnet needed cannot be reached from here, possibly due to routing problems on the network, possibly due to local configuration trouble. | |
| EHOSTDOWN | Host is down: the specific machine requested is offline. | |
| EHOSTUNREACH | Host is unreachable: the specific machine requested cannot be reached from here. | |
| ECONNREFUSED | Connection refused: the remote machine is not listening for connections on the requested port. | |
| ETIMEDOUT | Connection timed out: there was no response from the remote machine. It may be down, it may not be listening, or it may not be receiving our packets at all. | |
| ECONNRESET | Connection reset by peer: the connection was abandoned by the remote host. Usually seen on already-open connections after the remote machine reboots and thereby loses its network state. Sometimes also caused by defective network devices between the local and remote hosts. | |
| EMSGSIZE | Message too large: an internal protocol length limit was exceeded. | |
| ENOTSUP | Threads operation not supported: a special error code defined by the POSIX threads standard, which is a "special" interface. |