sigtimedwait (BPX1STW, BPX4STW) — Wait for a signal with a specified timeout

Function

The sigtimedwait callable service suspends the invoking thread until either the specified timeout expires, or a signal specified in the signal set becomes pending, at either the process or the invoking thread. If a signal that is specified in the signal set is sent to the invoker of sigtimedwait, the value of that signal is returned to the invoker and the sigtimedwait service ends.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, PSW key when the process was created (not PSW key 0)
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1STW):	31-bit
AMODE (BPX4STW):	64-bit
ASC mode:	Primary address space control (ASC) 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 BPX1STW,(Signal_mask,
              Siginfo_ptr
              Siginfo_len,
              Seconds,
              Nanoseconds,
              Return_value,
              Return_code,
              Reason_code)

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

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.

Siginfo_ptr

Supplied parameter

Type:: Address
Length:: Fullword (doubleword)

The name of a fullword (doubleword) that contains the address of user-supplied storage that is mapped by the BPXYSINF macro (see BPXYSINF — Map SIGINFO_T structure). If this address is nonzero, the sigtimedwait service uses this area to place additional signal information when a signal number is returned in Return_value. If this address is zero, or if an error is returned, no additional information is returned in this area.

Siginfo_len

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the user-supplied storage that is mapped by the BPXYSINF macro. If the address of Siginfo_ptr is zero, this parameter is ignored.

Seconds

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains an unsigned integer representing the maximum number of seconds that the calling program is willing to wait for one of the specified signals to become pending.

Note:

Seconds can be any value greater than or equal to 0 and less than or equal to 4 294 967 295. The value specified for Seconds must be an unsigned integer.
The values in the Seconds and Nanoseconds parameters are combined to determine the timeout value. A combined value of zero indicates that the sigtimedwait service does not wait at all. A value of SIG#NO_TIMEOUT (see BPXYSIGH — Signal constants) indicates that no timeout value is set.

Nanoseconds

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains an unsigned integer representing the number of nanoseconds to be added to the value specified by the Seconds parameter. Nanoseconds can be any value greater than or equal to 0 and less than or equal to 1 000 000 000.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the sigtimedwait 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 sigtimedwait service stores the return code. The sigtimedwait service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The sigtimedwait service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	One or more of the parameters that were passed to this service are in error. The following reason codes unique to the sigtimedwait service can accompany the return code: JRNanoSecondsTooBig, JRInvalidSignal.
EAGAIN	The service timed out before any of the specified signals became pending on the invoking thread.
EINTR	The service received a signal that was not specified in the input signal mask.

Reason_Code

Returned parameter

Type:: Integer
Length:: Fullword

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

The sigtimedwait service behaves in the same way as the sigwait service, except that with the sigtimedwait service you can specify a timeout value.
If a nonzero address is specified for the siginfo_ptr parameter, the sigtimedwait service also returns si_signo, si_code, and si_value, as mapped by BPXYSINF.
A timeout value of zero (Seconds + Nanoseconds) means that the sigtimedwait service does not wait at all. It checks for pending signals, and if no signal is found, it returns with an error of EAGAIN. If a signal is found, the service returns with the signal number of the pending signal.
A passed timeout value of SIG#NO_TIMEOUT (see BPXYSIGH — Signal constants) indicates that no timeout value is set. The sigtimedwait service waits until a signal becomes pending.

sigtimedwait (BPX1STW, BPX4STW) — Wait for a signal with a specified timeout

Function

Requirements

Format

Parameters

Usage notes

Related services

Characteristics and restrictions

Examples