segfault-raub

Segfault handler for Node.js

This is a part of Node3D project.

npm i -s segfault-raub

This module report debug information on process crash (and some other events). It doesn't affect the performance while the program is running normally.

The module prints to both STDERR and to the "segfault.log" file (if it exists inside "working directory"). If there is no such file, it won't be created, so it is up to you if the log-file is needed.

Note: this addon uses N-API, and therefore is ABI-compatible across different Node.js versions. Addon binaries are precompiled and there is no compilation step during the npm i command.

A zero-setup is available: just require the module and it comes pre-equipped with several signal listeners enabled by default.

require('segfault-raub');

Note: if your project tree contains multiple versions of this module, the first one imported will seize global['segfault-raub']. The rest of them will only re-export global['segfault-raub'] and WILL NOT import their own binaries.

---

If you want to use a custom location instead of "segfault.log", use:

require('segfault-raub').setLogPath("C:/my/log/file.txt");

You must create this file first, it must be there when the crash happens.

See the TypeScript declarations with comments.

Configuring Signals

As listed below, some signals (platform specific) are enabled by default. But they can be enabled/disabled manually:

Example:

const {
    setSignal,
    EXCEPTION_ACCESS_VIOLATION, SIGSEGV,
    EXCEPTION_BREAKPOINT, SIGTRAP,
} = require('segfault-raub');

setSignal(EXCEPTION_ACCESS_VIOLATION, false);
setSignal(SIGSEGV, false);

setSignal(EXCEPTION_BREAKPOINT, true);
setSignal(SIGTRAP, true);

// This enables capturing every signal on Windows.
setSignal(EXCEPTION_ALL, true);

On Windows, all the Unix signals are null, and the opposite is true. Passing null as the first parameter to setSignal has no effect and is safe.

Demo Methods

These are be helpful to see how the signals are reported and if the log files are being written properly.

• causeSegfault - Causes a memory access violation.
• causeDivisionInt - Divides an integer by zero.
• causeOverflow - Runs infinite recursion (stack overflow).
• causeIllegal - Raises an "illegal instruction" exception.

Example:

const { causeSegfault } = require('segfault-raub');
causeSegfault();

Windows Signals

Signal	Enabled	Description
EXCEPTION_ALL	no	All of the below.
EXCEPTION_ACCESS_VIOLATION	yes	Memory access was denied.
EXCEPTION_ARRAY_BOUNDS_EXCEEDED	yes	Array was accessed with an illegal index.
EXCEPTION_INT_DIVIDE_BY_ZERO	yes	Attempt to divide by an integer divisor of 0.
EXCEPTION_ILLEGAL_INSTRUCTION	yes	Attempt to execute an illegal instruction.
EXCEPTION_NONCONTINUABLE_EXCEPTION	yes	Can't continue after an exception.
EXCEPTION_STACK_OVERFLOW	yes	The thread used up its stack.
EXCEPTION_INVALID_HANDLE	yes	An invalid handle was specified.
EXCEPTION_FLT_DIVIDE_BY_ZERO	no	Attempt to divide by a float divisor of 0.f.
EXCEPTION_DATATYPE_MISALIGNMENT	no	A datatype misalignment was detected.
EXCEPTION_BREAKPOINT	no	A Breakpoint has been reached.
EXCEPTION_SINGLE_STEP	no	Continue single-stepping execution.
EXCEPTION_FLT_DENORMAL_OPERAND	no	One of the operands is denormal.
EXCEPTION_FLT_INEXACT_RESULT	no	The result cannot be represented exactly.
EXCEPTION_FLT_INVALID_OPERATION	no	Floating-point invalid operation.
EXCEPTION_FLT_OVERFLOW	no	The exponent of operation is too large.
EXCEPTION_FLT_STACK_CHECK	no	The Stack gone bad after a float operation.
EXCEPTION_FLT_UNDERFLOW	no	The exponent of operation is too low.
EXCEPTION_INT_OVERFLOW	no	The result of operation is too large.
EXCEPTION_PRIV_INSTRUCTION	no	Operation is not allowed in current mode.
EXCEPTION_IN_PAGE_ERROR	no	Can't access a memory page.
EXCEPTION_INVALID_DISPOSITION	no	Invalid disposition returned.
EXCEPTION_GUARD_PAGE	no	Accessing PAGE_GUARD-allocated modifier.

Unix Signals

Signal	Handling	Enabled	Description
SIGABRT	A	yes	Process abort signal.
SIGFPE	A	yes	Erroneous arithmetic operation.
SIGSEGV	A	yes	Invalid memory reference.
SIGILL	A	yes	Illegal instruction.
SIGBUS	A	yes	Access to an undefined portion of a memory object.
SIGTERM	T	no	Termination signal.
SIGINT	T	no	Terminal interrupt signal.
SIGALRM	T	no	Alarm clock.
SIGCHLD	I	no	Child process terminated, stopped, or continued.
SIGCONT	C	no	Continue executing, if stopped.
SIGHUP	T	no	Hangup.
SIGKILL	T	no	Kill (cannot be caught or ignored).
SIGPIPE	T	no	Write on a pipe with no one to read it.
SIGQUIT	A	no	Terminal quit signal.
SIGSTOP	S	no	Stop executing (cannot be caught or ignored).
SIGTSTP	S	no	Terminal stop signal.
SIGTTIN	S	no	Background process attempting read.
SIGTTOU	S	no	Background process attempting write.
SIGUSR1	T	no	User-defined signal 1.
SIGUSR2	T	no	User-defined signal 2.
SIGPROF	T	no	Profiling timer expired.
SIGSYS	A	no	Bad system call.
SIGTRAP	A	no	Trace/breakpoint trap.
SIGURG	I	no	High bandwidth data is available at a socket.
SIGVTALRM	T	no	Virtual timer expired.
SIGXCPU	A	no	CPU time limit exceeded.
SIGXFSZ	A	no	File size limit exceeded.

• T - Abnormal termination of the process.
• A - Abnormal termination of the process with additional actions.
• I - Ignore the signal.
• S - Stop the process.
• C - Continue the process, if it is stopped; otherwise, ignore the signal.

Legal notice

This package is derived from segfault-handler. The original licensing rules apply, see LICENSE_node-segfault-handler.

Also this project uses callstack walker which is licensed under BSD-2 Clause.

The rest of this package (the newly introduced files) is licensed under MIT.