diff options
Diffstat (limited to 'upstream/debian-bookworm/man2/semctl.2')
| -rw-r--r-- | upstream/debian-bookworm/man2/semctl.2 | 621 |
1 files changed, 621 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man2/semctl.2 b/upstream/debian-bookworm/man2/semctl.2 new file mode 100644 index 00000000..8f616a34 --- /dev/null +++ b/upstream/debian-bookworm/man2/semctl.2 @@ -0,0 +1,621 @@ +'\" t +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Tue Oct 22 17:53:56 1996 by Eric S. Raymond <esr@thyrsus.com> +.\" Modified Fri Jun 19 10:59:15 1998 by Andries Brouwer <aeb@cwi.nl> +.\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer <aeb@cwi.nl> +.\" Modified 20 Dec 2001, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Modified 21 Dec 2001, aeb +.\" Modified 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Added notes on CAP_IPC_OWNER requirement +.\" Modified 17 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID +.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Language and formatting clean-ups +.\" Rewrote semun text +.\" Added semid_ds and ipc_perm structure definitions +.\" 2005-08-02, mtk: Added IPC_INFO, SEM_INFO, SEM_STAT descriptions. +.\" 2018-03-20, dbueso: Added SEM_STAT_ANY description. +.\" +.TH semctl 2 2022-12-15 "Linux man-pages 6.03" +.SH NAME +semctl \- System V semaphore control operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/sem.h> +.PP +.BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);" +.fi +.SH DESCRIPTION +.BR semctl () +performs the control operation specified by +.I cmd +on the System\ V semaphore set identified by +.IR semid , +or on the +.IR semnum -th +semaphore of that set. +(The semaphores in a set are numbered starting at 0.) +.PP +This function has three or four arguments, depending on +.IR cmd . +When there are four, the fourth has the type +.IR "union semun" . +The \fIcalling program\fP must define this union as follows: +.PP +.in +4n +.EX +union semun { + int val; /* Value for SETVAL */ + struct semid_ds *buf; /* Buffer for IPC_STAT, IPC_SET */ + unsigned short *array; /* Array for GETALL, SETALL */ + struct seminfo *__buf; /* Buffer for IPC_INFO + (Linux\-specific) */ +}; +.EE +.in +.PP +The +.I semid_ds +data structure is defined in \fI<sys/sem.h>\fP as follows: +.PP +.in +4n +.EX +struct semid_ds { + struct ipc_perm sem_perm; /* Ownership and permissions */ + time_t sem_otime; /* Last semop time */ + time_t sem_ctime; /* Creation time/time of last + modification via semctl() */ + unsigned long sem_nsems; /* No. of semaphores in set */ +}; +.EE +.in +.PP +The fields of the +.I semid_ds +structure are as follows: +.TP 11 +.I sem_perm +This is an +.I ipc_perm +structure (see below) that specifies the access permissions on the semaphore +set. +.TP +.I sem_otime +Time of last +.BR semop (2) +system call. +.TP +.I sem_ctime +Time of creation of semaphore set or time of last +.BR semctl () +.BR IPCSET , +.BR SETVAL , +or +.B SETALL +operation. +.TP +.I sem_nsems +Number of semaphores in the set. +Each semaphore of the set is referenced by a nonnegative integer +ranging from +.B 0 +to +.IR sem_nsems\-1 . +.PP +The +.I ipc_perm +structure is defined as follows +(the highlighted fields are settable using +.BR IPC_SET ): +.PP +.in +4n +.EX +struct ipc_perm { + key_t __key; /* Key supplied to semget(2) */ + uid_t \fBuid\fP; /* Effective UID of owner */ + gid_t \fBgid\fP; /* Effective GID of owner */ + uid_t cuid; /* Effective UID of creator */ + gid_t cgid; /* Effective GID of creator */ + unsigned short \fBmode\fP; /* Permissions */ + unsigned short __seq; /* Sequence number */ +}; +.EE +.in +.PP +The least significant 9 bits of the +.I mode +field of the +.I ipc_perm +structure define the access permissions for the shared memory segment. +The permission bits are as follows: +.TS +l l. +0400 Read by user +0200 Write by user +0040 Read by group +0020 Write by group +0004 Read by others +0002 Write by others +.TE +.PP +In effect, "write" means "alter" for a semaphore set. +Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. +.PP +Valid values for +.I cmd +are: +.TP +.B IPC_STAT +Copy information from the kernel data structure associated with +.I semid +into the +.I semid_ds +structure pointed to by +.IR arg.buf . +The argument +.I semnum +is ignored. +The calling process must have read permission on the semaphore set. +.TP +.B IPC_SET +Write the values of some members of the +.I semid_ds +structure pointed to by +.I arg.buf +to the kernel data structure associated with this semaphore set, +updating also its +.I sem_ctime +member. +.IP +The following members of the structure are updated: +.IR sem_perm.uid , +.IR sem_perm.gid , +and (the least significant 9 bits of) +.IR sem_perm.mode . +.IP +The effective UID of the calling process must match the owner +.RI ( sem_perm.uid ) +or creator +.RI ( sem_perm.cuid ) +of the semaphore set, or the caller must be privileged. +The argument +.I semnum +is ignored. +.TP +.B IPC_RMID +Immediately remove the semaphore set, +awakening all processes blocked in +.BR semop (2) +calls on the set (with an error return and +.I errno +set to +.BR EIDRM ). +The effective user ID of the calling process must +match the creator or owner of the semaphore set, +or the caller must be privileged. +The argument +.I semnum +is ignored. +.TP +.BR IPC_INFO " (Linux\-specific)" +Return information about system-wide semaphore limits and +parameters in the structure pointed to by +.IR arg.__buf . +This structure is of type +.IR seminfo , +defined in +.I <sys/sem.h> +if the +.B _GNU_SOURCE +feature test macro is defined: +.IP +.in +4n +.EX +struct seminfo { + int semmap; /* Number of entries in semaphore + map; unused within kernel */ + int semmni; /* Maximum number of semaphore sets */ + int semmns; /* Maximum number of semaphores in all + semaphore sets */ + int semmnu; /* System\-wide maximum number of undo + structures; unused within kernel */ + int semmsl; /* Maximum number of semaphores in a + set */ + int semopm; /* Maximum number of operations for + semop(2) */ + int semume; /* Maximum number of undo entries per + process; unused within kernel */ + int semusz; /* Size of struct sem_undo */ + int semvmx; /* Maximum semaphore value */ + int semaem; /* Max. value that can be recorded for + semaphore adjustment (SEM_UNDO) */ +}; +.EE +.in +.IP +The +.IR semmsl , +.IR semmns , +.IR semopm , +and +.I semmni +settings can be changed via +.IR /proc/sys/kernel/sem ; +see +.BR proc (5) +for details. +.TP +.BR SEM_INFO " (Linux-specific)" +Return a +.I seminfo +structure containing the same information as for +.BR IPC_INFO , +except that the following fields are returned with information +about system resources consumed by semaphores: the +.I semusz +field returns the number of semaphore sets that currently exist +on the system; and the +.I semaem +field returns the total number of semaphores in all semaphore sets +on the system. +.TP +.BR SEM_STAT " (Linux-specific)" +Return a +.I semid_ds +structure as for +.BR IPC_STAT . +However, the +.I semid +argument is not a semaphore identifier, but instead an index into +the kernel's internal array that maintains information about +all semaphore sets on the system. +.TP +.BR SEM_STAT_ANY " (Linux-specific, since Linux 4.17)" +Return a +.I semid_ds +structure as for +.BR SEM_STAT . +However, +.I sem_perm.mode +is not checked for read access for +.I semid +meaning that any user can employ this operation (just as any user may read +.I /proc/sysvipc/sem +to obtain the same information). +.TP +.B GETALL +Return +.B semval +(i.e., the current value) +for all semaphores of the set into +.IR arg.array . +The argument +.I semnum +is ignored. +The calling process must have read permission on the semaphore set. +.TP +.B GETNCNT +Return the +.B semncnt +value for the +.IR semnum \-th +semaphore of the set +(i.e., the number of processes waiting for the semaphore's value to increase). +The calling process must have read permission on the semaphore set. +.TP +.B GETPID +Return the +.B sempid +value for the +.IR semnum \-th +semaphore of the set. +This is the PID of the process that last performed an operation on +that semaphore (but see NOTES). +The calling process must have read permission on the semaphore set. +.TP +.B GETVAL +Return +.B semval +(i.e., the semaphore value) for the +.IR semnum \-th +semaphore of the set. +The calling process must have read permission on the semaphore set. +.TP +.B GETZCNT +Return the +.B semzcnt +value for the +.IR semnum \-th +semaphore of the set +(i.e., the number of processes waiting for the semaphore value to become 0). +The calling process must have read permission on the semaphore set. +.TP +.B SETALL +Set the +.B semval +values for all semaphores of the set using +.IR arg.array , +updating also the +.I sem_ctime +member of the +.I semid_ds +structure associated with the set. +Undo entries (see +.BR semop (2)) +are cleared for altered semaphores in all processes. +If the changes to semaphore values would permit blocked +.BR semop (2) +calls in other processes to proceed, then those processes are woken up. +The argument +.I semnum +is ignored. +The calling process must have alter (write) permission on +the semaphore set. +.TP +.B SETVAL +Set the semaphore value +.RB ( semval ) +to +.I arg.val +for the +.IR semnum \-th +semaphore of the set, updating also the +.I sem_ctime +member of the +.I semid_ds +structure associated with the set. +Undo entries are cleared for altered semaphores in all processes. +If the changes to semaphore values would permit blocked +.BR semop (2) +calls in other processes to proceed, then those processes are woken up. +The calling process must have alter permission on the semaphore set. +.SH RETURN VALUE +On success, +.BR semctl () +returns a nonnegative value depending on +.I cmd +as follows: +.TP +.B GETNCNT +the value of +.BR semncnt . +.TP +.B GETPID +the value of +.BR sempid . +.TP +.B GETVAL +the value of +.BR semval . +.TP +.B GETZCNT +the value of +.BR semzcnt . +.TP +.B IPC_INFO +the index of the highest used entry in the +kernel's internal array recording information about all +semaphore sets. +(This information can be used with repeated +.B SEM_STAT +or +.B SEM_STAT_ANY +operations to obtain information about all semaphore sets on the system.) +.TP +.B SEM_INFO +as for +.BR IPC_INFO . +.TP +.B SEM_STAT +the identifier of the semaphore set whose index was given in +.IR semid . +.TP +.B SEM_STAT_ANY +as for +.BR SEM_STAT . +.PP +All other +.I cmd +values return 0 on success. +.PP +On failure, +.BR semctl () +returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EACCES +The argument +.I cmd +has one of the values +.BR GETALL , +.BR GETPID , +.BR GETVAL , +.BR GETNCNT , +.BR GETZCNT , +.BR IPC_STAT , +.BR SEM_STAT , +.BR SEM_STAT_ANY , +.BR SETALL , +or +.B SETVAL +and the calling process does not have the required +permissions on the semaphore set and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EFAULT +The address pointed to by +.I arg.buf +or +.I arg.array +isn't accessible. +.TP +.B EIDRM +The semaphore set was removed. +.TP +.B EINVAL +Invalid value for +.I cmd +or +.IR semid . +Or: for a +.B SEM_STAT +operation, the index value specified in +.I semid +referred to an array slot that is currently unused. +.TP +.B EPERM +The argument +.I cmd +has the value +.B IPC_SET +or +.B IPC_RMID +but the effective user ID of the calling process is not the creator +(as found in +.IR sem_perm.cuid ) +or the owner +(as found in +.IR sem_perm.uid ) +of the semaphore set, +and the process does not have the +.B CAP_SYS_ADMIN +capability. +.TP +.B ERANGE +The argument +.I cmd +has the value +.B SETALL +or +.B SETVAL +and the value to which +.B semval +is to be set (for some semaphore of the set) is less than 0 +or greater than the implementation limit +.BR SEMVMX . +.SH STANDARDS +POSIX.1-2001, POSIX.1-2008, SVr4. +.\" SVr4 documents more error conditions EINVAL and EOVERFLOW. +.PP +POSIX.1 specifies the +.\" POSIX.1-2001, POSIX.1-2008 +.I sem_nsems +field of the +.I semid_ds +structure as having the type +.IR "unsigned\ short" , +and the field is so defined on most other systems. +It was also so defined on Linux 2.2 and earlier, +but, since Linux 2.4, the field has the type +.IR "unsigned\ long" . +.SH NOTES +The +.BR IPC_INFO , +.BR SEM_STAT , +and +.B SEM_INFO +operations are used by the +.BR ipcs (1) +program to provide information on allocated resources. +In the future these may modified or moved to a +.I /proc +filesystem interface. +.PP +Various fields in a \fIstruct semid_ds\fP were typed as +.I short +under Linux 2.2 +and have become +.I long +under Linux 2.4. +To take advantage of this, +a recompilation under glibc-2.1.91 or later should suffice. +(The kernel distinguishes old and new calls by an +.B IPC_64 +flag in +.IR cmd .) +.PP +In some earlier versions of glibc, the +.I semun +union was defined in \fI<sys/sem.h>\fP, but POSIX.1 requires +.\" POSIX.1-2001, POSIX.1-2008 +that the caller define this union. +On versions of glibc where this union is \fInot\fP defined, +the macro +.B _SEM_SEMUN_UNDEFINED +is defined in \fI<sys/sem.h>\fP. +.PP +The following system limit on semaphore sets affects a +.BR semctl () +call: +.TP +.B SEMVMX +Maximum value for +.BR semval : +implementation dependent (32767). +.PP +For greater portability, it is best to always call +.BR semctl () +with four arguments. +.\" +.SS The sempid value +POSIX.1 defines +.I sempid +as the "process ID of [the] last operation" on a semaphore, +and explicitly notes that this value is set by a successful +.BR semop (2) +call, with the implication that no other interface affects the +.I sempid +value. +.PP +While some implementations conform to the behavior specified in POSIX.1, +others do not. +(The fault here probably lies with POSIX.1 inasmuch as it likely failed +to capture the full range of existing implementation behaviors.) +Various other implementations +.\" At least OpenSolaris (and, one supposes, older Solaris) and Darwin +also update +.I sempid +for the other operations that update the value of a semaphore: the +.B SETVAL +and +.B SETALL +operations, as well as the semaphore adjustments performed +on process termination as a consequence of the use of the +.B SEM_UNDO +flag (see +.BR semop (2)). +.PP +Linux also updates +.I sempid +for +.B SETVAL +operations and semaphore adjustments. +However, somewhat inconsistently, up to and including Linux 4.5, +the kernel did not update +.I sempid +for +.B SETALL +operations. +This was rectified +.\" commit a5f4db877177d2a3d7ae62a7bac3a5a27e083d7f +in Linux 4.6. +.SH EXAMPLES +See +.BR shmop (2). +.SH SEE ALSO +.BR ipc (2), +.BR semget (2), +.BR semop (2), +.BR capabilities (7), +.BR sem_overview (7), +.BR sysvipc (7) |