libbacktrace/backtrace.h

   1 /* backtrace.h -- Public header file for stack backtrace library.
   2    Copyright (C) 2012-2024 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, or if the debug info
  75    exists but has an unsupported version, but the function requires
  76    debug info (e.g., backtrace_full, backtrace_pcinfo).  The MSG in
  77    this case will be something along the lines of "no debug info".
  78    Similarly, ERRNUM will be passed as -1 if there is no symbol table,
  79    but the function requires a symbol table (e.g., backtrace_syminfo).
  80    This may be used as a signal that some other approach should be
  81    tried.  */
  82
  83 typedef void (*backtrace_error_callback) (void *data, const char *msg,
  84                                           int errnum);
  85
  86 /* Create state information for the backtrace routines.  This must be
  87    called before any of the other routines, and its return value must
  88    be passed to all of the other routines.  FILENAME is the path name
  89    of the executable file; if it is NULL the library will try
  90    system-specific path names.  If not NULL, FILENAME must point to a
  91    permanent buffer.  If THREADED is non-zero the state may be
  92    accessed by multiple threads simultaneously, and the library will
  93    use appropriate atomic operations.  If THREADED is zero the state
  94    may only be accessed by one thread at a time.  This returns a state
  95    pointer on success, NULL on error.  If an error occurs, this will
  96    call the ERROR_CALLBACK routine.
  97
  98    Calling this function allocates resources that cannot be freed.
  99    There is no backtrace_free_state function.  The state is used to
 100    cache information that is expensive to recompute.  Programs are
 101    expected to call this function at most once and to save the return
 102    value for all later calls to backtrace functions.  */
 103
 104 extern struct backtrace_state *backtrace_create_state (
 105     const char *filename, int threaded,
 106     backtrace_error_callback error_callback, void *data);
 107
 108 /* The type of the callback argument to the backtrace_full function.
 109    DATA is the argument passed to backtrace_full.  PC is the program
 110    counter.  FILENAME is the name of the file containing PC, or NULL
 111    if not available.  LINENO is the line number in FILENAME containing
 112    PC, or 0 if not available.  FUNCTION is the name of the function
 113    containing PC, or NULL if not available.  This should return 0 to
 114    continuing tracing.  The FILENAME and FUNCTION buffers may become
 115    invalid after this function returns.  */
 116
 117 typedef int (*backtrace_full_callback) (void *data, uintptr_t pc,
 118                                         const char *filename, int lineno,
 119                                         const char *function);
 120
 121 /* Get a full stack backtrace.  SKIP is the number of frames to skip;
 122    passing 0 will start the trace with the function calling
 123    backtrace_full.  DATA is passed to the callback routine.  If any
 124    call to CALLBACK returns a non-zero value, the stack backtrace
 125    stops, and backtrace returns that value; this may be used to limit
 126    the number of stack frames desired.  If all calls to CALLBACK
 127    return 0, backtrace returns 0.  The backtrace_full function will
 128    make at least one call to either CALLBACK or ERROR_CALLBACK.  This
 129    function requires debug info for the executable.  */
 130
 131 extern int backtrace_full (struct backtrace_state *state, int skip,
 132                            backtrace_full_callback callback,
 133                            backtrace_error_callback error_callback,
 134                            void *data);
 135
 136 /* The type of the callback argument to the backtrace_simple function.
 137    DATA is the argument passed to simple_backtrace.  PC is the program
 138    counter.  This should return 0 to continue tracing.  */
 139
 140 typedef int (*backtrace_simple_callback) (void *data, uintptr_t pc);
 141
 142 /* Get a simple backtrace.  SKIP is the number of frames to skip, as
 143    in backtrace.  DATA is passed to the callback routine.  If any call
 144    to CALLBACK returns a non-zero value, the stack backtrace stops,
 145    and backtrace_simple returns that value.  Otherwise
 146    backtrace_simple returns 0.  The backtrace_simple function will
 147    make at least one call to either CALLBACK or ERROR_CALLBACK.  This
 148    function does not require any debug info for the executable.  */
 149
 150 extern int backtrace_simple (struct backtrace_state *state, int skip,
 151                              backtrace_simple_callback callback,
 152                              backtrace_error_callback error_callback,
 153                              void *data);
 154
 155 /* Print the current backtrace in a user readable format to a FILE.
 156    SKIP is the number of frames to skip, as in backtrace_full.  Any
 157    error messages are printed to stderr.  This function requires debug
 158    info for the executable.  */
 159
 160 extern void backtrace_print (struct backtrace_state *state, int skip, FILE *);
 161
 162 /* Given PC, a program counter in the current program, call the
 163    callback function with filename, line number, and function name
 164    information.  This will normally call the callback function exactly
 165    once.  However, if the PC happens to describe an inlined call, and
 166    the debugging information contains the necessary information, then
 167    this may call the callback function multiple times.  This will make
 168    at least one call to either CALLBACK or ERROR_CALLBACK.  This
 169    returns the first non-zero value returned by CALLBACK, or 0.  */
 170
 171 extern int backtrace_pcinfo (struct backtrace_state *state, uintptr_t pc,
 172                              backtrace_full_callback callback,
 173                              backtrace_error_callback error_callback,
 174                              void *data);
 175
 176 /* The type of the callback argument to backtrace_syminfo.  DATA and
 177    PC are the arguments passed to backtrace_syminfo.  SYMNAME is the
 178    name of the symbol for the corresponding code.  SYMVAL is the
 179    value and SYMSIZE is the size of the symbol.  SYMNAME will be NULL
 180    if no error occurred but the symbol could not be found.  */
 181
 182 typedef void (*backtrace_syminfo_callback) (void *data, uintptr_t pc,
 183                                             const char *symname,
 184                                             uintptr_t symval,
 185                                             uintptr_t symsize);
 186
 187 /* Given ADDR, an address or program counter in the current program,
 188    call the callback information with the symbol name and value
 189    describing the function or variable in which ADDR may be found.
 190    This will call either CALLBACK or ERROR_CALLBACK exactly once.
 191    This returns 1 on success, 0 on failure.  This function requires
 192    the symbol table but does not require the debug info.  Note that if
 193    the symbol table is present but ADDR could not be found in the
 194    table, CALLBACK will be called with a NULL SYMNAME argument.
 195    Returns 1 on success, 0 on error.  */
 196
 197 extern int backtrace_syminfo (struct backtrace_state *state, uintptr_t addr,
 198                               backtrace_syminfo_callback callback,
 199                               backtrace_error_callback error_callback,
 200                               void *data);
 201
 202 #ifdef __cplusplus
 203 } /* End extern "C".  */
 204 #endif
 205
 206 #endif