1.\" $NetBSD: semop.2,v 1.11 2002/03/05 21:29:32 tv 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. The semaphore 47set 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. The 53.Va sembuf 54structures in the array contain the following members: 55.Bd -literal 56 unsigned short sem_num; /* semaphore # */ 57 short sem_op; /* semaphore operation */ 58 short sem_flg; /* operation flags */ 59.Ed 60.Pp 61Each operation (specified in 62.Va sem_op ) 63is applied to semaphore number 64.Va sem_num 65in the set of semaphores specified by 66.Fa semid . 67The value of 68.Va sem_op 69determines the action taken in the following way: 70.Bl -bullet 71.It 72.Va sem_op 73is less than 0. The current process is blocked until the value of the 74semaphore is greater than or equal to the absolute value of 75.Va sem_op . 76The absolute value of 77.Va sem_op 78is then subtracted from the value of the semaphore, and the calling 79process continues. Negative values of 80.Va sem_op 81are thus used to enter critical regions. 82.It 83.Va sem_op 84is greater than 0. Its value is added to the value of the specified 85semaphore. This is used to leave critical regions. 86.It 87.Va sem_op 88is equal to 0. The calling process is blocked until the value of the 89specified semaphore reaches 0. 90.El 91.Pp 92The behaviour of each operation is influenced by the flags set in 93.Va sem_flg 94in the following way: 95.Bl -tag -width IPC_NOWAITX 96.It Dv IPC_NOWAIT 97In the case where the calling process would normally block, waiting 98for a semaphore to reach a certain value, 99.Dv IPC_NOWAIT 100makes the 101call return immediately, returning a value of -1 and setting 102.Va errno 103to 104.Er EAGAIN . 105.It SEM_UNDO 106Keep track of the changes that this call makes to the value of a semaphore, 107so that they can be undone when the calling process terminates. This is 108useful to prevent other processes waiting on a semaphore to block forever, 109should the process that has the semaphore locked terminate in a critical 110section. 111.El 112.Sh RETURN VALUES 113Upon successful completion, a value of 0 is returned. Otherwise, -1 is 114returned and the global variable 115.Va errno 116is set to indicate the error. 117.Sh ERRORS 118.Fn semop 119will fail if: 120.Bl -tag -width Er 121.It Bq Er EINVAL 122There is no semaphore associated with 123.Fa semid . 124.Pp 125The semaphore set was removed while the process was waiting for one of 126its semaphores to reach a certain value. 127.It Bq Er EACCES 128The calling process has no permission to access the specified semaphore set. 129.It Bq Er E2BIG 130The value of 131.Fa nsops 132is too big. The maximum is defined as 133.Dv MAX_SOPS 134in 135.Aq Pa sys/sem.h . 136.It Bq Er EFBIG 137.Va sem_num 138in one of the sem_buf structures is less than 0, or greater than the actual 139number of semaphores in the set specified by 140.Fa semid . 141.It Bq Er ENOSPC 142.Dv SEM_UNDO 143was requested, and there is not enough space left in the kernel to 144store the undo information. 145.It Bq Er EAGAIN 146The requested operation can not immediately be performed, and 147.Dv IPC_NOWAIT 148was set in 149.Va sem_flg . 150.It Bq Er EFAULT 151.Fa sops 152points to an illegal address. 153.El 154.Sh SEE ALSO 155.Xr semctl 2 , 156.Xr semget 2 157.Sh STANDARDS 158The 159.Nm 160system call conforms to 161.St -xsh5 . 162.Sh HISTORY 163Semaphores appeared in the first release of 164.At V . 165