Debian Codegraph @

upstream/debian-unstable/man2/semop.2

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