OGR
cpl_vsi.h
Go to the documentation of this file.
1 /******************************************************************************
2  * $Id: cpl_vsi.h 28476 2015-02-13 14:40:11Z rouault $
3  *
4  * Project: CPL - Common Portability Library
5  * Author: Frank Warmerdam, warmerdam@pobox.com
6  * Purpose: Include file defining Virtual File System (VSI) functions, a
7  * layer over POSIX file and other system services.
8  *
9  ******************************************************************************
10  * Copyright (c) 1998, Frank Warmerdam
11  * Copyright (c) 2008-2014, Even Rouault <even dot rouault at mines-paris dot org>
12  *
13  * Permission is hereby granted, free of charge, to any person obtaining a
14  * copy of this software and associated documentation files (the "Software"),
15  * to deal in the Software without restriction, including without limitation
16  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
17  * and/or sell copies of the Software, and to permit persons to whom the
18  * Software is furnished to do so, subject to the following conditions:
19  *
20  * The above copyright notice and this permission notice shall be included
21  * in all copies or substantial portions of the Software.
22  *
23  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
24  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
25  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
26  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
28  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
29  * DEALINGS IN THE SOFTWARE.
30  ****************************************************************************/
31 
32 #ifndef CPL_VSI_H_INCLUDED
33 #define CPL_VSI_H_INCLUDED
34 
35 #include "cpl_port.h"
55 /* -------------------------------------------------------------------- */
56 /* We need access to ``struct stat''. */
57 /* -------------------------------------------------------------------- */
58 
59 /* Unix */
60 #if !defined(_WIN32) && !defined(_WIN32_WCE)
61 # include <unistd.h>
62 #endif
63 
64 /* Windows */
65 #if !defined(macos_pre10) && !defined(_WIN32_WCE)
66 # include <sys/stat.h>
67 #endif
68 
69 /* Windows CE */
70 #if defined(_WIN32_WCE)
71 # include <wce_stat.h>
72 #endif
73 
74 CPL_C_START
75 
76 /* ==================================================================== */
77 /* stdio file access functions. These may not support large */
78 /* files, and don't necessarily go through the virtualization */
79 /* API. */
80 /* ==================================================================== */
81 
82 FILE CPL_DLL * VSIFOpen( const char *, const char * ) CPL_WARN_UNUSED_RESULT;
83 int CPL_DLL VSIFClose( FILE * );
84 int CPL_DLL VSIFSeek( FILE *, long, int );
85 long CPL_DLL VSIFTell( FILE * );
86 void CPL_DLL VSIRewind( FILE * );
87 void CPL_DLL VSIFFlush( FILE * );
88 
89 size_t CPL_DLL VSIFRead( void *, size_t, size_t, FILE * );
90 size_t CPL_DLL VSIFWrite( const void *, size_t, size_t, FILE * );
91 char CPL_DLL *VSIFGets( char *, int, FILE * );
92 int CPL_DLL VSIFPuts( const char *, FILE * );
93 int CPL_DLL VSIFPrintf( FILE *, const char *, ... ) CPL_PRINT_FUNC_FORMAT(2, 3);
94 
95 int CPL_DLL VSIFGetc( FILE * );
96 int CPL_DLL VSIFPutc( int, FILE * );
97 int CPL_DLL VSIUngetc( int, FILE * );
98 int CPL_DLL VSIFEof( FILE * );
99 
100 /* ==================================================================== */
101 /* VSIStat() related. */
102 /* ==================================================================== */
103 
104 typedef struct stat VSIStatBuf;
105 int CPL_DLL VSIStat( const char *, VSIStatBuf * );
106 
107 #ifdef _WIN32
108 # define VSI_ISLNK(x) ( 0 ) /* N/A on Windows */
109 # define VSI_ISREG(x) ((x) & S_IFREG)
110 # define VSI_ISDIR(x) ((x) & S_IFDIR)
111 # define VSI_ISCHR(x) ((x) & S_IFCHR)
112 # define VSI_ISBLK(x) ( 0 ) /* N/A on Windows */
113 #else
114 # define VSI_ISLNK(x) S_ISLNK(x)
115 # define VSI_ISREG(x) S_ISREG(x)
116 # define VSI_ISDIR(x) S_ISDIR(x)
117 # define VSI_ISCHR(x) S_ISCHR(x)
118 # define VSI_ISBLK(x) S_ISBLK(x)
119 #endif
120 
121 /* ==================================================================== */
122 /* 64bit stdio file access functions. If we have a big size */
123 /* defined, then provide protypes for the large file API, */
124 /* otherwise redefine to use the regular api. */
125 /* ==================================================================== */
126 typedef GUIntBig vsi_l_offset;
127 
128 /* Make VSIL_STRICT_ENFORCE active in DEBUG builds */
129 #ifdef DEBUG
130 #define VSIL_STRICT_ENFORCE
131 #endif
132 
133 #ifdef VSIL_STRICT_ENFORCE
134 typedef struct _VSILFILE VSILFILE;
135 #else
136 typedef FILE VSILFILE;
137 #endif
138 
139 VSILFILE CPL_DLL * VSIFOpenL( const char *, const char * ) CPL_WARN_UNUSED_RESULT;
140 int CPL_DLL VSIFCloseL( VSILFILE * );
141 int CPL_DLL VSIFSeekL( VSILFILE *, vsi_l_offset, int );
142 vsi_l_offset CPL_DLL VSIFTellL( VSILFILE * );
143 void CPL_DLL VSIRewindL( VSILFILE * );
144 size_t CPL_DLL VSIFReadL( void *, size_t, size_t, VSILFILE * );
145 int CPL_DLL VSIFReadMultiRangeL( int nRanges, void ** ppData, const vsi_l_offset* panOffsets, const size_t* panSizes, VSILFILE * );
146 size_t CPL_DLL VSIFWriteL( const void *, size_t, size_t, VSILFILE * );
147 int CPL_DLL VSIFEofL( VSILFILE * );
148 int CPL_DLL VSIFTruncateL( VSILFILE *, vsi_l_offset );
149 int CPL_DLL VSIFFlushL( VSILFILE * );
150 int CPL_DLL VSIFPrintfL( VSILFILE *, const char *, ... ) CPL_PRINT_FUNC_FORMAT(2, 3);
151 int CPL_DLL VSIFPutcL( int, VSILFILE * );
152 
153 int CPL_DLL VSIIngestFile( VSILFILE* fp,
154  const char* pszFilename,
155  GByte** ppabyRet,
156  vsi_l_offset* pnSize,
157  GIntBig nMaxSize );
158 
159 #if defined(VSI_STAT64_T)
160 typedef struct VSI_STAT64_T VSIStatBufL;
161 #else
162 #define VSIStatBufL VSIStatBuf
163 #endif
164 
165 int CPL_DLL VSIStatL( const char *, VSIStatBufL * );
166 
167 #define VSI_STAT_EXISTS_FLAG 0x1
168 #define VSI_STAT_NATURE_FLAG 0x2
169 #define VSI_STAT_SIZE_FLAG 0x4
170 
171 int CPL_DLL VSIStatExL( const char * pszFilename, VSIStatBufL * psStatBuf, int nFlags );
172 
173 int CPL_DLL VSIIsCaseSensitiveFS( const char * pszFilename );
174 
175 void CPL_DLL *VSIFGetNativeFileDescriptorL( VSILFILE* );
176 
177 /* ==================================================================== */
178 /* Memory allocation */
179 /* ==================================================================== */
180 
181 void CPL_DLL *VSICalloc( size_t, size_t ) CPL_WARN_UNUSED_RESULT;
182 void CPL_DLL *VSIMalloc( size_t ) CPL_WARN_UNUSED_RESULT;
183 void CPL_DLL VSIFree( void * );
184 void CPL_DLL *VSIRealloc( void *, size_t ) CPL_WARN_UNUSED_RESULT;
185 char CPL_DLL *VSIStrdup( const char * ) CPL_WARN_UNUSED_RESULT;
186 
194 void CPL_DLL *VSIMalloc2( size_t nSize1, size_t nSize2 ) CPL_WARN_UNUSED_RESULT;
195 
203 void CPL_DLL *VSIMalloc3( size_t nSize1, size_t nSize2, size_t nSize3 ) CPL_WARN_UNUSED_RESULT;
204 
205 GIntBig CPL_DLL CPLGetPhysicalRAM(void);
206 GIntBig CPL_DLL CPLGetUsablePhysicalRAM(void);
207 
208 /* ==================================================================== */
209 /* Other... */
210 /* ==================================================================== */
211 
212 #define CPLReadDir VSIReadDir
213 char CPL_DLL **VSIReadDir( const char * );
214 char CPL_DLL **VSIReadDirRecursive( const char *pszPath );
215 int CPL_DLL VSIMkdir( const char * pathname, long mode );
216 int CPL_DLL VSIRmdir( const char * pathname );
217 int CPL_DLL VSIUnlink( const char * pathname );
218 int CPL_DLL VSIRename( const char * oldpath, const char * newpath );
219 char CPL_DLL *VSIStrerror( int );
220 
221 /* ==================================================================== */
222 /* Install special file access handlers. */
223 /* ==================================================================== */
224 void CPL_DLL VSIInstallMemFileHandler(void);
225 void CPL_DLL VSIInstallLargeFileHandler(void);
226 void CPL_DLL VSIInstallSubFileHandler(void);
227 void VSIInstallCurlFileHandler(void);
229 void VSIInstallGZipFileHandler(void); /* No reason to export that */
230 void VSIInstallZipFileHandler(void); /* No reason to export that */
231 void VSIInstallStdinHandler(void); /* No reason to export that */
232 void VSIInstallStdoutHandler(void); /* No reason to export that */
233 void CPL_DLL VSIInstallSparseFileHandler(void);
234 void VSIInstallTarFileHandler(void); /* No reason to export that */
235 void CPL_DLL VSICleanupFileManager(void);
236 
237 VSILFILE CPL_DLL *VSIFileFromMemBuffer( const char *pszFilename,
238  GByte *pabyData,
239  vsi_l_offset nDataLength,
240  int bTakeOwnership );
241 GByte CPL_DLL *VSIGetMemFileBuffer( const char *pszFilename,
242  vsi_l_offset *pnDataLength,
243  int bUnlinkAndSeize );
244 
245 typedef size_t (*VSIWriteFunction)(const void* ptr, size_t size, size_t nmemb, FILE* stream);
246 void CPL_DLL VSIStdoutSetRedirection( VSIWriteFunction pFct, FILE* stream );
247 
248 /* ==================================================================== */
249 /* Time quering. */
250 /* ==================================================================== */
251 
252 unsigned long CPL_DLL VSITime( unsigned long * );
253 const char CPL_DLL *VSICTime( unsigned long );
254 struct tm CPL_DLL *VSIGMTime( const time_t *pnTime,
255  struct tm *poBrokenTime );
256 struct tm CPL_DLL *VSILocalTime( const time_t *pnTime,
257  struct tm *poBrokenTime );
258 
259 /* -------------------------------------------------------------------- */
260 /* the following can be turned on for detailed logging of */
261 /* almost all IO calls. */
262 /* -------------------------------------------------------------------- */
263 #ifdef VSI_DEBUG
264 
265 #ifndef DEBUG
266 # define DEBUG
267 #endif
268 
269 #include "cpl_error.h"
270 
271 #define VSIDebug4(f,a1,a2,a3,a4) CPLDebug( "VSI", f, a1, a2, a3, a4 );
272 #define VSIDebug3( f, a1, a2, a3 ) CPLDebug( "VSI", f, a1, a2, a3 );
273 #define VSIDebug2( f, a1, a2 ) CPLDebug( "VSI", f, a1, a2 );
274 #define VSIDebug1( f, a1 ) CPLDebug( "VSI", f, a1 );
275 #else
276 #define VSIDebug4( f, a1, a2, a3, a4 ) {}
277 #define VSIDebug3( f, a1, a2, a3 ) {}
278 #define VSIDebug2( f, a1, a2 ) {}
279 #define VSIDebug1( f, a1 ) {}
280 #endif
281 
282 CPL_C_END
283 
284 #endif /* ndef CPL_VSI_H_INCLUDED */
VSILFILE * VSIFOpenL(const char *, const char *)
Open file.
Definition: cpl_vsil.cpp:508
int VSIMkdir(const char *pathname, long mode)
Create a directory.
Definition: cpl_vsil.cpp:266
GIntBig CPLGetPhysicalRAM(void)
Definition: cpl_vsisimple.cpp:957
char ** VSIReadDir(const char *)
Read names in a directory.
Definition: cpl_vsil.cpp:63
int VSIRename(const char *oldpath, const char *newpath)
Rename a file.
Definition: cpl_vsil.cpp:325
int VSIIngestFile(VSILFILE *fp, const char *pszFilename, GByte **ppabyRet, vsi_l_offset *pnSize, GIntBig nMaxSize)
Ingest a file into memory.
Definition: cpl_vsil.cpp:877
void * VSIFGetNativeFileDescriptorL(VSILFILE *)
Returns the "native" file descriptor for the virtual handle.
Definition: cpl_vsil.cpp:1034
size_t VSIFReadL(void *, size_t, size_t, VSILFILE *)
Read bytes from file.
Definition: cpl_vsil.cpp:673
void VSIStdoutSetRedirection(VSIWriteFunction pFct, FILE *stream)
Definition: cpl_vsil_stdout.cpp:57
GIntBig CPLGetUsablePhysicalRAM(void)
Definition: cpl_vsisimple.cpp:1025
int VSIStatL(const char *, VSIStatBufL *)
Get filesystem object info.
Definition: cpl_vsil.cpp:387
void VSIInstallStdoutHandler(void)
Install /vsistdout/ file system handler.
Definition: cpl_vsil_stdout.cpp:414
void VSIInstallSubFileHandler(void)
Definition: cpl_vsil_subfile.cpp:459
void VSIInstallCurlStreamingFileHandler(void)
Install /vsicurl_streaming/ HTTP/FTP file system handler (requires libcurl)
Definition: cpl_vsil_curl_streaming.cpp:1463
void VSIInstallStdinHandler(void)
Install /vsistdin/ file system handler.
Definition: cpl_vsil_stdin.cpp:393
int VSIFTruncateL(VSILFILE *, vsi_l_offset)
Truncate/expand the file to the specified size.
Definition: cpl_vsil.cpp:798
int VSIFFlushL(VSILFILE *)
Flush pending writes to disk.
Definition: cpl_vsil.cpp:641
VSILFILE * VSIFileFromMemBuffer(const char *pszFilename, GByte *pabyData, vsi_l_offset nDataLength, int bTakeOwnership)
Create memory "file" from a buffer.
Definition: cpl_vsi_mem.cpp:861
void VSIInstallTarFileHandler(void)
Install /vsitar/ file system handler.
Definition: cpl_vsil_tar.cpp:334
void VSIInstallZipFileHandler(void)
Install ZIP file system handler.
Definition: cpl_vsil_gzip.cpp:2389
int VSIIsCaseSensitiveFS(const char *pszFilename)
Returns if the filenames of the filesystem are case sensitive.
Definition: cpl_vsil.cpp:470
int VSIFPrintfL(VSILFILE *, const char *,...)
Formatted write to file.
Definition: cpl_vsil.cpp:824
void VSIInstallSparseFileHandler(void)
Definition: cpl_vsil_sparsefile.cpp:570
int VSIFReadMultiRangeL(int nRanges, void **ppData, const vsi_l_offset *panOffsets, const size_t *panSizes, VSILFILE *)
Read several ranges of bytes from file.
Definition: cpl_vsil.cpp:709
int VSIStatExL(const char *pszFilename, VSIStatBufL *psStatBuf, int nFlags)
Get filesystem object info.
Definition: cpl_vsil.cpp:424
void VSIInstallGZipFileHandler(void)
Install GZip file system handler.
Definition: cpl_vsil_gzip.cpp:1590
int VSIFEofL(VSILFILE *)
Test for end of file.
Definition: cpl_vsil.cpp:771
vsi_l_offset VSIFTellL(VSILFILE *)
Tell current file offset.
Definition: cpl_vsil.cpp:603
int VSIFSeekL(VSILFILE *, vsi_l_offset, int)
Seek to requested offset.
Definition: cpl_vsil.cpp:575
int VSIRmdir(const char *pathname)
Delete a directory.
Definition: cpl_vsil.cpp:354
void VSIInstallCurlFileHandler(void)
Install /vsicurl/ HTTP/FTP file system handler (requires libcurl)
Definition: cpl_vsil_curl.cpp:2686
void * VSIMalloc3(size_t nSize1, size_t nSize2, size_t nSize3)
Definition: cpl_vsisimple.cpp:817
int VSIUnlink(const char *pathname)
Delete a file.
Definition: cpl_vsil.cpp:294
int VSIFCloseL(VSILFILE *)
Close file.
Definition: cpl_vsil.cpp:540
void VSIInstallMemFileHandler(void)
Install "memory" file system handler.
Definition: cpl_vsi_mem.cpp:831
void * VSIMalloc2(size_t nSize1, size_t nSize2)
Definition: cpl_vsisimple.cpp:785
GByte * VSIGetMemFileBuffer(const char *pszFilename, vsi_l_offset *pnDataLength, int bUnlinkAndSeize)
Fetch buffer underlying memory file.
Definition: cpl_vsi_mem.cpp:917
size_t VSIFWriteL(const void *, size_t, size_t, VSILFILE *)
Write bytes to file.
Definition: cpl_vsil.cpp:742
char ** VSIReadDirRecursive(const char *pszPath)
Read names in a directory recursively.
Definition: cpl_vsil.cpp:106

Generated for GDAL by doxygen 1.8.10.