gdb/ui-file.h

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