1 | /* backtrace.h -- Public header file for stack backtrace library. |
2 | Copyright (C) 2012-2021 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 |
190 | |