man/, share/mk/: Move man*/ to man/

[thirdparty/man-pages.git] / man / man3 / backtrace.3

'\" 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)