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