1 /* 2 ** 2001 September 16 3 ** 4 ** The author disclaims copyright to this source code. In place of 5 ** a legal notice, here is a blessing: 6 ** 7 ** May you do good and not evil. 8 ** May you find forgiveness for yourself and forgive others. 9 ** May you share freely, never taking more than you give. 10 ** 11 ****************************************************************************** 12 ** 13 ** This header file (together with is companion C source-code file 14 ** "os.c") attempt to abstract the underlying operating system so that 15 ** the SQLite library will work on both POSIX and windows systems. 16 */ 17 #ifndef _SQLITE_OS_H_ 18 #define _SQLITE_OS_H_ 19 20 /* 21 ** Figure out if we are dealing with Unix, Windows, or some other 22 ** operating system. 23 */ 24 #if !defined(OS_UNIX) && !defined(OS_OTHER) 25 # define OS_OTHER 0 26 # ifndef OS_WIN 27 # if defined(_WIN32) || defined(WIN32) || defined(__CYGWIN__) || defined(__MINGW32__) || defined(__BORLANDC__) 28 # define OS_WIN 1 29 # define OS_UNIX 0 30 # define OS_OS2 0 31 # elif defined(_EMX_) || defined(_OS2) || defined(OS2) || defined(_OS2_) || defined(__OS2__) 32 # define OS_WIN 0 33 # define OS_UNIX 0 34 # define OS_OS2 1 35 # else 36 # define OS_WIN 0 37 # define OS_UNIX 1 38 # define OS_OS2 0 39 # endif 40 # else 41 # define OS_UNIX 0 42 # define OS_OS2 0 43 # endif 44 #else 45 # ifndef OS_WIN 46 # define OS_WIN 0 47 # endif 48 #endif 49 50 51 /* 52 ** Define the maximum size of a temporary filename 53 */ 54 #if OS_WIN 55 # include <windows.h> 56 # define SQLITE_TEMPNAME_SIZE (MAX_PATH+50) 57 #elif OS_OS2 58 # define INCL_DOSDATETIME 59 # define INCL_DOSFILEMGR 60 # define INCL_DOSERRORS 61 # define INCL_DOSMISC 62 # define INCL_DOSPROCESS 63 # include <os2.h> 64 # define SQLITE_TEMPNAME_SIZE (CCHMAXPATHCOMP) 65 #else 66 # define SQLITE_TEMPNAME_SIZE 200 67 #endif 68 69 /* If the SET_FULLSYNC macro is not defined above, then make it 70 ** a no-op 71 */ 72 #ifndef SET_FULLSYNC 73 # define SET_FULLSYNC(x,y) 74 #endif 75 76 /* 77 ** Temporary files are named starting with this prefix followed by 16 random 78 ** alphanumeric characters, and no file extension. They are stored in the 79 ** OS's standard temporary file directory, and are deleted prior to exit. 80 ** If sqlite is being embedded in another program, you may wish to change the 81 ** prefix to reflect your program's name, so that if your program exits 82 ** prematurely, old temporary files can be easily identified. This can be done 83 ** using -DTEMP_FILE_PREFIX=myprefix_ on the compiler command line. 84 ** 85 ** 2006-10-31: The default prefix used to be "sqlite_". But then 86 ** Mcafee started using SQLite in their anti-virus product and it 87 ** started putting files with the "sqlite" name in the c:/temp folder. 88 ** This annoyed many windows users. Those users would then do a 89 ** Google search for "sqlite", find the telephone numbers of the 90 ** developers and call to wake them up at night and complain. 91 ** For this reason, the default name prefix is changed to be "sqlite" 92 ** spelled backwards. So the temp files are still identified, but 93 ** anybody smart enough to figure out the code is also likely smart 94 ** enough to know that calling the developer will not help get rid 95 ** of the file. 96 */ 97 #ifndef TEMP_FILE_PREFIX 98 # define TEMP_FILE_PREFIX "etilqs_" 99 #endif 100 101 /* 102 ** Define the interfaces for Unix, Windows, and OS/2. 103 */ 104 #if OS_UNIX 105 #define sqlite3OsOpenReadWrite sqlite3UnixOpenReadWrite 106 #define sqlite3OsOpenExclusive sqlite3UnixOpenExclusive 107 #define sqlite3OsOpenReadOnly sqlite3UnixOpenReadOnly 108 #define sqlite3OsDelete sqlite3UnixDelete 109 #define sqlite3OsFileExists sqlite3UnixFileExists 110 #define sqlite3OsFullPathname sqlite3UnixFullPathname 111 #define sqlite3OsIsDirWritable sqlite3UnixIsDirWritable 112 #define sqlite3OsSyncDirectory sqlite3UnixSyncDirectory 113 #define sqlite3OsTempFileName sqlite3UnixTempFileName 114 #define sqlite3OsRandomSeed sqlite3UnixRandomSeed 115 #define sqlite3OsSleep sqlite3UnixSleep 116 #define sqlite3OsCurrentTime sqlite3UnixCurrentTime 117 #define sqlite3OsEnterMutex sqlite3UnixEnterMutex 118 #define sqlite3OsLeaveMutex sqlite3UnixLeaveMutex 119 #define sqlite3OsInMutex sqlite3UnixInMutex 120 #define sqlite3OsThreadSpecificData sqlite3UnixThreadSpecificData 121 #define sqlite3OsMalloc sqlite3GenericMalloc 122 #define sqlite3OsRealloc sqlite3GenericRealloc 123 #define sqlite3OsFree sqlite3GenericFree 124 #define sqlite3OsAllocationSize sqlite3GenericAllocationSize 125 #endif 126 #if OS_WIN 127 #define sqlite3OsOpenReadWrite sqlite3WinOpenReadWrite 128 #define sqlite3OsOpenExclusive sqlite3WinOpenExclusive 129 #define sqlite3OsOpenReadOnly sqlite3WinOpenReadOnly 130 #define sqlite3OsDelete sqlite3WinDelete 131 #define sqlite3OsFileExists sqlite3WinFileExists 132 #define sqlite3OsFullPathname sqlite3WinFullPathname 133 #define sqlite3OsIsDirWritable sqlite3WinIsDirWritable 134 #define sqlite3OsSyncDirectory sqlite3WinSyncDirectory 135 #define sqlite3OsTempFileName sqlite3WinTempFileName 136 #define sqlite3OsRandomSeed sqlite3WinRandomSeed 137 #define sqlite3OsSleep sqlite3WinSleep 138 #define sqlite3OsCurrentTime sqlite3WinCurrentTime 139 #define sqlite3OsEnterMutex sqlite3WinEnterMutex 140 #define sqlite3OsLeaveMutex sqlite3WinLeaveMutex 141 #define sqlite3OsInMutex sqlite3WinInMutex 142 #define sqlite3OsThreadSpecificData sqlite3WinThreadSpecificData 143 #define sqlite3OsMalloc sqlite3GenericMalloc 144 #define sqlite3OsRealloc sqlite3GenericRealloc 145 #define sqlite3OsFree sqlite3GenericFree 146 #define sqlite3OsAllocationSize sqlite3GenericAllocationSize 147 #endif 148 #if OS_OS2 149 #define sqlite3OsOpenReadWrite sqlite3Os2OpenReadWrite 150 #define sqlite3OsOpenExclusive sqlite3Os2OpenExclusive 151 #define sqlite3OsOpenReadOnly sqlite3Os2OpenReadOnly 152 #define sqlite3OsDelete sqlite3Os2Delete 153 #define sqlite3OsFileExists sqlite3Os2FileExists 154 #define sqlite3OsFullPathname sqlite3Os2FullPathname 155 #define sqlite3OsIsDirWritable sqlite3Os2IsDirWritable 156 #define sqlite3OsSyncDirectory sqlite3Os2SyncDirectory 157 #define sqlite3OsTempFileName sqlite3Os2TempFileName 158 #define sqlite3OsRandomSeed sqlite3Os2RandomSeed 159 #define sqlite3OsSleep sqlite3Os2Sleep 160 #define sqlite3OsCurrentTime sqlite3Os2CurrentTime 161 #define sqlite3OsEnterMutex sqlite3Os2EnterMutex 162 #define sqlite3OsLeaveMutex sqlite3Os2LeaveMutex 163 #define sqlite3OsInMutex sqlite3Os2InMutex 164 #define sqlite3OsThreadSpecificData sqlite3Os2ThreadSpecificData 165 #define sqlite3OsMalloc sqlite3GenericMalloc 166 #define sqlite3OsRealloc sqlite3GenericRealloc 167 #define sqlite3OsFree sqlite3GenericFree 168 #define sqlite3OsAllocationSize sqlite3GenericAllocationSize 169 #endif 170 171 172 173 174 /* 175 ** If using an alternative OS interface, then we must have an "os_other.h" 176 ** header file available for that interface. Presumably the "os_other.h" 177 ** header file contains #defines similar to those above. 178 */ 179 #if OS_OTHER 180 # include "os_other.h" 181 #endif 182 183 184 185 /* 186 ** Forward declarations 187 */ 188 typedef struct OsFile OsFile; 189 typedef struct IoMethod IoMethod; 190 191 /* 192 ** An instance of the following structure contains pointers to all 193 ** methods on an OsFile object. 194 */ 195 struct IoMethod { 196 int (*xClose)(OsFile**); 197 int (*xOpenDirectory)(OsFile*, const char*); 198 int (*xRead)(OsFile*, void*, int amt); 199 int (*xWrite)(OsFile*, const void*, int amt); 200 int (*xSeek)(OsFile*, i64 offset); 201 int (*xTruncate)(OsFile*, i64 size); 202 int (*xSync)(OsFile*, int); 203 void (*xSetFullSync)(OsFile *id, int setting); 204 int (*xFileHandle)(OsFile *id); 205 int (*xFileSize)(OsFile*, i64 *pSize); 206 int (*xLock)(OsFile*, int); 207 int (*xUnlock)(OsFile*, int); 208 int (*xLockState)(OsFile *id); 209 int (*xCheckReservedLock)(OsFile *id); 210 }; 211 212 /* 213 ** The OsFile object describes an open disk file in an OS-dependent way. 214 ** The version of OsFile defined here is a generic version. Each OS 215 ** implementation defines its own subclass of this structure that contains 216 ** additional information needed to handle file I/O. But the pMethod 217 ** entry (pointing to the virtual function table) always occurs first 218 ** so that we can always find the appropriate methods. 219 */ 220 struct OsFile { 221 IoMethod const *pMethod; 222 }; 223 224 /* 225 ** The following values may be passed as the second argument to 226 ** sqlite3OsLock(). The various locks exhibit the following semantics: 227 ** 228 ** SHARED: Any number of processes may hold a SHARED lock simultaneously. 229 ** RESERVED: A single process may hold a RESERVED lock on a file at 230 ** any time. Other processes may hold and obtain new SHARED locks. 231 ** PENDING: A single process may hold a PENDING lock on a file at 232 ** any one time. Existing SHARED locks may persist, but no new 233 ** SHARED locks may be obtained by other processes. 234 ** EXCLUSIVE: An EXCLUSIVE lock precludes all other locks. 235 ** 236 ** PENDING_LOCK may not be passed directly to sqlite3OsLock(). Instead, a 237 ** process that requests an EXCLUSIVE lock may actually obtain a PENDING 238 ** lock. This can be upgraded to an EXCLUSIVE lock by a subsequent call to 239 ** sqlite3OsLock(). 240 */ 241 #define NO_LOCK 0 242 #define SHARED_LOCK 1 243 #define RESERVED_LOCK 2 244 #define PENDING_LOCK 3 245 #define EXCLUSIVE_LOCK 4 246 247 /* 248 ** File Locking Notes: (Mostly about windows but also some info for Unix) 249 ** 250 ** We cannot use LockFileEx() or UnlockFileEx() on Win95/98/ME because 251 ** those functions are not available. So we use only LockFile() and 252 ** UnlockFile(). 253 ** 254 ** LockFile() prevents not just writing but also reading by other processes. 255 ** A SHARED_LOCK is obtained by locking a single randomly-chosen 256 ** byte out of a specific range of bytes. The lock byte is obtained at 257 ** random so two separate readers can probably access the file at the 258 ** same time, unless they are unlucky and choose the same lock byte. 259 ** An EXCLUSIVE_LOCK is obtained by locking all bytes in the range. 260 ** There can only be one writer. A RESERVED_LOCK is obtained by locking 261 ** a single byte of the file that is designated as the reserved lock byte. 262 ** A PENDING_LOCK is obtained by locking a designated byte different from 263 ** the RESERVED_LOCK byte. 264 ** 265 ** On WinNT/2K/XP systems, LockFileEx() and UnlockFileEx() are available, 266 ** which means we can use reader/writer locks. When reader/writer locks 267 ** are used, the lock is placed on the same range of bytes that is used 268 ** for probabilistic locking in Win95/98/ME. Hence, the locking scheme 269 ** will support two or more Win95 readers or two or more WinNT readers. 270 ** But a single Win95 reader will lock out all WinNT readers and a single 271 ** WinNT reader will lock out all other Win95 readers. 272 ** 273 ** The following #defines specify the range of bytes used for locking. 274 ** SHARED_SIZE is the number of bytes available in the pool from which 275 ** a random byte is selected for a shared lock. The pool of bytes for 276 ** shared locks begins at SHARED_FIRST. 277 ** 278 ** These #defines are available in sqlite_aux.h so that adaptors for 279 ** connecting SQLite to other operating systems can use the same byte 280 ** ranges for locking. In particular, the same locking strategy and 281 ** byte ranges are used for Unix. This leaves open the possiblity of having 282 ** clients on win95, winNT, and unix all talking to the same shared file 283 ** and all locking correctly. To do so would require that samba (or whatever 284 ** tool is being used for file sharing) implements locks correctly between 285 ** windows and unix. I'm guessing that isn't likely to happen, but by 286 ** using the same locking range we are at least open to the possibility. 287 ** 288 ** Locking in windows is manditory. For this reason, we cannot store 289 ** actual data in the bytes used for locking. The pager never allocates 290 ** the pages involved in locking therefore. SHARED_SIZE is selected so 291 ** that all locks will fit on a single page even at the minimum page size. 292 ** PENDING_BYTE defines the beginning of the locks. By default PENDING_BYTE 293 ** is set high so that we don't have to allocate an unused page except 294 ** for very large databases. But one should test the page skipping logic 295 ** by setting PENDING_BYTE low and running the entire regression suite. 296 ** 297 ** Changing the value of PENDING_BYTE results in a subtly incompatible 298 ** file format. Depending on how it is changed, you might not notice 299 ** the incompatibility right away, even running a full regression test. 300 ** The default location of PENDING_BYTE is the first byte past the 301 ** 1GB boundary. 302 ** 303 */ 304 #ifndef SQLITE_TEST 305 #define PENDING_BYTE 0x40000000 /* First byte past the 1GB boundary */ 306 #else 307 extern unsigned int sqlite3_pending_byte; 308 #define PENDING_BYTE sqlite3_pending_byte 309 #endif 310 311 #define RESERVED_BYTE (PENDING_BYTE+1) 312 #define SHARED_FIRST (PENDING_BYTE+2) 313 #define SHARED_SIZE 510 314 315 /* 316 ** Prototypes for operating system interface routines. 317 */ 318 int sqlite3OsClose(OsFile**); 319 int sqlite3OsOpenDirectory(OsFile*, const char*); 320 int sqlite3OsRead(OsFile*, void*, int amt); 321 int sqlite3OsWrite(OsFile*, const void*, int amt); 322 int sqlite3OsSeek(OsFile*, i64 offset); 323 int sqlite3OsTruncate(OsFile*, i64 size); 324 int sqlite3OsSync(OsFile*, int); 325 void sqlite3OsSetFullSync(OsFile *id, int setting); 326 int sqlite3OsFileHandle(OsFile *id); 327 int sqlite3OsFileSize(OsFile*, i64 *pSize); 328 int sqlite3OsLock(OsFile*, int); 329 int sqlite3OsUnlock(OsFile*, int); 330 int sqlite3OsLockState(OsFile *id); 331 int sqlite3OsCheckReservedLock(OsFile *id); 332 int sqlite3OsOpenReadWrite(const char*, OsFile**, int*); 333 int sqlite3OsOpenExclusive(const char*, OsFile**, int); 334 int sqlite3OsOpenReadOnly(const char*, OsFile**); 335 int sqlite3OsDelete(const char*); 336 int sqlite3OsFileExists(const char*); 337 char *sqlite3OsFullPathname(const char*); 338 int sqlite3OsIsDirWritable(char*); 339 int sqlite3OsSyncDirectory(const char*); 340 int sqlite3OsTempFileName(char*); 341 int sqlite3OsRandomSeed(char*); 342 int sqlite3OsSleep(int ms); 343 int sqlite3OsCurrentTime(double*); 344 void sqlite3OsEnterMutex(void); 345 void sqlite3OsLeaveMutex(void); 346 int sqlite3OsInMutex(int); 347 ThreadData *sqlite3OsThreadSpecificData(int); 348 void *sqlite3OsMalloc(int); 349 void *sqlite3OsRealloc(void *, int); 350 void sqlite3OsFree(void *); 351 int sqlite3OsAllocationSize(void *); 352 353 /* 354 ** If the SQLITE_ENABLE_REDEF_IO macro is defined, then the OS-layer 355 ** interface routines are not called directly but are invoked using 356 ** pointers to functions. This allows the implementation of various 357 ** OS-layer interface routines to be modified at run-time. There are 358 ** obscure but legitimate reasons for wanting to do this. But for 359 ** most users, a direct call to the underlying interface is preferable 360 ** so the the redefinable I/O interface is turned off by default. 361 */ 362 #ifdef SQLITE_ENABLE_REDEF_IO 363 364 /* 365 ** When redefinable I/O is enabled, a single global instance of the 366 ** following structure holds pointers to the routines that SQLite 367 ** uses to talk with the underlying operating system. Modify this 368 ** structure (before using any SQLite API!) to accomodate perculiar 369 ** operating system interfaces or behaviors. 370 */ 371 struct sqlite3OsVtbl { 372 int (*xOpenReadWrite)(const char*, OsFile**, int*); 373 int (*xOpenExclusive)(const char*, OsFile**, int); 374 int (*xOpenReadOnly)(const char*, OsFile**); 375 376 int (*xDelete)(const char*); 377 int (*xFileExists)(const char*); 378 char *(*xFullPathname)(const char*); 379 int (*xIsDirWritable)(char*); 380 int (*xSyncDirectory)(const char*); 381 int (*xTempFileName)(char*); 382 383 int (*xRandomSeed)(char*); 384 int (*xSleep)(int ms); 385 int (*xCurrentTime)(double*); 386 387 void (*xEnterMutex)(void); 388 void (*xLeaveMutex)(void); 389 int (*xInMutex)(int); 390 ThreadData *(*xThreadSpecificData)(int); 391 392 void *(*xMalloc)(int); 393 void *(*xRealloc)(void *, int); 394 void (*xFree)(void *); 395 int (*xAllocationSize)(void *); 396 }; 397 398 /* Macro used to comment out routines that do not exists when there is 399 ** no disk I/O 400 */ 401 #ifdef SQLITE_OMIT_DISKIO 402 # define IF_DISKIO(X) 0 403 #else 404 # define IF_DISKIO(X) X 405 #endif 406 407 #ifdef _SQLITE_OS_C_ 408 /* 409 ** The os.c file implements the global virtual function table. 410 */ 411 struct sqlite3OsVtbl sqlite3Os = { 412 IF_DISKIO( sqlite3OsOpenReadWrite ), 413 IF_DISKIO( sqlite3OsOpenExclusive ), 414 IF_DISKIO( sqlite3OsOpenReadOnly ), 415 IF_DISKIO( sqlite3OsDelete ), 416 IF_DISKIO( sqlite3OsFileExists ), 417 IF_DISKIO( sqlite3OsFullPathname ), 418 IF_DISKIO( sqlite3OsIsDirWritable ), 419 IF_DISKIO( sqlite3OsSyncDirectory ), 420 IF_DISKIO( sqlite3OsTempFileName ), 421 sqlite3OsRandomSeed, 422 sqlite3OsSleep, 423 sqlite3OsCurrentTime, 424 sqlite3OsEnterMutex, 425 sqlite3OsLeaveMutex, 426 sqlite3OsInMutex, 427 sqlite3OsThreadSpecificData, 428 sqlite3OsMalloc, 429 sqlite3OsRealloc, 430 sqlite3OsFree, 431 sqlite3OsAllocationSize 432 }; 433 #else 434 /* 435 ** Files other than os.c just reference the global virtual function table. 436 */ 437 extern struct sqlite3OsVtbl sqlite3Os; 438 #endif /* _SQLITE_OS_C_ */ 439 440 441 /* This additional API routine is available with redefinable I/O */ 442 struct sqlite3OsVtbl *sqlite3_os_switch(void); 443 444 445 /* 446 ** Redefine the OS interface to go through the virtual function table 447 ** rather than calling routines directly. 448 */ 449 #undef sqlite3OsOpenReadWrite 450 #undef sqlite3OsOpenExclusive 451 #undef sqlite3OsOpenReadOnly 452 #undef sqlite3OsDelete 453 #undef sqlite3OsFileExists 454 #undef sqlite3OsFullPathname 455 #undef sqlite3OsIsDirWritable 456 #undef sqlite3OsSyncDirectory 457 #undef sqlite3OsTempFileName 458 #undef sqlite3OsRandomSeed 459 #undef sqlite3OsSleep 460 #undef sqlite3OsCurrentTime 461 #undef sqlite3OsEnterMutex 462 #undef sqlite3OsLeaveMutex 463 #undef sqlite3OsInMutex 464 #undef sqlite3OsThreadSpecificData 465 #undef sqlite3OsMalloc 466 #undef sqlite3OsRealloc 467 #undef sqlite3OsFree 468 #undef sqlite3OsAllocationSize 469 #define sqlite3OsOpenReadWrite sqlite3Os.xOpenReadWrite 470 #define sqlite3OsOpenExclusive sqlite3Os.xOpenExclusive 471 #define sqlite3OsOpenReadOnly sqlite3Os.xOpenReadOnly 472 #define sqlite3OsDelete sqlite3Os.xDelete 473 #define sqlite3OsFileExists sqlite3Os.xFileExists 474 #define sqlite3OsFullPathname sqlite3Os.xFullPathname 475 #define sqlite3OsIsDirWritable sqlite3Os.xIsDirWritable 476 #define sqlite3OsSyncDirectory sqlite3Os.xSyncDirectory 477 #define sqlite3OsTempFileName sqlite3Os.xTempFileName 478 #define sqlite3OsRandomSeed sqlite3Os.xRandomSeed 479 #define sqlite3OsSleep sqlite3Os.xSleep 480 #define sqlite3OsCurrentTime sqlite3Os.xCurrentTime 481 #define sqlite3OsEnterMutex sqlite3Os.xEnterMutex 482 #define sqlite3OsLeaveMutex sqlite3Os.xLeaveMutex 483 #define sqlite3OsInMutex sqlite3Os.xInMutex 484 #define sqlite3OsThreadSpecificData sqlite3Os.xThreadSpecificData 485 #define sqlite3OsMalloc sqlite3Os.xMalloc 486 #define sqlite3OsRealloc sqlite3Os.xRealloc 487 #define sqlite3OsFree sqlite3Os.xFree 488 #define sqlite3OsAllocationSize sqlite3Os.xAllocationSize 489 490 #endif /* SQLITE_ENABLE_REDEF_IO */ 491 492 #endif /* _SQLITE_OS_H_ */ 493