]>
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 | |
81 | data structure is defined in <sys/sem.h> as follows: | |
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 | |
96 | structure is defined in <sys/ipc.h> as follows | |
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> | |
176 | if the _GNU_SOURCE feature test macro is defined: | |
177 | .nf | |
178 | .in +2n | |
179 | ||
180 | struct seminfo { | |
c13182ef | 181 | int semmap; /* # of entries in semaphore map; |
24ed820a MK |
182 | unused */ |
183 | int semmni; /* Max. # of semaphore sets */ | |
c13182ef | 184 | int semmns; /* Max. # of semaphores in all |
24ed820a | 185 | semaphore sets */ |
c13182ef | 186 | int semmnu; /* System-wide max. # of undo |
24ed820a MK |
187 | structures; unused */ |
188 | int semmsl; /* Max. # of semaphores in a set */ | |
0bfa087b | 189 | int semopm; /* Max. # of operations for semop(2) */ |
c13182ef | 190 | int semume; /* Max. # of undo entries per |
24ed820a MK |
191 | process; unused */ |
192 | int semusz; /* size of struct sem_undo */ | |
193 | int semvmx; /* Maximum semaphore value */ | |
c13182ef | 194 | int semaem; /* Max. value that can be recorded for |
24ed820a MK |
195 | semaphore adjustment (SEM_UNDO) */ |
196 | }; | |
197 | ||
198 | .in -2n | |
199 | .fi | |
c13182ef | 200 | The |
24ed820a MK |
201 | .IR semmsl , |
202 | .IR semmns , | |
203 | .IR semopm , | |
204 | and | |
205 | .I semmni | |
206 | settings can be changed via | |
207 | .IR /proc/sys/kernel/sem ; | |
208 | see | |
c13182ef | 209 | .BR proc (5) |
24ed820a MK |
210 | for details. |
211 | .TP | |
212 | .BR SEM_INFO " (Linux specific)" | |
213 | Returns a | |
214 | .I seminfo | |
215 | structure containing the same information as for | |
216 | .BR IPC_INFO , | |
c13182ef | 217 | except that the following fields are returned with information |
24ed820a MK |
218 | about system resources consumed by semaphores: the |
219 | .I semusz | |
c13182ef | 220 | field returns the number of semaphore sets that currently exist |
24ed820a MK |
221 | on the system; and the |
222 | .I semaem | |
c13182ef | 223 | field returns the total number of semaphores in all semaphore sets |
24ed820a MK |
224 | on the system. |
225 | .TP | |
226 | .BR SEM_STAT " (Linux specific)" | |
c13182ef MK |
227 | Returns a |
228 | .I semid_ds | |
24ed820a MK |
229 | structure as for |
230 | .BR IPC_STAT . | |
231 | However, the | |
232 | .I semid | |
233 | argument is not a semaphore identifier, but instead an index into | |
234 | the kernel's internal array that maintains information about | |
235 | all semaphore sets on the system. | |
236 | .TP | |
fea681da MK |
237 | .B GETALL |
238 | Return | |
239 | .B semval | |
70d0e5ef | 240 | (i.e., the current value) |
fea681da | 241 | for all semaphores of the set into |
70d0e5ef | 242 | .IB arg.array . |
fea681da MK |
243 | The argument |
244 | .I semnum | |
245 | is ignored. | |
70d0e5ef | 246 | The calling process must have read permission on the semaphore set. |
fea681da MK |
247 | .TP |
248 | .B GETNCNT | |
249 | The system call returns the value of | |
250 | .B semncnt | |
70d0e5ef MK |
251 | (i.e., the number of processes waiting for the value of |
252 | this semaphore to increase) for the | |
fea681da MK |
253 | .IR semnum \-th |
254 | semaphore of the set | |
75b94dc3 | 255 | (i.e., the number of processes waiting for an increase of |
fea681da MK |
256 | .B semval |
257 | for the | |
258 | .IR semnum \-th | |
259 | semaphore of the set). | |
70d0e5ef | 260 | The calling process must have read permission on the semaphore set. |
fea681da MK |
261 | .TP |
262 | .B GETPID | |
263 | The system call returns the value of | |
264 | .B sempid | |
265 | for the | |
266 | .IR semnum \-th | |
267 | semaphore of the set | |
70d0e5ef | 268 | (i.e. the PID of the process that executed the last |
0bfa087b | 269 | .BR semop (2) |
fea681da MK |
270 | call for the |
271 | .IR semnum \-th | |
272 | semaphore of the set). | |
70d0e5ef | 273 | The calling process must have read permission on the semaphore set. |
fea681da MK |
274 | .TP |
275 | .B GETVAL | |
276 | The system call returns the value of | |
277 | .B semval | |
278 | for the | |
279 | .IR semnum \-th | |
280 | semaphore of the set. | |
70d0e5ef | 281 | The calling process must have read permission on the semaphore set. |
fea681da MK |
282 | .TP |
283 | .B GETZCNT | |
284 | The system call returns the value of | |
285 | .B semzcnt | |
70d0e5ef MK |
286 | (i.e., the number of processes waiting for the value of |
287 | this semaphore to become zero) for the | |
fea681da MK |
288 | .IR semnum \-th |
289 | semaphore of the set | |
290 | (i.e. the number of processes waiting for | |
291 | .B semval | |
292 | of the | |
293 | .IR semnum \-th | |
294 | semaphore of the set to become 0). | |
70d0e5ef | 295 | The calling process must have read permission on the semaphore set. |
fea681da MK |
296 | .TP |
297 | .B SETALL | |
298 | Set | |
299 | .B semval | |
300 | for all semaphores of the set using | |
70d0e5ef | 301 | .IB arg.array , |
fea681da | 302 | updating also the |
70d0e5ef | 303 | .I sem_ctime |
fea681da | 304 | member of the |
70d0e5ef MK |
305 | .I semid_ds |
306 | structure associated with the set. | |
307 | Undo entries (see | |
308 | .BR semop (2)) | |
309 | are cleared for altered semaphores in all processes. | |
310 | If the changes to semaphore values would permit blocked | |
0bfa087b | 311 | .BR semop (2) |
70d0e5ef | 312 | calls in other processes to proceed, then those processes are woken up. |
fea681da MK |
313 | The argument |
314 | .I semnum | |
315 | is ignored. | |
70d0e5ef MK |
316 | The calling process must have alter (write) permission on |
317 | the semaphore set. | |
fea681da MK |
318 | .TP |
319 | .B SETVAL | |
320 | Set the value of | |
321 | .B semval | |
322 | to | |
70d0e5ef | 323 | .IB arg.val |
fea681da MK |
324 | for the |
325 | .IR semnum \-th | |
326 | semaphore of the set, updating also the | |
70d0e5ef | 327 | .I sem_ctime |
fea681da | 328 | member of the |
70d0e5ef MK |
329 | .I semid_ds |
330 | structure associated with the set. | |
fea681da | 331 | Undo entries are cleared for altered semaphores in all processes. |
70d0e5ef | 332 | If the changes to semaphore values would permit blocked |
0bfa087b | 333 | .BR semop (2) |
70d0e5ef MK |
334 | calls in other processes to proceed, then those processes are woken up. |
335 | The calling process must have alter permission on the semaphore set. | |
fea681da MK |
336 | .SH "RETURN VALUE" |
337 | On failure | |
540036b2 | 338 | .BR semctl () |
70d0e5ef | 339 | returns \-1 |
fea681da | 340 | with |
70d0e5ef | 341 | .I errno |
fea681da | 342 | indicating the error. |
24ed820a | 343 | |
18be658d | 344 | Otherwise the system call returns a non-negative value depending on |
fea681da MK |
345 | .I cmd |
346 | as follows: | |
347 | .TP 11 | |
348 | .B GETNCNT | |
349 | the value of | |
350 | .BR semncnt . | |
351 | .TP | |
352 | .B GETPID | |
353 | the value of | |
354 | .BR sempid . | |
355 | .TP | |
356 | .B GETVAL | |
357 | the value of | |
358 | .BR semval . | |
359 | .TP | |
360 | .B GETZCNT | |
361 | the value of | |
362 | .BR semzcnt . | |
24ed820a MK |
363 | .TP |
364 | .B IPC_INFO | |
365 | the index of the highest used entry in the | |
366 | kernel's internal array recording information about all | |
367 | semaphore sets. | |
368 | (This information can be used with repeated | |
c13182ef | 369 | .B SEM_STAT |
24ed820a MK |
370 | operations to obtain information about all semaphore sets on the system.) |
371 | .TP | |
372 | .B SEM_INFO | |
c13182ef | 373 | As for |
24ed820a MK |
374 | .BR IPC_INFO . |
375 | .TP | |
376 | .B SEM_STAT | |
377 | the identifier of the semaphore set whose index was given in | |
378 | .IR semid . | |
fea681da MK |
379 | .LP |
380 | All other | |
381 | .I cmd | |
382 | values return 0 on success. | |
383 | .SH ERRORS | |
384 | On failure, | |
70d0e5ef | 385 | .I errno |
fea681da MK |
386 | will be set to one of the following: |
387 | .TP 11 | |
388 | .B EACCES | |
389 | The argument | |
390 | .I cmd | |
391 | has one of the values | |
392 | .BR GETALL , | |
393 | .BR GETPID , | |
394 | .BR GETVAL , | |
395 | .BR GETNCNT , | |
396 | .BR GETZCNT , | |
397 | .BR IPC_STAT , | |
398 | .BR SEM_STAT , | |
399 | .BR SETALL , | |
400 | or | |
401 | .B SETVAL | |
402 | and the calling process does not have the required | |
403 | permissions on the semaphore set and does not have the | |
404 | .B CAP_IPC_OWNER | |
405 | capability. | |
406 | .TP | |
407 | .B EFAULT | |
408 | The address pointed to by | |
70d0e5ef | 409 | .IB arg.buf |
fea681da | 410 | or |
70d0e5ef | 411 | .IB arg.array |
fea681da MK |
412 | isn't accessible. |
413 | .TP | |
414 | .B EIDRM | |
415 | The semaphore set was removed. | |
416 | .TP | |
417 | .B EINVAL | |
418 | Invalid value for | |
419 | .I cmd | |
420 | or | |
421 | .IR semid . | |
24ed820a MK |
422 | Or: for a |
423 | .B SEM_STAT | |
c13182ef | 424 | operation, the index value specified in |
24ed820a MK |
425 | .I semid |
426 | referred to an array slot that is currently unused. | |
fea681da MK |
427 | .TP |
428 | .B EPERM | |
429 | The argument | |
430 | .I cmd | |
70d0e5ef | 431 | has the value |
fea681da MK |
432 | .B IPC_SET |
433 | or | |
434 | .B IPC_RMID | |
70d0e5ef | 435 | but the effective user ID of the calling process is not the creator |
fea681da MK |
436 | (as found in |
437 | .IR sem_perm.cuid ) | |
438 | or the owner | |
439 | (as found in | |
440 | .IR sem_perm.uid ) | |
441 | of the semaphore set, | |
442 | and the process does not have the | |
443 | .B CAP_SYS_ADMIN | |
444 | capability. | |
445 | .TP | |
446 | .B ERANGE | |
447 | The argument | |
448 | .I cmd | |
70d0e5ef | 449 | has the value |
fea681da MK |
450 | .B SETALL |
451 | or | |
452 | .B SETVAL | |
453 | and the value to which | |
454 | .B semval | |
70d0e5ef MK |
455 | is to be set (for some semaphore of the set) is less than 0 |
456 | or greater than the implementation limit | |
fea681da | 457 | .BR SEMVMX . |
a1d5f77c MK |
458 | .SH "CONFORMING TO" |
459 | SVr4, POSIX.1-2001. | |
460 | .\" SVr4 documents more error conditions EINVAL and EOVERFLOW. | |
fea681da MK |
461 | .SH NOTES |
462 | The | |
463 | .BR IPC_INFO , | |
464 | .BR SEM_STAT | |
465 | and | |
466 | .B SEM_INFO | |
24ed820a | 467 | operations are used by the |
fea681da MK |
468 | .BR ipcs (8) |
469 | program to provide information on allocated resources. | |
70d0e5ef | 470 | In the future these may modified or moved to a /proc file system |
fea681da MK |
471 | interface. |
472 | .LP | |
473 | Various fields in a \fIstruct semid_ds\fP were shorts under Linux 2.2 | |
677f4766 MK |
474 | and have become longs under Linux 2.4. |
475 | To take advantage of this, | |
fea681da | 476 | a recompilation under glibc-2.1.91 or later should suffice. |
70d0e5ef | 477 | (The kernel distinguishes old and new calls by an IPC_64 flag in |
fea681da MK |
478 | .IR cmd .) |
479 | .PP | |
70d0e5ef MK |
480 | In some earlier versions of glibc, the |
481 | .I semun | |
482 | union was defined in <sys/sem.h>, but POSIX.1-2001 requires | |
483 | that the caller define this union. | |
484 | On versions of glibc where this union is \fInot\fP defined, | |
485 | the macro | |
486 | .B _SEM_SEMUN_UNDEFINED | |
487 | is defined in <sys/sem.h>. | |
488 | .PP | |
fea681da | 489 | The following system limit on semaphore sets affects a |
540036b2 | 490 | .BR semctl () |
fea681da MK |
491 | call: |
492 | .TP 11 | |
493 | .B SEMVMX | |
494 | Maximum value for | |
495 | .BR semval : | |
496 | implementation dependent (32767). | |
497 | .LP | |
498 | For greater portability it is best to always call | |
540036b2 | 499 | .BR semctl () |
fea681da MK |
500 | with four arguments. |
501 | .LP | |
70d0e5ef | 502 | Under Linux, |
540036b2 | 503 | .BR semctl () |
fea681da MK |
504 | is not a system call, but is implemented via the system call |
505 | .BR ipc (2). | |
fea681da MK |
506 | .SH "SEE ALSO" |
507 | .BR ipc (2), | |
508 | .BR semget (2), | |
509 | .BR semop (2), | |
f675ea37 | 510 | .BR capabilities (7), |
2c5e151c MK |
511 | .BR sem_overview (7), |
512 | .BR svipc (7) |