QcCrashHandler Namespace
Crash reports (decision E-834). More...
| Header: | #include <common/diagnostics/QcCrashHandler.h> |
Classes
| struct | Setup |
Functions
| bool | available() |
| bool | crashForTest(const QString &kind) |
| QStringList | crashTestKinds() |
| bool | install(const QcCrashHandler::Setup &setup) |
| bool | installPlatform(const QcCrashHandler::Setup &setup) |
| int | logHandle() |
| void | preparePlatformCrashTest() |
| void | preparePlatformThread() |
| void | prepareThread() |
| const char * | reason() |
| void | reportFatalMessage() |
| void | setLogHandle(int handle) |
| void | setReason(const QByteArray &reason) |
| quint64 | threadId() |
Detailed Description
Installed once at the start of a program: on a fatal signal (macOS, Linux: SIGSEGV, SIGBUS, SIGILL, SIGFPE, SIGABRT, SIGTRAP, SIGSYS) or an unhandled exception (Windows) it writes a text report with the cause, address, thread and the stack, on Windows also a minidump, and (macOS, Linux) notes the crash at the end of the log file; then the process ends as it would have without it. std::terminate and qFatal end in abort() and are reported the same way, with their reason. The handler replaces earlier handlers of these signals and an earlier unhandled-exception filter without calling them (nothing in QtCraft installs one before). The signal handler uses only async-signal-safe calls on buffers prepared by install(). A second thread that crashes while the first writes its report waits for it (at most five seconds). Limits: a stack overflow is reported only on threads with an alternate signal stack (the main thread and those that called prepareThread()), and the symbol lookup of the backtrace may hang when the crash happened inside the dynamic loader. Builds with a sanitizer keep their own reports and install nothing.
Function Documentation
bool QcCrashHandler::available()
Returns whether this build can install the handler (not with sanitizers).
bool QcCrashHandler::crashForTest(const QString &kind)
The test hook –crash-test: crashes the way kind names at once ("segv", "abort", "fatal", "terminate", "trap", or "thread-segv" and "thread-overflow" on a thread of its own). Returns false for an unknown kind.
QStringList QcCrashHandler::crashTestKinds()
Returns the kinds crashForTest() knows.
bool QcCrashHandler::install(const QcCrashHandler::Setup &setup)
Installs the handler with setup. Returns false (after a warning) where it cannot.
bool QcCrashHandler::installPlatform(const QcCrashHandler::Setup &setup)
The platform part of install() with setup. Returns whether it installed the handler.
int QcCrashHandler::logHandle()
For the platform parts: returns the log handle, -1 for none.
See also setLogHandle().
void QcCrashHandler::preparePlatformCrashTest()
The platform part of crashForTest(): no dialog that would wait for a person.
void QcCrashHandler::preparePlatformThread()
The platform part of prepareThread().
void QcCrashHandler::prepareThread()
Prepares the calling thread for crash reports, at its start: an alternate signal stack of its own (macOS, Linux; so a stack overflow there is reported), room for the handler after a stack overflow and the terminate handler, which MSVC keeps per thread (Windows). Does nothing until install() succeeded.
const char *QcCrashHandler::reason()
For the platform parts (QcCrashHandler_posix.cpp, QcCrashHandler_win.cpp): returns the reason, empty when none.
See also setReason().
void QcCrashHandler::reportFatalMessage()
A fatal message (qFatal, Q_ASSERT) is about to end the process: on Windows Qt ends it with a fast fail that no handler sees, so the report and dump are written now; elsewhere the abort() that follows is reported.
void QcCrashHandler::setLogHandle(int handle)
Sets the log file's handle (QcLogWriter::handle), -1 for none: the crash line goes there.
See also logHandle().
void QcCrashHandler::setReason(const QByteArray &reason)
Sets reason as the reason the report names (a fatal message, a terminate); kept in a fixed buffer.
See also reason().
quint64 QcCrashHandler::threadId()
Returns the id of the calling thread as crash reports and log lines name it (the system's thread id); async-signal-safe.