GDAL
|
Standard C Covers. More...
#include "cpl_port.h"
#include "cpl_progress.h"
#include <stdbool.h>
#include <unistd.h>
#include <sys/stat.h>
Go to the source code of this file.
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. | |
#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 struct VSIVirtualHandle | 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. | |
typedef int(* | VSIFilesystemPluginUnlinkCallback) (void *pUserData, const char *pszFilename) |
Remove handle by name. | |
typedef int(* | VSIFilesystemPluginRenameCallback) (void *pUserData, const char *oldpath, const char *newpath) |
Rename handle. | |
typedef int(* | VSIFilesystemPluginMkdirCallback) (void *pUserData, const char *pszDirname, long nMode) |
Create Directory. | |
typedef int(* | VSIFilesystemPluginRmdirCallback) (void *pUserData, const char *pszDirname) |
Delete Directory. | |
typedef char **(* | VSIFilesystemPluginReadDirCallback) (void *pUserData, const char *pszDirname, int nMaxFiles) |
List directory content. | |
typedef char **(* | VSIFilesystemPluginSiblingFilesCallback) (void *pUserData, const char *pszDirname) |
List related files. | |
typedef void *(* | VSIFilesystemPluginOpenCallback) (void *pUserData, const char *pszFilename, const char *pszAccess) |
Open a handle. | |
typedef vsi_l_offset(* | VSIFilesystemPluginTellCallback) (void *pFile) |
Return current position in handle. | |
typedef int(* | VSIFilesystemPluginSeekCallback) (void *pFile, vsi_l_offset nOffset, int nWhence) |
Seek to position in handle. | |
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. | |
typedef int(* | VSIFilesystemPluginReadMultiRangeCallback) (void *pFile, int nRanges, void **ppData, const vsi_l_offset *panOffsets, const size_t *panSizes) |
Read from multiple offsets. | |
typedef VSIRangeStatus(* | VSIFilesystemPluginGetRangeStatusCallback) (void *pFile, vsi_l_offset nOffset, vsi_l_offset nLength) |
Get empty ranges. | |
typedef int(* | VSIFilesystemPluginEofCallback) (void *pFile) |
Has end of file been reached. | |
typedef size_t(* | VSIFilesystemPluginWriteCallback) (void *pFile, const void *pBuffer, size_t nSize, size_t nCount) |
Write bytes at current offset. | |
typedef int(* | VSIFilesystemPluginFlushCallback) (void *pFile) |
Sync written bytes. | |
typedef int(* | VSIFilesystemPluginTruncateCallback) (void *pFile, vsi_l_offset nNewSize) |
Truncate handle. | |
typedef int(* | VSIFilesystemPluginCloseCallback) (void *pFile) |
Close file handle. | |
typedef void(* | VSIFilesystemPluginAdviseReadCallback) (void *pFile, int nRanges, const vsi_l_offset *panOffsets, const size_t *panSizes) |
This optional method is called when code plans to access soon one or several ranges in a file. | |
typedef int(* | VSIFilesystemPluginErrorCallback) (void *pFile) |
Has a read error (non end-of-file related) has occurred? | |
typedef void(* | VSIFilesystemPluginClearErrCallback) (void *pFile) |
Clear error and end-of-file flags. | |
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. | |
VSILFILE * | VSIFOpenExL (const char *, const char *, int) |
Open/create file. | |
VSILFILE * | VSIFOpenEx2L (const char *, const char *, int, CSLConstList) |
Open/create file. | |
int | VSIFCloseL (VSILFILE *) |
Close file. | |
int | VSIFSeekL (VSILFILE *, vsi_l_offset, int) |
Seek to requested offset. | |
vsi_l_offset | VSIFTellL (VSILFILE *) |
Tell current file offset. | |
void | VSIRewindL (VSILFILE *) |
Rewind the file pointer to the beginning of the file. | |
size_t | VSIFReadL (void *, size_t, size_t, VSILFILE *) |
Read bytes from file. | |
int | VSIFReadMultiRangeL (int nRanges, void **ppData, const vsi_l_offset *panOffsets, const size_t *panSizes, VSILFILE *) |
Read several ranges of bytes from file. | |
size_t | VSIFWriteL (const void *, size_t, size_t, VSILFILE *) |
Write bytes to file. | |
void | VSIFClearErrL (VSILFILE *) |
Reset the error and end-of-file indicators. | |
int | VSIFErrorL (VSILFILE *) |
Test the error indicator. | |
int | VSIFEofL (VSILFILE *) |
Test for end of file. | |
int | VSIFTruncateL (VSILFILE *, vsi_l_offset) |
Truncate/expand the file to the specified size. | |
int | VSIFFlushL (VSILFILE *) |
Flush pending writes to disk. | |
int | VSIFPrintfL (VSILFILE *, const char *,...) |
Formatted write to file. | |
int | VSIFPutcL (int, VSILFILE *) |
Write a single byte to the file. | |
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. | |
int | VSIIngestFile (VSILFILE *fp, const char *pszFilename, GByte **ppabyRet, vsi_l_offset *pnSize, GIntBig nMaxSize) |
Ingest a file into memory. | |
int | VSIOverwriteFile (VSILFILE *fpTarget, const char *pszSourceFilename) |
Overwrite an existing file with content from another one. | |
int | VSIStatL (const char *, VSIStatBufL *) |
Get filesystem object info. | |
int | VSIStatExL (const char *pszFilename, VSIStatBufL *psStatBuf, int nFlags) |
Get filesystem object info. | |
int | VSIIsCaseSensitiveFS (const char *pszFilename) |
Returns if the filenames of the filesystem are case sensitive. | |
int | VSISupportsSparseFiles (const char *pszPath) |
Returns if the filesystem supports sparse files. | |
bool | VSIIsLocal (const char *pszPath) |
Returns if the file/filesystem is "local". | |
char * | VSIGetCanonicalFilename (const char *pszPath) |
Returns the canonical filename. | |
bool | VSISupportsSequentialWrite (const char *pszPath, bool bAllowLocalTempFile) |
Returns if the filesystem supports sequential write. | |
bool | VSISupportsRandomWrite (const char *pszPath, bool bAllowLocalTempFile) |
Returns if the filesystem supports random write. | |
int | VSIHasOptimizedReadMultiRange (const char *pszPath) |
Returns if the filesystem supports efficient multi-range reading. | |
const char * | VSIGetActualURL (const char *pszFilename) |
Returns the actual URL of a supplied filename. | |
char * | VSIGetSignedURL (const char *pszFilename, CSLConstList papszOptions) |
Returns a signed URL of a supplied filename. | |
const char * | VSIGetFileSystemOptions (const char *pszFilename) |
Return the list of options associated with a virtual file system handler as a serialized XML string. | |
char ** | VSIGetFileSystemsPrefixes (void) |
Return the list of prefixes for virtual file system handlers currently registered. | |
void * | VSIFGetNativeFileDescriptorL (VSILFILE *) |
Returns the "native" file descriptor for the virtual handle. | |
char ** | VSIGetFileMetadata (const char *pszFilename, const char *pszDomain, CSLConstList papszOptions) |
Get metadata on files. | |
int | VSISetFileMetadata (const char *pszFilename, CSLConstList papszMetadata, const char *pszDomain, CSLConstList papszOptions) |
Set metadata on files. | |
void | VSISetPathSpecificOption (const char *pszPathPrefix, const char *pszKey, const char *pszValue) |
Set a path specific option for a given path prefix. | |
void | VSIClearPathSpecificOptions (const char *pszPathPrefix) |
Clear path specific options set with VSISetPathSpecificOption() | |
const char * | VSIGetPathSpecificOption (const char *pszPath, const char *pszKey, const char *pszDefault) |
Get the value a path specific option. | |
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. | |
void | VSIClearCredentials (const char *pszPathPrefix) |
Clear path specific options set with VSISetPathSpecificOption() | |
const char * | VSIGetCredential (const char *pszPath, const char *pszKey, const char *pszDefault) |
Get the value of a credential (or more generally an option related to a virtual file system) for a given path. | |
void * | VSICalloc (size_t, size_t) |
Analog of calloc(). | |
void * | VSIMalloc (size_t) |
Analog of malloc(). | |
void | VSIFree (void *) |
Analog of free() for data allocated with VSIMalloc(), VSICalloc(), VSIRealloc() | |
void * | VSIRealloc (void *, size_t) |
Analog of realloc(). | |
char * | VSIStrdup (const char *) |
Analog of strdup(). | |
void * | VSIMallocAligned (size_t nAlignment, size_t nSize) |
Allocates a buffer with an alignment constraint. | |
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. | |
void | VSIFreeAligned (void *ptr) |
Free a buffer allocated with VSIMallocAligned(). | |
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. | |
void * | VSIMalloc3 (size_t nSize1, size_t nSize2, size_t nSize3) |
VSIMalloc3 allocates (nSize1 * nSize2 * nSize3) bytes. | |
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. | |
GIntBig | CPLGetUsablePhysicalRAM (void) |
Return the total physical RAM, usable by a process, in bytes. | |
char ** | VSIReadDir (const char *) |
Read names in a directory. | |
char ** | VSIReadDirRecursive (const char *pszPath) |
Read names in a directory recursively. | |
char ** | VSIReadDirEx (const char *pszPath, int nMaxFiles) |
Read names in a directory. | |
char ** | VSISiblingFiles (const char *pszPath) |
Return related filenames. | |
const char * | VSIGetDirectorySeparator (const char *pszPath) |
Return the directory separator for the specified path. | |
VSIDIR * | VSIOpenDir (const char *pszPath, int nRecurseDepth, const char *const *papszOptions) |
Open a directory to read its entries. | |
const VSIDIREntry * | VSIGetNextDirEntry (VSIDIR *dir) |
Return the next entry of the directory. | |
void | VSICloseDir (VSIDIR *dir) |
Close a directory. | |
int | VSIMkdir (const char *pszPathname, long mode) |
Create a directory. | |
int | VSIMkdirRecursive (const char *pszPathname, long mode) |
Create a directory and all its ancestors. | |
int | VSIRmdir (const char *pszDirname) |
Delete a directory. | |
int | VSIRmdirRecursive (const char *pszDirname) |
Delete a directory recursively. | |
int | VSIUnlink (const char *pszFilename) |
Delete a file. | |
int * | VSIUnlinkBatch (CSLConstList papszFiles) |
Delete several files, possibly in a batch. | |
int | VSIRename (const char *oldpath, const char *newpath) |
Rename a file. | |
int | VSICopyFile (const char *pszSource, const char *pszTarget, VSILFILE *fpSource, vsi_l_offset nSourceSize, const char *const *papszOptions, GDALProgressFunc pProgressFunc, void *pProgressData) |
Copy a source file into a target file. | |
int | VSICopyFileRestartable (const char *pszSource, const char *pszTarget, const char *pszInputPayload, char **ppszOutputPayload, const char *const *papszOptions, GDALProgressFunc pProgressFunc, void *pProgressData) |
Copy a source file into a target file in a way that can (potentially) be restarted. | |
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. | |
int | VSIMultipartUploadGetCapabilities (const char *pszFilename, int *pbNonSequentialUploadSupported, int *pbParallelUploadSupported, int *pbAbortSupported, size_t *pnMinPartSize, size_t *pnMaxPartSize, int *pnMaxPartCount) |
Return capabilities for multiple part file upload. | |
char * | VSIMultipartUploadStart (const char *pszFilename, CSLConstList papszOptions) |
Initiates the upload a (big) file in a piece-wise way. | |
char * | VSIMultipartUploadAddPart (const char *pszFilename, const char *pszUploadId, int nPartNumber, vsi_l_offset nFileOffset, const void *pData, size_t nDataLength, CSLConstList papszOptions) |
Uploads a new part to a multi-part uploaded file. | |
int | VSIMultipartUploadEnd (const char *pszFilename, const char *pszUploadId, size_t nPartIdsCount, const char *const *apszPartIds, vsi_l_offset nTotalSize, CSLConstList papszOptions) |
Completes a multi-part file upload. | |
int | VSIMultipartUploadAbort (const char *pszFilename, const char *pszUploadId, CSLConstList papszOptions) |
Aborts a multi-part file upload. | |
int | VSIAbortPendingUploads (const char *pszFilename) |
Abort all ongoing multi-part uploads. | |
char * | VSIStrerror (int) |
Return the error string corresponding to the error number. | |
GIntBig | VSIGetDiskFreeSpace (const char *pszDirname) |
Return free disk space available on the filesystem. | |
void | VSINetworkStatsReset (void) |
Clear network related statistics. | |
char * | VSINetworkStatsGetAsSerializedJSON (char **papszOptions) |
Return network related statistics, as a JSON serialized object. | |
void | VSIInstallMemFileHandler (void) |
Install "memory" file system handler. | |
void | VSIInstallSubFileHandler (void) |
Install /vsisubfile/ virtual file handler. | |
void | VSIInstallCurlFileHandler (void) |
Install /vsicurl/ HTTP/FTP file system handler (requires libcurl) | |
void | VSICurlClearCache (void) |
Clean local cache associated with /vsicurl/ (and related file systems) | |
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) | |
void | VSIInstallCurlStreamingFileHandler (void) |
Install /vsicurl_streaming/ HTTP/FTP file system handler (requires libcurl). | |
void | VSIInstallS3FileHandler (void) |
Install /vsis3/ Amazon S3 file system handler (requires libcurl) | |
void | VSIInstallS3StreamingFileHandler (void) |
Install /vsis3_streaming/ Amazon S3 file system handler (requires libcurl). | |
void | VSIInstallGSFileHandler (void) |
Install /vsigs/ Google Cloud Storage file system handler (requires libcurl) | |
void | VSIInstallGSStreamingFileHandler (void) |
Install /vsigs_streaming/ Google Cloud Storage file system handler (requires libcurl) | |
void | VSIInstallAzureFileHandler (void) |
Install /vsiaz/ Microsoft Azure Blob file system handler (requires libcurl) | |
void | VSIInstallAzureStreamingFileHandler (void) |
Install /vsiaz_streaming/ Microsoft Azure Blob file system handler (requires libcurl) | |
void | VSIInstallADLSFileHandler (void) |
Install /vsiaz/ Microsoft Azure Data Lake Storage Gen2 file system handler (requires libcurl) | |
void | VSIInstallOSSFileHandler (void) |
Install /vsioss/ Alibaba Cloud Object Storage Service (OSS) file system handler (requires libcurl) | |
void | VSIInstallOSSStreamingFileHandler (void) |
Install /vsiaz_streaming/ Alibaba Cloud Object Storage Service (OSS) (requires libcurl) | |
void | VSIInstallSwiftFileHandler (void) |
Install /vsiswift/ OpenStack Swif Object Storage (Swift) file system handler (requires libcurl) | |
void | VSIInstallSwiftStreamingFileHandler (void) |
Install /vsiswift_streaming/ OpenStack Swif Object Storage (Swift) file system handler (requires libcurl) | |
void | VSIInstall7zFileHandler (void) |
Install /vsi7z/ 7zip file system handler (requires libarchive) | |
void | VSIInstallRarFileHandler (void) |
Install /vsirar/ RAR file system handler (requires libarchive) | |
void | VSIInstallGZipFileHandler (void) |
Install GZip file system handler. | |
void | VSIInstallZipFileHandler (void) |
Install ZIP file system handler. | |
void | VSIInstallStdinHandler (void) |
Install /vsistdin/ file system handler. | |
void | VSIInstallHdfsHandler (void) |
Install /vsihdfs/ file system handler (requires JVM and HDFS support) | |
void | VSIInstallWebHdfsHandler (void) |
Install /vsiwebhdfs/ WebHDFS (Hadoop File System) REST API file system handler (requires libcurl) | |
void | VSIInstallStdoutHandler (void) |
Install /vsistdout/ file system handler. | |
void | VSIInstallSparseFileHandler (void) |
Install /vsisparse/ virtual file handler. | |
void | VSIInstallTarFileHandler (void) |
Install /vsitar/ file system handler. | |
void | VSIInstallCachedFileHandler (void) |
Install /vsicached? file system handler. | |
void | VSIInstallCryptFileHandler (void) |
Install /vsicrypt/ encrypted file system handler (requires libcrypto++) | |
void | VSISetCryptKey (const GByte *pabyKey, int nKeySize) |
Installs the encryption/decryption key. | |
bool | VSIDuplicateFileSystemHandler (const char *pszSourceFSName, const char *pszNewFSName) |
Duplicate an existing file system handler. | |
VSILFILE * | VSIFileFromMemBuffer (const char *pszFilename, GByte *pabyData, vsi_l_offset nDataLength, int bTakeOwnership) |
Create memory "file" from a buffer. | |
GByte * | VSIGetMemFileBuffer (const char *pszFilename, vsi_l_offset *pnDataLength, int bUnlinkAndSeize) |
Fetch buffer underlying memory file. | |
const char * | VSIMemGenerateHiddenFilename (const char *pszFilename) |
Generates a unique filename that can be used with the /vsimem/ virtual file system. | |
void | VSIStdoutSetRedirection (VSIWriteFunction pFct, FILE *stream) |
Set an alternative write function and output file handle instead of fwrite() / stdout. | |
VSIFilesystemPluginCallbacksStruct * | VSIAllocFilesystemPluginCallbacksStruct (void) |
return a VSIFilesystemPluginCallbacksStruct to be populated at runtime with handler callbacks | |
void | VSIFreeFilesystemPluginCallbacksStruct (VSIFilesystemPluginCallbacksStruct *poCb) |
free resources allocated by VSIAllocFilesystemPluginCallbacksStruct | |
int | VSIInstallPluginHandler (const char *pszPrefix, const VSIFilesystemPluginCallbacksStruct *poCb) |
register a handler on the given prefix. | |
int | VSIRemovePluginHandler (const char *pszPrefix) |
Unregister a handler previously installed with VSIInstallPluginHandler() on the given prefix. | |
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.
#define VSI_STAT_CACHE_ONLY 0x10 |
Flag provided to VSIStatExL() to only use already cached results.
typedef void(* VSIFilesystemPluginAdviseReadCallback) (void *pFile, int nRanges, const vsi_l_offset *panOffsets, const size_t *panSizes) |
This optional method is called when code plans to access soon one or several ranges in a file.
Some file systems may be able to use this hint to for example asynchronously start such requests.
Offsets may be given in a non-increasing order, and may potentially overlap.
pFile | File handle. |
nRanges | Size of the panOffsets and panSizes arrays. |
panOffsets | Array containing the start offset of each range. |
panSizes | Array containing the size (in bytes) of each range. |
typedef void(* VSIFilesystemPluginClearErrCallback) (void *pFile) |
Clear error and end-of-file flags.
typedef int(* VSIFilesystemPluginCloseCallback) (void *pFile) |
Close file handle.
Optional
typedef int(* VSIFilesystemPluginEofCallback) (void *pFile) |
Has end of file been reached.
Mandatory? for read handles.
typedef int(* VSIFilesystemPluginErrorCallback) (void *pFile) |
Has a read error (non end-of-file related) has occurred?
typedef int(* VSIFilesystemPluginFlushCallback) (void *pFile) |
Sync written bytes.
Optional
typedef VSIRangeStatus(* VSIFilesystemPluginGetRangeStatusCallback) (void *pFile, vsi_l_offset nOffset, vsi_l_offset nLength) |
Get empty ranges.
Optional
typedef int(* VSIFilesystemPluginMkdirCallback) (void *pUserData, const char *pszDirname, long nMode) |
Create Directory.
Optional
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.
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
typedef char **(* VSIFilesystemPluginReadDirCallback) (void *pUserData, const char *pszDirname, int nMaxFiles) |
List directory content.
Optional
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
typedef int(* VSIFilesystemPluginRenameCallback) (void *pUserData, const char *oldpath, const char *newpath) |
Rename handle.
Optional
typedef int(* VSIFilesystemPluginRmdirCallback) (void *pUserData, const char *pszDirname) |
Delete Directory.
Optional
typedef int(* VSIFilesystemPluginSeekCallback) (void *pFile, vsi_l_offset nOffset, int nWhence) |
Seek to position in handle.
Mandatory except for write only handles
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
typedef int(* VSIFilesystemPluginStatCallback) (void *pUserData, const char *pszFilename, VSIStatBufL *pStatBuf, int nFlags) |
Return information about a handle.
Optional (driver dependent)
typedef vsi_l_offset(* VSIFilesystemPluginTellCallback) (void *pFile) |
Return current position in handle.
Mandatory
typedef int(* VSIFilesystemPluginTruncateCallback) (void *pFile, vsi_l_offset nNewSize) |
Truncate handle.
Mandatory (driver dependent?) for write handles
typedef int(* VSIFilesystemPluginUnlinkCallback) (void *pUserData, const char *pszFilename) |
Remove handle by name.
Optional
typedef size_t(* VSIFilesystemPluginWriteCallback) (void *pFile, const void *pBuffer, size_t nSize, size_t nCount) |
Write bytes at current offset.
Mandatory for writable handles
enum VSIRangeStatus |
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 and with extra fixes in GDAL 3.6.3)
You should generally use CPLGetUsablePhysicalRAM() instead.
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 (virtual memory) on Posix systems. Starting with GDAL 3.6.1, it will also take into account RLIMIT_RSS on Linux.
Note: This memory may already be partly used by other processes.
int VSIAbortPendingUploads | ( | const char * | pszFilename | ) |
Abort all 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.
This can be needed to avoid extra billing for some cloud storage providers.
Without effect on other virtual file systems.
VSIMultipartUploadAbort() can also be used to cancel a given upload, if the upload ID is known.
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. |
VSIFilesystemPluginCallbacksStruct * VSIAllocFilesystemPluginCallbacksStruct | ( | void | ) |
return a VSIFilesystemPluginCallbacksStruct to be populated at runtime with handler callbacks
void * VSICalloc | ( | size_t | nCount, |
size_t | nSize | ||
) |
Analog of calloc().
Use VSIFree() to free
void VSIClearCredentials | ( | const char * | pszPathPrefix | ) |
Clear path specific options set with VSISetPathSpecificOption()
void VSIClearPathSpecificOptions | ( | const char * | pszPathPrefix | ) |
Clear path specific options set with VSISetPathSpecificOption()
Note that no particular care is taken to remove them from RAM in a secure way.
pszPathPrefix | If set to NULL, all path specific options are cleared. If set to not-NULL, only those set with VSISetPathSpecificOption(pszPathPrefix, ...) will be cleared. |
void VSICloseDir | ( | VSIDIR * | dir | ) |
Close a directory.
This function is close to the POSIX closedir() function.
dir | Directory handled returned by VSIOpenDir(). |
int VSICopyFile | ( | const char * | pszSource, |
const char * | pszTarget, | ||
VSILFILE * | fpSource, | ||
vsi_l_offset | nSourceSize, | ||
const char *const * | papszOptions, | ||
GDALProgressFunc | pProgressFunc, | ||
void * | pProgressData | ||
) |
Copy a source file into a target file.
For a /vsizip/foo.zip/bar target, the options available are those of CPLAddFileInZip()
The following copies are made fully on the target server, without local download from source and upload to target:
pszSource | Source filename. UTF-8 encoded. May be NULL if fpSource is not NULL. |
pszTarget | Target filename. UTF-8 encoded. Must not be NULL |
fpSource | File handle on the source file. May be NULL if pszSource is not NULL. |
nSourceSize | Size of the source file. Pass -1 if unknown. If set to -1, and progress callback is used, VSIStatL() will be used on pszSource to retrieve the source size. |
papszOptions | Null terminated list of options, or NULL. |
pProgressFunc | Progress callback, or NULL. |
pProgressData | User data of progress callback, or NULL. |
int VSICopyFileRestartable | ( | const char * | pszSource, |
const char * | pszTarget, | ||
const char * | pszInputPayload, | ||
char ** | ppszOutputPayload, | ||
const char *const * | papszOptions, | ||
GDALProgressFunc | pProgressFunc, | ||
void * | pProgressData | ||
) |
Copy a source file into a target file in a way that can (potentially) be restarted.
This function provides the possibility of efficiently restarting upload of large files to cloud storage that implements upload in a chunked way, such as /vsis3/ and /vsigs/. For other destination file systems, this function may fallback to VSICopyFile() and not provide any smart restartable implementation.
Example of a potential workflow:
pszSource | Source filename. UTF-8 encoded. Must not be NULL | |
pszTarget | Target filename. UTF-8 encoded. Must not be NULL | |
pszInputPayload | NULL at the first invocation. When doing a retry, should be the content of *ppszOutputPayload from a previous invocation. | |
[out] | ppszOutputPayload | Pointer to an output string that will be set to a value that can be provided as pszInputPayload for a next call to VSICopyFileRestartable(). ppszOutputPayload must not be NULL. The string set in *ppszOutputPayload, if not NULL, is JSON-encoded, and can be re-used in another process instance. It must be freed with VSIFree() when no longer needed. |
papszOptions | Null terminated list of options, or NULL. Currently accepted options are:
| |
pProgressFunc | Progress callback, or NULL. | |
pProgressData | User data of progress callback, or NULL. |
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.
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.
pszFilenamePrefix | Filename prefix |
bool VSIDuplicateFileSystemHandler | ( | const char * | pszSourceFSName, |
const char * | pszNewFSName | ||
) |
Duplicate an existing file system handler.
A number of virtual file system for remote object stores use protocols identical or close to popular ones (typically AWS S3), but with slightly different settings (at the very least the endpoint).
This functions allows to duplicate the source virtual file system handler as a new one with a different prefix (when the source virtual file system handler supports the duplication operation).
VSISetPathSpecificOption() will typically be called afterwards to change configurable settings on the cloned file system handler (e.g. AWS_S3_ENDPOINT for a clone of /vsis3/).
void VSIFClearErrL | ( | VSILFILE * | fp | ) |
Reset the error and end-of-file indicators.
This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.
Analog of the POSIX clearerr() call.
fp | file handle opened with VSIFOpenL(). |
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.
fp | file handle opened with VSIFOpenL(). Passing a nullptr produces undefined behavior. |
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, or a call to VSIFClearErrL().
This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.
Analog of the POSIX feof() call.
fp | file handle opened with VSIFOpenL(). |
int VSIFErrorL | ( | VSILFILE * | fp | ) |
Test the error indicator.
Returns TRUE (non-zero) if an error condition occurred during the previous read operation. The error indicator is cleared by a call to VSIFClearErrL(). Note that a end-of-file situation, reported by VSIFEofL(), is not an error reported by VSIFErrorL().
This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.
Analog of the POSIX feof() call.
fp | file handle opened with VSIFOpenL(). |
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.
On Windows regular files, this method does nothing, unless the VSI_FLUSH configuration option is set to YES (and only when the file has not been opened with the WRITE_THROUGH option).
fp | file handle opened with VSIFOpenL(). |
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.
fp | file handle opened with VSIFOpenL(). |
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".
fp | file handle opened with VSIFOpenL(). |
nOffset | offset of the start of the extent. |
nLength | extent length. |
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. Starting with GDAL 3.6, nullptr can also be passed as pszFilename to mean an anonymous file, that is destroyed when the handle is closed.
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.
pszFilename | the filename to be created, or nullptr |
pabyData | the data buffer for the file. |
nDataLength | the length of buffer in bytes. |
bTakeOwnership | TRUE to transfer "ownership" of buffer or FALSE. |
VSILFILE * VSIFOpenEx2L | ( | const char * | pszFilename, |
const char * | pszAccess, | ||
int | bSetError, | ||
CSLConstList | papszOptions | ||
) |
Open/create file.
This function opens (or creates) a file with the desired access. 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.
The following options are supported:
Options specifics to /vsis3/, /vsigs/, /vsioss/ and /vsiaz/ in "w" mode:
Options specifics to /vsiaz/ in "w" mode:
Analog of the POSIX fopen() function.
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. |
VSILFILE * VSIFOpenExL | ( | const char * | pszFilename, |
const char * | pszAccess, | ||
int | bSetError | ||
) |
Open/create file.
This function opens (or creates) a file with the desired access. 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.
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. |
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.
pszFilename | the file to open. UTF-8 encoded. |
pszAccess | access requested (i.e. "r", "r+", "w") |
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.
fp | file handle opened with VSIFOpenL(). |
pszFormat | the printf() style format string. |
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.
nChar | character to write. |
fp | file handle opened with VSIFOpenL(). |
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.
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(). |
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/.
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(). |
void VSIFreeAligned | ( | void * | ptr | ) |
Free a buffer allocated with VSIMallocAligned().
ptr | Buffer to free. |
void VSIFreeFilesystemPluginCallbacksStruct | ( | VSIFilesystemPluginCallbacksStruct * | poCb | ) |
free resources allocated by VSIAllocFilesystemPluginCallbacksStruct
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 ).
fp | file handle opened with VSIFOpenL(). |
nOffset | offset in bytes. |
nWhence | one of SEEK_SET, SEEK_CUR or SEEK_END. |
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.
fp | file handle opened with VSIFOpenL(). |
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.
fp | file handle opened with VSIFOpenL(). |
nNewSize | new size in bytes. |
size_t VSIFWriteL | ( | const void * | pBuffer, |
size_t | nSize, | ||
size_t | nCount, | ||
VSILFILE * | fp | ||
) |
Write bytes to file.
Writes nCount objects of nSize bytes to the indicated file at the current offset into the indicated buffer.
This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.
Analog of the POSIX fwrite() call.
pBuffer | the buffer from which the data should be written (at least nCount * nSize bytes in size. |
nSize | size of objects to write in bytes. |
nCount | number of objects to write. |
fp | file handle opened with VSIFOpenL(). |
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.
pszFilename | the path of the filesystem object. UTF-8 encoded. |
char * VSIGetCanonicalFilename | ( | const char * | pszPath | ) |
Returns the canonical filename.
May be implemented by case-insensitive filesystems (currently Win32 and MacOSX) to return the filename with its actual case (i.e. the one that would be used when listing the content of the directory).
pszPath | UTF-8 encoded path |
const char * VSIGetCredential | ( | const char * | pszPath, |
const char * | pszKey, | ||
const char * | pszDefault | ||
) |
Get the value of a credential (or more generally an option related to a virtual file system) for a given path.
const char * VSIGetDirectorySeparator | ( | const char * | pszPath | ) |
Return the directory separator for the specified path.
Default is forward slash. The only exception currently is the Windows file system which returns anti-slash, unless the specified path is of the form "{drive_letter}:/{rest_of_the_path}".
GIntBig VSIGetDiskFreeSpace | ( | const char * | pszDirname | ) |
Return free disk space available on the filesystem.
This function returns the free disk space available on the filesystem.
pszDirname | a directory of the filesystem to query. |
char ** VSIGetFileMetadata | ( | const char * | pszFilename, |
const char * | pszDomain, | ||
CSLConstList | papszOptions | ||
) |
Get metadata on files.
Implemented currently only for network-like filesystems, or starting with GDAL 3.7 for /vsizip/
Starting with GDAL 3.11, calling it with pszFilename being the root of a /vsigs/ bucket and pszDomain == nullptr, and when authenticated through OAuth2, will result in returning the result of a "Buckets: get" operation (https://cloud.google.com/storage/docs/json_api/v1/buckets/get), with the keys of the top-level JSON document as keys of the key=value pairs returned by this function.
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 ones are supported:
|
papszOptions | Unused. Should be set to NULL. |
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().
pszFilename | a filename, or prefix of a virtual file system handler. |
char ** VSIGetFileSystemsPrefixes | ( | void | ) |
Return the list of prefixes for virtual file system handlers currently registered.
Typically: "", "/vsimem/", "/vsicurl/", etc
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.
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. |
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.
Note: since GDAL 3.9, for recursive mode, the directory separator will no longer be always forward slash, but will be the one returned by VSIGetDirectorySeparator(pszPathIn), so potentially backslash on Windows file systems.
dir | Directory handled returned by VSIOpenDir(). Must not be NULL. |
const char * VSIGetPathSpecificOption | ( | const char * | pszPath, |
const char * | pszKey, | ||
const char * | pszDefault | ||
) |
Get the value a path specific option.
Such option is typically, but not limited to, a credential setting for a virtual file system.
If no match occurs, CPLGetConfigOption(pszKey, pszDefault) is returned.
Mostly to be used by virtual file system implementations.
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.
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:
|
/vsiaz/ supports additional options:
int VSIHasOptimizedReadMultiRange | ( | const char * | pszPath | ) |
Returns if the filesystem supports efficient multi-range reading.
Currently only returns TRUE for /vsicurl/ and derived file systems.
pszPath | the path of the filesystem object to be tested. UTF-8 encoded. |
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.
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. |
void VSIInstall7zFileHandler | ( | void | ) |
Install /vsi7z/ 7zip file system handler (requires libarchive)
embed:rst See :ref:`/vsi7z/ documentation <vsi7z>`
void VSIInstallADLSFileHandler | ( | void | ) |
Install /vsiaz/ Microsoft Azure Data Lake Storage Gen2 file system handler (requires libcurl)
embed:rst See :ref:`/vsiadls/ documentation <vsiadls>`
void VSIInstallAzureFileHandler | ( | void | ) |
Install /vsiaz/ Microsoft Azure Blob file system handler (requires libcurl)
embed:rst See :ref:`/vsiaz/ documentation <vsiaz>`
void VSIInstallAzureStreamingFileHandler | ( | void | ) |
Install /vsiaz_streaming/ Microsoft Azure Blob file system handler (requires libcurl)
embed:rst See :ref:`/vsiaz_streaming/ documentation <vsiaz_streaming>`
void VSIInstallCachedFileHandler | ( | void | ) |
Install /vsicached? file system handler.
embed:rst See :ref:`/vsicached? documentation <vsicached>`
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 :
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 :
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.
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 :
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.
void VSIInstallCurlFileHandler | ( | void | ) |
Install /vsicurl/ HTTP/FTP file system handler (requires libcurl)
embed:rst See :ref:`/vsicurl/ documentation <vsicurl>`
void VSIInstallCurlStreamingFileHandler | ( | void | ) |
Install /vsicurl_streaming/ HTTP/FTP file system handler (requires libcurl).
embed:rst See :ref:`/vsicurl_streaming/ documentation <vsicurl_streaming>`
void VSIInstallGSFileHandler | ( | void | ) |
Install /vsigs/ Google Cloud Storage file system handler (requires libcurl)
embed:rst See :ref:`/vsigs/ documentation <vsigs>`
void VSIInstallGSStreamingFileHandler | ( | void | ) |
Install /vsigs_streaming/ Google Cloud Storage file system handler (requires libcurl)
embed:rst See :ref:`/vsigs_streaming/ documentation <vsigs_streaming>`
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>`
void VSIInstallHdfsHandler | ( | void | ) |
Install /vsihdfs/ file system handler (requires JVM and HDFS support)
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.
void VSIInstallOSSFileHandler | ( | void | ) |
Install /vsioss/ Alibaba Cloud Object Storage Service (OSS) file system handler (requires libcurl)
embed:rst See :ref:`/vsioss/ documentation <vsioss>`
void VSIInstallOSSStreamingFileHandler | ( | void | ) |
Install /vsiaz_streaming/ Alibaba Cloud Object Storage Service (OSS) (requires libcurl)
embed:rst See :ref:`/vsioss_streaming/ documentation <vsioss_streaming>`
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 '/'
void VSIInstallRarFileHandler | ( | void | ) |
Install /vsirar/ RAR file system handler (requires libarchive)
embed:rst See :ref:`/vsirar/ documentation <vsirar>`
void VSIInstallS3FileHandler | ( | void | ) |
Install /vsis3/ Amazon S3 file system handler (requires libcurl)
embed:rst See :ref:`/vsis3/ documentation <vsis3>`
void VSIInstallS3StreamingFileHandler | ( | void | ) |
Install /vsis3_streaming/ Amazon S3 file system handler (requires libcurl).
embed:rst See :ref:`/vsis3_streaming/ documentation <vsis3_streaming>`
void VSIInstallSparseFileHandler | ( | void | ) |
Install /vsisparse/ virtual file handler.
embed:rst See :ref:`/vsisparse/ documentation <vsisparse>`
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 by default).
Starting with GDAL 3.6, this limit can be configured either by setting the CPL_VSISTDIN_BUFFER_LIMIT configuration option to a number of bytes (can be -1 for unlimited), or using the "/vsistdin?buffer_limit=value" filename.
embed:rst See :ref:`/vsistdin/ documentation <vsistdin>`
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>`
void VSIInstallSubFileHandler | ( | void | ) |
Install /vsisubfile/ virtual file handler.
embed:rst See :ref:`/vsisubfile/ documentation <vsisubfile>`
void VSIInstallSwiftFileHandler | ( | void | ) |
Install /vsiswift/ OpenStack Swif Object Storage (Swift) file system handler (requires libcurl)
embed:rst See :ref:`/vsiswift/ documentation <vsiswift>`
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>`
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>`
void VSIInstallWebHdfsHandler | ( | void | ) |
Install /vsiwebhdfs/ WebHDFS (Hadoop File System) REST API file system handler (requires libcurl)
embed:rst See :ref:`/vsiwebhdfs/ documentation <vsiwebhdfs>`
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>`
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.
pszFilename | the path of the filesystem object to be tested. UTF-8 encoded. |
bool VSIIsLocal | ( | const char * | pszPath | ) |
Returns if the file/filesystem is "local".
The concept of local is mostly by opposition with a network / remote file system whose access time can be long.
/vsimem/ is considered to be a local file system, although a non-persistent one.
pszPath | the path of the filesystem object to be tested. UTF-8 encoded. |
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().
nAlignment | Must be a power of 2, multiple of sizeof(void*), and lesser than 256. |
nSize | Size of the buffer to allocate. |
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().
nSize | Size of the buffer to allocate. |
const char * VSIMemGenerateHiddenFilename | ( | const char * | pszFilename | ) |
Generates a unique filename that can be used with the /vsimem/ virtual file system.
This function returns a (short-lived) string containing a unique filename, (using an atomic counter), designed for temporary files that must remain invisible for other users working at the "/vsimem/" top-level, i.e. such files are not returned by VSIReadDir("/vsimem/") or VSIReadDirRecursive("/vsimem/)".
The function does not create the file per se. Such filename can be used to create a regular file with VSIFOpenL() or VSIFileFromMemBuffer(), or create a directory with VSIMkdir()
Once created, deletion of those files using VSIUnlink(), VSIRmdirRecursive(), etc. is of the responsibility of the user. The user should not attempt to work with the "parent" directory returned by CPLGetPath() / CPLGetDirname() on the returned filename, and work only with files at the same level or in subdirectories of what is returned by this function.
pszFilename | the filename to be appended at the end of the returned filename. If not specified, defaults to "unnamed". |
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.
pszPathname | the path to the directory to create. UTF-8 encoded. |
mode | the permissions mode. |
int VSIMkdirRecursive | ( | const char * | pszPathname, |
long | mode | ||
) |
Create a directory and all its ancestors.
pszPathname | the path to the directory to create. UTF-8 encoded. |
mode | the permissions mode. |
int VSIMultipartUploadAbort | ( | const char * | pszFilename, |
const char * | pszUploadId, | ||
CSLConstList | papszOptions | ||
) |
Aborts a multi-part file upload.
Cf VSIMultipartUploadStart().
This function is not implemented for all virtual file systems. Use VSIMultipartUploadGetCapabilities() to determine if it is supported.
This can be needed to avoid extra billing for some cloud storage providers.
pszFilename | Filename for which multipart upload should be completed. Should be the same as the one used for VSIMultipartUploadStart() |
pszUploadId | Value returned by VSIMultipartUploadStart() |
papszOptions | Unused. Should be nullptr. |
char * VSIMultipartUploadAddPart | ( | const char * | pszFilename, |
const char * | pszUploadId, | ||
int | nPartNumber, | ||
vsi_l_offset | nFileOffset, | ||
const void * | pData, | ||
size_t | nDataLength, | ||
CSLConstList | papszOptions | ||
) |
Uploads a new part to a multi-part uploaded file.
Cf VSIMultipartUploadStart().
VSIMultipartUploadGetCapabilities() returns hints on the constraints that apply to the upload, in terms of minimum/maximum size of each part, maximum number of parts, and whether non-sequential or parallel uploads are supported.
pszFilename | Filename to which to append the new part. Should be the same as the one used for VSIMultipartUploadStart() |
pszUploadId | Value returned by VSIMultipartUploadStart() |
nPartNumber | Part number, starting at 1. |
nFileOffset | Offset within the file at which (starts at 0) the passed data starts. |
pData | Pointer to an array of nDataLength bytes. |
nDataLength | Size in bytes of pData. |
papszOptions | Unused. Should be nullptr. |
int VSIMultipartUploadEnd | ( | const char * | pszFilename, |
const char * | pszUploadId, | ||
size_t | nPartIdsCount, | ||
const char *const * | apszPartIds, | ||
vsi_l_offset | nTotalSize, | ||
CSLConstList | papszOptions | ||
) |
Completes a multi-part file upload.
Cf VSIMultipartUploadStart().
pszFilename | Filename for which multipart upload should be completed. Should be the same as the one used for VSIMultipartUploadStart() |
pszUploadId | Value returned by VSIMultipartUploadStart() |
nPartIdsCount | Number of parts, andsize of apszPartIds |
apszPartIds | Array of part identifiers (as returned by VSIMultipartUploadAddPart()), that must be ordered in the sequential order of parts, and of size nPartIdsCount. |
nTotalSize | Total size of the file in bytes (must be equal to the sum of nDataLength passed to VSIMultipartUploadAddPart()) |
papszOptions | Unused. Should be nullptr. |
int VSIMultipartUploadGetCapabilities | ( | const char * | pszFilename, |
int * | pbNonSequentialUploadSupported, | ||
int * | pbParallelUploadSupported, | ||
int * | pbAbortSupported, | ||
size_t * | pnMinPartSize, | ||
size_t * | pnMaxPartSize, | ||
int * | pnMaxPartCount | ||
) |
Return capabilities for multiple part file upload.
pszFilename | Filename, or virtual file system prefix, onto which capabilities should apply. | |
[out] | pbNonSequentialUploadSupported | If not null, the pointed value is set if parts can be uploaded in a non-sequential way. |
[out] | pbParallelUploadSupported | If not null, the pointed value is set if parts can be uploaded in a parallel way. (implies *pbNonSequentialUploadSupported = true) |
[out] | pbAbortSupported | If not null, the pointed value is set if VSIMultipartUploadAbort() is implemented. |
[out] | pnMinPartSize | If not null, the pointed value is set to the minimum size of parts (but the last one), in MiB. |
[out] | pnMaxPartSize | If not null, the pointed value is set to the maximum size of parts, in MiB. |
[out] | pnMaxPartCount | If not null, the pointed value is set to the maximum number of parts that can be uploaded. |
char * VSIMultipartUploadStart | ( | const char * | pszFilename, |
CSLConstList | papszOptions | ||
) |
Initiates the upload a (big) file in a piece-wise way.
Using this API directly is generally not needed, but in very advanced cases, as VSIFOpenL(..., "wb") + VSIFWriteL(), VSISync(), VSICopyFile() or VSICopyFileRestartable() may be able to leverage it when needed.
This is only implemented for the /vsis3/, /vsigs/, /vsiaz/, /vsiadls/ and /vsioss/ virtual file systems.
The typical workflow is to do :
If VSIMultipartUploadAbort() is supported by the filesystem (VSIMultipartUploadGetCapabilities() can be used to determine it), this function should be called to cancel an upload. This can be needed to avoid extra billing for some cloud storage providers.
The following options are supported:
pszFilename | Filename to create |
papszOptions | NULL or null-terminated list of options. |
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":{ [...] } } }
papszOptions | Unused. |
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.
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.
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:
|
int VSIOverwriteFile | ( | VSILFILE * | fpTarget, |
const char * | pszSourceFilename | ||
) |
Overwrite an existing file with content from another one.
fpTarget | file handle opened with VSIFOpenL() with "rb+" flag. |
pszSourceFilename | source filename |
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.
pszPath | the relative, or absolute path of a directory to read. UTF-8 encoded. |
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.
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. |
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.
Note: since GDAL 3.9, for recursive mode, the directory separator will no longer be always forward slash, but will be the one returned by VSIGetDirectorySeparator(pszPathIn), so potentially backslash on Windows file systems.
pszPathIn | the relative, or absolute path of a directory to read. UTF-8 encoded. |
void * VSIRealloc | ( | void * | pData, |
size_t | nNewSize | ||
) |
Analog of realloc().
Use VSIFree() to free
int VSIRemovePluginHandler | ( | const char * | pszPrefix | ) |
Unregister a handler previously installed with VSIInstallPluginHandler() on the given prefix.
Note: it is generally unsafe to remove a handler while there are still file handles opened that are managed by that handler. It is the responsibility of the caller to ensure that it calls this function in a situation where it is safe to do so.
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.
oldpath | the name of the file to be renamed. UTF-8 encoded. |
newpath | the name the file should be given. UTF-8 encoded. |
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.
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.
pszDirname | the path of the directory to be deleted. UTF-8 encoded. |
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.
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.
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.
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. |
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/
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:
|
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". |
void VSISetPathSpecificOption | ( | const char * | pszPathPrefix, |
const char * | pszKey, | ||
const char * | pszValue | ||
) |
Set a path specific option for a given path prefix.
Such option is typically, but not limited to, a credential setting for a virtual file system.
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.
pszPathPrefix | a path prefix of a virtual file system handler. Typically of the form "/vsiXXX/bucket". Must NOT be NULL. Should not include trailing slashes. |
pszKey | Option name. Must NOT be NULL. |
pszValue | Option value. May be NULL to erase it. |
char ** VSISiblingFiles | ( | const char * | pszFilename | ) |
Return related filenames.
This function is essentially meant at being used by GDAL internals.
pszFilename | the path of a filename to inspect UTF-8 encoded. |
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/)
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. |
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.
pszFilename | the path of the filesystem object to be queried. UTF-8 encoded. |
psStatBuf | the structure to load with information. |
void VSIStdoutSetRedirection | ( | VSIWriteFunction | pFct, |
FILE * | stream | ||
) |
Set an alternative write function and output file handle instead of fwrite() / stdout.
pFct | Function with same signature as fwrite() |
stream | File handle on which to output. Passed to pFct. |
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
bool VSISupportsRandomWrite | ( | const char * | pszPath, |
bool | bAllowLocalTempFile | ||
) |
Returns if the filesystem supports random write.
pszPath | the path of the filesystem object to be tested. UTF-8 encoded. |
bAllowLocalTempFile | whether the file system is allowed to use a local temporary file before uploading to the target location. |
bool VSISupportsSequentialWrite | ( | const char * | pszPath, |
bool | bAllowLocalTempFile | ||
) |
Returns if the filesystem supports sequential write.
pszPath | the path of the filesystem object to be tested. UTF-8 encoded. |
bAllowLocalTempFile | whether the file system is allowed to use a local temporary file before uploading to the target location. |
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.
pszPath | the path of the filesystem object to be tested. UTF-8 encoded. |
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:
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.
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:
|
pProgressFunc | Progress callback, or NULL. |
pProgressData | User data of progress callback, or NULL. |
ppapszOutputs | Unused. Should be set to NULL for now. |
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.
pszFilename | the path of the file to be deleted. UTF-8 encoded. |
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).
papszFiles | NULL terminated list of files. UTF-8 encoded. |