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