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