| @node Debugging Support |
| @c @node Debugging Support, , Cryptographic Functions, Top |
| @c %MENU% Functions to help debugging applications |
| @chapter Debugging support |
| |
| Applications are usually debugged using dedicated debugger programs. |
| But sometimes this is not possible and, in any case, it is useful to |
| provide the developer with as much information as possible at the time |
| the problems are experienced. For this reason a few functions are |
| provided which a program can use to help the developer more easily |
| locate the problem. |
| |
| |
| @menu |
| * Backtraces:: Obtaining and printing a back trace of the |
| current stack. |
| @end menu |
| |
| |
| @node Backtraces, , , Debugging Support |
| @section Backtraces |
| |
| @cindex backtrace |
| @cindex backtrace_symbols |
| @cindex backtrace_fd |
| A @dfn{backtrace} is a list of the function calls that are currently |
| active in a thread. The usual way to inspect a backtrace of a program |
| is to use an external debugger such as gdb. However, sometimes it is |
| useful to obtain a backtrace programmatically from within a program, |
| e.g., for the purposes of logging or diagnostics. |
| |
| The header file @file{execinfo.h} declares three functions that obtain |
| and manipulate backtraces of the current thread. |
| @pindex execinfo.h |
| |
| @comment execinfo.h |
| @comment GNU |
| @deftypefun int backtrace (void **@var{buffer}, int @var{size}) |
| The @code{backtrace} function obtains a backtrace for the current |
| thread, as a list of pointers, and places the information into |
| @var{buffer}. The argument @var{size} should be the number of |
| @w{@code{void *}} elements that will fit into @var{buffer}. The return |
| value is the actual number of entries of @var{buffer} that are obtained, |
| and is at most @var{size}. |
| |
| The pointers placed in @var{buffer} are actually return addresses |
| obtained by inspecting the stack, one return address per stack frame. |
| |
| Note that certain compiler optimizations may interfere with obtaining a |
| valid backtrace. Function inlining causes the inlined function to not |
| have a stack frame; tail call optimization replaces one stack frame with |
| another; frame pointer elimination will stop @code{backtrace} from |
| interpreting the stack contents correctly. |
| @end deftypefun |
| |
| @comment execinfo.h |
| @comment GNU |
| @deftypefun {char **} backtrace_symbols (void *const *@var{buffer}, int @var{size}) |
| The @code{backtrace_symbols} function translates the information |
| obtained from the @code{backtrace} function into an array of strings. |
| The argument @var{buffer} should be a pointer to an array of addresses |
| obtained via the @code{backtrace} function, and @var{size} is the number |
| of entries in that array (the return value of @code{backtrace}). |
| |
| The return value is a pointer to an array of strings, which has |
| @var{size} entries just like the array @var{buffer}. Each string |
| contains a printable representation of the corresponding element of |
| @var{buffer}. It includes the function name (if this can be |
| determined), an offset into the function, and the actual return address |
| (in hexadecimal). |
| |
| Currently, the function name and offset only be obtained on systems that |
| use the ELF binary format for programs and libraries. On other systems, |
| only the hexadecimal return address will be present. Also, you may need |
| to pass additional flags to the linker to make the function names |
| available to the program. (For example, on systems using GNU ld, you |
| must pass (@code{-rdynamic}.) |
| |
| The return value of @code{backtrace_symbols} is a pointer obtained via |
| the @code{malloc} function, and it is the responsibility of the caller |
| to @code{free} that pointer. Note that only the return value need be |
| freed, not the individual strings. |
| |
| The return value is @code{NULL} if sufficient memory for the strings |
| cannot be obtained. |
| @end deftypefun |
| |
| @comment execinfo.h |
| @comment GNU |
| @deftypefun void backtrace_symbols_fd (void *const *@var{buffer}, int @var{size}, int @var{fd}) |
| The @code{backtrace_symbols_fd} function performs the same translation |
| as the function @code{backtrace_symbols} function. Instead of returning |
| the strings to the caller, it writes the strings to the file descriptor |
| @var{fd}, one per line. It does not use the @code{malloc} function, and |
| can therefore be used in situations where that function might fail. |
| @end deftypefun |
| |
| The following program illustrates the use of these functions. Note that |
| the array to contain the return addresses returned by @code{backtrace} |
| is allocated on the stack. Therefore code like this can be used in |
| situations where the memory handling via @code{malloc} does not work |
| anymore (in which case the @code{backtrace_symbols} has to be replaced |
| by a @code{backtrace_symbols_fd} call as well). The number of return |
| addresses is normally not very large. Even complicated programs rather |
| seldom have a nesting level of more than, say, 50 and with 200 possible |
| entries probably all programs should be covered. |
| |
| @smallexample |
| @include execinfo.c.texi |
| @end smallexample |