* manual/arpg.texi: Spelling, misc fixes.
[kopensolaris-gnu/glibc.git] / manual / debug.texi
1 @node Debugging Support
2 @c @node Debugging Support, , Cryptographic Functions, Top
3 @c %MENU% Functions to help debugging applications.
4 @chapter Debugging support
5
6 Applications are usually debugged using dedicated debugger programs.
7 But sometimes this is not possible and, in any case, it is useful to
8 provide the developer with as much information as possible at the time 
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.
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
29 useful to obtain a backtrace programatically from within a program,
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
36 @comment execinfo.h
37 @comment GNU
38 @deftypefun int backtrace (void **@var{buffer}, int @var{size})
39 The @code{backtrace} function obtains a backtrace for the current
40 thread, as a list of pointers, and places the information into
41 @var{buffer}.  The argument @var{size} should be the number of
42 @w{@code{void *}} elements that will fit into @var{buffer}.  The return
43 value is the actual number of entries of @var{buffer} that are obtained,
44 and is at most @var{size}.
45
46 The pointers placed in @var{buffer} are actually return addresses
47 obtained by inspecting the stack, one return address per stack frame.
48
49 Note that certain compiler optimizations may interfere with obtaining a
50 valid backtrace.  Function inlining causes the inlined function to not
51 have a stack frame; tail call optimization replaces one stack frame with
52 another; frame pointer elimination will stop @code{backtrace} from
53 interpreting the stack contents correctly.
54 @end deftypefun
55
56 @comment execinfo.h
57 @comment GNU
58 @deftypefun {char **} backtrace_symbols (void *const *@var{buffer}, int @var{size})
59 The @code{backtrace_symbols} function translates the information
60 obtained from the @code{backtrace} function into an array of strings.
61 The argument @var{buffer} should be a pointer to an array of addresses
62 obtained via the @code{backtrace} function, and @var{size} is the number
63 of entries in that array (the return value of @code{backtrace}).
64
65 The return value is a pointer to an array of strings, which has
66 @var{size} entries just like the array @var{buffer}.  Each string
67 contains a printable representation of the corresponding element of
68 @var{buffer}.  It includes the function name (if this can be
69 determined), an offset into the function, and the actual return address
70 (in hexadecimal).
71
72 Currently, the function name and offset only be obtained on systems that
73 use the ELF binary format for programs and libraries.  On other systems,
74 only the hexadecimal return address will be present.  Also, you may need
75 to pass additional flags to the linker to make the function names
76 available to the program.  (For example, on systems using GNU ld, you
77 must pass (@code{-rdynamic}.)
78
79 The return value of @code{backtrace_symbols} is a pointer obtained via
80 the @code{malloc} function, and it is the responsibility of the caller
81 to @code{free} that pointer.  Note that only the return value need be
82 freed, not the individual strings.
83
84 The return value is @code{NULL} if sufficient memory for the strings
85 cannot be obtained.
86 @end deftypefun
87
88 @comment execinfo.h
89 @comment GNU
90 @deftypefun void backtrace_symbols_fd (void *const *@var{buffer}, int @var{size}, int @var{fd})
91 The @code{backtrace_symbols_fd} function performs the same translation
92 as the function @code{backtrace_symbols} function.  Instead of returning
93 the strings to the caller, it writes the strings to the file descriptor
94 @var{fd}, one per line.  It does not use the @code{malloc} function, and
95 can therefore be used in situations where that function might fail.
96 @end deftypefun
97
98 The following program illustrates the use of these functions.  Note that
99 the array to contain the return addresses returned by @code{backtrace}
100 is allocated on the stack.  Therefore code like this can be used in
101 situations where the memory handling via @code{malloc} does not work
102 anymore (in which case the @code{backtrace_symbols} has to be replaced
103 by a @code{backtrace_symbols_fd} call as well).  The number of return
104 addresses is normally not very large.  Even complicated programs rather
105 seldom have a nesting level of more than, say, 50 and with 200 possible
106 entries probably all programs should be covered.
107
108 @smallexample
109 @include execinfo.c.texi
110 @end smallexample