man3/backtrace.3

   1 .\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" drawing on material by Justin Pryzby <pryzbyj@justinpryzby.com>
   3 .\"
   4 .\" %%%LICENSE_START(PERMISSIVE_MISC)
   5 .\" Permission is hereby granted, free of charge, to any person obtaining
   6 .\" a copy of this software and associated documentation files (the
   7 .\" "Software"), to deal in the Software without restriction, including
   8 .\" without limitation the rights to use, copy, modify, merge, publish,
   9 .\" distribute, sublicense, and/or sell copies of the Software, and to
  10 .\" permit persons to whom the Software is furnished to do so, subject to
  11 .\" the following conditions:
  12 .\"
  13 .\" The above copyright notice and this permission notice shall be
  14 .\" included in all copies or substantial portions of the Software.
  15 .\"
  16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  17 .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  19 .\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  20 .\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  21 .\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  22 .\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" References:
  26 .\"   glibc manual and source
  27 .TH BACKTRACE 3 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  28 .SH NAME
  29 backtrace, backtrace_symbols, backtrace_symbols_fd \- support
  30 for application self-debugging
  31 .SH LIBRARY
  32 Standard C library
  33 .RI ( libc ", " \-lc )
  34 .SH SYNOPSIS
  35 .nf
  36 .B #include <execinfo.h>
  37 .PP
  38 .BI "int backtrace(void **" buffer ", int " size );
  39 .PP
  40 .BI "char **backtrace_symbols(void *const *" buffer ", int " size );
  41 .BI "void backtrace_symbols_fd(void *const *" buffer ", int " size ", int " fd );
  42 .fi
  43 .SH DESCRIPTION
  44 .BR backtrace ()
  45 returns a backtrace for the calling program,
  46 in the array pointed to by
  47 .IR buffer .
  48 A backtrace is the series of currently active function calls for
  49 the program.
  50 Each item in the array pointed to by
  51 .I buffer
  52 is of type
  53 .IR "void\ *" ,
  54 and is the return address from
  55 the corresponding stack frame.
  56 The
  57 .I size
  58 argument specifies the maximum number of addresses
  59 that can be stored in
  60 .IR buffer .
  61 If the backtrace is larger than
  62 .IR size ,
  63 then the addresses corresponding to the
  64 .I size
  65 most recent function calls are returned;
  66 to obtain the complete backtrace, make sure that
  67 .I buffer
  68 and
  69 .I size
  70 are large enough.
  71 .PP
  72 Given the set of addresses returned by
  73 .BR backtrace ()
  74 in
  75 .IR buffer ,
  76 .BR backtrace_symbols ()
  77 translates the addresses into an array of strings that describe
  78 the addresses symbolically.
  79 The
  80 .I size
  81 argument specifies the number of addresses in
  82 .IR buffer .
  83 The symbolic representation of each address consists of the function name
  84 (if this can be determined), a hexadecimal offset into the function,
  85 and the actual return address (in hexadecimal).
  86 The address of the array of string pointers is returned
  87 as the function result of
  88 .BR backtrace_symbols ().
  89 This array is
  90 .BR malloc (3)ed
  91 by
  92 .BR backtrace_symbols (),
  93 and must be freed by the caller.
  94 (The strings pointed to by the array of pointers
  95 need not and should not be freed.)
  96 .PP
  97 .BR backtrace_symbols_fd ()
  98 takes the same
  99 .I buffer
 100 and
 101 .I size
 102 arguments as
 103 .BR backtrace_symbols (),
 104 but instead of returning an array of strings to the caller,
 105 it writes the strings, one per line, to the file descriptor
 106 .IR fd .
 107 .BR backtrace_symbols_fd ()
 108 does not call
 109 .BR malloc (3),
 110 and so can be employed in situations where the latter function might
 111 fail, but see NOTES.
 112 .SH RETURN VALUE
 113 .BR backtrace ()
 114 returns the number of addresses returned in
 115 .IR buffer ,
 116 which is not greater than
 117 .IR size .
 118 If the return value is less than
 119 .IR size ,
 120 then the full backtrace was stored; if it is equal to
 121 .IR size ,
 122 then it may have been truncated, in which case the addresses of the
 123 oldest stack frames are not returned.
 124 .PP
 125 On success,
 126 .BR backtrace_symbols ()
 127 returns a pointer to the array
 128 .BR malloc (3)ed
 129 by the call;
 130 on error, NULL is returned.
 131 .SH VERSIONS
 132 .BR backtrace (),
 133 .BR backtrace_symbols (),
 134 and
 135 .BR backtrace_symbols_fd ()
 136 are provided in glibc since version 2.1.
 137 .SH ATTRIBUTES
 138 For an explanation of the terms used in this section, see
 139 .BR attributes (7).
 140 .ad l
 141 .nh
 142 .TS
 143 allbox;
 144 lbx lb lb
 145 l l l.
 146 Interface       Attribute       Value
 147 T{
 148 .BR backtrace (),
 149 .BR backtrace_symbols (),
 150 .BR backtrace_symbols_fd ()
 151 T}      Thread safety   MT-Safe
 152 .TE
 153 .hy
 154 .ad
 155 .sp 1
 156 .SH STANDARDS
 157 These functions are GNU extensions.
 158 .SH NOTES
 159 These functions make some assumptions about how a function's return
 160 address is stored on the stack.
 161 Note the following:
 162 .IP * 3
 163 Omission of the frame pointers (as
 164 implied by any of
 165 .BR gcc (1)'s
 166 nonzero optimization levels) may cause these assumptions to be
 167 violated.
 168 .IP *
 169 Inlined functions do not have stack frames.
 170 .IP *
 171 Tail-call optimization causes one stack frame to replace another.
 172 .IP *
 173 .BR backtrace ()
 174 and
 175 .BR backtrace_symbols_fd ()
 176 don't call
 177 .BR malloc ()
 178 explicitly, but they are part of
 179 .IR libgcc ,
 180 which gets loaded dynamically when first used.
 181 Dynamic loading usually triggers a call to
 182 .BR malloc (3).
 183 If you need certain calls to these two functions to not allocate memory
 184 (in signal handlers, for example), you need to make sure
 185 .I libgcc
 186 is loaded beforehand.
 187 .PP
 188 The symbol names may be unavailable without the use of special linker
 189 options.
 190 For systems using the GNU linker, it is necessary to use the
 191 .I \-rdynamic
 192 linker option.
 193 Note that names of "static" functions are not exposed,
 194 and won't be available in the backtrace.
 195 .SH EXAMPLES
 196 The program below demonstrates the use of
 197 .BR backtrace ()
 198 and
 199 .BR backtrace_symbols ().
 200 The following shell session shows what we might see when running the
 201 program:
 202 .PP
 203 .in +4n
 204 .EX
 205 .RB "$" " cc \-rdynamic prog.c \-o prog"
 206 .RB "$" " ./prog 3"
 207 backtrace() returned 8 addresses
 208 \&./prog(myfunc3+0x5c) [0x80487f0]
 209 \&./prog [0x8048871]
 210 \&./prog(myfunc+0x21) [0x8048894]
 211 \&./prog(myfunc+0x1a) [0x804888d]
 212 \&./prog(myfunc+0x1a) [0x804888d]
 213 \&./prog(main+0x65) [0x80488fb]
 214 \&/lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c]
 215 \&./prog [0x8048711]
 216 .EE
 217 .in
 218 .SS Program source
 219 \&
 220 .EX
 221 #include <execinfo.h>
 222 #include <stdio.h>
 223 #include <stdlib.h>
 224 #include <unistd.h>
 225
 226 #define BT_BUF_SIZE 100
 227
 228 void
 229 myfunc3(void)
 230 {
 231     int nptrs;
 232     void *buffer[BT_BUF_SIZE];
 233     char **strings;
 234
 235     nptrs = backtrace(buffer, BT_BUF_SIZE);
 236     printf("backtrace() returned %d addresses\en", nptrs);
 237
 238     /* The call backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO)
 239        would produce similar output to the following: */
 240
 241     strings = backtrace_symbols(buffer, nptrs);
 242     if (strings == NULL) {
 243         perror("backtrace_symbols");
 244         exit(EXIT_FAILURE);
 245     }
 246
 247     for (int j = 0; j < nptrs; j++)
 248         printf("%s\en", strings[j]);
 249
 250     free(strings);
 251 }
 252
 253 static void   /* "static" means don\(aqt export the symbol... */
 254 myfunc2(void)
 255 {
 256     myfunc3();
 257 }
 258
 259 void
 260 myfunc(int ncalls)
 261 {
 262     if (ncalls > 1)
 263         myfunc(ncalls \- 1);
 264     else
 265         myfunc2();
 266 }
 267
 268 int
 269 main(int argc, char *argv[])
 270 {
 271     if (argc != 2) {
 272         fprintf(stderr, "%s num\-calls\en", argv[0]);
 273         exit(EXIT_FAILURE);
 274     }
 275
 276     myfunc(atoi(argv[1]));
 277     exit(EXIT_SUCCESS);
 278 }
 279 .EE
 280 .SH SEE ALSO
 281 .BR addr2line (1),
 282 .BR gcc (1),
 283 .BR gdb (1),
 284 .BR ld (1),
 285 .BR dlopen (3),
 286 .BR malloc (3)