LLDB  mainline
Stream.h
Go to the documentation of this file.
1 //===-- Stream.h ------------------------------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #ifndef liblldb_Stream_h_
10 #define liblldb_Stream_h_
11 
12 #include "lldb/Utility/Flags.h"
13 #include "lldb/lldb-defines.h"
14 #include "lldb/lldb-enumerations.h"
15 #include "llvm/ADT/StringRef.h"
16 #include "llvm/Support/FormatVariadic.h"
17 #include "llvm/Support/raw_ostream.h"
18 
19 #include <stdarg.h>
20 #include <stddef.h>
21 #include <stdint.h>
22 #include <type_traits>
23 
24 namespace lldb_private {
25 
26 /// \class Stream Stream.h "lldb/Utility/Stream.h"
27 /// A stream class that can stream formatted output to a file.
28 class Stream {
29 public:
30  /// \a m_flags bit values.
31  enum {
32  eBinary = (1 << 0) ///< Get and put data as binary instead of as the default
33  /// string mode.
34  };
35 
36  /// Utility class for counting the bytes that were written to a stream in a
37  /// certain time span.
38  /// \example
39  /// ByteDelta delta(*this);
40  /// WriteDataToStream("foo");
41  /// return *delta;
42  /// \endcode
43  class ByteDelta {
44  Stream *m_stream;
45  /// Bytes we have written so far when ByteDelta was created.
46  size_t m_start;
47 
48  public:
49  ByteDelta(Stream &s) : m_stream(&s), m_start(s.GetWrittenBytes()) {}
50  /// Returns the number of bytes written to the given Stream since this
51  /// ByteDelta object was created.
52  size_t operator*() const { return m_stream->GetWrittenBytes() - m_start; }
53  };
54 
55  /// Construct with flags and address size and byte order.
56  ///
57  /// Construct with dump flags \a flags and the default address size. \a
58  /// flags can be any of the above enumeration logical OR'ed together.
59  Stream(uint32_t flags, uint32_t addr_size, lldb::ByteOrder byte_order);
60 
61  /// Construct a default Stream, not binary, host byte order and host addr
62  /// size.
63  ///
64  Stream();
65 
66  // FIXME: Streams should not be copyable.
67  Stream(const Stream &other) : m_forwarder(*this) { (*this) = other; }
68 
69  Stream &operator=(const Stream &rhs) {
70  m_flags = rhs.m_flags;
74  return *this;
75  }
76 
77  /// Destructor
78  virtual ~Stream();
79 
80  // Subclasses must override these methods
81 
82  /// Flush the stream.
83  ///
84  /// Subclasses should flush the stream to make any output appear if the
85  /// stream has any buffering.
86  virtual void Flush() = 0;
87 
88  /// Output character bytes to the stream.
89  ///
90  /// Appends \a src_len characters from the buffer \a src to the stream.
91  ///
92  /// \param[in] src
93  /// A buffer containing at least \a src_len bytes of data.
94  ///
95  /// \param[in] src_len
96  /// A number of bytes to append to the stream.
97  ///
98  /// \return
99  /// The number of bytes that were appended to the stream.
100  size_t Write(const void *src, size_t src_len) {
101  size_t appended_byte_count = WriteImpl(src, src_len);
102  m_bytes_written += appended_byte_count;
103  return appended_byte_count;
104  }
105 
106  size_t GetWrittenBytes() const { return m_bytes_written; }
107 
108  // Member functions
109  size_t PutChar(char ch);
110 
111  /// Set the byte_order value.
112  ///
113  /// Sets the byte order of the data to extract. Extracted values will be
114  /// swapped if necessary when decoding.
115  ///
116  /// \param[in] byte_order
117  /// The byte order value to use when extracting data.
118  ///
119  /// \return
120  /// The old byte order value.
122 
123  /// Format a C string from a printf style format and variable arguments and
124  /// encode and append the resulting C string as hex bytes.
125  ///
126  /// \param[in] format
127  /// A printf style format string.
128  ///
129  /// \param[in] ...
130  /// Any additional arguments needed for the printf format string.
131  ///
132  /// \return
133  /// The number of bytes that were appended to the stream.
134  size_t PrintfAsRawHex8(const char *format, ...)
135  __attribute__((__format__(__printf__, 2, 3)));
136 
137  /// Append an uint8_t value in the hexadecimal format to the stream.
138  ///
139  /// \param[in] uvalue
140  /// The value to append.
141  ///
142  /// \return
143  /// The number of bytes that were appended to the stream.
144  size_t PutHex8(uint8_t uvalue);
145 
146  size_t PutNHex8(size_t n, uint8_t uvalue);
147 
148  size_t PutHex16(uint16_t uvalue,
150 
151  size_t PutHex32(uint32_t uvalue,
153 
154  size_t PutHex64(uint64_t uvalue,
156 
157  size_t PutMaxHex64(uint64_t uvalue, size_t byte_size,
159  size_t PutFloat(float f,
161 
162  size_t PutDouble(double d,
164 
165  size_t PutLongDouble(long double ld,
167 
168  size_t PutPointer(void *ptr);
169 
170  // Append \a src_len bytes from \a src to the stream as hex characters (two
171  // ascii characters per byte of input data)
172  size_t
173  PutBytesAsRawHex8(const void *src, size_t src_len,
174  lldb::ByteOrder src_byte_order = lldb::eByteOrderInvalid,
175  lldb::ByteOrder dst_byte_order = lldb::eByteOrderInvalid);
176 
177  // Append \a src_len bytes from \a s to the stream as binary data.
178  size_t PutRawBytes(const void *s, size_t src_len,
179  lldb::ByteOrder src_byte_order = lldb::eByteOrderInvalid,
180  lldb::ByteOrder dst_byte_order = lldb::eByteOrderInvalid);
181 
182  size_t PutStringAsRawHex8(llvm::StringRef s);
183 
184  /// Output a NULL terminated C string \a cstr to the stream \a s.
185  ///
186  /// \param[in] cstr
187  /// A NULL terminated C string.
188  ///
189  /// \return
190  /// A reference to this class so multiple things can be streamed
191  /// in one statement.
192  Stream &operator<<(const char *cstr);
193 
194  Stream &operator<<(llvm::StringRef str);
195 
196  /// Output a pointer value \a p to the stream \a s.
197  ///
198  /// \param[in] p
199  /// A void pointer.
200  ///
201  /// \return
202  /// A reference to this class so multiple things can be streamed
203  /// in one statement.
204  Stream &operator<<(const void *p);
205 
206  /// Output a character \a ch to the stream \a s.
207  ///
208  /// \param[in] ch
209  /// A printable character value.
210  ///
211  /// \return
212  /// A reference to this class so multiple things can be streamed
213  /// in one statement.
214  Stream &operator<<(char ch);
215 
216  /// Output a uint8_t \a uval to the stream \a s.
217  ///
218  /// \param[in] uval
219  /// A uint8_t value.
220  ///
221  /// \return
222  /// A reference to this class so multiple things can be streamed
223  /// in one statement.
224  Stream &operator<<(uint8_t uval);
225 
226  /// Output a uint16_t \a uval to the stream \a s.
227  ///
228  /// \param[in] uval
229  /// A uint16_t value.
230  ///
231  /// \return
232  /// A reference to this class so multiple things can be streamed
233  /// in one statement.
234  Stream &operator<<(uint16_t uval);
235 
236  /// Output a uint32_t \a uval to the stream \a s.
237  ///
238  /// \param[in] uval
239  /// A uint32_t value.
240  ///
241  /// \return
242  /// A reference to this class so multiple things can be streamed
243  /// in one statement.
244  Stream &operator<<(uint32_t uval);
245 
246  /// Output a uint64_t \a uval to the stream \a s.
247  ///
248  /// \param[in] uval
249  /// A uint64_t value.
250  ///
251  /// \return
252  /// A reference to this class so multiple things can be streamed
253  /// in one statement.
254  Stream &operator<<(uint64_t uval);
255 
256  /// Output a int8_t \a sval to the stream \a s.
257  ///
258  /// \param[in] sval
259  /// A int8_t value.
260  ///
261  /// \return
262  /// A reference to this class so multiple things can be streamed
263  /// in one statement.
264  Stream &operator<<(int8_t sval);
265 
266  /// Output a int16_t \a sval to the stream \a s.
267  ///
268  /// \param[in] sval
269  /// A int16_t value.
270  ///
271  /// \return
272  /// A reference to this class so multiple things can be streamed
273  /// in one statement.
274  Stream &operator<<(int16_t sval);
275 
276  /// Output a int32_t \a sval to the stream \a s.
277  ///
278  /// \param[in] sval
279  /// A int32_t value.
280  ///
281  /// \return
282  /// A reference to this class so multiple things can be streamed
283  /// in one statement.
284  Stream &operator<<(int32_t sval);
285 
286  /// Output a int64_t \a sval to the stream \a s.
287  ///
288  /// \param[in] sval
289  /// A int64_t value.
290  ///
291  /// \return
292  /// A reference to this class so multiple things can be streamed
293  /// in one statement.
294  Stream &operator<<(int64_t sval);
295 
296  /// Output an address value to this stream.
297  ///
298  /// Put an address \a addr out to the stream with optional \a prefix and \a
299  /// suffix strings.
300  ///
301  /// \param[in] addr
302  /// An address value.
303  ///
304  /// \param[in] addr_size
305  /// Size in bytes of the address, used for formatting.
306  ///
307  /// \param[in] prefix
308  /// A prefix C string. If nullptr, no prefix will be output.
309  ///
310  /// \param[in] suffix
311  /// A suffix C string. If nullptr, no suffix will be output.
312  void Address(uint64_t addr, uint32_t addr_size, const char *prefix = nullptr,
313  const char *suffix = nullptr);
314 
315  /// Output an address range to this stream.
316  ///
317  /// Put an address range \a lo_addr - \a hi_addr out to the stream with
318  /// optional \a prefix and \a suffix strings.
319  ///
320  /// \param[in] lo_addr
321  /// The start address of the address range.
322  ///
323  /// \param[in] hi_addr
324  /// The end address of the address range.
325  ///
326  /// \param[in] addr_size
327  /// Size in bytes of the address, used for formatting.
328  ///
329  /// \param[in] prefix
330  /// A prefix C string. If nullptr, no prefix will be output.
331  ///
332  /// \param[in] suffix
333  /// A suffix C string. If nullptr, no suffix will be output.
334  void AddressRange(uint64_t lo_addr, uint64_t hi_addr, uint32_t addr_size,
335  const char *prefix = nullptr, const char *suffix = nullptr);
336 
337  /// Output a C string to the stream.
338  ///
339  /// Print a C string \a cstr to the stream.
340  ///
341  /// \param[in] cstr
342  /// The string to be output to the stream.
343  size_t PutCString(llvm::StringRef cstr);
344 
345  /// Output and End of Line character to the stream.
346  size_t EOL();
347 
348  /// Get the address size in bytes.
349  ///
350  /// \return
351  /// The size of an address in bytes that is used when outputting
352  /// address and pointer values to the stream.
354 
355  /// The flags accessor.
356  ///
357  /// \return
358  /// A reference to the Flags member variable.
359  Flags &GetFlags();
360 
361  /// The flags const accessor.
362  ///
363  /// \return
364  /// A const reference to the Flags member variable.
365  const Flags &GetFlags() const;
366 
367  //// The byte order accessor.
368  ////
369  //// \return
370  //// The byte order.
372 
373  /// Get the current indentation level.
374  ///
375  /// \return
376  /// The current indentation level as an integer.
377  int GetIndentLevel() const;
378 
379  /// Indent the current line in the stream.
380  ///
381  /// Indent the current line using the current indentation level and print an
382  /// optional string following the indentation spaces.
383  ///
384  /// \param[in] s
385  /// A C string to print following the indentation. If nullptr, just
386  /// output the indentation characters.
387  size_t Indent(const char *s = nullptr);
388  size_t Indent(llvm::StringRef s);
389 
390  /// Decrement the current indentation level.
391  void IndentLess(int amount = 2);
392 
393  /// Increment the current indentation level.
394  void IndentMore(int amount = 2);
395 
396  /// Output an offset value.
397  ///
398  /// Put an offset \a uval out to the stream using the printf format in \a
399  /// format.
400  ///
401  /// \param[in] offset
402  /// The offset value.
403  ///
404  /// \param[in] format
405  /// The printf style format to use when outputting the offset.
406  void Offset(uint32_t offset, const char *format = "0x%8.8x: ");
407 
408  /// Output printf formatted output to the stream.
409  ///
410  /// Print some formatted output to the stream.
411  ///
412  /// \param[in] format
413  /// A printf style format string.
414  ///
415  /// \param[in] ...
416  /// Variable arguments that are needed for the printf style
417  /// format string \a format.
418  size_t Printf(const char *format, ...) __attribute__((format(printf, 2, 3)));
419 
420  size_t PrintfVarArg(const char *format, va_list args);
421 
422  template <typename... Args> void Format(const char *format, Args &&... args) {
423  PutCString(llvm::formatv(format, std::forward<Args>(args)...).str());
424  }
425 
426  /// Output a quoted C string value to the stream.
427  ///
428  /// Print a double quoted NULL terminated C string to the stream using the
429  /// printf format in \a format.
430  ///
431  /// \param[in] cstr
432  /// A NULL terminated C string value.
433  ///
434  /// \param[in] format
435  /// The optional C string format that can be overridden.
436  void QuotedCString(const char *cstr, const char *format = "\"%s\"");
437 
438  /// Set the address size in bytes.
439  ///
440  /// \param[in] addr_size
441  /// The new size in bytes of an address to use when outputting
442  /// address and pointer values.
443  void SetAddressByteSize(uint32_t addr_size);
444 
445  /// Set the current indentation level.
446  ///
447  /// \param[in] level
448  /// The new indentation level.
449  void SetIndentLevel(int level);
450 
451  /// Output a SLEB128 number to the stream.
452  ///
453  /// Put an SLEB128 \a uval out to the stream using the printf format in \a
454  /// format.
455  ///
456  /// \param[in] uval
457  /// A uint64_t value that was extracted as a SLEB128 value.
458  size_t PutSLEB128(int64_t uval);
459 
460  /// Output a ULEB128 number to the stream.
461  ///
462  /// Put an ULEB128 \a uval out to the stream using the printf format in \a
463  /// format.
464  ///
465  /// \param[in] uval
466  /// A uint64_t value that was extracted as a ULEB128 value.
467  size_t PutULEB128(uint64_t uval);
468 
469  /// Returns a raw_ostream that forwards the data to this Stream object.
470  llvm::raw_ostream &AsRawOstream() {
471  return m_forwarder;
472  }
473 
474 protected:
475  // Member variables
476  Flags m_flags; ///< Dump flags.
477  uint32_t m_addr_size; ///< Size of an address in bytes.
479  m_byte_order; ///< Byte order to use when encoding scalar types.
480  int m_indent_level; ///< Indention level.
481  std::size_t m_bytes_written = 0; ///< Number of bytes written so far.
482 
483  void _PutHex8(uint8_t uvalue, bool add_prefix);
484 
485  /// Output character bytes to the stream.
486  ///
487  /// Appends \a src_len characters from the buffer \a src to the stream.
488  ///
489  /// \param[in] src
490  /// A buffer containing at least \a src_len bytes of data.
491  ///
492  /// \param[in] src_len
493  /// A number of bytes to append to the stream.
494  ///
495  /// \return
496  /// The number of bytes that were appended to the stream.
497  virtual size_t WriteImpl(const void *src, size_t src_len) = 0;
498 
499  /// \class RawOstreamForward Stream.h "lldb/Utility/Stream.h"
500  /// This is a wrapper class that exposes a raw_ostream interface that just
501  /// forwards to an LLDB stream, allowing to reuse LLVM algorithms that take
502  /// a raw_ostream within the LLDB code base.
503  class RawOstreamForward : public llvm::raw_ostream {
504  // Note: This stream must *not* maintain its own buffer, but instead
505  // directly write everything to the internal Stream class. Without this,
506  // we would run into the problem that the Stream written byte count would
507  // differ from the actually written bytes by the size of the internal
508  // raw_ostream buffer.
509 
510  Stream &m_target;
511  void write_impl(const char *Ptr, size_t Size) override {
512  m_target.Write(Ptr, Size);
513  }
514 
515  uint64_t current_pos() const override {
516  return m_target.GetWrittenBytes();
517  }
518 
519  public:
521  : llvm::raw_ostream(/*unbuffered*/ true), m_target(target) {}
522  };
524 };
525 
526 } // namespace lldb_private
527 
528 #endif // liblldb_Stream_h_
void Address(uint64_t addr, uint32_t addr_size, const char *prefix=nullptr, const char *suffix=nullptr)
Output an address value to this stream.
Definition: Stream.cpp:79
size_t PutCString(llvm::StringRef cstr)
Output a C string to the stream.
Definition: Stream.cpp:61
Stream & operator<<(const char *cstr)
Output a NULL terminated C string cstr to the stream s.
Definition: Stream.cpp:147
A command line argument class.
Definition: Args.h:32
Get and put data as binary instead of as the default string mode.
Definition: Stream.h:32
llvm::raw_ostream & AsRawOstream()
Returns a raw_ostream that forwards the data to this Stream object.
Definition: Stream.h:470
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
Definition: Debugger.h:71
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
uint32_t m_addr_size
Size of an address in bytes.
Definition: Stream.h:477
size_t PutHex16(uint16_t uvalue, lldb::ByteOrder byte_order=lldb::eByteOrderInvalid)
Definition: Stream.cpp:290
Flags & GetFlags()
The flags accessor.
Definition: Stream.cpp:235
void SetAddressByteSize(uint32_t addr_size)
Set the address size in bytes.
Definition: Stream.cpp:232
size_t GetWrittenBytes() const
Definition: Stream.h:106
size_t PutDouble(double d, lldb::ByteOrder byte_order=lldb::eByteOrderInvalid)
Definition: Stream.cpp:365
Stream(const Stream &other)
Definition: Stream.h:67
void SetIndentLevel(int level)
Set the current indentation level.
Definition: Stream.cpp:215
virtual void Flush()=0
Flush the stream.
void AddressRange(uint64_t lo_addr, uint64_t hi_addr, uint32_t addr_size, const char *prefix=nullptr, const char *suffix=nullptr)
Output an address range to this stream.
Definition: Stream.cpp:92
size_t Write(const void *src, size_t src_len)
Output character bytes to the stream.
Definition: Stream.h:100
Stream & operator=(const Stream &rhs)
Definition: Stream.h:69
size_t size_t PrintfVarArg(const char *format, va_list args)
Definition: Stream.cpp:115
size_t PutMaxHex64(uint64_t uvalue, size_t byte_size, lldb::ByteOrder byte_order=lldb::eByteOrderInvalid)
Definition: Stream.cpp:338
virtual ~Stream()
Destructor.
Definition: Stream.cpp:33
lldb::ByteOrder GetByteOrder() const
Definition: Stream.cpp:242
void Format(const char *format, Args &&... args)
Definition: Stream.h:422
size_t PutStringAsRawHex8(llvm::StringRef s)
Definition: Stream.cpp:432
int GetIndentLevel() const
Get the current indentation level.
Definition: Stream.cpp:212
Stream()
Construct a default Stream, not binary, host byte order and host addr size.
Definition: Stream.cpp:28
size_t EOL()
Output and End of Line character to the stream.
Definition: Stream.cpp:127
size_t PutHex32(uint32_t uvalue, lldb::ByteOrder byte_order=lldb::eByteOrderInvalid)
Definition: Stream.cpp:306
void IndentLess(int amount=2)
Decrement the current indentation level.
Definition: Stream.cpp:221
size_t Printf(const char *format,...) __attribute__((format(printf
Output printf formatted output to the stream.
Definition: Stream.cpp:106
size_t PutHex64(uint64_t uvalue, lldb::ByteOrder byte_order=lldb::eByteOrderInvalid)
Definition: Stream.cpp:322
int m_indent_level
Indention level.
Definition: Stream.h:480
size_t PutLongDouble(long double ld, lldb::ByteOrder byte_order=lldb::eByteOrderInvalid)
Definition: Stream.cpp:372
lldb::ByteOrder m_byte_order
Byte order to use when encoding scalar types.
Definition: Stream.h:479
void QuotedCString(const char *cstr, const char *format="\s\)
Output a quoted C string value to the stream.
Definition: Stream.cpp:73
size_t PrintfAsRawHex8(const char *format,...) __attribute__((__format__(__printf__
Format a C string from a printf style format and variable arguments and encode and append the resulti...
Definition: Stream.cpp:244
size_t PutChar(char ch)
Definition: Stream.cpp:103
A class to manage flags.
Definition: Flags.h:22
size_t PutNHex8(size_t n, uint8_t uvalue)
Definition: Stream.cpp:260
RawOstreamForward m_forwarder
Definition: Stream.h:523
size_t size_t PutHex8(uint8_t uvalue)
Append an uint8_t value in the hexadecimal format to the stream.
Definition: Stream.cpp:284
size_t operator*() const
Returns the number of bytes written to the given Stream since this ByteDelta object was created...
Definition: Stream.h:52
Flags m_flags
Dump flags.
Definition: Stream.h:476
size_t Indent(const char *s=nullptr)
Indent the current line in the stream.
Definition: Stream.cpp:131
void Offset(uint32_t offset, const char *format="0x%8.8x: ")
Output an offset value.
Definition: Stream.cpp:42
uint32_t GetAddressByteSize() const
Get the address size in bytes.
Definition: Stream.cpp:229
size_t PutSLEB128(int64_t uval)
Output a SLEB128 number to the stream.
Definition: Stream.cpp:45
size_t PutULEB128(uint64_t uval)
Output a ULEB128 number to the stream.
Definition: Stream.cpp:53
void IndentMore(int amount=2)
Increment the current indentation level.
Definition: Stream.cpp:218
lldb::ByteOrder SetByteOrder(lldb::ByteOrder byte_order)
Set the byte_order value.
Definition: Stream.cpp:35
virtual size_t WriteImpl(const void *src, size_t src_len)=0
Output character bytes to the stream.
size_t PutPointer(void *ptr)
Definition: Stream.cpp:353
std::size_t m_bytes_written
Number of bytes written so far.
Definition: Stream.h:481
size_t PutBytesAsRawHex8(const void *src, size_t src_len, lldb::ByteOrder src_byte_order=lldb::eByteOrderInvalid, lldb::ByteOrder dst_byte_order=lldb::eByteOrderInvalid)
Definition: Stream.cpp:406
size_t PutRawBytes(const void *s, size_t src_len, lldb::ByteOrder src_byte_order=lldb::eByteOrderInvalid, lldb::ByteOrder dst_byte_order=lldb::eByteOrderInvalid)
Definition: Stream.cpp:379
void _PutHex8(uint8_t uvalue, bool add_prefix)
Definition: Stream.cpp:267
This is a wrapper class that exposes a raw_ostream interface that just forwards to an LLDB stream...
Definition: Stream.h:503
size_t PutFloat(float f, lldb::ByteOrder byte_order=lldb::eByteOrderInvalid)
Definition: Stream.cpp:358