*** UNIX MANUAL PAGE BROWSER ***

intro(2) System Calls Manual intro(2) NAME intro, errno - Introduction to system calls SYNOPSIS #include <errno.h> DESCRIPTION Section 2 describes the DIGITAL UNIX system calls, which are the en- tries into the operating system kernel. Some reference pages in this section may contain suffixes to allow their files to exist with those of other reference pages having the same base name and section number. When used, suffixes are made up of one to four letters. See the man(1) reference page for more information on suffixes. DEFINITIONS The following terms are used in Section 2: An integer assigned by the system when a file is referenced by the open, dup, or pipe calls, or a socket is referenced by the socket or socketpair calls. The descriptor uniquely identifies an access path to that file or socket from a given process or any of its children. A directory is a special type of file that contains references to other files, called links. By convention, a directory contains at least two links called dot (.) and dot-dot (..). Dot refers to the directory itself and dot-dot refers to its parent directory. Access to system resources is governed by the effec- tive user ID, the effective group ID, and the group access list. The effective user ID and effective group ID are initially the process's real user ID and real group ID respectively. Either can be modified through execution of a set-user-ID or set-group- ID file, or possibly by one of its ancestors. For more informa- tion, see execve(2). The group access list is an additional set of group IDs used only in determining resource accessibility. Access checks are performed as defined under the term File Access Permissions. Every file in the file system has a set of access permissions. These permissions are used in determining whether a process may perform a requested operation on the file, such as opening a file for writing. Access permissions are established at the time a file is created. They can be changed with the chmod call. File access is separated into three types: read, write, and exe- cute. Directory files use the execute permission to control whether or not the directory can be searched. File access permissions are interpreted by the system as they apply to three different classes of users: the owner of the file, those users in the file's group, and anyone else. Every file has an independent set of access permissions for each of these classes. When an access check is made, the system decides if permission should be granted by checking the access informa- tion applicable to the caller. Read, write, and execute/search permissions on a file are granted to a process in the following instances: The process's effective user ID is that of the superuser. The process's ef- fective user ID matches the user ID of the owner of the file and the owner permissions allow the access. The process's effective user ID does not match the user ID of the owner of the file, but either the process's effective group ID matches the group ID of the file or the group ID of the file is in the process's group access list and the group permissions allow the access. Neither the effective user ID nor the effective group ID and group ac- cess list of the process match the corresponding user ID and group ID of the file, but the permissions for other users allow access. Read, write, and execute/search permissions on a file are not granted, as follows: If the process is trying to execute an im- age and the file system is mounted no execute, execute permis- sion is denied. If the process's effective UID is not root, the process is attempting to access a character or block special de- vice, and the file system is mounted with nodev, access is de- nied. If the process's effective UID is not root, the process is trying to execute an image with the setuid or setgid bit set in the file's permissions, and the file system is mounted no- suid, execute permission is denied. A name consisting of 1 to {NAME_MAX} bytes used to name an ordinary file, special file, or directory. The characters composing the name can be selected from the set of all character values, excluding the slash character (/) and the null character (0). The filenames dot (.) and dot-dot (..) have special meaning. Avoid using asterisks (*), question marks (?), or brackets ([ ]) as part of filenames because of the special meaning attached to these characters by the shell. A new process is created by a currently active process. For further information, see fork(2). The parent process ID of a process is the process ID of its cre- ator. A pathname is a string that is used to identify a file. A pathname consists of, at most, {PATH_MAX} bytes, including the terminating null character. A pathname has an optional begin- ning slash, followed by zero or more filenames separated by slashes. If the pathname refers to a directory, it may also have one or more trailing slashes. Multiple successive slashes are considered the same as one slash. If a pathname begins with a slash, the path search begins at the root directory of the process. Otherwise, the search begins from the current working directory. The special filename dot (.) refers to the directory specified by its predecessor. The special filename dot-dot (..) refers to the parent directory of its predecessor directory. As a special case, in the root directory, dot-dot may refer to the root di- rectory itself. A slash by itself names the root directory. A null pathname is invalid. Each active process in the system is uniquely identi- fied by a positive integer called a process ID. The range of this ID is from 0 to {PROC_MAX}. Each active process is a mem- ber of a process group that is identified by a positive integer called the process group ID. This is the process ID of the group leader. This grouping permits the signaling of related processes. For more information see the job control mechanisms described in csh(1). Each user on the system is identified by a positive integer called the real user ID. Each user is also a member of one or more groups. One of these groups is distinguished from others and used in implementing ac- counting facilities. The positive integer corresponding to this group is called the real group ID. All processes have a real user ID and real group ID. These are initialized from the equivalent attributes of the parent process. Each process has associated with it a concept of a root directory and a current working directory for the purpose of resolving path name searches. A process's root directory does not need to be the root directory of the root file system. Each process group is a member of a session. A process is con- sidered to be a member of the session of which its process group is a member. Typically there is one session per login. A socket is an endpoint for communication between processes. Each socket has queues for sending and receiving data. Sockets are typed according to their communications properties. These properties determine whether messages sent and received at a socket require the name of the partner, if communication is reliable, and if the format is used in naming message recipi- ents. Each instance of the system supports some collection of socket types. See socket(2) for more information about the types available and their properties. Each instance of the system supports some number of sets of com- munications protocols. Each protocol set supports addresses of a certain format. An Address Family is the set of addresses for a specific group of protocols. Each socket has an address cho- sen from the address family in which the socket was created. Those processes that have a process ID of 0, 1, and 2 are con- sidered special processes. Process 0 is the scheduler. Process 1 is the initialization process init, which is the ancestor of every other process in the system and controls the process structure. Process 2 is the exception handler. A process is recognized as a superuser process and is granted special privi- leges if its effective user ID is 0. Each active process can be a member of a terminal group that is identified by a positive integer called the tty group ID. This grouping is used to arbi- trate between multiple jobs contending for the same terminal. For more information, see csh(1) and tty(7). RETURN VALUES Most system calls have one or more return values. An error condition is indicated by an otherwise impossible return value. This value is usually -1. All return codes and values from functions are of type int unless otherwise noted. When a function returns an error condition, it also stores an error number in the external variable errno. This variable is not cleared on successful calls. Thus, you should test errno only after an error has occurred. Refer to errno(5) for information about using the errno vari- able. The remainder of this section lists in alphabetical order the symbolic codes for errno values, along with associated messages and ex- planations. Some codes represent more than one type of error. For ex- ample, [E2BIG] can indicate that the specified argument size has ex- ceeded the system limit of ARG_MAX, or that the specified number of sembuf structures has exceeded a predefined limit. Indicates that the specified argument and environment lists exceed the system limit of ARG_MAX bytes, or the number of bytes in the message exceeds the prede- fined limit. Indicates that the requested operation did not have the proper access permissions. This error may also indicate one or more of the following: The named file is not an ordinary file (acct()). The operation would cause the parent directory or process's information level to float such that it would no longer be dominated by the direc- tory or process's sensitivity level. The requested file is not avail- able for read or write access. The process is attempting to mount on a multilevel child directory. The value of the process ID argument matches the process ID of a child process of the calling process and the child process has successfully executed one of the exec functions (setpgid()). The function is trying to manipulate two files on two different file systems. An open with write mode has been attempted to a write protected tape. Indicates that the specified address is al- ready in use. Indicates that the specified address is not available from the local machine. Indicates that the addresses in the specified address family are not supported by the protocol family. Indicates that the requested resource, such as a lock or a process, is temporar- ily unavailable. This error may also indicate one or both of the fol- lowing: If the O_NONBLOCK flag is set for the requested function, the process would be delayed in a read or write operation. The specified time has elapsed (pthread_cond_timedwait()). Indicates that an opera- tion was attempted on a non-blocking object for which an operation was already in progress. Indicates that a socket or file descriptor para- meter is invalid. Indicates that the next STREAMS message is of the wrong type. Indicates that the NFS has encountered a Remote Procedure Call request or response that is invalid or that cannot be decoded. Indicates one or more of the following errors: The requested element is currently unavailable, or the associated system limit was exceeded. For NFS files, the requested device or directory is in use by another process. Indicates that a pending AIO (asynchronous input/output) op- eration was canceled. Indicates either that the child process does not exist, or that the requested child process information is unavailable. Indicates that the software caused a connection abort because there is no space on the socket's queue and the socket cannot receive further connections. Indicates that the connection request was refused. Indi- cates that a connection was forcibly reset (closed) by a peer. The situation normally results when a timeout or a reboot causes the loss of the connection on the remote socket. Indicates either a probable deadlock condition, or that the requested lock is owned by someone else. Indicates that a required destination address was omitted from an operation on a socket. Indicates an attempt to mount a dirty file system, one on which a consistency check has not or cannot be made. A dirty file system can be mounted by force only if the M_FMOUNT flag is included on the mount() call. Indicates that x and/or y are either Not a Number (NaN), or that they are in some other way unacceptable (for example, they exceed system limits). A write has failed because the user's disk block quota is exhausted or an open that would create a file has failed because the user's inode quota is exhausted. Indicates that the request element (for example, a file or a semaphore) already exists. Indicates that the requested address is in some way invalid, for example, out of bounds. Indicates either that the file size ex- ceeds the process's file size limit, or that the requested semaphore number is invalid. Valid semaphore numbers are greater than 0 (zero) and less than the specified number of semaphores. Indicates that a socket operation failed because the destination host was down. Indi- cates that a socket operation failed because no route could be found to the host. Indicates that the requested semaphore or message queue ID has been removed from the system. Indicates that a wide character code does not correspond to a valid character or an invalid multibyte char- acter sequence was detected. Indicates that a lengthy operation on a non-blocking object is now in progress. Indicates that an interrupt- ible function's process was interrupted by a signal that the process caught. Indicates that an invalid argument was passed to the function (such as, the requested argument does not exist or is out of bounds or is not a regular file, or that the result would be invalid). This er- ror may also indicate one or more of the following: The requested socket is not accepting connections (accept()) or is already bound (bind()). The specified superblock had a bad magic number or a block size that was out of range (mount()). The requested parameter is a lock/unlock parameter, but the element to be locked is already locked/unlocked (plock()). The kernel has not been compiled with the QUOTA option (quota()). An attempt was made to ignore or supply a han- dler for the SIGKILL, SIGSTOP, and SIGCONT signals (sigaction()). The requested device was not configured as a swap device or does not allow paging (swapon()). The requested device is not mounted or local (mount()). Indicates one of the following: A read or write physical I/O error. These errors do not always occur with the associated func- tion, but can occur with the subsequent function. The requested para- meter does not have an appropriate value, or is invalid (ptrace()). On a terminal, EIO means the following: the process is running in the background, the process did a write() to its controlling terminal, and TOSTOP is set on the terminal, but the process is neither ignoring nor blocking SIGTTOU, and the process group of the process is orphaned, i.e. a child of pid 1. Indicates that the socket is already connected. Indicates either that the request was for a write access to a file but the specified filename was actually a directory, or that the function was trying to rename a directory as a file. Indicates that too many links were encountered in translating a pathname. Indicates one or more of the following errors: Too many file descriptors are open (ex- ceeding OPEN_MAX). No space remains in the mount table. The attempt to attach a shared memory region exceeded the maximum number of at- tached regions allowed for any one process. This error indicates that a per process limit has been exceeded. See [ENFILE] for the case when a system-wide limit has been ex- ceeded. Indicates that the number of links would exceed LINK_MAX. Indicates that the message is too large to be sent all at once, as the socket requires. Indicates that the number of timers exceeds the value defined by the TIMER_MAX system variable. This error is available only in the realtime kernel. Indicates that the pathname argument exceeds PATH_MAX (currently 1024), or a pathname component exceeds NAME_MAX (255). Indi- cates that a socket operation has encountered a network that is down. Indicates that the network connection dropped when the remote host reset it by rebooting. Indicates that no route to the network or host exists. Indicates either that the system file table is full, or that there are too many files currently open in the system. This error indicates that a system-wide limit has been exceeded. See [EMFILE] for the case when a per process limit has been ex- ceeded. Indicates insufficient resources, such as buffers, to complete the call. Typically, a call used with sockets has failed due to a shortage of message or send/receive buffer space. Indicates that there is no message on the stream head read queue. Indicates one or more of the following errors: The file descriptor refers to an object that cannot be mapped. The requested block-special device file does not exist. A file sys- tem is unmounted. Indicates one or more of the following er- rors: The specified file pathname or directory pathname does not exist or points to an empty string. The O_CREAT flag is set and the named file or path prefix does not exist (open()). A mes- sage queue identifier does not exist for a message key identi- fier and the IPC_CREAT flag is not set for the function (msgget()). A semaphore ID does not exist for a semaphore key identifier and the IPC_CREAT flag is not set for the function (semget()). A shared memory region ID does not exist for a shared memory region key identifier and the IPC_CREAT flag is set for the function (shmeget()). Indicates that the specified file has appropriate access permissions but has an improper for- mat, such as an unrecognizable object file format. Indicates that the lock table is full because too many regions are already locked, or satisfying a lock (or unlock) request would result in the number of locked regions in the system exceeding a system- imposed limit. Indicates that insufficient memory is available for the requested function. This error may indicate one or more of the following errors: Mapped region attribute was set and part of the specified address range is already allocated (mmap()). The specified range is invalid for a process's ad- dress space or the range specifies one or more unmapped pages (msync()). A new semaphore could not be created (msem_init()). Indicates that a message of the requested type does not exist and the IPC_NOWAIT flag is set. Indicates that the requested socket option is unknown and the protocol is unavailable. Indi- cates one or more of the following errors: Not enough space to extend the file system or device for write operations on a file, directory, or both. The madvise() function tried to reserve re- sources that were not available to be reserved. The system-im- posed limit of the maximum number of allowed message queue iden- tifiers has been exceeded (msgget()). An attempt to create a semaphore ID exceeded the system-wide limit on the semaphore ta- ble (semget()). An attempt to create a new shared memory region ID exceeded the system-wide limit of maximum IDs (shmget()). The system-defined limit on the number of processes using SEM_UNDO was exceeded (semop()). Indicates that no more STREAMS resources are available. Indicates that the file descriptor is not associated with a stream. Indicates that the specified package does not contain the named symbol. Indicates an attempt to use a system call that is not implemented. Indicates that the specified parameter is not or does not point to a block de- vice. Indicates that the socket is not connected. Indicates that a component of the path parameter exists but is not a di- rectory, or an operation is being performed from a directory to a nonexistent directory. Indicates that a directory is not empty during a file system operation that requires an empty di- rectory. Indicates that the specified socket parameter refers to a file, not a socket. Indicates one or more of the following errors: The file descriptor's file is not a terminal. The call- ing process does not have a controlling terminal. The control- ling terminal is no longer associated with the calling process session (tcsetpgrp()). The specified open descriptor is not as- sociated with a character-special device or the specified re- quest does not apply to the kind of object that the specified open descriptor references (ioctl()). Indicates one or more of the following errors: The specified address, major device num- ber, or channel is out of valid range. No more channels are available (open()). The named file is a character-special or block-special file and the associated device does not exist (open()). The O_NONBLOCK flag is set, the named file is FIFO, O_WRONLY is set, and no process has the file open for reading (open()). The specified tape drive is offline or a disk pack is not loaded in the specified disk drive. Indicates either that the socket does not support the requested operation, or that the socket cannot accept the connection. Indicates that the func- tion attempted to perform an operation for which it did not have appropriate privileges, or the caller was not the owner of the requested element or superuser. This error may also indicate one or both of the following: The calling process was not in the same session as the target process (setpgid()). The calling process is already the process group leader or the process group ID of a process other than the calling process matches the process ID of the calling process (setsid()). Indicates that the selected protocol family is unconfigured or unimplemented. Indicates that an attempt was made to write to a pipe or FIFO that was not open for reading by any process. Indicates that a Remote Procedure Call (RPC) requested a server to perform an unimplemented procedure. The error is through NFS. Indicates that a Remote Procedure Call (RPC) requested a server to execute an unsupported version of a program. The error is through NFS. Indicates that a Remote Procedure Call (RPC) requested a server to execute an unsupported program. The error is through NFS. Indicates an error in STREAMS protocol. Indicates that either the socket or the protocol is not supported. Indicates that the specified protocol does not support the requested type of socket. Indicates one or more of the following errors: The re- sult would exceed the system-defined limits or cause an overflow (value too large) or an underflow (value too small). A speci- fied parameter is greater than 0 (zero) but smaller than the length of the pathname + 1 (getcwd()). The symbol value cannot be represented as an absolute value. The magnitude of x is such that total or partial loss of significance resulted. Indicates a server's attempt to handle an NFS request by generating a re- quest to another NFS server, which is not allowed. Indicates one or more of the following errors: The operation requested was to be performed on a read-only file system. An attempt was made to activate a paging file on a read-only file system. The named file resides on a read-only file system and the file type re- quires write access. Indicates that a Remote Procedure Call (RPC) requested a server to use an unsupported version of the RPC mechanism. The error is through NFS. Indicates that data cannot be sent to a socket because it has been shut down. Indi- cates that the socket type is not supported. Indicates that an invalid seek operation was requested for a pipe (FIFO), socket, or multiplexed special file (lseek()). Indicates one or more of the following errors: The requested process or child process ID is invalid or not in use. No disk quota is found for the speci- fied user. The specified thread ID does not refer to an exist- ing thread. Indicates one or more of the following errors: An opened file was deleted by the server or another client. The directory that contains an opened file was either unmounted or unexported by the server. A client cannot open a file because the server has unmounted or unexported the remote directory. Indicates that a system call timed out in a STREAMS operation. Indicates one or more of the following errors: The requested at- tempt at a connection timed out before a connection was estab- lished. For NFS files that are mounted with the soft option, either the server is down or there is a network problem. Indi- cates that there are too many references to some kernel-level object. The associated resource has presumably run out. Indi- cates that there are too many users, as evidenced by a full quota table. Indicates a version number mismatch between loader interfaces, such as between an old library and a new loader when the way libraries work has been changed. Indicates one or more of the following errors: The socket is marked nonblocking and no connections are waiting to be accepted. The socket is marked nonblocking and connection cannot be immediately completed. The file is locked and the function is instructed not to block when locking. The socket is marked as nonblocking and no space is available for the specified function. See also [EAGAIN]. Indicates either that a hard link was at- tempted between two file systems, or that a filename to be re- named by rename() is on a different file system from the link to which it is to be renamed. RELATED INFORMATION cc(1), csh(1), intro(3), perror(3), errno(5), tty(7). delim off intro(2)