backtrace, backtrace_symbols, backtrace_symbols_fd

Name

backtrace, backtrace_symbols, backtrace_symbols_fd -- runtime stack back tracing

Synopsis

#include <execinfo.h>

int backtrace(void **array, int size);

char **backtrace_symbols(void *const *array, int size);

void backtrace_symbols_fd(void *const *array, int size, int fd);

Description

backtrace() obtains a backtrace for the current thread as a list of pointers filled in to array. The size parameter describes the number of elements that will fit into array, backtrace() will truncate the list if necessary. A backtrace is a list of currently active function calls in a thread; each function call allocates a new stack frame and backtrace() obtains the return address from each stack frame.

backtrace_symbols() translates the information obtained from backtrace() into an array of strings. array is a pointer to an array of addresses as obtained from backtrace(). size is the number of entries in array, and should be the return value of the call to backtrace(). The strings contain the function name if it can be determined, a hedxadecimal offset into the function, and the actual return address in hexadecimal. Note that the pointer returned by backtrace_symbols() is obtained by an internal call to malloc() and should be freed when no longer needed.

backtrace_symbols_fd() performs the same transformation as backtrace_symbols() given the same argument pair array, size, but writes the strings to the file descriptor contained in fd. This avoids the allocation of string space.

Return Value

backtrace() returns the number of entries placed into array, no more than size. If the value is less than size, the full backtrace was returned; else it may have been truncated.

On success, backtrace_symbols() returns a pointer to an array of strings, which will have size entries. On error, NULL is returned.

Errors

No errors are defined for these functions. If backtrace_symbols_fd() fails, it will be due to a failure in the call to malloc(), and errno will be set accordingly.

Notes

The ability to obtain useful backtrace information, in particular function names, is dependent on a number of factors at the time of program construction, such as compiler optimization options. Even if the program itself is constructed so as to make symbols visible, the call trace may descend into system libraries which have not been so constructed.

Inlined functions do not have stack frames, and functions declared as static are not exposed and so will not be available in the backtrace.

See Also

malloc()