1backtrace(3) Library Functions Manual backtrace(3)
2
6 backtrace, backtrace_symbols, backtrace_symbols_fd - support for appli‐
7 cation self-debugging
8
10 Standard C library (libc, -lc)
11
13 #include <execinfo.h>
14 int backtrace(void *buffer[.size], int size);
16 char **backtrace_symbols(void *const buffer[.size], int size);
18 void backtrace_symbols_fd(void *const buffer[.size], int size, int fd);
19
21 backtrace() returns a backtrace for the calling program, in the array
22 pointed to by buffer. A backtrace is the series of currently active
23 function calls for the program. Each item in the array pointed to by
24 buffer is of type void *, and is the return address from the corre‐
25 sponding stack frame. The size argument specifies the maximum number
26 of addresses that can be stored in buffer. If the backtrace is larger
27 than size, then the addresses corresponding to the size most recent
28 function calls are returned; to obtain the complete backtrace, make
29 sure that buffer and size are large enough.
30 Given the set of addresses returned by backtrace() in buffer, back‐
32 trace_symbols() translates the addresses into an array of strings that
33 describe the addresses symbolically. The size argument specifies the
34 number of addresses in buffer. The symbolic representation of each ad‐
35 dress consists of the function name (if this can be determined), a
36 hexadecimal offset into the function, and the actual return address (in
37 hexadecimal). The address of the array of string pointers is returned
38 as the function result of backtrace_symbols(). This array is mal‐
39 loc(3)ed by backtrace_symbols(), and must be freed by the caller. (The
40 strings pointed to by the array of pointers need not and should not be
41 freed.)
42 backtrace_symbols_fd() takes the same buffer and size arguments as
44 backtrace_symbols(), but instead of returning an array of strings to
45 the caller, it writes the strings, one per line, to the file descriptor
46 fd. backtrace_symbols_fd() does not call malloc(3), and so can be em‐
47 ployed in situations where the latter function might fail, but see
48 NOTES.
49
51 backtrace() returns the number of addresses returned in buffer, which
52 is not greater than size. If the return value is less than size, then
53 the full backtrace was stored; if it is equal to size, then it may have
54 been truncated, in which case the addresses of the oldest stack frames
55 are not returned.
56 On success, backtrace_symbols() returns a pointer to the array mal‐
58 loc(3)ed by the call; on error, NULL is returned.
59
61 For an explanation of the terms used in this section, see at‐
62 tributes(7).
63 ┌────────────────────────────────────────────┬───────────────┬─────────┐
65 │Interface │ Attribute │ Value │
66 ├────────────────────────────────────────────┼───────────────┼─────────┤
67 │backtrace(), backtrace_symbols(), │ Thread safety │ MT-Safe │
68 │backtrace_symbols_fd() │ │ │
69 └────────────────────────────────────────────┴───────────────┴─────────┘
70
72 GNU.
73
75 glibc 2.1.
76
78 These functions make some assumptions about how a function's return
79 address is stored on the stack. Note the following:
80 • Omission of the frame pointers (as implied by any of gcc(1)'s
82 nonzero optimization levels) may cause these assumptions to be
83 violated.
84 • Inlined functions do not have stack frames.
86 • Tail-call optimization causes one stack frame to replace another.
88 • backtrace() and backtrace_symbols_fd() don't call malloc()
90 explicitly, but they are part of libgcc, which gets loaded
91 dynamically when first used. Dynamic loading usually triggers a
92 call to malloc(3). If you need certain calls to these two functions
93 to not allocate memory (in signal handlers, for example), you need
94 to make sure libgcc is loaded beforehand.
95 The symbol names may be unavailable without the use of special linker
97 options. For systems using the GNU linker, it is necessary to use the
98 -rdynamic linker option. Note that names of "static" functions are not
99 exposed, and won't be available in the backtrace.
100
102 The program below demonstrates the use of backtrace() and
103 backtrace_symbols(). The following shell session shows what we might
104 see when running the program:
105 $ cc -rdynamic prog.c -o prog
107 $ ./prog 3
108 backtrace() returned 8 addresses
109 ./prog(myfunc3+0x5c) [0x80487f0]
110 ./prog [0x8048871]
111 ./prog(myfunc+0x21) [0x8048894]
112 ./prog(myfunc+0x1a) [0x804888d]
113 ./prog(myfunc+0x1a) [0x804888d]
114 ./prog(main+0x65) [0x80488fb]
115 /lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c]
116 ./prog [0x8048711]
117 Program source
119 #include <execinfo.h>
121 #include <stdio.h>
122 #include <stdlib.h>
123 #include <unistd.h>
124 #define BT_BUF_SIZE 100
126 void
128 myfunc3(void)
129 {
130 int nptrs;
131 void *buffer[BT_BUF_SIZE];
132 char **strings;
133 nptrs = backtrace(buffer, BT_BUF_SIZE);
135 printf("backtrace() returned %d addresses\n", nptrs);
136 /* The call backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO)
138 would produce similar output to the following: */
139 strings = backtrace_symbols(buffer, nptrs);
141 if (strings == NULL) {
142 perror("backtrace_symbols");
143 exit(EXIT_FAILURE);
144 }
145 for (size_t j = 0; j < nptrs; j++)
147 printf("%s\n", strings[j]);
148 free(strings);
150 }
151 static void /* "static" means don't export the symbol... */
153 myfunc2(void)
154 {
155 myfunc3();
156 }
157 void
159 myfunc(int ncalls)
160 {
161 if (ncalls > 1)
162 myfunc(ncalls - 1);
163 else
164 myfunc2();
165 }
166 int
168 main(int argc, char *argv[])
169 {
170 if (argc != 2) {
171 fprintf(stderr, "%s num-calls\n", argv[0]);
172 exit(EXIT_FAILURE);
173 }
174 myfunc(atoi(argv[1]));
176 exit(EXIT_SUCCESS);
177 }
178
180 addr2line(1), gcc(1), gdb(1), ld(1), dlopen(3), malloc(3)
181Linux man-pages 6.05 2023-07-20 backtrace(3)