backtrace_symbols function buggy?
suckfish@ihug.co.nz
suckfish@ihug.co.nz
Sat Jan 13 14:28:00 GMT 2001
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;
+}
More information about the Libc-alpha
mailing list