| 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>SQLite Changes From Version 3.4.2 To 3.5.0</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 |
<?xml version="1.0" encoding="Windows-1252"?> |
| 119 |
|
| 120 |
<h1> Moving From SQLite 3.4.2 to 3.5.0</h1><p> |
| 121 |
SQLite version 3.5.0 (2007-09-04) introduces a new OS interface layer that |
| 122 |
is incompatible with all prior versions of SQLite. In addition, |
| 123 |
a few existing interfaces have been generalized to work across all |
| 124 |
database connections within a process rather than just all |
| 125 |
connections within a thread. The purpose of this article |
| 126 |
is to describe the changes to 3.5.0 in detail so that users |
| 127 |
of prior versions of SQLite can judge what, if any, effort will |
| 128 |
be required to upgrade to newer versions. |
| 129 |
</p> |
| 130 |
<h2>1.0 Overview Of Changes</h2><p> |
| 131 |
A quick enumeration of the changes in SQLite version 3.5.0 |
| 132 |
is provided here. Subsequent sections will describe these |
| 133 |
changes in more detail. |
| 134 |
</p> |
| 135 |
<p> |
| 136 |
<ol> |
| 137 |
<li>The OS interface layer has been completely reworked: |
| 138 |
<ol type="a"> |
| 139 |
<li>The undocumented <b>sqlite3_os_switch()</b> interface has |
| 140 |
been removed.</li> |
| 141 |
<li>The <b>SQLITE_ENABLE_REDEF_IO</b> compile-time flag no longer functions. |
| 142 |
I/O procedures are now always redefinable.</li> |
| 143 |
<li>Three new objects are defined for specifying I/O procedures: |
| 144 |
<a href="c3ref/vfs.html">sqlite3_vfs</a>, <a href="c3ref/file.html">sqlite3_file</a>, and <a href="c3ref/io_methods.html">sqlite3_io_methods</a>.</li> |
| 145 |
<li>Three new interfaces are used to create alternative OS interfaces: |
| 146 |
<a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a>, <a href="c3ref/vfs_find.html">sqlite3_vfs_unregister()</a>, and |
| 147 |
<a href="c3ref/vfs_find.html">sqlite3_vfs_find()</a>.</li> |
| 148 |
<li>A new interface has been added to provide additional control over |
| 149 |
the creation of new database connections: <a href="c3ref/open.html">sqlite3_open_v2()</a>. |
| 150 |
The legacy interfaces of <a href="c3ref/open.html">sqlite3_open()</a> and |
| 151 |
<a href="c3ref/open.html">sqlite3_open16()</a> continue to be fully supported.</li> |
| 152 |
</ol></li> |
| 153 |
<li>The optional shared cache and memory management features that |
| 154 |
were introduced in version 3.3.0 can now be used across multiple |
| 155 |
threads within the same process. Formerly, these extensions only |
| 156 |
applied to database connections operating within a single thread. |
| 157 |
<ol type="a"> |
| 158 |
<li>The <a href="c3ref/enable_shared_cache.html">sqlite3_enable_shared_cache()</a> interface now applies to all |
| 159 |
threads within a process, not to just the one thread in which it |
| 160 |
was run.</li> |
| 161 |
<li>The <a href="c3ref/soft_heap_limit.html">sqlite3_soft_heap_limit()</a> interface now applies to all threads |
| 162 |
within a process, not to just the one thread in which it was run.</li> |
| 163 |
<li>The <a href="c3ref/release_memory.html">sqlite3_release_memory()</a> interface will now attempt to reduce |
| 164 |
the memory usages across all database connections in all threads, not |
| 165 |
just connections in the thread where the interface is called.</li> |
| 166 |
<li>The <a href="c3ref/aggregate_count.html">sqlite3_thread_cleanup()</a> interface has become a no-op.</li> |
| 167 |
</ol></li> |
| 168 |
<li>Restrictions on the use of the same database connection by multiple |
| 169 |
threads have been dropped. It is now safe for |
| 170 |
multiple threads to use the same database connection at the same |
| 171 |
time.</li> |
| 172 |
<li>There is now a compile-time option that allows an application to |
| 173 |
define alternative malloc()/free() implementations without having |
| 174 |
to modify any core SQLite code.</li> |
| 175 |
<li>There is now a compile-time option that allows an application to |
| 176 |
define alternative mutex implementations without having |
| 177 |
to modify any core SQLite code.</li> |
| 178 |
</ol> |
| 179 |
</p> |
| 180 |
<p> |
| 181 |
Of these changes, only 1a and 2a through 2c are incompatibilities |
| 182 |
in any formal sense. |
| 183 |
But users who have previously made custom modifications to the |
| 184 |
SQLite source (for example to add a custom OS layer for embedded |
| 185 |
hardware) might find that these changes have a larger impact. |
| 186 |
On the other hand, an important goal of these changes is to make |
| 187 |
it much easier to customize SQLite for use on different operating |
| 188 |
systems. |
| 189 |
</p> |
| 190 |
<h2>2.0 The OS Interface Layer</h2><p> |
| 191 |
If your system defines a custom OS interface for SQLite or if you |
| 192 |
were using the undocumented <b>sqlite3_os_switch()</b> |
| 193 |
interface, then you will need to make modifications in order to |
| 194 |
upgrade to SQLite version 3.5.0. This may seem painful at first |
| 195 |
glance. But as you look more closely, you will probably discover |
| 196 |
that your changes are made smaller and easier to understand and manage |
| 197 |
by the new SQLite interface. It is likely that your changes will |
| 198 |
now also work seamlessly with the SQLite amalgamation. You will |
| 199 |
no longer need to make any changes to the core SQLite source code. |
| 200 |
All of your changes can be effected by application code and you can |
| 201 |
link against a standard, unmodified version of the SQLite amalgamation. |
| 202 |
Furthermore, the OS interface layer, which was formerly undocumented, |
| 203 |
is now an officially supported interface for SQLite. So you have |
| 204 |
some assurance that this will be a one-time change and that your |
| 205 |
new backend will continue to work in future versions of SQLite. |
| 206 |
</p> |
| 207 |
<h3>2.1 The Virtual File System Object</h3><p> |
| 208 |
The new OS interface for SQLite is built around an object named |
| 209 |
<a href="c3ref/vfs.html">sqlite3_vfs</a>. The "vfs" stands for "Virtual File System". |
| 210 |
The sqlite3_vfs object is basically a structure containing pointers |
| 211 |
to functions that implement the primitive disk I/O operations that |
| 212 |
SQLite needs to perform in order to read and write databases. |
| 213 |
In this article, we will often refer to an sqlite3_vfs objects as a "VFS". |
| 214 |
</p> |
| 215 |
<p> |
| 216 |
SQLite is able to use multiple VFSes at the same time. Each |
| 217 |
individual database connection is associated with just one VFS. |
| 218 |
But if you have multiple database connections, each connection |
| 219 |
can be associated with a different VFS. |
| 220 |
</p> |
| 221 |
<p> |
| 222 |
There is always a default VFS. |
| 223 |
The legacy interfaces <a href="c3ref/open.html">sqlite3_open()</a> and <a href="c3ref/open.html">sqlite3_open16()</a> always |
| 224 |
use the default VFS. |
| 225 |
The new interface for creating database connections, |
| 226 |
<a href="c3ref/open.html">sqlite3_open_v2()</a>, allows you to specify which VFS you want to |
| 227 |
use by name. |
| 228 |
</p> |
| 229 |
<h4>2.1.1 Registering New VFS Objects</h4><p> |
| 230 |
Standard builds of SQLite for Unix or Windows come with a single |
| 231 |
VFS named "unix" or "win32", as appropriate. This one VFS is also |
| 232 |
the default. So if you are using the legacy open functions, everything |
| 233 |
will continue to operate as it has before. The change is that an application |
| 234 |
now has the flexibility of adding new VFS modules to implement a |
| 235 |
customized OS layer. The <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a> API can be used |
| 236 |
to tell SQLite about one or more application-defined VFS modules: |
| 237 |
</p> |
| 238 |
<blockquote><pre> |
| 239 |
int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); |
| 240 |
</pre></blockquote><p> |
| 241 |
Applications can call sqlite3_vfs_register() at any time, though of course |
| 242 |
a VFS needs to be registered before it can be used. The first argument |
| 243 |
is a pointer to a customized VFS object that the application has prepared. |
| 244 |
Set the second argument to true to make the new VFS the default VFS so that |
| 245 |
it will be used by the legacy <a href="c3ref/open.html">sqlite3_open()</a> and <a href="c3ref/open.html">sqlite3_open16()</a> APIs. |
| 246 |
If the new VFS is not the default, then you will probably have to use |
| 247 |
the new <a href="c3ref/open.html">sqlite3_open_v2()</a> API to use it. Note, however, that if |
| 248 |
a new VFS is the only VFS known to SQLite (if SQLite was compiled without |
| 249 |
its usual default VFS or if the precompiled default VFS was removed |
| 250 |
using <a href="c3ref/vfs_find.html">sqlite3_vfs_unregister()</a>) then the new VFS automatically becomes the |
| 251 |
default VFS regardless of the makeDflt argument to <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a>. |
| 252 |
</p> |
| 253 |
<p> |
| 254 |
Standard builds include the default "unix" or "win32" VFSes. |
| 255 |
But if you use the -DOS_OTHER=1 compile-time option, then SQLite is |
| 256 |
built without a default VFS. In that case, the application must |
| 257 |
register at least one VFS prior to calling <a href="c3ref/open.html">sqlite3_open()</a>. |
| 258 |
This is the approach that embedded applications should use. |
| 259 |
Rather than modifying the SQLite source to insert an alternative |
| 260 |
OS layer as was done in prior releases of SQLite, instead compile |
| 261 |
an unmodified SQLite source file (preferably the amalgamation) |
| 262 |
with the -DOS_OTHER=1 option, then invoke <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a> |
| 263 |
to define the interface to the underlying filesystem prior to |
| 264 |
creating any database connections. |
| 265 |
</p> |
| 266 |
<h4>2.1.2 Additional Control Over VFS Objects</h4><p> |
| 267 |
The <a href="c3ref/vfs_find.html">sqlite3_vfs_unregister()</a> API is used to remove an existing |
| 268 |
VFS from the system. |
| 269 |
</p> |
| 270 |
<blockquote><pre> |
| 271 |
int sqlite3_vfs_unregister(sqlite3_vfs*); |
| 272 |
</pre></blockquote><p> |
| 273 |
The <a href="c3ref/vfs_find.html">sqlite3_vfs_find()</a> API is used to locate a particular VFS |
| 274 |
by name. Its prototype is as follows: |
| 275 |
</p> |
| 276 |
<blockquote><pre> |
| 277 |
sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); |
| 278 |
</pre></blockquote><p> |
| 279 |
The argument is the symbolic name for the desired VFS. If the |
| 280 |
argument is a NULL pointer, then the default VFS is returned. |
| 281 |
The function returns a pointer to the <a href="c3ref/vfs.html">sqlite3_vfs</a> object that |
| 282 |
implements the VFS. Or it returns a NULL pointer if no object |
| 283 |
could be found that matched the search criteria. |
| 284 |
</p> |
| 285 |
<h4>2.1.3 Modifications Of Existing VFSes</h4><p> |
| 286 |
Once a VFS has been registered, it should never be modified. If |
| 287 |
a change in behavior is required, a new VFS should be registered. |
| 288 |
The application could, perhaps, use <a href="c3ref/vfs_find.html">sqlite3_vfs_find()</a> to locate |
| 289 |
the old VFS, make a copy of the old VFS into a new <a href="c3ref/vfs.html">sqlite3_vfs</a> |
| 290 |
object, make the desired modifications to the new VFS, unregister |
| 291 |
the old VFS, then register the new VFS in its place. Existing |
| 292 |
database connections would continue to use the old VFS even after |
| 293 |
it is unregistered, but new database connections would use the |
| 294 |
new VFS. |
| 295 |
</p> |
| 296 |
<h4>2.1.4 The VFS Object</h4><p> |
| 297 |
A VFS object is an instance of the following structure: |
| 298 |
</p> |
| 299 |
<blockquote><pre> |
| 300 |
typedef struct sqlite3_vfs sqlite3_vfs; |
| 301 |
struct sqlite3_vfs { |
| 302 |
int iVersion; /* Structure version number */ |
| 303 |
int szOsFile; /* Size of subclassed sqlite3_file */ |
| 304 |
int mxPathname; /* Maximum file pathname length */ |
| 305 |
sqlite3_vfs *pNext; /* Next registered VFS */ |
| 306 |
const char *zName; /* Name of this virtual file system */ |
| 307 |
void *pAppData; /* Pointer to application-specific data */ |
| 308 |
int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*, |
| 309 |
int flags, int *pOutFlags); |
| 310 |
int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir); |
| 311 |
int (*xAccess)(sqlite3_vfs*, const char *zName, int flags); |
| 312 |
int (*xGetTempName)(sqlite3_vfs*, char *zOut); |
| 313 |
int (*xFullPathname)(sqlite3_vfs*, const char *zName, char *zOut); |
| 314 |
void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename); |
| 315 |
void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg); |
| 316 |
void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol); |
| 317 |
void (*xDlClose)(sqlite3_vfs*, void*); |
| 318 |
int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut); |
| 319 |
int (*xSleep)(sqlite3_vfs*, int microseconds); |
| 320 |
int (*xCurrentTime)(sqlite3_vfs*, double*); |
| 321 |
/* New fields may be appended in figure versions. The iVersion |
| 322 |
** value will increment whenever this happens. */ |
| 323 |
}; |
| 324 |
</pre></blockquote><p> |
| 325 |
To create a new VFS, an application fills in an instance of this |
| 326 |
structure with appropriate values and then calls <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a>. |
| 327 |
</p> |
| 328 |
<p> |
| 329 |
The iVersion field of <a href="c3ref/vfs.html">sqlite3_vfs</a> should be 1 for SQLite version 3.5.0. |
| 330 |
This number may increase in future versions of SQLite if we have to |
| 331 |
modify the VFS object in some way. We hope that this never happens, |
| 332 |
but the provision is made in case it does. |
| 333 |
</p> |
| 334 |
<p> |
| 335 |
The szOsFile field is the size in bytes of the structure that defines |
| 336 |
an open file: the <a href="c3ref/file.html">sqlite3_file</a> object. This object will be described |
| 337 |
more fully below. The point here is that each VFS implementation can |
| 338 |
define its own <a href="c3ref/file.html">sqlite3_file</a> object containing whatever information |
| 339 |
the VFS implementation needs to store about an open file. SQLite needs |
| 340 |
to know how big this object is, however, in order to preallocate enough |
| 341 |
space to hold it. |
| 342 |
</p> |
| 343 |
<p> |
| 344 |
The mxPathname field is the maximum length of a file pathname that |
| 345 |
this VFS can use. SQLite sometimes has to preallocate buffers of |
| 346 |
this size, so it should be as small as reasonably possible. Some |
| 347 |
filesystems permit huge pathnames, but in practice pathnames rarely |
| 348 |
extend beyond 100 bytes or so. You do not have to put the longest |
| 349 |
pathname that the underlying filesystem can handle here. You only |
| 350 |
have to put the longest pathname that you want SQLite to be able to |
| 351 |
handle. A few hundred is a good value in most cases. |
| 352 |
</p> |
| 353 |
<p> |
| 354 |
The pNext field is used internally by SQLite. Specifically, SQLite |
| 355 |
uses this field to form a linked list of registered VFSes. |
| 356 |
</p> |
| 357 |
<p> |
| 358 |
The zName field is the symbolic name of the VFS. This is the name |
| 359 |
that the <a href="c3ref/vfs_find.html">sqlite3_vfs_find()</a> compares against when it is looking for |
| 360 |
a VFS. |
| 361 |
</p> |
| 362 |
<p> |
| 363 |
The pAppData pointer is unused by the SQLite core. The pointer is |
| 364 |
available to store auxiliary information that a VFS information might |
| 365 |
want to carry around. |
| 366 |
</p> |
| 367 |
<p> |
| 368 |
The remaining fields of the <a href="c3ref/vfs.html">sqlite3_vfs</a> object all store pointers |
| 369 |
to functions that implement primitive operations. We call these |
| 370 |
"methods". The first method, xOpen, is used to open files on |
| 371 |
the underlying storage media. The result is an <a href="c3ref/file.html">sqlite3_file</a> |
| 372 |
object. There are additional methods, defined by the <a href="c3ref/file.html">sqlite3_file</a> |
| 373 |
object itself that are used to read and write and close the file. |
| 374 |
The additional methods are detailed below. The filename is in UTF-8. |
| 375 |
SQLite will guarantee that the zFilename string passed to |
| 376 |
xOpen() is a full pathname as generated by xFullPathname() and |
| 377 |
that the string will be valid and unchanged until xClose() is |
| 378 |
called. So the <a href="c3ref/file.html">sqlite3_file</a> can store a pointer to the |
| 379 |
filename if it needs to remember the filename for some reason. |
| 380 |
The flags argument to xOpen() is a copy of the flags argument |
| 381 |
to sqlite3_open_v2(). If sqlite3_open() or sqlite3_open16() |
| 382 |
is used, then flags is <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_READWRITE</a> | <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_CREATE</a>. |
| 383 |
If xOpen() opens a file read-only then it sets *pOutFlags to |
| 384 |
include <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_READONLY</a>. Other bits in *pOutFlags may be |
| 385 |
set. |
| 386 |
SQLite will also add one of the following flags to the xOpen() |
| 387 |
call, depending on the object being opened: |
| 388 |
<ul> |
| 389 |
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_MAIN_DB</a> |
| 390 |
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_MAIN_JOURNAL</a> |
| 391 |
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_TEMP_DB</a> |
| 392 |
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_TEMP_JOURNAL</a> |
| 393 |
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_TRANSIENT_DB</a> |
| 394 |
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_SUBJOURNAL</a> |
| 395 |
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_SUPER_JOURNAL</a> |
| 396 |
</ul> |
| 397 |
The file I/O implementation can use the object type flags to |
| 398 |
change the way it deals with files. For example, an application |
| 399 |
that does not care about crash recovery or rollback, might make |
| 400 |
the open of a journal file a no-op. Writes to this journal are |
| 401 |
also a no-op. Any attempt to read the journal returns <a href="rescode.html#ioerr">SQLITE_IOERR</a>. |
| 402 |
Or the implementation might recognize the a database file will |
| 403 |
be doing page-aligned sector reads and writes in a random order |
| 404 |
and set up its I/O subsystem accordingly. |
| 405 |
SQLite might also add one of the following flags to the xOpen |
| 406 |
method: |
| 407 |
<ul> |
| 408 |
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_DELETEONCLOSE</a> |
| 409 |
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_EXCLUSIVE</a> |
| 410 |
</ul> |
| 411 |
The <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_DELETEONCLOSE</a> flag means the file should be |
| 412 |
deleted when it is closed. This will always be set for TEMP |
| 413 |
databases and journals and for subjournals. The |
| 414 |
<a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_EXCLUSIVE</a> flag means the file should be opened |
| 415 |
for exclusive access. This flag is set for all files except |
| 416 |
for the main database file. |
| 417 |
The <a href="c3ref/file.html">sqlite3_file</a> structure passed as the third argument to |
| 418 |
xOpen is allocated by the caller. xOpen just fills it in. The |
| 419 |
caller allocates a minimum of szOsFile bytes for the <a href="c3ref/file.html">sqlite3_file</a> |
| 420 |
structure. |
| 421 |
</p> |
| 422 |
<p> |
| 423 |
The differences between an <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_TEMP_DB</a> database and an |
| 424 |
<a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_TRANSIENT_DB</a> database is this: The <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_TEMP_DB</a> |
| 425 |
is used for explicitly declared and named TEMP tables (using the |
| 426 |
CREATE TEMP TABLE syntax) or for named tables in a temporary database |
| 427 |
that is created by opening a database with a filename that is an empty |
| 428 |
string. An <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_TRANSIENT_DB</a> holds a database table that |
| 429 |
SQLite creates automatically in order to evaluate a subquery or |
| 430 |
ORDER BY or GROUP BY clause. Both TEMP_DB and TRANSIENT_DB databases |
| 431 |
are private and are deleted automatically. TEMP_DB databases last |
| 432 |
for the duration of the database connection. TRANSIENT_DB databases |
| 433 |
last only for the duration of a single SQL statement. |
| 434 |
</p> |
| 435 |
<p> |
| 436 |
The xDelete method is used to delete a file. The name of the file is |
| 437 |
given in the second parameter. The filename will be in UTF-8. |
| 438 |
The VFS must convert the filename into whatever character representation |
| 439 |
the underlying operating system expects. If the syncDir parameter is |
| 440 |
true, then the xDelete method should not return until the change |
| 441 |
to the directory contents for the directory containing the |
| 442 |
deleted file have been synced to disk in order to ensure that the |
| 443 |
file does not "reappear" if a power failure occurs soon after. |
| 444 |
</p> |
| 445 |
<p> |
| 446 |
The xAccess method is used to check for access permissions on a file. |
| 447 |
The filename will be UTF-8 encoded. The flags argument will be |
| 448 |
<a href="c3ref/c_access_exists.html">SQLITE_ACCESS_EXISTS</a> to check for the existence of the file, |
| 449 |
<a href="c3ref/c_access_exists.html">SQLITE_ACCESS_READWRITE</a> to check to see if the file is both readable |
| 450 |
and writable, or <a href="c3ref/c_access_exists.html">SQLITE_ACCESS_READ</a> to check to see if the file is |
| 451 |
at least readable. The "file" named by the second parameter might |
| 452 |
be a directory or folder name. |
| 453 |
</p> |
| 454 |
<p> |
| 455 |
The xGetTempName method computes the name of a temporary file that |
| 456 |
SQLite can use. The name should be written into the buffer given |
| 457 |
by the second parameter. SQLite will size that buffer to hold |
| 458 |
at least mxPathname bytes. The generated filename should be in UTF-8. |
| 459 |
To avoid security problems, the generated temporary filename should |
| 460 |
contain enough randomness to prevent an attacker from guessing the |
| 461 |
temporary filename in advance. |
| 462 |
</p> |
| 463 |
<p> |
| 464 |
The xFullPathname method is used to convert a relative pathname |
| 465 |
into a full pathname. The resulting full pathname is written into |
| 466 |
the buffer provided by the third parameter. SQLite will size the |
| 467 |
output buffer to at least mxPathname bytes. Both the input and |
| 468 |
output names should be in UTF-8. |
| 469 |
</p> |
| 470 |
<p> |
| 471 |
The xDlOpen, xDlError, xDlSym, and xDlClose methods are all used for |
| 472 |
accessing shared libraries at run-time. These methods may be omitted |
| 473 |
(and their pointers set to zero) if the library is compiled with |
| 474 |
<a href="compile.html#omit_load_extension">SQLITE_OMIT_LOAD_EXTENSION</a> or if the <a href="c3ref/enable_load_extension.html">sqlite3_enable_load_extension()</a> |
| 475 |
interface is never used to enable dynamic extension loading. The |
| 476 |
xDlOpen method opens a shared library or DLL and returns a pointer to |
| 477 |
a handle. NULL is returned if the open fails. If the open fails, |
| 478 |
the xDlError method can be used to obtain a text error message. |
| 479 |
The message is written into the zErrMsg buffer of the third parameter |
| 480 |
which is at least nByte bytes in length. The xDlSym returns a pointer |
| 481 |
to a symbol in the shared library. The name of the symbol is given |
| 482 |
by the second parameter. UTF-8 encoding is assumed. If the symbol |
| 483 |
is not found a NULL pointer is returned. The xDlClose routine closes |
| 484 |
the shared library. |
| 485 |
</p> |
| 486 |
<p> |
| 487 |
The xRandomness method is used exactly once to initialize the |
| 488 |
pseudo-random number generator (PRNG) inside of SQLite. Only |
| 489 |
the xRandomness method on the default VFS is used. The xRandomness |
| 490 |
methods on other VFSes are never accessed by SQLite. |
| 491 |
The xRandomness routine requests that nByte bytes of randomness |
| 492 |
be written into zOut. The routine returns the actual number of |
| 493 |
bytes of randomness obtained. The quality of the randomness so obtained |
| 494 |
will determine the quality of the randomness generated by built-in |
| 495 |
SQLite functions such as random() and randomblob(). SQLite also |
| 496 |
uses its PRNG to generate temporary file names. On some platforms |
| 497 |
(ex: Windows) SQLite assumes that temporary file names are unique |
| 498 |
without actually testing for collisions, so it is important to have |
| 499 |
good-quality randomness even if the random() and randomblob() |
| 500 |
functions are never used. |
| 501 |
</p> |
| 502 |
<p> |
| 503 |
The xSleep method is used to suspend the calling thread for at |
| 504 |
least the number of microseconds given. This method is used to |
| 505 |
implement the <a href="c3ref/sleep.html">sqlite3_sleep()</a> and <a href="c3ref/busy_timeout.html">sqlite3_busy_timeout()</a> APIs. |
| 506 |
In the case of <a href="c3ref/sleep.html">sqlite3_sleep()</a> the xSleep method of the default |
| 507 |
VFS is always used. If the underlying system does not have a |
| 508 |
microsecond resolution sleep capability, then the sleep time should |
| 509 |
be rounded up. xSleep returns this rounded-up value. |
| 510 |
</p> |
| 511 |
<p> |
| 512 |
The xCurrentTime method finds the current time and date and writes |
| 513 |
the result as a double-precision floating point value into a pointer |
| 514 |
provided by the second parameter. The time and date is in |
| 515 |
coordinated universal time (UTC) and is a fractional Julian day number. |
| 516 |
</p> |
| 517 |
<h4>2.1.5 The Open File Object</h4><p> |
| 518 |
The result of opening a file is an instance of an <a href="c3ref/file.html">sqlite3_file</a> object. |
| 519 |
The <a href="c3ref/file.html">sqlite3_file</a> object is an abstract base class defined as follows: |
| 520 |
</p> |
| 521 |
<blockquote><pre> |
| 522 |
typedef struct sqlite3_file sqlite3_file; |
| 523 |
struct sqlite3_file { |
| 524 |
const struct sqlite3_io_methods *pMethods; |
| 525 |
}; |
| 526 |
</pre></blockquote><p> |
| 527 |
Each VFS implementation will subclass the <a href="c3ref/file.html">sqlite3_file</a> by adding |
| 528 |
additional fields at the end to hold whatever information the VFS |
| 529 |
needs to know about an open file. It does not matter what information |
| 530 |
is stored as long as the total size of the structure does not exceed |
| 531 |
the szOsFile value recorded in the <a href="c3ref/vfs.html">sqlite3_vfs</a> object. |
| 532 |
</p> |
| 533 |
<p> |
| 534 |
The <a href="c3ref/io_methods.html">sqlite3_io_methods</a> object is a structure that contains pointers |
| 535 |
to methods for reading, writing, and otherwise dealing with files. |
| 536 |
This object is defined as follows: |
| 537 |
</p> |
| 538 |
<blockquote><pre> |
| 539 |
typedef struct sqlite3_io_methods sqlite3_io_methods; |
| 540 |
struct sqlite3_io_methods { |
| 541 |
int iVersion; |
| 542 |
int (*xClose)(sqlite3_file*); |
| 543 |
int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst); |
| 544 |
int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst); |
| 545 |
int (*xTruncate)(sqlite3_file*, sqlite3_int64 size); |
| 546 |
int (*xSync)(sqlite3_file*, int flags); |
| 547 |
int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize); |
| 548 |
int (*xLock)(sqlite3_file*, int); |
| 549 |
int (*xUnlock)(sqlite3_file*, int); |
| 550 |
int (*xCheckReservedLock)(sqlite3_file*); |
| 551 |
int (*xFileControl)(sqlite3_file*, int op, void *pArg); |
| 552 |
int (*xSectorSize)(sqlite3_file*); |
| 553 |
int (*xDeviceCharacteristics)(sqlite3_file*); |
| 554 |
/* Additional methods may be added in future releases */ |
| 555 |
}; |
| 556 |
</pre></blockquote><p> |
| 557 |
The iVersion field of <a href="c3ref/io_methods.html">sqlite3_io_methods</a> is provided as insurance |
| 558 |
against future enhancements. The iVersion value should always be |
| 559 |
1 for SQLite version 3.5. |
| 560 |
</p> |
| 561 |
<p> |
| 562 |
The xClose method closes the file. The space for the <a href="c3ref/file.html">sqlite3_file</a> |
| 563 |
structure is deallocated by the caller. But if the <a href="c3ref/file.html">sqlite3_file</a> |
| 564 |
contains pointers to other allocated memory or resources, those |
| 565 |
allocations should be released by the xClose method. |
| 566 |
</p> |
| 567 |
<p> |
| 568 |
The xRead method reads iAmt bytes from the file beginning at a byte |
| 569 |
offset to iOfst. The data read is stored in the pointer of the |
| 570 |
second parameter. xRead returns the <a href="rescode.html#ok">SQLITE_OK</a> on success, |
| 571 |
<a href="rescode.html#ioerr_short_read">SQLITE_IOERR_SHORT_READ</a> if it was not able to read the full number |
| 572 |
of bytes because it reached end-of-file, or <a href="rescode.html#ioerr_read">SQLITE_IOERR_READ</a> for |
| 573 |
any other error. |
| 574 |
</p> |
| 575 |
<p> |
| 576 |
The xWrite method writes iAmt bytes of data from the second parameter |
| 577 |
into the file beginning at an offset of iOfst bytes. If the size of |
| 578 |
the file is less than iOfst bytes prior to the write, then xWrite should |
| 579 |
ensure that the file is extended with zeros up to iOfst bytes prior |
| 580 |
to beginning its write. xWrite should extend the file as |
| 581 |
necessary so that the size of the file is at least iAmt+iOfst bytes |
| 582 |
at the conclusion of the xWrite call. The xWrite method returns |
| 583 |
<a href="rescode.html#ok">SQLITE_OK</a> on success. If the write cannot complete because the |
| 584 |
underlying storage medium is full, then <a href="rescode.html#full">SQLITE_FULL</a> is returned. |
| 585 |
<a href="rescode.html#ioerr_write">SQLITE_IOERR_WRITE</a> should be returned for any other error. |
| 586 |
</p> |
| 587 |
<p> |
| 588 |
The xTruncate method truncates a file to be nByte bytes in length. |
| 589 |
If the file is already nByte bytes or less in length then this |
| 590 |
method is a no-op. The xTruncate method returns <a href="rescode.html#ok">SQLITE_OK</a> on |
| 591 |
success and <a href="rescode.html#ioerr_truncate">SQLITE_IOERR_TRUNCATE</a> if anything goes wrong. |
| 592 |
</p> |
| 593 |
<p> |
| 594 |
The xSync method is used to force previously written data out of |
| 595 |
operating system cache and into non-volatile memory. The second |
| 596 |
parameter is usually <a href="c3ref/c_sync_dataonly.html">SQLITE_SYNC_NORMAL</a>. If the second parameter |
| 597 |
is <a href="c3ref/c_sync_dataonly.html">SQLITE_SYNC_FULL</a> then the xSync method should make sure that |
| 598 |
data has also been flushed through the disk controllers cache. |
| 599 |
The <a href="c3ref/c_sync_dataonly.html">SQLITE_SYNC_FULL</a> parameter is the equivalent of the F_FULLSYNC |
| 600 |
ioctl() on Mac OS X. The xSync method returns |
| 601 |
<a href="rescode.html#ok">SQLITE_OK</a> on success and <a href="rescode.html#ioerr_fsync">SQLITE_IOERR_FSYNC</a> if anything goes wrong. |
| 602 |
</p> |
| 603 |
<p> |
| 604 |
The xFileSize() method determines the current size of the file |
| 605 |
in bytes and writes that value into *pSize. It returns <a href="rescode.html#ok">SQLITE_OK</a> |
| 606 |
on success and <a href="rescode.html#ioerr_fstat">SQLITE_IOERR_FSTAT</a> if something goes wrong. |
| 607 |
</p> |
| 608 |
<p> |
| 609 |
The xLock and xUnlock methods are used to set and clear file locks. |
| 610 |
SQLite supports five levels of file locks, in order: |
| 611 |
<ul> |
| 612 |
<li> <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_NONE</a> |
| 613 |
<li> <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a> |
| 614 |
<li> <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_RESERVED</a> |
| 615 |
<li> <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_PENDING</a> |
| 616 |
<li> <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_EXCLUSIVE</a> |
| 617 |
</ul> |
| 618 |
The underlying implementation can support some subset of these locking |
| 619 |
levels as long as it meets the other requirements of this paragraph. |
| 620 |
The locking level is specified as the second argument to both xLock |
| 621 |
and xUnlock. The xLock method increases the locking level to the |
| 622 |
specified locking level or higher. The xUnlock method decreases the |
| 623 |
locking level to no lower than the level specified. |
| 624 |
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_NONE</a> means that the file is unlocked. <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a> |
| 625 |
gives permission to read the file. Multiple database connections can |
| 626 |
hold <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a> at the same time. |
| 627 |
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_RESERVED</a> is like <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a> in that it is permission |
| 628 |
to read the file. But only a single connection can hold a reserved lock |
| 629 |
at any point in time. The <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_PENDING</a> is also permission to |
| 630 |
read the file. Other connections can continue to read the file as well, |
| 631 |
but no other connection is allowed to escalate a lock from none to shared. |
| 632 |
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_EXCLUSIVE</a> is permission to write on the file. Only a single |
| 633 |
connection can hold an exclusive lock and no other connection can hold |
| 634 |
any lock (other than "none") while one connection holds an exclusive |
| 635 |
lock. The xLock returns <a href="rescode.html#ok">SQLITE_OK</a> on success, <a href="rescode.html#busy">SQLITE_BUSY</a> if it |
| 636 |
is unable to obtain the lock, or <a href="rescode.html#ioerr_rdlock">SQLITE_IOERR_RDLOCK</a> if something else |
| 637 |
goes wrong. The xUnlock method returns <a href="rescode.html#ok">SQLITE_OK</a> on success and |
| 638 |
<a href="rescode.html#ioerr_unlock">SQLITE_IOERR_UNLOCK</a> for problems. |
| 639 |
</p> |
| 640 |
<p> |
| 641 |
The xCheckReservedLock() method checks to see if another connection or |
| 642 |
another process is currently holding a reserved, pending, or exclusive |
| 643 |
lock on the file. It returns true or false. |
| 644 |
</p> |
| 645 |
<p> |
| 646 |
The xFileControl() method is a generic interface that allows custom |
| 647 |
VFS implementations to directly control an open file using the |
| 648 |
(new and experimental) |
| 649 |
<a href="c3ref/file_control.html">sqlite3_file_control()</a> interface. The second "op" argument |
| 650 |
is an integer opcode. The third |
| 651 |
argument is a generic pointer which is intended to be a pointer |
| 652 |
to a structure that may contain arguments or space in which to |
| 653 |
write return values. Potential uses for xFileControl() might be |
| 654 |
functions to enable blocking locks with timeouts, to change the |
| 655 |
locking strategy (for example to use dot-file locks), to inquire |
| 656 |
about the status of a lock, or to break stale locks. The SQLite |
| 657 |
core reserves opcodes less than 100 for its own use. |
| 658 |
A <a href="c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntllockstate">list of opcodes</a> less than 100 is available. |
| 659 |
Applications that define a custom xFileControl method should use opcodes |
| 660 |
greater than 100 to avoid conflicts. |
| 661 |
</p> |
| 662 |
<p> |
| 663 |
The xSectorSize returns the "sector size" of the underlying |
| 664 |
non-volatile media. A "sector" is defined as the smallest unit of |
| 665 |
storage that can be written without disturbing adjacent storage. |
| 666 |
On a disk drive the "sector size" has until recently been 512 bytes, |
| 667 |
though there is a push to increase this value to 4KiB. SQLite needs |
| 668 |
to know the sector size so that it can write a full sector at a |
| 669 |
time, and thus avoid corrupting adjacent storage space if a power |
| 670 |
loss occurs in the middle of a write. |
| 671 |
</p> |
| 672 |
<p> |
| 673 |
The xDeviceCharacteristics method returns an integer bit vector that |
| 674 |
defines any special properties that the underlying storage medium might |
| 675 |
have that SQLite can use to increase performance. The allowed return |
| 676 |
is the bit-wise OR of the following values: |
| 677 |
<ul> |
| 678 |
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC</a> |
| 679 |
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC512</a> |
| 680 |
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC1K</a> |
| 681 |
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC2K</a> |
| 682 |
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC4K</a> |
| 683 |
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC8K</a> |
| 684 |
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC16K</a> |
| 685 |
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC32K</a> |
| 686 |
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC64K</a> |
| 687 |
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SAFE_APPEND</a> |
| 688 |
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SEQUENTIAL</a> |
| 689 |
</ul> |
| 690 |
The <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC</a> bit means that all writes to this device are |
| 691 |
atomic in the sense that either the entire write occurs or none of it |
| 692 |
occurs. The other |
| 693 |
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC<i>nnn</i></a> values indicate that |
| 694 |
writes of aligned blocks of the indicated size are atomic. |
| 695 |
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SAFE_APPEND</a> means that when extending a file with new |
| 696 |
data, the new data is written first and then the file size is updated. |
| 697 |
So if a power failure occurs, there is no chance that the file might have |
| 698 |
been extended with randomness. The <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SEQUENTIAL</a> bit means |
| 699 |
that all writes occur in the order that they are issued and are not |
| 700 |
reordered by the underlying file system. |
| 701 |
</p> |
| 702 |
<h4>2.1.6 Checklist For Constructing A New VFS</h4><p> |
| 703 |
The preceding paragraphs contain a lot of information. |
| 704 |
To ease the task of constructing |
| 705 |
a new VFS for SQLite we offer the following implementation checklist: |
| 706 |
</p> |
| 707 |
<p> |
| 708 |
<ol> |
| 709 |
<li> Define an appropriate subclass of the <a href="c3ref/file.html">sqlite3_file</a> object. |
| 710 |
<li> Implement the methods required by the <a href="c3ref/io_methods.html">sqlite3_io_methods</a> object. |
| 711 |
<li> Create a static and |
| 712 |
constant <a href="c3ref/io_methods.html">sqlite3_io_methods</a> object containing pointers |
| 713 |
to the methods from the previous step. |
| 714 |
<li> Implement the xOpen method that opens a file and populates an |
| 715 |
<a href="c3ref/file.html">sqlite3_file</a> object, including setting pMethods to |
| 716 |
point to the <a href="c3ref/io_methods.html">sqlite3_io_methods</a> object from the previous step. |
| 717 |
<li> Implement the other methods required by <a href="c3ref/vfs.html">sqlite3_vfs</a>. |
| 718 |
<li> Define a static (but not constant) <a href="c3ref/vfs.html">sqlite3_vfs</a> structure that |
| 719 |
contains pointers to the xOpen method and the other methods and |
| 720 |
which contains the appropriate values for iVersion, szOsFile, |
| 721 |
mxPathname, zName, and pAppData. |
| 722 |
<li> Implement a procedure that calls <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a> and |
| 723 |
passes it a pointer to the <a href="c3ref/vfs.html">sqlite3_vfs</a> structure from the previous |
| 724 |
step. This procedure is probably the only exported symbol in the |
| 725 |
source file that implements your VFS. |
| 726 |
</ol> |
| 727 |
</p> |
| 728 |
<p> |
| 729 |
Within your application, call the procedure implemented in the last |
| 730 |
step above as part of your initialization process before any |
| 731 |
database connections are opened. |
| 732 |
</p> |
| 733 |
<h2>3.0 The Memory Allocation Subsystem</h2><p> |
| 734 |
Beginning with version 3.5, SQLite obtains all of the heap memory it |
| 735 |
needs using the routines <a href="c3ref/free.html">sqlite3_malloc()</a>, <a href="c3ref/free.html">sqlite3_free()</a>, and |
| 736 |
<a href="c3ref/free.html">sqlite3_realloc()</a>. These routines have existed in prior versions |
| 737 |
of SQLite, but SQLite has previously bypassed these routines and used |
| 738 |
its own memory allocator. This all changes in version 3.5.0. |
| 739 |
</p> |
| 740 |
<p> |
| 741 |
The SQLite source tree actually contains multiple versions of the |
| 742 |
memory allocator. The default high-speed version found in the |
| 743 |
"mem1.c" source file is used for most builds. But if the SQLITE_MEMDEBUG |
| 744 |
flag is enabled, a separate memory allocator in the "mem2.c" source file |
| 745 |
is used instead. The mem2.c allocator implements lots of hooks to |
| 746 |
do error checking and to simulate memory allocation failures for testing |
| 747 |
purposes. Both of these allocators use the malloc()/free() implementation |
| 748 |
in the standard C library. |
| 749 |
</p> |
| 750 |
<p> |
| 751 |
Applications are not required to use either of these standard memory |
| 752 |
allocators. If SQLite is compiled with <a href="compile.html#omitfeatures">SQLITE_OMIT_MEMORY_ALLOCATION</a> |
| 753 |
then no implementation for the <a href="c3ref/free.html">sqlite3_malloc()</a>, <a href="c3ref/free.html">sqlite3_realloc()</a>, |
| 754 |
and <a href="c3ref/free.html">sqlite3_free()</a> functions is provided. Instead, the application |
| 755 |
that links against SQLite must provide its own implementation of these |
| 756 |
functions. The application provided memory allocator is not required |
| 757 |
to use the malloc()/free() implementation in the standard C library. |
| 758 |
An embedded application might provide an alternative memory allocator |
| 759 |
that uses memory for a fixed memory pool set aside for the exclusive |
| 760 |
use of SQLite, for example. |
| 761 |
</p> |
| 762 |
<p> |
| 763 |
Applications that implement their own memory allocator must provide |
| 764 |
implementation for the usual three allocation functions |
| 765 |
<a href="c3ref/free.html">sqlite3_malloc()</a>, <a href="c3ref/free.html">sqlite3_realloc()</a>, and <a href="c3ref/free.html">sqlite3_free()</a>. |
| 766 |
And they must also implement a fourth function: |
| 767 |
</p> |
| 768 |
<blockquote><pre> |
| 769 |
int sqlite3_memory_alarm( |
| 770 |
void(*xCallback)(void *pArg, sqlite3_int64 used, int N), |
| 771 |
void *pArg, |
| 772 |
sqlite3_int64 iThreshold |
| 773 |
); |
| 774 |
</pre></blockquote><p> |
| 775 |
The <a href="c3ref/aggregate_count.html">sqlite3_memory_alarm</a> routine is used to register |
| 776 |
a callback on memory allocation events. |
| 777 |
This routine registers or clears a callback that fires when |
| 778 |
the amount of memory allocated exceeds iThreshold. Only |
| 779 |
a single callback can be registered at a time. Each call |
| 780 |
to <a href="c3ref/aggregate_count.html">sqlite3_memory_alarm()</a> overwrites the previous callback. |
| 781 |
The callback is disabled by setting xCallback to a NULL |
| 782 |
pointer. |
| 783 |
</p> |
| 784 |
<p> |
| 785 |
The parameters to the callback are the pArg value, the |
| 786 |
amount of memory currently in use, and the size of the |
| 787 |
allocation that provoked the callback. The callback will |
| 788 |
presumably invoke <a href="c3ref/free.html">sqlite3_free()</a> to free up memory space. |
| 789 |
The callback may invoke <a href="c3ref/free.html">sqlite3_malloc()</a> or <a href="c3ref/free.html">sqlite3_realloc()</a> |
| 790 |
but if it does, no additional callbacks will be invoked by |
| 791 |
the recursive calls. |
| 792 |
</p> |
| 793 |
<p> |
| 794 |
The <a href="c3ref/soft_heap_limit.html">sqlite3_soft_heap_limit()</a> interface works by registering |
| 795 |
a memory alarm at the soft heap limit and invoking |
| 796 |
<a href="c3ref/release_memory.html">sqlite3_release_memory()</a> in the alarm callback. Application |
| 797 |
programs should not attempt to use the <a href="c3ref/aggregate_count.html">sqlite3_memory_alarm()</a> |
| 798 |
interface because doing so will interfere with the |
| 799 |
<a href="c3ref/soft_heap_limit.html">sqlite3_soft_heap_limit()</a> module. This interface is exposed |
| 800 |
only so that applications can provide their own |
| 801 |
alternative implementation when the SQLite core is |
| 802 |
compiled with <a href="compile.html#omitfeatures">SQLITE_OMIT_MEMORY_ALLOCATION</a>. |
| 803 |
</p> |
| 804 |
<p> |
| 805 |
The built-in memory allocators in SQLite also provide the following |
| 806 |
additional interfaces: |
| 807 |
</p> |
| 808 |
<blockquote><pre> |
| 809 |
sqlite3_int64 sqlite3_memory_used(void); |
| 810 |
sqlite3_int64 sqlite3_memory_highwater(int resetFlag); |
| 811 |
</pre></blockquote><p> |
| 812 |
These interfaces can be used by an application to monitor how |
| 813 |
much memory SQLite is using. The <a href="c3ref/memory_highwater.html">sqlite3_memory_used()</a> routine |
| 814 |
returns the number of bytes of memory currently in use and the |
| 815 |
<a href="c3ref/memory_highwater.html">sqlite3_memory_highwater()</a> returns the maximum instantaneous |
| 816 |
memory usage. Neither routine includes the overhead associated |
| 817 |
with the memory allocator. These routines are provided for use |
| 818 |
by the application. SQLite never invokes them itself. So if |
| 819 |
the application is providing its own memory allocation subsystem, |
| 820 |
it can omit these interfaces if desired. |
| 821 |
</p> |
| 822 |
<h2>4.0 The Mutex Subsystem</h2><p> |
| 823 |
SQLite has always been threadsafe in the sense that it is safe to |
| 824 |
use different SQLite database connections in different threads at the |
| 825 |
same time. The constraint was that the same database connection |
| 826 |
could not be used in two separate threads at once. SQLite version 3.5.0 |
| 827 |
relaxes this constraint. |
| 828 |
</p> |
| 829 |
<p> |
| 830 |
In order to allow multiple threads to use the same database connection |
| 831 |
at the same time, SQLite must make extensive use of mutexes. And for |
| 832 |
this reason a new mutex subsystem has been added. The mutex subsystem |
| 833 |
has the following interface: |
| 834 |
</p> |
| 835 |
<blockquote><pre> |
| 836 |
sqlite3_mutex *sqlite3_mutex_alloc(int); |
| 837 |
void sqlite3_mutex_free(sqlite3_mutex*); |
| 838 |
void sqlite3_mutex_enter(sqlite3_mutex*); |
| 839 |
int sqlite3_mutex_try(sqlite3_mutex*); |
| 840 |
void sqlite3_mutex_leave(sqlite3_mutex*); |
| 841 |
</pre></blockquote><p> |
| 842 |
Though these routines exist for the use of the SQLite core, |
| 843 |
application code is free to use these routines as well, if desired. |
| 844 |
A mutex is an <a href="c3ref/mutex.html">sqlite3_mutex</a> object. The <a href="c3ref/mutex_alloc.html">sqlite3_mutex_alloc()</a> |
| 845 |
routine allocates a new mutex object and returns a pointer to it. |
| 846 |
The argument to <a href="c3ref/mutex_alloc.html">sqlite3_mutex_alloc()</a> should be |
| 847 |
<a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_FAST</a> or <a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_RECURSIVE</a> for non-recursive |
| 848 |
and recursive mutexes, respectively. If the underlying system does |
| 849 |
not provide non-recursive mutexes, then a recursive mutex can be |
| 850 |
substituted in that case. The argument to <a href="c3ref/mutex_alloc.html">sqlite3_mutex_alloc()</a> |
| 851 |
can also be a constant designating one of several static mutexes: |
| 852 |
<ul> |
| 853 |
<li> <a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_MAIN</a> |
| 854 |
<li> <a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_MEM</a> |
| 855 |
<li> <a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_MEM2</a> |
| 856 |
<li> <a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_PRNG</a> |
| 857 |
<li> <a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_LRU</a> |
| 858 |
</ul> |
| 859 |
These static mutexes are reserved for use internally by SQLite |
| 860 |
and should not be used by the application. The static mutexes |
| 861 |
are all non-recursive. |
| 862 |
</p> |
| 863 |
<p> |
| 864 |
The <a href="c3ref/mutex_alloc.html">sqlite3_mutex_free()</a> routine should be used to deallocate |
| 865 |
a non-static mutex. If a static mutex is passed to this routine |
| 866 |
then the behavior is undefined. |
| 867 |
</p> |
| 868 |
<p> |
| 869 |
The <a href="c3ref/mutex_alloc.html">sqlite3_mutex_enter()</a> attempts to enter the mutex and blocks |
| 870 |
if another thread is already there. <a href="c3ref/mutex_alloc.html">sqlite3_mutex_try()</a> attempts |
| 871 |
to enter and returns <a href="rescode.html#ok">SQLITE_OK</a> on success or <a href="rescode.html#busy">SQLITE_BUSY</a> if another |
| 872 |
thread is already there. <a href="c3ref/mutex_alloc.html">sqlite3_mutex_leave()</a> exits a mutex. |
| 873 |
The mutex is held until the number of exits matches the number of |
| 874 |
entrances. If <a href="c3ref/mutex_alloc.html">sqlite3_mutex_leave()</a> is called on a mutex that |
| 875 |
the thread is not currently holding, then the behavior is undefined. |
| 876 |
If any routine is called for a deallocated mutex, then the behavior |
| 877 |
is undefined. |
| 878 |
</p> |
| 879 |
<p> |
| 880 |
The SQLite source code provides multiple implementations of these |
| 881 |
APIs, suitable for varying environments. If SQLite is compiled with |
| 882 |
the SQLITE_THREADSAFE=0 flag then a no-op mutex implementation that |
| 883 |
is fast but does no real mutual exclusion is provided. That |
| 884 |
implementation is suitable for use in single-threaded applications |
| 885 |
or applications that only use SQLite in a single thread. Other |
| 886 |
real mutex implementations are provided based on the underlying |
| 887 |
operating system. |
| 888 |
</p> |
| 889 |
<p> |
| 890 |
Embedded applications may wish to provide their own mutex implementation. |
| 891 |
If SQLite is compiled with the -DSQLITE_MUTEX_APPDEF=1 compile-time flag |
| 892 |
then the SQLite core provides no mutex subsystem and a mutex subsystem |
| 893 |
that matches the interface described above must be provided by the |
| 894 |
application that links against SQLite. |
| 895 |
</p> |
| 896 |
<h2>5.0 Other Interface Changes</h2><p> |
| 897 |
Version 3.5.0 of SQLite changes the behavior of a few APIs in ways |
| 898 |
that are technically incompatible. However, these APIs are seldom |
| 899 |
used and even when they are used it is difficult to imagine a |
| 900 |
scenario where the change might break something. The changes |
| 901 |
makes these interfaces more useful and powerful. |
| 902 |
</p> |
| 903 |
<p> |
| 904 |
Prior to version 3.5.0, the <a href="c3ref/enable_shared_cache.html">sqlite3_enable_shared_cache()</a> API |
| 905 |
would enable and disable the shared cache feature for all connections |
| 906 |
within a single thread - the same thread from which the |
| 907 |
sqlite3_enable_shared_cache() routine was called. Database connections |
| 908 |
that used the shared cache were restricted to running in the same |
| 909 |
thread in which they were opened. Beginning with version 3.5.0, |
| 910 |
the sqlite3_enable_shared_cache() applies to all database connections |
| 911 |
in all threads within the process. Now database connections running |
| 912 |
in separate threads can share a cache. And database connections that |
| 913 |
use shared cache can migrate from one thread to another. |
| 914 |
</p> |
| 915 |
<p> |
| 916 |
Prior to version 3.5.0 the <a href="c3ref/soft_heap_limit.html">sqlite3_soft_heap_limit()</a> set an upper |
| 917 |
bound on heap memory usage for all database connections within a |
| 918 |
single thread. Each thread could have its own heap limit. Beginning |
| 919 |
in version 3.5.0, there is a single heap limit for the entire process. |
| 920 |
This seems more restrictive (one limit as opposed to many) but in |
| 921 |
practice it is what most users want. |
| 922 |
</p> |
| 923 |
<p> |
| 924 |
Prior to version 3.5.0 the <a href="c3ref/release_memory.html">sqlite3_release_memory()</a> function would |
| 925 |
try to reclaim memory from all database connections in the same thread |
| 926 |
as the sqlite3_release_memory() call. Beginning with version 3.5.0, |
| 927 |
the sqlite3_release_memory() function will attempt to reclaim memory |
| 928 |
from all database connections in all threads. |
| 929 |
</p> |
| 930 |
<h2>6.0 Summary</h2><p> |
| 931 |
The transition from SQLite version 3.4.2 to 3.5.0 is a major change. |
| 932 |
Every source code file in the SQLite core had to be modified, some |
| 933 |
extensively. And the change introduced some minor incompatibilities |
| 934 |
in the C interface. But we feel that the benefits of the transition |
| 935 |
from 3.4.2 to 3.5.0 far outweigh the pain of porting. The new |
| 936 |
VFS layer is now well-defined and stable and should simplify future |
| 937 |
customizations. The VFS layer, and the separable memory allocator |
| 938 |
and mutex subsystems allow a standard SQLite source code amalgamation |
| 939 |
to be used in an embedded project without change, greatly simplifying |
| 940 |
configuration management. And the resulting system is much more |
| 941 |
tolerant of highly threaded designs. |
| 942 |
</p> |
| 943 |
|
| 944 |
<p align="center"><small><i>This page was last updated on 2025-07-12 15:11:36Z </small></i></p> |
| 945 |
|