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