1 .\" $NetBSD: backtrace.3,v 1.5 2013/08/22 17:08:43 christos Exp $
4 .\" Copyright (c) 2012 The NetBSD Foundation, Inc.
5 .\" All rights reserved.
7 .\" This code is derived from software contributed to The NetBSD Foundation
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
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.
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.
36 .Nd fill in the backtrace of the currently executing thread
42 .Fn backtrace "void **addrlist" "size_t len"
44 .Fn backtrace_symbols "void * const *addrlist" "size_t len"
46 .Fn backtrace_symbols_fd "void * const *addrlist" "size_t len" "int fd"
48 .Fn backtrace_symbols_fmt "void * const *addrlist" "size_t len" "const char *fmt"
50 .Fn backtrace_symbols_fd_fmt "void * const *addrlist" "size_t len" "int fd" "const char *fmt"
54 function places into the array pointed by
56 the array of the values of the program counter for each frame called up to
59 The number of frames found (which can be fewer than
64 .Fn backtrace_symbols_fmt
65 function takes an array of previously filled addresses from
74 The formatting characters available are:
75 .Bl -tag -width a -offset indent
77 The numeric address of each element as would be printed using %p.
79 The name of the nearest function symbol (smaller than the address element)
82 if the symbol was dynamic, or looked up in the executable if static and
83 the /proc filesystem is available to determine the executable path.
85 The difference of the symbol address and the address element printed
88 The difference of the symbol address and the address element printed using
89 +0x%tx if non-zero, or nothing if zero.
91 The filename of the symbol as determined by
95 The array of formatted strings is returned as a contiguous memory address which
96 can be freed by a single
100 .Fn backtrace_symbols
101 function is equivalent of calling
102 .Fn backtrace_symbols_fmt
103 with a format argument of
104 .Dv "%a <%n%D> at %f"
107 .Fn backtrace_symbols_fd
109 .Fn backtrace_symbols_fd_fmt
110 are similar to the non _fd named functions, only instead of returning
111 an array or strings, they print a new-line separated array of strings in
120 function returns the number of elements that were filled in the backtrace.
122 .Fn backtrace_symbols
124 .Fn backtrace_symbols_fmt
125 return a string array on success, and
129 Diagnostic output may also be produced by the ELF symbol lookup functions.
136 library of functions first appeared in
143 Errors should not be printed but communicated to the caller differently.
145 .\"Because these functions use
147 .\"this is a separate library instead of being part of libc/libutil
148 .\"so that no library dependencies are introduced.
150 The Linux versions of the functions (there are no _fmt variants) use