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