|
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 ** This header file is #include-ed by sqliteInt.h and thus ends up |
|
18 ** being included by every source file. |
|
19 */ |
|
20 #ifndef _SQLITE_OS_H_ |
|
21 #define _SQLITE_OS_H_ |
|
22 |
|
23 /* |
|
24 ** Figure out if we are dealing with Unix, Windows, or some other |
|
25 ** operating system. After the following block of preprocess macros, |
|
26 ** all of OS_UNIX, OS_WIN, OS_OS2, and OS_OTHER will defined to either |
|
27 ** 1 or 0. One of the four will be 1. The other three will be 0. |
|
28 */ |
|
29 |
|
30 #if defined(OS_OTHER) |
|
31 |
|
32 # if OS_OTHER==1 |
|
33 # undef OS_UNIX |
|
34 # define OS_UNIX 0 |
|
35 # undef OS_WIN |
|
36 # define OS_WIN 0 |
|
37 # undef OS_OS2 |
|
38 # define OS_OS2 0 |
|
39 # else |
|
40 # undef OS_OTHER |
|
41 # endif |
|
42 #endif |
|
43 #if !defined(OS_UNIX) && !defined(OS_OTHER) && !defined(OS_SYMBIAN) |
|
44 # define OS_OTHER 0 |
|
45 # ifndef OS_WIN |
|
46 # if defined(_WIN32) || defined(WIN32) || defined(__CYGWIN__) || defined(__MINGW32__) || defined(__BORLANDC__) |
|
47 # define OS_WIN 1 |
|
48 # define OS_UNIX 0 |
|
49 # define OS_OS2 0 |
|
50 # elif defined(__EMX__) || defined(_OS2) || defined(OS2) || defined(_OS2_) || defined(__OS2__) |
|
51 # define OS_WIN 0 |
|
52 # define OS_UNIX 0 |
|
53 # define OS_OS2 1 |
|
54 # else |
|
55 # define OS_WIN 0 |
|
56 # define OS_UNIX 1 |
|
57 # define OS_OS2 0 |
|
58 # endif |
|
59 # else |
|
60 # define OS_UNIX 0 |
|
61 # define OS_OS2 0 |
|
62 # endif |
|
63 #else |
|
64 # ifndef OS_WIN |
|
65 # define OS_WIN 0 |
|
66 # endif |
|
67 #endif |
|
68 |
|
69 #ifdef OS_SYMBIAN |
|
70 # define SQLITE_TEMPNAME_SIZE (MAX_PATH+50) |
|
71 #endif |
|
72 |
|
73 |
|
74 /* |
|
75 ** Define the maximum size of a temporary filename |
|
76 */ |
|
77 #if OS_WIN |
|
78 # include <windows.h> |
|
79 # define SQLITE_TEMPNAME_SIZE (MAX_PATH+50) |
|
80 #elif OS_OS2 |
|
81 # if (__GNUC__ > 3 || __GNUC__ == 3 && __GNUC_MINOR__ >= 3) && defined(OS2_HIGH_MEMORY) |
|
82 # include <os2safe.h> /* has to be included before os2.h for linking to work */ |
|
83 # endif |
|
84 # define INCL_DOSDATETIME |
|
85 # define INCL_DOSFILEMGR |
|
86 # define INCL_DOSERRORS |
|
87 # define INCL_DOSMISC |
|
88 # define INCL_DOSPROCESS |
|
89 # define INCL_DOSMODULEMGR |
|
90 # define INCL_DOSSEMAPHORES |
|
91 # include <os2.h> |
|
92 # define SQLITE_TEMPNAME_SIZE (CCHMAXPATHCOMP) |
|
93 #else |
|
94 #ifndef SQLITE_TEMPNAME_SIZE |
|
95 # define SQLITE_TEMPNAME_SIZE 200 |
|
96 #endif |
|
97 #endif |
|
98 |
|
99 /* If the SET_FULLSYNC macro is not defined above, then make it |
|
100 ** a no-op |
|
101 */ |
|
102 #ifndef SET_FULLSYNC |
|
103 # define SET_FULLSYNC(x,y) |
|
104 #endif |
|
105 |
|
106 /* |
|
107 ** The default size of a disk sector |
|
108 */ |
|
109 #ifndef SQLITE_DEFAULT_SECTOR_SIZE |
|
110 # define SQLITE_DEFAULT_SECTOR_SIZE 512 |
|
111 #endif |
|
112 |
|
113 /* |
|
114 ** Temporary files are named starting with this prefix followed by 16 random |
|
115 ** alphanumeric characters, and no file extension. They are stored in the |
|
116 ** OS's standard temporary file directory, and are deleted prior to exit. |
|
117 ** If sqlite is being embedded in another program, you may wish to change the |
|
118 ** prefix to reflect your program's name, so that if your program exits |
|
119 ** prematurely, old temporary files can be easily identified. This can be done |
|
120 ** using -DSQLITE_TEMP_FILE_PREFIX=myprefix_ on the compiler command line. |
|
121 ** |
|
122 ** 2006-10-31: The default prefix used to be "sqlite_". But then |
|
123 ** Mcafee started using SQLite in their anti-virus product and it |
|
124 ** started putting files with the "sqlite" name in the c:/temp folder. |
|
125 ** This annoyed many windows users. Those users would then do a |
|
126 ** Google search for "sqlite", find the telephone numbers of the |
|
127 ** developers and call to wake them up at night and complain. |
|
128 ** For this reason, the default name prefix is changed to be "sqlite" |
|
129 ** spelled backwards. So the temp files are still identified, but |
|
130 ** anybody smart enough to figure out the code is also likely smart |
|
131 ** enough to know that calling the developer will not help get rid |
|
132 ** of the file. |
|
133 */ |
|
134 #ifndef SQLITE_TEMP_FILE_PREFIX |
|
135 # define SQLITE_TEMP_FILE_PREFIX "etilqs_" |
|
136 #endif |
|
137 |
|
138 /* |
|
139 ** The following values may be passed as the second argument to |
|
140 ** sqlite3OsLock(). The various locks exhibit the following semantics: |
|
141 ** |
|
142 ** SHARED: Any number of processes may hold a SHARED lock simultaneously. |
|
143 ** RESERVED: A single process may hold a RESERVED lock on a file at |
|
144 ** any time. Other processes may hold and obtain new SHARED locks. |
|
145 ** PENDING: A single process may hold a PENDING lock on a file at |
|
146 ** any one time. Existing SHARED locks may persist, but no new |
|
147 ** SHARED locks may be obtained by other processes. |
|
148 ** EXCLUSIVE: An EXCLUSIVE lock precludes all other locks. |
|
149 ** |
|
150 ** PENDING_LOCK may not be passed directly to sqlite3OsLock(). Instead, a |
|
151 ** process that requests an EXCLUSIVE lock may actually obtain a PENDING |
|
152 ** lock. This can be upgraded to an EXCLUSIVE lock by a subsequent call to |
|
153 ** sqlite3OsLock(). |
|
154 */ |
|
155 #define NO_LOCK 0 |
|
156 #define SHARED_LOCK 1 |
|
157 #define RESERVED_LOCK 2 |
|
158 #define PENDING_LOCK 3 |
|
159 #define EXCLUSIVE_LOCK 4 |
|
160 |
|
161 /* |
|
162 ** File Locking Notes: (Mostly about windows but also some info for Unix) |
|
163 ** |
|
164 ** We cannot use LockFileEx() or UnlockFileEx() on Win95/98/ME because |
|
165 ** those functions are not available. So we use only LockFile() and |
|
166 ** UnlockFile(). |
|
167 ** |
|
168 ** LockFile() prevents not just writing but also reading by other processes. |
|
169 ** A SHARED_LOCK is obtained by locking a single randomly-chosen |
|
170 ** byte out of a specific range of bytes. The lock byte is obtained at |
|
171 ** random so two separate readers can probably access the file at the |
|
172 ** same time, unless they are unlucky and choose the same lock byte. |
|
173 ** An EXCLUSIVE_LOCK is obtained by locking all bytes in the range. |
|
174 ** There can only be one writer. A RESERVED_LOCK is obtained by locking |
|
175 ** a single byte of the file that is designated as the reserved lock byte. |
|
176 ** A PENDING_LOCK is obtained by locking a designated byte different from |
|
177 ** the RESERVED_LOCK byte. |
|
178 ** |
|
179 ** On WinNT/2K/XP systems, LockFileEx() and UnlockFileEx() are available, |
|
180 ** which means we can use reader/writer locks. When reader/writer locks |
|
181 ** are used, the lock is placed on the same range of bytes that is used |
|
182 ** for probabilistic locking in Win95/98/ME. Hence, the locking scheme |
|
183 ** will support two or more Win95 readers or two or more WinNT readers. |
|
184 ** But a single Win95 reader will lock out all WinNT readers and a single |
|
185 ** WinNT reader will lock out all other Win95 readers. |
|
186 ** |
|
187 ** The following #defines specify the range of bytes used for locking. |
|
188 ** SHARED_SIZE is the number of bytes available in the pool from which |
|
189 ** a random byte is selected for a shared lock. The pool of bytes for |
|
190 ** shared locks begins at SHARED_FIRST. |
|
191 ** |
|
192 ** These #defines are available in sqlite_aux.h so that adaptors for |
|
193 ** connecting SQLite to other operating systems can use the same byte |
|
194 ** ranges for locking. In particular, the same locking strategy and |
|
195 ** byte ranges are used for Unix. This leaves open the possiblity of having |
|
196 ** clients on win95, winNT, and unix all talking to the same shared file |
|
197 ** and all locking correctly. To do so would require that samba (or whatever |
|
198 ** tool is being used for file sharing) implements locks correctly between |
|
199 ** windows and unix. I'm guessing that isn't likely to happen, but by |
|
200 ** using the same locking range we are at least open to the possibility. |
|
201 ** |
|
202 ** Locking in windows is manditory. For this reason, we cannot store |
|
203 ** actual data in the bytes used for locking. The pager never allocates |
|
204 ** the pages involved in locking therefore. SHARED_SIZE is selected so |
|
205 ** that all locks will fit on a single page even at the minimum page size. |
|
206 ** PENDING_BYTE defines the beginning of the locks. By default PENDING_BYTE |
|
207 ** is set high so that we don't have to allocate an unused page except |
|
208 ** for very large databases. But one should test the page skipping logic |
|
209 ** by setting PENDING_BYTE low and running the entire regression suite. |
|
210 ** |
|
211 ** Changing the value of PENDING_BYTE results in a subtly incompatible |
|
212 ** file format. Depending on how it is changed, you might not notice |
|
213 ** the incompatibility right away, even running a full regression test. |
|
214 ** The default location of PENDING_BYTE is the first byte past the |
|
215 ** 1GB boundary. |
|
216 ** |
|
217 */ |
|
218 #ifndef SQLITE_TEST |
|
219 #define PENDING_BYTE 0x40000000 /* First byte past the 1GB boundary */ |
|
220 #else |
|
221 extern unsigned int sqlite3_pending_byte; |
|
222 #define PENDING_BYTE sqlite3_pending_byte |
|
223 #endif |
|
224 |
|
225 #define RESERVED_BYTE (PENDING_BYTE+1) |
|
226 #define SHARED_FIRST (PENDING_BYTE+2) |
|
227 #define SHARED_SIZE 510 |
|
228 |
|
229 /* |
|
230 ** Functions for accessing sqlite3_file methods |
|
231 */ |
|
232 int sqlite3OsClose(sqlite3_file*); |
|
233 int sqlite3OsRead(sqlite3_file*, void*, int amt, i64 offset); |
|
234 int sqlite3OsWrite(sqlite3_file*, const void*, int amt, i64 offset); |
|
235 int sqlite3OsTruncate(sqlite3_file*, i64 size); |
|
236 int sqlite3OsSync(sqlite3_file*, int); |
|
237 int sqlite3OsFileSize(sqlite3_file*, i64 *pSize); |
|
238 int sqlite3OsLock(sqlite3_file*, int); |
|
239 int sqlite3OsUnlock(sqlite3_file*, int); |
|
240 int sqlite3OsCheckReservedLock(sqlite3_file *id); |
|
241 int sqlite3OsFileControl(sqlite3_file*,int,void*); |
|
242 int sqlite3OsSectorSize(sqlite3_file *id); |
|
243 int sqlite3OsDeviceCharacteristics(sqlite3_file *id); |
|
244 |
|
245 /* |
|
246 ** Functions for accessing sqlite3_vfs methods |
|
247 */ |
|
248 int sqlite3OsOpen(sqlite3_vfs *, const char *, sqlite3_file*, int, int *); |
|
249 int sqlite3OsDelete(sqlite3_vfs *, const char *, int); |
|
250 int sqlite3OsAccess(sqlite3_vfs *, const char *, int); |
|
251 int sqlite3OsGetTempname(sqlite3_vfs *, int, char *); |
|
252 int sqlite3OsFullPathname(sqlite3_vfs *, const char *, int, char *); |
|
253 void *sqlite3OsDlOpen(sqlite3_vfs *, const char *); |
|
254 void sqlite3OsDlError(sqlite3_vfs *, int, char *); |
|
255 void *sqlite3OsDlSym(sqlite3_vfs *, void *, const char *); |
|
256 void sqlite3OsDlClose(sqlite3_vfs *, void *); |
|
257 int sqlite3OsRandomness(sqlite3_vfs *, int, char *); |
|
258 int sqlite3OsSleep(sqlite3_vfs *, int); |
|
259 int sqlite3OsCurrentTime(sqlite3_vfs *, double*); |
|
260 |
|
261 /* |
|
262 ** Convenience functions for opening and closing files using |
|
263 ** sqlite3_malloc() to obtain space for the file-handle structure. |
|
264 */ |
|
265 int sqlite3OsOpenMalloc(sqlite3_vfs *, const char *, sqlite3_file **, int,int*); |
|
266 int sqlite3OsCloseFree(sqlite3_file *); |
|
267 |
|
268 /* |
|
269 ** Each OS-specific backend defines an instance of the following |
|
270 ** structure for returning a pointer to its sqlite3_vfs. If OS_OTHER |
|
271 ** is defined (meaning that the application-defined OS interface layer |
|
272 ** is used) then there is no default VFS. The application must |
|
273 ** register one or more VFS structures using sqlite3_vfs_register() |
|
274 ** before attempting to use SQLite. |
|
275 */ |
|
276 #if OS_UNIX || OS_WIN || OS_OS2 || OS_SYMBIAN |
|
277 sqlite3_vfs *sqlite3OsDefaultVfs(void); |
|
278 #else |
|
279 # define sqlite3OsDefaultVfs(X) 0 |
|
280 #endif |
|
281 |
|
282 int winDelete( |
|
283 sqlite3_vfs *pVfs, /* Not used on win32 */ |
|
284 const char *zFilename, /* Name of file to delete */ |
|
285 int syncDir /* Not used on win32 */ |
|
286 ); |
|
287 |
|
288 int winAccess( |
|
289 sqlite3_vfs *pVfs, /* Not used on win32 */ |
|
290 const char *zFilename, /* Name of file to check */ |
|
291 int flags /* Type of test to make on this file */ |
|
292 ); |
|
293 |
|
294 int winGetTempname(sqlite3_vfs *pVfs, int nBuf, char *zBuf); |
|
295 |
|
296 int winFullPathname( |
|
297 sqlite3_vfs *pVfs, /* Pointer to vfs object */ |
|
298 const char *zRelative, /* Possibly relative input path */ |
|
299 int nFull, /* Size of output buffer in bytes */ |
|
300 char *zFull /* Output buffer */ |
|
301 ); |
|
302 |
|
303 int winRandomness(sqlite3_vfs *pVfs, int nBuf, char *zBuf); |
|
304 |
|
305 int winClose(sqlite3_file *id); |
|
306 |
|
307 int winRead( |
|
308 sqlite3_file *id, /* File to read from */ |
|
309 void *pBuf, /* Write content into this buffer */ |
|
310 int amt, /* Number of bytes to read */ |
|
311 sqlite3_int64 offset /* Begin reading at this offset */ |
|
312 ); |
|
313 |
|
314 int winWrite( |
|
315 sqlite3_file *id, /* File to write into */ |
|
316 const void *pBuf, /* The bytes to be written */ |
|
317 int amt, /* Number of bytes to write */ |
|
318 sqlite3_int64 offset /* Offset into the file to begin writing at */ |
|
319 ); |
|
320 |
|
321 int winTruncate(sqlite3_file *id, sqlite3_int64 nByte); |
|
322 |
|
323 int winSync(sqlite3_file *id, int flags); |
|
324 |
|
325 int symbianFileSize(sqlite3_file *id, sqlite3_int64 *pSize); |
|
326 |
|
327 int winLock(sqlite3_file *id, int locktype); |
|
328 |
|
329 int winCheckReservedLock(sqlite3_file *id); |
|
330 |
|
331 int winUnlock(sqlite3_file *id, int locktype); |
|
332 |
|
333 int symbianFileControl(sqlite3_file *id, int op, void *pArg); |
|
334 |
|
335 int winSectorSize(sqlite3_file *id); |
|
336 |
|
337 int winDeviceCharacteristics(sqlite3_file *id); |
|
338 |
|
339 int winOpen( |
|
340 sqlite3_vfs *pVfs, /* Not used */ |
|
341 const char *zName, /* Name of the file (UTF-8) */ |
|
342 sqlite3_file *id, /* Write the SQLite file handle here */ |
|
343 int flags, /* Open mode flags */ |
|
344 int *pOutFlags /* Status return flags */ |
|
345 ); |
|
346 int winFullPathname( |
|
347 sqlite3_vfs *pVfs, /* Pointer to vfs object */ |
|
348 const char *zRelative, /* Possibly relative input path */ |
|
349 int nFull, /* Size of output buffer in bytes */ |
|
350 char *zFull /* Output buffer */ |
|
351 ); |
|
352 int winSleep(sqlite3_vfs *pVfs, int microsec); |
|
353 int winCurrentTime(sqlite3_vfs *pVfs, double *prNow); |
|
354 |
|
355 int winFileSize(sqlite3_file *id, sqlite3_int64 *pSize); |
|
356 |
|
357 int winFileControl(sqlite3_file *id, int op, void *pArg); |
|
358 |
|
359 #endif /* _SQLITE_OS_H_ */ |