1.\" $OpenBSD: semop.2,v 1.4 1997/11/24 02:07:33 deraadt Exp $ 2.\" $NetBSD: semop.2,v 1.1 1995/10/16 23:49:28 jtc Exp $ 3.\" 4.\" Copyright (c) 1995 Frank van der Linden 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed for the NetBSD Project 18.\" by Frank van der Linden 19.\" 4. The name of the author may not be used to endorse or promote products 20.\" derived from this software without specific prior written permission 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 23.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 24.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 25.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 26.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 27.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 31.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32.\"/ 33.Dd August 17, 1995 34.Dt SEMOP 2 35.Os 36.Sh NAME 37.Nm semop 38.Nd semaphore operations 39.Sh SYNOPSIS 40.Fd #include <sys/types.h> 41.Fd #include <sys/ipc.h> 42.Fd #include <sys/sem.h> 43.Ft int 44.Fn semop "int semid" "struct sembuf *sops" "int nsops" 45.Sh DESCRIPTION 46.Fn semop 47provides a number of atomic operations on a set of semaphores. The semaphore 48set is specified by 49.Fa semid . 50.Fa sops 51is an array of semaphore operations, 52.Fa nsops 53is the number of operations in this array. The 54.Va sembuf 55structures in the array contain the following members: 56.Bd -literal 57 u_short sem_num; /* semaphore # */ 58 short sem_op; /* semaphore operation */ 59 short sem_flg; /* operation flags */ 60.Ed 61 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. The current process is blocked until the value of the 75semaphore is greater than or equal to the absolute value of 76.Va sem_op . 77The absolute value of 78.Va sem_op 79is then subtracted from the value of the semaphore, and the calling 80process continues. Negative values of 81.Va sem_op 82are thus used to enter critical regions. 83.It 84.Va sem_op 85is greater than 0. Its value is added to the value of the specified 86semaphore. This is used to leave critical regions. 87.It 88.Va sem_op 89is equal to 0. The calling process is blocked until the value of the 90specified semaphore reaches 0. 91.El 92 93The behavior of each operation is influenced by the flags set in 94.Va sem_flg 95in the following way: 96.Bl -tag -width IPC_NOWAITX 97.It IPC_NOWAIT 98In the case where the calling process would normally block, waiting 99for a semaphore to reach a certain value, IPC_NOWAIT makes the 100call return immediately, returning a value of -1 and setting 101.Va errno 102to EAGAIN. 103.It SEM_UNDO 104Keep track of the changes that this call makes to the value of a semaphore, 105so that they can be undone when the calling process terminates. This is 106useful to prevent other processes waiting on a semaphore to block forever, 107should the process that has the semaphore locked terminate in a critical 108section. 109.El 110.Sh RETURN VALUES 111Upon successful completion, a value of 0 is returned. Otherwise, -1 is 112returned and the global variable 113.Va errno 114is set to indicate the error. 115.Sh ERRORS 116.Fn semop 117will fail if: 118.Bl -tag -width Er 119.It Bq Er EINVAL 120There is no semaphore associated with 121.Fa semid . 122 123The semaphore set was removed while the process was waiting for one of 124its semaphores to reach a certain value. 125 126.It Bq Er EACCES 127The calling process has no permission to access the specified semaphore set. 128.It Bq Er E2BIG 129The value of 130.Fa nsops 131is too big. The maximum is specified in MAX_SOPS in <sys/sem.h> 132.It Bq Er EFBIG 133.Va sem_num 134in one of the sem_buf structures is less than 0, or greater than the actual 135number of semaphores in the set specified by 136.Fa semid . 137.It Bq Er ENOSPC 138SEM_UNDO was requested, and there is not enough space left in the kernel to 139store the unfo information. 140.It Bq Er EAGAIN 141The requested operation can not immediately be performed, and IPC_NOWAIT 142was set in 143.Va sem_flg . 144.It Bq Er EFAULT 145.Fa sops 146points to an illegal address. 147.Sh SEE ALSO 148.Xr semctl 2 , 149.Xr semget 2 150.Sh BUGS 151In case of a removed semaphore identifier, 152.Va errno 153should be set to EIDRM, but OpenBSD does not define this error. 154