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 LLVM_ABI 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 LLVM_ABI void 39 EnablePrettyStackTraceOnSigInfoForThisThread(bool ShouldEnable = true); 40 41 /// Replaces the generic bug report message that is output upon 42 /// a crash. 43 LLVM_ABI void setBugReportMsg(const char *Msg); 44 45 /// Get the bug report message that will be output upon a crash. 46 LLVM_ABI const char *getBugReportMsg(); 47 48 /// PrettyStackTraceEntry - This class is used to represent a frame of the 49 /// "pretty" stack trace that is dumped when a program crashes. You can define 50 /// subclasses of this and declare them on the program stack: when they are 51 /// constructed and destructed, they will add their symbolic frames to a 52 /// virtual stack trace. This gets dumped out if the program crashes. 53 class LLVM_ABI PrettyStackTraceEntry { 54 LLVM_ABI friend PrettyStackTraceEntry * 55 ReverseStackTrace(PrettyStackTraceEntry *); 56 57 PrettyStackTraceEntry *NextEntry; 58 PrettyStackTraceEntry(const PrettyStackTraceEntry &) = delete; 59 void operator=(const PrettyStackTraceEntry &) = delete; 60 public: 61 PrettyStackTraceEntry(); 62 virtual ~PrettyStackTraceEntry(); 63 64 /// print - Emit information about this stack frame to OS. 65 virtual void print(raw_ostream &OS) const = 0; 66 67 /// getNextEntry - Return the next entry in the list of frames. getNextEntry()68 const PrettyStackTraceEntry *getNextEntry() const { return NextEntry; } 69 }; 70 71 /// PrettyStackTraceString - This object prints a specified string (which 72 /// should not contain newlines) to the stream as the stack trace when a crash 73 /// occurs. 74 class LLVM_ABI PrettyStackTraceString : public PrettyStackTraceEntry { 75 const char *Str; 76 public: PrettyStackTraceString(const char * str)77 PrettyStackTraceString(const char *str) : Str(str) {} 78 void print(raw_ostream &OS) const override; 79 }; 80 81 /// PrettyStackTraceFormat - This object prints a string (which may use 82 /// printf-style formatting but should not contain newlines) to the stream 83 /// as the stack trace when a crash occurs. 84 class LLVM_ABI PrettyStackTraceFormat : public PrettyStackTraceEntry { 85 llvm::SmallVector<char, 32> Str; 86 public: 87 PrettyStackTraceFormat(const char *Format, ...); 88 void print(raw_ostream &OS) const override; 89 }; 90 91 /// PrettyStackTraceProgram - This object prints a specified program arguments 92 /// to the stream as the stack trace when a crash occurs. 93 class LLVM_ABI PrettyStackTraceProgram : public PrettyStackTraceEntry { 94 int ArgC; 95 const char *const *ArgV; 96 public: PrettyStackTraceProgram(int argc,const char * const * argv)97 PrettyStackTraceProgram(int argc, const char * const*argv) 98 : ArgC(argc), ArgV(argv) { 99 EnablePrettyStackTrace(); 100 } 101 void print(raw_ostream &OS) const override; 102 }; 103 104 /// Returns the topmost element of the "pretty" stack state. 105 LLVM_ABI const void *SavePrettyStackState(); 106 107 /// Restores the topmost element of the "pretty" stack state to State, which 108 /// should come from a previous call to SavePrettyStackState(). This is 109 /// useful when using a CrashRecoveryContext in code that also uses 110 /// PrettyStackTraceEntries, to make sure the stack that's printed if a crash 111 /// happens after a crash that's been recovered by CrashRecoveryContext 112 /// doesn't have frames on it that were added in code unwound by the 113 /// CrashRecoveryContext. 114 LLVM_ABI void RestorePrettyStackState(const void *State); 115 116 } // end namespace llvm 117 118 #endif 119