]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) |
fc477423 | 2 | .\" and Copyright 2020 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
5 | .\" |
6 | .\" Modified Sun Nov 28 17:06:19 1993, Rik Faith (faith@cs.unc.edu) | |
7 | .\" with material from Luigi P. Bai (lpb@softint.com) | |
8 | .\" Portions Copyright 1993 Luigi P. Bai | |
9 | .\" Modified Tue Oct 22 22:04:23 1996 by Eric S. Raymond <esr@thyrsus.com> | |
c11b1abf MK |
10 | .\" Modified, 5 Jan 2002, Michael Kerrisk <mtk.manpages@gmail.com> |
11 | .\" Modified, 19 Sep 2002, Michael Kerrisk <mtk.manpages@gmail.com> | |
fea681da | 12 | .\" Added SHM_REMAP flag description |
c11b1abf | 13 | .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 14 | .\" Added notes on capability requirements |
c11b1abf | 15 | .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
f998edca MK |
16 | .\" Language and formatting clean-ups |
17 | .\" Changed wording and placement of sentence regarding attachment | |
18 | .\" of segments marked for destruction | |
fea681da | 19 | .\" |
45186a5d | 20 | .TH SHMOP 2 2021-03-22 "Linux man-pages (unreleased)" |
fea681da | 21 | .SH NAME |
47f065d6 | 22 | shmat, shmdt \- System V shared memory operations |
c58e86c4 AC |
23 | .SH LIBRARY |
24 | Standard C library | |
8fc3b2cf | 25 | .RI ( libc ", " \-lc ) |
fea681da MK |
26 | .SH SYNOPSIS |
27 | .nf | |
d314dbfd | 28 | .B #include <sys/shm.h> |
dbfe9c70 | 29 | .PP |
34e8ac03 | 30 | .BI "void *shmat(int " shmid ", const void *" shmaddr ", int " shmflg ); |
fea681da | 31 | .BI "int shmdt(const void *" shmaddr ); |
34e8ac03 | 32 | .fi |
fea681da | 33 | .SH DESCRIPTION |
587c51d1 | 34 | .SS shmat() |
f998edca | 35 | .BR shmat () |
efbfd7ec | 36 | attaches the System\ V shared memory segment identified by |
f998edca | 37 | .I shmid |
fea681da MK |
38 | to the address space of the calling process. |
39 | The attaching address is specified by | |
40 | .I shmaddr | |
41 | with one of the following criteria: | |
55f2c848 | 42 | .IP \(bu 2 |
fea681da MK |
43 | If |
44 | .I shmaddr | |
8478ee02 | 45 | is NULL, |
fe03cbd8 | 46 | the system chooses a suitable (unused) page-aligned address to attach |
fea681da | 47 | the segment. |
55f2c848 | 48 | .IP \(bu |
fea681da MK |
49 | If |
50 | .I shmaddr | |
8478ee02 | 51 | isn't NULL |
fea681da MK |
52 | and |
53 | .B SHM_RND | |
f998edca | 54 | is specified in |
fea681da MK |
55 | .IR shmflg , |
56 | the attach occurs at the address equal to | |
57 | .I shmaddr | |
58 | rounded down to the nearest multiple of | |
59 | .BR SHMLBA . | |
55f2c848 | 60 | .IP \(bu |
8b0545b4 | 61 | Otherwise, |
fea681da MK |
62 | .I shmaddr |
63 | must be a page-aligned address at which the attach occurs. | |
64 | .PP | |
8378b115 | 65 | In addition to |
1ba7cc71 | 66 | .BR SHM_RND , |
8378b115 MK |
67 | the following flags may be specified in the |
68 | .I shmflg | |
69 | bit-mask argument: | |
70 | .TP | |
4aaf987e MK |
71 | .BR SHM_EXEC " (Linux-specific; since Linux 2.6.9)" |
72 | Allow the contents of the segment to be executed. | |
73 | The caller must have execute permission on the segment. | |
74 | .TP | |
1ae6b2c7 | 75 | .B SHM_RDONLY |
bddaba77 | 76 | Attach the segment for read-only access. |
8378b115 MK |
77 | The process must have read permission for the segment. |
78 | If this flag is not specified, | |
79 | the segment is attached for read and write access, | |
fea681da MK |
80 | and the process must have read and write permission for the segment. |
81 | There is no notion of a write-only shared memory segment. | |
8378b115 | 82 | .TP |
e4e425b3 MK |
83 | .BR SHM_REMAP " (Linux-specific)" |
84 | This flag specifies | |
8378b115 | 85 | that the mapping of the segment should replace |
f998edca | 86 | any existing mapping in the range starting at |
fea681da MK |
87 | .I shmaddr |
88 | and continuing for the size of the segment. | |
33c90885 | 89 | (Normally, an |
fea681da MK |
90 | .B EINVAL |
91 | error would result if a mapping already exists in this address range.) | |
92 | In this case, | |
93 | .I shmaddr | |
8478ee02 | 94 | must not be NULL. |
fea681da MK |
95 | .PP |
96 | The | |
f998edca | 97 | .BR brk (2) |
fea681da MK |
98 | value of the calling process is not altered by the attach. |
99 | The segment will automatically be detached at process exit. | |
100 | The same segment may be attached as a read and as a read-write | |
101 | one, and more than once, in the process's address space. | |
102 | .PP | |
f998edca MK |
103 | A successful |
104 | .BR shmat () | |
105 | call updates the members of the | |
66ee0c7e | 106 | .I shmid_ds |
f998edca MK |
107 | structure (see |
108 | .BR shmctl (2)) | |
109 | associated with the shared memory segment as follows: | |
410ad573 | 110 | .IP \(bu 2 |
f998edca | 111 | .I shm_atime |
fea681da | 112 | is set to the current time. |
410ad573 | 113 | .IP \(bu |
f998edca | 114 | .I shm_lpid |
fea681da | 115 | is set to the process-ID of the calling process. |
410ad573 | 116 | .IP \(bu |
f998edca | 117 | .I shm_nattch |
fea681da | 118 | is incremented by one. |
587c51d1 MK |
119 | .\" |
120 | .SS shmdt() | |
f998edca | 121 | .BR shmdt () |
fea681da MK |
122 | detaches the shared memory segment located at the address specified by |
123 | .I shmaddr | |
124 | from the address space of the calling process. | |
2706f299 | 125 | The to-be-detached segment must be currently |
fea681da MK |
126 | attached with |
127 | .I shmaddr | |
f998edca MK |
128 | equal to the value returned by the attaching |
129 | .BR shmat () | |
fea681da MK |
130 | call. |
131 | .PP | |
132 | On a successful | |
f998edca | 133 | .BR shmdt () |
0bf534a9 | 134 | call, the system updates the members of the |
f998edca | 135 | .I shmid_ds |
fea681da | 136 | structure associated with the shared memory segment as follows: |
410ad573 | 137 | .IP \(bu 2 |
f998edca | 138 | .I shm_dtime |
fea681da | 139 | is set to the current time. |
410ad573 | 140 | .IP \(bu |
f998edca | 141 | .I shm_lpid |
fea681da | 142 | is set to the process-ID of the calling process. |
410ad573 | 143 | .IP \(bu |
f998edca | 144 | .I shm_nattch |
fea681da MK |
145 | is decremented by one. |
146 | If it becomes 0 and the segment is marked for deletion, | |
147 | the segment is deleted. | |
47297adb | 148 | .SH RETURN VALUE |
0bf534a9 | 149 | On success, |
f998edca | 150 | .BR shmat () |
0bf534a9 | 151 | returns the address of the attached shared memory segment; on error, |
009df872 | 152 | .I (void\ *)\ \-1 |
eeabb34e MK |
153 | is returned, and |
154 | .I errno | |
855d489a | 155 | is set to indicate the error. |
efeece04 | 156 | .PP |
0bf534a9 | 157 | On success, |
f998edca | 158 | .BR shmdt () |
eeabb34e | 159 | returns 0; on error \-1 is returned, and |
fea681da | 160 | .I errno |
855d489a | 161 | is set to indicate the error. |
fea681da | 162 | .SH ERRORS |
f998edca | 163 | .BR shmat () |
f2fa0558 | 164 | can fail with one of the following errors: |
fea681da MK |
165 | .TP |
166 | .B EACCES | |
167 | The calling process does not have the required permissions for | |
168 | the requested attach type, and does not have the | |
169 | .B CAP_IPC_OWNER | |
3294109d | 170 | capability in the user namespace that governs its IPC namespace. |
fea681da | 171 | .TP |
89b5016d MK |
172 | .B EIDRM |
173 | \fIshmid\fP points to a removed identifier. | |
174 | .TP | |
fea681da MK |
175 | .B EINVAL |
176 | Invalid | |
177 | .I shmid | |
178 | value, unaligned (i.e., not page-aligned and \fBSHM_RND\fP was not | |
179 | specified) or invalid | |
180 | .I shmaddr | |
228688f9 MK |
181 | value, or can't attach segment at |
182 | .IR shmaddr , | |
f998edca | 183 | or |
fea681da MK |
184 | .B SHM_REMAP |
185 | was specified and | |
186 | .I shmaddr | |
8478ee02 | 187 | was NULL. |
fea681da MK |
188 | .TP |
189 | .B ENOMEM | |
190 | Could not allocate memory for the descriptor or for the page tables. | |
191 | .PP | |
f998edca | 192 | .BR shmdt () |
f2fa0558 | 193 | can fail with one of the following errors: |
9aad1caa MK |
194 | .TP |
195 | .B EINVAL | |
196 | There is no shared memory segment attached at | |
c13182ef | 197 | .IR shmaddr ; |
9aad1caa MK |
198 | or, |
199 | .\" The following since 2.6.17-rc1: | |
200 | .I shmaddr | |
201 | is not aligned on a page boundary. | |
3113c7f3 | 202 | .SH STANDARDS |
2bc6fb60 | 203 | POSIX.1-2001, POSIX.1-2008, SVr4. |
a1d5f77c | 204 | .\" SVr4 documents an additional error condition EMFILE. |
efeece04 | 205 | .PP |
0bf534a9 | 206 | In SVID 3 (or perhaps earlier), |
a1d5f77c | 207 | the type of the \fIshmaddr\fP argument was changed from |
5049da5b | 208 | .I "char\ *" |
a1d5f77c | 209 | into |
5049da5b | 210 | .IR "const void\ *" , |
a1d5f77c MK |
211 | and the returned type of |
212 | .BR shmat () | |
213 | from | |
5049da5b | 214 | .I "char\ *" |
a1d5f77c | 215 | into |
5049da5b | 216 | .IR "void\ *" . |
fea681da | 217 | .SH NOTES |
11adc9b9 MK |
218 | After a |
219 | .BR fork (2), | |
220 | the child inherits the attached shared memory segments. | |
efeece04 | 221 | .PP |
11adc9b9 MK |
222 | After an |
223 | .BR execve (2), | |
224 | all attached shared memory segments are detached from the process. | |
efeece04 | 225 | .PP |
11adc9b9 MK |
226 | Upon |
227 | .BR _exit (2), | |
228 | all attached shared memory segments are detached from the process. | |
efeece04 | 229 | .PP |
fea681da | 230 | Using |
f998edca | 231 | .BR shmat () |
fea681da MK |
232 | with |
233 | .I shmaddr | |
8478ee02 | 234 | equal to NULL |
fea681da MK |
235 | is the preferred, portable way of attaching a shared memory segment. |
236 | Be aware that the shared memory segment attached in this way | |
237 | may be attached at different addresses in different processes. | |
238 | Therefore, any pointers maintained within the shared memory must be | |
239 | made relative (typically to the starting address of the segment), | |
240 | rather than absolute. | |
f998edca MK |
241 | .PP |
242 | On Linux, it is possible to attach a shared memory segment even if it | |
a6a99a4c | 243 | is already marked to be deleted. |
2bc6fb60 | 244 | However, POSIX.1 does not specify this behavior and |
f998edca | 245 | many other implementations do not support it. |
dd3568a1 | 246 | .PP |
f998edca MK |
247 | The following system parameter affects |
248 | .BR shmat (): | |
89b3c6b8 | 249 | .TP |
fea681da MK |
250 | .B SHMLBA |
251 | Segment low boundary address multiple. | |
2d2c6782 MK |
252 | When explicitly specifying an attach address in a call to |
253 | .BR shmat (), | |
254 | the caller should ensure that the address is a multiple of this value. | |
255 | This is necessary on some architectures, | |
256 | in order either to ensure good CPU cache performance or to ensure that | |
257 | different attaches of the same segment have consistent views | |
258 | within the CPU cache. | |
b7d1c645 | 259 | .B SHMLBA |
b739c378 MK |
260 | is normally some multiple of the system page size. |
261 | (On many Linux architectures, | |
262 | .B SHMLBA | |
263 | is the same as the system page size.) | |
fea681da | 264 | .PP |
964e1ae0 | 265 | The implementation places no intrinsic per-process limit on the |
fea681da MK |
266 | number of shared memory segments |
267 | .RB ( SHMSEG ). | |
a14af333 | 268 | .SH EXAMPLES |
fc477423 MK |
269 | The two programs shown below exchange a string using a shared memory segment. |
270 | Further details about the programs are given below. | |
271 | First, we show a shell session demonstrating their use. | |
272 | .PP | |
273 | In one terminal window, we run the "reader" program, | |
274 | which creates a System V shared memory segment and a System V semaphore set. | |
275 | The program prints out the IDs of the created objects, | |
276 | and then waits for the semaphore to change value. | |
277 | .PP | |
278 | .in +4n | |
279 | .EX | |
77ca5b1d | 280 | $ \fB./svshm_string_read\fP |
fc477423 MK |
281 | shmid = 1114194; semid = 15 |
282 | .EE | |
283 | .in | |
284 | .PP | |
285 | In another terminal window, we run the "writer" program. | |
286 | The "writer" program takes three command-line arguments: | |
287 | the IDs of the shared memory segment and semaphore set created | |
288 | by the "reader", and a string. | |
289 | It attaches the existing shared memory segment, | |
290 | copies the string to the shared memory, and modifies the semaphore value. | |
291 | .PP | |
292 | .in +4n | |
293 | .EX | |
294 | $ \fB./svshm_string_write 1114194 15 \(aqHello, world\(aq\fP | |
295 | .EE | |
296 | .in | |
297 | .PP | |
298 | Returning to the terminal where the "reader" is running, | |
299 | we see that the program has ceased waiting on the semaphore | |
300 | and has printed the string that was copied into the | |
301 | shared memory segment by the writer: | |
302 | .PP | |
303 | .in +4n | |
304 | .EX | |
305 | Hello, world | |
306 | .EE | |
307 | .in | |
fc477423 MK |
308 | .\" |
309 | .SS Program source: svshm_string.h | |
65f96dae | 310 | The following header file is included by the "reader" and "writer" programs: |
fc477423 MK |
311 | .PP |
312 | .in +4n | |
33857069 | 313 | .\" SRC BEGIN (svshm_string.h) |
fc477423 | 314 | .EX |
65f96dae MK |
315 | /* svshm_string.h |
316 | ||
317 | Licensed under GNU General Public License v2 or later. | |
318 | */ | |
fc477423 MK |
319 | #include <sys/types.h> |
320 | #include <sys/ipc.h> | |
321 | #include <sys/shm.h> | |
322 | #include <sys/sem.h> | |
323 | #include <stdio.h> | |
324 | #include <stdlib.h> | |
325 | #include <string.h> | |
326 | ||
327 | #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e | |
328 | } while (0) | |
329 | ||
330 | union semun { /* Used in calls to semctl() */ | |
331 | int val; | |
332 | struct semid_ds * buf; | |
333 | unsigned short * array; | |
334 | #if defined(__linux__) | |
335 | struct seminfo * __buf; | |
336 | #endif | |
337 | }; | |
338 | ||
339 | #define MEM_SIZE 4096 | |
340 | .EE | |
33857069 | 341 | .\" SRC END |
fc477423 MK |
342 | .in |
343 | .\" | |
344 | .SS Program source: svshm_string_read.c | |
345 | The "reader" program creates a shared memory segment and a semaphore set | |
346 | containing one semaphore. | |
347 | It then attaches the shared memory object into its address space | |
348 | and initializes the semaphore value to 1. | |
349 | Finally, the program waits for the semaphore value to become 0, | |
350 | and afterwards prints the string that has been copied into the | |
351 | shared memory segment by the "writer". | |
352 | .PP | |
353 | .in +4n | |
33857069 | 354 | .\" SRC BEGIN (svshm_string_read.c) |
fc477423 | 355 | .EX |
1a576c58 MK |
356 | /* svshm_string_read.c |
357 | ||
358 | Licensed under GNU General Public License v2 or later. | |
359 | */ | |
f2bdc79c AC |
360 | #include <stdio.h> |
361 | #include <stdlib.h> | |
362 | #include <sys/ipc.h> | |
363 | #include <sys/sem.h> | |
364 | #include <sys/shm.h> | |
365 | ||
fc477423 MK |
366 | #include "svshm_string.h" |
367 | ||
368 | int | |
c6ae6d97 | 369 | main(void) |
fc477423 MK |
370 | { |
371 | int semid, shmid; | |
372 | union semun arg, dummy; | |
373 | struct sembuf sop; | |
374 | char *addr; | |
375 | ||
376 | /* Create shared memory and semaphore set containing one | |
c6beb8a1 | 377 | semaphore. */ |
fc477423 MK |
378 | |
379 | shmid = shmget(IPC_PRIVATE, MEM_SIZE, IPC_CREAT | 0600); | |
380 | if (shmid == \-1) | |
381 | errExit("shmget"); | |
382 | ||
383 | semid = semget(IPC_PRIVATE, 1, IPC_CREAT | 0600); | |
5974cc55 V |
384 | if (semid == \-1) |
385 | errExit("semget"); | |
fc477423 | 386 | |
c6beb8a1 | 387 | /* Attach shared memory into our address space. */ |
fc477423 MK |
388 | |
389 | addr = shmat(shmid, NULL, SHM_RDONLY); | |
390 | if (addr == (void *) \-1) | |
391 | errExit("shmat"); | |
392 | ||
c6beb8a1 | 393 | /* Initialize semaphore 0 in set with value 1. */ |
fc477423 MK |
394 | |
395 | arg.val = 1; | |
396 | if (semctl(semid, 0, SETVAL, arg) == \-1) | |
397 | errExit("semctl"); | |
398 | ||
399 | printf("shmid = %d; semid = %d\en", shmid, semid); | |
400 | ||
c6beb8a1 | 401 | /* Wait for semaphore value to become 0. */ |
fc477423 MK |
402 | |
403 | sop.sem_num = 0; | |
404 | sop.sem_op = 0; | |
405 | sop.sem_flg = 0; | |
406 | ||
407 | if (semop(semid, &sop, 1) == \-1) | |
408 | errExit("semop"); | |
409 | ||
c6beb8a1 | 410 | /* Print the string from shared memory. */ |
fc477423 MK |
411 | |
412 | printf("%s\en", addr); | |
413 | ||
c6beb8a1 | 414 | /* Remove shared memory and semaphore set. */ |
fc477423 MK |
415 | |
416 | if (shmctl(shmid, IPC_RMID, NULL) == \-1) | |
417 | errExit("shmctl"); | |
418 | if (semctl(semid, 0, IPC_RMID, dummy) == \-1) | |
419 | errExit("semctl"); | |
420 | ||
421 | exit(EXIT_SUCCESS); | |
422 | } | |
423 | .EE | |
33857069 | 424 | .\" SRC END |
fc477423 MK |
425 | .in |
426 | .\" | |
427 | .SS Program source: svshm_string_write.c | |
428 | The writer program takes three command-line arguments: | |
429 | the IDs of the shared memory segment and semaphore set | |
430 | that have already been created by the "reader", and a string. | |
431 | It attaches the shared memory segment into its address space, | |
432 | and then decrements the semaphore value to 0 in order to inform the | |
433 | "reader" that it can now examine the contents of the shared memory. | |
434 | .PP | |
435 | .in +4n | |
33857069 | 436 | .\" SRC BEGIN (svshm_string_write.c) |
fc477423 | 437 | .EX |
1a576c58 MK |
438 | /* svshm_string_write.c |
439 | ||
440 | Licensed under GNU General Public License v2 or later. | |
441 | */ | |
f2bdc79c AC |
442 | #include <stdio.h> |
443 | #include <stdlib.h> | |
444 | #include <string.h> | |
445 | #include <sys/sem.h> | |
446 | #include <sys/shm.h> | |
447 | ||
fc477423 MK |
448 | #include "svshm_string.h" |
449 | ||
450 | int | |
451 | main(int argc, char *argv[]) | |
452 | { | |
453 | int semid, shmid; | |
454 | struct sembuf sop; | |
455 | char *addr; | |
456 | size_t len; | |
457 | ||
458 | if (argc != 4) { | |
459 | fprintf(stderr, "Usage: %s shmid semid string\en", argv[0]); | |
460 | exit(EXIT_FAILURE); | |
461 | } | |
462 | ||
463 | len = strlen(argv[3]) + 1; /* +1 to include trailing \(aq\e0\(aq */ | |
464 | if (len > MEM_SIZE) { | |
465 | fprintf(stderr, "String is too big!\en"); | |
466 | exit(EXIT_FAILURE); | |
467 | } | |
468 | ||
c6beb8a1 | 469 | /* Get object IDs from command\-line. */ |
fc477423 MK |
470 | |
471 | shmid = atoi(argv[1]); | |
472 | semid = atoi(argv[2]); | |
473 | ||
474 | /* Attach shared memory into our address space and copy string | |
475 | (including trailing null byte) into memory. */ | |
476 | ||
477 | addr = shmat(shmid, NULL, 0); | |
478 | if (addr == (void *) \-1) | |
479 | errExit("shmat"); | |
480 | ||
481 | memcpy(addr, argv[3], len); | |
482 | ||
c6beb8a1 | 483 | /* Decrement semaphore to 0. */ |
fc477423 MK |
484 | |
485 | sop.sem_num = 0; | |
486 | sop.sem_op = \-1; | |
487 | sop.sem_flg = 0; | |
488 | ||
489 | if (semop(semid, &sop, 1) == \-1) | |
490 | errExit("semop"); | |
491 | ||
492 | exit(EXIT_SUCCESS); | |
493 | } | |
494 | .EE | |
33857069 | 495 | .\" SRC END |
fc477423 | 496 | .in |
47297adb | 497 | .SH SEE ALSO |
fea681da MK |
498 | .BR brk (2), |
499 | .BR mmap (2), | |
500 | .BR shmctl (2), | |
501 | .BR shmget (2), | |
92243659 | 502 | .BR capabilities (7), |
f93af9c6 | 503 | .BR shm_overview (7), |
343cdc5a | 504 | .BR sysvipc (7) |