BACKTRACE(3) | Library Functions Manual | BACKTRACE(3)

# NAME

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

# SYNOPSIS

Backtrace Information Library (libexecinfo, -lexecinfo)
`#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

dladdr(3)

# HISTORY

The `backtrace`() library of functions first appeared in NetBSD 7.0 and was imported into OpenBSD 7.0.

# BUGS

1. Only unwinding with libunwind is supported. On architectures without libunwind the `backtrace`() function simply returns 0.
2. Since dladdr(3) only deals with dynamic symbols, local symbols from the main portion of the program are not printed.

June 7, 2025 | Debian