__sigactionset (BPX1SA2, BPX4SA2) — Examine or change a set of signal actions

Function

The __sigactionset callable service examines, changes, or both examines and changes the actions that are associated with a set of signals.

Requirements

Operation Environment
Authorization: Supervisor state or problem state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX1SA2): 31-bit
AMODE (BPX4SA2): 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  BPX1SA2,(New_count,
               New_structure,
               Old_count,
               Old_structure,
               SsetOption_flags,
               Return_value,
               Return_code,
               Reason_code)

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

Parameters

New_count
Supplied parameter
Type:
Integer
Length:
Fullword

The name of a fullword that contains the number of array elements in New_structure. New_count must be in the range from 0 to 64. If New_structure is not provided, specify a count of 0.

New_structure
Supplied parameter
Type:
Address
Length:
Fullword (doubleword)

The name of a fullword (doubleword) field that contains the address that points to the beginning of the new structure. The new structure contains the layout of the desired parameters for sigaction: New_sa_handler_address, New_sa_flags, New_sa_mask, UserData, and ConsolMask. ConsolMask is a bit mask that defines all the signals that are to have the same action. New_sa_handler_address, New_sa_flags, New_sa_mask, and UserData are mapped by the BPXYSSET macro. See BPXYSSET — Map the sigaction set.

Old_count
Supplied and returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword that contains the number of array elements that are allowed within Old_structure on input. On output, Old_count contains the number of array elements that have been stored. If Old_count is too small to hold the number of array elements that are needed, return code ENOMEM is returned. When ENOMEM is returned, Old_count contains the number of array elements that are required to contain the current signal action state.

Old_count must be in the range from 0 to 64.

If Old_structure is not provided, specify a count of 0.

You may not pass a constant in Old_count. If a constant is passed, an EFAULT is generated when an attempt is made to store back the result on exit.

Old_structure
Supplied parameter
Type:
Address
Length:
Fullword (doubleword)

The name of a fullword (doubleword) field that contains the address that points to the beginning of the old structure. On output from the call to __sigactionset, Old_structure contains the number of signal actions specified in Old_count.

SsetOption_flags
Supplied parameter
Type:
Structure
Length:
Fullword

The name of the area in which the option flags are set. A leftmost bit (Sset_IgInvalid) set to 1 indicates signals that are not valid; signals that are not valid are to be ignored. Possible SsetOption_Flags: Sset_IgInvalid = X'80000000', which indicates that invalid signals and sigactions are to be ignored.

In the following example, Sset_IgInvalid is set to 1 and New_count is passed in as 3. New_structure has been given an address that points to the storage area that contains the five fields shown: ConsolidatedMask, New_sa_flags, New_sa_mask, and New_user_data.

Sset_IgInvalid is set to 1 and New_count is passed in as 3. New_structure was given an address that points to the storage area that contains the five fields shown: ConsolidatedMask, New_sa_flags, New_sa_mask, and New_user_data.
Note:
  1. New_count can range from 1 to the maximum number of signals.
  2. The signal handlers (a set of additional signals to be masked), option flags, and user data that is specified by the __sigactionset service, are shared by all threads within a process.
  3. In the example shown:
    • The first set defines the action for signals 5–64 to their default state. Because some of these signals are unsupported, the setting of SsetOption_flags (Sset_IgInvalid) tells __sigactionset to ignore unsupported signals.
    • The second set tells __sigactionset to ignore signals 3 (SIGABRT#) and 4 (SIGILL#).
    • The third set defines a signal catcher with a mask for signals 1 (SIGHUP#) and 2 (SIGINT#).
Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the __sigactionset 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 __sigactionset service stores the return code. The __sigactionset 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 __sigactionset service can return one of the following values in the Return_code parameter:

Return_code Explanation
EINVAL The specified signal is incorrect or is an unsupported signal number; an attempt was made to catch or ignore a signal that cannot be caught or ignored; or the specified signal value was not within the range from 0 to 64. The following reason codes can accompany the return code: JRInvalidSignal, JRInvalidSigact, and JRInvalidRange.
The following are examples of incorrect scenarios:
  • Sset_IgInvalid is set to 0, and any bit position ranging from 33 to 64 is on. JRInvalidSignal is returned.
  • Sset_IgInvalid is set to 0, and signal 7 (SIGSTOP#), signal 34 (SIGTHSTOP#), signal 35 (SIGTHCONT#), or signal 9 (SIGKILL#) is on. JRInvalidSigact is returned.
ENOMEM There is not enough memory available to hold the number of array elements required to contain the current signal action state. The following reason codes can accompany the return code: JRSsetTooSmall.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the __sigactionset service stores the reason code. The __sigactionset service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

  1. For full details about the sigaction() parameters, see sigaction (BPX1SIA, BPX4SIA) — Examine or change a signal action.
  2. In a multithreaded process, the new signal action that is set by the __sigactionset service changes the signal action for all threads in the process.
  3. If multiple masks have a bit set on for the same signal, the one that is set is the last one.
  4. If the caller of __sigactionset does not specify Sset_IgInvalid within SsetOption_flags, a return code of EINVAL is returned for all signals and sigactions that are not valid. You can bypass this error by setting Sset_IgInvalid to 1.
  5. If New_count is zero (indicating a query of old signal actions), no changes are made to the signal actions.
  6. If Old_count is zero, the __signactionset service does not return anything in Old_structure.

Related services

Characteristics and restrictions

None.

Examples

For an example using this callable service, see BPX1SA2 (__sigactionset) example.