semop
Purpose
Performs semaphore operations.
Syntax
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>
int semop (semid, sops, nsops)
int semid;
struct sembuf sops[ ];
unsigned int nsops;
Description
The semop system call performs operations on the set of
semaphores associated with the semaphore identifier spec-
ified by the semid parameter. The sops parameter points
to an array of structures, each of which specifies a
semaphore operation. The nsops parameter is the number
of such structures in the array. The sembuf structure is
defined in the sys/sem.h header file, and it contains the
following members:
ushort sem_num; /* Semaphore number */
short sem_op; /* Semaphore operation */
short sem_flg; /* Operation flags */
Each semaphore operation specified by a sem_op is per-
formed on the corresponding semaphore specified by semid
and sem_num. The sem_flg for each operation is either 0,
or is constructed by logically OR-ing one or more of the
following values:
SEM_UNDO Specifies whether to modify semadj values.
SEM_ORDER Specifies whether to perform the operations
atomically or individually. (This applies
only to the sem_flg of the first operation
specified in the sops array.)
IPC_NOWAIT Specifies whether to wait or to return imme-
diately when a semaphore's semval is not a
certain value.
If SEM_ORDER is not set in sops[0|.sem_flg (the default),
then all of the semaphore operations specified in the
sops array are performed atomically. This means that no
semval value for any sem_num that appears in the entire
array of operations is modified until all the semaphore
operations can be completed. If the calling process must
wait until some semval requirement is met, then the semop
system call does so before performing any of the oper-
ations. If any semaphore operation would cause an error
to occur, then none of the operations are performed.
If SEM_ORDER is set in sops[0|.sem_flg, then the oper-
ations are performed individually in the order that they
appear in the sops array, regardless of whether any of
the operations require the process to wait. If an opera-
tion encounters an error condition, then the semop system
call sets SEM_ERR in the sem_flg of the failing opera-
tion, sets errno to indicate the error, and returns a
value of -1. In this case, the operations that precede
the failing one in the sops array have been performed,
but those following it have not.
The action taken for SEM_UNDO and IPC_NOWAIT is described
in the following text.
The sem_op field of the sembuf structure specifies one of
the following three semaphore operations:
1. If sem_op is a positive integer and the current
process has write permission, then the value of
sem_op is added to semval. If SEM_UNDO is set in
sem_flg, then the value of sem_op is also subtracted
from the calling process's semadj value for the spec-
ified semaphore.
2. If sem_op is a negative integer and the current
process has write permission, then one of the fol-
lowing occurs:
o If semval is greater than or equal to the abso-
lute value of sem_op, the absolute value of
sem_op is subtracted from semval. Also, if
SEM_UNDO is set in sem_flg, the absolute value of
sem_op is added to the calling process's semadj
value for the specified semaphore. The exit
system call adds the semadj value to the
semaphore's semval when the process terminates
(see "exit, _exit").
o If semval is less than the absolute value of
sem_op and IPC_NOWAIT is set in sem_flg, semop
returns a value of -1 and sets errno to EAGAIN.
o If semval is less than the absolute value of
sem_op and IPC_NOWAIT is not set in sem_flg, then
semop increments the semncnt associated with the
specified semaphore and suspends execution of the
calling process until one of the following
occurs:
- semval becomes greater than or equal to the
absolute value of sem_op. When this occurs,
the value of semncnt associated with the
specified semaphore is decremented, the abso-
lute value of sem_op is subtracted from
semval and, if SEM_UNDO is set in sem_flg,
the absolute value of sem_op is added to the
calling process's semadj value for the speci-
fied semaphore.
- The semid for which the calling process is
awaiting action is removed from the system
(see "semctl"). When this occurs, errno is
set equal to EIDRM, and a value of -1 is
returned.
- The calling process receives a signal that is
to be caught. When this occurs, the value of
semncnt associated with the specified
semaphore is decremented, and the calling
process resumes execution in the manner pre-
scribed in the signal system call.
3. If sem_op is 0 and the current process has read per-
mission, then one of the following occurs:
o If semval is 0, then semop returns a value of 0.
o If semval is not equal to 0 and IPC_NOWAIT is set
in sem_flg, then semop returns a value of -1 and
sets errno to EAGAIN.
o If semval is not equal to 0 and IPC_NOWAIT is not
set in sem_flg, semop increments the semzcnt
associated with the specified semaphore and sus-
pends execution of the calling process until one
of the following occurs:
- semval becomes 0, at which time the value of
semzcnt associated with the specified
semaphore is decremented.
- The semid for which the calling process is
awaiting action is removed from the system.
When this occurs, errno is set equal to
EIDRM, and a value of of -1 is returned.
- The calling process receives a signal that is
to be caught. When this occurs, the value of
semzcnt associated with the specified
semaphore is decremented, and the calling
process resumes execution in the manner pre-
scribed in the signal system call.
Return Value
Upon successful completion, the semop system call returns
a value of 0. Also, the sempid value for each semaphore
that is operated upon is set to the process ID of the
calling process.
If semop fails, a value of -1 is returned and errno is
set to indicate the error. If SEM_ORDER was set in the
sem_flg for the first semaphore operation in the sops
array, then SEM_ERR is set in the sem_flg for the failing
operation.
Diagnostics
The semop system call fails if one or more of the fol-
lowing are true for any of the semaphore operations spec-
ified by the sops parameter. If the operations were
performed individually, then see the preceding discussion
of SEM_ORDER for more information about error situations.
EINVAL The semid parameter is not a valid semaphore
identifier.
EFBIG sem_num is less than 0 or it is greater than
or equal to the number of semaphores in the
set associated with the semid parameter.
E2BIG The nsops parameter is greater than the
system-imposed maximum.
EACCES Operation permission is denied to the calling
process.
EAGAIN The operation would result in suspension of
the calling process, but IPC_NOWAIT is set in
sem_flg
ENOSPC The limit on the number of individual proc-
esses requesting a SEM_UNDO would be exceeded.
EINVAL The number of individual semaphores for which
the calling process requests a SEM_UNDO would
exceed the limit.
ERANGE An operation would cause a semval to overflow
the system-imposed limit.
ERANGE An operation would cause a semadj value to
overflow the system-imposed limit.
EFAULT The sops parameter &pointsout..
EINTR The semop system call received a signal.
EIDRM The semaphore identifier semid has been
removed from the system.
Related Information
In this book: "exec: execl, execv, execle, execve,
execlp, execvp," "exit, _exit," "fork," "semctl," and
"semget."