1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
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.
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.
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
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
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.
35 .TH SEMOP 2 2021-03-22 "Linux" "Linux Programmer's Manual"
37 semop, semtimedop \- System V semaphore operations
40 .B #include <sys/sem.h>
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 );
48 Feature Test Macro Requirements for glibc (see
49 .BR feature_test_macros (7)):
57 Each semaphore in a System\ V semaphore set
58 has the following associated values:
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
70 performs operations on selected semaphores in the set indicated by
74 elements in the array pointed to by
77 specifies an operation to be performed on a single semaphore.
78 The elements of this structure are of type
80 containing the following members:
84 unsigned short sem_num; /* semaphore number */
85 short sem_op; /* semaphore operation */
86 short sem_flg; /* operation flags */
96 If an operation specifies
98 it will be automatically undone when the process terminates.
100 The set of operations contained in
106 that is, the operations are performed either as a complete unit,
108 The behavior of the system call if not all operations can be
109 performed immediately depends on the presence of the
111 flag in the individual
113 fields, as noted below.
115 Each operation is performed on the
117 semaphore of the semaphore set, where the first semaphore of the set
119 There are three types of operation, distinguished by the value of
124 is a positive integer, the operation adds this value to
129 is specified for this operation, the system subtracts the value
131 from the semaphore adjustment
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.
139 is zero, the process must have read permission on the semaphore
141 This is a "wait-for-zero" operation: if
143 is zero, the operation can immediately proceed.
153 (and none of the operations in
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:
163 becomes 0, at which time the value of
175 The calling thread catches a signal:
187 is less than zero, the process must have alter permission on the
191 is greater than or equal to the absolute value of
193 the operation can proceed immediately:
194 the absolute value of
200 is specified for this operation, the system adds the absolute value of
202 to the semaphore adjustment
204 value for this semaphore.
205 If the absolute value of
218 (and none of the operations in
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:
228 becomes greater than or equal to the absolute value of
230 the operation now proceeds, as described above.
232 The semaphore set is removed from the system:
239 The calling thread catches a signal:
249 On successful completion, the
251 value for each semaphore specified in the array pointed to by
253 is set to the caller's process ID.
258 is set to the current time.
261 behaves identically to
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
267 structure whose address is passed in the
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,
279 (and none of the operations in
292 is interrupted by a signal, causing the call to fail with the error
303 On failure, they return \-1, and set
305 to indicate the error.
313 the maximum number of operations allowed per system
317 The calling process does not have the permissions required
318 to perform the specified semaphore operations,
319 and does not have the
321 capability in the user namespace that governs its IPC namespace.
324 An operation could not proceed immediately and either
328 or the time limit specified in
333 An address specified in either the
337 argument isn't accessible.
340 For some operation the value of
342 is less than 0 or greater than or equal to the number
343 of semaphores in the set.
346 The semaphore set was removed.
349 While blocked in this system call, the thread caught a signal; see
353 The semaphore set doesn't exist, or
355 is less than zero, or
357 has a nonpositive value.
362 of some operation specified
364 and the system does not have enough memory to allocate the undo
372 the implementation dependent maximum value for
376 first appeared in Linux 2.5.52,
377 and was subsequently backported into kernel 2.4.22.
380 first appeared in version 2.3.3.
382 POSIX.1-2001, POSIX.1-2008, SVr4.
383 .\" SVr4 documents additional error conditions EINVAL, EFBIG, ENOSPC.
387 structures of a process aren't inherited by the child produced by
389 but they are inherited across an
394 is never automatically restarted after being interrupted by a signal handler,
395 regardless of the setting of the
397 flag when establishing a signal handler.
399 A semaphore adjustment
401 value is a per-process, per-semaphore integer that is the negated sum
402 of all operations performed on a semaphore specifying the
405 Each process has a list of
407 values\(emone value for each semaphore on which it has operated using
409 When a process terminates, each of its per-semaphore
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
422 values in all processes are cleared.
426 flag allows more than one process to share a
432 The \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, and \fIsemnct\fP values
433 for a semaphore can all be retrieved using appropriate
437 The following limits on semaphore set resources affect the
442 Maximum number of operations allowed for one
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
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
457 fails due to kernel memory fragmentation when allocating memory to copy the
462 Maximum allowable value for
464 implementation dependent (32767).
466 The implementation has no intrinsic limits for
467 the adjust on exit maximum value
469 the system wide maximum number of undo structures
471 and the per-process maximum number of undo entries system parameters.
473 When a process terminates, its set of associated
475 structures is used to undo the effect of all of the
476 semaphore operations it performed with the
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
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.
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.
499 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110260821123863&w=2
501 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110261701025794&w=2
503 The following code segment uses
505 to atomically wait for the value of semaphore 0 to become zero,
506 and then increment the semaphore value by one.
510 struct sembuf sops[2];
513 /* Code to set \fIsemid\fP omitted */
515 sops[0].sem_num = 0; /* Operate on semaphore 0 */
516 sops[0].sem_op = 0; /* Wait for value to equal 0 */
519 sops[1].sem_num = 0; /* Operate on semaphore 0 */
520 sops[1].sem_op = 1; /* Increment value by one */
523 if (semop(semid, sops, 2) == \-1) {
530 A further example of the use of
539 .BR capabilities (7),
540 .BR sem_overview (7),