|
HDK
|
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) |
| #define ARCH_AXIOM | ( | cond | ) |
| #define ARCH_ERROR | ( | msg | ) |
| #define ARCH_WARNING | ( | msg | ) |
Callback for handling crashes.
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.
| 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.
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.
| ARCH_API std::string ArchGetProgramInfoForErrors | ( | const std::string & | key | ) |
Returns currently set program info.
Returns the currently set program name for reporting errors. Defaults to ArchGetExecutablePath().
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.
| 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.
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.
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.
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.
1.8.6 
