]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) |
2 | .\" | |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
4 | .\" |
5 | .\" Modified 1996-10-22, Eric S. Raymond <esr@thyrsus.com> | |
c11b1abf | 6 | .\" Modified 2002-01-08, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 7 | .\" Modified 2003-04-28, Ernie Petrides <petrides@redhat.com> |
c11b1abf MK |
8 | .\" Modified 2004-05-27, Michael Kerrisk <mtk.manpages@gmail.com> |
9 | .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com> | |
fe1c5199 MK |
10 | .\" Language and formatting clean-ups |
11 | .\" Added notes on /proc files | |
055fd5fa | 12 | .\" 2005-04-08, mtk, Noted kernel version numbers for semtimedop() |
dd9b25a6 | 13 | .\" 2007-07-09, mtk, Added an EXAMPLE code segment. |
fea681da | 14 | .\" |
45186a5d | 15 | .TH SEMOP 2 2021-03-22 "Linux man-pages (unreleased)" |
fea681da | 16 | .SH NAME |
47f065d6 | 17 | semop, semtimedop \- System V semaphore operations |
45e6e287 AC |
18 | .SH LIBRARY |
19 | Standard C library | |
8fc3b2cf | 20 | .RI ( libc ", " \-lc ) |
fea681da MK |
21 | .SH SYNOPSIS |
22 | .nf | |
2fadbfb5 | 23 | .B #include <sys/sem.h> |
68e4db0a | 24 | .PP |
4a60035c | 25 | .BI "int semop(int " semid ", struct sembuf *" sops ", size_t " nsops ); |
4a60035c RV |
26 | .BI "int semtimedop(int " semid ", struct sembuf *" sops ", size_t " nsops , |
27 | .BI " const struct timespec *" timeout ); | |
521bf584 | 28 | .fi |
68e4db0a | 29 | .PP |
d39ad78f | 30 | .RS -4 |
cc4615cc MK |
31 | Feature Test Macro Requirements for glibc (see |
32 | .BR feature_test_macros (7)): | |
d39ad78f | 33 | .RE |
68e4db0a | 34 | .PP |
cc4615cc | 35 | .BR semtimedop (): |
1dd0d7b4 MK |
36 | .nf |
37 | _GNU_SOURCE | |
38 | .fi | |
fea681da | 39 | .SH DESCRIPTION |
efbfd7ec | 40 | Each semaphore in a System\ V semaphore set |
47f065d6 | 41 | has the following associated values: |
bdd915e2 | 42 | .PP |
fea681da | 43 | .in +4n |
b8302363 | 44 | .EX |
fea681da MK |
45 | unsigned short semval; /* semaphore value */ |
46 | unsigned short semzcnt; /* # waiting for zero */ | |
47 | unsigned short semncnt; /* # waiting for increase */ | |
cd65c2b1 | 48 | pid_t sempid; /* PID of process that last |
b9c93deb | 49 | .EE |
3cf61490 | 50 | .in |
bdd915e2 | 51 | .PP |
fe1c5199 MK |
52 | .BR semop () |
53 | performs operations on selected semaphores in the set indicated by | |
fea681da MK |
54 | .IR semid . |
55 | Each of the | |
56 | .I nsops | |
57 | elements in the array pointed to by | |
58 | .I sops | |
be031d85 | 59 | is a structure that |
fe1c5199 MK |
60 | specifies an operation to be performed on a single semaphore. |
61 | The elements of this structure are of type | |
8478ee02 | 62 | .IR "struct sembuf" , |
fe1c5199 | 63 | containing the following members: |
51f5698d | 64 | .PP |
fea681da | 65 | .in +4n |
b8302363 | 66 | .EX |
fe1c5199 MK |
67 | unsigned short sem_num; /* semaphore number */ |
68 | short sem_op; /* semaphore operation */ | |
69 | short sem_flg; /* operation flags */ | |
b8302363 | 70 | .EE |
e646a1ba | 71 | .in |
ba39b288 | 72 | .PP |
fea681da MK |
73 | Flags recognized in |
74 | .I sem_flg | |
75 | are | |
76 | .B IPC_NOWAIT | |
77 | and | |
78 | .BR SEM_UNDO . | |
fe1c5199 | 79 | If an operation specifies |
fea681da | 80 | .BR SEM_UNDO , |
fe1c5199 | 81 | it will be automatically undone when the process terminates. |
fea681da MK |
82 | .PP |
83 | The set of operations contained in | |
84 | .I sops | |
c13182ef MK |
85 | is performed in |
86 | .IR "array order" , | |
87 | and | |
fea681da | 88 | .IR atomically , |
87f434df MK |
89 | that is, the operations are performed either as a complete unit, |
90 | or not at all. | |
d9bfdb9c | 91 | The behavior of the system call if not all operations can be |
fea681da MK |
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. | |
efeece04 | 97 | .PP |
fea681da MK |
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 | |
fe1c5199 | 101 | is numbered 0. |
fea681da MK |
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 | |
b41a5d54 MK |
112 | is specified for this operation, the system subtracts the value |
113 | .I sem_op | |
114 | from the semaphore adjustment | |
fea681da | 115 | .RI ( semadj ) |
b41a5d54 | 116 | value for this semaphore. |
352c778d | 117 | This operation can always proceed\(emit never forces a thread to wait. |
fea681da MK |
118 | The calling process must have alter permission on the semaphore set. |
119 | .PP | |
120 | If | |
121 | .I sem_op | |
fe1c5199 | 122 | is zero, the process must have read permission on the semaphore |
fea681da MK |
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 | |
fe1c5199 | 129 | is specified in |
fea681da | 130 | .IR sem_flg , |
fe1c5199 MK |
131 | .BR semop () |
132 | fails with | |
fea681da MK |
133 | .I errno |
134 | set to | |
135 | .B EAGAIN | |
136 | (and none of the operations in | |
137 | .I sops | |
138 | is performed). | |
68bcc5ff | 139 | Otherwise, |
fea681da | 140 | .I semzcnt |
352c778d MK |
141 | (the count of threads waiting until this semaphore's value becomes zero) |
142 | is incremented by one and the thread sleeps until | |
fea681da | 143 | one of the following occurs: |
5abea51f | 144 | .IP \(bu 2 |
fea681da MK |
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 | |
fe1c5199 MK |
151 | is removed: |
152 | .BR semop () | |
153 | fails, with | |
fea681da MK |
154 | .I errno |
155 | set to | |
156 | .BR EIDRM . | |
157 | .IP \(bu | |
352c778d | 158 | The calling thread catches a signal: |
fea681da MK |
159 | the value of |
160 | .I semzcnt | |
fe1c5199 MK |
161 | is decremented and |
162 | .BR semop () | |
163 | fails, with | |
fea681da MK |
164 | .I errno |
165 | set to | |
166 | .BR EINTR . | |
fea681da MK |
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 | |
b41a5d54 MK |
183 | is specified for this operation, the system adds the absolute value of |
184 | .I sem_op | |
185 | to the semaphore adjustment | |
fea681da | 186 | .RI ( semadj ) |
b41a5d54 | 187 | value for this semaphore. |
fea681da MK |
188 | If the absolute value of |
189 | .I sem_op | |
190 | is greater than | |
191 | .IR semval , | |
192 | and | |
193 | .B IPC_NOWAIT | |
fe1c5199 | 194 | is specified in |
fea681da | 195 | .IR sem_flg , |
fe1c5199 MK |
196 | .BR semop () |
197 | fails, with | |
fea681da MK |
198 | .I errno |
199 | set to | |
200 | .B EAGAIN | |
201 | (and none of the operations in | |
202 | .I sops | |
203 | is performed). | |
68bcc5ff | 204 | Otherwise, |
fea681da | 205 | .I semncnt |
352c778d MK |
206 | (the counter of threads waiting for this semaphore's value to increase) |
207 | is incremented by one and the thread sleeps until | |
fea681da | 208 | one of the following occurs: |
5abea51f | 209 | .IP \(bu 2 |
fea681da MK |
210 | .I semval |
211 | becomes greater than or equal to the absolute value of | |
b41a5d54 MK |
212 | .IR sem_op : |
213 | the operation now proceeds, as described above. | |
fea681da | 214 | .IP \(bu |
fe1c5199 MK |
215 | The semaphore set is removed from the system: |
216 | .BR semop () | |
217 | fails, with | |
fea681da MK |
218 | .I errno |
219 | set to | |
220 | .BR EIDRM . | |
221 | .IP \(bu | |
352c778d | 222 | The calling thread catches a signal: |
fea681da MK |
223 | the value of |
224 | .I semncnt | |
c13182ef | 225 | is decremented and |
fe1c5199 MK |
226 | .BR semop () |
227 | fails, with | |
fea681da MK |
228 | .I errno |
229 | set to | |
230 | .BR EINTR . | |
fea681da MK |
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 | |
352c778d | 236 | is set to the caller's process ID. |
fea681da MK |
237 | In addition, the |
238 | .I sem_otime | |
239 | .\" and | |
240 | .\" .I sem_ctime | |
241 | is set to the current time. | |
d9817570 | 242 | .SS semtimedop() |
fe1c5199 | 243 | .BR semtimedop () |
c13182ef | 244 | behaves identically to |
fe1c5199 | 245 | .BR semop () |
0649de17 | 246 | except that in those cases where the calling thread would sleep, |
fea681da MK |
247 | the duration of that sleep is limited by the amount of elapsed |
248 | time specified by the | |
66ee0c7e | 249 | .I timespec |
fea681da MK |
250 | structure whose address is passed in the |
251 | .I timeout | |
c4bb193f | 252 | argument. |
73655200 MK |
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.) | |
c13182ef | 256 | If the specified time limit has been reached, |
fe1c5199 MK |
257 | .BR semtimedop () |
258 | fails with | |
fea681da MK |
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 | |
c4bb193f | 267 | argument is NULL, |
fea681da | 268 | then |
fe1c5199 | 269 | .BR semtimedop () |
fea681da | 270 | behaves exactly like |
fe1c5199 | 271 | .BR semop (). |
efeece04 | 272 | .PP |
2013e2eb | 273 | Note that if |
92909040 | 274 | .BR semtimedop () |
2013e2eb MK |
275 | is interrupted by a signal, causing the call to fail with the error |
276 | .BR EINTR , | |
277 | the contents of | |
1ae6b2c7 | 278 | .I timeout |
2013e2eb | 279 | are left unchanged. |
47297adb | 280 | .SH RETURN VALUE |
9862ec0c | 281 | On success, |
fe1c5199 | 282 | .BR semop () |
c13182ef | 283 | and |
fe1c5199 | 284 | .BR semtimedop () |
9862ec0c MK |
285 | return 0. |
286 | On failure, they return \-1, and set | |
fea681da | 287 | .I errno |
9862ec0c | 288 | to indicate the error. |
fea681da | 289 | .SH ERRORS |
fea681da MK |
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 | |
3294109d | 304 | capability in the user namespace that governs its IPC namespace. |
fea681da MK |
305 | .TP |
306 | .B EAGAIN | |
307 | An operation could not proceed immediately and either | |
0daa9e92 | 308 | .B IPC_NOWAIT |
fe1c5199 | 309 | was specified in |
fea681da MK |
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 | |
c4bb193f | 318 | or the |
fea681da | 319 | .I timeout |
c4bb193f | 320 | argument isn't accessible. |
fea681da MK |
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 | |
352c778d | 332 | While blocked in this system call, the thread caught a signal; see |
01538d0d | 333 | .BR signal (7). |
fea681da MK |
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 | |
657316c0 | 340 | has a nonpositive value. |
fea681da MK |
341 | .TP |
342 | .B ENOMEM | |
343 | The | |
344 | .I sem_flg | |
fe1c5199 | 345 | of some operation specified |
fea681da MK |
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 . | |
4f73a46c MK |
357 | .SH VERSIONS |
358 | .BR semtimedop () | |
359 | first appeared in Linux 2.5.52, | |
360 | and was subsequently backported into kernel 2.4.22. | |
988db661 | 361 | Glibc support for |
4f73a46c MK |
362 | .BR semtimedop () |
363 | first appeared in version 2.3.3. | |
3113c7f3 | 364 | .SH STANDARDS |
ead51cab | 365 | POSIX.1-2001, POSIX.1-2008, SVr4. |
a1d5f77c | 366 | .\" SVr4 documents additional error conditions EINVAL, EFBIG, ENOSPC. |
fea681da MK |
367 | .SH NOTES |
368 | The | |
369 | .I sem_undo | |
55aa2920 MK |
370 | structures of a process aren't inherited by the child produced by |
371 | .BR fork (2), | |
372 | but they are inherited across an | |
fea681da MK |
373 | .BR execve (2) |
374 | system call. | |
375 | .PP | |
fe1c5199 | 376 | .BR semop () |
fea681da MK |
377 | is never automatically restarted after being interrupted by a signal handler, |
378 | regardless of the setting of the | |
379 | .B SA_RESTART | |
fe1c5199 | 380 | flag when establishing a signal handler. |
efeece04 | 381 | .PP |
b41a5d54 MK |
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 | |
fea681da MK |
386 | .B SEM_UNDO |
387 | flag. | |
b41a5d54 MK |
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). | |
fea681da MK |
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. | |
9d64e39e | 406 | The |
4f6396e2 | 407 | .BR clone (2) |
9d64e39e MK |
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. | |
efeece04 | 414 | .PP |
fea681da MK |
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. | |
0dc55d1b | 419 | .SS Semaphore limits |
540036b2 | 420 | The following limits on semaphore set resources affect the |
fe1c5199 | 421 | .BR semop () |
fea681da MK |
422 | call: |
423 | .TP | |
424 | .B SEMOPM | |
425 | Maximum number of operations allowed for one | |
fe1c5199 | 426 | .BR semop () |
98f792f7 MK |
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 . | |
fe1c5199 | 434 | .\" This /proc file is not available in Linux 2.2 and earlier -- MTK |
98f792f7 MK |
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 | |
bf7bc8b8 | 439 | .BR semop () |
98f792f7 | 440 | fails due to kernel memory fragmentation when allocating memory to copy the |
1ae6b2c7 | 441 | .I sops |
98f792f7 | 442 | array. |
fea681da MK |
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 ) | |
2706f299 | 454 | and the per-process maximum number of undo entries system parameters. |
fea681da MK |
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. | |
efeece04 | 476 | .PP |
c13182ef | 477 | In kernels 2.6.x, x <= 10, there is a bug that in some circumstances |
352c778d | 478 | prevents a thread that is waiting for a semaphore value to become |
3e4d52e1 MK |
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 | |
a14af333 | 485 | .SH EXAMPLES |
dd9b25a6 MK |
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. | |
408731d4 MK |
490 | .PP |
491 | .in +4n | |
492 | .EX | |
493 | struct sembuf sops[2]; | |
494 | int semid; | |
dd9b25a6 | 495 | |
408731d4 | 496 | /* Code to set \fIsemid\fP omitted */ |
dd9b25a6 | 497 | |
408731d4 MK |
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; | |
dd9b25a6 | 501 | |
408731d4 MK |
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; | |
dd9b25a6 | 505 | |
408731d4 MK |
506 | if (semop(semid, sops, 2) == \-1) { |
507 | perror("semop"); | |
508 | exit(EXIT_FAILURE); | |
509 | } | |
510 | .EE | |
511 | .in | |
26c8d4bb MK |
512 | .PP |
513 | A further example of the use of | |
514 | .BR semop () | |
515 | can be found in | |
516 | .BR shmop (2). | |
47297adb | 517 | .SH SEE ALSO |
f81b78a4 | 518 | .BR clone (2), |
fea681da MK |
519 | .BR semctl (2), |
520 | .BR semget (2), | |
521 | .BR sigaction (2), | |
f675ea37 | 522 | .BR capabilities (7), |
2c5e151c | 523 | .BR sem_overview (7), |
343cdc5a | 524 | .BR sysvipc (7), |
1d7c4d16 | 525 | .BR time (7) |