gdb/ui-file.h

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