debugger.h File Reference

Routines for interacting with a debugger. More...

+ Include dependency graph for debugger.h:

Go to the source code of this file.

Macros

#define ARCH_DEBUGGER_TRAP   do { ArchDebuggerTrap(); } while (0)
 Stop in the debugger. More...
 

Functions

ARCH_API void ArchDebuggerTrap () ARCH_NOINLINE
 Stop in a debugger. More...
 
ARCH_API void ArchDebuggerWait (bool wait)
 Cause debug traps to wait for the debugger or not. More...
 
ARCH_API bool ArchDebuggerAttach () ARCH_NOINLINE
 Attach a debugger. More...
 
ARCH_API bool ArchDebuggerIsAttached () ARCH_NOINLINE
 Test if a debugger is attached. More...
 
ARCH_API void ArchAbort (bool logging=true)
 Abort. More...
 

Detailed Description

Routines for interacting with a debugger.

Definition in file debugger.h.

Macro Definition Documentation

◆ ARCH_DEBUGGER_TRAP

#define ARCH_DEBUGGER_TRAP   do { ArchDebuggerTrap(); } while (0)

Stop in the debugger.

This macro expands to ArchDebuggerTrap() and, if necessary and possible, code to prevent optimization so the caller appears in the debugger's stack trace. The calling functions should also use the ARCH_NOINLINE function attribute.

Definition at line 106 of file debugger.h.

Function Documentation

◆ ArchAbort()

ARCH_API void ArchAbort ( bool  logging = true)

Abort.

This will try to avoid the JIT debugger if any if ARCH_AVOID_JIT is in the environment and the debugger isn't already attached. In that case it will _exit(134). If logging is false then this will attempt to bypass any crash logging.

◆ ArchDebuggerAttach()

ARCH_API bool ArchDebuggerAttach ( )

Attach a debugger.

Attaches the debugger by running the contents of the enviroment variable ARCH_DEBUGGER using /bin/sh. Any 'p' in the contents of this variable will be replaced with the process id of the process launching the debugger. Any 'e' will be replaced with the path to the executable for the process.

Returns true if ARCH_DEBUGGER is set and the debugger was successfully launched, otherwise returns false.

◆ ArchDebuggerIsAttached()

ARCH_API bool ArchDebuggerIsAttached ( )

Test if a debugger is attached.

Attempts to detect if a debugger is currently attached to the process.

◆ ArchDebuggerTrap()

ARCH_API void ArchDebuggerTrap ( )

Stop in a debugger.

This function will do one of the following: start a debugger attached to this process stopped on this function; stop in an already attached debugger; stop and wait for a debugger to attach, or nothing.

On Linux this will start a debugger using ArchDebuggerAttach() if no debugger is attached. If a debugger is (or was) attached it will stop on this function due to SIGTRAP. Alternatively, users can configure the debugger to not stop on SIGTRAP and instead break on ArchDebuggerTrap().

If a debugger is not attached, ArchDebuggerAttach() does not attach one, and ArchDebuggerWait() has been most recently called with true then this will wait for a debugger to attach, otherwise it does nothing and the process does not stop. The user can continue the process from the debugger simply by issuing the continue command. The user can also continue the process from an attached terminal by putting the process into the foreground or background.

◆ ArchDebuggerWait()

ARCH_API void ArchDebuggerWait ( bool  wait)

Cause debug traps to wait for the debugger or not.

When wait is true the next call to ArchDebuggerTrap() will cause the process to wait for a signal. The user can attach a debugger to continue the process. The process will not wait again until another call to this function with wait true.