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 | ** Attempt to automatically detect the operating system and setup the |
25 | ** necessary pre-processor macros for it. |
26 | */ |
27 | #include "os_setup.h" |
28 | |
29 | /* If the SET_FULLSYNC macro is not defined above, then make it |
30 | ** a no-op |
31 | */ |
32 | #ifndef SET_FULLSYNC |
33 | # define SET_FULLSYNC(x,y) |
34 | #endif |
35 | |
36 | /* Maximum pathname length. Note: FILENAME_MAX defined by stdio.h |
37 | */ |
38 | #ifndef SQLITE_MAX_PATHLEN |
39 | # define SQLITE_MAX_PATHLEN FILENAME_MAX |
40 | #endif |
41 | |
42 | /* Maximum number of symlinks that will be resolved while trying to |
43 | ** expand a filename in xFullPathname() in the VFS. |
44 | */ |
45 | #ifndef SQLITE_MAX_SYMLINK |
46 | # define SQLITE_MAX_SYMLINK 200 |
47 | #endif |
48 | |
49 | /* |
50 | ** The default size of a disk sector |
51 | */ |
52 | #ifndef SQLITE_DEFAULT_SECTOR_SIZE |
53 | # define SQLITE_DEFAULT_SECTOR_SIZE 4096 |
54 | #endif |
55 | |
56 | /* |
57 | ** Temporary files are named starting with this prefix followed by 16 random |
58 | ** alphanumeric characters, and no file extension. They are stored in the |
59 | ** OS's standard temporary file directory, and are deleted prior to exit. |
60 | ** If sqlite is being embedded in another program, you may wish to change the |
61 | ** prefix to reflect your program's name, so that if your program exits |
62 | ** prematurely, old temporary files can be easily identified. This can be done |
63 | ** using -DSQLITE_TEMP_FILE_PREFIX=myprefix_ on the compiler command line. |
64 | ** |
65 | ** 2006-10-31: The default prefix used to be "sqlite_". But then |
66 | ** Mcafee started using SQLite in their anti-virus product and it |
67 | ** started putting files with the "sqlite" name in the c:/temp folder. |
68 | ** This annoyed many windows users. Those users would then do a |
69 | ** Google search for "sqlite", find the telephone numbers of the |
70 | ** developers and call to wake them up at night and complain. |
71 | ** For this reason, the default name prefix is changed to be "sqlite" |
72 | ** spelled backwards. So the temp files are still identified, but |
73 | ** anybody smart enough to figure out the code is also likely smart |
74 | ** enough to know that calling the developer will not help get rid |
75 | ** of the file. |
76 | */ |
77 | #ifndef SQLITE_TEMP_FILE_PREFIX |
78 | # define SQLITE_TEMP_FILE_PREFIX "etilqs_" |
79 | #endif |
80 | |
81 | /* |
82 | ** The following values may be passed as the second argument to |
83 | ** sqlite3OsLock(). The various locks exhibit the following semantics: |
84 | ** |
85 | ** SHARED: Any number of processes may hold a SHARED lock simultaneously. |
86 | ** RESERVED: A single process may hold a RESERVED lock on a file at |
87 | ** any time. Other processes may hold and obtain new SHARED locks. |
88 | ** PENDING: A single process may hold a PENDING lock on a file at |
89 | ** any one time. Existing SHARED locks may persist, but no new |
90 | ** SHARED locks may be obtained by other processes. |
91 | ** EXCLUSIVE: An EXCLUSIVE lock precludes all other locks. |
92 | ** |
93 | ** PENDING_LOCK may not be passed directly to sqlite3OsLock(). Instead, a |
94 | ** process that requests an EXCLUSIVE lock may actually obtain a PENDING |
95 | ** lock. This can be upgraded to an EXCLUSIVE lock by a subsequent call to |
96 | ** sqlite3OsLock(). |
97 | */ |
98 | #define NO_LOCK 0 |
99 | #define SHARED_LOCK 1 |
100 | #define RESERVED_LOCK 2 |
101 | #define PENDING_LOCK 3 |
102 | #define EXCLUSIVE_LOCK 4 |
103 | |
104 | /* |
105 | ** File Locking Notes: (Mostly about windows but also some info for Unix) |
106 | ** |
107 | ** We cannot use LockFileEx() or UnlockFileEx() on Win95/98/ME because |
108 | ** those functions are not available. So we use only LockFile() and |
109 | ** UnlockFile(). |
110 | ** |
111 | ** LockFile() prevents not just writing but also reading by other processes. |
112 | ** A SHARED_LOCK is obtained by locking a single randomly-chosen |
113 | ** byte out of a specific range of bytes. The lock byte is obtained at |
114 | ** random so two separate readers can probably access the file at the |
115 | ** same time, unless they are unlucky and choose the same lock byte. |
116 | ** An EXCLUSIVE_LOCK is obtained by locking all bytes in the range. |
117 | ** There can only be one writer. A RESERVED_LOCK is obtained by locking |
118 | ** a single byte of the file that is designated as the reserved lock byte. |
119 | ** A PENDING_LOCK is obtained by locking a designated byte different from |
120 | ** the RESERVED_LOCK byte. |
121 | ** |
122 | ** On WinNT/2K/XP systems, LockFileEx() and UnlockFileEx() are available, |
123 | ** which means we can use reader/writer locks. When reader/writer locks |
124 | ** are used, the lock is placed on the same range of bytes that is used |
125 | ** for probabilistic locking in Win95/98/ME. Hence, the locking scheme |
126 | ** will support two or more Win95 readers or two or more WinNT readers. |
127 | ** But a single Win95 reader will lock out all WinNT readers and a single |
128 | ** WinNT reader will lock out all other Win95 readers. |
129 | ** |
130 | ** The following #defines specify the range of bytes used for locking. |
131 | ** SHARED_SIZE is the number of bytes available in the pool from which |
132 | ** a random byte is selected for a shared lock. The pool of bytes for |
133 | ** shared locks begins at SHARED_FIRST. |
134 | ** |
135 | ** The same locking strategy and |
136 | ** byte ranges are used for Unix. This leaves open the possibility of having |
137 | ** clients on win95, winNT, and unix all talking to the same shared file |
138 | ** and all locking correctly. To do so would require that samba (or whatever |
139 | ** tool is being used for file sharing) implements locks correctly between |
140 | ** windows and unix. I'm guessing that isn't likely to happen, but by |
141 | ** using the same locking range we are at least open to the possibility. |
142 | ** |
143 | ** Locking in windows is manditory. For this reason, we cannot store |
144 | ** actual data in the bytes used for locking. The pager never allocates |
145 | ** the pages involved in locking therefore. SHARED_SIZE is selected so |
146 | ** that all locks will fit on a single page even at the minimum page size. |
147 | ** PENDING_BYTE defines the beginning of the locks. By default PENDING_BYTE |
148 | ** is set high so that we don't have to allocate an unused page except |
149 | ** for very large databases. But one should test the page skipping logic |
150 | ** by setting PENDING_BYTE low and running the entire regression suite. |
151 | ** |
152 | ** Changing the value of PENDING_BYTE results in a subtly incompatible |
153 | ** file format. Depending on how it is changed, you might not notice |
154 | ** the incompatibility right away, even running a full regression test. |
155 | ** The default location of PENDING_BYTE is the first byte past the |
156 | ** 1GB boundary. |
157 | ** |
158 | */ |
159 | #ifdef SQLITE_OMIT_WSD |
160 | # define PENDING_BYTE (0x40000000) |
161 | #else |
162 | # define PENDING_BYTE sqlite3PendingByte |
163 | #endif |
164 | #define RESERVED_BYTE (PENDING_BYTE+1) |
165 | #define SHARED_FIRST (PENDING_BYTE+2) |
166 | #define SHARED_SIZE 510 |
167 | |
168 | /* |
169 | ** Wrapper around OS specific sqlite3_os_init() function. |
170 | */ |
171 | int sqlite3OsInit(void); |
172 | |
173 | /* |
174 | ** Functions for accessing sqlite3_file methods |
175 | */ |
176 | void sqlite3OsClose(sqlite3_file*); |
177 | int sqlite3OsRead(sqlite3_file*, void*, int amt, i64 offset); |
178 | int sqlite3OsWrite(sqlite3_file*, const void*, int amt, i64 offset); |
179 | int sqlite3OsTruncate(sqlite3_file*, i64 size); |
180 | int sqlite3OsSync(sqlite3_file*, int); |
181 | int sqlite3OsFileSize(sqlite3_file*, i64 *pSize); |
182 | int sqlite3OsLock(sqlite3_file*, int); |
183 | int sqlite3OsUnlock(sqlite3_file*, int); |
184 | int sqlite3OsCheckReservedLock(sqlite3_file *id, int *pResOut); |
185 | int sqlite3OsFileControl(sqlite3_file*,int,void*); |
186 | void sqlite3OsFileControlHint(sqlite3_file*,int,void*); |
187 | #define SQLITE_FCNTL_DB_UNCHANGED 0xca093fa0 |
188 | int sqlite3OsSectorSize(sqlite3_file *id); |
189 | int sqlite3OsDeviceCharacteristics(sqlite3_file *id); |
190 | #ifndef SQLITE_OMIT_WAL |
191 | int sqlite3OsShmMap(sqlite3_file *,int,int,int,void volatile **); |
192 | int sqlite3OsShmLock(sqlite3_file *id, int, int, int); |
193 | void sqlite3OsShmBarrier(sqlite3_file *id); |
194 | int sqlite3OsShmUnmap(sqlite3_file *id, int); |
195 | #endif /* SQLITE_OMIT_WAL */ |
196 | int sqlite3OsFetch(sqlite3_file *id, i64, int, void **); |
197 | int sqlite3OsUnfetch(sqlite3_file *, i64, void *); |
198 | |
199 | |
200 | /* |
201 | ** Functions for accessing sqlite3_vfs methods |
202 | */ |
203 | int sqlite3OsOpen(sqlite3_vfs *, const char *, sqlite3_file*, int, int *); |
204 | int sqlite3OsDelete(sqlite3_vfs *, const char *, int); |
205 | int sqlite3OsAccess(sqlite3_vfs *, const char *, int, int *pResOut); |
206 | int sqlite3OsFullPathname(sqlite3_vfs *, const char *, int, char *); |
207 | #ifndef SQLITE_OMIT_LOAD_EXTENSION |
208 | void *sqlite3OsDlOpen(sqlite3_vfs *, const char *); |
209 | void sqlite3OsDlError(sqlite3_vfs *, int, char *); |
210 | void (*sqlite3OsDlSym(sqlite3_vfs *, void *, const char *))(void); |
211 | void sqlite3OsDlClose(sqlite3_vfs *, void *); |
212 | #endif /* SQLITE_OMIT_LOAD_EXTENSION */ |
213 | int sqlite3OsRandomness(sqlite3_vfs *, int, char *); |
214 | int sqlite3OsSleep(sqlite3_vfs *, int); |
215 | int sqlite3OsGetLastError(sqlite3_vfs*); |
216 | int sqlite3OsCurrentTimeInt64(sqlite3_vfs *, sqlite3_int64*); |
217 | |
218 | /* |
219 | ** Convenience functions for opening and closing files using |
220 | ** sqlite3_malloc() to obtain space for the file-handle structure. |
221 | */ |
222 | int sqlite3OsOpenMalloc(sqlite3_vfs *, const char *, sqlite3_file **, int,int*); |
223 | void sqlite3OsCloseFree(sqlite3_file *); |
224 | |
225 | #endif /* _SQLITE_OS_H_ */ |
226 | |