Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 623 insertions, 0 deletions

diff --git a/man/man2/semctl.2 b/man/man2/semctl.2
new file mode 100644
index 0000000..a5c7fae
--- /dev/null
+++ b/man/man2/semctl.2
@@ -0,0 +1,623 @@
+'\" 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 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+semctl \- System V semaphore control operations
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/sem.h>
+.P
+.BI "int semctl(int " semid ", int " semnum ", int " op ", ...);"
+.fi
+.SH DESCRIPTION
+.BR semctl ()
+performs the control operation specified by
+.I op
+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.)
+.P
+This function has three or four arguments, depending on
+.IR op .
+When there are four, the fourth has the type
+.IR "union semun" .
+The \fIcalling program\fP must define this union as follows:
+.P
+.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
+.P
+The
+.I semid_ds
+data structure is defined in \fI<sys/sem.h>\fP as follows:
+.P
+.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
+.P
+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 .
+.P
+The
+.I ipc_perm
+structure is defined as follows
+(the highlighted fields are settable using
+.BR IPC_SET ):
+.P
+.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
+.P
+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
+.P
+In effect, "write" means "alter" for a semaphore set.
+Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
+.P
+Valid values for
+.I op
+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 op
+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 .
+.P
+All other
+.I op
+values return 0 on success.
+.P
+On failure,
+.BR semctl ()
+returns \-1 and sets
+.I errno
+to indicate the error.
+.SH ERRORS
+.TP
+.B EACCES
+The argument
+.I op
+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 op
+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 op
+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 op
+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 VERSIONS
+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" .
+.\"
+.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.
+.P
+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)).
+.P
+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 STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, SVr4.
+.\" SVr4 documents more error conditions EINVAL and EOVERFLOW.
+.P
+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 op .)
+.P
+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.
+.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.
+.P
+The following system limit on semaphore sets affects a
+.BR semctl ()
+call:
+.TP
+.B SEMVMX
+Maximum value for
+.BR semval :
+implementation dependent (32767).
+.P
+For greater portability, it is best to always call
+.BR semctl ()
+with four arguments.
+.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)