|
111
|
1 /* backtrace.h -- Public header file for stack backtrace library.
|
|
145
|
2 Copyright (C) 2012-2020 Free Software Foundation, Inc.
|
|
111
|
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 <stdio.h>
|
|
|
38
|
|
|
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
|
|
|
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
|
|
|
92 use appropriate atomic operations. If THREADED is zero the state
|
|
|
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
|
|
131
|
95 call the ERROR_CALLBACK routine.
|
|
|
96
|
|
145
|
97 Calling this function allocates resources that cannot be freed.
|
|
131
|
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. */
|
|
111
|
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
|
|
|
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. */
|
|
|
180
|
|
|
181 typedef void (*backtrace_syminfo_callback) (void *data, uintptr_t pc,
|
|
|
182 const char *symname,
|
|
|
183 uintptr_t symval,
|
|
|
184 uintptr_t symsize);
|
|
|
185
|
|
|
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,
|
|
|
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
|
