20 Mar 13:49

4f6451b

v1.4.0 Latest

Latest

CrashCatch v1.4.0 Release Notes

Released: 2026-03-20

This release is a correctness-focused update. No public API has changed existing code compiles and runs without modification. All changes are internal fixes to long-standing bugs in the crash handling implementation.

What Changed

Windows: Stack trace now shows the actual crash location

Previously, writeCrashLog called RtlCaptureContext from inside the exception handler. This captured the handler's own call stack, meaning frame [0] showed internal CrashCatch functions rather than the code that crashed.

The Windows exception handler now passes ep->ContextRecord (the CPU state frozen at the moment of the fault) directly into the stack walker. Frame [0] now correctly identifies the crashing function, file, and line number.

Before:

Stack Trace:
  [0]: writeCrashLog
  [1]: UnhandledExceptionHandler
  [2]: RtlDispatchException
  ...

After:

Stack Trace:
  [0]: MyApp::GameLoop (src\game.cpp:142)
  [1]: main (src\main.cpp:28)
  [2]: invoke_main (exe_common.inl:79)
  ...

Callbacks now fire after crash files are written

onCrash and onCrashUpload previously received file paths before those files existed on disk. Any code inside the callback that tried to read, parse, or upload the crash report would fail silently or open an empty file.

Both callbacks now fire after all files are fully written and closed. The file paths in CrashContext are guaranteed to be readable when either callback is invoked.

Linux signal handler is now async-signal-safe

Calling heap-allocating functions (std::string, std::ofstream, malloc, backtrace_symbols, abi::__cxa_demangle) directly from a POSIX signal handler is undefined behavior. If the crash occurred mid-malloc (e.g. heap corruption), the handler would deadlock.

The Linux signal handler now uses fork(). The child process performs all file I/O and executes callbacks it is safe to use the heap there. The parent calls _exit() immediately. This is the same pattern used by Google's Crashpad and Breakpad.

Linux: Demangled symbols now actually demangle

backtrace_symbols() returns full strings like ./myapp(_Z3foov+0x10) [0x7f...]. The previous demangle() function passed the entire string to abi::__cxa_demangle, which expects a raw mangled name and always returned the original string unchanged.

The mangled symbol is now extracted from between ( and + before demangling, producing readable output:

Before:

  [0]: ./myapp(_Z8myMethodv+0x42) [0x401234]

After:

  [0]: ./myapp(myMethod()+0x42) [0x401234]

Thread-safe timestamps

std::localtime returns a pointer to a shared static struct and is not thread-safe. A crash on a background thread while the main thread was also formatting a timestamp could produce a corrupted timestamp string.

Replaced with localtime_s (Windows) and localtime_r (Linux), both of which write into a caller-supplied struct.

Symbol loading moved to startup

SymInitialize was previously called inside the exception handler at crash time. This is slow (~100ms on large binaries) and will fail if another part of the application has already initialized DbgHelp symbols.

SymInitialize is now called once during CrashCatch::initialize(), so symbols are loaded and ready before any crash occurs.

Directory creation failures are now handled

If create_directories failed (bad path, missing permissions), the error was silently ignored and subsequent file writes would fail with no diagnostic. The std::error_code overload is now used if the output directory cannot be created, the handler exits early rather than attempting to write to an invalid path.

Internal Improvements

CrashContext is now constructed once per crash and shared between onCrash and onCrashUpload, rather than being constructed twice.
Version string in CrashCatch.hpp header comment corrected to match the release version.

New Tests

Two tests have been added to tests/ to permanently verify the corrected behavior:

Test	Verifies
`test_callback_order`	Log file exists on disk when `onCrash` fires
`test_stack_context`	Stack trace frame `[0]` is the crash-site function, not a handler frame

Upgrading

No changes to the public API. Replace CrashCatch.hpp (and CrashCatchDLL.hpp if used) with the v1.4.0 versions. Recompile. No code changes required.

Platform Compatibility

Platform	Status
Windows 10 / 11 (x64, x86)	Tested
Linux (GCC, Clang)	Fixes applied; signal-safety fix verified by code review — runtime testing on Linux recommended
macOS	Not yet supported

Full Changelog

See CHANGELOG.md for the complete history.

Assets 2

25 Feb 14:13

keithpotz

v1.3.0

5c8bd05

CrashCatch v 1.3.0

CrashCatch v1.3.0 Release Notes

Released: February 2026

What's New

🪟 Windows Stack Trace in Text Log

The .txt crash report on Windows now includes a full symbolicated stack trace,
matching the behavior already available on Linux. Stack frames include function
names and file/line numbers when debug symbols are available.

Previously the Windows .txt log only contained environment info and a
timestamp. The .dmp minidump file was the only way to inspect the call stack.
That is no longer the case.

Implementation uses StackWalk64, SymFromAddr, and SymGetLineFromAddr64
from DbgHelp — the same library already linked by CrashCatch for minidump
generation.

🔇 Stack Trace Suppression Flag

A new includeStackTrace config option lets you control whether the stack
trace is written to the .txt log on both Windows and Linux.

CrashCatch::Config config;
config.includeStackTrace = false;  // Omit stack trace from .txt log
CrashCatch::initialize(config);

Defaults to true — existing integrations are unaffected.

📦 DLL / Shared Library Support (`CrashCatchDLL.hpp`)

A new companion header CrashCatchDLL.hpp provides a plain C interface for
applications that cannot use C++17 directly — including projects built with
C++11, C++98, or plain C.

The DLL is compiled once with C++17. Consumers link against the binary and
include only CrashCatchDLL.hpp — no C++17 requirement on their end.

Building the DLL:

// CrashCatchDLL.cpp — compile this file with C++17
#define CRASHCATCH_DLL_EXPORTS
#include "CrashCatchDLL.hpp"

Using from a C++11 / C++98 project:

#include "CrashCatchDLL.hpp"

int main() {
    // Zero config
    crashcatch_enable();

    // -- or with full config --
    CrashCatch_Config cfg = crashcatch_default_config();
    cfg.app_version         = "2.0.0";
    cfg.show_crash_dialog   = 1;
    cfg.include_stack_trace = 1;
    cfg.on_crash = my_crash_handler;
    crashcatch_init(&cfg);
}

Exported C functions:

Function	Description
`crashcatch_enable()`	Zero-config initialization
`crashcatch_init(cfg)`	Initialize with full configuration
`crashcatch_default_config()`	Returns a config struct with defaults
`crashcatch_version()`	Returns version string

Both on_crash and on_crash_upload callbacks are supported via plain C
function pointers.

Changes

	Detail
Added	Windows `.txt` stack trace via `StackWalk64`
Added	`Config::includeStackTrace` flag (default `true`)
Added	`CrashCatchDLL.hpp` — C interface for DLL/shared library use
Changed	Linux stack trace now also respects `includeStackTrace` flag
Unchanged	All existing `CrashCatch::Config` fields and defaults
Unchanged	`CrashCatch.hpp` public API — fully backwards compatible

Upgrading from v1.2.0

No breaking changes. Existing code compiles and behaves identically.

To opt into the new Windows stack trace output, no changes are needed —
it is enabled by default. To suppress it:

config.includeStackTrace = false;

To use DLL support, add CrashCatchDLL.hpp to your include/ folder
alongside CrashCatch.hpp.

Addresses

#6 Feature Request for DLL
#7 Features request for outputting entire stack trace

Created and maintained by Keith Pottratz — MIT Licensed

Assets 4

18 Apr 21:59

keithpotz

v1.2

e783e3c

CrashCatch v1.2.0

🚀 CrashCatch v1.2.0

CrashCatch v1.2.0 is our biggest update yet — bringing full Linux support, powerful callback hooks, and the groundwork for cross-platform crash diagnostics — all within a single header file.

✨ What's New

🔧 Linux Support Finalized

✅ POSIX signal handling now supports:
- SIGSEGV – Segmentation fault
- SIGABRT – Aborted process
- SIGFPE – Floating-point exception
- SIGILL, SIGBUS – Illegal instruction, bus errors
✅ Stack traces via backtrace()
✅ Demangled function names using __cxa_demangle
✅ Executable path detection via /proc/self/exe

🧠 New CrashContext Struct

Contains detailed crash metadata passed into callback hooks:
- .dmp file path (Windows)
- .txt log path
- timestamp
- signal or exception code

🪝 `onCrash` and `onCrashUpload` Hooks

New configurable callbacks:

config.onCrash = [](const CrashContext& ctx) {
    // Cleanup or logging before app terminates
};

config.onCrashUpload = [](const CrashContext& ctx) {
    // Send crash file to your server/service
};```

Enabled cleanup, telemetry, logging, or remote upload logic right from the app!

🛑 Skips Debug Exceptions

Windows debug control exceptions (DBG_PRINTEXCEPTION_C, DBG_CONTROL_C) are now ignored to avoid false positives.

🧪 Examples Added

🧵 Example_ThreadCrash.cpp
➗ Example_divideByZero.cpp
💼 Example_FullConfig.cpp — now includes onCrash
☁️ Example_UploadCrash.cpp — demonstrates using onCrashUpload to simulate a remote crash report

🛠 Internal Improvements

Reorganized internal logic with clear inline documentation
Hardened Linux support for production use
Improved stack trace readability
Unified timestamp generation and path formatting

📝 Documentation

Updated README.md with full platform details
New linux.md page under GitHub Pages
Refined screenshots, quick start, and crash log examples

📦 CMake & CI

Enhanced CMake integration remains header-only
GitHub Actions CI runs automatically on push

🧭 Roadmap (Next Up)

macOS support via Mach exceptions
Remote crash uploads (via webhook or HTTPS endpoint)
.json crash logs
Crash viewer UI tool
Auto-rotate / cleanup of old log

🧠 Thanks & Community

Thanks to everyone who tested Linux support, contributed feedback, or opened issues. Let’s keep building it better — and safer.

If you like it, consider ⭐ starring the project!

Assets 3

04 Apr 23:34

keithpotz

v1.1.0

017989a

CrashCatch v1.1.0 – Now with Linux Support

[1.1.0] – 2025-04-04

Added

🐧 Linux support with POSIX signal handling
Signal-based crash capture for SIGSEGV, SIGABRT, and SIGFPE
Executable path resolution for Linux using /proc/self/exe
Stack traces using backtrace() and backtrace_symbols()

Changed

Refactored header-only implementation to be cross-platform
Improved crash log structure and formatting on Linux
Now detects and logs platform, architecture, and executable location

✅ Bug Fix: Linux Compatibility Crash (#1)

Resolved a Linux-specific compilation error reported in #1, which occurred due to the use of Windows.h-specific types and headers on non-Windows systems.

🔧 What changed:

CrashCatch now conditionally includes only platform-appropriate headers (e.g., Windows.h for Windows, signal.h and execinfo.h for Linux).
Windows-specific functionality (e.g., MiniDumpWriteDump, MessageBoxA) is fully gated behind #ifdef blocks.
Linux support now builds cleanly on GCC/Clang without needing to modify the source.

💡 Impact:

CrashCatch v1.1.0 is now cross-platform out of the box and builds cleanly on Linux with no manual patching required.

Fixed

Crash log generation on Linux wasn't triggered for certain signals
Windows-only includes and defines now guarded by platform macros

Zip File

The zip file has the CMakeLists.txt and CrashCatch.hpp files included

Assets 3

01 Apr 18:17

keithpotz

v1.0.0

b0975c0

CrashCatch v1.0.0 - Initial Public Release

🚀 CrashCatch v1.0.0 – Initial Public Release

CrashCatch is a single-header crash reporting library for modern C++ applications. This first release supports Windows and generates .dmp and .txt logs for unhandled exceptions.

🎯 Features

🧠 Stack trace + exception context
💾 Minidump file (.dmp) generation
📋 Human-readable log (.txt) with:
- Stack trace
- App version / build info
- Thread ID / exception code
- Uptime
✅ Zero-config mode (CRASHCATCH_AUTO_INIT)
⚙️ Configurable versioning, notes, dialog, and crash callback
🪛 One-liner setup via CrashCatch::enable()
🪄 Optional message box on crash (GUI-friendly)

📦 Installation

🟢 CrashCatch is a single-header library.

To use it, simply copy 'CrashCatch.hpp' file into your project:

#include "CrashCatch.hpp"

Or you can auto-init with:

#define CRASHCATCH_AUTO_INIT
#include "CrashCatch.hpp"

📁 Includes

CrashCatch.hpp – single header drop-in
5 real-world examples in /examples/
Screenshots and logs in /screenshots/

🛣 Future roadmap includes:

Linux/macOS support
Remote upload
JSON crash logs
Viewer GUI

Thank you for checking out CrashCatch!
Created and maintained by Keith Pottratz

Assets 3

Uh oh!

Releases: keithpotz/CrashCatch

v1.4.0

CrashCatch v1.4.0 Release Notes

What Changed

Windows: Stack trace now shows the actual crash location

Callbacks now fire after crash files are written

Linux signal handler is now async-signal-safe

Linux: Demangled symbols now actually demangle

Thread-safe timestamps

Symbol loading moved to startup

Directory creation failures are now handled

Internal Improvements

New Tests

Upgrading

Platform Compatibility

Full Changelog

Uh oh!

CrashCatch v 1.3.0

CrashCatch v1.3.0 Release Notes

What's New

🪟 Windows Stack Trace in Text Log

🔇 Stack Trace Suppression Flag

📦 DLL / Shared Library Support (CrashCatchDLL.hpp)

Changes

Upgrading from v1.2.0

Addresses

Uh oh!

CrashCatch v1.2.0

🚀 CrashCatch v1.2.0

✨ What's New

🔧 Linux Support Finalized

🧠 New CrashContext Struct

🪝 onCrash and onCrashUpload Hooks

🛑 Skips Debug Exceptions

🧪 Examples Added

🛠 Internal Improvements

📝 Documentation

📦 CMake & CI

🧭 Roadmap (Next Up)

🧠 Thanks & Community

Uh oh!

CrashCatch v1.1.0 – Now with Linux Support

[1.1.0] – 2025-04-04

Added

Changed

✅ Bug Fix: Linux Compatibility Crash (#1)

🔧 What changed:

💡 Impact:

Fixed

Zip File

Uh oh!

CrashCatch v1.0.0 - Initial Public Release

🎯 Features

📦 Installation

📁 Includes

Uh oh!

📦 DLL / Shared Library Support (`CrashCatchDLL.hpp`)

🪝 `onCrash` and `onCrashUpload` Hooks