shmctl (BPX1MCT, BPX4MCT) — Perform shared memory control operations
Function
The shmctl service provides a variety of shared memory control operations as specified by the Command parameter. These functions include reading and changing shared memory variables with the shmid_ds data structure, and removing a shared memory segment from the system.
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 (BPX1MCT): | 31-bit |
AMODE (BPX4MCT): | 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
|
AMODE 64 callers use BPX4MCT with the same parameters. The Buffer_address parameter is a doubleword.
Parameters
- Shared_Memory_ID
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
Specifies the shared memory identifier.
- Command
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword field that indicates the shared memory command that is to be executed. For the structure that contains these constants, see BPXYSHM—Map interprocess communication shared memory segments and BPXYIPCP — Map interprocess communication permissions. The values for Command are:- Ipc_STAT
- This command obtains status information about the shared memory that is identified by the Shared_Memory_ID parameter, if the current process has read permission. This information is stored in the area that is pointed to by the Buffer_address parameter and mapped by area MSQID_DS data structure. For the data structure, see BPXYSHM—Map interprocess communication shared memory segments, SHMID_DS DSECT.
- Ipc_SET
- This command sets the value of the IPC_UID, IPC_GID and IPC_MODE
from the SHMID_DS data structure that is associated with Shared_Memory_ID
into the SHMID_DS structure that is pointed to by the Buffer_address
parameter. Any value for IPC_UID and IPC_GID may be specified. Only
mode bits that are defined by semget under Semaphore_Flag argument
may be specified in the IPC_MODE field. This command can only be executed
by a process with an effective user ID equal to either that of a process
with appropriate privileges (see Authorization),
or to the value of IPC_CUID or IPC_UID in the SHMID_DS data structure
that is associated with Shared_Memory_ID. This information is taken
from the buffer pointed to by the Buffer_address parameter. For the
data structure, see BPXYSHM—Map interprocess communication shared memory segments, SHMID_DS DSECT.
For shared memory segments that were not created with the Ipc_MEGA option, the permissions that are in effect (IPC_MODE) when a process attaches a segment remain, even though these permissions may change. For shared memory segments that were created with the Ipc_MEGA option, the permissions that are set by this request take effect immediately. All processes that are currently attached to the shared memory segment are able to read only or read and write to it based on the permissions that are specified in the IPC_MODE.
The effect of the new mode on access is determined by the three parts of the mode field: the owner permissions, the group permissions, and other permissions. If all three read and all three write permissions in the new mode are off, the access for all attached processes is changed to read. If any of the three read permission bits is on without the corresponding write permission bit on, the access for all attached processes is changed to read. Otherwise, the access for all attached processes is changed to write.
- Ipc_RMID
- This command removes the shared memory identifier that is specified by Shared_Memory_ID from the system, and removes the shared memory segment and SHMID_DS data structure that are associated with it. This command can only be executed by a process with an effective user ID equal to either that of a process with appropriate privileges (see Authorization), or to the value of IPC_CUID or IPC_UID in the SHMID_DS data structure that is associated with Shared_Memory_ID.
- Buffer_address
- Supplied parameter
- Type:
- Address
- Length:
- Fullword (doubleword)
The name of a fullword (doubleword) field that contains the address of the buffer that is mapped by SHMID_DS. The shmctl service assumes that the size of this buffer is at least as large as SHMID_DS.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the shmctl service stores the return value, or a -1 if the operation is unsuccessful.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the shmctl service stores the return code. The shmctl 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 shmctl service can return one of the following values in the Return_code parameter:Return_code Explanation EACCES The command specified was Ipc_STAT, and the calling process does not have read permission. The following reason code can accompany the return code: JRIpcDenied. EFAULT The Buffer_Address parameter specified an address that caused the callable service to program check. The following reason code can accompany the return code: JRBadAddress. EINVAL This error code may be returned for the following reasons: - Shared_Memory_ID is not a valid shared memory identifier.
- The Command parameter is not a valid command.
- The mode bits were not valid (SET). The following reason codes can accompany the return code: JRIpcBadFlags, JRIpcBadID and JRBadEntryCode.
EPERM Command=IPC_RMID or IPC_SET, and the effective user ID of the caller is not that of a process with appropriate privileges (see Authorization), and is not the value of IPC_CUID or IPC_UID in the SHMID_DS data structure that is associated with Shared_Memory_ID. The following reason code can accompany the return code: JRIpcDenied. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the shmctl service stores the reason code. The shmctl 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.
- The remove operation is asynchronous to the return from the system call after the last attachment is broken.
- When a RMID is processed, no further attaches are allowed.
- Ipc_SET can change permissions, and may affect a thread's ability to use the shared memory functions.
- If an RMID was processed before a fork service, the child is not attached to the memory segment.
- Above the bar, shared memory cannot be used in subspace mode.
Related services
Characteristics and restrictions
The caller of the shmctl service is restricted by ownership and read and read-write permissions that are defined by shmget and shmctl Ipc_SET.
Examples
For an example using this callable service, see BPX1MCT (shmctl) example.