Merging upstream version 6.8.

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

1 files changed, 494 insertions, 0 deletions

diff --git a/man/man2/shmctl.2 b/man/man2/shmctl.2
new file mode 100644
index 0000000..45f8cf1
--- /dev/null
+++ b/man/man2/shmctl.2
@@ -0,0 +1,494 @@
+'\" t
+.\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993
+.\" and 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 1993-07-28, Rik Faith <faith@cs.unc.edu>
+.\" Modified 1993-11-28, Giorgio Ciucci <giorgio@crcc.it>
+.\" Modified 1997-01-31, Eric S. Raymond <esr@thyrsus.com>
+.\" Modified 2001-02-18, Andries Brouwer <aeb@cwi.nl>
+.\" Modified 2002-01-05, 2004-05-27, 2004-06-17,
+.\"    Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Modified 2004-10-11, aeb
+.\" Modified, Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"	Language and formatting clean-ups
+.\"	Updated shmid_ds structure definitions
+.\"	Added information on SHM_DEST and SHM_LOCKED flags
+.\"	Noted that CAP_IPC_LOCK is not required for SHM_UNLOCK
+.\"		since Linux 2.6.9
+.\" Modified, 2004-11-25, mtk, notes on 2.6.9 RLIMIT_MEMLOCK changes
+.\" 2005-04-25, mtk -- noted aberrant Linux behavior w.r.t. new
+.\"	attaches to a segment that has already been marked for deletion.
+.\" 2005-08-02, mtk: Added IPC_INFO, SHM_INFO, SHM_STAT descriptions.
+.\" 2018-03-20, dbueso: Added SHM_STAT_ANY description.
+.\"
+.TH shmctl 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+shmctl \- System V shared memory control
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/shm.h>
+.P
+.BI "int shmctl(int " shmid ", int " op ", struct shmid_ds *" buf );
+.fi
+.SH DESCRIPTION
+.BR shmctl ()
+performs the control operation specified by
+.I op
+on the System\ V shared memory segment whose identifier is given in
+.IR shmid .
+.P
+The
+.I buf
+argument is a pointer to a \fIshmid_ds\fP structure,
+defined in \fI<sys/shm.h>\fP as follows:
+.P
+.in +4n
+.EX
+struct shmid_ds {
+    struct ipc_perm shm_perm;    /* Ownership and permissions */
+    size_t          shm_segsz;   /* Size of segment (bytes) */
+    time_t          shm_atime;   /* Last attach time */
+    time_t          shm_dtime;   /* Last detach time */
+    time_t          shm_ctime;   /* Creation time/time of last
+                                    modification via shmctl() */
+    pid_t           shm_cpid;    /* PID of creator */
+    pid_t           shm_lpid;    /* PID of last shmat(2)/shmdt(2) */
+    shmatt_t        shm_nattch;  /* No. of current attaches */
+    ...
+};
+.EE
+.in
+.P
+The fields of the
+.I shmid_ds
+structure are as follows:
+.TP 12
+.I shm_perm
+This is an
+.I ipc_perm
+structure (see below) that specifies the access permissions
+on the shared memory segment.
+.TP
+.I shm_segsz
+Size in bytes of the shared memory segment.
+.TP
+.I shm_atime
+Time of the last
+.BR shmat (2)
+system call that attached this segment.
+.TP
+.I shm_dtime
+Time of the last
+.BR shmdt (2)
+system call that detached tgis segment.
+.TP
+.I shm_ctime
+Time of creation of segment or time of the last
+.BR shmctl ()
+.B IPC_SET
+operation.
+.TP
+.I shm_cpid
+ID of the process that created the shared memory segment.
+.TP
+.I shm_lpid
+ID of the last process that executed a
+.BR shmat (2)
+or
+.BR shmdt (2)
+system call on this segment.
+.TP
+.I shm_nattch
+Number of processes that have this segment attached.
+.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 shmget(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;     /* \fBPermissions\fP + SHM_DEST and
+                                SHM_LOCKED flags */
+    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
+Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
+(It is not necessary to have execute permission on a segment
+in order to perform a
+.BR shmat (2)
+call with the
+.B SHM_EXEC
+flag.)
+.P
+Valid values for
+.I op
+are:
+.TP
+.B IPC_STAT
+Copy information from the kernel data structure associated with
+.I shmid
+into the
+.I shmid_ds
+structure pointed to by \fIbuf\fP.
+The caller must have read permission on the
+shared memory segment.
+.TP
+.B IPC_SET
+Write the values of some members of the
+.I shmid_ds
+structure pointed to by
+.I buf
+to the kernel data structure associated with this shared memory segment,
+updating also its
+.I shm_ctime
+member.
+.IP
+The following fields are updated:
+\fIshm_perm.uid\fP, \fIshm_perm.gid\fP,
+and (the least significant 9 bits of) \fIshm_perm.mode\fP.
+.IP
+The effective UID of the calling process must match the owner
+.RI ( shm_perm.uid )
+or creator
+.RI ( shm_perm.cuid )
+of the shared memory segment, or the caller must be privileged.
+.TP
+.B IPC_RMID
+Mark the segment to be destroyed.
+The segment will actually be destroyed
+only after the last process detaches it (i.e., when the
+.I shm_nattch
+member of the associated structure
+.I shmid_ds
+is zero).
+The caller must be the owner or creator of the segment, or be privileged.
+The
+.I buf
+argument is ignored.
+.IP
+If a segment has been marked for destruction, then the (nonstandard)
+.B SHM_DEST
+flag of the
+.I shm_perm.mode
+field in the associated data structure retrieved by
+.B IPC_STAT
+will be set.
+.IP
+The caller \fImust\fP ensure that a segment is eventually destroyed;
+otherwise its pages that were faulted in will remain in memory or swap.
+.IP
+See also the description of
+.I  /proc/sys/kernel/shm_rmid_forced
+in
+.BR proc (5).
+.TP
+.BR IPC_INFO " (Linux-specific)"
+Return information about system-wide shared memory limits and
+parameters in the structure pointed to by
+.IR buf .
+This structure is of type
+.I shminfo
+(thus, a cast is required),
+defined in
+.I <sys/shm.h>
+if the
+.B _GNU_SOURCE
+feature test macro is defined:
+.IP
+.in +4n
+.EX
+struct shminfo {
+    unsigned long shmmax; /* Maximum segment size */
+    unsigned long shmmin; /* Minimum segment size;
+                             always 1 */
+    unsigned long shmmni; /* Maximum number of segments */
+    unsigned long shmseg; /* Maximum number of segments
+                             that a process can attach;
+                             unused within kernel */
+    unsigned long shmall; /* Maximum number of pages of
+                             shared memory, system\-wide */
+};
+.EE
+.in
+.IP
+The
+.IR shmmni ,
+.IR shmmax ,
+and
+.I shmall
+settings can be changed via
+.I /proc
+files of the same name; see
+.BR proc (5)
+for details.
+.TP
+.BR SHM_INFO " (Linux-specific)"
+Return a
+.I shm_info
+structure whose fields contain information
+about system resources consumed by shared memory.
+This structure is defined in
+.I <sys/shm.h>
+if the
+.B _GNU_SOURCE
+feature test macro is defined:
+.IP
+.in +4n
+.EX
+struct shm_info {
+    int           used_ids; /* # of currently existing
+                               segments */
+    unsigned long shm_tot;  /* Total number of shared
+                               memory pages */
+    unsigned long shm_rss;  /* # of resident shared
+                               memory pages */
+    unsigned long shm_swp;  /* # of swapped shared
+                               memory pages */
+    unsigned long swap_attempts;
+                            /* Unused since Linux 2.4 */
+    unsigned long swap_successes;
+                            /* Unused since Linux 2.4 */
+};
+.EE
+.in
+.TP
+.BR SHM_STAT " (Linux-specific)"
+Return a
+.I shmid_ds
+structure as for
+.BR IPC_STAT .
+However, the
+.I shmid
+argument is not a segment identifier, but instead an index into
+the kernel's internal array that maintains information about
+all shared memory segments on the system.
+.TP
+.BR SHM_STAT_ANY " (Linux-specific, since Linux 4.17)"
+Return a
+.I shmid_ds
+structure as for
+.BR SHM_STAT .
+However,
+.I shm_perm.mode
+is not checked for read access for
+.IR shmid ,
+meaning that any user can employ this operation (just as any user may read
+.I /proc/sysvipc/shm
+to obtain the same information).
+.P
+The caller can prevent or allow swapping of a shared
+memory segment with the following
+.I op
+values:
+.TP
+.BR SHM_LOCK " (Linux-specific)"
+Prevent swapping of the shared memory segment.
+The caller must fault in
+any pages that are required to be present after locking is enabled.
+If a segment has been locked, then the (nonstandard)
+.B SHM_LOCKED
+flag of the
+.I shm_perm.mode
+field in the associated data structure retrieved by
+.B IPC_STAT
+will be set.
+.TP
+.BR SHM_UNLOCK " (Linux-specific)"
+Unlock the segment, allowing it to be swapped out.
+.P
+Before Linux 2.6.10, only a privileged process
+could employ
+.B SHM_LOCK
+and
+.BR SHM_UNLOCK .
+Since Linux 2.6.10, an unprivileged process can employ these operations
+if its effective UID matches the owner or creator UID of the segment, and
+(for
+.BR SHM_LOCK )
+the amount of memory to be locked falls within the
+.B RLIMIT_MEMLOCK
+resource limit (see
+.BR setrlimit (2)).
+.\" There was some weirdness in Linux 2.6.9: SHM_LOCK and SHM_UNLOCK could
+.\" be applied to a segment, regardless of ownership of the segment.
+.\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed
+.\" in Linux 2.6.10.  MTK, May 2005
+.SH RETURN VALUE
+A successful
+.B IPC_INFO
+or
+.B SHM_INFO
+operation returns the index of the highest used entry in the
+kernel's internal array recording information about all
+shared memory segments.
+(This information can be used with repeated
+.B SHM_STAT
+or
+.B SHM_STAT_ANY
+operations to obtain information about all shared memory segments
+on the system.)
+A successful
+.B SHM_STAT
+operation returns the identifier of the shared memory segment
+whose index was given in
+.IR shmid .
+Other operations return 0 on success.
+.P
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EACCES
+\fBIPC_STAT\fP or \fBSHM_STAT\fP is requested and
+\fIshm_perm.mode\fP does not allow read access for
+.IR shmid ,
+and the calling process does not have the
+.B CAP_IPC_OWNER
+capability in the user namespace that governs its IPC namespace.
+.TP
+.B EFAULT
+The argument
+.I op
+has value
+.B IPC_SET
+or
+.B IPC_STAT
+but the address pointed to by
+.I buf
+isn't accessible.
+.TP
+.B EIDRM
+\fIshmid\fP points to a removed identifier.
+.TP
+.B EINVAL
+.I shmid
+is not a valid identifier, or
+.I op
+is not a valid operation.
+Or: for a
+.B SHM_STAT
+or
+.B SHM_STAT_ANY
+operation, the index value specified in
+.I shmid
+referred to an array slot that is currently unused.
+.TP
+.B ENOMEM
+(Since Linux 2.6.9),
+.B SHM_LOCK
+was specified and the size of the to-be-locked segment would mean
+that the total bytes in locked shared memory segments would exceed
+the limit for the real user ID of the calling process.
+This limit is defined by the
+.B RLIMIT_MEMLOCK
+soft resource limit (see
+.BR setrlimit (2)).
+.TP
+.B EOVERFLOW
+\fBIPC_STAT\fP is attempted, and the GID or UID value
+is too large to be stored in the structure pointed to by
+.IR buf .
+.TP
+.B EPERM
+\fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the
+effective user ID of the calling process is not that of the creator
+(found in
+.IR shm_perm.cuid ),
+or the owner
+(found in
+.IR shm_perm.uid ),
+and the process was not privileged (Linux: did not have the
+.B CAP_SYS_ADMIN
+capability).
+.IP
+Or (before Linux 2.6.9),
+.B SHM_LOCK
+or
+.B SHM_UNLOCK
+was specified, but the process was not privileged
+(Linux: did not have the
+.B CAP_IPC_LOCK
+capability).
+(Since Linux 2.6.9, this error can also occur if the
+.B RLIMIT_MEMLOCK
+is 0 and the caller is not privileged.)
+.SH VERSIONS
+Linux permits a process to attach
+.RB ( shmat (2))
+a shared memory segment that has already been marked for deletion
+using
+.IR shmctl(IPC_RMID) .
+This feature is not available on other UNIX implementations;
+portable applications should avoid relying on it.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, SVr4.
+.\" SVr4 documents additional error conditions EINVAL,
+.\" ENOENT, ENOSPC, ENOMEM, EEXIST.  Neither SVr4 nor SVID documents
+.\" an EIDRM error condition.
+.P
+Various fields in a \fIstruct shmid_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 .)
+.SH NOTES
+The
+.BR IPC_INFO ,
+.BR SHM_STAT ,
+and
+.B SHM_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.
+.SH SEE ALSO
+.BR mlock (2),
+.BR setrlimit (2),
+.BR shmget (2),
+.BR shmop (2),
+.BR capabilities (7),
+.BR sysvipc (7)