SYNOPSIS<\/a>
DESCRIPTION<\/a>
RETURN VALUE<\/a>
VERSIONS<\/a>
ATTRIBUTES<\/a>
CONFORMING TO<\/a>
NOTES<\/a>
EXAMPLES<\/a>
SEE ALSO<\/a>
COLOPHON<\/a> <\/p>\n
\n
NAME <\/a> <\/h2>\nbacktrace, backtrace_symbols, backtrace_symbols_fd \u2212 support for application self-debugging<\/p>\n
SYNOPSIS <\/a> <\/h2>\n#include <\/b><\/p>\nint backtrace(void **<\/b>buffer<\/i>, int<\/b> size<\/i>);<\/b><\/p>\n
char **backtrace_symbols(void *const *<\/b>buffer<\/i>, int<\/b> size<\/i>);<\/b><\/p>\n
void backtrace_symbols_fd(void *const *<\/b>buffer<\/i>, int<\/b> size<\/i>, int<\/b> fd<\/i>);<\/b><\/p>\nDESCRIPTION <\/a> <\/h2>\nbacktrace<\/b>() returns a backtrace for the calling program, in the array pointed to by buffer<\/i>. A backtrace is the series of currently active function calls for the program. Each item in the array pointed to by buffer<\/i> is of type void\u00a0*<\/i>, and is the return address from the corresponding stack frame. The size<\/i> argument specifies the maximum number of addresses that can be stored in buffer<\/i>. If the backtrace is larger than size<\/i>, then the addresses corresponding to the size<\/i> most recent function calls are returned; to obtain the complete backtrace, make sure that buffer<\/i> and size<\/i> are large enough.<\/p>\n
Given the set of addresses returned by backtrace<\/b>() in buffer<\/i>, backtrace_symbols<\/b>() translates the addresses into an array of strings that describe the addresses symbolically. The size<\/i> argument specifies the number of addresses in buffer<\/i>. 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 backtrace_symbols<\/b>(). This array is malloc<\/b>(3)ed by backtrace_symbols<\/b>(), and must be freed by the caller. (The strings pointed to by the array of pointers need not and should not be freed.)<\/p>\n
backtrace_symbols_fd<\/b>() takes the same buffer<\/i> and size<\/i> arguments as backtrace_symbols<\/b>(), but instead of returning an array of strings to the caller, it writes the strings, one per line, to the file descriptor fd<\/i>. backtrace_symbols_fd<\/b>() does not call malloc<\/b>(3), and so can be employed in situations where the latter function might fail, but see NOTES.<\/p>\nRETURN VALUE <\/a> <\/h2>\nbacktrace<\/b>() returns the number of addresses returned in buffer<\/i>, which is not greater than size<\/i>. If the return value is less than size<\/i>, then the full backtrace was stored; if it is equal to size<\/i>, then it may have been truncated, in which case the addresses of the oldest stack frames are not returned.<\/p>\n
On success, backtrace_symbols<\/b>() returns a pointer to the array malloc<\/b>(3)ed by the call; on error, NULL is returned.<\/p>\nVERSIONS <\/a> <\/h2>\nbacktrace<\/b>(), backtrace_symbols<\/b>(), and backtrace_symbols_fd<\/b>() are provided in glibc since version 2.1.<\/p>\nATTRIBUTES <\/a> <\/h2>\nFor an explanation of the terms used in this section, see attributes<\/b>(7).<\/p>\n
#include int backtrace(void **<\/b>buffer<\/i>, int<\/b> size<\/i>);<\/b><\/p>\n char **backtrace_symbols(void *const *<\/b>buffer<\/i>, int<\/b> size<\/i>);<\/b><\/p>\n void backtrace_symbols_fd(void *const *<\/b>buffer<\/i>, int<\/b> size<\/i>, int<\/b> fd<\/i>);<\/b><\/p>\n backtrace<\/b>() returns a backtrace for the calling program, in the array pointed to by buffer<\/i>. A backtrace is the series of currently active function calls for the program. Each item in the array pointed to by buffer<\/i> is of type void\u00a0*<\/i>, and is the return address from the corresponding stack frame. The size<\/i> argument specifies the maximum number of addresses that can be stored in buffer<\/i>. If the backtrace is larger than size<\/i>, then the addresses corresponding to the size<\/i> most recent function calls are returned; to obtain the complete backtrace, make sure that buffer<\/i> and size<\/i> are large enough.<\/p>\n Given the set of addresses returned by backtrace<\/b>() in buffer<\/i>, backtrace_symbols<\/b>() translates the addresses into an array of strings that describe the addresses symbolically. The size<\/i> argument specifies the number of addresses in buffer<\/i>. 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 backtrace_symbols<\/b>(). This array is malloc<\/b>(3)ed by backtrace_symbols<\/b>(), and must be freed by the caller. (The strings pointed to by the array of pointers need not and should not be freed.)<\/p>\n backtrace_symbols_fd<\/b>() takes the same buffer<\/i> and size<\/i> arguments as backtrace_symbols<\/b>(), but instead of returning an array of strings to the caller, it writes the strings, one per line, to the file descriptor fd<\/i>. backtrace_symbols_fd<\/b>() does not call malloc<\/b>(3), and so can be employed in situations where the latter function might fail, but see NOTES.<\/p>\n backtrace<\/b>() returns the number of addresses returned in buffer<\/i>, which is not greater than size<\/i>. If the return value is less than size<\/i>, then the full backtrace was stored; if it is equal to size<\/i>, then it may have been truncated, in which case the addresses of the oldest stack frames are not returned.<\/p>\n On success, backtrace_symbols<\/b>() returns a pointer to the array malloc<\/b>(3)ed by the call; on error, NULL is returned.<\/p>\n backtrace<\/b>(), backtrace_symbols<\/b>(), and backtrace_symbols_fd<\/b>() are provided in glibc since version 2.1.<\/p>\n For an explanation of the terms used in this section, see attributes<\/b>(7).<\/p>\nDESCRIPTION <\/a> <\/h2>\n
RETURN VALUE <\/a> <\/h2>\n
VERSIONS <\/a> <\/h2>\n
ATTRIBUTES <\/a> <\/h2>\n
![\"Image](\"grohtml-1579261.png\")
<\/p>\n