failure_signal_handler.h
Go to the documentation of this file.
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 
47 namespace absl {
48 
49 // FailureSignalHandlerOptions
50 //
51 // Struct for holding `absl::InstallFailureSignalHandler()` configuration
52 // options.
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.
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.
110 
111 namespace debugging_internal {
112 const char* FailureSignalToString(int signo);
113 } // namespace debugging_internal
114 
115 } // namespace absl
116 
117 #endif // ABSL_DEBUGGING_FAILURE_SIGNAL_HANDLER_H_
const char * FailureSignalToString(int signo)
Definition: algorithm.h:29
void InstallFailureSignalHandler(const FailureSignalHandlerOptions &options)


abseil_cpp
Author(s):
autogenerated on Mon Feb 28 2022 21:31:18