Advanced Usage

Although you can use just the stacktrace::dump_stacktrace to print out the stacktrace, you can also use some of the more "complex" features.

Exceptions

Use/extend the stack_aware_exception class

#include "stacktrace.h"

void some_buggy_function()
{
  // use the throw_dbg macro to make throwing easier
  throw_dbg(stacktrace::stack_aware_exception, "something is wrong!");
}

int main()
{
  try 
  {
    some_buggy_function();
  }
  catch(stacktrace::stack_aware_exception& e)
  {
    // use stream manipulators to set how to print exception
    // stacktrace::shortexcept: prints e.what()
    // stacktrace::longexcept: prints e.what(), and where it was thrown
    // stacktrace::stacktrace: prints e.what(), where it was thrown, and a stacktrace
    // some stacktrace elements from the constructor + stacktrace-generating functions will be printed
    std::cout << stacktrace::stacktrace << e;
  }
}

This example will output:

MESSAGE: something is wrong!
AT FUNC: void some_buggy_function()
AT FILE: /home/runner/work/stacktrace/stacktrace/examples/main.cpp:67 (some_buggy_function)

STACKTRACE:
AT: [000055fca4f1d530] /home/runner/work/stacktrace/stacktrace/examples/../include/detail/stacktrace_execinfo_impl.h:11 (stacktrace::stacktrace(unsigned long))
AT: [000055fca4f21aef] /home/runner/work/stacktrace/stacktrace/source/stacktrace.cpp:42 (stacktrace::stack_aware_exception::stack_aware_exception(char const*, int, char const*, char const*, char const*))
AT: [000055fca4f1cb3a] /home/runner/work/stacktrace/stacktrace/examples/main.cpp:67 (some_buggy_function())
AT: [000055fca4f1cd2f] /home/runner/work/stacktrace/stacktrace/examples/main.cpp:119 (main)
AT: [00007fb9cb8780b3] UNK:0 (UNK)
AT: [000055fca4f1c90e] UNK:0 (_start)

Custom printing

All you need to do is to implement a printer function (that takes a stacktrace::entry and a std::ostream). Be sure to not add a newline when printing, as that is already done for you.

#include "stacktrace.h"

int main()
{
  // make use of the short type for a print function (optional, you can just stick the lambda in the call)
  stacktrace::stack_printer printer = [](const entry& e, std::ostream& os) 
  { 
    os << "AT: [" << e.address << "] " << e.file << ':' << e.line << " (" << e.function << ')';
  };

  stacktrace::dump_stacktrace(10, printer, std::cout);
}

This example will print:

MESSAGE: something is wrong!
AT FUNC: void some_buggy_function()
AT FILE: /home/runner/work/stacktrace/stacktrace/examples/main.cpp:67 (some_buggy_function)

STACKTRACE:
AT: [00005606b07fe50c] /home/runner/work/stacktrace/stacktrace/examples/../include/detail/stacktrace_execinfo_impl.h:11 (stacktrace::stacktrace(unsigned long))
AT: [00005606b0802acb] /home/runner/work/stacktrace/stacktrace/source/stacktrace.cpp:42 (stacktrace::stack_aware_exception::stack_aware_exception(char const*, int, char const*, char const*, char const*))
AT: [00005606b07fdb3a] /home/runner/work/stacktrace/stacktrace/examples/main.cpp:67 (some_buggy_function())
AT: [00005606b07fdd0b] /home/runner/work/stacktrace/stacktrace/examples/main.cpp:119 (main)
AT: [00007f155bda50b3] UNK:0 (UNK)
AT: [00005606b07fd90e] UNK:0 (_start)

Finer control

You can also get finer control over what happens to the stacktrace

#include "stacktrace.h"

int main()
{
  stacktrace::pointer_stacktrace pointers = stacktrace::stacktrace(10); // capture the raw addresses of the stacktrace
  stacktrace::symbol_stacktrace symbols = stacktrace::get_traced(pointers); // use symbols to make the stacktrace more readable
                                                                            // dont call this if you are in release and have no symbols
  stacktrace::dump_stacktrace(symbols, std::cout); // dump_stacktrace works with a pre-existing symbol stacktrace
}