gdb/ui-file.h

   1 /* UI_FILE - a generic STDIO like output stream.
   2    Copyright (C) 1999-2024 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   ui_file (ui_file &&other) = default;
  34
  35   /* Public non-virtual API.  */
  36
  37   void printf (const char *, ...) ATTRIBUTE_PRINTF (2, 3);
  38
  39   /* Print a NUL-terminated string whose delimiter is QUOTER.  Note
  40      that these routines should only be called for printing things
  41      which are independent of the language of the program being
  42      debugged.
  43
  44      This will normally escape backslashes and instances of QUOTER.
  45      If QUOTER is 0, it won't escape backslashes or any quoting
  46      character.  As a side effect, if you pass the backslash character
  47      as the QUOTER, this will escape backslashes as usual, but not any
  48      other quoting character.  */
  49   void putstr (const char *str, int quoter);
  50
  51   /* Like putstr, but only print the first N characters of STR.  If
  52      ASYNC_SAFE is true, then the output is done via the
  53      write_async_safe method.  */
  54   void putstrn (const char *str, int n, int quoter, bool async_safe = false);
  55
  56   void putc (int c);
  57
  58   void vprintf (const char *, va_list) ATTRIBUTE_PRINTF (2, 0);
  59
  60   /* Methods below are both public, and overridable by ui_file
  61      subclasses.  */
  62
  63   virtual void write (const char *buf, long length_buf) = 0;
  64
  65   /* This version of "write" is safe for use in signal handlers.  It's
  66      not guaranteed that all existing output will have been flushed
  67      first.  Implementations are also free to ignore some or all of
  68      the request.  puts_async is not provided as the async versions
  69      are rarely used, no point in having both for a rarely used
  70      interface.  */
  71   virtual void write_async_safe (const char *buf, long length_buf)
  72   { gdb_assert_not_reached ("write_async_safe"); }
  73
  74   /* Some ui_files override this to provide a efficient implementation
  75      that avoids a strlen.  */
  76   virtual void puts (const char *str)
  77   { this->write (str, strlen (str)); }
  78
  79   virtual long read (char *buf, long length_buf)
  80   { gdb_assert_not_reached ("can't read from this file type"); }
  81
  82   virtual bool isatty ()
  83   { return false; }
  84
  85   /* true indicates terminal output behaviour such as cli_styling.
  86      This default implementation indicates to do terminal output
  87      behaviour if the UI_FILE is a tty.  A derived class can override
  88      TERM_OUT to have cli_styling behaviour without being a tty.  */
  89   virtual bool term_out ()
  90   { return isatty (); }
  91
  92   /* true if ANSI escapes can be used on STREAM.  */
  93   virtual bool can_emit_style_escape ()
  94   { return false; }
  95
  96   virtual void flush ()
  97   {}
  98
  99   /* If this object has an underlying file descriptor, then return it.
 100      Otherwise, return -1.  */
 101   virtual int fd () const
 102   { return -1; }
 103
 104   /* Indicate that if the next sequence of characters overflows the
 105      line, a newline should be inserted here rather than when it hits
 106      the end.  If INDENT is non-zero, it is a number of spaces to be
 107      printed to indent the wrapped part on the next line.
 108
 109      If the line is already overfull, we immediately print a newline and
 110      the indentation, and disable further wrapping.
 111
 112      If we don't know the width of lines, but we know the page height,
 113      we must not wrap words, but should still keep track of newlines
 114      that were explicitly printed.
 115
 116      This routine is guaranteed to force out any output which has been
 117      squirreled away in the wrap_buffer, so wrap_here (0) can be
 118      used to force out output from the wrap_buffer.  */
 119   virtual void wrap_here (int indent)
 120   {
 121   }
 122
 123   /* Emit an ANSI style escape for STYLE.  */
 124   virtual void emit_style_escape (const ui_file_style &style);
 125
 126   /* Rest the current output style to the empty style.  */
 127   virtual void reset_style ();
 128
 129   /* Print STR, bypassing any paging that might be done by this
 130      ui_file.  Note that nearly no code should call this -- it's
 131      intended for use by gdb_printf, but nothing else.  */
 132   virtual void puts_unfiltered (const char *str)
 133   {
 134     this->puts (str);
 135   }
 136
 137 protected:
 138
 139   /* The currently applied style.  */
 140   ui_file_style m_applied_style;
 141
 142 private:
 143
 144   /* Helper function for putstr and putstrn.  Print the character C on
 145      this stream as part of the contents of a literal string whose
 146      delimiter is QUOTER.  */
 147   void printchar (int c, int quoter, bool async_safe);
 148 };
 149
 150 typedef std::unique_ptr<ui_file> ui_file_up;
 151
 152 /* A ui_file that writes to nowhere.  */
 153
 154 class null_file : public ui_file
 155 {
 156 public:
 157   void write (const char *buf, long length_buf) override;
 158   void write_async_safe (const char *buf, long sizeof_buf) override;
 159   void puts (const char *str) override;
 160 };
 161
 162 /* A preallocated null_file stream.  */
 163 extern null_file null_stream;
 164
 165 extern int gdb_console_fputs (const char *, FILE *);
 166
 167 /* A std::string-based ui_file.  Can be used as a scratch buffer for
 168    collecting output.  */
 169
 170 class string_file : public ui_file
 171 {
 172 public:
 173   /* Construct a string_file to collect 'raw' output, i.e. without
 174      'terminal' behaviour such as cli_styling.  */
 175   string_file () : m_term_out (false) {};
 176   /* If TERM_OUT, construct a string_file with terminal output behaviour
 177      such as cli_styling)
 178      else collect 'raw' output like the previous constructor.  */
 179   explicit string_file (bool term_out) : m_term_out (term_out) {};
 180   ~string_file () override;
 181
 182   string_file (string_file &&other) = default;
 183
 184   /* Override ui_file methods.  */
 185
 186   void write (const char *buf, long length_buf) override;
 187
 188   long read (char *buf, long length_buf) override
 189   { gdb_assert_not_reached ("a string_file is not readable"); }
 190
 191   bool term_out () override;
 192   bool can_emit_style_escape () override;
 193
 194   /* string_file-specific public API.  */
 195
 196   /* Accesses the std::string containing the entire output collected
 197      so far.  */
 198   const std::string &string () { return m_string; }
 199
 200   /* Return an std::string containing the entire output collected so far.
 201
 202      The internal buffer is cleared, such that it's ready to build a new
 203      string.  */
 204   std::string release ()
 205   {
 206     std::string ret = std::move (m_string);
 207     m_string.clear ();
 208     return ret;
 209   }
 210
 211   /* Set the internal buffer contents to STR.  Any existing contents are
 212      discarded.  */
 213   string_file &operator= (std::string &&str)
 214   {
 215     m_string = std::move (str);
 216     return *this;
 217   }
 218
 219   /* Provide a few convenience methods with the same API as the
 220      underlying std::string.  */
 221   const char *data () const { return m_string.data (); }
 222   const char *c_str () const { return m_string.c_str (); }
 223   size_t size () const { return m_string.size (); }
 224   bool empty () const { return m_string.empty (); }
 225   void clear () { return m_string.clear (); }
 226
 227 private:
 228   /* The internal buffer.  */
 229   std::string m_string;
 230
 231   bool m_term_out;
 232 };
 233
 234 /* A ui_file implementation that maps directly onto <stdio.h>'s FILE.
 235    A stdio_file can either own its underlying file, or not.  If it
 236    owns the file, then destroying the stdio_file closes the underlying
 237    file, otherwise it is left open.  */
 238
 239 class stdio_file : public ui_file
 240 {
 241 public:
 242   /* Create a ui_file from a previously opened FILE.  CLOSE_P
 243      indicates whether the underlying file should be closed when the
 244      stdio_file is destroyed.  */
 245   explicit stdio_file (FILE *file, bool close_p = false);
 246
 247   /* Create an stdio_file that is not managing any file yet.  Call
 248      open to actually open something.  */
 249   stdio_file ();
 250
 251   ~stdio_file () override;
 252
 253   /* Open NAME in mode MODE, and own the resulting file.  Returns true
 254      on success, false otherwise.  If the stdio_file previously owned
 255      a file, it is closed.  */
 256   bool open (const char *name, const char *mode);
 257
 258   void flush () override;
 259
 260   void write (const char *buf, long length_buf) override;
 261
 262   void write_async_safe (const char *buf, long length_buf) override;
 263
 264   void puts (const char *) override;
 265
 266   long read (char *buf, long length_buf) override;
 267
 268   bool isatty () override;
 269
 270   bool can_emit_style_escape () override;
 271
 272   /* Return the underlying file descriptor.  */
 273   int fd () const override
 274   { return m_fd; }
 275
 276 private:
 277   /* Sets the internal stream to FILE, and saves the FILE's file
 278      descriptor in M_FD.  */
 279   void set_stream (FILE *file);
 280
 281   /* The file.  */
 282   FILE *m_file;
 283
 284   /* The associated file descriptor is extracted ahead of time for
 285      stdio_file::write_async_safe's benefit, in case fileno isn't
 286      async-safe.  */
 287   int m_fd;
 288
 289   /* If true, M_FILE is closed on destruction.  */
 290   bool m_close_p;
 291 };
 292
 293 typedef std::unique_ptr<stdio_file> stdio_file_up;
 294
 295 /* Like stdio_file, but specifically for stderr.
 296
 297    This exists because there is no real line-buffering on Windows, see
 298    <http://msdn.microsoft.com/en-us/library/86cebhfs%28v=vs.71%29.aspx>
 299    so the stdout is either fully-buffered or non-buffered.  We can't
 300    make stdout non-buffered, because of two concerns:
 301
 302     1. Non-buffering hurts performance.
 303     2. Non-buffering may change GDB's behavior when it is interacting
 304        with a front-end, such as Emacs.
 305
 306    We leave stdout as fully buffered, but flush it first when
 307    something is written to stderr.
 308
 309    Note that the 'write_async_safe' method is not overridden, because
 310    there's no way to flush a stream in an async-safe manner.
 311    Fortunately, it doesn't really matter, because:
 312
 313     1. That method is only used for printing internal debug output
 314        from signal handlers.
 315
 316     2. Windows hosts don't have a concept of async-safeness.  Signal
 317        handlers run in a separate thread, so they can call the regular
 318        non-async-safe output routines freely.
 319 */
 320 class stderr_file : public stdio_file
 321 {
 322 public:
 323   explicit stderr_file (FILE *stream);
 324
 325   /* Override the output routines to flush gdb_stdout before deferring
 326      to stdio_file for the actual outputting.  */
 327   void write (const char *buf, long length_buf) override;
 328   void puts (const char *linebuffer) override;
 329 };
 330
 331 /* A ui_file implementation that maps onto two ui-file objects.  */
 332
 333 class tee_file : public ui_file
 334 {
 335 public:
 336   /* Create a file which writes to both ONE and TWO.  Ownership of
 337      both files is up to the user.  */
 338   tee_file (ui_file *one, ui_file *two);
 339   ~tee_file () override;
 340
 341   void write (const char *buf, long length_buf) override;
 342   void write_async_safe (const char *buf, long length_buf) override;
 343   void puts (const char *) override;
 344
 345   bool isatty () override;
 346   bool term_out () override;
 347   bool can_emit_style_escape () override;
 348   void flush () override;
 349
 350   void emit_style_escape (const ui_file_style &style) override
 351   {
 352     m_one->emit_style_escape (style);
 353     m_two->emit_style_escape (style);
 354   }
 355
 356   void reset_style () override
 357   {
 358     m_one->reset_style ();
 359     m_two->reset_style ();
 360   }
 361
 362   void puts_unfiltered (const char *str) override
 363   {
 364     m_one->puts_unfiltered (str);
 365     m_two->puts_unfiltered (str);
 366   }
 367
 368 private:
 369   /* The two underlying ui_files.  */
 370   ui_file *m_one;
 371   ui_file *m_two;
 372 };
 373
 374 /* A ui_file implementation that filters out terminal escape
 375    sequences.  */
 376
 377 class no_terminal_escape_file : public stdio_file
 378 {
 379 public:
 380   no_terminal_escape_file ()
 381   {
 382   }
 383
 384   /* Like the stdio_file methods, but these filter out terminal escape
 385      sequences.  */
 386   void write (const char *buf, long length_buf) override;
 387   void puts (const char *linebuffer) override;
 388
 389   void emit_style_escape (const ui_file_style &style) override
 390   {
 391   }
 392
 393   void reset_style () override
 394   {
 395   }
 396 };
 397
 398 /* A base class for ui_file types that wrap another ui_file.  */
 399
 400 class wrapped_file : public ui_file
 401 {
 402 public:
 403
 404   bool isatty () override
 405   { return m_stream->isatty (); }
 406
 407   bool term_out () override
 408   { return m_stream->term_out (); }
 409
 410   bool can_emit_style_escape () override
 411   { return m_stream->can_emit_style_escape (); }
 412
 413   void flush () override
 414   { m_stream->flush (); }
 415
 416   void wrap_here (int indent) override
 417   { m_stream->wrap_here (indent); }
 418
 419   void emit_style_escape (const ui_file_style &style) override
 420   { m_stream->emit_style_escape (style); }
 421
 422   /* Rest the current output style to the empty style.  */
 423   void reset_style () override
 424   { m_stream->reset_style (); }
 425
 426   int fd () const override
 427   { return m_stream->fd (); }
 428
 429   void puts_unfiltered (const char *str) override
 430   { m_stream->puts_unfiltered (str); }
 431
 432   void write_async_safe (const char *buf, long length_buf) override
 433   { return m_stream->write_async_safe (buf, length_buf); }
 434
 435 protected:
 436
 437   /* Note that this class does not assume ownership of the stream.
 438      However, a subclass may choose to, by adding a 'delete' to its
 439      destructor.  */
 440   explicit wrapped_file (ui_file *stream)
 441     : m_stream (stream)
 442   {
 443   }
 444
 445   /* The underlying stream.  */
 446   ui_file *m_stream;
 447 };
 448
 449 /* A ui_file that optionally puts a timestamp at the start of each
 450    line of output.  */
 451
 452 class timestamped_file : public wrapped_file
 453 {
 454 public:
 455   explicit timestamped_file (ui_file *stream)
 456     : wrapped_file (stream)
 457   {
 458   }
 459
 460   DISABLE_COPY_AND_ASSIGN (timestamped_file);
 461
 462   void write (const char *buf, long len) override;
 463
 464 private:
 465
 466   /* True if the next output should be timestamped.  */
 467   bool m_needs_timestamp = true;
 468 };
 469
 470 #endif