2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993
|
|
|
|
.\"
|
|
|
|
.\" 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.
|
|
|
|
.\"
|
|
|
|
.\" 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>
|
2004-11-03 14:43:40 +00:00
|
|
|
.\" Modified, 8 Jan 2003, Michael Kerrisk, <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Removed EIDRM from errors - that can't happen...
|
2004-11-03 14:43:40 +00:00
|
|
|
.\" Modified, 27 May 2004, Michael Kerrisk <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Added notes on capability requirements
|
2004-11-10 17:23:19 +00:00
|
|
|
.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net>
|
|
|
|
.\" Language and formatting clean-ups
|
|
|
|
.\" Added notes on /proc files
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
2005-10-26 11:23:22 +00:00
|
|
|
.TH SHMGET 2 2005-10-26 "Linux 2.6.14" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
shmget \- allocates a shared memory segment
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.ad l
|
|
|
|
.B #include <sys/ipc.h>
|
|
|
|
.sp
|
|
|
|
.B #include <sys/shm.h>
|
|
|
|
.sp
|
2005-10-04 12:39:34 +00:00
|
|
|
.BI "int shmget(key_t " key ", size_t " size ", int " shmflg );
|
2004-11-03 13:51:07 +00:00
|
|
|
.ad b
|
|
|
|
.SH DESCRIPTION
|
2004-11-10 17:23:19 +00:00
|
|
|
.BR shmget ()
|
2004-11-03 13:51:07 +00:00
|
|
|
returns the identifier of the 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
|
|
|
|
.IR key
|
|
|
|
exists, and
|
|
|
|
.B IPC_CREAT
|
2004-11-10 17:23:19 +00:00
|
|
|
is specified in
|
|
|
|
.IR shmflg .
|
|
|
|
.PP
|
|
|
|
If
|
2004-11-03 13:51:07 +00:00
|
|
|
.I shmflg
|
2004-11-10 17:23:19 +00:00
|
|
|
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).)
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
The value
|
|
|
|
.I shmflg
|
|
|
|
is composed of:
|
|
|
|
.TP 12
|
|
|
|
.B IPC_CREAT
|
|
|
|
to create a new segment. If this flag is not used, then
|
2004-11-10 17:23:19 +00:00
|
|
|
.BR shmget ()
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2004-11-10 17:23:19 +00:00
|
|
|
.I mode_flags
|
|
|
|
(least significant 9 bits)
|
2004-11-03 13:51:07 +00:00
|
|
|
specifying the permissions granted to the owner, group, and world.
|
2004-11-10 17:23:19 +00:00
|
|
|
These bits have the same format, and the same
|
|
|
|
meaning, as the
|
|
|
|
.I mode
|
|
|
|
argument of
|
|
|
|
.BR open (2).
|
2004-11-03 13:51:07 +00:00
|
|
|
Presently, the execute permissions are not used by the system.
|
2005-10-26 10:31:14 +00:00
|
|
|
.TP
|
|
|
|
.B SHM_HUGETLB
|
|
|
|
Allocate the segment using "huge pages."
|
|
|
|
See the kernel source file
|
|
|
|
.I Documentation/vm/hugetlbpage.txt
|
|
|
|
for further information.
|
2005-11-14 13:24:17 +00:00
|
|
|
.\" FIXME 2.6.15-rc1 adds SHM_NORESERVE
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2004-11-10 17:23:19 +00:00
|
|
|
If a new shared memory segment is created,
|
|
|
|
then its associated data structure
|
2004-11-03 13:51:07 +00:00
|
|
|
.I shmid_ds
|
2004-11-10 17:23:19 +00:00
|
|
|
(see
|
|
|
|
.BR shmctl (2))
|
|
|
|
is initialised as follows:
|
2004-11-03 13:51:07 +00:00
|
|
|
.IP
|
2004-11-10 17:23:19 +00:00
|
|
|
.I shm_perm.cuid
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2004-11-10 17:23:19 +00:00
|
|
|
.I shm_perm.uid
|
2005-07-18 16:13:49 +00:00
|
|
|
are set to the effective user ID of the calling process.
|
2004-11-03 13:51:07 +00:00
|
|
|
.IP
|
2004-11-10 17:23:19 +00:00
|
|
|
.I shm_perm.cgid
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2004-11-10 17:23:19 +00:00
|
|
|
.I shm_perm.gid
|
2005-07-18 16:13:49 +00:00
|
|
|
are set to the effective group ID of the calling process.
|
2004-11-03 13:51:07 +00:00
|
|
|
.IP
|
2004-11-10 17:23:19 +00:00
|
|
|
The least significant 9 bits of
|
|
|
|
.I shm_perm.mode
|
|
|
|
are set to the least significant 9 bit of
|
2004-11-03 13:51:07 +00:00
|
|
|
.IR shmflg .
|
|
|
|
.IP
|
2004-11-10 17:23:19 +00:00
|
|
|
.I shm_segsz
|
2004-11-03 13:51:07 +00:00
|
|
|
is set to the value of
|
|
|
|
.IR size .
|
|
|
|
.IP
|
2004-11-10 17:23:19 +00:00
|
|
|
.IR shm_lpid ,
|
|
|
|
.IR shm_nattch ,
|
|
|
|
.I shm_atime
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2004-11-10 17:23:19 +00:00
|
|
|
.I shm_dtime
|
|
|
|
are set to 0.
|
2004-11-03 13:51:07 +00:00
|
|
|
.IP
|
2004-11-10 17:23:19 +00:00
|
|
|
.I shm_ctime
|
2004-11-03 13:51:07 +00:00
|
|
|
is set to the current time.
|
|
|
|
.PP
|
2004-11-10 17:23:19 +00:00
|
|
|
If the shared memory segment already exists, the permissions are
|
2004-11-03 13:51:07 +00:00
|
|
|
verified, and a check is made to see if it is marked for destruction.
|
|
|
|
.SH "SYSTEM CALLS"
|
|
|
|
.TP
|
2004-11-10 17:23:19 +00:00
|
|
|
.BR fork ()
|
2004-11-03 13:51:07 +00:00
|
|
|
After a
|
2004-11-10 17:23:19 +00:00
|
|
|
.BR fork ()
|
2004-11-03 13:51:07 +00:00
|
|
|
the child inherits the attached shared memory segments.
|
|
|
|
.TP
|
2004-11-10 17:23:19 +00:00
|
|
|
.BR exec ()
|
2004-11-03 13:51:07 +00:00
|
|
|
After an
|
2004-11-10 17:23:19 +00:00
|
|
|
.BR exec ()
|
2004-11-03 13:51:07 +00:00
|
|
|
all attached shared memory segments are detached (not destroyed).
|
|
|
|
.TP
|
2004-11-10 17:23:19 +00:00
|
|
|
.BR exit ()
|
2004-11-03 13:51:07 +00:00
|
|
|
Upon
|
2004-11-10 17:23:19 +00:00
|
|
|
.BR exit ()
|
2004-11-03 13:51:07 +00:00
|
|
|
all attached shared memory segments are detached (not destroyed).
|
|
|
|
.PP
|
|
|
|
.SH "RETURN VALUE"
|
|
|
|
A valid segment identifier,
|
|
|
|
.IR shmid ,
|
|
|
|
is returned on success, \-1 on error.
|
|
|
|
.SH ERRORS
|
|
|
|
On failure,
|
2004-11-10 17:23:19 +00:00
|
|
|
.I errno
|
2004-11-03 13:51:07 +00:00
|
|
|
is set to one of the following:
|
|
|
|
.TP 12
|
|
|
|
.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
|
|
|
|
.B IPC_CREAT | IPC_EXCL
|
|
|
|
was specified and the segment exists.
|
|
|
|
.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
|
|
|
|
of that segment.
|
|
|
|
.TP
|
|
|
|
.B ENFILE
|
|
|
|
.\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp()
|
|
|
|
The system 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
|
2005-07-18 16:02:32 +00:00
|
|
|
All possible shared memory IDs have been taken
|
2004-11-03 13:51:07 +00:00
|
|
|
.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 ).
|
2005-10-26 10:31:14 +00:00
|
|
|
.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).
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NOTES
|
|
|
|
.B IPC_PRIVATE
|
|
|
|
isn't a flag field but a
|
2004-11-10 17:23:19 +00:00
|
|
|
.I key_t
|
2004-11-03 13:51:07 +00:00
|
|
|
type.
|
|
|
|
If this special value is used for
|
|
|
|
.IR key ,
|
2004-11-10 17:23:19 +00:00
|
|
|
the system call ignores everything but the least significant 9 bits of
|
2004-11-03 13:51:07 +00:00
|
|
|
.I shmflg
|
|
|
|
and creates a new shared memory segment (on success).
|
|
|
|
.PP
|
2004-12-13 08:39:28 +00:00
|
|
|
The following limits on shared memory segment resources affect the
|
2004-11-10 17:23:19 +00:00
|
|
|
.BR shmget ()
|
2004-11-03 13:51:07 +00:00
|
|
|
call:
|
|
|
|
.TP 11
|
|
|
|
.B SHMALL
|
2004-11-10 17:23:19 +00:00
|
|
|
System wide maximum of shared memory pages
|
|
|
|
(on Linux, this limit can be read and modified via
|
|
|
|
.IR /proc/sys/kernel/shmall ).
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B SHMMAX
|
2004-11-10 17:23:19 +00:00
|
|
|
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 ).
|
2004-11-03 13:51:07 +00:00
|
|
|
.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 maximum number of shared memory segments: implementation
|
2004-11-10 17:23:19 +00:00
|
|
|
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 ).
|
2005-10-26 11:37:47 +00:00
|
|
|
.\" 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 SHMNI -- MTK
|
2004-11-10 17:23:19 +00:00
|
|
|
.\" This /proc file is not available in Linux 2.2 and earlier -- MTK
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
The implementation has no specific limits for the per process maximum
|
|
|
|
number of shared memory segments
|
|
|
|
.RB ( SHMSEG ).
|
|
|
|
.SH BUGS
|
|
|
|
The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW
|
|
|
|
would more clearly show its function.
|
|
|
|
.SH "CONFORMING TO"
|
|
|
|
SVr4, SVID. SVr4 documents an additional error condition EEXIST.
|
|
|
|
Until version 2.3.30 Linux would return EIDRM for a
|
2004-11-10 17:23:19 +00:00
|
|
|
.BR shmget ()
|
2004-11-03 13:51:07 +00:00
|
|
|
on a shared memory segment scheduled for deletion.
|
2005-10-26 10:31:14 +00:00
|
|
|
|
|
|
|
.B SHM_HUGETLB
|
|
|
|
is a non-portable Linux extension.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR shmat (2),
|
|
|
|
.BR shmctl (2),
|
|
|
|
.BR shmdt (2),
|
|
|
|
.BR ftok (3),
|
|
|
|
.BR ipc (5),
|
|
|
|
.BR capabilities (7)
|