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 
43 PXR_NAMESPACE_OPEN_SCOPE
44 
47 
64 ARCH_API
66  const char* reason,
67  const char* message = nullptr,
68  const char* extraLogMsg = nullptr);
69 
88 ARCH_API
89 void ArchSetPostMortem(const char* command, const char *const argv[]);
90 
96 ARCH_API
97 void ArchLogSessionInfo(const char *crashStackTrace=NULL);
98 
120 ARCH_API
121 void ArchSetLogSession(const char* command,
122  const char* const argv[],
123  const char* const crashArgv[]);
124 
129 ARCH_API
131 
133 ARCH_API
134 void ArchPrintStackTrace(FILE *fout,
135  const std::string& programName,
136  const std::string& reason);
137 
141 ARCH_API
142 void ArchPrintStackTrace(FILE *fout, const std::string& reason);
143 
146 ARCH_API
147 void ArchPrintStackTrace(std::ostream& out,
148  const std::string& programName,
149  const std::string& reason);
150 
154 ARCH_API
155 void ArchPrintStackTrace(std::ostream& out, const std::string& reason);
156 
158 typedef std::function<std::string(uintptr_t address)> ArchStackTraceCallback;
159 
165 ARCH_API
167 
170 ARCH_API
172 
175 ARCH_API
176 time_t ArchGetAppLaunchTime();
177 
183 ARCH_API
184 void ArchSetFatalStackLogging(bool flag);
185 
189 ARCH_API
191 
195 ARCH_API
196 void ArchSetProgramNameForErrors(const char * progName);
197 
200 ARCH_API
201 const char * ArchGetProgramNameForErrors();
202 
205 ARCH_API
206 void ArchSetProgramInfoForErrors( const std::string& key, const std::string& value );
207 
210 ARCH_API
211 std::string ArchGetProgramInfoForErrors(const std::string& key);
212 
220 ARCH_API
221 void ArchSetExtraLogInfoForErrors(const std::string &key,
222  std::vector<std::string> const *lines);
223 
234 ARCH_API
235 void ArchLogStackTrace(const std::string& progName,
236  const std::string& reason,
237  bool fatal = false,
238  const std::string& sessionLog = "");
239 
250 ARCH_API
251 void ArchLogStackTrace(const std::string& reason,
252  bool fatal = false,
253  const std::string& sessionLog = "");
254 
259 ARCH_API
260 std::vector<std::string> ArchGetStackTrace(size_t maxDepth);
261 
262 
267 ARCH_API
268 void ArchGetStackFrames(size_t maxDepth, std::vector<uintptr_t> *frames);
269 
276 ARCH_API
277 void ArchGetStackFrames(size_t maxDepth, size_t numFramesToSkipAtTop,
278  std::vector<uintptr_t> *frames);
279 
281 ARCH_API
282 void ArchPrintStackFrames(std::ostream& out,
283  const std::vector<uintptr_t> &frames,
284  bool skipUnknownFrames = false);
285 
288 typedef void (*ArchCrashHandlerSystemCB)(void* userData);
289 
303 ARCH_API
304 int ArchCrashHandlerSystemv(const char* pathname, char *const argv[],
305  int timeout, ArchCrashHandlerSystemCB callback,
306  void* userData);
307 
315 ARCH_API
316 void ArchTestCrash(bool spawnthread);
317 
318 #if defined(ARCH_OS_DARWIN)
319 // macOS has no ETIME. ECANCELED seems to have about the closest meaning to
320 // the actual error here. The operation is timing out, not being explicitly
321 // canceled, but it is canceled.
322 #ifndef ETIME
323 #define ETIME ECANCELED
324 #endif // end ETIME
325 #endif // end ARCH_OS_DARWIN
326 
328 
329 PXR_NAMESPACE_CLOSE_SCOPE
330 
331 #endif // PXR_BASE_ARCH_STACK_TRACE_H
std::function< std::string(uintptr_t address)> ArchStackTraceCallback
A callback to get a symbolic representation of an address.
Definition: stackTrace.h:158
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.
ARCH_API void ArchGetStackFrames(size_t maxDepth, std::vector< uintptr_t > *frames)
Save frames of current stack.
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 ArchSetProgramNameForErrors(const char *progName)
Sets the program name to be used in diagnostic output.
ARCH_API void ArchLogSessionInfo(const char *crashStackTrace=NULL)
Log session info.
ARCH_API void ArchPrintStackTrace(FILE *fout, const std::string &programName, const std::string &reason)
Print a stack trace to the given FILE pointer.
void(* ArchCrashHandlerSystemCB)(void *userData)
Callback for handling crashes.
Definition: stackTrace.h:288
ARCH_API void ArchSetPostMortem(const char *command, const char *const argv[])
Sets the command line that gathers call-stack info.
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 ArchSetLogSession(const char *command, const char *const argv[], const char *const crashArgv[])
Sets the command line to log sessions.
ARCH_API void ArchGetStackTraceCallback(ArchStackTraceCallback *cb)
Returns the callback to get a symbolic representation of an address.
ARCH_API void ArchSetStackTraceCallback(const ArchStackTraceCallback &cb)
Sets a callback to get a symbolic representation of an address.
ARCH_API const char * ArchGetProgramNameForErrors()
Returns the currently set program name for reporting errors.
ARCH_API bool ArchGetFatalStackLogging()
Returns whether automatic logging of fatal crashes is enabled This is set to false by default.
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.
Define integral types.
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 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 std::vector< std::string > ArchGetStackTrace(size_t maxDepth)
Return stack trace.
ARCH_API time_t ArchGetAppLaunchTime()
Returns the set value for the application's launch time.
ARCH_API void ArchEnableSessionLogging()
Register the callback to invoke logging at end of a successful session.
ARCH_API std::string ArchGetProgramInfoForErrors(const std::string &key)
Returns currently set program info.
ARCH_API void ArchSetFatalStackLogging(bool flag)
Enables or disables the automatic logging of crash information.