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"
26namespace llvm {
27// Typedefs that are convenient but only used by the stack-trace-collection code
28// added if DebugLoc origin-tracking is enabled.
29using AddressSet = DenseSet<void *>;
30using SymbolizedAddressMap = DenseMap<void *, SmallVector<std::string, 0>>;
31} // namespace llvm
32#endif
33
34namespace llvm {
35class StringRef;
36class raw_ostream;
37
38namespace sys {
39
40/// This function runs all the registered interrupt handlers, including the
41/// removal of files registered by RemoveFileOnSignal.
42LLVM_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.
47LLVM_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.
52LLVM_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.
62LLVM_ABI void PrintStackTraceOnErrorSignal(StringRef Argv0,
63 bool DisableCrashReporting = false);
64
65/// Disable all system dialog boxes that appear when the process crashes.
66LLVM_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.
71LLVM_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.
83template <unsigned long MaxDepth>
84int 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.
91void symbolizeAddresses(AddressSet &Addresses,
92 SymbolizedAddressMap &SymbolizedAddresses);
93#endif
94
95// Run all registered signal handlers.
96LLVM_ABI void RunSignalHandlers();
97
98using 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.
103LLVM_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.
114LLVM_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.
126LLVM_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.
142LLVM_ABI void SetOneShotPipeSignalFunction(void (*Handler)());
143
144/// On Unix systems and Windows, this function exits with an "IO error" exit
145/// code.
146LLVM_ABI void DefaultOneShotPipeSignalHandler();
147
148#ifdef _WIN32
149/// Windows does not support signals and this handler must be called manually.
150LLVM_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.
160LLVM_ABI void CleanupOnSignal(uintptr_t Context);
161
162LLVM_ABI void unregisterHandlers();
163} // namespace sys
164} // namespace llvm
165
166#endif
167