sigsuspend (BPX1SSU, BPX4SSU) — Change the signal mask and suspend the thread until a signal is delivered

Function

The sigsuspend callable service replaces a thread's current signal mask with a new signal mask. It then suspends the caller's thread until delivery of a signal whose action is either to process a signal-catching service or to end the thread.

Requirements

Operation Environment
Authorization: Problem Program or Supervisor State, PSW key when the process was created (not PSW key 0)
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX1SSU): 31-bit
AMODE (BPX4SSU): 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 BPX1SSU,(Signal_mask,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4SSU with the same parameter.

Parameters

Signal_mask
Supplied parameter
Type:
Structure
Length:
8 bytes

The name of an 8-byte area that contains a 64-bit signal mask that is set before waiting for a signal, and during the execution of any signal catcher. The leftmost bit represent signals 1 and the rightmost bit represents signal 64. Bits that are set to 1 represent signals that are blocked.

Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the sigsuspend service returns a -1 if it returns to its caller.

Return_code
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the sigsuspend service stores the return code. The sigsuspend 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 sigsuspend service can return one of the following values in the Return_code parameter:
Return_code Explanation
EINTR A signal was received and handled successfully.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

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

  1. The caller's thread starts running again when it receives one of the signals that are not blocked by the mask that is set by this call, or when a system failure occurs that sets Return_code to some value other than EINTR.
  2. The signal mask represents a set of signals that are to be blocked. Blocked signals do not "wake up" the suspended service. The signals SIGSTOP, SIGTHSTOP, SIGTHCONT, and SIGKILL cannot be blocked or ignored; they are delivered to the program no matter what the signal mask specifies.
  3. If the signal action is to end the thread, the sigsuspend service does not return.
  4. If the signal interruption is to give control to the signal interface routine (SIR), which is defined by the mvssigsetup service, the SIR is given control with the following PPSD fields:
    PPSDSAMASK
    Set to the New_sa_mask value, which is set by the sigaction service, for the signal number that caused the interruption.
    PPSDCURRENTMASK
    The signal mask value that existed before the sigsuspend service was called.

    To be XPG4 compliant, this is the signal mask that is installed when a signal catcher performs a normal return.

    PPSDCATCHERMASK
    The signal mask that is specified on the sigsuspend service.

    To be XPG4 compliant, the signal mask that is installed before calling a signal catcher is calculated by taking the union of PPSCATCHERTMASK, PPSDSAMASK, and the signal that caused the interrupt.

  5. The signal interface routine (SIR) that is defined by the mvssigsetup service is given control only when the PSW key of the sigsuspend caller is equal to the signal catcher key of the process. The signal catcher key is set to the PSW key of the caller of the first z/OS UNIX callable service that created the process.
  6. If the caller has a PSW key that is different from the signal catcher key, or has a PSW key of zero, the sigsuspend service returns with a return code of EMVSERR and reason code of JRPSWKeyNotValid.
  7. All pending unblocked signals are moved from the process level to the current thread.

Related services

Characteristics and restrictions

See The relationship of z/OS UNIX signals to callable services.

Examples

See BPX1SSU (sigsuspend) example for an example using this callable service.

Parent topic: Callable services descriptions