gdb/ui-file.h

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