Merging upstream version 6.8.

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

1 files changed, 412 insertions, 0 deletions

diff --git a/man/man2/shmget.2 b/man/man2/shmget.2
new file mode 100644
index 0000000..45ba5ab
--- /dev/null
+++ b/man/man2/shmget.2
@@ -0,0 +1,412 @@
+.\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified Wed Jul 28 10:57:35 1993, Rik Faith <faith@cs.unc.edu>
+.\" Modified Sun Nov 28 16:43:30 1993, Rik Faith <faith@cs.unc.edu>
+.\"          with material from Giorgio Ciucci <giorgio@crcc.it>
+.\" Portions Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
+.\" Modified Tue Oct 22 22:03:17 1996 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified, 8 Jan 2003, Michael Kerrisk, <mtk.manpages@gmail.com>
+.\"	Removed EIDRM from errors - that can't happen...
+.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"     Added notes on capability requirements
+.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"	Language and formatting clean-ups
+.\"	Added notes on /proc files
+.\"
+.TH shmget 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+shmget \- allocates a System V shared memory segment
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/shm.h>
+.P
+.BI "int shmget(key_t " key ", size_t " size ", int " shmflg );
+.fi
+.SH DESCRIPTION
+.BR shmget ()
+returns the identifier of the System\ V shared memory segment
+associated with the value of the argument
+.IR key .
+It may be used either to obtain the identifier of a previously created
+shared memory segment (when
+.I shmflg
+is zero and
+.I key
+does not have the value
+.BR IPC_PRIVATE ),
+or to create a new set.
+.P
+A new shared memory segment, with size equal to the value of
+.I size
+rounded up to a multiple of
+.BR PAGE_SIZE ,
+is created if
+.I key
+has the value
+.B IPC_PRIVATE
+or
+.I key
+isn't
+.BR IPC_PRIVATE ,
+no shared memory segment corresponding to
+.I key
+exists, and
+.B IPC_CREAT
+is specified in
+.IR shmflg .
+.P
+If
+.I shmflg
+specifies both
+.B IPC_CREAT
+and
+.B IPC_EXCL
+and a shared memory segment already exists for
+.IR key ,
+then
+.BR shmget ()
+fails with
+.I errno
+set to
+.BR EEXIST .
+(This is analogous to the effect of the combination
+.B O_CREAT | O_EXCL
+for
+.BR open (2).)
+.P
+The value
+.I shmflg
+is composed of:
+.TP
+.B IPC_CREAT
+Create a new segment.
+If this flag is not used, then
+.BR shmget ()
+will find the segment associated with \fIkey\fP and check to see if
+the user has permission to access the segment.
+.TP
+.B IPC_EXCL
+This flag is used with
+.B IPC_CREAT
+to ensure that this call creates the segment.
+If the segment already exists, the call fails.
+.TP
+.BR SHM_HUGETLB " (since Linux 2.6)"
+Allocate the segment using "huge" pages.
+See the Linux kernel source file
+.I Documentation/admin\-guide/mm/hugetlbpage.rst
+for further information.
+.TP
+.B SHM_HUGE_2MB
+.TQ
+.BR SHM_HUGE_1GB " (since Linux 3.8)"
+.\" See https://lwn.net/Articles/533499/
+Used in conjunction with
+.B SHM_HUGETLB
+to select alternative hugetlb page sizes (respectively, 2\ MB and 1\ GB)
+on systems that support multiple hugetlb page sizes.
+.IP
+More generally, the desired huge page size can be configured by encoding
+the base-2 logarithm of the desired page size in the six bits at the offset
+.BR SHM_HUGE_SHIFT .
+Thus, the above two constants are defined as:
+.IP
+.in +4n
+.EX
+#define SHM_HUGE_2MB    (21 << SHM_HUGE_SHIFT)
+#define SHM_HUGE_1GB    (30 << SHM_HUGE_SHIFT)
+.EE
+.in
+.IP
+For some additional details,
+see the discussion of the similarly named constants in
+.BR mmap (2).
+.TP
+.BR SHM_NORESERVE " (since Linux 2.6.15)"
+This flag serves the same purpose as the
+.BR mmap (2)
+.B MAP_NORESERVE
+flag.
+Do not reserve swap space for this segment.
+When swap space is reserved, one has the guarantee
+that it is possible to modify the segment.
+When swap space is not reserved one might get
+.B SIGSEGV
+upon a write
+if no physical memory is available.
+See also the discussion of the file
+.I /proc/sys/vm/overcommit_memory
+in
+.BR proc (5).
+.\" As at 2.6.17-rc2, this flag has no effect if SHM_HUGETLB was also
+.\" specified.
+.P
+In addition to the above flags, the least significant 9 bits of
+.I shmflg
+specify the permissions granted to the owner, group, and others.
+These bits have the same format, and the same
+meaning, as the
+.I mode
+argument of
+.BR open (2).
+Presently, execute permissions are not used by the system.
+.P
+When a new shared memory segment is created,
+its contents are initialized to zero values, and
+its associated data structure,
+.I shmid_ds
+(see
+.BR shmctl (2)),
+is initialized as follows:
+.IP \[bu] 3
+.I shm_perm.cuid
+and
+.I shm_perm.uid
+are set to the effective user ID of the calling process.
+.IP \[bu]
+.I shm_perm.cgid
+and
+.I shm_perm.gid
+are set to the effective group ID of the calling process.
+.IP \[bu]
+The least significant 9 bits of
+.I shm_perm.mode
+are set to the least significant 9 bit of
+.IR shmflg .
+.IP \[bu]
+.I shm_segsz
+is set to the value of
+.IR size .
+.IP \[bu]
+.IR shm_lpid ,
+.IR shm_nattch ,
+.IR shm_atime ,
+and
+.I shm_dtime
+are set to 0.
+.IP \[bu]
+.I shm_ctime
+is set to the current time.
+.P
+If the shared memory segment already exists, the permissions are
+verified, and a check is made to see if it is marked for destruction.
+.SH RETURN VALUE
+On success, a valid shared memory identifier is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EACCES
+The user does not have permission to access the
+shared memory segment, and does not have the
+.B CAP_IPC_OWNER
+capability in the user namespace that governs its IPC namespace.
+.TP
+.B EEXIST
+.B IPC_CREAT
+and
+.B IPC_EXCL
+were specified in
+.IR shmflg ,
+but a shared memory segment already exists for
+.IR key .
+.TP
+.B EINVAL
+A new segment was to be created and
+.I size
+is less than
+.B SHMMIN
+or greater than
+.BR SHMMAX .
+.TP
+.B EINVAL
+A segment for the given
+.I key
+exists, but \fIsize\fP is greater than the size
+of that segment.
+.TP
+.B ENFILE
+.\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp()
+The system-wide limit on the total number of open files has been reached.
+.TP
+.B ENOENT
+No segment exists for the given \fIkey\fP, and
+.B IPC_CREAT
+was not specified.
+.TP
+.B ENOMEM
+No memory could be allocated for segment overhead.
+.TP
+.B ENOSPC
+All possible shared memory IDs have been taken
+.RB ( SHMMNI ),
+or allocating a segment of the requested
+.I size
+would cause the system to exceed the system-wide limit on shared memory
+.RB ( SHMALL ).
+.TP
+.B EPERM
+The
+.B SHM_HUGETLB
+flag was specified, but the caller was not privileged (did not have the
+.B CAP_IPC_LOCK
+capability)
+and is not a member of the
+.I sysctl_hugetlb_shm_group
+group; see the description of
+.I /proc/sys/vm/sysctl_hugetlb_shm_group
+in
+.BR proc (5).
+.SH STANDARDS
+POSIX.1-2008.
+.P
+.B SHM_HUGETLB
+and
+.B SHM_NORESERVE
+are Linux extensions.
+.SH HISTORY
+POSIX.1-2001, SVr4.
+.\" SVr4 documents an additional error condition EEXIST.
+.SH NOTES
+.B IPC_PRIVATE
+isn't a flag field but a
+.I key_t
+type.
+If this special value is used for
+.IR key ,
+the system call ignores all but the least significant 9 bits of
+.I shmflg
+and creates a new shared memory segment.
+.\"
+.SS Shared memory limits
+The following limits on shared memory segment resources affect the
+.BR shmget ()
+call:
+.TP
+.B SHMALL
+System-wide limit on the total amount of shared memory,
+measured in units of the system page size.
+.IP
+On Linux, this limit can be read and modified via
+.IR /proc/sys/kernel/shmall .
+Since Linux 3.16,
+.\" commit 060028bac94bf60a65415d1d55a359c3a17d5c31
+the default value for this limit is:
+.IP
+.in +4n
+.EX
+ULONG_MAX - 2\[ha]24
+.EE
+.in
+.IP
+The effect of this value
+(which is suitable for both 32-bit and 64-bit systems)
+is to impose no limitation on allocations.
+This value, rather than
+.BR ULONG_MAX ,
+was chosen as the default to prevent some cases where historical
+applications simply raised the existing limit without first checking
+its current value.
+Such applications would cause the value to overflow if the limit was set at
+.BR ULONG_MAX .
+.IP
+From Linux 2.4 up to Linux 3.15,
+the default value for this limit was:
+.IP
+.in +4n
+.EX
+SHMMAX / PAGE_SIZE * (SHMMNI / 16)
+.EE
+.in
+.IP
+If
+.B SHMMAX
+and
+.B SHMMNI
+were not modified, then multiplying the result of this formula
+by the page size (to get a value in bytes) yielded a value of 8\ GB
+as the limit on the total memory used by all shared memory segments.
+.TP
+.B SHMMAX
+Maximum size in bytes for a shared memory segment.
+.IP
+On Linux, this limit can be read and modified via
+.IR /proc/sys/kernel/shmmax .
+Since Linux 3.16,
+.\" commit 060028bac94bf60a65415d1d55a359c3a17d5c31
+the default value for this limit is:
+.IP
+.in +4n
+.EX
+ULONG_MAX - 2\[ha]24
+.EE
+.in
+.IP
+The effect of this value
+(which is suitable for both 32-bit and 64-bit systems)
+is to impose no limitation on allocations.
+See the description of
+.B SHMALL
+for a discussion of why this default value (rather than
+.BR ULONG_MAX )
+is used.
+.IP
+From Linux 2.2 up to Linux 3.15, the default value of
+this limit was 0x2000000 (32\ MiB).
+.IP
+Because it is not possible to map just part of a shared memory segment,
+the amount of virtual memory places another limit on the maximum size of a
+usable segment:
+for example, on i386 the largest segments that can be mapped have a
+size of around 2.8\ GB, and on x86-64 the limit is around 127 TB.
+.TP
+.B SHMMIN
+Minimum size in bytes for a shared memory segment: implementation
+dependent (currently 1 byte, though
+.B PAGE_SIZE
+is the effective minimum size).
+.TP
+.B SHMMNI
+System-wide limit on the number of shared memory segments.
+In Linux 2.2, the default value for this limit was 128;
+since Linux 2.4, the default value is 4096.
+.IP
+On Linux, this limit can be read and modified via
+.IR /proc/sys/kernel/shmmni .
+.\" Kernels between Linux 2.4.x and Linux 2.6.8 had an off-by-one error
+.\" that meant that we could create one more segment than SHMMNI -- MTK
+.\" This /proc file is not available in Linux 2.2 and earlier -- MTK
+.P
+The implementation has no specific limits for the per-process maximum
+number of shared memory segments
+.RB ( SHMSEG ).
+.SS Linux notes
+Until Linux 2.3.30, Linux would return
+.B EIDRM
+for a
+.BR shmget ()
+on a shared memory segment scheduled for deletion.
+.SH BUGS
+The name choice
+.B IPC_PRIVATE
+was perhaps unfortunate,
+.B IPC_NEW
+would more clearly show its function.
+.SH EXAMPLES
+See
+.BR shmop (2).
+.SH SEE ALSO
+.BR memfd_create (2),
+.BR shmat (2),
+.BR shmctl (2),
+.BR shmdt (2),
+.BR ftok (3),
+.BR capabilities (7),
+.BR shm_overview (7),
+.BR sysvipc (7)