An abstract base class for files. More...

#include "lldb/Host/File.h"

Inheritance diagram for lldb_private::File:

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

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< OpenOptions >	GetOptions () 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 mode_t	ConvertOpenOptionsForPOSIXOpen (OpenOptions open_options)

static llvm::Expected< OpenOptions >	GetOptionsFromMode (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 File &	operator= (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 36 of file File.h.

Member Enumeration Documentation

◆ OpenOptions

enum lldb_private::File::OpenOptions : uint32_t

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

Definition at line 50 of file File.h.

Constructor & Destructor Documentation

◆ File() [1/2]

lldb_private::File::File ( )

inline

Definition at line 75 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 160 of file File.cpp.

References DescriptorIsValid(), lldb_private::eLazyBoolNo, lldb_private::eLazyBoolYes, GetDescriptor(), m_is_interactive, m_is_real_terminal, and m_supports_colors.

Referenced by GetIsInteractive(), GetIsRealTerminal(), and GetIsTerminalWithColors().

◆ classof()

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

inlinestatic

Definition at line 364 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::NativeFile, and lldb_private::SerialPort.

Definition at line 115 of file File.cpp.

References Flush().

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

◆ ConvertOpenOptionsForPOSIXOpen()

mode_t File::ConvertOpenOptionsForPOSIXOpen ( OpenOptions open_options )

static

Definition at line 778 of file File.cpp.

References eOpenOptionAppend, eOpenOptionCanCreate, eOpenOptionCanCreateNewOnly, eOpenOptionNonBlocking, eOpenOptionReadOnly, eOpenOptionReadWrite, eOpenOptionTruncate, eOpenOptionWriteOnly, and O_NONBLOCK.

◆ DescriptorIsValid()

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

inlinestatic

Definition at line 71 of file File.h.

Referenced by CalculateInteractiveAndTerminal(), lldb_private::NativeFile::DescriptorIsValidUnlocked(), GetPermissions(), and lldb_private::FileSystem::Open().

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

Referenced by Close(), and Sync().

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

References kInvalidDescriptor.

Referenced by CalculateInteractiveAndTerminal(), GetPermissions(), and 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_spec the file specification.

Returns: ENOTSUP, success, or another error.

Reimplemented in lldb_private::NativeFile.

Definition at line 121 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 193 of file File.cpp.

References CalculateInteractiveAndTerminal(), lldb_private::eLazyBoolCalculate, lldb_private::eLazyBoolYes, and m_is_interactive.

Referenced by lldb_private::CommandObjectGUI::DoExecute(), and lldb_private::Debugger::HandleProgressEvent().

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

References CalculateInteractiveAndTerminal(), lldb_private::eLazyBoolCalculate, lldb_private::eLazyBoolYes, and m_is_real_terminal.

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

References CalculateInteractiveAndTerminal(), lldb_private::eLazyBoolCalculate, lldb_private::eLazyBoolYes, and m_supports_colors.

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

◆ GetOpenMode()

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

inline

Definition at line 320 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 229 of file File.cpp.

Referenced by GetOpenMode().

◆ GetOptionsFromMode()

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

static

Definition at line 80 of file File.cpp.

References eOpenOptionAppend, eOpenOptionCanCreate, eOpenOptionInvalid, eOpenOptionReadOnly, eOpenOptionReadWrite, eOpenOptionTruncate, and eOpenOptionWriteOnly.

Referenced by lldb::SBFile::SBFile().

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

References DescriptorIsValid(), error(), GetDescriptor(), 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 128 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 45 of file File.cpp.

References eOpenOptionAppend, eOpenOptionCanCreate, eOpenOptionCanCreateNewOnly, eOpenOptionReadOnly, eOpenOptionReadWrite, and eOpenOptionWriteOnly.

Referenced by GetOpenMode(), and lldb_private::NativeFile::GetStream().

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

References lldb_private::IOObject::kInvalidHandleValue.

◆ isA()

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

inlinevirtual

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

Definition at line 363 of file File.h.

References ID.

Referenced by classof(), lldb_private::NativeFile::classof(), lldb_private::SerialPort::classof(), lldb_private::NativeFile::isA(), and lldb_private::SerialPort::isA().

◆ IsValid()

bool File::IsValid ( ) const

overridevirtual

IsValid.

Returns: true iff the file is valid.

Implements lldb_private::IOObject.

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

Definition at line 113 of file File.cpp.

Referenced by CommandObjectSettingsWrite::DoExecute(), lldb_private::ScriptInterpreterLua::ExecuteInterpreterLoop(), operator bool(), operator!(), and lldb_private::Target::SerializeBreakpointsToFile().

◆ operator bool()

lldb_private::File::operator bool ( ) const

inline

Definition at line 358 of file File.h.

References IsValid().

◆ operator!()

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

inline

Definition at line 360 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]	format	A printf style format string.
[in]	...	Variable arguments that are needed for the printf style format string format.

Definition at line 211 of file File.cpp.

References PrintfVarArg().

Referenced by lldb_private::CommandInterpreter::HandleCommandsFromFile().

◆ 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]	format	A printf style format string.
[in]	args	Variable arguments that are needed for the printf style format string format.

Reimplemented in lldb_private::NativeFile.

Definition at line 219 of file File.cpp.

References lldb_private::VASprintf(), and Write().

Referenced by Printf(), and lldb_private::NativeFile::PrintfVarArg().

◆ 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_bytes Pass 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 106 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]	dst	A buffer where to put the bytes that are read.
[in,out]	num_bytes	The number of bytes to read from the current file position which gets modified with the number of bytes that were read.
[in,out]	offset	The 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 148 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]	offset	The offset to seek to within the file relative to the current file position.
[in]	error_ptr	A 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 136 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]	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.
[in]	error_ptr	A 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 142 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]	offset	The offset to seek to within the file relative to the beginning of the file.
[in]	error_ptr	A 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 130 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 158 of file File.cpp.

References Flush().

◆ 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_bytes Pass 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 109 of file File.cpp.

Referenced by PrintfVarArg().

◆ 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]	src	A buffer containing the bytes to write.
[in,out]	num_bytes	The 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]	offset	The 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 152 of file File.cpp.

Member Data Documentation

◆ ID

char File::ID = 0

static

Definition at line 362 of file File.h.

Referenced by classof(), and isA().

◆ kInvalidDescriptor

int File::kInvalidDescriptor = -1

static

Definition at line 38 of file File.h.

Referenced by lldb_private::NativeFile::Close(), GetDescriptor(), lldb_private::NativeFile::GetDescriptor(), lldb_private::process_gdb_remote::GDBRemoteCommunicationServerCommon::Handle_vFile_Open(), lldb_private::NativeFile::Read(), lldb_private::Debugger::SaveInputTerminalState(), and lldb_private::NativeFile::Write().

◆ kInvalidStream

FILE * File::kInvalidStream = nullptr

static

Definition at line 39 of file File.h.

Referenced by lldb_private::NativeFile::Close(), and lldb_private::NativeFile::StreamIsValidUnlocked().

◆ m_is_interactive

LazyBool lldb_private::File::m_is_interactive = eLazyBoolCalculate

protected

Definition at line 367 of file File.h.

Referenced by CalculateInteractiveAndTerminal(), lldb_private::NativeFile::Close(), GetIsInteractive(), and lldb_private::SerialPort::IsValid().

◆ m_is_real_terminal

LazyBool lldb_private::File::m_is_real_terminal = eLazyBoolCalculate

protected

Definition at line 368 of file File.h.

Referenced by CalculateInteractiveAndTerminal(), lldb_private::NativeFile::Close(), and GetIsRealTerminal().

◆ m_supports_colors

LazyBool lldb_private::File::m_supports_colors = eLazyBoolCalculate

protected

Definition at line 369 of file File.h.

Referenced by CalculateInteractiveAndTerminal(), and GetIsTerminalWithColors().

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

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Private Member Functions

Detailed Description

Member Enumeration Documentation

◆ OpenOptions

Constructor & Destructor Documentation

◆ File() [1/2]

◆ File() [2/2]

Member Function Documentation

◆ CalculateInteractiveAndTerminal()

◆ classof()

◆ Close()

◆ ConvertOpenOptionsForPOSIXOpen()

◆ DescriptorIsValid()

◆ Flush()

◆ GetDescriptor()

◆ GetFileSpec()

◆ GetIsInteractive()

◆ GetIsRealTerminal()

◆ GetIsTerminalWithColors()

◆ GetOpenMode()

◆ GetOptions()

◆ GetOptionsFromMode()

◆ GetPermissions()

◆ GetStream()

◆ GetStreamOpenModeFromOptions()

◆ GetWaitableHandle()

◆ isA()

◆ IsValid()

◆ operator bool()

◆ operator!()

◆ operator=()

◆ Printf()

◆ PrintfVarArg()

◆ Read() [1/2]

◆ Read() [2/2]

◆ SeekFromCurrent()

◆ SeekFromEnd()

◆ SeekFromStart()

◆ Sync()

◆ Write() [1/2]

◆ Write() [2/2]

Member Data Documentation

◆ ID

◆ kInvalidDescriptor

◆ kInvalidStream

◆ m_is_interactive

◆ m_is_real_terminal

◆ m_supports_colors