shmat(2) DG/UX 4.30 shmat(2)
NAME
shmat - attach a shared memory segment
SYNOPSIS
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/shm.h>
char * shmat (shmid, shmaddr, shmflg)
int shmid;
char * shmaddr;
int shmflg;
PARAMETERS
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 Option flags. Used to select between the
various options for <shmaddr> and to choose
read-only or read-write access to the shared
memory segment. Valid flags are SHM_RND and
SHM_RDONLY.
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.
Licensed material--property of copyright holder(s) Page 1
shmat(2) DG/UX 4.30 shmat(2)
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 the superuser). 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
Licensed material--property of copyright holder(s) Page 2
shmat(2) DG/UX 4.30 shmat(2)
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
An 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.
EXCEPTIONS
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> modulos 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
Licensed material--property of copyright holder(s) Page 3
shmat(2) DG/UX 4.30 shmat(2)
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
The related system calls: exec(2), exit(2), fork(2),
intro(2), ipcrm(1), ipcs(1), shmctl(2), shmget(2),
memcntl(2).
Licensed material--property of copyright holder(s) Page 4