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 #include "absl/base/config.h" 48 49 namespace absl { 50 ABSL_NAMESPACE_BEGIN 51 52 // FailureSignalHandlerOptions 53 // 54 // Struct for holding `absl::InstallFailureSignalHandler()` configuration 55 // options. 56 struct FailureSignalHandlerOptions { 57 // If true, try to symbolize the stacktrace emitted on failure, provided that 58 // you have initialized a symbolizer for that purpose. (See symbolize.h for 59 // more information.) 60 bool symbolize_stacktrace = true; 61 62 // If true, try to run signal handlers on an alternate stack (if supported on 63 // the given platform). An alternate stack is useful for program crashes due 64 // to a stack overflow; by running on a alternate stack, the signal handler 65 // may run even when normal stack space has been exausted. The downside of 66 // using an alternate stack is that extra memory for the alternate stack needs 67 // to be pre-allocated. 68 bool use_alternate_stack = true; 69 70 // If positive, indicates the number of seconds after which the failure signal 71 // handler is invoked to abort the program. Setting such an alarm is useful in 72 // cases where the failure signal handler itself may become hung or 73 // deadlocked. 74 int alarm_on_failure_secs = 3; 75 76 // If true, call the previously registered signal handler for the signal that 77 // was received (if one was registered) after the existing signal handler 78 // runs. This mechanism can be used to chain signal handlers together. 79 // 80 // If false, the signal is raised to the default handler for that signal 81 // (which normally terminates the program). 82 // 83 // IMPORTANT: If true, the chained fatal signal handlers must not try to 84 // recover from the fatal signal. Instead, they should terminate the program 85 // via some mechanism, like raising the default handler for the signal, or by 86 // calling `_exit()`. Note that the failure signal handler may put parts of 87 // the Abseil library into a state from which they cannot recover. 88 bool call_previous_handler = false; 89 90 // If non-null, indicates a pointer to a callback function that will be called 91 // upon failure, with a string argument containing failure data. This function 92 // may be used as a hook to write failure data to a secondary location, such 93 // as a log file. This function may also be called with null data, as a hint 94 // to flush any buffered data before the program may be terminated. Consider 95 // flushing any buffered data in all calls to this function. 96 // 97 // Since this function runs within a signal handler, it should be 98 // async-signal-safe if possible. 99 // See http://man7.org/linux/man-pages/man7/signal-safety.7.html 100 void (*writerfn)(const char*) = nullptr; 101 }; 102 103 // InstallFailureSignalHandler() 104 // 105 // Installs a signal handler for the common failure signals `SIGSEGV`, `SIGILL`, 106 // `SIGFPE`, `SIGABRT`, `SIGTERM`, `SIGBUG`, and `SIGTRAP` (provided they exist 107 // on the given platform). The failure signal handler dumps program failure data 108 // useful for debugging in an unspecified format to stderr. This data may 109 // include the program counter, a stacktrace, and register information on some 110 // systems; do not rely on an exact format for the output, as it is subject to 111 // change. 112 void InstallFailureSignalHandler(const FailureSignalHandlerOptions& options); 113 114 namespace debugging_internal { 115 const char* FailureSignalToString(int signo); 116 } // namespace debugging_internal 117 118 ABSL_NAMESPACE_END 119 } // namespace absl 120 121 #endif // ABSL_DEBUGGING_FAILURE_SIGNAL_HANDLER_H_ 122