SEMOP

Section: Linux Programmer's Manual (2)
Updated: 1993-11-01
Index
Return to Main Contents

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 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.

This document was created by man2html, using the manual pages.
Time: 01:55:03 GMT, January 21, 2025