|
Functions having to do with error reporting/handling. More...
Files | |
file | error.h |
Low-level fatal error reporting. | |
file | stackTrace.h |
Architecture-specific call-stack tracing routines. | |
file | symbols.h |
Architecture-specific symbol lookup routines. | |
Macros | |
#define | ARCH_ERROR(msg) |
Unconditionally aborts the program. | |
#define | ARCH_WARNING(msg) |
Prints a warning message to stderr. | |
#define | ARCH_AXIOM(cond) |
Aborts the program if cond evaluates to false. | |
Typedefs | |
typedef std::function< std::string(uintptr_t address)> | ArchStackTraceCallback |
A callback to get a symbolic representation of an address. | |
typedef void(* | ArchCrashHandlerSystemCB) (void *userData) |
Callback for handling crashes. | |
Functions | |
ARCH_API void | ArchLogFatalProcessState (const char *reason, const char *message=nullptr, const char *extraLogMsg=nullptr) |
Dumps call-stack info to a file, prints a message to the terminal, and invokes crash handling script. | |
ARCH_API void | ArchLogCurrentProcessState (const char *reason, const char *message=nullptr, const char *extraLogMsg=nullptr) |
Dumps call-stack info to a file, and prints an informative message. | |
ARCH_API void | ArchSetProcessStateLogCommand (const char *command, const char *const argv[], const char *const fatalArgv[]) |
Sets command line that gets call-stack info and triggers crash handling script. | |
ARCH_API bool | ArchIsAppCrashing () |
Returns true if the fatal signal handler ArchLogFatalProcessState has been invoked. | |
ARCH_API void | ArchLogSessionInfo (const char *crashStackTrace=NULL) |
Log session info. | |
ARCH_API void | ArchSetLogSession (const char *command, const char *const argv[], const char *const crashArgv[]) |
Sets the command line to log sessions. | |
ARCH_API void | ArchEnableSessionLogging () |
Register the callback to invoke logging at end of a successful session. | |
ARCH_API void | ArchPrintStackTrace (FILE *fout, const std::string &programName, const std::string &reason) |
Print a stack trace to the given FILE pointer. | |
ARCH_API void | ArchPrintStackTrace (FILE *fout, const std::string &reason) |
Print a stack trace to the given FILE pointer. | |
ARCH_API void | ArchPrintStackTrace (std::ostream &out, const std::string &programName, const std::string &reason) |
Print a stack trace to the given ostream. | |
ARCH_API void | ArchPrintStackTrace (std::ostream &out, const std::string &reason) |
Print a stack trace to the given ostream. | |
ARCH_API void | ArchSetStackTraceCallback (const ArchStackTraceCallback &cb) |
Sets a callback to get a symbolic representation of an address. | |
ARCH_API void | ArchGetStackTraceCallback (ArchStackTraceCallback *cb) |
Returns the callback to get a symbolic representation of an address. | |
ARCH_API time_t | ArchGetAppLaunchTime () |
Returns the set value for the application's launch time. | |
ARCH_API void | ArchSetFatalStackLogging (bool flag) |
Enables or disables the automatic logging of crash information. | |
ARCH_API bool | ArchGetFatalStackLogging () |
Returns whether automatic logging of fatal crashes is enabled This is set to false by default. | |
ARCH_API void | ArchSetProgramNameForErrors (const char *progName) |
Sets the program name to be used in diagnostic output. | |
ARCH_API const char * | ArchGetProgramNameForErrors () |
Returns the currently set program name for reporting errors. | |
ARCH_API void | ArchSetProgramInfoForErrors (const std::string &key, const std::string &value) |
Sets additional program info to be reported to the terminal in case of a fatal error. | |
ARCH_API std::string | ArchGetProgramInfoForErrors (const std::string &key) |
Returns currently set program info. | |
ARCH_API void | ArchSetExtraLogInfoForErrors (const std::string &key, std::vector< std::string > const *lines) |
Stores (or removes if lines is nullptr) a pointer to additional log data that will be output in the stack trace log in case of a fatal error. | |
ARCH_API void | ArchLogStackTrace (const std::string &progName, const std::string &reason, bool fatal=false, const std::string &sessionLog="") |
Logs a stack trace to a file in /var/tmp. | |
ARCH_API void | ArchLogStackTrace (const std::string &reason, bool fatal=false, const std::string &sessionLog="") |
Logs a stack trace to a file in /var/tmp. | |
ARCH_API std::vector< std::string > | ArchGetStackTrace (size_t maxDepth) |
Return stack trace. | |
ARCH_API void | ArchGetStackFrames (size_t maxDepth, std::vector< uintptr_t > *frames) |
Save frames of current stack. | |
ARCH_API size_t | ArchGetStackFrames (size_t maxDepth, uintptr_t *frames) |
Store at most maxDepth frames of the current stack into frames . | |
ARCH_API void | ArchGetStackFrames (size_t maxDepth, size_t numFramesToSkipAtTop, std::vector< uintptr_t > *frames) |
Save frames of current stack. | |
ARCH_API size_t | ArchGetStackFrames (size_t maxDepth, size_t numFramesToSkipAtTop, uintptr_t *frames) |
Store at most maxDepth frames of the current stack into frames , skipping the first numFramesToSkipAtTop frames. | |
ARCH_API void | ArchPrintStackFrames (std::ostream &out, const std::vector< uintptr_t > &frames, bool skipUnknownFrames=false) |
Print stack frames to the given ostream. | |
ARCH_API int | ArchCrashHandlerSystemv (const char *pathname, char *const argv[], int timeout, ArchCrashHandlerSystemCB callback, void *userData) |
Replacement for 'system' safe for a crash handler. | |
ARCH_API bool | ArchGetAddressInfo (void *address, std::string *objectPath, void **baseAddress, std::string *symbolName, void **symbolAddress) |
Returns information about the address address in the running program. | |
Functions having to do with error reporting/handling.
#define ARCH_AXIOM | ( | cond | ) |
#define ARCH_ERROR | ( | msg | ) |
#define ARCH_WARNING | ( | msg | ) |
typedef void(* ArchCrashHandlerSystemCB) (void *userData) |
Callback for handling crashes.
Definition at line 317 of file stackTrace.h.
typedef std::function<std::string(uintptr_t address)> ArchStackTraceCallback |
A callback to get a symbolic representation of an address.
Definition at line 174 of file stackTrace.h.
ARCH_API int ArchCrashHandlerSystemv | ( | const char * | pathname, |
char *const | argv[], | ||
int | timeout, | ||
ArchCrashHandlerSystemCB | callback, | ||
void * | userData | ||
) |
Replacement for 'system' safe for a crash handler.
This function is a substitute for system() which does not allocate or free any data, and times out after timeout
seconds if the operation in argv
is not complete. Unlike system, it takes the full pathname
of the program to run, and won't search the path. Also unlike system, argv
[] are the separated arguments, starting with the program's name, as for execv. callback
is called every second. userData
is passed to callback
. callback
can be used, for example, to print a '.' repeatedly to show progress. The alarm used in this function could interfere with setitimer or other calls to alarm, and this function uses non-locking fork and exec if available so should not generally be used except following a catastrophe.
ARCH_API void ArchEnableSessionLogging | ( | ) |
Register the callback to invoke logging at end of a successful session.
This function registers ArchLogSessionInfo() and records the current timestamp, to send up-time to the DB upon exiting.
ARCH_API bool ArchGetAddressInfo | ( | void * | address, |
std::string * | objectPath, | ||
void ** | baseAddress, | ||
std::string * | symbolName, | ||
void ** | symbolAddress | ||
) |
Returns information about the address address
in the running program.
Returns false
if no information can be found, otherwise returns true
and modifies the other arguments: objectPath
is set to the absolute path to the executable or library the address is found in, baseAddress
is the address where that object is loaded, symbolName
is the symbolic name of the thing containing the address, and symbolAddress
is the starting address of that thing. If no thing is found to contain the address then symbolName
is cleared and symbolAddress
is set to NULL
. Any of the arguments except address
can be NULL
if the result isn't needed. This will return false
if NULL
is passed to address
.
ARCH_API time_t ArchGetAppLaunchTime | ( | ) |
Returns the set value for the application's launch time.
The timestamp for this value is set when the arch library is initialized.
ARCH_API bool ArchGetFatalStackLogging | ( | ) |
Returns whether automatic logging of fatal crashes is enabled This is set to false by default.
ARCH_API std::string ArchGetProgramInfoForErrors | ( | const std::string & | key | ) |
Returns currently set program info.
ARCH_API const char * ArchGetProgramNameForErrors | ( | ) |
Returns the currently set program name for reporting errors.
Defaults to ArchGetExecutablePath().
ARCH_API void ArchGetStackFrames | ( | size_t | maxDepth, |
size_t | numFramesToSkipAtTop, | ||
std::vector< uintptr_t > * | frames | ||
) |
Save frames of current stack.
This function saves at maximum maxDepth
frames of the current stack into the vector frames
, skipping the first numFramesToSkipAtTop
frames. The first frame will be at depth numFramesToSkipAtTop
and the last at depth numFramesToSkipAtTop
+ maxDepth
- 1.
ARCH_API size_t ArchGetStackFrames | ( | size_t | maxDepth, |
size_t | numFramesToSkipAtTop, | ||
uintptr_t * | frames | ||
) |
Store at most maxDepth
frames of the current stack into frames
, skipping the first numFramesToSkipAtTop
frames.
Return the number of stack frames written to frames
.
ARCH_API void ArchGetStackFrames | ( | size_t | maxDepth, |
std::vector< uintptr_t > * | frames | ||
) |
Save frames of current stack.
This function saves at maximum maxDepth
frames of the current stack into the vector frames
.
ARCH_API size_t ArchGetStackFrames | ( | size_t | maxDepth, |
uintptr_t * | frames | ||
) |
Store at most maxDepth
frames of the current stack into frames
.
Return the number of stack frames written to frames
.
ARCH_API std::vector< std::string > ArchGetStackTrace | ( | size_t | maxDepth | ) |
Return stack trace.
This function will return a vector of strings containing the current stack. The vector will be of maximum size maxDepth
.
ARCH_API void ArchGetStackTraceCallback | ( | ArchStackTraceCallback * | cb | ) |
Returns the callback to get a symbolic representation of an address.
ARCH_API bool ArchIsAppCrashing | ( | ) |
Returns true if the fatal signal handler ArchLogFatalProcessState has been invoked.
ARCH_API void ArchLogCurrentProcessState | ( | const char * | reason, |
const char * | message = nullptr , |
||
const char * | extraLogMsg = nullptr |
||
) |
Dumps call-stack info to a file, and prints an informative message.
The reason for the trace should be supplied in reason
. An additional message may be provided in message
. If reason
is NULL
then this function only writes message
to the banner (if any).
This function is nearly identical to ArchLogFatalProcessState, including calling an external program. However, it is intended for cases that may simulate or require the output info from a full fatal crash, but are not truly fatal errors. For cases where that is not necessary, using ArchPrintStackTrace()
or other related functions would be much faster.
Note the use of char*
as opposed to string:
this is intentional, because we are trying to use only async-safe function from here on and malloc() is not async-safe.
ARCH_API void ArchLogFatalProcessState | ( | const char * | reason, |
const char * | message = nullptr , |
||
const char * | extraLogMsg = nullptr |
||
) |
Dumps call-stack info to a file, prints a message to the terminal, and invokes crash handling script.
The reason for the trace should be supplied in reason
. An additional message may be provided in message
. If reason
is NULL
then this function only writes message
to the banner (if any).
This routine can be slow and is intended to be called for a fatal error, such as a caught coredump signal. While it can theoretically be called at any time, ArchLogCurrentProcessState()
should be used for nonfatal cases.
This function is implemented by calling an external program. This is suitable for times where the current process may be corrupted. In other cases, using ArchPrintStackTrace()
or other related functions would be much faster.
Note the use of char*
as opposed to string:
this is intentional, because we are trying to use only async-safe function from here on and malloc() is not async-safe.
ARCH_API void ArchLogSessionInfo | ( | const char * | crashStackTrace = NULL | ) |
Log session info.
Optionally indicate that this is due to a crash by providing the path to a file containing a stack trace in crashStackTrace
.
ARCH_API void ArchLogStackTrace | ( | const std::string & | progName, |
const std::string & | reason, | ||
bool | fatal = false , |
||
const std::string & | sessionLog = "" |
||
) |
Logs a stack trace to a file in /var/tmp.
This function is similar to ArchLogPostMortem()
, but will not fork an external process and only reports a stack trace. A file in /var/tmp is created with the name st_APPNAME.XXXXXX
, where mktemp
is used to make a unique extension for the file. If sessionLog
is specified, then it will be appended to this file. A message is printed to stderr
reporting that a stack trace has been taken and what file it has been written to. And if fatal
is true, then the stack trace will be added to the stack_trace database table.
ARCH_API void ArchLogStackTrace | ( | const std::string & | reason, |
bool | fatal = false , |
||
const std::string & | sessionLog = "" |
||
) |
Logs a stack trace to a file in /var/tmp.
This function is similar to ArchLogPostMortem()
, but will not fork an external process and only reports a stack trace. A file in /var/tmp is created with the name st_APPNAME.XXXXXX
, where mktemp
is used to make a unique extension for the file. If sessionLog
is specified, then it will be appended to this file. A message is printed to stderr
reporting that a stack trace has been taken and what file it has been written to. And if fatal
is true, then the stack trace will be added to the stack_trace database table.
ARCH_API void ArchPrintStackFrames | ( | std::ostream & | out, |
const std::vector< uintptr_t > & | frames, | ||
bool | skipUnknownFrames = false |
||
) |
Print stack frames to the given ostream.
ARCH_API void ArchPrintStackTrace | ( | FILE * | fout, |
const std::string & | programName, | ||
const std::string & | reason | ||
) |
Print a stack trace to the given FILE pointer.
ARCH_API void ArchPrintStackTrace | ( | FILE * | fout, |
const std::string & | reason | ||
) |
Print a stack trace to the given FILE pointer.
This function uses ArchGetProgramInfoForErrors as the programName
. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
ARCH_API void ArchPrintStackTrace | ( | std::ostream & | out, |
const std::string & | programName, | ||
const std::string & | reason | ||
) |
Print a stack trace to the given ostream.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
ARCH_API void ArchPrintStackTrace | ( | std::ostream & | out, |
const std::string & | reason | ||
) |
Print a stack trace to the given ostream.
This function uses ArchGetProgramInfoForErrors as the programName
. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
ARCH_API void ArchSetExtraLogInfoForErrors | ( | const std::string & | key, |
std::vector< std::string > const * | lines | ||
) |
Stores (or removes if lines
is nullptr) a pointer to additional log data that will be output in the stack trace log in case of a fatal error.
Note that the pointer lines
is copied, not the pointed-to data. In addition, Arch might read the data pointed to by lines
concurrently at any time. Thus it is the caller's responsibility to ensure that lines
is both valid and not mutated until replacing or removing it by invoking this function again with the same key
and different lines
.
ARCH_API void ArchSetFatalStackLogging | ( | bool | flag | ) |
Enables or disables the automatic logging of crash information.
This function controls whether the stack trace and build information is automatically caught and stored to an internal database when a fatal crash occurs.
ARCH_API void ArchSetLogSession | ( | const char * | command, |
const char *const | argv[], | ||
const char *const | crashArgv[] | ||
) |
Sets the command line to log sessions.
This function sets the command line to execute to log session info. argv
is used if no crash stack trace is provided, otherwise crashArgv
is used. Both must be NULL terminated. If command
or argv
is NULL then non-crashes are not logged; if command
or crashArgv
is NULL then crashes are not logged. If not NULL then argv[0] and crashArgv[0] must be full path to the program to execute, typically command
or "$cmd" as described below.
command
, argv
, and crashArgv
are not copied and must remain valid until the next call to ArchSetLogSession
.
Simple substitution is supported on argv elements:
ARCH_API void ArchSetProcessStateLogCommand | ( | const char * | command, |
const char *const | argv[], | ||
const char *const | fatalArgv[] | ||
) |
Sets command line that gets call-stack info and triggers crash handling script.
This function sets the command line to execute to gather and log call-stack info. argv
must be NULL terminated. If command
and/or argv
(or fatalArgv
in the case of a fatal crash) are NULL, then the command will not be executed. Otherwise argv[0] and fatalArgv[0] must be the full path to the program to execute, typically command
or "$cmd" as described below.
command
, argv
, and fatalArgv
are not copied and must remain valid until the next call to ArchSetProcessStateLogCommand
.
Simple substitution is supported on argv elements:
ARCH_API void ArchSetProgramInfoForErrors | ( | const std::string & | key, |
const std::string & | value | ||
) |
Sets additional program info to be reported to the terminal in case of a fatal error.
ARCH_API void ArchSetProgramNameForErrors | ( | const char * | progName | ) |
Sets the program name to be used in diagnostic output.
The default value is initialized to ArchGetExecutablePath().
ARCH_API void ArchSetStackTraceCallback | ( | const ArchStackTraceCallback & | cb | ) |
Sets a callback to get a symbolic representation of an address.
The callback returns a string for an address in a stack trace, typically including the name of the function containing the address. cb
may be NULL
to use a default implementation.