NAME
semop — semaphore operations
SYNOPSIS
#include <sys/sem.h>
int semop(
int semid,
struct sembuf *sops,
size_t nsops
);
DESCRIPTION
semop()
is used to atomically perform an array of semaphore operations
on the set of semaphores associated with the semaphore identifier
specified by
semid.
sops
is a pointer to the array of semaphore-operation structures.
nsops
is the number of such structures in the array.
The contents of each structure includes the following members:
ushort sem_num; /* semaphore number */
short sem_op /* semaphore operation */
short sem_flg; /* operation flags */
Each semaphore operation specified by
sem_op
is performed on the corresponding semaphore specified by
semid
and
sem_num.
Semaphore array operations are atomic
in that none of the semaphore operations are performed
until blocking conditions on all of the semaphores
in the array have been removed.
sem_op
specifies one of three semaphore operations as follows:
If
sem_op
is a negative integer, one of the following occurs:
If
semval
(see
semaphore identifier
in
glossary(9))
is greater than or equal to the absolute value of
sem_op,
the absolute value of
sem_op
is subtracted from
semval.
Also, if
(sem_flg &
SEM_UNDO)
is ``true'', the absolute value of
sem_op
is added to the calling process's
semadj
value (see
glossary(9)
and
exit(2))
for the specified semaphore.
If
semval
is less than the absolute value of
sem_op
and
(sem_flg &
IPC_NOWAIT)
is ``true'',
semop()
returns immediately.
If
semval
is less than the absolute value of
sem_op
and
(sem_flg &
IPC_NOWAIT)
is ``false'',
semop()
increments the semncnt associated with the specified semaphore
and suspend execution of the calling process
until one of the following conditions occur:
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 absolute value of
sem_op
is subtracted from
semval
and, if
(sem_flg &
SEM_UNDO)
is ``true'', the absolute value of
sem_op
is added to the calling process's
semadj
value for the specified semaphore.
The
semid
for which the calling process is awaiting action
is removed from the system (see
semctl(2)).
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 prescribed in
signal(5).
If
sem_op
is a positive integer, the value of
sem_op
is added to
semval
and, if
(sem_flg &
SEM_UNDO)
is ``true'', the value of
sem_op
is subtracted from the calling process's
semadj
value
for the specified semaphore.
If
sem_op
is zero,
one of the following occurs:
If
semval
is zero,
semop()
proceeds to the next semaphore operation specified by
sops,
or returns immediately if this is the last operation.
If
semval
is not equal to zero and
(sem_flg &
IPC_NOWAIT)
is ``true'',
semop()
returns immediately.
If
semval
is not equal to zero and
(sem_flg &
IPC_NOWAIT)
is ``false'',
semop()
increments the semzcnt associated with the specified semaphore
and suspends execution of the calling process until
one of the following occurs:
semval
becomes zero, 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 -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 prescribed in
signal(5).
EXAMPLES
The following call to
semop()
atomically performs
a "P" or "get" operation on the second semaphore in the semaphore
set and a "V" or "release" operation on the third semaphore in
the set. This example assumes the process has a valid
semid
which represents a set of 4 semaphores as shown on the
semget(2)
manual page. It also assumes that the
semvals
of the semaphores
in the set have been initialized as shown in the
semctl(2)
manual entry.
struct sembuf sops[4];
sops[0].sem_num = 1;
sops[0].sem_op = -1; /* P (get) */
sops[0].sem_flg = 0;
sops[1].sem_num = 2;
sops[1].sem_op = 1; /* V (release) */
sops[1].sem_flg = 0;
semop (mysemid, sops, 2);
RETURN VALUE
If
semop()
returns due to the receipt of a signal,
a value of -1 is returned to the calling process and
errno
is set to
EINTR.
If it returns due to the removal of a
semid
from the system, a value of -1 is returned and
errno
is set to
EIDRM.
Upon successful completion, a non-negative value is returned.
Otherwise, a value of -1 is returned and
errno
is set to indicate the error.
ERRORS
semop()
fails if one or more of the following is true
for any of the semaphore operations specified by
sops:
- [EINVAL]
semid
is not a valid semaphore identifier.
- [EFBIG]
sem_num
is less than zero or greater than or equal to the number of semaphores
in the set associated with
semid.
- [E2BIG]
nsops
is greater than the system-imposed maximum.
- [EACCES]
Operation permission is denied to the calling process (see
glossary(9)).
- [EAGAIN]
The operation would result in suspension of the calling process but
(sem_flg &
IPC_NOWAIT)
is ``true''.
- [ENOSPC]
The limit on the number of individual processes requesting an
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]
sops
points to an illegal address.
The reliable detection of this error will be implementation dependent.
Upon successful completion, the value of
sempid
for each semaphore specified in the array pointed to by
sops
is set equal to the process
ID
of the calling process.
The value of
sem_otime
in the data structure associated with the semaphore
identifier will be set to the current time.
STANDARDS CONFORMANCE
semop(): SVID2, SVID3, XPG2, XPG3, XPG4