NAME

backtrace, backtrace_packed, backtrace_user, — gather the PC and return addresses of a thread's kernel or user call stack

SYNOPSIS

#include <kern/backtrace.h>

unsigned int
backtrace(uintptr_t *bt, unsigned int btlen, struct backtrace_control *ctl, backtrace_info_t *info_out);

size_t
backtrace_packed(backtrace_pack_t packing, uintptr_t *bt, size_t btlen, struct backtrace_control *ctl, backtrace_info_t *info_out);

unsigned int
backtrace_user(uintptr_t *bt, unsigned int btlen, struct backtrace_control *ctl, struct backtrace_user_info *info_out);

DESCRIPTION

The backtrace, backtrace_packed, and backtrace_user functions fill a buffer with the current PC and return addresses of a thread's kernel and user call stack, respectively. This is only possible when frame pointers are pushed to the stack, alongside the return addresses. clang(1), disables this behavior with the -fomit-frame-pointer flag, so it will prevent these functions from working. Furthermore, leaf functions and inlined function calls can also prevent backtracing from reporting the source-level function control flow. backtrace_user() operates on user call stacks, while backtrace() captures the current kernel call stack. backtrace_packed() writes a more compact representation of the return addresses to a buffer, which can be unpacked with backtrace_unpack(9). Calling backtrace_user() on a kernel thread (which lacks a user context) is undefined.

Up to btlen instruction addresses (or btsize bytes for backtrace_packed()) are written to the buffer at bt. These functions also accept ctl and info_out arguments, described in BACKTRACE_CONTROL and BACKTRACE_INFO, respectively. backtrace_packed() takes a backtrace_pack_t to control which packing scheme to use.

backtrace() records the kernel PC and call stack of the current thread.

backtrace_packed() records the kernel PC and call stack of the current thread in a buffer in a compact representation. See backtrace_pack(9) for a description of the supported formats.

backtrace_user() records the user PC and call stack of the current thread, which must be associated with a user space task.

RETURN VALUES

The backtrace functions return the number of PC and return address elements (or bytes for backtrace_packed()) written to the provided buffer. If there is space, the buffer is terminated with a NULL entry (except for backtrace_packed()). The info_out argument will be set with information about the provided call stack. backtrace_user() will set btui_error to an error of the copyin(9) routine if an error occurred during call stack traversal.

BACKTRACE_CONTROL

The backtrace functions accept a struct backtrace_control control argument to alter their behavior, with the following fields:

btc_flags

These flags control the backtracer's behavior:

BTF_KERN_INTERRUPTED: For backtrace() only, record the PC and return addresses of the interrupted call stack.

btc_frame_addr

Start backtracing from the provided frame address.

btc_user_thread

Capture the backtrace of the provided thread pointer. This must be either the current thread or a different thread that is suspended and unable to run in user space.

btc_user_copy

For backtrace_user() only, the function to use instead of copyin(9) to copy data from the thread's user space virtual address space into the kernel.

btc_user_copy_context

Additional data that's passed to the custom copy routine to act as private context.

BACKTRACE_INFO

The backtrace functions report additional information through a backtrace_info_t flags out-parameter, with the following options:

BTI_64_BIT: The PC and call stack return addresses are 64-bit quantities.
BTI_TRUNCATED: The backtrace has been truncated and does not terminate with the base frame.

The backtrace_user() variant uses an out-parameter structure struct backtrace_user_info to return additional context:

btui_info: The backtrace_info_t flags, described above.
btui_error: Any error encountered while copying data.
btui_async_start_index: For Swift continuations (async stacks), the location where the continuation hint was found and where it logically branches from the standard call stack.
btui_async_frame_addr: The frame address of the Swift continuation to pass in to a subsequent call to backtrace_user() (as the control structure's frame address field) to follow the corresponding async stack.
btui_next_frame_addr: In the case of a truncated backtrace due to lack of space in the destination buffer, the next frame address to resume the backtrace operation.

EXAMPLE

uintptr_t bt[8] = {};
enum backtrace_info bti = BTI_NONE;
unsigned int len = backtrace(bt, sizeof(bt) / sizeof(bt[0]), NULL, &bti);
for (unsigned int i = 0; i < len; i++)  {
	printf("%d: 0x%lx\n", i, bt[i]);
}
if (bti & BTI_TRUNCATED) {
	printf("[... TRUNCATED ...]\n");
}