man2/semop.2

   1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" Modified 1996-10-22, Eric S. Raymond <esr@thyrsus.com>
  24 .\" Modified 2002-01-08, Michael Kerrisk <mtk-manpages@gmx.net>
  25 .\" Modified 2003-04-28, Ernie Petrides <petrides@redhat.com>
  26 .\" Modified 2004-05-27, Michael Kerrisk <mtk-manpages@gmx.net>
  27 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net>
  28 .\"     Language and formatting clean-ups
  29 .\"     Added notes on /proc files
  30 .\" 2005-04-08, mtk, Noted kernel version numbers for semtimedop()
  31 .\"
  32 .TH SEMOP 2 2004-11-10 "Linux" "Linux Programmer's Manual"
  33 .SH NAME
  34 semop, semtimedop \- semaphore operations
  35 .SH SYNOPSIS
  36 .nf
  37 .B
  38 #include <sys/types.h>
  39 .B
  40 #include <sys/ipc.h>
  41 .B
  42 #include <sys/sem.h>
  43 .sp
  44 .BI "int semop(int " semid ", struct sembuf *" sops ", unsigned " nsops );
  45 .sp
  46 .BI "int semtimedop(int " semid ", struct sembuf *" sops ", unsigned " nsops ,
  47 .BI "               struct timespec *" timeout );
  48 .fi
  49 .SH DESCRIPTION
  50 Each semaphore in a semaphore set has the following associated values:
  51 .sp
  52 .in +4n
  53 .nf
  54 unsigned short  semval;   /* semaphore value */
  55 unsigned short  semzcnt;  /* # waiting for zero */
  56 unsigned short  semncnt;  /* # waiting for increase */
  57 pid_t           sempid;   /* process that did last op */
  58 .sp
  59 .in -4n
  60 .fi
  61 .BR semop ()
  62 performs operations on selected semaphores in the set indicated by
  63 .IR semid .
  64 Each of the
  65 .I nsops
  66 elements in the array pointed to by
  67 .I sops
  68 specifies an operation to be performed on a single semaphore.
  69 The elements of this structure are of type
  70 .IR "struct sembuf" ,
  71 containing the following members:
  72 .sp
  73 .in +4n
  74 .nf
  75 unsigned short sem_num;  /* semaphore number */
  76 short          sem_op;   /* semaphore operation */
  77 short          sem_flg;  /* operation flags */
  78 .sp
  79 .in -4n
  80 .fi
  81 Flags recognized in
  82 .I sem_flg
  83 are
  84 .B IPC_NOWAIT
  85 and
  86 .BR SEM_UNDO .
  87 If an operation specifies
  88 .BR SEM_UNDO ,
  89 it will be automatically undone when the process terminates.
  90 .PP
  91 The set of operations contained in
  92 .I sops
  93 is performed in
  94 .IR "array order" ,
  95 and
  96 .IR atomically ,
  97 that is, the operations are performed either as a complete unit,
  98 or not at all.
  99 The behavior of the system call if not all operations can be
 100 performed immediately depends on the presence of the
 101 .B IPC_NOWAIT
 102 flag in the individual
 103 .I sem_flg
 104 fields, as noted below.
 105
 106 Each operation is performed on the
 107 .IR sem_num \-th
 108 semaphore of the semaphore set, where the first semaphore of the set
 109 is numbered 0.
 110 There are three types of operation, distinguished by the value of
 111 .IR sem_op .
 112 .PP
 113 If
 114 .I sem_op
 115 is a positive integer, the operation adds this value to
 116 the semaphore value
 117 .RI  ( semval ).
 118 Furthermore, if
 119 .B SEM_UNDO
 120 is specified for this operation, the system updates the process undo count
 121 .RI ( semadj )
 122 for this semaphore.
 123 This operation can always proceed \(em it never forces a process to wait.
 124 The calling process must have alter permission on the semaphore set.
 125 .PP
 126 If
 127 .I sem_op
 128 is zero, the process must have read permission on the semaphore
 129 set.
 130 This is a "wait-for-zero" operation: if
 131 .I semval
 132 is zero, the operation can immediately proceed.
 133 Otherwise, if
 134 .B IPC_NOWAIT
 135 is specified in
 136 .IR sem_flg ,
 137 .BR semop ()
 138 fails with
 139 .I errno
 140 set to
 141 .B EAGAIN
 142 (and none of the operations in
 143 .I sops
 144 is performed).
 145 Otherwise
 146 .I semzcnt
 147 (the count of processes waiting until this semaphore's value becomes zero)
 148 is incremented by one and the process sleeps until
 149 one of the following occurs:
 150 .IP \(bu
 151 .I semval
 152 becomes 0, at which time the value of
 153 .I semzcnt
 154 is decremented.
 155 .IP \(bu
 156 The semaphore set
 157 is removed:
 158 .BR semop ()
 159 fails, with
 160 .I errno
 161 set to
 162 .BR EIDRM .
 163 .IP \(bu
 164 The calling process catches a signal:
 165 the value of
 166 .I semzcnt
 167 is decremented and
 168 .BR semop ()
 169 fails, with
 170 .I errno
 171 set to
 172 .BR EINTR .
 173 .IP \(bu
 174 The time limit specified by
 175 .I timeout
 176 in a
 177 .BR semtimedop ()
 178 call expires:
 179 .BR semop ()
 180 fails, with
 181 .I errno
 182 set to
 183 .BR EAGAIN .
 184 .PP
 185 If
 186 .I sem_op
 187 is less than zero, the process must have alter permission on the
 188 semaphore set.
 189 If
 190 .I semval
 191 is greater than or equal to the absolute value of
 192 .IR sem_op ,
 193 the operation can proceed immediately:
 194 the absolute value of
 195 .I sem_op
 196 is subtracted from
 197 .IR semval ,
 198 and, if
 199 .B SEM_UNDO
 200 is specified for this operation, the system updates the process undo count
 201 .RI ( semadj )
 202 for this semaphore.
 203 If the absolute value of
 204 .I sem_op
 205 is greater than
 206 .IR semval ,
 207 and
 208 .B IPC_NOWAIT
 209 is specified in
 210 .IR sem_flg ,
 211 .BR semop ()
 212 fails, with
 213 .I errno
 214 set to
 215 .B EAGAIN
 216 (and none of the operations in
 217 .I sops
 218 is performed).
 219 Otherwise
 220 .I semncnt
 221 (the counter of processes waiting for this semaphore's value to increase)
 222 is incremented by one and the process sleeps until
 223 one of the following occurs:
 224 .IP \(bu
 225 .I semval
 226 becomes greater than or equal to the absolute value of
 227 .IR sem_op ,
 228 at which time the value of
 229 .I semncnt
 230 is decremented, the absolute value of
 231 .I sem_op
 232 is subtracted from
 233 .I semval
 234 and, if
 235 .B SEM_UNDO
 236 is specified for this operation, the system updates the process undo count
 237 .RI ( semadj )
 238 for this semaphore.
 239 .IP \(bu
 240 The semaphore set is removed from the system:
 241 .BR semop ()
 242 fails, with
 243 .I errno
 244 set to
 245 .BR EIDRM .
 246 .IP \(bu
 247 The calling process catches a signal:
 248 the value of
 249 .I semncnt
 250 is decremented and
 251 .BR semop ()
 252 fails, with
 253 .I errno
 254 set to
 255 .BR EINTR .
 256 .IP \(bu
 257 The time limit specified by
 258 .I timeout
 259 in a
 260 .BR semtimedop ()
 261 call expires: the system call fails, with
 262 .I errno
 263 set to
 264 .BR EAGAIN .
 265 .PP
 266 On successful completion, the
 267 .I sempid
 268 value for each semaphore specified in the array pointed to by
 269 .I sops
 270 is set to the process ID of the calling process.
 271 In addition, the
 272 .I sem_otime
 273 .\" and
 274 .\" .I sem_ctime
 275 is set to the current time.
 276 .PP
 277 .BR semtimedop ()
 278 behaves identically to
 279 .BR semop ()
 280 except that in those cases were the calling process would sleep,
 281 the duration of that sleep is limited by the amount of elapsed
 282 time specified by the
 283 .B timespec
 284 structure whose address is passed in the
 285 .I timeout
 286 parameter.
 287 If the specified time limit has been reached,
 288 .BR semtimedop ()
 289 fails with
 290 .I errno
 291 set to
 292 .B EAGAIN
 293 (and none of the operations in
 294 .I sops
 295 is performed).
 296 If the
 297 .I timeout
 298 parameter is NULL,
 299 then
 300 .BR semtimedop ()
 301 behaves exactly like
 302 .BR semop ().
 303 .SH "RETURN VALUE"
 304 If successful
 305 .BR semop ()
 306 and
 307 .BR semtimedop ()
 308 return 0;
 309 otherwise they return \-1
 310 with
 311 .I errno
 312 indicating the error.
 313 .SH ERRORS
 314 On failure,
 315 .I errno
 316 is set to one of the following:
 317 .TP
 318 .B E2BIG
 319 The argument
 320 .I nsops
 321 is greater than
 322 .BR SEMOPM ,
 323 the maximum number of operations allowed per system
 324 call.
 325 .TP
 326 .B EACCES
 327 The calling process does not have the permissions required
 328 to perform the specified semaphore operations,
 329 and does not have the
 330 .B CAP_IPC_OWNER
 331 capability.
 332 .TP
 333 .B EAGAIN
 334 An operation could not proceed immediately and either
 335 .BR IPC_NOWAIT
 336 was specified in
 337 .I sem_flg
 338 or the time limit specified in
 339 .I timeout
 340 expired.
 341 .TP
 342 .B EFAULT
 343 An address specified in either the
 344 .I sops
 345 or
 346 .I timeout
 347 parameters isn't accessible.
 348 .TP
 349 .B EFBIG
 350 For some operation the value of
 351 .I sem_num
 352 is less than 0 or greater than or equal to the number
 353 of semaphores in the set.
 354 .TP
 355 .B EIDRM
 356 The semaphore set was removed.
 357 .TP
 358 .B EINTR
 359 While blocked in this system call, the process caught a signal.
 360 .TP
 361 .B EINVAL
 362 The semaphore set doesn't exist, or
 363 .I semid
 364 is less than zero, or
 365 .I nsops
 366 has a non-positive value.
 367 .TP
 368 .B ENOMEM
 369 The
 370 .I sem_flg
 371 of some operation specified
 372 .B SEM_UNDO
 373 and the system does not have enough memory to allocate the undo
 374 structure.
 375 .TP
 376 .B ERANGE
 377 For some operation
 378 .I sem_op+semval
 379 is greater than
 380 .BR SEMVMX ,
 381 the implementation dependent maximum value for
 382 .IR semval .
 383 .SH VERSIONS
 384 .BR semtimedop ()
 385 first appeared in Linux 2.5.52,
 386 and was subsequently backported into kernel 2.4.22.
 387 Glibc support for
 388 .BR semtimedop ()
 389 first appeared in version 2.3.3.
 390 .SH "CONFORMING TO"
 391 SVr4, POSIX.1-2001.
 392 .\" SVr4 documents additional error conditions EINVAL, EFBIG, ENOSPC.
 393 .SH NOTES
 394 The
 395 .I sem_undo
 396 structures of a process aren't inherited across a
 397 .BR fork (2)
 398 system call, but they are inherited across an
 399 .BR execve (2)
 400 system call.
 401 .PP
 402 .BR semop ()
 403 is never automatically restarted after being interrupted by a signal handler,
 404 regardless of the setting of the
 405 .B SA_RESTART
 406 flag when establishing a signal handler.
 407 .PP
 408 .I semadj
 409 is a per\-process integer which is simply the (negative) count
 410 of all semaphore operations performed specifying the
 411 .B SEM_UNDO
 412 flag.
 413 When a semaphore's value is directly set using the
 414 .B SETVAL
 415 or
 416 .B SETALL
 417 request to
 418 .BR semctl (2),
 419 the corresponding
 420 .I semadj
 421 values in all processes are cleared.
 422 .PP
 423 The \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, and \fIsemnct\fP values
 424 for a semaphore can all be retrieved using appropriate
 425 .BR semctl (2)
 426 calls.
 427 .PP
 428 The following limits on semaphore set resources affect the
 429 .BR semop ()
 430 call:
 431 .TP
 432 .B SEMOPM
 433 Maximum number of operations allowed for one
 434 .BR semop ()
 435 call (32)
 436 (on Linux, this limit can be read and modified via the third field of
 437 .IR /proc/sys/kernel/sem ).
 438 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
 439 .TP
 440 .B SEMVMX
 441 Maximum allowable value for
 442 .IR semval :
 443 implementation dependent (32767).
 444 .PP
 445 The implementation has no intrinsic limits for
 446 the adjust on exit maximum value
 447 .RB ( SEMAEM ),
 448 the system wide maximum number of undo structures
 449 .RB ( SEMMNU )
 450 and the per\-process maximum number of undo entries system parameters.
 451 .SH BUGS
 452 When a process terminates, its set of associated
 453 .I semadj
 454 structures is used to undo the effect of all of the
 455 semaphore operations it performed with the
 456 .B SEM_UNDO
 457 flag.
 458 This raises a difficulty: if one (or more) of these semaphore adjustments
 459 would result in an attempt to decrease a semaphore's value below zero,
 460 what should an implementation do?
 461 One possible approach would be to block until all the semaphore
 462 adjustments could be performed.
 463 This is however undesirable since it could force process termination to
 464 block for arbitrarily long periods.
 465 Another possibility is that such semaphore adjustments could be ignored
 466 altogether (somewhat analogously to failing when
 467 .B IPC_NOWAIT
 468 is specified for a semaphore operation).
 469 Linux adopts a third approach: decreasing the semaphore value
 470 as far as possible (i.e., to zero) and allowing process
 471 termination to proceed immediately.
 472
 473 In kernels 2.6.x, x <= 10, there is a bug that in some circumstances
 474 prevents a process that is waiting for a semaphore value to become
 475 zero from being woken up when the value does actually become zero.
 476 This bug is fixed in kernel 2.6.11.
 477 .\" The bug report:
 478 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110260821123863&w=2
 479 .\" the fix:
 480 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110261701025794&w=2
 481 .SH "SEE ALSO"
 482 .BR semctl (2),
 483 .BR semget (2),
 484 .BR sigaction (2),
 485 .BR capabilities (7),
 486 .BR sem_overview (7),
 487 .BR svipc (7)