]>
Commit | Line | Data |
---|---|---|
145b262d | 1 | .\" Copyright (C) 2002, 2020 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 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 | |
10d76543 MK |
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 | 24 | .\" |
e8426ca2 | 25 | .TH SHM_OPEN 3 2020-04-11 "Linux" "Linux Programmer's Manual" |
fea681da | 26 | .SH NAME |
f68512e9 | 27 | shm_open, shm_unlink \- create/open or unlink POSIX shared memory objects |
fea681da | 28 | .SH SYNOPSIS |
fea681da | 29 | .B #include <sys/mman.h> |
e03e2055 | 30 | .br |
84c517a4 | 31 | .BR "#include <sys/stat.h>" " /* For mode constants */" |
87d17de4 | 32 | .br |
e03e2055 | 33 | .BR "#include <fcntl.h>" " /* For O_* constants */" |
68e4db0a | 34 | .PP |
fea681da | 35 | .BI "int shm_open(const char *" name ", int " oflag ", mode_t " mode ); |
68e4db0a | 36 | .PP |
fea681da | 37 | .BI "int shm_unlink(const char *" name ); |
68e4db0a | 38 | .PP |
20c58d70 | 39 | Link with \fI\-lrt\fP. |
fea681da | 40 | .SH DESCRIPTION |
bf0cac28 | 41 | .BR shm_open () |
fea681da MK |
42 | creates and opens a new, or opens an existing, POSIX shared memory object. |
43 | A POSIX shared memory object is in effect a handle which can | |
c13182ef | 44 | be used by unrelated processes to |
fea681da | 45 | .BR mmap (2) |
c13182ef MK |
46 | the same region of shared memory. |
47 | The | |
bf0cac28 | 48 | .BR shm_unlink () |
c13182ef | 49 | function performs the converse operation, |
fea681da | 50 | removing an object previously created by |
bf0cac28 | 51 | .BR shm_open (). |
dd3568a1 | 52 | .PP |
fea681da | 53 | The operation of |
bf0cac28 | 54 | .BR shm_open () |
fea681da MK |
55 | is analogous to that of |
56 | .BR open (2). | |
57 | .I name | |
c13182ef MK |
58 | specifies the shared memory object to be created or opened. |
59 | For portable use, | |
8e984751 MK |
60 | a shared memory object should be identified by a name of the form |
61 | .IR /somename ; | |
62 | that is, a null-terminated string of up to | |
bd838488 MK |
63 | .BI NAME_MAX |
64 | (i.e., 255) characters consisting of an initial slash, | |
8e984751 MK |
65 | .\" glibc allows the initial slash to be omitted, and makes |
66 | .\" multiple initial slashes equivalent to a single slash. | |
67 | .\" This differs from the implementation of POSIX message queues. | |
68 | followed by one or more characters, none of which are slashes. | |
69 | .\" glibc allows subdirectory components in the name, in which | |
70 | .\" case the subdirectory must exist under /dev/shm, and allow the | |
71 | .\" required permissions if a user wants to create a shared memory | |
72 | .\" object in that subdirectory. | |
dd3568a1 | 73 | .PP |
fea681da MK |
74 | .I oflag |
75 | is a bit mask created by ORing together exactly one of | |
c13182ef | 76 | .B O_RDONLY |
fea681da | 77 | or |
2d5e8aeb | 78 | .B O_RDWR |
fea681da | 79 | and any of the other flags listed here: |
0019177e | 80 | .TP |
fea681da MK |
81 | .B O_RDONLY |
82 | Open the object for read access. | |
33a0ccb2 | 83 | A shared memory object opened in this way can be |
c13182ef | 84 | .BR mmap (2)ed |
c9942389 MK |
85 | only for read |
86 | .RB ( PROT_READ ) | |
87 | access. | |
fea681da MK |
88 | .TP |
89 | .B O_RDWR | |
90 | Open the object for read-write access. | |
91 | .TP | |
92 | .B O_CREAT | |
c13182ef | 93 | Create the shared memory object if it does not exist. |
bf0cac28 MK |
94 | The user and group ownership of the object are taken |
95 | from the corresponding effective IDs of the calling process, | |
9ee4a2b6 | 96 | .\" In truth it is actually the filesystem IDs on Linux, but these |
bf0cac28 | 97 | .\" are nearly always the same as the effective IDs. (MTK, Jul 05) |
fea681da | 98 | and the object's |
c13182ef | 99 | permission bits are set according to the low-order 9 bits of |
fea681da MK |
100 | .IR mode , |
101 | except that those bits set in the process file mode | |
102 | creation mask (see | |
103 | .BR umask (2)) | |
104 | are cleared for the new object. | |
bf0cac28 | 105 | A set of macro constants which can be used to define |
fea681da | 106 | .I mode |
c13182ef | 107 | is listed in |
bf0cac28 | 108 | .BR open (2). |
87d17de4 MK |
109 | (Symbolic definitions of these constants can be obtained by including |
110 | .IR <sys/stat.h> .) | |
bdd915e2 | 111 | .IP |
5503c85e | 112 | A new shared memory object initially has zero length\(emthe size of the |
fea681da MK |
113 | object can be set using |
114 | .BR ftruncate (2). | |
bf0cac28 | 115 | The newly allocated bytes of a shared memory |
d9bfdb9c | 116 | object are automatically initialized to 0. |
c13182ef | 117 | .TP |
fea681da | 118 | .B O_EXCL |
c13182ef | 119 | If |
fea681da | 120 | .B O_CREAT |
bf0cac28 | 121 | was also specified, and a shared memory object with the given |
c13182ef | 122 | .I name |
fea681da | 123 | already exists, return an error. |
c13182ef | 124 | The check for the existence of the object, and its creation if it |
fea681da MK |
125 | does not exist, are performed atomically. |
126 | .TP | |
127 | .B O_TRUNC | |
128 | If the shared memory object already exists, truncate it to zero bytes. | |
dd3568a1 | 129 | .PP |
87d17de4 MK |
130 | Definitions of these flag values can be obtained by including |
131 | .IR <fcntl.h> . | |
dd3568a1 | 132 | .PP |
fea681da | 133 | On successful completion |
bf0cac28 | 134 | .BR shm_open () |
fea681da MK |
135 | returns a new file descriptor referring to the shared memory object. |
136 | This file descriptor is guaranteed to be the lowest-numbered file descriptor | |
c13182ef | 137 | not previously opened within the process. |
fea681da MK |
138 | The |
139 | .B FD_CLOEXEC | |
c13182ef | 140 | flag (see |
fea681da MK |
141 | .BR fcntl (2)) |
142 | is set for the file descriptor. | |
847e0d88 | 143 | .PP |
c13182ef MK |
144 | The file descriptor is normally used in subsequent calls |
145 | to | |
fea681da | 146 | .BR ftruncate (2) |
bf0cac28 | 147 | (for a newly created object) and |
fea681da MK |
148 | .BR mmap (2). |
149 | After a call to | |
150 | .BR mmap (2) | |
151 | the file descriptor may be closed without affecting the memory mapping. | |
847e0d88 | 152 | .PP |
fea681da | 153 | The operation |
c13182ef | 154 | of |
bf0cac28 | 155 | .BR shm_unlink () |
fea681da MK |
156 | is analogous to |
157 | .BR unlink (2): | |
158 | it removes a shared memory object name, and, once all processes | |
c13182ef | 159 | have unmapped the object, de-allocates and |
fea681da | 160 | destroys the contents of the associated memory region. |
c13182ef | 161 | After a successful |
bf0cac28 | 162 | .BR shm_unlink (), |
c13182ef | 163 | attempts to |
bf0cac28 | 164 | .BR shm_open () |
c13182ef | 165 | an object with the same |
fea681da | 166 | .I name |
26cd31fd | 167 | fail (unless |
fea681da MK |
168 | .B O_CREAT |
169 | was specified, in which case a new, distinct object is created). | |
47297adb | 170 | .SH RETURN VALUE |
fea681da | 171 | On success, |
bf0cac28 | 172 | .BR shm_open () |
ed09120a | 173 | returns a file descriptor (a nonnegative integer). |
c13182ef | 174 | On failure, |
bf0cac28 | 175 | .BR shm_open () |
fea681da | 176 | returns \-1. |
bf0cac28 | 177 | .BR shm_unlink () |
fea681da MK |
178 | returns 0 on success, or \-1 on error. |
179 | .SH ERRORS | |
180 | On failure, | |
181 | .I errno | |
c13182ef MK |
182 | is set to indicate the cause of the error. |
183 | Values which may appear in | |
fea681da MK |
184 | .I errno |
185 | include the following: | |
c13182ef | 186 | .TP |
fea681da MK |
187 | .B EACCES |
188 | Permission to | |
bf0cac28 | 189 | .BR shm_unlink () |
fea681da MK |
190 | the shared memory object was denied. |
191 | .TP | |
192 | .B EACCES | |
c13182ef | 193 | Permission was denied to |
bf0cac28 | 194 | .BR shm_open () |
fea681da MK |
195 | .I name |
196 | in the specified | |
bf0cac28 | 197 | .IR mode , |
c13182ef | 198 | or |
fea681da MK |
199 | .B O_TRUNC |
200 | was specified and the caller does not have write permission on the object. | |
c13182ef | 201 | .TP |
fea681da MK |
202 | .B EEXIST |
203 | Both | |
204 | .B O_CREAT | |
205 | and | |
c13182ef | 206 | .B O_EXCL |
fea681da | 207 | were specified to |
bf0cac28 | 208 | .BR shm_open () |
fea681da MK |
209 | and the shared memory object specified by |
210 | .I name | |
211 | already exists. | |
212 | .TP | |
213 | .B EINVAL | |
214 | The | |
215 | .I name | |
c13182ef | 216 | argument to |
bf0cac28 | 217 | .BR shm_open () |
fea681da MK |
218 | was invalid. |
219 | .TP | |
220 | .B EMFILE | |
26c32fab | 221 | The per-process limit on the number of open file descriptors has been reached. |
fea681da MK |
222 | .TP |
223 | .B ENAMETOOLONG | |
c13182ef | 224 | The length of |
fea681da | 225 | .I name |
c13182ef | 226 | exceeds |
fea681da MK |
227 | .BR PATH_MAX . |
228 | .TP | |
229 | .B ENFILE | |
e258766b | 230 | The system-wide limit on the total number of open files has been reached. |
fea681da MK |
231 | .TP |
232 | .B ENOENT | |
233 | An attempt was made to | |
bf0cac28 | 234 | .BR shm_open () |
c13182ef MK |
235 | a |
236 | .I name | |
fea681da MK |
237 | that did not exist, and |
238 | .B O_CREAT | |
239 | was not specified. | |
240 | .TP | |
241 | .B ENOENT | |
242 | An attempt was to made to | |
bf0cac28 | 243 | .BR shm_unlink () |
c13182ef MK |
244 | a |
245 | .I name | |
fea681da | 246 | that does not exist. |
67ff1512 MK |
247 | .SH VERSIONS |
248 | These functions are provided in glibc 2.2 and later. | |
be409be4 ZL |
249 | .SH ATTRIBUTES |
250 | For an explanation of the terms used in this section, see | |
251 | .BR attributes (7). | |
252 | .TS | |
253 | allbox; | |
254 | lbw24 lb lb | |
255 | l l l. | |
256 | Interface Attribute Value | |
257 | T{ | |
258 | .BR shm_open (), | |
259 | .BR shm_unlink () | |
260 | T} Thread safety MT-Safe locale | |
261 | .TE | |
847e0d88 | 262 | .sp 1 |
47297adb | 263 | .SH CONFORMING TO |
abb4b5b5 | 264 | POSIX.1-2001, POSIX.1-2008. |
dd3568a1 | 265 | .PP |
2b2581ee MK |
266 | POSIX.1-2001 says that the group ownership of a newly created shared |
267 | memory object is set to either the calling process's effective group ID | |
44a2c328 | 268 | or "a system default group ID". |
f71eeb14 MK |
269 | POSIX.1-2008 says that the group ownership |
270 | may be set to either the calling process's effective group ID | |
271 | or, if the object is visible in the filesystem, | |
272 | the group ID of the parent directory. | |
47297adb | 273 | .SH NOTES |
dd3568a1 | 274 | .PP |
c13182ef | 275 | POSIX leaves the behavior of the combination of |
fea681da MK |
276 | .B O_RDONLY |
277 | and | |
278 | .B O_TRUNC | |
c13182ef MK |
279 | unspecified. |
280 | On Linux, this will successfully truncate an existing | |
5503c85e | 281 | shared memory object\(emthis may not be so on other UNIX systems. |
dd3568a1 | 282 | .PP |
547afefe MK |
283 | The POSIX shared memory object implementation on Linux makes use |
284 | of a dedicated | |
285 | .BR tmpfs (5) | |
3a9a2ecb | 286 | filesystem that is normally mounted under |
bf0cac28 | 287 | .IR /dev/shm . |
145b262d MK |
288 | .SH EXAMPLE |
289 | The programs below employ POSIX shared memory and POSIX unnamed semaphores | |
290 | to exchange a piece of data. | |
291 | The "bounce" program (which must be run first) raises the case | |
292 | of a string that is placed into the shared memory by the "send" program. | |
293 | Once the data has been modified, the "send" program then prints | |
294 | the contents of the modified shared memory. | |
295 | An example execution of the two programs is the following: | |
296 | .PP | |
297 | .in +4n | |
298 | .EX | |
299 | $ \fB./pshm_ucase_bounce /myshm &\fP | |
300 | [1] 270171 | |
301 | $ \fB./pshm_ucase_send /myshm hello\fP | |
302 | HELLO | |
303 | .EE | |
304 | .in | |
305 | .PP | |
306 | Further detail about these programs is provided below. | |
307 | .\" | |
308 | .SS Program source: pshm_ucase.h | |
309 | The following header file is included by both programs below. | |
310 | Its primary purpose is to define a structure that will be imposed | |
311 | on the memory object that is shared between the two programs. | |
312 | .PP | |
313 | .in +4n | |
314 | .EX | |
315 | #include <sys/mman.h> | |
316 | #include <fcntl.h> | |
317 | #include <semaphore.h> | |
318 | #include <sys/stat.h> | |
319 | #include <stdio.h> | |
320 | #include <stdlib.h> | |
321 | #include <unistd.h> | |
322 | ||
323 | #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e | |
324 | } while (0) | |
325 | ||
326 | #define BUF_SIZE 1024 /* Maximum size for exchanged string */ | |
327 | ||
328 | /* Define a structure that will be imposed on the shared | |
329 | memory object */ | |
330 | ||
331 | struct shmbuf { | |
332 | sem_t sem1; /* POSIX unnamed semaphore */ | |
333 | sem_t sem2; /* POSIX unnamed semaphore */ | |
334 | size_t cnt; /* Number of bytes used in \(aqbuf\(aq */ | |
335 | char buf[BUF_SIZE]; /* Data being transferred */ | |
336 | }; | |
337 | .EE | |
338 | .in | |
339 | .PP | |
340 | .\" | |
341 | .SS Program source: pshm_ucase_bounce.c | |
342 | .PP | |
343 | The "bounce" program creates a new shared memory object with the name | |
344 | given in its command-line argument and sizes the object to | |
345 | match the size of the | |
346 | .I shmbuf | |
347 | structure defined in the header file. | |
348 | It then maps the object into the process's address space, | |
349 | and initializes two POSIX semaphores inside the object to 0. | |
350 | .PP | |
351 | After the "send" program has posted the first of the semaphores, | |
352 | the "bounce" program upper cases the data that has been placed | |
353 | in the memory by the "send" program and then posts the second semaphore | |
354 | to tell the "send" program that it may now access the shared memory. | |
355 | .PP | |
356 | .in +4n | |
357 | .EX | |
f379a700 MK |
358 | /* pshm_ucase_bounce.c |
359 | ||
360 | Licensed under GNU General Public License v2 or later. | |
361 | */ | |
145b262d MK |
362 | #include <ctype.h> |
363 | #include "pshm_ucase.h" | |
364 | ||
365 | int | |
366 | main(int argc, char *argv[]) | |
367 | { | |
368 | if (argc != 2) { | |
369 | fprintf(stderr, "Usage: %s /shm\-path\en", argv[0]); | |
370 | exit(EXIT_FAILURE); | |
371 | } | |
372 | ||
373 | char *shmpath = argv[1]; | |
374 | ||
375 | /* Create shared memory object and set its size to the size | |
376 | of our structure */ | |
377 | ||
378 | int fd = shm_open(shmpath, O_CREAT | O_EXCL | O_RDWR, | |
379 | S_IRUSR | S_IWUSR); | |
380 | if (fd == \-1) | |
381 | errExit("shm_open"); | |
382 | ||
383 | if (ftruncate(fd, sizeof(struct shmbuf)) == \-1) | |
384 | errExit("ftruncate"); | |
385 | ||
386 | /* Map the object into the caller\(aqs address space */ | |
387 | ||
388 | struct shmbuf *shmp = mmap(NULL, sizeof(struct shmbuf), | |
389 | PROT_READ | PROT_WRITE, | |
390 | MAP_SHARED, fd, 0); | |
391 | if (shmp == MAP_FAILED) | |
392 | errExit("mmap"); | |
393 | ||
394 | /* Initialize semaphores as process-shared, with value 0 */ | |
395 | ||
396 | if (sem_init(&shmp\->sem1, 1, 0) == \-1) | |
397 | errExit("sem_init\-sem1"); | |
398 | if (sem_init(&shmp\->sem2, 1, 0) == \-1) | |
399 | errExit("sem_init\-sem2"); | |
400 | ||
401 | /* Wait for \(aqsem1\(aq to be posted by peer before touching | |
402 | shared memory */ | |
403 | ||
404 | if (sem_wait(&shmp\->sem1) == \-1) | |
405 | errExit("sem_wait"); | |
406 | ||
407 | /* Convert data in shared memory into upper case */ | |
408 | ||
409 | for (int j = 0; j < shmp\->cnt; j++) | |
410 | shmp\->buf[j] = toupper((unsigned char) shmp\->buf[j]); | |
411 | ||
412 | /* Post \(aqsem2\(aq to tell the to tell peer that it can now | |
413 | access the modified data in shared memory */ | |
414 | ||
415 | if (sem_post(&shmp\->sem2) == \-1) | |
416 | errExit("sem_post"); | |
417 | ||
418 | /* Unlink the shared memory object. Even if the peer process | |
419 | is still using the object, this is okay. The object will | |
420 | be removed only after all open references are closed. */ | |
421 | ||
422 | shm_unlink(shmpath); | |
423 | ||
424 | exit(EXIT_SUCCESS); | |
425 | } | |
426 | .EE | |
427 | .in | |
428 | .PP | |
429 | .\" | |
430 | .SS Program source: pshm_ucase_send.c | |
431 | .PP | |
432 | The "send" program takes two command-line arguments: | |
433 | the pathname of a shared memory object previously created by the "bounce" | |
434 | program and a string that is to be copied into that object. | |
435 | .PP | |
436 | The program opens the shared memory object | |
437 | and maps the object into its address space. | |
438 | It then copies the data specified in its second argument | |
439 | into the shared memory, | |
440 | and posts the first semaphore, | |
441 | which tells the "bounce" program that it can now access that data. | |
442 | After the "bounce" program posts the second semaphore, | |
443 | the "send" program prints the contents of the shared memory | |
444 | on standard output. | |
445 | .PP | |
446 | .in +4n | |
447 | .EX | |
f379a700 MK |
448 | /* pshm_ucase_send.c |
449 | ||
450 | Licensed under GNU General Public License v2 or later. | |
451 | */ | |
145b262d MK |
452 | #include <string.h> |
453 | #include "pshm_ucase.h" | |
454 | ||
455 | int | |
456 | main(int argc, char *argv[]) | |
457 | { | |
458 | if (argc != 3) { | |
459 | fprintf(stderr, "Usage: %s /shm\-path string\en", argv[0]); | |
460 | exit(EXIT_FAILURE); | |
461 | } | |
462 | ||
463 | char *shmpath = argv[1]; | |
464 | char *string = argv[2]; | |
465 | size_t len = strlen(string); | |
466 | ||
467 | if (len > BUF_SIZE) { | |
468 | fprintf(stderr, "String is too long\en"); | |
469 | exit(EXIT_FAILURE); | |
470 | } | |
471 | ||
472 | /* Open the existing shared memory object and map it | |
473 | into the caller\(aqs address space */ | |
474 | ||
475 | int fd = shm_open(shmpath, O_RDWR, 0); | |
476 | if (fd == \-1) | |
477 | errExit("shm_open"); | |
478 | ||
479 | struct shmbuf *shmp = mmap(NULL, sizeof(struct shmbuf), | |
480 | PROT_READ | PROT_WRITE, | |
481 | MAP_SHARED, fd, 0); | |
482 | if (shmp == MAP_FAILED) | |
483 | errExit("mmap"); | |
484 | ||
485 | /* Copy data into the shared memory object */ | |
486 | ||
487 | shmp\->cnt = len; | |
488 | memcpy(&shmp\->buf, string, len); | |
489 | ||
490 | /* Tell peer that it can now access shared memory */ | |
491 | ||
492 | if (sem_post(&shmp\->sem1) == \-1) | |
493 | errExit("sem_post"); | |
494 | ||
495 | /* Wait until peer says that it has finished accessing | |
496 | the shared memory */ | |
497 | ||
498 | if (sem_wait(&shmp\->sem2) == \-1) | |
499 | errExit("sem_wait"); | |
500 | ||
501 | /* Write modified data in shared memory to standard output */ | |
502 | ||
503 | write(STDOUT_FILENO, &shmp\->buf, len); | |
504 | write(STDOUT_FILENO, "\en", 1); | |
505 | ||
506 | exit(EXIT_SUCCESS); | |
507 | } | |
508 | .EE | |
509 | .in | |
510 | .PP | |
47297adb | 511 | .SH SEE ALSO |
fea681da MK |
512 | .BR close (2), |
513 | .BR fchmod (2), | |
514 | .BR fchown (2), | |
515 | .BR fcntl (2), | |
516 | .BR fstat (2), | |
517 | .BR ftruncate (2), | |
c4d76cd9 | 518 | .BR memfd_create (2), |
fea681da MK |
519 | .BR mmap (2), |
520 | .BR open (2), | |
f93af9c6 MK |
521 | .BR umask (2), |
522 | .BR shm_overview (7) |