Virtual file handle. More...

#include <cpl_vsi_virtual.h>

Inherited by VSISparseFileHandle, VSISubFileHandle, and VSIUploadOnCloseHandle.

Public Member Functions
virtual int	Seek (vsi_l_offset nOffset, int nWhence)=0
	Seek to requested offset.

virtual vsi_l_offset	Tell ()=0
	Tell current file offset.

virtual size_t	Read (void *pBuffer, size_t nSize, size_t nCount)=0
	Read bytes from file.

virtual int	ReadMultiRange (int nRanges, void *ppData, const vsi_l_offset panOffsets, const size_t *panSizes)
	Read several ranges of bytes from file.

virtual void	AdviseRead (int nRanges, const vsi_l_offset panOffsets, const size_t panSizes)
	This method is called when code plans to access soon one or several ranges in a file.

virtual size_t	GetAdviseReadTotalBytesLimit () const
	Return the total maximum number of bytes that AdviseRead() can handle at once.

virtual size_t	Write (const void *pBuffer, size_t nSize, size_t nCount)=0
	Write bytes to file.

int	Printf (const char *pszFormat,...)
	Formatted write to file.

virtual void	ClearErr ()=0
	Reset the error and end-of-file indicators.

virtual int	Eof ()=0
	Test for end of file.

virtual int	Error ()=0
	Test the error indicator.

virtual int	Flush ()
	Flush pending writes to disk.

virtual int	Close ()=0
	Close file.

virtual int	Truncate (vsi_l_offset nNewSize)
	Truncate/expand the file to the specified size.

virtual void *	GetNativeFileDescriptor ()
	Returns the "native" file descriptor for the virtual handle.

virtual VSIRangeStatus	GetRangeStatus (vsi_l_offset nOffset, vsi_l_offset nLength)
	Return if a given file range contains data or holes filled with zeroes.

virtual bool	HasPRead () const
	Returns whether this file handle supports the PRead() method.

virtual size_t	PRead (void *pBuffer, size_t nSize, vsi_l_offset nOffset) const
	Do a parallel-compatible read operation.

virtual void	Interrupt ()
	Ask current operations to be interrupted.

Detailed Description

Virtual file handle.

Member Function Documentation

◆ AdviseRead()

virtual void VSIVirtualHandle::AdviseRead	(	int	nRanges,
		const vsi_l_offset *	panOffsets,
		const size_t *	panSizes
	)

inlinevirtual

This method is called when code plans to access soon one or several ranges in a file.

Some file systems may be able to use this hint to for example asynchronously start such requests.

Offsets may be given in a non-increasing order, and may potentially overlap.

Parameters

nRanges	Size of the panOffsets and panSizes arrays.
panOffsets	Array containing the start offset of each range.
panSizes	Array containing the size (in bytes) of each range.

Since: GDAL 3.7

◆ ClearErr()

VSIVirtualHandle::ClearErr ( )

pure virtual

Reset the error and end-of-file indicators.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX clearerr() call.

Since: 3.10

◆ Close()

VSIVirtualHandle::Close ( )

pure virtual

Close file.

This function closes the indicated file.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX fclose() function.

Returns: 0 on success or -1 on failure.

◆ Eof()

VSIVirtualHandle::Eof ( )

pure virtual

Test for end of file.

Returns TRUE (non-zero) if an end-of-file condition occurred during the previous read operation. The end-of-file flag is cleared by a successful VSIFSeekL() call, or a call to VSIFClearErrL().

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX feof() call.

Returns: TRUE if at EOF, else FALSE.

◆ Error()

VSIVirtualHandle::Error ( )

pure virtual

Test the error indicator.

Returns TRUE (non-zero) if an error condition occurred during the previous read operation. The error indicator is cleared by a call to VSIFClearErrL(). Note that a end-of-file situation, reported by VSIFEofL(), is not an error reported by VSIFErrorL().

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX ferror() call.

Returns: TRUE if the error indicator is set, else FALSE.

Since: 3.10

◆ Flush()

VSIVirtualHandle::Flush ( )

inlinevirtual

Flush pending writes to disk.

For files in write or update mode and on filesystem types where it is applicable, all pending output on the file is flushed to the physical disk.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX fflush() call.

On Windows regular files, this method does nothing, unless the VSI_FLUSH configuration option is set to YES (and only when the file has not been opened with the WRITE_THROUGH option).

Returns: 0 on success or -1 on error.

◆ GetAdviseReadTotalBytesLimit()

virtual size_t VSIVirtualHandle::GetAdviseReadTotalBytesLimit ( ) const

inlinevirtual

Return the total maximum number of bytes that AdviseRead() can handle at once.

Some AdviseRead() implementations may give up if the sum of the values in the panSizes[] array provided to AdviseRead() exceeds a limit.

Callers might use that threshold to optimize the efficiency of AdviseRead().

A returned value of 0 indicates a unknown limit.

Since: GDAL 3.9

◆ GetNativeFileDescriptor()

VSIVirtualHandle::GetNativeFileDescriptor ( )

inlinevirtual

Returns the "native" file descriptor for the virtual handle.

This will only return a non-NULL value for "real" files handled by the operating system (to be opposed to GDAL virtual file systems).

On POSIX systems, this will be a integer value ("fd") cast as a void*. On Windows systems, this will be the HANDLE.

Returns: the native file descriptor, or NULL.

◆ GetRangeStatus()

VSIVirtualHandle::GetRangeStatus	(	vsi_l_offset	nOffset,
		vsi_l_offset	nLength
	)

inlinevirtual

Return if a given file range contains data or holes filled with zeroes.

This uses the filesystem capabilities of querying which regions of a sparse file are allocated or not. This is currently only implemented for Linux (and no other Unix derivatives) and Windows.

Note: A return of VSI_RANGE_STATUS_DATA doesn't exclude that the extent is filled with zeroes! It must be interpreted as "may contain non-zero data".

Parameters

nOffset	offset of the start of the extent.
nLength	extent length.

Returns: extent status: VSI_RANGE_STATUS_UNKNOWN, VSI_RANGE_STATUS_DATA or VSI_RANGE_STATUS_HOLE

Since: GDAL 2.2

◆ HasPRead()

bool VSIVirtualHandle::HasPRead ( ) const

virtual

Returns whether this file handle supports the PRead() method.

Since: GDAL 3.6

◆ Interrupt()

virtual void VSIVirtualHandle::Interrupt ( )

inlinevirtual

Ask current operations to be interrupted.

Implementations must be thread-safe, as this will typically be called from another thread than the active one for this file.

◆ PRead()

size_t VSIVirtualHandle::PRead	(	void *	pBuffer,
		size_t	nSize,
		vsi_l_offset	nOffset
	)		const

virtual

Do a parallel-compatible read operation.

This methods reads into pBuffer up to nSize bytes starting at offset nOffset in the file. The current file offset is not affected by this method.

The implementation is thread-safe: several threads can issue PRead() concurrently on the same VSIVirtualHandle object.

This method has the same semantics as pread() Linux operation. It is only available if HasPRead() returns true.

Parameters

pBuffer	output buffer (must be at least nSize bytes large).
nSize	number of bytes to read in the file.
nOffset	file offset from which to read.

Returns: number of bytes read.

Since: GDAL 3.6

◆ Printf()

int VSIVirtualHandle::Printf	(	const char *	pszFormat,
			...
	)

Formatted write to file.

Provides fprintf() style formatted output to a VSI*L file. This formats an internal buffer which is written using VSIFWriteL().

Analog of the POSIX fprintf() call.

Parameters

pszFormat the printf() style format string.

Returns: the number of bytes written or -1 on an error.

◆ Read()

VSIVirtualHandle::Read	(	void *	pBuffer,
		size_t	nSize,
		size_t	nCount
	)

pure virtual

Read bytes from file.

Reads nCount objects of nSize bytes from the indicated file at the current offset into the indicated buffer.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX fread() call.

Parameters

pBuffer	the buffer into which the data should be read (at least nCount * nSize bytes in size.
nSize	size of objects to read in bytes.
nCount	number of objects to read.

Returns: number of objects successfully read. If that number is less than nCount, VSIFEofL() or VSIFErrorL() can be used to determine the reason for the short read.

◆ ReadMultiRange()

VSIVirtualHandle::ReadMultiRange	(	int	nRanges,
		void **	ppData,
		const vsi_l_offset *	panOffsets,
		const size_t *	panSizes
	)

virtual

Read several ranges of bytes from file.

Reads nRanges objects of panSizes[i] bytes from the indicated file at the offset panOffsets[i] into the buffer ppData[i].

Ranges must be sorted in ascending start offset, and must not overlap each other.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory or /vsicurl/.

Parameters

nRanges	number of ranges to read.
ppData	array of nRanges buffer into which the data should be read (ppData[i] must be at list panSizes[i] bytes).
panOffsets	array of nRanges offsets at which the data should be read.
panSizes	array of nRanges sizes of objects to read (in bytes).

Returns: 0 in case of success, -1 otherwise.

Since: GDAL 1.9.0

◆ Seek()

int VSIVirtualHandle::Seek	(	vsi_l_offset	nOffset,
		int	nWhence
	)

pure virtual

Seek to requested offset.

Seek to the desired offset (nOffset) in the indicated file.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX fseek() call.

Caution: vsi_l_offset is a unsigned type, so SEEK_CUR can only be used for positive seek. If negative seek is needed, use handle->Seek( handle->Tell() + negative_offset, SEEK_SET ).

Parameters

nOffset	offset in bytes.
nWhence	one of SEEK_SET, SEEK_CUR or SEEK_END.

Returns: 0 on success or -1 one failure.

◆ Tell()

VSIVirtualHandle::Tell ( )

pure virtual

Tell current file offset.

Returns the current file read/write offset in bytes from the beginning of the file.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX ftell() call.

Returns: file offset in bytes.

◆ Truncate()

VSIVirtualHandle::Truncate ( vsi_l_offset nNewSize )

virtual

Truncate/expand the file to the specified size.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX ftruncate() call.

Parameters

nNewSize new size in bytes.

Returns: 0 on success

Since: GDAL 1.9.0

◆ Write()

VSIVirtualHandle::Write	(	const void *	pBuffer,
		size_t	nSize,
		size_t	nCount
	)

pure virtual

Write bytes to file.

Writes nCount objects of nSize bytes to the indicated file at the current offset into the indicated buffer.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX fwrite() call.

Parameters

pBuffer	the buffer from which the data should be written (at least nCount * nSize bytes in size.
nSize	size of objects to write in bytes.
nCount	number of objects to write.

Returns: number of objects successfully written.

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

cpl_vsi_virtual.h
cpl_vsil.cpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ AdviseRead()

◆ ClearErr()

◆ Close()

◆ Eof()

◆ Error()

◆ Flush()

◆ GetAdviseReadTotalBytesLimit()

◆ GetNativeFileDescriptor()

◆ GetRangeStatus()

◆ HasPRead()

◆ Interrupt()

◆ PRead()

◆ Printf()

◆ Read()

◆ ReadMultiRange()

◆ Seek()

◆ Tell()

◆ Truncate()

◆ Write()