Debian Codegraph @

www/capi3ref.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>C/C++ Interface For SQLite Version 3</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
119
120
121
122 <h1 align="center">
123 C-language Interface Specification for SQLite
124 </h1>
125
126 <p>This page is intended to be a precise and detailed specification.
127 For a tutorial introduction, see instead:
128 <ul>
129 <li><a href="quickstart.html">SQLite In 3 Minutes Or Less</a> and/or
130 <li>the <a href="cintro.html">Introduction To The SQLite C/C++ Interface</a>.
131 </ul>
132 This same content is also available split out into
133 <a href="../c3ref/intro.html">some smaller pages</a>.</p>
134
135 <hr>
136
137
138
139 <h2>Experimental And Deprecated Interfaces</h2>
140
141 <p>SQLite interfaces can be subdivided into three categories:</p>
142
143 <ol>
144 <li>Stable</li>
145 <li>Experimental</li>
146 <li>Deprecated</li>
147 </ol>
148
149 <p>Stable interfaces will be maintained indefinitely in a backwards
150 compatible way. An application that uses only stable interfaces
151 should always be able to relink against a newer version of SQLite
152 without any changes.</p>
153
154 <p>Experimental interfaces are subject to change.
155 Applications that use experimental interfaces
156 may need to be modified when upgrading to a newer SQLite release, though
157 this is rare.
158 When new interfaces are added to SQLite, they generally begin
159 as experimental interfaces. After an interface has been in use for
160 a while and the developers are confident that the design of the interface
161 is sound and worthy of long-term support, the interface is marked
162 as stable.</p>
163
164 <p>Deprecated interfaces have been superseded by better methods of
165 accomplishing the same thing and should be avoided in new applications.
166 Deprecated interfaces continue to be supported for the sake of
167 backwards compatibility. At some point in the future, it is possible
168 that deprecated interfaces may be removed.</p>
169
170 <p>Key points:</p>
171
172 <ul>
173 <li>Experimental interfaces are subject to change and/or removal
174 at any time.</li>
175
176 <li>Deprecated interfaces should not be used in new code and might
177 be removed in some future release.</li>
178 </ul>
179
180 <hr>
181 <h2>List Of Objects:</h2>
182 <div class='columns' style='columns: 14em auto;'>
183 <ul style='padding-top:0;'>
184 <li><a href='#sqlite3'>sqlite3</a></li>
185 <li><a href='#sqlite3_api_routines'>sqlite3_api_routines</a></li>
186 <li><a href='#sqlite3_backup'>sqlite3_backup</a></li>
187 <li><a href='#sqlite3_blob'>sqlite3_blob</a></li>
188 <li><a href='#sqlite3_context'>sqlite3_context</a></li>
189 <li><a href='#sqlite3_data_directory'>sqlite3_data_directory</a></li>
190 <li><a href='#sqlite3_file'>sqlite3_file</a></li>
191 <li><a href='#sqlite3_filename'>sqlite3_filename</a></li>
192 <li><a href='#sqlite3_index_info'>sqlite3_index_info</a></li>
193 <li><a href='#sqlite3_int64'>sqlite3_int64</a></li>
194 <li><a href='#sqlite3_int64'>sqlite3_uint64</a></li>
195 <li><a href='#sqlite3_int64'>sqlite_int64</a></li>
196 <li><a href='#sqlite3_int64'>sqlite_uint64</a></li>
197 <li><a href='#sqlite3_io_methods'>sqlite3_io_methods</a></li>
198 <li><a href='#sqlite3_mem_methods'>sqlite3_mem_methods</a></li>
199 <li><a href='#sqlite3_module'>sqlite3_module</a></li>
200 <li><a href='#sqlite3_mutex'>sqlite3_mutex</a></li>
201 <li><a href='#sqlite3_mutex_methods'>sqlite3_mutex_methods</a></li>
202 <li><a href='#sqlite3_pcache'>sqlite3_pcache</a></li>
203 <li><a href='#sqlite3_pcache_methods2'>sqlite3_pcache_methods2</a></li>
204 <li><a href='#sqlite3_pcache_page'>sqlite3_pcache_page</a></li>
205 <li><a href='#sqlite3_snapshot'>sqlite3_snapshot</a></li>
206 <li><a href='#sqlite3_stmt'>sqlite3_stmt</a></li>
207 <li><a href='#sqlite3_str'>sqlite3_str</a></li>
208 <li><a href='#sqlite3_temp_directory'>sqlite3_temp_directory</a></li>
209 <li><a href='#sqlite3_value'>sqlite3_value</a></li>
210 <li><a href='#sqlite3_vfs'>sqlite3_vfs</a></li>
211 <li><a href='#sqlite3_vtab'>sqlite3_vtab</a></li>
212 <li><a href='#sqlite3_vtab_cursor'>sqlite3_vtab_cursor</a></li>
213 </ul>
214 </div>
215 <hr>
216
217 <h2>List Of Constants:</h2>
218 <p>Also available: <a href="rescode.html">list of error codes</a></p>
219 <div class='columns' style='columns: 20em auto;'>
220 <ul style='padding-top:0;'>
221 <li><a href='#SQLITE_ABORT'>SQLITE_ABORT</a></li>
222 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_ABORT_ROLLBACK</a></li>
223 <li><a href='#SQLITE_ACCESS_EXISTS'>SQLITE_ACCESS_EXISTS</a></li>
224 <li><a href='#SQLITE_ACCESS_EXISTS'>SQLITE_ACCESS_READ</a></li>
225 <li><a href='#SQLITE_ACCESS_EXISTS'>SQLITE_ACCESS_READWRITE</a></li>
226 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_ALTER_TABLE</a></li>
227 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_ANALYZE</a></li>
228 <li><a href='#sqliteany'>SQLITE_ANY</a></li>
229 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_ATTACH</a></li>
230 <li><a href='#SQLITE_ABORT'>SQLITE_AUTH</a></li>
231 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_AUTH_USER</a></li>
232 <li><a href='#SQLITE_BLOB'>SQLITE_BLOB</a></li>
233 <li><a href='#SQLITE_ABORT'>SQLITE_BUSY</a></li>
234 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_BUSY_RECOVERY</a></li>
235 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_BUSY_SNAPSHOT</a></li>
236 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_BUSY_TIMEOUT</a></li>
237 <li><a href='#SQLITE_ABORT'>SQLITE_CANTOPEN</a></li>
238 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CANTOPEN_CONVPATH</a></li>
239 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CANTOPEN_DIRTYWAL</a></li>
240 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CANTOPEN_FULLPATH</a></li>
241 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CANTOPEN_ISDIR</a></li>
242 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CANTOPEN_NOTEMPDIR</a></li>
243 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CANTOPEN_SYMLINK</a></li>
244 <li><a href='#SQLITE_CARRAY_BLOB'>SQLITE_CARRAY_BLOB</a></li>
245 <li><a href='#SQLITE_CARRAY_BLOB'>SQLITE_CARRAY_DOUBLE</a></li>
246 <li><a href='#SQLITE_CARRAY_BLOB'>SQLITE_CARRAY_INT32</a></li>
247 <li><a href='#SQLITE_CARRAY_BLOB'>SQLITE_CARRAY_INT64</a></li>
248 <li><a href='#SQLITE_CARRAY_BLOB'>SQLITE_CARRAY_TEXT</a></li>
249 <li><a href='#SQLITE_CHECKPOINT_FULL'>SQLITE_CHECKPOINT_FULL</a></li>
250 <li><a href='#SQLITE_CHECKPOINT_FULL'>SQLITE_CHECKPOINT_NOOP</a></li>
251 <li><a href='#SQLITE_CHECKPOINT_FULL'>SQLITE_CHECKPOINT_PASSIVE</a></li>
252 <li><a href='#SQLITE_CHECKPOINT_FULL'>SQLITE_CHECKPOINT_RESTART</a></li>
253 <li><a href='#SQLITE_CHECKPOINT_FULL'>SQLITE_CHECKPOINT_TRUNCATE</a></li>
254 <li><a href='#sqliteconfigcoveringindexscan'>SQLITE_CONFIG_COVERING_INDEX_SCAN</a></li>
255 <li><a href='#sqliteconfiggetmalloc'>SQLITE_CONFIG_GETMALLOC</a></li>
256 <li><a href='#sqliteconfiggetmutex'>SQLITE_CONFIG_GETMUTEX</a></li>
257 <li><a href='#sqliteconfiggetpcache'>SQLITE_CONFIG_GETPCACHE</a></li>
258 <li><a href='#sqliteconfiggetpcache2'>SQLITE_CONFIG_GETPCACHE2</a></li>
259 <li><a href='#sqliteconfigheap'>SQLITE_CONFIG_HEAP</a></li>
260 <li><a href='#sqliteconfiglog'>SQLITE_CONFIG_LOG</a></li>
261 <li><a href='#sqliteconfiglookaside'>SQLITE_CONFIG_LOOKASIDE</a></li>
262 <li><a href='#sqliteconfigmalloc'>SQLITE_CONFIG_MALLOC</a></li>
263 <li><a href='#sqliteconfigmemdbmaxsize'>SQLITE_CONFIG_MEMDB_MAXSIZE</a></li>
264 <li><a href='#sqliteconfigmemstatus'>SQLITE_CONFIG_MEMSTATUS</a></li>
265 <li><a href='#sqliteconfigmmapsize'>SQLITE_CONFIG_MMAP_SIZE</a></li>
266 <li><a href='#sqliteconfigmultithread'>SQLITE_CONFIG_MULTITHREAD</a></li>
267 <li><a href='#sqliteconfigmutex'>SQLITE_CONFIG_MUTEX</a></li>
268 <li><a href='#sqliteconfigpagecache'>SQLITE_CONFIG_PAGECACHE</a></li>
269 <li><a href='#sqliteconfigpcache'>SQLITE_CONFIG_PCACHE</a></li>
270 <li><a href='#sqliteconfigpcache2'>SQLITE_CONFIG_PCACHE2</a></li>
271 <li><a href='#sqliteconfigpcachehdrsz'>SQLITE_CONFIG_PCACHE_HDRSZ</a></li>
272 <li><a href='#sqliteconfigpmasz'>SQLITE_CONFIG_PMASZ</a></li>
273 <li><a href='#sqliteconfigrowidinview'>SQLITE_CONFIG_ROWID_IN_VIEW</a></li>
274 <li><a href='#sqliteconfigscratch'>SQLITE_CONFIG_SCRATCH</a></li>
275 <li><a href='#sqliteconfigserialized'>SQLITE_CONFIG_SERIALIZED</a></li>
276 <li><a href='#sqliteconfigsinglethread'>SQLITE_CONFIG_SINGLETHREAD</a></li>
277 <li><a href='#sqliteconfigsmallmalloc'>SQLITE_CONFIG_SMALL_MALLOC</a></li>
278 <li><a href='#sqliteconfigsorterrefsize'>SQLITE_CONFIG_SORTERREF_SIZE</a></li>
279 <li><a href='#sqliteconfigsqllog'>SQLITE_CONFIG_SQLLOG</a></li>
280 <li><a href='#sqliteconfigstmtjrnlspill'>SQLITE_CONFIG_STMTJRNL_SPILL</a></li>
281 <li><a href='#sqliteconfiguri'>SQLITE_CONFIG_URI</a></li>
282 <li><a href='#sqliteconfigwin32heapsize'>SQLITE_CONFIG_WIN32_HEAPSIZE</a></li>
283 <li><a href='#SQLITE_ABORT'>SQLITE_CONSTRAINT</a></li>
284 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_CHECK</a></li>
285 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_COMMITHOOK</a></li>
286 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_DATATYPE</a></li>
287 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_FOREIGNKEY</a></li>
288 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_FUNCTION</a></li>
289 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_NOTNULL</a></li>
290 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_PINNED</a></li>
291 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_PRIMARYKEY</a></li>
292 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_ROWID</a></li>
293 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_TRIGGER</a></li>
294 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_UNIQUE</a></li>
295 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_VTAB</a></li>
296 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_COPY</a></li>
297 <li><a href='#SQLITE_ABORT'>SQLITE_CORRUPT</a></li>
298 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CORRUPT_INDEX</a></li>
299 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CORRUPT_SEQUENCE</a></li>
300 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CORRUPT_VTAB</a></li>
301 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_INDEX</a></li>
302 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_TABLE</a></li>
303 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_TEMP_INDEX</a></li>
304 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_TEMP_TABLE</a></li>
305 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_TEMP_TRIGGER</a></li>
306 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_TEMP_VIEW</a></li>
307 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_TRIGGER</a></li>
308 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_VIEW</a></li>
309 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_VTABLE</a></li>
310 <li><a href='#sqlitedbconfigdefensive'>SQLITE_DBCONFIG_DEFENSIVE</a></li>
311 <li><a href='#sqlitedbconfigdqsddl'>SQLITE_DBCONFIG_DQS_DDL</a></li>
312 <li><a href='#sqlitedbconfigdqsdml'>SQLITE_DBCONFIG_DQS_DML</a></li>
313 <li><a href='#sqlitedbconfigenableattachcreate'>SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE</a></li>
314 <li><a href='#sqlitedbconfigenableattachwrite'>SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE</a></li>
315 <li><a href='#sqlitedbconfigenablecomments'>SQLITE_DBCONFIG_ENABLE_COMMENTS</a></li>
316 <li><a href='#sqlitedbconfigenablefkey'>SQLITE_DBCONFIG_ENABLE_FKEY</a></li>
317 <li><a href='#sqlitedbconfigenablefts3tokenizer'>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</a></li>
318 <li><a href='#sqlitedbconfigenableloadextension'>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</a></li>
319 <li><a href='#sqlitedbconfigenableqpsg'>SQLITE_DBCONFIG_ENABLE_QPSG</a></li>
320 <li><a href='#sqlitedbconfigenabletrigger'>SQLITE_DBCONFIG_ENABLE_TRIGGER</a></li>
321 <li><a href='#sqlitedbconfigenableview'>SQLITE_DBCONFIG_ENABLE_VIEW</a></li>
322 <li><a href='#sqlitedbconfigfpdigits'>SQLITE_DBCONFIG_FP_DIGITS</a></li>
323 <li><a href='#sqlitedbconfiglegacyaltertable'>SQLITE_DBCONFIG_LEGACY_ALTER_TABLE</a></li>
324 <li><a href='#sqlitedbconfiglegacyfileformat'>SQLITE_DBCONFIG_LEGACY_FILE_FORMAT</a></li>
325 <li><a href='#sqlitedbconfiglookaside'>SQLITE_DBCONFIG_LOOKASIDE</a></li>
326 <li><a href='#sqlitedbconfigmaindbname'>SQLITE_DBCONFIG_MAINDBNAME</a></li>
327 <li><a href='#SQLITE_DBCONFIG_DEFENSIVE'>SQLITE_DBCONFIG_MAX</a></li>
328 <li><a href='#sqlitedbconfignockptonclose'>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</a></li>
329 <li><a href='#sqlitedbconfigresetdatabase'>SQLITE_DBCONFIG_RESET_DATABASE</a></li>
330 <li><a href='#sqlitedbconfigreversescanorder'>SQLITE_DBCONFIG_REVERSE_SCANORDER</a></li>
331 <li><a href='#sqlitedbconfigstmtscanstatus'>SQLITE_DBCONFIG_STMT_SCANSTATUS</a></li>
332 <li><a href='#sqlitedbconfigtriggereqp'>SQLITE_DBCONFIG_TRIGGER_EQP</a></li>
333 <li><a href='#sqlitedbconfigtrustedschema'>SQLITE_DBCONFIG_TRUSTED_SCHEMA</a></li>
334 <li><a href='#sqlitedbconfigwritableschema'>SQLITE_DBCONFIG_WRITABLE_SCHEMA</a></li>
335 <li><a href='#sqlitedbstatuscachehit'>SQLITE_DBSTATUS_CACHE_HIT</a></li>
336 <li><a href='#sqlitedbstatuscachemiss'>SQLITE_DBSTATUS_CACHE_MISS</a></li>
337 <li><a href='#sqlitedbstatuscachespill'>SQLITE_DBSTATUS_CACHE_SPILL</a></li>
338 <li><a href='#sqlitedbstatuscacheused'>SQLITE_DBSTATUS_CACHE_USED</a></li>
339 <li><a href='#sqlitedbstatuscacheusedshared'>SQLITE_DBSTATUS_CACHE_USED_SHARED</a></li>
340 <li><a href='#sqlitedbstatuscachewrite'>SQLITE_DBSTATUS_CACHE_WRITE</a></li>
341 <li><a href='#sqlitedbstatusdeferredfks'>SQLITE_DBSTATUS_DEFERRED_FKS</a></li>
342 <li><a href='#sqlitedbstatuslookasidehit'>SQLITE_DBSTATUS_LOOKASIDE_HIT</a></li>
343 <li><a href='#sqlitedbstatuslookasidemissfull'>SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL</a></li>
344 <li><a href='#sqlitedbstatuslookasidemisssize'>SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE</a></li>
345 <li><a href='#sqlitedbstatuslookasideused'>SQLITE_DBSTATUS_LOOKASIDE_USED</a></li>
346 <li><a href='#SQLITE_DBSTATUS options'>SQLITE_DBSTATUS_MAX</a></li>
347 <li><a href='#sqlitedbstatusschemaused'>SQLITE_DBSTATUS_SCHEMA_USED</a></li>
348 <li><a href='#sqlitedbstatusstmtused'>SQLITE_DBSTATUS_STMT_USED</a></li>
349 <li><a href='#SQLITE_DBSTATUS options'>SQLITE_DBSTATUS_TEMPBUF_SPILL</a></li>
350 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DELETE</a></li>
351 <li><a href='#SQLITE_DENY'>SQLITE_DENY</a></li>
352 <li><a href='#SQLITE_DESERIALIZE_FREEONCLOSE'>SQLITE_DESERIALIZE_FREEONCLOSE</a></li>
353 <li><a href='#SQLITE_DESERIALIZE_FREEONCLOSE'>SQLITE_DESERIALIZE_READONLY</a></li>
354 <li><a href='#SQLITE_DESERIALIZE_FREEONCLOSE'>SQLITE_DESERIALIZE_RESIZEABLE</a></li>
355 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DETACH</a></li>
356 <li><a href='#sqlitedeterministic'>SQLITE_DETERMINISTIC</a></li>
357 <li><a href='#sqlitedirectonly'>SQLITE_DIRECTONLY</a></li>
358 <li><a href='#SQLITE_ABORT'>SQLITE_DONE</a></li>
359 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_INDEX</a></li>
360 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_TABLE</a></li>
361 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_TEMP_INDEX</a></li>
362 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_TEMP_TABLE</a></li>
363 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_TEMP_TRIGGER</a></li>
364 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_TEMP_VIEW</a></li>
365 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_TRIGGER</a></li>
366 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_VIEW</a></li>
367 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_VTABLE</a></li>
368 <li><a href='#SQLITE_ABORT'>SQLITE_EMPTY</a></li>
369 <li><a href='#SQLITE_ABORT'>SQLITE_ERROR</a></li>
370 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_ERROR_KEY</a></li>
371 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_ERROR_MISSING_COLLSEQ</a></li>
372 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_ERROR_RESERVESIZE</a></li>
373 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_ERROR_RETRY</a></li>
374 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_ERROR_SNAPSHOT</a></li>
375 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_ERROR_UNABLE</a></li>
376 <li><a href='#SQLITE_FAIL'>SQLITE_FAIL</a></li>
377 <li><a href='#sqlitefcntlbeginatomicwrite'>SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a></li>
378 <li><a href='#sqlitefcntlblockonconnect'>SQLITE_FCNTL_BLOCK_ON_CONNECT</a></li>
379 <li><a href='#sqlitefcntlbusyhandler'>SQLITE_FCNTL_BUSYHANDLER</a></li>
380 <li><a href='#sqlitefcntlchunksize'>SQLITE_FCNTL_CHUNK_SIZE</a></li>
381 <li><a href='#sqlitefcntlckptdone'>SQLITE_FCNTL_CKPT_DONE</a></li>
382 <li><a href='#sqlitefcntlckptstart'>SQLITE_FCNTL_CKPT_START</a></li>
383 <li><a href='#sqlitefcntlcksmfile'>SQLITE_FCNTL_CKSM_FILE</a></li>
384 <li><a href='#sqlitefcntlcommitatomicwrite'>SQLITE_FCNTL_COMMIT_ATOMIC_WRITE</a></li>
385 <li><a href='#sqlitefcntlcommitphasetwo'>SQLITE_FCNTL_COMMIT_PHASETWO</a></li>
386 <li><a href='#sqlitefcntldataversion'>SQLITE_FCNTL_DATA_VERSION</a></li>
387 <li><a href='#sqlitefcntlexternalreader'>SQLITE_FCNTL_EXTERNAL_READER</a></li>
388 <li><a href='#sqlitefcntlfilestat'>SQLITE_FCNTL_FILESTAT</a></li>
389 <li><a href='#sqlitefcntlfilepointer'>SQLITE_FCNTL_FILE_POINTER</a></li>
390 <li><a href='#SQLITE_FCNTL_BEGIN_ATOMIC_WRITE'>SQLITE_FCNTL_GET_LOCKPROXYFILE</a></li>
391 <li><a href='#sqlitefcntlhasmoved'>SQLITE_FCNTL_HAS_MOVED</a></li>
392 <li><a href='#sqlitefcntljournalpointer'>SQLITE_FCNTL_JOURNAL_POINTER</a></li>
393 <li><a href='#SQLITE_FCNTL_BEGIN_ATOMIC_WRITE'>SQLITE_FCNTL_LAST_ERRNO</a></li>
394 <li><a href='#sqlitefcntllockstate'>SQLITE_FCNTL_LOCKSTATE</a></li>
395 <li><a href='#sqlitefcntllocktimeout'>SQLITE_FCNTL_LOCK_TIMEOUT</a></li>
396 <li><a href='#sqlitefcntlmmapsize'>SQLITE_FCNTL_MMAP_SIZE</a></li>
397 <li><a href='#sqlitefcntlnullio'>SQLITE_FCNTL_NULL_IO</a></li>
398 <li><a href='#sqlitefcntloverwrite'>SQLITE_FCNTL_OVERWRITE</a></li>
399 <li><a href='#SQLITE_FCNTL_BEGIN_ATOMIC_WRITE'>SQLITE_FCNTL_PDB</a></li>
400 <li><a href='#sqlitefcntlpersistwal'>SQLITE_FCNTL_PERSIST_WAL</a></li>
401 <li><a href='#sqlitefcntlpowersafeoverwrite'>SQLITE_FCNTL_POWERSAFE_OVERWRITE</a></li>
402 <li><a href='#sqlitefcntlpragma'>SQLITE_FCNTL_PRAGMA</a></li>
403 <li><a href='#sqlitefcntlrbu'>SQLITE_FCNTL_RBU</a></li>
404 <li><a href='#SQLITE_FCNTL_BEGIN_ATOMIC_WRITE'>SQLITE_FCNTL_RESERVE_BYTES</a></li>
405 <li><a href='#sqlitefcntlresetcache'>SQLITE_FCNTL_RESET_CACHE</a></li>
406 <li><a href='#sqlitefcntlrollbackatomicwrite'>SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE</a></li>
407 <li><a href='#SQLITE_FCNTL_BEGIN_ATOMIC_WRITE'>SQLITE_FCNTL_SET_LOCKPROXYFILE</a></li>
408 <li><a href='#sqlitefcntlsizehint'>SQLITE_FCNTL_SIZE_HINT</a></li>
409 <li><a href='#sqlitefcntlsizelimit'>SQLITE_FCNTL_SIZE_LIMIT</a></li>
410 <li><a href='#sqlitefcntlsync'>SQLITE_FCNTL_SYNC</a></li>
411 <li><a href='#sqlitefcntlsyncomitted'>SQLITE_FCNTL_SYNC_OMITTED</a></li>
412 <li><a href='#sqlitefcntltempfilename'>SQLITE_FCNTL_TEMPFILENAME</a></li>
413 <li><a href='#sqlitefcntltrace'>SQLITE_FCNTL_TRACE</a></li>
414 <li><a href='#sqlitefcntlvfsname'>SQLITE_FCNTL_VFSNAME</a></li>
415 <li><a href='#sqlitefcntlvfspointer'>SQLITE_FCNTL_VFS_POINTER</a></li>
416 <li><a href='#sqlitefcntlwalblock'>SQLITE_FCNTL_WAL_BLOCK</a></li>
417 <li><a href='#sqlitefcntlwin32avretry'>SQLITE_FCNTL_WIN32_AV_RETRY</a></li>
418 <li><a href='#sqlitefcntlwin32gethandle'>SQLITE_FCNTL_WIN32_GET_HANDLE</a></li>
419 <li><a href='#sqlitefcntlwin32sethandle'>SQLITE_FCNTL_WIN32_SET_HANDLE</a></li>
420 <li><a href='#sqlitefcntlzipvfs'>SQLITE_FCNTL_ZIPVFS</a></li>
421 <li><a href='#SQLITE_BLOB'>SQLITE_FLOAT</a></li>
422 <li><a href='#SQLITE_ABORT'>SQLITE_FORMAT</a></li>
423 <li><a href='#SQLITE_ABORT'>SQLITE_FULL</a></li>
424 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_FUNCTION</a></li>
425 <li><a href='#SQLITE_DENY'>SQLITE_IGNORE</a></li>
426 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_EQ</a></li>
427 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_FUNCTION</a></li>
428 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_GE</a></li>
429 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_GLOB</a></li>
430 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_GT</a></li>
431 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_IS</a></li>
432 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_ISNOT</a></li>
433 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_ISNOTNULL</a></li>
434 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_ISNULL</a></li>
435 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_LE</a></li>
436 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_LIKE</a></li>
437 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_LIMIT</a></li>
438 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_LT</a></li>
439 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_MATCH</a></li>
440 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_NE</a></li>
441 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_OFFSET</a></li>
442 <li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_REGEXP</a></li>
443 <li><a href='#SQLITE_INDEX_SCAN_HEX'>SQLITE_INDEX_SCAN_HEX</a></li>
444 <li><a href='#SQLITE_INDEX_SCAN_HEX'>SQLITE_INDEX_SCAN_UNIQUE</a></li>
445 <li><a href='#sqliteinnocuous'>SQLITE_INNOCUOUS</a></li>
446 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_INSERT</a></li>
447 <li><a href='#SQLITE_BLOB'>SQLITE_INTEGER</a></li>
448 <li><a href='#SQLITE_ABORT'>SQLITE_INTERNAL</a></li>
449 <li><a href='#SQLITE_ABORT'>SQLITE_INTERRUPT</a></li>
450 <li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC</a></li>
451 <li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC16K</a></li>
452 <li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC1K</a></li>
453 <li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC2K</a></li>
454 <li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC32K</a></li>
455 <li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC4K</a></li>
456 <li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC512</a></li>
457 <li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC64K</a></li>
458 <li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC8K</a></li>
459 <li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_BATCH_ATOMIC</a></li>
460 <li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_IMMUTABLE</a></li>
461 <li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_POWERSAFE_OVERWRITE</a></li>
462 <li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_SAFE_APPEND</a></li>
463 <li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_SEQUENTIAL</a></li>
464 <li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_SUBPAGE_READ</a></li>
465 <li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN</a></li>
466 <li><a href='#SQLITE_ABORT'>SQLITE_IOERR</a></li>
467 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_ACCESS</a></li>
468 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_AUTH</a></li>
469 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_BADKEY</a></li>
470 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_BEGIN_ATOMIC</a></li>
471 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_BLOCKED</a></li>
472 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_CHECKRESERVEDLOCK</a></li>
473 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_CLOSE</a></li>
474 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_CODEC</a></li>
475 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_COMMIT_ATOMIC</a></li>
476 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_CONVPATH</a></li>
477 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_CORRUPTFS</a></li>
478 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_DATA</a></li>
479 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_DELETE</a></li>
480 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_DELETE_NOENT</a></li>
481 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_DIR_CLOSE</a></li>
482 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_DIR_FSYNC</a></li>
483 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_FSTAT</a></li>
484 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_FSYNC</a></li>
485 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_GETTEMPPATH</a></li>
486 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_IN_PAGE</a></li>
487 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_LOCK</a></li>
488 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_MMAP</a></li>
489 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_NOMEM</a></li>
490 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_RDLOCK</a></li>
491 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_READ</a></li>
492 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_ROLLBACK_ATOMIC</a></li>
493 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_SEEK</a></li>
494 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_SHMLOCK</a></li>
495 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_SHMMAP</a></li>
496 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_SHMOPEN</a></li>
497 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_SHMSIZE</a></li>
498 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_SHORT_READ</a></li>
499 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_TRUNCATE</a></li>
500 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_UNLOCK</a></li>
501 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_VNODE</a></li>
502 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_WRITE</a></li>
503 <li><a href='#sqlitelimitattached'>SQLITE_LIMIT_ATTACHED</a></li>
504 <li><a href='#sqlitelimitcolumn'>SQLITE_LIMIT_COLUMN</a></li>
505 <li><a href='#sqlitelimitcompoundselect'>SQLITE_LIMIT_COMPOUND_SELECT</a></li>
506 <li><a href='#sqlitelimitexprdepth'>SQLITE_LIMIT_EXPR_DEPTH</a></li>
507 <li><a href='#sqlitelimitfunctionarg'>SQLITE_LIMIT_FUNCTION_ARG</a></li>
508 <li><a href='#sqlitelimitlength'>SQLITE_LIMIT_LENGTH</a></li>
509 <li><a href='#sqlitelimitlikepatternlength'>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</a></li>
510 <li><a href='#sqlitelimitparserdepth'>SQLITE_LIMIT_PARSER_DEPTH</a></li>
511 <li><a href='#sqlitelimitsqllength'>SQLITE_LIMIT_SQL_LENGTH</a></li>
512 <li><a href='#sqlitelimittriggerdepth'>SQLITE_LIMIT_TRIGGER_DEPTH</a></li>
513 <li><a href='#sqlitelimitvariablenumber'>SQLITE_LIMIT_VARIABLE_NUMBER</a></li>
514 <li><a href='#sqlitelimitvdbeop'>SQLITE_LIMIT_VDBE_OP</a></li>
515 <li><a href='#sqlitelimitworkerthreads'>SQLITE_LIMIT_WORKER_THREADS</a></li>
516 <li><a href='#SQLITE_ABORT'>SQLITE_LOCKED</a></li>
517 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_LOCKED_SHAREDCACHE</a></li>
518 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_LOCKED_VTAB</a></li>
519 <li><a href='#SQLITE_LOCK_EXCLUSIVE'>SQLITE_LOCK_EXCLUSIVE</a></li>
520 <li><a href='#SQLITE_LOCK_EXCLUSIVE'>SQLITE_LOCK_NONE</a></li>
521 <li><a href='#SQLITE_LOCK_EXCLUSIVE'>SQLITE_LOCK_PENDING</a></li>
522 <li><a href='#SQLITE_LOCK_EXCLUSIVE'>SQLITE_LOCK_RESERVED</a></li>
523 <li><a href='#SQLITE_LOCK_EXCLUSIVE'>SQLITE_LOCK_SHARED</a></li>
524 <li><a href='#SQLITE_ABORT'>SQLITE_MISMATCH</a></li>
525 <li><a href='#SQLITE_ABORT'>SQLITE_MISUSE</a></li>
526 <li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_FAST</a></li>
527 <li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_RECURSIVE</a></li>
528 <li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_APP1</a></li>
529 <li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_APP2</a></li>
530 <li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_APP3</a></li>
531 <li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_LRU</a></li>
532 <li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_LRU2</a></li>
533 <li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_MAIN</a></li>
534 <li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_MEM</a></li>
535 <li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_MEM2</a></li>
536 <li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_OPEN</a></li>
537 <li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_PMEM</a></li>
538 <li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_PRNG</a></li>
539 <li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_VFS1</a></li>
540 <li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_VFS2</a></li>
541 <li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_VFS3</a></li>
542 <li><a href='#SQLITE_ABORT'>SQLITE_NOLFS</a></li>
543 <li><a href='#SQLITE_ABORT'>SQLITE_NOMEM</a></li>
544 <li><a href='#SQLITE_ABORT'>SQLITE_NOTADB</a></li>
545 <li><a href='#SQLITE_ABORT'>SQLITE_NOTFOUND</a></li>
546 <li><a href='#SQLITE_ABORT'>SQLITE_NOTICE</a></li>
547 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_NOTICE_RBU</a></li>
548 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_NOTICE_RECOVER_ROLLBACK</a></li>
549 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_NOTICE_RECOVER_WAL</a></li>
550 <li><a href='#SQLITE_BLOB'>SQLITE_NULL</a></li>
551 <li><a href='#SQLITE_ABORT'>SQLITE_OK</a></li>
552 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_OK_LOAD_PERMANENTLY</a></li>
553 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_OK_SYMLINK</a></li>
554 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_AUTOPROXY</a></li>
555 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_CREATE</a></li>
556 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_DELETEONCLOSE</a></li>
557 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_EXCLUSIVE</a></li>
558 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_EXRESCODE</a></li>
559 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_FULLMUTEX</a></li>
560 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_MAIN_DB</a></li>
561 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_MAIN_JOURNAL</a></li>
562 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_MEMORY</a></li>
563 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_NOFOLLOW</a></li>
564 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_NOMUTEX</a></li>
565 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_PRIVATECACHE</a></li>
566 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_READONLY</a></li>
567 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_READWRITE</a></li>
568 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_SHAREDCACHE</a></li>
569 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_SUBJOURNAL</a></li>
570 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_SUPER_JOURNAL</a></li>
571 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_TEMP_DB</a></li>
572 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_TEMP_JOURNAL</a></li>
573 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_TRANSIENT_DB</a></li>
574 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_URI</a></li>
575 <li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_WAL</a></li>
576 <li><a href='#SQLITE_ABORT'>SQLITE_PERM</a></li>
577 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_PRAGMA</a></li>
578 <li><a href='#sqlitepreparedontlog'>SQLITE_PREPARE_DONT_LOG</a></li>
579 <li><a href='#sqlitepreparefromddl'>SQLITE_PREPARE_FROM_DDL</a></li>
580 <li><a href='#sqlitepreparenormalize'>SQLITE_PREPARE_NORMALIZE</a></li>
581 <li><a href='#sqlitepreparenovtab'>SQLITE_PREPARE_NO_VTAB</a></li>
582 <li><a href='#sqlitepreparepersistent'>SQLITE_PREPARE_PERSISTENT</a></li>
583 <li><a href='#SQLITE_ABORT'>SQLITE_PROTOCOL</a></li>
584 <li><a href='#SQLITE_ABORT'>SQLITE_RANGE</a></li>
585 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_READ</a></li>
586 <li><a href='#SQLITE_ABORT'>SQLITE_READONLY</a></li>
587 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_READONLY_CANTINIT</a></li>
588 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_READONLY_CANTLOCK</a></li>
589 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_READONLY_DBMOVED</a></li>
590 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_READONLY_DIRECTORY</a></li>
591 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_READONLY_RECOVERY</a></li>
592 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_READONLY_ROLLBACK</a></li>
593 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_RECURSIVE</a></li>
594 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_REINDEX</a></li>
595 <li><a href='#SQLITE_FAIL'>SQLITE_REPLACE</a></li>
596 <li><a href='#sqliteresultsubtype'>SQLITE_RESULT_SUBTYPE</a></li>
597 <li><a href='#SQLITE_FAIL'>SQLITE_ROLLBACK</a></li>
598 <li><a href='#SQLITE_ABORT'>SQLITE_ROW</a></li>
599 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_SAVEPOINT</a></li>
600 <li><a href='#SQLITE_SCANSTAT_COMPLEX'>SQLITE_SCANSTAT_COMPLEX</a></li>
601 <li><a href='#sqlitescanstatest'>SQLITE_SCANSTAT_EST</a></li>
602 <li><a href='#sqlitescanstatexplain'>SQLITE_SCANSTAT_EXPLAIN</a></li>
603 <li><a href='#sqlitescanstatname'>SQLITE_SCANSTAT_NAME</a></li>
604 <li><a href='#sqlitescanstatncycle'>SQLITE_SCANSTAT_NCYCLE</a></li>
605 <li><a href='#sqlitescanstatnloop'>SQLITE_SCANSTAT_NLOOP</a></li>
606 <li><a href='#sqlitescanstatnvisit'>SQLITE_SCANSTAT_NVISIT</a></li>
607 <li><a href='#sqlitescanstatparentid'>SQLITE_SCANSTAT_PARENTID</a></li>
608 <li><a href='#sqlitescanstatselectid'>SQLITE_SCANSTAT_SELECTID</a></li>
609 <li><a href='#SQLITE_ABORT'>SQLITE_SCHEMA</a></li>
610 <li><a href='#SQLITE_SCM_BRANCH'>SQLITE_SCM_BRANCH</a></li>
611 <li><a href='#SQLITE_SCM_BRANCH'>SQLITE_SCM_DATETIME</a></li>
612 <li><a href='#SQLITE_SCM_BRANCH'>SQLITE_SCM_TAGS</a></li>
613 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_SELECT</a></li>
614 <li><a href='#sqliteselforder1'>SQLITE_SELFORDER1</a></li>
615 <li><a href='#SQLITE_SERIALIZE_NOCOPY'>SQLITE_SERIALIZE_NOCOPY</a></li>
616 <li><a href='#SQLITE_SETLK_BLOCK_ON_CONNECT'>SQLITE_SETLK_BLOCK_ON_CONNECT</a></li>
617 <li><a href='#SQLITE_SHM_EXCLUSIVE'>SQLITE_SHM_EXCLUSIVE</a></li>
618 <li><a href='#SQLITE_SHM_EXCLUSIVE'>SQLITE_SHM_LOCK</a></li>
619 <li><a href='#SQLITE_SHM_NLOCK'>SQLITE_SHM_NLOCK</a></li>
620 <li><a href='#SQLITE_SHM_EXCLUSIVE'>SQLITE_SHM_SHARED</a></li>
621 <li><a href='#SQLITE_SHM_EXCLUSIVE'>SQLITE_SHM_UNLOCK</a></li>
622 <li><a href='#SQLITE_SCM_BRANCH'>SQLITE_SOURCE_ID</a></li>
623 <li><a href='#SQLITE_STATIC'>SQLITE_STATIC</a></li>
624 <li><a href='#sqlitestatusmalloccount'>SQLITE_STATUS_MALLOC_COUNT</a></li>
625 <li><a href='#sqlitestatusmallocsize'>SQLITE_STATUS_MALLOC_SIZE</a></li>
626 <li><a href='#sqlitestatusmemoryused'>SQLITE_STATUS_MEMORY_USED</a></li>
627 <li><a href='#sqlitestatuspagecacheoverflow'>SQLITE_STATUS_PAGECACHE_OVERFLOW</a></li>
628 <li><a href='#sqlitestatuspagecachesize'>SQLITE_STATUS_PAGECACHE_SIZE</a></li>
629 <li><a href='#sqlitestatuspagecacheused'>SQLITE_STATUS_PAGECACHE_USED</a></li>
630 <li><a href='#sqlitestatusparserstack'>SQLITE_STATUS_PARSER_STACK</a></li>
631 <li><a href='#sqlitestatusscratchoverflow'>SQLITE_STATUS_SCRATCH_OVERFLOW</a></li>
632 <li><a href='#sqlitestatusscratchsize'>SQLITE_STATUS_SCRATCH_SIZE</a></li>
633 <li><a href='#sqlitestatusscratchused'>SQLITE_STATUS_SCRATCH_USED</a></li>
634 <li><a href='#sqlitestmtstatusautoindex'>SQLITE_STMTSTATUS_AUTOINDEX</a></li>
635 <li><a href='#SQLITE_STMTSTATUS counter'>SQLITE_STMTSTATUS_FILTER_HIT</a></li>
636 <li><a href='#sqlitestmtstatusfiltermiss'>SQLITE_STMTSTATUS_FILTER_MISS</a></li>
637 <li><a href='#sqlitestmtstatusfullscanstep'>SQLITE_STMTSTATUS_FULLSCAN_STEP</a></li>
638 <li><a href='#sqlitestmtstatusmemused'>SQLITE_STMTSTATUS_MEMUSED</a></li>
639 <li><a href='#sqlitestmtstatusreprepare'>SQLITE_STMTSTATUS_REPREPARE</a></li>
640 <li><a href='#sqlitestmtstatusrun'>SQLITE_STMTSTATUS_RUN</a></li>
641 <li><a href='#sqlitestmtstatussort'>SQLITE_STMTSTATUS_SORT</a></li>
642 <li><a href='#sqlitestmtstatusvmstep'>SQLITE_STMTSTATUS_VM_STEP</a></li>
643 <li><a href='#sqlitesubtype'>SQLITE_SUBTYPE</a></li>
644 <li><a href='#SQLITE_SYNC_DATAONLY'>SQLITE_SYNC_DATAONLY</a></li>
645 <li><a href='#SQLITE_SYNC_DATAONLY'>SQLITE_SYNC_FULL</a></li>
646 <li><a href='#SQLITE_SYNC_DATAONLY'>SQLITE_SYNC_NORMAL</a></li>
647 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_ALWAYS</a></li>
648 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_ASSERT</a></li>
649 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_ATOF</a></li>
650 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS</a></li>
651 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_BITVEC_TEST</a></li>
652 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_BYTEORDER</a></li>
653 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_EXPLAIN_STMT</a></li>
654 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_EXTRA_SCHEMA_CHECKS</a></li>
655 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_FAULT_INSTALL</a></li>
656 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_FIRST</a></li>
657 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_FK_NO_ACTION</a></li>
658 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_GETOPT</a></li>
659 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_IMPOSTER</a></li>
660 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_INTERNAL_FUNCTIONS</a></li>
661 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_ISINIT</a></li>
662 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_ISKEYWORD</a></li>
663 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_JSON_SELFCHECK</a></li>
664 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_LAST</a></li>
665 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_LOCALTIME_FAULT</a></li>
666 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_LOGEST</a></li>
667 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_NEVER_CORRUPT</a></li>
668 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD</a></li>
669 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_OPTIMIZATIONS</a></li>
670 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_PARSER_COVERAGE</a></li>
671 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_PENDING_BYTE</a></li>
672 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_PRNG_RESET</a></li>
673 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_PRNG_RESTORE</a></li>
674 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_PRNG_SAVE</a></li>
675 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_PRNG_SEED</a></li>
676 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_RESERVE</a></li>
677 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_RESULT_INTREAL</a></li>
678 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_SCRATCHMALLOC</a></li>
679 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_SEEK_COUNT</a></li>
680 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_SORTER_MMAP</a></li>
681 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_TRACEFLAGS</a></li>
682 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_TUNE</a></li>
683 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_USELONGDOUBLE</a></li>
684 <li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_VDBE_COVERAGE</a></li>
685 <li><a href='#SQLITE_BLOB'>SQLITE_TEXT</a></li>
686 <li><a href='#SQLITE_ABORT'>SQLITE_TOOBIG</a></li>
687 <li><a href='#SQLITE_TRACE'>SQLITE_TRACE</a></li>
688 <li><a href='#sqlitetraceclose'>SQLITE_TRACE_CLOSE</a></li>
689 <li><a href='#sqlitetraceprofile'>SQLITE_TRACE_PROFILE</a></li>
690 <li><a href='#sqlitetracerow'>SQLITE_TRACE_ROW</a></li>
691 <li><a href='#sqlitetracestmt'>SQLITE_TRACE_STMT</a></li>
692 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_TRANSACTION</a></li>
693 <li><a href='#SQLITE_STATIC'>SQLITE_TRANSIENT</a></li>
694 <li><a href='#sqlitetxnnone'>SQLITE_TXN_NONE</a></li>
695 <li><a href='#sqlitetxnread'>SQLITE_TXN_READ</a></li>
696 <li><a href='#sqlitetxnwrite'>SQLITE_TXN_WRITE</a></li>
697 <li><a href='#SQLITE_ALTER_TABLE'>SQLITE_UPDATE</a></li>
698 <li><a href='#sqliteutf16'>SQLITE_UTF16</a></li>
699 <li><a href='#sqliteutf16be'>SQLITE_UTF16BE</a></li>
700 <li><a href='#sqliteutf16le'>SQLITE_UTF16LE</a></li>
701 <li><a href='#sqliteutf16aligned'>SQLITE_UTF16_ALIGNED</a></li>
702 <li><a href='#sqliteutf8'>SQLITE_UTF8</a></li>
703 <li><a href='#sqliteutf8zt'>SQLITE_UTF8_ZT</a></li>
704 <li><a href='#SQLITE_SCM_BRANCH'>SQLITE_VERSION</a></li>
705 <li><a href='#SQLITE_SCM_BRANCH'>SQLITE_VERSION_NUMBER</a></li>
706 <li><a href='#sqlitevtabconstraintsupport'>SQLITE_VTAB_CONSTRAINT_SUPPORT</a></li>
707 <li><a href='#sqlitevtabdirectonly'>SQLITE_VTAB_DIRECTONLY</a></li>
708 <li><a href='#sqlitevtabinnocuous'>SQLITE_VTAB_INNOCUOUS</a></li>
709 <li><a href='#sqlitevtabusesallschemas'>SQLITE_VTAB_USES_ALL_SCHEMAS</a></li>
710 <li><a href='#SQLITE_ABORT'>SQLITE_WARNING</a></li>
711 <li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_WARNING_AUTOINDEX</a></li>
712 <li><a href='#SQLITE_WIN32_DATA_DIRECTORY_TYPE'>SQLITE_WIN32_DATA_DIRECTORY_TYPE</a></li>
713 <li><a href='#SQLITE_WIN32_DATA_DIRECTORY_TYPE'>SQLITE_WIN32_TEMP_DIRECTORY_TYPE</a></li>
714 </ul>
715 </div>
716 <hr>
717
718 <h2>List Of Functions:</h2>
719 <p>Note: Functions marked with "<small><i>(exp)</i></small>"
720 are <a href="capi3ref.html">experimental</a> and functions whose names are
721 <s>struck through</s> are <a href="capi3ref.html">deprecated</a>.</p>
722 <!-- number of functions: 295 -->
723 <!-- number of deprecated functions: 9 -->
724 <!-- number of experimental functions: 0 -->
725 <div class='columns' style='columns: 15em auto;'>
726 <ul style='padding-top:0;'>
727 <li><a href='#sqlite3_aggregate_context'>sqlite3_aggregate_context</a></li>
728 <li><s>sqlite3_aggregate_count</s></li>
729 <li><a href='#sqlite3_auto_extension'>sqlite3_auto_extension</a></li>
730 <li><a href='#sqlite3_autovacuum_pages'>sqlite3_autovacuum_pages</a></li>
731 <li><a href='#sqlite3backupfinish'>sqlite3_backup_finish</a></li>
732 <li><a href='#sqlite3backupinit'>sqlite3_backup_init</a></li>
733 <li><a href='#sqlite3backuppagecount'>sqlite3_backup_pagecount</a></li>
734 <li><a href='#sqlite3backupremaining'>sqlite3_backup_remaining</a></li>
735 <li><a href='#sqlite3backupstep'>sqlite3_backup_step</a></li>
736 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_blob</a></li>
737 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_blob64</a></li>
738 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_double</a></li>
739 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_int</a></li>
740 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_int64</a></li>
741 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_null</a></li>
742 <li><a href='#sqlite3_bind_parameter_count'>sqlite3_bind_parameter_count</a></li>
743 <li><a href='#sqlite3_bind_parameter_index'>sqlite3_bind_parameter_index</a></li>
744 <li><a href='#sqlite3_bind_parameter_name'>sqlite3_bind_parameter_name</a></li>
745 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_pointer</a></li>
746 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_text</a></li>
747 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_text16</a></li>
748 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_text64</a></li>
749 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_value</a></li>
750 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_zeroblob</a></li>
751 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_zeroblob64</a></li>
752 <li><a href='#sqlite3_blob_bytes'>sqlite3_blob_bytes</a></li>
753 <li><a href='#sqlite3_blob_close'>sqlite3_blob_close</a></li>
754 <li><a href='#sqlite3_blob_open'>sqlite3_blob_open</a></li>
755 <li><a href='#sqlite3_blob_read'>sqlite3_blob_read</a></li>
756 <li><a href='#sqlite3_blob_reopen'>sqlite3_blob_reopen</a></li>
757 <li><a href='#sqlite3_blob_write'>sqlite3_blob_write</a></li>
758 <li><a href='#sqlite3_busy_handler'>sqlite3_busy_handler</a></li>
759 <li><a href='#sqlite3_busy_timeout'>sqlite3_busy_timeout</a></li>
760 <li><a href='#sqlite3_cancel_auto_extension'>sqlite3_cancel_auto_extension</a></li>
761 <li><a href='#sqlite3_carray_bind'>sqlite3_carray_bind</a></li>
762 <li><a href='#sqlite3_carray_bind'>sqlite3_carray_bind_v2</a></li>
763 <li><a href='#sqlite3_changes'>sqlite3_changes</a></li>
764 <li><a href='#sqlite3_changes'>sqlite3_changes64</a></li>
765 <li><a href='#sqlite3_clear_bindings'>sqlite3_clear_bindings</a></li>
766 <li><a href='#sqlite3_close'>sqlite3_close</a></li>
767 <li><a href='#sqlite3_close'>sqlite3_close_v2</a></li>
768 <li><a href='#sqlite3_collation_needed'>sqlite3_collation_needed</a></li>
769 <li><a href='#sqlite3_collation_needed'>sqlite3_collation_needed16</a></li>
770 <li><a href='#sqlite3_column_blob'>sqlite3_column_blob</a></li>
771 <li><a href='#sqlite3_column_blob'>sqlite3_column_bytes</a></li>
772 <li><a href='#sqlite3_column_blob'>sqlite3_column_bytes16</a></li>
773 <li><a href='#sqlite3_column_count'>sqlite3_column_count</a></li>
774 <li><a href='#sqlite3_column_database_name'>sqlite3_column_database_name</a></li>
775 <li><a href='#sqlite3_column_database_name'>sqlite3_column_database_name16</a></li>
776 <li><a href='#sqlite3_column_decltype'>sqlite3_column_decltype</a></li>
777 <li><a href='#sqlite3_column_decltype'>sqlite3_column_decltype16</a></li>
778 <li><a href='#sqlite3_column_blob'>sqlite3_column_double</a></li>
779 <li><a href='#sqlite3_column_blob'>sqlite3_column_int</a></li>
780 <li><a href='#sqlite3_column_blob'>sqlite3_column_int64</a></li>
781 <li><a href='#sqlite3_column_name'>sqlite3_column_name</a></li>
782 <li><a href='#sqlite3_column_name'>sqlite3_column_name16</a></li>
783 <li><a href='#sqlite3_column_database_name'>sqlite3_column_origin_name</a></li>
784 <li><a href='#sqlite3_column_database_name'>sqlite3_column_origin_name16</a></li>
785 <li><a href='#sqlite3_column_database_name'>sqlite3_column_table_name</a></li>
786 <li><a href='#sqlite3_column_database_name'>sqlite3_column_table_name16</a></li>
787 <li><a href='#sqlite3_column_blob'>sqlite3_column_text</a></li>
788 <li><a href='#sqlite3_column_blob'>sqlite3_column_text16</a></li>
789 <li><a href='#sqlite3_column_blob'>sqlite3_column_type</a></li>
790 <li><a href='#sqlite3_column_blob'>sqlite3_column_value</a></li>
791 <li><a href='#sqlite3_commit_hook'>sqlite3_commit_hook</a></li>
792 <li><a href='#sqlite3_compileoption_get'>sqlite3_compileoption_get</a></li>
793 <li><a href='#sqlite3_compileoption_get'>sqlite3_compileoption_used</a></li>
794 <li><a href='#sqlite3_complete'>sqlite3_complete</a></li>
795 <li><a href='#sqlite3_complete'>sqlite3_complete16</a></li>
796 <li><a href='#sqlite3_config'>sqlite3_config</a></li>
797 <li><a href='#sqlite3_context_db_handle'>sqlite3_context_db_handle</a></li>
798 <li><a href='#sqlite3_create_collation'>sqlite3_create_collation</a></li>
799 <li><a href='#sqlite3_create_collation'>sqlite3_create_collation16</a></li>
800 <li><a href='#sqlite3_create_collation'>sqlite3_create_collation_v2</a></li>
801 <li><a href='#sqlite3_create_filename'>sqlite3_create_filename</a></li>
802 <li><a href='#sqlite3_create_function'>sqlite3_create_function</a></li>
803 <li><a href='#sqlite3_create_function'>sqlite3_create_function16</a></li>
804 <li><a href='#sqlite3_create_function'>sqlite3_create_function_v2</a></li>
805 <li><a href='#sqlite3_create_module'>sqlite3_create_module</a></li>
806 <li><a href='#sqlite3_create_module'>sqlite3_create_module_v2</a></li>
807 <li><a href='#sqlite3_create_function'>sqlite3_create_window_function</a></li>
808 <li><a href='#sqlite3_data_count'>sqlite3_data_count</a></li>
809 <li><a href='#sqlite3_database_file_object'>sqlite3_database_file_object</a></li>
810 <li><a href='#sqlite3_db_cacheflush'>sqlite3_db_cacheflush</a></li>
811 <li><a href='#sqlite3_db_config'>sqlite3_db_config</a></li>
812 <li><a href='#sqlite3_db_filename'>sqlite3_db_filename</a></li>
813 <li><a href='#sqlite3_db_handle'>sqlite3_db_handle</a></li>
814 <li><a href='#sqlite3_db_mutex'>sqlite3_db_mutex</a></li>
815 <li><a href='#sqlite3_db_name'>sqlite3_db_name</a></li>
816 <li><a href='#sqlite3_db_readonly'>sqlite3_db_readonly</a></li>
817 <li><a href='#sqlite3_db_release_memory'>sqlite3_db_release_memory</a></li>
818 <li><a href='#sqlite3_db_status'>sqlite3_db_status</a></li>
819 <li><a href='#sqlite3_db_status'>sqlite3_db_status64</a></li>
820 <li><a href='#sqlite3_declare_vtab'>sqlite3_declare_vtab</a></li>
821 <li><a href='#sqlite3_deserialize'>sqlite3_deserialize</a></li>
822 <li><a href='#sqlite3_drop_modules'>sqlite3_drop_modules</a></li>
823 <li><a href='#sqlite3_enable_load_extension'>sqlite3_enable_load_extension</a></li>
824 <li><a href='#sqlite3_enable_shared_cache'>sqlite3_enable_shared_cache</a></li>
825 <li><a href='#sqlite3_errcode'>sqlite3_errcode</a></li>
826 <li><a href='#sqlite3_errcode'>sqlite3_errmsg</a></li>
827 <li><a href='#sqlite3_errcode'>sqlite3_errmsg16</a></li>
828 <li><a href='#sqlite3_errcode'>sqlite3_error_offset</a></li>
829 <li><a href='#sqlite3_errcode'>sqlite3_errstr</a></li>
830 <li><a href='#sqlite3_exec'>sqlite3_exec</a></li>
831 <li><a href='#sqlite3_expanded_sql'>sqlite3_expanded_sql</a></li>
832 <li><s>sqlite3_expired</s></li>
833 <li><a href='#sqlite3_errcode'>sqlite3_extended_errcode</a></li>
834 <li><a href='#sqlite3_extended_result_codes'>sqlite3_extended_result_codes</a></li>
835 <li><a href='#sqlite3_file_control'>sqlite3_file_control</a></li>
836 <li><a href='#sqlite3_filename_database'>sqlite3_filename_database</a></li>
837 <li><a href='#sqlite3_filename_database'>sqlite3_filename_journal</a></li>
838 <li><a href='#sqlite3_filename_database'>sqlite3_filename_wal</a></li>
839 <li><a href='#sqlite3_finalize'>sqlite3_finalize</a></li>
840 <li><a href='#sqlite3_free'>sqlite3_free</a></li>
841 <li><a href='#sqlite3_create_filename'>sqlite3_free_filename</a></li>
842 <li><a href='#sqlite3_free_table'>sqlite3_free_table</a></li>
843 <li><a href='#sqlite3_get_autocommit'>sqlite3_get_autocommit</a></li>
844 <li><a href='#sqlite3_get_auxdata'>sqlite3_get_auxdata</a></li>
845 <li><a href='#sqlite3_get_clientdata'>sqlite3_get_clientdata</a></li>
846 <li><a href='#sqlite3_free_table'>sqlite3_get_table</a></li>
847 <li><s>sqlite3_global_recover</s></li>
848 <li><a href='#sqlite3_hard_heap_limit64'>sqlite3_hard_heap_limit64</a></li>
849 <li><a href='#sqlite3_initialize'>sqlite3_initialize</a></li>
850 <li><a href='#sqlite3_interrupt'>sqlite3_interrupt</a></li>
851 <li><a href='#sqlite3_interrupt'>sqlite3_is_interrupted</a></li>
852 <li><a href='#sqlite3_keyword_check'>sqlite3_keyword_check</a></li>
853 <li><a href='#sqlite3_keyword_check'>sqlite3_keyword_count</a></li>
854 <li><a href='#sqlite3_keyword_check'>sqlite3_keyword_name</a></li>
855 <li><a href='#sqlite3_last_insert_rowid'>sqlite3_last_insert_rowid</a></li>
856 <li><a href='#sqlite3_libversion'>sqlite3_libversion</a></li>
857 <li><a href='#sqlite3_libversion'>sqlite3_libversion_number</a></li>
858 <li><a href='#sqlite3_limit'>sqlite3_limit</a></li>
859 <li><a href='#sqlite3_load_extension'>sqlite3_load_extension</a></li>
860 <li><a href='#sqlite3_log'>sqlite3_log</a></li>
861 <li><a href='#sqlite3_free'>sqlite3_malloc</a></li>
862 <li><a href='#sqlite3_free'>sqlite3_malloc64</a></li>
863 <li><s>sqlite3_memory_alarm</s></li>
864 <li><a href='#sqlite3_memory_highwater'>sqlite3_memory_highwater</a></li>
865 <li><a href='#sqlite3_memory_highwater'>sqlite3_memory_used</a></li>
866 <li><a href='#sqlite3_mprintf'>sqlite3_mprintf</a></li>
867 <li><a href='#sqlite3_free'>sqlite3_msize</a></li>
868 <li><a href='#sqlite3_mutex_alloc'>sqlite3_mutex_alloc</a></li>
869 <li><a href='#sqlite3_mutex_alloc'>sqlite3_mutex_enter</a></li>
870 <li><a href='#sqlite3_mutex_alloc'>sqlite3_mutex_free</a></li>
871 <li><a href='#sqlite3_mutex_held'>sqlite3_mutex_held</a></li>
872 <li><a href='#sqlite3_mutex_alloc'>sqlite3_mutex_leave</a></li>
873 <li><a href='#sqlite3_mutex_held'>sqlite3_mutex_notheld</a></li>
874 <li><a href='#sqlite3_mutex_alloc'>sqlite3_mutex_try</a></li>
875 <li><a href='#sqlite3_next_stmt'>sqlite3_next_stmt</a></li>
876 <li><a href='#sqlite3_expanded_sql'>sqlite3_normalized_sql</a></li>
877 <li><a href='#sqlite3_open'>sqlite3_open</a></li>
878 <li><a href='#sqlite3_open'>sqlite3_open16</a></li>
879 <li><a href='#sqlite3_open'>sqlite3_open_v2</a></li>
880 <li><a href='#sqlite3_initialize'>sqlite3_os_end</a></li>
881 <li><a href='#sqlite3_initialize'>sqlite3_os_init</a></li>
882 <li><a href='#sqlite3_overload_function'>sqlite3_overload_function</a></li>
883 <li><a href='#sqlite3_prepare'>sqlite3_prepare</a></li>
884 <li><a href='#sqlite3_prepare'>sqlite3_prepare16</a></li>
885 <li><a href='#sqlite3_prepare'>sqlite3_prepare16_v2</a></li>
886 <li><a href='#sqlite3_prepare'>sqlite3_prepare16_v3</a></li>
887 <li><a href='#sqlite3_prepare'>sqlite3_prepare_v2</a></li>
888 <li><a href='#sqlite3_prepare'>sqlite3_prepare_v3</a></li>
889 <li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_blobwrite</a></li>
890 <li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_count</a></li>
891 <li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_depth</a></li>
892 <li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_hook</a></li>
893 <li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_new</a></li>
894 <li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_old</a></li>
895 <li><s>sqlite3_profile</s></li>
896 <li><a href='#sqlite3_progress_handler'>sqlite3_progress_handler</a></li>
897 <li><a href='#sqlite3_randomness'>sqlite3_randomness</a></li>
898 <li><a href='#sqlite3_free'>sqlite3_realloc</a></li>
899 <li><a href='#sqlite3_free'>sqlite3_realloc64</a></li>
900 <li><a href='#sqlite3_release_memory'>sqlite3_release_memory</a></li>
901 <li><a href='#sqlite3_reset'>sqlite3_reset</a></li>
902 <li><a href='#sqlite3_reset_auto_extension'>sqlite3_reset_auto_extension</a></li>
903 <li><a href='#sqlite3_result_blob'>sqlite3_result_blob</a></li>
904 <li><a href='#sqlite3_result_blob'>sqlite3_result_blob64</a></li>
905 <li><a href='#sqlite3_result_blob'>sqlite3_result_double</a></li>
906 <li><a href='#sqlite3_result_blob'>sqlite3_result_error</a></li>
907 <li><a href='#sqlite3_result_blob'>sqlite3_result_error16</a></li>
908 <li><a href='#sqlite3_result_blob'>sqlite3_result_error_code</a></li>
909 <li><a href='#sqlite3_result_blob'>sqlite3_result_error_nomem</a></li>
910 <li><a href='#sqlite3_result_blob'>sqlite3_result_error_toobig</a></li>
911 <li><a href='#sqlite3_result_blob'>sqlite3_result_int</a></li>
912 <li><a href='#sqlite3_result_blob'>sqlite3_result_int64</a></li>
913 <li><a href='#sqlite3_result_blob'>sqlite3_result_null</a></li>
914 <li><a href='#sqlite3_result_blob'>sqlite3_result_pointer</a></li>
915 <li><a href='#sqlite3_result_subtype'>sqlite3_result_subtype</a></li>
916 <li><a href='#sqlite3_result_blob'>sqlite3_result_text</a></li>
917 <li><a href='#sqlite3_result_blob'>sqlite3_result_text16</a></li>
918 <li><a href='#sqlite3_result_blob'>sqlite3_result_text16be</a></li>
919 <li><a href='#sqlite3_result_blob'>sqlite3_result_text16le</a></li>
920 <li><a href='#sqlite3_result_blob'>sqlite3_result_text64</a></li>
921 <li><a href='#sqlite3_result_blob'>sqlite3_result_value</a></li>
922 <li><a href='#sqlite3_result_blob'>sqlite3_result_zeroblob</a></li>
923 <li><a href='#sqlite3_result_blob'>sqlite3_result_zeroblob64</a></li>
924 <li><a href='#sqlite3_commit_hook'>sqlite3_rollback_hook</a></li>
925 <li><a href='#sqlite3_serialize'>sqlite3_serialize</a></li>
926 <li><a href='#sqlite3_set_authorizer'>sqlite3_set_authorizer</a></li>
927 <li><a href='#sqlite3_get_auxdata'>sqlite3_set_auxdata</a></li>
928 <li><a href='#sqlite3_get_clientdata'>sqlite3_set_clientdata</a></li>
929 <li><a href='#sqlite3_set_errmsg'>sqlite3_set_errmsg</a></li>
930 <li><a href='#sqlite3_set_last_insert_rowid'>sqlite3_set_last_insert_rowid</a></li>
931 <li><a href='#sqlite3_setlk_timeout'>sqlite3_setlk_timeout</a></li>
932 <li><a href='#sqlite3_initialize'>sqlite3_shutdown</a></li>
933 <li><a href='#sqlite3_sleep'>sqlite3_sleep</a></li>
934 <li><a href='#sqlite3_snapshot_cmp'>sqlite3_snapshot_cmp</a></li>
935 <li><a href='#sqlite3_snapshot_free'>sqlite3_snapshot_free</a></li>
936 <li><a href='#sqlite3_snapshot_get'>sqlite3_snapshot_get</a></li>
937 <li><a href='#sqlite3_snapshot_open'>sqlite3_snapshot_open</a></li>
938 <li><a href='#sqlite3_snapshot_recover'>sqlite3_snapshot_recover</a></li>
939 <li><a href='#sqlite3_mprintf'>sqlite3_snprintf</a></li>
940 <li><s>sqlite3_soft_heap_limit</s></li>
941 <li><a href='#sqlite3_hard_heap_limit64'>sqlite3_soft_heap_limit64</a></li>
942 <li><a href='#sqlite3_libversion'>sqlite3_sourceid</a></li>
943 <li><a href='#sqlite3_expanded_sql'>sqlite3_sql</a></li>
944 <li><a href='#sqlite3_status'>sqlite3_status</a></li>
945 <li><a href='#sqlite3_status'>sqlite3_status64</a></li>
946 <li><a href='#sqlite3_step'>sqlite3_step</a></li>
947 <li><a href='#sqlite3_stmt_busy'>sqlite3_stmt_busy</a></li>
948 <li><a href='#sqlite3_stmt_explain'>sqlite3_stmt_explain</a></li>
949 <li><a href='#sqlite3_stmt_isexplain'>sqlite3_stmt_isexplain</a></li>
950 <li><a href='#sqlite3_stmt_readonly'>sqlite3_stmt_readonly</a></li>
951 <li><a href='#sqlite3_stmt_scanstatus'>sqlite3_stmt_scanstatus</a></li>
952 <li><a href='#sqlite3_stmt_scanstatus_reset'>sqlite3_stmt_scanstatus_reset</a></li>
953 <li><a href='#sqlite3_stmt_scanstatus'>sqlite3_stmt_scanstatus_v2</a></li>
954 <li><a href='#sqlite3_stmt_status'>sqlite3_stmt_status</a></li>
955 <li><a href='#sqlite3_str_append'>sqlite3_str_append</a></li>
956 <li><a href='#sqlite3_str_append'>sqlite3_str_appendall</a></li>
957 <li><a href='#sqlite3_str_append'>sqlite3_str_appendchar</a></li>
958 <li><a href='#sqlite3_str_append'>sqlite3_str_appendf</a></li>
959 <li><a href='#sqlite3_str_errcode'>sqlite3_str_errcode</a></li>
960 <li><a href='#sqlite3_str_finish'>sqlite3_str_finish</a></li>
961 <li><a href='#sqlite3_str_finish'>sqlite3_str_free</a></li>
962 <li><a href='#sqlite3_str_errcode'>sqlite3_str_length</a></li>
963 <li><a href='#sqlite3_str_new'>sqlite3_str_new</a></li>
964 <li><a href='#sqlite3_str_append'>sqlite3_str_reset</a></li>
965 <li><a href='#sqlite3_str_append'>sqlite3_str_truncate</a></li>
966 <li><a href='#sqlite3_str_errcode'>sqlite3_str_value</a></li>
967 <li><a href='#sqlite3_str_append'>sqlite3_str_vappendf</a></li>
968 <li><a href='#sqlite3_strglob'>sqlite3_strglob</a></li>
969 <li><a href='#sqlite3_stricmp'>sqlite3_stricmp</a></li>
970 <li><a href='#sqlite3_strlike'>sqlite3_strlike</a></li>
971 <li><a href='#sqlite3_stricmp'>sqlite3_strnicmp</a></li>
972 <li><a href='#sqlite3_system_errno'>sqlite3_system_errno</a></li>
973 <li><a href='#sqlite3_table_column_metadata'>sqlite3_table_column_metadata</a></li>
974 <li><a href='#sqlite3_test_control'>sqlite3_test_control</a></li>
975 <li><s>sqlite3_thread_cleanup</s></li>
976 <li><a href='#sqlite3_threadsafe'>sqlite3_threadsafe</a></li>
977 <li><a href='#sqlite3_total_changes'>sqlite3_total_changes</a></li>
978 <li><a href='#sqlite3_total_changes'>sqlite3_total_changes64</a></li>
979 <li><s>sqlite3_trace</s></li>
980 <li><a href='#sqlite3_trace_v2'>sqlite3_trace_v2</a></li>
981 <li><s>sqlite3_transfer_bindings</s></li>
982 <li><a href='#sqlite3_txn_state'>sqlite3_txn_state</a></li>
983 <li><a href='#sqlite3_unlock_notify'>sqlite3_unlock_notify</a></li>
984 <li><a href='#sqlite3_update_hook'>sqlite3_update_hook</a></li>
985 <li><a href='#sqlite3_uri_boolean'>sqlite3_uri_boolean</a></li>
986 <li><a href='#sqlite3_uri_boolean'>sqlite3_uri_int64</a></li>
987 <li><a href='#sqlite3_uri_boolean'>sqlite3_uri_key</a></li>
988 <li><a href='#sqlite3_uri_boolean'>sqlite3_uri_parameter</a></li>
989 <li><a href='#sqlite3_user_data'>sqlite3_user_data</a></li>
990 <li><a href='#sqlite3_value_blob'>sqlite3_value_blob</a></li>
991 <li><a href='#sqlite3_value_blob'>sqlite3_value_bytes</a></li>
992 <li><a href='#sqlite3_value_blob'>sqlite3_value_bytes16</a></li>
993 <li><a href='#sqlite3_value_blob'>sqlite3_value_double</a></li>
994 <li><a href='#sqlite3_value_dup'>sqlite3_value_dup</a></li>
995 <li><a href='#sqlite3_value_encoding'>sqlite3_value_encoding</a></li>
996 <li><a href='#sqlite3_value_dup'>sqlite3_value_free</a></li>
997 <li><a href='#sqlite3_value_blob'>sqlite3_value_frombind</a></li>
998 <li><a href='#sqlite3_value_blob'>sqlite3_value_int</a></li>
999 <li><a href='#sqlite3_value_blob'>sqlite3_value_int64</a></li>
1000 <li><a href='#sqlite3_value_blob'>sqlite3_value_nochange</a></li>
1001 <li><a href='#sqlite3_value_blob'>sqlite3_value_numeric_type</a></li>
1002 <li><a href='#sqlite3_value_blob'>sqlite3_value_pointer</a></li>
1003 <li><a href='#sqlite3_value_subtype'>sqlite3_value_subtype</a></li>
1004 <li><a href='#sqlite3_value_blob'>sqlite3_value_text</a></li>
1005 <li><a href='#sqlite3_value_blob'>sqlite3_value_text16</a></li>
1006 <li><a href='#sqlite3_value_blob'>sqlite3_value_text16be</a></li>
1007 <li><a href='#sqlite3_value_blob'>sqlite3_value_text16le</a></li>
1008 <li><a href='#sqlite3_value_blob'>sqlite3_value_type</a></li>
1009 <li><a href='#sqlite3_libversion'>sqlite3_version</a></li>
1010 <li><a href='#sqlite3_vfs_find'>sqlite3_vfs_find</a></li>
1011 <li><a href='#sqlite3_vfs_find'>sqlite3_vfs_register</a></li>
1012 <li><a href='#sqlite3_vfs_find'>sqlite3_vfs_unregister</a></li>
1013 <li><a href='#sqlite3_mprintf'>sqlite3_vmprintf</a></li>
1014 <li><a href='#sqlite3_mprintf'>sqlite3_vsnprintf</a></li>
1015 <li><a href='#sqlite3_vtab_collation'>sqlite3_vtab_collation</a></li>
1016 <li><a href='#sqlite3_vtab_config'>sqlite3_vtab_config</a></li>
1017 <li><a href='#sqlite3_vtab_distinct'>sqlite3_vtab_distinct</a></li>
1018 <li><a href='#sqlite3_vtab_in'>sqlite3_vtab_in</a></li>
1019 <li><a href='#sqlite3_vtab_in_first'>sqlite3_vtab_in_first</a></li>
1020 <li><a href='#sqlite3_vtab_in_first'>sqlite3_vtab_in_next</a></li>
1021 <li><a href='#sqlite3_vtab_nochange'>sqlite3_vtab_nochange</a></li>
1022 <li><a href='#sqlite3_vtab_on_conflict'>sqlite3_vtab_on_conflict</a></li>
1023 <li><a href='#sqlite3_vtab_rhs_value'>sqlite3_vtab_rhs_value</a></li>
1024 <li><a href='#sqlite3_wal_autocheckpoint'>sqlite3_wal_autocheckpoint</a></li>
1025 <li><a href='#sqlite3_wal_checkpoint'>sqlite3_wal_checkpoint</a></li>
1026 <li><a href='#sqlite3_wal_checkpoint_v2'>sqlite3_wal_checkpoint_v2</a></li>
1027 <li><a href='#sqlite3_wal_hook'>sqlite3_wal_hook</a></li>
1028 <li><a href='#sqlite3_win32_set_directory'>sqlite3_win32_set_directory</a></li>
1029 <li><a href='#sqlite3_win32_set_directory'>sqlite3_win32_set_directory16</a></li>
1030 <li><a href='#sqlite3_win32_set_directory'>sqlite3_win32_set_directory8</a></li>
1031 </ul>
1032 </div>
1033 <hr>
1034 <a name="SQLITE_SERIALIZE_NOCOPY"></a>
1035 <h2>Flags for sqlite3_serialize</h2>
1036 </div>
1037 <blockquote><pre>
1038 #define SQLITE_SERIALIZE_NOCOPY 0x001 /* Do no memory allocations */
1039 </pre></blockquote>
1040 <p>
1041 Zero or more of the following constants can be OR-ed together for
1042 the F argument to <a href="#sqlite3_serialize">sqlite3_serialize(D,S,P,F)</a>.</p>
1043
1044 <p>SQLITE_SERIALIZE_NOCOPY means that <a href="#sqlite3_serialize">sqlite3_serialize()</a> will return
1045 a pointer to contiguous in-memory database that it is currently using,
1046 without making a copy of the database. If SQLite is not currently using
1047 a contiguous in-memory database, then this option causes
1048 <a href="#sqlite3_serialize">sqlite3_serialize()</a> to return a NULL pointer. SQLite will only be
1049 using a contiguous in-memory database if it has been initialized by a
1050 prior call to <a href="#sqlite3_deserialize">sqlite3_deserialize()</a>.
1051 </p><hr><a name="SQLITE_SETLK_BLOCK_ON_CONNECT"></a>
1052 <h2>Flags for sqlite3_setlk_timeout()</h2>
1053 </div>
1054 <blockquote><pre>
1055 #define SQLITE_SETLK_BLOCK_ON_CONNECT 0x01
1056 </pre></blockquote>
1057 <p></p><hr><a name="SQLITE_SHM_NLOCK"></a>
1058 <h2>Maximum xShmLock index</h2>
1059 </div>
1060 <blockquote><pre>
1061 #define SQLITE_SHM_NLOCK 8
1062 </pre></blockquote>
1063 <p>
1064 The xShmLock method on <a href="#sqlite3_io_methods">sqlite3_io_methods</a> may use values
1065 between 0 and this upper bound as its "offset" argument.
1066 The SQLite core will never attempt to acquire or release a
1067 lock outside of this range
1068 </p><hr><a name="sqlite3_api_routines"></a>
1069 <h2>Loadable Extension Thunk</h2>
1070 </div>
1071 <blockquote><pre>
1072 typedef struct sqlite3_api_routines sqlite3_api_routines;
1073 </pre></blockquote>
1074 <p>
1075 A pointer to the opaque sqlite3_api_routines structure is passed as
1076 the third parameter to entry points of <a href="loadext.html">loadable extensions</a>. This
1077 structure must be typedefed in order to work around compiler warnings
1078 on some platforms.
1079 </p><hr><a name="sqlite3_backup"></a>
1080 <h2>Online Backup Object</h2>
1081 </div>
1082 <blockquote><pre>
1083 typedef struct sqlite3_backup sqlite3_backup;
1084 </pre></blockquote>
1085 <p>
1086 The sqlite3_backup object records state information about an ongoing
1087 online backup operation. The sqlite3_backup object is created by
1088 a call to <a href="#sqlite3backupinit">sqlite3_backup_init()</a> and is destroyed by a call to
1089 <a href="#sqlite3backupfinish">sqlite3_backup_finish()</a>.</p>
1090
1091 <p>See Also: <a href="backup.html">Using the SQLite Online Backup API</a>
1092 </p><hr><a name="sqlite3_context"></a>
1093 <h2>SQL Function Context Object</h2>
1094 </div>
1095 <blockquote><pre>
1096 typedef struct sqlite3_context sqlite3_context;
1097 </pre></blockquote>
1098 <p>
1099 The context in which an SQL function executes is stored in an
1100 sqlite3_context object. A pointer to an sqlite3_context object
1101 is always the first parameter to <a href="appfunc.html">application-defined SQL functions</a>.
1102 The application-defined SQL function implementation will pass this
1103 pointer through into calls to <a href="#sqlite3_result_blob">sqlite3_result()</a>,
1104 <a href="#sqlite3_aggregate_context">sqlite3_aggregate_context()</a>, <a href="#sqlite3_user_data">sqlite3_user_data()</a>,
1105 <a href="#sqlite3_context_db_handle">sqlite3_context_db_handle()</a>, <a href="#sqlite3_get_auxdata">sqlite3_get_auxdata()</a>,
1106 and/or <a href="#sqlite3_get_auxdata">sqlite3_set_auxdata()</a>.
1107 </p><p>26 Methods using this object:
1108 <div class='columns' style='columns: 17em auto;'>
1109 <ul style='padding-top:0;'>
1110 <li><a href='#sqlite3_aggregate_context'>sqlite3_aggregate_context</a></li>
1111 <li><a href='#sqlite3_context_db_handle'>sqlite3_context_db_handle</a></li>
1112 <li><a href='#sqlite3_get_auxdata'>sqlite3_get_auxdata</a></li>
1113 <li><a href='#sqlite3_result_blob'>sqlite3_result_blob</a></li>
1114 <li><a href='#sqlite3_result_blob'>sqlite3_result_blob64</a></li>
1115 <li><a href='#sqlite3_result_blob'>sqlite3_result_double</a></li>
1116 <li><a href='#sqlite3_result_blob'>sqlite3_result_error</a></li>
1117 <li><a href='#sqlite3_result_blob'>sqlite3_result_error16</a></li>
1118 <li><a href='#sqlite3_result_blob'>sqlite3_result_error_code</a></li>
1119 <li><a href='#sqlite3_result_blob'>sqlite3_result_error_nomem</a></li>
1120 <li><a href='#sqlite3_result_blob'>sqlite3_result_error_toobig</a></li>
1121 <li><a href='#sqlite3_result_blob'>sqlite3_result_int</a></li>
1122 <li><a href='#sqlite3_result_blob'>sqlite3_result_int64</a></li>
1123 <li><a href='#sqlite3_result_blob'>sqlite3_result_null</a></li>
1124 <li><a href='#sqlite3_result_blob'>sqlite3_result_pointer</a></li>
1125 <li><a href='#sqlite3_result_subtype'>sqlite3_result_subtype</a></li>
1126 <li><a href='#sqlite3_result_blob'>sqlite3_result_text</a></li>
1127 <li><a href='#sqlite3_result_blob'>sqlite3_result_text16</a></li>
1128 <li><a href='#sqlite3_result_blob'>sqlite3_result_text16be</a></li>
1129 <li><a href='#sqlite3_result_blob'>sqlite3_result_text16le</a></li>
1130 <li><a href='#sqlite3_result_blob'>sqlite3_result_text64</a></li>
1131 <li><a href='#sqlite3_result_blob'>sqlite3_result_value</a></li>
1132 <li><a href='#sqlite3_result_blob'>sqlite3_result_zeroblob</a></li>
1133 <li><a href='#sqlite3_result_blob'>sqlite3_result_zeroblob64</a></li>
1134 <li><a href='#sqlite3_get_auxdata'>sqlite3_set_auxdata</a></li>
1135 <li><a href='#sqlite3_user_data'>sqlite3_user_data</a></li>
1136 </ul>
1137 </div>
1138 </p>
1139 <hr><a name="sqlite3_data_directory"></a>
1140 <h2>Name Of The Folder Holding Database Files</h2>
1141 </div>
1142 <blockquote><pre>
1143 SQLITE_EXTERN char *sqlite3_data_directory;
1144 </pre></blockquote>
1145 <p>
1146 If this global variable is made to point to a string which is
1147 the name of a folder (a.k.a. directory), then all database files
1148 specified with a relative pathname and created or accessed by
1149 SQLite when using a built-in windows <a href="#sqlite3_vfs">VFS</a> will be assumed
1150 to be relative to that directory. If this variable is a NULL
1151 pointer, then SQLite assumes that all database files specified
1152 with a relative pathname are relative to the current directory
1153 for the process. Only the windows VFS makes use of this global
1154 variable; it is ignored by the unix VFS.</p>
1155
1156 <p>Changing the value of this variable while a database connection is
1157 open can result in a corrupt database.</p>
1158
1159 <p>It is not safe to read or modify this variable in more than one
1160 thread at a time. It is not safe to read or modify this variable
1161 if a <a href="#sqlite3">database connection</a> is being used at the same time in a separate
1162 thread.
1163 It is intended that this variable be set once
1164 as part of process initialization and before any SQLite interface
1165 routines have been called and that this variable remain unchanged
1166 thereafter.</p>
1167
1168 <p>The <a href="pragma.html#pragma_data_store_directory">data_store_directory pragma</a> may modify this variable and cause
1169 it to point to memory obtained from <a href="#sqlite3_free">sqlite3_malloc</a>. Furthermore,
1170 the <a href="pragma.html#pragma_data_store_directory">data_store_directory pragma</a> always assumes that any string
1171 that this variable points to is held in memory obtained from
1172 <a href="#sqlite3_free">sqlite3_malloc</a> and the pragma may attempt to free that memory
1173 using <a href="#sqlite3_free">sqlite3_free</a>.
1174 Hence, if this variable is modified directly, either it should be
1175 made NULL or made to point to memory obtained from <a href="#sqlite3_free">sqlite3_malloc</a>
1176 or else the use of the <a href="pragma.html#pragma_data_store_directory">data_store_directory pragma</a> should be avoided.
1177 </p><hr><a name="sqlite3_file"></a>
1178 <h2>OS Interface Open File Handle</h2>
1179 </div>
1180 <blockquote><pre>
1181 typedef struct sqlite3_file sqlite3_file;
1182 struct sqlite3_file {
1183 const struct sqlite3_io_methods *pMethods; /* Methods for an open file */
1184 };
1185 </pre></blockquote>
1186 <p>
1187 An <a href="#sqlite3_file">sqlite3_file</a> object represents an open file in the
1188 <a href="#sqlite3_vfs">OS interface layer</a>. Individual OS interface
1189 implementations will
1190 want to subclass this object by appending additional fields
1191 for their own use. The pMethods entry is a pointer to an
1192 <a href="#sqlite3_io_methods">sqlite3_io_methods</a> object that defines methods for performing
1193 I/O operations on the open file.
1194 </p><hr><a name="sqlite3_filename"></a>
1195 <h2>File Name</h2>
1196 </div>
1197 <blockquote><pre>
1198 typedef const char *sqlite3_filename;
1199 </pre></blockquote>
1200 <p>
1201 Type <a href="#sqlite3_filename">sqlite3_filename</a> is used by SQLite to pass filenames to the
1202 xOpen method of a <a href="vfs.html">VFS</a>. It may be cast to (const char*) and treated
1203 as a normal, nul-terminated, UTF-8 buffer containing the filename, but
1204 may also be passed to special APIs such as:</p>
1205
1206 <p><ul>
1207 <li> sqlite3_filename_database()
1208 <li> sqlite3_filename_journal()
1209 <li> sqlite3_filename_wal()
1210 <li> sqlite3_uri_parameter()
1211 <li> sqlite3_uri_boolean()
1212 <li> sqlite3_uri_int64()
1213 <li> sqlite3_uri_key()
1214 </ul>
1215 </p><hr><a name="sqlite3_index_info"></a>
1216 <h2>Virtual Table Indexing Information</h2>
1217 </div>
1218 <blockquote><pre>
1219 struct sqlite3_index_info {
1220 /* Inputs */
1221 int nConstraint; /* Number of entries in aConstraint */
1222 struct sqlite3_index_constraint {
1223 int iColumn; /* Column constrained. -1 for ROWID */
1224 unsigned char op; /* Constraint operator */
1225 unsigned char usable; /* True if this constraint is usable */
1226 int iTermOffset; /* Used internally - xBestIndex should ignore */
1227 } *aConstraint; /* Table of WHERE clause constraints */
1228 int nOrderBy; /* Number of terms in the ORDER BY clause */
1229 struct sqlite3_index_orderby {
1230 int iColumn; /* Column number */
1231 unsigned char desc; /* True for DESC. False for ASC. */
1232 } *aOrderBy; /* The ORDER BY clause */
1233 /* Outputs */
1234 struct sqlite3_index_constraint_usage {
1235 int argvIndex; /* if &gt;0, constraint is part of argv to xFilter */
1236 unsigned char omit; /* Do not code a test for this constraint */
1237 } *aConstraintUsage;
1238 int idxNum; /* Number used to identify the index */
1239 char *idxStr; /* String, possibly obtained from sqlite3_malloc */
1240 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
1241 int orderByConsumed; /* True if output is already ordered */
1242 double estimatedCost; /* Estimated cost of using this index */
1243 /* Fields below are only available in SQLite 3.8.2 and later */
1244 sqlite3_int64 estimatedRows; /* Estimated number of rows returned */
1245 /* Fields below are only available in SQLite 3.9.0 and later */
1246 int idxFlags; /* Mask of SQLITE_INDEX_SCAN_* flags */
1247 /* Fields below are only available in SQLite 3.10.0 and later */
1248 sqlite3_uint64 colUsed; /* Input: Mask of columns used by statement */
1249 };
1250 </pre></blockquote>
1251 <p>
1252 The sqlite3_index_info structure and its substructures is used as part
1253 of the <a href="vtab.html">virtual table</a> interface to
1254 pass information into and receive the reply from the <a href="vtab.html#xbestindex">xBestIndex</a>
1255 method of a <a href="#sqlite3_module">virtual table module</a>. The fields under **Inputs** are the
1256 inputs to xBestIndex and are read-only. xBestIndex inserts its
1257 results into the **Outputs** fields.</p>
1258
1259 <p>The aConstraint[] array records WHERE clause constraints of the form:</p>
1260
1261 <p><blockquote>column OP expr</blockquote></p>
1262
1263 <p>where OP is =, &lt;, &lt;=, &gt;, or &gt;=. The particular operator is
1264 stored in aConstraint[].op using one of the
1265 <a href="#SQLITE_INDEX_CONSTRAINT_EQ">SQLITE_INDEX_CONSTRAINT_ values</a>.
1266 The index of the column is stored in
1267 aConstraint[].iColumn. aConstraint[].usable is TRUE if the
1268 expr on the right-hand side can be evaluated (and thus the constraint
1269 is usable) and false if it cannot.</p>
1270
1271 <p>The optimizer automatically inverts terms of the form "expr OP column"
1272 and makes other simplifications to the WHERE clause in an attempt to
1273 get as many WHERE clause terms into the form shown above as possible.
1274 The aConstraint[] array only reports WHERE clause terms that are
1275 relevant to the particular virtual table being queried.</p>
1276
1277 <p>Information about the ORDER BY clause is stored in aOrderBy[].
1278 Each term of aOrderBy records a column of the ORDER BY clause.</p>
1279
1280 <p>The colUsed field indicates which columns of the virtual table may be
1281 required by the current scan. Virtual table columns are numbered from
1282 zero in the order in which they appear within the CREATE TABLE statement
1283 passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62),
1284 the corresponding bit is set within the colUsed mask if the column may be
1285 required by SQLite. If the table has at least 64 columns and any column
1286 to the right of the first 63 is required, then bit 63 of colUsed is also
1287 set. In other words, column iCol may be required if the expression
1288 (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to
1289 non-zero.</p>
1290
1291 <p>The <a href="vtab.html#xbestindex">xBestIndex</a> method must fill aConstraintUsage[] with information
1292 about what parameters to pass to xFilter. If argvIndex>0 then
1293 the right-hand side of the corresponding aConstraint[] is evaluated
1294 and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit
1295 is true, then the constraint is assumed to be fully handled by the
1296 virtual table and might not be checked again by the byte code. The
1297 aConstraintUsage[].omit flag is an optimization hint. When the omit flag
1298 is left in its default setting of false, the constraint will always be
1299 checked separately in byte code. If the omit flag is changed to true, then
1300 the constraint may or may not be checked in byte code. In other words,
1301 when the omit flag is true there is no guarantee that the constraint will
1302 not be checked again using byte code.</p>
1303
1304 <p>The idxNum and idxStr values are recorded and passed into the
1305 <a href="vtab.html#xfilter">xFilter</a> method.
1306 <a href="#sqlite3_free">sqlite3_free()</a> is used to free idxStr if and only if
1307 needToFreeIdxStr is true.</p>
1308
1309 <p>The orderByConsumed means that output from <a href="vtab.html#xfilter">xFilter</a>/<a href="vtab.html#xnext">xNext</a> will occur in
1310 the correct order to satisfy the ORDER BY clause so that no separate
1311 sorting step is required.</p>
1312
1313 <p>The estimatedCost value is an estimate of the cost of a particular
1314 strategy. A cost of N indicates that the cost of the strategy is similar
1315 to a linear scan of an SQLite table with N rows. A cost of log(N)
1316 indicates that the expense of the operation is similar to that of a
1317 binary search on a unique indexed field of an SQLite table with N rows.</p>
1318
1319 <p>The estimatedRows value is an estimate of the number of rows that
1320 will be returned by the strategy.</p>
1321
1322 <p>The xBestIndex method may optionally populate the idxFlags field with a
1323 mask of SQLITE_INDEX_SCAN_* flags. One such flag is
1324 <a href="#SQLITE_INDEX_SCAN_HEX">SQLITE_INDEX_SCAN_HEX</a>, which if set causes the <a href="eqp.html">EXPLAIN QUERY PLAN</a>
1325 output to show the idxNum as hex instead of as decimal. Another flag is
1326 SQLITE_INDEX_SCAN_UNIQUE, which if set indicates that the query plan will
1327 return at most one row.</p>
1328
1329 <p>Additionally, if xBestIndex sets the SQLITE_INDEX_SCAN_UNIQUE flag, then
1330 SQLite also assumes that if a call to the xUpdate() method is made as
1331 part of the same statement to delete or update a virtual table row and the
1332 implementation returns SQLITE_CONSTRAINT, then there is no need to rollback
1333 any database changes. In other words, if the xUpdate() returns
1334 SQLITE_CONSTRAINT, the database contents must be exactly as they were
1335 before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not
1336 set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by
1337 the xUpdate method are automatically rolled back by SQLite.</p>
1338
1339 <p>IMPORTANT: The estimatedRows field was added to the sqlite3_index_info
1340 structure for SQLite <a href="releaselog/3_8_2.html">version 3.8.2</a> (2013-12-06).
1341 If a virtual table extension is
1342 used with an SQLite version earlier than 3.8.2, the results of attempting
1343 to read or write the estimatedRows field are undefined (but are likely
1344 to include crashing the application). The estimatedRows field should
1345 therefore only be used if <a href="#sqlite3_libversion">sqlite3_libversion_number()</a> returns a
1346 value greater than or equal to 3008002. Similarly, the idxFlags field
1347 was added for <a href="releaselog/3_9_0.html">version 3.9.0</a> (2015-10-14).
1348 It may therefore only be used if
1349 sqlite3_libversion_number() returns a value greater than or equal to
1350 3009000.
1351 </p><p>3 Methods using this object:
1352 <a href="#sqlite3_vtab_collation">sqlite3_vtab_collation()</a>,
1353 <a href="#sqlite3_vtab_distinct">sqlite3_vtab_distinct()</a>,
1354 <a href="#sqlite3_vtab_rhs_value">sqlite3_vtab_rhs_value()</a></p>
1355 <hr><a name="sqlite3_io_methods"></a>
1356 <h2>OS Interface File Virtual Methods Object</h2>
1357 </div>
1358 <blockquote><pre>
1359 typedef struct sqlite3_io_methods sqlite3_io_methods;
1360 struct sqlite3_io_methods {
1361 int iVersion;
1362 int (*xClose)(sqlite3_file*);
1363 int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
1364 int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
1365 int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
1366 int (*xSync)(sqlite3_file*, int flags);
1367 int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
1368 int (*xLock)(sqlite3_file*, int);
1369 int (*xUnlock)(sqlite3_file*, int);
1370 int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
1371 int (*xFileControl)(sqlite3_file*, int op, void *pArg);
1372 int (*xSectorSize)(sqlite3_file*);
1373 int (*xDeviceCharacteristics)(sqlite3_file*);
1374 /* Methods above are valid for version 1 */
1375 int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
1376 int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
1377 void (*xShmBarrier)(sqlite3_file*);
1378 int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
1379 /* Methods above are valid for version 2 */
1380 int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
1381 int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
1382 /* Methods above are valid for version 3 */
1383 /* Additional methods may be added in future releases */
1384 };
1385 </pre></blockquote>
1386 <p>
1387 Every file opened by the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> method populates an
1388 <a href="#sqlite3_file">sqlite3_file</a> object (or, more commonly, a subclass of the
1389 <a href="#sqlite3_file">sqlite3_file</a> object) with a pointer to an instance of this object.
1390 This object defines the methods used to perform various operations
1391 against the open file represented by the <a href="#sqlite3_file">sqlite3_file</a> object.</p>
1392
1393 <p>If the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> method sets the sqlite3_file.pMethods element
1394 to a non-NULL pointer, then the sqlite3_io_methods.xClose method
1395 may be invoked even if the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> reported that it failed. The
1396 only way to prevent a call to xClose following a failed <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a>
1397 is for the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> to set the sqlite3_file.pMethods element
1398 to NULL.</p>
1399
1400 <p>The flags argument to xSync may be one of <a href="#SQLITE_SYNC_DATAONLY">SQLITE_SYNC_NORMAL</a> or
1401 <a href="#SQLITE_SYNC_DATAONLY">SQLITE_SYNC_FULL</a>. The first choice is the normal fsync().
1402 The second choice is a Mac OS X style fullsync. The <a href="#SQLITE_SYNC_DATAONLY">SQLITE_SYNC_DATAONLY</a>
1403 flag may be ORed in to indicate that only the data of the file
1404 and not its inode needs to be synced.</p>
1405
1406 <p>The integer values to xLock() and xUnlock() are one of
1407 <ul>
1408 <li> <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_NONE</a>,
1409 <li> <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_SHARED</a>,
1410 <li> <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_RESERVED</a>,
1411 <li> <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_PENDING</a>, or
1412 <li> <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_EXCLUSIVE</a>.
1413 </ul>
1414 xLock() upgrades the database file lock. In other words, xLock() moves the
1415 database file lock in the direction NONE toward EXCLUSIVE. The argument to
1416 xLock() is always one of SHARED, RESERVED, PENDING, or EXCLUSIVE, never
1417 SQLITE_LOCK_NONE. If the database file lock is already at or above the
1418 requested lock, then the call to xLock() is a no-op.
1419 xUnlock() downgrades the database file lock to either SHARED or NONE.
1420 If the lock is already at or below the requested lock state, then the call
1421 to xUnlock() is a no-op.
1422 The xCheckReservedLock() method checks whether any database connection,
1423 either in this process or in some other process, is holding a RESERVED,
1424 PENDING, or EXCLUSIVE lock on the file. It returns, via its output
1425 pointer parameter, true if such a lock exists and false otherwise.</p>
1426
1427 <p>The xFileControl() method is a generic interface that allows custom
1428 VFS implementations to directly control an open file using the
1429 <a href="#sqlite3_file_control">sqlite3_file_control()</a> interface. The second "op" argument is an
1430 integer opcode. The third argument is a generic pointer intended to
1431 point to a structure that may contain arguments or space in which to
1432 write return values. Potential uses for xFileControl() might be
1433 functions to enable blocking locks with timeouts, to change the
1434 locking strategy (for example to use dot-file locks), to inquire
1435 about the status of a lock, or to break stale locks. The SQLite
1436 core reserves all opcodes less than 100 for its own use.
1437 A <a href="#SQLITE_FCNTL_BEGIN_ATOMIC_WRITE">list of opcodes</a> less than 100 is available.
1438 Applications that define a custom xFileControl method should use opcodes
1439 greater than 100 to avoid conflicts. VFS implementations should
1440 return <a href="#SQLITE_ABORT">SQLITE_NOTFOUND</a> for file control opcodes that they do not
1441 recognize.</p>
1442
1443 <p>The xSectorSize() method returns the sector size of the
1444 device that underlies the file. The sector size is the
1445 minimum write that can be performed without disturbing
1446 other bytes in the file. The xDeviceCharacteristics()
1447 method returns a bit vector describing behaviors of the
1448 underlying device:</p>
1449
1450 <p><ul>
1451 <li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC</a>
1452 <li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC512</a>
1453 <li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC1K</a>
1454 <li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC2K</a>
1455 <li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC4K</a>
1456 <li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC8K</a>
1457 <li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC16K</a>
1458 <li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC32K</a>
1459 <li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC64K</a>
1460 <li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_SAFE_APPEND</a>
1461 <li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_SEQUENTIAL</a>
1462 <li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN</a>
1463 <li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_POWERSAFE_OVERWRITE</a>
1464 <li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_IMMUTABLE</a>
1465 <li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_BATCH_ATOMIC</a>
1466 <li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_SUBPAGE_READ</a>
1467 </ul></p>
1468
1469 <p>The SQLITE_IOCAP_ATOMIC property means that all writes of
1470 any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
1471 mean that writes of blocks that are nnn bytes in size and
1472 are aligned to an address which is an integer multiple of
1473 nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
1474 that when data is appended to a file, the data is appended
1475 first then the size of the file is extended, never the other
1476 way around. The SQLITE_IOCAP_SEQUENTIAL property means that
1477 information is written to disk in the same order as calls
1478 to xWrite().</p>
1479
1480 <p>If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
1481 in the unread portions of the buffer with zeros. A VFS that
1482 fails to zero-fill short reads might seem to work. However,
1483 failure to zero-fill short reads will eventually lead to
1484 database corruption.
1485 </p><hr><a name="sqlite3_mem_methods"></a>
1486 <h2>Memory Allocation Routines</h2>
1487 </div>
1488 <blockquote><pre>
1489 typedef struct sqlite3_mem_methods sqlite3_mem_methods;
1490 struct sqlite3_mem_methods {
1491 void *(*xMalloc)(int); /* Memory allocation function */
1492 void (*xFree)(void*); /* Free a prior allocation */
1493 void *(*xRealloc)(void*,int); /* Resize an allocation */
1494 int (*xSize)(void*); /* Return the size of an allocation */
1495 int (*xRoundup)(int); /* Round up request size to allocation size */
1496 int (*xInit)(void*); /* Initialize the memory allocator */
1497 void (*xShutdown)(void*); /* Deinitialize the memory allocator */
1498 void *pAppData; /* Argument to xInit() and xShutdown() */
1499 };
1500 </pre></blockquote>
1501 <p>
1502 An instance of this object defines the interface between SQLite
1503 and low-level memory allocation routines.</p>
1504
1505 <p>This object is used in only one place in the SQLite interface.
1506 A pointer to an instance of this object is the argument to
1507 <a href="#sqlite3_config">sqlite3_config()</a> when the configuration option is
1508 <a href="#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a> or <a href="#sqliteconfiggetmalloc">SQLITE_CONFIG_GETMALLOC</a>.
1509 By creating an instance of this object
1510 and passing it to <a href="#sqlite3_config">sqlite3_config</a>(<a href="#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a>)
1511 during configuration, an application can specify an alternative
1512 memory allocation subsystem for SQLite to use for all of its
1513 dynamic memory needs.</p>
1514
1515 <p>Note that SQLite comes with several <a href="malloc.html#altalloc">built-in memory allocators</a>
1516 that are perfectly adequate for the overwhelming majority of applications
1517 and that this object is only useful to a tiny minority of applications
1518 with specialized memory allocation requirements. This object is
1519 also used during testing of SQLite in order to specify an alternative
1520 memory allocator that simulates memory out-of-memory conditions in
1521 order to verify that SQLite recovers gracefully from such
1522 conditions.</p>
1523
1524 <p>The xMalloc, xRealloc, and xFree methods must work like the
1525 malloc(), realloc() and free() functions from the standard C library.
1526 SQLite guarantees that the second argument to
1527 xRealloc is always a value returned by a prior call to xRoundup.</p>
1528
1529 <p>xSize should return the allocated size of a memory allocation
1530 previously obtained from xMalloc or xRealloc. The allocated size
1531 is always at least as big as the requested size but may be larger.</p>
1532
1533 <p>The xRoundup method returns what would be the allocated size of
1534 a memory allocation given a particular requested size. Most memory
1535 allocators round up memory allocations at least to the next multiple
1536 of 8. Some allocators round up to a larger multiple or to a power of 2.
1537 Every memory allocation request coming in through <a href="#sqlite3_free">sqlite3_malloc()</a>
1538 or <a href="#sqlite3_free">sqlite3_realloc()</a> first calls xRoundup. If xRoundup returns 0,
1539 that causes the corresponding memory allocation to fail.</p>
1540
1541 <p>The xInit method initializes the memory allocator. For example,
1542 it might allocate any required mutexes or initialize internal data
1543 structures. The xShutdown method is invoked (indirectly) by
1544 <a href="#sqlite3_initialize">sqlite3_shutdown()</a> and should deallocate any resources acquired
1545 by xInit. The pAppData pointer is used as the only parameter to
1546 xInit and xShutdown.</p>
1547
1548 <p>SQLite holds the <a href="#SQLITE_MUTEX_FAST">SQLITE_MUTEX_STATIC_MAIN</a> mutex when it invokes
1549 the xInit method, so the xInit method need not be threadsafe. The
1550 xShutdown method is only called from <a href="#sqlite3_initialize">sqlite3_shutdown()</a> so it does
1551 not need to be threadsafe either. For all other methods, SQLite
1552 holds the <a href="#SQLITE_MUTEX_FAST">SQLITE_MUTEX_STATIC_MEM</a> mutex as long as the
1553 <a href="#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> configuration option is turned on (which
1554 it is by default) and so the methods are automatically serialized.
1555 However, if <a href="#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> is disabled, then the other
1556 methods must be threadsafe or else make their own arrangements for
1557 serialization.</p>
1558
1559 <p>SQLite will never invoke xInit() more than once without an intervening
1560 call to xShutdown().
1561 </p><hr><a name="sqlite3_mutex"></a>
1562 <h2>Mutex Handle</h2>
1563 </div>
1564 <blockquote><pre>
1565 typedef struct sqlite3_mutex sqlite3_mutex;
1566 </pre></blockquote>
1567 <p>
1568 The mutex module within SQLite defines <a href="#sqlite3_mutex">sqlite3_mutex</a> to be an
1569 abstract type for a mutex object. The SQLite core never looks
1570 at the internal representation of an <a href="#sqlite3_mutex">sqlite3_mutex</a>. It only
1571 deals with pointers to the <a href="#sqlite3_mutex">sqlite3_mutex</a> object.</p>
1572
1573 <p>Mutexes are created using <a href="#sqlite3_mutex_alloc">sqlite3_mutex_alloc()</a>.
1574 </p><hr><a name="sqlite3_mutex_methods"></a>
1575 <h2>Mutex Methods Object</h2>
1576 </div>
1577 <blockquote><pre>
1578 typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
1579 struct sqlite3_mutex_methods {
1580 int (*xMutexInit)(void);
1581 int (*xMutexEnd)(void);
1582 sqlite3_mutex *(*xMutexAlloc)(int);
1583 void (*xMutexFree)(sqlite3_mutex *);
1584 void (*xMutexEnter)(sqlite3_mutex *);
1585 int (*xMutexTry)(sqlite3_mutex *);
1586 void (*xMutexLeave)(sqlite3_mutex *);
1587 int (*xMutexHeld)(sqlite3_mutex *);
1588 int (*xMutexNotheld)(sqlite3_mutex *);
1589 };
1590 </pre></blockquote>
1591 <p>
1592 An instance of this structure defines the low-level routines
1593 used to allocate and use mutexes.</p>
1594
1595 <p>Usually, the default mutex implementations provided by SQLite are
1596 sufficient, however the application has the option of substituting a custom
1597 implementation for specialized deployments or systems for which SQLite
1598 does not provide a suitable implementation. In this case, the application
1599 creates and populates an instance of this structure to pass
1600 to sqlite3_config() along with the <a href="#sqliteconfigmutex">SQLITE_CONFIG_MUTEX</a> option.
1601 Additionally, an instance of this structure can be used as an
1602 output variable when querying the system for the current mutex
1603 implementation, using the <a href="#sqliteconfiggetmutex">SQLITE_CONFIG_GETMUTEX</a> option.</p>
1604
1605 <p>The xMutexInit method defined by this structure is invoked as
1606 part of system initialization by the sqlite3_initialize() function.
1607 The xMutexInit routine is called by SQLite exactly once for each
1608 effective call to <a href="#sqlite3_initialize">sqlite3_initialize()</a>.</p>
1609
1610 <p>The xMutexEnd method defined by this structure is invoked as
1611 part of system shutdown by the sqlite3_shutdown() function. The
1612 implementation of this method is expected to release all outstanding
1613 resources obtained by the mutex methods implementation, especially
1614 those obtained by the xMutexInit method. The xMutexEnd()
1615 interface is invoked exactly once for each call to <a href="#sqlite3_initialize">sqlite3_shutdown()</a>.</p>
1616
1617 <p>The remaining seven methods defined by this structure (xMutexAlloc,
1618 xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and
1619 xMutexNotheld) implement the following interfaces (respectively):</p>
1620
1621 <p><ul>
1622 <li> <a href="#sqlite3_mutex_alloc">sqlite3_mutex_alloc()</a> </li>
1623 <li> <a href="#sqlite3_mutex_alloc">sqlite3_mutex_free()</a> </li>
1624 <li> <a href="#sqlite3_mutex_alloc">sqlite3_mutex_enter()</a> </li>
1625 <li> <a href="#sqlite3_mutex_alloc">sqlite3_mutex_try()</a> </li>
1626 <li> <a href="#sqlite3_mutex_alloc">sqlite3_mutex_leave()</a> </li>
1627 <li> <a href="#sqlite3_mutex_held">sqlite3_mutex_held()</a> </li>
1628 <li> <a href="#sqlite3_mutex_held">sqlite3_mutex_notheld()</a> </li>
1629 </ul></p>
1630
1631 <p>The only difference is that the public sqlite3_XXX functions enumerated
1632 above silently ignore any invocations that pass a NULL pointer instead
1633 of a valid mutex handle. The implementations of the methods defined
1634 by this structure are not required to handle this case. The results
1635 of passing a NULL pointer instead of a valid mutex handle are undefined
1636 (i.e. it is acceptable to provide an implementation that segfaults if
1637 it is passed a NULL pointer).</p>
1638
1639 <p>The xMutexInit() method must be threadsafe. It must be harmless to
1640 invoke xMutexInit() multiple times within the same process and without
1641 intervening calls to xMutexEnd(). Second and subsequent calls to
1642 xMutexInit() must be no-ops.</p>
1643
1644 <p>xMutexInit() must not use SQLite memory allocation (<a href="#sqlite3_free">sqlite3_malloc()</a>
1645 and its associates). Similarly, xMutexAlloc() must not use SQLite memory
1646 allocation for a static mutex. However xMutexAlloc() may use SQLite
1647 memory allocation for a fast or recursive mutex.</p>
1648
1649 <p>SQLite will invoke the xMutexEnd() method when <a href="#sqlite3_initialize">sqlite3_shutdown()</a> is
1650 called, but only if the prior call to xMutexInit returned SQLITE_OK.
1651 If xMutexInit fails in any way, it is expected to clean up after itself
1652 prior to returning.
1653 </p><hr><a name="sqlite3_pcache"></a>
1654 <h2>Custom Page Cache Object</h2>
1655 </div>
1656 <blockquote><pre>
1657 typedef struct sqlite3_pcache sqlite3_pcache;
1658 </pre></blockquote>
1659 <p>
1660 The sqlite3_pcache type is opaque. It is implemented by
1661 the pluggable module. The SQLite core has no knowledge of
1662 its size or internal structure and never deals with the
1663 sqlite3_pcache object except by holding and passing pointers
1664 to the object.</p>
1665
1666 <p>See <a href="#sqlite3_pcache_methods2">sqlite3_pcache_methods2</a> for additional information.
1667 </p><hr><a name="sqlite3_pcache_page"></a>
1668 <h2>Custom Page Cache Object</h2>
1669 </div>
1670 <blockquote><pre>
1671 typedef struct sqlite3_pcache_page sqlite3_pcache_page;
1672 struct sqlite3_pcache_page {
1673 void *pBuf; /* The content of the page */
1674 void *pExtra; /* Extra information associated with the page */
1675 };
1676 </pre></blockquote>
1677 <p>
1678 The sqlite3_pcache_page object represents a single page in the
1679 page cache. The page cache will allocate instances of this
1680 object. Various methods of the page cache use pointers to instances
1681 of this object as parameters or as their return value.</p>
1682
1683 <p>See <a href="#sqlite3_pcache_methods2">sqlite3_pcache_methods2</a> for additional information.
1684 </p><hr><a name="sqlite3_temp_directory"></a>
1685 <h2>Name Of The Folder Holding Temporary Files</h2>
1686 </div>
1687 <blockquote><pre>
1688 SQLITE_EXTERN char *sqlite3_temp_directory;
1689 </pre></blockquote>
1690 <p>
1691 If this global variable is made to point to a string which is
1692 the name of a folder (a.k.a. directory), then all temporary files
1693 created by SQLite when using a built-in <a href="#sqlite3_vfs">VFS</a>
1694 will be placed in that directory. If this variable
1695 is a NULL pointer, then SQLite performs a search for an appropriate
1696 temporary file directory.</p>
1697
1698 <p>Applications are strongly discouraged from using this global variable.
1699 It is required to set a temporary folder on Windows Runtime (WinRT).
1700 But for all other platforms, it is highly recommended that applications
1701 neither read nor write this variable. This global variable is a relic
1702 that exists for backwards compatibility of legacy applications and should
1703 be avoided in new projects.</p>
1704
1705 <p>It is not safe to read or modify this variable in more than one
1706 thread at a time. It is not safe to read or modify this variable
1707 if a <a href="#sqlite3">database connection</a> is being used at the same time in a separate
1708 thread.
1709 It is intended that this variable be set once
1710 as part of process initialization and before any SQLite interface
1711 routines have been called and that this variable remain unchanged
1712 thereafter.</p>
1713
1714 <p>The <a href="pragma.html#pragma_temp_store_directory">temp_store_directory pragma</a> may modify this variable and cause
1715 it to point to memory obtained from <a href="#sqlite3_free">sqlite3_malloc</a>. Furthermore,
1716 the <a href="pragma.html#pragma_temp_store_directory">temp_store_directory pragma</a> always assumes that any string
1717 that this variable points to is held in memory obtained from
1718 <a href="#sqlite3_free">sqlite3_malloc</a> and the pragma may attempt to free that memory
1719 using <a href="#sqlite3_free">sqlite3_free</a>.
1720 Hence, if this variable is modified directly, either it should be
1721 made NULL or made to point to memory obtained from <a href="#sqlite3_free">sqlite3_malloc</a>
1722 or else the use of the <a href="pragma.html#pragma_temp_store_directory">temp_store_directory pragma</a> should be avoided.
1723 Except when requested by the <a href="pragma.html#pragma_temp_store_directory">temp_store_directory pragma</a>, SQLite
1724 does not free the memory that sqlite3_temp_directory points to. If
1725 the application wants that memory to be freed, it must do
1726 so itself, taking care to only do so after all <a href="#sqlite3">database connection</a>
1727 objects have been destroyed.</p>
1728
1729 <p><b>Note to Windows Runtime users:</b> The temporary directory must be set
1730 prior to calling <a href="#sqlite3_open">sqlite3_open</a> or <a href="#sqlite3_open">sqlite3_open_v2</a>. Otherwise, various
1731 features that require the use of temporary files may fail. Here is an
1732 example of how to do this using C++ with the Windows Runtime:</p>
1733
1734 <p><blockquote><pre>
1735 LPCWSTR zPath = Windows::Storage::ApplicationData::Current->
1736 &nbsp; TemporaryFolder->Path->Data();
1737 char zPathBuf&#91;MAX_PATH + 1&#93;;
1738 memset(zPathBuf, 0, sizeof(zPathBuf));
1739 WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, sizeof(zPathBuf),
1740 &nbsp; NULL, NULL);
1741 sqlite3_temp_directory = sqlite3_mprintf("%s", zPathBuf);
1742 </pre></blockquote>
1743 </p><hr><a name="sqlite3_vfs"></a>
1744 <h2>OS Interface Object</h2>
1745 </div>
1746 <blockquote><pre>
1747 typedef struct sqlite3_vfs sqlite3_vfs;
1748 typedef void (*sqlite3_syscall_ptr)(void);
1749 struct sqlite3_vfs {
1750 int iVersion; /* Structure version number (currently 3) */
1751 int szOsFile; /* Size of subclassed sqlite3_file */
1752 int mxPathname; /* Maximum file pathname length */
1753 sqlite3_vfs *pNext; /* Next registered VFS */
1754 const char *zName; /* Name of this virtual file system */
1755 void *pAppData; /* Pointer to application-specific data */
1756 int (*xOpen)(sqlite3_vfs*, sqlite3_filename zName, sqlite3_file*,
1757 int flags, int *pOutFlags);
1758 int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
1759 int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
1760 int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
1761 void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
1762 void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
1763 void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
1764 void (*xDlClose)(sqlite3_vfs*, void*);
1765 int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
1766 int (*xSleep)(sqlite3_vfs*, int microseconds);
1767 int (*xCurrentTime)(sqlite3_vfs*, double*);
1768 int (*xGetLastError)(sqlite3_vfs*, int, char *);
1769 /*
1770 ** The methods above are in version 1 of the sqlite_vfs object
1771 ** definition. Those that follow are added in version 2 or later
1772 */
1773 int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
1774 /*
1775 ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
1776 ** Those below are for version 3 and greater.
1777 */
1778 int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
1779 sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
1780 const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
1781 /*
1782 ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
1783 ** New fields may be appended in future versions. The iVersion
1784 ** value will increment whenever this happens.
1785 */
1786 };
1787 </pre></blockquote>
1788 <p>
1789 An instance of the sqlite3_vfs object defines the interface between
1790 the SQLite core and the underlying operating system. The "vfs"
1791 in the name of the object stands for "virtual file system". See
1792 the <a href="vfs.html">VFS documentation</a> for further information.</p>
1793
1794 <p>The VFS interface is sometimes extended by adding new methods onto
1795 the end. Each time such an extension occurs, the iVersion field
1796 is incremented. The iVersion value started out as 1 in
1797 SQLite <a href="releaselog/3_5_0.html">version 3.5.0</a> on 2007-09-04, then increased to 2
1798 with SQLite <a href="releaselog/3_7_0.html">version 3.7.0</a> on 2010-07-21, and then increased
1799 to 3 with SQLite <a href="releaselog/3_7_6.html">version 3.7.6</a> on 2011-04-12. Additional fields
1800 may be appended to the sqlite3_vfs object and the iVersion value
1801 may increase again in future versions of SQLite.
1802 Note that due to an oversight, the structure
1803 of the sqlite3_vfs object changed in the transition from
1804 SQLite <a href="releaselog/3_5_9.html">version 3.5.9</a> to <a href="releaselog/3_6_0.html">version 3.6.0</a> on 2008-07-16
1805 and yet the iVersion field was not increased.</p>
1806
1807 <p>The szOsFile field is the size of the subclassed <a href="#sqlite3_file">sqlite3_file</a>
1808 structure used by this VFS. mxPathname is the maximum length of
1809 a pathname in this VFS.</p>
1810
1811 <p>Registered sqlite3_vfs objects are kept on a linked list formed by
1812 the pNext pointer. The <a href="#sqlite3_vfs_find">sqlite3_vfs_register()</a>
1813 and <a href="#sqlite3_vfs_find">sqlite3_vfs_unregister()</a> interfaces manage this list
1814 in a thread-safe way. The <a href="#sqlite3_vfs_find">sqlite3_vfs_find()</a> interface
1815 searches the list. Neither the application code nor the VFS
1816 implementation should use the pNext pointer.</p>
1817
1818 <p>The pNext field is the only field in the sqlite3_vfs
1819 structure that SQLite will ever modify. SQLite will only access
1820 or modify this field while holding a particular static mutex.
1821 The application should never modify anything within the sqlite3_vfs
1822 object once the object has been registered.</p>
1823
1824 <p>The zName field holds the name of the VFS module. The name must
1825 be unique across all VFS modules.</p>
1826
1827 <p><a name="sqlite3vfsxopen"></a>
1828
1829 SQLite guarantees that the zFilename parameter to xOpen
1830 is either a NULL pointer or string obtained
1831 from xFullPathname() with an optional suffix added.
1832 If a suffix is added to the zFilename parameter, it will
1833 consist of a single "-" character followed by no more than
1834 11 alphanumeric and/or "-" characters.
1835 SQLite further guarantees that
1836 the string will be valid and unchanged until xClose() is
1837 called. Because of the previous sentence,
1838 the <a href="#sqlite3_file">sqlite3_file</a> can safely store a pointer to the
1839 filename if it needs to remember the filename for some reason.
1840 If the zFilename parameter to xOpen is a NULL pointer then xOpen
1841 must invent its own temporary name for the file. Whenever the
1842 xFilename parameter is NULL it will also be the case that the
1843 flags parameter will include <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_DELETEONCLOSE</a>.</p>
1844
1845 <p>The flags argument to xOpen() includes all bits set in
1846 the flags argument to <a href="#sqlite3_open">sqlite3_open_v2()</a>. Or if <a href="#sqlite3_open">sqlite3_open()</a>
1847 or <a href="#sqlite3_open">sqlite3_open16()</a> is used, then flags includes at least
1848 <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READWRITE</a> | <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_CREATE</a>.
1849 If xOpen() opens a file read-only then it sets *pOutFlags to
1850 include <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READONLY</a>. Other bits in *pOutFlags may be set.</p>
1851
1852 <p>SQLite will also add one of the following flags to the xOpen()
1853 call, depending on the object being opened:</p>
1854
1855 <p><ul>
1856 <li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_MAIN_DB</a>
1857 <li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_MAIN_JOURNAL</a>
1858 <li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_TEMP_DB</a>
1859 <li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_TEMP_JOURNAL</a>
1860 <li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_TRANSIENT_DB</a>
1861 <li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_SUBJOURNAL</a>
1862 <li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_SUPER_JOURNAL</a>
1863 <li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_WAL</a>
1864 </ul></p>
1865
1866 <p>The file I/O implementation can use the object type flags to
1867 change the way it deals with files. For example, an application
1868 that does not care about crash recovery or rollback might make
1869 the open of a journal file a no-op. Writes to this journal would
1870 also be no-ops, and any attempt to read the journal would return
1871 SQLITE_IOERR. Or the implementation might recognize that a database
1872 file will be doing page-aligned sector reads and writes in a random
1873 order and set up its I/O subsystem accordingly.</p>
1874
1875 <p>SQLite might also add one of the following flags to the xOpen method:</p>
1876
1877 <p><ul>
1878 <li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_DELETEONCLOSE</a>
1879 <li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_EXCLUSIVE</a>
1880 </ul></p>
1881
1882 <p>The <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_DELETEONCLOSE</a> flag means the file should be
1883 deleted when it is closed. The <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_DELETEONCLOSE</a>
1884 will be set for TEMP databases and their journals, transient
1885 databases, and subjournals.</p>
1886
1887 <p>The <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_EXCLUSIVE</a> flag is always used in conjunction
1888 with the <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_CREATE</a> flag, which are both directly
1889 analogous to the O_EXCL and O_CREAT flags of the POSIX open()
1890 API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
1891 SQLITE_OPEN_CREATE, is used to indicate that file should always
1892 be created, and that it is an error if it already exists.
1893 It is <i>not</i> used to indicate the file should be opened
1894 for exclusive access.</p>
1895
1896 <p>At least szOsFile bytes of memory are allocated by SQLite
1897 to hold the <a href="#sqlite3_file">sqlite3_file</a> structure passed as the third
1898 argument to xOpen. The xOpen method does not have to
1899 allocate the structure; it should just fill it in. Note that
1900 the xOpen method must set the sqlite3_file.pMethods to either
1901 a valid <a href="#sqlite3_io_methods">sqlite3_io_methods</a> object or to NULL. xOpen must do
1902 this even if the open fails. SQLite expects that the sqlite3_file.pMethods
1903 element will be valid after xOpen returns regardless of the success
1904 or failure of the xOpen call.</p>
1905
1906 <p><a name="sqlite3vfsxaccess"></a>
1907
1908 The flags argument to xAccess() may be <a href="#SQLITE_ACCESS_EXISTS">SQLITE_ACCESS_EXISTS</a>
1909 to test for the existence of a file, or <a href="#SQLITE_ACCESS_EXISTS">SQLITE_ACCESS_READWRITE</a> to
1910 test whether a file is readable and writable, or <a href="#SQLITE_ACCESS_EXISTS">SQLITE_ACCESS_READ</a>
1911 to test whether a file is at least readable. The SQLITE_ACCESS_READ
1912 flag is never actually used and is not implemented in the built-in
1913 VFSes of SQLite. The file is named by the second argument and can be a
1914 directory. The xAccess method returns <a href="#SQLITE_ABORT">SQLITE_OK</a> on success or some
1915 non-zero error code if there is an I/O error or if the name of
1916 the file given in the second argument is illegal. If SQLITE_OK
1917 is returned, then non-zero or zero is written into *pResOut to indicate
1918 whether or not the file is accessible.</p>
1919
1920 <p>SQLite will always allocate at least mxPathname+1 bytes for the
1921 output buffer xFullPathname. The exact size of the output buffer
1922 is also passed as a parameter to both methods. If the output buffer
1923 is not large enough, <a href="#SQLITE_ABORT">SQLITE_CANTOPEN</a> should be returned. Since this is
1924 handled as a fatal error by SQLite, vfs implementations should endeavor
1925 to prevent this by setting mxPathname to a sufficiently large value.</p>
1926
1927 <p>The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
1928 interfaces are not strictly a part of the filesystem, but they are
1929 included in the VFS structure for completeness.
1930 The xRandomness() function attempts to return nBytes bytes
1931 of good-quality randomness into zOut. The return value is
1932 the actual number of bytes of randomness obtained.
1933 The xSleep() method causes the calling thread to sleep for at
1934 least the number of microseconds given. The xCurrentTime()
1935 method returns a Julian Day Number for the current date and time as
1936 a floating point value.
1937 The xCurrentTimeInt64() method returns, as an integer, the Julian
1938 Day Number multiplied by 86400000 (the number of milliseconds in
1939 a 24-hour day).
1940 SQLite will use the xCurrentTimeInt64() method to get the current
1941 date and time if that method is available (if iVersion is 2 or
1942 greater and the function pointer is not NULL) and will fall back
1943 to xCurrentTime() if xCurrentTimeInt64() is unavailable.</p>
1944
1945 <p>The xSetSystemCall(), xGetSystemCall(), and xNextSystemCall() interfaces
1946 are not used by the SQLite core. These optional interfaces are provided
1947 by some VFSes to facilitate testing of the VFS code. By overriding
1948 system calls with functions under its control, a test program can
1949 simulate faults and error conditions that would otherwise be difficult
1950 or impossible to induce. The set of system calls that can be overridden
1951 varies from one VFS to another, and from one version of the same VFS to the
1952 next. Applications that use these interfaces must be prepared for any
1953 or all of these interfaces to be NULL or for their behavior to change
1954 from one release to the next. Applications must not attempt to access
1955 any of these methods if the iVersion of the VFS is less than 3.
1956 </p><hr><a name="sqlite3_vtab"></a>
1957 <h2>Virtual Table Instance Object</h2>
1958 </div>
1959 <blockquote><pre>
1960 struct sqlite3_vtab {
1961 const sqlite3_module *pModule; /* The module for this virtual table */
1962 int nRef; /* Number of open cursors */
1963 char *zErrMsg; /* Error message from sqlite3_mprintf() */
1964 /* Virtual table implementations will typically add additional fields */
1965 };
1966 </pre></blockquote>
1967 <p>
1968 Every <a href="#sqlite3_module">virtual table module</a> implementation uses a subclass
1969 of this object to describe a particular instance
1970 of the <a href="vtab.html">virtual table</a>. Each subclass will
1971 be tailored to the specific needs of the module implementation.
1972 The purpose of this superclass is to define certain fields that are
1973 common to all module implementations.</p>
1974
1975 <p>Virtual tables methods can set an error message by assigning a
1976 string obtained from <a href="#sqlite3_mprintf">sqlite3_mprintf()</a> to zErrMsg. The method should
1977 take care that any prior string is freed by a call to <a href="#sqlite3_free">sqlite3_free()</a>
1978 prior to assigning a new string to zErrMsg. After the error message
1979 is delivered up to the client application, the string will be automatically
1980 freed by sqlite3_free() and the zErrMsg field will be zeroed.
1981 </p><hr><a name="sqlite3_aggregate_context"></a>
1982 <h2>Obtain Aggregate Function Context</h2>
1983 </div>
1984 <blockquote><pre>
1985 void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
1986 </pre></blockquote>
1987 <p>
1988 Implementations of aggregate SQL functions use this
1989 routine to allocate memory for storing their state.</p>
1990
1991 <p>The first time the sqlite3_aggregate_context(C,N) routine is called
1992 for a particular aggregate function, SQLite allocates
1993 N bytes of memory, zeroes out that memory, and returns a pointer
1994 to the new memory. On second and subsequent calls to
1995 sqlite3_aggregate_context() for the same aggregate function instance,
1996 the same buffer is returned. Sqlite3_aggregate_context() is normally
1997 called once for each invocation of the xStep callback and then one
1998 last time when the xFinal callback is invoked. When no rows match
1999 an aggregate query, the xStep() callback of the aggregate function
2000 implementation is never called and xFinal() is called exactly once.
2001 In those cases, sqlite3_aggregate_context() might be called for the
2002 first time from within xFinal().</p>
2003
2004 <p>The sqlite3_aggregate_context(C,N) routine returns a NULL pointer
2005 when first called if N is less than or equal to zero or if a memory
2006 allocation error occurs.</p>
2007
2008 <p>The amount of space allocated by sqlite3_aggregate_context(C,N) is
2009 determined by the N parameter on the first successful call. Changing the
2010 value of N in any subsequent call to sqlite3_aggregate_context() within
2011 the same aggregate function instance will not resize the memory
2012 allocation. Within the xFinal callback, it is customary to set
2013 N=0 in calls to sqlite3_aggregate_context(C,N) so that no
2014 pointless memory allocations occur.</p>
2015
2016 <p>SQLite automatically frees the memory allocated by
2017 sqlite3_aggregate_context() when the aggregate query concludes.</p>
2018
2019 <p>The first parameter must be a copy of the
2020 <a href="#sqlite3_context">SQL function context</a> that is the first parameter
2021 to the xStep or xFinal callback routine that implements the aggregate
2022 function.</p>
2023
2024 <p>This routine must be called from the same thread in which
2025 the aggregate SQL function is running.
2026 </p><hr><a name="sqlite3_auto_extension"></a>
2027 <h2>Automatically Load Statically Linked Extensions</h2>
2028 </div>
2029 <blockquote><pre>
2030 int sqlite3_auto_extension(void(*xEntryPoint)(void));
2031 </pre></blockquote>
2032 <p>
2033 This interface causes the xEntryPoint() function to be invoked for
2034 each new <a href="#sqlite3">database connection</a> that is created. The idea here is that
2035 xEntryPoint() is the entry point for a statically linked <a href="loadext.html">SQLite extension</a>
2036 that is to be automatically loaded into all new database connections.</p>
2037
2038 <p>Even though the function prototype shows that xEntryPoint() takes
2039 no arguments and returns void, SQLite invokes xEntryPoint() with three
2040 arguments and expects an integer result as if the signature of the
2041 entry point were as follows:</p>
2042
2043 <p><blockquote><pre>
2044 &nbsp; int xEntryPoint(
2045 &nbsp; sqlite3 *db,
2046 &nbsp; char **pzErrMsg,
2047 &nbsp; const struct sqlite3_api_routines *pThunk
2048 &nbsp; );
2049 </pre></blockquote></p>
2050
2051 <p>If the xEntryPoint routine encounters an error, it should make *pzErrMsg
2052 point to an appropriate error message (obtained from <a href="#sqlite3_mprintf">sqlite3_mprintf()</a>)
2053 and return an appropriate <a href="rescode.html">error code</a>. SQLite ensures that *pzErrMsg
2054 is NULL before calling the xEntryPoint(). SQLite will invoke
2055 <a href="#sqlite3_free">sqlite3_free()</a> on *pzErrMsg after xEntryPoint() returns. If any
2056 xEntryPoint() returns an error, the <a href="#sqlite3_open">sqlite3_open()</a>, <a href="#sqlite3_open">sqlite3_open16()</a>,
2057 or <a href="#sqlite3_open">sqlite3_open_v2()</a> call that provoked the xEntryPoint() will fail.</p>
2058
2059 <p>Calling sqlite3_auto_extension(X) with an entry point X that is already
2060 on the list of automatic extensions is a harmless no-op. No entry point
2061 will be called more than once for each database connection that is opened.</p>
2062
2063 <p>See also: <a href="#sqlite3_reset_auto_extension">sqlite3_reset_auto_extension()</a>
2064 and <a href="#sqlite3_cancel_auto_extension">sqlite3_cancel_auto_extension()</a>
2065 </p><hr><a name="sqlite3_autovacuum_pages"></a>
2066 <h2>Autovacuum Compaction Amount Callback</h2>
2067 </div>
2068 <blockquote><pre>
2069 int sqlite3_autovacuum_pages(
2070 sqlite3 *db,
2071 unsigned int(*)(void*,const char*,unsigned int,unsigned int,unsigned int),
2072 void*,
2073 void(*)(void*)
2074 );
2075 </pre></blockquote>
2076 <p>
2077 The sqlite3_autovacuum_pages(D,C,P,X) interface registers a callback
2078 function C that is invoked prior to each autovacuum of the database
2079 file. The callback is passed a copy of the generic data pointer (P),
2080 the schema-name of the attached database that is being autovacuumed,
2081 the size of the database file in pages, the number of free pages,
2082 and the number of bytes per page, respectively. The callback should
2083 return the number of free pages that should be removed by the
2084 autovacuum. If the callback returns zero, then no autovacuum happens.
2085 If the value returned is greater than or equal to the number of
2086 free pages, then a complete autovacuum happens.</p>
2087
2088 <p><p>If there are multiple ATTACH-ed database files that are being
2089 modified as part of a transaction commit, then the autovacuum pages
2090 callback is invoked separately for each file.</p>
2091
2092 <p><p><b>The callback is not reentrant.</b> The callback function should
2093 not attempt to invoke any other SQLite interface. If it does, bad
2094 things may happen, including segmentation faults and corrupt database
2095 files. The callback function should be a simple function that
2096 does some arithmetic on its input parameters and returns a result.</p>
2097
2098 <p>The X parameter to sqlite3_autovacuum_pages(D,C,P,X) is an optional
2099 destructor for the P parameter. If X is not NULL, then X(P) is
2100 invoked whenever the database connection closes or when the callback
2101 is overwritten by another invocation of sqlite3_autovacuum_pages().</p>
2102
2103 <p><p>There is only one autovacuum pages callback per database connection.
2104 Each call to the sqlite3_autovacuum_pages() interface overrides all
2105 previous invocations for that database connection. If the callback
2106 argument (C) to sqlite3_autovacuum_pages(D,C,P,X) is a NULL pointer,
2107 then the autovacuum steps callback is canceled. The return value
2108 from sqlite3_autovacuum_pages() is normally SQLITE_OK, but might
2109 be some other error code if something goes wrong. The current
2110 implementation will only return SQLITE_OK or SQLITE_MISUSE, but other
2111 return codes might be added in future releases.</p>
2112
2113 <p><p>If no autovacuum pages callback is specified (the usual case) or
2114 a NULL pointer is provided for the callback,
2115 then the default behavior is to vacuum all free pages. So, in other
2116 words, the default behavior is the same as if the callback function
2117 were something like this:</p>
2118
2119 <p><blockquote><pre>
2120 &nbsp; unsigned int demonstration_autovac_pages_callback(
2121 &nbsp; void *pClientData,
2122 &nbsp; const char *zSchema,
2123 &nbsp; unsigned int nDbPage,
2124 &nbsp; unsigned int nFreePage,
2125 &nbsp; unsigned int nBytePerPage
2126 &nbsp; ){
2127 &nbsp; return nFreePage;
2128 &nbsp; }
2129 </pre></blockquote>
2130 </p><hr><a name="sqlite3_bind_parameter_count"></a>
2131 <h2>Number Of SQL Parameters</h2>
2132 </div>
2133 <blockquote><pre>
2134 int sqlite3_bind_parameter_count(sqlite3_stmt*);
2135 </pre></blockquote>
2136 <p>
2137 This routine can be used to find the number of <a href="#sqlite3_bind_blob">SQL parameters</a>
2138 in a <a href="#sqlite3_stmt">prepared statement</a>. SQL parameters are tokens of the
2139 form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
2140 placeholders for values that are <a href="#sqlite3_bind_blob">bound</a>
2141 to the parameters at a later time.</p>
2142
2143 <p>This routine actually returns the index of the largest (rightmost)
2144 parameter. For all forms except ?NNN, this will correspond to the
2145 number of unique parameters. If parameters of the ?NNN form are used,
2146 there may be gaps in the list.</p>
2147
2148 <p>See also: <a href="#sqlite3_bind_blob">sqlite3_bind()</a>,
2149 <a href="#sqlite3_bind_parameter_name">sqlite3_bind_parameter_name()</a>, and
2150 <a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a>.
2151 </p><hr><a name="sqlite3_bind_parameter_index"></a>
2152 <h2>Index Of A Parameter With A Given Name</h2>
2153 </div>
2154 <blockquote><pre>
2155 int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
2156 </pre></blockquote>
2157 <p>
2158 Return the index of an SQL parameter given its name. The
2159 index value returned is suitable for use as the second
2160 parameter to <a href="#sqlite3_bind_blob">sqlite3_bind()</a>. A zero
2161 is returned if no matching parameter is found. The parameter
2162 name must be given in UTF-8 even if the original statement
2163 was prepared from UTF-16 text using <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a> or
2164 <a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a>.</p>
2165
2166 <p>See also: <a href="#sqlite3_bind_blob">sqlite3_bind()</a>,
2167 <a href="#sqlite3_bind_parameter_count">sqlite3_bind_parameter_count()</a>, and
2168 <a href="#sqlite3_bind_parameter_name">sqlite3_bind_parameter_name()</a>.
2169 </p><hr><a name="sqlite3_bind_parameter_name"></a>
2170 <h2>Name Of A Host Parameter</h2>
2171 </div>
2172 <blockquote><pre>
2173 const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
2174 </pre></blockquote>
2175 <p>
2176 The sqlite3_bind_parameter_name(P,N) interface returns
2177 the name of the N-th <a href="#sqlite3_bind_blob">SQL parameter</a> in the <a href="#sqlite3_stmt">prepared statement</a> P.
2178 SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
2179 have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
2180 respectively.
2181 In other words, the initial ":" or "$" or "@" or "?"
2182 is included as part of the name.
2183 Parameters of the form "?" without a following integer have no name
2184 and are referred to as "nameless" or "anonymous parameters".</p>
2185
2186 <p>The first host parameter has an index of 1, not 0.</p>
2187
2188 <p>If the value N is out of range or if the N-th parameter is
2189 nameless, then NULL is returned. The returned string is
2190 always in UTF-8 encoding even if the named parameter was
2191 originally specified as UTF-16 in <a href="#sqlite3_prepare">sqlite3_prepare16()</a>,
2192 <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a>, or <a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a>.</p>
2193
2194 <p>See also: <a href="#sqlite3_bind_blob">sqlite3_bind()</a>,
2195 <a href="#sqlite3_bind_parameter_count">sqlite3_bind_parameter_count()</a>, and
2196 <a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a>.
2197 </p><hr><a name="sqlite3_blob_bytes"></a>
2198 <h2>Return The Size Of An Open BLOB</h2>
2199 </div>
2200 <blockquote><pre>
2201 int sqlite3_blob_bytes(sqlite3_blob *);
2202 </pre></blockquote>
2203 <p>
2204 Returns the size in bytes of the BLOB accessible via the
2205 successfully opened <a href="#sqlite3_blob">BLOB handle</a> in its only argument. The
2206 incremental blob I/O routines can only read or overwrite existing
2207 blob content; they cannot change the size of a blob.</p>
2208
2209 <p>This routine only works on a <a href="#sqlite3_blob">BLOB handle</a> which has been created
2210 by a prior successful call to <a href="#sqlite3_blob_open">sqlite3_blob_open()</a> and which has not
2211 been closed by <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>. Passing any other pointer in
2212 to this routine results in undefined and probably undesirable behavior.
2213 </p><hr><a name="sqlite3_blob_close"></a>
2214 <h2>Close A BLOB Handle</h2>
2215 </div>
2216 <blockquote><pre>
2217 int sqlite3_blob_close(sqlite3_blob *);
2218 </pre></blockquote>
2219 <p>
2220 This function closes an open <a href="#sqlite3_blob">BLOB handle</a>. The BLOB handle is closed
2221 unconditionally. Even if this routine returns an error code, the
2222 handle is still closed.</p>
2223
2224 <p>If the blob handle being closed was opened for read-write access, and if
2225 the database is in auto-commit mode and there are no other open read-write
2226 blob handles or active write statements, the current transaction is
2227 committed. If an error occurs while committing the transaction, an error
2228 code is returned and the transaction rolled back.</p>
2229
2230 <p>Calling this function with an argument that is not a NULL pointer or an
2231 open blob handle results in undefined behavior. Calling this routine
2232 with a null pointer (such as would be returned by a failed call to
2233 <a href="#sqlite3_blob_open">sqlite3_blob_open()</a>) is a harmless no-op. Otherwise, if this function
2234 is passed a valid open blob handle, the values returned by the
2235 sqlite3_errcode() and sqlite3_errmsg() functions are set before returning.
2236 </p><hr><a name="sqlite3_blob_open"></a>
2237 <h2>Open A BLOB For Incremental I/O</h2>
2238 </div>
2239 <blockquote><pre>
2240 int sqlite3_blob_open(
2241 sqlite3*,
2242 const char *zDb,
2243 const char *zTable,
2244 const char *zColumn,
2245 sqlite3_int64 iRow,
2246 int flags,
2247 sqlite3_blob **ppBlob
2248 );
2249 </pre></blockquote>
2250 <p>
2251 This interfaces opens a <a href="#sqlite3_blob">handle</a> to the BLOB located
2252 in row iRow, column zColumn, table zTable in database zDb;
2253 in other words, the same BLOB that would be selected by:</p>
2254
2255 <p><pre>
2256 SELECT zColumn FROM zDb.zTable WHERE <a href="lang_createtable.html#rowid">rowid</a> = iRow;
2257 </pre></p>
2258
2259 <p>Parameter zDb is not the filename that contains the database, but
2260 rather the symbolic name of the database. For attached databases, this is
2261 the name that appears after the AS keyword in the <a href="lang_attach.html">ATTACH</a> statement.
2262 For the main database file, the database name is "main". For TEMP
2263 tables, the database name is "temp".</p>
2264
2265 <p>If the flags parameter is non-zero, then the BLOB is opened for read
2266 and write access. If the flags parameter is zero, the BLOB is opened for
2267 read-only access.</p>
2268
2269 <p>On success, <a href="#SQLITE_ABORT">SQLITE_OK</a> is returned and the new <a href="#sqlite3_blob">BLOB handle</a> is stored
2270 in *ppBlob. Otherwise an <a href="rescode.html">error code</a> is returned and, unless the error
2271 code is SQLITE_MISUSE, *ppBlob is set to NULL. This means that, provided
2272 the API is not misused, it is always safe to call <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>
2273 on *ppBlob after this function returns.</p>
2274
2275 <p>This function fails with SQLITE_ERROR if any of the following are true:
2276 <ul>
2277 <li> Database zDb does not exist,
2278 <li> Table zTable does not exist within database zDb,
2279 <li> Table zTable is a WITHOUT ROWID table,
2280 <li> Column zColumn does not exist,
2281 <li> Row iRow is not present in the table,
2282 <li> The specified column of row iRow contains a value that is not
2283 a TEXT or BLOB value,
2284 <li> Column zColumn is part of an index, PRIMARY KEY or UNIQUE
2285 constraint and the blob is being opened for read/write access,
2286 <li> <a href="foreignkeys.html">Foreign key constraints</a> are enabled,
2287 column zColumn is part of a <a href="foreignkeys.html#parentchild">child key</a> definition and the blob is
2288 being opened for read/write access.
2289 </ul></p>
2290
2291 <p>Unless it returns SQLITE_MISUSE, this function sets the
2292 <a href="#sqlite3">database connection</a> error code and message accessible via
2293 <a href="#sqlite3_errcode">sqlite3_errcode()</a> and <a href="#sqlite3_errcode">sqlite3_errmsg()</a> and related functions.</p>
2294
2295 <p>A BLOB referenced by sqlite3_blob_open() may be read using the
2296 <a href="#sqlite3_blob_read">sqlite3_blob_read()</a> interface and modified by using
2297 <a href="#sqlite3_blob_write">sqlite3_blob_write()</a>. The <a href="#sqlite3_blob">BLOB handle</a> can be moved to a
2298 different row of the same table using the <a href="#sqlite3_blob_reopen">sqlite3_blob_reopen()</a>
2299 interface. However, the column, table, or database of a <a href="#sqlite3_blob">BLOB handle</a>
2300 cannot be changed after the <a href="#sqlite3_blob">BLOB handle</a> is opened.</p>
2301
2302 <p>If the row that a BLOB handle points to is modified by an
2303 <a href="lang_update.html">UPDATE</a>, <a href="lang_delete.html">DELETE</a>, or by <a href="lang_conflict.html">ON CONFLICT</a> side-effects
2304 then the BLOB handle is marked as "expired".
2305 This is true if any column of the row is changed, even a column
2306 other than the one the BLOB handle is open on.
2307 Calls to <a href="#sqlite3_blob_read">sqlite3_blob_read()</a> and <a href="#sqlite3_blob_write">sqlite3_blob_write()</a> for
2308 an expired BLOB handle fail with a return code of <a href="#SQLITE_ABORT">SQLITE_ABORT</a>.
2309 Changes written into a BLOB prior to the BLOB expiring are not
2310 rolled back by the expiration of the BLOB. Such changes will eventually
2311 commit if the transaction continues to completion.</p>
2312
2313 <p>Use the <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> interface to determine the size of
2314 the opened blob. The size of a blob may not be changed by this
2315 interface. Use the <a href="lang_update.html">UPDATE</a> SQL command to change the size of a
2316 blob.</p>
2317
2318 <p>The <a href="#sqlite3_bind_blob">sqlite3_bind_zeroblob()</a> and <a href="#sqlite3_result_blob">sqlite3_result_zeroblob()</a> interfaces
2319 and the built-in <a href="lang_corefunc.html#zeroblob">zeroblob</a> SQL function may be used to create a
2320 zero-filled blob to read or write using the incremental-blob interface.</p>
2321
2322 <p>To avoid a resource leak, every open <a href="#sqlite3_blob">BLOB handle</a> should eventually
2323 be released by a call to <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>.</p>
2324
2325 <p>See also: <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>,
2326 <a href="#sqlite3_blob_reopen">sqlite3_blob_reopen()</a>, <a href="#sqlite3_blob_read">sqlite3_blob_read()</a>,
2327 <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a>, <a href="#sqlite3_blob_write">sqlite3_blob_write()</a>.
2328 </p><hr><a name="sqlite3_blob_read"></a>
2329 <h2>Read Data From A BLOB Incrementally</h2>
2330 </div>
2331 <blockquote><pre>
2332 int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
2333 </pre></blockquote>
2334 <p>
2335 This function is used to read data from an open <a href="#sqlite3_blob">BLOB handle</a> into a
2336 caller-supplied buffer. N bytes of data are copied into buffer Z
2337 from the open BLOB, starting at offset iOffset.</p>
2338
2339 <p>If offset iOffset is less than N bytes from the end of the BLOB,
2340 <a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is read. If N or iOffset is
2341 less than zero, <a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is read.
2342 The size of the blob (and hence the maximum value of N+iOffset)
2343 can be determined using the <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> interface.</p>
2344
2345 <p>An attempt to read from an expired <a href="#sqlite3_blob">BLOB handle</a> fails with an
2346 error code of <a href="#SQLITE_ABORT">SQLITE_ABORT</a>.</p>
2347
2348 <p>On success, sqlite3_blob_read() returns SQLITE_OK.
2349 Otherwise, an <a href="rescode.html">error code</a> or an <a href="rescode.html#extrc">extended error code</a> is returned.</p>
2350
2351 <p>This routine only works on a <a href="#sqlite3_blob">BLOB handle</a> which has been created
2352 by a prior successful call to <a href="#sqlite3_blob_open">sqlite3_blob_open()</a> and which has not
2353 been closed by <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>. Passing any other pointer in
2354 to this routine results in undefined and probably undesirable behavior.</p>
2355
2356 <p>See also: <a href="#sqlite3_blob_write">sqlite3_blob_write()</a>.
2357 </p><hr><a name="sqlite3_blob_reopen"></a>
2358 <h2>Move a BLOB Handle to a New Row</h2>
2359 </div>
2360 <blockquote><pre>
2361 int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
2362 </pre></blockquote>
2363 <p>
2364 This function is used to move an existing <a href="#sqlite3_blob">BLOB handle</a> so that it points
2365 to a different row of the same database table. The new row is identified
2366 by the rowid value passed as the second argument. Only the row can be
2367 changed. The database, table and column on which the blob handle is open
2368 remain the same. Moving an existing <a href="#sqlite3_blob">BLOB handle</a> to a new row is
2369 faster than closing the existing handle and opening a new one.</p>
2370
2371 <p>The new row must meet the same criteria as for <a href="#sqlite3_blob_open">sqlite3_blob_open()</a> -
2372 it must exist and there must be either a blob or text value stored in
2373 the nominated column. If the new row is not present in the table, or if
2374 it does not contain a blob or text value, or if another error occurs, an
2375 SQLite error code is returned and the blob handle is considered aborted.
2376 All subsequent calls to <a href="#sqlite3_blob_read">sqlite3_blob_read()</a>, <a href="#sqlite3_blob_write">sqlite3_blob_write()</a> or
2377 <a href="#sqlite3_blob_reopen">sqlite3_blob_reopen()</a> on an aborted blob handle immediately return
2378 SQLITE_ABORT. Calling <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> on an aborted blob handle
2379 always returns zero.</p>
2380
2381 <p>This function sets the database handle error code and message.
2382 </p><hr><a name="sqlite3_blob_write"></a>
2383 <h2>Write Data Into A BLOB Incrementally</h2>
2384 </div>
2385 <blockquote><pre>
2386 int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
2387 </pre></blockquote>
2388 <p>
2389 This function is used to write data into an open <a href="#sqlite3_blob">BLOB handle</a> from a
2390 caller-supplied buffer. N bytes of data are copied from the buffer Z
2391 into the open BLOB, starting at offset iOffset.</p>
2392
2393 <p>On success, sqlite3_blob_write() returns SQLITE_OK.
2394 Otherwise, an <a href="rescode.html">error code</a> or an <a href="rescode.html#extrc">extended error code</a> is returned.
2395 Unless SQLITE_MISUSE is returned, this function sets the
2396 <a href="#sqlite3">database connection</a> error code and message accessible via
2397 <a href="#sqlite3_errcode">sqlite3_errcode()</a> and <a href="#sqlite3_errcode">sqlite3_errmsg()</a> and related functions.</p>
2398
2399 <p>If the <a href="#sqlite3_blob">BLOB handle</a> passed as the first argument was not opened for
2400 writing (the flags parameter to <a href="#sqlite3_blob_open">sqlite3_blob_open()</a> was zero),
2401 this function returns <a href="#SQLITE_ABORT">SQLITE_READONLY</a>.</p>
2402
2403 <p>This function may only modify the contents of the BLOB; it is
2404 not possible to increase the size of a BLOB using this API.
2405 If offset iOffset is less than N bytes from the end of the BLOB,
2406 <a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is written. The size of the
2407 BLOB (and hence the maximum value of N+iOffset) can be determined
2408 using the <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> interface. If N or iOffset are less
2409 than zero <a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is written.</p>
2410
2411 <p>An attempt to write to an expired <a href="#sqlite3_blob">BLOB handle</a> fails with an
2412 error code of <a href="#SQLITE_ABORT">SQLITE_ABORT</a>. Writes to the BLOB that occurred
2413 before the <a href="#sqlite3_blob">BLOB handle</a> expired are not rolled back by the
2414 expiration of the handle, though of course those changes might
2415 have been overwritten by the statement that expired the BLOB handle
2416 or by other independent statements.</p>
2417
2418 <p>This routine only works on a <a href="#sqlite3_blob">BLOB handle</a> which has been created
2419 by a prior successful call to <a href="#sqlite3_blob_open">sqlite3_blob_open()</a> and which has not
2420 been closed by <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>. Passing any other pointer in
2421 to this routine results in undefined and probably undesirable behavior.</p>
2422
2423 <p>See also: <a href="#sqlite3_blob_read">sqlite3_blob_read()</a>.
2424 </p><hr><a name="sqlite3_busy_timeout"></a>
2425 <h2>Set A Busy Timeout</h2>
2426 </div>
2427 <blockquote><pre>
2428 int sqlite3_busy_timeout(sqlite3*, int ms);
2429 </pre></blockquote>
2430 <p>
2431 This routine sets a <a href="#sqlite3_busy_handler">busy handler</a> that sleeps
2432 for a specified amount of time when a table is locked. The handler
2433 will sleep multiple times until at least "ms" milliseconds of sleeping
2434 have accumulated. After at least "ms" milliseconds of sleeping,
2435 the handler returns 0 which causes <a href="#sqlite3_step">sqlite3_step()</a> to return
2436 <a href="#SQLITE_ABORT">SQLITE_BUSY</a>.</p>
2437
2438 <p>Calling this routine with an argument less than or equal to zero
2439 turns off all busy handlers.</p>
2440
2441 <p>There can only be a single busy handler for a particular
2442 <a href="#sqlite3">database connection</a> at any given moment. If another busy handler
2443 was defined (using <a href="#sqlite3_busy_handler">sqlite3_busy_handler()</a>) prior to calling
2444 this routine, that other busy handler is cleared.</p>
2445
2446 <p>See also: <a href="pragma.html#pragma_busy_timeout">PRAGMA busy_timeout</a>
2447 </p><hr><a name="sqlite3_cancel_auto_extension"></a>
2448 <h2>Cancel Automatic Extension Loading</h2>
2449 </div>
2450 <blockquote><pre>
2451 int sqlite3_cancel_auto_extension(void(*xEntryPoint)(void));
2452 </pre></blockquote>
2453 <p>
2454 The <a href="#sqlite3_cancel_auto_extension">sqlite3_cancel_auto_extension(X)</a> interface unregisters the
2455 initialization routine X that was registered using a prior call to
2456 <a href="#sqlite3_auto_extension">sqlite3_auto_extension(X)</a>. The <a href="#sqlite3_cancel_auto_extension">sqlite3_cancel_auto_extension(X)</a>
2457 routine returns 1 if initialization routine X was successfully
2458 unregistered and it returns 0 if X was not on the list of initialization
2459 routines.
2460 </p><hr><a name="sqlite3_clear_bindings"></a>
2461 <h2>Reset All Bindings On A Prepared Statement</h2>
2462 </div>
2463 <blockquote><pre>
2464 int sqlite3_clear_bindings(sqlite3_stmt*);
2465 </pre></blockquote>
2466 <p>
2467 Contrary to the intuition of many, <a href="#sqlite3_reset">sqlite3_reset()</a> does not reset
2468 the <a href="#sqlite3_bind_blob">bindings</a> on a <a href="#sqlite3_stmt">prepared statement</a>.
2469 Use this routine to reset all host parameters to NULL.
2470 </p><hr><a name="sqlite3_column_count"></a>
2471 <h2>Number Of Columns In A Result Set</h2>
2472 </div>
2473 <blockquote><pre>
2474 int sqlite3_column_count(sqlite3_stmt *pStmt);
2475 </pre></blockquote>
2476 <p>
2477 Return the number of columns in the result set returned by the
2478 <a href="#sqlite3_stmt">prepared statement</a>. If this routine returns 0, that means the
2479 <a href="#sqlite3_stmt">prepared statement</a> returns no data (for example an <a href="lang_update.html">UPDATE</a>).
2480 However, just because this routine returns a positive number does not
2481 mean that one or more rows of data will be returned. A SELECT statement
2482 will always have a positive sqlite3_column_count() but depending on the
2483 WHERE clause constraints and the table content, it might return no rows.</p>
2484
2485 <p>See also: <a href="#sqlite3_data_count">sqlite3_data_count()</a>
2486 </p><hr><a name="sqlite3_config"></a>
2487 <h2>Configuring The SQLite Library</h2>
2488 </div>
2489 <blockquote><pre>
2490 int sqlite3_config(int, ...);
2491 </pre></blockquote>
2492 <p>
2493 The sqlite3_config() interface is used to make global configuration
2494 changes to SQLite in order to tune SQLite to the specific needs of
2495 the application. The default configuration is recommended for most
2496 applications and so this routine is usually not necessary. It is
2497 provided to support rare applications with unusual needs.</p>
2498
2499 <p><b>The sqlite3_config() interface is not threadsafe. The application
2500 must ensure that no other SQLite interfaces are invoked by other
2501 threads while sqlite3_config() is running.</b></p>
2502
2503 <p>The first argument to sqlite3_config() is an integer
2504 <a href="#SQLITE_CONFIG_COVERING_INDEX_SCAN">configuration option</a> that determines
2505 what property of SQLite is to be configured. Subsequent arguments
2506 vary depending on the <a href="#SQLITE_CONFIG_COVERING_INDEX_SCAN">configuration option</a>
2507 in the first argument.</p>
2508
2509 <p>For most configuration options, the sqlite3_config() interface
2510 may only be invoked prior to library initialization using
2511 <a href="#sqlite3_initialize">sqlite3_initialize()</a> or after shutdown by <a href="#sqlite3_initialize">sqlite3_shutdown()</a>.
2512 The exceptional configuration options that may be invoked at any time
2513 are called "anytime configuration options".
2514 If sqlite3_config() is called after <a href="#sqlite3_initialize">sqlite3_initialize()</a> and before
2515 <a href="#sqlite3_initialize">sqlite3_shutdown()</a> with a first argument that is not an anytime
2516 configuration option, then the sqlite3_config() call will
2517 return SQLITE_MISUSE.
2518 Note, however, that sqlite3_config() can be called as part of the
2519 implementation of an application-defined <a href="#sqlite3_initialize">sqlite3_os_init()</a>.</p>
2520
2521 <p>When a configuration option is set, sqlite3_config() returns <a href="#SQLITE_ABORT">SQLITE_OK</a>.
2522 If the option is unknown or SQLite is unable to set the option
2523 then this routine returns a non-zero <a href="rescode.html">error code</a>.
2524 </p><hr><a name="sqlite3_context_db_handle"></a>
2525 <h2>Database Connection For Functions</h2>
2526 </div>
2527 <blockquote><pre>
2528 sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
2529 </pre></blockquote>
2530 <p>
2531 The sqlite3_context_db_handle() interface returns a copy of
2532 the pointer to the <a href="#sqlite3">database connection</a> (the 1st parameter)
2533 of the <a href="#sqlite3_create_function">sqlite3_create_function()</a>
2534 and <a href="#sqlite3_create_function">sqlite3_create_function16()</a> routines that originally
2535 registered the application defined function.
2536 </p><hr><a name="sqlite3_data_count"></a>
2537 <h2>Number of columns in a result set</h2>
2538 </div>
2539 <blockquote><pre>
2540 int sqlite3_data_count(sqlite3_stmt *pStmt);
2541 </pre></blockquote>
2542 <p>
2543 The sqlite3_data_count(P) interface returns the number of columns in the
2544 current row of the result set of <a href="#sqlite3_stmt">prepared statement</a> P.
2545 If prepared statement P does not have results ready to return
2546 (via calls to the <a href="#sqlite3_column_blob">sqlite3_column()</a> family of
2547 interfaces) then sqlite3_data_count(P) returns 0.
2548 The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
2549 The sqlite3_data_count(P) routine returns 0 if the previous call to
2550 <a href="#sqlite3_step">sqlite3_step</a>(P) returned <a href="#SQLITE_ABORT">SQLITE_DONE</a>. The sqlite3_data_count(P)
2551 will return non-zero if previous call to <a href="#sqlite3_step">sqlite3_step</a>(P) returned
2552 <a href="#SQLITE_ABORT">SQLITE_ROW</a>, except in the case of the <a href="pragma.html#pragma_incremental_vacuum">PRAGMA incremental_vacuum</a>
2553 where it always returns zero since each step of that multi-step
2554 pragma returns 0 columns of data.</p>
2555
2556 <p>See also: <a href="#sqlite3_column_count">sqlite3_column_count()</a>
2557 </p><hr><a name="sqlite3_database_file_object"></a>
2558 <h2>Database File Corresponding To A Journal</h2>
2559 </div>
2560 <blockquote><pre>
2561 sqlite3_file *sqlite3_database_file_object(const char*);
2562 </pre></blockquote>
2563 <p>
2564 If X is the name of a rollback or WAL-mode journal file that is
2565 passed into the xOpen method of <a href="#sqlite3_vfs">sqlite3_vfs</a>, then
2566 sqlite3_database_file_object(X) returns a pointer to the <a href="#sqlite3_file">sqlite3_file</a>
2567 object that represents the main database file.</p>
2568
2569 <p>This routine is intended for use in custom <a href="vfs.html">VFS</a> implementations
2570 only. It is not a general-purpose interface.
2571 The argument sqlite3_file_object(X) must be a filename pointer that
2572 has been passed into <a href="#sqlite3_vfs">sqlite3_vfs</a>.xOpen method where the
2573 flags parameter to xOpen contains one of the bits
2574 <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_MAIN_JOURNAL</a> or <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_WAL</a>. Any other use
2575 of this routine results in undefined and probably undesirable
2576 behavior.
2577 </p><hr><a name="sqlite3_db_cacheflush"></a>
2578 <h2>Flush caches to disk mid-transaction</h2>
2579 </div>
2580 <blockquote><pre>
2581 int sqlite3_db_cacheflush(sqlite3*);
2582 </pre></blockquote>
2583 <p>
2584 If a write-transaction is open on <a href="#sqlite3">database connection</a> D when the
2585 <a href="#sqlite3_db_cacheflush">sqlite3_db_cacheflush(D)</a> interface is invoked, any dirty
2586 pages in the pager-cache that are not currently in use are written out
2587 to disk. A dirty page may be in use if a database cursor created by an
2588 active SQL statement is reading from it, or if it is page 1 of a database
2589 file (page 1 is always "in use"). The <a href="#sqlite3_db_cacheflush">sqlite3_db_cacheflush(D)</a>
2590 interface flushes caches for all schemas - "main", "temp", and
2591 any <a href="lang_attach.html">attached</a> databases.</p>
2592
2593 <p>If this function needs to obtain extra database locks before dirty pages
2594 can be flushed to disk, it does so. If those locks cannot be obtained
2595 immediately and there is a busy-handler callback configured, it is invoked
2596 in the usual manner. If the required lock still cannot be obtained, then
2597 the database is skipped and an attempt made to flush any dirty pages
2598 belonging to the next (if any) database. If any databases are skipped
2599 because locks cannot be obtained, but no other error occurs, this
2600 function returns SQLITE_BUSY.</p>
2601
2602 <p>If any other error occurs while flushing dirty pages to disk (for
2603 example an IO error or out-of-memory condition), then processing is
2604 abandoned and an SQLite <a href="rescode.html">error code</a> is returned to the caller immediately.</p>
2605
2606 <p>Otherwise, if no error occurs, <a href="#sqlite3_db_cacheflush">sqlite3_db_cacheflush()</a> returns SQLITE_OK.</p>
2607
2608 <p>This function does not set the database handle error code or message
2609 returned by the <a href="#sqlite3_errcode">sqlite3_errcode()</a> and <a href="#sqlite3_errcode">sqlite3_errmsg()</a> functions.
2610 </p><hr><a name="sqlite3_db_config"></a>
2611 <h2>Configure database connections</h2>
2612 </div>
2613 <blockquote><pre>
2614 int sqlite3_db_config(sqlite3*, int op, ...);
2615 </pre></blockquote>
2616 <p>
2617 The sqlite3_db_config() interface is used to make configuration
2618 changes to a <a href="#sqlite3">database connection</a>. The interface is similar to
2619 <a href="#sqlite3_config">sqlite3_config()</a> except that the changes apply to a single
2620 <a href="#sqlite3">database connection</a> (specified in the first argument).</p>
2621
2622 <p>The second argument to sqlite3_db_config(D,V,...) is the
2623 <a href="#sqlitedbconfiglookaside">configuration verb</a> - an integer code
2624 that indicates what aspect of the <a href="#sqlite3">database connection</a> is being configured.
2625 Subsequent arguments vary depending on the configuration verb.</p>
2626
2627 <p>Calls to sqlite3_db_config() return SQLITE_OK if and only if
2628 the call is considered successful.
2629 </p><hr><a name="sqlite3_db_filename"></a>
2630 <h2>Return The Filename For A Database Connection</h2>
2631 </div>
2632 <blockquote><pre>
2633 sqlite3_filename sqlite3_db_filename(sqlite3 *db, const char *zDbName);
2634 </pre></blockquote>
2635 <p>
2636 The sqlite3_db_filename(D,N) interface returns a pointer to the filename
2637 associated with database N of connection D.
2638 If there is no attached database N on the database
2639 connection D, or if database N is a temporary or in-memory database, then
2640 this function will return either a NULL pointer or an empty string.</p>
2641
2642 <p>The string value returned by this routine is owned and managed by
2643 the database connection. The value will be valid until the database N
2644 is <a href="lang_detach.html">DETACH</a>-ed or until the database connection closes.</p>
2645
2646 <p>The filename returned by this function is the output of the
2647 xFullPathname method of the <a href="vfs.html">VFS</a>. In other words, the filename
2648 will be an absolute pathname, even if the filename used
2649 to open the database originally was a URI or relative pathname.</p>
2650
2651 <p>If the filename pointer returned by this routine is not NULL, then it
2652 can be used as the filename input parameter to these routines:
2653 <ul>
2654 <li> <a href="#sqlite3_uri_boolean">sqlite3_uri_parameter()</a>
2655 <li> <a href="#sqlite3_uri_boolean">sqlite3_uri_boolean()</a>
2656 <li> <a href="#sqlite3_uri_boolean">sqlite3_uri_int64()</a>
2657 <li> <a href="#sqlite3_filename_database">sqlite3_filename_database()</a>
2658 <li> <a href="#sqlite3_filename_database">sqlite3_filename_journal()</a>
2659 <li> <a href="#sqlite3_filename_database">sqlite3_filename_wal()</a>
2660 </ul>
2661 </p><hr><a name="sqlite3_db_handle"></a>
2662 <h2>Find The Database Handle Of A Prepared Statement</h2>
2663 </div>
2664 <blockquote><pre>
2665 sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
2666 </pre></blockquote>
2667 <p>
2668 The sqlite3_db_handle interface returns the <a href="#sqlite3">database connection</a> handle
2669 to which a <a href="#sqlite3_stmt">prepared statement</a> belongs. The <a href="#sqlite3">database connection</a>
2670 returned by sqlite3_db_handle is the same <a href="#sqlite3">database connection</a>
2671 that was the first argument
2672 to the <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> call (or its variants) that was used to
2673 create the statement in the first place.
2674 </p><hr><a name="sqlite3_db_mutex"></a>
2675 <h2>Retrieve the mutex for a database connection</h2>
2676 </div>
2677 <blockquote><pre>
2678 sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
2679 </pre></blockquote>
2680 <p>
2681 This interface returns a pointer to the <a href="#sqlite3_mutex">sqlite3_mutex</a> object that
2682 serializes access to the <a href="#sqlite3">database connection</a> given in the argument
2683 when the <a href="threadsafe.html">threading mode</a> is Serialized.
2684 If the <a href="threadsafe.html">threading mode</a> is Single-thread or Multi-thread then this
2685 routine returns a NULL pointer.
2686 </p><hr><a name="sqlite3_db_name"></a>
2687 <h2>Return The Schema Name For A Database Connection</h2>
2688 </div>
2689 <blockquote><pre>
2690 const char *sqlite3_db_name(sqlite3 *db, int N);
2691 </pre></blockquote>
2692 <p>
2693 The sqlite3_db_name(D,N) interface returns a pointer to the schema name
2694 for the N-th database on database connection D, or a NULL pointer if N is
2695 out of range. An N value of 0 means the main database file. An N of 1 is
2696 the "temp" schema. Larger values of N correspond to various ATTACH-ed
2697 databases.</p>
2698
2699 <p>Space to hold the string that is returned by sqlite3_db_name() is managed
2700 by SQLite itself. The string might be deallocated by any operation that
2701 changes the schema, including <a href="lang_attach.html">ATTACH</a> or <a href="lang_detach.html">DETACH</a> or calls to
2702 <a href="#sqlite3_serialize">sqlite3_serialize()</a> or <a href="#sqlite3_deserialize">sqlite3_deserialize()</a>, even operations that
2703 occur on a different thread. Applications that need to
2704 remember the string long-term should make their own copy. Applications that
2705 are accessing the same database connection simultaneously on multiple
2706 threads should mutex-protect calls to this API and should make their own
2707 private copy of the result prior to releasing the mutex.
2708 </p><hr><a name="sqlite3_db_readonly"></a>
2709 <h2>Determine if a database is read-only</h2>
2710 </div>
2711 <blockquote><pre>
2712 int sqlite3_db_readonly(sqlite3 *db, const char *zDbName);
2713 </pre></blockquote>
2714 <p>
2715 The sqlite3_db_readonly(D,N) interface returns 1 if the database N
2716 of connection D is read-only, 0 if it is read/write, or -1 if N is not
2717 the name of a database on connection D.
2718 </p><hr><a name="sqlite3_db_release_memory"></a>
2719 <h2>Free Memory Used By A Database Connection</h2>
2720 </div>
2721 <blockquote><pre>
2722 int sqlite3_db_release_memory(sqlite3*);
2723 </pre></blockquote>
2724 <p>
2725 The sqlite3_db_release_memory(D) interface attempts to free as much heap
2726 memory as possible from database connection D. Unlike the
2727 <a href="#sqlite3_release_memory">sqlite3_release_memory()</a> interface, this interface is in effect even
2728 when the <a href="compile.html#enable_memory_management">SQLITE_ENABLE_MEMORY_MANAGEMENT</a> compile-time option is
2729 omitted.</p>
2730
2731 <p>See also: <a href="#sqlite3_release_memory">sqlite3_release_memory()</a>
2732 </p><hr><a name="sqlite3_declare_vtab"></a>
2733 <h2>Declare The Schema Of A Virtual Table</h2>
2734 </div>
2735 <blockquote><pre>
2736 int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
2737 </pre></blockquote>
2738 <p>
2739 The <a href="vtab.html#xcreate">xCreate</a> and <a href="vtab.html#xconnect">xConnect</a> methods of a
2740 <a href="#sqlite3_module">virtual table module</a> call this interface
2741 to declare the format (the names and datatypes of the columns) of
2742 the virtual tables they implement.
2743 </p><hr><a name="sqlite3_deserialize"></a>
2744 <h2>Deserialize a database</h2>
2745 </div>
2746 <blockquote><pre>
2747 int sqlite3_deserialize(
2748 sqlite3 *db, /* The database connection */
2749 const char *zSchema, /* Which DB to reopen with the deserialization */
2750 unsigned char *pData, /* The serialized database content */
2751 sqlite3_int64 szDb, /* Number of bytes in the deserialization */
2752 sqlite3_int64 szBuf, /* Total size of buffer pData[] */
2753 unsigned mFlags /* Zero or more SQLITE_DESERIALIZE_* flags */
2754 );
2755 </pre></blockquote>
2756 <p>
2757 The sqlite3_deserialize(D,S,P,N,M,F) interface causes the
2758 <a href="#sqlite3">database connection</a> D to disconnect from database S and then
2759 reopen S as an in-memory database based on the serialization
2760 contained in P. If S is a NULL pointer, the main database is
2761 used. The serialized database P is N bytes in size. M is the size
2762 of the buffer P, which might be larger than N. If M is larger than
2763 N, and the SQLITE_DESERIALIZE_READONLY bit is not set in F, then
2764 SQLite is permitted to add content to the in-memory database as
2765 long as the total size does not exceed M bytes.</p>
2766
2767 <p>If the SQLITE_DESERIALIZE_FREEONCLOSE bit is set in F, then SQLite will
2768 invoke sqlite3_free() on the serialization buffer when the database
2769 connection closes. If the SQLITE_DESERIALIZE_RESIZEABLE bit is set, then
2770 SQLite will try to increase the buffer size using sqlite3_realloc64()
2771 if writes on the database cause it to grow larger than M bytes.</p>
2772
2773 <p>Applications must not modify the buffer P or invalidate it before
2774 the database connection D is closed.</p>
2775
2776 <p>The sqlite3_deserialize() interface will fail with SQLITE_BUSY if the
2777 database is currently in a read transaction or is involved in a backup
2778 operation.</p>
2779
2780 <p>It is not possible to deserialize into the TEMP database. If the
2781 S argument to sqlite3_deserialize(D,S,P,N,M,F) is "temp" then the
2782 function returns SQLITE_ERROR.</p>
2783
2784 <p>The deserialized database should not be in <a href="wal.html">WAL mode</a>. If the database
2785 is in WAL mode, then any attempt to use the database file will result
2786 in an <a href="#SQLITE_ABORT">SQLITE_CANTOPEN</a> error. The application can set the
2787 <a href="fileformat2.html#vnums">file format version numbers</a> (bytes 18 and 19) of the input database P
2788 to 0x01 prior to invoking sqlite3_deserialize(D,S,P,N,M,F) to force the
2789 database file into rollback mode and work around this limitation.</p>
2790
2791 <p>If sqlite3_deserialize(D,S,P,N,M,F) fails for any reason and if the
2792 SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F, then
2793 <a href="#sqlite3_free">sqlite3_free()</a> is invoked on argument P prior to returning.</p>
2794
2795 <p>This interface is omitted if SQLite is compiled with the
2796 <a href="compile.html#omit_deserialize">SQLITE_OMIT_DESERIALIZE</a> option.
2797 </p><hr><a name="sqlite3_drop_modules"></a>
2798 <h2>Remove Unnecessary Virtual Table Implementations</h2>
2799 </div>
2800 <blockquote><pre>
2801 int sqlite3_drop_modules(
2802 sqlite3 *db, /* Remove modules from this connection */
2803 const char **azKeep /* Except, do not remove the ones named here */
2804 );
2805 </pre></blockquote>
2806 <p>
2807 The sqlite3_drop_modules(D,L) interface removes all virtual
2808 table modules from database connection D except those named on list L.
2809 The L parameter must be either NULL or a pointer to an array of pointers
2810 to strings where the array is terminated by a single NULL pointer.
2811 If the L parameter is NULL, then all virtual table modules are removed.</p>
2812
2813 <p>See also: <a href="#sqlite3_create_module">sqlite3_create_module()</a>
2814 </p><hr><a name="sqlite3_enable_load_extension"></a>
2815 <h2>Enable Or Disable Extension Loading</h2>
2816 </div>
2817 <blockquote><pre>
2818 int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
2819 </pre></blockquote>
2820 <p>
2821 So as not to open security holes in older applications that are
2822 unprepared to deal with <a href="loadext.html">extension loading</a>, and as a means of disabling
2823 <a href="loadext.html">extension loading</a> while evaluating user-entered SQL, the following API
2824 is provided to turn the <a href="#sqlite3_load_extension">sqlite3_load_extension()</a> mechanism on and off.</p>
2825
2826 <p>Extension loading is off by default.
2827 Call the sqlite3_enable_load_extension() routine with onoff==1
2828 to turn extension loading on and call it with onoff==0 to turn
2829 it back off again.</p>
2830
2831 <p>This interface enables or disables both the C-API
2832 <a href="#sqlite3_load_extension">sqlite3_load_extension()</a> and the SQL function <a href="lang_corefunc.html#load_extension">load_extension()</a>.
2833 Use <a href="#sqlite3_db_config">sqlite3_db_config</a>(db,<a href="#sqlitedbconfigenableloadextension">SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</a>,..)
2834 to enable or disable only the C-API.</p>
2835
2836 <p><b>Security warning:</b> It is recommended that extension loading
2837 be enabled using the <a href="#sqlitedbconfigenableloadextension">SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</a> method
2838 rather than this interface, so the <a href="lang_corefunc.html#load_extension">load_extension()</a> SQL function
2839 remains disabled. This will prevent SQL injections from giving attackers
2840 access to extension loading capabilities.
2841 </p><hr><a name="sqlite3_enable_shared_cache"></a>
2842 <h2>Enable Or Disable Shared Pager Cache</h2>
2843 </div>
2844 <blockquote><pre>
2845 int sqlite3_enable_shared_cache(int);
2846 </pre></blockquote>
2847 <p>
2848 This routine enables or disables the sharing of the database cache
2849 and schema data structures between <a href="#sqlite3">connections</a>
2850 to the same database. Sharing is enabled if the argument is true
2851 and disabled if the argument is false.</p>
2852
2853 <p>This interface is omitted if SQLite is compiled with
2854 <a href="compile.html#omit_shared_cache">-DSQLITE_OMIT_SHARED_CACHE</a>. The <a href="compile.html#omit_shared_cache">-DSQLITE_OMIT_SHARED_CACHE</a>
2855 compile-time option is recommended because the
2856 <a href="sharedcache.html#dontuse">use of shared cache mode is discouraged</a>.</p>
2857
2858 <p>Cache sharing is enabled and disabled for an entire process.
2859 This is a change as of SQLite <a href="releaselog/3_5_0.html">version 3.5.0</a> (2007-09-04).
2860 In prior versions of SQLite,
2861 sharing was enabled or disabled for each thread separately.</p>
2862
2863 <p>The cache sharing mode set by this interface effects all subsequent
2864 calls to <a href="#sqlite3_open">sqlite3_open()</a>, <a href="#sqlite3_open">sqlite3_open_v2()</a>, and <a href="#sqlite3_open">sqlite3_open16()</a>.
2865 Existing database connections continue to use the sharing mode
2866 that was in effect at the time they were opened.</p>
2867
2868 <p>This routine returns <a href="#SQLITE_ABORT">SQLITE_OK</a> if shared cache was enabled or disabled
2869 successfully. An <a href="rescode.html">error code</a> is returned otherwise.</p>
2870
2871 <p>Shared cache is disabled by default. It is recommended that it stay
2872 that way. In other words, do not use this routine. This interface
2873 continues to be provided for historical compatibility, but its use is
2874 discouraged. Any use of shared cache is discouraged. If shared cache
2875 must be used, it is recommended that shared cache only be enabled for
2876 individual database connections using the <a href="#sqlite3_open">sqlite3_open_v2()</a> interface
2877 with the <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_SHAREDCACHE</a> flag.</p>
2878
2879 <p>Note: This method is disabled on MacOS X 10.7 and iOS version 5.0
2880 and will always return SQLITE_MISUSE. On those systems,
2881 shared cache mode should be enabled per-database connection via
2882 <a href="#sqlite3_open">sqlite3_open_v2()</a> with <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_SHAREDCACHE</a>.</p>
2883
2884 <p>This interface is threadsafe on processors where writing a
2885 32-bit integer is atomic.</p>
2886
2887 <p>See Also: <a href="sharedcache.html">SQLite Shared-Cache Mode</a>
2888 </p><hr><a name="sqlite3_exec"></a>
2889 <h2>One-Step Query Execution Interface</h2>
2890 </div>
2891 <blockquote><pre>
2892 int sqlite3_exec(
2893 sqlite3*, /* An open database */
2894 const char *sql, /* SQL to be evaluated */
2895 int (*callback)(void*,int,char**,char**), /* Callback function */
2896 void *, /* 1st argument to callback */
2897 char **errmsg /* Error msg written here */
2898 );
2899 </pre></blockquote>
2900 <p>
2901 The sqlite3_exec() interface is a convenience wrapper around
2902 <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>, <a href="#sqlite3_step">sqlite3_step()</a>, and <a href="#sqlite3_finalize">sqlite3_finalize()</a>,
2903 that allows an application to run multiple statements of SQL
2904 without having to use a lot of C code.</p>
2905
2906 <p>The sqlite3_exec() interface runs zero or more UTF-8 encoded,
2907 semicolon-separated SQL statements passed into its 2nd argument,
2908 in the context of the <a href="#sqlite3">database connection</a> passed in as its 1st
2909 argument. If the callback function of the 3rd argument to
2910 sqlite3_exec() is not NULL, then it is invoked for each result row
2911 coming out of the evaluated SQL statements. The 4th argument to
2912 sqlite3_exec() is relayed through to the 1st argument of each
2913 callback invocation. If the callback pointer to sqlite3_exec()
2914 is NULL, then no callback is ever invoked and result rows are
2915 ignored.</p>
2916
2917 <p>If an error occurs while evaluating the SQL statements passed into
2918 sqlite3_exec(), then execution of the current statement stops and
2919 subsequent statements are skipped. If the 5th parameter to sqlite3_exec()
2920 is not NULL then any error message is written into memory obtained
2921 from <a href="#sqlite3_free">sqlite3_malloc()</a> and passed back through the 5th parameter.
2922 To avoid memory leaks, the application should invoke <a href="#sqlite3_free">sqlite3_free()</a>
2923 on error message strings returned through the 5th parameter of
2924 sqlite3_exec() after the error message string is no longer needed.
2925 If the 5th parameter to sqlite3_exec() is not NULL and no errors
2926 occur, then sqlite3_exec() sets the pointer in its 5th parameter to
2927 NULL before returning.</p>
2928
2929 <p>If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
2930 routine returns SQLITE_ABORT without invoking the callback again and
2931 without running any subsequent SQL statements.</p>
2932
2933 <p>The 2nd argument to the sqlite3_exec() callback function is the
2934 number of columns in the result. The 3rd argument to the sqlite3_exec()
2935 callback is an array of pointers to strings obtained as if from
2936 <a href="#sqlite3_column_blob">sqlite3_column_text()</a>, one for each column. If an element of a
2937 result row is NULL then the corresponding string pointer for the
2938 sqlite3_exec() callback is a NULL pointer. The 4th argument to the
2939 sqlite3_exec() callback is an array of pointers to strings where each
2940 entry represents the name of a corresponding result column as obtained
2941 from <a href="#sqlite3_column_name">sqlite3_column_name()</a>.</p>
2942
2943 <p>If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
2944 to an empty string, or a pointer that contains only whitespace and/or
2945 SQL comments, then no SQL statements are evaluated and the database
2946 is not changed.</p>
2947
2948 <p>Restrictions:</p>
2949
2950 <p><ul>
2951 <li> The application must ensure that the 1st parameter to sqlite3_exec()
2952 is a valid and open <a href="#sqlite3">database connection</a>.
2953 <li> The application must not close the <a href="#sqlite3">database connection</a> specified by
2954 the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
2955 <li> The application must not modify the SQL statement text passed into
2956 the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
2957 <li> The application must not dereference the arrays or string pointers
2958 passed as the 3rd and 4th callback parameters after it returns.
2959 </ul>
2960 </p><hr><a name="sqlite3_extended_result_codes"></a>
2961 <h2>Enable Or Disable Extended Result Codes</h2>
2962 </div>
2963 <blockquote><pre>
2964 int sqlite3_extended_result_codes(sqlite3*, int onoff);
2965 </pre></blockquote>
2966 <p>
2967 The sqlite3_extended_result_codes() routine enables or disables the
2968 <a href="rescode.html#extrc">extended result codes</a> feature of SQLite. The extended result
2969 codes are disabled by default for historical compatibility.
2970 </p><hr><a name="sqlite3_finalize"></a>
2971 <h2>Destroy A Prepared Statement Object</h2>
2972 </div>
2973 <blockquote><pre>
2974 int sqlite3_finalize(sqlite3_stmt *pStmt);
2975 </pre></blockquote>
2976 <p>
2977 The sqlite3_finalize() function is called to delete a <a href="#sqlite3_stmt">prepared statement</a>.
2978 If the most recent evaluation of the statement encountered no errors
2979 or if the statement has never been evaluated, then sqlite3_finalize() returns
2980 SQLITE_OK. If the most recent evaluation of statement S failed, then
2981 sqlite3_finalize(S) returns the appropriate <a href="rescode.html">error code</a> or
2982 <a href="rescode.html#extrc">extended error code</a>.</p>
2983
2984 <p>The sqlite3_finalize(S) routine can be called at any point during
2985 the life cycle of <a href="#sqlite3_stmt">prepared statement</a> S:
2986 before statement S is ever evaluated, after
2987 one or more calls to <a href="#sqlite3_reset">sqlite3_reset()</a>, or after any call
2988 to <a href="#sqlite3_step">sqlite3_step()</a> regardless of whether or not the statement has
2989 completed execution.</p>
2990
2991 <p>Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.</p>
2992
2993 <p>The application must finalize every <a href="#sqlite3_stmt">prepared statement</a> in order to avoid
2994 resource leaks. It is a grievous error for the application to try to use
2995 a prepared statement after it has been finalized. Any use of a prepared
2996 statement after it has been finalized can result in undefined and
2997 undesirable behavior such as segfaults and heap corruption.
2998 </p><hr><a name="sqlite3_last_insert_rowid"></a>
2999 <h2>Last Insert Rowid</h2>
3000 </div>
3001 <blockquote><pre>
3002 sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
3003 </pre></blockquote>
3004 <p>
3005 Each entry in most SQLite tables (except for <a href="withoutrowid.html">WITHOUT ROWID</a> tables)
3006 has a unique 64-bit signed
3007 integer key called the <a href="lang_createtable.html#rowid">"rowid"</a>. The rowid is always available
3008 as an undeclared column named ROWID, OID, or _ROWID_ as long as those
3009 names are not also used by explicitly declared columns. If
3010 the table has a column of type <a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a> then that column
3011 is another alias for the rowid.</p>
3012
3013 <p>The sqlite3_last_insert_rowid(D) interface usually returns the <a href="lang_createtable.html#rowid">rowid</a> of
3014 the most recent successful <a href="lang_insert.html">INSERT</a> into a rowid table or <a href="vtab.html">virtual table</a>
3015 on database connection D. Inserts into <a href="withoutrowid.html">WITHOUT ROWID</a> tables are not
3016 recorded. If no successful <a href="lang_insert.html">INSERT</a>s into rowid tables have ever occurred
3017 on the database connection D, then sqlite3_last_insert_rowid(D) returns
3018 zero.</p>
3019
3020 <p>As well as being set automatically as rows are inserted into database
3021 tables, the value returned by this function may be set explicitly by
3022 <a href="#sqlite3_set_last_insert_rowid">sqlite3_set_last_insert_rowid()</a></p>
3023
3024 <p>Some virtual table implementations may INSERT rows into rowid tables as
3025 part of committing a transaction (e.g. to flush data accumulated in memory
3026 to disk). In this case subsequent calls to this function return the rowid
3027 associated with these internal INSERT operations, which leads to
3028 unintuitive results. Virtual table implementations that do write to rowid
3029 tables in this way can avoid this problem by restoring the original
3030 rowid value using <a href="#sqlite3_set_last_insert_rowid">sqlite3_set_last_insert_rowid()</a> before returning
3031 control to the user.</p>
3032
3033 <p>If an <a href="lang_insert.html">INSERT</a> occurs within a trigger then this routine will
3034 return the <a href="lang_createtable.html#rowid">rowid</a> of the inserted row as long as the trigger is
3035 running. Once the trigger program ends, the value returned
3036 by this routine reverts to what it was before the trigger was fired.</p>
3037
3038 <p>An <a href="lang_insert.html">INSERT</a> that fails due to a constraint violation is not a
3039 successful <a href="lang_insert.html">INSERT</a> and does not change the value returned by this
3040 routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
3041 and INSERT OR ABORT make no changes to the return value of this
3042 routine when their insertion fails. When INSERT OR REPLACE
3043 encounters a constraint violation, it does not fail. The
3044 INSERT continues to completion after deleting rows that caused
3045 the constraint problem so INSERT OR REPLACE will always change
3046 the return value of this interface.</p>
3047
3048 <p>For the purposes of this routine, an <a href="lang_insert.html">INSERT</a> is considered to
3049 be successful even if it is subsequently rolled back.</p>
3050
3051 <p>This function is accessible to SQL statements via the
3052 <a href="lang_corefunc.html#last_insert_rowid">last_insert_rowid() SQL function</a>.</p>
3053
3054 <p>If a separate thread performs a new <a href="lang_insert.html">INSERT</a> on the same
3055 database connection while the <a href="#sqlite3_last_insert_rowid">sqlite3_last_insert_rowid()</a>
3056 function is running and thus changes the last insert <a href="lang_createtable.html#rowid">rowid</a>,
3057 then the value returned by <a href="#sqlite3_last_insert_rowid">sqlite3_last_insert_rowid()</a> is
3058 unpredictable and might not equal either the old or the new
3059 last insert <a href="lang_createtable.html#rowid">rowid</a>.
3060 </p><hr><a name="sqlite3_limit"></a>
3061 <h2>Run-time Limits</h2>
3062 </div>
3063 <blockquote><pre>
3064 int sqlite3_limit(sqlite3*, int id, int newVal);
3065 </pre></blockquote>
3066 <p>
3067 This interface allows the size of various constructs to be limited
3068 on a connection by connection basis. The first parameter is the
3069 <a href="#sqlite3">database connection</a> whose limit is to be set or queried. The
3070 second parameter is one of the <a href="#SQLITE_LIMIT_ATTACHED">limit categories</a> that define a
3071 class of constructs to be size limited. The third parameter is the
3072 new limit for that construct.</p>
3073
3074 <p>If the new limit is a negative number, the limit is unchanged.
3075 For each limit category SQLITE_LIMIT_<i>NAME</i> there is a
3076 <a href="limits.html">hard upper bound</a>
3077 set at compile-time by a C preprocessor macro called
3078 <a href="limits.html">SQLITE_MAX_<i>NAME</i></a>.
3079 (The "_LIMIT_" in the name is changed to "_MAX_".)
3080 Attempts to increase a limit above its hard upper bound are
3081 silently truncated to the hard upper bound.</p>
3082
3083 <p>Regardless of whether or not the limit was changed, the
3084 <a href="#sqlite3_limit">sqlite3_limit()</a> interface returns the prior value of the limit.
3085 Hence, to find the current value of a limit without changing it,
3086 simply invoke this interface with the third parameter set to -1.</p>
3087
3088 <p>Run-time limits are intended for use in applications that manage
3089 both their own internal database and also databases that are controlled
3090 by untrusted external sources. An example application might be a
3091 web browser that has its own databases for storing history and
3092 separate databases controlled by JavaScript applications downloaded
3093 off the Internet. The internal databases can be given the
3094 large, default limits. Databases managed by external sources can
3095 be given much smaller limits designed to prevent a denial of service
3096 attack. Developers might also want to use the <a href="#sqlite3_set_authorizer">sqlite3_set_authorizer()</a>
3097 interface to further control untrusted SQL. The size of the database
3098 created by an untrusted script can be contained using the
3099 <a href="pragma.html#pragma_max_page_count">max_page_count</a> <a href="pragma.html#syntax">PRAGMA</a>.</p>
3100
3101 <p>New run-time limit categories may be added in future releases.
3102 </p><hr><a name="sqlite3_load_extension"></a>
3103 <h2>Load An Extension</h2>
3104 </div>
3105 <blockquote><pre>
3106 int sqlite3_load_extension(
3107 sqlite3 *db, /* Load the extension into this database connection */
3108 const char *zFile, /* Name of the shared library containing extension */
3109 const char *zProc, /* Entry point. Derived from zFile if 0 */
3110 char **pzErrMsg /* Put error message here if not 0 */
3111 );
3112 </pre></blockquote>
3113 <p>
3114 This interface loads an SQLite extension library from the named file.</p>
3115
3116 <p>The sqlite3_load_extension() interface attempts to load an
3117 <a href="loadext.html">SQLite extension</a> library contained in the file zFile. If
3118 the file cannot be loaded directly, attempts are made to load
3119 with various operating-system specific filename extensions added.
3120 So for example, if "samplelib" cannot be loaded, then names like
3121 "samplelib.so" or "samplelib.dylib" or "samplelib.dll" might
3122 be tried also.</p>
3123
3124 <p>The entry point is zProc.
3125 zProc may be 0, in which case SQLite will try to come up with an
3126 entry point name on its own. It first tries "sqlite3_extension_init".
3127 If that does not work, it tries names of the form "sqlite3_X_init"
3128 where X consists of the lower-case equivalent of all ASCII alphabetic
3129 characters or all ASCII alphanumeric characters in the filename from
3130 the last "/" to the first following "." and omitting any initial "lib".
3131 The sqlite3_load_extension() interface returns
3132 <a href="#SQLITE_ABORT">SQLITE_OK</a> on success and <a href="#SQLITE_ABORT">SQLITE_ERROR</a> if something goes wrong.
3133 If an error occurs and pzErrMsg is not 0, then the
3134 <a href="#sqlite3_load_extension">sqlite3_load_extension()</a> interface shall attempt to
3135 fill *pzErrMsg with error message text stored in memory
3136 obtained from <a href="#sqlite3_free">sqlite3_malloc()</a>. The calling function
3137 should free this memory by calling <a href="#sqlite3_free">sqlite3_free()</a>.</p>
3138
3139 <p>Extension loading must be enabled using
3140 <a href="#sqlite3_enable_load_extension">sqlite3_enable_load_extension()</a> or
3141 <a href="#sqlite3_db_config">sqlite3_db_config</a>(db,<a href="#sqlitedbconfigenableloadextension">SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</a>,1,NULL)
3142 prior to calling this API,
3143 otherwise an error will be returned.</p>
3144
3145 <p><b>Security warning:</b> It is recommended that the
3146 <a href="#sqlitedbconfigenableloadextension">SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</a> method be used to enable only this
3147 interface. The use of the <a href="#sqlite3_enable_load_extension">sqlite3_enable_load_extension()</a> interface
3148 should be avoided. This will keep the SQL function <a href="lang_corefunc.html#load_extension">load_extension()</a>
3149 disabled and prevent SQL injections from giving attackers
3150 access to extension loading capabilities.</p>
3151
3152 <p>See also the <a href="lang_corefunc.html#load_extension">load_extension() SQL function</a>.
3153 </p><hr><a name="sqlite3_log"></a>
3154 <h2>Error Logging Interface</h2>
3155 </div>
3156 <blockquote><pre>
3157 void sqlite3_log(int iErrCode, const char *zFormat, ...);
3158 </pre></blockquote>
3159 <p>
3160 The <a href="#sqlite3_log">sqlite3_log()</a> interface writes a message into the <a href="errlog.html">error log</a>
3161 established by the <a href="#sqliteconfiglog">SQLITE_CONFIG_LOG</a> option to <a href="#sqlite3_config">sqlite3_config()</a>.
3162 If logging is enabled, the zFormat string and subsequent arguments are
3163 used with <a href="#sqlite3_mprintf">sqlite3_snprintf()</a> to generate the final output string.</p>
3164
3165 <p>The sqlite3_log() interface is intended for use by extensions such as
3166 virtual tables, collating functions, and SQL functions. While there is
3167 nothing to prevent an application from calling sqlite3_log(), doing so
3168 is considered bad form.</p>
3169
3170 <p>The zFormat string must not be NULL.</p>
3171
3172 <p>To avoid deadlocks and other threading problems, the sqlite3_log() routine
3173 will not use dynamically allocated memory. The log message is stored in
3174 a fixed-length buffer on the stack. If the log message is longer than
3175 a few hundred characters, it will be truncated to the length of the
3176 buffer.
3177 </p><hr><a name="sqlite3_next_stmt"></a>
3178 <h2>Find the next prepared statement</h2>
3179 </div>
3180 <blockquote><pre>
3181 sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
3182 </pre></blockquote>
3183 <p>
3184 This interface returns a pointer to the next <a href="#sqlite3_stmt">prepared statement</a> after
3185 pStmt associated with the <a href="#sqlite3">database connection</a> pDb. If pStmt is NULL
3186 then this interface returns a pointer to the first prepared statement
3187 associated with the database connection pDb. If no prepared statement
3188 satisfies the conditions of this routine, it returns NULL.</p>
3189
3190 <p>The <a href="#sqlite3">database connection</a> pointer D in a call to
3191 <a href="#sqlite3_next_stmt">sqlite3_next_stmt(D,S)</a> must refer to an open database
3192 connection and in particular must not be a NULL pointer.
3193 </p><hr><a name="sqlite3_overload_function"></a>
3194 <h2>Overload A Function For A Virtual Table</h2>
3195 </div>
3196 <blockquote><pre>
3197 int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
3198 </pre></blockquote>
3199 <p>
3200 Virtual tables can provide alternative implementations of functions
3201 using the <a href="vtab.html#xfindfunction">xFindFunction</a> method of the <a href="#sqlite3_module">virtual table module</a>.
3202 But global versions of those functions
3203 must exist in order to be overloaded.</p>
3204
3205 <p>This API makes sure a global version of a function with a particular
3206 name and number of parameters exists. If no such function exists
3207 before this API is called, a new function is created. The implementation
3208 of the new function always causes an exception to be thrown. So
3209 the new function is not good for anything by itself. Its only
3210 purpose is to be a placeholder function that can be overloaded
3211 by a <a href="vtab.html">virtual table</a>.
3212 </p><hr><a name="sqlite3_progress_handler"></a>
3213 <h2>Query Progress Callbacks</h2>
3214 </div>
3215 <blockquote><pre>
3216 void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
3217 </pre></blockquote>
3218 <p>
3219 The sqlite3_progress_handler(D,N,X,P) interface causes the callback
3220 function X to be invoked periodically during long running calls to
3221 <a href="#sqlite3_step">sqlite3_step()</a> and <a href="#sqlite3_prepare">sqlite3_prepare()</a> and similar for
3222 database connection D. An example use for this
3223 interface is to keep a GUI updated during a large query.</p>
3224
3225 <p>The parameter P is passed through as the only parameter to the
3226 callback function X. The parameter N is the approximate number of
3227 <a href="opcode.html">virtual machine instructions</a> that are evaluated between successive
3228 invocations of the callback X. If N is less than one then the progress
3229 handler is disabled.</p>
3230
3231 <p>Only a single progress handler may be defined at one time per
3232 <a href="#sqlite3">database connection</a>; setting a new progress handler cancels the
3233 old one. Setting parameter X to NULL disables the progress handler.
3234 The progress handler is also disabled by setting N to a value less
3235 than 1.</p>
3236
3237 <p>If the progress callback returns non-zero, the operation is
3238 interrupted. This feature can be used to implement a
3239 "Cancel" button on a GUI progress dialog box.</p>
3240
3241 <p>The progress handler callback must not do anything that will modify
3242 the database connection that invoked the progress handler.
3243 Note that <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> and <a href="#sqlite3_step">sqlite3_step()</a> both modify their
3244 database connections for the meaning of "modify" in this paragraph.</p>
3245
3246 <p>The progress handler callback would originally only be invoked from the
3247 bytecode engine. It still might be invoked during <a href="#sqlite3_prepare">sqlite3_prepare()</a>
3248 and similar because those routines might force a reparse of the schema
3249 which involves running the bytecode engine. However, beginning with
3250 SQLite version 3.41.0, the progress handler callback might also be
3251 invoked directly from <a href="#sqlite3_prepare">sqlite3_prepare()</a> while analyzing and generating
3252 code for complex queries.
3253 </p><hr><a name="sqlite3_randomness"></a>
3254 <h2>Pseudo-Random Number Generator</h2>
3255 </div>
3256 <blockquote><pre>
3257 void sqlite3_randomness(int N, void *P);
3258 </pre></blockquote>
3259 <p>
3260 SQLite contains a high-quality pseudo-random number generator (PRNG) used to
3261 select random <a href="lang_createtable.html#rowid">ROWIDs</a> when inserting new records into a table that
3262 already uses the largest possible <a href="lang_createtable.html#rowid">ROWID</a>. The PRNG is also used for
3263 the built-in random() and randomblob() SQL functions. This interface allows
3264 applications to access the same PRNG for other purposes.</p>
3265
3266 <p>A call to this routine stores N bytes of randomness into buffer P.
3267 The P parameter can be a NULL pointer.</p>
3268
3269 <p>If this routine has not been previously called or if the previous
3270 call had N less than one or a NULL pointer for P, then the PRNG is
3271 seeded using randomness obtained from the xRandomness method of
3272 the default <a href="#sqlite3_vfs">sqlite3_vfs</a> object.
3273 If the previous call to this routine had an N of 1 or more and a
3274 non-NULL P then the pseudo-randomness is generated
3275 internally and without recourse to the <a href="#sqlite3_vfs">sqlite3_vfs</a> xRandomness
3276 method.
3277 </p><hr><a name="sqlite3_release_memory"></a>
3278 <h2>Attempt To Free Heap Memory</h2>
3279 </div>
3280 <blockquote><pre>
3281 int sqlite3_release_memory(int);
3282 </pre></blockquote>
3283 <p>
3284 The sqlite3_release_memory() interface attempts to free N bytes
3285 of heap memory by deallocating non-essential memory allocations
3286 held by the database library. Memory used to cache database
3287 pages to improve performance is an example of non-essential memory.
3288 sqlite3_release_memory() returns the number of bytes actually freed,
3289 which might be more or less than the amount requested.
3290 The sqlite3_release_memory() routine is a no-op returning zero
3291 if SQLite is not compiled with <a href="compile.html#enable_memory_management">SQLITE_ENABLE_MEMORY_MANAGEMENT</a>.</p>
3292
3293 <p>See also: <a href="#sqlite3_db_release_memory">sqlite3_db_release_memory()</a>
3294 </p><hr><a name="sqlite3_reset"></a>
3295 <h2>Reset A Prepared Statement Object</h2>
3296 </div>
3297 <blockquote><pre>
3298 int sqlite3_reset(sqlite3_stmt *pStmt);
3299 </pre></blockquote>
3300 <p>
3301 The sqlite3_reset() function is called to reset a <a href="#sqlite3_stmt">prepared statement</a>
3302 object back to its initial state, ready to be re-executed.
3303 Any SQL statement variables that had values bound to them using
3304 the <a href="#sqlite3_bind_blob">sqlite3_bind_*() API</a> retain their values.
3305 Use <a href="#sqlite3_clear_bindings">sqlite3_clear_bindings()</a> to reset the bindings.</p>
3306
3307 <p>The <a href="#sqlite3_reset">sqlite3_reset(S)</a> interface resets the <a href="#sqlite3_stmt">prepared statement</a> S
3308 back to the beginning of its program.</p>
3309
3310 <p>The return code from <a href="#sqlite3_reset">sqlite3_reset(S)</a> indicates whether or not
3311 the previous evaluation of prepared statement S completed successfully.
3312 If <a href="#sqlite3_step">sqlite3_step(S)</a> has never before been called on S or if
3313 <a href="#sqlite3_step">sqlite3_step(S)</a> has not been called since the previous call
3314 to <a href="#sqlite3_reset">sqlite3_reset(S)</a>, then <a href="#sqlite3_reset">sqlite3_reset(S)</a> will return
3315 <a href="#SQLITE_ABORT">SQLITE_OK</a>.</p>
3316
3317 <p>If the most recent call to <a href="#sqlite3_step">sqlite3_step(S)</a> for the
3318 <a href="#sqlite3_stmt">prepared statement</a> S indicated an error, then
3319 <a href="#sqlite3_reset">sqlite3_reset(S)</a> returns an appropriate <a href="rescode.html">error code</a>.
3320 The <a href="#sqlite3_reset">sqlite3_reset(S)</a> interface might also return an <a href="rescode.html">error code</a>
3321 if there were no prior errors but the process of resetting
3322 the prepared statement caused a new error. For example, if an
3323 <a href="lang_insert.html">INSERT</a> statement with a <a href="lang_returning.html">RETURNING</a> clause is only stepped one time,
3324 that one call to <a href="#sqlite3_step">sqlite3_step(S)</a> might return SQLITE_ROW but
3325 the overall statement might still fail and the <a href="#sqlite3_reset">sqlite3_reset(S)</a> call
3326 might return SQLITE_BUSY if locking constraints prevent the
3327 database change from committing. Therefore, it is important that
3328 applications check the return code from <a href="#sqlite3_reset">sqlite3_reset(S)</a> even if
3329 no prior call to <a href="#sqlite3_step">sqlite3_step(S)</a> indicated a problem.</p>
3330
3331 <p>The <a href="#sqlite3_reset">sqlite3_reset(S)</a> interface does not change the values
3332 of any <a href="#sqlite3_bind_blob">bindings</a> on the <a href="#sqlite3_stmt">prepared statement</a> S.
3333 </p><hr><a name="sqlite3_reset_auto_extension"></a>
3334 <h2>Reset Automatic Extension Loading</h2>
3335 </div>
3336 <blockquote><pre>
3337 void sqlite3_reset_auto_extension(void);
3338 </pre></blockquote>
3339 <p>
3340 This interface disables all automatic extensions previously
3341 registered using <a href="#sqlite3_auto_extension">sqlite3_auto_extension()</a>.
3342 </p><hr><a name="sqlite3_result_subtype"></a>
3343 <h2>Setting The Subtype Of An SQL Function</h2>
3344 </div>
3345 <blockquote><pre>
3346 void sqlite3_result_subtype(sqlite3_context*,unsigned int);
3347 </pre></blockquote>
3348 <p>
3349 The sqlite3_result_subtype(C,T) function causes the subtype of
3350 the result from the <a href="appfunc.html">application-defined SQL function</a> with
3351 <a href="#sqlite3_context">sqlite3_context</a> C to be the value T. Only the lower 8 bits
3352 of the subtype T are preserved in current versions of SQLite;
3353 higher order bits are discarded.
3354 The number of subtype bytes preserved by SQLite might increase
3355 in future releases of SQLite.</p>
3356
3357 <p>Every <a href="appfunc.html">application-defined SQL function</a> that invokes this interface
3358 should include the <a href="#sqliteresultsubtype">SQLITE_RESULT_SUBTYPE</a> property in its
3359 text encoding argument when the SQL function is
3360 <a href="#sqlite3_create_function">registered</a>. If the <a href="#sqliteresultsubtype">SQLITE_RESULT_SUBTYPE</a>
3361 property is omitted from the function that invokes sqlite3_result_subtype(),
3362 then in some cases the sqlite3_result_subtype() might fail to set
3363 the result subtype.</p>
3364
3365 <p>If SQLite is compiled with -DSQLITE_STRICT_SUBTYPE=1, then any
3366 SQL function that invokes the sqlite3_result_subtype() interface
3367 and that does not have the SQLITE_RESULT_SUBTYPE property will raise
3368 an error. Future versions of SQLite might enable -DSQLITE_STRICT_SUBTYPE=1
3369 by default.
3370 </p><hr><a name="sqlite3_serialize"></a>
3371 <h2>Serialize a database</h2>
3372 </div>
3373 <blockquote><pre>
3374 unsigned char *sqlite3_serialize(
3375 sqlite3 *db, /* The database connection */
3376 const char *zSchema, /* Which DB to serialize. ex: "main", "temp", ... */
3377 sqlite3_int64 *piSize, /* Write size of the DB here, if not NULL */
3378 unsigned int mFlags /* Zero or more SQLITE_SERIALIZE_* flags */
3379 );
3380 </pre></blockquote>
3381 <p>
3382 The sqlite3_serialize(D,S,P,F) interface returns a pointer to
3383 memory that is a serialization of the S database on
3384 <a href="#sqlite3">database connection</a> D. If S is a NULL pointer, the main database is used.
3385 If P is not a NULL pointer, then the size of the database in bytes
3386 is written into *P.</p>
3387
3388 <p>For an ordinary on-disk database file, the serialization is just a
3389 copy of the disk file. For an in-memory database or a "TEMP" database,
3390 the serialization is the same sequence of bytes which would be written
3391 to disk if that database were backed up to disk.</p>
3392
3393 <p>The usual case is that sqlite3_serialize() copies the serialization of
3394 the database into memory obtained from <a href="#sqlite3_free">sqlite3_malloc64()</a> and returns
3395 a pointer to that memory. The caller is responsible for freeing the
3396 returned value to avoid a memory leak. However, if the F argument
3397 contains the SQLITE_SERIALIZE_NOCOPY bit, then no memory allocations
3398 are made, and the sqlite3_serialize() function will return a pointer
3399 to the contiguous memory representation of the database that SQLite
3400 is currently using for that database, or NULL if no such contiguous
3401 memory representation of the database exists. A contiguous memory
3402 representation of the database will usually only exist if there has
3403 been a prior call to <a href="#sqlite3_deserialize">sqlite3_deserialize(D,S,...)</a> with the same
3404 values of D and S.
3405 The size of the database is written into *P even if the
3406 SQLITE_SERIALIZE_NOCOPY bit is set but no contiguous copy
3407 of the database exists.</p>
3408
3409 <p>After the call, if the SQLITE_SERIALIZE_NOCOPY bit had been set,
3410 the returned buffer content will remain accessible and unchanged
3411 until either the next write operation on the connection or when
3412 the connection is closed, and applications must not modify the
3413 buffer. If the bit had been clear, the returned buffer will not
3414 be accessed by SQLite after the call.</p>
3415
3416 <p>A call to sqlite3_serialize(D,S,P,F) might return NULL even if the
3417 SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory
3418 allocation error occurs.</p>
3419
3420 <p>This interface is omitted if SQLite is compiled with the
3421 <a href="compile.html#omit_deserialize">SQLITE_OMIT_DESERIALIZE</a> option.
3422 </p><hr><a name="sqlite3_set_errmsg"></a>
3423 <h2>Set Error Code And Message</h2>
3424 </div>
3425 <blockquote><pre>
3426 int sqlite3_set_errmsg(sqlite3 *db, int errcode, const char *zErrMsg);
3427 </pre></blockquote>
3428 <p>
3429 Set the error code of the database handle passed as the first argument
3430 to errcode, and the error message to a copy of nul-terminated string
3431 zErrMsg. If zErrMsg is passed NULL, then the error message is set to
3432 the default message associated with the supplied error code. Subsequent
3433 calls to <a href="#sqlite3_errcode">sqlite3_errcode()</a> and <a href="#sqlite3_errcode">sqlite3_errmsg()</a> and similar will
3434 return the values set by this routine in place of what was previously
3435 set by SQLite itself.</p>
3436
3437 <p>This function returns SQLITE_OK if the error code and error message are
3438 successfully set, SQLITE_NOMEM if an OOM occurs, and SQLITE_MISUSE if
3439 the database handle is NULL or invalid.</p>
3440
3441 <p>The error code and message set by this routine remains in effect until
3442 they are changed, either by another call to this routine or until they are
3443 changed to by SQLite itself to reflect the result of some subsquent
3444 API call.</p>
3445
3446 <p>This function is intended for use by SQLite extensions or wrappers. The
3447 idea is that an extension or wrapper can use this routine to set error
3448 messages and error codes and thus behave more like a core SQLite
3449 feature from the point of view of an application.
3450 </p><hr><a name="sqlite3_set_last_insert_rowid"></a>
3451 <h2>Set the Last Insert Rowid value.</h2>
3452 </div>
3453 <blockquote><pre>
3454 void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
3455 </pre></blockquote>
3456 <p>
3457 The sqlite3_set_last_insert_rowid(D, R) method allows the application to
3458 set the value returned by calling sqlite3_last_insert_rowid(D) to R
3459 without inserting a row into the database.
3460 </p><hr><a name="sqlite3_setlk_timeout"></a>
3461 <h2>Set the Setlk Timeout</h2>
3462 </div>
3463 <blockquote><pre>
3464 int sqlite3_setlk_timeout(sqlite3*, int ms, int flags);
3465 </pre></blockquote>
3466 <p>
3467 This routine is only useful in SQLITE_ENABLE_SETLK_TIMEOUT builds. If
3468 the VFS supports blocking locks, it sets the timeout in ms used by
3469 eligible locks taken on wal mode databases by the specified database
3470 handle. In non-SQLITE_ENABLE_SETLK_TIMEOUT builds, or if the VFS does
3471 not support blocking locks, this function is a no-op.</p>
3472
3473 <p>Passing 0 to this function disables blocking locks altogether. Passing
3474 -1 to this function requests that the VFS blocks for a long time -
3475 indefinitely if possible. The results of passing any other negative value
3476 are undefined.</p>
3477
3478 <p>Internally, each SQLite database handle stores two timeout values - the
3479 busy-timeout (used for rollback mode databases, or if the VFS does not
3480 support blocking locks) and the setlk-timeout (used for blocking locks
3481 on wal-mode databases). The sqlite3_busy_timeout() method sets both
3482 values, this function sets only the setlk-timeout value. Therefore,
3483 to configure separate busy-timeout and setlk-timeout values for a single
3484 database handle, call sqlite3_busy_timeout() followed by this function.</p>
3485
3486 <p>Whenever the number of connections to a wal mode database falls from
3487 1 to 0, the last connection takes an exclusive lock on the database,
3488 then checkpoints and deletes the wal file. While it is doing this, any
3489 new connection that tries to read from the database fails with an
3490 SQLITE_BUSY error. Or, if the SQLITE_SETLK_BLOCK_ON_CONNECT flag is
3491 passed to this API, the new connection blocks until the exclusive lock
3492 has been released.
3493 </p><hr><a name="sqlite3_sleep"></a>
3494 <h2>Suspend Execution For A Short Time</h2>
3495 </div>
3496 <blockquote><pre>
3497 int sqlite3_sleep(int);
3498 </pre></blockquote>
3499 <p>
3500 The sqlite3_sleep() function causes the current thread to suspend execution
3501 for at least a number of milliseconds specified in its parameter.</p>
3502
3503 <p>If the operating system does not support sleep requests with
3504 millisecond time resolution, then the time will be rounded up to
3505 the nearest second. The number of milliseconds of sleep actually
3506 requested from the operating system is returned.</p>
3507
3508 <p>SQLite implements this interface by calling the xSleep()
3509 method of the default <a href="#sqlite3_vfs">sqlite3_vfs</a> object. If the xSleep() method
3510 of the default VFS is not implemented correctly, or not implemented at
3511 all, then the behavior of sqlite3_sleep() may deviate from the description
3512 in the previous paragraphs.</p>
3513
3514 <p>If a negative argument is passed to sqlite3_sleep() the results vary by
3515 VFS and operating system. Some system treat a negative argument as an
3516 instruction to sleep forever. Others understand it to mean do not sleep
3517 at all. In SQLite version 3.42.0 and later, a negative
3518 argument passed into sqlite3_sleep() is changed to zero before it is relayed
3519 down into the xSleep method of the VFS.
3520 </p><hr><a name="sqlite3_snapshot_cmp"></a>
3521 <h2>Compare the ages of two snapshot handles.</h2>
3522 </div>
3523 <blockquote><pre>
3524 int sqlite3_snapshot_cmp(
3525 sqlite3_snapshot *p1,
3526 sqlite3_snapshot *p2
3527 );
3528 </pre></blockquote>
3529 <p>
3530 The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages
3531 of two valid snapshot handles.</p>
3532
3533 <p>If the two snapshot handles are not associated with the same database
3534 file, the result of the comparison is undefined.</p>
3535
3536 <p>Additionally, the result of the comparison is only valid if both of the
3537 snapshot handles were obtained by calling sqlite3_snapshot_get() since the
3538 last time the wal file was deleted. The wal file is deleted when the
3539 database is changed back to rollback mode or when the number of database
3540 clients drops to zero. If either snapshot handle was obtained before the
3541 wal file was last deleted, the value returned by this function
3542 is undefined.</p>
3543
3544 <p>Otherwise, this API returns a negative value if P1 refers to an older
3545 snapshot than P2, zero if the two handles refer to the same database
3546 snapshot, and a positive value if P1 is a newer snapshot than P2.</p>
3547
3548 <p>This interface is only available if SQLite is compiled with the
3549 <a href="compile.html#enable_snapshot">SQLITE_ENABLE_SNAPSHOT</a> option.
3550 </p><hr><a name="sqlite3_snapshot_free"></a>
3551 <h2>Destroy a snapshot</h2>
3552 </div>
3553 <blockquote><pre>
3554 void sqlite3_snapshot_free(sqlite3_snapshot*);
3555 </pre></blockquote>
3556 <p>
3557 The <a href="#sqlite3_snapshot_free">sqlite3_snapshot_free(P)</a> interface destroys <a href="#sqlite3_snapshot">sqlite3_snapshot</a> P.
3558 The application must eventually free every <a href="#sqlite3_snapshot">sqlite3_snapshot</a> object
3559 using this routine to avoid a memory leak.</p>
3560
3561 <p>The <a href="#sqlite3_snapshot_free">sqlite3_snapshot_free()</a> interface is only available when the
3562 <a href="compile.html#enable_snapshot">SQLITE_ENABLE_SNAPSHOT</a> compile-time option is used.
3563 </p><hr><a name="sqlite3_snapshot_get"></a>
3564 <h2>Record A Database Snapshot</h2>
3565 </div>
3566 <blockquote><pre>
3567 int sqlite3_snapshot_get(
3568 sqlite3 *db,
3569 const char *zSchema,
3570 sqlite3_snapshot **ppSnapshot
3571 );
3572 </pre></blockquote>
3573 <p>
3574 The <a href="#sqlite3_snapshot_get">sqlite3_snapshot_get(D,S,P)</a> interface attempts to make a
3575 new <a href="#sqlite3_snapshot">sqlite3_snapshot</a> object that records the current state of
3576 schema S in database connection D. On success, the
3577 <a href="#sqlite3_snapshot_get">sqlite3_snapshot_get(D,S,P)</a> interface writes a pointer to the newly
3578 created <a href="#sqlite3_snapshot">sqlite3_snapshot</a> object into *P and returns SQLITE_OK.
3579 If there is not already a read-transaction open on schema S when
3580 this function is called, one is opened automatically.</p>
3581
3582 <p>If a read-transaction is opened by this function, then it is guaranteed
3583 that the returned snapshot object may not be invalidated by a database
3584 writer or checkpointer until after the read-transaction is closed. This
3585 is not guaranteed if a read-transaction is already open when this
3586 function is called. In that case, any subsequent write or checkpoint
3587 operation on the database may invalidate the returned snapshot handle,
3588 even while the read-transaction remains open.</p>
3589
3590 <p>The following must be true for this function to succeed. If any of
3591 the following statements are false when sqlite3_snapshot_get() is
3592 called, SQLITE_ERROR is returned. The final value of *P is undefined
3593 in this case.</p>
3594
3595 <p><ul>
3596 <li> The database handle must not be in <a href="#sqlite3_get_autocommit">autocommit mode</a>.</p>
3597
3598 <p><li> Schema S of <a href="#sqlite3">database connection</a> D must be a <a href="wal.html">WAL mode</a> database.</p>
3599
3600 <p><li> There must not be a write transaction open on schema S of database
3601 connection D.</p>
3602
3603 <p><li> One or more transactions must have been written to the current wal
3604 file since it was created on disk (by any connection). This means
3605 that a snapshot cannot be taken on a wal mode database with no wal
3606 file immediately after it is first opened. At least one transaction
3607 must be written to it first.
3608 </ul></p>
3609
3610 <p>This function may also return SQLITE_NOMEM. If it is called with the
3611 database handle in autocommit mode but fails for some other reason,
3612 whether or not a read transaction is opened on schema S is undefined.</p>
3613
3614 <p>The <a href="#sqlite3_snapshot">sqlite3_snapshot</a> object returned from a successful call to
3615 <a href="#sqlite3_snapshot_get">sqlite3_snapshot_get()</a> must be freed using <a href="#sqlite3_snapshot_free">sqlite3_snapshot_free()</a>
3616 to avoid a memory leak.</p>
3617
3618 <p>The <a href="#sqlite3_snapshot_get">sqlite3_snapshot_get()</a> interface is only available when the
3619 <a href="compile.html#enable_snapshot">SQLITE_ENABLE_SNAPSHOT</a> compile-time option is used.
3620 </p><hr><a name="sqlite3_snapshot_open"></a>
3621 <h2>Start a read transaction on an historical snapshot</h2>
3622 </div>
3623 <blockquote><pre>
3624 int sqlite3_snapshot_open(
3625 sqlite3 *db,
3626 const char *zSchema,
3627 sqlite3_snapshot *pSnapshot
3628 );
3629 </pre></blockquote>
3630 <p>
3631 The <a href="#sqlite3_snapshot_open">sqlite3_snapshot_open(D,S,P)</a> interface either starts a new read
3632 transaction or upgrades an existing one for schema S of
3633 <a href="#sqlite3">database connection</a> D such that the read transaction refers to
3634 historical <a href="#sqlite3_snapshot">snapshot</a> P, rather than the most recent change to the
3635 database. The <a href="#sqlite3_snapshot_open">sqlite3_snapshot_open()</a> interface returns SQLITE_OK
3636 on success or an appropriate <a href="rescode.html">error code</a> if it fails.</p>
3637
3638 <p>In order to succeed, the database connection must not be in
3639 <a href="#sqlite3_get_autocommit">autocommit mode</a> when <a href="#sqlite3_snapshot_open">sqlite3_snapshot_open(D,S,P)</a> is called. If there
3640 is already a read transaction open on schema S, then the database handle
3641 must have no active statements (SELECT statements that have been passed
3642 to sqlite3_step() but not sqlite3_reset() or sqlite3_finalize()).
3643 SQLITE_ERROR is returned if either of these conditions is violated, or
3644 if schema S does not exist, or if the snapshot object is invalid.</p>
3645
3646 <p>A call to sqlite3_snapshot_open() will fail to open if the specified
3647 snapshot has been overwritten by a <a href="wal.html#ckpt">checkpoint</a>. In this case
3648 SQLITE_ERROR_SNAPSHOT is returned.</p>
3649
3650 <p>If there is already a read transaction open when this function is
3651 invoked, then the same read transaction remains open (on the same
3652 database snapshot) if SQLITE_ERROR, SQLITE_BUSY or SQLITE_ERROR_SNAPSHOT
3653 is returned. If another error code - for example SQLITE_PROTOCOL or an
3654 SQLITE_IOERR error code - is returned, then the final state of the
3655 read transaction is undefined. If SQLITE_OK is returned, then the
3656 read transaction is now open on database snapshot P.</p>
3657
3658 <p>A call to <a href="#sqlite3_snapshot_open">sqlite3_snapshot_open(D,S,P)</a> will fail if the
3659 database connection D does not know that the database file for
3660 schema S is in <a href="wal.html">WAL mode</a>. A database connection might not know
3661 that the database file is in <a href="wal.html">WAL mode</a> if there has been no prior
3662 I/O on that database connection, or if the database entered <a href="wal.html">WAL mode</a>
3663 after the most recent I/O on the database connection.
3664 (Hint: Run "<a href="pragma.html#pragma_application_id">PRAGMA application_id</a>" against a newly opened
3665 database connection in order to make it ready to use snapshots.)</p>
3666
3667 <p>The <a href="#sqlite3_snapshot_open">sqlite3_snapshot_open()</a> interface is only available when the
3668 <a href="compile.html#enable_snapshot">SQLITE_ENABLE_SNAPSHOT</a> compile-time option is used.
3669 </p><hr><a name="sqlite3_snapshot_recover"></a>
3670 <h2>Recover snapshots from a wal file</h2>
3671 </div>
3672 <blockquote><pre>
3673 int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb);
3674 </pre></blockquote>
3675 <p>
3676 If a <a href="wal.html#walfile">WAL file</a> remains on disk after all database connections close
3677 (either through the use of the <a href="#sqlitefcntlpersistwal">SQLITE_FCNTL_PERSIST_WAL</a> <a href="#sqlite3_file_control">file control</a>
3678 or because the last process to have the database opened exited without
3679 calling <a href="#sqlite3_close">sqlite3_close()</a>) and a new connection is subsequently opened
3680 on that database and <a href="wal.html#walfile">WAL file</a>, the <a href="#sqlite3_snapshot_open">sqlite3_snapshot_open()</a> interface
3681 will only be able to open the last transaction added to the WAL file
3682 even though the WAL file contains other valid transactions.</p>
3683
3684 <p>This function attempts to scan the WAL file associated with database zDb
3685 of database handle db and make all valid snapshots available to
3686 sqlite3_snapshot_open(). It is an error if there is already a read
3687 transaction open on the database, or if the database is not a WAL mode
3688 database.</p>
3689
3690 <p>SQLITE_OK is returned if successful, or an SQLite error code otherwise.</p>
3691
3692 <p>This interface is only available if SQLite is compiled with the
3693 <a href="compile.html#enable_snapshot">SQLITE_ENABLE_SNAPSHOT</a> option.
3694 </p><hr><a name="sqlite3_soft_heap_limit"></a>
3695 <h2>Deprecated Soft Heap Limit Interface</h2>
3696 </div>
3697 <blockquote><pre>
3698 void sqlite3_soft_heap_limit(int N);
3699 </pre></blockquote>
3700 <p>
3701 This is a deprecated version of the <a href="#sqlite3_hard_heap_limit64">sqlite3_soft_heap_limit64()</a>
3702 interface. This routine is provided for historical compatibility
3703 only. All new applications should use the
3704 <a href="#sqlite3_hard_heap_limit64">sqlite3_soft_heap_limit64()</a> interface rather than this one.
3705 </p><hr><a name="sqlite3_step"></a>
3706 <h2>Evaluate An SQL Statement</h2>
3707 </div>
3708 <blockquote><pre>
3709 int sqlite3_step(sqlite3_stmt*);
3710 </pre></blockquote>
3711 <p>
3712 After a <a href="#sqlite3_stmt">prepared statement</a> has been prepared using any of
3713 <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>, <a href="#sqlite3_prepare">sqlite3_prepare_v3()</a>, <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a>,
3714 or <a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a> or one of the legacy
3715 interfaces <a href="#sqlite3_prepare">sqlite3_prepare()</a> or <a href="#sqlite3_prepare">sqlite3_prepare16()</a>, this function
3716 must be called one or more times to evaluate the statement.</p>
3717
3718 <p>The details of the behavior of the sqlite3_step() interface depend
3719 on whether the statement was prepared using the newer "vX" interfaces
3720 <a href="#sqlite3_prepare">sqlite3_prepare_v3()</a>, <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>, <a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a>,
3721 <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a> or the older legacy
3722 interfaces <a href="#sqlite3_prepare">sqlite3_prepare()</a> and <a href="#sqlite3_prepare">sqlite3_prepare16()</a>. The use of the
3723 new "vX" interface is recommended for new applications but the legacy
3724 interface will continue to be supported.</p>
3725
3726 <p>In the legacy interface, the return value will be either <a href="#SQLITE_ABORT">SQLITE_BUSY</a>,
3727 <a href="#SQLITE_ABORT">SQLITE_DONE</a>, <a href="#SQLITE_ABORT">SQLITE_ROW</a>, <a href="#SQLITE_ABORT">SQLITE_ERROR</a>, or <a href="#SQLITE_ABORT">SQLITE_MISUSE</a>.
3728 With the "v2" interface, any of the other <a href="rescode.html">result codes</a> or
3729 <a href="rescode.html#extrc">extended result codes</a> might be returned as well.</p>
3730
3731 <p><a href="#SQLITE_ABORT">SQLITE_BUSY</a> means that the database engine was unable to acquire the
3732 database locks it needs to do its job. If the statement is a <a href="lang_transaction.html">COMMIT</a>
3733 or occurs outside of an explicit transaction, then you can retry the
3734 statement. If the statement is not a <a href="lang_transaction.html">COMMIT</a> and occurs within an
3735 explicit transaction then you should rollback the transaction before
3736 continuing.</p>
3737
3738 <p><a href="#SQLITE_ABORT">SQLITE_DONE</a> means that the statement has finished executing
3739 successfully. sqlite3_step() should not be called again on this virtual
3740 machine without first calling <a href="#sqlite3_reset">sqlite3_reset()</a> to reset the virtual
3741 machine back to its initial state.</p>
3742
3743 <p>If the SQL statement being executed returns any data, then <a href="#SQLITE_ABORT">SQLITE_ROW</a>
3744 is returned each time a new row of data is ready for processing by the
3745 caller. The values may be accessed using the <a href="#sqlite3_column_blob">column access functions</a>.
3746 sqlite3_step() is called again to retrieve the next row of data.</p>
3747
3748 <p><a href="#SQLITE_ABORT">SQLITE_ERROR</a> means that a run-time error (such as a constraint
3749 violation) has occurred. sqlite3_step() should not be called again on
3750 the VM. More information may be found by calling <a href="#sqlite3_errcode">sqlite3_errmsg()</a>.
3751 With the legacy interface, a more specific error code (for example,
3752 <a href="#SQLITE_ABORT">SQLITE_INTERRUPT</a>, <a href="#SQLITE_ABORT">SQLITE_SCHEMA</a>, <a href="#SQLITE_ABORT">SQLITE_CORRUPT</a>, and so forth)
3753 can be obtained by calling <a href="#sqlite3_reset">sqlite3_reset()</a> on the
3754 <a href="#sqlite3_stmt">prepared statement</a>. In the "v2" interface,
3755 the more specific error code is returned directly by sqlite3_step().</p>
3756
3757 <p><a href="#SQLITE_ABORT">SQLITE_MISUSE</a> means that the this routine was called inappropriately.
3758 Perhaps it was called on a <a href="#sqlite3_stmt">prepared statement</a> that has
3759 already been <a href="#sqlite3_finalize">finalized</a> or on one that had
3760 previously returned <a href="#SQLITE_ABORT">SQLITE_ERROR</a> or <a href="#SQLITE_ABORT">SQLITE_DONE</a>. Or it could
3761 be the case that the same database connection is being used by two or
3762 more threads at the same moment in time.</p>
3763
3764 <p>For all versions of SQLite up to and including 3.6.23.1, a call to
3765 <a href="#sqlite3_reset">sqlite3_reset()</a> was required after sqlite3_step() returned anything
3766 other than <a href="#SQLITE_ABORT">SQLITE_ROW</a> before any subsequent invocation of
3767 sqlite3_step(). Failure to reset the prepared statement using
3768 <a href="#sqlite3_reset">sqlite3_reset()</a> would result in an <a href="#SQLITE_ABORT">SQLITE_MISUSE</a> return from
3769 sqlite3_step(). But after <a href="releaselog/3_6_23_1.html">version 3.6.23.1</a> (2010-03-26),
3770 sqlite3_step() began
3771 calling <a href="#sqlite3_reset">sqlite3_reset()</a> automatically in this circumstance rather
3772 than returning <a href="#SQLITE_ABORT">SQLITE_MISUSE</a>. This is not considered a compatibility
3773 break because any application that ever receives an SQLITE_MISUSE error
3774 is broken by definition. The <a href="compile.html#omit_autoreset">SQLITE_OMIT_AUTORESET</a> compile-time option
3775 can be used to restore the legacy behavior.</p>
3776
3777 <p><b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
3778 API always returns a generic error code, <a href="#SQLITE_ABORT">SQLITE_ERROR</a>, following any
3779 error other than <a href="#SQLITE_ABORT">SQLITE_BUSY</a> and <a href="#SQLITE_ABORT">SQLITE_MISUSE</a>. You must call
3780 <a href="#sqlite3_reset">sqlite3_reset()</a> or <a href="#sqlite3_finalize">sqlite3_finalize()</a> in order to find one of the
3781 specific <a href="rescode.html">error codes</a> that better describes the error.
3782 We admit that this is a goofy design. The problem has been fixed
3783 with the "v2" interface. If you prepare all of your SQL statements
3784 using <a href="#sqlite3_prepare">sqlite3_prepare_v3()</a> or <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>
3785 or <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a> or <a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a> instead
3786 of the legacy <a href="#sqlite3_prepare">sqlite3_prepare()</a> and <a href="#sqlite3_prepare">sqlite3_prepare16()</a> interfaces,
3787 then the more specific <a href="rescode.html">error codes</a> are returned directly
3788 by sqlite3_step(). The use of the "vX" interfaces is recommended.
3789 </p><hr><a name="sqlite3_stmt_busy"></a>
3790 <h2>Determine If A Prepared Statement Has Been Reset</h2>
3791 </div>
3792 <blockquote><pre>
3793 int sqlite3_stmt_busy(sqlite3_stmt*);
3794 </pre></blockquote>
3795 <p>
3796 The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
3797 <a href="#sqlite3_stmt">prepared statement</a> S has been stepped at least once using
3798 <a href="#sqlite3_step">sqlite3_step(S)</a> but has neither run to completion (returned
3799 <a href="#SQLITE_ABORT">SQLITE_DONE</a> from <a href="#sqlite3_step">sqlite3_step(S)</a>) nor
3800 been reset using <a href="#sqlite3_reset">sqlite3_reset(S)</a>. The sqlite3_stmt_busy(S)
3801 interface returns false if S is a NULL pointer. If S is not a
3802 NULL pointer and is not a pointer to a valid <a href="#sqlite3_stmt">prepared statement</a>
3803 object, then the behavior is undefined and probably undesirable.</p>
3804
3805 <p>This interface can be used in combination <a href="#sqlite3_next_stmt">sqlite3_next_stmt()</a>
3806 to locate all prepared statements associated with a database
3807 connection that are in need of being reset. This can be used,
3808 for example, in diagnostic routines to search for prepared
3809 statements that are holding a transaction open.
3810 </p><hr><a name="sqlite3_stmt_explain"></a>
3811 <h2>Change The EXPLAIN Setting For A Prepared Statement</h2>
3812 </div>
3813 <blockquote><pre>
3814 int sqlite3_stmt_explain(sqlite3_stmt *pStmt, int eMode);
3815 </pre></blockquote>
3816 <p>
3817 The sqlite3_stmt_explain(S,E) interface changes the EXPLAIN
3818 setting for <a href="#sqlite3_stmt">prepared statement</a> S. If E is zero, then S becomes
3819 a normal prepared statement. If E is 1, then S behaves as if
3820 its SQL text began with "<a href="lang_explain.html">EXPLAIN</a>". If E is 2, then S behaves as if
3821 its SQL text began with "<a href="eqp.html">EXPLAIN QUERY PLAN</a>".</p>
3822
3823 <p>Calling sqlite3_stmt_explain(S,E) might cause S to be reprepared.
3824 SQLite tries to avoid a reprepare, but a reprepare might be necessary
3825 on the first transition into EXPLAIN or EXPLAIN QUERY PLAN mode.</p>
3826
3827 <p>Because of the potential need to reprepare, a call to
3828 sqlite3_stmt_explain(S,E) will fail with SQLITE_ERROR if S cannot be
3829 reprepared because it was created using <a href="#sqlite3_prepare">sqlite3_prepare()</a> instead of
3830 the newer <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or <a href="#sqlite3_prepare">sqlite3_prepare_v3()</a> interfaces and
3831 hence has no saved SQL text with which to reprepare.</p>
3832
3833 <p>Changing the explain setting for a prepared statement does not change
3834 the original SQL text for the statement. Hence, if the SQL text originally
3835 began with EXPLAIN or EXPLAIN QUERY PLAN, but sqlite3_stmt_explain(S,0)
3836 is called to convert the statement into an ordinary statement, the EXPLAIN
3837 or EXPLAIN QUERY PLAN keywords will still appear in the sqlite3_sql(S)
3838 output, even though the statement now acts like a normal SQL statement.</p>
3839
3840 <p>This routine returns SQLITE_OK if the explain mode is successfully
3841 changed, or an error code if the explain mode could not be changed.
3842 The explain mode cannot be changed while a statement is active.
3843 Hence, it is good practice to call <a href="#sqlite3_reset">sqlite3_reset(S)</a>
3844 immediately prior to calling sqlite3_stmt_explain(S,E).
3845 </p><hr><a name="sqlite3_stmt_isexplain"></a>
3846 <h2>Query The EXPLAIN Setting For A Prepared Statement</h2>
3847 </div>
3848 <blockquote><pre>
3849 int sqlite3_stmt_isexplain(sqlite3_stmt *pStmt);
3850 </pre></blockquote>
3851 <p>
3852 The sqlite3_stmt_isexplain(S) interface returns 1 if the
3853 prepared statement S is an EXPLAIN statement, or 2 if the
3854 statement S is an EXPLAIN QUERY PLAN.
3855 The sqlite3_stmt_isexplain(S) interface returns 0 if S is
3856 an ordinary statement or a NULL pointer.
3857 </p><hr><a name="sqlite3_stmt_readonly"></a>
3858 <h2>Determine If An SQL Statement Writes The Database</h2>
3859 </div>
3860 <blockquote><pre>
3861 int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
3862 </pre></blockquote>
3863 <p>
3864 The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
3865 and only if the <a href="#sqlite3_stmt">prepared statement</a> X makes no direct changes to
3866 the content of the database file.</p>
3867
3868 <p>Note that <a href="appfunc.html">application-defined SQL functions</a> or
3869 <a href="vtab.html">virtual tables</a> might change the database indirectly as a side effect.
3870 For example, if an application defines a function "eval()" that
3871 calls <a href="#sqlite3_exec">sqlite3_exec()</a>, then the following SQL statement would
3872 change the database file through side-effects:</p>
3873
3874 <p><blockquote><pre>
3875 SELECT eval('DELETE FROM t1') FROM t2;
3876 </pre></blockquote></p>
3877
3878 <p>But because the <a href="lang_select.html">SELECT</a> statement does not change the database file
3879 directly, sqlite3_stmt_readonly() would still return true.</p>
3880
3881 <p>Transaction control statements such as <a href="lang_transaction.html">BEGIN</a>, <a href="lang_transaction.html">COMMIT</a>, <a href="lang_transaction.html">ROLLBACK</a>,
3882 <a href="lang_savepoint.html">SAVEPOINT</a>, and <a href="lang_savepoint.html">RELEASE</a> cause sqlite3_stmt_readonly() to return true,
3883 since the statements themselves do not actually modify the database but
3884 rather they control the timing of when other statements modify the
3885 database. The <a href="lang_attach.html">ATTACH</a> and <a href="lang_detach.html">DETACH</a> statements also cause
3886 sqlite3_stmt_readonly() to return true since, while those statements
3887 change the configuration of a database connection, they do not make
3888 changes to the content of the database files on disk.
3889 The sqlite3_stmt_readonly() interface returns true for <a href="lang_transaction.html">BEGIN</a> since
3890 <a href="lang_transaction.html">BEGIN</a> merely sets internal flags, but the <a href="lang_transaction.html">BEGIN IMMEDIATE</a> and
3891 <a href="lang_transaction.html">BEGIN EXCLUSIVE</a> commands do touch the database and so
3892 sqlite3_stmt_readonly() returns false for those commands.</p>
3893
3894 <p>This routine returns false if there is any possibility that the
3895 statement might change the database file. A false return does
3896 not guarantee that the statement will change the database file.
3897 For example, an UPDATE statement might have a WHERE clause that
3898 makes it a no-op, but the sqlite3_stmt_readonly() result would still
3899 be false. Similarly, a CREATE TABLE IF NOT EXISTS statement is a
3900 read-only no-op if the table already exists, but
3901 sqlite3_stmt_readonly() still returns false for such a statement.</p>
3902
3903 <p>If prepared statement X is an <a href="lang_explain.html">EXPLAIN</a> or <a href="eqp.html">EXPLAIN QUERY PLAN</a>
3904 statement, then sqlite3_stmt_readonly(X) returns the same value as
3905 if the EXPLAIN or EXPLAIN QUERY PLAN prefix were omitted.
3906 </p><hr><a name="sqlite3_stmt_scanstatus_reset"></a>
3907 <h2>Zero Scan-Status Counters</h2>
3908 </div>
3909 <blockquote><pre>
3910 void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*);
3911 </pre></blockquote>
3912 <p>
3913 Zero all <a href="#sqlite3_stmt_scanstatus">sqlite3_stmt_scanstatus()</a> related event counters.</p>
3914
3915 <p>This API is only available if the library is built with pre-processor
3916 symbol <a href="compile.html#enable_stmt_scanstatus">SQLITE_ENABLE_STMT_SCANSTATUS</a> defined.
3917 </p><hr><a name="sqlite3_stmt_status"></a>
3918 <h2>Prepared Statement Status</h2>
3919 </div>
3920 <blockquote><pre>
3921 int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
3922 </pre></blockquote>
3923 <p>
3924 Each prepared statement maintains various
3925 <a href="#SQLITE_STMTSTATUS counter">SQLITE_STMTSTATUS counters</a> that measure the number
3926 of times it has performed specific operations. These counters can
3927 be used to monitor the performance characteristics of the prepared
3928 statements. For example, if the number of table steps greatly exceeds
3929 the number of table searches or result rows, that would tend to indicate
3930 that the prepared statement is using a full table scan rather than
3931 an index.</p>
3932
3933 <p>This interface is used to retrieve and reset counter values from
3934 a <a href="#sqlite3_stmt">prepared statement</a>. The first argument is the prepared statement
3935 object to be interrogated. The second argument
3936 is an integer code for a specific <a href="#SQLITE_STMTSTATUS counter">SQLITE_STMTSTATUS counter</a>
3937 to be interrogated.
3938 The current value of the requested counter is returned.
3939 If the resetFlg is true, then the counter is reset to zero after this
3940 interface call returns.</p>
3941
3942 <p>See also: <a href="#sqlite3_status">sqlite3_status()</a> and <a href="#sqlite3_db_status">sqlite3_db_status()</a>.
3943 </p><hr><a name="sqlite3_str_new"></a>
3944 <h2>Create A New Dynamic String Object</h2>
3945 </div>
3946 <blockquote><pre>
3947 sqlite3_str *sqlite3_str_new(sqlite3*);
3948 </pre></blockquote>
3949 <p>
3950 The <a href="#sqlite3_str_new">sqlite3_str_new(D)</a> interface allocates and initializes
3951 a new <a href="#sqlite3_str">sqlite3_str</a> object. To avoid memory leaks, the object returned by
3952 <a href="#sqlite3_str_new">sqlite3_str_new()</a> must be freed by a subsequent call to
3953 <a href="#sqlite3_str_finish">sqlite3_str_finish(X)</a>.</p>
3954
3955 <p>The <a href="#sqlite3_str_new">sqlite3_str_new(D)</a> interface always returns a pointer to a
3956 valid <a href="#sqlite3_str">sqlite3_str</a> object, though in the event of an out-of-memory
3957 error the returned object might be a special singleton that will
3958 silently reject new text, always return SQLITE_NOMEM from
3959 <a href="#sqlite3_str_errcode">sqlite3_str_errcode()</a>, always return 0 for
3960 <a href="#sqlite3_str_errcode">sqlite3_str_length()</a>, and always return NULL from
3961 <a href="#sqlite3_str_finish">sqlite3_str_finish(X)</a>. It is always safe to use the value
3962 returned by <a href="#sqlite3_str_new">sqlite3_str_new(D)</a> as the sqlite3_str parameter
3963 to any of the other <a href="#sqlite3_str">sqlite3_str</a> methods.</p>
3964
3965 <p>The D parameter to <a href="#sqlite3_str_new">sqlite3_str_new(D)</a> may be NULL. If the
3966 D parameter in <a href="#sqlite3_str_new">sqlite3_str_new(D)</a> is not NULL, then the maximum
3967 length of the string contained in the <a href="#sqlite3_str">sqlite3_str</a> object will be
3968 the value set for <a href="#sqlite3_limit">sqlite3_limit</a>(D,<a href="#sqlitelimitlength">SQLITE_LIMIT_LENGTH</a>) instead
3969 of <a href="limits.html#max_length">SQLITE_MAX_LENGTH</a>.
3970 </p><hr><a name="sqlite3_strglob"></a>
3971 <h2>String Globbing</h2>
3972 </div>
3973 <blockquote><pre>
3974 int sqlite3_strglob(const char *zGlob, const char *zStr);
3975 </pre></blockquote>
3976 <p>The <a href="#sqlite3_strglob">sqlite3_strglob(P,X)</a> interface returns zero if and only if
3977 string X matches the <a href="lang_expr.html#glob">GLOB</a> pattern P.
3978 The definition of <a href="lang_expr.html#glob">GLOB</a> pattern matching used in
3979 <a href="#sqlite3_strglob">sqlite3_strglob(P,X)</a> is the same as for the "X GLOB P" operator in the
3980 SQL dialect understood by SQLite. The <a href="#sqlite3_strglob">sqlite3_strglob(P,X)</a> function
3981 is case sensitive.</p>
3982
3983 <p>Note that this routine returns zero on a match and non-zero if the strings
3984 do not match, the same as <a href="#sqlite3_stricmp">sqlite3_stricmp()</a> and <a href="#sqlite3_stricmp">sqlite3_strnicmp()</a>.</p>
3985
3986 <p>See also: <a href="#sqlite3_strlike">sqlite3_strlike()</a>.
3987 </p><hr><a name="sqlite3_strlike"></a>
3988 <h2>String LIKE Matching</h2>
3989 </div>
3990 <blockquote><pre>
3991 int sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc);
3992 </pre></blockquote>
3993 <p>The <a href="#sqlite3_strlike">sqlite3_strlike(P,X,E)</a> interface returns zero if and only if
3994 string X matches the <a href="lang_expr.html#like">LIKE</a> pattern P with escape character E.
3995 The definition of <a href="lang_expr.html#like">LIKE</a> pattern matching used in
3996 <a href="#sqlite3_strlike">sqlite3_strlike(P,X,E)</a> is the same as for the "X LIKE P ESCAPE E"
3997 operator in the SQL dialect understood by SQLite. For "X LIKE P" without
3998 the ESCAPE clause, set the E parameter of <a href="#sqlite3_strlike">sqlite3_strlike(P,X,E)</a> to 0.
3999 As with the LIKE operator, the <a href="#sqlite3_strlike">sqlite3_strlike(P,X,E)</a> function is case
4000 insensitive - equivalent upper and lower case ASCII characters match
4001 one another.</p>
4002
4003 <p>The <a href="#sqlite3_strlike">sqlite3_strlike(P,X,E)</a> function matches Unicode characters, though
4004 only ASCII characters are case folded.</p>
4005
4006 <p>Note that this routine returns zero on a match and non-zero if the strings
4007 do not match, the same as <a href="#sqlite3_stricmp">sqlite3_stricmp()</a> and <a href="#sqlite3_stricmp">sqlite3_strnicmp()</a>.</p>
4008
4009 <p>See also: <a href="#sqlite3_strglob">sqlite3_strglob()</a>.
4010 </p><hr><a name="sqlite3_system_errno"></a>
4011 <h2>Low-level system error code</h2>
4012 </div>
4013 <blockquote><pre>
4014 int sqlite3_system_errno(sqlite3*);
4015 </pre></blockquote>
4016 <p>
4017 Attempt to return the underlying operating system error code or error
4018 number that caused the most recent I/O error or failure to open a file.
4019 The return value is OS-dependent. For example, on unix systems, after
4020 <a href="#sqlite3_open">sqlite3_open_v2()</a> returns <a href="#SQLITE_ABORT">SQLITE_CANTOPEN</a>, this interface could be
4021 called to get back the underlying "errno" that caused the problem, such
4022 as ENOSPC, EAUTH, EISDIR, and so forth.
4023 </p><hr><a name="sqlite3_table_column_metadata"></a>
4024 <h2>Extract Metadata About A Column Of A Table</h2>
4025 </div>
4026 <blockquote><pre>
4027 int sqlite3_table_column_metadata(
4028 sqlite3 *db, /* Connection handle */
4029 const char *zDbName, /* Database name or NULL */
4030 const char *zTableName, /* Table name */
4031 const char *zColumnName, /* Column name */
4032 char const **pzDataType, /* OUTPUT: Declared data type */
4033 char const **pzCollSeq, /* OUTPUT: Collation sequence name */
4034 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
4035 int *pPrimaryKey, /* OUTPUT: True if column part of PK */
4036 int *pAutoinc /* OUTPUT: True if column is auto-increment */
4037 );
4038 </pre></blockquote>
4039 <p>
4040 The sqlite3_table_column_metadata(X,D,T,C,....) routine returns
4041 information about column C of table T in database D
4042 on <a href="#sqlite3">database connection</a> X. The sqlite3_table_column_metadata()
4043 interface returns SQLITE_OK and fills in the non-NULL pointers in
4044 the final five arguments with appropriate values if the specified
4045 column exists. The sqlite3_table_column_metadata() interface returns
4046 SQLITE_ERROR if the specified column does not exist.
4047 If the column-name parameter to sqlite3_table_column_metadata() is a
4048 NULL pointer, then this routine simply checks for the existence of the
4049 table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it
4050 does not. If the table name parameter T in a call to
4051 sqlite3_table_column_metadata(X,D,T,C,...) is NULL then the result is
4052 undefined behavior.</p>
4053
4054 <p>The column is identified by the second, third and fourth parameters to
4055 this function. The second parameter is either the name of the database
4056 (i.e. "main", "temp", or an attached database) containing the specified
4057 table or NULL. If it is NULL, then all attached databases are searched
4058 for the table using the same algorithm used by the database engine to
4059 resolve unqualified table references.</p>
4060
4061 <p>The third and fourth parameters to this function are the table and column
4062 name of the desired column, respectively.</p>
4063
4064 <p>Metadata is returned by writing to the memory locations passed as the 5th
4065 and subsequent parameters to this function. Any of these arguments may be
4066 NULL, in which case the corresponding element of metadata is omitted.</p>
4067
4068 <p><blockquote>
4069 <table border="1">
4070 <tr><th> Parameter <th> Output<br>Type <th> Description</p>
4071
4072 <p><tr><td> 5th <td> const char* <td> Data type
4073 <tr><td> 6th <td> const char* <td> Name of default collation sequence
4074 <tr><td> 7th <td> int <td> True if column has a NOT NULL constraint
4075 <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY
4076 <tr><td> 9th <td> int <td> True if column is <a href="autoinc.html">AUTOINCREMENT</a>
4077 </table>
4078 </blockquote></p>
4079
4080 <p>The memory pointed to by the character pointers returned for the
4081 declaration type and collation sequence is valid until the next
4082 call to any SQLite API function.</p>
4083
4084 <p>If the specified table is actually a view, an <a href="rescode.html">error code</a> is returned.</p>
4085
4086 <p>If the specified column is "rowid", "oid" or "_rowid_" and the table
4087 is not a <a href="withoutrowid.html">WITHOUT ROWID</a> table and an
4088 <a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a> column has been explicitly declared, then the output
4089 parameters are set for the explicitly declared column. If there is no
4090 <a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a> column, then the outputs
4091 for the <a href="lang_createtable.html#rowid">rowid</a> are set as follows:</p>
4092
4093 <p><pre>
4094 data type: "INTEGER"
4095 collation sequence: "BINARY"
4096 not null: 0
4097 primary key: 1
4098 auto increment: 0
4099 </pre></p>
4100
4101 <p>This function causes all database schemas to be read from disk and
4102 parsed, if that has not already been done, and returns an error if
4103 any errors are encountered while loading the schema.
4104 </p><hr><a name="sqlite3_test_control"></a>
4105 <h2>Testing Interface</h2>
4106 </div>
4107 <blockquote><pre>
4108 int sqlite3_test_control(int op, ...);
4109 </pre></blockquote>
4110 <p>
4111 The sqlite3_test_control() interface is used to read out internal
4112 state of SQLite and to inject faults into SQLite for testing
4113 purposes. The first parameter is an operation code that determines
4114 the number, meaning, and operation of all subsequent parameters.</p>
4115
4116 <p>This interface is not for use by applications. It exists solely
4117 for verifying the correct operation of the SQLite library. Depending
4118 on how the SQLite library is compiled, this interface might not exist.</p>
4119
4120 <p>The details of the operation codes, their meanings, the parameters
4121 they take, and what they do are all subject to change without notice.
4122 Unlike most of the SQLite API, this function is not guaranteed to
4123 operate consistently from one release to the next.
4124 </p><hr><a name="sqlite3_threadsafe"></a>
4125 <h2>Test To See If The Library Is Threadsafe</h2>
4126 </div>
4127 <blockquote><pre>
4128 int sqlite3_threadsafe(void);
4129 </pre></blockquote>
4130 <p>
4131 The sqlite3_threadsafe() function returns zero if and only if
4132 SQLite was compiled with mutexing code omitted due to the
4133 <a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> compile-time option being set to 0.</p>
4134
4135 <p>SQLite can be compiled with or without mutexes. When
4136 the <a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> C preprocessor macro is 1 or 2, mutexes
4137 are enabled and SQLite is threadsafe. When the
4138 <a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> macro is 0,
4139 the mutexes are omitted. Without the mutexes, it is not safe
4140 to use SQLite concurrently from more than one thread.</p>
4141
4142 <p>Enabling mutexes incurs a measurable performance penalty.
4143 So if speed is of utmost importance, it makes sense to disable
4144 the mutexes. But for maximum safety, mutexes should be enabled.
4145 The default behavior is for mutexes to be enabled.</p>
4146
4147 <p>This interface can be used by an application to make sure that the
4148 version of SQLite that it is linking against was compiled with
4149 the desired setting of the <a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> macro.</p>
4150
4151 <p>This interface only reports on the compile-time mutex setting
4152 of the <a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> flag. If SQLite is compiled with
4153 SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
4154 can be fully or partially disabled using a call to <a href="#sqlite3_config">sqlite3_config()</a>
4155 with the verbs <a href="#sqliteconfigsinglethread">SQLITE_CONFIG_SINGLETHREAD</a>, <a href="#sqliteconfigmultithread">SQLITE_CONFIG_MULTITHREAD</a>,
4156 or <a href="#sqliteconfigserialized">SQLITE_CONFIG_SERIALIZED</a>. The return value of the
4157 sqlite3_threadsafe() function shows only the compile-time setting of
4158 thread safety, not any run-time changes to that setting made by
4159 sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
4160 is unchanged by calls to sqlite3_config().</p>
4161
4162 <p>See the <a href="threadsafe.html">threading mode</a> documentation for additional information.
4163 </p><hr><a name="sqlite3_trace_v2"></a>
4164 <h2>SQL Trace Hook</h2>
4165 </div>
4166 <blockquote><pre>
4167 int sqlite3_trace_v2(
4168 sqlite3*,
4169 unsigned uMask,
4170 int(*xCallback)(unsigned,void*,void*,void*),
4171 void *pCtx
4172 );
4173 </pre></blockquote>
4174 <p>
4175 The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
4176 function X against <a href="#sqlite3">database connection</a> D, using property mask M
4177 and context pointer P. If the X callback is
4178 NULL or if the M mask is zero, then tracing is disabled. The
4179 M argument should be the bitwise OR-ed combination of
4180 zero or more <a href="#SQLITE_TRACE">SQLITE_TRACE</a> constants.</p>
4181
4182 <p>Each call to either sqlite3_trace(D,X,P) or sqlite3_trace_v2(D,M,X,P)
4183 overrides (cancels) all prior calls to sqlite3_trace(D,X,P) or
4184 sqlite3_trace_v2(D,M,X,P) for the <a href="#sqlite3">database connection</a> D. Each
4185 database connection may have at most one trace callback.</p>
4186
4187 <p>The X callback is invoked whenever any of the events identified by
4188 mask M occur. The integer return value from the callback is currently
4189 ignored, though this may change in future releases. Callback
4190 implementations should return zero to ensure future compatibility.</p>
4191
4192 <p>A trace callback is invoked with four arguments: callback(T,C,P,X).
4193 The T argument is one of the <a href="#SQLITE_TRACE">SQLITE_TRACE</a>
4194 constants to indicate why the callback was invoked.
4195 The C argument is a copy of the context pointer.
4196 The P and X arguments are pointers whose meanings depend on T.</p>
4197
4198 <p>The sqlite3_trace_v2() interface is intended to replace the legacy
4199 interfaces <a href="#sqlite3_profile">sqlite3_trace()</a> and <a href="#sqlite3_profile">sqlite3_profile()</a>, both of which
4200 are deprecated.
4201 </p><hr><a name="sqlite3_txn_state"></a>
4202 <h2>Determine the transaction state of a database</h2>
4203 </div>
4204 <blockquote><pre>
4205 int sqlite3_txn_state(sqlite3*,const char *zSchema);
4206 </pre></blockquote>
4207 <p>
4208 The sqlite3_txn_state(D,S) interface returns the current
4209 <a href="#SQLITE_TXN_NONE">transaction state</a> of schema S in database connection D. If S is NULL,
4210 then the highest transaction state of any schema on database connection D
4211 is returned. Transaction states are (in order of lowest to highest):
4212 <ol>
4213 <li value="0"> SQLITE_TXN_NONE
4214 <li value="1"> SQLITE_TXN_READ
4215 <li value="2"> SQLITE_TXN_WRITE
4216 </ol>
4217 If the S argument to sqlite3_txn_state(D,S) is not the name of
4218 a valid schema, then -1 is returned.
4219 </p><hr><a name="sqlite3_unlock_notify"></a>
4220 <h2>Unlock Notification</h2>
4221 </div>
4222 <blockquote><pre>
4223 int sqlite3_unlock_notify(
4224 sqlite3 *pBlocked, /* Waiting connection */
4225 void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */
4226 void *pNotifyArg /* Argument to pass to xNotify */
4227 );
4228 </pre></blockquote>
4229 <p>
4230 When running in shared-cache mode, a database operation may fail with
4231 an <a href="#SQLITE_ABORT">SQLITE_LOCKED</a> error if the required locks on the shared-cache or
4232 individual tables within the shared-cache cannot be obtained. See
4233 <a href="sharedcache.html">SQLite Shared-Cache Mode</a> for a description of shared-cache locking.
4234 This API may be used to register a callback that SQLite will invoke
4235 when the connection currently holding the required lock relinquishes it.
4236 This API is only available if the library was compiled with the
4237 <a href="compile.html#enable_unlock_notify">SQLITE_ENABLE_UNLOCK_NOTIFY</a> C-preprocessor symbol defined.</p>
4238
4239 <p>See Also: <a href="unlock_notify.html">Using the SQLite Unlock Notification Feature</a>.</p>
4240
4241 <p>Shared-cache locks are released when a database connection concludes
4242 its current transaction, either by committing it or rolling it back.</p>
4243
4244 <p>When a connection (known as the blocked connection) fails to obtain a
4245 shared-cache lock and SQLITE_LOCKED is returned to the caller, the
4246 identity of the database connection (the blocking connection) that
4247 has locked the required resource is stored internally. After an
4248 application receives an SQLITE_LOCKED error, it may call the
4249 sqlite3_unlock_notify() method with the blocked connection handle as
4250 the first argument to register for a callback that will be invoked
4251 when the blocking connection's current transaction is concluded. The
4252 callback is invoked from within the <a href="#sqlite3_step">sqlite3_step</a> or <a href="#sqlite3_close">sqlite3_close</a>
4253 call that concludes the blocking connection's transaction.</p>
4254
4255 <p>If sqlite3_unlock_notify() is called in a multi-threaded application,
4256 there is a chance that the blocking connection will have already
4257 concluded its transaction by the time sqlite3_unlock_notify() is invoked.
4258 If this happens, then the specified callback is invoked immediately,
4259 from within the call to sqlite3_unlock_notify().</p>
4260
4261 <p>If the blocked connection is attempting to obtain a write-lock on a
4262 shared-cache table, and more than one other connection currently holds
4263 a read-lock on the same table, then SQLite arbitrarily selects one of
4264 the other connections to use as the blocking connection.</p>
4265
4266 <p>There may be at most one unlock-notify callback registered by a
4267 blocked connection. If sqlite3_unlock_notify() is called when the
4268 blocked connection already has a registered unlock-notify callback,
4269 then the new callback replaces the old. If sqlite3_unlock_notify() is
4270 called with a NULL pointer as its second argument, then any existing
4271 unlock-notify callback is canceled. The blocked connection's
4272 unlock-notify callback may also be canceled by closing the blocked
4273 connection using <a href="#sqlite3_close">sqlite3_close()</a>.</p>
4274
4275 <p>The unlock-notify callback is not reentrant. If an application invokes
4276 any sqlite3_xxx API functions from within an unlock-notify callback, a
4277 crash or deadlock may be the result.</p>
4278
4279 <p>Unless deadlock is detected (see below), sqlite3_unlock_notify() always
4280 returns SQLITE_OK.</p>
4281
4282 <p><b>Callback Invocation Details</b></p>
4283
4284 <p>When an unlock-notify callback is registered, the application provides a
4285 single void* pointer that is passed to the callback when it is invoked.
4286 However, the signature of the callback function allows SQLite to pass
4287 it an array of void* context pointers. The first argument passed to
4288 an unlock-notify callback is a pointer to an array of void* pointers,
4289 and the second is the number of entries in the array.</p>
4290
4291 <p>When a blocking connection's transaction is concluded, there may be
4292 more than one blocked connection that has registered for an unlock-notify
4293 callback. If two or more such blocked connections have specified the
4294 same callback function, then instead of invoking the callback function
4295 multiple times, it is invoked once with the set of void* context pointers
4296 specified by the blocked connections bundled together into an array.
4297 This gives the application an opportunity to prioritize any actions
4298 related to the set of unblocked database connections.</p>
4299
4300 <p><b>Deadlock Detection</b></p>
4301
4302 <p>Assuming that after registering for an unlock-notify callback a
4303 database waits for the callback to be issued before taking any further
4304 action (a reasonable assumption), then using this API may cause the
4305 application to deadlock. For example, if connection X is waiting for
4306 connection Y's transaction to be concluded, and similarly connection
4307 Y is waiting on connection X's transaction, then neither connection
4308 will proceed and the system may remain deadlocked indefinitely.</p>
4309
4310 <p>To avoid this scenario, the sqlite3_unlock_notify() performs deadlock
4311 detection. If a given call to sqlite3_unlock_notify() would put the
4312 system in a deadlocked state, then SQLITE_LOCKED is returned and no
4313 unlock-notify callback is registered. The system is said to be in
4314 a deadlocked state if connection A has registered for an unlock-notify
4315 callback on the conclusion of connection B's transaction, and connection
4316 B has itself registered for an unlock-notify callback when connection
4317 A's transaction is concluded. Indirect deadlock is also detected, so
4318 the system is also considered to be deadlocked if connection B has
4319 registered for an unlock-notify callback on the conclusion of connection
4320 C's transaction, where connection C is waiting on connection A. Any
4321 number of levels of indirection are allowed.</p>
4322
4323 <p><b>The "DROP TABLE" Exception</b></p>
4324
4325 <p>When a call to <a href="#sqlite3_step">sqlite3_step()</a> returns SQLITE_LOCKED, it is almost
4326 always appropriate to call sqlite3_unlock_notify(). There is however,
4327 one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
4328 SQLite checks if there are any currently executing SELECT statements
4329 that belong to the same connection. If there are, SQLITE_LOCKED is
4330 returned. In this case there is no "blocking connection", so invoking
4331 sqlite3_unlock_notify() results in the unlock-notify callback being
4332 invoked immediately. If the application then re-attempts the "DROP TABLE"
4333 or "DROP INDEX" query, an infinite loop might be the result.</p>
4334
4335 <p>One way around this problem is to check the extended error code returned
4336 by an sqlite3_step() call. If there is a blocking connection, then the
4337 extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
4338 the special "DROP TABLE/INDEX" case, the extended error code is just
4339 SQLITE_LOCKED.
4340 </p><hr><a name="sqlite3_update_hook"></a>
4341 <h2>Data Change Notification Callbacks</h2>
4342 </div>
4343 <blockquote><pre>
4344 void *sqlite3_update_hook(
4345 sqlite3*,
4346 void(*)(void *,int ,char const *,char const *,sqlite3_int64),
4347 void*
4348 );
4349 </pre></blockquote>
4350 <p>
4351 The sqlite3_update_hook() interface registers a callback function
4352 with the <a href="#sqlite3">database connection</a> identified by the first argument
4353 to be invoked whenever a row is updated, inserted or deleted in
4354 a <a href="rowidtable.html">rowid table</a>.
4355 Any callback set by a previous call to this function
4356 for the same database connection is overridden.</p>
4357
4358 <p>The second argument is a pointer to the function to invoke when a
4359 row is updated, inserted or deleted in a rowid table.
4360 The update hook is disabled by invoking sqlite3_update_hook()
4361 with a NULL pointer as the second parameter.
4362 The first argument to the callback is a copy of the third argument
4363 to sqlite3_update_hook().
4364 The second callback argument is one of <a href="#SQLITE_ALTER_TABLE">SQLITE_INSERT</a>, <a href="#SQLITE_ALTER_TABLE">SQLITE_DELETE</a>,
4365 or <a href="#SQLITE_ALTER_TABLE">SQLITE_UPDATE</a>, depending on the operation that caused the callback
4366 to be invoked.
4367 The third and fourth arguments to the callback contain pointers to the
4368 database and table name containing the affected row.
4369 The final callback parameter is the <a href="lang_createtable.html#rowid">rowid</a> of the row.
4370 In the case of an update, this is the <a href="lang_createtable.html#rowid">rowid</a> after the update takes place.</p>
4371
4372 <p>The update hook is not invoked when internal system tables are
4373 modified (i.e. sqlite_sequence).
4374 The update hook is not invoked when <a href="withoutrowid.html">WITHOUT ROWID</a> tables are modified.</p>
4375
4376 <p>In the current implementation, the update hook
4377 is not invoked when conflicting rows are deleted because of an
4378 <a href="lang_conflict.html">ON CONFLICT REPLACE</a> clause. Nor is the update hook
4379 invoked when rows are deleted using the <a href="lang_delete.html#truncateopt">truncate optimization</a>.
4380 The exceptions defined in this paragraph might change in a future
4381 release of SQLite.</p>
4382
4383 <p>Whether the update hook is invoked before or after the
4384 corresponding change is currently unspecified and may differ
4385 depending on the type of change. Do not rely on the order of the
4386 hook call with regards to the final result of the operation which
4387 triggers the hook.</p>
4388
4389 <p>The update hook implementation must not do anything that will modify
4390 the database connection that invoked the update hook. Any actions
4391 to modify the database connection must be deferred until after the
4392 completion of the <a href="#sqlite3_step">sqlite3_step()</a> call that triggered the update hook.
4393 Note that <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> and <a href="#sqlite3_step">sqlite3_step()</a> both modify their
4394 database connections for the meaning of "modify" in this paragraph.</p>
4395
4396 <p>The sqlite3_update_hook(D,C,P) function
4397 returns the P argument from the previous call
4398 on the same <a href="#sqlite3">database connection</a> D, or NULL for
4399 the first call on D.</p>
4400
4401 <p>See also the <a href="#sqlite3_commit_hook">sqlite3_commit_hook()</a>, <a href="#sqlite3_commit_hook">sqlite3_rollback_hook()</a>,
4402 and <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_hook()</a> interfaces.
4403 </p><hr><a name="sqlite3_user_data"></a>
4404 <h2>User Data For Functions</h2>
4405 </div>
4406 <blockquote><pre>
4407 void *sqlite3_user_data(sqlite3_context*);
4408 </pre></blockquote>
4409 <p>
4410 The sqlite3_user_data() interface returns a copy of
4411 the pointer that was the pUserData parameter (the 5th parameter)
4412 of the <a href="#sqlite3_create_function">sqlite3_create_function()</a>
4413 and <a href="#sqlite3_create_function">sqlite3_create_function16()</a> routines that originally
4414 registered the application defined function.</p>
4415
4416 <p>This routine must be called from the same thread in which
4417 the application-defined function is running.
4418 </p><hr><a name="sqlite3_value_encoding"></a>
4419 <h2>Report the internal text encoding state of an sqlite3_value object</h2>
4420 </div>
4421 <blockquote><pre>
4422 int sqlite3_value_encoding(sqlite3_value*);
4423 </pre></blockquote>
4424 <p>
4425 The sqlite3_value_encoding(X) interface returns one of <a href="#sqliteutf8">SQLITE_UTF8</a>,
4426 <a href="#sqliteutf16be">SQLITE_UTF16BE</a>, or <a href="#sqliteutf16le">SQLITE_UTF16LE</a> according to the current text encoding
4427 of the value X, assuming that X has type TEXT. If sqlite3_value_type(X)
4428 returns something other than SQLITE_TEXT, then the return value from
4429 sqlite3_value_encoding(X) is meaningless. Calls to
4430 <a href="#sqlite3_value_blob">sqlite3_value_text(X)</a>, <a href="#sqlite3_value_blob">sqlite3_value_text16(X)</a>,
4431 <a href="#sqlite3_value_blob">sqlite3_value_text16be(X)</a>,
4432 <a href="#sqlite3_value_blob">sqlite3_value_text16le(X)</a>, <a href="#sqlite3_value_blob">sqlite3_value_bytes(X)</a>, or
4433 <a href="#sqlite3_value_blob">sqlite3_value_bytes16(X)</a> might change the encoding of the value X and
4434 thus change the return from subsequent calls to sqlite3_value_encoding(X).</p>
4435
4436 <p>This routine is intended for used by applications that test and validate
4437 the SQLite implementation. This routine is inquiring about the opaque
4438 internal state of an <a href="#sqlite3_value">sqlite3_value</a> object. Ordinary applications should
4439 not need to know what the internal state of an sqlite3_value object is and
4440 hence should not need to use this interface.
4441 </p><hr><a name="sqlite3_value_subtype"></a>
4442 <h2>Finding The Subtype Of SQL Values</h2>
4443 </div>
4444 <blockquote><pre>
4445 unsigned int sqlite3_value_subtype(sqlite3_value*);
4446 </pre></blockquote>
4447 <p>
4448 The sqlite3_value_subtype(V) function returns the subtype for
4449 an <a href="appfunc.html">application-defined SQL function</a> argument V. The subtype
4450 information can be used to pass a limited amount of context from
4451 one SQL function to another. Use the <a href="#sqlite3_result_subtype">sqlite3_result_subtype()</a>
4452 routine to set the subtype for the return value of an SQL function.</p>
4453
4454 <p>Every <a href="appfunc.html">application-defined SQL function</a> that invokes this interface
4455 should include the <a href="#sqlitesubtype">SQLITE_SUBTYPE</a> property in the text
4456 encoding argument when the function is <a href="#sqlite3_create_function">registered</a>.
4457 If the <a href="#sqlitesubtype">SQLITE_SUBTYPE</a> property is omitted, then sqlite3_value_subtype()
4458 might return zero instead of the upstream subtype in some corner cases.
4459 </p><hr><a name="sqlite3_vtab_collation"></a>
4460 <h2>Determine The Collation For a Virtual Table Constraint</h2>
4461 </div>
4462 <blockquote><pre>
4463 const char *sqlite3_vtab_collation(sqlite3_index_info*,int);
4464 </pre></blockquote>
4465 <p>
4466 This function may only be called from within a call to the <a href="vtab.html#xbestindex">xBestIndex</a>
4467 method of a <a href="vtab.html">virtual table</a>. This function returns a pointer to a string
4468 that is the name of the appropriate collation sequence to use for text
4469 comparisons on the constraint identified by its arguments.</p>
4470
4471 <p>The first argument must be the pointer to the <a href="#sqlite3_index_info">sqlite3_index_info</a> object
4472 that is the first parameter to the xBestIndex() method. The second argument
4473 must be an index into the aConstraint[] array belonging to the
4474 sqlite3_index_info structure passed to xBestIndex.</p>
4475
4476 <p>Important:
4477 The first parameter must be the same pointer that is passed into the
4478 xBestMethod() method. The first parameter may not be a pointer to a
4479 different <a href="#sqlite3_index_info">sqlite3_index_info</a> object, even an exact copy.</p>
4480
4481 <p>The return value is computed as follows:</p>
4482
4483 <p><ol>
4484 <li><p> If the constraint comes from a WHERE clause expression that contains
4485 a <a href="lang_expr.html#collateop">COLLATE operator</a>, then the name of the collation specified by
4486 that COLLATE operator is returned.
4487 <li><p> If there is no COLLATE operator, but the column that is the subject
4488 of the constraint specifies an alternative collating sequence via
4489 a <a href="lang_createtable.html#collateclause">COLLATE clause</a> on the column definition within the CREATE TABLE
4490 statement that was passed into <a href="#sqlite3_declare_vtab">sqlite3_declare_vtab()</a>, then the
4491 name of that alternative collating sequence is returned.
4492 <li><p> Otherwise, "BINARY" is returned.
4493 </ol>
4494 </p><hr><a name="sqlite3_vtab_config"></a>
4495 <h2>Virtual Table Interface Configuration</h2>
4496 </div>
4497 <blockquote><pre>
4498 int sqlite3_vtab_config(sqlite3*, int op, ...);
4499 </pre></blockquote>
4500 <p>
4501 This function may be called by either the <a href="vtab.html#xconnect">xConnect</a> or <a href="vtab.html#xcreate">xCreate</a> method
4502 of a <a href="vtab.html">virtual table</a> implementation to configure
4503 various facets of the virtual table interface.</p>
4504
4505 <p>If this interface is invoked outside the context of an xConnect or
4506 xCreate virtual table method then the behavior is undefined.</p>
4507
4508 <p>In the call sqlite3_vtab_config(D,C,...) the D parameter is the
4509 <a href="#sqlite3">database connection</a> in which the virtual table is being created and
4510 which is passed in as the first argument to the <a href="vtab.html#xconnect">xConnect</a> or <a href="vtab.html#xcreate">xCreate</a>
4511 method that is invoking sqlite3_vtab_config(). The C parameter is one
4512 of the <a href="#SQLITE_VTAB_CONSTRAINT_SUPPORT">virtual table configuration options</a>. The presence and meaning
4513 of parameters after C depend on which <a href="#SQLITE_VTAB_CONSTRAINT_SUPPORT">virtual table configuration option</a>
4514 is used.
4515 </p><hr><a name="sqlite3_vtab_distinct"></a>
4516 <h2>Determine if a virtual table query is DISTINCT</h2>
4517 </div>
4518 <blockquote><pre>
4519 int sqlite3_vtab_distinct(sqlite3_index_info*);
4520 </pre></blockquote>
4521 <p>
4522 This API may only be used from within an <a href="vtab.html#xbestindex">xBestIndex method</a>
4523 of a <a href="vtab.html">virtual table</a> implementation. The result of calling this
4524 interface from outside of xBestIndex() is undefined and probably harmful.</p>
4525
4526 <p>The sqlite3_vtab_distinct() interface returns an integer between 0 and
4527 3. The integer returned by sqlite3_vtab_distinct()
4528 gives the virtual table additional information about how the query
4529 planner wants the output to be ordered. As long as the virtual table
4530 can meet the ordering requirements of the query planner, it may set
4531 the "orderByConsumed" flag.</p>
4532
4533 <p><ol><li value="0"><p>
4534 If the sqlite3_vtab_distinct() interface returns 0, that means
4535 that the query planner needs the virtual table to return all rows in the
4536 sort order defined by the "nOrderBy" and "aOrderBy" fields of the
4537 <a href="#sqlite3_index_info">sqlite3_index_info</a> object. This is the default expectation. If the
4538 virtual table outputs all rows in sorted order, then it is always safe for
4539 the xBestIndex method to set the "orderByConsumed" flag, regardless of
4540 the return value from sqlite3_vtab_distinct().
4541 <li value="1"><p>
4542 If the sqlite3_vtab_distinct() interface returns 1, that means
4543 that the query planner does not need the rows to be returned in sorted order
4544 as long as all rows with the same values in all columns identified by the
4545 "aOrderBy" field are adjacent. This mode is used when the query planner
4546 is doing a GROUP BY.
4547 <li value="2"><p>
4548 If the sqlite3_vtab_distinct() interface returns 2, that means
4549 that the query planner does not need the rows returned in any particular
4550 order, as long as rows with the same values in all columns identified
4551 by "aOrderBy" are adjacent. Furthermore, when two or more rows
4552 contain the same values for all columns identified by "colUsed", all but
4553 one such row may optionally be omitted from the result.
4554 The virtual table is not required to omit rows that are duplicates
4555 over the "colUsed" columns, but if the virtual table can do that without
4556 too much extra effort, it could potentially help the query to run faster.
4557 This mode is used for a DISTINCT query.
4558 <li value="3"><p>
4559 If the sqlite3_vtab_distinct() interface returns 3, that means the
4560 virtual table must return rows in the order defined by "aOrderBy" as
4561 if the sqlite3_vtab_distinct() interface had returned 0. However if
4562 two or more rows in the result have the same values for all columns
4563 identified by "colUsed", then all but one such row may optionally be
4564 omitted. Like when the return value is 2, the virtual table
4565 is not required to omit rows that are duplicates over the "colUsed"
4566 columns, but if the virtual table can do that without
4567 too much extra effort, it could potentially help the query to run faster.
4568 This mode is used for queries
4569 that have both DISTINCT and ORDER BY clauses.
4570 </ol></p>
4571
4572 <p><p>The following table summarizes the conditions under which the
4573 virtual table is allowed to set the "orderByConsumed" flag based on
4574 the value returned by sqlite3_vtab_distinct(). This table is a
4575 restatement of the previous four paragraphs:</p>
4576
4577 <p><table border=1 cellspacing=0 cellpadding=10 width="90%">
4578 <tr>
4579 <td valign="top">sqlite3_vtab_distinct() return value
4580 <td valign="top">Rows are returned in aOrderBy order
4581 <td valign="top">Rows with the same value in all aOrderBy columns are
4582 adjacent
4583 <td valign="top">Duplicates over all colUsed columns may be omitted
4584 <tr><td>0<td>yes<td>yes<td>no
4585 <tr><td>1<td>no<td>yes<td>no
4586 <tr><td>2<td>no<td>yes<td>yes
4587 <tr><td>3<td>yes<td>yes<td>yes
4588 </table></p>
4589
4590 <p>For the purposes of comparing virtual table output values to see if the
4591 values are the same value for sorting purposes, two NULL values are
4592 considered to be the same. In other words, the comparison operator is "IS"
4593 (or "IS NOT DISTINCT FROM") and not "==".</p>
4594
4595 <p>If a virtual table implementation is unable to meet the requirements
4596 specified above, then it must not set the "orderByConsumed" flag in the
4597 <a href="#sqlite3_index_info">sqlite3_index_info</a> object or an incorrect answer may result.</p>
4598
4599 <p>A virtual table implementation is always free to return rows in any order
4600 it wants, as long as the "orderByConsumed" flag is not set. When the
4601 "orderByConsumed" flag is unset, the query planner will add extra
4602 <a href="opcode.html">bytecode</a> to ensure that the final results returned by the SQL query are
4603 ordered correctly. The use of the "orderByConsumed" flag and the
4604 sqlite3_vtab_distinct() interface is merely an optimization. Careful
4605 use of the sqlite3_vtab_distinct() interface and the "orderByConsumed"
4606 flag might help queries against a virtual table to run faster. Being
4607 overly aggressive and setting the "orderByConsumed" flag when it is not
4608 valid to do so, on the other hand, might cause SQLite to return incorrect
4609 results.
4610 </p><hr><a name="sqlite3_vtab_in"></a>
4611 <h2>Identify and handle IN constraints in xBestIndex</h2>
4612 </div>
4613 <blockquote><pre>
4614 int sqlite3_vtab_in(sqlite3_index_info*, int iCons, int bHandle);
4615 </pre></blockquote>
4616 <p>
4617 This interface may only be used from within an
4618 <a href="vtab.html#xbestindex">xBestIndex() method</a> of a <a href="vtab.html">virtual table</a> implementation.
4619 The result of invoking this interface from any other context is
4620 undefined and probably harmful.</p>
4621
4622 <p>A constraint on a virtual table of the form
4623 "<a href="lang_expr.html#in_op">column IN (...)</a>" is
4624 communicated to the xBestIndex method as a
4625 <a href="#SQLITE_INDEX_CONSTRAINT_EQ">SQLITE_INDEX_CONSTRAINT_EQ</a> constraint. If xBestIndex wants to use
4626 this constraint, it must set the corresponding
4627 aConstraintUsage[].argvIndex to a positive integer. Then, under
4628 the usual mode of handling IN operators, SQLite generates <a href="opcode.html">bytecode</a>
4629 that invokes the <a href="vtab.html#xfilter">xFilter() method</a> once for each value
4630 on the right-hand side of the IN operator. Thus the virtual table
4631 only sees a single value from the right-hand side of the IN operator
4632 at a time.</p>
4633
4634 <p>In some cases, however, it would be advantageous for the virtual
4635 table to see all values on the right-hand of the IN operator all at
4636 once. The sqlite3_vtab_in() interfaces facilitates this in two ways:</p>
4637
4638 <p><ol>
4639 <li><p>
4640 A call to sqlite3_vtab_in(P,N,-1) will return true (non-zero)
4641 if and only if the <a href="#sqlite3_index_info">P->aConstraint</a>[N] constraint
4642 is an <a href="lang_expr.html#in_op">IN operator</a> that can be processed all at once. In other words,
4643 sqlite3_vtab_in() with -1 in the third argument is a mechanism
4644 by which the virtual table can ask SQLite if all-at-once processing
4645 of the IN operator is even possible.</p>
4646
4647 <p><li><p>
4648 A call to sqlite3_vtab_in(P,N,F) with F==1 or F==0 indicates
4649 to SQLite that the virtual table does or does not want to process
4650 the IN operator all-at-once, respectively. Thus when the third
4651 parameter (F) is non-negative, this interface is the mechanism by
4652 which the virtual table tells SQLite how it wants to process the
4653 IN operator.
4654 </ol></p>
4655
4656 <p>The sqlite3_vtab_in(P,N,F) interface can be invoked multiple times
4657 within the same xBestIndex method call. For any given P,N pair,
4658 the return value from sqlite3_vtab_in(P,N,F) will always be the same
4659 within the same xBestIndex call. If the interface returns true
4660 (non-zero), that means that the constraint is an IN operator
4661 that can be processed all-at-once. If the constraint is not an IN
4662 operator or cannot be processed all-at-once, then the interface returns
4663 false.</p>
4664
4665 <p>All-at-once processing of the IN operator is selected if both of the
4666 following conditions are met:</p>
4667
4668 <p><ol>
4669 <li><p> The P->aConstraintUsage[N].argvIndex value is set to a positive
4670 integer. This is how the virtual table tells SQLite that it wants to
4671 use the N-th constraint.</p>
4672
4673 <p><li><p> The last call to sqlite3_vtab_in(P,N,F) for which F was
4674 non-negative had F>=1.
4675 </ol></p>
4676
4677 <p>If either or both of the conditions above are false, then SQLite uses
4678 the traditional one-at-a-time processing strategy for the IN constraint.
4679 If both conditions are true, then the argvIndex-th parameter to the
4680 xFilter method will be an <a href="#sqlite3_value">sqlite3_value</a> that appears to be NULL,
4681 but which can be passed to <a href="#sqlite3_vtab_in_first">sqlite3_vtab_in_first()</a> and
4682 <a href="#sqlite3_vtab_in_first">sqlite3_vtab_in_next()</a> to find all values on the right-hand side
4683 of the IN constraint.
4684 </p><hr><a name="sqlite3_vtab_nochange"></a>
4685 <h2>Determine If Virtual Table Column Access Is For UPDATE</h2>
4686 </div>
4687 <blockquote><pre>
4688 int sqlite3_vtab_nochange(sqlite3_context*);
4689 </pre></blockquote>
4690 <p>
4691 If the sqlite3_vtab_nochange(X) routine is called within the <a href="vtab.html#xcolumn">xColumn</a>
4692 method of a <a href="vtab.html">virtual table</a>, then it might return true if the
4693 column is being fetched as part of an UPDATE operation during which the
4694 column value will not change. The virtual table implementation can use
4695 this hint as permission to substitute a return value that is less
4696 expensive to compute and that the corresponding
4697 <a href="vtab.html#xupdate">xUpdate</a> method understands as a "no-change" value.</p>
4698
4699 <p>If the <a href="vtab.html#xcolumn">xColumn</a> method calls sqlite3_vtab_nochange() and finds that
4700 the column is not changed by the UPDATE statement, then the xColumn
4701 method can optionally return without setting a result, without calling
4702 any of the <a href="#sqlite3_result_blob">sqlite3_result_xxxxx() interfaces</a>.
4703 In that case, <a href="#sqlite3_value_blob">sqlite3_value_nochange(X)</a> will return true for the
4704 same column in the <a href="vtab.html#xupdate">xUpdate</a> method.</p>
4705
4706 <p>The sqlite3_vtab_nochange() routine is an optimization. Virtual table
4707 implementations should continue to give a correct answer even if the
4708 sqlite3_vtab_nochange() interface were to always return false. In the
4709 current implementation, the sqlite3_vtab_nochange() interface does always
4710 returns false for the enhanced <a href="lang_update.html#upfrom">UPDATE FROM</a> statement.
4711 </p><hr><a name="sqlite3_vtab_on_conflict"></a>
4712 <h2>Determine The Virtual Table Conflict Policy</h2>
4713 </div>
4714 <blockquote><pre>
4715 int sqlite3_vtab_on_conflict(sqlite3 *);
4716 </pre></blockquote>
4717 <p>
4718 This function may only be called from within a call to the <a href="vtab.html#xupdate">xUpdate</a> method
4719 of a <a href="vtab.html">virtual table</a> implementation for an INSERT or UPDATE operation. The
4720 value returned is one of <a href="#SQLITE_FAIL">SQLITE_ROLLBACK</a>, <a href="#SQLITE_DENY">SQLITE_IGNORE</a>, <a href="#SQLITE_FAIL">SQLITE_FAIL</a>,
4721 <a href="#SQLITE_ABORT">SQLITE_ABORT</a>, or <a href="#SQLITE_FAIL">SQLITE_REPLACE</a>, according to the <a href="lang_conflict.html">ON CONFLICT</a> mode
4722 of the SQL statement that triggered the call to the <a href="vtab.html#xupdate">xUpdate</a> method of the
4723 <a href="vtab.html">virtual table</a>.
4724 </p><hr><a name="sqlite3_vtab_rhs_value"></a>
4725 <h2>Constraint values in xBestIndex()</h2>
4726 </div>
4727 <blockquote><pre>
4728 int sqlite3_vtab_rhs_value(sqlite3_index_info*, int, sqlite3_value **ppVal);
4729 </pre></blockquote>
4730 <p>
4731 This API may only be used from within the <a href="vtab.html#xbestindex">xBestIndex method</a>
4732 of a <a href="vtab.html">virtual table</a> implementation. The result of calling this interface
4733 from outside of an xBestIndex method are undefined and probably harmful.</p>
4734
4735 <p>When the sqlite3_vtab_rhs_value(P,J,V) interface is invoked from within
4736 the <a href="vtab.html#xbestindex">xBestIndex</a> method of a <a href="vtab.html">virtual table</a> implementation, with P being
4737 a copy of the <a href="#sqlite3_index_info">sqlite3_index_info</a> object pointer passed into xBestIndex and
4738 J being a 0-based index into P->aConstraint[], then this routine
4739 attempts to set *V to the value of the right-hand operand of
4740 that constraint if the right-hand operand is known. If the
4741 right-hand operand is not known, then *V is set to a NULL pointer.
4742 The sqlite3_vtab_rhs_value(P,J,V) interface returns SQLITE_OK if
4743 and only if *V is set to a value. The sqlite3_vtab_rhs_value(P,J,V)
4744 inteface returns SQLITE_NOTFOUND if the right-hand side of the J-th
4745 constraint is not available. The sqlite3_vtab_rhs_value() interface
4746 can return a result code other than SQLITE_OK or SQLITE_NOTFOUND if
4747 something goes wrong.</p>
4748
4749 <p>The sqlite3_vtab_rhs_value() interface is usually only successful if
4750 the right-hand operand of a constraint is a literal value in the original
4751 SQL statement. If the right-hand operand is an expression or a reference
4752 to some other column or a <a href="#sqlite3_bind_blob">host parameter</a>, then sqlite3_vtab_rhs_value()
4753 will probably return <a href="#SQLITE_ABORT">SQLITE_NOTFOUND</a>.</p>
4754
4755 <p>Some constraints, such as <a href="#SQLITE_INDEX_CONSTRAINT_EQ">SQLITE_INDEX_CONSTRAINT_ISNULL</a> and
4756 <a href="#SQLITE_INDEX_CONSTRAINT_EQ">SQLITE_INDEX_CONSTRAINT_ISNOTNULL</a>, have no right-hand operand. For such
4757 constraints, sqlite3_vtab_rhs_value() always returns SQLITE_NOTFOUND.</p>
4758
4759 <p>The <a href="#sqlite3_value">sqlite3_value</a> object returned in *V is a protected sqlite3_value
4760 and remains valid for the duration of the xBestIndex method call.
4761 When xBestIndex returns, the sqlite3_value object returned by
4762 sqlite3_vtab_rhs_value() is automatically deallocated.</p>
4763
4764 <p>The "_rhs_" in the name of this routine is an abbreviation for
4765 "Right-Hand Side".
4766 </p><hr><a name="sqlite3_wal_autocheckpoint"></a>
4767 <h2>Configure an auto-checkpoint</h2>
4768 </div>
4769 <blockquote><pre>
4770 int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
4771 </pre></blockquote>
4772 <p>
4773 The <a href="#sqlite3_wal_autocheckpoint">sqlite3_wal_autocheckpoint(D,N)</a> is a wrapper around
4774 <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> that causes any database on <a href="#sqlite3">database connection</a> D
4775 to automatically <a href="wal.html#ckpt">checkpoint</a>
4776 after committing a transaction if there are N or
4777 more frames in the <a href="wal.html">write-ahead log</a> file. Passing zero or
4778 a negative value as the N parameter disables automatic
4779 checkpoints entirely.</p>
4780
4781 <p>The callback registered by this function replaces any existing callback
4782 registered using <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a>. Likewise, registering a callback
4783 using <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> disables the automatic checkpoint mechanism
4784 configured by this function.</p>
4785
4786 <p>The <a href="pragma.html#pragma_wal_autocheckpoint">wal_autocheckpoint pragma</a> can be used to invoke this interface
4787 from SQL.</p>
4788
4789 <p>Checkpoints initiated by this mechanism are
4790 <a href="#sqlite3_wal_checkpoint_v2">PASSIVE</a>.</p>
4791
4792 <p>Every new <a href="#sqlite3">database connection</a> defaults to having the auto-checkpoint
4793 enabled with a threshold of 1000 or <a href="compile.html#default_wal_autocheckpoint">SQLITE_DEFAULT_WAL_AUTOCHECKPOINT</a>
4794 pages.</p>
4795
4796 <p>The use of this interface is only necessary if the default setting
4797 is found to be suboptimal for a particular application.
4798 </p><hr><a name="sqlite3_wal_checkpoint"></a>
4799 <h2>Checkpoint a database</h2>
4800 </div>
4801 <blockquote><pre>
4802 int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
4803 </pre></blockquote>
4804 <p>
4805 The sqlite3_wal_checkpoint(D,X) is equivalent to
4806 <a href="#sqlite3_wal_checkpoint_v2">sqlite3_wal_checkpoint_v2</a>(D,X,<a href="#SQLITE_CHECKPOINT_FULL">SQLITE_CHECKPOINT_PASSIVE</a>,0,0).</p>
4807
4808 <p>In brief, sqlite3_wal_checkpoint(D,X) causes the content in the
4809 <a href="wal.html">write-ahead log</a> for database X on <a href="#sqlite3">database connection</a> D to be
4810 transferred into the database file and for the write-ahead log to
4811 be reset. See the <a href="wal.html#ckpt">checkpointing</a> documentation for addition
4812 information.</p>
4813
4814 <p>This interface used to be the only way to cause a checkpoint to
4815 occur. But then the newer and more powerful <a href="#sqlite3_wal_checkpoint_v2">sqlite3_wal_checkpoint_v2()</a>
4816 interface was added. This interface is retained for backwards
4817 compatibility and as a convenience for applications that need to manually
4818 start a callback but which do not need the full power (and corresponding
4819 complication) of <a href="#sqlite3_wal_checkpoint_v2">sqlite3_wal_checkpoint_v2()</a>.
4820 </p><hr><a name="sqlite3_wal_checkpoint_v2"></a>
4821 <h2>Checkpoint a database</h2>
4822 </div>
4823 <blockquote><pre>
4824 int sqlite3_wal_checkpoint_v2(
4825 sqlite3 *db, /* Database handle */
4826 const char *zDb, /* Name of attached database (or NULL) */
4827 int eMode, /* SQLITE_CHECKPOINT_* value */
4828 int *pnLog, /* OUT: Size of WAL log in frames */
4829 int *pnCkpt /* OUT: Total number of frames checkpointed */
4830 );
4831 </pre></blockquote>
4832 <p>
4833 The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint
4834 operation on database X of <a href="#sqlite3">database connection</a> D in mode M. Status
4835 information is written back into integers pointed to by L and C.
4836 The M parameter must be a valid <a href="#SQLITE_CHECKPOINT_FULL">checkpoint mode</a>:</p>
4837
4838 <p><dl>
4839 <dt>SQLITE_CHECKPOINT_PASSIVE<dd>
4840 Checkpoint as many frames as possible without waiting for any database
4841 readers or writers to finish, then sync the database file if all frames
4842 in the log were checkpointed. The <a href="#sqlite3_busy_handler">busy-handler callback</a>
4843 is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.
4844 On the other hand, passive mode might leave the checkpoint unfinished
4845 if there are concurrent readers or writers.</p>
4846
4847 <p><dt>SQLITE_CHECKPOINT_FULL<dd>
4848 This mode blocks (it invokes the
4849 <a href="#sqlite3_busy_handler">busy-handler callback</a>) until there is no
4850 database writer and all readers are reading from the most recent database
4851 snapshot. It then checkpoints all frames in the log file and syncs the
4852 database file. This mode blocks new database writers while it is pending,
4853 but new database readers are allowed to continue unimpeded.</p>
4854
4855 <p><dt>SQLITE_CHECKPOINT_RESTART<dd>
4856 This mode works the same way as SQLITE_CHECKPOINT_FULL with the addition
4857 that after checkpointing the log file it blocks (calls the
4858 <a href="#sqlite3_busy_handler">busy-handler callback</a>)
4859 until all readers are reading from the database file only. This ensures
4860 that the next writer will restart the log file from the beginning.
4861 Like SQLITE_CHECKPOINT_FULL, this mode blocks new
4862 database writer attempts while it is pending, but does not impede readers.</p>
4863
4864 <p><dt>SQLITE_CHECKPOINT_TRUNCATE<dd>
4865 This mode works the same way as SQLITE_CHECKPOINT_RESTART with the
4866 addition that it also truncates the log file to zero bytes just prior
4867 to a successful return.</p>
4868
4869 <p><dt>SQLITE_CHECKPOINT_NOOP<dd>
4870 This mode always checkpoints zero frames. The only reason to invoke
4871 a NOOP checkpoint is to access the values returned by
4872 sqlite3_wal_checkpoint_v2() via output parameters *pnLog and *pnCkpt.
4873 </dl></p>
4874
4875 <p>If pnLog is not NULL, then *pnLog is set to the total number of frames in
4876 the log file or to -1 if the checkpoint could not run because
4877 of an error or because the database is not in <a href="wal.html">WAL mode</a>. If pnCkpt is not
4878 NULL,then *pnCkpt is set to the total number of checkpointed frames in the
4879 log file (including any that were already checkpointed before the function
4880 was called) or to -1 if the checkpoint could not run due to an error or
4881 because the database is not in WAL mode. Note that upon successful
4882 completion of an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been
4883 truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.</p>
4884
4885 <p>All calls obtain an exclusive "checkpoint" lock on the database file. If
4886 any other process is running a checkpoint operation at the same time, the
4887 lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a
4888 busy-handler configured, it will not be invoked in this case.</p>
4889
4890 <p>The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the
4891 exclusive "writer" lock on the database file. If the writer lock cannot be
4892 obtained immediately, and a busy-handler is configured, it is invoked and
4893 the writer lock retried until either the busy-handler returns 0 or the lock
4894 is successfully obtained. The busy-handler is also invoked while waiting for
4895 database readers as described above. If the busy-handler returns 0 before
4896 the writer lock is obtained or while waiting for database readers, the
4897 checkpoint operation proceeds from that point in the same way as
4898 SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
4899 without blocking any further. SQLITE_BUSY is returned in this case.</p>
4900
4901 <p>If parameter zDb is NULL or points to a zero length string, then the
4902 specified operation is attempted on all WAL databases <a href="lang_attach.html">attached</a> to
4903 <a href="#sqlite3">database connection</a> db. In this case the
4904 values written to output parameters *pnLog and *pnCkpt are undefined. If
4905 an SQLITE_BUSY error is encountered when processing one or more of the
4906 attached WAL databases, the operation is still attempted on any remaining
4907 attached databases and SQLITE_BUSY is returned at the end. If any other
4908 error occurs while processing an attached database, processing is abandoned
4909 and the error code is returned to the caller immediately. If no error
4910 (SQLITE_BUSY or otherwise) is encountered while processing the attached
4911 databases, SQLITE_OK is returned.</p>
4912
4913 <p>If database zDb is the name of an attached database that is not in WAL
4914 mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If
4915 zDb is not NULL (or a zero length string) and is not the name of any
4916 attached database, SQLITE_ERROR is returned to the caller.</p>
4917
4918 <p>Unless it returns SQLITE_MISUSE,
4919 the sqlite3_wal_checkpoint_v2() interface
4920 sets the error information that is queried by
4921 <a href="#sqlite3_errcode">sqlite3_errcode()</a> and <a href="#sqlite3_errcode">sqlite3_errmsg()</a>.</p>
4922
4923 <p>The <a href="pragma.html#pragma_wal_checkpoint">PRAGMA wal_checkpoint</a> command can be used to invoke this interface
4924 from SQL.
4925 </p><hr><a name="sqlite3_wal_hook"></a>
4926 <h2>Write-Ahead Log Commit Hook</h2>
4927 </div>
4928 <blockquote><pre>
4929 void *sqlite3_wal_hook(
4930 sqlite3*,
4931 int(*)(void *,sqlite3*,const char*,int),
4932 void*
4933 );
4934 </pre></blockquote>
4935 <p>
4936 The <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> function is used to register a callback that
4937 is invoked each time data is committed to a database in wal mode.</p>
4938
4939 <p>The callback is invoked by SQLite after the commit has taken place and
4940 the associated write-lock on the database released, so the implementation
4941 may read, write or <a href="wal.html#ckpt">checkpoint</a> the database as required.</p>
4942
4943 <p>The first parameter passed to the callback function when it is invoked
4944 is a copy of the third parameter passed to sqlite3_wal_hook() when
4945 registering the callback. The second is a copy of the database handle.
4946 The third parameter is the name of the database that was written to -
4947 either "main" or the name of an <a href="lang_attach.html">ATTACH</a>-ed database. The fourth parameter
4948 is the number of pages currently in the write-ahead log file,
4949 including those that were just committed.</p>
4950
4951 <p>The callback function should normally return <a href="#SQLITE_ABORT">SQLITE_OK</a>. If an error
4952 code is returned, that error will propagate back up through the
4953 SQLite code base to cause the statement that provoked the callback
4954 to report an error, though the commit will have still occurred. If the
4955 callback returns <a href="#SQLITE_ABORT">SQLITE_ROW</a> or <a href="#SQLITE_ABORT">SQLITE_DONE</a>, or if it returns a value
4956 that does not correspond to any valid SQLite error code, the results
4957 are undefined.</p>
4958
4959 <p>A single database handle may have at most a single write-ahead log
4960 callback registered at one time. Calling <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a>
4961 replaces the default behavior or previously registered write-ahead
4962 log callback.</p>
4963
4964 <p>The return value is a copy of the third parameter from the
4965 previous call, if any, or 0.</p>
4966
4967 <p>The <a href="#sqlite3_wal_autocheckpoint">sqlite3_wal_autocheckpoint()</a> interface and the
4968 <a href="pragma.html#pragma_wal_autocheckpoint">wal_autocheckpoint pragma</a> both invoke <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> and
4969 will overwrite any prior <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> settings.</p>
4970
4971 <p>If a write-ahead log callback is set using this function then
4972 <a href="#sqlite3_wal_checkpoint_v2">sqlite3_wal_checkpoint_v2()</a> or <a href="pragma.html#pragma_wal_checkpoint">PRAGMA wal_checkpoint</a>
4973 should be invoked periodically to keep the write-ahead log file
4974 from growing without bound.</p>
4975
4976 <p>Passing a NULL pointer for the callback disables automatic
4977 checkpointing entirely. To re-enable the default behavior, call
4978 sqlite3_wal_autocheckpoint(db,1000) or use <a href="pragma.html#pragma_wal_checkpoint">PRAGMA wal_checkpoint</a>.
4979 </p><hr><a name="SQLITE_ABORT"></a>
4980 <h2>Result Codes</h2>
4981 </div>
4982 <blockquote><pre>
4983 #define SQLITE_OK 0 /* Successful result */
4984 /* beginning-of-error-codes */
4985 #define SQLITE_ERROR 1 /* Generic error */
4986 #define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */
4987 #define SQLITE_PERM 3 /* Access permission denied */
4988 #define SQLITE_ABORT 4 /* Callback routine requested an abort */
4989 #define SQLITE_BUSY 5 /* The database file is locked */
4990 #define SQLITE_LOCKED 6 /* A table in the database is locked */
4991 #define SQLITE_NOMEM 7 /* A malloc() failed */
4992 #define SQLITE_READONLY 8 /* Attempt to write a readonly database */
4993 #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
4994 #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
4995 #define SQLITE_CORRUPT 11 /* The database disk image is malformed */
4996 #define SQLITE_NOTFOUND 12 /* Unknown opcode in sqlite3_file_control() */
4997 #define SQLITE_FULL 13 /* Insertion failed because database is full */
4998 #define SQLITE_CANTOPEN 14 /* Unable to open the database file */
4999 #define SQLITE_PROTOCOL 15 /* Database lock protocol error */
5000 #define SQLITE_EMPTY 16 /* Internal use only */
5001 #define SQLITE_SCHEMA 17 /* The database schema changed */
5002 #define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
5003 #define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
5004 #define SQLITE_MISMATCH 20 /* Data type mismatch */
5005 #define SQLITE_MISUSE 21 /* Library used incorrectly */
5006 #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
5007 #define SQLITE_AUTH 23 /* Authorization denied */
5008 #define SQLITE_FORMAT 24 /* Not used */
5009 #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
5010 #define SQLITE_NOTADB 26 /* File opened that is not a database file */
5011 #define SQLITE_NOTICE 27 /* Notifications from sqlite3_log() */
5012 #define SQLITE_WARNING 28 /* Warnings from sqlite3_log() */
5013 #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
5014 #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
5015 /* end-of-error-codes */
5016 </pre></blockquote>
5017 <p>
5018 Many SQLite functions return an integer result code from the set shown
5019 here in order to indicate success or failure.</p>
5020
5021 <p>New error codes may be added in future versions of SQLite.</p>
5022
5023 <p>See also: <a href="#SQLITE_ABORT_ROLLBACK">extended result code definitions</a>
5024 </p><hr><a name="SQLITE_ABORT_ROLLBACK"></a>
5025 <h2>Extended Result Codes</h2>
5026 </div>
5027 <blockquote><pre>
5028 #define SQLITE_ERROR_MISSING_COLLSEQ (SQLITE_ERROR | (1&lt;&lt;8))
5029 #define SQLITE_ERROR_RETRY (SQLITE_ERROR | (2&lt;&lt;8))
5030 #define SQLITE_ERROR_SNAPSHOT (SQLITE_ERROR | (3&lt;&lt;8))
5031 #define SQLITE_ERROR_RESERVESIZE (SQLITE_ERROR | (4&lt;&lt;8))
5032 #define SQLITE_ERROR_KEY (SQLITE_ERROR | (5&lt;&lt;8))
5033 #define SQLITE_ERROR_UNABLE (SQLITE_ERROR | (6&lt;&lt;8))
5034 #define SQLITE_IOERR_READ (SQLITE_IOERR | (1&lt;&lt;8))
5035 #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2&lt;&lt;8))
5036 #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3&lt;&lt;8))
5037 #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4&lt;&lt;8))
5038 #define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5&lt;&lt;8))
5039 #define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6&lt;&lt;8))
5040 #define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7&lt;&lt;8))
5041 #define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8&lt;&lt;8))
5042 #define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9&lt;&lt;8))
5043 #define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10&lt;&lt;8))
5044 #define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11&lt;&lt;8))
5045 #define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12&lt;&lt;8))
5046 #define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13&lt;&lt;8))
5047 #define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14&lt;&lt;8))
5048 #define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15&lt;&lt;8))
5049 #define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16&lt;&lt;8))
5050 #define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17&lt;&lt;8))
5051 #define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR | (18&lt;&lt;8))
5052 #define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19&lt;&lt;8))
5053 #define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20&lt;&lt;8))
5054 #define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21&lt;&lt;8))
5055 #define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22&lt;&lt;8))
5056 #define SQLITE_IOERR_DELETE_NOENT (SQLITE_IOERR | (23&lt;&lt;8))
5057 #define SQLITE_IOERR_MMAP (SQLITE_IOERR | (24&lt;&lt;8))
5058 #define SQLITE_IOERR_GETTEMPPATH (SQLITE_IOERR | (25&lt;&lt;8))
5059 #define SQLITE_IOERR_CONVPATH (SQLITE_IOERR | (26&lt;&lt;8))
5060 #define SQLITE_IOERR_VNODE (SQLITE_IOERR | (27&lt;&lt;8))
5061 #define SQLITE_IOERR_AUTH (SQLITE_IOERR | (28&lt;&lt;8))
5062 #define SQLITE_IOERR_BEGIN_ATOMIC (SQLITE_IOERR | (29&lt;&lt;8))
5063 #define SQLITE_IOERR_COMMIT_ATOMIC (SQLITE_IOERR | (30&lt;&lt;8))
5064 #define SQLITE_IOERR_ROLLBACK_ATOMIC (SQLITE_IOERR | (31&lt;&lt;8))
5065 #define SQLITE_IOERR_DATA (SQLITE_IOERR | (32&lt;&lt;8))
5066 #define SQLITE_IOERR_CORRUPTFS (SQLITE_IOERR | (33&lt;&lt;8))
5067 #define SQLITE_IOERR_IN_PAGE (SQLITE_IOERR | (34&lt;&lt;8))
5068 #define SQLITE_IOERR_BADKEY (SQLITE_IOERR | (35&lt;&lt;8))
5069 #define SQLITE_IOERR_CODEC (SQLITE_IOERR | (36&lt;&lt;8))
5070 #define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1&lt;&lt;8))
5071 #define SQLITE_LOCKED_VTAB (SQLITE_LOCKED | (2&lt;&lt;8))
5072 #define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1&lt;&lt;8))
5073 #define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2&lt;&lt;8))
5074 #define SQLITE_BUSY_TIMEOUT (SQLITE_BUSY | (3&lt;&lt;8))
5075 #define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1&lt;&lt;8))
5076 #define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2&lt;&lt;8))
5077 #define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3&lt;&lt;8))
5078 #define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4&lt;&lt;8))
5079 #define SQLITE_CANTOPEN_DIRTYWAL (SQLITE_CANTOPEN | (5&lt;&lt;8)) /* Not Used */
5080 #define SQLITE_CANTOPEN_SYMLINK (SQLITE_CANTOPEN | (6&lt;&lt;8))
5081 #define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1&lt;&lt;8))
5082 #define SQLITE_CORRUPT_SEQUENCE (SQLITE_CORRUPT | (2&lt;&lt;8))
5083 #define SQLITE_CORRUPT_INDEX (SQLITE_CORRUPT | (3&lt;&lt;8))
5084 #define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1&lt;&lt;8))
5085 #define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2&lt;&lt;8))
5086 #define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3&lt;&lt;8))
5087 #define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4&lt;&lt;8))
5088 #define SQLITE_READONLY_CANTINIT (SQLITE_READONLY | (5&lt;&lt;8))
5089 #define SQLITE_READONLY_DIRECTORY (SQLITE_READONLY | (6&lt;&lt;8))
5090 #define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2&lt;&lt;8))
5091 #define SQLITE_CONSTRAINT_CHECK (SQLITE_CONSTRAINT | (1&lt;&lt;8))
5092 #define SQLITE_CONSTRAINT_COMMITHOOK (SQLITE_CONSTRAINT | (2&lt;&lt;8))
5093 #define SQLITE_CONSTRAINT_FOREIGNKEY (SQLITE_CONSTRAINT | (3&lt;&lt;8))
5094 #define SQLITE_CONSTRAINT_FUNCTION (SQLITE_CONSTRAINT | (4&lt;&lt;8))
5095 #define SQLITE_CONSTRAINT_NOTNULL (SQLITE_CONSTRAINT | (5&lt;&lt;8))
5096 #define SQLITE_CONSTRAINT_PRIMARYKEY (SQLITE_CONSTRAINT | (6&lt;&lt;8))
5097 #define SQLITE_CONSTRAINT_TRIGGER (SQLITE_CONSTRAINT | (7&lt;&lt;8))
5098 #define SQLITE_CONSTRAINT_UNIQUE (SQLITE_CONSTRAINT | (8&lt;&lt;8))
5099 #define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9&lt;&lt;8))
5100 #define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10&lt;&lt;8))
5101 #define SQLITE_CONSTRAINT_PINNED (SQLITE_CONSTRAINT |(11&lt;&lt;8))
5102 #define SQLITE_CONSTRAINT_DATATYPE (SQLITE_CONSTRAINT |(12&lt;&lt;8))
5103 #define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1&lt;&lt;8))
5104 #define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2&lt;&lt;8))
5105 #define SQLITE_NOTICE_RBU (SQLITE_NOTICE | (3&lt;&lt;8))
5106 #define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1&lt;&lt;8))
5107 #define SQLITE_AUTH_USER (SQLITE_AUTH | (1&lt;&lt;8))
5108 #define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1&lt;&lt;8))
5109 #define SQLITE_OK_SYMLINK (SQLITE_OK | (2&lt;&lt;8)) /* internal only */
5110 </pre></blockquote>
5111 <p>
5112 In its default configuration, SQLite API routines return one of 30 integer
5113 <a href="rescode.html">result codes</a>. However, experience has shown that many of
5114 these result codes are too coarse-grained. They do not provide as
5115 much information about problems as programmers might like. In an effort to
5116 address this, newer versions of SQLite (version 3.3.8 2006-10-09
5117 and later) include
5118 support for additional result codes that provide more detailed information
5119 about errors. These <a href="rescode.html#extrc">extended result codes</a> are enabled or disabled
5120 on a per database connection basis using the
5121 <a href="#sqlite3_extended_result_codes">sqlite3_extended_result_codes()</a> API. Or, the extended code for
5122 the most recent error can be obtained using
5123 <a href="#sqlite3_errcode">sqlite3_extended_errcode()</a>.
5124 </p><hr><a name="SQLITE_ACCESS_EXISTS"></a>
5125 <h2>Flags for the xAccess VFS method</h2>
5126 </div>
5127 <blockquote><pre>
5128 #define SQLITE_ACCESS_EXISTS 0
5129 #define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */
5130 #define SQLITE_ACCESS_READ 2 /* Unused */
5131 </pre></blockquote>
5132 <p>
5133 These integer constants can be used as the third parameter to
5134 the xAccess method of an <a href="#sqlite3_vfs">sqlite3_vfs</a> object. They determine
5135 what kind of permissions the xAccess method is looking for.
5136 With SQLITE_ACCESS_EXISTS, the xAccess method
5137 simply checks whether the file exists.
5138 With SQLITE_ACCESS_READWRITE, the xAccess method
5139 checks whether the named directory is both readable and writable
5140 (in other words, if files can be added, removed, and renamed within
5141 the directory).
5142 The SQLITE_ACCESS_READWRITE constant is currently used only by the
5143 <a href="pragma.html#pragma_temp_store_directory">temp_store_directory pragma</a>, though this could change in a future
5144 release of SQLite.
5145 With SQLITE_ACCESS_READ, the xAccess method
5146 checks whether the file is readable. The SQLITE_ACCESS_READ constant is
5147 currently unused, though it might be used in a future release of
5148 SQLite.
5149 </p><hr><a name="SQLITE_ALTER_TABLE"></a>
5150 <h2>Authorizer Action Codes</h2>
5151 </div>
5152 <blockquote><pre>
5153 /******************************************* 3rd ************ 4th ***********/
5154 #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
5155 #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
5156 #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
5157 #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
5158 #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
5159 #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
5160 #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
5161 #define SQLITE_CREATE_VIEW 8 /* View Name NULL */
5162 #define SQLITE_DELETE 9 /* Table Name NULL */
5163 #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
5164 #define SQLITE_DROP_TABLE 11 /* Table Name NULL */
5165 #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
5166 #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
5167 #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
5168 #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
5169 #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
5170 #define SQLITE_DROP_VIEW 17 /* View Name NULL */
5171 #define SQLITE_INSERT 18 /* Table Name NULL */
5172 #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
5173 #define SQLITE_READ 20 /* Table Name Column Name */
5174 #define SQLITE_SELECT 21 /* NULL NULL */
5175 #define SQLITE_TRANSACTION 22 /* Operation NULL */
5176 #define SQLITE_UPDATE 23 /* Table Name Column Name */
5177 #define SQLITE_ATTACH 24 /* Filename NULL */
5178 #define SQLITE_DETACH 25 /* Database Name NULL */
5179 #define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
5180 #define SQLITE_REINDEX 27 /* Index Name NULL */
5181 #define SQLITE_ANALYZE 28 /* Table Name NULL */
5182 #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
5183 #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
5184 #define SQLITE_FUNCTION 31 /* NULL Function Name */
5185 #define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */
5186 #define SQLITE_COPY 0 /* No longer used */
5187 #define SQLITE_RECURSIVE 33 /* NULL NULL */
5188 </pre></blockquote>
5189 <p>
5190 The <a href="#sqlite3_set_authorizer">sqlite3_set_authorizer()</a> interface registers a callback function
5191 that is invoked to authorize certain SQL statement actions. The
5192 second parameter to the callback is an integer code that specifies
5193 what action is being authorized. These are the integer action codes that
5194 the authorizer callback may be passed.</p>
5195
5196 <p>These action code values signify what kind of operation is to be
5197 authorized. The 3rd and 4th parameters to the authorization
5198 callback function will be parameters or NULL depending on which of these
5199 codes is used as the second parameter. The 5th parameter to the
5200 authorizer callback is the name of the database ("main", "temp",
5201 etc.) if applicable. The 6th parameter to the authorizer callback
5202 is the name of the inner-most trigger or view that is responsible for
5203 the access attempt or NULL if this access attempt is directly from
5204 top-level SQL code.
5205 </p><hr><a name="SQLITE_ANY"></a>
5206 <h2>Text Encodings</h2>
5207 </div>
5208 <blockquote><pre>
5209 #define SQLITE_UTF8 1 /* IMP: R-37514-35566 */
5210 #define SQLITE_UTF16LE 2 /* IMP: R-03371-37637 */
5211 #define SQLITE_UTF16BE 3 /* IMP: R-51971-34154 */
5212 #define SQLITE_UTF16 4 /* Use native byte order */
5213 #define SQLITE_ANY 5 /* Deprecated */
5214 #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
5215 #define SQLITE_UTF8_ZT 16 /* Zero-terminated UTF8 */
5216 </pre></blockquote>
5217 <p>
5218 These constants define integer codes that represent the various
5219 text encodings supported by SQLite.</p>
5220
5221 <p><dl>
5222 <a name="sqliteutf8"></a>
5223 <dt>SQLITE_UTF8</dt><dd>Text is encoding as UTF-8</dd></p>
5224
5225 <p><a name="sqliteutf16le"></a>
5226 <dt>SQLITE_UTF16LE</dt><dd>Text is encoding as UTF-16
5227 with each code point being expressed "little endian" - the least significant
5228 byte first. This is the usual encoding, for example on Windows.</dd></p>
5229
5230 <p><a name="sqliteutf16be"></a>
5231 <dt>SQLITE_UTF16BE</dt><dd>Text is encoding as UTF-16
5232 with each code point being expressed "big endian" - the most significant
5233 byte first. This encoding is less common, but is still sometimes seen,
5234 specially on older systems.</p>
5235
5236 <p><a name="sqliteutf16"></a>
5237 <dt>SQLITE_UTF16</dt><dd>Text is encoding as UTF-16
5238 with each code point being expressed either little endian or as big
5239 endian, according to the native endianness of the host computer.</p>
5240
5241 <p><a name="sqliteany"></a>
5242 <dt>SQLITE_ANY</dt><dd>This encoding value may only be used
5243 to declare the preferred text for <a href="appfunc.html">application-defined SQL functions</a>
5244 created using <a href="#sqlite3_create_function">sqlite3_create_function()</a> and similar. If the preferred
5245 encoding (the 4th parameter to sqlite3_create_function() - the eTextRep
5246 parameter) is SQLITE_ANY, that indicates that the function does not have
5247 a preference regarding the text encoding of its parameters and can take
5248 any text encoding that the SQLite core find convenient to supply. This
5249 option is deprecated. Please do not use it in new applications.</p>
5250
5251 <p><a name="sqliteutf16aligned"></a>
5252 <dt>SQLITE_UTF16_ALIGNED</dt><dd>This encoding
5253 value may be used as the 3rd parameter (the eTextRep parameter) to
5254 <a href="#sqlite3_create_collation">sqlite3_create_collation()</a> and similar. This encoding value means
5255 that the application-defined collating sequence created expects its
5256 input strings to be in UTF16 in native byte order, and that the start
5257 of the strings must be aligned to a 2-byte boundary.</p>
5258
5259 <p><a name="sqliteutf8zt"></a>
5260 <dt>SQLITE_UTF8_ZT</dt><dd>This option can only be
5261 used to specify the text encoding to strings input to
5262 <a href="#sqlite3_result_blob">sqlite3_result_text64()</a> and <a href="#sqlite3_bind_blob">sqlite3_bind_text64()</a>.
5263 The SQLITE_UTF8_ZT encoding means that the input string (call it "z")
5264 is UTF-8 encoded and that it is zero-terminated. If the length parameter
5265 (call it "n") is non-negative, this encoding option means that the caller
5266 guarantees that z array contains at least n+1 bytes and that the z&#91;n&#93;
5267 byte has a value of zero.
5268 This option gives the same output as SQLITE_UTF8, but can be more efficient
5269 by avoiding the need to make a copy of the input string, in some cases.
5270 However, if z is allocated to hold fewer than n+1 bytes or if the
5271 z&#91;n&#93; byte is not zero, undefined behavior may result.
5272 </dl>
5273 </p><hr><a name="SQLITE_BLOB"></a>
5274 <h2>Fundamental Datatypes</h2>
5275 </div>
5276 <blockquote><pre>
5277 #define SQLITE_INTEGER 1
5278 #define SQLITE_FLOAT 2
5279 #define SQLITE_BLOB 4
5280 #define SQLITE_NULL 5
5281 #ifdef SQLITE_TEXT
5282 # undef SQLITE_TEXT
5283 #else
5284 # define SQLITE_TEXT 3
5285 #endif
5286 #define SQLITE3_TEXT 3
5287 </pre></blockquote>
5288 <p>
5289 Every value in SQLite has one of five fundamental datatypes:</p>
5290
5291 <p><ul>
5292 <li> 64-bit signed integer
5293 <li> 64-bit IEEE floating point number
5294 <li> string
5295 <li> BLOB
5296 <li> NULL
5297 </ul></p>
5298
5299 <p>These constants are codes for each of those types.</p>
5300
5301 <p>Note that the SQLITE_TEXT constant was also used in SQLite version 2
5302 for a completely different meaning. Software that links against both
5303 SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
5304 SQLITE_TEXT.
5305 </p><hr><a name="SQLITE_CARRAY_BLOB"></a>
5306 <h2>Datatypes for the CARRAY table-valued function</h2>
5307 </div>
5308 <blockquote><pre>
5309 #define SQLITE_CARRAY_INT32 0 /* Data is 32-bit signed integers */
5310 #define SQLITE_CARRAY_INT64 1 /* Data is 64-bit signed integers */
5311 #define SQLITE_CARRAY_DOUBLE 2 /* Data is doubles */
5312 #define SQLITE_CARRAY_TEXT 3 /* Data is char* */
5313 #define SQLITE_CARRAY_BLOB 4 /* Data is struct iovec */
5314 </pre></blockquote>
5315 <p>
5316 The fifth argument to the <a href="#sqlite3_carray_bind">sqlite3_carray_bind()</a> interface musts be
5317 one of the following constants, to specify the datatype of the array
5318 that is being bound into the <a href="carray.html">carray table-valued function</a>.
5319 </p><hr><a name="SQLITE_CHECKPOINT_FULL"></a>
5320 <h2>Checkpoint Mode Values</h2>
5321 </div>
5322 <blockquote><pre>
5323 #define SQLITE_CHECKPOINT_NOOP -1 /* Do no work at all */
5324 #define SQLITE_CHECKPOINT_PASSIVE 0 /* Do as much as possible w/o blocking */
5325 #define SQLITE_CHECKPOINT_FULL 1 /* Wait for writers, then checkpoint */
5326 #define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for readers */
5327 #define SQLITE_CHECKPOINT_TRUNCATE 3 /* Like RESTART but also truncate WAL */
5328 </pre></blockquote>
5329 <p>
5330 These constants define all valid values for the "checkpoint mode" passed
5331 as the third parameter to the <a href="#sqlite3_wal_checkpoint_v2">sqlite3_wal_checkpoint_v2()</a> interface.
5332 See the <a href="#sqlite3_wal_checkpoint_v2">sqlite3_wal_checkpoint_v2()</a> documentation for details on the
5333 meaning of each of these checkpoint modes.
5334 </p><hr><a name="SQLITE_CONFIG_COVERING_INDEX_SCAN"></a>
5335 <h2>Configuration Options</h2>
5336 </div>
5337 <blockquote><pre>
5338 #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
5339 #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
5340 #define SQLITE_CONFIG_SERIALIZED 3 /* nil */
5341 #define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
5342 #define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
5343 #define SQLITE_CONFIG_SCRATCH 6 /* No longer used */
5344 #define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
5345 #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
5346 #define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
5347 #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
5348 #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
5349 /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
5350 #define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
5351 #define SQLITE_CONFIG_PCACHE 14 /* no-op */
5352 #define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
5353 #define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
5354 #define SQLITE_CONFIG_URI 17 /* int */
5355 #define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */
5356 #define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */
5357 #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */
5358 #define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */
5359 #define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */
5360 #define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */
5361 #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */
5362 #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */
5363 #define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */
5364 #define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */
5365 #define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */
5366 #define SQLITE_CONFIG_MEMDB_MAXSIZE 29 /* sqlite3_int64 */
5367 #define SQLITE_CONFIG_ROWID_IN_VIEW 30 /* int* */
5368 </pre></blockquote>
5369 <p>
5370 These constants are the available integer configuration options that
5371 can be passed as the first argument to the <a href="#sqlite3_config">sqlite3_config()</a> interface.</p>
5372
5373 <p>Most of the configuration options for sqlite3_config()
5374 will only work if invoked prior to <a href="#sqlite3_initialize">sqlite3_initialize()</a> or after
5375 <a href="#sqlite3_initialize">sqlite3_shutdown()</a>. The few exceptions to this rule are called
5376 "anytime configuration options".
5377 Calling <a href="#sqlite3_config">sqlite3_config()</a> with a first argument that is not an
5378 anytime configuration option in between calls to <a href="#sqlite3_initialize">sqlite3_initialize()</a> and
5379 <a href="#sqlite3_initialize">sqlite3_shutdown()</a> is a no-op that returns SQLITE_MISUSE.</p>
5380
5381 <p>The set of anytime configuration options can change (by insertions
5382 and/or deletions) from one release of SQLite to the next.
5383 As of SQLite version 3.42.0, the complete set of anytime configuration
5384 options is:
5385 <ul>
5386 <li> SQLITE_CONFIG_LOG
5387 <li> SQLITE_CONFIG_PCACHE_HDRSZ
5388 </ul></p>
5389
5390 <p>New configuration options may be added in future releases of SQLite.
5391 Existing configuration options might be discontinued. Applications
5392 should check the return code from <a href="#sqlite3_config">sqlite3_config()</a> to make sure that
5393 the call worked. The <a href="#sqlite3_config">sqlite3_config()</a> interface will return a
5394 non-zero <a href="rescode.html">error code</a> if a discontinued or unsupported configuration option
5395 is invoked.</p>
5396
5397 <p><dl>
5398 <a name="sqliteconfigsinglethread"></a>
5399 <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
5400 <dd>There are no arguments to this option. This option sets the
5401 <a href="threadsafe.html">threading mode</a> to Single-thread. In other words, it disables
5402 all mutexing and puts SQLite into a mode where it can only be used
5403 by a single thread. If SQLite is compiled with
5404 the <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
5405 it is not possible to change the <a href="threadsafe.html">threading mode</a> from its default
5406 value of Single-thread and so <a href="#sqlite3_config">sqlite3_config()</a> will return
5407 <a href="#SQLITE_ABORT">SQLITE_ERROR</a> if called with the SQLITE_CONFIG_SINGLETHREAD
5408 configuration option.</dd></p>
5409
5410 <p><a name="sqliteconfigmultithread"></a>
5411 <dt>SQLITE_CONFIG_MULTITHREAD</dt>
5412 <dd>There are no arguments to this option. This option sets the
5413 <a href="threadsafe.html">threading mode</a> to Multi-thread. In other words, it disables
5414 mutexing on <a href="#sqlite3">database connection</a> and <a href="#sqlite3_stmt">prepared statement</a> objects.
5415 The application is responsible for serializing access to
5416 <a href="#sqlite3">database connections</a> and <a href="#sqlite3_stmt">prepared statements</a>. But other mutexes
5417 are enabled so that SQLite will be safe to use in a multi-threaded
5418 environment as long as no two threads attempt to use the same
5419 <a href="#sqlite3">database connection</a> at the same time. If SQLite is compiled with
5420 the <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
5421 it is not possible to set the Multi-thread <a href="threadsafe.html">threading mode</a> and
5422 <a href="#sqlite3_config">sqlite3_config()</a> will return <a href="#SQLITE_ABORT">SQLITE_ERROR</a> if called with the
5423 SQLITE_CONFIG_MULTITHREAD configuration option.</dd></p>
5424
5425 <p><a name="sqliteconfigserialized"></a>
5426 <dt>SQLITE_CONFIG_SERIALIZED</dt>
5427 <dd>There are no arguments to this option. This option sets the
5428 <a href="threadsafe.html">threading mode</a> to Serialized. In other words, this option enables
5429 all mutexes including the recursive
5430 mutexes on <a href="#sqlite3">database connection</a> and <a href="#sqlite3_stmt">prepared statement</a> objects.
5431 In this mode (which is the default when SQLite is compiled with
5432 <a href="compile.html#threadsafe">SQLITE_THREADSAFE=1</a>) the SQLite library will itself serialize access
5433 to <a href="#sqlite3">database connections</a> and <a href="#sqlite3_stmt">prepared statements</a> so that the
5434 application is free to use the same <a href="#sqlite3">database connection</a> or the
5435 same <a href="#sqlite3_stmt">prepared statement</a> in different threads at the same time.
5436 If SQLite is compiled with
5437 the <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
5438 it is not possible to set the Serialized <a href="threadsafe.html">threading mode</a> and
5439 <a href="#sqlite3_config">sqlite3_config()</a> will return <a href="#SQLITE_ABORT">SQLITE_ERROR</a> if called with the
5440 SQLITE_CONFIG_SERIALIZED configuration option.</dd></p>
5441
5442 <p><a name="sqliteconfigmalloc"></a>
5443 <dt>SQLITE_CONFIG_MALLOC</dt>
5444 <dd> The SQLITE_CONFIG_MALLOC option takes a single argument which is
5445 a pointer to an instance of the <a href="#sqlite3_mem_methods">sqlite3_mem_methods</a> structure.
5446 The argument specifies
5447 alternative low-level memory allocation routines to be used in place of
5448 the memory allocation routines built into SQLite. SQLite makes
5449 its own private copy of the content of the <a href="#sqlite3_mem_methods">sqlite3_mem_methods</a> structure
5450 before the <a href="#sqlite3_config">sqlite3_config()</a> call returns.</dd></p>
5451
5452 <p><a name="sqliteconfiggetmalloc"></a>
5453 <dt>SQLITE_CONFIG_GETMALLOC</dt>
5454 <dd> The SQLITE_CONFIG_GETMALLOC option takes a single argument which
5455 is a pointer to an instance of the <a href="#sqlite3_mem_methods">sqlite3_mem_methods</a> structure.
5456 The <a href="#sqlite3_mem_methods">sqlite3_mem_methods</a>
5457 structure is filled with the currently defined memory allocation routines.
5458 This option can be used to overload the default memory allocation
5459 routines with a wrapper that simulates memory allocation failure or
5460 tracks memory usage, for example. </dd></p>
5461
5462 <p><a name="sqliteconfigsmallmalloc"></a>
5463 <dt>SQLITE_CONFIG_SMALL_MALLOC</dt>
5464 <dd> The SQLITE_CONFIG_SMALL_MALLOC option takes a single argument of
5465 type int, interpreted as a boolean, which if true provides a hint to
5466 SQLite that it should avoid large memory allocations if possible.
5467 SQLite will run faster if it is free to make large memory allocations,
5468 but some applications might prefer to run slower in exchange for
5469 guarantees about memory fragmentation that are possible if large
5470 allocations are avoided. This hint is normally off.
5471 </dd></p>
5472
5473 <p><a name="sqliteconfigmemstatus"></a>
5474 <dt>SQLITE_CONFIG_MEMSTATUS</dt>
5475 <dd> The SQLITE_CONFIG_MEMSTATUS option takes a single argument of type int,
5476 interpreted as a boolean, which enables or disables the collection of
5477 memory allocation statistics. When memory allocation statistics are
5478 disabled, the following SQLite interfaces become non-operational:
5479 <ul>
5480 <li> <a href="#sqlite3_hard_heap_limit64">sqlite3_hard_heap_limit64()</a>
5481 <li> <a href="#sqlite3_memory_highwater">sqlite3_memory_used()</a>
5482 <li> <a href="#sqlite3_memory_highwater">sqlite3_memory_highwater()</a>
5483 <li> <a href="#sqlite3_hard_heap_limit64">sqlite3_soft_heap_limit64()</a>
5484 <li> <a href="#sqlite3_status">sqlite3_status64()</a>
5485 </ul>
5486 Memory allocation statistics are enabled by default unless SQLite is
5487 compiled with <a href="compile.html#default_memstatus">SQLITE_DEFAULT_MEMSTATUS</a>=0 in which case memory
5488 allocation statistics are disabled by default.
5489 </dd></p>
5490
5491 <p><a name="sqliteconfigscratch"></a>
5492 <dt>SQLITE_CONFIG_SCRATCH</dt>
5493 <dd> The SQLITE_CONFIG_SCRATCH option is no longer used.
5494 </dd></p>
5495
5496 <p><a name="sqliteconfigpagecache"></a>
5497 <dt>SQLITE_CONFIG_PAGECACHE</dt>
5498 <dd> The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
5499 that SQLite can use for the database page cache with the default page
5500 cache implementation.
5501 This configuration option is a no-op if an application-defined page
5502 cache implementation is loaded using the <a href="#sqliteconfigpcache2">SQLITE_CONFIG_PCACHE2</a>.
5503 There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
5504 8-byte aligned memory (pMem), the size of each page cache line (sz),
5505 and the number of cache lines (N).
5506 The sz argument should be the size of the largest database page
5507 (a power of two between 512 and 65536) plus some extra bytes for each
5508 page header. The number of extra bytes needed by the page header
5509 can be determined using <a href="#sqliteconfigpcachehdrsz">SQLITE_CONFIG_PCACHE_HDRSZ</a>.
5510 It is harmless, apart from the wasted memory,
5511 for the sz parameter to be larger than necessary. The pMem
5512 argument must be either a NULL pointer or a pointer to an 8-byte
5513 aligned block of memory of at least sz*N bytes, otherwise
5514 subsequent behavior is undefined.
5515 When pMem is not NULL, SQLite will strive to use the memory provided
5516 to satisfy page cache needs, falling back to <a href="#sqlite3_free">sqlite3_malloc()</a> if
5517 a page cache line is larger than sz bytes or if all of the pMem buffer
5518 is exhausted.
5519 If pMem is NULL and N is non-zero, then each database connection
5520 does an initial bulk allocation for page cache memory
5521 from <a href="#sqlite3_free">sqlite3_malloc()</a> sufficient for N cache lines if N is positive or
5522 of -1024*N bytes if N is negative. If additional
5523 page cache memory is needed beyond what is provided by the initial
5524 allocation, then SQLite goes to <a href="#sqlite3_free">sqlite3_malloc()</a> separately for each
5525 additional cache line. </dd></p>
5526
5527 <p><a name="sqliteconfigheap"></a>
5528 <dt>SQLITE_CONFIG_HEAP</dt>
5529 <dd> The SQLITE_CONFIG_HEAP option specifies a static memory buffer
5530 that SQLite will use for all of its dynamic memory allocation needs
5531 beyond those provided for by <a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>.
5532 The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
5533 with either <a href="compile.html#enable_memsys3">SQLITE_ENABLE_MEMSYS3</a> or <a href="compile.html#enable_memsys5">SQLITE_ENABLE_MEMSYS5</a> and returns
5534 <a href="#SQLITE_ABORT">SQLITE_ERROR</a> if invoked otherwise.
5535 There are three arguments to SQLITE_CONFIG_HEAP:
5536 An 8-byte aligned pointer to the memory,
5537 the number of bytes in the memory buffer, and the minimum allocation size.
5538 If the first pointer (the memory pointer) is NULL, then SQLite reverts
5539 to using its default memory allocator (the system malloc() implementation),
5540 undoing any prior invocation of <a href="#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a>. If the
5541 memory pointer is not NULL then the alternative memory
5542 allocator is engaged to handle all of SQLites memory allocation needs.
5543 The first pointer (the memory pointer) must be aligned to an 8-byte
5544 boundary or subsequent behavior of SQLite will be undefined.
5545 The minimum allocation size is capped at 2**12. Reasonable values
5546 for the minimum allocation size are 2**5 through 2**8.</dd></p>
5547
5548 <p><a name="sqliteconfigmutex"></a>
5549 <dt>SQLITE_CONFIG_MUTEX</dt>
5550 <dd> The SQLITE_CONFIG_MUTEX option takes a single argument which is a
5551 pointer to an instance of the <a href="#sqlite3_mutex_methods">sqlite3_mutex_methods</a> structure.
5552 The argument specifies alternative low-level mutex routines to be used
5553 in place of the mutex routines built into SQLite. SQLite makes a copy of
5554 the content of the <a href="#sqlite3_mutex_methods">sqlite3_mutex_methods</a> structure before the call to
5555 <a href="#sqlite3_config">sqlite3_config()</a> returns. If SQLite is compiled with
5556 the <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
5557 the entire mutexing subsystem is omitted from the build and hence calls to
5558 <a href="#sqlite3_config">sqlite3_config()</a> with the SQLITE_CONFIG_MUTEX configuration option will
5559 return <a href="#SQLITE_ABORT">SQLITE_ERROR</a>.</dd></p>
5560
5561 <p><a name="sqliteconfiggetmutex"></a>
5562 <dt>SQLITE_CONFIG_GETMUTEX</dt>
5563 <dd> The SQLITE_CONFIG_GETMUTEX option takes a single argument which
5564 is a pointer to an instance of the <a href="#sqlite3_mutex_methods">sqlite3_mutex_methods</a> structure. The
5565 <a href="#sqlite3_mutex_methods">sqlite3_mutex_methods</a>
5566 structure is filled with the currently defined mutex routines.
5567 This option can be used to overload the default mutex allocation
5568 routines with a wrapper used to track mutex usage for performance
5569 profiling or testing, for example. If SQLite is compiled with
5570 the <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
5571 the entire mutexing subsystem is omitted from the build and hence calls to
5572 <a href="#sqlite3_config">sqlite3_config()</a> with the SQLITE_CONFIG_GETMUTEX configuration option will
5573 return <a href="#SQLITE_ABORT">SQLITE_ERROR</a>.</dd></p>
5574
5575 <p><a name="sqliteconfiglookaside"></a>
5576 <dt>SQLITE_CONFIG_LOOKASIDE</dt>
5577 <dd> The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine
5578 the default size of <a href="malloc.html#lookaside">lookaside memory</a> on each <a href="#sqlite3">database connection</a>.
5579 The first argument is the
5580 size of each lookaside buffer slot ("sz") and the second is the number of
5581 slots allocated to each database connection ("cnt").
5582 SQLITE_CONFIG_LOOKASIDE sets the <i>default</i> lookaside size.
5583 The <a href="#sqlitedbconfiglookaside">SQLITE_DBCONFIG_LOOKASIDE</a> option to <a href="#sqlite3_db_config">sqlite3_db_config()</a> can
5584 be used to change the lookaside configuration on individual connections.
5585 The <a href="compile.html#default_lookaside">-DSQLITE_DEFAULT_LOOKASIDE</a> option can be used to change the
5586 default lookaside configuration at compile-time.
5587 </dd></p>
5588
5589 <p><a name="sqliteconfigpcache2"></a>
5590 <dt>SQLITE_CONFIG_PCACHE2</dt>
5591 <dd> The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
5592 a pointer to an <a href="#sqlite3_pcache_methods2">sqlite3_pcache_methods2</a> object. This object specifies
5593 the interface to a custom page cache implementation.
5594 SQLite makes a copy of the <a href="#sqlite3_pcache_methods2">sqlite3_pcache_methods2</a> object.</dd></p>
5595
5596 <p><a name="sqliteconfiggetpcache2"></a>
5597 <dt>SQLITE_CONFIG_GETPCACHE2</dt>
5598 <dd> The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
5599 is a pointer to an <a href="#sqlite3_pcache_methods2">sqlite3_pcache_methods2</a> object. SQLite copies off
5600 the current page cache implementation into that object. </dd></p>
5601
5602 <p><a name="sqliteconfiglog"></a>
5603 <dt>SQLITE_CONFIG_LOG</dt>
5604 <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
5605 global <a href="errlog.html">error log</a>.
5606 (The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
5607 function with a call signature of void(*)(void*,int,const char*),
5608 and a pointer to void. If the function pointer is not NULL, it is
5609 invoked by <a href="#sqlite3_log">sqlite3_log()</a> to process each logging event. If the
5610 function pointer is NULL, the <a href="#sqlite3_log">sqlite3_log()</a> interface becomes a no-op.
5611 The void pointer that is the second argument to SQLITE_CONFIG_LOG is
5612 passed through as the first parameter to the application-defined logger
5613 function whenever that function is invoked. The second parameter to
5614 the logger function is a copy of the first parameter to the corresponding
5615 <a href="#sqlite3_log">sqlite3_log()</a> call and is intended to be a <a href="rescode.html">result code</a> or an
5616 <a href="rescode.html#extrc">extended result code</a>. The third parameter passed to the logger is
5617 a log message after formatting via <a href="#sqlite3_mprintf">sqlite3_snprintf()</a>.
5618 The SQLite logging interface is not reentrant; the logger function
5619 supplied by the application must not invoke any SQLite interface.
5620 In a multi-threaded application, the application-defined logger
5621 function must be threadsafe. </dd></p>
5622
5623 <p><a name="sqliteconfiguri"></a>
5624 <dt>SQLITE_CONFIG_URI
5625 <dd>The SQLITE_CONFIG_URI option takes a single argument of type int.
5626 If non-zero, then URI handling is globally enabled. If the parameter is zero,
5627 then URI handling is globally disabled. If URI handling is globally
5628 enabled, all filenames passed to <a href="#sqlite3_open">sqlite3_open()</a>, <a href="#sqlite3_open">sqlite3_open_v2()</a>,
5629 <a href="#sqlite3_open">sqlite3_open16()</a> or
5630 specified as part of <a href="lang_attach.html">ATTACH</a> commands are interpreted as URIs, regardless
5631 of whether or not the <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_URI</a> flag is set when the database
5632 connection is opened. If it is globally disabled, filenames are
5633 only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
5634 database connection is opened. By default, URI handling is globally
5635 disabled. The default value may be changed by compiling with the
5636 <a href="compile.html#use_uri">SQLITE_USE_URI</a> symbol defined.</p>
5637
5638 <p><a name="sqliteconfigcoveringindexscan"></a>
5639 <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
5640 <dd>The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
5641 argument which is interpreted as a boolean in order to enable or disable
5642 the use of covering indices for full table scans in the query optimizer.
5643 The default setting is determined
5644 by the <a href="compile.html#allow_covering_index_scan">SQLITE_ALLOW_COVERING_INDEX_SCAN</a> compile-time option, or is "on"
5645 if that compile-time option is omitted.
5646 The ability to disable the use of covering indices for full table scans
5647 is because some incorrectly coded legacy applications might malfunction
5648 when the optimization is enabled. Providing the ability to
5649 disable the optimization allows the older, buggy application code to work
5650 without change even with newer versions of SQLite.</p>
5651
5652 <p><a name="sqliteconfigpcache"></a>
5653 <a name="sqliteconfiggetpcache"></a>
5654
5655 <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
5656 <dd> These options are obsolete and should not be used by new code.
5657 They are retained for backwards compatibility but are now no-ops.
5658 </dd></p>
5659
5660 <p><a name="sqliteconfigsqllog"></a>
5661
5662 <dt>SQLITE_CONFIG_SQLLOG
5663 <dd>This option is only available if sqlite is compiled with the
5664 <a href="compile.html#enable_sqllog">SQLITE_ENABLE_SQLLOG</a> pre-processor macro defined. The first argument should
5665 be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
5666 The second should be of type (void*). The callback is invoked by the library
5667 in three separate circumstances, identified by the value passed as the
5668 fourth parameter. If the fourth parameter is 0, then the database connection
5669 passed as the second argument has just been opened. The third argument
5670 points to a buffer containing the name of the main database file. If the
5671 fourth parameter is 1, then the SQL statement that the third parameter
5672 points to has just been executed. Or, if the fourth parameter is 2, then
5673 the connection being passed as the second parameter is being closed. The
5674 third parameter is passed NULL In this case. An example of using this
5675 configuration option can be seen in the "test_sqllog.c" source file in
5676 the canonical SQLite source tree.</dd></p>
5677
5678 <p><a name="sqliteconfigmmapsize"></a>
5679
5680 <dt>SQLITE_CONFIG_MMAP_SIZE
5681 <dd>SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
5682 that are the default mmap size limit (the default setting for
5683 <a href="pragma.html#pragma_mmap_size">PRAGMA mmap_size</a>) and the maximum allowed mmap size limit.
5684 The default setting can be overridden by each database connection using
5685 either the <a href="pragma.html#pragma_mmap_size">PRAGMA mmap_size</a> command, or by using the
5686 <a href="#sqlitefcntlmmapsize">SQLITE_FCNTL_MMAP_SIZE</a> file control. The maximum allowed mmap size
5687 will be silently truncated if necessary so that it does not exceed the
5688 compile-time maximum mmap size set by the
5689 <a href="compile.html#max_mmap_size">SQLITE_MAX_MMAP_SIZE</a> compile-time option.
5690 If either argument to this option is negative, then that argument is
5691 changed to its compile-time default.</p>
5692
5693 <p><a name="sqliteconfigwin32heapsize"></a>
5694
5695 <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
5696 <dd>The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
5697 compiled for Windows with the <a href="compile.html#win32_malloc">SQLITE_WIN32_MALLOC</a> pre-processor macro
5698 defined. SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
5699 that specifies the maximum size of the created heap.</p>
5700
5701 <p><a name="sqliteconfigpcachehdrsz"></a>
5702
5703 <dt>SQLITE_CONFIG_PCACHE_HDRSZ
5704 <dd>The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
5705 is a pointer to an integer and writes into that integer the number of extra
5706 bytes per page required for each page in <a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>.
5707 The amount of extra space required can change depending on the compiler,
5708 target platform, and SQLite version.</p>
5709
5710 <p><a name="sqliteconfigpmasz"></a>
5711
5712 <dt>SQLITE_CONFIG_PMASZ
5713 <dd>The SQLITE_CONFIG_PMASZ option takes a single parameter which
5714 is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
5715 sorter to that integer. The default minimum PMA Size is set by the
5716 <a href="compile.html#sorter_pmasz">SQLITE_SORTER_PMASZ</a> compile-time option. New threads are launched
5717 to help with sort operations when multithreaded sorting
5718 is enabled (using the <a href="pragma.html#pragma_threads">PRAGMA threads</a> command) and the amount of content
5719 to be sorted exceeds the page size times the minimum of the
5720 <a href="pragma.html#pragma_cache_size">PRAGMA cache_size</a> setting and this value.</p>
5721
5722 <p><a name="sqliteconfigstmtjrnlspill"></a>
5723
5724 <dt>SQLITE_CONFIG_STMTJRNL_SPILL
5725 <dd>The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which
5726 becomes the <a href="tempfiles.html#stmtjrnl">statement journal</a> spill-to-disk threshold.
5727 <a href="tempfiles.html#stmtjrnl">Statement journals</a> are held in memory until their size (in bytes)
5728 exceeds this threshold, at which point they are written to disk.
5729 Or if the threshold is -1, statement journals are always held
5730 exclusively in memory.
5731 Since many statement journals never become large, setting the spill
5732 threshold to a value such as 64KiB can greatly reduce the amount of
5733 I/O required to support statement rollback.
5734 The default value for this setting is controlled by the
5735 <a href="compile.html#stmtjrnl_spill">SQLITE_STMTJRNL_SPILL</a> compile-time option.</p>
5736
5737 <p><a name="sqliteconfigsorterrefsize"></a>
5738
5739 <dt>SQLITE_CONFIG_SORTERREF_SIZE
5740 <dd>The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter
5741 of type (int) - the new value of the sorter-reference size threshold.
5742 Usually, when SQLite uses an external sort to order records according
5743 to an ORDER BY clause, all fields required by the caller are present in the
5744 sorted records. However, if SQLite determines based on the declared type
5745 of a table column that its values are likely to be very large - larger
5746 than the configured sorter-reference size threshold - then a reference
5747 is stored in each sorted record and the required column values loaded
5748 from the database as records are returned in sorted order. The default
5749 value for this option is to never use this optimization. Specifying a
5750 negative value for this option restores the default behavior.
5751 This option is only available if SQLite is compiled with the
5752 <a href="compile.html#enable_sorter_references">SQLITE_ENABLE_SORTER_REFERENCES</a> compile-time option.</p>
5753
5754 <p><a name="sqliteconfigmemdbmaxsize"></a>
5755
5756 <dt>SQLITE_CONFIG_MEMDB_MAXSIZE
5757 <dd>The SQLITE_CONFIG_MEMDB_MAXSIZE option accepts a single parameter
5758 <a href="#sqlite3_int64">sqlite3_int64</a> parameter which is the default maximum size for an in-memory
5759 database created using <a href="#sqlite3_deserialize">sqlite3_deserialize()</a>. This default maximum
5760 size can be adjusted up or down for individual databases using the
5761 <a href="#sqlitefcntlsizelimit">SQLITE_FCNTL_SIZE_LIMIT</a> <a href="#sqlite3_file_control">file-control</a>. If this
5762 configuration setting is never used, then the default maximum is determined
5763 by the <a href="compile.html#memdb_default_maxsize">SQLITE_MEMDB_DEFAULT_MAXSIZE</a> compile-time option. If that
5764 compile-time option is not set, then the default maximum is 1073741824.</p>
5765
5766 <p><a name="sqliteconfigrowidinview"></a>
5767
5768 <dt>SQLITE_CONFIG_ROWID_IN_VIEW
5769 <dd>The SQLITE_CONFIG_ROWID_IN_VIEW option enables or disables the ability
5770 for VIEWs to have a ROWID. The capability can only be enabled if SQLite is
5771 compiled with -DSQLITE_ALLOW_ROWID_IN_VIEW, in which case the capability
5772 defaults to on. This configuration option queries the current setting or
5773 changes the setting to off or on. The argument is a pointer to an integer.
5774 If that integer initially holds a value of 1, then the ability for VIEWs to
5775 have ROWIDs is activated. If the integer initially holds zero, then the
5776 ability is deactivated. Any other initial value for the integer leaves the
5777 setting unchanged. After changes, if any, the integer is written with
5778 a 1 or 0, if the ability for VIEWs to have ROWIDs is on or off. If SQLite
5779 is compiled without -DSQLITE_ALLOW_ROWID_IN_VIEW (which is the usual and
5780 recommended case) then the integer is always filled with zero, regardless
5781 if its initial value.
5782 </dl>
5783 </p><hr><a name="SQLITE_DBCONFIG_DEFENSIVE"></a>
5784 <h2>Database Connection Configuration Options</h2>
5785 </div>
5786 <blockquote><pre>
5787 #define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */
5788 #define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */
5789 #define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */
5790 #define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */
5791 #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */
5792 #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */
5793 #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */
5794 #define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */
5795 #define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */
5796 #define SQLITE_DBCONFIG_RESET_DATABASE 1009 /* int int* */
5797 #define SQLITE_DBCONFIG_DEFENSIVE 1010 /* int int* */
5798 #define SQLITE_DBCONFIG_WRITABLE_SCHEMA 1011 /* int int* */
5799 #define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE 1012 /* int int* */
5800 #define SQLITE_DBCONFIG_DQS_DML 1013 /* int int* */
5801 #define SQLITE_DBCONFIG_DQS_DDL 1014 /* int int* */
5802 #define SQLITE_DBCONFIG_ENABLE_VIEW 1015 /* int int* */
5803 #define SQLITE_DBCONFIG_LEGACY_FILE_FORMAT 1016 /* int int* */
5804 #define SQLITE_DBCONFIG_TRUSTED_SCHEMA 1017 /* int int* */
5805 #define SQLITE_DBCONFIG_STMT_SCANSTATUS 1018 /* int int* */
5806 #define SQLITE_DBCONFIG_REVERSE_SCANORDER 1019 /* int int* */
5807 #define SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE 1020 /* int int* */
5808 #define SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE 1021 /* int int* */
5809 #define SQLITE_DBCONFIG_ENABLE_COMMENTS 1022 /* int int* */
5810 #define SQLITE_DBCONFIG_FP_DIGITS 1023 /* int int* */
5811 #define SQLITE_DBCONFIG_MAX 1023 /* Largest DBCONFIG */
5812 </pre></blockquote>
5813 <p>
5814 These constants are the available integer configuration options that
5815 can be passed as the second parameter to the <a href="#sqlite3_db_config">sqlite3_db_config()</a> interface.</p>
5816
5817 <p>The <a href="#sqlite3_db_config">sqlite3_db_config()</a> interface is a var-args function. It takes a
5818 variable number of parameters, though always at least two. The number of
5819 parameters passed into sqlite3_db_config() depends on which of these
5820 constants is given as the second parameter. This documentation page
5821 refers to parameters beyond the second as "arguments". Thus, when this
5822 page says "the N-th argument" it means "the N-th parameter past the
5823 configuration option" or "the (N+2)-th parameter to sqlite3_db_config()".</p>
5824
5825 <p>New configuration options may be added in future releases of SQLite.
5826 Existing configuration options might be discontinued. Applications
5827 should check the return code from <a href="#sqlite3_db_config">sqlite3_db_config()</a> to make sure that
5828 the call worked. The <a href="#sqlite3_db_config">sqlite3_db_config()</a> interface will return a
5829 non-zero <a href="rescode.html">error code</a> if a discontinued or unsupported configuration option
5830 is invoked.</p>
5831
5832 <p><dl>
5833 <a name="sqlitedbconfiglookaside"></a>
5834
5835 <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
5836 <dd> The SQLITE_DBCONFIG_LOOKASIDE option is used to adjust the
5837 configuration of the <a href="malloc.html#lookaside">lookaside memory allocator</a> within a database
5838 connection.
5839 The arguments to the SQLITE_DBCONFIG_LOOKASIDE option are <i>not</i>
5840 in the <a href="#dbconfigarguments">usual format</a>.
5841 The SQLITE_DBCONFIG_LOOKASIDE option takes three arguments, not two,
5842 so that a call to <a href="#sqlite3_db_config">sqlite3_db_config()</a> that uses SQLITE_DBCONFIG_LOOKASIDE
5843 should have a total of five parameters.
5844 <ol>
5845 <li><p>The first argument ("buf") is a
5846 pointer to a memory buffer to use for lookaside memory.
5847 The first argument may be NULL in which case SQLite will allocate the
5848 lookaside buffer itself using <a href="#sqlite3_free">sqlite3_malloc()</a>.
5849 <li><P>The second argument ("sz") is the
5850 size of each lookaside buffer slot. Lookaside is disabled if "sz"
5851 is less than 8. The "sz" argument should be a multiple of 8 less than
5852 65536. If "sz" does not meet this constraint, it is reduced in size until
5853 it does.
5854 <li><p>The third argument ("cnt") is the number of slots.
5855 Lookaside is disabled if "cnt"is less than 1.
5856 that the product of "sz" and "cnt" does not exceed 2,147,418,112. The "cnt"
5857 parameter is usually chosen so that the product of "sz" and "cnt" is less
5858 than 1,000,000.
5859 </ol>
5860 <p>If the "buf" argument is not NULL, then it must
5861 point to a memory buffer with a size that is greater than
5862 or equal to the product of "sz" and "cnt".
5863 The buffer must be aligned to an 8-byte boundary.
5864 The lookaside memory
5865 configuration for a database connection can only be changed when that
5866 connection is not currently using lookaside memory, or in other words
5867 when the value returned by <a href="#sqlitedbstatuslookasideused">SQLITE_DBSTATUS_LOOKASIDE_USED</a> is zero.
5868 Any attempt to change the lookaside memory configuration when lookaside
5869 memory is in use leaves the configuration unchanged and returns
5870 <a href="#SQLITE_ABORT">SQLITE_BUSY</a>.
5871 If the "buf" argument is NULL and an attempt
5872 to allocate memory based on "sz" and "cnt" fails, then
5873 lookaside is silently disabled.
5874 <p>
5875 The <a href="#sqliteconfiglookaside">SQLITE_CONFIG_LOOKASIDE</a> configuration option can be used to set the
5876 default lookaside configuration at initialization. The
5877 <a href="compile.html#default_lookaside">-DSQLITE_DEFAULT_LOOKASIDE</a> option can be used to set the default lookaside
5878 configuration at compile-time. Typical values for lookaside are 1200 for
5879 "sz" and 40 to 100 for "cnt".
5880 </dd></p>
5881
5882 <p><a name="sqlitedbconfigenablefkey"></a>
5883
5884 <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
5885 <dd> This option is used to enable or disable the enforcement of
5886 <a href="foreignkeys.html">foreign key constraints</a>. This is the same setting that is
5887 enabled or disabled by the <a href="pragma.html#pragma_foreign_keys">PRAGMA foreign_keys</a> statement.
5888 The first argument is an integer which is 0 to disable FK enforcement,
5889 positive to enable FK enforcement or negative to leave FK enforcement
5890 unchanged. The second parameter is a pointer to an integer into which
5891 is written 0 or 1 to indicate whether FK enforcement is off or on
5892 following this call. The second parameter may be a NULL pointer, in
5893 which case the FK enforcement setting is not reported back. </dd></p>
5894
5895 <p><a name="sqlitedbconfigenabletrigger"></a>
5896
5897 <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
5898 <dd> This option is used to enable or disable <a href="lang_createtrigger.html">triggers</a>.
5899 There should be two additional arguments.
5900 The first argument is an integer which is 0 to disable triggers,
5901 positive to enable triggers or negative to leave the setting unchanged.
5902 The second parameter is a pointer to an integer into which
5903 is written 0 or 1 to indicate whether triggers are disabled or enabled
5904 following this call. The second parameter may be a NULL pointer, in
5905 which case the trigger setting is not reported back.</p>
5906
5907 <p><p>Originally this option disabled all triggers. However, since
5908 SQLite version 3.35.0, TEMP triggers are still allowed even if
5909 this option is off. So, in other words, this option now only disables
5910 triggers in the main database schema or in the schemas of <a href="lang_attach.html">ATTACH</a>-ed
5911 databases. </dd></p>
5912
5913 <p><a name="sqlitedbconfigenableview"></a>
5914
5915 <dt>SQLITE_DBCONFIG_ENABLE_VIEW</dt>
5916 <dd> This option is used to enable or disable <a href="lang_createview.html">views</a>.
5917 There must be two additional arguments.
5918 The first argument is an integer which is 0 to disable views,
5919 positive to enable views or negative to leave the setting unchanged.
5920 The second parameter is a pointer to an integer into which
5921 is written 0 or 1 to indicate whether views are disabled or enabled
5922 following this call. The second parameter may be a NULL pointer, in
5923 which case the view setting is not reported back.</p>
5924
5925 <p><p>Originally this option disabled all views. However, since
5926 SQLite version 3.35.0, TEMP views are still allowed even if
5927 this option is off. So, in other words, this option now only disables
5928 views in the main database schema or in the schemas of ATTACH-ed
5929 databases. </dd></p>
5930
5931 <p><a name="sqlitedbconfigenablefts3tokenizer"></a>
5932
5933 <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt>
5934 <dd> This option is used to enable or disable using the
5935 <a href="fts3.html#f3tknzr">fts3_tokenizer()</a> function - part of the <a href="fts3.html">FTS3</a> full-text search engine
5936 extension - without using bound parameters as the parameters. Doing so
5937 is disabled by default. There must be two additional arguments. The first
5938 argument is an integer. If it is passed 0, then using fts3_tokenizer()
5939 without bound parameters is disabled. If it is passed a positive value,
5940 then calling fts3_tokenizer without bound parameters is enabled. If it
5941 is passed a negative value, this setting is not modified - this can be
5942 used to query for the current setting. The second parameter is a pointer
5943 to an integer into which is written 0 or 1 to indicate the current value
5944 of this setting (after it is modified, if applicable). The second
5945 parameter may be a NULL pointer, in which case the value of the setting
5946 is not reported back. Refer to <a href="fts3.html">FTS3</a> documentation for further details.
5947 </dd></p>
5948
5949 <p><a name="sqlitedbconfigenableloadextension"></a>
5950
5951 <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt>
5952 <dd> This option is used to enable or disable the <a href="#sqlite3_load_extension">sqlite3_load_extension()</a>
5953 interface independently of the <a href="lang_corefunc.html#load_extension">load_extension()</a> SQL function.
5954 The <a href="#sqlite3_enable_load_extension">sqlite3_enable_load_extension()</a> API enables or disables both the
5955 C-API <a href="#sqlite3_load_extension">sqlite3_load_extension()</a> and the SQL function <a href="lang_corefunc.html#load_extension">load_extension()</a>.
5956 There must be two additional arguments.
5957 When the first argument to this interface is 1, then only the C-API is
5958 enabled and the SQL function remains disabled. If the first argument to
5959 this interface is 0, then both the C-API and the SQL function are disabled.
5960 If the first argument is -1, then no changes are made to the state of either
5961 the C-API or the SQL function.
5962 The second parameter is a pointer to an integer into which
5963 is written 0 or 1 to indicate whether <a href="#sqlite3_load_extension">sqlite3_load_extension()</a> interface
5964 is disabled or enabled following this call. The second parameter may
5965 be a NULL pointer, in which case the new setting is not reported back.
5966 </dd></p>
5967
5968 <p><a name="sqlitedbconfigmaindbname"></a>
5969 <dt>SQLITE_DBCONFIG_MAINDBNAME</dt>
5970 <dd> This option is used to change the name of the "main" database
5971 schema. This option does not follow the
5972 <a href="#dbconfigarguments">usual SQLITE_DBCONFIG argument format</a>.
5973 This option takes exactly one additional argument so that the
5974 <a href="#sqlite3_db_config">sqlite3_db_config()</a> call has a total of three parameters. The
5975 extra argument must be a pointer to a constant UTF8 string which
5976 will become the new schema name in place of "main". SQLite does
5977 not make a copy of the new main schema name string, so the application
5978 must ensure that the argument passed into SQLITE_DBCONFIG MAINDBNAME
5979 is unchanged until after the database connection closes.
5980 </dd></p>
5981
5982 <p><a name="sqlitedbconfignockptonclose"></a>
5983
5984 <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt>
5985 <dd> Usually, when a database in <a href="wal.html">WAL mode</a> is closed or detached from a
5986 database handle, SQLite checks if if there are other connections to the
5987 same database, and if there are no other database connection (if the
5988 connection being closed is the last open connection to the database),
5989 then SQLite performs a <a href="wal.html#ckpt">checkpoint</a> before closing the connection and
5990 deletes the WAL file. The SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE option can
5991 be used to override that behavior. The first argument passed to this
5992 operation (the third parameter to <a href="#sqlite3_db_config">sqlite3_db_config()</a>) is an integer
5993 which is positive to disable checkpoints-on-close, or zero (the default)
5994 to enable them, and negative to leave the setting unchanged.
5995 The second argument (the fourth parameter) is a pointer to an integer
5996 into which is written 0 or 1 to indicate whether checkpoints-on-close
5997 have been disabled - 0 if they are not disabled, 1 if they are.
5998 </dd></p>
5999
6000 <p><a name="sqlitedbconfigenableqpsg"></a>
6001 <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt>
6002 <dd>The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates
6003 the <a href="queryplanner-ng.html#qpstab">query planner stability guarantee</a> (QPSG). When the QPSG is active,
6004 a single SQL query statement will always use the same algorithm regardless
6005 of values of <a href="lang_expr.html#varparam">bound parameters</a>. The QPSG disables some query optimizations
6006 that look at the values of bound parameters, which can make some queries
6007 slower. But the QPSG has the advantage of more predictable behavior. With
6008 the QPSG active, SQLite will always use the same query plan in the field as
6009 was used during testing in the lab.
6010 The first argument to this setting is an integer which is 0 to disable
6011 the QPSG, positive to enable QPSG, or negative to leave the setting
6012 unchanged. The second parameter is a pointer to an integer into which
6013 is written 0 or 1 to indicate whether the QPSG is disabled or enabled
6014 following this call.
6015 </dd></p>
6016
6017 <p><a name="sqlitedbconfigtriggereqp"></a>
6018 <dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt>
6019 <dd> By default, the output of EXPLAIN QUERY PLAN commands does not
6020 include output for any operations performed by trigger programs. This
6021 option is used to set or clear (the default) a flag that governs this
6022 behavior. The first parameter passed to this operation is an integer -
6023 positive to enable output for trigger programs, or zero to disable it,
6024 or negative to leave the setting unchanged.
6025 The second parameter is a pointer to an integer into which is written
6026 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if
6027 it is not disabled, 1 if it is.
6028 </dd></p>
6029
6030 <p><a name="sqlitedbconfigresetdatabase"></a>
6031 <dt>SQLITE_DBCONFIG_RESET_DATABASE</dt>
6032 <dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run
6033 <a href="lang_vacuum.html">VACUUM</a> in order to reset a database back to an empty database
6034 with no schema and no content. The following process works even for
6035 a badly corrupted database file:
6036 <ol>
6037 <li> If the database connection is newly opened, make sure it has read the
6038 database schema by preparing then discarding some query against the
6039 database, or calling sqlite3_table_column_metadata(), ignoring any
6040 errors. This step is only necessary if the application desires to keep
6041 the database in WAL mode after the reset if it was in WAL mode before
6042 the reset.
6043 <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0);
6044 <li> <a href="#sqlite3_exec">sqlite3_exec</a>(db, "<a href="lang_vacuum.html">VACUUM</a>", 0, 0, 0);
6045 <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0);
6046 </ol>
6047 Because resetting a database is destructive and irreversible, the
6048 process requires the use of this obscure API and multiple steps to
6049 help ensure that it does not happen by accident. Because this
6050 feature must be capable of resetting corrupt databases, and
6051 shutting down virtual tables may require access to that corrupt
6052 storage, the library must abandon any installed virtual tables
6053 without calling their xDestroy() methods.</p>
6054
6055 <p><a name="sqlitedbconfigdefensive"></a>
6056 <dt>SQLITE_DBCONFIG_DEFENSIVE</dt>
6057 <dd>The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the
6058 "defensive" flag for a database connection. When the defensive
6059 flag is enabled, language features that allow ordinary SQL to
6060 deliberately corrupt the database file are disabled. The disabled
6061 features include but are not limited to the following:
6062 <ul>
6063 <li> The <a href="pragma.html#pragma_writable_schema">PRAGMA writable_schema=ON</a> statement.
6064 <li> The <a href="pragma.html#pragma_journal_mode">PRAGMA journal_mode=OFF</a> statement.
6065 <li> The <a href="pragma.html#pragma_schema_version">PRAGMA schema_version=N</a> statement.
6066 <li> Writes to the <a href="dbpage.html">sqlite_dbpage</a> virtual table.
6067 <li> Direct writes to <a href="vtab.html#xshadowname">shadow tables</a>.
6068 </ul>
6069 </dd></p>
6070
6071 <p><a name="sqlitedbconfigwritableschema"></a>
6072 <dt>SQLITE_DBCONFIG_WRITABLE_SCHEMA</dt>
6073 <dd>The SQLITE_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates the
6074 "writable_schema" flag. This has the same effect and is logically equivalent
6075 to setting <a href="pragma.html#pragma_writable_schema">PRAGMA writable_schema=ON</a> or <a href="pragma.html#pragma_writable_schema">PRAGMA writable_schema=OFF</a>.
6076 The first argument to this setting is an integer which is 0 to disable
6077 the writable_schema, positive to enable writable_schema, or negative to
6078 leave the setting unchanged. The second parameter is a pointer to an
6079 integer into which is written 0 or 1 to indicate whether the writable_schema
6080 is enabled or disabled following this call.
6081 </dd></p>
6082
6083 <p><a name="sqlitedbconfiglegacyaltertable"></a>
6084
6085 <dt>SQLITE_DBCONFIG_LEGACY_ALTER_TABLE</dt>
6086 <dd>The SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates
6087 the legacy behavior of the <a href="lang_altertable.html#altertabrename">ALTER TABLE RENAME</a> command such that it
6088 behaves as it did prior to <a href="releaselog/3_24_0.html">version 3.24.0</a> (2018-06-04). See the
6089 "Compatibility Notice" on the <a href="lang_altertable.html#altertabrename">ALTER TABLE RENAME documentation</a> for
6090 additional information. This feature can also be turned on and off
6091 using the <a href="pragma.html#pragma_legacy_alter_table">PRAGMA legacy_alter_table</a> statement.
6092 </dd></p>
6093
6094 <p><a name="sqlitedbconfigdqsdml"></a>
6095
6096 <dt>SQLITE_DBCONFIG_DQS_DML</dt>
6097 <dd>The SQLITE_DBCONFIG_DQS_DML option activates or deactivates
6098 the legacy <a href="quirks.html#dblquote">double-quoted string literal</a> misfeature for DML statements
6099 only, that is DELETE, INSERT, SELECT, and UPDATE statements. The
6100 default value of this setting is determined by the <a href="compile.html#dqs">-DSQLITE_DQS</a>
6101 compile-time option.
6102 </dd></p>
6103
6104 <p><a name="sqlitedbconfigdqsddl"></a>
6105
6106 <dt>SQLITE_DBCONFIG_DQS_DDL</dt>
6107 <dd>The SQLITE_DBCONFIG_DQS option activates or deactivates
6108 the legacy <a href="quirks.html#dblquote">double-quoted string literal</a> misfeature for DDL statements,
6109 such as CREATE TABLE and CREATE INDEX. The
6110 default value of this setting is determined by the <a href="compile.html#dqs">-DSQLITE_DQS</a>
6111 compile-time option.
6112 </dd></p>
6113
6114 <p><a name="sqlitedbconfigtrustedschema"></a>
6115
6116 <dt>SQLITE_DBCONFIG_TRUSTED_SCHEMA</dt>
6117 <dd>The SQLITE_DBCONFIG_TRUSTED_SCHEMA option tells SQLite to
6118 assume that database schemas are untainted by malicious content.
6119 When the SQLITE_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite
6120 takes additional defensive steps to protect the application from harm
6121 including:
6122 <ul>
6123 <li> Prohibit the use of SQL functions inside triggers, views,
6124 CHECK constraints, DEFAULT clauses, expression indexes,
6125 partial indexes, or generated columns
6126 unless those functions are tagged with <a href="#sqliteinnocuous">SQLITE_INNOCUOUS</a>.
6127 <li> Prohibit the use of virtual tables inside of triggers or views
6128 unless those virtual tables are tagged with <a href="#sqlitevtabinnocuous">SQLITE_VTAB_INNOCUOUS</a>.
6129 </ul>
6130 This setting defaults to "on" for legacy compatibility, however
6131 all applications are advised to turn it off if possible. This setting
6132 can also be controlled using the <a href="pragma.html#pragma_trusted_schema">PRAGMA trusted_schema</a> statement.
6133 </dd></p>
6134
6135 <p><a name="sqlitedbconfiglegacyfileformat"></a>
6136
6137 <dt>SQLITE_DBCONFIG_LEGACY_FILE_FORMAT</dt>
6138 <dd>The SQLITE_DBCONFIG_LEGACY_FILE_FORMAT option activates or deactivates
6139 the legacy file format flag. When activated, this flag causes all newly
6140 created database files to have a schema format version number (the 4-byte
6141 integer found at offset 44 into the database header) of 1. This in turn
6142 means that the resulting database file will be readable and writable by
6143 any SQLite version back to 3.0.0 (2004-06-18). Without this setting,
6144 newly created databases are generally not understandable by SQLite versions
6145 prior to 3.3.0 (2006-01-11). As these words are written, there
6146 is now scarcely any need to generate database files that are compatible
6147 all the way back to version 3.0.0, and so this setting is of little
6148 practical use, but is provided so that SQLite can continue to claim the
6149 ability to generate new database files that are compatible with version
6150 3.0.0.
6151 <p>Note that when the SQLITE_DBCONFIG_LEGACY_FILE_FORMAT setting is on,
6152 the <a href="lang_vacuum.html">VACUUM</a> command will fail with an obscure error when attempting to
6153 process a table with generated columns and a descending index. This is
6154 not considered a bug since SQLite versions 3.3.0 and earlier do not support
6155 either generated columns or descending indexes.
6156 </dd></p>
6157
6158 <p><a name="sqlitedbconfigstmtscanstatus"></a>
6159
6160 <dt>SQLITE_DBCONFIG_STMT_SCANSTATUS</dt>
6161 <dd>The SQLITE_DBCONFIG_STMT_SCANSTATUS option is only useful in
6162 <a href="compile.html#enable_stmt_scanstatus">SQLITE_ENABLE_STMT_SCANSTATUS</a> builds. In this case, it sets or clears
6163 a flag that enables collection of run-time performance statistics
6164 used by <a href="#sqlite3_stmt_scanstatus">sqlite3_stmt_scanstatus_v2()</a> and the <a href="bytecodevtab.html#nexec">nexec and ncycle</a>
6165 columns of the <a href="bytecodevtab.html">bytecode virtual table</a>.
6166 For statistics to be collected, the flag must be set on
6167 the database handle both when the SQL statement is
6168 <a href="#sqlite3_prepare">prepared</a> and when it is <a href="#sqlite3_step">stepped</a>.
6169 The flag is set (collection of statistics is enabled) by default.
6170 <p>This option takes two arguments: an integer and a pointer to
6171 an integer. The first argument is 1, 0, or -1 to enable, disable, or
6172 leave unchanged the statement scanstatus option. If the second argument
6173 is not NULL, then the value of the statement scanstatus setting after
6174 processing the first argument is written into the integer that the second
6175 argument points to.
6176 </dd></p>
6177
6178 <p><a name="sqlitedbconfigreversescanorder"></a>
6179
6180 <dt>SQLITE_DBCONFIG_REVERSE_SCANORDER</dt>
6181 <dd>The SQLITE_DBCONFIG_REVERSE_SCANORDER option changes the default order
6182 in which tables and indexes are scanned so that the scans start at the end
6183 and work toward the beginning rather than starting at the beginning and
6184 working toward the end. Setting SQLITE_DBCONFIG_REVERSE_SCANORDER is the
6185 same as setting <a href="pragma.html#pragma_reverse_unordered_selects">PRAGMA reverse_unordered_selects</a>. <p>This option takes
6186 two arguments which are an integer and a pointer to an integer. The first
6187 argument is 1, 0, or -1 to enable, disable, or leave unchanged the
6188 reverse scan order flag, respectively. If the second argument is not NULL,
6189 then 0 or 1 is written into the integer that the second argument points to
6190 depending on if the reverse scan order flag is set after processing the
6191 first argument.
6192 </dd></p>
6193
6194 <p><a name="sqlitedbconfigenableattachcreate"></a>
6195
6196 <dt>SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE</dt>
6197 <dd>The SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE option enables or disables
6198 the ability of the <a href="lang_attach.html">ATTACH DATABASE</a> SQL command to create a new database
6199 file if the database filed named in the ATTACH command does not already
6200 exist. This ability of ATTACH to create a new database is enabled by
6201 default. Applications can disable or reenable the ability for ATTACH to
6202 create new database files using this DBCONFIG option.<p>
6203 This option takes two arguments which are an integer and a pointer
6204 to an integer. The first argument is 1, 0, or -1 to enable, disable, or
6205 leave unchanged the attach-create flag, respectively. If the second
6206 argument is not NULL, then 0 or 1 is written into the integer that the
6207 second argument points to depending on if the attach-create flag is set
6208 after processing the first argument.
6209 </dd></p>
6210
6211 <p><a name="sqlitedbconfigenableattachwrite"></a>
6212
6213 <dt>SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE</dt>
6214 <dd>The SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE option enables or disables the
6215 ability of the <a href="lang_attach.html">ATTACH DATABASE</a> SQL command to open a database for writing.
6216 This capability is enabled by default. Applications can disable or
6217 reenable this capability using the current DBCONFIG option. If
6218 this capability is disabled, the <a href="lang_attach.html">ATTACH</a> command will still work,
6219 but the database will be opened read-only. If this option is disabled,
6220 then the ability to create a new database using <a href="lang_attach.html">ATTACH</a> is also disabled,
6221 regardless of the value of the <a href="#sqlitedbconfigenableattachcreate">SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE</a>
6222 option.<p>
6223 This option takes two arguments which are an integer and a pointer
6224 to an integer. The first argument is 1, 0, or -1 to enable, disable, or
6225 leave unchanged the ability to ATTACH another database for writing,
6226 respectively. If the second argument is not NULL, then 0 or 1 is written
6227 into the integer to which the second argument points, depending on whether
6228 the ability to ATTACH a read/write database is enabled or disabled
6229 after processing the first argument.
6230 </dd></p>
6231
6232 <p><a name="sqlitedbconfigenablecomments"></a>
6233
6234 <dt>SQLITE_DBCONFIG_ENABLE_COMMENTS</dt>
6235 <dd>The SQLITE_DBCONFIG_ENABLE_COMMENTS option enables or disables the
6236 ability to include comments in SQL text. Comments are enabled by default.
6237 An application can disable or reenable comments in SQL text using this
6238 DBCONFIG option.<p>
6239 This option takes two arguments which are an integer and a pointer
6240 to an integer. The first argument is 1, 0, or -1 to enable, disable, or
6241 leave unchanged the ability to use comments in SQL text,
6242 respectively. If the second argument is not NULL, then 0 or 1 is written
6243 into the integer that the second argument points to depending on if
6244 comments are allowed in SQL text after processing the first argument.
6245 </dd></p>
6246
6247 <p><a name="sqlitedbconfigfpdigits"></a>
6248
6249 <dt>SQLITE_DBCONFIG_FP_DIGITS</dt>
6250 <dd>The SQLITE_DBCONFIG_FP_DIGITS setting is a small integer that determines
6251 the number of significant digits that SQLite will attempt to preserve when
6252 converting floating point numbers (IEEE 754 "doubles") into text. The
6253 default value 17, as of SQLite version 3.52.0. The value was 15 in all
6254 prior versions.<p>
6255 This option takes two arguments which are an integer and a pointer
6256 to an integer. The first argument is a small integer, between 3 and 23, or
6257 zero. The FP_DIGITS setting is changed to that small integer, or left
6258 unaltered if the first argument is zero or out of range. The second argument
6259 is a pointer to an integer. If the pointer is not NULL, then the value of
6260 the FP_DIGITS setting, after possibly being modified by the first
6261 arguments, is written into the integer to which the second argument points.
6262 </dd></p>
6263
6264 <p></dl></p>
6265
6266 <p><a name="dbconfigarguments"></a>
6267 <h3>Arguments To SQLITE_DBCONFIG Options</h3></p>
6268
6269 <p><p>Most of the SQLITE_DBCONFIG options take two arguments, so that the
6270 overall call to <a href="#sqlite3_db_config">sqlite3_db_config()</a> has a total of four parameters.
6271 The first argument (the third parameter to sqlite3_db_config()) is
6272 an integer.
6273 The second argument is a pointer to an integer. If the first argument is 1,
6274 then the option becomes enabled. If the first integer argument is 0,
6275 then the option is disabled.
6276 If the first argument is -1, then the option setting
6277 is unchanged. The second argument, the pointer to an integer, may be NULL.
6278 If the second argument is not NULL, then a value of 0 or 1 is written into
6279 the integer to which the second argument points, depending on whether the
6280 setting is disabled or enabled after applying any changes specified by
6281 the first argument.</p>
6282
6283 <p><p>While most SQLITE_DBCONFIG options use the argument format
6284 described in the previous paragraph, the <a href="#sqlitedbconfigmaindbname">SQLITE_DBCONFIG_MAINDBNAME</a>,
6285 <a href="#sqlitedbconfiglookaside">SQLITE_DBCONFIG_LOOKASIDE</a>, and <a href="#sqlitedbconfigfpdigits">SQLITE_DBCONFIG_FP_DIGITS</a> options
6286 are different. See the documentation of those exceptional options for
6287 details.
6288 </p><hr><a name="SQLITE_DENY"></a>
6289 <h2>Authorizer Return Codes</h2>
6290 </div>
6291 <blockquote><pre>
6292 #define SQLITE_DENY 1 /* Abort the SQL statement with an error */
6293 #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
6294 </pre></blockquote>
6295 <p>
6296 The <a href="#sqlite3_set_authorizer">authorizer callback function</a> must
6297 return either <a href="#SQLITE_ABORT">SQLITE_OK</a> or one of these two constants in order
6298 to signal SQLite whether or not the action is permitted. See the
6299 <a href="#sqlite3_set_authorizer">authorizer documentation</a> for additional
6300 information.</p>
6301
6302 <p>Note that SQLITE_IGNORE is also used as a <a href="#SQLITE_FAIL">conflict resolution mode</a>
6303 returned from the <a href="#sqlite3_vtab_on_conflict">sqlite3_vtab_on_conflict()</a> interface.
6304 </p><hr><a name="SQLITE_DESERIALIZE_FREEONCLOSE"></a>
6305 <h2>Flags for sqlite3_deserialize()</h2>
6306 </div>
6307 <blockquote><pre>
6308 #define SQLITE_DESERIALIZE_FREEONCLOSE 1 /* Call sqlite3_free() on close */
6309 #define SQLITE_DESERIALIZE_RESIZEABLE 2 /* Resize using sqlite3_realloc64() */
6310 #define SQLITE_DESERIALIZE_READONLY 4 /* Database is read-only */
6311 </pre></blockquote>
6312 <p>
6313 The following are allowed values for the 6th argument (the F argument) to
6314 the <a href="#sqlite3_deserialize">sqlite3_deserialize(D,S,P,N,M,F)</a> interface.</p>
6315
6316 <p>The SQLITE_DESERIALIZE_FREEONCLOSE means that the database serialization
6317 in the P argument is held in memory obtained from <a href="#sqlite3_free">sqlite3_malloc64()</a>
6318 and that SQLite should take ownership of this memory and automatically
6319 free it when it has finished using it. Without this flag, the caller
6320 is responsible for freeing any dynamically allocated memory.</p>
6321
6322 <p>The SQLITE_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed to
6323 grow the size of the database using calls to <a href="#sqlite3_free">sqlite3_realloc64()</a>. This
6324 flag should only be used if SQLITE_DESERIALIZE_FREEONCLOSE is also used.
6325 Without this flag, the deserialized database cannot increase in size beyond
6326 the number of bytes specified by the M parameter.</p>
6327
6328 <p>The SQLITE_DESERIALIZE_READONLY flag means that the deserialized database
6329 should be treated as read-only.
6330 </p><hr><a name="SQLITE_DETERMINISTIC"></a>
6331 <h2>Function Flags</h2>
6332 </div>
6333 <blockquote><pre>
6334 #define SQLITE_DETERMINISTIC 0x000000800
6335 #define SQLITE_DIRECTONLY 0x000080000
6336 #define SQLITE_SUBTYPE 0x000100000
6337 #define SQLITE_INNOCUOUS 0x000200000
6338 #define SQLITE_RESULT_SUBTYPE 0x001000000
6339 #define SQLITE_SELFORDER1 0x002000000
6340 </pre></blockquote>
6341 <p>
6342 These constants may be ORed together with the
6343 <a href="#sqliteutf8">preferred text encoding</a> as the fourth argument
6344 to <a href="#sqlite3_create_function">sqlite3_create_function()</a>, <a href="#sqlite3_create_function">sqlite3_create_function16()</a>, or
6345 <a href="#sqlite3_create_function">sqlite3_create_function_v2()</a>.</p>
6346
6347 <p><dl>
6348 <a name="sqlitedeterministic"></a>
6349 <dt>SQLITE_DETERMINISTIC</dt><dd>
6350 The SQLITE_DETERMINISTIC flag means that the new function always gives
6351 the same output when the input parameters are the same.
6352 The <a href="lang_corefunc.html#abs">abs() function</a> is deterministic, for example, but
6353 <a href="lang_corefunc.html#randomblob">randomblob()</a> is not. Functions must
6354 be deterministic in order to be used in certain contexts such as
6355 with the WHERE clause of <a href="partialindex.html">partial indexes</a> or in <a href="gencol.html">generated columns</a>.
6356 SQLite might also optimize deterministic functions by factoring them
6357 out of inner loops.
6358 </dd></p>
6359
6360 <p><a name="sqlitedirectonly"></a>
6361 <dt>SQLITE_DIRECTONLY</dt><dd>
6362 The SQLITE_DIRECTONLY flag means that the function may only be invoked
6363 from top-level SQL, and cannot be used in VIEWs or TRIGGERs nor in
6364 schema structures such as <a href="lang_createtable.html#ckconst">CHECK constraints</a>, <a href="lang_createtable.html#dfltval">DEFAULT clauses</a>,
6365 <a href="expridx.html">expression indexes</a>, <a href="partialindex.html">partial indexes</a>, or <a href="gencol.html">generated columns</a>.
6366 <p>
6367 The SQLITE_DIRECTONLY flag is recommended for any
6368 <a href="appfunc.html">application-defined SQL function</a>
6369 that has side-effects or that could potentially leak sensitive information.
6370 This will prevent attacks in which an application is tricked
6371 into using a database file that has had its schema surreptitiously
6372 modified to invoke the application-defined function in ways that are
6373 harmful.
6374 <p>
6375 Some people say it is good practice to set SQLITE_DIRECTONLY on all
6376 <a href="appfunc.html">application-defined SQL functions</a>, regardless of whether or not they
6377 are security sensitive, as doing so prevents those functions from being used
6378 inside of the database schema, and thus ensures that the database
6379 can be inspected and modified using generic tools (such as the <a href="cli.html">CLI</a>)
6380 that do not have access to the application-defined functions.
6381 </dd></p>
6382
6383 <p><a name="sqliteinnocuous"></a>
6384 <dt>SQLITE_INNOCUOUS</dt><dd>
6385 The SQLITE_INNOCUOUS flag means that the function is unlikely
6386 to cause problems even if misused. An innocuous function should have
6387 no side effects and should not depend on any values other than its
6388 input parameters. The <a href="lang_corefunc.html#abs">abs() function</a> is an example of an
6389 innocuous function.
6390 The <a href="lang_corefunc.html#load_extension">load_extension() SQL function</a> is not innocuous because of its
6391 side effects.
6392 <p> SQLITE_INNOCUOUS is similar to SQLITE_DETERMINISTIC, but is not
6393 exactly the same. The <a href="lang_corefunc.html#random">random() function</a> is an example of a
6394 function that is innocuous but not deterministic.
6395 <p>Some heightened security settings
6396 (<a href="#sqlitedbconfigtrustedschema">SQLITE_DBCONFIG_TRUSTED_SCHEMA</a> and <a href="pragma.html#pragma_trusted_schema">PRAGMA trusted_schema=OFF</a>)
6397 disable the use of SQL functions inside views and triggers and in
6398 schema structures such as <a href="lang_createtable.html#ckconst">CHECK constraints</a>, <a href="lang_createtable.html#dfltval">DEFAULT clauses</a>,
6399 <a href="expridx.html">expression indexes</a>, <a href="partialindex.html">partial indexes</a>, and <a href="gencol.html">generated columns</a> unless
6400 the function is tagged with SQLITE_INNOCUOUS. Most built-in functions
6401 are innocuous. Developers are advised to avoid using the
6402 SQLITE_INNOCUOUS flag for application-defined functions unless the
6403 function has been carefully audited and found to be free of potentially
6404 security-adverse side-effects and information-leaks.
6405 </dd></p>
6406
6407 <p><a name="sqlitesubtype"></a>
6408 <dt>SQLITE_SUBTYPE</dt><dd>
6409 The SQLITE_SUBTYPE flag indicates to SQLite that a function might call
6410 <a href="#sqlite3_value_subtype">sqlite3_value_subtype()</a> to inspect the sub-types of its arguments.
6411 This flag instructs SQLite to omit some corner-case optimizations that
6412 might disrupt the operation of the <a href="#sqlite3_value_subtype">sqlite3_value_subtype()</a> function,
6413 causing it to return zero rather than the correct subtype().
6414 All SQL functions that invoke <a href="#sqlite3_value_subtype">sqlite3_value_subtype()</a> should have this
6415 property. If the SQLITE_SUBTYPE property is omitted, then the return
6416 value from <a href="#sqlite3_value_subtype">sqlite3_value_subtype()</a> might sometimes be zero even though
6417 a non-zero subtype was specified by the function argument expression.</p>
6418
6419 <p><a name="sqliteresultsubtype"></a>
6420 <dt>SQLITE_RESULT_SUBTYPE</dt><dd>
6421 The SQLITE_RESULT_SUBTYPE flag indicates to SQLite that a function might call
6422 <a href="#sqlite3_result_subtype">sqlite3_result_subtype()</a> to cause a sub-type to be associated with its
6423 result.
6424 Every function that invokes <a href="#sqlite3_result_subtype">sqlite3_result_subtype()</a> should have this
6425 property. If it does not, then the call to <a href="#sqlite3_result_subtype">sqlite3_result_subtype()</a>
6426 might become a no-op if the function is used as a term in an
6427 <a href="expridx.html">expression index</a>. On the other hand, SQL functions that never invoke
6428 <a href="#sqlite3_result_subtype">sqlite3_result_subtype()</a> should avoid setting this property, as the
6429 purpose of this property is to disable certain optimizations that are
6430 incompatible with subtypes.</p>
6431
6432 <p><a name="sqliteselforder1"></a>
6433 <dt>SQLITE_SELFORDER1</dt><dd>
6434 The SQLITE_SELFORDER1 flag indicates that the function is an aggregate
6435 that internally orders the values provided to the first argument. The
6436 ordered-set aggregate SQL notation with a single ORDER BY term can be
6437 used to invoke this function. If the ordered-set aggregate notation is
6438 used on a function that lacks this flag, then an error is raised. Note
6439 that the ordered-set aggregate syntax is only available if SQLite is
6440 built using the -DSQLITE_ENABLE_ORDERED_SET_AGGREGATES compile-time option.
6441 </dd>
6442 </dl>
6443 </p><hr><a name="SQLITE_FAIL"></a>
6444 <h2>Conflict resolution modes</h2>
6445 </div>
6446 <blockquote><pre>
6447 #define SQLITE_ROLLBACK 1
6448 /* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */
6449 #define SQLITE_FAIL 3
6450 /* #define SQLITE_ABORT 4 // Also an error code */
6451 #define SQLITE_REPLACE 5
6452 </pre></blockquote>
6453 <p>
6454 These constants are returned by <a href="#sqlite3_vtab_on_conflict">sqlite3_vtab_on_conflict()</a> to
6455 inform a <a href="vtab.html">virtual table</a> implementation of the <a href="lang_conflict.html">ON CONFLICT</a> mode
6456 for the SQL statement being evaluated.</p>
6457
6458 <p>Note that the <a href="#SQLITE_DENY">SQLITE_IGNORE</a> constant is also used as a potential
6459 return value from the <a href="#sqlite3_set_authorizer">sqlite3_set_authorizer()</a> callback and that
6460 <a href="#SQLITE_ABORT">SQLITE_ABORT</a> is also a <a href="rescode.html">result code</a>.
6461 </p><hr><a name="SQLITE_FCNTL_BEGIN_ATOMIC_WRITE"></a>
6462 <h2>Standard File Control Opcodes</h2>
6463 </div>
6464 <blockquote><pre>
6465 #define SQLITE_FCNTL_LOCKSTATE 1
6466 #define SQLITE_FCNTL_GET_LOCKPROXYFILE 2
6467 #define SQLITE_FCNTL_SET_LOCKPROXYFILE 3
6468 #define SQLITE_FCNTL_LAST_ERRNO 4
6469 #define SQLITE_FCNTL_SIZE_HINT 5
6470 #define SQLITE_FCNTL_CHUNK_SIZE 6
6471 #define SQLITE_FCNTL_FILE_POINTER 7
6472 #define SQLITE_FCNTL_SYNC_OMITTED 8
6473 #define SQLITE_FCNTL_WIN32_AV_RETRY 9
6474 #define SQLITE_FCNTL_PERSIST_WAL 10
6475 #define SQLITE_FCNTL_OVERWRITE 11
6476 #define SQLITE_FCNTL_VFSNAME 12
6477 #define SQLITE_FCNTL_POWERSAFE_OVERWRITE 13
6478 #define SQLITE_FCNTL_PRAGMA 14
6479 #define SQLITE_FCNTL_BUSYHANDLER 15
6480 #define SQLITE_FCNTL_TEMPFILENAME 16
6481 #define SQLITE_FCNTL_MMAP_SIZE 18
6482 #define SQLITE_FCNTL_TRACE 19
6483 #define SQLITE_FCNTL_HAS_MOVED 20
6484 #define SQLITE_FCNTL_SYNC 21
6485 #define SQLITE_FCNTL_COMMIT_PHASETWO 22
6486 #define SQLITE_FCNTL_WIN32_SET_HANDLE 23
6487 #define SQLITE_FCNTL_WAL_BLOCK 24
6488 #define SQLITE_FCNTL_ZIPVFS 25
6489 #define SQLITE_FCNTL_RBU 26
6490 #define SQLITE_FCNTL_VFS_POINTER 27
6491 #define SQLITE_FCNTL_JOURNAL_POINTER 28
6492 #define SQLITE_FCNTL_WIN32_GET_HANDLE 29
6493 #define SQLITE_FCNTL_PDB 30
6494 #define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 31
6495 #define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE 32
6496 #define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 33
6497 #define SQLITE_FCNTL_LOCK_TIMEOUT 34
6498 #define SQLITE_FCNTL_DATA_VERSION 35
6499 #define SQLITE_FCNTL_SIZE_LIMIT 36
6500 #define SQLITE_FCNTL_CKPT_DONE 37
6501 #define SQLITE_FCNTL_RESERVE_BYTES 38
6502 #define SQLITE_FCNTL_CKPT_START 39
6503 #define SQLITE_FCNTL_EXTERNAL_READER 40
6504 #define SQLITE_FCNTL_CKSM_FILE 41
6505 #define SQLITE_FCNTL_RESET_CACHE 42
6506 #define SQLITE_FCNTL_NULL_IO 43
6507 #define SQLITE_FCNTL_BLOCK_ON_CONNECT 44
6508 #define SQLITE_FCNTL_FILESTAT 45
6509 </pre></blockquote>
6510 <p>
6511 These integer constants are opcodes for the xFileControl method
6512 of the <a href="#sqlite3_io_methods">sqlite3_io_methods</a> object and for the <a href="#sqlite3_file_control">sqlite3_file_control()</a>
6513 interface.</p>
6514
6515 <p><ul>
6516 <li><a name="sqlitefcntllockstate"></a>
6517
6518 The <a href="#sqlitefcntllockstate">SQLITE_FCNTL_LOCKSTATE</a> opcode is used for debugging. This
6519 opcode causes the xFileControl method to write the current state of
6520 the lock (one of <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_NONE</a>, <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_SHARED</a>,
6521 <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_RESERVED</a>, <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_PENDING</a>, or <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_EXCLUSIVE</a>)
6522 into an integer that the pArg argument points to.
6523 This capability is only available if SQLite is compiled with <a href="compile.html#debug">SQLITE_DEBUG</a>.</p>
6524
6525 <p><li><a name="sqlitefcntlsizehint"></a>
6526
6527 The <a href="#sqlitefcntlsizehint">SQLITE_FCNTL_SIZE_HINT</a> opcode is used by SQLite to give the VFS
6528 layer a hint of how large the database file will grow to be during the
6529 current transaction. This hint is not guaranteed to be accurate but it
6530 is often close. The underlying VFS might choose to preallocate database
6531 file space based on this hint in order to help writes to the database
6532 file run faster.</p>
6533
6534 <p><li><a name="sqlitefcntlsizelimit"></a>
6535
6536 The <a href="#sqlitefcntlsizelimit">SQLITE_FCNTL_SIZE_LIMIT</a> opcode is used by in-memory VFS that
6537 implements <a href="#sqlite3_deserialize">sqlite3_deserialize()</a> to set an upper bound on the size
6538 of the in-memory database. The argument is a pointer to a <a href="#sqlite3_int64">sqlite3_int64</a>.
6539 If the integer pointed to is negative, then it is filled in with the
6540 current limit. Otherwise the limit is set to the larger of the value
6541 of the integer pointed to and the current database size. The integer
6542 pointed to is set to the new limit.</p>
6543
6544 <p><li><a name="sqlitefcntlchunksize"></a>
6545
6546 The <a href="#sqlitefcntlchunksize">SQLITE_FCNTL_CHUNK_SIZE</a> opcode is used to request that the VFS
6547 extends and truncates the database file in chunks of a size specified
6548 by the user. The fourth argument to <a href="#sqlite3_file_control">sqlite3_file_control()</a> should
6549 point to an integer (type int) containing the new chunk-size to use
6550 for the nominated database. Allocating database file space in large
6551 chunks (say 1MB at a time), may reduce file-system fragmentation and
6552 improve performance on some systems.</p>
6553
6554 <p><li><a name="sqlitefcntlfilepointer"></a>
6555
6556 The <a href="#sqlitefcntlfilepointer">SQLITE_FCNTL_FILE_POINTER</a> opcode is used to obtain a pointer
6557 to the <a href="#sqlite3_file">sqlite3_file</a> object associated with a particular database
6558 connection. See also <a href="#sqlitefcntljournalpointer">SQLITE_FCNTL_JOURNAL_POINTER</a>.</p>
6559
6560 <p><li><a name="sqlitefcntljournalpointer"></a>
6561
6562 The <a href="#sqlitefcntljournalpointer">SQLITE_FCNTL_JOURNAL_POINTER</a> opcode is used to obtain a pointer
6563 to the <a href="#sqlite3_file">sqlite3_file</a> object associated with the journal file (either
6564 the <a href="lockingv3.html#rollback">rollback journal</a> or the <a href="wal.html">write-ahead log</a>) for a particular database
6565 connection. See also <a href="#sqlitefcntlfilepointer">SQLITE_FCNTL_FILE_POINTER</a>.</p>
6566
6567 <p><li><a name="sqlitefcntlsyncomitted"></a>
6568
6569 The SQLITE_FCNTL_SYNC_OMITTED file-control is no longer used.</p>
6570
6571 <p><li><a name="sqlitefcntlsync"></a>
6572
6573 The <a href="#sqlitefcntlsync">SQLITE_FCNTL_SYNC</a> opcode is generated internally by SQLite and
6574 sent to the VFS immediately before the xSync method is invoked on a
6575 database file descriptor. Or, if the xSync method is not invoked
6576 because the user has configured SQLite with
6577 <a href="pragma.html#pragma_synchronous">PRAGMA synchronous=OFF</a> it is invoked in place
6578 of the xSync method. In most cases, the pointer argument passed with
6579 this file-control is NULL. However, if the database file is being synced
6580 as part of a multi-database commit, the argument points to a nul-terminated
6581 string containing the transactions super-journal file name. VFSes that
6582 do not need this signal should silently ignore this opcode. Applications
6583 should not call <a href="#sqlite3_file_control">sqlite3_file_control()</a> with this opcode as doing so may
6584 disrupt the operation of the specialized VFSes that do require it.</p>
6585
6586 <p><li><a name="sqlitefcntlcommitphasetwo"></a>
6587
6588 The <a href="#sqlitefcntlcommitphasetwo">SQLITE_FCNTL_COMMIT_PHASETWO</a> opcode is generated internally by SQLite
6589 and sent to the VFS after a transaction has been committed immediately
6590 but before the database is unlocked. VFSes that do not need this signal
6591 should silently ignore this opcode. Applications should not call
6592 <a href="#sqlite3_file_control">sqlite3_file_control()</a> with this opcode as doing so may disrupt the
6593 operation of the specialized VFSes that do require it.</p>
6594
6595 <p><li><a name="sqlitefcntlwin32avretry"></a>
6596
6597 The <a href="#sqlitefcntlwin32avretry">SQLITE_FCNTL_WIN32_AV_RETRY</a> opcode is used to configure automatic
6598 retry counts and intervals for certain disk I/O operations for the
6599 windows <a href="vfs.html">VFS</a> in order to provide robustness in the presence of
6600 anti-virus programs. By default, the windows VFS will retry file read,
6601 file write, and file delete operations up to 10 times, with a delay
6602 of 25 milliseconds before the first retry and with the delay increasing
6603 by an additional 25 milliseconds with each subsequent retry. This
6604 opcode allows these two values (10 retries and 25 milliseconds of delay)
6605 to be adjusted. The values are changed for all database connections
6606 within the same process. The argument is a pointer to an array of two
6607 integers where the first integer is the new retry count and the second
6608 integer is the delay. If either integer is negative, then the setting
6609 is not changed but instead the prior value of that setting is written
6610 into the array entry, allowing the current retry settings to be
6611 interrogated. The zDbName parameter is ignored.</p>
6612
6613 <p><li><a name="sqlitefcntlpersistwal"></a>
6614
6615 The <a href="#sqlitefcntlpersistwal">SQLITE_FCNTL_PERSIST_WAL</a> opcode is used to set or query the
6616 persistent <a href="wal.html">Write Ahead Log</a> setting. By default, the auxiliary
6617 write ahead log (<a href="wal.html#walfile">WAL file</a>) and shared memory
6618 files used for transaction control
6619 are automatically deleted when the latest connection to the database
6620 closes. Setting persistent WAL mode causes those files to persist after
6621 close. Persisting the files is useful when other processes that do not
6622 have write permission on the directory containing the database file want
6623 to read the database file, as the WAL and shared memory files must exist
6624 in order for the database to be readable. The fourth parameter to
6625 <a href="#sqlite3_file_control">sqlite3_file_control()</a> for this opcode should be a pointer to an integer.
6626 That integer is 0 to disable persistent WAL mode or 1 to enable persistent
6627 WAL mode. If the integer is -1, then it is overwritten with the current
6628 WAL persistence setting.</p>
6629
6630 <p><li><a name="sqlitefcntlpowersafeoverwrite"></a>
6631
6632 The <a href="#sqlitefcntlpowersafeoverwrite">SQLITE_FCNTL_POWERSAFE_OVERWRITE</a> opcode is used to set or query the
6633 persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting
6634 determines the <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_POWERSAFE_OVERWRITE</a> bit of the
6635 xDeviceCharacteristics methods. The fourth parameter to
6636 <a href="#sqlite3_file_control">sqlite3_file_control()</a> for this opcode should be a pointer to an integer.
6637 That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
6638 mode. If the integer is -1, then it is overwritten with the current
6639 zero-damage mode setting.</p>
6640
6641 <p><li><a name="sqlitefcntloverwrite"></a>
6642
6643 The <a href="#sqlitefcntloverwrite">SQLITE_FCNTL_OVERWRITE</a> opcode is invoked by SQLite after opening
6644 a write transaction to indicate that, unless it is rolled back for some
6645 reason, the entire database file will be overwritten by the current
6646 transaction. This is used by VACUUM operations.</p>
6647
6648 <p><li><a name="sqlitefcntlvfsname"></a>
6649
6650 The <a href="#sqlitefcntlvfsname">SQLITE_FCNTL_VFSNAME</a> opcode can be used to obtain the names of
6651 all <a href="vfs.html">VFSes</a> in the VFS stack. The names of all VFS shims and the
6652 final bottom-level VFS are written into memory obtained from
6653 <a href="#sqlite3_free">sqlite3_malloc()</a> and the result is stored in the char* variable
6654 that the fourth parameter of <a href="#sqlite3_file_control">sqlite3_file_control()</a> points to.
6655 The caller is responsible for freeing the memory when done. As with
6656 all file-control actions, there is no guarantee that this will actually
6657 do anything. Callers should initialize the char* variable to a NULL
6658 pointer in case this file-control is not implemented. This file-control
6659 is intended for diagnostic use only.</p>
6660
6661 <p><li><a name="sqlitefcntlvfspointer"></a>
6662
6663 The <a href="#sqlitefcntlvfspointer">SQLITE_FCNTL_VFS_POINTER</a> opcode finds a pointer to the top-level
6664 <a href="vfs.html">VFSes</a> currently in use. The argument X in
6665 sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be
6666 of type "<a href="#sqlite3_vfs">sqlite3_vfs</a> **". This opcode will set *X
6667 to a pointer to the top-level VFS.
6668 When there are multiple VFS shims in the stack, this opcode finds the
6669 upper-most shim only.</p>
6670
6671 <p><li><a name="sqlitefcntlpragma"></a>
6672
6673 Whenever a <a href="pragma.html#syntax">PRAGMA</a> statement is parsed, an <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a>
6674 file control is sent to the open <a href="#sqlite3_file">sqlite3_file</a> object corresponding
6675 to the database file to which the pragma statement refers. The argument
6676 to the <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control is an array of
6677 pointers to strings (char**) in which the second element of the array
6678 is the name of the pragma and the third element is the argument to the
6679 pragma or NULL if the pragma has no argument. The handler for an
6680 <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control can optionally make the first element
6681 of the char** argument point to a string obtained from <a href="#sqlite3_mprintf">sqlite3_mprintf()</a>
6682 or the equivalent and that string will become the result of the pragma or
6683 the error message if the pragma fails. If the
6684 <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control returns <a href="#SQLITE_ABORT">SQLITE_NOTFOUND</a>, then normal
6685 <a href="pragma.html#syntax">PRAGMA</a> processing continues. If the <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a>
6686 file control returns <a href="#SQLITE_ABORT">SQLITE_OK</a>, then the parser assumes that the
6687 VFS has handled the PRAGMA itself and the parser generates a no-op
6688 prepared statement if result string is NULL, or that returns a copy
6689 of the result string if the string is non-NULL.
6690 If the <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control returns
6691 any result code other than <a href="#SQLITE_ABORT">SQLITE_OK</a> or <a href="#SQLITE_ABORT">SQLITE_NOTFOUND</a>, that means
6692 that the VFS encountered an error while handling the <a href="pragma.html#syntax">PRAGMA</a> and the
6693 compilation of the PRAGMA fails with an error. The <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a>
6694 file control occurs at the beginning of pragma statement analysis and so
6695 it is able to override built-in <a href="pragma.html#syntax">PRAGMA</a> statements.</p>
6696
6697 <p><li><a name="sqlitefcntlbusyhandler"></a>
6698
6699 The <a href="#sqlitefcntlbusyhandler">SQLITE_FCNTL_BUSYHANDLER</a>
6700 file-control may be invoked by SQLite on the database file handle
6701 shortly after it is opened in order to provide a custom VFS with access
6702 to the connection's busy-handler callback. The argument is of type (void**)
6703 - an array of two (void *) values. The first (void *) actually points
6704 to a function of type (int (*)(void *)). In order to invoke the connection's
6705 busy-handler, this function should be invoked with the second (void *) in
6706 the array as the only argument. If it returns non-zero, then the operation
6707 should be retried. If it returns zero, the custom VFS should abandon the
6708 current operation.</p>
6709
6710 <p><li><a name="sqlitefcntltempfilename"></a>
6711
6712 Applications can invoke the <a href="#sqlitefcntltempfilename">SQLITE_FCNTL_TEMPFILENAME</a> file-control
6713 to have SQLite generate a
6714 temporary filename using the same algorithm that is followed to generate
6715 temporary filenames for TEMP tables and other internal uses. The
6716 argument should be a char** which will be filled with the filename
6717 written into memory obtained from <a href="#sqlite3_free">sqlite3_malloc()</a>. The caller should
6718 invoke <a href="#sqlite3_free">sqlite3_free()</a> on the result to avoid a memory leak.</p>
6719
6720 <p><li><a name="sqlitefcntlmmapsize"></a>
6721
6722 The <a href="#sqlitefcntlmmapsize">SQLITE_FCNTL_MMAP_SIZE</a> file control is used to query or set the
6723 maximum number of bytes that will be used for memory-mapped I/O.
6724 The argument is a pointer to a value of type sqlite3_int64 that
6725 is an advisory maximum number of bytes in the file to memory map. The
6726 pointer is overwritten with the old value. The limit is not changed if
6727 the value originally pointed to is negative, and so the current limit
6728 can be queried by passing in a pointer to a negative number. This
6729 file-control is used internally to implement <a href="pragma.html#pragma_mmap_size">PRAGMA mmap_size</a>.</p>
6730
6731 <p><li><a name="sqlitefcntltrace"></a>
6732
6733 The <a href="#sqlitefcntltrace">SQLITE_FCNTL_TRACE</a> file control provides advisory information
6734 to the VFS about what the higher layers of the SQLite stack are doing.
6735 This file control is used by some VFS activity tracing <a href="vfs.html#shim">shims</a>.
6736 The argument is a zero-terminated string. Higher layers in the
6737 SQLite stack may generate instances of this file control if
6738 the <a href="compile.html#use_fcntl_trace">SQLITE_USE_FCNTL_TRACE</a> compile-time option is enabled.</p>
6739
6740 <p><li><a name="sqlitefcntlhasmoved"></a>
6741
6742 The <a href="#sqlitefcntlhasmoved">SQLITE_FCNTL_HAS_MOVED</a> file control interprets its argument as a
6743 pointer to an integer and it writes a boolean into that integer depending
6744 on whether or not the file has been renamed, moved, or deleted since it
6745 was first opened.</p>
6746
6747 <p><li><a name="sqlitefcntlwin32gethandle"></a>
6748
6749 The <a href="#sqlitefcntlwin32gethandle">SQLITE_FCNTL_WIN32_GET_HANDLE</a> opcode can be used to obtain the
6750 underlying native file handle associated with a file handle. This file
6751 control interprets its argument as a pointer to a native file handle and
6752 writes the resulting value there.</p>
6753
6754 <p><li><a name="sqlitefcntlwin32sethandle"></a>
6755
6756 The <a href="#sqlitefcntlwin32sethandle">SQLITE_FCNTL_WIN32_SET_HANDLE</a> opcode is used for debugging. This
6757 opcode causes the xFileControl method to swap the file handle with the one
6758 pointed to by the pArg argument. This capability is used during testing
6759 and only needs to be supported when SQLITE_TEST is defined.</p>
6760
6761 <p><li><a name="sqlitefcntlnullio"></a>
6762
6763 The <a href="#sqlitefcntlnullio">SQLITE_FCNTL_NULL_IO</a> opcode sets the low-level file descriptor
6764 or file handle for the <a href="#sqlite3_file">sqlite3_file</a> object such that it will no longer
6765 read or write to the database file.</p>
6766
6767 <p><li><a name="sqlitefcntlwalblock"></a>
6768
6769 The <a href="#sqlitefcntlwalblock">SQLITE_FCNTL_WAL_BLOCK</a> is a signal to the VFS layer that it might
6770 be advantageous to block on the next WAL lock if the lock is not immediately
6771 available. The WAL subsystem issues this signal during rare
6772 circumstances in order to fix a problem with priority inversion.
6773 Applications should <em>not</em> use this file-control.</p>
6774
6775 <p><li><a name="sqlitefcntlzipvfs"></a>
6776
6777 The <a href="#sqlitefcntlzipvfs">SQLITE_FCNTL_ZIPVFS</a> opcode is implemented by zipvfs only. All other
6778 VFS should return SQLITE_NOTFOUND for this opcode.</p>
6779
6780 <p><li><a name="sqlitefcntlrbu"></a>
6781
6782 The <a href="#sqlitefcntlrbu">SQLITE_FCNTL_RBU</a> opcode is implemented by the special VFS used by
6783 the RBU extension only. All other VFS should return SQLITE_NOTFOUND for
6784 this opcode.</p>
6785
6786 <p><li><a name="sqlitefcntlbeginatomicwrite"></a>
6787
6788 If the <a href="#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a> opcode returns SQLITE_OK, then
6789 the file descriptor is placed in "batch write mode", which
6790 means all subsequent write operations will be deferred and done
6791 atomically at the next <a href="#sqlitefcntlcommitatomicwrite">SQLITE_FCNTL_COMMIT_ATOMIC_WRITE</a>. Systems
6792 that do not support batch atomic writes will return SQLITE_NOTFOUND.
6793 Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to
6794 the closing <a href="#sqlitefcntlcommitatomicwrite">SQLITE_FCNTL_COMMIT_ATOMIC_WRITE</a> or
6795 <a href="#sqlitefcntlrollbackatomicwrite">SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE</a>, SQLite will make
6796 no VFS interface calls on the same <a href="#sqlite3_file">sqlite3_file</a> file descriptor
6797 except for calls to the xWrite method and the xFileControl method
6798 with <a href="#sqlitefcntlsizehint">SQLITE_FCNTL_SIZE_HINT</a>.</p>
6799
6800 <p><li><a name="sqlitefcntlcommitatomicwrite"></a>
6801
6802 The <a href="#sqlitefcntlcommitatomicwrite">SQLITE_FCNTL_COMMIT_ATOMIC_WRITE</a> opcode causes all write
6803 operations since the previous successful call to
6804 <a href="#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a> to be performed atomically.
6805 This file control returns <a href="#SQLITE_ABORT">SQLITE_OK</a> if and only if the writes were
6806 all performed successfully and have been committed to persistent storage.
6807 Regardless of whether or not it is successful, this file control takes
6808 the file descriptor out of batch write mode so that all subsequent
6809 write operations are independent.
6810 SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without
6811 a prior successful call to <a href="#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a>.</p>
6812
6813 <p><li><a name="sqlitefcntlrollbackatomicwrite"></a>
6814
6815 The <a href="#sqlitefcntlrollbackatomicwrite">SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE</a> opcode causes all write
6816 operations since the previous successful call to
6817 <a href="#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a> to be rolled back.
6818 This file control takes the file descriptor out of batch write mode
6819 so that all subsequent write operations are independent.
6820 SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without
6821 a prior successful call to <a href="#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a>.</p>
6822
6823 <p><li><a name="sqlitefcntllocktimeout"></a>
6824
6825 The <a href="#sqlitefcntllocktimeout">SQLITE_FCNTL_LOCK_TIMEOUT</a> opcode is used to configure a VFS
6826 to block for up to M milliseconds before failing when attempting to
6827 obtain a file lock using the xLock or xShmLock methods of the VFS.
6828 The parameter is a pointer to a 32-bit signed integer that contains
6829 the value that M is to be set to. Before returning, the 32-bit signed
6830 integer is overwritten with the previous value of M.</p>
6831
6832 <p><li><a name="sqlitefcntlblockonconnect"></a>
6833
6834 The <a href="#sqlitefcntlblockonconnect">SQLITE_FCNTL_BLOCK_ON_CONNECT</a> opcode is used to configure the
6835 VFS to block when taking a SHARED lock to connect to a wal mode database.
6836 This is used to implement the functionality associated with
6837 SQLITE_SETLK_BLOCK_ON_CONNECT.</p>
6838
6839 <p><li><a name="sqlitefcntldataversion"></a>
6840
6841 The <a href="#sqlitefcntldataversion">SQLITE_FCNTL_DATA_VERSION</a> opcode is used to detect changes to
6842 a database file. The argument is a pointer to a 32-bit unsigned integer.
6843 The "data version" for the pager is written into the pointer. The
6844 "data version" changes whenever any change occurs to the corresponding
6845 database file, either through SQL statements on the same database
6846 connection or through transactions committed by separate database
6847 connections possibly in other processes. The <a href="#sqlite3_total_changes">sqlite3_total_changes()</a>
6848 interface can be used to find if any database on the connection has changed,
6849 but that interface responds to changes on TEMP as well as MAIN and does
6850 not provide a mechanism to detect changes to MAIN only. Also, the
6851 <a href="#sqlite3_total_changes">sqlite3_total_changes()</a> interface responds to internal changes only and
6852 omits changes made by other database connections. The
6853 <a href="pragma.html#pragma_data_version">PRAGMA data_version</a> command provides a mechanism to detect changes to
6854 a single attached database that occur due to other database connections,
6855 but omits changes implemented by the database connection on which it is
6856 called. This file control is the only mechanism to detect changes that
6857 happen either internally or externally and that are associated with
6858 a particular attached database.</p>
6859
6860 <p><li><a name="sqlitefcntlckptstart"></a>
6861
6862 The <a href="#sqlitefcntlckptstart">SQLITE_FCNTL_CKPT_START</a> opcode is invoked from within a checkpoint
6863 in wal mode before the client starts to copy pages from the wal
6864 file to the database file.</p>
6865
6866 <p><li><a name="sqlitefcntlckptdone"></a>
6867
6868 The <a href="#sqlitefcntlckptdone">SQLITE_FCNTL_CKPT_DONE</a> opcode is invoked from within a checkpoint
6869 in wal mode after the client has finished copying pages from the wal
6870 file to the database file, but before the *-shm file is updated to
6871 record the fact that the pages have been checkpointed.</p>
6872
6873 <p><li><a name="sqlitefcntlexternalreader"></a>
6874
6875 The EXPERIMENTAL <a href="#sqlitefcntlexternalreader">SQLITE_FCNTL_EXTERNAL_READER</a> opcode is used to detect
6876 whether or not there is a database client in another process with a wal-mode
6877 transaction open on the database or not. It is only available on unix. The
6878 (void*) argument passed with this file-control should be a pointer to a
6879 value of type (int). The integer value is set to 1 if the database is a wal
6880 mode database and there exists at least one client in another process that
6881 currently has an SQL transaction open on the database. It is set to 0 if
6882 the database is not a wal-mode db, or if there is no such connection in any
6883 other process. This opcode cannot be used to detect transactions opened
6884 by clients within the current process, only within other processes.</p>
6885
6886 <p><li><a name="sqlitefcntlcksmfile"></a>
6887
6888 The <a href="#sqlitefcntlcksmfile">SQLITE_FCNTL_CKSM_FILE</a> opcode is for use internally by the
6889 <a href="cksumvfs.html">checksum VFS shim</a> only.</p>
6890
6891 <p><li><a name="sqlitefcntlresetcache"></a>
6892
6893 If there is currently no transaction open on the database, and the
6894 database is not a temp db, then the <a href="#sqlitefcntlresetcache">SQLITE_FCNTL_RESET_CACHE</a> file-control
6895 purges the contents of the in-memory page cache. If there is an open
6896 transaction, or if the db is a temp-db, this opcode is a no-op, not an error.</p>
6897
6898 <p><li><a name="sqlitefcntlfilestat"></a>
6899
6900 The <a href="#sqlitefcntlfilestat">SQLITE_FCNTL_FILESTAT</a> opcode returns low-level diagnostic information
6901 about the <a href="#sqlite3_file">sqlite3_file</a> objects used access the database and journal files
6902 for the given schema. The fourth parameter to <a href="#sqlite3_file_control">sqlite3_file_control()</a>
6903 should be an initialized <a href="#sqlite3_str">sqlite3_str</a> pointer. JSON text describing
6904 various aspects of the sqlite3_file object is appended to the sqlite3_str.
6905 The SQLITE_FCNTL_FILESTAT opcode is usually a no-op, unless compile-time
6906 options are used to enable it.
6907 </ul>
6908 </p><hr><a name="SQLITE_INDEX_CONSTRAINT_EQ"></a>
6909 <h2>Virtual Table Constraint Operator Codes</h2>
6910 </div>
6911 <blockquote><pre>
6912 #define SQLITE_INDEX_CONSTRAINT_EQ 2
6913 #define SQLITE_INDEX_CONSTRAINT_GT 4
6914 #define SQLITE_INDEX_CONSTRAINT_LE 8
6915 #define SQLITE_INDEX_CONSTRAINT_LT 16
6916 #define SQLITE_INDEX_CONSTRAINT_GE 32
6917 #define SQLITE_INDEX_CONSTRAINT_MATCH 64
6918 #define SQLITE_INDEX_CONSTRAINT_LIKE 65
6919 #define SQLITE_INDEX_CONSTRAINT_GLOB 66
6920 #define SQLITE_INDEX_CONSTRAINT_REGEXP 67
6921 #define SQLITE_INDEX_CONSTRAINT_NE 68
6922 #define SQLITE_INDEX_CONSTRAINT_ISNOT 69
6923 #define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70
6924 #define SQLITE_INDEX_CONSTRAINT_ISNULL 71
6925 #define SQLITE_INDEX_CONSTRAINT_IS 72
6926 #define SQLITE_INDEX_CONSTRAINT_LIMIT 73
6927 #define SQLITE_INDEX_CONSTRAINT_OFFSET 74
6928 #define SQLITE_INDEX_CONSTRAINT_FUNCTION 150
6929 </pre></blockquote>
6930 <p>
6931 These macros define the allowed values for the
6932 <a href="#sqlite3_index_info">sqlite3_index_info</a>.aConstraint[].op field. Each value represents
6933 an operator that is part of a constraint term in the WHERE clause of
6934 a query that uses a <a href="vtab.html">virtual table</a>.</p>
6935
6936 <p>The left-hand operand of the operator is given by the corresponding
6937 aConstraint[].iColumn field. An iColumn of -1 indicates the left-hand
6938 operand is the rowid.
6939 The SQLITE_INDEX_CONSTRAINT_LIMIT and SQLITE_INDEX_CONSTRAINT_OFFSET
6940 operators have no left-hand operand, and so for those operators the
6941 corresponding aConstraint[].iColumn is meaningless and should not be
6942 used.</p>
6943
6944 <p>All operator values from SQLITE_INDEX_CONSTRAINT_FUNCTION through
6945 value 255 are reserved to represent functions that are overloaded
6946 by the <a href="vtab.html#xfindfunction">xFindFunction method</a> of the virtual table
6947 implementation.</p>
6948
6949 <p>The right-hand operands for each constraint might be accessible using
6950 the <a href="#sqlite3_vtab_rhs_value">sqlite3_vtab_rhs_value()</a> interface. Usually the right-hand
6951 operand is only available if it appears as a single constant literal
6952 in the input SQL. If the right-hand operand is another column or an
6953 expression (even a constant expression) or a parameter, then the
6954 sqlite3_vtab_rhs_value() probably will not be able to extract it.
6955 The SQLITE_INDEX_CONSTRAINT_ISNULL and
6956 SQLITE_INDEX_CONSTRAINT_ISNOTNULL operators have no right-hand operand
6957 and hence calls to sqlite3_vtab_rhs_value() for those operators will
6958 always return SQLITE_NOTFOUND.</p>
6959
6960 <p>The collating sequence to be used for comparison can be found using
6961 the <a href="#sqlite3_vtab_collation">sqlite3_vtab_collation()</a> interface. For most real-world virtual
6962 tables, the collating sequence of constraints does not matter (for example
6963 because the constraints are numeric) and so the sqlite3_vtab_collation()
6964 interface is not commonly needed.
6965 </p><hr><a name="SQLITE_INDEX_SCAN_HEX"></a>
6966 <h2>Virtual Table Scan Flags</h2>
6967 </div>
6968 <blockquote><pre>
6969 #define SQLITE_INDEX_SCAN_UNIQUE 0x00000001 /* Scan visits at most 1 row */
6970 #define SQLITE_INDEX_SCAN_HEX 0x00000002 /* Display idxNum as hex */
6971 /* in EXPLAIN QUERY PLAN */
6972 </pre></blockquote>
6973 <p>
6974 Virtual table implementations are allowed to set the
6975 <a href="#sqlite3_index_info">sqlite3_index_info</a>.idxFlags field to some combination of
6976 these bits.
6977 </p><hr><a name="SQLITE_IOCAP_ATOMIC"></a>
6978 <h2>Device Characteristics</h2>
6979 </div>
6980 <blockquote><pre>
6981 #define SQLITE_IOCAP_ATOMIC 0x00000001
6982 #define SQLITE_IOCAP_ATOMIC512 0x00000002
6983 #define SQLITE_IOCAP_ATOMIC1K 0x00000004
6984 #define SQLITE_IOCAP_ATOMIC2K 0x00000008
6985 #define SQLITE_IOCAP_ATOMIC4K 0x00000010
6986 #define SQLITE_IOCAP_ATOMIC8K 0x00000020
6987 #define SQLITE_IOCAP_ATOMIC16K 0x00000040
6988 #define SQLITE_IOCAP_ATOMIC32K 0x00000080
6989 #define SQLITE_IOCAP_ATOMIC64K 0x00000100
6990 #define SQLITE_IOCAP_SAFE_APPEND 0x00000200
6991 #define SQLITE_IOCAP_SEQUENTIAL 0x00000400
6992 #define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800
6993 #define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000
6994 #define SQLITE_IOCAP_IMMUTABLE 0x00002000
6995 #define SQLITE_IOCAP_BATCH_ATOMIC 0x00004000
6996 #define SQLITE_IOCAP_SUBPAGE_READ 0x00008000
6997 </pre></blockquote>
6998 <p>
6999 The xDeviceCharacteristics method of the <a href="#sqlite3_io_methods">sqlite3_io_methods</a>
7000 object returns an integer which is a vector of these
7001 bit values expressing I/O characteristics of the mass storage
7002 device that holds the file that the <a href="#sqlite3_io_methods">sqlite3_io_methods</a>
7003 refers to.</p>
7004
7005 <p>The SQLITE_IOCAP_ATOMIC property means that all writes of
7006 any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
7007 mean that writes of blocks that are nnn bytes in size and
7008 are aligned to an address which is an integer multiple of
7009 nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
7010 that when data is appended to a file, the data is appended
7011 first then the size of the file is extended, never the other
7012 way around. The SQLITE_IOCAP_SEQUENTIAL property means that
7013 information is written to disk in the same order as calls
7014 to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
7015 after reboot following a crash or power loss, the only bytes in a
7016 file that were written at the application level might have changed
7017 and that adjacent bytes, even bytes within the same sector are
7018 guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
7019 flag indicates that a file cannot be deleted when open. The
7020 SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
7021 read-only media and cannot be changed even by processes with
7022 elevated privileges.</p>
7023
7024 <p>The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying
7025 filesystem supports doing multiple write operations atomically when those
7026 write operations are bracketed by <a href="#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a> and
7027 <a href="#sqlitefcntlcommitatomicwrite">SQLITE_FCNTL_COMMIT_ATOMIC_WRITE</a>.</p>
7028
7029 <p>The SQLITE_IOCAP_SUBPAGE_READ property means that it is ok to read
7030 from the database file in amounts that are not a multiple of the
7031 page size and that do not begin at a page boundary. Without this
7032 property, SQLite is careful to only do full-page reads and write
7033 on aligned pages, with the one exception that it will do a sub-page
7034 read of the first page to access the database header.
7035 </p><hr><a name="SQLITE_LOCK_EXCLUSIVE"></a>
7036 <h2>File Locking Levels</h2>
7037 </div>
7038 <blockquote><pre>
7039 #define SQLITE_LOCK_NONE 0 /* xUnlock() only */
7040 #define SQLITE_LOCK_SHARED 1 /* xLock() or xUnlock() */
7041 #define SQLITE_LOCK_RESERVED 2 /* xLock() only */
7042 #define SQLITE_LOCK_PENDING 3 /* xLock() only */
7043 #define SQLITE_LOCK_EXCLUSIVE 4 /* xLock() only */
7044 </pre></blockquote>
7045 <p>
7046 SQLite uses one of these integer values as the second
7047 argument to calls it makes to the xLock() and xUnlock() methods
7048 of an <a href="#sqlite3_io_methods">sqlite3_io_methods</a> object. These values are ordered from
7049 least restrictive to most restrictive.</p>
7050
7051 <p>The argument to xLock() is always SHARED or higher. The argument to
7052 xUnlock is either SHARED or NONE.
7053 </p><hr><a name="SQLITE_MUTEX_FAST"></a>
7054 <h2>Mutex Types</h2>
7055 </div>
7056 <blockquote><pre>
7057 #define SQLITE_MUTEX_FAST 0
7058 #define SQLITE_MUTEX_RECURSIVE 1
7059 #define SQLITE_MUTEX_STATIC_MAIN 2
7060 #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */
7061 #define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */
7062 #define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */
7063 #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_randomness() */
7064 #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
7065 #define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */
7066 #define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */
7067 #define SQLITE_MUTEX_STATIC_APP1 8 /* For use by application */
7068 #define SQLITE_MUTEX_STATIC_APP2 9 /* For use by application */
7069 #define SQLITE_MUTEX_STATIC_APP3 10 /* For use by application */
7070 #define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */
7071 #define SQLITE_MUTEX_STATIC_VFS2 12 /* For use by extension VFS */
7072 #define SQLITE_MUTEX_STATIC_VFS3 13 /* For use by application VFS */
7073 </pre></blockquote>
7074 <p>
7075 The <a href="#sqlite3_mutex_alloc">sqlite3_mutex_alloc()</a> interface takes a single argument
7076 which is one of these integer constants.</p>
7077
7078 <p>The set of static mutexes may change from one SQLite release to the
7079 next. Applications that override the built-in mutex logic must be
7080 prepared to accommodate additional static mutexes.
7081 </p><hr><a name="SQLITE_OPEN_AUTOPROXY"></a>
7082 <h2>Flags For File Open Operations</h2>
7083 </div>
7084 <blockquote><pre>
7085 #define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */
7086 #define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */
7087 #define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */
7088 #define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */
7089 #define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */
7090 #define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */
7091 #define SQLITE_OPEN_URI 0x00000040 /* Ok for sqlite3_open_v2() */
7092 #define SQLITE_OPEN_MEMORY 0x00000080 /* Ok for sqlite3_open_v2() */
7093 #define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */
7094 #define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */
7095 #define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */
7096 #define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */
7097 #define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */
7098 #define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */
7099 #define SQLITE_OPEN_SUPER_JOURNAL 0x00004000 /* VFS only */
7100 #define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */
7101 #define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */
7102 #define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */
7103 #define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */
7104 #define SQLITE_OPEN_WAL 0x00080000 /* VFS only */
7105 #define SQLITE_OPEN_NOFOLLOW 0x01000000 /* Ok for sqlite3_open_v2() */
7106 #define SQLITE_OPEN_EXRESCODE 0x02000000 /* Extended result codes */
7107 </pre></blockquote>
7108 <p>
7109 These bit values are intended for use in the
7110 3rd parameter to the <a href="#sqlite3_open">sqlite3_open_v2()</a> interface and
7111 in the 4th parameter to the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> method.</p>
7112
7113 <p>Only those flags marked as "Ok for sqlite3_open_v2()" may be
7114 used as the third argument to the <a href="#sqlite3_open">sqlite3_open_v2()</a> interface.
7115 The other flags have historically been ignored by sqlite3_open_v2(),
7116 though future versions of SQLite might change so that an error is
7117 raised if any of the disallowed bits are passed into sqlite3_open_v2().
7118 Applications should not depend on the historical behavior.</p>
7119
7120 <p>Note in particular that passing the SQLITE_OPEN_EXCLUSIVE flag into
7121 <a href="#sqlite3_open">sqlite3_open_v2()</a> does *not* cause the underlying database file
7122 to be opened using O_EXCL. Passing SQLITE_OPEN_EXCLUSIVE into
7123 <a href="#sqlite3_open">sqlite3_open_v2()</a> has historically been a no-op and might become an
7124 error in future versions of SQLite.
7125 </p><hr><a name="SQLITE_PREPARE_DONT_LOG"></a>
7126 <h2>Prepare Flags</h2>
7127 </div>
7128 <blockquote><pre>
7129 #define SQLITE_PREPARE_PERSISTENT 0x01
7130 #define SQLITE_PREPARE_NORMALIZE 0x02
7131 #define SQLITE_PREPARE_NO_VTAB 0x04
7132 #define SQLITE_PREPARE_DONT_LOG 0x10
7133 #define SQLITE_PREPARE_FROM_DDL 0x20
7134 </pre></blockquote>
7135 <p>
7136 These constants define various flags that can be passed into the
7137 "prepFlags" parameter of the <a href="#sqlite3_prepare">sqlite3_prepare_v3()</a> and
7138 <a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a> interfaces.</p>
7139
7140 <p>New flags may be added in future releases of SQLite.</p>
7141
7142 <p><dl>
7143 <a name="sqlitepreparepersistent"></a>
7144 <dt>SQLITE_PREPARE_PERSISTENT</dt>
7145 <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
7146 that the prepared statement will be retained for a long time and
7147 probably reused many times. Without this flag, <a href="#sqlite3_prepare">sqlite3_prepare_v3()</a>
7148 and <a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a> assume that the prepared statement will
7149 be used just once or at most a few times and then destroyed using
7150 <a href="#sqlite3_finalize">sqlite3_finalize()</a> relatively soon. The current implementation acts
7151 on this hint by avoiding the use of <a href="malloc.html#lookaside">lookaside memory</a> so as not to
7152 deplete the limited store of lookaside memory. Future versions of
7153 SQLite may act on this hint differently.</p>
7154
7155 <p><a name="sqlitepreparenormalize"></a>
7156 <dt>SQLITE_PREPARE_NORMALIZE</dt>
7157 <dd>The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used
7158 to be required for any prepared statement that wanted to use the
7159 <a href="#sqlite3_expanded_sql">sqlite3_normalized_sql()</a> interface. However, the
7160 <a href="#sqlite3_expanded_sql">sqlite3_normalized_sql()</a> interface is now available to all
7161 prepared statements, regardless of whether or not they use this
7162 flag.</p>
7163
7164 <p><a name="sqlitepreparenovtab"></a>
7165 <dt>SQLITE_PREPARE_NO_VTAB</dt>
7166 <dd>The SQLITE_PREPARE_NO_VTAB flag causes the SQL compiler
7167 to return an error (error code SQLITE_ERROR) if the statement uses
7168 any virtual tables.</p>
7169
7170 <p><a name="sqlitepreparedontlog"></a>
7171 <dt>SQLITE_PREPARE_DONT_LOG</dt>
7172 <dd>The SQLITE_PREPARE_DONT_LOG flag prevents SQL compiler
7173 errors from being sent to the error log defined by
7174 <a href="#sqliteconfiglog">SQLITE_CONFIG_LOG</a>. This can be used, for example, to do test
7175 compiles to see if some SQL syntax is well-formed, without generating
7176 messages on the global error log when it is not. If the test compile
7177 fails, the sqlite3_prepare_v3() call returns the same error indications
7178 with or without this flag; it just omits the call to <a href="#sqlite3_log">sqlite3_log()</a> that
7179 logs the error.</p>
7180
7181 <p><a name="sqlitepreparefromddl"></a>
7182 <dt>SQLITE_PREPARE_FROM_DDL</dt>
7183 <dd>The SQLITE_PREPARE_FROM_DDL flag causes the SQL compiler to enforce
7184 security constraints that would otherwise only be enforced when parsing
7185 the database schema. In other words, the SQLITE_PREPARE_FROM_DDL flag
7186 causes the SQL compiler to treat the SQL statement being prepared as if
7187 it had come from an attacker. When SQLITE_PREPARE_FROM_DDL is used and
7188 <a href="#sqlitedbconfigtrustedschema">SQLITE_DBCONFIG_TRUSTED_SCHEMA</a> is off, SQL functions may only be called
7189 if they are tagged with <a href="#sqliteinnocuous">SQLITE_INNOCUOUS</a> and virtual tables may only
7190 be used if they are tagged with <a href="#sqlitevtabinnocuous">SQLITE_VTAB_INNOCUOUS</a>. Best practice
7191 is to use the SQLITE_PREPARE_FROM_DDL option when preparing any SQL that
7192 is derived from parts of the database schema. In particular, virtual
7193 table implementations that run SQL statements that are derived from
7194 arguments to their CREATE VIRTUAL TABLE statement should always use
7195 <a href="#sqlite3_prepare">sqlite3_prepare_v3()</a> and set the SQLITE_PREPARE_FROM_DDL flag to
7196 prevent bypass of the <a href="#sqlitedbconfigtrustedschema">SQLITE_DBCONFIG_TRUSTED_SCHEMA</a> security checks.
7197 </dl>
7198 </p><hr><a name="SQLITE_SCANSTAT_COMPLEX"></a>
7199 <h2>Prepared Statement Scan Status</h2>
7200 </div>
7201 <blockquote><pre>
7202 #define SQLITE_SCANSTAT_COMPLEX 0x0001
7203 </pre></blockquote>
7204 <p></p><hr><a name="SQLITE_SCANSTAT_EST"></a>
7205 <h2>Prepared Statement Scan Status Opcodes</h2>
7206 </div>
7207 <blockquote><pre>
7208 #define SQLITE_SCANSTAT_NLOOP 0
7209 #define SQLITE_SCANSTAT_NVISIT 1
7210 #define SQLITE_SCANSTAT_EST 2
7211 #define SQLITE_SCANSTAT_NAME 3
7212 #define SQLITE_SCANSTAT_EXPLAIN 4
7213 #define SQLITE_SCANSTAT_SELECTID 5
7214 #define SQLITE_SCANSTAT_PARENTID 6
7215 #define SQLITE_SCANSTAT_NCYCLE 7
7216 </pre></blockquote>
7217 <p>
7218 The following constants can be used for the T parameter to the
7219 <a href="#sqlite3_stmt_scanstatus">sqlite3_stmt_scanstatus(S,X,T,V)</a> interface. Each constant designates a
7220 different metric for sqlite3_stmt_scanstatus() to return.</p>
7221
7222 <p>When the value returned to V is a string, space to hold that string is
7223 managed by the prepared statement S and will be automatically freed when
7224 S is finalized.</p>
7225
7226 <p>Not all values are available for all query elements. When a value is
7227 not available, the output variable is set to -1 if the value is numeric,
7228 or to NULL if it is a string (SQLITE_SCANSTAT_NAME).</p>
7229
7230 <p><dl>
7231 <a name="sqlitescanstatnloop"></a>
7232 <dt>SQLITE_SCANSTAT_NLOOP</dt>
7233 <dd>The <a href="#sqlite3_int64">sqlite3_int64</a> variable pointed to by the V parameter will be
7234 set to the total number of times that the X-th loop has run.</dd></p>
7235
7236 <p><a name="sqlitescanstatnvisit"></a>
7237 <dt>SQLITE_SCANSTAT_NVISIT</dt>
7238 <dd>The <a href="#sqlite3_int64">sqlite3_int64</a> variable pointed to by the V parameter will be set
7239 to the total number of rows examined by all iterations of the X-th loop.</dd></p>
7240
7241 <p><a name="sqlitescanstatest"></a>
7242 <dt>SQLITE_SCANSTAT_EST</dt>
7243 <dd>The "double" variable pointed to by the V parameter will be set to the
7244 query planner's estimate for the average number of rows output from each
7245 iteration of the X-th loop. If the query planner's estimate was accurate,
7246 then this value will approximate the quotient NVISIT/NLOOP and the
7247 product of this value for all prior loops with the same SELECTID will
7248 be the NLOOP value for the current loop.</dd></p>
7249
7250 <p><a name="sqlitescanstatname"></a>
7251 <dt>SQLITE_SCANSTAT_NAME</dt>
7252 <dd>The "const char *" variable pointed to by the V parameter will be set
7253 to a zero-terminated UTF-8 string containing the name of the index or table
7254 used for the X-th loop.</dd></p>
7255
7256 <p><a name="sqlitescanstatexplain"></a>
7257 <dt>SQLITE_SCANSTAT_EXPLAIN</dt>
7258 <dd>The "const char *" variable pointed to by the V parameter will be set
7259 to a zero-terminated UTF-8 string containing the <a href="eqp.html">EXPLAIN QUERY PLAN</a>
7260 description for the X-th loop.</dd></p>
7261
7262 <p><a name="sqlitescanstatselectid"></a>
7263 <dt>SQLITE_SCANSTAT_SELECTID</dt>
7264 <dd>The "int" variable pointed to by the V parameter will be set to the
7265 id for the X-th query plan element. The id value is unique within the
7266 statement. The select-id is the same value as is output in the first
7267 column of an <a href="eqp.html">EXPLAIN QUERY PLAN</a> query.</dd></p>
7268
7269 <p><a name="sqlitescanstatparentid"></a>
7270 <dt>SQLITE_SCANSTAT_PARENTID</dt>
7271 <dd>The "int" variable pointed to by the V parameter will be set to the
7272 id of the parent of the current query element, if applicable, or
7273 to zero if the query element has no parent. This is the same value as
7274 returned in the second column of an <a href="eqp.html">EXPLAIN QUERY PLAN</a> query.</dd></p>
7275
7276 <p><a name="sqlitescanstatncycle"></a>
7277 <dt>SQLITE_SCANSTAT_NCYCLE</dt>
7278 <dd>The sqlite3_int64 output value is set to the number of cycles,
7279 according to the processor time-stamp counter, that elapsed while the
7280 query element was being processed. This value is not available for
7281 all query elements - if it is unavailable the output variable is
7282 set to -1.</dd>
7283 </dl>
7284 </p><hr><a name="SQLITE_SCM_BRANCH"></a>
7285 <h2>Compile-Time Library Version Numbers</h2>
7286 </div>
7287 <blockquote><pre>
7288 #define SQLITE_VERSION "3.53.2"
7289 #define SQLITE_VERSION_NUMBER 3053002
7290 #define SQLITE_SOURCE_ID "2026-06-03 19:12:13 d6e03d8c777cfa2d35e3b60d8ec3e0187f3e9f99d8e2ee9cac695fd6fcdf1a24"
7291 #define SQLITE_SCM_BRANCH "branch-3.53"
7292 #define SQLITE_SCM_TAGS "release version-3.53.2"
7293 #define SQLITE_SCM_DATETIME "2026-06-03T19:12:13.350Z"
7294 </pre></blockquote>
7295 <p>
7296 The <a href="#SQLITE_SCM_BRANCH">SQLITE_VERSION</a> C preprocessor macro in the sqlite3.h header
7297 evaluates to a string literal that is the SQLite version in the
7298 format "X.Y.Z" where X is the major version number (always 3 for
7299 SQLite3) and Y is the minor version number and Z is the release number.
7300 The <a href="#SQLITE_SCM_BRANCH">SQLITE_VERSION_NUMBER</a> C preprocessor macro resolves to an integer
7301 with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
7302 numbers used in <a href="#SQLITE_SCM_BRANCH">SQLITE_VERSION</a>.
7303 The SQLITE_VERSION_NUMBER for any given release of SQLite will also
7304 be larger than the release from which it is derived. Either Y will
7305 be held constant and Z will be incremented or else Y will be incremented
7306 and Z will be reset to zero.</p>
7307
7308 <p>Since <a href="releaselog/3_6_18.html">version 3.6.18</a> (2009-09-11),
7309 SQLite source code has been stored in the
7310 <a href="http://fossil-scm.org/">Fossil configuration management
7311 system</a>. The SQLITE_SOURCE_ID macro evaluates to
7312 a string which identifies a particular check-in of SQLite
7313 within its configuration management system. The SQLITE_SOURCE_ID
7314 string contains the date and time of the check-in (UTC) and a SHA1
7315 or SHA3-256 hash of the entire source tree. If the source code has
7316 been edited in any way since it was last checked in, then the last
7317 four hexadecimal digits of the hash may be modified.</p>
7318
7319 <p>See also: <a href="#sqlite3_libversion">sqlite3_libversion()</a>,
7320 <a href="#sqlite3_libversion">sqlite3_libversion_number()</a>, <a href="#sqlite3_libversion">sqlite3_sourceid()</a>,
7321 <a href="lang_corefunc.html#sqlite_version">sqlite_version()</a> and <a href="lang_corefunc.html#sqlite_source_id">sqlite_source_id()</a>.
7322 </p><hr><a name="SQLITE_SHM_EXCLUSIVE"></a>
7323 <h2>Flags for the xShmLock VFS method</h2>
7324 </div>
7325 <blockquote><pre>
7326 #define SQLITE_SHM_UNLOCK 1
7327 #define SQLITE_SHM_LOCK 2
7328 #define SQLITE_SHM_SHARED 4
7329 #define SQLITE_SHM_EXCLUSIVE 8
7330 </pre></blockquote>
7331 <p>
7332 These integer constants define the various locking operations
7333 allowed by the xShmLock method of <a href="#sqlite3_io_methods">sqlite3_io_methods</a>. The
7334 following are the only legal combinations of flags to the
7335 xShmLock method:</p>
7336
7337 <p><ul>
7338 <li> SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
7339 <li> SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
7340 <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
7341 <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
7342 </ul></p>
7343
7344 <p>When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
7345 was given on the corresponding lock.</p>
7346
7347 <p>The xShmLock method can transition between unlocked and SHARED or
7348 between unlocked and EXCLUSIVE. It cannot transition between SHARED
7349 and EXCLUSIVE.
7350 </p><hr><a name="SQLITE_STATIC"></a>
7351 <h2>Constants Defining Special Destructor Behavior</h2>
7352 </div>
7353 <blockquote><pre>
7354 typedef void (*sqlite3_destructor_type)(void*);
7355 #define SQLITE_STATIC ((sqlite3_destructor_type)0)
7356 #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)
7357 </pre></blockquote>
7358 <p>
7359 These are special values for the destructor that is passed in as the
7360 final argument to routines like <a href="#sqlite3_result_blob">sqlite3_result_blob()</a>. If the destructor
7361 argument is SQLITE_STATIC, it means that the content pointer is constant
7362 and will never change. It does not need to be destroyed. The
7363 SQLITE_TRANSIENT value means that the content will likely change in
7364 the near future and that SQLite should make its own private copy of
7365 the content before returning.</p>
7366
7367 <p>The typedef is necessary to work around problems in certain
7368 C++ compilers.
7369 </p><hr><a name="SQLITE_STATUS_MALLOC_COUNT"></a>
7370 <h2>Status Parameters</h2>
7371 </div>
7372 <blockquote><pre>
7373 #define SQLITE_STATUS_MEMORY_USED 0
7374 #define SQLITE_STATUS_PAGECACHE_USED 1
7375 #define SQLITE_STATUS_PAGECACHE_OVERFLOW 2
7376 #define SQLITE_STATUS_SCRATCH_USED 3 /* NOT USED */
7377 #define SQLITE_STATUS_SCRATCH_OVERFLOW 4 /* NOT USED */
7378 #define SQLITE_STATUS_MALLOC_SIZE 5
7379 #define SQLITE_STATUS_PARSER_STACK 6
7380 #define SQLITE_STATUS_PAGECACHE_SIZE 7
7381 #define SQLITE_STATUS_SCRATCH_SIZE 8 /* NOT USED */
7382 #define SQLITE_STATUS_MALLOC_COUNT 9
7383 </pre></blockquote>
7384 <p>
7385 These integer constants designate various run-time status parameters
7386 that can be returned by <a href="#sqlite3_status">sqlite3_status()</a>.</p>
7387
7388 <p><dl>
7389 <a name="sqlitestatusmemoryused"></a>
7390 <dt>SQLITE_STATUS_MEMORY_USED</dt>
7391 <dd>This parameter is the current amount of memory checked out
7392 using <a href="#sqlite3_free">sqlite3_malloc()</a>, either directly or indirectly. The
7393 figure includes calls made to <a href="#sqlite3_free">sqlite3_malloc()</a> by the application
7394 and internal memory usage by the SQLite library. Auxiliary page-cache
7395 memory controlled by <a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a> is not included in
7396 this parameter. The amount returned is the sum of the allocation
7397 sizes as reported by the xSize method in <a href="#sqlite3_mem_methods">sqlite3_mem_methods</a>.</dd></p>
7398
7399 <p><a name="sqlitestatusmallocsize"></a>
7400 <dt>SQLITE_STATUS_MALLOC_SIZE</dt>
7401 <dd>This parameter records the largest memory allocation request
7402 handed to <a href="#sqlite3_free">sqlite3_malloc()</a> or <a href="#sqlite3_free">sqlite3_realloc()</a> (or their
7403 internal equivalents). Only the value returned in the
7404 *pHighwater parameter to <a href="#sqlite3_status">sqlite3_status()</a> is of interest.
7405 The value written into the *pCurrent parameter is undefined.</dd></p>
7406
7407 <p><a name="sqlitestatusmalloccount"></a>
7408 <dt>SQLITE_STATUS_MALLOC_COUNT</dt>
7409 <dd>This parameter records the number of separate memory allocations
7410 currently checked out.</dd></p>
7411
7412 <p><a name="sqlitestatuspagecacheused"></a>
7413 <dt>SQLITE_STATUS_PAGECACHE_USED</dt>
7414 <dd>This parameter returns the number of pages used out of the
7415 <a href="malloc.html#pagecache">pagecache memory allocator</a> that was configured using
7416 <a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>. The
7417 value returned is in pages, not in bytes.</dd></p>
7418
7419 <p><a name="sqlitestatuspagecacheoverflow"></a>
7420
7421 <dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>
7422 <dd>This parameter returns the number of bytes of page cache
7423 allocation which could not be satisfied by the <a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>
7424 buffer and where forced to overflow to <a href="#sqlite3_free">sqlite3_malloc()</a>. The
7425 returned value includes allocations that overflowed because they
7426 were too large (they were larger than the "sz" parameter to
7427 <a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>) and allocations that overflowed because
7428 no space was left in the page cache.</dd></p>
7429
7430 <p><a name="sqlitestatuspagecachesize"></a>
7431 <dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
7432 <dd>This parameter records the largest memory allocation request
7433 handed to the <a href="malloc.html#pagecache">pagecache memory allocator</a>. Only the value returned in the
7434 *pHighwater parameter to <a href="#sqlite3_status">sqlite3_status()</a> is of interest.
7435 The value written into the *pCurrent parameter is undefined.</dd></p>
7436
7437 <p><a name="sqlitestatusscratchused"></a>
7438 <dt>SQLITE_STATUS_SCRATCH_USED</dt>
7439 <dd>No longer used.</dd></p>
7440
7441 <p><a name="sqlitestatusscratchoverflow"></a>
7442 <dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
7443 <dd>No longer used.</dd></p>
7444
7445 <p><a name="sqlitestatusscratchsize"></a>
7446 <dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
7447 <dd>No longer used.</dd></p>
7448
7449 <p><a name="sqlitestatusparserstack"></a>
7450 <dt>SQLITE_STATUS_PARSER_STACK</dt>
7451 <dd>The *pHighwater parameter records the deepest parser stack.
7452 The *pCurrent value is undefined. The *pHighwater value is only
7453 meaningful if SQLite is compiled with <a href="compile.html#yytrackmaxstackdepth">YYTRACKMAXSTACKDEPTH</a>.</dd>
7454 </dl></p>
7455
7456 <p>New status parameters may be added from time to time.
7457 </p><hr><a name="SQLITE_SYNC_DATAONLY"></a>
7458 <h2>Synchronization Type Flags</h2>
7459 </div>
7460 <blockquote><pre>
7461 #define SQLITE_SYNC_NORMAL 0x00002
7462 #define SQLITE_SYNC_FULL 0x00003
7463 #define SQLITE_SYNC_DATAONLY 0x00010
7464 </pre></blockquote>
7465 <p>
7466 When SQLite invokes the xSync() method of an
7467 <a href="#sqlite3_io_methods">sqlite3_io_methods</a> object it uses a combination of
7468 these integer values as the second argument.</p>
7469
7470 <p>When the SQLITE_SYNC_DATAONLY flag is used, it means that the
7471 sync operation only needs to flush data to mass storage. Inode
7472 information need not be flushed. If the lower four bits of the flag
7473 equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
7474 If the lower four bits equal SQLITE_SYNC_FULL, that means
7475 to use Mac OS X style fullsync instead of fsync().</p>
7476
7477 <p>Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
7478 with the <a href="pragma.html#pragma_synchronous">PRAGMA synchronous</a>=NORMAL and <a href="pragma.html#pragma_synchronous">PRAGMA synchronous</a>=FULL
7479 settings. The <a href="pragma.html#pragma_synchronous">synchronous pragma</a> determines when calls to the
7480 xSync VFS method occur and applies uniformly across all platforms.
7481 The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
7482 energetic or rigorous or forceful the sync operations are and
7483 only make a difference on Mac OSX for the default SQLite code.
7484 (Third-party VFS implementations might also make the distinction
7485 between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
7486 operating systems natively supported by SQLite, only Mac OSX
7487 cares about the difference.)
7488 </p><hr><a name="SQLITE_TESTCTRL_ALWAYS"></a>
7489 <h2>Testing Interface Operation Codes</h2>
7490 </div>
7491 <blockquote><pre>
7492 #define SQLITE_TESTCTRL_FIRST 5
7493 #define SQLITE_TESTCTRL_PRNG_SAVE 5
7494 #define SQLITE_TESTCTRL_PRNG_RESTORE 6
7495 #define SQLITE_TESTCTRL_PRNG_RESET 7 /* NOT USED */
7496 #define SQLITE_TESTCTRL_FK_NO_ACTION 7
7497 #define SQLITE_TESTCTRL_BITVEC_TEST 8
7498 #define SQLITE_TESTCTRL_FAULT_INSTALL 9
7499 #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10
7500 #define SQLITE_TESTCTRL_PENDING_BYTE 11
7501 #define SQLITE_TESTCTRL_ASSERT 12
7502 #define SQLITE_TESTCTRL_ALWAYS 13
7503 #define SQLITE_TESTCTRL_RESERVE 14 /* NOT USED */
7504 #define SQLITE_TESTCTRL_JSON_SELFCHECK 14
7505 #define SQLITE_TESTCTRL_OPTIMIZATIONS 15
7506 #define SQLITE_TESTCTRL_ISKEYWORD 16 /* NOT USED */
7507 #define SQLITE_TESTCTRL_GETOPT 16
7508 #define SQLITE_TESTCTRL_SCRATCHMALLOC 17 /* NOT USED */
7509 #define SQLITE_TESTCTRL_INTERNAL_FUNCTIONS 17
7510 #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18
7511 #define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */
7512 #define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19
7513 #define SQLITE_TESTCTRL_NEVER_CORRUPT 20
7514 #define SQLITE_TESTCTRL_VDBE_COVERAGE 21
7515 #define SQLITE_TESTCTRL_BYTEORDER 22
7516 #define SQLITE_TESTCTRL_ISINIT 23
7517 #define SQLITE_TESTCTRL_SORTER_MMAP 24
7518 #define SQLITE_TESTCTRL_IMPOSTER 25
7519 #define SQLITE_TESTCTRL_PARSER_COVERAGE 26
7520 #define SQLITE_TESTCTRL_RESULT_INTREAL 27
7521 #define SQLITE_TESTCTRL_PRNG_SEED 28
7522 #define SQLITE_TESTCTRL_EXTRA_SCHEMA_CHECKS 29
7523 #define SQLITE_TESTCTRL_SEEK_COUNT 30
7524 #define SQLITE_TESTCTRL_TRACEFLAGS 31
7525 #define SQLITE_TESTCTRL_TUNE 32
7526 #define SQLITE_TESTCTRL_LOGEST 33
7527 #define SQLITE_TESTCTRL_USELONGDOUBLE 34 /* NOT USED */
7528 #define SQLITE_TESTCTRL_ATOF 34
7529 #define SQLITE_TESTCTRL_LAST 34 /* Largest TESTCTRL */
7530 </pre></blockquote>
7531 <p>
7532 These constants are the valid operation code parameters used
7533 as the first argument to <a href="#sqlite3_test_control">sqlite3_test_control()</a>.</p>
7534
7535 <p>These parameters and their meanings are subject to change
7536 without notice. These values are for testing purposes only.
7537 Applications should not use any of these parameters or the
7538 <a href="#sqlite3_test_control">sqlite3_test_control()</a> interface.
7539 </p><hr><a name="SQLITE_TRACE"></a>
7540 <h2>SQL Trace Event Codes</h2>
7541 </div>
7542 <blockquote><pre>
7543 #define SQLITE_TRACE_STMT 0x01
7544 #define SQLITE_TRACE_PROFILE 0x02
7545 #define SQLITE_TRACE_ROW 0x04
7546 #define SQLITE_TRACE_CLOSE 0x08
7547 </pre></blockquote>
7548 <p>
7549 These constants identify classes of events that can be monitored
7550 using the <a href="#sqlite3_trace_v2">sqlite3_trace_v2()</a> tracing logic. The M argument
7551 to <a href="#sqlite3_trace_v2">sqlite3_trace_v2(D,M,X,P)</a> is an OR-ed combination of one or more of
7552 the following constants. The first argument to the trace callback
7553 is one of the following constants.</p>
7554
7555 <p>New tracing constants may be added in future releases.</p>
7556
7557 <p>A trace callback has four arguments: xCallback(T,C,P,X).
7558 The T argument is one of the integer type codes above.
7559 The C argument is a copy of the context pointer passed in as the
7560 fourth argument to <a href="#sqlite3_trace_v2">sqlite3_trace_v2()</a>.
7561 The P and X arguments are pointers whose meanings depend on T.</p>
7562
7563 <p><dl>
7564 <a name="sqlitetracestmt"></a>
7565 <dt>SQLITE_TRACE_STMT</dt>
7566 <dd>An SQLITE_TRACE_STMT callback is invoked when a prepared statement
7567 first begins running and possibly at other times during the
7568 execution of the prepared statement, such as at the start of each
7569 trigger subprogram. The P argument is a pointer to the
7570 <a href="#sqlite3_stmt">prepared statement</a>. The X argument is a pointer to a string which
7571 is the unexpanded SQL text of the prepared statement or an SQL comment
7572 that indicates the invocation of a trigger. The callback can compute
7573 the same text that would have been returned by the legacy <a href="#sqlite3_profile">sqlite3_trace()</a>
7574 interface by using the X argument when X begins with "--" and invoking
7575 <a href="#sqlite3_expanded_sql">sqlite3_expanded_sql(P)</a> otherwise.</p>
7576
7577 <p><a name="sqlitetraceprofile"></a>
7578 <dt>SQLITE_TRACE_PROFILE</dt>
7579 <dd>An SQLITE_TRACE_PROFILE callback provides approximately the same
7580 information as is provided by the <a href="#sqlite3_profile">sqlite3_profile()</a> callback.
7581 The P argument is a pointer to the <a href="#sqlite3_stmt">prepared statement</a> and the
7582 X argument points to a 64-bit integer which is approximately
7583 the number of nanoseconds that the prepared statement took to run.
7584 The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.</p>
7585
7586 <p><a name="sqlitetracerow"></a>
7587 <dt>SQLITE_TRACE_ROW</dt>
7588 <dd>An SQLITE_TRACE_ROW callback is invoked whenever a prepared
7589 statement generates a single row of result.
7590 The P argument is a pointer to the <a href="#sqlite3_stmt">prepared statement</a> and the
7591 X argument is unused.</p>
7592
7593 <p><a name="sqlitetraceclose"></a>
7594 <dt>SQLITE_TRACE_CLOSE</dt>
7595 <dd>An SQLITE_TRACE_CLOSE callback is invoked when a database
7596 connection closes.
7597 The P argument is a pointer to the <a href="#sqlite3">database connection</a> object
7598 and the X argument is unused.
7599 </dl>
7600 </p><hr><a name="SQLITE_TXN_NONE"></a>
7601 <h2>Allowed return values from sqlite3_txn_state()</h2>
7602 </div>
7603 <blockquote><pre>
7604 #define SQLITE_TXN_NONE 0
7605 #define SQLITE_TXN_READ 1
7606 #define SQLITE_TXN_WRITE 2
7607 </pre></blockquote>
7608 <p>
7609 These constants define the current transaction state of a database file.
7610 The <a href="#sqlite3_txn_state">sqlite3_txn_state(D,S)</a> interface returns one of these
7611 constants in order to describe the transaction state of schema S
7612 in <a href="#sqlite3">database connection</a> D.</p>
7613
7614 <p><dl>
7615 <a name="sqlitetxnnone"></a>
7616 <dt>SQLITE_TXN_NONE</dt>
7617 <dd>The SQLITE_TXN_NONE state means that no transaction is currently
7618 pending.</dd></p>
7619
7620 <p><a name="sqlitetxnread"></a>
7621 <dt>SQLITE_TXN_READ</dt>
7622 <dd>The SQLITE_TXN_READ state means that the database is currently
7623 in a read transaction. Content has been read from the database file
7624 but nothing in the database file has changed. The transaction state
7625 will be advanced to SQLITE_TXN_WRITE if any changes occur and there are
7626 no other conflicting concurrent write transactions. The transaction
7627 state will revert to SQLITE_TXN_NONE following a <a href="lang_transaction.html">ROLLBACK</a> or
7628 <a href="lang_transaction.html">COMMIT</a>.</dd></p>
7629
7630 <p><a name="sqlitetxnwrite"></a>
7631 <dt>SQLITE_TXN_WRITE</dt>
7632 <dd>The SQLITE_TXN_WRITE state means that the database is currently
7633 in a write transaction. Content has been written to the database file
7634 but has not yet committed. The transaction state will change to
7635 SQLITE_TXN_NONE at the next <a href="lang_transaction.html">ROLLBACK</a> or <a href="lang_transaction.html">COMMIT</a>.</dd>
7636 </p><hr><a name="SQLITE_VTAB_CONSTRAINT_SUPPORT"></a>
7637 <h2>Virtual Table Configuration Options</h2>
7638 </div>
7639 <blockquote><pre>
7640 #define SQLITE_VTAB_CONSTRAINT_SUPPORT 1
7641 #define SQLITE_VTAB_INNOCUOUS 2
7642 #define SQLITE_VTAB_DIRECTONLY 3
7643 #define SQLITE_VTAB_USES_ALL_SCHEMAS 4
7644 </pre></blockquote>
7645 <p>
7646 These macros define the various options to the
7647 <a href="#sqlite3_vtab_config">sqlite3_vtab_config()</a> interface that <a href="vtab.html">virtual table</a> implementations
7648 can use to customize and optimize their behavior.</p>
7649
7650 <p><dl>
7651 <a name="sqlitevtabconstraintsupport"></a>
7652
7653 <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT</dt>
7654 <dd>Calls of the form
7655 <a href="#sqlite3_vtab_config">sqlite3_vtab_config</a>(db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported,
7656 where X is an integer. If X is zero, then the <a href="vtab.html">virtual table</a> whose
7657 <a href="vtab.html#xcreate">xCreate</a> or <a href="vtab.html#xconnect">xConnect</a> method invoked <a href="#sqlite3_vtab_config">sqlite3_vtab_config()</a> does not
7658 support constraints. In this configuration (which is the default) if
7659 a call to the <a href="vtab.html#xupdate">xUpdate</a> method returns <a href="#SQLITE_ABORT">SQLITE_CONSTRAINT</a>, then the entire
7660 statement is rolled back as if <a href="lang_conflict.html">OR ABORT</a> had been
7661 specified as part of the user's SQL statement, regardless of the actual
7662 ON CONFLICT mode specified.</p>
7663
7664 <p>If X is non-zero, then the virtual table implementation guarantees
7665 that if <a href="vtab.html#xupdate">xUpdate</a> returns <a href="#SQLITE_ABORT">SQLITE_CONSTRAINT</a>, it will do so before
7666 any modifications to internal or persistent data structures have been made.
7667 If the <a href="lang_conflict.html">ON CONFLICT</a> mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite
7668 is able to roll back a statement or database transaction, and abandon
7669 or continue processing the current SQL statement as appropriate.
7670 If the ON CONFLICT mode is REPLACE and the <a href="vtab.html#xupdate">xUpdate</a> method returns
7671 <a href="#SQLITE_ABORT">SQLITE_CONSTRAINT</a>, SQLite handles this as if the ON CONFLICT mode
7672 had been ABORT.</p>
7673
7674 <p>Virtual table implementations that are required to handle OR REPLACE
7675 must do so within the <a href="vtab.html#xupdate">xUpdate</a> method. If a call to the
7676 <a href="#sqlite3_vtab_on_conflict">sqlite3_vtab_on_conflict()</a> function indicates that the current ON
7677 CONFLICT policy is REPLACE, the virtual table implementation should
7678 silently replace the appropriate rows within the xUpdate callback and
7679 return SQLITE_OK. Or, if this is not possible, it may return
7680 SQLITE_CONSTRAINT, in which case SQLite falls back to OR ABORT
7681 constraint handling.
7682 </dd></p>
7683
7684 <p><a name="sqlitevtabdirectonly"></a>
7685 <dt>SQLITE_VTAB_DIRECTONLY</dt>
7686 <dd>Calls of the form
7687 <a href="#sqlite3_vtab_config">sqlite3_vtab_config</a>(db,SQLITE_VTAB_DIRECTONLY) from within the
7688 the <a href="vtab.html#xconnect">xConnect</a> or <a href="vtab.html#xcreate">xCreate</a> methods of a <a href="vtab.html">virtual table</a> implementation
7689 prohibits that virtual table from being used from within triggers and
7690 views.
7691 </dd></p>
7692
7693 <p><a name="sqlitevtabinnocuous"></a>
7694 <dt>SQLITE_VTAB_INNOCUOUS</dt>
7695 <dd>Calls of the form
7696 <a href="#sqlite3_vtab_config">sqlite3_vtab_config</a>(db,SQLITE_VTAB_INNOCUOUS) from within the
7697 <a href="vtab.html#xconnect">xConnect</a> or <a href="vtab.html#xcreate">xCreate</a> methods of a <a href="vtab.html">virtual table</a> implementation
7698 identify that virtual table as being safe to use from within triggers
7699 and views. Conceptually, the SQLITE_VTAB_INNOCUOUS tag means that the
7700 virtual table can do no serious harm even if it is controlled by a
7701 malicious hacker. Developers should avoid setting the SQLITE_VTAB_INNOCUOUS
7702 flag unless absolutely necessary.
7703 </dd></p>
7704
7705 <p><a name="sqlitevtabusesallschemas"></a>
7706 <dt>SQLITE_VTAB_USES_ALL_SCHEMAS</dt>
7707 <dd>Calls of the form
7708 <a href="#sqlite3_vtab_config">sqlite3_vtab_config</a>(db,SQLITE_VTAB_USES_ALL_SCHEMA) from within the
7709 the <a href="vtab.html#xconnect">xConnect</a> or <a href="vtab.html#xcreate">xCreate</a> methods of a <a href="vtab.html">virtual table</a> implementation
7710 instruct the query planner to begin at least a read transaction on
7711 all schemas ("main", "temp", and any ATTACH-ed databases) whenever the
7712 virtual table is used.
7713 </dd>
7714 </dl>
7715 </p><hr><a name="SQLITE_WIN32_DATA_DIRECTORY_TYPE"></a>
7716 <h2>Win32 Directory Types</h2>
7717 </div>
7718 <blockquote><pre>
7719 #define SQLITE_WIN32_DATA_DIRECTORY_TYPE 1
7720 #define SQLITE_WIN32_TEMP_DIRECTORY_TYPE 2
7721 </pre></blockquote>
7722 <p>
7723 These macros are only available on Windows. They define the allowed values
7724 for the type argument to the <a href="#sqlite3_win32_set_directory">sqlite3_win32_set_directory</a> interface.
7725 </p><hr><a name="SQLITE_LIMIT_ATTACHED"></a>
7726 <h2>Run-Time Limit Categories</h2>
7727 </div>
7728 <blockquote><pre>
7729 #define SQLITE_LIMIT_LENGTH 0
7730 #define SQLITE_LIMIT_SQL_LENGTH 1
7731 #define SQLITE_LIMIT_COLUMN 2
7732 #define SQLITE_LIMIT_EXPR_DEPTH 3
7733 #define SQLITE_LIMIT_COMPOUND_SELECT 4
7734 #define SQLITE_LIMIT_VDBE_OP 5
7735 #define SQLITE_LIMIT_FUNCTION_ARG 6
7736 #define SQLITE_LIMIT_ATTACHED 7
7737 #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8
7738 #define SQLITE_LIMIT_VARIABLE_NUMBER 9
7739 #define SQLITE_LIMIT_TRIGGER_DEPTH 10
7740 #define SQLITE_LIMIT_WORKER_THREADS 11
7741 #define SQLITE_LIMIT_PARSER_DEPTH 12
7742 </pre></blockquote>
7743 <p>
7744 These constants define various performance limits
7745 that can be lowered at run-time using <a href="#sqlite3_limit">sqlite3_limit()</a>.
7746 A concise description of these limits follows, and additional information
7747 is available at <a href="limits.html">Limits in SQLite</a>.</p>
7748
7749 <p><dl>
7750 <a name="sqlitelimitlength"></a>
7751 <dt>SQLITE_LIMIT_LENGTH</dt>
7752 <dd>The maximum size of any string or BLOB or table row, in bytes.<dd></p>
7753
7754 <p><a name="sqlitelimitsqllength"></a>
7755 <dt>SQLITE_LIMIT_SQL_LENGTH</dt>
7756 <dd>The maximum length of an SQL statement, in bytes.</dd></p>
7757
7758 <p><a name="sqlitelimitcolumn"></a>
7759 <dt>SQLITE_LIMIT_COLUMN</dt>
7760 <dd>The maximum number of columns in a table definition or in the
7761 result set of a <a href="lang_select.html">SELECT</a> or the maximum number of columns in an index
7762 or in an ORDER BY or GROUP BY clause.</dd></p>
7763
7764 <p><a name="sqlitelimitexprdepth"></a>
7765 <dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
7766 <dd>The maximum depth of the parse tree on any expression.</dd></p>
7767
7768 <p><a name="sqlitelimitparserdepth"></a>
7769 <dt>SQLITE_LIMIT_PARSER_DEPTH</dt>
7770 <dd>The maximum depth of the LALR(1) parser stack used to analyze
7771 input SQL statements.</dd></p>
7772
7773 <p><a name="sqlitelimitcompoundselect"></a>
7774 <dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
7775 <dd>The maximum number of terms in a compound SELECT statement.</dd></p>
7776
7777 <p><a name="sqlitelimitvdbeop"></a>
7778 <dt>SQLITE_LIMIT_VDBE_OP</dt>
7779 <dd>The maximum number of instructions in a virtual machine program
7780 used to implement an SQL statement. If <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or
7781 the equivalent tries to allocate space for more than this many opcodes
7782 in a single prepared statement, an SQLITE_NOMEM error is returned.</dd></p>
7783
7784 <p><a name="sqlitelimitfunctionarg"></a>
7785 <dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
7786 <dd>The maximum number of arguments on a function.</dd></p>
7787
7788 <p><a name="sqlitelimitattached"></a>
7789 <dt>SQLITE_LIMIT_ATTACHED</dt>
7790 <dd>The maximum number of <a href="lang_attach.html">attached databases</a>.</dd></p>
7791
7792 <p><a name="sqlitelimitlikepatternlength"></a>
7793
7794 <dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
7795 <dd>The maximum length of the pattern argument to the <a href="lang_expr.html#like">LIKE</a> or
7796 <a href="lang_expr.html#glob">GLOB</a> operators.</dd></p>
7797
7798 <p><a name="sqlitelimitvariablenumber"></a>
7799
7800 <dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
7801 <dd>The maximum index number of any <a href="lang_expr.html#varparam">parameter</a> in an SQL statement.</p>
7802
7803 <p><a name="sqlitelimittriggerdepth"></a>
7804 <dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
7805 <dd>The maximum depth of recursion for triggers.</dd></p>
7806
7807 <p><a name="sqlitelimitworkerthreads"></a>
7808 <dt>SQLITE_LIMIT_WORKER_THREADS</dt>
7809 <dd>The maximum number of auxiliary worker threads that a single
7810 <a href="#sqlite3_stmt">prepared statement</a> may start.</dd>
7811 </dl>
7812 </p><hr><a name="SQLITE_DBSTATUS options"></a>
7813 <h2>Status Parameters for database connections</h2>
7814 </div>
7815 <blockquote><pre>
7816 #define SQLITE_DBSTATUS_LOOKASIDE_USED 0
7817 #define SQLITE_DBSTATUS_CACHE_USED 1
7818 #define SQLITE_DBSTATUS_SCHEMA_USED 2
7819 #define SQLITE_DBSTATUS_STMT_USED 3
7820 #define SQLITE_DBSTATUS_LOOKASIDE_HIT 4
7821 #define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5
7822 #define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6
7823 #define SQLITE_DBSTATUS_CACHE_HIT 7
7824 #define SQLITE_DBSTATUS_CACHE_MISS 8
7825 #define SQLITE_DBSTATUS_CACHE_WRITE 9
7826 #define SQLITE_DBSTATUS_DEFERRED_FKS 10
7827 #define SQLITE_DBSTATUS_CACHE_USED_SHARED 11
7828 #define SQLITE_DBSTATUS_CACHE_SPILL 12
7829 #define SQLITE_DBSTATUS_TEMPBUF_SPILL 13
7830 #define SQLITE_DBSTATUS_MAX 13 /* Largest defined DBSTATUS */
7831 </pre></blockquote>
7832 <p>
7833 These constants are the available integer "verbs" that can be passed as
7834 the second argument to the <a href="#sqlite3_db_status">sqlite3_db_status()</a> interface.</p>
7835
7836 <p>New verbs may be added in future releases of SQLite. Existing verbs
7837 might be discontinued. Applications should check the return code from
7838 <a href="#sqlite3_db_status">sqlite3_db_status()</a> to make sure that the call worked.
7839 The <a href="#sqlite3_db_status">sqlite3_db_status()</a> interface will return a non-zero error code
7840 if a discontinued or unsupported verb is invoked.</p>
7841
7842 <p><dl>
7843 <a name="sqlitedbstatuslookasideused"></a>
7844 <dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
7845 <dd>This parameter returns the number of lookaside memory slots currently
7846 checked out.</dd></p>
7847
7848 <p><a name="sqlitedbstatuslookasidehit"></a>
7849 <dt>SQLITE_DBSTATUS_LOOKASIDE_HIT</dt>
7850 <dd>This parameter returns the number of malloc attempts that were
7851 satisfied using lookaside memory. Only the high-water value is meaningful;
7852 the current value is always zero.</dd></p>
7853
7854 <p><a name="sqlitedbstatuslookasidemisssize"></a>
7855
7856 <dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE</dt>
7857 <dd>This parameter returns the number of malloc attempts that might have
7858 been satisfied using lookaside memory but failed due to the amount of
7859 memory requested being larger than the lookaside slot size.
7860 Only the high-water value is meaningful;
7861 the current value is always zero.</dd></p>
7862
7863 <p><a name="sqlitedbstatuslookasidemissfull"></a>
7864
7865 <dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL</dt>
7866 <dd>This parameter returns the number of malloc attempts that might have
7867 been satisfied using lookaside memory but failed due to all lookaside
7868 memory already being in use.
7869 Only the high-water value is meaningful;
7870 the current value is always zero.</dd></p>
7871
7872 <p><a name="sqlitedbstatuscacheused"></a>
7873 <dt>SQLITE_DBSTATUS_CACHE_USED</dt>
7874 <dd>This parameter returns the approximate number of bytes of heap
7875 memory used by all pager caches associated with the database connection.
7876 The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.
7877 </dd></p>
7878
7879 <p><a name="sqlitedbstatuscacheusedshared"></a>
7880
7881 <dt>SQLITE_DBSTATUS_CACHE_USED_SHARED</dt>
7882 <dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a
7883 pager cache is shared between two or more connections the bytes of heap
7884 memory used by that pager cache is divided evenly between the attached
7885 connections. In other words, if none of the pager caches associated
7886 with the database connection are shared, this request returns the same
7887 value as DBSTATUS_CACHE_USED. Or, if one or more of the pager caches are
7888 shared, the value returned by this call will be smaller than that returned
7889 by DBSTATUS_CACHE_USED. The highwater mark associated with
7890 SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0.</dd></p>
7891
7892 <p><a name="sqlitedbstatusschemaused"></a>
7893 <dt>SQLITE_DBSTATUS_SCHEMA_USED</dt>
7894 <dd>This parameter returns the approximate number of bytes of heap
7895 memory used to store the schema for all databases associated
7896 with the connection - main, temp, and any <a href="lang_attach.html">ATTACH</a>-ed databases.
7897 The full amount of memory used by the schemas is reported, even if the
7898 schema memory is shared with other database connections due to
7899 <a href="sharedcache.html">shared cache mode</a> being enabled.
7900 The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.
7901 </dd></p>
7902
7903 <p><a name="sqlitedbstatusstmtused"></a>
7904 <dt>SQLITE_DBSTATUS_STMT_USED</dt>
7905 <dd>This parameter returns the approximate number of bytes of heap
7906 and lookaside memory used by all prepared statements associated with
7907 the database connection.
7908 The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.
7909 </dd></p>
7910
7911 <p><a name="sqlitedbstatuscachehit"></a>
7912 <dt>SQLITE_DBSTATUS_CACHE_HIT</dt>
7913 <dd>This parameter returns the number of pager cache hits that have
7914 occurred. The highwater mark associated with SQLITE_DBSTATUS_CACHE_HIT
7915 is always 0.
7916 </dd></p>
7917
7918 <p><a name="sqlitedbstatuscachemiss"></a>
7919 <dt>SQLITE_DBSTATUS_CACHE_MISS</dt>
7920 <dd>This parameter returns the number of pager cache misses that have
7921 occurred. The highwater mark associated with SQLITE_DBSTATUS_CACHE_MISS
7922 is always 0.
7923 </dd></p>
7924
7925 <p><a name="sqlitedbstatuscachewrite"></a>
7926 <dt>SQLITE_DBSTATUS_CACHE_WRITE</dt>
7927 <dd>This parameter returns the number of dirty cache entries that have
7928 been written to disk. Specifically, the number of pages written to the
7929 wal file in wal mode databases, or the number of pages written to the
7930 database file in rollback mode databases. Any pages written as part of
7931 transaction rollback or database recovery operations are not included.
7932 If an IO or other error occurs while writing a page to disk, the effect
7933 on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined. The
7934 highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0.
7935 <p>
7936 There is overlap between the quantities measured by this parameter
7937 (SQLITE_DBSTATUS_CACHE_WRITE) and SQLITE_DBSTATUS_TEMPBUF_SPILL.
7938 Resetting one will reduce the other.
7939 </dd></p>
7940
7941 <p><a name="sqlitedbstatuscachespill"></a>
7942 <dt>SQLITE_DBSTATUS_CACHE_SPILL</dt>
7943 <dd>This parameter returns the number of dirty cache entries that have
7944 been written to disk in the middle of a transaction due to the page
7945 cache overflowing. Transactions are more efficient if they are written
7946 to disk all at once. When pages spill mid-transaction, that introduces
7947 additional overhead. This parameter can be used to help identify
7948 inefficiencies that can be resolved by increasing the cache size.
7949 </dd></p>
7950
7951 <p><a name="sqlitedbstatusdeferredfks"></a>
7952 <dt>SQLITE_DBSTATUS_DEFERRED_FKS</dt>
7953 <dd>This parameter returns zero for the current value if and only if
7954 all foreign key constraints (deferred or immediate) have been
7955 resolved. The highwater mark is always 0.</p>
7956
7957 <p><a href="#SQLITE_DBSTATUS options">[SQLITE_DBSTATUS_TEMPBUF_SPILL</a> <dt>SQLITE_DBSTATUS_TEMPBUF_SPILL</dt>
7958 <dd>This parameter returns the number of bytes written to temporary
7959 files on disk that could have been kept in memory had sufficient memory
7960 been available. This value includes writes to intermediate tables that
7961 are part of complex queries, external sorts that spill to disk, and
7962 writes to TEMP tables.
7963 The highwater mark is always 0.
7964 <p>
7965 There is overlap between the quantities measured by this parameter
7966 (SQLITE_DBSTATUS_TEMPBUF_SPILL) and SQLITE_DBSTATUS_CACHE_WRITE.
7967 Resetting one will reduce the other.
7968 </dd>
7969 </dl>
7970 </p><hr><a name="SQLITE_STMTSTATUS counter"></a>
7971 <h2>Status Parameters for prepared statements</h2>
7972 </div>
7973 <blockquote><pre>
7974 #define SQLITE_STMTSTATUS_FULLSCAN_STEP 1
7975 #define SQLITE_STMTSTATUS_SORT 2
7976 #define SQLITE_STMTSTATUS_AUTOINDEX 3
7977 #define SQLITE_STMTSTATUS_VM_STEP 4
7978 #define SQLITE_STMTSTATUS_REPREPARE 5
7979 #define SQLITE_STMTSTATUS_RUN 6
7980 #define SQLITE_STMTSTATUS_FILTER_MISS 7
7981 #define SQLITE_STMTSTATUS_FILTER_HIT 8
7982 #define SQLITE_STMTSTATUS_MEMUSED 99
7983 </pre></blockquote>
7984 <p>
7985 These preprocessor macros define integer codes that name counter
7986 values associated with the <a href="#sqlite3_stmt_status">sqlite3_stmt_status()</a> interface.
7987 The meanings of the various counters are as follows:</p>
7988
7989 <p><dl>
7990 <a name="sqlitestmtstatusfullscanstep"></a>
7991 <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt>
7992 <dd>This is the number of times that SQLite has stepped forward in
7993 a table as part of a full table scan. Large numbers for this counter
7994 may indicate opportunities for performance improvement through
7995 careful use of indices.</dd></p>
7996
7997 <p><a name="sqlitestmtstatussort"></a>
7998 <dt>SQLITE_STMTSTATUS_SORT</dt>
7999 <dd>This is the number of sort operations that have occurred.
8000 A non-zero value in this counter may indicate an opportunity to
8001 improve performance through careful use of indices.</dd></p>
8002
8003 <p><a name="sqlitestmtstatusautoindex"></a>
8004 <dt>SQLITE_STMTSTATUS_AUTOINDEX</dt>
8005 <dd>This is the number of rows inserted into transient indices that
8006 were created automatically in order to help joins run faster.
8007 A non-zero value in this counter may indicate an opportunity to
8008 improve performance by adding permanent indices that do not
8009 need to be reinitialized each time the statement is run.</dd></p>
8010
8011 <p><a name="sqlitestmtstatusvmstep"></a>
8012 <dt>SQLITE_STMTSTATUS_VM_STEP</dt>
8013 <dd>This is the number of virtual machine operations executed
8014 by the prepared statement if that number is less than or equal
8015 to 2147483647. The number of virtual machine operations can be
8016 used as a proxy for the total work done by the prepared statement.
8017 If the number of virtual machine operations exceeds 2147483647
8018 then the value returned by this statement status code is undefined.</dd></p>
8019
8020 <p><a name="sqlitestmtstatusreprepare"></a>
8021 <dt>SQLITE_STMTSTATUS_REPREPARE</dt>
8022 <dd>This is the number of times that the prepare statement has been
8023 automatically regenerated due to schema changes or changes to
8024 <a href="lang_expr.html#varparam">bound parameters</a> that might affect the query plan.</dd></p>
8025
8026 <p><a name="sqlitestmtstatusrun"></a>
8027 <dt>SQLITE_STMTSTATUS_RUN</dt>
8028 <dd>This is the number of times that the prepared statement has
8029 been run. A single "run" for the purposes of this counter is one
8030 or more calls to <a href="#sqlite3_step">sqlite3_step()</a> followed by a call to <a href="#sqlite3_reset">sqlite3_reset()</a>.
8031 The counter is incremented on the first <a href="#sqlite3_step">sqlite3_step()</a> call of each
8032 cycle.</dd></p>
8033
8034 <p><a name="sqlitestmtstatusfiltermiss"></a>
8035
8036 <a name="sqlitestmtstatusfilterhit"></a>
8037
8038 <dt>SQLITE_STMTSTATUS_FILTER_HIT<br>
8039 SQLITE_STMTSTATUS_FILTER_MISS</dt>
8040 <dd>SQLITE_STMTSTATUS_FILTER_HIT is the number of times that a join
8041 step was bypassed because a Bloom filter returned not-found. The
8042 corresponding SQLITE_STMTSTATUS_FILTER_MISS value is the number of
8043 times that the Bloom filter returned a find, and thus the join step
8044 had to be processed as normal.</dd></p>
8045
8046 <p><a name="sqlitestmtstatusmemused"></a>
8047 <dt>SQLITE_STMTSTATUS_MEMUSED</dt>
8048 <dd>This is the approximate number of bytes of heap memory
8049 used to store the prepared statement. This value is not actually
8050 a counter, and so the resetFlg parameter to sqlite3_stmt_status()
8051 is ignored when the opcode is SQLITE_STMTSTATUS_MEMUSED.
8052 </dd>
8053 </dl>
8054 </p><hr><a name="sqlite3_snapshot"></a>
8055 <h2>Database Snapshot</h2>
8056 </div>
8057 <blockquote><pre>
8058 typedef struct sqlite3_snapshot {
8059 unsigned char hidden[48];
8060 } sqlite3_snapshot;
8061 </pre></blockquote>
8062 <p>
8063 An instance of the snapshot object records the state of a <a href="wal.html">WAL mode</a>
8064 database for some specific point in history.</p>
8065
8066 <p>In <a href="wal.html">WAL mode</a>, multiple <a href="#sqlite3">database connections</a> that are open on the
8067 same database file can each be reading a different historical version
8068 of the database file. When a <a href="#sqlite3">database connection</a> begins a read
8069 transaction, that connection sees an unchanging copy of the database
8070 as it existed for the point in time when the transaction first started.
8071 Subsequent changes to the database from other connections are not seen
8072 by the reader until a new read transaction is started.</p>
8073
8074 <p>The sqlite3_snapshot object records state information about an historical
8075 version of the database file so that it is possible to later open a new read
8076 transaction that sees that historical version of the database rather than
8077 the most recent version.
8078 </p><p>1 Constructor using this object: <a href="#sqlite3_snapshot_get">sqlite3_snapshot_get()</a></p>
8079 <p>1 Destructor using this object: <a href="#sqlite3_snapshot_free">sqlite3_snapshot_free()</a></p>
8080 <p>3 Methods using this object:
8081 <a href="#sqlite3_snapshot_cmp">sqlite3_snapshot_cmp()</a>,
8082 <a href="#sqlite3_snapshot_open">sqlite3_snapshot_open()</a>,
8083 <a href="#sqlite3_snapshot_recover">sqlite3_snapshot_recover()</a></p>
8084 <hr><a name="sqlite3_int64"></a>
8085 <h2>64-Bit Integer Types</h2>
8086 </div>
8087 <blockquote><pre>
8088 #ifdef SQLITE_INT64_TYPE
8089 typedef SQLITE_INT64_TYPE sqlite_int64;
8090 # ifdef SQLITE_UINT64_TYPE
8091 typedef SQLITE_UINT64_TYPE sqlite_uint64;
8092 # else
8093 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
8094 # endif
8095 #elif defined(_MSC_VER) || defined(__BORLANDC__)
8096 typedef __int64 sqlite_int64;
8097 typedef unsigned __int64 sqlite_uint64;
8098 #else
8099 typedef long long int sqlite_int64;
8100 typedef unsigned long long int sqlite_uint64;
8101 #endif
8102 typedef sqlite_int64 sqlite3_int64;
8103 typedef sqlite_uint64 sqlite3_uint64;
8104 </pre></blockquote>
8105 <p>
8106 Because there is no cross-platform way to specify 64-bit integer types
8107 SQLite includes typedefs for 64-bit signed and unsigned integers.</p>
8108
8109 <p>The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
8110 The sqlite_int64 and sqlite_uint64 types are supported for backwards
8111 compatibility only.</p>
8112
8113 <p>The sqlite3_int64 and sqlite_int64 types can store integer values
8114 between -9223372036854775808 and +9223372036854775807 inclusive. The
8115 sqlite3_uint64 and sqlite_uint64 types can store integer values
8116 between 0 and +18446744073709551615 inclusive.
8117 </p><hr><a name="sqlite3_module"></a>
8118 <h2>Virtual Table Object</h2>
8119 </div>
8120 <blockquote><pre>
8121 struct sqlite3_module {
8122 int iVersion;
8123 int (*xCreate)(sqlite3*, void *pAux,
8124 int argc, const char *const*argv,
8125 sqlite3_vtab **ppVTab, char**);
8126 int (*xConnect)(sqlite3*, void *pAux,
8127 int argc, const char *const*argv,
8128 sqlite3_vtab **ppVTab, char**);
8129 int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
8130 int (*xDisconnect)(sqlite3_vtab *pVTab);
8131 int (*xDestroy)(sqlite3_vtab *pVTab);
8132 int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
8133 int (*xClose)(sqlite3_vtab_cursor*);
8134 int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
8135 int argc, sqlite3_value **argv);
8136 int (*xNext)(sqlite3_vtab_cursor*);
8137 int (*xEof)(sqlite3_vtab_cursor*);
8138 int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
8139 int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
8140 int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
8141 int (*xBegin)(sqlite3_vtab *pVTab);
8142 int (*xSync)(sqlite3_vtab *pVTab);
8143 int (*xCommit)(sqlite3_vtab *pVTab);
8144 int (*xRollback)(sqlite3_vtab *pVTab);
8145 int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
8146 void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
8147 void **ppArg);
8148 int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
8149 /* The methods above are in version 1 of the sqlite_module object. Those
8150 ** below are for version 2 and greater. */
8151 int (*xSavepoint)(sqlite3_vtab *pVTab, int);
8152 int (*xRelease)(sqlite3_vtab *pVTab, int);
8153 int (*xRollbackTo)(sqlite3_vtab *pVTab, int);
8154 /* The methods above are in versions 1 and 2 of the sqlite_module object.
8155 ** Those below are for version 3 and greater. */
8156 int (*xShadowName)(const char*);
8157 /* The methods above are in versions 1 through 3 of the sqlite_module object.
8158 ** Those below are for version 4 and greater. */
8159 int (*xIntegrity)(sqlite3_vtab *pVTab, const char *zSchema,
8160 const char *zTabName, int mFlags, char **pzErr);
8161 };
8162 </pre></blockquote>
8163 <p>
8164 This structure, sometimes called a "virtual table module",
8165 defines the implementation of a <a href="vtab.html">virtual table</a>.
8166 This structure consists mostly of methods for the module.</p>
8167
8168 <p>A virtual table module is created by filling in a persistent
8169 instance of this structure and passing a pointer to that instance
8170 to <a href="#sqlite3_create_module">sqlite3_create_module()</a> or <a href="#sqlite3_create_module">sqlite3_create_module_v2()</a>.
8171 The registration remains valid until it is replaced by a different
8172 module or until the <a href="#sqlite3">database connection</a> closes. The content
8173 of this structure must not change while it is registered with
8174 any database connection.
8175 </p><hr><a name="sqlite3_vtab_cursor"></a>
8176 <h2>Virtual Table Cursor Object</h2>
8177 </div>
8178 <blockquote><pre>
8179 struct sqlite3_vtab_cursor {
8180 sqlite3_vtab *pVtab; /* Virtual table of this cursor */
8181 /* Virtual table implementations will typically add additional fields */
8182 };
8183 </pre></blockquote>
8184 <p>
8185 Every <a href="#sqlite3_module">virtual table module</a> implementation uses a subclass of the
8186 following structure to describe cursors that point into the
8187 <a href="vtab.html">virtual table</a> and are used
8188 to loop through the virtual table. Cursors are created using the
8189 <a href="vtab.html#xopen">xOpen</a> method of the module and are destroyed
8190 by the <a href="vtab.html#xclose">xClose</a> method. Cursors are used
8191 by the <a href="vtab.html#xfilter">xFilter</a>, <a href="vtab.html#xnext">xNext</a>, <a href="vtab.html#xeof">xEof</a>, <a href="vtab.html#xcolumn">xColumn</a>, and <a href="vtab.html#xrowid">xRowid</a> methods
8192 of the module. Each module implementation will define
8193 the content of a cursor structure to suit its own needs.</p>
8194
8195 <p>This superclass exists in order to define fields of the cursor that
8196 are common to all implementations.
8197 </p><hr><a name="sqlite3_blob"></a>
8198 <h2>A Handle To An Open BLOB</h2>
8199 </div>
8200 <blockquote><pre>
8201 typedef struct sqlite3_blob sqlite3_blob;
8202 </pre></blockquote>
8203 <p>
8204 An instance of this object represents an open BLOB on which
8205 <a href="#sqlite3_blob_open">incremental BLOB I/O</a> can be performed.
8206 Objects of this type are created by <a href="#sqlite3_blob_open">sqlite3_blob_open()</a>
8207 and destroyed by <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>.
8208 The <a href="#sqlite3_blob_read">sqlite3_blob_read()</a> and <a href="#sqlite3_blob_write">sqlite3_blob_write()</a> interfaces
8209 can be used to read or write small subsections of the BLOB.
8210 The <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> interface returns the size of the BLOB in bytes.
8211 </p><p>1 Constructor using this object: <a href="#sqlite3_blob_open">sqlite3_blob_open()</a></p>
8212 <p>1 Destructor using this object: <a href="#sqlite3_blob_close">sqlite3_blob_close()</a></p>
8213 <p>4 Methods using this object:
8214 <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a>,
8215 <a href="#sqlite3_blob_read">sqlite3_blob_read()</a>,
8216 <a href="#sqlite3_blob_reopen">sqlite3_blob_reopen()</a>,
8217 <a href="#sqlite3_blob_write">sqlite3_blob_write()</a></p>
8218 <hr><a name="sqlite3"></a>
8219 <h2>Database Connection Handle</h2>
8220 </div>
8221 <blockquote><pre>
8222 typedef struct sqlite3 sqlite3;
8223 </pre></blockquote>
8224 <p>
8225 Each open SQLite database is represented by a pointer to an instance of
8226 the opaque structure named "sqlite3". It is useful to think of an sqlite3
8227 pointer as an object. The <a href="#sqlite3_open">sqlite3_open()</a>, <a href="#sqlite3_open">sqlite3_open16()</a>, and
8228 <a href="#sqlite3_open">sqlite3_open_v2()</a> interfaces are its constructors, and <a href="#sqlite3_close">sqlite3_close()</a>
8229 and <a href="#sqlite3_close">sqlite3_close_v2()</a> are its destructors. There are many other
8230 interfaces (such as
8231 <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>, <a href="#sqlite3_create_function">sqlite3_create_function()</a>, and
8232 <a href="#sqlite3_busy_timeout">sqlite3_busy_timeout()</a> to name but three) that are methods on an
8233 sqlite3 object.
8234 </p><p>3 Constructors using this object:
8235 <a href="#sqlite3_open">sqlite3_open()</a>,
8236 <a href="#sqlite3_open">sqlite3_open16()</a>,
8237 <a href="#sqlite3_open">sqlite3_open_v2()</a></p>
8238 <p>2 Destructors using this object:
8239 <a href="#sqlite3_close">sqlite3_close()</a>,
8240 <a href="#sqlite3_close">sqlite3_close_v2()</a></p>
8241 <p>80 Methods using this object:
8242 <div class='columns' style='columns: 17em auto;'>
8243 <ul style='padding-top:0;'>
8244 <li><a href='#sqlite3_autovacuum_pages'>sqlite3_autovacuum_pages</a></li>
8245 <li><a href='#sqlite3_blob_open'>sqlite3_blob_open</a></li>
8246 <li><a href='#sqlite3_busy_handler'>sqlite3_busy_handler</a></li>
8247 <li><a href='#sqlite3_busy_timeout'>sqlite3_busy_timeout</a></li>
8248 <li><a href='#sqlite3_changes'>sqlite3_changes</a></li>
8249 <li><a href='#sqlite3_changes'>sqlite3_changes64</a></li>
8250 <li><a href='#sqlite3_collation_needed'>sqlite3_collation_needed</a></li>
8251 <li><a href='#sqlite3_collation_needed'>sqlite3_collation_needed16</a></li>
8252 <li><a href='#sqlite3_commit_hook'>sqlite3_commit_hook</a></li>
8253 <li><a href='#sqlite3_create_collation'>sqlite3_create_collation</a></li>
8254 <li><a href='#sqlite3_create_collation'>sqlite3_create_collation16</a></li>
8255 <li><a href='#sqlite3_create_collation'>sqlite3_create_collation_v2</a></li>
8256 <li><a href='#sqlite3_create_function'>sqlite3_create_function</a></li>
8257 <li><a href='#sqlite3_create_function'>sqlite3_create_function16</a></li>
8258 <li><a href='#sqlite3_create_function'>sqlite3_create_function_v2</a></li>
8259 <li><a href='#sqlite3_create_module'>sqlite3_create_module</a></li>
8260 <li><a href='#sqlite3_create_module'>sqlite3_create_module_v2</a></li>
8261 <li><a href='#sqlite3_create_function'>sqlite3_create_window_function</a></li>
8262 <li><a href='#sqlite3_db_cacheflush'>sqlite3_db_cacheflush</a></li>
8263 <li><a href='#sqlite3_db_config'>sqlite3_db_config</a></li>
8264 <li><a href='#sqlite3_db_filename'>sqlite3_db_filename</a></li>
8265 <li><a href='#sqlite3_db_mutex'>sqlite3_db_mutex</a></li>
8266 <li><a href='#sqlite3_db_name'>sqlite3_db_name</a></li>
8267 <li><a href='#sqlite3_db_readonly'>sqlite3_db_readonly</a></li>
8268 <li><a href='#sqlite3_db_release_memory'>sqlite3_db_release_memory</a></li>
8269 <li><a href='#sqlite3_db_status'>sqlite3_db_status</a></li>
8270 <li><a href='#sqlite3_db_status'>sqlite3_db_status64</a></li>
8271 <li><a href='#sqlite3_drop_modules'>sqlite3_drop_modules</a></li>
8272 <li><a href='#sqlite3_enable_load_extension'>sqlite3_enable_load_extension</a></li>
8273 <li><a href='#sqlite3_errcode'>sqlite3_errcode</a></li>
8274 <li><a href='#sqlite3_errcode'>sqlite3_errmsg</a></li>
8275 <li><a href='#sqlite3_errcode'>sqlite3_errmsg16</a></li>
8276 <li><a href='#sqlite3_errcode'>sqlite3_error_offset</a></li>
8277 <li><a href='#sqlite3_errcode'>sqlite3_errstr</a></li>
8278 <li><a href='#sqlite3_exec'>sqlite3_exec</a></li>
8279 <li><a href='#sqlite3_errcode'>sqlite3_extended_errcode</a></li>
8280 <li><a href='#sqlite3_extended_result_codes'>sqlite3_extended_result_codes</a></li>
8281 <li><a href='#sqlite3_file_control'>sqlite3_file_control</a></li>
8282 <li><a href='#sqlite3_free_table'>sqlite3_free_table</a></li>
8283 <li><a href='#sqlite3_get_autocommit'>sqlite3_get_autocommit</a></li>
8284 <li><a href='#sqlite3_get_clientdata'>sqlite3_get_clientdata</a></li>
8285 <li><a href='#sqlite3_free_table'>sqlite3_get_table</a></li>
8286 <li><a href='#sqlite3_interrupt'>sqlite3_interrupt</a></li>
8287 <li><a href='#sqlite3_interrupt'>sqlite3_is_interrupted</a></li>
8288 <li><a href='#sqlite3_last_insert_rowid'>sqlite3_last_insert_rowid</a></li>
8289 <li><a href='#sqlite3_limit'>sqlite3_limit</a></li>
8290 <li><a href='#sqlite3_load_extension'>sqlite3_load_extension</a></li>
8291 <li><a href='#sqlite3_next_stmt'>sqlite3_next_stmt</a></li>
8292 <li><a href='#sqlite3_overload_function'>sqlite3_overload_function</a></li>
8293 <li><a href='#sqlite3_prepare'>sqlite3_prepare</a></li>
8294 <li><a href='#sqlite3_prepare'>sqlite3_prepare16</a></li>
8295 <li><a href='#sqlite3_prepare'>sqlite3_prepare16_v2</a></li>
8296 <li><a href='#sqlite3_prepare'>sqlite3_prepare16_v3</a></li>
8297 <li><a href='#sqlite3_prepare'>sqlite3_prepare_v2</a></li>
8298 <li><a href='#sqlite3_prepare'>sqlite3_prepare_v3</a></li>
8299 <li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_blobwrite</a></li>
8300 <li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_count</a></li>
8301 <li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_depth</a></li>
8302 <li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_hook</a></li>
8303 <li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_new</a></li>
8304 <li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_old</a></li>
8305 <li><a href='#sqlite3_progress_handler'>sqlite3_progress_handler</a></li>
8306 <li><a href='#sqlite3_commit_hook'>sqlite3_rollback_hook</a></li>
8307 <li><a href='#sqlite3_set_authorizer'>sqlite3_set_authorizer</a></li>
8308 <li><a href='#sqlite3_get_clientdata'>sqlite3_set_clientdata</a></li>
8309 <li><a href='#sqlite3_set_errmsg'>sqlite3_set_errmsg</a></li>
8310 <li><a href='#sqlite3_set_last_insert_rowid'>sqlite3_set_last_insert_rowid</a></li>
8311 <li><a href='#sqlite3_setlk_timeout'>sqlite3_setlk_timeout</a></li>
8312 <li><a href='#sqlite3_system_errno'>sqlite3_system_errno</a></li>
8313 <li><a href='#sqlite3_table_column_metadata'>sqlite3_table_column_metadata</a></li>
8314 <li><a href='#sqlite3_total_changes'>sqlite3_total_changes</a></li>
8315 <li><a href='#sqlite3_total_changes'>sqlite3_total_changes64</a></li>
8316 <li><a href='#sqlite3_trace_v2'>sqlite3_trace_v2</a></li>
8317 <li><a href='#sqlite3_txn_state'>sqlite3_txn_state</a></li>
8318 <li><a href='#sqlite3_unlock_notify'>sqlite3_unlock_notify</a></li>
8319 <li><a href='#sqlite3_update_hook'>sqlite3_update_hook</a></li>
8320 <li><a href='#sqlite3_wal_autocheckpoint'>sqlite3_wal_autocheckpoint</a></li>
8321 <li><a href='#sqlite3_wal_checkpoint'>sqlite3_wal_checkpoint</a></li>
8322 <li><a href='#sqlite3_wal_checkpoint_v2'>sqlite3_wal_checkpoint_v2</a></li>
8323 <li><a href='#sqlite3_wal_hook'>sqlite3_wal_hook</a></li>
8324 </ul>
8325 </div>
8326 </p>
8327 <hr><a name="sqlite3_str"></a>
8328 <h2>Dynamic String Object</h2>
8329 </div>
8330 <blockquote><pre>
8331 typedef struct sqlite3_str sqlite3_str;
8332 </pre></blockquote>
8333 <p>
8334 An instance of the sqlite3_str object contains a dynamically-sized
8335 string under construction.</p>
8336
8337 <p>The lifecycle of an sqlite3_str object is as follows:
8338 <ol>
8339 <li> The sqlite3_str object is created using <a href="#sqlite3_str_new">sqlite3_str_new()</a>.
8340 <li> Text is appended to the sqlite3_str object using various
8341 methods, such as <a href="#sqlite3_str_append">sqlite3_str_appendf()</a>.
8342 <li> The sqlite3_str object is destroyed and the string it created
8343 is returned using the <a href="#sqlite3_str_finish">sqlite3_str_finish()</a> interface.
8344 </ol>
8345 </p><p>1 Constructor using this object: <a href="#sqlite3_str_new">sqlite3_str_new()</a></p>
8346 <p>2 Destructors using this object:
8347 <a href="#sqlite3_str_finish">sqlite3_str_finish()</a>,
8348 <a href="#sqlite3_str_finish">sqlite3_str_free()</a></p>
8349 <p>10 Methods using this object:
8350 <div class='columns' style='columns: 17em auto;'>
8351 <ul style='padding-top:0;'>
8352 <li><a href='#sqlite3_str_append'>sqlite3_str_append</a></li>
8353 <li><a href='#sqlite3_str_append'>sqlite3_str_appendall</a></li>
8354 <li><a href='#sqlite3_str_append'>sqlite3_str_appendchar</a></li>
8355 <li><a href='#sqlite3_str_append'>sqlite3_str_appendf</a></li>
8356 <li><a href='#sqlite3_str_errcode'>sqlite3_str_errcode</a></li>
8357 <li><a href='#sqlite3_str_errcode'>sqlite3_str_length</a></li>
8358 <li><a href='#sqlite3_str_append'>sqlite3_str_reset</a></li>
8359 <li><a href='#sqlite3_str_append'>sqlite3_str_truncate</a></li>
8360 <li><a href='#sqlite3_str_errcode'>sqlite3_str_value</a></li>
8361 <li><a href='#sqlite3_str_append'>sqlite3_str_vappendf</a></li>
8362 </ul>
8363 </div>
8364 </p>
8365 <hr><a name="sqlite3_pcache_methods2"></a>
8366 <h2>Application Defined Page Cache.</h2>
8367 </div>
8368 <blockquote><pre>
8369 typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2;
8370 struct sqlite3_pcache_methods2 {
8371 int iVersion;
8372 void *pArg;
8373 int (*xInit)(void*);
8374 void (*xShutdown)(void*);
8375 sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable);
8376 void (*xCachesize)(sqlite3_pcache*, int nCachesize);
8377 int (*xPagecount)(sqlite3_pcache*);
8378 sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
8379 void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard);
8380 void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*,
8381 unsigned oldKey, unsigned newKey);
8382 void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
8383 void (*xDestroy)(sqlite3_pcache*);
8384 void (*xShrink)(sqlite3_pcache*);
8385 };
8386 </pre></blockquote>
8387 <p>
8388 The <a href="#sqlite3_config">sqlite3_config</a>(<a href="#sqliteconfigpcache2">SQLITE_CONFIG_PCACHE2</a>, ...) interface can
8389 register an alternative page cache implementation by passing in an
8390 instance of the sqlite3_pcache_methods2 structure.
8391 In many applications, most of the heap memory allocated by
8392 SQLite is used for the page cache.
8393 By implementing a
8394 custom page cache using this API, an application can better control
8395 the amount of memory consumed by SQLite, the way in which
8396 that memory is allocated and released, and the policies used to
8397 determine exactly which parts of a database file are cached and for
8398 how long.</p>
8399
8400 <p>The alternative page cache mechanism is an
8401 extreme measure that is only needed by the most demanding applications.
8402 The built-in page cache is recommended for most uses.</p>
8403
8404 <p>The contents of the sqlite3_pcache_methods2 structure are copied to an
8405 internal buffer by SQLite within the call to <a href="#sqlite3_config">sqlite3_config</a>. Hence
8406 the application may discard the parameter after the call to
8407 <a href="#sqlite3_config">sqlite3_config()</a> returns.</p>
8408
8409 <p><a name="thexinitpagecachemethod"></a>
8410
8411 The xInit() method is called once for each effective
8412 call to <a href="#sqlite3_initialize">sqlite3_initialize()</a>
8413 (usually only once during the lifetime of the process). The xInit()
8414 method is passed a copy of the sqlite3_pcache_methods2.pArg value.
8415 The intent of the xInit() method is to set up global data structures
8416 required by the custom page cache implementation.
8417 If the xInit() method is NULL, then the
8418 built-in default page cache is used instead of the application defined
8419 page cache.</p>
8420
8421 <p><a name="thexshutdownpagecachemethod"></a>
8422
8423 The xShutdown() method is called by <a href="#sqlite3_initialize">sqlite3_shutdown()</a>.
8424 It can be used to clean up
8425 any outstanding resources before process shutdown, if required.
8426 The xShutdown() method may be NULL.</p>
8427
8428 <p>SQLite automatically serializes calls to the xInit method,
8429 so the xInit method need not be threadsafe. The
8430 xShutdown method is only called from <a href="#sqlite3_initialize">sqlite3_shutdown()</a> so it does
8431 not need to be threadsafe either. All other methods must be threadsafe
8432 in multithreaded applications.</p>
8433
8434 <p>SQLite will never invoke xInit() more than once without an intervening
8435 call to xShutdown().</p>
8436
8437 <p><a name="thexcreatepagecachemethods"></a>
8438
8439 SQLite invokes the xCreate() method to construct a new cache instance.
8440 SQLite will typically create one cache instance for each open database file,
8441 though this is not guaranteed. The
8442 first parameter, szPage, is the size in bytes of the pages that must
8443 be allocated by the cache. szPage will always be a power of two. The
8444 second parameter szExtra is a number of bytes of extra storage
8445 associated with each page cache entry. The szExtra parameter will be
8446 a number less than 250. SQLite will use the
8447 extra szExtra bytes on each page to store metadata about the underlying
8448 database page on disk. The value passed into szExtra depends
8449 on the SQLite version, the target platform, and how SQLite was compiled.
8450 The third argument to xCreate(), bPurgeable, is true if the cache being
8451 created will be used to cache database pages of a file stored on disk, or
8452 false if it is used for an in-memory database. The cache implementation
8453 does not have to do anything special based upon the value of bPurgeable;
8454 it is purely advisory. On a cache where bPurgeable is false, SQLite will
8455 never invoke xUnpin() except to deliberately delete a page.
8456 In other words, calls to xUnpin() on a cache with bPurgeable set to
8457 false will always have the "discard" flag set to true.
8458 Hence, a cache created with bPurgeable set to false will
8459 never contain any unpinned pages.</p>
8460
8461 <p><a name="thexcachesizepagecachemethod"></a>
8462
8463 The xCachesize() method may be called at any time by SQLite to set the
8464 suggested maximum cache-size (number of pages stored) for the cache
8465 instance passed as the first argument. This is the value configured using
8466 the SQLite "<a href="pragma.html#pragma_cache_size">PRAGMA cache_size</a>" command. As with the bPurgeable
8467 parameter, the implementation is not required to do anything with this
8468 value; it is advisory only.</p>
8469
8470 <p><a name="thexpagecountpagecachemethods"></a>
8471
8472 The xPagecount() method must return the number of pages currently
8473 stored in the cache, both pinned and unpinned.</p>
8474
8475 <p><a name="thexfetchpagecachemethods"></a>
8476
8477 The xFetch() method locates a page in the cache and returns a pointer to
8478 an sqlite3_pcache_page object associated with that page, or a NULL pointer.
8479 The pBuf element of the returned sqlite3_pcache_page object will be a
8480 pointer to a buffer of szPage bytes used to store the content of a
8481 single database page. The pExtra element of sqlite3_pcache_page will be
8482 a pointer to the szExtra bytes of extra storage that SQLite has requested
8483 for each entry in the page cache.</p>
8484
8485 <p>The page to be fetched is determined by the key. The minimum key value
8486 is 1. After it has been retrieved using xFetch, the page is considered
8487 to be "pinned".</p>
8488
8489 <p>If the requested page is already in the page cache, then the page cache
8490 implementation must return a pointer to the page buffer with its content
8491 intact. If the requested page is not already in the cache, then the
8492 cache implementation should use the value of the createFlag
8493 parameter to help it determine what action to take:</p>
8494
8495 <p><table border=1 width=85% align=center>
8496 <tr><th> createFlag <th> Behavior when page is not already in cache
8497 <tr><td> 0 <td> Do not allocate a new page. Return NULL.
8498 <tr><td> 1 <td> Allocate a new page if it is easy and convenient to do so.
8499 Otherwise return NULL.
8500 <tr><td> 2 <td> Make every effort to allocate a new page. Only return
8501 NULL if allocating a new page is effectively impossible.
8502 </table></p>
8503
8504 <p>SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite
8505 will only use a createFlag of 2 after a prior call with a createFlag of 1
8506 failed. In between the xFetch() calls, SQLite may
8507 attempt to unpin one or more cache pages by spilling the content of
8508 pinned pages to disk and synching the operating system disk cache.</p>
8509
8510 <p><a name="thexunpinpagecachemethod"></a>
8511
8512 xUnpin() is called by SQLite with a pointer to a currently pinned page
8513 as its second argument. If the third parameter, discard, is non-zero,
8514 then the page must be evicted from the cache.
8515 If the discard parameter is
8516 zero, then the page may be discarded or retained at the discretion of the
8517 page cache implementation. The page cache implementation
8518 may choose to evict unpinned pages at any time.</p>
8519
8520 <p>The cache must not perform any reference counting. A single
8521 call to xUnpin() unpins the page regardless of the number of prior calls
8522 to xFetch().</p>
8523
8524 <p><a name="thexrekeypagecachemethods"></a>
8525
8526 The xRekey() method is used to change the key value associated with the
8527 page passed as the second argument. If the cache
8528 previously contains an entry associated with newKey, it must be
8529 discarded. Any prior cache entry associated with newKey is guaranteed not
8530 to be pinned.</p>
8531
8532 <p>When SQLite calls the xTruncate() method, the cache must discard all
8533 existing cache entries with page numbers (keys) greater than or equal
8534 to the value of the iLimit parameter passed to xTruncate(). If any
8535 of these pages are pinned, they become implicitly unpinned, meaning that
8536 they can be safely discarded.</p>
8537
8538 <p><a name="thexdestroypagecachemethod"></a>
8539
8540 The xDestroy() method is used to delete a cache allocated by xCreate().
8541 All resources associated with the specified cache should be freed. After
8542 calling the xDestroy() method, SQLite considers the <a href="#sqlite3_pcache">sqlite3_pcache*</a>
8543 handle invalid, and will not use it with any other sqlite3_pcache_methods2
8544 functions.</p>
8545
8546 <p><a name="thexshrinkpagecachemethod"></a>
8547
8548 SQLite invokes the xShrink() method when it wants the page cache to
8549 free up as much of heap memory as possible. The page cache implementation
8550 is not obligated to free any memory, but well-behaved implementations should
8551 do their best.
8552 </p><hr><a name="sqlite3_stmt"></a>
8553 <h2>Prepared Statement Object</h2>
8554 </div>
8555 <blockquote><pre>
8556 typedef struct sqlite3_stmt sqlite3_stmt;
8557 </pre></blockquote>
8558 <p>
8559 An instance of this object represents a single SQL statement that
8560 has been compiled into binary form and is ready to be evaluated.</p>
8561
8562 <p>Think of each SQL statement as a separate computer program. The
8563 original SQL text is source code. A prepared statement object
8564 is the compiled object code. All SQL must be converted into a
8565 prepared statement before it can be run.</p>
8566
8567 <p>The life-cycle of a prepared statement object usually goes like this:</p>
8568
8569 <p><ol>
8570 <li> Create the prepared statement object using <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>.
8571 <li> Bind values to <a href="lang_expr.html#varparam">parameters</a> using the sqlite3_bind_*()
8572 interfaces.
8573 <li> Run the SQL by calling <a href="#sqlite3_step">sqlite3_step()</a> one or more times.
8574 <li> Reset the prepared statement using <a href="#sqlite3_reset">sqlite3_reset()</a> then go back
8575 to step 2. Do this zero or more times.
8576 <li> Destroy the object using <a href="#sqlite3_finalize">sqlite3_finalize()</a>.
8577 </ol>
8578 </p><p>6 Constructors using this object:
8579 <div class='columns' style='columns: 17em auto;'>
8580 <ul style='padding-top:0;'>
8581 <li><a href='#sqlite3_prepare'>sqlite3_prepare</a></li>
8582 <li><a href='#sqlite3_prepare'>sqlite3_prepare16</a></li>
8583 <li><a href='#sqlite3_prepare'>sqlite3_prepare16_v2</a></li>
8584 <li><a href='#sqlite3_prepare'>sqlite3_prepare16_v3</a></li>
8585 <li><a href='#sqlite3_prepare'>sqlite3_prepare_v2</a></li>
8586 <li><a href='#sqlite3_prepare'>sqlite3_prepare_v3</a></li>
8587 </ul>
8588 </div>
8589 </p>
8590 <p>1 Destructor using this object: <a href="#sqlite3_finalize">sqlite3_finalize()</a></p>
8591 <p>53 Methods using this object:
8592 <div class='columns' style='columns: 17em auto;'>
8593 <ul style='padding-top:0;'>
8594 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_blob</a></li>
8595 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_blob64</a></li>
8596 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_double</a></li>
8597 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_int</a></li>
8598 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_int64</a></li>
8599 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_null</a></li>
8600 <li><a href='#sqlite3_bind_parameter_count'>sqlite3_bind_parameter_count</a></li>
8601 <li><a href='#sqlite3_bind_parameter_index'>sqlite3_bind_parameter_index</a></li>
8602 <li><a href='#sqlite3_bind_parameter_name'>sqlite3_bind_parameter_name</a></li>
8603 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_pointer</a></li>
8604 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_text</a></li>
8605 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_text16</a></li>
8606 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_text64</a></li>
8607 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_value</a></li>
8608 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_zeroblob</a></li>
8609 <li><a href='#sqlite3_bind_blob'>sqlite3_bind_zeroblob64</a></li>
8610 <li><a href='#sqlite3_clear_bindings'>sqlite3_clear_bindings</a></li>
8611 <li><a href='#sqlite3_column_blob'>sqlite3_column_blob</a></li>
8612 <li><a href='#sqlite3_column_blob'>sqlite3_column_bytes</a></li>
8613 <li><a href='#sqlite3_column_blob'>sqlite3_column_bytes16</a></li>
8614 <li><a href='#sqlite3_column_count'>sqlite3_column_count</a></li>
8615 <li><a href='#sqlite3_column_database_name'>sqlite3_column_database_name</a></li>
8616 <li><a href='#sqlite3_column_database_name'>sqlite3_column_database_name16</a></li>
8617 <li><a href='#sqlite3_column_decltype'>sqlite3_column_decltype</a></li>
8618 <li><a href='#sqlite3_column_decltype'>sqlite3_column_decltype16</a></li>
8619 <li><a href='#sqlite3_column_blob'>sqlite3_column_double</a></li>
8620 <li><a href='#sqlite3_column_blob'>sqlite3_column_int</a></li>
8621 <li><a href='#sqlite3_column_blob'>sqlite3_column_int64</a></li>
8622 <li><a href='#sqlite3_column_name'>sqlite3_column_name</a></li>
8623 <li><a href='#sqlite3_column_name'>sqlite3_column_name16</a></li>
8624 <li><a href='#sqlite3_column_database_name'>sqlite3_column_origin_name</a></li>
8625 <li><a href='#sqlite3_column_database_name'>sqlite3_column_origin_name16</a></li>
8626 <li><a href='#sqlite3_column_database_name'>sqlite3_column_table_name</a></li>
8627 <li><a href='#sqlite3_column_database_name'>sqlite3_column_table_name16</a></li>
8628 <li><a href='#sqlite3_column_blob'>sqlite3_column_text</a></li>
8629 <li><a href='#sqlite3_column_blob'>sqlite3_column_text16</a></li>
8630 <li><a href='#sqlite3_column_blob'>sqlite3_column_type</a></li>
8631 <li><a href='#sqlite3_column_blob'>sqlite3_column_value</a></li>
8632 <li><a href='#sqlite3_data_count'>sqlite3_data_count</a></li>
8633 <li><a href='#sqlite3_db_handle'>sqlite3_db_handle</a></li>
8634 <li><a href='#sqlite3_expanded_sql'>sqlite3_expanded_sql</a></li>
8635 <li><a href='#sqlite3_expanded_sql'>sqlite3_normalized_sql</a></li>
8636 <li><a href='#sqlite3_reset'>sqlite3_reset</a></li>
8637 <li><a href='#sqlite3_expanded_sql'>sqlite3_sql</a></li>
8638 <li><a href='#sqlite3_step'>sqlite3_step</a></li>
8639 <li><a href='#sqlite3_stmt_busy'>sqlite3_stmt_busy</a></li>
8640 <li><a href='#sqlite3_stmt_explain'>sqlite3_stmt_explain</a></li>
8641 <li><a href='#sqlite3_stmt_isexplain'>sqlite3_stmt_isexplain</a></li>
8642 <li><a href='#sqlite3_stmt_readonly'>sqlite3_stmt_readonly</a></li>
8643 <li><a href='#sqlite3_stmt_scanstatus'>sqlite3_stmt_scanstatus</a></li>
8644 <li><a href='#sqlite3_stmt_scanstatus_reset'>sqlite3_stmt_scanstatus_reset</a></li>
8645 <li><a href='#sqlite3_stmt_scanstatus'>sqlite3_stmt_scanstatus_v2</a></li>
8646 <li><a href='#sqlite3_stmt_status'>sqlite3_stmt_status</a></li>
8647 </ul>
8648 </div>
8649 </p>
8650 <hr><a name="sqlite3_value"></a>
8651 <h2>Dynamically Typed Value Object</h2>
8652 </div>
8653 <blockquote><pre>
8654 typedef struct sqlite3_value sqlite3_value;
8655 </pre></blockquote>
8656 <p>
8657 SQLite uses the sqlite3_value object to represent all values
8658 that can be stored in a database table. SQLite uses dynamic typing
8659 for the values it stores. Values stored in sqlite3_value objects
8660 can be integers, floating point values, strings, BLOBs, or NULL.</p>
8661
8662 <p>An sqlite3_value object may be either "protected" or "unprotected".
8663 Some interfaces require a protected sqlite3_value. Other interfaces
8664 will accept either a protected or an unprotected sqlite3_value.
8665 Every interface that accepts sqlite3_value arguments specifies
8666 whether or not it requires a protected sqlite3_value. The
8667 <a href="#sqlite3_value_dup">sqlite3_value_dup()</a> interface can be used to construct a new
8668 protected sqlite3_value from an unprotected sqlite3_value.</p>
8669
8670 <p>The terms "protected" and "unprotected" refer to whether or not
8671 a mutex is held. An internal mutex is held for a protected
8672 sqlite3_value object but no mutex is held for an unprotected
8673 sqlite3_value object. If SQLite is compiled to be single-threaded
8674 (with <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> and with <a href="#sqlite3_threadsafe">sqlite3_threadsafe()</a> returning 0)
8675 or if SQLite is run in one of reduced mutex modes
8676 <a href="#sqliteconfigsinglethread">SQLITE_CONFIG_SINGLETHREAD</a> or <a href="#sqliteconfigmultithread">SQLITE_CONFIG_MULTITHREAD</a>
8677 then there is no distinction between protected and unprotected
8678 sqlite3_value objects and they can be used interchangeably. However,
8679 for maximum code portability it is recommended that applications
8680 still make the distinction between protected and unprotected
8681 sqlite3_value objects even when not strictly required.</p>
8682
8683 <p>The sqlite3_value objects that are passed as parameters into the
8684 implementation of <a href="appfunc.html">application-defined SQL functions</a> are protected.
8685 The sqlite3_value objects returned by <a href="#sqlite3_vtab_rhs_value">sqlite3_vtab_rhs_value()</a>
8686 are protected.
8687 The sqlite3_value object returned by
8688 <a href="#sqlite3_column_blob">sqlite3_column_value()</a> is unprotected.
8689 Unprotected sqlite3_value objects may only be used as arguments
8690 to <a href="#sqlite3_result_blob">sqlite3_result_value()</a>, <a href="#sqlite3_bind_blob">sqlite3_bind_value()</a>, and
8691 <a href="#sqlite3_value_dup">sqlite3_value_dup()</a>.
8692 The <a href="#sqlite3_value_blob">sqlite3_value_type()</a> family of
8693 interfaces require protected sqlite3_value objects.
8694 </p><p>19 Methods using this object:
8695 <div class='columns' style='columns: 17em auto;'>
8696 <ul style='padding-top:0;'>
8697 <li><a href='#sqlite3_value_blob'>sqlite3_value_blob</a></li>
8698 <li><a href='#sqlite3_value_blob'>sqlite3_value_bytes</a></li>
8699 <li><a href='#sqlite3_value_blob'>sqlite3_value_bytes16</a></li>
8700 <li><a href='#sqlite3_value_blob'>sqlite3_value_double</a></li>
8701 <li><a href='#sqlite3_value_dup'>sqlite3_value_dup</a></li>
8702 <li><a href='#sqlite3_value_encoding'>sqlite3_value_encoding</a></li>
8703 <li><a href='#sqlite3_value_dup'>sqlite3_value_free</a></li>
8704 <li><a href='#sqlite3_value_blob'>sqlite3_value_frombind</a></li>
8705 <li><a href='#sqlite3_value_blob'>sqlite3_value_int</a></li>
8706 <li><a href='#sqlite3_value_blob'>sqlite3_value_int64</a></li>
8707 <li><a href='#sqlite3_value_blob'>sqlite3_value_nochange</a></li>
8708 <li><a href='#sqlite3_value_blob'>sqlite3_value_numeric_type</a></li>
8709 <li><a href='#sqlite3_value_blob'>sqlite3_value_pointer</a></li>
8710 <li><a href='#sqlite3_value_subtype'>sqlite3_value_subtype</a></li>
8711 <li><a href='#sqlite3_value_blob'>sqlite3_value_text</a></li>
8712 <li><a href='#sqlite3_value_blob'>sqlite3_value_text16</a></li>
8713 <li><a href='#sqlite3_value_blob'>sqlite3_value_text16be</a></li>
8714 <li><a href='#sqlite3_value_blob'>sqlite3_value_text16le</a></li>
8715 <li><a href='#sqlite3_value_blob'>sqlite3_value_type</a></li>
8716 </ul>
8717 </div>
8718 </p>
8719 <hr><a name="sqlite3_aggregate_count"></a>
8720 <h2>Deprecated Functions</h2>
8721 </div>
8722 <blockquote><pre>
8723 #ifndef SQLITE_OMIT_DEPRECATED
8724 int sqlite3_aggregate_count(sqlite3_context*);
8725 int sqlite3_expired(sqlite3_stmt*);
8726 int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
8727 int sqlite3_global_recover(void);
8728 void sqlite3_thread_cleanup(void);
8729 int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),
8730 void*,sqlite3_int64);
8731 #endif
8732 </pre></blockquote>
8733 <p>
8734 These functions are <a href="capi3ref.html">deprecated</a>. In order to maintain
8735 backwards compatibility with older code, these functions continue
8736 to be supported. However, new applications should avoid
8737 the use of these functions. To encourage programmers to avoid
8738 these functions, we will not explain what they do.
8739 </p><hr><a name="sqlite3_backup_finish"></a>
8740 <h2>Online Backup API.</h2>
8741 </div>
8742 <blockquote><pre>
8743 sqlite3_backup *sqlite3_backup_init(
8744 sqlite3 *pDest, /* Destination database handle */
8745 const char *zDestName, /* Destination database name */
8746 sqlite3 *pSource, /* Source database handle */
8747 const char *zSourceName /* Source database name */
8748 );
8749 int sqlite3_backup_step(sqlite3_backup *p, int nPage);
8750 int sqlite3_backup_finish(sqlite3_backup *p);
8751 int sqlite3_backup_remaining(sqlite3_backup *p);
8752 int sqlite3_backup_pagecount(sqlite3_backup *p);
8753 </pre></blockquote>
8754 <p>
8755 The backup API copies the content of one database into another.
8756 It is useful either for creating backups of databases or
8757 for copying in-memory databases to or from persistent files.</p>
8758
8759 <p>See Also: <a href="backup.html">Using the SQLite Online Backup API</a></p>
8760
8761 <p>SQLite holds a write transaction open on the destination database file
8762 for the duration of the backup operation.
8763 The source database is read-locked only while it is being read;
8764 it is not locked continuously for the entire backup operation.
8765 Thus, the backup may be performed on a live source database without
8766 preventing other database connections from
8767 reading or writing to the source database while the backup is underway.</p>
8768
8769 <p>To perform a backup operation:
8770 <ol>
8771 <li><b>sqlite3_backup_init()</b> is called once to initialize the
8772 backup,
8773 <li><b>sqlite3_backup_step()</b> is called one or more times to transfer
8774 the data between the two databases, and finally
8775 <li><b>sqlite3_backup_finish()</b> is called to release all resources
8776 associated with the backup operation.
8777 </ol>
8778 There should be exactly one call to sqlite3_backup_finish() for each
8779 successful call to sqlite3_backup_init().</p>
8780
8781 <p><a name="sqlite3backupinit"></a>
8782 <b>sqlite3_backup_init()</b></p>
8783
8784 <p>The D and N arguments to sqlite3_backup_init(D,N,S,M) are the
8785 <a href="#sqlite3">database connection</a> associated with the destination database
8786 and the database name, respectively.
8787 The database name is "main" for the main database, "temp" for the
8788 temporary database, or the name specified after the AS keyword in
8789 an <a href="lang_attach.html">ATTACH</a> statement for an attached database.
8790 The S and M arguments passed to
8791 sqlite3_backup_init(D,N,S,M) identify the <a href="#sqlite3">database connection</a>
8792 and database name of the source database, respectively.
8793 The source and destination <a href="#sqlite3">database connections</a> (parameters S and D)
8794 must be different or else sqlite3_backup_init(D,N,S,M) will fail with
8795 an error.</p>
8796
8797 <p>A call to sqlite3_backup_init() will fail, returning NULL, if
8798 there is already a read or read-write transaction open on the
8799 destination database.</p>
8800
8801 <p>If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
8802 returned and an error code and error message are stored in the
8803 destination <a href="#sqlite3">database connection</a> D.
8804 The error code and message for the failed call to sqlite3_backup_init()
8805 can be retrieved using the <a href="#sqlite3_errcode">sqlite3_errcode()</a>, <a href="#sqlite3_errcode">sqlite3_errmsg()</a>, and/or
8806 <a href="#sqlite3_errcode">sqlite3_errmsg16()</a> functions.
8807 A successful call to sqlite3_backup_init() returns a pointer to an
8808 <a href="#sqlite3_backup">sqlite3_backup</a> object.
8809 The <a href="#sqlite3_backup">sqlite3_backup</a> object may be used with the sqlite3_backup_step() and
8810 sqlite3_backup_finish() functions to perform the specified backup
8811 operation.</p>
8812
8813 <p><a name="sqlite3backupstep"></a>
8814 <b>sqlite3_backup_step()</b></p>
8815
8816 <p>Function sqlite3_backup_step(B,N) will copy up to N pages between
8817 the source and destination databases specified by <a href="#sqlite3_backup">sqlite3_backup</a> object B.
8818 If N is negative, all remaining source pages are copied.
8819 If sqlite3_backup_step(B,N) successfully copies N pages and there
8820 are still more pages to be copied, then the function returns <a href="#SQLITE_ABORT">SQLITE_OK</a>.
8821 If sqlite3_backup_step(B,N) successfully finishes copying all pages
8822 from source to destination, then it returns <a href="#SQLITE_ABORT">SQLITE_DONE</a>.
8823 If an error occurs while running sqlite3_backup_step(B,N),
8824 then an <a href="rescode.html">error code</a> is returned. As well as <a href="#SQLITE_ABORT">SQLITE_OK</a> and
8825 <a href="#SQLITE_ABORT">SQLITE_DONE</a>, a call to sqlite3_backup_step() may return <a href="#SQLITE_ABORT">SQLITE_READONLY</a>,
8826 <a href="#SQLITE_ABORT">SQLITE_NOMEM</a>, <a href="#SQLITE_ABORT">SQLITE_BUSY</a>, <a href="#SQLITE_ABORT">SQLITE_LOCKED</a>, or an
8827 <a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_XXX</a> extended error code.</p>
8828
8829 <p>The sqlite3_backup_step() might return <a href="#SQLITE_ABORT">SQLITE_READONLY</a> if
8830 <ol>
8831 <li> the destination database was opened read-only, or
8832 <li> the destination database is using write-ahead-log journaling
8833 and the destination and source page sizes differ, or
8834 <li> the destination database is an in-memory database and the
8835 destination and source page sizes differ.
8836 </ol></p>
8837
8838 <p>If sqlite3_backup_step() cannot obtain a required file-system lock, then
8839 the <a href="#sqlite3_busy_handler">busy-handler function</a>
8840 is invoked (if one is specified). If the
8841 busy-handler returns non-zero before the lock is available, then
8842 <a href="#SQLITE_ABORT">SQLITE_BUSY</a> is returned to the caller. In this case the call to
8843 sqlite3_backup_step() can be retried later. If the source
8844 <a href="#sqlite3">database connection</a>
8845 is being used to write to the source database when sqlite3_backup_step()
8846 is called, then <a href="#SQLITE_ABORT">SQLITE_LOCKED</a> is returned immediately. Again, in this
8847 case the call to sqlite3_backup_step() can be retried later on. If
8848 <a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_XXX</a>, <a href="#SQLITE_ABORT">SQLITE_NOMEM</a>, or
8849 <a href="#SQLITE_ABORT">SQLITE_READONLY</a> is returned, then
8850 there is no point in retrying the call to sqlite3_backup_step(). These
8851 errors are considered fatal. The application must accept
8852 that the backup operation has failed and pass the backup operation handle
8853 to the sqlite3_backup_finish() to release associated resources.</p>
8854
8855 <p>The first call to sqlite3_backup_step() obtains an exclusive lock
8856 on the destination file. The exclusive lock is not released until either
8857 sqlite3_backup_finish() is called or the backup operation is complete
8858 and sqlite3_backup_step() returns <a href="#SQLITE_ABORT">SQLITE_DONE</a>. Every call to
8859 sqlite3_backup_step() obtains a <a href="lockingv3.html#shared_lock">shared lock</a> on the source database that
8860 lasts for the duration of the sqlite3_backup_step() call.
8861 Because the source database is not locked between calls to
8862 sqlite3_backup_step(), the source database may be modified mid-way
8863 through the backup process. If the source database is modified by an
8864 external process or via a database connection other than the one being
8865 used by the backup operation, then the backup will be automatically
8866 restarted by the next call to sqlite3_backup_step(). If the source
8867 database is modified by using the same database connection as is used
8868 by the backup operation, then the backup database is automatically
8869 updated at the same time.</p>
8870
8871 <p><a name="sqlite3backupfinish"></a>
8872 <b>sqlite3_backup_finish()</b></p>
8873
8874 <p>When sqlite3_backup_step() has returned <a href="#SQLITE_ABORT">SQLITE_DONE</a>, or when the
8875 application wishes to abandon the backup operation, the application
8876 should destroy the <a href="#sqlite3_backup">sqlite3_backup</a> by passing it to sqlite3_backup_finish().
8877 The sqlite3_backup_finish() interfaces releases all
8878 resources associated with the <a href="#sqlite3_backup">sqlite3_backup</a> object.
8879 If sqlite3_backup_step() has not yet returned <a href="#SQLITE_ABORT">SQLITE_DONE</a>, then any
8880 active write-transaction on the destination database is rolled back.
8881 The <a href="#sqlite3_backup">sqlite3_backup</a> object is invalid
8882 and may not be used following a call to sqlite3_backup_finish().</p>
8883
8884 <p>The value returned by sqlite3_backup_finish is <a href="#SQLITE_ABORT">SQLITE_OK</a> if no
8885 sqlite3_backup_step() errors occurred, regardless of whether or not
8886 sqlite3_backup_step() completed.
8887 If an out-of-memory condition or IO error occurred during any prior
8888 sqlite3_backup_step() call on the same <a href="#sqlite3_backup">sqlite3_backup</a> object, then
8889 sqlite3_backup_finish() returns the corresponding <a href="rescode.html">error code</a>.</p>
8890
8891 <p>A return of <a href="#SQLITE_ABORT">SQLITE_BUSY</a> or <a href="#SQLITE_ABORT">SQLITE_LOCKED</a> from sqlite3_backup_step()
8892 is not a permanent error and does not affect the return value of
8893 sqlite3_backup_finish().</p>
8894
8895 <p><a name="sqlite3backupremaining"></a>
8896 <a name="sqlite3backuppagecount"></a>
8897
8898 <b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b></p>
8899
8900 <p>The sqlite3_backup_remaining() routine returns the number of pages still
8901 to be backed up at the conclusion of the most recent sqlite3_backup_step().
8902 The sqlite3_backup_pagecount() routine returns the total number of pages
8903 in the source database at the conclusion of the most recent
8904 sqlite3_backup_step().
8905 The values returned by these functions are only updated by
8906 sqlite3_backup_step(). If the source database is modified in a way that
8907 changes the size of the source database or the number of pages remaining,
8908 those changes are not reflected in the output of sqlite3_backup_pagecount()
8909 and sqlite3_backup_remaining() until after the next
8910 sqlite3_backup_step().</p>
8911
8912 <p><b>Concurrent Usage of Database Handles</b></p>
8913
8914 <p>The source <a href="#sqlite3">database connection</a> may be used by the application for other
8915 purposes while a backup operation is underway or being initialized.
8916 If SQLite is compiled and configured to support threadsafe database
8917 connections, then the source database connection may be used concurrently
8918 from within other threads.</p>
8919
8920 <p>However, the application must guarantee that the destination
8921 <a href="#sqlite3">database connection</a> is not passed to any other API (by any thread) after
8922 sqlite3_backup_init() is called and before the corresponding call to
8923 sqlite3_backup_finish(). SQLite does not currently check to see
8924 if the application incorrectly accesses the destination <a href="#sqlite3">database connection</a>
8925 and so no error code is reported, but the operations may malfunction
8926 nevertheless. Use of the destination database connection while a
8927 backup is in progress might also cause a mutex deadlock.</p>
8928
8929 <p>If running in <a href="sharedcache.html">shared cache mode</a>, the application must
8930 guarantee that the shared cache used by the destination database
8931 is not accessed while the backup is running. In practice this means
8932 that the application must guarantee that the disk file being
8933 backed up to is not accessed by any connection within the process,
8934 not just the specific connection that was passed to sqlite3_backup_init().</p>
8935
8936 <p>The <a href="#sqlite3_backup">sqlite3_backup</a> object itself is partially threadsafe. Multiple
8937 threads may safely make multiple concurrent calls to sqlite3_backup_step().
8938 However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
8939 APIs are not strictly speaking threadsafe. If they are invoked at the
8940 same time as another thread is invoking sqlite3_backup_step() it is
8941 possible that they return invalid values.</p>
8942
8943 <p><b>Alternatives To Using The Backup API</b></p>
8944
8945 <p>Other techniques for safely creating a consistent backup of an SQLite
8946 database include:</p>
8947
8948 <p><ul>
8949 <li> The <a href="lang_vacuum.html#vacuuminto">VACUUM INTO</a> command.
8950 <li> The <a href="rsync.html">sqlite3_rsync</a> utility program.
8951 </ul>
8952 </p><hr><a name="sqlite3_carray_bind"></a>
8953 <h2>Bind array values to the CARRAY table-valued function</h2>
8954 </div>
8955 <blockquote><pre>
8956 int sqlite3_carray_bind_v2(
8957 sqlite3_stmt *pStmt, /* Statement to be bound */
8958 int i, /* Parameter index */
8959 void *aData, /* Pointer to array data */
8960 int nData, /* Number of data elements */
8961 int mFlags, /* CARRAY flags */
8962 void (*xDel)(void*), /* Destructor for aData */
8963 void *pDel /* Optional argument to xDel() */
8964 );
8965 int sqlite3_carray_bind(
8966 sqlite3_stmt *pStmt, /* Statement to be bound */
8967 int i, /* Parameter index */
8968 void *aData, /* Pointer to array data */
8969 int nData, /* Number of data elements */
8970 int mFlags, /* CARRAY flags */
8971 void (*xDel)(void*) /* Destructor for aData */
8972 );
8973 </pre></blockquote>
8974 <p>
8975 The sqlite3_carray_bind_v2(S,I,P,N,F,X,D) interface binds an array value to
8976 parameter that is the first argument of the <a href="carray.html">carray() table-valued function</a>.
8977 The S parameter is a pointer to the <a href="#sqlite3_stmt">prepared statement</a> that uses the
8978 carray() functions. I is the parameter index to be bound. I must be the
8979 index of the parameter that is the first argument to the carray()
8980 table-valued function. P is a pointer to the array to be bound, and N
8981 is the number of elements in the array. The F argument is one of
8982 constants <a href="#SQLITE_CARRAY_BLOB">SQLITE_CARRAY_INT32</a>, <a href="#SQLITE_CARRAY_BLOB">SQLITE_CARRAY_INT64</a>,
8983 <a href="#SQLITE_CARRAY_BLOB">SQLITE_CARRAY_DOUBLE</a>, <a href="#SQLITE_CARRAY_BLOB">SQLITE_CARRAY_TEXT</a>,
8984 or <a href="#SQLITE_CARRAY_BLOB">SQLITE_CARRAY_BLOB</a> to indicate the datatype of the array P.</p>
8985
8986 <p>If the X argument is not a NULL pointer or one of the special
8987 values <a href="#SQLITE_STATIC">SQLITE_STATIC</a> or <a href="#SQLITE_STATIC">SQLITE_TRANSIENT</a>, then SQLite will invoke
8988 the function X with argument D when it is finished using the data in P.
8989 The call to X(D) is a destructor for the array P. The destructor X(D)
8990 is invoked even if the call to sqlite3_carray_bind_v2() fails. If the X
8991 parameter is the special-case value <a href="#SQLITE_STATIC">SQLITE_STATIC</a>, then SQLite assumes
8992 that the data static and the destructor is never invoked. If the X
8993 parameter is the special-case value <a href="#SQLITE_STATIC">SQLITE_TRANSIENT</a>, then
8994 sqlite3_carray_bind_v2() makes its own private copy of the data prior
8995 to returning and never invokes the destructor X.</p>
8996
8997 <p>The sqlite3_carray_bind() function works the same as sqlite3_carray_bind_v2()
8998 with a D parameter set to P. In other words,
8999 sqlite3_carray_bind(S,I,P,N,F,X) is same as
9000 sqlite3_carray_bind_v2(S,I,P,N,F,X,P).
9001 </p><hr><a name="sqlite3_changes"></a>
9002 <h2>Count The Number Of Rows Modified</h2>
9003 </div>
9004 <blockquote><pre>
9005 int sqlite3_changes(sqlite3*);
9006 sqlite3_int64 sqlite3_changes64(sqlite3*);
9007 </pre></blockquote>
9008 <p>
9009 These functions return the number of rows modified, inserted or
9010 deleted by the most recently completed INSERT, UPDATE or DELETE
9011 statement on the database connection specified by the only parameter.
9012 The two functions are identical except for the type of the return value
9013 and that if the number of rows modified by the most recent INSERT, UPDATE,
9014 or DELETE is greater than the maximum value supported by type "int", then
9015 the return value of sqlite3_changes() is undefined. Executing any other
9016 type of SQL statement does not modify the value returned by these functions.
9017 For the purposes of this interface, a CREATE TABLE AS SELECT statement
9018 does not count as an INSERT, UPDATE or DELETE statement and hence the rows
9019 added to the new table by the CREATE TABLE AS SELECT statement are not
9020 counted.</p>
9021
9022 <p>Only changes made directly by the INSERT, UPDATE or DELETE statement are
9023 considered - auxiliary changes caused by <a href="lang_createtrigger.html">triggers</a>,
9024 <a href="foreignkeys.html#fk_actions">foreign key actions</a> or <a href="lang_replace.html">REPLACE</a> constraint resolution are not counted.</p>
9025
9026 <p>Changes to a view that are intercepted by
9027 <a href="lang_createtrigger.html#instead_of_trigger">INSTEAD OF triggers</a> are not counted. The value
9028 returned by sqlite3_changes() immediately after an INSERT, UPDATE or
9029 DELETE statement run on a view is always zero. Only changes made to real
9030 tables are counted.</p>
9031
9032 <p>Things are more complicated if the sqlite3_changes() function is
9033 executed while a trigger program is running. This may happen if the
9034 program uses the <a href="lang_corefunc.html#changes">changes() SQL function</a>, or if some other callback
9035 function invokes sqlite3_changes() directly. Essentially:</p>
9036
9037 <p><ul>
9038 <li> Before entering a trigger program the value returned by
9039 sqlite3_changes() function is saved. After the trigger program
9040 has finished, the original value is restored.</p>
9041
9042 <p><li> Within a trigger program each INSERT, UPDATE and DELETE
9043 statement sets the value returned by sqlite3_changes()
9044 upon completion as normal. Of course, this value will not include
9045 any changes performed by sub-triggers, as the sqlite3_changes()
9046 value will be saved and restored after each sub-trigger has run.
9047 </ul></p>
9048
9049 <p>This means that if the changes() SQL function (or similar) is used
9050 by the first INSERT, UPDATE or DELETE statement within a trigger, it
9051 returns the value as set when the calling statement began executing.
9052 If it is used by the second or subsequent such statement within a trigger
9053 program, the value returned reflects the number of rows modified by the
9054 previous INSERT, UPDATE or DELETE statement within the same trigger.</p>
9055
9056 <p>If a separate thread makes changes on the same database connection
9057 while <a href="#sqlite3_changes">sqlite3_changes()</a> is running then the value returned
9058 is unpredictable and not meaningful.</p>
9059
9060 <p>See also:
9061 <ul>
9062 <li> the <a href="#sqlite3_total_changes">sqlite3_total_changes()</a> interface
9063 <li> the <a href="pragma.html#pragma_count_changes">count_changes pragma</a>
9064 <li> the <a href="lang_corefunc.html#changes">changes() SQL function</a>
9065 <li> the <a href="pragma.html#pragma_data_version">data_version pragma</a>
9066 </ul>
9067 </p><hr><a name="sqlite3_close"></a>
9068 <h2>Closing A Database Connection</h2>
9069 </div>
9070 <blockquote><pre>
9071 int sqlite3_close(sqlite3*);
9072 int sqlite3_close_v2(sqlite3*);
9073 </pre></blockquote>
9074 <p>
9075 The sqlite3_close() and sqlite3_close_v2() routines are destructors
9076 for the <a href="#sqlite3">sqlite3</a> object.
9077 Calls to sqlite3_close() and sqlite3_close_v2() return <a href="#SQLITE_ABORT">SQLITE_OK</a> if
9078 the <a href="#sqlite3">sqlite3</a> object is successfully destroyed and all associated
9079 resources are deallocated.</p>
9080
9081 <p>Ideally, applications should <a href="#sqlite3_finalize">finalize</a> all
9082 <a href="#sqlite3_stmt">prepared statements</a>, <a href="#sqlite3_blob_close">close</a> all <a href="#sqlite3_blob">BLOB handles</a>, and
9083 <a href="#sqlite3backupfinish">finish</a> all <a href="#sqlite3_backup">sqlite3_backup</a> objects associated
9084 with the <a href="#sqlite3">sqlite3</a> object prior to attempting to close the object.
9085 If the database connection is associated with unfinalized prepared
9086 statements, BLOB handlers, and/or unfinished sqlite3_backup objects then
9087 sqlite3_close() will leave the database connection open and return
9088 <a href="#SQLITE_ABORT">SQLITE_BUSY</a>. If sqlite3_close_v2() is called with unfinalized prepared
9089 statements, unclosed BLOB handlers, and/or unfinished sqlite3_backups,
9090 it returns <a href="#SQLITE_ABORT">SQLITE_OK</a> regardless, but instead of deallocating the database
9091 connection immediately, it marks the database connection as an unusable
9092 "zombie" and makes arrangements to automatically deallocate the database
9093 connection after all prepared statements are finalized, all BLOB handles
9094 are closed, and all backups have finished. The sqlite3_close_v2() interface
9095 is intended for use with host languages that are garbage collected, and
9096 where the order in which destructors are called is arbitrary.</p>
9097
9098 <p>If an <a href="#sqlite3">sqlite3</a> object is destroyed while a transaction is open,
9099 the transaction is automatically rolled back.</p>
9100
9101 <p>The C parameter to <a href="#sqlite3_close">sqlite3_close(C)</a> and <a href="#sqlite3_close">sqlite3_close_v2(C)</a>
9102 must be either a NULL
9103 pointer or an <a href="#sqlite3">sqlite3</a> object pointer obtained
9104 from <a href="#sqlite3_open">sqlite3_open()</a>, <a href="#sqlite3_open">sqlite3_open16()</a>, or
9105 <a href="#sqlite3_open">sqlite3_open_v2()</a>, and not previously closed.
9106 Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
9107 argument is a harmless no-op.
9108 </p><hr><a name="sqlite3_collation_needed"></a>
9109 <h2>Collation Needed Callbacks</h2>
9110 </div>
9111 <blockquote><pre>
9112 int sqlite3_collation_needed(
9113 sqlite3*,
9114 void*,
9115 void(*)(void*,sqlite3*,int eTextRep,const char*)
9116 );
9117 int sqlite3_collation_needed16(
9118 sqlite3*,
9119 void*,
9120 void(*)(void*,sqlite3*,int eTextRep,const void*)
9121 );
9122 </pre></blockquote>
9123 <p>
9124 To avoid having to register all collation sequences before a database
9125 can be used, a single callback function may be registered with the
9126 <a href="#sqlite3">database connection</a> to be invoked whenever an undefined collation
9127 sequence is required.</p>
9128
9129 <p>If the function is registered using the sqlite3_collation_needed() API,
9130 then it is passed the names of undefined collation sequences as strings
9131 encoded in UTF-8. If sqlite3_collation_needed16() is used,
9132 the names are passed as UTF-16 in machine native byte order.
9133 A call to either function replaces the existing collation-needed callback.</p>
9134
9135 <p>When the callback is invoked, the first argument passed is a copy
9136 of the second argument to sqlite3_collation_needed() or
9137 sqlite3_collation_needed16(). The second argument is the database
9138 connection. The third argument is one of <a href="#sqliteutf8">SQLITE_UTF8</a>, <a href="#sqliteutf16be">SQLITE_UTF16BE</a>,
9139 or <a href="#sqliteutf16le">SQLITE_UTF16LE</a>, indicating the most desirable form of the collation
9140 sequence function required. The fourth parameter is the name of the
9141 required collation sequence.</p>
9142
9143 <p>The callback function should register the desired collation using
9144 <a href="#sqlite3_create_collation">sqlite3_create_collation()</a>, <a href="#sqlite3_create_collation">sqlite3_create_collation16()</a>, or
9145 <a href="#sqlite3_create_collation">sqlite3_create_collation_v2()</a>.
9146 </p><hr><a name="sqlite3_column_database_name"></a>
9147 <h2>Source Of Data In A Query Result</h2>
9148 </div>
9149 <blockquote><pre>
9150 const char *sqlite3_column_database_name(sqlite3_stmt*,int);
9151 const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
9152 const char *sqlite3_column_table_name(sqlite3_stmt*,int);
9153 const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
9154 const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
9155 const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
9156 </pre></blockquote>
9157 <p>
9158 These routines provide a means to determine the database, table, and
9159 table column that is the origin of a particular result column in a
9160 <a href="lang_select.html">SELECT</a> statement.
9161 The name of the database or table or column can be returned as
9162 either a UTF-8 or UTF-16 string. The _database_ routines return
9163 the database name, the _table_ routines return the table name, and
9164 the origin_ routines return the column name.
9165 The returned string is valid until the <a href="#sqlite3_stmt">prepared statement</a> is destroyed
9166 using <a href="#sqlite3_finalize">sqlite3_finalize()</a> or until the statement is automatically
9167 reprepared by the first call to <a href="#sqlite3_step">sqlite3_step()</a> for a particular run
9168 or until the same information is requested
9169 again in a different encoding.</p>
9170
9171 <p>The names returned are the original un-aliased names of the
9172 database, table, and column.</p>
9173
9174 <p>The first argument to these interfaces is a <a href="#sqlite3_stmt">prepared statement</a>.
9175 These functions return information about the Nth result column returned by
9176 the statement, where N is the second function argument.
9177 The left-most column is column 0 for these routines.</p>
9178
9179 <p>If the Nth column returned by the statement is an expression or
9180 subquery and is not a column value, then all of these functions return
9181 NULL. These routines might also return NULL if a memory allocation error
9182 occurs. Otherwise, they return the name of the attached database, table,
9183 or column that query result column was extracted from.</p>
9184
9185 <p>As with all other SQLite APIs, those whose names end with "16" return
9186 UTF-16 encoded strings and the other functions return UTF-8.</p>
9187
9188 <p>These APIs are only available if the library was compiled with the
9189 <a href="compile.html#enable_column_metadata">SQLITE_ENABLE_COLUMN_METADATA</a> C-preprocessor symbol.</p>
9190
9191 <p>If two or more threads call one or more
9192 <a href="#sqlite3_column_database_name">column metadata interfaces</a>
9193 for the same <a href="#sqlite3_stmt">prepared statement</a> and result column
9194 at the same time then the results are undefined.
9195 </p><hr><a name="sqlite3_column_decltype"></a>
9196 <h2>Declared Datatype Of A Query Result</h2>
9197 </div>
9198 <blockquote><pre>
9199 const char *sqlite3_column_decltype(sqlite3_stmt*,int);
9200 const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
9201 </pre></blockquote>
9202 <p>
9203 The first parameter is a <a href="#sqlite3_stmt">prepared statement</a>.
9204 If this statement is a <a href="lang_select.html">SELECT</a> statement and the Nth column of the
9205 returned result set of that <a href="lang_select.html">SELECT</a> is a table column (not an
9206 expression or subquery) then the declared type of the table
9207 column is returned. If the Nth column of the result set is an
9208 expression or subquery, then a NULL pointer is returned.
9209 The returned string is always UTF-8 encoded.</p>
9210
9211 <p>For example, given the database schema:</p>
9212
9213 <p>CREATE TABLE t1(c1 VARIANT);</p>
9214
9215 <p>and the following statement to be compiled:</p>
9216
9217 <p>SELECT c1 + 1, c1 FROM t1;</p>
9218
9219 <p>this routine would return the string "VARIANT" for the second result
9220 column (i==1), and a NULL pointer for the first result column (i==0).</p>
9221
9222 <p>SQLite uses dynamic run-time typing. So just because a column
9223 is declared to contain a particular type does not mean that the
9224 data stored in that column is of the declared type. SQLite is
9225 strongly typed, but the typing is dynamic not static. Type
9226 is associated with individual values, not with the containers
9227 used to hold those values.
9228 </p><hr><a name="sqlite3_column_name"></a>
9229 <h2>Column Names In A Result Set</h2>
9230 </div>
9231 <blockquote><pre>
9232 const char *sqlite3_column_name(sqlite3_stmt*, int N);
9233 const void *sqlite3_column_name16(sqlite3_stmt*, int N);
9234 </pre></blockquote>
9235 <p>
9236 These routines return the name assigned to a particular column
9237 in the result set of a <a href="lang_select.html">SELECT</a> statement. The sqlite3_column_name()
9238 interface returns a pointer to a zero-terminated UTF-8 string
9239 and sqlite3_column_name16() returns a pointer to a zero-terminated
9240 UTF-16 string. The first parameter is the <a href="#sqlite3_stmt">prepared statement</a>
9241 that implements the <a href="lang_select.html">SELECT</a> statement. The second parameter is the
9242 column number. The leftmost column is number 0.</p>
9243
9244 <p>The returned string pointer is valid until either the <a href="#sqlite3_stmt">prepared statement</a>
9245 is destroyed by <a href="#sqlite3_finalize">sqlite3_finalize()</a> or until the statement is automatically
9246 reprepared by the first call to <a href="#sqlite3_step">sqlite3_step()</a> for a particular run
9247 or until the next call to
9248 sqlite3_column_name() or sqlite3_column_name16() on the same column.</p>
9249
9250 <p>If sqlite3_malloc() fails during the processing of either routine
9251 (for example during a conversion from UTF-8 to UTF-16) then a
9252 NULL pointer is returned.</p>
9253
9254 <p>The name of a result column is the value of the "AS" clause for
9255 that column, if there is an AS clause. If there is no AS clause
9256 then the name of the column is unspecified and may change from
9257 one release of SQLite to the next.
9258 </p><hr><a name="sqlite3_commit_hook"></a>
9259 <h2>Commit And Rollback Notification Callbacks</h2>
9260 </div>
9261 <blockquote><pre>
9262 void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
9263 void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
9264 </pre></blockquote>
9265 <p>
9266 The sqlite3_commit_hook() interface registers a callback
9267 function to be invoked whenever a transaction is <a href="lang_transaction.html">committed</a>.
9268 Any callback set by a previous call to sqlite3_commit_hook()
9269 for the same database connection is overridden.
9270 The sqlite3_rollback_hook() interface registers a callback
9271 function to be invoked whenever a transaction is <a href="lang_transaction.html">rolled back</a>.
9272 Any callback set by a previous call to sqlite3_rollback_hook()
9273 for the same database connection is overridden.
9274 The pArg argument is passed through to the callback.
9275 If the callback on a commit hook function returns non-zero,
9276 then the commit is converted into a rollback.</p>
9277
9278 <p>The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions
9279 return the P argument from the previous call of the same function
9280 on the same <a href="#sqlite3">database connection</a> D, or NULL for
9281 the first call for each function on D.</p>
9282
9283 <p>The commit and rollback hook callbacks are not reentrant.
9284 The callback implementation must not do anything that will modify
9285 the database connection that invoked the callback. Any actions
9286 to modify the database connection must be deferred until after the
9287 completion of the <a href="#sqlite3_step">sqlite3_step()</a> call that triggered the commit
9288 or rollback hook in the first place.
9289 Note that running any other SQL statements, including SELECT statements,
9290 or merely calling <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> and <a href="#sqlite3_step">sqlite3_step()</a> will modify
9291 the database connections for the meaning of "modify" in this paragraph.</p>
9292
9293 <p>Registering a NULL function disables the callback.</p>
9294
9295 <p>When the commit hook callback routine returns zero, the <a href="lang_transaction.html">COMMIT</a>
9296 operation is allowed to continue normally. If the commit hook
9297 returns non-zero, then the <a href="lang_transaction.html">COMMIT</a> is converted into a <a href="lang_transaction.html">ROLLBACK</a>.
9298 The rollback hook is invoked on a rollback that results from a commit
9299 hook returning non-zero, just as it would be with any other rollback.</p>
9300
9301 <p>For the purposes of this API, a transaction is said to have been
9302 rolled back if an explicit "ROLLBACK" statement is executed, or
9303 an error or constraint causes an implicit rollback to occur.
9304 The rollback callback is not invoked if a transaction is
9305 automatically rolled back because the database connection is closed.</p>
9306
9307 <p>See also the <a href="#sqlite3_update_hook">sqlite3_update_hook()</a> interface.
9308 </p><hr><a name="sqlite3_compileoption_get"></a>
9309 <h2>Run-Time Library Compilation Options Diagnostics</h2>
9310 </div>
9311 <blockquote><pre>
9312 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
9313 int sqlite3_compileoption_used(const char *zOptName);
9314 const char *sqlite3_compileoption_get(int N);
9315 #else
9316 # define sqlite3_compileoption_used(X) 0
9317 # define sqlite3_compileoption_get(X) ((void*)0)
9318 #endif
9319 </pre></blockquote>
9320 <p>
9321 The sqlite3_compileoption_used() function returns 0 or 1
9322 indicating whether the specified option was defined at
9323 compile time. The SQLITE_ prefix may be omitted from the
9324 option name passed to sqlite3_compileoption_used().</p>
9325
9326 <p>The sqlite3_compileoption_get() function allows iterating
9327 over the list of options that were defined at compile time by
9328 returning the N-th compile time option string. If N is out of range,
9329 sqlite3_compileoption_get() returns a NULL pointer. The SQLITE_
9330 prefix is omitted from any strings returned by
9331 sqlite3_compileoption_get().</p>
9332
9333 <p>Support for the diagnostic functions sqlite3_compileoption_used()
9334 and sqlite3_compileoption_get() may be omitted by specifying the
9335 <a href="compile.html#omit_compileoption_diags">SQLITE_OMIT_COMPILEOPTION_DIAGS</a> option at compile time.</p>
9336
9337 <p>See also: SQL functions <a href="lang_corefunc.html#sqlite_compileoption_used">sqlite_compileoption_used()</a> and
9338 <a href="lang_corefunc.html#sqlite_compileoption_get">sqlite_compileoption_get()</a> and the <a href="pragma.html#pragma_compile_options">compile_options pragma</a>.
9339 </p><hr><a name="sqlite3_complete"></a>
9340 <h2>Determine If An SQL Statement Is Complete</h2>
9341 </div>
9342 <blockquote><pre>
9343 int sqlite3_complete(const char *sql);
9344 int sqlite3_complete16(const void *sql);
9345 </pre></blockquote>
9346 <p>
9347 These routines are useful during command-line input to determine if the
9348 currently entered text seems to form a complete SQL statement or
9349 if additional input is needed before sending the text into
9350 SQLite for parsing. These routines return 1 if the input string
9351 appears to be a complete SQL statement. A statement is judged to be
9352 complete if it ends with a semicolon token and is not a prefix of a
9353 well-formed CREATE TRIGGER statement. Semicolons that are embedded within
9354 string literals or quoted identifier names or comments are not
9355 independent tokens (they are part of the token in which they are
9356 embedded) and thus do not count as a statement terminator. Whitespace
9357 and comments that follow the final semicolon are ignored.</p>
9358
9359 <p>These routines return 0 if the statement is incomplete. If a
9360 memory allocation fails, then SQLITE_NOMEM is returned.</p>
9361
9362 <p>These routines do not parse the SQL statements and thus
9363 will not detect syntactically incorrect SQL.</p>
9364
9365 <p>If SQLite has not been initialized using <a href="#sqlite3_initialize">sqlite3_initialize()</a> prior
9366 to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
9367 automatically by sqlite3_complete16(). If that initialization fails,
9368 then the return value from sqlite3_complete16() will be non-zero
9369 regardless of whether or not the input SQL is complete.</p>
9370
9371 <p>The input to <a href="#sqlite3_complete">sqlite3_complete()</a> must be a zero-terminated
9372 UTF-8 string.</p>
9373
9374 <p>The input to <a href="#sqlite3_complete">sqlite3_complete16()</a> must be a zero-terminated
9375 UTF-16 string in native byte order.
9376 </p><hr><a name="sqlite3_create_collation"></a>
9377 <h2>Define New Collating Sequences</h2>
9378 </div>
9379 <blockquote><pre>
9380 int sqlite3_create_collation(
9381 sqlite3*,
9382 const char *zName,
9383 int eTextRep,
9384 void *pArg,
9385 int(*xCompare)(void*,int,const void*,int,const void*)
9386 );
9387 int sqlite3_create_collation_v2(
9388 sqlite3*,
9389 const char *zName,
9390 int eTextRep,
9391 void *pArg,
9392 int(*xCompare)(void*,int,const void*,int,const void*),
9393 void(*xDestroy)(void*)
9394 );
9395 int sqlite3_create_collation16(
9396 sqlite3*,
9397 const void *zName,
9398 int eTextRep,
9399 void *pArg,
9400 int(*xCompare)(void*,int,const void*,int,const void*)
9401 );
9402 </pre></blockquote>
9403 <p>
9404 These functions add, remove, or modify a <a href="datatype3.html#collation">collation</a> associated
9405 with the <a href="#sqlite3">database connection</a> specified as the first argument.</p>
9406
9407 <p>The name of the collation is a UTF-8 string
9408 for sqlite3_create_collation() and sqlite3_create_collation_v2()
9409 and a UTF-16 string in native byte order for sqlite3_create_collation16().
9410 Collation names that compare equal according to <a href="#sqlite3_stricmp">sqlite3_strnicmp()</a> are
9411 considered to be the same name.</p>
9412
9413 <p>The third argument (eTextRep) must be one of the constants:
9414 <ul>
9415 <li> <a href="#sqliteutf8">SQLITE_UTF8</a>,
9416 <li> <a href="#sqliteutf16le">SQLITE_UTF16LE</a>,
9417 <li> <a href="#sqliteutf16be">SQLITE_UTF16BE</a>,
9418 <li> <a href="#sqliteutf16">SQLITE_UTF16</a>, or
9419 <li> <a href="#sqliteutf16aligned">SQLITE_UTF16_ALIGNED</a>.
9420 </ul>
9421 The eTextRep argument determines the encoding of strings passed
9422 to the collating function callback, xCompare.
9423 The <a href="#sqliteutf16">SQLITE_UTF16</a> and <a href="#sqliteutf16aligned">SQLITE_UTF16_ALIGNED</a> values for eTextRep
9424 force strings to be UTF16 with native byte order.
9425 The <a href="#sqliteutf16aligned">SQLITE_UTF16_ALIGNED</a> value for eTextRep forces strings to begin
9426 on an even byte address.</p>
9427
9428 <p>The fourth argument, pArg, is an application data pointer that is passed
9429 through as the first argument to the collating function callback.</p>
9430
9431 <p>The fifth argument, xCompare, is a pointer to the collating function.
9432 Multiple collating functions can be registered using the same name but
9433 with different eTextRep parameters and SQLite will use whichever
9434 function requires the least amount of data transformation.
9435 If the xCompare argument is NULL then the collating function is
9436 deleted. When all collating functions having the same name are deleted,
9437 that collation is no longer usable.</p>
9438
9439 <p>The collating function callback is invoked with a copy of the pArg
9440 application data pointer and with two strings in the encoding specified
9441 by the eTextRep argument. The two integer parameters to the collating
9442 function callback are the length of the two strings, in bytes. The collating
9443 function must return an integer that is negative, zero, or positive
9444 if the first string is less than, equal to, or greater than the second,
9445 respectively. A collating function must always return the same answer
9446 given the same inputs. If two or more collating functions are registered
9447 to the same collation name (using different eTextRep values) then all
9448 must give an equivalent answer when invoked with equivalent strings.
9449 The collating function must obey the following properties for all
9450 strings A, B, and C:</p>
9451
9452 <p><ol>
9453 <li> If A==B then B==A.
9454 <li> If A==B and B==C then A==C.
9455 <li> If A&lt;B THEN B&gt;A.
9456 <li> If A&lt;B and B&lt;C then A&lt;C.
9457 </ol></p>
9458
9459 <p>If a collating function fails any of the above constraints and that
9460 collating function is registered and used, then the behavior of SQLite
9461 is undefined.</p>
9462
9463 <p>The sqlite3_create_collation_v2() works like sqlite3_create_collation()
9464 with the addition that the xDestroy callback is invoked on pArg when
9465 the collating function is deleted.
9466 Collating functions are deleted when they are overridden by later
9467 calls to the collation creation functions or when the
9468 <a href="#sqlite3">database connection</a> is closed using <a href="#sqlite3_close">sqlite3_close()</a>.</p>
9469
9470 <p>The xDestroy callback is <u>not</u> called if the
9471 sqlite3_create_collation_v2() function fails. Applications that invoke
9472 sqlite3_create_collation_v2() with a non-NULL xDestroy argument should
9473 check the return code and dispose of the application data pointer
9474 themselves rather than expecting SQLite to deal with it for them.
9475 This is different from every other SQLite interface. The inconsistency
9476 is unfortunate but cannot be changed without breaking backwards
9477 compatibility.</p>
9478
9479 <p>See also: <a href="#sqlite3_collation_needed">sqlite3_collation_needed()</a> and <a href="#sqlite3_collation_needed">sqlite3_collation_needed16()</a>.
9480 </p><hr><a name="sqlite3_create_filename"></a>
9481 <h2>Create and Destroy VFS Filenames</h2>
9482 </div>
9483 <blockquote><pre>
9484 sqlite3_filename sqlite3_create_filename(
9485 const char *zDatabase,
9486 const char *zJournal,
9487 const char *zWal,
9488 int nParam,
9489 const char **azParam
9490 );
9491 void sqlite3_free_filename(sqlite3_filename);
9492 </pre></blockquote>
9493 <p>
9494 These interfaces are provided for use by <a href="vfs.html#shim">VFS shim</a> implementations and
9495 are not useful outside of that context.</p>
9496
9497 <p>The sqlite3_create_filename(D,J,W,N,P) allocates memory to hold a version of
9498 database filename D with corresponding journal file J and WAL file W and
9499 an array P of N URI Key/Value pairs. The result from
9500 sqlite3_create_filename(D,J,W,N,P) is a pointer to a database filename that
9501 is safe to pass to routines like:
9502 <ul>
9503 <li> <a href="#sqlite3_uri_boolean">sqlite3_uri_parameter()</a>,
9504 <li> <a href="#sqlite3_uri_boolean">sqlite3_uri_boolean()</a>,
9505 <li> <a href="#sqlite3_uri_boolean">sqlite3_uri_int64()</a>,
9506 <li> <a href="#sqlite3_uri_boolean">sqlite3_uri_key()</a>,
9507 <li> <a href="#sqlite3_filename_database">sqlite3_filename_database()</a>,
9508 <li> <a href="#sqlite3_filename_database">sqlite3_filename_journal()</a>, or
9509 <li> <a href="#sqlite3_filename_database">sqlite3_filename_wal()</a>.
9510 </ul>
9511 If a memory allocation error occurs, sqlite3_create_filename() might
9512 return a NULL pointer. The memory obtained from sqlite3_create_filename(X)
9513 must be released by a corresponding call to sqlite3_free_filename(Y).</p>
9514
9515 <p>The P parameter in sqlite3_create_filename(D,J,W,N,P) should be an array
9516 of 2*N pointers to strings. Each pair of pointers in this array corresponds
9517 to a key and value for a query parameter. The P parameter may be a NULL
9518 pointer if N is zero. None of the 2*N pointers in the P array may be
9519 NULL pointers and key pointers should not be empty strings.
9520 None of the D, J, or W parameters to sqlite3_create_filename(D,J,W,N,P) may
9521 be NULL pointers, though they can be empty strings.</p>
9522
9523 <p>The sqlite3_free_filename(Y) routine releases a memory allocation
9524 previously obtained from sqlite3_create_filename(). Invoking
9525 sqlite3_free_filename(Y) where Y is a NULL pointer is a harmless no-op.</p>
9526
9527 <p>If the Y parameter to sqlite3_free_filename(Y) is anything other
9528 than a NULL pointer or a pointer previously acquired from
9529 sqlite3_create_filename(), then bad things such as heap
9530 corruption or segfaults may occur. The value Y should not be
9531 used again after sqlite3_free_filename(Y) has been called. This means
9532 that if the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen()</a> method of a VFS has been called using Y,
9533 then the corresponding [sqlite3_module.xClose() method should also be
9534 invoked prior to calling sqlite3_free_filename(Y).
9535 </p><hr><a name="sqlite3_create_module"></a>
9536 <h2>Register A Virtual Table Implementation</h2>
9537 </div>
9538 <blockquote><pre>
9539 int sqlite3_create_module(
9540 sqlite3 *db, /* SQLite connection to register module with */
9541 const char *zName, /* Name of the module */
9542 const sqlite3_module *p, /* Methods for the module */
9543 void *pClientData /* Client data for xCreate/xConnect */
9544 );
9545 int sqlite3_create_module_v2(
9546 sqlite3 *db, /* SQLite connection to register module with */
9547 const char *zName, /* Name of the module */
9548 const sqlite3_module *p, /* Methods for the module */
9549 void *pClientData, /* Client data for xCreate/xConnect */
9550 void(*xDestroy)(void*) /* Module destructor function */
9551 );
9552 </pre></blockquote>
9553 <p>
9554 These routines are used to register a new <a href="#sqlite3_module">virtual table module</a> name.
9555 Module names must be registered before
9556 creating a new <a href="vtab.html">virtual table</a> using the module and before using a
9557 preexisting <a href="vtab.html">virtual table</a> for the module.</p>
9558
9559 <p>The module name is registered on the <a href="#sqlite3">database connection</a> specified
9560 by the first parameter. The name of the module is given by the
9561 second parameter. The third parameter is a pointer to
9562 the implementation of the <a href="#sqlite3_module">virtual table module</a>. The fourth
9563 parameter is an arbitrary client data pointer that is passed through
9564 into the <a href="vtab.html#xcreate">xCreate</a> and <a href="vtab.html#xconnect">xConnect</a> methods of the virtual table module
9565 when a new virtual table is being created or reinitialized.</p>
9566
9567 <p>The sqlite3_create_module_v2() interface has a fifth parameter which
9568 is a pointer to a destructor for the pClientData. SQLite will
9569 invoke the destructor function (if it is not NULL) when SQLite
9570 no longer needs the pClientData pointer. The destructor will also
9571 be invoked if the call to sqlite3_create_module_v2() fails.
9572 The sqlite3_create_module()
9573 interface is equivalent to sqlite3_create_module_v2() with a NULL
9574 destructor.</p>
9575
9576 <p>If the third parameter (the pointer to the sqlite3_module object) is
9577 NULL then no new module is created and any existing modules with the
9578 same name are dropped.</p>
9579
9580 <p>See also: <a href="#sqlite3_drop_modules">sqlite3_drop_modules()</a>
9581 </p><hr><a name="sqlite3_db_status"></a>
9582 <h2>Database Connection Status</h2>
9583 </div>
9584 <blockquote><pre>
9585 int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
9586 int sqlite3_db_status64(sqlite3*,int,sqlite3_int64*,sqlite3_int64*,int);
9587 </pre></blockquote>
9588 <p>
9589 This interface is used to retrieve runtime status information
9590 about a single <a href="#sqlite3">database connection</a>. The first argument is the
9591 database connection object to be interrogated. The second argument
9592 is an integer constant, taken from the set of
9593 <a href="#SQLITE_DBSTATUS options">SQLITE_DBSTATUS options</a>, that
9594 determines the parameter to interrogate. The set of
9595 <a href="#SQLITE_DBSTATUS options">SQLITE_DBSTATUS options</a> is likely
9596 to grow in future releases of SQLite.</p>
9597
9598 <p>The current value of the requested parameter is written into *pCur
9599 and the highest instantaneous value is written into *pHiwtr. If
9600 the resetFlg is true, then the highest instantaneous value is
9601 reset back down to the current value.</p>
9602
9603 <p>The sqlite3_db_status() routine returns SQLITE_OK on success and a
9604 non-zero <a href="rescode.html">error code</a> on failure.</p>
9605
9606 <p>The sqlite3_db_status64(D,O,C,H,R) routine works exactly the same
9607 way as sqlite3_db_status(D,O,C,H,R) routine except that the C and H
9608 parameters are pointer to 64-bit integers (type: sqlite3_int64) instead
9609 of pointers to 32-bit integers, which allows larger status values
9610 to be returned. If a status value exceeds 2,147,483,647 then
9611 sqlite3_db_status() will truncate the value whereas sqlite3_db_status64()
9612 will return the full value.</p>
9613
9614 <p>See also: <a href="#sqlite3_status">sqlite3_status()</a> and <a href="#sqlite3_stmt_status">sqlite3_stmt_status()</a>.
9615 </p><hr><a name="sqlite3_errcode"></a>
9616 <h2>Error Codes And Messages</h2>
9617 </div>
9618 <blockquote><pre>
9619 int sqlite3_errcode(sqlite3 *db);
9620 int sqlite3_extended_errcode(sqlite3 *db);
9621 const char *sqlite3_errmsg(sqlite3*);
9622 const void *sqlite3_errmsg16(sqlite3*);
9623 const char *sqlite3_errstr(int);
9624 int sqlite3_error_offset(sqlite3 *db);
9625 </pre></blockquote>
9626 <p>
9627 If the most recent sqlite3_* API call associated with
9628 <a href="#sqlite3">database connection</a> D failed, then the sqlite3_errcode(D) interface
9629 returns the numeric <a href="rescode.html">result code</a> or <a href="rescode.html#extrc">extended result code</a> for that
9630 API call.
9631 The sqlite3_extended_errcode()
9632 interface is the same except that it always returns the
9633 <a href="rescode.html#extrc">extended result code</a> even when extended result codes are
9634 disabled.</p>
9635
9636 <p>The values returned by sqlite3_errcode() and/or
9637 sqlite3_extended_errcode() might change with each API call.
9638 Except, there are some interfaces that are guaranteed to never
9639 change the value of the error code. The error-code preserving
9640 interfaces include the following:</p>
9641
9642 <p><ul>
9643 <li> sqlite3_errcode()
9644 <li> sqlite3_extended_errcode()
9645 <li> sqlite3_errmsg()
9646 <li> sqlite3_errmsg16()
9647 <li> sqlite3_error_offset()
9648 <li> sqlite3_db_handle()
9649 </ul></p>
9650
9651 <p>The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
9652 text that describes the error, as either UTF-8 or UTF-16 respectively,
9653 or NULL if no error message is available.
9654 (See how SQLite handles <a href="invalidutf.html">invalid UTF</a> for exceptions to this rule.)
9655 Memory to hold the error message string is managed internally.
9656 The application does not need to worry about freeing the result.
9657 However, the error string might be overwritten or deallocated by
9658 subsequent calls to other SQLite interface functions.</p>
9659
9660 <p>The sqlite3_errstr(E) interface returns the English-language text
9661 that describes the <a href="rescode.html">result code</a> E, as UTF-8, or NULL if E is not a
9662 result code for which a text error message is available.
9663 Memory to hold the error message string is managed internally
9664 and must not be freed by the application.</p>
9665
9666 <p>If the most recent error references a specific token in the input
9667 SQL, the sqlite3_error_offset() interface returns the byte offset
9668 of the start of that token. The byte offset returned by
9669 sqlite3_error_offset() assumes that the input SQL is UTF-8.
9670 If the most recent error does not reference a specific token in the input
9671 SQL, then the sqlite3_error_offset() function returns -1.</p>
9672
9673 <p>When the serialized <a href="threadsafe.html">threading mode</a> is in use, it might be the
9674 case that a second error occurs on a separate thread in between
9675 the time of the first error and the call to these interfaces.
9676 When that happens, the second error will be reported since these
9677 interfaces always report the most recent result. To avoid
9678 this, each thread can obtain exclusive use of the <a href="#sqlite3">database connection</a> D
9679 by invoking <a href="#sqlite3_mutex_alloc">sqlite3_mutex_enter</a>(<a href="#sqlite3_db_mutex">sqlite3_db_mutex</a>(D)) before beginning
9680 to use D and invoking <a href="#sqlite3_mutex_alloc">sqlite3_mutex_leave</a>(<a href="#sqlite3_db_mutex">sqlite3_db_mutex</a>(D)) after
9681 all calls to the interfaces listed here are completed.</p>
9682
9683 <p>If an interface fails with SQLITE_MISUSE, that means the interface
9684 was invoked incorrectly by the application. In that case, the
9685 error code and message may or may not be set.
9686 </p><hr><a name="sqlite3_expanded_sql"></a>
9687 <h2>Retrieving Statement SQL</h2>
9688 </div>
9689 <blockquote><pre>
9690 const char *sqlite3_sql(sqlite3_stmt *pStmt);
9691 char *sqlite3_expanded_sql(sqlite3_stmt *pStmt);
9692 #ifdef SQLITE_ENABLE_NORMALIZE
9693 const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt);
9694 #endif
9695 </pre></blockquote>
9696 <p>
9697 The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
9698 SQL text used to create <a href="#sqlite3_stmt">prepared statement</a> P if P was
9699 created by <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>, <a href="#sqlite3_prepare">sqlite3_prepare_v3()</a>,
9700 <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a>, or <a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a>.
9701 The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
9702 string containing the SQL text of prepared statement P with
9703 <a href="lang_expr.html#varparam">bound parameters</a> expanded.
9704 The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8
9705 string containing the normalized SQL text of prepared statement P. The
9706 semantics used to normalize a SQL statement are unspecified and subject
9707 to change. At a minimum, literal values will be replaced with suitable
9708 placeholders.</p>
9709
9710 <p>For example, if a prepared statement is created using the SQL
9711 text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
9712 and parameter :xyz is unbound, then sqlite3_sql() will return
9713 the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql()
9714 will return "SELECT 2345,NULL".</p>
9715
9716 <p>The sqlite3_expanded_sql() interface returns NULL if insufficient memory
9717 is available to hold the result, or if the result would exceed the
9718 maximum string length determined by the <a href="#sqlitelimitlength">SQLITE_LIMIT_LENGTH</a>.</p>
9719
9720 <p>The <a href="compile.html#trace_size_limit">SQLITE_TRACE_SIZE_LIMIT</a> compile-time option limits the size of
9721 bound parameter expansions. The <a href="compile.html#omit_trace">SQLITE_OMIT_TRACE</a> compile-time
9722 option causes sqlite3_expanded_sql() to always return NULL.</p>
9723
9724 <p>The strings returned by sqlite3_sql(P) and sqlite3_normalized_sql(P)
9725 are managed by SQLite and are automatically freed when the prepared
9726 statement is finalized.
9727 The string returned by sqlite3_expanded_sql(P), on the other hand,
9728 is obtained from <a href="#sqlite3_free">sqlite3_malloc()</a> and must be freed by the application
9729 by passing it to <a href="#sqlite3_free">sqlite3_free()</a>.</p>
9730
9731 <p>The sqlite3_normalized_sql() interface is only available if
9732 the <a href="compile.html#enable_normalize">SQLITE_ENABLE_NORMALIZE</a> compile-time option is defined.
9733 </p><hr><a name="sqlite3_filename_database"></a>
9734 <h2>Translate filenames</h2>
9735 </div>
9736 <blockquote><pre>
9737 const char *sqlite3_filename_database(sqlite3_filename);
9738 const char *sqlite3_filename_journal(sqlite3_filename);
9739 const char *sqlite3_filename_wal(sqlite3_filename);
9740 </pre></blockquote>
9741 <p>
9742 These routines are available to <a href="vfs.html">custom VFS implementations</a> for
9743 translating filenames between the main database file, the journal file,
9744 and the WAL file.</p>
9745
9746 <p>If F is the name of an sqlite database file, journal file, or WAL file
9747 passed by the SQLite core into the VFS, then sqlite3_filename_database(F)
9748 returns the name of the corresponding database file.</p>
9749
9750 <p>If F is the name of an sqlite database file, journal file, or WAL file
9751 passed by the SQLite core into the VFS, or if F is a database filename
9752 obtained from <a href="#sqlite3_db_filename">sqlite3_db_filename()</a>, then sqlite3_filename_journal(F)
9753 returns the name of the corresponding rollback journal file.</p>
9754
9755 <p>If F is the name of an sqlite database file, journal file, or WAL file
9756 that was passed by the SQLite core into the VFS, or if F is a database
9757 filename obtained from <a href="#sqlite3_db_filename">sqlite3_db_filename()</a>, then
9758 sqlite3_filename_wal(F) returns the name of the corresponding
9759 WAL file.</p>
9760
9761 <p>In all of the above, if F is not the name of a database, journal or WAL
9762 filename passed into the VFS from the SQLite core and F is not the
9763 return value from <a href="#sqlite3_db_filename">sqlite3_db_filename()</a>, then the result is
9764 undefined and is likely a memory access violation.
9765 </p><hr><a name="sqlite3_free"></a>
9766 <h2>Memory Allocation Subsystem</h2>
9767 </div>
9768 <blockquote><pre>
9769 void *sqlite3_malloc(int);
9770 void *sqlite3_malloc64(sqlite3_uint64);
9771 void *sqlite3_realloc(void*, int);
9772 void *sqlite3_realloc64(void*, sqlite3_uint64);
9773 void sqlite3_free(void*);
9774 sqlite3_uint64 sqlite3_msize(void*);
9775 </pre></blockquote>
9776 <p>
9777 The SQLite core uses these three routines for all of its own
9778 internal memory allocation needs. "Core" in the previous sentence
9779 does not include operating-system specific <a href="vfs.html">VFS</a> implementation. The
9780 Windows VFS uses native malloc() and free() for some operations.</p>
9781
9782 <p>The sqlite3_malloc() routine returns a pointer to a block
9783 of memory at least N bytes in length, where N is the parameter.
9784 If sqlite3_malloc() is unable to obtain sufficient free
9785 memory, it returns a NULL pointer. If the parameter N to
9786 sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
9787 a NULL pointer.</p>
9788
9789 <p>The sqlite3_malloc64(N) routine works just like
9790 sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
9791 of a signed 32-bit integer.</p>
9792
9793 <p>Calling sqlite3_free() with a pointer previously returned
9794 by sqlite3_malloc() or sqlite3_realloc() releases that memory so
9795 that it might be reused. The sqlite3_free() routine is
9796 a no-op if it is called with a NULL pointer. Passing a NULL pointer
9797 to sqlite3_free() is harmless. After being freed, memory
9798 should neither be read nor written. Even reading previously freed
9799 memory might result in a segmentation fault or other severe error.
9800 Memory corruption, a segmentation fault, or other severe error
9801 might result if sqlite3_free() is called with a non-NULL pointer that
9802 was not obtained from sqlite3_malloc() or sqlite3_realloc().</p>
9803
9804 <p>The sqlite3_realloc(X,N) interface attempts to resize a
9805 prior memory allocation X to be at least N bytes.
9806 If the X parameter to sqlite3_realloc(X,N)
9807 is a NULL pointer then its behavior is identical to calling
9808 sqlite3_malloc(N).
9809 If the N parameter to sqlite3_realloc(X,N) is zero or
9810 negative then the behavior is exactly the same as calling
9811 sqlite3_free(X).
9812 sqlite3_realloc(X,N) returns a pointer to a memory allocation
9813 of at least N bytes in size or NULL if insufficient memory is available.
9814 If M is the size of the prior allocation, then min(N,M) bytes of the
9815 prior allocation are copied into the beginning of the buffer returned
9816 by sqlite3_realloc(X,N) and the prior allocation is freed.
9817 If sqlite3_realloc(X,N) returns NULL and N is positive, then the
9818 prior allocation is not freed.</p>
9819
9820 <p>The sqlite3_realloc64(X,N) interface works the same as
9821 sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
9822 of a 32-bit signed integer.</p>
9823
9824 <p>If X is a memory allocation previously obtained from sqlite3_malloc(),
9825 sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then
9826 sqlite3_msize(X) returns the size of that memory allocation in bytes.
9827 The value returned by sqlite3_msize(X) might be larger than the number
9828 of bytes requested when X was allocated. If X is a NULL pointer then
9829 sqlite3_msize(X) returns zero. If X points to something that is not
9830 the beginning of memory allocation, or if it points to a formerly
9831 valid memory allocation that has now been freed, then the behavior
9832 of sqlite3_msize(X) is undefined and possibly harmful.</p>
9833
9834 <p>The memory returned by sqlite3_malloc(), sqlite3_realloc(),
9835 sqlite3_malloc64(), and sqlite3_realloc64()
9836 is always aligned to at least an 8 byte boundary, or to a
9837 4 byte boundary if the <a href="compile.html#4_byte_aligned_malloc">SQLITE_4_BYTE_ALIGNED_MALLOC</a> compile-time
9838 option is used.</p>
9839
9840 <p>The pointer arguments to <a href="#sqlite3_free">sqlite3_free()</a> and <a href="#sqlite3_free">sqlite3_realloc()</a>
9841 must be either NULL or else pointers obtained from a prior
9842 invocation of <a href="#sqlite3_free">sqlite3_malloc()</a> or <a href="#sqlite3_free">sqlite3_realloc()</a> that have
9843 not yet been released.</p>
9844
9845 <p>The application must not read or write any part of
9846 a block of memory after it has been released using
9847 <a href="#sqlite3_free">sqlite3_free()</a> or <a href="#sqlite3_free">sqlite3_realloc()</a>.
9848 </p><hr><a name="sqlite3_free_table"></a>
9849 <h2>Convenience Routines For Running Queries</h2>
9850 </div>
9851 <blockquote><pre>
9852 int sqlite3_get_table(
9853 sqlite3 *db, /* An open database */
9854 const char *zSql, /* SQL to be evaluated */
9855 char ***pazResult, /* Results of the query */
9856 int *pnRow, /* Number of result rows written here */
9857 int *pnColumn, /* Number of result columns written here */
9858 char **pzErrmsg /* Error msg written here */
9859 );
9860 void sqlite3_free_table(char **result);
9861 </pre></blockquote>
9862 <p>
9863 This is a legacy interface that is preserved for backwards compatibility.
9864 Use of this interface is not recommended.</p>
9865
9866 <p>Definition: A <b>result table</b> is a memory data structure created by the
9867 <a href="#sqlite3_free_table">sqlite3_get_table()</a> interface. A result table records the
9868 complete query results from one or more queries.</p>
9869
9870 <p>The table conceptually has a number of rows and columns. But
9871 these numbers are not part of the result table itself. These
9872 numbers are obtained separately. Let N be the number of rows
9873 and M be the number of columns.</p>
9874
9875 <p>A result table is an array of pointers to zero-terminated UTF-8 strings.
9876 There are (N+1)*M elements in the array. The first M pointers point
9877 to zero-terminated strings that contain the names of the columns.
9878 The remaining entries all point to query results. NULL values result
9879 in NULL pointers. All other values are in their UTF-8 zero-terminated
9880 string representation as returned by <a href="#sqlite3_column_blob">sqlite3_column_text()</a>.</p>
9881
9882 <p>A result table might consist of one or more memory allocations.
9883 It is not safe to pass a result table directly to <a href="#sqlite3_free">sqlite3_free()</a>.
9884 A result table should be deallocated using <a href="#sqlite3_free_table">sqlite3_free_table()</a>.</p>
9885
9886 <p>As an example of the result table format, suppose a query result
9887 is as follows:</p>
9888
9889 <p><blockquote><pre>
9890 Name | Age
9891 -----------------------
9892 Alice | 43
9893 Bob | 28
9894 Cindy | 21
9895 </pre></blockquote></p>
9896
9897 <p>There are two columns (M==2) and three rows (N==3). Thus the
9898 result table has 8 entries. Suppose the result table is stored
9899 in an array named azResult. Then azResult holds this content:</p>
9900
9901 <p><blockquote><pre>
9902 azResult&#91;0] = "Name";
9903 azResult&#91;1] = "Age";
9904 azResult&#91;2] = "Alice";
9905 azResult&#91;3] = "43";
9906 azResult&#91;4] = "Bob";
9907 azResult&#91;5] = "28";
9908 azResult&#91;6] = "Cindy";
9909 azResult&#91;7] = "21";
9910 </pre></blockquote></p>
9911
9912 <p>The sqlite3_get_table() function evaluates one or more
9913 semicolon-separated SQL statements in the zero-terminated UTF-8
9914 string of its 2nd parameter and returns a result table to the
9915 pointer given in its 3rd parameter.</p>
9916
9917 <p>After the application has finished with the result from sqlite3_get_table(),
9918 it must pass the result table pointer to sqlite3_free_table() in order to
9919 release the memory that was malloced. Because of the way the
9920 <a href="#sqlite3_free">sqlite3_malloc()</a> happens within sqlite3_get_table(), the calling
9921 function must not try to call <a href="#sqlite3_free">sqlite3_free()</a> directly. Only
9922 <a href="#sqlite3_free_table">sqlite3_free_table()</a> is able to release the memory properly and safely.</p>
9923
9924 <p>The sqlite3_get_table() interface is implemented as a wrapper around
9925 <a href="#sqlite3_exec">sqlite3_exec()</a>. The sqlite3_get_table() routine does not have access
9926 to any internal data structures of SQLite. It uses only the public
9927 interface defined here. As a consequence, errors that occur in the
9928 wrapper layer outside of the internal <a href="#sqlite3_exec">sqlite3_exec()</a> call are not
9929 reflected in subsequent calls to <a href="#sqlite3_errcode">sqlite3_errcode()</a> or
9930 <a href="#sqlite3_errcode">sqlite3_errmsg()</a>.
9931 </p><hr><a name="sqlite3_get_auxdata"></a>
9932 <h2>Function Auxiliary Data</h2>
9933 </div>
9934 <blockquote><pre>
9935 void *sqlite3_get_auxdata(sqlite3_context*, int N);
9936 void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
9937 </pre></blockquote>
9938 <p>
9939 These functions may be used by (non-aggregate) SQL functions to
9940 associate auxiliary data with argument values. If the same argument
9941 value is passed to multiple invocations of the same SQL function during
9942 query execution, under some circumstances the associated auxiliary data
9943 might be preserved. An example of where this might be useful is in a
9944 regular-expression matching function. The compiled version of the regular
9945 expression can be stored as auxiliary data associated with the pattern
9946 string. Then as long as the pattern string remains the same,
9947 the compiled regular expression can be reused on multiple
9948 invocations of the same function.</p>
9949
9950 <p>The sqlite3_get_auxdata(C,N) interface returns a pointer to the auxiliary
9951 data associated by the sqlite3_set_auxdata(C,N,P,X) function with the
9952 Nth argument value to the application-defined function. N is zero
9953 for the left-most function argument. If there is no auxiliary data
9954 associated with the function argument, the sqlite3_get_auxdata(C,N)
9955 interface returns a NULL pointer.</p>
9956
9957 <p>The sqlite3_set_auxdata(C,N,P,X) interface saves P as auxiliary data for the
9958 N-th argument of the application-defined function. Subsequent
9959 calls to sqlite3_get_auxdata(C,N) return P from the most recent
9960 sqlite3_set_auxdata(C,N,P,X) call if the auxiliary data is still valid or
9961 NULL if the auxiliary data has been discarded.
9962 After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
9963 SQLite will invoke the destructor function X with parameter P exactly
9964 once, when the auxiliary data is discarded.
9965 SQLite is free to discard the auxiliary data at any time, including: <ul>
9966 <li> when the corresponding function parameter changes, or
9967 <li> when <a href="#sqlite3_reset">sqlite3_reset()</a> or <a href="#sqlite3_finalize">sqlite3_finalize()</a> is called for the
9968 SQL statement, or
9969 <li> when sqlite3_set_auxdata() is invoked again on the same
9970 parameter, or
9971 <li> during the original sqlite3_set_auxdata() call when a memory
9972 allocation error occurs.
9973 <li> during the original sqlite3_set_auxdata() call if the function
9974 is evaluated during query planning instead of during query execution,
9975 as sometimes happens with <a href="compile.html#enable_stat4">SQLITE_ENABLE_STAT4</a>. </ul></p>
9976
9977 <p>Note the last two bullets in particular. The destructor X in
9978 sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the
9979 sqlite3_set_auxdata() interface even returns. Hence sqlite3_set_auxdata()
9980 should be called near the end of the function implementation and the
9981 function implementation should not make any use of P after
9982 sqlite3_set_auxdata() has been called. Furthermore, a call to
9983 sqlite3_get_auxdata() that occurs immediately after a corresponding call
9984 to sqlite3_set_auxdata() might still return NULL if an out-of-memory
9985 condition occurred during the sqlite3_set_auxdata() call or if the
9986 function is being evaluated during query planning rather than during
9987 query execution.</p>
9988
9989 <p>In practice, auxiliary data is preserved between function calls for
9990 function parameters that are compile-time constants, including literal
9991 values and <a href="lang_expr.html#varparam">parameters</a> and expressions composed from the same.</p>
9992
9993 <p>The value of the N parameter to these interfaces should be non-negative.
9994 Future enhancements may make use of negative N values to define new
9995 kinds of function caching behavior.</p>
9996
9997 <p>These routines must be called from the same thread in which
9998 the SQL function is running.</p>
9999
10000 <p>See also: <a href="#sqlite3_get_clientdata">sqlite3_get_clientdata()</a> and <a href="#sqlite3_get_clientdata">sqlite3_set_clientdata()</a>.
10001 </p><hr><a name="sqlite3_get_clientdata"></a>
10002 <h2>Database Connection Client Data</h2>
10003 </div>
10004 <blockquote><pre>
10005 void *sqlite3_get_clientdata(sqlite3*,const char*);
10006 int sqlite3_set_clientdata(sqlite3*, const char*, void*, void(*)(void*));
10007 </pre></blockquote>
10008 <p>
10009 These functions are used to associate one or more named pointers
10010 with a <a href="#sqlite3">database connection</a>.
10011 A call to sqlite3_set_clientdata(D,N,P,X) causes the pointer P
10012 to be attached to <a href="#sqlite3">database connection</a> D using name N. Subsequent
10013 calls to sqlite3_get_clientdata(D,N) will return a copy of pointer P
10014 or a NULL pointer if there were no prior calls to
10015 sqlite3_set_clientdata() with the same values of D and N.
10016 Names are compared using strcmp() and are thus case sensitive.
10017 It returns 0 on success and SQLITE_NOMEM on allocation failure.</p>
10018
10019 <p>If P and X are both non-NULL, then the destructor X is invoked with
10020 argument P on the first of the following occurrences:
10021 <ul>
10022 <li> An out-of-memory error occurs during the call to
10023 sqlite3_set_clientdata() which attempts to register pointer P.
10024 <li> A subsequent call to sqlite3_set_clientdata(D,N,P,X) is made
10025 with the same D and N parameters.
10026 <li> The database connection closes. SQLite does not make any guarantees
10027 about the order in which destructors are called, only that all
10028 destructors will be called exactly once at some point during the
10029 database connection closing process.
10030 </ul></p>
10031
10032 <p>SQLite does not do anything with client data other than invoke
10033 destructors on the client data at the appropriate time. The intended
10034 use for client data is to provide a mechanism for wrapper libraries
10035 to store additional information about an SQLite database connection.</p>
10036
10037 <p>There is no limit (other than available memory) on the number of different
10038 client data pointers (with different names) that can be attached to a
10039 single database connection. However, the current implementation stores
10040 the content on a linked list. Insert and retrieval performance will
10041 be proportional to the number of entries. The design use case, and
10042 the use case for which the implementation is optimized, is
10043 that an application will store only small number of client data names,
10044 typically just one or two. This interface is not intended to be a
10045 generalized key/value store for thousands or millions of keys. It
10046 will work for that, but performance might be disappointing.</p>
10047
10048 <p>There is no way to enumerate the client data pointers
10049 associated with a database connection. The N parameter can be thought
10050 of as a secret key such that only code that knows the secret key is able
10051 to access the associated data.</p>
10052
10053 <p>Security Warning: These interfaces should not be exposed in scripting
10054 languages or in other circumstances where it might be possible for an
10055 attacker to invoke them. Any agent that can invoke these interfaces
10056 can probably also take control of the process.</p>
10057
10058 <p>Database connection client data is only available for SQLite
10059 version 3.44.0 (2023-11-01) and later.</p>
10060
10061 <p>See also: <a href="#sqlite3_get_auxdata">sqlite3_set_auxdata()</a> and <a href="#sqlite3_get_auxdata">sqlite3_get_auxdata()</a>.
10062 </p><hr><a name="sqlite3_hard_heap_limit64"></a>
10063 <h2>Impose A Limit On Heap Size</h2>
10064 </div>
10065 <blockquote><pre>
10066 sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
10067 sqlite3_int64 sqlite3_hard_heap_limit64(sqlite3_int64 N);
10068 </pre></blockquote>
10069 <p>
10070 These interfaces impose limits on the amount of heap memory that will be
10071 used by all database connections within a single process.</p>
10072
10073 <p>The sqlite3_soft_heap_limit64() interface sets and/or queries the
10074 soft limit on the amount of heap memory that may be allocated by SQLite.
10075 SQLite strives to keep heap memory utilization below the soft heap
10076 limit by reducing the number of pages held in the page cache
10077 as heap memory usages approaches the limit.
10078 The soft heap limit is "soft" because even though SQLite strives to stay
10079 below the limit, it will exceed the limit rather than generate
10080 an <a href="#SQLITE_ABORT">SQLITE_NOMEM</a> error. In other words, the soft heap limit
10081 is advisory only.</p>
10082
10083 <p>The sqlite3_hard_heap_limit64(N) interface sets a hard upper bound of
10084 N bytes on the amount of memory that will be allocated. The
10085 sqlite3_hard_heap_limit64(N) interface is similar to
10086 sqlite3_soft_heap_limit64(N) except that memory allocations will fail
10087 when the hard heap limit is reached.</p>
10088
10089 <p>The return value from both sqlite3_soft_heap_limit64() and
10090 sqlite3_hard_heap_limit64() is the size of
10091 the heap limit prior to the call, or negative in the case of an
10092 error. If the argument N is negative
10093 then no change is made to the heap limit. Hence, the current
10094 size of heap limits can be determined by invoking
10095 sqlite3_soft_heap_limit64(-1) or sqlite3_hard_heap_limit(-1).</p>
10096
10097 <p>Setting the heap limits to zero disables the heap limiter mechanism.</p>
10098
10099 <p>The soft heap limit may not be greater than the hard heap limit.
10100 If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N)
10101 is invoked with a value of N that is greater than the hard heap limit,
10102 the soft heap limit is set to the value of the hard heap limit.
10103 The soft heap limit is automatically enabled whenever the hard heap
10104 limit is enabled. When sqlite3_hard_heap_limit64(N) is invoked and
10105 the soft heap limit is outside the range of 1..N, then the soft heap
10106 limit is set to N. Invoking sqlite3_soft_heap_limit64(0) when the
10107 hard heap limit is enabled makes the soft heap limit equal to the
10108 hard heap limit.</p>
10109
10110 <p>The memory allocation limits can also be adjusted using
10111 <a href="pragma.html#pragma_soft_heap_limit">PRAGMA soft_heap_limit</a> and <a href="pragma.html#pragma_hard_heap_limit">PRAGMA hard_heap_limit</a>.</p>
10112
10113 <p>The heap limits are not enforced in the current implementation
10114 if one or more of following conditions are true:</p>
10115
10116 <p><ul>
10117 <li> The limit value is set to zero.
10118 <li> Memory accounting is disabled using a combination of the
10119 <a href="#sqlite3_config">sqlite3_config</a>(<a href="#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a>,...) start-time option and
10120 the <a href="compile.html#default_memstatus">SQLITE_DEFAULT_MEMSTATUS</a> compile-time option.
10121 <li> An alternative page cache implementation is specified using
10122 <a href="#sqlite3_config">sqlite3_config</a>(<a href="#sqliteconfigpcache2">SQLITE_CONFIG_PCACHE2</a>,...).
10123 <li> The page cache allocates from its own memory pool supplied
10124 by <a href="#sqlite3_config">sqlite3_config</a>(<a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>,...) rather than
10125 from the heap.
10126 </ul></p>
10127
10128 <p>The circumstances under which SQLite will enforce the heap limits may
10129 change in future releases of SQLite.
10130 </p><hr><a name="sqlite3_initialize"></a>
10131 <h2>Initialize The SQLite Library</h2>
10132 </div>
10133 <blockquote><pre>
10134 int sqlite3_initialize(void);
10135 int sqlite3_shutdown(void);
10136 int sqlite3_os_init(void);
10137 int sqlite3_os_end(void);
10138 </pre></blockquote>
10139 <p>
10140 The sqlite3_initialize() routine initializes the
10141 SQLite library. The sqlite3_shutdown() routine
10142 deallocates any resources that were allocated by sqlite3_initialize().
10143 These routines are designed to aid in process initialization and
10144 shutdown on embedded systems. Workstation applications using
10145 SQLite normally do not need to invoke either of these routines.</p>
10146
10147 <p>A call to sqlite3_initialize() is an "effective" call if it is
10148 the first time sqlite3_initialize() is invoked during the lifetime of
10149 the process, or if it is the first time sqlite3_initialize() is invoked
10150 following a call to sqlite3_shutdown(). Only an effective call
10151 of sqlite3_initialize() does any initialization. All other calls
10152 are harmless no-ops.</p>
10153
10154 <p>A call to sqlite3_shutdown() is an "effective" call if it is the first
10155 call to sqlite3_shutdown() since the last sqlite3_initialize(). Only
10156 an effective call to sqlite3_shutdown() does any deinitialization.
10157 All other valid calls to sqlite3_shutdown() are harmless no-ops.</p>
10158
10159 <p>The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
10160 is not. The sqlite3_shutdown() interface must only be called from a
10161 single thread. All open <a href="#sqlite3">database connections</a> must be closed and all
10162 other SQLite resources must be deallocated prior to invoking
10163 sqlite3_shutdown().</p>
10164
10165 <p>Among other things, sqlite3_initialize() will invoke
10166 sqlite3_os_init(). Similarly, sqlite3_shutdown()
10167 will invoke sqlite3_os_end().</p>
10168
10169 <p>The sqlite3_initialize() routine returns <a href="#SQLITE_ABORT">SQLITE_OK</a> on success.
10170 If for some reason, sqlite3_initialize() is unable to initialize
10171 the library (perhaps it is unable to allocate a needed resource such
10172 as a mutex) it returns an <a href="rescode.html">error code</a> other than <a href="#SQLITE_ABORT">SQLITE_OK</a>.</p>
10173
10174 <p>The sqlite3_initialize() routine is called internally by many other
10175 SQLite interfaces so that an application usually does not need to
10176 invoke sqlite3_initialize() directly. For example, <a href="#sqlite3_open">sqlite3_open()</a>
10177 calls sqlite3_initialize() so the SQLite library will be automatically
10178 initialized when <a href="#sqlite3_open">sqlite3_open()</a> is called if it has not been initialized
10179 already. However, if SQLite is compiled with the <a href="compile.html#omit_autoinit">SQLITE_OMIT_AUTOINIT</a>
10180 compile-time option, then the automatic calls to sqlite3_initialize()
10181 are omitted and the application must call sqlite3_initialize() directly
10182 prior to using any other SQLite interface. For maximum portability,
10183 it is recommended that applications always invoke sqlite3_initialize()
10184 directly prior to using any other SQLite interface. Future releases
10185 of SQLite may require this. In other words, the behavior exhibited
10186 when SQLite is compiled with <a href="compile.html#omit_autoinit">SQLITE_OMIT_AUTOINIT</a> might become the
10187 default behavior in some future release of SQLite.</p>
10188
10189 <p>The sqlite3_os_init() routine does operating-system specific
10190 initialization of the SQLite library. The sqlite3_os_end()
10191 routine undoes the effect of sqlite3_os_init(). Typical tasks
10192 performed by these routines include allocation or deallocation
10193 of static resources, initialization of global variables,
10194 setting up a default <a href="#sqlite3_vfs">sqlite3_vfs</a> module, or setting up
10195 a default configuration using <a href="#sqlite3_config">sqlite3_config()</a>.</p>
10196
10197 <p>The application should never invoke either sqlite3_os_init()
10198 or sqlite3_os_end() directly. The application should only invoke
10199 sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init()
10200 interface is called automatically by sqlite3_initialize() and
10201 sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
10202 implementations for sqlite3_os_init() and sqlite3_os_end()
10203 are built into SQLite when it is compiled for Unix, Windows, or OS/2.
10204 When <a href="custombuild.html">built for other platforms</a>
10205 (using the <a href="compile.html#os_other">SQLITE_OS_OTHER=1</a> compile-time
10206 option) the application must supply a suitable implementation for
10207 sqlite3_os_init() and sqlite3_os_end(). An application-supplied
10208 implementation of sqlite3_os_init() or sqlite3_os_end()
10209 must return <a href="#SQLITE_ABORT">SQLITE_OK</a> on success and some other <a href="rescode.html">error code</a> upon
10210 failure.
10211 </p><hr><a name="sqlite3_interrupt"></a>
10212 <h2>Interrupt A Long-Running Query</h2>
10213 </div>
10214 <blockquote><pre>
10215 void sqlite3_interrupt(sqlite3*);
10216 int sqlite3_is_interrupted(sqlite3*);
10217 </pre></blockquote>
10218 <p>
10219 This function causes any pending database operation to abort and
10220 return at its earliest opportunity. This routine is typically
10221 called in response to a user action such as pressing "Cancel"
10222 or Ctrl-C where the user wants a long query operation to halt
10223 immediately.</p>
10224
10225 <p>It is safe to call this routine from a thread different from the
10226 thread that is currently running the database operation. But it
10227 is not safe to call this routine with a <a href="#sqlite3">database connection</a> that
10228 is closed or might close before sqlite3_interrupt() returns.</p>
10229
10230 <p>If an SQL operation is very nearly finished at the time when
10231 sqlite3_interrupt() is called, then it might not have an opportunity
10232 to be interrupted and might continue to completion.</p>
10233
10234 <p>An SQL operation that is interrupted will return <a href="#SQLITE_ABORT">SQLITE_INTERRUPT</a>.
10235 If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
10236 that is inside an explicit transaction, then the entire transaction
10237 will be rolled back automatically.</p>
10238
10239 <p>The sqlite3_interrupt(D) call is in effect until all currently running
10240 SQL statements on <a href="#sqlite3">database connection</a> D complete. Any new SQL statements
10241 that are started after the sqlite3_interrupt() call and before the
10242 running statement count reaches zero are interrupted as if they had been
10243 running prior to the sqlite3_interrupt() call. New SQL statements
10244 that are started after the running statement count reaches zero are
10245 not effected by the sqlite3_interrupt().
10246 A call to sqlite3_interrupt(D) that occurs when there are no running
10247 SQL statements is a no-op and has no effect on SQL statements
10248 that are started after the sqlite3_interrupt() call returns.</p>
10249
10250 <p>The <a href="#sqlite3_interrupt">sqlite3_is_interrupted(D)</a> interface can be used to determine whether
10251 or not an interrupt is currently in effect for <a href="#sqlite3">database connection</a> D.
10252 It returns 1 if an interrupt is currently in effect, or 0 otherwise.
10253 </p><hr><a name="sqlite3_keyword_check"></a>
10254 <h2>SQL Keyword Checking</h2>
10255 </div>
10256 <blockquote><pre>
10257 int sqlite3_keyword_count(void);
10258 int sqlite3_keyword_name(int,const char**,int*);
10259 int sqlite3_keyword_check(const char*,int);
10260 </pre></blockquote>
10261 <p>
10262 These routines provide access to the set of SQL language keywords
10263 recognized by SQLite. Applications can use these routines to determine
10264 whether or not a specific identifier needs to be escaped (for example,
10265 by enclosing in double-quotes) so as not to confuse the parser.</p>
10266
10267 <p>The sqlite3_keyword_count() interface returns the number of distinct
10268 keywords understood by SQLite.</p>
10269
10270 <p>The sqlite3_keyword_name(N,Z,L) interface finds the 0-based N-th keyword and
10271 makes *Z point to that keyword expressed as UTF8 and writes the number
10272 of bytes in the keyword into *L. The string that *Z points to is not
10273 zero-terminated. The sqlite3_keyword_name(N,Z,L) routine returns
10274 SQLITE_OK if N is within bounds and SQLITE_ERROR if not. If either Z
10275 or L are NULL or invalid pointers then calls to
10276 sqlite3_keyword_name(N,Z,L) result in undefined behavior.</p>
10277
10278 <p>The sqlite3_keyword_check(Z,L) interface checks to see whether or not
10279 the L-byte UTF8 identifier that Z points to is a keyword, returning non-zero
10280 if it is and zero if not.</p>
10281
10282 <p>The parser used by SQLite is forgiving. It is often possible to use
10283 a keyword as an identifier as long as such use does not result in a
10284 parsing ambiguity. For example, the statement
10285 "CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" is accepted by SQLite, and
10286 creates a new table named "BEGIN" with three columns named
10287 "REPLACE", "PRAGMA", and "END". Nevertheless, best practice is to avoid
10288 using keywords as identifiers. Common techniques used to avoid keyword
10289 name collisions include:
10290 <ul>
10291 <li> Put all identifier names inside double-quotes. This is the official
10292 SQL way to escape identifier names.
10293 <li> Put identifier names inside &#91;...&#93;. This is not standard SQL,
10294 but it is what SQL Server does and so lots of programmers use this
10295 technique.
10296 <li> Begin every identifier with the letter "Z" as no SQL keywords start
10297 with "Z".
10298 <li> Include a digit somewhere in every identifier name.
10299 </ul></p>
10300
10301 <p>Note that the number of keywords understood by SQLite can depend on
10302 compile-time options. For example, "VACUUM" is not a keyword if
10303 SQLite is compiled with the <a href="compile.html#omit_vacuum">-DSQLITE_OMIT_VACUUM</a> option. Also,
10304 new keywords may be added to future releases of SQLite.
10305 </p><hr><a name="sqlite3_libversion"></a>
10306 <h2>Run-Time Library Version Numbers</h2>
10307 </div>
10308 <blockquote><pre>
10309 SQLITE_EXTERN const char sqlite3_version[];
10310 const char *sqlite3_libversion(void);
10311 const char *sqlite3_sourceid(void);
10312 int sqlite3_libversion_number(void);
10313 </pre></blockquote>
10314 <p>
10315 These interfaces provide the same information as the <a href="#SQLITE_SCM_BRANCH">SQLITE_VERSION</a>,
10316 <a href="#SQLITE_SCM_BRANCH">SQLITE_VERSION_NUMBER</a>, and <a href="#SQLITE_SCM_BRANCH">SQLITE_SOURCE_ID</a> C preprocessor macros
10317 but are associated with the library instead of the header file. Cautious
10318 programmers might include assert() statements in their application to
10319 verify that values returned by these interfaces match the macros in
10320 the header, and thus ensure that the application is
10321 compiled with matching library and header files.</p>
10322
10323 <p><blockquote><pre>
10324 assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
10325 assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 );
10326 assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
10327 </pre></blockquote></p>
10328
10329 <p>The sqlite3_version[] string constant contains the text of the
10330 <a href="#SQLITE_SCM_BRANCH">SQLITE_VERSION</a> macro. The sqlite3_libversion() function returns a
10331 pointer to the sqlite3_version[] string constant. The sqlite3_libversion()
10332 function is provided for use in DLLs since DLL users usually do not have
10333 direct access to string constants within the DLL. The
10334 sqlite3_libversion_number() function returns an integer equal to
10335 <a href="#SQLITE_SCM_BRANCH">SQLITE_VERSION_NUMBER</a>. The sqlite3_sourceid() function returns
10336 a pointer to a string constant whose value is the same as the
10337 <a href="#SQLITE_SCM_BRANCH">SQLITE_SOURCE_ID</a> C preprocessor macro. Except if SQLite is built
10338 using an edited copy of <a href="amalgamation.html">the amalgamation</a>, then the last four characters
10339 of the hash might be different from <a href="#SQLITE_SCM_BRANCH">SQLITE_SOURCE_ID</a>.</p>
10340
10341 <p>See also: <a href="lang_corefunc.html#sqlite_version">sqlite_version()</a> and <a href="lang_corefunc.html#sqlite_source_id">sqlite_source_id()</a>.
10342 </p><hr><a name="sqlite3_memory_highwater"></a>
10343 <h2>Memory Allocator Statistics</h2>
10344 </div>
10345 <blockquote><pre>
10346 sqlite3_int64 sqlite3_memory_used(void);
10347 sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
10348 </pre></blockquote>
10349 <p>
10350 SQLite provides these two interfaces for reporting on the status
10351 of the <a href="#sqlite3_free">sqlite3_malloc()</a>, <a href="#sqlite3_free">sqlite3_free()</a>, and <a href="#sqlite3_free">sqlite3_realloc()</a>
10352 routines, which form the built-in memory allocation subsystem.</p>
10353
10354 <p>The <a href="#sqlite3_memory_highwater">sqlite3_memory_used()</a> routine returns the number of bytes
10355 of memory currently outstanding (malloced but not freed).
10356 The <a href="#sqlite3_memory_highwater">sqlite3_memory_highwater()</a> routine returns the maximum
10357 value of <a href="#sqlite3_memory_highwater">sqlite3_memory_used()</a> since the high-water mark
10358 was last reset. The values returned by <a href="#sqlite3_memory_highwater">sqlite3_memory_used()</a> and
10359 <a href="#sqlite3_memory_highwater">sqlite3_memory_highwater()</a> include any overhead
10360 added by SQLite in its implementation of <a href="#sqlite3_free">sqlite3_malloc()</a>,
10361 but not overhead added by any underlying system library
10362 routines that <a href="#sqlite3_free">sqlite3_malloc()</a> may call.</p>
10363
10364 <p>The memory high-water mark is reset to the current value of
10365 <a href="#sqlite3_memory_highwater">sqlite3_memory_used()</a> if and only if the parameter to
10366 <a href="#sqlite3_memory_highwater">sqlite3_memory_highwater()</a> is true. The value returned
10367 by <a href="#sqlite3_memory_highwater">sqlite3_memory_highwater(1)</a> is the high-water mark
10368 prior to the reset.
10369 </p><hr><a name="sqlite3_mprintf"></a>
10370 <h2>Formatted String Printing Functions</h2>
10371 </div>
10372 <blockquote><pre>
10373 char *sqlite3_mprintf(const char*,...);
10374 char *sqlite3_vmprintf(const char*, va_list);
10375 char *sqlite3_snprintf(int,char*,const char*, ...);
10376 char *sqlite3_vsnprintf(int,char*,const char*, va_list);
10377 </pre></blockquote>
10378 <p>
10379 These routines are work-alikes of the "printf()" family of functions
10380 from the standard C library.
10381 These routines understand most of the common formatting options from
10382 the standard library printf()
10383 plus some additional non-standard formats (<a href="printf.html#percentq">%q</a>, <a href="printf.html#percentq">%Q</a>, <a href="printf.html#percentw">%w</a>, and <a href="printf.html#percentz">%z</a>).
10384 See the <a href="printf.html">built-in printf()</a> documentation for details.</p>
10385
10386 <p>The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
10387 results into memory obtained from <a href="#sqlite3_free">sqlite3_malloc64()</a>.
10388 The strings returned by these two routines should be
10389 released by <a href="#sqlite3_free">sqlite3_free()</a>. Both routines return a
10390 NULL pointer if <a href="#sqlite3_free">sqlite3_malloc64()</a> is unable to allocate enough
10391 memory to hold the resulting string.</p>
10392
10393 <p>The sqlite3_snprintf() routine is similar to "snprintf()" from
10394 the standard C library. The result is written into the
10395 buffer supplied as the second parameter whose size is given by
10396 the first parameter. Note that the order of the
10397 first two parameters is reversed from snprintf(). This is an
10398 historical accident that cannot be fixed without breaking
10399 backwards compatibility. Note also that sqlite3_snprintf()
10400 returns a pointer to its buffer instead of the number of
10401 characters actually written into the buffer. We admit that
10402 the number of characters written would be a more useful return
10403 value but we cannot change the implementation of sqlite3_snprintf()
10404 now without breaking compatibility.</p>
10405
10406 <p>As long as the buffer size is greater than zero, sqlite3_snprintf()
10407 guarantees that the buffer is always zero-terminated. The first
10408 parameter "n" is the total size of the buffer, including space for
10409 the zero terminator. So the longest string that can be completely
10410 written will be n-1 characters.</p>
10411
10412 <p>The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().</p>
10413
10414 <p>See also: <a href="printf.html">built-in printf()</a>, <a href="lang_corefunc.html#printf">printf() SQL function</a>
10415 </p><hr><a name="sqlite3_mutex_alloc"></a>
10416 <h2>Mutexes</h2>
10417 </div>
10418 <blockquote><pre>
10419 sqlite3_mutex *sqlite3_mutex_alloc(int);
10420 void sqlite3_mutex_free(sqlite3_mutex*);
10421 void sqlite3_mutex_enter(sqlite3_mutex*);
10422 int sqlite3_mutex_try(sqlite3_mutex*);
10423 void sqlite3_mutex_leave(sqlite3_mutex*);
10424 </pre></blockquote>
10425 <p>
10426 The SQLite core uses these routines for thread
10427 synchronization. Though they are intended for internal
10428 use by SQLite, code that links against SQLite is
10429 permitted to use any of these routines.</p>
10430
10431 <p>The SQLite source code contains multiple implementations
10432 of these mutex routines. An appropriate implementation
10433 is selected automatically at compile-time. The following
10434 implementations are available in the SQLite core:</p>
10435
10436 <p><ul>
10437 <li> SQLITE_MUTEX_PTHREADS
10438 <li> SQLITE_MUTEX_W32
10439 <li> SQLITE_MUTEX_NOOP
10440 </ul></p>
10441
10442 <p>The SQLITE_MUTEX_NOOP implementation is a set of routines
10443 that does no real locking and is appropriate for use in
10444 a single-threaded application. The SQLITE_MUTEX_PTHREADS and
10445 SQLITE_MUTEX_W32 implementations are appropriate for use on Unix
10446 and Windows.</p>
10447
10448 <p>The sqlite3_mutex_alloc() routine allocates a new
10449 mutex and returns a pointer to it. The sqlite3_mutex_alloc()
10450 routine returns NULL if it is unable to allocate the requested
10451 mutex. The argument to sqlite3_mutex_alloc() must be one of these
10452 integer constants:</p>
10453
10454 <p><ul>
10455 <li> SQLITE_MUTEX_FAST
10456 <li> SQLITE_MUTEX_RECURSIVE
10457 <li> SQLITE_MUTEX_STATIC_MAIN
10458 <li> SQLITE_MUTEX_STATIC_MEM
10459 <li> SQLITE_MUTEX_STATIC_OPEN
10460 <li> SQLITE_MUTEX_STATIC_PRNG
10461 <li> SQLITE_MUTEX_STATIC_LRU
10462 <li> SQLITE_MUTEX_STATIC_PMEM
10463 <li> SQLITE_MUTEX_STATIC_APP1
10464 <li> SQLITE_MUTEX_STATIC_APP2
10465 <li> SQLITE_MUTEX_STATIC_APP3
10466 <li> SQLITE_MUTEX_STATIC_VFS1
10467 <li> SQLITE_MUTEX_STATIC_VFS2
10468 <li> SQLITE_MUTEX_STATIC_VFS3
10469 </ul></p>
10470
10471 <p>The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
10472 cause sqlite3_mutex_alloc() to create
10473 a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
10474 is used but not necessarily so when SQLITE_MUTEX_FAST is used.
10475 The mutex implementation does not need to make a distinction
10476 between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
10477 not want to. SQLite will only request a recursive mutex in
10478 cases where it really needs one. If a faster non-recursive mutex
10479 implementation is available on the host platform, the mutex subsystem
10480 might return such a mutex in response to SQLITE_MUTEX_FAST.</p>
10481
10482 <p>The other allowed parameters to sqlite3_mutex_alloc() (anything other
10483 than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return
10484 a pointer to a static preexisting mutex. Nine static mutexes are
10485 used by the current version of SQLite. Future versions of SQLite
10486 may add additional static mutexes. Static mutexes are for internal
10487 use by SQLite only. Applications that use SQLite mutexes should
10488 use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
10489 SQLITE_MUTEX_RECURSIVE.</p>
10490
10491 <p>Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
10492 or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
10493 returns a different mutex on every call. For the static
10494 mutex types, the same mutex is returned on every call that has
10495 the same type number.</p>
10496
10497 <p>The sqlite3_mutex_free() routine deallocates a previously
10498 allocated dynamic mutex. Attempting to deallocate a static
10499 mutex results in undefined behavior.</p>
10500
10501 <p>The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
10502 to enter a mutex. If another thread is already within the mutex,
10503 sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
10504 SQLITE_BUSY. The sqlite3_mutex_try() interface returns <a href="#SQLITE_ABORT">SQLITE_OK</a>
10505 upon successful entry. Mutexes created using
10506 SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
10507 In such cases, the
10508 mutex must be exited an equal number of times before another thread
10509 can enter. If the same thread tries to enter any mutex other
10510 than an SQLITE_MUTEX_RECURSIVE more than once, the behavior is undefined.</p>
10511
10512 <p>Some systems (for example, Windows 95) do not support the operation
10513 implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try()
10514 will always return SQLITE_BUSY. In most cases the SQLite core only uses
10515 sqlite3_mutex_try() as an optimization, so this is acceptable
10516 behavior. The exceptions are unix builds that set the
10517 SQLITE_ENABLE_SETLK_TIMEOUT build option. In that case a working
10518 sqlite3_mutex_try() is required.</p>
10519
10520 <p>The sqlite3_mutex_leave() routine exits a mutex that was
10521 previously entered by the same thread. The behavior
10522 is undefined if the mutex is not currently entered by the
10523 calling thread or is not currently allocated.</p>
10524
10525 <p>If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(),
10526 sqlite3_mutex_leave(), or sqlite3_mutex_free() is a NULL pointer,
10527 then any of the four routines behaves as a no-op.</p>
10528
10529 <p>See also: <a href="#sqlite3_mutex_held">sqlite3_mutex_held()</a> and <a href="#sqlite3_mutex_held">sqlite3_mutex_notheld()</a>.
10530 </p><hr><a name="sqlite3_mutex_held"></a>
10531 <h2>Mutex Verification Routines</h2>
10532 </div>
10533 <blockquote><pre>
10534 #ifndef NDEBUG
10535 int sqlite3_mutex_held(sqlite3_mutex*);
10536 int sqlite3_mutex_notheld(sqlite3_mutex*);
10537 #endif
10538 </pre></blockquote>
10539 <p>
10540 The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
10541 are intended for use inside assert() statements. The SQLite core
10542 never uses these routines except inside an assert() and applications
10543 are advised to follow the lead of the core. The SQLite core only
10544 provides implementations for these routines when it is compiled
10545 with the SQLITE_DEBUG flag. External mutex implementations
10546 are only required to provide these routines if SQLITE_DEBUG is
10547 defined and if NDEBUG is not defined.</p>
10548
10549 <p>These routines should return true if the mutex in their argument
10550 is held or not held, respectively, by the calling thread.</p>
10551
10552 <p>The implementation is not required to provide versions of these
10553 routines that actually work. If the implementation does not provide working
10554 versions of these routines, it should at least provide stubs that always
10555 return true so that one does not get spurious assertion failures.</p>
10556
10557 <p>If the argument to sqlite3_mutex_held() is a NULL pointer then
10558 the routine should return 1. This seems counter-intuitive since
10559 clearly the mutex cannot be held if it does not exist. But
10560 the reason the mutex does not exist is because the build is not
10561 using mutexes. And we do not want the assert() containing the
10562 call to sqlite3_mutex_held() to fail, so a non-zero return is
10563 the appropriate thing to do. The sqlite3_mutex_notheld()
10564 interface should also return 1 when given a NULL pointer.
10565 </p><hr><a name="sqlite3_open"></a>
10566 <h2>Opening A New Database Connection</h2>
10567 </div>
10568 <blockquote><pre>
10569 int sqlite3_open(
10570 const char *filename, /* Database filename (UTF-8) */
10571 sqlite3 **ppDb /* OUT: SQLite db handle */
10572 );
10573 int sqlite3_open16(
10574 const void *filename, /* Database filename (UTF-16) */
10575 sqlite3 **ppDb /* OUT: SQLite db handle */
10576 );
10577 int sqlite3_open_v2(
10578 const char *filename, /* Database filename (UTF-8) */
10579 sqlite3 **ppDb, /* OUT: SQLite db handle */
10580 int flags, /* Flags */
10581 const char *zVfs /* Name of VFS module to use */
10582 );
10583 </pre></blockquote>
10584 <p>
10585 These routines open an SQLite database file as specified by the
10586 filename argument. The filename argument is interpreted as UTF-8 for
10587 sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
10588 order for sqlite3_open16(). A <a href="#sqlite3">database connection</a> handle is usually
10589 returned in *ppDb, even if an error occurs. The only exception is that
10590 if SQLite is unable to allocate memory to hold the <a href="#sqlite3">sqlite3</a> object,
10591 a NULL will be written into *ppDb instead of a pointer to the <a href="#sqlite3">sqlite3</a>
10592 object. If the database is opened (and/or created) successfully, then
10593 <a href="#SQLITE_ABORT">SQLITE_OK</a> is returned. Otherwise an <a href="rescode.html">error code</a> is returned. The
10594 <a href="#sqlite3_errcode">sqlite3_errmsg()</a> or <a href="#sqlite3_errcode">sqlite3_errmsg16()</a> routines can be used to obtain
10595 an English language description of the error following a failure of any
10596 of the sqlite3_open() routines.</p>
10597
10598 <p>The default encoding will be UTF-8 for databases created using
10599 sqlite3_open() or sqlite3_open_v2(). The default encoding for databases
10600 created using sqlite3_open16() will be UTF-16 in the native byte order.</p>
10601
10602 <p>Whether or not an error occurs when it is opened, resources
10603 associated with the <a href="#sqlite3">database connection</a> handle should be released by
10604 passing it to <a href="#sqlite3_close">sqlite3_close()</a> when it is no longer required.</p>
10605
10606 <p>The sqlite3_open_v2() interface works like sqlite3_open()
10607 except that it accepts two additional parameters for additional control
10608 over the new database connection. The flags parameter to
10609 sqlite3_open_v2() must include, at a minimum, one of the following
10610 three flag combinations:</p>
10611
10612 <p><dl>
10613 <dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READONLY</a></dt>
10614 <dd>The database is opened in read-only mode. If the database does
10615 not already exist, an error is returned.</dd></p>
10616
10617 <p><dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READWRITE</a></dt>
10618 <dd>The database is opened for reading and writing if possible, or
10619 reading only if the file is write protected by the operating
10620 system. In either case the database must already exist, otherwise
10621 an error is returned. For historical reasons, if opening in
10622 read-write mode fails due to OS-level permissions, an attempt is
10623 made to open it in read-only mode. <a href="#sqlite3_db_readonly">sqlite3_db_readonly()</a> can be
10624 used to determine whether the database is actually
10625 read-write.</dd></p>
10626
10627 <p><dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READWRITE</a> | <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_CREATE</a></dt>
10628 <dd>The database is opened for reading and writing, and is created if
10629 it does not already exist. This is the behavior that is always used for
10630 sqlite3_open() and sqlite3_open16().</dd>
10631 </dl></p>
10632
10633 <p>In addition to the required flags, the following optional flags are
10634 also supported:</p>
10635
10636 <p><dl>
10637 <dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_URI</a></dt>
10638 <dd>The filename can be interpreted as a URI if this flag is set.</dd></p>
10639
10640 <p><dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_MEMORY</a></dt>
10641 <dd>The database will be opened as an in-memory database. The database
10642 is named by the "filename" argument for the purposes of cache-sharing,
10643 if shared cache mode is enabled, but the "filename" is otherwise ignored.
10644 </dd></p>
10645
10646 <p><dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_NOMUTEX</a></dt>
10647 <dd>The new database connection will use the "multi-thread"
10648 <a href="threadsafe.html">threading mode</a>. This means that separate threads are allowed
10649 to use SQLite at the same time, as long as each thread is using
10650 a different <a href="#sqlite3">database connection</a>.</p>
10651
10652 <p><dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_FULLMUTEX</a></dt>
10653 <dd>The new database connection will use the "serialized"
10654 <a href="threadsafe.html">threading mode</a>. This means the multiple threads can safely
10655 attempt to use the same database connection at the same time.
10656 (Mutexes will block any actual concurrency, but in this mode
10657 there is no harm in trying.)</p>
10658
10659 <p><dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_SHAREDCACHE</a></dt>
10660 <dd>The database is opened with <a href="sharedcache.html">shared cache</a> enabled, overriding
10661 the default shared cache setting provided by
10662 <a href="#sqlite3_enable_shared_cache">sqlite3_enable_shared_cache()</a>.
10663 The <a href="sharedcache.html#dontuse">use of shared cache mode is discouraged</a> and hence shared cache
10664 capabilities may be omitted from many builds of SQLite. In such cases,
10665 this option is a no-op.</p>
10666
10667 <p><dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_PRIVATECACHE</a></dt>
10668 <dd>The database is opened with <a href="sharedcache.html">shared cache</a> disabled, overriding
10669 the default shared cache setting provided by
10670 <a href="#sqlite3_enable_shared_cache">sqlite3_enable_shared_cache()</a>.</p>
10671
10672 <p><a name="openexrescode"></a>
10673 <dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_EXRESCODE</a></dt>
10674 <dd>The database connection comes up in "extended result code mode".
10675 In other words, the database behaves as if
10676 <a href="#sqlite3_extended_result_codes">sqlite3_extended_result_codes(db,1)</a> were called on the database
10677 connection as soon as the connection is created. In addition to setting
10678 the extended result code mode, this flag also causes <a href="#sqlite3_open">sqlite3_open_v2()</a>
10679 to return an extended result code.</dd></p>
10680
10681 <p><a name="opennofollow"></a>
10682 <dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_NOFOLLOW</a></dt>
10683 <dd>The database filename is not allowed to contain a symbolic link</dd>
10684 </dl></p>
10685
10686 <p>If the 3rd parameter to sqlite3_open_v2() is not one of the
10687 required combinations shown above optionally combined with other
10688 <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_* bits</a>
10689 then the behavior is undefined. Historic versions of SQLite
10690 have silently ignored surplus bits in the flags parameter to
10691 sqlite3_open_v2(), however that behavior might not be carried through
10692 into future versions of SQLite and so applications should not rely
10693 upon it. Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op
10694 for sqlite3_open_v2(). The SQLITE_OPEN_EXCLUSIVE does *not* cause
10695 the open to fail if the database already exists. The SQLITE_OPEN_EXCLUSIVE
10696 flag is intended for use by the <a href="#sqlite3_vfs">VFS interface</a> only, and not
10697 by sqlite3_open_v2().</p>
10698
10699 <p>The fourth parameter to sqlite3_open_v2() is the name of the
10700 <a href="#sqlite3_vfs">sqlite3_vfs</a> object that defines the operating system interface that
10701 the new database connection should use. If the fourth parameter is
10702 a NULL pointer then the default <a href="#sqlite3_vfs">sqlite3_vfs</a> object is used.</p>
10703
10704 <p>If the filename is ":memory:", then a private, temporary in-memory database
10705 is created for the connection. This in-memory database will vanish when
10706 the database connection is closed. Future versions of SQLite might
10707 make use of additional special filenames that begin with the ":" character.
10708 It is recommended that when a database filename actually does begin with
10709 a ":" character you should prefix the filename with a pathname such as
10710 "./" to avoid ambiguity.</p>
10711
10712 <p>If the filename is an empty string, then a private, temporary
10713 on-disk database will be created. This private database will be
10714 automatically deleted as soon as the database connection is closed.</p>
10715
10716 <p><a name="urifilenamesinsqlite3open"></a>
10717 <h3>URI Filenames</h3></p>
10718
10719 <p>If <a href="uri.html">URI filename</a> interpretation is enabled, and the filename argument
10720 begins with "file:", then the filename is interpreted as a URI. URI
10721 filename interpretation is enabled if the <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_URI</a> flag is
10722 set in the third argument to sqlite3_open_v2(), or if it has
10723 been enabled globally using the <a href="#sqliteconfiguri">SQLITE_CONFIG_URI</a> option with the
10724 <a href="#sqlite3_config">sqlite3_config()</a> method or by the <a href="compile.html#use_uri">SQLITE_USE_URI</a> compile-time option.
10725 URI filename interpretation is turned off
10726 by default, but future releases of SQLite might enable URI filename
10727 interpretation by default. See "<a href="uri.html">URI filenames</a>" for additional
10728 information.</p>
10729
10730 <p>URI filenames are parsed according to RFC 3986. If the URI contains an
10731 authority, then it must be either an empty string or the string
10732 "localhost". If the authority is not an empty string or "localhost", an
10733 error is returned to the caller. The fragment component of a URI, if
10734 present, is ignored.</p>
10735
10736 <p>SQLite uses the path component of the URI as the name of the disk file
10737 which contains the database. If the path begins with a '/' character,
10738 then it is interpreted as an absolute path. If the path does not begin
10739 with a '/' (meaning that the authority section is omitted from the URI)
10740 then the path is interpreted as a relative path.
10741 On windows, the first component of an absolute path
10742 is a drive specification (e.g. "C:").</p>
10743
10744 <p><a name="coreuriqueryparameters"></a>
10745
10746 The query component of a URI may contain parameters that are interpreted
10747 either by SQLite itself, or by a <a href="vfs.html">custom VFS implementation</a>.
10748 SQLite and its built-in <a href="vfs.html">VFSes</a> interpret the
10749 following query parameters:</p>
10750
10751 <p><ul>
10752 <li> <b>vfs</b>: The "vfs" parameter may be used to specify the name of
10753 a VFS object that provides the operating system interface that should
10754 be used to access the database file on disk. If this option is set to
10755 an empty string the default VFS object is used. Specifying an unknown
10756 VFS is an error. If sqlite3_open_v2() is used and the vfs option is
10757 present, then the VFS specified by the option takes precedence over
10758 the value passed as the fourth parameter to sqlite3_open_v2().</p>
10759
10760 <p><li> <b>mode</b>: The mode parameter may be set to either "ro", "rw",
10761 "rwc", or "memory". Attempting to set it to any other value is
10762 an error.
10763 If "ro" is specified, then the database is opened for read-only
10764 access, just as if the <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READONLY</a> flag had been set in the
10765 third argument to sqlite3_open_v2(). If the mode option is set to
10766 "rw", then the database is opened for read-write (but not create)
10767 access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had
10768 been set. Value "rwc" is equivalent to setting both
10769 SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. If the mode option is
10770 set to "memory" then a pure <a href="inmemorydb.html">in-memory database</a> that never reads
10771 or writes from disk is used. It is an error to specify a value for
10772 the mode parameter that is less restrictive than that specified by
10773 the flags passed in the third parameter to sqlite3_open_v2().</p>
10774
10775 <p><li> <b>cache</b>: The cache parameter may be set to either "shared" or
10776 "private". Setting it to "shared" is equivalent to setting the
10777 SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
10778 sqlite3_open_v2(). Setting the cache parameter to "private" is
10779 equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
10780 If sqlite3_open_v2() is used and the "cache" parameter is present in
10781 a URI filename, its value overrides any behavior requested by setting
10782 SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.</p>
10783
10784 <p><li> <b>psow</b>: The psow parameter indicates whether or not the
10785 <a href="psow.html">powersafe overwrite</a> property does or does not apply to the
10786 storage media on which the database file resides.</p>
10787
10788 <p><li> <b>nolock</b>: The nolock parameter is a boolean query parameter
10789 which if set disables file locking in rollback journal modes. This
10790 is useful for accessing a database on a filesystem that does not
10791 support locking. Caution: Database corruption might result if two
10792 or more processes write to the same database and any one of those
10793 processes uses nolock=1.</p>
10794
10795 <p><li> <b>immutable</b>: The immutable parameter is a boolean query
10796 parameter that indicates that the database file is stored on
10797 read-only media. When immutable is set, SQLite assumes that the
10798 database file cannot be changed, even by a process with higher
10799 privilege, and so the database is opened read-only and all locking
10800 and change detection is disabled. Caution: Setting the immutable
10801 property on a database file that does in fact change can result
10802 in incorrect query results and/or <a href="#SQLITE_ABORT">SQLITE_CORRUPT</a> errors.
10803 See also: <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_IMMUTABLE</a>.</p>
10804
10805 <p></ul></p>
10806
10807 <p>Specifying an unknown parameter in the query component of a URI is not an
10808 error. Future versions of SQLite might understand additional query
10809 parameters. See "<a href="uri.html#coreqp">query parameters with special meaning to SQLite</a>" for
10810 additional information.</p>
10811
10812 <p><a name="urifilenameexamples"></a>
10813 <h3>URI filename examples</h3></p>
10814
10815 <p><table border="1" align=center cellpadding=5>
10816 <tr><th> URI filenames <th> Results
10817 <tr><td> file:data.db <td>
10818 Open the file "data.db" in the current directory.
10819 <tr><td> file:/home/fred/data.db<br>
10820 file:///home/fred/data.db <br>
10821 file://localhost/home/fred/data.db <br> <td>
10822 Open the database file "/home/fred/data.db".
10823 <tr><td> file://darkstar/home/fred/data.db <td>
10824 An error. "darkstar" is not a recognized authority.
10825 <tr><td style="white-space:nowrap">
10826 file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
10827 <td> Windows only: Open the file "data.db" on fred's desktop on drive
10828 C:. Note that the %20 escaping in this example is not strictly
10829 necessary - space characters can be used literally
10830 in URI filenames.
10831 <tr><td> file:data.db?mode=ro&cache=private <td>
10832 Open file "data.db" in the current directory for read-only access.
10833 Regardless of whether or not shared-cache mode is enabled by
10834 default, use a private cache.
10835 <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
10836 Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
10837 that uses dot-files in place of posix advisory locking.
10838 <tr><td> file:data.db?mode=readonly <td>
10839 An error. "readonly" is not a valid option for the "mode" parameter.
10840 Use "ro" instead: "file:data.db?mode=ro".
10841 </table></p>
10842
10843 <p>URI hexadecimal escape sequences (%HH) are supported within the path and
10844 query components of a URI. A hexadecimal escape sequence consists of a
10845 percent sign - "%" - followed by exactly two hexadecimal digits
10846 specifying an octet value. Before the path or query components of a
10847 URI filename are interpreted, they are encoded using UTF-8 and all
10848 hexadecimal escape sequences replaced by a single byte containing the
10849 corresponding octet. If this process generates an invalid UTF-8 encoding,
10850 the results are undefined.</p>
10851
10852 <p><b>Note to Windows users:</b> The encoding used for the filename argument
10853 of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
10854 codepage is currently defined. Filenames containing international
10855 characters must be converted to UTF-8 prior to passing them into
10856 sqlite3_open() or sqlite3_open_v2().</p>
10857
10858 <p><b>Note to Windows Runtime users:</b> The temporary directory must be set
10859 prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various
10860 features that require the use of temporary files may fail.</p>
10861
10862 <p>See also: <a href="#sqlite3_temp_directory">sqlite3_temp_directory</a>
10863 </p><hr><a name="sqlite3_preupdate_blobwrite"></a>
10864 <h2>The pre-update hook.</h2>
10865 </div>
10866 <blockquote><pre>
10867 #if defined(SQLITE_ENABLE_PREUPDATE_HOOK)
10868 void *sqlite3_preupdate_hook(
10869 sqlite3 *db,
10870 void(*xPreUpdate)(
10871 void *pCtx, /* Copy of third arg to preupdate_hook() */
10872 sqlite3 *db, /* Database handle */
10873 int op, /* SQLITE_UPDATE, DELETE or INSERT */
10874 char const *zDb, /* Database name */
10875 char const *zName, /* Table name */
10876 sqlite3_int64 iKey1, /* Rowid of row about to be deleted/updated */
10877 sqlite3_int64 iKey2 /* New rowid value (for a rowid UPDATE) */
10878 ),
10879 void*
10880 );
10881 int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **);
10882 int sqlite3_preupdate_count(sqlite3 *);
10883 int sqlite3_preupdate_depth(sqlite3 *);
10884 int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);
10885 int sqlite3_preupdate_blobwrite(sqlite3 *);
10886 #endif
10887 </pre></blockquote>
10888 <p>
10889 These interfaces are only available if SQLite is compiled using the
10890 <a href="compile.html#enable_preupdate_hook">SQLITE_ENABLE_PREUPDATE_HOOK</a> compile-time option.</p>
10891
10892 <p>The <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_hook()</a> interface registers a callback function
10893 that is invoked prior to each <a href="lang_insert.html">INSERT</a>, <a href="lang_update.html">UPDATE</a>, and <a href="lang_delete.html">DELETE</a> operation
10894 on a database table.
10895 At most one preupdate hook may be registered at a time on a single
10896 <a href="#sqlite3">database connection</a>; each call to <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_hook()</a> overrides
10897 the previous setting.
10898 The preupdate hook is disabled by invoking <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_hook()</a>
10899 with a NULL pointer as the second parameter.
10900 The third parameter to <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_hook()</a> is passed through as
10901 the first parameter to callbacks.</p>
10902
10903 <p>The preupdate hook only fires for changes to real database tables; the
10904 preupdate hook is not invoked for changes to <a href="vtab.html">virtual tables</a> or to
10905 system tables like sqlite_sequence or sqlite_stat1.</p>
10906
10907 <p>The second parameter to the preupdate callback is a pointer to
10908 the <a href="#sqlite3">database connection</a> that registered the preupdate hook.
10909 The third parameter to the preupdate callback is one of the constants
10910 <a href="#SQLITE_ALTER_TABLE">SQLITE_INSERT</a>, <a href="#SQLITE_ALTER_TABLE">SQLITE_DELETE</a>, or <a href="#SQLITE_ALTER_TABLE">SQLITE_UPDATE</a> to identify the
10911 kind of update operation that is about to occur.
10912 The fourth parameter to the preupdate callback is the name of the
10913 database within the database connection that is being modified. This
10914 will be "main" for the main database or "temp" for TEMP tables or
10915 the name given after the AS keyword in the <a href="lang_attach.html">ATTACH</a> statement for attached
10916 databases.
10917 The fifth parameter to the preupdate callback is the name of the
10918 table that is being modified.</p>
10919
10920 <p>For an UPDATE or DELETE operation on a <a href="rowidtable.html">rowid table</a>, the sixth
10921 parameter passed to the preupdate callback is the initial <a href="lang_createtable.html#rowid">rowid</a> of the
10922 row being modified or deleted. For an INSERT operation on a rowid table,
10923 or any operation on a WITHOUT ROWID table, the value of the sixth
10924 parameter is undefined. For an INSERT or UPDATE on a rowid table the
10925 seventh parameter is the final rowid value of the row being inserted
10926 or updated. The value of the seventh parameter passed to the callback
10927 function is not defined for operations on WITHOUT ROWID tables, or for
10928 DELETE operations on rowid tables.</p>
10929
10930 <p>The sqlite3_preupdate_hook(D,C,P) function returns the P argument from
10931 the previous call on the same <a href="#sqlite3">database connection</a> D, or NULL for
10932 the first call on D.</p>
10933
10934 <p>The <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_old()</a>, <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_new()</a>,
10935 <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_count()</a>, and <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_depth()</a> interfaces
10936 provide additional information about a preupdate event. These routines
10937 may only be called from within a preupdate callback. Invoking any of
10938 these routines from outside of a preupdate callback or with a
10939 <a href="#sqlite3">database connection</a> pointer that is different from the one supplied
10940 to the preupdate callback results in undefined and probably undesirable
10941 behavior.</p>
10942
10943 <p>The <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_count(D)</a> interface returns the number of columns
10944 in the row that is being inserted, updated, or deleted.</p>
10945
10946 <p>The <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_old(D,N,P)</a> interface writes into P a pointer to
10947 a <a href="#sqlite3_value">protected sqlite3_value</a> that contains the value of the Nth column of
10948 the table row before it is updated. The N parameter must be between 0
10949 and one less than the number of columns or the behavior will be
10950 undefined. This must only be used within SQLITE_UPDATE and SQLITE_DELETE
10951 preupdate callbacks; if it is used by an SQLITE_INSERT callback then the
10952 behavior is undefined. The <a href="#sqlite3_value">sqlite3_value</a> that P points to
10953 will be destroyed when the preupdate callback returns.</p>
10954
10955 <p>The <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_new(D,N,P)</a> interface writes into P a pointer to
10956 a <a href="#sqlite3_value">protected sqlite3_value</a> that contains the value of the Nth column of
10957 the table row after it is updated. The N parameter must be between 0
10958 and one less than the number of columns or the behavior will be
10959 undefined. This must only be used within SQLITE_INSERT and SQLITE_UPDATE
10960 preupdate callbacks; if it is used by an SQLITE_DELETE callback then the
10961 behavior is undefined. The <a href="#sqlite3_value">sqlite3_value</a> that P points to
10962 will be destroyed when the preupdate callback returns.</p>
10963
10964 <p>The <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_depth(D)</a> interface returns 0 if the preupdate
10965 callback was invoked as a result of a direct insert, update, or delete
10966 operation; or 1 for inserts, updates, or deletes invoked by top-level
10967 triggers; or 2 for changes resulting from triggers called by top-level
10968 triggers; and so forth.</p>
10969
10970 <p>When the <a href="#sqlite3_blob_write">sqlite3_blob_write()</a> API is used to update a blob column,
10971 the pre-update hook is invoked with SQLITE_DELETE, because
10972 the new values are not yet available. In this case, when a
10973 callback made with op==SQLITE_DELETE is actually a write using the
10974 sqlite3_blob_write() API, the <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_blobwrite()</a> returns
10975 the index of the column being written. In other cases, where the
10976 pre-update hook is being invoked for some other reason, including a
10977 regular DELETE, sqlite3_preupdate_blobwrite() returns -1.</p>
10978
10979 <p>See also: <a href="#sqlite3_update_hook">sqlite3_update_hook()</a>
10980 </p><hr><a name="sqlite3_profile"></a>
10981 <h2>Deprecated Tracing And Profiling Functions</h2>
10982 </div>
10983 <blockquote><pre>
10984 void *sqlite3_trace(sqlite3*,
10985 void(*xTrace)(void*,const char*), void*);
10986 void *sqlite3_profile(sqlite3*,
10987 void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
10988 </pre></blockquote>
10989 <p>
10990 These routines are deprecated. Use the <a href="#sqlite3_trace_v2">sqlite3_trace_v2()</a> interface
10991 instead of the routines described here.</p>
10992
10993 <p>These routines register callback functions that can be used for
10994 tracing and profiling the execution of SQL statements.</p>
10995
10996 <p>The callback function registered by sqlite3_trace() is invoked at
10997 various times when an SQL statement is being run by <a href="#sqlite3_step">sqlite3_step()</a>.
10998 The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
10999 SQL statement text as the statement first begins executing.
11000 Additional sqlite3_trace() callbacks might occur
11001 as each triggered subprogram is entered. The callbacks for triggers
11002 contain a UTF-8 SQL comment that identifies the trigger.</p>
11003
11004 <p>The <a href="compile.html#trace_size_limit">SQLITE_TRACE_SIZE_LIMIT</a> compile-time option can be used to limit
11005 the length of <a href="lang_expr.html#varparam">bound parameter</a> expansion in the output of sqlite3_trace().</p>
11006
11007 <p>The callback function registered by sqlite3_profile() is invoked
11008 as each SQL statement finishes. The profile callback contains
11009 the original statement text and an estimate of wall-clock time
11010 of how long that statement took to run. The profile callback
11011 time is in units of nanoseconds, however the current implementation
11012 is only capable of millisecond resolution so the six least significant
11013 digits in the time are meaningless. Future versions of SQLite
11014 might provide greater resolution on the profiler callback. Invoking
11015 either <a href="#sqlite3_profile">sqlite3_trace()</a> or <a href="#sqlite3_trace_v2">sqlite3_trace_v2()</a> will cancel the
11016 profile callback.
11017 </p><hr><a name="sqlite3_result_blob"></a>
11018 <h2>Setting The Result Of An SQL Function</h2>
11019 </div>
11020 <blockquote><pre>
11021 void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
11022 void sqlite3_result_blob64(sqlite3_context*,const void*,
11023 sqlite3_uint64,void(*)(void*));
11024 void sqlite3_result_double(sqlite3_context*, double);
11025 void sqlite3_result_error(sqlite3_context*, const char*, int);
11026 void sqlite3_result_error16(sqlite3_context*, const void*, int);
11027 void sqlite3_result_error_toobig(sqlite3_context*);
11028 void sqlite3_result_error_nomem(sqlite3_context*);
11029 void sqlite3_result_error_code(sqlite3_context*, int);
11030 void sqlite3_result_int(sqlite3_context*, int);
11031 void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
11032 void sqlite3_result_null(sqlite3_context*);
11033 void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
11034 void sqlite3_result_text64(sqlite3_context*, const char *z, sqlite3_uint64 n,
11035 void(*)(void*), unsigned char encoding);
11036 void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
11037 void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
11038 void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
11039 void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
11040 void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*));
11041 void sqlite3_result_zeroblob(sqlite3_context*, int n);
11042 int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);
11043 </pre></blockquote>
11044 <p>
11045 These routines are used by the xFunc or xFinal callbacks that
11046 implement SQL functions and aggregates. See
11047 <a href="#sqlite3_create_function">sqlite3_create_function()</a> and <a href="#sqlite3_create_function">sqlite3_create_function16()</a>
11048 for additional information.</p>
11049
11050 <p>These functions work very much like the <a href="#sqlite3_bind_blob">parameter binding</a> family of
11051 functions used to bind values to host parameters in prepared statements.
11052 Refer to the <a href="#sqlite3_bind_blob">SQL parameter</a> documentation for additional information.</p>
11053
11054 <p>The sqlite3_result_blob() interface sets the result from
11055 an application-defined function to be the BLOB whose content is pointed
11056 to by the second parameter and which is N bytes long where N is the
11057 third parameter.</p>
11058
11059 <p>The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N)
11060 interfaces set the result of the application-defined function to be
11061 a BLOB containing all zero bytes and N bytes in size.</p>
11062
11063 <p>The sqlite3_result_double() interface sets the result from
11064 an application-defined function to be a floating point value specified
11065 by its 2nd argument.</p>
11066
11067 <p>The sqlite3_result_error() and sqlite3_result_error16() functions
11068 cause the implemented SQL function to throw an exception.
11069 SQLite uses the string pointed to by the
11070 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
11071 as the text of an error message. SQLite interprets the error
11072 message string from sqlite3_result_error() as UTF-8. SQLite
11073 interprets the string from sqlite3_result_error16() as UTF-16 using
11074 the same <a href="#byteorderdeterminationrules">byte-order determination rules</a> as <a href="#sqlite3_bind_blob">sqlite3_bind_text16()</a>.
11075 If the third parameter to sqlite3_result_error()
11076 or sqlite3_result_error16() is negative then SQLite takes as the error
11077 message all text up through the first zero character.
11078 If the third parameter to sqlite3_result_error() or
11079 sqlite3_result_error16() is non-negative then SQLite takes that many
11080 bytes (not characters) from the 2nd parameter as the error message.
11081 The sqlite3_result_error() and sqlite3_result_error16()
11082 routines make a private copy of the error message text before
11083 they return. Hence, the calling function can deallocate or
11084 modify the text after they return without harm.
11085 The sqlite3_result_error_code() function changes the error code
11086 returned by SQLite as a result of an error in a function. By default,
11087 the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error()
11088 or sqlite3_result_error16() resets the error code to SQLITE_ERROR.</p>
11089
11090 <p>The sqlite3_result_error_toobig() interface causes SQLite to throw an
11091 error indicating that a string or BLOB is too long to represent.</p>
11092
11093 <p>The sqlite3_result_error_nomem() interface causes SQLite to throw an
11094 error indicating that a memory allocation failed.</p>
11095
11096 <p>The sqlite3_result_int() interface sets the return value
11097 of the application-defined function to be the 32-bit signed integer
11098 value given in the 2nd argument.
11099 The sqlite3_result_int64() interface sets the return value
11100 of the application-defined function to be the 64-bit signed integer
11101 value given in the 2nd argument.</p>
11102
11103 <p>The sqlite3_result_null() interface sets the return value
11104 of the application-defined function to be NULL.</p>
11105
11106 <p>The sqlite3_result_text(), sqlite3_result_text16(),
11107 sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
11108 set the return value of the application-defined function to be
11109 a text string which is represented as UTF-8, UTF-16 native byte order,
11110 UTF-16 little endian, or UTF-16 big endian, respectively.
11111 The sqlite3_result_text64(C,Z,N,D,E) interface sets the return value of an
11112 application-defined function to be a text string in an encoding
11113 specified the E parameter, which must be one
11114 of <a href="#sqliteutf8">SQLITE_UTF8</a>, <a href="#sqliteutf8zt">SQLITE_UTF8_ZT</a>, <a href="#sqliteutf16">SQLITE_UTF16</a>, <a href="#sqliteutf16be">SQLITE_UTF16BE</a>,
11115 or <a href="#sqliteutf16le">SQLITE_UTF16LE</a>. The special value <a href="#sqliteutf8zt">SQLITE_UTF8_ZT</a> means that
11116 the result text is both UTF-8 and zero-terminated. In other words,
11117 SQLITE_UTF8_ZT means that the Z array holds at least N+1 bytes and that
11118 the Z&#91;N&#93; is zero.
11119 SQLite takes the text result from the application from
11120 the 2nd parameter of the sqlite3_result_text* interfaces.
11121 If the 3rd parameter to any of the sqlite3_result_text* interfaces
11122 other than sqlite3_result_text64() is negative, then SQLite computes
11123 the string length itself by searching the 2nd parameter for the first
11124 zero character.
11125 If the 3rd parameter to the sqlite3_result_text* interfaces
11126 is non-negative, then as many bytes (not characters) of the text
11127 pointed to by the 2nd parameter are taken as the application-defined
11128 function result. If the 3rd parameter is non-negative, then it
11129 must be the byte offset into the string where the NUL terminator would
11130 appear if the string were NUL terminated. If any NUL characters occur
11131 in the string at a byte offset that is less than the value of the 3rd
11132 parameter, then the resulting string will contain embedded NULs and the
11133 result of expressions operating on strings with embedded NULs is undefined.
11134 If the 4th parameter to the sqlite3_result_text* interfaces
11135 or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
11136 function as the destructor on the text or BLOB result when it has
11137 finished using that result.
11138 If the 4th parameter to the sqlite3_result_text* interfaces or to
11139 sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
11140 assumes that the text or BLOB result is in constant space and does not
11141 copy the content of the parameter nor call a destructor on the content
11142 when it has finished using that result.
11143 If the 4th parameter to the sqlite3_result_text* interfaces
11144 or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
11145 then SQLite makes a copy of the result into space obtained
11146 from <a href="#sqlite3_free">sqlite3_malloc()</a> before it returns.</p>
11147
11148 <p>For the sqlite3_result_text16(), sqlite3_result_text16le(), and
11149 sqlite3_result_text16be() routines, and for sqlite3_result_text64()
11150 when the encoding is not UTF8, if the input UTF16 begins with a
11151 byte-order mark (BOM, U+FEFF) then the BOM is removed from the
11152 string and the rest of the string is interpreted according to the
11153 byte-order specified by the BOM. The byte-order specified by
11154 the BOM at the beginning of the text overrides the byte-order
11155 specified by the interface procedure. So, for example, if
11156 sqlite3_result_text16le() is invoked with text that begins
11157 with bytes 0xfe, 0xff (a big-endian byte-order mark) then the
11158 first two bytes of input are skipped and the remaining input
11159 is interpreted as UTF16BE text.</p>
11160
11161 <p>For UTF16 input text to the sqlite3_result_text16(),
11162 sqlite3_result_text16be(), sqlite3_result_text16le(), and
11163 sqlite3_result_text64() routines, if the text contains invalid
11164 UTF16 characters, the invalid characters might be converted
11165 into the unicode replacement character, U+FFFD.</p>
11166
11167 <p>The sqlite3_result_value() interface sets the result of
11168 the application-defined function to be a copy of the
11169 <a href="#sqlite3_value">unprotected sqlite3_value</a> object specified by the 2nd parameter. The
11170 sqlite3_result_value() interface makes a copy of the <a href="#sqlite3_value">sqlite3_value</a>
11171 so that the <a href="#sqlite3_value">sqlite3_value</a> specified in the parameter may change or
11172 be deallocated after sqlite3_result_value() returns without harm.
11173 A <a href="#sqlite3_value">protected sqlite3_value</a> object may always be used where an
11174 <a href="#sqlite3_value">unprotected sqlite3_value</a> object is required, so either
11175 kind of <a href="#sqlite3_value">sqlite3_value</a> object can be used with this interface.</p>
11176
11177 <p>The sqlite3_result_pointer(C,P,T,D) interface sets the result to an
11178 SQL NULL value, just like <a href="#sqlite3_result_blob">sqlite3_result_null(C)</a>, except that it
11179 also associates the host-language pointer P or type T with that
11180 NULL value such that the pointer can be retrieved within an
11181 <a href="appfunc.html">application-defined SQL function</a> using <a href="#sqlite3_value_blob">sqlite3_value_pointer()</a>.
11182 If the D parameter is not NULL, then it is a pointer to a destructor
11183 for the P parameter. SQLite invokes D with P as its only argument
11184 when SQLite is finished with P. The T parameter should be a static
11185 string and preferably a string literal. The sqlite3_result_pointer()
11186 routine is part of the <a href="bindptr.html">pointer passing interface</a> added for SQLite 3.20.0.</p>
11187
11188 <p>If these routines are called from within a different thread
11189 than the one containing the application-defined function that received
11190 the <a href="#sqlite3_context">sqlite3_context</a> pointer, the results are undefined.
11191 </p><hr><a name="sqlite3_status"></a>
11192 <h2>SQLite Runtime Status</h2>
11193 </div>
11194 <blockquote><pre>
11195 int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
11196 int sqlite3_status64(
11197 int op,
11198 sqlite3_int64 *pCurrent,
11199 sqlite3_int64 *pHighwater,
11200 int resetFlag
11201 );
11202 </pre></blockquote>
11203 <p>
11204 These interfaces are used to retrieve runtime status information
11205 about the performance of SQLite, and optionally to reset various
11206 highwater marks. The first argument is an integer code for
11207 the specific parameter to measure. Recognized integer codes
11208 are of the form <a href="#SQLITE_STATUS_MALLOC_COUNT">SQLITE_STATUS_...</a>.
11209 The current value of the parameter is returned into *pCurrent.
11210 The highest recorded value is returned in *pHighwater. If the
11211 resetFlag is true, then the highest record value is reset after
11212 *pHighwater is written. Some parameters do not record the highest
11213 value. For those parameters
11214 nothing is written into *pHighwater and the resetFlag is ignored.
11215 Other parameters record only the highwater mark and not the current
11216 value. For these latter parameters nothing is written into *pCurrent.</p>
11217
11218 <p>The sqlite3_status() and sqlite3_status64() routines return
11219 SQLITE_OK on success and a non-zero <a href="rescode.html">error code</a> on failure.</p>
11220
11221 <p>If either the current value or the highwater mark is too large to
11222 be represented by a 32-bit integer, then the values returned by
11223 sqlite3_status() are undefined.</p>
11224
11225 <p>See also: <a href="#sqlite3_db_status">sqlite3_db_status()</a>
11226 </p><hr><a name="sqlite3_stmt_scanstatus"></a>
11227 <h2>Prepared Statement Scan Status</h2>
11228 </div>
11229 <blockquote><pre>
11230 int sqlite3_stmt_scanstatus(
11231 sqlite3_stmt *pStmt, /* Prepared statement for which info desired */
11232 int idx, /* Index of loop to report on */
11233 int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */
11234 void *pOut /* Result written here */
11235 );
11236 int sqlite3_stmt_scanstatus_v2(
11237 sqlite3_stmt *pStmt, /* Prepared statement for which info desired */
11238 int idx, /* Index of loop to report on */
11239 int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */
11240 int flags, /* Mask of flags defined below */
11241 void *pOut /* Result written here */
11242 );
11243 </pre></blockquote>
11244 <p>
11245 These interfaces return information about the predicted and measured
11246 performance for pStmt. Advanced applications can use this
11247 interface to compare the predicted and the measured performance and
11248 issue warnings and/or rerun <a href="lang_analyze.html">ANALYZE</a> if discrepancies are found.</p>
11249
11250 <p>Since this interface is expected to be rarely used, it is only
11251 available if SQLite is compiled using the <a href="compile.html#enable_stmt_scanstatus">SQLITE_ENABLE_STMT_SCANSTATUS</a>
11252 compile-time option.</p>
11253
11254 <p>The "iScanStatusOp" parameter determines which status information to return.
11255 The "iScanStatusOp" must be one of the <a href="#SQLITE_SCANSTAT_EST">scanstatus options</a> or the behavior
11256 of this interface is undefined. The requested measurement is written into
11257 a variable pointed to by the "pOut" parameter.</p>
11258
11259 <p>The "flags" parameter must be passed a mask of flags. At present only
11260 one flag is defined - <a href="#SQLITE_SCANSTAT_COMPLEX">SQLITE_SCANSTAT_COMPLEX</a>. If SQLITE_SCANSTAT_COMPLEX
11261 is specified, then status information is available for all elements
11262 of a query plan that are reported by "<a href="eqp.html">EXPLAIN QUERY PLAN</a>" output. If
11263 SQLITE_SCANSTAT_COMPLEX is not specified, then only query plan elements
11264 that correspond to query loops (the "SCAN..." and "SEARCH..." elements of
11265 the EXPLAIN QUERY PLAN output) are available. Invoking API
11266 sqlite3_stmt_scanstatus() is equivalent to calling
11267 sqlite3_stmt_scanstatus_v2() with a zeroed flags parameter.</p>
11268
11269 <p>Parameter "idx" identifies the specific query element to retrieve statistics
11270 for. Query elements are numbered starting from zero. A value of -1 may
11271 retrieve statistics for the entire query. If idx is out of range
11272 - less than -1 or greater than or equal to the total number of query
11273 elements used to implement the statement - a non-zero value is returned and
11274 the variable that pOut points to is unchanged.</p>
11275
11276 <p>See also: <a href="#sqlite3_stmt_scanstatus_reset">sqlite3_stmt_scanstatus_reset()</a> and the
11277 <a href="bytecodevtab.html#nexec">nexec and ncycle</a> columns of the <a href="bytecodevtab.html">bytecode virtual table</a>.
11278 </p><hr><a name="sqlite3_str_append"></a>
11279 <h2>Add Content To A Dynamic String</h2>
11280 </div>
11281 <blockquote><pre>
11282 void sqlite3_str_appendf(sqlite3_str*, const char *zFormat, ...);
11283 void sqlite3_str_vappendf(sqlite3_str*, const char *zFormat, va_list);
11284 void sqlite3_str_append(sqlite3_str*, const char *zIn, int N);
11285 void sqlite3_str_appendall(sqlite3_str*, const char *zIn);
11286 void sqlite3_str_appendchar(sqlite3_str*, int N, char C);
11287 void sqlite3_str_reset(sqlite3_str*);
11288 void sqlite3_str_truncate(sqlite3_str*,int N);
11289 </pre></blockquote>
11290 <p>
11291 These interfaces add or remove content to an sqlite3_str object
11292 previously obtained from <a href="#sqlite3_str_new">sqlite3_str_new()</a>.</p>
11293
11294 <p>The <a href="#sqlite3_str_append">sqlite3_str_appendf(X,F,...)</a> and
11295 <a href="#sqlite3_str_append">sqlite3_str_vappendf(X,F,V)</a> interfaces uses the <a href="printf.html">built-in printf</a>
11296 functionality of SQLite to append formatted text onto the end of
11297 <a href="#sqlite3_str">sqlite3_str</a> object X.</p>
11298
11299 <p>The <a href="#sqlite3_str_append">sqlite3_str_append(X,S,N)</a> method appends exactly N bytes from string S
11300 onto the end of the <a href="#sqlite3_str">sqlite3_str</a> object X. N must be non-negative.
11301 S must contain at least N non-zero bytes of content. To append a
11302 zero-terminated string in its entirety, use the <a href="#sqlite3_str_append">sqlite3_str_appendall()</a>
11303 method instead.</p>
11304
11305 <p>The <a href="#sqlite3_str_append">sqlite3_str_appendall(X,S)</a> method appends the complete content of
11306 zero-terminated string S onto the end of <a href="#sqlite3_str">sqlite3_str</a> object X.</p>
11307
11308 <p>The <a href="#sqlite3_str_append">sqlite3_str_appendchar(X,N,C)</a> method appends N copies of the
11309 single-byte character C onto the end of <a href="#sqlite3_str">sqlite3_str</a> object X.
11310 This method can be used, for example, to add whitespace indentation.</p>
11311
11312 <p>The <a href="#sqlite3_str_append">sqlite3_str_reset(X)</a> method resets the string under construction
11313 inside <a href="#sqlite3_str">sqlite3_str</a> object X back to zero bytes in length.</p>
11314
11315 <p>The <a href="#sqlite3_str_append">sqlite3_str_truncate(X,N)</a> method changes the length of the string
11316 under construction to be N bytes or less. This routine is a no-op if
11317 N is negative or if the string is already N bytes or smaller in size.</p>
11318
11319 <p>These methods do not return a result code. If an error occurs, that fact
11320 is recorded in the <a href="#sqlite3_str">sqlite3_str</a> object and can be recovered by a
11321 subsequent call to <a href="#sqlite3_str_errcode">sqlite3_str_errcode(X)</a>.
11322 </p><hr><a name="sqlite3_str_errcode"></a>
11323 <h2>Status Of A Dynamic String</h2>
11324 </div>
11325 <blockquote><pre>
11326 int sqlite3_str_errcode(sqlite3_str*);
11327 int sqlite3_str_length(sqlite3_str*);
11328 char *sqlite3_str_value(sqlite3_str*);
11329 </pre></blockquote>
11330 <p>
11331 These interfaces return the current status of an <a href="#sqlite3_str">sqlite3_str</a> object.</p>
11332
11333 <p>If any prior errors have occurred while constructing the dynamic string
11334 in sqlite3_str X, then the <a href="#sqlite3_str_errcode">sqlite3_str_errcode(X)</a> method will return
11335 an appropriate error code. The <a href="#sqlite3_str_errcode">sqlite3_str_errcode(X)</a> method returns
11336 <a href="#SQLITE_ABORT">SQLITE_NOMEM</a> following any out-of-memory error, or
11337 <a href="#SQLITE_ABORT">SQLITE_TOOBIG</a> if the size of the dynamic string exceeds
11338 <a href="limits.html#max_length">SQLITE_MAX_LENGTH</a>, or <a href="#SQLITE_ABORT">SQLITE_OK</a> if there have been no errors.</p>
11339
11340 <p>The <a href="#sqlite3_str_errcode">sqlite3_str_length(X)</a> method returns the current length, in bytes,
11341 of the dynamic string under construction in <a href="#sqlite3_str">sqlite3_str</a> object X.
11342 The length returned by <a href="#sqlite3_str_errcode">sqlite3_str_length(X)</a> does not include the
11343 zero-termination byte.</p>
11344
11345 <p>The <a href="#sqlite3_str_errcode">sqlite3_str_value(X)</a> method returns a pointer to the current
11346 content of the dynamic string under construction in X. The value
11347 returned by <a href="#sqlite3_str_errcode">sqlite3_str_value(X)</a> is managed by the sqlite3_str object X
11348 and might be freed or altered by any subsequent method on the same
11349 <a href="#sqlite3_str">sqlite3_str</a> object. Applications must not use the pointer returned by
11350 <a href="#sqlite3_str_errcode">sqlite3_str_value(X)</a> after any subsequent method call on the same
11351 object. Applications may change the content of the string returned
11352 by <a href="#sqlite3_str_errcode">sqlite3_str_value(X)</a> as long as they do not write into any bytes
11353 outside the range of 0 to <a href="#sqlite3_str_errcode">sqlite3_str_length(X)</a> and do not read or
11354 write any byte after any subsequent sqlite3_str method call.
11355 </p><hr><a name="sqlite3_str_finish"></a>
11356 <h2>Finalize A Dynamic String</h2>
11357 </div>
11358 <blockquote><pre>
11359 char *sqlite3_str_finish(sqlite3_str*);
11360 void sqlite3_str_free(sqlite3_str*);
11361 </pre></blockquote>
11362 <p>
11363 The <a href="#sqlite3_str_finish">sqlite3_str_finish(X)</a> interface destroys the sqlite3_str object X
11364 and returns a pointer to a memory buffer obtained from <a href="#sqlite3_free">sqlite3_malloc64()</a>
11365 that contains the constructed string. The calling application should
11366 pass the returned value to <a href="#sqlite3_free">sqlite3_free()</a> to avoid a memory leak.
11367 The <a href="#sqlite3_str_finish">sqlite3_str_finish(X)</a> interface may return a NULL pointer if any
11368 errors were encountered during construction of the string. The
11369 <a href="#sqlite3_str_finish">sqlite3_str_finish(X)</a> interface might also return a NULL pointer if the
11370 string in <a href="#sqlite3_str">sqlite3_str</a> object X is zero bytes long.</p>
11371
11372 <p>The <a href="#sqlite3_str_finish">sqlite3_str_free(X)</a> interface destroys both the sqlite3_str object
11373 X and the string content it contains. Calling sqlite3_str_free(X) is
11374 the equivalent of calling <a href="#sqlite3_free">sqlite3_free</a>(sqlite3_str_finish(X)).
11375 </p><hr><a name="sqlite3_stricmp"></a>
11376 <h2>String Comparison</h2>
11377 </div>
11378 <blockquote><pre>
11379 int sqlite3_stricmp(const char *, const char *);
11380 int sqlite3_strnicmp(const char *, const char *, int);
11381 </pre></blockquote>
11382 <p>
11383 The <a href="#sqlite3_stricmp">sqlite3_stricmp()</a> and <a href="#sqlite3_stricmp">sqlite3_strnicmp()</a> APIs allow applications
11384 and extensions to compare the contents of two buffers containing UTF-8
11385 strings in a case-independent fashion, using the same definition of "case
11386 independence" that SQLite uses internally when comparing identifiers.
11387 </p><hr><a name="sqlite3_total_changes"></a>
11388 <h2>Total Number Of Rows Modified</h2>
11389 </div>
11390 <blockquote><pre>
11391 int sqlite3_total_changes(sqlite3*);
11392 sqlite3_int64 sqlite3_total_changes64(sqlite3*);
11393 </pre></blockquote>
11394 <p>
11395 These functions return the total number of rows inserted, modified or
11396 deleted by all <a href="lang_insert.html">INSERT</a>, <a href="lang_update.html">UPDATE</a> or <a href="lang_delete.html">DELETE</a> statements completed
11397 since the database connection was opened, including those executed as
11398 part of trigger programs. The two functions are identical except for the
11399 type of the return value and that if the number of rows modified by the
11400 connection exceeds the maximum value supported by type "int", then
11401 the return value of sqlite3_total_changes() is undefined. Executing
11402 any other type of SQL statement does not affect the value returned by
11403 sqlite3_total_changes().</p>
11404
11405 <p>Changes made as part of <a href="foreignkeys.html#fk_actions">foreign key actions</a> are included in the
11406 count, but those made as part of REPLACE constraint resolution are
11407 not. Changes to a view that are intercepted by INSTEAD OF triggers
11408 are not counted.</p>
11409
11410 <p>The <a href="#sqlite3_total_changes">sqlite3_total_changes(D)</a> interface only reports the number
11411 of rows that changed due to SQL statement run against database
11412 connection D. Any changes by other database connections are ignored.
11413 To detect changes against a database file from other database
11414 connections use the <a href="pragma.html#pragma_data_version">PRAGMA data_version</a> command or the
11415 <a href="#sqlitefcntldataversion">SQLITE_FCNTL_DATA_VERSION</a> <a href="#sqlite3_file_control">file control</a>.</p>
11416
11417 <p>If a separate thread makes changes on the same database connection
11418 while <a href="#sqlite3_total_changes">sqlite3_total_changes()</a> is running then the value
11419 returned is unpredictable and not meaningful.</p>
11420
11421 <p>See also:
11422 <ul>
11423 <li> the <a href="#sqlite3_changes">sqlite3_changes()</a> interface
11424 <li> the <a href="pragma.html#pragma_count_changes">count_changes pragma</a>
11425 <li> the <a href="lang_corefunc.html#changes">changes() SQL function</a>
11426 <li> the <a href="pragma.html#pragma_data_version">data_version pragma</a>
11427 <li> the <a href="#sqlitefcntldataversion">SQLITE_FCNTL_DATA_VERSION</a> <a href="#sqlite3_file_control">file control</a>
11428 </ul>
11429 </p><hr><a name="sqlite3_uri_boolean"></a>
11430 <h2>Obtain Values For URI Parameters</h2>
11431 </div>
11432 <blockquote><pre>
11433 const char *sqlite3_uri_parameter(sqlite3_filename z, const char *zParam);
11434 int sqlite3_uri_boolean(sqlite3_filename z, const char *zParam, int bDefault);
11435 sqlite3_int64 sqlite3_uri_int64(sqlite3_filename, const char*, sqlite3_int64);
11436 const char *sqlite3_uri_key(sqlite3_filename z, int N);
11437 </pre></blockquote>
11438 <p>
11439 These are utility routines, useful to <a href="vfs.html">custom VFS implementations</a>,
11440 that check if a database file was a URI that contained a specific query
11441 parameter, and if so obtains the value of that query parameter.</p>
11442
11443 <p>The first parameter to these interfaces (hereafter referred to
11444 as F) must be one of:
11445 <ul>
11446 <li> A database filename pointer created by the SQLite core and
11447 passed into the xOpen() method of a VFS implementation, or
11448 <li> A filename obtained from <a href="#sqlite3_db_filename">sqlite3_db_filename()</a>, or
11449 <li> A new filename constructed using <a href="#sqlite3_create_filename">sqlite3_create_filename()</a>.
11450 </ul>
11451 If the F parameter is not one of the above, then the behavior is
11452 undefined and probably undesirable. Older versions of SQLite were
11453 more tolerant of invalid F parameters than newer versions.</p>
11454
11455 <p>If F is a suitable filename (as described in the previous paragraph)
11456 and if P is the name of the query parameter, then
11457 sqlite3_uri_parameter(F,P) returns the value of the P
11458 parameter if it exists or a NULL pointer if P does not appear as a
11459 query parameter on F. If P is a query parameter of F and it
11460 has no explicit value, then sqlite3_uri_parameter(F,P) returns
11461 a pointer to an empty string.</p>
11462
11463 <p>The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
11464 parameter and returns true (1) or false (0) according to the value
11465 of P. The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the
11466 value of query parameter P is one of "yes", "true", or "on" in any
11467 case or if the value begins with a non-zero number. The
11468 sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of
11469 query parameter P is one of "no", "false", or "off" in any case or
11470 if the value begins with a numeric zero. If P is not a query
11471 parameter on F or if the value of P does not match any of the
11472 above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).</p>
11473
11474 <p>The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
11475 64-bit signed integer and returns that integer, or D if P does not
11476 exist. If the value of P is something other than an integer, then
11477 zero is returned.</p>
11478
11479 <p>The sqlite3_uri_key(F,N) returns a pointer to the name (not
11480 the value) of the N-th query parameter for filename F, or a NULL
11481 pointer if N is less than zero or greater than the number of query
11482 parameters minus 1. The N value is zero-based so N should be 0 to obtain
11483 the name of the first query parameter, 1 for the second parameter, and
11484 so forth.</p>
11485
11486 <p>If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
11487 sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and
11488 is not a database file pathname pointer that the SQLite core passed
11489 into the xOpen VFS method, then the behavior of this routine is undefined
11490 and probably undesirable.</p>
11491
11492 <p>Beginning with SQLite <a href="releaselog/3_31_0.html">version 3.31.0</a> (2020-01-22) the input F
11493 parameter can also be the name of a rollback journal file or WAL file
11494 in addition to the main database file. Prior to version 3.31.0, these
11495 routines would only work if F was the name of the main database file.
11496 When the F parameter is the name of the rollback journal or WAL file,
11497 it has access to all the same query parameters as were found on the
11498 main database file.</p>
11499
11500 <p>See the <a href="uri.html">URI filename</a> documentation for additional information.
11501 </p><hr><a name="sqlite3_value_blob"></a>
11502 <h2>Obtaining SQL Values</h2>
11503 </div>
11504 <blockquote><pre>
11505 const void *sqlite3_value_blob(sqlite3_value*);
11506 double sqlite3_value_double(sqlite3_value*);
11507 int sqlite3_value_int(sqlite3_value*);
11508 sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
11509 void *sqlite3_value_pointer(sqlite3_value*, const char*);
11510 const unsigned char *sqlite3_value_text(sqlite3_value*);
11511 const void *sqlite3_value_text16(sqlite3_value*);
11512 const void *sqlite3_value_text16le(sqlite3_value*);
11513 const void *sqlite3_value_text16be(sqlite3_value*);
11514 int sqlite3_value_bytes(sqlite3_value*);
11515 int sqlite3_value_bytes16(sqlite3_value*);
11516 int sqlite3_value_type(sqlite3_value*);
11517 int sqlite3_value_numeric_type(sqlite3_value*);
11518 int sqlite3_value_nochange(sqlite3_value*);
11519 int sqlite3_value_frombind(sqlite3_value*);
11520 </pre></blockquote>
11521 <p>
11522 <b>Summary:</b>
11523 <blockquote><table border=0 cellpadding=0 cellspacing=0>
11524 <tr><td><b>sqlite3_value_blob</b><td>&rarr;<td>BLOB value
11525 <tr><td><b>sqlite3_value_double</b><td>&rarr;<td>REAL value
11526 <tr><td><b>sqlite3_value_int</b><td>&rarr;<td>32-bit INTEGER value
11527 <tr><td><b>sqlite3_value_int64</b><td>&rarr;<td>64-bit INTEGER value
11528 <tr><td><b>sqlite3_value_pointer</b><td>&rarr;<td>Pointer value
11529 <tr><td><b>sqlite3_value_text</b><td>&rarr;<td>UTF-8 TEXT value
11530 <tr><td><b>sqlite3_value_text16</b><td>&rarr;<td>UTF-16 TEXT value in
11531 the native byteorder
11532 <tr><td><b>sqlite3_value_text16be</b><td>&rarr;<td>UTF-16be TEXT value
11533 <tr><td><b>sqlite3_value_text16le</b><td>&rarr;<td>UTF-16le TEXT value
11534 <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
11535 <tr><td><b>sqlite3_value_bytes</b><td>&rarr;<td>Size of a BLOB
11536 or a UTF-8 TEXT in bytes
11537 <tr><td><b>sqlite3_value_bytes16&nbsp;&nbsp;</b>
11538 <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
11539 TEXT in bytes
11540 <tr><td><b>sqlite3_value_type</b><td>&rarr;<td>Default
11541 datatype of the value
11542 <tr><td><b>sqlite3_value_numeric_type&nbsp;&nbsp;</b>
11543 <td>&rarr;&nbsp;&nbsp;<td>Best numeric datatype of the value
11544 <tr><td><b>sqlite3_value_nochange&nbsp;&nbsp;</b>
11545 <td>&rarr;&nbsp;&nbsp;<td>True if the column is unchanged in an UPDATE
11546 against a virtual table.
11547 <tr><td><b>sqlite3_value_frombind&nbsp;&nbsp;</b>
11548 <td>&rarr;&nbsp;&nbsp;<td>True if value originated from a <a href="lang_expr.html#varparam">bound parameter</a>
11549 </table></blockquote></p>
11550
11551 <p><b>Details:</b></p>
11552
11553 <p>These routines extract type, size, and content information from
11554 <a href="#sqlite3_value">protected sqlite3_value</a> objects. Protected sqlite3_value objects
11555 are used to pass parameter information into the functions that
11556 implement <a href="appfunc.html">application-defined SQL functions</a> and <a href="vtab.html">virtual tables</a>.</p>
11557
11558 <p>These routines work only with <a href="#sqlite3_value">protected sqlite3_value</a> objects.
11559 Any attempt to use these routines on an <a href="#sqlite3_value">unprotected sqlite3_value</a>
11560 is not threadsafe.</p>
11561
11562 <p>These routines work just like the corresponding <a href="#sqlite3_column_blob">column access functions</a>
11563 except that these routines take a single <a href="#sqlite3_value">protected sqlite3_value</a> object
11564 pointer instead of a <a href="#sqlite3_stmt">sqlite3_stmt*</a> pointer and an integer column number.</p>
11565
11566 <p>The sqlite3_value_text16() interface extracts a UTF-16 string
11567 in the native byte-order of the host machine. The
11568 sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
11569 extract UTF-16 strings as big-endian and little-endian respectively.</p>
11570
11571 <p>If <a href="#sqlite3_value">sqlite3_value</a> object V was initialized
11572 using <a href="#sqlite3_bind_blob">sqlite3_bind_pointer(S,I,P,X,D)</a> or <a href="#sqlite3_result_blob">sqlite3_result_pointer(C,P,X,D)</a>
11573 and if X and Y are strings that compare equal according to strcmp(X,Y),
11574 then sqlite3_value_pointer(V,Y) will return the pointer P. Otherwise,
11575 sqlite3_value_pointer(V,Y) returns a NULL. The sqlite3_bind_pointer()
11576 routine is part of the <a href="bindptr.html">pointer passing interface</a> added for SQLite 3.20.0.</p>
11577
11578 <p>The sqlite3_value_type(V) interface returns the
11579 <a href="#SQLITE_BLOB">datatype code</a> for the initial datatype of the
11580 <a href="#sqlite3_value">sqlite3_value</a> object V. The returned value is one of <a href="#SQLITE_BLOB">SQLITE_INTEGER</a>,
11581 <a href="#SQLITE_BLOB">SQLITE_FLOAT</a>, <a href="#SQLITE_BLOB">SQLITE_TEXT</a>, <a href="#SQLITE_BLOB">SQLITE_BLOB</a>, or <a href="#SQLITE_BLOB">SQLITE_NULL</a>.
11582 Other interfaces might change the datatype for an sqlite3_value object.
11583 For example, if the datatype is initially SQLITE_INTEGER and
11584 sqlite3_value_text(V) is called to extract a text value for that
11585 integer, then subsequent calls to sqlite3_value_type(V) might return
11586 SQLITE_TEXT. Whether or not a persistent internal datatype conversion
11587 occurs is undefined and may change from one release of SQLite to the next.</p>
11588
11589 <p>The sqlite3_value_numeric_type() interface attempts to apply
11590 numeric affinity to the value. This means that an attempt is
11591 made to convert the value to an integer or floating point. If
11592 such a conversion is possible without loss of information (in other
11593 words, if the value is a string that looks like a number)
11594 then the conversion is performed. Otherwise no conversion occurs.
11595 The <a href="#SQLITE_BLOB">datatype</a> after conversion is returned.</p>
11596
11597 <p>Within the <a href="vtab.html#xupdate">xUpdate</a> method of a <a href="vtab.html">virtual table</a>, the
11598 sqlite3_value_nochange(X) interface returns true if and only if
11599 the column corresponding to X is unchanged by the UPDATE operation
11600 that the xUpdate method call was invoked to implement and if
11601 the prior <a href="vtab.html#xcolumn">xColumn</a> method call that was invoked to extract
11602 the value for that column returned without setting a result (probably
11603 because it queried <a href="#sqlite3_vtab_nochange">sqlite3_vtab_nochange()</a> and found that the column
11604 was unchanging). Within an <a href="vtab.html#xupdate">xUpdate</a> method, any value for which
11605 sqlite3_value_nochange(X) is true will in all other respects appear
11606 to be a NULL value. If sqlite3_value_nochange(X) is invoked anywhere other
11607 than within an <a href="vtab.html#xupdate">xUpdate</a> method call for an UPDATE statement, then
11608 the return value is arbitrary and meaningless.</p>
11609
11610 <p>The sqlite3_value_frombind(X) interface returns non-zero if the
11611 value X originated from one of the <a href="#sqlite3_bind_blob">sqlite3_bind()</a>
11612 interfaces. If X comes from an SQL literal value, or a table column,
11613 or an expression, then sqlite3_value_frombind(X) returns zero.</p>
11614
11615 <p>Please pay particular attention to the fact that the pointer returned
11616 from <a href="#sqlite3_value_blob">sqlite3_value_blob()</a>, <a href="#sqlite3_value_blob">sqlite3_value_text()</a>, or
11617 <a href="#sqlite3_value_blob">sqlite3_value_text16()</a> can be invalidated by a subsequent call to
11618 <a href="#sqlite3_value_blob">sqlite3_value_bytes()</a>, <a href="#sqlite3_value_blob">sqlite3_value_bytes16()</a>, <a href="#sqlite3_value_blob">sqlite3_value_text()</a>,
11619 or <a href="#sqlite3_value_blob">sqlite3_value_text16()</a>.</p>
11620
11621 <p>These routines must be called from the same thread as
11622 the SQL function that supplied the <a href="#sqlite3_value">sqlite3_value*</a> parameters.</p>
11623
11624 <p>As long as the input parameter is correct, these routines can only
11625 fail if an out-of-memory error occurs while trying to do a
11626 UTF8&rarr;UTF16 or UTF16&rarr;UTF8 conversion.
11627 If an out-of-memory error occurs, then the return value from these
11628 routines is the same as if the column had contained an SQL NULL value.
11629 If the input sqlite3_value was not obtained from <a href="#sqlite3_value_dup">sqlite3_value_dup()</a>,
11630 then valid SQL NULL returns can also be distinguished from
11631 out-of-memory errors after extracting the value
11632 by invoking the <a href="#sqlite3_errcode">sqlite3_errcode()</a> immediately after the suspicious
11633 return value is obtained and before any
11634 other SQLite interface is called on the same <a href="#sqlite3">database connection</a>.
11635 If the input sqlite3_value was obtained from sqlite3_value_dup() then
11636 it is disconnected from the database connection and so sqlite3_errcode()
11637 will not work.
11638 In that case, the only way to distinguish an out-of-memory
11639 condition from a true SQL NULL is to invoke sqlite3_value_type() on the
11640 input to see if it is NULL prior to trying to extract the value.
11641 </p><hr><a name="sqlite3_value_dup"></a>
11642 <h2>Copy And Free SQL Values</h2>
11643 </div>
11644 <blockquote><pre>
11645 sqlite3_value *sqlite3_value_dup(const sqlite3_value*);
11646 void sqlite3_value_free(sqlite3_value*);
11647 </pre></blockquote>
11648 <p>
11649 The sqlite3_value_dup(V) interface makes a copy of the <a href="#sqlite3_value">sqlite3_value</a>
11650 object V and returns a pointer to that copy. The <a href="#sqlite3_value">sqlite3_value</a> returned
11651 is a <a href="#sqlite3_value">protected sqlite3_value</a> object even if the input is not.
11652 The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a
11653 memory allocation fails. If V is a <a href="bindptr.html">pointer value</a>, then the result
11654 of sqlite3_value_dup(V) is a NULL value.</p>
11655
11656 <p>The sqlite3_value_free(V) interface frees an <a href="#sqlite3_value">sqlite3_value</a> object
11657 previously obtained from <a href="#sqlite3_value_dup">sqlite3_value_dup()</a>. If V is a NULL pointer
11658 then sqlite3_value_free(V) is a harmless no-op.
11659 </p><hr><a name="sqlite3_vfs_find"></a>
11660 <h2>Virtual File System Objects</h2>
11661 </div>
11662 <blockquote><pre>
11663 sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
11664 int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
11665 int sqlite3_vfs_unregister(sqlite3_vfs*);
11666 </pre></blockquote>
11667 <p>
11668 A virtual filesystem (VFS) is an <a href="#sqlite3_vfs">sqlite3_vfs</a> object
11669 that SQLite uses to interact
11670 with the underlying operating system. Most SQLite builds come with a
11671 single default VFS that is appropriate for the host computer.
11672 New VFSes can be registered and existing VFSes can be unregistered.
11673 The following interfaces are provided.</p>
11674
11675 <p>The sqlite3_vfs_find() interface returns a pointer to a VFS given its name.
11676 Names are case sensitive.
11677 Names are zero-terminated UTF-8 strings.
11678 If there is no match, a NULL pointer is returned.
11679 If zVfsName is NULL then the default VFS is returned.</p>
11680
11681 <p>New VFSes are registered with sqlite3_vfs_register().
11682 Each new VFS becomes the default VFS if the makeDflt flag is set.
11683 The same VFS can be registered multiple times without injury.
11684 To make an existing VFS into the default VFS, register it again
11685 with the makeDflt flag set. If two different VFSes with the
11686 same name are registered, the behavior is undefined. If a
11687 VFS is registered with a name that is NULL or an empty string,
11688 then the behavior is undefined.</p>
11689
11690 <p>Unregister a VFS with the sqlite3_vfs_unregister() interface.
11691 If the default VFS is unregistered, another VFS is chosen as
11692 the default. The choice for the new VFS is arbitrary.
11693 </p><hr><a name="sqlite3_vtab_in_first"></a>
11694 <h2>Find all elements on the right-hand side of an IN constraint.</h2>
11695 </div>
11696 <blockquote><pre>
11697 int sqlite3_vtab_in_first(sqlite3_value *pVal, sqlite3_value **ppOut);
11698 int sqlite3_vtab_in_next(sqlite3_value *pVal, sqlite3_value **ppOut);
11699 </pre></blockquote>
11700 <p>
11701 These interfaces are only useful from within the
11702 <a href="vtab.html#xfilter">xFilter() method</a> of a <a href="vtab.html">virtual table</a> implementation.
11703 The result of invoking these interfaces from any other context
11704 is undefined and probably harmful.</p>
11705
11706 <p>The X parameter in a call to sqlite3_vtab_in_first(X,P) or
11707 sqlite3_vtab_in_next(X,P) should be one of the parameters to the
11708 xFilter method which invokes these routines, and specifically
11709 a parameter that was previously selected for all-at-once IN constraint
11710 processing using the <a href="#sqlite3_vtab_in">sqlite3_vtab_in()</a> interface in the
11711 <a href="vtab.html#xbestindex">xBestIndex method</a>. If the X parameter is not
11712 an xFilter argument that was selected for all-at-once IN constraint
11713 processing, then these routines return <a href="#SQLITE_ABORT">SQLITE_ERROR</a>.</p>
11714
11715 <p>Use these routines to access all values on the right-hand side
11716 of the IN constraint using code like the following:</p>
11717
11718 <p><blockquote><pre>
11719 &nbsp; for(rc=sqlite3_vtab_in_first(pList, &pVal);
11720 &nbsp; rc==SQLITE_OK && pVal;
11721 &nbsp; rc=sqlite3_vtab_in_next(pList, &pVal)
11722 &nbsp; ){
11723 &nbsp; // do something with pVal
11724 &nbsp; }
11725 &nbsp; if( rc!=SQLITE_DONE ){
11726 &nbsp; // an error has occurred
11727 &nbsp; }
11728 </pre></blockquote></p>
11729
11730 <p>On success, the sqlite3_vtab_in_first(X,P) and sqlite3_vtab_in_next(X,P)
11731 routines return SQLITE_OK and set *P to point to the first or next value
11732 on the RHS of the IN constraint. If there are no more values on the
11733 right hand side of the IN constraint, then *P is set to NULL and these
11734 routines return <a href="#SQLITE_ABORT">SQLITE_DONE</a>. The return value might be
11735 some other value, such as SQLITE_NOMEM, in the event of a malfunction.</p>
11736
11737 <p>The *ppOut values returned by these routines are only valid until the
11738 next call to either of these routines or until the end of the xFilter
11739 method from which these routines were called. If the virtual table
11740 implementation needs to retain the *ppOut values for longer, it must make
11741 copies. The *ppOut values are <a href="#sqlite3_value">protected</a>.
11742 </p><hr><a name="sqlite3_win32_set_directory"></a>
11743 <h2>Win32 Specific Interface</h2>
11744 </div>
11745 <blockquote><pre>
11746 int sqlite3_win32_set_directory(
11747 unsigned long type, /* Identifier for directory being set or reset */
11748 void *zValue /* New value for directory being set or reset */
11749 );
11750 int sqlite3_win32_set_directory8(unsigned long type, const char *zValue);
11751 int sqlite3_win32_set_directory16(unsigned long type, const void *zValue);
11752 </pre></blockquote>
11753 <p>
11754 These interfaces are available only on Windows. The
11755 <a href="#sqlite3_win32_set_directory">sqlite3_win32_set_directory</a> interface is used to set the value associated
11756 with the <a href="#sqlite3_temp_directory">sqlite3_temp_directory</a> or <a href="#sqlite3_data_directory">sqlite3_data_directory</a> variable, to
11757 zValue, depending on the value of the type parameter. The zValue parameter
11758 should be NULL to cause the previous value to be freed via <a href="#sqlite3_free">sqlite3_free</a>;
11759 a non-NULL value will be copied into memory obtained from <a href="#sqlite3_free">sqlite3_malloc</a>
11760 prior to being used. The <a href="#sqlite3_win32_set_directory">sqlite3_win32_set_directory</a> interface returns
11761 <a href="#SQLITE_ABORT">SQLITE_OK</a> to indicate success, <a href="#SQLITE_ABORT">SQLITE_ERROR</a> if the type is unsupported,
11762 or <a href="#SQLITE_ABORT">SQLITE_NOMEM</a> if memory could not be allocated. The value of the
11763 <a href="#sqlite3_data_directory">sqlite3_data_directory</a> variable is intended to act as a replacement for
11764 the current directory on the sub-platforms of Win32 where that concept is
11765 not present, e.g. WinRT and UWP. The <a href="#sqlite3_win32_set_directory">sqlite3_win32_set_directory8</a> and
11766 <a href="#sqlite3_win32_set_directory">sqlite3_win32_set_directory16</a> interfaces behave exactly the same as the
11767 sqlite3_win32_set_directory interface except the string parameter must be
11768 UTF-8 or UTF-16, respectively.
11769 </p><hr><a name="sqlite3_bind_blob"></a>
11770 <h2>Binding Values To Prepared Statements</h2>
11771 </div>
11772 <blockquote><pre>
11773 int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
11774 int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
11775 void(*)(void*));
11776 int sqlite3_bind_double(sqlite3_stmt*, int, double);
11777 int sqlite3_bind_int(sqlite3_stmt*, int, int);
11778 int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
11779 int sqlite3_bind_null(sqlite3_stmt*, int);
11780 int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
11781 int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
11782 int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
11783 void(*)(void*), unsigned char encoding);
11784 int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
11785 int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*));
11786 int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
11787 int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
11788 </pre></blockquote>
11789 <p>
11790 In the SQL statement text input to <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> and its variants,
11791 literals may be replaced by a <a href="lang_expr.html#varparam">parameter</a> that matches one of the following
11792 templates:</p>
11793
11794 <p><ul>
11795 <li> ?
11796 <li> ?NNN
11797 <li> :VVV
11798 <li> @VVV
11799 <li> $VVV
11800 </ul></p>
11801
11802 <p>In the templates above, NNN represents an integer literal,
11803 and VVV represents an alphanumeric identifier. The values of these
11804 parameters (also called "host parameter names" or "SQL parameters")
11805 can be set using the sqlite3_bind_*() routines defined here.</p>
11806
11807 <p>The first argument to the sqlite3_bind_*() routines is always
11808 a pointer to the <a href="#sqlite3_stmt">sqlite3_stmt</a> object returned from
11809 <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or its variants.</p>
11810
11811 <p>The second argument is the index of the SQL parameter to be set.
11812 The leftmost SQL parameter has an index of 1. When the same named
11813 SQL parameter is used more than once, second and subsequent
11814 occurrences have the same index as the first occurrence.
11815 The index for named parameters can be looked up using the
11816 <a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a> API if desired. The index
11817 for "?NNN" parameters is the value of NNN.
11818 The NNN value must be between 1 and the <a href="#sqlite3_limit">sqlite3_limit()</a>
11819 parameter <a href="#sqlitelimitvariablenumber">SQLITE_LIMIT_VARIABLE_NUMBER</a> (default value: 32766).</p>
11820
11821 <p>The third argument is the value to bind to the parameter.
11822 If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
11823 or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
11824 is ignored and the end result is the same as sqlite3_bind_null().
11825 If the third parameter to sqlite3_bind_text() is not NULL, then
11826 it should be a pointer to well-formed UTF8 text.
11827 If the third parameter to sqlite3_bind_text16() is not NULL, then
11828 it should be a pointer to well-formed UTF16 text.
11829 If the third parameter to sqlite3_bind_text64() is not NULL, then
11830 it should be a pointer to a well-formed unicode string that is
11831 either UTF8 if the sixth parameter is SQLITE_UTF8 or SQLITE_UTF8_ZT,
11832 or UTF16 otherwise.</p>
11833
11834 <p><a name="byteorderdeterminationrules"></a>
11835 The byte-order of
11836 UTF16 input text is determined by the byte-order mark (BOM, U+FEFF)
11837 found in the first character, which is removed, or in the absence of a BOM
11838 the byte order is the native byte order of the host
11839 machine for sqlite3_bind_text16() or the byte order specified in
11840 the 6th parameter for sqlite3_bind_text64().
11841 If UTF16 input text contains invalid unicode
11842 characters, then SQLite might change those invalid characters
11843 into the unicode replacement character: U+FFFD.</p>
11844
11845 <p>In those routines that have a fourth argument, its value is the
11846 number of bytes in the parameter. To be clear: the value is the
11847 number of <u>bytes</u> in the value, not the number of characters.
11848 If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
11849 is negative, then the length of the string is
11850 the number of bytes up to the first zero terminator.
11851 If the fourth parameter to sqlite3_bind_blob() is negative, then
11852 the behavior is undefined.
11853 If a non-negative fourth parameter is provided to sqlite3_bind_text()
11854 or sqlite3_bind_text16() or sqlite3_bind_text64() then
11855 that parameter must be the byte offset
11856 where the NUL terminator would occur assuming the string were NUL
11857 terminated. If any NUL characters occur at byte offsets less than
11858 the value of the fourth parameter then the resulting string value will
11859 contain embedded NULs. The result of expressions involving strings
11860 with embedded NULs is undefined.</p>
11861
11862 <p>The fifth argument to the BLOB and string binding interfaces controls
11863 or indicates the lifetime of the object referenced by the third parameter.
11864 These three options exist:
11865 (1) A destructor to dispose of the BLOB or string after SQLite has finished
11866 with it may be passed. It is called to dispose of the BLOB or string even
11867 if the call to the bind API fails, except the destructor is not called if
11868 the third parameter is a NULL pointer or the fourth parameter is negative.
11869 (2) The special constant, <a href="#SQLITE_STATIC">SQLITE_STATIC</a>, may be passed to indicate that
11870 the application remains responsible for disposing of the object. In this
11871 case, the object and the provided pointer to it must remain valid until
11872 either the prepared statement is finalized or the same SQL parameter is
11873 bound to something else, whichever occurs sooner.
11874 (3) The constant, <a href="#SQLITE_STATIC">SQLITE_TRANSIENT</a>, may be passed to indicate that the
11875 object is to be copied prior to the return from sqlite3_bind_*(). The
11876 object and pointer to it must remain valid until then. SQLite will then
11877 manage the lifetime of its private copy.</p>
11878
11879 <p>The sixth argument (the E argument)
11880 to sqlite3_bind_text64(S,K,Z,N,D,E) must be one of
11881 <a href="#sqliteutf8">SQLITE_UTF8</a>, <a href="#sqliteutf8zt">SQLITE_UTF8_ZT</a>, <a href="#sqliteutf16">SQLITE_UTF16</a>, <a href="#sqliteutf16be">SQLITE_UTF16BE</a>,
11882 or <a href="#sqliteutf16le">SQLITE_UTF16LE</a> to specify the encoding of the text in the
11883 third parameter, Z. The special value <a href="#sqliteutf8zt">SQLITE_UTF8_ZT</a> means that the
11884 string argument is both UTF-8 encoded and is zero-terminated. In other
11885 words, SQLITE_UTF8_ZT means that the Z array is allocated to hold at
11886 least N+1 bytes and that the Z&#91;N&#93; byte is zero. If
11887 the E argument to sqlite3_bind_text64(S,K,Z,N,D,E) is not one of the
11888 allowed values shown above, or if the text encoding is different
11889 from the encoding specified by the sixth parameter, then the behavior
11890 is undefined.</p>
11891
11892 <p>The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
11893 is filled with zeroes. A zeroblob uses a fixed amount of memory
11894 (just an integer to hold its size) while it is being processed.
11895 Zeroblobs are intended to serve as placeholders for BLOBs whose
11896 content is later written using
11897 <a href="#sqlite3_blob_open">incremental BLOB I/O</a> routines.
11898 A negative value for the zeroblob results in a zero-length BLOB.</p>
11899
11900 <p>The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in
11901 <a href="#sqlite3_stmt">prepared statement</a> S to have an SQL value of NULL, but to also be
11902 associated with the pointer P of type T. D is either a NULL pointer or
11903 a pointer to a destructor function for P. SQLite will invoke the
11904 destructor D with a single argument of P when it is finished using
11905 P, even if the call to sqlite3_bind_pointer() fails. Due to a
11906 historical design quirk, results are undefined if D is
11907 SQLITE_TRANSIENT. The T parameter should be a static string,
11908 preferably a string literal. The sqlite3_bind_pointer() routine is
11909 part of the <a href="bindptr.html">pointer passing interface</a> added for SQLite 3.20.0.</p>
11910
11911 <p>If any of the sqlite3_bind_*() routines are called with a NULL pointer
11912 for the <a href="#sqlite3_stmt">prepared statement</a> or with a prepared statement for which
11913 <a href="#sqlite3_step">sqlite3_step()</a> has been called more recently than <a href="#sqlite3_reset">sqlite3_reset()</a>,
11914 then the call will return <a href="#SQLITE_ABORT">SQLITE_MISUSE</a>. If any sqlite3_bind_()
11915 routine is passed a <a href="#sqlite3_stmt">prepared statement</a> that has been finalized, the
11916 result is undefined and probably harmful.</p>
11917
11918 <p>Bindings are not cleared by the <a href="#sqlite3_reset">sqlite3_reset()</a> routine.
11919 Unbound parameters are interpreted as NULL.</p>
11920
11921 <p>The sqlite3_bind_* routines return <a href="#SQLITE_ABORT">SQLITE_OK</a> on success or an
11922 <a href="rescode.html">error code</a> if anything goes wrong.
11923 <a href="#SQLITE_ABORT">SQLITE_TOOBIG</a> might be returned if the size of a string or BLOB
11924 exceeds limits imposed by <a href="#sqlite3_limit">sqlite3_limit</a>(<a href="#sqlitelimitlength">SQLITE_LIMIT_LENGTH</a>) or
11925 <a href="limits.html#max_length">SQLITE_MAX_LENGTH</a>.
11926 <a href="#SQLITE_ABORT">SQLITE_RANGE</a> is returned if the parameter
11927 index is out of range. <a href="#SQLITE_ABORT">SQLITE_NOMEM</a> is returned if malloc() fails.</p>
11928
11929 <p>See also: <a href="#sqlite3_bind_parameter_count">sqlite3_bind_parameter_count()</a>,
11930 <a href="#sqlite3_bind_parameter_name">sqlite3_bind_parameter_name()</a>, and <a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a>.
11931 </p><hr><a name="sqlite3_prepare"></a>
11932 <h2>Compiling An SQL Statement</h2>
11933 </div>
11934 <blockquote><pre>
11935 int sqlite3_prepare(
11936 sqlite3 *db, /* Database handle */
11937 const char *zSql, /* SQL statement, UTF-8 encoded */
11938 int nByte, /* Maximum length of zSql in bytes. */
11939 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
11940 const char **pzTail /* OUT: Pointer to unused portion of zSql */
11941 );
11942 int sqlite3_prepare_v2(
11943 sqlite3 *db, /* Database handle */
11944 const char *zSql, /* SQL statement, UTF-8 encoded */
11945 int nByte, /* Maximum length of zSql in bytes. */
11946 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
11947 const char **pzTail /* OUT: Pointer to unused portion of zSql */
11948 );
11949 int sqlite3_prepare_v3(
11950 sqlite3 *db, /* Database handle */
11951 const char *zSql, /* SQL statement, UTF-8 encoded */
11952 int nByte, /* Maximum length of zSql in bytes. */
11953 unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
11954 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
11955 const char **pzTail /* OUT: Pointer to unused portion of zSql */
11956 );
11957 int sqlite3_prepare16(
11958 sqlite3 *db, /* Database handle */
11959 const void *zSql, /* SQL statement, UTF-16 encoded */
11960 int nByte, /* Maximum length of zSql in bytes. */
11961 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
11962 const void **pzTail /* OUT: Pointer to unused portion of zSql */
11963 );
11964 int sqlite3_prepare16_v2(
11965 sqlite3 *db, /* Database handle */
11966 const void *zSql, /* SQL statement, UTF-16 encoded */
11967 int nByte, /* Maximum length of zSql in bytes. */
11968 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
11969 const void **pzTail /* OUT: Pointer to unused portion of zSql */
11970 );
11971 int sqlite3_prepare16_v3(
11972 sqlite3 *db, /* Database handle */
11973 const void *zSql, /* SQL statement, UTF-16 encoded */
11974 int nByte, /* Maximum length of zSql in bytes. */
11975 unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
11976 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
11977 const void **pzTail /* OUT: Pointer to unused portion of zSql */
11978 );
11979 </pre></blockquote>
11980 <p>
11981 To execute an SQL statement, it must first be compiled into a byte-code
11982 program using one of these routines. Or, in other words, these routines
11983 are constructors for the <a href="#sqlite3_stmt">prepared statement</a> object.</p>
11984
11985 <p>The preferred routine to use is <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>. The
11986 <a href="#sqlite3_prepare">sqlite3_prepare()</a> interface is legacy and should be avoided.
11987 <a href="#sqlite3_prepare">sqlite3_prepare_v3()</a> has an extra
11988 <a href="#sqlitepreparefromddl">"prepFlags" option</a> that is sometimes
11989 needed for special purpose or to pass along security restrictions.</p>
11990
11991 <p>The use of the UTF-8 interfaces is preferred, as SQLite currently
11992 does all parsing using UTF-8. The UTF-16 interfaces are provided
11993 as a convenience. The UTF-16 interfaces work by converting the
11994 input text into UTF-8, then invoking the corresponding UTF-8 interface.</p>
11995
11996 <p>The first argument, "db", is a <a href="#sqlite3">database connection</a> obtained from a
11997 prior successful call to <a href="#sqlite3_open">sqlite3_open()</a>, <a href="#sqlite3_open">sqlite3_open_v2()</a> or
11998 <a href="#sqlite3_open">sqlite3_open16()</a>. The database connection must not have been closed.</p>
11999
12000 <p>The second argument, "zSql", is the statement to be compiled, encoded
12001 as either UTF-8 or UTF-16. The sqlite3_prepare(), sqlite3_prepare_v2(),
12002 and sqlite3_prepare_v3()
12003 interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),
12004 and sqlite3_prepare16_v3() use UTF-16.</p>
12005
12006 <p>If the nByte argument is negative, then zSql is read up to the
12007 first zero terminator. If nByte is positive, then it is the maximum
12008 number of bytes read from zSql. When nByte is positive, zSql is read
12009 up to the first zero terminator or until the nByte bytes have been read,
12010 whichever comes first. If nByte is zero, then no prepared
12011 statement is generated.
12012 If the caller knows that the supplied string is nul-terminated, then
12013 there is a small performance advantage to passing an nByte parameter that
12014 is the number of bytes in the input string <i>including</i>
12015 the nul-terminator.
12016 Note that nByte measures the length of the input in bytes, not
12017 characters, even for the UTF-16 interfaces.</p>
12018
12019 <p>If pzTail is not NULL then *pzTail is made to point to the first byte
12020 past the end of the first SQL statement in zSql. These routines only
12021 compile the first statement in zSql, so *pzTail is left pointing to
12022 what remains uncompiled.</p>
12023
12024 <p>*ppStmt is left pointing to a compiled <a href="#sqlite3_stmt">prepared statement</a> that can be
12025 executed using <a href="#sqlite3_step">sqlite3_step()</a>. If there is an error, *ppStmt is set
12026 to NULL. If the input text contains no SQL (if the input is an empty
12027 string or a comment) then *ppStmt is set to NULL.
12028 The calling procedure is responsible for deleting the compiled
12029 SQL statement using <a href="#sqlite3_finalize">sqlite3_finalize()</a> after it has finished with it.
12030 ppStmt may not be NULL.</p>
12031
12032 <p>On success, the sqlite3_prepare() family of routines return <a href="#SQLITE_ABORT">SQLITE_OK</a>;
12033 otherwise an <a href="rescode.html">error code</a> is returned.</p>
12034
12035 <p>The sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(),
12036 and sqlite3_prepare16_v3() interfaces are recommended for all new programs.
12037 The older interfaces (sqlite3_prepare() and sqlite3_prepare16())
12038 are retained for backwards compatibility, but their use is discouraged.
12039 In the "vX" interfaces, the prepared statement
12040 that is returned (the <a href="#sqlite3_stmt">sqlite3_stmt</a> object) contains a copy of the
12041 original SQL text. This causes the <a href="#sqlite3_step">sqlite3_step()</a> interface to
12042 behave differently in three ways:</p>
12043
12044 <p><ol>
12045 <li>
12046 If the database schema changes, instead of returning <a href="#SQLITE_ABORT">SQLITE_SCHEMA</a> as it
12047 always used to do, <a href="#sqlite3_step">sqlite3_step()</a> will automatically recompile the SQL
12048 statement and try to run it again. As many as <a href="compile.html#max_schema_retry">SQLITE_MAX_SCHEMA_RETRY</a>
12049 retries will occur before sqlite3_step() gives up and returns an error.
12050 </li></p>
12051
12052 <p><li>
12053 When an error occurs, <a href="#sqlite3_step">sqlite3_step()</a> will return one of the detailed
12054 <a href="rescode.html">error codes</a> or <a href="rescode.html#extrc">extended error codes</a>. The legacy behavior was that
12055 <a href="#sqlite3_step">sqlite3_step()</a> would only return a generic <a href="#SQLITE_ABORT">SQLITE_ERROR</a> result code
12056 and the application would have to make a second call to <a href="#sqlite3_reset">sqlite3_reset()</a>
12057 in order to find the underlying cause of the problem. With the "v2" prepare
12058 interfaces, the underlying reason for the error is returned immediately.
12059 </li></p>
12060
12061 <p><li>
12062 If the specific value bound to a <a href="lang_expr.html#varparam">host parameter</a> in the
12063 WHERE clause might influence the choice of query plan for a statement,
12064 then the statement will be automatically recompiled, as if there had been
12065 a schema change, on the first <a href="#sqlite3_step">sqlite3_step()</a> call following any change
12066 to the <a href="#sqlite3_bind_blob">bindings</a> of that <a href="lang_expr.html#varparam">parameter</a>.
12067 The specific value of a WHERE-clause <a href="lang_expr.html#varparam">parameter</a> might influence the
12068 choice of query plan if the parameter is the left-hand side of a <a href="lang_expr.html#like">LIKE</a>
12069 or <a href="lang_expr.html#glob">GLOB</a> operator or if the parameter is compared to an indexed column
12070 and the <a href="compile.html#enable_stat4">SQLITE_ENABLE_STAT4</a> compile-time option is enabled.
12071 </li>
12072 </ol></p>
12073
12074 <p><p>sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having
12075 the extra prepFlags parameter, which is a bit array consisting of zero or
12076 more of the <a href="#sqlitepreparepersistent">SQLITE_PREPARE_*</a> flags. The
12077 sqlite3_prepare_v2() interface works exactly the same as
12078 sqlite3_prepare_v3() with a zero prepFlags parameter.
12079 </p><hr><a name="sqlite3_set_authorizer"></a>
12080 <h2>Compile-Time Authorization Callbacks</h2>
12081 </div>
12082 <blockquote><pre>
12083 int sqlite3_set_authorizer(
12084 sqlite3*,
12085 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
12086 void *pUserData
12087 );
12088 </pre></blockquote>
12089 <p>
12090 This routine registers an authorizer callback with a particular
12091 <a href="#sqlite3">database connection</a>, supplied in the first argument.
12092 The authorizer callback is invoked as SQL statements are being compiled
12093 by <a href="#sqlite3_prepare">sqlite3_prepare()</a> or its variants <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>,
12094 <a href="#sqlite3_prepare">sqlite3_prepare_v3()</a>, <a href="#sqlite3_prepare">sqlite3_prepare16()</a>, <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a>,
12095 and <a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a>. At various
12096 points during the compilation process, as logic is being created
12097 to perform various actions, the authorizer callback is invoked to
12098 see if those actions are allowed. The authorizer callback should
12099 return <a href="#SQLITE_ABORT">SQLITE_OK</a> to allow the action, <a href="#SQLITE_DENY">SQLITE_IGNORE</a> to disallow the
12100 specific action but allow the SQL statement to continue to be
12101 compiled, or <a href="#SQLITE_DENY">SQLITE_DENY</a> to cause the entire SQL statement to be
12102 rejected with an error. If the authorizer callback returns
12103 any value other than <a href="#SQLITE_DENY">SQLITE_IGNORE</a>, <a href="#SQLITE_ABORT">SQLITE_OK</a>, or <a href="#SQLITE_DENY">SQLITE_DENY</a>
12104 then the <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or equivalent call that triggered
12105 the authorizer will fail with an error message.</p>
12106
12107 <p>When the callback returns <a href="#SQLITE_ABORT">SQLITE_OK</a>, that means the operation
12108 requested is ok. When the callback returns <a href="#SQLITE_DENY">SQLITE_DENY</a>, the
12109 <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or equivalent call that triggered the
12110 authorizer will fail with an error message explaining that
12111 access is denied.</p>
12112
12113 <p>The first parameter to the authorizer callback is a copy of the third
12114 parameter to the sqlite3_set_authorizer() interface. The second parameter
12115 to the callback is an integer <a href="#SQLITE_ALTER_TABLE">action code</a> that specifies
12116 the particular action to be authorized. The third through sixth parameters
12117 to the callback are either NULL pointers or zero-terminated strings
12118 that contain additional details about the action to be authorized.
12119 Applications must always be prepared to encounter a NULL pointer in any
12120 of the third through the sixth parameters of the authorization callback.</p>
12121
12122 <p>If the action code is <a href="#SQLITE_ALTER_TABLE">SQLITE_READ</a>
12123 and the callback returns <a href="#SQLITE_DENY">SQLITE_IGNORE</a> then the
12124 <a href="#sqlite3_stmt">prepared statement</a> statement is constructed to substitute
12125 a NULL value in place of the table column that would have
12126 been read if <a href="#SQLITE_ABORT">SQLITE_OK</a> had been returned. The <a href="#SQLITE_DENY">SQLITE_IGNORE</a>
12127 return can be used to deny an untrusted user access to individual
12128 columns of a table.
12129 When a table is referenced by a <a href="lang_select.html">SELECT</a> but no column values are
12130 extracted from that table (for example in a query like
12131 "SELECT count(*) FROM tab") then the <a href="#SQLITE_ALTER_TABLE">SQLITE_READ</a> authorizer callback
12132 is invoked once for that table with a column name that is an empty string.
12133 If the action code is <a href="#SQLITE_ALTER_TABLE">SQLITE_DELETE</a> and the callback returns
12134 <a href="#SQLITE_DENY">SQLITE_IGNORE</a> then the <a href="lang_delete.html">DELETE</a> operation proceeds but the
12135 <a href="lang_delete.html#truncateopt">truncate optimization</a> is disabled and all rows are deleted individually.</p>
12136
12137 <p>An authorizer is used when <a href="#sqlite3_prepare">preparing</a>
12138 SQL statements from an untrusted source, to ensure that the SQL statements
12139 do not try to access data they are not allowed to see, or that they do not
12140 try to execute malicious statements that damage the database. For
12141 example, an application may allow a user to enter arbitrary
12142 SQL queries for evaluation by a database. But the application does
12143 not want the user to be able to make arbitrary changes to the
12144 database. An authorizer could then be put in place while the
12145 user-entered SQL is being <a href="#sqlite3_prepare">prepared</a> that
12146 disallows everything except <a href="lang_select.html">SELECT</a> statements.</p>
12147
12148 <p>Applications that need to process SQL from untrusted sources
12149 might also consider lowering resource limits using <a href="#sqlite3_limit">sqlite3_limit()</a>
12150 and limiting database size using the <a href="pragma.html#pragma_max_page_count">max_page_count</a> <a href="pragma.html#syntax">PRAGMA</a>
12151 in addition to using an authorizer.</p>
12152
12153 <p>Only a single authorizer can be in place on a database connection
12154 at a time. Each call to sqlite3_set_authorizer overrides the
12155 previous call. Disable the authorizer by installing a NULL callback.
12156 The authorizer is disabled by default.</p>
12157
12158 <p>The authorizer callback must not do anything that will modify
12159 the database connection that invoked the authorizer callback.
12160 Note that <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> and <a href="#sqlite3_step">sqlite3_step()</a> both modify their
12161 database connections for the meaning of "modify" in this paragraph.</p>
12162
12163 <p>When <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> is used to prepare a statement, the
12164 statement might be re-prepared during <a href="#sqlite3_step">sqlite3_step()</a> due to a
12165 schema change. Hence, the application should ensure that the
12166 correct authorizer callback remains in place during the <a href="#sqlite3_step">sqlite3_step()</a>.</p>
12167
12168 <p>Note that the authorizer callback is invoked only during
12169 <a href="#sqlite3_prepare">sqlite3_prepare()</a> or its variants. Authorization is not
12170 performed during statement evaluation in <a href="#sqlite3_step">sqlite3_step()</a>, unless
12171 as stated in the previous paragraph, sqlite3_step() invokes
12172 sqlite3_prepare_v2() to reprepare a statement after a schema change.
12173 </p><hr><a name="sqlite3_get_autocommit"></a>
12174 <h2>Test For Auto-Commit Mode</h2>
12175 </div>
12176 <blockquote><pre>
12177 int sqlite3_get_autocommit(sqlite3*);
12178 </pre></blockquote>
12179 <p>
12180 The sqlite3_get_autocommit() interface returns non-zero or
12181 zero if the given database connection is or is not in autocommit mode,
12182 respectively. Autocommit mode is on by default.
12183 Autocommit mode is disabled by a <a href="lang_transaction.html">BEGIN</a> statement.
12184 Autocommit mode is re-enabled by a <a href="lang_transaction.html">COMMIT</a> or <a href="lang_transaction.html">ROLLBACK</a>.</p>
12185
12186 <p>If certain kinds of errors occur on a statement within a multi-statement
12187 transaction (errors including <a href="#SQLITE_ABORT">SQLITE_FULL</a>, <a href="#SQLITE_ABORT">SQLITE_IOERR</a>,
12188 <a href="#SQLITE_ABORT">SQLITE_NOMEM</a>, <a href="#SQLITE_ABORT">SQLITE_BUSY</a>, and <a href="#SQLITE_ABORT">SQLITE_INTERRUPT</a>) then the
12189 transaction might be rolled back automatically. The only way to
12190 find out whether SQLite automatically rolled back the transaction after
12191 an error is to use this function.</p>
12192
12193 <p>If another thread changes the autocommit status of the database
12194 connection while this routine is running, then the return value
12195 is undefined.
12196 </p><hr><a name="sqlite3_busy_handler"></a>
12197 <h2>Register A Callback To Handle SQLITE_BUSY Errors</h2>
12198 </div>
12199 <blockquote><pre>
12200 int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*);
12201 </pre></blockquote>
12202 <p>
12203 The sqlite3_busy_handler(D,X,P) routine sets a callback function X
12204 that might be invoked with argument P whenever
12205 an attempt is made to access a database table associated with
12206 <a href="#sqlite3">database connection</a> D when another thread
12207 or process has the table locked.
12208 The sqlite3_busy_handler() interface is used to implement
12209 <a href="#sqlite3_busy_timeout">sqlite3_busy_timeout()</a> and <a href="pragma.html#pragma_busy_timeout">PRAGMA busy_timeout</a>.</p>
12210
12211 <p>If the busy callback is NULL, then <a href="#SQLITE_ABORT">SQLITE_BUSY</a>
12212 is returned immediately upon encountering the lock. If the busy callback
12213 is not NULL, then the callback might be invoked with two arguments.</p>
12214
12215 <p>The first argument to the busy handler is a copy of the void* pointer which
12216 is the third argument to sqlite3_busy_handler(). The second argument to
12217 the busy handler callback is the number of times that the busy handler has
12218 been invoked previously for the same locking event. If the
12219 busy callback returns 0, then no additional attempts are made to
12220 access the database and <a href="#SQLITE_ABORT">SQLITE_BUSY</a> is returned
12221 to the application.
12222 If the callback returns non-zero, then another attempt
12223 is made to access the database and the cycle repeats.</p>
12224
12225 <p>The presence of a busy handler does not guarantee that it will be invoked
12226 when there is lock contention. If SQLite determines that invoking the busy
12227 handler could result in a deadlock, it will go ahead and return <a href="#SQLITE_ABORT">SQLITE_BUSY</a>
12228 to the application instead of invoking the
12229 busy handler.
12230 Consider a scenario where one process is holding a read lock that
12231 it is trying to promote to a reserved lock and
12232 a second process is holding a reserved lock that it is trying
12233 to promote to an exclusive lock. The first process cannot proceed
12234 because it is blocked by the second and the second process cannot
12235 proceed because it is blocked by the first. If both processes
12236 invoke the busy handlers, neither will make any progress. Therefore,
12237 SQLite returns <a href="#SQLITE_ABORT">SQLITE_BUSY</a> for the first process, hoping that this
12238 will induce the first process to release its read lock and allow
12239 the second process to proceed.</p>
12240
12241 <p>The default busy callback is NULL.</p>
12242
12243 <p>There can only be a single busy handler defined for each
12244 <a href="#sqlite3">database connection</a>. Setting a new busy handler clears any
12245 previously set handler. Note that calling <a href="#sqlite3_busy_timeout">sqlite3_busy_timeout()</a>
12246 or evaluating <a href="pragma.html#pragma_busy_timeout">PRAGMA busy_timeout=N</a> will change the
12247 busy handler and thus clear any previously set busy handler.</p>
12248
12249 <p>The busy callback should not take any actions which modify the
12250 database connection that invoked the busy handler. In other words,
12251 the busy handler is not reentrant. Any such actions
12252 result in undefined behavior.</p>
12253
12254 <p>A busy handler must not close the database connection
12255 or <a href="#sqlite3_stmt">prepared statement</a> that invoked the busy handler.
12256 </p><hr><a name="sqlite3_column_blob"></a>
12257 <h2>Result Values From A Query</h2>
12258 </div>
12259 <blockquote><pre>
12260 const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
12261 double sqlite3_column_double(sqlite3_stmt*, int iCol);
12262 int sqlite3_column_int(sqlite3_stmt*, int iCol);
12263 sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
12264 const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
12265 const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
12266 sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
12267 int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
12268 int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
12269 int sqlite3_column_type(sqlite3_stmt*, int iCol);
12270 </pre></blockquote>
12271 <p>
12272 <b>Summary:</b>
12273 <blockquote><table border=0 cellpadding=0 cellspacing=0>
12274 <tr><td><b>sqlite3_column_blob</b><td>&rarr;<td>BLOB result
12275 <tr><td><b>sqlite3_column_double</b><td>&rarr;<td>REAL result
12276 <tr><td><b>sqlite3_column_int</b><td>&rarr;<td>32-bit INTEGER result
12277 <tr><td><b>sqlite3_column_int64</b><td>&rarr;<td>64-bit INTEGER result
12278 <tr><td><b>sqlite3_column_text</b><td>&rarr;<td>UTF-8 TEXT result
12279 <tr><td><b>sqlite3_column_text16</b><td>&rarr;<td>UTF-16 TEXT result
12280 <tr><td><b>sqlite3_column_value</b><td>&rarr;<td>The result as an
12281 <a href="#sqlite3_value">unprotected sqlite3_value</a> object.
12282 <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
12283 <tr><td><b>sqlite3_column_bytes</b><td>&rarr;<td>Size of a BLOB
12284 or a UTF-8 TEXT result in bytes
12285 <tr><td><b>sqlite3_column_bytes16&nbsp;&nbsp;</b>
12286 <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
12287 TEXT in bytes
12288 <tr><td><b>sqlite3_column_type</b><td>&rarr;<td>Default
12289 datatype of the result
12290 </table></blockquote></p>
12291
12292 <p><b>Details:</b></p>
12293
12294 <p>These routines return information about a single column of the current
12295 result row of a query. In every case the first argument is a pointer
12296 to the <a href="#sqlite3_stmt">prepared statement</a> that is being evaluated (the <a href="#sqlite3_stmt">sqlite3_stmt*</a>
12297 that was returned from <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or one of its variants)
12298 and the second argument is the index of the column for which information
12299 should be returned. The leftmost column of the result set has the index 0.
12300 The number of columns in the result can be determined using
12301 <a href="#sqlite3_column_count">sqlite3_column_count()</a>.</p>
12302
12303 <p>If the SQL statement does not currently point to a valid row, or if the
12304 column index is out of range, the result is undefined.
12305 These routines may only be called when the most recent call to
12306 <a href="#sqlite3_step">sqlite3_step()</a> has returned <a href="#SQLITE_ABORT">SQLITE_ROW</a> and neither
12307 <a href="#sqlite3_reset">sqlite3_reset()</a> nor <a href="#sqlite3_finalize">sqlite3_finalize()</a> have been called subsequently.
12308 If any of these routines are called after <a href="#sqlite3_reset">sqlite3_reset()</a> or
12309 <a href="#sqlite3_finalize">sqlite3_finalize()</a> or after <a href="#sqlite3_step">sqlite3_step()</a> has returned
12310 something other than <a href="#SQLITE_ABORT">SQLITE_ROW</a>, the results are undefined.
12311 If <a href="#sqlite3_step">sqlite3_step()</a> or <a href="#sqlite3_reset">sqlite3_reset()</a> or <a href="#sqlite3_finalize">sqlite3_finalize()</a>
12312 are called from a different thread while any of these routines
12313 are pending, then the results are undefined.</p>
12314
12315 <p>The first six interfaces (_blob, _double, _int, _int64, _text, and _text16)
12316 each return the value of a result column in a specific data format. If
12317 the result column is not initially in the requested format (for example,
12318 if the query returns an integer but the sqlite3_column_text() interface
12319 is used to extract the value) then an automatic type conversion is performed.</p>
12320
12321 <p>The sqlite3_column_type() routine returns the
12322 <a href="#SQLITE_BLOB">datatype code</a> for the initial data type
12323 of the result column. The returned value is one of <a href="#SQLITE_BLOB">SQLITE_INTEGER</a>,
12324 <a href="#SQLITE_BLOB">SQLITE_FLOAT</a>, <a href="#SQLITE_BLOB">SQLITE_TEXT</a>, <a href="#SQLITE_BLOB">SQLITE_BLOB</a>, or <a href="#SQLITE_BLOB">SQLITE_NULL</a>.
12325 The return value of sqlite3_column_type() can be used to decide which
12326 of the first six interface should be used to extract the column value.
12327 The value returned by sqlite3_column_type() is only meaningful if no
12328 automatic type conversions have occurred for the value in question.
12329 After a type conversion, the result of calling sqlite3_column_type()
12330 is undefined, though harmless. Future
12331 versions of SQLite may change the behavior of sqlite3_column_type()
12332 following a type conversion.</p>
12333
12334 <p>If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()
12335 or sqlite3_column_bytes16() interfaces can be used to determine the size
12336 of that BLOB or string.</p>
12337
12338 <p>If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
12339 routine returns the number of bytes in that BLOB or string.
12340 If the result is a UTF-16 string, then sqlite3_column_bytes() converts
12341 the string to UTF-8 and then returns the number of bytes.
12342 If the result is a numeric value then sqlite3_column_bytes() uses
12343 <a href="#sqlite3_mprintf">sqlite3_snprintf()</a> to convert that value to a UTF-8 string and returns
12344 the number of bytes in that string.
12345 If the result is NULL, then sqlite3_column_bytes() returns zero.</p>
12346
12347 <p>If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
12348 routine returns the number of bytes in that BLOB or string.
12349 If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
12350 the string to UTF-16 and then returns the number of bytes.
12351 If the result is a numeric value then sqlite3_column_bytes16() uses
12352 <a href="#sqlite3_mprintf">sqlite3_snprintf()</a> to convert that value to a UTF-16 string and returns
12353 the number of bytes in that string.
12354 If the result is NULL, then sqlite3_column_bytes16() returns zero.</p>
12355
12356 <p>The values returned by <a href="#sqlite3_column_blob">sqlite3_column_bytes()</a> and
12357 <a href="#sqlite3_column_blob">sqlite3_column_bytes16()</a> do not include the zero terminators at the end
12358 of the string. For clarity: the values returned by
12359 <a href="#sqlite3_column_blob">sqlite3_column_bytes()</a> and <a href="#sqlite3_column_blob">sqlite3_column_bytes16()</a> are the number of
12360 bytes in the string, not the number of characters.</p>
12361
12362 <p>Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
12363 even empty strings, are always zero-terminated. The return
12364 value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.</p>
12365
12366 <p>Strings returned by sqlite3_column_text16() always have the endianness
12367 which is native to the platform, regardless of the text encoding set
12368 for the database.</p>
12369
12370 <p><b>Warning:</b> The object returned by <a href="#sqlite3_column_blob">sqlite3_column_value()</a> is an
12371 <a href="#sqlite3_value">unprotected sqlite3_value</a> object. In a multithreaded environment,
12372 an unprotected sqlite3_value object may only be used safely with
12373 <a href="#sqlite3_bind_blob">sqlite3_bind_value()</a> and <a href="#sqlite3_result_blob">sqlite3_result_value()</a>.
12374 If the <a href="#sqlite3_value">unprotected sqlite3_value</a> object returned by
12375 <a href="#sqlite3_column_blob">sqlite3_column_value()</a> is used in any other way, including calls
12376 to routines like <a href="#sqlite3_value_blob">sqlite3_value_int()</a>, <a href="#sqlite3_value_blob">sqlite3_value_text()</a>,
12377 or <a href="#sqlite3_value_blob">sqlite3_value_bytes()</a>, the behavior is not threadsafe.
12378 Hence, the sqlite3_column_value() interface
12379 is normally only useful within the implementation of
12380 <a href="appfunc.html">application-defined SQL functions</a> or <a href="vtab.html">virtual tables</a>, not within
12381 top-level application code.</p>
12382
12383 <p>These routines may attempt to convert the datatype of the result.
12384 For example, if the internal representation is FLOAT and a text result
12385 is requested, <a href="#sqlite3_mprintf">sqlite3_snprintf()</a> is used internally to perform the
12386 conversion automatically. The following table details the conversions
12387 that are applied:</p>
12388
12389 <p><blockquote>
12390 <table border="1">
12391 <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion</p>
12392
12393 <p><tr><td> NULL <td> INTEGER <td> Result is 0
12394 <tr><td> NULL <td> FLOAT <td> Result is 0.0
12395 <tr><td> NULL <td> TEXT <td> Result is a NULL pointer
12396 <tr><td> NULL <td> BLOB <td> Result is a NULL pointer
12397 <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
12398 <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
12399 <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT
12400 <tr><td> FLOAT <td> INTEGER <td> <a href="lang_expr.html#castexpr">CAST</a> to INTEGER
12401 <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
12402 <tr><td> FLOAT <td> BLOB <td> <a href="lang_expr.html#castexpr">CAST</a> to BLOB
12403 <tr><td> TEXT <td> INTEGER <td> <a href="lang_expr.html#castexpr">CAST</a> to INTEGER
12404 <tr><td> TEXT <td> FLOAT <td> <a href="lang_expr.html#castexpr">CAST</a> to REAL
12405 <tr><td> TEXT <td> BLOB <td> No change
12406 <tr><td> BLOB <td> INTEGER <td> <a href="lang_expr.html#castexpr">CAST</a> to INTEGER
12407 <tr><td> BLOB <td> FLOAT <td> <a href="lang_expr.html#castexpr">CAST</a> to REAL
12408 <tr><td> BLOB <td> TEXT <td> <a href="lang_expr.html#castexpr">CAST</a> to TEXT, ensure zero terminator
12409 </table>
12410 </blockquote></p>
12411
12412 <p>Note that when type conversions occur, pointers returned by prior
12413 calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
12414 sqlite3_column_text16() may be invalidated.
12415 Type conversions and pointer invalidations might occur
12416 in the following cases:</p>
12417
12418 <p><ul>
12419 <li> The initial content is a BLOB and sqlite3_column_text() or
12420 sqlite3_column_text16() is called. A zero-terminator might
12421 need to be added to the string.</li>
12422 <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
12423 sqlite3_column_text16() is called. The content must be converted
12424 to UTF-16.</li>
12425 <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
12426 sqlite3_column_text() is called. The content must be converted
12427 to UTF-8.</li>
12428 </ul></p>
12429
12430 <p>Conversions between UTF-16be and UTF-16le are always done in place and do
12431 not invalidate a prior pointer, though of course the content of the buffer
12432 that the prior pointer references will have been modified. Other kinds
12433 of conversion are done in place when it is possible, but sometimes they
12434 are not possible and in those cases prior pointers are invalidated.</p>
12435
12436 <p>The safest policy is to invoke these routines
12437 in one of the following ways:</p>
12438
12439 <p><ul>
12440 <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
12441 <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
12442 <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
12443 </ul></p>
12444
12445 <p>In other words, you should call sqlite3_column_text(),
12446 sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
12447 into the desired format, then invoke sqlite3_column_bytes() or
12448 sqlite3_column_bytes16() to find the size of the result. Do not mix calls
12449 to sqlite3_column_text() or sqlite3_column_blob() with calls to
12450 sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
12451 with calls to sqlite3_column_bytes().</p>
12452
12453 <p>The pointers returned are valid until a type conversion occurs as
12454 described above, or until <a href="#sqlite3_step">sqlite3_step()</a> or <a href="#sqlite3_reset">sqlite3_reset()</a> or
12455 <a href="#sqlite3_finalize">sqlite3_finalize()</a> is called. The memory space used to hold strings
12456 and BLOBs is freed automatically. Do not pass the pointers returned
12457 from <a href="#sqlite3_column_blob">sqlite3_column_blob()</a>, <a href="#sqlite3_column_blob">sqlite3_column_text()</a>, etc. into
12458 <a href="#sqlite3_free">sqlite3_free()</a>.</p>
12459
12460 <p>As long as the input parameters are correct, these routines will only
12461 fail if an out-of-memory error occurs during a format conversion.
12462 Only the following subset of interfaces are subject to out-of-memory
12463 errors:</p>
12464
12465 <p><ul>
12466 <li> sqlite3_column_blob()
12467 <li> sqlite3_column_text()
12468 <li> sqlite3_column_text16()
12469 <li> sqlite3_column_bytes()
12470 <li> sqlite3_column_bytes16()
12471 </ul></p>
12472
12473 <p>If an out-of-memory error occurs, then the return value from these
12474 routines is the same as if the column had contained an SQL NULL value.
12475 Valid SQL NULL returns can be distinguished from out-of-memory errors
12476 by invoking the <a href="#sqlite3_errcode">sqlite3_errcode()</a> immediately after the suspect
12477 return value is obtained and before any
12478 other SQLite interface is called on the same <a href="#sqlite3">database connection</a>.
12479 </p><hr><a name="sqlite3_file_control"></a>
12480 <h2>Low-Level Control Of Database Files</h2>
12481 </div>
12482 <blockquote><pre>
12483 int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
12484 </pre></blockquote>
12485 <p>
12486 The <a href="#sqlite3_file_control">sqlite3_file_control()</a> interface makes a direct call to the
12487 xFileControl method for the <a href="#sqlite3_io_methods">sqlite3_io_methods</a> object associated
12488 with a particular database identified by the second argument. The
12489 name of the database is "main" for the main database or "temp" for the
12490 TEMP database, or the name that appears after the AS keyword for
12491 databases that are added using the <a href="lang_attach.html">ATTACH</a> SQL command.
12492 A NULL pointer can be used in place of "main" to refer to the
12493 main database file.
12494 The third and fourth parameters to this routine
12495 are passed directly through to the second and third parameters of
12496 the xFileControl method. The return value of the xFileControl
12497 method becomes the return value of this routine.</p>
12498
12499 <p>A few opcodes for <a href="#sqlite3_file_control">sqlite3_file_control()</a> are handled directly
12500 by the SQLite core and never invoke the
12501 sqlite3_io_methods.xFileControl method.
12502 The <a href="#sqlitefcntlfilepointer">SQLITE_FCNTL_FILE_POINTER</a> value for the op parameter causes
12503 a pointer to the underlying <a href="#sqlite3_file">sqlite3_file</a> object to be written into
12504 the space pointed to by the 4th parameter. The
12505 <a href="#sqlitefcntljournalpointer">SQLITE_FCNTL_JOURNAL_POINTER</a> works similarly except that it returns
12506 the <a href="#sqlite3_file">sqlite3_file</a> object associated with the journal file instead of
12507 the main database. The <a href="#sqlitefcntlvfspointer">SQLITE_FCNTL_VFS_POINTER</a> opcode returns
12508 a pointer to the underlying <a href="#sqlite3_vfs">sqlite3_vfs</a> object for the file.
12509 The <a href="#sqlitefcntldataversion">SQLITE_FCNTL_DATA_VERSION</a> returns the data version counter
12510 from the pager.</p>
12511
12512 <p>If the second parameter (zDbName) does not match the name of any
12513 open database file, then SQLITE_ERROR is returned. This error
12514 code is not remembered and will not be recalled by <a href="#sqlite3_errcode">sqlite3_errcode()</a>
12515 or <a href="#sqlite3_errcode">sqlite3_errmsg()</a>. The underlying xFileControl method might
12516 also return SQLITE_ERROR. There is no way to distinguish between
12517 an incorrect zDbName and an SQLITE_ERROR return from the underlying
12518 xFileControl method.</p>
12519
12520 <p>See also: <a href="#SQLITE_FCNTL_BEGIN_ATOMIC_WRITE">file control opcodes</a>
12521 </p><hr><a name="sqlite3_create_function"></a>
12522 <h2>Create Or Redefine SQL Functions</h2>
12523 </div>
12524 <blockquote><pre>
12525 int sqlite3_create_function(
12526 sqlite3 *db,
12527 const char *zFunctionName,
12528 int nArg,
12529 int eTextRep,
12530 void *pApp,
12531 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
12532 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
12533 void (*xFinal)(sqlite3_context*)
12534 );
12535 int sqlite3_create_function16(
12536 sqlite3 *db,
12537 const void *zFunctionName,
12538 int nArg,
12539 int eTextRep,
12540 void *pApp,
12541 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
12542 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
12543 void (*xFinal)(sqlite3_context*)
12544 );
12545 int sqlite3_create_function_v2(
12546 sqlite3 *db,
12547 const char *zFunctionName,
12548 int nArg,
12549 int eTextRep,
12550 void *pApp,
12551 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
12552 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
12553 void (*xFinal)(sqlite3_context*),
12554 void(*xDestroy)(void*)
12555 );
12556 int sqlite3_create_window_function(
12557 sqlite3 *db,
12558 const char *zFunctionName,
12559 int nArg,
12560 int eTextRep,
12561 void *pApp,
12562 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
12563 void (*xFinal)(sqlite3_context*),
12564 void (*xValue)(sqlite3_context*),
12565 void (*xInverse)(sqlite3_context*,int,sqlite3_value**),
12566 void(*xDestroy)(void*)
12567 );
12568 </pre></blockquote>
12569 <p>
12570 These functions (collectively known as "function creation routines")
12571 are used to add SQL functions or aggregates or to redefine the behavior
12572 of existing SQL functions or aggregates. The only differences between
12573 the three "sqlite3_create_function*" routines are the text encoding
12574 expected for the second parameter (the name of the function being
12575 created) and the presence or absence of a destructor callback for
12576 the application data pointer. Function sqlite3_create_window_function()
12577 is similar, but allows the user to supply the extra callback functions
12578 needed by <a href="windowfunctions.html#aggwinfunc">aggregate window functions</a>.</p>
12579
12580 <p>The first parameter is the <a href="#sqlite3">database connection</a> to which the SQL
12581 function is to be added. If an application uses more than one database
12582 connection then application-defined SQL functions must be added
12583 to each database connection separately.</p>
12584
12585 <p>The second parameter is the name of the SQL function to be created or
12586 redefined. The length of the name is limited to 255 bytes in a UTF-8
12587 representation, exclusive of the zero-terminator. Note that the name
12588 length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
12589 Any attempt to create a function with a longer name
12590 will result in <a href="#SQLITE_ABORT">SQLITE_MISUSE</a> being returned.</p>
12591
12592 <p>The third parameter (nArg)
12593 is the number of arguments that the SQL function or
12594 aggregate takes. If this parameter is -1, then the SQL function or
12595 aggregate may take any number of arguments between 0 and the limit
12596 set by <a href="#sqlite3_limit">sqlite3_limit</a>(<a href="#sqlitelimitfunctionarg">SQLITE_LIMIT_FUNCTION_ARG</a>). If the third
12597 parameter is less than -1 or greater than 127 then the behavior is
12598 undefined.</p>
12599
12600 <p>The fourth parameter, eTextRep, specifies what
12601 <a href="#sqliteutf8">text encoding</a> this SQL function prefers for
12602 its parameters. The application should set this parameter to
12603 <a href="#sqliteutf16le">SQLITE_UTF16LE</a> if the function implementation invokes
12604 <a href="#sqlite3_value_blob">sqlite3_value_text16le()</a> on an input, or <a href="#sqliteutf16be">SQLITE_UTF16BE</a> if the
12605 implementation invokes <a href="#sqlite3_value_blob">sqlite3_value_text16be()</a> on an input, or
12606 <a href="#sqliteutf16">SQLITE_UTF16</a> if <a href="#sqlite3_value_blob">sqlite3_value_text16()</a> is used, or <a href="#sqliteutf8">SQLITE_UTF8</a>
12607 otherwise. The same SQL function may be registered multiple times using
12608 different preferred text encodings, with different implementations for
12609 each encoding.
12610 When multiple implementations of the same function are available, SQLite
12611 will pick the one that involves the least amount of data conversion.</p>
12612
12613 <p>The fourth parameter may optionally be ORed with <a href="#sqlitedeterministic">SQLITE_DETERMINISTIC</a>
12614 to signal that the function will always return the same result given
12615 the same inputs within a single SQL statement. Most SQL functions are
12616 deterministic. The built-in <a href="lang_corefunc.html#random">random()</a> SQL function is an example of a
12617 function that is not deterministic. The SQLite query planner is able to
12618 perform additional optimizations on deterministic functions, so use
12619 of the <a href="#sqlitedeterministic">SQLITE_DETERMINISTIC</a> flag is recommended where possible.</p>
12620
12621 <p>The fourth parameter may also optionally include the <a href="#sqlitedirectonly">SQLITE_DIRECTONLY</a>
12622 flag, which if present prevents the function from being invoked from
12623 within VIEWs, TRIGGERs, CHECK constraints, generated column expressions,
12624 index expressions, or the WHERE clause of partial indexes.</p>
12625
12626 <p>For best security, the <a href="#sqlitedirectonly">SQLITE_DIRECTONLY</a> flag is recommended for
12627 all application-defined SQL functions that do not need to be
12628 used inside of triggers, views, CHECK constraints, or other elements of
12629 the database schema. This flag is especially recommended for SQL
12630 functions that have side effects or reveal internal application state.
12631 Without this flag, an attacker might be able to modify the schema of
12632 a database file to include invocations of the function with parameters
12633 chosen by the attacker, which the application will then execute when
12634 the database file is opened and read.</p>
12635
12636 <p>The fifth parameter is an arbitrary pointer. The implementation of the
12637 function can gain access to this pointer using <a href="#sqlite3_user_data">sqlite3_user_data()</a>.</p>
12638
12639 <p>The sixth, seventh and eighth parameters passed to the three
12640 "sqlite3_create_function*" functions, xFunc, xStep and xFinal, are
12641 pointers to C-language functions that implement the SQL function or
12642 aggregate. A scalar SQL function requires an implementation of the xFunc
12643 callback only; NULL pointers must be passed as the xStep and xFinal
12644 parameters. An aggregate SQL function requires an implementation of xStep
12645 and xFinal and NULL pointer must be passed for xFunc. To delete an existing
12646 SQL function or aggregate, pass NULL pointers for all three function
12647 callbacks.</p>
12648
12649 <p>The sixth, seventh, eighth and ninth parameters (xStep, xFinal, xValue
12650 and xInverse) passed to sqlite3_create_window_function are pointers to
12651 C-language callbacks that implement the new function. xStep and xFinal
12652 must both be non-NULL. xValue and xInverse may either both be NULL, in
12653 which case a regular aggregate function is created, or must both be
12654 non-NULL, in which case the new function may be used as either an aggregate
12655 or aggregate window function. More details regarding the implementation
12656 of aggregate window functions are
12657 <a href="windowfunctions.html#udfwinfunc">available here</a>.</p>
12658
12659 <p>If the final parameter to sqlite3_create_function_v2() or
12660 sqlite3_create_window_function() is not NULL, then it is the destructor for
12661 the application data pointer. The destructor is invoked when the function
12662 is deleted, either by being overloaded or when the database connection
12663 closes. The destructor is also invoked if the call to
12664 sqlite3_create_function_v2() fails. When the destructor callback is
12665 invoked, it is passed a single argument which is a copy of the application
12666 data pointer which was the fifth parameter to sqlite3_create_function_v2().</p>
12667
12668 <p>It is permitted to register multiple implementations of the same
12669 functions with the same name but with either differing numbers of
12670 arguments or differing preferred text encodings. SQLite will use
12671 the implementation that most closely matches the way in which the
12672 SQL function is used. A function implementation with a non-negative
12673 nArg parameter is a better match than a function implementation with
12674 a negative nArg. A function where the preferred text encoding
12675 matches the database encoding is a better
12676 match than a function where the encoding is different.
12677 A function where the encoding difference is between UTF16le and UTF16be
12678 is a closer match than a function where the encoding difference is
12679 between UTF8 and UTF16.</p>
12680
12681 <p>Built-in functions may be overloaded by new application-defined functions.</p>
12682
12683 <p>An application-defined function is permitted to call other
12684 SQLite interfaces. However, such calls must not
12685 close the database connection nor finalize or reset the prepared
12686 statement in which the function is running.
12687 </p><hr>
12688
12689