1 /****************************************************************************** 2 * $Id: cpl_vsi.h 15217 2008-08-25 20:34:50Z 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 * 12 * Permission is hereby granted, free of charge, to any person obtaining a 13 * copy of this software and associated documentation files (the "Software"), 14 * to deal in the Software without restriction, including without limitation 15 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 16 * and/or sell copies of the Software, and to permit persons to whom the 17 * Software is furnished to do so, subject to the following conditions: 18 * 19 * The above copyright notice and this permission notice shall be included 20 * in all copies or substantial portions of the Software. 21 * 22 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 23 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 24 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 25 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 26 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 27 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 28 * DEALINGS IN THE SOFTWARE. 29 ****************************************************************************/ 30 31 #ifndef CPL_VSI_H_INCLUDED 32 #define CPL_VSI_H_INCLUDED 33 34 #include "cpl_port.h" 35 /** 36 * \file cpl_vsi.h 37 * 38 * Standard C Covers 39 * 40 * The VSI functions are intended to be hookable aliases for Standard C 41 * I/O, memory allocation and other system functions. They are intended 42 * to allow virtualization of disk I/O so that non file data sources 43 * can be made to appear as files, and so that additional error trapping 44 * and reporting can be interested. The memory access API is aliased 45 * so that special application memory management services can be used. 46 * 47 * Is is intended that each of these functions retains exactly the same 48 * calling pattern as the original Standard C functions they relate to. 49 * This means we don't have to provide custom documentation, and also means 50 * that the default implementation is very simple. 51 */ 52 53 54 /* -------------------------------------------------------------------- */ 55 /* We need access to ``struct stat''. */ 56 /* -------------------------------------------------------------------- */ 57 58 /* Unix */ 59 #if !defined(_WIN32) && !defined(_WIN32_WCE) 60 # include <unistd.h> 61 #endif 62 63 /* Windows */ 64 #if !defined(macos_pre10) && !defined(_WIN32_WCE) 65 # include <sys/stat.h> 66 #endif 67 68 /* Windows CE */ 69 #if defined(_WIN32_WCE) 70 # include <wce_stat.h> 71 #endif 72 73 CPL_C_START 74 75 /* ==================================================================== */ 76 /* stdio file access functions. These may not support large */ 77 /* files, and don't necessarily go through the virtualization */ 78 /* API. */ 79 /* ==================================================================== */ 80 81 FILE CPL_DLL * VSIFOpen( const char *, const char * ); 82 int CPL_DLL VSIFClose( FILE * ); 83 int CPL_DLL VSIFSeek( FILE *, long, int ); 84 long CPL_DLL VSIFTell( FILE * ); 85 void CPL_DLL VSIRewind( FILE * ); 86 void CPL_DLL VSIFFlush( FILE * ); 87 88 size_t CPL_DLL VSIFRead( void *, size_t, size_t, FILE * ); 89 size_t CPL_DLL VSIFWrite( const void *, size_t, size_t, FILE * ); 90 char CPL_DLL *VSIFGets( char *, int, FILE * ); 91 int CPL_DLL VSIFPuts( const char *, FILE * ); 92 int CPL_DLL VSIFPrintf( FILE *, const char *, ... ) CPL_PRINT_FUNC_FORMAT(2, 3); 93 94 int CPL_DLL VSIFGetc( FILE * ); 95 int CPL_DLL VSIFPutc( int, FILE * ); 96 int CPL_DLL VSIUngetc( int, FILE * ); 97 int CPL_DLL VSIFEof( FILE * ); 98 99 /* ==================================================================== */ 100 /* VSIStat() related. */ 101 /* ==================================================================== */ 102 103 typedef struct stat VSIStatBuf; 104 int CPL_DLL VSIStat( const char *, VSIStatBuf * ); 105 106 #ifdef _WIN32 107 # define VSI_ISLNK(x) ( 0 ) /* N/A on Windows */ 108 # define VSI_ISREG(x) ((x) & S_IFREG) 109 # define VSI_ISDIR(x) ((x) & S_IFDIR) 110 # define VSI_ISCHR(x) ((x) & S_IFCHR) 111 # define VSI_ISBLK(x) ( 0 ) /* N/A on Windows */ 112 #else 113 # define VSI_ISLNK(x) S_ISLNK(x) 114 # define VSI_ISREG(x) S_ISREG(x) 115 # define VSI_ISDIR(x) S_ISDIR(x) 116 # define VSI_ISCHR(x) S_ISCHR(x) 117 # define VSI_ISBLK(x) S_ISBLK(x) 118 #endif 119 120 /* ==================================================================== */ 121 /* 64bit stdio file access functions. If we have a big size */ 122 /* defined, then provide protypes for the large file API, */ 123 /* otherwise redefine to use the regular api. */ 124 /* ==================================================================== */ 125 typedef GUIntBig vsi_l_offset; 126 127 FILE CPL_DLL * VSIFOpenL( const char *, const char * ); 128 int CPL_DLL VSIFCloseL( FILE * ); 129 int CPL_DLL VSIFSeekL( FILE *, vsi_l_offset, int ); 130 vsi_l_offset CPL_DLL VSIFTellL( FILE * ); 131 void CPL_DLL VSIRewindL( FILE * ); 132 size_t CPL_DLL VSIFReadL( void *, size_t, size_t, FILE * ); 133 size_t CPL_DLL VSIFWriteL( const void *, size_t, size_t, FILE * ); 134 int CPL_DLL VSIFEofL( FILE * ); 135 int CPL_DLL VSIFFlushL( FILE * ); 136 int CPL_DLL VSIFPrintfL( FILE *, const char *, ... ) CPL_PRINT_FUNC_FORMAT(2, 3); 137 int CPL_DLL VSIFPutcL( int, FILE * ); 138 139 #if defined(VSI_STAT64_T) 140 typedef struct VSI_STAT64_T VSIStatBufL; 141 #else 142 #define VSIStatBufL VSIStatBuf 143 #endif 144 145 int CPL_DLL VSIStatL( const char *, VSIStatBufL * ); 146 147 /* ==================================================================== */ 148 /* Memory allocation */ 149 /* ==================================================================== */ 150 151 void CPL_DLL *VSICalloc( size_t, size_t ); 152 void CPL_DLL *VSIMalloc( size_t ); 153 void CPL_DLL VSIFree( void * ); 154 void CPL_DLL *VSIRealloc( void *, size_t ); 155 char CPL_DLL *VSIStrdup( const char * ); 156 157 /** 158 VSIMalloc2 allocates (nSize1 * nSize2) bytes. 159 In case of overflow of the multiplication, or if memory allocation fails, a 160 NULL pointer is returned and a CE_Failure error is raised with CPLError(). 161 If nSize1 == 0 || nSize2 == 0, a NULL pointer will also be returned. 162 CPLFree() or VSIFree() can be used to free memory allocated by this function. 163 */ 164 void CPL_DLL *VSIMalloc2( size_t nSize1, size_t nSize2 ); 165 166 /** 167 VSIMalloc3 allocates (nSize1 * nSize2 * nSize3) bytes. 168 In case of overflow of the multiplication, or if memory allocation fails, a 169 NULL pointer is returned and a CE_Failure error is raised with CPLError(). 170 If nSize1 == 0 || nSize2 == 0 || nSize3 == 0, a NULL pointer will also be returned. 171 CPLFree() or VSIFree() can be used to free memory allocated by this function. 172 */ 173 void CPL_DLL *VSIMalloc3( size_t nSize1, size_t nSize2, size_t nSize3 ); 174 175 176 /* ==================================================================== */ 177 /* Other... */ 178 /* ==================================================================== */ 179 180 #define CPLReadDir VSIReadDir 181 char CPL_DLL **VSIReadDir( const char * ); 182 int CPL_DLL VSIMkdir( const char * pathname, long mode ); 183 int CPL_DLL VSIRmdir( const char * pathname ); 184 int CPL_DLL VSIUnlink( const char * pathname ); 185 int CPL_DLL VSIRename( const char * oldpath, const char * newpath ); 186 char CPL_DLL *VSIStrerror( int ); 187 188 /* ==================================================================== */ 189 /* Install special file access handlers. */ 190 /* ==================================================================== */ 191 void CPL_DLL VSIInstallMemFileHandler(void); 192 void CPL_DLL VSIInstallLargeFileHandler(void); 193 void VSIInstallGZipFileHandler(void); /* No reason to export that */ 194 void VSIInstallZipFileHandler(void); /* No reason to export that */ 195 void CPL_DLL VSICleanupFileManager(void); 196 197 FILE CPL_DLL *VSIFileFromMemBuffer( const char *pszFilename, 198 GByte *pabyData, 199 vsi_l_offset nDataLength, 200 int bTakeOwnership ); 201 GByte CPL_DLL *VSIGetMemFileBuffer( const char *pszFilename, 202 vsi_l_offset *pnDataLength, 203 int bUnlinkAndSeize ); 204 205 /* ==================================================================== */ 206 /* Time quering. */ 207 /* ==================================================================== */ 208 209 unsigned long CPL_DLL VSITime( unsigned long * ); 210 const char CPL_DLL *VSICTime( unsigned long ); 211 struct tm CPL_DLL *VSIGMTime( const time_t *pnTime, 212 struct tm *poBrokenTime ); 213 struct tm CPL_DLL *VSILocalTime( const time_t *pnTime, 214 struct tm *poBrokenTime ); 215 216 /* -------------------------------------------------------------------- */ 217 /* the following can be turned on for detailed logging of */ 218 /* almost all IO calls. */ 219 /* -------------------------------------------------------------------- */ 220 #ifdef VSI_DEBUG 221 222 #ifndef DEBUG 223 # define DEBUG 224 #endif 225 226 #include "cpl_error.h" 227 228 #define VSIDebug4(f,a1,a2,a3,a4) CPLDebug( "VSI", f, a1, a2, a3, a4 ); 229 #define VSIDebug3( f, a1, a2, a3 ) CPLDebug( "VSI", f, a1, a2, a3 ); 230 #define VSIDebug2( f, a1, a2 ) CPLDebug( "VSI", f, a1, a2 ); 231 #define VSIDebug1( f, a1 ) CPLDebug( "VSI", f, a1 ); 232 #else 233 #define VSIDebug4( f, a1, a2, a3, a4 ) {} 234 #define VSIDebug3( f, a1, a2, a3 ) {} 235 #define VSIDebug2( f, a1, a2 ) {} 236 #define VSIDebug1( f, a1 ) {} 237 #endif 238 239 CPL_C_END 240 241 #endif /* ndef CPL_VSI_H_INCLUDED */ 242