gdb/event-top.h

   1 /* Definitions used by event-top.c, for GDB, the GNU debugger.
   2
   3    Copyright (C) 1999-2025 Free Software Foundation, Inc.
   4
   5    Written by Elena Zannoni <ezannoni@cygnus.com> of Cygnus Solutions.
   6
   7    This file is part of GDB.
   8
   9    This program is free software; you can redistribute it and/or modify
  10    it under the terms of the GNU General Public License as published by
  11    the Free Software Foundation; either version 3 of the License, or
  12    (at your option) any later version.
  13
  14    This program is distributed in the hope that it will be useful,
  15    but WITHOUT ANY WARRANTY; without even the implied warranty of
  16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17    GNU General Public License for more details.
  18
  19    You should have received a copy of the GNU General Public License
  20    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  21
  22 #ifndef GDB_EVENT_TOP_H
  23 #define GDB_EVENT_TOP_H
  24
  25 #include <signal.h>
  26
  27 #include "extension.h"
  28
  29 struct cmd_list_element;
  30
  31 /* The current quit handler (and its type).  This is called from the
  32    QUIT macro.  See default_quit_handler below for default behavior.
  33    Parts of GDB temporarily override this to e.g., completely suppress
  34    Ctrl-C because it would not be safe to throw.  E.g., normally, you
  35    wouldn't want to quit between a RSP command and its response, as
  36    that would break the communication with the target, but you may
  37    still want to intercept the Ctrl-C and offer to disconnect if the
  38    user presses Ctrl-C multiple times while the target is stuck
  39    waiting for the wedged remote stub.  */
  40 typedef void (quit_handler_ftype) ();
  41 extern quit_handler_ftype *quit_handler;
  42
  43 /* Exported functions from event-top.c.
  44    FIXME: these should really go into top.h.  */
  45
  46 /* The default quit handler.  Checks whether Ctrl-C was pressed, and
  47    if so:
  48
  49      - If GDB owns the terminal, throws a quit exception.
  50
  51      - If GDB does not own the terminal, forwards the Ctrl-C to the
  52        target.
  53 */
  54
  55 extern void default_quit_handler ();
  56
  57 /* Flag that function quit should call quit_force.  */
  58
  59 extern volatile bool sync_quit_force_run;
  60
  61 /* Set sync_quit_force_run and also call set_quit_flag().  */
  62
  63 extern void set_force_quit_flag ();
  64
  65 /* Control C eventually causes this to be called, at a convenient time.  */
  66
  67 extern void quit ();
  68
  69 /* Helper for the QUIT macro.  */
  70
  71 extern void maybe_quit ();
  72
  73 /* Check whether a Ctrl-C was typed, and if so, call the current quit
  74    handler.  */
  75
  76 #define QUIT maybe_quit ()
  77
  78 /* Set the serial event associated with the quit flag.  */
  79
  80 extern void quit_serial_event_set ();
  81
  82 /* Clear the serial event associated with the quit flag.  */
  83
  84 extern void quit_serial_event_clear ();
  85
  86 /* Wrap f (args) and handle exceptions by:
  87    - returning val, and
  88    - calling set_quit_flag or set_force_quit_flag, if needed.  */
  89
  90 template <typename R, R val, typename F, typename... Args>
  91 static R
  92 catch_exceptions (F &&f, Args&&... args)
  93 {
  94    try
  95      {
  96        return f (std::forward<Args> (args)...);
  97      }
  98    catch (const gdb_exception &ex)
  99      {
 100        if (ex.reason == RETURN_QUIT)
 101          set_quit_flag ();
 102        else if (ex.reason == RETURN_FORCED_QUIT)
 103          set_force_quit_flag ();
 104      }
 105
 106    return val;
 107 }
 108
 109 extern void display_gdb_prompt (const char *new_prompt);
 110 extern void gdb_setup_readline (int);
 111 extern void gdb_disable_readline (void);
 112 extern void gdb_init_signals (void);
 113 extern void change_line_handler (int);
 114
 115 extern void command_line_handler (gdb::unique_xmalloc_ptr<char> &&rl);
 116 extern void command_handler (const char *command);
 117
 118 #ifdef SIGTSTP
 119 extern void handle_sigtstp (int sig);
 120 #endif
 121
 122 extern void handle_sigint (int sig);
 123 extern void handle_sigterm (int sig);
 124 extern void async_request_quit (void *arg);
 125 extern void async_disable_stdin (void);
 126 extern void async_enable_stdin (void);
 127
 128 /* Exported variables from event-top.c.
 129    FIXME: these should really go into top.h.  */
 130
 131 extern bool set_editing_cmd_var;
 132 extern bool exec_done_display_p;
 133 extern void (*after_char_processing_hook) (void);
 134 extern int call_stdin_event_handler_again_p;
 135 extern void gdb_readline_no_editing_callback (void *client_data);
 136
 137 /* Wrappers for rl_callback_handler_remove and
 138    rl_callback_handler_install that keep track of whether the callback
 139    handler is installed in readline.  Do not call the readline
 140    versions directly.  */
 141 extern void gdb_rl_callback_handler_remove (void);
 142 extern void gdb_rl_callback_handler_install (const char *prompt);
 143
 144 /* Reinstall the readline callback handler (with no prompt), if not
 145    currently installed.  */
 146 extern void gdb_rl_callback_handler_reinstall (void);
 147
 148 /* Called by readline after a complete line has been gathered from the
 149    user, but before the line is dispatched to back to GDB.  This function
 150    is a wrapper around readline's builtin rl_deprep_terminal function, and
 151    handles the case where readline received EOF.  */
 152 extern void gdb_rl_deprep_term_function (void);
 153
 154 typedef void (*segv_handler_t) (int);
 155
 156 /* On construction, replaces the current thread's SIGSEGV handler with
 157    the provided one.  On destruction, restores the handler to the
 158    original one.  */
 159 class scoped_segv_handler_restore
 160 {
 161  public:
 162   scoped_segv_handler_restore (segv_handler_t new_handler);
 163   ~scoped_segv_handler_restore ();
 164
 165  private:
 166   segv_handler_t m_old_handler;
 167 };
 168
 169 #endif /* GDB_EVENT_TOP_H */