mirror of https://github.com/mkerrisk/man-pages
284 lines
7.1 KiB
Groff
284 lines
7.1 KiB
Groff
.\" 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 2021-03-22 GNU "Linux Programmer's Manual"
|
|
.SH NAME
|
|
backtrace, backtrace_symbols, backtrace_symbols_fd \- support
|
|
for application self-debugging
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <execinfo.h>
|
|
.PP
|
|
.BI "int backtrace(void **" buffer ", int " size );
|
|
.PP
|
|
.BI "char **backtrace_symbols(void *const *" buffer ", int " size );
|
|
.BI "void backtrace_symbols_fd(void *const *" buffer ", 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.
|
|
.PP
|
|
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.)
|
|
.PP
|
|
.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.
|
|
.PP
|
|
On success,
|
|
.BR backtrace_symbols ()
|
|
returns a pointer to the array
|
|
.BR malloc (3)ed
|
|
by the call;
|
|
on error, NULL is returned.
|
|
.SH VERSIONS
|
|
.BR backtrace (),
|
|
.BR backtrace_symbols (),
|
|
and
|
|
.BR backtrace_symbols_fd ()
|
|
are provided in glibc since version 2.1.
|
|
.SH ATTRIBUTES
|
|
For an explanation of the terms used in this section, see
|
|
.BR attributes (7).
|
|
.ad l
|
|
.nh
|
|
.TS
|
|
allbox;
|
|
lbx lb lb
|
|
l l l.
|
|
Interface Attribute Value
|
|
T{
|
|
.BR backtrace (),
|
|
.BR backtrace_symbols (),
|
|
.BR backtrace_symbols_fd ()
|
|
T} Thread safety MT-Safe
|
|
.TE
|
|
.hy
|
|
.ad
|
|
.sp 1
|
|
.SH CONFORMING TO
|
|
These functions are GNU extensions.
|
|
.SH NOTES
|
|
These functions make some assumptions about how a function's return
|
|
address is stored on the stack.
|
|
Note the following:
|
|
.IP * 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 *
|
|
Inlined functions do not have stack frames.
|
|
.IP *
|
|
Tail-call optimization causes one stack frame to replace another.
|
|
.IP *
|
|
.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.
|
|
.PP
|
|
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:
|
|
.PP
|
|
.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
|
|
\&
|
|
.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 (int j = 0; j < nptrs; j++)
|
|
printf("%s\en", strings[j]);
|
|
|
|
free(strings);
|
|
}
|
|
|
|
static void /* "static" means don\(aqt 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
|
|
.SH SEE ALSO
|
|
.BR addr2line (1),
|
|
.BR gcc (1),
|
|
.BR gdb (1),
|
|
.BR ld (1),
|
|
.BR dlopen (3),
|
|
.BR malloc (3)
|