SEMOP(2) Linux Programmer's Manual SEMOP(2)
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
elements in the array pointed to by sops specify an opera
tion 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 per
missions on the semaphore set. If semval is zero, the
operation 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:
· semval becomes 0, at which time the value of
semzcnt is decremented.
· The semaphore set is removed: the system
call fails with errno set to EIDRM.
Linux 0.99.13 November 1, 1993 1
SEMOP(2) Linux Programmer's Manual SEMOP(2)
· 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 abso
lute value of sem_op is subtracted by semval. Further
more, if SEM_UNDO is asserted for this operation, the sys
tem updates the process 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 performed) with errno set to EAGAIN.
Otherwise semncnt is incremented by one and the process
sleeps until one of the following occurs:
· semval becomes greater or equal to the abso
lute value of sem_op, at which time the
value of semncnt is decremented, the abso
lute value of sem_op is subtracted from sem
val and, if SEM_UNDO is asserted for this
operation, the system updates the process
undo count for this semaphore.
· The semaphore set is removed from the sys
tem: the system call fails with errno set to
EIDRM.
· 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.
Furthermore 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
Linux 0.99.13 November 1, 1993 2
SEMOP(2) Linux Programmer's Manual SEMOP(2)
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 accessi
ble.
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 allo
cate 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
affecting 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
Linux 0.99.13 November 1, 1993 3
SEMOP(2) Linux Programmer's Manual SEMOP(2)
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 accumu
lated 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
EINVAL, EFBIG, ENOSPC.
SEE ALSO
ipc(5), semctl(2), semget(2).
Linux 0.99.13 November 1, 1993 4