# shmat

## PROLOG



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


## NAME



           shmat — XSI shared memory attach operation
    


## SYNOPSIS



           #include <sys/shm.h>
    
           void *shmat(int _shmid_ , const void *_shmaddr_ , int _shmflg_);
    


## DESCRIPTION



           The _shmat_() function operates on XSI shared memory (see the Base
           Definitions volume of POSIX.1‐2017, _Section 3.346_ , _Shared Memory_
           _Object_).  It is unspecified whether this function interoperates
           with the realtime interprocess communication facilities defined in
           _Section 2.8_ , _Realtime_.
    
           The _shmat_() function attaches the shared memory segment associated
           with the shared memory identifier specified by _shmid_ to the
           address space of the calling process. The segment is attached at
           the address specified by one of the following criteria:
    
            *  If _shmaddr_ is a null pointer, the segment is attached at the
               first available address as selected by the system.
    
            *  If _shmaddr_ is not a null pointer and (_shmflg_ &SHM_RND) is non-
               zero, the segment is attached at the address given by (_shmaddr_
               -((_uintptr_t_)_shmaddr_ %SHMLBA)). The character **'%'** is the C-
               language remainder operator.
    
            *  If _shmaddr_ is not a null pointer and (_shmflg_ &SHM_RND) is 0,
               the segment is attached at the address given by _shmaddr_.
    
            *  The segment is attached for reading if (_shmflg_ &SHM_RDONLY) is
               non-zero and the calling process has read permission;
               otherwise, if it is 0 and the calling process has read and
               write permission, the segment is attached for reading and
               writing.
    


## RETURN VALUE



           Upon successful completion, _shmat_() shall increment the value of
           _shm_nattch_ in the data structure associated with the shared memory
           ID of the attached shared memory segment and return the segment's
           start address.  Also, the _shm_atime_ timestamp shall be set to the
           current time, as described in _Section 2.7.1_ , _IPC General_
           _Description_.
    
           Otherwise, the shared memory segment shall not be attached,
           _shmat_() shall return (**void ***)-1, and _errno_ shall be set to
           indicate the error.
    


## ERRORS



           The _shmat_() function shall fail if:
    
           **EACCES** Operation permission is denied to the calling process; see
                  _Section 2.7_ , _XSI Interprocess Communication_.
    
           **EINVAL** The value of _shmid_ is not a valid shared memory identifier,
                  the _shmaddr_ is not a null pointer, and the value of
                  (_shmaddr_ -((_uintptr_t_)_shmaddr_ %SHMLBA)) is an illegal
                  address for attaching shared memory; or the _shmaddr_ is not
                  a null pointer, (_shmflg_ &SHM_RND) is 0, and the value of
                  _shmaddr_ is an illegal address for attaching shared memory.
    
           **EMFILE** The number of shared memory segments attached to the
                  calling process would exceed the system-imposed limit.
    
           **ENOMEM** The available data space is not large enough to accommodate
                  the shared memory segment.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           The POSIX Realtime Extension defines alternative interfaces for
           interprocess communication. Application developers who need to use
           IPC should design their applications so that modules using the IPC
           routines described in _Section 2.7_ , _XSI Interprocess Communication_
           can be easily modified to use the alternative interfaces.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *