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