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