NAME
semop - semaphore operations
SYNOPSIS
# include <sys/types.h>
# include <sys/ipc.h>
# include <sys/sem.h>
int semop ( int semid, struct sembuf *sops, unsigned nsops )
DESCRIPTION
The function performs operations on selected members of the
semaphore set indicated by semid. Each of the nsops ele-
ments in the array pointed to by sops specify an operation
to be performed on a semaphore by a struct sembuf including
the following members:
short sem_num; /* semaphore number: 0 = first */
short sem_op; /* semaphore operation */
short sem_flg; /* operation flags */
Flags recognized in sem_flg are IPC_NOWAIT and SEM_UNDO. If
an operation asserts SEM_UNDO, it will be undone when the
process exits.
The system call semantic assures that the operations will be
performed if and only if all of them will succeed. Each
operation is performed on the sem_num-th semaphore of the
semaphore set - where the first semaphore of the set is
semaphore 0 - and is one among the following three.
If sem_op is a positive integer, the operation adds this
value to semval. Furthermore, if SEM_UNDO is asserted for
this operation, the system updates the process undo count
for this semaphore. The operation always goes through, so
no process sleeping can happen. The calling process must
have alter permissions on the semaphore set.
If sem_op is zero, the process must have read access permis-
sions on the semaphore set. If semval is zero, the opera-
tion goes through. Otherwise, if IPC_NOWAIT is asserted in
sem_flg, the system call fails (undoing all previous actions
performed) with errno set to EAGAIN. Otherwise semzcnt is
incremented by one and the process sleeps until one of the
following occurs:
o semval becomes 0, at which time the value of
semzcnt is decremented.
o The semaphore set is removed: the system call
fails with errno set to EIDRM.
o The calling process receives a signal that has to
be caught: the value of semzcnt is decremented
and the system call fails with errno set to EINTR.
If sem_op is less than zero, the process must have alter
permissions on the semaphore set. If semval is greater than
or equal to the absolute value of sem_op, the absolute value
of sem_op is subtracted by semval. Furthermore, if SEM_UNDO
is asserted for this operation, the system updates the pro-
cess undo count for this semaphore. Then the operation goes
through. Otherwise, if IPC_NOWAIT is asserted in sem_flg,
the system call fails (undoing all previous actions per-
formed) with errno set to EAGAIN. Otherwise semncnt is
incremented by one and the process sleeps until one of the
following occurs:
o semval becomes greater or equal to the absolute
value of sem_op, at which time the value of
semncnt is decremented, the absolute value of
sem_op is subtracted from semval and, if SEM_UNDO
is asserted for this operation, the system updates
the process undo count for this semaphore.
o The semaphore set is removed from the system: the
system call fails with errno set to EIDRM.
o The calling process receives a signal that has to
be caught: the value of semncnt is decremented
and the system call fails with errno set to EINTR.
In case of success, the sempid member of the structure sem
for each semaphore specified in the array pointed to by sops
is set to the process-ID of the calling process. Further-
more both sem_otime and sem_ctime are set to the current
time.
RETURN VALUE
If successful the system call returns 0, otherwise it
returns -1 with errno indicating the error.
ERRORS
For a failing return, errno will be set to one among the
following values:
E2BIG The argument nsops is greater than SEMOPM, the
maximum number of operations allowed per system
call.
EACCES The calling process has no access permissions on
the semaphore set as required by one of the
specified operations.
EAGAIN An operation could not go through and IPC_NOWAIT
was asserted in its sem_flg.
EFAULT The address pointed to by sops isn't accessible.
EFBIG For some operation the value of sem_num is less
than 0 or greater than or equal to the number of
semaphores in the set.
EIDRM The semaphore set was removed.
EINTR Sleeping on a wait queue, the process received a
signal that had to be caught.
EINVAL The semaphore set doesn't exist, or semid is less
than zero, or nsops has a non-positive value.
ENOMEM The sem_flg of some operation asserted SEM_UNDO
and the system has not enough memory to allocate
the undo structure.
ERANGE For some operation semop+semval is greater than
SEMVMX, the implementation dependent maximum
value for semval.
NOTES
The sem_undo structures of a process aren't inherited by its
child on execution of a fork(2) system call. They are
instead inherited by the substituting process resulting by
the execution of the execve(2) system call.
The followings are limits on semaphore set resources affect-
ing a semop call:
SEMOPM Maximum number of operations allowed for one
semop call: policy dependent.
SEMVMX Maximum allowable value for semval: implementa-
tion dependent (32767).
The implementation has no intrinsic limits for the adjust on
exit maximum value (SEMAEM), the system wide maximum number
of undo structures (SEMMNU) and the per process maximum
number of undo entries system parameters.
BUGS
The system maintains a per process sem_undo structure for
each semaphore altered by the process with undo requests.
Those structures are free at process exit. One major cause
for unhappiness with the undo mechanism is that it does not
fit in with the notion of having an atomic set of operations
an array of semaphores. The undo requests for an array and
each semaphore therein may have been accumulated over many
semopt calls. Should the process sleep when exiting, or
should all undo operations be applied with the IPC_NOWAIT
flag in effect? Currently those undo operations which go
through immediately are applied, and those that require a
wait are ignored silently. Thus harmless undo usage is
guaranteed with private semaphores only.
CONFORMING TO
SVr4, SVID. SVr4 documents additional error conditions EIN-
VAL, EFBIG, ENOSPC.
SEE ALSO
ipc(5), semctl(2), semget(2).