1// Copyright 2018 The Abseil Authors.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// https://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14//
15// -----------------------------------------------------------------------------
16// File: failure_signal_handler.h
17// -----------------------------------------------------------------------------
18//
19// This file configures the Abseil *failure signal handler* to capture and dump
20// useful debugging information (such as a stacktrace) upon program failure.
21//
22// To use the failure signal handler, call `absl::InstallFailureSignalHandler()`
23// very early in your program, usually in the first few lines of main():
24//
25// int main(int argc, char** argv) {
26// // Initialize the symbolizer to get a human-readable stack trace
27// absl::InitializeSymbolizer(argv[0]);
28//
29// absl::FailureSignalHandlerOptions options;
30// absl::InstallFailureSignalHandler(options);
31// DoSomethingInteresting();
32// return 0;
33// }
34//
35// Any program that raises a fatal signal (such as `SIGSEGV`, `SIGILL`,
36// `SIGFPE`, `SIGABRT`, `SIGTERM`, `SIGBUG`, and `SIGTRAP`) will call the
37// installed failure signal handler and provide debugging information to stderr.
38//
39// Note that you should *not* install the Abseil failure signal handler more
40// than once. You may, of course, have another (non-Abseil) failure signal
41// handler installed (which would be triggered if Abseil's failure signal
42// handler sets `call_previous_handler` to `true`).
43
44#ifndef ABSL_DEBUGGING_FAILURE_SIGNAL_HANDLER_H_
45#define ABSL_DEBUGGING_FAILURE_SIGNAL_HANDLER_H_
46
47namespace absl {
48
49// FailureSignalHandlerOptions
50//
51// Struct for holding `absl::InstallFailureSignalHandler()` configuration
52// options.
53struct FailureSignalHandlerOptions {
54 // If true, try to symbolize the stacktrace emitted on failure, provided that
55 // you have initialized a symbolizer for that purpose. (See symbolize.h for
56 // more information.)
57 bool symbolize_stacktrace = true;
58
59 // If true, try to run signal handlers on an alternate stack (if supported on
60 // the given platform). An alternate stack is useful for program crashes due
61 // to a stack overflow; by running on a alternate stack, the signal handler
62 // may run even when normal stack space has been exausted. The downside of
63 // using an alternate stack is that extra memory for the alternate stack needs
64 // to be pre-allocated.
65 bool use_alternate_stack = true;
66
67 // If positive, indicates the number of seconds after which the failure signal
68 // handler is invoked to abort the program. Setting such an alarm is useful in
69 // cases where the failure signal handler itself may become hung or
70 // deadlocked.
71 int alarm_on_failure_secs = 3;
72
73 // If true, call the previously registered signal handler for the signal that
74 // was received (if one was registered) after the existing signal handler
75 // runs. This mechanism can be used to chain signal handlers together.
76 //
77 // If false, the signal is raised to the default handler for that signal
78 // (which normally terminates the program).
79 //
80 // IMPORTANT: If true, the chained fatal signal handlers must not try to
81 // recover from the fatal signal. Instead, they should terminate the program
82 // via some mechanism, like raising the default handler for the signal, or by
83 // calling `_exit()`. Note that the failure signal handler may put parts of
84 // the Abseil library into a state from which they cannot recover.
85 bool call_previous_handler = false;
86
87 // If non-null, indicates a pointer to a callback function that will be called
88 // upon failure, with a std::string argument containing failure data. This function
89 // may be used as a hook to write failure data to a secondary location, such
90 // as a log file. This function may also be called with null data, as a hint
91 // to flush any buffered data before the program may be terminated. Consider
92 // flushing any buffered data in all calls to this function.
93 //
94 // Since this function runs within a signal handler, it should be
95 // async-signal-safe if possible.
96 // See http://man7.org/linux/man-pages/man7/signal-safety.7.html
97 void (*writerfn)(const char*) = nullptr;
98};
99
100// InstallFailureSignalHandler()
101//
102// Installs a signal handler for the common failure signals `SIGSEGV`, `SIGILL`,
103// `SIGFPE`, `SIGABRT`, `SIGTERM`, `SIGBUG`, and `SIGTRAP` (provided they exist
104// on the given platform). The failure signal handler dumps program failure data
105// useful for debugging in an unspecified format to stderr. This data may
106// include the program counter, a stacktrace, and register information on some
107// systems; do not rely on an exact format for the output, as it is subject to
108// change.
109void InstallFailureSignalHandler(const FailureSignalHandlerOptions& options);
110
111namespace debugging_internal {
112const char* FailureSignalToString(int signo);
113} // namespace debugging_internal
114
115} // namespace absl
116
117#endif // ABSL_DEBUGGING_FAILURE_SIGNAL_HANDLER_H_
118