Defines | Typedefs | Functions

cpl_vsi.h File Reference

Standard C Covers. More...

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

Go to the source code of this file.

Defines

#define VSI_ISLNK(x)   S_ISLNK(x)
#define VSI_ISREG(x)   S_ISREG(x)
#define VSI_ISDIR(x)   S_ISDIR(x)
#define VSI_ISCHR(x)   S_ISCHR(x)
#define VSI_ISBLK(x)   S_ISBLK(x)
#define VSI_STAT_EXISTS_FLAG   0x1
#define VSI_STAT_NATURE_FLAG   0x2
#define VSI_STAT_SIZE_FLAG   0x4
#define CPLReadDir   VSIReadDir
#define VSIDebug4(f, a1, a2, a3, a4)   {}
#define VSIDebug3(f, a1, a2, a3)   {}
#define VSIDebug2(f, a1, a2)   {}
#define VSIDebug1(f, a1)   {}

Typedefs

typedef struct stat VSIStatBuf
typedef GUIntBig vsi_l_offset
typedef FILE VSILFILE
typedef struct VSI_STAT64_T VSIStatBufL

Functions

FILE * VSIFOpen (const char *, const char *) CPL_WARN_UNUSED_RESULT
int VSIFClose (FILE *)
int VSIFSeek (FILE *, long, int)
long VSIFTell (FILE *)
void VSIRewind (FILE *)
void VSIFFlush (FILE *)
size_t VSIFRead (void *, size_t, size_t, FILE *)
size_t VSIFWrite (const void *, size_t, size_t, FILE *)
char * VSIFGets (char *, int, FILE *)
int VSIFPuts (const char *, FILE *)
int VSIFPrintf (FILE *, const char *,...)
int VSIFGetc (FILE *)
int VSIFPutc (int, FILE *)
int VSIUngetc (int, FILE *)
int VSIFEof (FILE *)
int VSIStat (const char *, VSIStatBuf *)
VSILFILE * VSIFOpenL (const char *, const char *) CPL_WARN_UNUSED_RESULT
 Open 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 *)
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.
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 *)
int VSIIngestFile (VSILFILE *fp, const char *pszFilename, GByte **ppabyRet, vsi_l_offset *pnSize, GIntBig nMaxSize)
 Ingest a file into memory.
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.
void * VSIFGetNativeFileDescriptorL (VSILFILE *)
 Returns the "native" file descriptor for the virtual handle.
void * VSICalloc (size_t, size_t) CPL_WARN_UNUSED_RESULT
void * VSIMalloc (size_t) CPL_WARN_UNUSED_RESULT
void VSIFree (void *)
void * VSIRealloc (void *, size_t) CPL_WARN_UNUSED_RESULT
char * VSIStrdup (const char *) CPL_WARN_UNUSED_RESULT
void * VSIMalloc2 (size_t nSize1, size_t nSize2) CPL_WARN_UNUSED_RESULT
 VSIMalloc2 allocates (nSize1 * nSize2) bytes.
void * VSIMalloc3 (size_t nSize1, size_t nSize2, size_t nSize3) CPL_WARN_UNUSED_RESULT
 VSIMalloc3 allocates (nSize1 * nSize2 * nSize3) bytes.
char ** VSIReadDir (const char *)
 Read names in a directory.
char ** VSIReadDirRecursive (const char *pszPath)
 Read names in a directory recursively.
int VSIMkdir (const char *pathname, long mode)
 Create a directory.
int VSIRmdir (const char *pathname)
 Delete a directory.
int VSIUnlink (const char *pathname)
 Delete a file.
int VSIRename (const char *oldpath, const char *newpath)
 Rename a file.
char * VSIStrerror (int)
void VSIInstallMemFileHandler (void)
 Install "memory" file system handler.
void VSIInstallLargeFileHandler (void)
void VSIInstallSubFileHandler (void)
 Install /vsisubfile/ virtual file handler.
void VSIInstallCurlFileHandler (void)
 Install /vsicurl/ HTTP/FTP file system handler (requires libcurl).
void VSIInstallCurlStreamingFileHandler (void)
 Install /vsicurl_streaming/ HTTP/FTP file system handler (requires libcurl).
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 VSIInstallStdoutHandler (void)
 Install /vsistdout/ file system handler.
void VSIInstallSparseFileHandler (void)
 Install /vsisparse/ virtual file handler.
void VSIInstallTarFileHandler (void)
 Install /vsitar/ file system handler.
void VSICleanupFileManager (void)
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.
unsigned long VSITime (unsigned long *)
const char * VSICTime (unsigned long)
struct tm * VSIGMTime (const time_t *pnTime, struct tm *poBrokenTime)
struct tm * VSILocalTime (const time_t *pnTime, struct tm *poBrokenTime)

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.

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


Function Documentation

int VSIFCloseL ( VSILFILE *  fp  ) 

Close file.

This function closes the indicated file.

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

Analog of the POSIX fclose() function.

Parameters:
fp file handle opened with VSIFOpenL().
Returns:
0 on success or -1 on failure.
int VSIFEofL ( VSILFILE *  fp  ) 

Test for end of file.

Returns TRUE (non-zero) if an end-of-file condition occured during the previous read operation. The end-of-file flag is cleared by a successfull VSIFSeekL() call.

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

Analog of the POSIX feof() call.

Parameters:
fp file handle opened with VSIFOpenL().
Returns:
TRUE if at EOF else FALSE.
int VSIFFlushL ( VSILFILE *  fp  ) 

Flush pending writes to disk.

For files in write or update mode and on filesystem types where it is applicable, all pending output on the file is flushed to the physical disk.

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

Analog of the POSIX fflush() call.

Parameters:
fp file handle opened with VSIFOpenL().
Returns:
0 on success or -1 on error.
void* VSIFGetNativeFileDescriptorL ( VSILFILE *  fp  ) 

Returns the "native" file descriptor for the virtual handle.

This will only return a non-NULL value for "real" files handled by the operating system (to be opposed to GDAL virtual file systems).

On POSIX systems, this will be a integer value ("fd") cast as a void*. On Windows systems, this will be the HANDLE.

Parameters:
fp file handle opened with VSIFOpenL().
Returns:
the native file descriptor, or NULL.
VSILFILE* VSIFileFromMemBuffer ( const char *  pszFilename,
GByte *  pabyData,
vsi_l_offset  nDataLength,
int  bTakeOwnership 
)

Create memory "file" from a buffer.

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

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

Parameters:
pszFilename the filename to be created.
pabyData the data buffer for the file.
nDataLength the length of buffer in bytes.
bTakeOwnership TRUE to transfer "ownership" of buffer or FALSE.
Returns:
open file handle on created file (see VSIFOpenL()).
VSILFILE* 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, retoring the pre-1.8.0 behavior of VSIFOpenL().

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

Analog of the POSIX fopen() function.

Parameters:
pszFilename the file to open. UTF-8 encoded.
pszAccess access requested (ie. "r", "r+", "w".
Returns:
NULL on failure, or the file handle.
int VSIFPrintfL ( VSILFILE *  fp,
const char *  pszFormat,
  ... 
)

Formatted write to file.

Provides fprintf() style formatted output to a VSI*L file. This formats an internal buffer which is written using VSIFWriteL().

Analog of the POSIX fprintf() call.

Parameters:
fp file handle opened with VSIFOpenL().
pszFormat the printf style format string.
Returns:
the number of bytes written or -1 on an error.
size_t VSIFReadL ( void *  pBuffer,
size_t  nSize,
size_t  nCount,
VSILFILE *  fp 
)

Read bytes from file.

Reads nCount objects of nSize bytes from the indicated file at the current offset into the indicated buffer.

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

Analog of the POSIX fread() call.

Parameters:
pBuffer the buffer into which the data should be read (at least nCount * nSize bytes in size.
nSize size of objects to read in bytes.
nCount number of objects to read.
fp file handle opened with VSIFOpenL().
Returns:
number of objects successfully read.
int VSIFReadMultiRangeL ( int  nRanges,
void **  ppData,
const vsi_l_offset *  panOffsets,
const size_t *  panSizes,
VSILFILE *  fp 
)

Read several ranges of bytes from file.

Reads nRanges objects of panSizes[i] bytes from the indicated file at the offset panOffsets[i] into the buffer ppData[i].

Ranges must be sorted in ascending start offset, and must not overlap each other.

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

Parameters:
nRanges number of ranges to read.
ppData array of nRanges buffer into which the data should be read (ppData[i] must be at list panSizes[i] bytes).
panOffsets array of nRanges offsets at which the data should be read.
panSizes array of nRanges sizes of objects to read (in bytes).
fp file handle opened with VSIFOpenL().
Returns:
0 in case of success, -1 otherwise.
Since:
GDAL 1.9.0
int VSIFSeekL ( VSILFILE *  fp,
vsi_l_offset  nOffset,
int  nWhence 
)

Seek to requested offset.

Seek to the desired offset (nOffset) in the indicated file.

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

Analog of the POSIX fseek() call.

Parameters:
fp file handle opened with VSIFOpenL().
nOffset offset in bytes.
nWhence one of SEEK_SET, SEEK_CUR or SEEK_END.
Returns:
0 on success or -1 one failure.
vsi_l_offset VSIFTellL ( VSILFILE *  fp  ) 

Tell current file offset.

Returns the current file read/write offset in bytes from the beginning of the file.

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

Analog of the POSIX ftell() call.

Parameters:
fp file handle opened with VSIFOpenL().
Returns:
file offset in bytes.
int VSIFTruncateL ( VSILFILE *  fp,
vsi_l_offset  nNewSize 
)

Truncate/expand the file to the specified size.

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

Analog of the POSIX ftruncate() call.

Parameters:
fp file handle opened with VSIFOpenL().
nNewSize new size in bytes.
Returns:
0 on success
Since:
GDAL 1.9.0
size_t VSIFWriteL ( const void *  pBuffer,
size_t  nSize,
size_t  nCount,
VSILFILE *  fp 
)

Write bytes to file.

Writess nCount objects of nSize bytes to the indicated file at the current offset into the indicated buffer.

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

Analog of the POSIX fwrite() call.

Parameters:
pBuffer the buffer from which the data should be written (at least nCount * nSize bytes in size.
nSize size of objects to read in bytes.
nCount number of objects to read.
fp file handle opened with VSIFOpenL().
Returns:
number of objects successfully written.
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 existance.

Parameters:
pszFilename the name of the file to grab the buffer of.
pnDataLength (file) length returned in this variable.
bUnlinkAndSeize TRUE to remove the file, or FALSE to leave unaltered.
Returns:
pointer to memory buffer or NULL on failure.
int VSIIngestFile ( VSILFILE *  fp,
const char *  pszFilename,
GByte **  ppabyRet,
vsi_l_offset *  pnSize,
GIntBig  nMaxSize 
)

Ingest a file into memory.

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

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

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

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

Parameters:
fp file handle opened with VSIFOpenL().
pszFilename filename.
ppabyRet pointer to the target buffer. *ppabyRet must be freed with VSIFree()
pnSize pointer to variable to store the file size. May be NULL.
nMaxSize maximum size of file allowed. If no limit, set to a negative value.
Returns:
TRUE in case of success.
Since:
GDAL 1.11
void VSIInstallCurlFileHandler ( void   ) 

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

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

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

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

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

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

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

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

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

Since:
GDAL 1.8.0
void VSIInstallCurlStreamingFileHandler ( void   ) 

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

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

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

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

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

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

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

Since:
GDAL 1.10
void VSIInstallGZipFileHandler ( void   ) 

Install GZip file system handler.

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

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

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

Since:
GDAL 1.6.0
void VSIInstallMemFileHandler ( void   ) 

Install "memory" file system handler.

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

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

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

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

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

Install /vsisparse/ virtual file handler.

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

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

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

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

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

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

Hopefully the values and semantics are fairly obvious.

This driver is installed by default.

void VSIInstallStdinHandler ( void   ) 

Install /vsistdin/ file system handler.

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

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

Since:
GDAL 1.8.0
void VSIInstallStdoutHandler ( void   ) 

Install /vsistdout/ file system handler.

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

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

Since:
GDAL 1.8.0
void VSIInstallSubFileHandler ( void   ) 

Install /vsisubfile/ virtual file handler.

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

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

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

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

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

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

void VSIInstallTarFileHandler ( void   ) 

Install /vsitar/ file system handler.

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

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

The syntax to open a file inside a zip 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.

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

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

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

Directory listing is available through VSIReadDir().

Since:
GDAL 1.8.0
void VSIInstallZipFileHandler ( void   ) 

Install ZIP file system handler.

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

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

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

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

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

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

Directory listing is available through VSIReadDir().

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

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

Since:
GDAL 1.6.0
int VSIIsCaseSensitiveFS ( const char *  pszFilename  ) 

Returns if the filenames of the filesystem are case sensitive.

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

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

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

Parameters:
pszFilename the path of the filesystem object to be tested. UTF-8 encoded.
Returns:
TRUE if the filenames of the filesystem are case sensitive.
Since:
GDAL 1.8.0
void* 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.

int VSIMkdir ( const char *  pszPathname,
long  mode 
)

Create a directory.

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

Analog of the POSIX mkdir() function.

Parameters:
pszPathname the path to the directory to create. UTF-8 encoded.
mode the permissions mode.
Returns:
0 on success or -1 on an error.
char** VSIReadDir ( const char *  pszPath  ) 

Read names in a directory.

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

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

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

Parameters:
pszPath the relative, or absolute path of a directory to read. UTF-8 encoded.
Returns:
The list of entries in the directory, or NULL if the directory doesn't exist. Filenames are returned in UTF-8 encoding.
char** VSIReadDirRecursive ( const char *  pszPathIn  ) 

Read names in a directory recursively.

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

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

Parameters:
pszPathIn the relative, or absolute path of a directory to read. UTF-8 encoded.
Returns:
The list of entries in the directory and subdirectories or NULL if the directory doesn't exist. Filenames are returned in UTF-8 encoding.
Since:
GDAL 1.10.0
int VSIRename ( const char *  oldpath,
const char *  newpath 
)

Rename a file.

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

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

Analog of the POSIX rename() function.

Parameters:
oldpath the name of the file to be renamed. UTF-8 encoded.
newpath the name the file should be given. UTF-8 encoded.
Returns:
0 on success or -1 on an error.
int VSIRmdir ( const char *  pszDirname  ) 

Delete a directory.

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

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

Analog of the POSIX rmdir() function.

Parameters:
pszDirname the path of the directory to be deleted. UTF-8 encoded.
Returns:
0 on success or -1 on an error.
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 the st_size (size in bytes), and st_mode (file type). This method is similar to VSIStat(), but will work on large files on systems where this requires special calls.

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

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

Parameters:
pszFilename the path of the filesystem object to be queried. UTF-8 encoded.
psStatBuf the structure to load with information.
nFlags 0 to get all information, or VSI_STAT_EXISTS_FLAG, VSI_STAT_NATURE_FLAG or VSI_STAT_SIZE_FLAG, or a combination of those to get partial info.
Returns:
0 on success or -1 on an error.
Since:
GDAL 1.8.0
int VSIStatL ( const char *  pszFilename,
VSIStatBufL *  psStatBuf 
)

Get filesystem object info.

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

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

Analog of the POSIX stat() function.

Parameters:
pszFilename the path of the filesystem object to be queried. UTF-8 encoded.
psStatBuf the structure to load with information.
Returns:
0 on success or -1 on an error.
int VSIUnlink ( const char *  pszFilename  ) 

Delete a file.

Deletes a file object from the file system.

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

Analog of the POSIX unlink() function.

Parameters:
pszFilename the path of the file to be deleted. UTF-8 encoded.
Returns:
0 on success or -1 on an error.

Generated for GDAL by doxygen 1.7.1.