1.\" $NetBSD: backtrace.3,v 1.5 2013/08/22 17:08:43 christos Exp $ 2.\" $FreeBSD$ 3.\" 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 August 23, 2013 32.Dt BACKTRACE 3 33.Os 34.Sh NAME 35.Nm backtrace 36.Nd fill in the backtrace of the currently executing thread 37.Sh LIBRARY 38.Lb libexecinfo 39.Sh SYNOPSIS 40.In execinfo.h 41.Ft size_t 42.Fn backtrace "void **addrlist" "size_t len" 43.Ft "char **" 44.Fn backtrace_symbols "void * const *addrlist" "size_t len" 45.Ft int 46.Fn backtrace_symbols_fd "void * const *addrlist" "size_t len" "int fd" 47.Ft "char **" 48.Fn backtrace_symbols_fmt "void * const *addrlist" "size_t len" "const char *fmt" 49.Ft int 50.Fn backtrace_symbols_fmt_fd "void * const *addrlist" "size_t len" "const char *fmt" "int fd" 51.Sh DESCRIPTION 52The 53.Fn backtrace 54function places into the array pointed by 55.Fa addrlist 56the array of the values of the program counter for each frame called up to 57.Fa len 58frames. 59The number of frames found (which can be fewer than 60.Fa len ) 61is returned. 62.Pp 63The 64.Fn backtrace_symbols_fmt 65function takes an array of previously filled addresses from 66.Fn backtrace 67in 68.Fa addrlist 69of 70.Fa len 71elements, and uses 72.Fa fmt 73to format them. 74The formatting characters available are: 75.Bl -tag -width a -offset indent 76.It Dv a 77The numeric address of each element as would be printed using %p. 78.It Dv n 79The name of the nearest function symbol (smaller than the address element) 80as determined by 81.Xr dladdr 3 82if the symbol was dynamic, or looked up in the executable if static and 83the /proc filesystem is available to determine the executable path. 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 addresss 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.Dv "%a <%n%D> at %f" 105.Pp 106The 107.Fn backtrace_symbols_fd 108and 109.Fn backtrace_symbols_fmt_fd 110are similar to the non _fd named functions, only instead of returning 111an array or 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 . 129Diagnostic output may also be produced by the ELF symbol lookup functions. 130.Sh SEE ALSO 131.Xr dladdr 3 , 132.Xr elf 3 133.Sh HISTORY 134The 135.Fn backtrace 136library of functions first appeared in 137.Nx 7.0 138and 139.Fx 10.0 . 140.Sh BUGS 141.Bl -enum 142.It 143Errors should not be printed but communicated to the caller differently. 144.It 145Because these functions use 146.Xr elf 3 147this is a separate library instead of being part of libc/libutil 148so that no library dependencies are introduced. 149.It 150The Linux versions of the functions (there are no _fmt variants) use 151.Ft int 152instead of 153.Ft size_t 154arguments. 155.El 156