🐧 Linux Support

CrashCatch provides robust, out-of-the-box crash handling for native Linux C++ applications using POSIX signals and backtrace().

It captures detailed crash context, generates a human-readable .txt report, and includes demangled stack traces and environment info all from a single header.

---

🔥 Supported Signals

CrashCatch handles a wide set of fatal signals:

Signal	Description
SIGSEGV	Segmentation fault (invalid memory access)
SIGABRT	Aborted process (e.g. abort())
SIGFPE	Floating point exception (e.g. divide by zero)
SIGILL	Illegal instruction
SIGBUS	Bus error (e.g. misaligned memory access)

All signals trigger a crash log and invoke the optional onCrash() and onCrashUpload() callbacks with full crash context.

---

🧠 Linux Features

• ✅ Signal name & number logged in crash reports
• ✅ Async-signal-safe handler using fork() no deadlocks even on heap corruption (v1.4.0)
• ✅ Demangled C++ symbol names in stack traces (v1.4.0 properly extracts mangled name before demangling)
• ✅ Executable path detection via /proc/self/exe
• ✅ Crash context includes signal, timestamp, paths, and notes
• ✅ Callbacks fire after crash files are written (v1.4.0)
• ✅ Thread-safe timestamp generation via localtime_r (v1.4.0)
• ✅ Works in GUI and headless/CLI environments

---

⚡ How the Handler Works (v1.4.0)

Signal handlers in Linux are restricted to async-signal-safe functions only. Calling malloc, std::string, or file I/O directly from a signal handler is undefined behavior and can deadlock if the crash occurred mid-heap-operation.

CrashCatch solves this with fork():

1. The signal fires the handler records the signal number and path strings
2. fork() is called the child process inherits the parent's memory image
3. The child performs all file I/O, stack trace generation, and callback execution — safely
4. The parent waits for the child to finish, then calls _exit()

This is the same pattern used by Google's Crashpad and Breakpad.

---

📋 Output Format

When a crash occurs, CrashCatch creates a .txt log in ./crash_dumps/ (configurable) containing:

• Timestamp
• Signal name and number
• Stack trace with demangled C++ symbols
• Application version and build config
• Executable path
• Any additional notes set in config

🧾 Example Output

Crash Report
============
Signal: Segmentation fault (11)
Timestamp: 2026-03-20_09-15-23

Environment Info:
App Version: 2.0.0
Build Config: Release
Platform: Linux
Executable: /home/user/myapp

Stack Trace:
  [0]: ./myapp(MyClass::crashingMethod()+0x42) [0x401234]
  [1]: ./myapp(main+0x1f) [0x401100]
  [2]: libc.so.6(__libc_start_main+0xf3) [0x7f...]

Compile with -rdynamic to get function names in stack frames.

---

Testing Linux Crashes

Null Pointer

#include "CrashCatch.hpp"

int main() {
    CrashCatch::enable();
    int* ptr = nullptr;
    *ptr = 42; // SIGSEGV
    return 0;
}

Divide by Zero

#include "CrashCatch.hpp"

int main() {
    CrashCatch::enable();
    int zero = 0;
    int crash = 1 / zero; // SIGFPE
    return crash;
}

Threaded Fault

#include <thread>
#include "CrashCatch.hpp"

void crashFunc() {
    int* p = nullptr;
    *p = 5; // SIGSEGV from background thread
}

int main() {
    CrashCatch::enable();
    std::thread t(crashFunc);
    t.join();
}

---

CMake Setup

No special setup is required on Linux. Simply include the header and optionally link with -rdynamic to improve symbol resolution:

target_link_options(MyApp PRIVATE -rdynamic)

Or using the compiler directly:

g++ -std=c++17 main.cpp -rdynamic -o myapp

-rdynamic allows symbol names to appear in stack traces generated by backtrace_symbols().

---

🚧 Known Limitations

• Crash logs are .txt only on Linux .dmp MiniDump format is Windows only
• Stack traces may not show full function names without -rdynamic
• GUI message boxes are not supported on Linux