API

The libbacktrace library defines the following data types and variables:

bt_accessor_t
An opaque structure that holds the identity of the thread to backtrace.
bt_memmap_t
An opaque structure that holds the memory map of a given process. A memory map is made of a list of all of the object files (executable and shared libraries) in process memory, and its text segments' location and size.
bt_accessor_t bt_acc_self
A preinitialized accessor used to backtrace BT_SELF.
Note: Don't call bt_init_accessor() or bt_release_accessor() for this global variable.

The library also defines the following functions, described in more detail in the QNX Neutrino C Library Reference:

bt_get_backtrace()
Collect a backtrace
bt_init_accessor()
Initialize a backtrace accessor
bt_load_memmap()
Load a memory map associated with a backtrace
bt_release_accessor()
Release an accessor for a backtrace
bt_set_flags()
Set or clear the flags for backtracing
bt_sprn_memmap()
Format the memory map information for a backtrace
bt_sprnf_addrs()
Format the addresses from a backtrace
bt_translate_addrs()
Translate the addresses from a backtrace
bt_unload_memmap()
Unload a memory map associated with a backtrace

In general, here's how you use these functions:

  1. Call bt_init_accessor() to set up the backtrace.
  2. Optionally call bt_set_flags() if you want to do a live backtrace. By default, bt_get_backtrace() freezes a thread before gathering the backtrace.
  3. Call bt_get_backtrace() to collect the backtrace addresses.
  4. Optionally load the memory map for the process by calling bt_load_memmap(). You need to do this if you want to format the information in certain ways.
  5. Optionally call bt_sprn_memmap() to produce a string of the memory map's contents.
  6. Call bt_sprnf_addrs() or bt_translate_addrs() to format the backtrace addresses.
  7. Call bt_unload_memmap() to unload the memory map.
  8. Call bt_release_accessor() to release the accessor.