LLDB mainline
lldb_private::NativeFileBase Class Referenceabstract

Common base for the platform-specific NativeFile implementations. More...

#include "lldb/Host/File.h"

Inheritance diagram for lldb_private::NativeFileBase:
[legend]

Classes

struct  ValueGuard

Public Types

enum  TransferOwnership : bool { Owned = true , Unowned = false }
Public Types inherited from lldb_private::File
enum  OpenOptions : uint32_t {
  eOpenOptionReadOnly = 0x0 , eOpenOptionWriteOnly = 0x1 , eOpenOptionReadWrite = 0x2 , eOpenOptionAppend ,
  eOpenOptionCanCreate = 0x200 , eOpenOptionTruncate = 0x400 , eOpenOptionCanCreateNewOnly , eOpenOptionNonBlocking = (1u << 28) ,
  eOpenOptionDontFollowSymlinks = (1u << 29) , eOpenOptionCloseOnExec , eOpenOptionInvalid = (1u << 31)
}
Public Types inherited from lldb_private::IOObject
enum  FDType { eFDTypeFile , eFDTypeSocket }
using WaitableHandle = lldb::file_t

Public Member Functions

bool IsValid () const override
 IsValid.
Status Read (void *buf, size_t &num_bytes) override
 Read bytes from a file from the current file position into buf.
Status Write (const void *buf, size_t &num_bytes) override
 Write bytes from buf to a file at the current file position.
Status Close () override
 Flush any buffers and release any resources owned by the file.
WaitableHandle GetWaitableHandle () override
 Get a handle that can be used for OS polling interfaces, such as WaitForMultipleObjects, select, or epoll.
Status GetFileSpec (FileSpec &file_spec) const override
 Get the file specification for this file, if possible.
int GetDescriptor () const override
 Get underlying OS file descriptor for this file, or kInvalidDescriptor.
FILE * GetStream () override
 Get the underlying libc stream for this file, or NULL.
off_t SeekFromStart (off_t offset, Status *error_ptr=nullptr) override
 Seek to an offset relative to the beginning of the file.
off_t SeekFromCurrent (off_t offset, Status *error_ptr=nullptr) override
 Seek to an offset relative to the current file position.
off_t SeekFromEnd (off_t offset, Status *error_ptr=nullptr) override
 Seek to an offset relative to the end of the file.
virtual Status Read (void *dst, size_t &num_bytes, off_t &offset) override=0
 Read bytes from a file from the specified file offset.
virtual Status Write (const void *src, size_t &num_bytes, off_t &offset) override=0
 Write bytes to a file at the specified file offset.
Status Flush () override
 Flush the current stream.
virtual Status Sync () override=0
 Sync to disk.
size_t PrintfVarArg (const char *format, va_list args) override
 Output printf formatted output to the stream.
llvm::Expected< OpenOptionsGetOptions () const override
 Return the OpenOptions for this file.
bool isA (const void *classID) const override
Public Member Functions inherited from lldb_private::File
 File ()
size_t Printf (const char *format,...) __attribute__((format(printf
 Output printf formatted output to the stream.
llvm::Expected< const char * > GetOpenMode () const
uint32_t GetPermissions (Status &error) const
 Get the permissions for a this file.
bool GetIsInteractive ()
 Return true if this file is interactive.
bool GetIsRealTerminal ()
 Return true if this file from a real terminal.
bool GetIsTerminalWithColors ()
 Return true if this file is a terminal which supports colors.
 operator bool () const
bool operator! () const
Public Member Functions inherited from lldb_private::IOObject
 IOObject (FDType type)
virtual ~IOObject ()
FDType GetFdType () const

Static Public Member Functions

static bool classof (const File *file)
Static Public Member Functions inherited from lldb_private::File
static mode_t ConvertOpenOptionsForPOSIXOpen (OpenOptions open_options)
static llvm::Expected< OpenOptionsGetOptionsFromMode (llvm::StringRef mode)
static bool DescriptorIsValid (int descriptor)
static llvm::Expected< const char * > GetStreamOpenModeFromOptions (OpenOptions options)
static bool classof (const File *file)

Static Public Attributes

static char ID = 0
Static Public Attributes inherited from lldb_private::File
static int kInvalidDescriptor = -1
static FILE * kInvalidStream = nullptr
static constexpr OpenOptions OpenOptionsModeMask
static char ID = 0
Static Public Attributes inherited from lldb_private::IOObject
static const WaitableHandle kInvalidHandleValue = -1

Protected Member Functions

 NativeFileBase ()
 NativeFileBase (FILE *fh, OpenOptions options, bool transfer_ownership)
 NativeFileBase (int fd, OpenOptions options, bool transfer_ownership)
 ~NativeFileBase () override
bool DescriptorIsValidUnlocked () const
bool StreamIsValidUnlocked () const
ValueGuard DescriptorIsValid () const
ValueGuard StreamIsValid () const
virtual int Fileno (FILE *fh) const
 Map a stream to its underlying file descriptor.
virtual int Dup (int fd) const
 Duplicate a file descriptor.
virtual bool TryWriteStreamUnlocked (const void *buf, size_t &num_bytes, Status &error)
 Hook for stream writes that bypass the default fwrite path.
Protected Member Functions inherited from lldb_private::File
virtual void CalculateInteractiveAndTerminal ()
 Refresh the cached interactive / terminal / color flags by inspecting the underlying descriptor.

Protected Attributes

int m_descriptor = kInvalidDescriptor
bool m_own_descriptor = false
std::mutex m_descriptor_mutex
FILE * m_stream = kInvalidStream
std::mutex m_stream_mutex
OpenOptions m_options {}
bool m_own_stream = false
std::mutex offset_access_mutex
Protected Attributes inherited from lldb_private::File
LazyBool m_is_interactive = eLazyBoolCalculate
LazyBool m_is_real_terminal = eLazyBoolCalculate
LazyBool m_supports_colors = eLazyBoolCalculate
Protected Attributes inherited from lldb_private::IOObject
FDType m_fd_type

Private Member Functions

 NativeFileBase (const NativeFileBase &)=delete
const NativeFileBaseoperator= (const NativeFileBase &)=delete

Detailed Description

Common base for the platform-specific NativeFile implementations.

Holds the descriptor / stream state and provides the platform-neutral method bodies.

Definition at line 387 of file FileBase.h.

Member Enumeration Documentation

◆ TransferOwnership

Enumerator
Owned 
Unowned 

Definition at line 389 of file FileBase.h.

Constructor & Destructor Documentation

◆ NativeFileBase() [1/4]

◆ NativeFileBase() [2/4]

NativeFileBase::NativeFileBase ( FILE * fh,
OpenOptions options,
bool transfer_ownership )
protected

Definition at line 220 of file File.cpp.

References m_options, m_own_stream, and m_stream.

◆ NativeFileBase() [3/4]

NativeFileBase::NativeFileBase ( int fd,
OpenOptions options,
bool transfer_ownership )
protected

Definition at line 224 of file File.cpp.

References m_descriptor, m_options, and m_own_descriptor.

◆ ~NativeFileBase()

lldb_private::NativeFileBase::~NativeFileBase ( )
inlineoverrideprotected

Definition at line 427 of file FileBase.h.

References Close().

◆ NativeFileBase() [4/4]

lldb_private::NativeFileBase::NativeFileBase ( const NativeFileBase & )
privatedelete

References NativeFileBase().

Member Function Documentation

◆ classof()

bool lldb_private::NativeFileBase::classof ( const File * file)
inlinestatic

Definition at line 418 of file FileBase.h.

References lldb_private::File::File(), ID, and lldb_private::File::isA().

◆ Close()

◆ DescriptorIsValid()

ValueGuard lldb_private::NativeFileBase::DescriptorIsValid ( ) const
inlineprotected

◆ DescriptorIsValidUnlocked()

bool lldb_private::NativeFileBase::DescriptorIsValidUnlocked ( ) const
inlineprotected

Definition at line 436 of file FileBase.h.

References lldb_private::File::DescriptorIsValid(), and m_descriptor.

Referenced by Close(), DescriptorIsValid(), and IsValid().

◆ Dup()

int NativeFileBase::Dup ( int fd) const
protectedvirtual

Duplicate a file descriptor.

Reimplemented in lldb_private::NativeFileWindows.

Definition at line 241 of file File.cpp.

Referenced by GetStream().

◆ Fileno()

int NativeFileBase::Fileno ( FILE * fh) const
protectedvirtual

Map a stream to its underlying file descriptor.

Reimplemented in lldb_private::NativeFileWindows.

Definition at line 239 of file File.cpp.

Referenced by GetDescriptor().

◆ Flush()

Status NativeFileBase::Flush ( )
overridevirtual

Flush the current stream.

Returns
An error object that indicates success or the reason for failure.

Reimplemented from lldb_private::File.

Definition at line 435 of file File.cpp.

References DescriptorIsValid(), error(), lldb_private::Status::FromErrno(), lldb_private::Status::FromErrorString(), m_stream, and StreamIsValid().

◆ GetDescriptor()

int NativeFileBase::GetDescriptor ( ) const
overridevirtual

Get underlying OS file descriptor for this file, or kInvalidDescriptor.

If the descriptor is valid, then it may be used directly for I/O However, the File may also perform it's own buffering, so avoid using this if it is not necessary, or use Flush() appropriately.

Returns
a valid file descriptor for this file or kInvalidDescriptor

Reimplemented from lldb_private::File.

Definition at line 243 of file File.cpp.

References DescriptorIsValid(), Fileno(), lldb_private::File::kInvalidDescriptor, m_descriptor, m_stream, and StreamIsValid().

Referenced by lldb_private::NativeFilePosix::CalculateInteractiveAndTerminal(), lldb_private::NativeFileWindows::CalculateInteractiveAndTerminal(), lldb_private::NativeFilePosix::GetFileSpec(), lldb_private::NativeFilePosix::GetWaitableHandle(), lldb_private::NativeFileWindows::GetWaitableHandle(), lldb_private::NativeFilePosix::Read(), lldb_private::NativeFileWindows::Read(), lldb_private::NativeFilePosix::Write(), and lldb_private::NativeFileWindows::Write().

◆ GetFileSpec()

Status NativeFileBase::GetFileSpec ( FileSpec & file_spec) const
overridevirtual

Get the file specification for this file, if possible.

Parameters
[out]file_specthe file specification.
Returns
ENOTSUP, success, or another error.

Reimplemented from lldb_private::File.

Reimplemented in lldb_private::NativeFilePosix.

Definition at line 333 of file File.cpp.

References lldb_private::FileSpec::Clear(), and lldb_private::Status::FromErrorString().

◆ GetOptions()

Expected< File::OpenOptions > NativeFileBase::GetOptions ( ) const
overridevirtual

Return the OpenOptions for this file.

Some options like eOpenOptionDontFollowSymlinks only make sense when a file is being opened (or not at all) and may not be preserved for this method. But any valid File should return either eOpenOptionReadOnly, eOpenOptionWriteOnly or eOpenOptionReadWrite here.

Returns
OpenOptions flags for this file, or an error.

Reimplemented from lldb_private::File.

Definition at line 235 of file File.cpp.

References m_options.

◆ GetStream()

FILE * NativeFileBase::GetStream ( )
overridevirtual

Get the underlying libc stream for this file, or NULL.

Not all valid files will have a FILE* stream. This should only be used if absolutely necessary, such as to interact with 3rd party libraries that need FILE* streams.

Returns
a valid stream or NULL;

Reimplemented from lldb_private::File.

Definition at line 265 of file File.cpp.

References DescriptorIsValid(), Dup(), lldb_private::File::GetStreamOpenModeFromOptions(), m_descriptor, m_options, m_own_descriptor, m_own_stream, m_stream, and StreamIsValid().

◆ GetWaitableHandle()

IOObject::WaitableHandle NativeFileBase::GetWaitableHandle ( )
overridevirtual

Get a handle that can be used for OS polling interfaces, such as WaitForMultipleObjects, select, or epoll.

This may return IOObject::kInvalidHandleValue if none is available. This will generally be the same as the file descriptor, this function is not interchangeable with GetDescriptor(). A WaitableHandle must only be used for polling, not actual I/O.

Returns
a valid handle or IOObject::kInvalidHandleValue

Reimplemented from lldb_private::File.

Reimplemented in lldb_private::NativeFilePosix, and lldb_private::NativeFileWindows.

Definition at line 258 of file File.cpp.

References lldb_private::IOObject::kInvalidHandleValue.

◆ isA()

bool lldb_private::NativeFileBase::isA ( const void * classID) const
inlineoverridevirtual

◆ IsValid()

bool NativeFileBase::IsValid ( ) const
overridevirtual

IsValid.

Returns
true iff the file is valid.

Reimplemented from lldb_private::File.

Reimplemented in lldb_private::SerialPort.

Definition at line 229 of file File.cpp.

References DescriptorIsValidUnlocked(), m_descriptor_mutex, m_stream_mutex, and StreamIsValidUnlocked().

Referenced by lldb_private::NativeFilePosix::GetFileSpec().

◆ operator=()

const NativeFileBase & lldb_private::NativeFileBase::operator= ( const NativeFileBase & )
privatedelete

References NativeFileBase().

◆ PrintfVarArg()

size_t NativeFileBase::PrintfVarArg ( const char * format,
va_list args )
overridevirtual

Output printf formatted output to the stream.

Print some formatted output to the stream.

Parameters
[in]formatA printf style format string.
[in]argsVariable arguments that are needed for the printf style format string format.

Reimplemented from lldb_private::File.

Definition at line 595 of file File.cpp.

References m_stream, lldb_private::File::PrintfVarArg(), and StreamIsValid().

◆ Read() [1/2]

Status NativeFileBase::Read ( void * buf,
size_t & num_bytes )
overridevirtual

Read bytes from a file from the current file position into buf.

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.

Parameters
[in,out]num_bytesPass in the size of buf. Read will pass out the number of bytes read. Zero bytes read with no error indicates EOF.
Returns
success, ENOTSUP, or another error.

Reimplemented from lldb_private::File.

Reimplemented in lldb_private::NativeFilePosix, and lldb_private::NativeFileWindows.

Definition at line 457 of file File.cpp.

References DescriptorIsValid(), lldb_private::File::eOpenOptionWriteOnly, error(), lldb_private::Status::FromErrno(), lldb_private::Status::FromErrorString(), m_descriptor, m_options, m_stream, lldb_private::File::OpenOptionsModeMask, Read(), lldb_private::Status, and StreamIsValid().

Referenced by lldb_private::NativeFilePosix::NativeFilePosix(), lldb_private::NativeFileWindows::NativeFileWindows(), Read(), and lldb_private::NativeFileWindows::Read().

◆ Read() [2/2]

virtual Status lldb_private::NativeFileBase::Read ( void * dst,
size_t & num_bytes,
off_t & offset )
overridepure virtual

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.

Parameters
[in]dstA buffer where to put the bytes that are read.
[in,out]num_bytesThe number of bytes to read from the current file position which gets modified with the number of bytes that were read.
[in,out]offsetThe offset within the file from which to read num_bytes bytes. This offset gets incremented by the number of bytes that were read.
Returns
An error object that indicates success or the reason for failure.

Reimplemented from lldb_private::File.

Implemented in lldb_private::NativeFilePosix, and lldb_private::NativeFileWindows.

◆ SeekFromCurrent()

off_t NativeFileBase::SeekFromCurrent ( off_t offset,
Status * error_ptr = nullptr )
overridevirtual

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 also
File::Read (void *, size_t, off_t &)
File::Write (const void *, size_t, off_t &)
Parameters
[in]offsetThe offset to seek to within the file relative to the current file position.
[in]error_ptrA pointer to a lldb_private::Status object that will be filled in if non-nullptr.
Returns
The resulting seek offset, or -1 on error.

Reimplemented from lldb_private::File.

Definition at line 373 of file File.cpp.

References lldb_private::Status::Clear(), DescriptorIsValid(), lldb_private::Status::FromErrno(), m_descriptor, m_stream, and StreamIsValid().

◆ SeekFromEnd()

off_t NativeFileBase::SeekFromEnd ( off_t offset,
Status * error_ptr = nullptr )
overridevirtual

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 also
File::Read (void *, size_t, off_t &)
File::Write (const void *, size_t, off_t &)
Parameters
[in,out]offsetThe offset to seek to within the file relative to the end of the file which gets filled in with the resulting absolute file offset.
[in]error_ptrA pointer to a lldb_private::Status object that will be filled in if non-nullptr.
Returns
The resulting seek offset, or -1 on error.

Reimplemented from lldb_private::File.

Definition at line 404 of file File.cpp.

References lldb_private::Status::Clear(), DescriptorIsValid(), lldb_private::Status::FromErrno(), lldb_private::Status::FromErrorString(), m_descriptor, m_stream, and StreamIsValid().

◆ SeekFromStart()

off_t NativeFileBase::SeekFromStart ( off_t offset,
Status * error_ptr = nullptr )
overridevirtual

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 also
File::Read (void *, size_t, off_t &)
File::Write (const void *, size_t, off_t &)
Parameters
[in]offsetThe offset to seek to within the file relative to the beginning of the file.
[in]error_ptrA pointer to a lldb_private::Status object that will be filled in if non-nullptr.
Returns
The resulting seek offset, or -1 on error.

Reimplemented from lldb_private::File.

Definition at line 342 of file File.cpp.

References lldb_private::Status::Clear(), DescriptorIsValid(), lldb_private::Status::FromErrno(), lldb_private::Status::FromErrorString(), m_descriptor, m_stream, and StreamIsValid().

Referenced by lldb_private::NativeFileWindows::Read(), and lldb_private::NativeFileWindows::Write().

◆ StreamIsValid()

ValueGuard lldb_private::NativeFileBase::StreamIsValid ( ) const
inlineprotected

◆ StreamIsValidUnlocked()

bool lldb_private::NativeFileBase::StreamIsValidUnlocked ( ) const
inlineprotected

Definition at line 440 of file FileBase.h.

References lldb_private::File::kInvalidStream, and m_stream.

Referenced by Close(), IsValid(), and StreamIsValid().

◆ Sync()

virtual Status lldb_private::NativeFileBase::Sync ( )
overridepure virtual

Sync to disk.

Returns
An error object that indicates success or the reason for failure.

Reimplemented from lldb_private::File.

Implemented in lldb_private::NativeFilePosix, and lldb_private::NativeFileWindows.

◆ TryWriteStreamUnlocked()

virtual bool lldb_private::NativeFileBase::TryWriteStreamUnlocked ( const void * buf,
size_t & num_bytes,
Status & error )
inlineprotectedvirtual

Hook for stream writes that bypass the default fwrite path.

Returns true if the bytes were consumed.

Reimplemented in lldb_private::NativeFileWindows.

Definition at line 460 of file FileBase.h.

References error().

Referenced by Write().

◆ Write() [1/2]

Status NativeFileBase::Write ( const void * buf,
size_t & num_bytes )
overridevirtual

Write bytes from buf 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.

Parameters
[in,out]num_bytesPass in the size of buf. Write will pass out the number of bytes written. Write will attempt write the full number of bytes and will not return early except on error.
Returns
success, ENOTSUP, or another error.

Reimplemented from lldb_private::File.

Reimplemented in lldb_private::NativeFilePosix, and lldb_private::NativeFileWindows.

Definition at line 525 of file File.cpp.

References DescriptorIsValid(), lldb_private::File::eOpenOptionReadOnly, error(), lldb_private::Status::FromErrno(), lldb_private::Status::FromErrorString(), m_descriptor, m_options, m_stream, lldb_private::File::OpenOptionsModeMask, lldb_private::Status, StreamIsValid(), TryWriteStreamUnlocked(), and Write().

Referenced by lldb_private::NativeFilePosix::NativeFilePosix(), lldb_private::NativeFileWindows::NativeFileWindows(), Write(), and lldb_private::NativeFileWindows::Write().

◆ Write() [2/2]

virtual Status lldb_private::NativeFileBase::Write ( const void * src,
size_t & num_bytes,
off_t & offset )
overridepure virtual

Write bytes to a file at the specified file offset.

NOTE: This function is thread safe in that clients manager their own file position markers, though clients will need to implement their own locking externally to avoid multiple people writing to the file at the same time.

Parameters
[in]srcA buffer containing the bytes to write.
[in,out]num_bytesThe number of bytes to write to the file at offset offset. num_bytes gets modified with the number of bytes that were read.
[in,out]offsetThe offset within the file at which to write num_bytes bytes. This offset gets incremented by the number of bytes that were written.
Returns
An error object that indicates success or the reason for failure.

Reimplemented from lldb_private::File.

Implemented in lldb_private::NativeFilePosix, and lldb_private::NativeFileWindows.

Member Data Documentation

◆ ID

char NativeFileBase::ID = 0
static

Definition at line 414 of file FileBase.h.

Referenced by classof(), and isA().

◆ m_descriptor

◆ m_descriptor_mutex

std::mutex lldb_private::NativeFileBase::m_descriptor_mutex
mutableprotected

Definition at line 467 of file FileBase.h.

Referenced by Close(), DescriptorIsValid(), and IsValid().

◆ m_options

OpenOptions lldb_private::NativeFileBase::m_options {}
protected

Definition at line 472 of file FileBase.h.

Referenced by Close(), GetOptions(), GetStream(), NativeFileBase(), NativeFileBase(), Read(), and Write().

◆ m_own_descriptor

bool lldb_private::NativeFileBase::m_own_descriptor = false
protected

Definition at line 466 of file FileBase.h.

Referenced by Close(), GetStream(), and NativeFileBase().

◆ m_own_stream

bool lldb_private::NativeFileBase::m_own_stream = false
protected

Definition at line 473 of file FileBase.h.

Referenced by Close(), GetStream(), and NativeFileBase().

◆ m_stream

◆ m_stream_mutex

std::mutex lldb_private::NativeFileBase::m_stream_mutex
mutableprotected

Definition at line 470 of file FileBase.h.

Referenced by Close(), IsValid(), and StreamIsValid().

◆ offset_access_mutex

std::mutex lldb_private::NativeFileBase::offset_access_mutex
protected

The documentation for this class was generated from the following files: