BACKTRACE(3) Library Functions Manual BACKTRACE(3)

backtrace, backtrace_symbols, backtrace_symbols_fd, backtrace_symbols_fmt, backtrace_symbols_fd_fmt — fill in the backtrace of the currently executing thread

Backtrace Information Library (libexecinfo, -lexecinfo)

#include <execinfo.h>

size_t
backtrace(void **addrlist, size_t len);

int
backtrace_sandbox_init(void);

void
backtrace_sandbox_fini(void);

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);

The () 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 () and () functions are intended to enable sandbox usage of backtrace. The backtrace_sandbox_init() function must be called before the sandbox is entered, and will acquire any resources needed to function in a sandbox. The backtrace_sandbox_fini() function will release the resources it acquired.

The () 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:

The numeric address of each element as would be printed using %p.
The name of the nearest function symbol (smaller than the address element) as determined by dladdr(3) if the symbol was dynamic, or looked up in the executable if static and the /proc filesystem is available to determine the executable path.
The difference of the symbol address and the address element printed using 0x%tx.
The difference of the symbol address and the address element printed using +0x%tx if non-zero, or nothing if zero.
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 () function is equivalent of calling backtrace_symbols_fmt() with a format argument of “%a <%n%D> at %f”

The () and () 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.

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. Diagnostic output may also be produced by the ELF symbol lookup functions.

dladdr(3), elf(3)

The backtrace() library of functions first appeared in NetBSD 7.0.

  1. Errors should not be printed but communicated to the caller differently.
  2. Because these functions use elf(3) this is a separate library instead of being part of libc/libutil so that no library dependencies are introduced.
  3. The Linux versions of the functions (there are no _fmt variants) use int instead of size_t arguments.
  4. Since dladdr(3) only deals with dynamic symbols, we need to find the symbols from the main portion of the program. For that we need to locate the executable, and we use procfs for finding it, which is not portable.
January 22, 2025 NetBSD 11.0