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