diff options
Diffstat (limited to 'man/man3/backtrace.3')
| -rw-r--r-- | man/man3/backtrace.3 | 283 |
1 files changed, 283 insertions, 0 deletions
diff --git a/man/man3/backtrace.3 b/man/man3/backtrace.3 new file mode 100644 index 000000000..4875da31f --- /dev/null +++ b/man/man3/backtrace.3 @@ -0,0 +1,283 @@ +'\" t +.\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com> +.\" drawing on material by Justin Pryzby <pryzbyj@justinpryzby.com> +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.\" References: +.\" glibc manual and source +.TH backtrace 3 (date) "Linux man-pages (unreleased)" +.SH NAME +backtrace, backtrace_symbols, backtrace_symbols_fd \- support +for application self-debugging +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <execinfo.h> +.P +.BI "int backtrace(void *" buffer [. size "], int " size ); +.P +.BI "char **backtrace_symbols(void *const " buffer [. size "], int " size ); +.BI "void backtrace_symbols_fd(void *const " buffer [. size "], int " size ", \ +int " fd ); +.fi +.SH DESCRIPTION +.BR backtrace () +returns a backtrace for the calling program, +in the array pointed to by +.IR buffer . +A backtrace is the series of currently active function calls for +the program. +Each item in the array pointed to by +.I buffer +is of type +.IR "void\ *" , +and is the return address from +the corresponding stack frame. +The +.I size +argument specifies the maximum number of addresses +that can be stored in +.IR buffer . +If the backtrace is larger than +.IR size , +then the addresses corresponding to the +.I size +most recent function calls are returned; +to obtain the complete backtrace, make sure that +.I buffer +and +.I size +are large enough. +.P +Given the set of addresses returned by +.BR backtrace () +in +.IR buffer , +.BR backtrace_symbols () +translates the addresses into an array of strings that describe +the addresses symbolically. +The +.I size +argument specifies the number of addresses in +.IR buffer . +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 +.BR backtrace_symbols (). +This array is +.BR malloc (3)ed +by +.BR backtrace_symbols (), +and must be freed by the caller. +(The strings pointed to by the array of pointers +need not and should not be freed.) +.P +.BR backtrace_symbols_fd () +takes the same +.I buffer +and +.I size +arguments as +.BR backtrace_symbols (), +but instead of returning an array of strings to the caller, +it writes the strings, one per line, to the file descriptor +.IR fd . +.BR backtrace_symbols_fd () +does not call +.BR malloc (3), +and so can be employed in situations where the latter function might +fail, but see NOTES. +.SH RETURN VALUE +.BR backtrace () +returns the number of addresses returned in +.IR buffer , +which is not greater than +.IR size . +If the return value is less than +.IR size , +then the full backtrace was stored; if it is equal to +.IR size , +then it may have been truncated, in which case the addresses of the +oldest stack frames are not returned. +.P +On success, +.BR backtrace_symbols () +returns a pointer to the array +.BR malloc (3)ed +by the call; +on error, NULL is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR backtrace (), +.BR backtrace_symbols (), +.BR backtrace_symbols_fd () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.SH NOTES +These functions make some assumptions about how a function's return +address is stored on the stack. +Note the following: +.IP \[bu] 3 +Omission of the frame pointers (as +implied by any of +.BR gcc (1)'s +nonzero optimization levels) may cause these assumptions to be +violated. +.IP \[bu] +Inlined functions do not have stack frames. +.IP \[bu] +Tail-call optimization causes one stack frame to replace another. +.IP \[bu] +.BR backtrace () +and +.BR backtrace_symbols_fd () +don't call +.BR malloc () +explicitly, but they are part of +.IR libgcc , +which gets loaded dynamically when first used. +Dynamic loading usually triggers a call to +.BR malloc (3). +If you need certain calls to these two functions to not allocate memory +(in signal handlers, for example), you need to make sure +.I libgcc +is loaded beforehand. +.P +The symbol names may be unavailable without the use of special linker +options. +For systems using the GNU linker, it is necessary to use the +.I \-rdynamic +linker option. +Note that names of "static" functions are not exposed, +and won't be available in the backtrace. +.SH EXAMPLES +The program below demonstrates the use of +.BR backtrace () +and +.BR backtrace_symbols (). +The following shell session shows what we might see when running the +program: +.P +.in +4n +.EX +.RB "$" " cc \-rdynamic prog.c \-o prog" +.RB "$" " ./prog 3" +backtrace() returned 8 addresses +\&./prog(myfunc3+0x5c) [0x80487f0] +\&./prog [0x8048871] +\&./prog(myfunc+0x21) [0x8048894] +\&./prog(myfunc+0x1a) [0x804888d] +\&./prog(myfunc+0x1a) [0x804888d] +\&./prog(main+0x65) [0x80488fb] +\&/lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c] +\&./prog [0x8048711] +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (backtrace.c) +.EX +#include <execinfo.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +#define BT_BUF_SIZE 100 +\& +void +myfunc3(void) +{ + int nptrs; + void *buffer[BT_BUF_SIZE]; + char **strings; +\& + nptrs = backtrace(buffer, BT_BUF_SIZE); + printf("backtrace() returned %d addresses\en", nptrs); +\& + /* The call backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO) + would produce similar output to the following: */ +\& + strings = backtrace_symbols(buffer, nptrs); + if (strings == NULL) { + perror("backtrace_symbols"); + exit(EXIT_FAILURE); + } +\& + for (size_t j = 0; j < nptrs; j++) + printf("%s\en", strings[j]); +\& + free(strings); +} +\& +static void /* "static" means don\[aq]t export the symbol... */ +myfunc2(void) +{ + myfunc3(); +} +\& +void +myfunc(int ncalls) +{ + if (ncalls > 1) + myfunc(ncalls \- 1); + else + myfunc2(); +} +\& +int +main(int argc, char *argv[]) +{ + if (argc != 2) { + fprintf(stderr, "%s num\-calls\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + myfunc(atoi(argv[1])); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR addr2line (1), +.BR gcc (1), +.BR gdb (1), +.BR ld (1), +.BR dlopen (3), +.BR malloc (3) |