BACKTRACE
NAME
backtrace, backtrace_symbols, backtrace_symbols_fd - support
for application self-debugging
SYNOPSIS
#include <execinfo.h>
int backtrace(void
I ** buffer ,
int
B size );
char **backtrace_symbols(void *const
I * buffer ,
int
B size );
void backtrace_symbols_fd(void *const
I * buffer ,
int
B size ,
int
B fd );
DESCRIPTION
R backtrace ()
returns a backtrace for the calling program,
in the array pointed to by
R buffer .
A backtrace is the series of currently active function calls for
the program.
Each item in the array pointed to by
buffer
is of type
void *, and is the return address from
the corresponding stack frame.
The
size
argument specifies the maximum number of addresses
that can be stored in
R buffer .
If the backtrace is larger than
R size ,
then the addresses corresponding to the
size
most recent function calls are returned;
to obtain the complete backtrace, make sure that
buffer
and
size
are large enough.
Given the set of addresses returned by
R backtrace ()
in
R buffer ,
R backtrace_symbols ()
translates the addresses into an array of strings that describe
the addresses symbolically.
The
size
argument specifies the number of addresses in
R buffer .
The symbolic representation of each address consists of the function name
(if this can be determined), a hexadecimal offset into the function,
and the actual return address (in hexadecimal).
The address of the array of string pointers is returned
as the function result of
R backtrace_symbols ().
This array is
malloc(3)ed
by
R backtrace_symbols (),
and must be freed by the caller.
(The strings pointed to by
R strings
need not and should not be freed.)
R backtrace_symbols_fd ()
takes the same
buffer
and
size
arguments as
R backtrace_symbols (),
but instead of returning an array of strings to the caller,
it writes the strings, one per line, to the file descriptor
R fd .
R backtrace_symbols ()
does not call
malloc(3),
and so can be employed in situations where the latter function might fail.
RETURN VALUE
R backtrace ()
returns the number of addresses returned in
R buffer ,
which is not greater than
R size .
If the return value is less than
R size ,
then the full backtrace was stored; if it is equal to
R size ,
then it may have been truncated, in which case the addresses of the
oldest stack frames are not returned.
On success,
R backtrace_symbols ()
returns a pointer to the array
malloc(3)ed
by the call;
on error, NULL is returned.
CONFORMING TO
These functions are GNU extensions.
NOTES
These functions make some assumptions about how a function's return
address is stored on the stack.
Note the following:
*
Omission of the frame pointers (as
implied by any of
gcc(1)'s
non-zero optimization levels) may cause these assumptions to be
violated.
*
Inlined functions do not have stack frames.
*
Tail-call optimization causes one stack frame to replace another.
The symbol names may be unavailable without the use of special linker
options.
For systems using the GNU linker, it is necessary to use the
-rdynamic
linker option.
Note that names of "static" functions are not exposed,
and won't be available in the backtrace.
EXAMPLE
The program below demonstrates the use of
R backtrace ()
and
R backtrace_symbols ().
The following shell session shows what we might see when running the
program:
$ cc -rdynamic prog.c -o prog
$ ./prog 3
backtrace() returned 8 addresses
./prog(myfunc3+0x5c) [0x80487f0]
./prog [0x8048871]
./prog(myfunc+0x21) [0x8048894]
./prog(myfunc+0x1a) [0x804888d]
./prog(myfunc+0x1a) [0x804888d]
./prog(main+0x65) [0x80488fb]
/lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c]
./prog [0x8048711]
#include <execinfo.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
void
myfunc3(void)
{
int j, nptrs;
#define SIZE 100
void *buffer[100];
char **strings;
nptrs = backtrace(buffer, SIZE);
printf("backtrace() returned %d addresses\n", nptrs);
/* The call backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO)
would produce similar output to the following: */
strings = backtrace_symbols(buffer, nptrs);
if (strings == NULL) {
perror("backtrace_symbols");
exit(EXIT_FAILURE);
}
for (j = 0; j < nptrs; j++)
printf("%s\n", strings[j]);
free(strings);
}
static void /* 'static' means don't export the symbol... */
myfunc2(void)
{
myfunc3();
}
void
myfunc(int ncalls)
{
if (ncalls > 1)
myfunc(ncalls - 1);
else
myfunc2();
}
int
main(int argc, char *argv[])
{
if (argc != 2) {
fprintf(stderr, "%s num-calls\n", argv[0]);
exit(EXIT_FAILURE);
}
myfunc(atoi(argv[1]));
exit(EXIT_SUCCESS);
}
SEE ALSO
