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 2008-06-14 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 fail.
120 returns the number of addresses returned in
122 which is not greater than
124 If the return value is less than
126 then the full backtrace was stored; if it is equal to
128 then it may have been truncated, in which case the addresses of the
129 oldest stack frames are not returned.
132 .BR backtrace_symbols ()
133 returns a pointer to the array
136 on error, NULL is returned.
139 .BR backtrace_symbols (),
141 .BR backtrace_symbols_fd ()
142 are provided in glibc since version 2.1.
144 These functions are GNU extensions.
146 These functions make some assumptions about how a function's return
147 address is stored on the stack.
150 Omission of the frame pointers (as
153 nonzero optimization levels) may cause these assumptions to be
156 Inlined functions do not have stack frames.
158 Tail-call optimization causes one stack frame to replace another.
160 The symbol names may be unavailable without the use of special linker
162 For systems using the GNU linker, it is necessary to use the
165 Note that names of "static" functions are not exposed,
166 and won't be available in the backtrace.
168 The program below demonstrates the use of
171 .BR backtrace_symbols ().
172 The following shell session shows what we might see when running the
177 .RB "$" " cc \-rdynamic prog.c \-o prog"
179 backtrace() returned 8 addresses
180 \&./prog(myfunc3+0x5c) [0x80487f0]
182 \&./prog(myfunc+0x21) [0x8048894]
183 \&./prog(myfunc+0x1a) [0x804888d]
184 \&./prog(myfunc+0x1a) [0x804888d]
185 \&./prog(main+0x65) [0x80488fb]
186 \&/lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c]
193 #include <execinfo.h>
206 nptrs = backtrace(buffer, SIZE);
207 printf("backtrace() returned %d addresses\\n", nptrs);
209 /* The call backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO)
210 would produce similar output to the following: */
212 strings = backtrace_symbols(buffer, nptrs);
213 if (strings == NULL) {
214 perror("backtrace_symbols");
218 for (j = 0; j < nptrs; j++)
219 printf("%s\\n", strings[j]);
224 static void /* "static" means don\(aqt export the symbol... */
240 main(int argc, char *argv[])
243 fprintf(stderr, "%s num\-calls\\n", argv[0]);
247 myfunc(atoi(argv[1]));
257 This page is part of release 3.64 of the Linux
260 A description of the project,
261 and information about reporting bugs,
263 \%http://www.kernel.org/doc/man\-pages/.