/* backtrace.h -- Public header file for stack backtrace library.
- Copyright (C) 2012-2013 Free Software Foundation, Inc.
+ Copyright (C) 2012-2024 Free Software Foundation, Inc.
Written by Ian Lance Taylor, Google.
Redistribution and use in source and binary forms, with or without
met:
(1) Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
+ 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.
-
+ 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.
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. */
+ debug info can be found for the executable, or if the debug info
+ exists but has an unsupported version, 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);
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. */
+ 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,
/* 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. SYMNAME will be NULL if no error occurred but the symbol
- could not be found. */
+ 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 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