1 .\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
2 .\" drawing on material by Justin Pryzby <pryzbyj@justinpryzby.com>
4 .\" %%%LICENSE_START(PERMISSIVE_MISC)
5 .\" Permission is hereby granted, free of charge, to any person obtaining
6 .\" a copy of this software and associated documentation files (the
7 .\" "Software"), to deal in the Software without restriction, including
8 .\" without limitation the rights to use, copy, modify, merge, publish,
9 .\" distribute, sublicense, and/or sell copies of the Software, and to
10 .\" permit persons to whom the Software is furnished to do so, subject to
11 .\" the following conditions:
13 .\" The above copyright notice and this permission notice shall be
14 .\" included in all copies or substantial portions of the Software.
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17 .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19 .\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
20 .\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
21 .\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
22 .\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
26 .\" glibc manual and source
27 .TH BACKTRACE 3 2017-09-15 GNU "Linux Programmer's Manual"
29 backtrace, backtrace_symbols, backtrace_symbols_fd \- support
30 for application self-debugging
32 .B #include <execinfo.h>
39 .B char **backtrace_symbols(void *const
44 .B void backtrace_symbols_fd(void *const
52 returns a backtrace for the calling program,
53 in the array pointed to by
55 A backtrace is the series of currently active function calls for
57 Each item in the array pointed to by
61 and is the return address from
62 the corresponding stack frame.
65 argument specifies the maximum number of addresses
68 If the backtrace is larger than
70 then the addresses corresponding to the
72 most recent function calls are returned;
73 to obtain the complete backtrace, make sure that
79 Given the set of addresses returned by
83 .BR backtrace_symbols ()
84 translates the addresses into an array of strings that describe
85 the addresses symbolically.
88 argument specifies the number of addresses in
90 The symbolic representation of each address consists of the function name
91 (if this can be determined), a hexadecimal offset into the function,
92 and the actual return address (in hexadecimal).
93 The address of the array of string pointers is returned
94 as the function result of
95 .BR backtrace_symbols ().
99 .BR backtrace_symbols (),
100 and must be freed by the caller.
101 (The strings pointed to by the array of pointers
102 need not and should not be freed.)
104 .BR backtrace_symbols_fd ()
110 .BR backtrace_symbols (),
111 but instead of returning an array of strings to the caller,
112 it writes the strings, one per line, to the file descriptor
114 .BR backtrace_symbols_fd ()
117 and so can be employed in situations where the latter function might
121 returns the number of addresses returned in
123 which is not greater than
125 If the return value is less than
127 then the full backtrace was stored; if it is equal to
129 then it may have been truncated, in which case the addresses of the
130 oldest stack frames are not returned.
133 .BR backtrace_symbols ()
134 returns a pointer to the array
137 on error, NULL is returned.
140 .BR backtrace_symbols (),
142 .BR backtrace_symbols_fd ()
143 are provided in glibc since version 2.1.
145 For an explanation of the terms used in this section, see
151 Interface Attribute Value
155 .BR backtrace_symbols (),
157 .BR backtrace_symbols_fd ()
158 T} Thread safety MT-Safe
161 These functions are GNU extensions.
163 These functions make some assumptions about how a function's return
164 address is stored on the stack.
167 Omission of the frame pointers (as
170 nonzero optimization levels) may cause these assumptions to be
173 Inlined functions do not have stack frames.
175 Tail-call optimization causes one stack frame to replace another.
179 .BR backtrace_symbols_fd ()
182 explicitly, but they are part of
184 which gets loaded dynamically when first used.
185 Dynamic loading usually triggers a call to
187 If you need certain calls to these two functions to not allocate memory
188 (in signal handlers, for example), you need to make sure
190 is loaded beforehand.
192 The symbol names may be unavailable without the use of special linker
194 For systems using the GNU linker, it is necessary to use the
197 Note that names of "static" functions are not exposed,
198 and won't be available in the backtrace.
200 The program below demonstrates the use of
203 .BR backtrace_symbols ().
204 The following shell session shows what we might see when running the
209 .RB "$" " cc \-rdynamic prog.c \-o prog"
211 backtrace() returned 8 addresses
212 \&./prog(myfunc3+0x5c) [0x80487f0]
214 \&./prog(myfunc+0x21) [0x8048894]
215 \&./prog(myfunc+0x1a) [0x804888d]
216 \&./prog(myfunc+0x1a) [0x804888d]
217 \&./prog(main+0x65) [0x80488fb]
218 \&/lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c]
225 #include <execinfo.h>
230 #define BT_BUF_SIZE 100
236 void *buffer[BT_BUF_SIZE];
239 nptrs = backtrace(buffer, BT_BUF_SIZE);
240 printf("backtrace() returned %d addresses\\n", nptrs);
242 /* The call backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO)
243 would produce similar output to the following: */
245 strings = backtrace_symbols(buffer, nptrs);
246 if (strings == NULL) {
247 perror("backtrace_symbols");
251 for (j = 0; j < nptrs; j++)
252 printf("%s\\n", strings[j]);
257 static void /* "static" means don\(aqt export the symbol... */
273 main(int argc, char *argv[])
276 fprintf(stderr, "%s num\-calls\\n", argv[0]);
280 myfunc(atoi(argv[1]));