diff options
Diffstat (limited to 'include/lldb/Utility/Stream.h')
| -rw-r--r-- | include/lldb/Utility/Stream.h | 231 |
1 files changed, 69 insertions, 162 deletions
diff --git a/include/lldb/Utility/Stream.h b/include/lldb/Utility/Stream.h index bd4283edf8a9..b24d4e457177 100644 --- a/include/lldb/Utility/Stream.h +++ b/include/lldb/Utility/Stream.h @@ -1,9 +1,8 @@ //===-- Stream.h ------------------------------------------------*- C++ -*-===// // -// The LLVM Compiler Infrastructure -// -// This file is distributed under the University of Illinois Open Source -// License. See LICENSE.TXT for details. +// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. +// See https://llvm.org/LICENSE.txt for license information. +// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception // //===----------------------------------------------------------------------===// @@ -24,15 +23,11 @@ namespace lldb_private { -//---------------------------------------------------------------------- -/// @class Stream Stream.h "lldb/Utility/Stream.h" +/// \class Stream Stream.h "lldb/Utility/Stream.h" /// A stream class that can stream formatted output to a file. -//---------------------------------------------------------------------- class Stream { public: - //------------------------------------------------------------------ /// \a m_flags bit values. - //------------------------------------------------------------------ enum { eBinary = (1 << 0) ///< Get and put data as binary instead of as the default /// string mode. @@ -40,11 +35,11 @@ public: /// Utility class for counting the bytes that were written to a stream in a /// certain time span. - /// @example + /// \example /// ByteDelta delta(*this); /// WriteDataToStream("foo"); /// return *delta; - /// @endcode + /// \endcode class ByteDelta { Stream *m_stream; /// Bytes we have written so far when ByteDelta was created. @@ -57,19 +52,15 @@ public: size_t operator*() const { return m_stream->GetWrittenBytes() - m_start; } }; - //------------------------------------------------------------------ /// Construct with flags and address size and byte order. /// /// Construct with dump flags \a flags and the default address size. \a /// flags can be any of the above enumeration logical OR'ed together. - //------------------------------------------------------------------ Stream(uint32_t flags, uint32_t addr_size, lldb::ByteOrder byte_order); - //------------------------------------------------------------------ /// Construct a default Stream, not binary, host byte order and host addr /// size. /// - //------------------------------------------------------------------ Stream(); // FIXME: Streams should not be copyable. @@ -83,37 +74,29 @@ public: return *this; } - //------------------------------------------------------------------ /// Destructor - //------------------------------------------------------------------ virtual ~Stream(); - //------------------------------------------------------------------ // Subclasses must override these methods - //------------------------------------------------------------------ - //------------------------------------------------------------------ /// Flush the stream. /// /// Subclasses should flush the stream to make any output appear if the /// stream has any buffering. - //------------------------------------------------------------------ virtual void Flush() = 0; - //------------------------------------------------------------------ /// Output character bytes to the stream. /// /// Appends \a src_len characters from the buffer \a src to the stream. /// - /// @param[in] src + /// \param[in] src /// A buffer containing at least \a src_len bytes of data. /// - /// @param[in] src_len + /// \param[in] src_len /// A number of bytes to append to the stream. /// - /// @return + /// \return /// The number of bytes that were appended to the stream. - //------------------------------------------------------------------ size_t Write(const void *src, size_t src_len) { size_t appended_byte_count = WriteImpl(src, src_len); m_bytes_written += appended_byte_count; @@ -122,50 +105,42 @@ public: size_t GetWrittenBytes() const { return m_bytes_written; } - //------------------------------------------------------------------ // Member functions - //------------------------------------------------------------------ size_t PutChar(char ch); - //------------------------------------------------------------------ /// Set the byte_order value. /// /// Sets the byte order of the data to extract. Extracted values will be /// swapped if necessary when decoding. /// - /// @param[in] byte_order + /// \param[in] byte_order /// The byte order value to use when extracting data. /// - /// @return + /// \return /// The old byte order value. - //------------------------------------------------------------------ lldb::ByteOrder SetByteOrder(lldb::ByteOrder byte_order); - //------------------------------------------------------------------ /// Format a C string from a printf style format and variable arguments and /// encode and append the resulting C string as hex bytes. /// - /// @param[in] format + /// \param[in] format /// A printf style format string. /// - /// @param[in] ... + /// \param[in] ... /// Any additional arguments needed for the printf format string. /// - /// @return + /// \return /// The number of bytes that were appended to the stream. - //------------------------------------------------------------------ size_t PrintfAsRawHex8(const char *format, ...) __attribute__((__format__(__printf__, 2, 3))); - //------------------------------------------------------------------ /// Append an uint8_t value in the hexadecimal format to the stream. /// - /// @param[in] uvalue + /// \param[in] uvalue /// The value to append. /// - /// @return + /// \return /// The number of bytes that were appended to the stream. - //------------------------------------------------------------------ size_t PutHex8(uint8_t uvalue); size_t PutNHex8(size_t n, uint8_t uvalue); @@ -204,292 +179,242 @@ public: lldb::ByteOrder src_byte_order = lldb::eByteOrderInvalid, lldb::ByteOrder dst_byte_order = lldb::eByteOrderInvalid); - size_t PutCStringAsRawHex8(const char *s); + size_t PutStringAsRawHex8(llvm::StringRef s); - //------------------------------------------------------------------ /// Output a NULL terminated C string \a cstr to the stream \a s. /// - /// @param[in] cstr + /// \param[in] cstr /// A NULL terminated C string. /// - /// @return + /// \return /// A reference to this class so multiple things can be streamed /// in one statement. - //------------------------------------------------------------------ Stream &operator<<(const char *cstr); Stream &operator<<(llvm::StringRef str); - //------------------------------------------------------------------ /// Output a pointer value \a p to the stream \a s. /// - /// @param[in] p + /// \param[in] p /// A void pointer. /// - /// @return + /// \return /// A reference to this class so multiple things can be streamed /// in one statement. - //------------------------------------------------------------------ Stream &operator<<(const void *p); - //------------------------------------------------------------------ /// Output a character \a ch to the stream \a s. /// - /// @param[in] ch + /// \param[in] ch /// A printable character value. /// - /// @return + /// \return /// A reference to this class so multiple things can be streamed /// in one statement. - //------------------------------------------------------------------ Stream &operator<<(char ch); - //------------------------------------------------------------------ /// Output a uint8_t \a uval to the stream \a s. /// - /// @param[in] uval + /// \param[in] uval /// A uint8_t value. /// - /// @return + /// \return /// A reference to this class so multiple things can be streamed /// in one statement. - //------------------------------------------------------------------ Stream &operator<<(uint8_t uval); - //------------------------------------------------------------------ /// Output a uint16_t \a uval to the stream \a s. /// - /// @param[in] uval + /// \param[in] uval /// A uint16_t value. /// - /// @return + /// \return /// A reference to this class so multiple things can be streamed /// in one statement. - //------------------------------------------------------------------ Stream &operator<<(uint16_t uval); - //------------------------------------------------------------------ /// Output a uint32_t \a uval to the stream \a s. /// - /// @param[in] uval + /// \param[in] uval /// A uint32_t value. /// - /// @return + /// \return /// A reference to this class so multiple things can be streamed /// in one statement. - //------------------------------------------------------------------ Stream &operator<<(uint32_t uval); - //------------------------------------------------------------------ /// Output a uint64_t \a uval to the stream \a s. /// - /// @param[in] uval + /// \param[in] uval /// A uint64_t value. /// - /// @return + /// \return /// A reference to this class so multiple things can be streamed /// in one statement. - //------------------------------------------------------------------ Stream &operator<<(uint64_t uval); - //------------------------------------------------------------------ /// Output a int8_t \a sval to the stream \a s. /// - /// @param[in] sval + /// \param[in] sval /// A int8_t value. /// - /// @return + /// \return /// A reference to this class so multiple things can be streamed /// in one statement. - //------------------------------------------------------------------ Stream &operator<<(int8_t sval); - //------------------------------------------------------------------ /// Output a int16_t \a sval to the stream \a s. /// - /// @param[in] sval + /// \param[in] sval /// A int16_t value. /// - /// @return + /// \return /// A reference to this class so multiple things can be streamed /// in one statement. - //------------------------------------------------------------------ Stream &operator<<(int16_t sval); - //------------------------------------------------------------------ /// Output a int32_t \a sval to the stream \a s. /// - /// @param[in] sval + /// \param[in] sval /// A int32_t value. /// - /// @return + /// \return /// A reference to this class so multiple things can be streamed /// in one statement. - //------------------------------------------------------------------ Stream &operator<<(int32_t sval); - //------------------------------------------------------------------ /// Output a int64_t \a sval to the stream \a s. /// - /// @param[in] sval + /// \param[in] sval /// A int64_t value. /// - /// @return + /// \return /// A reference to this class so multiple things can be streamed /// in one statement. - //------------------------------------------------------------------ Stream &operator<<(int64_t sval); - //------------------------------------------------------------------ /// Output an address value to this stream. /// /// Put an address \a addr out to the stream with optional \a prefix and \a /// suffix strings. /// - /// @param[in] addr + /// \param[in] addr /// An address value. /// - /// @param[in] addr_size + /// \param[in] addr_size /// Size in bytes of the address, used for formatting. /// - /// @param[in] prefix + /// \param[in] prefix /// A prefix C string. If nullptr, no prefix will be output. /// - /// @param[in] suffix + /// \param[in] suffix /// A suffix C string. If nullptr, no suffix will be output. - //------------------------------------------------------------------ void Address(uint64_t addr, uint32_t addr_size, const char *prefix = nullptr, const char *suffix = nullptr); - //------------------------------------------------------------------ /// Output an address range to this stream. /// /// Put an address range \a lo_addr - \a hi_addr out to the stream with /// optional \a prefix and \a suffix strings. /// - /// @param[in] lo_addr + /// \param[in] lo_addr /// The start address of the address range. /// - /// @param[in] hi_addr + /// \param[in] hi_addr /// The end address of the address range. /// - /// @param[in] addr_size + /// \param[in] addr_size /// Size in bytes of the address, used for formatting. /// - /// @param[in] prefix + /// \param[in] prefix /// A prefix C string. If nullptr, no prefix will be output. /// - /// @param[in] suffix + /// \param[in] suffix /// A suffix C string. If nullptr, no suffix will be output. - //------------------------------------------------------------------ void AddressRange(uint64_t lo_addr, uint64_t hi_addr, uint32_t addr_size, const char *prefix = nullptr, const char *suffix = nullptr); - //------------------------------------------------------------------ /// Output a C string to the stream. /// /// Print a C string \a cstr to the stream. /// - /// @param[in] cstr + /// \param[in] cstr /// The string to be output to the stream. - //------------------------------------------------------------------ size_t PutCString(llvm::StringRef cstr); - //------------------------------------------------------------------ /// Output and End of Line character to the stream. - //------------------------------------------------------------------ size_t EOL(); - //------------------------------------------------------------------ /// Get the address size in bytes. /// - /// @return + /// \return /// The size of an address in bytes that is used when outputting /// address and pointer values to the stream. - //------------------------------------------------------------------ uint32_t GetAddressByteSize() const; - //------------------------------------------------------------------ /// The flags accessor. /// - /// @return + /// \return /// A reference to the Flags member variable. - //------------------------------------------------------------------ Flags &GetFlags(); - //------------------------------------------------------------------ /// The flags const accessor. /// - /// @return + /// \return /// A const reference to the Flags member variable. - //------------------------------------------------------------------ const Flags &GetFlags() const; - //------------------------------------------------------------------ //// The byte order accessor. //// - //// @return + //// \return //// The byte order. - //------------------------------------------------------------------ lldb::ByteOrder GetByteOrder() const; - //------------------------------------------------------------------ /// Get the current indentation level. /// - /// @return + /// \return /// The current indentation level as an integer. - //------------------------------------------------------------------ int GetIndentLevel() const; - //------------------------------------------------------------------ /// Indent the current line in the stream. /// /// Indent the current line using the current indentation level and print an /// optional string following the indentation spaces. /// - /// @param[in] s + /// \param[in] s /// A C string to print following the indentation. If nullptr, just /// output the indentation characters. - //------------------------------------------------------------------ size_t Indent(const char *s = nullptr); size_t Indent(llvm::StringRef s); - //------------------------------------------------------------------ /// Decrement the current indentation level. - //------------------------------------------------------------------ void IndentLess(int amount = 2); - //------------------------------------------------------------------ /// Increment the current indentation level. - //------------------------------------------------------------------ void IndentMore(int amount = 2); - //------------------------------------------------------------------ /// Output an offset value. /// /// Put an offset \a uval out to the stream using the printf format in \a /// format. /// - /// @param[in] offset + /// \param[in] offset /// The offset value. /// - /// @param[in] format + /// \param[in] format /// The printf style format to use when outputting the offset. - //------------------------------------------------------------------ void Offset(uint32_t offset, const char *format = "0x%8.8x: "); - //------------------------------------------------------------------ /// Output printf formatted output to the stream. /// /// Print some formatted output to the stream. /// - /// @param[in] format + /// \param[in] format /// A printf style format string. /// - /// @param[in] ... + /// \param[in] ... /// Variable arguments that are needed for the printf style /// format string \a format. - //------------------------------------------------------------------ size_t Printf(const char *format, ...) __attribute__((format(printf, 2, 3))); size_t PrintfVarArg(const char *format, va_list args); @@ -498,70 +423,56 @@ public: PutCString(llvm::formatv(format, std::forward<Args>(args)...).str()); } - //------------------------------------------------------------------ /// Output a quoted C string value to the stream. /// /// Print a double quoted NULL terminated C string to the stream using the /// printf format in \a format. /// - /// @param[in] cstr + /// \param[in] cstr /// A NULL terminated C string value. /// - /// @param[in] format + /// \param[in] format /// The optional C string format that can be overridden. - //------------------------------------------------------------------ void QuotedCString(const char *cstr, const char *format = "\"%s\""); - //------------------------------------------------------------------ /// Set the address size in bytes. /// - /// @param[in] addr_size + /// \param[in] addr_size /// The new size in bytes of an address to use when outputting /// address and pointer values. - //------------------------------------------------------------------ void SetAddressByteSize(uint32_t addr_size); - //------------------------------------------------------------------ /// Set the current indentation level. /// - /// @param[in] level + /// \param[in] level /// The new indentation level. - //------------------------------------------------------------------ void SetIndentLevel(int level); - //------------------------------------------------------------------ /// Output a SLEB128 number to the stream. /// /// Put an SLEB128 \a uval out to the stream using the printf format in \a /// format. /// - /// @param[in] uval + /// \param[in] uval /// A uint64_t value that was extracted as a SLEB128 value. - //------------------------------------------------------------------ size_t PutSLEB128(int64_t uval); - //------------------------------------------------------------------ /// Output a ULEB128 number to the stream. /// /// Put an ULEB128 \a uval out to the stream using the printf format in \a /// format. /// - /// @param[in] uval + /// \param[in] uval /// A uint64_t value that was extracted as a ULEB128 value. - //------------------------------------------------------------------ size_t PutULEB128(uint64_t uval); - //------------------------------------------------------------------ /// Returns a raw_ostream that forwards the data to this Stream object. - //------------------------------------------------------------------ llvm::raw_ostream &AsRawOstream() { return m_forwarder; } protected: - //------------------------------------------------------------------ // Member variables - //------------------------------------------------------------------ Flags m_flags; ///< Dump flags. uint32_t m_addr_size; ///< Size of an address in bytes. lldb::ByteOrder @@ -571,28 +482,24 @@ protected: void _PutHex8(uint8_t uvalue, bool add_prefix); - //------------------------------------------------------------------ /// Output character bytes to the stream. /// /// Appends \a src_len characters from the buffer \a src to the stream. /// - /// @param[in] src + /// \param[in] src /// A buffer containing at least \a src_len bytes of data. /// - /// @param[in] src_len + /// \param[in] src_len /// A number of bytes to append to the stream. /// - /// @return + /// \return /// The number of bytes that were appended to the stream. - //------------------------------------------------------------------ virtual size_t WriteImpl(const void *src, size_t src_len) = 0; - //---------------------------------------------------------------------- - /// @class RawOstreamForward Stream.h "lldb/Utility/Stream.h" + /// \class RawOstreamForward Stream.h "lldb/Utility/Stream.h" /// This is a wrapper class that exposes a raw_ostream interface that just /// forwards to an LLDB stream, allowing to reuse LLVM algorithms that take /// a raw_ostream within the LLDB code base. - //---------------------------------------------------------------------- class RawOstreamForward : public llvm::raw_ostream { // Note: This stream must *not* maintain its own buffer, but instead // directly write everything to the internal Stream class. Without this, |