shmopen(2) shmopen(2)
NAME
shmopen - establishes a connection between a shared memory object and a
file descriptor
C SYNOPSIS
#include <sys/man.h>
int shmopen (const char *path, int oflag, modet mode );
DESCRIPTION
path is a pointer to the character string which names a shared memory
object. shmopen 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:
ORDONLY
Open the memory object for reading only.
ORDWR Open the memory object for reading and writing.
With one of the above flags set, any of the following flags may also be
specified:
OCREAT
If the memory object already exists, this flag has no effect, except
as noted under OEXCL 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 SISGID 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
SISGID 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
shmopen(2) shmopen(2)
The ``save text image after execution bit'' of the mode is
cleared [see chmod(2)].
OTRUNC If the shared memory object exists, its length is truncated to
zero and the mode and owner are unchanged.
OEXCL If OEXCL and OCREAT are set, shmopen 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 shmopen naming the same
memory object in the same directory with OEXCL and OCREAT set.
Shared memory objects and their associated data persist until the memory
object is unlinked and all other references are dropped [see
shmunlink(2) and close(2)].
If path is a symbolic link and OCREAT and OEXCL 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 FDCLOEXEC 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
shmopen as described in fcntl(2).
If OCREAT is set and the memory object did not previously exist,
shmopen marks the following memory object fields for update: statime,
stctime and stmtime. Further, the sttime and stmtime fields of the
memory object parent directory are also marked for update.
If OTRUNC is set and the memory object did previously exist, shmopen
marks the stctime and stmtime fields for update.
There is a system enforced limit on the number of open file descriptors
per process {OPENMAX}, 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
shmopen(2) shmopen(2)
EACCES OCREAT or OTRUNC 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, OCREAT or OTRUNC are
specified, mandatory file/record locking is set, and there are
outstanding record locks on the file naming the object [see
chmod(2)].
EDQUOT OCREAT 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 OCREAT and OEXCL 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 shmopen system call.
EINVAL path The FDCLOEXEC 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 {PATHMAX}, or the length
of a path component exceeds {NAMEMAX} while {POSIXNOTRUNC} is
in effect.
ENFILE The system file table is full.
ENOENT OCREAT is not set and the shared memory object does not exist.
ENOENT OCREAT is set and a component of the path prefix does not exist
or is the null pathname.
ENOSPC OCREAT and OEXCL 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
shmopen(2) shmopen(2)
ENOSPC OCREAT 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 OWRONLY, ORDWR, OCREAT, or OTRUNC 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),
shmunlink(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