--- name: "semop" section: "2" platform: "macos" package: "xnu" version: "12377.121.6" release: "macOS 26.5" platforms: ["linux", "freebsd", "macos"] url: "https://new.carta.tech/semop" --- # semop(2) atomic array of operations on a semaphore set ## NAME **semop** – atomic array of operations on a semaphore set ## SYNOPSIS **#include \** *int*\ **semop**(*int semid*, *struct sembuf \*sops*, *size\_t nsops*); ## DESCRIPTION The **semop**() system call atomically performs the array of operations indicated by *sops* on the semaphore set indicated by *semid*. The length of *sops* is indicated by *nsops*. Each operation is encoded in a *struct sembuf*, which is defined as follows: ``` struct sembuf { u_short sem_num; /* semaphore # */ short sem_op; /* semaphore operation */ short sem_flg; /* operation flags */ }; ``` For each element in *sops*, *sem\_op* and *sem\_flg* determine an operation to be performed on semaphore number *sem\_num* in the set. The values SEM\_UNDO and IPC\_NOWAIT may be *OR*'ed into the *sem\_flg* member in order to modify the behavior of the given operation. The operation performed depends as follows on the value of *sem\_op*: - When *sem\_op* is positive and the process has alter permission, the semaphore's value is incremented by *sem\_op*'s value. If SEM\_UNDO is specified, the semaphore's adjust on exit value is decremented by *sem\_op*'s value. A positive value for *sem\_op* generally corresponds to a process releasing a resource associated with the semaphore. - The behavior when *sem\_op* is negative and the process has alter permission, depends on the current value of the semaphore: - If the current value of the semaphore is greater than or equal to the absolute value of *sem\_op*, then the value is decremented by the absolute value of *sem\_op*. If SEM\_UNDO is specified, the semaphore's adjust on exit value is incremented by the absolute value of *sem\_op*. - If the current value of the semaphore is less than the absolute value of *sem\_op*, one of the following happens: - If IPC\_NOWAIT was specified, then **semop**() returns immediately with a return value of EAGAIN. - Otherwise, the calling process is put to sleep until one of the following conditions is satisfied: - Some other process removes the semaphore with the IPC\_RMID option of [semctl(2)](/semctl/2.md). In this case, **semop**() returns immediately with a return value of EIDRM. - The process receives a signal that is to be caught. In this case, the process will resume execution as defined by [sigaction(2)](/sigaction/2.md). - The semaphore's value is greater than or equal to the absolute value of *sem\_op*. When this condition becomes true, the semaphore's value is decremented by the absolute value of *sem\_op*, the semaphore's adjust on exit value is incremented by the absolute value of *sem\_op*. A negative value for *sem\_op* generally means that a process is waiting for a resource to become available. - When *sem\_op* is zero and the process has read permission, one of the following will occur: - If the current value of the semaphore is equal to zero then **semop**() can return immediately. - If IPC\_NOWAIT was specified, then **semop**() returns immediately with a return value of EAGAIN. - Otherwise, the calling process is put to sleep until one of the following conditions is satisfied: - Some other process removes the semaphore with the IPC\_RMID option of [semctl(2)](/semctl/2.md). In this case, **semop**() returns immediately with a return value of EIDRM. - The process receives a signal that is to be caught. In this case, the process will resume execution as defined by [sigaction(2)](/sigaction/2.md). - The semaphore's value becomes zero. For each semaphore a process has in use, the kernel maintains an “adjust on exit” value, as alluded to earlier. When a process exits, either voluntarily or involuntarily, the adjust on exit value for each semaphore is added to the semaphore's value. This can be used to insure that a resource is released if a process terminates unexpectedly. ## RETURN VALUES The **semop()** function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error. ## ERRORS The **semop**() system call will fail if: - \[E2BIG\] Too many operations are specified. \[SEMOPM\] - \[EACCES\] Permission is denied, due to a mismatch between the operation and the mode of the semaphore set. - \[EAGAIN\] The semaphore's value would result in the process being put to sleep and IPC\_NOWAIT is specified. - \[EFBIG\] *sem\_num* is not in the range of valid semaphores for the set. - \[EIDRM\] The semaphore set is removed from the system. - \[EINTR\] The **semop**() system call is interrupted by a signal. - \[EINVAL\] No semaphore set corresponds to *semid*, or the process would exceed the system-defined limit for the number of per-process SEM\_UNDO structures. - \[ENOSPC\] The system SEM\_UNDO pool \[SEMMNU\] is full. - \[ERANGE\] The requested operation would cause either the semaphore's current value \[SEMVMX\] or its adjust-on-exit value \[SEMAEM\] to exceed the system-imposed limits. ## LEGACY SYNOPSIS **#include \** **#include \** **#include \** The include files ⟨sys/types.h⟩ and ⟨sys/ipc.h⟩ are necessary. ## SEE ALSO [semctl(2)](/semctl/2.md), [semget(2)](/semget/2.md), [sigaction(2)](/sigaction/2.md), [compat(5)](/compat/5.md) ## BUGS The **semop**() system call may block waiting for memory even if IPC\_NOWAIT was specified.