NAME
backtrace,
backtrace_symbols,
backtrace_symbols_fd,
backtrace_symbols_fmt,
backtrace_symbols_fd_fmt —
fill in the backtrace of the currently
executing thread
SYNOPSIS
#include
<execinfo.h>
size_t
backtrace(void
**addrlist, size_t
len);
char **
backtrace_symbols(void
* const *addrlist, size_t
len);
int
backtrace_symbols_fd(void
* const *addrlist, size_t
len, int fd);
char **
backtrace_symbols_fmt(void
* const *addrlist, size_t
len, const char
*fmt);
int
backtrace_symbols_fd_fmt(void
* const *addrlist, size_t
len, int fd,
const char *fmt);
DESCRIPTION
The
backtrace()
function places into the array pointed by addrlist the
array of the values of the program counter for each frame called up to
len frames. The number of frames found (which can be
fewer than len) is returned.
The
backtrace_symbols_fmt()
function takes an array of previously filled addresses from
backtrace() in addrlist of
len elements, and uses fmt to
format them. The formatting characters available are:
a- The numeric address of each element as would be printed using %p.
n- The name of the nearest function symbol (smaller than the address element) as determined by dladdr(3)
d- The difference of the symbol address and the address element printed using 0x%tx.
D- The difference of the symbol address and the address element printed using +0x%tx if non-zero, or nothing if zero.
f- The filename of the symbol as determined by dladdr(3).
The array of formatted strings is returned as a contiguous memory address which can be freed by a single free(3).
The
backtrace_symbols()
function is equivalent of calling
backtrace_symbols_fmt() with a format argument of
“%a <%n%D> at %f”
The
backtrace_symbols_fd()
and
backtrace_symbols_fd_fmt()
are similar to the non _fd named functions, only instead of returning an
array of strings, they print a new-line separated array of strings in fd,
and return 0 on success and
-1 on failure.
RETURN VALUES
The backtrace() function returns the
number of elements that were filled in the backtrace. The
backtrace_symbols() and
backtrace_symbols_fmt() return a string array on
success, and NULL on failure, setting
errno.
SEE ALSO
HISTORY
The backtrace() library of functions first
appeared in NetBSD 7.0 and was imported into
OpenBSD 7.0.
BUGS
- Only unwinding with libunwind is supported. On architectures without
libunwind the
backtrace() function simply returns 0. - Since dladdr(3) only deals with dynamic symbols, local symbols from the main portion of the program are not printed.