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