SDTS_AL
Classes | Macros | Typedefs | Enumerations | Functions
cpl_vsi.h File Reference
#include "cpl_port.h"
#include "cpl_progress.h"
#include <unistd.h>
#include <sys/stat.h>

Go to the source code of this file.

Classes

struct  VSIDIREntry
 
struct  VSIFilesystemPluginCallbacksStruct
 

Macros

#define VSI_ISLNK(x)   S_ISLNK(x)
 
#define VSI_ISREG(x)   S_ISREG(x)
 
#define VSI_ISDIR(x)   S_ISDIR(x)
 
#define VSI_L_OFFSET_MAX   GUINTBIG_MAX
 
#define VSI_STAT_EXISTS_FLAG   0x1
 
#define VSI_STAT_NATURE_FLAG   0x2
 
#define VSI_STAT_SIZE_FLAG   0x4
 
#define VSI_STAT_SET_ERROR_FLAG   0x8
 
#define VSI_MALLOC_ALIGNED_AUTO_VERBOSE(size)   VSIMallocAlignedAutoVerbose(size,__FILE__,__LINE__)
 
#define VSI_MALLOC_VERBOSE(size)   VSIMallocVerbose(size,__FILE__,__LINE__)
 
#define VSI_MALLOC2_VERBOSE(nSize1, nSize2)   VSIMalloc2Verbose(nSize1,nSize2,__FILE__,__LINE__)
 
#define VSI_MALLOC3_VERBOSE(nSize1, nSize2, nSize3)   VSIMalloc3Verbose(nSize1,nSize2,nSize3,__FILE__,__LINE__)
 
#define VSI_CALLOC_VERBOSE(nCount, nSize)   VSICallocVerbose(nCount,nSize,__FILE__,__LINE__)
 
#define VSI_REALLOC_VERBOSE(pOldPtr, nNewSize)   VSIReallocVerbose(pOldPtr,nNewSize,__FILE__,__LINE__)
 
#define VSI_STRDUP_VERBOSE(pszStr)   VSIStrdupVerbose(pszStr,__FILE__,__LINE__)
 
#define CPLReadDir   VSIReadDir
 

Typedefs

typedef GUIntBig vsi_l_offset
 
typedef FILE VSILFILE
 
typedef struct VSI_STAT64_T VSIStatBufL
 
typedef struct VSIDIR VSIDIR
 
typedef struct VSIDIREntry VSIDIREntry
 
typedef size_t(* VSIWriteFunction) (const void *ptr, size_t size, size_t nmemb, FILE *stream)
 
typedef int(* VSIFilesystemPluginStatCallback) (void *pUserData, const char *pszFilename, VSIStatBufL *pStatBuf, int nFlags)
 
typedef int(* VSIFilesystemPluginUnlinkCallback) (void *pUserData, const char *pszFilename)
 
typedef int(* VSIFilesystemPluginRenameCallback) (void *pUserData, const char *oldpath, const char *newpath)
 
typedef int(* VSIFilesystemPluginMkdirCallback) (void *pUserData, const char *pszDirname, long nMode)
 
typedef int(* VSIFilesystemPluginRmdirCallback) (void *pUserData, const char *pszDirname)
 
typedef char **(* VSIFilesystemPluginReadDirCallback) (void *pUserData, const char *pszDirname, int nMaxFiles)
 
typedef void *(* VSIFilesystemPluginOpenCallback) (void *pUserData, const char *pszFilename, const char *pszAccess)
 
typedef vsi_l_offset(* VSIFilesystemPluginTellCallback) (void *pFile)
 
typedef int(* VSIFilesystemPluginSeekCallback) (void *pFile, vsi_l_offset nOffset, int nWhence)
 
typedef size_t(* VSIFilesystemPluginReadCallback) (void *pFile, void *pBuffer, size_t nSize, size_t nCount)
 
typedef int(* VSIFilesystemPluginReadMultiRangeCallback) (void *pFile, int nRanges, void **ppData, const vsi_l_offset *panOffsets, const size_t *panSizes)
 
typedef VSIRangeStatus(* VSIFilesystemPluginGetRangeStatusCallback) (void *pFile, vsi_l_offset nOffset, vsi_l_offset nLength)
 
typedef int(* VSIFilesystemPluginEofCallback) (void *pFile)
 
typedef size_t(* VSIFilesystemPluginWriteCallback) (void *pFile, const void *pBuffer, size_t nSize, size_t nCount)
 
typedef int(* VSIFilesystemPluginFlushCallback) (void *pFile)
 
typedef int(* VSIFilesystemPluginTruncateCallback) (void *pFile, vsi_l_offset nNewSize)
 
typedef int(* VSIFilesystemPluginCloseCallback) (void *pFile)
 

Enumerations

enum  VSIRangeStatus { VSI_RANGE_STATUS_UNKNOWN, VSI_RANGE_STATUS_DATA, VSI_RANGE_STATUS_HOLE }
 

Functions

VSILFILE CPL_DLL * VSIFOpenL (const char *, const char *) CPL_WARN_UNUSED_RESULT
 Open file. More...
 
VSILFILE CPL_DLL * VSIFOpenExL (const char *, const char *, int) CPL_WARN_UNUSED_RESULT
 Open file. More...
 
int CPL_DLL VSIFCloseL (VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
 Close file. More...
 
int CPL_DLL VSIFSeekL (VSILFILE *, vsi_l_offset, int) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
 Seek to requested offset. More...
 
vsi_l_offset CPL_DLL VSIFTellL (VSILFILE *) CPL_WARN_UNUSED_RESULT
 Tell current file offset. More...
 
void CPL_DLL VSIRewindL (VSILFILE *)
 Rewind the file pointer to the beginning of the file. More...
 
size_t CPL_DLL VSIFReadL (void *, size_t, size_t, VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
 Read bytes from file. More...
 
int CPL_DLL VSIFReadMultiRangeL (int nRanges, void **ppData, const vsi_l_offset *panOffsets, const size_t *panSizes, VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
 Read several ranges of bytes from file. More...
 
size_t CPL_DLL VSIFWriteL (const void *, size_t, size_t, VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
 Write bytes to file. More...
 
int CPL_DLL VSIFEofL (VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
 Test for end of file. More...
 
int CPL_DLL VSIFTruncateL (VSILFILE *, vsi_l_offset) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
 Truncate/expand the file to the specified size. More...
 
int CPL_DLL VSIFFlushL (VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
 Flush pending writes to disk. More...
 
int CPL_DLL int CPL_DLL VSIFPutcL (int, VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
 Write a single byte to the file. More...
 
VSIRangeStatus CPL_DLL 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 CPL_DLL VSIIngestFile (VSILFILE *fp, const char *pszFilename, GByte **ppabyRet, vsi_l_offset *pnSize, GIntBig nMaxSize) CPL_WARN_UNUSED_RESULT
 Ingest a file into memory. More...
 
int CPL_DLL VSIOverwriteFile (VSILFILE *fpTarget, const char *pszSourceFilename) CPL_WARN_UNUSED_RESULT
 Overwrite an existing file with content from another one. More...
 
int CPL_DLL VSIStatL (const char *, VSIStatBufL *) CPL_WARN_UNUSED_RESULT
 Get filesystem object info. More...
 
int CPL_DLL VSIStatExL (const char *pszFilename, VSIStatBufL *psStatBuf, int nFlags) CPL_WARN_UNUSED_RESULT
 Get filesystem object info. More...
 
int CPL_DLL VSIIsCaseSensitiveFS (const char *pszFilename)
 Returns if the filenames of the filesystem are case sensitive. More...
 
int CPL_DLL VSISupportsSparseFiles (const char *pszPath)
 Returns if the filesystem supports sparse files. More...
 
int CPL_DLL VSIHasOptimizedReadMultiRange (const char *pszPath)
 Returns if the filesystem supports efficient multi-range reading. More...
 
const char CPL_DLL * VSIGetActualURL (const char *pszFilename)
 Returns the actual URL of a supplied filename. More...
 
char CPL_DLL * VSIGetSignedURL (const char *pszFilename, CSLConstList papszOptions)
 Returns a signed URL of a supplied filename. More...
 
const char CPL_DLL * VSIGetFileSystemOptions (const char *pszFilename)
 Return the list of options associated with a virtual file system handler as a serialized XML string. More...
 
char CPL_DLL ** VSIGetFileSystemsPrefixes (void)
 Return the list of prefixes for virtual file system handlers currently registered. More...
 
void CPL_DLL * VSIFGetNativeFileDescriptorL (VSILFILE *)
 Returns the "native" file descriptor for the virtual handle. More...
 
void CPL_DLL * VSICalloc (size_t, size_t) CPL_WARN_UNUSED_RESULT
 
void CPL_DLL * VSIMalloc (size_t) CPL_WARN_UNUSED_RESULT
 
void CPL_DLL VSIFree (void *)
 
void CPL_DLL * VSIRealloc (void *, size_t) CPL_WARN_UNUSED_RESULT
 
char CPL_DLL * VSIStrdup (const char *) CPL_WARN_UNUSED_RESULT
 
void CPL_DLL * VSIMallocAligned (size_t nAlignment, size_t nSize) CPL_WARN_UNUSED_RESULT
 
void CPL_DLL * VSIMallocAlignedAuto (size_t nSize) CPL_WARN_UNUSED_RESULT
 
void CPL_DLL VSIFreeAligned (void *ptr)
 
void CPL_DLL * VSIMallocAlignedAutoVerbose (size_t nSize, const char *pszFile, int nLine) CPL_WARN_UNUSED_RESULT
 
void CPL_DLL * VSIMalloc2 (size_t nSize1, size_t nSize2) CPL_WARN_UNUSED_RESULT
 
void CPL_DLL * VSIMalloc3 (size_t nSize1, size_t nSize2, size_t nSize3) CPL_WARN_UNUSED_RESULT
 
void CPL_DLL * VSIMallocVerbose (size_t nSize, const char *pszFile, int nLine) CPL_WARN_UNUSED_RESULT
 
void CPL_DLL * VSIMalloc2Verbose (size_t nSize1, size_t nSize2, const char *pszFile, int nLine) CPL_WARN_UNUSED_RESULT
 
void CPL_DLL * VSIMalloc3Verbose (size_t nSize1, size_t nSize2, size_t nSize3, const char *pszFile, int nLine) CPL_WARN_UNUSED_RESULT
 
void CPL_DLL * VSICallocVerbose (size_t nCount, size_t nSize, const char *pszFile, int nLine) CPL_WARN_UNUSED_RESULT
 
void CPL_DLL * VSIReallocVerbose (void *pOldPtr, size_t nNewSize, const char *pszFile, int nLine) CPL_WARN_UNUSED_RESULT
 
char CPL_DLL * VSIStrdupVerbose (const char *pszStr, const char *pszFile, int nLine) CPL_WARN_UNUSED_RESULT
 
GIntBig CPL_DLL CPLGetPhysicalRAM (void)
 
GIntBig CPL_DLL CPLGetUsablePhysicalRAM (void)
 
char CPL_DLL ** VSIReadDir (const char *)
 Read names in a directory. More...
 
char CPL_DLL ** VSIReadDirRecursive (const char *pszPath)
 Read names in a directory recursively. More...
 
char CPL_DLL ** VSIReadDirEx (const char *pszPath, int nMaxFiles)
 Read names in a directory. More...
 
VSIDIR CPL_DLL * VSIOpenDir (const char *pszPath, int nRecurseDepth, const char *const *papszOptions)
 Open a directory to read its entries. More...
 
const VSIDIREntry CPL_DLL * VSIGetNextDirEntry (VSIDIR *dir)
 Return the next entry of the directory. More...
 
void CPL_DLL VSICloseDir (VSIDIR *dir)
 Close a directory. More...
 
int CPL_DLL VSIMkdir (const char *pszPathname, long mode)
 Create a directory. More...
 
int CPL_DLL VSIMkdirRecursive (const char *pszPathname, long mode)
 Create a directory and all its ancestors. More...
 
int CPL_DLL VSIRmdir (const char *pszDirname)
 Delete a directory. More...
 
int CPL_DLL VSIRmdirRecursive (const char *pszDirname)
 Delete a directory recursively. More...
 
int CPL_DLL VSIUnlink (const char *pszFilename)
 Delete a file. More...
 
int CPL_DLL VSIRename (const char *oldpath, const char *newpath)
 Rename a file. More...
 
int CPL_DLL 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...
 
char CPL_DLL * VSIStrerror (int)
 
GIntBig CPL_DLL VSIGetDiskFreeSpace (const char *pszDirname)
 Return free disk space available on the filesystem. More...
 
void CPL_DLL VSIInstallMemFileHandler (void)
 Install "memory" file system handler. More...
 
void CPL_DLL VSIInstallSubFileHandler (void)
 
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 (non-functional stub) More...
 
void VSIInstallStdoutHandler (void)
 Install /vsistdout/ file system handler. More...
 
void CPL_DLL VSIInstallSparseFileHandler (void)
 
void VSIInstallTarFileHandler (void)
 Install /vsitar/ file system handler. More...
 
VSILFILE CPL_DLL * VSIFileFromMemBuffer (const char *pszFilename, GByte *pabyData, vsi_l_offset nDataLength, int bTakeOwnership) CPL_WARN_UNUSED_RESULT
 Create memory "file" from a buffer. More...
 
GByte CPL_DLL * VSIGetMemFileBuffer (const char *pszFilename, vsi_l_offset *pnDataLength, int bUnlinkAndSeize)
 Fetch buffer underlying memory file. More...
 
void CPL_DLL VSIStdoutSetRedirection (VSIWriteFunction pFct, FILE *stream)
 
VSIFilesystemPluginCallbacksStruct CPL_DLL * VSIAllocFilesystemPluginCallbacksStruct (void)
 
void CPL_DLL VSIFreeFilesystemPluginCallbacksStruct (VSIFilesystemPluginCallbacksStruct *poCb)
 
int CPL_DLL VSIInstallPluginHandler (const char *pszPrefix, const VSIFilesystemPluginCallbacksStruct *poCb)
 

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

◆ CPLReadDir

#define CPLReadDir   VSIReadDir

Alias of VSIReadDir()

◆ VSI_CALLOC_VERBOSE

#define VSI_CALLOC_VERBOSE (   nCount,
  nSize 
)    VSICallocVerbose(nCount,nSize,__FILE__,__LINE__)

VSI_CALLOC_VERBOSE

◆ VSI_ISDIR

#define VSI_ISDIR (   x)    S_ISDIR(x)

Test if the file is a directory

◆ VSI_ISLNK

#define VSI_ISLNK (   x)    S_ISLNK(x)

Test if the file is a symbolic link

◆ VSI_ISREG

#define VSI_ISREG (   x)    S_ISREG(x)

Test if the file is a regular file

◆ VSI_L_OFFSET_MAX

#define VSI_L_OFFSET_MAX   GUINTBIG_MAX

Maximum value for a file offset

◆ VSI_MALLOC2_VERBOSE

#define VSI_MALLOC2_VERBOSE (   nSize1,
  nSize2 
)    VSIMalloc2Verbose(nSize1,nSize2,__FILE__,__LINE__)

VSI_MALLOC2_VERBOSE

◆ VSI_MALLOC3_VERBOSE

#define VSI_MALLOC3_VERBOSE (   nSize1,
  nSize2,
  nSize3 
)    VSIMalloc3Verbose(nSize1,nSize2,nSize3,__FILE__,__LINE__)

VSI_MALLOC3_VERBOSE

◆ VSI_MALLOC_ALIGNED_AUTO_VERBOSE

#define VSI_MALLOC_ALIGNED_AUTO_VERBOSE (   size)    VSIMallocAlignedAutoVerbose(size,__FILE__,__LINE__)

VSIMallocAlignedAutoVerbose() with FILE and LINE reporting

◆ VSI_MALLOC_VERBOSE

#define VSI_MALLOC_VERBOSE (   size)    VSIMallocVerbose(size,__FILE__,__LINE__)

VSI_MALLOC_VERBOSE

◆ VSI_REALLOC_VERBOSE

#define VSI_REALLOC_VERBOSE (   pOldPtr,
  nNewSize 
)    VSIReallocVerbose(pOldPtr,nNewSize,__FILE__,__LINE__)

VSI_REALLOC_VERBOSE

◆ VSI_STAT_EXISTS_FLAG

#define VSI_STAT_EXISTS_FLAG   0x1

Flag provided to VSIStatExL() to test if the file exists

◆ VSI_STAT_NATURE_FLAG

#define VSI_STAT_NATURE_FLAG   0x2

Flag provided to VSIStatExL() to query the nature (file/dir) of the file

◆ VSI_STAT_SET_ERROR_FLAG

#define VSI_STAT_SET_ERROR_FLAG   0x8

Flag provided to VSIStatExL() to issue a VSIError in case of failure

◆ VSI_STAT_SIZE_FLAG

#define VSI_STAT_SIZE_FLAG   0x4

Flag provided to VSIStatExL() to query the file size

◆ VSI_STRDUP_VERBOSE

#define VSI_STRDUP_VERBOSE (   pszStr)    VSIStrdupVerbose(pszStr,__FILE__,__LINE__)

VSI_STRDUP_VERBOSE

Typedef Documentation

◆ vsi_l_offset

Type for a file offset

◆ VSIDIR

typedef struct VSIDIR VSIDIR

Opaque type for a directory iterator

◆ VSIDIREntry

VSIDIREntry::VSIDIREntry

Directory entry.

◆ VSIFilesystemPluginCloseCallback

typedef int(* VSIFilesystemPluginCloseCallback) (void *pFile)

Close file handle. Optional

Since
GDAL 2.5

◆ VSIFilesystemPluginEofCallback

typedef int(* VSIFilesystemPluginEofCallback) (void *pFile)

Has end of file been reached. Mandatory? for read handles.

Since
GDAL 2.5

◆ VSIFilesystemPluginFlushCallback

typedef int(* VSIFilesystemPluginFlushCallback) (void *pFile)

Sync written bytes. Optional

Since
GDAL 2.5

◆ VSIFilesystemPluginGetRangeStatusCallback

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

Get empty ranges. Optional

Since
GDAL 2.5

◆ VSIFilesystemPluginMkdirCallback

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

Create Directory. Optional

Since
GDAL 2.5

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

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

◆ VSIFilesystemPluginReadDirCallback

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

List directory content. Optional

Since
GDAL 2.5

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

◆ VSIFilesystemPluginRenameCallback

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

Rename handle. Optional

Since
GDAL 2.5

◆ VSIFilesystemPluginRmdirCallback

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

Delete Directory. Optional

Since
GDAL 2.5

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

◆ VSIFilesystemPluginStatCallback

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

Return information about a handle. Optional (driver dependent)

Since
GDAL 2.5

◆ VSIFilesystemPluginTellCallback

typedef vsi_l_offset(* VSIFilesystemPluginTellCallback) (void *pFile)

Return current position in handle. Mandatory

Since
GDAL 2.5

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

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

◆ VSILFILE

typedef FILE VSILFILE

Opaque type for a FILE that implements the VSIVirtualHandle API

◆ VSIStatBufL

typedef struct VSI_STAT64_T VSIStatBufL

Type for VSIStatL()

◆ VSIWriteFunction

typedef size_t(* VSIWriteFunction) (const void *ptr, size_t size, size_t nmemb, FILE *stream)

Callback used by VSIStdoutSetRedirection()

Enumeration Type Documentation

◆ VSIRangeStatus

Range status

Enumerator
VSI_RANGE_STATUS_UNKNOWN 

Unknown

VSI_RANGE_STATUS_DATA 

Data present

VSI_RANGE_STATUS_HOLE 

Hole

Function Documentation

◆ CPLGetPhysicalRAM()

GIntBig CPL_DLL 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 CPL_DLL 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

◆ VSIAllocFilesystemPluginCallbacksStruct()

VSIFilesystemPluginCallbacksStruct CPL_DLL* VSIAllocFilesystemPluginCallbacksStruct ( void  )

return a VSIFilesystemPluginCallbacksStruct to be populated at runtime with handler callbacks

Since
GDAL 2.5

◆ VSICalloc()

void CPL_DLL* VSICalloc ( size_t  nCount,
size_t  nSize 
)

Analog of calloc(). Use VSIFree() to free

◆ VSICallocVerbose()

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

VSICallocVerbose

◆ VSICloseDir()

void CPL_DLL VSICloseDir ( VSIDIR dir)

Close a directory.

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

Parameters
dirDirectory handled returned by VSIOpenDir().
Since
GDAL 2.4

◆ VSIFCloseL()

int CPL_DLL 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
fpfile handle opened with VSIFOpenL(). Passing a nullptr produces undefined behavior.
Returns
0 on success or -1 on failure.

◆ VSIFEofL()

int CPL_DLL 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
fpfile handle opened with VSIFOpenL().
Returns
TRUE if at EOF else FALSE.

◆ VSIFFlushL()

int CPL_DLL 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
fpfile handle opened with VSIFOpenL().
Returns
0 on success or -1 on error.

◆ VSIFGetNativeFileDescriptorL()

void CPL_DLL* 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
fpfile handle opened with VSIFOpenL().
Returns
the native file descriptor, or NULL.

◆ VSIFGetRangeStatusL()

VSIRangeStatus CPL_DLL 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
fpfile handle opened with VSIFOpenL().
nOffsetoffset of the start of the extent.
nLengthextent length.
Returns
extent status: VSI_RANGE_STATUS_UNKNOWN, VSI_RANGE_STATUS_DATA or VSI_RANGE_STATUS_HOLE
Since
GDAL 2.2

◆ VSIFileFromMemBuffer()

VSILFILE CPL_DLL* 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
pszFilenamethe filename to be created.
pabyDatathe data buffer for the file.
nDataLengththe length of buffer in bytes.
bTakeOwnershipTRUE to transfer "ownership" of buffer or FALSE.
Returns
open file handle on created file (see VSIFOpenL()).

◆ VSIFOpenExL()

VSILFILE CPL_DLL* 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
pszFilenamethe file to open. UTF-8 encoded.
pszAccessaccess requested (i.e. "r", "r+", "w")
bSetErrorflag 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 CPL_DLL* 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
pszFilenamethe file to open. UTF-8 encoded.
pszAccessaccess requested (i.e. "r", "r+", "w")
Returns
NULL on failure, or the file handle.

◆ VSIFPutcL()

int CPL_DLL int CPL_DLL 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
nCharcharacter to write.
fpfile handle opened with VSIFOpenL().
Returns
1 in case of success, 0 on error.

◆ VSIFReadL()

size_t CPL_DLL 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
pBufferthe buffer into which the data should be read (at least nCount * nSize bytes in size.
nSizesize of objects to read in bytes.
nCountnumber of objects to read.
fpfile handle opened with VSIFOpenL().
Returns
number of objects successfully read.

◆ VSIFReadMultiRangeL()

int CPL_DLL 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
nRangesnumber of ranges to read.
ppDataarray of nRanges buffer into which the data should be read (ppData[i] must be at list panSizes[i] bytes).
panOffsetsarray of nRanges offsets at which the data should be read.
panSizesarray of nRanges sizes of objects to read (in bytes).
fpfile handle opened with VSIFOpenL().
Returns
0 in case of success, -1 otherwise.
Since
GDAL 1.9.0

◆ VSIFree()

void CPL_DLL VSIFree ( void *  pData)

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

◆ VSIFreeAligned()

void CPL_DLL VSIFreeAligned ( void *  ptr)

Free a buffer allocated with VSIMallocAligned().

Parameters
ptrBuffer to free.
Since
GDAL 2.2

◆ VSIFreeFilesystemPluginCallbacksStruct()

void CPL_DLL VSIFreeFilesystemPluginCallbacksStruct ( VSIFilesystemPluginCallbacksStruct poCb)

free resources allocated by VSIAllocFilesystemPluginCallbacksStruct

Since
GDAL 2.5

◆ VSIFSeekL()

int CPL_DLL 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
fpfile handle opened with VSIFOpenL().
nOffsetoffset in bytes.
nWhenceone of SEEK_SET, SEEK_CUR or SEEK_END.
Returns
0 on success or -1 one failure.

◆ VSIFTellL()

vsi_l_offset CPL_DLL 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
fpfile handle opened with VSIFOpenL().
Returns
file offset in bytes.

◆ VSIFTruncateL()

int CPL_DLL 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
fpfile handle opened with VSIFOpenL().
nNewSizenew size in bytes.
Returns
0 on success
Since
GDAL 1.9.0

◆ VSIFWriteL()

size_t CPL_DLL 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
pBufferthe buffer from which the data should be written (at least nCount * nSize bytes in size.
nSizesize of objects to read in bytes.
nCountnumber of objects to read.
fpfile handle opened with VSIFOpenL().
Returns
number of objects successfully written.

◆ VSIGetActualURL()

const char CPL_DLL* 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
pszFilenamethe 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

◆ VSIGetDiskFreeSpace()

GIntBig CPL_DLL VSIGetDiskFreeSpace ( const char *  pszDirname)

Return free disk space available on the filesystem.

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

Parameters
pszDirnamea directory of the filesystem to query.
Returns
The free space in bytes. Or -1 in case of error.
Since
GDAL 2.1

◆ VSIGetFileSystemOptions()

const char CPL_DLL* 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
pszFilenamea 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 CPL_DLL** 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 CPL_DLL* 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
pszFilenamethe name of the file to grab the buffer of.
pnDataLength(file) length returned in this variable.
bUnlinkAndSeizeTRUE to remove the file, or FALSE to leave unaltered.
Returns
pointer to memory buffer or NULL on failure.

◆ VSIGetNextDirEntry()

const VSIDIREntry CPL_DLL* 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
dirDirectory 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 CPL_DLL* 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
pszFilenamethe path of the filesystem object. UTF-8 encoded.
papszOptionslist 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 CPL_DLL VSIHasOptimizedReadMultiRange ( const char *  pszPath)

Returns if the filesystem supports efficient multi-range reading.

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

Parameters
pszPaththe 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 CPL_DLL 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
fpfile handle opened with VSIFOpenL().
pszFilenamefilename.
ppabyRetpointer to the target buffer. *ppabyRet must be freed with VSIFree()
pnSizepointer to variable to store the file size. May be NULL.
nMaxSizemaximum size of file allowed. If no limit, set to a negative value.
Returns
TRUE in case of success.
Since
GDAL 1.11

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

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

Since
GDAL 1.6.0

◆ VSIInstallHdfsHandler()

void VSIInstallHdfsHandler ( void  )

Install /vsihdfs/ file system handler (non-functional stub)

Since
GDAL 2.4.0

◆ VSIInstallMemFileHandler()

void CPL_DLL 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 );
}

◆ VSIInstallPluginHandler()

int CPL_DLL 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 2.5

◆ VSIInstallSparseFileHandler()

void CPL_DLL VSIInstallSparseFileHandler ( void  )

Install /vsisparse/ virtual file handler.

See also
/vsisparse/ documentation

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

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

Since
GDAL 1.8.0

◆ VSIInstallSubFileHandler()

void CPL_DLL VSIInstallSubFileHandler ( void  )

Install /vsisubfile/ virtual file handler.

See also
/vsisubfile/ documentation

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

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

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

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

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

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

Directory listing is available through VSIReadDir().

Since
GDAL 1.8.0

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

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

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

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

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

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

Directory listing is available through VSIReadDir().

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

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

Since
GDAL 1.6.0

◆ VSIIsCaseSensitiveFS()

int CPL_DLL 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
pszFilenamethe 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 CPL_DLL* VSIMalloc ( size_t  nSize)

Analog of malloc(). Use VSIFree() to free

◆ VSIMalloc2()

void CPL_DLL* 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.

◆ VSIMalloc2Verbose()

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

VSIMalloc2Verbose

◆ VSIMalloc3()

void CPL_DLL* 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.

◆ VSIMalloc3Verbose()

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

VSIMalloc3Verbose

◆ VSIMallocAligned()

void CPL_DLL* VSIMallocAligned ( size_t  nAlignment,
size_t  nSize 
)

Allocates a buffer with an alignment constraint.

The return value must be freed with VSIFreeAligned().

Parameters
nAlignmentMust be a power of 2, multiple of sizeof(void*), and lesser than 256.
nSizeSize of the buffer to allocate.
Returns
a buffer aligned on nAlignment and of size nSize, or NULL
Since
GDAL 2.2

◆ VSIMallocAlignedAuto()

void CPL_DLL* 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
nSizeSize of the buffer to allocate.
Returns
an aligned buffer of size nSize, or NULL
Since
GDAL 2.2

◆ VSIMallocAlignedAutoVerbose()

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

◆ VSIMallocVerbose()

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

VSIMallocVerbose

◆ VSIMkdir()

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

Create a directory.

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

Analog of the POSIX mkdir() function.

Parameters
pszPathnamethe path to the directory to create. UTF-8 encoded.
modethe permissions mode.
Returns
0 on success or -1 on an error.

◆ VSIMkdirRecursive()

int CPL_DLL VSIMkdirRecursive ( const char *  pszPathname,
long  mode 
)

Create a directory and all its ancestors.

Parameters
pszPathnamethe path to the directory to create. UTF-8 encoded.
modethe permissions mode.
Returns
0 on success or -1 on an error.
Since
GDAL 2.3

◆ VSIOpenDir()

VSIDIR CPL_DLL* 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/ and /vsiaz/, 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
pszPaththe relative, or absolute path of a directory to read. UTF-8 encoded.
nRecurseDepth0 means do not recurse in subdirectories, 1 means recurse only in the first level of subdirectories, etc. -1 means unlimited recursion level
papszOptionsNULL terminated list of options, or NULL.
Returns
a handle, or NULL in case of error
Since
GDAL 2.4

◆ VSIOverwriteFile()

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

Overwrite an existing file with content from another one.

Parameters
fpTargetfile handle opened with VSIFOpenL() with "rb+" flag.
pszSourceFilenamesource filename
Returns
TRUE in case of success.
Since
GDAL 3.1

◆ VSIReadDir()

char CPL_DLL** 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
pszPaththe 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 CPL_DLL** 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
pszPaththe relative, or absolute path of a directory to read. UTF-8 encoded.
nMaxFilesmaximum 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 CPL_DLL** 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
pszPathInthe 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 CPL_DLL* VSIRealloc ( void *  pData,
size_t  nNewSize 
)

Analog of realloc(). Use VSIFree() to free

◆ VSIReallocVerbose()

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

VSIReallocVerbose

◆ VSIRename()

int CPL_DLL 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
oldpaththe name of the file to be renamed. UTF-8 encoded.
newpaththe name the file should be given. UTF-8 encoded.
Returns
0 on success or -1 on an error.

◆ VSIRewindL()

void CPL_DLL 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
fpfile handle opened with VSIFOpenL().

◆ VSIRmdir()

int CPL_DLL 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
pszDirnamethe path of the directory to be deleted. UTF-8 encoded.
Returns
0 on success or -1 on an error.

◆ VSIRmdirRecursive()

int CPL_DLL VSIRmdirRecursive ( const char *  pszDirname)

Delete a directory recursively.

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

Returns
0 on success or -1 on an error.
Since
GDAL 2.3

◆ VSIStatExL()

int CPL_DLL 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
pszFilenamethe path of the filesystem object to be queried. UTF-8 encoded.
psStatBufthe structure to load with information.
nFlags0 to get all information, or VSI_STAT_EXISTS_FLAG, VSI_STAT_NATURE_FLAG or VSI_STAT_SIZE_FLAG, or a combination of those to get partial info.
Returns
0 on success or -1 on an error.
Since
GDAL 1.8.0

◆ VSIStatL()

int CPL_DLL 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
pszFilenamethe path of the filesystem object to be queried. UTF-8 encoded.
psStatBufthe structure to load with information.
Returns
0 on success or -1 on an error.

◆ VSIStdoutSetRedirection()

void CPL_DLL VSIStdoutSetRedirection ( VSIWriteFunction  pFct,
FILE *  stream 
)

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

Parameters
pFctFunction with same signature as fwrite()
streamFile handle on which to output. Passed to pFct.
Since
GDAL 2.0

◆ VSIStrdup()

char CPL_DLL* VSIStrdup ( const char *  pszString)

Analog of strdup(). Use VSIFree() to free

◆ VSIStrdupVerbose()

char CPL_DLL* VSIStrdupVerbose ( const char *  pszStr,
const char *  pszFile,
int  nLine 
)

VSIStrdupVerbose

◆ VSIStrerror()

char CPL_DLL* VSIStrerror ( int  nErrno)

Return the error string corresponding to the error number. Do not free it

◆ VSISupportsSparseFiles()

int CPL_DLL 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
pszPaththe 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 CPL_DLL 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.

Note: currently only implemented efficiently for local filesystem <--> remote filesystem.

Similarly to rsync behaviour, 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
pszSourceSource file or directory. UTF-8 encoded.
pszTargetTarget file or direcotry. UTF-8 encoded.
papszOptionsNull terminated list of options, or NULL. Currently accepted options are:
  • RECURSIVE=NO (the default is YES)
  • SYNC_STRATEGY=TIMESTAMP/ETAG. 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.

pProgressFuncProgress callback, or NULL.
pProgressDataUser data of progress callback, or NULL.
ppapszOutputsUnused. Should be set to NULL for now.
Returns
TRUE on success or FALSE on an error.
Since
GDAL 2.4

◆ VSIUnlink()

int CPL_DLL 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
pszFilenamethe path of the file to be deleted. UTF-8 encoded.
Returns
0 on success or -1 on an error.
GByte
unsigned char GByte
Definition: cpl_port.h:215
VSIUnlink
int CPL_DLL VSIUnlink(const char *pszFilename)
Delete a file.
Definition: cpl_vsil.cpp:498
VSIFileFromMemBuffer
VSILFILE CPL_DLL * VSIFileFromMemBuffer(const char *pszFilename, GByte *pabyData, vsi_l_offset nDataLength, int bTakeOwnership) CPL_WARN_UNUSED_RESULT
Create memory "file" from a buffer.
Definition: cpl_vsi_mem.cpp:898
VSIGetMemFileBuffer
GByte CPL_DLL * VSIGetMemFileBuffer(const char *pszFilename, vsi_l_offset *pnDataLength, int bUnlinkAndSeize)
Fetch buffer underlying memory file.
Definition: cpl_vsi_mem.cpp:959
vsi_l_offset
GUIntBig vsi_l_offset
Definition: cpl_vsi.h:140
VSIFCloseL
int CPL_DLL VSIFCloseL(VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
Close file.
Definition: cpl_vsil.cpp:1472