The shmat service attaches the shared memory segment that is associated with a shared memory identifier.
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state; PSW key 2, 8, or 9 |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1MAT): | 31-bit |
AMODE (BPX4MAT): | 64-bit |
ASC mode: | Primary mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
|
|
Specifies the shared memory identifier that is returned by the shmget service.
For BPX1MAT, the name of a field that contains a 31-bit address of where in the caller's address space storage is to be obtained and the segment is to be attached, or a 31-bit zero.
For BPX4MAT, the name of a field that contains a 64-bit address of where in the caller's address space storage is to be obtained and the segment is to be attached, or a 64-bit zero.
For BPX4MAT, the address must always be the same, and it must be above the bar.
If the shared memory segment is defined as an IPC_MEGA segment, the value that is specified in Shared_Memory_Address must be either zero or equal to or greater than 16 megabytes; otherwise, the request fails with an EINVAL.
If the segment being attached is above the 2G bar (that is, it is a 64-bit address), the Shared_Memory_Address must either be zero or the same address that was returned on the shmgt() call. If the segment being attached is below the bar (that is, it was created with option IPC_BELOWBAR or IPC_MEGA on the BPX4MGT call), then the Shared_Memory_Address follows the same rules as for BPX1MAT callers.
Shm_RDONLY identifies the segment that is to be attached for read only; otherwise, the segment is attached for read and write. Shm_RDONLY has no effect for attaches to shared memory segments that are created with the IPC_MEGA option. Whether the segment is attached read only or read and write depends on how it is currently accessed by other attaches, as all users have the same access to shared memory that is created with the IPC_MEGA option.
Shm_RND causes the Shared_Memory_Address to be truncated to a page boundary (last 12 bits zero), or to a megabyte boundary (last 20 bits zero) if the shared memory segment is defined as an IPC_MEGA segment.
The name of a doubleword in which the shmat service returns the shared memory segment address (the address that is to be passed to the detach) when Return_value is zero.
The name of a fullword in which the shmat service returns the shared memory segment address (the address that is to be passed to the detach), or -1, if the operation is not successful.
Return_code | Explanation |
---|---|
EACCES | One of the following conditions occurred:
|
EINVAL | Shared_Memory_ID is not a valid shared memory identifier, for
one of the following reasons:
The following reason codes can accompany the return code: JRIpcBadID, JRBadAddress, JRNoUserStorage, JRStorNotAvail, or JrUnsupportedKey. |
EMFILE | The number of shared memory segments attached to the caller's process exceeds the system-imposed maximum. This system limit is set with the IPCSHMNSEGS parameter in a BPXPRMxx parmlib member. You can use the ipcs -x shell command to view this value. The following reason code can accompany the return code: JRShmMaxAttach. |
ENOMEM | The available system storage is not large enough to accommodate the shared memory segment. The following reason codes can accompany the return code: JRNoUserStorage, JRSMNoStorage, JRIarvserv or JRShrStgShortage. |
The name of a fullword in which the shmat service stores the reason code. The shmat service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.
For an example using this callable service, see BPX1MAT (shmat) example.