Standard C Covers. More...

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

Classes
struct	VSIDIREntry
	Directory entry. More...

struct	VSIFilesystemPluginCallbacksStruct
	struct containing callbacks to used by the handler. More...

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	VSIStatBufL VSIStatBuf
	Type for VSIStatL()

#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_STAT_CACHE_ONLY 0x10
	Flag provided to VSIStatExL() to only use already cached results. More...

#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 VSIDIR	VSIDIR
	Opaque type for a directory iterator.

typedef size_t(*	VSIWriteFunction) (const void ptr, size_t size, size_t nmemb, FILE stream)
	Callback used by VSIStdoutSetRedirection()

typedef int(*	VSIFilesystemPluginStatCallback) (void pUserData, const char pszFilename, VSIStatBufL *pStatBuf, int nFlags)
	Return information about a handle. More...

typedef int(*	VSIFilesystemPluginUnlinkCallback) (void pUserData, const char pszFilename)
	Remove handle by name. More...

typedef int(*	VSIFilesystemPluginRenameCallback) (void pUserData, const char oldpath, const char *newpath)
	Rename handle. More...

typedef int(*	VSIFilesystemPluginMkdirCallback) (void pUserData, const char pszDirname, long nMode)
	Create Directory. More...

typedef int(*	VSIFilesystemPluginRmdirCallback) (void pUserData, const char pszDirname)
	Delete Directory. More...

typedef char *(	VSIFilesystemPluginReadDirCallback) (void pUserData, const char pszDirname, int nMaxFiles)
	List directory content. More...

typedef char *(	VSIFilesystemPluginSiblingFilesCallback) (void pUserData, const char pszDirname)
	List related files. More...

typedef void (	VSIFilesystemPluginOpenCallback) (void pUserData, const char pszFilename, const char *pszAccess)
	Open a handle. More...

typedef vsi_l_offset(*	VSIFilesystemPluginTellCallback) (void *pFile)
	Return current position in handle. More...

typedef int(*	VSIFilesystemPluginSeekCallback) (void *pFile, vsi_l_offset nOffset, int nWhence)
	Seek to position in handle. More...

typedef size_t(*	VSIFilesystemPluginReadCallback) (void pFile, void pBuffer, size_t nSize, size_t nCount)
	Read data from current position, returns the number of blocks correctly read. More...

typedef int(*	VSIFilesystemPluginReadMultiRangeCallback) (void pFile, int nRanges, void ppData, const vsi_l_offset panOffsets, const size_t *panSizes)
	Read from multiple offsets. More...

typedef VSIRangeStatus(*	VSIFilesystemPluginGetRangeStatusCallback) (void *pFile, vsi_l_offset nOffset, vsi_l_offset nLength)
	Get empty ranges. More...

typedef int(*	VSIFilesystemPluginEofCallback) (void *pFile)
	Has end of file been reached. More...

typedef size_t(*	VSIFilesystemPluginWriteCallback) (void pFile, const void pBuffer, size_t nSize, size_t nCount)
	Write bytes at current offset. More...

typedef int(*	VSIFilesystemPluginFlushCallback) (void *pFile)
	Sync written bytes. More...

typedef int(*	VSIFilesystemPluginTruncateCallback) (void *pFile, vsi_l_offset nNewSize)
	Truncate handle. More...

typedef int(*	VSIFilesystemPluginCloseCallback) (void *pFile)
	Close file handle. More...

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 )
	Open file. More...

VSILFILE *	VSIFOpenExL (const char , const char , int)
	Open file. More...

VSILFILE *	VSIFOpenEx2L (const char , const char , int, CSLConstList)
	Open file. More...

int	VSIFCloseL (VSILFILE *)
	Close file. More...

int	VSIFSeekL (VSILFILE *, vsi_l_offset, int)
	Seek to requested offset. More...

vsi_l_offset	VSIFTellL (VSILFILE *)
	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 )
	Read bytes from file. More...

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

size_t	VSIFWriteL (const void , size_t, size_t, VSILFILE )
	Write bytes to file. More...

int	VSIFEofL (VSILFILE *)
	Test for end of file. More...

int	VSIFTruncateL (VSILFILE *, vsi_l_offset)
	Truncate/expand the file to the specified size. More...

int	VSIFFlushL (VSILFILE *)
	Flush pending writes to disk. More...

int	VSIFPrintfL (VSILFILE , const char ,...)
	Formatted write to file. More...

int	VSIFPutcL (int, VSILFILE *)
	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)
	Ingest a file into memory. More...

int	VSIOverwriteFile (VSILFILE fpTarget, const char pszSourceFilename)
	Overwrite an existing file with content from another one. More...

int	VSIStatL (const char , VSIStatBufL )
	Get filesystem object info. More...

int	VSIStatExL (const char pszFilename, VSIStatBufL psStatBuf, int nFlags)
	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...

int	VSIHasOptimizedReadMultiRange (const char *pszPath)
	Returns if the filesystem supports efficient multi-range reading. More...

const char *	VSIGetActualURL (const char *pszFilename)
	Returns the actual URL of a supplied filename. More...

char *	VSIGetSignedURL (const char *pszFilename, CSLConstList papszOptions)
	Returns a signed URL of a supplied filename. More...

const char *	VSIGetFileSystemOptions (const char *pszFilename)
	Return the list of options associated with a virtual file system handler as a serialized XML string. More...

char **	VSIGetFileSystemsPrefixes (void)
	Return the list of prefixes for virtual file system handlers currently registered. More...

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

char **	VSIGetFileMetadata (const char pszFilename, const char pszDomain, CSLConstList papszOptions)
	Get metadata on files. More...

int	VSISetFileMetadata (const char pszFilename, CSLConstList papszMetadata, const char pszDomain, CSLConstList papszOptions)
	Set metadata on files. More...

void	VSISetCredential (const char pszPathPrefix, const char pszKey, const char *pszValue)
	Set a credential (or more generally an option related to a virtual file system) for a given path prefix. More...

void	VSIClearCredentials (const char *pszPathPrefix)
	Clear credentials set with VSISetCredential() More...

const char *	VSIGetCredential (const char pszPath, const char pszKey, const char *pszDefault)
	Get a credential option for a given path. More...

void *	VSICalloc (size_t, size_t)
	Analog of calloc(). More...

void *	VSIMalloc (size_t)
	Analog of malloc(). More...

void	VSIFree (void *)
	Analog of free() for data allocated with VSIMalloc(), VSICalloc(), VSIRealloc()

void *	VSIRealloc (void *, size_t)
	Analog of realloc(). More...

char *	VSIStrdup (const char *)
	Analog of strdup(). More...

void *	VSIMallocAligned (size_t nAlignment, size_t nSize)
	Allocates a buffer with an alignment constraint. More...

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

void	VSIFreeAligned (void *ptr)
	Free a buffer allocated with VSIMallocAligned(). More...

void *	VSIMallocAlignedAutoVerbose (size_t nSize, const char *pszFile, int nLine)
	See VSIMallocAlignedAuto()

void *	VSIMalloc2 (size_t nSize1, size_t nSize2)
	VSIMalloc2 allocates (nSize1 * nSize2) bytes. More...

void *	VSIMalloc3 (size_t nSize1, size_t nSize2, size_t nSize3)
	VSIMalloc3 allocates (nSize1 * nSize2 * nSize3) bytes. More...

void *	VSIMallocVerbose (size_t nSize, const char *pszFile, int nLine)
	VSIMallocVerbose.

void *	VSIMalloc2Verbose (size_t nSize1, size_t nSize2, const char *pszFile, int nLine)
	VSIMalloc2Verbose.

void *	VSIMalloc3Verbose (size_t nSize1, size_t nSize2, size_t nSize3, const char *pszFile, int nLine)
	VSIMalloc3Verbose.

void *	VSICallocVerbose (size_t nCount, size_t nSize, const char *pszFile, int nLine)
	VSICallocVerbose.

void *	VSIReallocVerbose (void pOldPtr, size_t nNewSize, const char pszFile, int nLine)
	VSIReallocVerbose.

char *	VSIStrdupVerbose (const char pszStr, const char pszFile, int nLine)
	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...

char **	VSISiblingFiles (const char *pszPath)
	Return related filenames. More...

VSIDIR *	VSIOpenDir (const char pszPath, int nRecurseDepth, const char const *papszOptions)
	Open a directory to read its entries. More...

const VSIDIREntry *	VSIGetNextDirEntry (VSIDIR *dir)
	Return the next entry of the directory. More...

void	VSICloseDir (VSIDIR *dir)
	Close a directory. More...

int	VSIMkdir (const char *pszPathname, long mode)
	Create a directory. More...

int	VSIMkdirRecursive (const char *pszPathname, long mode)
	Create a directory and all its ancestors. More...

int	VSIRmdir (const char *pszDirname)
	Delete a directory. More...

int	VSIRmdirRecursive (const char *pszDirname)
	Delete a directory recursively. More...

int	VSIUnlink (const char *pszFilename)
	Delete a file. More...

int *	VSIUnlinkBatch (CSLConstList papszFiles)
	Delete several files, possibly in a batch. More...

int	VSIRename (const char oldpath, const char newpath)
	Rename a file. More...

int	VSISync (const char pszSource, const char pszTarget, const char const papszOptions, GDALProgressFunc pProgressFunc, void pProgressData, char **ppapszOutputs)
	Synchronize a source file/directory with a target file/directory. More...

int	VSIAbortPendingUploads (const char *pszFilename)
	Abort ongoing multi-part uploads. 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	VSINetworkStatsReset (void)
	Clear network related statistics. More...

char *	VSINetworkStatsGetAsSerializedJSON (char **papszOptions)
	Return network related statistics, as a JSON serialized object. 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	VSICurlClearCache (void)
	Clean local cache associated with /vsicurl/ (and related file systems) More...

void	VSICurlPartialClearCache (const char *pszFilenamePrefix)
	Clean local cache associated with /vsicurl/ (and related file systems) for a given filename (and its subfiles and subdirectories if it is a directory) 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	VSIInstallAzureFileHandler (void)
	Install /vsiaz/ Microsoft Azure Blob file system handler (requires libcurl) More...

void	VSIInstallAzureStreamingFileHandler (void)
	Install /vsiaz_streaming/ Microsoft Azure Blob file system handler (requires libcurl) More...

void	VSIInstallADLSFileHandler (void)
	Install /vsiaz/ Microsoft Azure Data Lake Storage Gen2 file system handler (requires libcurl) More...

void	VSIInstallOSSFileHandler (void)
	Install /vsioss/ Alibaba Cloud Object Storage Service (OSS) file system handler (requires libcurl) More...

void	VSIInstallOSSStreamingFileHandler (void)
	Install /vsiaz_streaming/ Alibaba Cloud Object Storage Service (OSS) (requires libcurl) More...

void	VSIInstallSwiftFileHandler (void)
	Install /vsiswift/ OpenStack Swif Object Storage (Swift) file system handler (requires libcurl) More...

void	VSIInstallSwiftStreamingFileHandler (void)
	Install /vsiswift_streaming/ OpenStack Swif Object Storage (Swift) 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	VSIInstallHdfsHandler (void)
	Install /vsihdfs/ file system handler (requires JVM and HDFS support) More...

void	VSIInstallWebHdfsHandler (void)
	Install /vsiwebhdfs/ WebHDFS (Hadoop File System) REST API file system handler (requires libcurl) 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)
	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...

VSIFilesystemPluginCallbacksStruct *	VSIAllocFilesystemPluginCallbacksStruct (void)
	return a VSIFilesystemPluginCallbacksStruct to be populated at runtime with handler callbacks More...

void	VSIFreeFilesystemPluginCallbacksStruct (VSIFilesystemPluginCallbacksStruct *poCb)
	free resources allocated by VSIAllocFilesystemPluginCallbacksStruct More...

int	VSIInstallPluginHandler (const char pszPrefix, const VSIFilesystemPluginCallbacksStruct poCb)
	register a handler on the given prefix. 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.

Macro Definition Documentation

◆ VSI_STAT_CACHE_ONLY

#define VSI_STAT_CACHE_ONLY 0x10

Flag provided to VSIStatExL() to only use already cached results.

Since: GDAL 3.4

Typedef Documentation

◆ VSIFilesystemPluginCloseCallback

typedef int(* VSIFilesystemPluginCloseCallback) (void *pFile)

Close file handle.

Optional

Since: GDAL 3.0

◆ VSIFilesystemPluginEofCallback

typedef int(* VSIFilesystemPluginEofCallback) (void *pFile)

Has end of file been reached.

Mandatory? for read handles.

Since: GDAL 3.0

◆ VSIFilesystemPluginFlushCallback

typedef int(* VSIFilesystemPluginFlushCallback) (void *pFile)

Sync written bytes.

Optional

Since: GDAL 3.0

◆ VSIFilesystemPluginGetRangeStatusCallback

typedef VSIRangeStatus(* VSIFilesystemPluginGetRangeStatusCallback) (void *pFile, vsi_l_offset nOffset, vsi_l_offset nLength)

Get empty ranges.

Optional

Since: GDAL 3.0

◆ VSIFilesystemPluginMkdirCallback

typedef int(* VSIFilesystemPluginMkdirCallback) (void *pUserData, const char *pszDirname, long nMode)

Create Directory.

Optional

Since: GDAL 3.0

◆ VSIFilesystemPluginOpenCallback

typedef void*(* VSIFilesystemPluginOpenCallback) (void *pUserData, const char *pszFilename, const char *pszAccess)

Open a handle.

Mandatory. Returns an opaque pointer that will be used in subsequent file I/O calls. Should return null and/or set errno if the handle does not exist or the access mode is incorrect.

Since: GDAL 3.0

◆ VSIFilesystemPluginReadCallback

typedef size_t(* VSIFilesystemPluginReadCallback) (void *pFile, void *pBuffer, size_t nSize, size_t nCount)

Read data from current position, returns the number of blocks correctly read.

Mandatory except for write only handles

Since: GDAL 3.0

◆ VSIFilesystemPluginReadDirCallback

typedef char**(* VSIFilesystemPluginReadDirCallback) (void *pUserData, const char *pszDirname, int nMaxFiles)

List directory content.

Optional

Since: GDAL 3.0

◆ VSIFilesystemPluginReadMultiRangeCallback

typedef int(* VSIFilesystemPluginReadMultiRangeCallback) (void *pFile, int nRanges, void **ppData, const vsi_l_offset *panOffsets, const size_t *panSizes)

Read from multiple offsets.

Optional, will be replaced by multiple calls to Read() if not provided

Since: GDAL 3.0

◆ VSIFilesystemPluginRenameCallback

typedef int(* VSIFilesystemPluginRenameCallback) (void *pUserData, const char *oldpath, const char *newpath)

Rename handle.

Optional

Since: GDAL 3.0

◆ VSIFilesystemPluginRmdirCallback

typedef int(* VSIFilesystemPluginRmdirCallback) (void *pUserData, const char *pszDirname)

Delete Directory.

Optional

Since: GDAL 3.0

◆ VSIFilesystemPluginSeekCallback

typedef int(* VSIFilesystemPluginSeekCallback) (void *pFile, vsi_l_offset nOffset, int nWhence)

Seek to position in handle.

Mandatory except for write only handles

Since: GDAL 3.0

◆ VSIFilesystemPluginSiblingFilesCallback

typedef char**(* VSIFilesystemPluginSiblingFilesCallback) (void *pUserData, const char *pszDirname)

List related files.

Must return NULL if unknown, or a list of relative filenames that can be opened along the main file. If no other file than pszFilename needs to be opened, return static_cast<char**> (CPLCalloc(1,sizeof(char*)));

Optional

Since: GDAL 3.2

◆ VSIFilesystemPluginStatCallback

typedef int(* VSIFilesystemPluginStatCallback) (void *pUserData, const char *pszFilename, VSIStatBufL *pStatBuf, int nFlags)

Return information about a handle.

Optional (driver dependent)

Since: GDAL 3.0

◆ VSIFilesystemPluginTellCallback

typedef vsi_l_offset(* VSIFilesystemPluginTellCallback) (void *pFile)

Return current position in handle.

Mandatory

Since: GDAL 3.0

◆ VSIFilesystemPluginTruncateCallback

typedef int(* VSIFilesystemPluginTruncateCallback) (void *pFile, vsi_l_offset nNewSize)

Truncate handle.

Mandatory (driver dependent?) for write handles

◆ VSIFilesystemPluginUnlinkCallback

typedef int(* VSIFilesystemPluginUnlinkCallback) (void *pUserData, const char *pszFilename)

Remove handle by name.

Optional

Since: GDAL 3.0

◆ VSIFilesystemPluginWriteCallback

typedef size_t(* VSIFilesystemPluginWriteCallback) (void *pFile, const void *pBuffer, size_t nSize, size_t nCount)

Write bytes at current offset.

Mandatory for writable handles

Since: GDAL 3.0

Enumeration Type Documentation

◆ VSIRangeStatus

enum VSIRangeStatus

Range status.

Enumerator
VSI_RANGE_STATUS_UNKNOWN	Unknown.
VSI_RANGE_STATUS_DATA	Data present.
VSI_RANGE_STATUS_HOLE	Hole.

Function Documentation

◆ CPLGetPhysicalRAM()

GIntBig CPLGetPhysicalRAM ( void )

Return the total physical RAM in bytes.

In the context of a container using cgroups (typically Docker), this will take into account that limitation (starting with GDAL 2.4.0)

You should generally use CPLGetUsablePhysicalRAM() instead.

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

Since: GDAL 2.0

◆ CPLGetUsablePhysicalRAM()

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.

Starting with GDAL 2.4.0, it will also take account resource limits on Posix systems.

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

◆ VSIAbortPendingUploads()

int VSIAbortPendingUploads ( const char * pszFilename )

Abort ongoing multi-part uploads.

Abort ongoing multi-part uploads on AWS S3 and Google Cloud Storage. This can be used in case a process doing such uploads was killed in a unclean way.

Without effect on other virtual file systems.

Parameters

pszFilename filename or prefix of a directory into which multipart uploads must be aborted. This can be the root directory of a bucket. UTF-8 encoded.

Returns: TRUE on success or FALSE on an error.

Since: GDAL 3.4

◆ VSIAllocFilesystemPluginCallbacksStruct()

VSIFilesystemPluginCallbacksStruct* VSIAllocFilesystemPluginCallbacksStruct ( void )

return a VSIFilesystemPluginCallbacksStruct to be populated at runtime with handler callbacks

Since: GDAL 3.0

◆ VSICalloc()

void* VSICalloc	(	size_t	nCount,
		size_t	nSize
	)

Analog of calloc().

Use VSIFree() to free

◆ VSIClearCredentials()

void VSIClearCredentials ( const char * pszPathPrefix )

Clear credentials set with VSISetCredential()

Note that no particular care is taken to remove them from RAM in a secure way.

Parameters

pszPathPrefix If set to NULL, all credentials are cleared. If set to not-NULL, only those set with VSISetCredential(pszPathPrefix, ...) will be cleared.

Since: GDAL 3.5

◆ VSICloseDir()

void VSICloseDir ( VSIDIR * dir )

Close a directory.

This function is close to the POSIX closedir() function.

Parameters

dir	Directory handled returned by VSIOpenDir().

Since: GDAL 2.4

◆ VSICurlClearCache()

void VSICurlClearCache ( void )

Clean local cache associated with /vsicurl/ (and related file systems)

/vsicurl (and related file systems like /vsis3/, /vsigs/, /vsiaz/, /vsioss/, /vsiswift/) cache a number of metadata and data for faster execution in read-only scenarios. But when the content on the server-side may change during the same process, those mechanisms can prevent opening new files, or give an outdated version of them.

Since: GDAL 2.2.1

◆ VSICurlPartialClearCache()

void VSICurlPartialClearCache ( const char * pszFilenamePrefix )

Clean local cache associated with /vsicurl/ (and related file systems) for a given filename (and its subfiles and subdirectories if it is a directory)

/vsicurl (and related file systems like /vsis3/, /vsigs/, /vsiaz/, /vsioss/, /vsiswift/) cache a number of metadata and data for faster execution in read-only scenarios. But when the content on the server-side may change during the same process, those mechanisms can prevent opening new files, or give an outdated version of them.

Parameters

pszFilenamePrefix Filename prefix

Since: GDAL 2.4.0

◆ VSIFCloseL()

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.

◆ VSIFEofL()

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.

◆ VSIFFlushL()

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.

◆ VSIFGetNativeFileDescriptorL()

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.

◆ VSIFGetRangeStatusL()

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

◆ VSIFileFromMemBuffer()

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()).

◆ VSIFOpenEx2L()

VSILFILE* VSIFOpenEx2L	(	const char *	pszFilename,
		const char *	pszAccess,
		int	bSetError,
		CSLConstList	papszOptions
	)

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.
papszOptions	NULL or NULL-terminated list of strings. The content is highly file system dependent. Currently only MIME headers such as Content-Type and Content-Encoding are supported for the /vsis3/, /vsigs/, /vsiaz/, /vsiadls/ file systems.

Returns: NULL on failure, or the file handle.

Since: GDAL 3.3

◆ VSIFOpenExL()

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

◆ VSIFOpenL()

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.

◆ VSIFPrintfL()

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.

◆ VSIFPutcL()

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.

◆ VSIFReadL()

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.

◆ VSIFReadMultiRangeL()

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

◆ VSIFreeAligned()

void VSIFreeAligned ( void * ptr )

Free a buffer allocated with VSIMallocAligned().

Parameters

ptr	Buffer to free.

Since: GDAL 2.2

◆ VSIFreeFilesystemPluginCallbacksStruct()

void VSIFreeFilesystemPluginCallbacksStruct ( VSIFilesystemPluginCallbacksStruct * poCb )

free resources allocated by VSIAllocFilesystemPluginCallbacksStruct

Since: GDAL 3.0

◆ VSIFSeekL()

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.

Caution: vsi_l_offset is a unsigned type, so SEEK_CUR can only be used for positive seek. If negative seek is needed, use VSIFSeekL( fp, VSIFTellL(fp) + negative_offset, SEEK_SET ).

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.

◆ VSIFTellL()

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.

◆ VSIFTruncateL()

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

◆ VSIFWriteL()

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.

◆ VSIGetActualURL()

const char* VSIGetActualURL ( const char * pszFilename )

Returns the actual URL of a supplied filename.

Currently only returns a non-NULL value for network-based virtual file systems. For example "/vsis3/bucket/filename" will be expanded as "https://bucket.s3.amazon.com/filename"

Note that the lifetime of the returned string, is short, and may be invalidated by any following GDAL functions.

Parameters

pszFilename the path of the filesystem object. UTF-8 encoded.

Returns: the actual URL corresponding to the supplied filename, or NULL. Should not be freed.

Since: GDAL 2.3

◆ VSIGetCredential()

const char* VSIGetCredential	(	const char *	pszPath,
		const char *	pszKey,
		const char *	pszDefault
	)

Get a credential option for a given path.

If no match occurs, CPLGetConfigOption(pszKey, pszDefault) is returned.

Mostly to be use by virtual file system implementations.

Since: GDAL 3.5

See also: VSISetCredential()

◆ VSIGetDiskFreeSpace()

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

◆ VSIGetFileMetadata()

char** VSIGetFileMetadata	(	const char *	pszFilename,
		const char *	pszDomain,
		CSLConstList	papszOptions
	)

Get metadata on files.

Implemented currently only for network-like filesystems.

Parameters

pszFilename	the path of the filesystem object to be queried. UTF-8 encoded.
pszDomain	Metadata domain to query. Depends on the file system. The following are supported: HEADERS: to get HTTP headers for network-like filesystems (/vsicurl/, /vsis3/, /vsgis/, etc) TAGS: /vsis3/: to get S3 Object tagging information /vsiaz/: to get blob tags. Refer to https://docs.microsoft.com/en-us/rest/api/storageservices/get-blob-tags STATUS: specific to /vsiadls/: returns all system defined properties for a path (seems in practice to be a subset of HEADERS) ACL: specific to /vsiadls/ and /vsigs/: returns the access control list for a path. For /vsigs/, a single XML=xml_content string is returned. Refer to https://cloud.google.com/storage/docs/xml-api/get-object-acls METADATA: specific to /vsiaz/: to set blob metadata. Refer to https://docs.microsoft.com/en-us/rest/api/storageservices/get-blob-metadata. Note: this will be a subset of what pszDomain=HEADERS returns
papszOptions	Unused. Should be set to NULL.

Returns: a NULL-terminated list of key=value strings, to be freed with CSLDestroy() or NULL in case of error / empty list.

Since: GDAL 3.1.0

◆ VSIGetFileSystemOptions()

const char* VSIGetFileSystemOptions ( const char * pszFilename )

Return the list of options associated with a virtual file system handler as a serialized XML string.

Those options may be set as configuration options with CPLSetConfigOption().

Parameters

pszFilename a filename, or prefix of a virtual file system handler.

Returns: a string, which must not be freed, or NULL if no options is declared.

Since: GDAL 2.3

◆ VSIGetFileSystemsPrefixes()

char** VSIGetFileSystemsPrefixes ( void )

Return the list of prefixes for virtual file system handlers currently registered.

Typically: "", "/vsimem/", "/vsicurl/", etc

Returns: a NULL terminated list of prefixes. Must be freed with CSLDestroy()

Since: GDAL 2.3

◆ VSIGetMemFileBuffer()

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.

◆ VSIGetNextDirEntry()

const VSIDIREntry* VSIGetNextDirEntry ( VSIDIR * dir )

Return the next entry of the directory.

This function is close to the POSIX readdir() function. It actually returns more information (file size, last modification time), which on 'real' file systems involve one 'stat' call per file.

For filesystems that can have both a regular file and a directory name of the same name (typically /vsis3/), when this situation of duplicate happens, the directory name will be suffixed by a slash character. Otherwise directory names are not suffixed by slash.

The returned entry remains valid until the next call to VSINextDirEntry() or VSICloseDir() with the same handle.

Parameters

dir	Directory handled returned by VSIOpenDir(). Must not be NULL.

Returns: a entry, or NULL if there is no more entry in the directory. This return value must not be freed.

Since: GDAL 2.4

◆ VSIGetSignedURL()

char* VSIGetSignedURL	(	const char *	pszFilename,
		CSLConstList	papszOptions
	)

Returns a signed URL of a supplied filename.

Currently only returns a non-NULL value for /vsis3/, /vsigs/, /vsiaz/ and /vsioss/ For example "/vsis3/bucket/filename" will be expanded as "https://bucket.s3.amazon.com/filename?X-Amz-Algorithm=AWS4-HMAC-SHA256..." Configuration options that apply for file opening (typically to provide credentials), and are returned by VSIGetFileSystemOptions(), are also valid in that context.

Parameters

pszFilename the path of the filesystem object. UTF-8 encoded.

papszOptions

list of options, or NULL. Depend on file system handler. For /vsis3/, /vsigs/, /vsiaz/ and /vsioss/, the following options are supported:

START_DATE=YYMMDDTHHMMSSZ: date and time in UTC following ISO 8601 standard, corresponding to the start of validity of the URL. If not specified, current date time.
EXPIRATION_DELAY=number_of_seconds: number between 1 and 604800 (seven days) for the validity of the signed URL. Defaults to 3600 (one hour)
VERB=GET/HEAD/DELETE/PUT/POST: HTTP VERB for which the request will be used. Default to GET.

/vsiaz/ supports additional options:

SIGNEDIDENTIFIER=value: to relate the given shared access signature to a corresponding stored access policy.
SIGNEDPERMISSIONS=r|w: permissions associated with the shared access signature. Normally deduced from VERB.

Returns: a signed URL, or NULL. Should be freed with CPLFree().

Since: GDAL 2.3

◆ VSIHasOptimizedReadMultiRange()

int VSIHasOptimizedReadMultiRange ( const char * pszPath )

Returns if the filesystem supports efficient multi-range reading.

Currently only returns TRUE for /vsicurl/ and derived file systems.

Parameters

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

Returns: TRUE if the file system is known to have an efficient multi-range reading.

Since: GDAL 2.3

◆ VSIIngestFile()

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

◆ VSIInstallADLSFileHandler()

void VSIInstallADLSFileHandler ( void )

Install /vsiaz/ Microsoft Azure Data Lake Storage Gen2 file system handler (requires libcurl)

embed:rst
See :ref:`/vsiadls/ documentation <vsiadls>`

Since: GDAL 3.3

◆ VSIInstallAzureFileHandler()

void VSIInstallAzureFileHandler ( void )

Install /vsiaz/ Microsoft Azure Blob file system handler (requires libcurl)

embed:rst
See :ref:`/vsiaz/ documentation <vsiaz>`

Since: GDAL 2.3

◆ VSIInstallAzureStreamingFileHandler()

void VSIInstallAzureStreamingFileHandler ( void )

Install /vsiaz_streaming/ Microsoft Azure Blob file system handler (requires libcurl)

embed:rst
See :ref:`/vsiaz_streaming/ documentation <vsiaz_streaming>`

Since: GDAL 2.3

◆ VSIInstallCryptFileHandler()

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 :

8 bytes. Signature. Fixed value: VSICRYPT.
UINT16_LE. Header size (including previous signature bytes).
UINT8. Format major version. Current value: 1.
UINT8. Format minor version. Current value: 0.
UINT16. Sector size.
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.
UINT8. Block cipher mode of operation. Valid values are: 0 = CBC, 1 = CFB, 2 = OFB, 3 = CTR, 4 = CBC_CTS.
UINT8. Size in bytes of the Initial Vector.
N bytes with the content of the Initial Vector, where N is the value of the previous field.
UINT16_LE. Size in bytes of the free text.
N bytes with the content of the free text, where N is the value of the previous field.
UINT8. Size in bytes of encrypted content (key check), or 0 if key check is absent.
N bytes with encrypted content (key check), where N is the value of the previous field.
UINT64_LE. Size of the unencrypted file, in bytes.
UINT16_LE. Size in bytes of extra content (of unspecified semantics). For v1.0, fixed value of 0
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

◆ VSIInstallCurlFileHandler()

void VSIInstallCurlFileHandler ( void )

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

embed:rst
See :ref:`/vsicurl/ documentation <vsicurl>`

Since: GDAL 1.8.0

◆ VSIInstallCurlStreamingFileHandler()

void VSIInstallCurlStreamingFileHandler ( void )

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

embed:rst
See :ref:`/vsicurl_streaming/ documentation <vsicurl_streaming>`

Since: GDAL 1.10

◆ VSIInstallGSFileHandler()

void VSIInstallGSFileHandler ( void )

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

embed:rst
See :ref:`/vsigs/ documentation <vsigs>`

Since: GDAL 2.2

◆ VSIInstallGSStreamingFileHandler()

void VSIInstallGSStreamingFileHandler ( void )

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

embed:rst
See :ref:`/vsigs_streaming/ documentation <vsigs_streaming>`

Since: GDAL 2.2

◆ VSIInstallGZipFileHandler()

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.

embed:rst
See :ref:`/vsigzip/ documentation <vsigzip>`

Since: GDAL 1.6.0

◆ VSIInstallHdfsHandler()

void VSIInstallHdfsHandler ( void )

Install /vsihdfs/ file system handler (requires JVM and HDFS support)

Since: GDAL 2.4.0

◆ VSIInstallMemFileHandler()

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.

Directory related functions are supported.

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

GByte *ConvertBufferFormat( GByte *pabyInData, vsi_l_offset nInDataLength,
                            vsi_l_offset *pnOutDataLength )
{
    // create memory file system object from buffer.
    VSIFCloseL( VSIFileFromMemBuffer( "/vsimem/work.dat", pabyInData,
                                      nInDataLength, FALSE ) );
 
    // Open memory buffer for read.
    GDALDatasetH hDS = GDALOpen( "/vsimem/work.dat", GA_ReadOnly );
 
    // Get output format driver.
    GDALDriverH hDriver = GDALGetDriverByName( "GTiff" );
    GDALDatasetH hOutDS;
 
    hOutDS = GDALCreateCopy( hDriver, "/vsimem/out.tif", hDS, TRUE, NULL,
                             NULL, NULL );
 
    // close source file, and "unlink" it.
    GDALClose( hDS );
    VSIUnlink( "/vsimem/work.dat" );
 
    // seize the buffer associated with the output file.
 
    return VSIGetMemFileBuffer( "/vsimem/out.tif", pnOutDataLength, TRUE );
}

◆ VSIInstallOSSFileHandler()

void VSIInstallOSSFileHandler ( void )

Install /vsioss/ Alibaba Cloud Object Storage Service (OSS) file system handler (requires libcurl)

embed:rst
See :ref:`/vsioss/ documentation <vsioss>`

Since: GDAL 2.3

◆ VSIInstallOSSStreamingFileHandler()

void VSIInstallOSSStreamingFileHandler ( void )

Install /vsiaz_streaming/ Alibaba Cloud Object Storage Service (OSS) (requires libcurl)

embed:rst
See :ref:`/vsioss_streaming/ documentation <vsioss_streaming>`

Since: GDAL 2.3

◆ VSIInstallPluginHandler()

int VSIInstallPluginHandler	(	const char *	pszPrefix,
		const VSIFilesystemPluginCallbacksStruct *	poCb
	)

register a handler on the given prefix.

All IO on datasets opened with the filename /prefix/xxxxxx will go through these callbacks. pszPrefix must begin and end with a '/'

Since: GDAL 3.0

◆ VSIInstallS3FileHandler()

void VSIInstallS3FileHandler ( void )

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

embed:rst
See :ref:`/vsis3/ documentation <vsis3>`

Since: GDAL 2.1

◆ VSIInstallS3StreamingFileHandler()

void VSIInstallS3StreamingFileHandler ( void )

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

embed:rst
See :ref:`/vsis3_streaming/ documentation <vsis3_streaming>`

Since: GDAL 2.1

◆ VSIInstallSparseFileHandler()

void VSIInstallSparseFileHandler ( void )

Install /vsisparse/ virtual file handler.

embed:rst
See :ref:`/vsisparse/ documentation <vsisparse>`

◆ VSIInstallStdinHandler()

void VSIInstallStdinHandler ( void )

Install /vsistdin/ file system handler.

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

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

embed:rst
See :ref:`/vsistdin/ documentation <vsistdin>`

Since: GDAL 1.8.0

◆ VSIInstallStdoutHandler()

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().

A variation of this file system exists as the /vsistdout_redirect/ file system handler, where the output function can be defined with VSIStdoutSetRedirection().

embed:rst
See :ref:`/vsistdout/ documentation <vsistdout>`

Since: GDAL 1.8.0

◆ VSIInstallSubFileHandler()

void VSIInstallSubFileHandler ( void )

Install /vsisubfile/ virtual file handler.

embed:rst
See :ref:`/vsisubfile/ documentation <vsisubfile>`

◆ VSIInstallSwiftFileHandler()

void VSIInstallSwiftFileHandler ( void )

Install /vsiswift/ OpenStack Swif Object Storage (Swift) file system handler (requires libcurl)

embed:rst
See :ref:`/vsiswift/ documentation <vsiswift>`

Since: GDAL 2.3

◆ VSIInstallSwiftStreamingFileHandler()

void VSIInstallSwiftStreamingFileHandler ( void )

Install /vsiswift_streaming/ OpenStack Swif Object Storage (Swift) file system handler (requires libcurl)

embed:rst
See :ref:`/vsiswift_streaming/ documentation <vsiswift_streaming>`

Since: GDAL 2.3

◆ VSIInstallTarFileHandler()

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.

embed:rst
See :ref:`/vsitar/ documentation <vsitar>`

Since: GDAL 1.8.0

◆ VSIInstallWebHdfsHandler()

void VSIInstallWebHdfsHandler ( void )

Install /vsiwebhdfs/ WebHDFS (Hadoop File System) REST API file system handler (requires libcurl)

embed:rst
See :ref:`/vsiwebhdfs/ documentation <vsiwebhdfs>`

Since: GDAL 2.4

◆ VSIInstallZipFileHandler()

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.

embed:rst
See :ref:`/vsizip/ documentation <vsizip>`

Since: GDAL 1.6.0

◆ VSIIsCaseSensitiveFS()

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

◆ VSIMalloc()

void* VSIMalloc ( size_t nSize )

Analog of malloc().

Use VSIFree() to free

◆ VSIMalloc2()

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.

◆ VSIMalloc3()

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.

◆ VSIMallocAligned()

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

◆ VSIMallocAlignedAuto()

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

◆ VSIMkdir()

int VSIMkdir	(	const char *	pszPathname,
		long	mode
	)

Create a directory.

Create a new directory with the indicated mode. For POSIX-style systems, the mode is modified by the file creation mask (umask). However, some file systems and platforms may not use umask, or they may ignore the mode completely. So a reasonable cross-platform default mode value is 0755.

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.

◆ VSIMkdirRecursive()

int VSIMkdirRecursive	(	const char *	pszPathname,
		long	mode
	)

Create a directory and all its ancestors.

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.

Since: GDAL 2.3

◆ VSINetworkStatsGetAsSerializedJSON()

char* VSINetworkStatsGetAsSerializedJSON ( char ** papszOptions )

Return network related statistics, as a JSON serialized object.

Statistics collecting should be enabled with the CPL_VSIL_NETWORK_STATS_ENABLED configuration option set to YES before any network activity starts (for efficiency, reading it is cached on first access, until VSINetworkStatsReset() is called)

Statistics can also be emitted on standard output at process termination if the CPL_VSIL_SHOW_NETWORK_STATS configuration option is set to YES.

Example of output:

{
  "methods":{
    "GET":{
      "count":6,
      "downloaded_bytes":40825
    },
    "PUT":{
      "count":1,
      "uploaded_bytes":35472
    }
  },
  "handlers":{
    "vsigs":{
      "methods":{
        "GET":{
          "count":2,
          "downloaded_bytes":446
        },
        "PUT":{
          "count":1,
          "uploaded_bytes":35472
        }
      },
      "files":{
        "\/vsigs\/spatialys\/byte.tif":{
          "methods":{
            "PUT":{
              "count":1,
              "uploaded_bytes":35472
            }
          },
          "actions":{
            "Write":{
              "methods":{
                "PUT":{
                  "count":1,
                  "uploaded_bytes":35472
                }
              }
            }
          }
        }
      },
      "actions":{
        "Stat":{
          "methods":{
            "GET":{
              "count":2,
              "downloaded_bytes":446
            }
          },
          "files":{
            "\/vsigs\/spatialys\/byte.tif\/":{
              "methods":{
                "GET":{
                  "count":1,
                  "downloaded_bytes":181
                }
              }
            }
          }
        }
      }
    },
    "vsis3":{
         [...]
    }
  }
}

Parameters

papszOptions Unused.

Returns: a JSON serialized string to free with VSIFree(), or nullptr

Since: GDAL 3.2.0

◆ VSINetworkStatsReset()

void VSINetworkStatsReset ( void )

Clear network related statistics.

The effect of the CPL_VSIL_NETWORK_STATS_ENABLED configuration option will also be reset. That is, that the next network access will check its value again.

Since: GDAL 3.2.0

◆ VSIOpenDir()

VSIDIR* VSIOpenDir	(	const char *	pszPath,
		int	nRecurseDepth,
		const char const	papszOptions
	)

Open a directory to read its entries.

This function is close to the POSIX opendir() function.

For /vsis3/, /vsigs/, /vsioss/, /vsiaz/ and /vsiadls/, this function has an efficient implementation, minimizing the number of network requests, when invoked with nRecurseDepth <= 0.

Entries are read by calling VSIGetNextDirEntry() on the handled returned by that function, until it returns NULL. VSICloseDir() must be called once done with the returned directory handle.

Parameters

pszPath	the relative, or absolute path of a directory to read. UTF-8 encoded.
nRecurseDepth	0 means do not recurse in subdirectories, 1 means recurse only in the first level of subdirectories, etc. -1 means unlimited recursion level
papszOptions	NULL terminated list of options, or NULL. The following options are implemented: PREFIX=string: (GDAL >= 3.4) Filter to select filenames only starting with the specified prefix. Implemented efficiently for /vsis3/, /vsigs/, and /vsiaz/ (but not /vsiadls/) NAME_AND_TYPE_ONLY=YES/NO: (GDAL >= 3.4) Defaults to NO. If set to YES, only the pszName and nMode members of VSIDIR are guaranteed to be set. This is implemented efficiently for the Unix virtual file system.

Returns: a handle, or NULL in case of error

Since: GDAL 2.4

◆ VSIOverwriteFile()

int VSIOverwriteFile	(	VSILFILE *	fpTarget,
		const char *	pszSourceFilename
	)

Overwrite an existing file with content from another one.

Parameters

fpTarget	file handle opened with VSIFOpenL() with "rb+" flag.
pszSourceFilename	source filename

Returns: TRUE in case of success.

Since: GDAL 3.1

◆ VSIReadDir()

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.

◆ VSIReadDirEx()

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

◆ VSIReadDirRecursive()

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

◆ VSIRealloc()

void* VSIRealloc	(	void *	pData,
		size_t	nNewSize
	)

Analog of realloc().

Use VSIFree() to free

◆ VSIRename()

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.

◆ VSIRewindL()

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().

◆ VSIRmdir()

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.

◆ VSIRmdirRecursive()

int VSIRmdirRecursive ( const char * pszDirname )

Delete a directory recursively.

Deletes a directory object and its content from the file system.

Starting with GDAL 3.1, /vsis3/ has an efficient implementation of this function. Starting with GDAL 3.4, /vsigs/ has an efficient implementation of this function, provided that OAuth2 authentication is used.

Returns: 0 on success or -1 on an error.

Since: GDAL 2.3

◆ VSISetCredential()

void VSISetCredential	(	const char *	pszPathPrefix,
		const char *	pszKey,
		const char *	pszValue
	)

Set a credential (or more generally an option related to a virtual file system) for a given path prefix.

That option may also be set as a configuration option with CPLSetConfigOption(), but this function allows to specify them with a granularity at the level of a file path, which makes it easier if using the same virtual file system but with different credentials (e.g. different credentials for bucket "/vsis3/foo" and "/vsis3/bar")

This is supported for the following virtual file systems: /vsis3/, /vsigs/, /vsiaz/, /vsioss/, /vsiwebhdfs, /vsiswift. Note: setting them for a path starting with /vsiXXX/ will also apply for /vsiXXX_streaming/ requests.

Note that no particular care is taken to store them in RAM in a secure way. So they might accidentally hit persistent storage if swapping occurs, or someone with access to the memory allocated by the process may be able to read them.

Parameters

pszPathPrefix	a path prefix of a virtual file system handler. Typically of the form "/vsiXXX/bucket". Must NOT be NULL.
pszKey	Option name. Must NOT be NULL.
pszValue	Option value. May be NULL to erase it.

Since: GDAL 3.5

◆ VSISetCryptKey()

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/

◆ VSISetFileMetadata()

int VSISetFileMetadata	(	const char *	pszFilename,
		CSLConstList	papszMetadata,
		const char *	pszDomain,
		CSLConstList	papszOptions
	)

Set metadata on files.

Implemented currently only for /vsis3/, /vsigs/, /vsiaz/ and /vsiadls/

Parameters

pszFilename	the path of the filesystem object to be set. UTF-8 encoded.
papszMetadata	NULL-terminated list of key=value strings.
pszDomain	Metadata domain to set. Depends on the file system. The following are supported: HEADERS: specific to /vsis3/ and /vsigs/: to set HTTP headers, such as "Content-Type", or other file system specific header. For /vsigs/, this also includes: x-goog-meta-{key}={value}. Note that you should specify all metadata to be set, as existing metadata will be overridden. TAGS: Content of papszMetadata should be KEY=VALUE pairs. /vsis3/: to set S3 Object tagging information /vsiaz/: to set blob tags. Refer to https://docs.microsoft.com/en-us/rest/api/storageservices/set-blob-tags. Note: storageV2 must be enabled on the account PROPERTIES: to /vsiaz/: to set properties. Refer to https://docs.microsoft.com/en-us/rest/api/storageservices/set-blob-properties. to /vsiadls/: to set properties. Refer to https://docs.microsoft.com/en-us/rest/api/storageservices/datalakestoragegen2/path/update for headers valid for action=setProperties. ACL: specific to /vsiadls/ and /vsigs/: to set access control list. For /vsiadls/, refer to https://docs.microsoft.com/en-us/rest/api/storageservices/datalakestoragegen2/path/update for headers valid for action=setAccessControl or setAccessControlRecursive. In setAccessControlRecursive, x-ms-acl must be specified in papszMetadata. For /vsigs/, refer to https://cloud.google.com/storage/docs/xml-api/put-object-acls. A single XML=xml_content string should be specified as in papszMetadata. METADATA: specific to /vsiaz/: to set blob metadata. Refer to https://docs.microsoft.com/en-us/rest/api/storageservices/set-blob-metadata. Content of papszMetadata should be strings in the form x-ms-meta-name=value
papszOptions	NULL or NULL terminated list of options. For /vsiadls/ and pszDomain=ACL, "RECURSIVE=TRUE" can be set to set the access control list recursively. When RECURSIVE=TRUE is set, MODE should also be set to one of "set", "modify" or "remove".

Returns: TRUE in case of success.

Since: GDAL 3.1.0

◆ VSISiblingFiles()

char** VSISiblingFiles ( const char * pszFilename )

Return related filenames.

This function is essentially meant at being used by GDAL internals.

Parameters

pszFilename the path of a filename to inspect UTF-8 encoded.

Returns: The list of entries, relative to the directory, of all sidecar files available or NULL if the list is not known. Filenames are returned in UTF-8 encoding. Most implementations will return NULL, and a subsequent ReadDir will list all files available in the file's directory. This function will be overridden by VSI FilesystemHandlers that wish to force e.g. an empty list to avoid opening non-existent files on slow filesystems. The return value shall be destroyed with CSLDestroy()

Since: GDAL 3.2

◆ VSIStatExL()

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, VSI_STAT_SIZE_FLAG, VSI_STAT_SET_ERROR_FLAG, VSI_STAT_CACHE_ONLY or a combination of those to get partial info.

Returns: 0 on success or -1 on an error.

Since: GDAL 1.8.0

◆ VSIStatL()

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.

◆ VSIStdoutSetRedirection()

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

◆ VSIStrdup()

char* VSIStrdup ( const char * pszString )

Analog of strdup().

Use VSIFree() to free

◆ VSIStrerror()

char* VSIStrerror ( int nErrno )

Return the error string corresponding to the error number.

Do not free it

◆ VSISupportsSparseFiles()

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

◆ VSISync()

int VSISync	(	const char *	pszSource,
		const char *	pszTarget,
		const char const	papszOptions,
		GDALProgressFunc	pProgressFunc,
		void *	pProgressData,
		char ***	ppapszOutputs
	)

Synchronize a source file/directory with a target file/directory.

This is a analog of the 'rsync' utility. In the current implementation, rsync would be more efficient for local file copying, but VSISync() main interest is when the source or target is a remote file system like /vsis3/ or /vsigs/, in which case it can take into account the timestamps of the files (or optionally the ETag/MD5Sum) to avoid unneeded copy operations.

This is only implemented efficiently for:

local filesystem <--> remote filesystem.
remote filesystem <--> remote filesystem (starting with GDAL 3.1). Where the source and target remote filesystems are the same and one of /vsis3/, /vsigs/ or /vsiaz/

Similarly to rsync behavior, if the source filename ends with a slash, it means that the content of the directory must be copied, but not the directory name. For example, assuming "/home/even/foo" contains a file "bar", VSISync("/home/even/foo/", "/mnt/media", ...) will create a "/mnt/media/bar" file. Whereas VSISync("/home/even/foo", "/mnt/media", ...) will create a "/mnt/media/foo" directory which contains a bar file.

Parameters

pszSource	Source file or directory. UTF-8 encoded.
pszTarget	Target file or directory. UTF-8 encoded.
papszOptions	Null terminated list of options, or NULL. Currently accepted options are: RECURSIVE=NO (the default is YES) SYNC_STRATEGY=TIMESTAMP/ETAG/OVERWRITE. Determines which criterion is used to determine if a target file must be replaced when it already exists and has the same file size as the source. Only applies for a source or target being a network filesystem. The default is TIMESTAMP (similarly to how 'aws s3 sync' works), that is to say that for an upload operation, a remote file is replaced if it has a different size or if it is older than the source. For a download operation, a local file is replaced if it has a different size or if it is newer than the remote file. The ETAG strategy assumes that the ETag metadata of the remote file is the MD5Sum of the file content, which is only true in the case of /vsis3/ for files not using KMS server side encryption and uploaded in a single PUT operation (so smaller than 50 MB given the default used by GDAL). Only to be used for /vsis3/, /vsigs/ or other filesystems using a MD5Sum as ETAG. The OVERWRITE strategy (GDAL >= 3.2) will always overwrite the target file with the source one. NUM_THREADS=integer. (GDAL >= 3.1) Number of threads to use for parallel file copying. Only use for when /vsis3/, /vsigs/, /vsiaz/ or /vsiadls/ is in source or target. The default is 10 since GDAL 3.3 CHUNK_SIZE=integer. (GDAL >= 3.1) Maximum size of chunk (in bytes) to use to split large objects when downloading them from /vsis3/, /vsigs/, /vsiaz/ or /vsiadls/ to local file system, or for upload to /vsis3/, /vsiaz/ or /vsiadls/ from local file system. Only used if NUM_THREADS > 1. For upload to /vsis3/, this chunk size must be set at least to 5 MB. The default is 8 MB since GDAL 3.3 x-amz-KEY=value. (GDAL >= 3.5) MIME header to pass during creation of a /vsis3/ object. x-goog-KEY=value. (GDAL >= 3.5) MIME header to pass during creation of a /vsigs/ object. x-ms-KEY=value. (GDAL >= 3.5) MIME header to pass during creation of a /vsiaz/ or /vsiadls/ object.
pProgressFunc	Progress callback, or NULL.
pProgressData	User data of progress callback, or NULL.
ppapszOutputs	Unused. Should be set to NULL for now.

Returns: TRUE on success or FALSE on an error.

Since: GDAL 2.4

◆ VSIUnlink()

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.

◆ VSIUnlinkBatch()

int* VSIUnlinkBatch ( CSLConstList papszFiles )

Delete several files, possibly in a batch.

All files should belong to the same file system handler.

This is implemented efficiently for /vsis3/ and /vsigs/ (provided for /vsigs/ that OAuth2 authentication is used).

Parameters

papszFiles NULL terminated list of files. UTF-8 encoded.

Returns: an array of size CSLCount(papszFiles), whose values are TRUE or FALSE depending on the success of deletion of the corresponding file. The array should be freed with VSIFree(). NULL might be return in case of a more general error (for example, files belonging to different file system handlers)

Since: GDAL 3.1

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ VSI_STAT_CACHE_ONLY

Typedef Documentation

◆ VSIFilesystemPluginCloseCallback

◆ VSIFilesystemPluginEofCallback

◆ VSIFilesystemPluginFlushCallback

◆ VSIFilesystemPluginGetRangeStatusCallback

◆ VSIFilesystemPluginMkdirCallback

◆ VSIFilesystemPluginOpenCallback

◆ VSIFilesystemPluginReadCallback

◆ VSIFilesystemPluginReadDirCallback

◆ VSIFilesystemPluginReadMultiRangeCallback

◆ VSIFilesystemPluginRenameCallback

◆ VSIFilesystemPluginRmdirCallback

◆ VSIFilesystemPluginSeekCallback

◆ VSIFilesystemPluginSiblingFilesCallback

◆ VSIFilesystemPluginStatCallback

◆ VSIFilesystemPluginTellCallback

◆ VSIFilesystemPluginTruncateCallback

◆ VSIFilesystemPluginUnlinkCallback

◆ VSIFilesystemPluginWriteCallback

Enumeration Type Documentation

◆ VSIRangeStatus

Function Documentation

◆ CPLGetPhysicalRAM()

◆ CPLGetUsablePhysicalRAM()

◆ VSIAbortPendingUploads()

◆ VSIAllocFilesystemPluginCallbacksStruct()

◆ VSICalloc()

◆ VSIClearCredentials()

◆ VSICloseDir()

◆ VSICurlClearCache()

◆ VSICurlPartialClearCache()

◆ VSIFCloseL()

◆ VSIFEofL()

◆ VSIFFlushL()

◆ VSIFGetNativeFileDescriptorL()

◆ VSIFGetRangeStatusL()

◆ VSIFileFromMemBuffer()

◆ VSIFOpenEx2L()

◆ VSIFOpenExL()

◆ VSIFOpenL()

◆ VSIFPrintfL()

◆ VSIFPutcL()

◆ VSIFReadL()

◆ VSIFReadMultiRangeL()

◆ VSIFreeAligned()

◆ VSIFreeFilesystemPluginCallbacksStruct()

◆ VSIFSeekL()

◆ VSIFTellL()

◆ VSIFTruncateL()

◆ VSIFWriteL()

◆ VSIGetActualURL()

◆ VSIGetCredential()

◆ VSIGetDiskFreeSpace()

◆ VSIGetFileMetadata()

◆ VSIGetFileSystemOptions()

◆ VSIGetFileSystemsPrefixes()

◆ VSIGetMemFileBuffer()

◆ VSIGetNextDirEntry()

◆ VSIGetSignedURL()

◆ VSIHasOptimizedReadMultiRange()

◆ VSIIngestFile()

◆ VSIInstallADLSFileHandler()

◆ VSIInstallAzureFileHandler()

◆ VSIInstallAzureStreamingFileHandler()

◆ VSIInstallCryptFileHandler()

◆ VSIInstallCurlFileHandler()

◆ VSIInstallCurlStreamingFileHandler()

◆ VSIInstallGSFileHandler()

◆ VSIInstallGSStreamingFileHandler()

◆ VSIInstallGZipFileHandler()

◆ VSIInstallHdfsHandler()

◆ VSIInstallMemFileHandler()