Crash Handler

Macros
#define	DBG_CrashInteractive   (DBG_CrashExit | DBG_CrashPrompt | DBG_CrashProgressUI)
#define	DBG_CrashNonInteractive   (DBG_CrashExit | DBG_CrashDump | DBG_CrashUpload | DBG_CrashDelete)

Typedefs
typedef bool(*	dbgCrashCallback) (bool after)

Enumerations
enum	DEBUG_CRASH_FLAGS_ENUM {   DBG_CrashExit = 0x0001 , DBG_CrashDump = 0x0002 , DBG_CrashFullDump = 0x0004 , DBG_CrashUpload = 0x0008 ,   DBG_CrashBreakpoint = 0x0010 , DBG_CrashDelete = 0x0020 , DBG_CrashInternal = 0x0040 , DBG_CrashProgressUI = 0x0080 ,   DBG_CrashDevMode = 0x0100 , DBG_CrashNotify = 0x0200 , DBG_CrashPrompt = 0x1000 , DBG_CrashPromptLocal = 0x3000 }

Functions
void	dbgCrashSetMode (uint32 mode)
uint32	dbgCrashGetMode ()
bool	dbgCrashSetPath (strref path)
void	dbgCrashAddCallback (dbgCrashCallback cb)
void	dbgCrashRemoveCallback (dbgCrashCallback cb)
void	dbgCrashIncludeMemory (void *ptr, size_t sz)
void	dbgCrashExcludeMemory (void *ptr, size_t sz)
void	dbgCrashAddMetaStr (const char *name, const char *val)
void	dbgCrashAddMetaInt (const char *name, int val)
void	dbgCrashAddVersionStr (const char *name, const char *val)
void	dbgCrashAddVersionInt (const char *name, int val)
void _no_return	dbgCrashNow (int skipframes)

Detailed Description

Platform-agnostic crash handler with memory dump generation and reporting.

The crash handler system provides:

• Automatic crash detection and signal/exception handling
• Memory dump generation (mini or full dumps)
• Stack trace capture and symbolication
• Custom metadata injection into crash reports
• Memory region inclusion for debugging
• Crash report upload to reporting services
• User prompts and progress UI (configurable)
• Pre/post crash callbacks for cleanup or logging

Typical initialization:

// Non-interactive service (auto-upload crashes)
dbgCrashSetMode(DBG_CrashNonInteractive);
 
// Interactive application (prompt user)
dbgCrashSetMode(DBG_CrashInteractive);
dbgCrashSetPath(_S"C:/CrashDumps");
 
// Add version info that appears in all reports
dbgCrashAddVersionStr("app_version", "1.2.3");
dbgCrashAddVersionInt("build_number", 12345);

Triggering a controlled crash:

// Add crash-specific metadata
dbgCrashAddMetaStr("operation", "file_write");
dbgCrashAddMetaInt("error_code", errno);
 
// Trigger crash handler (does not return)
dbgCrashNow(0);

Macro Definition Documentation

DBG_CrashInteractive

#define DBG_CrashInteractive   (DBG_CrashExit | DBG_CrashPrompt | DBG_CrashProgressUI)

Preset crash mode for interactive applications

Exits gracefully, prompts user for action, and shows progress UI. Suitable for desktop applications where user interaction is expected.

Definition at line 72 of file crash.h.

DBG_CrashNonInteractive

#define DBG_CrashNonInteractive   (DBG_CrashExit | DBG_CrashDump | DBG_CrashUpload | DBG_CrashDelete)

Preset crash mode for non-interactive services

Exits gracefully, generates minidump, uploads automatically, and deletes dump after upload. Suitable for background services, daemons, or server processes.

Definition at line 78 of file crash.h.

Typedef Documentation

dbgCrashCallback

typedef bool(* dbgCrashCallback) (bool after)

Callback function invoked when a crash occurs

Parameters

after

false during initial crash handling (right after exception); true just before process exit

Returns

true to continue crash processing; false to abort and use OS default handler

CRITICAL: Callbacks must be signal-safe. Do NOT perform:

• Memory allocation (xaAlloc, malloc, etc.)
• Complex locking (may deadlock)
• Logging to files or network
• String operations that allocate

Safe operations:

• Writing to pre-allocated buffers
• Simple flag setting
• Stack-based operations

Callbacks are invoked twice: once during initial exception handling for immediate response, and again just before exit for final cleanup.

Definition at line 122 of file crash.h.

Enumeration Type Documentation

DEBUG_CRASH_FLAGS_ENUM

enum DEBUG_CRASH_FLAGS_ENUM

Flags controlling crash handler behavior

These flags can be combined with bitwise OR to configure how crashes are handled.

Enumerator
DBG_CrashExit	Exit process gracefully after handling crash.
DBG_CrashDump	Generate minidump (small memory dump)
DBG_CrashFullDump	Generate full memory dump (large, includes entire process)
DBG_CrashUpload	Submit crash report to reporting service.
DBG_CrashBreakpoint	Trigger breakpoint for debugger attachment.
DBG_CrashDelete	Delete dump file after successful upload.
DBG_CrashInternal	Submit to internal endpoint rather than public reporting service.
DBG_CrashProgressUI	Show progress UI while uploading crash report.
DBG_CrashDevMode	Process is in development mode; allow debugging and special handling.
DBG_CrashNotify	Show notification dialog but do not offer user options.
DBG_CrashPrompt	Prompt user upon crash; user can choose crash handling options.
DBG_CrashPromptLocal	Prompt user but disallow upload (implies CrashPrompt)

Definition at line 53 of file crash.h.

Function Documentation

dbgCrashAddCallback()

void dbgCrashAddCallback

(

dbgCrashCallback

cb

)

Register a crash callback function

Parameters

cb	Callback to invoke on crash

Callbacks are deduplicated - adding the same callback multiple times has no effect. All registered callbacks are invoked in registration order.

dbgCrashAddMetaInt()

void dbgCrashAddMetaInt	(	const char *	name,
		int	val
	)

Add integer metadata to crash report

Parameters

name	Metadata key name
val	Integer value

Like dbgCrashAddMetaStr() but for integer values.

dbgCrashAddMetaStr()

void dbgCrashAddMetaStr	(	const char *	name,
		const char *	val
	)

Add string metadata to crash report

Parameters

name	Metadata key name
val	String value

Adds crash-specific metadata that appears in the crash report. Should be used for information directly related to the crash condition, called just before triggering a crash.

For runtime metadata that persists across the application lifecycle, use the Black Box system instead.

Metadata is automatically JSON-escaped and included in the crash report payload.

dbgCrashAddVersionInt()

void dbgCrashAddVersionInt	(	const char *	name,
		int	val
	)

Add integer version metadata to crash report root

Parameters

name	Version field name
val	Integer value

Like dbgCrashAddVersionStr() but for integer values.

dbgCrashAddVersionStr()

void dbgCrashAddVersionStr	(	const char *	name,
		const char *	val
	)

Add string version metadata to crash report root

Parameters

name	Version field name
val	String value

Adds version information to the root level of crash reports. Typically called during application initialization for version identifiers, build numbers, or configuration that applies to all crashes.

Appears at crash report root level, separate from per-crash metadata.

dbgCrashExcludeMemory()

void dbgCrashExcludeMemory	(	void *	ptr,
		size_t	sz
	)

Remove a previously marked memory region from crash dumps

Parameters

ptr	Pointer to start of memory region
sz	Size of memory region in bytes

Removes a region previously added with dbgCrashIncludeMemory(). Does NOT exclude automatically selected regions like stacks and data segments.

dbgCrashGetMode()

uint32 dbgCrashGetMode

(

)

Get current crash handler mode

Returns

Current mode flags

dbgCrashIncludeMemory()

void dbgCrashIncludeMemory	(	void *	ptr,
		size_t	sz
	)

Mark a memory region for inclusion in crash dumps

Parameters

ptr	Pointer to start of memory region
sz	Size of memory region in bytes

Ensures the specified memory region is included in minidumps. Useful for capturing circular buffers, shared memory, or other important data structures that might not be automatically included.

Automatically included regions:

• Stack of all threads
• Global/static data segments
• Memory around crash location

dbgCrashNow()

void _no_return dbgCrashNow

(

int

skipframes

)

Trigger crash handler immediately

Parameters

skipframes

Number of stack frames to skip in stack trace

Invokes the crash handler as if a fatal exception occurred. Does not return - process terminates according to configured mode.

Use skipframes to exclude internal error handling frames from the captured stack trace. Pass 0 to include all frames.

Before calling, use dbgCrashAddMetaStr()/dbgCrashAddMetaInt() to add crash-specific context.

dbgCrashRemoveCallback()

void dbgCrashRemoveCallback

(

dbgCrashCallback

cb

)

Unregister a previously registered crash callback

Parameters

cb	Callback to remove

dbgCrashSetMode()

void dbgCrashSetMode

(

uint32

mode

)

Set crash handler behavior mode

Parameters

mode	Combination of DEBUG_CRASH_FLAGS_ENUM flags

Configures how the crash handler behaves when a crash occurs. Thread-safe and can be changed at runtime.

dbgCrashSetMode(DBG_CrashInteractive);
// or custom combination:
dbgCrashSetMode(DBG_CrashExit | DBG_CrashDump | DBG_CrashPrompt);

dbgCrashSetPath()

bool dbgCrashSetPath

(

strref

path

)

Set crash dump output directory

Parameters

path	Directory path where crash dumps should be written

Specifies where crash dump files (.dmp) should be saved. If not set, uses platform-specific default location.