original/man2/semop.2

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