Virtual file handle. More...

#include <cpl_vsi_virtual.h>

Inherited by VSISparseFileHandle, and VSISubFileHandle.

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

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

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

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

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

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

virtual int	Flush ()
	Flush pending writes to disk. More...

virtual int	Close ()=0
	Close file. More...

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

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

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

Detailed Description

Virtual file handle.

Member Function Documentation

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

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.

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

Returns: 0 on success or -1 on error.

◆ 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

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

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

Writess 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 read in bytes.
nCount	number of objects to read.

Returns: number of objects successfully written.

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

cpl_vsi_virtual.h
cpl_vsil.cpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ Close()

◆ Eof()

◆ Flush()

◆ GetNativeFileDescriptor()

◆ GetRangeStatus()

◆ Read()

◆ ReadMultiRange()

◆ Seek()

◆ Tell()

◆ Truncate()

◆ Write()