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