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
5Redistribution and use in source and binary forms, with or without
6modification, are permitted provided that the following conditions are
7met:
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
21THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
22IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
23WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
24DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
25INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
26(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
27SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
29STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
30IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
31POSSIBILITY 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
41extern "C" {
42#endif
43
44/* The backtrace state. This struct is intentionally not defined in
45 the public interface. */
46
47struct 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
66typedef 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
87extern 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
100typedef 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
114extern 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
123typedef 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
133extern 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
143extern 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
154extern 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
165typedef 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
180extern 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