]>
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 | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" Modified Tue Oct 22 17:53:56 1996 by Eric S. Raymond <esr@thyrsus.com> | |
27 | .\" Modified Fri Jun 19 10:59:15 1998 by Andries Brouwer <aeb@cwi.nl> | |
28 | .\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer <aeb@cwi.nl> | |
c11b1abf | 29 | .\" Modified 20 Dec 2001, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 30 | .\" Modified 21 Dec 2001, aeb |
c11b1abf | 31 | .\" Modified 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 32 | .\" Added notes on CAP_IPC_OWNER requirement |
c11b1abf | 33 | .\" Modified 17 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 34 | .\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID |
c11b1abf | 35 | .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
70d0e5ef MK |
36 | .\" Language and formatting clean-ups |
37 | .\" Rewrote semun text | |
38 | .\" Added semid_ds and ipc_perm structure definitions | |
24ed820a | 39 | .\" 2005-08-02, mtk: Added IPC_INFO, SEM_INFO, SEM_STAT descriptions. |
d2ff4f86 | 40 | .\" 2018-03-20, dbueso: Added SEM_STAT_ANY description. |
fea681da | 41 | .\" |
e8426ca2 | 42 | .TH SEMCTL 2 2020-04-11 "Linux" "Linux Programmer's Manual" |
fea681da | 43 | .SH NAME |
47f065d6 | 44 | semctl \- System V semaphore control operations |
fea681da MK |
45 | .SH SYNOPSIS |
46 | .nf | |
47 | .B #include <sys/types.h> | |
48 | .B #include <sys/ipc.h> | |
49 | .B #include <sys/sem.h> | |
68e4db0a | 50 | .PP |
fea681da MK |
51 | .BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);" |
52 | .fi | |
53 | .SH DESCRIPTION | |
540036b2 | 54 | .BR semctl () |
fea681da MK |
55 | performs the control operation specified by |
56 | .I cmd | |
efbfd7ec | 57 | on the System\ V semaphore set identified by |
fea681da MK |
58 | .IR semid , |
59 | or on the | |
60 | .IR semnum -th | |
61 | semaphore of that set. | |
70d0e5ef | 62 | (The semaphores in a set are numbered starting at 0.) |
fea681da | 63 | .PP |
70d0e5ef MK |
64 | This function has three or four arguments, depending on |
65 | .IR cmd . | |
66 | When there are four, the fourth has the type | |
67 | .IR "union semun" . | |
68 | The \fIcalling program\fP must define this union as follows: | |
efeece04 | 69 | .PP |
70d0e5ef | 70 | .in +4n |
b8302363 | 71 | .EX |
fea681da | 72 | union semun { |
70d0e5ef MK |
73 | int val; /* Value for SETVAL */ |
74 | struct semid_ds *buf; /* Buffer for IPC_STAT, IPC_SET */ | |
75 | unsigned short *array; /* Array for GETALL, SETALL */ | |
c13182ef | 76 | struct seminfo *__buf; /* Buffer for IPC_INFO |
8382f16d | 77 | (Linux-specific) */ |
fea681da | 78 | }; |
b8302363 | 79 | .EE |
e646a1ba | 80 | .in |
fea681da | 81 | .PP |
70d0e5ef MK |
82 | The |
83 | .I semid_ds | |
c84371c6 | 84 | data structure is defined in \fI<sys/sem.h>\fP as follows: |
e646a1ba | 85 | .PP |
70d0e5ef | 86 | .in +4n |
e646a1ba | 87 | .EX |
70d0e5ef | 88 | struct semid_ds { |
45cbde66 | 89 | struct ipc_perm sem_perm; /* Ownership and permissions */ |
70d0e5ef | 90 | time_t sem_otime; /* Last semop time */ |
5fd4345e MK |
91 | time_t sem_ctime; /* Creation time/time of last |
92 | modification via semctl() */ | |
32398a62 | 93 | unsigned long sem_nsems; /* No. of semaphores in set */ |
70d0e5ef | 94 | }; |
b8302363 | 95 | .EE |
e646a1ba | 96 | .in |
1c9b3f5f MK |
97 | The fields of the |
98 | .I semid_ds | |
99 | structure are as follows: | |
100 | .TP 11 | |
101 | .I sem_perm | |
c7d32a9e | 102 | This is an |
1c9b3f5f | 103 | .I ipc_perm |
c7d32a9e | 104 | structure (see below) that specifies the access permissions on the semaphore |
1c9b3f5f MK |
105 | set. |
106 | .TP | |
107 | .I sem_otime | |
108 | Time of last | |
109 | .BR semop (2) | |
110 | system call. | |
111 | .TP | |
112 | .I sem_ctime | |
5fd4345e | 113 | Time of creation of semaphore set or time of last |
6fea5f4f | 114 | .BR semctl () |
5fd4345e MK |
115 | .BR IPCSET , |
116 | .BR SETVAL , | |
117 | or | |
118 | .BR SETVALL | |
119 | operation. | |
1c9b3f5f MK |
120 | .TP |
121 | .I sem_nsems | |
122 | Number of semaphores in the set. | |
123 | Each semaphore of the set is referenced by a nonnegative integer | |
124 | ranging from | |
125 | .B 0 | |
126 | to | |
127 | .IR sem_nsems\-1 . | |
70d0e5ef MK |
128 | .PP |
129 | The | |
130 | .I ipc_perm | |
548be2a6 | 131 | structure is defined as follows |
70d0e5ef MK |
132 | (the highlighted fields are settable using |
133 | .BR IPC_SET ): | |
134 | .PP | |
70d0e5ef | 135 | .in +4n |
b8302363 | 136 | .EX |
70d0e5ef | 137 | struct ipc_perm { |
b546318a | 138 | key_t __key; /* Key supplied to semget(2) */ |
58413227 MK |
139 | uid_t \fBuid\fP; /* Effective UID of owner */ |
140 | gid_t \fBgid\fP; /* Effective GID of owner */ | |
141 | uid_t cuid; /* Effective UID of creator */ | |
142 | gid_t cgid; /* Effective GID of creator */ | |
70d0e5ef | 143 | unsigned short \fBmode\fP; /* Permissions */ |
b546318a | 144 | unsigned short __seq; /* Sequence number */ |
70d0e5ef | 145 | }; |
b8302363 | 146 | .EE |
e646a1ba | 147 | .in |
70d0e5ef | 148 | .PP |
702f1a76 MK |
149 | The least significant 9 bits of the |
150 | .I mode | |
151 | field of the | |
152 | .I ipc_perm | |
153 | structure define the access permissions for the shared memory segment. | |
154 | The permission bits are as follows: | |
155 | .TS | |
156 | l l. | |
157 | 0400 Read by user | |
158 | 0200 Write by user | |
159 | 0040 Read by group | |
160 | 0020 Write by group | |
161 | 0004 Read by others | |
162 | 0002 Write by others | |
163 | .TE | |
164 | .PP | |
165 | In effect, "write" means "alter" for a semaphore set. | |
166 | Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. | |
167 | .PP | |
70d0e5ef | 168 | Valid values for |
fea681da MK |
169 | .I cmd |
170 | are: | |
0019177e | 171 | .TP |
fea681da | 172 | .B IPC_STAT |
70d0e5ef MK |
173 | Copy information from the kernel data structure associated with |
174 | .I semid | |
175 | into the | |
176 | .I semid_ds | |
177 | structure pointed to by | |
178 | .IR arg.buf . | |
fea681da MK |
179 | The argument |
180 | .I semnum | |
181 | is ignored. | |
70d0e5ef | 182 | The calling process must have read permission on the semaphore set. |
fea681da MK |
183 | .TP |
184 | .B IPC_SET | |
185 | Write the values of some members of the | |
70d0e5ef | 186 | .I semid_ds |
fea681da | 187 | structure pointed to by |
70d0e5ef MK |
188 | .I arg.buf |
189 | to the kernel data structure associated with this semaphore set, | |
190 | updating also its | |
191 | .I sem_ctime | |
fea681da | 192 | member. |
c13182ef | 193 | The following members of the structure are updated: |
70d0e5ef MK |
194 | .IR sem_perm.uid , |
195 | .IR sem_perm.gid , | |
196 | and (the least significant 9 bits of) | |
197 | .IR sem_perm.mode . | |
198 | The effective UID of the calling process must match the owner | |
199 | .RI ( sem_perm.uid ) | |
c13182ef | 200 | or creator |
70d0e5ef MK |
201 | .RI ( sem_perm.cuid ) |
202 | of the semaphore set, or the caller must be privileged. | |
fea681da MK |
203 | The argument |
204 | .I semnum | |
205 | is ignored. | |
206 | .TP | |
207 | .B IPC_RMID | |
70d0e5ef MK |
208 | Immediately remove the semaphore set, |
209 | awakening all processes blocked in | |
0bfa087b | 210 | .BR semop (2) |
70d0e5ef MK |
211 | calls on the set (with an error return and |
212 | .I errno | |
fea681da MK |
213 | set to |
214 | .BR EIDRM ). | |
499d62f2 | 215 | The effective user ID of the calling process must |
540036b2 MK |
216 | match the creator or owner of the semaphore set, |
217 | or the caller must be privileged. | |
fea681da MK |
218 | The argument |
219 | .I semnum | |
220 | is ignored. | |
221 | .TP | |
8382f16d | 222 | .BR IPC_INFO " (Linux-specific)" |
5fe2d5b7 | 223 | Return information about system-wide semaphore limits and |
24ed820a MK |
224 | parameters in the structure pointed to by |
225 | .IR arg.__buf . | |
226 | This structure is of type | |
227 | .IR seminfo , | |
228 | defined in | |
229 | .I <sys/sem.h> | |
682edefb | 230 | if the |
0daa9e92 | 231 | .B _GNU_SOURCE |
682edefb | 232 | feature test macro is defined: |
e646a1ba | 233 | .IP |
088a639b | 234 | .in +4n |
e646a1ba | 235 | .EX |
24ed820a | 236 | struct seminfo { |
ffc19357 MK |
237 | int semmap; /* Number of entries in semaphore |
238 | map; unused within kernel */ | |
239 | int semmni; /* Maximum number of semaphore sets */ | |
240 | int semmns; /* Maximum number of semaphores in all | |
24ed820a | 241 | semaphore sets */ |
ffc19357 MK |
242 | int semmnu; /* System-wide maximum number of undo |
243 | structures; unused within kernel */ | |
244 | int semmsl; /* Maximum number of semaphores in a | |
245 | set */ | |
246 | int semopm; /* Maximum number of operations for | |
247 | semop(2) */ | |
248 | int semume; /* Maximum number of undo entries per | |
249 | process; unused within kernel */ | |
250 | int semusz; /* Size of struct sem_undo */ | |
24ed820a | 251 | int semvmx; /* Maximum semaphore value */ |
c13182ef | 252 | int semaem; /* Max. value that can be recorded for |
24ed820a MK |
253 | semaphore adjustment (SEM_UNDO) */ |
254 | }; | |
e646a1ba | 255 | .EE |
088a639b | 256 | .in |
e646a1ba | 257 | .IP |
c13182ef | 258 | The |
24ed820a MK |
259 | .IR semmsl , |
260 | .IR semmns , | |
261 | .IR semopm , | |
262 | and | |
263 | .I semmni | |
264 | settings can be changed via | |
265 | .IR /proc/sys/kernel/sem ; | |
266 | see | |
c13182ef | 267 | .BR proc (5) |
24ed820a MK |
268 | for details. |
269 | .TP | |
8382f16d | 270 | .BR SEM_INFO " (Linux-specific)" |
5fe2d5b7 | 271 | Return a |
24ed820a MK |
272 | .I seminfo |
273 | structure containing the same information as for | |
274 | .BR IPC_INFO , | |
c13182ef | 275 | except that the following fields are returned with information |
24ed820a MK |
276 | about system resources consumed by semaphores: the |
277 | .I semusz | |
c13182ef | 278 | field returns the number of semaphore sets that currently exist |
24ed820a MK |
279 | on the system; and the |
280 | .I semaem | |
c13182ef | 281 | field returns the total number of semaphores in all semaphore sets |
24ed820a MK |
282 | on the system. |
283 | .TP | |
8382f16d | 284 | .BR SEM_STAT " (Linux-specific)" |
5fe2d5b7 | 285 | Return a |
c13182ef | 286 | .I semid_ds |
24ed820a MK |
287 | structure as for |
288 | .BR IPC_STAT . | |
289 | However, the | |
290 | .I semid | |
291 | argument is not a semaphore identifier, but instead an index into | |
292 | the kernel's internal array that maintains information about | |
293 | all semaphore sets on the system. | |
294 | .TP | |
f7246c6d | 295 | .BR SEM_STAT_ANY " (Linux-specific, since Linux 4.17)" |
d2ff4f86 DB |
296 | Return a |
297 | .I seminfo | |
298 | structure containing the same information as for | |
299 | .BR SEM_STAT . | |
c020b5a2 | 300 | However, |
d2ff4f86 DB |
301 | .I sem_perm.mode |
302 | is not checked for read access for | |
c020b5a2 MK |
303 | .IR semid |
304 | meaning that any user can employ this operation (just as any user may read | |
305 | .IR /proc/sysvipc/sem | |
306 | to obtain the same information). | |
14cbb25e | 307 | .TP |
fea681da MK |
308 | .B GETALL |
309 | Return | |
310 | .B semval | |
70d0e5ef | 311 | (i.e., the current value) |
fea681da | 312 | for all semaphores of the set into |
d6c57ce6 | 313 | .IR arg.array . |
fea681da MK |
314 | The argument |
315 | .I semnum | |
316 | is ignored. | |
70d0e5ef | 317 | The calling process must have read permission on the semaphore set. |
fea681da MK |
318 | .TP |
319 | .B GETNCNT | |
dd7f869f | 320 | Return the |
fea681da | 321 | .B semncnt |
dd7f869f | 322 | value for the |
fea681da MK |
323 | .IR semnum \-th |
324 | semaphore of the set | |
dd7f869f | 325 | (i.e., the number of processes waiting for the semaphore's value to increase). |
70d0e5ef | 326 | The calling process must have read permission on the semaphore set. |
fea681da MK |
327 | .TP |
328 | .B GETPID | |
dd7f869f | 329 | Return the |
fea681da | 330 | .B sempid |
dd7f869f | 331 | value for the |
fea681da | 332 | .IR semnum \-th |
84466c16 MK |
333 | semaphore of the set. |
334 | This is the PID of the process that last performed an operation on | |
335 | that semaphore (but see NOTES). | |
70d0e5ef | 336 | The calling process must have read permission on the semaphore set. |
fea681da MK |
337 | .TP |
338 | .B GETVAL | |
dd7f869f | 339 | Return |
fea681da | 340 | .B semval |
dd7f869f | 341 | (i.e., the semaphore value) for the |
fea681da MK |
342 | .IR semnum \-th |
343 | semaphore of the set. | |
70d0e5ef | 344 | The calling process must have read permission on the semaphore set. |
fea681da MK |
345 | .TP |
346 | .B GETZCNT | |
dd7f869f | 347 | Return the |
fea681da | 348 | .B semzcnt |
dd7f869f | 349 | value for the |
fea681da MK |
350 | .IR semnum \-th |
351 | semaphore of the set | |
dd7f869f | 352 | (i.e., the number of processes waiting for the semaphore value to become 0). |
70d0e5ef | 353 | The calling process must have read permission on the semaphore set. |
fea681da MK |
354 | .TP |
355 | .B SETALL | |
dd7f869f | 356 | Set the |
fea681da | 357 | .B semval |
dd7f869f | 358 | values for all semaphores of the set using |
d6c57ce6 | 359 | .IR arg.array , |
fea681da | 360 | updating also the |
70d0e5ef | 361 | .I sem_ctime |
fea681da | 362 | member of the |
70d0e5ef MK |
363 | .I semid_ds |
364 | structure associated with the set. | |
365 | Undo entries (see | |
366 | .BR semop (2)) | |
367 | are cleared for altered semaphores in all processes. | |
368 | If the changes to semaphore values would permit blocked | |
0bfa087b | 369 | .BR semop (2) |
70d0e5ef | 370 | calls in other processes to proceed, then those processes are woken up. |
fea681da MK |
371 | The argument |
372 | .I semnum | |
373 | is ignored. | |
70d0e5ef MK |
374 | The calling process must have alter (write) permission on |
375 | the semaphore set. | |
fea681da MK |
376 | .TP |
377 | .B SETVAL | |
765a67c3 | 378 | Set the semaphore value |
dd7f869f | 379 | .BR ( semval ) |
fea681da | 380 | to |
0daa9e92 | 381 | .I arg.val |
fea681da MK |
382 | for the |
383 | .IR semnum \-th | |
384 | semaphore of the set, updating also the | |
70d0e5ef | 385 | .I sem_ctime |
fea681da | 386 | member of the |
70d0e5ef MK |
387 | .I semid_ds |
388 | structure associated with the set. | |
fea681da | 389 | Undo entries are cleared for altered semaphores in all processes. |
70d0e5ef | 390 | If the changes to semaphore values would permit blocked |
0bfa087b | 391 | .BR semop (2) |
70d0e5ef MK |
392 | calls in other processes to proceed, then those processes are woken up. |
393 | The calling process must have alter permission on the semaphore set. | |
47297adb | 394 | .SH RETURN VALUE |
27ab91ca | 395 | On failure, |
540036b2 | 396 | .BR semctl () |
70d0e5ef | 397 | returns \-1 |
fea681da | 398 | with |
70d0e5ef | 399 | .I errno |
fea681da | 400 | indicating the error. |
efeece04 | 401 | .PP |
27ab91ca | 402 | Otherwise, the system call returns a nonnegative value depending on |
fea681da MK |
403 | .I cmd |
404 | as follows: | |
0019177e | 405 | .TP |
fea681da MK |
406 | .B GETNCNT |
407 | the value of | |
408 | .BR semncnt . | |
409 | .TP | |
410 | .B GETPID | |
411 | the value of | |
412 | .BR sempid . | |
413 | .TP | |
414 | .B GETVAL | |
415 | the value of | |
416 | .BR semval . | |
417 | .TP | |
418 | .B GETZCNT | |
419 | the value of | |
420 | .BR semzcnt . | |
24ed820a MK |
421 | .TP |
422 | .B IPC_INFO | |
423 | the index of the highest used entry in the | |
424 | kernel's internal array recording information about all | |
425 | semaphore sets. | |
426 | (This information can be used with repeated | |
14cbb25e MK |
427 | .B SEM_STAT |
428 | or | |
429 | .B SEM_STAT_ANY | |
24ed820a MK |
430 | operations to obtain information about all semaphore sets on the system.) |
431 | .TP | |
432 | .B SEM_INFO | |
c5c3137d | 433 | as for |
24ed820a MK |
434 | .BR IPC_INFO . |
435 | .TP | |
436 | .B SEM_STAT | |
437 | the identifier of the semaphore set whose index was given in | |
438 | .IR semid . | |
d2ff4f86 DB |
439 | .TP |
440 | .B SEM_STAT_ANY | |
441 | as for | |
442 | .BR SEM_STAT . | |
dd3568a1 | 443 | .PP |
fea681da MK |
444 | All other |
445 | .I cmd | |
446 | values return 0 on success. | |
447 | .SH ERRORS | |
448 | On failure, | |
70d0e5ef | 449 | .I errno |
fea681da | 450 | will be set to one of the following: |
89b3c6b8 | 451 | .TP |
fea681da MK |
452 | .B EACCES |
453 | The argument | |
454 | .I cmd | |
455 | has one of the values | |
456 | .BR GETALL , | |
457 | .BR GETPID , | |
458 | .BR GETVAL , | |
459 | .BR GETNCNT , | |
460 | .BR GETZCNT , | |
461 | .BR IPC_STAT , | |
462 | .BR SEM_STAT , | |
d2ff4f86 | 463 | .BR SEM_STAT_ANY , |
fea681da MK |
464 | .BR SETALL , |
465 | or | |
466 | .B SETVAL | |
467 | and the calling process does not have the required | |
468 | permissions on the semaphore set and does not have the | |
469 | .B CAP_IPC_OWNER | |
3294109d | 470 | capability in the user namespace that governs its IPC namespace. |
fea681da MK |
471 | .TP |
472 | .B EFAULT | |
473 | The address pointed to by | |
0daa9e92 | 474 | .I arg.buf |
fea681da | 475 | or |
0daa9e92 | 476 | .I arg.array |
fea681da MK |
477 | isn't accessible. |
478 | .TP | |
479 | .B EIDRM | |
480 | The semaphore set was removed. | |
481 | .TP | |
482 | .B EINVAL | |
483 | Invalid value for | |
484 | .I cmd | |
485 | or | |
486 | .IR semid . | |
24ed820a MK |
487 | Or: for a |
488 | .B SEM_STAT | |
c13182ef | 489 | operation, the index value specified in |
24ed820a MK |
490 | .I semid |
491 | referred to an array slot that is currently unused. | |
fea681da MK |
492 | .TP |
493 | .B EPERM | |
494 | The argument | |
495 | .I cmd | |
70d0e5ef | 496 | has the value |
fea681da MK |
497 | .B IPC_SET |
498 | or | |
499 | .B IPC_RMID | |
70d0e5ef | 500 | but the effective user ID of the calling process is not the creator |
fea681da MK |
501 | (as found in |
502 | .IR sem_perm.cuid ) | |
503 | or the owner | |
504 | (as found in | |
505 | .IR sem_perm.uid ) | |
506 | of the semaphore set, | |
507 | and the process does not have the | |
508 | .B CAP_SYS_ADMIN | |
509 | capability. | |
510 | .TP | |
511 | .B ERANGE | |
512 | The argument | |
513 | .I cmd | |
70d0e5ef | 514 | has the value |
fea681da MK |
515 | .B SETALL |
516 | or | |
517 | .B SETVAL | |
518 | and the value to which | |
519 | .B semval | |
70d0e5ef MK |
520 | is to be set (for some semaphore of the set) is less than 0 |
521 | or greater than the implementation limit | |
fea681da | 522 | .BR SEMVMX . |
47297adb | 523 | .SH CONFORMING TO |
175b0eec | 524 | POSIX.1-2001, POSIX.1-2008, SVr4. |
a1d5f77c | 525 | .\" SVr4 documents more error conditions EINVAL and EOVERFLOW. |
efeece04 | 526 | .PP |
26356091 MK |
527 | POSIX.1 specifies the |
528 | .\" POSIX.1-2001, POSIX.1-2008 | |
32398a62 MK |
529 | .I sem_nsems |
530 | field of the | |
531 | .I semid_ds | |
532 | structure as having the type | |
533 | .IR "unsigned\ short" , | |
534 | and the field is so defined on most other systems. | |
535 | It was also so defined on Linux 2.2 and earlier, | |
536 | but, since Linux 2.4, the field has the type | |
537 | .IR "unsigned\ long" . | |
fea681da | 538 | .SH NOTES |
f6652463 MK |
539 | The inclusion of |
540 | .I <sys/types.h> | |
541 | and | |
542 | .I <sys/ipc.h> | |
543 | isn't required on Linux or by any version of POSIX. | |
544 | However, | |
545 | some old implementations required the inclusion of these header files, | |
546 | and the SVID also documented their inclusion. | |
547 | Applications intended to be portable to such old systems may need | |
548 | to include these header files. | |
549 | .\" Like Linux, the FreeBSD man pages still document | |
550 | .\" the inclusion of these header files. | |
efeece04 | 551 | .PP |
fea681da MK |
552 | The |
553 | .BR IPC_INFO , | |
0daa9e92 | 554 | .B SEM_STAT |
fea681da MK |
555 | and |
556 | .B SEM_INFO | |
24ed820a | 557 | operations are used by the |
81a8f8e7 | 558 | .BR ipcs (1) |
fea681da | 559 | program to provide information on allocated resources. |
282c1a35 MK |
560 | In the future these may modified or moved to a |
561 | .I /proc | |
562 | filesystem interface. | |
dd3568a1 | 563 | .PP |
e3e25559 MK |
564 | Various fields in a \fIstruct semid_ds\fP were typed as |
565 | .I short | |
566 | under Linux 2.2 | |
567 | and have become | |
568 | .I long | |
569 | under Linux 2.4. | |
677f4766 | 570 | To take advantage of this, |
fea681da | 571 | a recompilation under glibc-2.1.91 or later should suffice. |
682edefb | 572 | (The kernel distinguishes old and new calls by an |
0daa9e92 | 573 | .B IPC_64 |
682edefb | 574 | flag in |
fea681da MK |
575 | .IR cmd .) |
576 | .PP | |
70d0e5ef MK |
577 | In some earlier versions of glibc, the |
578 | .I semun | |
26356091 MK |
579 | union was defined in \fI<sys/sem.h>\fP, but POSIX.1 requires |
580 | .\" POSIX.1-2001, POSIX.1-2008 | |
70d0e5ef MK |
581 | that the caller define this union. |
582 | On versions of glibc where this union is \fInot\fP defined, | |
583 | the macro | |
584 | .B _SEM_SEMUN_UNDEFINED | |
c84371c6 | 585 | is defined in \fI<sys/sem.h>\fP. |
70d0e5ef | 586 | .PP |
fea681da | 587 | The following system limit on semaphore sets affects a |
540036b2 | 588 | .BR semctl () |
fea681da | 589 | call: |
89b3c6b8 | 590 | .TP |
fea681da MK |
591 | .B SEMVMX |
592 | Maximum value for | |
593 | .BR semval : | |
594 | implementation dependent (32767). | |
dd3568a1 | 595 | .PP |
27ab91ca | 596 | For greater portability, it is best to always call |
540036b2 | 597 | .BR semctl () |
fea681da | 598 | with four arguments. |
84466c16 MK |
599 | .\" |
600 | .SS The sempid value | |
601 | POSIX.1 defines | |
602 | .I sempid | |
603 | as the "process ID of [the] last operation" on a semaphore, | |
604 | and explicitly notes that this value is set by a successful | |
605 | .BR semop (2) | |
606 | call, with the implication that no other interface affects the | |
607 | .I sempid | |
608 | value. | |
efeece04 | 609 | .PP |
84466c16 MK |
610 | While some implementations conform to the behavior specified in POSIX.1, |
611 | others do not. | |
612 | (The fault here probably lies with POSIX.1 inasmuch as it likely failed | |
613 | to capture the full range of existing implementation behaviors.) | |
614 | Various other implementations | |
615 | .\" At least OpenSolaris (and, one supposes, older Solaris) and Darwin | |
616 | also update | |
617 | .I sempid | |
618 | for the other operations that update the value of a semaphore: the | |
619 | .B SETVAL | |
620 | and | |
621 | .B SETALL | |
622 | operations, as well as the semaphore adjustments performed | |
623 | on process termination as a consequence of the use of the | |
624 | .B SEM_UNDO | |
625 | flag (see | |
626 | .BR semop (2)). | |
efeece04 | 627 | .PP |
84466c16 MK |
628 | Linux also updates |
629 | .I sempid | |
630 | for | |
631 | .BR SETVAL | |
632 | operations and semaphore adjustments. | |
ce160b21 MK |
633 | However, somewhat inconsistently, up to and including Linux 4.5, |
634 | the kernel did not update | |
84466c16 MK |
635 | .I sempid |
636 | for | |
637 | .BR SETALL | |
638 | operations. | |
efcc21c9 MK |
639 | This was rectified |
640 | .\" commit a5f4db877177d2a3d7ae62a7bac3a5a27e083d7f | |
641 | in Linux 4.6. | |
5d7a1843 MK |
642 | .SH EXAMPLE |
643 | See | |
644 | .BR shmop (2). | |
47297adb | 645 | .SH SEE ALSO |
fea681da MK |
646 | .BR ipc (2), |
647 | .BR semget (2), | |
648 | .BR semop (2), | |
f675ea37 | 649 | .BR capabilities (7), |
2c5e151c | 650 | .BR sem_overview (7), |
343cdc5a | 651 | .BR sysvipc (7) |