Debian Codegraph @

upstream/debian-unstable/man3/shm_open.3

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