1/* backtrace.h -- Public header file for stack backtrace library.
2   Copyright (C) 2012-2015 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 <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
58extern "C" {
59#endif
60
61/* The backtrace state.  This struct is intentionally not defined in
62   the public interface.  */
63
64struct 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
82typedef 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
97extern 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
110typedef 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
124extern 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
133typedef 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
143extern 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
153extern 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
164extern 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
175typedef 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
190extern 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
200