shmat (BPX1MAT, BPX4MAT) — Attach to a shared memory segment

Function

The shmat service attaches the shared memory segment that is associated with a shared memory identifier.

Amode 31:

Each shmat() to the same shared memory segment results in a storage OBTAIN in the user address space. A unique storage address is returned from shmat().
A display of attaches via the shell IPCS command will show each unique attach.

Amode 64:

Each shmat() to the same shared memory object is pointing to the same storage. The same storage address is returned from shmat().
When there are multiple attachers to the same memory object from within a process, the shell IPCS command shows just one attach for the object.
A maximum of 1000 attaches to the same memory object from a single process is allowed.

Requirements

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.

Format

The syntax format is as follows:

CALL BPX1MAT,(Shared_Memory_ID,
              Shared_Memory_Address,
              Shared_Memory_Flag,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers need an additional parameter:

CALL BPX4MAT,(Shared_Memory_ID,
              Shared_Memory_Address,
              Shared_Memory_Flag,
              Attached_Address
              Return_value,
              Return_code,
              Reason_code)

The Shared_Memory_Address parameter is a doubleword.

Parameters

Shared_Memory_ID

Supplied parameter

Type:: Integer
Length:: Fullword

Specifies the shared memory identifier that is returned by the shmget service.

Shared_Memory_Address

Supplied parameter

Type:: Address
Length:: Fullword (doubleword)

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.

If Shared_Memory_Address is a null pointer, the segment is attached at the first available address selected by the system that is on a page boundary; or on a megabyte boundary, if the shared memory segment is defined as an IPC_MEGA segment.
If Shared_Memory_Address is not a null pointer and Shm_RND is specified, the segment's storage address is 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.
If Shared_Memory_Address is not a null pointer and Shm_RND is not specified, the segment is attached at the address that is specified. If the shared memory segment is defined as an IPC_MEGA segment, the specified address must be a megabyte multiple, or the request is failed with an EINVAL.

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.

Shared_Memory_Flag

Supplied parameter

Type:: Integer
Length:: Fullword

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.

Attached_Address

Returned parameter (BPX4MAT only)

Type:: Integer
Length:: Doubleword

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.

Return_value

Returned parameter

Type:: Address
Length:: Fullword

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

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the shmat service stores the return code. The shmat service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The shmat service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	One of the following conditions occurred: Operation permission is denied to the caller. The combination of Shared_Memory_Flag and permissions denies the requester access. The following reason code can accompany the return code: JRIpcDenied. The caller's PSW key does not match the key of the shared memory segment (except that callers running in PSW key 8 can attach to a key 9 shared memory segment). The following reason code can accompany the return code: JrKeyMismatch.
EINVAL	Shared_Memory_ID is not a valid shared memory identifier, for one of the following reasons: Shared_Memory_Address is not zero, it is not on a page boundary, and SHM_RND was not specified. Shared_Memory_Address is not zero, it is not on a megabyte boundary, and SHM_RND was not specified. The storage at Shared_Memory_Address could not be obtained in the user's address space. The caller is not running with a PSW key of 2, 8, or 9. 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.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

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.

Usage notes

If an attempt is made to access memory outside the shared memory segment, normal address space storage is accessed.
It is the application's responsibility to determine the length of the shared memory segment that is attached.
If an attempt is made to update a shared memory segment that is attached with Shm_RDONLY access, a program check occurs.
Because of the nature of the mapping of shared memory segments to different addresses within the multiple processes it is attached to, relative addresses should be used as pointers within the shared memory segment.
The storage is allocated in subpool 129, which is associated with the job step task. This allows a thread to attach a shared memory segment and exit, allowing other threads in the process to access the storage.
See shmget (BPX1MGT, BPX4MGT) — Create/find a shared memory segment, usage note 10, for an explanation of the storage key chosen for a shared memory segment.
Above the bar, shared memory cannot be used in subspace mode.

Related services

Characteristics and restrictions

The invoker is restricted by ownership and read and write permissions defined by shmget and shmctl IPC_SET.
Restricted to callers running in PSW key 2, 8, or 9. Authorized users can exploit the IARVSERV macro directly to create shared memory in system keys.

Examples

For an example using this callable service, see BPX1MAT (shmat) example.