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