BACKTRACE(3)

NAME
backtrace - glibc and libexecinfo backtrace compatible API

SYNOPSIS
#include <execinfo.h>
int
backtrace(void **buffer, int depth);
char **
backtrace_symbols(void *const *buffer, int depth);
void
backtrace_symbols_fd(void *const *buffer, int depth, int fd);

DESCRIPTION
backtrace() fills out the pointer array provided in buffer up to depth elements with the stack trace pointers. It returns the stack depth on success or -1 on failure.

backtrace_symbols() returns an array of strings. Each string represents one buffer element. The depth parameter governs the buffer length. On failure the function returns NULL. The caller is responsible for freeing the returned pointer.

backtrace_symbols_fd() creates an identical trace as backtrace_symbols() however it writes it to file fd. The caller is responsible for opening the file with the appropriate flags.

EXAMPLES
The following code fragment illustrates the use of the backtrace functionality:

    void
    print_backtrace(void)
    {
    	void			*bt[BT_MAX_DEPTH];
    	char			**strings;
    	int			i, d;
            d = backtrace(bt, BT_MAX_DEPTH);
    	if (d == -1)
    		errx(1, "backtrace");
    	strings = backtrace_symbols(bt, d);
    	if (strings == NULL)
    		errx(1, "backtrace_symbols");
    	for (i = 0; i < d; i++)
    		printf("%s, strings[i]);
    	free(strings);
    }

SEE ALSO
gdb(1) gcc(1)

HISTORY
-nosplit backtrace was written by Marco Peereboom <marco@conformalcom>

BUGS
As typical with GNU software the interface is clumsy and error prone. While writing a more sophisticated backtracing mechanism it was obvious that the GNU functionality could be trivially emulated.

Due to a bug in gcc one has to compile applications with the following flags -Wl,--export-dynamic in order to get human readable function names.