Loading...
Searching...
No Matches
stackTrace.h
Go to the documentation of this file.
1//
2// Copyright 2016 Pixar
3//
4// Licensed under the Apache License, Version 2.0 (the "Apache License")
5// with the following modification; you may not use this file except in
6// compliance with the Apache License and the following modification to it:
7// Section 6. Trademarks. is deleted and replaced with:
8//
9// 6. Trademarks. This License does not grant permission to use the trade
10// names, trademarks, service marks, or product names of the Licensor
11// and its affiliates, except as required to comply with Section 4(c) of
12// the License and to reproduce the content of the NOTICE file.
13//
14// You may obtain a copy of the Apache License at
15//
16// http://www.apache.org/licenses/LICENSE-2.0
17//
18// Unless required by applicable law or agreed to in writing, software
19// distributed under the Apache License with the above modification is
20// distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21// KIND, either express or implied. See the Apache License for the specific
22// language governing permissions and limitations under the Apache License.
23//
24#ifndef PXR_BASE_ARCH_STACK_TRACE_H
25#define PXR_BASE_ARCH_STACK_TRACE_H
26
30
31#include "pxr/pxr.h"
32#include "pxr/base/arch/api.h"
33#include "pxr/base/arch/defines.h"
34
35#include <inttypes.h>
36#include <stdio.h>
37#include <functional>
38#include <vector>
39#include <string>
40#include <iosfwd>
41#include <ctime>
42
43PXR_NAMESPACE_OPEN_SCOPE
44
47
67ARCH_API
68void ArchLogFatalProcessState(const char* reason,
69 const char* message = nullptr,
70 const char* extraLogMsg = nullptr);
71
88ARCH_API
89void ArchLogCurrentProcessState(const char* reason,
90 const char* message = nullptr,
91 const char* extraLogMsg = nullptr);
92
114ARCH_API
115void ArchSetProcessStateLogCommand(const char* command,
116 const char *const argv[],
117 const char* const fatalArgv[]);
118
121ARCH_API
123
129ARCH_API
130void ArchLogSessionInfo(const char *crashStackTrace=NULL);
131
153ARCH_API
154void ArchSetLogSession(const char* command,
155 const char* const argv[],
156 const char* const crashArgv[]);
157
162ARCH_API
164
166ARCH_API
167void ArchPrintStackTrace(FILE *fout,
168 const std::string& programName,
169 const std::string& reason);
170
174ARCH_API
175void ArchPrintStackTrace(FILE *fout, const std::string& reason);
176
179ARCH_API
180void ArchPrintStackTrace(std::ostream& out,
181 const std::string& programName,
182 const std::string& reason);
183
187ARCH_API
188void ArchPrintStackTrace(std::ostream& out, const std::string& reason);
189
191typedef std::function<std::string(uintptr_t address)> ArchStackTraceCallback;
192
198ARCH_API
200
203ARCH_API
205
208ARCH_API
210
216ARCH_API
218
222ARCH_API
224
228ARCH_API
229void ArchSetProgramNameForErrors(const char * progName);
230
233ARCH_API
235
238ARCH_API
239void ArchSetProgramInfoForErrors( const std::string& key, const std::string& value );
240
243ARCH_API
244std::string ArchGetProgramInfoForErrors(const std::string& key);
245
253ARCH_API
254void ArchSetExtraLogInfoForErrors(const std::string &key,
255 std::vector<std::string> const *lines);
256
267ARCH_API
268void ArchLogStackTrace(const std::string& progName,
269 const std::string& reason,
270 bool fatal = false,
271 const std::string& sessionLog = "");
272
283ARCH_API
284void ArchLogStackTrace(const std::string& reason,
285 bool fatal = false,
286 const std::string& sessionLog = "");
287
292ARCH_API
293std::vector<std::string> ArchGetStackTrace(size_t maxDepth);
294
295
300ARCH_API
301void ArchGetStackFrames(size_t maxDepth, std::vector<uintptr_t> *frames);
302
305ARCH_API
306size_t ArchGetStackFrames(size_t maxDepth, uintptr_t *frames);
307
314ARCH_API
315void ArchGetStackFrames(size_t maxDepth, size_t numFramesToSkipAtTop,
316 std::vector<uintptr_t> *frames);
317
321ARCH_API
322size_t ArchGetStackFrames(size_t maxDepth, size_t numFramesToSkipAtTop,
323 uintptr_t *frames);
324
325
327ARCH_API
328void ArchPrintStackFrames(std::ostream& out,
329 const std::vector<uintptr_t> &frames,
330 bool skipUnknownFrames = false);
331
334typedef void (*ArchCrashHandlerSystemCB)(void* userData);
335
349ARCH_API
350int ArchCrashHandlerSystemv(const char* pathname, char *const argv[],
351 int timeout, ArchCrashHandlerSystemCB callback,
352 void* userData);
353
354#if defined(ARCH_OS_DARWIN)
355// macOS has no ETIME. ECANCELED seems to have about the closest meaning to
356// the actual error here. The operation is timing out, not being explicitly
357// canceled, but it is canceled.
358#ifndef ETIME
359#define ETIME ECANCELED
360#endif // end ETIME
361#endif // end ARCH_OS_DARWIN
362
364
365PXR_NAMESPACE_CLOSE_SCOPE
366
367#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:191
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:334
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.