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