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