__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
|
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.
Note:- New_count can range from 1 to the maximum number of signals.
- 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.
- 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
- For full details about the sigaction() parameters, see sigaction (BPX1SIA, BPX4SIA) — Examine or change a signal action.
- 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.
- If multiple masks have a bit set on for the same signal, the one that is set is the last one.
- 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.
- If New_count is zero (indicating a query of old signal actions), no changes are made to the signal actions.
- If Old_count is zero, the __signactionset service does not return anything in Old_structure.
Related services
- sigaction (BPX1SIA, BPX4SIA) — Examine or change a signal action
- exec (BPX1EXC, BPX4EXC) — Run a program
- kill (BPX1KIL, BPX4KIL) — Send a signal to a process
- mvssigsetup (BPX1MSS, BPX4MSS) — Set up MVS signals
- sigprocmask (BPX1SPM, BPX4SPM) — Examine or change a process's signal mask
- sigsuspend (BPX1SSU, BPX4SSU) — Change the signal mask and suspend the thread until a signal is delivered
Characteristics and restrictions
None.
Examples
For an example using this callable service, see BPX1SA2 (__sigactionset) example.