]> git.ipfire.org Git - thirdparty/man-pages.git/blame - man2/shmget.2
fifo.4 --> fifo.7
[thirdparty/man-pages.git] / man2 / shmget.2
CommitLineData
fea681da
MK
1.\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993
2.\"
3.\" Permission is granted to make and distribute verbatim copies of this
4.\" manual provided the copyright notice and this permission notice are
5.\" preserved on all copies.
6.\"
7.\" Permission is granted to copy and distribute modified versions of this
8.\" manual under the conditions for verbatim copying, provided that the
9.\" entire resulting derived work is distributed under the terms of a
10.\" permission notice identical to this one.
11.\"
12.\" Since the Linux kernel and libraries are constantly changing, this
13.\" manual page may be incorrect or out-of-date. The author(s) assume no
14.\" responsibility for errors or omissions, or for damages resulting from
15.\" the use of the information contained herein. The author(s) may not
16.\" have taken the same level of care in the production of this manual,
17.\" which is licensed free of charge, as they might when working
18.\" professionally.
19.\"
20.\" Formatted or processed versions of this manual, if unaccompanied by
21.\" the source, must acknowledge the copyright and authors of this work.
22.\"
23.\" Modified Wed Jul 28 10:57:35 1993, Rik Faith <faith@cs.unc.edu>
24.\" Modified Sun Nov 28 16:43:30 1993, Rik Faith <faith@cs.unc.edu>
25.\" with material from Giorgio Ciucci <giorgio@crcc.it>
26.\" Portions Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
27.\" Modified Tue Oct 22 22:03:17 1996 by Eric S. Raymond <esr@thyrsus.com>
305a0578 28.\" Modified, 8 Jan 2003, Michael Kerrisk, <mtk-manpages@gmx.net>
fea681da 29.\" Removed EIDRM from errors - that can't happen...
305a0578 30.\" Modified, 27 May 2004, Michael Kerrisk <mtk-manpages@gmx.net>
fea681da 31.\" Added notes on capability requirements
c952e226
MK
32.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net>
33.\" Language and formatting clean-ups
34.\" Added notes on /proc files
fea681da 35.\"
f39637fa 36.TH SHMGET 2 2005-10-26 "Linux 2.6.14" "Linux Programmer's Manual"
fea681da
MK
37.SH NAME
38shmget \- allocates a shared memory segment
39.SH SYNOPSIS
40.ad l
41.B #include <sys/ipc.h>
42.sp
43.B #include <sys/shm.h>
44.sp
f7174672 45.BI "int shmget(key_t " key ", size_t " size ", int " shmflg );
fea681da
MK
46.ad b
47.SH DESCRIPTION
c952e226 48.BR shmget ()
fea681da
MK
49returns the identifier of the shared memory segment
50associated with the value of the argument
51.IR key .
52A new shared memory segment, with size equal to the value of
53.I size
54rounded up to a multiple of
55.BR PAGE_SIZE ,
56is created if
57.I key
58has the value
59.B IPC_PRIVATE
60or
61.I key
62isn't
63.BR IPC_PRIVATE ,
64no shared memory segment corresponding to
65.IR key
66exists, and
67.B IPC_CREAT
c952e226
MK
68is specified in
69.IR shmflg .
70.PP
71If
fea681da 72.I shmflg
c952e226
MK
73specifies both
74.B IPC_CREAT
75and
76.B IPC_EXCL
77and a shared memory segment already exists for
78.IR key ,
79then
80.BR shmget ()
81fails with
82.I errno
83set to
84.BR EEXIST .
85(This is analogous to the effect of the combination
86.B O_CREAT | O_EXCL
87for
88.BR open (2).)
fea681da
MK
89.PP
90The value
91.I shmflg
92is composed of:
93.TP 12
94.B IPC_CREAT
95to create a new segment. If this flag is not used, then
c952e226 96.BR shmget ()
fea681da
MK
97will find the segment associated with \fIkey\fP and check to see if
98the user has permission to access the segment.
99.TP
100.B IPC_EXCL
101used with \fBIPC_CREAT\fP to ensure failure if the segment already exists.
102.TP
c952e226
MK
103.I mode_flags
104(least significant 9 bits)
fea681da 105specifying the permissions granted to the owner, group, and world.
c952e226
MK
106These bits have the same format, and the same
107meaning, as the
108.I mode
109argument of
110.BR open (2).
fea681da 111Presently, the execute permissions are not used by the system.
eb57338f
MK
112.TP
113.B SHM_HUGETLB
114Allocate the segment using "huge pages."
115See the kernel source file
116.I Documentation/vm/hugetlbpage.txt
117for further information.
92057f4d 118.\" FIXME 2.6.15 adds SHM_NORESERVE; document it.
fea681da 119.PP
c952e226
MK
120If a new shared memory segment is created,
121then its associated data structure
fea681da 122.I shmid_ds
c952e226
MK
123(see
124.BR shmctl (2))
125is initialised as follows:
fea681da 126.IP
c952e226 127.I shm_perm.cuid
fea681da 128and
c952e226 129.I shm_perm.uid
499d62f2 130are set to the effective user ID of the calling process.
fea681da 131.IP
c952e226 132.I shm_perm.cgid
fea681da 133and
c952e226 134.I shm_perm.gid
499d62f2 135are set to the effective group ID of the calling process.
fea681da 136.IP
c952e226
MK
137The least significant 9 bits of
138.I shm_perm.mode
139are set to the least significant 9 bit of
fea681da
MK
140.IR shmflg .
141.IP
c952e226 142.I shm_segsz
fea681da
MK
143is set to the value of
144.IR size .
145.IP
c952e226
MK
146.IR shm_lpid ,
147.IR shm_nattch ,
148.I shm_atime
fea681da 149and
c952e226
MK
150.I shm_dtime
151are set to 0.
fea681da 152.IP
c952e226 153.I shm_ctime
fea681da
MK
154is set to the current time.
155.PP
c952e226 156If the shared memory segment already exists, the permissions are
fea681da 157verified, and a check is made to see if it is marked for destruction.
fea681da
MK
158.SH "SYSTEM CALLS"
159.TP
c952e226 160.BR fork ()
fea681da 161After a
c952e226 162.BR fork ()
fea681da
MK
163the child inherits the attached shared memory segments.
164.TP
c952e226 165.BR exec ()
fea681da 166After an
c952e226 167.BR exec ()
fea681da
MK
168all attached shared memory segments are detached (not destroyed).
169.TP
c952e226 170.BR exit ()
fea681da 171Upon
c952e226 172.BR exit ()
fea681da
MK
173all attached shared memory segments are detached (not destroyed).
174.PP
175.SH "RETURN VALUE"
176A valid segment identifier,
177.IR shmid ,
178is returned on success, \-1 on error.
179.SH ERRORS
180On failure,
c952e226 181.I errno
fea681da
MK
182is set to one of the following:
183.TP 12
184.B EACCES
185The user does not have permission to access the
186shared memory segment, and does not have the
187.B CAP_IPC_OWNER
188capability.
189.TP
190.B EEXIST
191.B IPC_CREAT | IPC_EXCL
192was specified and the segment exists.
193.TP
fea681da
MK
194.B EINVAL
195A new segment was to be created and \fIsize\fP < \fBSHMMIN\fP
196or \fIsize\fP > \fBSHMMAX\fP, or no new segment was to be created,
197a segment with given key existed, but \fIsize\fP is greater than the size
198of that segment.
199.TP
200.B ENFILE
201.\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp()
202The system limit on the total number of open files has been reached.
203.TP
204.B ENOENT
205No segment exists for the given \fIkey\fP, and
206.B IPC_CREAT
207was not specified.
208.TP
209.B ENOMEM
210No memory could be allocated for segment overhead.
211.TP
212.B ENOSPC
357cf3fe 213All possible shared memory IDs have been taken
fea681da
MK
214.RB ( SHMMNI ),
215or allocating a segment of the requested
216.I size
217would cause the system to exceed the system-wide limit on shared memory
218.RB ( SHMALL ).
eb57338f
MK
219.TP
220.B EPERM
221The
222.B SHM_HUGETLB
223flag was specified, but the caller was not privileged (did not have the
224.B CAP_IPC_LOCK
225capability).
fea681da
MK
226.SH NOTES
227.B IPC_PRIVATE
228isn't a flag field but a
c952e226 229.I key_t
fea681da
MK
230type.
231If this special value is used for
232.IR key ,
c952e226 233the system call ignores everything but the least significant 9 bits of
fea681da
MK
234.I shmflg
235and creates a new shared memory segment (on success).
236.PP
540036b2 237The following limits on shared memory segment resources affect the
c952e226 238.BR shmget ()
fea681da
MK
239call:
240.TP 11
241.B SHMALL
c952e226
MK
242System wide maximum of shared memory pages
243(on Linux, this limit can be read and modified via
244.IR /proc/sys/kernel/shmall ).
fea681da
MK
245.TP
246.B SHMMAX
c952e226
MK
247Maximum size in bytes for a shared memory segment: policy dependent
248(on Linux, this limit can be read and modified via
249.IR /proc/sys/kernel/shmmax ).
fea681da
MK
250.TP
251.B SHMMIN
252Minimum size in bytes for a shared memory segment: implementation
253dependent (currently 1 byte, though
254.B PAGE_SIZE
255is the effective minimum size).
256.TP
257.B SHMMNI
258System wide maximum number of shared memory segments: implementation
c952e226
MK
259dependent (currently 4096, was 128 before Linux 2.3.99;
260on Linux, this limit can be read and modified via
261.IR /proc/sys/kernel/shmmni ).
ed978af2 262.\" Kernels between 2.4.x and 2.6.8 had an off-by-one error that meant
cd31a0d6 263.\" that we could create one more segment than SHMMNI -- MTK
c952e226 264.\" This /proc file is not available in Linux 2.2 and earlier -- MTK
fea681da
MK
265.PP
266The implementation has no specific limits for the per process maximum
267number of shared memory segments
268.RB ( SHMSEG ).
269.SH BUGS
270The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW
271would more clearly show its function.
272.SH "CONFORMING TO"
273SVr4, SVID. SVr4 documents an additional error condition EEXIST.
274Until version 2.3.30 Linux would return EIDRM for a
c952e226 275.BR shmget ()
fea681da 276on a shared memory segment scheduled for deletion.
eb57338f
MK
277
278.B SHM_HUGETLB
279is a non-portable Linux extension.
fea681da
MK
280.SH "SEE ALSO"
281.BR shmat (2),
282.BR shmctl (2),
283.BR shmdt (2),
284.BR ftok (3),
92243659
MK
285.BR capabilities (7),
286.BR ipc (7)