Re: backtrace_symbols function buggy?

[suckfish at ihug dot co dot nz]

Ulrich,

>> Below, I'd expect to see the functions print_bt, foo2 and main in the
>> printed backtrace; instead, backtrace_symbols is printed three times.
>> 
>
>Add -rdynamic to the compiler line.

Thanks for the hint; it solved my problem.

There is currently no documentation for the functions in execinfo.h, so I
wrote some.  The enclosed diff contains files manual/execinfo.texi, and
manual/examples/execinfo.c.

I have not modified other rest of the manual to include these, because I
don't know how to or where to put them.  If someone gives me a hint then
I'll do so and resubmit the patch; alternatively someone else could do it.

Ralph.

--- /dev/null	Thu Jan  1 12:00:00 1970
+++ manual/execinfo.texi	Sun Jan 14 11:14:09 2001
@@ -0,0 +1,76 @@
+@node Backtraces, Top, Top, Top
+@c %MENU% Obtaining and printing a back trace of the current stack.
+@chapter 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 size of
+@var{buffer}.  The return value is the 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
+
+@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 length
+of that array.
+
+The return value is a pointer to an array of strings, which has length
+@var{size}.  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 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
+
+@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
+
+@smallexample
+@include execinfo.c.texi
+@end smallexample
--- /dev/null	Thu Jan  1 12:00:00 1970
+++ manual/examples/execinfo.c	Sun Jan 14 11:02:47 2001
@@ -0,0 +1,39 @@
+#include <execinfo.h>
+#include <stdio.h>
+#include <malloc.h>
+
+/* Obtain a backtrace and print it to @code{stdout}. */
+
+void
+print_trace (void)
+{
+  void * array[10];
+  int size;
+  char ** strings;
+  int i;
+
+  size = backtrace (array, 10);
+  strings = backtrace_symbols (array, size);
+
+  printf ("Obtained %i stack frames.\n", size);
+
+  for (i = 0; i < size; i++)
+     printf ("%s\n", strings[i]);
+
+  free (strings);
+}
+
+/* A dummy function to make the backtrace more interesting. */
+
+void
+dummy_function (void)
+{
+  print_trace();
+}
+
+int
+main (void)
+{
+  dummy_function();
+  return 0;
+}