Files
file	error.h

file	stackTrace.h

file	symbols.h

Macros
#define	ARCH_ERROR(msg)

#define	ARCH_WARNING(msg)

#define	ARCH_AXIOM(cond)

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)

Functions
ARCH_API void	ArchLogFatalProcessState (const char reason, const char message=nullptr, const char *extraLogMsg=nullptr)

ARCH_API void	ArchLogCurrentProcessState (const char reason, const char message=nullptr, const char *extraLogMsg=nullptr)

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

ARCH_API bool	ArchIsAppCrashing ()

ARCH_API void	ArchLogSessionInfo (const char *crashStackTrace=NULL)

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

ARCH_API void	ArchEnableSessionLogging ()

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)

ARCH_API void	ArchPrintStackTrace (std::ostream &out, const std::string &programName, const std::string &reason)

ARCH_API void	ArchPrintStackTrace (std::ostream &out, const std::string &reason)

ARCH_API void	ArchSetStackTraceCallback (const ArchStackTraceCallback &cb)

ARCH_API void	ArchGetStackTraceCallback (ArchStackTraceCallback *cb)

ARCH_API time_t	ArchGetAppLaunchTime ()

ARCH_API void	ArchSetFatalStackLogging (bool flag)

ARCH_API bool	ArchGetFatalStackLogging ()

ARCH_API void	ArchSetProgramNameForErrors (const char *progName)

ARCH_API const char *	ArchGetProgramNameForErrors ()

ARCH_API void	ArchSetProgramInfoForErrors (const std::string &key, const std::string &value)

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

ARCH_API void	ArchSetExtraLogInfoForErrors (const std::string &key, std::vector< std::string > const *lines)

ARCH_API void	ArchLogStackTrace (const std::string &progName, const std::string &reason, bool fatal=false, const std::string &sessionLog="")

ARCH_API void	ArchLogStackTrace (const std::string &reason, bool fatal=false, const std::string &sessionLog="")

ARCH_API std::vector< std::string >	ArchGetStackTrace (size_t maxDepth)

ARCH_API void	ArchGetStackFrames (size_t maxDepth, std::vector< uintptr_t > *frames)

ARCH_API size_t	ArchGetStackFrames (size_t maxDepth, uintptr_t *frames)

ARCH_API void	ArchGetStackFrames (size_t maxDepth, size_t numFramesToSkipAtTop, std::vector< uintptr_t > *frames)

ARCH_API size_t	ArchGetStackFrames (size_t maxDepth, size_t numFramesToSkipAtTop, uintptr_t *frames)

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

ARCH_API int	ArchCrashHandlerSystemv (const char pathname, char const argv[], int timeout, ArchCrashHandlerSystemCB callback, void *userData)

PXR_NAMESPACE_OPEN_SCOPE ARCH_API bool	ArchGetAddressInfo (void address, std::string objectPath, void *baseAddress, std::string symbolName, void **symbolAddress)

Detailed Description

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

PXR_NAMESPACE_OPEN_SCOPE 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 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 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 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 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:

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

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