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 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: 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