1.\" Copyright (c) 2021, Apple Inc. All rights reserved. 2. 3.Dd February 15, 2021 4.Dt BACKTRACE 9 5.Os Darwin 6. 7.Sh NAME 8.Nm backtrace , 9.Nm backtrace_user , 10.Nd gather the PC and return addresses of a thread's kernel or user call stack 11. 12.Sh SYNOPSIS 13.In kern/backtrace.h 14.Ft unsigned int 15.Fo backtrace 16.Fa "uintptr_t *bt" 17.Fa "unsigned int btlen" 18.Fa "struct backtrace_control *ctl" 19.Fa "backtrace_info_t *info_out" 20.Fc 21. 22.Ft unsigned int 23.Fo backtrace_user 24.Fa "uintptr_t *bt" 25.Fa "unsigned int btlen" 26.Fa "struct backtrace_control *ctl" 27.Fa "struct backtrace_user_info *info_out" 28.Fc 29. 30.Sh DESCRIPTION 31The 32.Nm backtrace 33and 34.Nm backtrace_user 35functions fill a buffer with the current PC and return addresses of a thread's 36kernel and user call stack, respectively. 37This is only possible when frame pointers are pushed to the stack, alongside the 38return addresses. 39.Xr clang 1 , 40disables this behavior with the 41.Fl fomit-frame-pointer 42flag, so it will prevent these functions from working. 43Furthermore, leaf functions and inlined function calls can also prevent 44backtracing from reporting the source-level function control flow. 45.Fn backtrace_user 46operates on user call stacks, while 47.Fn backtrace 48captures the current kernel call stack. 49Calling 50.Fn backtrace_user 51on a kernel thread 52.Pq which lacks a user context 53is undefined. 54.Pp 55Up to 56.Fa btlen 57instruction addresses are written to the buffer at 58.Fa bt . 59These functions also accept 60.Fa ctl 61and 62.Fa info_out 63arguments, described in 64.Sx BACKTRACE_CONTROL 65and 66.Sx BACKTRACE_INFO , 67respectively. 68.Pp 69.Fn backtrace 70records the kernel PC and call stack of the current thread. 71.Pp 72.Fn backtrace_user 73records the user PC and call stack of the current thread, which must be 74associated with a user space task. 75. 76.Sh RETURN VALUES 77The 78.Nm 79functions return the number of PC and return address elements written to the 80provided buffer. 81If there is space, the buffer is terminated with a NULL entry. 82The 83.Fa info_out 84argument will be set with information about the provided call stack. 85.Fn backtrace_user 86will set 87.Ft btui_error 88to an error of the 89.Xr copyin 9 90routine if an error occurred during call stack traversal. 91. 92.Sh BACKTRACE_CONTROL 93The 94.Nm 95functions accept a 96.Ft struct backtrace_control 97control argument to alter their behavior, 98with the following fields: 99.Bl -tag -width btc_user_thread 100.It Ft btc_flags 101These flags control the backtracer's behavior: 102.Bl -tag -width BTF_KERN_INTERRUPTED 103.It Dv BTF_KERN_INTERRUPTED 104For 105.Fn backtrace 106only, record the PC and return addresses of the interrupted call stack. 107.El 108.It Ft btc_frame_addr 109Start backtracing from the provided frame address. 110.It Ft btc_user_thread 111Capture the backtrace of the provided thread pointer. 112This must be either the current thread or a different thread that is suspended 113and unable to run in user space. 114.It Ft btc_user_copy 115For 116.Fn backtrace_user 117only, the function to use instead of 118.Xr copyin 9 119to copy data from the thread's user space virtual address space into the kernel. 120.It Ft btc_user_copy_context 121Additional data that's passed to the custom copy routine to act as private 122context. 123.El 124. 125.Sh BACKTRACE_INFO 126The 127.Nm 128functions report additional information through a 129.Ft backtrace_info_t 130flags out-parameter, 131with the following options: 132.Bl -tag -width BTI_TRUNCATED 133.It Dv BTI_64_BIT 134The PC and call stack return addresses are 64-bit quantities. 135.It Dv BTI_TRUNCATED 136The backtrace has been truncated and does not terminate with the base frame. 137.El 138.Pp 139The 140.Fn backtrace_user 141variant uses an out-parameter structure 142.Ft struct backtrace_user_info 143to return additional context: 144.Bl -tag -width btui_ 145.It Ft btui_info 146The 147.Ft backtrace_info_t 148flags, described above. 149.It Ft btui_error 150Any error encountered while copying data. 151.It Ft btui_async_start_index 152For Swift continuations 153.Pq async stacks , 154the location where the continuation hint was found and where it logically 155branches from the standard call stack. 156.It Ft btui_async_frame_addr 157The frame address of the Swift continuation to pass in to a subsequent call 158to 159.Fn backtrace_user 160.Pq as the control structure's frame address field 161to follow the corresponding async stack. 162.It Ft btui_next_frame_addr 163In the case of a truncated backtrace due to lack of space in the destination 164buffer, the next frame address to resume the backtrace operation. 165.El 166. 167.Sh EXAMPLE 168.Bd -literal 169uintptr_t bt[8] = {}; 170enum backtrace_info bti = BTI_NONE; 171unsigned int len = backtrace(bt, sizeof(bt) / sizeof(bt[0]), NULL, &bti); 172for (unsigned int i = 0; i < len; i++) { 173 printf("%d: 0x%lx\\n", i, bt[i]); 174} 175if (bti & BTI_TRUNCATED) { 176 printf("[... TRUNCATED ...]\\n"); 177} 178.Ed 179. 180.Sh SEE ALSO 181.Xr backtrace 3 182and 183.Xr copyin 9 184