1 /* UI_FILE - a generic STDIO like output stream.
2 Copyright (C) 1999-2020 Free Software Foundation, Inc.
4 This file is part of GDB.
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.
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.
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/>. */
25 /* The abstract ui_file base class. */
31 virtual ~ui_file () = 0;
33 /* Public non-virtual API. */
35 void printf (const char *, ...) ATTRIBUTE_PRINTF (2, 3);
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
);
42 void putstrn (const char *str
, int n
, int quoter
);
46 void vprintf (const char *, va_list) ATTRIBUTE_PRINTF (2, 0);
48 /* Methods below are both public, and overridable by ui_file
51 virtual void write (const char *buf
, long length_buf
) = 0;
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
59 virtual void write_async_safe (const char *buf
, long length_buf
)
60 { gdb_assert_not_reached ("write_async_safe"); }
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
)); }
67 virtual long read (char *buf
, long length_buf
)
68 { gdb_assert_not_reached ("can't read from this file type"); }
70 virtual bool isatty ()
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 ()
80 /* true if ANSI escapes can be used on STREAM. */
81 virtual bool can_emit_style_escape ()
88 typedef std::unique_ptr
<ui_file
> ui_file_up
;
90 /* A ui_file that writes to nowhere. */
92 class null_file
: public ui_file
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
;
100 /* A preallocated null_file stream. */
101 extern null_file null_stream
;
103 extern void ui_file_flush (ui_file
*);
105 extern int ui_file_isatty (struct ui_file
*);
107 extern void ui_file_write (struct ui_file
*file
, const char *buf
,
110 extern void ui_file_write_async_safe (struct ui_file
*file
, const char *buf
,
113 extern long ui_file_read (struct ui_file
*file
, char *buf
, long length_buf
);
115 extern void ui_file_puts (struct ui_file
*file
, const char *buf
);
117 extern int gdb_console_fputs (const char *, FILE *);
119 /* A std::string-based ui_file. Can be used as a scratch buffer for
120 collecting output. */
122 class string_file
: public ui_file
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
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
;
134 /* Override ui_file methods. */
136 void write (const char *buf
, long length_buf
) override
;
138 long read (char *buf
, long length_buf
) override
139 { gdb_assert_not_reached ("a string_file is not readable"); }
141 bool term_out () override
;
142 bool can_emit_style_escape () override
;
144 /* string_file-specific public API. */
146 /* Accesses the std::string containing the entire output collected
149 Returns a non-const reference so that it's easy to move the
150 string contents out of the string_file. E.g.:
155 return std::move (buf.string ());
157 std::string
&string () { return m_string
; }
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 (); }
168 /* The internal buffer. */
169 std::string m_string
;
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. */
179 class stdio_file
: public ui_file
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);
187 /* Create an stdio_file that is not managing any file yet. Call
188 open to actually open something. */
191 ~stdio_file () override
;
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
);
198 void flush () override
;
200 void write (const char *buf
, long length_buf
) override
;
202 void write_async_safe (const char *buf
, long length_buf
) override
;
204 void puts (const char *) override
;
206 long read (char *buf
, long length_buf
) override
;
208 bool isatty () override
;
210 bool can_emit_style_escape () override
;
213 /* Sets the internal stream to FILE, and saves the FILE's file
214 descriptor in M_FD. */
215 void set_stream (FILE *file
);
220 /* The associated file descriptor is extracted ahead of time for
221 stdio_file::write_async_safe's benefit, in case fileno isn't
225 /* If true, M_FILE is closed on destruction. */
229 typedef std::unique_ptr
<stdio_file
> stdio_file_up
;
231 /* Like stdio_file, but specifically for stderr.
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:
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.
242 We leave stdout as fully buffered, but flush it first when
243 something is written to stderr.
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:
249 1. That method is only used for printing internal debug output
250 from signal handlers.
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.
256 class stderr_file
: public stdio_file
259 explicit stderr_file (FILE *stream
);
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
;
267 /* A ui_file implementation that maps onto two ui-file objects. */
269 class tee_file
: public ui_file
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
;
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
;
281 bool isatty () override
;
282 bool term_out () override
;
283 bool can_emit_style_escape () override
;
284 void flush () override
;
287 /* The two underlying ui_files. */
292 /* A ui_file implementation that filters out terminal escape
295 class no_terminal_escape_file
: public stdio_file
298 no_terminal_escape_file ()
302 /* Like the stdio_file methods, but these filter out terminal escape
304 void write (const char *buf
, long length_buf
) override
;
305 void puts (const char *linebuffer
) override
;