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. The values SEM_UNDO and IPC_NOWAIT may be 74.Em OR Ns 'ed 75into the 76.Fa sem_flg 77member in order to modify the behavior of the given operation. 78.Pp 79The operation performed depends as follows on the value of 80.Fa sem_op : 81.\" 82.\" This section is based on the description of semop() in 83.\" Stevens, _Advanced Programming in the UNIX Environment_. 84.\" 85.Bl -bullet 86.It 87When 88.Fa sem_op 89is positive, the semaphore's value is incremented by 90.Fa sem_op Ns 's 91value. If SEM_UNDO is specified, the semaphore's adjust on exit 92value is decremented by 93.Fa sem_op Ns 's 94value. A positive value for 95.Fa sem_op 96generally corresponds to a process releasing a resource 97associated with the semaphore. 98.It 99The behavior when 100.Fa sem_op 101is negative depends on the current value of the semaphore: 102.Bl -bullet 103.It 104If the current value of the semaphore is greater than or equal to 105the absolute value of 106.Fa sem_op , 107then the value is decremented by the absolute value of 108.Fa sem_op . 109If SEM_UNDO is specified, the semaphore's adjust on exit 110value is incremented by the absolute value of 111.Fa sem_op . 112.It 113If the current value of the semaphore is less than 114.Fa sem_op Ns 's 115value, one of the following happens: 116.\" XXX a *second* sublist? 117.Bl -bullet 118.It 119If IPC_NOWAIT was specified, then 120.Fn semop 121returns immediately with a return value of 122.Er EAGAIN . 123.It 124If some other process has removed the semaphore with the IPC_RMID 125option of 126.Fn semctl , 127then 128.Fn semop 129returns immediately with a return value of 130.Er EINVAL . 131.It 132Otherwise, the calling process is put to sleep until the semaphore's 133value is greater than or equal to the absolute value of 134.Fa sem_op . 135When this condition becomes true, the semaphore's value is decremented 136by the absolute value of 137.Fa sem_op , 138and the semaphore's adjust on exit value is incremented by the 139absolute value of 140.Fa sem_op . 141.El 142.Pp 143A negative value for 144.Fa sem_op 145generally means that a process is waiting for a resource to become 146available. 147.El 148.It 149When 150.Fa sem_op 151is zero, the process waits for the semaphore's value to become zero. 152If it is already zero, the call to 153.Fn semop 154can return immediately. Otherwise, the calling process is put to 155sleep until the semaphore's value becomes zero. 156.El 157.Pp 158For each semaphore a process has in use, the kernel maintains an 159`adjust on exit' value, as alluded to earlier. When a process 160exits, either voluntarily or involuntarily, the adjust on exit value 161for each semaphore is added to the semaphore's value. This can 162be used to insure that a resource is released if a process terminates 163unexpectedly. 164.Sh RETURN VALUES 165.Rv -std semop 166.Sh ENVIRONMENT 167The XSI Interprocess Communication family of functions is also available 168as an implementation in userspace. 169To use it, the 170.Xr sysvipcd 8 171daemon has to be running. 172.Pp 173If the 174.Ev USR_SYSVIPC 175variable is set in a process' environment, the process and its children 176will use the userspace implementation. 177.Sh ERRORS 178.Fn Semop 179will fail if: 180.Bl -tag -width Er 181.It Bq Er EINVAL 182No semaphore set corresponds to 183.Fa semid . 184.It Bq Er EACCES 185Permission denied due to mismatch between operation and mode of 186semaphore set. 187.It Bq Er EAGAIN 188The semaphore's value was less than 189.Fa sem_op , 190and IPC_NOWAIT was specified. 191.It Bq Er E2BIG 192Too many operations were specified. 193.It Bq Er EFBIG 194.\" 195.\" I'd have thought this would be EINVAL, but the source says 196.\" EFBIG. 197.\" 198.Fa sem_num 199was not in the range of valid semaphores for the set. 200.El 201.Sh SEE ALSO 202.Xr semctl 2 , 203.Xr semget 2 204.Sh AUTHORS 205.An -nosplit 206The 207.Dx 208specific userspace implementation (see 209.Sx ENVIRONMENT ) 210was written by 211.An Larisa Grigore . 212