Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
BACKTRACE(3)		     Library Functions Manual		    BACKTRACE(3)

NAME
     backtrace -- fill in the backtrace of the currently executing thread

LIBRARY
     libexecinfo

SYNOPSIS
     #include <execinfo.h>

     size_t
     backtrace(void **addrlist, size_t len);

     char **
     backtrace_symbols(void * const *addrlist, size_t len);

     int
     backtrace_symbols_fd(void * const *addrlist, size_t len, int fd);

     char **
     backtrace_symbols_fmt(void * const *addrlist, size_t len, const char *fmt);

     int
     backtrace_symbols_fd_fmt(void * const *addrlist, size_t len, int fd,
	 const char *fmt);

DESCRIPTION
     The  backtrace() function places into the array pointed by addrlist the ar-
     ray of the values of the program counter for each frame called  up  to  len
     frames.   The  number  of frames found (which can be fewer than len) is re-
     turned.

     The backtrace_symbols_fmt() function takes an array  of  previously  filled
     addresses	from  backtrace()  in  addrlist of len elements, and uses fmt to
     format them.  The formatting characters available are:

	   a  The numeric address of each element as would be printed using %p.

	   n  The name of the nearest function symbol (smaller than the  address
	      element)	as determined by dladdr(3) if the symbol was dynamic, or
	      looked up in the executable if static and the /proc filesystem  is
	      available to determine the executable path.

	   d  The  difference  of  the	symbol	address  and the address element
	      printed using 0x%tx.

	   D  The difference of the  symbol  address  and  the	address  element
	      printed using +0x%tx if non-zero, or nothing if zero.

	   f  The filename of the symbol as determined by dladdr(3).

     The  array  of formatted strings is returned as a contiguous memory address
     which can be freed by a single free(3).

     The backtrace_symbols() function is equivalent  of  calling  backtrace_sym-
     bols_fmt() with a format argument of %a <%n%D> at %f

     The  backtrace_symbols_fd()  and  backtrace_symbols_fd_fmt() are similar to
     the non _fd named functions, only instead of returning an array or strings,
     they print a new-line separated array of strings in fd,  and  return  0  on
     success and -1 on failure.

RETURN VALUES
     The backtrace() function returns the number of elements that were filled in
     the  backtrace.  The backtrace_symbols() and backtrace_symbols_fmt() return
     a string array on success, and NULL on failure, setting errno.   Diagnostic
     output may also be produced by the ELF symbol lookup functions.

SEE ALSO
     dladdr(3), elf(3)

HISTORY
     The  backtrace()  library	of  functions  first  appeared in NetBSD 7.0 and
     FreeBSD 10.0.

BUGS
     1.   Errors should not be printed but communicated to  the  caller  differ-
	  ently.

     2.   Because  these functions use elf(3) this is a separate library instead
	  of being part of libc/libutil so that no library dependencies are  in-
	  troduced.

     3.   The  Linux  versions of the functions (there are no _fmt variants) use
	  int instead of size_t arguments.

FreeBSD ports 15.1		December 12, 2015		    BACKTRACE(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=backtrace&sektion=3&manpath=FreeBSD+15.1-RELEASE+and+Ports>

home | help