shmat(2) DG/UX R4.11MU05 shmat(2)
NAME
shmat - attach a shared memory segment
SYNOPSIS
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/shm.h>
void * shmat (shmid, shmaddr, shmflg)
int shmid;
const void * shmaddr;
int shmflg;
where:
shmid The shared memory identifier of the shared segment to
attach
shmaddr The byte address at which to attach the shared segment (may
be defaulted to a system-selected value or rounded to a
system-specified address boundary)
shmflg SHM_RND or SHM_RDONLY, an option flag used to select
between the various options for shmaddr and to choose read-
only or read-write access to the shared memory segment
DESCRIPTION
Shmat attaches the shared memory segment associated with the shared
memory identifier specified by shmid to the data segment of the
calling process. The segment is attached at the byte address
specified by the caller as detailed below, for either read-write
access or read-only access. The length of the shared memory segment
is taken from the shared memory descriptor associated with shmid;
i.e., by the value of the shm_segsz field. There is no way to attach
only a portion of a shared memory segment.
The address where the segment is attached is returned upon successful
completion of the call. This address may be specified in one of
three ways:
· Explicitly without rounding.
If shmaddr is non-zero, and shmflg & SHM_RND is false, the
segment is attached at shmaddr. shmaddr must be a multiple of
the page size; otherwise, an error is returned.
· Explicitly with rounding.
If shmaddr is non-zero, and shmflg & SHM_RND is true, the
segment is attached at the address obtained by rounding down
shmaddr to a multiple of SHMLBA, specifically, to (shmaddr -
(shmaddr modulo SHMLBA))
· By default.
If shmaddr is zero, the segment is attached at the first
convenient address as selected by the system. NOTE: "first
convenient" address means the value is implementation
dependent, and may change from release to release. The value
is arbitrary and the user should not depend on how the address
is selected.
The segment is attached with read-only access if (shmflg &
SHM_RDONLY) evaluates to true, otherwise it is attached for reading
and writing.
Upon successful completion, this call changes the following fields in
the shared memory data structure associated with the shared segment:
shm_lpid Changed to equal the process identifier of the calling
process.
shm_atime Changed to equal the current time.
shm_nattach Incremented by 1.
There is a per-process limit on the number of shared segments a
process may have attached simultaneously. If the process is
currently at this system-imposed maximum, the attach operation will
not be performed. This limit is the same for ALL processes
regardless of process identifier (i.e., this limit does apply to
processes whose effective user id is root). This limit is specified
by the SHMSEG configuration variable.
A fork operation is an implicit attach operation, since a new process
inherits all attached shared memory segments from its parent. This
implicit attach alters only the shm_nattach field as described above
for an explicit attach; the shm_atime and shm_lpid fields are not
changed by this implicit attach. Note this implicit attach applies
to all attached shared memory segments. This includes IPC_PRIVATE
segments, and also segments that have been the target of the IPC_RMID
operation of shmctl, i.e., have been "deleted" but still exist
because their attach account (shm_nattach) has not become zero. This
exception is the only way such a "deleted" shared memory segment can
be attached.
Shmat will fail and not attach the shared memory segment if an error
occurs.
ACCESS CONTROL
The calling process must have read permission to the shared segment
as defined in the shm_perm field of the associated shared memory data
structure to attach for read-only access, and read and write
permission to attach for read-write access.
RETURN VALUE
address The shmat operation was successful; the value returned is
the starting byte address of the newly attached shared
memory segment.
-1 An error occurred. errno is set to indicate the error.
DIAGNOSTICS
Errno may be set to one of the following error codes:
EINVAL shmid is not a valid shared memory identifier.
EINVAL The rounding option was used; i.e., SHM_RND evaluates to
true and shmaddr is not equal to zero, but the value of
(shmaddr - (shmaddr modulo SHMLBA)) is an invalid address.
EINVAL shmaddr was given explicitly; i.e., shmaddr is not equal to
zero and SHM_RND evaluates to false, but the value of
shmaddr is not a multiple of the page size, or is an
invalid address.
EACCES Operation permission is denied to the calling process.
ENOMEM Either the kernel or the user data space is insufficient to
accommodate the attach request. This error may not recur
on subsequent calls, if other operations free the needed
space.
EMFILE The number of shared memory segments attached to the
calling process would exceed the system-imposed limit.
EAGAIN The system-imposed limit on space locked into physical
memory would be exceeded; the MCL_FUTURE memory locking
option is in effect for the calling process (see
memcntl(2)).
SEE ALSO
ipcrm(1), ipcs(1), intro(2), exec(2), exit(2), _exit(2), fork(2),
memcntl(2), shmctl(2), shmget(2).
Licensed material--property of copyright holder(s)