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