INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
NAME
intro - introduction to system calls and error numbers
SYNOPSIS
DESCRIPTION
This section describes all of the system calls.
NOTE
Functions that are available for both -systype svr3 and
-systype bsd43 are included in this section without the
designation (-SVR3) after the section number.
ERROR NUMBERS
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 vari-
able 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
superuser. It is also returned for attempts by ordi-
nary users to do things allowed only to the superuser.
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
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.
Printed 11/19/92 Page 1
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
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 NCARGS bytes is presented
to a member of the exec(2) family. NCARGS is defined in
sys/param.h.
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 resources or 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 insuffi-
cient memory or swap space.
12 ENOMEM Not enough space
During an exec(2), brk(2), or sbrk (see brk(2)), a pro-
gram 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 regis-
ters, 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 which 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.
Page 2 Printed 11/19/92
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
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 con-
text, e.g., 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; 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 argu-
ment 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.
Printed 11/19/92 Page 3
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
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
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 accom-
plished 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 to a file, as defined by MAXLINK in sys/param.h
(usually 1000).
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 execu-
tion due to the removal of an identifier from the file
system's name space [see msgctl(2), semctl(2), and
shmctl(2)].
Page 4 Printed 11/19/92
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
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) opera-
tion 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.
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
Printed 11/19/92 Page 5
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
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 accessi-
ble.
77 EBADMSG Bad message
During a read(2), getmsg(2), or ioctl(2) I_RECVFD sys-
tem call to a STREAMS device, something has come to the
head of the queue that can't be processed. That some-
thing 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.
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 cor-
rupted.
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.
Page 6 Printed 11/19/92
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
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
not allowed.
90 ENOTSUP Not supported
This error occurs when an optional portion of a subsys-
tem is not supported.
101 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)).
102 EINPROGRESS Operation now in progress
An operation that takes a long time to complete (such
as a connect(2)) was attempted on a non_clocking object
(see fcntl(2)).
103 EALREADY Operation already in progress
An operation was attempted on a non-blocking object
that already had an operation in progress.
104 ENOTSOCK Socket operation on non-socket
Self-explanatory.
105 EDESTADDRREQ Destination address required
A required address was omitted from an operation on a
socket.
106 EMSGSIZE Message too long
A message sent on a socket was larger than the internal
message buffer or some other network limit.
107 EPROTOTYPE Protocol wrong type for socket
A protocol was specified that does not support the
semantics of the socket type requested. For example,
you cannot use the ARPA Internet UDP protocol with type
SOCK_STREAM.
108 ENOPROTOOPT Option not supported by protocol
A bad option or level was specified in a getsockopt(2)
or setsockopt call.
109 EPROTONOSUPPORT Protocol not supported
The support for the socket type has not been configured
Printed 11/19/92 Page 7
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
into the system or no implementation for it exists.
110 ESOCKTNOSUPPORT Socket type unsupported
The support for the socket type has not been configured
into the system or nor implementation for it exists.
111 EOPNOTSUPP Operation not supported on socket
For example, trying to accept a connection on a
datagram socket.
112 EPRNOSUPPORT Protocol family unsupported
The protocol family has not been configured into the
system or no implementation for it exists.
113 EAFNOSUPPORT Address family unsupported 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 proto-
cols.
114 EADDRINUSE Address already in use
Only one usage of each address is normally permitted.
115 EADDRNOTAVAIL Can't assign requested address
Normally results from an attempt to create a socket
with an address not on this machine.
116 ENETDOWN Network is down
A socket operation encountered a dead network.
117 ENETUNREACH Network is unreachable
A socket operation was attempted to an unreachable net-
work.
118 ENETRESET Network dropped connection on reset
The host you were connected to crashed and rebooted.
119 ECONNABORTED Software caused connection abort
A connection abort was caused internal to your host
machine.
120 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.
121 ENOBUFS No buffer space available
an operation on a socket or pipe was not performed
because the system lacked sufficient buffer space or
because a queue was full.
Page 8 Printed 11/19/92
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
122 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.
123 ENOTCONN Socket is unconnected
A request to send or receive data was disallowed
because the socket is not connected and (when sending
on a datagram socket) no address was supplied.
124 ESHUTDOWN Can't send after socket shutdown
A request to send data was disallowed because the
socket had already been shut down with a previous shut-
down(2) call.
126 ETIMEDOUT Connection 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.)
127 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.
128 EHOSTDOWN Host is down
A socket operation failed because the destination host
was down.
129 EHOSTUNREACH Host is unreachable
A socket operation was attempted to an unreachable
host.
130 ELOOP Too many levels of symbolic links
A path name lookup involved more than 8 symbolic links.
131 ENAMETOOLONG File name too long
A component of a path name exceeded 255 (MAXNAMELEN)
characters, or an entire path name exceeded 1023
(MAXPATHLEN-1) characters.
132 ENOTEMPTY Directory not empty
A directory with entries other than "." and ".." was
supplied to a remove directory or rename call.
133 EDQUOT Disc quota exceeded
A write on an ordinary file, the creation of a direc-
tory or symbolic link, or the creation of a directory
entry failed because the user's quota of disk blocks
was exhausted, or the allocation of an inode for a
Printed 11/19/92 Page 9
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
newly created file failed because the user's quota of
inodes was exhausted.
134 ESTALE Stale NFS file handle
A client referenced an open file, when the file has
been deleted.
135 ENFSREMOTE Too many levels of remote in path
An attempt was made to mount a file remotely into a
path that already has a remotely mounted component.
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 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 a group. The group is identi-
fied by a positive integer called the real 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
Page 10 Printed 11/19/92
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
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)].
Superuser
A process is recognized as a superuser process and is
granted special privileges, such as immunity from file per-
missions, 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. proc2
is the daemon process that ages and steals pages (uhand).
proc3 is the daemon process that flushes delayed writes.
Descriptor
A descriptor is an integer used to do I/O on a file. The
value of a descriptor is from 0 to (NOFILES - 1). A process
may have no more than NOFILES file descriptors open simul-
taneously. A file descriptor is returned by system calls
such as open(2), pipe(2), or socketpair(2). The descriptor
is used as an argument by calls such as read(2), write(2),
ioctl(2), and close(2).
System V File Name Types
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 charac-
ter 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 per-
mitted, the use of unprintable characters in file names
should be avoided.
BSD File Name Types
Names consisting of up to 255 (MAXNAMELEN) characters can be
used to name an ordinary file, special file or directory.
These characters can be selected from the set of all ASCII
characters, excluding 0 (null) and the ASCII code for /
(slash). (The parity bit, bit 8, must be 0.)
Printed 11/19/92 Page 11
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
Note: 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 and Path Prefix
A path name is a null-terminated character string starting
with an optional slash (/), followed by zero or more direc-
tory 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.
For System V-type file systems, unless specifically stated
otherwise, the null path name is treated as if it named a
non-existent file. For BSD-type files systems, a null path
name refers to the current directory.
Directory
Directory entries are called links. By convention, a direc-
tory 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 path name searches. The root directory of a pro-
cess 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 permis-
sions. These permissions are used to determine whether a
process can perform a requested operation on the file (such
as opening a file for writing). Access permissions are
established at the time a file is created. They can be
changed at some later time through the chmod (2) call.
File access is broken down according to whether a file can
be: read, written, or executed. Directory files use the
execute permission to control if the directory can be
searched.
File access permissions are interpreted by the system as
they apply to three different classes of users: the owner of
the file, those users in the file's group, 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
Page 12 Printed 11/19/92
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
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 superuser.
The process's effective user ID matches the user ID of the
owner of the file and the owner permissions allow the
access.
The process's effective user ID does not match the user ID
of the owner of the file, 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 proper-
ties. 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 type; consult socket(2) for more information about
the type available and their properties.
Each instance of the system supports some number of sets of
communications protocols. Each protocol set support
addresses of a certain format. An Address Family is the set
addresses for a specific group of protocols. Each socket
has an address chosen from the address family in which the
socket was created.
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:
Printed 11/19/92 Page 13
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
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 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 */
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 per-
formed a msgsnd operation.
msg_lrpid is the process id of the last process that per-
formed 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},
Page 14 Printed 11/19/92
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
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 pro-
cess if one or more of the following are true:
The effective user ID of the process is superuser.
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 sema-
phore operation permission (see below). This structure
includes the following members:
ushort uid; /* user id */
ushort gid; /* group id */
ushort cuid; /* creator user id */
ushort cgid; /* creator group id */
Printed 11/19/92 Page 15
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
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 which is the actual value
of the semaphore.
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 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 pro-
cess if one or more of the following are true:
Page 16 Printed 11/19/92
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
The effective user ID of the process is superuser.
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 fol-
lowing 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 */
Printed 11/19/92 Page 17
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
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 per-
formed 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 (see shmop(2))
operation,
shm_dtime is the time of the last shmdt (see shmop(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 pro-
cess if one or more of the following are true:
The effective user ID of the process is superuser.
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.
Page 18 Printed 11/19/92
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
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 pro-
cessing 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 pro-
cess. The principle functions of the stream head are pro-
cessing 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 peri-
pheral 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 commun-
icating within a stream.
Printed 11/19/92 Page 19
INTRO(2-SVR3) RISC/os Reference Manual INTRO(2-SVR3)
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 con-
taining messages moving upstream.
Write Queue
In a stream, the message queue in a module or driver con-
taining 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), perror(3).
Page 20 Printed 11/19/92