NAME

shm_open − open a shared memory object for reading or writing

SYNOPSIS

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <sys/mman.h>

int shm_open (const char ∗path, int oflag, ... /∗ mode_t mode ∗/);

DESCRIPTION

The shm_open function establishes a connection between a shared memory object and a file descriptor.  It creates an open file description that refers to the shared memory object and a file descriptor that refers to that open file description.  The file descriptor is used by other functions to refer to that shared memory object. 

path points to a path name naming a shared memory object.  shm_open opens a file descriptor for the named shared memory object and sets the file status flags according to the value of oflag. oflag values are constructed by OR-ing Flags from the following list (only one of the first two flags below may be used):

O_RDONLY Open for reading only. 

O_RDWR Open for reading and writing. 

O_CREAT If the shared memory object exists, this flag has no effect, except as noted under O_EXCL below.  Otherwise, the shared memory object is created and the owner ID of the object is set to the effective user ID of the process, the group ID of the object is set to the effective group ID of the process, or if the S_ISGID bit is set in the directory in which the object is being created, the object’s group ID is set to the group ID of its parent directory.  If the group ID of the new shared 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 [see creat(2)]:

All bits set in the file mode creation mask of the process are cleared [see umask(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 0 and the mode and owner are unchanged.  O_TRUNC has no effect on FIFO special files or directories. 

O_EXCL If O_EXCL and O_CREAT are set, shm_open will fail if the shared memory object exists.  The check for the existence of the shared memory object and the creation of the object if it does not exist is atomic with respect to other processes executing shm_open naming the same shared memory object in the same directory with O_EXCL and O_CREAT set. 

The new file descriptor is the lowest numbered file descriptor available and is set to close on an exec system call [see fcntl(2)]. 

Certain flag values can be set following shm_open as described in fcntl(2). 

If O_CREAT is set and the shared memory object did not previously exist, upon successful completion shm_open marks for update the st_atime, st_ctime and st_mtime fields of the object and the st_ctime and st_mtime fields of the parent directory. 

If O_TRUNC is set and the shared memory object did previously exist, upon successful completion shm_open marks for update the st_ctime and st_mtime fields of the object. 

The named shared memory object is opened unless one or more of the following are true:

EACCES The shared memory object does not exist and write permission is denied by the parent directory of the object to be created. 

EACCES 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 shared memory object. 

EAGAIN The shared memory object exists, mandatory file/record locking is set, and there are outstanding record locks on the object [see chmod(2)]. 

EEXIST O_CREAT and O_EXCL are set, and the named 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. 

EISDIR The named shared memory object is a directory. 

ELOOP Too many symbolic links were encountered in translating path. 

EMFILE The process has too many open files and/or shared memory objects [see getrlimit(2)]. 

EMULTIHOP Components of path require hopping to multiple remote machines and the file system does not allow it. 

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

ENOLINK path points to a remote machine, and the link to that machine is no longer active. 

ENOMEM The system is unable to allocate a send descriptor. 

ENOSPC O_CREAT and O_EXCL are set, and the file system is out of inodes. 

ENOSPC O_CREAT is set and the directory that would contain the shared memory object cannot be extended. 

ENOSR Unable to allocate a stream. 

ENOTDIR A component of the path prefix is not a directory. 

EROFS The named shared memory object resides on a read-only file system and either O_RDWR, O_CREAT, or O_TRUNC is set in oflag (if the shared memory object does not exist). 

SEE ALSO

intro(2), chmod(2), creat(2), exec(2), fcntl(2), getrlimit(2), stat(2), umask(2), shm_unlink(3X), stat(5)

DIAGNOSTICS

Upon successful completion, the file descriptor is returned.  Otherwise, a value of −1 is returned and errno is set to indicate the error. 

  —  POSIX 1003.4 Extensions