diff options
Diffstat (limited to '')
| -rw-r--r-- | man2/shmget.2 | 410 |
1 files changed, 410 insertions, 0 deletions
diff --git a/man2/shmget.2 b/man2/shmget.2 new file mode 100644 index 0000000..074e83e --- /dev/null +++ b/man2/shmget.2 @@ -0,0 +1,410 @@ +.\" 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 2023-03-30 "Linux man-pages 6.05.01" +.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> +.PP +.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. +.PP +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 . +.PP +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).) +.PP +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 +.BR SHM_HUGE_2MB ", " 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. +.PP +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. +.PP +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. +.PP +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. +.PP +.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 +.PP +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) |