gdb/ui-file.h

   1 /* UI_FILE - a generic STDIO like output stream.
   2    Copyright (C) 1999-2021 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
  93 typedef std::unique_ptr<ui_file> ui_file_up;
  94
  95 /* A ui_file that writes to nowhere.  */
  96
  97 class null_file : public ui_file
  98 {
  99 public:
 100   void write (const char *buf, long length_buf) override;
 101   void write_async_safe (const char *buf, long sizeof_buf) override;
 102   void puts (const char *str) override;
 103 };
 104
 105 /* A preallocated null_file stream.  */
 106 extern null_file null_stream;
 107
 108 extern int gdb_console_fputs (const char *, FILE *);
 109
 110 /* A std::string-based ui_file.  Can be used as a scratch buffer for
 111    collecting output.  */
 112
 113 class string_file : public ui_file
 114 {
 115 public:
 116   /* Construct a string_file to collect 'raw' output, i.e. without
 117      'terminal' behaviour such as cli_styling.  */
 118   string_file () : m_term_out (false) {};
 119   /* If TERM_OUT, construct a string_file with terminal output behaviour
 120      such as cli_styling)
 121      else collect 'raw' output like the previous constructor.  */
 122   explicit string_file (bool term_out) : m_term_out (term_out) {};
 123   ~string_file () override;
 124
 125   /* Override ui_file methods.  */
 126
 127   void write (const char *buf, long length_buf) override;
 128
 129   long read (char *buf, long length_buf) override
 130   { gdb_assert_not_reached ("a string_file is not readable"); }
 131
 132   bool term_out () override;
 133   bool can_emit_style_escape () override;
 134
 135   /* string_file-specific public API.  */
 136
 137   /* Accesses the std::string containing the entire output collected
 138      so far.
 139
 140      Returns a non-const reference so that it's easy to move the
 141      string contents out of the string_file.  E.g.:
 142
 143       string_file buf;
 144       buf.printf (....);
 145       buf.printf (....);
 146       return std::move (buf.string ());
 147   */
 148   std::string &string () { return m_string; }
 149
 150   /* Provide a few convenience methods with the same API as the
 151      underlying std::string.  */
 152   const char *data () const { return m_string.data (); }
 153   const char *c_str () const { return m_string.c_str (); }
 154   size_t size () const { return m_string.size (); }
 155   bool empty () const { return m_string.empty (); }
 156   void clear () { return m_string.clear (); }
 157
 158 private:
 159   /* The internal buffer.  */
 160   std::string m_string;
 161
 162   bool m_term_out;
 163 };
 164
 165 /* A ui_file implementation that maps directly onto <stdio.h>'s FILE.
 166    A stdio_file can either own its underlying file, or not.  If it
 167    owns the file, then destroying the stdio_file closes the underlying
 168    file, otherwise it is left open.  */
 169
 170 class stdio_file : public ui_file
 171 {
 172 public:
 173   /* Create a ui_file from a previously opened FILE.  CLOSE_P
 174      indicates whether the underlying file should be closed when the
 175      stdio_file is destroyed.  */
 176   explicit stdio_file (FILE *file, bool close_p = false);
 177
 178   /* Create an stdio_file that is not managing any file yet.  Call
 179      open to actually open something.  */
 180   stdio_file ();
 181
 182   ~stdio_file () override;
 183
 184   /* Open NAME in mode MODE, and own the resulting file.  Returns true
 185      on success, false otherwise.  If the stdio_file previously owned
 186      a file, it is closed.  */
 187   bool open (const char *name, const char *mode);
 188
 189   void flush () override;
 190
 191   void write (const char *buf, long length_buf) override;
 192
 193   void write_async_safe (const char *buf, long length_buf) override;
 194
 195   void puts (const char *) override;
 196
 197   long read (char *buf, long length_buf) override;
 198
 199   bool isatty () override;
 200
 201   bool can_emit_style_escape () override;
 202
 203   /* Return the underlying file descriptor.  */
 204   int fd () const override
 205   { return m_fd; }
 206
 207 private:
 208   /* Sets the internal stream to FILE, and saves the FILE's file
 209      descriptor in M_FD.  */
 210   void set_stream (FILE *file);
 211
 212   /* The file.  */
 213   FILE *m_file;
 214
 215   /* The associated file descriptor is extracted ahead of time for
 216      stdio_file::write_async_safe's benefit, in case fileno isn't
 217      async-safe.  */
 218   int m_fd;
 219
 220   /* If true, M_FILE is closed on destruction.  */
 221   bool m_close_p;
 222 };
 223
 224 typedef std::unique_ptr<stdio_file> stdio_file_up;
 225
 226 /* Like stdio_file, but specifically for stderr.
 227
 228    This exists because there is no real line-buffering on Windows, see
 229    <http://msdn.microsoft.com/en-us/library/86cebhfs%28v=vs.71%29.aspx>
 230    so the stdout is either fully-buffered or non-buffered.  We can't
 231    make stdout non-buffered, because of two concerns:
 232
 233     1. Non-buffering hurts performance.
 234     2. Non-buffering may change GDB's behavior when it is interacting
 235        with a front-end, such as Emacs.
 236
 237    We leave stdout as fully buffered, but flush it first when
 238    something is written to stderr.
 239
 240    Note that the 'write_async_safe' method is not overridden, because
 241    there's no way to flush a stream in an async-safe manner.
 242    Fortunately, it doesn't really matter, because:
 243
 244     1. That method is only used for printing internal debug output
 245        from signal handlers.
 246
 247     2. Windows hosts don't have a concept of async-safeness.  Signal
 248        handlers run in a separate thread, so they can call the regular
 249        non-async-safe output routines freely.
 250 */
 251 class stderr_file : public stdio_file
 252 {
 253 public:
 254   explicit stderr_file (FILE *stream);
 255
 256   /* Override the output routines to flush gdb_stdout before deferring
 257      to stdio_file for the actual outputting.  */
 258   void write (const char *buf, long length_buf) override;
 259   void puts (const char *linebuffer) override;
 260 };
 261
 262 /* A ui_file implementation that maps onto two ui-file objects.  */
 263
 264 class tee_file : public ui_file
 265 {
 266 public:
 267   /* Create a file which writes to both ONE and TWO.  ONE will remain
 268      open when this object is destroyed; but TWO will be closed.  */
 269   tee_file (ui_file *one, ui_file_up &&two);
 270   ~tee_file () override;
 271
 272   void write (const char *buf, long length_buf) override;
 273   void write_async_safe (const char *buf, long length_buf) override;
 274   void puts (const char *) override;
 275
 276   bool isatty () override;
 277   bool term_out () override;
 278   bool can_emit_style_escape () override;
 279   void flush () override;
 280
 281 private:
 282   /* The two underlying ui_files.  */
 283   ui_file *m_one;
 284   ui_file_up m_two;
 285 };
 286
 287 /* A ui_file implementation that filters out terminal escape
 288    sequences.  */
 289
 290 class no_terminal_escape_file : public stdio_file
 291 {
 292 public:
 293   no_terminal_escape_file ()
 294   {
 295   }
 296
 297   /* Like the stdio_file methods, but these filter out terminal escape
 298      sequences.  */
 299   void write (const char *buf, long length_buf) override;
 300   void puts (const char *linebuffer) override;
 301 };
 302
 303 #endif