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