All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
Diagnostics

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.
 

Detailed Description

Functions having to do with error reporting/handling.

Macro Definition Documentation

◆ ARCH_AXIOM

#define ARCH_AXIOM (   cond)

Aborts the program if cond evaluates to false.

Definition at line 68 of file error.h.

◆ ARCH_ERROR

#define ARCH_ERROR (   msg)

Unconditionally aborts the program.

Parameters
msgis a literal string, a const char* (but not an std::string) that describes why the program is aborting.

Definition at line 55 of file error.h.

◆ ARCH_WARNING

#define ARCH_WARNING (   msg)

Prints a warning message to stderr.

Parameters
msgis a literal string, a const char* (but not an std::string).

Definition at line 63 of file error.h.

Typedef Documentation

◆ ArchCrashHandlerSystemCB

typedef void(* ArchCrashHandlerSystemCB) (void *userData)

Callback for handling crashes.

See also
ArchCrashHandlerSystemv

Definition at line 317 of file stackTrace.h.

◆ ArchStackTraceCallback

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.

Function Documentation

◆ ArchCrashHandlerSystemv()

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.

◆ ArchEnableSessionLogging()

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.

◆ ArchGetAddressInfo()

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.

◆ ArchGetAppLaunchTime()

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.

◆ ArchGetFatalStackLogging()

ARCH_API bool ArchGetFatalStackLogging ( )

Returns whether automatic logging of fatal crashes is enabled This is set to false by default.

See also
ArchSetFatalStackLogging

◆ ArchGetProgramInfoForErrors()

ARCH_API std::string ArchGetProgramInfoForErrors ( const std::string &  key)

Returns currently set program info.

See also
ArchSetExtraLogInfoForErrors

◆ ArchGetProgramNameForErrors()

ARCH_API const char * ArchGetProgramNameForErrors ( )

Returns the currently set program name for reporting errors.

Defaults to ArchGetExecutablePath().

◆ ArchGetStackFrames() [1/4]

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.

◆ ArchGetStackFrames() [2/4]

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.

◆ ArchGetStackFrames() [3/4]

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.

◆ ArchGetStackFrames() [4/4]

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.

◆ ArchGetStackTrace()

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.

◆ ArchGetStackTraceCallback()

ARCH_API void ArchGetStackTraceCallback ( ArchStackTraceCallback cb)

Returns the callback to get a symbolic representation of an address.

See also
ArchSetStackTraceCallback

◆ ArchIsAppCrashing()

ARCH_API bool ArchIsAppCrashing ( )

Returns true if the fatal signal handler ArchLogFatalProcessState has been invoked.

◆ ArchLogCurrentProcessState()

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.

◆ ArchLogFatalProcessState()

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.

◆ ArchLogSessionInfo()

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.

◆ ArchLogStackTrace() [1/2]

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.

◆ ArchLogStackTrace() [2/2]

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.

◆ ArchPrintStackFrames()

ARCH_API void ArchPrintStackFrames ( std::ostream &  out,
const std::vector< uintptr_t > &  frames,
bool  skipUnknownFrames = false 
)

Print stack frames to the given ostream.

◆ ArchPrintStackTrace() [1/4]

ARCH_API void ArchPrintStackTrace ( FILE *  fout,
const std::string &  programName,
const std::string &  reason 
)

Print a stack trace to the given FILE pointer.

◆ ArchPrintStackTrace() [2/4]

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.

◆ ArchPrintStackTrace() [3/4]

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.

◆ ArchPrintStackTrace() [4/4]

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.

◆ ArchSetExtraLogInfoForErrors()

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.

◆ ArchSetFatalStackLogging()

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.

◆ ArchSetLogSession()

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:

  • $cmd: Substitutes the command pathname, or $ARCH_LOGSESSION if set
  • $prog Substitutes the program name
  • $pid: Substitutes the process id
  • $time: Substitutes the user time (if available, else wall time)
  • $stack: Substitutes the crash stack string (only in crashArgv)
See also
ArchLogSessionInfo

◆ ArchSetProcessStateLogCommand()

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:

  • $cmd: Substitutes the command pathname, or $ARCH_POSTMORTEM if set
  • $pid: Substitutes the process id
  • $log: Substitutes the log pathname
  • $time: Substitutes the user time (if available, else wall time)
  • $reason: Substitutes the reason string for the crash
See also
ArchLogFatalProcessState

◆ ArchSetProgramInfoForErrors()

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.

◆ ArchSetProgramNameForErrors()

ARCH_API void ArchSetProgramNameForErrors ( const char *  progName)

Sets the program name to be used in diagnostic output.

The default value is initialized to ArchGetExecutablePath().

◆ ArchSetStackTraceCallback()

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.