Debian Codegraph @

upstream/debian-unstable/man2/semctl.2

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