Debian Codegraph @

upstream/debian-unstable/man3/backtrace.3

raw
1 '\" t
2 .\" Copyright 2007, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" %%%LICENSE_START(PERMISSIVE_MISC)
6 .\" Permission is hereby granted, free of charge, to any person obtaining
7 .\" a copy of this software and associated documentation files (the
8 .\" "Software"), to deal in the Software without restriction, including
9 .\" without limitation the rights to use, copy, modify, merge, publish,
10 .\" distribute, sublicense, and/or sell copies of the Software, and to
11 .\" permit persons to whom the Software is furnished to do so, subject to
12 .\" the following conditions:
13 .\"
14 .\" The above copyright notice and this permission notice shall be
15 .\" included in all copies or substantial portions of the Software.
16 .\"
17 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18 .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
20 .\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
21 .\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
22 .\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
23 .\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24 .\" %%%LICENSE_END
25 .\"
26 .TH backtrace 3 2026-02-08 "Linux man-pages 6.18"
27 .SH NAME
28 backtrace, backtrace_symbols, backtrace_symbols_fd \- support
29 for application self-debugging
30 .SH LIBRARY
31 Standard C library
32 .RI ( libc ,\~ \-lc )
33 .SH SYNOPSIS
34 .nf
35 .B #include <execinfo.h>
36 .P
37 .BR "int backtrace(" "int size;"
38 .BI " void *" buffer [ size "], int " size );
39 .P
40 .BR "char **backtrace_symbols(" "int size;"
41 .BI " void *const " buffer [ size "], int " size );
42 .BR "void backtrace_symbols_fd(" "int size;"
43 .BI " void *const " buffer [ size "], int " size ", int " fd );
44 .fi
45 .SH DESCRIPTION
46 .BR backtrace ()
47 returns a backtrace for the calling program,
48 in the array pointed to by
49 .IR buffer .
50 A backtrace is the series of currently active function calls for
51 the program.
52 Each item in the array pointed to by
53 .I buffer
54 is of type
55 .IR "void\ *" ,
56 and is the return address from
57 the corresponding stack frame.
58 The
59 .I size
60 argument specifies the maximum number of addresses
61 that can be stored in
62 .IR buffer .
63 If the backtrace is larger than
64 .IR size ,
65 then the addresses corresponding to the
66 .I size
67 most recent function calls are returned;
68 to obtain the complete backtrace, make sure that
69 .I buffer
70 and
71 .I size
72 are large enough.
73 .P
74 Given the set of addresses returned by
75 .BR backtrace ()
76 in
77 .IR buffer ,
78 .BR backtrace_symbols ()
79 translates the addresses into an array of strings that describe
80 the addresses symbolically.
81 The
82 .I size
83 argument specifies the number of addresses in
84 .IR buffer .
85 The symbolic representation of each address consists of the function name
86 (if this can be determined), a hexadecimal offset into the function,
87 and the actual return address (in hexadecimal).
88 The address of the array of string pointers is returned
89 as the function result of
90 .BR backtrace_symbols ().
91 This array is
92 .BR malloc (3)ed
93 by
94 .BR backtrace_symbols (),
95 and must be freed by the caller.
96 (The strings pointed to by the array of pointers
97 need not and should not be freed.)
98 .P
99 .BR backtrace_symbols_fd ()
100 takes the same
101 .I buffer
102 and
103 .I size
104 arguments as
105 .BR backtrace_symbols (),
106 but instead of returning an array of strings to the caller,
107 it writes the strings, one per line, to the file descriptor
108 .IR fd .
109 .BR backtrace_symbols_fd ()
110 does not call
111 .BR malloc (3),
112 and so can be employed in situations where the latter function might
113 fail, but see NOTES.
114 .SH RETURN VALUE
115 .BR backtrace ()
116 returns the number of addresses returned in
117 .IR buffer ,
118 which is not greater than
119 .IR size .
120 If the return value is less than
121 .IR size ,
122 then the full backtrace was stored;
123 if it is equal to
124 .IR size ,
125 then it may have been truncated,
126 in which case,
127 the addresses of the oldest stack frames are not returned.
128 .P
129 On success,
130 .BR backtrace_symbols ()
131 returns a pointer to the array
132 .BR malloc (3)ed
133 by the call;
134 on error, NULL is returned.
135 .SH ATTRIBUTES
136 For an explanation of the terms used in this section, see
137 .BR attributes (7).
138 .TS
139 allbox;
140 lbx lb lb
141 l l l.
142 Interface Attribute Value
143 T{
144 .na
145 .nh
146 .BR backtrace (),
147 .BR backtrace_symbols (),
148 .BR backtrace_symbols_fd ()
149 T} Thread safety MT-Safe
150 .TE
151 .SH STANDARDS
152 GNU.
153 .SH HISTORY
154 glibc 2.1.
155 .SH NOTES
156 These functions make some assumptions about how a function's return
157 address is stored on the stack.
158 Note the following:
159 .IP \[bu] 3
160 Omission of the frame pointers (as
161 implied by any of
162 .BR gcc (1)'s
163 nonzero optimization levels) may cause these assumptions to be
164 violated.
165 .IP \[bu]
166 Inlined functions do not have stack frames.
167 .IP \[bu]
168 Tail-call optimization causes one stack frame to replace another.
169 .IP \[bu]
170 .BR backtrace ()
171 and
172 .BR backtrace_symbols_fd ()
173 don't call
174 .BR malloc ()
175 explicitly, but they are part of
176 .IR libgcc ,
177 which gets loaded dynamically when first used.
178 Dynamic loading usually triggers a call to
179 .BR malloc (3).
180 If you need certain calls to these two functions to not allocate memory
181 (in signal handlers, for example), you need to make sure
182 .I libgcc
183 is loaded beforehand.
184 .P
185 The symbol names may be unavailable without the use of special linker
186 options.
187 For systems using the GNU linker, it is necessary to use the
188 .I \-rdynamic
189 linker option.
190 Note that names of "static" functions are not exposed,
191 and won't be available in the backtrace.
192 .SH EXAMPLES
193 The program below demonstrates the use of
194 .BR backtrace ()
195 and
196 .BR backtrace_symbols ().
197 The following shell session shows what we might see when running the
198 program:
199 .P
200 .in +4n
201 .EX
202 .RB "$" " cc \-rdynamic prog.c \-o prog"
203 .RB "$" " ./prog 3"
204 backtrace() returned 8 addresses
205 \&./prog(myfunc3+0x5c) [0x80487f0]
206 \&./prog [0x8048871]
207 \&./prog(myfunc+0x21) [0x8048894]
208 \&./prog(myfunc+0x1a) [0x804888d]
209 \&./prog(myfunc+0x1a) [0x804888d]
210 \&./prog(main+0x65) [0x80488fb]
211 \&/lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c]
212 \&./prog [0x8048711]
213 .EE
214 .in
215 .SS Program source
216 \&
217 .\" SRC BEGIN (backtrace.c)
218 .EX
219 #include <execinfo.h>
220 #include <stdio.h>
221 #include <stdlib.h>
222 #include <unistd.h>
223 \&
224 #define BT_BUF_SIZE 100
225 \&
226 void
227 myfunc3(void)
228 {
229 int nptrs;
230 void *buffer[BT_BUF_SIZE];
231 char **strings;
232 \&
233 nptrs = backtrace(buffer, BT_BUF_SIZE);
234 printf("backtrace() returned %d addresses\[rs]n", nptrs);
235 \&
236 /* The call backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO)
237 would produce similar output to the following: */
238 \&
239 strings = backtrace_symbols(buffer, nptrs);
240 if (strings == NULL) {
241 perror("backtrace_symbols");
242 exit(EXIT_FAILURE);
243 }
244 \&
245 for (size_t j = 0; j < nptrs; j++)
246 printf("%s\[rs]n", strings[j]);
247 \&
248 free(strings);
249 }
250 \&
251 static void /* "static" means don\[aq]t export the symbol. */
252 myfunc2(void)
253 {
254 myfunc3();
255 }
256 \&
257 void
258 myfunc(int ncalls)
259 {
260 if (ncalls > 1)
261 myfunc(ncalls \- 1);
262 else
263 myfunc2();
264 }
265 \&
266 int
267 main(int argc, char *argv[])
268 {
269 if (argc != 2) {
270 fprintf(stderr, "%s num\-calls\[rs]n", argv[0]);
271 exit(EXIT_FAILURE);
272 }
273 \&
274 myfunc(atoi(argv[1]));
275 exit(EXIT_SUCCESS);
276 }
277 .EE
278 .\" SRC END
279 .SH SEE ALSO
280 .BR addr2line (1),
281 .BR gcc (1),
282 .BR gdb (1),
283 .BR ld (1),
284 .BR dlopen (3),
285 .BR malloc (3)