lib/libc/sys/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$
  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 LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In sys/types.h
  38 .In sys/ipc.h
  39 .In sys/sem.h
  40 .Ft int
  41 .Fn semop "int semid" "struct sembuf *array" "size_t nops"
  42 .Sh DESCRIPTION
  43 The
  44 .Fn semop
  45 system call
  46 atomically performs the array of operations indicated by
  47 .Fa array
  48 on the semaphore set indicated by
  49 .Fa semid .
  50 The length of
  51 .Fa array
  52 is indicated by
  53 .Fa nops .
  54 Each operation is encoded in a
  55 .Vt "struct sembuf" ,
  56 which is defined as follows:
  57 .\"
  58 .\" From <sys/sem.h>
  59 .\"
  60 .Bd -literal
  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 array ,
  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 ensure 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 .It Bq Er EINVAL
 235 No semaphore set corresponds to
 236 .Fa semid ,
 237 or the process would exceed the system-defined limit for the number of
 238 per-process
 239 .Dv SEM_UNDO
 240 structures.
 241 .It Bq Er EACCES
 242 Permission denied due to mismatch between operation and mode of
 243 semaphore set.
 244 .It Bq Er EAGAIN
 245 The semaphore's value would have resulted in the process being put to sleep
 246 and
 247 .Dv IPC_NOWAIT
 248 was specified.
 249 .It Bq Er E2BIG
 250 Too many operations were specified.
 251 .Bq Dv SEMOPM
 252 .It Bq Er EFBIG
 253 .\"
 254 .\" I'd have thought this would be EINVAL, but the source says
 255 .\" EFBIG.
 256 .\"
 257 .Va sem_num
 258 was not in the range of valid semaphores for the set.
 259 .It Bq Er EIDRM
 260 The semaphore set was removed from the system.
 261 .It Bq Er EINTR
 262 The
 263 .Fn semop
 264 system call was interrupted by a signal.
 265 .It Bq Er ENOSPC
 266 The system
 267 .Dv SEM_UNDO
 268 pool
 269 .Bq Dv SEMMNU
 270 is full.
 271 .It Bq Er ERANGE
 272 The requested operation would cause either
 273 the semaphore's current value
 274 .Bq Dv SEMVMX
 275 or its adjust on exit value
 276 .Bq Dv SEMAEM
 277 to exceed the system-imposed limits.
 278 .El
 279 .Sh SEE ALSO
 280 .Xr semctl 2 ,
 281 .Xr semget 2 ,
 282 .Xr sigaction 2
 283 .Sh BUGS
 284 The
 285 .Fn semop
 286 system call
 287 may block waiting for memory even if
 288 .Dv IPC_NOWAIT
 289 was specified.