1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
3 .\" Permission is granted to make and distribute verbatim copies of this
4 .\" manual provided the copyright notice and this permission notice are
5 .\" preserved on all copies.
7 .\" Permission is granted to copy and distribute modified versions of this
8 .\" manual under the conditions for verbatim copying, provided that the
9 .\" entire resulting derived work is distributed under the terms of a
10 .\" permission notice identical to this one.
12 .\" Since the Linux kernel and libraries are constantly changing, this
13 .\" manual page may be incorrect or out-of-date. The author(s) assume no
14 .\" responsibility for errors or omissions, or for damages resulting from
15 .\" the use of the information contained herein. The author(s) may not
16 .\" have taken the same level of care in the production of this manual,
17 .\" which is licensed free of charge, as they might when working
20 .\" Formatted or processed versions of this manual, if unaccompanied by
21 .\" the source, must acknowledge the copyright and authors of this work.
23 .\" Modified 1996-10-22, Eric S. Raymond <esr@thyrsus.com>
24 .\" Modified 2002-01-08, Michael Kerrisk <mtk-manpages@gmx.net>
25 .\" Modified 2003-04-28, Ernie Petrides <petrides@redhat.com>
26 .\" Modified 2004-05-27, Michael Kerrisk <mtk-manpages@gmx.net>
27 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net>
28 .\" Language and formatting clean-ups
29 .\" Added notes on /proc files
30 .\" 2005-04-08, mtk, Noted kernel version numbers for semtimedop()
32 .TH SEMOP 2 2004-11-10 "Linux" "Linux Programmer's Manual"
34 semop, semtimedop \- semaphore operations
38 #include <sys/types.h>
44 .BI "int semop(int " semid ", struct sembuf *" sops ", unsigned " nsops );
46 .BI "int semtimedop(int " semid ", struct sembuf *" sops ", unsigned " nsops ,
47 .BI " struct timespec *" timeout );
50 Each semaphore in a semaphore set has the following associated values:
54 unsigned short semval; /* semaphore value */
55 unsigned short semzcnt; /* # waiting for zero */
56 unsigned short semncnt; /* # waiting for increase */
57 pid_t sempid; /* process that did last op */
62 performs operations on selected semaphores in the set indicated by
66 elements in the array pointed to by
68 specifies an operation to be performed on a single semaphore.
69 The elements of this structure are of type
71 containing the following members:
75 unsigned short sem_num; /* semaphore number */
76 short sem_op; /* semaphore operation */
77 short sem_flg; /* operation flags */
87 If an operation specifies
89 it will be automatically undone when the process terminates.
91 The set of operations contained in
97 that is, the operations are performed either as a complete unit,
99 The behavior of the system call if not all operations can be
100 performed immediately depends on the presence of the
102 flag in the individual
104 fields, as noted below.
106 Each operation is performed on the
108 semaphore of the semaphore set, where the first semaphore of the set
110 There are three types of operation, distinguished by the value of
115 is a positive integer, the operation adds this value to
120 is specified for this operation, the system updates the process undo count
123 This operation can always proceed \(em it never forces a process to wait.
124 The calling process must have alter permission on the semaphore set.
128 is zero, the process must have read permission on the semaphore
130 This is a "wait-for-zero" operation: if
132 is zero, the operation can immediately proceed.
142 (and none of the operations in
147 (the count of processes waiting until this semaphore's value becomes zero)
148 is incremented by one and the process sleeps until
149 one of the following occurs:
152 becomes 0, at which time the value of
164 The calling process catches a signal:
174 The time limit specified by
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 updates the process undo count
203 If the absolute value of
216 (and none of the operations in
221 (the counter of processes waiting for this semaphore's value to increase)
222 is incremented by one and the process sleeps until
223 one of the following occurs:
226 becomes greater than or equal to the absolute value of
228 at which time the value of
230 is decremented, the absolute value of
236 is specified for this operation, the system updates the process undo count
240 The semaphore set is removed from the system:
247 The calling process catches a signal:
257 The time limit specified by
261 call expires: the system call fails, with
266 On successful completion, the
268 value for each semaphore specified in the array pointed to by
270 is set to the process ID of the calling process.
275 is set to the current time.
278 behaves identically to
280 except that in those cases were the calling process would sleep,
281 the duration of that sleep is limited by the amount of elapsed
282 time specified by the
284 structure whose address is passed in the
287 If the specified time limit has been reached,
293 (and none of the operations in
309 otherwise they return \-1
312 indicating the error.
316 is set to one of the following:
323 the maximum number of operations allowed per system
327 The calling process does not have the permissions required
328 to perform the specified semaphore operations,
329 and does not have the
334 An operation could not proceed immediately and either
338 or the time limit specified in
343 An address specified in either the
347 parameters isn't accessible.
350 For some operation the value of
352 is less than 0 or greater than or equal to the number
353 of semaphores in the set.
356 The semaphore set was removed.
359 While blocked in this system call, the process caught a signal.
362 The semaphore set doesn't exist, or
364 is less than zero, or
366 has a non-positive value.
371 of some operation specified
373 and the system does not have enough memory to allocate the undo
381 the implementation dependent maximum value for
385 first appeared in Linux 2.5.52,
386 and was subsequently backported into kernel 2.4.22.
389 first appeared in version 2.3.3.
392 .\" SVr4 documents additional error conditions EINVAL, EFBIG, ENOSPC.
396 structures of a process aren't inherited across a
398 system call, but they are inherited across an
403 is never automatically restarted after being interrupted by a signal handler,
404 regardless of the setting of the
406 flag when establishing a signal handler.
409 is a per\-process integer which is simply the (negative) count
410 of all semaphore operations performed specifying the
413 When a semaphore's value is directly set using the
421 values in all processes are cleared.
423 The \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, and \fIsemnct\fP values
424 for a semaphore can all be retrieved using appropriate
428 The following limits on semaphore set resources affect the
433 Maximum number of operations allowed for one
436 (on Linux, this limit can be read and modified via the third field of
437 .IR /proc/sys/kernel/sem ).
438 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
441 Maximum allowable value for
443 implementation dependent (32767).
445 The implementation has no intrinsic limits for
446 the adjust on exit maximum value
448 the system wide maximum number of undo structures
450 and the per\-process maximum number of undo entries system parameters.
452 When a process terminates, its set of associated
454 structures is used to undo the effect of all of the
455 semaphore operations it performed with the
458 This raises a difficulty: if one (or more) of these semaphore adjustments
459 would result in an attempt to decrease a semaphore's value below zero,
460 what should an implementation do?
461 One possible approach would be to block until all the semaphore
462 adjustments could be performed.
463 This is however undesirable since it could force process termination to
464 block for arbitrarily long periods.
465 Another possibility is that such semaphore adjustments could be ignored
466 altogether (somewhat analogously to failing when
468 is specified for a semaphore operation).
469 Linux adopts a third approach: decreasing the semaphore value
470 as far as possible (i.e., to zero) and allowing process
471 termination to proceed immediately.
473 In kernels 2.6.x, x <= 10, there is a bug that in some circumstances
474 prevents a process that is waiting for a semaphore value to become
475 zero from being woken up when the value does actually become zero.
476 This bug is fixed in kernel 2.6.11.
478 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110260821123863&w=2
480 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110261701025794&w=2
485 .BR capabilities (7),
486 .BR sem_overview (7),