GDAL

- Main Page
- Related Pages
- Classes
- Files
- Download
- Issue Tracker

- File List
- File Members

Macros | Typedefs | Enumerations | Functions
cpl_vsi.h File Reference

Standard C Covers. More...

`#include "cpl_port.h"`
`#include <unistd.h>`
`#include <sys/stat.h>`

Go to the source code of this file.

## Macros
#define | VSI_ISLNK(x) S_ISLNK(x)
| Test if the file is a symbolic link.
#define | VSI_ISREG(x) S_ISREG(x)
| Test if the file is a regular file.
#define | VSI_ISDIR(x) S_ISDIR(x)
| Test if the file is a directory.
#define | VSI_L_OFFSET_MAX GUINTBIG_MAX
| Maximum value for a file offset.
#define | VSI_STAT_EXISTS_FLAG 0x1
| Flag provided to VSIStatExL() to test if the file exists.
#define | VSI_STAT_NATURE_FLAG 0x2
| Flag provided to VSIStatExL() to query the nature (file/dir) of the file.
#define | VSI_STAT_SIZE_FLAG 0x4
| Flag provided to VSIStatExL() to query the file size.
#define | VSI_STAT_SET_ERROR_FLAG 0x8
| Flag provided to VSIStatExL() to issue a VSIError in case of failure.
#define | VSI_MALLOC_ALIGNED_AUTO_VERBOSE(size) VSIMallocAlignedAutoVerbose(size,__FILE__,__LINE__)
| VSIMallocAlignedAutoVerbose() with FILE and LINE reporting.
#define | VSI_MALLOC_VERBOSE(size) VSIMallocVerbose(size,__FILE__,__LINE__)
| VSI_MALLOC_VERBOSE.
#define | VSI_MALLOC2_VERBOSE(nSize1, nSize2) VSIMalloc2Verbose(nSize1,nSize2,__FILE__,__LINE__)
| VSI_MALLOC2_VERBOSE.
#define | VSI_MALLOC3_VERBOSE(nSize1, nSize2, nSize3) VSIMalloc3Verbose(nSize1,nSize2,nSize3,__FILE__,__LINE__)
| VSI_MALLOC3_VERBOSE.
#define | VSI_CALLOC_VERBOSE(nCount, nSize) VSICallocVerbose(nCount,nSize,__FILE__,__LINE__)
| VSI_CALLOC_VERBOSE.
#define | VSI_REALLOC_VERBOSE(pOldPtr, nNewSize) VSIReallocVerbose(pOldPtr,nNewSize,__FILE__,__LINE__)
| VSI_REALLOC_VERBOSE.
#define | VSI_STRDUP_VERBOSE(pszStr) VSIStrdupVerbose(pszStr,__FILE__,__LINE__)
| VSI_STRDUP_VERBOSE.
#define | CPLReadDir VSIReadDir
| Alias of VSIReadDir()

## Typedefs
typedef GUIntBig | vsi_l_offset
| Type for a file offset.
typedef FILE | VSILFILE
| Opaque type for a FILE that implements the VSIVirtualHandle API.
typedef struct VSI_STAT64_T | VSIStatBufL
| Type for VSIStatL()
typedef size_t(* | VSIWriteFunction )(const void *ptr, size_t size, size_t nmemb, FILE *stream)
| Callback used by VSIStdoutSetRedirection()

## Enumerations
enum | VSIRangeStatus { VSI_RANGE_STATUS_UNKNOWN, VSI_RANGE_STATUS_DATA, VSI_RANGE_STATUS_HOLE }
| Range status. More...

## Functions
VSILFILE * | VSIFOpenL (const char *, const char *) CPL_WARN_UNUSED_RESULT
| Open file. More...
VSILFILE * | VSIFOpenExL (const char *, const char *, int) CPL_WARN_UNUSED_RESULT
| Open file. More...
int | VSIFCloseL (VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
| Close file. More...
int | VSIFSeekL (VSILFILE *, vsi_l_offset, int) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
| Seek to requested offset. More...
vsi_l_offset | VSIFTellL (VSILFILE *) CPL_WARN_UNUSED_RESULT
| Tell current file offset. More...
void | VSIRewindL (VSILFILE *)
| Rewind the file pointer to the beginning of the file. More...
size_t | VSIFReadL (void *, size_t, size_t, VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
| Read bytes from file. More...
int | VSIFReadMultiRangeL (int nRanges, void **ppData, const vsi_l_offset *panOffsets, const size_t *panSizes, VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
| Read several ranges of bytes from file. More...
size_t | VSIFWriteL (const void *, size_t, size_t, VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
| Write bytes to file. More...
int | VSIFEofL (VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
| Test for end of file. More...
int | VSIFTruncateL (VSILFILE *, vsi_l_offset) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
| Truncate/expand the file to the specified size. More...
int | VSIFFlushL (VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
| Flush pending writes to disk. More...
int | VSIFPrintfL (VSILFILE *, const char *,...) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
| Formatted write to file. More...
int | VSIFPutcL (int, VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
| Write a single byte to the file. More...
VSIRangeStatus | VSIFGetRangeStatusL (VSILFILE *fp, vsi_l_offset nStart, vsi_l_offset nLength)
| Return if a given file range contains data or holes filled with zeroes. More...
int | VSIIngestFile (VSILFILE *fp, const char *pszFilename, GByte **ppabyRet, vsi_l_offset *pnSize, GIntBig nMaxSize) CPL_WARN_UNUSED_RESULT
| Ingest a file into memory. More...
int | VSIStatL (const char *, VSIStatBufL *) CPL_WARN_UNUSED_RESULT
| Get filesystem object info. More...
int | VSIStatExL (const char *pszFilename, VSIStatBufL *psStatBuf, int nFlags) CPL_WARN_UNUSED_RESULT
| Get filesystem object info. More...
int | VSIIsCaseSensitiveFS (const char *pszFilename)
| Returns if the filenames of the filesystem are case sensitive. More...
int | VSISupportsSparseFiles (const char *pszPath)
| Returns if the filesystem supports sparse files. More...
void * | VSIFGetNativeFileDescriptorL (VSILFILE *)
| Returns the "native" file descriptor for the virtual handle. More...
void * | VSICalloc (size_t, size_t) CPL_WARN_UNUSED_RESULT
| Analog of calloc(). More...
void * | VSIMalloc (size_t) CPL_WARN_UNUSED_RESULT
| Analog of malloc(). More...
void | VSIFree (void *)
| Analog of free() for data allocated with VSIMalloc(), VSICalloc(), VSIRealloc()
void * | VSIRealloc (void *, size_t) CPL_WARN_UNUSED_RESULT
| Analog of realloc(). More...
char * | VSIStrdup (const char *) CPL_WARN_UNUSED_RESULT
| Analog of strdup(). More...
void * | VSIMallocAligned (size_t nAlignment, size_t nSize) CPL_WARN_UNUSED_RESULT
| Allocates a buffer with an alignment constraint. More...
void * | VSIMallocAlignedAuto (size_t nSize) CPL_WARN_UNUSED_RESULT
| Allocates a buffer with an alignment constraint such that it can be used by the most demanding vector instruction set on that platform. More...
void | VSIFreeAligned (void *ptr)
| Free a buffer allocated with VSIMallocAligned(). More...
void * | VSIMallocAlignedAutoVerbose (size_t nSize, const char *pszFile, int nLine) CPL_WARN_UNUSED_RESULT
| See VSIMallocAlignedAuto()
void * | VSIMalloc2 (size_t nSize1, size_t nSize2) CPL_WARN_UNUSED_RESULT
| VSIMalloc2 allocates (nSize1 * nSize2) bytes. More...
void * | VSIMalloc3 (size_t nSize1, size_t nSize2, size_t nSize3) CPL_WARN_UNUSED_RESULT
| VSIMalloc3 allocates (nSize1 * nSize2 * nSize3) bytes. More...
void * | VSIMallocVerbose (size_t nSize, const char *pszFile, int nLine) CPL_WARN_UNUSED_RESULT
| VSIMallocVerbose.
void * | VSIMalloc2Verbose (size_t nSize1, size_t nSize2, const char *pszFile, int nLine) CPL_WARN_UNUSED_RESULT
| VSIMalloc2Verbose.
void * | VSIMalloc3Verbose (size_t nSize1, size_t nSize2, size_t nSize3, const char *pszFile, int nLine) CPL_WARN_UNUSED_RESULT
| VSIMalloc3Verbose.
void * | VSICallocVerbose (size_t nCount, size_t nSize, const char *pszFile, int nLine) CPL_WARN_UNUSED_RESULT
| VSICallocVerbose.
void * | VSIReallocVerbose (void *pOldPtr, size_t nNewSize, const char *pszFile, int nLine) CPL_WARN_UNUSED_RESULT
| VSIReallocVerbose.
char * | VSIStrdupVerbose (const char *pszStr, const char *pszFile, int nLine) CPL_WARN_UNUSED_RESULT
| VSIStrdupVerbose.
GIntBig | CPLGetPhysicalRAM (void)
| Return the total physical RAM in bytes. More...
GIntBig | CPLGetUsablePhysicalRAM (void)
| Return the total physical RAM, usable by a process, in bytes. More...
char ** | VSIReadDir (const char *)
| Read names in a directory. More...
char ** | VSIReadDirRecursive (const char *pszPath)
| Read names in a directory recursively. More...
char ** | VSIReadDirEx (const char *pszPath, int nMaxFiles)
| Read names in a directory. More...
int | VSIMkdir (const char *pathname, long mode)
| Create a directory. More...
int | VSIRmdir (const char *pathname)
| Delete a directory. More...
int | VSIUnlink (const char *pathname)
| Delete a file. More...
int | VSIRename (const char *oldpath, const char *newpath)
| Rename a file. More...
char * | VSIStrerror (int)
| Return the error string corresponding to the error number. More...
GIntBig | VSIGetDiskFreeSpace (const char *pszDirname)
| Return free disk space available on the filesystem. More...
void | VSIInstallMemFileHandler (void)
| Install "memory" file system handler. More...
void | VSIInstallSubFileHandler (void)
| Install /vsisubfile/ virtual file handler. More...
void | VSIInstallCurlFileHandler (void)
| Install /vsicurl/ HTTP/FTP file system handler (requires libcurl) More...
void | VSIInstallCurlStreamingFileHandler (void)
| Install /vsicurl_streaming/ HTTP/FTP file system handler (requires libcurl). More...
void | VSIInstallS3FileHandler (void)
| Install /vsis3/ Amazon S3 file system handler (requires libcurl) More...
void | VSIInstallS3StreamingFileHandler (void)
| Install /vsis3_streaming/ Amazon S3 file system handler (requires libcurl). More...
void | VSIInstallGSFileHandler (void)
| Install /vsigs/ Google Cloud Storage file system handler (requires libcurl) More...
void | VSIInstallGSStreamingFileHandler (void)
| Install /vsigs_streaming/ Google Cloud Storage file system handler (requires libcurl) More...
void | VSIInstallGZipFileHandler (void)
| Install GZip file system handler. More...
void | VSIInstallZipFileHandler (void)
| Install ZIP file system handler. More...
void | VSIInstallStdinHandler (void)
| Install /vsistdin/ file system handler. More...
void | VSIInstallStdoutHandler (void)
| Install /vsistdout/ file system handler. More...
void | VSIInstallSparseFileHandler (void)
| Install /vsisparse/ virtual file handler. More...
void | VSIInstallTarFileHandler (void)
| Install /vsitar/ file system handler. More...
void | VSIInstallCryptFileHandler (void)
| Install /vsicrypt/ encrypted file system handler (requires libcrypto++) More...
void | VSISetCryptKey (const GByte *pabyKey, int nKeySize)
| Installs the encryption/decryption key. More...
VSILFILE * | VSIFileFromMemBuffer (const char *pszFilename, GByte *pabyData, vsi_l_offset nDataLength, int bTakeOwnership) CPL_WARN_UNUSED_RESULT
| Create memory "file" from a buffer. More...
GByte * | VSIGetMemFileBuffer (const char *pszFilename, vsi_l_offset *pnDataLength, int bUnlinkAndSeize)
| Fetch buffer underlying memory file. More...
void | VSIStdoutSetRedirection (VSIWriteFunction pFct, FILE *stream)
| Set an alternative write function and output file handle instead of fwrite() / stdout. More...

## Detailed Description

Standard C Covers.

The VSI functions are intended to be hookable aliases for Standard C I/O, memory allocation and other system functions. They are intended to allow virtualization of disk I/O so that non file data sources can be made to appear as files, and so that additional error trapping and reporting can be interested. The memory access API is aliased so that special application memory management services can be used.

It is intended that each of these functions retains exactly the same calling pattern as the original Standard C functions they relate to. This means we don't have to provide custom documentation, and also means that the default implementation is very simple.

## Enumeration Type Documentation

enum VSIRangeStatus

Range status.

Enumerator
VSI_RANGE_STATUS_UNKNOWN | Unknown.
VSI_RANGE_STATUS_DATA | Data present.
VSI_RANGE_STATUS_HOLE | Hole.

## Function Documentation

GIntBig CPLGetPhysicalRAM | ( | void |  | ) |

Return the total physical RAM in bytes.

Returns
  the total physical RAM in bytes (or 0 in case of failure).

Since
  GDAL 2.0

GIntBig CPLGetUsablePhysicalRAM | ( | void |  | ) |

Return the total physical RAM, usable by a process, in bytes.

This is the same as CPLGetPhysicalRAM() except it will limit to 2 GB for 32 bit processes.

Note: This memory may already be partly used by other processes.

Returns
  the total physical RAM, usable by a process, in bytes (or 0 in case of failure).

Since
  GDAL 2.0

void* VSICalloc | ( | size_t | nCount,
|  | size_t | nSize
| ) |  |

Analog of calloc().

Use VSIFree() to free

int VSIFCloseL | ( | VSILFILE * | fp | ) |

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.

Parameters

  fp | file handle opened with VSIFOpenL(). Passing a nullptr produces undefined behavior.

Returns
  0 on success or -1 on failure.

int VSIFEofL | ( | VSILFILE * | fp | ) |

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.

Parameters

  fp | file handle opened with VSIFOpenL().

Returns
  TRUE if at EOF else FALSE.

int VSIFFlushL | ( | VSILFILE * | fp | ) |

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.

Parameters

  fp | file handle opened with VSIFOpenL().

Returns
  0 on success or -1 on error.

void* VSIFGetNativeFileDescriptorL | ( | VSILFILE * | fp | ) |

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.

Parameters

  fp | file handle opened with VSIFOpenL().

Returns
  the native file descriptor, or NULL.

VSIRangeStatus VSIFGetRangeStatusL | ( | VSILFILE * | fp,
|  | vsi_l_offset | nOffset,
|  | vsi_l_offset | nLength
| ) |  |

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 exte,t is filled with zeroes! It must be interpreted as "may contain non-zero data".

Parameters

  fp | file handle opened with VSIFOpenL().
  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

VSILFILE* VSIFileFromMemBuffer | ( | const char * | pszFilename,
|  | GByte * | pabyData,
|  | vsi_l_offset | nDataLength,
|  | int | bTakeOwnership
| ) |  |

Create memory "file" from a buffer.

A virtual memory file is created from the passed buffer with the indicated filename. Under normal conditions the filename would need to be absolute and within the /vsimem/ portion of the filesystem.

If bTakeOwnership is TRUE, then the memory file system handler will take ownership of the buffer, freeing it when the file is deleted. Otherwise it remains the responsibility of the caller, but should not be freed as long as it might be accessed as a file. In no circumstances does this function take a copy of the pabyData contents.

Parameters

  pszFilename | the filename to be created.
  pabyData | the data buffer for the file.
  nDataLength | the length of buffer in bytes.
  bTakeOwnership | TRUE to transfer "ownership" of buffer or FALSE.

Returns
  open file handle on created file (see VSIFOpenL()).

VSILFILE* VSIFOpenExL | ( | const char * | pszFilename,
|  | const char * | pszAccess,
|  | int | bSetError
| ) |  |

Open file.

This function opens a file with the desired access. Large files (larger than 2GB) should be supported. Binary access is always implied and the "b" does not need to be included in the pszAccess string.

Note that the "VSILFILE *" returned by this function is NOT a standard C library FILE *, and cannot be used with any functions other than the "VSI*L" family of functions. They aren't "real" FILE objects.

On windows it is possible to define the configuration option GDAL_FILE_IS_UTF8 to have pszFilename treated as being in the local encoding instead of UTF-8, restoring the pre-1.8.0 behavior of VSIFOpenL().

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

Analog of the POSIX fopen() function.

Parameters

  pszFilename | the file to open. UTF-8 encoded.
  pszAccess | access requested (i.e. "r", "r+", "w")
  bSetError | flag determining whether or not this open call should set VSIErrors on failure.

Returns
  NULL on failure, or the file handle.

Since
  GDAL 2.1

VSILFILE* VSIFOpenL | ( | const char * | pszFilename,
|  | const char * | pszAccess
| ) |  |

Open file.

This function opens a file with the desired access. Large files (larger than 2GB) should be supported. Binary access is always implied and the "b" does not need to be included in the pszAccess string.

Note that the "VSILFILE *" returned since GDAL 1.8.0 by this function is NOT a standard C library FILE *, and cannot be used with any functions other than the "VSI*L" family of functions. They aren't "real" FILE objects.

On windows it is possible to define the configuration option GDAL_FILE_IS_UTF8 to have pszFilename treated as being in the local encoding instead of UTF-8, restoring the pre-1.8.0 behavior of VSIFOpenL().

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

Analog of the POSIX fopen() function.

Parameters

  pszFilename | the file to open. UTF-8 encoded.
  pszAccess | access requested (i.e. "r", "r+", "w")

Returns
  NULL on failure, or the file handle.

int VSIFPrintfL | ( | VSILFILE * | fp,
|  | 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

  fp | file handle opened with VSIFOpenL().
  pszFormat | the printf() style format string.

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

int VSIFPutcL | ( | int | nChar,
|  | VSILFILE * | fp
| ) |  |

Write a single byte to the file.

Writes the character nChar, cast to an unsigned char, to file.

Almost an analog of the POSIX fputc() call, except that it returns the number of character written (1 or 0), and not the (cast) character itself or EOF.

Parameters

  nChar | character to write.
  fp | file handle opened with VSIFOpenL().

Returns
  1 in case of success, 0 on error.

size_t VSIFReadL | ( | void * | pBuffer,
|  | size_t | nSize,
|  | size_t | nCount,
|  | VSILFILE * | fp
| ) |  |

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.
  fp | file handle opened with VSIFOpenL().

Returns
  number of objects successfully read.

int VSIFReadMultiRangeL | ( | int | nRanges,
|  | void ** | ppData,
|  | const vsi_l_offset * | panOffsets,
|  | const size_t * | panSizes,
|  | VSILFILE * | fp
| ) |  |

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).
  fp | file handle opened with VSIFOpenL().

Returns
  0 in case of success, -1 otherwise.

Since
  GDAL 1.9.0

void VSIFreeAligned | ( | void * | ptr | ) |

Free a buffer allocated with VSIMallocAligned().

Parameters

  ptr | Buffer to free.

Since
  GDAL 2.2

int VSIFSeekL | ( | VSILFILE * | fp,
|  | vsi_l_offset | nOffset,
|  | int | nWhence
| ) |  |

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.

Parameters

  fp | file handle opened with VSIFOpenL().
  nOffset | offset in bytes.
  nWhence | one of SEEK_SET, SEEK_CUR or SEEK_END.

Returns
  0 on success or -1 one failure.

vsi_l_offset VSIFTellL | ( | VSILFILE * | fp | ) |

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.

Parameters

  fp | file handle opened with VSIFOpenL().

Returns
  file offset in bytes.

int VSIFTruncateL | ( | VSILFILE * | fp,
|  | vsi_l_offset | nNewSize
| ) |  |

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

  fp | file handle opened with VSIFOpenL().
  nNewSize | new size in bytes.

Returns
  0 on success

Since
  GDAL 1.9.0

size_t VSIFWriteL | ( | const void * | pBuffer,
|  | size_t | nSize,
|  | size_t | nCount,
|  | VSILFILE * | fp
| ) |  |

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.
  fp | file handle opened with VSIFOpenL().

Returns
  number of objects successfully written.

GIntBig VSIGetDiskFreeSpace | ( | const char * | pszDirname | ) |

Return free disk space available on the filesystem.

This function returns the free disk space available on the filesystem.

Parameters

  pszDirname | a directory of the filesystem to query.

Returns
  The free space in bytes. Or -1 in case of error.

Since
  GDAL 2.1

GByte* VSIGetMemFileBuffer | ( | const char * | pszFilename,
|  | vsi_l_offset * | pnDataLength,
|  | int | bUnlinkAndSeize
| ) |  |

Fetch buffer underlying memory file.

This function returns a pointer to the memory buffer underlying a virtual "in memory" file. If bUnlinkAndSeize is TRUE the filesystem object will be deleted, and ownership of the buffer will pass to the caller otherwise the underlying file will remain in existence.

Parameters

  pszFilename | the name of the file to grab the buffer of.
  pnDataLength | (file) length returned in this variable.
  bUnlinkAndSeize | TRUE to remove the file, or FALSE to leave unaltered.

Returns
  pointer to memory buffer or NULL on failure.

int VSIIngestFile | ( | VSILFILE * | fp,
|  | const char * | pszFilename,
|  | GByte ** | ppabyRet,
|  | vsi_l_offset * | pnSize,
|  | GIntBig | nMaxSize
| ) |  |

Ingest a file into memory.

Read the whole content of a file into a memory buffer.

Either fp or pszFilename can be NULL, but not both at the same time.

If fp is passed non-NULL, it is the responsibility of the caller to close it.

If non-NULL, the returned buffer is guaranteed to be NUL-terminated.

Parameters

  fp | file handle opened with VSIFOpenL().
  pszFilename | filename.
  ppabyRet | pointer to the target buffer. *ppabyRet must be freed with VSIFree()
  pnSize | pointer to variable to store the file size. May be NULL.
  nMaxSize | maximum size of file allowed. If no limit, set to a negative value.

Returns
  TRUE in case of success.

Since
  GDAL 1.11

void VSIInstallCryptFileHandler | ( | void |  | ) |

Install /vsicrypt/ encrypted file system handler (requires libcrypto++)

A special file handler is installed that allows reading/creating/update encrypted files on the fly, with random access capabilities.

The cryptographic algorithms used are block ciphers, with symmetric key.

In their simplest form, recognized filenames are of the form /vsicrypt//absolute_path/to/file, /vsicrypt/c:/absolute_path/to/file or /vsicrypt/relative/path/to/file.

Options can also be used with the following format : /vsicrypt/option1=val1,option2=val2,...,file=/path/to/file

They can also be passed as configuration option/environment variable, because in some use cases, the syntax with option in the filename might not properly work with some drivers.

In all modes, the encryption key must be provided. There are several ways of doing so :

- By adding a key= parameter to the filename, like /vsicrypt/key=my_secret_key,file=/path/to/file. Note that this restricts the key to be in text format, whereas at its full power, it can be binary content.
- By adding a key_b64= parameter to the filename, to specify a binary key expressed in Base64 encoding, like /vsicrypt/key_b64=th1sl00kslikebase64=,file=/path/to/file.
- By setting the VSICRYPT_KEY configuration option. The key should be in text format.
- By setting the VSICRYPT_KEY_B64 configuration option. The key should be encoded in Base64.
- By using the VSISetCryptKey() C function.

When creating a file, if key=GENERATE_IT or VSICRYPT_KEY=GENERATE_IT is passed, the encryption key will be generated from the pseudo-random number generator of the operating system. The key will be displayed on the standard error stream in a Base64 form (unless the VSICRYPT_DISPLAY_GENERATED_KEY configuration option is set to OFF), and the VSICRYPT_KEY_B64 configuration option will also be set with the Base64 form of the key (so that CPLGetConfigOption("VSICRYPT_KEY_B64", NULL) can be used to get it back).

The available options are :

- alg=AES/Blowfish/Camellia/CAST256/DES_EDE2/DES_EDE3/MARS/IDEA/RC5/RC6/Serpent/SHACAL2/SKIPJACK/Twofish/XTEA: to specify the block cipher algorithm. The default is AES. Only used on creation. Ignored otherwise. Note: depending on how GDAL is build, if linked against the DLL version of libcrypto++, only a subset of those algorithms will be available, namely AES, DES_EDE2, DES_EDE3 and SKIPJACK. Also available as VSICRYPT_ALG configuration option.
- mode=CBC/CFB/OFB/CTR/CBC_CTS: to specify the block cipher mode of operation. The default is CBC. Only used on creation. Ignored otherwise. Also available as VSICRYPT_MODE configuration option.
- key=text_key: see above.
- key_b64=base64_encoded_key: see above.
- freetext=some_text: to specify a text content that will be written unencrypted in the file header, for informational purposes. Default to empty. Only used on creation. Ignored otherwise. Also available as VSICRYPT_FREETEXT configuration option.
- sector_size=int_value: to specify the size of the "sector", which is the unit chunk of information that is encrypted/decrypted. Default to 512 bytes. The valid values depend on the algorithm and block cipher mode of operation. Only used on creation. Ignored otherwise. Also available as VSICRYPT_SECTOR_SIZE configuration option.

- iv=initial_vector_as_text: to specify the Initial Vector. This is an advanced option that should generally NOT be used. It is only useful to get completely deterministic output given the plaintext, key and other parameters, which in general NOT what you want to do. By default, a random initial vector of the appropriate size will be generated for each new file created. Only used on creation. Ignored otherwise. Also available as VSICRYPT_IV configuration option.

- add_key_check=YES/NO: whether a special value should be encrypted in the header, so as to be quickly able to determine if the decryption key is correct. Defaults to NO. Only used on creation. Ignored otherwise. Also available as VSICRYPT_ADD_KEY_CHECK configuration option.
- file=filename. To specify the filename. This must be the last option put in the option list (so as to make it possible to use filenames with comma in them. )

This special file handler can be combined with other virtual filesystems handlers, such as /vsizip. For example, /vsicrypt//vsicurl/path/to/remote/encrypted/file.tif

Implementation details:

The structure of encrypted files is the following: a header, immediately followed by the encrypted payload (by sectors, i.e. chunks of sector_size bytes).

The header structure is the following :

1. 8 bytes. Signature. Fixed value: VSICRYPT.
2. UINT16_LE. Header size (including previous signature bytes).
3. UINT8. Format major version. Current value: 1.
4. UINT8. Format minor version. Current value: 0.
5. UINT16. Sector size.
6. UINT8. Cipher algorithm. Valid values are: 0 = AES (Rijndael), 1 = Blowfish, 2 = Camellia, 3 = CAST256, 4 = DES_EDE2, 5 = DES_EDE3, 6 = MARS, 7 = IDEA, 8 = RC5, 9 = RC6, 10 = Serpent, 11 = SHACAL2, 12 = SKIPJACK, 13 = Twofish, 14 = XTEA.
7. UINT8. Block cipher mode of operation. Valid values are: 0 = CBC, 1 = CFB, 2 = OFB, 3 = CTR, 4 = CBC_CTS.
8. UINT8. Size in bytes of the Initial Vector.
9. N bytes with the content of the Initial Vector, where N is the value of the previous field.
10. UINT16_LE. Size in bytes of the free text.
11. N bytes with the content of the free text, where N is the value of the previous field.
12. UINT8. Size in bytes of encrypted content (key check), or 0 if key check is absent.
13. N bytes with encrypted content (key check), where N is the value of the previous field.
14. UINT64_LE. Size of the unencrypted file, in bytes.
15. UINT16_LE. Size in bytes of extra content (of unspecified semantics). For v1.0, fixed value of 0
16. N bytes with extra content (of unspecified semantics), where N is the value of the previous field.

This design does not provide any means of authentication or integrity check.

Each sector is encrypted/decrypted independently of other sectors. For that, the Initial Vector contained in the header is XOR'ed with the file offset (relative to plain text file) of the start of the sector being processed, as a 8-byte integer. More precisely, the first byte of the main IV is XOR'ed with the 8 least-significant bits of the sector offset, the second byte of the main IV is XOR'ed with the following 8 bits of the sector offset, etc... until the 8th byte.

This design could potentially be prone to chosen-plaintext attack, for example if the attacker managed to get (part of) an existing encrypted file to be encrypted from plaintext he might have selected.

Note: if "hostile" code can explore process content, or attach to it with a debugger, it might be relatively easy to retrieve the encryption key. A GDAL plugin could for example get the content of configuration options, or list opened datasets and see the key/key_b64 values, so disabling plugin loading might be a first step, as well as linking statically GDAL to application code. If plugin loading is enabled or GDAL dynamically linked, using VSISetCryptKey() to set the key might make it a bit more complicated to spy the key. But, as said initially, this is in no way a perfect protection.

Since
  GDAL 2.1.0

void VSIInstallCurlFileHandler | ( | void |  | ) |

Install /vsicurl/ HTTP/FTP file system handler (requires libcurl)

A special file handler is installed that allows on-the-fly random reading of files available through HTTP/FTP web protocols, without prior download of the entire file.

Recognized filenames are of the form /vsicurl/http://path/to/remote/resource or /vsicurl/ftp://path/to/remote/resource where path/to/remote/resource is the URL of a remote resource.

Partial downloads (requires the HTTP server to support random reading) are done with a 16 KB granularity by default. If the driver detects sequential reading it will progressively increase the chunk size up to 2 MB to improve download performance.

The GDAL_HTTP_PROXY, GDAL_HTTP_PROXYUSERPWD and GDAL_PROXY_AUTH configuration options can be used to define a proxy server. The syntax to use is the one of Curl CURLOPT_PROXY, CURLOPT_PROXYUSERPWD and CURLOPT_PROXYAUTH options.

Starting with GDAL 1.10, the file can be cached in RAM by setting the configuration option VSI_CACHE to TRUE. The cache size defaults to 25 MB, but can be modified by setting the configuration option VSI_CACHE_SIZE (in bytes).

Starting with GDAL 2.1, /vsicurl/ will try to query directly redirected URLs to Amazon S3 signed URLs during their validity period, so as to minimize round-trips. This behaviour can be disabled by setting the configuration option CPL_VSIL_CURL_USE_S3_REDIRECT to NO.

Starting with GDAL 2.1.3, the CURL_CA_BUNDLE or SSL_CERT_FILE configuration options can be used to set the path to the Certification Authority (CA) bundle file (if not specified, curl will use a file in a system location).

VSIStatL() will return the size in st_size member and file nature- file or directory - in st_mode member (the later only reliable with FTP resources for now).

VSIReadDir() should be able to parse the HTML directory listing returned by the most popular web servers, such as Apache or Microsoft IIS.

This special file handler can be combined with other virtual filesystems handlers, such as /vsizip. For example, /vsizip//vsicurl/path/to/remote/file.zip/path/inside/zip

Since
  GDAL 1.8.0

void VSIInstallCurlStreamingFileHandler | ( | void |  | ) |

Install /vsicurl_streaming/ HTTP/FTP file system handler (requires libcurl).

A special file handler is installed that allows on-the-fly sequential reading of files streamed through HTTP/FTP web protocols (typically dynamically generated files), without prior download of the entire file.

Although this file handler is able seek to random offsets in the file, this will not be efficient. If you need efficient random access and that the server supports range dowloading, you should use the /vsicurl/ file system handler instead.

Recognized filenames are of the form /vsicurl_streaming/http://path/to/remote/resource or /vsicurl_streaming/ftp://path/to/remote/resource where path/to/remote/resource is the URL of a remote resource.

The GDAL_HTTP_PROXY, GDAL_HTTP_PROXYUSERPWD and GDAL_PROXY_AUTH configuration options can be used to define a proxy server. The syntax to use is the one of Curl CURLOPT_PROXY, CURLOPT_PROXYUSERPWD and CURLOPT_PROXYAUTH options.

Starting with GDAL 2.1.3, the CURL_CA_BUNDLE or SSL_CERT_FILE configuration options can be used to set the path to the Certification Authority (CA) bundle file (if not specified, curl will use a file in a system location).

The file can be cached in RAM by setting the configuration option VSI_CACHE to TRUE. The cache size defaults to 25 MB, but can be modified by setting the configuration option VSI_CACHE_SIZE (in bytes).

VSIStatL() will return the size in st_size member and file nature- file or directory - in st_mode member (the later only reliable with FTP resources for now).

Since
  GDAL 1.10

void VSIInstallGSFileHandler | ( | void |  | ) |

Install /vsigs/ Google Cloud Storage file system handler (requires libcurl)

A special file handler is installed that allows on-the-fly random reading of non-public files available in Google Cloud Storage buckets, without prior download of the entire file. Read-only support for now.

Recognized filenames are of the form /vsigs/bucket/key where bucket is the name of the bucket and key the object "key", i.e. a filename potentially containing subdirectories.

Partial downloads are done with a 16 KB granularity by default. If the driver detects sequential reading it will progressively increase the chunk size up to 2 MB to improve download performance.

The GS_SECRET_ACCESS_KEY and GS_ACCESS_KEY_ID configuration options must be set to use the AWS S3 authentication compatibility method.

Alternatively, it is possible to set the GDAL_HTTP_HEADER_FILE configuration option to point to a filename of a text file with "key: value" headers. Typically, it must contain a "Authorization: Bearer XXXXXXXXX" line.

The GDAL_HTTP_PROXY, GDAL_HTTP_PROXYUSERPWD and GDAL_PROXY_AUTH configuration options can be used to define a proxy server. The syntax to use is the one of Curl CURLOPT_PROXY, CURLOPT_PROXYUSERPWD and CURLOPT_PROXYAUTH options.

The CURL_CA_BUNDLE or SSL_CERT_FILE configuration options can be used to set the path to the Certification Authority (CA) bundle file (if not specified, curl will use a file in a system location).

On reading, the file can be cached in RAM by setting the configuration option VSI_CACHE to TRUE. The cache size defaults to 25 MB, but can be modified by setting the configuration option VSI_CACHE_SIZE (in bytes).

VSIStatL() will return the size in st_size member.

Since
  GDAL 2.2

void VSIInstallGSStreamingFileHandler | ( | void |  | ) |

Install /vsigs_streaming/ Google Cloud Storage file system handler (requires libcurl)

A special file handler is installed that allows on-the-fly random reading of non-public files streamed from Google Cloud Storage buckets, without prior download of the entire file.

Recognized filenames are of the form /vsigs_streaming/bucket/key where bucket is the name of the bucket and key the object "key", i.e. a filename potentially containing subdirectories.

Partial downloads are done with a 16 KB granularity by default. If the driver detects sequential reading it will progressively increase the chunk size up to 2 MB to improve download performance.

The GS_SECRET_ACCESS_KEY and GS_ACCESS_KEY_ID configuration options must be set to use the AWS S3 authentication compatibility method.

Alternatively, it is possible to set the GDAL_HTTP_HEADER_FILE configuration option to point to a filename of a text file with "key: value" headers. Typically, it must contain a "Authorization: Bearer XXXXXXXXX" line.

The GDAL_HTTP_PROXY, GDAL_HTTP_PROXYUSERPWD and GDAL_PROXY_AUTH configuration options can be used to define a proxy server. The syntax to use is the one of Curl CURLOPT_PROXY, CURLOPT_PROXYUSERPWD and CURLOPT_PROXYAUTH options.

The CURL_CA_BUNDLE or SSL_CERT_FILE configuration options can be used to set the path to the Certification Authority (CA) bundle file (if not specified, curl will use a file in a system location).

On reading, the file can be cached in RAM by setting the configuration option VSI_CACHE to TRUE. The cache size defaults to 25 MB, but can be modified by setting the configuration option VSI_CACHE_SIZE (in bytes).

VSIStatL() will return the size in st_size member.

Since
  GDAL 2.2

void VSIInstallGZipFileHandler | ( | void |  | ) |

Install GZip file system handler.

A special file handler is installed that allows reading on-the-fly and writing in GZip (.gz) files.

All portions of the file system underneath the base path "/vsigzip/" will be handled by this driver.

Additional documentation is to be found at: http://trac.osgeo.org/gdal/wiki/UserDocs/ReadInZip

Since
  GDAL 1.6.0

void VSIInstallMemFileHandler | ( | void |  | ) |

Install "memory" file system handler.

A special file handler is installed that allows block of memory to be treated as files. All portions of the file system underneath the base path "/vsimem/" will be handled by this driver.

Normal VSI*L functions can be used freely to create and destroy memory arrays treating them as if they were real file system objects. Some additional methods exist to efficient create memory file system objects without duplicating original copies of the data or to "steal" the block of memory associated with a memory file.

At this time the memory handler does not properly handle directory semantics for the memory portion of the filesystem. The VSIReadDir() function is not supported though this will be corrected in the future.

Calling this function repeatedly should do no harm, though it is not necessary. It is already called the first time a virtualizable file access function (i.e. VSIFOpenL(), VSIMkDir(), etc) is called.

This code example demonstrates using GDAL to translate from one memory buffer to another.

1 GByte *ConvertBufferFormat( GByte *pabyInData, vsi_l_offset nInDataLength,
2 vsi_l_offset *pnOutDataLength )
3 {
4 // create memory file system object from buffer.
5 VSIFCloseL( VSIFileFromMemBuffer( "/vsimem/work.dat", pabyInData,
6 nInDataLength, FALSE ) );
7
8 // Open memory buffer for read.
9 GDALDatasetH hDS = GDALOpen( "/vsimem/work.dat", GA_ReadOnly );
10
11 // Get output format driver.
12 GDALDriverH hDriver = GDALGetDriverByName( "GTiff" );
13 GDALDatasetH hOutDS;
14
15 hOutDS = GDALCreateCopy( hDriver, "/vsimem/out.tif", hDS, TRUE, NULL,
16 NULL, NULL );
17
18 // close source file, and "unlink" it.
19 GDALClose( hDS );
20 VSIUnlink( "/vsimem/work.dat" );
21
22 // seize the buffer associated with the output file.
23
24 return VSIGetMemFileBuffer( "/vsimem/out.tif", pnOutDataLength, TRUE );
25 }

void VSIInstallS3FileHandler | ( | void |  | ) |

Install /vsis3/ Amazon S3 file system handler (requires libcurl)

A special file handler is installed that allows on-the-fly random reading of non-public files available in AWS S3 buckets, without prior download of the entire file. It also allows sequential writing of files (no seeks or read operations are then allowed).

Recognized filenames are of the form /vsis3/bucket/key where bucket is the name of the S3 bucket and key the S3 object "key", i.e. a filename potentially containing subdirectories.

Partial downloads are done with a 16 KB granularity by default. If the driver detects sequential reading it will progressively increase the chunk size up to 2 MB to improve download performance.

The AWS_SECRET_ACCESS_KEY and AWS_ACCESS_KEY_ID configuration options must be set. The AWS_SESSION_TOKEN configuration option must be set when temporary credentials are used. The AWS_REGION configuration option may be set to one of the supported S3 regions and defaults to 'us-east-1' The AWS_S3_ENDPOINT configuration option defaults to s3.amazonaws.com. Starting with GDAL 2.2, the AWS_REQUEST_PAYER configuration option may be set to "requester" to facilitate use with Requester Pays buckets.

The GDAL_HTTP_PROXY, GDAL_HTTP_PROXYUSERPWD and GDAL_PROXY_AUTH configuration options can be used to define a proxy server. The syntax to use is the one of Curl CURLOPT_PROXY, CURLOPT_PROXYUSERPWD and CURLOPT_PROXYAUTH options.

Starting with GDAL 2.1.3, the CURL_CA_BUNDLE or SSL_CERT_FILE configuration options can be used to set the path to the Certification Authority (CA) bundle file (if not specified, curl will use a file in a system location).

On reading, the file can be cached in RAM by setting the configuration option VSI_CACHE to TRUE. The cache size defaults to 25 MB, but can be modified by setting the configuration option VSI_CACHE_SIZE (in bytes).

On writing, the file is uploaded using the S3 multipart upload API. The size of chunks is set to 50 MB by default, allowing creating files up to 500 GB (10000 parts of 50 MB each). If larger files are needed, then increase the value of the VSIS3_CHUNK_SIZE config option to a larger value (expressed in MB). In case the process is killed and the file not properly closed, the multipart upload will remain open, causing Amazon to charge you for the parts storage. You'll have to abort yourself with other means such "ghost" uploads (e.g. with the s3cmd utility) For files smaller than the chunk size, a simple PUT request is used instead of the multipart upload API.

VSIStatL() will return the size in st_size member.

Since
  GDAL 2.1

void VSIInstallS3StreamingFileHandler | ( | void |  | ) |

Install /vsis3_streaming/ Amazon S3 file system handler (requires libcurl).

A special file handler is installed that allows on-the-fly sequential reading of non-public files streamed from AWS S3 buckets without prior download of the entire file.

Recognized filenames are of the form /vsis3_streaming/bucket/key where bucket is the name of the S3 bucket and resource the S3 object "key", i.e. a filename potentially containing subdirectories.

The AWS_SECRET_ACCESS_KEY and AWS_ACCESS_KEY_ID configuration options must be set. The AWS_SESSION_TOKEN configuration option must be set when temporary credentials are used.

The AWS_REGION configuration option may be set to one of the supported S3 regions and defaults to 'us-east-1'. The AWS_S3_ENDPOINT configuration option defaults to s3.amazonaws.com. Starting with GDAL 2.2, the AWS_REQUEST_PAYER configuration option may be set to "requester" to facilitate use with Requester Pays buckets.

The GDAL_HTTP_PROXY, GDAL_HTTP_PROXYUSERPWD and GDAL_PROXY_AUTH configuration options can be used to define a proxy server. The syntax to use is the one of Curl CURLOPT_PROXY, CURLOPT_PROXYUSERPWD and CURLOPT_PROXYAUTH options.

Starting with GDAL 2.1.3, the CURL_CA_BUNDLE or SSL_CERT_FILE configuration options can be used to set the path to the Certification Authority (CA) bundle file (if not specified, curl will use a file in a system location).

The file can be cached in RAM by setting the configuration option VSI_CACHE to TRUE. The cache size defaults to 25 MB, but can be modified by setting the configuration option VSI_CACHE_SIZE (in bytes).

VSIStatL() will return the size in st_size member.

Since
  GDAL 2.1

void VSIInstallSparseFileHandler | ( | void |  | ) |

Install /vsisparse/ virtual file handler.

The sparse virtual file handler allows a virtual file to be composed from chunks of data in other files, potentially with large spaces in the virtual file set to a constant value. This can make it possible to test some sorts of operations on what seems to be a large file with image data set to a constant value. It is also helpful when wanting to add test files to the test suite that are too large, but for which most of the data can be ignored. It could, in theory, also be used to treat several files on different file systems as one large virtual file.

The file referenced by /vsisparse/ should be an XML control file formatted something like:

    <VSISparseFile>
      <Length>87629264</Length>
      <SubfileRegion>  Stuff at start of file.
        <Filename relative="1">251_head.dat</Filename>
        <DestinationOffset>0</DestinationOffset>
        <SourceOffset>0</SourceOffset>
        <RegionLength>2768</RegionLength>
      </SubfileRegion>

      <SubfileRegion>  RasterDMS node.
        <Filename relative="1">251_rasterdms.dat</Filename>
        <DestinationOffset>87313104</DestinationOffset>
        <SourceOffset>0</SourceOffset>
        <RegionLength>160</RegionLength>
      </SubfileRegion>

      <SubfileRegion>  Stuff at end of file.
        <Filename relative="1">251_tail.dat</Filename>
        <DestinationOffset>87611924</DestinationOffset>
        <SourceOffset>0</SourceOffset>
        <RegionLength>17340</RegionLength>
      </SubfileRegion>

      <ConstantRegion>  Default for the rest of the file.
        <DestinationOffset>0</DestinationOffset>
        <RegionLength>87629264</RegionLength>
        <Value>0</Value>
      </ConstantRegion>
    </VSISparseFile>

Hopefully the values and semantics are fairly obvious.

This driver is installed by default.

void VSIInstallStdinHandler | ( | void |  | ) |

Install /vsistdin/ file system handler.

A special file handler is installed that allows reading from the standard input steam.

The file operations available are of course limited to Read() and forward Seek() (full seek in the first MB of a file).

Since
  GDAL 1.8.0

void VSIInstallStdoutHandler | ( | void |  | ) |

Install /vsistdout/ file system handler.

A special file handler is installed that allows writing to the standard output stream.

The file operations available are of course limited to Write().

Since
  GDAL 1.8.0

void VSIInstallSubFileHandler | ( | void |  | ) |

Install /vsisubfile/ virtual file handler.

This virtual file system handler allows access to subregions of files, treating them as a file on their own to the virtual file system functions (VSIFOpenL(), etc).

A special form of the filename is used to indicate a subportion of another file:

/vsisubfile/<offset>[_<size>],<filename>

The size parameter is optional. Without it the remainder of the file from the start offset as treated as part of the subfile. Otherwise only <size> bytes from <offset> are treated as part of the subfile. The <filename> portion may be a relative or absolute path using normal rules. The <offset> and <size> values are in bytes.

eg. /vsisubfile/1000_3000,/data/abc.ntf /vsisubfile/5000,../xyz/raw.dat

Unlike the /vsimem/ or conventional file system handlers, there is no meaningful support for filesystem operations for creating new files, traversing directories, and deleting files within the /vsisubfile/ area. Only the VSIStatL(), VSIFOpenL() and operations based on the file handle returned by VSIFOpenL() operate properly.

void VSIInstallTarFileHandler | ( | void |  | ) |

Install /vsitar/ file system handler.

A special file handler is installed that allows reading on-the-fly in TAR (regular .tar, or compressed .tar.gz/.tgz) archives.

All portions of the file system underneath the base path "/vsitar/" will be handled by this driver.

The syntax to open a file inside a tar file is /vsitar/path/to/the/file.tar/path/inside/the/tar/file were path/to/the/file.tar is relative or absolute and path/inside/the/tar/file is the relative path to the file inside the archive.

Starting with GDAL 2.2, an alternate syntax is available so as to enable chaining and not being dependent on .tar extension : /vsitar/{/path/to/the/archive}/path/inside/the/tar/file. Note that /path/to/the/archive may also itself this alternate syntax.

If the path is absolute, it should begin with a / on a Unix-like OS (or C:\ on Windows), so the line looks like /vsitar//home/gdal/... For example gdalinfo /vsitar/myarchive.tar/subdir1/file1.tif

Syntactic sugar : if the tar archive contains only one file located at its root, just mentionning "/vsitar/path/to/the/file.tar" will work

VSIStatL() will return the uncompressed size in st_size member and file nature- file or directory - in st_mode member.

Directory listing is available through VSIReadDir().

Since
  GDAL 1.8.0

void VSIInstallZipFileHandler | ( | void |  | ) |

Install ZIP file system handler.

A special file handler is installed that allows reading on-the-fly in ZIP (.zip) archives.

All portions of the file system underneath the base path "/vsizip/" will be handled by this driver.

The syntax to open a file inside a zip file is /vsizip/path/to/the/file.zip/path/inside/the/zip/file were path/to/the/file.zip is relative or absolute and path/inside/the/zip/file is the relative path to the file inside the archive.

Starting with GDAL 2.2, an alternate syntax is available so as to enable chaining and not being dependent on .zip extension : /vsitar/{/path/to/the/archive}/path/inside/the/zip/file. Note that /path/to/the/archive may also itself this alternate syntax.

If the path is absolute, it should begin with a / on a Unix-like OS (or C:\ on Windows), so the line looks like /vsizip//home/gdal/... For example gdalinfo /vsizip/myarchive.zip/subdir1/file1.tif

Syntactic sugar : if the .zip file contains only one file located at its root, just mentioning "/vsizip/path/to/the/file.zip" will work

VSIStatL() will return the uncompressed size in st_size member and file nature- file or directory - in st_mode member.

Directory listing is available through VSIReadDir().

Since GDAL 1.8.0, write capabilities are available. They allow creating a new zip file and adding new files to an already existing (or just created) zip file. Read and write operations cannot be interleaved : the new zip must be closed before being re-opened for read.

Additional documentation is to be found at http://trac.osgeo.org/gdal/wiki/UserDocs/ReadInZip

Since
  GDAL 1.6.0

int VSIIsCaseSensitiveFS | ( | const char * | pszFilename | ) |

Returns if the filenames of the filesystem are case sensitive.

This method retrieves to which filesystem belongs the passed filename and return TRUE if the filenames of that filesystem are case sensitive.

Currently, this will return FALSE only for Windows real filenames. Other VSI virtual filesystems are case sensitive.

This methods avoid ugly #ifndef WIN32 / #endif code, that is wrong when dealing with virtual filenames.

Parameters

  pszFilename | the path of the filesystem object to be tested. UTF-8 encoded.

Returns
  TRUE if the filenames of the filesystem are case sensitive.

Since
  GDAL 1.8.0

void* VSIMalloc | ( | size_t | nSize | ) |

Analog of malloc().

Use VSIFree() to free

void* VSIMalloc2 | ( | size_t | nSize1,
|  | size_t | nSize2
| ) |  |

VSIMalloc2 allocates (nSize1 * nSize2) bytes.

In case of overflow of the multiplication, or if memory allocation fails, a NULL pointer is returned and a CE_Failure error is raised with CPLError(). If nSize1 == 0 || nSize2 == 0, a NULL pointer will also be returned. CPLFree() or VSIFree() can be used to free memory allocated by this function.

void* VSIMalloc3 | ( | size_t | nSize1,
|  | size_t | nSize2,
|  | size_t | nSize3
| ) |  |

VSIMalloc3 allocates (nSize1 * nSize2 * nSize3) bytes.

In case of overflow of the multiplication, or if memory allocation fails, a NULL pointer is returned and a CE_Failure error is raised with CPLError(). If nSize1 == 0 || nSize2 == 0 || nSize3 == 0, a NULL pointer will also be returned. CPLFree() or VSIFree() can be used to free memory allocated by this function.

void* VSIMallocAligned | ( | size_t | nAlignment,
|  | size_t | nSize
| ) |  |

Allocates a buffer with an alignment constraint.

The return value must be freed with VSIFreeAligned().

Parameters

  nAlignment | Must be a power of 2, multiple of sizeof(void*), and lesser than 256.
  nSize | Size of the buffer to allocate.

Returns
  a buffer aligned on nAlignment and of size nSize, or NULL

Since
  GDAL 2.2

void* VSIMallocAlignedAuto | ( | size_t | nSize | ) |

Allocates a buffer with an alignment constraint such that it can be used by the most demanding vector instruction set on that platform.

The return value must be freed with VSIFreeAligned().

Parameters

  nSize | Size of the buffer to allocate.

Returns
  an aligned buffer of size nSize, or NULL

Since
  GDAL 2.2

int VSIMkdir | ( | const char * | pszPathname,
|  | long | mode
| ) |  |

Create a directory.

Create a new directory with the indicated mode. The mode is ignored on some platforms. A reasonable default mode value would be 0666. This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX mkdir() function.

Parameters

  pszPathname | the path to the directory to create. UTF-8 encoded.
  mode | the permissions mode.

Returns
  0 on success or -1 on an error.

char** VSIReadDir | ( | const char * | pszPath | ) |

Read names in a directory.

This function abstracts access to directory contains. It returns a list of strings containing the names of files, and directories in this directory. The resulting string list becomes the responsibility of the application and should be freed with CSLDestroy() when no longer needed.

Note that no error is issued via CPLError() if the directory path is invalid, though NULL is returned.

This function used to be known as CPLReadDir(), but the old name is now deprecated.

Parameters

  pszPath | the relative, or absolute path of a directory to read. UTF-8 encoded.

Returns
  The list of entries in the directory, or NULL if the directory doesn't exist. Filenames are returned in UTF-8 encoding.

char** VSIReadDirEx | ( | const char * | pszPath,
|  | int | nMaxFiles
| ) |  |

Read names in a directory.

This function abstracts access to directory contains. It returns a list of strings containing the names of files, and directories in this directory. The resulting string list becomes the responsibility of the application and should be freed with CSLDestroy() when no longer needed.

Note that no error is issued via CPLError() if the directory path is invalid, though NULL is returned.

If nMaxFiles is set to a positive number, directory listing will stop after that limit has been reached. Note that to indicate truncate, at least one element more than the nMaxFiles limit will be returned. If CSLCount() on the result is lesser or equal to nMaxFiles, then no truncation occurred.

Parameters

  pszPath | the relative, or absolute path of a directory to read. UTF-8 encoded.
  nMaxFiles | maximum number of files after which to stop, or 0 for no limit.

Returns
  The list of entries in the directory, or NULL if the directory doesn't exist. Filenames are returned in UTF-8 encoding.

Since
  GDAL 2.1

char** VSIReadDirRecursive | ( | const char * | pszPathIn | ) |

Read names in a directory recursively.

This function abstracts access to directory contents and subdirectories. It returns a list of strings containing the names of files and directories in this directory and all subdirectories. The resulting string list becomes the responsibility of the application and should be freed with CSLDestroy() when no longer needed.

Note that no error is issued via CPLError() if the directory path is invalid, though NULL is returned.

Parameters

  pszPathIn | the relative, or absolute path of a directory to read. UTF-8 encoded.

Returns
  The list of entries in the directory and subdirectories or NULL if the directory doesn't exist. Filenames are returned in UTF-8 encoding.

Since
  GDAL 1.10.0

void* VSIRealloc | ( | void * | pData,
|  | size_t | nNewSize
| ) |  |

Analog of realloc().

Use VSIFree() to free

int VSIRename | ( | const char * | oldpath,
|  | const char * | newpath
| ) |  |

Rename a file.

Renames a file object in the file system. It should be possible to rename a file onto a new filesystem, but it is safest if this function is only used to rename files that remain in the same directory.

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

Analog of the POSIX rename() function.

Parameters

  oldpath | the name of the file to be renamed. UTF-8 encoded.
  newpath | the name the file should be given. UTF-8 encoded.

Returns
  0 on success or -1 on an error.

void VSIRewindL | ( | VSILFILE * | fp | ) |

Rewind the file pointer to the beginning of the file.

This is equivalent to VSIFSeekL( fp, 0, SEEK_SET )

Analog of the POSIX rewind() call.

Parameters

  fp | file handle opened with VSIFOpenL().

int VSIRmdir | ( | const char * | pszDirname | ) |

Delete a directory.

Deletes a directory object from the file system. On some systems the directory must be empty before it can be deleted.

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

Analog of the POSIX rmdir() function.

Parameters

  pszDirname | the path of the directory to be deleted. UTF-8 encoded.

Returns
  0 on success or -1 on an error.

void VSISetCryptKey | ( | const GByte * | pabyKey,
|  | int | nKeySize
| ) |  |

Installs the encryption/decryption key.

By passing a NULL key, the previously installed key will be cleared. Note, however, that it is not guaranteed that there won't be trace of it in other places in memory or in on-disk temporary file.

Parameters

  pabyKey | key. Might be NULL to clear previously set key.
  nKeySize | length of the key in bytes. Might be 0 to clear previously set key.

See also
  VSIInstallCryptFileHandler() for documentation on /vsicrypt/

int VSIStatExL | ( | const char * | pszFilename,
|  | VSIStatBufL * | psStatBuf,
|  | int | nFlags
| ) |  |

Get filesystem object info.

Fetches status information about a filesystem object (file, directory, etc). The returned information is placed in the VSIStatBufL structure. For portability, only use the st_size (size in bytes) and st_mode (file type). This method is similar to VSIStat(), but will work on large files on systems where this requires special calls.

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

Analog of the POSIX stat() function, with an extra parameter to specify which information is needed, which offers a potential for speed optimizations on specialized and potentially slow virtual filesystem objects (/vsigzip/, /vsicurl/)

Parameters

  pszFilename | the path of the filesystem object to be queried. UTF-8 encoded.
  psStatBuf | the structure to load with information.
  nFlags | 0 to get all information, or VSI_STAT_EXISTS_FLAG, VSI_STAT_NATURE_FLAG or VSI_STAT_SIZE_FLAG, or a combination of those to get partial info.

Returns
  0 on success or -1 on an error.

Since
  GDAL 1.8.0

int VSIStatL | ( | const char * | pszFilename,
|  | VSIStatBufL * | psStatBuf
| ) |  |

Get filesystem object info.

Fetches status information about a filesystem object (file, directory, etc). The returned information is placed in the VSIStatBufL structure. For portability, only use the st_size (size in bytes) and st_mode (file type). This method is similar to VSIStat(), but will work on large files on systems where this requires special calls.

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

Analog of the POSIX stat() function.

Parameters

  pszFilename | the path of the filesystem object to be queried. UTF-8 encoded.
  psStatBuf | the structure to load with information.

Returns
  0 on success or -1 on an error.

void VSIStdoutSetRedirection | ( | VSIWriteFunction | pFct,
|  | FILE * | stream
| ) |  |

Set an alternative write function and output file handle instead of fwrite() / stdout.

Parameters

  pFct | Function with same signature as fwrite()
  stream | File handle on which to output. Passed to pFct.

Since
  GDAL 2.0

char* VSIStrdup | ( | const char * | pszString | ) |

Analog of strdup().

Use VSIFree() to free

char* VSIStrerror | ( | int | nErrno | ) |

Return the error string corresponding to the error number.

Do not free it

int VSISupportsSparseFiles | ( | const char * | pszPath | ) |

Returns if the filesystem supports sparse files.

Only supported on Linux (and no other Unix derivatives) and Windows. On Linux, the answer depends on a few hardcoded signatures for common filesystems. Other filesystems will be considered as not supporting sparse files.

Parameters

  pszPath | the path of the filesystem object to be tested. UTF-8 encoded.

Returns
  TRUE if the file system is known to support sparse files. FALSE may be returned both in cases where it is known to not support them, or when it is unknown.

Since
  GDAL 2.2

int VSIUnlink | ( | const char * | pszFilename | ) |

Delete a file.

Deletes a file object from the file system.

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

Analog of the POSIX unlink() function.

Parameters

  pszFilename | the path of the file to be deleted. UTF-8 encoded.

Returns
  0 on success or -1 on an error.

Generated for GDAL by 1.8.8.