stx::backtrace Namespace Reference

Classes
struct	CharSpan
	Mutable type-erased view over a contiguous character container. More...
struct	Frame
	reperesents an active stack frame. More...
struct	Symbol

Typedefs
using	Callback = bool(*)(Frame, int)

Enumerations
enum	SignalError { SignalError::Unknown, SignalError::SigErr }

Functions
SpanReport	operator>> (ReportQuery, SignalError const &err) noexcept
int	trace (Callback callback, int skip_count=0)
auto	handle_signal (int signal) noexcept -> Result< void(*)(int), SignalError >

Typedef Documentation

Callback

using stx::backtrace::Callback = typedef bool (*)(Frame, int)

Enumeration Type Documentation

SignalError

enum stx::backtrace::SignalError

strong

Enumerator
Unknown	An Unknown error occurred.
SigErr	std::signal returned SIG_ERR

Function Documentation

handle_signal()

auto stx::backtrace::handle_signal ( int  signal ) -> Result< void(*)(int), SignalError >

noexcept

Installs an handler for the specified signal that prints a backtrace whenever the signal is raised. It can and will only handle SIGSEGV, SIGILL, and SIGFPE. It returns the previous signal handler if successful, else returns the error.

Example

// immediately after program startup
handle_signal(SIGILL).unwrap();
handle_signal(SIGSEGV).unwrap();
handle_signal(SIGFPE).unwrap();

operator>>()

SpanReport stx::backtrace::operator>> ( ReportQuery  , SignalError const &  err  )

inlinenoexcept

trace()

int stx::backtrace::trace	(	Callback	callback,
		int	skip_count = 0
	)

Gets a backtrace within the current machine's state. This function walks down the stack, and calls callback on each stack frame as it does so. if the callback invocation's result evaluates to true, it stops which means it has found the desired stack frame, else, it keeps walking the stack until it exhausts the stack frame / reaches the maximum stack depth. This function does not perform stack-unwinding.

Returns the number of stack frames read.

callback is allowed to throw exceptions.

WARNING

Do not move the frame nor its member objects out of the callback, nor bind a reference to them.

Panic and Exception Tolerance

The function is non-panicking as long as the callback doesn't panic. The callback can throw an exception.

Example

 stx::backtrace::trace([](Frame frame, int) {
  std::cout << "Instruction Pointer="
            << frame.ip.clone().unwrap()
            << std::endl;
  return false;
});