]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) |
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. | |
f998edca | 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. | |
f998edca | 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 Sun Nov 28 17:06:19 1993, Rik Faith (faith@cs.unc.edu) | |
26 | .\" with material from Luigi P. Bai (lpb@softint.com) | |
27 | .\" Portions Copyright 1993 Luigi P. Bai | |
28 | .\" Modified Tue Oct 22 22:04:23 1996 by Eric S. Raymond <esr@thyrsus.com> | |
c11b1abf MK |
29 | .\" Modified, 5 Jan 2002, Michael Kerrisk <mtk.manpages@gmail.com> |
30 | .\" Modified, 19 Sep 2002, Michael Kerrisk <mtk.manpages@gmail.com> | |
fea681da | 31 | .\" Added SHM_REMAP flag description |
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> |
f998edca MK |
35 | .\" Language and formatting clean-ups |
36 | .\" Changed wording and placement of sentence regarding attachment | |
37 | .\" of segments marked for destruction | |
fea681da | 38 | .\" |
be5e7098 | 39 | .\" FIXME . Add an example program to this page. |
4aaf987e | 40 | .\" |
63121bd4 | 41 | .TH SHMOP 2 2019-08-02 "Linux" "Linux Programmer's Manual" |
fea681da | 42 | .SH NAME |
47f065d6 | 43 | shmat, shmdt \- System V shared memory operations |
fea681da MK |
44 | .SH SYNOPSIS |
45 | .nf | |
d314dbfd MK |
46 | .B #include <sys/types.h> |
47 | .B #include <sys/shm.h> | |
dbfe9c70 | 48 | .PP |
34e8ac03 | 49 | .BI "void *shmat(int " shmid ", const void *" shmaddr ", int " shmflg ); |
dbfe9c70 | 50 | .PP |
fea681da | 51 | .BI "int shmdt(const void *" shmaddr ); |
34e8ac03 | 52 | .fi |
fea681da | 53 | .SH DESCRIPTION |
587c51d1 | 54 | .SS shmat() |
f998edca | 55 | .BR shmat () |
efbfd7ec | 56 | attaches the System\ V shared memory segment identified by |
f998edca | 57 | .I shmid |
fea681da MK |
58 | to the address space of the calling process. |
59 | The attaching address is specified by | |
60 | .I shmaddr | |
61 | with one of the following criteria: | |
8b0545b4 | 62 | .IP * 3 |
fea681da MK |
63 | If |
64 | .I shmaddr | |
8478ee02 | 65 | is NULL, |
fe03cbd8 | 66 | the system chooses a suitable (unused) page-aligned address to attach |
fea681da | 67 | the segment. |
8b0545b4 | 68 | .IP * |
fea681da MK |
69 | If |
70 | .I shmaddr | |
8478ee02 | 71 | isn't NULL |
fea681da MK |
72 | and |
73 | .B SHM_RND | |
f998edca | 74 | is specified in |
fea681da MK |
75 | .IR shmflg , |
76 | the attach occurs at the address equal to | |
77 | .I shmaddr | |
78 | rounded down to the nearest multiple of | |
79 | .BR SHMLBA . | |
8b0545b4 MK |
80 | .IP * |
81 | Otherwise, | |
fea681da MK |
82 | .I shmaddr |
83 | must be a page-aligned address at which the attach occurs. | |
84 | .PP | |
8378b115 | 85 | In addition to |
1ba7cc71 | 86 | .BR SHM_RND , |
8378b115 MK |
87 | the following flags may be specified in the |
88 | .I shmflg | |
89 | bit-mask argument: | |
90 | .TP | |
4aaf987e MK |
91 | .BR SHM_EXEC " (Linux-specific; since Linux 2.6.9)" |
92 | Allow the contents of the segment to be executed. | |
93 | The caller must have execute permission on the segment. | |
94 | .TP | |
8378b115 | 95 | .BR SHM_RDONLY |
bddaba77 | 96 | Attach the segment for read-only access. |
8378b115 MK |
97 | The process must have read permission for the segment. |
98 | If this flag is not specified, | |
99 | the segment is attached for read and write access, | |
fea681da MK |
100 | and the process must have read and write permission for the segment. |
101 | There is no notion of a write-only shared memory segment. | |
8378b115 | 102 | .TP |
e4e425b3 MK |
103 | .BR SHM_REMAP " (Linux-specific)" |
104 | This flag specifies | |
8378b115 | 105 | that the mapping of the segment should replace |
f998edca | 106 | any existing mapping in the range starting at |
fea681da MK |
107 | .I shmaddr |
108 | and continuing for the size of the segment. | |
33c90885 | 109 | (Normally, an |
fea681da MK |
110 | .B EINVAL |
111 | error would result if a mapping already exists in this address range.) | |
112 | In this case, | |
113 | .I shmaddr | |
8478ee02 | 114 | must not be NULL. |
fea681da MK |
115 | .PP |
116 | The | |
f998edca | 117 | .BR brk (2) |
fea681da MK |
118 | value of the calling process is not altered by the attach. |
119 | The segment will automatically be detached at process exit. | |
120 | The same segment may be attached as a read and as a read-write | |
121 | one, and more than once, in the process's address space. | |
122 | .PP | |
f998edca MK |
123 | A successful |
124 | .BR shmat () | |
125 | call updates the members of the | |
66ee0c7e | 126 | .I shmid_ds |
f998edca MK |
127 | structure (see |
128 | .BR shmctl (2)) | |
129 | associated with the shared memory segment as follows: | |
fea681da | 130 | .IP |
f998edca | 131 | .I shm_atime |
fea681da MK |
132 | is set to the current time. |
133 | .IP | |
f998edca | 134 | .I shm_lpid |
fea681da MK |
135 | is set to the process-ID of the calling process. |
136 | .IP | |
f998edca | 137 | .I shm_nattch |
fea681da | 138 | is incremented by one. |
587c51d1 MK |
139 | .\" |
140 | .SS shmdt() | |
f998edca | 141 | .BR shmdt () |
fea681da MK |
142 | detaches the shared memory segment located at the address specified by |
143 | .I shmaddr | |
144 | from the address space of the calling process. | |
2706f299 | 145 | The to-be-detached segment must be currently |
fea681da MK |
146 | attached with |
147 | .I shmaddr | |
f998edca MK |
148 | equal to the value returned by the attaching |
149 | .BR shmat () | |
fea681da MK |
150 | call. |
151 | .PP | |
152 | On a successful | |
f998edca | 153 | .BR shmdt () |
0bf534a9 | 154 | call, the system updates the members of the |
f998edca | 155 | .I shmid_ds |
fea681da MK |
156 | structure associated with the shared memory segment as follows: |
157 | .IP | |
f998edca | 158 | .I shm_dtime |
fea681da MK |
159 | is set to the current time. |
160 | .IP | |
f998edca | 161 | .I shm_lpid |
fea681da MK |
162 | is set to the process-ID of the calling process. |
163 | .IP | |
f998edca | 164 | .I shm_nattch |
fea681da MK |
165 | is decremented by one. |
166 | If it becomes 0 and the segment is marked for deletion, | |
167 | the segment is deleted. | |
47297adb | 168 | .SH RETURN VALUE |
0bf534a9 | 169 | On success, |
f998edca | 170 | .BR shmat () |
0bf534a9 | 171 | returns the address of the attached shared memory segment; on error, |
009df872 | 172 | .I (void\ *)\ \-1 |
eeabb34e MK |
173 | is returned, and |
174 | .I errno | |
175 | is set to indicate the cause of the error. | |
efeece04 | 176 | .PP |
0bf534a9 | 177 | On success, |
f998edca | 178 | .BR shmdt () |
eeabb34e | 179 | returns 0; on error \-1 is returned, and |
fea681da | 180 | .I errno |
eeabb34e | 181 | is set to indicate the cause of the error. |
fea681da MK |
182 | .SH ERRORS |
183 | When | |
f998edca | 184 | .BR shmat () |
fea681da MK |
185 | fails, |
186 | .I errno | |
187 | is set to one of the following: | |
188 | .TP | |
189 | .B EACCES | |
190 | The calling process does not have the required permissions for | |
191 | the requested attach type, and does not have the | |
192 | .B CAP_IPC_OWNER | |
3294109d | 193 | capability in the user namespace that governs its IPC namespace. |
fea681da | 194 | .TP |
89b5016d MK |
195 | .B EIDRM |
196 | \fIshmid\fP points to a removed identifier. | |
197 | .TP | |
fea681da MK |
198 | .B EINVAL |
199 | Invalid | |
200 | .I shmid | |
201 | value, unaligned (i.e., not page-aligned and \fBSHM_RND\fP was not | |
202 | specified) or invalid | |
203 | .I shmaddr | |
228688f9 MK |
204 | value, or can't attach segment at |
205 | .IR shmaddr , | |
f998edca | 206 | or |
fea681da MK |
207 | .B SHM_REMAP |
208 | was specified and | |
209 | .I shmaddr | |
8478ee02 | 210 | was NULL. |
fea681da MK |
211 | .TP |
212 | .B ENOMEM | |
213 | Could not allocate memory for the descriptor or for the page tables. | |
214 | .PP | |
9aad1caa | 215 | When |
f998edca | 216 | .BR shmdt () |
9aad1caa | 217 | fails, |
fea681da | 218 | .I errno |
9aad1caa MK |
219 | is set as follows: |
220 | .TP | |
221 | .B EINVAL | |
222 | There is no shared memory segment attached at | |
c13182ef | 223 | .IR shmaddr ; |
9aad1caa MK |
224 | or, |
225 | .\" The following since 2.6.17-rc1: | |
226 | .I shmaddr | |
227 | is not aligned on a page boundary. | |
47297adb | 228 | .SH CONFORMING TO |
2bc6fb60 | 229 | POSIX.1-2001, POSIX.1-2008, SVr4. |
a1d5f77c | 230 | .\" SVr4 documents an additional error condition EMFILE. |
efeece04 | 231 | .PP |
0bf534a9 | 232 | In SVID 3 (or perhaps earlier), |
a1d5f77c | 233 | the type of the \fIshmaddr\fP argument was changed from |
5049da5b | 234 | .I "char\ *" |
a1d5f77c | 235 | into |
5049da5b | 236 | .IR "const void\ *" , |
a1d5f77c MK |
237 | and the returned type of |
238 | .BR shmat () | |
239 | from | |
5049da5b | 240 | .I "char\ *" |
a1d5f77c | 241 | into |
5049da5b | 242 | .IR "void\ *" . |
fea681da | 243 | .SH NOTES |
11adc9b9 MK |
244 | .PP |
245 | After a | |
246 | .BR fork (2), | |
247 | the child inherits the attached shared memory segments. | |
efeece04 | 248 | .PP |
11adc9b9 MK |
249 | After an |
250 | .BR execve (2), | |
251 | all attached shared memory segments are detached from the process. | |
efeece04 | 252 | .PP |
11adc9b9 MK |
253 | Upon |
254 | .BR _exit (2), | |
255 | all attached shared memory segments are detached from the process. | |
efeece04 | 256 | .PP |
fea681da | 257 | Using |
f998edca | 258 | .BR shmat () |
fea681da MK |
259 | with |
260 | .I shmaddr | |
8478ee02 | 261 | equal to NULL |
fea681da MK |
262 | is the preferred, portable way of attaching a shared memory segment. |
263 | Be aware that the shared memory segment attached in this way | |
264 | may be attached at different addresses in different processes. | |
265 | Therefore, any pointers maintained within the shared memory must be | |
266 | made relative (typically to the starting address of the segment), | |
267 | rather than absolute. | |
f998edca MK |
268 | .PP |
269 | On Linux, it is possible to attach a shared memory segment even if it | |
a6a99a4c | 270 | is already marked to be deleted. |
2bc6fb60 | 271 | However, POSIX.1 does not specify this behavior and |
f998edca | 272 | many other implementations do not support it. |
dd3568a1 | 273 | .PP |
f998edca MK |
274 | The following system parameter affects |
275 | .BR shmat (): | |
89b3c6b8 | 276 | .TP |
fea681da MK |
277 | .B SHMLBA |
278 | Segment low boundary address multiple. | |
2d2c6782 MK |
279 | When explicitly specifying an attach address in a call to |
280 | .BR shmat (), | |
281 | the caller should ensure that the address is a multiple of this value. | |
282 | This is necessary on some architectures, | |
283 | in order either to ensure good CPU cache performance or to ensure that | |
284 | different attaches of the same segment have consistent views | |
285 | within the CPU cache. | |
b7d1c645 | 286 | .B SHMLBA |
b739c378 MK |
287 | is normally some multiple of the system page size. |
288 | (On many Linux architectures, | |
289 | .B SHMLBA | |
290 | is the same as the system page size.) | |
fea681da | 291 | .PP |
964e1ae0 | 292 | The implementation places no intrinsic per-process limit on the |
fea681da MK |
293 | number of shared memory segments |
294 | .RB ( SHMSEG ). | |
47297adb | 295 | .SH SEE ALSO |
fea681da MK |
296 | .BR brk (2), |
297 | .BR mmap (2), | |
298 | .BR shmctl (2), | |
299 | .BR shmget (2), | |
92243659 | 300 | .BR capabilities (7), |
f93af9c6 | 301 | .BR shm_overview (7), |
343cdc5a | 302 | .BR sysvipc (7) |