1 //===- llvm/Support/PrettyStackTrace.h - Pretty Crash Handling --*- C++ -*-===//
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 //===----------------------------------------------------------------------===//
9 // This file defines the PrettyStackTraceEntry class, which is used to make
10 // crashes give more contextual information about what the program was doing
13 //===----------------------------------------------------------------------===//
15 #ifndef LLVM_SUPPORT_PRETTYSTACKTRACE_H
16 #define LLVM_SUPPORT_PRETTYSTACKTRACE_H
18 #include "llvm/ADT/SmallVector.h"
19 #include "llvm/Support/Compiler.h"
24 /// Enables dumping a "pretty" stack trace when the program crashes.
26 /// \see PrettyStackTraceEntry
27 void EnablePrettyStackTrace();
29 /// Enables (or disables) dumping a "pretty" stack trace when the user sends
30 /// SIGINFO or SIGUSR1 to the current process.
32 /// This is a per-thread decision so that a program can choose to print stack
33 /// traces only on a primary thread, or on all threads that use
34 /// PrettyStackTraceEntry.
36 /// \see EnablePrettyStackTrace
37 /// \see PrettyStackTraceEntry
38 void EnablePrettyStackTraceOnSigInfoForThisThread(bool ShouldEnable
= true);
40 /// PrettyStackTraceEntry - This class is used to represent a frame of the
41 /// "pretty" stack trace that is dumped when a program crashes. You can define
42 /// subclasses of this and declare them on the program stack: when they are
43 /// constructed and destructed, they will add their symbolic frames to a
44 /// virtual stack trace. This gets dumped out if the program crashes.
45 class PrettyStackTraceEntry
{
46 friend PrettyStackTraceEntry
*ReverseStackTrace(PrettyStackTraceEntry
*);
48 PrettyStackTraceEntry
*NextEntry
;
49 PrettyStackTraceEntry(const PrettyStackTraceEntry
&) = delete;
50 void operator=(const PrettyStackTraceEntry
&) = delete;
52 PrettyStackTraceEntry();
53 virtual ~PrettyStackTraceEntry();
55 /// print - Emit information about this stack frame to OS.
56 virtual void print(raw_ostream
&OS
) const = 0;
58 /// getNextEntry - Return the next entry in the list of frames.
59 const PrettyStackTraceEntry
*getNextEntry() const { return NextEntry
; }
62 /// PrettyStackTraceString - This object prints a specified string (which
63 /// should not contain newlines) to the stream as the stack trace when a crash
65 class PrettyStackTraceString
: public PrettyStackTraceEntry
{
68 PrettyStackTraceString(const char *str
) : Str(str
) {}
69 void print(raw_ostream
&OS
) const override
;
72 /// PrettyStackTraceFormat - This object prints a string (which may use
73 /// printf-style formatting but should not contain newlines) to the stream
74 /// as the stack trace when a crash occurs.
75 class PrettyStackTraceFormat
: public PrettyStackTraceEntry
{
76 llvm::SmallVector
<char, 32> Str
;
78 PrettyStackTraceFormat(const char *Format
, ...);
79 void print(raw_ostream
&OS
) const override
;
82 /// PrettyStackTraceProgram - This object prints a specified program arguments
83 /// to the stream as the stack trace when a crash occurs.
84 class PrettyStackTraceProgram
: public PrettyStackTraceEntry
{
86 const char *const *ArgV
;
88 PrettyStackTraceProgram(int argc
, const char * const*argv
)
89 : ArgC(argc
), ArgV(argv
) {
90 EnablePrettyStackTrace();
92 void print(raw_ostream
&OS
) const override
;
95 /// Returns the topmost element of the "pretty" stack state.
96 const void *SavePrettyStackState();
98 /// Restores the topmost element of the "pretty" stack state to State, which
99 /// should come from a previous call to SavePrettyStackState(). This is
100 /// useful when using a CrashRecoveryContext in code that also uses
101 /// PrettyStackTraceEntries, to make sure the stack that's printed if a crash
102 /// happens after a crash that's been recovered by CrashRecoveryContext
103 /// doesn't have frames on it that were added in code unwound by the
104 /// CrashRecoveryContext.
105 void RestorePrettyStackState(const void *State
);
107 } // end namespace llvm