diff options
author | 2018-04-26 06:47:58 -0700 | |
---|---|---|
committer | 2018-04-26 11:05:43 -0400 | |
commit | 28f5b890702139effabf3576f20e1a4db4a90a80 (patch) | |
tree | a063698e44f3bb6ad708fcf290a05d1af3ea9aa6 /absl/debugging/failure_signal_handler.h | |
parent | ea0e750e52ee223db34a242f9a7229ac04a0f473 (diff) |
- 81cdce434ff1bd8fa54c832a11dda59af46e79cc Adds a failure signal handler to Abseil. by Derek Mauro <dmauro@google.com>
- 40a973dd1b159e7455dd5fc06ac2d3f494d72c3e Remove test fixture requirement for ExceptionSafetyTester... by Abseil Team <absl-team@google.com>
GitOrigin-RevId: 81cdce434ff1bd8fa54c832a11dda59af46e79cc
Change-Id: Ia9fca98e38f229b68f7ec45600dee1bbd5dcff33
Diffstat (limited to 'absl/debugging/failure_signal_handler.h')
-rw-r--r-- | absl/debugging/failure_signal_handler.h | 103 |
1 files changed, 103 insertions, 0 deletions
diff --git a/absl/debugging/failure_signal_handler.h b/absl/debugging/failure_signal_handler.h new file mode 100644 index 00000000..17522f00 --- /dev/null +++ b/absl/debugging/failure_signal_handler.h @@ -0,0 +1,103 @@ +// +// Copyright 2018 The Abseil Authors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +// This module allows the programmer to install a signal handler that +// dumps useful debugging information (like a stacktrace) on program +// failure. To use this functionality, call +// absl::InstallFailureSignalHandler() very early in your program, +// usually in the first few lines of main(): +// +// int main(int argc, char** argv) { +// absl::InitializeSymbolizer(argv[0]); +// absl::FailureSignalHandlerOptions options; +// absl::InstallFailureSignalHandler(options); +// DoSomethingInteresting(); +// return 0; +// } + +#ifndef ABSL_DEBUGGING_FAILURE_SIGNAL_HANDLER_H_ +#define ABSL_DEBUGGING_FAILURE_SIGNAL_HANDLER_H_ + +namespace absl { + +// Options struct for absl::InstallFailureSignalHandler(). +struct FailureSignalHandlerOptions { + // If true, try to symbolize the stacktrace emitted on failure. + bool symbolize_stacktrace = true; + + // If true, try to run signal handlers on an alternate stack (if + // supported on the given platform). This is useful in the case + // where the program crashes due to a stack overflow. By running on + // a alternate stack, the signal handler might be able to run even + // when the normal stack space has been exausted. The downside of + // using an alternate stack is that extra memory for the alternate + // stack needs to be pre-allocated. + bool use_alternate_stack = true; + + // If positive, FailureSignalHandler() sets an alarm to be delivered + // to the program after this many seconds, which will immediately + // abort the program. This is useful in the potential case where + // FailureSignalHandler() itself is hung or deadlocked. + int alarm_on_failure_secs = 3; + + // If false, after absl::FailureSignalHandler() runs, the signal is + // raised to the default handler for that signal (which normally + // terminates the program). + // + // If true, after absl::FailureSignalHandler() runs, it will call + // the previously registered signal handler for the signal that was + // received (if one was registered). This can be used to chain + // signal handlers. + // + // IMPORTANT: If true, the chained fatal signal handlers must not + // try to recover from the fatal signal. Instead, they should + // terminate the program via some mechanism, like raising the + // default handler for the signal, or by calling _exit(). + // absl::FailureSignalHandler() may put parts of the Abseil + // library into a state that cannot be recovered from. + bool call_previous_handler = false; + + // If not null, this function may be called with a std::string argument + // containing failure data. This function is used as a hook to write + // the failure data to a secondary location, for instance, to a log + // file. This function may also be called with a null data + // argument. This is a hint that this is a good time to flush any + // buffered data before the program may be terminated. Consider + // flushing any buffered data in all calls to this function. + // + // Since this function runs in a signal handler, it should be + // async-signal-safe if possible. + // See http://man7.org/linux/man-pages/man7/signal-safety.7.html + void (*writerfn)(const char*) = nullptr; +}; + +// Installs a signal handler for the common failure signals SIGSEGV, +// SIGILL, SIGFPE, SIGABRT, SIGTERM, SIGBUG, and SIGTRAP (if they +// exist on the given platform). The signal handler dumps program +// failure data in a unspecified format to stderr. The data dumped by +// the signal handler includes information that may be useful in +// debugging the failure. This may include the program counter, a +// stacktrace, and register information on some systems. Do not rely +// on the exact format of the output; it is subject to change. +void InstallFailureSignalHandler(const FailureSignalHandlerOptions& options); + +namespace debugging_internal { +const char* FailureSignalToString(int signo); +} // namespace debugging_internal + +} // namespace absl + +#endif // ABSL_DEBUGGING_FAILURE_SIGNAL_HANDLER_H_ |