1.\" $OpenBSD: semop.2,v 1.20 2021/10/23 21:17:45 jmc Exp $ 2.\" $NetBSD: semop.2,v 1.1 1995/10/16 23:49:28 jtc Exp $ 3.\" 4.\" Copyright (c) 1995 Frank van der Linden 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed for the NetBSD Project 18.\" by Frank van der Linden 19.\" 4. The name of the author may not be used to endorse or promote products 20.\" derived from this software without specific prior written permission 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 23.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 24.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 25.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 26.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 27.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 31.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32.\"/ 33.Dd $Mdocdate: October 23 2021 $ 34.Dt SEMOP 2 35.Os 36.Sh NAME 37.Nm semop 38.Nd semaphore operations 39.Sh SYNOPSIS 40.In sys/sem.h 41.Ft int 42.Fn semop "int semid" "struct sembuf *sops" "size_t nsops" 43.Sh DESCRIPTION 44.Fn semop 45provides a number of atomic operations on a set of semaphores. 46The semaphore set is specified by 47.Fa semid . 48.Fa sops 49is an array of semaphore operations, 50.Fa nsops 51is the number of operations in this array. 52The 53.Va sembuf 54structures in the array contain the following members: 55.Bd -literal 56 u_short sem_num; /* semaphore # */ 57 short sem_op; /* semaphore operation */ 58 short sem_flg; /* operation flags */ 59.Ed 60.Pp 61Each operation (specified in 62.Va sem_op ) 63is applied to semaphore number 64.Va sem_num 65in the set of semaphores specified by 66.Fa semid . 67The value of 68.Va sem_op 69determines the action taken in the following way: 70.Bl -bullet 71.It 72.Va sem_op 73is less than 0. 74The current process is blocked until the value of the 75semaphore is greater than or equal to the absolute value of 76.Va sem_op . 77The absolute value of 78.Va sem_op 79is then subtracted from the value of the semaphore, and the calling 80process continues. 81Negative values of 82.Va sem_op 83are thus used to enter critical regions. 84.It 85.Va sem_op 86is greater than 0. 87Its value is added to the value of the specified semaphore. 88This is used to leave critical regions. 89.It 90.Va sem_op 91is equal to 0. 92The calling process is blocked until the value of the specified 93semaphore reaches 0. 94.El 95.Pp 96The behavior of each operation is influenced by the flags set in 97.Va sem_flg 98in the following way: 99.Bl -tag -width IPC_NOWAITX 100.It Dv IPC_NOWAIT 101In the case where the calling process would normally block, waiting 102for a semaphore to reach a certain value, 103.Dv IPC_NOWAIT 104makes the 105call return immediately, returning a value of \-1 and setting 106.Va errno 107to 108.Er EAGAIN . 109.It Dv SEM_UNDO 110Keep track of the changes that this call makes to the value of a semaphore, 111so that they can be undone when the calling process terminates. 112This is useful to prevent other processes waiting on a semaphore to 113block forever, should the process that has the semaphore locked 114terminate in a critical section. 115.El 116.Sh RETURN VALUES 117.Rv -std 118.Sh ERRORS 119.Fn semop 120will fail if: 121.Bl -tag -width Er 122.It Bq Er EINVAL 123There is no semaphore associated with 124.Fa semid . 125.It Bq Er EIDRM 126The semaphore set was removed while the process was waiting for one of 127its semaphores to reach a certain value. 128.It Bq Er EACCES 129The calling process has no permission to access the specified semaphore set. 130.It Bq Er E2BIG 131The value of 132.Fa nsops 133is too big. 134The maximum is specified in MAX_SOPS in 135.In sys/sem.h . 136.It Bq Er EFBIG 137.Va sem_num 138in one of the sem_buf structures is less than 0, or greater than the actual 139number of semaphores in the set specified by 140.Fa semid . 141.It Bq Er ENOSPC 142.Dv SEM_UNDO 143was requested, and there is not enough space left in the kernel to 144store the undo information. 145.It Bq Er EAGAIN 146The requested operation cannot immediately be performed, and 147.Dv IPC_NOWAIT 148was set in 149.Va sem_flg . 150.It Bq Er EFAULT 151.Fa sops 152points to an illegal address. 153.El 154.Sh SEE ALSO 155.Xr ipcrm 1 , 156.Xr ipcs 1 , 157.Xr semctl 2 , 158.Xr semget 2 159