Content-type: text/html Man page of intro

intro

Section: System Calls (2)
Index Return to Main Contents
 

NAME

intro, errno - Introduction to system calls  

SYNOPSIS

#include <errno.h>


 

DESCRIPTION

Section 2 describes the Tru64 UNIX system calls, which are the entries 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 effective 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 information, 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 execute.
 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 information 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 effective 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 access 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 image and the file system is mounted no execute, execute permission is denied. If the process's effective UID is not root, the process is attempting to access a character or block special device, and the file system is mounted with nodev, access is denied. 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 nosuid, 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 creator. 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 beginning 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 directory itself.
A slash by itself names the root directory. A null pathname is invalid. Each active process in the system is uniquely identified by a positive integer called a process ID. The range of this ID is from 0 to {PROC_MAX}. Each active process is a member 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 accounting 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 considered 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 recipients.
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 communications 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 chosen from the address family in which the socket was created. Those processes that have a process ID of 0, 1, and 2 are considered 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 privileges 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 arbitrate 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.
 

ERRORS

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 variable. The remainder of this section lists in alphabetical order the symbolic codes for errno values, along with associated messages and explanations. Some codes represent more than one type of error. For example, [E2BIG] can indicate that the specified argument size has exceeded 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 predefined 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 directory or process's sensitivity level. The requested file is not available 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 already 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 temporarily unavailable. This error may also indicate one or both of the following: 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 operation was attempted on a non-blocking object for which an operation was already in progress. Indicates that a socket or file descriptor parameter 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) operation 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. Indicates 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 exceeds 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. Indicates 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 character sequence was detected. Indicates that a lengthy operation on a non-blocking object is now in progress. Indicates that an interruptible 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 error 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 handler 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 function, but can occur with the subsequent function. The requested parameter 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 (exceeding OPEN_MAX). No space remains in the mount table. The attempt to attach a shared memory region exceeded the maximum number of attached 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 exceeded. 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). Indicates 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 exceeded. 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 system is unmounted. Indicates one or more of the following errors: 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 message queue identifier does not exist for a message key identifier 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 format, 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 address 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. Indicates 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 resources that were not available to be reserved. The system-imposed limit of the maximum number of allowed message queue identifiers has been exceeded (msgget()). An attempt to create a semaphore ID exceeded the system-wide limit on the semaphore table (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 device. Indicates that the socket is not connected. Indicates that a component of the path parameter exists but is not a directory, 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 directory. 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 calling process does not have a controlling terminal. The controlling terminal is no longer associated with the calling process session (tcsetpgrp()). The specified open descriptor is not associated with a character-special device or the specified request 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 number, 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 function 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 result would exceed the system-defined limits or cause an overflow (value too large) or an underflow (value too small). A specified 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 request 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 requires 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. Indicates 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 specified user. The specified thread ID does not refer to an existing 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 attempt at a connection timed out before a connection was established. For NFS files that are mounted with the soft option, either the server is down or there is a network problem. Indicates that there are too many references to some kernel-level object. The associated resource has presumably run out. Indicates 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 attempted between two file systems, or that a filename to be renamed by rename() is on a different file system from the link to which it is to be renamed.
 

SEE ALSO

cc(1), csh(1), intro(3), perror(3), errno(5), tty(7)


 

Index

NAME
SYNOPSIS
DESCRIPTION
DEFINITIONS
RETURN VALUES
ERRORS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 02:40:16 GMT, October 02, 2010