semget (BPX1SGT, BPX4SGT) — Create or find a set of semaphores

Function

The semget function creates a new semaphore set or finds an existing semaphore set. The semaphore set ID is returned.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1SGT):	31-bit
AMODE (BPX4SGT):	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

CALL BPX1SGT,(Key,
              Number_of_Semaphores,
              Semaphore_Flags,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4SGT with the same parameters.

Parameters

Key

Supplied parameter

Type:: Integer
Length:: Fullword

Identification for this semaphore set. This is either a user-defined value that serves as a lookup value to determine if the semaphore set 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 semaphore set, or when it wants to privately control access to it by other processes.)

Number_of_Semaphores

Supplied parameter

Type:: Integer
Length:: Fullword

The number of semaphores that are to be allocated to this set. This value may be zero if the application knows that the semaphore set should already be created for the specified key parameter. A zero value is not allowed with Ipc_CREAT or Ipc_PRIVATE. The maximum for this variable is controlled by the installation. For an existing semaphore identifier, this variable must not be greater than the number of semaphores in that set.

Semaphore_Flags

Supplied parameter

Type:: Structure
Length:: Fullword

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

Ipc_CREAT: Creates a message queue if the key specified does not already have an associated ID. Ipc_CREAT is ignored when Ipc_PRIVATE is specified.
Ipc_EXCL: Causes the semget 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_BINSEM: Binary semaphore. The semaphore must behave in a binary manner: the number of semaphore operations must be 1, and the semop must be either 1 with a semval of 1, or -1 with a semval of 0 or 1. Specifying the SEM_UNDO flag in the SEM_FLGS field of BPXYSEM on a semop() request against a binary semaphore allows the semaphore to be released when a process exits without releasing it. The use of this flag improves performance if the PLO instruction is available on the hardware.
Ipc_SHORTHOLD: Indicates that the application will hold the resource that is being serialized for extremely short intervals of time. When the IPC_BINSEM flag is also specified, the default first-in-first-out ordering of semaphore obtain requesters is bypassed, allowing short duration requesters to cut to the front of the wait chain.
S_IRUSR: Permits the process that owns the semaphore set to read it.
S_IWUSR: Permits the process that owns the semaphore set to alter it.
S_IRGRP: Permits the group that is associated with the semaphore set to read it.
S_IWGRP: Permits the group that is associated with the semaphore set to alter it.
S_IROTH: Permits others to read the semaphore set.
S_IWOTH: Permits others to alter the semaphore set.

The values that begin with the "Ipc_" prefix are defined in BPXYIPCP and 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 the "S_I" prefix are defined in BPXYMODE, and are a subset of the access permissions that apply to files.

This operand is ignored if the semaphore set is already defined to the system.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the semget service returns the semaphore identifier or, if unsuccessful, -1.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

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

Return_code	Explanation
EACCES	A semaphore identifier exists for the Key parameter, but access permission, as specified by the low-order 9 bits of the Semaphore_Flags parameter, is not granted (the "S_" items). The following reason code can accompany the return code: JRIpcDenied.
EEXIST	A semaphore identifier exists for the Key parameter, and both Ipc_CREAT and Ipc_EXCL are specified. The following reason code can accompany the return code: JRIpcExists.
EINVAL	Number_of_Semaphores is not valid when: The semaphore identifier exists for the Key parameter and Number_of_Semaphores exceeds the number of semaphores previously defined. Number_of_Semaphores is zero. Number_of_Semaphores exceeds the system limit. This system limit is set with the IPCSEMNSEMS parameter in a BPXPRM parmlib member. You can use the ipcs -x shell command to view this value. The Semaphore_Flags parameter includes bits that are not supported by this function. The following reason codes can accompany the return code: JRSema4BadNSems, JRSema4ZeroNSems, JRSema4BigNSems, and JRIpcBadFlags.
ENOENT	A semaphore identifier does not exist for the Key parameter and Ipc_CREAT was not set. The following reason code can accompany the return code: JRIpcNoExists.
ENOSPC	A semaphore identifier is to be created, but the system-imposed limit on the maximum number of allocated semaphore identifiers system-wide would be exceeded. This system limit is set with the IPCSEMNIDS parameter in the BPXPRM parmlib member. You can use ipcs -x shell command to the view this value. You can use the ipcrm shell command to remove unused semaphore 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 semget service stores the reason code. The semget 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

Each semaphore in the semaphore set is represented by a data structure that is defined as follows:
semval

Unsigned halfword semaphore value

sempid

Process ID of last operation

semncnt

Unsigned halfword number of processes waiting for semval to become greater than current value

semzcnt

Unsigned halfword number of processes waiting for semval to become zero
When a semaphore set is created, the value of semval for all semaphores is set to zero.
As long as the semaphore ID is known and access is permitted, any thread can invoke semctl or semop without invoking semget.
This function returns the semaphore identifier that is associated with the Key parameter.
When it is successful, this function creates a data structure that is defined by SEMID_DS and an array that contains the number of semaphores specified, if one of the following is true:
- The Key parameter is equal to Ipc_PRIVATE.
- The Key parameter does not already have a semaphore identifier associated with it, and Ipc_CREAT is set.
For the data structure, see BPXYSEM — Map interprocess communication semaphores.
Upon creation, the data structure that is associated with the new semaphore 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 Semaphore_Flags parameter.
- SEM_NSEMS is set equal to the value of the Number_of_Semaphores parameter.
- SEM_OTIME is set to 0 and SEM_CTIME is set to the current time.
If the Key parameter is not Ipc_PRIVATE, Ipc_EXCL is not set, and a semaphore identifier already exists for the specified Key parameter, the value of the Number_of_Semaphores parameter that is specified may not exceed the Number_of_Semaphores specified on the semget that created the semaphore set.
The semaphore set is removed from the system as soon as BPX1SCT/BPX4SCT (semctl RMID) is processed.
Users of Ipc_PRIVATE semaphore sets are responsible for removing them when they are no longer needed. Failure to do so ties up resources.
Semaphores created with the Ipc_BINSEM attribute show this bit, and may also show the Ipc_PLOinUse bit, in the S_MODE byte that is returned with the w_getipc request.

Related services

Characteristics and restrictions

There is a maximum number of semaphore sets and semaphores that are allowed in the system.
The invoker is restricted by ownership, read, and read-write permissions that are defined by semget and semctl Ipc_SET.

Examples

For an example using this callable service, see BPX1SGT (semget) example.