]>
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. | |
11 | .\" | |
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. | |
19 | .\" | |
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 | |
fea681da | 30 | .\" |
fe1c5199 | 31 | .TH SEMOP 2 2004-11-10 "Linux 2.6.9" "Linux Programmer's Manual" |
fea681da MK |
32 | .SH NAME |
33 | semop, semtimedop \- semaphore operations | |
34 | .SH SYNOPSIS | |
35 | .nf | |
36 | .B | |
37 | #include <sys/types.h> | |
38 | .B | |
39 | #include <sys/ipc.h> | |
40 | .B | |
41 | #include <sys/sem.h> | |
42 | .fi | |
43 | .sp | |
44 | .BI "int semop(int " semid , | |
45 | .BI "struct sembuf *" sops , | |
46 | .BI "unsigned " nsops ); | |
47 | .sp | |
48 | .BI "int semtimedop(int " semid , | |
49 | .BI "struct sembuf *" sops , | |
50 | .BI "unsigned " nsops , | |
51 | .BI "struct timespec *" timeout ); | |
52 | .SH DESCRIPTION | |
fe1c5199 | 53 | Each semaphore in a semaphore set has the following associated values: |
fea681da MK |
54 | .sp |
55 | .in +4n | |
56 | .nf | |
57 | unsigned short semval; /* semaphore value */ | |
58 | unsigned short semzcnt; /* # waiting for zero */ | |
59 | unsigned short semncnt; /* # waiting for increase */ | |
60 | pid_t sempid; /* process that did last op */ | |
61 | .sp | |
62 | .in -4n | |
63 | .fi | |
fe1c5199 MK |
64 | .BR semop () |
65 | performs operations on selected semaphores in the set indicated by | |
fea681da MK |
66 | .IR semid . |
67 | Each of the | |
68 | .I nsops | |
69 | elements in the array pointed to by | |
70 | .I sops | |
fe1c5199 MK |
71 | specifies an operation to be performed on a single semaphore. |
72 | The elements of this structure are of type | |
73 | .BR "struct sembuf" , | |
74 | containing the following members: | |
fea681da MK |
75 | .sp |
76 | .in +4n | |
77 | .nf | |
fe1c5199 MK |
78 | unsigned short sem_num; /* semaphore number */ |
79 | short sem_op; /* semaphore operation */ | |
80 | short sem_flg; /* operation flags */ | |
fea681da MK |
81 | .sp |
82 | .in -4n | |
83 | .fi | |
84 | Flags recognized in | |
85 | .I sem_flg | |
86 | are | |
87 | .B IPC_NOWAIT | |
88 | and | |
89 | .BR SEM_UNDO . | |
fe1c5199 | 90 | If an operation specifies |
fea681da | 91 | .BR SEM_UNDO , |
fe1c5199 | 92 | it will be automatically undone when the process terminates. |
fea681da MK |
93 | .PP |
94 | The set of operations contained in | |
95 | .I sops | |
96 | is performed | |
97 | .IR atomically , | |
98 | that is, the operations are performed at the same time, and only | |
99 | if they can all be simultaneously performed. | |
100 | The behaviour of the system call if not all operations can be | |
101 | performed immediately depends on the presence of the | |
102 | .B IPC_NOWAIT | |
103 | flag in the individual | |
104 | .I sem_flg | |
105 | fields, as noted below. | |
106 | ||
107 | Each operation is performed on the | |
108 | .IR sem_num \-th | |
109 | semaphore of the semaphore set, where the first semaphore of the set | |
fe1c5199 | 110 | is numbered 0. |
fea681da MK |
111 | There are three types of operation, distinguished by the value of |
112 | .IR sem_op . | |
113 | .PP | |
114 | If | |
115 | .I sem_op | |
116 | is a positive integer, the operation adds this value to | |
117 | the semaphore value | |
118 | .RI ( semval ). | |
119 | Furthermore, if | |
120 | .B SEM_UNDO | |
fe1c5199 | 121 | is specified for this operation, the system updates the process undo count |
fea681da MK |
122 | .RI ( semadj ) |
123 | for this semaphore. | |
124 | This operation can always proceed \- it never forces a process to wait. | |
125 | The calling process must have alter permission on the semaphore set. | |
126 | .PP | |
127 | If | |
128 | .I sem_op | |
fe1c5199 | 129 | is zero, the process must have read permission on the semaphore |
fea681da MK |
130 | set. |
131 | This is a "wait-for-zero" operation: if | |
132 | .I semval | |
133 | is zero, the operation can immediately proceed. | |
134 | Otherwise, if | |
135 | .B IPC_NOWAIT | |
fe1c5199 | 136 | is specified in |
fea681da | 137 | .IR sem_flg , |
fe1c5199 MK |
138 | .BR semop () |
139 | fails with | |
fea681da MK |
140 | .I errno |
141 | set to | |
142 | .B EAGAIN | |
143 | (and none of the operations in | |
144 | .I sops | |
145 | is performed). | |
146 | Otherwise | |
147 | .I semzcnt | |
148 | (the count of processes waiting until this semaphore's value becomes zero) | |
149 | is incremented by one and the process sleeps until | |
150 | one of the following occurs: | |
151 | .IP \(bu | |
152 | .I semval | |
153 | becomes 0, at which time the value of | |
154 | .I semzcnt | |
155 | is decremented. | |
156 | .IP \(bu | |
157 | The semaphore set | |
fe1c5199 MK |
158 | is removed: |
159 | .BR semop () | |
160 | fails, with | |
fea681da MK |
161 | .I errno |
162 | set to | |
163 | .BR EIDRM . | |
164 | .IP \(bu | |
165 | The calling process catches a signal: | |
166 | the value of | |
167 | .I semzcnt | |
fe1c5199 MK |
168 | is decremented and |
169 | .BR semop () | |
170 | fails, with | |
fea681da MK |
171 | .I errno |
172 | set to | |
173 | .BR EINTR . | |
174 | .IP \(bu | |
175 | The time limit specified by | |
176 | .I timeout | |
177 | in a | |
fe1c5199 MK |
178 | .BR semtimedop () |
179 | call expires: | |
180 | .BR semop () | |
181 | fails, with | |
fea681da MK |
182 | .I errno |
183 | set to | |
184 | .BR EAGAIN . | |
185 | .PP | |
186 | If | |
187 | .I sem_op | |
188 | is less than zero, the process must have alter permission on the | |
189 | semaphore set. | |
190 | If | |
191 | .I semval | |
192 | is greater than or equal to the absolute value of | |
193 | .IR sem_op , | |
194 | the operation can proceed immediately: | |
195 | the absolute value of | |
196 | .I sem_op | |
197 | is subtracted from | |
198 | .IR semval , | |
199 | and, if | |
200 | .B SEM_UNDO | |
fe1c5199 | 201 | is specified for this operation, the system updates the process undo count |
fea681da MK |
202 | .RI ( semadj ) |
203 | for this semaphore. | |
204 | If the absolute value of | |
205 | .I sem_op | |
206 | is greater than | |
207 | .IR semval , | |
208 | and | |
209 | .B IPC_NOWAIT | |
fe1c5199 | 210 | is specified in |
fea681da | 211 | .IR sem_flg , |
fe1c5199 MK |
212 | .BR semop () |
213 | fails, with | |
fea681da MK |
214 | .I errno |
215 | set to | |
216 | .B EAGAIN | |
217 | (and none of the operations in | |
218 | .I sops | |
219 | is performed). | |
220 | Otherwise | |
221 | .I semncnt | |
222 | (the counter of processes waiting for this semaphore's value to increase) | |
223 | is incremented by one and the process sleeps until | |
224 | one of the following occurs: | |
225 | .IP \(bu | |
226 | .I semval | |
227 | becomes greater than or equal to the absolute value of | |
228 | .IR sem_op , | |
229 | at which time the value of | |
230 | .I semncnt | |
231 | is decremented, the absolute value of | |
232 | .I sem_op | |
233 | is subtracted from | |
234 | .I semval | |
235 | and, if | |
236 | .B SEM_UNDO | |
fe1c5199 | 237 | is specified for this operation, the system updates the process undo count |
fea681da MK |
238 | .RI ( semadj ) |
239 | for this semaphore. | |
240 | .IP \(bu | |
fe1c5199 MK |
241 | The semaphore set is removed from the system: |
242 | .BR semop () | |
243 | fails, with | |
fea681da MK |
244 | .I errno |
245 | set to | |
246 | .BR EIDRM . | |
247 | .IP \(bu | |
248 | The calling process catches a signal: | |
249 | the value of | |
250 | .I semncnt | |
fe1c5199 MK |
251 | is decremented and |
252 | .BR semop () | |
253 | fails, with | |
fea681da MK |
254 | .I errno |
255 | set to | |
256 | .BR EINTR . | |
257 | .IP \(bu | |
258 | The time limit specified by | |
259 | .I timeout | |
260 | in a | |
fe1c5199 | 261 | .BR semtimedop () |
fea681da MK |
262 | call expires: the system call fails, with |
263 | .I errno | |
264 | set to | |
265 | .BR EAGAIN . | |
266 | .PP | |
267 | On successful completion, the | |
268 | .I sempid | |
269 | value for each semaphore specified in the array pointed to by | |
270 | .I sops | |
271 | is set to the process ID of the calling process. | |
272 | In addition, the | |
273 | .I sem_otime | |
274 | .\" and | |
275 | .\" .I sem_ctime | |
276 | is set to the current time. | |
277 | .PP | |
fe1c5199 MK |
278 | .BR semtimedop () |
279 | behaves identically to | |
280 | .BR semop () | |
fea681da MK |
281 | except that in those cases were the calling process would sleep, |
282 | the duration of that sleep is limited by the amount of elapsed | |
283 | time specified by the | |
284 | .B timespec | |
285 | structure whose address is passed in the | |
286 | .I timeout | |
287 | parameter. 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 | |
298 | parameter is | |
299 | .BR NULL , | |
300 | then | |
fe1c5199 | 301 | .BR semtimedop () |
fea681da | 302 | behaves exactly like |
fe1c5199 | 303 | .BR semop (). |
fea681da | 304 | .SH "RETURN VALUE" |
fe1c5199 MK |
305 | If successful |
306 | .BR semop () | |
307 | and | |
308 | .BR semtimedop () | |
309 | return 0; | |
310 | otherwise they return -1 | |
fea681da MK |
311 | with |
312 | .I errno | |
313 | indicating the error. | |
314 | .SH ERRORS | |
315 | On failure, | |
316 | .I errno | |
317 | is set to one of the following: | |
318 | .TP | |
319 | .B E2BIG | |
320 | The argument | |
321 | .I nsops | |
322 | is greater than | |
323 | .BR SEMOPM , | |
324 | the maximum number of operations allowed per system | |
325 | call. | |
326 | .TP | |
327 | .B EACCES | |
328 | The calling process does not have the permissions required | |
329 | to perform the specified semaphore operations, | |
330 | and does not have the | |
331 | .B CAP_IPC_OWNER | |
332 | capability. | |
333 | .TP | |
334 | .B EAGAIN | |
335 | An operation could not proceed immediately and either | |
336 | .BR IPC_NOWAIT | |
fe1c5199 | 337 | was specified in |
fea681da MK |
338 | .I sem_flg |
339 | or the time limit specified in | |
340 | .I timeout | |
341 | expired. | |
342 | .TP | |
343 | .B EFAULT | |
344 | An address specified in either the | |
345 | .I sops | |
346 | or | |
347 | .I timeout | |
348 | parameters isn't accessible. | |
349 | .TP | |
350 | .B EFBIG | |
351 | For some operation the value of | |
352 | .I sem_num | |
353 | is less than 0 or greater than or equal to the number | |
354 | of semaphores in the set. | |
355 | .TP | |
356 | .B EIDRM | |
357 | The semaphore set was removed. | |
358 | .TP | |
359 | .B EINTR | |
360 | While blocked in this system call, the process caught a signal. | |
361 | .TP | |
362 | .B EINVAL | |
363 | The semaphore set doesn't exist, or | |
364 | .I semid | |
365 | is less than zero, or | |
366 | .I nsops | |
367 | has a non-positive value. | |
368 | .TP | |
369 | .B ENOMEM | |
370 | The | |
371 | .I sem_flg | |
fe1c5199 | 372 | of some operation specified |
fea681da MK |
373 | .B SEM_UNDO |
374 | and the system does not have enough memory to allocate the undo | |
375 | structure. | |
376 | .TP | |
377 | .B ERANGE | |
378 | For some operation | |
379 | .I sem_op+semval | |
380 | is greater than | |
381 | .BR SEMVMX , | |
382 | the implementation dependent maximum value for | |
383 | .IR semval . | |
384 | .SH NOTES | |
385 | The | |
386 | .I sem_undo | |
387 | structures of a process aren't inherited across a | |
388 | .BR fork (2) | |
fe1c5199 | 389 | system call, but they are inherited across an |
fea681da MK |
390 | .BR execve (2) |
391 | system call. | |
392 | .PP | |
fe1c5199 | 393 | .BR semop () |
fea681da MK |
394 | is never automatically restarted after being interrupted by a signal handler, |
395 | regardless of the setting of the | |
396 | .B SA_RESTART | |
fe1c5199 | 397 | flag when establishing a signal handler. |
fea681da MK |
398 | .PP |
399 | .I semadj | |
400 | is a per\-process integer which is simply the (negative) count | |
401 | of all semaphore operations performed specifying the | |
402 | .B SEM_UNDO | |
403 | flag. | |
404 | When a semaphore's value is directly set using the | |
405 | .B SETVAL | |
406 | or | |
407 | .B SETALL | |
408 | request to | |
409 | .BR semctl (2), | |
410 | the corresponding | |
411 | .I semadj | |
412 | values in all processes are cleared. | |
413 | .PP | |
414 | The \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, and \fIsemnct\fP values | |
415 | for a semaphore can all be retrieved using appropriate | |
416 | .BR semctl (2) | |
417 | calls. | |
418 | .PP | |
540036b2 | 419 | The following limits on semaphore set resources affect the |
fe1c5199 | 420 | .BR semop () |
fea681da MK |
421 | call: |
422 | .TP | |
423 | .B SEMOPM | |
424 | Maximum number of operations allowed for one | |
fe1c5199 MK |
425 | .BR semop () |
426 | call (32) | |
427 | (on Linux, this limit can be read and modified via the third field of | |
428 | .IR /proc/sys/kernel/sem ). | |
429 | .\" This /proc file is not available in Linux 2.2 and earlier -- MTK | |
fea681da MK |
430 | .TP |
431 | .B SEMVMX | |
432 | Maximum allowable value for | |
433 | .IR semval : | |
434 | implementation dependent (32767). | |
435 | .PP | |
436 | The implementation has no intrinsic limits for | |
437 | the adjust on exit maximum value | |
438 | .RB ( SEMAEM ), | |
439 | the system wide maximum number of undo structures | |
440 | .RB ( SEMMNU ) | |
441 | and the per\-process maximum number of undo entries system parameters. | |
442 | .SH BUGS | |
443 | When a process terminates, its set of associated | |
444 | .I semadj | |
445 | structures is used to undo the effect of all of the | |
446 | semaphore operations it performed with the | |
447 | .B SEM_UNDO | |
448 | flag. | |
449 | This raises a difficulty: if one (or more) of these semaphore adjustments | |
450 | would result in an attempt to decrease a semaphore's value below zero, | |
451 | what should an implementation do? | |
452 | One possible approach would be to block until all the semaphore | |
453 | adjustments could be performed. | |
454 | This is however undesirable since it could force process termination to | |
455 | block for arbitrarily long periods. | |
456 | Another possibility is that such semaphore adjustments could be ignored | |
457 | altogether (somewhat analogously to failing when | |
458 | .B IPC_NOWAIT | |
459 | is specified for a semaphore operation). | |
460 | Linux adopts a third approach: decreasing the semaphore value | |
461 | as far as possible (i.e., to zero) and allowing process | |
462 | termination to proceed immediately. | |
463 | .SH "CONFORMING TO" | |
464 | SVr4, SVID. SVr4 documents additional error conditions EINVAL, EFBIG, | |
465 | ENOSPC. | |
466 | .SH "SEE ALSO" | |
467 | .BR semctl (2), | |
468 | .BR semget (2), | |
469 | .BR sigaction (2), | |
470 | .BR ipc (5), | |
471 | .BR capabilities (7) |