GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  BACKTRACE (3)

NAME

backtrace - fill in the backtrace of the currently executing thread

CONTENTS

Library
Synopsis
Description
Return Values
See Also
History
Bugs

LIBRARY


.Lb libexecinfo

SYNOPSIS


.In 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_fmt_fd void * const *addrlist size_t len const char *fmt int fd

DESCRIPTION

The backtrace function places into the array pointed by addrlist the array 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 returned.

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 addresss 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_symbols_fmt with a format argument of %a <%n%D> at %f

The backtrace_symbols_fd and backtrace_symbols_fmt_fd 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
.Nx 7.0 and
.Fx 10.0 .

BUGS

  1. Errors should not be printed but communicated to the caller differently.
  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 introduced.
  3. The Linux versions of the functions (there are no _fmt variants) use int instead of size_t arguments.
Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.