1 /* backtrace.h -- Public header file for stack backtrace library. 2 Copyright (C) 2012-2013 Free Software Foundation, Inc. 3 Written by Ian Lance Taylor, Google. 4 5 Redistribution and use in source and binary forms, with or without 6 modification, are permitted provided that the following conditions are 7 met: 8 9 (1) Redistributions of source code must retain the above copyright 10 notice, this list of conditions and the following disclaimer. 11 12 (2) Redistributions in binary form must reproduce the above copyright 13 notice, this list of conditions and the following disclaimer in 14 the documentation and/or other materials provided with the 15 distribution. 16 17 (3) The name of the author may not be used to 18 endorse or promote products derived from this software without 19 specific prior written permission. 20 21 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 22 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 23 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 24 DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, 25 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 26 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 27 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 29 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 30 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 31 POSSIBILITY OF SUCH DAMAGE. */ 32 33 #ifndef BACKTRACE_H 34 #define BACKTRACE_H 35 36 #include <stddef.h> 37 #include <stdio.h> 38 39 /* We want to get a definition for uintptr_t, but we still care about 40 systems that don't have <stdint.h>. */ 41 #if defined(__GLIBC__) && __GLIBC__ >= 2 42 43 #include <stdint.h> 44 45 #elif defined(HAVE_STDINT_H) 46 47 #include <stdint.h> 48 49 #else 50 51 /* Systems that don't have <stdint.h> must provide gstdint.h, e.g., 52 from GCC_HEADER_STDINT in configure.ac. */ 53 #include "gstdint.h" 54 55 #endif 56 57 #ifdef __cplusplus 58 extern "C" { 59 #endif 60 61 /* The backtrace state. This struct is intentionally not defined in 62 the public interface. */ 63 64 struct backtrace_state; 65 66 /* The type of the error callback argument to backtrace functions. 67 This function, if not NULL, will be called for certain error cases. 68 The DATA argument is passed to the function that calls this one. 69 The MSG argument is an error message. The ERRNUM argument, if 70 greater than 0, holds an errno value. The MSG buffer may become 71 invalid after this function returns. 72 73 As a special case, the ERRNUM argument will be passed as -1 if no 74 debug info can be found for the executable, but the function 75 requires debug info (e.g., backtrace_full, backtrace_pcinfo). The 76 MSG in this case will be something along the lines of "no debug 77 info". Similarly, ERRNUM will be passed as -1 if there is no 78 symbol table, but the function requires a symbol table (e.g., 79 backtrace_syminfo). This may be used as a signal that some other 80 approach should be tried. */ 81 82 typedef void (*backtrace_error_callback) (void *data, const char *msg, 83 int errnum); 84 85 /* Create state information for the backtrace routines. This must be 86 called before any of the other routines, and its return value must 87 be passed to all of the other routines. FILENAME is the path name 88 of the executable file; if it is NULL the library will try 89 system-specific path names. If not NULL, FILENAME must point to a 90 permanent buffer. If THREADED is non-zero the state may be 91 accessed by multiple threads simultaneously, and the library will 92 use appropriate locks (this requires that the library be configured 93 with --enable-backtrace-threads). If THREADED is zero the state 94 may only be accessed by one thread at a time. This returns a state 95 pointer on success, NULL on error. If an error occurs, this will 96 call the ERROR_CALLBACK routine. */ 97 98 extern struct backtrace_state *backtrace_create_state ( 99 const char *filename, int threaded, 100 backtrace_error_callback error_callback, void *data); 101 102 /* The type of the callback argument to the backtrace_full function. 103 DATA is the argument passed to backtrace_full. PC is the program 104 counter. FILENAME is the name of the file containing PC, or NULL 105 if not available. LINENO is the line number in FILENAME containing 106 PC, or 0 if not available. FUNCTION is the name of the function 107 containing PC, or NULL if not available. This should return 0 to 108 continuing tracing. The FILENAME and FUNCTION buffers may become 109 invalid after this function returns. */ 110 111 typedef int (*backtrace_full_callback) (void *data, uintptr_t pc, 112 const char *filename, int lineno, 113 const char *function); 114 115 /* Get a full stack backtrace. SKIP is the number of frames to skip; 116 passing 0 will start the trace with the function calling 117 backtrace_full. DATA is passed to the callback routine. If any 118 call to CALLBACK returns a non-zero value, the stack backtrace 119 stops, and backtrace returns that value; this may be used to limit 120 the number of stack frames desired. If all calls to CALLBACK 121 return 0, backtrace returns 0. The backtrace_full function will 122 make at least one call to either CALLBACK or ERROR_CALLBACK. This 123 function requires debug info for the executable. */ 124 125 extern int backtrace_full (struct backtrace_state *state, int skip, 126 backtrace_full_callback callback, 127 backtrace_error_callback error_callback, 128 void *data); 129 130 /* The type of the callback argument to the backtrace_simple function. 131 DATA is the argument passed to simple_backtrace. PC is the program 132 counter. This should return 0 to continue tracing. */ 133 134 typedef int (*backtrace_simple_callback) (void *data, uintptr_t pc); 135 136 /* Get a simple backtrace. SKIP is the number of frames to skip, as 137 in backtrace. DATA is passed to the callback routine. If any call 138 to CALLBACK returns a non-zero value, the stack backtrace stops, 139 and backtrace_simple returns that value. Otherwise 140 backtrace_simple returns 0. The backtrace_simple function will 141 make at least one call to either CALLBACK or ERROR_CALLBACK. This 142 function does not require any debug info for the executable. */ 143 144 extern int backtrace_simple (struct backtrace_state *state, int skip, 145 backtrace_simple_callback callback, 146 backtrace_error_callback error_callback, 147 void *data); 148 149 /* Print the current backtrace in a user readable format to a FILE. 150 SKIP is the number of frames to skip, as in backtrace_full. Any 151 error messages are printed to stderr. This function requires debug 152 info for the executable. */ 153 154 extern void backtrace_print (struct backtrace_state *state, int skip, FILE *); 155 156 /* Given PC, a program counter in the current program, call the 157 callback function with filename, line number, and function name 158 information. This will normally call the callback function exactly 159 once. However, if the PC happens to describe an inlined call, and 160 the debugging information contains the necessary information, then 161 this may call the callback function multiple times. This will make 162 at least one call to either CALLBACK or ERROR_CALLBACK. This 163 returns the first non-zero value returned by CALLBACK, or 0. */ 164 165 extern int backtrace_pcinfo (struct backtrace_state *state, uintptr_t pc, 166 backtrace_full_callback callback, 167 backtrace_error_callback error_callback, 168 void *data); 169 170 /* The type of the callback argument to backtrace_syminfo. DATA and 171 PC are the arguments passed to backtrace_syminfo. SYMNAME is the 172 name of the symbol for the corresponding code. SYMVAL is the 173 value. SYMNAME will be NULL if no error occurred but the symbol 174 could not be found. */ 175 176 typedef void (*backtrace_syminfo_callback) (void *data, uintptr_t pc, 177 const char *symname, 178 uintptr_t symval); 179 180 /* Given PC, a program counter in the current program, call the 181 callback information with the symbol name and value describing the 182 function in which PC may be found. This will call either CALLBACK 183 or ERROR_CALLBACK exactly once. This returns 1 on success, 0 on 184 failure. This function requires the symbol table but does not 185 require the debug info. Note that if the symbol table is present 186 but PC could not be found in the table, CALLBACK will be called 187 with a NULL SYMNAME argument. Returns 1 on success, 0 on 188 error. */ 189 190 extern int backtrace_syminfo (struct backtrace_state *state, uintptr_t pc, 191 backtrace_syminfo_callback callback, 192 backtrace_error_callback error_callback, 193 void *data); 194 195 #ifdef __cplusplus 196 } /* End extern "C". */ 197 #endif 198 199 #endif 200