[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 2

shmat Subroutine

Purpose

Attaches a shared memory segment or a mapped file to the current process.

Library

Standard C Library (libc.a)

Syntax

#include <sys/shm.h>
void *shmat (SharedMemoryID, SharedMemoryAddress, SharedMemoryFlag)
intSharedMemoryID, SharedMemoryFlag;
const void *SharedMemoryAddress;

Description

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.

Parameters

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:
  • If the SharedMemoryAddress parameter is not equal to 0, and the SHM_RND flag is set in the SharedMemoryFlag parameter, the segment or file is attached at the next lower segment boundary. This address is given by (SharedMemoryAddress -(SharedMemoryAddress modulo SHMLBA_EXTSHM if environment variable EXTSHM=ON or SHMLBA if not.)

  • If the SharedMemoryAddress parameter is not equal to 0 and the SHM_RND flag is not set in the SharedMemoryFlag parameter, the segment or file is attached at the address given by the SharedMemoryAddress parameter. If this address does not point to a SHMLBA_EXTSHM boundary if the environment variable EXTSHM=ON or SHMLBA boundary if not, the shmat subroutine returns the value -1 and sets the errno global variable to the EINVAL error code.
SharedMemoryFlag Specifies several options. Its value is either 0 or is constructed by logically ORing one or more of the following values:
SHM_COPY Changes an open file to deferred update (see the openx subroutine). Included only for compatibility with previous versions of the operating system.
SHM_MAP Maps a file onto the address space instead of a shared memory segment. The SharedMemoryID parameter must specify an open file descriptor in this case.
SHMLBA Specifies the low boundary address multiple of a segment.
SHM_RDONLY Specifies read-only mode instead of the default read-write mode.
SHM_RND Rounds the address given by the SharedMemoryAddress parameter to the next lower segment boundary, if necessary.

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.

Return Values

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.

Error Codes

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:

EACCES The calling process is denied permission for the specified operation.
EAGAIN The file to be mapped has enforced locking enabled, and the file is currently locked.
EBADF A file descriptor to map does not refer to an open regular file.
EEXIST The file to be mapped has already been mapped.
EINVAL The SHM_RDONLY and SHM_COPY flags are both set.
EINVAL The SharedMemoryID parameter is not a valid shared memory identifier.
EINVAL The SharedMemoryAddress parameter is not equal to 0, and the value of (SharedMemoryAddress - (SharedMemoryAddress modulo SHMLBA_EXTSHM if the environment variable EXTSHM=ON or SHMLBA if not ) points outside the address space of the process.
EINVAL The SharedMemoryAddress parameter is not equal to 0, the SHM_RND flag is not set in the SharedMemoryFlag parameter, and the SharedMemoryAddress parameter points to a location outside of the address space of the process.
EMFILE The number of shared memory segments attached to the calling process exceeds the system-imposed limit.
ENOMEM The available data space in memory is not large enough to hold the shared memory segment.
ENOMEM The available data space in memory is not large enough to hold the mapped file data structure.
ENOMEM The requested address and length crosses a segment boundary. This is not supported when the environment variable EXTSHM=ON.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

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.


[ Previous | Next | Contents | Glossary | Home | Search ]