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