mirror of https://github.com/mkerrisk/man-pages
Documentation of backtrace(), backtrace_symbols(), and
backtrace_symbols_fd().
This commit is contained in:
parent
c7b4971bab
commit
46b7511910
|
@ -0,0 +1,245 @@
|
|||
.\" Copyright (C) 2007 Michael Kerrisk <mtk-manpages@gmx.net>
|
||||
.\" drawing on material by Justin Pryzby <pryzbyj@justinpryzby.com>
|
||||
.\"
|
||||
.\" 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.
|
||||
.\"
|
||||
.\" References:
|
||||
.\" glibc manual and source
|
||||
.TH BACKTRACE 3 "2007-06-22" GNU
|
||||
.SH NAME
|
||||
backtrace, backtrace_symbols, backtrace_symbols_fd \- support
|
||||
for application self-debugging
|
||||
.SH SYNOPSIS
|
||||
.B #include <execinfo.h>
|
||||
|
||||
.B int backtrace(void
|
||||
.BI ** buffer ,
|
||||
.B int
|
||||
.IB size );
|
||||
|
||||
.B char **backtrace_symbols(void *const
|
||||
.BI * buffer ,
|
||||
.B int
|
||||
.IB size );
|
||||
|
||||
.B void backtrace_symbols_fd(void *const
|
||||
.BI * buffer ,
|
||||
.B int
|
||||
.IB size ,
|
||||
.B int
|
||||
.IB fd );
|
||||
.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 \fIvoid *\fP, 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.
|
||||
|
||||
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
|
||||
.IR strings
|
||||
need not and should not be freed.)
|
||||
|
||||
.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 ()
|
||||
does not call
|
||||
.BR malloc (3),
|
||||
and so can be employed in situations where the latter function might fail.
|
||||
.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.
|
||||
|
||||
On success,
|
||||
.BR backtrace_symbols ()
|
||||
returns a pointer to the array
|
||||
.BR malloc (3)ed
|
||||
by the call;
|
||||
on error, NULL is returned.
|
||||
.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
|
||||
non-zero 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.
|
||||
.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 EXAMPLE
|
||||
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:
|
||||
.nf
|
||||
.in +0.25i
|
||||
|
||||
$ cc -rdynamic prog.c -o prog
|
||||
$ ./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]
|
||||
.in
|
||||
.fi
|
||||
.nf
|
||||
|
||||
#include <execinfo.h>
|
||||
#include <stdio.h>
|
||||
#include <stdlib.h>
|
||||
#include <unistd.h>
|
||||
|
||||
void
|
||||
myfunc3(void)
|
||||
{
|
||||
int j, nptrs;
|
||||
#define SIZE 100
|
||||
void *buffer[100];
|
||||
char **strings;
|
||||
|
||||
nptrs = backtrace(buffer, SIZE);
|
||||
printf("backtrace() returned %d addresses\\n", 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 (j = 0; j < nptrs; j++)
|
||||
printf("%s\\n", strings[j]);
|
||||
|
||||
free(strings);
|
||||
}
|
||||
|
||||
static void /* 'static' means don'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\\n", argv[0]);
|
||||
exit(EXIT_FAILURE);
|
||||
}
|
||||
|
||||
myfunc(atoi(argv[1]));
|
||||
exit(EXIT_SUCCESS);
|
||||
}
|
||||
.fi
|
||||
.SH SEE ALSO
|
||||
.BR gcc (1),
|
||||
.BR ld (1),
|
||||
.BR dlopen (3),
|
||||
.BR malloc (3)
|
|
@ -0,0 +1 @@
|
|||
.so man3/backtrace.3
|
|
@ -0,0 +1 @@
|
|||
.so man3/backtrace.3
|
Loading…
Reference in New Issue