contrib/llvm/tools/lldb/include/lldb/Utility/Stream.h

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