Debian Codegraph @

upstream/debian-trixie/man2/semctl.2

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