]>
Commit | Line | Data |
---|---|---|
c11b1abf | 1 | .\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com> |
46b75119 MK |
2 | .\" drawing on material by Justin Pryzby <pryzbyj@justinpryzby.com> |
3 | .\" | |
7c576f45 | 4 | .\" %%%LICENSE_START(PERMISSIVE_MISC) |
46b75119 MK |
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: | |
12 | .\" | |
13 | .\" The above copyright notice and this permission notice shall be | |
14 | .\" included in all copies or substantial portions of the Software. | |
15 | .\" | |
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. | |
8ff7380d | 23 | .\" %%%LICENSE_END |
46b75119 MK |
24 | .\" |
25 | .\" References: | |
26 | .\" glibc manual and source | |
45186a5d | 27 | .TH BACKTRACE 3 2021-03-22 "Linux man-pages (unreleased)" |
46b75119 MK |
28 | .SH NAME |
29 | backtrace, backtrace_symbols, backtrace_symbols_fd \- support | |
30 | for application self-debugging | |
b813014f AC |
31 | .SH LIBRARY |
32 | Standard C library | |
33 | .RI ( libc ", " \-lc ) | |
46b75119 | 34 | .SH SYNOPSIS |
7b5d39f4 | 35 | .nf |
46b75119 | 36 | .B #include <execinfo.h> |
dbfe9c70 | 37 | .PP |
7b5d39f4 | 38 | .BI "int backtrace(void **" buffer ", int " size ); |
dbfe9c70 | 39 | .PP |
7b5d39f4 MK |
40 | .BI "char **backtrace_symbols(void *const *" buffer ", int " size ); |
41 | .BI "void backtrace_symbols_fd(void *const *" buffer ", int " size ", int " fd ); | |
42 | .fi | |
46b75119 MK |
43 | .SH DESCRIPTION |
44 | .BR backtrace () | |
45 | returns a backtrace for the calling program, | |
46 | in the array pointed to by | |
47 | .IR buffer . | |
48 | A backtrace is the series of currently active function calls for | |
49 | the program. | |
50 | Each item in the array pointed to by | |
51 | .I buffer | |
c9942389 MK |
52 | is of type |
53 | .IR "void\ *" , | |
54 | and is the return address from | |
46b75119 MK |
55 | the corresponding stack frame. |
56 | The | |
57 | .I size | |
58 | argument specifies the maximum number of addresses | |
59 | that can be stored in | |
60 | .IR buffer . | |
61 | If the backtrace is larger than | |
62 | .IR size , | |
63 | then the addresses corresponding to the | |
64 | .I size | |
65 | most recent function calls are returned; | |
66 | to obtain the complete backtrace, make sure that | |
67 | .I buffer | |
68 | and | |
69 | .I size | |
70 | are large enough. | |
847e0d88 | 71 | .PP |
46b75119 MK |
72 | Given the set of addresses returned by |
73 | .BR backtrace () | |
74 | in | |
75 | .IR buffer , | |
76 | .BR backtrace_symbols () | |
77 | translates the addresses into an array of strings that describe | |
78 | the addresses symbolically. | |
79 | The | |
80 | .I size | |
81 | argument specifies the number of addresses in | |
82 | .IR buffer . | |
83 | The symbolic representation of each address consists of the function name | |
84 | (if this can be determined), a hexadecimal offset into the function, | |
85 | and the actual return address (in hexadecimal). | |
86 | The address of the array of string pointers is returned | |
87 | as the function result of | |
88 | .BR backtrace_symbols (). | |
89 | This array is | |
90 | .BR malloc (3)ed | |
988db661 | 91 | by |
46b75119 MK |
92 | .BR backtrace_symbols (), |
93 | and must be freed by the caller. | |
02770bac | 94 | (The strings pointed to by the array of pointers |
46b75119 | 95 | need not and should not be freed.) |
847e0d88 | 96 | .PP |
46b75119 MK |
97 | .BR backtrace_symbols_fd () |
98 | takes the same | |
99 | .I buffer | |
100 | and | |
101 | .I size | |
102 | arguments as | |
103 | .BR backtrace_symbols (), | |
104 | but instead of returning an array of strings to the caller, | |
105 | it writes the strings, one per line, to the file descriptor | |
106 | .IR fd . | |
ada00e83 | 107 | .BR backtrace_symbols_fd () |
46b75119 MK |
108 | does not call |
109 | .BR malloc (3), | |
ca5d5169 SP |
110 | and so can be employed in situations where the latter function might |
111 | fail, but see NOTES. | |
47297adb | 112 | .SH RETURN VALUE |
46b75119 MK |
113 | .BR backtrace () |
114 | returns the number of addresses returned in | |
115 | .IR buffer , | |
116 | which is not greater than | |
117 | .IR size . | |
118 | If the return value is less than | |
119 | .IR size , | |
120 | then the full backtrace was stored; if it is equal to | |
121 | .IR size , | |
122 | then it may have been truncated, in which case the addresses of the | |
123 | oldest stack frames are not returned. | |
847e0d88 | 124 | .PP |
46b75119 MK |
125 | On success, |
126 | .BR backtrace_symbols () | |
127 | returns a pointer to the array | |
128 | .BR malloc (3)ed | |
129 | by the call; | |
130 | on error, NULL is returned. | |
c343e74c MK |
131 | .SH VERSIONS |
132 | .BR backtrace (), | |
133 | .BR backtrace_symbols (), | |
134 | and | |
135 | .BR backtrace_symbols_fd () | |
7316d60f | 136 | are provided in glibc since version 2.1. |
952509e7 MS |
137 | .SH ATTRIBUTES |
138 | For an explanation of the terms used in this section, see | |
139 | .BR attributes (7). | |
c466875e MK |
140 | .ad l |
141 | .nh | |
952509e7 MS |
142 | .TS |
143 | allbox; | |
c466875e | 144 | lbx lb lb |
952509e7 MS |
145 | l l l. |
146 | Interface Attribute Value | |
147 | T{ | |
148 | .BR backtrace (), | |
952509e7 | 149 | .BR backtrace_symbols (), |
952509e7 MS |
150 | .BR backtrace_symbols_fd () |
151 | T} Thread safety MT-Safe | |
152 | .TE | |
c466875e MK |
153 | .hy |
154 | .ad | |
155 | .sp 1 | |
3113c7f3 | 156 | .SH STANDARDS |
46b75119 MK |
157 | These functions are GNU extensions. |
158 | .SH NOTES | |
159 | These functions make some assumptions about how a function's return | |
160 | address is stored on the stack. | |
161 | Note the following: | |
162 | .IP * 3 | |
163 | Omission of the frame pointers (as | |
164 | implied by any of | |
165 | .BR gcc (1)'s | |
c7094399 | 166 | nonzero optimization levels) may cause these assumptions to be |
46b75119 MK |
167 | violated. |
168 | .IP * | |
169 | Inlined functions do not have stack frames. | |
170 | .IP * | |
171 | Tail-call optimization causes one stack frame to replace another. | |
ca5d5169 SP |
172 | .IP * |
173 | .BR backtrace () | |
174 | and | |
175 | .BR backtrace_symbols_fd () | |
176 | don't call | |
177 | .BR malloc () | |
454f90d7 MK |
178 | explicitly, but they are part of |
179 | .IR libgcc , | |
180 | which gets loaded dynamically when first used. | |
181 | Dynamic loading usually triggers a call to | |
182 | .BR malloc (3). | |
183 | If you need certain calls to these two functions to not allocate memory | |
184 | (in signal handlers, for example), you need to make sure | |
185 | .I libgcc | |
186 | is loaded beforehand. | |
46b75119 MK |
187 | .PP |
188 | The symbol names may be unavailable without the use of special linker | |
189 | options. | |
190 | For systems using the GNU linker, it is necessary to use the | |
191 | .I \-rdynamic | |
192 | linker option. | |
193 | Note that names of "static" functions are not exposed, | |
194 | and won't be available in the backtrace. | |
a14af333 | 195 | .SH EXAMPLES |
46b75119 MK |
196 | The program below demonstrates the use of |
197 | .BR backtrace () | |
198 | and | |
199 | .BR backtrace_symbols (). | |
200 | The following shell session shows what we might see when running the | |
201 | program: | |
e646a1ba | 202 | .PP |
088a639b | 203 | .in +4n |
e646a1ba | 204 | .EX |
b43a3b30 MK |
205 | .RB "$" " cc \-rdynamic prog.c \-o prog" |
206 | .RB "$" " ./prog 3" | |
207 | backtrace() returned 8 addresses | |
208 | \&./prog(myfunc3+0x5c) [0x80487f0] | |
209 | \&./prog [0x8048871] | |
210 | \&./prog(myfunc+0x21) [0x8048894] | |
211 | \&./prog(myfunc+0x1a) [0x804888d] | |
212 | \&./prog(myfunc+0x1a) [0x804888d] | |
213 | \&./prog(main+0x65) [0x80488fb] | |
214 | \&/lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c] | |
215 | \&./prog [0x8048711] | |
b8302363 | 216 | .EE |
e646a1ba | 217 | .in |
9c330504 | 218 | .SS Program source |
d84d0300 | 219 | \& |
e7d0bb47 | 220 | .EX |
46b75119 MK |
221 | #include <execinfo.h> |
222 | #include <stdio.h> | |
223 | #include <stdlib.h> | |
224 | #include <unistd.h> | |
225 | ||
cefcfd92 MK |
226 | #define BT_BUF_SIZE 100 |
227 | ||
46b75119 MK |
228 | void |
229 | myfunc3(void) | |
230 | { | |
88893a77 | 231 | int nptrs; |
cefcfd92 | 232 | void *buffer[BT_BUF_SIZE]; |
46b75119 MK |
233 | char **strings; |
234 | ||
cefcfd92 | 235 | nptrs = backtrace(buffer, BT_BUF_SIZE); |
d1a71985 | 236 | printf("backtrace() returned %d addresses\en", nptrs); |
46b75119 MK |
237 | |
238 | /* The call backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO) | |
239 | would produce similar output to the following: */ | |
240 | ||
241 | strings = backtrace_symbols(buffer, nptrs); | |
242 | if (strings == NULL) { | |
243 | perror("backtrace_symbols"); | |
244 | exit(EXIT_FAILURE); | |
245 | } | |
246 | ||
88893a77 | 247 | for (int j = 0; j < nptrs; j++) |
d1a71985 | 248 | printf("%s\en", strings[j]); |
46b75119 MK |
249 | |
250 | free(strings); | |
251 | } | |
252 | ||
f81fb444 | 253 | static void /* "static" means don\(aqt export the symbol... */ |
46b75119 MK |
254 | myfunc2(void) |
255 | { | |
256 | myfunc3(); | |
257 | } | |
258 | ||
259 | void | |
260 | myfunc(int ncalls) | |
261 | { | |
262 | if (ncalls > 1) | |
29059a65 | 263 | myfunc(ncalls \- 1); |
46b75119 MK |
264 | else |
265 | myfunc2(); | |
266 | } | |
267 | ||
268 | int | |
269 | main(int argc, char *argv[]) | |
270 | { | |
271 | if (argc != 2) { | |
d1a71985 | 272 | fprintf(stderr, "%s num\-calls\en", argv[0]); |
46b75119 MK |
273 | exit(EXIT_FAILURE); |
274 | } | |
275 | ||
276 | myfunc(atoi(argv[1])); | |
277 | exit(EXIT_SUCCESS); | |
278 | } | |
e7d0bb47 | 279 | .EE |
46b75119 | 280 | .SH SEE ALSO |
4f9d01a9 | 281 | .BR addr2line (1), |
46b75119 | 282 | .BR gcc (1), |
d64b3725 | 283 | .BR gdb (1), |
46b75119 MK |
284 | .BR ld (1), |
285 | .BR dlopen (3), | |
286 | .BR malloc (3) |