1.\" $NetBSD: semop.2,v 1.12 2002/10/01 18:10:45 wiz Exp $ 2.\" 3.\" Copyright (c) 1995 Frank van der Linden 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.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed for the NetBSD Project 17.\" by Frank van der Linden 18.\" 4. The name of the author may not be used to endorse or promote products 19.\" derived from this software without specific prior written permission 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 22.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 23.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 24.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 26.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 30.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31.\" 32.Dd August 25, 1999 33.Dt SEMOP 2 34.Os 35.Sh NAME 36.Nm semop 37.Nd semaphore operations 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.Fd #include \*[Lt]sys/sem.h\*[Gt] 42.Ft int 43.Fn semop "int semid" "struct sembuf *sops" "size_t nsops" 44.Sh DESCRIPTION 45.Fn semop 46provides a number of atomic operations on a set of semaphores. 47The semaphore set is specified by 48.Fa semid , 49.Fa sops 50is an array of semaphore operations, and 51.Fa nsops 52is the number of operations in this array. 53The 54.Va sembuf 55structures in the array contain the following members: 56.Bd -literal 57 unsigned short sem_num; /* semaphore # */ 58 short sem_op; /* semaphore operation */ 59 short sem_flg; /* operation flags */ 60.Ed 61.Pp 62Each operation (specified in 63.Va sem_op ) 64is applied to semaphore number 65.Va sem_num 66in the set of semaphores specified by 67.Fa semid . 68The value of 69.Va sem_op 70determines the action taken in the following way: 71.Bl -bullet 72.It 73.Va sem_op 74is less than 0. 75The current process is blocked until the value of the 76semaphore is greater than or equal to the absolute value of 77.Va sem_op . 78The absolute value of 79.Va sem_op 80is then subtracted from the value of the semaphore, and the calling 81process continues. 82Negative values of 83.Va sem_op 84are thus used to enter critical regions. 85.It 86.Va sem_op 87is greater than 0. 88Its value is added to the value of the specified semaphore. 89This is used to leave critical regions. 90.It 91.Va sem_op 92is equal to 0. 93The calling process is blocked until the value of the 94specified semaphore reaches 0. 95.El 96.Pp 97The behaviour of each operation is influenced by the flags set in 98.Va sem_flg 99in the following way: 100.Bl -tag -width IPC_NOWAITX 101.It Dv IPC_NOWAIT 102In the case where the calling process would normally block, waiting 103for a semaphore to reach a certain value, 104.Dv IPC_NOWAIT 105makes the 106call return immediately, returning a value of -1 and setting 107.Va errno 108to 109.Er EAGAIN . 110.It SEM_UNDO 111Keep track of the changes that this call makes to the value of a semaphore, 112so that they can be undone when the calling process terminates. 113This is useful to prevent other processes waiting on a semaphore to block 114forever, should the process that has the semaphore locked terminate in a 115critical section. 116.El 117.Sh RETURN VALUES 118Upon successful completion, a value of 0 is returned. 119Otherwise, -1 is returned and the global variable 120.Va errno 121is set to indicate the error. 122.Sh ERRORS 123.Fn semop 124will fail if: 125.Bl -tag -width Er 126.It Bq Er EINVAL 127There is no semaphore associated with 128.Fa semid . 129.Pp 130The semaphore set was removed while the process was waiting for one of 131its semaphores to reach a certain value. 132.It Bq Er EACCES 133The calling process has no permission to access the specified semaphore set. 134.It Bq Er E2BIG 135The value of 136.Fa nsops 137is too big. 138The maximum is defined as 139.Dv MAX_SOPS 140in 141.Aq Pa sys/sem.h . 142.It Bq Er EFBIG 143.Va sem_num 144in one of the sem_buf structures is less than 0, or greater than the actual 145number of semaphores in the set specified by 146.Fa semid . 147.It Bq Er ENOSPC 148.Dv SEM_UNDO 149was requested, and there is not enough space left in the kernel to 150store the undo information. 151.It Bq Er EAGAIN 152The requested operation can not immediately be performed, and 153.Dv IPC_NOWAIT 154was set in 155.Va sem_flg . 156.It Bq Er EFAULT 157.Fa sops 158points to an illegal address. 159.El 160.Sh SEE ALSO 161.Xr semctl 2 , 162.Xr semget 2 163.Sh STANDARDS 164The 165.Nm 166system call conforms to 167.St -xsh5 . 168.Sh HISTORY 169Semaphores appeared in the first release of 170.At V . 171