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.\" $DragonFly: src/lib/libc/sys/semop.2,v 1.2 2003/06/17 04:26:47 dillon Exp $ 28.\" 29.Dd September 22, 1995 30.Dt SEMOP 2 31.Os 32.Sh NAME 33.Nm semop 34.Nd atomic array of operations on a semaphore set 35.Sh LIBRARY 36.Lb libc 37.Sh SYNOPSIS 38.In sys/types.h 39.In sys/ipc.h 40.In sys/sem.h 41.Ft int 42.Fn semop "int semid" "struct sembuf array[]" "unsigned nops" 43.Sh DESCRIPTION 44.Fn Semop 45atomically performs the array of operations indicated by 46.Fa array 47on the semaphore set indicated by 48.Fa semid . 49The length of 50.Fa array 51is indicated by 52.Fa nops . 53Each operation is encoded in a 54.Fa "struct sembuf" , 55which is defined as follows: 56.Bd -literal 57.\" 58.\" From <sys/sem.h> 59.\" 60struct sembuf { 61 u_short sem_num; /* semaphore # */ 62 short sem_op; /* semaphore operation */ 63 short sem_flg; /* operation flags */ 64}; 65.Ed 66.Pp 67For each element in 68.Fa array , 69.Fa sem_op 70and 71.Fa sem_flg 72determine an operation to be performed on semaphore number 73.Fa sem_num 74in the set. The values SEM_UNDO and IPC_NOWAIT may be 75.Em OR Ns 'ed 76into the 77.Fa sem_flg 78member in order to modify the behavior of the given operation. 79.Pp 80The operation performed depends as follows on the value of 81.Fa sem_op : 82.\" 83.\" This section is based on the description of semop() in 84.\" Stevens, _Advanced Programming in the UNIX Environment_. 85.\" 86.Bl -bullet 87.It 88When 89.Fa sem_op 90is positive, the semaphore's value is incremented by 91.Fa sem_op Ns 's 92value. If SEM_UNDO is specified, the semaphore's adjust on exit 93value is decremented by 94.Fa sem_op Ns 's 95value. A positive value for 96.Fa sem_op 97generally corresponds to a process releasing a resource 98associated with the semaphore. 99.It 100The behavior when 101.Fa sem_op 102is negative depends on the current value of the semaphore: 103.Bl -bullet 104.It 105If the current value of the semaphore is greater than or equal to 106the absolute value of 107.Fa sem_op , 108then the value is decremented by the absolute value of 109.Fa sem_op . 110If SEM_UNDO is specified, the semaphore's adjust on exit 111value is incremented by the absolute value of 112.Fa sem_op . 113.It 114If the current value of the semaphore is less than 115.Fa sem_op Ns 's 116value, one of the following happens: 117.\" XXX a *second* sublist? 118.Bl -bullet 119.It 120If IPC_NOWAIT was specified, then 121.Fn semop 122returns immediately with a return value of 123.Er EAGAIN . 124.It 125If some other process has removed the semaphore with the IPC_RMID 126option of 127.Fn semctl , 128then 129.Fn semop 130returns immediately with a return value of 131.Er EINVAL . 132.It 133Otherwise, the calling process is put to sleep until the semaphore's 134value is greater than or equal to the absolute value of 135.Fa sem_op . 136When this condition becomes true, the semaphore's value is decremented 137by the absolute value of 138.Fa sem_op , 139and the semaphore's adjust on exit value is incremented by the 140absolute value of 141.Fa sem_op . 142.El 143.Pp 144A negative value for 145.Fa sem_op 146generally means that a process is waiting for a resource to become 147available. 148.El 149.Pp 150.It 151When 152.Fa sem_op 153is zero, the process waits for the semaphore's value to become zero. 154If it is already zero, the call to 155.Fn semop 156can return immediately. Otherwise, the calling process is put to 157sleep until the semaphore's value becomes zero. 158.El 159.Pp 160For each semaphore a process has in use, the kernel maintains an 161`adjust on exit' value, as alluded to earlier. When a process 162exits, either voluntarily or involuntarily, the adjust on exit value 163for each semaphore is added to the semaphore's value. This can 164be used to insure that a resource is released if a process terminates 165unexpectedly. 166.Sh RETURN VALUES 167.Rv -std semop 168.Sh ERRORS 169.Fn Semop 170will fail if: 171.Bl -tag -width Er 172.It Bq Er EINVAL 173No semaphore set corresponds to 174.Fa semid . 175.It Bq Er EACCES 176Permission denied due to mismatch between operation and mode of 177semaphore set. 178.It Bq Er EAGAIN 179The semaphore's value was less than 180.Fa sem_op , 181and IPC_NOWAIT was specified. 182.It Bq Er E2BIG 183Too many operations were specified. 184.It Bq Er EFBIG 185.\" 186.\" I'd have thought this would be EINVAL, but the source says 187.\" EFBIG. 188.\" 189.Fa sem_num 190was not in the range of valid semaphores for the set. 191.El 192.Sh SEE ALSO 193.Xr semctl 2 , 194.Xr semget 2 195