1 //===- llvm/Support/Signals.h - Signal Handling support ---------*- 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 some helpful functions for dealing with the possibility of 10 // unix signals occurring while your program is running. 11 // 12 //===----------------------------------------------------------------------===// 13 14 #ifndef LLVM_SUPPORT_SIGNALS_H 15 #define LLVM_SUPPORT_SIGNALS_H 16 17 #include "llvm/Config/llvm-config.h" 18 #include "llvm/Support/Compiler.h" 19 #include <cstdint> 20 #include <string> 21 22 #if LLVM_ENABLE_DEBUGLOC_TRACKING_ORIGIN 23 #include "llvm/ADT/DenseMap.h" 24 #include "llvm/ADT/DenseSet.h" 25 #include "llvm/ADT/SmallVector.h" 26 namespace llvm { 27 // Typedefs that are convenient but only used by the stack-trace-collection code 28 // added if DebugLoc origin-tracking is enabled. 29 using AddressSet = DenseSet<void *>; 30 using SymbolizedAddressMap = DenseMap<void *, SmallVector<std::string, 0>>; 31 } // namespace llvm 32 #endif 33 34 namespace llvm { 35 class StringRef; 36 class raw_ostream; 37 38 namespace sys { 39 40 /// This function runs all the registered interrupt handlers, including the 41 /// removal of files registered by RemoveFileOnSignal. 42 LLVM_ABI void RunInterruptHandlers(); 43 44 /// This function registers signal handlers to ensure that if a signal gets 45 /// delivered that the named file is removed. 46 /// Remove a file if a fatal signal occurs. 47 LLVM_ABI bool RemoveFileOnSignal(StringRef Filename, 48 std::string *ErrMsg = nullptr); 49 50 /// This function removes a file from the list of files to be removed on 51 /// signal delivery. 52 LLVM_ABI void DontRemoveFileOnSignal(StringRef Filename); 53 54 /// When an error signal (such as SIGABRT or SIGSEGV) is delivered to the 55 /// process, print a stack trace and then exit. 56 /// Print a stack trace if a fatal signal occurs. 57 /// \param Argv0 the current binary name, used to find the symbolizer 58 /// relative to the current binary before searching $PATH; can be 59 /// StringRef(), in which case we will only search $PATH. 60 /// \param DisableCrashReporting if \c true, disable the normal crash 61 /// reporting mechanisms on the underlying operating system. 62 LLVM_ABI void PrintStackTraceOnErrorSignal(StringRef Argv0, 63 bool DisableCrashReporting = false); 64 65 /// Disable all system dialog boxes that appear when the process crashes. 66 LLVM_ABI void DisableSystemDialogsOnCrash(); 67 68 /// Print the stack trace using the given \c raw_ostream object. 69 /// \param Depth refers to the number of stackframes to print. If not 70 /// specified, the entire frame is printed. 71 LLVM_ABI void PrintStackTrace(raw_ostream &OS, int Depth = 0); 72 73 #if LLVM_ENABLE_DEBUGLOC_TRACKING_ORIGIN 74 #ifdef NDEBUG 75 #error DebugLoc origin-tracking should not be enabled in Release builds. 76 #endif 77 /// Populates the given array with a stack trace of the current program, up to 78 /// MaxDepth frames. Returns the number of frames returned, which will be 79 /// inserted into \p StackTrace from index 0. All entries after the returned 80 /// depth will be unmodified. NB: This is only intended to be used for 81 /// introspection of LLVM by Debugify, will not be enabled in release builds, 82 /// and should not be relied on for other purposes. 83 template <unsigned long MaxDepth> 84 int getStackTrace(std::array<void *, MaxDepth> &StackTrace); 85 86 /// Takes a set of \p Addresses, symbolizes them and stores the result in the 87 /// provided \p SymbolizedAddresses map. 88 /// NB: This is only intended to be used for introspection of LLVM by 89 /// Debugify, will not be enabled in release builds, and should not be relied 90 /// on for other purposes. 91 void symbolizeAddresses(AddressSet &Addresses, 92 SymbolizedAddressMap &SymbolizedAddresses); 93 #endif 94 95 // Run all registered signal handlers. 96 LLVM_ABI void RunSignalHandlers(); 97 98 using SignalHandlerCallback = void (*)(void *); 99 100 /// Add a function to be called when an abort/kill signal is delivered to the 101 /// process. The handler can have a cookie passed to it to identify what 102 /// instance of the handler it is. 103 LLVM_ABI void AddSignalHandler(SignalHandlerCallback FnPtr, void *Cookie); 104 105 /// This function registers a function to be called when the user "interrupts" 106 /// the program (typically by pressing ctrl-c). When the user interrupts the 107 /// program, the specified interrupt function is called instead of the program 108 /// being killed, and the interrupt function automatically disabled. 109 /// 110 /// Note that interrupt functions are not allowed to call any non-reentrant 111 /// functions. An null interrupt function pointer disables the current 112 /// installed function. Note also that the handler may be executed on a 113 /// different thread on some platforms. 114 LLVM_ABI void SetInterruptFunction(void (*IF)()); 115 116 /// Registers a function to be called when an "info" signal is delivered to 117 /// the process. 118 /// 119 /// On POSIX systems, this will be SIGUSR1; on systems that have it, SIGINFO 120 /// will also be used (typically ctrl-t). 121 /// 122 /// Note that signal handlers are not allowed to call any non-reentrant 123 /// functions. An null function pointer disables the current installed 124 /// function. Note also that the handler may be executed on a different 125 /// thread on some platforms. 126 LLVM_ABI void SetInfoSignalFunction(void (*Handler)()); 127 128 /// Registers a function to be called in a "one-shot" manner when a pipe 129 /// signal is delivered to the process (i.e., on a failed write to a pipe). 130 /// After the pipe signal is handled once, the handler is unregistered. 131 /// 132 /// The LLVM signal handling code will not install any handler for the pipe 133 /// signal unless one is provided with this API (see \ref 134 /// DefaultOneShotPipeSignalHandler). This handler must be provided before 135 /// any other LLVM signal handlers are installed: the \ref InitLLVM 136 /// constructor has a flag that can simplify this setup. 137 /// 138 /// Note that the handler is not allowed to call any non-reentrant 139 /// functions. A null handler pointer disables the current installed 140 /// function. Note also that the handler may be executed on a 141 /// different thread on some platforms. 142 LLVM_ABI void SetOneShotPipeSignalFunction(void (*Handler)()); 143 144 /// On Unix systems and Windows, this function exits with an "IO error" exit 145 /// code. 146 LLVM_ABI void DefaultOneShotPipeSignalHandler(); 147 148 #ifdef _WIN32 149 /// Windows does not support signals and this handler must be called manually. 150 LLVM_ABI void CallOneShotPipeSignalHandler(); 151 #endif 152 153 /// This function does the following: 154 /// - clean up any temporary files registered with RemoveFileOnSignal() 155 /// - dump the callstack from the exception context 156 /// - call any relevant interrupt/signal handlers 157 /// - create a core/mini dump of the exception context whenever possible 158 /// Context is a system-specific failure context: it is the signal type on 159 /// Unix; the ExceptionContext on Windows. 160 LLVM_ABI void CleanupOnSignal(uintptr_t Context); 161 162 LLVM_ABI void unregisterHandlers(); 163 } // namespace sys 164 } // namespace llvm 165 166 #endif 167