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 // http://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. 53 struct 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. 109 void InstallFailureSignalHandler(const FailureSignalHandlerOptions& options); 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_ 118