intro, errno - Introduction to system calls
#include <errno.h>
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.
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).
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 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
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). 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 systemdefined
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.
cc(1), csh(1), intro(3), perror(3), errno(5), tty(7)
intro(2)
[ Back ] |
