gdb/ui-file.h

   1 /* UI_FILE - a generic STDIO like output stream.
   2    Copyright (C) 1999-2022 Free Software Foundation, Inc.
   3
   4    This file is part of GDB.
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  18
  19 #ifndef UI_FILE_H
  20 #define UI_FILE_H
  21
  22 #include <string>
  23 #include "ui-style.h"
  24
  25 /* The abstract ui_file base class.  */
  26
  27 class ui_file
  28 {
  29 public:
  30   ui_file ();
  31   virtual ~ui_file () = 0;
  32
  33   /* Public non-virtual API.  */
  34
  35   void printf (const char *, ...) ATTRIBUTE_PRINTF (2, 3);
  36
  37   /* Print a NUL-terminated string whose delimiter is QUOTER.  Note
  38      that these routines should only be called for printing things
  39      which are independent of the language of the program being
  40      debugged.
  41
  42      This will normally escape backslashes and instances of QUOTER.
  43      If QUOTER is 0, it won't escape backslashes or any quoting
  44      character.  As a side effect, if you pass the backslash character
  45      as the QUOTER, this will escape backslashes as usual, but not any
  46      other quoting character.  */
  47   void putstr (const char *str, int quoter);
  48
  49   /* Like putstr, but only print the first N characters of STR.  If
  50      ASYNC_SAFE is true, then the output is done via the
  51      write_async_safe method.  */
  52   void putstrn (const char *str, int n, int quoter, bool async_safe = false);
  53
  54   int putc (int c);
  55
  56   void vprintf (const char *, va_list) ATTRIBUTE_PRINTF (2, 0);
  57
  58   /* Methods below are both public, and overridable by ui_file
  59      subclasses.  */
  60
  61   virtual void write (const char *buf, long length_buf) = 0;
  62
  63   /* This version of "write" is safe for use in signal handlers.  It's
  64      not guaranteed that all existing output will have been flushed
  65      first.  Implementations are also free to ignore some or all of
  66      the request.  puts_async is not provided as the async versions
  67      are rarely used, no point in having both for a rarely used
  68      interface.  */
  69   virtual void write_async_safe (const char *buf, long length_buf)
  70   { gdb_assert_not_reached ("write_async_safe"); }
  71
  72   /* Some ui_files override this to provide a efficient implementation
  73      that avoids a strlen.  */
  74   virtual void puts (const char *str)
  75   { this->write (str, strlen (str)); }
  76
  77   virtual long read (char *buf, long length_buf)
  78   { gdb_assert_not_reached ("can't read from this file type"); }
  79
  80   virtual bool isatty ()
  81   { return false; }
  82
  83   /* true indicates terminal output behaviour such as cli_styling.
  84      This default implementation indicates to do terminal output
  85      behaviour if the UI_FILE is a tty.  A derived class can override
  86      TERM_OUT to have cli_styling behaviour without being a tty.  */
  87   virtual bool term_out ()
  88   { return isatty (); }
  89
  90   /* true if ANSI escapes can be used on STREAM.  */
  91   virtual bool can_emit_style_escape ()
  92   { return false; }
  93
  94   virtual void flush ()
  95   {}
  96
  97   /* If this object has an underlying file descriptor, then return it.
  98      Otherwise, return -1.  */
  99   virtual int fd () const
 100   { return -1; }
 101
 102   /* Return true if this object supports paging, false otherwise.  */
 103   virtual bool can_page () const
 104   {
 105     /* Almost no file supports paging, which is why this is the
 106        default.  */
 107     return false;
 108   }
 109
 110 private:
 111
 112   /* Helper function for putstr and putstrn.  Print the character C on
 113      this stream as part of the contents of a literal string whose
 114      delimiter is QUOTER.  */
 115   void printchar (int c, int quoter, bool async_safe);
 116 };
 117
 118 typedef std::unique_ptr<ui_file> ui_file_up;
 119
 120 /* A ui_file that writes to nowhere.  */
 121
 122 class null_file : public ui_file
 123 {
 124 public:
 125   void write (const char *buf, long length_buf) override;
 126   void write_async_safe (const char *buf, long sizeof_buf) override;
 127   void puts (const char *str) override;
 128 };
 129
 130 /* A preallocated null_file stream.  */
 131 extern null_file null_stream;
 132
 133 extern int gdb_console_fputs (const char *, FILE *);
 134
 135 /* A std::string-based ui_file.  Can be used as a scratch buffer for
 136    collecting output.  */
 137
 138 class string_file : public ui_file
 139 {
 140 public:
 141   /* Construct a string_file to collect 'raw' output, i.e. without
 142      'terminal' behaviour such as cli_styling.  */
 143   string_file () : m_term_out (false) {};
 144   /* If TERM_OUT, construct a string_file with terminal output behaviour
 145      such as cli_styling)
 146      else collect 'raw' output like the previous constructor.  */
 147   explicit string_file (bool term_out) : m_term_out (term_out) {};
 148   ~string_file () override;
 149
 150   /* Override ui_file methods.  */
 151
 152   void write (const char *buf, long length_buf) override;
 153
 154   long read (char *buf, long length_buf) override
 155   { gdb_assert_not_reached ("a string_file is not readable"); }
 156
 157   bool term_out () override;
 158   bool can_emit_style_escape () override;
 159
 160   /* string_file-specific public API.  */
 161
 162   /* Accesses the std::string containing the entire output collected
 163      so far.  */
 164   const std::string &string () { return m_string; }
 165
 166   /* Return an std::string containing the entire output collected so far.
 167
 168      The internal buffer is cleared, such that it's ready to build a new
 169      string.  */
 170   std::string release ()
 171   {
 172     std::string ret = std::move (m_string);
 173     m_string.clear ();
 174     return ret;
 175   }
 176
 177   /* Provide a few convenience methods with the same API as the
 178      underlying std::string.  */
 179   const char *data () const { return m_string.data (); }
 180   const char *c_str () const { return m_string.c_str (); }
 181   size_t size () const { return m_string.size (); }
 182   bool empty () const { return m_string.empty (); }
 183   void clear () { return m_string.clear (); }
 184
 185 private:
 186   /* The internal buffer.  */
 187   std::string m_string;
 188
 189   bool m_term_out;
 190 };
 191
 192 /* A ui_file implementation that maps directly onto <stdio.h>'s FILE.
 193    A stdio_file can either own its underlying file, or not.  If it
 194    owns the file, then destroying the stdio_file closes the underlying
 195    file, otherwise it is left open.  */
 196
 197 class stdio_file : public ui_file
 198 {
 199 public:
 200   /* Create a ui_file from a previously opened FILE.  CLOSE_P
 201      indicates whether the underlying file should be closed when the
 202      stdio_file is destroyed.  */
 203   explicit stdio_file (FILE *file, bool close_p = false);
 204
 205   /* Create an stdio_file that is not managing any file yet.  Call
 206      open to actually open something.  */
 207   stdio_file ();
 208
 209   ~stdio_file () override;
 210
 211   /* Open NAME in mode MODE, and own the resulting file.  Returns true
 212      on success, false otherwise.  If the stdio_file previously owned
 213      a file, it is closed.  */
 214   bool open (const char *name, const char *mode);
 215
 216   void flush () override;
 217
 218   void write (const char *buf, long length_buf) override;
 219
 220   void write_async_safe (const char *buf, long length_buf) override;
 221
 222   void puts (const char *) override;
 223
 224   long read (char *buf, long length_buf) override;
 225
 226   bool isatty () override;
 227
 228   bool can_emit_style_escape () override;
 229
 230   /* Return the underlying file descriptor.  */
 231   int fd () const override
 232   { return m_fd; }
 233
 234   virtual bool can_page () const override
 235   {
 236     return m_file == stdout;
 237   }
 238
 239 private:
 240   /* Sets the internal stream to FILE, and saves the FILE's file
 241      descriptor in M_FD.  */
 242   void set_stream (FILE *file);
 243
 244   /* The file.  */
 245   FILE *m_file;
 246
 247   /* The associated file descriptor is extracted ahead of time for
 248      stdio_file::write_async_safe's benefit, in case fileno isn't
 249      async-safe.  */
 250   int m_fd;
 251
 252   /* If true, M_FILE is closed on destruction.  */
 253   bool m_close_p;
 254 };
 255
 256 typedef std::unique_ptr<stdio_file> stdio_file_up;
 257
 258 /* Like stdio_file, but specifically for stderr.
 259
 260    This exists because there is no real line-buffering on Windows, see
 261    <http://msdn.microsoft.com/en-us/library/86cebhfs%28v=vs.71%29.aspx>
 262    so the stdout is either fully-buffered or non-buffered.  We can't
 263    make stdout non-buffered, because of two concerns:
 264
 265     1. Non-buffering hurts performance.
 266     2. Non-buffering may change GDB's behavior when it is interacting
 267        with a front-end, such as Emacs.
 268
 269    We leave stdout as fully buffered, but flush it first when
 270    something is written to stderr.
 271
 272    Note that the 'write_async_safe' method is not overridden, because
 273    there's no way to flush a stream in an async-safe manner.
 274    Fortunately, it doesn't really matter, because:
 275
 276     1. That method is only used for printing internal debug output
 277        from signal handlers.
 278
 279     2. Windows hosts don't have a concept of async-safeness.  Signal
 280        handlers run in a separate thread, so they can call the regular
 281        non-async-safe output routines freely.
 282 */
 283 class stderr_file : public stdio_file
 284 {
 285 public:
 286   explicit stderr_file (FILE *stream);
 287
 288   /* Override the output routines to flush gdb_stdout before deferring
 289      to stdio_file for the actual outputting.  */
 290   void write (const char *buf, long length_buf) override;
 291   void puts (const char *linebuffer) override;
 292 };
 293
 294 /* A ui_file implementation that maps onto two ui-file objects.  */
 295
 296 class tee_file : public ui_file
 297 {
 298 public:
 299   /* Create a file which writes to both ONE and TWO.  ONE will remain
 300      open when this object is destroyed; but TWO will be closed.  */
 301   tee_file (ui_file *one, ui_file_up &&two);
 302   ~tee_file () override;
 303
 304   void write (const char *buf, long length_buf) override;
 305   void write_async_safe (const char *buf, long length_buf) override;
 306   void puts (const char *) override;
 307
 308   bool isatty () override;
 309   bool term_out () override;
 310   bool can_emit_style_escape () override;
 311   void flush () override;
 312
 313   virtual bool can_page () const override
 314   {
 315     /* If one of the underlying files can page, then we allow it
 316        here.  */
 317     return m_one->can_page () || m_two->can_page ();
 318   }
 319
 320 private:
 321   /* The two underlying ui_files.  */
 322   ui_file *m_one;
 323   ui_file_up m_two;
 324 };
 325
 326 /* A ui_file implementation that filters out terminal escape
 327    sequences.  */
 328
 329 class no_terminal_escape_file : public stdio_file
 330 {
 331 public:
 332   no_terminal_escape_file ()
 333   {
 334   }
 335
 336   /* Like the stdio_file methods, but these filter out terminal escape
 337      sequences.  */
 338   void write (const char *buf, long length_buf) override;
 339   void puts (const char *linebuffer) override;
 340 };
 341
 342 #endif