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