Crate crash_handler

🔥 crash-handler

Runs user-specified code when a crash occurs

Linux/Android

On Linux this is done by handling signals, namely the following.

One important detail of the Linux signal handling is that this crate hooks pthread_create so that an alternate signal stack is always installed on every thread. std::thread::Thread already does this, however hooking pthread_create allows us to ensure this occurs for threads created from eg. C/C++ code as well. An alternate stack is necessary to reliably handle a SIGSEGV caused by a stack overflow, as signals are otherwise handled on the same stack that raised the signal.

SIGABRT

Signal sent to a process to tell it to abort, i.e. to terminate. The signal is usually initiated by the process itself when it calls std::process::abort or libc::abort, but it can be sent to the process from outside itself like any other signal.

SIGBUS

Signal sent to a process when it causes a bus error.

SIGFPE

Signal sent to a process when it executes an erroneous arithmetic operation. Though it stands for floating point exception this signal covers integer operations as well.

SIGILL

Signal sent to a process when it attempts to execute an illegal, malformed, unknown, or privileged, instruction.

SIGSEGV

Signal sent to a process when it makes an invalid virtual memory reference, a segmentation fault. This covers infamous null pointer access, out of bounds access, use after free, stack overflows, etc.

SIGTRAP

Signal sent to a process when a trap is raised, eg. a breakpoint or debug assertion.

Windows

On Windows we catch exceptions, which cover a wide range of crash reasons, as well as invalid parameters and purecall

MacOS

On Macos we use exception ports. Exception ports are the first layer that exceptions are filtered, from a thread level, to a process (task) level, and finally to a host level.

If no user ports have been registered, the default Macos implementation is to convert the Mach exception into an equivalent Unix signal and deliver it to any registered signal handlers before performing the default action for the exception/signal (ie process termination). This means that if you use this crate in conjunction with signal handling on MacOs, you will not get the results you expect as the exception port used by this crate will take precedence over the signal handler. See this issue for a concrete example.

Note that there is one exception to the above, which is that SIGABRT is handled by a signal handler, as there is no equivalent Mach exception for it.

EXC_BAD_ACCESS

Covers similar crashes as SIGSEGV and SIGBUS

EXC_BAD_INSTRUCTION

Covers similar crashes as SIGILL

EXC_ARITHMETIC

Covers similar crashes as SIGFPE

EXC_BREAKPOINT

Covers similar crashes as SIGTRAP

Contribution

We welcome community contributions to this project.

Please read our Contributor Guide for more information on how to get started. Please also read our Contributor Terms before you make any contributions.

Any contribution intentionally submitted for inclusion in an Embark Studios project, shall comply with the Rust standard licensing model (MIT OR Apache 2.0) and therefore be dual licensed as described below, without any additional terms or conditions:

License

This contribution is dual licensed under EITHER OF

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

For clarity, “your” refers to Embark or any other licensee/user of the contribution.

Modules

jmp

FFI bindings for non-local goto

unix

The sole purpose of the unix module is to hook pthread_create to ensure an alternate stack is installed for every native thread in case of a stack overflow. This doesn’t apply to MacOS as it uses exception ports, which are always delivered to a specific thread owned by the exception handler

Macros

debug_print

Structs

CrashContext

The full context for a Linux/Android crash

CrashHandler

A Linux/Android signal handler

Enums

CrashEventResult

The result of the user code executed during a crash event

Error

An error that can occur when attaching or detaching a crate::CrashHandler

Signal

The signals that we support catching and raising

Traits

CrashEvent

User implemented trait for handling a crash event that has ocurred.

Functions

make_crash_event^⚠

Creates a CrashEvent using the supplied closure as the implementation.

make_single_crash_event^⚠

Creates a CrashEvent using the supplied closure as the implementation.

write_stderr

Writes the specified string directly to stderr.