| 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) |