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