1 //===- llvm/Support/PrettyStackTrace.h - Pretty Crash Handling --*- C++ -*-===//
2 //
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
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 // This file defines the PrettyStackTraceEntry class, which is used to make
10 // crashes give more contextual information about what the program was doing
11 // when it crashed.
12 //
13 //===----------------------------------------------------------------------===//
14 
15 #ifndef LLVM_SUPPORT_PRETTYSTACKTRACE_H
16 #define LLVM_SUPPORT_PRETTYSTACKTRACE_H
17 
18 #include "llvm/ADT/SmallVector.h"
19 #include "llvm/Support/Compiler.h"
20 
21 namespace llvm {
22   class raw_ostream;
23 
24   /// Enables dumping a "pretty" stack trace when the program crashes.
25   ///
26   /// \see PrettyStackTraceEntry
27   void EnablePrettyStackTrace();
28 
29   /// Enables (or disables) dumping a "pretty" stack trace when the user sends
30   /// SIGINFO or SIGUSR1 to the current process.
31   ///
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.
35   ///
36   /// \see EnablePrettyStackTrace
37   /// \see PrettyStackTraceEntry
38   void EnablePrettyStackTraceOnSigInfoForThisThread(bool ShouldEnable = true);
39 
40   /// Replaces the generic bug report message that is output upon
41   /// a crash.
42   void setBugReportMsg(const char *Msg);
43 
44   /// Get the bug report message that will be output upon a crash.
45   const char *getBugReportMsg();
46 
47   /// PrettyStackTraceEntry - This class is used to represent a frame of the
48   /// "pretty" stack trace that is dumped when a program crashes. You can define
49   /// subclasses of this and declare them on the program stack: when they are
50   /// constructed and destructed, they will add their symbolic frames to a
51   /// virtual stack trace.  This gets dumped out if the program crashes.
52   class PrettyStackTraceEntry {
53     friend PrettyStackTraceEntry *ReverseStackTrace(PrettyStackTraceEntry *);
54 
55     PrettyStackTraceEntry *NextEntry;
56     PrettyStackTraceEntry(const PrettyStackTraceEntry &) = delete;
57     void operator=(const PrettyStackTraceEntry &) = delete;
58   public:
59     PrettyStackTraceEntry();
60     virtual ~PrettyStackTraceEntry();
61 
62     /// print - Emit information about this stack frame to OS.
63     virtual void print(raw_ostream &OS) const = 0;
64 
65     /// getNextEntry - Return the next entry in the list of frames.
66     const PrettyStackTraceEntry *getNextEntry() const { return NextEntry; }
67   };
68 
69   /// PrettyStackTraceString - This object prints a specified string (which
70   /// should not contain newlines) to the stream as the stack trace when a crash
71   /// occurs.
72   class PrettyStackTraceString : public PrettyStackTraceEntry {
73     const char *Str;
74   public:
75     PrettyStackTraceString(const char *str) : Str(str) {}
76     void print(raw_ostream &OS) const override;
77   };
78 
79   /// PrettyStackTraceFormat - This object prints a string (which may use
80   /// printf-style formatting but should not contain newlines) to the stream
81   /// as the stack trace when a crash occurs.
82   class PrettyStackTraceFormat : public PrettyStackTraceEntry {
83     llvm::SmallVector<char, 32> Str;
84   public:
85     PrettyStackTraceFormat(const char *Format, ...);
86     void print(raw_ostream &OS) const override;
87   };
88 
89   /// PrettyStackTraceProgram - This object prints a specified program arguments
90   /// to the stream as the stack trace when a crash occurs.
91   class PrettyStackTraceProgram : public PrettyStackTraceEntry {
92     int ArgC;
93     const char *const *ArgV;
94   public:
95     PrettyStackTraceProgram(int argc, const char * const*argv)
96       : ArgC(argc), ArgV(argv) {
97       EnablePrettyStackTrace();
98     }
99     void print(raw_ostream &OS) const override;
100   };
101 
102   /// Returns the topmost element of the "pretty" stack state.
103   const void *SavePrettyStackState();
104 
105   /// Restores the topmost element of the "pretty" stack state to State, which
106   /// should come from a previous call to SavePrettyStackState().  This is
107   /// useful when using a CrashRecoveryContext in code that also uses
108   /// PrettyStackTraceEntries, to make sure the stack that's printed if a crash
109   /// happens after a crash that's been recovered by CrashRecoveryContext
110   /// doesn't have frames on it that were added in code unwound by the
111   /// CrashRecoveryContext.
112   void RestorePrettyStackState(const void *State);
113 
114 } // end namespace llvm
115 
116 #endif
117