File indexing completed on 2024-03-24 15:26:37
0001 /* 0002 This file is part of the KDE Libraries 0003 SPDX-FileCopyrightText: 2000 Timo Hummel <timo.hummel@sap.com> 0004 SPDX-FileCopyrightText: 2000 Tom Braun <braunt@fh-konstanz.de> 0005 0006 SPDX-License-Identifier: LGPL-2.0-or-later 0007 */ 0008 0009 #ifndef KCRASH_H 0010 #define KCRASH_H 0011 0012 #include <kcrash_export.h> 0013 0014 #include <qglobal.h> 0015 0016 class QString; 0017 0018 /** 0019 * This namespace contains functions to handle crashes. 0020 * It allows you to set a crash handler function that will be called 0021 * when your application crashes and also provides a default crash 0022 * handler that implements the following functionality: 0023 * @li Launches the KDE crash display application (DrKonqi) to let 0024 * the user report the bug and/or debug it. 0025 * @li Calls an emergency save function that you can set with 0026 * setEmergencySaveFunction() to attempt to save the application's data. 0027 * @li Autorestarts your application. 0028 * 0029 * @note All the above features are optional and you need to enable them 0030 * explicitly. By default, the defaultCrashHandler() will not do anything. 0031 * However, if you are using KApplication, it will by default enable launching 0032 * DrKonqi on crashes, unless the --nocrashhandler argument was passed on 0033 * the command line or the environment variable KDE_DEBUG is set to any value. 0034 */ 0035 namespace KCrash 0036 { 0037 /** 0038 * Initialize KCrash. 0039 * 0040 * This does nothing if $KDE_DEBUG is set. 0041 * 0042 * Call this in your main() to ensure that the crash handler is always launched. 0043 * @since 5.15 0044 */ 0045 KCRASH_EXPORT void initialize(); 0046 0047 /** 0048 * The default crash handler. 0049 * Do not call this function directly. Instead, use 0050 * setCrashHandler() to set it as your application's crash handler. 0051 * @param signal the signal number 0052 * @note If you implement your own crash handler, you will have to 0053 * call this function from your implementation if you want to use the 0054 * features of this namespace. 0055 */ 0056 KCRASH_EXPORT void defaultCrashHandler(int signal); 0057 0058 /** 0059 * Typedef for a pointer to a crash handler function. 0060 * The function's argument is the number of the signal. 0061 */ 0062 typedef void (*HandlerType)(int); 0063 0064 /** 0065 * Install a function to be called when a crash occurs. 0066 * A crash occurs when one of the following signals is 0067 * caught: SIGSEGV, SIGBUS, SIGFPE, SIGILL, SIGABRT. 0068 * @param handler this can be one of: 0069 * @li null, in which case signal catching is disabled 0070 * (by setting the signal handler for the crash signals to SIG_DFL) 0071 * @li a user defined function in the form: 0072 * static (if in a class) void myCrashHandler(int); 0073 * @li if handler is omitted, the default crash handler is installed 0074 * @note If you use setDrKonqiEnabled(true), setEmergencySaveFunction(myfunc) 0075 * or setFlags(AutoRestart), you do not need to call this function 0076 * explicitly. The default crash handler is automatically installed by 0077 * those functions if needed. However, if you set a custom crash handler, 0078 * those functions will not change it. 0079 */ 0080 KCRASH_EXPORT void setCrashHandler(HandlerType handler = defaultCrashHandler); 0081 0082 /** 0083 * Returns the installed crash handler. 0084 * @return the crash handler 0085 */ 0086 KCRASH_EXPORT HandlerType crashHandler(); 0087 0088 /** 0089 * Installs a function which should try to save the application's data. 0090 * @note It is the crash handler's responsibility to call this function. 0091 * Therefore, if no crash handler is set, the default crash handler 0092 * is installed to ensure the save function will be called. 0093 * @param saveFunction the handler to install 0094 */ 0095 KCRASH_EXPORT void setEmergencySaveFunction(HandlerType saveFunction = nullptr); 0096 0097 /** 0098 * Returns the currently set emergency save function. 0099 * @return the emergency save function 0100 */ 0101 KCRASH_EXPORT HandlerType emergencySaveFunction(); 0102 0103 /** 0104 * Options to determine how the default crash handler should behave. 0105 * @see CrashFlags 0106 */ 0107 enum CrashFlag { 0108 KeepFDs = 1, ///< don't close all file descriptors immediately 0109 SaferDialog = 2, ///< start DrKonqi without arbitrary disk access 0110 AlwaysDirectly = 0111 4, ///< never try to to start DrKonqi via kdeinit. Use fork() and exec() instead. @deprecated This is now the default, and does not need to be set. 0112 AutoRestart = 8, ///< autorestart this application. Only sensible for KUniqueApplications. @since 4.1. 0113 }; 0114 /** 0115 * Stores a combination of #CrashFlag values. 0116 */ 0117 Q_DECLARE_FLAGS(CrashFlags, CrashFlag) 0118 Q_DECLARE_OPERATORS_FOR_FLAGS(CrashFlags) 0119 0120 /** 0121 * Set options to determine how the default crash handler should behave. 0122 * @param flags ORed together CrashFlags 0123 */ 0124 KCRASH_EXPORT void setFlags(KCrash::CrashFlags flags); 0125 0126 /** 0127 * Enables or disables launching DrKonqi from the crash handler. 0128 * By default, launching DrKonqi is enabled when QCoreApplication is created. 0129 * To disable it: 0130 * @code 0131 void disableDrKonqi() 0132 { 0133 KCrash::setDrKonqiEnabled(false); 0134 } 0135 Q_CONSTRUCTOR_FUNCTION(disableDrKonqi) 0136 * \endcode 0137 * @note It is the crash handler's responsibility to launch DrKonqi. 0138 * Therefore, if no crash handler is set, this method also installs 0139 * the default crash handler to ensure that DrKonqi will be launched. 0140 * @since 4.5 0141 */ 0142 KCRASH_EXPORT void setDrKonqiEnabled(bool enabled); 0143 0144 /** 0145 * Returns true if DrKonqi is set to be launched from the crash handler or false otherwise. 0146 * @since 4.5 0147 */ 0148 KCRASH_EXPORT bool isDrKonqiEnabled(); 0149 0150 /** 0151 * Allows providing information to be included in the bug report. 0152 * 0153 * @since 5.69 0154 */ 0155 KCRASH_EXPORT void setErrorMessage(const QString &message); 0156 0157 } 0158 0159 #endif