]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) |
1130df60 | 2 | .\" and Copyright 2004, 2005 Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da MK |
3 | .\" |
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. | |
23 | .\" | |
24 | .\" Modified Tue Oct 22 17:53:56 1996 by Eric S. Raymond <esr@thyrsus.com> | |
25 | .\" Modified Fri Jun 19 10:59:15 1998 by Andries Brouwer <aeb@cwi.nl> | |
26 | .\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer <aeb@cwi.nl> | |
305a0578 | 27 | .\" Modified 20 Dec 2001, Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da | 28 | .\" Modified 21 Dec 2001, aeb |
305a0578 | 29 | .\" Modified 27 May 2004, Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da | 30 | .\" Added notes on CAP_IPC_OWNER requirement |
305a0578 | 31 | .\" Modified 17 Jun 2004, Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da | 32 | .\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID |
70d0e5ef MK |
33 | .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net> |
34 | .\" Language and formatting clean-ups | |
35 | .\" Rewrote semun text | |
36 | .\" Added semid_ds and ipc_perm structure definitions | |
24ed820a | 37 | .\" 2005-08-02, mtk: Added IPC_INFO, SEM_INFO, SEM_STAT descriptions. |
fea681da | 38 | .\" |
d9343c5c | 39 | .TH SEMCTL 2 2004-11-10 "Linux" "Linux Programmer's Manual" |
fea681da MK |
40 | .SH NAME |
41 | semctl \- semaphore control operations | |
42 | .SH SYNOPSIS | |
43 | .nf | |
44 | .B #include <sys/types.h> | |
45 | .B #include <sys/ipc.h> | |
46 | .B #include <sys/sem.h> | |
47 | .sp | |
48 | .BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);" | |
49 | .fi | |
50 | .SH DESCRIPTION | |
540036b2 | 51 | .BR semctl () |
fea681da MK |
52 | performs the control operation specified by |
53 | .I cmd | |
54 | on the semaphore set identified by | |
55 | .IR semid , | |
56 | or on the | |
57 | .IR semnum -th | |
58 | semaphore of that set. | |
70d0e5ef | 59 | (The semaphores in a set are numbered starting at 0.) |
fea681da | 60 | .PP |
70d0e5ef MK |
61 | This function has three or four arguments, depending on |
62 | .IR cmd . | |
63 | When there are four, the fourth has the type | |
64 | .IR "union semun" . | |
65 | The \fIcalling program\fP must define this union as follows: | |
fea681da MK |
66 | |
67 | .nf | |
70d0e5ef | 68 | .in +4n |
fea681da | 69 | union semun { |
70d0e5ef MK |
70 | int val; /* Value for SETVAL */ |
71 | struct semid_ds *buf; /* Buffer for IPC_STAT, IPC_SET */ | |
72 | unsigned short *array; /* Array for GETALL, SETALL */ | |
c13182ef | 73 | struct seminfo *__buf; /* Buffer for IPC_INFO |
70d0e5ef | 74 | (Linux specific) */ |
fea681da | 75 | }; |
70d0e5ef | 76 | .in -4n |
fea681da MK |
77 | .fi |
78 | .PP | |
70d0e5ef MK |
79 | The |
80 | .I semid_ds | |
c84371c6 | 81 | data structure is defined in \fI<sys/sem.h>\fP as follows: |
70d0e5ef MK |
82 | .nf |
83 | .in +4n | |
84 | ||
85 | struct semid_ds { | |
86 | struct ipc_perm sem_perm; /* Ownership and permissions | |
87 | time_t sem_otime; /* Last semop time */ | |
88 | time_t sem_ctime; /* Last change time */ | |
89 | unsigned short sem_nsems; /* No. of semaphores in set */ | |
90 | }; | |
91 | .in -4n | |
92 | .fi | |
93 | .PP | |
94 | The | |
95 | .I ipc_perm | |
c84371c6 | 96 | structure is defined in \fI<sys/ipc.h>\fP as follows |
70d0e5ef MK |
97 | (the highlighted fields are settable using |
98 | .BR IPC_SET ): | |
99 | .PP | |
100 | .nf | |
101 | .in +4n | |
102 | struct ipc_perm { | |
0bfa087b | 103 | key_t key; /* Key supplied to semget(2) */ |
70d0e5ef MK |
104 | uid_t \fBuid\fP; /* Effective UID of owner */ |
105 | gid_t \fBgid\fP; /* Effective GID of owner */ | |
106 | uid_t cuid; /* Effective UID of creator */ | |
107 | gid_t cgid; /* Effective GID of creator */ | |
108 | unsigned short \fBmode\fP; /* Permissions */ | |
109 | unsigned short seq; /* Sequence number */ | |
110 | }; | |
111 | .in -4n | |
112 | .fi | |
113 | .PP | |
114 | Valid values for | |
fea681da MK |
115 | .I cmd |
116 | are: | |
117 | .TP 12 | |
118 | .B IPC_STAT | |
70d0e5ef MK |
119 | Copy information from the kernel data structure associated with |
120 | .I semid | |
121 | into the | |
122 | .I semid_ds | |
123 | structure pointed to by | |
124 | .IR arg.buf . | |
fea681da MK |
125 | The argument |
126 | .I semnum | |
127 | is ignored. | |
70d0e5ef | 128 | The calling process must have read permission on the semaphore set. |
fea681da MK |
129 | .TP |
130 | .B IPC_SET | |
131 | Write the values of some members of the | |
70d0e5ef | 132 | .I semid_ds |
fea681da | 133 | structure pointed to by |
70d0e5ef MK |
134 | .I arg.buf |
135 | to the kernel data structure associated with this semaphore set, | |
136 | updating also its | |
137 | .I sem_ctime | |
fea681da | 138 | member. |
c13182ef | 139 | The following members of the structure are updated: |
70d0e5ef MK |
140 | .IR sem_perm.uid , |
141 | .IR sem_perm.gid , | |
142 | and (the least significant 9 bits of) | |
143 | .IR sem_perm.mode . | |
144 | The effective UID of the calling process must match the owner | |
145 | .RI ( sem_perm.uid ) | |
c13182ef | 146 | or creator |
70d0e5ef MK |
147 | .RI ( sem_perm.cuid ) |
148 | of the semaphore set, or the caller must be privileged. | |
fea681da MK |
149 | The argument |
150 | .I semnum | |
151 | is ignored. | |
152 | .TP | |
153 | .B IPC_RMID | |
70d0e5ef MK |
154 | Immediately remove the semaphore set, |
155 | awakening all processes blocked in | |
0bfa087b | 156 | .BR semop (2) |
70d0e5ef MK |
157 | calls on the set (with an error return and |
158 | .I errno | |
fea681da MK |
159 | set to |
160 | .BR EIDRM ). | |
499d62f2 | 161 | The effective user ID of the calling process must |
540036b2 MK |
162 | match the creator or owner of the semaphore set, |
163 | or the caller must be privileged. | |
fea681da MK |
164 | The argument |
165 | .I semnum | |
166 | is ignored. | |
167 | .TP | |
24ed820a | 168 | .BR IPC_INFO " (Linux specific)" |
c13182ef | 169 | Returns information about system-wide semaphore limits and |
24ed820a MK |
170 | parameters in the structure pointed to by |
171 | .IR arg.__buf . | |
172 | This structure is of type | |
173 | .IR seminfo , | |
174 | defined in | |
175 | .I <sys/sem.h> | |
682edefb MK |
176 | if the |
177 | .BR _GNU_SOURCE | |
178 | feature test macro is defined: | |
24ed820a MK |
179 | .nf |
180 | .in +2n | |
181 | ||
182 | struct seminfo { | |
c13182ef | 183 | int semmap; /* # of entries in semaphore map; |
24ed820a MK |
184 | unused */ |
185 | int semmni; /* Max. # of semaphore sets */ | |
c13182ef | 186 | int semmns; /* Max. # of semaphores in all |
24ed820a | 187 | semaphore sets */ |
c13182ef | 188 | int semmnu; /* System-wide max. # of undo |
24ed820a MK |
189 | structures; unused */ |
190 | int semmsl; /* Max. # of semaphores in a set */ | |
0bfa087b | 191 | int semopm; /* Max. # of operations for semop(2) */ |
c13182ef | 192 | int semume; /* Max. # of undo entries per |
24ed820a MK |
193 | process; unused */ |
194 | int semusz; /* size of struct sem_undo */ | |
195 | int semvmx; /* Maximum semaphore value */ | |
c13182ef | 196 | int semaem; /* Max. value that can be recorded for |
24ed820a MK |
197 | semaphore adjustment (SEM_UNDO) */ |
198 | }; | |
199 | ||
200 | .in -2n | |
201 | .fi | |
c13182ef | 202 | The |
24ed820a MK |
203 | .IR semmsl , |
204 | .IR semmns , | |
205 | .IR semopm , | |
206 | and | |
207 | .I semmni | |
208 | settings can be changed via | |
209 | .IR /proc/sys/kernel/sem ; | |
210 | see | |
c13182ef | 211 | .BR proc (5) |
24ed820a MK |
212 | for details. |
213 | .TP | |
214 | .BR SEM_INFO " (Linux specific)" | |
215 | Returns a | |
216 | .I seminfo | |
217 | structure containing the same information as for | |
218 | .BR IPC_INFO , | |
c13182ef | 219 | except that the following fields are returned with information |
24ed820a MK |
220 | about system resources consumed by semaphores: the |
221 | .I semusz | |
c13182ef | 222 | field returns the number of semaphore sets that currently exist |
24ed820a MK |
223 | on the system; and the |
224 | .I semaem | |
c13182ef | 225 | field returns the total number of semaphores in all semaphore sets |
24ed820a MK |
226 | on the system. |
227 | .TP | |
228 | .BR SEM_STAT " (Linux specific)" | |
c13182ef MK |
229 | Returns a |
230 | .I semid_ds | |
24ed820a MK |
231 | structure as for |
232 | .BR IPC_STAT . | |
233 | However, the | |
234 | .I semid | |
235 | argument is not a semaphore identifier, but instead an index into | |
236 | the kernel's internal array that maintains information about | |
237 | all semaphore sets on the system. | |
238 | .TP | |
fea681da MK |
239 | .B GETALL |
240 | Return | |
241 | .B semval | |
70d0e5ef | 242 | (i.e., the current value) |
fea681da | 243 | for all semaphores of the set into |
70d0e5ef | 244 | .IB arg.array . |
fea681da MK |
245 | The argument |
246 | .I semnum | |
247 | is ignored. | |
70d0e5ef | 248 | The calling process must have read permission on the semaphore set. |
fea681da MK |
249 | .TP |
250 | .B GETNCNT | |
251 | The system call returns the value of | |
252 | .B semncnt | |
70d0e5ef MK |
253 | (i.e., the number of processes waiting for the value of |
254 | this semaphore to increase) for the | |
fea681da MK |
255 | .IR semnum \-th |
256 | semaphore of the set | |
75b94dc3 | 257 | (i.e., the number of processes waiting for an increase of |
fea681da MK |
258 | .B semval |
259 | for the | |
260 | .IR semnum \-th | |
261 | semaphore of the set). | |
70d0e5ef | 262 | The calling process must have read permission on the semaphore set. |
fea681da MK |
263 | .TP |
264 | .B GETPID | |
265 | The system call returns the value of | |
266 | .B sempid | |
267 | for the | |
268 | .IR semnum \-th | |
269 | semaphore of the set | |
70d0e5ef | 270 | (i.e. the PID of the process that executed the last |
0bfa087b | 271 | .BR semop (2) |
fea681da MK |
272 | call for the |
273 | .IR semnum \-th | |
274 | semaphore of the set). | |
70d0e5ef | 275 | The calling process must have read permission on the semaphore set. |
fea681da MK |
276 | .TP |
277 | .B GETVAL | |
278 | The system call returns the value of | |
279 | .B semval | |
280 | for the | |
281 | .IR semnum \-th | |
282 | semaphore of the set. | |
70d0e5ef | 283 | The calling process must have read permission on the semaphore set. |
fea681da MK |
284 | .TP |
285 | .B GETZCNT | |
286 | The system call returns the value of | |
287 | .B semzcnt | |
70d0e5ef MK |
288 | (i.e., the number of processes waiting for the value of |
289 | this semaphore to become zero) for the | |
fea681da MK |
290 | .IR semnum \-th |
291 | semaphore of the set | |
292 | (i.e. the number of processes waiting for | |
293 | .B semval | |
294 | of the | |
295 | .IR semnum \-th | |
296 | semaphore of the set to become 0). | |
70d0e5ef | 297 | The calling process must have read permission on the semaphore set. |
fea681da MK |
298 | .TP |
299 | .B SETALL | |
300 | Set | |
301 | .B semval | |
302 | for all semaphores of the set using | |
70d0e5ef | 303 | .IB arg.array , |
fea681da | 304 | updating also the |
70d0e5ef | 305 | .I sem_ctime |
fea681da | 306 | member of the |
70d0e5ef MK |
307 | .I semid_ds |
308 | structure associated with the set. | |
309 | Undo entries (see | |
310 | .BR semop (2)) | |
311 | are cleared for altered semaphores in all processes. | |
312 | If the changes to semaphore values would permit blocked | |
0bfa087b | 313 | .BR semop (2) |
70d0e5ef | 314 | calls in other processes to proceed, then those processes are woken up. |
fea681da MK |
315 | The argument |
316 | .I semnum | |
317 | is ignored. | |
70d0e5ef MK |
318 | The calling process must have alter (write) permission on |
319 | the semaphore set. | |
fea681da MK |
320 | .TP |
321 | .B SETVAL | |
322 | Set the value of | |
323 | .B semval | |
324 | to | |
70d0e5ef | 325 | .IB arg.val |
fea681da MK |
326 | for the |
327 | .IR semnum \-th | |
328 | semaphore of the set, updating also the | |
70d0e5ef | 329 | .I sem_ctime |
fea681da | 330 | member of the |
70d0e5ef MK |
331 | .I semid_ds |
332 | structure associated with the set. | |
fea681da | 333 | Undo entries are cleared for altered semaphores in all processes. |
70d0e5ef | 334 | If the changes to semaphore values would permit blocked |
0bfa087b | 335 | .BR semop (2) |
70d0e5ef MK |
336 | calls in other processes to proceed, then those processes are woken up. |
337 | The calling process must have alter permission on the semaphore set. | |
fea681da MK |
338 | .SH "RETURN VALUE" |
339 | On failure | |
540036b2 | 340 | .BR semctl () |
70d0e5ef | 341 | returns \-1 |
fea681da | 342 | with |
70d0e5ef | 343 | .I errno |
fea681da | 344 | indicating the error. |
24ed820a | 345 | |
18be658d | 346 | Otherwise the system call returns a non-negative value depending on |
fea681da MK |
347 | .I cmd |
348 | as follows: | |
349 | .TP 11 | |
350 | .B GETNCNT | |
351 | the value of | |
352 | .BR semncnt . | |
353 | .TP | |
354 | .B GETPID | |
355 | the value of | |
356 | .BR sempid . | |
357 | .TP | |
358 | .B GETVAL | |
359 | the value of | |
360 | .BR semval . | |
361 | .TP | |
362 | .B GETZCNT | |
363 | the value of | |
364 | .BR semzcnt . | |
24ed820a MK |
365 | .TP |
366 | .B IPC_INFO | |
367 | the index of the highest used entry in the | |
368 | kernel's internal array recording information about all | |
369 | semaphore sets. | |
370 | (This information can be used with repeated | |
c13182ef | 371 | .B SEM_STAT |
24ed820a MK |
372 | operations to obtain information about all semaphore sets on the system.) |
373 | .TP | |
374 | .B SEM_INFO | |
c13182ef | 375 | As for |
24ed820a MK |
376 | .BR IPC_INFO . |
377 | .TP | |
378 | .B SEM_STAT | |
379 | the identifier of the semaphore set whose index was given in | |
380 | .IR semid . | |
fea681da MK |
381 | .LP |
382 | All other | |
383 | .I cmd | |
384 | values return 0 on success. | |
385 | .SH ERRORS | |
386 | On failure, | |
70d0e5ef | 387 | .I errno |
fea681da MK |
388 | will be set to one of the following: |
389 | .TP 11 | |
390 | .B EACCES | |
391 | The argument | |
392 | .I cmd | |
393 | has one of the values | |
394 | .BR GETALL , | |
395 | .BR GETPID , | |
396 | .BR GETVAL , | |
397 | .BR GETNCNT , | |
398 | .BR GETZCNT , | |
399 | .BR IPC_STAT , | |
400 | .BR SEM_STAT , | |
401 | .BR SETALL , | |
402 | or | |
403 | .B SETVAL | |
404 | and the calling process does not have the required | |
405 | permissions on the semaphore set and does not have the | |
406 | .B CAP_IPC_OWNER | |
407 | capability. | |
408 | .TP | |
409 | .B EFAULT | |
410 | The address pointed to by | |
70d0e5ef | 411 | .IB arg.buf |
fea681da | 412 | or |
70d0e5ef | 413 | .IB arg.array |
fea681da MK |
414 | isn't accessible. |
415 | .TP | |
416 | .B EIDRM | |
417 | The semaphore set was removed. | |
418 | .TP | |
419 | .B EINVAL | |
420 | Invalid value for | |
421 | .I cmd | |
422 | or | |
423 | .IR semid . | |
24ed820a MK |
424 | Or: for a |
425 | .B SEM_STAT | |
c13182ef | 426 | operation, the index value specified in |
24ed820a MK |
427 | .I semid |
428 | referred to an array slot that is currently unused. | |
fea681da MK |
429 | .TP |
430 | .B EPERM | |
431 | The argument | |
432 | .I cmd | |
70d0e5ef | 433 | has the value |
fea681da MK |
434 | .B IPC_SET |
435 | or | |
436 | .B IPC_RMID | |
70d0e5ef | 437 | but the effective user ID of the calling process is not the creator |
fea681da MK |
438 | (as found in |
439 | .IR sem_perm.cuid ) | |
440 | or the owner | |
441 | (as found in | |
442 | .IR sem_perm.uid ) | |
443 | of the semaphore set, | |
444 | and the process does not have the | |
445 | .B CAP_SYS_ADMIN | |
446 | capability. | |
447 | .TP | |
448 | .B ERANGE | |
449 | The argument | |
450 | .I cmd | |
70d0e5ef | 451 | has the value |
fea681da MK |
452 | .B SETALL |
453 | or | |
454 | .B SETVAL | |
455 | and the value to which | |
456 | .B semval | |
70d0e5ef MK |
457 | is to be set (for some semaphore of the set) is less than 0 |
458 | or greater than the implementation limit | |
fea681da | 459 | .BR SEMVMX . |
a1d5f77c MK |
460 | .SH "CONFORMING TO" |
461 | SVr4, POSIX.1-2001. | |
462 | .\" SVr4 documents more error conditions EINVAL and EOVERFLOW. | |
fea681da MK |
463 | .SH NOTES |
464 | The | |
465 | .BR IPC_INFO , | |
466 | .BR SEM_STAT | |
467 | and | |
468 | .B SEM_INFO | |
24ed820a | 469 | operations are used by the |
fea681da MK |
470 | .BR ipcs (8) |
471 | program to provide information on allocated resources. | |
70d0e5ef | 472 | In the future these may modified or moved to a /proc file system |
fea681da MK |
473 | interface. |
474 | .LP | |
475 | Various fields in a \fIstruct semid_ds\fP were shorts under Linux 2.2 | |
677f4766 MK |
476 | and have become longs under Linux 2.4. |
477 | To take advantage of this, | |
fea681da | 478 | a recompilation under glibc-2.1.91 or later should suffice. |
682edefb MK |
479 | (The kernel distinguishes old and new calls by an |
480 | .BR IPC_64 | |
481 | flag in | |
fea681da MK |
482 | .IR cmd .) |
483 | .PP | |
70d0e5ef MK |
484 | In some earlier versions of glibc, the |
485 | .I semun | |
c84371c6 | 486 | union was defined in \fI<sys/sem.h>\fP, but POSIX.1-2001 requires |
70d0e5ef MK |
487 | that the caller define this union. |
488 | On versions of glibc where this union is \fInot\fP defined, | |
489 | the macro | |
490 | .B _SEM_SEMUN_UNDEFINED | |
c84371c6 | 491 | is defined in \fI<sys/sem.h>\fP. |
70d0e5ef | 492 | .PP |
fea681da | 493 | The following system limit on semaphore sets affects a |
540036b2 | 494 | .BR semctl () |
fea681da MK |
495 | call: |
496 | .TP 11 | |
497 | .B SEMVMX | |
498 | Maximum value for | |
499 | .BR semval : | |
500 | implementation dependent (32767). | |
501 | .LP | |
502 | For greater portability it is best to always call | |
540036b2 | 503 | .BR semctl () |
fea681da MK |
504 | with four arguments. |
505 | .LP | |
70d0e5ef | 506 | Under Linux, |
540036b2 | 507 | .BR semctl () |
fea681da MK |
508 | is not a system call, but is implemented via the system call |
509 | .BR ipc (2). | |
fea681da MK |
510 | .SH "SEE ALSO" |
511 | .BR ipc (2), | |
512 | .BR semget (2), | |
513 | .BR semop (2), | |
f675ea37 | 514 | .BR capabilities (7), |
2c5e151c MK |
515 | .BR sem_overview (7), |
516 | .BR svipc (7) |