mirror of https://github.com/mkerrisk/man-pages
414 lines
11 KiB
Groff
414 lines
11 KiB
Groff
.\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" 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 2015-12-28 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
shmget \- allocates a System V shared memory segment
|
|
.SH SYNOPSIS
|
|
.ad l
|
|
.B #include <sys/ipc.h>
|
|
.br
|
|
.B #include <sys/shm.h>
|
|
.sp
|
|
.BI "int shmget(key_t " key ", size_t " size ", int " shmflg );
|
|
.ad b
|
|
.SH DESCRIPTION
|
|
.BR shmget ()
|
|
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
|
|
.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 12
|
|
.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/vm/hugetlbpage.txt
|
|
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.
|
|
|
|
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:
|
|
|
|
.nf
|
|
.in +4
|
|
#define SHM_HUGE_2MB (21 << SHM_HUGE_SHIFT)
|
|
#define SHM_HUGE_1GB (30 << SHM_HUGE_SHIFT)
|
|
.in
|
|
.fi
|
|
|
|
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
|
|
.I shm_perm.cuid
|
|
and
|
|
.I shm_perm.uid
|
|
are set to the effective user ID of the calling process.
|
|
.IP
|
|
.I shm_perm.cgid
|
|
and
|
|
.I shm_perm.gid
|
|
are set to the effective group ID of the calling process.
|
|
.IP
|
|
The least significant 9 bits of
|
|
.I shm_perm.mode
|
|
are set to the least significant 9 bit of
|
|
.IR shmflg .
|
|
.IP
|
|
.I shm_segsz
|
|
is set to the value of
|
|
.IR size .
|
|
.IP
|
|
.IR shm_lpid ,
|
|
.IR shm_nattch ,
|
|
.IR shm_atime ,
|
|
and
|
|
.I shm_dtime
|
|
are set to 0.
|
|
.IP
|
|
.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
|
|
On failure,
|
|
.I errno
|
|
is set to one of the following:
|
|
.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.
|
|
.TP
|
|
.B EEXIST
|
|
.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 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).
|
|
.SH CONFORMING TO
|
|
POSIX.1-2001, POSIX.1-2008, SVr4.
|
|
.\" SVr4 documents an additional error condition EEXIST.
|
|
|
|
.B SHM_HUGETLB
|
|
and
|
|
.B SHM_NORESERVE
|
|
are Linux extensions.
|
|
.SH NOTES
|
|
The inclusion of
|
|
.I <sys/types.h>
|
|
and
|
|
.I <sys/ipc.h>
|
|
isn't required on Linux or by any version of POSIX.
|
|
However,
|
|
some old implementations required the inclusion of these header files,
|
|
and the SVID also documented their inclusion.
|
|
Applications intended to be portable to such old systems may need
|
|
to include these header files.
|
|
.\" Like Linux, the FreeBSD man pages still document
|
|
.\" the inclusion of these header files.
|
|
|
|
.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.
|
|
|
|
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.
|
|
|
|
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
|
|
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.
|
|
|
|
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
|
|
.PP
|
|
The implementation has no specific limits for the per-process maximum
|
|
number of shared memory segments
|
|
.RB ( SHMSEG ).
|
|
.SS Linux notes
|
|
Until version 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 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 svipc (7)
|