DragonFly On-Line Manual Pages

SHM_OPEN(3)           DragonFly Library Functions Manual           SHM_OPEN(3)

NAME
     shm_open, shm_unlink - POSIX shared memory object operations

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <sys/types.h>
     #include <sys/mman.h>

     int
     shm_open(const char *path, int flags, mode_t mode);

     int
     shm_unlink(const char *path);

DESCRIPTION
     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.

IMPLEMENTATION NOTES
     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
     objects).

     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
     fcntl(2).)

RETURN VALUES
     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.

COMPATIBILITY
     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.

ERRORS
     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.

SEE ALSO
     mmap(2), munmap(2), open(2), unlink(2), tmpfs(5)

STANDARDS
     The shm_open() and shm_unlink() functions are believed to conform to IEEE
     Std 1003.1b-1993 ("POSIX.1b").

HISTORY
     The shm_open() and shm_unlink() functions first appeared in FreeBSD 4.3.

AUTHORS
     Garrett A. Wollman <wollman@FreeBSD.org> (C library support and this
     manual page)
     Matthew Dillon <dillon@FreeBSD.org> (MAP_NOSYNC)

DragonFly 5.5-DEVELOPMENT        June 28, 2019       DragonFly 5.5-DEVELOPMENT