]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993 |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
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. | |
c13182ef | 12 | .\" |
fea681da MK |
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. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da MK |
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> | |
c11b1abf | 30 | .\" Modified, 8 Jan 2003, Michael Kerrisk, <mtk.manpages@gmail.com> |
fea681da | 31 | .\" Removed EIDRM from errors - that can't happen... |
c11b1abf | 32 | .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 33 | .\" Added notes on capability requirements |
c11b1abf | 34 | .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
c952e226 MK |
35 | .\" Language and formatting clean-ups |
36 | .\" Added notes on /proc files | |
fea681da | 37 | .\" |
4b8c67d9 | 38 | .TH SHMGET 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 39 | .SH NAME |
47f065d6 | 40 | shmget \- allocates a System V shared memory segment |
fea681da MK |
41 | .SH SYNOPSIS |
42 | .ad l | |
43 | .B #include <sys/ipc.h> | |
d314dbfd | 44 | .br |
fea681da | 45 | .B #include <sys/shm.h> |
68e4db0a | 46 | .PP |
f7174672 | 47 | .BI "int shmget(key_t " key ", size_t " size ", int " shmflg ); |
fea681da MK |
48 | .ad b |
49 | .SH DESCRIPTION | |
c952e226 | 50 | .BR shmget () |
efbfd7ec | 51 | returns the identifier of the System\ V shared memory segment |
fea681da MK |
52 | associated with the value of the argument |
53 | .IR key . | |
f8ac3de3 MK |
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. | |
8c2e5f83 | 62 | .PP |
fea681da MK |
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 | |
0daa9e92 | 76 | .I key |
fea681da MK |
77 | exists, and |
78 | .B IPC_CREAT | |
c952e226 MK |
79 | is specified in |
80 | .IR shmflg . | |
81 | .PP | |
82 | If | |
fea681da | 83 | .I shmflg |
c952e226 MK |
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 () | |
c13182ef | 92 | fails with |
c952e226 MK |
93 | .I errno |
94 | set to | |
95 | .BR EEXIST . | |
c13182ef | 96 | (This is analogous to the effect of the combination |
c952e226 MK |
97 | .B O_CREAT | O_EXCL |
98 | for | |
99 | .BR open (2).) | |
fea681da MK |
100 | .PP |
101 | The value | |
102 | .I shmflg | |
103 | is composed of: | |
104 | .TP 12 | |
105 | .B IPC_CREAT | |
130a878d | 106 | Create a new segment. |
c13182ef | 107 | If this flag is not used, then |
c952e226 | 108 | .BR shmget () |
c13182ef | 109 | will find the segment associated with \fIkey\fP and check to see if |
fea681da MK |
110 | the user has permission to access the segment. |
111 | .TP | |
112 | .B IPC_EXCL | |
fbaf6d6e MK |
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. | |
fea681da | 117 | .TP |
32047971 | 118 | .BR SHM_HUGETLB " (since Linux 2.6)" |
c13182ef | 119 | Allocate the segment using "huge pages." |
66a9882e | 120 | See the Linux kernel source file |
eb57338f MK |
121 | .I Documentation/vm/hugetlbpage.txt |
122 | for further information. | |
32047971 | 123 | .TP |
6ca52c17 MK |
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 | |
c4b7e5ac | 128 | to select alternative hugetlb page sizes (respectively, 2\ MB and 1\ GB) |
6ca52c17 | 129 | on systems that support multiple hugetlb page sizes. |
efeece04 | 130 | .IP |
6ca52c17 MK |
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: | |
efeece04 | 135 | .IP |
6ca52c17 | 136 | .in +4 |
207050fa | 137 | .EX |
6ca52c17 MK |
138 | #define SHM_HUGE_2MB (21 << SHM_HUGE_SHIFT) |
139 | #define SHM_HUGE_1GB (30 << SHM_HUGE_SHIFT) | |
b8302363 | 140 | .EE |
e646a1ba | 141 | .in |
efeece04 | 142 | .IP |
6ca52c17 MK |
143 | For some additional details, |
144 | see the discussion of the similarly named constants in | |
145 | .BR mmap (2). | |
146 | .TP | |
32047971 MK |
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. | |
c13182ef | 152 | Do not reserve swap space for this segment. |
32047971 MK |
153 | When swap space is reserved, one has the guarantee |
154 | that it is possible to modify the segment. | |
8bd58774 MK |
155 | When swap space is not reserved one might get |
156 | .B SIGSEGV | |
157 | upon a write | |
32047971 MK |
158 | if no physical memory is available. |
159 | See also the discussion of the file | |
160 | .I /proc/sys/vm/overcommit_memory | |
c13182ef | 161 | in |
defcceb3 | 162 | .BR proc (5). |
32047971 MK |
163 | .\" As at 2.6.17-rc2, this flag has no effect if SHM_HUGETLB was also |
164 | .\" specified. | |
fea681da | 165 | .PP |
e1d802d5 MK |
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 | |
6319e935 | 176 | When a new shared memory segment is created, |
d9bfdb9c | 177 | its contents are initialized to zero values, and |
6319e935 | 178 | its associated data structure, |
fea681da | 179 | .I shmid_ds |
c952e226 | 180 | (see |
6319e935 | 181 | .BR shmctl (2)), |
d9bfdb9c | 182 | is initialized as follows: |
fea681da | 183 | .IP |
c952e226 | 184 | .I shm_perm.cuid |
fea681da | 185 | and |
c952e226 | 186 | .I shm_perm.uid |
499d62f2 | 187 | are set to the effective user ID of the calling process. |
fea681da | 188 | .IP |
c952e226 | 189 | .I shm_perm.cgid |
fea681da | 190 | and |
c952e226 | 191 | .I shm_perm.gid |
499d62f2 | 192 | are set to the effective group ID of the calling process. |
fea681da | 193 | .IP |
c952e226 MK |
194 | The least significant 9 bits of |
195 | .I shm_perm.mode | |
196 | are set to the least significant 9 bit of | |
fea681da MK |
197 | .IR shmflg . |
198 | .IP | |
c952e226 | 199 | .I shm_segsz |
fea681da MK |
200 | is set to the value of |
201 | .IR size . | |
202 | .IP | |
c952e226 MK |
203 | .IR shm_lpid , |
204 | .IR shm_nattch , | |
a797afac | 205 | .IR shm_atime , |
fea681da | 206 | and |
c952e226 MK |
207 | .I shm_dtime |
208 | are set to 0. | |
fea681da | 209 | .IP |
c952e226 | 210 | .I shm_ctime |
fea681da MK |
211 | is set to the current time. |
212 | .PP | |
c952e226 | 213 | If the shared memory segment already exists, the permissions are |
fea681da | 214 | verified, and a check is made to see if it is marked for destruction. |
47297adb | 215 | .SH RETURN VALUE |
716c8c3f | 216 | On success, a valid shared memory identifier is returned. |
0bca57f3 | 217 | On error, \-1 is returned, and |
716c8c3f MK |
218 | .I errno |
219 | is set to indicate the error. | |
fea681da MK |
220 | .SH ERRORS |
221 | On failure, | |
c952e226 | 222 | .I errno |
fea681da | 223 | is set to one of the following: |
89b3c6b8 | 224 | .TP |
fea681da | 225 | .B EACCES |
c13182ef | 226 | The user does not have permission to access the |
fea681da MK |
227 | shared memory segment, and does not have the |
228 | .B CAP_IPC_OWNER | |
3294109d | 229 | capability in the user namespace that governs its IPC namespace. |
fea681da MK |
230 | .TP |
231 | .B EEXIST | |
247e5615 MK |
232 | .BR IPC_CREAT |
233 | and | |
234 | .BR IPC_EXCL | |
235 | were specified in | |
236 | .IR shmflg , | |
237 | but a shared memory segment already exists for | |
238 | .IR key . | |
fea681da | 239 | .TP |
fea681da | 240 | .B EINVAL |
a350124d MK |
241 | A new segment was to be created and |
242 | .I size | |
243 | is less than | |
8804c8da | 244 | .B SHMMIN |
a350124d | 245 | or greater than |
41651a35 MK |
246 | .BR SHMMAX . |
247 | .TP | |
248 | .B EINVAL | |
11bae399 | 249 | A segment for the given |
41651a35 MK |
250 | .I key |
251 | exists, but \fIsize\fP is greater than the size | |
fea681da MK |
252 | of that segment. |
253 | .TP | |
254 | .B ENFILE | |
255 | .\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp() | |
e258766b | 256 | The system-wide limit on the total number of open files has been reached. |
fea681da MK |
257 | .TP |
258 | .B ENOENT | |
259 | No segment exists for the given \fIkey\fP, and | |
260 | .B IPC_CREAT | |
261 | was not specified. | |
262 | .TP | |
263 | .B ENOMEM | |
264 | No memory could be allocated for segment overhead. | |
265 | .TP | |
266 | .B ENOSPC | |
357cf3fe | 267 | All possible shared memory IDs have been taken |
fea681da MK |
268 | .RB ( SHMMNI ), |
269 | or allocating a segment of the requested | |
270 | .I size | |
271 | would cause the system to exceed the system-wide limit on shared memory | |
272 | .RB ( SHMALL ). | |
eb57338f MK |
273 | .TP |
274 | .B EPERM | |
275 | The | |
276 | .B SHM_HUGETLB | |
277 | flag was specified, but the caller was not privileged (did not have the | |
278 | .B CAP_IPC_LOCK | |
279 | capability). | |
47297adb | 280 | .SH CONFORMING TO |
6131817b | 281 | POSIX.1-2001, POSIX.1-2008, SVr4. |
a1d5f77c | 282 | .\" SVr4 documents an additional error condition EEXIST. |
efeece04 | 283 | .PP |
a1d5f77c | 284 | .B SHM_HUGETLB |
53b81588 MK |
285 | and |
286 | .B SHM_NORESERVE | |
287 | are Linux extensions. | |
fea681da | 288 | .SH NOTES |
f6652463 MK |
289 | The inclusion of |
290 | .I <sys/types.h> | |
291 | and | |
292 | .I <sys/ipc.h> | |
293 | isn't required on Linux or by any version of POSIX. | |
294 | However, | |
295 | some old implementations required the inclusion of these header files, | |
296 | and the SVID also documented their inclusion. | |
297 | Applications intended to be portable to such old systems may need | |
298 | to include these header files. | |
299 | .\" Like Linux, the FreeBSD man pages still document | |
300 | .\" the inclusion of these header files. | |
efeece04 | 301 | .PP |
fea681da MK |
302 | .B IPC_PRIVATE |
303 | isn't a flag field but a | |
c952e226 | 304 | .I key_t |
fea681da MK |
305 | type. |
306 | If this special value is used for | |
307 | .IR key , | |
ec64ab7f | 308 | the system call ignores all but the least significant 9 bits of |
fea681da | 309 | .I shmflg |
ec64ab7f | 310 | and creates a new shared memory segment. |
72c68b6a MK |
311 | .\" |
312 | .SS Shared memory limits | |
540036b2 | 313 | The following limits on shared memory segment resources affect the |
c952e226 | 314 | .BR shmget () |
fea681da | 315 | call: |
89b3c6b8 | 316 | .TP |
fea681da | 317 | .B SHMALL |
24ade49d MK |
318 | System-wide limit on the total amount of shared memory, |
319 | measured in units of the system page size. | |
efeece04 | 320 | .IP |
9a413675 DB |
321 | On Linux, this limit can be read and modified via |
322 | .IR /proc/sys/kernel/shmall . | |
562ac2f2 MK |
323 | Since Linux 3.16, |
324 | .\" commit 060028bac94bf60a65415d1d55a359c3a17d5c31 | |
9a413675 | 325 | the default value for this limit is: |
efeece04 | 326 | .IP |
9a413675 | 327 | ULONG_MAX - 2^24 |
efeece04 | 328 | .IP |
9a413675 DB |
329 | The effect of this value |
330 | (which is suitable for both 32-bit and 64-bit systems) | |
331 | is to impose no limitation on allocations. | |
332 | This value, rather than | |
333 | .BR ULONG_MAX , | |
334 | was chosen as the default to prevent some cases where historical | |
335 | applications simply raised the existing limit without first checking | |
336 | its current value. | |
337 | Such applications would cause the value to overflow if the limit was set at | |
338 | .BR ULONG_MAX . | |
efeece04 | 339 | .IP |
f037b098 | 340 | From Linux 2.4 up to Linux 3.15, |
d4bf702f | 341 | the default value for this limit was: |
efeece04 | 342 | .IP |
e6a38ea6 | 343 | SHMMAX / PAGE_SIZE * (SHMMNI / 16) |
efeece04 | 344 | .IP |
23c95909 MS |
345 | If |
346 | .B SHMMAX | |
347 | and | |
348 | .B SHMMNI | |
d4bf702f | 349 | were not modified, then multiplying the result of this formula |
c4b7e5ac | 350 | by the page size (to get a value in bytes) yielded a value of 8\ GB |
d4bf702f | 351 | as the limit on the total memory used by all shared memory segments. |
fea681da MK |
352 | .TP |
353 | .B SHMMAX | |
c00811f3 | 354 | Maximum size in bytes for a shared memory segment. |
efeece04 | 355 | .IP |
9a413675 DB |
356 | On Linux, this limit can be read and modified via |
357 | .IR /proc/sys/kernel/shmmax . | |
562ac2f2 MK |
358 | Since Linux 3.16, |
359 | .\" commit 060028bac94bf60a65415d1d55a359c3a17d5c31 | |
9a413675 | 360 | the default value for this limit is: |
efeece04 | 361 | .IP |
9a413675 | 362 | ULONG_MAX - 2^24 |
efeece04 | 363 | .IP |
9a413675 DB |
364 | The effect of this value |
365 | (which is suitable for both 32-bit and 64-bit systems) | |
366 | is to impose no limitation on allocations. | |
367 | See the description of | |
368 | .BR SHMALL | |
369 | for a discussion of why this default value (rather than | |
370 | .BR ULONG_MAX ) | |
371 | is used. | |
efeece04 | 372 | .IP |
f037b098 | 373 | From Linux 2.2 up to Linux 3.15, the default value of |
ee8655b5 | 374 | this limit was 0x2000000 (32\ MB). |
efeece04 | 375 | .IP |
1fabbf12 | 376 | Because it is not possible to map just part of a shared memory segment, |
e5cceccf | 377 | the amount of virtual memory places another limit on the maximum size of a |
1fabbf12 MK |
378 | usable segment: |
379 | for example, on i386 the largest segments that can be mapped have a | |
9ea5bc66 | 380 | size of around 2.8\ GB, and on x86-64 the limit is around 127 TB. |
fea681da MK |
381 | .TP |
382 | .B SHMMIN | |
383 | Minimum size in bytes for a shared memory segment: implementation | |
384 | dependent (currently 1 byte, though | |
385 | .B PAGE_SIZE | |
386 | is the effective minimum size). | |
387 | .TP | |
388 | .B SHMMNI | |
ab99b254 | 389 | System-wide limit on the number of shared memory segments. |
098c6998 MK |
390 | In Linux 2.2, the default value for this limit was 128; |
391 | since Linux 2.4, the default value is 4096. | |
efeece04 | 392 | .IP |
8ab18f6c MK |
393 | On Linux, this limit can be read and modified via |
394 | .IR /proc/sys/kernel/shmmni . | |
ed978af2 | 395 | .\" Kernels between 2.4.x and 2.6.8 had an off-by-one error that meant |
cd31a0d6 | 396 | .\" that we could create one more segment than SHMMNI -- MTK |
c952e226 | 397 | .\" This /proc file is not available in Linux 2.2 and earlier -- MTK |
fea681da | 398 | .PP |
5b55dde2 | 399 | The implementation has no specific limits for the per-process maximum |
fea681da MK |
400 | number of shared memory segments |
401 | .RB ( SHMSEG ). | |
c634028a | 402 | .SS Linux notes |
2ddef207 | 403 | Until version 2.3.30, Linux would return |
0daa9e92 | 404 | .B EIDRM |
2f0af33b | 405 | for a |
4fb31341 MK |
406 | .BR shmget () |
407 | on a shared memory segment scheduled for deletion. | |
fea681da | 408 | .SH BUGS |
2f0af33b MK |
409 | The name choice |
410 | .B IPC_PRIVATE | |
9091595d MK |
411 | was perhaps unfortunate, |
412 | .B IPC_NEW | |
fea681da | 413 | would more clearly show its function. |
47297adb | 414 | .SH SEE ALSO |
c4d76cd9 | 415 | .BR memfd_create (2), |
fea681da MK |
416 | .BR shmat (2), |
417 | .BR shmctl (2), | |
418 | .BR shmdt (2), | |
419 | .BR ftok (3), | |
92243659 | 420 | .BR capabilities (7), |
f93af9c6 | 421 | .BR shm_overview (7), |
2c5e151c | 422 | .BR svipc (7) |