1 /* backtrace.h -- Public header file for stack backtrace library. 2 Copyright (C) 2012-2016 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 <stdint.h> 38 #include <stdio.h> 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /* The backtrace state. This struct is intentionally not defined in 45 the public interface. */ 46 47 struct backtrace_state; 48 49 /* The type of the error callback argument to backtrace functions. 50 This function, if not NULL, will be called for certain error cases. 51 The DATA argument is passed to the function that calls this one. 52 The MSG argument is an error message. The ERRNUM argument, if 53 greater than 0, holds an errno value. The MSG buffer may become 54 invalid after this function returns. 55 56 As a special case, the ERRNUM argument will be passed as -1 if no 57 debug info can be found for the executable, but the function 58 requires debug info (e.g., backtrace_full, backtrace_pcinfo). The 59 MSG in this case will be something along the lines of "no debug 60 info". Similarly, ERRNUM will be passed as -1 if there is no 61 symbol table, but the function requires a symbol table (e.g., 62 backtrace_syminfo). This may be used as a signal that some other 63 approach should be tried. */ 64 65 typedef void (*backtrace_error_callback) (void *data, const char *msg, 66 int errnum); 67 68 /* Create state information for the backtrace routines. This must be 69 called before any of the other routines, and its return value must 70 be passed to all of the other routines. FILENAME is the path name 71 of the executable file; if it is NULL the library will try 72 system-specific path names. If not NULL, FILENAME must point to a 73 permanent buffer. If THREADED is non-zero the state may be 74 accessed by multiple threads simultaneously, and the library will 75 use appropriate atomic operations. If THREADED is zero the state 76 may only be accessed by one thread at a time. This returns a state 77 pointer on success, NULL on error. If an error occurs, this will 78 call the ERROR_CALLBACK routine. */ 79 80 extern struct backtrace_state *backtrace_create_state ( 81 const char *filename, int threaded, 82 backtrace_error_callback error_callback, void *data); 83 84 /* Release all resources held by STATE. */ 85 86 extern void backtrace_destroy_state (struct backtrace_state *state, 87 backtrace_error_callback error_callback, 88 void *data); 89 90 /* The type of the function called by backtrace_so_iterator. */ 91 92 typedef int backtrace_so_callback (const char *name, uintptr_t addr, void *data); 93 94 /* The type of the function that iterates over shared libs. 95 ITER_STATE is the iter_state argument to backtrace_set_so_iterator. 96 DATA is passed to CALLBACK. 97 The semantics are the same as dl_iterate_phdr. 98 CALLBACK is called for each shared library until are shared libs 99 are processed or a callback returns non-zero. */ 100 101 typedef int backtrace_so_iterator (void* iter_state, 102 backtrace_so_callback *callback, 103 void *data); 104 105 /* Set the shared library(object) iterator. */ 106 107 extern void backtrace_set_so_iterator (struct backtrace_state *state, 108 backtrace_so_iterator *func, 109 void *iter_state); 110 111 /* Set the base address of the file FILENAME passed to 112 backtrace_create_state. */ 113 114 extern void backtrace_set_base_address (struct backtrace_state *state, 115 uintptr_t base); 116 117 /* The type of the callback argument to the backtrace_full function. 118 DATA is the argument passed to backtrace_full. PC is the program 119 counter. FILENAME is the name of the file containing PC, or NULL 120 if not available. LINENO is the line number in FILENAME containing 121 PC, or 0 if not available. FUNCTION is the name of the function 122 containing PC, or NULL if not available. This should return 0 to 123 continuing tracing. The FILENAME and FUNCTION buffers may become 124 invalid after this function returns. */ 125 126 typedef int (*backtrace_full_callback) (void *data, uintptr_t pc, 127 const char *filename, int lineno, 128 const char *function); 129 130 /* Get a full stack backtrace. SKIP is the number of frames to skip; 131 passing 0 will start the trace with the function calling 132 backtrace_full. DATA is passed to the callback routine. If any 133 call to CALLBACK returns a non-zero value, the stack backtrace 134 stops, and backtrace returns that value; this may be used to limit 135 the number of stack frames desired. If all calls to CALLBACK 136 return 0, backtrace returns 0. The backtrace_full function will 137 make at least one call to either CALLBACK or ERROR_CALLBACK. This 138 function requires debug info for the executable. */ 139 140 extern int backtrace_full (struct backtrace_state *state, int skip, 141 backtrace_full_callback callback, 142 backtrace_error_callback error_callback, 143 void *data); 144 145 /* The type of the callback argument to the backtrace_simple function. 146 DATA is the argument passed to simple_backtrace. PC is the program 147 counter. This should return 0 to continue tracing. */ 148 149 typedef int (*backtrace_simple_callback) (void *data, uintptr_t pc); 150 151 /* Get a simple backtrace. SKIP is the number of frames to skip, as 152 in backtrace. DATA is passed to the callback routine. If any call 153 to CALLBACK returns a non-zero value, the stack backtrace stops, 154 and backtrace_simple returns that value. Otherwise 155 backtrace_simple returns 0. The backtrace_simple function will 156 make at least one call to either CALLBACK or ERROR_CALLBACK. This 157 function does not require any debug info for the executable. */ 158 159 extern int backtrace_simple (struct backtrace_state *state, int skip, 160 backtrace_simple_callback callback, 161 backtrace_error_callback error_callback, 162 void *data); 163 164 /* Print the current backtrace in a user readable format to a FILE. 165 SKIP is the number of frames to skip, as in backtrace_full. Any 166 error messages are printed to stderr. This function requires debug 167 info for the executable. */ 168 169 extern void backtrace_print (struct backtrace_state *state, int skip, FILE *); 170 171 /* Given PC, a program counter in the current program, call the 172 callback function with filename, line number, and function name 173 information. This will normally call the callback function exactly 174 once. However, if the PC happens to describe an inlined call, and 175 the debugging information contains the necessary information, then 176 this may call the callback function multiple times. This will make 177 at least one call to either CALLBACK or ERROR_CALLBACK. This 178 returns the first non-zero value returned by CALLBACK, or 0. */ 179 180 extern int backtrace_pcinfo (struct backtrace_state *state, uintptr_t pc, 181 backtrace_full_callback callback, 182 backtrace_error_callback error_callback, 183 void *data); 184 185 /* The type of the callback argument to backtrace_syminfo. DATA and 186 PC are the arguments passed to backtrace_syminfo. SYMNAME is the 187 name of the symbol for the corresponding code. SYMVAL is the 188 value and SYMSIZE is the size of the symbol. SYMNAME will be NULL 189 if no error occurred but the symbol could not be found. */ 190 191 typedef void (*backtrace_syminfo_callback) (void *data, uintptr_t pc, 192 const char *symname, 193 uintptr_t symval, 194 uintptr_t symsize); 195 196 /* Given ADDR, an address or program counter in the current program, 197 call the callback information with the symbol name and value 198 describing the function or variable in which ADDR may be found. 199 This will call either CALLBACK or ERROR_CALLBACK exactly once. 200 This returns 1 on success, 0 on failure. This function requires 201 the symbol table but does not require the debug info. Note that if 202 the symbol table is present but ADDR could not be found in the 203 table, CALLBACK will be called with a NULL SYMNAME argument. 204 Returns 1 on success, 0 on error. */ 205 206 extern int backtrace_syminfo (struct backtrace_state *state, uintptr_t addr, 207 backtrace_syminfo_callback callback, 208 backtrace_error_callback error_callback, 209 void *data); 210 211 #ifdef __cplusplus 212 } /* End extern "C". */ 213 #endif 214 215 #endif 216