shm_open(2)shm_open(2)NAMEshm_open - establishes a connection between a shared memory object and a
file descriptor
C SYNOPSIS
#include <sys/mman.h>
#include <fcntl.h>
int shm_open (const char *path, int oflag, mode_t mode );
DESCRIPTION
path is a pointer to the character string which names a shared memory
object. shm_open opens a file descriptor for the shared memory object
and sets the memory access flag according to the value of oflag. The
oflag must be set to one of the following values:
O_RDONLY
Open the memory object for reading only.
O_RDWR Open the memory object for reading and writing.
With one of the above flags set, any of the following flags may also be
specified:
O_CREAT
If the memory object already exists, this flag has no effect, except
as noted under O_EXCL below. Otherwise, the memory object is
created. Shared memory objects are represented by files in the file
namespace (commands like ls will display memory objects as regular
files). Because of this relationship, shared memory objects inherit
their access semantics from files. The owner ID of the memory
object is set to the effective user IDs of the process, the group ID
of the memory object is set to the effective group IDs of the
process or to the group ID of the directory in which the memory
object is being created. This is determined as follows:
If the underlying filesystem was mounted with the BSD file
creation semantics flag [see fstab(4)] or the S_ISGID bit is
set [see chmod(2)] on the parent directory, then the group ID
of the new file is set to the group ID of the parent directory,
otherwise it is set to the effective group ID of the calling
process.
If the group ID of the memory object does not match the
effective group ID, or one of the supplementary groups IDs, the
S_ISGID bit is cleared. The access permission bits of the file
mode are set to the value of mode, modified as follows:
All bits set in the file mode creation mask of the process
are cleared [see umask(2)].
Page 1
shm_open(2)shm_open(2)
The ``save text image after execution bit'' of the mode is
cleared [see chmod(2)].
O_TRUNC If the shared memory object exists, its length is truncated to
zero and the mode and owner are unchanged.
O_EXCL If O_EXCL and O_CREAT are set, shm_open will fail if the memory
object exists. The check for the existence of the memory object
and the creation of the name in the file namespace is atomic with
respect to other processes executing shm_open naming the same
memory object in the same directory with O_EXCL and O_CREAT set.
Shared memory objects and their associated data persist until the memory
object is unlinked and all other references are dropped [see
shm_unlink(2) and close(2)].
If path is a symbolic link and O_CREAT and O_EXCL are set, the link is
not followed.
The new shared memory object file descriptor is the lowest numbered file
descriptor available and is set to close upon the execution of an exec
system call.
The FD_CLOEXEC file descriptor flag of the newly created shared memory
object is set. This flag will cause the file descriptor to close upon
the execution of an exec system call.
Memory object file descriptor flag values may be modified following
shm_open as described in fcntl(2).
If O_CREAT is set and the memory object did not previously exist,
shm_open marks the following memory object fields for update: st_atime,
st_ctime and st_mtime. Further, the st_time and st_mtime fields of the
memory object parent directory are also marked for update.
If O_TRUNC is set and the memory object did previously exist, shm_open
marks the st_ctime and st_mtime fields for update.
There is a system enforced limit on the number of open file descriptors
per process {OPEN_MAX}, whose value is returned by the getdtablesize(2)
function.
If the character string, pointed to by path, is prefixed with /dev then
unpredictable results may occur. Devices are opened using the open(2)
function.
The shared memory object is opened unless one or more of the following
are true:
EACCES The shared memory object, named by path, does not exist and write
permission is denied by the parent directory of the memory object
to be created.
Page 2
shm_open(2)shm_open(2)
EACCES O_CREAT or O_TRUNC is specified and write permission is denied.
EACCES A component of the path prefix denies search permission.
EACCES oflag permission is denied for an existing memory object.
EAGAIN The shared memory object exists, O_CREAT or O_TRUNC are
specified, mandatory file/record locking is set, and there are
outstanding record locks on the file naming the object [see
chmod(2)].
EDQUOT O_CREAT is specified, the memory object does not exist, and the
directory in which the entry for the new memory object is being
placed cannot be extended either because the user's quota of disk
blocks on the file system containing the directory has been
exhausted or the user's quota of inodes on the file system on
which the file is being created has been exhausted.
EEXIST O_CREAT and O_EXCL are set, and the shared memory object exists.
EFAULT path points outside the allocated address space of the process.
EINTR A signal was caught during the shm_open system call.
EINVAL path The FD_CLOEXEC file descriptor flag of the named shared
memory object could not be set.
EISDIR The memory object is a directory and oflag is write or
read/write.
ELOOP Too many symbolic links were encountered in translating path.
EMFILE The process has too many open files [see getrlimit(2)].
ENAMETOOLONG
The length of the path argument exceeds {PATH_MAX}, or the length
of a path component exceeds {NAME_MAX} while {_POSIX_NO_TRUNC} is
in effect.
ENFILE The system file table is full.
ENOENT O_CREAT is not set and the shared memory object does not exist.
ENOENT O_CREAT is set and a component of the path prefix does not exist
or is the null pathname.
ENOSPC O_CREAT and O_EXCL are set, and the file system is out of inodes
or the directory in which the entry for the new memory object is
being placed cannot be extended because there is no space left on
the file system containing the directory.
Page 3
shm_open(2)shm_open(2)
ENOSPC O_CREAT is set and the directory that would contain the memory
object cannot be extended.
ENOTDIR A component of the path prefix is not a directory.
ETIMEDOUT
The memory object of the shm_open is located on a remote system
which is not available [see intro(2)].
EROFS The named memory object resides on a read-only file system and
either O_WRONLY, O_RDWR, O_CREAT, or O_TRUNC is set in oflag (if
the memory object does not exist).
SEE ALSOclose(2), dup(2), exec(2), fcntl(2), ftruncate(2), mmap(2),
shm_unlink(2), umask(2)DIAGNOSTICS
Upon successful completion, the file descriptor is returned. Otherwise,
a value of -1 is returned and errno is set to indicate the error.
Page 4
