From 2244ddf2bfc9a524d8a617881c78ecb1d85f3544 Mon Sep 17 00:00:00 2001 From: Ulrich Drepper Date: Wed, 17 Jan 2001 16:54:30 +0000 Subject: Update. 2001-01-17 Ulrich Drepper * manual/Makefile (chapters): Add debug. * manual/debug.texi: New file. * manual/examples/execinfo.c: New file. Patch by suckfish@ihug.co.nz. --- manual/debug.texi | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 manual/debug.texi (limited to 'manual/debug.texi') diff --git a/manual/debug.texi b/manual/debug.texi new file mode 100644 index 0000000000..0fe1e3e4e7 --- /dev/null +++ b/manual/debug.texi @@ -0,0 +1,110 @@ +@node Debugging Support +@c @node Debugging Support, , Cryptographic Functions, Top +@c %MENU% Functions to help debugging applications. +@chapter Debugging support + +Applications often get debugged using dedicated debugger programs. But +sometimes this is not possible and it is in any case useful to provide +the developer at the time the problems are experienced with as much +information as possible. For this reason there exist a few functions +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 programatically 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 fitting 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 optimisations may interfere with obtaining a +valid backtrace. Function inlining causes the inlined function to not +have a stack frame; tail call optimisation 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 hexidecimal). + +Currently, the function name and offset can currently only be obtained +on systems that use the ELF binary format for programs and libraries. +On other systems, only the hexidecimal return address will be present. +Also, you may need to pass additional flags to the linker +(@code{-rdynamic} on systems using GNU ld) to make the function names +available to the program. + +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, but 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 -- cgit v1.2.3