1.\" $NetBSD: semop.2,v 1.18 2024/10/03 16:58:17 christos Exp $ 2.\" 3.\" Copyright (c) 1995 Frank van der Linden 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed for the NetBSD Project 17.\" by Frank van der Linden 18.\" 4. The name of the author may not be used to endorse or promote products 19.\" derived from this software without specific prior written permission 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 22.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 23.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 24.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 26.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 30.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31.\" 32.Dd October 3, 2024 33.Dt SEMOP 2 34.Os 35.Sh NAME 36.Nm semop, semtimedop 37.Nd semaphore operations 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In sys/sem.h 42.Ft int 43.Fn semop "int semid" "struct sembuf *sops" "size_t nsops" 44.Ft int 45.Fn semtimedop "int semid" "struct sembuf *sops" "size_t nsops" "struct timespec *timeout" 46.Sh DESCRIPTION 47.Fn semop 48provides a number of atomic operations on a set of semaphores. 49The semaphore set is specified by 50.Fa semid , 51.Fa sops 52is an array of semaphore operations, and 53.Fa nsops 54is the number of operations in this array. 55The 56.Va sembuf 57structures in the array contain the following members: 58.Bd -literal 59 unsigned short sem_num; /* semaphore # */ 60 short sem_op; /* semaphore operation */ 61 short sem_flg; /* operation flags */ 62.Ed 63.Pp 64Each operation (specified in 65.Va sem_op ) 66is applied to semaphore number 67.Va sem_num 68in the set of semaphores specified by 69.Fa semid . 70The value of 71.Va sem_op 72determines the action taken in the following way: 73.Bl -bullet 74.It 75.Va sem_op 76is less than 0. 77The current process is blocked until the value of the 78semaphore is greater than or equal to the absolute value of 79.Va sem_op . 80The absolute value of 81.Va sem_op 82is then subtracted from the value of the semaphore, and the calling 83process continues. 84Negative values of 85.Va sem_op 86are thus used to enter critical regions. 87.It 88.Va sem_op 89is greater than 0. 90Its value is added to the value of the specified semaphore. 91This is used to leave critical regions. 92.It 93.Va sem_op 94is equal to 0. 95The calling process is blocked until the value of the 96specified semaphore reaches 0. 97.El 98.Pp 99The behaviour of each operation is influenced by the flags set in 100.Va sem_flg 101in the following way: 102.Bl -tag -width IPC_NOWAITX 103.It Dv IPC_NOWAIT 104In the case where the calling process would normally block, waiting 105for a semaphore to reach a certain value, 106.Dv IPC_NOWAIT 107makes the 108call return immediately, returning a value of \-1 and setting 109.Va errno 110to 111.Er EAGAIN . 112.It SEM_UNDO 113Keep track of the changes that this call makes to the value of a semaphore, 114so that they can be undone when the calling process terminates. 115This is useful to prevent other processes waiting on a semaphore to block 116forever, should the process that has the semaphore locked terminate in a 117critical section. 118.El 119.Pp 120.Fn semtimedop 121is similar to 122.Fn semop , 123but it also allows specifying a timeout. 124When the semaphore is not available, 125the thread typically sleeps until the semaphore is available. 126.Fn semtimedop 127allows specifying a maximum amount of time in 128.Fa timeout 129argument that a thread should sleep while waiting for the semaphore to be available. 130If the specified time limit has been reached, 131.Fn semtimedop 132fails with 133.Er EAGAIN 134(and none of the operations in 135.Fa sops 136are performed). 137If 138.Fa timeout 139is 140.Dv NULL , 141.Fn semtimedop 142behaves exactly like 143.Fn semop . 144.Sh RETURN VALUES 145Upon successful completion both 146.Fn semop 147and 148.Fn semtimedop 149return a value of 0. Otherwise, \-1 is returned and the global variable 150.Va errno 151is set to indicate the error. 152.Sh ERRORS 153.Fn semop 154will fail if: 155.Bl -tag -width Er 156.It Bq Er EINVAL 157There is no semaphore associated with 158.Fa semid . 159.It Bq Er EIDRM 160The semaphore set was removed while the process was waiting for one of 161its semaphores to reach a certain value. 162.It Bq Er EACCES 163The calling process has no permission to access the specified semaphore set. 164.It Bq Er E2BIG 165The value of 166.Fa nsops 167is too big. 168The maximum is defined as 169.Dv MAX_SOPS 170in 171.In sys/sem.h . 172.It Bq Er EFBIG 173.Va sem_num 174in one of the sem_buf structures is less than 0, or greater than the actual 175number of semaphores in the set specified by 176.Fa semid . 177.It Bq Er ENOSPC 178.Dv SEM_UNDO 179was requested, and there is not enough space left in the kernel to 180store the undo information. 181.It Bq Er EAGAIN 182The requested operation can not immediately be performed, and 183.Dv IPC_NOWAIT 184was set in 185.Va sem_flg . 186.It Bq Er EFAULT 187.Fa sops 188points to an illegal address. 189.It Bq Er EINTR 190While blocked in this system call, the thread caught a signal. 191.El 192.Pp 193In addition, 194.Fn semtimedop 195will fail if: 196.Bl -tag -width Er 197.It Bq Er EAGAIN 198An operation could not proceed immediately and either 199.Dv IPC_NOWAIT 200was specified in 201.Va sem_flg 202or the time limit specified in 203.Fa timeout 204expired. 205.It Bq Er EFAULT 206An address specified in the 207.Fa timeout 208argument isn't accessible. 209.El 210.Sh EXAMPLES 211The following example shows how to perform a semaphore operation with a timeout: 212.Bd -literal -offset indent 213 214/* Performs a semaphore operation with a 5 sec timeout*/ 215 216struct sembuf sops[1]; /* Semaphore operation structure */ 217struct timespec timeout; /* Timeout structure */ 218 219/* Create semaphore set with 1 semaphore */ 220int semid = semget(key, 1, 0666 | IPC_CREAT); 221 222/* Initialize semaphore to 0 */ 223if (semctl(semid, 0, SETVAL, 0) == -1) { 224 warn("semctl SETVAL"); 225 exit(EXIT_FAILURE); 226} 227 228sops[0].sem_num = 0; /* Operation on semaphore 0 */ 229sops[0].sem_op = -1; /* Decrement semaphore by 1 */ 230sops[0].sem_flg = 0; /* No flags */ 231 232timeout.tv_sec = 5; /* 5 seconds */ 233timeout.tv_nsec = 0; /* 0 nanoseconds */ 234 235if (semtimedop(semid, sops, 1, &timeout) == -1) { 236 warn("semtimedop"); /* Print error message */ 237} 238.Ed 239.Sh SEE ALSO 240.Xr semctl 2 , 241.Xr semget 2 242.Sh STANDARDS 243The 244.Nm 245system call conforms to 246.St -xsh5 . 247.Sh HISTORY 248Semaphores appeared in the first release of 249.At V . 250