SEMOP (2)
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 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 permissions 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 .
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 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 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.
The semaphore set is removed from the system: 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 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 affecting a
semop
call:
SEMOPM
Maximum number of operations allowed for one
semop
call: policy dependent.
SEMVMX
Maximum allowable value for
semval :
implementation 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 EINVAL, EFBIG,
ENOSPC.
SEE ALSO
|