Debian Codegraph @

www/34to35.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>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