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

A file class. More...

#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 {
  eOpenOptionRead = (1u << 0), eOpenOptionWrite = (1u << 1), eOpenOptionAppend, eOpenOptionTruncate = (1u << 3),
  eOpenOptionNonBlocking = (1u << 4), eOpenOptionCanCreate = (1u << 5), eOpenOptionCanCreateNewOnly, eOpenOptionDontFollowSymlinks = (1u << 7),
  eOpenOptionCloseOnExec
}
 
- Public Types inherited from lldb_private::IOObject
enum  FDType { eFDTypeFile, eFDTypeSocket }
 
typedef int WaitableHandle
 

Public Member Functions

 File ()
 
 File (FILE *fh, bool transfer_ownership)
 
 File (int fd, bool transfer_ownership)
 
 ~File () override
 Destructor. More...
 
bool IsValid () const override
 
 operator bool () const
 Convert to pointer operator. More...
 
bool operator! () const
 Logical NOT operator. More...
 
Status GetFileSpec (FileSpec &file_spec) const
 Get the file spec for this file. More...
 
Status Close () override
 
void Clear ()
 
int GetDescriptor () const
 
WaitableHandle GetWaitableHandle () override
 
void SetDescriptor (int fd, bool transfer_ownership)
 
FILE * GetStream ()
 
void SetStream (FILE *fh, bool transfer_ownership)
 
Status Read (void *buf, size_t &num_bytes) override
 Read bytes from a file from the current file position. More...
 
Status Write (const void *buf, size_t &num_bytes) override
 Write bytes to a file at the current file position. More...
 
off_t SeekFromStart (off_t offset, Status *error_ptr=nullptr)
 Seek to an offset relative to the beginning of the file. More...
 
off_t SeekFromCurrent (off_t offset, Status *error_ptr=nullptr)
 Seek to an offset relative to the current file position. More...
 
off_t SeekFromEnd (off_t offset, Status *error_ptr=nullptr)
 Seek to an offset relative to the end of the file. More...
 
Status Read (void *dst, size_t &num_bytes, off_t &offset)
 Read bytes from a file from the specified file offset. More...
 
Status Read (size_t &num_bytes, off_t &offset, bool null_terminate, lldb::DataBufferSP &data_buffer_sp)
 Read bytes from a file from the specified file offset. More...
 
Status Write (const void *src, size_t &num_bytes, off_t &offset)
 Write bytes to a file at the specified file offset. More...
 
Status Flush ()
 Flush the current stream. More...
 
Status Sync ()
 Sync to disk. More...
 
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 ()
 
size_t Printf (const char *format,...) __attribute__((format(printf
 Output printf formatted output to the stream. More...
 
size_t size_t PrintfVarArg (const char *format, va_list args)
 
void SetOptions (uint32_t options)
 
- Public Member Functions inherited from lldb_private::IOObject
 IOObject (FDType type, bool should_close)
 
virtual ~IOObject ()
 
FDType GetFdType () const
 

Static Public Member Functions

static mode_t ConvertOpenOptionsForPOSIXOpen (uint32_t open_options)
 
static bool DescriptorIsValid (int descriptor)
 

Static Public Attributes

static int kInvalidDescriptor = -1
 
static FILE * kInvalidStream = NULL
 
- Static Public Attributes inherited from lldb_private::IOObject
static const WaitableHandle kInvalidHandleValue = -1
 

Protected Member Functions

bool DescriptorIsValid () const
 
bool StreamIsValid () const
 
void CalculateInteractiveAndTerminal ()
 

Protected Attributes

int m_descriptor
 
FILE * m_stream
 
uint32_t m_options
 
bool m_own_stream
 
LazyBool m_is_interactive
 
LazyBool m_is_real_terminal
 
LazyBool m_supports_colors
 
std::mutex offset_access_mutex
 
- Protected Attributes inherited from lldb_private::IOObject
FDType m_fd_type
 
bool m_should_close_fd
 

Detailed Description

A file class.

A file class that divides abstracts the LLDB core from host file functionality.

Definition at line 29 of file File.h.

Member Enumeration Documentation

◆ OpenOptions

Enumerator
eOpenOptionRead 
eOpenOptionWrite 
eOpenOptionAppend 
eOpenOptionTruncate 
eOpenOptionNonBlocking 
eOpenOptionCanCreate 
eOpenOptionCanCreateNewOnly 
eOpenOptionDontFollowSymlinks 
eOpenOptionCloseOnExec 

Definition at line 36 of file File.h.

Constructor & Destructor Documentation

◆ File() [1/3]

lldb_private::File::File ( )
inline

Definition at line 53 of file File.h.

◆ File() [2/3]

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

Definition at line 60 of file File.h.

◆ File() [3/3]

lldb_private::File::File ( int  fd,
bool  transfer_ownership 
)
inline

Definition at line 67 of file File.h.

References ~File().

◆ ~File()

File::~File ( )
override

Destructor.

The destructor is virtual in case this class is subclassed.

Definition at line 74 of file File.cpp.

Referenced by File().

Member Function Documentation

◆ CalculateInteractiveAndTerminal()

void File::CalculateInteractiveAndTerminal ( )
protected

Definition at line 677 of file File.cpp.

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

Referenced by StreamIsValid().

◆ Clear()

void File::Clear ( )

Definition at line 179 of file File.cpp.

References lldb_private::eLazyBoolCalculate.

Referenced by operator!().

◆ Close()

Status File::Close ( )
overridevirtual

◆ ConvertOpenOptionsForPOSIXOpen()

mode_t File::ConvertOpenOptionsForPOSIXOpen ( uint32_t  open_options)
static

Definition at line 653 of file File.cpp.

References O_NONBLOCK.

◆ DescriptorIsValid() [1/2]

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

Definition at line 367 of file File.h.

◆ DescriptorIsValid() [2/2]

bool lldb_private::File::DescriptorIsValid ( ) const
inlineprotected

Definition at line 370 of file File.h.

References DescriptorIsValid(), and m_descriptor.

Referenced by DescriptorIsValid(), IsValid(), operator bool(), and operator!().

◆ Flush()

Status File::Flush ( )

Flush the current stream.

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

Definition at line 301 of file File.cpp.

References lldb_private::Status::SetErrorString(), and lldb_private::Status::SetErrorToErrno().

Referenced by lldb_private::StreamFile::Flush(), operator!(), and lldb_private::ScriptInterpreterPythonImpl::SetStdHandle().

◆ GetDescriptor()

int File::GetDescriptor ( ) const

◆ GetFileSpec()

Status File::GetFileSpec ( FileSpec file_spec) const

Get the file spec for this file.

Returns
A reference to the file specification object.

Definition at line 188 of file File.cpp.

References lldb_private::FileSpec::Clear(), lldb_private::Status::Fail(), PATH_MAX, lldb_private::Status::SetErrorString(), lldb_private::Status::SetErrorToErrno(), and lldb_private::FileSpec::SetFile().

Referenced by operator!().

◆ 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 706 of file File.cpp.

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

Referenced by operator!().

◆ 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 712 of file File.cpp.

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

Referenced by operator!().

◆ GetIsTerminalWithColors()

bool File::GetIsTerminalWithColors ( )

Definition at line 718 of file File.cpp.

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

Referenced by operator!().

◆ 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 142 of file File.cpp.

References lldb_private::Status::Clear(), S_IRWXG, S_IRWXO, S_IRWXU, lldb_private::Status::SetErrorString(), and lldb_private::Status::SetErrorToErrno().

Referenced by operator!(), and lldb_private::Platform::PutFile().

◆ GetStream()

FILE * File::GetStream ( )

Definition at line 103 of file File.cpp.

References GetStreamOpenModeFromOptions().

Referenced by operator!(), and lldb_private::PythonFile::Reset().

◆ GetWaitableHandle()

IOObject::WaitableHandle File::GetWaitableHandle ( )
overridevirtual

Implements lldb_private::IOObject.

Definition at line 94 of file File.cpp.

Referenced by operator!().

◆ IsValid()

bool lldb_private::File::IsValid ( ) const
inlineoverridevirtual

◆ operator bool()

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

Convert to pointer operator.

This allows code to check a File object to see if it contains anything valid using code such as:

File file(...);
if (file)
{ ...
Returns
A pointer to this object if either the directory or filename is valid, nullptr otherwise.

Definition at line 96 of file File.h.

References DescriptorIsValid(), and StreamIsValid().

◆ operator!()

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

Logical NOT operator.

This allows code to check a File object to see if it is invalid using code such as:

File file(...);
if (!file)
{ ...
Returns
Returns true if the object has an empty directory and filename, false otherwise.

Definition at line 112 of file File.h.

References Clear(), Close(), DescriptorIsValid(), Flush(), GetDescriptor(), GetFileSpec(), GetIsInteractive(), GetIsRealTerminal(), GetIsTerminalWithColors(), GetPermissions(), GetStream(), GetWaitableHandle(), Printf(), PrintfVarArg(), Read(), SeekFromCurrent(), SeekFromEnd(), SeekFromStart(), SetDescriptor(), SetStream(), StreamIsValid(), Sync(), and Write().

◆ Printf()

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

Output printf formatted output to the stream.

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 625 of file File.cpp.

Referenced by operator!().

◆ PrintfVarArg()

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

Definition at line 634 of file File.cpp.

References vasprintf().

Referenced by operator!().

◆ Read() [1/3]

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

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.

Parameters
[in]bufA 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.
Returns
An error object that indicates success or the reason for failure.

Implements lldb_private::IOObject.

Definition at line 335 of file File.cpp.

References lldb_private::Status::Fail(), lldb_private::Status::SetErrorString(), and lldb_private::Status::SetErrorToErrno().

Referenced by lldb_private::process_gdb_remote::GDBRemoteCommunicationServerCommon::Handle_vFile_pRead(), operator!(), and lldb_private::Platform::PutFile().

◆ Read() [2/3]

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

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.

Definition at line 456 of file File.cpp.

References lldb_private::Status::Fail(), lldb_private::Status::SetErrorString(), lldb_private::Status::SetErrorToErrno(), and lldb_private::Status::Success().

◆ Read() [3/3]

Status lldb_private::File::Read ( size_t &  num_bytes,
off_t &  offset,
bool  null_terminate,
lldb::DataBufferSP &  data_buffer_sp 
)

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,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.
[in]null_terminateEnsure that the data that is read is terminated with a NULL character so that the data can be used as a C string.
[out]data_buffer_spA 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.
Returns
An error object that indicates success or the reason for failure.

◆ SeekFromCurrent()

off_t File::SeekFromCurrent ( 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 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.

Definition at line 249 of file File.cpp.

References lldb_private::Status::Clear(), lldb_private::Status::SetErrorString(), and lldb_private::Status::SetErrorToErrno().

Referenced by operator!().

◆ SeekFromEnd()

off_t File::SeekFromEnd ( 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 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.

Definition at line 275 of file File.cpp.

References lldb_private::Status::Clear(), lldb_private::Status::SetErrorString(), and lldb_private::Status::SetErrorToErrno().

Referenced by operator!().

◆ SeekFromStart()

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

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.

Definition at line 223 of file File.cpp.

References lldb_private::Status::Clear(), lldb_private::Status::SetErrorString(), and lldb_private::Status::SetErrorToErrno().

Referenced by operator!(), lldb_private::Platform::PutFile(), and ObjectFileMachO::SaveCore().

◆ SetDescriptor()

void File::SetDescriptor ( int  fd,
bool  transfer_ownership 
)

◆ SetOptions()

void lldb_private::File::SetOptions ( uint32_t  options)
inline

Definition at line 365 of file File.h.

References m_options.

Referenced by lldb_private::PythonFile::GetUnderlyingFile(), and lldb_private::FileSystem::Open().

◆ SetStream()

void File::SetStream ( FILE *  fh,
bool  transfer_ownership 
)

◆ StreamIsValid()

bool lldb_private::File::StreamIsValid ( ) const
inlineprotected

Definition at line 372 of file File.h.

References CalculateInteractiveAndTerminal(), kInvalidStream, and m_stream.

Referenced by IsValid(), operator bool(), and operator!().

◆ Sync()

Status File::Sync ( )

Sync to disk.

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

Definition at line 312 of file File.cpp.

References lldb_private::Status::SetErrorString(), lldb_private::Status::SetErrorToErrno(), and lldb_private::Status::SetErrorToGenericError().

Referenced by operator!().

◆ Write() [1/2]

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

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.

Parameters
[in]bufA buffer where to put the bytes that are read.
[in,out]num_bytesThe number of bytes to write to the current file position which gets modified with the number of bytes that were written.
Returns
An error object that indicates success or the reason for failure.

Implements lldb_private::IOObject.

Definition at line 394 of file File.cpp.

References lldb_private::Status::Fail(), lldb_private::Status::SetErrorString(), and lldb_private::Status::SetErrorToErrno().

Referenced by lldb_private::process_gdb_remote::GDBRemoteCommunicationServerCommon::Handle_vFile_pWrite(), lldb_private::REPL::IOHandlerInputComplete(), operator!(), lldb_private::ClangExpressionParser::Parse(), lldb_private::RenderScriptRuntime::SaveAllocation(), ObjectFileMachO::SaveCore(), and lldb_private::StreamFile::WriteImpl().

◆ Write() [2/2]

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

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.

Definition at line 560 of file File.cpp.

References lldb_private::Status::Fail(), lldb_private::Status::SetErrorString(), and lldb_private::Status::SetErrorToErrno().

Member Data Documentation

◆ kInvalidDescriptor

int File::kInvalidDescriptor = -1
static

Definition at line 31 of file File.h.

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

◆ kInvalidStream

FILE * File::kInvalidStream = NULL
static

Definition at line 32 of file File.h.

Referenced by StreamIsValid().

◆ m_descriptor

int lldb_private::File::m_descriptor
protected

Definition at line 377 of file File.h.

Referenced by DescriptorIsValid().

◆ m_is_interactive

LazyBool lldb_private::File::m_is_interactive
protected

Definition at line 381 of file File.h.

◆ m_is_real_terminal

LazyBool lldb_private::File::m_is_real_terminal
protected

Definition at line 382 of file File.h.

◆ m_options

uint32_t lldb_private::File::m_options
protected

Definition at line 379 of file File.h.

Referenced by SetOptions().

◆ m_own_stream

bool lldb_private::File::m_own_stream
protected

Definition at line 380 of file File.h.

◆ m_stream

FILE* lldb_private::File::m_stream
protected

Definition at line 378 of file File.h.

Referenced by StreamIsValid().

◆ m_supports_colors

LazyBool lldb_private::File::m_supports_colors
protected

Definition at line 383 of file File.h.

◆ offset_access_mutex

std::mutex lldb_private::File::offset_access_mutex
protected

Definition at line 384 of file File.h.


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