gdb/ui-file.h

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