sigprocmask (BPX1SPM, BPX4SPM) — Examine or change a process's signal mask

Function

The sigprocmask callable service examines, changes, or both examines and changes the calling thread's signal mask.

Requirements

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

AMODE 64 callers use BPX4SPM with the same parameters.

Parameters

How
Supplied parameter
Type:
Structure
Length:
Fullword
The name of a fullword that contains a numeric value that identifies the action that is to be taken on the thread's signal mask. The following constants, which are defined in BPXYSIGH, define the actions to be taken: See BPXYSIGH — Signal constants.
Constant Description
SIG_BLOCK# Add the signals in New_signal_mask to those to be blocked for this thread.
SIG_UNBLOCK# Delete the signals in New_signal_mask from those blocked for this thread.
SIG_SETMASK# Replace the thread's signal mask with New_signal_mask.
New_signal_mask
Supplied parameter
Type:
Address
Length:
Fullword

The name of a fullword that contains either 0 or the address of an 8-byte area that contains the 64-bit signal mask. The leftmost bit represents signal number 1, and the rightmost bit represents signal number 64. The New_signal_mask parameter is applied to the thread's signal mask as specified by the How parameter. Mask bits that are set on represent signals that are blocked. If zero, the signal mask is not changed, and the How parameter is ignored.

Old_signal_mask
Parameter supplied and returned
Type:
Address
Length:
Fullword

The name of a fullword that contains either 0 or the address of an 8-byte signal-mask return area. The service stores in this area the signal mask that was in effect, showing the signals that were blocked. The leftmost bit represents signal number 1, and the rightmost bit represents signal number 64. Mask bits set on represent signals that are blocked. A zero indicates that no signal mask was returned.

Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the sigprocmask service returns 0 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 sigprocmask service stores the return code. The sigprocmask 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 sigprocmask service can return one of the following values in the Return_code parameter:
Return_code Explanation
EFAULT The specified address for New_signal_mask or Old_signal_mask was incorrect.
EINVAL The value of the How parameter is not one of the allowable values.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the sigprocmask service stores the reason code. The sigprocmask 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 sigprocmask service examines, changes, or both examines and changes the signal mask for the calling thread. This mask is called the thread's signal mask. If there are any pending unblocked signals, either at the process level or at the current thread's level, after changing the signal mask, at least one of the signals is delivered to the thread before the sigprocmask service returns.
  2. In a multithreaded process, the sigprocmask service is used to control to which thread in the process a signal that is generated by the kill service is delivered. For example, if two threads in a process have SIGUSR1 signals blocked and one thread does not, the SIGUSR1 signal that is generated by the kill service from another process is delivered to the thread that does not have the signal blocked.
  3. You cannot block the SIGKILL, SIGSTOP, SIGTHSTOP, and SIGTHCONT signals. If you call the sigprocmask service with a request that would block those signals, that part of your request is ignored and no error is indicated.
  4. A request to block signals that are not supported is accepted, and a return value of zero is returned.
  5. All pending unblocked signals are moved from the process level to the current thread.
  6. See Optimizing performance using process- and thread-level information.

Related services

Characteristics and restrictions

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

Examples

For an example using this callable service, see BPX1SPM (sigprocmask) example.