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: src/lib/libc/sys/semop.2,v 1.18 2003/01/25 21:27:37 alfred Exp $ 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 SYNOPSIS 35.In sys/sem.h 36.Ft int 37.Fo semop 38.Fa "int semid" 39.Fa "struct sembuf *sops" 40.Fa "size_t nsops" 41.Fc 42.Sh DESCRIPTION 43The 44.Fn semop 45system call 46atomically performs the array of operations indicated by 47.Fa sops 48on the semaphore set indicated by 49.Fa semid . 50The length of 51.Fa sops 52is indicated by 53.Fa nsops . 54Each operation is encoded in a 55.Vt "struct sembuf" , 56which is defined as follows: 57.Bd -literal 58.\" 59.\" From <sys/sem.h> 60.\" 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 sops , 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 insure 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.\" =========== 235.It Bq Er E2BIG 236Too many operations are specified. 237.Bq Dv SEMOPM 238.\" =========== 239.It Bq Er EACCES 240Permission is denied, due to a mismatch between the operation 241and the mode of the semaphore set. 242.\" =========== 243.It Bq Er EAGAIN 244The semaphore's value would result 245in the process being put to sleep and 246.Dv IPC_NOWAIT 247is specified. 248.\" =========== 249.It Bq Er EFBIG 250.\" 251.\" I'd have thought this would be EINVAL, 252.\" but the source says EFBIG. 253.\" 254.Va sem_num 255is not in the range of valid semaphores for the set. 256.\" =========== 257.It Bq Er EIDRM 258The semaphore set is removed from the system. 259.\" =========== 260.It Bq Er EINTR 261The 262.Fn semop 263system call is interrupted by a signal. 264.\" =========== 265.It Bq Er EINVAL 266No semaphore set corresponds to 267.Fa semid , 268or the process would exceed the system-defined limit 269for the number of per-process 270.Dv SEM_UNDO 271structures. 272.\" =========== 273.It Bq Er ENOSPC 274The system 275.Dv SEM_UNDO 276pool 277.Bq Dv SEMMNU 278is full. 279.\" =========== 280.It Bq Er ERANGE 281The requested operation would cause either 282the semaphore's current value 283.Bq Dv SEMVMX 284or its adjust-on-exit value 285.Bq Dv SEMAEM 286to exceed the system-imposed limits. 287.El 288.Sh LEGACY SYNOPSIS 289.Fd #include <sys/types.h> 290.Fd #include <sys/ipc.h> 291.Fd #include <sys/sem.h> 292.Pp 293The include files 294.In sys/types.h 295and 296.In sys/ipc.h 297are necessary. 298.Sh SEE ALSO 299.Xr semctl 2 , 300.Xr semget 2 , 301.Xr sigaction 2 , 302.Xr compat 5 303.Sh BUGS 304The 305.Fn semop 306system call 307may block waiting for memory even if 308.Dv IPC_NOWAIT 309was specified. 310