shmget (BPX1MGT, BPX4MGT) — Create/find a shared memory segment

Function

The shmget function returns a shared memory ID that it either created or was allowed to access.

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 (BPX1MGT):	31-bit
AMODE (BPX4MGT):	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 BPX1MGT,(Key,
              Shared_Memory_Size,
              Shared_Memory_Flags,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4MGT with the same parameters. The Shared_Memory_Size parameter is a doubleword.

Parameters

Key

Supplied parameter

Type:: Integer
Length:: Fullword

Identification for this shared memory segment. This is either a user defined value that serves as a lookup value to determine if the shared memory segment already exists, or the reserved value IPC_PRIVATE. (See BPXYIPCP — Map interprocess communication permissions. IPC_PRIVATE is sometimes used when a process does not want to share a memory segment because it wants to privately control access to it by other processes.)

Shared_Memory_Size

Supplied parameter

Type:: Integer
Length:: Fullword (doubleword)

A fullword (doubleword) field that contains the number of bytes of shared memory that are required. If IPC_MEGA is specified, the value must be a multiple of megabytes, or the request is failed with EINVAL. If IPC_GIGA is specified, the value must be a multiple of gigabytes, or the request is failed with EINVAL. If the caller is running in AMODE 64, the requested number of bytes will be rounded up to the nearest megabyte multiple.

Shared_Memory_Flags

Supplied parameter

Type:: Integer
Length:: Fullword

Valid values for this field include any combination of the following (additional bits cause an EINVAL):

IPC_CREAT

Creates a shared memory segment if the specified key does not already have an associated ID. IPC_CREAT is ignored when IPC_PRIVATE is specified.

IPC_EXCL

Causes the shmget function to fail if the key specified has an associated ID. IPC_EXCL is ignored when IPC_CREAT is not specified or when IPC_PRIVATE is specified.

IPC_MEGA

Allocates shared storage in megabyte multiples. Use IPC_MEGA to decrease ESQA storage utilization in support of shared memory segments.

IPC_GIGA

Allocates shared storage in gigabyte multiples. Use IPC_GIGA to decrease real storage utilization when running in AMODE 64.

IPC_BELOWBAR

For AMODE 64 callers, IPC_BELOWBAR forces the memory object to be allocated from below the 2-gigabyte address range. This allows 64-bit applications to share objects with 31-bit applications.

IPC_SHAREAS

Enables sharing of the same storage area from multiple processes in the same address space.

For AMODE 31 callers, this flag is only supported when the IPC_MEGA flag is also specified; otherwise, this flag is ignored.
For AMODE 64 callers, this flag is supported for all shared memory segments that are obtained above the 2G bar.

S_IRUSR

Permits the process that owns the memory segment to read it.

S_IWUSR

Permits the process that owns the memory segment to alter it.

S_IRGRP

Permits the group that is associated with the memory segment to read it.

S_IWGRP

Permits the group that is associated with the memory segment to alter it.

S_IROTH

Permits others to read the memory segment.

S_IWOTH

Permits others to alter the memory segment.

The values that begin with an "IPC_" prefix are defined in BPXYIPCP. They are mapped onto S_TYPE, which is in BPXYMODE. See BPXYIPCP — Map interprocess communication permissions and BPXYMODE — Map the mode constants of the file services.

The values that begin with an "S_I" prefix are defined in BPXYMODE, and are a subset of the access permissions that apply to files.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the shmget service returns the shared memory identifier or, if it is unsuccessful, -1.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the shmget service stores the return code. The shmget 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 shmget service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	One of the following conditions occurred: The shared memory identifier does not exist for the Key parameter, and either the Shared_Memory-Size parameter is zero or it is greater than the system-imposed maximum. This system-imposed maximum is set with the IPCSHMMPAGES parameter in a BPXPRMxx parmlib member. You can use the ipcs -x shell command to view this value. The shared memory identifier exists for the Key parameter, but the size of the segment that is associated with it is less than the Shared_Memory_Size parameter, and the Shared_Memory_Size parameter is not equal to 0. The Shared_Memory_Flags include bits that are not supported by this function. The following reason codes can accompany the return code: JRShmBadSize and JRIpcBadFlags.
EACCES	One of the following conditions occurred: A shared memory identifier exists for the Key parameter, but the operation permission, as specified by the low-order 9–bits of the Shared_Memory_Flags parameter, is not granted (the "S_" items). The following reason code can accompany the return code: JRIpcDenied. The caller is running in PSW key 2 but has a TCB key other than 2. The following reason code can accompany the return code: JrKeyMismatch
EEXIST	A shared memory identifier exists for the Key parameter, and both IPC_CREAT and IPC_EXCL were specified. The following reason code can accompany the return code: JRIpcExists.
ENOENT	A shared memory identifier does not exist for the Key parameter, and IPC_CREAT was not specified. The following reason code can accompany the return code: JRIpcNoExists.
ENOMEM	A shared memory identifier and associated shared memory segment are to be created, but the amount of system storage would exceed the system-imposed limit. The system limit is set with the IPCSHMSPAGES parameter in a BPXPRMxx parmlib member. You can use the ipcs -y shell command to view this value, which is displayed under SPAGES. The following reason code can accompany the return code: JRShmMaxSpages.
ENOSPC	A shared memory identifier is to be created, but the system-imposed limit on the maximum number of allocated shared memory identifiers system-wide would be exceeded. This system limit is set with the IPCSHMNIDS parameter in a BPXPRMxx parmlib member. You can use the ipcs -x shell command to view this value. You can use the ipcrm shell command to remove unused shared memory identifiers. The following reason code can accompany the return code: JRIpcMaxIDs.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the shmget service stores the reason code. The shmget 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.

Usage notes

When a shared memory segment has been created, subsequent shmget calls to find the existing shared memory segment must request a size that is less than or equal to the value that was specified when the shared memory segment was created.
As long as a task knows the shared memory segment ID, it may issue a shmat, shmctl or shmdt (shmget is not needed).
The shmget function returns the shared memory segment identifier that is associated with the Key parameter.
This function creates a data structure defined by SHMID_DS if one of the following is true:
- The Key parameter is equal to IPC_PRIVATE.
- The Key parameter does not already have a shared memory segment identifier associated with it, and IPC_CREAT is set.
For the data structure, see BPXYSHM—Map interprocess communication shared memory segments.
Upon creation, the data structure that is associated with the new shared memory segment identifier is initialized as follows:
- IPC_CUID and IPC_UID are set to the effective user ID of the calling process.
- IPC_CGID and IPC_GID are set to the effective group ID of the calling process.
- The low-order 9-bits of IPC_MODE are equal to the low-order 9-bits of the Shared_Memory_Flags parameter.
- SHM_OTIME is set to 0 and SHM_CTIME is set to the current time.
- The storage is initialized to nulls when the segment is created.
- The storage is allocated in key 8.
The shared memory segment is removed from the system when shmctl RMID is processed, and when all users have detached (with the shmdt service) or terminated.
The first shmget request to define a shared memory segment determines whether the segment has the IPC_MEGA/IPC_GIGA attribute (on the IPC_MEGA/IPC_GIGA option of the Shared_Memory_Flags parameter). Subsequent shmget requests, which use existing shared memory segments, have no effect on the IPC_MEGA attribute that is defined by that segment. In other words, the IPC_MEGA/IPC_GIGA option takes effect only for the first shmget request, and is ignored for all subsequent requests.
Shared memory segments created with the IPC_MEGA/IPC_GIGA attribute show this bit in the S_MODE byte that is returned with the w_getipc request.
Above the bar, shared memory cannot be used in subspace mode.
The user address space storage for a shared memory segment is normally obtained in storage key 8, except under the following special circumstances:
- The caller of BPX1MGT that initially creates a shared memory segment is running in PSW key 2 or 9 and either of the following is true:
  - The caller is running in AMODE 64 and the shared memory segment is neither of type IPC_MEGA nor type IPC_BELOWBAR.
  - The caller is running in AMODE 31 and the shared memory segment is of type IPC_MEGA.
Under these circumstances, the user address space storage is obtained in the key of the caller (either key 2 or key 9). Any subsequent use of the segment from any address space will cause the user address space storage to be obtained in the same storage key in which the segment was initially created. This is true regardless of the PSW key in which the caller is running at the time of any subsequent attach request.

Related services

Characteristics and restrictions

There is a maximum number of shared memory segments allowed in the system.
There is a system-imposed limit on the maximum segment size that is defined in the BPXPRMxx parmlib member.
The caller of the shmget 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 BPX1MGT (shmget) example.