]>
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 | .\" |
716c8c3f | 38 | .TH SHMGET 2 2013-04-19 "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 MK |
45 | .B #include <sys/shm.h> |
46 | .sp | |
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 () |
47f065d6 | 51 | returns the identifier of the System V shared memory segment |
fea681da MK |
52 | associated with the value of the argument |
53 | .IR key . | |
54 | A new shared memory segment, with size equal to the value of | |
55 | .I size | |
56 | rounded up to a multiple of | |
57 | .BR PAGE_SIZE , | |
58 | is created if | |
59 | .I key | |
60 | has the value | |
61 | .B IPC_PRIVATE | |
62 | or | |
63 | .I key | |
64 | isn't | |
65 | .BR IPC_PRIVATE , | |
66 | no shared memory segment corresponding to | |
0daa9e92 | 67 | .I key |
fea681da MK |
68 | exists, and |
69 | .B IPC_CREAT | |
c952e226 MK |
70 | is specified in |
71 | .IR shmflg . | |
72 | .PP | |
73 | If | |
fea681da | 74 | .I shmflg |
c952e226 MK |
75 | specifies both |
76 | .B IPC_CREAT | |
77 | and | |
78 | .B IPC_EXCL | |
79 | and a shared memory segment already exists for | |
80 | .IR key , | |
81 | then | |
82 | .BR shmget () | |
c13182ef | 83 | fails with |
c952e226 MK |
84 | .I errno |
85 | set to | |
86 | .BR EEXIST . | |
c13182ef | 87 | (This is analogous to the effect of the combination |
c952e226 MK |
88 | .B O_CREAT | O_EXCL |
89 | for | |
90 | .BR open (2).) | |
fea681da MK |
91 | .PP |
92 | The value | |
93 | .I shmflg | |
94 | is composed of: | |
95 | .TP 12 | |
96 | .B IPC_CREAT | |
c13182ef MK |
97 | to create a new segment. |
98 | If this flag is not used, then | |
c952e226 | 99 | .BR shmget () |
c13182ef | 100 | will find the segment associated with \fIkey\fP and check to see if |
fea681da MK |
101 | the user has permission to access the segment. |
102 | .TP | |
103 | .B IPC_EXCL | |
c13182ef | 104 | used with \fBIPC_CREAT\fP to ensure failure if the segment already exists. |
fea681da | 105 | .TP |
c13182ef | 106 | .I mode_flags |
c952e226 | 107 | (least significant 9 bits) |
fea681da | 108 | specifying the permissions granted to the owner, group, and world. |
c952e226 MK |
109 | These bits have the same format, and the same |
110 | meaning, as the | |
111 | .I mode | |
112 | argument of | |
113 | .BR open (2). | |
fea681da | 114 | Presently, the execute permissions are not used by the system. |
eb57338f | 115 | .TP |
32047971 | 116 | .BR SHM_HUGETLB " (since Linux 2.6)" |
c13182ef | 117 | Allocate the segment using "huge pages." |
66a9882e | 118 | See the Linux kernel source file |
eb57338f MK |
119 | .I Documentation/vm/hugetlbpage.txt |
120 | for further information. | |
32047971 MK |
121 | .TP |
122 | .BR SHM_NORESERVE " (since Linux 2.6.15)" | |
123 | This flag serves the same purpose as the | |
124 | .BR mmap (2) | |
125 | .B MAP_NORESERVE | |
126 | flag. | |
c13182ef | 127 | Do not reserve swap space for this segment. |
32047971 MK |
128 | When swap space is reserved, one has the guarantee |
129 | that it is possible to modify the segment. | |
8bd58774 MK |
130 | When swap space is not reserved one might get |
131 | .B SIGSEGV | |
132 | upon a write | |
32047971 MK |
133 | if no physical memory is available. |
134 | See also the discussion of the file | |
135 | .I /proc/sys/vm/overcommit_memory | |
c13182ef | 136 | in |
defcceb3 | 137 | .BR proc (5). |
32047971 MK |
138 | .\" As at 2.6.17-rc2, this flag has no effect if SHM_HUGETLB was also |
139 | .\" specified. | |
fea681da | 140 | .PP |
6319e935 | 141 | When a new shared memory segment is created, |
d9bfdb9c | 142 | its contents are initialized to zero values, and |
6319e935 | 143 | its associated data structure, |
fea681da | 144 | .I shmid_ds |
c952e226 | 145 | (see |
6319e935 | 146 | .BR shmctl (2)), |
d9bfdb9c | 147 | is initialized as follows: |
fea681da | 148 | .IP |
c952e226 | 149 | .I shm_perm.cuid |
fea681da | 150 | and |
c952e226 | 151 | .I shm_perm.uid |
499d62f2 | 152 | are set to the effective user ID of the calling process. |
fea681da | 153 | .IP |
c952e226 | 154 | .I shm_perm.cgid |
fea681da | 155 | and |
c952e226 | 156 | .I shm_perm.gid |
499d62f2 | 157 | are set to the effective group ID of the calling process. |
fea681da | 158 | .IP |
c952e226 MK |
159 | The least significant 9 bits of |
160 | .I shm_perm.mode | |
161 | are set to the least significant 9 bit of | |
fea681da MK |
162 | .IR shmflg . |
163 | .IP | |
c952e226 | 164 | .I shm_segsz |
fea681da MK |
165 | is set to the value of |
166 | .IR size . | |
167 | .IP | |
c952e226 MK |
168 | .IR shm_lpid , |
169 | .IR shm_nattch , | |
a797afac | 170 | .IR shm_atime , |
fea681da | 171 | and |
c952e226 MK |
172 | .I shm_dtime |
173 | are set to 0. | |
fea681da | 174 | .IP |
c952e226 | 175 | .I shm_ctime |
fea681da MK |
176 | is set to the current time. |
177 | .PP | |
c952e226 | 178 | If the shared memory segment already exists, the permissions are |
fea681da | 179 | verified, and a check is made to see if it is marked for destruction. |
47297adb | 180 | .SH RETURN VALUE |
716c8c3f | 181 | On success, a valid shared memory identifier is returned. |
0bca57f3 | 182 | On error, \-1 is returned, and |
716c8c3f MK |
183 | .I errno |
184 | is set to indicate the error. | |
fea681da MK |
185 | .SH ERRORS |
186 | On failure, | |
c952e226 | 187 | .I errno |
fea681da | 188 | is set to one of the following: |
89b3c6b8 | 189 | .TP |
fea681da | 190 | .B EACCES |
c13182ef | 191 | The user does not have permission to access the |
fea681da MK |
192 | shared memory segment, and does not have the |
193 | .B CAP_IPC_OWNER | |
194 | capability. | |
195 | .TP | |
196 | .B EEXIST | |
197 | .B IPC_CREAT | IPC_EXCL | |
198 | was specified and the segment exists. | |
199 | .TP | |
fea681da MK |
200 | .B EINVAL |
201 | A new segment was to be created and \fIsize\fP < \fBSHMMIN\fP | |
202 | or \fIsize\fP > \fBSHMMAX\fP, or no new segment was to be created, | |
203 | a segment with given key existed, but \fIsize\fP is greater than the size | |
204 | of that segment. | |
205 | .TP | |
206 | .B ENFILE | |
207 | .\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp() | |
208 | The system limit on the total number of open files has been reached. | |
209 | .TP | |
210 | .B ENOENT | |
211 | No segment exists for the given \fIkey\fP, and | |
212 | .B IPC_CREAT | |
213 | was not specified. | |
214 | .TP | |
215 | .B ENOMEM | |
216 | No memory could be allocated for segment overhead. | |
217 | .TP | |
218 | .B ENOSPC | |
357cf3fe | 219 | All possible shared memory IDs have been taken |
fea681da MK |
220 | .RB ( SHMMNI ), |
221 | or allocating a segment of the requested | |
222 | .I size | |
223 | would cause the system to exceed the system-wide limit on shared memory | |
224 | .RB ( SHMALL ). | |
eb57338f MK |
225 | .TP |
226 | .B EPERM | |
227 | The | |
228 | .B SHM_HUGETLB | |
229 | flag was specified, but the caller was not privileged (did not have the | |
230 | .B CAP_IPC_LOCK | |
231 | capability). | |
47297adb | 232 | .SH CONFORMING TO |
a1d5f77c MK |
233 | SVr4, POSIX.1-2001. |
234 | .\" SVr4 documents an additional error condition EEXIST. | |
235 | ||
236 | .B SHM_HUGETLB | |
d603cc27 | 237 | is a nonportable Linux extension. |
fea681da | 238 | .SH NOTES |
f6652463 MK |
239 | The inclusion of |
240 | .I <sys/types.h> | |
241 | and | |
242 | .I <sys/ipc.h> | |
243 | isn't required on Linux or by any version of POSIX. | |
244 | However, | |
245 | some old implementations required the inclusion of these header files, | |
246 | and the SVID also documented their inclusion. | |
247 | Applications intended to be portable to such old systems may need | |
248 | to include these header files. | |
249 | .\" Like Linux, the FreeBSD man pages still document | |
250 | .\" the inclusion of these header files. | |
251 | ||
fea681da MK |
252 | .B IPC_PRIVATE |
253 | isn't a flag field but a | |
c952e226 | 254 | .I key_t |
fea681da MK |
255 | type. |
256 | If this special value is used for | |
257 | .IR key , | |
c952e226 | 258 | the system call ignores everything but the least significant 9 bits of |
fea681da MK |
259 | .I shmflg |
260 | and creates a new shared memory segment (on success). | |
261 | .PP | |
540036b2 | 262 | The following limits on shared memory segment resources affect the |
c952e226 | 263 | .BR shmget () |
fea681da | 264 | call: |
89b3c6b8 | 265 | .TP |
fea681da | 266 | .B SHMALL |
c952e226 MK |
267 | System wide maximum of shared memory pages |
268 | (on Linux, this limit can be read and modified via | |
269 | .IR /proc/sys/kernel/shmall ). | |
fea681da MK |
270 | .TP |
271 | .B SHMMAX | |
c952e226 MK |
272 | Maximum size in bytes for a shared memory segment: policy dependent |
273 | (on Linux, this limit can be read and modified via | |
274 | .IR /proc/sys/kernel/shmmax ). | |
fea681da MK |
275 | .TP |
276 | .B SHMMIN | |
277 | Minimum size in bytes for a shared memory segment: implementation | |
278 | dependent (currently 1 byte, though | |
279 | .B PAGE_SIZE | |
280 | is the effective minimum size). | |
281 | .TP | |
282 | .B SHMMNI | |
283 | System wide maximum number of shared memory segments: implementation | |
c952e226 MK |
284 | dependent (currently 4096, was 128 before Linux 2.3.99; |
285 | on Linux, this limit can be read and modified via | |
286 | .IR /proc/sys/kernel/shmmni ). | |
ed978af2 | 287 | .\" Kernels between 2.4.x and 2.6.8 had an off-by-one error that meant |
cd31a0d6 | 288 | .\" that we could create one more segment than SHMMNI -- MTK |
c952e226 | 289 | .\" This /proc file is not available in Linux 2.2 and earlier -- MTK |
fea681da | 290 | .PP |
5b55dde2 | 291 | The implementation has no specific limits for the per-process maximum |
fea681da MK |
292 | number of shared memory segments |
293 | .RB ( SHMSEG ). | |
c634028a | 294 | .SS Linux notes |
2f0af33b | 295 | Until version 2.3.30 Linux would return |
0daa9e92 | 296 | .B EIDRM |
2f0af33b | 297 | for a |
4fb31341 MK |
298 | .BR shmget () |
299 | on a shared memory segment scheduled for deletion. | |
fea681da | 300 | .SH BUGS |
2f0af33b MK |
301 | The name choice |
302 | .B IPC_PRIVATE | |
9091595d MK |
303 | was perhaps unfortunate, |
304 | .B IPC_NEW | |
fea681da | 305 | would more clearly show its function. |
47297adb | 306 | .SH SEE ALSO |
fea681da MK |
307 | .BR shmat (2), |
308 | .BR shmctl (2), | |
309 | .BR shmdt (2), | |
310 | .BR ftok (3), | |
92243659 | 311 | .BR capabilities (7), |
f93af9c6 | 312 | .BR shm_overview (7), |
2c5e151c | 313 | .BR svipc (7) |