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. More...

#define	ARCH_WARNING(msg)
	Prints a warning message to stderr. More...

#define	ARCH_AXIOM(cond)
	Aborts the program if `cond` evaluates to false. More...

Typedefs
typedef std::function < std::string(uintptr_t address)>	ArchStackTraceCallback
	A callback to get a symbolic representation of an address. More...

typedef void(*	ArchCrashHandlerSystemCB )(void *userData)
	Callback for handling crashes. More...

Functions
ARCH_API void	ArchLogPostMortem (const char reason, const char message=nullptr, const char *extraLogMsg=nullptr)
	Dumps call-stack info to a file, and prints an informative message. More...

ARCH_API void	ArchSetPostMortem (const char command, const char const argv[])
	Sets the command line that gathers call-stack info. More...

ARCH_API void	ArchLogSessionInfo (const char *crashStackTrace=NULL)
	Log session info. More...

ARCH_API void	ArchSetLogSession (const char command, const char const argv[], const char *const crashArgv[])
	Sets the command line to log sessions. More...

ARCH_API void	ArchEnableSessionLogging ()
	Register the callback to invoke logging at end of a successful session. More...

ARCH_API void	ArchPrintStackTrace (FILE *fout, const std::string &programName, const std::string &reason)
	Print a stack trace to the given FILE pointer. More...

ARCH_API void	ArchPrintStackTrace (FILE *fout, const std::string &reason)
	Print a stack trace to the given FILE pointer. More...

ARCH_API void	ArchPrintStackTrace (std::ostream &out, const std::string &programName, const std::string &reason)
	Print a stack trace to the given ostream. More...

ARCH_API void	ArchPrintStackTrace (std::ostream &out, const std::string &reason)
	Print a stack trace to the given ostream. More...

ARCH_API void	ArchSetStackTraceCallback (const ArchStackTraceCallback &cb)
	Sets a callback to get a symbolic representation of an address. More...

ARCH_API void	ArchGetStackTraceCallback (ArchStackTraceCallback *cb)
	Returns the callback to get a symbolic representation of an address. More...

ARCH_API time_t	ArchGetAppLaunchTime ()
	Returns the set value for the application's launch time. More...

ARCH_API void	ArchSetFatalStackLogging (bool flag)
	Enables or disables the automatic logging of crash information. More...

ARCH_API bool	ArchGetFatalStackLogging ()
	Returns whether automatic logging of fatal crashes is enabled This is set to false by default. More...

ARCH_API void	ArchSetProgramNameForErrors (const char *progName)
	Sets the program name to be used in diagnostic output. More...

ARCH_API const char *	ArchGetProgramNameForErrors ()
	Returns the currently set program name for reporting errors. More...

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. More...

ARCH_API std::string	ArchGetProgramInfoForErrors (const std::string &key)
	Returns currently set program info. More...

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. More...

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. More...

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. More...

ARCH_API std::vector< std::string >	ArchGetStackTrace (size_t maxDepth)
	Return stack trace. More...

ARCH_API void	ArchGetStackFrames (size_t maxDepth, std::vector< uintptr_t > *frames)
	Save frames of current stack. More...

ARCH_API void	ArchGetStackFrames (size_t maxDepth, size_t numFramesToSkipAtTop, std::vector< uintptr_t > *frames)
	Save frames of current stack. More...

ARCH_API void	ArchPrintStackFrames (std::ostream &out, const std::vector< uintptr_t > &frames)
	Print stack frames to the given ostream. More...

ARCH_API int	ArchCrashHandlerSystemv (const char pathname, char const argv[], int timeout, ArchCrashHandlerSystemCB callback, void *userData)
	Replacement for 'system' safe for a crash handler. More...

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. More...

Detailed Description

Functions having to do with error reporting/handling.

Macro Definition Documentation

#define ARCH_AXIOM ( cond )

Aborts the program if cond evaluates to false.

Definition at line 85 of file error.h.

#define ARCH_ERROR ( msg )

Unconditionally aborts the program.

Parameters

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

Definition at line 72 of file error.h.

#define ARCH_WARNING ( msg )

Prints a warning message to stderr.

Parameters

msg	is a literal string, a `const` `char*` (but not an `std::string`).

Definition at line 80 of file error.h.

Typedef Documentation

typedef void(* ArchCrashHandlerSystemCB)(void *userData)

Callback for handling crashes.

See Also: ArchCrashHandlerSystemv

Definition at line 287 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 158 of file stackTrace.h.

Function Documentation

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.

See Also: ArchSetFatalStackLogging

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

Returns currently set program info.

See Also: ArchSetExtraLogInfoForErrors

ARCH_API const char* ArchGetProgramNameForErrors ( )

Returns the currently set program name for reporting errors.

Defaults to ArchGetExecutablePath().

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 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 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.

See Also: ArchSetStackTraceCallback

ARCH_API void ArchLogPostMortem	(	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. This routine can be slow and is intended to be called for a fatal error, such as a caught coredump signal, but may be called at any time. 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 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
	)

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:

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

ARCH_API void ArchSetPostMortem	(	const char *	command,
		const char *const	argv[]
	)

Sets the command line that gathers call-stack info.

This function sets the command line to execute to gather and log call-stack info. argv must be NULL terminated. command and/or argv may be NULL to suppress execution. Otherwise argv[0] must be the full path to the program to execute, typically command or "$cmd" as described below.

command and argv are not copied and must remain valid until the next call to ArchSetPostMortem.

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)

See Also: ArchLogPostMortem

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.

Files

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation