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.\" $FreeBSD: src/lib/libc/sys/semop.2,v 1.7.2.6 2001/12/14 18:34:01 ru Exp $ 27.\" 28.Dd January 4, 2014 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[]" "unsigned nops" 42.Sh DESCRIPTION 43.Fn Semop 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.Fa "struct sembuf" , 54which is defined as follows: 55.Bd -literal 56.\" 57.\" From <sys/sem.h> 58.\" 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.Fa sem_op 69and 70.Fa sem_flg 71determine an operation to be performed on semaphore number 72.Fa 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.Fa 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.Fa sem_op : 86.\" 87.\" This section is based on the description of semop() in 88.\" Stevens, _Advanced Programming in the UNIX Environment_. 89.\" 90.Bl -bullet 91.It 92When 93.Fa sem_op 94is positive, the semaphore's value is incremented by 95.Fa sem_op Ns 's 96value. 97If 98.Dv SEM_UNDO 99is specified, the semaphore's adjust on exit value is decremented by 100.Fa sem_op Ns 's 101value. 102A positive value for 103.Fa sem_op 104generally corresponds to a process releasing a resource 105associated with the semaphore. 106.It 107The behavior when 108.Fa sem_op 109is negative depends on the current value of the semaphore: 110.Bl -bullet 111.It 112If the current value of the semaphore is greater than or equal to 113the absolute value of 114.Fa sem_op , 115then the value is decremented by the absolute value of 116.Fa sem_op . 117If 118.Dv SEM_UNDO 119is specified, the semaphore's adjust on exit 120value is incremented by the absolute value of 121.Fa sem_op . 122.It 123If the current value of the semaphore is less than 124.Fa sem_op Ns 's 125value, one of the following happens: 126.\" XXX a *second* sublist? 127.Bl -bullet 128.It 129If 130.Dv IPC_NOWAIT 131was specified, then 132.Fn semop 133returns immediately with a return value of 134.Er EAGAIN . 135.It 136If some other process has removed the semaphore with the 137.Dv IPC_RMID 138option of 139.Fn semctl , 140then 141.Fn semop 142returns immediately with a return value of 143.Er EINVAL . 144.It 145Otherwise, the calling process is put to sleep until the semaphore's 146value is greater than or equal to the absolute value of 147.Fa sem_op . 148When this condition becomes true, the semaphore's value is decremented 149by the absolute value of 150.Fa sem_op , 151and the semaphore's adjust on exit value is incremented by the 152absolute value of 153.Fa sem_op . 154.El 155.Pp 156A negative value for 157.Fa sem_op 158generally means that a process is waiting for a resource to become 159available. 160.El 161.It 162When 163.Fa sem_op 164is zero, the process waits for the semaphore's value to become zero. 165If it is already zero, the call to 166.Fn semop 167can return immediately. 168Otherwise, the calling process is put to 169sleep until the semaphore's value becomes zero. 170.El 171.Pp 172For each semaphore a process has in use, the kernel maintains an 173`adjust on exit' value, as alluded to earlier. 174When a process 175exits, either voluntarily or involuntarily, the adjust on exit value 176for each semaphore is added to the semaphore's value. 177This can 178be used to insure that a resource is released if a process terminates 179unexpectedly. 180.Sh RETURN VALUES 181.Rv -std semop 182.Sh ENVIRONMENT 183The XSI Interprocess Communication family of functions is also available 184as an implementation in userspace. 185To use it, the 186.Xr sysvipcd 8 187daemon has to be running. 188.Pp 189If the 190.Ev USR_SYSVIPC 191variable is set in a process' environment, the process and its children 192will use the userspace implementation. 193.Sh ERRORS 194.Fn Semop 195will fail if: 196.Bl -tag -width Er 197.It Bq Er EINVAL 198No semaphore set corresponds to 199.Fa semid . 200.It Bq Er EACCES 201Permission denied due to mismatch between operation and mode of 202semaphore set. 203.It Bq Er EAGAIN 204The semaphore's value was less than 205.Fa sem_op , 206and 207.Dv IPC_NOWAIT 208was specified. 209.It Bq Er E2BIG 210Too many operations were specified. 211.It Bq Er EFBIG 212.\" 213.\" I'd have thought this would be EINVAL, but the source says 214.\" EFBIG. 215.\" 216.Fa sem_num 217was not in the range of valid semaphores for the set. 218.El 219.Sh SEE ALSO 220.Xr semctl 2 , 221.Xr semget 2 222.Sh AUTHORS 223.An -nosplit 224The 225.Dx 226specific userspace implementation (see 227.Sx ENVIRONMENT ) 228was written by 229.An Larisa Grigore . 230