manual/debug.texi

   1 @node Debugging Support
   2 @c @node Debugging Support, POSIX Threads, 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 programmatically 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 @safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{} @ascuheap{} @ascudlopen{} @ascuplugin{} @asulock{}}@acunsafe{@acuinit{} @acsmem{} @aculock{} @acsfd{}}}
  40 @c The generic implementation just does pointer chasing within the local
  41 @c stack, without any guarantees that this will handle signal frames
  42 @c correctly, so it's AS-Unsafe to begin with.  However, most (all?)
  43 @c arches defer to libgcc_s's _Unwind_* implementation, dlopening
  44 @c libgcc_s.so to that end except in a static version of libc.
  45 @c libgcc_s's implementation may in turn defer to libunwind.  We can't
  46 @c assume those implementations are AS- or AC-safe, but even if we
  47 @c could, our own initialization path isn't, and libgcc's implementation
  48 @c calls malloc and performs internal locking, so...
  49 The @code{backtrace} function obtains a backtrace for the current
  50 thread, as a list of pointers, and places the information into
  51 @var{buffer}.  The argument @var{size} should be the number of
  52 @w{@code{void *}} elements that will fit into @var{buffer}.  The return
  53 value is the actual number of entries of @var{buffer} that are obtained,
  54 and is at most @var{size}.
  55
  56 The pointers placed in @var{buffer} are actually return addresses
  57 obtained by inspecting the stack, one return address per stack frame.
  58
  59 Note that certain compiler optimizations may interfere with obtaining a
  60 valid backtrace.  Function inlining causes the inlined function to not
  61 have a stack frame; tail call optimization replaces one stack frame with
  62 another; frame pointer elimination will stop @code{backtrace} from
  63 interpreting the stack contents correctly.
  64 @end deftypefun
  65
  66 @comment execinfo.h
  67 @comment GNU
  68 @deftypefun {char **} backtrace_symbols (void *const *@var{buffer}, int @var{size})
  69 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @aculock{}}}
  70 @c Collects info returned by _dl_addr in an auto array, allocates memory
  71 @c for the whole return buffer with malloc then sprintfs into it storing
  72 @c pointers to the strings into the array entries in the buffer.
  73 @c _dl_addr takes the recursive dl_load_lock then calls
  74 @c _dl_find_dso_for_object and determine_info.
  75 @c _dl_find_dso_for_object calls _dl-addr_inside_object.
  76 @c All of them are safe as long as the lock is held.
  77 @c @asucorrupt?  It doesn't look like the dynamic loader's data
  78 @c structures could be in an inconsistent state that would cause
  79 @c malfunction here.
  80 The @code{backtrace_symbols} function translates the information
  81 obtained from the @code{backtrace} function into an array of strings.
  82 The argument @var{buffer} should be a pointer to an array of addresses
  83 obtained via the @code{backtrace} function, and @var{size} is the number
  84 of entries in that array (the return value of @code{backtrace}).
  85
  86 The return value is a pointer to an array of strings, which has
  87 @var{size} entries just like the array @var{buffer}.  Each string
  88 contains a printable representation of the corresponding element of
  89 @var{buffer}.  It includes the function name (if this can be
  90 determined), an offset into the function, and the actual return address
  91 (in hexadecimal).
  92
  93 Currently, the function name and offset only be obtained on systems that
  94 use the ELF binary format for programs and libraries.  On other systems,
  95 only the hexadecimal return address will be present.  Also, you may need
  96 to pass additional flags to the linker to make the function names
  97 available to the program.  (For example, on systems using GNU ld, you
  98 must pass (@code{-rdynamic}.)
  99
 100 The return value of @code{backtrace_symbols} is a pointer obtained via
 101 the @code{malloc} function, and it is the responsibility of the caller
 102 to @code{free} that pointer.  Note that only the return value need be
 103 freed, not the individual strings.
 104
 105 The return value is @code{NULL} if sufficient memory for the strings
 106 cannot be obtained.
 107 @end deftypefun
 108
 109 @comment execinfo.h
 110 @comment GNU
 111 @deftypefun void backtrace_symbols_fd (void *const *@var{buffer}, int @var{size}, int @var{fd})
 112 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
 113 @c Single loop of _dl_addr over addresses, collecting info into an iovec
 114 @c written out with a writev call per iteration.  Addresses and offsets
 115 @c are converted to hex in auto buffers, so the only potential issue
 116 @c here is leaking the dl lock in case of cancellation.
 117 The @code{backtrace_symbols_fd} function performs the same translation
 118 as the function @code{backtrace_symbols} function.  Instead of returning
 119 the strings to the caller, it writes the strings to the file descriptor
 120 @var{fd}, one per line.  It does not use the @code{malloc} function, and
 121 can therefore be used in situations where that function might fail.
 122 @end deftypefun
 123
 124 The following program illustrates the use of these functions.  Note that
 125 the array to contain the return addresses returned by @code{backtrace}
 126 is allocated on the stack.  Therefore code like this can be used in
 127 situations where the memory handling via @code{malloc} does not work
 128 anymore (in which case the @code{backtrace_symbols} has to be replaced
 129 by a @code{backtrace_symbols_fd} call as well).  The number of return
 130 addresses is normally not very large.  Even complicated programs rather
 131 seldom have a nesting level of more than, say, 50 and with 200 possible
 132 entries probably all programs should be covered.
 133
 134 @smallexample
 135 @include execinfo.c.texi
 136 @end smallexample