1.\" $OpenBSD: backtrace.3,v 1.3 2021/06/11 19:36:00 jmc Exp $ 2.\" 3.\" Copyright (c) 2021 Todd Mortimer <mortimer@openbsd.org> 4.\" Copyright (c) 2012 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Christos Zoulas 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: June 11 2021 $ 32.Dt BACKTRACE 3 33.Os 34.Sh NAME 35.Nm backtrace , 36.Nm backtrace_symbols , 37.Nm backtrace_symbols_fd , 38.Nm backtrace_symbols_fmt , 39.Nm backtrace_symbols_fd_fmt 40.Nd fill in the backtrace of the currently executing thread 41.Sh SYNOPSIS 42.In execinfo.h 43.Ft size_t 44.Fn backtrace "void **addrlist" "size_t len" 45.Ft "char **" 46.Fn backtrace_symbols "void * const *addrlist" "size_t len" 47.Ft int 48.Fn backtrace_symbols_fd "void * const *addrlist" "size_t len" "int fd" 49.Ft "char **" 50.Fn backtrace_symbols_fmt "void * const *addrlist" "size_t len" "const char *fmt" 51.Ft int 52.Fn backtrace_symbols_fd_fmt "void * const *addrlist" "size_t len" "int fd" "const char *fmt" 53.Sh DESCRIPTION 54The 55.Fn backtrace 56function places into the array pointed by 57.Fa addrlist 58the array of the values of the program counter for each frame called up to 59.Fa len 60frames. 61The number of frames found (which can be fewer than 62.Fa len ) 63is returned. 64.Pp 65The 66.Fn backtrace_symbols_fmt 67function takes an array of previously filled addresses from 68.Fn backtrace 69in 70.Fa addrlist 71of 72.Fa len 73elements, and uses 74.Fa fmt 75to format them. 76The formatting characters available are: 77.Bl -tag -width a -offset indent 78.It Dv a 79The numeric address of each element as would be printed using %p. 80.It Dv n 81The name of the nearest function symbol (smaller than the address element) 82as determined by 83.Xr dladdr 3 84.It Dv d 85The difference of the symbol address and the address element printed 86using 0x%tx. 87.It Dv D 88The difference of the symbol address and the address element printed using 89+0x%tx if non-zero, or nothing if zero. 90.It Dv f 91The filename of the symbol as determined by 92.Xr dladdr 3 . 93.El 94.Pp 95The array of formatted strings is returned as a contiguous memory address which 96can be freed by a single 97.Xr free 3 . 98.Pp 99The 100.Fn backtrace_symbols 101function is equivalent of calling 102.Fn backtrace_symbols_fmt 103with a format argument of 104.Dq "%a <%n%D> at %f" 105.Pp 106The 107.Fn backtrace_symbols_fd 108and 109.Fn backtrace_symbols_fd_fmt 110are similar to the non _fd named functions, only instead of returning 111an array of strings, they print a new-line separated array of strings in 112fd, and return 113.Dv 0 114on success and 115.Dv \-1 116on failure. 117.Sh RETURN VALUES 118The 119.Fn backtrace 120function returns the number of elements that were filled in the backtrace. 121The 122.Fn backtrace_symbols 123and 124.Fn backtrace_symbols_fmt 125return a string array on success, and 126.Dv NULL 127on failure, setting 128.Va errno . 129.Sh SEE ALSO 130.Xr dladdr 3 131.Sh HISTORY 132The 133.Fn backtrace 134library of functions first appeared in 135.Nx 7.0 136and was imported into 137.Ox 7.0 . 138.Sh BUGS 139.Bl -enum 140.It 141Only unwinding with libunwind is supported. 142On architectures without libunwind the 143.Fn backtrace 144function simply returns 0. 145.It 146Since 147.Xr dladdr 3 148only deals with dynamic symbols, local symbols from the main 149portion of the program are not printed. 150.El 151