Attaches a shared memory segment or a mapped file to the current process.
#include <sys/shm.h>
void *shmat (SharedMemoryID, SharedMemoryAddress, SharedMemoryFlag) intSharedMemoryID, SharedMemoryFlag; const void *SharedMemoryAddress;
The shmat subroutine attaches the shared memory segment or mapped file specified by the SharedMemoryID parameter (returned by the shmget subroutine), or file descriptor specified by the SharedMemoryID parameter (returned by the openx subroutine) to the address space of the calling process.
The following limits apply to shared memory:
Note: The following applies to AIX Version 4.2.1 and later releases for 32-bit processes only.
An extended shmat capability is available. If an environment variable EXTSHM=ON is defined then processes executing in that environment will be able to create and attach more than eleven shared memory segments.
The segments can be of size from 1 byte to 2GB, although for segments larger than 256MB in size the environment variable EXTSHM=ON is ignored. The process can attach these segments into the address space for the size of the segment. Another segment could be attached at the end of the first one in the same 256MB segment region. The address at which a process can attach is at page boundaries - a multiple of SHMLBA_EXTSHM bytes. For segments larger than 256MB in size, the address at which a process can attach is at 256MB boundaries, which is a multiple of SHMLBA bytes.
The segments can be of size from 1 byte to 256MB. The process can attach these segments into the address space for the size of the segment. Another segment could be attached at the end of the first one in the same 256MB segment region. The address at which a process can attach will be at page boundaries - a multiple of SHMLBA_EXTSHM bytes.
The maximum address space available for shared memory with or without the environment variable and for memory mapping is 2.75GB. An additional segment register "0xE" is available so that the address space is from 0x30000000 to 0xE0000000. However, a 256MB region starting from 0xD0000000 will be used by the shared libraries and is therefore unavailable for shared memory regions or mmapped regions.
There are some restrictions on the use of the extended shmat feature. These shared memory regions can not be used as I/O buffers where the unpinning of the buffer occurs in an interrupt handler. The restrictions on the use are the same as that of mmap buffers.
The smaller region sizes are not supported for mapping files. Regardless of whether EXTSHM=ON or not, mapping a file will consume at least 256MB of address space.
The SHM_SIZE shmctl command is not supported for segments created with EXTSHM=ON.
A segment created with EXTSHM=ON can be attached by a process without EXTSHM=ON. This will consume a 256MB area of the address space irrespective of the size of the shared memory region.
A segment created without EXTSHM=ON can be attached by a process with EXTSHM=ON. This will consume a 256MB area of the address space irrespective of the size of the shared memory region.
The environment variable provides the option of executing an application either with the additional functionality of attaching more than 11 segments when EXTSHM=ON, or the higher-performance access to 11 or fewer segments when the environment variable is not set.
| SharedMemoryID | Specifies an identifier for the shared memory segment. |
| SharedMemoryAddress | Identifies the segment or file attached at the address specified by the SharedMemoryAddress parameter, as follows:
|
| SharedMemoryFlag | Specifies several options. Its value is either 0 or is constructed by logically ORing one or more of the following values:
The shmat program makes a shared memory segment addressable by the current process. The segment is attached for reading if the SHM_RDONLY flag is set and the current process has read permission. If the SHM_RDONLY flag is not set and the current process has both read and write permission, it is attached for reading and writing. If the SHM_MAP flag is set, file mapping takes place. In this case, the shmat subroutine maps the file open on the file descriptor specified by the SharedMemoryID onto a segment. The file must be a regular file. The segment is then mapped into the address space of the process. A file of any size can be mapped if there is enough space in the user address space. When file mapping is requested, the SharedMemoryFlag parameter specifies how the file should be mapped. If the SHM_RDONLY flag is set, the file is mapped read-only. To map read-write, the file must have been opened for writing. All processes that map the same file read-only or read-write map to the same segment. This segment remains mapped until the last process mapping the file closes it. A mapped file opened with the O_DEFER update has deferred update. That is, changes to the shared segment do not affect the contents of the file resident in the file system until an fsync subroutine is issued to the file descriptor for which the mapping was requested. Setting the SHM_COPY flag changes the file to the deferred state. The file remains in this state until all processes close it. The SHM_COPY flag is provided only for compatibility with Version 2 of the operating system. New programs should use the O_DEFER open flag. A file descriptor can be used to map the corresponding file only once. To map a file several times requires multiple file descriptors. When a file is mapped onto a segment, the file is referenced by accessing the segment. The memory paging system automatically takes care of the physical I/O. References beyond the end of the file cause the file to be extended in page-sized increments. |
When successful, the segment start address of the attached shared memory segment or mapped file is returned. Otherwise, the shared memory segment is not attached, the errno global variable is set to indicate the error, and a value of -1 is returned.
The shmat subroutine is unsuccessful and the shared memory segment or mapped file is not attached if one or more of the following are true:
This subroutine is part of Base Operating System (BOS) Runtime.
The exec subroutine, exit subroutine, fclear subroutine, fork subroutine, fsync subroutine, mmap subroutine, munmap subroutine, openx subroutine, truncate subroutine, readvx subroutine, shmctl subroutine, shmdt subroutine, shmget subroutine, writevx subroutine.
List of Memory Manipulation Services, Subroutines Overview, Understanding Memory Mapping in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.