Line data Source code
1 : /******************************************************************************
2 : *
3 : * Project: CPL - Common Portability Library
4 : * Author: Frank Warmerdam, warmerdam@pobox.com
5 : * Purpose: Include file defining Virtual File System (VSI) functions, a
6 : * layer over POSIX file and other system services.
7 : *
8 : ******************************************************************************
9 : * Copyright (c) 1998, Frank Warmerdam
10 : * Copyright (c) 2008-2014, Even Rouault <even dot rouault at spatialys.com>
11 : *
12 : * SPDX-License-Identifier: MIT
13 : ****************************************************************************/
14 :
15 : #ifndef CPL_VSI_H_INCLUDED
16 : #define CPL_VSI_H_INCLUDED
17 :
18 : #include "cpl_port.h"
19 : #include "cpl_progress.h"
20 :
21 : #include <stdbool.h>
22 :
23 : #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
24 : extern "C++"
25 : {
26 : #include <string>
27 : }
28 : #endif
29 :
30 : /**
31 : * \file cpl_vsi.h
32 : *
33 : * Standard C Covers
34 : *
35 : * The VSI (Virtual System Interface) functions are intended to be hookable
36 : * aliases for Standard C I/O, memory allocation and other system functions.
37 : * They are intended to allow virtualization of disk I/O so that non file data
38 : * sources can be made to appear as files, and so that additional error trapping
39 : * and reporting can be interested. The memory access API is aliased
40 : * so that special application memory management services can be used.
41 : *
42 : * It is intended that each of these functions retains exactly the same
43 : * calling pattern as the original Standard C functions they relate to.
44 : * This means we don't have to provide custom documentation, and also means
45 : * that the default implementation is very simple.
46 : */
47 :
48 : /* -------------------------------------------------------------------- */
49 : /* We need access to ``struct stat''. */
50 : /* -------------------------------------------------------------------- */
51 :
52 : /* Unix */
53 : #if !defined(_WIN32)
54 : #include <unistd.h>
55 : #endif
56 :
57 : /* Windows */
58 : #include <sys/stat.h>
59 :
60 : CPL_C_START
61 :
62 : /*! @cond Doxygen_Suppress */
63 : #ifdef ENABLE_EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
64 : #define EXPERIMENTAL_CPL_WARN_UNUSED_RESULT CPL_WARN_UNUSED_RESULT
65 : #else
66 : #define EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
67 : #endif
68 : /*! @endcond */
69 :
70 : /* ==================================================================== */
71 : /* stdio file access functions. These do not support large */
72 : /* files, and do not go through the virtualization API. */
73 : /* ==================================================================== */
74 :
75 : /*! @cond Doxygen_Suppress */
76 :
77 : FILE CPL_DLL *VSIFOpen(const char *, const char *) CPL_WARN_UNUSED_RESULT;
78 : int CPL_DLL VSIFClose(FILE *);
79 : int CPL_DLL VSIFSeek(FILE *, long, int) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
80 : long CPL_DLL VSIFTell(FILE *) CPL_WARN_UNUSED_RESULT;
81 : void CPL_DLL VSIRewind(FILE *);
82 : void CPL_DLL VSIFFlush(FILE *);
83 :
84 : size_t CPL_DLL VSIFRead(void *, size_t, size_t,
85 : FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
86 : size_t CPL_DLL VSIFWrite(const void *, size_t, size_t,
87 : FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
88 : char CPL_DLL *VSIFGets(char *, int, FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
89 : int CPL_DLL VSIFPuts(const char *, FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
90 : int CPL_DLL VSIFPrintf(FILE *, CPL_FORMAT_STRING(const char *),
91 : ...) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
92 : CPL_PRINT_FUNC_FORMAT(2, 3);
93 :
94 : int CPL_DLL VSIFGetc(FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
95 : int CPL_DLL VSIFPutc(int, FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
96 : int CPL_DLL VSIUngetc(int, FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
97 : int CPL_DLL VSIFEof(FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
98 :
99 : /*! @endcond */
100 :
101 : /* ==================================================================== */
102 : /* VSIStat() related. */
103 : /* ==================================================================== */
104 :
105 : /*! @cond Doxygen_Suppress */
106 : typedef struct stat VSIStatBuf;
107 : int CPL_DLL VSIStat(const char *, VSIStatBuf *) CPL_WARN_UNUSED_RESULT;
108 : /*! @endcond */
109 :
110 : #ifdef _WIN32
111 : #define VSI_ISLNK(x) (0) /* N/A on Windows */
112 : #define VSI_ISREG(x) ((x) & S_IFREG)
113 : #define VSI_ISDIR(x) ((x) & S_IFDIR)
114 : #define VSI_ISCHR(x) ((x) & S_IFCHR)
115 : #define VSI_ISBLK(x) (0) /* N/A on Windows */
116 : #else
117 : /** Test if the file is a symbolic link */
118 : #define VSI_ISLNK(x) S_ISLNK(x)
119 : /** Test if the file is a regular file */
120 : #define VSI_ISREG(x) S_ISREG(x)
121 : /** Test if the file is a directory */
122 : #define VSI_ISDIR(x) S_ISDIR(x)
123 : /*! @cond Doxygen_Suppress */
124 : #define VSI_ISCHR(x) S_ISCHR(x)
125 : #define VSI_ISBLK(x) S_ISBLK(x)
126 : /*! @endcond */
127 : #endif
128 :
129 : /* ==================================================================== */
130 : /* 64bit stdio file access functions. If we have a big size */
131 : /* defined, then provide prototypes for the large file API, */
132 : /* otherwise redefine to use the regular api. */
133 : /* ==================================================================== */
134 :
135 : /** Type for a file offset */
136 : typedef GUIntBig vsi_l_offset;
137 : /** Maximum value for a file offset */
138 : #define VSI_L_OFFSET_MAX GUINTBIG_MAX
139 :
140 : /** Opaque type for a FILE that implements the VSIVirtualHandle API */
141 : typedef struct VSIVirtualHandle VSILFILE;
142 :
143 : VSILFILE CPL_DLL *VSIFOpenL(const char *, const char *) CPL_WARN_UNUSED_RESULT;
144 : VSILFILE CPL_DLL *VSIFOpenExL(const char *, const char *,
145 : int) CPL_WARN_UNUSED_RESULT;
146 : VSILFILE CPL_DLL *VSIFOpenEx2L(const char *, const char *, int,
147 : CSLConstList) CPL_WARN_UNUSED_RESULT;
148 : int CPL_DLL VSIFCloseL(VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
149 : int CPL_DLL VSIFSeekL(VSILFILE *, vsi_l_offset,
150 : int) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
151 : #ifdef GDAL_COMPILATION
152 : #ifdef __cplusplus
153 :
154 : /*! @cond Doxygen_Suppress */
155 : CPL_C_END
156 :
157 : int VSIFSeekL(VSILFILE *, int &, int) = delete;
158 : int VSIFSeekL(VSILFILE *, const int &, int) = delete;
159 : int VSIFSeekL(VSILFILE *, unsigned &, int) = delete;
160 : int VSIFSeekL(VSILFILE *, const unsigned &, int) = delete;
161 :
162 907747 : inline int VSIFSeekL(VSILFILE *f, int &&nOffset, int nWhence)
163 : {
164 907747 : return VSIFSeekL(f, static_cast<vsi_l_offset>(nOffset), nWhence);
165 : }
166 :
167 : template <typename T>
168 : inline std::enable_if_t<
169 : std::is_same_v<T, uint64_t> && !std::is_same_v<uint64_t, vsi_l_offset>, int>
170 63433 : VSIFSeekL(VSILFILE *f, T nOffset, int nWhence)
171 : {
172 63433 : return VSIFSeekL(f, static_cast<vsi_l_offset>(nOffset), nWhence);
173 : }
174 :
175 : template <typename T>
176 : inline std::enable_if_t<std::is_same_v<T, size_t> &&
177 : !std::is_same_v<T, uint64_t> &&
178 : !std::is_same_v<size_t, unsigned> &&
179 : !std::is_same_v<size_t, vsi_l_offset>,
180 : int>
181 : VSIFSeekL(VSILFILE *f, T, int) = delete;
182 :
183 : CPL_C_START
184 :
185 : /*! @endcond */
186 : #endif
187 : #endif
188 : vsi_l_offset CPL_DLL VSIFTellL(VSILFILE *) CPL_WARN_UNUSED_RESULT;
189 : void CPL_DLL VSIRewindL(VSILFILE *);
190 : size_t CPL_DLL VSIFReadL(void *, size_t, size_t,
191 : VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
192 : int CPL_DLL VSIFReadMultiRangeL(int nRanges, void **ppData,
193 : const vsi_l_offset *panOffsets,
194 : const size_t *panSizes,
195 : VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
196 : size_t CPL_DLL VSIFWriteL(const void *, size_t, size_t,
197 : VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
198 : void CPL_DLL VSIFClearErrL(VSILFILE *);
199 : int CPL_DLL VSIFErrorL(VSILFILE *) CPL_WARN_UNUSED_RESULT;
200 : int CPL_DLL VSIFEofL(VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
201 : int CPL_DLL VSIFTruncateL(VSILFILE *,
202 : vsi_l_offset) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
203 : int CPL_DLL VSIFFlushL(VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
204 : int CPL_DLL VSIFPrintfL(VSILFILE *, CPL_FORMAT_STRING(const char *),
205 : ...) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
206 : CPL_PRINT_FUNC_FORMAT(2, 3);
207 : int CPL_DLL VSIFPutcL(int, VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
208 :
209 : /** Range status */
210 : typedef enum
211 : {
212 : VSI_RANGE_STATUS_UNKNOWN, /**< Unknown */
213 : VSI_RANGE_STATUS_DATA, /**< Data present */
214 : VSI_RANGE_STATUS_HOLE /**< Hole */
215 : } VSIRangeStatus;
216 :
217 : VSIRangeStatus CPL_DLL VSIFGetRangeStatusL(VSILFILE *fp, vsi_l_offset nStart,
218 : vsi_l_offset nLength);
219 :
220 : int CPL_DLL VSIIngestFile(VSILFILE *fp, const char *pszFilename,
221 : GByte **ppabyRet, vsi_l_offset *pnSize,
222 : GIntBig nMaxSize) CPL_WARN_UNUSED_RESULT;
223 :
224 : int CPL_DLL VSIOverwriteFile(VSILFILE *fpTarget, const char *pszSourceFilename)
225 : CPL_WARN_UNUSED_RESULT;
226 :
227 : #if defined(VSI_STAT64_T)
228 : /** Type for VSIStatL() */
229 : typedef struct VSI_STAT64_T VSIStatBufL;
230 : #else
231 : /** Type for VSIStatL() */
232 : #define VSIStatBufL VSIStatBuf
233 : #endif
234 :
235 : int CPL_DLL VSIStatL(const char *, VSIStatBufL *) CPL_WARN_UNUSED_RESULT;
236 :
237 : /** Flag provided to VSIStatExL() to test if the file exists */
238 : #define VSI_STAT_EXISTS_FLAG 0x1
239 : /** Flag provided to VSIStatExL() to query the nature (file/dir) of the file */
240 : #define VSI_STAT_NATURE_FLAG 0x2
241 : /** Flag provided to VSIStatExL() to query the file size */
242 : #define VSI_STAT_SIZE_FLAG 0x4
243 : /** Flag provided to VSIStatExL() to issue a VSIError in case of failure */
244 : #define VSI_STAT_SET_ERROR_FLAG 0x8
245 : /** Flag provided to VSIStatExL() to only use already cached results.
246 : * @since GDAL 3.4
247 : */
248 : #define VSI_STAT_CACHE_ONLY 0x10
249 :
250 : int CPL_DLL VSIStatExL(const char *pszFilename, VSIStatBufL *psStatBuf,
251 : int nFlags) CPL_WARN_UNUSED_RESULT;
252 :
253 : int CPL_DLL VSIIsCaseSensitiveFS(const char *pszFilename);
254 :
255 : int CPL_DLL VSISupportsSparseFiles(const char *pszPath);
256 :
257 : bool CPL_DLL VSIIsLocal(const char *pszPath);
258 :
259 : char CPL_DLL *VSIGetCanonicalFilename(const char *pszPath);
260 :
261 : bool CPL_DLL VSISupportsSequentialWrite(const char *pszPath,
262 : bool bAllowLocalTempFile);
263 :
264 : bool CPL_DLL VSISupportsRandomWrite(const char *pszPath,
265 : bool bAllowLocalTempFile);
266 :
267 : int CPL_DLL VSIHasOptimizedReadMultiRange(const char *pszPath);
268 :
269 : const char CPL_DLL *VSIGetActualURL(const char *pszFilename);
270 :
271 : char CPL_DLL *VSIGetSignedURL(const char *pszFilename,
272 : CSLConstList papszOptions);
273 :
274 : const char CPL_DLL *VSIGetFileSystemOptions(const char *pszFilename);
275 :
276 : char CPL_DLL **VSIGetFileSystemsPrefixes(void);
277 :
278 : void CPL_DLL *VSIFGetNativeFileDescriptorL(VSILFILE *);
279 :
280 : char CPL_DLL **
281 : VSIGetFileMetadata(const char *pszFilename, const char *pszDomain,
282 : CSLConstList papszOptions) CPL_WARN_UNUSED_RESULT;
283 :
284 : int CPL_DLL VSISetFileMetadata(const char *pszFilename,
285 : CSLConstList papszMetadata,
286 : const char *pszDomain,
287 : CSLConstList papszOptions);
288 :
289 : void CPL_DLL VSISetPathSpecificOption(const char *pszPathPrefix,
290 : const char *pszKey, const char *pszValue);
291 : void CPL_DLL VSIClearPathSpecificOptions(const char *pszPathPrefix);
292 : const char CPL_DLL *VSIGetPathSpecificOption(const char *pszPath,
293 : const char *pszKey,
294 : const char *pszDefault);
295 :
296 : void CPL_DLL VSISetCredential(const char *pszPathPrefix, const char *pszKey,
297 : const char *pszValue)
298 : /*! @cond Doxygen_Suppress */
299 : CPL_WARN_DEPRECATED("Use VSISetPathSpecificOption instead")
300 : /*! @endcond */
301 : ;
302 : void CPL_DLL VSIClearCredentials(const char *pszPathPrefix)
303 : /*! @cond Doxygen_Suppress */
304 : CPL_WARN_DEPRECATED("Use VSIClearPathSpecificOptions instead")
305 : /*! @endcond */
306 : ;
307 : const char CPL_DLL *VSIGetCredential(const char *pszPath, const char *pszKey,
308 : const char *pszDefault)
309 : /*! @cond Doxygen_Suppress */
310 : CPL_WARN_DEPRECATED("Use VSIGetPathSpecificOption instead")
311 : /*! @endcond */
312 : ;
313 :
314 : /* ==================================================================== */
315 : /* Memory allocation */
316 : /* ==================================================================== */
317 :
318 : void CPL_DLL *VSICalloc(size_t, size_t) CPL_WARN_UNUSED_RESULT;
319 : void CPL_DLL *VSIMalloc(size_t) CPL_WARN_UNUSED_RESULT;
320 : void CPL_DLL VSIFree(void *);
321 : void CPL_DLL *VSIRealloc(void *, size_t) CPL_WARN_UNUSED_RESULT;
322 : char CPL_DLL *VSIStrdup(const char *) CPL_WARN_UNUSED_RESULT;
323 :
324 : #if defined(__cplusplus)
325 : extern "C++"
326 : {
327 : /*! @cond Doxygen_Suppress */
328 : struct CPL_DLL VSIFreeReleaser
329 : {
330 124083 : void operator()(void *p) const
331 : {
332 124083 : VSIFree(p);
333 124083 : }
334 : };
335 :
336 : /*! @endcond */
337 : }
338 : #endif
339 :
340 : void CPL_DLL *VSIMallocAligned(size_t nAlignment,
341 : size_t nSize) CPL_WARN_UNUSED_RESULT;
342 : void CPL_DLL *VSIMallocAlignedAuto(size_t nSize) CPL_WARN_UNUSED_RESULT;
343 : void CPL_DLL VSIFreeAligned(void *ptr);
344 :
345 : void CPL_DLL *VSIMallocAlignedAutoVerbose(size_t nSize, const char *pszFile,
346 : int nLine) CPL_WARN_UNUSED_RESULT;
347 : /** VSIMallocAlignedAutoVerbose() with FILE and LINE reporting */
348 : #define VSI_MALLOC_ALIGNED_AUTO_VERBOSE(size) \
349 : VSIMallocAlignedAutoVerbose(size, __FILE__, __LINE__)
350 :
351 : /**
352 : VSIMalloc2 allocates (nSize1 * nSize2) bytes.
353 : In case of overflow of the multiplication, or if memory allocation fails, a
354 : NULL pointer is returned and a CE_Failure error is raised with CPLError().
355 : If nSize1 == 0 || nSize2 == 0, a NULL pointer will also be returned.
356 : CPLFree() or VSIFree() can be used to free memory allocated by this function.
357 : */
358 : void CPL_DLL *VSIMalloc2(size_t nSize1, size_t nSize2) CPL_WARN_UNUSED_RESULT;
359 :
360 : /**
361 : VSIMalloc3 allocates (nSize1 * nSize2 * nSize3) bytes.
362 : In case of overflow of the multiplication, or if memory allocation fails, a
363 : NULL pointer is returned and a CE_Failure error is raised with CPLError().
364 : If nSize1 == 0 || nSize2 == 0 || nSize3 == 0, a NULL pointer will also be
365 : returned. CPLFree() or VSIFree() can be used to free memory allocated by this
366 : function.
367 : */
368 : void CPL_DLL *VSIMalloc3(size_t nSize1, size_t nSize2,
369 : size_t nSize3) CPL_WARN_UNUSED_RESULT;
370 :
371 : /** VSIMallocVerbose */
372 : void CPL_DLL *VSIMallocVerbose(size_t nSize, const char *pszFile,
373 : int nLine) CPL_WARN_UNUSED_RESULT;
374 : /** VSI_MALLOC_VERBOSE */
375 : #define VSI_MALLOC_VERBOSE(size) VSIMallocVerbose(size, __FILE__, __LINE__)
376 :
377 : /** VSIMalloc2Verbose */
378 : void CPL_DLL *VSIMalloc2Verbose(size_t nSize1, size_t nSize2,
379 : const char *pszFile,
380 : int nLine) CPL_WARN_UNUSED_RESULT;
381 : /** VSI_MALLOC2_VERBOSE */
382 : #define VSI_MALLOC2_VERBOSE(nSize1, nSize2) \
383 : VSIMalloc2Verbose(nSize1, nSize2, __FILE__, __LINE__)
384 :
385 : /** VSIMalloc3Verbose */
386 : void CPL_DLL *VSIMalloc3Verbose(size_t nSize1, size_t nSize2, size_t nSize3,
387 : const char *pszFile,
388 : int nLine) CPL_WARN_UNUSED_RESULT;
389 : /** VSI_MALLOC3_VERBOSE */
390 : #define VSI_MALLOC3_VERBOSE(nSize1, nSize2, nSize3) \
391 : VSIMalloc3Verbose(nSize1, nSize2, nSize3, __FILE__, __LINE__)
392 :
393 : /** VSICallocVerbose */
394 : void CPL_DLL *VSICallocVerbose(size_t nCount, size_t nSize, const char *pszFile,
395 : int nLine) CPL_WARN_UNUSED_RESULT;
396 : /** VSI_CALLOC_VERBOSE */
397 : #define VSI_CALLOC_VERBOSE(nCount, nSize) \
398 : VSICallocVerbose(nCount, nSize, __FILE__, __LINE__)
399 :
400 : /** VSIReallocVerbose */
401 : void CPL_DLL *VSIReallocVerbose(void *pOldPtr, size_t nNewSize,
402 : const char *pszFile,
403 : int nLine) CPL_WARN_UNUSED_RESULT;
404 : /** VSI_REALLOC_VERBOSE */
405 : #define VSI_REALLOC_VERBOSE(pOldPtr, nNewSize) \
406 : VSIReallocVerbose(pOldPtr, nNewSize, __FILE__, __LINE__)
407 :
408 : /** VSIStrdupVerbose */
409 : char CPL_DLL *VSIStrdupVerbose(const char *pszStr, const char *pszFile,
410 : int nLine) CPL_WARN_UNUSED_RESULT;
411 : /** VSI_STRDUP_VERBOSE */
412 : #define VSI_STRDUP_VERBOSE(pszStr) VSIStrdupVerbose(pszStr, __FILE__, __LINE__)
413 :
414 : GIntBig CPL_DLL CPLGetPhysicalRAM(void);
415 : GIntBig CPL_DLL CPLGetUsablePhysicalRAM(void);
416 :
417 : /* ==================================================================== */
418 : /* Other... */
419 : /* ==================================================================== */
420 :
421 : /** Alias of VSIReadDir() */
422 : #define CPLReadDir VSIReadDir
423 : char CPL_DLL **VSIReadDir(const char *);
424 : char CPL_DLL **VSIReadDirRecursive(const char *pszPath);
425 : char CPL_DLL **VSIReadDirEx(const char *pszPath, int nMaxFiles);
426 : char CPL_DLL **VSISiblingFiles(const char *pszPath);
427 : char CPL_DLL **VSIGlob(const char *pszPattern, const char *const *papszOptions,
428 : GDALProgressFunc pProgressFunc, void *pProgressData);
429 :
430 : const char CPL_DLL *VSIGetDirectorySeparator(const char *pszPath);
431 :
432 : /** Opaque type for a directory iterator */
433 : typedef struct VSIDIR VSIDIR;
434 :
435 : VSIDIR CPL_DLL *VSIOpenDir(const char *pszPath, int nRecurseDepth,
436 : const char *const *papszOptions);
437 :
438 : /*! @cond Doxygen_Suppress */
439 : typedef struct VSIDIREntry VSIDIREntry;
440 :
441 : /*! @endcond */
442 :
443 : /** Directory entry. */
444 : struct VSIDIREntry
445 : {
446 : /** Filename */
447 : char *pszName;
448 : /** File mode. See VSI_ISREG() / VSI_ISDIR() */
449 : int nMode;
450 : /** File size */
451 : vsi_l_offset nSize;
452 : /** Last modification time (seconds since 1970/01/01) */
453 : GIntBig nMTime;
454 : /** Whether nMode is known: 0 = unknown, 1 = known. */
455 : char bModeKnown;
456 : /** Whether nSize is known: 0 = unknown, 1 = known. */
457 : char bSizeKnown;
458 : /** Whether nMTime is known: 0 = unknown, 1 = known. */
459 : char bMTimeKnown;
460 : /** NULL-terminated list of extra properties. */
461 : char **papszExtra;
462 :
463 : #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
464 : /*! @cond Doxygen_Suppress */
465 : VSIDIREntry();
466 : ~VSIDIREntry();
467 : VSIDIREntry(const VSIDIREntry &);
468 : VSIDIREntry &operator=(VSIDIREntry &) = delete;
469 : /*! @endcond */
470 : #endif
471 : };
472 :
473 : const VSIDIREntry CPL_DLL *VSIGetNextDirEntry(VSIDIR *dir);
474 : void CPL_DLL VSICloseDir(VSIDIR *dir);
475 :
476 : int CPL_DLL VSIMkdir(const char *pszPathname, long mode);
477 : int CPL_DLL VSIMkdirRecursive(const char *pszPathname, long mode);
478 : int CPL_DLL VSIRmdir(const char *pszDirname);
479 : int CPL_DLL VSIRmdirRecursive(const char *pszDirname);
480 : int CPL_DLL VSIUnlink(const char *pszFilename);
481 : int CPL_DLL *VSIUnlinkBatch(CSLConstList papszFiles);
482 : int CPL_DLL VSIRename(const char *oldpath, const char *newpath);
483 : int CPL_DLL VSIMove(const char *oldpath, const char *newpath,
484 : const char *const *papszOptions,
485 : GDALProgressFunc pProgressFunc, void *pProgressData);
486 : int CPL_DLL VSICopyFile(const char *pszSource, const char *pszTarget,
487 : VSILFILE *fpSource, vsi_l_offset nSourceSize,
488 : const char *const *papszOptions,
489 : GDALProgressFunc pProgressFunc, void *pProgressData);
490 : int CPL_DLL VSICopyFileRestartable(const char *pszSource, const char *pszTarget,
491 : const char *pszInputPayload,
492 : char **ppszOutputPayload,
493 : const char *const *papszOptions,
494 : GDALProgressFunc pProgressFunc,
495 : void *pProgressData);
496 : int CPL_DLL VSISync(const char *pszSource, const char *pszTarget,
497 : const char *const *papszOptions,
498 : GDALProgressFunc pProgressFunc, void *pProgressData,
499 : char ***ppapszOutputs);
500 :
501 : int CPL_DLL VSIMultipartUploadGetCapabilities(
502 : const char *pszFilename, int *pbNonSequentialUploadSupported,
503 : int *pbParallelUploadSupported, int *pbAbortSupported,
504 : size_t *pnMinPartSize, size_t *pnMaxPartSize, int *pnMaxPartCount);
505 :
506 : char CPL_DLL *VSIMultipartUploadStart(const char *pszFilename,
507 : CSLConstList papszOptions);
508 : char CPL_DLL *VSIMultipartUploadAddPart(const char *pszFilename,
509 : const char *pszUploadId,
510 : int nPartNumber,
511 : vsi_l_offset nFileOffset,
512 : const void *pData, size_t nDataLength,
513 : CSLConstList papszOptions);
514 : int CPL_DLL VSIMultipartUploadEnd(const char *pszFilename,
515 : const char *pszUploadId, size_t nPartIdsCount,
516 : const char *const *apszPartIds,
517 : vsi_l_offset nTotalSize,
518 : CSLConstList papszOptions);
519 : int CPL_DLL VSIMultipartUploadAbort(const char *pszFilename,
520 : const char *pszUploadId,
521 : CSLConstList papszOptions);
522 :
523 : int CPL_DLL VSIAbortPendingUploads(const char *pszFilename);
524 :
525 : char CPL_DLL *VSIStrerror(int);
526 : GIntBig CPL_DLL VSIGetDiskFreeSpace(const char *pszDirname);
527 :
528 : void CPL_DLL VSINetworkStatsReset(void);
529 : char CPL_DLL *VSINetworkStatsGetAsSerializedJSON(char **papszOptions);
530 :
531 : #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
532 : extern "C++"
533 : {
534 : std::string CPL_DLL VSIURIToVSIPath(const std::string &osURI);
535 : }
536 : #endif
537 :
538 : /* ==================================================================== */
539 : /* Install special file access handlers. */
540 : /* ==================================================================== */
541 : void CPL_DLL VSIInstallMemFileHandler(void);
542 : /*! @cond Doxygen_Suppress */
543 : void CPL_DLL VSIInstallLargeFileHandler(void);
544 : /*! @endcond */
545 : void CPL_DLL VSIInstallSubFileHandler(void);
546 : void VSIInstallCurlFileHandler(void);
547 : void CPL_DLL VSICurlClearCache(void);
548 : void CPL_DLL VSICurlPartialClearCache(const char *pszFilenamePrefix);
549 : void VSIInstallCurlStreamingFileHandler(void);
550 : void VSIInstallS3FileHandler(void);
551 : void VSIInstallS3StreamingFileHandler(void);
552 : void VSIInstallGSFileHandler(void);
553 : void VSIInstallGSStreamingFileHandler(void);
554 : void VSIInstallAzureFileHandler(void);
555 : void VSIInstallAzureStreamingFileHandler(void);
556 : void VSIInstallADLSFileHandler(void);
557 : void VSIInstallOSSFileHandler(void);
558 : void VSIInstallOSSStreamingFileHandler(void);
559 : void VSIInstallSwiftFileHandler(void);
560 : void VSIInstallSwiftStreamingFileHandler(void);
561 : void VSIInstall7zFileHandler(void); /* No reason to export that */
562 : void VSIInstallRarFileHandler(void); /* No reason to export that */
563 : void VSIInstallGZipFileHandler(void); /* No reason to export that */
564 : void VSIInstallZipFileHandler(void); /* No reason to export that */
565 : void VSIInstallStdinHandler(void); /* No reason to export that */
566 : void VSIInstallHdfsHandler(void); /* No reason to export that */
567 : void VSIInstallWebHdfsHandler(void); /* No reason to export that */
568 : void VSIInstallStdoutHandler(void); /* No reason to export that */
569 : void CPL_DLL VSIInstallSparseFileHandler(void);
570 : void VSIInstallTarFileHandler(void); /* No reason to export that */
571 : void VSIInstallCachedFileHandler(void); /* No reason to export that */
572 : void CPL_DLL VSIInstallCryptFileHandler(void);
573 : void CPL_DLL VSISetCryptKey(const GByte *pabyKey, int nKeySize);
574 : /*! @cond Doxygen_Suppress */
575 : void CPL_DLL VSICleanupFileManager(void);
576 : /*! @endcond */
577 :
578 : bool CPL_DLL VSIDuplicateFileSystemHandler(const char *pszSourceFSName,
579 : const char *pszNewFSName);
580 :
581 : VSILFILE CPL_DLL *
582 : VSIFileFromMemBuffer(const char *pszFilename, GByte *pabyData,
583 : vsi_l_offset nDataLength,
584 : int bTakeOwnership) CPL_WARN_UNUSED_RESULT;
585 : GByte CPL_DLL *VSIGetMemFileBuffer(const char *pszFilename,
586 : vsi_l_offset *pnDataLength,
587 : int bUnlinkAndSeize);
588 :
589 : const char CPL_DLL *VSIMemGenerateHiddenFilename(const char *pszFilename);
590 :
591 : /** Callback used by VSIStdoutSetRedirection() */
592 : typedef size_t (*VSIWriteFunction)(const void *ptr, size_t size, size_t nmemb,
593 : FILE *stream);
594 : void CPL_DLL VSIStdoutSetRedirection(VSIWriteFunction pFct, FILE *stream);
595 :
596 : /**
597 : * Return information about a handle. Optional (driver dependent)
598 : * @since GDAL 3.0
599 : */
600 : typedef int (*VSIFilesystemPluginStatCallback)(void *pUserData,
601 : const char *pszFilename,
602 : VSIStatBufL *pStatBuf,
603 : int nFlags);
604 : /**
605 : * Remove handle by name. Optional
606 : * @since GDAL 3.0
607 : */
608 : typedef int (*VSIFilesystemPluginUnlinkCallback)(void *pUserData,
609 : const char *pszFilename);
610 : /**
611 : * Rename handle. Optional
612 : * @since GDAL 3.0
613 : */
614 : typedef int (*VSIFilesystemPluginRenameCallback)(void *pUserData,
615 : const char *oldpath,
616 : const char *newpath);
617 : /**
618 : * Create Directory. Optional
619 : * @since GDAL 3.0
620 : */
621 : typedef int (*VSIFilesystemPluginMkdirCallback)(void *pUserData,
622 : const char *pszDirname,
623 : long nMode);
624 : /**
625 : * Delete Directory. Optional
626 : * @since GDAL 3.0
627 : */
628 : typedef int (*VSIFilesystemPluginRmdirCallback)(void *pUserData,
629 : const char *pszDirname);
630 : /**
631 : * List directory content. Optional
632 : * @since GDAL 3.0
633 : */
634 : typedef char **(*VSIFilesystemPluginReadDirCallback)(void *pUserData,
635 : const char *pszDirname,
636 : int nMaxFiles);
637 : /**
638 : * List related files. Must return NULL if unknown, or a list of relative
639 : * filenames that can be opened along the main file. If no other file than
640 : * pszFilename needs to be opened, return static_cast<char**>
641 : * (CPLCalloc(1,sizeof(char*)));
642 : *
643 : * Optional
644 : * @since GDAL 3.2
645 : */
646 : typedef char **(*VSIFilesystemPluginSiblingFilesCallback)(
647 : void *pUserData, const char *pszDirname);
648 : /**
649 : * Open a handle. Mandatory. Returns an opaque pointer that will be used in
650 : * subsequent file I/O calls. Should return null and/or set errno if the handle
651 : * does not exist or the access mode is incorrect.
652 : * @since GDAL 3.0
653 : */
654 : typedef void *(*VSIFilesystemPluginOpenCallback)(void *pUserData,
655 : const char *pszFilename,
656 : const char *pszAccess);
657 : /**
658 : * Return current position in handle. Mandatory
659 : * @since GDAL 3.0
660 : */
661 : typedef vsi_l_offset (*VSIFilesystemPluginTellCallback)(void *pFile);
662 : /**
663 : * Seek to position in handle. Mandatory except for write only handles
664 : * @since GDAL 3.0
665 : */
666 : typedef int (*VSIFilesystemPluginSeekCallback)(void *pFile,
667 : vsi_l_offset nOffset,
668 : int nWhence);
669 : /**
670 : * Read data from current position, returns the number of blocks correctly read.
671 : * Mandatory except for write only handles
672 : * @since GDAL 3.0
673 : */
674 : typedef size_t (*VSIFilesystemPluginReadCallback)(void *pFile, void *pBuffer,
675 : size_t nSize, size_t nCount);
676 : /**
677 : * Read from multiple offsets. Optional, will be replaced by multiple calls to
678 : * Read() if not provided
679 : * @since GDAL 3.0
680 : */
681 : typedef int (*VSIFilesystemPluginReadMultiRangeCallback)(
682 : void *pFile, int nRanges, void **ppData, const vsi_l_offset *panOffsets,
683 : const size_t *panSizes);
684 : /**
685 : * Get empty ranges. Optional
686 : * @since GDAL 3.0
687 : */
688 : typedef VSIRangeStatus (*VSIFilesystemPluginGetRangeStatusCallback)(
689 : void *pFile, vsi_l_offset nOffset, vsi_l_offset nLength);
690 : /**
691 : * Has end of file been reached. Mandatory? for read handles.
692 : * @since GDAL 3.0
693 : */
694 : typedef int (*VSIFilesystemPluginEofCallback)(void *pFile);
695 : /**
696 : * Write bytes at current offset. Mandatory for writable handles
697 : * @since GDAL 3.0
698 : */
699 : typedef size_t (*VSIFilesystemPluginWriteCallback)(void *pFile,
700 : const void *pBuffer,
701 : size_t nSize, size_t nCount);
702 : /**
703 : * Sync written bytes. Optional
704 : * @since GDAL 3.0
705 : */
706 : typedef int (*VSIFilesystemPluginFlushCallback)(void *pFile);
707 : /**
708 : * Truncate handle. Mandatory (driver dependent?) for write handles
709 : */
710 : typedef int (*VSIFilesystemPluginTruncateCallback)(void *pFile,
711 : vsi_l_offset nNewSize);
712 : /**
713 : * Close file handle. Optional
714 : * @since GDAL 3.0
715 : */
716 : typedef int (*VSIFilesystemPluginCloseCallback)(void *pFile);
717 :
718 : /**
719 : * This optional method is called when code plans to access soon one or several
720 : * ranges in a file. Some file systems may be able to use this hint to
721 : * for example asynchronously start such requests.
722 : *
723 : * Offsets may be given in a non-increasing order, and may potentially
724 : * overlap.
725 : *
726 : * @param pFile File handle.
727 : * @param nRanges Size of the panOffsets and panSizes arrays.
728 : * @param panOffsets Array containing the start offset of each range.
729 : * @param panSizes Array containing the size (in bytes) of each range.
730 : * @since GDAL 3.7
731 : */
732 : typedef void (*VSIFilesystemPluginAdviseReadCallback)(
733 : void *pFile, int nRanges, const vsi_l_offset *panOffsets,
734 : const size_t *panSizes);
735 :
736 : /**
737 : * Has a read error (non end-of-file related) has occurred?
738 : * @since GDAL 3.10
739 : */
740 : typedef int (*VSIFilesystemPluginErrorCallback)(void *pFile);
741 :
742 : /**
743 : * Clear error and end-of-file flags.
744 : * @since GDAL 3.10
745 : */
746 : typedef void (*VSIFilesystemPluginClearErrCallback)(void *pFile);
747 :
748 : /**
749 : * struct containing callbacks to used by the handler.
750 : * (rw), (r), (w) or () at the end indicate whether the given callback is
751 : * mandatory for reading and or writing handlers. A (?) indicates that the
752 : * callback might be mandatory for certain drivers only.
753 : * @since GDAL 3.0
754 : */
755 : typedef struct
756 : {
757 : /**
758 : * Optional opaque pointer passed back to filemanager callbacks (e.g. open,
759 : * stat, rmdir)
760 : */
761 : void *pUserData;
762 : VSIFilesystemPluginStatCallback stat; /**< stat handle by name (rw)*/
763 : VSIFilesystemPluginUnlinkCallback unlink; /**< unlink handle by name ()*/
764 : VSIFilesystemPluginRenameCallback rename; /**< rename handle ()*/
765 : VSIFilesystemPluginMkdirCallback mkdir; /**< make directory ()*/
766 : VSIFilesystemPluginRmdirCallback rmdir; /**< remove directory ()*/
767 : VSIFilesystemPluginReadDirCallback
768 : read_dir; /**< list directory content (r?)*/
769 : VSIFilesystemPluginOpenCallback open; /**< open handle by name (rw) */
770 : VSIFilesystemPluginTellCallback
771 : tell; /**< get current position of handle (rw) */
772 : VSIFilesystemPluginSeekCallback
773 : seek; /**< set current position of handle (rw) */
774 : VSIFilesystemPluginReadCallback read; /**< read from current position (r) */
775 : VSIFilesystemPluginReadMultiRangeCallback
776 : read_multi_range; /**< read multiple blocks ()*/
777 : VSIFilesystemPluginGetRangeStatusCallback
778 : get_range_status; /**< get range status () */
779 : VSIFilesystemPluginEofCallback
780 : eof; /**< has end of file been reached (r?) */
781 : VSIFilesystemPluginWriteCallback
782 : write; /**< write bytes to current position (w) */
783 : VSIFilesystemPluginFlushCallback flush; /**< sync bytes (w) */
784 : VSIFilesystemPluginTruncateCallback truncate; /**< truncate handle (w?) */
785 : VSIFilesystemPluginCloseCallback close; /**< close handle (rw) */
786 : size_t nBufferSize; /**< buffer small reads (makes handler read only) */
787 : size_t nCacheSize; /**< max mem to use per file when buffering */
788 : VSIFilesystemPluginSiblingFilesCallback
789 : sibling_files; /**< list related files*/
790 :
791 : /** The following optional member has been added in GDAL 3.7: */
792 : VSIFilesystemPluginAdviseReadCallback advise_read; /**< AdviseRead() */
793 :
794 : VSIFilesystemPluginErrorCallback error; /**< has read error occurred (r) */
795 : VSIFilesystemPluginClearErrCallback clear_err; /**< clear error flags(r) */
796 : /*
797 : Callbacks are defined as a struct allocated by a call to
798 : VSIAllocFilesystemPluginCallbacksStruct in order to try to maintain ABI
799 : stability when eventually adding a new member. Any callbacks added to
800 : this struct SHOULD be added to the END of this struct
801 : */
802 : } VSIFilesystemPluginCallbacksStruct;
803 :
804 : /**
805 : * return a VSIFilesystemPluginCallbacksStruct to be populated at runtime with
806 : * handler callbacks
807 : * @since GDAL 3.0
808 : */
809 : VSIFilesystemPluginCallbacksStruct CPL_DLL *
810 : VSIAllocFilesystemPluginCallbacksStruct(void);
811 :
812 : /**
813 : * free resources allocated by VSIAllocFilesystemPluginCallbacksStruct
814 : * @since GDAL 3.0
815 : */
816 : void CPL_DLL VSIFreeFilesystemPluginCallbacksStruct(
817 : VSIFilesystemPluginCallbacksStruct *poCb);
818 :
819 : /**
820 : * register a handler on the given prefix. All IO on datasets opened with the
821 : * filename /prefix/xxxxxx will go through these callbacks. pszPrefix must begin
822 : * and end with a '/'
823 : * @since GDAL 3.0
824 : */
825 : int CPL_DLL VSIInstallPluginHandler(
826 : const char *pszPrefix, const VSIFilesystemPluginCallbacksStruct *poCb);
827 :
828 : /**
829 : * Unregister a handler previously installed with VSIInstallPluginHandler() on
830 : * the given prefix.
831 : * Note: it is generally unsafe to remove a handler while there are still file
832 : * handles opened that are managed by that handler. It is the responsibility of
833 : * the caller to ensure that it calls this function in a situation where it is
834 : * safe to do so.
835 : * @since GDAL 3.9
836 : */
837 : int CPL_DLL VSIRemovePluginHandler(const char *pszPrefix);
838 :
839 : /* ==================================================================== */
840 : /* Time querying. */
841 : /* ==================================================================== */
842 :
843 : /*! @cond Doxygen_Suppress */
844 : unsigned long CPL_DLL VSITime(unsigned long *);
845 : const char CPL_DLL *VSICTime(unsigned long);
846 : struct tm CPL_DLL *VSIGMTime(const time_t *pnTime, struct tm *poBrokenTime);
847 : struct tm CPL_DLL *VSILocalTime(const time_t *pnTime, struct tm *poBrokenTime);
848 : /*! @endcond */
849 :
850 : /*! @cond Doxygen_Suppress */
851 : /* -------------------------------------------------------------------- */
852 : /* the following can be turned on for detailed logging of */
853 : /* almost all IO calls. */
854 : /* -------------------------------------------------------------------- */
855 : #ifdef VSI_DEBUG
856 :
857 : #ifndef DEBUG
858 : #define DEBUG
859 : #endif
860 :
861 : #include "cpl_error.h"
862 :
863 : #define VSIDebug4(f, a1, a2, a3, a4) CPLDebug("VSI", f, a1, a2, a3, a4);
864 : #define VSIDebug3(f, a1, a2, a3) CPLDebug("VSI", f, a1, a2, a3);
865 : #define VSIDebug2(f, a1, a2) CPLDebug("VSI", f, a1, a2);
866 : #define VSIDebug1(f, a1) CPLDebug("VSI", f, a1);
867 : #else
868 : #define VSIDebug4(f, a1, a2, a3, a4) \
869 : { \
870 : }
871 : #define VSIDebug3(f, a1, a2, a3) \
872 : { \
873 : }
874 : #define VSIDebug2(f, a1, a2) \
875 : { \
876 : }
877 : #define VSIDebug1(f, a1) \
878 : { \
879 : }
880 : #endif
881 : /*! @endcond */
882 :
883 : CPL_C_END
884 :
885 : #endif /* ndef CPL_VSI_H_INCLUDED */
|
