crashpad::Signals Class Reference

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)
| 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
| ) |  |

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().

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