1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
|
<!DOCTYPE html>
<html><head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link href="../sqlite.css" rel="stylesheet">
<title>OS Interface Object</title>
<!-- path=../ -->
</head>
<body>
<div class=nosearch>
<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite" border="0">
</a>
<div><!-- IE hack to prevent disappearing logo --></div>
<div class="tagline desktoponly">
Small. Fast. Reliable.<br>Choose any three.
</div>
<div class="menu mainmenu">
<ul>
<li><a href="../index.html">Home</a>
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
<li class='wideonly'><a href='../about.html'>About</a>
<li class='desktoponly'><a href="../docs.html">Documentation</a>
<li class='desktoponly'><a href="../download.html">Download</a>
<li class='wideonly'><a href='../copyright.html'>License</a>
<li class='desktoponly'><a href="../support.html">Support</a>
<li class='desktoponly'><a href="../prosupport.html">Purchase</a>
<li class='search' id='search_menubutton'>
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
</ul>
</div>
<div class="menu submenu" id="submenu">
<ul>
<li><a href='../about.html'>About</a>
<li><a href='../docs.html'>Documentation</a>
<li><a href='../download.html'>Download</a>
<li><a href='../support.html'>Support</a>
<li><a href='../prosupport.html'>Purchase</a>
</ul>
</div>
<div class="searchmenu" id="searchmenu">
<form method="GET" action="../search">
<select name="s" id="searchtype">
<option value="d">Search Documentation</option>
<option value="c">Search Changelog</option>
</select>
<input type="text" name="q" id="searchbox" value="">
<input type="submit" value="Go">
</form>
</div>
</div>
<script>
function toggle_div(nm) {
var w = document.getElementById(nm);
if( w.style.display=="block" ){
w.style.display = "none";
}else{
w.style.display = "block";
}
}
function toggle_search() {
var w = document.getElementById("searchmenu");
if( w.style.display=="block" ){
w.style.display = "none";
} else {
w.style.display = "block";
setTimeout(function(){
document.getElementById("searchbox").focus()
}, 30);
}
}
function div_off(nm){document.getElementById(nm).style.display="none";}
window.onbeforeunload = function(e){div_off("submenu");}
/* Disable the Search feature if we are not operating from CGI, since */
/* Search is accomplished using CGI and will not work without it. */
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
document.getElementById("search_menubutton").style.display = "none";
}
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
function hideorshow(btn,obj){
var x = document.getElementById(obj);
var b = document.getElementById(btn);
if( x.style.display!='none' ){
x.style.display = 'none';
b.innerHTML='show';
}else{
x.style.display = '';
b.innerHTML='hide';
}
return false;
}
var antiRobot = 0;
function antiRobotGo(){
if( antiRobot!=3 ) return;
antiRobot = 7;
var j = document.getElementById("mtimelink");
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
}
function antiRobotDefense(){
document.body.onmousedown=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousedown=null;
}
document.body.onmousemove=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousemove=null;
}
setTimeout(function(){
antiRobot |= 1;
antiRobotGo();
}, 100)
antiRobotGo();
}
antiRobotDefense();
</script>
<!-- keywords: sqlite3_vfs -->
<div class=nosearch>
<a href="intro.html"><h2>SQLite C Interface</h2></a>
<h2>OS Interface Object</h2>
</div>
<blockquote><pre>
typedef struct sqlite3_vfs sqlite3_vfs;
typedef void (*sqlite3_syscall_ptr)(void);
struct sqlite3_vfs {
int iVersion; /* Structure version number (currently 3) */
int szOsFile; /* Size of subclassed sqlite3_file */
int mxPathname; /* Maximum file pathname length */
sqlite3_vfs *pNext; /* Next registered VFS */
const char *zName; /* Name of this virtual file system */
void *pAppData; /* Pointer to application-specific data */
int (*xOpen)(sqlite3_vfs*, sqlite3_filename zName, sqlite3_file*,
int flags, int *pOutFlags);
int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
void (*xDlClose)(sqlite3_vfs*, void*);
int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
int (*xSleep)(sqlite3_vfs*, int microseconds);
int (*xCurrentTime)(sqlite3_vfs*, double*);
int (*xGetLastError)(sqlite3_vfs*, int, char *);
/*
** The methods above are in version 1 of the sqlite_vfs object
** definition. Those that follow are added in version 2 or later
*/
int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
/*
** The methods above are in versions 1 and 2 of the sqlite_vfs object.
** Those below are for version 3 and greater.
*/
int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
/*
** The methods above are in versions 1 through 3 of the sqlite_vfs object.
** New fields may be appended in future versions. The iVersion
** value will increment whenever this happens.
*/
};
</pre></blockquote>
<p>
An instance of the sqlite3_vfs object defines the interface between
the SQLite core and the underlying operating system. The "vfs"
in the name of the object stands for "virtual file system". See
the <a href="../vfs.html">VFS documentation</a> for further information.</p>
<p>The VFS interface is sometimes extended by adding new methods onto
the end. Each time such an extension occurs, the iVersion field
is incremented. The iVersion value started out as 1 in
SQLite <a href="../releaselog/3_5_0.html">version 3.5.0</a> on 2007-09-04, then increased to 2
with SQLite <a href="../releaselog/3_7_0.html">version 3.7.0</a> on 2010-07-21, and then increased
to 3 with SQLite <a href="../releaselog/3_7_6.html">version 3.7.6</a> on 2011-04-12. Additional fields
may be appended to the sqlite3_vfs object and the iVersion value
may increase again in future versions of SQLite.
Note that due to an oversight, the structure
of the sqlite3_vfs object changed in the transition from
SQLite <a href="../releaselog/3_5_9.html">version 3.5.9</a> to <a href="../releaselog/3_6_0.html">version 3.6.0</a> on 2008-07-16
and yet the iVersion field was not increased.</p>
<p>The szOsFile field is the size of the subclassed <a href="../c3ref/file.html">sqlite3_file</a>
structure used by this VFS. mxPathname is the maximum length of
a pathname in this VFS.</p>
<p>Registered sqlite3_vfs objects are kept on a linked list formed by
the pNext pointer. The <a href="../c3ref/vfs_find.html">sqlite3_vfs_register()</a>
and <a href="../c3ref/vfs_find.html">sqlite3_vfs_unregister()</a> interfaces manage this list
in a thread-safe way. The <a href="../c3ref/vfs_find.html">sqlite3_vfs_find()</a> interface
searches the list. Neither the application code nor the VFS
implementation should use the pNext pointer.</p>
<p>The pNext field is the only field in the sqlite3_vfs
structure that SQLite will ever modify. SQLite will only access
or modify this field while holding a particular static mutex.
The application should never modify anything within the sqlite3_vfs
object once the object has been registered.</p>
<p>The zName field holds the name of the VFS module. The name must
be unique across all VFS modules.</p>
<p><a name="sqlite3vfsxopen"></a>
SQLite guarantees that the zFilename parameter to xOpen
is either a NULL pointer or string obtained
from xFullPathname() with an optional suffix added.
If a suffix is added to the zFilename parameter, it will
consist of a single "-" character followed by no more than
11 alphanumeric and/or "-" characters.
SQLite further guarantees that
the string will be valid and unchanged until xClose() is
called. Because of the previous sentence,
the <a href="../c3ref/file.html">sqlite3_file</a> can safely store a pointer to the
filename if it needs to remember the filename for some reason.
If the zFilename parameter to xOpen is a NULL pointer then xOpen
must invent its own temporary name for the file. Whenever the
xFilename parameter is NULL it will also be the case that the
flags parameter will include <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_DELETEONCLOSE</a>.</p>
<p>The flags argument to xOpen() includes all bits set in
the flags argument to <a href="../c3ref/open.html">sqlite3_open_v2()</a>. Or if <a href="../c3ref/open.html">sqlite3_open()</a>
or <a href="../c3ref/open.html">sqlite3_open16()</a> is used, then flags includes at least
<a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READWRITE</a> | <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_CREATE</a>.
If xOpen() opens a file read-only then it sets *pOutFlags to
include <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READONLY</a>. Other bits in *pOutFlags may be set.</p>
<p>SQLite will also add one of the following flags to the xOpen()
call, depending on the object being opened:</p>
<p><ul>
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_MAIN_DB</a>
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_MAIN_JOURNAL</a>
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_TEMP_DB</a>
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_TEMP_JOURNAL</a>
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_TRANSIENT_DB</a>
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_SUBJOURNAL</a>
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_SUPER_JOURNAL</a>
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_WAL</a>
</ul></p>
<p>The file I/O implementation can use the object type flags to
change the way it deals with files. For example, an application
that does not care about crash recovery or rollback might make
the open of a journal file a no-op. Writes to this journal would
also be no-ops, and any attempt to read the journal would return
SQLITE_IOERR. Or the implementation might recognize that a database
file will be doing page-aligned sector reads and writes in a random
order and set up its I/O subsystem accordingly.</p>
<p>SQLite might also add one of the following flags to the xOpen method:</p>
<p><ul>
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_DELETEONCLOSE</a>
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_EXCLUSIVE</a>
</ul></p>
<p>The <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_DELETEONCLOSE</a> flag means the file should be
deleted when it is closed. The <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_DELETEONCLOSE</a>
will be set for TEMP databases and their journals, transient
databases, and subjournals.</p>
<p>The <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_EXCLUSIVE</a> flag is always used in conjunction
with the <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_CREATE</a> flag, which are both directly
analogous to the O_EXCL and O_CREAT flags of the POSIX open()
API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
SQLITE_OPEN_CREATE, is used to indicate that file should always
be created, and that it is an error if it already exists.
It is <i>not</i> used to indicate the file should be opened
for exclusive access.</p>
<p>At least szOsFile bytes of memory are allocated by SQLite
to hold the <a href="../c3ref/file.html">sqlite3_file</a> structure passed as the third
argument to xOpen. The xOpen method does not have to
allocate the structure; it should just fill it in. Note that
the xOpen method must set the sqlite3_file.pMethods to either
a valid <a href="../c3ref/io_methods.html">sqlite3_io_methods</a> object or to NULL. xOpen must do
this even if the open fails. SQLite expects that the sqlite3_file.pMethods
element will be valid after xOpen returns regardless of the success
or failure of the xOpen call.</p>
<p><a name="sqlite3vfsxaccess"></a>
The flags argument to xAccess() may be <a href="../c3ref/c_access_exists.html">SQLITE_ACCESS_EXISTS</a>
to test for the existence of a file, or <a href="../c3ref/c_access_exists.html">SQLITE_ACCESS_READWRITE</a> to
test whether a file is readable and writable, or <a href="../c3ref/c_access_exists.html">SQLITE_ACCESS_READ</a>
to test whether a file is at least readable. The SQLITE_ACCESS_READ
flag is never actually used and is not implemented in the built-in
VFSes of SQLite. The file is named by the second argument and can be a
directory. The xAccess method returns <a href="../rescode.html#ok">SQLITE_OK</a> on success or some
non-zero error code if there is an I/O error or if the name of
the file given in the second argument is illegal. If SQLITE_OK
is returned, then non-zero or zero is written into *pResOut to indicate
whether or not the file is accessible.</p>
<p>SQLite will always allocate at least mxPathname+1 bytes for the
output buffer xFullPathname. The exact size of the output buffer
is also passed as a parameter to both methods. If the output buffer
is not large enough, <a href="../rescode.html#cantopen">SQLITE_CANTOPEN</a> should be returned. Since this is
handled as a fatal error by SQLite, vfs implementations should endeavor
to prevent this by setting mxPathname to a sufficiently large value.</p>
<p>The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
interfaces are not strictly a part of the filesystem, but they are
included in the VFS structure for completeness.
The xRandomness() function attempts to return nBytes bytes
of good-quality randomness into zOut. The return value is
the actual number of bytes of randomness obtained.
The xSleep() method causes the calling thread to sleep for at
least the number of microseconds given. The xCurrentTime()
method returns a Julian Day Number for the current date and time as
a floating point value.
The xCurrentTimeInt64() method returns, as an integer, the Julian
Day Number multiplied by 86400000 (the number of milliseconds in
a 24-hour day).
SQLite will use the xCurrentTimeInt64() method to get the current
date and time if that method is available (if iVersion is 2 or
greater and the function pointer is not NULL) and will fall back
to xCurrentTime() if xCurrentTimeInt64() is unavailable.</p>
<p>The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
are not used by the SQLite core. These optional interfaces are provided
by some VFSes to facilitate testing of the VFS code. By overriding
system calls with functions under its control, a test program can
simulate faults and error conditions that would otherwise be difficult
or impossible to induce. The set of system calls that can be overridden
varies from one VFS to another, and from one version of the same VFS to the
next. Applications that use these interfaces must be prepared for any
or all of these interfaces to be NULL or for their behavior to change
from one release to the next. Applications must not attempt to access
any of these methods if the iVersion of the VFS is less than 3.
</p><p>See also lists of
<a href="objlist.html">Objects</a>,
<a href="constlist.html">Constants</a>, and
<a href="funclist.html">Functions</a>.</p>
|
