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