LLDB mainline
Classes | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | Private Member Functions | List of all members
lldb_private::NativeFile Class Reference

#include <File.h>

Inheritance diagram for lldb_private::NativeFile:
Inheritance graph
[legend]

Classes

struct  ValueGuard
 

Public Member Functions

 NativeFile ()
 
 NativeFile (FILE *fh, bool transfer_ownership)
 
 NativeFile (int fd, OpenOptions options, bool transfer_ownership)
 
 ~NativeFile () override
 
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.
 
Status Read (void *dst, size_t &num_bytes, off_t &offset) override
 Read bytes from a file from the specified file offset.
 
Status Write (const void *src, size_t &num_bytes, off_t &offset) override
 Write bytes to a file at the specified file offset.
 
Status Flush () override
 Flush the current stream.
 
Status Sync () override
 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 ()
 
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.
 
bool IsValid () const override
 IsValid.
 
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.
 
virtual Status GetFileSpec (FileSpec &file_spec) const
 Get the file specification for this file, if possible.
 
virtual int GetDescriptor () const
 Get underlying OS file descriptor for this file, or kInvalidDescriptor.
 
virtual FILE * GetStream ()
 Get the underlying libc stream for this file, or NULL.
 
virtual off_t SeekFromStart (off_t offset, Status *error_ptr=nullptr)
 Seek to an offset relative to the beginning of the file.
 
virtual off_t SeekFromCurrent (off_t offset, Status *error_ptr=nullptr)
 Seek to an offset relative to the current file position.
 
virtual off_t SeekFromEnd (off_t offset, Status *error_ptr=nullptr)
 Seek to an offset relative to the end of the file.
 
virtual Status Read (void *dst, size_t &num_bytes, off_t &offset)
 Read bytes from a file from the specified file offset.
 
virtual Status Write (const void *src, size_t &num_bytes, off_t &offset)
 Write bytes to a file at the specified file offset.
 
virtual Status Flush ()
 Flush the current stream.
 
virtual Status Sync ()
 Sync to disk.
 
size_t Printf (const char *format,...) __attribute__((format(printf
 Output printf formatted output to the stream.
 
size_t virtual size_t PrintfVarArg (const char *format, va_list args)
 Output printf formatted output to the stream.
 
virtual llvm::Expected< OpenOptionsGetOptions () const
 Return the OpenOptions for this file.
 
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
 
virtual bool isA (const void *classID) const
 
- Public Member Functions inherited from lldb_private::IOObject
 IOObject (FDType type)
 
virtual ~IOObject ()
 
virtual Status Read (void *buf, size_t &num_bytes)=0
 
virtual Status Write (const void *buf, size_t &num_bytes)=0
 
virtual bool IsValid () const =0
 
virtual Status Close ()=0
 
FDType GetFdType () const
 
virtual WaitableHandle GetWaitableHandle ()=0
 

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 char ID = 0
 
- Static Public Attributes inherited from lldb_private::IOObject
static const WaitableHandle kInvalidHandleValue = -1
 

Protected Member Functions

bool DescriptorIsValidUnlocked () const
 
bool StreamIsValidUnlocked () const
 
ValueGuard DescriptorIsValid () const
 
ValueGuard StreamIsValid () const
 
- Protected Member Functions inherited from lldb_private::File
void CalculateInteractiveAndTerminal ()
 

Protected Attributes

int m_descriptor
 
bool m_own_descriptor = false
 
std::mutex m_descriptor_mutex
 
FILE * m_stream
 
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

 NativeFile (const NativeFile &)=delete
 
const NativeFileoperator= (const NativeFile &)=delete
 

Additional Inherited Members

- 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 }
 
typedef int WaitableHandle
 

Detailed Description

Definition at line 378 of file File.h.

Constructor & Destructor Documentation

◆ NativeFile() [1/4]

lldb_private::NativeFile::NativeFile ( )
inline

Definition at line 380 of file File.h.

◆ NativeFile() [2/4]

lldb_private::NativeFile::NativeFile ( FILE *  fh,
bool  transfer_ownership 
)
inline

Definition at line 382 of file File.h.

◆ NativeFile() [3/4]

lldb_private::NativeFile::NativeFile ( int  fd,
OpenOptions  options,
bool  transfer_ownership 
)
inline

Definition at line 386 of file File.h.

◆ ~NativeFile()

lldb_private::NativeFile::~NativeFile ( )
inlineoverride

Definition at line 390 of file File.h.

References Close().

◆ NativeFile() [4/4]

lldb_private::NativeFile::NativeFile ( const NativeFile )
privatedelete

Member Function Documentation

◆ classof()

static bool lldb_private::NativeFile::classof ( const File file)
inlinestatic

Definition at line 415 of file File.h.

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

◆ Close()

Status NativeFile::Close ( )
overridevirtual

◆ DescriptorIsValid()

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

◆ DescriptorIsValidUnlocked()

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

Definition at line 425 of file File.h.

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

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

◆ Flush()

Status NativeFile::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 479 of file File.cpp.

References DescriptorIsValid(), error(), m_stream, and StreamIsValid().

◆ GetDescriptor()

int NativeFile::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 257 of file File.cpp.

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

Referenced by GetFileSpec(), GetWaitableHandle(), Read(), and Write().

◆ GetFileSpec()

Status NativeFile::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.

Definition at line 351 of file File.cpp.

References lldb_private::FileSpec::Clear(), error(), GetDescriptor(), IsValid(), PATH_MAX, and lldb_private::FileSpec::SetFile().

◆ GetOptions()

Expected< File::OpenOptions > NativeFile::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 255 of file File.cpp.

References m_options.

◆ GetStream()

FILE * NativeFile::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 280 of file File.cpp.

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

◆ GetWaitableHandle()

IOObject::WaitableHandle NativeFile::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.

Definition at line 276 of file File.cpp.

References GetDescriptor().

◆ isA()

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

Reimplemented from lldb_private::File.

Reimplemented in lldb_private::SerialPort.

Definition at line 412 of file File.h.

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

◆ IsValid()

bool NativeFile::IsValid ( ) const
overridevirtual

IsValid.

Returns
true iff the file is valid.

Reimplemented from lldb_private::File.

Reimplemented in lldb_private::SerialPort.

Definition at line 250 of file File.cpp.

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

Referenced by GetFileSpec(), and lldb_private::SerialPort::IsValid().

◆ operator=()

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

◆ PrintfVarArg()

size_t NativeFile::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 770 of file File.cpp.

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

◆ Read() [1/2]

Status NativeFile::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.

Definition at line 518 of file File.cpp.

References DescriptorIsValid(), error(), m_descriptor, m_stream, Read(), and StreamIsValid().

Referenced by lldb_private::process_gdb_remote::GDBRemoteCommunicationServerCommon::Handle_vFile_pRead(), and Read().

◆ Read() [2/2]

Status NativeFile::Read ( void *  dst,
size_t &  num_bytes,
off_t &  offset 
)
overridevirtual

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.

Definition at line 646 of file File.cpp.

References error(), GetDescriptor(), lldb_private::File::kInvalidDescriptor, m_descriptor, offset_access_mutex, Read(), and SeekFromStart().

◆ SeekFromCurrent()

off_t NativeFile::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 418 of file File.cpp.

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

◆ SeekFromEnd()

off_t NativeFile::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 449 of file File.cpp.

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

◆ SeekFromStart()

off_t NativeFile::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 387 of file File.cpp.

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

Referenced by Read(), and Write().

◆ StreamIsValid()

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

◆ StreamIsValidUnlocked()

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

Definition at line 430 of file File.h.

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

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

◆ Sync()

Status NativeFile::Sync ( )
overridevirtual

Sync to disk.

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

Reimplemented from lldb_private::File.

Definition at line 495 of file File.cpp.

References DescriptorIsValid(), error(), and m_descriptor.

◆ Write() [1/2]

Status NativeFile::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.

Definition at line 582 of file File.cpp.

References DescriptorIsValid(), error(), m_descriptor, m_stream, StreamIsValid(), and Write().

Referenced by lldb_private::ClangUtilityFunction::ClangUtilityFunction(), lldb_private::process_gdb_remote::GDBRemoteCommunicationServerCommon::Handle_vFile_pWrite(), lldb_private::ClangExpressionParser::ParseInternal(), and Write().

◆ Write() [2/2]

Status NativeFile::Write ( const void *  src,
size_t &  num_bytes,
off_t &  offset 
)
overridevirtual

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.

Definition at line 706 of file File.cpp.

References error(), GetDescriptor(), lldb_private::File::kInvalidDescriptor, m_descriptor, offset_access_mutex, SeekFromStart(), and Write().

Member Data Documentation

◆ ID

char NativeFile::ID = 0
static

Definition at line 411 of file File.h.

Referenced by classof(), and isA().

◆ m_descriptor

int lldb_private::NativeFile::m_descriptor
protected

◆ m_descriptor_mutex

std::mutex lldb_private::NativeFile::m_descriptor_mutex
mutableprotected

Definition at line 444 of file File.h.

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

◆ m_options

OpenOptions lldb_private::NativeFile::m_options {}
protected

Definition at line 449 of file File.h.

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

◆ m_own_descriptor

bool lldb_private::NativeFile::m_own_descriptor = false
protected

Definition at line 443 of file File.h.

Referenced by Close(), and GetStream().

◆ m_own_stream

bool lldb_private::NativeFile::m_own_stream = false
protected

Definition at line 450 of file File.h.

Referenced by Close(), and GetStream().

◆ m_stream

FILE* lldb_private::NativeFile::m_stream
protected

◆ m_stream_mutex

std::mutex lldb_private::NativeFile::m_stream_mutex
mutableprotected

Definition at line 447 of file File.h.

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

◆ offset_access_mutex

std::mutex lldb_private::NativeFile::offset_access_mutex
protected

Definition at line 451 of file File.h.

Referenced by Read(), and Write().


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