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 <cstdint> 18 #include <string> 19 20 namespace llvm { 21 class StringRef; 22 class raw_ostream; 23 24 namespace sys { 25 26 /// This function runs all the registered interrupt handlers, including the 27 /// removal of files registered by RemoveFileOnSignal. 28 void RunInterruptHandlers(); 29 30 /// This function registers signal handlers to ensure that if a signal gets 31 /// delivered that the named file is removed. 32 /// Remove a file if a fatal signal occurs. 33 bool RemoveFileOnSignal(StringRef Filename, std::string* ErrMsg = nullptr); 34 35 /// This function removes a file from the list of files to be removed on 36 /// signal delivery. 37 void DontRemoveFileOnSignal(StringRef Filename); 38 39 /// When an error signal (such as SIGABRT or SIGSEGV) is delivered to the 40 /// process, print a stack trace and then exit. 41 /// Print a stack trace if a fatal signal occurs. 42 /// \param Argv0 the current binary name, used to find the symbolizer 43 /// relative to the current binary before searching $PATH; can be 44 /// StringRef(), in which case we will only search $PATH. 45 /// \param DisableCrashReporting if \c true, disable the normal crash 46 /// reporting mechanisms on the underlying operating system. 47 void PrintStackTraceOnErrorSignal(StringRef Argv0, 48 bool DisableCrashReporting = false); 49 50 /// Disable all system dialog boxes that appear when the process crashes. 51 void DisableSystemDialogsOnCrash(); 52 53 /// Print the stack trace using the given \c raw_ostream object. 54 /// \param Depth refers to the number of stackframes to print. If not 55 /// specified, the entire frame is printed. 56 void PrintStackTrace(raw_ostream &OS, int Depth = 0); 57 58 // Run all registered signal handlers. 59 void RunSignalHandlers(); 60 61 using SignalHandlerCallback = void (*)(void *); 62 63 /// Add a function to be called when an abort/kill signal is delivered to the 64 /// process. The handler can have a cookie passed to it to identify what 65 /// instance of the handler it is. 66 void AddSignalHandler(SignalHandlerCallback FnPtr, void *Cookie); 67 68 /// This function registers a function to be called when the user "interrupts" 69 /// the program (typically by pressing ctrl-c). When the user interrupts the 70 /// program, the specified interrupt function is called instead of the program 71 /// being killed, and the interrupt function automatically disabled. 72 /// 73 /// Note that interrupt functions are not allowed to call any non-reentrant 74 /// functions. An null interrupt function pointer disables the current 75 /// installed function. Note also that the handler may be executed on a 76 /// different thread on some platforms. 77 void SetInterruptFunction(void (*IF)()); 78 79 /// Registers a function to be called when an "info" signal is delivered to 80 /// the process. 81 /// 82 /// On POSIX systems, this will be SIGUSR1; on systems that have it, SIGINFO 83 /// will also be used (typically ctrl-t). 84 /// 85 /// Note that signal handlers are not allowed to call any non-reentrant 86 /// functions. An null function pointer disables the current installed 87 /// function. Note also that the handler may be executed on a different 88 /// thread on some platforms. 89 void SetInfoSignalFunction(void (*Handler)()); 90 91 /// Registers a function to be called in a "one-shot" manner when a pipe 92 /// signal is delivered to the process (i.e., on a failed write to a pipe). 93 /// After the pipe signal is handled once, the handler is unregistered. 94 /// 95 /// The LLVM signal handling code will not install any handler for the pipe 96 /// signal unless one is provided with this API (see \ref 97 /// DefaultOneShotPipeSignalHandler). This handler must be provided before 98 /// any other LLVM signal handlers are installed: the \ref InitLLVM 99 /// constructor has a flag that can simplify this setup. 100 /// 101 /// Note that the handler is not allowed to call any non-reentrant 102 /// functions. A null handler pointer disables the current installed 103 /// function. Note also that the handler may be executed on a 104 /// different thread on some platforms. 105 void SetOneShotPipeSignalFunction(void (*Handler)()); 106 107 /// On Unix systems and Windows, this function exits with an "IO error" exit 108 /// code. 109 void DefaultOneShotPipeSignalHandler(); 110 111 #ifdef _WIN32 112 /// Windows does not support signals and this handler must be called manually. 113 void CallOneShotPipeSignalHandler(); 114 #endif 115 116 /// This function does the following: 117 /// - clean up any temporary files registered with RemoveFileOnSignal() 118 /// - dump the callstack from the exception context 119 /// - call any relevant interrupt/signal handlers 120 /// - create a core/mini dump of the exception context whenever possible 121 /// Context is a system-specific failure context: it is the signal type on 122 /// Unix; the ExceptionContext on Windows. 123 void CleanupOnSignal(uintptr_t Context); 124 125 void unregisterHandlers(); 126 } // End sys namespace 127 } // End llvm namespace 128 129 #endif 130