intro(2)intro(2)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 informa‐
tion 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 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
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 permis‐
sion 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 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 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 consid‐
ered 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 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
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 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 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 usu‐
ally -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 vari‐
able. 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 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
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 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 param‐
eter 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 unavail‐
able. 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 omit‐
ted 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. Indi‐
cates 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 num‐
ber 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 sup‐
ply a handler for the SIGKILL, SIGSTOP, and SIGCONT signals (sigac‐
tion()). 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 associ‐
ated 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 file name was actually a directory, or that
the function was trying to rename a directory as a file.
For an NFS client, an attempt was made to read a directory that
resides on an NFS server by using a function, such as read(). In
this case, readdir() or getdirentries() is required to read the
directory. 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). 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
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 sys‐
tem 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 iden‐
tifier 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
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. 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
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. Indi‐
cates 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 direc‐
tory is not empty during a file system operation that requires
an empty directory. Indicates that the specified socket parame‐
ter refers to a file, not a socket. Indicates one or more of
the following errors: The file descriptor's file is not a termi‐
nal. The calling process does not have a controlling terminal.
The controlling terminal is no longer associated with the call‐
ing process session (tcsetpgrp()). The specified open descrip‐
tor 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 chan‐
nels are available (open()). The named file is a character-spe‐
cial 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 indi‐
cate 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()). Indi‐
cates that the selected protocol family is unconfigured or unim‐
plemented. 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 sup‐
ported. Indicates that the specified protocol does not support
the requested type of socket. Indicates one or more of the fol‐
lowing 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 signifi‐
cance 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 sys‐
tem. 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 sup‐
ported. 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 refer‐
ences 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 speci‐
fied 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 ALSOcc(1), csh(1), intro(3), perror(3), errno(5), tty(7)intro(2)