| blob | 6e9995e8106424f7b5a3df13e4127908f434629f |
1 .\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993
2 .\"
3 .\" %%%LICENSE_START(VERBATIM)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
7 .\"
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
12 .\"
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
19 .\" professionally.
20 .\"
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
23 .\" %%%LICENSE_END
24 .\"
25 .\" Modified Wed Jul 28 10:57:35 1993, Rik Faith <faith@cs.unc.edu>
26 .\" Modified Sun Nov 28 16:43:30 1993, Rik Faith <faith@cs.unc.edu>
27 .\" with material from Giorgio Ciucci <giorgio@crcc.it>
28 .\" Portions Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
29 .\" Modified Tue Oct 22 22:03:17 1996 by Eric S. Raymond <esr@thyrsus.com>
30 .\" Modified, 8 Jan 2003, Michael Kerrisk, <mtk.manpages@gmail.com>
31 .\" Removed EIDRM from errors - that can't happen...
32 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
33 .\" Added notes on capability requirements
34 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
35 .\" Language and formatting clean-ups
36 .\" Added notes on /proc files
37 .\"
38 .TH SHMGET 2 2021-03-22 "Linux" "Linux Programmer's Manual"
39 .SH NAME
40 shmget \- allocates a System V shared memory segment
41 .SH SYNOPSIS
42 .nf
43 .ad l
44 .B #include <sys/shm.h>
45 .PP
46 .BI "int shmget(key_t " key ", size_t " size ", int " shmflg );
47 .ad b
48 .fi
49 .SH DESCRIPTION
50 .BR shmget ()
51 returns the identifier of the System\ V shared memory segment
52 associated with the value of the argument
53 .IR key .
54 It may be used either to obtain the identifier of a previously created
55 shared memory segment (when
56 .I shmflg
57 is zero and
58 .I key
59 does not have the value
60 .BR IPC_PRIVATE ),
61 or to create a new set.
62 .PP
63 A new shared memory segment, with size equal to the value of
64 .I size
65 rounded up to a multiple of
66 .BR PAGE_SIZE ,
67 is created if
68 .I key
69 has the value
70 .B IPC_PRIVATE
71 or
72 .I key
73 isn't
74 .BR IPC_PRIVATE ,
75 no shared memory segment corresponding to
76 .I key
77 exists, and
78 .B IPC_CREAT
79 is specified in
80 .IR shmflg .
81 .PP
82 If
83 .I shmflg
84 specifies both
85 .B IPC_CREAT
86 and
87 .B IPC_EXCL
88 and a shared memory segment already exists for
89 .IR key ,
90 then
91 .BR shmget ()
92 fails with
93 .I errno
94 set to
95 .BR EEXIST .
96 (This is analogous to the effect of the combination
97 .B O_CREAT | O_EXCL
98 for
99 .BR open (2).)
100 .PP
101 The value
102 .I shmflg
103 is composed of:
104 .TP
105 .B IPC_CREAT
106 Create a new segment.
107 If this flag is not used, then
108 .BR shmget ()
109 will find the segment associated with \fIkey\fP and check to see if
110 the user has permission to access the segment.
111 .TP
112 .B IPC_EXCL
113 This flag is used with
114 .B IPC_CREAT
115 to ensure that this call creates the segment.
116 If the segment already exists, the call fails.
117 .TP
118 .BR SHM_HUGETLB " (since Linux 2.6)"
119 Allocate the segment using "huge" pages.
120 See the Linux kernel source file
121 .I Documentation/admin\-guide/mm/hugetlbpage.rst
122 for further information.
123 .TP
124 .BR SHM_HUGE_2MB ", " SHM_HUGE_1GB " (since Linux 3.8)"
125 .\" See https://lwn.net/Articles/533499/
126 Used in conjunction with
127 .B SHM_HUGETLB
128 to select alternative hugetlb page sizes (respectively, 2\ MB and 1\ GB)
129 on systems that support multiple hugetlb page sizes.
130 .IP
131 More generally, the desired huge page size can be configured by encoding
132 the base-2 logarithm of the desired page size in the six bits at the offset
133 .BR SHM_HUGE_SHIFT .
134 Thus, the above two constants are defined as:
135 .IP
136 .in +4n
137 .EX
138 #define SHM_HUGE_2MB (21 << SHM_HUGE_SHIFT)
139 #define SHM_HUGE_1GB (30 << SHM_HUGE_SHIFT)
140 .EE
141 .in
142 .IP
143 For some additional details,
144 see the discussion of the similarly named constants in
145 .BR mmap (2).
146 .TP
147 .BR SHM_NORESERVE " (since Linux 2.6.15)"
148 This flag serves the same purpose as the
149 .BR mmap (2)
150 .B MAP_NORESERVE
151 flag.
152 Do not reserve swap space for this segment.
153 When swap space is reserved, one has the guarantee
154 that it is possible to modify the segment.
155 When swap space is not reserved one might get
156 .B SIGSEGV
157 upon a write
158 if no physical memory is available.
159 See also the discussion of the file
160 .I /proc/sys/vm/overcommit_memory
161 in
162 .BR proc (5).
163 .\" As at 2.6.17-rc2, this flag has no effect if SHM_HUGETLB was also
164 .\" specified.
165 .PP
166 In addition to the above flags, the least significant 9 bits of
167 .I shmflg
168 specify the permissions granted to the owner, group, and others.
169 These bits have the same format, and the same
170 meaning, as the
171 .I mode
172 argument of
173 .BR open (2).
174 Presently, execute permissions are not used by the system.
175 .PP
176 When a new shared memory segment is created,
177 its contents are initialized to zero values, and
178 its associated data structure,
179 .I shmid_ds
180 (see
181 .BR shmctl (2)),
182 is initialized as follows:
183 .IP \(bu 2
184 .I shm_perm.cuid
185 and
186 .I shm_perm.uid
187 are set to the effective user ID of the calling process.
188 .IP \(bu
189 .I shm_perm.cgid
190 and
191 .I shm_perm.gid
192 are set to the effective group ID of the calling process.
193 .IP \(bu
194 The least significant 9 bits of
195 .I shm_perm.mode
196 are set to the least significant 9 bit of
197 .IR shmflg .
198 .IP \(bu
199 .I shm_segsz
200 is set to the value of
201 .IR size .
202 .IP \(bu
203 .IR shm_lpid ,
204 .IR shm_nattch ,
205 .IR shm_atime ,
206 and
207 .I shm_dtime
208 are set to 0.
209 .IP \(bu
210 .I shm_ctime
211 is set to the current time.
212 .PP
213 If the shared memory segment already exists, the permissions are
214 verified, and a check is made to see if it is marked for destruction.
215 .SH RETURN VALUE
216 On success, a valid shared memory identifier is returned.
217 On error, \-1 is returned, and
218 .I errno
219 is set to indicate the error.
220 .SH ERRORS
221 .TP
222 .B EACCES
223 The user does not have permission to access the
224 shared memory segment, and does not have the
225 .B CAP_IPC_OWNER
226 capability in the user namespace that governs its IPC namespace.
227 .TP
228 .B EEXIST
229 .BR IPC_CREAT
230 and
231 .BR IPC_EXCL
232 were specified in
233 .IR shmflg ,
234 but a shared memory segment already exists for
235 .IR key .
236 .TP
237 .B EINVAL
238 A new segment was to be created and
239 .I size
240 is less than
241 .B SHMMIN
242 or greater than
243 .BR SHMMAX .
244 .TP
245 .B EINVAL
246 A segment for the given
247 .I key
248 exists, but \fIsize\fP is greater than the size
249 of that segment.
250 .TP
251 .B ENFILE
252 .\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp()
253 The system-wide limit on the total number of open files has been reached.
254 .TP
255 .B ENOENT
256 No segment exists for the given \fIkey\fP, and
257 .B IPC_CREAT
258 was not specified.
259 .TP
260 .B ENOMEM
261 No memory could be allocated for segment overhead.
262 .TP
263 .B ENOSPC
264 All possible shared memory IDs have been taken
265 .RB ( SHMMNI ),
266 or allocating a segment of the requested
267 .I size
268 would cause the system to exceed the system-wide limit on shared memory
269 .RB ( SHMALL ).
270 .TP
271 .B EPERM
272 The
273 .B SHM_HUGETLB
274 flag was specified, but the caller was not privileged (did not have the
275 .B CAP_IPC_LOCK
276 capability)
277 and is not a member of the
278 .I sysctl_hugetlb_shm_group
279 group; see the description of
280 .I /proc/sys/vm/sysctl_hugetlb_shm_group
281 in
282 .BR proc (5).
283 .SH CONFORMING TO
284 POSIX.1-2001, POSIX.1-2008, SVr4.
285 .\" SVr4 documents an additional error condition EEXIST.
286 .PP
287 .B SHM_HUGETLB
288 and
289 .B SHM_NORESERVE
290 are Linux extensions.
291 .SH NOTES
292 .B IPC_PRIVATE
293 isn't a flag field but a
294 .I key_t
295 type.
296 If this special value is used for
297 .IR key ,
298 the system call ignores all but the least significant 9 bits of
299 .I shmflg
300 and creates a new shared memory segment.
301 .\"
302 .SS Shared memory limits
303 The following limits on shared memory segment resources affect the
304 .BR shmget ()
305 call:
306 .TP
307 .B SHMALL
308 System-wide limit on the total amount of shared memory,
309 measured in units of the system page size.
310 .IP
311 On Linux, this limit can be read and modified via
312 .IR /proc/sys/kernel/shmall .
313 Since Linux 3.16,
314 .\" commit 060028bac94bf60a65415d1d55a359c3a17d5c31
315 the default value for this limit is:
316 .IP
317 ULONG_MAX - 2^24
318 .IP
319 The effect of this value
320 (which is suitable for both 32-bit and 64-bit systems)
321 is to impose no limitation on allocations.
322 This value, rather than
323 .BR ULONG_MAX ,
324 was chosen as the default to prevent some cases where historical
325 applications simply raised the existing limit without first checking
326 its current value.
327 Such applications would cause the value to overflow if the limit was set at
328 .BR ULONG_MAX .
329 .IP
330 From Linux 2.4 up to Linux 3.15,
331 the default value for this limit was:
332 .IP
333 SHMMAX / PAGE_SIZE * (SHMMNI / 16)
334 .IP
335 If
336 .B SHMMAX
337 and
338 .B SHMMNI
339 were not modified, then multiplying the result of this formula
340 by the page size (to get a value in bytes) yielded a value of 8\ GB
341 as the limit on the total memory used by all shared memory segments.
342 .TP
343 .B SHMMAX
344 Maximum size in bytes for a shared memory segment.
345 .IP
346 On Linux, this limit can be read and modified via
347 .IR /proc/sys/kernel/shmmax .
348 Since Linux 3.16,
349 .\" commit 060028bac94bf60a65415d1d55a359c3a17d5c31
350 the default value for this limit is:
351 .IP
352 ULONG_MAX - 2^24
353 .IP
354 The effect of this value
355 (which is suitable for both 32-bit and 64-bit systems)
356 is to impose no limitation on allocations.
357 See the description of
358 .BR SHMALL
359 for a discussion of why this default value (rather than
360 .BR ULONG_MAX )
361 is used.
362 .IP
363 From Linux 2.2 up to Linux 3.15, the default value of
364 this limit was 0x2000000 (32\ MB).
365 .IP
366 Because it is not possible to map just part of a shared memory segment,
367 the amount of virtual memory places another limit on the maximum size of a
368 usable segment:
369 for example, on i386 the largest segments that can be mapped have a
370 size of around 2.8\ GB, and on x86-64 the limit is around 127 TB.
371 .TP
372 .B SHMMIN
373 Minimum size in bytes for a shared memory segment: implementation
374 dependent (currently 1 byte, though
375 .B PAGE_SIZE
376 is the effective minimum size).
377 .TP
378 .B SHMMNI
379 System-wide limit on the number of shared memory segments.
380 In Linux 2.2, the default value for this limit was 128;
381 since Linux 2.4, the default value is 4096.
382 .IP
383 On Linux, this limit can be read and modified via
384 .IR /proc/sys/kernel/shmmni .
385 .\" Kernels between 2.4.x and 2.6.8 had an off-by-one error that meant
386 .\" that we could create one more segment than SHMMNI -- MTK
387 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
388 .PP
389 The implementation has no specific limits for the per-process maximum
390 number of shared memory segments
391 .RB ( SHMSEG ).
392 .SS Linux notes
393 Until version 2.3.30, Linux would return
394 .B EIDRM
395 for a
396 .BR shmget ()
397 on a shared memory segment scheduled for deletion.
398 .SH BUGS
399 The name choice
400 .B IPC_PRIVATE
401 was perhaps unfortunate,
402 .B IPC_NEW
403 would more clearly show its function.
404 .SH EXAMPLES
405 See
406 .BR shmop (2).
407 .SH SEE ALSO
408 .BR memfd_create (2),
409 .BR shmat (2),
410 .BR shmctl (2),
411 .BR shmdt (2),
412 .BR ftok (3),
413 .BR capabilities (7),
414 .BR shm_overview (7),
415 .BR sysvipc (7)