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
|
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.