gdb/ui.h

   1 /* Copyright (C) 2023-2024 Free Software Foundation, Inc.
   2
   3    This file is part of GDB.
   4
   5    This program is free software; you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 3 of the License, or
   8    (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  17
  18 #ifndef UI_H
  19 #define UI_H
  20
  21 #include "gdbsupport/event-loop.h"
  22 #include "gdbsupport/intrusive_list.h"
  23 #include "gdbsupport/next-iterator.h"
  24 #include "gdbsupport/scoped_restore.h"
  25
  26 struct interp;
  27
  28 /* Prompt state.  */
  29
  30 enum prompt_state
  31 {
  32   /* The command line is blocked simulating synchronous execution.
  33      This is used to implement the foreground execution commands
  34      ('run', 'continue', etc.).  We won't display the prompt and
  35      accept further commands until the execution is actually over.  */
  36   PROMPT_BLOCKED,
  37
  38   /* The command finished; display the prompt before returning back to
  39      the top level.  */
  40   PROMPT_NEEDED,
  41
  42   /* We've displayed the prompt already, ready for input.  */
  43   PROMPTED,
  44 };
  45
  46 /* All about a user interface instance.  Each user interface has its
  47    own I/O files/streams, readline state, its own top level
  48    interpreter (for the main UI, this is the interpreter specified
  49    with -i on the command line) and secondary interpreters (for
  50    interpreter-exec ...), etc.  There's always one UI associated with
  51    stdin/stdout/stderr, but the user can create secondary UIs, for
  52    example, to create a separate MI channel on its own stdio
  53    streams.  */
  54
  55 struct ui
  56 {
  57   /* Create a new UI.  */
  58   ui (FILE *instream, FILE *outstream, FILE *errstream);
  59   ~ui ();
  60
  61   DISABLE_COPY_AND_ASSIGN (ui);
  62
  63   /* Pointer to next in singly-linked list.  */
  64   struct ui *next = nullptr;
  65
  66   /* Convenient handle (UI number).  Unique across all UIs.  */
  67   int num;
  68
  69   /* The UI's command line buffer.  This is to used to accumulate
  70      input until we have a whole command line.  */
  71   std::string line_buffer;
  72
  73   /* The callback used by the event loop whenever an event is detected
  74      on the UI's input file descriptor.  This function incrementally
  75      builds a buffer where it accumulates the line read up to the
  76      point of invocation.  In the special case in which the character
  77      read is newline, the function invokes the INPUT_HANDLER callback
  78      (see below).  */
  79   void (*call_readline) (gdb_client_data) = nullptr;
  80
  81   /* The function to invoke when a complete line of input is ready for
  82      processing.  */
  83   void (*input_handler) (gdb::unique_xmalloc_ptr<char> &&) = nullptr;
  84
  85   /* True if this UI is using the readline library for command
  86      editing; false if using GDB's own simple readline emulation, with
  87      no editing support.  */
  88   int command_editing = 0;
  89
  90   /* Each UI has its own independent set of interpreters.  */
  91   intrusive_list<interp> interp_list;
  92   interp *current_interpreter = nullptr;
  93   interp *top_level_interpreter = nullptr;
  94
  95   /* The interpreter that is active while `interp_exec' is active, NULL
  96      at all other times.  */
  97   interp *command_interpreter = nullptr;
  98
  99   /* True if the UI is in async mode, false if in sync mode.  If in
 100      sync mode, a synchronous execution command (e.g, "next") does not
 101      return until the command is finished.  If in async mode, then
 102      running a synchronous command returns right after resuming the
 103      target.  Waiting for the command's completion is later done on
 104      the top event loop.  For the main UI, this starts out disabled,
 105      until all the explicit command line arguments (e.g., `gdb -ex
 106      "start" -ex "next"') are processed.  */
 107   int async = 0;
 108
 109   /* The number of nested readline secondary prompts that are
 110      currently active.  */
 111   int secondary_prompt_depth = 0;
 112
 113   /* The UI's stdin.  Set to stdin for the main UI.  */
 114   FILE *stdin_stream;
 115
 116   /* stdio stream that command input is being read from.  Set to stdin
 117      normally.  Set by source_command to the file we are sourcing.
 118      Set to NULL if we are executing a user-defined command or
 119      interacting via a GUI.  */
 120   FILE *instream;
 121   /* Standard output stream.  */
 122   FILE *outstream;
 123   /* Standard error stream.  */
 124   FILE *errstream;
 125
 126   /* The file descriptor for the input stream, so that we can register
 127      it with the event loop.  This can be set to -1 to prevent this
 128      registration.  */
 129   int input_fd;
 130
 131   /* Whether ISATTY returns true on input_fd.  Cached here because
 132      quit_force needs to know this _after_ input_fd might be
 133      closed.  */
 134   bool m_input_interactive_p;
 135
 136   /* See enum prompt_state's description.  */
 137   enum prompt_state prompt_state = PROMPT_NEEDED;
 138
 139   /* Whether the prompt should be kept blocked.  This is useful to not
 140      unblock the prompt too early in the context of nested command
 141      execution.  */
 142   bool keep_prompt_blocked = false;
 143
 144   /* The fields below that start with "m_" are "private".  They're
 145      meant to be accessed through wrapper macros that make them look
 146      like globals.  */
 147
 148   /* The ui_file streams.  */
 149   /* Normal results */
 150   struct ui_file *m_gdb_stdout;
 151   /* Input stream */
 152   struct ui_file *m_gdb_stdin;
 153   /* Serious error notifications */
 154   struct ui_file *m_gdb_stderr;
 155   /* Log/debug/trace messages that should bypass normal stdout/stderr
 156      filtering.  */
 157   struct ui_file *m_gdb_stdlog;
 158
 159   /* The current ui_out.  */
 160   struct ui_out *m_current_uiout = nullptr;
 161
 162   /* Register the UI's input file descriptor in the event loop.  */
 163   void register_file_handler ();
 164
 165   /* Unregister the UI's input file descriptor from the event loop.  */
 166   void unregister_file_handler ();
 167
 168   /* Return true if this UI's input fd is a tty.  */
 169   bool input_interactive_p () const;
 170 };
 171
 172 /* The main UI.  This is the UI that is bound to stdin/stdout/stderr.
 173    It always exists and is created automatically when GDB starts
 174    up.  */
 175 extern struct ui *main_ui;
 176
 177 /* The current UI.  */
 178 extern struct ui *current_ui;
 179
 180 /* The list of all UIs.  */
 181 extern struct ui *ui_list;
 182
 183 /* State for SWITCH_THRU_ALL_UIS.  */
 184 class switch_thru_all_uis
 185 {
 186 public:
 187
 188   switch_thru_all_uis () : m_iter (ui_list), m_save_ui (&current_ui)
 189   {
 190     current_ui = ui_list;
 191   }
 192
 193   DISABLE_COPY_AND_ASSIGN (switch_thru_all_uis);
 194
 195   /* If done iterating, return true; otherwise return false.  */
 196   bool done () const
 197   {
 198     return m_iter == NULL;
 199   }
 200
 201   /* Move to the next UI, setting current_ui if iteration is not yet
 202      complete.  */
 203   void next ()
 204   {
 205     m_iter = m_iter->next;
 206     if (m_iter != NULL)
 207       current_ui = m_iter;
 208   }
 209
 210  private:
 211
 212   /* Used to iterate through the UIs.  */
 213   struct ui *m_iter;
 214
 215   /* Save and restore current_ui.  */
 216   scoped_restore_tmpl<struct ui *> m_save_ui;
 217 };
 218
 219   /* Traverse through all UI, and switch the current UI to the one
 220      being iterated.  */
 221 #define SWITCH_THRU_ALL_UIS()           \
 222   for (switch_thru_all_uis stau_state; !stau_state.done (); stau_state.next ())
 223
 224 using ui_range = next_range<ui>;
 225
 226 /* An adapter that can be used to traverse over all UIs.  */
 227 static inline
 228 ui_range all_uis ()
 229 {
 230   return ui_range (ui_list);
 231 }
 232
 233 #endif /* UI_H */