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   /* Indicate that if the next sequence of characters overflows the
 111      line, a newline should be inserted here rather than when it hits
 112      the end.  If INDENT is non-zero, it is a number of spaces to be
 113      printed to indent the wrapped part on the next line.
 114
 115      If the line is already overfull, we immediately print a newline and
 116      the indentation, and disable further wrapping.
 117
 118      If we don't know the width of lines, but we know the page height,
 119      we must not wrap words, but should still keep track of newlines
 120      that were explicitly printed.
 121
 122      This routine is guaranteed to force out any output which has been
 123      squirreled away in the wrap_buffer, so wrap_here (0) can be
 124      used to force out output from the wrap_buffer.  */
 125   void wrap_here (int indent);
 126
 127 private:
 128
 129   /* Helper function for putstr and putstrn.  Print the character C on
 130      this stream as part of the contents of a literal string whose
 131      delimiter is QUOTER.  */
 132   void printchar (int c, int quoter, bool async_safe);
 133 };
 134
 135 typedef std::unique_ptr<ui_file> ui_file_up;
 136
 137 /* A ui_file that writes to nowhere.  */
 138
 139 class null_file : public ui_file
 140 {
 141 public:
 142   void write (const char *buf, long length_buf) override;
 143   void write_async_safe (const char *buf, long sizeof_buf) override;
 144   void puts (const char *str) override;
 145 };
 146
 147 /* A preallocated null_file stream.  */
 148 extern null_file null_stream;
 149
 150 extern int gdb_console_fputs (const char *, FILE *);
 151
 152 /* A std::string-based ui_file.  Can be used as a scratch buffer for
 153    collecting output.  */
 154
 155 class string_file : public ui_file
 156 {
 157 public:
 158   /* Construct a string_file to collect 'raw' output, i.e. without
 159      'terminal' behaviour such as cli_styling.  */
 160   string_file () : m_term_out (false) {};
 161   /* If TERM_OUT, construct a string_file with terminal output behaviour
 162      such as cli_styling)
 163      else collect 'raw' output like the previous constructor.  */
 164   explicit string_file (bool term_out) : m_term_out (term_out) {};
 165   ~string_file () override;
 166
 167   /* Override ui_file methods.  */
 168
 169   void write (const char *buf, long length_buf) override;
 170
 171   long read (char *buf, long length_buf) override
 172   { gdb_assert_not_reached ("a string_file is not readable"); }
 173
 174   bool term_out () override;
 175   bool can_emit_style_escape () override;
 176
 177   /* string_file-specific public API.  */
 178
 179   /* Accesses the std::string containing the entire output collected
 180      so far.  */
 181   const std::string &string () { return m_string; }
 182
 183   /* Return an std::string containing the entire output collected so far.
 184
 185      The internal buffer is cleared, such that it's ready to build a new
 186      string.  */
 187   std::string release ()
 188   {
 189     std::string ret = std::move (m_string);
 190     m_string.clear ();
 191     return ret;
 192   }
 193
 194   /* Provide a few convenience methods with the same API as the
 195      underlying std::string.  */
 196   const char *data () const { return m_string.data (); }
 197   const char *c_str () const { return m_string.c_str (); }
 198   size_t size () const { return m_string.size (); }
 199   bool empty () const { return m_string.empty (); }
 200   void clear () { return m_string.clear (); }
 201
 202 private:
 203   /* The internal buffer.  */
 204   std::string m_string;
 205
 206   bool m_term_out;
 207 };
 208
 209 /* A ui_file implementation that maps directly onto <stdio.h>'s FILE.
 210    A stdio_file can either own its underlying file, or not.  If it
 211    owns the file, then destroying the stdio_file closes the underlying
 212    file, otherwise it is left open.  */
 213
 214 class stdio_file : public ui_file
 215 {
 216 public:
 217   /* Create a ui_file from a previously opened FILE.  CLOSE_P
 218      indicates whether the underlying file should be closed when the
 219      stdio_file is destroyed.  */
 220   explicit stdio_file (FILE *file, bool close_p = false);
 221
 222   /* Create an stdio_file that is not managing any file yet.  Call
 223      open to actually open something.  */
 224   stdio_file ();
 225
 226   ~stdio_file () override;
 227
 228   /* Open NAME in mode MODE, and own the resulting file.  Returns true
 229      on success, false otherwise.  If the stdio_file previously owned
 230      a file, it is closed.  */
 231   bool open (const char *name, const char *mode);
 232
 233   void flush () override;
 234
 235   void write (const char *buf, long length_buf) override;
 236
 237   void write_async_safe (const char *buf, long length_buf) override;
 238
 239   void puts (const char *) override;
 240
 241   long read (char *buf, long length_buf) override;
 242
 243   bool isatty () override;
 244
 245   bool can_emit_style_escape () override;
 246
 247   /* Return the underlying file descriptor.  */
 248   int fd () const override
 249   { return m_fd; }
 250
 251   virtual bool can_page () const override
 252   {
 253     return m_file == stdout;
 254   }
 255
 256 private:
 257   /* Sets the internal stream to FILE, and saves the FILE's file
 258      descriptor in M_FD.  */
 259   void set_stream (FILE *file);
 260
 261   /* The file.  */
 262   FILE *m_file;
 263
 264   /* The associated file descriptor is extracted ahead of time for
 265      stdio_file::write_async_safe's benefit, in case fileno isn't
 266      async-safe.  */
 267   int m_fd;
 268
 269   /* If true, M_FILE is closed on destruction.  */
 270   bool m_close_p;
 271 };
 272
 273 typedef std::unique_ptr<stdio_file> stdio_file_up;
 274
 275 /* Like stdio_file, but specifically for stderr.
 276
 277    This exists because there is no real line-buffering on Windows, see
 278    <http://msdn.microsoft.com/en-us/library/86cebhfs%28v=vs.71%29.aspx>
 279    so the stdout is either fully-buffered or non-buffered.  We can't
 280    make stdout non-buffered, because of two concerns:
 281
 282     1. Non-buffering hurts performance.
 283     2. Non-buffering may change GDB's behavior when it is interacting
 284        with a front-end, such as Emacs.
 285
 286    We leave stdout as fully buffered, but flush it first when
 287    something is written to stderr.
 288
 289    Note that the 'write_async_safe' method is not overridden, because
 290    there's no way to flush a stream in an async-safe manner.
 291    Fortunately, it doesn't really matter, because:
 292
 293     1. That method is only used for printing internal debug output
 294        from signal handlers.
 295
 296     2. Windows hosts don't have a concept of async-safeness.  Signal
 297        handlers run in a separate thread, so they can call the regular
 298        non-async-safe output routines freely.
 299 */
 300 class stderr_file : public stdio_file
 301 {
 302 public:
 303   explicit stderr_file (FILE *stream);
 304
 305   /* Override the output routines to flush gdb_stdout before deferring
 306      to stdio_file for the actual outputting.  */
 307   void write (const char *buf, long length_buf) override;
 308   void puts (const char *linebuffer) override;
 309 };
 310
 311 /* A ui_file implementation that maps onto two ui-file objects.  */
 312
 313 class tee_file : public ui_file
 314 {
 315 public:
 316   /* Create a file which writes to both ONE and TWO.  ONE will remain
 317      open when this object is destroyed; but TWO will be closed.  */
 318   tee_file (ui_file *one, ui_file_up &&two);
 319   ~tee_file () override;
 320
 321   void write (const char *buf, long length_buf) override;
 322   void write_async_safe (const char *buf, long length_buf) override;
 323   void puts (const char *) override;
 324
 325   bool isatty () override;
 326   bool term_out () override;
 327   bool can_emit_style_escape () override;
 328   void flush () override;
 329
 330   virtual bool can_page () const override
 331   {
 332     /* If one of the underlying files can page, then we allow it
 333        here.  */
 334     return m_one->can_page () || m_two->can_page ();
 335   }
 336
 337 private:
 338   /* The two underlying ui_files.  */
 339   ui_file *m_one;
 340   ui_file_up m_two;
 341 };
 342
 343 /* A ui_file implementation that filters out terminal escape
 344    sequences.  */
 345
 346 class no_terminal_escape_file : public stdio_file
 347 {
 348 public:
 349   no_terminal_escape_file ()
 350   {
 351   }
 352
 353   /* Like the stdio_file methods, but these filter out terminal escape
 354      sequences.  */
 355   void write (const char *buf, long length_buf) override;
 356   void puts (const char *linebuffer) override;
 357 };
 358
 359 #endif