[pkg] change the build behavior
[pysqlcipher.git] / amalgamation / sqlite3.h
1 /*
2 ** 2001 September 15
3 **
4 ** The author disclaims copyright to this source code.  In place of
5 ** a legal notice, here is a blessing:
6 **
7 **    May you do good and not evil.
8 **    May you find forgiveness for yourself and forgive others.
9 **    May you share freely, never taking more than you give.
10 **
11 *************************************************************************
12 ** This header file defines the interface that the SQLite library
13 ** presents to client programs.  If a C-function, structure, datatype,
14 ** or constant definition does not appear in this file, then it is
15 ** not a published API of SQLite, is subject to change without
16 ** notice, and should not be referenced by programs that use SQLite.
17 **
18 ** Some of the definitions that are in this file are marked as
19 ** "experimental".  Experimental interfaces are normally new
20 ** features recently added to SQLite.  We do not anticipate changes
21 ** to experimental interfaces but reserve the right to make minor changes
22 ** if experience from use "in the wild" suggest such changes are prudent.
23 **
24 ** The official C-language API documentation for SQLite is derived
25 ** from comments in this file.  This file is the authoritative source
26 ** on how SQLite interfaces are supposed to operate.
27 **
28 ** The name of this file under configuration management is "sqlite.h.in".
29 ** The makefile makes some minor changes to this file (such as inserting
30 ** the version number) and changes its name to "sqlite3.h" as
31 ** part of the build process.
32 */
33 #ifndef _SQLITE3_H_
34 #define _SQLITE3_H_
35 #include <stdarg.h>     /* Needed for the definition of va_list */
36
37 /*
38 ** Make sure we can call this stuff from C++.
39 */
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43
44
45 /*
46 ** Provide the ability to override linkage features of the interface.
47 */
48 #ifndef SQLITE_EXTERN
49 # define SQLITE_EXTERN extern
50 #endif
51 #ifndef SQLITE_API
52 # define SQLITE_API
53 #endif
54 #ifndef SQLITE_CDECL
55 # define SQLITE_CDECL
56 #endif
57 #ifndef SQLITE_STDCALL
58 # define SQLITE_STDCALL
59 #endif
60
61 /*
62 ** These no-op macros are used in front of interfaces to mark those
63 ** interfaces as either deprecated or experimental.  New applications
64 ** should not use deprecated interfaces - they are supported for backwards
65 ** compatibility only.  Application writers should be aware that
66 ** experimental interfaces are subject to change in point releases.
67 **
68 ** These macros used to resolve to various kinds of compiler magic that
69 ** would generate warning messages when they were used.  But that
70 ** compiler magic ended up generating such a flurry of bug reports
71 ** that we have taken it all out and gone back to using simple
72 ** noop macros.
73 */
74 #define SQLITE_DEPRECATED
75 #define SQLITE_EXPERIMENTAL
76
77 /*
78 ** Ensure these symbols were not defined by some previous header file.
79 */
80 #ifdef SQLITE_VERSION
81 # undef SQLITE_VERSION
82 #endif
83 #ifdef SQLITE_VERSION_NUMBER
84 # undef SQLITE_VERSION_NUMBER
85 #endif
86
87 /*
88 ** CAPI3REF: Compile-Time Library Version Numbers
89 **
90 ** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
91 ** evaluates to a string literal that is the SQLite version in the
92 ** format "X.Y.Z" where X is the major version number (always 3 for
93 ** SQLite3) and Y is the minor version number and Z is the release number.)^
94 ** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
95 ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
96 ** numbers used in [SQLITE_VERSION].)^
97 ** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
98 ** be larger than the release from which it is derived.  Either Y will
99 ** be held constant and Z will be incremented or else Y will be incremented
100 ** and Z will be reset to zero.
101 **
102 ** Since version 3.6.18, SQLite source code has been stored in the
103 ** <a href="http://www.fossil-scm.org/">Fossil configuration management
104 ** system</a>.  ^The SQLITE_SOURCE_ID macro evaluates to
105 ** a string which identifies a particular check-in of SQLite
106 ** within its configuration management system.  ^The SQLITE_SOURCE_ID
107 ** string contains the date and time of the check-in (UTC) and an SHA1
108 ** hash of the entire source tree.
109 **
110 ** See also: [sqlite3_libversion()],
111 ** [sqlite3_libversion_number()], [sqlite3_sourceid()],
112 ** [sqlite_version()] and [sqlite_source_id()].
113 */
114 #define SQLITE_VERSION        "3.11.0"
115 #define SQLITE_VERSION_NUMBER 3011000
116 #define SQLITE_SOURCE_ID      "2016-02-15 17:29:24 3d862f207e3adc00f78066799ac5a8c282430a5f"
117
118 /*
119 ** CAPI3REF: Run-Time Library Version Numbers
120 ** KEYWORDS: sqlite3_version, sqlite3_sourceid
121 **
122 ** These interfaces provide the same information as the [SQLITE_VERSION],
123 ** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
124 ** but are associated with the library instead of the header file.  ^(Cautious
125 ** programmers might include assert() statements in their application to
126 ** verify that values returned by these interfaces match the macros in
127 ** the header, and thus ensure that the application is
128 ** compiled with matching library and header files.
129 **
130 ** <blockquote><pre>
131 ** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
132 ** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );
133 ** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
134 ** </pre></blockquote>)^
135 **
136 ** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
137 ** macro.  ^The sqlite3_libversion() function returns a pointer to the
138 ** to the sqlite3_version[] string constant.  The sqlite3_libversion()
139 ** function is provided for use in DLLs since DLL users usually do not have
140 ** direct access to string constants within the DLL.  ^The
141 ** sqlite3_libversion_number() function returns an integer equal to
142 ** [SQLITE_VERSION_NUMBER].  ^The sqlite3_sourceid() function returns 
143 ** a pointer to a string constant whose value is the same as the 
144 ** [SQLITE_SOURCE_ID] C preprocessor macro.
145 **
146 ** See also: [sqlite_version()] and [sqlite_source_id()].
147 */
148 SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
149 SQLITE_API const char *SQLITE_STDCALL sqlite3_libversion(void);
150 SQLITE_API const char *SQLITE_STDCALL sqlite3_sourceid(void);
151 SQLITE_API int SQLITE_STDCALL sqlite3_libversion_number(void);
152
153 /*
154 ** CAPI3REF: Run-Time Library Compilation Options Diagnostics
155 **
156 ** ^The sqlite3_compileoption_used() function returns 0 or 1 
157 ** indicating whether the specified option was defined at 
158 ** compile time.  ^The SQLITE_ prefix may be omitted from the 
159 ** option name passed to sqlite3_compileoption_used().  
160 **
161 ** ^The sqlite3_compileoption_get() function allows iterating
162 ** over the list of options that were defined at compile time by
163 ** returning the N-th compile time option string.  ^If N is out of range,
164 ** sqlite3_compileoption_get() returns a NULL pointer.  ^The SQLITE_ 
165 ** prefix is omitted from any strings returned by 
166 ** sqlite3_compileoption_get().
167 **
168 ** ^Support for the diagnostic functions sqlite3_compileoption_used()
169 ** and sqlite3_compileoption_get() may be omitted by specifying the 
170 ** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
171 **
172 ** See also: SQL functions [sqlite_compileoption_used()] and
173 ** [sqlite_compileoption_get()] and the [compile_options pragma].
174 */
175 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
176 SQLITE_API int SQLITE_STDCALL sqlite3_compileoption_used(const char *zOptName);
177 SQLITE_API const char *SQLITE_STDCALL sqlite3_compileoption_get(int N);
178 #endif
179
180 /*
181 ** CAPI3REF: Test To See If The Library Is Threadsafe
182 **
183 ** ^The sqlite3_threadsafe() function returns zero if and only if
184 ** SQLite was compiled with mutexing code omitted due to the
185 ** [SQLITE_THREADSAFE] compile-time option being set to 0.
186 **
187 ** SQLite can be compiled with or without mutexes.  When
188 ** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
189 ** are enabled and SQLite is threadsafe.  When the
190 ** [SQLITE_THREADSAFE] macro is 0, 
191 ** the mutexes are omitted.  Without the mutexes, it is not safe
192 ** to use SQLite concurrently from more than one thread.
193 **
194 ** Enabling mutexes incurs a measurable performance penalty.
195 ** So if speed is of utmost importance, it makes sense to disable
196 ** the mutexes.  But for maximum safety, mutexes should be enabled.
197 ** ^The default behavior is for mutexes to be enabled.
198 **
199 ** This interface can be used by an application to make sure that the
200 ** version of SQLite that it is linking against was compiled with
201 ** the desired setting of the [SQLITE_THREADSAFE] macro.
202 **
203 ** This interface only reports on the compile-time mutex setting
204 ** of the [SQLITE_THREADSAFE] flag.  If SQLite is compiled with
205 ** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
206 ** can be fully or partially disabled using a call to [sqlite3_config()]
207 ** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
208 ** or [SQLITE_CONFIG_SERIALIZED].  ^(The return value of the
209 ** sqlite3_threadsafe() function shows only the compile-time setting of
210 ** thread safety, not any run-time changes to that setting made by
211 ** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
212 ** is unchanged by calls to sqlite3_config().)^
213 **
214 ** See the [threading mode] documentation for additional information.
215 */
216 SQLITE_API int SQLITE_STDCALL sqlite3_threadsafe(void);
217
218 /*
219 ** CAPI3REF: Database Connection Handle
220 ** KEYWORDS: {database connection} {database connections}
221 **
222 ** Each open SQLite database is represented by a pointer to an instance of
223 ** the opaque structure named "sqlite3".  It is useful to think of an sqlite3
224 ** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and
225 ** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
226 ** and [sqlite3_close_v2()] are its destructors.  There are many other
227 ** interfaces (such as
228 ** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
229 ** [sqlite3_busy_timeout()] to name but three) that are methods on an
230 ** sqlite3 object.
231 */
232 typedef struct sqlite3 sqlite3;
233
234 /*
235 ** CAPI3REF: 64-Bit Integer Types
236 ** KEYWORDS: sqlite_int64 sqlite_uint64
237 **
238 ** Because there is no cross-platform way to specify 64-bit integer types
239 ** SQLite includes typedefs for 64-bit signed and unsigned integers.
240 **
241 ** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
242 ** The sqlite_int64 and sqlite_uint64 types are supported for backwards
243 ** compatibility only.
244 **
245 ** ^The sqlite3_int64 and sqlite_int64 types can store integer values
246 ** between -9223372036854775808 and +9223372036854775807 inclusive.  ^The
247 ** sqlite3_uint64 and sqlite_uint64 types can store integer values 
248 ** between 0 and +18446744073709551615 inclusive.
249 */
250 #ifdef SQLITE_INT64_TYPE
251   typedef SQLITE_INT64_TYPE sqlite_int64;
252   typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
253 #elif defined(_MSC_VER) || defined(__BORLANDC__)
254   typedef __int64 sqlite_int64;
255   typedef unsigned __int64 sqlite_uint64;
256 #else
257   typedef long long int sqlite_int64;
258   typedef unsigned long long int sqlite_uint64;
259 #endif
260 typedef sqlite_int64 sqlite3_int64;
261 typedef sqlite_uint64 sqlite3_uint64;
262
263 /*
264 ** If compiling for a processor that lacks floating point support,
265 ** substitute integer for floating-point.
266 */
267 #ifdef SQLITE_OMIT_FLOATING_POINT
268 # define double sqlite3_int64
269 #endif
270
271 /*
272 ** CAPI3REF: Closing A Database Connection
273 ** DESTRUCTOR: sqlite3
274 **
275 ** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
276 ** for the [sqlite3] object.
277 ** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if
278 ** the [sqlite3] object is successfully destroyed and all associated
279 ** resources are deallocated.
280 **
281 ** ^If the database connection is associated with unfinalized prepared
282 ** statements or unfinished sqlite3_backup objects then sqlite3_close()
283 ** will leave the database connection open and return [SQLITE_BUSY].
284 ** ^If sqlite3_close_v2() is called with unfinalized prepared statements
285 ** and/or unfinished sqlite3_backups, then the database connection becomes
286 ** an unusable "zombie" which will automatically be deallocated when the
287 ** last prepared statement is finalized or the last sqlite3_backup is
288 ** finished.  The sqlite3_close_v2() interface is intended for use with
289 ** host languages that are garbage collected, and where the order in which
290 ** destructors are called is arbitrary.
291 **
292 ** Applications should [sqlite3_finalize | finalize] all [prepared statements],
293 ** [sqlite3_blob_close | close] all [BLOB handles], and 
294 ** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated
295 ** with the [sqlite3] object prior to attempting to close the object.  ^If
296 ** sqlite3_close_v2() is called on a [database connection] that still has
297 ** outstanding [prepared statements], [BLOB handles], and/or
298 ** [sqlite3_backup] objects then it returns [SQLITE_OK] and the deallocation
299 ** of resources is deferred until all [prepared statements], [BLOB handles],
300 ** and [sqlite3_backup] objects are also destroyed.
301 **
302 ** ^If an [sqlite3] object is destroyed while a transaction is open,
303 ** the transaction is automatically rolled back.
304 **
305 ** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]
306 ** must be either a NULL
307 ** pointer or an [sqlite3] object pointer obtained
308 ** from [sqlite3_open()], [sqlite3_open16()], or
309 ** [sqlite3_open_v2()], and not previously closed.
310 ** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
311 ** argument is a harmless no-op.
312 */
313 SQLITE_API int SQLITE_STDCALL sqlite3_close(sqlite3*);
314 SQLITE_API int SQLITE_STDCALL sqlite3_close_v2(sqlite3*);
315
316 /*
317 ** The type for a callback function.
318 ** This is legacy and deprecated.  It is included for historical
319 ** compatibility and is not documented.
320 */
321 typedef int (*sqlite3_callback)(void*,int,char**, char**);
322
323 /*
324 ** CAPI3REF: One-Step Query Execution Interface
325 ** METHOD: sqlite3
326 **
327 ** The sqlite3_exec() interface is a convenience wrapper around
328 ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
329 ** that allows an application to run multiple statements of SQL
330 ** without having to use a lot of C code. 
331 **
332 ** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
333 ** semicolon-separate SQL statements passed into its 2nd argument,
334 ** in the context of the [database connection] passed in as its 1st
335 ** argument.  ^If the callback function of the 3rd argument to
336 ** sqlite3_exec() is not NULL, then it is invoked for each result row
337 ** coming out of the evaluated SQL statements.  ^The 4th argument to
338 ** sqlite3_exec() is relayed through to the 1st argument of each
339 ** callback invocation.  ^If the callback pointer to sqlite3_exec()
340 ** is NULL, then no callback is ever invoked and result rows are
341 ** ignored.
342 **
343 ** ^If an error occurs while evaluating the SQL statements passed into
344 ** sqlite3_exec(), then execution of the current statement stops and
345 ** subsequent statements are skipped.  ^If the 5th parameter to sqlite3_exec()
346 ** is not NULL then any error message is written into memory obtained
347 ** from [sqlite3_malloc()] and passed back through the 5th parameter.
348 ** To avoid memory leaks, the application should invoke [sqlite3_free()]
349 ** on error message strings returned through the 5th parameter of
350 ** sqlite3_exec() after the error message string is no longer needed.
351 ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
352 ** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
353 ** NULL before returning.
354 **
355 ** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
356 ** routine returns SQLITE_ABORT without invoking the callback again and
357 ** without running any subsequent SQL statements.
358 **
359 ** ^The 2nd argument to the sqlite3_exec() callback function is the
360 ** number of columns in the result.  ^The 3rd argument to the sqlite3_exec()
361 ** callback is an array of pointers to strings obtained as if from
362 ** [sqlite3_column_text()], one for each column.  ^If an element of a
363 ** result row is NULL then the corresponding string pointer for the
364 ** sqlite3_exec() callback is a NULL pointer.  ^The 4th argument to the
365 ** sqlite3_exec() callback is an array of pointers to strings where each
366 ** entry represents the name of corresponding result column as obtained
367 ** from [sqlite3_column_name()].
368 **
369 ** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
370 ** to an empty string, or a pointer that contains only whitespace and/or 
371 ** SQL comments, then no SQL statements are evaluated and the database
372 ** is not changed.
373 **
374 ** Restrictions:
375 **
376 ** <ul>
377 ** <li> The application must ensure that the 1st parameter to sqlite3_exec()
378 **      is a valid and open [database connection].
379 ** <li> The application must not close the [database connection] specified by
380 **      the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
381 ** <li> The application must not modify the SQL statement text passed into
382 **      the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
383 ** </ul>
384 */
385 SQLITE_API int SQLITE_STDCALL sqlite3_exec(
386   sqlite3*,                                  /* An open database */
387   const char *sql,                           /* SQL to be evaluated */
388   int (*callback)(void*,int,char**,char**),  /* Callback function */
389   void *,                                    /* 1st argument to callback */
390   char **errmsg                              /* Error msg written here */
391 );
392
393 /*
394 ** CAPI3REF: Result Codes
395 ** KEYWORDS: {result code definitions}
396 **
397 ** Many SQLite functions return an integer result code from the set shown
398 ** here in order to indicate success or failure.
399 **
400 ** New error codes may be added in future versions of SQLite.
401 **
402 ** See also: [extended result code definitions]
403 */
404 #define SQLITE_OK           0   /* Successful result */
405 /* beginning-of-error-codes */
406 #define SQLITE_ERROR        1   /* SQL error or missing database */
407 #define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
408 #define SQLITE_PERM         3   /* Access permission denied */
409 #define SQLITE_ABORT        4   /* Callback routine requested an abort */
410 #define SQLITE_BUSY         5   /* The database file is locked */
411 #define SQLITE_LOCKED       6   /* A table in the database is locked */
412 #define SQLITE_NOMEM        7   /* A malloc() failed */
413 #define SQLITE_READONLY     8   /* Attempt to write a readonly database */
414 #define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
415 #define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
416 #define SQLITE_CORRUPT     11   /* The database disk image is malformed */
417 #define SQLITE_NOTFOUND    12   /* Unknown opcode in sqlite3_file_control() */
418 #define SQLITE_FULL        13   /* Insertion failed because database is full */
419 #define SQLITE_CANTOPEN    14   /* Unable to open the database file */
420 #define SQLITE_PROTOCOL    15   /* Database lock protocol error */
421 #define SQLITE_EMPTY       16   /* Database is empty */
422 #define SQLITE_SCHEMA      17   /* The database schema changed */
423 #define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
424 #define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
425 #define SQLITE_MISMATCH    20   /* Data type mismatch */
426 #define SQLITE_MISUSE      21   /* Library used incorrectly */
427 #define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
428 #define SQLITE_AUTH        23   /* Authorization denied */
429 #define SQLITE_FORMAT      24   /* Auxiliary database format error */
430 #define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
431 #define SQLITE_NOTADB      26   /* File opened that is not a database file */
432 #define SQLITE_NOTICE      27   /* Notifications from sqlite3_log() */
433 #define SQLITE_WARNING     28   /* Warnings from sqlite3_log() */
434 #define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
435 #define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
436 /* end-of-error-codes */
437
438 /*
439 ** CAPI3REF: Extended Result Codes
440 ** KEYWORDS: {extended result code definitions}
441 **
442 ** In its default configuration, SQLite API routines return one of 30 integer
443 ** [result codes].  However, experience has shown that many of
444 ** these result codes are too coarse-grained.  They do not provide as
445 ** much information about problems as programmers might like.  In an effort to
446 ** address this, newer versions of SQLite (version 3.3.8 and later) include
447 ** support for additional result codes that provide more detailed information
448 ** about errors. These [extended result codes] are enabled or disabled
449 ** on a per database connection basis using the
450 ** [sqlite3_extended_result_codes()] API.  Or, the extended code for
451 ** the most recent error can be obtained using
452 ** [sqlite3_extended_errcode()].
453 */
454 #define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))
455 #define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))
456 #define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))
457 #define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))
458 #define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))
459 #define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))
460 #define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7<<8))
461 #define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8<<8))
462 #define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9<<8))
463 #define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10<<8))
464 #define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11<<8))
465 #define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12<<8))
466 #define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))
467 #define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
468 #define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))
469 #define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))
470 #define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))
471 #define SQLITE_IOERR_SHMOPEN           (SQLITE_IOERR | (18<<8))
472 #define SQLITE_IOERR_SHMSIZE           (SQLITE_IOERR | (19<<8))
473 #define SQLITE_IOERR_SHMLOCK           (SQLITE_IOERR | (20<<8))
474 #define SQLITE_IOERR_SHMMAP            (SQLITE_IOERR | (21<<8))
475 #define SQLITE_IOERR_SEEK              (SQLITE_IOERR | (22<<8))
476 #define SQLITE_IOERR_DELETE_NOENT      (SQLITE_IOERR | (23<<8))
477 #define SQLITE_IOERR_MMAP              (SQLITE_IOERR | (24<<8))
478 #define SQLITE_IOERR_GETTEMPPATH       (SQLITE_IOERR | (25<<8))
479 #define SQLITE_IOERR_CONVPATH          (SQLITE_IOERR | (26<<8))
480 #define SQLITE_IOERR_VNODE             (SQLITE_IOERR | (27<<8))
481 #define SQLITE_IOERR_AUTH              (SQLITE_IOERR | (28<<8))
482 #define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED |  (1<<8))
483 #define SQLITE_BUSY_RECOVERY           (SQLITE_BUSY   |  (1<<8))
484 #define SQLITE_BUSY_SNAPSHOT           (SQLITE_BUSY   |  (2<<8))
485 #define SQLITE_CANTOPEN_NOTEMPDIR      (SQLITE_CANTOPEN | (1<<8))
486 #define SQLITE_CANTOPEN_ISDIR          (SQLITE_CANTOPEN | (2<<8))
487 #define SQLITE_CANTOPEN_FULLPATH       (SQLITE_CANTOPEN | (3<<8))
488 #define SQLITE_CANTOPEN_CONVPATH       (SQLITE_CANTOPEN | (4<<8))
489 #define SQLITE_CORRUPT_VTAB            (SQLITE_CORRUPT | (1<<8))
490 #define SQLITE_READONLY_RECOVERY       (SQLITE_READONLY | (1<<8))
491 #define SQLITE_READONLY_CANTLOCK       (SQLITE_READONLY | (2<<8))
492 #define SQLITE_READONLY_ROLLBACK       (SQLITE_READONLY | (3<<8))
493 #define SQLITE_READONLY_DBMOVED        (SQLITE_READONLY | (4<<8))
494 #define SQLITE_ABORT_ROLLBACK          (SQLITE_ABORT | (2<<8))
495 #define SQLITE_CONSTRAINT_CHECK        (SQLITE_CONSTRAINT | (1<<8))
496 #define SQLITE_CONSTRAINT_COMMITHOOK   (SQLITE_CONSTRAINT | (2<<8))
497 #define SQLITE_CONSTRAINT_FOREIGNKEY   (SQLITE_CONSTRAINT | (3<<8))
498 #define SQLITE_CONSTRAINT_FUNCTION     (SQLITE_CONSTRAINT | (4<<8))
499 #define SQLITE_CONSTRAINT_NOTNULL      (SQLITE_CONSTRAINT | (5<<8))
500 #define SQLITE_CONSTRAINT_PRIMARYKEY   (SQLITE_CONSTRAINT | (6<<8))
501 #define SQLITE_CONSTRAINT_TRIGGER      (SQLITE_CONSTRAINT | (7<<8))
502 #define SQLITE_CONSTRAINT_UNIQUE       (SQLITE_CONSTRAINT | (8<<8))
503 #define SQLITE_CONSTRAINT_VTAB         (SQLITE_CONSTRAINT | (9<<8))
504 #define SQLITE_CONSTRAINT_ROWID        (SQLITE_CONSTRAINT |(10<<8))
505 #define SQLITE_NOTICE_RECOVER_WAL      (SQLITE_NOTICE | (1<<8))
506 #define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
507 #define SQLITE_WARNING_AUTOINDEX       (SQLITE_WARNING | (1<<8))
508 #define SQLITE_AUTH_USER               (SQLITE_AUTH | (1<<8))
509
510 /*
511 ** CAPI3REF: Flags For File Open Operations
512 **
513 ** These bit values are intended for use in the
514 ** 3rd parameter to the [sqlite3_open_v2()] interface and
515 ** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
516 */
517 #define SQLITE_OPEN_READONLY         0x00000001  /* Ok for sqlite3_open_v2() */
518 #define SQLITE_OPEN_READWRITE        0x00000002  /* Ok for sqlite3_open_v2() */
519 #define SQLITE_OPEN_CREATE           0x00000004  /* Ok for sqlite3_open_v2() */
520 #define SQLITE_OPEN_DELETEONCLOSE    0x00000008  /* VFS only */
521 #define SQLITE_OPEN_EXCLUSIVE        0x00000010  /* VFS only */
522 #define SQLITE_OPEN_AUTOPROXY        0x00000020  /* VFS only */
523 #define SQLITE_OPEN_URI              0x00000040  /* Ok for sqlite3_open_v2() */
524 #define SQLITE_OPEN_MEMORY           0x00000080  /* Ok for sqlite3_open_v2() */
525 #define SQLITE_OPEN_MAIN_DB          0x00000100  /* VFS only */
526 #define SQLITE_OPEN_TEMP_DB          0x00000200  /* VFS only */
527 #define SQLITE_OPEN_TRANSIENT_DB     0x00000400  /* VFS only */
528 #define SQLITE_OPEN_MAIN_JOURNAL     0x00000800  /* VFS only */
529 #define SQLITE_OPEN_TEMP_JOURNAL     0x00001000  /* VFS only */
530 #define SQLITE_OPEN_SUBJOURNAL       0x00002000  /* VFS only */
531 #define SQLITE_OPEN_MASTER_JOURNAL   0x00004000  /* VFS only */
532 #define SQLITE_OPEN_NOMUTEX          0x00008000  /* Ok for sqlite3_open_v2() */
533 #define SQLITE_OPEN_FULLMUTEX        0x00010000  /* Ok for sqlite3_open_v2() */
534 #define SQLITE_OPEN_SHAREDCACHE      0x00020000  /* Ok for sqlite3_open_v2() */
535 #define SQLITE_OPEN_PRIVATECACHE     0x00040000  /* Ok for sqlite3_open_v2() */
536 #define SQLITE_OPEN_WAL              0x00080000  /* VFS only */
537
538 /* Reserved:                         0x00F00000 */
539
540 /*
541 ** CAPI3REF: Device Characteristics
542 **
543 ** The xDeviceCharacteristics method of the [sqlite3_io_methods]
544 ** object returns an integer which is a vector of these
545 ** bit values expressing I/O characteristics of the mass storage
546 ** device that holds the file that the [sqlite3_io_methods]
547 ** refers to.
548 **
549 ** The SQLITE_IOCAP_ATOMIC property means that all writes of
550 ** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
551 ** mean that writes of blocks that are nnn bytes in size and
552 ** are aligned to an address which is an integer multiple of
553 ** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
554 ** that when data is appended to a file, the data is appended
555 ** first then the size of the file is extended, never the other
556 ** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
557 ** information is written to disk in the same order as calls
558 ** to xWrite().  The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
559 ** after reboot following a crash or power loss, the only bytes in a
560 ** file that were written at the application level might have changed
561 ** and that adjacent bytes, even bytes within the same sector are
562 ** guaranteed to be unchanged.  The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
563 ** flag indicate that a file cannot be deleted when open.  The
564 ** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
565 ** read-only media and cannot be changed even by processes with
566 ** elevated privileges.
567 */
568 #define SQLITE_IOCAP_ATOMIC                 0x00000001
569 #define SQLITE_IOCAP_ATOMIC512              0x00000002
570 #define SQLITE_IOCAP_ATOMIC1K               0x00000004
571 #define SQLITE_IOCAP_ATOMIC2K               0x00000008
572 #define SQLITE_IOCAP_ATOMIC4K               0x00000010
573 #define SQLITE_IOCAP_ATOMIC8K               0x00000020
574 #define SQLITE_IOCAP_ATOMIC16K              0x00000040
575 #define SQLITE_IOCAP_ATOMIC32K              0x00000080
576 #define SQLITE_IOCAP_ATOMIC64K              0x00000100
577 #define SQLITE_IOCAP_SAFE_APPEND            0x00000200
578 #define SQLITE_IOCAP_SEQUENTIAL             0x00000400
579 #define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN  0x00000800
580 #define SQLITE_IOCAP_POWERSAFE_OVERWRITE    0x00001000
581 #define SQLITE_IOCAP_IMMUTABLE              0x00002000
582
583 /*
584 ** CAPI3REF: File Locking Levels
585 **
586 ** SQLite uses one of these integer values as the second
587 ** argument to calls it makes to the xLock() and xUnlock() methods
588 ** of an [sqlite3_io_methods] object.
589 */
590 #define SQLITE_LOCK_NONE          0
591 #define SQLITE_LOCK_SHARED        1
592 #define SQLITE_LOCK_RESERVED      2
593 #define SQLITE_LOCK_PENDING       3
594 #define SQLITE_LOCK_EXCLUSIVE     4
595
596 /*
597 ** CAPI3REF: Synchronization Type Flags
598 **
599 ** When SQLite invokes the xSync() method of an
600 ** [sqlite3_io_methods] object it uses a combination of
601 ** these integer values as the second argument.
602 **
603 ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
604 ** sync operation only needs to flush data to mass storage.  Inode
605 ** information need not be flushed. If the lower four bits of the flag
606 ** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
607 ** If the lower four bits equal SQLITE_SYNC_FULL, that means
608 ** to use Mac OS X style fullsync instead of fsync().
609 **
610 ** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
611 ** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
612 ** settings.  The [synchronous pragma] determines when calls to the
613 ** xSync VFS method occur and applies uniformly across all platforms.
614 ** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
615 ** energetic or rigorous or forceful the sync operations are and
616 ** only make a difference on Mac OSX for the default SQLite code.
617 ** (Third-party VFS implementations might also make the distinction
618 ** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
619 ** operating systems natively supported by SQLite, only Mac OSX
620 ** cares about the difference.)
621 */
622 #define SQLITE_SYNC_NORMAL        0x00002
623 #define SQLITE_SYNC_FULL          0x00003
624 #define SQLITE_SYNC_DATAONLY      0x00010
625
626 /*
627 ** CAPI3REF: OS Interface Open File Handle
628 **
629 ** An [sqlite3_file] object represents an open file in the 
630 ** [sqlite3_vfs | OS interface layer].  Individual OS interface
631 ** implementations will
632 ** want to subclass this object by appending additional fields
633 ** for their own use.  The pMethods entry is a pointer to an
634 ** [sqlite3_io_methods] object that defines methods for performing
635 ** I/O operations on the open file.
636 */
637 typedef struct sqlite3_file sqlite3_file;
638 struct sqlite3_file {
639   const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */
640 };
641
642 /*
643 ** CAPI3REF: OS Interface File Virtual Methods Object
644 **
645 ** Every file opened by the [sqlite3_vfs.xOpen] method populates an
646 ** [sqlite3_file] object (or, more commonly, a subclass of the
647 ** [sqlite3_file] object) with a pointer to an instance of this object.
648 ** This object defines the methods used to perform various operations
649 ** against the open file represented by the [sqlite3_file] object.
650 **
651 ** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element 
652 ** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
653 ** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed.  The
654 ** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
655 ** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
656 ** to NULL.
657 **
658 ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
659 ** [SQLITE_SYNC_FULL].  The first choice is the normal fsync().
660 ** The second choice is a Mac OS X style fullsync.  The [SQLITE_SYNC_DATAONLY]
661 ** flag may be ORed in to indicate that only the data of the file
662 ** and not its inode needs to be synced.
663 **
664 ** The integer values to xLock() and xUnlock() are one of
665 ** <ul>
666 ** <li> [SQLITE_LOCK_NONE],
667 ** <li> [SQLITE_LOCK_SHARED],
668 ** <li> [SQLITE_LOCK_RESERVED],
669 ** <li> [SQLITE_LOCK_PENDING], or
670 ** <li> [SQLITE_LOCK_EXCLUSIVE].
671 ** </ul>
672 ** xLock() increases the lock. xUnlock() decreases the lock.
673 ** The xCheckReservedLock() method checks whether any database connection,
674 ** either in this process or in some other process, is holding a RESERVED,
675 ** PENDING, or EXCLUSIVE lock on the file.  It returns true
676 ** if such a lock exists and false otherwise.
677 **
678 ** The xFileControl() method is a generic interface that allows custom
679 ** VFS implementations to directly control an open file using the
680 ** [sqlite3_file_control()] interface.  The second "op" argument is an
681 ** integer opcode.  The third argument is a generic pointer intended to
682 ** point to a structure that may contain arguments or space in which to
683 ** write return values.  Potential uses for xFileControl() might be
684 ** functions to enable blocking locks with timeouts, to change the
685 ** locking strategy (for example to use dot-file locks), to inquire
686 ** about the status of a lock, or to break stale locks.  The SQLite
687 ** core reserves all opcodes less than 100 for its own use.
688 ** A [file control opcodes | list of opcodes] less than 100 is available.
689 ** Applications that define a custom xFileControl method should use opcodes
690 ** greater than 100 to avoid conflicts.  VFS implementations should
691 ** return [SQLITE_NOTFOUND] for file control opcodes that they do not
692 ** recognize.
693 **
694 ** The xSectorSize() method returns the sector size of the
695 ** device that underlies the file.  The sector size is the
696 ** minimum write that can be performed without disturbing
697 ** other bytes in the file.  The xDeviceCharacteristics()
698 ** method returns a bit vector describing behaviors of the
699 ** underlying device:
700 **
701 ** <ul>
702 ** <li> [SQLITE_IOCAP_ATOMIC]
703 ** <li> [SQLITE_IOCAP_ATOMIC512]
704 ** <li> [SQLITE_IOCAP_ATOMIC1K]
705 ** <li> [SQLITE_IOCAP_ATOMIC2K]
706 ** <li> [SQLITE_IOCAP_ATOMIC4K]
707 ** <li> [SQLITE_IOCAP_ATOMIC8K]
708 ** <li> [SQLITE_IOCAP_ATOMIC16K]
709 ** <li> [SQLITE_IOCAP_ATOMIC32K]
710 ** <li> [SQLITE_IOCAP_ATOMIC64K]
711 ** <li> [SQLITE_IOCAP_SAFE_APPEND]
712 ** <li> [SQLITE_IOCAP_SEQUENTIAL]
713 ** </ul>
714 **
715 ** The SQLITE_IOCAP_ATOMIC property means that all writes of
716 ** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
717 ** mean that writes of blocks that are nnn bytes in size and
718 ** are aligned to an address which is an integer multiple of
719 ** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
720 ** that when data is appended to a file, the data is appended
721 ** first then the size of the file is extended, never the other
722 ** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
723 ** information is written to disk in the same order as calls
724 ** to xWrite().
725 **
726 ** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
727 ** in the unread portions of the buffer with zeros.  A VFS that
728 ** fails to zero-fill short reads might seem to work.  However,
729 ** failure to zero-fill short reads will eventually lead to
730 ** database corruption.
731 */
732 typedef struct sqlite3_io_methods sqlite3_io_methods;
733 struct sqlite3_io_methods {
734   int iVersion;
735   int (*xClose)(sqlite3_file*);
736   int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
737   int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
738   int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
739   int (*xSync)(sqlite3_file*, int flags);
740   int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
741   int (*xLock)(sqlite3_file*, int);
742   int (*xUnlock)(sqlite3_file*, int);
743   int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
744   int (*xFileControl)(sqlite3_file*, int op, void *pArg);
745   int (*xSectorSize)(sqlite3_file*);
746   int (*xDeviceCharacteristics)(sqlite3_file*);
747   /* Methods above are valid for version 1 */
748   int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
749   int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
750   void (*xShmBarrier)(sqlite3_file*);
751   int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
752   /* Methods above are valid for version 2 */
753   int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
754   int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
755   /* Methods above are valid for version 3 */
756   /* Additional methods may be added in future releases */
757 };
758
759 /*
760 ** CAPI3REF: Standard File Control Opcodes
761 ** KEYWORDS: {file control opcodes} {file control opcode}
762 **
763 ** These integer constants are opcodes for the xFileControl method
764 ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
765 ** interface.
766 **
767 ** <ul>
768 ** <li>[[SQLITE_FCNTL_LOCKSTATE]]
769 ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This
770 ** opcode causes the xFileControl method to write the current state of
771 ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
772 ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
773 ** into an integer that the pArg argument points to. This capability
774 ** is used during testing and is only available when the SQLITE_TEST
775 ** compile-time option is used.
776 **
777 ** <li>[[SQLITE_FCNTL_SIZE_HINT]]
778 ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
779 ** layer a hint of how large the database file will grow to be during the
780 ** current transaction.  This hint is not guaranteed to be accurate but it
781 ** is often close.  The underlying VFS might choose to preallocate database
782 ** file space based on this hint in order to help writes to the database
783 ** file run faster.
784 **
785 ** <li>[[SQLITE_FCNTL_CHUNK_SIZE]]
786 ** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
787 ** extends and truncates the database file in chunks of a size specified
788 ** by the user. The fourth argument to [sqlite3_file_control()] should 
789 ** point to an integer (type int) containing the new chunk-size to use
790 ** for the nominated database. Allocating database file space in large
791 ** chunks (say 1MB at a time), may reduce file-system fragmentation and
792 ** improve performance on some systems.
793 **
794 ** <li>[[SQLITE_FCNTL_FILE_POINTER]]
795 ** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
796 ** to the [sqlite3_file] object associated with a particular database
797 ** connection.  See also [SQLITE_FCNTL_JOURNAL_POINTER].
798 **
799 ** <li>[[SQLITE_FCNTL_JOURNAL_POINTER]]
800 ** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
801 ** to the [sqlite3_file] object associated with the journal file (either
802 ** the [rollback journal] or the [write-ahead log]) for a particular database
803 ** connection.  See also [SQLITE_FCNTL_FILE_POINTER].
804 **
805 ** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
806 ** No longer in use.
807 **
808 ** <li>[[SQLITE_FCNTL_SYNC]]
809 ** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
810 ** sent to the VFS immediately before the xSync method is invoked on a
811 ** database file descriptor. Or, if the xSync method is not invoked 
812 ** because the user has configured SQLite with 
813 ** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place 
814 ** of the xSync method. In most cases, the pointer argument passed with
815 ** this file-control is NULL. However, if the database file is being synced
816 ** as part of a multi-database commit, the argument points to a nul-terminated
817 ** string containing the transactions master-journal file name. VFSes that 
818 ** do not need this signal should silently ignore this opcode. Applications 
819 ** should not call [sqlite3_file_control()] with this opcode as doing so may 
820 ** disrupt the operation of the specialized VFSes that do require it.  
821 **
822 ** <li>[[SQLITE_FCNTL_COMMIT_PHASETWO]]
823 ** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite
824 ** and sent to the VFS after a transaction has been committed immediately
825 ** but before the database is unlocked. VFSes that do not need this signal
826 ** should silently ignore this opcode. Applications should not call
827 ** [sqlite3_file_control()] with this opcode as doing so may disrupt the 
828 ** operation of the specialized VFSes that do require it.  
829 **
830 ** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]]
831 ** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
832 ** retry counts and intervals for certain disk I/O operations for the
833 ** windows [VFS] in order to provide robustness in the presence of
834 ** anti-virus programs.  By default, the windows VFS will retry file read,
835 ** file write, and file delete operations up to 10 times, with a delay
836 ** of 25 milliseconds before the first retry and with the delay increasing
837 ** by an additional 25 milliseconds with each subsequent retry.  This
838 ** opcode allows these two values (10 retries and 25 milliseconds of delay)
839 ** to be adjusted.  The values are changed for all database connections
840 ** within the same process.  The argument is a pointer to an array of two
841 ** integers where the first integer i the new retry count and the second
842 ** integer is the delay.  If either integer is negative, then the setting
843 ** is not changed but instead the prior value of that setting is written
844 ** into the array entry, allowing the current retry settings to be
845 ** interrogated.  The zDbName parameter is ignored.
846 **
847 ** <li>[[SQLITE_FCNTL_PERSIST_WAL]]
848 ** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
849 ** persistent [WAL | Write Ahead Log] setting.  By default, the auxiliary
850 ** write ahead log and shared memory files used for transaction control
851 ** are automatically deleted when the latest connection to the database
852 ** closes.  Setting persistent WAL mode causes those files to persist after
853 ** close.  Persisting the files is useful when other processes that do not
854 ** have write permission on the directory containing the database file want
855 ** to read the database file, as the WAL and shared memory files must exist
856 ** in order for the database to be readable.  The fourth parameter to
857 ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
858 ** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
859 ** WAL mode.  If the integer is -1, then it is overwritten with the current
860 ** WAL persistence setting.
861 **
862 ** <li>[[SQLITE_FCNTL_POWERSAFE_OVERWRITE]]
863 ** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
864 ** persistent "powersafe-overwrite" or "PSOW" setting.  The PSOW setting
865 ** determines the [SQLITE_IOCAP_POWERSAFE_OVERWRITE] bit of the
866 ** xDeviceCharacteristics methods. The fourth parameter to
867 ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
868 ** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
869 ** mode.  If the integer is -1, then it is overwritten with the current
870 ** zero-damage mode setting.
871 **
872 ** <li>[[SQLITE_FCNTL_OVERWRITE]]
873 ** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening
874 ** a write transaction to indicate that, unless it is rolled back for some
875 ** reason, the entire database file will be overwritten by the current 
876 ** transaction. This is used by VACUUM operations.
877 **
878 ** <li>[[SQLITE_FCNTL_VFSNAME]]
879 ** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of
880 ** all [VFSes] in the VFS stack.  The names are of all VFS shims and the
881 ** final bottom-level VFS are written into memory obtained from 
882 ** [sqlite3_malloc()] and the result is stored in the char* variable
883 ** that the fourth parameter of [sqlite3_file_control()] points to.
884 ** The caller is responsible for freeing the memory when done.  As with
885 ** all file-control actions, there is no guarantee that this will actually
886 ** do anything.  Callers should initialize the char* variable to a NULL
887 ** pointer in case this file-control is not implemented.  This file-control
888 ** is intended for diagnostic use only.
889 **
890 ** <li>[[SQLITE_FCNTL_VFS_POINTER]]
891 ** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
892 ** [VFSes] currently in use.  ^(The argument X in
893 ** sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be
894 ** of type "[sqlite3_vfs] **".  This opcodes will set *X
895 ** to a pointer to the top-level VFS.)^
896 ** ^When there are multiple VFS shims in the stack, this opcode finds the
897 ** upper-most shim only.
898 **
899 ** <li>[[SQLITE_FCNTL_PRAGMA]]
900 ** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA] 
901 ** file control is sent to the open [sqlite3_file] object corresponding
902 ** to the database file to which the pragma statement refers. ^The argument
903 ** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
904 ** pointers to strings (char**) in which the second element of the array
905 ** is the name of the pragma and the third element is the argument to the
906 ** pragma or NULL if the pragma has no argument.  ^The handler for an
907 ** [SQLITE_FCNTL_PRAGMA] file control can optionally make the first element
908 ** of the char** argument point to a string obtained from [sqlite3_mprintf()]
909 ** or the equivalent and that string will become the result of the pragma or
910 ** the error message if the pragma fails. ^If the
911 ** [SQLITE_FCNTL_PRAGMA] file control returns [SQLITE_NOTFOUND], then normal 
912 ** [PRAGMA] processing continues.  ^If the [SQLITE_FCNTL_PRAGMA]
913 ** file control returns [SQLITE_OK], then the parser assumes that the
914 ** VFS has handled the PRAGMA itself and the parser generates a no-op
915 ** prepared statement if result string is NULL, or that returns a copy
916 ** of the result string if the string is non-NULL.
917 ** ^If the [SQLITE_FCNTL_PRAGMA] file control returns
918 ** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
919 ** that the VFS encountered an error while handling the [PRAGMA] and the
920 ** compilation of the PRAGMA fails with an error.  ^The [SQLITE_FCNTL_PRAGMA]
921 ** file control occurs at the beginning of pragma statement analysis and so
922 ** it is able to override built-in [PRAGMA] statements.
923 **
924 ** <li>[[SQLITE_FCNTL_BUSYHANDLER]]
925 ** ^The [SQLITE_FCNTL_BUSYHANDLER]
926 ** file-control may be invoked by SQLite on the database file handle
927 ** shortly after it is opened in order to provide a custom VFS with access
928 ** to the connections busy-handler callback. The argument is of type (void **)
929 ** - an array of two (void *) values. The first (void *) actually points
930 ** to a function of type (int (*)(void *)). In order to invoke the connections
931 ** busy-handler, this function should be invoked with the second (void *) in
932 ** the array as the only argument. If it returns non-zero, then the operation
933 ** should be retried. If it returns zero, the custom VFS should abandon the
934 ** current operation.
935 **
936 ** <li>[[SQLITE_FCNTL_TEMPFILENAME]]
937 ** ^Application can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control
938 ** to have SQLite generate a
939 ** temporary filename using the same algorithm that is followed to generate
940 ** temporary filenames for TEMP tables and other internal uses.  The
941 ** argument should be a char** which will be filled with the filename
942 ** written into memory obtained from [sqlite3_malloc()].  The caller should
943 ** invoke [sqlite3_free()] on the result to avoid a memory leak.
944 **
945 ** <li>[[SQLITE_FCNTL_MMAP_SIZE]]
946 ** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the
947 ** maximum number of bytes that will be used for memory-mapped I/O.
948 ** The argument is a pointer to a value of type sqlite3_int64 that
949 ** is an advisory maximum number of bytes in the file to memory map.  The
950 ** pointer is overwritten with the old value.  The limit is not changed if
951 ** the value originally pointed to is negative, and so the current limit 
952 ** can be queried by passing in a pointer to a negative number.  This
953 ** file-control is used internally to implement [PRAGMA mmap_size].
954 **
955 ** <li>[[SQLITE_FCNTL_TRACE]]
956 ** The [SQLITE_FCNTL_TRACE] file control provides advisory information
957 ** to the VFS about what the higher layers of the SQLite stack are doing.
958 ** This file control is used by some VFS activity tracing [shims].
959 ** The argument is a zero-terminated string.  Higher layers in the
960 ** SQLite stack may generate instances of this file control if
961 ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
962 **
963 ** <li>[[SQLITE_FCNTL_HAS_MOVED]]
964 ** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a
965 ** pointer to an integer and it writes a boolean into that integer depending
966 ** on whether or not the file has been renamed, moved, or deleted since it
967 ** was first opened.
968 **
969 ** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]]
970 ** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging.  This
971 ** opcode causes the xFileControl method to swap the file handle with the one
972 ** pointed to by the pArg argument.  This capability is used during testing
973 ** and only needs to be supported when SQLITE_TEST is defined.
974 **
975 ** <li>[[SQLITE_FCNTL_WAL_BLOCK]]
976 ** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might
977 ** be advantageous to block on the next WAL lock if the lock is not immediately
978 ** available.  The WAL subsystem issues this signal during rare
979 ** circumstances in order to fix a problem with priority inversion.
980 ** Applications should <em>not</em> use this file-control.
981 **
982 ** <li>[[SQLITE_FCNTL_ZIPVFS]]
983 ** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other
984 ** VFS should return SQLITE_NOTFOUND for this opcode.
985 **
986 ** <li>[[SQLITE_FCNTL_RBU]]
987 ** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
988 ** the RBU extension only.  All other VFS should return SQLITE_NOTFOUND for
989 ** this opcode.  
990 ** </ul>
991 */
992 #define SQLITE_FCNTL_LOCKSTATE               1
993 #define SQLITE_FCNTL_GET_LOCKPROXYFILE       2
994 #define SQLITE_FCNTL_SET_LOCKPROXYFILE       3
995 #define SQLITE_FCNTL_LAST_ERRNO              4
996 #define SQLITE_FCNTL_SIZE_HINT               5
997 #define SQLITE_FCNTL_CHUNK_SIZE              6
998 #define SQLITE_FCNTL_FILE_POINTER            7
999 #define SQLITE_FCNTL_SYNC_OMITTED            8
1000 #define SQLITE_FCNTL_WIN32_AV_RETRY          9
1001 #define SQLITE_FCNTL_PERSIST_WAL            10
1002 #define SQLITE_FCNTL_OVERWRITE              11
1003 #define SQLITE_FCNTL_VFSNAME                12
1004 #define SQLITE_FCNTL_POWERSAFE_OVERWRITE    13
1005 #define SQLITE_FCNTL_PRAGMA                 14
1006 #define SQLITE_FCNTL_BUSYHANDLER            15
1007 #define SQLITE_FCNTL_TEMPFILENAME           16
1008 #define SQLITE_FCNTL_MMAP_SIZE              18
1009 #define SQLITE_FCNTL_TRACE                  19
1010 #define SQLITE_FCNTL_HAS_MOVED              20
1011 #define SQLITE_FCNTL_SYNC                   21
1012 #define SQLITE_FCNTL_COMMIT_PHASETWO        22
1013 #define SQLITE_FCNTL_WIN32_SET_HANDLE       23
1014 #define SQLITE_FCNTL_WAL_BLOCK              24
1015 #define SQLITE_FCNTL_ZIPVFS                 25
1016 #define SQLITE_FCNTL_RBU                    26
1017 #define SQLITE_FCNTL_VFS_POINTER            27
1018 #define SQLITE_FCNTL_JOURNAL_POINTER        28
1019
1020 /* deprecated names */
1021 #define SQLITE_GET_LOCKPROXYFILE      SQLITE_FCNTL_GET_LOCKPROXYFILE
1022 #define SQLITE_SET_LOCKPROXYFILE      SQLITE_FCNTL_SET_LOCKPROXYFILE
1023 #define SQLITE_LAST_ERRNO             SQLITE_FCNTL_LAST_ERRNO
1024
1025
1026 /*
1027 ** CAPI3REF: Mutex Handle
1028 **
1029 ** The mutex module within SQLite defines [sqlite3_mutex] to be an
1030 ** abstract type for a mutex object.  The SQLite core never looks
1031 ** at the internal representation of an [sqlite3_mutex].  It only
1032 ** deals with pointers to the [sqlite3_mutex] object.
1033 **
1034 ** Mutexes are created using [sqlite3_mutex_alloc()].
1035 */
1036 typedef struct sqlite3_mutex sqlite3_mutex;
1037
1038 /*
1039 ** CAPI3REF: OS Interface Object
1040 **
1041 ** An instance of the sqlite3_vfs object defines the interface between
1042 ** the SQLite core and the underlying operating system.  The "vfs"
1043 ** in the name of the object stands for "virtual file system".  See
1044 ** the [VFS | VFS documentation] for further information.
1045 **
1046 ** The value of the iVersion field is initially 1 but may be larger in
1047 ** future versions of SQLite.  Additional fields may be appended to this
1048 ** object when the iVersion value is increased.  Note that the structure
1049 ** of the sqlite3_vfs object changes in the transaction between
1050 ** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
1051 ** modified.
1052 **
1053 ** The szOsFile field is the size of the subclassed [sqlite3_file]
1054 ** structure used by this VFS.  mxPathname is the maximum length of
1055 ** a pathname in this VFS.
1056 **
1057 ** Registered sqlite3_vfs objects are kept on a linked list formed by
1058 ** the pNext pointer.  The [sqlite3_vfs_register()]
1059 ** and [sqlite3_vfs_unregister()] interfaces manage this list
1060 ** in a thread-safe way.  The [sqlite3_vfs_find()] interface
1061 ** searches the list.  Neither the application code nor the VFS
1062 ** implementation should use the pNext pointer.
1063 **
1064 ** The pNext field is the only field in the sqlite3_vfs
1065 ** structure that SQLite will ever modify.  SQLite will only access
1066 ** or modify this field while holding a particular static mutex.
1067 ** The application should never modify anything within the sqlite3_vfs
1068 ** object once the object has been registered.
1069 **
1070 ** The zName field holds the name of the VFS module.  The name must
1071 ** be unique across all VFS modules.
1072 **
1073 ** [[sqlite3_vfs.xOpen]]
1074 ** ^SQLite guarantees that the zFilename parameter to xOpen
1075 ** is either a NULL pointer or string obtained
1076 ** from xFullPathname() with an optional suffix added.
1077 ** ^If a suffix is added to the zFilename parameter, it will
1078 ** consist of a single "-" character followed by no more than
1079 ** 11 alphanumeric and/or "-" characters.
1080 ** ^SQLite further guarantees that
1081 ** the string will be valid and unchanged until xClose() is
1082 ** called. Because of the previous sentence,
1083 ** the [sqlite3_file] can safely store a pointer to the
1084 ** filename if it needs to remember the filename for some reason.
1085 ** If the zFilename parameter to xOpen is a NULL pointer then xOpen
1086 ** must invent its own temporary name for the file.  ^Whenever the 
1087 ** xFilename parameter is NULL it will also be the case that the
1088 ** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
1089 **
1090 ** The flags argument to xOpen() includes all bits set in
1091 ** the flags argument to [sqlite3_open_v2()].  Or if [sqlite3_open()]
1092 ** or [sqlite3_open16()] is used, then flags includes at least
1093 ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. 
1094 ** If xOpen() opens a file read-only then it sets *pOutFlags to
1095 ** include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be set.
1096 **
1097 ** ^(SQLite will also add one of the following flags to the xOpen()
1098 ** call, depending on the object being opened:
1099 **
1100 ** <ul>
1101 ** <li>  [SQLITE_OPEN_MAIN_DB]
1102 ** <li>  [SQLITE_OPEN_MAIN_JOURNAL]
1103 ** <li>  [SQLITE_OPEN_TEMP_DB]
1104 ** <li>  [SQLITE_OPEN_TEMP_JOURNAL]
1105 ** <li>  [SQLITE_OPEN_TRANSIENT_DB]
1106 ** <li>  [SQLITE_OPEN_SUBJOURNAL]
1107 ** <li>  [SQLITE_OPEN_MASTER_JOURNAL]
1108 ** <li>  [SQLITE_OPEN_WAL]
1109 ** </ul>)^
1110 **
1111 ** The file I/O implementation can use the object type flags to
1112 ** change the way it deals with files.  For example, an application
1113 ** that does not care about crash recovery or rollback might make
1114 ** the open of a journal file a no-op.  Writes to this journal would
1115 ** also be no-ops, and any attempt to read the journal would return
1116 ** SQLITE_IOERR.  Or the implementation might recognize that a database
1117 ** file will be doing page-aligned sector reads and writes in a random
1118 ** order and set up its I/O subsystem accordingly.
1119 **
1120 ** SQLite might also add one of the following flags to the xOpen method:
1121 **
1122 ** <ul>
1123 ** <li> [SQLITE_OPEN_DELETEONCLOSE]
1124 ** <li> [SQLITE_OPEN_EXCLUSIVE]
1125 ** </ul>
1126 **
1127 ** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
1128 ** deleted when it is closed.  ^The [SQLITE_OPEN_DELETEONCLOSE]
1129 ** will be set for TEMP databases and their journals, transient
1130 ** databases, and subjournals.
1131 **
1132 ** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
1133 ** with the [SQLITE_OPEN_CREATE] flag, which are both directly
1134 ** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
1135 ** API.  The SQLITE_OPEN_EXCLUSIVE flag, when paired with the 
1136 ** SQLITE_OPEN_CREATE, is used to indicate that file should always
1137 ** be created, and that it is an error if it already exists.
1138 ** It is <i>not</i> used to indicate the file should be opened 
1139 ** for exclusive access.
1140 **
1141 ** ^At least szOsFile bytes of memory are allocated by SQLite
1142 ** to hold the  [sqlite3_file] structure passed as the third
1143 ** argument to xOpen.  The xOpen method does not have to
1144 ** allocate the structure; it should just fill it in.  Note that
1145 ** the xOpen method must set the sqlite3_file.pMethods to either
1146 ** a valid [sqlite3_io_methods] object or to NULL.  xOpen must do
1147 ** this even if the open fails.  SQLite expects that the sqlite3_file.pMethods
1148 ** element will be valid after xOpen returns regardless of the success
1149 ** or failure of the xOpen call.
1150 **
1151 ** [[sqlite3_vfs.xAccess]]
1152 ** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
1153 ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
1154 ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
1155 ** to test whether a file is at least readable.   The file can be a
1156 ** directory.
1157 **
1158 ** ^SQLite will always allocate at least mxPathname+1 bytes for the
1159 ** output buffer xFullPathname.  The exact size of the output buffer
1160 ** is also passed as a parameter to both  methods. If the output buffer
1161 ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
1162 ** handled as a fatal error by SQLite, vfs implementations should endeavor
1163 ** to prevent this by setting mxPathname to a sufficiently large value.
1164 **
1165 ** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
1166 ** interfaces are not strictly a part of the filesystem, but they are
1167 ** included in the VFS structure for completeness.
1168 ** The xRandomness() function attempts to return nBytes bytes
1169 ** of good-quality randomness into zOut.  The return value is
1170 ** the actual number of bytes of randomness obtained.
1171 ** The xSleep() method causes the calling thread to sleep for at
1172 ** least the number of microseconds given.  ^The xCurrentTime()
1173 ** method returns a Julian Day Number for the current date and time as
1174 ** a floating point value.
1175 ** ^The xCurrentTimeInt64() method returns, as an integer, the Julian
1176 ** Day Number multiplied by 86400000 (the number of milliseconds in 
1177 ** a 24-hour day).  
1178 ** ^SQLite will use the xCurrentTimeInt64() method to get the current
1179 ** date and time if that method is available (if iVersion is 2 or 
1180 ** greater and the function pointer is not NULL) and will fall back
1181 ** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
1182 **
1183 ** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
1184 ** are not used by the SQLite core.  These optional interfaces are provided
1185 ** by some VFSes to facilitate testing of the VFS code. By overriding 
1186 ** system calls with functions under its control, a test program can
1187 ** simulate faults and error conditions that would otherwise be difficult
1188 ** or impossible to induce.  The set of system calls that can be overridden
1189 ** varies from one VFS to another, and from one version of the same VFS to the
1190 ** next.  Applications that use these interfaces must be prepared for any
1191 ** or all of these interfaces to be NULL or for their behavior to change
1192 ** from one release to the next.  Applications must not attempt to access
1193 ** any of these methods if the iVersion of the VFS is less than 3.
1194 */
1195 typedef struct sqlite3_vfs sqlite3_vfs;
1196 typedef void (*sqlite3_syscall_ptr)(void);
1197 struct sqlite3_vfs {
1198   int iVersion;            /* Structure version number (currently 3) */
1199   int szOsFile;            /* Size of subclassed sqlite3_file */
1200   int mxPathname;          /* Maximum file pathname length */
1201   sqlite3_vfs *pNext;      /* Next registered VFS */
1202   const char *zName;       /* Name of this virtual file system */
1203   void *pAppData;          /* Pointer to application-specific data */
1204   int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
1205                int flags, int *pOutFlags);
1206   int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
1207   int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
1208   int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
1209   void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
1210   void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
1211   void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
1212   void (*xDlClose)(sqlite3_vfs*, void*);
1213   int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
1214   int (*xSleep)(sqlite3_vfs*, int microseconds);
1215   int (*xCurrentTime)(sqlite3_vfs*, double*);
1216   int (*xGetLastError)(sqlite3_vfs*, int, char *);
1217   /*
1218   ** The methods above are in version 1 of the sqlite_vfs object
1219   ** definition.  Those that follow are added in version 2 or later
1220   */
1221   int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
1222   /*
1223   ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
1224   ** Those below are for version 3 and greater.
1225   */
1226   int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
1227   sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
1228   const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
1229   /*
1230   ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
1231   ** New fields may be appended in figure versions.  The iVersion
1232   ** value will increment whenever this happens. 
1233   */
1234 };
1235
1236 /*
1237 ** CAPI3REF: Flags for the xAccess VFS method
1238 **
1239 ** These integer constants can be used as the third parameter to
1240 ** the xAccess method of an [sqlite3_vfs] object.  They determine
1241 ** what kind of permissions the xAccess method is looking for.
1242 ** With SQLITE_ACCESS_EXISTS, the xAccess method
1243 ** simply checks whether the file exists.
1244 ** With SQLITE_ACCESS_READWRITE, the xAccess method
1245 ** checks whether the named directory is both readable and writable
1246 ** (in other words, if files can be added, removed, and renamed within
1247 ** the directory).
1248 ** The SQLITE_ACCESS_READWRITE constant is currently used only by the
1249 ** [temp_store_directory pragma], though this could change in a future
1250 ** release of SQLite.
1251 ** With SQLITE_ACCESS_READ, the xAccess method
1252 ** checks whether the file is readable.  The SQLITE_ACCESS_READ constant is
1253 ** currently unused, though it might be used in a future release of
1254 ** SQLite.
1255 */
1256 #define SQLITE_ACCESS_EXISTS    0
1257 #define SQLITE_ACCESS_READWRITE 1   /* Used by PRAGMA temp_store_directory */
1258 #define SQLITE_ACCESS_READ      2   /* Unused */
1259
1260 /*
1261 ** CAPI3REF: Flags for the xShmLock VFS method
1262 **
1263 ** These integer constants define the various locking operations
1264 ** allowed by the xShmLock method of [sqlite3_io_methods].  The
1265 ** following are the only legal combinations of flags to the
1266 ** xShmLock method:
1267 **
1268 ** <ul>
1269 ** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
1270 ** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
1271 ** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
1272 ** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
1273 ** </ul>
1274 **
1275 ** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
1276 ** was given on the corresponding lock.  
1277 **
1278 ** The xShmLock method can transition between unlocked and SHARED or
1279 ** between unlocked and EXCLUSIVE.  It cannot transition between SHARED
1280 ** and EXCLUSIVE.
1281 */
1282 #define SQLITE_SHM_UNLOCK       1
1283 #define SQLITE_SHM_LOCK         2
1284 #define SQLITE_SHM_SHARED       4
1285 #define SQLITE_SHM_EXCLUSIVE    8
1286
1287 /*
1288 ** CAPI3REF: Maximum xShmLock index
1289 **
1290 ** The xShmLock method on [sqlite3_io_methods] may use values
1291 ** between 0 and this upper bound as its "offset" argument.
1292 ** The SQLite core will never attempt to acquire or release a
1293 ** lock outside of this range
1294 */
1295 #define SQLITE_SHM_NLOCK        8
1296
1297
1298 /*
1299 ** CAPI3REF: Initialize The SQLite Library
1300 **
1301 ** ^The sqlite3_initialize() routine initializes the
1302 ** SQLite library.  ^The sqlite3_shutdown() routine
1303 ** deallocates any resources that were allocated by sqlite3_initialize().
1304 ** These routines are designed to aid in process initialization and
1305 ** shutdown on embedded systems.  Workstation applications using
1306 ** SQLite normally do not need to invoke either of these routines.
1307 **
1308 ** A call to sqlite3_initialize() is an "effective" call if it is
1309 ** the first time sqlite3_initialize() is invoked during the lifetime of
1310 ** the process, or if it is the first time sqlite3_initialize() is invoked
1311 ** following a call to sqlite3_shutdown().  ^(Only an effective call
1312 ** of sqlite3_initialize() does any initialization.  All other calls
1313 ** are harmless no-ops.)^
1314 **
1315 ** A call to sqlite3_shutdown() is an "effective" call if it is the first
1316 ** call to sqlite3_shutdown() since the last sqlite3_initialize().  ^(Only
1317 ** an effective call to sqlite3_shutdown() does any deinitialization.
1318 ** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
1319 **
1320 ** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
1321 ** is not.  The sqlite3_shutdown() interface must only be called from a
1322 ** single thread.  All open [database connections] must be closed and all
1323 ** other SQLite resources must be deallocated prior to invoking
1324 ** sqlite3_shutdown().
1325 **
1326 ** Among other things, ^sqlite3_initialize() will invoke
1327 ** sqlite3_os_init().  Similarly, ^sqlite3_shutdown()
1328 ** will invoke sqlite3_os_end().
1329 **
1330 ** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
1331 ** ^If for some reason, sqlite3_initialize() is unable to initialize
1332 ** the library (perhaps it is unable to allocate a needed resource such
1333 ** as a mutex) it returns an [error code] other than [SQLITE_OK].
1334 **
1335 ** ^The sqlite3_initialize() routine is called internally by many other
1336 ** SQLite interfaces so that an application usually does not need to
1337 ** invoke sqlite3_initialize() directly.  For example, [sqlite3_open()]
1338 ** calls sqlite3_initialize() so the SQLite library will be automatically
1339 ** initialized when [sqlite3_open()] is called if it has not be initialized
1340 ** already.  ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
1341 ** compile-time option, then the automatic calls to sqlite3_initialize()
1342 ** are omitted and the application must call sqlite3_initialize() directly
1343 ** prior to using any other SQLite interface.  For maximum portability,
1344 ** it is recommended that applications always invoke sqlite3_initialize()
1345 ** directly prior to using any other SQLite interface.  Future releases
1346 ** of SQLite may require this.  In other words, the behavior exhibited
1347 ** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
1348 ** default behavior in some future release of SQLite.
1349 **
1350 ** The sqlite3_os_init() routine does operating-system specific
1351 ** initialization of the SQLite library.  The sqlite3_os_end()
1352 ** routine undoes the effect of sqlite3_os_init().  Typical tasks
1353 ** performed by these routines include allocation or deallocation
1354 ** of static resources, initialization of global variables,
1355 ** setting up a default [sqlite3_vfs] module, or setting up
1356 ** a default configuration using [sqlite3_config()].
1357 **
1358 ** The application should never invoke either sqlite3_os_init()
1359 ** or sqlite3_os_end() directly.  The application should only invoke
1360 ** sqlite3_initialize() and sqlite3_shutdown().  The sqlite3_os_init()
1361 ** interface is called automatically by sqlite3_initialize() and
1362 ** sqlite3_os_end() is called by sqlite3_shutdown().  Appropriate
1363 ** implementations for sqlite3_os_init() and sqlite3_os_end()
1364 ** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
1365 ** When [custom builds | built for other platforms]
1366 ** (using the [SQLITE_OS_OTHER=1] compile-time
1367 ** option) the application must supply a suitable implementation for
1368 ** sqlite3_os_init() and sqlite3_os_end().  An application-supplied
1369 ** implementation of sqlite3_os_init() or sqlite3_os_end()
1370 ** must return [SQLITE_OK] on success and some other [error code] upon
1371 ** failure.
1372 */
1373 SQLITE_API int SQLITE_STDCALL sqlite3_initialize(void);
1374 SQLITE_API int SQLITE_STDCALL sqlite3_shutdown(void);
1375 SQLITE_API int SQLITE_STDCALL sqlite3_os_init(void);
1376 SQLITE_API int SQLITE_STDCALL sqlite3_os_end(void);
1377
1378 /*
1379 ** CAPI3REF: Configuring The SQLite Library
1380 **
1381 ** The sqlite3_config() interface is used to make global configuration
1382 ** changes to SQLite in order to tune SQLite to the specific needs of
1383 ** the application.  The default configuration is recommended for most
1384 ** applications and so this routine is usually not necessary.  It is
1385 ** provided to support rare applications with unusual needs.
1386 **
1387 ** <b>The sqlite3_config() interface is not threadsafe. The application
1388 ** must ensure that no other SQLite interfaces are invoked by other
1389 ** threads while sqlite3_config() is running.</b>
1390 **
1391 ** The sqlite3_config() interface
1392 ** may only be invoked prior to library initialization using
1393 ** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
1394 ** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
1395 ** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
1396 ** Note, however, that ^sqlite3_config() can be called as part of the
1397 ** implementation of an application-defined [sqlite3_os_init()].
1398 **
1399 ** The first argument to sqlite3_config() is an integer
1400 ** [configuration option] that determines
1401 ** what property of SQLite is to be configured.  Subsequent arguments
1402 ** vary depending on the [configuration option]
1403 ** in the first argument.
1404 **
1405 ** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
1406 ** ^If the option is unknown or SQLite is unable to set the option
1407 ** then this routine returns a non-zero [error code].
1408 */
1409 SQLITE_API int SQLITE_CDECL sqlite3_config(int, ...);
1410
1411 /*
1412 ** CAPI3REF: Configure database connections
1413 ** METHOD: sqlite3
1414 **
1415 ** The sqlite3_db_config() interface is used to make configuration
1416 ** changes to a [database connection].  The interface is similar to
1417 ** [sqlite3_config()] except that the changes apply to a single
1418 ** [database connection] (specified in the first argument).
1419 **
1420 ** The second argument to sqlite3_db_config(D,V,...)  is the
1421 ** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code 
1422 ** that indicates what aspect of the [database connection] is being configured.
1423 ** Subsequent arguments vary depending on the configuration verb.
1424 **
1425 ** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
1426 ** the call is considered successful.
1427 */
1428 SQLITE_API int SQLITE_CDECL sqlite3_db_config(sqlite3*, int op, ...);
1429
1430 /*
1431 ** CAPI3REF: Memory Allocation Routines
1432 **
1433 ** An instance of this object defines the interface between SQLite
1434 ** and low-level memory allocation routines.
1435 **
1436 ** This object is used in only one place in the SQLite interface.
1437 ** A pointer to an instance of this object is the argument to
1438 ** [sqlite3_config()] when the configuration option is
1439 ** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].  
1440 ** By creating an instance of this object
1441 ** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
1442 ** during configuration, an application can specify an alternative
1443 ** memory allocation subsystem for SQLite to use for all of its
1444 ** dynamic memory needs.
1445 **
1446 ** Note that SQLite comes with several [built-in memory allocators]
1447 ** that are perfectly adequate for the overwhelming majority of applications
1448 ** and that this object is only useful to a tiny minority of applications
1449 ** with specialized memory allocation requirements.  This object is
1450 ** also used during testing of SQLite in order to specify an alternative
1451 ** memory allocator that simulates memory out-of-memory conditions in
1452 ** order to verify that SQLite recovers gracefully from such
1453 ** conditions.
1454 **
1455 ** The xMalloc, xRealloc, and xFree methods must work like the
1456 ** malloc(), realloc() and free() functions from the standard C library.
1457 ** ^SQLite guarantees that the second argument to
1458 ** xRealloc is always a value returned by a prior call to xRoundup.
1459 **
1460 ** xSize should return the allocated size of a memory allocation
1461 ** previously obtained from xMalloc or xRealloc.  The allocated size
1462 ** is always at least as big as the requested size but may be larger.
1463 **
1464 ** The xRoundup method returns what would be the allocated size of
1465 ** a memory allocation given a particular requested size.  Most memory
1466 ** allocators round up memory allocations at least to the next multiple
1467 ** of 8.  Some allocators round up to a larger multiple or to a power of 2.
1468 ** Every memory allocation request coming in through [sqlite3_malloc()]
1469 ** or [sqlite3_realloc()] first calls xRoundup.  If xRoundup returns 0, 
1470 ** that causes the corresponding memory allocation to fail.
1471 **
1472 ** The xInit method initializes the memory allocator.  For example,
1473 ** it might allocate any require mutexes or initialize internal data
1474 ** structures.  The xShutdown method is invoked (indirectly) by
1475 ** [sqlite3_shutdown()] and should deallocate any resources acquired
1476 ** by xInit.  The pAppData pointer is used as the only parameter to
1477 ** xInit and xShutdown.
1478 **
1479 ** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes
1480 ** the xInit method, so the xInit method need not be threadsafe.  The
1481 ** xShutdown method is only called from [sqlite3_shutdown()] so it does
1482 ** not need to be threadsafe either.  For all other methods, SQLite
1483 ** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
1484 ** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
1485 ** it is by default) and so the methods are automatically serialized.
1486 ** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
1487 ** methods must be threadsafe or else make their own arrangements for
1488 ** serialization.
1489 **
1490 ** SQLite will never invoke xInit() more than once without an intervening
1491 ** call to xShutdown().
1492 */
1493 typedef struct sqlite3_mem_methods sqlite3_mem_methods;
1494 struct sqlite3_mem_methods {
1495   void *(*xMalloc)(int);         /* Memory allocation function */
1496   void (*xFree)(void*);          /* Free a prior allocation */
1497   void *(*xRealloc)(void*,int);  /* Resize an allocation */
1498   int (*xSize)(void*);           /* Return the size of an allocation */
1499   int (*xRoundup)(int);          /* Round up request size to allocation size */
1500   int (*xInit)(void*);           /* Initialize the memory allocator */
1501   void (*xShutdown)(void*);      /* Deinitialize the memory allocator */
1502   void *pAppData;                /* Argument to xInit() and xShutdown() */
1503 };
1504
1505 /*
1506 ** CAPI3REF: Configuration Options
1507 ** KEYWORDS: {configuration option}
1508 **
1509 ** These constants are the available integer configuration options that
1510 ** can be passed as the first argument to the [sqlite3_config()] interface.
1511 **
1512 ** New configuration options may be added in future releases of SQLite.
1513 ** Existing configuration options might be discontinued.  Applications
1514 ** should check the return code from [sqlite3_config()] to make sure that
1515 ** the call worked.  The [sqlite3_config()] interface will return a
1516 ** non-zero [error code] if a discontinued or unsupported configuration option
1517 ** is invoked.
1518 **
1519 ** <dl>
1520 ** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
1521 ** <dd>There are no arguments to this option.  ^This option sets the
1522 ** [threading mode] to Single-thread.  In other words, it disables
1523 ** all mutexing and puts SQLite into a mode where it can only be used
1524 ** by a single thread.   ^If SQLite is compiled with
1525 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1526 ** it is not possible to change the [threading mode] from its default
1527 ** value of Single-thread and so [sqlite3_config()] will return 
1528 ** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
1529 ** configuration option.</dd>
1530 **
1531 ** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt>
1532 ** <dd>There are no arguments to this option.  ^This option sets the
1533 ** [threading mode] to Multi-thread.  In other words, it disables
1534 ** mutexing on [database connection] and [prepared statement] objects.
1535 ** The application is responsible for serializing access to
1536 ** [database connections] and [prepared statements].  But other mutexes
1537 ** are enabled so that SQLite will be safe to use in a multi-threaded
1538 ** environment as long as no two threads attempt to use the same
1539 ** [database connection] at the same time.  ^If SQLite is compiled with
1540 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1541 ** it is not possible to set the Multi-thread [threading mode] and
1542 ** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1543 ** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
1544 **
1545 ** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt>
1546 ** <dd>There are no arguments to this option.  ^This option sets the
1547 ** [threading mode] to Serialized. In other words, this option enables
1548 ** all mutexes including the recursive
1549 ** mutexes on [database connection] and [prepared statement] objects.
1550 ** In this mode (which is the default when SQLite is compiled with
1551 ** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
1552 ** to [database connections] and [prepared statements] so that the
1553 ** application is free to use the same [database connection] or the
1554 ** same [prepared statement] in different threads at the same time.
1555 ** ^If SQLite is compiled with
1556 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1557 ** it is not possible to set the Serialized [threading mode] and
1558 ** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1559 ** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
1560 **
1561 ** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>
1562 ** <dd> ^(The SQLITE_CONFIG_MALLOC option takes a single argument which is 
1563 ** a pointer to an instance of the [sqlite3_mem_methods] structure.
1564 ** The argument specifies
1565 ** alternative low-level memory allocation routines to be used in place of
1566 ** the memory allocation routines built into SQLite.)^ ^SQLite makes
1567 ** its own private copy of the content of the [sqlite3_mem_methods] structure
1568 ** before the [sqlite3_config()] call returns.</dd>
1569 **
1570 ** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>
1571 ** <dd> ^(The SQLITE_CONFIG_GETMALLOC option takes a single argument which
1572 ** is a pointer to an instance of the [sqlite3_mem_methods] structure.
1573 ** The [sqlite3_mem_methods]
1574 ** structure is filled with the currently defined memory allocation routines.)^
1575 ** This option can be used to overload the default memory allocation
1576 ** routines with a wrapper that simulations memory allocation failure or
1577 ** tracks memory usage, for example. </dd>
1578 **
1579 ** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
1580 ** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
1581 ** interpreted as a boolean, which enables or disables the collection of
1582 ** memory allocation statistics. ^(When memory allocation statistics are
1583 ** disabled, the following SQLite interfaces become non-operational:
1584 **   <ul>
1585 **   <li> [sqlite3_memory_used()]
1586 **   <li> [sqlite3_memory_highwater()]
1587 **   <li> [sqlite3_soft_heap_limit64()]
1588 **   <li> [sqlite3_status64()]
1589 **   </ul>)^
1590 ** ^Memory allocation statistics are enabled by default unless SQLite is
1591 ** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
1592 ** allocation statistics are disabled by default.
1593 ** </dd>
1594 **
1595 ** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
1596 ** <dd> ^The SQLITE_CONFIG_SCRATCH option specifies a static memory buffer
1597 ** that SQLite can use for scratch memory.  ^(There are three arguments
1598 ** to SQLITE_CONFIG_SCRATCH:  A pointer an 8-byte
1599 ** aligned memory buffer from which the scratch allocations will be
1600 ** drawn, the size of each scratch allocation (sz),
1601 ** and the maximum number of scratch allocations (N).)^
1602 ** The first argument must be a pointer to an 8-byte aligned buffer
1603 ** of at least sz*N bytes of memory.
1604 ** ^SQLite will not use more than one scratch buffers per thread.
1605 ** ^SQLite will never request a scratch buffer that is more than 6
1606 ** times the database page size.
1607 ** ^If SQLite needs needs additional
1608 ** scratch memory beyond what is provided by this configuration option, then 
1609 ** [sqlite3_malloc()] will be used to obtain the memory needed.<p>
1610 ** ^When the application provides any amount of scratch memory using
1611 ** SQLITE_CONFIG_SCRATCH, SQLite avoids unnecessary large
1612 ** [sqlite3_malloc|heap allocations].
1613 ** This can help [Robson proof|prevent memory allocation failures] due to heap
1614 ** fragmentation in low-memory embedded systems.
1615 ** </dd>
1616 **
1617 ** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
1618 ** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
1619 ** that SQLite can use for the database page cache with the default page
1620 ** cache implementation.  
1621 ** This configuration option is a no-op if an application-define page
1622 ** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
1623 ** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
1624 ** 8-byte aligned memory (pMem), the size of each page cache line (sz),
1625 ** and the number of cache lines (N).
1626 ** The sz argument should be the size of the largest database page
1627 ** (a power of two between 512 and 65536) plus some extra bytes for each
1628 ** page header.  ^The number of extra bytes needed by the page header
1629 ** can be determined using [SQLITE_CONFIG_PCACHE_HDRSZ].
1630 ** ^It is harmless, apart from the wasted memory,
1631 ** for the sz parameter to be larger than necessary.  The pMem
1632 ** argument must be either a NULL pointer or a pointer to an 8-byte
1633 ** aligned block of memory of at least sz*N bytes, otherwise
1634 ** subsequent behavior is undefined.
1635 ** ^When pMem is not NULL, SQLite will strive to use the memory provided
1636 ** to satisfy page cache needs, falling back to [sqlite3_malloc()] if
1637 ** a page cache line is larger than sz bytes or if all of the pMem buffer
1638 ** is exhausted.
1639 ** ^If pMem is NULL and N is non-zero, then each database connection
1640 ** does an initial bulk allocation for page cache memory
1641 ** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
1642 ** of -1024*N bytes if N is negative, . ^If additional
1643 ** page cache memory is needed beyond what is provided by the initial
1644 ** allocation, then SQLite goes to [sqlite3_malloc()] separately for each
1645 ** additional cache line. </dd>
1646 **
1647 ** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
1648 ** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer 
1649 ** that SQLite will use for all of its dynamic memory allocation needs
1650 ** beyond those provided for by [SQLITE_CONFIG_SCRATCH] and
1651 ** [SQLITE_CONFIG_PAGECACHE].
1652 ** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
1653 ** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
1654 ** [SQLITE_ERROR] if invoked otherwise.
1655 ** ^There are three arguments to SQLITE_CONFIG_HEAP:
1656 ** An 8-byte aligned pointer to the memory,
1657 ** the number of bytes in the memory buffer, and the minimum allocation size.
1658 ** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
1659 ** to using its default memory allocator (the system malloc() implementation),
1660 ** undoing any prior invocation of [SQLITE_CONFIG_MALLOC].  ^If the
1661 ** memory pointer is not NULL then the alternative memory
1662 ** allocator is engaged to handle all of SQLites memory allocation needs.
1663 ** The first pointer (the memory pointer) must be aligned to an 8-byte
1664 ** boundary or subsequent behavior of SQLite will be undefined.
1665 ** The minimum allocation size is capped at 2**12. Reasonable values
1666 ** for the minimum allocation size are 2**5 through 2**8.</dd>
1667 **
1668 ** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
1669 ** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
1670 ** pointer to an instance of the [sqlite3_mutex_methods] structure.
1671 ** The argument specifies alternative low-level mutex routines to be used
1672 ** in place the mutex routines built into SQLite.)^  ^SQLite makes a copy of
1673 ** the content of the [sqlite3_mutex_methods] structure before the call to
1674 ** [sqlite3_config()] returns. ^If SQLite is compiled with
1675 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1676 ** the entire mutexing subsystem is omitted from the build and hence calls to
1677 ** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
1678 ** return [SQLITE_ERROR].</dd>
1679 **
1680 ** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
1681 ** <dd> ^(The SQLITE_CONFIG_GETMUTEX option takes a single argument which
1682 ** is a pointer to an instance of the [sqlite3_mutex_methods] structure.  The
1683 ** [sqlite3_mutex_methods]
1684 ** structure is filled with the currently defined mutex routines.)^
1685 ** This option can be used to overload the default mutex allocation
1686 ** routines with a wrapper used to track mutex usage for performance
1687 ** profiling or testing, for example.   ^If SQLite is compiled with
1688 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1689 ** the entire mutexing subsystem is omitted from the build and hence calls to
1690 ** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
1691 ** return [SQLITE_ERROR].</dd>
1692 **
1693 ** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
1694 ** <dd> ^(The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine
1695 ** the default size of lookaside memory on each [database connection].
1696 ** The first argument is the
1697 ** size of each lookaside buffer slot and the second is the number of
1698 ** slots allocated to each database connection.)^  ^(SQLITE_CONFIG_LOOKASIDE
1699 ** sets the <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
1700 ** option to [sqlite3_db_config()] can be used to change the lookaside
1701 ** configuration on individual connections.)^ </dd>
1702 **
1703 ** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>
1704 ** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is 
1705 ** a pointer to an [sqlite3_pcache_methods2] object.  This object specifies
1706 ** the interface to a custom page cache implementation.)^
1707 ** ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.</dd>
1708 **
1709 ** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
1710 ** <dd> ^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
1711 ** is a pointer to an [sqlite3_pcache_methods2] object.  SQLite copies of
1712 ** the current page cache implementation into that object.)^ </dd>
1713 **
1714 ** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
1715 ** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
1716 ** global [error log].
1717 ** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
1718 ** function with a call signature of void(*)(void*,int,const char*), 
1719 ** and a pointer to void. ^If the function pointer is not NULL, it is
1720 ** invoked by [sqlite3_log()] to process each logging event.  ^If the
1721 ** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
1722 ** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
1723 ** passed through as the first parameter to the application-defined logger
1724 ** function whenever that function is invoked.  ^The second parameter to
1725 ** the logger function is a copy of the first parameter to the corresponding
1726 ** [sqlite3_log()] call and is intended to be a [result code] or an
1727 ** [extended result code].  ^The third parameter passed to the logger is
1728 ** log message after formatting via [sqlite3_snprintf()].
1729 ** The SQLite logging interface is not reentrant; the logger function
1730 ** supplied by the application must not invoke any SQLite interface.
1731 ** In a multi-threaded application, the application-defined logger
1732 ** function must be threadsafe. </dd>
1733 **
1734 ** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
1735 ** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.
1736 ** If non-zero, then URI handling is globally enabled. If the parameter is zero,
1737 ** then URI handling is globally disabled.)^ ^If URI handling is globally
1738 ** enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()],
1739 ** [sqlite3_open16()] or
1740 ** specified as part of [ATTACH] commands are interpreted as URIs, regardless
1741 ** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
1742 ** connection is opened. ^If it is globally disabled, filenames are
1743 ** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
1744 ** database connection is opened. ^(By default, URI handling is globally
1745 ** disabled. The default value may be changed by compiling with the
1746 ** [SQLITE_USE_URI] symbol defined.)^
1747 **
1748 ** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
1749 ** <dd>^The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
1750 ** argument which is interpreted as a boolean in order to enable or disable
1751 ** the use of covering indices for full table scans in the query optimizer.
1752 ** ^The default setting is determined
1753 ** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
1754 ** if that compile-time option is omitted.
1755 ** The ability to disable the use of covering indices for full table scans
1756 ** is because some incorrectly coded legacy applications might malfunction
1757 ** when the optimization is enabled.  Providing the ability to
1758 ** disable the optimization allows the older, buggy application code to work
1759 ** without change even with newer versions of SQLite.
1760 **
1761 ** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]]
1762 ** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
1763 ** <dd> These options are obsolete and should not be used by new code.
1764 ** They are retained for backwards compatibility but are now no-ops.
1765 ** </dd>
1766 **
1767 ** [[SQLITE_CONFIG_SQLLOG]]
1768 ** <dt>SQLITE_CONFIG_SQLLOG
1769 ** <dd>This option is only available if sqlite is compiled with the
1770 ** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should
1771 ** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
1772 ** The second should be of type (void*). The callback is invoked by the library
1773 ** in three separate circumstances, identified by the value passed as the
1774 ** fourth parameter. If the fourth parameter is 0, then the database connection
1775 ** passed as the second argument has just been opened. The third argument
1776 ** points to a buffer containing the name of the main database file. If the
1777 ** fourth parameter is 1, then the SQL statement that the third parameter
1778 ** points to has just been executed. Or, if the fourth parameter is 2, then
1779 ** the connection being passed as the second parameter is being closed. The
1780 ** third parameter is passed NULL In this case.  An example of using this
1781 ** configuration option can be seen in the "test_sqllog.c" source file in
1782 ** the canonical SQLite source tree.</dd>
1783 **
1784 ** [[SQLITE_CONFIG_MMAP_SIZE]]
1785 ** <dt>SQLITE_CONFIG_MMAP_SIZE
1786 ** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
1787 ** that are the default mmap size limit (the default setting for
1788 ** [PRAGMA mmap_size]) and the maximum allowed mmap size limit.
1789 ** ^The default setting can be overridden by each database connection using
1790 ** either the [PRAGMA mmap_size] command, or by using the
1791 ** [SQLITE_FCNTL_MMAP_SIZE] file control.  ^(The maximum allowed mmap size
1792 ** will be silently truncated if necessary so that it does not exceed the
1793 ** compile-time maximum mmap size set by the
1794 ** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
1795 ** ^If either argument to this option is negative, then that argument is
1796 ** changed to its compile-time default.
1797 **
1798 ** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
1799 ** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
1800 ** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
1801 ** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro
1802 ** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
1803 ** that specifies the maximum size of the created heap.
1804 **
1805 ** [[SQLITE_CONFIG_PCACHE_HDRSZ]]
1806 ** <dt>SQLITE_CONFIG_PCACHE_HDRSZ
1807 ** <dd>^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
1808 ** is a pointer to an integer and writes into that integer the number of extra
1809 ** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE].
1810 ** The amount of extra space required can change depending on the compiler,
1811 ** target platform, and SQLite version.
1812 **
1813 ** [[SQLITE_CONFIG_PMASZ]]
1814 ** <dt>SQLITE_CONFIG_PMASZ
1815 ** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which
1816 ** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
1817 ** sorter to that integer.  The default minimum PMA Size is set by the
1818 ** [SQLITE_SORTER_PMASZ] compile-time option.  New threads are launched
1819 ** to help with sort operations when multithreaded sorting
1820 ** is enabled (using the [PRAGMA threads] command) and the amount of content
1821 ** to be sorted exceeds the page size times the minimum of the
1822 ** [PRAGMA cache_size] setting and this value.
1823 ** </dl>
1824 */
1825 #define SQLITE_CONFIG_SINGLETHREAD  1  /* nil */
1826 #define SQLITE_CONFIG_MULTITHREAD   2  /* nil */
1827 #define SQLITE_CONFIG_SERIALIZED    3  /* nil */
1828 #define SQLITE_CONFIG_MALLOC        4  /* sqlite3_mem_methods* */
1829 #define SQLITE_CONFIG_GETMALLOC     5  /* sqlite3_mem_methods* */
1830 #define SQLITE_CONFIG_SCRATCH       6  /* void*, int sz, int N */
1831 #define SQLITE_CONFIG_PAGECACHE     7  /* void*, int sz, int N */
1832 #define SQLITE_CONFIG_HEAP          8  /* void*, int nByte, int min */
1833 #define SQLITE_CONFIG_MEMSTATUS     9  /* boolean */
1834 #define SQLITE_CONFIG_MUTEX        10  /* sqlite3_mutex_methods* */
1835 #define SQLITE_CONFIG_GETMUTEX     11  /* sqlite3_mutex_methods* */
1836 /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ 
1837 #define SQLITE_CONFIG_LOOKASIDE    13  /* int int */
1838 #define SQLITE_CONFIG_PCACHE       14  /* no-op */
1839 #define SQLITE_CONFIG_GETPCACHE    15  /* no-op */
1840 #define SQLITE_CONFIG_LOG          16  /* xFunc, void* */
1841 #define SQLITE_CONFIG_URI          17  /* int */
1842 #define SQLITE_CONFIG_PCACHE2      18  /* sqlite3_pcache_methods2* */
1843 #define SQLITE_CONFIG_GETPCACHE2   19  /* sqlite3_pcache_methods2* */
1844 #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20  /* int */
1845 #define SQLITE_CONFIG_SQLLOG       21  /* xSqllog, void* */
1846 #define SQLITE_CONFIG_MMAP_SIZE    22  /* sqlite3_int64, sqlite3_int64 */
1847 #define SQLITE_CONFIG_WIN32_HEAPSIZE      23  /* int nByte */
1848 #define SQLITE_CONFIG_PCACHE_HDRSZ        24  /* int *psz */
1849 #define SQLITE_CONFIG_PMASZ               25  /* unsigned int szPma */
1850
1851 /*
1852 ** CAPI3REF: Database Connection Configuration Options
1853 **
1854 ** These constants are the available integer configuration options that
1855 ** can be passed as the second argument to the [sqlite3_db_config()] interface.
1856 **
1857 ** New configuration options may be added in future releases of SQLite.
1858 ** Existing configuration options might be discontinued.  Applications
1859 ** should check the return code from [sqlite3_db_config()] to make sure that
1860 ** the call worked.  ^The [sqlite3_db_config()] interface will return a
1861 ** non-zero [error code] if a discontinued or unsupported configuration option
1862 ** is invoked.
1863 **
1864 ** <dl>
1865 ** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
1866 ** <dd> ^This option takes three additional arguments that determine the 
1867 ** [lookaside memory allocator] configuration for the [database connection].
1868 ** ^The first argument (the third parameter to [sqlite3_db_config()] is a
1869 ** pointer to a memory buffer to use for lookaside memory.
1870 ** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
1871 ** may be NULL in which case SQLite will allocate the
1872 ** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
1873 ** size of each lookaside buffer slot.  ^The third argument is the number of
1874 ** slots.  The size of the buffer in the first argument must be greater than
1875 ** or equal to the product of the second and third arguments.  The buffer
1876 ** must be aligned to an 8-byte boundary.  ^If the second argument to
1877 ** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
1878 ** rounded down to the next smaller multiple of 8.  ^(The lookaside memory
1879 ** configuration for a database connection can only be changed when that
1880 ** connection is not currently using lookaside memory, or in other words
1881 ** when the "current value" returned by
1882 ** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
1883 ** Any attempt to change the lookaside memory configuration when lookaside
1884 ** memory is in use leaves the configuration unchanged and returns 
1885 ** [SQLITE_BUSY].)^</dd>
1886 **
1887 ** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
1888 ** <dd> ^This option is used to enable or disable the enforcement of
1889 ** [foreign key constraints].  There should be two additional arguments.
1890 ** The first argument is an integer which is 0 to disable FK enforcement,
1891 ** positive to enable FK enforcement or negative to leave FK enforcement
1892 ** unchanged.  The second parameter is a pointer to an integer into which
1893 ** is written 0 or 1 to indicate whether FK enforcement is off or on
1894 ** following this call.  The second parameter may be a NULL pointer, in
1895 ** which case the FK enforcement setting is not reported back. </dd>
1896 **
1897 ** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
1898 ** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
1899 ** There should be two additional arguments.
1900 ** The first argument is an integer which is 0 to disable triggers,
1901 ** positive to enable triggers or negative to leave the setting unchanged.
1902 ** The second parameter is a pointer to an integer into which
1903 ** is written 0 or 1 to indicate whether triggers are disabled or enabled
1904 ** following this call.  The second parameter may be a NULL pointer, in
1905 ** which case the trigger setting is not reported back. </dd>
1906 **
1907 ** </dl>
1908 */
1909 #define SQLITE_DBCONFIG_LOOKASIDE       1001  /* void* int int */
1910 #define SQLITE_DBCONFIG_ENABLE_FKEY     1002  /* int int* */
1911 #define SQLITE_DBCONFIG_ENABLE_TRIGGER  1003  /* int int* */
1912
1913
1914 /*
1915 ** CAPI3REF: Enable Or Disable Extended Result Codes
1916 ** METHOD: sqlite3
1917 **
1918 ** ^The sqlite3_extended_result_codes() routine enables or disables the
1919 ** [extended result codes] feature of SQLite. ^The extended result
1920 ** codes are disabled by default for historical compatibility.
1921 */
1922 SQLITE_API int SQLITE_STDCALL sqlite3_extended_result_codes(sqlite3*, int onoff);
1923
1924 /*
1925 ** CAPI3REF: Last Insert Rowid
1926 ** METHOD: sqlite3
1927 **
1928 ** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables)
1929 ** has a unique 64-bit signed
1930 ** integer key called the [ROWID | "rowid"]. ^The rowid is always available
1931 ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
1932 ** names are not also used by explicitly declared columns. ^If
1933 ** the table has a column of type [INTEGER PRIMARY KEY] then that column
1934 ** is another alias for the rowid.
1935 **
1936 ** ^The sqlite3_last_insert_rowid(D) interface returns the [rowid] of the 
1937 ** most recent successful [INSERT] into a rowid table or [virtual table]
1938 ** on database connection D.
1939 ** ^Inserts into [WITHOUT ROWID] tables are not recorded.
1940 ** ^If no successful [INSERT]s into rowid tables
1941 ** have ever occurred on the database connection D, 
1942 ** then sqlite3_last_insert_rowid(D) returns zero.
1943 **
1944 ** ^(If an [INSERT] occurs within a trigger or within a [virtual table]
1945 ** method, then this routine will return the [rowid] of the inserted
1946 ** row as long as the trigger or virtual table method is running.
1947 ** But once the trigger or virtual table method ends, the value returned 
1948 ** by this routine reverts to what it was before the trigger or virtual
1949 ** table method began.)^
1950 **
1951 ** ^An [INSERT] that fails due to a constraint violation is not a
1952 ** successful [INSERT] and does not change the value returned by this
1953 ** routine.  ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
1954 ** and INSERT OR ABORT make no changes to the return value of this
1955 ** routine when their insertion fails.  ^(When INSERT OR REPLACE
1956 ** encounters a constraint violation, it does not fail.  The
1957 ** INSERT continues to completion after deleting rows that caused
1958 ** the constraint problem so INSERT OR REPLACE will always change
1959 ** the return value of this interface.)^
1960 **
1961 ** ^For the purposes of this routine, an [INSERT] is considered to
1962 ** be successful even if it is subsequently rolled back.
1963 **
1964 ** This function is accessible to SQL statements via the
1965 ** [last_insert_rowid() SQL function].
1966 **
1967 ** If a separate thread performs a new [INSERT] on the same
1968 ** database connection while the [sqlite3_last_insert_rowid()]
1969 ** function is running and thus changes the last insert [rowid],
1970 ** then the value returned by [sqlite3_last_insert_rowid()] is
1971 ** unpredictable and might not equal either the old or the new
1972 ** last insert [rowid].
1973 */
1974 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_last_insert_rowid(sqlite3*);
1975
1976 /*
1977 ** CAPI3REF: Count The Number Of Rows Modified
1978 ** METHOD: sqlite3
1979 **
1980 ** ^This function returns the number of rows modified, inserted or
1981 ** deleted by the most recently completed INSERT, UPDATE or DELETE
1982 ** statement on the database connection specified by the only parameter.
1983 ** ^Executing any other type of SQL statement does not modify the value
1984 ** returned by this function.
1985 **
1986 ** ^Only changes made directly by the INSERT, UPDATE or DELETE statement are
1987 ** considered - auxiliary changes caused by [CREATE TRIGGER | triggers], 
1988 ** [foreign key actions] or [REPLACE] constraint resolution are not counted.
1989 ** 
1990 ** Changes to a view that are intercepted by 
1991 ** [INSTEAD OF trigger | INSTEAD OF triggers] are not counted. ^The value 
1992 ** returned by sqlite3_changes() immediately after an INSERT, UPDATE or 
1993 ** DELETE statement run on a view is always zero. Only changes made to real 
1994 ** tables are counted.
1995 **
1996 ** Things are more complicated if the sqlite3_changes() function is
1997 ** executed while a trigger program is running. This may happen if the
1998 ** program uses the [changes() SQL function], or if some other callback
1999 ** function invokes sqlite3_changes() directly. Essentially:
2000 ** 
2001 ** <ul>
2002 **   <li> ^(Before entering a trigger program the value returned by
2003 **        sqlite3_changes() function is saved. After the trigger program 
2004 **        has finished, the original value is restored.)^
2005 ** 
2006 **   <li> ^(Within a trigger program each INSERT, UPDATE and DELETE 
2007 **        statement sets the value returned by sqlite3_changes() 
2008 **        upon completion as normal. Of course, this value will not include 
2009 **        any changes performed by sub-triggers, as the sqlite3_changes() 
2010 **        value will be saved and restored after each sub-trigger has run.)^
2011 ** </ul>
2012 ** 
2013 ** ^This means that if the changes() SQL function (or similar) is used
2014 ** by the first INSERT, UPDATE or DELETE statement within a trigger, it 
2015 ** returns the value as set when the calling statement began executing.
2016 ** ^If it is used by the second or subsequent such statement within a trigger 
2017 ** program, the value returned reflects the number of rows modified by the 
2018 ** previous INSERT, UPDATE or DELETE statement within the same trigger.
2019 **
2020 ** See also the [sqlite3_total_changes()] interface, the
2021 ** [count_changes pragma], and the [changes() SQL function].
2022 **
2023 ** If a separate thread makes changes on the same database connection
2024 ** while [sqlite3_changes()] is running then the value returned
2025 ** is unpredictable and not meaningful.
2026 */
2027 SQLITE_API int SQLITE_STDCALL sqlite3_changes(sqlite3*);
2028
2029 /*
2030 ** CAPI3REF: Total Number Of Rows Modified
2031 ** METHOD: sqlite3
2032 **
2033 ** ^This function returns the total number of rows inserted, modified or
2034 ** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed
2035 ** since the database connection was opened, including those executed as
2036 ** part of trigger programs. ^Executing any other type of SQL statement
2037 ** does not affect the value returned by sqlite3_total_changes().
2038 ** 
2039 ** ^Changes made as part of [foreign key actions] are included in the
2040 ** count, but those made as part of REPLACE constraint resolution are
2041 ** not. ^Changes to a view that are intercepted by INSTEAD OF triggers 
2042 ** are not counted.
2043 ** 
2044 ** See also the [sqlite3_changes()] interface, the
2045 ** [count_changes pragma], and the [total_changes() SQL function].
2046 **
2047 ** If a separate thread makes changes on the same database connection
2048 ** while [sqlite3_total_changes()] is running then the value
2049 ** returned is unpredictable and not meaningful.
2050 */
2051 SQLITE_API int SQLITE_STDCALL sqlite3_total_changes(sqlite3*);
2052
2053 /*
2054 ** CAPI3REF: Interrupt A Long-Running Query
2055 ** METHOD: sqlite3
2056 **
2057 ** ^This function causes any pending database operation to abort and
2058 ** return at its earliest opportunity. This routine is typically
2059 ** called in response to a user action such as pressing "Cancel"
2060 ** or Ctrl-C where the user wants a long query operation to halt
2061 ** immediately.
2062 **
2063 ** ^It is safe to call this routine from a thread different from the
2064 ** thread that is currently running the database operation.  But it
2065 ** is not safe to call this routine with a [database connection] that
2066 ** is closed or might close before sqlite3_interrupt() returns.
2067 **
2068 ** ^If an SQL operation is very nearly finished at the time when
2069 ** sqlite3_interrupt() is called, then it might not have an opportunity
2070 ** to be interrupted and might continue to completion.
2071 **
2072 ** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
2073 ** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
2074 ** that is inside an explicit transaction, then the entire transaction
2075 ** will be rolled back automatically.
2076 **
2077 ** ^The sqlite3_interrupt(D) call is in effect until all currently running
2078 ** SQL statements on [database connection] D complete.  ^Any new SQL statements
2079 ** that are started after the sqlite3_interrupt() call and before the 
2080 ** running statements reaches zero are interrupted as if they had been
2081 ** running prior to the sqlite3_interrupt() call.  ^New SQL statements
2082 ** that are started after the running statement count reaches zero are
2083 ** not effected by the sqlite3_interrupt().
2084 ** ^A call to sqlite3_interrupt(D) that occurs when there are no running
2085 ** SQL statements is a no-op and has no effect on SQL statements
2086 ** that are started after the sqlite3_interrupt() call returns.
2087 **
2088 ** If the database connection closes while [sqlite3_interrupt()]
2089 ** is running then bad things will likely happen.
2090 */
2091 SQLITE_API void SQLITE_STDCALL sqlite3_interrupt(sqlite3*);
2092
2093 /*
2094 ** CAPI3REF: Determine If An SQL Statement Is Complete
2095 **
2096 ** These routines are useful during command-line input to determine if the
2097 ** currently entered text seems to form a complete SQL statement or
2098 ** if additional input is needed before sending the text into
2099 ** SQLite for parsing.  ^These routines return 1 if the input string
2100 ** appears to be a complete SQL statement.  ^A statement is judged to be
2101 ** complete if it ends with a semicolon token and is not a prefix of a
2102 ** well-formed CREATE TRIGGER statement.  ^Semicolons that are embedded within
2103 ** string literals or quoted identifier names or comments are not
2104 ** independent tokens (they are part of the token in which they are
2105 ** embedded) and thus do not count as a statement terminator.  ^Whitespace
2106 ** and comments that follow the final semicolon are ignored.
2107 **
2108 ** ^These routines return 0 if the statement is incomplete.  ^If a
2109 ** memory allocation fails, then SQLITE_NOMEM is returned.
2110 **
2111 ** ^These routines do not parse the SQL statements thus
2112 ** will not detect syntactically incorrect SQL.
2113 **
2114 ** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior 
2115 ** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
2116 ** automatically by sqlite3_complete16().  If that initialization fails,
2117 ** then the return value from sqlite3_complete16() will be non-zero
2118 ** regardless of whether or not the input SQL is complete.)^
2119 **
2120 ** The input to [sqlite3_complete()] must be a zero-terminated
2121 ** UTF-8 string.
2122 **
2123 ** The input to [sqlite3_complete16()] must be a zero-terminated
2124 ** UTF-16 string in native byte order.
2125 */
2126 SQLITE_API int SQLITE_STDCALL sqlite3_complete(const char *sql);
2127 SQLITE_API int SQLITE_STDCALL sqlite3_complete16(const void *sql);
2128
2129 /*
2130 ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
2131 ** KEYWORDS: {busy-handler callback} {busy handler}
2132 ** METHOD: sqlite3
2133 **
2134 ** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
2135 ** that might be invoked with argument P whenever
2136 ** an attempt is made to access a database table associated with
2137 ** [database connection] D when another thread
2138 ** or process has the table locked.
2139 ** The sqlite3_busy_handler() interface is used to implement
2140 ** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout].
2141 **
2142 ** ^If the busy callback is NULL, then [SQLITE_BUSY]
2143 ** is returned immediately upon encountering the lock.  ^If the busy callback
2144 ** is not NULL, then the callback might be invoked with two arguments.
2145 **
2146 ** ^The first argument to the busy handler is a copy of the void* pointer which
2147 ** is the third argument to sqlite3_busy_handler().  ^The second argument to
2148 ** the busy handler callback is the number of times that the busy handler has
2149 ** been invoked previously for the same locking event.  ^If the
2150 ** busy callback returns 0, then no additional attempts are made to
2151 ** access the database and [SQLITE_BUSY] is returned
2152 ** to the application.
2153 ** ^If the callback returns non-zero, then another attempt
2154 ** is made to access the database and the cycle repeats.
2155 **
2156 ** The presence of a busy handler does not guarantee that it will be invoked
2157 ** when there is lock contention. ^If SQLite determines that invoking the busy
2158 ** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
2159 ** to the application instead of invoking the 
2160 ** busy handler.
2161 ** Consider a scenario where one process is holding a read lock that
2162 ** it is trying to promote to a reserved lock and
2163 ** a second process is holding a reserved lock that it is trying
2164 ** to promote to an exclusive lock.  The first process cannot proceed
2165 ** because it is blocked by the second and the second process cannot
2166 ** proceed because it is blocked by the first.  If both processes
2167 ** invoke the busy handlers, neither will make any progress.  Therefore,
2168 ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
2169 ** will induce the first process to release its read lock and allow
2170 ** the second process to proceed.
2171 **
2172 ** ^The default busy callback is NULL.
2173 **
2174 ** ^(There can only be a single busy handler defined for each
2175 ** [database connection].  Setting a new busy handler clears any
2176 ** previously set handler.)^  ^Note that calling [sqlite3_busy_timeout()]
2177 ** or evaluating [PRAGMA busy_timeout=N] will change the
2178 ** busy handler and thus clear any previously set busy handler.
2179 **
2180 ** The busy callback should not take any actions which modify the
2181 ** database connection that invoked the busy handler.  In other words,
2182 ** the busy handler is not reentrant.  Any such actions
2183 ** result in undefined behavior.
2184 ** 
2185 ** A busy handler must not close the database connection
2186 ** or [prepared statement] that invoked the busy handler.
2187 */
2188 SQLITE_API int SQLITE_STDCALL sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
2189
2190 /*
2191 ** CAPI3REF: Set A Busy Timeout
2192 ** METHOD: sqlite3
2193 **
2194 ** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
2195 ** for a specified amount of time when a table is locked.  ^The handler
2196 ** will sleep multiple times until at least "ms" milliseconds of sleeping
2197 ** have accumulated.  ^After at least "ms" milliseconds of sleeping,
2198 ** the handler returns 0 which causes [sqlite3_step()] to return
2199 ** [SQLITE_BUSY].
2200 **
2201 ** ^Calling this routine with an argument less than or equal to zero
2202 ** turns off all busy handlers.
2203 **
2204 ** ^(There can only be a single busy handler for a particular
2205 ** [database connection] at any given moment.  If another busy handler
2206 ** was defined  (using [sqlite3_busy_handler()]) prior to calling
2207 ** this routine, that other busy handler is cleared.)^
2208 **
2209 ** See also:  [PRAGMA busy_timeout]
2210 */
2211 SQLITE_API int SQLITE_STDCALL sqlite3_busy_timeout(sqlite3*, int ms);
2212
2213 /*
2214 ** CAPI3REF: Convenience Routines For Running Queries
2215 ** METHOD: sqlite3
2216 **
2217 ** This is a legacy interface that is preserved for backwards compatibility.
2218 ** Use of this interface is not recommended.
2219 **
2220 ** Definition: A <b>result table</b> is memory data structure created by the
2221 ** [sqlite3_get_table()] interface.  A result table records the
2222 ** complete query results from one or more queries.
2223 **
2224 ** The table conceptually has a number of rows and columns.  But
2225 ** these numbers are not part of the result table itself.  These
2226 ** numbers are obtained separately.  Let N be the number of rows
2227 ** and M be the number of columns.
2228 **
2229 ** A result table is an array of pointers to zero-terminated UTF-8 strings.
2230 ** There are (N+1)*M elements in the array.  The first M pointers point
2231 ** to zero-terminated strings that  contain the names of the columns.
2232 ** The remaining entries all point to query results.  NULL values result
2233 ** in NULL pointers.  All other values are in their UTF-8 zero-terminated
2234 ** string representation as returned by [sqlite3_column_text()].
2235 **
2236 ** A result table might consist of one or more memory allocations.
2237 ** It is not safe to pass a result table directly to [sqlite3_free()].
2238 ** A result table should be deallocated using [sqlite3_free_table()].
2239 **
2240 ** ^(As an example of the result table format, suppose a query result
2241 ** is as follows:
2242 **
2243 ** <blockquote><pre>
2244 **        Name        | Age
2245 **        -----------------------
2246 **        Alice       | 43
2247 **        Bob         | 28
2248 **        Cindy       | 21
2249 ** </pre></blockquote>
2250 **
2251 ** There are two column (M==2) and three rows (N==3).  Thus the
2252 ** result table has 8 entries.  Suppose the result table is stored
2253 ** in an array names azResult.  Then azResult holds this content:
2254 **
2255 ** <blockquote><pre>
2256 **        azResult&#91;0] = "Name";
2257 **        azResult&#91;1] = "Age";
2258 **        azResult&#91;2] = "Alice";
2259 **        azResult&#91;3] = "43";
2260 **        azResult&#91;4] = "Bob";
2261 **        azResult&#91;5] = "28";
2262 **        azResult&#91;6] = "Cindy";
2263 **        azResult&#91;7] = "21";
2264 ** </pre></blockquote>)^
2265 **
2266 ** ^The sqlite3_get_table() function evaluates one or more
2267 ** semicolon-separated SQL statements in the zero-terminated UTF-8
2268 ** string of its 2nd parameter and returns a result table to the
2269 ** pointer given in its 3rd parameter.
2270 **
2271 ** After the application has finished with the result from sqlite3_get_table(),
2272 ** it must pass the result table pointer to sqlite3_free_table() in order to
2273 ** release the memory that was malloced.  Because of the way the
2274 ** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
2275 ** function must not try to call [sqlite3_free()] directly.  Only
2276 ** [sqlite3_free_table()] is able to release the memory properly and safely.
2277 **
2278 ** The sqlite3_get_table() interface is implemented as a wrapper around
2279 ** [sqlite3_exec()].  The sqlite3_get_table() routine does not have access
2280 ** to any internal data structures of SQLite.  It uses only the public
2281 ** interface defined here.  As a consequence, errors that occur in the
2282 ** wrapper layer outside of the internal [sqlite3_exec()] call are not
2283 ** reflected in subsequent calls to [sqlite3_errcode()] or
2284 ** [sqlite3_errmsg()].
2285 */
2286 SQLITE_API int SQLITE_STDCALL sqlite3_get_table(
2287   sqlite3 *db,          /* An open database */
2288   const char *zSql,     /* SQL to be evaluated */
2289   char ***pazResult,    /* Results of the query */
2290   int *pnRow,           /* Number of result rows written here */
2291   int *pnColumn,        /* Number of result columns written here */
2292   char **pzErrmsg       /* Error msg written here */
2293 );
2294 SQLITE_API void SQLITE_STDCALL sqlite3_free_table(char **result);
2295
2296 /*
2297 ** CAPI3REF: Formatted String Printing Functions
2298 **
2299 ** These routines are work-alikes of the "printf()" family of functions
2300 ** from the standard C library.
2301 ** These routines understand most of the common K&R formatting options,
2302 ** plus some additional non-standard formats, detailed below.
2303 ** Note that some of the more obscure formatting options from recent
2304 ** C-library standards are omitted from this implementation.
2305 **
2306 ** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
2307 ** results into memory obtained from [sqlite3_malloc()].
2308 ** The strings returned by these two routines should be
2309 ** released by [sqlite3_free()].  ^Both routines return a
2310 ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
2311 ** memory to hold the resulting string.
2312 **
2313 ** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
2314 ** the standard C library.  The result is written into the
2315 ** buffer supplied as the second parameter whose size is given by
2316 ** the first parameter. Note that the order of the
2317 ** first two parameters is reversed from snprintf().)^  This is an
2318 ** historical accident that cannot be fixed without breaking
2319 ** backwards compatibility.  ^(Note also that sqlite3_snprintf()
2320 ** returns a pointer to its buffer instead of the number of
2321 ** characters actually written into the buffer.)^  We admit that
2322 ** the number of characters written would be a more useful return
2323 ** value but we cannot change the implementation of sqlite3_snprintf()
2324 ** now without breaking compatibility.
2325 **
2326 ** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
2327 ** guarantees that the buffer is always zero-terminated.  ^The first
2328 ** parameter "n" is the total size of the buffer, including space for
2329 ** the zero terminator.  So the longest string that can be completely
2330 ** written will be n-1 characters.
2331 **
2332 ** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
2333 **
2334 ** These routines all implement some additional formatting
2335 ** options that are useful for constructing SQL statements.
2336 ** All of the usual printf() formatting options apply.  In addition, there
2337 ** is are "%q", "%Q", "%w" and "%z" options.
2338 **
2339 ** ^(The %q option works like %s in that it substitutes a nul-terminated
2340 ** string from the argument list.  But %q also doubles every '\'' character.
2341 ** %q is designed for use inside a string literal.)^  By doubling each '\''
2342 ** character it escapes that character and allows it to be inserted into
2343 ** the string.
2344 **
2345 ** For example, assume the string variable zText contains text as follows:
2346 **
2347 ** <blockquote><pre>
2348 **  char *zText = "It's a happy day!";
2349 ** </pre></blockquote>
2350 **
2351 ** One can use this text in an SQL statement as follows:
2352 **
2353 ** <blockquote><pre>
2354 **  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
2355 **  sqlite3_exec(db, zSQL, 0, 0, 0);
2356 **  sqlite3_free(zSQL);
2357 ** </pre></blockquote>
2358 **
2359 ** Because the %q format string is used, the '\'' character in zText
2360 ** is escaped and the SQL generated is as follows:
2361 **
2362 ** <blockquote><pre>
2363 **  INSERT INTO table1 VALUES('It''s a happy day!')
2364 ** </pre></blockquote>
2365 **
2366 ** This is correct.  Had we used %s instead of %q, the generated SQL
2367 ** would have looked like this:
2368 **
2369 ** <blockquote><pre>
2370 **  INSERT INTO table1 VALUES('It's a happy day!');
2371 ** </pre></blockquote>
2372 **
2373 ** This second example is an SQL syntax error.  As a general rule you should
2374 ** always use %q instead of %s when inserting text into a string literal.
2375 **
2376 ** ^(The %Q option works like %q except it also adds single quotes around
2377 ** the outside of the total string.  Additionally, if the parameter in the
2378 ** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
2379 ** single quotes).)^  So, for example, one could say:
2380 **
2381 ** <blockquote><pre>
2382 **  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
2383 **  sqlite3_exec(db, zSQL, 0, 0, 0);
2384 **  sqlite3_free(zSQL);
2385 ** </pre></blockquote>
2386 **
2387 ** The code above will render a correct SQL statement in the zSQL
2388 ** variable even if the zText variable is a NULL pointer.
2389 **
2390 ** ^(The "%w" formatting option is like "%q" except that it expects to
2391 ** be contained within double-quotes instead of single quotes, and it
2392 ** escapes the double-quote character instead of the single-quote
2393 ** character.)^  The "%w" formatting option is intended for safely inserting
2394 ** table and column names into a constructed SQL statement.
2395 **
2396 ** ^(The "%z" formatting option works like "%s" but with the
2397 ** addition that after the string has been read and copied into
2398 ** the result, [sqlite3_free()] is called on the input string.)^
2399 */
2400 SQLITE_API char *SQLITE_CDECL sqlite3_mprintf(const char*,...);
2401 SQLITE_API char *SQLITE_STDCALL sqlite3_vmprintf(const char*, va_list);
2402 SQLITE_API char *SQLITE_CDECL sqlite3_snprintf(int,char*,const char*, ...);
2403 SQLITE_API char *SQLITE_STDCALL sqlite3_vsnprintf(int,char*,const char*, va_list);
2404
2405 /*
2406 ** CAPI3REF: Memory Allocation Subsystem
2407 **
2408 ** The SQLite core uses these three routines for all of its own
2409 ** internal memory allocation needs. "Core" in the previous sentence
2410 ** does not include operating-system specific VFS implementation.  The
2411 ** Windows VFS uses native malloc() and free() for some operations.
2412 **
2413 ** ^The sqlite3_malloc() routine returns a pointer to a block
2414 ** of memory at least N bytes in length, where N is the parameter.
2415 ** ^If sqlite3_malloc() is unable to obtain sufficient free
2416 ** memory, it returns a NULL pointer.  ^If the parameter N to
2417 ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
2418 ** a NULL pointer.
2419 **
2420 ** ^The sqlite3_malloc64(N) routine works just like
2421 ** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
2422 ** of a signed 32-bit integer.
2423 **
2424 ** ^Calling sqlite3_free() with a pointer previously returned
2425 ** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
2426 ** that it might be reused.  ^The sqlite3_free() routine is
2427 ** a no-op if is called with a NULL pointer.  Passing a NULL pointer
2428 ** to sqlite3_free() is harmless.  After being freed, memory
2429 ** should neither be read nor written.  Even reading previously freed
2430 ** memory might result in a segmentation fault or other severe error.
2431 ** Memory corruption, a segmentation fault, or other severe error
2432 ** might result if sqlite3_free() is called with a non-NULL pointer that
2433 ** was not obtained from sqlite3_malloc() or sqlite3_realloc().
2434 **
2435 ** ^The sqlite3_realloc(X,N) interface attempts to resize a
2436 ** prior memory allocation X to be at least N bytes.
2437 ** ^If the X parameter to sqlite3_realloc(X,N)
2438 ** is a NULL pointer then its behavior is identical to calling
2439 ** sqlite3_malloc(N).
2440 ** ^If the N parameter to sqlite3_realloc(X,N) is zero or
2441 ** negative then the behavior is exactly the same as calling
2442 ** sqlite3_free(X).
2443 ** ^sqlite3_realloc(X,N) returns a pointer to a memory allocation
2444 ** of at least N bytes in size or NULL if insufficient memory is available.
2445 ** ^If M is the size of the prior allocation, then min(N,M) bytes
2446 ** of the prior allocation are copied into the beginning of buffer returned
2447 ** by sqlite3_realloc(X,N) and the prior allocation is freed.
2448 ** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the
2449 ** prior allocation is not freed.
2450 **
2451 ** ^The sqlite3_realloc64(X,N) interfaces works the same as
2452 ** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
2453 ** of a 32-bit signed integer.
2454 **
2455 ** ^If X is a memory allocation previously obtained from sqlite3_malloc(),
2456 ** sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then
2457 ** sqlite3_msize(X) returns the size of that memory allocation in bytes.
2458 ** ^The value returned by sqlite3_msize(X) might be larger than the number
2459 ** of bytes requested when X was allocated.  ^If X is a NULL pointer then
2460 ** sqlite3_msize(X) returns zero.  If X points to something that is not
2461 ** the beginning of memory allocation, or if it points to a formerly
2462 ** valid memory allocation that has now been freed, then the behavior
2463 ** of sqlite3_msize(X) is undefined and possibly harmful.
2464 **
2465 ** ^The memory returned by sqlite3_malloc(), sqlite3_realloc(),
2466 ** sqlite3_malloc64(), and sqlite3_realloc64()
2467 ** is always aligned to at least an 8 byte boundary, or to a
2468 ** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
2469 ** option is used.
2470 **
2471 ** In SQLite version 3.5.0 and 3.5.1, it was possible to define
2472 ** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
2473 ** implementation of these routines to be omitted.  That capability
2474 ** is no longer provided.  Only built-in memory allocators can be used.
2475 **
2476 ** Prior to SQLite version 3.7.10, the Windows OS interface layer called
2477 ** the system malloc() and free() directly when converting
2478 ** filenames between the UTF-8 encoding used by SQLite
2479 ** and whatever filename encoding is used by the particular Windows
2480 ** installation.  Memory allocation errors were detected, but
2481 ** they were reported back as [SQLITE_CANTOPEN] or
2482 ** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
2483 **
2484 ** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
2485 ** must be either NULL or else pointers obtained from a prior
2486 ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
2487 ** not yet been released.
2488 **
2489 ** The application must not read or write any part of
2490 ** a block of memory after it has been released using
2491 ** [sqlite3_free()] or [sqlite3_realloc()].
2492 */
2493 SQLITE_API void *SQLITE_STDCALL sqlite3_malloc(int);
2494 SQLITE_API void *SQLITE_STDCALL sqlite3_malloc64(sqlite3_uint64);
2495 SQLITE_API void *SQLITE_STDCALL sqlite3_realloc(void*, int);
2496 SQLITE_API void *SQLITE_STDCALL sqlite3_realloc64(void*, sqlite3_uint64);
2497 SQLITE_API void SQLITE_STDCALL sqlite3_free(void*);
2498 SQLITE_API sqlite3_uint64 SQLITE_STDCALL sqlite3_msize(void*);
2499
2500 /*
2501 ** CAPI3REF: Memory Allocator Statistics
2502 **
2503 ** SQLite provides these two interfaces for reporting on the status
2504 ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
2505 ** routines, which form the built-in memory allocation subsystem.
2506 **
2507 ** ^The [sqlite3_memory_used()] routine returns the number of bytes
2508 ** of memory currently outstanding (malloced but not freed).
2509 ** ^The [sqlite3_memory_highwater()] routine returns the maximum
2510 ** value of [sqlite3_memory_used()] since the high-water mark
2511 ** was last reset.  ^The values returned by [sqlite3_memory_used()] and
2512 ** [sqlite3_memory_highwater()] include any overhead
2513 ** added by SQLite in its implementation of [sqlite3_malloc()],
2514 ** but not overhead added by the any underlying system library
2515 ** routines that [sqlite3_malloc()] may call.
2516 **
2517 ** ^The memory high-water mark is reset to the current value of
2518 ** [sqlite3_memory_used()] if and only if the parameter to
2519 ** [sqlite3_memory_highwater()] is true.  ^The value returned
2520 ** by [sqlite3_memory_highwater(1)] is the high-water mark
2521 ** prior to the reset.
2522 */
2523 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_memory_used(void);
2524 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_memory_highwater(int resetFlag);
2525
2526 /*
2527 ** CAPI3REF: Pseudo-Random Number Generator
2528 **
2529 ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
2530 ** select random [ROWID | ROWIDs] when inserting new records into a table that
2531 ** already uses the largest possible [ROWID].  The PRNG is also used for
2532 ** the build-in random() and randomblob() SQL functions.  This interface allows
2533 ** applications to access the same PRNG for other purposes.
2534 **
2535 ** ^A call to this routine stores N bytes of randomness into buffer P.
2536 ** ^The P parameter can be a NULL pointer.
2537 **
2538 ** ^If this routine has not been previously called or if the previous
2539 ** call had N less than one or a NULL pointer for P, then the PRNG is
2540 ** seeded using randomness obtained from the xRandomness method of
2541 ** the default [sqlite3_vfs] object.
2542 ** ^If the previous call to this routine had an N of 1 or more and a
2543 ** non-NULL P then the pseudo-randomness is generated
2544 ** internally and without recourse to the [sqlite3_vfs] xRandomness
2545 ** method.
2546 */
2547 SQLITE_API void SQLITE_STDCALL sqlite3_randomness(int N, void *P);
2548
2549 /*
2550 ** CAPI3REF: Compile-Time Authorization Callbacks
2551 ** METHOD: sqlite3
2552 **
2553 ** ^This routine registers an authorizer callback with a particular
2554 ** [database connection], supplied in the first argument.
2555 ** ^The authorizer callback is invoked as SQL statements are being compiled
2556 ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
2557 ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()].  ^At various
2558 ** points during the compilation process, as logic is being created
2559 ** to perform various actions, the authorizer callback is invoked to
2560 ** see if those actions are allowed.  ^The authorizer callback should
2561 ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
2562 ** specific action but allow the SQL statement to continue to be
2563 ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
2564 ** rejected with an error.  ^If the authorizer callback returns
2565 ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
2566 ** then the [sqlite3_prepare_v2()] or equivalent call that triggered
2567 ** the authorizer will fail with an error message.
2568 **
2569 ** When the callback returns [SQLITE_OK], that means the operation
2570 ** requested is ok.  ^When the callback returns [SQLITE_DENY], the
2571 ** [sqlite3_prepare_v2()] or equivalent call that triggered the
2572 ** authorizer will fail with an error message explaining that
2573 ** access is denied. 
2574 **
2575 ** ^The first parameter to the authorizer callback is a copy of the third
2576 ** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
2577 ** to the callback is an integer [SQLITE_COPY | action code] that specifies
2578 ** the particular action to be authorized. ^The third through sixth parameters
2579 ** to the callback are zero-terminated strings that contain additional
2580 ** details about the action to be authorized.
2581 **
2582 ** ^If the action code is [SQLITE_READ]
2583 ** and the callback returns [SQLITE_IGNORE] then the
2584 ** [prepared statement] statement is constructed to substitute
2585 ** a NULL value in place of the table column that would have
2586 ** been read if [SQLITE_OK] had been returned.  The [SQLITE_IGNORE]
2587 ** return can be used to deny an untrusted user access to individual
2588 ** columns of a table.
2589 ** ^If the action code is [SQLITE_DELETE] and the callback returns
2590 ** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
2591 ** [truncate optimization] is disabled and all rows are deleted individually.
2592 **
2593 ** An authorizer is used when [sqlite3_prepare | preparing]
2594 ** SQL statements from an untrusted source, to ensure that the SQL statements
2595 ** do not try to access data they are not allowed to see, or that they do not
2596 ** try to execute malicious statements that damage the database.  For
2597 ** example, an application may allow a user to enter arbitrary
2598 ** SQL queries for evaluation by a database.  But the application does
2599 ** not want the user to be able to make arbitrary changes to the
2600 ** database.  An authorizer could then be put in place while the
2601 ** user-entered SQL is being [sqlite3_prepare | prepared] that
2602 ** disallows everything except [SELECT] statements.
2603 **
2604 ** Applications that need to process SQL from untrusted sources
2605 ** might also consider lowering resource limits using [sqlite3_limit()]
2606 ** and limiting database size using the [max_page_count] [PRAGMA]
2607 ** in addition to using an authorizer.
2608 **
2609 ** ^(Only a single authorizer can be in place on a database connection
2610 ** at a time.  Each call to sqlite3_set_authorizer overrides the
2611 ** previous call.)^  ^Disable the authorizer by installing a NULL callback.
2612 ** The authorizer is disabled by default.
2613 **
2614 ** The authorizer callback must not do anything that will modify
2615 ** the database connection that invoked the authorizer callback.
2616 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
2617 ** database connections for the meaning of "modify" in this paragraph.
2618 **
2619 ** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
2620 ** statement might be re-prepared during [sqlite3_step()] due to a 
2621 ** schema change.  Hence, the application should ensure that the
2622 ** correct authorizer callback remains in place during the [sqlite3_step()].
2623 **
2624 ** ^Note that the authorizer callback is invoked only during
2625 ** [sqlite3_prepare()] or its variants.  Authorization is not
2626 ** performed during statement evaluation in [sqlite3_step()], unless
2627 ** as stated in the previous paragraph, sqlite3_step() invokes
2628 ** sqlite3_prepare_v2() to reprepare a statement after a schema change.
2629 */
2630 SQLITE_API int SQLITE_STDCALL sqlite3_set_authorizer(
2631   sqlite3*,
2632   int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
2633   void *pUserData
2634 );
2635
2636 /*
2637 ** CAPI3REF: Authorizer Return Codes
2638 **
2639 ** The [sqlite3_set_authorizer | authorizer callback function] must
2640 ** return either [SQLITE_OK] or one of these two constants in order
2641 ** to signal SQLite whether or not the action is permitted.  See the
2642 ** [sqlite3_set_authorizer | authorizer documentation] for additional
2643 ** information.
2644 **
2645 ** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
2646 ** returned from the [sqlite3_vtab_on_conflict()] interface.
2647 */
2648 #define SQLITE_DENY   1   /* Abort the SQL statement with an error */
2649 #define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
2650
2651 /*
2652 ** CAPI3REF: Authorizer Action Codes
2653 **
2654 ** The [sqlite3_set_authorizer()] interface registers a callback function
2655 ** that is invoked to authorize certain SQL statement actions.  The
2656 ** second parameter to the callback is an integer code that specifies
2657 ** what action is being authorized.  These are the integer action codes that
2658 ** the authorizer callback may be passed.
2659 **
2660 ** These action code values signify what kind of operation is to be
2661 ** authorized.  The 3rd and 4th parameters to the authorization
2662 ** callback function will be parameters or NULL depending on which of these
2663 ** codes is used as the second parameter.  ^(The 5th parameter to the
2664 ** authorizer callback is the name of the database ("main", "temp",
2665 ** etc.) if applicable.)^  ^The 6th parameter to the authorizer callback
2666 ** is the name of the inner-most trigger or view that is responsible for
2667 ** the access attempt or NULL if this access attempt is directly from
2668 ** top-level SQL code.
2669 */
2670 /******************************************* 3rd ************ 4th ***********/
2671 #define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
2672 #define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
2673 #define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
2674 #define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
2675 #define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
2676 #define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
2677 #define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
2678 #define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
2679 #define SQLITE_DELETE                9   /* Table Name      NULL            */
2680 #define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
2681 #define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
2682 #define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
2683 #define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
2684 #define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
2685 #define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
2686 #define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
2687 #define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
2688 #define SQLITE_INSERT               18   /* Table Name      NULL            */
2689 #define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
2690 #define SQLITE_READ                 20   /* Table Name      Column Name     */
2691 #define SQLITE_SELECT               21   /* NULL            NULL            */
2692 #define SQLITE_TRANSACTION          22   /* Operation       NULL            */
2693 #define SQLITE_UPDATE               23   /* Table Name      Column Name     */
2694 #define SQLITE_ATTACH               24   /* Filename        NULL            */
2695 #define SQLITE_DETACH               25   /* Database Name   NULL            */
2696 #define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */
2697 #define SQLITE_REINDEX              27   /* Index Name      NULL            */
2698 #define SQLITE_ANALYZE              28   /* Table Name      NULL            */
2699 #define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */
2700 #define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */
2701 #define SQLITE_FUNCTION             31   /* NULL            Function Name   */
2702 #define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */
2703 #define SQLITE_COPY                  0   /* No longer used */
2704 #define SQLITE_RECURSIVE            33   /* NULL            NULL            */
2705
2706 /*
2707 ** CAPI3REF: Tracing And Profiling Functions
2708 ** METHOD: sqlite3
2709 **
2710 ** These routines register callback functions that can be used for
2711 ** tracing and profiling the execution of SQL statements.
2712 **
2713 ** ^The callback function registered by sqlite3_trace() is invoked at
2714 ** various times when an SQL statement is being run by [sqlite3_step()].
2715 ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
2716 ** SQL statement text as the statement first begins executing.
2717 ** ^(Additional sqlite3_trace() callbacks might occur
2718 ** as each triggered subprogram is entered.  The callbacks for triggers
2719 ** contain a UTF-8 SQL comment that identifies the trigger.)^
2720 **
2721 ** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
2722 ** the length of [bound parameter] expansion in the output of sqlite3_trace().
2723 **
2724 ** ^The callback function registered by sqlite3_profile() is invoked
2725 ** as each SQL statement finishes.  ^The profile callback contains
2726 ** the original statement text and an estimate of wall-clock time
2727 ** of how long that statement took to run.  ^The profile callback
2728 ** time is in units of nanoseconds, however the current implementation
2729 ** is only capable of millisecond resolution so the six least significant
2730 ** digits in the time are meaningless.  Future versions of SQLite
2731 ** might provide greater resolution on the profiler callback.  The
2732 ** sqlite3_profile() function is considered experimental and is
2733 ** subject to change in future versions of SQLite.
2734 */
2735 SQLITE_API void *SQLITE_STDCALL sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
2736 SQLITE_API SQLITE_EXPERIMENTAL void *SQLITE_STDCALL sqlite3_profile(sqlite3*,
2737    void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
2738
2739 /*
2740 ** CAPI3REF: Query Progress Callbacks
2741 ** METHOD: sqlite3
2742 **
2743 ** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
2744 ** function X to be invoked periodically during long running calls to
2745 ** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for
2746 ** database connection D.  An example use for this
2747 ** interface is to keep a GUI updated during a large query.
2748 **
2749 ** ^The parameter P is passed through as the only parameter to the 
2750 ** callback function X.  ^The parameter N is the approximate number of 
2751 ** [virtual machine instructions] that are evaluated between successive
2752 ** invocations of the callback X.  ^If N is less than one then the progress
2753 ** handler is disabled.
2754 **
2755 ** ^Only a single progress handler may be defined at one time per
2756 ** [database connection]; setting a new progress handler cancels the
2757 ** old one.  ^Setting parameter X to NULL disables the progress handler.
2758 ** ^The progress handler is also disabled by setting N to a value less
2759 ** than 1.
2760 **
2761 ** ^If the progress callback returns non-zero, the operation is
2762 ** interrupted.  This feature can be used to implement a
2763 ** "Cancel" button on a GUI progress dialog box.
2764 **
2765 ** The progress handler callback must not do anything that will modify
2766 ** the database connection that invoked the progress handler.
2767 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
2768 ** database connections for the meaning of "modify" in this paragraph.
2769 **
2770 */
2771 SQLITE_API void SQLITE_STDCALL sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
2772
2773 /*
2774 ** CAPI3REF: Opening A New Database Connection
2775 ** CONSTRUCTOR: sqlite3
2776 **
2777 ** ^These routines open an SQLite database file as specified by the 
2778 ** filename argument. ^The filename argument is interpreted as UTF-8 for
2779 ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
2780 ** order for sqlite3_open16(). ^(A [database connection] handle is usually
2781 ** returned in *ppDb, even if an error occurs.  The only exception is that
2782 ** if SQLite is unable to allocate memory to hold the [sqlite3] object,
2783 ** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
2784 ** object.)^ ^(If the database is opened (and/or created) successfully, then
2785 ** [SQLITE_OK] is returned.  Otherwise an [error code] is returned.)^ ^The
2786 ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
2787 ** an English language description of the error following a failure of any
2788 ** of the sqlite3_open() routines.
2789 **
2790 ** ^The default encoding will be UTF-8 for databases created using
2791 ** sqlite3_open() or sqlite3_open_v2().  ^The default encoding for databases
2792 ** created using sqlite3_open16() will be UTF-16 in the native byte order.
2793 **
2794 ** Whether or not an error occurs when it is opened, resources
2795 ** associated with the [database connection] handle should be released by
2796 ** passing it to [sqlite3_close()] when it is no longer required.
2797 **
2798 ** The sqlite3_open_v2() interface works like sqlite3_open()
2799 ** except that it accepts two additional parameters for additional control
2800 ** over the new database connection.  ^(The flags parameter to
2801 ** sqlite3_open_v2() can take one of
2802 ** the following three values, optionally combined with the 
2803 ** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE],
2804 ** [SQLITE_OPEN_PRIVATECACHE], and/or [SQLITE_OPEN_URI] flags:)^
2805 **
2806 ** <dl>
2807 ** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
2808 ** <dd>The database is opened in read-only mode.  If the database does not
2809 ** already exist, an error is returned.</dd>)^
2810 **
2811 ** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
2812 ** <dd>The database is opened for reading and writing if possible, or reading
2813 ** only if the file is write protected by the operating system.  In either
2814 ** case the database must already exist, otherwise an error is returned.</dd>)^
2815 **
2816 ** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
2817 ** <dd>The database is opened for reading and writing, and is created if
2818 ** it does not already exist. This is the behavior that is always used for
2819 ** sqlite3_open() and sqlite3_open16().</dd>)^
2820 ** </dl>
2821 **
2822 ** If the 3rd parameter to sqlite3_open_v2() is not one of the
2823 ** combinations shown above optionally combined with other
2824 ** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]
2825 ** then the behavior is undefined.
2826 **
2827 ** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
2828 ** opens in the multi-thread [threading mode] as long as the single-thread
2829 ** mode has not been set at compile-time or start-time.  ^If the
2830 ** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
2831 ** in the serialized [threading mode] unless single-thread was
2832 ** previously selected at compile-time or start-time.
2833 ** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
2834 ** eligible to use [shared cache mode], regardless of whether or not shared
2835 ** cache is enabled using [sqlite3_enable_shared_cache()].  ^The
2836 ** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not
2837 ** participate in [shared cache mode] even if it is enabled.
2838 **
2839 ** ^The fourth parameter to sqlite3_open_v2() is the name of the
2840 ** [sqlite3_vfs] object that defines the operating system interface that
2841 ** the new database connection should use.  ^If the fourth parameter is
2842 ** a NULL pointer then the default [sqlite3_vfs] object is used.
2843 **
2844 ** ^If the filename is ":memory:", then a private, temporary in-memory database
2845 ** is created for the connection.  ^This in-memory database will vanish when
2846 ** the database connection is closed.  Future versions of SQLite might
2847 ** make use of additional special filenames that begin with the ":" character.
2848 ** It is recommended that when a database filename actually does begin with
2849 ** a ":" character you should prefix the filename with a pathname such as
2850 ** "./" to avoid ambiguity.
2851 **
2852 ** ^If the filename is an empty string, then a private, temporary
2853 ** on-disk database will be created.  ^This private database will be
2854 ** automatically deleted as soon as the database connection is closed.
2855 **
2856 ** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>
2857 **
2858 ** ^If [URI filename] interpretation is enabled, and the filename argument
2859 ** begins with "file:", then the filename is interpreted as a URI. ^URI
2860 ** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
2861 ** set in the fourth argument to sqlite3_open_v2(), or if it has
2862 ** been enabled globally using the [SQLITE_CONFIG_URI] option with the
2863 ** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
2864 ** As of SQLite version 3.7.7, URI filename interpretation is turned off
2865 ** by default, but future releases of SQLite might enable URI filename
2866 ** interpretation by default.  See "[URI filenames]" for additional
2867 ** information.
2868 **
2869 ** URI filenames are parsed according to RFC 3986. ^If the URI contains an
2870 ** authority, then it must be either an empty string or the string 
2871 ** "localhost". ^If the authority is not an empty string or "localhost", an 
2872 ** error is returned to the caller. ^The fragment component of a URI, if 
2873 ** present, is ignored.
2874 **
2875 ** ^SQLite uses the path component of the URI as the name of the disk file
2876 ** which contains the database. ^If the path begins with a '/' character, 
2877 ** then it is interpreted as an absolute path. ^If the path does not begin 
2878 ** with a '/' (meaning that the authority section is omitted from the URI)
2879 ** then the path is interpreted as a relative path. 
2880 ** ^(On windows, the first component of an absolute path 
2881 ** is a drive specification (e.g. "C:").)^
2882 **
2883 ** [[core URI query parameters]]
2884 ** The query component of a URI may contain parameters that are interpreted
2885 ** either by SQLite itself, or by a [VFS | custom VFS implementation].
2886 ** SQLite and its built-in [VFSes] interpret the
2887 ** following query parameters:
2888 **
2889 ** <ul>
2890 **   <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
2891 **     a VFS object that provides the operating system interface that should
2892 **     be used to access the database file on disk. ^If this option is set to
2893 **     an empty string the default VFS object is used. ^Specifying an unknown
2894 **     VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
2895 **     present, then the VFS specified by the option takes precedence over
2896 **     the value passed as the fourth parameter to sqlite3_open_v2().
2897 **
2898 **   <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw",
2899 **     "rwc", or "memory". Attempting to set it to any other value is
2900 **     an error)^. 
2901 **     ^If "ro" is specified, then the database is opened for read-only 
2902 **     access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the 
2903 **     third argument to sqlite3_open_v2(). ^If the mode option is set to 
2904 **     "rw", then the database is opened for read-write (but not create) 
2905 **     access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had 
2906 **     been set. ^Value "rwc" is equivalent to setting both 
2907 **     SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE.  ^If the mode option is
2908 **     set to "memory" then a pure [in-memory database] that never reads
2909 **     or writes from disk is used. ^It is an error to specify a value for
2910 **     the mode parameter that is less restrictive than that specified by
2911 **     the flags passed in the third parameter to sqlite3_open_v2().
2912 **
2913 **   <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
2914 **     "private". ^Setting it to "shared" is equivalent to setting the
2915 **     SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
2916 **     sqlite3_open_v2(). ^Setting the cache parameter to "private" is 
2917 **     equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
2918 **     ^If sqlite3_open_v2() is used and the "cache" parameter is present in
2919 **     a URI filename, its value overrides any behavior requested by setting
2920 **     SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
2921 **
2922 **  <li> <b>psow</b>: ^The psow parameter indicates whether or not the
2923 **     [powersafe overwrite] property does or does not apply to the
2924 **     storage media on which the database file resides.
2925 **
2926 **  <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
2927 **     which if set disables file locking in rollback journal modes.  This
2928 **     is useful for accessing a database on a filesystem that does not
2929 **     support locking.  Caution:  Database corruption might result if two
2930 **     or more processes write to the same database and any one of those
2931 **     processes uses nolock=1.
2932 **
2933 **  <li> <b>immutable</b>: ^The immutable parameter is a boolean query
2934 **     parameter that indicates that the database file is stored on
2935 **     read-only media.  ^When immutable is set, SQLite assumes that the
2936 **     database file cannot be changed, even by a process with higher
2937 **     privilege, and so the database is opened read-only and all locking
2938 **     and change detection is disabled.  Caution: Setting the immutable
2939 **     property on a database file that does in fact change can result
2940 **     in incorrect query results and/or [SQLITE_CORRUPT] errors.
2941 **     See also: [SQLITE_IOCAP_IMMUTABLE].
2942 **       
2943 ** </ul>
2944 **
2945 ** ^Specifying an unknown parameter in the query component of a URI is not an
2946 ** error.  Future versions of SQLite might understand additional query
2947 ** parameters.  See "[query parameters with special meaning to SQLite]" for
2948 ** additional information.
2949 **
2950 ** [[URI filename examples]] <h3>URI filename examples</h3>
2951 **
2952 ** <table border="1" align=center cellpadding=5>
2953 ** <tr><th> URI filenames <th> Results
2954 ** <tr><td> file:data.db <td> 
2955 **          Open the file "data.db" in the current directory.
2956 ** <tr><td> file:/home/fred/data.db<br>
2957 **          file:///home/fred/data.db <br> 
2958 **          file://localhost/home/fred/data.db <br> <td> 
2959 **          Open the database file "/home/fred/data.db".
2960 ** <tr><td> file://darkstar/home/fred/data.db <td> 
2961 **          An error. "darkstar" is not a recognized authority.
2962 ** <tr><td style="white-space:nowrap"> 
2963 **          file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
2964 **     <td> Windows only: Open the file "data.db" on fred's desktop on drive
2965 **          C:. Note that the %20 escaping in this example is not strictly 
2966 **          necessary - space characters can be used literally
2967 **          in URI filenames.
2968 ** <tr><td> file:data.db?mode=ro&cache=private <td> 
2969 **          Open file "data.db" in the current directory for read-only access.
2970 **          Regardless of whether or not shared-cache mode is enabled by
2971 **          default, use a private cache.
2972 ** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
2973 **          Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
2974 **          that uses dot-files in place of posix advisory locking.
2975 ** <tr><td> file:data.db?mode=readonly <td> 
2976 **          An error. "readonly" is not a valid option for the "mode" parameter.
2977 ** </table>
2978 **
2979 ** ^URI hexadecimal escape sequences (%HH) are supported within the path and
2980 ** query components of a URI. A hexadecimal escape sequence consists of a
2981 ** percent sign - "%" - followed by exactly two hexadecimal digits 
2982 ** specifying an octet value. ^Before the path or query components of a
2983 ** URI filename are interpreted, they are encoded using UTF-8 and all 
2984 ** hexadecimal escape sequences replaced by a single byte containing the
2985 ** corresponding octet. If this process generates an invalid UTF-8 encoding,
2986 ** the results are undefined.
2987 **
2988 ** <b>Note to Windows users:</b>  The encoding used for the filename argument
2989 ** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
2990 ** codepage is currently defined.  Filenames containing international
2991 ** characters must be converted to UTF-8 prior to passing them into
2992 ** sqlite3_open() or sqlite3_open_v2().
2993 **
2994 ** <b>Note to Windows Runtime users:</b>  The temporary directory must be set
2995 ** prior to calling sqlite3_open() or sqlite3_open_v2().  Otherwise, various
2996 ** features that require the use of temporary files may fail.
2997 **
2998 ** See also: [sqlite3_temp_directory]
2999 */
3000 SQLITE_API int SQLITE_STDCALL sqlite3_open(
3001   const char *filename,   /* Database filename (UTF-8) */
3002   sqlite3 **ppDb          /* OUT: SQLite db handle */
3003 );
3004 SQLITE_API int SQLITE_STDCALL sqlite3_open16(
3005   const void *filename,   /* Database filename (UTF-16) */
3006   sqlite3 **ppDb          /* OUT: SQLite db handle */
3007 );
3008 SQLITE_API int SQLITE_STDCALL sqlite3_open_v2(
3009   const char *filename,   /* Database filename (UTF-8) */
3010   sqlite3 **ppDb,         /* OUT: SQLite db handle */
3011   int flags,              /* Flags */
3012   const char *zVfs        /* Name of VFS module to use */
3013 );
3014
3015 /*
3016 ** CAPI3REF: Obtain Values For URI Parameters
3017 **
3018 ** These are utility routines, useful to VFS implementations, that check
3019 ** to see if a database file was a URI that contained a specific query 
3020 ** parameter, and if so obtains the value of that query parameter.
3021 **
3022 ** If F is the database filename pointer passed into the xOpen() method of 
3023 ** a VFS implementation when the flags parameter to xOpen() has one or 
3024 ** more of the [SQLITE_OPEN_URI] or [SQLITE_OPEN_MAIN_DB] bits set and
3025 ** P is the name of the query parameter, then
3026 ** sqlite3_uri_parameter(F,P) returns the value of the P
3027 ** parameter if it exists or a NULL pointer if P does not appear as a 
3028 ** query parameter on F.  If P is a query parameter of F
3029 ** has no explicit value, then sqlite3_uri_parameter(F,P) returns
3030 ** a pointer to an empty string.
3031 **
3032 ** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
3033 ** parameter and returns true (1) or false (0) according to the value
3034 ** of P.  The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the
3035 ** value of query parameter P is one of "yes", "true", or "on" in any
3036 ** case or if the value begins with a non-zero number.  The 
3037 ** sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of
3038 ** query parameter P is one of "no", "false", or "off" in any case or
3039 ** if the value begins with a numeric zero.  If P is not a query
3040 ** parameter on F or if the value of P is does not match any of the
3041 ** above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).
3042 **
3043 ** The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
3044 ** 64-bit signed integer and returns that integer, or D if P does not
3045 ** exist.  If the value of P is something other than an integer, then
3046 ** zero is returned.
3047 ** 
3048 ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
3049 ** sqlite3_uri_boolean(F,P,B) returns B.  If F is not a NULL pointer and
3050 ** is not a database file pathname pointer that SQLite passed into the xOpen
3051 ** VFS method, then the behavior of this routine is undefined and probably
3052 ** undesirable.
3053 */
3054 SQLITE_API const char *SQLITE_STDCALL sqlite3_uri_parameter(const char *zFilename, const char *zParam);
3055 SQLITE_API int SQLITE_STDCALL sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault);
3056 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_uri_int64(const char*, const char*, sqlite3_int64);
3057
3058
3059 /*
3060 ** CAPI3REF: Error Codes And Messages
3061 ** METHOD: sqlite3
3062 **
3063 ** ^If the most recent sqlite3_* API call associated with 
3064 ** [database connection] D failed, then the sqlite3_errcode(D) interface
3065 ** returns the numeric [result code] or [extended result code] for that
3066 ** API call.
3067 ** If the most recent API call was successful,
3068 ** then the return value from sqlite3_errcode() is undefined.
3069 ** ^The sqlite3_extended_errcode()
3070 ** interface is the same except that it always returns the 
3071 ** [extended result code] even when extended result codes are
3072 ** disabled.
3073 **
3074 ** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
3075 ** text that describes the error, as either UTF-8 or UTF-16 respectively.
3076 ** ^(Memory to hold the error message string is managed internally.
3077 ** The application does not need to worry about freeing the result.
3078 ** However, the error string might be overwritten or deallocated by
3079 ** subsequent calls to other SQLite interface functions.)^
3080 **
3081 ** ^The sqlite3_errstr() interface returns the English-language text
3082 ** that describes the [result code], as UTF-8.
3083 ** ^(Memory to hold the error message string is managed internally
3084 ** and must not be freed by the application)^.
3085 **
3086 ** When the serialized [threading mode] is in use, it might be the
3087 ** case that a second error occurs on a separate thread in between
3088 ** the time of the first error and the call to these interfaces.
3089 ** When that happens, the second error will be reported since these
3090 ** interfaces always report the most recent result.  To avoid
3091 ** this, each thread can obtain exclusive use of the [database connection] D
3092 ** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
3093 ** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
3094 ** all calls to the interfaces listed here are completed.
3095 **
3096 ** If an interface fails with SQLITE_MISUSE, that means the interface
3097 ** was invoked incorrectly by the application.  In that case, the
3098 ** error code and message may or may not be set.
3099 */
3100 SQLITE_API int SQLITE_STDCALL sqlite3_errcode(sqlite3 *db);
3101 SQLITE_API int SQLITE_STDCALL sqlite3_extended_errcode(sqlite3 *db);
3102 SQLITE_API const char *SQLITE_STDCALL sqlite3_errmsg(sqlite3*);
3103 SQLITE_API const void *SQLITE_STDCALL sqlite3_errmsg16(sqlite3*);
3104 SQLITE_API const char *SQLITE_STDCALL sqlite3_errstr(int);
3105
3106 /*
3107 ** CAPI3REF: Prepared Statement Object
3108 ** KEYWORDS: {prepared statement} {prepared statements}
3109 **
3110 ** An instance of this object represents a single SQL statement that
3111 ** has been compiled into binary form and is ready to be evaluated.
3112 **
3113 ** Think of each SQL statement as a separate computer program.  The
3114 ** original SQL text is source code.  A prepared statement object 
3115 ** is the compiled object code.  All SQL must be converted into a
3116 ** prepared statement before it can be run.
3117 **
3118 ** The life-cycle of a prepared statement object usually goes like this:
3119 **
3120 ** <ol>
3121 ** <li> Create the prepared statement object using [sqlite3_prepare_v2()].
3122 ** <li> Bind values to [parameters] using the sqlite3_bind_*()
3123 **      interfaces.
3124 ** <li> Run the SQL by calling [sqlite3_step()] one or more times.
3125 ** <li> Reset the prepared statement using [sqlite3_reset()] then go back
3126 **      to step 2.  Do this zero or more times.
3127 ** <li> Destroy the object using [sqlite3_finalize()].
3128 ** </ol>
3129 */
3130 typedef struct sqlite3_stmt sqlite3_stmt;
3131
3132 /*
3133 ** CAPI3REF: Run-time Limits
3134 ** METHOD: sqlite3
3135 **
3136 ** ^(This interface allows the size of various constructs to be limited
3137 ** on a connection by connection basis.  The first parameter is the
3138 ** [database connection] whose limit is to be set or queried.  The
3139 ** second parameter is one of the [limit categories] that define a
3140 ** class of constructs to be size limited.  The third parameter is the
3141 ** new limit for that construct.)^
3142 **
3143 ** ^If the new limit is a negative number, the limit is unchanged.
3144 ** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a 
3145 ** [limits | hard upper bound]
3146 ** set at compile-time by a C preprocessor macro called
3147 ** [limits | SQLITE_MAX_<i>NAME</i>].
3148 ** (The "_LIMIT_" in the name is changed to "_MAX_".))^
3149 ** ^Attempts to increase a limit above its hard upper bound are
3150 ** silently truncated to the hard upper bound.
3151 **
3152 ** ^Regardless of whether or not the limit was changed, the 
3153 ** [sqlite3_limit()] interface returns the prior value of the limit.
3154 ** ^Hence, to find the current value of a limit without changing it,
3155 ** simply invoke this interface with the third parameter set to -1.
3156 **
3157 ** Run-time limits are intended for use in applications that manage
3158 ** both their own internal database and also databases that are controlled
3159 ** by untrusted external sources.  An example application might be a
3160 ** web browser that has its own databases for storing history and
3161 ** separate databases controlled by JavaScript applications downloaded
3162 ** off the Internet.  The internal databases can be given the
3163 ** large, default limits.  Databases managed by external sources can
3164 ** be given much smaller limits designed to prevent a denial of service
3165 ** attack.  Developers might also want to use the [sqlite3_set_authorizer()]
3166 ** interface to further control untrusted SQL.  The size of the database
3167 ** created by an untrusted script can be contained using the
3168 ** [max_page_count] [PRAGMA].
3169 **
3170 ** New run-time limit categories may be added in future releases.
3171 */
3172 SQLITE_API int SQLITE_STDCALL sqlite3_limit(sqlite3*, int id, int newVal);
3173
3174 /*
3175 ** CAPI3REF: Run-Time Limit Categories
3176 ** KEYWORDS: {limit category} {*limit categories}
3177 **
3178 ** These constants define various performance limits
3179 ** that can be lowered at run-time using [sqlite3_limit()].
3180 ** The synopsis of the meanings of the various limits is shown below.
3181 ** Additional information is available at [limits | Limits in SQLite].
3182 **
3183 ** <dl>
3184 ** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt>
3185 ** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^
3186 **
3187 ** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
3188 ** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
3189 **
3190 ** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt>
3191 ** <dd>The maximum number of columns in a table definition or in the
3192 ** result set of a [SELECT] or the maximum number of columns in an index
3193 ** or in an ORDER BY or GROUP BY clause.</dd>)^
3194 **
3195 ** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
3196 ** <dd>The maximum depth of the parse tree on any expression.</dd>)^
3197 **
3198 ** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
3199 ** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
3200 **
3201 ** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
3202 ** <dd>The maximum number of instructions in a virtual machine program
3203 ** used to implement an SQL statement.  This limit is not currently
3204 ** enforced, though that might be added in some future release of
3205 ** SQLite.</dd>)^
3206 **
3207 ** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
3208 ** <dd>The maximum number of arguments on a function.</dd>)^
3209 **
3210 ** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
3211 ** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
3212 **
3213 ** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]
3214 ** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
3215 ** <dd>The maximum length of the pattern argument to the [LIKE] or
3216 ** [GLOB] operators.</dd>)^
3217 **
3218 ** [[SQLITE_LIMIT_VARIABLE_NUMBER]]
3219 ** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
3220 ** <dd>The maximum index number of any [parameter] in an SQL statement.)^
3221 **
3222 ** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
3223 ** <dd>The maximum depth of recursion for triggers.</dd>)^
3224 **
3225 ** [[SQLITE_LIMIT_WORKER_THREADS]] ^(<dt>SQLITE_LIMIT_WORKER_THREADS</dt>
3226 ** <dd>The maximum number of auxiliary worker threads that a single
3227 ** [prepared statement] may start.</dd>)^
3228 ** </dl>
3229 */
3230 #define SQLITE_LIMIT_LENGTH                    0
3231 #define SQLITE_LIMIT_SQL_LENGTH                1
3232 #define SQLITE_LIMIT_COLUMN                    2
3233 #define SQLITE_LIMIT_EXPR_DEPTH                3
3234 #define SQLITE_LIMIT_COMPOUND_SELECT           4
3235 #define SQLITE_LIMIT_VDBE_OP                   5
3236 #define SQLITE_LIMIT_FUNCTION_ARG              6
3237 #define SQLITE_LIMIT_ATTACHED                  7
3238 #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH       8
3239 #define SQLITE_LIMIT_VARIABLE_NUMBER           9
3240 #define SQLITE_LIMIT_TRIGGER_DEPTH            10
3241 #define SQLITE_LIMIT_WORKER_THREADS           11
3242
3243 /*
3244 ** CAPI3REF: Compiling An SQL Statement
3245 ** KEYWORDS: {SQL statement compiler}
3246 ** METHOD: sqlite3
3247 ** CONSTRUCTOR: sqlite3_stmt
3248 **
3249 ** To execute an SQL query, it must first be compiled into a byte-code
3250 ** program using one of these routines.
3251 **
3252 ** The first argument, "db", is a [database connection] obtained from a
3253 ** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
3254 ** [sqlite3_open16()].  The database connection must not have been closed.
3255 **
3256 ** The second argument, "zSql", is the statement to be compiled, encoded
3257 ** as either UTF-8 or UTF-16.  The sqlite3_prepare() and sqlite3_prepare_v2()
3258 ** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
3259 ** use UTF-16.
3260 **
3261 ** ^If the nByte argument is negative, then zSql is read up to the
3262 ** first zero terminator. ^If nByte is positive, then it is the
3263 ** number of bytes read from zSql.  ^If nByte is zero, then no prepared
3264 ** statement is generated.
3265 ** If the caller knows that the supplied string is nul-terminated, then
3266 ** there is a small performance advantage to passing an nByte parameter that
3267 ** is the number of bytes in the input string <i>including</i>
3268 ** the nul-terminator.
3269 **
3270 ** ^If pzTail is not NULL then *pzTail is made to point to the first byte
3271 ** past the end of the first SQL statement in zSql.  These routines only
3272 ** compile the first statement in zSql, so *pzTail is left pointing to
3273 ** what remains uncompiled.
3274 **
3275 ** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
3276 ** executed using [sqlite3_step()].  ^If there is an error, *ppStmt is set
3277 ** to NULL.  ^If the input text contains no SQL (if the input is an empty
3278 ** string or a comment) then *ppStmt is set to NULL.
3279 ** The calling procedure is responsible for deleting the compiled
3280 ** SQL statement using [sqlite3_finalize()] after it has finished with it.
3281 ** ppStmt may not be NULL.
3282 **
3283 ** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
3284 ** otherwise an [error code] is returned.
3285 **
3286 ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
3287 ** recommended for all new programs. The two older interfaces are retained
3288 ** for backwards compatibility, but their use is discouraged.
3289 ** ^In the "v2" interfaces, the prepared statement
3290 ** that is returned (the [sqlite3_stmt] object) contains a copy of the
3291 ** original SQL text. This causes the [sqlite3_step()] interface to
3292 ** behave differently in three ways:
3293 **
3294 ** <ol>
3295 ** <li>
3296 ** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
3297 ** always used to do, [sqlite3_step()] will automatically recompile the SQL
3298 ** statement and try to run it again. As many as [SQLITE_MAX_SCHEMA_RETRY]
3299 ** retries will occur before sqlite3_step() gives up and returns an error.
3300 ** </li>
3301 **
3302 ** <li>
3303 ** ^When an error occurs, [sqlite3_step()] will return one of the detailed
3304 ** [error codes] or [extended error codes].  ^The legacy behavior was that
3305 ** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
3306 ** and the application would have to make a second call to [sqlite3_reset()]
3307 ** in order to find the underlying cause of the problem. With the "v2" prepare
3308 ** interfaces, the underlying reason for the error is returned immediately.
3309 ** </li>
3310 **
3311 ** <li>
3312 ** ^If the specific value bound to [parameter | host parameter] in the 
3313 ** WHERE clause might influence the choice of query plan for a statement,
3314 ** then the statement will be automatically recompiled, as if there had been 
3315 ** a schema change, on the first  [sqlite3_step()] call following any change
3316 ** to the [sqlite3_bind_text | bindings] of that [parameter]. 
3317 ** ^The specific value of WHERE-clause [parameter] might influence the 
3318 ** choice of query plan if the parameter is the left-hand side of a [LIKE]
3319 ** or [GLOB] operator or if the parameter is compared to an indexed column
3320 ** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled.
3321 ** </li>
3322 ** </ol>
3323 */
3324 SQLITE_API int SQLITE_STDCALL sqlite3_prepare(
3325   sqlite3 *db,            /* Database handle */
3326   const char *zSql,       /* SQL statement, UTF-8 encoded */
3327   int nByte,              /* Maximum length of zSql in bytes. */
3328   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
3329   const char **pzTail     /* OUT: Pointer to unused portion of zSql */
3330 );
3331 SQLITE_API int SQLITE_STDCALL sqlite3_prepare_v2(
3332   sqlite3 *db,            /* Database handle */
3333   const char *zSql,       /* SQL statement, UTF-8 encoded */
3334   int nByte,              /* Maximum length of zSql in bytes. */
3335   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
3336   const char **pzTail     /* OUT: Pointer to unused portion of zSql */
3337 );
3338 SQLITE_API int SQLITE_STDCALL sqlite3_prepare16(
3339   sqlite3 *db,            /* Database handle */
3340   const void *zSql,       /* SQL statement, UTF-16 encoded */
3341   int nByte,              /* Maximum length of zSql in bytes. */
3342   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
3343   const void **pzTail     /* OUT: Pointer to unused portion of zSql */
3344 );
3345 SQLITE_API int SQLITE_STDCALL sqlite3_prepare16_v2(
3346   sqlite3 *db,            /* Database handle */
3347   const void *zSql,       /* SQL statement, UTF-16 encoded */
3348   int nByte,              /* Maximum length of zSql in bytes. */
3349   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
3350   const void **pzTail     /* OUT: Pointer to unused portion of zSql */
3351 );
3352
3353 /*
3354 ** CAPI3REF: Retrieving Statement SQL
3355 ** METHOD: sqlite3_stmt
3356 **
3357 ** ^This interface can be used to retrieve a saved copy of the original
3358 ** SQL text used to create a [prepared statement] if that statement was
3359 ** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].
3360 */
3361 SQLITE_API const char *SQLITE_STDCALL sqlite3_sql(sqlite3_stmt *pStmt);
3362
3363 /*
3364 ** CAPI3REF: Determine If An SQL Statement Writes The Database
3365 ** METHOD: sqlite3_stmt
3366 **
3367 ** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
3368 ** and only if the [prepared statement] X makes no direct changes to
3369 ** the content of the database file.
3370 **
3371 ** Note that [application-defined SQL functions] or
3372 ** [virtual tables] might change the database indirectly as a side effect.  
3373 ** ^(For example, if an application defines a function "eval()" that 
3374 ** calls [sqlite3_exec()], then the following SQL statement would
3375 ** change the database file through side-effects:
3376 **
3377 ** <blockquote><pre>
3378 **    SELECT eval('DELETE FROM t1') FROM t2;
3379 ** </pre></blockquote>
3380 **
3381 ** But because the [SELECT] statement does not change the database file
3382 ** directly, sqlite3_stmt_readonly() would still return true.)^
3383 **
3384 ** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],
3385 ** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
3386 ** since the statements themselves do not actually modify the database but
3387 ** rather they control the timing of when other statements modify the 
3388 ** database.  ^The [ATTACH] and [DETACH] statements also cause
3389 ** sqlite3_stmt_readonly() to return true since, while those statements
3390 ** change the configuration of a database connection, they do not make 
3391 ** changes to the content of the database files on disk.
3392 */
3393 SQLITE_API int SQLITE_STDCALL sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
3394
3395 /*
3396 ** CAPI3REF: Determine If A Prepared Statement Has Been Reset
3397 ** METHOD: sqlite3_stmt
3398 **
3399 ** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
3400 ** [prepared statement] S has been stepped at least once using 
3401 ** [sqlite3_step(S)] but has neither run to completion (returned
3402 ** [SQLITE_DONE] from [sqlite3_step(S)]) nor
3403 ** been reset using [sqlite3_reset(S)].  ^The sqlite3_stmt_busy(S)
3404 ** interface returns false if S is a NULL pointer.  If S is not a 
3405 ** NULL pointer and is not a pointer to a valid [prepared statement]
3406 ** object, then the behavior is undefined and probably undesirable.
3407 **
3408 ** This interface can be used in combination [sqlite3_next_stmt()]
3409 ** to locate all prepared statements associated with a database 
3410 ** connection that are in need of being reset.  This can be used,
3411 ** for example, in diagnostic routines to search for prepared 
3412 ** statements that are holding a transaction open.
3413 */
3414 SQLITE_API int SQLITE_STDCALL sqlite3_stmt_busy(sqlite3_stmt*);
3415
3416 /*
3417 ** CAPI3REF: Dynamically Typed Value Object
3418 ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
3419 **
3420 ** SQLite uses the sqlite3_value object to represent all values
3421 ** that can be stored in a database table. SQLite uses dynamic typing
3422 ** for the values it stores.  ^Values stored in sqlite3_value objects
3423 ** can be integers, floating point values, strings, BLOBs, or NULL.
3424 **
3425 ** An sqlite3_value object may be either "protected" or "unprotected".
3426 ** Some interfaces require a protected sqlite3_value.  Other interfaces
3427 ** will accept either a protected or an unprotected sqlite3_value.
3428 ** Every interface that accepts sqlite3_value arguments specifies
3429 ** whether or not it requires a protected sqlite3_value.  The
3430 ** [sqlite3_value_dup()] interface can be used to construct a new 
3431 ** protected sqlite3_value from an unprotected sqlite3_value.
3432 **
3433 ** The terms "protected" and "unprotected" refer to whether or not
3434 ** a mutex is held.  An internal mutex is held for a protected
3435 ** sqlite3_value object but no mutex is held for an unprotected
3436 ** sqlite3_value object.  If SQLite is compiled to be single-threaded
3437 ** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
3438 ** or if SQLite is run in one of reduced mutex modes 
3439 ** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
3440 ** then there is no distinction between protected and unprotected
3441 ** sqlite3_value objects and they can be used interchangeably.  However,
3442 ** for maximum code portability it is recommended that applications
3443 ** still make the distinction between protected and unprotected
3444 ** sqlite3_value objects even when not strictly required.
3445 **
3446 ** ^The sqlite3_value objects that are passed as parameters into the
3447 ** implementation of [application-defined SQL functions] are protected.
3448 ** ^The sqlite3_value object returned by
3449 ** [sqlite3_column_value()] is unprotected.
3450 ** Unprotected sqlite3_value objects may only be used with
3451 ** [sqlite3_result_value()] and [sqlite3_bind_value()].
3452 ** The [sqlite3_value_blob | sqlite3_value_type()] family of
3453 ** interfaces require protected sqlite3_value objects.
3454 */
3455 typedef struct Mem sqlite3_value;
3456
3457 /*
3458 ** CAPI3REF: SQL Function Context Object
3459 **
3460 ** The context in which an SQL function executes is stored in an
3461 ** sqlite3_context object.  ^A pointer to an sqlite3_context object
3462 ** is always first parameter to [application-defined SQL functions].
3463 ** The application-defined SQL function implementation will pass this
3464 ** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
3465 ** [sqlite3_aggregate_context()], [sqlite3_user_data()],
3466 ** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
3467 ** and/or [sqlite3_set_auxdata()].
3468 */
3469 typedef struct sqlite3_context sqlite3_context;
3470
3471 /*
3472 ** CAPI3REF: Binding Values To Prepared Statements
3473 ** KEYWORDS: {host parameter} {host parameters} {host parameter name}
3474 ** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
3475 ** METHOD: sqlite3_stmt
3476 **
3477 ** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
3478 ** literals may be replaced by a [parameter] that matches one of following
3479 ** templates:
3480 **
3481 ** <ul>
3482 ** <li>  ?
3483 ** <li>  ?NNN
3484 ** <li>  :VVV
3485 ** <li>  @VVV
3486 ** <li>  $VVV
3487 ** </ul>
3488 **
3489 ** In the templates above, NNN represents an integer literal,
3490 ** and VVV represents an alphanumeric identifier.)^  ^The values of these
3491 ** parameters (also called "host parameter names" or "SQL parameters")
3492 ** can be set using the sqlite3_bind_*() routines defined here.
3493 **
3494 ** ^The first argument to the sqlite3_bind_*() routines is always
3495 ** a pointer to the [sqlite3_stmt] object returned from
3496 ** [sqlite3_prepare_v2()] or its variants.
3497 **
3498 ** ^The second argument is the index of the SQL parameter to be set.
3499 ** ^The leftmost SQL parameter has an index of 1.  ^When the same named
3500 ** SQL parameter is used more than once, second and subsequent
3501 ** occurrences have the same index as the first occurrence.
3502 ** ^The index for named parameters can be looked up using the
3503 ** [sqlite3_bind_parameter_index()] API if desired.  ^The index
3504 ** for "?NNN" parameters is the value of NNN.
3505 ** ^The NNN value must be between 1 and the [sqlite3_limit()]
3506 ** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999).
3507 **
3508 ** ^The third argument is the value to bind to the parameter.
3509 ** ^If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
3510 ** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
3511 ** is ignored and the end result is the same as sqlite3_bind_null().
3512 **
3513 ** ^(In those routines that have a fourth argument, its value is the
3514 ** number of bytes in the parameter.  To be clear: the value is the
3515 ** number of <u>bytes</u> in the value, not the number of characters.)^
3516 ** ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
3517 ** is negative, then the length of the string is
3518 ** the number of bytes up to the first zero terminator.
3519 ** If the fourth parameter to sqlite3_bind_blob() is negative, then
3520 ** the behavior is undefined.
3521 ** If a non-negative fourth parameter is provided to sqlite3_bind_text()
3522 ** or sqlite3_bind_text16() or sqlite3_bind_text64() then
3523 ** that parameter must be the byte offset
3524 ** where the NUL terminator would occur assuming the string were NUL
3525 ** terminated.  If any NUL characters occur at byte offsets less than 
3526 ** the value of the fourth parameter then the resulting string value will
3527 ** contain embedded NULs.  The result of expressions involving strings
3528 ** with embedded NULs is undefined.
3529 **
3530 ** ^The fifth argument to the BLOB and string binding interfaces
3531 ** is a destructor used to dispose of the BLOB or
3532 ** string after SQLite has finished with it.  ^The destructor is called
3533 ** to dispose of the BLOB or string even if the call to bind API fails.
3534 ** ^If the fifth argument is
3535 ** the special value [SQLITE_STATIC], then SQLite assumes that the
3536 ** information is in static, unmanaged space and does not need to be freed.
3537 ** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
3538 ** SQLite makes its own private copy of the data immediately, before
3539 ** the sqlite3_bind_*() routine returns.
3540 **
3541 ** ^The sixth argument to sqlite3_bind_text64() must be one of
3542 ** [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE]
3543 ** to specify the encoding of the text in the third parameter.  If
3544 ** the sixth argument to sqlite3_bind_text64() is not one of the
3545 ** allowed values shown above, or if the text encoding is different
3546 ** from the encoding specified by the sixth parameter, then the behavior
3547 ** is undefined.
3548 **
3549 ** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
3550 ** is filled with zeroes.  ^A zeroblob uses a fixed amount of memory
3551 ** (just an integer to hold its size) while it is being processed.
3552 ** Zeroblobs are intended to serve as placeholders for BLOBs whose
3553 ** content is later written using
3554 ** [sqlite3_blob_open | incremental BLOB I/O] routines.
3555 ** ^A negative value for the zeroblob results in a zero-length BLOB.
3556 **
3557 ** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
3558 ** for the [prepared statement] or with a prepared statement for which
3559 ** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
3560 ** then the call will return [SQLITE_MISUSE].  If any sqlite3_bind_()
3561 ** routine is passed a [prepared statement] that has been finalized, the
3562 ** result is undefined and probably harmful.
3563 **
3564 ** ^Bindings are not cleared by the [sqlite3_reset()] routine.
3565 ** ^Unbound parameters are interpreted as NULL.
3566 **
3567 ** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
3568 ** [error code] if anything goes wrong.
3569 ** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB
3570 ** exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or
3571 ** [SQLITE_MAX_LENGTH].
3572 ** ^[SQLITE_RANGE] is returned if the parameter
3573 ** index is out of range.  ^[SQLITE_NOMEM] is returned if malloc() fails.
3574 **
3575 ** See also: [sqlite3_bind_parameter_count()],
3576 ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
3577 */
3578 SQLITE_API int SQLITE_STDCALL sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
3579 SQLITE_API int SQLITE_STDCALL sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
3580                         void(*)(void*));
3581 SQLITE_API int SQLITE_STDCALL sqlite3_bind_double(sqlite3_stmt*, int, double);
3582 SQLITE_API int SQLITE_STDCALL sqlite3_bind_int(sqlite3_stmt*, int, int);
3583 SQLITE_API int SQLITE_STDCALL sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
3584 SQLITE_API int SQLITE_STDCALL sqlite3_bind_null(sqlite3_stmt*, int);
3585 SQLITE_API int SQLITE_STDCALL sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
3586 SQLITE_API int SQLITE_STDCALL sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
3587 SQLITE_API int SQLITE_STDCALL sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
3588                          void(*)(void*), unsigned char encoding);
3589 SQLITE_API int SQLITE_STDCALL sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
3590 SQLITE_API int SQLITE_STDCALL sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
3591 SQLITE_API int SQLITE_STDCALL sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
3592
3593 /*
3594 ** CAPI3REF: Number Of SQL Parameters
3595 ** METHOD: sqlite3_stmt
3596 **
3597 ** ^This routine can be used to find the number of [SQL parameters]
3598 ** in a [prepared statement].  SQL parameters are tokens of the
3599 ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
3600 ** placeholders for values that are [sqlite3_bind_blob | bound]
3601 ** to the parameters at a later time.
3602 **
3603 ** ^(This routine actually returns the index of the largest (rightmost)
3604 ** parameter. For all forms except ?NNN, this will correspond to the
3605 ** number of unique parameters.  If parameters of the ?NNN form are used,
3606 ** there may be gaps in the list.)^
3607 **
3608 ** See also: [sqlite3_bind_blob|sqlite3_bind()],
3609 ** [sqlite3_bind_parameter_name()], and
3610 ** [sqlite3_bind_parameter_index()].
3611 */
3612 SQLITE_API int SQLITE_STDCALL sqlite3_bind_parameter_count(sqlite3_stmt*);
3613
3614 /*
3615 ** CAPI3REF: Name Of A Host Parameter
3616 ** METHOD: sqlite3_stmt
3617 **
3618 ** ^The sqlite3_bind_parameter_name(P,N) interface returns
3619 ** the name of the N-th [SQL parameter] in the [prepared statement] P.
3620 ** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
3621 ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
3622 ** respectively.
3623 ** In other words, the initial ":" or "$" or "@" or "?"
3624 ** is included as part of the name.)^
3625 ** ^Parameters of the form "?" without a following integer have no name
3626 ** and are referred to as "nameless" or "anonymous parameters".
3627 **
3628 ** ^The first host parameter has an index of 1, not 0.
3629 **
3630 ** ^If the value N is out of range or if the N-th parameter is
3631 ** nameless, then NULL is returned.  ^The returned string is
3632 ** always in UTF-8 encoding even if the named parameter was
3633 ** originally specified as UTF-16 in [sqlite3_prepare16()] or
3634 ** [sqlite3_prepare16_v2()].
3635 **
3636 ** See also: [sqlite3_bind_blob|sqlite3_bind()],
3637 ** [sqlite3_bind_parameter_count()], and
3638 ** [sqlite3_bind_parameter_index()].
3639 */
3640 SQLITE_API const char *SQLITE_STDCALL sqlite3_bind_parameter_name(sqlite3_stmt*, int);
3641
3642 /*
3643 ** CAPI3REF: Index Of A Parameter With A Given Name
3644 ** METHOD: sqlite3_stmt
3645 **
3646 ** ^Return the index of an SQL parameter given its name.  ^The
3647 ** index value returned is suitable for use as the second
3648 ** parameter to [sqlite3_bind_blob|sqlite3_bind()].  ^A zero
3649 ** is returned if no matching parameter is found.  ^The parameter
3650 ** name must be given in UTF-8 even if the original statement
3651 ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
3652 **
3653 ** See also: [sqlite3_bind_blob|sqlite3_bind()],
3654 ** [sqlite3_bind_parameter_count()], and
3655 ** [sqlite3_bind_parameter_name()].
3656 */
3657 SQLITE_API int SQLITE_STDCALL sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
3658
3659 /*
3660 ** CAPI3REF: Reset All Bindings On A Prepared Statement
3661 ** METHOD: sqlite3_stmt
3662 **
3663 ** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
3664 ** the [sqlite3_bind_blob | bindings] on a [prepared statement].
3665 ** ^Use this routine to reset all host parameters to NULL.
3666 */
3667 SQLITE_API int SQLITE_STDCALL sqlite3_clear_bindings(sqlite3_stmt*);
3668
3669 /*
3670 ** CAPI3REF: Number Of Columns In A Result Set
3671 ** METHOD: sqlite3_stmt
3672 **
3673 ** ^Return the number of columns in the result set returned by the
3674 ** [prepared statement]. ^This routine returns 0 if pStmt is an SQL
3675 ** statement that does not return data (for example an [UPDATE]).
3676 **
3677 ** See also: [sqlite3_data_count()]
3678 */
3679 SQLITE_API int SQLITE_STDCALL sqlite3_column_count(sqlite3_stmt *pStmt);
3680
3681 /*
3682 ** CAPI3REF: Column Names In A Result Set
3683 ** METHOD: sqlite3_stmt
3684 **
3685 ** ^These routines return the name assigned to a particular column
3686 ** in the result set of a [SELECT] statement.  ^The sqlite3_column_name()
3687 ** interface returns a pointer to a zero-terminated UTF-8 string
3688 ** and sqlite3_column_name16() returns a pointer to a zero-terminated
3689 ** UTF-16 string.  ^The first parameter is the [prepared statement]
3690 ** that implements the [SELECT] statement. ^The second parameter is the
3691 ** column number.  ^The leftmost column is number 0.
3692 **
3693 ** ^The returned string pointer is valid until either the [prepared statement]
3694 ** is destroyed by [sqlite3_finalize()] or until the statement is automatically
3695 ** reprepared by the first call to [sqlite3_step()] for a particular run
3696 ** or until the next call to
3697 ** sqlite3_column_name() or sqlite3_column_name16() on the same column.
3698 **
3699 ** ^If sqlite3_malloc() fails during the processing of either routine
3700 ** (for example during a conversion from UTF-8 to UTF-16) then a
3701 ** NULL pointer is returned.
3702 **
3703 ** ^The name of a result column is the value of the "AS" clause for
3704 ** that column, if there is an AS clause.  If there is no AS clause
3705 ** then the name of the column is unspecified and may change from
3706 ** one release of SQLite to the next.
3707 */
3708 SQLITE_API const char *SQLITE_STDCALL sqlite3_column_name(sqlite3_stmt*, int N);
3709 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_name16(sqlite3_stmt*, int N);
3710
3711 /*
3712 ** CAPI3REF: Source Of Data In A Query Result
3713 ** METHOD: sqlite3_stmt
3714 **
3715 ** ^These routines provide a means to determine the database, table, and
3716 ** table column that is the origin of a particular result column in
3717 ** [SELECT] statement.
3718 ** ^The name of the database or table or column can be returned as
3719 ** either a UTF-8 or UTF-16 string.  ^The _database_ routines return
3720 ** the database name, the _table_ routines return the table name, and
3721 ** the origin_ routines return the column name.
3722 ** ^The returned string is valid until the [prepared statement] is destroyed
3723 ** using [sqlite3_finalize()] or until the statement is automatically
3724 ** reprepared by the first call to [sqlite3_step()] for a particular run
3725 ** or until the same information is requested
3726 ** again in a different encoding.
3727 **
3728 ** ^The names returned are the original un-aliased names of the
3729 ** database, table, and column.
3730 **
3731 ** ^The first argument to these interfaces is a [prepared statement].
3732 ** ^These functions return information about the Nth result column returned by
3733 ** the statement, where N is the second function argument.
3734 ** ^The left-most column is column 0 for these routines.
3735 **
3736 ** ^If the Nth column returned by the statement is an expression or
3737 ** subquery and is not a column value, then all of these functions return
3738 ** NULL.  ^These routine might also return NULL if a memory allocation error
3739 ** occurs.  ^Otherwise, they return the name of the attached database, table,
3740 ** or column that query result column was extracted from.
3741 **
3742 ** ^As with all other SQLite APIs, those whose names end with "16" return
3743 ** UTF-16 encoded strings and the other functions return UTF-8.
3744 **
3745 ** ^These APIs are only available if the library was compiled with the
3746 ** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
3747 **
3748 ** If two or more threads call one or more of these routines against the same
3749 ** prepared statement and column at the same time then the results are
3750 ** undefined.
3751 **
3752 ** If two or more threads call one or more
3753 ** [sqlite3_column_database_name | column metadata interfaces]
3754 ** for the same [prepared statement] and result column
3755 ** at the same time then the results are undefined.
3756 */
3757 SQLITE_API const char *SQLITE_STDCALL sqlite3_column_database_name(sqlite3_stmt*,int);
3758 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_database_name16(sqlite3_stmt*,int);
3759 SQLITE_API const char *SQLITE_STDCALL sqlite3_column_table_name(sqlite3_stmt*,int);
3760 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_table_name16(sqlite3_stmt*,int);
3761 SQLITE_API const char *SQLITE_STDCALL sqlite3_column_origin_name(sqlite3_stmt*,int);
3762 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_origin_name16(sqlite3_stmt*,int);
3763
3764 /*
3765 ** CAPI3REF: Declared Datatype Of A Query Result
3766 ** METHOD: sqlite3_stmt
3767 **
3768 ** ^(The first parameter is a [prepared statement].
3769 ** If this statement is a [SELECT] statement and the Nth column of the
3770 ** returned result set of that [SELECT] is a table column (not an
3771 ** expression or subquery) then the declared type of the table
3772 ** column is returned.)^  ^If the Nth column of the result set is an
3773 ** expression or subquery, then a NULL pointer is returned.
3774 ** ^The returned string is always UTF-8 encoded.
3775 **
3776 ** ^(For example, given the database schema:
3777 **
3778 ** CREATE TABLE t1(c1 VARIANT);
3779 **
3780 ** and the following statement to be compiled:
3781 **
3782 ** SELECT c1 + 1, c1 FROM t1;
3783 **
3784 ** this routine would return the string "VARIANT" for the second result
3785 ** column (i==1), and a NULL pointer for the first result column (i==0).)^
3786 **
3787 ** ^SQLite uses dynamic run-time typing.  ^So just because a column
3788 ** is declared to contain a particular type does not mean that the
3789 ** data stored in that column is of the declared type.  SQLite is
3790 ** strongly typed, but the typing is dynamic not static.  ^Type
3791 ** is associated with individual values, not with the containers
3792 ** used to hold those values.
3793 */
3794 SQLITE_API const char *SQLITE_STDCALL sqlite3_column_decltype(sqlite3_stmt*,int);
3795 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_decltype16(sqlite3_stmt*,int);
3796
3797 /*
3798 ** CAPI3REF: Evaluate An SQL Statement
3799 ** METHOD: sqlite3_stmt
3800 **
3801 ** After a [prepared statement] has been prepared using either
3802 ** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
3803 ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
3804 ** must be called one or more times to evaluate the statement.
3805 **
3806 ** The details of the behavior of the sqlite3_step() interface depend
3807 ** on whether the statement was prepared using the newer "v2" interface
3808 ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
3809 ** interface [sqlite3_prepare()] and [sqlite3_prepare16()].  The use of the
3810 ** new "v2" interface is recommended for new applications but the legacy
3811 ** interface will continue to be supported.
3812 **
3813 ** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
3814 ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
3815 ** ^With the "v2" interface, any of the other [result codes] or
3816 ** [extended result codes] might be returned as well.
3817 **
3818 ** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
3819 ** database locks it needs to do its job.  ^If the statement is a [COMMIT]
3820 ** or occurs outside of an explicit transaction, then you can retry the
3821 ** statement.  If the statement is not a [COMMIT] and occurs within an
3822 ** explicit transaction then you should rollback the transaction before
3823 ** continuing.
3824 **
3825 ** ^[SQLITE_DONE] means that the statement has finished executing
3826 ** successfully.  sqlite3_step() should not be called again on this virtual
3827 ** machine without first calling [sqlite3_reset()] to reset the virtual
3828 ** machine back to its initial state.
3829 **
3830 ** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]
3831 ** is returned each time a new row of data is ready for processing by the
3832 ** caller. The values may be accessed using the [column access functions].
3833 ** sqlite3_step() is called again to retrieve the next row of data.
3834 **
3835 ** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
3836 ** violation) has occurred.  sqlite3_step() should not be called again on
3837 ** the VM. More information may be found by calling [sqlite3_errmsg()].
3838 ** ^With the legacy interface, a more specific error code (for example,
3839 ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
3840 ** can be obtained by calling [sqlite3_reset()] on the
3841 ** [prepared statement].  ^In the "v2" interface,
3842 ** the more specific error code is returned directly by sqlite3_step().
3843 **
3844 ** [SQLITE_MISUSE] means that the this routine was called inappropriately.
3845 ** Perhaps it was called on a [prepared statement] that has
3846 ** already been [sqlite3_finalize | finalized] or on one that had
3847 ** previously returned [SQLITE_ERROR] or [SQLITE_DONE].  Or it could
3848 ** be the case that the same database connection is being used by two or
3849 ** more threads at the same moment in time.
3850 **
3851 ** For all versions of SQLite up to and including 3.6.23.1, a call to
3852 ** [sqlite3_reset()] was required after sqlite3_step() returned anything
3853 ** other than [SQLITE_ROW] before any subsequent invocation of
3854 ** sqlite3_step().  Failure to reset the prepared statement using 
3855 ** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from
3856 ** sqlite3_step().  But after version 3.6.23.1, sqlite3_step() began
3857 ** calling [sqlite3_reset()] automatically in this circumstance rather
3858 ** than returning [SQLITE_MISUSE].  This is not considered a compatibility
3859 ** break because any application that ever receives an SQLITE_MISUSE error
3860 ** is broken by definition.  The [SQLITE_OMIT_AUTORESET] compile-time option
3861 ** can be used to restore the legacy behavior.
3862 **
3863 ** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
3864 ** API always returns a generic error code, [SQLITE_ERROR], following any
3865 ** error other than [SQLITE_BUSY] and [SQLITE_MISUSE].  You must call
3866 ** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
3867 ** specific [error codes] that better describes the error.
3868 ** We admit that this is a goofy design.  The problem has been fixed
3869 ** with the "v2" interface.  If you prepare all of your SQL statements
3870 ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
3871 ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
3872 ** then the more specific [error codes] are returned directly
3873 ** by sqlite3_step().  The use of the "v2" interface is recommended.
3874 */
3875 SQLITE_API int SQLITE_STDCALL sqlite3_step(sqlite3_stmt*);
3876
3877 /*
3878 ** CAPI3REF: Number of columns in a result set
3879 ** METHOD: sqlite3_stmt
3880 **
3881 ** ^The sqlite3_data_count(P) interface returns the number of columns in the
3882 ** current row of the result set of [prepared statement] P.
3883 ** ^If prepared statement P does not have results ready to return
3884 ** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of
3885 ** interfaces) then sqlite3_data_count(P) returns 0.
3886 ** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
3887 ** ^The sqlite3_data_count(P) routine returns 0 if the previous call to
3888 ** [sqlite3_step](P) returned [SQLITE_DONE].  ^The sqlite3_data_count(P)
3889 ** will return non-zero if previous call to [sqlite3_step](P) returned
3890 ** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum]
3891 ** where it always returns zero since each step of that multi-step
3892 ** pragma returns 0 columns of data.
3893 **
3894 ** See also: [sqlite3_column_count()]
3895 */
3896 SQLITE_API int SQLITE_STDCALL sqlite3_data_count(sqlite3_stmt *pStmt);
3897
3898 /*
3899 ** CAPI3REF: Fundamental Datatypes
3900 ** KEYWORDS: SQLITE_TEXT
3901 **
3902 ** ^(Every value in SQLite has one of five fundamental datatypes:
3903 **
3904 ** <ul>
3905 ** <li> 64-bit signed integer
3906 ** <li> 64-bit IEEE floating point number
3907 ** <li> string
3908 ** <li> BLOB
3909 ** <li> NULL
3910 ** </ul>)^
3911 **
3912 ** These constants are codes for each of those types.
3913 **
3914 ** Note that the SQLITE_TEXT constant was also used in SQLite version 2
3915 ** for a completely different meaning.  Software that links against both
3916 ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
3917 ** SQLITE_TEXT.
3918 */
3919 #define SQLITE_INTEGER  1
3920 #define SQLITE_FLOAT    2
3921 #define SQLITE_BLOB     4
3922 #define SQLITE_NULL     5
3923 #ifdef SQLITE_TEXT
3924 # undef SQLITE_TEXT
3925 #else
3926 # define SQLITE_TEXT     3
3927 #endif
3928 #define SQLITE3_TEXT     3
3929
3930 /*
3931 ** CAPI3REF: Result Values From A Query
3932 ** KEYWORDS: {column access functions}
3933 ** METHOD: sqlite3_stmt
3934 **
3935 ** ^These routines return information about a single column of the current
3936 ** result row of a query.  ^In every case the first argument is a pointer
3937 ** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
3938 ** that was returned from [sqlite3_prepare_v2()] or one of its variants)
3939 ** and the second argument is the index of the column for which information
3940 ** should be returned. ^The leftmost column of the result set has the index 0.
3941 ** ^The number of columns in the result can be determined using
3942 ** [sqlite3_column_count()].
3943 **
3944 ** If the SQL statement does not currently point to a valid row, or if the
3945 ** column index is out of range, the result is undefined.
3946 ** These routines may only be called when the most recent call to
3947 ** [sqlite3_step()] has returned [SQLITE_ROW] and neither
3948 ** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.
3949 ** If any of these routines are called after [sqlite3_reset()] or
3950 ** [sqlite3_finalize()] or after [sqlite3_step()] has returned
3951 ** something other than [SQLITE_ROW], the results are undefined.
3952 ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
3953 ** are called from a different thread while any of these routines
3954 ** are pending, then the results are undefined.
3955 **
3956 ** ^The sqlite3_column_type() routine returns the
3957 ** [SQLITE_INTEGER | datatype code] for the initial data type
3958 ** of the result column.  ^The returned value is one of [SQLITE_INTEGER],
3959 ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].  The value
3960 ** returned by sqlite3_column_type() is only meaningful if no type
3961 ** conversions have occurred as described below.  After a type conversion,
3962 ** the value returned by sqlite3_column_type() is undefined.  Future
3963 ** versions of SQLite may change the behavior of sqlite3_column_type()
3964 ** following a type conversion.
3965 **
3966 ** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
3967 ** routine returns the number of bytes in that BLOB or string.
3968 ** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
3969 ** the string to UTF-8 and then returns the number of bytes.
3970 ** ^If the result is a numeric value then sqlite3_column_bytes() uses
3971 ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
3972 ** the number of bytes in that string.
3973 ** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
3974 **
3975 ** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
3976 ** routine returns the number of bytes in that BLOB or string.
3977 ** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
3978 ** the string to UTF-16 and then returns the number of bytes.
3979 ** ^If the result is a numeric value then sqlite3_column_bytes16() uses
3980 ** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
3981 ** the number of bytes in that string.
3982 ** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
3983 **
3984 ** ^The values returned by [sqlite3_column_bytes()] and 
3985 ** [sqlite3_column_bytes16()] do not include the zero terminators at the end
3986 ** of the string.  ^For clarity: the values returned by
3987 ** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of
3988 ** bytes in the string, not the number of characters.
3989 **
3990 ** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
3991 ** even empty strings, are always zero-terminated.  ^The return
3992 ** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
3993 **
3994 ** <b>Warning:</b> ^The object returned by [sqlite3_column_value()] is an
3995 ** [unprotected sqlite3_value] object.  In a multithreaded environment,
3996 ** an unprotected sqlite3_value object may only be used safely with
3997 ** [sqlite3_bind_value()] and [sqlite3_result_value()].
3998 ** If the [unprotected sqlite3_value] object returned by
3999 ** [sqlite3_column_value()] is used in any other way, including calls
4000 ** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
4001 ** or [sqlite3_value_bytes()], the behavior is not threadsafe.
4002 **
4003 ** These routines attempt to convert the value where appropriate.  ^For
4004 ** example, if the internal representation is FLOAT and a text result
4005 ** is requested, [sqlite3_snprintf()] is used internally to perform the
4006 ** conversion automatically.  ^(The following table details the conversions
4007 ** that are applied:
4008 **
4009 ** <blockquote>
4010 ** <table border="1">
4011 ** <tr><th> Internal<br>Type <th> Requested<br>Type <th>  Conversion
4012 **
4013 ** <tr><td>  NULL    <td> INTEGER   <td> Result is 0
4014 ** <tr><td>  NULL    <td>  FLOAT    <td> Result is 0.0
4015 ** <tr><td>  NULL    <td>   TEXT    <td> Result is a NULL pointer
4016 ** <tr><td>  NULL    <td>   BLOB    <td> Result is a NULL pointer
4017 ** <tr><td> INTEGER  <td>  FLOAT    <td> Convert from integer to float
4018 ** <tr><td> INTEGER  <td>   TEXT    <td> ASCII rendering of the integer
4019 ** <tr><td> INTEGER  <td>   BLOB    <td> Same as INTEGER->TEXT
4020 ** <tr><td>  FLOAT   <td> INTEGER   <td> [CAST] to INTEGER
4021 ** <tr><td>  FLOAT   <td>   TEXT    <td> ASCII rendering of the float
4022 ** <tr><td>  FLOAT   <td>   BLOB    <td> [CAST] to BLOB
4023 ** <tr><td>  TEXT    <td> INTEGER   <td> [CAST] to INTEGER
4024 ** <tr><td>  TEXT    <td>  FLOAT    <td> [CAST] to REAL
4025 ** <tr><td>  TEXT    <td>   BLOB    <td> No change
4026 ** <tr><td>  BLOB    <td> INTEGER   <td> [CAST] to INTEGER
4027 ** <tr><td>  BLOB    <td>  FLOAT    <td> [CAST] to REAL
4028 ** <tr><td>  BLOB    <td>   TEXT    <td> Add a zero terminator if needed
4029 ** </table>
4030 ** </blockquote>)^
4031 **
4032 ** Note that when type conversions occur, pointers returned by prior
4033 ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
4034 ** sqlite3_column_text16() may be invalidated.
4035 ** Type conversions and pointer invalidations might occur
4036 ** in the following cases:
4037 **
4038 ** <ul>
4039 ** <li> The initial content is a BLOB and sqlite3_column_text() or
4040 **      sqlite3_column_text16() is called.  A zero-terminator might
4041 **      need to be added to the string.</li>
4042 ** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
4043 **      sqlite3_column_text16() is called.  The content must be converted
4044 **      to UTF-16.</li>
4045 ** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
4046 **      sqlite3_column_text() is called.  The content must be converted
4047 **      to UTF-8.</li>
4048 ** </ul>
4049 **
4050 ** ^Conversions between UTF-16be and UTF-16le are always done in place and do
4051 ** not invalidate a prior pointer, though of course the content of the buffer
4052 ** that the prior pointer references will have been modified.  Other kinds
4053 ** of conversion are done in place when it is possible, but sometimes they
4054 ** are not possible and in those cases prior pointers are invalidated.
4055 **
4056 ** The safest policy is to invoke these routines
4057 ** in one of the following ways:
4058 **
4059 ** <ul>
4060 **  <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
4061 **  <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
4062 **  <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
4063 ** </ul>
4064 **
4065 ** In other words, you should call sqlite3_column_text(),
4066 ** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
4067 ** into the desired format, then invoke sqlite3_column_bytes() or
4068 ** sqlite3_column_bytes16() to find the size of the result.  Do not mix calls
4069 ** to sqlite3_column_text() or sqlite3_column_blob() with calls to
4070 ** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
4071 ** with calls to sqlite3_column_bytes().
4072 **
4073 ** ^The pointers returned are valid until a type conversion occurs as
4074 ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
4075 ** [sqlite3_finalize()] is called.  ^The memory space used to hold strings
4076 ** and BLOBs is freed automatically.  Do <em>not</em> pass the pointers returned
4077 ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
4078 ** [sqlite3_free()].
4079 **
4080 ** ^(If a memory allocation error occurs during the evaluation of any
4081 ** of these routines, a default value is returned.  The default value
4082 ** is either the integer 0, the floating point number 0.0, or a NULL
4083 ** pointer.  Subsequent calls to [sqlite3_errcode()] will return
4084 ** [SQLITE_NOMEM].)^
4085 */
4086 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_blob(sqlite3_stmt*, int iCol);
4087 SQLITE_API int SQLITE_STDCALL sqlite3_column_bytes(sqlite3_stmt*, int iCol);
4088 SQLITE_API int SQLITE_STDCALL sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
4089 SQLITE_API double SQLITE_STDCALL sqlite3_column_double(sqlite3_stmt*, int iCol);
4090 SQLITE_API int SQLITE_STDCALL sqlite3_column_int(sqlite3_stmt*, int iCol);
4091 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_column_int64(sqlite3_stmt*, int iCol);
4092 SQLITE_API const unsigned char *SQLITE_STDCALL sqlite3_column_text(sqlite3_stmt*, int iCol);
4093 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_text16(sqlite3_stmt*, int iCol);
4094 SQLITE_API int SQLITE_STDCALL sqlite3_column_type(sqlite3_stmt*, int iCol);
4095 SQLITE_API sqlite3_value *SQLITE_STDCALL sqlite3_column_value(sqlite3_stmt*, int iCol);
4096
4097 /*
4098 ** CAPI3REF: Destroy A Prepared Statement Object
4099 ** DESTRUCTOR: sqlite3_stmt
4100 **
4101 ** ^The sqlite3_finalize() function is called to delete a [prepared statement].
4102 ** ^If the most recent evaluation of the statement encountered no errors
4103 ** or if the statement is never been evaluated, then sqlite3_finalize() returns
4104 ** SQLITE_OK.  ^If the most recent evaluation of statement S failed, then
4105 ** sqlite3_finalize(S) returns the appropriate [error code] or
4106 ** [extended error code].
4107 **
4108 ** ^The sqlite3_finalize(S) routine can be called at any point during
4109 ** the life cycle of [prepared statement] S:
4110 ** before statement S is ever evaluated, after
4111 ** one or more calls to [sqlite3_reset()], or after any call
4112 ** to [sqlite3_step()] regardless of whether or not the statement has
4113 ** completed execution.
4114 **
4115 ** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
4116 **
4117 ** The application must finalize every [prepared statement] in order to avoid
4118 ** resource leaks.  It is a grievous error for the application to try to use
4119 ** a prepared statement after it has been finalized.  Any use of a prepared
4120 ** statement after it has been finalized can result in undefined and
4121 ** undesirable behavior such as segfaults and heap corruption.
4122 */
4123 SQLITE_API int SQLITE_STDCALL sqlite3_finalize(sqlite3_stmt *pStmt);
4124
4125 /*
4126 ** CAPI3REF: Reset A Prepared Statement Object
4127 ** METHOD: sqlite3_stmt
4128 **
4129 ** The sqlite3_reset() function is called to reset a [prepared statement]
4130 ** object back to its initial state, ready to be re-executed.
4131 ** ^Any SQL statement variables that had values bound to them using
4132 ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
4133 ** Use [sqlite3_clear_bindings()] to reset the bindings.