1.\" $NetBSD: backtrace.3,v 1.10 2017/10/22 14:07:03 abhinav 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 November 5, 2015 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 "char **" 47.Fn backtrace_symbols "void * const *addrlist" "size_t len" 48.Ft int 49.Fn backtrace_symbols_fd "void * const *addrlist" "size_t len" "int fd" 50.Ft "char **" 51.Fn backtrace_symbols_fmt "void * const *addrlist" "size_t len" "const char *fmt" 52.Ft int 53.Fn backtrace_symbols_fd_fmt "void * const *addrlist" "size_t len" "int fd" "const char *fmt" 54.Sh DESCRIPTION 55The 56.Fn backtrace 57function places into the array pointed by 58.Fa addrlist 59the array of the values of the program counter for each frame called up to 60.Fa len 61frames. 62The number of frames found (which can be fewer than 63.Fa len ) 64is returned. 65.Pp 66The 67.Fn backtrace_symbols_fmt 68function takes an array of previously filled addresses from 69.Fn backtrace 70in 71.Fa addrlist 72of 73.Fa len 74elements, and uses 75.Fa fmt 76to format them. 77The formatting characters available are: 78.Bl -tag -width a -offset indent 79.It Dv a 80The numeric address of each element as would be printed using %p. 81.It Dv n 82The name of the nearest function symbol (smaller than the address element) 83as determined by 84.Xr dladdr 3 85if the symbol was dynamic, or looked up in the executable if static and 86the /proc filesystem is available to determine the executable path. 87.It Dv d 88The difference of the symbol address and the address element printed 89using 0x%tx. 90.It Dv D 91The difference of the symbol address and the address element printed using 92+0x%tx if non-zero, or nothing if zero. 93.It Dv f 94The filename of the symbol as determined by 95.Xr dladdr 3 . 96.El 97.Pp 98The array of formatted strings is returned as a contiguous memory address which 99can be freed by a single 100.Xr free 3 . 101.Pp 102The 103.Fn backtrace_symbols 104function is equivalent of calling 105.Fn backtrace_symbols_fmt 106with a format argument of 107.Dq "%a <%n%D> at %f" 108.Pp 109The 110.Fn backtrace_symbols_fd 111and 112.Fn backtrace_symbols_fd_fmt 113are similar to the non _fd named functions, only instead of returning 114an array of strings, they print a new-line separated array of strings in 115fd, and return 116.Dv 0 117on success and 118.Dv \-1 119on failure. 120.Sh RETURN VALUES 121The 122.Fn backtrace 123function returns the number of elements that were filled in the backtrace. 124The 125.Fn backtrace_symbols 126and 127.Fn backtrace_symbols_fmt 128return a string array on success, and 129.Dv NULL 130on failure, setting 131.Va errno . 132Diagnostic output may also be produced by the ELF symbol lookup functions. 133.Sh SEE ALSO 134.Xr dladdr 3 , 135.Xr elf 3 136.Sh HISTORY 137The 138.Fn backtrace 139library of functions first appeared in 140.Nx 7.0 . 141.Sh BUGS 142.Bl -enum 143.It 144Errors should not be printed but communicated to the caller differently. 145.It 146Because these functions use 147.Xr elf 3 148this is a separate library instead of being part of libc/libutil 149so that no library dependencies are introduced. 150.It 151The Linux versions of the functions (there are no _fmt variants) use 152.Ft int 153instead of 154.Ft size_t 155arguments. 156.It 157Since 158.Xr dladdr 3 159only deals with dynamic symbols, we need to find the symbols from the main 160portion of the program. 161For that we need to locate the executable, and we use procfs for 162finding it, which is not portable. 163.El 164