debug — Hare documentation

debug+x86_64 +linux

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

dwarf
image

Index

Types

type stackframe = struct {
	fp: nullable *stackframe,
	ip: uintptr,
};

// Undocumented types:
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[link]

type stackframe = struct {
	fp: nullable *stackframe,
	ip: uintptr,
};

Details for a stack frame. Contents are architecture-specific.

type trace[link]

Show undocumented member

type trace = struct {
	id: u64,
	frames: *stackframe,
};

Functions

fn backtrace[link]

fn backtrace(self: *image::image, frame: stackframe) void;

Prints a backtrace to the standard error.

fn frame_pc[link]

fn frame_pc(frame: stackframe) uintptr;

Return the program counter address for the given stack frame.

fn next[link]

fn next(frame: stackframe) (stackframe | done);

Returns the next stack frame walking the stack.

fn symbol_byaddr[link]

fn symbol_byaddr(image: *image::image, addr: uintptr) (elf::sym64 | io::error | void);

Returns the symbol that occupies a given address.

fn symbol_byname[link]

fn symbol_byname(image: *image::image, name: str) (elf::sym64 | io::error | void);

Returns symbol information by name.

fn symbol_name[link]

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[link]

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[link]

fn trace_by_id(id: u64) (stackframe | void);

Retrives a stack trace by its ID.

fn trace_store[link]

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[link]

fn translate(ptr: uintptr) (uintptr | void);

Tries to translate a pointer into an ELF address of the currently running binary.

fn walk[link]

fn walk() stackframe;

Returns the caller's stack frame. Call next to walk the stack.