Debian Codegraph @

www/c3ref/vfs.html

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