INTRO(2) SysV INTRO(2)
NAME
intro - introduction to system calls and error numbers
SYNOPSIS
#include <errno.h>
DESCRIPTION
This section describes all of the system calls. Domain(R)/OS SysV
implements these calls by way of the global library /lib/clib.
Most of these calls have one or more error returns. An error condition
is indicated by an otherwise impossible returned value. This is almost
always -1 or the NULL pointer; the individual descriptions specify the
details. An error number is also made available in the external variable
errno. errno is not cleared on successful calls, so it should be tested
only after an error has been indicated.
Each system call description attempts to list all possible error numbers.
The following is a complete list of the error numbers and their names as
defined in <errno.h>:
1 EPERM Not super-user
Typically, this error indicates an attempt to modify a file in some
way forbidden except to its owner or super-user. It is also
returned for attempts by ordinary users to do things allowed only to
the super-user.
2 ENOENT No such file or directory
This error occurs when a filename is specified and the file should
exist but doesn't, or when one of the directories in a pathname does
not exist.
3 ESRCH No such process
No process can be found corresponding to that specified by pid in
kill(2) or ptrace(2).
4 EINTR Interrupted system call
An asynchronous signal (such as interrupt or quit), which the user
has elected to catch, occurred during a system call. If execution
is resumed after processing the signal, it will appear as if the
interrupted system call returned this error condition.
5 EIO I/O error
Some physical I/O error has occurred. This error may, in some
cases, occur on a call following the one to which it actually
applies.
6 ENXIO No such device or address
I/O on a special file refers to a subdevice that does not exist, or
beyond the limits of the device. This error may also occur when,
for example, a tape drive is not online or no disk pack is loaded on
a drive.
7 E2BIG Arg list too long
An argument list {ARG_MAX} longer than 26620 bytes is presented to a
member of the exec(2) family.
8 ENOEXEC Exec format error
A request is made to execute a file which, although it has the
appropriate permissions, does not start with a valid magic number
(see a.out(4)).
9 EBADF Bad file number
Either a file descriptor refers to no open file, or a read(2)
(respectively, write(2)) request is made to a file that is open only
for writing (respectively, reading).
10 ECHILD No childen
A wait(2) was executed by a process that had no existing or
unwaited-for child processes.
11 EAGAIN No more processes
A fork(2) failed because the system's process table is full or the
user is not allowed to create any more processes. Or a system call
failed because of insufficient memory or swap space.
12 ENOMEM Not enough space
During an exec(2), brk(2), or sbrk(2), a program asks for more space
than the system is able to supply. This may not be a temporary
condition; the maximum space size is a system parameter. The error
may also occur if the arrangement of text, data, and stack segments
requires too many segmentation registers, or if there is not enough
swap space during a fork(2).
13 EACCES Permission denied
An attempt was made to access a file in a way forbidden by the
protection system.
14 EFAULT Bad address
The system encountered a hardware fault in attempting to use an
argument of a system call.
15 ENOTBLK Block device required
A non-block file was mentioned where a block device was required,
for example, in mount(2).
16 EBUSY Device or resource busy
An attempt was made to mount a device that was already mounted, or
an attempt was made to unmount a device on which there is an active
file (open file, current directory, mounted-on file, active text
segment). This error will also occur if an attempt is made to
enable accounting when it is already enabled. The device or
resource is currently unavailable.
17 EEXIST File exists
An existing file was mentioned in an inappropriate context, for
example, link(2).
18 EXDEV Cross-device link
A link to a file on another device was attempted.
19 ENODEV No such device
An attempt was made to apply an inappropriate system call to a
device, for example, read a write-only device.
20 ENOTDIR Not a directory
A non-directory was specified where a directory is required, for
example, in a path prefix or as an argument to chdir(2).
21 EISDIR Is a directory
An attempt was made to write on a directory.
22 EINVAL Invalid argument
Some invalid argument has been specified (for example, unmounting a
non-mounted device, mentioning an undefined signal in signal(2) or
kill(2), reading or writing a file for which lseek(2) has generated
a negative pointer). Also set by the math functions described in
the (3M) entries of this manual.
23 ENFILE File table overflow
The system file table is full, and temporarily no more opens can be
accepted.
24 EMFILE Too many open files
No process may have more than NOFILES (default 128) descriptors open
at a time.
25 ENOTTY Not a character device (or) Not a typewriter
An attempt was made to ioctl(2) a file that is not a special
character device.
26 ETXTBSY Text file busy
An attempt was made to execute a pure-procedure program that is
currently open for writing. Also, an attempt was made to open for
writing or to remove a pure-procedure program that is being
executed.
27 EFBIG File too large
The size of a file exceeded the maximum file size or ULIMIT (see
ulimit(2)).
28 ENOSPC No space left on device
During a write(2) to an ordinary file, there is no free space left
on the device. In fcntl(2), the setting or removing of record locks
on a file cannot be accomplished because there are no more record
entries left on the system.
29 ESPIPE Illegal seek
An lseek(2) was issued to a pipe.
30 EROFS Read-only file system
An attempt to modify a file or directory was made on a device
mounted read-only.
31 EMLINK Too many links
An attempt was made to make more than the maximum number of links
(1,000) to a file.
32 EPIPE Broken pipe
A write on a pipe for which there is no process to read the data.
This condition normally generates a signal; the error is returned if
the signal is ignored.
33 EDOM Math argument
The argument of a function in the math package (3M) is out of the
domain of the function.
34 ERANGE Result too large
The value of a function in the math package (3M) is not
representable within machine precision.
35 EWOULDBLOCK Operation would block
An operation that would cause a process to block was attempted on an
object in non-blocking mode (see fcntl(2)).
35 EDEADLK Operation would deadlock
An operation that would cause a process to deadlock was attempted on
an object in non-blocking mode (see fcntl(2)).
36 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)).
37 EALREADY Operation already in progress
An operation was attempted on a non-blocking object that already had
an operation in progress.
38-61 Unused
Miscellany
62 ELOOP Too many levels of symbolic links
A pathname lookup involved more than eight symbolic links.
63 ENAMETOOLONG File name too long
A component of a pathname exceeded 255 {NAME_MAX} characters, or an
entire pathname exceeded 1023 {PATH_MAX} characters.
64 ENOTEMPTY Directory not empty
A directory with entries other than dot (.) and dot-dot (..) was
supplied to a remove directory or rename call.
65 ENOMSG No message of desired type
An attempt was made to receive a message of a type that does not
exist on the specified message queue (see msgop(2)).
66 EIDRM Identifier removed
This error is returned to processes that resume execution due to the
removal of an identifier from the file system's name space (see
msgctl(2), semctl(2), and shmctl(2)).
67-74 Reserved numbers
75-79 Unused
80 ENOLCK No lock
In fcntl(2), the setting or removing of record locks on a file
cannot be accomplished because there are no more record entries left
on the system.
81 ENOSTR Not a stream
A putmsg(2) or getmsg(2) system call was attempted on a file
descriptor that is not a STREAMS device.
82 ENODATA No data
No-delay I/O has been specified but there's no data.
83 ETIME Stream ioctl time-out
The timer set for a STREAMS ioctl(2) call has expired. The cause of
this error is device specific and could indicate either a hardware
or software failure, or perhaps a time-out value that is too short
for the specific operation. The status of the ioctl(2) operation is
indeterminate.
84 ENOSR No stream resources
During a STREAMS open(2), either no STREAMS queues or no STREAMS
head data structures were available.
92 EPROTO Protocol error
Some protocol error occurred. This error is device specific, but is
generally not related to a hardware failure.
96 EBADMSG Bad message
During a read(2), getmsg(2), or ioctl(2) I_RECVFD system call to a
STREAMS device, something has come to the head of the queue that
can't be processed. That something depends on the system call:
read(2) - control information or a passed file descriptor; getmsg(2)
- passed file descriptor; ioctl(2) - control or data information.
DEFINITIONS
Process ID. Each active process in the system is uniquely identified by
a positive integer called a process ID. The range of this ID is from 1
to 30,000.
Parent Process ID. A new process is created by a currently active
process (see fork(2)). The parent process ID of a process is the process
ID of its creator.
Process Group ID. Each active process is a member of a process group
that is identified by a positive integer called the process group ID.
This ID is the process ID of the group leader. This grouping permits the
signaling of related processes (see kill(2)).
Tty Group ID. 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 terminate a group of related processes upon
termination of one of the processes in the group (see exit(2) and
signal(2)).
Real User, Group, and Organization IDs. Each user allowed on the system
is identified by a positive integer (0 to 65,535) called a real user ID.
Each user is also a member of a group and an organization. The group is
identified by a positive integer called the real group ID. The
organization is identified by a positive integer called the real
organization ID.
An active process has a real user ID, a real group ID, and a real
organization ID that are set to the real user ID, real group ID, and real
organization ID, respectively, of the user responsible for the creation
of the process.
Effective User, Group, and Organization IDs. An active process has an
effective user ID, an effective group ID, and an effective organization
ID that are used to determine file access permissions (see "File Access
Permissions"). The effective user ID, effective group ID, and effective
organization ID are equal to the process' real user ID, real group ID,
and real organization ID, respectively, unless the process or one of its
ancestors evolved from a file that had the set-user-ID, set-group ID, or
set-organization ID bit set (see exec(2)).
Super-user. A process is recognized as a super-user process and is
granted special privileges, such as immunity from file permissions, if
its effective user ID is 0.
Special Processes. Domain/OS SysV has no Process 0; under some
implementations, it 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 null (under
some implementations, Process 2 is the paging daemon).
File Descriptor. A file descriptor is a small integer used to do I/O on
a file. The value of a file descriptor is from 0 to (NOFILE-1). A
process may have no more than NOFILES file descriptors open
simultaneously. A file descriptor is returned by system calls such as
open(2) or pipe(2). The file descriptor is used as an argument by calls
such as read(2), write(2), ioctl(2), and close(2).
File Name. Names consisting of 1 to 255 characters may be used to name
an ordinary file, special file, or directory.
These characters may be selected from the set of all character values
excluding \0 (null) and the ASCII code for / (slash).
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 (see sh(1)). Although permitted, the use of unprintable characters
in file names should be avoided.
Pathname and Path Prefix. A pathname 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 filename.
If a pathname begins with a slash, the path search begins at the "root"
directory. Otherwise, the search begins from the current working
directory.
A slash by itself names the root directory.
Unless specifically stated otherwise, the null pathname is treated as if
it named a non-existent file.
Directory. 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 directory and a current working
directory for the purpose of resolving pathname searches. The root
directory of a process need not be the root directory of the root file
system.
File Access Permissions. Read, write, and execute/search permissions on
a file are granted to a process if one or more of the following are true:
+ The effective user ID of the process is super-user.
+ The effective user ID of the process matches the user ID of the owner
of the file, and the appropriate access bit of the "owner" portion
(0700) of the file mode is set.
+ The effective user ID of the process does not match the user ID of the
owner of the file, the effective group ID of the process matches the
group of the file, and the appropriate access bit of the "group"
portion (0070) of the file mode is set.
+ The effective user ID of the process does not match the user ID of the
owner of the file, the effective group ID of the process does not
match the group ID of the file, and the appropriate access bit of the
"other" portion (0007) of the file mode is set.
Otherwise, the corresponding permissions are denied.
Domain/OS SysV derives file access permissions from Domain/OS "Access
Control Lists" (ACLs). Domain/OS SysV derives permissions for the owner
and group of an object from the analogous entries in the ACL. It derives
permissions for "others," however, from at least two entries in the ACL,
one of which sets the access rights for the organization. For more
information, see the Domain/OS System Administration Guide.
Message Queue Identifier. A message queue identifier (msqid) is a unique
positive integer created by a msgget(2) system call. Each msqid has a
message queue and a data structure associated with it. The data
structure is referred to as msqid_ds and contains the following members:
struct ipc_perm msg_perm;
struct msg *msg_first;
struct msg *msg_last;
ushort msg_cbytes;
ushort msg_qnum;
ushort msg_qbytes;
ushort msg_lspid;
ushort msg_lrpid;
time_t msg_stime;
time_t msg_rtime;
time_t msg_ctime;
msg_perm is an ipc_perm structure that specifies the message
operation permission (see "Message Operation Permissions"). This
structure includes the following members:
ushort cuid; /* creator user id */
ushort cgid; /* creator group id */
ushort uid; /* user id */
ushort gid; /* group id */
ushort mode; /* r/w permission */
ushort seq; /* slot usage sequence # */
key_t key; /* key */
msg *msg_first is a pointer to the first message on the queue.
msg *msg_last is a pointer to the last message on the queue.
msg_cbytes is the current number of bytes on the queue.
msg_qnum is the number of messages currently on the queue.
msg_qbytes is the maximum number of bytes allowed on the queue.
msg_lspid is the process ID of the last process that performed a
msgsnd operation.
msg_lrpid is the process ID of the last process that performed a
msgrcv operation.
msg_stime is the time of the last msgsnd operation.
msg_rtime is the time of the last msgrcv operation
msg_ctime is the time of the last msgctl(2) operation that changed a
member of the above structure.
Message Operation Permissions. In the msgop(2) and msgctl(2) system call
descriptions, the permission required for an operation is given as
"{token}", where "token" is the type of permission needed, interpreted as
follows:
00400 Read by user
00200 Write by user
00040 Read by group
00020 Write by group
00004 Read by others
00002 Write by others
Read and write permissions on an msqid are granted to a process if one or
more of the following are true:
+ The effective user ID of the process is super-user.
+ The effective user ID of the process matches msg_perm.cuid or
msg_perm.uid in the data structure associated with msqid, and the
appropriate bit of the "user" portion (0600) of msg_perm.mode is set.
+ The effective group ID of the process matches msg_perm.cgid or
msg_perm.gid, and the appropriate bit of the "group" portion (060) of
msg_perm.mode is set.
+ The appropriate bit of the "other" portion (006) of msg_perm.mode is
set.
Otherwise, the corresponding permissions are denied.
Semaphore Identifier. A semaphore identifier (semid) is a unique
positive integer created by a semget(2) system call. Each semid has a
set of semaphores and a data structure associated with it. The data
structure is referred to as semid_ds and contains the following members:
struct ipc_perm sem_perm; /* operation permission struct */
struct sem *sem_base; /* ptr to first semaphore in set */
ushort sem_nsems; /* number of sems in set */
time_t sem_otime; /* last operation time */
time_t sem_ctime; /* last change time */
/* Times measured in secs since */
/* 00:00:00 GMT, Jan. 1, 1970 */
sem_perm is an ipc_perm structure that specifies the semaphore
operation permission (see "Semaphore Operation Permissions"). This
structure includes the following members:
ushort uid; /* user id */
ushort gid; /* group id */
ushort cuid; /* creator user id */
ushort cgid; /* creator group id */
ushort mode; /* r/a permission */
ushort seq; /* slot usage sequence number */
key_t key; /* key */
sem_nsems is equal to the number of semaphores in the set. Each
semaphore in the set is referenced by a positive integer referred to
as a sem_num. sem_num values run sequentially from 0 to the value
of sem_nsems minus 1.
sem_otime is the time of the last semop(2) operation.
sem_ctime is the time of the last semctl(2) operation that changed a
member of the above structure.
A semaphore is a data structure called sem that contains the
following members:
ushort semval; /* semaphore value */
short sempid; /* pid of last operation */
ushort semncnt; /* # awaiting semval > cval */
ushort semzcnt; /* # awaiting semval = 0 */
semval is a non-negative integer that is the actual value of the
semphore.
sempid is equal to the process ID of the last process that performed
a semaphore operation on this semaphore.
semncnt is a count of the number of processes that are currently
suspended awaiting this semaphore's semval to become greater than
its current value.
semzcnt is a count of the number of processes that are currently
suspended awaiting this semaphore's semval to become 0.
Semaphore Operation Permissions. In the semop(2) and semctl(2) system
call descriptions, the permission required for an operation is given as
"{token}", where "token" is the type of permission needed interpreted as
follows:
00400 Read by user
00200 Alter by user
00040 Read by group
00020 Alter by group
00004 Read by others
00002 Alter by others
Read and alter permissions on a semid are granted to a process if one or
more of the following are true:
+ The effective user ID of the process is super-user.
+ The effective user ID of the process matches sem_perm.cuid or
sem_perm.uid in the data structure associated with semid, and the
appropriate bit of the "user" portion (0600) of sem_perm.mode is set.
+ The effective group ID of the process matches sem_perm.cgid or
sem_perm.gid, and the appropriate bit of the "group" portion (060) of
sem_perm.mode is set.
+ The appropriate bit of the "other" portion (006) of sem_perm.mode is
set.
Otherwise, the corresponding permissions are denied.
Shared Memory Identifier. A shared memory identifier (shmid) is a unique
positive integer created by a shmget(2) system call. Each shmid has a
segment of memory (referred to as a shared memory segment) and a data
structure associated with it. (Note that these shared memory segments
must be explicitly removed by the user after the last reference to them
is removed.) The data structure is referred to as shmid_ds and contains
the following members:
struct ipc_perm shm_perm; /* operation permission struct */
int shm_segsz; /* size of segment */
struct region *shm_reg; /*ptr to region structure */
char pad[4]; /* for swap compatibility */
ushort shm_lpid; /* pid of last operation */
ushort shm_cpid; /* creator pid */
ushort shm_nattch; /* number of current attaches */
ushort shm_cnattch; /* used only for shminfo */
time_t shm_atime; /* last attach time */
time_t shm_dtime; /* last detach time */
time_t shm_ctime; /* last change time */
/* Times measured in secs since */
/* 00:00:00 GMT, Jan. 1, 1970 */
shm_perm is an ipc_perm structure that specifies the shared memory
operation permission (see below). This structure includes the
following members:
ushort cuid; /* creator user id */
ushort cgid; /* creator group id */
ushort uid; /* user id */
ushort gid; /* group id */
ushort mode; /* r/w permission */
ushort seq; /* slot usage sequence # */
key_t key; /* key */
shm_segsz specifies the size of the shared memory segment in bytes.
shm_cpid is the process ID of the process that created the shared
memory identifier.
shm_lpid is the process ID of the last process that performed a
shmop(2) operation.
shm_nattch is the number of processes that currently have this
segment attached.
shm_atime is the time of the last shmat(2) operation,
shm_dtime is the time of the last shmdt(2) operation.
shm_ctime is the time of the last shmctl(2) operation that changed
one of the members of the above structure.
Shared Memory Operation Permissions. In the shmop(2) and shmctl(2)
system call descriptions, the permission required for an operation is
given as "{token}", where "token" is the type of permission needed
interpreted as follows:
00400 Read by user
00200 Write by user
00040 Read by group
00020 Write by group
00004 Read by others
00002 Write by others
Read and write permissions on a shmid are granted to a process if one or
more of the following are true:
+ The effective user ID of the process is super-user.
+ The effective user ID of the process matches shm_perm.cuid, or
shm_perm.uid in the data structure associated with shmid, and the
appropriate bit of the "user" portion (0600) of shm_perm.mode is set.
+ The effective group ID of the process matches shm_perm.cgid or
shm_perm.gid, and the appropriate bit of the "group" portion (060) of
shm_perm.mode is set.
+ The appropriate bit of the "other" portion (06) of shm_perm.mode is
set.
Otherwise, the corresponding permissions are denied.
STREAMS. A set of kernel mechanisms that support the development of
network services and data communication drivers. It defines interface
standards for character input/output within the kernel and between the
kernel and user level processes. The STREAMS mechanism is composed of
utility routines, kernel facilities, and a set of data structures.
Stream. A Stream is a full-duplex data path within the kernel between a
user process and driver routines. The primary components are a "Stream
head," a "driver," and zero or more "modules" between the stream head and
driver. A Stream is analogous to a shell pipeline except that data flow
and processing are bidirectional.
Stream Head. In a Stream, the Stream head is the end of the Stream that
provides the interface between the Stream and a user process. The
principle functions of the Stream head are processing STREAMS-related
system calls and passing data and information between a user process and
the Stream.
Driver. In a Stream, the driver provides the interface between
peripheral hardware and the Stream. A driver can also be a pseudo-
driver, such as a "multiplexor" or log driver (see log(7)), which is not
associated with a hardware device.
Module. A module is an entity containing processing routines for input
and output data. It always exists in the middle of a Stream, between the
Stream's head and a driver. A module is the STREAMS counterpart to the
commands in a shell pipeline except that a module contains a pair of
functions that allow independent bidirectional downstream""( and
"upstream") data flow and processing.
Downstream. In a Stream, the direction from Stream head to driver.
Upstream. In a Stream, the direction from driver to Stream head.
Message. In a Stream, one or more blocks of data or information, with
associated STREAMS control structures. Messages can be of several
defined types, which identify the message contents. Messages are the
only means of transferring data and communicating within a Stream.
Message Queue. In a Stream, a linked list of messages awaiting
processing by a module or driver.
Read Queue. In a Stream, the message queue in a module or driver
containing messages moving upstream.
Write Queue. In a Stream, the message queue in a module or driver
containing messages moving downstream.
Multiplexor. A multiplexor is a driver that allows Streams associated
with several user processes to be connected to a single driver, or
several drivers to be connected to a single user process. STREAMS does
not provide a general multiplexing driver, but does provide the
facilities for constructing them and for connecting multiplexed
configurations of Streams.
FILES
/lib/clib
SEE ALSO
intro(3).
NOTES
Other implementations may define the following errors:
ENONET Machine is not on the network. This error is Remote File
Sharing (RFS) specific. It occurs when users try to
advertise, unadvertise, mount, or unmount remote resources
while the machine has not done the proper startup to connect
to the network.
ENOPKG No package. This error occurs when users attempt to use a
system call from a package that has not been installed.
EREMOTE Resource is remote. This error is RFS specific. It occurs
when users try to advertise a resource that is not on the
local machine, or try to mount/unmount a device (or pathname)
that is on a remote machine.
ENOLINK Virtual circuit is gone. This error is RFS specific. It
occurs when the link (virtual circuit) connecting to a remote
machine is gone.
EADV Advertise error. This error is RFS specific. It occurs when
users try to advertise a resource that has been advertised
already, or try to stop the RFS while there are resources
still advertised, or try to forcibly unmount a resource when
it is still advertised.
ESRMNT Srmount error. This error is RFS specific. It occurs when
users try to stop RFS while there are resources still mounted
by remote machines.
ECOMM Communication error. This error is RFS specific. It occurs
when users try to send messages to remote machines and no
virtual circuit can be found.
EMULTIHOP Multihop attempted. This error is RFS specific. It occurs
when users try to access remote resources that are not
directly accessible.