All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
stackTrace.h
Go to the documentation of this file.
1//
2// Copyright 2016 Pixar
3//
4// Licensed under the terms set forth in the LICENSE.txt file available at
5// https://openusd.org/license.
6//
7#ifndef PXR_BASE_ARCH_STACK_TRACE_H
8#define PXR_BASE_ARCH_STACK_TRACE_H
9
13
14#include "pxr/pxr.h"
15#include "pxr/base/arch/api.h"
16#include "pxr/base/arch/defines.h"
17
18#include <inttypes.h>
19#include <stdio.h>
20#include <functional>
21#include <vector>
22#include <string>
23#include <iosfwd>
24#include <ctime>
25
26PXR_NAMESPACE_OPEN_SCOPE
27
30
50ARCH_API
51void ArchLogFatalProcessState(const char* reason,
52 const char* message = nullptr,
53 const char* extraLogMsg = nullptr);
54
71ARCH_API
72void ArchLogCurrentProcessState(const char* reason,
73 const char* message = nullptr,
74 const char* extraLogMsg = nullptr);
75
97ARCH_API
98void ArchSetProcessStateLogCommand(const char* command,
99 const char *const argv[],
100 const char* const fatalArgv[]);
101
104ARCH_API
106
112ARCH_API
113void ArchLogSessionInfo(const char *crashStackTrace=NULL);
114
136ARCH_API
137void ArchSetLogSession(const char* command,
138 const char* const argv[],
139 const char* const crashArgv[]);
140
145ARCH_API
147
149ARCH_API
150void ArchPrintStackTrace(FILE *fout,
151 const std::string& programName,
152 const std::string& reason);
153
157ARCH_API
158void ArchPrintStackTrace(FILE *fout, const std::string& reason);
159
162ARCH_API
163void ArchPrintStackTrace(std::ostream& out,
164 const std::string& programName,
165 const std::string& reason);
166
170ARCH_API
171void ArchPrintStackTrace(std::ostream& out, const std::string& reason);
172
174typedef std::function<std::string(uintptr_t address)> ArchStackTraceCallback;
175
181ARCH_API
183
186ARCH_API
188
191ARCH_API
193
199ARCH_API
201
205ARCH_API
207
211ARCH_API
212void ArchSetProgramNameForErrors(const char * progName);
213
216ARCH_API
218
221ARCH_API
222void ArchSetProgramInfoForErrors( const std::string& key, const std::string& value );
223
226ARCH_API
227std::string ArchGetProgramInfoForErrors(const std::string& key);
228
236ARCH_API
237void ArchSetExtraLogInfoForErrors(const std::string &key,
238 std::vector<std::string> const *lines);
239
250ARCH_API
251void ArchLogStackTrace(const std::string& progName,
252 const std::string& reason,
253 bool fatal = false,
254 const std::string& sessionLog = "");
255
266ARCH_API
267void ArchLogStackTrace(const std::string& reason,
268 bool fatal = false,
269 const std::string& sessionLog = "");
270
275ARCH_API
276std::vector<std::string> ArchGetStackTrace(size_t maxDepth);
277
278
283ARCH_API
284void ArchGetStackFrames(size_t maxDepth, std::vector<uintptr_t> *frames);
285
288ARCH_API
289size_t ArchGetStackFrames(size_t maxDepth, uintptr_t *frames);
290
297ARCH_API
298void ArchGetStackFrames(size_t maxDepth, size_t numFramesToSkipAtTop,
299 std::vector<uintptr_t> *frames);
300
304ARCH_API
305size_t ArchGetStackFrames(size_t maxDepth, size_t numFramesToSkipAtTop,
306 uintptr_t *frames);
307
308
310ARCH_API
311void ArchPrintStackFrames(std::ostream& out,
312 const std::vector<uintptr_t> &frames,
313 bool skipUnknownFrames = false);
314
317typedef void (*ArchCrashHandlerSystemCB)(void* userData);
318
332ARCH_API
333int ArchCrashHandlerSystemv(const char* pathname, char *const argv[],
334 int timeout, ArchCrashHandlerSystemCB callback,
335 void* userData);
336
337#if defined(ARCH_OS_DARWIN)
338// macOS has no ETIME. ECANCELED seems to have about the closest meaning to
339// the actual error here. The operation is timing out, not being explicitly
340// canceled, but it is canceled.
341#ifndef ETIME
342#define ETIME ECANCELED
343#endif // end ETIME
344#endif // end ARCH_OS_DARWIN
345
347
348PXR_NAMESPACE_CLOSE_SCOPE
349
350#endif // PXR_BASE_ARCH_STACK_TRACE_H
ARCH_API void ArchGetStackFrames(size_t maxDepth, std::vector< uintptr_t > *frames)
Save frames of current stack.
ARCH_API void ArchSetFatalStackLogging(bool flag)
Enables or disables the automatic logging of crash information.
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 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 ArchEnableSessionLogging()
Register the callback to invoke logging at end of a successful session.
ARCH_API time_t ArchGetAppLaunchTime()
Returns the set value for the application's launch time.
ARCH_API std::string ArchGetProgramInfoForErrors(const std::string &key)
Returns currently set program info.
ARCH_API std::vector< std::string > ArchGetStackTrace(size_t maxDepth)
Return stack trace.
ARCH_API void ArchGetStackTraceCallback(ArchStackTraceCallback *cb)
Returns the callback to get a symbolic representation of an address.
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 ArchPrintStackFrames(std::ostream &out, const std::vector< uintptr_t > &frames, bool skipUnknownFrames=false)
Print stack frames to the given ostream.
ARCH_API bool ArchGetFatalStackLogging()
Returns whether automatic logging of fatal crashes is enabled This is set to false by default.
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 ArchSetStackTraceCallback(const ArchStackTraceCallback &cb)
Sets a callback to get a symbolic representation of an address.
std::function< std::string(uintptr_t address)> ArchStackTraceCallback
A callback to get a symbolic representation of an address.
Definition: stackTrace.h:174
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 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 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 s...
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 ArchSetProgramNameForErrors(const char *progName)
Sets the program name to be used in diagnostic output.
ARCH_API bool ArchIsAppCrashing()
Returns true if the fatal signal handler ArchLogFatalProcessState has been invoked.
ARCH_API const char * ArchGetProgramNameForErrors()
Returns the currently set program name for reporting errors.
ARCH_API void ArchLogSessionInfo(const char *crashStackTrace=NULL)
Log session info.
void(* ArchCrashHandlerSystemCB)(void *userData)
Callback for handling crashes.
Definition: stackTrace.h:317
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.
Define integral types.