bt_get_backtrace()

Collect a backtrace

Note: The backtrace library is an unsupported feature, due to its fragility. For more information, see Backtraces in the QNX Neutrino technotes.

Synopsis:

#include <backtrace.h>

int bt_get_backtrace( bt_accessor_t *acc,
                      bt_addr_t *addrs,
                      int len );

Arguments:

acc: A pointer to a bt_accessor_t structure. This is an opaque structure that holds the identity of the thread to backtrace.
addrs: An array of bt_addr_t members where the function can store the addresses; addrs[0] is the top of stack.
len: The maximum number of addresses to collect and store in addrs.

Library:

libbacktrace

Use the -l backtrace option to qcc to link against this library.

Description:

The bt_get_backtrace() function collects a backtrace up to len deep. The behavior depends on how you initialized the accessor when you called bt_init_accessor():

If BT_SELF, the library uses direct memory access to gather the information from the stack.
If BT_THREAD, or for BT_PROCESS where the process ID and thread ID are for the calling thread, the library uses direct memory access.
For BT_THREAD where the thread ID isn't for the calling thread, or for BT_PROCESS with the process ID of the calling process and the thread ID other than that of the calling thread, the library stops the thread, fetches the thread context and registers, uses direct memory access, and the restarts the thread.
For BT_PROCESS where the process ID isn't that of the calling process, the library stops the thread, fetches the thread context and registers, uses the process's entry in the /proc filesystem to access memory, and then restarts the thread.

Note the following:

When you're backtracing within the same process, if bt_get_backtrace() attempts to access a non-existent memory location, signals are masked, and SIGSEGV is trapped to avoid crashing the program.
QNX Neutrino 6.3.0 and earlier can't stop a single thread, so in this case stopping a thread really means stopping all threads in the process.
QNX Neutrino 6.3.2 and later can stop a single thread.
If other applications and processes start and stop threads, it may interfere with bt_get_backtrace().

Returns:

The number of addresses stored in addrs.

Classification:

QNX Neutrino

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes