|
| 1 | +/* backtrace.h -- Public header file for stack backtrace library. |
| 2 | + Copyright (C) 2012-2024 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, or if the debug info |
| 58 | + exists but has an unsupported version, but the function requires |
| 59 | + debug info (e.g., backtrace_full, backtrace_pcinfo). The MSG in |
| 60 | + this case will be something along the lines of "no debug info". |
| 61 | + Similarly, ERRNUM will be passed as -1 if there is no symbol table, |
| 62 | + but the function requires a symbol table (e.g., backtrace_syminfo). |
| 63 | + This may be used as a signal that some other approach should be |
| 64 | + tried. */ |
| 65 | + |
| 66 | +typedef void (*backtrace_error_callback) (void *data, const char *msg, |
| 67 | + int errnum); |
| 68 | + |
| 69 | +/* Create state information for the backtrace routines. This must be |
| 70 | + called before any of the other routines, and its return value must |
| 71 | + be passed to all of the other routines. FILENAME is the path name |
| 72 | + of the executable file; if it is NULL the library will try |
| 73 | + system-specific path names. If not NULL, FILENAME must point to a |
| 74 | + permanent buffer. If THREADED is non-zero the state may be |
| 75 | + accessed by multiple threads simultaneously, and the library will |
| 76 | + use appropriate atomic operations. If THREADED is zero the state |
| 77 | + may only be accessed by one thread at a time. This returns a state |
| 78 | + pointer on success, NULL on error. If an error occurs, this will |
| 79 | + call the ERROR_CALLBACK routine. |
| 80 | +
|
| 81 | + Calling this function allocates resources that cannot be freed. |
| 82 | + There is no backtrace_free_state function. The state is used to |
| 83 | + cache information that is expensive to recompute. Programs are |
| 84 | + expected to call this function at most once and to save the return |
| 85 | + value for all later calls to backtrace functions. */ |
| 86 | + |
| 87 | +extern struct backtrace_state *backtrace_create_state ( |
| 88 | + const char *filename, int threaded, |
| 89 | + backtrace_error_callback error_callback, void *data); |
| 90 | + |
| 91 | +/* The type of the callback argument to the backtrace_full function. |
| 92 | + DATA is the argument passed to backtrace_full. PC is the program |
| 93 | + counter. FILENAME is the name of the file containing PC, or NULL |
| 94 | + if not available. LINENO is the line number in FILENAME containing |
| 95 | + PC, or 0 if not available. FUNCTION is the name of the function |
| 96 | + containing PC, or NULL if not available. This should return 0 to |
| 97 | + continuing tracing. The FILENAME and FUNCTION buffers may become |
| 98 | + invalid after this function returns. */ |
| 99 | + |
| 100 | +typedef int (*backtrace_full_callback) (void *data, uintptr_t pc, |
| 101 | + const char *filename, int lineno, |
| 102 | + const char *function); |
| 103 | + |
| 104 | +/* Get a full stack backtrace. SKIP is the number of frames to skip; |
| 105 | + passing 0 will start the trace with the function calling |
| 106 | + backtrace_full. DATA is passed to the callback routine. If any |
| 107 | + call to CALLBACK returns a non-zero value, the stack backtrace |
| 108 | + stops, and backtrace returns that value; this may be used to limit |
| 109 | + the number of stack frames desired. If all calls to CALLBACK |
| 110 | + return 0, backtrace returns 0. The backtrace_full function will |
| 111 | + make at least one call to either CALLBACK or ERROR_CALLBACK. This |
| 112 | + function requires debug info for the executable. */ |
| 113 | + |
| 114 | +extern int backtrace_full (struct backtrace_state *state, int skip, |
| 115 | + backtrace_full_callback callback, |
| 116 | + backtrace_error_callback error_callback, |
| 117 | + void *data); |
| 118 | + |
| 119 | +/* The type of the callback argument to the backtrace_simple function. |
| 120 | + DATA is the argument passed to simple_backtrace. PC is the program |
| 121 | + counter. This should return 0 to continue tracing. */ |
| 122 | + |
| 123 | +typedef int (*backtrace_simple_callback) (void *data, uintptr_t pc); |
| 124 | + |
| 125 | +/* Get a simple backtrace. SKIP is the number of frames to skip, as |
| 126 | + in backtrace. DATA is passed to the callback routine. If any call |
| 127 | + to CALLBACK returns a non-zero value, the stack backtrace stops, |
| 128 | + and backtrace_simple returns that value. Otherwise |
| 129 | + backtrace_simple returns 0. The backtrace_simple function will |
| 130 | + make at least one call to either CALLBACK or ERROR_CALLBACK. This |
| 131 | + function does not require any debug info for the executable. */ |
| 132 | + |
| 133 | +extern int backtrace_simple (struct backtrace_state *state, int skip, |
| 134 | + backtrace_simple_callback callback, |
| 135 | + backtrace_error_callback error_callback, |
| 136 | + void *data); |
| 137 | + |
| 138 | +/* Print the current backtrace in a user readable format to a FILE. |
| 139 | + SKIP is the number of frames to skip, as in backtrace_full. Any |
| 140 | + error messages are printed to stderr. This function requires debug |
| 141 | + info for the executable. */ |
| 142 | + |
| 143 | +extern void backtrace_print (struct backtrace_state *state, int skip, FILE *); |
| 144 | + |
| 145 | +/* Given PC, a program counter in the current program, call the |
| 146 | + callback function with filename, line number, and function name |
| 147 | + information. This will normally call the callback function exactly |
| 148 | + once. However, if the PC happens to describe an inlined call, and |
| 149 | + the debugging information contains the necessary information, then |
| 150 | + this may call the callback function multiple times. This will make |
| 151 | + at least one call to either CALLBACK or ERROR_CALLBACK. This |
| 152 | + returns the first non-zero value returned by CALLBACK, or 0. */ |
| 153 | + |
| 154 | +extern int backtrace_pcinfo (struct backtrace_state *state, uintptr_t pc, |
| 155 | + backtrace_full_callback callback, |
| 156 | + backtrace_error_callback error_callback, |
| 157 | + void *data); |
| 158 | + |
| 159 | +/* The type of the callback argument to backtrace_syminfo. DATA and |
| 160 | + PC are the arguments passed to backtrace_syminfo. SYMNAME is the |
| 161 | + name of the symbol for the corresponding code. SYMVAL is the |
| 162 | + value and SYMSIZE is the size of the symbol. SYMNAME will be NULL |
| 163 | + if no error occurred but the symbol could not be found. */ |
| 164 | + |
| 165 | +typedef void (*backtrace_syminfo_callback) (void *data, uintptr_t pc, |
| 166 | + const char *symname, |
| 167 | + uintptr_t symval, |
| 168 | + uintptr_t symsize); |
| 169 | + |
| 170 | +/* Given ADDR, an address or program counter in the current program, |
| 171 | + call the callback information with the symbol name and value |
| 172 | + describing the function or variable in which ADDR may be found. |
| 173 | + This will call either CALLBACK or ERROR_CALLBACK exactly once. |
| 174 | + This returns 1 on success, 0 on failure. This function requires |
| 175 | + the symbol table but does not require the debug info. Note that if |
| 176 | + the symbol table is present but ADDR could not be found in the |
| 177 | + table, CALLBACK will be called with a NULL SYMNAME argument. |
| 178 | + Returns 1 on success, 0 on error. */ |
| 179 | + |
| 180 | +extern int backtrace_syminfo (struct backtrace_state *state, uintptr_t addr, |
| 181 | + backtrace_syminfo_callback callback, |
| 182 | + backtrace_error_callback error_callback, |
| 183 | + void *data); |
| 184 | + |
| 185 | +#ifdef __cplusplus |
| 186 | +} /* End extern "C". */ |
| 187 | +#endif |
| 188 | + |
| 189 | +#endif |
0 commit comments