---
name: "backtrace"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/backtrace"
---

# backtrace(3)

fill in the backtrace of the currently executing thread

## NAME

**backtrace** – fill in the backtrace of the currently executing thread

## LIBRARY

library “libexecinfo”

## 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)](/dladdr/3.md) if the symbol was dynamic, or looked up in the executable if static and the /proc filesystem is available to determine the executable path.

- 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)](/dladdr/3.md).

The array of formatted strings is returned as a contiguous memory address which can be freed by a single [free(3)](/free/3.md).

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

## SEE ALSO

[dladdr(3)](/dladdr/3.md), [elf(3)](/elf/3.md)

## HISTORY

The **backtrace**() library of functions first appeared in NetBSD 7.0 and FreeBSD 10.0.

## BUGS

1. Errors should not be printed but communicated to the caller differently.

2. Because these functions use [elf(3)](/elf/3.md) 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.