semctl (BPX1SCT, BPX4SCT) — Perform semaphore control operations

Function

The semctl service provides semaphore control operations. These functions include reading and changing the values of semaphores and removing a set of semaphores from the system.

Requirements

Operation Environment
Authorization: Supervisor state or problem state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX1SCT): 31-bit
AMODE (BPX4SCT): 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 BPX1SCT,(Semaphore_ID,
              Semaphore_Number
              Command,
              SValue  |  Argument_address ( Buffer | Array),
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4SCT with the same parameters. All parameter addresses and addresses in parameter structures are doublewords.

Parameters

Semaphore_ID
Supplied parameter
Type:
Integer
Length:
Fullword

Specifies the semaphore identifier.

Semaphore_Number
Supplied parameter
Type:
Integer
Length:
Fullword

Specifies the semaphore number. Semaphore_Number ranges from 0 to Number_of_Semaphores - 1. Use with Sem_GETVAL, Sem_SETVAL, Sem_GETNCNT and Sem_GETZCNT. This argument is ignored for all other commands.

Command
Supplied parameter
Type:
Integer
Length:
Fullword
The name of a fullword field that indicates the semaphore command that is to be executed. For the structure that contains these constants, see BPXYSEM — Map interprocess communication semaphores and BPXYIPCP — Map interprocess communication permissions. The values for Command are:
Sem_GETVAL
Returns the value of semval for the requested Semaphore_Number, if the current process has read permission.
Sem_SETVAL
Sets the semval for the requested Semaphore_Number to the contents of SValue, if the current process has alter permission. When this Command is successfully executed, the semadj values that correspond to this semaphore for all processes are cleared.
Sem_GETPID
Returns the ID of the most recent process to update the semaphore, if the current process has read permission.
Sem_GETNCNT
Returns the number of threads waiting on the semaphore to become greater than the current value, if the current process has read permission. See semop (BPX1SOP, BPX4SOP) — Perform semaphore serialization operations.
Sem_GETZCNT
Returns the number of threads waiting on the semaphore to become zero, if the current process has read permission. See semop (BPX1SOP, BPX4SOP) — Perform semaphore serialization operations.
Sem_GETALL
Stores all semaphore semvals into the array of halfwords that is pointed to by the Argument_address parameter, if the current process has read permission. It is the caller's responsibility to ensure that the storage that is allocated for the array is large enough to hold all semaphore elements. The number of semaphore values stored is SEM_NSEMS, which may be obtained using the Ipc_STAT command.
Sem_SETALL
Sets semvals according to the array that is pointed to by the Argument_address parameter, if the current process has alter permission. Each value must be zero or positive. When this Command is successfully executed, the semadj values that correspond to each specified semaphore in all processes are cleared. It is the caller's responsibility to ensure that the storage that is allocated for the array is large enough for all semaphore elements. The number of semaphore values read is SEM_NSEMS, which may be obtained using the Ipc_STAT command.

If IPC_BINSEM is specified on the semget call, this option should not be used when there is a possibility that other threads could be performing semaphore operations on this semaphore, as there may be no serialization while the semaphore values are being updated.

Ipc_STAT
Obtains status information about the semaphore that is identified by the Semaphore_ID parameter, if the current process has read permission. This information is stored in the buffer that is pointed to by the Argument_address parameter.
Ipc_SET
Sets the value of the IPC_UID, IPC_GID and IPC_MODE from the SEMID_DS data structure that is associated with Semaphore_ID into the SEMID_DS structure that is pointed to by Argument_address. Any value for IPC_UID and IPC_GID may be specified. Only the mode bits that are documented for semget argument Semaphore_Flags may be set. This Command can only be executed by a process that has an effective user ID equal either to that of a process with appropriate privileges (see Authorization) or to the value of IPC_CUID or IPC_UID in the SEMID_DS data structure that is associated with Semaphore_ID. This information is taken from the buffer that is pointed to by the Argument_address parameter. For the data structure, see BPXYSEM — Map interprocess communication semaphores, SEMID_DS DSECT.
Ipc_RMID
Removes the semaphore identifier that is specified by Semaphore_ID from the system and destroys the set of semaphores and the SEMID_DS data structure that are associated with it. This Command can only be executed by a process that has 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 SEMID_DS data structure that is associated with Semaphore_ID.
SValue
Supplied parameter
Type:
Integer
Length:
Fullword

Specifies the value to be set for the semaphore that is identified by the Semaphore_Number.

Argument_address (Buffer | Array)
Supplied parameter
Type:
Address
Length:
Fullword
The name of a field that contains the address of the Buffer, Array or a null.
Table 1. Calling parameters and commands
Number Command Buffer | Array Return Value
Sem No. GETVAL NA SemVal, -1
Sem No. SETVAL SValue 0, -1
Sem No. GETPID NA Pid, -1
Sem No. GETNCNT NA Count, -1
Sem No. GETZCNT NA Count, -1
NA GETALL Array, output 0, -1
NA SETALL Array, input 0, -1
NA STAT Buffer, output 0, -1
NA SET Buffer, input 0, -1
NA RMID NA 0, -1
Buffer
Supplied and returned parameter
Type:
Structure
Length:
Length of SEMID_DS.

The name of a fullword (doubleword) field that contains the address of a data area that is mapped by SEMID_DS. This field is used for stat and set.

Array
Supplied and returned parameter
Type:
Structure
Length:
GETALL - An array of 2-byte integers for each semaphore in the set equal to (SEM_NSEMS * 2).

SETALL - A 2-byte integer for each semaphore in the set equal to (SEM_NSEMS * 2).

SETVAL - A 4-byte integer for the specified semaphore. The valid range is 0 through the system limit.

Return_value
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the semctl service returns -1, if not successful, or the following when successful:
GETVAL
The value of semval is returned
GETPID
The value of sempid is returned
GETNCNT
The value of semncnt is returned
GETZCNT
The value of semzcnt is returned
All others
A value of zero is returned
Return_code
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the semctl service stores the return code. The semctl 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 semctl service can return one of the following values in the Return_code parameter:
Return_code Explanation
EACCES Operation permission (read or alter) is denied to the calling process. The following reason code can accompany the return code: JRIpcDenied.
EFAULT The Buffer or ARRAY parameter specified an address that caused the callable service to program check. The following reason code can accompany the return code: JRBadAddress.
EINVAL One of the following errors occurred:
  • Semaphore_ID is not a valid semaphore identifier.
  • Semaphore_Number is less than zero or greater than or equal to the number of semaphores in this set.
  • The Command parameter is not a valid command.
  • The mode bits were not valid (ipc_SET).
The following reason codes can accompany the return code: JRIpcBadFlags, JRIpcBadID, JRSema4BadSemN and JRBadEntryCode.
EPERM The Command was 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 SEMID_DS data structure that is associated with Semaphore_ID. The following reason code can accompany the return code: JRIpcDenied.
ERANGE The SETVAL or SETALL value exceeds the system-imposed maximum that is defined by SEM#MAX_VAL in BPXYSEM. The following reason code can accompany the return code: JRSema4BadValue.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

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

  1. 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 the last operation
    semncnt
    Unsigned halfword number of processes waiting for semval to become greater than the current value
    semzcnt
    Unsigned halfword number of processes waiting for semval to become zero
  2. The Semaphore_ID was obtained from semget (BPX1SGT, BPX4SGT).
  3. A semadj variable is maintained by the process for all of its threads. This adjustment value allows the kernel to restore semaphore values if a process terminates before it can issue a semop. It is the application's responsibility to maintain semadj values for process termination.
  4. Ipc_SET can change permissions, and may affect a thread's ability to use the semaphore functions.
  5. When a semaphore ID is removed (Ipc_RMID) from the system, all waiting threads regain control with RV=-1, RC=EIDRM, and RC=JRIpcRemoved.
  6. The remove is complete by the time control is returned to the caller.

Related services

Characteristics and restrictions

The invoker is restricted by ownership and read and read-write permissions that are defined by semget and semctl Ipc_SET.

Examples

For an example using this callable service, see BPX1SCT (semctl) example.

Parent topic: Callable services descriptions