INTRO(2) INTRO(2)
NAME
intro - introduction to system calls and error numbers
SYNOPSIS
#include <errno.h>
DESCRIPTION
This section describes all of the system calls. 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 owner
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 file name is specified and the
file should exist but doesn't, or when one of the
directories in a path name 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
Page 1 May 1989
INTRO(2) INTRO(2)
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 which does
not exist, or beyond the limits of the device. It may
also occur when, for example, a tape drive is not on-
line or no disk pack is loaded on a drive.
7 E2BIG Arg list too long
An argument list longer than 5,120 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 which is open only for writing (respectively,
reading).
10 ECHILD No child processes
A wait was executed by a process that had no existing
or unwaited-for child processes.
11 EAGAIN No more processes
A fork 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
Page 2 May 1989
INTRO(2) INTRO(2)
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). If this
error occurs on a resource associated with Remote File
Sharing (RFS), it indicates a memory depletion wich may
be temporary, dependent on system activity at the time
the call was invoked.
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, e.g., 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 dismount a device on
which there is an active file (open file, current
directory, mounted-on file, active text segment). It
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, e.g., link(2).
18 EXDEV Cross-device link
A link to a file on another device was attempted.
Page 3 May 1989
INTRO(2) INTRO(2)
19 ENODEV No such device
An attempt was made to apply an inappropriate system
call to a device; e.g., 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 (e.g., dismounting 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 20)
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 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
Page 4 May 1989
INTRO(2) INTRO(2)
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 to make more than the maximum number of
links (1024) 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 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)].
36 EIDRM Identifier removed
This error is returned to processes that resume
Page 5 May 1989
INTRO(2) INTRO(2)
execution due to the removal of an identifier from the
file system's name space [see msgctl(2), semctl(2), and
shmctl(2)].
37-44 Reserved numbers
45 EDEADLK Deadlock
A deadlock situation was detected and avoided. This
error pertains to file and record locking.
46 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.
60 ENOSTR Not a stream
A putmsg(2) or getmsg(2) system call was attempted on a
file descriptor that is not a STREAMS device.
62 ETIME Stream ioctl timeout
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 timeout value that is too short for the
specific operation. The status of the ioctl(2)
operation is indeterminate.
63 ENOSR No stream resources
During a STREAMS open(2), either no STREAMS queues or
no STREAMS head data structures were available.
64 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.
65 ENOPKG No package
This error occurs when users attempt to use a system
call from a package which has not been installed.
Page 6 May 1989
INTRO(2) INTRO(2)
66 EREMOTE Resource is remote
This error is RFS specific. It occurs when users try to
advertise a resource which is not on the local machine,
or try to mount/unmount a device (or pathname) that is
on a remote machine.
67 ENOLINK Virtual circuit is gone
This error is RFS specific. It occurs when the link
(virtual circuit) connecting to a remote machine is
gone.
68 EADV Advertise error
This error is RFS specific. It occurs when users try to
advertise a resource which has been advertised already,
or try to stop the RFS while there are resources still
advertised, or try to force unmount a resource when it
is still advertised.
69 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.
70 ECOMM Communication error
This error is RFS specific. It occurs when trying to
send messages to remote machines but no virtual circuit
can be found.
71 EPROTO Protocol error
Some protocol error occurred. This error is device
specific, but is generally not related to a hardware
failure.
74 EMULTIHOP Multihop attempted
This error is RFS specific. It occurs when users try to
access remote resources which are not directly
accessible.
77 EBADMSG Bad message
During a read(2), getmsg(2), or ioctl(2) I_RECVFD
Page 7 May 1989
INTRO(2) INTRO(2)
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.
78 ENAMETOOLONG
A component of a pathname exceeded NAME_MAX characters
or an entire pathname exceeded PATH_MAX characters.
83 ELIBACC Cannot access a needed shared library
Trying to exec(2) an a.out that requires a shared
library (to be linked in) and the shared library
doesn't exist or the user doesn't have permission to
use it.
84 ELIBBAD Accessing a corrupted shared library
Trying to exec(2) an a.out that requires a shared
library (to be linked in) and exec(2) could not load
the shared library. The shared library is probably
corrupted.
85 ELIBSCN .lib section in a.out corrupted
Trying to exec(2) an a.out that requires a shared
library (to be linked in) and there was erroneous data
in the .lib section of the a.out. The .lib section
tells exec(2) what shared libraries are needed. The
a.out is probably corrupted.
86 ELIBMAX Attempting to link in more shared libraries
than system limit
Trying to exec(2) an a.out that requires more shared
libraries (to be linked in) than is allowed on the
current configuration of the system. See the System
Administrator's Guide.
87 ELIBEXEC Cannot exec a shared library directly
Trying to exec(2) a shared library directly. This is
Page 8 May 1989
INTRO(2) INTRO(2)
not allowed.
89 ENOSYS System call not supported by the system.
90 ELOOP Unable to parse a symbolic link.
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)].
Session ID Each active process is a member of a group which
is identified by a positive integer called the Session ID.
This ID is the process ID of the session leader. This
grouping may be used to terminate or continue certain
processes upon termination of one of the processes in the
group. See exit(2), signals(2), and setsid(2).
Controlling Process A controlling process is a session
leader that has opened a terminal.
Orphaned Process Group An orphaned process group is a
process group which has no member whose parent is a member
of another process group in the same session. A member of
Page 9 May 1989
INTRO(2) INTRO(2)
such a group is not allowed to be in a stopped state.
Real User ID and Real Group ID Each user allowed on the
system is identified by a positive integer (0 to 65535)
called a real user ID.
Each user is also a member of at least one group. A group
is identified by a positive integer called a group ID.
An active process has a real user ID and real group ID that
are set to the real user ID and real group ID, respectively,
of the user responsible for the creation of the process.
Effective User ID and Effective Group ID An active process
has an effective user ID and an effective group ID that are
used to determine file access permissions (see below). The
effective user ID and effective group ID are equal to the
process's real user ID and real group ID respectively,
unless the process or one of its ancestors evolved from a
file that had the set-user-ID bit or set-group 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 The processes with a process ID of 0 and a
process ID of 1 are special processes and are referred to as
proc0 and proc1.
Proc0 is the scheduler. Proc1 is the initialization process
(init). Proc1 is the ancestor of every other process in the
system and is used to control the process structure.
File Descriptor A file descriptor is a small integer used to
Page 10 May 1989
INTRO(2) INTRO(2)
do I/O on a file. The value of a file descriptor is from 0
to (NOFILES - 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 14 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.
Path Name and Path Prefix 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.
If a path name 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 path name 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
Page 11 May 1989
INTRO(2) INTRO(2)
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 path
name 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, and 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, and 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.
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
Page 12 May 1989
INTRO(2) INTRO(2)
associated with it. The data structure is referred to as
msqid_ds and contains the following members:
struct ipc_perm msg_perm;
ushort msg_qnum;
ushort msg_qbytes;
ushort msg_lspid;
ushort msg_lrpid;
time_t msg_atime;
time_t msg_causec;
time_t msg_dtime;
time_t msg_dvsec;
time_t msg_ctime;
time_t msg_cusec;
msgperm is an ipc_perm structure that specifies the message
operation permission (see below). This structure includes
the following members:
uid_t cuid; /* creator user id */
gid_t cgid; /* creator group id */
uid_t uid; /* user id */
gid_t gid; /* group id */
mode_t mode; /* r/w permission */
ushort seq; /* slot usage sequence # */
key_t key; /* key */
msg *msgfirst
is a pointer to the first message on the queue.
msg *msglast
is a pointer to the last message on the queue.
msgcbytes
is the current number of bytes on the queue.
msgqnum
is the number of messages currently on the queue.
msgqbytes
Page 13 May 1989
INTRO(2) INTRO(2)
is the maximum number of bytes allowed on the queue.
msglspid
is the process id of the last process that performed a
msgsnd operation.
msglrpid
is the process id of the last process that performed a
msgrcv operation.
msgatime
and msgausec are the seconds and microseconds,
respectively, of the time of the last msgsnd operation.
msgstime
and msgsusec are the seconds and microseconds,
respectively, of the time of the last msgrcv operation
msgctime
and msgcusec are the seconds and microseconds,
respectively, of 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 a 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.
Page 14 May 1989
INTRO(2) INTRO(2)
The effective user ID of the process matches
msgperm.cuid or msgperm.uid in the data structure
associated with msqid and the appropriate bit of the
``user'' portion (0600) of msgperm.mode is set.
The effective group ID of the process matches
msgperm.cgid or msgperm.gid and the appropriate bit
of the ``group'' portion (060) of msgperm.mode is set.
The appropriate bit of the ``other'' portion (006) of
msgperm.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_ousec;
time_t sem_ctime; /* last change time */
/* Times measured in secs since */
/* 00:00:00 GMT, Jan. 1, 1970 */
time_t sem_cusec;
semperm is an ipc_perm structure that specifies the
semaphore operation permission (see below). This structure
includes the following members:
uid_t uid; /* user id */
gid_t gid; /* group id */
uid_t cuid; /* creator user id */
gid_d cgid; /* creator group id */
mode_t mode; /* r/a permission */
Page 15 May 1989
INTRO(2) INTRO(2)
ushort seq; /* slot usage sequence number */
key_t key; /* key */
semnsems
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.
semotime
and semousec are the seconds and microseconds,
respectively, of the time of the last semop(2)
operation.
semctime
and semcusec are the seconds and microseconds,
respectively, of 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 which 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.
Page 16 May 1989
INTRO(2) INTRO(2)
semzcnt
is a count of the number of processes that are
currently suspended awaiting this semaphore's semval to
become zero.
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
semperm.cuid or semperm.uid in the data structure
associated with semid and the appropriate bit of the
``user'' portion (0600) of semperm.mode is set.
The effective group ID of the process matches
semperm.cgid or semperm.gid and the appropriate bit
of the ``group'' portion (060) of semperm.mode is set.
The appropriate bit of the ``other'' portion (006) of
semperm.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
Page 17 May 1989
INTRO(2) INTRO(2)
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 */
pid_t shm_lpid; /* pid of last operation */
pid_t shm_cpid; /* creator pid */
ushort shm_nattch; /* number of current attaches */
time_t shm_atime; /* last attach time */
time_t shm_ausec;
time_t shm_dtime; /* last detach time */
time_t shm_dvsec;
time_t shm_ctime; /* last change time */
time_t shm_cusec; /* Times measured in secs since */
/* 00:00:00 GMT, Jan. 1, 1970 */
shmperm is an ipc_perm structure that specifies the shared
memory operation permission (see below). This structure
includes the following members:
uid_t cuid; /* creator user id */
gid_t cgid; /* creator group id */
uid_t uid; /* user id */
gid_t gid; /* group id */
mode_t mode; /* r/w permission */
ushort seq; /* slot usage sequence # */
key_t key; /* key */
shmsegsz
specifies the size of the shared memory segment in
bytes.
shmcpid
is the process id of the process that created the
shared memory identifier.
Page 18 May 1989
INTRO(2) INTRO(2)
shmlpid
is the process id of the last process that performed a
shmop(2) operation.
shmnattch
is the number of processes that currently have this
segment attached.
shmatime
and shmausec are the seconds and microseconds,
respectively, of the time of the last shmat(2)
operation,
shmdtime
and shmdusec are the seconds and microseconds,
respectively, of the time of the last shmdt(2)
operation.
shmctime
and shmausec are the seconds and microseconds,
respectively, of 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:
Page 19 May 1989
INTRO(2) INTRO(2)
The effective user ID of the process is super-user.
The effective user ID of the process matches
shmperm.cuid or shmperm.uid in the data structure
associated with shmid and the appropriate bit of the
``user'' portion (0600) of shmperm.mode is set.
The effective group ID of the process matches
shmperm.cgid or shmperm.gid and the appropriate bit
of the ``group'' portion (060) of shmperm.mode is set.
The appropriate bit of the ``other'' portion (06) of
shmperm.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.
Page 20 May 1989
INTRO(2) INTRO(2)
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
which 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.
Page 21 May 1989
INTRO(2) INTRO(2)
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.
SEE ALSO
intro(3).
Page 22 May 1989