//
// 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_
