sigaction (BPX1SIA, BPX4SIA) — Examine or change a signal action

Function

Requirements

Parameters

Signal

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the number of the signal to examine, set, or both set and examine the action for.

New_sa_handler_address

Supplied parameter

Type:

Address

Length:

Fullword (doubleword)

The name of a fullword (doubleword) that contains either zero or the address of a fullword that contains the new signal action.

• If it contains zero, no new action is set for this signal.
• If it is not zero, set the signal action using the options that are described in this topic and in the BPXYSIGH macro. See BPXYSIGH — Signal constants.

Constant	Description
SIG_DFL#	Take the default action for this signal.
SIG_IGN#	Ignore this signal.
Address	Address of the signal catcher function.

New_sa_mask

Supplied parameter

Type:

Structure

Length:

8 bytes

The name of an 8-byte area that contains a 64-bit mask of signals that are to be blocked during execution of the signal-catching function. The leftmost bit represents signal number 1, and the rightmost bit represents signal number 64. Bits that are set to 1 represent signals that are blocked.

You must always provide this field, even though New_sa_mask is not used when the New_sa_handler_address parameter contains a 0.

New_sa_flags

Supplied parameter

Type:

Structure

Length:

Fullword

The name of the fullword that contains the value of the signal action flags.

You must always provide this field, even though New_sa_flags is not used when the New_sa_handler_address parameter contains a 0.

New_sa_flags can be set to the following constants defined in the BPXYSIGH macro:

Constant	Description
SA_FLAGS_DFT#	None of the following functions.
SA_NOCLDSTOP#	Do not generate SIGCHLD signals to the calling process when its children stop or are continued. (This is used only when Signal is set to SIGCHLD).
SA_OLD_STYLE#	The PPSDOLDSTYLE flag is set. This is provided for the C compiler runtime library to implement old-style signal callable service functions. The C compiler runtime library's signal interface routine is responsible for checking PPSDOLDSTYLE and setting sigaction to default action where needed.
SA_ONSTACK#	The PPSDONSTACK flag is set. This is provided for the caller to implement alternate stack signal delivery processing.
SA_RESETHAND#	The PPSDRESETHAND flag is set. This is provided for the caller to reset the signal action to SIG_DFL# on entry to the signal catcher.
SA_RESTART#	The PPSDRESTART flag is set. This is provided for the caller to implement restart for functions that normally would receive an EINTR if a signal is delivered.
SA_SIGINFO#	The PPSDSIGINF flag is set. This is provided for the caller to provide additional information to the signal catcher, namely additional signal information and user context information.
SA_NOCLDWAIT#	Do not create zombie processes when children of the calling process exit (used only when Signal is set to SIGCHLD).
SA_NODEFER	The PPSDNODEFER flag is set. This is provided for the caller to not automatically block the Signal when the signal catcher is invoked.
SA_IGNORE	The value of the new_sa_handler is saved and returned on subsequent calls, but the signal is ignored.

Old_sa_handler_address

Parameter supplied and returned

Type:

Address

Length:

Fullword (doubleword)

The name of a fullword (doubleword) that contains either zero or the address of a fullword in which the system returns the old (current) signal action. If Old_sa_handler_address is specified as 0, the old signal action, Old_sa_mask, and Old_sa_flags, are not returned.

Old_sa_mask

Returned parameter

Type:

Structure

Length:

8 bytes

The name of an 8-byte area where the old (current) value of the 64-bit mask of signals blocked during execution of the signal-catching function is returned. Bits that are set to 1 represent signals that are blocked.

You must provide this parameter, although Old_sa_mask is not returned when Old_sa_handler_address contains 0.

Old_sa_flags

Returned parameter

Type:

Structure

Length:

Fullword

The name of the fullword in which the old (current) signal action flags are returned.

You must always provide this field, even though Old_sa_flags is not returned when Old_sa_handler_address contains 0.

User_data

Supplied parameter

Type:

Character

Length:

Fullword (doubleword)

The name of a fullword (doubleword) that contains 4 bytes of user-supplied data that is passed to the signal interface routine when the signal is delivered.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

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

Return_code	Explanation
EINVAL	The specified signal value is incorrect or is an unsupported signal number; an attempt was made to catch a signal that cannot be caught; or an attempt was made to ignore a signal that cannot be ignored. The following reason codes can accompany the return code: JRInvalidSignal and JRInvalidSigact.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the sigaction service stores the reason code. The sigaction 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. If New_sa_handler_address value is set to the action SIG_DFL for a signal that cannot be caught or ignored, the sigaction request is ignored and Return_value is set to 0.
2. Setting a signal action to ignore for a signal that is pending causes the pending signal to be discarded.
3. Setting signal action SIG_IGN or catch for signals SIGSTOP, SIGTHSTOP, SIGTHCONT, or SIGKILL is not allowed.
4. Setting signal action SIG_IGN for SIGIO is not allowed.
5. The SA_NOCLDWAIT flag should not be used with the waitpid (BPX1WAT, BPX4WAT) WNOHANG flag, or with the SIGSTOP or SIGCONT signals. Because the SA_NOCLDWAIT flag indicates that child processes of the calling process do not become zombies, these child processes do not report their status to the calling process when they end. Thus, if the calling process subsequently issues a waitpid call, it suspends until all of its child processes terminate, and then receives an ECHILD error return. This is expected behavior when SA_NOCLDWAIT is set. However, using SIGSTOP or SIGCONT signals with a child process could cause stop status to be reported to the calling process if it issues a subsequent waitpid call. Likewise, the use of the WNOHANG flag on a subsequent waitpid would result in an immediate return, instead of the process suspending until all child processes terminate. For these reasons, care should be taken not to mix these incompatible functions.
6. Setting signal action SIG_IGN for SIGCHLD has the same effect as setting the SA_NOCLDWAIT flag.
7. The SA_NOCLDSTOP and SA_NOCLDWAIT flags, despite having similar names, result in different types of actions. SA_NOCLDSTOP results in SIGCHLD signals not being sent when child processes stop or are continued. Setting SA_NOCLDWAIT results in child processes not becoming zombies or reporting their exit status, but SIGCHLD signals are still sent when child processes end.
8. The user data is delivered on a per-signal basis for the specific signal that is specified on this invocation. This field must be respecified if user data is desired for the next signal. This user data is set even if the action is SIG_DFT or SIG_IGN.
9. Although the user can be in supervisor state and any PSW key when this service is used, the kernel does not deliver signals to the signal interface routine until the task is running with a PSW key equal to the PSW key when the first callable service was entered and the process was created. See mvssigsetup (BPX1MSS, BPX4MSS) — Set up MVS signals.
10. The sigaction caller's thread must be registered for signals. You can register the thread by calling mvssigsetup, or, after signals are set up, by creating the thread with pthread_create. If the thread is not registered for signals, the sigaction service fails with a return code of EINVAL and a reason code of JRNotSigSetup. See mvssigsetup (BPX1MSS, BPX4MSS) — Set up MVS signals.
11. Constants that are used for this callable service are defined in the BPXYSIGH macro. See BPXYSIGH — Signal constants.

Related services

• 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

In a multithreaded process, the new signal action that is set by the sigaction service changes the signal action for all threads in the process.