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