]>
Commit | Line | Data |
---|---|---|
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 MK |
35 | .\" |
36 | .TH SHMGET 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" | |
37 | .SH NAME | |
38 | shmget \- 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 | |
45 | .BI "int shmget(key_t " key ", int " size ", int " shmflg ); | |
46 | .ad b | |
47 | .SH DESCRIPTION | |
c952e226 | 48 | .BR shmget () |
fea681da MK |
49 | returns the identifier of the shared memory segment |
50 | associated with the value of the argument | |
51 | .IR key . | |
52 | A new shared memory segment, with size equal to the value of | |
53 | .I size | |
54 | rounded up to a multiple of | |
55 | .BR PAGE_SIZE , | |
56 | is created if | |
57 | .I key | |
58 | has the value | |
59 | .B IPC_PRIVATE | |
60 | or | |
61 | .I key | |
62 | isn't | |
63 | .BR IPC_PRIVATE , | |
64 | no shared memory segment corresponding to | |
65 | .IR key | |
66 | exists, and | |
67 | .B IPC_CREAT | |
c952e226 MK |
68 | is specified in |
69 | .IR shmflg . | |
70 | .PP | |
71 | If | |
fea681da | 72 | .I shmflg |
c952e226 MK |
73 | specifies both |
74 | .B IPC_CREAT | |
75 | and | |
76 | .B IPC_EXCL | |
77 | and a shared memory segment already exists for | |
78 | .IR key , | |
79 | then | |
80 | .BR shmget () | |
81 | fails with | |
82 | .I errno | |
83 | set to | |
84 | .BR EEXIST . | |
85 | (This is analogous to the effect of the combination | |
86 | .B O_CREAT | O_EXCL | |
87 | for | |
88 | .BR open (2).) | |
fea681da MK |
89 | .PP |
90 | The value | |
91 | .I shmflg | |
92 | is composed of: | |
93 | .TP 12 | |
94 | .B IPC_CREAT | |
95 | to create a new segment. If this flag is not used, then | |
c952e226 | 96 | .BR shmget () |
fea681da MK |
97 | will find the segment associated with \fIkey\fP and check to see if |
98 | the user has permission to access the segment. | |
99 | .TP | |
100 | .B IPC_EXCL | |
101 | used 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 | 105 | specifying the permissions granted to the owner, group, and world. |
c952e226 MK |
106 | These bits have the same format, and the same |
107 | meaning, as the | |
108 | .I mode | |
109 | argument of | |
110 | .BR open (2). | |
fea681da MK |
111 | Presently, the execute permissions are not used by the system. |
112 | .\" FIXME -- document SHM_HUGETLB | |
113 | .PP | |
c952e226 MK |
114 | If a new shared memory segment is created, |
115 | then its associated data structure | |
fea681da | 116 | .I shmid_ds |
c952e226 MK |
117 | (see |
118 | .BR shmctl (2)) | |
119 | is initialised as follows: | |
fea681da | 120 | .IP |
c952e226 | 121 | .I shm_perm.cuid |
fea681da | 122 | and |
c952e226 | 123 | .I shm_perm.uid |
fea681da MK |
124 | are set to the effective user\-ID of the calling process. |
125 | .IP | |
c952e226 | 126 | .I shm_perm.cgid |
fea681da | 127 | and |
c952e226 | 128 | .I shm_perm.gid |
fea681da MK |
129 | are set to the effective group\-ID of the calling process. |
130 | .IP | |
c952e226 MK |
131 | The least significant 9 bits of |
132 | .I shm_perm.mode | |
133 | are set to the least significant 9 bit of | |
fea681da MK |
134 | .IR shmflg . |
135 | .IP | |
c952e226 | 136 | .I shm_segsz |
fea681da MK |
137 | is set to the value of |
138 | .IR size . | |
139 | .IP | |
c952e226 MK |
140 | .IR shm_lpid , |
141 | .IR shm_nattch , | |
142 | .I shm_atime | |
fea681da | 143 | and |
c952e226 MK |
144 | .I shm_dtime |
145 | are set to 0. | |
fea681da | 146 | .IP |
c952e226 | 147 | .I shm_ctime |
fea681da MK |
148 | is set to the current time. |
149 | .PP | |
c952e226 | 150 | If the shared memory segment already exists, the permissions are |
fea681da | 151 | verified, and a check is made to see if it is marked for destruction. |
fea681da MK |
152 | .SH "SYSTEM CALLS" |
153 | .TP | |
c952e226 | 154 | .BR fork () |
fea681da | 155 | After a |
c952e226 | 156 | .BR fork () |
fea681da MK |
157 | the child inherits the attached shared memory segments. |
158 | .TP | |
c952e226 | 159 | .BR exec () |
fea681da | 160 | After an |
c952e226 | 161 | .BR exec () |
fea681da MK |
162 | all attached shared memory segments are detached (not destroyed). |
163 | .TP | |
c952e226 | 164 | .BR exit () |
fea681da | 165 | Upon |
c952e226 | 166 | .BR exit () |
fea681da MK |
167 | all attached shared memory segments are detached (not destroyed). |
168 | .PP | |
169 | .SH "RETURN VALUE" | |
170 | A valid segment identifier, | |
171 | .IR shmid , | |
172 | is returned on success, \-1 on error. | |
173 | .SH ERRORS | |
174 | On failure, | |
c952e226 | 175 | .I errno |
fea681da MK |
176 | is set to one of the following: |
177 | .TP 12 | |
178 | .B EACCES | |
179 | The user does not have permission to access the | |
180 | shared memory segment, and does not have the | |
181 | .B CAP_IPC_OWNER | |
182 | capability. | |
183 | .TP | |
184 | .B EEXIST | |
185 | .B IPC_CREAT | IPC_EXCL | |
186 | was specified and the segment exists. | |
187 | .TP | |
188 | .\" FIXME -- SHM_HUGETLB requires CAP_IPC_LOCK, or the error EPERM | |
189 | .\" results | |
190 | .B EINVAL | |
191 | A new segment was to be created and \fIsize\fP < \fBSHMMIN\fP | |
192 | or \fIsize\fP > \fBSHMMAX\fP, or no new segment was to be created, | |
193 | a segment with given key existed, but \fIsize\fP is greater than the size | |
194 | of that segment. | |
195 | .TP | |
196 | .B ENFILE | |
197 | .\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp() | |
198 | The system limit on the total number of open files has been reached. | |
199 | .TP | |
200 | .B ENOENT | |
201 | No segment exists for the given \fIkey\fP, and | |
202 | .B IPC_CREAT | |
203 | was not specified. | |
204 | .TP | |
205 | .B ENOMEM | |
206 | No memory could be allocated for segment overhead. | |
207 | .TP | |
208 | .B ENOSPC | |
357cf3fe | 209 | All possible shared memory IDs have been taken |
fea681da MK |
210 | .RB ( SHMMNI ), |
211 | or allocating a segment of the requested | |
212 | .I size | |
213 | would cause the system to exceed the system-wide limit on shared memory | |
214 | .RB ( SHMALL ). | |
215 | .SH NOTES | |
216 | .B IPC_PRIVATE | |
217 | isn't a flag field but a | |
c952e226 | 218 | .I key_t |
fea681da MK |
219 | type. |
220 | If this special value is used for | |
221 | .IR key , | |
c952e226 | 222 | the system call ignores everything but the least significant 9 bits of |
fea681da MK |
223 | .I shmflg |
224 | and creates a new shared memory segment (on success). | |
225 | .PP | |
540036b2 | 226 | The following limits on shared memory segment resources affect the |
c952e226 | 227 | .BR shmget () |
fea681da MK |
228 | call: |
229 | .TP 11 | |
230 | .B SHMALL | |
c952e226 MK |
231 | System wide maximum of shared memory pages |
232 | (on Linux, this limit can be read and modified via | |
233 | .IR /proc/sys/kernel/shmall ). | |
fea681da MK |
234 | .TP |
235 | .B SHMMAX | |
c952e226 MK |
236 | Maximum size in bytes for a shared memory segment: policy dependent |
237 | (on Linux, this limit can be read and modified via | |
238 | .IR /proc/sys/kernel/shmmax ). | |
fea681da MK |
239 | .TP |
240 | .B SHMMIN | |
241 | Minimum size in bytes for a shared memory segment: implementation | |
242 | dependent (currently 1 byte, though | |
243 | .B PAGE_SIZE | |
244 | is the effective minimum size). | |
245 | .TP | |
246 | .B SHMMNI | |
247 | System wide maximum number of shared memory segments: implementation | |
c952e226 MK |
248 | dependent (currently 4096, was 128 before Linux 2.3.99; |
249 | on Linux, this limit can be read and modified via | |
250 | .IR /proc/sys/kernel/shmmni ). | |
251 | .\" This /proc file is not available in Linux 2.2 and earlier -- MTK | |
fea681da MK |
252 | .PP |
253 | The implementation has no specific limits for the per process maximum | |
254 | number of shared memory segments | |
255 | .RB ( SHMSEG ). | |
256 | .SH BUGS | |
257 | The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW | |
258 | would more clearly show its function. | |
259 | .SH "CONFORMING TO" | |
260 | SVr4, SVID. SVr4 documents an additional error condition EEXIST. | |
261 | Until version 2.3.30 Linux would return EIDRM for a | |
c952e226 | 262 | .BR shmget () |
fea681da MK |
263 | on a shared memory segment scheduled for deletion. |
264 | .SH "SEE ALSO" | |
265 | .BR shmat (2), | |
266 | .BR shmctl (2), | |
267 | .BR shmdt (2), | |
268 | .BR ftok (3), | |
269 | .BR ipc (5), | |
270 | .BR capabilities (7) |