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