]>
Commit | Line | Data |
---|---|---|
eff02e4f | 1 | /* backtrace.h -- Public header file for stack backtrace library. |
8d9254fc | 2 | Copyright (C) 2012-2020 Free Software Foundation, Inc. |
eff02e4f ILT |
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 | |
84ebf639 | 10 | notice, this list of conditions and the following disclaimer. |
eff02e4f ILT |
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 | |
84ebf639 CL |
15 | distribution. |
16 | ||
eff02e4f ILT |
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> | |
eff02e4f ILT |
37 | #include <stdio.h> |
38 | ||
76850556 RO |
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 | ||
eff02e4f ILT |
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 | |
25e6253e | 92 | use appropriate atomic operations. If THREADED is zero the state |
eff02e4f ILT |
93 | may only be accessed by one thread at a time. This returns a state |
94 | pointer on success, NULL on error. If an error occurs, this will | |
a2a86641 ILT |
95 | call the ERROR_CALLBACK routine. |
96 | ||
67914693 | 97 | Calling this function allocates resources that cannot be freed. |
a2a86641 ILT |
98 | There is no backtrace_free_state function. The state is used to |
99 | cache information that is expensive to recompute. Programs are | |
100 | expected to call this function at most once and to save the return | |
101 | value for all later calls to backtrace functions. */ | |
eff02e4f ILT |
102 | |
103 | extern struct backtrace_state *backtrace_create_state ( | |
104 | const char *filename, int threaded, | |
105 | backtrace_error_callback error_callback, void *data); | |
106 | ||
107 | /* The type of the callback argument to the backtrace_full function. | |
108 | DATA is the argument passed to backtrace_full. PC is the program | |
109 | counter. FILENAME is the name of the file containing PC, or NULL | |
110 | if not available. LINENO is the line number in FILENAME containing | |
111 | PC, or 0 if not available. FUNCTION is the name of the function | |
112 | containing PC, or NULL if not available. This should return 0 to | |
113 | continuing tracing. The FILENAME and FUNCTION buffers may become | |
114 | invalid after this function returns. */ | |
115 | ||
116 | typedef int (*backtrace_full_callback) (void *data, uintptr_t pc, | |
117 | const char *filename, int lineno, | |
118 | const char *function); | |
119 | ||
120 | /* Get a full stack backtrace. SKIP is the number of frames to skip; | |
121 | passing 0 will start the trace with the function calling | |
122 | backtrace_full. DATA is passed to the callback routine. If any | |
123 | call to CALLBACK returns a non-zero value, the stack backtrace | |
124 | stops, and backtrace returns that value; this may be used to limit | |
125 | the number of stack frames desired. If all calls to CALLBACK | |
126 | return 0, backtrace returns 0. The backtrace_full function will | |
127 | make at least one call to either CALLBACK or ERROR_CALLBACK. This | |
128 | function requires debug info for the executable. */ | |
129 | ||
130 | extern int backtrace_full (struct backtrace_state *state, int skip, | |
131 | backtrace_full_callback callback, | |
132 | backtrace_error_callback error_callback, | |
133 | void *data); | |
134 | ||
135 | /* The type of the callback argument to the backtrace_simple function. | |
136 | DATA is the argument passed to simple_backtrace. PC is the program | |
137 | counter. This should return 0 to continue tracing. */ | |
138 | ||
139 | typedef int (*backtrace_simple_callback) (void *data, uintptr_t pc); | |
140 | ||
141 | /* Get a simple backtrace. SKIP is the number of frames to skip, as | |
142 | in backtrace. DATA is passed to the callback routine. If any call | |
143 | to CALLBACK returns a non-zero value, the stack backtrace stops, | |
144 | and backtrace_simple returns that value. Otherwise | |
145 | backtrace_simple returns 0. The backtrace_simple function will | |
146 | make at least one call to either CALLBACK or ERROR_CALLBACK. This | |
147 | function does not require any debug info for the executable. */ | |
148 | ||
149 | extern int backtrace_simple (struct backtrace_state *state, int skip, | |
150 | backtrace_simple_callback callback, | |
151 | backtrace_error_callback error_callback, | |
152 | void *data); | |
153 | ||
154 | /* Print the current backtrace in a user readable format to a FILE. | |
155 | SKIP is the number of frames to skip, as in backtrace_full. Any | |
156 | error messages are printed to stderr. This function requires debug | |
157 | info for the executable. */ | |
158 | ||
159 | extern void backtrace_print (struct backtrace_state *state, int skip, FILE *); | |
160 | ||
161 | /* Given PC, a program counter in the current program, call the | |
162 | callback function with filename, line number, and function name | |
163 | information. This will normally call the callback function exactly | |
164 | once. However, if the PC happens to describe an inlined call, and | |
165 | the debugging information contains the necessary information, then | |
166 | this may call the callback function multiple times. This will make | |
167 | at least one call to either CALLBACK or ERROR_CALLBACK. This | |
168 | returns the first non-zero value returned by CALLBACK, or 0. */ | |
169 | ||
170 | extern int backtrace_pcinfo (struct backtrace_state *state, uintptr_t pc, | |
171 | backtrace_full_callback callback, | |
172 | backtrace_error_callback error_callback, | |
173 | void *data); | |
174 | ||
175 | /* The type of the callback argument to backtrace_syminfo. DATA and | |
176 | PC are the arguments passed to backtrace_syminfo. SYMNAME is the | |
177 | name of the symbol for the corresponding code. SYMVAL is the | |
1f96a712 JJ |
178 | value and SYMSIZE is the size of the symbol. SYMNAME will be NULL |
179 | if no error occurred but the symbol could not be found. */ | |
eff02e4f ILT |
180 | |
181 | typedef void (*backtrace_syminfo_callback) (void *data, uintptr_t pc, | |
182 | const char *symname, | |
1f96a712 JJ |
183 | uintptr_t symval, |
184 | uintptr_t symsize); | |
eff02e4f | 185 | |
cfa658e4 ILT |
186 | /* Given ADDR, an address or program counter in the current program, |
187 | call the callback information with the symbol name and value | |
188 | describing the function or variable in which ADDR may be found. | |
189 | This will call either CALLBACK or ERROR_CALLBACK exactly once. | |
190 | This returns 1 on success, 0 on failure. This function requires | |
191 | the symbol table but does not require the debug info. Note that if | |
192 | the symbol table is present but ADDR could not be found in the | |
193 | table, CALLBACK will be called with a NULL SYMNAME argument. | |
194 | Returns 1 on success, 0 on error. */ | |
195 | ||
196 | extern int backtrace_syminfo (struct backtrace_state *state, uintptr_t addr, | |
eff02e4f ILT |
197 | backtrace_syminfo_callback callback, |
198 | backtrace_error_callback error_callback, | |
199 | void *data); | |
200 | ||
201 | #ifdef __cplusplus | |
202 | } /* End extern "C". */ | |
203 | #endif | |
204 | ||
205 | #endif |