diff options
Diffstat (limited to 'include/lldb/Host/File.h')
| -rw-r--r-- | include/lldb/Host/File.h | 141 |
1 files changed, 51 insertions, 90 deletions
diff --git a/include/lldb/Host/File.h b/include/lldb/Host/File.h index 69ae2004e4222..eb28c4ada0e71 100644 --- a/include/lldb/Host/File.h +++ b/include/lldb/Host/File.h @@ -1,9 +1,8 @@ //===-- File.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 // //===----------------------------------------------------------------------===// @@ -15,19 +14,18 @@ #include "lldb/Utility/Status.h" #include "lldb/lldb-private.h" +#include <mutex> #include <stdarg.h> #include <stdio.h> #include <sys/types.h> namespace lldb_private { -//---------------------------------------------------------------------- -/// @class File File.h "lldb/Host/File.h" +/// \class File File.h "lldb/Host/File.h" /// A file class. /// /// A file class that divides abstracts the LLDB core from host file /// functionality. -//---------------------------------------------------------------------- class File : public IOObject { public: static int kInvalidDescriptor; @@ -72,59 +70,51 @@ public: m_is_interactive(eLazyBoolCalculate), m_is_real_terminal(eLazyBoolCalculate) {} - //------------------------------------------------------------------ /// Destructor. /// /// The destructor is virtual in case this class is subclassed. - //------------------------------------------------------------------ ~File() override; bool IsValid() const override { return DescriptorIsValid() || StreamIsValid(); } - //------------------------------------------------------------------ /// Convert to pointer operator. /// /// This allows code to check a File object to see if it contains anything /// valid using code such as: /// - /// @code + /// \code /// File file(...); /// if (file) /// { ... - /// @endcode + /// \endcode /// - /// @return + /// \return /// A pointer to this object if either the directory or filename /// is valid, nullptr otherwise. - //------------------------------------------------------------------ operator bool() const { return DescriptorIsValid() || StreamIsValid(); } - //------------------------------------------------------------------ /// Logical NOT operator. /// /// This allows code to check a File object to see if it is invalid using /// code such as: /// - /// @code + /// \code /// File file(...); /// if (!file) /// { ... - /// @endcode + /// \endcode /// - /// @return + /// \return /// Returns \b true if the object has an empty directory and /// filename, \b false otherwise. - //------------------------------------------------------------------ bool operator!() const { return !DescriptorIsValid() && !StreamIsValid(); } - //------------------------------------------------------------------ /// Get the file spec for this file. /// - /// @return + /// \return /// A reference to the file specification object. - //------------------------------------------------------------------ Status GetFileSpec(FileSpec &file_spec) const; Status Close() override; @@ -141,172 +131,157 @@ public: void SetStream(FILE *fh, bool transfer_ownership); - //------------------------------------------------------------------ /// Read bytes from a file from the current file position. /// /// NOTE: This function is NOT thread safe. Use the read function /// that takes an "off_t &offset" to ensure correct operation in multi- /// threaded environments. /// - /// @param[in] buf + /// \param[in] buf /// A buffer where to put the bytes that are read. /// - /// @param[in,out] num_bytes + /// \param[in,out] num_bytes /// The number of bytes to read form the current file position /// which gets modified with the number of bytes that were read. /// - /// @return + /// \return /// An error object that indicates success or the reason for /// failure. - //------------------------------------------------------------------ Status Read(void *buf, size_t &num_bytes) override; - //------------------------------------------------------------------ /// Write bytes to a file at the current file position. /// /// NOTE: This function is NOT thread safe. Use the write function /// that takes an "off_t &offset" to ensure correct operation in multi- /// threaded environments. /// - /// @param[in] buf + /// \param[in] buf /// A buffer where to put the bytes that are read. /// - /// @param[in,out] num_bytes + /// \param[in,out] num_bytes /// The number of bytes to write to the current file position /// which gets modified with the number of bytes that were /// written. /// - /// @return + /// \return /// An error object that indicates success or the reason for /// failure. - //------------------------------------------------------------------ Status Write(const void *buf, size_t &num_bytes) override; - //------------------------------------------------------------------ /// Seek to an offset relative to the beginning of the file. /// /// NOTE: This function is NOT thread safe, other threads that /// access this object might also change the current file position. For /// thread safe reads and writes see the following functions: @see - /// File::Read (void *, size_t, off_t &) @see File::Write (const void *, + /// File::Read (void *, size_t, off_t &) \see File::Write (const void *, /// size_t, off_t &) /// - /// @param[in] offset + /// \param[in] offset /// The offset to seek to within the file relative to the /// beginning of the file. /// - /// @param[in] error_ptr + /// \param[in] error_ptr /// A pointer to a lldb_private::Status object that will be /// filled in if non-nullptr. /// - /// @return + /// \return /// The resulting seek offset, or -1 on error. - //------------------------------------------------------------------ off_t SeekFromStart(off_t offset, Status *error_ptr = nullptr); - //------------------------------------------------------------------ /// Seek to an offset relative to the current file position. /// /// NOTE: This function is NOT thread safe, other threads that /// access this object might also change the current file position. For /// thread safe reads and writes see the following functions: @see - /// File::Read (void *, size_t, off_t &) @see File::Write (const void *, + /// File::Read (void *, size_t, off_t &) \see File::Write (const void *, /// size_t, off_t &) /// - /// @param[in] offset + /// \param[in] offset /// The offset to seek to within the file relative to the /// current file position. /// - /// @param[in] error_ptr + /// \param[in] error_ptr /// A pointer to a lldb_private::Status object that will be /// filled in if non-nullptr. /// - /// @return + /// \return /// The resulting seek offset, or -1 on error. - //------------------------------------------------------------------ off_t SeekFromCurrent(off_t offset, Status *error_ptr = nullptr); - //------------------------------------------------------------------ /// Seek to an offset relative to the end of the file. /// /// NOTE: This function is NOT thread safe, other threads that /// access this object might also change the current file position. For /// thread safe reads and writes see the following functions: @see - /// File::Read (void *, size_t, off_t &) @see File::Write (const void *, + /// File::Read (void *, size_t, off_t &) \see File::Write (const void *, /// size_t, off_t &) /// - /// @param[in,out] offset + /// \param[in,out] offset /// The offset to seek to within the file relative to the /// end of the file which gets filled in with the resulting /// absolute file offset. /// - /// @param[in] error_ptr + /// \param[in] error_ptr /// A pointer to a lldb_private::Status object that will be /// filled in if non-nullptr. /// - /// @return + /// \return /// The resulting seek offset, or -1 on error. - //------------------------------------------------------------------ off_t SeekFromEnd(off_t offset, Status *error_ptr = nullptr); - //------------------------------------------------------------------ /// Read bytes from a file from the specified file offset. /// /// NOTE: This function is thread safe in that clients manager their /// own file position markers and reads on other threads won't mess up the /// current read. /// - /// @param[in] dst + /// \param[in] dst /// A buffer where to put the bytes that are read. /// - /// @param[in,out] num_bytes + /// \param[in,out] num_bytes /// The number of bytes to read form the current file position /// which gets modified with the number of bytes that were read. /// - /// @param[in,out] offset + /// \param[in,out] offset /// The offset within the file from which to read \a num_bytes /// bytes. This offset gets incremented by the number of bytes /// that were read. /// - /// @return + /// \return /// An error object that indicates success or the reason for /// failure. - //------------------------------------------------------------------ Status Read(void *dst, size_t &num_bytes, off_t &offset); - //------------------------------------------------------------------ /// Read bytes from a file from the specified file offset. /// /// NOTE: This function is thread safe in that clients manager their /// own file position markers and reads on other threads won't mess up the /// current read. /// - /// @param[in,out] num_bytes + /// \param[in,out] num_bytes /// The number of bytes to read form the current file position /// which gets modified with the number of bytes that were read. /// - /// @param[in,out] offset + /// \param[in,out] offset /// The offset within the file from which to read \a num_bytes /// bytes. This offset gets incremented by the number of bytes /// that were read. /// - /// @param[in] null_terminate + /// \param[in] null_terminate /// Ensure that the data that is read is terminated with a NULL /// character so that the data can be used as a C string. /// - /// @param[out] data_buffer_sp + /// \param[out] data_buffer_sp /// A data buffer to create and fill in that will contain any /// data that is read from the file. This buffer will be reset /// if an error occurs. /// - /// @return + /// \return /// An error object that indicates success or the reason for /// failure. - //------------------------------------------------------------------ Status Read(size_t &num_bytes, off_t &offset, bool null_terminate, lldb::DataBufferSP &data_buffer_sp); - //------------------------------------------------------------------ /// Write bytes to a file at the specified file offset. /// /// NOTE: This function is thread safe in that clients manager their @@ -314,88 +289,75 @@ public: /// own locking externally to avoid multiple people writing to the file at /// the same time. /// - /// @param[in] src + /// \param[in] src /// A buffer containing the bytes to write. /// - /// @param[in,out] num_bytes + /// \param[in,out] num_bytes /// The number of bytes to write to the file at offset \a offset. /// \a num_bytes gets modified with the number of bytes that /// were read. /// - /// @param[in,out] offset + /// \param[in,out] offset /// The offset within the file at which to write \a num_bytes /// bytes. This offset gets incremented by the number of bytes /// that were written. /// - /// @return + /// \return /// An error object that indicates success or the reason for /// failure. - //------------------------------------------------------------------ Status Write(const void *src, size_t &num_bytes, off_t &offset); - //------------------------------------------------------------------ /// Flush the current stream /// - /// @return + /// \return /// An error object that indicates success or the reason for /// failure. - //------------------------------------------------------------------ Status Flush(); - //------------------------------------------------------------------ /// Sync to disk. /// - /// @return + /// \return /// An error object that indicates success or the reason for /// failure. - //------------------------------------------------------------------ Status Sync(); - //------------------------------------------------------------------ /// Get the permissions for a this file. /// - /// @return + /// \return /// Bits logical OR'ed together from the permission bits defined /// in lldb_private::File::Permissions. - //------------------------------------------------------------------ uint32_t GetPermissions(Status &error) const; - //------------------------------------------------------------------ /// Return true if this file is interactive. /// - /// @return + /// \return /// True if this file is a terminal (tty or pty), false /// otherwise. - //------------------------------------------------------------------ bool GetIsInteractive(); - //------------------------------------------------------------------ /// Return true if this file from a real terminal. /// /// Just knowing a file is a interactive isn't enough, we also need to know /// if the terminal has a width and height so we can do cursor movement and /// other terminal manipulations by sending escape sequences. /// - /// @return + /// \return /// True if this file is a terminal (tty, not a pty) that has /// a non-zero width and height, false otherwise. - //------------------------------------------------------------------ bool GetIsRealTerminal(); bool GetIsTerminalWithColors(); - //------------------------------------------------------------------ /// 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); @@ -411,9 +373,7 @@ protected: void CalculateInteractiveAndTerminal(); - //------------------------------------------------------------------ // Member variables - //------------------------------------------------------------------ int m_descriptor; FILE *m_stream; uint32_t m_options; @@ -421,6 +381,7 @@ protected: LazyBool m_is_interactive; LazyBool m_is_real_terminal; LazyBool m_supports_colors; + std::mutex offset_access_mutex; private: DISALLOW_COPY_AND_ASSIGN(File); |