SHM_OPEN(3)                POSIX Programmer's Manual               SHM_OPEN(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       shm_open -- open a shared memory object (RREEAALLTTIIMMEE)

SSYYNNOOPPSSIISS
       #include <sys/mman.h>

       int shm_open(const char *_n_a_m_e, int _o_f_l_a_g, mode_t _m_o_d_e);

DDEESSCCRRIIPPTTIIOONN
       The _s_h_m___o_p_e_n() function shall establish a connection between a shared
       memory object and a file descriptor. It shall create 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. The _n_a_m_e argument points to a string naming a shared memory
       object. It is unspecified whether the name appears in the file system
       and is visible to other functions that take pathnames as arguments. The
       _n_a_m_e argument conforms to the construction rules for a pathname, except
       that the interpretation of <slash> characters other than the leading
       <slash> character in _n_a_m_e is implementation-defined, and that the
       length limits for the _n_a_m_e argument are implementation-defined and need
       not be the same as the pathname limits {PATH_MAX} and {NAME_MAX}.  If
       _n_a_m_e begins with the <slash> character, then processes calling
       _s_h_m___o_p_e_n() with the same value of _n_a_m_e refer to the same shared memory
       object, as long as that name has not been removed. If _n_a_m_e does not
       begin with the <slash> character, the effect is implementation-defined.

       If successful, _s_h_m___o_p_e_n() shall return a file descriptor for the shared
       memory object that is the lowest numbered file descriptor not currently
       open for that process.  The open file description is new, and therefore
       the file descriptor does not share it with any other processes. It is
       unspecified whether the file offset is set. The FD_CLOEXEC file
       descriptor flag associated with the new file descriptor is set.

       The file status flags and file access modes of the open file
       description are according to the value of _o_f_l_a_g.  The _o_f_l_a_g argument is
       the bitwise-inclusive OR of the following flags defined in the
       _<_f_c_n_t_l_._h_> header. Applications specify exactly one of the first two
       values (access modes) below in the value of _o_f_l_a_g:

       O_RDONLY    Open for read access only.

       O_RDWR      Open for read or write access.

       Any combination of the remaining flags may be specified in the value of
       _o_f_l_a_g:

       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. The user ID of the shared
                   memory object shall be set to the effective user ID of the
                   process. The group ID of the shared memory object shall be
                   set to the effective group ID of the process; however, if
                   the _n_a_m_e argument is visible in the file system, the group
                   ID may be set to the group ID of the containing directory.
                   The permission bits of the shared memory object shall be
                   set to the value of the _m_o_d_e argument except those set in
                   the file mode creation mask of the process. When bits in
                   _m_o_d_e other than the file permission bits are set, the
                   effect is unspecified. The _m_o_d_e argument does not affect
                   whether the shared memory object is opened for reading, for
                   writing, or for both. The shared memory object has a size
                   of zero.

       O_EXCL      If O_EXCL and O_CREAT are set, _s_h_m___o_p_e_n() fails 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 _s_h_m___o_p_e_n() naming the same shared memory object
                   with O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT
                   is not set, the result is undefined.

       O_TRUNC     If the shared memory object exists, and it is successfully
                   opened O_RDWR, the object shall be truncated to zero length
                   and the mode and owner shall be unchanged by this function
                   call. The result of using O_TRUNC with O_RDONLY is
                   undefined.

       When a shared memory object is created, the state of the shared memory
       object, including all data associated with the shared memory object,
       persists until the shared memory object is unlinked and all other
       references are gone. It is unspecified whether the name and shared
       memory object state remain valid after a system reboot.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, the _s_h_m___o_p_e_n() function shall return a non-
       negative integer representing the lowest numbered unused file
       descriptor. Otherwise, it shall return -1 and set _e_r_r_n_o to indicate the
       error.

EERRRROORRSS
       The _s_h_m___o_p_e_n() function shall fail if:

       EEAACCCCEESS The shared memory object exists and the permissions specified by
              _o_f_l_a_g are denied, or the shared memory object does not exist and
              permission to create the shared memory object is denied, or
              O_TRUNC is specified and write permission is denied.

       EEEEXXIISSTT O_CREAT and O_EXCL are set and the named shared memory object
              already exists.

       EEIINNTTRR  The _s_h_m___o_p_e_n() operation was interrupted by a signal.

       EEIINNVVAALL The _s_h_m___o_p_e_n() operation is not supported for the given name.

       EEMMFFIILLEE All file descriptors available to the process are currently
              open.

       EENNFFIILLEE Too many shared memory objects are currently open in the system.

       EENNOOEENNTT O_CREAT is not set and the named shared memory object does not
              exist.

       EENNOOSSPPCC There is insufficient space for the creation of the new shared
              memory object.

       The _s_h_m___o_p_e_n() function may fail if:

       EENNAAMMEETTOOOOLLOONNGG
              The length of the _n_a_m_e argument exceeds {_POSIX_PATH_MAX} on
              systems that do not support the XSI option or exceeds
              {_XOPEN_PATH_MAX} on XSI systems, or has a pathname component
              that is longer than {_POSIX_NAME_MAX} on systems that do not
              support the XSI option or longer than {_XOPEN_NAME_MAX} on XSI
              systems.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
   CCrreeaattiinngg aanndd MMaappppiinngg aa SShhaarreedd MMeemmoorryy OObbjjeecctt
       The following code segment demonstrates the use of _s_h_m___o_p_e_n() to create
       a shared memory object which is then sized using _f_t_r_u_n_c_a_t_e() before
       being mapped into the process address space using _m_m_a_p():

           ##iinncclluuddee <<uunniissttdd..hh>>
           ##iinncclluuddee <<ssyyss//mmmmaann..hh>>
           ......

           #define MAX_LEN 10000
           struct region {        /* Defines "structure" of shared memory */
               int len;
               char buf[MAX_LEN];
           };
           struct region *rptr;
           int fd;

           /* Create shared memory object and set its size */

           fd = shm_open("/myregion", O_CREAT | O_RDWR, S_IRUSR | S_IWUSR);
           if (fd == -1)
               /* Handle error */;

           if (ftruncate(fd, sizeof(struct region)) == -1)
               /* Handle error */;

           /* Map shared memory object */

           rptr = mmap(NULL, sizeof(struct region),
                  PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
           if (rptr == MAP_FAILED)
               /* Handle error */;

           /* Now we can refer to mapped region using fields of rptr;
              for example, rptr->len */
           ...

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

RRAATTIIOONNAALLEE
       When the Memory Mapped Files option is supported, the normal _o_p_e_n()
       call is used to obtain a descriptor to a file to be mapped according to
       existing practice with _m_m_a_p().  When the Shared Memory Objects option
       is supported, the _s_h_m___o_p_e_n() function shall obtain a descriptor to the
       shared memory object to be mapped.

       There is ample precedent for having a file descriptor represent several
       types of objects. In the POSIX.1-1990 standard, a file descriptor can
       represent a file, a pipe, a FIFO, a tty, or a directory. Many
       implementations simply have an operations vector, which is indexed by
       the file descriptor type and does very different operations. Note that
       in some cases the file descriptor passed to generic operations on file
       descriptors is returned by _o_p_e_n() or _c_r_e_a_t() and in some cases returned
       by alternate functions, such as _p_i_p_e().  The latter technique is used
       by _s_h_m___o_p_e_n().

       Note that such shared memory objects can actually be implemented as
       mapped files. In both cases, the size can be set after the open using
       _f_t_r_u_n_c_a_t_e().  The _s_h_m___o_p_e_n() function itself does not create a shared
       object of a specified size because this would duplicate an extant
       function that set the size of an object referenced by a file
       descriptor.

       On implementations where memory objects are implemented using the
       existing file system, the _s_h_m___o_p_e_n() function may be implemented using
       a macro that invokes _o_p_e_n(), and the _s_h_m___u_n_l_i_n_k() function may be
       implemented using a macro that invokes _u_n_l_i_n_k().

       For implementations without a permanent file system, the definition of
       the name of the memory objects is allowed not to survive a system
       reboot. Note that this allows systems with a permanent file system to
       implement memory objects as data structures internal to the
       implementation as well.

       On implementations that choose to implement memory objects using memory
       directly, a _s_h_m___o_p_e_n() followed by an _f_t_r_u_n_c_a_t_e() and _c_l_o_s_e() can be
       used to preallocate a shared memory area and to set the size of that
       preallocation. This may be necessary for systems without virtual memory
       hardware support in order to ensure that the memory is contiguous.

       The set of valid open flags to _s_h_m___o_p_e_n() was restricted to O_RDONLY,
       O_RDWR, O_CREAT, and O_TRUNC because these could be easily implemented
       on most memory mapping systems. This volume of POSIX.1-2008 is silent
       on the results if the implementation cannot supply the requested file
       access because of implementation-defined reasons, including hardware
       ones.

       The error conditions [[EEAACCCCEESS]] and [[EENNOOTTSSUUPP]] are provided to inform the
       application that the implementation cannot complete a request.

       [[EEAACCCCEESS]] indicates for implementation-defined reasons, probably
       hardware-related, that the implementation cannot comply with a
       requested mode because it conflicts with another requested mode. An
       example might be that an application desires to open a memory object
       two times, mapping different areas with different access modes. If the
       implementation cannot map a single area into a process space in two
       places, which would be required if different access modes were required
       for the two areas, then the implementation may inform the application
       at the time of the second open.

       [[EENNOOTTSSUUPP]] indicates for implementation-defined reasons, probably
       hardware-related, that the implementation cannot comply with a
       requested mode at all. An example would be that the hardware of the
       implementation cannot support write-only shared memory areas.

       On all implementations, it may be desirable to restrict the location of
       the memory objects to specific file systems for performance (such as a
       RAM disk) or implementation-defined reasons (shared memory supported
       directly only on certain file systems). The _s_h_m___o_p_e_n() function may be
       used to enforce these restrictions. There are a number of methods
       available to the application to determine an appropriate name of the
       file or the location of an appropriate directory. One way is from the
       environment via _g_e_t_e_n_v().  Another would be from a configuration file.

       This volume of POSIX.1-2008 specifies that memory objects have initial
       contents of zero when created. This is consistent with current behavior
       for both files and newly allocated memory. For those implementations
       that use physical memory, it would be possible that such
       implementations could simply use available memory and give it to the
       process uninitialized.  This, however, is not consistent with standard
       behavior for the uninitialized data area, the stack, and of course,
       files. Finally, it is highly desirable to set the allocated memory to
       zero for security reasons. Thus, initializing memory objects to zero is
       required.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       A future version might require the _s_h_m___o_p_e_n() and _s_h_m___u_n_l_i_n_k()
       functions to have semantics similar to normal file system operations.

SSEEEE AALLSSOO
       _c_l_o_s_e(), _d_u_p(), _e_x_e_c, _f_c_n_t_l(), _m_m_a_p(), _s_h_m_a_t(), _s_h_m_c_t_l(), _s_h_m_d_t(),
       _s_h_m___u_n_l_i_n_k(), _u_m_a_s_k()

       The Base Definitions volume of POSIX.1-2008, <<ffccnnttll..hh>>, <<ssyyss__mmmmaann..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be obtained online
       at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                          SHM_OPEN(3)
