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