GDAL

Public Member Functions | List of all members
VSIVirtualHandle Struct Referenceabstract

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. 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 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. More...
virtual size_t | GetAdviseReadTotalBytesLimit () const
| Return the total maximum number of bytes that AdviseRead() can handle at once. More...
virtual size_t | Write (const void *pBuffer, size_t nSize, size_t nCount)=0
| Write bytes to file. More...
int | Printf (const char *pszFormat,...)
| Formatted write 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...
virtual bool | HasPRead () const
| Returns whether this file handle supports the PRead() method. More...
virtual size_t | PRead (void *pBuffer, size_t nSize, vsi_l_offset nOffset) const
| Do a parallel-compatible read operation. More...

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

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

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

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

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