Utilities for handling POSIX signals. More...

#include "util/posix/signals.h"

Classes
class	OldActions
	A group of `struct sigaction` structures corresponding to a set of signals’ previous actions, addressable by signal number. More...

Public Types
using	Handler = void()(int, siginfo_t , void *)
	The type used for `struct sigaction::sa_sigaction`.

Static Public Member Functions
static bool	InstallHandler (int sig, Handler handler, int flags, struct sigaction *old_action)
	Installs a new signal handler. More...

static bool	InstallDefaultHandler (int sig)
	Installs `SIG_DFL` for the signal sig. More...

static bool	InstallCrashHandlers (Handler handler, int flags, OldActions old_actions, const std::set< int > unhandled_signals=nullptr)
	Installs a new signal handler for all signals associated with crashes. More...

static bool	InstallTerminateHandlers (Handler handler, int flags, OldActions *old_actions)
	Installs a new signal handler for all signals associated with termination. More...

static bool	WillSignalReraiseAutonomously (const siginfo_t *siginfo)
	Determines whether a signal will be re-raised autonomously upon return from a signal handler. More...

static void	RestoreHandlerAndReraiseSignalOnReturn (const siginfo_t siginfo, const struct sigaction old_action)
	Restores a previous signal action and arranges to re-raise a signal on return from a signal handler. More...

static bool	IsCrashSignal (int sig)
	Determines whether a signal is associated with a crash. More...

static bool	IsTerminateSignal (int sig)
	Determines whether a signal is associated with termination. More...

Static Public Attributes
static constexpr int	kSimulatedSigno = -1
	A signal number used by Crashpad to simulate signals.

Detailed Description

Utilities for handling POSIX signals.

Member Function Documentation

◆ InstallCrashHandlers()

bool crashpad::Signals::InstallCrashHandlers	(	Handler	handler,
		int	flags,
		OldActions *	old_actions,
		const std::set< int > *	unhandled_signals = `nullptr`
	)

static

Installs a new signal handler for all signals associated with crashes.

Signals associated with crashes are those whose default dispositions involve creating a core dump. The precise set of signals involved varies between operating systems.

A single signal may either be associated with a crash or with termination (see InstallTerminateHandlers()), and perhaps neither, but never both.

Parameters

[in]	handler	A signal-handling function to execute, used as the `struct sigaction::sa_sigaction` field when calling `sigaction()`.
[in]	flags	Flags to pass to `sigaction()` in the `struct sigaction::sa_flags` field. `SA_SIGINFO` will be specified implicitly.
[out]	old_actions	The previous actions for the signals, replaced by the new action. May be `nullptr` if not needed. The same old_actions object may be used for calls to both this function and InstallTerminateHandlers().
[in]	unhandled_signals	Signal handlers will not be installed for signal numbers in this set. Optional.

Returns: true on success. false on failure with a message logged.

Warning: This function may not be called from a signal handler because of its use of logging. See RestoreHandlerAndReraiseSignalOnReturn() instead.

◆ InstallDefaultHandler()

bool crashpad::Signals::InstallDefaultHandler ( int sig )

static

Installs SIG_DFL for the signal sig.

Parameters

[in] sig The signal to set the default action for.

Returns: true on success, false on failure with errno set. No message is logged.

◆ InstallHandler()

bool crashpad::Signals::InstallHandler	(	int	sig,
		Handler	handler,
		int	flags,
		struct sigaction *	old_action
	)

static

Installs a new signal handler.

Parameters

[in]	sig	The signal number to handle.
[in]	handler	A signal-handling function to execute, used as the `struct sigaction::sa_sigaction` field when calling `sigaction()`.
[in]	flags	Flags to pass to `sigaction()` in the `struct sigaction::sa_flags` field. `SA_SIGINFO` will be specified implicitly.
[out]	old_action	The previous action for the signal, replaced by the new action. May be `nullptr` if not needed.

Returns: true on success. false on failure with a message logged.

Warning: This function may not be called from a signal handler because of its use of logging. See RestoreHandlerAndReraiseSignalOnReturn() instead.

◆ InstallTerminateHandlers()

bool crashpad::Signals::InstallTerminateHandlers	(	Handler	handler,
		int	flags,
		OldActions *	old_actions
	)

static

Installs a new signal handler for all signals associated with termination.

Signals associated with termination are those whose default dispositions involve terminating the process without creating a core dump. The precise set of signals involved varies between operating systems.

A single signal may either be associated with termination or with a crash (see InstalCrashHandlers()), and perhaps neither, but never both.

Parameters

[in]	handler	A signal-handling function to execute, used as the `struct sigaction::sa_sigaction` field when calling `sigaction()`.
[in]	flags	Flags to pass to `sigaction()` in the `struct sigaction::sa_flags` field. `SA_SIGINFO` will be specified implicitly.
[out]	old_actions	The previous actions for the signals, replaced by the new action. May be `nullptr` if not needed. The same old_actions object may be used for calls to both this function and InstallCrashHandlers().

Returns: true on success. false on failure with a message logged.

Warning: This function may not be called from a signal handler because of its use of logging. See RestoreHandlerAndReraiseSignalOnReturn() instead.

◆ IsCrashSignal()

bool crashpad::Signals::IsCrashSignal ( int sig )

static

Determines whether a signal is associated with a crash.

Signals associated with crashes are those whose default dispositions involve creating a core dump. The precise set of signals involved varies between operating systems.

Parameters

[in] sig The signal to test.

Returns: true if sig is associated with a crash. false otherwise.

Note: This function is safe to call from a signal handler.

◆ IsTerminateSignal()

bool crashpad::Signals::IsTerminateSignal ( int sig )

static

Determines whether a signal is associated with termination.

Signals associated with termination are those whose default dispositions involve terminating the process without creating a core dump. The precise set of signals involved varies between operating systems.

Parameters

[in] sig The signal to test.

Returns: true if sig is associated with termination. false otherwise.

Note: This function is safe to call from a signal handler.

◆ RestoreHandlerAndReraiseSignalOnReturn()

void crashpad::Signals::RestoreHandlerAndReraiseSignalOnReturn	(	const siginfo_t *	siginfo,
		const struct sigaction *	old_action
	)

static

Restores a previous signal action and arranges to re-raise a signal on return from a signal handler.

Parameters

[in]	siginfo	A pointer to a `siginfo_t` object received by a signal handler.
[in]	old_action	The previous action for the signal, which will be re-established as the signal’s action. May be `nullptr`, which directs the default action for the signal to be used.

If this function fails, it will immediately call _exit() and set an exit status of 191.

Note: This function may only be called from a signal handler.

◆ WillSignalReraiseAutonomously()

bool crashpad::Signals::WillSignalReraiseAutonomously ( const siginfo_t * siginfo )

static

Determines whether a signal will be re-raised autonomously upon return from a signal handler.

Certain signals, when generated synchronously in response to a hardware fault, are unrecoverable. Upon return from the signal handler, the same action that triggered the signal to be raised initially will be retried, and unless the signal handler took action to mitigate this error, the same signal will be re-raised. As an example, a CPU will not be able to read unmapped memory (causing SIGSEGV), thus the signal will be re-raised upon return from the signal handler unless the signal handler established a memory mapping where required.

It is important to distinguish between these synchronous signals generated in response to a hardware fault and signals generated asynchronously or in software. As an example, SIGSEGV will not re-raise autonomously if sent by kill().

This function distinguishes between signals that can re-raise autonomously, and for those that can, between instances of the signal that were generated synchronously in response to a hardware fault and instances that were generated by other means.

Parameters

[in] siginfo A pointer to a siginfo_t object received by a signal handler.

Returns: true if the signal being handled will re-raise itself autonomously upon return from a signal handler. false if it will not. When this function returns false, a signal can still be re-raised upon return from a signal handler by calling raise() from within the signal handler.

Note: This function is safe to call from a signal handler.

The documentation for this class was generated from the following files:

util/posix/signals.h
util/posix/signals.cc

Classes

Public Types

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ InstallCrashHandlers()

◆ InstallDefaultHandler()

◆ InstallHandler()

◆ InstallTerminateHandlers()

◆ IsCrashSignal()

◆ IsTerminateSignal()

◆ RestoreHandlerAndReraiseSignalOnReturn()

◆ WillSignalReraiseAutonomously()