INTRO(2) System Calls INTRO(2)
NAME
intro - introduction to system calls and error numbers
SYNOPSIS
#include <sys/errno.h>
DESCRIPTION
This section provides an overview of the GNO system calls, their error
returns, and other common definitions and concepts. Some functions
listed in this chapter are not actually implemented as kernel traps,
but have been listed as such because they would be system calls on a
traditional Unix system.
The SYNOPSIS section of each manual page gives the prototype for the
function(s) described, along with a listing of the header files which
provide the prototypes. The sequence of header file inclusion may be
important, so they should be included in the sequence given.
The DESCRIPTION section gives the detailed description of the system
call.
Reference may be made to symbolic links or other features or functions
that are either unimplemented or otherwise unavailable under GNO. This
information has often been obtained from the original BSD manual pages.
In most cases such information has been retained in the GNO manual
pages either because such functionality is planned or because the in‐
formation is relevent to code intended to run on other BSD operating
systems.
DIAGNOSTICS
Nearly all of the system calls provide an error number in the external
variable errno, which is defined as:
extern int errno;
When a system call detects an error, it returns an integer value indi‐
cating failure (usually -1) and sets the variable errno accordingly.
(This allows interpretation of the failure on receiving a -1 and to
take action accordingly.) Successful calls never set errno; once set,
it remains until another error occurs. It should only be examined af‐
ter an error. Note that a number of system calls overload the meanings
of these error numbers, and that the meanings must be interpreted ac‐
cording to the type and circumstances of the call.
The following is a complete list of the errors used in GNO and their
names as given in <sys/errno.h>. The first twelve (up to ENOSPC) are
also used by the ORCA/Shell.
ENOERR -- Error 0
Not used.
EDOM -- Numerical argument out of domain
A numerical input argument was outside the defined domain
of the mathematical function.
ERANGE -- Numerical result out of range
A numerical result of the function was too large to fit
in the available space (perhaps exceeded precision).
ENOMEM -- Cannot allocate memory
The new process image required more memory than was al‐
lowed by the hardware or by system-imposed memory manage‐
ment constraints.
ENOENT -- No such file or directory
A component of a specified pathname did not exist, or the
pathname was an empty string.
EIO -- Input/output error
Some physical input or output error occurred.
Any GS/OS errors that occur and which do not have any
other suitable errno counterparts will be mapped to this
error.
EINVAL -- Invalid argument
Some invalid argument was supplied. (For example, speci‐
fying an undefined signal to a signal or kill function).
EBADF -- Bad file descriptor
A file descriptor argument was out of range, referred to
no open file, or a read (write) request was made to a
file that was only open for writing (reading).
EMFILE -- Too many open files
(The limit on the number of open files per process is 32.
This is configurable under some versions of Unix, but not
under GNO.) Getdtablesize(2) will obtain the current
limit.
EACCES -- Permission denied
An attempt was made to access a file in a way forbidden
by its file access permissions.
The default ORCA/C header files use EACCESS (with two
S´s) for this macro, but GNO does not since it causes a
conflict with standard macros in the <arpa/tftp.h>
header.
EEXIST -- File exists
An existing file was mentioned in an inappropriate con‐
text.
ENOSPC -- Device out of space
A write to an ordinary file, the creation of a directory
or symbolic link, or the creation of a directory entry
failed because no more disk blocks were available on the
file system, or (for filesystems using inodes) the allo‐
cation of an inode for a newly created file failed be‐
cause no more inodes were available on the file system.
EPERM -- Operation not permitted
An attempt was made to perform an operation limited to
processes with appropriate privileges or to the owner of
a file or other resources.
ESRCH -- No such process
No process could be found corresponding to that specified
by the given process ID.
EINTR -- Interrupted function call
An asynchronous signal (such as SIGINT or SIGQUIT) was
caught by the process during the execution of an inter‐
ruptible function. If the signal handler performs a nor‐
mal return, the interrupted function call will seem to
have returned the error condition.
E2BIG -- Arg list too long
The number of bytes used for the argument and environment
list of the new process exceeded the current limit of
4096 bytes (NCARGS in <sys/param.h>).
ENOEXEC -- Exec format error
A request was made to execute a file that, although it
has the appropriate permissions, was not in the format
required for an executable file.
ECHILD -- No child processes
A wait or waitpid function was executed by a process that
had no existing or unwaited-for child processes.
EAGAIN -- Resource temporarily unavailable
This is a temporary condition and later calls to the same
routine may complete normally.
ENOTDIR -- Not a directory
A component of the specified pathname existed, but it was
not a directory, when a directory was expected.
ENOTTY -- Inappropriate ioctl for device
A control function (see ioctl(2)) was attempted for a
file or special device for which the operation was inap‐
propriate.
EPIPE -- Broken pipe
A write on a pipe, socket or FIFO for which there is no
process to read the data.
ESPIPE -- Illegal seek
An lseek function was issued on a socket, pipe or FIFO.
ENOTBLK -- Not a block device
A block device operation was attempted on a non-block de‐
vice or file.
EISDIR -- Is a directory
An attempt was made to open a directory with write mode
specified.
ENOTSOCK -- Socket operation on non-socket
Self-explanatory.
EDESTADDRREQ -- Destination address required
A required address was omitted from an operation on a
socket.
EMSGSIZE -- Message too long
A message sent on a socket was larger than the internal
message buffer or some other network limit.
EPROTOTYPE -- Protocol wrong type for socket
A protocol was specified that does not support the seman‐
tics of the socket type requested. For example, you can‐
not use the ARPA Internet UDP protocol with type
SOCK_STREAM.
ENOPROTOOPT -- Protocol not available
A bad option or level was specified in a getsockopt(2) or
setsockopt(2) call.
EPROTONOSUPPORT -- Protocol not supported
The protocol has not been configured into the system or
no implementation for it exists.
ESOCKTNOSUPPORT -- Socket type not supported
The support for the socket type has not been configured
into the system or no implementation for it exists.
EOPNOTSUPP -- Operation not supported
The attempted operation is not supported for the type of
object referenced. Usually this occurs when a file de‐
scriptor refers to a file or socket that cannot support
this operation, for example, trying to accept a connec‐
tion on a datagram socket.
EPFNOSUPPORT -- Protocol family not supported
The protocol family has not been configured into the sys‐
tem or no implementation for it exists.
EAFNOSUPPORT -- Address family not supported by protocol family
An address incompatible with the requested protocol was
used. For example, you shouldn't necessarily expect to
be able to use NS addresses with ARPA Internet protocols.
EADDRINUSE -- Address already in use
Only one usage of each address is normally permitted.
EADDRNOTAVAIL -- Cannot assign requested address
Normally results from an attempt to create a socket with
an address not on this machine.
ENETDOWN -- Network is down
A socket operation encountered a dead network.
ENETUNREACH -- Network is unreachable
A socket operation was attempted to an unreachable net‐
work.
ENETRESET -- Network dropped connection on reset
The host you were connected to crashed and rebooted.
ECONNABORTED -- Software caused connection abort
A connection abort was caused internal to your host ma‐
chine.
ECONNRESET -- Connection reset by peer
A connection was forcibly closed by a peer. This nor‐
mally results from a loss of the connection on the remote
socket due to a timeout or a reboot.
ENOBUFS -- No buffer space available
An operation on a socket or pipe was not performed be‐
cause the system lacked sufficient buffer space or be‐
cause a queue was full.
EISCONN -- Socket is already connected
A connect request was made on an already connected
socket; or, a sendto or sendmsg request on a connected
socket specified a destination when already connected.
ENOTCONN -- Socket is not connected
An request to send or receive data was disallowed because
the socket was not connected and (when sending on a data‐
gram socket) no address was supplied.
ESHUTDOWN -- Cannot send after socket shutdown
A request to send data was disallowed because the socket
had already been shut down with a previous shutdown(2)
call.
ETIMEDOUT -- Operation timed out
A connect or send request failed because the connected
party did not properly respond after a period of time.
(The timeout period is dependent on the communication
protocol.)
ECONNREFUSED -- Connection refused
No connection could be made because the target machine
actively refused it. This usually results from trying to
connect to a service that is inactive on the foreign
host.
EWOULDBLOCK -- Operation would block
An operation was attempted on a non-blocking file de‐
scriptor that would cause the calling process to block.
EINPROGRESS -- Operation now in progress
An operation that takes a long time to complete (such as
a connect(2)) was attempted on a non-blocking object (see
fcntl(2)).
EALREADY -- Operation already in progress
An operation was attempted on a non-blocking object that
already had an operation in progress.
EFAULT -- Bad address
The system detected an invalid address in attempting to
use an argument of a call.
ENODEV -- Operation not supported by device
An attempt was made to apply an inappropriate function to
a device, for example, trying to read a write-only device
such as a printer.
EHOSTDOWN -- Host is down
A socket operation failed because the destination host
was down.
EHOSTUNREACH -- No route to host
A socket operation was attempted to an unreachable host.
The following errors may be present in various BSD sources, but are not
currently used in GNO:
ENXIO -- No such device or address
Input or output on a special file referred to a device
that did not exist, or made a request beyond the limits
of the device. This error may also occur when, for exam‐
ple, a tape drive is not online or no disk pack is loaded
on a drive.
EDEADLK -- Resource deadlock avoided
An attempt was made to lock a system resource that would
have resulted in a deadlock situation.
EBUSY -- Resource busy
An attempt to use a system resource which was in use at
the time in a manner which would have conflicted with the
request.
EXDEV -- Improper link
A hard link to a file on another file system was at‐
tempted.
ENFILE -- Too many open files in system
Maximum number of file descriptors allowable on the sys‐
tem has been reached and a requests for an open cannot be
satisfied until at least one has been closed.
ETXTBSY -- Text file busy
The new process was a pure procedure (shared text) file
which was open for writing by another process, or while
the pure procedure file was being executed an open call
requested write access.
EFBIG -- File too large
The size of a file exceeded the maximum (about 2.1E9
bytes).
EROFS -- Read-only file system
An attempt was made to modify a file or directory was
made on a file system that was read-only at the time.
EMLINK -- Too many links
Maximum allowable hard links to a single file has been
exceeded (limit of 32767 hard links per file).
ELOOP -- Too many levels of symbolic links
A path name lookup involved more than 8 symbolic links.
ENAMETOOLONG -- File name too long
A component of a path name exceeded 255 (MAXNAMELEN)
characters, or an entire path name exceeded 1023 (MAX‐
PATHLEN-1) characters.
ENOTEMPTY -- Directory not empty
A directory with entries other than . and .. was sup‐
plied to a remove directory or rename call.
EPROCLIM -- Too many processes
EUSERS -- Too many users
The quota system ran out of table entries.
EDQUOT -- Disc quota exceeded
A write to an ordinary file, the creation of a directory
or symbolic link, or the creation of a directory entry
failed because the user's quota of disk blocks was ex‐
hausted, or the allocation of an inode for a newly cre‐
ated file failed because the user's quota of inodes was
exhausted.
ESTALE -- Stale NFS file handle
An attempt was made to access an open file (on an NFS
filesystem) which is now unavailable as referenced by the
file descriptor. This may indicate the file was deleted
on the NFS server or some other catastrophic event oc‐
curred.
EBADRPC -- RPC struct is bad
Exchange of RPC information was unsuccessful.
ERPCMISMATCH -- RPC version wrong
The version of RPC on the remote peer is not compatible
with the local version.
EPROGUNAVAIL -- RPC prog. not avail
The requested program is not registered on the remote
host.
EPROGMISMATCH -- Program version wrong
The requested version of the program is not available on
the remote host RPC.
EPROCUNAVAIL -- Bad procedure for program
An RPC call was attempted for a procedure which doesn't
exist in the remote program.
ENOLCK -- No locks available
A system-imposed limit on the number of simultaneous file
locks was reached.
ENOSYS -- Function not implemented
Attempted a system call that is not available on this
system.
DEFINITIONS
Process ID
Each active process in the system is uniquely identified by a
non-negative integer called a process ID. The range of this ID
is from 0 to 30000.
Parent process ID
A new process is created by a currently active process; (see
fork(2)). The parent process ID of a process is initially the
process ID of its creator. If the creating process exits, the
parent process ID of each child is set to the ID of a system
process, init.
Process Group
Each active process is a member of a process group that is iden‐
tified by a non-negative integer called the process group ID.
This is the process ID of the group leader. This grouping per‐
mits the signaling of related processes (see termios(4)) and the
job control mechanisms of csh(1).
Session
A session is a set of one or more process groups. A session is
created by a successful call to setsid(2), which causes the
caller to become the only member of the only process group in
the new session.
Session leader
A process that has created a new session by a successful call to
setsid(2), is known as a session leader. Only a session leader
may acquire a terminal as its controlling terminal (see
termios(4)).
Controlling process
A session leader with a controlling terminal is a controlling
process.
Controlling terminal
A terminal that is associated with a session is known as the
controlling terminal for that session and its members.
Terminal Process Group ID
A terminal may be acquired by a session leader as its control‐
ling terminal. Once a terminal is associated with a session,
any of the process groups within the session may be placed into
the foreground by setting the terminal process group ID to the
ID of the process group. This facility is used to arbitrate be‐
tween multiple jobs contending for the same terminal; (see
csh(1) and tty(4)).
Orphaned Process Group
A process group is considered to be orphaned if it is not under
the control of a job control shell. More precisely, a process
group is orphaned when none of its members has a parent process
that is in the same session as the group, but is in a different
process group. Note that when a process exits, the parent
process for its children is changed to be init, which is in a
separate session. Not all members of an orphaned process group
are necessarily orphaned processes (those whose creating process
has exited). The process group of a session leader is orphaned
by definition.
Real User ID and Real Group ID
Each user on the system is identified by a positive integer
termed 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
distinguished group is termed the real group ID.
All processes have a real user ID and real group ID. These are
initialized from the equivalent attributes of the process that
created it.
Effective User Id, Effective Group Id, and Group Access List
Access to system resources is governed by two values: the effec‐
tive user ID, and the group access list. The first member of
the group access list is also known as the effective group ID.
(In POSIX.1, the group access list is known as the set of sup‐
plementary group IDs, and it is unspecified whether the effec‐
tive group ID is a member of the list.)
The effective user ID and effective group ID are initially the
process's real user ID and real group ID respectively. Either
may be modified through execution of a set-user-ID or set-group-
ID file (possibly by one its ancestors) (see execve(2)). By
convention, the effective group ID (the first member of the
group access list) is duplicated, so that the execution of a
set-group-ID program does not result in the loss of the original
(real) group ID.
The group access list is a set of group IDs used only in deter‐
mining resource accessibility. Access checks are performed as
described below in ``File Access Permissions''.
Saved Set User ID and Saved Set Group ID
When a process executes a new file, the effective user ID is set
to the owner of the file if the file is set-user-ID, and the ef‐
fective group ID (first element of the group access list) is set
to the group of the file if the file is set-group-ID. The ef‐
fective user ID of the process is then recorded as the saved
set-user-ID, and the effective group ID of the process is
recorded as the saved set-group-ID. These values may be used to
regain those values as the effective user or group ID after re‐
verting to the real ID (see setuid(2)). (In POSIX.1, the saved
set-user-ID and saved set-group-ID are optional, and are used in
setuid and setgid, but this does not work as desired for the su‐
per-user.)
Super-user
A process is recognized as a super-user process and is granted
special privileges if its effective user ID is 0.
Special Processes
The processes with process IDs of 0, 1, and 2 are special.
Process 0 is the scheduler. Process 1 is the initialization
process init, and is the ancestor of every other process in the
system. It is used to control the process structure. Process 2
is the paging daemon.
Descriptor
An integer assigned by the system when a file is referenced by
open(2) or dup(2), or when a socket is created by pipe(2),
socket(2) or socketpair(2), which uniquely identifies an access
path to that file or socket from a given process or any of its
children.
File Name
names consisting of up to 255 (MAXNAMELEN) characters may be
used to name an ordinary file, special file, or directory.
These characters may be selected from the set of all ASCII char‐
acter excluding 0 (NUL) and the ASCII code for / (slash). (The
parity bit, bit 7, must be 0.)
Note that it is generally unwise to use *, ?, [ or ] as part of
file names because of the special meaning attached to these
characters by the shell.
Path Name
A path name is a NULL-terminated character string starting with
an optional slash /, followed by zero or more directory names
separated by slashes, optionally followed by a file name. The
total length of a path name must be less than 1024 (MAXPATHLEN)
characters.
If a path name begins with a slash, the path search begins at
the root directory. Otherwise, the search begins from the cur‐
rent working directory. A slash by itself names the root direc‐
tory. An empty pathname refers to the current directory.
Directory
A directory is a special type of file that contains entries that
are references to other files. Directory entries are called
links. By convention, a directory contains at least two links,
. and .., referred to as dot and dot-dot respectively. Dot
refers to the directory itself and dot-dot refers to its parent
directory.
Root Directory and Current Working Directory
Each process has associated with it a concept of a root direc‐
tory and a current working directory for the purpose of resolv‐
ing path name searches. A process's root directory need not be
the root directory of the root file system.
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 may be changed at some later time
through the chmod(2) call.
File access is broken down according to whether a file may be:
read, written, or executed. Directory files use the execute
permission to control if the directory may 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, 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 if:
The process's effective user ID is that of the super-user.
(Note: even the super-user cannot execute a non-executable
file.)
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, and 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 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.
Otherwise, permission is denied.
Sockets and Address Families
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 include whether messages sent and received at a
socket require the name of the partner, whether communication is
reliable, the format used in naming message recipients, etc.
Each instance of the system supports some collection of socket
types; consult 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.
SEE ALSO
intro(3), perror(3), the GNO Kernel Reference Manual.
GNO 29 January 1997 INTRO(2)
Man(1) output converted with
man2html