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.