]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) |
2 | .\" | |
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. | |
6 | .\" | |
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. | |
c13182ef | 11 | .\" |
fea681da MK |
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 | |
18 | .\" professionally. | |
c13182ef | 19 | .\" |
fea681da MK |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
23 | .\" Modified 1996-10-22, Eric S. Raymond <esr@thyrsus.com> | |
305a0578 | 24 | .\" Modified 2002-01-08, Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da | 25 | .\" Modified 2003-04-28, Ernie Petrides <petrides@redhat.com> |
305a0578 | 26 | .\" Modified 2004-05-27, Michael Kerrisk <mtk-manpages@gmx.net> |
fe1c5199 MK |
27 | .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net> |
28 | .\" Language and formatting clean-ups | |
29 | .\" Added notes on /proc files | |
055fd5fa | 30 | .\" 2005-04-08, mtk, Noted kernel version numbers for semtimedop() |
fea681da | 31 | .\" |
d9343c5c | 32 | .TH SEMOP 2 2004-11-10 "Linux" "Linux Programmer's Manual" |
fea681da MK |
33 | .SH NAME |
34 | semop, semtimedop \- semaphore operations | |
35 | .SH SYNOPSIS | |
36 | .nf | |
37 | .B | |
38 | #include <sys/types.h> | |
39 | .B | |
40 | #include <sys/ipc.h> | |
41 | .B | |
42 | #include <sys/sem.h> | |
fea681da | 43 | .sp |
521bf584 | 44 | .BI "int semop(int " semid ", struct sembuf *" sops ", unsigned " nsops ); |
fea681da | 45 | .sp |
521bf584 MK |
46 | .BI "int semtimedop(int " semid ", struct sembuf *" sops ", unsigned " nsops , |
47 | .BI " struct timespec *" timeout ); | |
48 | .fi | |
fea681da | 49 | .SH DESCRIPTION |
fe1c5199 | 50 | Each semaphore in a semaphore set has the following associated values: |
fea681da MK |
51 | .sp |
52 | .in +4n | |
53 | .nf | |
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 */ | |
58 | .sp | |
59 | .in -4n | |
60 | .fi | |
fe1c5199 MK |
61 | .BR semop () |
62 | performs operations on selected semaphores in the set indicated by | |
fea681da MK |
63 | .IR semid . |
64 | Each of the | |
65 | .I nsops | |
66 | elements in the array pointed to by | |
67 | .I sops | |
fe1c5199 MK |
68 | specifies an operation to be performed on a single semaphore. |
69 | The elements of this structure are of type | |
8478ee02 | 70 | .IR "struct sembuf" , |
fe1c5199 | 71 | containing the following members: |
fea681da MK |
72 | .sp |
73 | .in +4n | |
74 | .nf | |
fe1c5199 MK |
75 | unsigned short sem_num; /* semaphore number */ |
76 | short sem_op; /* semaphore operation */ | |
77 | short sem_flg; /* operation flags */ | |
fea681da MK |
78 | .sp |
79 | .in -4n | |
80 | .fi | |
81 | Flags recognized in | |
82 | .I sem_flg | |
83 | are | |
84 | .B IPC_NOWAIT | |
85 | and | |
86 | .BR SEM_UNDO . | |
fe1c5199 | 87 | If an operation specifies |
fea681da | 88 | .BR SEM_UNDO , |
fe1c5199 | 89 | it will be automatically undone when the process terminates. |
fea681da MK |
90 | .PP |
91 | The set of operations contained in | |
92 | .I sops | |
c13182ef MK |
93 | is performed in |
94 | .IR "array order" , | |
95 | and | |
fea681da | 96 | .IR atomically , |
87f434df MK |
97 | that is, the operations are performed either as a complete unit, |
98 | or not at all. | |
d9bfdb9c | 99 | The behavior of the system call if not all operations can be |
fea681da MK |
100 | performed immediately depends on the presence of the |
101 | .B IPC_NOWAIT | |
102 | flag in the individual | |
103 | .I sem_flg | |
104 | fields, as noted below. | |
105 | ||
106 | Each operation is performed on the | |
107 | .IR sem_num \-th | |
108 | semaphore of the semaphore set, where the first semaphore of the set | |
fe1c5199 | 109 | is numbered 0. |
fea681da MK |
110 | There are three types of operation, distinguished by the value of |
111 | .IR sem_op . | |
112 | .PP | |
113 | If | |
114 | .I sem_op | |
115 | is a positive integer, the operation adds this value to | |
116 | the semaphore value | |
117 | .RI ( semval ). | |
118 | Furthermore, if | |
119 | .B SEM_UNDO | |
fe1c5199 | 120 | is specified for this operation, the system updates the process undo count |
fea681da MK |
121 | .RI ( semadj ) |
122 | for this semaphore. | |
df8a3cac | 123 | This operation can always proceed \(em it never forces a process to wait. |
fea681da MK |
124 | The calling process must have alter permission on the semaphore set. |
125 | .PP | |
126 | If | |
127 | .I sem_op | |
fe1c5199 | 128 | is zero, the process must have read permission on the semaphore |
fea681da MK |
129 | set. |
130 | This is a "wait-for-zero" operation: if | |
131 | .I semval | |
132 | is zero, the operation can immediately proceed. | |
133 | Otherwise, if | |
134 | .B IPC_NOWAIT | |
fe1c5199 | 135 | is specified in |
fea681da | 136 | .IR sem_flg , |
fe1c5199 MK |
137 | .BR semop () |
138 | fails with | |
fea681da MK |
139 | .I errno |
140 | set to | |
141 | .B EAGAIN | |
142 | (and none of the operations in | |
143 | .I sops | |
144 | is performed). | |
145 | Otherwise | |
146 | .I semzcnt | |
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: | |
150 | .IP \(bu | |
151 | .I semval | |
152 | becomes 0, at which time the value of | |
153 | .I semzcnt | |
154 | is decremented. | |
155 | .IP \(bu | |
156 | The semaphore set | |
fe1c5199 MK |
157 | is removed: |
158 | .BR semop () | |
159 | fails, with | |
fea681da MK |
160 | .I errno |
161 | set to | |
162 | .BR EIDRM . | |
163 | .IP \(bu | |
164 | The calling process catches a signal: | |
165 | the value of | |
166 | .I semzcnt | |
fe1c5199 MK |
167 | is decremented and |
168 | .BR semop () | |
169 | fails, with | |
fea681da MK |
170 | .I errno |
171 | set to | |
172 | .BR EINTR . | |
173 | .IP \(bu | |
174 | The time limit specified by | |
175 | .I timeout | |
176 | in a | |
fe1c5199 MK |
177 | .BR semtimedop () |
178 | call expires: | |
179 | .BR semop () | |
180 | fails, with | |
fea681da MK |
181 | .I errno |
182 | set to | |
183 | .BR EAGAIN . | |
184 | .PP | |
185 | If | |
186 | .I sem_op | |
187 | is less than zero, the process must have alter permission on the | |
188 | semaphore set. | |
189 | If | |
190 | .I semval | |
191 | is greater than or equal to the absolute value of | |
192 | .IR sem_op , | |
193 | the operation can proceed immediately: | |
194 | the absolute value of | |
195 | .I sem_op | |
196 | is subtracted from | |
197 | .IR semval , | |
198 | and, if | |
199 | .B SEM_UNDO | |
fe1c5199 | 200 | is specified for this operation, the system updates the process undo count |
fea681da MK |
201 | .RI ( semadj ) |
202 | for this semaphore. | |
203 | If the absolute value of | |
204 | .I sem_op | |
205 | is greater than | |
206 | .IR semval , | |
207 | and | |
208 | .B IPC_NOWAIT | |
fe1c5199 | 209 | is specified in |
fea681da | 210 | .IR sem_flg , |
fe1c5199 MK |
211 | .BR semop () |
212 | fails, with | |
fea681da MK |
213 | .I errno |
214 | set to | |
215 | .B EAGAIN | |
216 | (and none of the operations in | |
217 | .I sops | |
218 | is performed). | |
219 | Otherwise | |
220 | .I semncnt | |
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: | |
224 | .IP \(bu | |
225 | .I semval | |
226 | becomes greater than or equal to the absolute value of | |
227 | .IR sem_op , | |
228 | at which time the value of | |
229 | .I semncnt | |
230 | is decremented, the absolute value of | |
231 | .I sem_op | |
232 | is subtracted from | |
233 | .I semval | |
234 | and, if | |
235 | .B SEM_UNDO | |
fe1c5199 | 236 | is specified for this operation, the system updates the process undo count |
fea681da MK |
237 | .RI ( semadj ) |
238 | for this semaphore. | |
239 | .IP \(bu | |
fe1c5199 MK |
240 | The semaphore set is removed from the system: |
241 | .BR semop () | |
242 | fails, with | |
fea681da MK |
243 | .I errno |
244 | set to | |
245 | .BR EIDRM . | |
246 | .IP \(bu | |
247 | The calling process catches a signal: | |
248 | the value of | |
249 | .I semncnt | |
c13182ef | 250 | is decremented and |
fe1c5199 MK |
251 | .BR semop () |
252 | fails, with | |
fea681da MK |
253 | .I errno |
254 | set to | |
255 | .BR EINTR . | |
256 | .IP \(bu | |
257 | The time limit specified by | |
258 | .I timeout | |
259 | in a | |
fe1c5199 | 260 | .BR semtimedop () |
fea681da MK |
261 | call expires: the system call fails, with |
262 | .I errno | |
263 | set to | |
264 | .BR EAGAIN . | |
265 | .PP | |
266 | On successful completion, the | |
267 | .I sempid | |
268 | value for each semaphore specified in the array pointed to by | |
269 | .I sops | |
270 | is set to the process ID of the calling process. | |
271 | In addition, the | |
272 | .I sem_otime | |
273 | .\" and | |
274 | .\" .I sem_ctime | |
275 | is set to the current time. | |
276 | .PP | |
fe1c5199 | 277 | .BR semtimedop () |
c13182ef | 278 | behaves identically to |
fe1c5199 | 279 | .BR semop () |
fea681da MK |
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 | |
283 | .B timespec | |
284 | structure whose address is passed in the | |
285 | .I timeout | |
c13182ef MK |
286 | parameter. |
287 | If the specified time limit has been reached, | |
fe1c5199 MK |
288 | .BR semtimedop () |
289 | fails with | |
fea681da MK |
290 | .I errno |
291 | set to | |
292 | .B EAGAIN | |
293 | (and none of the operations in | |
294 | .I sops | |
295 | is performed). | |
296 | If the | |
297 | .I timeout | |
859ae99c | 298 | parameter is NULL, |
fea681da | 299 | then |
fe1c5199 | 300 | .BR semtimedop () |
fea681da | 301 | behaves exactly like |
fe1c5199 | 302 | .BR semop (). |
fea681da | 303 | .SH "RETURN VALUE" |
fe1c5199 MK |
304 | If successful |
305 | .BR semop () | |
c13182ef | 306 | and |
fe1c5199 MK |
307 | .BR semtimedop () |
308 | return 0; | |
8729177b | 309 | otherwise they return \-1 |
fea681da MK |
310 | with |
311 | .I errno | |
312 | indicating the error. | |
313 | .SH ERRORS | |
314 | On failure, | |
315 | .I errno | |
316 | is set to one of the following: | |
317 | .TP | |
318 | .B E2BIG | |
319 | The argument | |
320 | .I nsops | |
321 | is greater than | |
322 | .BR SEMOPM , | |
323 | the maximum number of operations allowed per system | |
324 | call. | |
325 | .TP | |
326 | .B EACCES | |
327 | The calling process does not have the permissions required | |
328 | to perform the specified semaphore operations, | |
329 | and does not have the | |
330 | .B CAP_IPC_OWNER | |
331 | capability. | |
332 | .TP | |
333 | .B EAGAIN | |
334 | An operation could not proceed immediately and either | |
335 | .BR IPC_NOWAIT | |
fe1c5199 | 336 | was specified in |
fea681da MK |
337 | .I sem_flg |
338 | or the time limit specified in | |
339 | .I timeout | |
340 | expired. | |
341 | .TP | |
342 | .B EFAULT | |
343 | An address specified in either the | |
344 | .I sops | |
345 | or | |
346 | .I timeout | |
347 | parameters isn't accessible. | |
348 | .TP | |
349 | .B EFBIG | |
350 | For some operation the value of | |
351 | .I sem_num | |
352 | is less than 0 or greater than or equal to the number | |
353 | of semaphores in the set. | |
354 | .TP | |
355 | .B EIDRM | |
356 | The semaphore set was removed. | |
357 | .TP | |
358 | .B EINTR | |
359 | While blocked in this system call, the process caught a signal. | |
360 | .TP | |
361 | .B EINVAL | |
362 | The semaphore set doesn't exist, or | |
363 | .I semid | |
364 | is less than zero, or | |
365 | .I nsops | |
366 | has a non-positive value. | |
367 | .TP | |
368 | .B ENOMEM | |
369 | The | |
370 | .I sem_flg | |
fe1c5199 | 371 | of some operation specified |
fea681da MK |
372 | .B SEM_UNDO |
373 | and the system does not have enough memory to allocate the undo | |
374 | structure. | |
375 | .TP | |
376 | .B ERANGE | |
377 | For some operation | |
378 | .I sem_op+semval | |
379 | is greater than | |
380 | .BR SEMVMX , | |
381 | the implementation dependent maximum value for | |
382 | .IR semval . | |
4f73a46c MK |
383 | .SH VERSIONS |
384 | .BR semtimedop () | |
385 | first appeared in Linux 2.5.52, | |
386 | and was subsequently backported into kernel 2.4.22. | |
988db661 | 387 | Glibc support for |
4f73a46c MK |
388 | .BR semtimedop () |
389 | first appeared in version 2.3.3. | |
a1d5f77c MK |
390 | .SH "CONFORMING TO" |
391 | SVr4, POSIX.1-2001. | |
392 | .\" SVr4 documents additional error conditions EINVAL, EFBIG, ENOSPC. | |
fea681da MK |
393 | .SH NOTES |
394 | The | |
395 | .I sem_undo | |
396 | structures of a process aren't inherited across a | |
397 | .BR fork (2) | |
fe1c5199 | 398 | system call, but they are inherited across an |
fea681da MK |
399 | .BR execve (2) |
400 | system call. | |
401 | .PP | |
fe1c5199 | 402 | .BR semop () |
fea681da MK |
403 | is never automatically restarted after being interrupted by a signal handler, |
404 | regardless of the setting of the | |
405 | .B SA_RESTART | |
fe1c5199 | 406 | flag when establishing a signal handler. |
fea681da MK |
407 | .PP |
408 | .I semadj | |
409 | is a per\-process integer which is simply the (negative) count | |
410 | of all semaphore operations performed specifying the | |
411 | .B SEM_UNDO | |
412 | flag. | |
413 | When a semaphore's value is directly set using the | |
414 | .B SETVAL | |
415 | or | |
416 | .B SETALL | |
417 | request to | |
418 | .BR semctl (2), | |
419 | the corresponding | |
420 | .I semadj | |
421 | values in all processes are cleared. | |
422 | .PP | |
423 | The \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, and \fIsemnct\fP values | |
424 | for a semaphore can all be retrieved using appropriate | |
425 | .BR semctl (2) | |
426 | calls. | |
427 | .PP | |
540036b2 | 428 | The following limits on semaphore set resources affect the |
fe1c5199 | 429 | .BR semop () |
fea681da MK |
430 | call: |
431 | .TP | |
432 | .B SEMOPM | |
433 | Maximum number of operations allowed for one | |
fe1c5199 MK |
434 | .BR semop () |
435 | call (32) | |
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 | |
fea681da MK |
439 | .TP |
440 | .B SEMVMX | |
441 | Maximum allowable value for | |
442 | .IR semval : | |
443 | implementation dependent (32767). | |
444 | .PP | |
445 | The implementation has no intrinsic limits for | |
446 | the adjust on exit maximum value | |
447 | .RB ( SEMAEM ), | |
448 | the system wide maximum number of undo structures | |
449 | .RB ( SEMMNU ) | |
450 | and the per\-process maximum number of undo entries system parameters. | |
451 | .SH BUGS | |
452 | When a process terminates, its set of associated | |
453 | .I semadj | |
454 | structures is used to undo the effect of all of the | |
455 | semaphore operations it performed with the | |
456 | .B SEM_UNDO | |
457 | flag. | |
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 | |
467 | .B IPC_NOWAIT | |
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. | |
3e4d52e1 | 472 | |
c13182ef MK |
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 | |
3e4d52e1 MK |
475 | zero from being woken up when the value does actually become zero. |
476 | This bug is fixed in kernel 2.6.11. | |
477 | .\" The bug report: | |
478 | .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110260821123863&w=2 | |
479 | .\" the fix: | |
480 | .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110261701025794&w=2 | |
fea681da MK |
481 | .SH "SEE ALSO" |
482 | .BR semctl (2), | |
483 | .BR semget (2), | |
484 | .BR sigaction (2), | |
f675ea37 | 485 | .BR capabilities (7), |
2c5e151c MK |
486 | .BR sem_overview (7), |
487 | .BR svipc (7) |