llvm/Support/PrettyStackTrace.h

0001 //===- llvm/Support/PrettyStackTrace.h - Pretty Crash Handling --*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008 //
0009 // This file defines the PrettyStackTraceEntry class, which is used to make
0010 // crashes give more contextual information about what the program was doing
0011 // when it crashed.
0012 //
0013 //===----------------------------------------------------------------------===//
0014
0015 #ifndef LLVM_SUPPORT_PRETTYSTACKTRACE_H
0016 #define LLVM_SUPPORT_PRETTYSTACKTRACE_H
0017
0018 #include "llvm/ADT/SmallVector.h"
0019 #include "llvm/Support/Compiler.h"
0020
0021 namespace llvm {
0022   class raw_ostream;
0023
0024   /// Enables dumping a "pretty" stack trace when the program crashes.
0025   ///
0026   /// \see PrettyStackTraceEntry
0027   void EnablePrettyStackTrace();
0028
0029   /// Enables (or disables) dumping a "pretty" stack trace when the user sends
0030   /// SIGINFO or SIGUSR1 to the current process.
0031   ///
0032   /// This is a per-thread decision so that a program can choose to print stack
0033   /// traces only on a primary thread, or on all threads that use
0034   /// PrettyStackTraceEntry.
0035   ///
0036   /// \see EnablePrettyStackTrace
0037   /// \see PrettyStackTraceEntry
0038   void EnablePrettyStackTraceOnSigInfoForThisThread(bool ShouldEnable = true);
0039
0040   /// Replaces the generic bug report message that is output upon
0041   /// a crash.
0042   void setBugReportMsg(const char *Msg);
0043
0044   /// Get the bug report message that will be output upon a crash.
0045   const char *getBugReportMsg();
0046
0047   /// PrettyStackTraceEntry - This class is used to represent a frame of the
0048   /// "pretty" stack trace that is dumped when a program crashes. You can define
0049   /// subclasses of this and declare them on the program stack: when they are
0050   /// constructed and destructed, they will add their symbolic frames to a
0051   /// virtual stack trace.  This gets dumped out if the program crashes.
0052   class PrettyStackTraceEntry {
0053     friend PrettyStackTraceEntry *ReverseStackTrace(PrettyStackTraceEntry *);
0054
0055     PrettyStackTraceEntry *NextEntry;
0056     PrettyStackTraceEntry(const PrettyStackTraceEntry &) = delete;
0057     void operator=(const PrettyStackTraceEntry &) = delete;
0058   public:
0059     PrettyStackTraceEntry();
0060     virtual ~PrettyStackTraceEntry();
0061
0062     /// print - Emit information about this stack frame to OS.
0063     virtual void print(raw_ostream &OS) const = 0;
0064
0065     /// getNextEntry - Return the next entry in the list of frames.
0066     const PrettyStackTraceEntry *getNextEntry() const { return NextEntry; }
0067   };
0068
0069   /// PrettyStackTraceString - This object prints a specified string (which
0070   /// should not contain newlines) to the stream as the stack trace when a crash
0071   /// occurs.
0072   class PrettyStackTraceString : public PrettyStackTraceEntry {
0073     const char *Str;
0074   public:
0075     PrettyStackTraceString(const char *str) : Str(str) {}
0076     void print(raw_ostream &OS) const override;
0077   };
0078
0079   /// PrettyStackTraceFormat - This object prints a string (which may use
0080   /// printf-style formatting but should not contain newlines) to the stream
0081   /// as the stack trace when a crash occurs.
0082   class PrettyStackTraceFormat : public PrettyStackTraceEntry {
0083     llvm::SmallVector<char, 32> Str;
0084   public:
0085     PrettyStackTraceFormat(const char *Format, ...);
0086     void print(raw_ostream &OS) const override;
0087   };
0088
0089   /// PrettyStackTraceProgram - This object prints a specified program arguments
0090   /// to the stream as the stack trace when a crash occurs.
0091   class PrettyStackTraceProgram : public PrettyStackTraceEntry {
0092     int ArgC;
0093     const char *const *ArgV;
0094   public:
0095     PrettyStackTraceProgram(int argc, const char * const*argv)
0096       : ArgC(argc), ArgV(argv) {
0097       EnablePrettyStackTrace();
0098     }
0099     void print(raw_ostream &OS) const override;
0100   };
0101
0102   /// Returns the topmost element of the "pretty" stack state.
0103   const void *SavePrettyStackState();
0104
0105   /// Restores the topmost element of the "pretty" stack state to State, which
0106   /// should come from a previous call to SavePrettyStackState().  This is
0107   /// useful when using a CrashRecoveryContext in code that also uses
0108   /// PrettyStackTraceEntries, to make sure the stack that's printed if a crash
0109   /// happens after a crash that's been recovered by CrashRecoveryContext
0110   /// doesn't have frames on it that were added in code unwound by the
0111   /// CrashRecoveryContext.
0112   void RestorePrettyStackState(const void *State);
0113
0114 } // end namespace llvm
0115
0116 #endif