shm_open(2) shm_open(2) NAME shm_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)]. 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. 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. 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 ALSO close(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