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 often get debugged using dedicated debugger programs.  But
   7 sometimes this is not possible and it is in any case useful to provide
   8 the developer at the time the problems are experienced with as much
   9 information as possible.  For this reason there exist a few functions
  10 which a program can use to help the developer more easily locate the
  11 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 fitting into @var{buffer}.  The return value
  43 is the actual number of entries of @var{buffer} that are obtained, and
  44 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 optimisations may interfere with obtaining a
  50 valid backtrace.  Function inlining causes the inlined function to not
  51 have a stack frame; tail call optimisation 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 hexidecimal).
  71
  72 Currently, the function name and offset can currently only be obtained
  73 on systems that use the ELF binary format for programs and libraries.
  74 On other systems, only the hexidecimal return address will be present.
  75 Also, you may need to pass additional flags to the linker
  76 (@code{-rdynamic} on systems using GNU ld) to make the function names
  77 available to the program.
  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, but 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