Debian Codegraph @

upstream/debian-trixie/man3/backtrace.3

raw
1 '\" t
2 .\" Copyright (C) 2007 Michael Kerrisk <[email protected]>
3 .\" drawing on material by Justin Pryzby <[email protected]>
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 .\" References:
27 .\" glibc manual and source
28 .TH backtrace 3 2024-06-15 "Linux man-pages 6.9.1"
29 .SH NAME
30 backtrace, backtrace_symbols, backtrace_symbols_fd \- support
31 for application self-debugging
32 .SH LIBRARY
33 Standard C library
34 .RI ( libc ", " \-lc )
35 .SH SYNOPSIS
36 .nf
37 .B #include <execinfo.h>
38 .P
39 .BI "int backtrace(void *" buffer [. size "], int " size );
40 .P
41 .BI "char **backtrace_symbols(void *const " buffer [. size "], int " size );
42 .BI "void backtrace_symbols_fd(void *const " buffer [. size "], int " size ", \
43 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; if it is equal to
123 .IR size ,
124 then it may have been truncated, in which case the addresses of the
125 oldest stack frames are not returned.
126 .P
127 On success,
128 .BR backtrace_symbols ()
129 returns a pointer to the array
130 .BR malloc (3)ed
131 by the call;
132 on error, NULL is returned.
133 .SH ATTRIBUTES
134 For an explanation of the terms used in this section, see
135 .BR attributes (7).
136 .TS
137 allbox;
138 lbx lb lb
139 l l l.
140 Interface Attribute Value
141 T{
142 .na
143 .nh
144 .BR backtrace (),
145 .BR backtrace_symbols (),
146 .BR backtrace_symbols_fd ()
147 T} Thread safety MT-Safe
148 .TE
149 .SH STANDARDS
150 GNU.
151 .SH HISTORY
152 glibc 2.1.
153 .SH NOTES
154 These functions make some assumptions about how a function's return
155 address is stored on the stack.
156 Note the following:
157 .IP \[bu] 3
158 Omission of the frame pointers (as
159 implied by any of
160 .BR gcc (1)'s
161 nonzero optimization levels) may cause these assumptions to be
162 violated.
163 .IP \[bu]
164 Inlined functions do not have stack frames.
165 .IP \[bu]
166 Tail-call optimization causes one stack frame to replace another.
167 .IP \[bu]
168 .BR backtrace ()
169 and
170 .BR backtrace_symbols_fd ()
171 don't call
172 .BR malloc ()
173 explicitly, but they are part of
174 .IR libgcc ,
175 which gets loaded dynamically when first used.
176 Dynamic loading usually triggers a call to
177 .BR malloc (3).
178 If you need certain calls to these two functions to not allocate memory
179 (in signal handlers, for example), you need to make sure
180 .I libgcc
181 is loaded beforehand.
182 .P
183 The symbol names may be unavailable without the use of special linker
184 options.
185 For systems using the GNU linker, it is necessary to use the
186 .I \-rdynamic
187 linker option.
188 Note that names of "static" functions are not exposed,
189 and won't be available in the backtrace.
190 .SH EXAMPLES
191 The program below demonstrates the use of
192 .BR backtrace ()
193 and
194 .BR backtrace_symbols ().
195 The following shell session shows what we might see when running the
196 program:
197 .P
198 .in +4n
199 .EX
200 .RB "$" " cc \-rdynamic prog.c \-o prog"
201 .RB "$" " ./prog 3"
202 backtrace() returned 8 addresses
203 \&./prog(myfunc3+0x5c) [0x80487f0]
204 \&./prog [0x8048871]
205 \&./prog(myfunc+0x21) [0x8048894]
206 \&./prog(myfunc+0x1a) [0x804888d]
207 \&./prog(myfunc+0x1a) [0x804888d]
208 \&./prog(main+0x65) [0x80488fb]
209 \&/lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c]
210 \&./prog [0x8048711]
211 .EE
212 .in
213 .SS Program source
214 \&
215 .\" SRC BEGIN (backtrace.c)
216 .EX
217 #include <execinfo.h>
218 #include <stdio.h>
219 #include <stdlib.h>
220 #include <unistd.h>
221 \&
222 #define BT_BUF_SIZE 100
223 \&
224 void
225 myfunc3(void)
226 {
227 int nptrs;
228 void *buffer[BT_BUF_SIZE];
229 char **strings;
230 \&
231 nptrs = backtrace(buffer, BT_BUF_SIZE);
232 printf("backtrace() returned %d addresses\[rs]n", nptrs);
233 \&
234 /* The call backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO)
235 would produce similar output to the following: */
236 \&
237 strings = backtrace_symbols(buffer, nptrs);
238 if (strings == NULL) {
239 perror("backtrace_symbols");
240 exit(EXIT_FAILURE);
241 }
242 \&
243 for (size_t j = 0; j < nptrs; j++)
244 printf("%s\[rs]n", strings[j]);
245 \&
246 free(strings);
247 }
248 \&
249 static void /* "static" means don\[aq]t export the symbol... */
250 myfunc2(void)
251 {
252 myfunc3();
253 }
254 \&
255 void
256 myfunc(int ncalls)
257 {
258 if (ncalls > 1)
259 myfunc(ncalls \- 1);
260 else
261 myfunc2();
262 }
263 \&
264 int
265 main(int argc, char *argv[])
266 {
267 if (argc != 2) {
268 fprintf(stderr, "%s num\-calls\[rs]n", argv[0]);
269 exit(EXIT_FAILURE);
270 }
271 \&
272 myfunc(atoi(argv[1]));
273 exit(EXIT_SUCCESS);
274 }
275 .EE
276 .\" SRC END
277 .SH SEE ALSO
278 .BR addr2line (1),
279 .BR gcc (1),
280 .BR gdb (1),
281 .BR ld (1),
282 .BR dlopen (3),
283 .BR malloc (3)