You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
188 lines
8.5 KiB
188 lines
8.5 KiB
/* backtrace.h -- Public header file for stack backtrace library. |
|
Copyright (C) 2012-2020 Free Software Foundation, Inc. |
|
Written by Ian Lance Taylor, Google. |
|
|
|
Redistribution and use in source and binary forms, with or without |
|
modification, are permitted provided that the following conditions are |
|
met: |
|
|
|
(1) Redistributions of source code must retain the above copyright |
|
notice, this list of conditions and the following disclaimer. |
|
|
|
(2) Redistributions in binary form must reproduce the above copyright |
|
notice, this list of conditions and the following disclaimer in |
|
the documentation and/or other materials provided with the |
|
distribution. |
|
|
|
(3) The name of the author may not be used to |
|
endorse or promote products derived from this software without |
|
specific prior written permission. |
|
|
|
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR |
|
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED |
|
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE |
|
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, |
|
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES |
|
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR |
|
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
|
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, |
|
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING |
|
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
|
POSSIBILITY OF SUCH DAMAGE. */ |
|
|
|
#ifndef BACKTRACE_H |
|
#define BACKTRACE_H |
|
|
|
#include <stddef.h> |
|
#include <stdint.h> |
|
#include <stdio.h> |
|
|
|
#ifdef __cplusplus |
|
extern "C" { |
|
#endif |
|
|
|
/* The backtrace state. This struct is intentionally not defined in |
|
the public interface. */ |
|
|
|
struct backtrace_state; |
|
|
|
/* The type of the error callback argument to backtrace functions. |
|
This function, if not NULL, will be called for certain error cases. |
|
The DATA argument is passed to the function that calls this one. |
|
The MSG argument is an error message. The ERRNUM argument, if |
|
greater than 0, holds an errno value. The MSG buffer may become |
|
invalid after this function returns. |
|
|
|
As a special case, the ERRNUM argument will be passed as -1 if no |
|
debug info can be found for the executable, but the function |
|
requires debug info (e.g., backtrace_full, backtrace_pcinfo). The |
|
MSG in this case will be something along the lines of "no debug |
|
info". Similarly, ERRNUM will be passed as -1 if there is no |
|
symbol table, but the function requires a symbol table (e.g., |
|
backtrace_syminfo). This may be used as a signal that some other |
|
approach should be tried. */ |
|
|
|
typedef void (*backtrace_error_callback) (void *data, const char *msg, |
|
int errnum); |
|
|
|
/* Create state information for the backtrace routines. This must be |
|
called before any of the other routines, and its return value must |
|
be passed to all of the other routines. FILENAME is the path name |
|
of the executable file; if it is NULL the library will try |
|
system-specific path names. If not NULL, FILENAME must point to a |
|
permanent buffer. If THREADED is non-zero the state may be |
|
accessed by multiple threads simultaneously, and the library will |
|
use appropriate atomic operations. If THREADED is zero the state |
|
may only be accessed by one thread at a time. This returns a state |
|
pointer on success, NULL on error. If an error occurs, this will |
|
call the ERROR_CALLBACK routine. |
|
|
|
Calling this function allocates resources that cannot be freed. |
|
There is no backtrace_free_state function. The state is used to |
|
cache information that is expensive to recompute. Programs are |
|
expected to call this function at most once and to save the return |
|
value for all later calls to backtrace functions. */ |
|
|
|
extern struct backtrace_state *backtrace_create_state ( |
|
const char *filename, int threaded, |
|
backtrace_error_callback error_callback, void *data); |
|
|
|
/* The type of the callback argument to the backtrace_full function. |
|
DATA is the argument passed to backtrace_full. PC is the program |
|
counter. FILENAME is the name of the file containing PC, or NULL |
|
if not available. LINENO is the line number in FILENAME containing |
|
PC, or 0 if not available. FUNCTION is the name of the function |
|
containing PC, or NULL if not available. This should return 0 to |
|
continuing tracing. The FILENAME and FUNCTION buffers may become |
|
invalid after this function returns. */ |
|
|
|
typedef int (*backtrace_full_callback) (void *data, uintptr_t pc, |
|
const char *filename, int lineno, |
|
const char *function); |
|
|
|
/* Get a full stack backtrace. SKIP is the number of frames to skip; |
|
passing 0 will start the trace with the function calling |
|
backtrace_full. DATA is passed to the callback routine. If any |
|
call to CALLBACK returns a non-zero value, the stack backtrace |
|
stops, and backtrace returns that value; this may be used to limit |
|
the number of stack frames desired. If all calls to CALLBACK |
|
return 0, backtrace returns 0. The backtrace_full function will |
|
make at least one call to either CALLBACK or ERROR_CALLBACK. This |
|
function requires debug info for the executable. */ |
|
|
|
extern int backtrace_full (struct backtrace_state *state, int skip, |
|
backtrace_full_callback callback, |
|
backtrace_error_callback error_callback, |
|
void *data); |
|
|
|
/* The type of the callback argument to the backtrace_simple function. |
|
DATA is the argument passed to simple_backtrace. PC is the program |
|
counter. This should return 0 to continue tracing. */ |
|
|
|
typedef int (*backtrace_simple_callback) (void *data, uintptr_t pc); |
|
|
|
/* Get a simple backtrace. SKIP is the number of frames to skip, as |
|
in backtrace. DATA is passed to the callback routine. If any call |
|
to CALLBACK returns a non-zero value, the stack backtrace stops, |
|
and backtrace_simple returns that value. Otherwise |
|
backtrace_simple returns 0. The backtrace_simple function will |
|
make at least one call to either CALLBACK or ERROR_CALLBACK. This |
|
function does not require any debug info for the executable. */ |
|
|
|
extern int backtrace_simple (struct backtrace_state *state, int skip, |
|
backtrace_simple_callback callback, |
|
backtrace_error_callback error_callback, |
|
void *data); |
|
|
|
/* Print the current backtrace in a user readable format to a FILE. |
|
SKIP is the number of frames to skip, as in backtrace_full. Any |
|
error messages are printed to stderr. This function requires debug |
|
info for the executable. */ |
|
|
|
extern void backtrace_print (struct backtrace_state *state, int skip, FILE *); |
|
|
|
/* Given PC, a program counter in the current program, call the |
|
callback function with filename, line number, and function name |
|
information. This will normally call the callback function exactly |
|
once. However, if the PC happens to describe an inlined call, and |
|
the debugging information contains the necessary information, then |
|
this may call the callback function multiple times. This will make |
|
at least one call to either CALLBACK or ERROR_CALLBACK. This |
|
returns the first non-zero value returned by CALLBACK, or 0. */ |
|
|
|
extern int backtrace_pcinfo (struct backtrace_state *state, uintptr_t pc, |
|
backtrace_full_callback callback, |
|
backtrace_error_callback error_callback, |
|
void *data); |
|
|
|
/* The type of the callback argument to backtrace_syminfo. DATA and |
|
PC are the arguments passed to backtrace_syminfo. SYMNAME is the |
|
name of the symbol for the corresponding code. SYMVAL is the |
|
value and SYMSIZE is the size of the symbol. SYMNAME will be NULL |
|
if no error occurred but the symbol could not be found. */ |
|
|
|
typedef void (*backtrace_syminfo_callback) (void *data, uintptr_t pc, |
|
const char *symname, |
|
uintptr_t symval, |
|
uintptr_t symsize); |
|
|
|
/* Given ADDR, an address or program counter in the current program, |
|
call the callback information with the symbol name and value |
|
describing the function or variable in which ADDR may be found. |
|
This will call either CALLBACK or ERROR_CALLBACK exactly once. |
|
This returns 1 on success, 0 on failure. This function requires |
|
the symbol table but does not require the debug info. Note that if |
|
the symbol table is present but ADDR could not be found in the |
|
table, CALLBACK will be called with a NULL SYMNAME argument. |
|
Returns 1 on success, 0 on error. */ |
|
|
|
extern int backtrace_syminfo (struct backtrace_state *state, uintptr_t addr, |
|
backtrace_syminfo_callback callback, |
|
backtrace_error_callback error_callback, |
|
void *data); |
|
|
|
#ifdef __cplusplus |
|
} /* End extern "C". */ |
|
#endif |
|
|
|
#endif
|
|
|