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/sem.h
  36 .Ft int
  37 .Fo semop
  38 .Fa "int semid"
  39 .Fa "struct sembuf *sops"
  40 .Fa "size_t nsops"
  41 .Fc
  42 .Sh DESCRIPTION
  43 The
  44 .Fn semop
  45 system call
  46 atomically performs the array of operations indicated by
  47 .Fa sops
  48 on the semaphore set indicated by
  49 .Fa semid .
  50 The length of
  51 .Fa sops
  52 is indicated by
  53 .Fa nsops .
  54 Each operation is encoded in a
  55 .Vt "struct sembuf" ,
  56 which is defined as follows:
  57 .Bd -literal
  58 .\"
  59 .\" From <sys/sem.h>
  60 .\"
  61 struct sembuf {
  62         u_short sem_num;        /* semaphore # */
  63         short   sem_op;         /* semaphore operation */
  64         short   sem_flg;        /* operation flags */
  65 };
  66 .Ed
  67 .Pp
  68 For each element in
  69 .Fa sops ,
  70 .Va sem_op
  71 and
  72 .Va sem_flg
  73 determine an operation to be performed on semaphore number
  74 .Va sem_num
  75 in the set.
  76 The values
  77 .Dv SEM_UNDO
  78 and
  79 .Dv IPC_NOWAIT
  80 may be
  81 .Em OR Ns 'ed
  82 into the
  83 .Va sem_flg
  84 member in order to modify the behavior of the given operation.
  85 .Pp
  86 The operation performed depends as follows on the value of
  87 .Va sem_op :
  88 .\"
  89 .\" This section is based on the description of semop() in
  90 .\" Stevens, _Advanced Programming in the UNIX Environment_,
  91 .\" and the semop(2) description in The Open Group Unix2 specification.
  92 .\"
  93 .Bl -bullet
  94 .It
  95 When
  96 .Va sem_op
  97 is positive and the process has alter permission,
  98 the semaphore's value is incremented by
  99 .Va sem_op Ns 's
 100 value.
 101 If
 102 .Dv SEM_UNDO
 103 is specified, the semaphore's adjust on exit value is decremented by
 104 .Va sem_op Ns 's
 105 value.
 106 A positive value for
 107 .Va sem_op
 108 generally corresponds to a process releasing a resource
 109 associated with the semaphore.
 110 .It
 111 The behavior when
 112 .Va sem_op
 113 is negative and the process has alter permission,
 114 depends on the current value of the semaphore:
 115 .Bl -bullet
 116 .It
 117 If the current value of the semaphore is greater than or equal to
 118 the absolute value of
 119 .Va sem_op ,
 120 then the value is decremented by the absolute value of
 121 .Va sem_op .
 122 If
 123 .Dv SEM_UNDO
 124 is specified, the semaphore's adjust on exit
 125 value is incremented by the absolute value of
 126 .Va sem_op .
 127 .It
 128 If the current value of the semaphore is less than the absolute value of
 129 .Va sem_op ,
 130 one of the following happens:
 131 .\" XXX a *second* sublist?
 132 .Bl -bullet
 133 .It
 134 If
 135 .Dv IPC_NOWAIT
 136 was specified, then
 137 .Fn semop
 138 returns immediately with a return value of
 139 .Er EAGAIN .
 140 .It
 141 Otherwise, the calling process is put to sleep until one of the following
 142 conditions is satisfied:
 143 .\" XXX We already have two sublists, why not a third?
 144 .Bl -bullet
 145 .It
 146 Some other process removes the semaphore with the
 147 .Dv IPC_RMID
 148 option of
 149 .Xr semctl 2 .
 150 In this case,
 151 .Fn semop
 152 returns immediately with a return value of
 153 .Er EIDRM .
 154 .It
 155 The process receives a signal that is to be caught.
 156 In this case, the process will resume execution as defined by
 157 .Xr sigaction 2 .
 158 .It
 159 The semaphore's
 160 value is greater than or equal to the absolute value of
 161 .Va sem_op .
 162 When this condition becomes true, the semaphore's value is decremented
 163 by the absolute value of
 164 .Va sem_op ,
 165 the semaphore's adjust on exit value is incremented by the
 166 absolute value of
 167 .Va sem_op .
 168 .El
 169 .El
 170 .El
 171 .Pp
 172 A negative value for
 173 .Va sem_op
 174 generally means that a process is waiting for a resource to become
 175 available.
 176 .It
 177 When
 178 .Va sem_op
 179 is zero and the process has read permission,
 180 one of the following will occur:
 181 .Bl -bullet
 182 .It
 183 If the current value of the semaphore is equal to zero
 184 then
 185 .Fn semop
 186 can return immediately.
 187 .It
 188 If
 189 .Dv IPC_NOWAIT
 190 was specified, then
 191 .Fn semop
 192 returns immediately with a return value of
 193 .Er EAGAIN .
 194 .It
 195 Otherwise, the calling process is put to sleep until one of the following
 196 conditions is satisfied:
 197 .\" XXX Another nested sublists
 198 .Bl -bullet
 199 .It
 200 Some other process removes the semaphore with the
 201 .Dv IPC_RMID
 202 option of
 203 .Xr semctl 2 .
 204 In this case,
 205 .Fn semop
 206 returns immediately with a return value of
 207 .Er EIDRM .
 208 .It
 209 The process receives a signal that is to be caught.
 210 In this case, the process will resume execution as defined by
 211 .Xr sigaction 2 .
 212 .It
 213 The semaphore's value becomes zero.
 214 .El
 215 .El
 216 .El
 217 .Pp
 218 For each semaphore a process has in use, the kernel maintains an
 219 .Dq "adjust on exit"
 220 value, as alluded to earlier.
 221 When a process
 222 exits, either voluntarily or involuntarily, the adjust on exit value
 223 for each semaphore is added to the semaphore's value.
 224 This can
 225 be used to insure that a resource is released if a process terminates
 226 unexpectedly.
 227 .Sh RETURN VALUES
 228 .Rv -std semop
 229 .Sh ERRORS
 230 The
 231 .Fn semop
 232 system call will fail if:
 233 .Bl -tag -width Er
 234 .\" ===========
 235 .It Bq Er E2BIG
 236 Too many operations are specified.
 237 .Bq Dv SEMOPM
 238 .\" ===========
 239 .It Bq Er EACCES
 240 Permission is denied, due to a mismatch between the operation
 241 and the mode of the semaphore set.
 242 .\" ===========
 243 .It Bq Er EAGAIN
 244 The semaphore's value would result
 245 in the process being put to sleep and
 246 .Dv IPC_NOWAIT
 247 is specified.
 248 .\" ===========
 249 .It Bq Er EFBIG
 250 .\"
 251 .\" I'd have thought this would be EINVAL,
 252 .\" but the source says EFBIG.
 253 .\"
 254 .Va sem_num
 255 is not in the range of valid semaphores for the set.
 256 .\" ===========
 257 .It Bq Er EIDRM
 258 The semaphore set is removed from the system.
 259 .\" ===========
 260 .It Bq Er EINTR
 261 The
 262 .Fn semop
 263 system call is interrupted by a signal.
 264 .\" ===========
 265 .It Bq Er EINVAL
 266 No semaphore set corresponds to
 267 .Fa semid ,
 268 or the process would exceed the system-defined limit
 269 for the number of per-process
 270 .Dv SEM_UNDO
 271 structures.
 272 .\" ===========
 273 .It Bq Er ENOSPC
 274 The system
 275 .Dv SEM_UNDO
 276 pool
 277 .Bq Dv SEMMNU
 278 is full.
 279 .\" ===========
 280 .It Bq Er ERANGE
 281 The requested operation would cause either
 282 the semaphore's current value
 283 .Bq Dv SEMVMX
 284 or its adjust-on-exit value
 285 .Bq Dv SEMAEM
 286 to exceed the system-imposed limits.
 287 .El
 288 .Sh LEGACY SYNOPSIS
 289 .Fd #include <sys/types.h>
 290 .Fd #include <sys/ipc.h>
 291 .Fd #include <sys/sem.h>
 292 .Pp
 293 The include files
 294 .In sys/types.h
 295 and
 296 .In sys/ipc.h
 297 are necessary.
 298 .Sh SEE ALSO
 299 .Xr semctl 2 ,
 300 .Xr semget 2 ,
 301 .Xr sigaction 2 ,
 302 .Xr compat 5
 303 .Sh BUGS
 304 The
 305 .Fn semop
 306 system call
 307 may block waiting for memory even if
 308 .Dv IPC_NOWAIT
 309 was specified.