1.\" $NetBSD: backtrace.3,v 1.11 2025/01/23 12:08:12 christos Exp $ 2.\" 3.\" Copyright (c) 2012 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Christos Zoulas 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd January 22, 2025 31.Dt BACKTRACE 3 32.Os 33.Sh NAME 34.Nm backtrace , 35.Nm backtrace_symbols , 36.Nm backtrace_symbols_fd , 37.Nm backtrace_symbols_fmt , 38.Nm backtrace_symbols_fd_fmt 39.Nd fill in the backtrace of the currently executing thread 40.Sh LIBRARY 41.Lb libexecinfo 42.Sh SYNOPSIS 43.In execinfo.h 44.Ft size_t 45.Fn backtrace "void **addrlist" "size_t len" 46.Ft "int" 47.Fn backtrace_sandbox_init "void" 48.Ft "void" 49.Fn backtrace_sandbox_fini "void" 50.Ft "char **" 51.Fn backtrace_symbols "void * const *addrlist" "size_t len" 52.Ft int 53.Fn backtrace_symbols_fd "void * const *addrlist" "size_t len" "int fd" 54.Ft "char **" 55.Fn backtrace_symbols_fmt "void * const *addrlist" "size_t len" "const char *fmt" 56.Ft int 57.Fn backtrace_symbols_fd_fmt "void * const *addrlist" "size_t len" "int fd" "const char *fmt" 58.Sh DESCRIPTION 59The 60.Fn backtrace 61function places into the array pointed by 62.Fa addrlist 63the array of the values of the program counter for each frame called up to 64.Fa len 65frames. 66The number of frames found (which can be fewer than 67.Fa len ) 68is returned. 69.Pp 70The 71.Fn backtrace_sandbox_init 72and 73.Fn backtrace_sandbox_fini 74functions are intended to enable sandbox usage of 75.Nm . 76The 77.Fn backtrace_sandbox_init 78function must be called before the sandbox is entered, and will acquire any 79resources needed to function in a sandbox. 80The 81.Fn backtrace_sandbox_fini 82function will release the resources it acquired. 83.Pp 84The 85.Fn backtrace_symbols_fmt 86function takes an array of previously filled addresses from 87.Fn backtrace 88in 89.Fa addrlist 90of 91.Fa len 92elements, and uses 93.Fa fmt 94to format them. 95The formatting characters available are: 96.Bl -tag -width a -offset indent 97.It Dv a 98The numeric address of each element as would be printed using %p. 99.It Dv n 100The name of the nearest function symbol (smaller than the address element) 101as determined by 102.Xr dladdr 3 103if the symbol was dynamic, or looked up in the executable if static and 104the /proc filesystem is available to determine the executable path. 105.It Dv d 106The difference of the symbol address and the address element printed 107using 0x%tx. 108.It Dv D 109The difference of the symbol address and the address element printed using 110+0x%tx if non-zero, or nothing if zero. 111.It Dv f 112The filename of the symbol as determined by 113.Xr dladdr 3 . 114.El 115.Pp 116The array of formatted strings is returned as a contiguous memory address which 117can be freed by a single 118.Xr free 3 . 119.Pp 120The 121.Fn backtrace_symbols 122function is equivalent of calling 123.Fn backtrace_symbols_fmt 124with a format argument of 125.Dq "%a <%n%D> at %f" 126.Pp 127The 128.Fn backtrace_symbols_fd 129and 130.Fn backtrace_symbols_fd_fmt 131are similar to the non _fd named functions, only instead of returning 132an array of strings, they print a new-line separated array of strings in 133fd, and return 134.Dv 0 135on success and 136.Dv \-1 137on failure. 138.Sh RETURN VALUES 139The 140.Fn backtrace 141function returns the number of elements that were filled in the backtrace. 142The 143.Fn backtrace_symbols 144and 145.Fn backtrace_symbols_fmt 146return a string array on success, and 147.Dv NULL 148on failure, setting 149.Va errno . 150Diagnostic output may also be produced by the ELF symbol lookup functions. 151.Sh SEE ALSO 152.Xr dladdr 3 , 153.Xr elf 3 154.Sh HISTORY 155The 156.Fn backtrace 157library of functions first appeared in 158.Nx 7.0 . 159.Sh BUGS 160.Bl -enum 161.It 162Errors should not be printed but communicated to the caller differently. 163.It 164Because these functions use 165.Xr elf 3 166this is a separate library instead of being part of libc/libutil 167so that no library dependencies are introduced. 168.It 169The Linux versions of the functions (there are no _fmt variants) use 170.Ft int 171instead of 172.Ft size_t 173arguments. 174.It 175Since 176.Xr dladdr 3 177only deals with dynamic symbols, we need to find the symbols from the main 178portion of the program. 179For that we need to locate the executable, and we use procfs for 180finding it, which is not portable. 181.El 182