1.\" $NetBSD: semop.2,v 1.1 1995/10/16 23:49:28 jtc 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 17, 1995 33.Dt SEMOP 2 34.Os NetBSD 35.Sh NAME 36.Nm semop 37.Nd semaphore operations 38.Sh SYNOPSIS 39.Fd #include <sys/types.h> 40.Fd #include <sys/ipc.h> 41.Fd #include <sys/sem.h> 42.Ft int 43.Fn semop "int semid" "struct sembuf *sops" "int 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, 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 u_short sem_num; /* semaphore # */ 57 short sem_op; /* semaphore operation */ 58 short sem_flg; /* operation flags */ 59.Ed 60 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 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 IPC_NOWAIT 97In the case where the calling process would normally block, waiting 98for a semaphore to reach a certain value, IPC_NOWAIT makes the 99call return immediately, returning a value of -1 and setting 100.Va errno 101to EAGAIN. 102.It SEM_UNDO 103Keep track of the changes that this call makes to the value of a semaphore, 104so that they can be undone when the calling process terminates. This is 105useful to prevent other processes waiting on a semaphore to block forever, 106should the process that has the semaphore locked terminate in a critical 107section. 108.El 109.Sh RETURN VALUES 110Upon successful completion, a value of 0 is returned. Otherwise, -1 is 111returned and the global variable 112.Va errno 113is set to indicate the error. 114.Sh ERRORS 115.Fn semop 116will fail if: 117.Bl -tag -width Er 118.It Bq Er EINVAL 119There is no semaphore associated with 120.Fa semid . 121 122The semaphore set was removed while the process was waiting for one of 123its semaphores to reach a certain value. 124 125.It Bq Er EACCESS 126The calling process has no permission to access the specified semaphore set. 127.It Bq Er E2BIG 128The value of 129.Fa nsops 130is too big. The maximum is specified in MAX_SOPS in <sys/sem.h> 131.It Bq Er EFBIG 132.Va sem_num 133in one of the sem_buf structures is less than 0, or greater than the actual 134number of semaphores in the set specified by 135.Fa semid . 136.It Bq Er ENOSPC 137SEM_UNDO was requested, and there is not enough space left in the kernel to 138store the unfo information. 139.It Bq Er EAGAIN 140The requested operation can not immediately be performed, and IPC_NOWAIT 141was set in 142.Va sem_flg . 143.It Bq Er EFAULT 144.Fa sops 145points to an illegal address. 146.Sh SEE ALSO 147.Xr semctl 2 , 148.Xr semget 2 149.Sh BUGS 150In case of a removed semaphore identifier, 151.Va errno 152should be set to EIDRM, but NetBSD does not define this error. 153