NAME
shm_open,
shm_unlink —
shared memory object operations
LIBRARY
POSIX Real-time Library (librt, -lrt)
SYNOPSIS
#include <sys/types.h>
#include <sys/mman.h>
#include <fcntl.h>
int
shm_open(
const
char *name,
int
flags,
mode_t mode);
int
shm_unlink(
const
char *name);
DESCRIPTION
The
shm_open() function creates or opens a POSIX shared memory
object named
name. The
flags
argument contains a subset of the flags used by
open(2). An access mode of either
O_RDONLY
or
O_RDWR
must be
included in
flags. The optional flags
O_CREAT
,
O_EXCL
, and
O_TRUNC
may also be specified.
If
O_CREAT
is specified, then a new shared memory object
named
name will be created if it does not exist. In this
case, the shared memory object is created with mode
mode
subject to the process' umask value. If both the
O_CREAT
and
O_EXCL
flags are
specified and a shared memory object named
path already
exists, then
shm_open() will fail with
EEXIST
.
Newly created objects start off with a size of zero. If an existing shared
memory object is opened with
O_RDWR
and the
O_TRUNC
flag is specified, then the shared memory
object will be truncated to a size of zero. The size of the object can be
adjusted via
ftruncate(2) and
queried via
fstat(2).
The new descriptor is set to close during
execve(2) system calls; see
close(2) and
fcntl(2).
The
shm_unlink() system call removes a shared memory object
named
path.
RETURN VALUES
If successful,
shm_open() returns a non-negative integer, and
shm_unlink() returns zero. Both functions return -1 on
failure, and set
errno to indicate the error.
COMPATIBILITY
The
path argument does not necessarily represent a
pathname (although it does in most other implementations). Two processes
opening the same
path are guaranteed to access the same
shared memory object if and only if
path begins with a
slash (‘
/
’) character.
Only the
O_RDONLY
,
O_RDWR
,
O_CREAT
,
O_EXCL
, and
O_TRUNC
flags may be used in portable programs.
The result of using
open(2),
read(2), or
write(2) on a shared memory
object, or on the descriptor returned by
shm_open(), is
undefined. It is also undefined whether the shared memory object itself, or
its contents, persist across reboots.
ERRORS
The following errors are defined for
shm_open():
-
-
- [
EACCES
]
- The required permissions (for reading or reading and
writing) are denied.
-
-
- [
EEXIST
]
O_CREAT
and
O_EXCL
are specified and the named shared memory
object does exist.
-
-
- [
EFAULT
]
- The path argument points outside the
process' allocated address space.
-
-
- [
EINVAL
]
- A flag other than
O_RDONLY
,
O_RDWR
, O_CREAT
,
O_EXCL
, or O_TRUNC
was
included in flags; or the path
does not begin with a slash (‘/
’)
character.
-
-
- [
EMFILE
]
- The process has already reached its limit for open file
descriptors.
-
-
- [
ENAMETOOLONG
]
- The entire pathname exceeded
{
PATH_MAX
} characters.
-
-
- [
ENFILE
]
- The system file table is full.
-
-
- [
ENOENT
]
O_CREAT
is specified and the named
shared memory object does not exist.
-
-
- [
ENOTSUP
]
- Not supported, most likely due to missing or incorrect
/var/shm mount.
The following errors are defined for
shm_unlink():
-
-
- [
EACCES
]
- The required permissions are denied.
shm_unlink() requires write permission to the shared
memory object.
-
-
- [
EFAULT
]
- The path argument points outside the
process' allocated address space.
-
-
- [
ENAMETOOLONG
]
- The entire pathname exceeded
{
PATH_MAX
} characters.
-
-
- [
ENOENT
]
- The named shared memory object does not exist.
SEE ALSO
close(2),
fstat(2),
ftruncate(2),
mmap(2),
munmap(2)
STANDARDS
The
shm_open() and
shm_unlink() functions
are expected to conform to
IEEE Std 1003.1b-1993
(“POSIX.1b”).
HISTORY
These functions first appeared in
NetBSD 7.0.