man2/semop.2

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