]>
Commit | Line | Data |
---|---|---|
2244ddf2 | 1 | @node Debugging Support |
9d0a979e | 2 | @c @node Debugging Support, Threads, Cryptographic Functions, Top |
5656e294 | 3 | @c %MENU% Functions to help debugging applications |
2244ddf2 UD |
4 | @chapter Debugging support |
5 | ||
f6b02eff UD |
6 | Applications are usually debugged using dedicated debugger programs. |
7 | But sometimes this is not possible and, in any case, it is useful to | |
3ba06713 | 8 | provide the developer with as much information as possible at the time |
f6b02eff UD |
9 | the problems are experienced. For this reason a few functions are |
10 | provided which a program can use to help the developer more easily | |
11 | locate the problem. | |
2244ddf2 UD |
12 | |
13 | ||
14 | @menu | |
15 | * Backtraces:: Obtaining and printing a back trace of the | |
16 | current stack. | |
17 | @end menu | |
18 | ||
19 | ||
20 | @node Backtraces, , , Debugging Support | |
21 | @section Backtraces | |
22 | ||
23 | @cindex backtrace | |
24 | @cindex backtrace_symbols | |
25 | @cindex backtrace_fd | |
26 | A @dfn{backtrace} is a list of the function calls that are currently | |
27 | active in a thread. The usual way to inspect a backtrace of a program | |
28 | is to use an external debugger such as gdb. However, sometimes it is | |
3ba06713 | 29 | useful to obtain a backtrace programmatically from within a program, |
2244ddf2 UD |
30 | e.g., for the purposes of logging or diagnostics. |
31 | ||
32 | The header file @file{execinfo.h} declares three functions that obtain | |
33 | and manipulate backtraces of the current thread. | |
34 | @pindex execinfo.h | |
35 | ||
2244ddf2 | 36 | @deftypefun int backtrace (void **@var{buffer}, int @var{size}) |
d08a7e4c | 37 | @standards{GNU, execinfo.h} |
0037bb60 AO |
38 | @safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{} @ascuheap{} @ascudlopen{} @ascuplugin{} @asulock{}}@acunsafe{@acuinit{} @acsmem{} @aculock{} @acsfd{}}} |
39 | @c The generic implementation just does pointer chasing within the local | |
40 | @c stack, without any guarantees that this will handle signal frames | |
41 | @c correctly, so it's AS-Unsafe to begin with. However, most (all?) | |
42 | @c arches defer to libgcc_s's _Unwind_* implementation, dlopening | |
43 | @c libgcc_s.so to that end except in a static version of libc. | |
44 | @c libgcc_s's implementation may in turn defer to libunwind. We can't | |
45 | @c assume those implementations are AS- or AC-safe, but even if we | |
46 | @c could, our own initialization path isn't, and libgcc's implementation | |
47 | @c calls malloc and performs internal locking, so... | |
2244ddf2 UD |
48 | The @code{backtrace} function obtains a backtrace for the current |
49 | thread, as a list of pointers, and places the information into | |
50 | @var{buffer}. The argument @var{size} should be the number of | |
f6b02eff UD |
51 | @w{@code{void *}} elements that will fit into @var{buffer}. The return |
52 | value is the actual number of entries of @var{buffer} that are obtained, | |
53 | and is at most @var{size}. | |
2244ddf2 UD |
54 | |
55 | The pointers placed in @var{buffer} are actually return addresses | |
56 | obtained by inspecting the stack, one return address per stack frame. | |
57 | ||
0bc93a2f | 58 | Note that certain compiler optimizations may interfere with obtaining a |
2244ddf2 | 59 | valid backtrace. Function inlining causes the inlined function to not |
0bc93a2f | 60 | have a stack frame; tail call optimization replaces one stack frame with |
2244ddf2 UD |
61 | another; frame pointer elimination will stop @code{backtrace} from |
62 | interpreting the stack contents correctly. | |
63 | @end deftypefun | |
64 | ||
2244ddf2 | 65 | @deftypefun {char **} backtrace_symbols (void *const *@var{buffer}, int @var{size}) |
d08a7e4c | 66 | @standards{GNU, execinfo.h} |
0037bb60 AO |
67 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @aculock{}}} |
68 | @c Collects info returned by _dl_addr in an auto array, allocates memory | |
69 | @c for the whole return buffer with malloc then sprintfs into it storing | |
70 | @c pointers to the strings into the array entries in the buffer. | |
71 | @c _dl_addr takes the recursive dl_load_lock then calls | |
72 | @c _dl_find_dso_for_object and determine_info. | |
73 | @c _dl_find_dso_for_object calls _dl-addr_inside_object. | |
74 | @c All of them are safe as long as the lock is held. | |
75 | @c @asucorrupt? It doesn't look like the dynamic loader's data | |
76 | @c structures could be in an inconsistent state that would cause | |
77 | @c malfunction here. | |
2244ddf2 UD |
78 | The @code{backtrace_symbols} function translates the information |
79 | obtained from the @code{backtrace} function into an array of strings. | |
80 | The argument @var{buffer} should be a pointer to an array of addresses | |
81 | obtained via the @code{backtrace} function, and @var{size} is the number | |
82 | of entries in that array (the return value of @code{backtrace}). | |
83 | ||
84 | The return value is a pointer to an array of strings, which has | |
85 | @var{size} entries just like the array @var{buffer}. Each string | |
86 | contains a printable representation of the corresponding element of | |
87 | @var{buffer}. It includes the function name (if this can be | |
88 | determined), an offset into the function, and the actual return address | |
f6b02eff | 89 | (in hexadecimal). |
2244ddf2 | 90 | |
db5e4e88 | 91 | Currently, the function name and offset can only be obtained on systems that |
f6b02eff UD |
92 | use the ELF binary format for programs and libraries. On other systems, |
93 | only the hexadecimal return address will be present. Also, you may need | |
94 | to pass additional flags to the linker to make the function names | |
95 | available to the program. (For example, on systems using GNU ld, you | |
db5e4e88 | 96 | must pass @code{-rdynamic}.) |
2244ddf2 UD |
97 | |
98 | The return value of @code{backtrace_symbols} is a pointer obtained via | |
99 | the @code{malloc} function, and it is the responsibility of the caller | |
100 | to @code{free} that pointer. Note that only the return value need be | |
f6b02eff | 101 | freed, not the individual strings. |
2244ddf2 UD |
102 | |
103 | The return value is @code{NULL} if sufficient memory for the strings | |
104 | cannot be obtained. | |
105 | @end deftypefun | |
106 | ||
2244ddf2 | 107 | @deftypefun void backtrace_symbols_fd (void *const *@var{buffer}, int @var{size}, int @var{fd}) |
d08a7e4c | 108 | @standards{GNU, execinfo.h} |
0037bb60 AO |
109 | @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} |
110 | @c Single loop of _dl_addr over addresses, collecting info into an iovec | |
111 | @c written out with a writev call per iteration. Addresses and offsets | |
112 | @c are converted to hex in auto buffers, so the only potential issue | |
113 | @c here is leaking the dl lock in case of cancellation. | |
2244ddf2 UD |
114 | The @code{backtrace_symbols_fd} function performs the same translation |
115 | as the function @code{backtrace_symbols} function. Instead of returning | |
116 | the strings to the caller, it writes the strings to the file descriptor | |
117 | @var{fd}, one per line. It does not use the @code{malloc} function, and | |
118 | can therefore be used in situations where that function might fail. | |
119 | @end deftypefun | |
120 | ||
121 | The following program illustrates the use of these functions. Note that | |
122 | the array to contain the return addresses returned by @code{backtrace} | |
123 | is allocated on the stack. Therefore code like this can be used in | |
124 | situations where the memory handling via @code{malloc} does not work | |
125 | anymore (in which case the @code{backtrace_symbols} has to be replaced | |
126 | by a @code{backtrace_symbols_fd} call as well). The number of return | |
127 | addresses is normally not very large. Even complicated programs rather | |
128 | seldom have a nesting level of more than, say, 50 and with 200 possible | |
129 | entries probably all programs should be covered. | |
130 | ||
131 | @smallexample | |
132 | @include execinfo.c.texi | |
133 | @end smallexample |