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 MacOS. 22 ** 23 ** N.B. MacOS means Mac Classic (or Carbon). Treat Darwin (OS X) as Unix. 24 ** The MacOS build is designed to use CodeWarrior (tested with v8) 25 */ 26 #if !defined(OS_UNIX) && !defined(OS_TEST) && !defined(OS_OTHER) 27 # define OS_OTHER 0 28 # ifndef OS_WIN 29 # if defined(_WIN32) || defined(WIN32) || defined(__CYGWIN__) || defined(__MINGW32__) || defined(__BORLANDC__) 30 # define OS_WIN 1 31 # define OS_UNIX 0 32 # else 33 # define OS_WIN 0 34 # define OS_UNIX 1 35 # endif 36 # else 37 # define OS_UNIX 0 38 # endif 39 #else 40 # ifndef OS_WIN 41 # define OS_WIN 0 42 # endif 43 #endif 44 45 /* 46 ** Invoke the appropriate operating-system specific header file. 47 */ 48 #if OS_TEST 49 # include "os_test.h" 50 #endif 51 #if OS_UNIX 52 # include "os_unix.h" 53 #endif 54 #if OS_WIN 55 # include "os_win.h" 56 #endif 57 58 /* os_other.c and os_other.h are not delivered with SQLite. These files 59 ** are place-holders that can be filled in by third-party developers to 60 ** implement backends to their on proprietary operating systems. 61 */ 62 #if OS_OTHER 63 # include "os_other.h" 64 #endif 65 66 /* If the SET_FULLSYNC macro is not defined above, then make it 67 ** a no-op 68 */ 69 #ifndef SET_FULLSYNC 70 # define SET_FULLSYNC(x,y) 71 #endif 72 73 /* 74 ** Temporary files are named starting with this prefix followed by 16 random 75 ** alphanumeric characters, and no file extension. They are stored in the 76 ** OS's standard temporary file directory, and are deleted prior to exit. 77 ** If sqlite is being embedded in another program, you may wish to change the 78 ** prefix to reflect your program's name, so that if your program exits 79 ** prematurely, old temporary files can be easily identified. This can be done 80 ** using -DTEMP_FILE_PREFIX=myprefix_ on the compiler command line. 81 */ 82 #ifndef TEMP_FILE_PREFIX 83 # define TEMP_FILE_PREFIX "sqlite_" 84 #endif 85 86 /* 87 ** The following values may be passed as the second argument to 88 ** sqlite3OsLock(). The various locks exhibit the following semantics: 89 ** 90 ** SHARED: Any number of processes may hold a SHARED lock simultaneously. 91 ** RESERVED: A single process may hold a RESERVED lock on a file at 92 ** any time. Other processes may hold and obtain new SHARED locks. 93 ** PENDING: A single process may hold a PENDING lock on a file at 94 ** any one time. Existing SHARED locks may persist, but no new 95 ** SHARED locks may be obtained by other processes. 96 ** EXCLUSIVE: An EXCLUSIVE lock precludes all other locks. 97 ** 98 ** PENDING_LOCK may not be passed directly to sqlite3OsLock(). Instead, a 99 ** process that requests an EXCLUSIVE lock may actually obtain a PENDING 100 ** lock. This can be upgraded to an EXCLUSIVE lock by a subsequent call to 101 ** sqlite3OsLock(). 102 */ 103 #define NO_LOCK 0 104 #define SHARED_LOCK 1 105 #define RESERVED_LOCK 2 106 #define PENDING_LOCK 3 107 #define EXCLUSIVE_LOCK 4 108 109 /* 110 ** File Locking Notes: (Mostly about windows but also some info for Unix) 111 ** 112 ** We cannot use LockFileEx() or UnlockFileEx() on Win95/98/ME because 113 ** those functions are not available. So we use only LockFile() and 114 ** UnlockFile(). 115 ** 116 ** LockFile() prevents not just writing but also reading by other processes. 117 ** A SHARED_LOCK is obtained by locking a single randomly-chosen 118 ** byte out of a specific range of bytes. The lock byte is obtained at 119 ** random so two separate readers can probably access the file at the 120 ** same time, unless they are unlucky and choose the same lock byte. 121 ** An EXCLUSIVE_LOCK is obtained by locking all bytes in the range. 122 ** There can only be one writer. A RESERVED_LOCK is obtained by locking 123 ** a single byte of the file that is designated as the reserved lock byte. 124 ** A PENDING_LOCK is obtained by locking a designated byte different from 125 ** the RESERVED_LOCK byte. 126 ** 127 ** On WinNT/2K/XP systems, LockFileEx() and UnlockFileEx() are available, 128 ** which means we can use reader/writer locks. When reader/writer locks 129 ** are used, the lock is placed on the same range of bytes that is used 130 ** for probabilistic locking in Win95/98/ME. Hence, the locking scheme 131 ** will support two or more Win95 readers or two or more WinNT readers. 132 ** But a single Win95 reader will lock out all WinNT readers and a single 133 ** WinNT reader will lock out all other Win95 readers. 134 ** 135 ** The following #defines specify the range of bytes used for locking. 136 ** SHARED_SIZE is the number of bytes available in the pool from which 137 ** a random byte is selected for a shared lock. The pool of bytes for 138 ** shared locks begins at SHARED_FIRST. 139 ** 140 ** These #defines are available in os.h so that Unix can use the same 141 ** byte ranges for locking. This leaves open the possiblity of having 142 ** clients on win95, winNT, and unix all talking to the same shared file 143 ** and all locking correctly. To do so would require that samba (or whatever 144 ** tool is being used for file sharing) implements locks correctly between 145 ** windows and unix. I'm guessing that isn't likely to happen, but by 146 ** using the same locking range we are at least open to the possibility. 147 ** 148 ** Locking in windows is manditory. For this reason, we cannot store 149 ** actual data in the bytes used for locking. The pager never allocates 150 ** the pages involved in locking therefore. SHARED_SIZE is selected so 151 ** that all locks will fit on a single page even at the minimum page size. 152 ** PENDING_BYTE defines the beginning of the locks. By default PENDING_BYTE 153 ** is set high so that we don't have to allocate an unused page except 154 ** for very large databases. But one should test the page skipping logic 155 ** by setting PENDING_BYTE low and running the entire regression suite. 156 ** 157 ** Changing the value of PENDING_BYTE results in a subtly incompatible 158 ** file format. Depending on how it is changed, you might not notice 159 ** the incompatibility right away, even running a full regression test. 160 ** The default location of PENDING_BYTE is the first byte past the 161 ** 1GB boundary. 162 ** 163 */ 164 #define PENDING_BYTE 0x40000000 /* First byte past the 1GB boundary */ 165 /* #define PENDING_BYTE 0x5400 // Page 22 - for testing */ 166 #define RESERVED_BYTE (PENDING_BYTE+1) 167 #define SHARED_FIRST (PENDING_BYTE+2) 168 #define SHARED_SIZE 510 169 170 171 int sqlite3OsDelete(const char*); 172 int sqlite3OsFileExists(const char*); 173 int sqlite3OsOpenReadWrite(const char*, OsFile*, int*); 174 int sqlite3OsOpenExclusive(const char*, OsFile*, int); 175 int sqlite3OsOpenReadOnly(const char*, OsFile*); 176 int sqlite3OsOpenDirectory(const char*, OsFile*); 177 int sqlite3OsSyncDirectory(const char*); 178 int sqlite3OsTempFileName(char*); 179 int sqlite3OsIsDirWritable(char*); 180 int sqlite3OsClose(OsFile*); 181 int sqlite3OsRead(OsFile*, void*, int amt); 182 int sqlite3OsWrite(OsFile*, const void*, int amt); 183 int sqlite3OsSeek(OsFile*, i64 offset); 184 int sqlite3OsSync(OsFile*); 185 int sqlite3OsTruncate(OsFile*, i64 size); 186 int sqlite3OsFileSize(OsFile*, i64 *pSize); 187 char *sqlite3OsFullPathname(const char*); 188 int sqlite3OsLock(OsFile*, int); 189 int sqlite3OsUnlock(OsFile*, int); 190 int sqlite3OsCheckReservedLock(OsFile *id); 191 192 193 /* The interface for file I/O is above. Other miscellaneous functions 194 ** are below */ 195 196 int sqlite3OsRandomSeed(char*); 197 int sqlite3OsSleep(int ms); 198 int sqlite3OsCurrentTime(double*); 199 void sqlite3OsEnterMutex(void); 200 void sqlite3OsLeaveMutex(void); 201 202 #endif /* _SQLITE_OS_H_ */ 203