sigwait (BPX1SWT, BPX4SWT) — Wait for a signal

Function

The sigwait callable service waits for an asynchronous signal. If a signal that is specified in the signal set is sent to the invoker of sigwait, the value of that signal is returned to the invoker and the sigwait service ends.

Requirements

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

AMODE 64 callers use BPX4SWT with the same parameters.

Parameters

Signal_mask
Supplied parameter
Type:
Structure
Length:
8 bytes

The name of an 8-byte field area that contains a 64-bit signal mask that contains the set of signals that this task is to wait on. The leftmost bit represents signal 1, and the rightmost bit represents signal 64. Bits that are set to 1 represent signals that are waited on.

Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the sigwait service returns the signal if the request is successful, or -1 if it is not successful.

Return_code
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the sigwait service stores the return code. The sigwait service returns Return_code only if Return_value is -1.For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. The sigwait service can return one of the following values in the Return_code parameter:
Return_code Explanation
EINVAL The Signal_mask argument contained a signal that represents an incorrect signal number. The following reason code can accompany this return code: JRInvalidSignal.
Reason_Code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the sigwait service stores the reason code. The sigwait service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.

Usage notes

  1. If any signals that are specified in Signal_mask are pending upon invocation of the sigwait service, one of those signals has its value returned to the invoker, and that signal is cleared from the set of pending signals.
  2. If there are no pending signals that were specified in Signal_mask, the sigwait service waits until a signal that is specified in Signal_mask is generated. A signal mask of zero causes the caller to wait until the task or process is terminated.
  3. If sigwait is invoked for a SIGKILL, SIGSTOP, or SIGTHSTOP signal, and a SIGKILL, SIGSTOP, or SIGTHSTOP signal arrives, the value of the signal is not returned to the invoker. Rather, the SIGKILL, SIGSTOP, or SIGTHSTOP action occurs.
  4. The current sigaction ( sigaction (BPX1SIA, BPX4SIA) — Examine or change a signal action) that is associated with a signal that is returned is not performed. This action also remains unchanged by the use of the sigwait service.
  5. If there are multiple threads in a process that have issued a sigwait for the same signal, exactly one of these threads returns from sigwait with the signal number if the signal was directed at the process.

Related services

Characteristics and restrictions

There are no restrictions on the use of the sigwait service.

Examples

See BPX1SWT (sigwait) example.