debug
The debug module implements various runtime debugging services. It is enabled by default when you build programs in debug mode (you can disable this by building in release mode with the -R flag to hare(1)). It provides detailed backtraces in various error conditions, including:
- Assertion failures
- Built-in assertions (e.g. for the "as" operator)
- Segmentation faults
- Arithmetic exceptions (e.g. divide by zero)
- Bus errors
- Stack overflows
In order to accomplish this, the debug module does some logic on @init which rigs up rt:: with debugging hooks and installs the relevant signal handlers globally. If you set your own signal handlers for terminating signals (e.g. SIGFPE) that the debug module handles, they will override the debug hooks.
This module may also be used explicitly to inspect details of the running program -- for instance, you can trace the call stack with walk.
Submodules
Index
Types
type stackframe = struct {
fp: nullable *stackframe,
ip: uintptr,
};
type trace = struct {
id: u64,
frames: *stackframe,
};
Functions
fn backtrace(self: *image::image, frame: stackframe) void;
fn frame_pc(frame: stackframe) uintptr;
fn next(frame: stackframe) (stackframe | done);
fn symbol_byaddr(image: *image::image, addr: uintptr) (elf::sym64 | io::error | void);
fn symbol_byname(image: *image::image, name: str) (elf::sym64 | io::error | void);
fn symbol_name(image: *image::image, sym: *elf::sym64) (const str | io::error | void);
fn symname_to_ident(name: str) const str;
fn trace_by_id(id: u64) (stackframe | void);
fn trace_store(frame: stackframe) (u64 | nomem);
fn translate(ptr: uintptr) (uintptr | void);
fn walk() stackframe;
Types
type stackframe
type stackframe = struct {
fp: nullable *stackframe,
ip: uintptr,
};
Details for a stack frame. Contents are architecture-specific.
type trace
Show undocumented member
type trace = struct {
id: u64,
frames: *stackframe,
};
Functions
fn backtrace
fn backtrace(self: *image::image, frame: stackframe) void;
Prints a backtrace to the standard error.
fn frame_pc
fn frame_pc(frame: stackframe) uintptr;
Return the program counter address for the given stack frame.
fn next
fn next(frame: stackframe) (stackframe | done);
Returns the next stack frame walking the stack.
fn symbol_byaddr
fn symbol_byaddr(image: *image::image, addr: uintptr) (elf::sym64 | io::error | void);
Returns the symbol that occupies a given address.
fn symbol_byname
fn symbol_byname(image: *image::image, name: str) (elf::sym64 | io::error | void);
Returns symbol information by name.
fn symbol_name
fn symbol_name(image: *image::image, sym: *elf::sym64) (const str | io::error | void);
Returns the name of the given symbol, or void if the executable was stripped.
fn symname_to_ident
fn symname_to_ident(name: str) const str;
Converts a symbol name to a Hare identifier. The return value is statically allocated.
fn trace_by_id
fn trace_by_id(id: u64) (stackframe | void);
Retrives a stack trace by its ID.
fn trace_store
fn trace_store(frame: stackframe) (u64 | nomem);
Stores a stack trace and returns its ID. Stored stack traces are hashed and de-duplicated in a global stack list.
fn translate
fn translate(ptr: uintptr) (uintptr | void);
Tries to translate a pointer into an ELF address of the currently running binary.
fn walk
fn walk() stackframe;
Returns the caller's stack frame. Call next to walk the stack.