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