1/24/12

Backtraces - The GNU C Librar

Up: Debugging Support

33.1 Backtraces
A backtrace is a list of the function calls that are currently active in a thread. The usual way to inspect a backtrace of a program is to use an external debugger such as gdb. However, sometimes it is useful to obtain a backtrace programmatically from within a program, e.g., for the purposes of logging or diagnostics. The header file e e i f . declares three functions that obtain and manipulate backtraces of the current cnoh thread. Function: int backtrace (void **buffer, int si e) The b c t a efunction obtains a backtrace for the current thread, as a list of pointers, and places akrc the information into buffer. The argument si e should be the number of v i *elements that will fit od into buffer. The return value is the actual number of entries of buffer that are obtained, and is at most si e. The pointers placed in buffer are actually return addresses obtained by inspecting the stack, one return address per stack frame. Note that certain compiler optimizations may interfere with obtaining a valid backtrace. Function inlining causes the inlined function to not have a stack frame; tail call optimization replaces one stack frame with another; frame pointer elimination will stop b c t a efrom interpreting the stack akrc contents correctly. Function: char ** backtrace_s mbols (void *const *buffer, int si e) The b c t a e s m o sfunction translates the information obtained from the b c t a e akrc_ bl akrc function into an array of strings. The argument buffer should be a pointer to an array of addresses obtained via the b c t a efunction, and si e is the number of entries in that array (the return akrc value of b c t a e a k r c ). The return value is a pointer to an array of strings, which has si e entries just like the array buffer. Each string contains a printable representation of the corresponding element of buffer. It includes the function name (if this can be determined), an offset into the function, and the actual return address (in hexadecimal). Currently, the function name and offset only be obtained on systems that use the ELF binary format for programs and libraries. On other systems, only the hexadecimal return address will be present. Also, you may need to pass additional flags to the linker to make the function names available to the program. (For example, on systems using GNU ld, you must pass (- d n m c r a i .) The return value of b c t a e s m o sis a pointer obtained via the m l o function, and it is akrc_ bl alc the responsibility of the caller to f e that pointer. Note that only the return value need be freed, re not the individual strings.
www.gnu.org/software/libc/manual/html_node/Backtraces.html 1/2

1/24/12

Backtraces - The GNU C Librar

The return value is N L if sufficient memory for the strings cannot be obtained. UL Function: void backtrace_s mbols_fd (void *const *buffer, int si e, int fd) The b c t a e s m o s f function performs the same translation as the function akrc_ybl_d b c t a e s m o sfunction. Instead of returning the strings to the caller, it writes the strings to akrc_ybl the file descriptor fd, one per line. It does not use the m l o function, and can therefore be used alc in situations where that function might fail. The following program illustrates the use of these functions. Note that the array to contain the return addresses returned by b c t a eis allocated on the stack. Therefore code like this can be used in situations where the akrc memory handling via m l o does not work anymore (in which case the b c t a e s m o shas to be alc akrc_ybl replaced by a b c t a e s m o s f call as well). The number of return addresses is normally not very large. akrc_ybl_d Even complicated programs rather seldom have a nesting level of more than, say, 50 and with 200 possible entries probably all programs should be covered.
#nld <xcnoh icue eeif.> #nld <ti.> icue sdoh #nld <tlbh icue sdi.> / Obtain a backtrace and print it to s d u . * * tot / vi od pittae(od rn_rc vi) { vi *ra[0; od ary1] sz_ sz; iet ie ca *srns hr *tig; sz_ i iet ; sz =bctae(ra,1) ie akrc ary 0; srns=bctaesmos(ra,sz) tig akrc_ybl ary ie; pit (Otie %dsakfae.n,sz) rnf "band z tc rms\" ie; fr( =0 i<sz;i+ o i ; ie +) pit (%\" srnsi) rnf "sn, tig[]; fe (tig) re srns;

/ A dummy function to make the backtrace more interesting. * * / vi od dmyfnto (od um_ucin vi) { pittae(; rn_rc )

it n mi (od an vi) { dmyfnto (; um_ucin ) rtr 0 eun ;

www.gnu.org/software/libc/manual/html_node/Backtraces.html

2/2