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

#include "lldb/Host/File.h"

Inheritance diagram for lldb_private::File:
Inheritance graph
[legend]
Collaboration diagram for lldb_private::File:
Collaboration graph
[legend]

Public Types

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
 

Public Member Functions

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

Static Public Member Functions

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 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

void CalculateInteractiveAndTerminal ()
 

Protected Attributes

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

 File (const File &)=delete
 
const Fileoperator= (const File &)=delete
 

Detailed Description

An abstract base class for files.

Files will often be NativeFiles, which provides a wrapper around host OS file functionality. But it is also possible to subclass file to provide objects that have file or stream functionality but are not backed by any host OS file.

Definition at line 35 of file File.h.

Member Enumeration Documentation

◆ OpenOptions

Enumerator
eOpenOptionReadOnly 
eOpenOptionWriteOnly 
eOpenOptionReadWrite 
eOpenOptionAppend 
eOpenOptionCanCreate 
eOpenOptionTruncate 
eOpenOptionCanCreateNewOnly 
eOpenOptionNonBlocking 
eOpenOptionDontFollowSymlinks 
eOpenOptionCloseOnExec 
eOpenOptionInvalid 

Definition at line 49 of file File.h.

Constructor & Destructor Documentation

◆ File() [1/2]

lldb_private::File::File ( )
inline

Definition at line 74 of file File.h.

◆ File() [2/2]

lldb_private::File::File ( const File )
privatedelete

Member Function Documentation

◆ CalculateInteractiveAndTerminal()

void File::CalculateInteractiveAndTerminal ( )
protected

Definition at line 158 of file File.cpp.

References lldb_private::eLazyBoolNo, and lldb_private::eLazyBoolYes.

◆ classof()

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

Definition at line 363 of file File.h.

References ID, and isA().

◆ Close()

Status File::Close ( )
overridevirtual

Flush any buffers and release any resources owned by the file.

After Close() the file will be invalid.

Returns
success or an error.

Implements lldb_private::IOObject.

Reimplemented in lldb_private::SerialPort, and lldb_private::NativeFile.

Definition at line 113 of file File.cpp.

Referenced by lldb_private::Debugger::Clear(), and lldb_private::Debugger::StopIOHandlerThread().

◆ ConvertOpenOptionsForPOSIXOpen()

mode_t File::ConvertOpenOptionsForPOSIXOpen ( OpenOptions  open_options)
static

Definition at line 743 of file File.cpp.

References O_NONBLOCK.

◆ DescriptorIsValid()

static bool lldb_private::File::DescriptorIsValid ( int  descriptor)
inlinestatic

Definition at line 70 of file File.h.

Referenced by lldb_private::NativeFile::DescriptorIsValid().

◆ Flush()

Status File::Flush ( )
virtual

Flush the current stream.

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

Reimplemented in lldb_private::NativeFile.

Definition at line 154 of file File.cpp.

◆ GetDescriptor()

int File::GetDescriptor ( ) const
virtual

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 in lldb_private::NativeFile.

Definition at line 124 of file File.cpp.

Referenced by lldb_private::Debugger::SaveInputTerminalState().

◆ GetFileSpec()

Status File::GetFileSpec ( FileSpec file_spec) const
virtual

Get the file specification for this file, if possible.

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

Reimplemented in lldb_private::NativeFile.

Definition at line 119 of file File.cpp.

References lldb_private::FileSpec::Clear().

◆ GetIsInteractive()

bool File::GetIsInteractive ( )

Return true if this file is interactive.

Returns
True if this file is a terminal (tty or pty), false otherwise.

Definition at line 191 of file File.cpp.

References lldb_private::eLazyBoolCalculate, and lldb_private::eLazyBoolYes.

Referenced by lldb_private::CommandObjectGUI::DoExecute().

◆ GetIsRealTerminal()

bool File::GetIsRealTerminal ( )

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.

Returns
True if this file is a terminal (tty, not a pty) that has a non-zero width and height, false otherwise.

Definition at line 197 of file File.cpp.

References lldb_private::eLazyBoolCalculate, and lldb_private::eLazyBoolYes.

Referenced by lldb_private::CommandObjectGUI::DoExecute().

◆ GetIsTerminalWithColors()

bool File::GetIsTerminalWithColors ( )

Return true if this file is a terminal which supports colors.

Returns
True iff this is a terminal and it supports colors.

Definition at line 203 of file File.cpp.

References lldb_private::eLazyBoolCalculate, and lldb_private::eLazyBoolYes.

◆ GetOpenMode()

llvm::Expected<const char *> lldb_private::File::GetOpenMode ( ) const
inline

Definition at line 319 of file File.h.

References GetOptions(), and GetStreamOpenModeFromOptions().

◆ GetOptions()

Expected< File::OpenOptions > File::GetOptions ( ) const
virtual

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 in lldb_private::NativeFile.

Definition at line 232 of file File.cpp.

Referenced by GetOpenMode().

◆ GetOptionsFromMode()

Expected< File::OpenOptions > File::GetOptionsFromMode ( llvm::StringRef  mode)
static

Definition at line 78 of file File.cpp.

◆ GetPermissions()

uint32_t File::GetPermissions ( Status error) const

Get the permissions for a this file.

Returns
Bits logical OR'ed together from the permission bits defined in lldb_private::File::Permissions.

Definition at line 238 of file File.cpp.

References error(), S_IRWXG, S_IRWXO, and S_IRWXU.

◆ GetStream()

FILE * File::GetStream ( )
virtual

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 in lldb_private::NativeFile.

Definition at line 126 of file File.cpp.

Referenced by lldb_private::CommandObjectGUI::DoExecute(), lldb::SBDebugger::GetErrorFileHandle(), lldb::SBDebugger::GetInputFileHandle(), lldb::SBDebugger::GetOutputFileHandle(), and IOHandlerLuaInterpreter::IOHandlerLuaInterpreter().

◆ GetStreamOpenModeFromOptions()

Expected< const char * > File::GetStreamOpenModeFromOptions ( File::OpenOptions  options)
static

Definition at line 43 of file File.cpp.

Referenced by GetOpenMode().

◆ GetWaitableHandle()

IOObject::WaitableHandle File::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

Implements lldb_private::IOObject.

Reimplemented in lldb_private::NativeFile.

Definition at line 115 of file File.cpp.

◆ isA()

virtual bool lldb_private::File::isA ( const void *  classID) const
inlinevirtual

◆ IsValid()

bool File::IsValid ( ) const
overridevirtual

◆ operator bool()

lldb_private::File::operator bool ( ) const
inline

Definition at line 357 of file File.h.

References IsValid().

◆ operator!()

bool lldb_private::File::operator! ( ) const
inline

Definition at line 359 of file File.h.

References IsValid().

◆ operator=()

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

◆ Printf()

size_t File::Printf ( const char *  format,
  ... 
)

Output printf formatted output to the stream.

NOTE: this is not virtual, because it just calls the va_list version of the function.

Print some formatted output to the stream.

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

Definition at line 209 of file File.cpp.

◆ PrintfVarArg()

size_t File::PrintfVarArg ( const char *  format,
va_list  args 
)
virtual

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 in lldb_private::NativeFile.

Definition at line 217 of file File.cpp.

References vasprintf().

◆ Read() [1/2]

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

Implements lldb_private::IOObject.

Reimplemented in lldb_private::NativeFile.

Definition at line 104 of file File.cpp.

Referenced by GetTripleForProcess().

◆ Read() [2/2]

Status File::Read ( void *  dst,
size_t &  num_bytes,
off_t &  offset 
)
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 form 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 in lldb_private::NativeFile.

Definition at line 146 of file File.cpp.

◆ SeekFromCurrent()

off_t File::SeekFromCurrent ( off_t  offset,
Status error_ptr = nullptr 
)
virtual

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 in lldb_private::NativeFile.

Definition at line 134 of file File.cpp.

◆ SeekFromEnd()

off_t File::SeekFromEnd ( off_t  offset,
Status error_ptr = nullptr 
)
virtual

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 in lldb_private::NativeFile.

Definition at line 140 of file File.cpp.

◆ SeekFromStart()

off_t File::SeekFromStart ( off_t  offset,
Status error_ptr = nullptr 
)
virtual

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 in lldb_private::NativeFile.

Definition at line 128 of file File.cpp.

Referenced by GetTripleForProcess().

◆ Sync()

Status File::Sync ( )
virtual

Sync to disk.

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

Reimplemented in lldb_private::NativeFile.

Definition at line 156 of file File.cpp.

◆ Write() [1/2]

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

Implements lldb_private::IOObject.

Reimplemented in lldb_private::NativeFile.

Definition at line 107 of file File.cpp.

◆ Write() [2/2]

Status File::Write ( const void *  src,
size_t &  num_bytes,
off_t &  offset 
)
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 in lldb_private::NativeFile.

Definition at line 150 of file File.cpp.

Member Data Documentation

◆ ID

char File::ID = 0
static

Definition at line 359 of file File.h.

Referenced by classof(), and isA().

◆ kInvalidDescriptor

int File::kInvalidDescriptor = -1
static

◆ kInvalidStream

FILE * File::kInvalidStream = nullptr
static

Definition at line 38 of file File.h.

Referenced by lldb_private::NativeFile::StreamIsValid().

◆ m_is_interactive

LazyBool lldb_private::File::m_is_interactive = eLazyBoolCalculate
protected

Definition at line 366 of file File.h.

Referenced by lldb_private::SerialPort::IsValid().

◆ m_is_real_terminal

LazyBool lldb_private::File::m_is_real_terminal = eLazyBoolCalculate
protected

Definition at line 367 of file File.h.

◆ m_supports_colors

LazyBool lldb_private::File::m_supports_colors = eLazyBoolCalculate
protected

Definition at line 368 of file File.h.


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