DragonFly On-Line Manual Pages
SHM_OPEN(3) DragonFly Library Functions Manual SHM_OPEN(3)
shm_open, shm_unlink - POSIX shared memory object operations
Standard C Library (libc, -lc)
shm_open(const char *path, int flags, mode_t mode);
shm_unlink(const char *path);
The shm_open() function opens (or optionally creates) a POSIX shared
memory object named path. The shm_unlink() function removes a shared
memory object named path. Using the same path allows unrelated processes
to access the same object.
DragonFly mounts a tmpfs(5) file system at /var/run/shm. POSIX shared
memory objects are implemented as ordinary files under that directory.
The shm_open() and shm_unlink() functions act as wrappers around open(2)
and unlink(2). Any leading slash (`/') characters are removed from path
to make it relative to /var/run/shm. The flags and mode arguments are
passed through unaltered. flags is checked to ensure that the access
mode specified is not O_WRONLY (which is not defined for shared memory
In addition, the DragonFly implementation causes mmap() of a descriptor
returned by shm_open() to behave as if the MAP_NOSYNC flag had been
specified to mmap(2). (It does so by setting a special file flag using
If successful, shm_open() returns a non-negative integer; shm_unlink()
returns zero. Both functions return -1 on failure, and set errno to
indicate the error.
On DragonFly and many other operating systems the path argument is
interpreted as a file system pathname under a special directory where a
memory-backed file system is mounted. Most operating systems do some
name mangling to path. Leading slashes are commonly removed to turn an
absolute pathname into a relative one. Problematic characters may be
escaped and there may be a length limit on path. On some systems the
mangled pathname is completely different from the given path. On a few
systems, shared memory objects live outside the ordinary file system in
their own dedicated namespace.
According to POSIX two processes opening the same path are guaranteed to
access the same shared memory object if and only if path begins with a
slash. The most portable form of pathname is probably `/foobar', i.e.
one leading slash, no other slashes and no dots.
The result of using open(2) on the pathname of a shared memory object, or
using read(2) or write(2) on a file descriptor returned by shm_open(), is
undefined by POSIX. It is also undefined whether the shared memory
object itself, or its contents, persist across reboots. On DragonFly and
most other systems they do not. Only the O_RDONLY, O_RDWR, O_CREAT,
O_EXCL, and O_TRUNC flags may be used in portable programs.
The shm_open() and shm_unlink() functions can fail with any error defined
for open() and unlink(), respectively. In addition, the following errors
are defined for shm_open():
[EINVAL] The object named by path is not a shared memory object
(i.e., it is not a regular file).
[EINVAL] The flags argument to shm_open() specifies an access
mode of O_WRONLY.
mmap(2), munmap(2), open(2), unlink(2), tmpfs(5)
The shm_open() and shm_unlink() functions are believed to conform to IEEE
Std 1003.1b-1993 ("POSIX.1b").
The shm_open() and shm_unlink() functions first appeared in FreeBSD 4.3.
Garrett A. Wollman <wollman@FreeBSD.org> (C library support and this
Matthew Dillon <dillon@FreeBSD.org> (MAP_NOSYNC)
DragonFly 5.5-DEVELOPMENT June 28, 2019 DragonFly 5.5-DEVELOPMENT