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