bsd/man/man2/semop.2

   1 .\"
   2 .\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com>
   3 .\"
   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 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD: src/lib/libc/sys/semop.2,v 1.18 2003/01/25 21:27:37 alfred Exp $
  27 .\"
  28 .Dd September 22, 1995
  29 .Dt SEMOP 2
  30 .Os
  31 .Sh NAME
  32 .Nm semop
  33 .Nd atomic array of operations on a semaphore set
  34 .Sh SYNOPSIS
  35 .In sys/types.h
  36 .In sys/ipc.h
  37 .In sys/sem.h
  38 .Ft int
  39 .Fn semop "int semid" "struct sembuf *array" "size_t nops"
  40 .Sh DESCRIPTION
  41 The
  42 .Fn semop
  43 system call
  44 atomically performs the array of operations indicated by
  45 .Fa array
  46 on the semaphore set indicated by
  47 .Fa semid .
  48 The length of
  49 .Fa array
  50 is indicated by
  51 .Fa nops .
  52 Each operation is encoded in a
  53 .Vt "struct sembuf" ,
  54 which is defined as follows:
  55 .Bd -literal
  56 .\"
  57 .\" From <sys/sem.h>
  58 .\"
  59 struct sembuf {
  60         u_short sem_num;        /* semaphore # */
  61         short   sem_op;         /* semaphore operation */
  62         short   sem_flg;        /* operation flags */
  63 };
  64 .Ed
  65 .Pp
  66 For each element in
  67 .Fa array ,
  68 .Va sem_op
  69 and
  70 .Va sem_flg
  71 determine an operation to be performed on semaphore number
  72 .Va sem_num
  73 in the set.
  74 The values
  75 .Dv SEM_UNDO
  76 and
  77 .Dv IPC_NOWAIT
  78 may be
  79 .Em OR Ns 'ed
  80 into the
  81 .Va sem_flg
  82 member in order to modify the behavior of the given operation.
  83 .Pp
  84 The operation performed depends as follows on the value of
  85 .Va sem_op :
  86 .\"
  87 .\" This section is based on the description of semop() in
  88 .\" Stevens, _Advanced Programming in the UNIX Environment_,
  89 .\" and the semop(2) description in The Open Group Unix2 specification.
  90 .\"
  91 .Bl -bullet
  92 .It
  93 When
  94 .Va sem_op
  95 is positive and the process has alter permission,
  96 the semaphore's value is incremented by
  97 .Va sem_op Ns 's
  98 value.
  99 If
 100 .Dv SEM_UNDO
 101 is specified, the semaphore's adjust on exit value is decremented by
 102 .Va sem_op Ns 's
 103 value.
 104 A positive value for
 105 .Va sem_op
 106 generally corresponds to a process releasing a resource
 107 associated with the semaphore.
 108 .It
 109 The behavior when
 110 .Va sem_op
 111 is negative and the process has alter permission,
 112 depends on the current value of the semaphore:
 113 .Bl -bullet
 114 .It
 115 If the current value of the semaphore is greater than or equal to
 116 the absolute value of
 117 .Va sem_op ,
 118 then the value is decremented by the absolute value of
 119 .Va sem_op .
 120 If
 121 .Dv SEM_UNDO
 122 is specified, the semaphore's adjust on exit
 123 value is incremented by the absolute value of
 124 .Va sem_op .
 125 .It
 126 If the current value of the semaphore is less than the absolute value of
 127 .Va sem_op ,
 128 one of the following happens:
 129 .\" XXX a *second* sublist?
 130 .Bl -bullet
 131 .It
 132 If
 133 .Dv IPC_NOWAIT
 134 was specified, then
 135 .Fn semop
 136 returns immediately with a return value of
 137 .Er EAGAIN .
 138 .It
 139 Otherwise, the calling process is put to sleep until one of the following
 140 conditions is satisfied:
 141 .\" XXX We already have two sublists, why not a third?
 142 .Bl -bullet
 143 .It
 144 Some other process removes the semaphore with the
 145 .Dv IPC_RMID
 146 option of
 147 .Xr semctl 2 .
 148 In this case,
 149 .Fn semop
 150 returns immediately with a return value of
 151 .Er EIDRM .
 152 .It
 153 The process receives a signal that is to be caught.
 154 In this case, the process will resume execution as defined by
 155 .Xr sigaction 2 .
 156 .It
 157 The semaphore's
 158 value is greater than or equal to the absolute value of
 159 .Va sem_op .
 160 When this condition becomes true, the semaphore's value is decremented
 161 by the absolute value of
 162 .Va sem_op ,
 163 the semaphore's adjust on exit value is incremented by the
 164 absolute value of
 165 .Va sem_op .
 166 .El
 167 .El
 168 .El
 169 .Pp
 170 A negative value for
 171 .Va sem_op
 172 generally means that a process is waiting for a resource to become
 173 available.
 174 .It
 175 When
 176 .Va sem_op
 177 is zero and the process has read permission,
 178 one of the following will occur:
 179 .Bl -bullet
 180 .It
 181 If the current value of the semaphore is equal to zero
 182 then
 183 .Fn semop
 184 can return immediately.
 185 .It
 186 If
 187 .Dv IPC_NOWAIT
 188 was specified, then
 189 .Fn semop
 190 returns immediately with a return value of
 191 .Er EAGAIN .
 192 .It
 193 Otherwise, the calling process is put to sleep until one of the following
 194 conditions is satisfied:
 195 .\" XXX Another nested sublists
 196 .Bl -bullet
 197 .It
 198 Some other process removes the semaphore with the
 199 .Dv IPC_RMID
 200 option of
 201 .Xr semctl 2 .
 202 In this case,
 203 .Fn semop
 204 returns immediately with a return value of
 205 .Er EIDRM .
 206 .It
 207 The process receives a signal that is to be caught.
 208 In this case, the process will resume execution as defined by
 209 .Xr sigaction 2 .
 210 .It
 211 The semaphore's value becomes zero.
 212 .El
 213 .El
 214 .El
 215 .Pp
 216 For each semaphore a process has in use, the kernel maintains an
 217 .Dq "adjust on exit"
 218 value, as alluded to earlier.
 219 When a process
 220 exits, either voluntarily or involuntarily, the adjust on exit value
 221 for each semaphore is added to the semaphore's value.
 222 This can
 223 be used to insure that a resource is released if a process terminates
 224 unexpectedly.
 225 .Sh RETURN VALUES
 226 .Rv -std semop
 227 .Sh ERRORS
 228 The
 229 .Fn semop
 230 system call will fail if:
 231 .Bl -tag -width Er
 232 .It Bq Er EINVAL
 233 No semaphore set corresponds to
 234 .Fa semid ,
 235 or the process would exceed the system-defined limit for the number of
 236 per-process
 237 .Dv SEM_UNDO
 238 structures.
 239 .It Bq Er EACCES
 240 Permission denied due to mismatch between operation and mode of
 241 semaphore set.
 242 .It Bq Er EAGAIN
 243 The semaphore's value would have resulted in the process being put to sleep
 244 and
 245 .Dv IPC_NOWAIT
 246 was specified.
 247 .It Bq Er E2BIG
 248 Too many operations were specified.
 249 .Bq Dv SEMOPM
 250 .It Bq Er EFBIG
 251 .\"
 252 .\" I'd have thought this would be EINVAL, but the source says
 253 .\" EFBIG.
 254 .\"
 255 .Va sem_num
 256 was not in the range of valid semaphores for the set.
 257 .It Bq Er EIDRM
 258 The semaphore set was removed from the system.
 259 .It Bq Er EINTR
 260 The
 261 .Fn semop
 262 system call was interrupted by a signal.
 263 .It Bq Er ENOSPC
 264 The system
 265 .Dv SEM_UNDO
 266 pool
 267 .Bq Dv SEMMNU
 268 is full.
 269 .It Bq Er ERANGE
 270 The requested operation would cause either
 271 the semaphore's current value
 272 .Bq Dv SEMVMX
 273 or its adjust on exit value
 274 .Bq Dv SEMAEM
 275 to exceed the system-imposed limits.
 276 .El
 277 .Sh SEE ALSO
 278 .Xr semctl 2 ,
 279 .Xr semget 2 ,
 280 .Xr sigaction 2
 281 .Sh BUGS
 282 The
 283 .Fn semop
 284 system call
 285 may block waiting for memory even if
 286 .Dv IPC_NOWAIT
 287 was specified.