SEMOP(3,L) AIX Technical Reference SEMOP(3,L)
-------------------------------------------------------------------------------
semop
PURPOSE
Performs semaphore operations.
LIBRARY
Standard C Library (libc.a)
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 specified 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 performed on the
corresponding semaphore specified by semid and sem_num. The sem_flg for each
operation is either 0 or constructed by logically ORing 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 immediately when a
semaphore's semval is not a certain value.
Processed November 7, 1990 SEMOP(3,L) 1
SEMOP(3,L) AIX Technical Reference SEMOP(3,L)
If SEM_ORDER is not set in sops[0].sem_flg, 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, the semop system call
does so before performing any of the operations. If any semaphore operation
would cause an error to occur, none of the operations is performed.
If SEM_ORDER is set in sops[0].sem_flg, the operations 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 operation
encounters an error condition, the semop system call sets SEM_ERR in the
sem_flg of the failing operation, 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, the value of sem_op is added to semval. If SEM_UNDO is set in
sem_flg, the value of sem_op is also subtracted from the calling process's
semadj value for the specified semaphore.
2. If sem_op is a negative integer and the current process has write
permission, one of the following occurs:
o If semval 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_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, 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 absolute 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 specified semaphore.
Processed November 7, 1990 SEMOP(3,L) 2
SEMOP(3,L) AIX Technical Reference SEMOP(3,L)
- 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 prescribed in the signal system call.
3. If sem_op is 0 and the current process has read permission, one of the
following occurs:
o If semval is 0, semop returns a value of 0.
o If semval is not equal to 0 and IPC_NOWAIT is set in sem_flg, 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
suspends 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 prescribed in the signal system call.
Note: In a Transparent Computing Facility cluster, semaphores are not
maintained across the cluster. This means that a process cannot
communicate via semaphores to processes on another cluster site and the
process itself cannot migrate.
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, SEM_ERR is set in the sem_flg for the failing operation.
ERROR CONDITIONS
Processed November 7, 1990 SEMOP(3,L) 3
SEMOP(3,L) AIX Technical Reference SEMOP(3,L)
The semop system call fails if one or more of the following are true for any of
the semaphore operations specified by the sops parameter. If the operations
were performed individually, 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 processes 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.
EAGAIN Space cannot be allocated for an internal data structure (SEM_UNDO).
EAGAIN Insufficient kernel memory available to allocate the semaphore data
structures.
ERANGE An operation would cause a semadj value to overflow the system-imposed
limit.
EFAULT The sops parameter points to a location outside of the process's
allocated address space.
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, vfork," "semctl," and "semget."
Processed November 7, 1990 SEMOP(3,L) 4