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 | |