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
|
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. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. 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 the reason codes, see z/OS UNIX System Services Messages and Codes.
Usage notes
- 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.
- 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.
- 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.
- 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.
- 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
For an example using this callable service, see BPX1SWT (sigwait) example.