summaryrefslogtreecommitdiff
path: root/absl/debugging/failure_signal_handler.h
diff options
context:
space:
mode:
authorGravatar Abseil Team <absl-team@google.com>2018-04-26 06:47:58 -0700
committerGravatar Derek Mauro <dmauro@google.com>2018-04-26 11:05:43 -0400
commit28f5b890702139effabf3576f20e1a4db4a90a80 (patch)
treea063698e44f3bb6ad708fcf290a05d1af3ea9aa6 /absl/debugging/failure_signal_handler.h
parentea0e750e52ee223db34a242f9a7229ac04a0f473 (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.h103
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_