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 2020-04-11 "Linux" "Linux Programmer's Manual"
37 semop, semtimedop \- System V semaphore operations
40 .B #include <sys/types.h>
41 .B #include <sys/ipc.h>
42 .B #include <sys/sem.h>
44 .BI "int semop(int " semid ", struct sembuf *" sops ", size_t " nsops );
46 .BI "int semtimedop(int " semid ", struct sembuf *" sops ", size_t " nsops ,
47 .BI " const struct timespec *" timeout );
51 Feature Test Macro Requirements for glibc (see
52 .BR feature_test_macros (7)):
58 Each semaphore in a System\ V semaphore set
59 has the following associated values:
63 unsigned short semval; /* semaphore value */
64 unsigned short semzcnt; /* # waiting for zero */
65 unsigned short semncnt; /* # waiting for increase */
66 pid_t sempid; /* PID of process that last
71 performs operations on selected semaphores in the set indicated by
75 elements in the array pointed to by
78 specifies an operation to be performed on a single semaphore.
79 The elements of this structure are of type
81 containing the following members:
85 unsigned short sem_num; /* semaphore number */
86 short sem_op; /* semaphore operation */
87 short sem_flg; /* operation flags */
97 If an operation specifies
99 it will be automatically undone when the process terminates.
101 The set of operations contained in
107 that is, the operations are performed either as a complete unit,
109 The behavior of the system call if not all operations can be
110 performed immediately depends on the presence of the
112 flag in the individual
114 fields, as noted below.
116 Each operation is performed on the
118 semaphore of the semaphore set, where the first semaphore of the set
120 There are three types of operation, distinguished by the value of
125 is a positive integer, the operation adds this value to
130 is specified for this operation, the system subtracts the value
132 from the semaphore adjustment
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.
140 is zero, the process must have read permission on the semaphore
142 This is a "wait-for-zero" operation: if
144 is zero, the operation can immediately proceed.
154 (and none of the operations in
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:
164 becomes 0, at which time the value of
176 The calling thread catches a signal:
188 is less than zero, the process must have alter permission on the
192 is greater than or equal to the absolute value of
194 the operation can proceed immediately:
195 the absolute value of
201 is specified for this operation, the system adds the absolute value of
203 to the semaphore adjustment
205 value for this semaphore.
206 If the absolute value of
219 (and none of the operations in
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:
229 becomes greater than or equal to the absolute value of
231 the operation now proceeds, as described above.
233 The semaphore set is removed from the system:
240 The calling thread catches a signal:
250 On successful completion, the
252 value for each semaphore specified in the array pointed to by
254 is set to the caller's process ID.
259 is set to the current time.
262 behaves identically to
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
268 structure whose address is passed in the
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,
280 (and none of the operations in
293 is interrupted by a signal, causing the call to fail with the error
304 otherwise they return \-1
307 indicating the error.
311 is set to one of the following:
318 the maximum number of operations allowed per system
322 The calling process does not have the permissions required
323 to perform the specified semaphore operations,
324 and does not have the
326 capability in the user namespace that governs its IPC namespace.
329 An operation could not proceed immediately and either
333 or the time limit specified in
338 An address specified in either the
342 argument isn't accessible.
345 For some operation the value of
347 is less than 0 or greater than or equal to the number
348 of semaphores in the set.
351 The semaphore set was removed.
354 While blocked in this system call, the thread caught a signal; see
358 The semaphore set doesn't exist, or
360 is less than zero, or
362 has a nonpositive value.
367 of some operation specified
369 and the system does not have enough memory to allocate the undo
377 the implementation dependent maximum value for
381 first appeared in Linux 2.5.52,
382 and was subsequently backported into kernel 2.4.22.
385 first appeared in version 2.3.3.
387 POSIX.1-2001, POSIX.1-2008, SVr4.
388 .\" SVr4 documents additional error conditions EINVAL, EFBIG, ENOSPC.
394 isn't required on Linux or by any version of POSIX.
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.
405 structures of a process aren't inherited by the child produced by
407 but they are inherited across an
412 is never automatically restarted after being interrupted by a signal handler,
413 regardless of the setting of the
415 flag when establishing a signal handler.
417 A semaphore adjustment
419 value is a per-process, per-semaphore integer that is the negated sum
420 of all operations performed on a semaphore specifying the
423 Each process has a list of
425 values\(emone value for each semaphore on which it has operated using
427 When a process terminates, each of its per-semaphore
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
440 values in all processes are cleared.
444 flag allows more than one process to share a
450 The \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, and \fIsemnct\fP values
451 for a semaphore can all be retrieved using appropriate
455 The following limits on semaphore set resources affect the
460 Maximum number of operations allowed for one
464 .\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4
465 the default value for this limit was 32.
466 Since Linux 3.19, the default value is 500.
467 On Linux, this limit can be read and modified via the third field of
468 .IR /proc/sys/kernel/sem .
469 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
471 this limit should not be raised above 1000,
472 .\" See comment in Linux 3.19 source file include/uapi/linux/sem.h
473 because of the risk of that
475 fails due to kernel memory fragmentation when allocating memory to copy the
480 Maximum allowable value for
482 implementation dependent (32767).
484 The implementation has no intrinsic limits for
485 the adjust on exit maximum value
487 the system wide maximum number of undo structures
489 and the per-process maximum number of undo entries system parameters.
491 When a process terminates, its set of associated
493 structures is used to undo the effect of all of the
494 semaphore operations it performed with the
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
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.
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.
517 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110260821123863&w=2
519 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110261701025794&w=2
521 The following code segment uses
523 to atomically wait for the value of semaphore 0 to become zero,
524 and then increment the semaphore value by one.
528 struct sembuf sops[2];
531 /* Code to set \fIsemid\fP omitted */
533 sops[0].sem_num = 0; /* Operate on semaphore 0 */
534 sops[0].sem_op = 0; /* Wait for value to equal 0 */
537 sops[1].sem_num = 0; /* Operate on semaphore 0 */
538 sops[1].sem_op = 1; /* Increment value by one */
541 if (semop(semid, sops, 2) == \-1) {
548 A further example of the use of
557 .BR capabilities (7),
558 .BR sem_overview (7),