.\" Language and formatting clean-ups
.\" Added notes on /proc files
.\"
-.TH SHMGET 2 2012-05-31 "Linux" "Linux Programmer's Manual"
+.TH SHMGET 2 2015-01-10 "Linux" "Linux Programmer's Manual"
.SH NAME
shmget \- allocates a System V shared memory segment
.SH SYNOPSIS
.ad b
.SH DESCRIPTION
.BR shmget ()
-returns the identifier of the System V shared memory segment
+returns the identifier of the System\ V shared memory segment
associated with the value of the argument
.IR key .
A new shared memory segment, with size equal to the value of
is composed of:
.TP 12
.B IPC_CREAT
-to create a new segment.
+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
-used with \fBIPC_CREAT\fP to ensure failure if the segment already exists.
-.TP
-.I mode_flags
-(least significant 9 bits)
-specifying the permissions granted to the owner, group, and world.
-These bits have the same format, and the same
-meaning, as the
-.I mode
-argument of
-.BR open (2).
-Presently, the execute permissions are not used by the system.
+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."
.\" 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,
.IP
.IR shm_lpid ,
.IR shm_nattch ,
-.I shm_atime
+.IR shm_atime ,
and
.I shm_dtime
are set to 0.
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
-A valid segment identifier,
-.IR shmid ,
-is returned on success, \-1 on error.
+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
On failure,
.I errno
capability.
.TP
.B EEXIST
-.B IPC_CREAT | IPC_EXCL
-was specified and the segment exists.
+.BR IPC_CREAT
+and
+.BR 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 new segment was to be created and \fIsize\fP < \fBSHMMIN\fP
-or \fIsize\fP > \fBSHMMAX\fP, or no new segment was to be created,
-a segment with given key existed, but \fIsize\fP is greater than the size
+A segment for the given
+.I key
+exists, but \fIsize\fP is greater than the size
of that segment.
.TP
.B ENFILE
.\" SVr4 documents an additional error condition EEXIST.
.B SHM_HUGETLB
-is a nonportable Linux extension.
+and
+.B SHM_NORESERVE
+are Linux extensions.
.SH NOTES
The inclusion of
.I <sys/types.h>
type.
If this special value is used for
.IR key ,
-the system call ignores everything but the least significant 9 bits of
+the system call ignores all but the least significant 9 bits of
.I shmflg
-and creates a new shared memory segment (on success).
-.PP
+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 maximum of shared memory pages
-(on Linux, this limit can be read and modified via
-.IR /proc/sys/kernel/shmall ).
+System-wide limit on the total amount of shared memory,
+measured in units of the system page size.
+
+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:
+
+ ULONG_MAX - 2^24
+
+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 .
+
+From Linux 2.4 up to Linux 3.15,
+the default value for this limit was:
+
+ SHMMAX / PAGE_SIZE * (SHMMNI / 16)
+
+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: policy dependent
-(on Linux, this limit can be read and modified via
-.IR /proc/sys/kernel/shmmax ).
+Maximum size in bytes for a shared memory segment.
+
+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:
+
+ ULONG_MAX - 2^24
+
+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
+.BR SHMALL
+for a discussion of why this default value (rather than
+.BR ULONG_MAX )
+is used.
+
+From Linux 2.2 up to Linux 3.15, the default value of
+this limit was 0x2000000 (32MB).
+
+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
is the effective minimum size).
.TP
.B SHMMNI
-System wide maximum number of shared memory segments: implementation
-dependent (currently 4096, was 128 before Linux 2.3.99;
-on Linux, this limit can be read and modified via
-.IR /proc/sys/kernel/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.
+
+On Linux, this limit can be read and modified via
+.IR /proc/sys/kernel/shmmni .
.\" Kernels between 2.4.x and 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
number of shared memory segments
.RB ( SHMSEG ).
.SS Linux notes
-Until version 2.3.30 Linux would return
+Until version 2.3.30, Linux would return
.B EIDRM
for a
.BR shmget ()
.B IPC_NEW
would more clearly show its function.
.SH SEE ALSO
+.BR memfd_create (2),
.BR shmat (2),
.BR shmctl (2),
.BR shmdt (2),
.BR capabilities (7),
.BR shm_overview (7),
.BR svipc (7)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.