diff options
Diffstat (limited to 'man3/backtrace.3')
| -rw-r--r-- | man3/backtrace.3 | 283 |
1 files changed, 0 insertions, 283 deletions
diff --git a/man3/backtrace.3 b/man3/backtrace.3 deleted file mode 100644 index 399b180..0000000 --- a/man3/backtrace.3 +++ /dev/null @@ -1,283 +0,0 @@ -'\" 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 2023-10-31 "Linux man-pages 6.7" -.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) |