1@node Debugging Support
2@c @node Debugging Support, Threads, Cryptographic Functions, Top
3@c %MENU% Functions to help debugging applications
4@chapter Debugging support
5
6Applications are usually debugged using dedicated debugger programs.
7But sometimes this is not possible and, in any case, it is useful to
8provide the developer with as much information as possible at the time
9the problems are experienced.  For this reason a few functions are
10provided which a program can use to help the developer more easily
11locate the problem.
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
26A @dfn{backtrace} is a list of the function calls that are currently
27active in a thread.  The usual way to inspect a backtrace of a program
28is to use an external debugger such as gdb.  However, sometimes it is
29useful to obtain a backtrace programmatically from within a program,
30e.g., for the purposes of logging or diagnostics.
31
32The header file @file{execinfo.h} declares three functions that obtain
33and manipulate backtraces of the current thread.
34@pindex execinfo.h
35
36@deftypefun int backtrace (void **@var{buffer}, int @var{size})
37@standards{GNU, execinfo.h}
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...
48The @code{backtrace} function obtains a backtrace for the current
49thread, as a list of pointers, and places the information into
50@var{buffer}.  The argument @var{size} should be the number of
51@w{@code{void *}} elements that will fit into @var{buffer}.  The return
52value is the actual number of entries of @var{buffer} that are obtained,
53and is at most @var{size}.
54
55The pointers placed in @var{buffer} are actually return addresses
56obtained by inspecting the stack, one return address per stack frame.
57
58Note that certain compiler optimizations may interfere with obtaining a
59valid backtrace.  Function inlining causes the inlined function to not
60have a stack frame; tail call optimization replaces one stack frame with
61another; frame pointer elimination will stop @code{backtrace} from
62interpreting the stack contents correctly.
63@end deftypefun
64
65@deftypefun {char **} backtrace_symbols (void *const *@var{buffer}, int @var{size})
66@standards{GNU, execinfo.h}
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.
78The @code{backtrace_symbols} function translates the information
79obtained from the @code{backtrace} function into an array of strings.
80The argument @var{buffer} should be a pointer to an array of addresses
81obtained via the @code{backtrace} function, and @var{size} is the number
82of entries in that array (the return value of @code{backtrace}).
83
84The return value is a pointer to an array of strings, which has
85@var{size} entries just like the array @var{buffer}.  Each string
86contains a printable representation of the corresponding element of
87@var{buffer}.  It includes the function name (if this can be
88determined), an offset into the function, and the actual return address
89(in hexadecimal).
90
91Currently, the function name and offset can only be obtained on systems that
92use the ELF binary format for programs and libraries.  On other systems,
93only the hexadecimal return address will be present.  Also, you may need
94to pass additional flags to the linker to make the function names
95available to the program.  (For example, on systems using GNU ld, you
96must pass @code{-rdynamic}.)
97
98The return value of @code{backtrace_symbols} is a pointer obtained via
99the @code{malloc} function, and it is the responsibility of the caller
100to @code{free} that pointer.  Note that only the return value need be
101freed, not the individual strings.
102
103The return value is @code{NULL} if sufficient memory for the strings
104cannot be obtained.
105@end deftypefun
106
107@deftypefun void backtrace_symbols_fd (void *const *@var{buffer}, int @var{size}, int @var{fd})
108@standards{GNU, execinfo.h}
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.
114The @code{backtrace_symbols_fd} function performs the same translation
115as the function @code{backtrace_symbols} function.  Instead of returning
116the 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
118can therefore be used in situations where that function might fail.
119@end deftypefun
120
121The following program illustrates the use of these functions.  Note that
122the array to contain the return addresses returned by @code{backtrace}
123is allocated on the stack.  Therefore code like this can be used in
124situations where the memory handling via @code{malloc} does not work
125anymore (in which case the @code{backtrace_symbols} has to be replaced
126by a @code{backtrace_symbols_fd} call as well).  The number of return
127addresses is normally not very large.  Even complicated programs rather
128seldom have a nesting level of more than, say, 50 and with 200 possible
129entries probably all programs should be covered.
130
131@smallexample
132@include execinfo.c.texi
133@end smallexample
134