]>
Commit | Line | Data |
---|---|---|
d9fcf2fb | 1 | /* UI_FILE - a generic STDIO like output stream. |
1d506c26 | 2 | Copyright (C) 1999-2024 Free Software Foundation, Inc. |
d9fcf2fb JM |
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 | |
a9762ec7 | 8 | the Free Software Foundation; either version 3 of the License, or |
d9fcf2fb JM |
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 | |
a9762ec7 | 17 | along with this program. If not, see <http://www.gnu.org/licenses/>. */ |
d9fcf2fb JM |
18 | |
19 | #ifndef UI_FILE_H | |
20 | #define UI_FILE_H | |
21 | ||
8de00631 | 22 | #include <string> |
eedeedd2 | 23 | #include "ui-style.h" |
8de00631 | 24 | |
d7e74731 PA |
25 | /* The abstract ui_file base class. */ |
26 | ||
27 | class ui_file | |
28 | { | |
29 | public: | |
30 | ui_file (); | |
31 | virtual ~ui_file () = 0; | |
d9fcf2fb | 32 | |
34f997c8 AB |
33 | ui_file (ui_file &&other) = default; |
34 | ||
d7e74731 | 35 | /* Public non-virtual API. */ |
d9fcf2fb | 36 | |
d7e74731 | 37 | void printf (const char *, ...) ATTRIBUTE_PRINTF (2, 3); |
d9fcf2fb | 38 | |
d53fd721 TT |
39 | /* Print a NUL-terminated string whose delimiter is QUOTER. Note |
40 | that these routines should only be called for printing things | |
41 | which are independent of the language of the program being | |
42 | debugged. | |
43 | ||
44 | This will normally escape backslashes and instances of QUOTER. | |
45 | If QUOTER is 0, it won't escape backslashes or any quoting | |
46 | character. As a side effect, if you pass the backslash character | |
47 | as the QUOTER, this will escape backslashes as usual, but not any | |
48 | other quoting character. */ | |
d7e74731 | 49 | void putstr (const char *str, int quoter); |
d9fcf2fb | 50 | |
d53fd721 TT |
51 | /* Like putstr, but only print the first N characters of STR. If |
52 | ASYNC_SAFE is true, then the output is done via the | |
53 | write_async_safe method. */ | |
54 | void putstrn (const char *str, int n, int quoter, bool async_safe = false); | |
3e43a32a | 55 | |
4311246b | 56 | void putc (int c); |
3e43a32a | 57 | |
d7e74731 | 58 | void vprintf (const char *, va_list) ATTRIBUTE_PRINTF (2, 0); |
01124a23 | 59 | |
d7e74731 PA |
60 | /* Methods below are both public, and overridable by ui_file |
61 | subclasses. */ | |
3e43a32a | 62 | |
d7e74731 | 63 | virtual void write (const char *buf, long length_buf) = 0; |
3e43a32a | 64 | |
d7e74731 PA |
65 | /* This version of "write" is safe for use in signal handlers. It's |
66 | not guaranteed that all existing output will have been flushed | |
67 | first. Implementations are also free to ignore some or all of | |
68 | the request. puts_async is not provided as the async versions | |
69 | are rarely used, no point in having both for a rarely used | |
70 | interface. */ | |
71 | virtual void write_async_safe (const char *buf, long length_buf) | |
72 | { gdb_assert_not_reached ("write_async_safe"); } | |
3e43a32a | 73 | |
d7e74731 PA |
74 | /* Some ui_files override this to provide a efficient implementation |
75 | that avoids a strlen. */ | |
76 | virtual void puts (const char *str) | |
77 | { this->write (str, strlen (str)); } | |
d9fcf2fb | 78 | |
d7e74731 PA |
79 | virtual long read (char *buf, long length_buf) |
80 | { gdb_assert_not_reached ("can't read from this file type"); } | |
d9fcf2fb | 81 | |
d7e74731 PA |
82 | virtual bool isatty () |
83 | { return false; } | |
2a9d5ccf | 84 | |
8a522c6c PW |
85 | /* true indicates terminal output behaviour such as cli_styling. |
86 | This default implementation indicates to do terminal output | |
87 | behaviour if the UI_FILE is a tty. A derived class can override | |
88 | TERM_OUT to have cli_styling behaviour without being a tty. */ | |
89 | virtual bool term_out () | |
90 | { return isatty (); } | |
91 | ||
92 | /* true if ANSI escapes can be used on STREAM. */ | |
93 | virtual bool can_emit_style_escape () | |
94 | { return false; } | |
95 | ||
d7e74731 PA |
96 | virtual void flush () |
97 | {} | |
6aa4f97c AB |
98 | |
99 | /* If this object has an underlying file descriptor, then return it. | |
100 | Otherwise, return -1. */ | |
101 | virtual int fd () const | |
102 | { return -1; } | |
84b33497 | 103 | |
7016a382 TT |
104 | /* Indicate that if the next sequence of characters overflows the |
105 | line, a newline should be inserted here rather than when it hits | |
106 | the end. If INDENT is non-zero, it is a number of spaces to be | |
107 | printed to indent the wrapped part on the next line. | |
108 | ||
109 | If the line is already overfull, we immediately print a newline and | |
110 | the indentation, and disable further wrapping. | |
111 | ||
112 | If we don't know the width of lines, but we know the page height, | |
113 | we must not wrap words, but should still keep track of newlines | |
114 | that were explicitly printed. | |
115 | ||
116 | This routine is guaranteed to force out any output which has been | |
117 | squirreled away in the wrap_buffer, so wrap_here (0) can be | |
118 | used to force out output from the wrap_buffer. */ | |
3cd52293 TT |
119 | virtual void wrap_here (int indent) |
120 | { | |
121 | } | |
7016a382 | 122 | |
c8d74a7b TT |
123 | /* Emit an ANSI style escape for STYLE. */ |
124 | virtual void emit_style_escape (const ui_file_style &style); | |
125 | ||
126 | /* Rest the current output style to the empty style. */ | |
127 | virtual void reset_style (); | |
128 | ||
9b716718 TT |
129 | /* Print STR, bypassing any paging that might be done by this |
130 | ui_file. Note that nearly no code should call this -- it's | |
6cb06a8c | 131 | intended for use by gdb_printf, but nothing else. */ |
9b716718 TT |
132 | virtual void puts_unfiltered (const char *str) |
133 | { | |
134 | this->puts (str); | |
135 | } | |
136 | ||
c8d74a7b TT |
137 | protected: |
138 | ||
139 | /* The currently applied style. */ | |
140 | ui_file_style m_applied_style; | |
141 | ||
d53fd721 TT |
142 | private: |
143 | ||
144 | /* Helper function for putstr and putstrn. Print the character C on | |
145 | this stream as part of the contents of a literal string whose | |
146 | delimiter is QUOTER. */ | |
147 | void printchar (int c, int quoter, bool async_safe); | |
d7e74731 | 148 | }; |
d9fcf2fb | 149 | |
d7e74731 | 150 | typedef std::unique_ptr<ui_file> ui_file_up; |
d9fcf2fb | 151 | |
d7e74731 | 152 | /* A ui_file that writes to nowhere. */ |
d9fcf2fb | 153 | |
d7e74731 PA |
154 | class null_file : public ui_file |
155 | { | |
156 | public: | |
157 | void write (const char *buf, long length_buf) override; | |
158 | void write_async_safe (const char *buf, long sizeof_buf) override; | |
159 | void puts (const char *str) override; | |
160 | }; | |
d9fcf2fb | 161 | |
d7e74731 PA |
162 | /* A preallocated null_file stream. */ |
163 | extern null_file null_stream; | |
164 | ||
e4adb939 EZ |
165 | extern int gdb_console_fputs (const char *, FILE *); |
166 | ||
d7e74731 PA |
167 | /* A std::string-based ui_file. Can be used as a scratch buffer for |
168 | collecting output. */ | |
d9fcf2fb | 169 | |
d7e74731 PA |
170 | class string_file : public ui_file |
171 | { | |
172 | public: | |
8a522c6c PW |
173 | /* Construct a string_file to collect 'raw' output, i.e. without |
174 | 'terminal' behaviour such as cli_styling. */ | |
175 | string_file () : m_term_out (false) {}; | |
176 | /* If TERM_OUT, construct a string_file with terminal output behaviour | |
177 | such as cli_styling) | |
178 | else collect 'raw' output like the previous constructor. */ | |
179 | explicit string_file (bool term_out) : m_term_out (term_out) {}; | |
d7e74731 | 180 | ~string_file () override; |
d9fcf2fb | 181 | |
34f997c8 AB |
182 | string_file (string_file &&other) = default; |
183 | ||
d7e74731 | 184 | /* Override ui_file methods. */ |
8de00631 | 185 | |
d7e74731 | 186 | void write (const char *buf, long length_buf) override; |
d9fcf2fb | 187 | |
d7e74731 PA |
188 | long read (char *buf, long length_buf) override |
189 | { gdb_assert_not_reached ("a string_file is not readable"); } | |
190 | ||
8a522c6c PW |
191 | bool term_out () override; |
192 | bool can_emit_style_escape () override; | |
193 | ||
d7e74731 PA |
194 | /* string_file-specific public API. */ |
195 | ||
196 | /* Accesses the std::string containing the entire output collected | |
5d10a204 SM |
197 | so far. */ |
198 | const std::string &string () { return m_string; } | |
d7e74731 | 199 | |
5d10a204 | 200 | /* Return an std::string containing the entire output collected so far. |
d7e74731 | 201 | |
5d10a204 SM |
202 | The internal buffer is cleared, such that it's ready to build a new |
203 | string. */ | |
204 | std::string release () | |
205 | { | |
206 | std::string ret = std::move (m_string); | |
207 | m_string.clear (); | |
208 | return ret; | |
209 | } | |
d7e74731 | 210 | |
e867795e AB |
211 | /* Set the internal buffer contents to STR. Any existing contents are |
212 | discarded. */ | |
213 | string_file &operator= (std::string &&str) | |
214 | { | |
215 | m_string = std::move (str); | |
216 | return *this; | |
217 | } | |
218 | ||
d7e74731 PA |
219 | /* Provide a few convenience methods with the same API as the |
220 | underlying std::string. */ | |
221 | const char *data () const { return m_string.data (); } | |
222 | const char *c_str () const { return m_string.c_str (); } | |
223 | size_t size () const { return m_string.size (); } | |
224 | bool empty () const { return m_string.empty (); } | |
225 | void clear () { return m_string.clear (); } | |
226 | ||
227 | private: | |
228 | /* The internal buffer. */ | |
229 | std::string m_string; | |
8a522c6c PW |
230 | |
231 | bool m_term_out; | |
d7e74731 PA |
232 | }; |
233 | ||
234 | /* A ui_file implementation that maps directly onto <stdio.h>'s FILE. | |
235 | A stdio_file can either own its underlying file, or not. If it | |
236 | owns the file, then destroying the stdio_file closes the underlying | |
237 | file, otherwise it is left open. */ | |
238 | ||
239 | class stdio_file : public ui_file | |
240 | { | |
241 | public: | |
242 | /* Create a ui_file from a previously opened FILE. CLOSE_P | |
243 | indicates whether the underlying file should be closed when the | |
244 | stdio_file is destroyed. */ | |
245 | explicit stdio_file (FILE *file, bool close_p = false); | |
246 | ||
247 | /* Create an stdio_file that is not managing any file yet. Call | |
248 | open to actually open something. */ | |
249 | stdio_file (); | |
250 | ||
251 | ~stdio_file () override; | |
252 | ||
253 | /* Open NAME in mode MODE, and own the resulting file. Returns true | |
254 | on success, false otherwise. If the stdio_file previously owned | |
255 | a file, it is closed. */ | |
256 | bool open (const char *name, const char *mode); | |
257 | ||
258 | void flush () override; | |
259 | ||
260 | void write (const char *buf, long length_buf) override; | |
261 | ||
262 | void write_async_safe (const char *buf, long length_buf) override; | |
263 | ||
264 | void puts (const char *) override; | |
265 | ||
266 | long read (char *buf, long length_buf) override; | |
267 | ||
268 | bool isatty () override; | |
269 | ||
8a522c6c PW |
270 | bool can_emit_style_escape () override; |
271 | ||
6aa4f97c AB |
272 | /* Return the underlying file descriptor. */ |
273 | int fd () const override | |
274 | { return m_fd; } | |
275 | ||
d7e74731 PA |
276 | private: |
277 | /* Sets the internal stream to FILE, and saves the FILE's file | |
278 | descriptor in M_FD. */ | |
279 | void set_stream (FILE *file); | |
280 | ||
281 | /* The file. */ | |
282 | FILE *m_file; | |
283 | ||
284 | /* The associated file descriptor is extracted ahead of time for | |
285 | stdio_file::write_async_safe's benefit, in case fileno isn't | |
286 | async-safe. */ | |
287 | int m_fd; | |
288 | ||
289 | /* If true, M_FILE is closed on destruction. */ | |
290 | bool m_close_p; | |
291 | }; | |
292 | ||
293 | typedef std::unique_ptr<stdio_file> stdio_file_up; | |
294 | ||
295 | /* Like stdio_file, but specifically for stderr. | |
296 | ||
297 | This exists because there is no real line-buffering on Windows, see | |
298 | <http://msdn.microsoft.com/en-us/library/86cebhfs%28v=vs.71%29.aspx> | |
299 | so the stdout is either fully-buffered or non-buffered. We can't | |
300 | make stdout non-buffered, because of two concerns: | |
449092f6 | 301 | |
d7e74731 PA |
302 | 1. Non-buffering hurts performance. |
303 | 2. Non-buffering may change GDB's behavior when it is interacting | |
304 | with a front-end, such as Emacs. | |
2a9d5ccf | 305 | |
d7e74731 PA |
306 | We leave stdout as fully buffered, but flush it first when |
307 | something is written to stderr. | |
d9fcf2fb | 308 | |
d7e74731 PA |
309 | Note that the 'write_async_safe' method is not overridden, because |
310 | there's no way to flush a stream in an async-safe manner. | |
311 | Fortunately, it doesn't really matter, because: | |
312 | ||
313 | 1. That method is only used for printing internal debug output | |
314 | from signal handlers. | |
315 | ||
316 | 2. Windows hosts don't have a concept of async-safeness. Signal | |
317 | handlers run in a separate thread, so they can call the regular | |
318 | non-async-safe output routines freely. | |
319 | */ | |
320 | class stderr_file : public stdio_file | |
321 | { | |
322 | public: | |
323 | explicit stderr_file (FILE *stream); | |
324 | ||
325 | /* Override the output routines to flush gdb_stdout before deferring | |
326 | to stdio_file for the actual outputting. */ | |
327 | void write (const char *buf, long length_buf) override; | |
328 | void puts (const char *linebuffer) override; | |
329 | }; | |
d9fcf2fb | 330 | |
d7e74731 | 331 | /* A ui_file implementation that maps onto two ui-file objects. */ |
d9fcf2fb | 332 | |
d7e74731 PA |
333 | class tee_file : public ui_file |
334 | { | |
335 | public: | |
2b141965 TT |
336 | /* Create a file which writes to both ONE and TWO. Ownership of |
337 | both files is up to the user. */ | |
338 | tee_file (ui_file *one, ui_file *two); | |
d7e74731 | 339 | ~tee_file () override; |
d9fcf2fb | 340 | |
d7e74731 PA |
341 | void write (const char *buf, long length_buf) override; |
342 | void write_async_safe (const char *buf, long length_buf) override; | |
343 | void puts (const char *) override; | |
ffa4ac95 | 344 | |
d7e74731 | 345 | bool isatty () override; |
8a522c6c PW |
346 | bool term_out () override; |
347 | bool can_emit_style_escape () override; | |
d7e74731 | 348 | void flush () override; |
ffa4ac95 | 349 | |
3cd52293 TT |
350 | void emit_style_escape (const ui_file_style &style) override |
351 | { | |
352 | m_one->emit_style_escape (style); | |
353 | m_two->emit_style_escape (style); | |
354 | } | |
355 | ||
356 | void reset_style () override | |
84b33497 | 357 | { |
3cd52293 TT |
358 | m_one->reset_style (); |
359 | m_two->reset_style (); | |
84b33497 TT |
360 | } |
361 | ||
9b716718 TT |
362 | void puts_unfiltered (const char *str) override |
363 | { | |
364 | m_one->puts_unfiltered (str); | |
365 | m_two->puts_unfiltered (str); | |
366 | } | |
367 | ||
d7e74731 | 368 | private: |
f3a09c80 AH |
369 | /* The two underlying ui_files. */ |
370 | ui_file *m_one; | |
2b141965 | 371 | ui_file *m_two; |
d7e74731 | 372 | }; |
d9fcf2fb | 373 | |
0735b091 TT |
374 | /* A ui_file implementation that filters out terminal escape |
375 | sequences. */ | |
376 | ||
377 | class no_terminal_escape_file : public stdio_file | |
378 | { | |
379 | public: | |
380 | no_terminal_escape_file () | |
381 | { | |
382 | } | |
383 | ||
384 | /* Like the stdio_file methods, but these filter out terminal escape | |
385 | sequences. */ | |
386 | void write (const char *buf, long length_buf) override; | |
387 | void puts (const char *linebuffer) override; | |
c8d74a7b TT |
388 | |
389 | void emit_style_escape (const ui_file_style &style) override | |
390 | { | |
391 | } | |
392 | ||
393 | void reset_style () override | |
394 | { | |
395 | } | |
0735b091 TT |
396 | }; |
397 | ||
c269d90a | 398 | /* A base class for ui_file types that wrap another ui_file. */ |
3c6c449e | 399 | |
c269d90a | 400 | class wrapped_file : public ui_file |
3c6c449e TT |
401 | { |
402 | public: | |
c269d90a TT |
403 | |
404 | bool isatty () override | |
405 | { return m_stream->isatty (); } | |
406 | ||
407 | bool term_out () override | |
408 | { return m_stream->term_out (); } | |
3c6c449e | 409 | |
962937b1 SM |
410 | bool can_emit_style_escape () override |
411 | { return m_stream->can_emit_style_escape (); } | |
412 | ||
c269d90a TT |
413 | void flush () override |
414 | { m_stream->flush (); } | |
415 | ||
416 | void wrap_here (int indent) override | |
417 | { m_stream->wrap_here (indent); } | |
418 | ||
419 | void emit_style_escape (const ui_file_style &style) override | |
420 | { m_stream->emit_style_escape (style); } | |
421 | ||
422 | /* Rest the current output style to the empty style. */ | |
423 | void reset_style () override | |
424 | { m_stream->reset_style (); } | |
425 | ||
426 | int fd () const override | |
427 | { return m_stream->fd (); } | |
428 | ||
429 | void puts_unfiltered (const char *str) override | |
430 | { m_stream->puts_unfiltered (str); } | |
431 | ||
ad62fd45 SM |
432 | void write_async_safe (const char *buf, long length_buf) override |
433 | { return m_stream->write_async_safe (buf, length_buf); } | |
434 | ||
c269d90a TT |
435 | protected: |
436 | ||
437 | /* Note that this class does not assume ownership of the stream. | |
438 | However, a subclass may choose to, by adding a 'delete' to its | |
439 | destructor. */ | |
440 | explicit wrapped_file (ui_file *stream) | |
441 | : m_stream (stream) | |
442 | { | |
443 | } | |
444 | ||
445 | /* The underlying stream. */ | |
446 | ui_file *m_stream; | |
447 | }; | |
448 | ||
449 | /* A ui_file that optionally puts a timestamp at the start of each | |
450 | line of output. */ | |
451 | ||
452 | class timestamped_file : public wrapped_file | |
453 | { | |
454 | public: | |
455 | explicit timestamped_file (ui_file *stream) | |
456 | : wrapped_file (stream) | |
457 | { | |
458 | } | |
459 | ||
3c6c449e TT |
460 | DISABLE_COPY_AND_ASSIGN (timestamped_file); |
461 | ||
462 | void write (const char *buf, long len) override; | |
463 | ||
464 | private: | |
465 | ||
3c6c449e TT |
466 | /* True if the next output should be timestamped. */ |
467 | bool m_needs_timestamp = true; | |
468 | }; | |
469 | ||
d9fcf2fb | 470 | #endif |