man.bsd.lv manual page server

NAME

shm_open, shm_unlink — POSIX shared memory object operations

LIBRARY

library “libc”

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

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)