1.\" 2.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> 3.\" 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.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd September 22, 1995 27.Dt SEMOP 2 28.Os 29.Sh NAME 30.Nm semop 31.Nd atomic array of operations on a semaphore set 32.Sh LIBRARY 33.Lb libc 34.Sh SYNOPSIS 35.In sys/types.h 36.In sys/ipc.h 37.In sys/sem.h 38.Ft int 39.Fn semop "int semid" "struct sembuf *array" "size_t nops" 40.Sh DESCRIPTION 41The 42.Fn semop 43system call 44atomically performs the array of operations indicated by 45.Fa array 46on the semaphore set indicated by 47.Fa semid . 48The length of 49.Fa array 50is indicated by 51.Fa nops . 52Each operation is encoded in a 53.Vt "struct sembuf" , 54which is defined as follows: 55.\" 56.\" From <sys/sem.h> 57.\" 58.Bd -literal 59struct sembuf { 60 u_short sem_num; /* semaphore # */ 61 short sem_op; /* semaphore operation */ 62 short sem_flg; /* operation flags */ 63}; 64.Ed 65.Pp 66For each element in 67.Fa array , 68.Va sem_op 69and 70.Va sem_flg 71determine an operation to be performed on semaphore number 72.Va sem_num 73in the set. 74The values 75.Dv SEM_UNDO 76and 77.Dv IPC_NOWAIT 78may be 79.Em OR Ns 'ed 80into the 81.Va sem_flg 82member in order to modify the behavior of the given operation. 83.Pp 84The operation performed depends as follows on the value of 85.Va sem_op : 86.\" 87.\" This section is based on the description of semop() in 88.\" Stevens, _Advanced Programming in the UNIX Environment_, 89.\" and the semop(2) description in The Open Group Unix2 specification. 90.\" 91.Bl -bullet 92.It 93When 94.Va sem_op 95is positive and the process has alter permission, 96the semaphore's value is incremented by 97.Va sem_op Ns 's 98value. 99If 100.Dv SEM_UNDO 101is specified, the semaphore's adjust on exit value is decremented by 102.Va sem_op Ns 's 103value. 104A positive value for 105.Va sem_op 106generally corresponds to a process releasing a resource 107associated with the semaphore. 108.It 109The behavior when 110.Va sem_op 111is negative and the process has alter permission, 112depends on the current value of the semaphore: 113.Bl -bullet 114.It 115If the current value of the semaphore is greater than or equal to 116the absolute value of 117.Va sem_op , 118then the value is decremented by the absolute value of 119.Va sem_op . 120If 121.Dv SEM_UNDO 122is specified, the semaphore's adjust on exit 123value is incremented by the absolute value of 124.Va sem_op . 125.It 126If the current value of the semaphore is less than the absolute value of 127.Va sem_op , 128one of the following happens: 129.\" XXX a *second* sublist? 130.Bl -bullet 131.It 132If 133.Dv IPC_NOWAIT 134was specified, then 135.Fn semop 136returns immediately with a return value of 137.Er EAGAIN . 138.It 139Otherwise, the calling process is put to sleep until one of the following 140conditions is satisfied: 141.\" XXX We already have two sublists, why not a third? 142.Bl -bullet 143.It 144Some other process removes the semaphore with the 145.Dv IPC_RMID 146option of 147.Xr semctl 2 . 148In this case, 149.Fn semop 150returns immediately with a return value of 151.Er EIDRM . 152.It 153The process receives a signal that is to be caught. 154In this case, the process will resume execution as defined by 155.Xr sigaction 2 . 156.It 157The semaphore's 158value is greater than or equal to the absolute value of 159.Va sem_op . 160When this condition becomes true, the semaphore's value is decremented 161by the absolute value of 162.Va sem_op , 163the semaphore's adjust on exit value is incremented by the 164absolute value of 165.Va sem_op . 166.El 167.El 168.El 169.Pp 170A negative value for 171.Va sem_op 172generally means that a process is waiting for a resource to become 173available. 174.It 175When 176.Va sem_op 177is zero and the process has read permission, 178one of the following will occur: 179.Bl -bullet 180.It 181If the current value of the semaphore is equal to zero 182then 183.Fn semop 184can return immediately. 185.It 186If 187.Dv IPC_NOWAIT 188was specified, then 189.Fn semop 190returns immediately with a return value of 191.Er EAGAIN . 192.It 193Otherwise, the calling process is put to sleep until one of the following 194conditions is satisfied: 195.\" XXX Another nested sublists 196.Bl -bullet 197.It 198Some other process removes the semaphore with the 199.Dv IPC_RMID 200option of 201.Xr semctl 2 . 202In this case, 203.Fn semop 204returns immediately with a return value of 205.Er EIDRM . 206.It 207The process receives a signal that is to be caught. 208In this case, the process will resume execution as defined by 209.Xr sigaction 2 . 210.It 211The semaphore's value becomes zero. 212.El 213.El 214.El 215.Pp 216For each semaphore a process has in use, the kernel maintains an 217.Dq "adjust on exit" 218value, as alluded to earlier. 219When a process 220exits, either voluntarily or involuntarily, the adjust on exit value 221for each semaphore is added to the semaphore's value. 222This can 223be used to ensure that a resource is released if a process terminates 224unexpectedly. 225.Sh RETURN VALUES 226.Rv -std semop 227.Sh ERRORS 228The 229.Fn semop 230system call will fail if: 231.Bl -tag -width Er 232.It Bq Er EINVAL 233No semaphore set corresponds to 234.Fa semid , 235or the process would exceed the system-defined limit for the number of 236per-process 237.Dv SEM_UNDO 238structures. 239.It Bq Er EACCES 240Permission denied due to mismatch between operation and mode of 241semaphore set. 242.It Bq Er EAGAIN 243The semaphore's value would have resulted in the process being put to sleep 244and 245.Dv IPC_NOWAIT 246was specified. 247.It Bq Er E2BIG 248Too many operations were specified. 249.Bq Dv SEMOPM 250.It Bq Er EFBIG 251.\" 252.\" I'd have thought this would be EINVAL, but the source says 253.\" EFBIG. 254.\" 255.Va sem_num 256was not in the range of valid semaphores for the set. 257.It Bq Er EIDRM 258The semaphore set was removed from the system. 259.It Bq Er EINTR 260The 261.Fn semop 262system call was interrupted by a signal. 263.It Bq Er ENOSPC 264The system 265.Dv SEM_UNDO 266pool 267.Bq Dv SEMMNU 268is full. 269.It Bq Er ERANGE 270The requested operation would cause either 271the semaphore's current value 272.Bq Dv SEMVMX 273or its adjust on exit value 274.Bq Dv SEMAEM 275to exceed the system-imposed limits. 276.El 277.Sh SEE ALSO 278.Xr semctl 2 , 279.Xr semget 2 , 280.Xr sigaction 2 281.Sh BUGS 282The 283.Fn semop 284system call 285may block waiting for memory even if 286.Dv IPC_NOWAIT 287was specified. 288