xref: /netbsd-src/external/gpl3/gcc.old/dist/libbacktrace/backtrace.h (revision 8feb0f0b7eaff0608f8350bbfa3098827b4bb91b)
1 /* backtrace.h -- Public header file for stack backtrace library.
2    Copyright (C) 2012-2020 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    Calling this function allocates resources that cannot be freed.
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.  */
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
206