INTRO(S) XENIX System V INTRO(S)
Name
intro - Introduces system services, library routines and
error numbers.
Syntax
#include <errno.h>
Description
This section describes all system services. System services
include all routines or system calls that are available in
the operating system kernel. These routines are available to
a C program automatically as part of the standard library
libc. Other routines are available in a variety of
libraries. On 8086/88, and 286 systems, versions for Small,
Middle, and Large model programs are provided (that is,
three of each library). On 386 systems, Small, Middle, and
Large programs for 286 processes and Small model programs
for 386 processes are provided.
To use routines in a program that are not part of the
standard library libc, the appropriate library must be
linked. This is done by specifying -l name to the compiler
or linker, where name is the name listed below. For example
-l m , and -l termcap are specifications to the linker to
search the named libraries for routines to be linked to the
object module. The names of the available libraries are:
c The standard library containing all system call
interfaces, Standard I/O routines, and other general
purpose services.
m The standard math library.
termcap Routines for accessing the termcap data base
describing terminal characteristics.
curses Screen and cursor manipulation routines.
dbm Data base management routines.
x The standard library.
Most services that are part of the operating system kernel
have one or more error returns. An error condition is
indicated by an otherwise impossible returned value. This
is almost always -1; 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.
All of the possible error numbers are not listed in each
Page 1 (printed 8/7/87)
INTRO(S) XENIX System V INTRO(S)
system call description because many errors are possible for
most of the calls. 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 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 or ptrace.
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. 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 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(F)).
9 EBADF Bad file number:
Either a file descriptor refers to no open file, or a
read (respectively write) request is made to a file
which is open only for writing (respectively reading).
Page 2 (printed 8/7/87)
INTRO(S) XENIX System V INTRO(S)
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.
12 ENOMEM Not enough space:
During an exec, or sbrk, a program asks for more space
than the system is able to supply. This is not 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.
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 nonblock file was mentioned where a block device was
required, e.g., in mount.
16 EBUSY Device busy:
An attempt 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.
17 EEXIST File exists:
An existing file was mentioned in an inappropriate
context, e.g., link.
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; e.g., read a write-only device.
20 ENOTDIR Not a directory:
A nondirectory was specified where a directory is
required, for example, in a path prefix or as an
Page 3 (printed 8/7/87)
INTRO(S) XENIX System V INTRO(S)
argument to chdir(S).
21 EISDIR Is a directory:
An attempt to write on a directory.
22 EINVAL Invalid argument:
An invalid argument (e.g., dismounting a nonmounted
device; mentioning an undefined signal in signal or
kill; reading or writing a file for which lseek has
generated a negative pointer). Also set by the math
functions described in the (S) entries of this manual.
23 ENFILE File table overflow:
The system's table of open files is full and
temporarily no more opens can be accepted.
24 EMFILE Too many open files:
No process may have more than 60 file descriptors open
at a time.
25 ENOTTY Not a character device
26 ETXTBSY Text file busy:
An attempt to execute a pure-procedure program which is
currently open for writing (or reading). Also an
attempt to open for writing a pure-procedure program
that is being executed.
27 EFBIG File too large:
The size of a file exceeded the maximum file size
(1,082,201,088 bytes) or ULIMIT; see ulimit(S).
28 ENOSPC No space left on device:
During a write to an ordinary file, there is no free
space left on the device.
29 ESPIPE Illegal seek:
An lseek 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 (1000) 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.
Page 4 (printed 8/7/87)
INTRO(S) XENIX System V INTRO(S)
33 EDOM Math arg out of domain of func:
The argument of a function in the math package is out
of the domain of the function.
34 ERANGE Math result not representable:
The value of a function in the math package is not
representable within machine precision.
35 EUCLEAN File system needs cleaning:
An attempt was made to mount(S) a file system whose
super-block is not flagged clean.
36 EDEADLOCK Would deadlock:
A process' attempt to lock a file region would cause a
deadlock between processes vying for control of that
region.
36 EDEADLK Would deadlock:
A process' attempt to lock a file region would cause a
deadlock between processes vying for control of that
region.
37 ENOTNAM Not a name file:
A creatsem(S), opensem(S), waitsem(S), or sigsem(S) was
issued using an invalid semaphore identifier.
38 ENAVAIL Not available:
An opensem(S), waitsem(S) or sigsem(S) was issued to a
semaphore that has not been initialized by a call to
creatsem(S). A sigsem was issued to a semaphore out of
sequence; i.e., before the process has issued the
corresponding waitsem to the semaphore. An nbwaitsem
was issued to a semaphore guarding a resource that is
currently in use by another process. The semaphore on
which a process was waiting has been left in an
inconsistent state when the process controlling the
semaphore exits without relinquishing control properly;
i.e., without issuing a waitsem on the semaphore.
39 EISNAM A name file:
A name file (semaphore, shared data, etc.) was
specified when not expected.
43 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(S).
44 EIDRM Identifier removed:
This error is returned to a process that resumes
execution due to the removal of an identifier from the
file system's name space; see msgctl(S), semctl(S), and
Page 5 (printed 8/7/87)
INTRO(S) XENIX System V INTRO(S)
shmctl(S).
45 ENOLCK No locks available:
The system's lock table was full, and a file locking or
unlocking operation was attempted which would have
created an additional lock table entry.
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 0 to 30,000.
Parent Process ID
A new process is created by a currently active process; see
fork(S). 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(S).
Process Group Leader
A process group leader is any process whose process group ID
is the same as its process ID . Any process may become a
group leader by calling setgrp(S). A process inherits the
process group ID of the process that created it, see fork(S)
and exec(S).
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
process upon termination of one of the processes in the
group; see exit(S) and signal(S).
Real User ID and Real Group ID
Each user allowed on the system is identified by a positive
integer called a real user ID.
Each user is also a member of a group. The group is
identified by a positive integer called the real group ID.
An active process has a real user ID and a 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
Page 6 (printed 8/7/87)
INTRO(S) XENIX System V INTRO(S)
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' 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(S).
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 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.
Filename
Names consisting of up 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 a
slash (/).
Note that it is generally unwise to use *, ?, [, or ] as
part of filenames because of the special meaning attached to
these characters by the shell. Likewise, the high order bit
of the character should not be set.
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. A filename is a string of 1 to 14 characters
other than the ASCII slash and null, and a directory name is
a string of 1 to 14 characters (other than the ASCII slash
and null) naming a directory.
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 nonexistent file.
Page 7 (printed 8/7/87)
INTRO(S) XENIX System V INTRO(S)
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 a concept of a root directory and a current
working directory for the purpose of resolving pathname
searches associated with it. A process' root directory need
not be the root directory of the root file system. See
chroot(C) and chroot(S).
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 process' effective user ID is super-user.
The process' effective user ID 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 process' effective user ID does not match the user
ID of the owner of the file, and the process' group ID
matches the group of the file, and the appropriate
access bit of the ``group'' portion (070) of the file
mode is set.
The process' effective user ID does not match the user
ID of the owner of the file, and the process' effective
group ID does not match the group ID of the file, and
the appropriate access bit of the ``other'' portion
(07) of the file mode is set.
Otherwise, the corresponding permissions are denied. See
chmod(C) and chmod(S).
Message Queue Identifier
A message queue identifier (msqid) is a unique positive
integer created by a msgget(S) 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; /* operation permission struct */
ushort msg_qnum; /* number of msgs on q */
ushort msg_qbytes; /* max number of bytes on q */
ushort msg_lspid; /* pid of last msgsnd operation */
ushort msg_lrpid; /* pid of last msgrcv operation */
time_t msg_stime; /* last msgsnd time */
Page 8 (printed 8/7/87)
INTRO(S) XENIX System V INTRO(S)
time_t msg_rtime; /* last msgrcv time */
time_t msg_ctime; /* last change time */
/* Times measured in secs since */
/* 00:00:00 GMT, Jan. 1, 1970 */
msg_perm is an ipc_perm structure that specifies the message
operation permission (see below). The 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 */
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, and
msg_ctime is the time of the last msgctl(S) operation that
changed a member in the above structure.
Message Operation Permissions
In the msgop(S) and msgctl(S) system call descriptions, the
permission required for an operation is given as
``{token}'', where ``token'' is the type of permission
needed. It is interpreted as follows:
00400 Read by user
00200 Write by user
00060 Read, write by group
00006 Read, 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.
The effective user ID of the process matches
msg_perm.uid or msg_perm.cuid in the data structure
associated with msqid, and the appropriate bit of the
``user'' portion (0600) of msg_perm.mode is set.
The effective user ID of the process does not match
msg_perm.uid or msg_perm.cuid and the effective group
ID of the process matches msg_perm.gid or msg_perm.cgid
and the appropriate bit of the ``group'' portion (060)
of msg_perm.mode is set.
Page 9 (printed 8/7/87)
INTRO(S) XENIX System V INTRO(S)
The effective user ID of the process does not match
msg_perm.uid or msg_perm.cuid and the effective group
ID of the process does not match msg_perm.gid or
msg_perm.cgid and the appropriate bit of the ``other''
portion (06) 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(S) 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 */
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 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/a permission */
The value of 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(S)
operation, and sem_ctime is the time of the last semctl(S)
operation that changed a member of the above structure.
A semaphore is a data structure 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. 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
Page 10 (printed 8/7/87)
INTRO(S) XENIX System V INTRO(S)
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 zero.
Semaphore Operation Permissions
In the semop(S) and semctl(S) system call descriptions, the
permission required for an operation is given as
``{token}'', where ``token'' is the type of permission
needed and is interpreted as follows:
00400 Read by user
00200 Alter by user
00060 Read, alter by group
00006 Read, alter by others
Read and alter permissions for 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.uid or sem_perm.cuid in the data structure
associated with semid, and the appropriate ``user''
portion (0600) bit of sem_perm.mode is set.
The effective user ID of the process does not match
sem_perm.uid , or sem_perm.cuid and the effective group
ID of the process matches sem_perm.gid or sem_perm.cgid
and the appropriate bit of the ``group'' portion (060)
of sem_perm.mode is set.
The effective user ID of the process does not match
sem_perm.uid or sem_perm.cuid and the effective group
ID of the process does not match sem_perm.gid or
sem_perm.cgid and the appropriate bit of the ``other''
portion (06) 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(S) system call. Each shmid has
a segment of memory (referred to as a shared memory segment)
and a data structure associated with it. 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 */
ushort shm_cpid; /* creator pid */
ushort shm_lpid; /* pid of last operation */
Page 11 (printed 8/7/87)
INTRO(S) XENIX System V INTRO(S)
short shm_nattch; /* number of current attaches */
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). The 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 */
shm_segsz specifies the size of the shared memory segment.
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(S) operation.
shm_nattch is the number of processes that currently have
this segment attached. shm_atime is the time of the last
shmat operation. shm_dtime is the time of the last shmdt
operation, and shm_ctime is the time of the last shmctl(S)
operation that changed one of the above structure members.
Shared Memory Operation Permissions
In the shmop(S) and shmctl(S) system call descriptions, the
permission required for an operation is given as
``{token}'', where ``token'' is the type of permission
needed. It is interpreted as follows:
00400 Read by user
00200 Write by user
00060 Read, write by group
00006 Read, 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.uid or shm_perm.cuid in the data structure
associated with shmid and the appropriate bit of the
``user'' portion (0600) of shm_perm.mode is set.
The effective user ID of the process does not match
shm_perm.uid or shm_perm.cuid and the effective group
ID of the process matches shm_perm.gid or shm_perm.cgid
and the appropriate bit of the ``group'' portion (060)
Page 12 (printed 8/7/87)
INTRO(S) XENIX System V INTRO(S)
of shm_perm.mode is set.
The effective user ID of the process does not match
shm_perm.uid or shm_perm.cuid and the effective group
ID of the process does not match shm_perm.gid or
shm_perm.cgid and the appropriate bit of the ``other''
portion (06) of shm_perm.mode is set.
Otherwise, the corresponding permissions are denied.
See Also
close(S), ioctl(S), open(S), pipe(S), read(S), write(S)
Page 13 (printed 8/7/87)