"Fossies" - the Fresh Open Source Software Archive

Member "sqlite-autoconf-3320300/sqlite3.h" (18 Jun 2020, 581196 Bytes) of package /linux/misc/sqlite-autoconf-3320300.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "sqlite3.h" see the Fossies "Dox" file reference documentation and the last Fossies "Diffs" side-by-side code changes report: autoconf3250300_vs_3260000.

    1 /*
    2 ** 2001-09-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_APICALL
   58 # define SQLITE_APICALL
   59 #endif
   60 #ifndef SQLITE_STDCALL
   61 # define SQLITE_STDCALL SQLITE_APICALL
   62 #endif
   63 #ifndef SQLITE_CALLBACK
   64 # define SQLITE_CALLBACK
   65 #endif
   66 #ifndef SQLITE_SYSAPI
   67 # define SQLITE_SYSAPI
   68 #endif
   69 
   70 /*
   71 ** These no-op macros are used in front of interfaces to mark those
   72 ** interfaces as either deprecated or experimental.  New applications
   73 ** should not use deprecated interfaces - they are supported for backwards
   74 ** compatibility only.  Application writers should be aware that
   75 ** experimental interfaces are subject to change in point releases.
   76 **
   77 ** These macros used to resolve to various kinds of compiler magic that
   78 ** would generate warning messages when they were used.  But that
   79 ** compiler magic ended up generating such a flurry of bug reports
   80 ** that we have taken it all out and gone back to using simple
   81 ** noop macros.
   82 */
   83 #define SQLITE_DEPRECATED
   84 #define SQLITE_EXPERIMENTAL
   85 
   86 /*
   87 ** Ensure these symbols were not defined by some previous header file.
   88 */
   89 #ifdef SQLITE_VERSION
   90 # undef SQLITE_VERSION
   91 #endif
   92 #ifdef SQLITE_VERSION_NUMBER
   93 # undef SQLITE_VERSION_NUMBER
   94 #endif
   95 
   96 /*
   97 ** CAPI3REF: Compile-Time Library Version Numbers
   98 **
   99 ** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
  100 ** evaluates to a string literal that is the SQLite version in the
  101 ** format "X.Y.Z" where X is the major version number (always 3 for
  102 ** SQLite3) and Y is the minor version number and Z is the release number.)^
  103 ** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
  104 ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
  105 ** numbers used in [SQLITE_VERSION].)^
  106 ** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
  107 ** be larger than the release from which it is derived.  Either Y will
  108 ** be held constant and Z will be incremented or else Y will be incremented
  109 ** and Z will be reset to zero.
  110 **
  111 ** Since [version 3.6.18] ([dateof:3.6.18]), 
  112 ** SQLite source code has been stored in the
  113 ** <a href="http://www.fossil-scm.org/">Fossil configuration management
  114 ** system</a>.  ^The SQLITE_SOURCE_ID macro evaluates to
  115 ** a string which identifies a particular check-in of SQLite
  116 ** within its configuration management system.  ^The SQLITE_SOURCE_ID
  117 ** string contains the date and time of the check-in (UTC) and a SHA1
  118 ** or SHA3-256 hash of the entire source tree.  If the source code has
  119 ** been edited in any way since it was last checked in, then the last
  120 ** four hexadecimal digits of the hash may be modified.
  121 **
  122 ** See also: [sqlite3_libversion()],
  123 ** [sqlite3_libversion_number()], [sqlite3_sourceid()],
  124 ** [sqlite_version()] and [sqlite_source_id()].
  125 */
  126 #define SQLITE_VERSION        "3.32.3"
  127 #define SQLITE_VERSION_NUMBER 3032003
  128 #define SQLITE_SOURCE_ID      "2020-06-18 14:00:33 7ebdfa80be8e8e73324b8d66b3460222eb74c7e9dfd655b48d6ca7e1933cc8fd"
  129 
  130 /*
  131 ** CAPI3REF: Run-Time Library Version Numbers
  132 ** KEYWORDS: sqlite3_version sqlite3_sourceid
  133 **
  134 ** These interfaces provide the same information as the [SQLITE_VERSION],
  135 ** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
  136 ** but are associated with the library instead of the header file.  ^(Cautious
  137 ** programmers might include assert() statements in their application to
  138 ** verify that values returned by these interfaces match the macros in
  139 ** the header, and thus ensure that the application is
  140 ** compiled with matching library and header files.
  141 **
  142 ** <blockquote><pre>
  143 ** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
  144 ** assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 );
  145 ** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
  146 ** </pre></blockquote>)^
  147 **
  148 ** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
  149 ** macro.  ^The sqlite3_libversion() function returns a pointer to the
  150 ** to the sqlite3_version[] string constant.  The sqlite3_libversion()
  151 ** function is provided for use in DLLs since DLL users usually do not have
  152 ** direct access to string constants within the DLL.  ^The
  153 ** sqlite3_libversion_number() function returns an integer equal to
  154 ** [SQLITE_VERSION_NUMBER].  ^(The sqlite3_sourceid() function returns 
  155 ** a pointer to a string constant whose value is the same as the 
  156 ** [SQLITE_SOURCE_ID] C preprocessor macro.  Except if SQLite is built
  157 ** using an edited copy of [the amalgamation], then the last four characters
  158 ** of the hash might be different from [SQLITE_SOURCE_ID].)^
  159 **
  160 ** See also: [sqlite_version()] and [sqlite_source_id()].
  161 */
  162 SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
  163 SQLITE_API const char *sqlite3_libversion(void);
  164 SQLITE_API const char *sqlite3_sourceid(void);
  165 SQLITE_API int sqlite3_libversion_number(void);
  166 
  167 /*
  168 ** CAPI3REF: Run-Time Library Compilation Options Diagnostics
  169 **
  170 ** ^The sqlite3_compileoption_used() function returns 0 or 1 
  171 ** indicating whether the specified option was defined at 
  172 ** compile time.  ^The SQLITE_ prefix may be omitted from the 
  173 ** option name passed to sqlite3_compileoption_used().  
  174 **
  175 ** ^The sqlite3_compileoption_get() function allows iterating
  176 ** over the list of options that were defined at compile time by
  177 ** returning the N-th compile time option string.  ^If N is out of range,
  178 ** sqlite3_compileoption_get() returns a NULL pointer.  ^The SQLITE_ 
  179 ** prefix is omitted from any strings returned by 
  180 ** sqlite3_compileoption_get().
  181 **
  182 ** ^Support for the diagnostic functions sqlite3_compileoption_used()
  183 ** and sqlite3_compileoption_get() may be omitted by specifying the 
  184 ** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
  185 **
  186 ** See also: SQL functions [sqlite_compileoption_used()] and
  187 ** [sqlite_compileoption_get()] and the [compile_options pragma].
  188 */
  189 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
  190 SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
  191 SQLITE_API const char *sqlite3_compileoption_get(int N);
  192 #else
  193 # define sqlite3_compileoption_used(X) 0
  194 # define sqlite3_compileoption_get(X)  ((void*)0)
  195 #endif
  196 
  197 /*
  198 ** CAPI3REF: Test To See If The Library Is Threadsafe
  199 **
  200 ** ^The sqlite3_threadsafe() function returns zero if and only if
  201 ** SQLite was compiled with mutexing code omitted due to the
  202 ** [SQLITE_THREADSAFE] compile-time option being set to 0.
  203 **
  204 ** SQLite can be compiled with or without mutexes.  When
  205 ** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
  206 ** are enabled and SQLite is threadsafe.  When the
  207 ** [SQLITE_THREADSAFE] macro is 0, 
  208 ** the mutexes are omitted.  Without the mutexes, it is not safe
  209 ** to use SQLite concurrently from more than one thread.
  210 **
  211 ** Enabling mutexes incurs a measurable performance penalty.
  212 ** So if speed is of utmost importance, it makes sense to disable
  213 ** the mutexes.  But for maximum safety, mutexes should be enabled.
  214 ** ^The default behavior is for mutexes to be enabled.
  215 **
  216 ** This interface can be used by an application to make sure that the
  217 ** version of SQLite that it is linking against was compiled with
  218 ** the desired setting of the [SQLITE_THREADSAFE] macro.
  219 **
  220 ** This interface only reports on the compile-time mutex setting
  221 ** of the [SQLITE_THREADSAFE] flag.  If SQLite is compiled with
  222 ** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
  223 ** can be fully or partially disabled using a call to [sqlite3_config()]
  224 ** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
  225 ** or [SQLITE_CONFIG_SERIALIZED].  ^(The return value of the
  226 ** sqlite3_threadsafe() function shows only the compile-time setting of
  227 ** thread safety, not any run-time changes to that setting made by
  228 ** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
  229 ** is unchanged by calls to sqlite3_config().)^
  230 **
  231 ** See the [threading mode] documentation for additional information.
  232 */
  233 SQLITE_API int sqlite3_threadsafe(void);
  234 
  235 /*
  236 ** CAPI3REF: Database Connection Handle
  237 ** KEYWORDS: {database connection} {database connections}
  238 **
  239 ** Each open SQLite database is represented by a pointer to an instance of
  240 ** the opaque structure named "sqlite3".  It is useful to think of an sqlite3
  241 ** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and
  242 ** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
  243 ** and [sqlite3_close_v2()] are its destructors.  There are many other
  244 ** interfaces (such as
  245 ** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
  246 ** [sqlite3_busy_timeout()] to name but three) that are methods on an
  247 ** sqlite3 object.
  248 */
  249 typedef struct sqlite3 sqlite3;
  250 
  251 /*
  252 ** CAPI3REF: 64-Bit Integer Types
  253 ** KEYWORDS: sqlite_int64 sqlite_uint64
  254 **
  255 ** Because there is no cross-platform way to specify 64-bit integer types
  256 ** SQLite includes typedefs for 64-bit signed and unsigned integers.
  257 **
  258 ** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
  259 ** The sqlite_int64 and sqlite_uint64 types are supported for backwards
  260 ** compatibility only.
  261 **
  262 ** ^The sqlite3_int64 and sqlite_int64 types can store integer values
  263 ** between -9223372036854775808 and +9223372036854775807 inclusive.  ^The
  264 ** sqlite3_uint64 and sqlite_uint64 types can store integer values 
  265 ** between 0 and +18446744073709551615 inclusive.
  266 */
  267 #ifdef SQLITE_INT64_TYPE
  268   typedef SQLITE_INT64_TYPE sqlite_int64;
  269 # ifdef SQLITE_UINT64_TYPE
  270     typedef SQLITE_UINT64_TYPE sqlite_uint64;
  271 # else  
  272     typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
  273 # endif
  274 #elif defined(_MSC_VER) || defined(__BORLANDC__)
  275   typedef __int64 sqlite_int64;
  276   typedef unsigned __int64 sqlite_uint64;
  277 #else
  278   typedef long long int sqlite_int64;
  279   typedef unsigned long long int sqlite_uint64;
  280 #endif
  281 typedef sqlite_int64 sqlite3_int64;
  282 typedef sqlite_uint64 sqlite3_uint64;
  283 
  284 /*
  285 ** If compiling for a processor that lacks floating point support,
  286 ** substitute integer for floating-point.
  287 */
  288 #ifdef SQLITE_OMIT_FLOATING_POINT
  289 # define double sqlite3_int64
  290 #endif
  291 
  292 /*
  293 ** CAPI3REF: Closing A Database Connection
  294 ** DESTRUCTOR: sqlite3
  295 **
  296 ** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
  297 ** for the [sqlite3] object.
  298 ** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if
  299 ** the [sqlite3] object is successfully destroyed and all associated
  300 ** resources are deallocated.
  301 **
  302 ** Ideally, applications should [sqlite3_finalize | finalize] all
  303 ** [prepared statements], [sqlite3_blob_close | close] all [BLOB handles], and 
  304 ** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated
  305 ** with the [sqlite3] object prior to attempting to close the object.
  306 ** ^If the database connection is associated with unfinalized prepared
  307 ** statements, BLOB handlers, and/or unfinished sqlite3_backup objects then
  308 ** sqlite3_close() will leave the database connection open and return
  309 ** [SQLITE_BUSY]. ^If sqlite3_close_v2() is called with unfinalized prepared
  310 ** statements, unclosed BLOB handlers, and/or unfinished sqlite3_backups,
  311 ** it returns [SQLITE_OK] regardless, but instead of deallocating the database
  312 ** connection immediately, it marks the database connection as an unusable
  313 ** "zombie" and makes arrangements to automatically deallocate the database
  314 ** connection after all prepared statements are finalized, all BLOB handles
  315 ** are closed, and all backups have finished. The sqlite3_close_v2() interface
  316 ** is intended for use with host languages that are garbage collected, and
  317 ** where the order in which destructors are called is arbitrary.
  318 **
  319 ** ^If an [sqlite3] object is destroyed while a transaction is open,
  320 ** the transaction is automatically rolled back.
  321 **
  322 ** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]
  323 ** must be either a NULL
  324 ** pointer or an [sqlite3] object pointer obtained
  325 ** from [sqlite3_open()], [sqlite3_open16()], or
  326 ** [sqlite3_open_v2()], and not previously closed.
  327 ** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
  328 ** argument is a harmless no-op.
  329 */
  330 SQLITE_API int sqlite3_close(sqlite3*);
  331 SQLITE_API int sqlite3_close_v2(sqlite3*);
  332 
  333 /*
  334 ** The type for a callback function.
  335 ** This is legacy and deprecated.  It is included for historical
  336 ** compatibility and is not documented.
  337 */
  338 typedef int (*sqlite3_callback)(void*,int,char**, char**);
  339 
  340 /*
  341 ** CAPI3REF: One-Step Query Execution Interface
  342 ** METHOD: sqlite3
  343 **
  344 ** The sqlite3_exec() interface is a convenience wrapper around
  345 ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
  346 ** that allows an application to run multiple statements of SQL
  347 ** without having to use a lot of C code. 
  348 **
  349 ** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
  350 ** semicolon-separate SQL statements passed into its 2nd argument,
  351 ** in the context of the [database connection] passed in as its 1st
  352 ** argument.  ^If the callback function of the 3rd argument to
  353 ** sqlite3_exec() is not NULL, then it is invoked for each result row
  354 ** coming out of the evaluated SQL statements.  ^The 4th argument to
  355 ** sqlite3_exec() is relayed through to the 1st argument of each
  356 ** callback invocation.  ^If the callback pointer to sqlite3_exec()
  357 ** is NULL, then no callback is ever invoked and result rows are
  358 ** ignored.
  359 **
  360 ** ^If an error occurs while evaluating the SQL statements passed into
  361 ** sqlite3_exec(), then execution of the current statement stops and
  362 ** subsequent statements are skipped.  ^If the 5th parameter to sqlite3_exec()
  363 ** is not NULL then any error message is written into memory obtained
  364 ** from [sqlite3_malloc()] and passed back through the 5th parameter.
  365 ** To avoid memory leaks, the application should invoke [sqlite3_free()]
  366 ** on error message strings returned through the 5th parameter of
  367 ** sqlite3_exec() after the error message string is no longer needed.
  368 ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
  369 ** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
  370 ** NULL before returning.
  371 **
  372 ** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
  373 ** routine returns SQLITE_ABORT without invoking the callback again and
  374 ** without running any subsequent SQL statements.
  375 **
  376 ** ^The 2nd argument to the sqlite3_exec() callback function is the
  377 ** number of columns in the result.  ^The 3rd argument to the sqlite3_exec()
  378 ** callback is an array of pointers to strings obtained as if from
  379 ** [sqlite3_column_text()], one for each column.  ^If an element of a
  380 ** result row is NULL then the corresponding string pointer for the
  381 ** sqlite3_exec() callback is a NULL pointer.  ^The 4th argument to the
  382 ** sqlite3_exec() callback is an array of pointers to strings where each
  383 ** entry represents the name of corresponding result column as obtained
  384 ** from [sqlite3_column_name()].
  385 **
  386 ** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
  387 ** to an empty string, or a pointer that contains only whitespace and/or 
  388 ** SQL comments, then no SQL statements are evaluated and the database
  389 ** is not changed.
  390 **
  391 ** Restrictions:
  392 **
  393 ** <ul>
  394 ** <li> The application must ensure that the 1st parameter to sqlite3_exec()
  395 **      is a valid and open [database connection].
  396 ** <li> The application must not close the [database connection] specified by
  397 **      the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
  398 ** <li> The application must not modify the SQL statement text passed into
  399 **      the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
  400 ** </ul>
  401 */
  402 SQLITE_API int sqlite3_exec(
  403   sqlite3*,                                  /* An open database */
  404   const char *sql,                           /* SQL to be evaluated */
  405   int (*callback)(void*,int,char**,char**),  /* Callback function */
  406   void *,                                    /* 1st argument to callback */
  407   char **errmsg                              /* Error msg written here */
  408 );
  409 
  410 /*
  411 ** CAPI3REF: Result Codes
  412 ** KEYWORDS: {result code definitions}
  413 **
  414 ** Many SQLite functions return an integer result code from the set shown
  415 ** here in order to indicate success or failure.
  416 **
  417 ** New error codes may be added in future versions of SQLite.
  418 **
  419 ** See also: [extended result code definitions]
  420 */
  421 #define SQLITE_OK           0   /* Successful result */
  422 /* beginning-of-error-codes */
  423 #define SQLITE_ERROR        1   /* Generic error */
  424 #define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
  425 #define SQLITE_PERM         3   /* Access permission denied */
  426 #define SQLITE_ABORT        4   /* Callback routine requested an abort */
  427 #define SQLITE_BUSY         5   /* The database file is locked */
  428 #define SQLITE_LOCKED       6   /* A table in the database is locked */
  429 #define SQLITE_NOMEM        7   /* A malloc() failed */
  430 #define SQLITE_READONLY     8   /* Attempt to write a readonly database */
  431 #define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
  432 #define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
  433 #define SQLITE_CORRUPT     11   /* The database disk image is malformed */
  434 #define SQLITE_NOTFOUND    12   /* Unknown opcode in sqlite3_file_control() */
  435 #define SQLITE_FULL        13   /* Insertion failed because database is full */
  436 #define SQLITE_CANTOPEN    14   /* Unable to open the database file */
  437 #define SQLITE_PROTOCOL    15   /* Database lock protocol error */
  438 #define SQLITE_EMPTY       16   /* Internal use only */
  439 #define SQLITE_SCHEMA      17   /* The database schema changed */
  440 #define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
  441 #define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
  442 #define SQLITE_MISMATCH    20   /* Data type mismatch */
  443 #define SQLITE_MISUSE      21   /* Library used incorrectly */
  444 #define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
  445 #define SQLITE_AUTH        23   /* Authorization denied */
  446 #define SQLITE_FORMAT      24   /* Not used */
  447 #define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
  448 #define SQLITE_NOTADB      26   /* File opened that is not a database file */
  449 #define SQLITE_NOTICE      27   /* Notifications from sqlite3_log() */
  450 #define SQLITE_WARNING     28   /* Warnings from sqlite3_log() */
  451 #define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
  452 #define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
  453 /* end-of-error-codes */
  454 
  455 /*
  456 ** CAPI3REF: Extended Result Codes
  457 ** KEYWORDS: {extended result code definitions}
  458 **
  459 ** In its default configuration, SQLite API routines return one of 30 integer
  460 ** [result codes].  However, experience has shown that many of
  461 ** these result codes are too coarse-grained.  They do not provide as
  462 ** much information about problems as programmers might like.  In an effort to
  463 ** address this, newer versions of SQLite (version 3.3.8 [dateof:3.3.8]
  464 ** and later) include
  465 ** support for additional result codes that provide more detailed information
  466 ** about errors. These [extended result codes] are enabled or disabled
  467 ** on a per database connection basis using the
  468 ** [sqlite3_extended_result_codes()] API.  Or, the extended code for
  469 ** the most recent error can be obtained using
  470 ** [sqlite3_extended_errcode()].
  471 */
  472 #define SQLITE_ERROR_MISSING_COLLSEQ   (SQLITE_ERROR | (1<<8))
  473 #define SQLITE_ERROR_RETRY             (SQLITE_ERROR | (2<<8))
  474 #define SQLITE_ERROR_SNAPSHOT          (SQLITE_ERROR | (3<<8))
  475 #define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))
  476 #define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))
  477 #define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))
  478 #define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))
  479 #define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))
  480 #define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))
  481 #define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7<<8))
  482 #define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8<<8))
  483 #define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9<<8))
  484 #define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10<<8))
  485 #define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11<<8))
  486 #define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12<<8))
  487 #define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))
  488 #define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
  489 #define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))
  490 #define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))
  491 #define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))
  492 #define SQLITE_IOERR_SHMOPEN           (SQLITE_IOERR | (18<<8))
  493 #define SQLITE_IOERR_SHMSIZE           (SQLITE_IOERR | (19<<8))
  494 #define SQLITE_IOERR_SHMLOCK           (SQLITE_IOERR | (20<<8))
  495 #define SQLITE_IOERR_SHMMAP            (SQLITE_IOERR | (21<<8))
  496 #define SQLITE_IOERR_SEEK              (SQLITE_IOERR | (22<<8))
  497 #define SQLITE_IOERR_DELETE_NOENT      (SQLITE_IOERR | (23<<8))
  498 #define SQLITE_IOERR_MMAP              (SQLITE_IOERR | (24<<8))
  499 #define SQLITE_IOERR_GETTEMPPATH       (SQLITE_IOERR | (25<<8))
  500 #define SQLITE_IOERR_CONVPATH          (SQLITE_IOERR | (26<<8))
  501 #define SQLITE_IOERR_VNODE             (SQLITE_IOERR | (27<<8))
  502 #define SQLITE_IOERR_AUTH              (SQLITE_IOERR | (28<<8))
  503 #define SQLITE_IOERR_BEGIN_ATOMIC      (SQLITE_IOERR | (29<<8))
  504 #define SQLITE_IOERR_COMMIT_ATOMIC     (SQLITE_IOERR | (30<<8))
  505 #define SQLITE_IOERR_ROLLBACK_ATOMIC   (SQLITE_IOERR | (31<<8))
  506 #define SQLITE_IOERR_DATA              (SQLITE_IOERR | (32<<8))
  507 #define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED |  (1<<8))
  508 #define SQLITE_LOCKED_VTAB             (SQLITE_LOCKED |  (2<<8))
  509 #define SQLITE_BUSY_RECOVERY           (SQLITE_BUSY   |  (1<<8))
  510 #define SQLITE_BUSY_SNAPSHOT           (SQLITE_BUSY   |  (2<<8))
  511 #define SQLITE_BUSY_TIMEOUT            (SQLITE_BUSY   |  (3<<8))
  512 #define SQLITE_CANTOPEN_NOTEMPDIR      (SQLITE_CANTOPEN | (1<<8))
  513 #define SQLITE_CANTOPEN_ISDIR          (SQLITE_CANTOPEN | (2<<8))
  514 #define SQLITE_CANTOPEN_FULLPATH       (SQLITE_CANTOPEN | (3<<8))
  515 #define SQLITE_CANTOPEN_CONVPATH       (SQLITE_CANTOPEN | (4<<8))
  516 #define SQLITE_CANTOPEN_DIRTYWAL       (SQLITE_CANTOPEN | (5<<8)) /* Not Used */
  517 #define SQLITE_CANTOPEN_SYMLINK        (SQLITE_CANTOPEN | (6<<8))
  518 #define SQLITE_CORRUPT_VTAB            (SQLITE_CORRUPT | (1<<8))
  519 #define SQLITE_CORRUPT_SEQUENCE        (SQLITE_CORRUPT | (2<<8))
  520 #define SQLITE_CORRUPT_INDEX           (SQLITE_CORRUPT | (3<<8))
  521 #define SQLITE_READONLY_RECOVERY       (SQLITE_READONLY | (1<<8))
  522 #define SQLITE_READONLY_CANTLOCK       (SQLITE_READONLY | (2<<8))
  523 #define SQLITE_READONLY_ROLLBACK       (SQLITE_READONLY | (3<<8))
  524 #define SQLITE_READONLY_DBMOVED        (SQLITE_READONLY | (4<<8))
  525 #define SQLITE_READONLY_CANTINIT       (SQLITE_READONLY | (5<<8))
  526 #define SQLITE_READONLY_DIRECTORY      (SQLITE_READONLY | (6<<8))
  527 #define SQLITE_ABORT_ROLLBACK          (SQLITE_ABORT | (2<<8))
  528 #define SQLITE_CONSTRAINT_CHECK        (SQLITE_CONSTRAINT | (1<<8))
  529 #define SQLITE_CONSTRAINT_COMMITHOOK   (SQLITE_CONSTRAINT | (2<<8))
  530 #define SQLITE_CONSTRAINT_FOREIGNKEY   (SQLITE_CONSTRAINT | (3<<8))
  531 #define SQLITE_CONSTRAINT_FUNCTION     (SQLITE_CONSTRAINT | (4<<8))
  532 #define SQLITE_CONSTRAINT_NOTNULL      (SQLITE_CONSTRAINT | (5<<8))
  533 #define SQLITE_CONSTRAINT_PRIMARYKEY   (SQLITE_CONSTRAINT | (6<<8))
  534 #define SQLITE_CONSTRAINT_TRIGGER      (SQLITE_CONSTRAINT | (7<<8))
  535 #define SQLITE_CONSTRAINT_UNIQUE       (SQLITE_CONSTRAINT | (8<<8))
  536 #define SQLITE_CONSTRAINT_VTAB         (SQLITE_CONSTRAINT | (9<<8))
  537 #define SQLITE_CONSTRAINT_ROWID        (SQLITE_CONSTRAINT |(10<<8))
  538 #define SQLITE_CONSTRAINT_PINNED       (SQLITE_CONSTRAINT |(11<<8))
  539 #define SQLITE_NOTICE_RECOVER_WAL      (SQLITE_NOTICE | (1<<8))
  540 #define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
  541 #define SQLITE_WARNING_AUTOINDEX       (SQLITE_WARNING | (1<<8))
  542 #define SQLITE_AUTH_USER               (SQLITE_AUTH | (1<<8))
  543 #define SQLITE_OK_LOAD_PERMANENTLY     (SQLITE_OK | (1<<8))
  544 #define SQLITE_OK_SYMLINK              (SQLITE_OK | (2<<8))
  545 
  546 /*
  547 ** CAPI3REF: Flags For File Open Operations
  548 **
  549 ** These bit values are intended for use in the
  550 ** 3rd parameter to the [sqlite3_open_v2()] interface and
  551 ** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
  552 */
  553 #define SQLITE_OPEN_READONLY         0x00000001  /* Ok for sqlite3_open_v2() */
  554 #define SQLITE_OPEN_READWRITE        0x00000002  /* Ok for sqlite3_open_v2() */
  555 #define SQLITE_OPEN_CREATE           0x00000004  /* Ok for sqlite3_open_v2() */
  556 #define SQLITE_OPEN_DELETEONCLOSE    0x00000008  /* VFS only */
  557 #define SQLITE_OPEN_EXCLUSIVE        0x00000010  /* VFS only */
  558 #define SQLITE_OPEN_AUTOPROXY        0x00000020  /* VFS only */
  559 #define SQLITE_OPEN_URI              0x00000040  /* Ok for sqlite3_open_v2() */
  560 #define SQLITE_OPEN_MEMORY           0x00000080  /* Ok for sqlite3_open_v2() */
  561 #define SQLITE_OPEN_MAIN_DB          0x00000100  /* VFS only */
  562 #define SQLITE_OPEN_TEMP_DB          0x00000200  /* VFS only */
  563 #define SQLITE_OPEN_TRANSIENT_DB     0x00000400  /* VFS only */
  564 #define SQLITE_OPEN_MAIN_JOURNAL     0x00000800  /* VFS only */
  565 #define SQLITE_OPEN_TEMP_JOURNAL     0x00001000  /* VFS only */
  566 #define SQLITE_OPEN_SUBJOURNAL       0x00002000  /* VFS only */
  567 #define SQLITE_OPEN_MASTER_JOURNAL   0x00004000  /* VFS only */
  568 #define SQLITE_OPEN_NOMUTEX          0x00008000  /* Ok for sqlite3_open_v2() */
  569 #define SQLITE_OPEN_FULLMUTEX        0x00010000  /* Ok for sqlite3_open_v2() */
  570 #define SQLITE_OPEN_SHAREDCACHE      0x00020000  /* Ok for sqlite3_open_v2() */
  571 #define SQLITE_OPEN_PRIVATECACHE     0x00040000  /* Ok for sqlite3_open_v2() */
  572 #define SQLITE_OPEN_WAL              0x00080000  /* VFS only */
  573 #define SQLITE_OPEN_NOFOLLOW         0x01000000  /* Ok for sqlite3_open_v2() */
  574 
  575 /* Reserved:                         0x00F00000 */
  576 
  577 /*
  578 ** CAPI3REF: Device Characteristics
  579 **
  580 ** The xDeviceCharacteristics method of the [sqlite3_io_methods]
  581 ** object returns an integer which is a vector of these
  582 ** bit values expressing I/O characteristics of the mass storage
  583 ** device that holds the file that the [sqlite3_io_methods]
  584 ** refers to.
  585 **
  586 ** The SQLITE_IOCAP_ATOMIC property means that all writes of
  587 ** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
  588 ** mean that writes of blocks that are nnn bytes in size and
  589 ** are aligned to an address which is an integer multiple of
  590 ** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
  591 ** that when data is appended to a file, the data is appended
  592 ** first then the size of the file is extended, never the other
  593 ** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
  594 ** information is written to disk in the same order as calls
  595 ** to xWrite().  The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
  596 ** after reboot following a crash or power loss, the only bytes in a
  597 ** file that were written at the application level might have changed
  598 ** and that adjacent bytes, even bytes within the same sector are
  599 ** guaranteed to be unchanged.  The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
  600 ** flag indicates that a file cannot be deleted when open.  The
  601 ** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
  602 ** read-only media and cannot be changed even by processes with
  603 ** elevated privileges.
  604 **
  605 ** The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying
  606 ** filesystem supports doing multiple write operations atomically when those
  607 ** write operations are bracketed by [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] and
  608 ** [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE].
  609 */
  610 #define SQLITE_IOCAP_ATOMIC                 0x00000001
  611 #define SQLITE_IOCAP_ATOMIC512              0x00000002
  612 #define SQLITE_IOCAP_ATOMIC1K               0x00000004
  613 #define SQLITE_IOCAP_ATOMIC2K               0x00000008
  614 #define SQLITE_IOCAP_ATOMIC4K               0x00000010
  615 #define SQLITE_IOCAP_ATOMIC8K               0x00000020
  616 #define SQLITE_IOCAP_ATOMIC16K              0x00000040
  617 #define SQLITE_IOCAP_ATOMIC32K              0x00000080
  618 #define SQLITE_IOCAP_ATOMIC64K              0x00000100
  619 #define SQLITE_IOCAP_SAFE_APPEND            0x00000200
  620 #define SQLITE_IOCAP_SEQUENTIAL             0x00000400
  621 #define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN  0x00000800
  622 #define SQLITE_IOCAP_POWERSAFE_OVERWRITE    0x00001000
  623 #define SQLITE_IOCAP_IMMUTABLE              0x00002000
  624 #define SQLITE_IOCAP_BATCH_ATOMIC           0x00004000
  625 
  626 /*
  627 ** CAPI3REF: File Locking Levels
  628 **
  629 ** SQLite uses one of these integer values as the second
  630 ** argument to calls it makes to the xLock() and xUnlock() methods
  631 ** of an [sqlite3_io_methods] object.
  632 */
  633 #define SQLITE_LOCK_NONE          0
  634 #define SQLITE_LOCK_SHARED        1
  635 #define SQLITE_LOCK_RESERVED      2
  636 #define SQLITE_LOCK_PENDING       3
  637 #define SQLITE_LOCK_EXCLUSIVE     4
  638 
  639 /*
  640 ** CAPI3REF: Synchronization Type Flags
  641 **
  642 ** When SQLite invokes the xSync() method of an
  643 ** [sqlite3_io_methods] object it uses a combination of
  644 ** these integer values as the second argument.
  645 **
  646 ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
  647 ** sync operation only needs to flush data to mass storage.  Inode
  648 ** information need not be flushed. If the lower four bits of the flag
  649 ** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
  650 ** If the lower four bits equal SQLITE_SYNC_FULL, that means
  651 ** to use Mac OS X style fullsync instead of fsync().
  652 **
  653 ** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
  654 ** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
  655 ** settings.  The [synchronous pragma] determines when calls to the
  656 ** xSync VFS method occur and applies uniformly across all platforms.
  657 ** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
  658 ** energetic or rigorous or forceful the sync operations are and
  659 ** only make a difference on Mac OSX for the default SQLite code.
  660 ** (Third-party VFS implementations might also make the distinction
  661 ** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
  662 ** operating systems natively supported by SQLite, only Mac OSX
  663 ** cares about the difference.)
  664 */
  665 #define SQLITE_SYNC_NORMAL        0x00002
  666 #define SQLITE_SYNC_FULL          0x00003
  667 #define SQLITE_SYNC_DATAONLY      0x00010
  668 
  669 /*
  670 ** CAPI3REF: OS Interface Open File Handle
  671 **
  672 ** An [sqlite3_file] object represents an open file in the 
  673 ** [sqlite3_vfs | OS interface layer].  Individual OS interface
  674 ** implementations will
  675 ** want to subclass this object by appending additional fields
  676 ** for their own use.  The pMethods entry is a pointer to an
  677 ** [sqlite3_io_methods] object that defines methods for performing
  678 ** I/O operations on the open file.
  679 */
  680 typedef struct sqlite3_file sqlite3_file;
  681 struct sqlite3_file {
  682   const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */
  683 };
  684 
  685 /*
  686 ** CAPI3REF: OS Interface File Virtual Methods Object
  687 **
  688 ** Every file opened by the [sqlite3_vfs.xOpen] method populates an
  689 ** [sqlite3_file] object (or, more commonly, a subclass of the
  690 ** [sqlite3_file] object) with a pointer to an instance of this object.
  691 ** This object defines the methods used to perform various operations
  692 ** against the open file represented by the [sqlite3_file] object.
  693 **
  694 ** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element 
  695 ** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
  696 ** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed.  The
  697 ** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
  698 ** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
  699 ** to NULL.
  700 **
  701 ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
  702 ** [SQLITE_SYNC_FULL].  The first choice is the normal fsync().
  703 ** The second choice is a Mac OS X style fullsync.  The [SQLITE_SYNC_DATAONLY]
  704 ** flag may be ORed in to indicate that only the data of the file
  705 ** and not its inode needs to be synced.
  706 **
  707 ** The integer values to xLock() and xUnlock() are one of
  708 ** <ul>
  709 ** <li> [SQLITE_LOCK_NONE],
  710 ** <li> [SQLITE_LOCK_SHARED],
  711 ** <li> [SQLITE_LOCK_RESERVED],
  712 ** <li> [SQLITE_LOCK_PENDING], or
  713 ** <li> [SQLITE_LOCK_EXCLUSIVE].
  714 ** </ul>
  715 ** xLock() increases the lock. xUnlock() decreases the lock.
  716 ** The xCheckReservedLock() method checks whether any database connection,
  717 ** either in this process or in some other process, is holding a RESERVED,
  718 ** PENDING, or EXCLUSIVE lock on the file.  It returns true
  719 ** if such a lock exists and false otherwise.
  720 **
  721 ** The xFileControl() method is a generic interface that allows custom
  722 ** VFS implementations to directly control an open file using the
  723 ** [sqlite3_file_control()] interface.  The second "op" argument is an
  724 ** integer opcode.  The third argument is a generic pointer intended to
  725 ** point to a structure that may contain arguments or space in which to
  726 ** write return values.  Potential uses for xFileControl() might be
  727 ** functions to enable blocking locks with timeouts, to change the
  728 ** locking strategy (for example to use dot-file locks), to inquire
  729 ** about the status of a lock, or to break stale locks.  The SQLite
  730 ** core reserves all opcodes less than 100 for its own use.
  731 ** A [file control opcodes | list of opcodes] less than 100 is available.
  732 ** Applications that define a custom xFileControl method should use opcodes
  733 ** greater than 100 to avoid conflicts.  VFS implementations should
  734 ** return [SQLITE_NOTFOUND] for file control opcodes that they do not
  735 ** recognize.
  736 **
  737 ** The xSectorSize() method returns the sector size of the
  738 ** device that underlies the file.  The sector size is the
  739 ** minimum write that can be performed without disturbing
  740 ** other bytes in the file.  The xDeviceCharacteristics()
  741 ** method returns a bit vector describing behaviors of the
  742 ** underlying device:
  743 **
  744 ** <ul>
  745 ** <li> [SQLITE_IOCAP_ATOMIC]
  746 ** <li> [SQLITE_IOCAP_ATOMIC512]
  747 ** <li> [SQLITE_IOCAP_ATOMIC1K]
  748 ** <li> [SQLITE_IOCAP_ATOMIC2K]
  749 ** <li> [SQLITE_IOCAP_ATOMIC4K]
  750 ** <li> [SQLITE_IOCAP_ATOMIC8K]
  751 ** <li> [SQLITE_IOCAP_ATOMIC16K]
  752 ** <li> [SQLITE_IOCAP_ATOMIC32K]
  753 ** <li> [SQLITE_IOCAP_ATOMIC64K]
  754 ** <li> [SQLITE_IOCAP_SAFE_APPEND]
  755 ** <li> [SQLITE_IOCAP_SEQUENTIAL]
  756 ** <li> [SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN]
  757 ** <li> [SQLITE_IOCAP_POWERSAFE_OVERWRITE]
  758 ** <li> [SQLITE_IOCAP_IMMUTABLE]
  759 ** <li> [SQLITE_IOCAP_BATCH_ATOMIC]
  760 ** </ul>
  761 **
  762 ** The SQLITE_IOCAP_ATOMIC property means that all writes of
  763 ** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
  764 ** mean that writes of blocks that are nnn bytes in size and
  765 ** are aligned to an address which is an integer multiple of
  766 ** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
  767 ** that when data is appended to a file, the data is appended
  768 ** first then the size of the file is extended, never the other
  769 ** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
  770 ** information is written to disk in the same order as calls
  771 ** to xWrite().
  772 **
  773 ** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
  774 ** in the unread portions of the buffer with zeros.  A VFS that
  775 ** fails to zero-fill short reads might seem to work.  However,
  776 ** failure to zero-fill short reads will eventually lead to
  777 ** database corruption.
  778 */
  779 typedef struct sqlite3_io_methods sqlite3_io_methods;
  780 struct sqlite3_io_methods {
  781   int iVersion;
  782   int (*xClose)(sqlite3_file*);
  783   int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
  784   int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
  785   int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
  786   int (*xSync)(sqlite3_file*, int flags);
  787   int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
  788   int (*xLock)(sqlite3_file*, int);
  789   int (*xUnlock)(sqlite3_file*, int);
  790   int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
  791   int (*xFileControl)(sqlite3_file*, int op, void *pArg);
  792   int (*xSectorSize)(sqlite3_file*);
  793   int (*xDeviceCharacteristics)(sqlite3_file*);
  794   /* Methods above are valid for version 1 */
  795   int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
  796   int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
  797   void (*xShmBarrier)(sqlite3_file*);
  798   int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
  799   /* Methods above are valid for version 2 */
  800   int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
  801   int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
  802   /* Methods above are valid for version 3 */
  803   /* Additional methods may be added in future releases */
  804 };
  805 
  806 /*
  807 ** CAPI3REF: Standard File Control Opcodes
  808 ** KEYWORDS: {file control opcodes} {file control opcode}
  809 **
  810 ** These integer constants are opcodes for the xFileControl method
  811 ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
  812 ** interface.
  813 **
  814 ** <ul>
  815 ** <li>[[SQLITE_FCNTL_LOCKSTATE]]
  816 ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This
  817 ** opcode causes the xFileControl method to write the current state of
  818 ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
  819 ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
  820 ** into an integer that the pArg argument points to. This capability
  821 ** is used during testing and is only available when the SQLITE_TEST
  822 ** compile-time option is used.
  823 **
  824 ** <li>[[SQLITE_FCNTL_SIZE_HINT]]
  825 ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
  826 ** layer a hint of how large the database file will grow to be during the
  827 ** current transaction.  This hint is not guaranteed to be accurate but it
  828 ** is often close.  The underlying VFS might choose to preallocate database
  829 ** file space based on this hint in order to help writes to the database
  830 ** file run faster.
  831 **
  832 ** <li>[[SQLITE_FCNTL_SIZE_LIMIT]]
  833 ** The [SQLITE_FCNTL_SIZE_LIMIT] opcode is used by in-memory VFS that
  834 ** implements [sqlite3_deserialize()] to set an upper bound on the size
  835 ** of the in-memory database.  The argument is a pointer to a [sqlite3_int64].
  836 ** If the integer pointed to is negative, then it is filled in with the
  837 ** current limit.  Otherwise the limit is set to the larger of the value
  838 ** of the integer pointed to and the current database size.  The integer
  839 ** pointed to is set to the new limit.
  840 **
  841 ** <li>[[SQLITE_FCNTL_CHUNK_SIZE]]
  842 ** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
  843 ** extends and truncates the database file in chunks of a size specified
  844 ** by the user. The fourth argument to [sqlite3_file_control()] should 
  845 ** point to an integer (type int) containing the new chunk-size to use
  846 ** for the nominated database. Allocating database file space in large
  847 ** chunks (say 1MB at a time), may reduce file-system fragmentation and
  848 ** improve performance on some systems.
  849 **
  850 ** <li>[[SQLITE_FCNTL_FILE_POINTER]]
  851 ** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
  852 ** to the [sqlite3_file] object associated with a particular database
  853 ** connection.  See also [SQLITE_FCNTL_JOURNAL_POINTER].
  854 **
  855 ** <li>[[SQLITE_FCNTL_JOURNAL_POINTER]]
  856 ** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
  857 ** to the [sqlite3_file] object associated with the journal file (either
  858 ** the [rollback journal] or the [write-ahead log]) for a particular database
  859 ** connection.  See also [SQLITE_FCNTL_FILE_POINTER].
  860 **
  861 ** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
  862 ** No longer in use.
  863 **
  864 ** <li>[[SQLITE_FCNTL_SYNC]]
  865 ** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
  866 ** sent to the VFS immediately before the xSync method is invoked on a
  867 ** database file descriptor. Or, if the xSync method is not invoked 
  868 ** because the user has configured SQLite with 
  869 ** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place 
  870 ** of the xSync method. In most cases, the pointer argument passed with
  871 ** this file-control is NULL. However, if the database file is being synced
  872 ** as part of a multi-database commit, the argument points to a nul-terminated
  873 ** string containing the transactions master-journal file name. VFSes that 
  874 ** do not need this signal should silently ignore this opcode. Applications 
  875 ** should not call [sqlite3_file_control()] with this opcode as doing so may 
  876 ** disrupt the operation of the specialized VFSes that do require it.  
  877 **
  878 ** <li>[[SQLITE_FCNTL_COMMIT_PHASETWO]]
  879 ** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite
  880 ** and sent to the VFS after a transaction has been committed immediately
  881 ** but before the database is unlocked. VFSes that do not need this signal
  882 ** should silently ignore this opcode. Applications should not call
  883 ** [sqlite3_file_control()] with this opcode as doing so may disrupt the 
  884 ** operation of the specialized VFSes that do require it.  
  885 **
  886 ** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]]
  887 ** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
  888 ** retry counts and intervals for certain disk I/O operations for the
  889 ** windows [VFS] in order to provide robustness in the presence of
  890 ** anti-virus programs.  By default, the windows VFS will retry file read,
  891 ** file write, and file delete operations up to 10 times, with a delay
  892 ** of 25 milliseconds before the first retry and with the delay increasing
  893 ** by an additional 25 milliseconds with each subsequent retry.  This
  894 ** opcode allows these two values (10 retries and 25 milliseconds of delay)
  895 ** to be adjusted.  The values are changed for all database connections
  896 ** within the same process.  The argument is a pointer to an array of two
  897 ** integers where the first integer is the new retry count and the second
  898 ** integer is the delay.  If either integer is negative, then the setting
  899 ** is not changed but instead the prior value of that setting is written
  900 ** into the array entry, allowing the current retry settings to be
  901 ** interrogated.  The zDbName parameter is ignored.
  902 **
  903 ** <li>[[SQLITE_FCNTL_PERSIST_WAL]]
  904 ** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
  905 ** persistent [WAL | Write Ahead Log] setting.  By default, the auxiliary
  906 ** write ahead log ([WAL file]) and shared memory
  907 ** files used for transaction control
  908 ** are automatically deleted when the latest connection to the database
  909 ** closes.  Setting persistent WAL mode causes those files to persist after
  910 ** close.  Persisting the files is useful when other processes that do not
  911 ** have write permission on the directory containing the database file want
  912 ** to read the database file, as the WAL and shared memory files must exist
  913 ** in order for the database to be readable.  The fourth parameter to
  914 ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
  915 ** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
  916 ** WAL mode.  If the integer is -1, then it is overwritten with the current
  917 ** WAL persistence setting.
  918 **
  919 ** <li>[[SQLITE_FCNTL_POWERSAFE_OVERWRITE]]
  920 ** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
  921 ** persistent "powersafe-overwrite" or "PSOW" setting.  The PSOW setting
  922 ** determines the [SQLITE_IOCAP_POWERSAFE_OVERWRITE] bit of the
  923 ** xDeviceCharacteristics methods. The fourth parameter to
  924 ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
  925 ** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
  926 ** mode.  If the integer is -1, then it is overwritten with the current
  927 ** zero-damage mode setting.
  928 **
  929 ** <li>[[SQLITE_FCNTL_OVERWRITE]]
  930 ** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening
  931 ** a write transaction to indicate that, unless it is rolled back for some
  932 ** reason, the entire database file will be overwritten by the current 
  933 ** transaction. This is used by VACUUM operations.
  934 **
  935 ** <li>[[SQLITE_FCNTL_VFSNAME]]
  936 ** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of
  937 ** all [VFSes] in the VFS stack.  The names are of all VFS shims and the
  938 ** final bottom-level VFS are written into memory obtained from 
  939 ** [sqlite3_malloc()] and the result is stored in the char* variable
  940 ** that the fourth parameter of [sqlite3_file_control()] points to.
  941 ** The caller is responsible for freeing the memory when done.  As with
  942 ** all file-control actions, there is no guarantee that this will actually
  943 ** do anything.  Callers should initialize the char* variable to a NULL
  944 ** pointer in case this file-control is not implemented.  This file-control
  945 ** is intended for diagnostic use only.
  946 **
  947 ** <li>[[SQLITE_FCNTL_VFS_POINTER]]
  948 ** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
  949 ** [VFSes] currently in use.  ^(The argument X in
  950 ** sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be
  951 ** of type "[sqlite3_vfs] **".  This opcodes will set *X
  952 ** to a pointer to the top-level VFS.)^
  953 ** ^When there are multiple VFS shims in the stack, this opcode finds the
  954 ** upper-most shim only.
  955 **
  956 ** <li>[[SQLITE_FCNTL_PRAGMA]]
  957 ** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA] 
  958 ** file control is sent to the open [sqlite3_file] object corresponding
  959 ** to the database file to which the pragma statement refers. ^The argument
  960 ** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
  961 ** pointers to strings (char**) in which the second element of the array
  962 ** is the name of the pragma and the third element is the argument to the
  963 ** pragma or NULL if the pragma has no argument.  ^The handler for an
  964 ** [SQLITE_FCNTL_PRAGMA] file control can optionally make the first element
  965 ** of the char** argument point to a string obtained from [sqlite3_mprintf()]
  966 ** or the equivalent and that string will become the result of the pragma or
  967 ** the error message if the pragma fails. ^If the
  968 ** [SQLITE_FCNTL_PRAGMA] file control returns [SQLITE_NOTFOUND], then normal 
  969 ** [PRAGMA] processing continues.  ^If the [SQLITE_FCNTL_PRAGMA]
  970 ** file control returns [SQLITE_OK], then the parser assumes that the
  971 ** VFS has handled the PRAGMA itself and the parser generates a no-op
  972 ** prepared statement if result string is NULL, or that returns a copy
  973 ** of the result string if the string is non-NULL.
  974 ** ^If the [SQLITE_FCNTL_PRAGMA] file control returns
  975 ** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
  976 ** that the VFS encountered an error while handling the [PRAGMA] and the
  977 ** compilation of the PRAGMA fails with an error.  ^The [SQLITE_FCNTL_PRAGMA]
  978 ** file control occurs at the beginning of pragma statement analysis and so
  979 ** it is able to override built-in [PRAGMA] statements.
  980 **
  981 ** <li>[[SQLITE_FCNTL_BUSYHANDLER]]
  982 ** ^The [SQLITE_FCNTL_BUSYHANDLER]
  983 ** file-control may be invoked by SQLite on the database file handle
  984 ** shortly after it is opened in order to provide a custom VFS with access
  985 ** to the connection's busy-handler callback. The argument is of type (void**)
  986 ** - an array of two (void *) values. The first (void *) actually points
  987 ** to a function of type (int (*)(void *)). In order to invoke the connection's
  988 ** busy-handler, this function should be invoked with the second (void *) in
  989 ** the array as the only argument. If it returns non-zero, then the operation
  990 ** should be retried. If it returns zero, the custom VFS should abandon the
  991 ** current operation.
  992 **
  993 ** <li>[[SQLITE_FCNTL_TEMPFILENAME]]
  994 ** ^Applications can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control
  995 ** to have SQLite generate a
  996 ** temporary filename using the same algorithm that is followed to generate
  997 ** temporary filenames for TEMP tables and other internal uses.  The
  998 ** argument should be a char** which will be filled with the filename
  999 ** written into memory obtained from [sqlite3_malloc()].  The caller should
 1000 ** invoke [sqlite3_free()] on the result to avoid a memory leak.
 1001 **
 1002 ** <li>[[SQLITE_FCNTL_MMAP_SIZE]]
 1003 ** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the
 1004 ** maximum number of bytes that will be used for memory-mapped I/O.
 1005 ** The argument is a pointer to a value of type sqlite3_int64 that
 1006 ** is an advisory maximum number of bytes in the file to memory map.  The
 1007 ** pointer is overwritten with the old value.  The limit is not changed if
 1008 ** the value originally pointed to is negative, and so the current limit 
 1009 ** can be queried by passing in a pointer to a negative number.  This
 1010 ** file-control is used internally to implement [PRAGMA mmap_size].
 1011 **
 1012 ** <li>[[SQLITE_FCNTL_TRACE]]
 1013 ** The [SQLITE_FCNTL_TRACE] file control provides advisory information
 1014 ** to the VFS about what the higher layers of the SQLite stack are doing.
 1015 ** This file control is used by some VFS activity tracing [shims].
 1016 ** The argument is a zero-terminated string.  Higher layers in the
 1017 ** SQLite stack may generate instances of this file control if
 1018 ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
 1019 **
 1020 ** <li>[[SQLITE_FCNTL_HAS_MOVED]]
 1021 ** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a
 1022 ** pointer to an integer and it writes a boolean into that integer depending
 1023 ** on whether or not the file has been renamed, moved, or deleted since it
 1024 ** was first opened.
 1025 **
 1026 ** <li>[[SQLITE_FCNTL_WIN32_GET_HANDLE]]
 1027 ** The [SQLITE_FCNTL_WIN32_GET_HANDLE] opcode can be used to obtain the
 1028 ** underlying native file handle associated with a file handle.  This file
 1029 ** control interprets its argument as a pointer to a native file handle and
 1030 ** writes the resulting value there.
 1031 **
 1032 ** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]]
 1033 ** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging.  This
 1034 ** opcode causes the xFileControl method to swap the file handle with the one
 1035 ** pointed to by the pArg argument.  This capability is used during testing
 1036 ** and only needs to be supported when SQLITE_TEST is defined.
 1037 **
 1038 ** <li>[[SQLITE_FCNTL_WAL_BLOCK]]
 1039 ** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might
 1040 ** be advantageous to block on the next WAL lock if the lock is not immediately
 1041 ** available.  The WAL subsystem issues this signal during rare
 1042 ** circumstances in order to fix a problem with priority inversion.
 1043 ** Applications should <em>not</em> use this file-control.
 1044 **
 1045 ** <li>[[SQLITE_FCNTL_ZIPVFS]]
 1046 ** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other
 1047 ** VFS should return SQLITE_NOTFOUND for this opcode.
 1048 **
 1049 ** <li>[[SQLITE_FCNTL_RBU]]
 1050 ** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
 1051 ** the RBU extension only.  All other VFS should return SQLITE_NOTFOUND for
 1052 ** this opcode.  
 1053 **
 1054 ** <li>[[SQLITE_FCNTL_BEGIN_ATOMIC_WRITE]]
 1055 ** If the [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] opcode returns SQLITE_OK, then
 1056 ** the file descriptor is placed in "batch write mode", which
 1057 ** means all subsequent write operations will be deferred and done
 1058 ** atomically at the next [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE].  Systems
 1059 ** that do not support batch atomic writes will return SQLITE_NOTFOUND.
 1060 ** ^Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to
 1061 ** the closing [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] or
 1062 ** [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE], SQLite will make
 1063 ** no VFS interface calls on the same [sqlite3_file] file descriptor
 1064 ** except for calls to the xWrite method and the xFileControl method
 1065 ** with [SQLITE_FCNTL_SIZE_HINT].
 1066 **
 1067 ** <li>[[SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]]
 1068 ** The [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] opcode causes all write
 1069 ** operations since the previous successful call to 
 1070 ** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be performed atomically.
 1071 ** This file control returns [SQLITE_OK] if and only if the writes were
 1072 ** all performed successfully and have been committed to persistent storage.
 1073 ** ^Regardless of whether or not it is successful, this file control takes
 1074 ** the file descriptor out of batch write mode so that all subsequent
 1075 ** write operations are independent.
 1076 ** ^SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without
 1077 ** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
 1078 **
 1079 ** <li>[[SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE]]
 1080 ** The [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE] opcode causes all write
 1081 ** operations since the previous successful call to 
 1082 ** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be rolled back.
 1083 ** ^This file control takes the file descriptor out of batch write mode
 1084 ** so that all subsequent write operations are independent.
 1085 ** ^SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without
 1086 ** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
 1087 **
 1088 ** <li>[[SQLITE_FCNTL_LOCK_TIMEOUT]]
 1089 ** The [SQLITE_FCNTL_LOCK_TIMEOUT] opcode is used to configure a VFS
 1090 ** to block for up to M milliseconds before failing when attempting to 
 1091 ** obtain a file lock using the xLock or xShmLock methods of the VFS. 
 1092 ** The parameter is a pointer to a 32-bit signed integer that contains
 1093 ** the value that M is to be set to. Before returning, the 32-bit signed
 1094 ** integer is overwritten with the previous value of M.
 1095 **
 1096 ** <li>[[SQLITE_FCNTL_DATA_VERSION]]
 1097 ** The [SQLITE_FCNTL_DATA_VERSION] opcode is used to detect changes to
 1098 ** a database file.  The argument is a pointer to a 32-bit unsigned integer.
 1099 ** The "data version" for the pager is written into the pointer.  The
 1100 ** "data version" changes whenever any change occurs to the corresponding
 1101 ** database file, either through SQL statements on the same database
 1102 ** connection or through transactions committed by separate database
 1103 ** connections possibly in other processes. The [sqlite3_total_changes()]
 1104 ** interface can be used to find if any database on the connection has changed,
 1105 ** but that interface responds to changes on TEMP as well as MAIN and does
 1106 ** not provide a mechanism to detect changes to MAIN only.  Also, the
 1107 ** [sqlite3_total_changes()] interface responds to internal changes only and
 1108 ** omits changes made by other database connections.  The
 1109 ** [PRAGMA data_version] command provides a mechanism to detect changes to
 1110 ** a single attached database that occur due to other database connections,
 1111 ** but omits changes implemented by the database connection on which it is
 1112 ** called.  This file control is the only mechanism to detect changes that
 1113 ** happen either internally or externally and that are associated with
 1114 ** a particular attached database.
 1115 **
 1116 ** <li>[[SQLITE_FCNTL_CKPT_START]]
 1117 ** The [SQLITE_FCNTL_CKPT_START] opcode is invoked from within a checkpoint
 1118 ** in wal mode before the client starts to copy pages from the wal
 1119 ** file to the database file.
 1120 **
 1121 ** <li>[[SQLITE_FCNTL_CKPT_DONE]]
 1122 ** The [SQLITE_FCNTL_CKPT_DONE] opcode is invoked from within a checkpoint
 1123 ** in wal mode after the client has finished copying pages from the wal
 1124 ** file to the database file, but before the *-shm file is updated to
 1125 ** record the fact that the pages have been checkpointed.
 1126 ** </ul>
 1127 */
 1128 #define SQLITE_FCNTL_LOCKSTATE               1
 1129 #define SQLITE_FCNTL_GET_LOCKPROXYFILE       2
 1130 #define SQLITE_FCNTL_SET_LOCKPROXYFILE       3
 1131 #define SQLITE_FCNTL_LAST_ERRNO              4
 1132 #define SQLITE_FCNTL_SIZE_HINT               5
 1133 #define SQLITE_FCNTL_CHUNK_SIZE              6
 1134 #define SQLITE_FCNTL_FILE_POINTER            7
 1135 #define SQLITE_FCNTL_SYNC_OMITTED            8
 1136 #define SQLITE_FCNTL_WIN32_AV_RETRY          9
 1137 #define SQLITE_FCNTL_PERSIST_WAL            10
 1138 #define SQLITE_FCNTL_OVERWRITE              11
 1139 #define SQLITE_FCNTL_VFSNAME                12
 1140 #define SQLITE_FCNTL_POWERSAFE_OVERWRITE    13
 1141 #define SQLITE_FCNTL_PRAGMA                 14
 1142 #define SQLITE_FCNTL_BUSYHANDLER            15
 1143 #define SQLITE_FCNTL_TEMPFILENAME           16
 1144 #define SQLITE_FCNTL_MMAP_SIZE              18
 1145 #define SQLITE_FCNTL_TRACE                  19
 1146 #define SQLITE_FCNTL_HAS_MOVED              20
 1147 #define SQLITE_FCNTL_SYNC                   21
 1148 #define SQLITE_FCNTL_COMMIT_PHASETWO        22
 1149 #define SQLITE_FCNTL_WIN32_SET_HANDLE       23
 1150 #define SQLITE_FCNTL_WAL_BLOCK              24
 1151 #define SQLITE_FCNTL_ZIPVFS                 25
 1152 #define SQLITE_FCNTL_RBU                    26
 1153 #define SQLITE_FCNTL_VFS_POINTER            27
 1154 #define SQLITE_FCNTL_JOURNAL_POINTER        28
 1155 #define SQLITE_FCNTL_WIN32_GET_HANDLE       29
 1156 #define SQLITE_FCNTL_PDB                    30
 1157 #define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE     31
 1158 #define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE    32
 1159 #define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE  33
 1160 #define SQLITE_FCNTL_LOCK_TIMEOUT           34
 1161 #define SQLITE_FCNTL_DATA_VERSION           35
 1162 #define SQLITE_FCNTL_SIZE_LIMIT             36
 1163 #define SQLITE_FCNTL_CKPT_DONE              37
 1164 #define SQLITE_FCNTL_RESERVE_BYTES          38
 1165 #define SQLITE_FCNTL_CKPT_START             39
 1166 
 1167 /* deprecated names */
 1168 #define SQLITE_GET_LOCKPROXYFILE      SQLITE_FCNTL_GET_LOCKPROXYFILE
 1169 #define SQLITE_SET_LOCKPROXYFILE      SQLITE_FCNTL_SET_LOCKPROXYFILE
 1170 #define SQLITE_LAST_ERRNO             SQLITE_FCNTL_LAST_ERRNO
 1171 
 1172 
 1173 /*
 1174 ** CAPI3REF: Mutex Handle
 1175 **
 1176 ** The mutex module within SQLite defines [sqlite3_mutex] to be an
 1177 ** abstract type for a mutex object.  The SQLite core never looks
 1178 ** at the internal representation of an [sqlite3_mutex].  It only
 1179 ** deals with pointers to the [sqlite3_mutex] object.
 1180 **
 1181 ** Mutexes are created using [sqlite3_mutex_alloc()].
 1182 */
 1183 typedef struct sqlite3_mutex sqlite3_mutex;
 1184 
 1185 /*
 1186 ** CAPI3REF: Loadable Extension Thunk
 1187 **
 1188 ** A pointer to the opaque sqlite3_api_routines structure is passed as
 1189 ** the third parameter to entry points of [loadable extensions].  This
 1190 ** structure must be typedefed in order to work around compiler warnings
 1191 ** on some platforms.
 1192 */
 1193 typedef struct sqlite3_api_routines sqlite3_api_routines;
 1194 
 1195 /*
 1196 ** CAPI3REF: OS Interface Object
 1197 **
 1198 ** An instance of the sqlite3_vfs object defines the interface between
 1199 ** the SQLite core and the underlying operating system.  The "vfs"
 1200 ** in the name of the object stands for "virtual file system".  See
 1201 ** the [VFS | VFS documentation] for further information.
 1202 **
 1203 ** The VFS interface is sometimes extended by adding new methods onto
 1204 ** the end.  Each time such an extension occurs, the iVersion field
 1205 ** is incremented.  The iVersion value started out as 1 in
 1206 ** SQLite [version 3.5.0] on [dateof:3.5.0], then increased to 2
 1207 ** with SQLite [version 3.7.0] on [dateof:3.7.0], and then increased
 1208 ** to 3 with SQLite [version 3.7.6] on [dateof:3.7.6].  Additional fields
 1209 ** may be appended to the sqlite3_vfs object and the iVersion value
 1210 ** may increase again in future versions of SQLite.
 1211 ** Note that due to an oversight, the structure
 1212 ** of the sqlite3_vfs object changed in the transition from
 1213 ** SQLite [version 3.5.9] to [version 3.6.0] on [dateof:3.6.0]
 1214 ** and yet the iVersion field was not increased.
 1215 **
 1216 ** The szOsFile field is the size of the subclassed [sqlite3_file]
 1217 ** structure used by this VFS.  mxPathname is the maximum length of
 1218 ** a pathname in this VFS.
 1219 **
 1220 ** Registered sqlite3_vfs objects are kept on a linked list formed by
 1221 ** the pNext pointer.  The [sqlite3_vfs_register()]
 1222 ** and [sqlite3_vfs_unregister()] interfaces manage this list
 1223 ** in a thread-safe way.  The [sqlite3_vfs_find()] interface
 1224 ** searches the list.  Neither the application code nor the VFS
 1225 ** implementation should use the pNext pointer.
 1226 **
 1227 ** The pNext field is the only field in the sqlite3_vfs
 1228 ** structure that SQLite will ever modify.  SQLite will only access
 1229 ** or modify this field while holding a particular static mutex.
 1230 ** The application should never modify anything within the sqlite3_vfs
 1231 ** object once the object has been registered.
 1232 **
 1233 ** The zName field holds the name of the VFS module.  The name must
 1234 ** be unique across all VFS modules.
 1235 **
 1236 ** [[sqlite3_vfs.xOpen]]
 1237 ** ^SQLite guarantees that the zFilename parameter to xOpen
 1238 ** is either a NULL pointer or string obtained
 1239 ** from xFullPathname() with an optional suffix added.
 1240 ** ^If a suffix is added to the zFilename parameter, it will
 1241 ** consist of a single "-" character followed by no more than
 1242 ** 11 alphanumeric and/or "-" characters.
 1243 ** ^SQLite further guarantees that
 1244 ** the string will be valid and unchanged until xClose() is
 1245 ** called. Because of the previous sentence,
 1246 ** the [sqlite3_file] can safely store a pointer to the
 1247 ** filename if it needs to remember the filename for some reason.
 1248 ** If the zFilename parameter to xOpen is a NULL pointer then xOpen
 1249 ** must invent its own temporary name for the file.  ^Whenever the 
 1250 ** xFilename parameter is NULL it will also be the case that the
 1251 ** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
 1252 **
 1253 ** The flags argument to xOpen() includes all bits set in
 1254 ** the flags argument to [sqlite3_open_v2()].  Or if [sqlite3_open()]
 1255 ** or [sqlite3_open16()] is used, then flags includes at least
 1256 ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. 
 1257 ** If xOpen() opens a file read-only then it sets *pOutFlags to
 1258 ** include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be set.
 1259 **
 1260 ** ^(SQLite will also add one of the following flags to the xOpen()
 1261 ** call, depending on the object being opened:
 1262 **
 1263 ** <ul>
 1264 ** <li>  [SQLITE_OPEN_MAIN_DB]
 1265 ** <li>  [SQLITE_OPEN_MAIN_JOURNAL]
 1266 ** <li>  [SQLITE_OPEN_TEMP_DB]
 1267 ** <li>  [SQLITE_OPEN_TEMP_JOURNAL]
 1268 ** <li>  [SQLITE_OPEN_TRANSIENT_DB]
 1269 ** <li>  [SQLITE_OPEN_SUBJOURNAL]
 1270 ** <li>  [SQLITE_OPEN_MASTER_JOURNAL]
 1271 ** <li>  [SQLITE_OPEN_WAL]
 1272 ** </ul>)^
 1273 **
 1274 ** The file I/O implementation can use the object type flags to
 1275 ** change the way it deals with files.  For example, an application
 1276 ** that does not care about crash recovery or rollback might make
 1277 ** the open of a journal file a no-op.  Writes to this journal would
 1278 ** also be no-ops, and any attempt to read the journal would return
 1279 ** SQLITE_IOERR.  Or the implementation might recognize that a database
 1280 ** file will be doing page-aligned sector reads and writes in a random
 1281 ** order and set up its I/O subsystem accordingly.
 1282 **
 1283 ** SQLite might also add one of the following flags to the xOpen method:
 1284 **
 1285 ** <ul>
 1286 ** <li> [SQLITE_OPEN_DELETEONCLOSE]
 1287 ** <li> [SQLITE_OPEN_EXCLUSIVE]
 1288 ** </ul>
 1289 **
 1290 ** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
 1291 ** deleted when it is closed.  ^The [SQLITE_OPEN_DELETEONCLOSE]
 1292 ** will be set for TEMP databases and their journals, transient
 1293 ** databases, and subjournals.
 1294 **
 1295 ** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
 1296 ** with the [SQLITE_OPEN_CREATE] flag, which are both directly
 1297 ** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
 1298 ** API.  The SQLITE_OPEN_EXCLUSIVE flag, when paired with the 
 1299 ** SQLITE_OPEN_CREATE, is used to indicate that file should always
 1300 ** be created, and that it is an error if it already exists.
 1301 ** It is <i>not</i> used to indicate the file should be opened 
 1302 ** for exclusive access.
 1303 **
 1304 ** ^At least szOsFile bytes of memory are allocated by SQLite
 1305 ** to hold the [sqlite3_file] structure passed as the third
 1306 ** argument to xOpen.  The xOpen method does not have to
 1307 ** allocate the structure; it should just fill it in.  Note that
 1308 ** the xOpen method must set the sqlite3_file.pMethods to either
 1309 ** a valid [sqlite3_io_methods] object or to NULL.  xOpen must do
 1310 ** this even if the open fails.  SQLite expects that the sqlite3_file.pMethods
 1311 ** element will be valid after xOpen returns regardless of the success
 1312 ** or failure of the xOpen call.
 1313 **
 1314 ** [[sqlite3_vfs.xAccess]]
 1315 ** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
 1316 ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
 1317 ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
 1318 ** to test whether a file is at least readable.  The SQLITE_ACCESS_READ
 1319 ** flag is never actually used and is not implemented in the built-in
 1320 ** VFSes of SQLite.  The file is named by the second argument and can be a
 1321 ** directory. The xAccess method returns [SQLITE_OK] on success or some
 1322 ** non-zero error code if there is an I/O error or if the name of
 1323 ** the file given in the second argument is illegal.  If SQLITE_OK
 1324 ** is returned, then non-zero or zero is written into *pResOut to indicate
 1325 ** whether or not the file is accessible.  
 1326 **
 1327 ** ^SQLite will always allocate at least mxPathname+1 bytes for the
 1328 ** output buffer xFullPathname.  The exact size of the output buffer
 1329 ** is also passed as a parameter to both  methods. If the output buffer
 1330 ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
 1331 ** handled as a fatal error by SQLite, vfs implementations should endeavor
 1332 ** to prevent this by setting mxPathname to a sufficiently large value.
 1333 **
 1334 ** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
 1335 ** interfaces are not strictly a part of the filesystem, but they are
 1336 ** included in the VFS structure for completeness.
 1337 ** The xRandomness() function attempts to return nBytes bytes
 1338 ** of good-quality randomness into zOut.  The return value is
 1339 ** the actual number of bytes of randomness obtained.
 1340 ** The xSleep() method causes the calling thread to sleep for at
 1341 ** least the number of microseconds given.  ^The xCurrentTime()
 1342 ** method returns a Julian Day Number for the current date and time as
 1343 ** a floating point value.
 1344 ** ^The xCurrentTimeInt64() method returns, as an integer, the Julian
 1345 ** Day Number multiplied by 86400000 (the number of milliseconds in 
 1346 ** a 24-hour day).  
 1347 ** ^SQLite will use the xCurrentTimeInt64() method to get the current
 1348 ** date and time if that method is available (if iVersion is 2 or 
 1349 ** greater and the function pointer is not NULL) and will fall back
 1350 ** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
 1351 **
 1352 ** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
 1353 ** are not used by the SQLite core.  These optional interfaces are provided
 1354 ** by some VFSes to facilitate testing of the VFS code. By overriding 
 1355 ** system calls with functions under its control, a test program can
 1356 ** simulate faults and error conditions that would otherwise be difficult
 1357 ** or impossible to induce.  The set of system calls that can be overridden
 1358 ** varies from one VFS to another, and from one version of the same VFS to the
 1359 ** next.  Applications that use these interfaces must be prepared for any
 1360 ** or all of these interfaces to be NULL or for their behavior to change
 1361 ** from one release to the next.  Applications must not attempt to access
 1362 ** any of these methods if the iVersion of the VFS is less than 3.
 1363 */
 1364 typedef struct sqlite3_vfs sqlite3_vfs;
 1365 typedef void (*sqlite3_syscall_ptr)(void);
 1366 struct sqlite3_vfs {
 1367   int iVersion;            /* Structure version number (currently 3) */
 1368   int szOsFile;            /* Size of subclassed sqlite3_file */
 1369   int mxPathname;          /* Maximum file pathname length */
 1370   sqlite3_vfs *pNext;      /* Next registered VFS */
 1371   const char *zName;       /* Name of this virtual file system */
 1372   void *pAppData;          /* Pointer to application-specific data */
 1373   int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
 1374                int flags, int *pOutFlags);
 1375   int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
 1376   int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
 1377   int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
 1378   void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
 1379   void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
 1380   void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
 1381   void (*xDlClose)(sqlite3_vfs*, void*);
 1382   int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
 1383   int (*xSleep)(sqlite3_vfs*, int microseconds);
 1384   int (*xCurrentTime)(sqlite3_vfs*, double*);
 1385   int (*xGetLastError)(sqlite3_vfs*, int, char *);
 1386   /*
 1387   ** The methods above are in version 1 of the sqlite_vfs object
 1388   ** definition.  Those that follow are added in version 2 or later
 1389   */
 1390   int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
 1391   /*
 1392   ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
 1393   ** Those below are for version 3 and greater.
 1394   */
 1395   int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
 1396   sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
 1397   const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
 1398   /*
 1399   ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
 1400   ** New fields may be appended in future versions.  The iVersion
 1401   ** value will increment whenever this happens. 
 1402   */
 1403 };
 1404 
 1405 /*
 1406 ** CAPI3REF: Flags for the xAccess VFS method
 1407 **
 1408 ** These integer constants can be used as the third parameter to
 1409 ** the xAccess method of an [sqlite3_vfs] object.  They determine
 1410 ** what kind of permissions the xAccess method is looking for.
 1411 ** With SQLITE_ACCESS_EXISTS, the xAccess method
 1412 ** simply checks whether the file exists.
 1413 ** With SQLITE_ACCESS_READWRITE, the xAccess method
 1414 ** checks whether the named directory is both readable and writable
 1415 ** (in other words, if files can be added, removed, and renamed within
 1416 ** the directory).
 1417 ** The SQLITE_ACCESS_READWRITE constant is currently used only by the
 1418 ** [temp_store_directory pragma], though this could change in a future
 1419 ** release of SQLite.
 1420 ** With SQLITE_ACCESS_READ, the xAccess method
 1421 ** checks whether the file is readable.  The SQLITE_ACCESS_READ constant is
 1422 ** currently unused, though it might be used in a future release of
 1423 ** SQLite.
 1424 */
 1425 #define SQLITE_ACCESS_EXISTS    0
 1426 #define SQLITE_ACCESS_READWRITE 1   /* Used by PRAGMA temp_store_directory */
 1427 #define SQLITE_ACCESS_READ      2   /* Unused */
 1428 
 1429 /*
 1430 ** CAPI3REF: Flags for the xShmLock VFS method
 1431 **
 1432 ** These integer constants define the various locking operations
 1433 ** allowed by the xShmLock method of [sqlite3_io_methods].  The
 1434 ** following are the only legal combinations of flags to the
 1435 ** xShmLock method:
 1436 **
 1437 ** <ul>
 1438 ** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
 1439 ** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
 1440 ** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
 1441 ** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
 1442 ** </ul>
 1443 **
 1444 ** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
 1445 ** was given on the corresponding lock.  
 1446 **
 1447 ** The xShmLock method can transition between unlocked and SHARED or
 1448 ** between unlocked and EXCLUSIVE.  It cannot transition between SHARED
 1449 ** and EXCLUSIVE.
 1450 */
 1451 #define SQLITE_SHM_UNLOCK       1
 1452 #define SQLITE_SHM_LOCK         2
 1453 #define SQLITE_SHM_SHARED       4
 1454 #define SQLITE_SHM_EXCLUSIVE    8
 1455 
 1456 /*
 1457 ** CAPI3REF: Maximum xShmLock index
 1458 **
 1459 ** The xShmLock method on [sqlite3_io_methods] may use values
 1460 ** between 0 and this upper bound as its "offset" argument.
 1461 ** The SQLite core will never attempt to acquire or release a
 1462 ** lock outside of this range
 1463 */
 1464 #define SQLITE_SHM_NLOCK        8
 1465 
 1466 
 1467 /*
 1468 ** CAPI3REF: Initialize The SQLite Library
 1469 **
 1470 ** ^The sqlite3_initialize() routine initializes the
 1471 ** SQLite library.  ^The sqlite3_shutdown() routine
 1472 ** deallocates any resources that were allocated by sqlite3_initialize().
 1473 ** These routines are designed to aid in process initialization and
 1474 ** shutdown on embedded systems.  Workstation applications using
 1475 ** SQLite normally do not need to invoke either of these routines.
 1476 **
 1477 ** A call to sqlite3_initialize() is an "effective" call if it is
 1478 ** the first time sqlite3_initialize() is invoked during the lifetime of
 1479 ** the process, or if it is the first time sqlite3_initialize() is invoked
 1480 ** following a call to sqlite3_shutdown().  ^(Only an effective call
 1481 ** of sqlite3_initialize() does any initialization.  All other calls
 1482 ** are harmless no-ops.)^
 1483 **
 1484 ** A call to sqlite3_shutdown() is an "effective" call if it is the first
 1485 ** call to sqlite3_shutdown() since the last sqlite3_initialize().  ^(Only
 1486 ** an effective call to sqlite3_shutdown() does any deinitialization.
 1487 ** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
 1488 **
 1489 ** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
 1490 ** is not.  The sqlite3_shutdown() interface must only be called from a
 1491 ** single thread.  All open [database connections] must be closed and all
 1492 ** other SQLite resources must be deallocated prior to invoking
 1493 ** sqlite3_shutdown().
 1494 **
 1495 ** Among other things, ^sqlite3_initialize() will invoke
 1496 ** sqlite3_os_init().  Similarly, ^sqlite3_shutdown()
 1497 ** will invoke sqlite3_os_end().
 1498 **
 1499 ** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
 1500 ** ^If for some reason, sqlite3_initialize() is unable to initialize
 1501 ** the library (perhaps it is unable to allocate a needed resource such
 1502 ** as a mutex) it returns an [error code] other than [SQLITE_OK].
 1503 **
 1504 ** ^The sqlite3_initialize() routine is called internally by many other
 1505 ** SQLite interfaces so that an application usually does not need to
 1506 ** invoke sqlite3_initialize() directly.  For example, [sqlite3_open()]
 1507 ** calls sqlite3_initialize() so the SQLite library will be automatically
 1508 ** initialized when [sqlite3_open()] is called if it has not be initialized
 1509 ** already.  ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
 1510 ** compile-time option, then the automatic calls to sqlite3_initialize()
 1511 ** are omitted and the application must call sqlite3_initialize() directly
 1512 ** prior to using any other SQLite interface.  For maximum portability,
 1513 ** it is recommended that applications always invoke sqlite3_initialize()
 1514 ** directly prior to using any other SQLite interface.  Future releases
 1515 ** of SQLite may require this.  In other words, the behavior exhibited
 1516 ** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
 1517 ** default behavior in some future release of SQLite.
 1518 **
 1519 ** The sqlite3_os_init() routine does operating-system specific
 1520 ** initialization of the SQLite library.  The sqlite3_os_end()
 1521 ** routine undoes the effect of sqlite3_os_init().  Typical tasks
 1522 ** performed by these routines include allocation or deallocation
 1523 ** of static resources, initialization of global variables,
 1524 ** setting up a default [sqlite3_vfs] module, or setting up
 1525 ** a default configuration using [sqlite3_config()].
 1526 **
 1527 ** The application should never invoke either sqlite3_os_init()
 1528 ** or sqlite3_os_end() directly.  The application should only invoke
 1529 ** sqlite3_initialize() and sqlite3_shutdown().  The sqlite3_os_init()
 1530 ** interface is called automatically by sqlite3_initialize() and
 1531 ** sqlite3_os_end() is called by sqlite3_shutdown().  Appropriate
 1532 ** implementations for sqlite3_os_init() and sqlite3_os_end()
 1533 ** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
 1534 ** When [custom builds | built for other platforms]
 1535 ** (using the [SQLITE_OS_OTHER=1] compile-time
 1536 ** option) the application must supply a suitable implementation for
 1537 ** sqlite3_os_init() and sqlite3_os_end().  An application-supplied
 1538 ** implementation of sqlite3_os_init() or sqlite3_os_end()
 1539 ** must return [SQLITE_OK] on success and some other [error code] upon
 1540 ** failure.
 1541 */
 1542 SQLITE_API int sqlite3_initialize(void);
 1543 SQLITE_API int sqlite3_shutdown(void);
 1544 SQLITE_API int sqlite3_os_init(void);
 1545 SQLITE_API int sqlite3_os_end(void);
 1546 
 1547 /*
 1548 ** CAPI3REF: Configuring The SQLite Library
 1549 **
 1550 ** The sqlite3_config() interface is used to make global configuration
 1551 ** changes to SQLite in order to tune SQLite to the specific needs of
 1552 ** the application.  The default configuration is recommended for most
 1553 ** applications and so this routine is usually not necessary.  It is
 1554 ** provided to support rare applications with unusual needs.
 1555 **
 1556 ** <b>The sqlite3_config() interface is not threadsafe. The application
 1557 ** must ensure that no other SQLite interfaces are invoked by other
 1558 ** threads while sqlite3_config() is running.</b>
 1559 **
 1560 ** The sqlite3_config() interface
 1561 ** may only be invoked prior to library initialization using
 1562 ** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
 1563 ** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
 1564 ** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
 1565 ** Note, however, that ^sqlite3_config() can be called as part of the
 1566 ** implementation of an application-defined [sqlite3_os_init()].
 1567 **
 1568 ** The first argument to sqlite3_config() is an integer
 1569 ** [configuration option] that determines
 1570 ** what property of SQLite is to be configured.  Subsequent arguments
 1571 ** vary depending on the [configuration option]
 1572 ** in the first argument.
 1573 **
 1574 ** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
 1575 ** ^If the option is unknown or SQLite is unable to set the option
 1576 ** then this routine returns a non-zero [error code].
 1577 */
 1578 SQLITE_API int sqlite3_config(int, ...);
 1579 
 1580 /*
 1581 ** CAPI3REF: Configure database connections
 1582 ** METHOD: sqlite3
 1583 **
 1584 ** The sqlite3_db_config() interface is used to make configuration
 1585 ** changes to a [database connection].  The interface is similar to
 1586 ** [sqlite3_config()] except that the changes apply to a single
 1587 ** [database connection] (specified in the first argument).
 1588 **
 1589 ** The second argument to sqlite3_db_config(D,V,...)  is the
 1590 ** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code 
 1591 ** that indicates what aspect of the [database connection] is being configured.
 1592 ** Subsequent arguments vary depending on the configuration verb.
 1593 **
 1594 ** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
 1595 ** the call is considered successful.
 1596 */
 1597 SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
 1598 
 1599 /*
 1600 ** CAPI3REF: Memory Allocation Routines
 1601 **
 1602 ** An instance of this object defines the interface between SQLite
 1603 ** and low-level memory allocation routines.
 1604 **
 1605 ** This object is used in only one place in the SQLite interface.
 1606 ** A pointer to an instance of this object is the argument to
 1607 ** [sqlite3_config()] when the configuration option is
 1608 ** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].  
 1609 ** By creating an instance of this object
 1610 ** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
 1611 ** during configuration, an application can specify an alternative
 1612 ** memory allocation subsystem for SQLite to use for all of its
 1613 ** dynamic memory needs.
 1614 **
 1615 ** Note that SQLite comes with several [built-in memory allocators]
 1616 ** that are perfectly adequate for the overwhelming majority of applications
 1617 ** and that this object is only useful to a tiny minority of applications
 1618 ** with specialized memory allocation requirements.  This object is
 1619 ** also used during testing of SQLite in order to specify an alternative
 1620 ** memory allocator that simulates memory out-of-memory conditions in
 1621 ** order to verify that SQLite recovers gracefully from such
 1622 ** conditions.
 1623 **
 1624 ** The xMalloc, xRealloc, and xFree methods must work like the
 1625 ** malloc(), realloc() and free() functions from the standard C library.
 1626 ** ^SQLite guarantees that the second argument to
 1627 ** xRealloc is always a value returned by a prior call to xRoundup.
 1628 **
 1629 ** xSize should return the allocated size of a memory allocation
 1630 ** previously obtained from xMalloc or xRealloc.  The allocated size
 1631 ** is always at least as big as the requested size but may be larger.
 1632 **
 1633 ** The xRoundup method returns what would be the allocated size of
 1634 ** a memory allocation given a particular requested size.  Most memory
 1635 ** allocators round up memory allocations at least to the next multiple
 1636 ** of 8.  Some allocators round up to a larger multiple or to a power of 2.
 1637 ** Every memory allocation request coming in through [sqlite3_malloc()]
 1638 ** or [sqlite3_realloc()] first calls xRoundup.  If xRoundup returns 0, 
 1639 ** that causes the corresponding memory allocation to fail.
 1640 **
 1641 ** The xInit method initializes the memory allocator.  For example,
 1642 ** it might allocate any required mutexes or initialize internal data
 1643 ** structures.  The xShutdown method is invoked (indirectly) by
 1644 ** [sqlite3_shutdown()] and should deallocate any resources acquired
 1645 ** by xInit.  The pAppData pointer is used as the only parameter to
 1646 ** xInit and xShutdown.
 1647 **
 1648 ** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes
 1649 ** the xInit method, so the xInit method need not be threadsafe.  The
 1650 ** xShutdown method is only called from [sqlite3_shutdown()] so it does
 1651 ** not need to be threadsafe either.  For all other methods, SQLite
 1652 ** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
 1653 ** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
 1654 ** it is by default) and so the methods are automatically serialized.
 1655 ** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
 1656 ** methods must be threadsafe or else make their own arrangements for
 1657 ** serialization.
 1658 **
 1659 ** SQLite will never invoke xInit() more than once without an intervening
 1660 ** call to xShutdown().
 1661 */
 1662 typedef struct sqlite3_mem_methods sqlite3_mem_methods;
 1663 struct sqlite3_mem_methods {
 1664   void *(*xMalloc)(int);         /* Memory allocation function */
 1665   void (*xFree)(void*);          /* Free a prior allocation */
 1666   void *(*xRealloc)(void*,int);  /* Resize an allocation */
 1667   int (*xSize)(void*);           /* Return the size of an allocation */
 1668   int (*xRoundup)(int);          /* Round up request size to allocation size */
 1669   int (*xInit)(void*);           /* Initialize the memory allocator */
 1670   void (*xShutdown)(void*);      /* Deinitialize the memory allocator */
 1671   void *pAppData;                /* Argument to xInit() and xShutdown() */
 1672 };
 1673 
 1674 /*
 1675 ** CAPI3REF: Configuration Options
 1676 ** KEYWORDS: {configuration option}
 1677 **
 1678 ** These constants are the available integer configuration options that
 1679 ** can be passed as the first argument to the [sqlite3_config()] interface.
 1680 **
 1681 ** New configuration options may be added in future releases of SQLite.
 1682 ** Existing configuration options might be discontinued.  Applications
 1683 ** should check the return code from [sqlite3_config()] to make sure that
 1684 ** the call worked.  The [sqlite3_config()] interface will return a
 1685 ** non-zero [error code] if a discontinued or unsupported configuration option
 1686 ** is invoked.
 1687 **
 1688 ** <dl>
 1689 ** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
 1690 ** <dd>There are no arguments to this option.  ^This option sets the
 1691 ** [threading mode] to Single-thread.  In other words, it disables
 1692 ** all mutexing and puts SQLite into a mode where it can only be used
 1693 ** by a single thread.   ^If SQLite is compiled with
 1694 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
 1695 ** it is not possible to change the [threading mode] from its default
 1696 ** value of Single-thread and so [sqlite3_config()] will return 
 1697 ** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
 1698 ** configuration option.</dd>
 1699 **
 1700 ** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt>
 1701 ** <dd>There are no arguments to this option.  ^This option sets the
 1702 ** [threading mode] to Multi-thread.  In other words, it disables
 1703 ** mutexing on [database connection] and [prepared statement] objects.
 1704 ** The application is responsible for serializing access to
 1705 ** [database connections] and [prepared statements].  But other mutexes
 1706 ** are enabled so that SQLite will be safe to use in a multi-threaded
 1707 ** environment as long as no two threads attempt to use the same
 1708 ** [database connection] at the same time.  ^If SQLite is compiled with
 1709 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
 1710 ** it is not possible to set the Multi-thread [threading mode] and
 1711 ** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
 1712 ** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
 1713 **
 1714 ** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt>
 1715 ** <dd>There are no arguments to this option.  ^This option sets the
 1716 ** [threading mode] to Serialized. In other words, this option enables
 1717 ** all mutexes including the recursive
 1718 ** mutexes on [database connection] and [prepared statement] objects.
 1719 ** In this mode (which is the default when SQLite is compiled with
 1720 ** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
 1721 ** to [database connections] and [prepared statements] so that the
 1722 ** application is free to use the same [database connection] or the
 1723 ** same [prepared statement] in different threads at the same time.
 1724 ** ^If SQLite is compiled with
 1725 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
 1726 ** it is not possible to set the Serialized [threading mode] and
 1727 ** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
 1728 ** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
 1729 **
 1730 ** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>
 1731 ** <dd> ^(The SQLITE_CONFIG_MALLOC option takes a single argument which is 
 1732 ** a pointer to an instance of the [sqlite3_mem_methods] structure.
 1733 ** The argument specifies
 1734 ** alternative low-level memory allocation routines to be used in place of
 1735 ** the memory allocation routines built into SQLite.)^ ^SQLite makes
 1736 ** its own private copy of the content of the [sqlite3_mem_methods] structure
 1737 ** before the [sqlite3_config()] call returns.</dd>
 1738 **
 1739 ** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>
 1740 ** <dd> ^(The SQLITE_CONFIG_GETMALLOC option takes a single argument which
 1741 ** is a pointer to an instance of the [sqlite3_mem_methods] structure.
 1742 ** The [sqlite3_mem_methods]
 1743 ** structure is filled with the currently defined memory allocation routines.)^
 1744 ** This option can be used to overload the default memory allocation
 1745 ** routines with a wrapper that simulations memory allocation failure or
 1746 ** tracks memory usage, for example. </dd>
 1747 **
 1748 ** [[SQLITE_CONFIG_SMALL_MALLOC]] <dt>SQLITE_CONFIG_SMALL_MALLOC</dt>
 1749 ** <dd> ^The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of
 1750 ** type int, interpreted as a boolean, which if true provides a hint to
 1751 ** SQLite that it should avoid large memory allocations if possible.
 1752 ** SQLite will run faster if it is free to make large memory allocations,
 1753 ** but some application might prefer to run slower in exchange for
 1754 ** guarantees about memory fragmentation that are possible if large
 1755 ** allocations are avoided.  This hint is normally off.
 1756 ** </dd>
 1757 **
 1758 ** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
 1759 ** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
 1760 ** interpreted as a boolean, which enables or disables the collection of
 1761 ** memory allocation statistics. ^(When memory allocation statistics are
 1762 ** disabled, the following SQLite interfaces become non-operational:
 1763 **   <ul>
 1764 **   <li> [sqlite3_hard_heap_limit64()]
 1765 **   <li> [sqlite3_memory_used()]
 1766 **   <li> [sqlite3_memory_highwater()]
 1767 **   <li> [sqlite3_soft_heap_limit64()]
 1768 **   <li> [sqlite3_status64()]
 1769 **   </ul>)^
 1770 ** ^Memory allocation statistics are enabled by default unless SQLite is
 1771 ** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
 1772 ** allocation statistics are disabled by default.
 1773 ** </dd>
 1774 **
 1775 ** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
 1776 ** <dd> The SQLITE_CONFIG_SCRATCH option is no longer used.
 1777 ** </dd>
 1778 **
 1779 ** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
 1780 ** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
 1781 ** that SQLite can use for the database page cache with the default page
 1782 ** cache implementation.  
 1783 ** This configuration option is a no-op if an application-defined page
 1784 ** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
 1785 ** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
 1786 ** 8-byte aligned memory (pMem), the size of each page cache line (sz),
 1787 ** and the number of cache lines (N).
 1788 ** The sz argument should be the size of the largest database page
 1789 ** (a power of two between 512 and 65536) plus some extra bytes for each
 1790 ** page header.  ^The number of extra bytes needed by the page header
 1791 ** can be determined using [SQLITE_CONFIG_PCACHE_HDRSZ].
 1792 ** ^It is harmless, apart from the wasted memory,
 1793 ** for the sz parameter to be larger than necessary.  The pMem
 1794 ** argument must be either a NULL pointer or a pointer to an 8-byte
 1795 ** aligned block of memory of at least sz*N bytes, otherwise
 1796 ** subsequent behavior is undefined.
 1797 ** ^When pMem is not NULL, SQLite will strive to use the memory provided
 1798 ** to satisfy page cache needs, falling back to [sqlite3_malloc()] if
 1799 ** a page cache line is larger than sz bytes or if all of the pMem buffer
 1800 ** is exhausted.
 1801 ** ^If pMem is NULL and N is non-zero, then each database connection
 1802 ** does an initial bulk allocation for page cache memory
 1803 ** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
 1804 ** of -1024*N bytes if N is negative, . ^If additional
 1805 ** page cache memory is needed beyond what is provided by the initial
 1806 ** allocation, then SQLite goes to [sqlite3_malloc()] separately for each
 1807 ** additional cache line. </dd>
 1808 **
 1809 ** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
 1810 ** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer 
 1811 ** that SQLite will use for all of its dynamic memory allocation needs
 1812 ** beyond those provided for by [SQLITE_CONFIG_PAGECACHE].
 1813 ** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
 1814 ** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
 1815 ** [SQLITE_ERROR] if invoked otherwise.
 1816 ** ^There are three arguments to SQLITE_CONFIG_HEAP:
 1817 ** An 8-byte aligned pointer to the memory,
 1818 ** the number of bytes in the memory buffer, and the minimum allocation size.
 1819 ** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
 1820 ** to using its default memory allocator (the system malloc() implementation),
 1821 ** undoing any prior invocation of [SQLITE_CONFIG_MALLOC].  ^If the
 1822 ** memory pointer is not NULL then the alternative memory
 1823 ** allocator is engaged to handle all of SQLites memory allocation needs.
 1824 ** The first pointer (the memory pointer) must be aligned to an 8-byte
 1825 ** boundary or subsequent behavior of SQLite will be undefined.
 1826 ** The minimum allocation size is capped at 2**12. Reasonable values
 1827 ** for the minimum allocation size are 2**5 through 2**8.</dd>
 1828 **
 1829 ** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
 1830 ** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
 1831 ** pointer to an instance of the [sqlite3_mutex_methods] structure.
 1832 ** The argument specifies alternative low-level mutex routines to be used
 1833 ** in place the mutex routines built into SQLite.)^  ^SQLite makes a copy of
 1834 ** the content of the [sqlite3_mutex_methods] structure before the call to
 1835 ** [sqlite3_config()] returns. ^If SQLite is compiled with
 1836 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
 1837 ** the entire mutexing subsystem is omitted from the build and hence calls to
 1838 ** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
 1839 ** return [SQLITE_ERROR].</dd>
 1840 **
 1841 ** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
 1842 ** <dd> ^(The SQLITE_CONFIG_GETMUTEX option takes a single argument which
 1843 ** is a pointer to an instance of the [sqlite3_mutex_methods] structure.  The
 1844 ** [sqlite3_mutex_methods]
 1845 ** structure is filled with the currently defined mutex routines.)^
 1846 ** This option can be used to overload the default mutex allocation
 1847 ** routines with a wrapper used to track mutex usage for performance
 1848 ** profiling or testing, for example.   ^If SQLite is compiled with
 1849 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
 1850 ** the entire mutexing subsystem is omitted from the build and hence calls to
 1851 ** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
 1852 ** return [SQLITE_ERROR].</dd>
 1853 **
 1854 ** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
 1855 ** <dd> ^(The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine
 1856 ** the default size of lookaside memory on each [database connection].
 1857 ** The first argument is the
 1858 ** size of each lookaside buffer slot and the second is the number of
 1859 ** slots allocated to each database connection.)^  ^(SQLITE_CONFIG_LOOKASIDE
 1860 ** sets the <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
 1861 ** option to [sqlite3_db_config()] can be used to change the lookaside
 1862 ** configuration on individual connections.)^ </dd>
 1863 **
 1864 ** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>
 1865 ** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is 
 1866 ** a pointer to an [sqlite3_pcache_methods2] object.  This object specifies
 1867 ** the interface to a custom page cache implementation.)^
 1868 ** ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.</dd>
 1869 **
 1870 ** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
 1871 ** <dd> ^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
 1872 ** is a pointer to an [sqlite3_pcache_methods2] object.  SQLite copies of
 1873 ** the current page cache implementation into that object.)^ </dd>
 1874 **
 1875 ** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
 1876 ** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
 1877 ** global [error log].
 1878 ** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
 1879 ** function with a call signature of void(*)(void*,int,const char*), 
 1880 ** and a pointer to void. ^If the function pointer is not NULL, it is
 1881 ** invoked by [sqlite3_log()] to process each logging event.  ^If the
 1882 ** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
 1883 ** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
 1884 ** passed through as the first parameter to the application-defined logger
 1885 ** function whenever that function is invoked.  ^The second parameter to
 1886 ** the logger function is a copy of the first parameter to the corresponding
 1887 ** [sqlite3_log()] call and is intended to be a [result code] or an
 1888 ** [extended result code].  ^The third parameter passed to the logger is
 1889 ** log message after formatting via [sqlite3_snprintf()].
 1890 ** The SQLite logging interface is not reentrant; the logger function
 1891 ** supplied by the application must not invoke any SQLite interface.
 1892 ** In a multi-threaded application, the application-defined logger
 1893 ** function must be threadsafe. </dd>
 1894 **
 1895 ** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
 1896 ** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.
 1897 ** If non-zero, then URI handling is globally enabled. If the parameter is zero,
 1898 ** then URI handling is globally disabled.)^ ^If URI handling is globally
 1899 ** enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()],
 1900 ** [sqlite3_open16()] or
 1901 ** specified as part of [ATTACH] commands are interpreted as URIs, regardless
 1902 ** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
 1903 ** connection is opened. ^If it is globally disabled, filenames are
 1904 ** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
 1905 ** database connection is opened. ^(By default, URI handling is globally
 1906 ** disabled. The default value may be changed by compiling with the
 1907 ** [SQLITE_USE_URI] symbol defined.)^
 1908 **
 1909 ** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
 1910 ** <dd>^The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
 1911 ** argument which is interpreted as a boolean in order to enable or disable
 1912 ** the use of covering indices for full table scans in the query optimizer.
 1913 ** ^The default setting is determined
 1914 ** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
 1915 ** if that compile-time option is omitted.
 1916 ** The ability to disable the use of covering indices for full table scans
 1917 ** is because some incorrectly coded legacy applications might malfunction
 1918 ** when the optimization is enabled.  Providing the ability to
 1919 ** disable the optimization allows the older, buggy application code to work
 1920 ** without change even with newer versions of SQLite.
 1921 **
 1922 ** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]]
 1923 ** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
 1924 ** <dd> These options are obsolete and should not be used by new code.
 1925 ** They are retained for backwards compatibility but are now no-ops.
 1926 ** </dd>
 1927 **
 1928 ** [[SQLITE_CONFIG_SQLLOG]]
 1929 ** <dt>SQLITE_CONFIG_SQLLOG
 1930 ** <dd>This option is only available if sqlite is compiled with the
 1931 ** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should
 1932 ** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
 1933 ** The second should be of type (void*). The callback is invoked by the library
 1934 ** in three separate circumstances, identified by the value passed as the
 1935 ** fourth parameter. If the fourth parameter is 0, then the database connection
 1936 ** passed as the second argument has just been opened. The third argument
 1937 ** points to a buffer containing the name of the main database file. If the
 1938 ** fourth parameter is 1, then the SQL statement that the third parameter
 1939 ** points to has just been executed. Or, if the fourth parameter is 2, then
 1940 ** the connection being passed as the second parameter is being closed. The
 1941 ** third parameter is passed NULL In this case.  An example of using this
 1942 ** configuration option can be seen in the "test_sqllog.c" source file in
 1943 ** the canonical SQLite source tree.</dd>
 1944 **
 1945 ** [[SQLITE_CONFIG_MMAP_SIZE]]
 1946 ** <dt>SQLITE_CONFIG_MMAP_SIZE
 1947 ** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
 1948 ** that are the default mmap size limit (the default setting for
 1949 ** [PRAGMA mmap_size]) and the maximum allowed mmap size limit.
 1950 ** ^The default setting can be overridden by each database connection using
 1951 ** either the [PRAGMA mmap_size] command, or by using the
 1952 ** [SQLITE_FCNTL_MMAP_SIZE] file control.  ^(The maximum allowed mmap size
 1953 ** will be silently truncated if necessary so that it does not exceed the
 1954 ** compile-time maximum mmap size set by the
 1955 ** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
 1956 ** ^If either argument to this option is negative, then that argument is
 1957 ** changed to its compile-time default.
 1958 **
 1959 ** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
 1960 ** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
 1961 ** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
 1962 ** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro
 1963 ** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
 1964 ** that specifies the maximum size of the created heap.
 1965 **
 1966 ** [[SQLITE_CONFIG_PCACHE_HDRSZ]]
 1967 ** <dt>SQLITE_CONFIG_PCACHE_HDRSZ
 1968 ** <dd>^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
 1969 ** is a pointer to an integer and writes into that integer the number of extra
 1970 ** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE].
 1971 ** The amount of extra space required can change depending on the compiler,
 1972 ** target platform, and SQLite version.
 1973 **
 1974 ** [[SQLITE_CONFIG_PMASZ]]
 1975 ** <dt>SQLITE_CONFIG_PMASZ
 1976 ** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which
 1977 ** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
 1978 ** sorter to that integer.  The default minimum PMA Size is set by the
 1979 ** [SQLITE_SORTER_PMASZ] compile-time option.  New threads are launched
 1980 ** to help with sort operations when multithreaded sorting
 1981 ** is enabled (using the [PRAGMA threads] command) and the amount of content
 1982 ** to be sorted exceeds the page size times the minimum of the
 1983 ** [PRAGMA cache_size] setting and this value.
 1984 **
 1985 ** [[SQLITE_CONFIG_STMTJRNL_SPILL]]
 1986 ** <dt>SQLITE_CONFIG_STMTJRNL_SPILL
 1987 ** <dd>^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which
 1988 ** becomes the [statement journal] spill-to-disk threshold.  
 1989 ** [Statement journals] are held in memory until their size (in bytes)
 1990 ** exceeds this threshold, at which point they are written to disk.
 1991 ** Or if the threshold is -1, statement journals are always held
 1992 ** exclusively in memory.
 1993 ** Since many statement journals never become large, setting the spill
 1994 ** threshold to a value such as 64KiB can greatly reduce the amount of
 1995 ** I/O required to support statement rollback.
 1996 ** The default value for this setting is controlled by the
 1997 ** [SQLITE_STMTJRNL_SPILL] compile-time option.
 1998 **
 1999 ** [[SQLITE_CONFIG_SORTERREF_SIZE]]
 2000 ** <dt>SQLITE_CONFIG_SORTERREF_SIZE
 2001 ** <dd>The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter
 2002 ** of type (int) - the new value of the sorter-reference size threshold.
 2003 ** Usually, when SQLite uses an external sort to order records according
 2004 ** to an ORDER BY clause, all fields required by the caller are present in the
 2005 ** sorted records. However, if SQLite determines based on the declared type
 2006 ** of a table column that its values are likely to be very large - larger
 2007 ** than the configured sorter-reference size threshold - then a reference
 2008 ** is stored in each sorted record and the required column values loaded
 2009 ** from the database as records are returned in sorted order. The default
 2010 ** value for this option is to never use this optimization. Specifying a 
 2011 ** negative value for this option restores the default behaviour.
 2012 ** This option is only available if SQLite is compiled with the
 2013 ** [SQLITE_ENABLE_SORTER_REFERENCES] compile-time option.
 2014 **
 2015 ** [[SQLITE_CONFIG_MEMDB_MAXSIZE]]
 2016 ** <dt>SQLITE_CONFIG_MEMDB_MAXSIZE
 2017 ** <dd>The SQLITE_CONFIG_MEMDB_MAXSIZE option accepts a single parameter
 2018 ** [sqlite3_int64] parameter which is the default maximum size for an in-memory
 2019 ** database created using [sqlite3_deserialize()].  This default maximum
 2020 ** size can be adjusted up or down for individual databases using the
 2021 ** [SQLITE_FCNTL_SIZE_LIMIT] [sqlite3_file_control|file-control].  If this
 2022 ** configuration setting is never used, then the default maximum is determined
 2023 ** by the [SQLITE_MEMDB_DEFAULT_MAXSIZE] compile-time option.  If that
 2024 ** compile-time option is not set, then the default maximum is 1073741824.
 2025 ** </dl>
 2026 */
 2027 #define SQLITE_CONFIG_SINGLETHREAD  1  /* nil */
 2028 #define SQLITE_CONFIG_MULTITHREAD   2  /* nil */
 2029 #define SQLITE_CONFIG_SERIALIZED    3  /* nil */
 2030 #define SQLITE_CONFIG_MALLOC        4  /* sqlite3_mem_methods* */
 2031 #define SQLITE_CONFIG_GETMALLOC     5  /* sqlite3_mem_methods* */
 2032 #define SQLITE_CONFIG_SCRATCH       6  /* No longer used */
 2033 #define SQLITE_CONFIG_PAGECACHE     7  /* void*, int sz, int N */
 2034 #define SQLITE_CONFIG_HEAP          8  /* void*, int nByte, int min */
 2035 #define SQLITE_CONFIG_MEMSTATUS     9  /* boolean */
 2036 #define SQLITE_CONFIG_MUTEX        10  /* sqlite3_mutex_methods* */
 2037 #define SQLITE_CONFIG_GETMUTEX     11  /* sqlite3_mutex_methods* */
 2038 /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ 
 2039 #define SQLITE_CONFIG_LOOKASIDE    13  /* int int */
 2040 #define SQLITE_CONFIG_PCACHE       14  /* no-op */
 2041 #define SQLITE_CONFIG_GETPCACHE    15  /* no-op */
 2042 #define SQLITE_CONFIG_LOG          16  /* xFunc, void* */
 2043 #define SQLITE_CONFIG_URI          17  /* int */
 2044 #define SQLITE_CONFIG_PCACHE2      18  /* sqlite3_pcache_methods2* */
 2045 #define SQLITE_CONFIG_GETPCACHE2   19  /* sqlite3_pcache_methods2* */
 2046 #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20  /* int */
 2047 #define SQLITE_CONFIG_SQLLOG       21  /* xSqllog, void* */
 2048 #define SQLITE_CONFIG_MMAP_SIZE    22  /* sqlite3_int64, sqlite3_int64 */
 2049 #define SQLITE_CONFIG_WIN32_HEAPSIZE      23  /* int nByte */
 2050 #define SQLITE_CONFIG_PCACHE_HDRSZ        24  /* int *psz */
 2051 #define SQLITE_CONFIG_PMASZ               25  /* unsigned int szPma */
 2052 #define SQLITE_CONFIG_STMTJRNL_SPILL      26  /* int nByte */
 2053 #define SQLITE_CONFIG_SMALL_MALLOC        27  /* boolean */
 2054 #define SQLITE_CONFIG_SORTERREF_SIZE      28  /* int nByte */
 2055 #define SQLITE_CONFIG_MEMDB_MAXSIZE       29  /* sqlite3_int64 */
 2056 
 2057 /*
 2058 ** CAPI3REF: Database Connection Configuration Options
 2059 **
 2060 ** These constants are the available integer configuration options that
 2061 ** can be passed as the second argument to the [sqlite3_db_config()] interface.
 2062 **
 2063 ** New configuration options may be added in future releases of SQLite.
 2064 ** Existing configuration options might be discontinued.  Applications
 2065 ** should check the return code from [sqlite3_db_config()] to make sure that
 2066 ** the call worked.  ^The [sqlite3_db_config()] interface will return a
 2067 ** non-zero [error code] if a discontinued or unsupported configuration option
 2068 ** is invoked.
 2069 **
 2070 ** <dl>
 2071 ** [[SQLITE_DBCONFIG_LOOKASIDE]]
 2072 ** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
 2073 ** <dd> ^This option takes three additional arguments that determine the 
 2074 ** [lookaside memory allocator] configuration for the [database connection].
 2075 ** ^The first argument (the third parameter to [sqlite3_db_config()] is a
 2076 ** pointer to a memory buffer to use for lookaside memory.
 2077 ** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
 2078 ** may be NULL in which case SQLite will allocate the
 2079 ** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
 2080 ** size of each lookaside buffer slot.  ^The third argument is the number of
 2081 ** slots.  The size of the buffer in the first argument must be greater than
 2082 ** or equal to the product of the second and third arguments.  The buffer
 2083 ** must be aligned to an 8-byte boundary.  ^If the second argument to
 2084 ** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
 2085 ** rounded down to the next smaller multiple of 8.  ^(The lookaside memory
 2086 ** configuration for a database connection can only be changed when that
 2087 ** connection is not currently using lookaside memory, or in other words
 2088 ** when the "current value" returned by
 2089 ** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
 2090 ** Any attempt to change the lookaside memory configuration when lookaside
 2091 ** memory is in use leaves the configuration unchanged and returns 
 2092 ** [SQLITE_BUSY].)^</dd>
 2093 **
 2094 ** [[SQLITE_DBCONFIG_ENABLE_FKEY]]
 2095 ** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
 2096 ** <dd> ^This option is used to enable or disable the enforcement of
 2097 ** [foreign key constraints].  There should be two additional arguments.
 2098 ** The first argument is an integer which is 0 to disable FK enforcement,
 2099 ** positive to enable FK enforcement or negative to leave FK enforcement
 2100 ** unchanged.  The second parameter is a pointer to an integer into which
 2101 ** is written 0 or 1 to indicate whether FK enforcement is off or on
 2102 ** following this call.  The second parameter may be a NULL pointer, in
 2103 ** which case the FK enforcement setting is not reported back. </dd>
 2104 **
 2105 ** [[SQLITE_DBCONFIG_ENABLE_TRIGGER]]
 2106 ** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
 2107 ** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
 2108 ** There should be two additional arguments.
 2109 ** The first argument is an integer which is 0 to disable triggers,
 2110 ** positive to enable triggers or negative to leave the setting unchanged.
 2111 ** The second parameter is a pointer to an integer into which
 2112 ** is written 0 or 1 to indicate whether triggers are disabled or enabled
 2113 ** following this call.  The second parameter may be a NULL pointer, in
 2114 ** which case the trigger setting is not reported back. </dd>
 2115 **
 2116 ** [[SQLITE_DBCONFIG_ENABLE_VIEW]]
 2117 ** <dt>SQLITE_DBCONFIG_ENABLE_VIEW</dt>
 2118 ** <dd> ^This option is used to enable or disable [CREATE VIEW | views].
 2119 ** There should be two additional arguments.
 2120 ** The first argument is an integer which is 0 to disable views,
 2121 ** positive to enable views or negative to leave the setting unchanged.
 2122 ** The second parameter is a pointer to an integer into which
 2123 ** is written 0 or 1 to indicate whether views are disabled or enabled
 2124 ** following this call.  The second parameter may be a NULL pointer, in
 2125 ** which case the view setting is not reported back. </dd>
 2126 **
 2127 ** [[SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER]]
 2128 ** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt>
 2129 ** <dd> ^This option is used to enable or disable the
 2130 ** [fts3_tokenizer()] function which is part of the
 2131 ** [FTS3] full-text search engine extension.
 2132 ** There should be two additional arguments.
 2133 ** The first argument is an integer which is 0 to disable fts3_tokenizer() or
 2134 ** positive to enable fts3_tokenizer() or negative to leave the setting
 2135 ** unchanged.
 2136 ** The second parameter is a pointer to an integer into which
 2137 ** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled
 2138 ** following this call.  The second parameter may be a NULL pointer, in
 2139 ** which case the new setting is not reported back. </dd>
 2140 **
 2141 ** [[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION]]
 2142 ** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt>
 2143 ** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()]
 2144 ** interface independently of the [load_extension()] SQL function.
 2145 ** The [sqlite3_enable_load_extension()] API enables or disables both the
 2146 ** C-API [sqlite3_load_extension()] and the SQL function [load_extension()].
 2147 ** There should be two additional arguments.
 2148 ** When the first argument to this interface is 1, then only the C-API is
 2149 ** enabled and the SQL function remains disabled.  If the first argument to
 2150 ** this interface is 0, then both the C-API and the SQL function are disabled.
 2151 ** If the first argument is -1, then no changes are made to state of either the
 2152 ** C-API or the SQL function.
 2153 ** The second parameter is a pointer to an integer into which
 2154 ** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface
 2155 ** is disabled or enabled following this call.  The second parameter may
 2156 ** be a NULL pointer, in which case the new setting is not reported back.
 2157 ** </dd>
 2158 **
 2159 ** [[SQLITE_DBCONFIG_MAINDBNAME]] <dt>SQLITE_DBCONFIG_MAINDBNAME</dt>
 2160 ** <dd> ^This option is used to change the name of the "main" database
 2161 ** schema.  ^The sole argument is a pointer to a constant UTF8 string
 2162 ** which will become the new schema name in place of "main".  ^SQLite
 2163 ** does not make a copy of the new main schema name string, so the application
 2164 ** must ensure that the argument passed into this DBCONFIG option is unchanged
 2165 ** until after the database connection closes.
 2166 ** </dd>
 2167 **
 2168 ** [[SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE]] 
 2169 ** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt>
 2170 ** <dd> Usually, when a database in wal mode is closed or detached from a 
 2171 ** database handle, SQLite checks if this will mean that there are now no 
 2172 ** connections at all to the database. If so, it performs a checkpoint 
 2173 ** operation before closing the connection. This option may be used to
 2174 ** override this behaviour. The first parameter passed to this operation
 2175 ** is an integer - positive to disable checkpoints-on-close, or zero (the
 2176 ** default) to enable them, and negative to leave the setting unchanged.
 2177 ** The second parameter is a pointer to an integer
 2178 ** into which is written 0 or 1 to indicate whether checkpoints-on-close
 2179 ** have been disabled - 0 if they are not disabled, 1 if they are.
 2180 ** </dd>
 2181 **
 2182 ** [[SQLITE_DBCONFIG_ENABLE_QPSG]] <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt>
 2183 ** <dd>^(The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates
 2184 ** the [query planner stability guarantee] (QPSG).  When the QPSG is active,
 2185 ** a single SQL query statement will always use the same algorithm regardless
 2186 ** of values of [bound parameters].)^ The QPSG disables some query optimizations
 2187 ** that look at the values of bound parameters, which can make some queries
 2188 ** slower.  But the QPSG has the advantage of more predictable behavior.  With
 2189 ** the QPSG active, SQLite will always use the same query plan in the field as
 2190 ** was used during testing in the lab.
 2191 ** The first argument to this setting is an integer which is 0 to disable 
 2192 ** the QPSG, positive to enable QPSG, or negative to leave the setting
 2193 ** unchanged. The second parameter is a pointer to an integer into which
 2194 ** is written 0 or 1 to indicate whether the QPSG is disabled or enabled
 2195 ** following this call.
 2196 ** </dd>
 2197 **
 2198 ** [[SQLITE_DBCONFIG_TRIGGER_EQP]] <dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt>
 2199 ** <dd> By default, the output of EXPLAIN QUERY PLAN commands does not 
 2200 ** include output for any operations performed by trigger programs. This
 2201 ** option is used to set or clear (the default) a flag that governs this
 2202 ** behavior. The first parameter passed to this operation is an integer -
 2203 ** positive to enable output for trigger programs, or zero to disable it,
 2204 ** or negative to leave the setting unchanged.
 2205 ** The second parameter is a pointer to an integer into which is written 
 2206 ** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if 
 2207 ** it is not disabled, 1 if it is.  
 2208 ** </dd>
 2209 **
 2210 ** [[SQLITE_DBCONFIG_RESET_DATABASE]] <dt>SQLITE_DBCONFIG_RESET_DATABASE</dt>
 2211 ** <dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run
 2212 ** [VACUUM] in order to reset a database back to an empty database
 2213 ** with no schema and no content. The following process works even for
 2214 ** a badly corrupted database file:
 2215 ** <ol>
 2216 ** <li> If the database connection is newly opened, make sure it has read the
 2217 **      database schema by preparing then discarding some query against the
 2218 **      database, or calling sqlite3_table_column_metadata(), ignoring any
 2219 **      errors.  This step is only necessary if the application desires to keep
 2220 **      the database in WAL mode after the reset if it was in WAL mode before
 2221 **      the reset.  
 2222 ** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0);
 2223 ** <li> [sqlite3_exec](db, "[VACUUM]", 0, 0, 0);
 2224 ** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0);
 2225 ** </ol>
 2226 ** Because resetting a database is destructive and irreversible, the
 2227 ** process requires the use of this obscure API and multiple steps to help
 2228 ** ensure that it does not happen by accident.
 2229 **
 2230 ** [[SQLITE_DBCONFIG_DEFENSIVE]] <dt>SQLITE_DBCONFIG_DEFENSIVE</dt>
 2231 ** <dd>The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the
 2232 ** "defensive" flag for a database connection.  When the defensive
 2233 ** flag is enabled, language features that allow ordinary SQL to 
 2234 ** deliberately corrupt the database file are disabled.  The disabled
 2235 ** features include but are not limited to the following:
 2236 ** <ul>
 2237 ** <li> The [PRAGMA writable_schema=ON] statement.
 2238 ** <li> The [PRAGMA journal_mode=OFF] statement.
 2239 ** <li> Writes to the [sqlite_dbpage] virtual table.
 2240 ** <li> Direct writes to [shadow tables].
 2241 ** </ul>
 2242 ** </dd>
 2243 **
 2244 ** [[SQLITE_DBCONFIG_WRITABLE_SCHEMA]] <dt>SQLITE_DBCONFIG_WRITABLE_SCHEMA</dt>
 2245 ** <dd>The SQLITE_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates the
 2246 ** "writable_schema" flag. This has the same effect and is logically equivalent
 2247 ** to setting [PRAGMA writable_schema=ON] or [PRAGMA writable_schema=OFF].
 2248 ** The first argument to this setting is an integer which is 0 to disable 
 2249 ** the writable_schema, positive to enable writable_schema, or negative to
 2250 ** leave the setting unchanged. The second parameter is a pointer to an
 2251 ** integer into which is written 0 or 1 to indicate whether the writable_schema
 2252 ** is enabled or disabled following this call.
 2253 ** </dd>
 2254 **
 2255 ** [[SQLITE_DBCONFIG_LEGACY_ALTER_TABLE]]
 2256 ** <dt>SQLITE_DBCONFIG_LEGACY_ALTER_TABLE</dt>
 2257 ** <dd>The SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates
 2258 ** the legacy behavior of the [ALTER TABLE RENAME] command such it
 2259 ** behaves as it did prior to [version 3.24.0] (2018-06-04).  See the
 2260 ** "Compatibility Notice" on the [ALTER TABLE RENAME documentation] for
 2261 ** additional information. This feature can also be turned on and off
 2262 ** using the [PRAGMA legacy_alter_table] statement.
 2263 ** </dd>
 2264 **
 2265 ** [[SQLITE_DBCONFIG_DQS_DML]]
 2266 ** <dt>SQLITE_DBCONFIG_DQS_DML</td>
 2267 ** <dd>The SQLITE_DBCONFIG_DQS_DML option activates or deactivates
 2268 ** the legacy [double-quoted string literal] misfeature for DML statements
 2269 ** only, that is DELETE, INSERT, SELECT, and UPDATE statements. The
 2270 ** default value of this setting is determined by the [-DSQLITE_DQS]
 2271 ** compile-time option.
 2272 ** </dd>
 2273 **
 2274 ** [[SQLITE_DBCONFIG_DQS_DDL]]
 2275 ** <dt>SQLITE_DBCONFIG_DQS_DDL</td>
 2276 ** <dd>The SQLITE_DBCONFIG_DQS option activates or deactivates
 2277 ** the legacy [double-quoted string literal] misfeature for DDL statements,
 2278 ** such as CREATE TABLE and CREATE INDEX. The
 2279 ** default value of this setting is determined by the [-DSQLITE_DQS]
 2280 ** compile-time option.
 2281 ** </dd>
 2282 **
 2283 ** [[SQLITE_DBCONFIG_TRUSTED_SCHEMA]]
 2284 ** <dt>SQLITE_DBCONFIG_TRUSTED_SCHEMA</td>
 2285 ** <dd>The SQLITE_DBCONFIG_TRUSTED_SCHEMA option tells SQLite to
 2286 ** assume that database schemas (the contents of the [sqlite_master] tables)
 2287 ** are untainted by malicious content.
 2288 ** When the SQLITE_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite
 2289 ** takes additional defensive steps to protect the application from harm
 2290 ** including:
 2291 ** <ul>
 2292 ** <li> Prohibit the use of SQL functions inside triggers, views,
 2293 ** CHECK constraints, DEFAULT clauses, expression indexes, 
 2294 ** partial indexes, or generated columns
 2295 ** unless those functions are tagged with [SQLITE_INNOCUOUS].
 2296 ** <li> Prohibit the use of virtual tables inside of triggers or views
 2297 ** unless those virtual tables are tagged with [SQLITE_VTAB_INNOCUOUS].
 2298 ** </ul>
 2299 ** This setting defaults to "on" for legacy compatibility, however
 2300 ** all applications are advised to turn it off if possible. This setting
 2301 ** can also be controlled using the [PRAGMA trusted_schema] statement.
 2302 ** </dd>
 2303 **
 2304 ** [[SQLITE_DBCONFIG_LEGACY_FILE_FORMAT]]
 2305 ** <dt>SQLITE_DBCONFIG_LEGACY_FILE_FORMAT</td>
 2306 ** <dd>The SQLITE_DBCONFIG_LEGACY_FILE_FORMAT option activates or deactivates
 2307 ** the legacy file format flag.  When activated, this flag causes all newly
 2308 ** created database file to have a schema format version number (the 4-byte
 2309 ** integer found at offset 44 into the database header) of 1.  This in turn
 2310 ** means that the resulting database file will be readable and writable by
 2311 ** any SQLite version back to 3.0.0 ([dateof:3.0.0]).  Without this setting,
 2312 ** newly created databases are generally not understandable by SQLite versions
 2313 ** prior to 3.3.0 ([dateof:3.3.0]).  As these words are written, there
 2314 ** is now scarcely any need to generated database files that are compatible 
 2315 ** all the way back to version 3.0.0, and so this setting is of little
 2316 ** practical use, but is provided so that SQLite can continue to claim the
 2317 ** ability to generate new database files that are compatible with  version
 2318 ** 3.0.0.
 2319 ** <p>Note that when the SQLITE_DBCONFIG_LEGACY_FILE_FORMAT setting is on,
 2320 ** the [VACUUM] command will fail with an obscure error when attempting to
 2321 ** process a table with generated columns and a descending index.  This is
 2322 ** not considered a bug since SQLite versions 3.3.0 and earlier do not support
 2323 ** either generated columns or decending indexes.
 2324 ** </dd>
 2325 ** </dl>
 2326 */
 2327 #define SQLITE_DBCONFIG_MAINDBNAME            1000 /* const char* */
 2328 #define SQLITE_DBCONFIG_LOOKASIDE             1001 /* void* int int */
 2329 #define SQLITE_DBCONFIG_ENABLE_FKEY           1002 /* int int* */
 2330 #define SQLITE_DBCONFIG_ENABLE_TRIGGER        1003 /* int int* */
 2331 #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */
 2332 #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */
 2333 #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE      1006 /* int int* */
 2334 #define SQLITE_DBCONFIG_ENABLE_QPSG           1007 /* int int* */
 2335 #define SQLITE_DBCONFIG_TRIGGER_EQP           1008 /* int int* */
 2336 #define SQLITE_DBCONFIG_RESET_DATABASE        1009 /* int int* */
 2337 #define SQLITE_DBCONFIG_DEFENSIVE             1010 /* int int* */
 2338 #define SQLITE_DBCONFIG_WRITABLE_SCHEMA       1011 /* int int* */
 2339 #define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE    1012 /* int int* */
 2340 #define SQLITE_DBCONFIG_DQS_DML               1013 /* int int* */
 2341 #define SQLITE_DBCONFIG_DQS_DDL               1014 /* int int* */
 2342 #define SQLITE_DBCONFIG_ENABLE_VIEW           1015 /* int int* */
 2343 #define SQLITE_DBCONFIG_LEGACY_FILE_FORMAT    1016 /* int int* */
 2344 #define SQLITE_DBCONFIG_TRUSTED_SCHEMA        1017 /* int int* */
 2345 #define SQLITE_DBCONFIG_MAX                   1017 /* Largest DBCONFIG */
 2346 
 2347 /*
 2348 ** CAPI3REF: Enable Or Disable Extended Result Codes
 2349 ** METHOD: sqlite3
 2350 **
 2351 ** ^The sqlite3_extended_result_codes() routine enables or disables the
 2352 ** [extended result codes] feature of SQLite. ^The extended result
 2353 ** codes are disabled by default for historical compatibility.
 2354 */
 2355 SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
 2356 
 2357 /*
 2358 ** CAPI3REF: Last Insert Rowid
 2359 ** METHOD: sqlite3
 2360 **
 2361 ** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables)
 2362 ** has a unique 64-bit signed
 2363 ** integer key called the [ROWID | "rowid"]. ^The rowid is always available
 2364 ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
 2365 ** names are not also used by explicitly declared columns. ^If
 2366 ** the table has a column of type [INTEGER PRIMARY KEY] then that column
 2367 ** is another alias for the rowid.
 2368 **
 2369 ** ^The sqlite3_last_insert_rowid(D) interface usually returns the [rowid] of
 2370 ** the most recent successful [INSERT] into a rowid table or [virtual table]
 2371 ** on database connection D. ^Inserts into [WITHOUT ROWID] tables are not
 2372 ** recorded. ^If no successful [INSERT]s into rowid tables have ever occurred 
 2373 ** on the database connection D, then sqlite3_last_insert_rowid(D) returns 
 2374 ** zero.
 2375 **
 2376 ** As well as being set automatically as rows are inserted into database
 2377 ** tables, the value returned by this function may be set explicitly by
 2378 ** [sqlite3_set_last_insert_rowid()]
 2379 **
 2380 ** Some virtual table implementations may INSERT rows into rowid tables as
 2381 ** part of committing a transaction (e.g. to flush data accumulated in memory
 2382 ** to disk). In this case subsequent calls to this function return the rowid
 2383 ** associated with these internal INSERT operations, which leads to 
 2384 ** unintuitive results. Virtual table implementations that do write to rowid
 2385 ** tables in this way can avoid this problem by restoring the original 
 2386 ** rowid value using [sqlite3_set_last_insert_rowid()] before returning 
 2387 ** control to the user.
 2388 **
 2389 ** ^(If an [INSERT] occurs within a trigger then this routine will 
 2390 ** return the [rowid] of the inserted row as long as the trigger is 
 2391 ** running. Once the trigger program ends, the value returned 
 2392 ** by this routine reverts to what it was before the trigger was fired.)^
 2393 **
 2394 ** ^An [INSERT] that fails due to a constraint violation is not a
 2395 ** successful [INSERT] and does not change the value returned by this
 2396 ** routine.  ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
 2397 ** and INSERT OR ABORT make no changes to the return value of this
 2398 ** routine when their insertion fails.  ^(When INSERT OR REPLACE
 2399 ** encounters a constraint violation, it does not fail.  The
 2400 ** INSERT continues to completion after deleting rows that caused
 2401 ** the constraint problem so INSERT OR REPLACE will always change
 2402 ** the return value of this interface.)^
 2403 **
 2404 ** ^For the purposes of this routine, an [INSERT] is considered to
 2405 ** be successful even if it is subsequently rolled back.
 2406 **
 2407 ** This function is accessible to SQL statements via the
 2408 ** [last_insert_rowid() SQL function].
 2409 **
 2410 ** If a separate thread performs a new [INSERT] on the same
 2411 ** database connection while the [sqlite3_last_insert_rowid()]
 2412 ** function is running and thus changes the last insert [rowid],
 2413 ** then the value returned by [sqlite3_last_insert_rowid()] is
 2414 ** unpredictable and might not equal either the old or the new
 2415 ** last insert [rowid].
 2416 */
 2417 SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
 2418 
 2419 /*
 2420 ** CAPI3REF: Set the Last Insert Rowid value.
 2421 ** METHOD: sqlite3
 2422 **
 2423 ** The sqlite3_set_last_insert_rowid(D, R) method allows the application to
 2424 ** set the value returned by calling sqlite3_last_insert_rowid(D) to R 
 2425 ** without inserting a row into the database.
 2426 */
 2427 SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
 2428 
 2429 /*
 2430 ** CAPI3REF: Count The Number Of Rows Modified
 2431 ** METHOD: sqlite3
 2432 **
 2433 ** ^This function returns the number of rows modified, inserted or
 2434 ** deleted by the most recently completed INSERT, UPDATE or DELETE
 2435 ** statement on the database connection specified by the only parameter.
 2436 ** ^Executing any other type of SQL statement does not modify the value
 2437 ** returned by this function.
 2438 **
 2439 ** ^Only changes made directly by the INSERT, UPDATE or DELETE statement are
 2440 ** considered - auxiliary changes caused by [CREATE TRIGGER | triggers], 
 2441 ** [foreign key actions] or [REPLACE] constraint resolution are not counted.
 2442 ** 
 2443 ** Changes to a view that are intercepted by 
 2444 ** [INSTEAD OF trigger | INSTEAD OF triggers] are not counted. ^The value 
 2445 ** returned by sqlite3_changes() immediately after an INSERT, UPDATE or 
 2446 ** DELETE statement run on a view is always zero. Only changes made to real 
 2447 ** tables are counted.
 2448 **
 2449 ** Things are more complicated if the sqlite3_changes() function is
 2450 ** executed while a trigger program is running. This may happen if the
 2451 ** program uses the [changes() SQL function], or if some other callback
 2452 ** function invokes sqlite3_changes() directly. Essentially:
 2453 ** 
 2454 ** <ul>
 2455 **   <li> ^(Before entering a trigger program the value returned by
 2456 **        sqlite3_changes() function is saved. After the trigger program 
 2457 **        has finished, the original value is restored.)^
 2458 ** 
 2459 **   <li> ^(Within a trigger program each INSERT, UPDATE and DELETE 
 2460 **        statement sets the value returned by sqlite3_changes() 
 2461 **        upon completion as normal. Of course, this value will not include 
 2462 **        any changes performed by sub-triggers, as the sqlite3_changes() 
 2463 **        value will be saved and restored after each sub-trigger has run.)^
 2464 ** </ul>
 2465 ** 
 2466 ** ^This means that if the changes() SQL function (or similar) is used
 2467 ** by the first INSERT, UPDATE or DELETE statement within a trigger, it 
 2468 ** returns the value as set when the calling statement began executing.
 2469 ** ^If it is used by the second or subsequent such statement within a trigger 
 2470 ** program, the value returned reflects the number of rows modified by the 
 2471 ** previous INSERT, UPDATE or DELETE statement within the same trigger.
 2472 **
 2473 ** If a separate thread makes changes on the same database connection
 2474 ** while [sqlite3_changes()] is running then the value returned
 2475 ** is unpredictable and not meaningful.
 2476 **
 2477 ** See also:
 2478 ** <ul>
 2479 ** <li> the [sqlite3_total_changes()] interface
 2480 ** <li> the [count_changes pragma]
 2481 ** <li> the [changes() SQL function]
 2482 ** <li> the [data_version pragma]
 2483 ** </ul>
 2484 */
 2485 SQLITE_API int sqlite3_changes(sqlite3*);
 2486 
 2487 /*
 2488 ** CAPI3REF: Total Number Of Rows Modified
 2489 ** METHOD: sqlite3
 2490 **
 2491 ** ^This function returns the total number of rows inserted, modified or
 2492 ** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed
 2493 ** since the database connection was opened, including those executed as
 2494 ** part of trigger programs. ^Executing any other type of SQL statement
 2495 ** does not affect the value returned by sqlite3_total_changes().
 2496 ** 
 2497 ** ^Changes made as part of [foreign key actions] are included in the
 2498 ** count, but those made as part of REPLACE constraint resolution are
 2499 ** not. ^Changes to a view that are intercepted by INSTEAD OF triggers 
 2500 ** are not counted.
 2501 **
 2502 ** The [sqlite3_total_changes(D)] interface only reports the number
 2503 ** of rows that changed due to SQL statement run against database
 2504 ** connection D.  Any changes by other database connections are ignored.
 2505 ** To detect changes against a database file from other database
 2506 ** connections use the [PRAGMA data_version] command or the
 2507 ** [SQLITE_FCNTL_DATA_VERSION] [file control].
 2508 ** 
 2509 ** If a separate thread makes changes on the same database connection
 2510 ** while [sqlite3_total_changes()] is running then the value
 2511 ** returned is unpredictable and not meaningful.
 2512 **
 2513 ** See also:
 2514 ** <ul>
 2515 ** <li> the [sqlite3_changes()] interface
 2516 ** <li> the [count_changes pragma]
 2517 ** <li> the [changes() SQL function]
 2518 ** <li> the [data_version pragma]
 2519 ** <li> the [SQLITE_FCNTL_DATA_VERSION] [file control]
 2520 ** </ul>
 2521 */
 2522 SQLITE_API int sqlite3_total_changes(sqlite3*);
 2523 
 2524 /*
 2525 ** CAPI3REF: Interrupt A Long-Running Query
 2526 ** METHOD: sqlite3
 2527 **
 2528 ** ^This function causes any pending database operation to abort and
 2529 ** return at its earliest opportunity. This routine is typically
 2530 ** called in response to a user action such as pressing "Cancel"
 2531 ** or Ctrl-C where the user wants a long query operation to halt
 2532 ** immediately.
 2533 **
 2534 ** ^It is safe to call this routine from a thread different from the
 2535 ** thread that is currently running the database operation.  But it
 2536 ** is not safe to call this routine with a [database connection] that
 2537 ** is closed or might close before sqlite3_interrupt() returns.
 2538 **
 2539 ** ^If an SQL operation is very nearly finished at the time when
 2540 ** sqlite3_interrupt() is called, then it might not have an opportunity
 2541 ** to be interrupted and might continue to completion.
 2542 **
 2543 ** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
 2544 ** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
 2545 ** that is inside an explicit transaction, then the entire transaction
 2546 ** will be rolled back automatically.
 2547 **
 2548 ** ^The sqlite3_interrupt(D) call is in effect until all currently running
 2549 ** SQL statements on [database connection] D complete.  ^Any new SQL statements
 2550 ** that are started after the sqlite3_interrupt() call and before the 
 2551 ** running statement count reaches zero are interrupted as if they had been
 2552 ** running prior to the sqlite3_interrupt() call.  ^New SQL statements
 2553 ** that are started after the running statement count reaches zero are
 2554 ** not effected by the sqlite3_interrupt().
 2555 ** ^A call to sqlite3_interrupt(D) that occurs when there are no running
 2556 ** SQL statements is a no-op and has no effect on SQL statements
 2557 ** that are started after the sqlite3_interrupt() call returns.
 2558 */
 2559 SQLITE_API void sqlite3_interrupt(sqlite3*);
 2560 
 2561 /*
 2562 ** CAPI3REF: Determine If An SQL Statement Is Complete
 2563 **
 2564 ** These routines are useful during command-line input to determine if the
 2565 ** currently entered text seems to form a complete SQL statement or
 2566 ** if additional input is needed before sending the text into
 2567 ** SQLite for parsing.  ^These routines return 1 if the input string
 2568 ** appears to be a complete SQL statement.  ^A statement is judged to be
 2569 ** complete if it ends with a semicolon token and is not a prefix of a
 2570 ** well-formed CREATE TRIGGER statement.  ^Semicolons that are embedded within
 2571 ** string literals or quoted identifier names or comments are not
 2572 ** independent tokens (they are part of the token in which they are
 2573 ** embedded) and thus do not count as a statement terminator.  ^Whitespace
 2574 ** and comments that follow the final semicolon are ignored.
 2575 **
 2576 ** ^These routines return 0 if the statement is incomplete.  ^If a
 2577 ** memory allocation fails, then SQLITE_NOMEM is returned.
 2578 **
 2579 ** ^These routines do not parse the SQL statements thus
 2580 ** will not detect syntactically incorrect SQL.
 2581 **
 2582 ** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior 
 2583 ** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
 2584 ** automatically by sqlite3_complete16().  If that initialization fails,
 2585 ** then the return value from sqlite3_complete16() will be non-zero
 2586 ** regardless of whether or not the input SQL is complete.)^
 2587 **
 2588 ** The input to [sqlite3_complete()] must be a zero-terminated
 2589 ** UTF-8 string.
 2590 **
 2591 ** The input to [sqlite3_complete16()] must be a zero-terminated
 2592 ** UTF-16 string in native byte order.
 2593 */
 2594 SQLITE_API int sqlite3_complete(const char *sql);
 2595 SQLITE_API int sqlite3_complete16(const void *sql);
 2596 
 2597 /*
 2598 ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
 2599 ** KEYWORDS: {busy-handler callback} {busy handler}
 2600 ** METHOD: sqlite3
 2601 **
 2602 ** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
 2603 ** that might be invoked with argument P whenever
 2604 ** an attempt is made to access a database table associated with
 2605 ** [database connection] D when another thread
 2606 ** or process has the table locked.
 2607 ** The sqlite3_busy_handler() interface is used to implement
 2608 ** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout].
 2609 **
 2610 ** ^If the busy callback is NULL, then [SQLITE_BUSY]
 2611 ** is returned immediately upon encountering the lock.  ^If the busy callback
 2612 ** is not NULL, then the callback might be invoked with two arguments.
 2613 **
 2614 ** ^The first argument to the busy handler is a copy of the void* pointer which
 2615 ** is the third argument to sqlite3_busy_handler().  ^The second argument to
 2616 ** the busy handler callback is the number of times that the busy handler has
 2617 ** been invoked previously for the same locking event.  ^If the
 2618 ** busy callback returns 0, then no additional attempts are made to
 2619 ** access the database and [SQLITE_BUSY] is returned
 2620 ** to the application.
 2621 ** ^If the callback returns non-zero, then another attempt
 2622 ** is made to access the database and the cycle repeats.
 2623 **
 2624 ** The presence of a busy handler does not guarantee that it will be invoked
 2625 ** when there is lock contention. ^If SQLite determines that invoking the busy
 2626 ** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
 2627 ** to the application instead of invoking the 
 2628 ** busy handler.
 2629 ** Consider a scenario where one process is holding a read lock that
 2630 ** it is trying to promote to a reserved lock and
 2631 ** a second process is holding a reserved lock that it is trying
 2632 ** to promote to an exclusive lock.  The first process cannot proceed
 2633 ** because it is blocked by the second and the second process cannot
 2634 ** proceed because it is blocked by the first.  If both processes
 2635 ** invoke the busy handlers, neither will make any progress.  Therefore,
 2636 ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
 2637 ** will induce the first process to release its read lock and allow
 2638 ** the second process to proceed.
 2639 **
 2640 ** ^The default busy callback is NULL.
 2641 **
 2642 ** ^(There can only be a single busy handler defined for each
 2643 ** [database connection].  Setting a new busy handler clears any
 2644 ** previously set handler.)^  ^Note that calling [sqlite3_busy_timeout()]
 2645 ** or evaluating [PRAGMA busy_timeout=N] will change the
 2646 ** busy handler and thus clear any previously set busy handler.
 2647 **
 2648 ** The busy callback should not take any actions which modify the
 2649 ** database connection that invoked the busy handler.  In other words,
 2650 ** the busy handler is not reentrant.  Any such actions
 2651 ** result in undefined behavior.
 2652 ** 
 2653 ** A busy handler must not close the database connection
 2654 ** or [prepared statement] that invoked the busy handler.
 2655 */
 2656 SQLITE_API int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*);
 2657 
 2658 /*
 2659 ** CAPI3REF: Set A Busy Timeout
 2660 ** METHOD: sqlite3
 2661 **
 2662 ** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
 2663 ** for a specified amount of time when a table is locked.  ^The handler
 2664 ** will sleep multiple times until at least "ms" milliseconds of sleeping
 2665 ** have accumulated.  ^After at least "ms" milliseconds of sleeping,
 2666 ** the handler returns 0 which causes [sqlite3_step()] to return
 2667 ** [SQLITE_BUSY].
 2668 **
 2669 ** ^Calling this routine with an argument less than or equal to zero
 2670 ** turns off all busy handlers.
 2671 **
 2672 ** ^(There can only be a single busy handler for a particular
 2673 ** [database connection] at any given moment.  If another busy handler
 2674 ** was defined  (using [sqlite3_busy_handler()]) prior to calling
 2675 ** this routine, that other busy handler is cleared.)^
 2676 **
 2677 ** See also:  [PRAGMA busy_timeout]
 2678 */
 2679 SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
 2680 
 2681 /*
 2682 ** CAPI3REF: Convenience Routines For Running Queries
 2683 ** METHOD: sqlite3
 2684 **
 2685 ** This is a legacy interface that is preserved for backwards compatibility.
 2686 ** Use of this interface is not recommended.
 2687 **
 2688 ** Definition: A <b>result table</b> is memory data structure created by the
 2689 ** [sqlite3_get_table()] interface.  A result table records the
 2690 ** complete query results from one or more queries.
 2691 **
 2692 ** The table conceptually has a number of rows and columns.  But
 2693 ** these numbers are not part of the result table itself.  These
 2694 ** numbers are obtained separately.  Let N be the number of rows
 2695 ** and M be the number of columns.
 2696 **
 2697 ** A result table is an array of pointers to zero-terminated UTF-8 strings.
 2698 ** There are (N+1)*M elements in the array.  The first M pointers point
 2699 ** to zero-terminated strings that  contain the names of the columns.
 2700 ** The remaining entries all point to query results.  NULL values result
 2701 ** in NULL pointers.  All other values are in their UTF-8 zero-terminated
 2702 ** string representation as returned by [sqlite3_column_text()].
 2703 **
 2704 ** A result table might consist of one or more memory allocations.
 2705 ** It is not safe to pass a result table directly to [sqlite3_free()].
 2706 ** A result table should be deallocated using [sqlite3_free_table()].
 2707 **
 2708 ** ^(As an example of the result table format, suppose a query result
 2709 ** is as follows:
 2710 **
 2711 ** <blockquote><pre>
 2712 **        Name        | Age
 2713 **        -----------------------
 2714 **        Alice       | 43
 2715 **        Bob         | 28
 2716 **        Cindy       | 21
 2717 ** </pre></blockquote>
 2718 **
 2719 ** There are two columns (M==2) and three rows (N==3).  Thus the
 2720 ** result table has 8 entries.  Suppose the result table is stored
 2721 ** in an array named azResult.  Then azResult holds this content:
 2722 **
 2723 ** <blockquote><pre>
 2724 **        azResult&#91;0] = "Name";
 2725 **        azResult&#91;1] = "Age";
 2726 **        azResult&#91;2] = "Alice";
 2727 **        azResult&#91;3] = "43";
 2728 **        azResult&#91;4] = "Bob";
 2729 **        azResult&#91;5] = "28";
 2730 **        azResult&#91;6] = "Cindy";
 2731 **        azResult&#91;7] = "21";
 2732 ** </pre></blockquote>)^
 2733 **
 2734 ** ^The sqlite3_get_table() function evaluates one or more
 2735 ** semicolon-separated SQL statements in the zero-terminated UTF-8
 2736 ** string of its 2nd parameter and returns a result table to the
 2737 ** pointer given in its 3rd parameter.
 2738 **
 2739 ** After the application has finished with the result from sqlite3_get_table(),
 2740 ** it must pass the result table pointer to sqlite3_free_table() in order to
 2741 ** release the memory that was malloced.  Because of the way the
 2742 ** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
 2743 ** function must not try to call [sqlite3_free()] directly.  Only
 2744 ** [sqlite3_free_table()] is able to release the memory properly and safely.
 2745 **
 2746 ** The sqlite3_get_table() interface is implemented as a wrapper around
 2747 ** [sqlite3_exec()].  The sqlite3_get_table() routine does not have access
 2748 ** to any internal data structures of SQLite.  It uses only the public
 2749 ** interface defined here.  As a consequence, errors that occur in the
 2750 ** wrapper layer outside of the internal [sqlite3_exec()] call are not
 2751 ** reflected in subsequent calls to [sqlite3_errcode()] or
 2752 ** [sqlite3_errmsg()].
 2753 */
 2754 SQLITE_API int sqlite3_get_table(
 2755   sqlite3 *db,          /* An open database */
 2756   const char *zSql,     /* SQL to be evaluated */
 2757   char ***pazResult,    /* Results of the query */
 2758   int *pnRow,           /* Number of result rows written here */
 2759   int *pnColumn,        /* Number of result columns written here */
 2760   char **pzErrmsg       /* Error msg written here */
 2761 );
 2762 SQLITE_API void sqlite3_free_table(char **result);
 2763 
 2764 /*
 2765 ** CAPI3REF: Formatted String Printing Functions
 2766 **
 2767 ** These routines are work-alikes of the "printf()" family of functions
 2768 ** from the standard C library.
 2769 ** These routines understand most of the common formatting options from
 2770 ** the standard library printf() 
 2771 ** plus some additional non-standard formats ([%q], [%Q], [%w], and [%z]).
 2772 ** See the [built-in printf()] documentation for details.
 2773 **
 2774 ** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
 2775 ** results into memory obtained from [sqlite3_malloc64()].
 2776 ** The strings returned by these two routines should be
 2777 ** released by [sqlite3_free()].  ^Both routines return a
 2778 ** NULL pointer if [sqlite3_malloc64()] is unable to allocate enough
 2779 ** memory to hold the resulting string.
 2780 **
 2781 ** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
 2782 ** the standard C library.  The result is written into the
 2783 ** buffer supplied as the second parameter whose size is given by
 2784 ** the first parameter. Note that the order of the
 2785 ** first two parameters is reversed from snprintf().)^  This is an
 2786 ** historical accident that cannot be fixed without breaking
 2787 ** backwards compatibility.  ^(Note also that sqlite3_snprintf()
 2788 ** returns a pointer to its buffer instead of the number of
 2789 ** characters actually written into the buffer.)^  We admit that
 2790 ** the number of characters written would be a more useful return
 2791 ** value but we cannot change the implementation of sqlite3_snprintf()
 2792 ** now without breaking compatibility.
 2793 **
 2794 ** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
 2795 ** guarantees that the buffer is always zero-terminated.  ^The first
 2796 ** parameter "n" is the total size of the buffer, including space for
 2797 ** the zero terminator.  So the longest string that can be completely
 2798 ** written will be n-1 characters.
 2799 **
 2800 ** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
 2801 **
 2802 ** See also:  [built-in printf()], [printf() SQL function]
 2803 */
 2804 SQLITE_API char *sqlite3_mprintf(const char*,...);
 2805 SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
 2806 SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
 2807 SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
 2808 
 2809 /*
 2810 ** CAPI3REF: Memory Allocation Subsystem
 2811 **
 2812 ** The SQLite core uses these three routines for all of its own
 2813 ** internal memory allocation needs. "Core" in the previous sentence
 2814 ** does not include operating-system specific [VFS] implementation.  The
 2815 ** Windows VFS uses native malloc() and free() for some operations.
 2816 **
 2817 ** ^The sqlite3_malloc() routine returns a pointer to a block
 2818 ** of memory at least N bytes in length, where N is the parameter.
 2819 ** ^If sqlite3_malloc() is unable to obtain sufficient free
 2820 ** memory, it returns a NULL pointer.  ^If the parameter N to
 2821 ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
 2822 ** a NULL pointer.
 2823 **
 2824 ** ^The sqlite3_malloc64(N) routine works just like
 2825 ** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
 2826 ** of a signed 32-bit integer.
 2827 **
 2828 ** ^Calling sqlite3_free() with a pointer previously returned
 2829 ** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
 2830 ** that it might be reused.  ^The sqlite3_free() routine is
 2831 ** a no-op if is called with a NULL pointer.  Passing a NULL pointer
 2832 ** to sqlite3_free() is harmless.  After being freed, memory
 2833 ** should neither be read nor written.  Even reading previously freed
 2834 ** memory might result in a segmentation fault or other severe error.
 2835 ** Memory corruption, a segmentation fault, or other severe error
 2836 ** might result if sqlite3_free() is called with a non-NULL pointer that
 2837 ** was not obtained from sqlite3_malloc() or sqlite3_realloc().
 2838 **
 2839 ** ^The sqlite3_realloc(X,N) interface attempts to resize a
 2840 ** prior memory allocation X to be at least N bytes.
 2841 ** ^If the X parameter to sqlite3_realloc(X,N)
 2842 ** is a NULL pointer then its behavior is identical to calling
 2843 ** sqlite3_malloc(N).
 2844 ** ^If the N parameter to sqlite3_realloc(X,N) is zero or
 2845 ** negative then the behavior is exactly the same as calling
 2846 ** sqlite3_free(X).
 2847 ** ^sqlite3_realloc(X,N) returns a pointer to a memory allocation
 2848 ** of at least N bytes in size or NULL if insufficient memory is available.
 2849 ** ^If M is the size of the prior allocation, then min(N,M) bytes
 2850 ** of the prior allocation are copied into the beginning of buffer returned
 2851 ** by sqlite3_realloc(X,N) and the prior allocation is freed.
 2852 ** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the
 2853 ** prior allocation is not freed.
 2854 **
 2855 ** ^The sqlite3_realloc64(X,N) interfaces works the same as
 2856 ** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
 2857 ** of a 32-bit signed integer.
 2858 **
 2859 ** ^If X is a memory allocation previously obtained from sqlite3_malloc(),
 2860 ** sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then
 2861 ** sqlite3_msize(X) returns the size of that memory allocation in bytes.
 2862 ** ^The value returned by sqlite3_msize(X) might be larger than the number
 2863 ** of bytes requested when X was allocated.  ^If X is a NULL pointer then
 2864 ** sqlite3_msize(X) returns zero.  If X points to something that is not
 2865 ** the beginning of memory allocation, or if it points to a formerly
 2866 ** valid memory allocation that has now been freed, then the behavior
 2867 ** of sqlite3_msize(X) is undefined and possibly harmful.
 2868 **
 2869 ** ^The memory returned by sqlite3_malloc(), sqlite3_realloc(),
 2870 ** sqlite3_malloc64(), and sqlite3_realloc64()
 2871 ** is always aligned to at least an 8 byte boundary, or to a
 2872 ** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
 2873 ** option is used.
 2874 **
 2875 ** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
 2876 ** must be either NULL or else pointers obtained from a prior
 2877 ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
 2878 ** not yet been released.
 2879 **
 2880 ** The application must not read or write any part of
 2881 ** a block of memory after it has been released using
 2882 ** [sqlite3_free()] or [sqlite3_realloc()].
 2883 */
 2884 SQLITE_API void *sqlite3_malloc(int);
 2885 SQLITE_API void *sqlite3_malloc64(sqlite3_uint64);
 2886 SQLITE_API void *sqlite3_realloc(void*, int);
 2887 SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64);
 2888 SQLITE_API void sqlite3_free(void*);
 2889 SQLITE_API sqlite3_uint64 sqlite3_msize(void*);
 2890 
 2891 /*
 2892 ** CAPI3REF: Memory Allocator Statistics
 2893 **
 2894 ** SQLite provides these two interfaces for reporting on the status
 2895 ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
 2896 ** routines, which form the built-in memory allocation subsystem.
 2897 **
 2898 ** ^The [sqlite3_memory_used()] routine returns the number of bytes
 2899 ** of memory currently outstanding (malloced but not freed).
 2900 ** ^The [sqlite3_memory_highwater()] routine returns the maximum
 2901 ** value of [sqlite3_memory_used()] since the high-water mark
 2902 ** was last reset.  ^The values returned by [sqlite3_memory_used()] and
 2903 ** [sqlite3_memory_highwater()] include any overhead
 2904 ** added by SQLite in its implementation of [sqlite3_malloc()],
 2905 ** but not overhead added by the any underlying system library
 2906 ** routines that [sqlite3_malloc()] may call.
 2907 **
 2908 ** ^The memory high-water mark is reset to the current value of
 2909 ** [sqlite3_memory_used()] if and only if the parameter to
 2910 ** [sqlite3_memory_highwater()] is true.  ^The value returned
 2911 ** by [sqlite3_memory_highwater(1)] is the high-water mark
 2912 ** prior to the reset.
 2913 */
 2914 SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
 2915 SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
 2916 
 2917 /*
 2918 ** CAPI3REF: Pseudo-Random Number Generator
 2919 **
 2920 ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
 2921 ** select random [ROWID | ROWIDs] when inserting new records into a table that
 2922 ** already uses the largest possible [ROWID].  The PRNG is also used for
 2923 ** the built-in random() and randomblob() SQL functions.  This interface allows
 2924 ** applications to access the same PRNG for other purposes.
 2925 **
 2926 ** ^A call to this routine stores N bytes of randomness into buffer P.
 2927 ** ^The P parameter can be a NULL pointer.
 2928 **
 2929 ** ^If this routine has not been previously called or if the previous
 2930 ** call had N less than one or a NULL pointer for P, then the PRNG is
 2931 ** seeded using randomness obtained from the xRandomness method of
 2932 ** the default [sqlite3_vfs] object.
 2933 ** ^If the previous call to this routine had an N of 1 or more and a
 2934 ** non-NULL P then the pseudo-randomness is generated
 2935 ** internally and without recourse to the [sqlite3_vfs] xRandomness
 2936 ** method.
 2937 */
 2938 SQLITE_API void sqlite3_randomness(int N, void *P);
 2939 
 2940 /*
 2941 ** CAPI3REF: Compile-Time Authorization Callbacks
 2942 ** METHOD: sqlite3
 2943 ** KEYWORDS: {authorizer callback}
 2944 **
 2945 ** ^This routine registers an authorizer callback with a particular
 2946 ** [database connection], supplied in the first argument.
 2947 ** ^The authorizer callback is invoked as SQL statements are being compiled
 2948 ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
 2949 ** [sqlite3_prepare_v3()], [sqlite3_prepare16()], [sqlite3_prepare16_v2()],
 2950 ** and [sqlite3_prepare16_v3()].  ^At various
 2951 ** points during the compilation process, as logic is being created
 2952 ** to perform various actions, the authorizer callback is invoked to
 2953 ** see if those actions are allowed.  ^The authorizer callback should
 2954 ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
 2955 ** specific action but allow the SQL statement to continue to be
 2956 ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
 2957 ** rejected with an error.  ^If the authorizer callback returns
 2958 ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
 2959 ** then the [sqlite3_prepare_v2()] or equivalent call that triggered
 2960 ** the authorizer will fail with an error message.
 2961 **
 2962 ** When the callback returns [SQLITE_OK], that means the operation
 2963 ** requested is ok.  ^When the callback returns [SQLITE_DENY], the
 2964 ** [sqlite3_prepare_v2()] or equivalent call that triggered the
 2965 ** authorizer will fail with an error message explaining that
 2966 ** access is denied. 
 2967 **
 2968 ** ^The first parameter to the authorizer callback is a copy of the third
 2969 ** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
 2970 ** to the callback is an integer [SQLITE_COPY | action code] that specifies
 2971 ** the particular action to be authorized. ^The third through sixth parameters
 2972 ** to the callback are either NULL pointers or zero-terminated strings
 2973 ** that contain additional details about the action to be authorized.
 2974 ** Applications must always be prepared to encounter a NULL pointer in any
 2975 ** of the third through the sixth parameters of the authorization callback.
 2976 **
 2977 ** ^If the action code is [SQLITE_READ]
 2978 ** and the callback returns [SQLITE_IGNORE] then the
 2979 ** [prepared statement] statement is constructed to substitute
 2980 ** a NULL value in place of the table column that would have
 2981 ** been read if [SQLITE_OK] had been returned.  The [SQLITE_IGNORE]
 2982 ** return can be used to deny an untrusted user access to individual
 2983 ** columns of a table.
 2984 ** ^When a table is referenced by a [SELECT] but no column values are
 2985 ** extracted from that table (for example in a query like
 2986 ** "SELECT count(*) FROM tab") then the [SQLITE_READ] authorizer callback
 2987 ** is invoked once for that table with a column name that is an empty string.
 2988 ** ^If the action code is [SQLITE_DELETE] and the callback returns
 2989 ** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
 2990 ** [truncate optimization] is disabled and all rows are deleted individually.
 2991 **
 2992 ** An authorizer is used when [sqlite3_prepare | preparing]
 2993 ** SQL statements from an untrusted source, to ensure that the SQL statements
 2994 ** do not try to access data they are not allowed to see, or that they do not
 2995 ** try to execute malicious statements that damage the database.  For
 2996 ** example, an application may allow a user to enter arbitrary
 2997 ** SQL queries for evaluation by a database.  But the application does
 2998 ** not want the user to be able to make arbitrary changes to the
 2999 ** database.  An authorizer could then be put in place while the
 3000 ** user-entered SQL is being [sqlite3_prepare | prepared] that
 3001 ** disallows everything except [SELECT] statements.
 3002 **
 3003 ** Applications that need to process SQL from untrusted sources
 3004 ** might also consider lowering resource limits using [sqlite3_limit()]
 3005 ** and limiting database size using the [max_page_count] [PRAGMA]
 3006 ** in addition to using an authorizer.
 3007 **
 3008 ** ^(Only a single authorizer can be in place on a database connection
 3009 ** at a time.  Each call to sqlite3_set_authorizer overrides the
 3010 ** previous call.)^  ^Disable the authorizer by installing a NULL callback.
 3011 ** The authorizer is disabled by default.
 3012 **
 3013 ** The authorizer callback must not do anything that will modify
 3014 ** the database connection that invoked the authorizer callback.
 3015 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
 3016 ** database connections for the meaning of "modify" in this paragraph.
 3017 **
 3018 ** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
 3019 ** statement might be re-prepared during [sqlite3_step()] due to a 
 3020 ** schema change.  Hence, the application should ensure that the
 3021 ** correct authorizer callback remains in place during the [sqlite3_step()].
 3022 **
 3023 ** ^Note that the authorizer callback is invoked only during
 3024 ** [sqlite3_prepare()] or its variants.  Authorization is not
 3025 ** performed during statement evaluation in [sqlite3_step()], unless
 3026 ** as stated in the previous paragraph, sqlite3_step() invokes
 3027 ** sqlite3_prepare_v2() to reprepare a statement after a schema change.
 3028 */
 3029 SQLITE_API int sqlite3_set_authorizer(
 3030   sqlite3*,
 3031   int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
 3032   void *pUserData
 3033 );
 3034 
 3035 /*
 3036 ** CAPI3REF: Authorizer Return Codes
 3037 **
 3038 ** The [sqlite3_set_authorizer | authorizer callback function] must
 3039 ** return either [SQLITE_OK] or one of these two constants in order
 3040 ** to signal SQLite whether or not the action is permitted.  See the
 3041 ** [sqlite3_set_authorizer | authorizer documentation] for additional
 3042 ** information.
 3043 **
 3044 ** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
 3045 ** returned from the [sqlite3_vtab_on_conflict()] interface.
 3046 */
 3047 #define SQLITE_DENY   1   /* Abort the SQL statement with an error */
 3048 #define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
 3049 
 3050 /*
 3051 ** CAPI3REF: Authorizer Action Codes
 3052 **
 3053 ** The [sqlite3_set_authorizer()] interface registers a callback function
 3054 ** that is invoked to authorize certain SQL statement actions.  The
 3055 ** second parameter to the callback is an integer code that specifies
 3056 ** what action is being authorized.  These are the integer action codes that
 3057 ** the authorizer callback may be passed.
 3058 **
 3059 ** These action code values signify what kind of operation is to be
 3060 ** authorized.  The 3rd and 4th parameters to the authorization
 3061 ** callback function will be parameters or NULL depending on which of these
 3062 ** codes is used as the second parameter.  ^(The 5th parameter to the
 3063 ** authorizer callback is the name of the database ("main", "temp",
 3064 ** etc.) if applicable.)^  ^The 6th parameter to the authorizer callback
 3065 ** is the name of the inner-most trigger or view that is responsible for
 3066 ** the access attempt or NULL if this access attempt is directly from
 3067 ** top-level SQL code.
 3068 */
 3069 /******************************************* 3rd ************ 4th ***********/
 3070 #define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
 3071 #define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
 3072 #define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
 3073 #define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
 3074 #define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
 3075 #define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
 3076 #define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
 3077 #define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
 3078 #define SQLITE_DELETE                9   /* Table Name      NULL            */
 3079 #define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
 3080 #define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
 3081 #define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
 3082 #define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
 3083 #define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
 3084 #define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
 3085 #define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
 3086 #define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
 3087 #define SQLITE_INSERT               18   /* Table Name      NULL            */
 3088 #define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
 3089 #define SQLITE_READ                 20   /* Table Name      Column Name     */
 3090 #define SQLITE_SELECT               21   /* NULL            NULL            */
 3091 #define SQLITE_TRANSACTION          22   /* Operation       NULL            */
 3092 #define SQLITE_UPDATE               23   /* Table Name      Column Name     */
 3093 #define SQLITE_ATTACH               24   /* Filename        NULL            */
 3094 #define SQLITE_DETACH               25   /* Database Name   NULL            */
 3095 #define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */
 3096 #define SQLITE_REINDEX              27   /* Index Name      NULL            */
 3097 #define SQLITE_ANALYZE              28   /* Table Name      NULL            */
 3098 #define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */
 3099 #define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */
 3100 #define SQLITE_FUNCTION             31   /* NULL            Function Name   */
 3101 #define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */
 3102 #define SQLITE_COPY                  0   /* No longer used */
 3103 #define SQLITE_RECURSIVE            33   /* NULL            NULL            */
 3104 
 3105 /*
 3106 ** CAPI3REF: Tracing And Profiling Functions
 3107 ** METHOD: sqlite3
 3108 **
 3109 ** These routines are deprecated. Use the [sqlite3_trace_v2()] interface
 3110 ** instead of the routines described here.
 3111 **
 3112 ** These routines register callback functions that can be used for
 3113 ** tracing and profiling the execution of SQL statements.
 3114 **
 3115 ** ^The callback function registered by sqlite3_trace() is invoked at
 3116 ** various times when an SQL statement is being run by [sqlite3_step()].
 3117 ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
 3118 ** SQL statement text as the statement first begins executing.
 3119 ** ^(Additional sqlite3_trace() callbacks might occur
 3120 ** as each triggered subprogram is entered.  The callbacks for triggers
 3121 ** contain a UTF-8 SQL comment that identifies the trigger.)^
 3122 **
 3123 ** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
 3124 ** the length of [bound parameter] expansion in the output of sqlite3_trace().
 3125 **
 3126 ** ^The callback function registered by sqlite3_profile() is invoked
 3127 ** as each SQL statement finishes.  ^The profile callback contains
 3128 ** the original statement text and an estimate of wall-clock time
 3129 ** of how long that statement took to run.  ^The profile callback
 3130 ** time is in units of nanoseconds, however the current implementation
 3131 ** is only capable of millisecond resolution so the six least significant
 3132 ** digits in the time are meaningless.  Future versions of SQLite
 3133 ** might provide greater resolution on the profiler callback.  Invoking
 3134 ** either [sqlite3_trace()] or [sqlite3_trace_v2()] will cancel the
 3135 ** profile callback.
 3136 */
 3137 SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*,
 3138    void(*xTrace)(void*,const char*), void*);
 3139 SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,
 3140    void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
 3141 
 3142 /*
 3143 ** CAPI3REF: SQL Trace Event Codes
 3144 ** KEYWORDS: SQLITE_TRACE
 3145 **
 3146 ** These constants identify classes of events that can be monitored
 3147 ** using the [sqlite3_trace_v2()] tracing logic.  The M argument
 3148 ** to [sqlite3_trace_v2(D,M,X,P)] is an OR-ed combination of one or more of
 3149 ** the following constants.  ^The first argument to the trace callback
 3150 ** is one of the following constants.
 3151 **
 3152 ** New tracing constants may be added in future releases.
 3153 **
 3154 ** ^A trace callback has four arguments: xCallback(T,C,P,X).
 3155 ** ^The T argument is one of the integer type codes above.
 3156 ** ^The C argument is a copy of the context pointer passed in as the
 3157 ** fourth argument to [sqlite3_trace_v2()].
 3158 ** The P and X arguments are pointers whose meanings depend on T.
 3159 **
 3160 ** <dl>
 3161 ** [[SQLITE_TRACE_STMT]] <dt>SQLITE_TRACE_STMT</dt>
 3162 ** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement
 3163 ** first begins running and possibly at other times during the
 3164 ** execution of the prepared statement, such as at the start of each
 3165 ** trigger subprogram. ^The P argument is a pointer to the
 3166 ** [prepared statement]. ^The X argument is a pointer to a string which
 3167 ** is the unexpanded SQL text of the prepared statement or an SQL comment 
 3168 ** that indicates the invocation of a trigger.  ^The callback can compute
 3169 ** the same text that would have been returned by the legacy [sqlite3_trace()]
 3170 ** interface by using the X argument when X begins with "--" and invoking
 3171 ** [sqlite3_expanded_sql(P)] otherwise.
 3172 **
 3173 ** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt>
 3174 ** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same
 3175 ** information as is provided by the [sqlite3_profile()] callback.
 3176 ** ^The P argument is a pointer to the [prepared statement] and the
 3177 ** X argument points to a 64-bit integer which is the estimated of
 3178 ** the number of nanosecond that the prepared statement took to run.
 3179 ** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
 3180 **
 3181 ** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>
 3182 ** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
 3183 ** statement generates a single row of result.  
 3184 ** ^The P argument is a pointer to the [prepared statement] and the
 3185 ** X argument is unused.
 3186 **
 3187 ** [[SQLITE_TRACE_CLOSE]] <dt>SQLITE_TRACE_CLOSE</dt>
 3188 ** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database
 3189 ** connection closes.
 3190 ** ^The P argument is a pointer to the [database connection] object
 3191 ** and the X argument is unused.
 3192 ** </dl>
 3193 */
 3194 #define SQLITE_TRACE_STMT       0x01
 3195 #define SQLITE_TRACE_PROFILE    0x02
 3196 #define SQLITE_TRACE_ROW        0x04
 3197 #define SQLITE_TRACE_CLOSE      0x08
 3198 
 3199 /*
 3200 ** CAPI3REF: SQL Trace Hook
 3201 ** METHOD: sqlite3
 3202 **
 3203 ** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
 3204 ** function X against [database connection] D, using property mask M
 3205 ** and context pointer P.  ^If the X callback is
 3206 ** NULL or if the M mask is zero, then tracing is disabled.  The
 3207 ** M argument should be the bitwise OR-ed combination of
 3208 ** zero or more [SQLITE_TRACE] constants.
 3209 **
 3210 ** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides 
 3211 ** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2().
 3212 **
 3213 ** ^The X callback is invoked whenever any of the events identified by 
 3214 ** mask M occur.  ^The integer return value from the callback is currently
 3215 ** ignored, though this may change in future releases.  Callback
 3216 ** implementations should return zero to ensure future compatibility.
 3217 **
 3218 ** ^A trace callback is invoked with four arguments: callback(T,C,P,X).
 3219 ** ^The T argument is one of the [SQLITE_TRACE]
 3220 ** constants to indicate why the callback was invoked.
 3221 ** ^The C argument is a copy of the context pointer.
 3222 ** The P and X arguments are pointers whose meanings depend on T.
 3223 **
 3224 ** The sqlite3_trace_v2() interface is intended to replace the legacy
 3225 ** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which
 3226 ** are deprecated.
 3227 */
 3228 SQLITE_API int sqlite3_trace_v2(
 3229   sqlite3*,
 3230   unsigned uMask,
 3231   int(*xCallback)(unsigned,void*,void*,void*),
 3232   void *pCtx
 3233 );
 3234 
 3235 /*
 3236 ** CAPI3REF: Query Progress Callbacks
 3237 ** METHOD: sqlite3
 3238 **
 3239 ** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
 3240 ** function X to be invoked periodically during long running calls to
 3241 ** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for
 3242 ** database connection D.  An example use for this
 3243 ** interface is to keep a GUI updated during a large query.
 3244 **
 3245 ** ^The parameter P is passed through as the only parameter to the 
 3246 ** callback function X.  ^The parameter N is the approximate number of 
 3247 ** [virtual machine instructions] that are evaluated between successive
 3248 ** invocations of the callback X.  ^If N is less than one then the progress
 3249 ** handler is disabled.
 3250 **
 3251 ** ^Only a single progress handler may be defined at one time per
 3252 ** [database connection]; setting a new progress handler cancels the
 3253 ** old one.  ^Setting parameter X to NULL disables the progress handler.
 3254 ** ^The progress handler is also disabled by setting N to a value less
 3255 ** than 1.
 3256 **
 3257 ** ^If the progress callback returns non-zero, the operation is
 3258 ** interrupted.  This feature can be used to implement a
 3259 ** "Cancel" button on a GUI progress dialog box.
 3260 **
 3261 ** The progress handler callback must not do anything that will modify
 3262 ** the database connection that invoked the progress handler.
 3263 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
 3264 ** database connections for the meaning of "modify" in this paragraph.
 3265 **
 3266 */
 3267 SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
 3268 
 3269 /*
 3270 ** CAPI3REF: Opening A New Database Connection
 3271 ** CONSTRUCTOR: sqlite3
 3272 **
 3273 ** ^These routines open an SQLite database file as specified by the 
 3274 ** filename argument. ^The filename argument is interpreted as UTF-8 for
 3275 ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
 3276 ** order for sqlite3_open16(). ^(A [database connection] handle is usually
 3277 ** returned in *ppDb, even if an error occurs.  The only exception is that
 3278 ** if SQLite is unable to allocate memory to hold the [sqlite3] object,
 3279 ** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
 3280 ** object.)^ ^(If the database is opened (and/or created) successfully, then
 3281 ** [SQLITE_OK] is returned.  Otherwise an [error code] is returned.)^ ^The
 3282 ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
 3283 ** an English language description of the error following a failure of any
 3284 ** of the sqlite3_open() routines.
 3285 **
 3286 ** ^The default encoding will be UTF-8 for databases created using
 3287 ** sqlite3_open() or sqlite3_open_v2().  ^The default encoding for databases
 3288 ** created using sqlite3_open16() will be UTF-16 in the native byte order.
 3289 **
 3290 ** Whether or not an error occurs when it is opened, resources
 3291 ** associated with the [database connection] handle should be released by
 3292 ** passing it to [sqlite3_close()] when it is no longer required.
 3293 **
 3294 ** The sqlite3_open_v2() interface works like sqlite3_open()
 3295 ** except that it accepts two additional parameters for additional control
 3296 ** over the new database connection.  ^(The flags parameter to
 3297 ** sqlite3_open_v2() must include, at a minimum, one of the following
 3298 ** three flag combinations:)^
 3299 **
 3300 ** <dl>
 3301 ** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
 3302 ** <dd>The database is opened in read-only mode.  If the database does not
 3303 ** already exist, an error is returned.</dd>)^
 3304 **
 3305 ** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
 3306 ** <dd>The database is opened for reading and writing if possible, or reading
 3307 ** only if the file is write protected by the operating system.  In either
 3308 ** case the database must already exist, otherwise an error is returned.</dd>)^
 3309 **
 3310 ** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
 3311 ** <dd>The database is opened for reading and writing, and is created if
 3312 ** it does not already exist. This is the behavior that is always used for
 3313 ** sqlite3_open() and sqlite3_open16().</dd>)^
 3314 ** </dl>
 3315 **
 3316 ** In addition to the required flags, the following optional flags are
 3317 ** also supported:
 3318 **
 3319 ** <dl>
 3320 ** ^(<dt>[SQLITE_OPEN_URI]</dt>
 3321 ** <dd>The filename can be interpreted as a URI if this flag is set.</dd>)^
 3322 **
 3323 ** ^(<dt>[SQLITE_OPEN_MEMORY]</dt>
 3324 ** <dd>The database will be opened as an in-memory database.  The database
 3325 ** is named by the "filename" argument for the purposes of cache-sharing,
 3326 ** if shared cache mode is enabled, but the "filename" is otherwise ignored.
 3327 ** </dd>)^
 3328 **
 3329 ** ^(<dt>[SQLITE_OPEN_NOMUTEX]</dt>
 3330 ** <dd>The new database connection will use the "multi-thread"
 3331 ** [threading mode].)^  This means that separate threads are allowed
 3332 ** to use SQLite at the same time, as long as each thread is using
 3333 ** a different [database connection].
 3334 **
 3335 ** ^(<dt>[SQLITE_OPEN_FULLMUTEX]</dt>
 3336 ** <dd>The new database connection will use the "serialized"
 3337 ** [threading mode].)^  This means the multiple threads can safely
 3338 ** attempt to use the same database connection at the same time.
 3339 ** (Mutexes will block any actual concurrency, but in this mode
 3340 ** there is no harm in trying.)
 3341 **
 3342 ** ^(<dt>[SQLITE_OPEN_SHAREDCACHE]</dt>
 3343 ** <dd>The database is opened [shared cache] enabled, overriding
 3344 ** the default shared cache setting provided by
 3345 ** [sqlite3_enable_shared_cache()].)^
 3346 **
 3347 ** ^(<dt>[SQLITE_OPEN_PRIVATECACHE]</dt>
 3348 ** <dd>The database is opened [shared cache] disabled, overriding
 3349 ** the default shared cache setting provided by
 3350 ** [sqlite3_enable_shared_cache()].)^
 3351 **
 3352 ** [[OPEN_NOFOLLOW]] ^(<dt>[SQLITE_OPEN_NOFOLLOW]</dt>
 3353 ** <dd>The database filename is not allowed to be a symbolic link</dd>
 3354 ** </dl>)^
 3355 **
 3356 ** If the 3rd parameter to sqlite3_open_v2() is not one of the
 3357 ** required combinations shown above optionally combined with other
 3358 ** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]
 3359 ** then the behavior is undefined.
 3360 **
 3361 ** ^The fourth parameter to sqlite3_open_v2() is the name of the
 3362 ** [sqlite3_vfs] object that defines the operating system interface that
 3363 ** the new database connection should use.  ^If the fourth parameter is
 3364 ** a NULL pointer then the default [sqlite3_vfs] object is used.
 3365 **
 3366 ** ^If the filename is ":memory:", then a private, temporary in-memory database
 3367 ** is created for the connection.  ^This in-memory database will vanish when
 3368 ** the database connection is closed.  Future versions of SQLite might
 3369 ** make use of additional special filenames that begin with the ":" character.
 3370 ** It is recommended that when a database filename actually does begin with
 3371 ** a ":" character you should prefix the filename with a pathname such as
 3372 ** "./" to avoid ambiguity.
 3373 **
 3374 ** ^If the filename is an empty string, then a private, temporary
 3375 ** on-disk database will be created.  ^This private database will be
 3376 ** automatically deleted as soon as the database connection is closed.
 3377 **
 3378 ** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>
 3379 **
 3380 ** ^If [URI filename] interpretation is enabled, and the filename argument
 3381 ** begins with "file:", then the filename is interpreted as a URI. ^URI
 3382 ** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
 3383 ** set in the third argument to sqlite3_open_v2(), or if it has
 3384 ** been enabled globally using the [SQLITE_CONFIG_URI] option with the
 3385 ** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
 3386 ** URI filename interpretation is turned off
 3387 ** by default, but future releases of SQLite might enable URI filename
 3388 ** interpretation by default.  See "[URI filenames]" for additional
 3389 ** information.
 3390 **
 3391 ** URI filenames are parsed according to RFC 3986. ^If the URI contains an
 3392 ** authority, then it must be either an empty string or the string 
 3393 ** "localhost". ^If the authority is not an empty string or "localhost", an 
 3394 ** error is returned to the caller. ^The fragment component of a URI, if 
 3395 ** present, is ignored.
 3396 **
 3397 ** ^SQLite uses the path component of the URI as the name of the disk file
 3398 ** which contains the database. ^If the path begins with a '/' character, 
 3399 ** then it is interpreted as an absolute path. ^If the path does not begin 
 3400 ** with a '/' (meaning that the authority section is omitted from the URI)
 3401 ** then the path is interpreted as a relative path. 
 3402 ** ^(On windows, the first component of an absolute path 
 3403 ** is a drive specification (e.g. "C:").)^
 3404 **
 3405 ** [[core URI query parameters]]
 3406 ** The query component of a URI may contain parameters that are interpreted
 3407 ** either by SQLite itself, or by a [VFS | custom VFS implementation].
 3408 ** SQLite and its built-in [VFSes] interpret the
 3409 ** following query parameters:
 3410 **
 3411 ** <ul>
 3412 **   <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
 3413 **     a VFS object that provides the operating system interface that should
 3414 **     be used to access the database file on disk. ^If this option is set to
 3415 **     an empty string the default VFS object is used. ^Specifying an unknown
 3416 **     VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
 3417 **     present, then the VFS specified by the option takes precedence over
 3418 **     the value passed as the fourth parameter to sqlite3_open_v2().
 3419 **
 3420 **   <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw",
 3421 **     "rwc", or "memory". Attempting to set it to any other value is
 3422 **     an error)^. 
 3423 **     ^If "ro" is specified, then the database is opened for read-only 
 3424 **     access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the 
 3425 **     third argument to sqlite3_open_v2(). ^If the mode option is set to 
 3426 **     "rw", then the database is opened for read-write (but not create) 
 3427 **     access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had 
 3428 **     been set. ^Value "rwc" is equivalent to setting both 
 3429 **     SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE.  ^If the mode option is
 3430 **     set to "memory" then a pure [in-memory database] that never reads
 3431 **     or writes from disk is used. ^It is an error to specify a value for
 3432 **     the mode parameter that is less restrictive than that specified by
 3433 **     the flags passed in the third parameter to sqlite3_open_v2().
 3434 **
 3435 **   <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
 3436 **     "private". ^Setting it to "shared" is equivalent to setting the
 3437 **     SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
 3438 **     sqlite3_open_v2(). ^Setting the cache parameter to "private" is 
 3439 **     equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
 3440 **     ^If sqlite3_open_v2() is used and the "cache" parameter is present in
 3441 **     a URI filename, its value overrides any behavior requested by setting
 3442 **     SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
 3443 **
 3444 **  <li> <b>psow</b>: ^The psow parameter indicates whether or not the
 3445 **     [powersafe overwrite] property does or does not apply to the
 3446 **     storage media on which the database file resides.
 3447 **
 3448 **  <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
 3449 **     which if set disables file locking in rollback journal modes.  This
 3450 **     is useful for accessing a database on a filesystem that does not
 3451 **     support locking.  Caution:  Database corruption might result if two
 3452 **     or more processes write to the same database and any one of those
 3453 **     processes uses nolock=1.
 3454 **
 3455 **  <li> <b>immutable</b>: ^The immutable parameter is a boolean query
 3456 **     parameter that indicates that the database file is stored on
 3457 **     read-only media.  ^When immutable is set, SQLite assumes that the
 3458 **     database file cannot be changed, even by a process with higher
 3459 **     privilege, and so the database is opened read-only and all locking
 3460 **     and change detection is disabled.  Caution: Setting the immutable
 3461 **     property on a database file that does in fact change can result
 3462 **     in incorrect query results and/or [SQLITE_CORRUPT] errors.
 3463 **     See also: [SQLITE_IOCAP_IMMUTABLE].
 3464 **       
 3465 ** </ul>
 3466 **
 3467 ** ^Specifying an unknown parameter in the query component of a URI is not an
 3468 ** error.  Future versions of SQLite might understand additional query
 3469 ** parameters.  See "[query parameters with special meaning to SQLite]" for
 3470 ** additional information.
 3471 **
 3472 ** [[URI filename examples]] <h3>URI filename examples</h3>
 3473 **
 3474 ** <table border="1" align=center cellpadding=5>
 3475 ** <tr><th> URI filenames <th> Results
 3476 ** <tr><td> file:data.db <td> 
 3477 **          Open the file "data.db" in the current directory.
 3478 ** <tr><td> file:/home/fred/data.db<br>
 3479 **          file:///home/fred/data.db <br> 
 3480 **          file://localhost/home/fred/data.db <br> <td> 
 3481 **          Open the database file "/home/fred/data.db".
 3482 ** <tr><td> file://darkstar/home/fred/data.db <td> 
 3483 **          An error. "darkstar" is not a recognized authority.
 3484 ** <tr><td style="white-space:nowrap"> 
 3485 **          file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
 3486 **     <td> Windows only: Open the file "data.db" on fred's desktop on drive
 3487 **          C:. Note that the %20 escaping in this example is not strictly 
 3488 **          necessary - space characters can be used literally
 3489 **          in URI filenames.
 3490 ** <tr><td> file:data.db?mode=ro&cache=private <td> 
 3491 **          Open file "data.db" in the current directory for read-only access.
 3492 **          Regardless of whether or not shared-cache mode is enabled by
 3493 **          default, use a private cache.
 3494 ** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
 3495 **          Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
 3496 **          that uses dot-files in place of posix advisory locking.
 3497 ** <tr><td> file:data.db?mode=readonly <td> 
 3498 **          An error. "readonly" is not a valid option for the "mode" parameter.
 3499 ** </table>
 3500 **
 3501 ** ^URI hexadecimal escape sequences (%HH) are supported within the path and
 3502 ** query components of a URI. A hexadecimal escape sequence consists of a
 3503 ** percent sign - "%" - followed by exactly two hexadecimal digits 
 3504 ** specifying an octet value. ^Before the path or query components of a
 3505 ** URI filename are interpreted, they are encoded using UTF-8 and all 
 3506 ** hexadecimal escape sequences replaced by a single byte containing the
 3507 ** corresponding octet. If this process generates an invalid UTF-8 encoding,
 3508 ** the results are undefined.
 3509 **
 3510 ** <b>Note to Windows users:</b>  The encoding used for the filename argument
 3511 ** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
 3512 ** codepage is currently defined.  Filenames containing international
 3513 ** characters must be converted to UTF-8 prior to passing them into
 3514 ** sqlite3_open() or sqlite3_open_v2().
 3515 **
 3516 ** <b>Note to Windows Runtime users:</b>  The temporary directory must be set
 3517 ** prior to calling sqlite3_open() or sqlite3_open_v2().  Otherwise, various
 3518 ** features that require the use of temporary files may fail.
 3519 **
 3520 ** See also: [sqlite3_temp_directory]
 3521 */
 3522 SQLITE_API int sqlite3_open(
 3523   const char *filename,   /* Database filename (UTF-8) */
 3524   sqlite3 **ppDb          /* OUT: SQLite db handle */
 3525 );
 3526 SQLITE_API int sqlite3_open16(
 3527   const void *filename,   /* Database filename (UTF-16) */
 3528   sqlite3 **ppDb          /* OUT: SQLite db handle */
 3529 );
 3530 SQLITE_API int sqlite3_open_v2(
 3531   const char *filename,   /* Database filename (UTF-8) */
 3532   sqlite3 **ppDb,         /* OUT: SQLite db handle */
 3533   int flags,              /* Flags */
 3534   const char *zVfs        /* Name of VFS module to use */
 3535 );
 3536 
 3537 /*
 3538 ** CAPI3REF: Obtain Values For URI Parameters
 3539 **
 3540 ** These are utility routines, useful to [VFS|custom VFS implementations],
 3541 ** that check if a database file was a URI that contained a specific query 
 3542 ** parameter, and if so obtains the value of that query parameter.
 3543 **
 3544 ** The first parameter to these interfaces (hereafter referred to
 3545 ** as F) must be one of:
 3546 ** <ul>
 3547 ** <li> A database filename pointer created by the SQLite core and
 3548 ** passed into the xOpen() method of a VFS implemention, or
 3549 ** <li> A filename obtained from [sqlite3_db_filename()], or
 3550 ** <li> A new filename constructed using [sqlite3_create_filename()].
 3551 ** </ul>
 3552 ** If the F parameter is not one of the above, then the behavior is
 3553 ** undefined and probably undesirable.  Older versions of SQLite were
 3554 ** more tolerant of invalid F parameters than newer versions.
 3555 **
 3556 ** If F is a suitable filename (as described in the previous paragraph)
 3557 ** and if P is the name of the query parameter, then
 3558 ** sqlite3_uri_parameter(F,P) returns the value of the P
 3559 ** parameter if it exists or a NULL pointer if P does not appear as a 
 3560 ** query parameter on F.  If P is a query parameter of F and it
 3561 ** has no explicit value, then sqlite3_uri_parameter(F,P) returns
 3562 ** a pointer to an empty string.
 3563 **
 3564 ** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
 3565 ** parameter and returns true (1) or false (0) according to the value
 3566 ** of P.  The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the
 3567 ** value of query parameter P is one of "yes", "true", or "on" in any
 3568 ** case or if the value begins with a non-zero number.  The 
 3569 ** sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of
 3570 ** query parameter P is one of "no", "false", or "off" in any case or
 3571 ** if the value begins with a numeric zero.  If P is not a query
 3572 ** parameter on F or if the value of P does not match any of the
 3573 ** above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).
 3574 **
 3575 ** The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
 3576 ** 64-bit signed integer and returns that integer, or D if P does not
 3577 ** exist.  If the value of P is something other than an integer, then
 3578 ** zero is returned.
 3579 **
 3580 ** The sqlite3_uri_key(F,N) returns a pointer to the name (not
 3581 ** the value) of the N-th query parameter for filename F, or a NULL
 3582 ** pointer if N is less than zero or greater than the number of query
 3583 ** parameters minus 1.  The N value is zero-based so N should be 0 to obtain
 3584 ** the name of the first query parameter, 1 for the second parameter, and
 3585 ** so forth.
 3586 ** 
 3587 ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
 3588 ** sqlite3_uri_boolean(F,P,B) returns B.  If F is not a NULL pointer and
 3589 ** is not a database file pathname pointer that the SQLite core passed
 3590 ** into the xOpen VFS method, then the behavior of this routine is undefined
 3591 ** and probably undesirable.
 3592 **
 3593 ** Beginning with SQLite [version 3.31.0] ([dateof:3.31.0]) the input F
 3594 ** parameter can also be the name of a rollback journal file or WAL file
 3595 ** in addition to the main database file.  Prior to version 3.31.0, these
 3596 ** routines would only work if F was the name of the main database file.
 3597 ** When the F parameter is the name of the rollback journal or WAL file,
 3598 ** it has access to all the same query parameters as were found on the
 3599 ** main database file.
 3600 **
 3601 ** See the [URI filename] documentation for additional information.
 3602 */
 3603 SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);
 3604 SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault);
 3605 SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64);
 3606 SQLITE_API const char *sqlite3_uri_key(const char *zFilename, int N);
 3607 
 3608 /*
 3609 ** CAPI3REF:  Translate filenames
 3610 **
 3611 ** These routines are available to [VFS|custom VFS implementations] for
 3612 ** translating filenames between the main database file, the journal file,
 3613 ** and the WAL file.
 3614 **
 3615 ** If F is the name of an sqlite database file, journal file, or WAL file
 3616 ** passed by the SQLite core into the VFS, then sqlite3_filename_database(F)
 3617 ** returns the name of the corresponding database file.
 3618 **
 3619 ** If F is the name of an sqlite database file, journal file, or WAL file
 3620 ** passed by the SQLite core into the VFS, or if F is a database filename
 3621 ** obtained from [sqlite3_db_filename()], then sqlite3_filename_journal(F)
 3622 ** returns the name of the corresponding rollback journal file.
 3623 **
 3624 ** If F is the name of an sqlite database file, journal file, or WAL file
 3625 ** that was passed by the SQLite core into the VFS, or if F is a database
 3626 ** filename obtained from [sqlite3_db_filename()], then
 3627 ** sqlite3_filename_wal(F) returns the name of the corresponding
 3628 ** WAL file.
 3629 **
 3630 ** In all of the above, if F is not the name of a database, journal or WAL
 3631 ** filename passed into the VFS from the SQLite core and F is not the
 3632 ** return value from [sqlite3_db_filename()], then the result is
 3633 ** undefined and is likely a memory access violation.
 3634 */
 3635 SQLITE_API const char *sqlite3_filename_database(const char*);
 3636 SQLITE_API const char *sqlite3_filename_journal(const char*);
 3637 SQLITE_API const char *sqlite3_filename_wal(const char*);
 3638 
 3639 /*
 3640 ** CAPI3REF:  Database File Corresponding To A Journal
 3641 **
 3642 ** ^If X is the name of a rollback or WAL-mode journal file that is
 3643 ** passed into the xOpen method of [sqlite3_vfs], then 
 3644 ** sqlite3_database_file_object(X) returns a pointer to the [sqlite3_file]
 3645 ** object that represents the main database file.
 3646 **
 3647 ** This routine is intended for use in custom [VFS] implementations
 3648 ** only.  It is not a general-purpose interface.
 3649 ** The argument sqlite3_file_object(X) must be a filename pointer that
 3650 ** has been passed into [sqlite3_vfs].xOpen method where the 
 3651 ** flags parameter to xOpen contains one of the bits
 3652 ** [SQLITE_OPEN_MAIN_JOURNAL] or [SQLITE_OPEN_WAL].  Any other use
 3653 ** of this routine results in undefined and probably undesirable
 3654 ** behavior.
 3655 */
 3656 SQLITE_API sqlite3_file *sqlite3_database_file_object(const char*);
 3657 
 3658 /*
 3659 ** CAPI3REF: Create and Destroy VFS Filenames
 3660 **
 3661 ** These interfces are provided for use by [VFS shim] implementations and
 3662 ** are not useful outside of that context.
 3663 **
 3664 ** The sqlite3_create_filename(D,J,W,N,P) allocates memory to hold a version of
 3665 ** database filename D with corresponding journal file J and WAL file W and
 3666 ** with N URI parameters key/values pairs in the array P.  The result from
 3667 ** sqlite3_create_filename(D,J,W,N,P) is a pointer to a database filename that
 3668 ** is safe to pass to routines like:
 3669 ** <ul>
 3670 ** <li> [sqlite3_uri_parameter()],
 3671 ** <li> [sqlite3_uri_boolean()],
 3672 ** <li> [sqlite3_uri_int64()],
 3673 ** <li> [sqlite3_uri_key()], 
 3674 ** <li> [sqlite3_filename_database()],
 3675 ** <li> [sqlite3_filename_journal()], or
 3676 ** <li> [sqlite3_filename_wal()].
 3677 ** </ul>
 3678 ** If a memory allocation error occurs, sqlite3_create_filename() might
 3679 ** return a NULL pointer.  The memory obtained from sqlite3_create_filename(X)
 3680 ** must be released by a corresponding call to sqlite3_free_filename(Y).
 3681 **
 3682 ** The P parameter in sqlite3_create_filename(D,J,W,N,P) should be an array
 3683 ** of 2*N pointers to strings.  Each pair of pointers in this array corresponds
 3684 ** to a key and value for a query parameter.  The P parameter may be a NULL
 3685 ** pointer if N is zero.  None of the 2*N pointers in the P array may be
 3686 ** NULL pointers and key pointers should not be empty strings.
 3687 ** None of the D, J, or W parameters to sqlite3_create_filename(D,J,W,N,P) may
 3688 ** be NULL pointers, though they can be empty strings.
 3689 **
 3690 ** The sqlite3_free_filename(Y) routine releases a memory allocation
 3691 ** previously obtained from sqlite3_create_filename().  Invoking
 3692 ** sqlite3_free_filename(Y) where Y is a NULL pointer is a harmless no-op.
 3693 **
 3694 ** If the Y parameter to sqlite3_free_filename(Y) is anything other
 3695 ** than a NULL pointer or a pointer previously acquired from
 3696 ** sqlite3_create_filename(), then bad things such as heap
 3697 ** corruption or segfaults may occur. The value Y should be 
 3698 ** used again after sqlite3_free_filename(Y) has been called.  This means
 3699 ** that if the [sqlite3_vfs.xOpen()] method of a VFS has been called using Y,
 3700 ** then the corresponding [sqlite3_module.xClose() method should also be
 3701 ** invoked prior to calling sqlite3_free_filename(Y).
 3702 */
 3703 SQLITE_API char *sqlite3_create_filename(
 3704   const char *zDatabase,
 3705   const char *zJournal,
 3706   const char *zWal,
 3707   int nParam,
 3708   const char **azParam
 3709 );
 3710 SQLITE_API void sqlite3_free_filename(char*);
 3711 
 3712 /*
 3713 ** CAPI3REF: Error Codes And Messages
 3714 ** METHOD: sqlite3
 3715 **
 3716 ** ^If the most recent sqlite3_* API call associated with 
 3717 ** [database connection] D failed, then the sqlite3_errcode(D) interface
 3718 ** returns the numeric [result code] or [extended result code] for that
 3719 ** API call.
 3720 ** ^The sqlite3_extended_errcode()
 3721 ** interface is the same except that it always returns the 
 3722 ** [extended result code] even when extended result codes are
 3723 ** disabled.
 3724 **
 3725 ** The values returned by sqlite3_errcode() and/or
 3726 ** sqlite3_extended_errcode() might change with each API call.
 3727 ** Except, there are some interfaces that are guaranteed to never
 3728 ** change the value of the error code.  The error-code preserving
 3729 ** interfaces are:
 3730 **
 3731 ** <ul>
 3732 ** <li> sqlite3_errcode()
 3733 ** <li> sqlite3_extended_errcode()
 3734 ** <li> sqlite3_errmsg()
 3735 ** <li> sqlite3_errmsg16()
 3736 ** </ul>
 3737 **
 3738 ** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
 3739 ** text that describes the error, as either UTF-8 or UTF-16 respectively.
 3740 ** ^(Memory to hold the error message string is managed internally.
 3741 ** The application does not need to worry about freeing the result.
 3742 ** However, the error string might be overwritten or deallocated by
 3743 ** subsequent calls to other SQLite interface functions.)^
 3744 **
 3745 ** ^The sqlite3_errstr() interface returns the English-language text
 3746 ** that describes the [result code], as UTF-8.
 3747 ** ^(Memory to hold the error message string is managed internally
 3748 ** and must not be freed by the application)^.
 3749 **
 3750 ** When the serialized [threading mode] is in use, it might be the
 3751 ** case that a second error occurs on a separate thread in between
 3752 ** the time of the first error and the call to these interfaces.
 3753 ** When that happens, the second error will be reported since these
 3754 ** interfaces always report the most recent result.  To avoid
 3755 ** this, each thread can obtain exclusive use of the [database connection] D
 3756 ** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
 3757 ** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
 3758 ** all calls to the interfaces listed here are completed.
 3759 **
 3760 ** If an interface fails with SQLITE_MISUSE, that means the interface
 3761 ** was invoked incorrectly by the application.  In that case, the
 3762 ** error code and message may or may not be set.
 3763 */
 3764 SQLITE_API int sqlite3_errcode(sqlite3 *db);
 3765 SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
 3766 SQLITE_API const char *sqlite3_errmsg(sqlite3*);
 3767 SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
 3768 SQLITE_API const char *sqlite3_errstr(int);
 3769 
 3770 /*
 3771 ** CAPI3REF: Prepared Statement Object
 3772 ** KEYWORDS: {prepared statement} {prepared statements}
 3773 **
 3774 ** An instance of this object represents a single SQL statement that
 3775 ** has been compiled into binary form and is ready to be evaluated.
 3776 **
 3777 ** Think of each SQL statement as a separate computer program.  The
 3778 ** original SQL text is source code.  A prepared statement object 
 3779 ** is the compiled object code.  All SQL must be converted into a
 3780 ** prepared statement before it can be run.
 3781 **
 3782 ** The life-cycle of a prepared statement object usually goes like this:
 3783 **
 3784 ** <ol>
 3785 ** <li> Create the prepared statement object using [sqlite3_prepare_v2()].
 3786 ** <li> Bind values to [parameters] using the sqlite3_bind_*()
 3787 **      interfaces.
 3788 ** <li> Run the SQL by calling [sqlite3_step()] one or more times.
 3789 ** <li> Reset the prepared statement using [sqlite3_reset()] then go back
 3790 **      to step 2.  Do this zero or more times.
 3791 ** <li> Destroy the object using [sqlite3_finalize()].
 3792 ** </ol>
 3793 */
 3794 typedef struct sqlite3_stmt sqlite3_stmt;
 3795 
 3796 /*
 3797 ** CAPI3REF: Run-time Limits
 3798 ** METHOD: sqlite3
 3799 **
 3800 ** ^(This interface allows the size of various constructs to be limited
 3801 ** on a connection by connection basis.  The first parameter is the
 3802 ** [database connection] whose limit is to be set or queried.  The
 3803 ** second parameter is one of the [limit categories] that define a
 3804 ** class of constructs to be size limited.  The third parameter is the
 3805 ** new limit for that construct.)^
 3806 **
 3807 ** ^If the new limit is a negative number, the limit is unchanged.
 3808 ** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a 
 3809 ** [limits | hard upper bound]
 3810 ** set at compile-time by a C preprocessor macro called
 3811 ** [limits | SQLITE_MAX_<i>NAME</i>].
 3812 ** (The "_LIMIT_" in the name is changed to "_MAX_".))^
 3813 ** ^Attempts to increase a limit above its hard upper bound are
 3814 ** silently truncated to the hard upper bound.
 3815 **
 3816 ** ^Regardless of whether or not the limit was changed, the 
 3817 ** [sqlite3_limit()] interface returns the prior value of the limit.
 3818 ** ^Hence, to find the current value of a limit without changing it,
 3819 ** simply invoke this interface with the third parameter set to -1.
 3820 **
 3821 ** Run-time limits are intended for use in applications that manage
 3822 ** both their own internal database and also databases that are controlled
 3823 ** by untrusted external sources.  An example application might be a
 3824 ** web browser that has its own databases for storing history and
 3825 ** separate databases controlled by JavaScript applications downloaded
 3826 ** off the Internet.  The internal databases can be given the
 3827 ** large, default limits.  Databases managed by external sources can
 3828 ** be given much smaller limits designed to prevent a denial of service
 3829 ** attack.  Developers might also want to use the [sqlite3_set_authorizer()]
 3830 ** interface to further control untrusted SQL.  The size of the database
 3831 ** created by an untrusted script can be contained using the
 3832 ** [max_page_count] [PRAGMA].
 3833 **
 3834 ** New run-time limit categories may be added in future releases.
 3835 */
 3836 SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
 3837 
 3838 /*
 3839 ** CAPI3REF: Run-Time Limit Categories
 3840 ** KEYWORDS: {limit category} {*limit categories}
 3841 **
 3842 ** These constants define various performance limits
 3843 ** that can be lowered at run-time using [sqlite3_limit()].
 3844 ** The synopsis of the meanings of the various limits is shown below.
 3845 ** Additional information is available at [limits | Limits in SQLite].
 3846 **
 3847 ** <dl>
 3848 ** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt>
 3849 ** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^
 3850 **
 3851 ** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
 3852 ** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
 3853 **
 3854 ** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt>
 3855 ** <dd>The maximum number of columns in a table definition or in the
 3856 ** result set of a [SELECT] or the maximum number of columns in an index
 3857 ** or in an ORDER BY or GROUP BY clause.</dd>)^
 3858 **
 3859 ** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
 3860 ** <dd>The maximum depth of the parse tree on any expression.</dd>)^
 3861 **
 3862 ** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
 3863 ** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
 3864 **
 3865 ** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
 3866 ** <dd>The maximum number of instructions in a virtual machine program
 3867 ** used to implement an SQL statement.  If [sqlite3_prepare_v2()] or
 3868 ** the equivalent tries to allocate space for more than this many opcodes
 3869 ** in a single prepared statement, an SQLITE_NOMEM error is returned.</dd>)^
 3870 **
 3871 ** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
 3872 ** <dd>The maximum number of arguments on a function.</dd>)^
 3873 **
 3874 ** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
 3875 ** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
 3876 **
 3877 ** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]
 3878 ** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
 3879 ** <dd>The maximum length of the pattern argument to the [LIKE] or
 3880 ** [GLOB] operators.</dd>)^
 3881 **
 3882 ** [[SQLITE_LIMIT_VARIABLE_NUMBER]]
 3883 ** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
 3884 ** <dd>The maximum index number of any [parameter] in an SQL statement.)^
 3885 **
 3886 ** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
 3887 ** <dd>The maximum depth of recursion for triggers.</dd>)^
 3888 **
 3889 ** [[SQLITE_LIMIT_WORKER_THREADS]] ^(<dt>SQLITE_LIMIT_WORKER_THREADS</dt>
 3890 ** <dd>The maximum number of auxiliary worker threads that a single
 3891 ** [prepared statement] may start.</dd>)^
 3892 ** </dl>
 3893 */
 3894 #define SQLITE_LIMIT_LENGTH                    0
 3895 #define SQLITE_LIMIT_SQL_LENGTH                1
 3896 #define SQLITE_LIMIT_COLUMN                    2
 3897 #define SQLITE_LIMIT_EXPR_DEPTH                3
 3898 #define SQLITE_LIMIT_COMPOUND_SELECT           4
 3899 #define SQLITE_LIMIT_VDBE_OP                   5
 3900 #define SQLITE_LIMIT_FUNCTION_ARG              6
 3901 #define SQLITE_LIMIT_ATTACHED                  7
 3902 #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH       8
 3903 #define SQLITE_LIMIT_VARIABLE_NUMBER           9
 3904 #define SQLITE_LIMIT_TRIGGER_DEPTH            10
 3905 #define SQLITE_LIMIT_WORKER_THREADS           11
 3906 
 3907 /*
 3908 ** CAPI3REF: Prepare Flags
 3909 **
 3910 ** These constants define various flags that can be passed into
 3911 ** "prepFlags" parameter of the [sqlite3_prepare_v3()] and
 3912 ** [sqlite3_prepare16_v3()] interfaces.
 3913 **
 3914 ** New flags may be added in future releases of SQLite.
 3915 **
 3916 ** <dl>
 3917 ** [[SQLITE_PREPARE_PERSISTENT]] ^(<dt>SQLITE_PREPARE_PERSISTENT</dt>
 3918 ** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
 3919 ** that the prepared statement will be retained for a long time and
 3920 ** probably reused many times.)^ ^Without this flag, [sqlite3_prepare_v3()]
 3921 ** and [sqlite3_prepare16_v3()] assume that the prepared statement will 
 3922 ** be used just once or at most a few times and then destroyed using
 3923 ** [sqlite3_finalize()] relatively soon. The current implementation acts
 3924 ** on this hint by avoiding the use of [lookaside memory] so as not to
 3925 ** deplete the limited store of lookaside memory. Future versions of
 3926 ** SQLite may act on this hint differently.
 3927 **
 3928 ** [[SQLITE_PREPARE_NORMALIZE]] <dt>SQLITE_PREPARE_NORMALIZE</dt>
 3929 ** <dd>The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used
 3930 ** to be required for any prepared statement that wanted to use the
 3931 ** [sqlite3_normalized_sql()] interface.  However, the
 3932 ** [sqlite3_normalized_sql()] interface is now available to all
 3933 ** prepared statements, regardless of whether or not they use this
 3934 ** flag.
 3935 **
 3936 ** [[SQLITE_PREPARE_NO_VTAB]] <dt>SQLITE_PREPARE_NO_VTAB</dt>
 3937 ** <dd>The SQLITE_PREPARE_NO_VTAB flag causes the SQL compiler
 3938 ** to return an error (error code SQLITE_ERROR) if the statement uses
 3939 ** any virtual tables.
 3940 ** </dl>
 3941 */
 3942 #define SQLITE_PREPARE_PERSISTENT              0x01
 3943 #define SQLITE_PREPARE_NORMALIZE               0x02
 3944 #define SQLITE_PREPARE_NO_VTAB                 0x04
 3945 
 3946 /*
 3947 ** CAPI3REF: Compiling An SQL Statement
 3948 ** KEYWORDS: {SQL statement compiler}
 3949 ** METHOD: sqlite3
 3950 ** CONSTRUCTOR: sqlite3_stmt
 3951 **
 3952 ** To execute an SQL statement, it must first be compiled into a byte-code
 3953 ** program using one of these routines.  Or, in other words, these routines
 3954 ** are constructors for the [prepared statement] object.
 3955 **
 3956 ** The preferred routine to use is [sqlite3_prepare_v2()].  The
 3957 ** [sqlite3_prepare()] interface is legacy and should be avoided.
 3958 ** [sqlite3_prepare_v3()] has an extra "prepFlags" option that is used
 3959 ** for special purposes.
 3960 **
 3961 ** The use of the UTF-8 interfaces is preferred, as SQLite currently
 3962 ** does all parsing using UTF-8.  The UTF-16 interfaces are provided
 3963 ** as a convenience.  The UTF-16 interfaces work by converting the
 3964 ** input text into UTF-8, then invoking the corresponding UTF-8 interface.
 3965 **
 3966 ** The first argument, "db", is a [database connection] obtained from a
 3967 ** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
 3968 ** [sqlite3_open16()].  The database connection must not have been closed.
 3969 **
 3970 ** The second argument, "zSql", is the statement to be compiled, encoded
 3971 ** as either UTF-8 or UTF-16.  The sqlite3_prepare(), sqlite3_prepare_v2(),
 3972 ** and sqlite3_prepare_v3()
 3973 ** interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),
 3974 ** and sqlite3_prepare16_v3() use UTF-16.
 3975 **
 3976 ** ^If the nByte argument is negative, then zSql is read up to the
 3977 ** first zero terminator. ^If nByte is positive, then it is the
 3978 ** number of bytes read from zSql.  ^If nByte is zero, then no prepared
 3979 ** statement is generated.
 3980 ** If the caller knows that the supplied string is nul-terminated, then
 3981 ** there is a small performance advantage to passing an nByte parameter that
 3982 ** is the number of bytes in the input string <i>including</i>
 3983 ** the nul-terminator.
 3984 **
 3985 ** ^If pzTail is not NULL then *pzTail is made to point to the first byte
 3986 ** past the end of the first SQL statement in zSql.  These routines only
 3987 ** compile the first statement in zSql, so *pzTail is left pointing to
 3988 ** what remains uncompiled.
 3989 **
 3990 ** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
 3991 ** executed using [sqlite3_step()].  ^If there is an error, *ppStmt is set
 3992 ** to NULL.  ^If the input text contains no SQL (if the input is an empty
 3993 ** string or a comment) then *ppStmt is set to NULL.
 3994 ** The calling procedure is responsible for deleting the compiled
 3995 ** SQL statement using [sqlite3_finalize()] after it has finished with it.
 3996 ** ppStmt may not be NULL.
 3997 **
 3998 ** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
 3999 ** otherwise an [error code] is returned.
 4000 **
 4001 ** The sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(),
 4002 ** and sqlite3_prepare16_v3() interfaces are recommended for all new programs.
 4003 ** The older interfaces (sqlite3_prepare() and sqlite3_prepare16())
 4004 ** are retained for backwards compatibility, but their use is discouraged.
 4005 ** ^In the "vX" interfaces, the prepared statement
 4006 ** that is returned (the [sqlite3_stmt] object) contains a copy of the
 4007 ** original SQL text. This causes the [sqlite3_step()] interface to
 4008 ** behave differently in three ways:
 4009 **
 4010 ** <ol>
 4011 ** <li>
 4012 ** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
 4013 ** always used to do, [sqlite3_step()] will automatically recompile the SQL
 4014 ** statement and try to run it again. As many as [SQLITE_MAX_SCHEMA_RETRY]
 4015 ** retries will occur before sqlite3_step() gives up and returns an error.
 4016 ** </li>
 4017 **
 4018 ** <li>
 4019 ** ^When an error occurs, [sqlite3_step()] will return one of the detailed
 4020 ** [error codes] or [extended error codes].  ^The legacy behavior was that
 4021 ** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
 4022 ** and the application would have to make a second call to [sqlite3_reset()]
 4023 ** in order to find the underlying cause of the problem. With the "v2" prepare
 4024 ** interfaces, the underlying reason for the error is returned immediately.
 4025 ** </li>
 4026 **
 4027 ** <li>
 4028 ** ^If the specific value bound to a [parameter | host parameter] in the 
 4029 ** WHERE clause might influence the choice of query plan for a statement,
 4030 ** then the statement will be automatically recompiled, as if there had been 
 4031 ** a schema change, on the first [sqlite3_step()] call following any change
 4032 ** to the [sqlite3_bind_text | bindings] of that [parameter]. 
 4033 ** ^The specific value of a WHERE-clause [parameter] might influence the 
 4034 ** choice of query plan if the parameter is the left-hand side of a [LIKE]
 4035 ** or [GLOB] operator or if the parameter is compared to an indexed column
 4036 ** and the [SQLITE_ENABLE_STAT4] compile-time option is enabled.
 4037 ** </li>
 4038 ** </ol>
 4039 **
 4040 ** <p>^sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having
 4041 ** the extra prepFlags parameter, which is a bit array consisting of zero or
 4042 ** more of the [SQLITE_PREPARE_PERSISTENT|SQLITE_PREPARE_*] flags.  ^The
 4043 ** sqlite3_prepare_v2() interface works exactly the same as
 4044 ** sqlite3_prepare_v3() with a zero prepFlags parameter.
 4045 */
 4046 SQLITE_API int sqlite3_prepare(
 4047   sqlite3 *db,            /* Database handle */
 4048   const char *zSql,       /* SQL statement, UTF-8 encoded */
 4049   int nByte,              /* Maximum length of zSql in bytes. */
 4050   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
 4051   const char **pzTail     /* OUT: Pointer to unused portion of zSql */
 4052 );
 4053 SQLITE_API int sqlite3_prepare_v2(
 4054   sqlite3 *db,            /* Database handle */
 4055   const char *zSql,       /* SQL statement, UTF-8 encoded */
 4056   int nByte,              /* Maximum length of zSql in bytes. */
 4057   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
 4058   const char **pzTail     /* OUT: Pointer to unused portion of zSql */
 4059 );
 4060 SQLITE_API int sqlite3_prepare_v3(
 4061   sqlite3 *db,            /* Database handle */
 4062   const char *zSql,       /* SQL statement, UTF-8 encoded */
 4063   int nByte,              /* Maximum length of zSql in bytes. */
 4064   unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
 4065   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
 4066   const char **pzTail     /* OUT: Pointer to unused portion of zSql */
 4067 );
 4068 SQLITE_API int sqlite3_prepare16(
 4069   sqlite3 *db,            /* Database handle */
 4070   const void *zSql,       /* SQL statement, UTF-16 encoded */
 4071   int nByte,              /* Maximum length of zSql in bytes. */
 4072   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
 4073   const void **pzTail     /* OUT: Pointer to unused portion of zSql */
 4074 );
 4075 SQLITE_API int sqlite3_prepare16_v2(
 4076   sqlite3 *db,            /* Database handle */
 4077   const void *zSql,       /* SQL statement, UTF-16 encoded */
 4078   int nByte,              /* Maximum length of zSql in bytes. */
 4079   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
 4080   const void **pzTail     /* OUT: Pointer to unused portion of zSql */
 4081 );
 4082 SQLITE_API int sqlite3_prepare16_v3(
 4083   sqlite3 *db,            /* Database handle */
 4084   const void *zSql,       /* SQL statement, UTF-16 encoded */
 4085   int nByte,              /* Maximum length of zSql in bytes. */
 4086   unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
 4087   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
 4088   const void **pzTail     /* OUT: Pointer to unused portion of zSql */
 4089 );
 4090 
 4091 /*
 4092 ** CAPI3REF: Retrieving Statement SQL
 4093 ** METHOD: sqlite3_stmt
 4094 **
 4095 ** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
 4096 ** SQL text used to create [prepared statement] P if P was
 4097 ** created by [sqlite3_prepare_v2()], [sqlite3_prepare_v3()],
 4098 ** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
 4099 ** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
 4100 ** string containing the SQL text of prepared statement P with
 4101 ** [bound parameters] expanded.
 4102 ** ^The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8
 4103 ** string containing the normalized SQL text of prepared statement P.  The
 4104 ** semantics used to normalize a SQL statement are unspecified and subject
 4105 ** to change.  At a minimum, literal values will be replaced with suitable
 4106 ** placeholders.
 4107 **
 4108 ** ^(For example, if a prepared statement is created using the SQL
 4109 ** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
 4110 ** and parameter :xyz is unbound, then sqlite3_sql() will return
 4111 ** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql()
 4112 ** will return "SELECT 2345,NULL".)^
 4113 **
 4114 ** ^The sqlite3_expanded_sql() interface returns NULL if insufficient memory
 4115 ** is available to hold the result, or if the result would exceed the
 4116 ** the maximum string length determined by the [SQLITE_LIMIT_LENGTH].
 4117 **
 4118 ** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of
 4119 ** bound parameter expansions.  ^The [SQLITE_OMIT_TRACE] compile-time
 4120 ** option causes sqlite3_expanded_sql() to always return NULL.
 4121 **
 4122 ** ^The strings returned by sqlite3_sql(P) and sqlite3_normalized_sql(P)
 4123 ** are managed by SQLite and are automatically freed when the prepared
 4124 ** statement is finalized.
 4125 ** ^The string returned by sqlite3_expanded_sql(P), on the other hand,
 4126 ** is obtained from [sqlite3_malloc()] and must be free by the application
 4127 ** by passing it to [sqlite3_free()].
 4128 */
 4129 SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
 4130 SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt);
 4131 SQLITE_API const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt);
 4132 
 4133 /*
 4134 ** CAPI3REF: Determine If An SQL Statement Writes The Database
 4135 ** METHOD: sqlite3_stmt
 4136 **
 4137 ** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
 4138 ** and only if the [prepared statement] X makes no direct changes to
 4139 ** the content of the database file.
 4140 **
 4141 ** Note that [application-defined SQL functions] or
 4142 ** [virtual tables] might change the database indirectly as a side effect.  
 4143 ** ^(For example, if an application defines a function "eval()" that 
 4144 ** calls [sqlite3_exec()], then the following SQL statement would
 4145 ** change the database file through side-effects:
 4146 **
 4147 ** <blockquote><pre>
 4148 **    SELECT eval('DELETE FROM t1') FROM t2;
 4149 ** </pre></blockquote>
 4150 **
 4151 ** But because the [SELECT] statement does not change the database file
 4152 ** directly, sqlite3_stmt_readonly() would still return true.)^
 4153 **
 4154 ** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],
 4155 ** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
 4156 ** since the statements themselves do not actually modify the database but
 4157 ** rather they control the timing of when other statements modify the 
 4158 ** database.  ^The [ATTACH] and [DETACH] statements also cause
 4159 ** sqlite3_stmt_readonly() to return true since, while those statements
 4160 ** change the configuration of a database connection, they do not make 
 4161 ** changes to the content of the database files on disk.
 4162 ** ^The sqlite3_stmt_readonly() interface returns true for [BEGIN] since
 4163 ** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and
 4164 ** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so
 4165 ** sqlite3_stmt_readonly() returns false for those commands.
 4166 */
 4167 SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
 4168 
 4169 /*
 4170 ** CAPI3REF: Query The EXPLAIN Setting For A Prepared Statement
 4171 ** METHOD: sqlite3_stmt
 4172 **
 4173 ** ^The sqlite3_stmt_isexplain(S) interface returns 1 if the
 4174 ** prepared statement S is an EXPLAIN statement, or 2 if the
 4175 ** statement S is an EXPLAIN QUERY PLAN.
 4176 ** ^The sqlite3_stmt_isexplain(S) interface returns 0 if S is
 4177 ** an ordinary statement or a NULL pointer.
 4178 */
 4179 SQLITE_API int sqlite3_stmt_isexplain(sqlite3_stmt *pStmt);
 4180 
 4181 /*
 4182 ** CAPI3REF: Determine If A Prepared Statement Has Been Reset
 4183 ** METHOD: sqlite3_stmt
 4184 **
 4185 ** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
 4186 ** [prepared statement] S has been stepped at least once using 
 4187 ** [sqlite3_step(S)] but has neither run to completion (returned
 4188 ** [SQLITE_DONE] from [sqlite3_step(S)]) nor
 4189 ** been reset using [sqlite3_reset(S)].  ^The sqlite3_stmt_busy(S)
 4190 ** interface returns false if S is a NULL pointer.  If S is not a 
 4191 ** NULL pointer and is not a pointer to a valid [prepared statement]
 4192 ** object, then the behavior is undefined and probably undesirable.
 4193 **
 4194 ** This interface can be used in combination [sqlite3_next_stmt()]
 4195 ** to locate all prepared statements associated with a database 
 4196 ** connection that are in need of being reset.  This can be used,
 4197 ** for example, in diagnostic routines to search for prepared 
 4198 ** statements that are holding a transaction open.
 4199 */
 4200 SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
 4201 
 4202 /*
 4203 ** CAPI3REF: Dynamically Typed Value Object
 4204 ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
 4205 **
 4206 ** SQLite uses the sqlite3_value object to represent all values
 4207 ** that can be stored in a database table. SQLite uses dynamic typing
 4208 ** for the values it stores.  ^Values stored in sqlite3_value objects
 4209 ** can be integers, floating point values, strings, BLOBs, or NULL.
 4210 **
 4211 ** An sqlite3_value object may be either "protected" or "unprotected".
 4212 ** Some interfaces require a protected sqlite3_value.  Other interfaces
 4213 ** will accept either a protected or an unprotected sqlite3_value.
 4214 ** Every interface that accepts sqlite3_value arguments specifies
 4215 ** whether or not it requires a protected sqlite3_value.  The
 4216 ** [sqlite3_value_dup()] interface can be used to construct a new 
 4217 ** protected sqlite3_value from an unprotected sqlite3_value.
 4218 **
 4219 ** The terms "protected" and "unprotected" refer to whether or not
 4220 ** a mutex is held.  An internal mutex is held for a protected
 4221 ** sqlite3_value object but no mutex is held for an unprotected
 4222 ** sqlite3_value object.  If SQLite is compiled to be single-threaded
 4223 ** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
 4224 ** or if SQLite is run in one of reduced mutex modes 
 4225 ** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
 4226 ** then there is no distinction between protected and unprotected
 4227 ** sqlite3_value objects and they can be used interchangeably.  However,
 4228 ** for maximum code portability it is recommended that applications
 4229 ** still make the distinction between protected and unprotected
 4230 ** sqlite3_value objects even when not strictly required.
 4231 **
 4232 ** ^The sqlite3_value objects that are passed as parameters into the
 4233 ** implementation of [application-defined SQL functions] are protected.
 4234 ** ^The sqlite3_value object returned by
 4235 ** [sqlite3_column_value()] is unprotected.
 4236 ** Unprotected sqlite3_value objects may only be used as arguments
 4237 ** to [sqlite3_result_value()], [sqlite3_bind_value()], and
 4238 ** [sqlite3_value_dup()].
 4239 ** The [sqlite3_value_blob | sqlite3_value_type()] family of
 4240 ** interfaces require protected sqlite3_value objects.
 4241 */
 4242 typedef struct sqlite3_value sqlite3_value;
 4243 
 4244 /*
 4245 ** CAPI3REF: SQL Function Context Object
 4246 **
 4247 ** The context in which an SQL function executes is stored in an
 4248 ** sqlite3_context object.  ^A pointer to an sqlite3_context object
 4249 ** is always first parameter to [application-defined SQL functions].
 4250 ** The application-defined SQL function implementation will pass this
 4251 ** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
 4252 ** [sqlite3_aggregate_context()], [sqlite3_user_data()],
 4253 ** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
 4254 ** and/or [sqlite3_set_auxdata()].
 4255 */
 4256 typedef struct sqlite3_context sqlite3_context;
 4257 
 4258 /*
 4259 ** CAPI3REF: Binding Values To Prepared Statements
 4260 ** KEYWORDS: {host parameter} {host parameters} {host parameter name}
 4261 ** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
 4262 ** METHOD: sqlite3_stmt
 4263 **
 4264 ** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
 4265 ** literals may be replaced by a [parameter] that matches one of following
 4266 ** templates:
 4267 **
 4268 ** <ul>
 4269 ** <li>  ?
 4270 ** <li>  ?NNN
 4271 ** <li>  :VVV
 4272 ** <li>  @VVV
 4273 ** <li>  $VVV
 4274 ** </ul>
 4275 **
 4276 ** In the templates above, NNN represents an integer literal,
 4277 ** and VVV represents an alphanumeric identifier.)^  ^The values of these
 4278 ** parameters (also called "host parameter names" or "SQL parameters")
 4279 ** can be set using the sqlite3_bind_*() routines defined here.
 4280 **
 4281 ** ^The first argument to the sqlite3_bind_*() routines is always
 4282 ** a pointer to the [sqlite3_stmt] object returned from
 4283 ** [sqlite3_prepare_v2()] or its variants.
 4284 **
 4285 ** ^The second argument is the index of the SQL parameter to be set.
 4286 ** ^The leftmost SQL parameter has an index of 1.  ^When the same named
 4287 ** SQL parameter is used more than once, second and subsequent
 4288 ** occurrences have the same index as the first occurrence.
 4289 ** ^The index for named parameters can be looked up using the
 4290 ** [sqlite3_bind_parameter_index()] API if desired.  ^The index
 4291 ** for "?NNN" parameters is the value of NNN.
 4292 ** ^The NNN value must be between 1 and the [sqlite3_limit()]
 4293 ** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 32766).
 4294 **
 4295 ** ^The third argument is the value to bind to the parameter.
 4296 ** ^If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
 4297 ** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
 4298 ** is ignored and the end result is the same as sqlite3_bind_null().
 4299 ** ^If the third parameter to sqlite3_bind_text() is not NULL, then
 4300 ** it should be a pointer to well-formed UTF8 text.
 4301 ** ^If the third parameter to sqlite3_bind_text16() is not NULL, then
 4302 ** it should be a pointer to well-formed UTF16 text.
 4303 ** ^If the third parameter to sqlite3_bind_text64() is not NULL, then
 4304 ** it should be a pointer to a well-formed unicode string that is
 4305 ** either UTF8 if the sixth parameter is SQLITE_UTF8, or UTF16
 4306 ** otherwise.
 4307 **
 4308 ** [[byte-order determination rules]] ^The byte-order of
 4309 ** UTF16 input text is determined by the byte-order mark (BOM, U+FEFF)
 4310 ** found in first character, which is removed, or in the absence of a BOM
 4311 ** the byte order is the native byte order of the host
 4312 ** machine for sqlite3_bind_text16() or the byte order specified in
 4313 ** the 6th parameter for sqlite3_bind_text64().)^ 
 4314 ** ^If UTF16 input text contains invalid unicode
 4315 ** characters, then SQLite might change those invalid characters
 4316 ** into the unicode replacement character: U+FFFD.
 4317 **
 4318 ** ^(In those routines that have a fourth argument, its value is the
 4319 ** number of bytes in the parameter.  To be clear: the value is the
 4320 ** number of <u>bytes</u> in the value, not the number of characters.)^
 4321 ** ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
 4322 ** is negative, then the length of the string is
 4323 ** the number of bytes up to the first zero terminator.
 4324 ** If the fourth parameter to sqlite3_bind_blob() is negative, then
 4325 ** the behavior is undefined.
 4326 ** If a non-negative fourth parameter is provided to sqlite3_bind_text()
 4327 ** or sqlite3_bind_text16() or sqlite3_bind_text64() then
 4328 ** that parameter must be the byte offset
 4329 ** where the NUL terminator would occur assuming the string were NUL
 4330 ** terminated.  If any NUL characters occurs at byte offsets less than 
 4331 ** the value of the fourth parameter then the resulting string value will
 4332 ** contain embedded NULs.  The result of expressions involving strings
 4333 ** with embedded NULs is undefined.
 4334 **
 4335 ** ^The fifth argument to the BLOB and string binding interfaces
 4336 ** is a destructor used to dispose of the BLOB or
 4337 ** string after SQLite has finished with it.  ^The destructor is called
 4338 ** to dispose of the BLOB or string even if the call to the bind API fails,
 4339 ** except the destructor is not called if the third parameter is a NULL
 4340 ** pointer or the fourth parameter is negative.
 4341 ** ^If the fifth argument is
 4342 ** the special value [SQLITE_STATIC], then SQLite assumes that the
 4343 ** information is in static, unmanaged space and does not need to be freed.
 4344 ** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
 4345 ** SQLite makes its own private copy of the data immediately, before
 4346 ** the sqlite3_bind_*() routine returns.
 4347 **
 4348 ** ^The sixth argument to sqlite3_bind_text64() must be one of
 4349 ** [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE]
 4350 ** to specify the encoding of the text in the third parameter.  If
 4351 ** the sixth argument to sqlite3_bind_text64() is not one of the
 4352 ** allowed values shown above, or if the text encoding is different
 4353 ** from the encoding specified by the sixth parameter, then the behavior
 4354 ** is undefined.
 4355 **
 4356 ** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
 4357 ** is filled with zeroes.  ^A zeroblob uses a fixed amount of memory
 4358 ** (just an integer to hold its size) while it is being processed.
 4359 ** Zeroblobs are intended to serve as placeholders for BLOBs whose
 4360 ** content is later written using
 4361 ** [sqlite3_blob_open | incremental BLOB I/O] routines.
 4362 ** ^A negative value for the zeroblob results in a zero-length BLOB.
 4363 **
 4364 ** ^The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in
 4365 ** [prepared statement] S to have an SQL value of NULL, but to also be
 4366 ** associated with the pointer P of type T.  ^D is either a NULL pointer or
 4367 ** a pointer to a destructor function for P. ^SQLite will invoke the
 4368 ** destructor D with a single argument of P when it is finished using
 4369 ** P.  The T parameter should be a static string, preferably a string
 4370 ** literal. The sqlite3_bind_pointer() routine is part of the
 4371 ** [pointer passing interface] added for SQLite 3.20.0.
 4372 **
 4373 ** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
 4374 ** for the [prepared statement] or with a prepared statement for which
 4375 ** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
 4376 ** then the call will return [SQLITE_MISUSE].  If any sqlite3_bind_()
 4377 ** routine is passed a [prepared statement] that has been finalized, the
 4378 ** result is undefined and probably harmful.
 4379 **
 4380 ** ^Bindings are not cleared by the [sqlite3_reset()] routine.
 4381 ** ^Unbound parameters are interpreted as NULL.
 4382 **
 4383 ** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
 4384 ** [error code] if anything goes wrong.
 4385 ** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB
 4386 ** exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or
 4387 ** [SQLITE_MAX_LENGTH].
 4388 ** ^[SQLITE_RANGE] is returned if the parameter
 4389 ** index is out of range.  ^[SQLITE_NOMEM] is returned if malloc() fails.
 4390 **
 4391 ** See also: [sqlite3_bind_parameter_count()],
 4392 ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
 4393 */
 4394 SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
 4395 SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
 4396                         void(*)(void*));
 4397 SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
 4398 SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
 4399 SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
 4400 SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
 4401 SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
 4402 SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
 4403 SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
 4404                          void(*)(void*), unsigned char encoding);
 4405 SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
 4406 SQLITE_API int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*));
 4407 SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
 4408 SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
 4409 
 4410 /*
 4411 ** CAPI3REF: Number Of SQL Parameters
 4412 ** METHOD: sqlite3_stmt
 4413 **
 4414 ** ^This routine can be used to find the number of [SQL parameters]
 4415 ** in a [prepared statement].  SQL parameters are tokens of the
 4416 ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
 4417 ** placeholders for values that are [sqlite3_bind_blob | bound]
 4418 ** to the parameters at a later time.
 4419 **
 4420 ** ^(This routine actually returns the index of the largest (rightmost)
 4421 ** parameter. For all forms except ?NNN, this will correspond to the
 4422 ** number of unique parameters.  If parameters of the ?NNN form are used,
 4423 ** there may be gaps in the list.)^
 4424 **
 4425 ** See also: [sqlite3_bind_blob|sqlite3_bind()],
 4426 ** [sqlite3_bind_parameter_name()], and
 4427 ** [sqlite3_bind_parameter_index()].
 4428 */
 4429 SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
 4430 
 4431 /*
 4432 ** CAPI3REF: Name Of A Host Parameter
 4433 ** METHOD: sqlite3_stmt
 4434 **
 4435 ** ^The sqlite3_bind_parameter_name(P,N) interface returns
 4436 ** the name of the N-th [SQL parameter] in the [prepared statement] P.
 4437 ** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
 4438 ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
 4439 ** respectively.
 4440 ** In other words, the initial ":" or "$" or "@" or "?"
 4441 ** is included as part of the name.)^
 4442 ** ^Parameters of the form "?" without a following integer have no name
 4443 ** and are referred to as "nameless" or "anonymous parameters".
 4444 **
 4445 ** ^The first host parameter has an index of 1, not 0.
 4446 **
 4447 ** ^If the value N is out of range or if the N-th parameter is
 4448 ** nameless, then NULL is returned.  ^The returned string is
 4449 ** always in UTF-8 encoding even if the named parameter was
 4450 ** originally specified as UTF-16 in [sqlite3_prepare16()],
 4451 ** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
 4452 **
 4453 ** See also: [sqlite3_bind_blob|sqlite3_bind()],
 4454 ** [sqlite3_bind_parameter_count()], and
 4455 ** [sqlite3_bind_parameter_index()].
 4456 */
 4457 SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
 4458 
 4459 /*
 4460 ** CAPI3REF: Index Of A Parameter With A Given Name
 4461 ** METHOD: sqlite3_stmt
 4462 **
 4463 ** ^Return the index of an SQL parameter given its name.  ^The
 4464 ** index value returned is suitable for use as the second
 4465 ** parameter to [sqlite3_bind_blob|sqlite3_bind()].  ^A zero
 4466 ** is returned if no matching parameter is found.  ^The parameter
 4467 ** name must be given in UTF-8 even if the original statement
 4468 ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()] or
 4469 ** [sqlite3_prepare16_v3()].
 4470 **
 4471 ** See also: [sqlite3_bind_blob|sqlite3_bind()],
 4472 ** [sqlite3_bind_parameter_count()], and
 4473 ** [sqlite3_bind_parameter_name()].
 4474 */
 4475 SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
 4476 
 4477 /*
 4478 ** CAPI3REF: Reset All Bindings On A Prepared Statement
 4479 ** METHOD: sqlite3_stmt
 4480 **
 4481 ** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
 4482 ** the [sqlite3_bind_blob | bindings] on a [prepared statement].
 4483 ** ^Use this routine to reset all host parameters to NULL.
 4484 */
 4485 SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
 4486 
 4487 /*
 4488 ** CAPI3REF: Number Of Columns In A Result Set
 4489 ** METHOD: sqlite3_stmt
 4490 **
 4491 ** ^Return the number of columns in the result set returned by the
 4492 ** [prepared statement]. ^If this routine returns 0, that means the 
 4493 ** [prepared statement] returns no data (for example an [UPDATE]).
 4494 ** ^However, just because this routine returns a positive number does not
 4495 ** mean that one or more rows of data will be returned.  ^A SELECT statement
 4496 ** will always have a positive sqlite3_column_count() but depending on the
 4497 ** WHERE clause constraints and the table content, it might return no rows.
 4498 **
 4499 ** See also: [sqlite3_data_count()]
 4500 */
 4501 SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
 4502 
 4503 /*
 4504 ** CAPI3REF: Column Names In A Result Set
 4505 ** METHOD: sqlite3_stmt
 4506 **
 4507 ** ^These routines return the name assigned to a particular column
 4508 ** in the result set of a [SELECT] statement.  ^The sqlite3_column_name()
 4509 ** interface returns a pointer to a zero-terminated UTF-8 string
 4510 ** and sqlite3_column_name16() returns a pointer to a zero-terminated
 4511 ** UTF-16 string.  ^The first parameter is the [prepared statement]
 4512 ** that implements the [SELECT] statement. ^The second parameter is the
 4513 ** column number.  ^The leftmost column is number 0.
 4514 **
 4515 ** ^The returned string pointer is valid until either the [prepared statement]
 4516 ** is destroyed by [sqlite3_finalize()] or until the statement is automatically
 4517 ** reprepared by the first call to [sqlite3_step()] for a particular run
 4518 ** or until the next call to
 4519 ** sqlite3_column_name() or sqlite3_column_name16() on the same column.
 4520 **
 4521 ** ^If sqlite3_malloc() fails during the processing of either routine
 4522 ** (for example during a conversion from UTF-8 to UTF-16) then a
 4523 ** NULL pointer is returned.
 4524 **
 4525 ** ^The name of a result column is the value of the "AS" clause for
 4526 ** that column, if there is an AS clause.  If there is no AS clause
 4527 ** then the name of the column is unspecified and may change from
 4528 ** one release of SQLite to the next.
 4529 */
 4530 SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
 4531 SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
 4532 
 4533 /*
 4534 ** CAPI3REF: Source Of Data In A Query Result
 4535 ** METHOD: sqlite3_stmt
 4536 **
 4537 ** ^These routines provide a means to determine the database, table, and
 4538 ** table column that is the origin of a particular result column in
 4539 ** [SELECT] statement.
 4540 ** ^The name of the database or table or column can be returned as
 4541 ** either a UTF-8 or UTF-16 string.  ^The _database_ routines return
 4542 ** the database name, the _table_ routines return the table name, and
 4543 ** the origin_ routines return the column name.
 4544 ** ^The returned string is valid until the [prepared statement] is destroyed
 4545 ** using [sqlite3_finalize()] or until the statement is automatically
 4546 ** reprepared by the first call to [sqlite3_step()] for a particular run
 4547 ** or until the same information is requested
 4548 ** again in a different encoding.
 4549 **
 4550 ** ^The names returned are the original un-aliased names of the
 4551 ** database, table, and column.
 4552 **
 4553 ** ^The first argument to these interfaces is a [prepared statement].
 4554 ** ^These functions return information about the Nth result column returned by
 4555 ** the statement, where N is the second function argument.
 4556 ** ^The left-most column is column 0 for these routines.
 4557 **
 4558 ** ^If the Nth column returned by the statement is an expression or
 4559 ** subquery and is not a column value, then all of these functions return
 4560 ** NULL.  ^These routines might also return NULL if a memory allocation error
 4561 ** occurs.  ^Otherwise, they return the name of the attached database, table,
 4562 ** or column that query result column was extracted from.
 4563 **
 4564 ** ^As with all other SQLite APIs, those whose names end with "16" return
 4565 ** UTF-16 encoded strings and the other functions return UTF-8.
 4566 **
 4567 ** ^These APIs are only available if the library was compiled with the
 4568 ** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
 4569 **
 4570 ** If two or more threads call one or more
 4571 ** [sqlite3_column_database_name | column metadata interfaces]
 4572 ** for the same [prepared statement] and result column
 4573 ** at the same time then the results are undefined.
 4574 */
 4575 SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);
 4576 SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
 4577 SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);
 4578 SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
 4579 SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
 4580 SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
 4581 
 4582 /*
 4583 ** CAPI3REF: Declared Datatype Of A Query Result
 4584 ** METHOD: sqlite3_stmt
 4585 **
 4586 ** ^(The first parameter is a [prepared statement].
 4587 ** If this statement is a [SELECT] statement and the Nth column of the
 4588 ** returned result set of that [SELECT] is a table column (not an
 4589 ** expression or subquery) then the declared type of the table
 4590 ** column is returned.)^  ^If the Nth column of the result set is an
 4591 ** expression or subquery, then a NULL pointer is returned.
 4592 ** ^The returned string is always UTF-8 encoded.
 4593 **
 4594 ** ^(For example, given the database schema:
 4595 **
 4596 ** CREATE TABLE t1(c1 VARIANT);
 4597 **
 4598 ** and the following statement to be compiled:
 4599 **
 4600 ** SELECT c1 + 1, c1 FROM t1;
 4601 **
 4602 ** this routine would return the string "VARIANT" for the second result
 4603 ** column (i==1), and a NULL pointer for the first result column (i==0).)^
 4604 **
 4605 ** ^SQLite uses dynamic run-time typing.  ^So just because a column
 4606 ** is declared to contain a particular type does not mean that the
 4607 ** data stored in that column is of the declared type.  SQLite is
 4608 ** strongly typed, but the typing is dynamic not static.  ^Type
 4609 ** is associated with individual values, not with the containers
 4610 ** used to hold those values.
 4611 */
 4612 SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
 4613 SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
 4614 
 4615 /*
 4616 ** CAPI3REF: Evaluate An SQL Statement
 4617 ** METHOD: sqlite3_stmt
 4618 **
 4619 ** After a [prepared statement] has been prepared using any of
 4620 ** [sqlite3_prepare_v2()], [sqlite3_prepare_v3()], [sqlite3_prepare16_v2()],
 4621 ** or [sqlite3_prepare16_v3()] or one of the legacy
 4622 ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
 4623 ** must be called one or more times to evaluate the statement.
 4624 **
 4625 ** The details of the behavior of the sqlite3_step() interface depend
 4626 ** on whether the statement was prepared using the newer "vX" interfaces
 4627 ** [sqlite3_prepare_v3()], [sqlite3_prepare_v2()], [sqlite3_prepare16_v3()],
 4628 ** [sqlite3_prepare16_v2()] or the older legacy
 4629 ** interfaces [sqlite3_prepare()] and [sqlite3_prepare16()].  The use of the
 4630 ** new "vX" interface is recommended for new applications but the legacy
 4631 ** interface will continue to be supported.
 4632 **
 4633 ** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
 4634 ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
 4635 ** ^With the "v2" interface, any of the other [result codes] or
 4636 ** [extended result codes] might be returned as well.
 4637 **
 4638 ** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
 4639 ** database locks it needs to do its job.  ^If the statement is a [COMMIT]
 4640 ** or occurs outside of an explicit transaction, then you can retry the
 4641 ** statement.  If the statement is not a [COMMIT] and occurs within an
 4642 ** explicit transaction then you should rollback the transaction before
 4643 ** continuing.
 4644 **
 4645 ** ^[SQLITE_DONE] means that the statement has finished executing
 4646 ** successfully.  sqlite3_step() should not be called again on this virtual
 4647 ** machine without first calling [sqlite3_reset()] to reset the virtual
 4648 ** machine back to its initial state.
 4649 **
 4650 ** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]
 4651 ** is returned each time a new row of data is ready for processing by the
 4652 ** caller. The values may be accessed using the [column access functions].
 4653 ** sqlite3_step() is called again to retrieve the next row of data.
 4654 **
 4655 ** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
 4656 ** violation) has occurred.  sqlite3_step() should not be called again on
 4657 ** the VM. More information may be found by calling [sqlite3_errmsg()].
 4658 ** ^With the legacy interface, a more specific error code (for example,
 4659 ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
 4660 ** can be obtained by calling [sqlite3_reset()] on the
 4661 ** [prepared statement].  ^In the "v2" interface,
 4662 ** the more specific error code is returned directly by sqlite3_step().
 4663 **
 4664 ** [SQLITE_MISUSE] means that the this routine was called inappropriately.
 4665 ** Perhaps it was called on a [prepared statement] that has
 4666 ** already been [sqlite3_finalize | finalized] or on one that had
 4667 ** previously returned [SQLITE_ERROR] or [SQLITE_DONE].  Or it could
 4668 ** be the case that the same database connection is being used by two or
 4669 ** more threads at the same moment in time.
 4670 **
 4671 ** For all versions of SQLite up to and including 3.6.23.1, a call to
 4672 ** [sqlite3_reset()] was required after sqlite3_step() returned anything
 4673 ** other than [SQLITE_ROW] before any subsequent invocation of
 4674 ** sqlite3_step().  Failure to reset the prepared statement using 
 4675 ** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from
 4676 ** sqlite3_step().  But after [version 3.6.23.1] ([dateof:3.6.23.1],
 4677 ** sqlite3_step() began
 4678 ** calling [sqlite3_reset()] automatically in this circumstance rather
 4679 ** than returning [SQLITE_MISUSE].  This is not considered a compatibility
 4680 ** break because any application that ever receives an SQLITE_MISUSE error
 4681 ** is broken by definition.  The [SQLITE_OMIT_AUTORESET] compile-time option
 4682 ** can be used to restore the legacy behavior.
 4683 **
 4684 ** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
 4685 ** API always returns a generic error code, [SQLITE_ERROR], following any
 4686 ** error other than [SQLITE_BUSY] and [SQLITE_MISUSE].  You must call
 4687 ** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
 4688 ** specific [error codes] that better describes the error.
 4689 ** We admit that this is a goofy design.  The problem has been fixed
 4690 ** with the "v2" interface.  If you prepare all of your SQL statements
 4691 ** using [sqlite3_prepare_v3()] or [sqlite3_prepare_v2()]
 4692 ** or [sqlite3_prepare16_v2()] or [sqlite3_prepare16_v3()] instead
 4693 ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
 4694 ** then the more specific [error codes] are returned directly
 4695 ** by sqlite3_step().  The use of the "vX" interfaces is recommended.
 4696 */
 4697 SQLITE_API int sqlite3_step(sqlite3_stmt*);
 4698 
 4699 /*
 4700 ** CAPI3REF: Number of columns in a result set
 4701 ** METHOD: sqlite3_stmt
 4702 **
 4703 ** ^The sqlite3_data_count(P) interface returns the number of columns in the
 4704 ** current row of the result set of [prepared statement] P.
 4705 ** ^If prepared statement P does not have results ready to return
 4706 ** (via calls to the [sqlite3_column_int | sqlite3_column()] family of
 4707 ** interfaces) then sqlite3_data_count(P) returns 0.
 4708 ** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
 4709 ** ^The sqlite3_data_count(P) routine returns 0 if the previous call to
 4710 ** [sqlite3_step](P) returned [SQLITE_DONE].  ^The sqlite3_data_count(P)
 4711 ** will return non-zero if previous call to [sqlite3_step](P) returned
 4712 ** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum]
 4713 ** where it always returns zero since each step of that multi-step
 4714 ** pragma returns 0 columns of data.
 4715 **
 4716 ** See also: [sqlite3_column_count()]
 4717 */
 4718 SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
 4719 
 4720 /*
 4721 ** CAPI3REF: Fundamental Datatypes
 4722 ** KEYWORDS: SQLITE_TEXT
 4723 **
 4724 ** ^(Every value in SQLite has one of five fundamental datatypes:
 4725 **
 4726 ** <ul>
 4727 ** <li> 64-bit signed integer
 4728 ** <li> 64-bit IEEE floating point number
 4729 ** <li> string
 4730 ** <li> BLOB
 4731 ** <li> NULL
 4732 ** </ul>)^
 4733 **
 4734 ** These constants are codes for each of those types.
 4735 **
 4736 ** Note that the SQLITE_TEXT constant was also used in SQLite version 2
 4737 ** for a completely different meaning.  Software that links against both
 4738 ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
 4739 ** SQLITE_TEXT.
 4740 */
 4741 #define SQLITE_INTEGER  1
 4742 #define SQLITE_FLOAT    2
 4743 #define SQLITE_BLOB     4
 4744 #define SQLITE_NULL     5
 4745 #ifdef SQLITE_TEXT
 4746 # undef SQLITE_TEXT
 4747 #else
 4748 # define SQLITE_TEXT     3
 4749 #endif
 4750 #define SQLITE3_TEXT     3
 4751 
 4752 /*
 4753 ** CAPI3REF: Result Values From A Query
 4754 ** KEYWORDS: {column access functions}
 4755 ** METHOD: sqlite3_stmt
 4756 **
 4757 ** <b>Summary:</b>
 4758 ** <blockquote><table border=0 cellpadding=0 cellspacing=0>
 4759 ** <tr><td><b>sqlite3_column_blob</b><td>&rarr;<td>BLOB result
 4760 ** <tr><td><b>sqlite3_column_double</b><td>&rarr;<td>REAL result
 4761 ** <tr><td><b>sqlite3_column_int</b><td>&rarr;<td>32-bit INTEGER result
 4762 ** <tr><td><b>sqlite3_column_int64</b><td>&rarr;<td>64-bit INTEGER result
 4763 ** <tr><td><b>sqlite3_column_text</b><td>&rarr;<td>UTF-8 TEXT result
 4764 ** <tr><td><b>sqlite3_column_text16</b><td>&rarr;<td>UTF-16 TEXT result
 4765 ** <tr><td><b>sqlite3_column_value</b><td>&rarr;<td>The result as an 
 4766 ** [sqlite3_value|unprotected sqlite3_value] object.
 4767 ** <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
 4768 ** <tr><td><b>sqlite3_column_bytes</b><td>&rarr;<td>Size of a BLOB
 4769 ** or a UTF-8 TEXT result in bytes
 4770 ** <tr><td><b>sqlite3_column_bytes16&nbsp;&nbsp;</b>
 4771 ** <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
 4772 ** TEXT in bytes
 4773 ** <tr><td><b>sqlite3_column_type</b><td>&rarr;<td>Default
 4774 ** datatype of the result
 4775 ** </table></blockquote>
 4776 **
 4777 ** <b>Details:</b>
 4778 **
 4779 ** ^These routines return information about a single column of the current
 4780 ** result row of a query.  ^In every case the first argument is a pointer
 4781 ** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
 4782 ** that was returned from [sqlite3_prepare_v2()] or one of its variants)
 4783 ** and the second argument is the index of the column for which information
 4784 ** should be returned. ^The leftmost column of the result set has the index 0.
 4785 ** ^The number of columns in the result can be determined using
 4786 ** [sqlite3_column_count()].
 4787 **
 4788 ** If the SQL statement does not currently point to a valid row, or if the
 4789 ** column index is out of range, the result is undefined.
 4790 ** These routines may only be called when the most recent call to
 4791 ** [sqlite3_step()] has returned [SQLITE_ROW] and neither
 4792 ** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.
 4793 ** If any of these routines are called after [sqlite3_reset()] or
 4794 ** [sqlite3_finalize()] or after [sqlite3_step()] has returned
 4795 ** something other than [SQLITE_ROW], the results are undefined.
 4796 ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
 4797 ** are called from a different thread while any of these routines
 4798 ** are pending, then the results are undefined.
 4799 **
 4800 ** The first six interfaces (_blob, _double, _int, _int64, _text, and _text16)
 4801 ** each return the value of a result column in a specific data format.  If
 4802 ** the result column is not initially in the requested format (for example,
 4803 ** if the query returns an integer but the sqlite3_column_text() interface
 4804 ** is used to extract the value) then an automatic type conversion is performed.
 4805 **
 4806 ** ^The sqlite3_column_type() routine returns the
 4807 ** [SQLITE_INTEGER | datatype code] for the initial data type
 4808 ** of the result column.  ^The returned value is one of [SQLITE_INTEGER],
 4809 ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].
 4810 ** The return value of sqlite3_column_type() can be used to decide which
 4811 ** of the first six interface should be used to extract the column value.
 4812 ** The value returned by sqlite3_column_type() is only meaningful if no
 4813 ** automatic type conversions have occurred for the value in question.  
 4814 ** After a type conversion, the result of calling sqlite3_column_type()
 4815 ** is undefined, though harmless.  Future
 4816 ** versions of SQLite may change the behavior of sqlite3_column_type()
 4817 ** following a type conversion.
 4818 **
 4819 ** If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()
 4820 ** or sqlite3_column_bytes16() interfaces can be used to determine the size
 4821 ** of that BLOB or string.
 4822 **
 4823 ** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
 4824 ** routine returns the number of bytes in that BLOB or string.
 4825 ** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
 4826 ** the string to UTF-8 and then returns the number of bytes.
 4827 ** ^If the result is a numeric value then sqlite3_column_bytes() uses
 4828 ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
 4829 ** the number of bytes in that string.
 4830 ** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
 4831 **
 4832 ** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
 4833 ** routine returns the number of bytes in that BLOB or string.
 4834 ** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
 4835 ** the string to UTF-16 and then returns the number of bytes.
 4836 ** ^If the result is a numeric value then sqlite3_column_bytes16() uses
 4837 ** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
 4838 ** the number of bytes in that string.
 4839 ** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
 4840 **
 4841 ** ^The values returned by [sqlite3_column_bytes()] and 
 4842 ** [sqlite3_column_bytes16()] do not include the zero terminators at the end
 4843 ** of the string.  ^For clarity: the values returned by
 4844 ** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of
 4845 ** bytes in the string, not the number of characters.
 4846 **
 4847 ** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
 4848 ** even empty strings, are always zero-terminated.  ^The return
 4849 ** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
 4850 **
 4851 ** <b>Warning:</b> ^The object returned by [sqlite3_column_value()] is an
 4852 ** [unprotected sqlite3_value] object.  In a multithreaded environment,
 4853 ** an unprotected sqlite3_value object may only be used safely with
 4854 ** [sqlite3_bind_value()] and [sqlite3_result_value()].
 4855 ** If the [unprotected sqlite3_value] object returned by
 4856 ** [sqlite3_column_value()] is used in any other way, including calls
 4857 ** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
 4858 ** or [sqlite3_value_bytes()], the behavior is not threadsafe.
 4859 ** Hence, the sqlite3_column_value() interface
 4860 ** is normally only useful within the implementation of 
 4861 ** [application-defined SQL functions] or [virtual tables], not within
 4862 ** top-level application code.
 4863 **
 4864 ** The these routines may attempt to convert the datatype of the result.
 4865 ** ^For example, if the internal representation is FLOAT and a text result
 4866 ** is requested, [sqlite3_snprintf()] is used internally to perform the
 4867 ** conversion automatically.  ^(The following table details the conversions
 4868 ** that are applied:
 4869 **
 4870 ** <blockquote>
 4871 ** <table border="1">
 4872 ** <tr><th> Internal<br>Type <th> Requested<br>Type <th>  Conversion
 4873 **
 4874 ** <tr><td>  NULL    <td> INTEGER   <td> Result is 0
 4875 ** <tr><td>  NULL    <td>  FLOAT    <td> Result is 0.0
 4876 ** <tr><td>  NULL    <td>   TEXT    <td> Result is a NULL pointer
 4877 ** <tr><td>  NULL    <td>   BLOB    <td> Result is a NULL pointer
 4878 ** <tr><td> INTEGER  <td>  FLOAT    <td> Convert from integer to float
 4879 ** <tr><td> INTEGER  <td>   TEXT    <td> ASCII rendering of the integer
 4880 ** <tr><td> INTEGER  <td>   BLOB    <td> Same as INTEGER->TEXT
 4881 ** <tr><td>  FLOAT   <td> INTEGER   <td> [CAST] to INTEGER
 4882 ** <tr><td>  FLOAT   <td>   TEXT    <td> ASCII rendering of the float
 4883 ** <tr><td>  FLOAT   <td>   BLOB    <td> [CAST] to BLOB
 4884 ** <tr><td>  TEXT    <td> INTEGER   <td> [CAST] to INTEGER
 4885 ** <tr><td>  TEXT    <td>  FLOAT    <td> [CAST] to REAL
 4886 ** <tr><td>  TEXT    <td>   BLOB    <td> No change
 4887 ** <tr><td>  BLOB    <td> INTEGER   <td> [CAST] to INTEGER
 4888 ** <tr><td>  BLOB    <td>  FLOAT    <td> [CAST] to REAL
 4889 ** <tr><td>  BLOB    <td>   TEXT    <td> Add a zero terminator if needed
 4890 ** </table>
 4891 ** </blockquote>)^
 4892 **
 4893 ** Note that when type conversions occur, pointers returned by prior
 4894 ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
 4895 ** sqlite3_column_text16() may be invalidated.
 4896 ** Type conversions and pointer invalidations might occur
 4897 ** in the following cases:
 4898 **
 4899 ** <ul>
 4900 ** <li> The initial content is a BLOB and sqlite3_column_text() or
 4901 **      sqlite3_column_text16() is called.  A zero-terminator might
 4902 **      need to be added to the string.</li>
 4903 ** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
 4904 **      sqlite3_column_text16() is called.  The content must be converted
 4905 **      to UTF-16.</li>
 4906 ** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
 4907 **      sqlite3_column_text() is called.  The content must be converted
 4908 **      to UTF-8.</li>
 4909 ** </ul>
 4910 **
 4911 ** ^Conversions between UTF-16be and UTF-16le are always done in place and do
 4912 ** not invalidate a prior pointer, though of course the content of the buffer
 4913 ** that the prior pointer references will have been modified.  Other kinds
 4914 ** of conversion are done in place when it is possible, but sometimes they
 4915 ** are not possible and in those cases prior pointers are invalidated.
 4916 **
 4917 ** The safest policy is to invoke these routines
 4918 ** in one of the following ways:
 4919 **
 4920 ** <ul>
 4921 **  <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
 4922 **  <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
 4923 **  <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
 4924 ** </ul>
 4925 **
 4926 ** In other words, you should call sqlite3_column_text(),
 4927 ** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
 4928 ** into the desired format, then invoke sqlite3_column_bytes() or
 4929 ** sqlite3_column_bytes16() to find the size of the result.  Do not mix calls
 4930 ** to sqlite3_column_text() or sqlite3_column_blob() with calls to
 4931 ** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
 4932 ** with calls to sqlite3_column_bytes().
 4933 **
 4934 ** ^The pointers returned are valid until a type conversion occurs as
 4935 ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
 4936 ** [sqlite3_finalize()] is called.  ^The memory space used to hold strings
 4937 ** and BLOBs is freed automatically.  Do not pass the pointers returned
 4938 ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
 4939 ** [sqlite3_free()].
 4940 **
 4941 ** As long as the input parameters are correct, these routines will only
 4942 ** fail if an out-of-memory error occurs during a format conversion.
 4943 ** Only the following subset of interfaces are subject to out-of-memory
 4944 ** errors:
 4945 **
 4946 ** <ul>
 4947 ** <li> sqlite3_column_blob()
 4948 ** <li> sqlite3_column_text()
 4949 ** <li> sqlite3_column_text16()
 4950 ** <li> sqlite3_column_bytes()
 4951 ** <li> sqlite3_column_bytes16()
 4952 ** </ul>
 4953 **
 4954 ** If an out-of-memory error occurs, then the return value from these
 4955 ** routines is the same as if the column had contained an SQL NULL value.
 4956 ** Valid SQL NULL returns can be distinguished from out-of-memory errors
 4957 ** by invoking the [sqlite3_errcode()] immediately after the suspect
 4958 ** return value is obtained and before any
 4959 ** other SQLite interface is called on the same [database connection].
 4960 */
 4961 SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
 4962 SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
 4963 SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
 4964 SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
 4965 SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
 4966 SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
 4967 SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
 4968 SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
 4969 SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
 4970 SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
 4971 
 4972 /*
 4973 ** CAPI3REF: Destroy A Prepared Statement Object
 4974 ** DESTRUCTOR: sqlite3_stmt
 4975 **
 4976 ** ^The sqlite3_finalize() function is called to delete a [prepared statement].
 4977 ** ^If the most recent evaluation of the statement encountered no errors
 4978 ** or if the statement is never been evaluated, then sqlite3_finalize() returns
 4979 ** SQLITE_OK.  ^If the most recent evaluation of statement S failed, then
 4980 ** sqlite3_finalize(S) returns the appropriate [error code] or
 4981 ** [extended error code].
 4982 **
 4983 ** ^The sqlite3_finalize(S) routine can be called at any point during
 4984 ** the life cycle of [prepared statement] S:
 4985 ** before statement S is ever evaluated, after
 4986 ** one or more calls to [sqlite3_reset()], or after any call
 4987 ** to [sqlite3_step()] regardless of whether or not the statement has
 4988 ** completed execution.
 4989 **
 4990 ** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
 4991 **
 4992 ** The application must finalize every [prepared statement] in order to avoid
 4993 ** resource leaks.  It is a grievous error for the application to try to use
 4994 ** a prepared statement after it has been finalized.  Any use of a prepared
 4995 ** statement after it has been finalized can result in undefined and
 4996 ** undesirable behavior such as segfaults and heap corruption.
 4997 */
 4998 SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
 4999 
 5000 /*
 5001 ** CAPI3REF: Reset A Prepared Statement Object
 5002 ** METHOD: sqlite3_stmt
 5003 **
 5004 ** The sqlite3_reset() function is called to reset a [prepared statement]
 5005 ** object back to its initial state, ready to be re-executed.
 5006 ** ^Any SQL statement variables that had values bound to them using
 5007 ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
 5008 ** Use [sqlite3_clear_bindings()] to reset the bindings.
 5009 **
 5010 ** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S
 5011 ** back to the beginning of its program.
 5012 **
 5013 ** ^If the most recent call to [sqlite3_step(S)] for the
 5014 ** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
 5015 ** or if [sqlite3_step(S)] has never before been called on S,
 5016 ** then [sqlite3_reset(S)] returns [SQLITE_OK].
 5017 **
 5018 ** ^If the most recent call to [sqlite3_step(S)] for the
 5019 ** [prepared statement] S indicated an error, then
 5020 ** [sqlite3_reset(S)] returns an appropriate [error code].
 5021 **
 5022 ** ^The [sqlite3_reset(S)] interface does not change the values
 5023 ** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
 5024 */
 5025 SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
 5026 
 5027 /*
 5028 ** CAPI3REF: Create Or Redefine SQL Functions
 5029 ** KEYWORDS: {function creation routines}
 5030 ** METHOD: sqlite3
 5031 **
 5032 ** ^These functions (collectively known as "function creation routines")
 5033 ** are used to add SQL functions or aggregates or to redefine the behavior
 5034 ** of existing SQL functions or aggregates. The only differences between
 5035 ** the three "sqlite3_create_function*" routines are the text encoding 
 5036 ** expected for the second parameter (the name of the function being 
 5037 ** created) and the presence or absence of a destructor callback for
 5038 ** the application data pointer. Function sqlite3_create_window_function()
 5039 ** is similar, but allows the user to supply the extra callback functions
 5040 ** needed by [aggregate window functions].
 5041 **
 5042 ** ^The first parameter is the [database connection] to which the SQL
 5043 ** function is to be added.  ^If an application uses more than one database
 5044 ** connection then application-defined SQL functions must be added
 5045 ** to each database connection separately.
 5046 **
 5047 ** ^The second parameter is the name of the SQL function to be created or
 5048 ** redefined.  ^The length of the name is limited to 255 bytes in a UTF-8
 5049 ** representation, exclusive of the zero-terminator.  ^Note that the name
 5050 ** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.  
 5051 ** ^Any attempt to create a function with a longer name
 5052 ** will result in [SQLITE_MISUSE] being returned.
 5053 **
 5054 ** ^The third parameter (nArg)
 5055 ** is the number of arguments that the SQL function or
 5056 ** aggregate takes. ^If this parameter is -1, then the SQL function or
 5057 ** aggregate may take any number of arguments between 0 and the limit
 5058 ** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]).  If the third
 5059 ** parameter is less than -1 or greater than 127 then the behavior is
 5060 ** undefined.
 5061 **
 5062 ** ^The fourth parameter, eTextRep, specifies what
 5063 ** [SQLITE_UTF8 | text encoding] this SQL function prefers for
 5064 ** its parameters.  The application should set this parameter to
 5065 ** [SQLITE_UTF16LE] if the function implementation invokes 
 5066 ** [sqlite3_value_text16le()] on an input, or [SQLITE_UTF16BE] if the
 5067 ** implementation invokes [sqlite3_value_text16be()] on an input, or
 5068 ** [SQLITE_UTF16] if [sqlite3_value_text16()] is used, or [SQLITE_UTF8]
 5069 ** otherwise.  ^The same SQL function may be registered multiple times using
 5070 ** different preferred text encodings, with different implementations for
 5071 ** each encoding.
 5072 ** ^When multiple implementations of the same function are available, SQLite
 5073 ** will pick the one that involves the least amount of data conversion.
 5074 **
 5075 ** ^The fourth parameter may optionally be ORed with [SQLITE_DETERMINISTIC]
 5076 ** to signal that the function will always return the same result given
 5077 ** the same inputs within a single SQL statement.  Most SQL functions are
 5078 ** deterministic.  The built-in [random()] SQL function is an example of a
 5079 ** function that is not deterministic.  The SQLite query planner is able to
 5080 ** perform additional optimizations on deterministic functions, so use
 5081 ** of the [SQLITE_DETERMINISTIC] flag is recommended where possible.
 5082 **
 5083 ** ^The fourth parameter may also optionally include the [SQLITE_DIRECTONLY]
 5084 ** flag, which if present prevents the function from being invoked from
 5085 ** within VIEWs, TRIGGERs, CHECK constraints, generated column expressions,
 5086 ** index expressions, or the WHERE clause of partial indexes.
 5087 **
 5088 ** <span style="background-color:#ffff90;">
 5089 ** For best security, the [SQLITE_DIRECTONLY] flag is recommended for
 5090 ** all application-defined SQL functions that do not need to be
 5091 ** used inside of triggers, view, CHECK constraints, or other elements of
 5092 ** the database schema.  This flags is especially recommended for SQL 
 5093 ** functions that have side effects or reveal internal application state.
 5094 ** Without this flag, an attacker might be able to modify the schema of
 5095 ** a database file to include invocations of the function with parameters
 5096 ** chosen by the attacker, which the application will then execute when
 5097 ** the database file is opened and read.
 5098 ** </span>
 5099 **
 5100 ** ^(The fifth parameter is an arbitrary pointer.  The implementation of the
 5101 ** function can gain access to this pointer using [sqlite3_user_data()].)^
 5102 **
 5103 ** ^The sixth, seventh and eighth parameters passed to the three
 5104 ** "sqlite3_create_function*" functions, xFunc, xStep and xFinal, are
 5105 ** pointers to C-language functions that implement the SQL function or
 5106 ** aggregate. ^A scalar SQL function requires an implementation of the xFunc
 5107 ** callback only; NULL pointers must be passed as the xStep and xFinal
 5108 ** parameters. ^An aggregate SQL function requires an implementation of xStep
 5109 ** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing
 5110 ** SQL function or aggregate, pass NULL pointers for all three function
 5111 ** callbacks.
 5112 **
 5113 ** ^The sixth, seventh, eighth and ninth parameters (xStep, xFinal, xValue 
 5114 ** and xInverse) passed to sqlite3_create_window_function are pointers to
 5115 ** C-language callbacks that implement the new function. xStep and xFinal
 5116 ** must both be non-NULL. xValue and xInverse may either both be NULL, in
 5117 ** which case a regular aggregate function is created, or must both be 
 5118 ** non-NULL, in which case the new function may be used as either an aggregate
 5119 ** or aggregate window function. More details regarding the implementation
 5120 ** of aggregate window functions are 
 5121 ** [user-defined window functions|available here].
 5122 **
 5123 ** ^(If the final parameter to sqlite3_create_function_v2() or
 5124 ** sqlite3_create_window_function() is not NULL, then it is destructor for
 5125 ** the application data pointer. The destructor is invoked when the function 
 5126 ** is deleted, either by being overloaded or when the database connection 
 5127 ** closes.)^ ^The destructor is also invoked if the call to 
 5128 ** sqlite3_create_function_v2() fails.  ^When the destructor callback is
 5129 ** invoked, it is passed a single argument which is a copy of the application
 5130 ** data pointer which was the fifth parameter to sqlite3_create_function_v2().
 5131 **
 5132 ** ^It is permitted to register multiple implementations of the same
 5133 ** functions with the same name but with either differing numbers of
 5134 ** arguments or differing preferred text encodings.  ^SQLite will use
 5135 ** the implementation that most closely matches the way in which the
 5136 ** SQL function is used.  ^A function implementation with a non-negative
 5137 ** nArg parameter is a better match than a function implementation with
 5138 ** a negative nArg.  ^A function where the preferred text encoding
 5139 ** matches the database encoding is a better
 5140 ** match than a function where the encoding is different.  
 5141 ** ^A function where the encoding difference is between UTF16le and UTF16be
 5142 ** is a closer match than a function where the encoding difference is
 5143 ** between UTF8 and UTF16.
 5144 **
 5145 ** ^Built-in functions may be overloaded by new application-defined functions.
 5146 **
 5147 ** ^An application-defined function is permitted to call other
 5148 ** SQLite interfaces.  However, such calls must not
 5149 ** close the database connection nor finalize or reset the prepared
 5150 ** statement in which the function is running.
 5151 */
 5152 SQLITE_API int sqlite3_create_function(
 5153   sqlite3 *db,
 5154   const char *zFunctionName,
 5155   int nArg,
 5156   int eTextRep,
 5157   void *pApp,
 5158   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
 5159   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
 5160   void (*xFinal)(sqlite3_context*)
 5161 );
 5162 SQLITE_API int sqlite3_create_function16(
 5163   sqlite3 *db,
 5164   const void *zFunctionName,
 5165   int nArg,
 5166   int eTextRep,
 5167   void *pApp,
 5168   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
 5169   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
 5170   void (*xFinal)(sqlite3_context*)
 5171 );
 5172 SQLITE_API int sqlite3_create_function_v2(
 5173   sqlite3 *db,
 5174   const char *zFunctionName,
 5175   int nArg,
 5176   int eTextRep,
 5177   void *pApp,
 5178   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
 5179   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
 5180   void (*xFinal)(sqlite3_context*),
 5181   void(*xDestroy)(void*)
 5182 );
 5183 SQLITE_API int sqlite3_create_window_function(
 5184   sqlite3 *db,
 5185   const char *zFunctionName,
 5186   int nArg,
 5187   int eTextRep,
 5188   void *pApp,
 5189   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
 5190   void (*xFinal)(sqlite3_context*),
 5191   void (*xValue)(sqlite3_context*),
 5192   void (*xInverse)(sqlite3_context*,int,sqlite3_value**),
 5193   void(*xDestroy)(void*)
 5194 );
 5195 
 5196 /*
 5197 ** CAPI3REF: Text Encodings
 5198 **
 5199 ** These constant define integer codes that represent the various
 5200 ** text encodings supported by SQLite.
 5201 */
 5202 #define SQLITE_UTF8           1    /* IMP: R-37514-35566 */
 5203 #define SQLITE_UTF16LE        2    /* IMP: R-03371-37637 */
 5204 #define SQLITE_UTF16BE        3    /* IMP: R-51971-34154 */
 5205 #define SQLITE_UTF16          4    /* Use native byte order */
 5206 #define SQLITE_ANY            5    /* Deprecated */
 5207 #define SQLITE_UTF16_ALIGNED  8    /* sqlite3_create_collation only */
 5208 
 5209 /*
 5210 ** CAPI3REF: Function Flags
 5211 **
 5212 ** These constants may be ORed together with the 
 5213 ** [SQLITE_UTF8 | preferred text encoding] as the fourth argument
 5214 ** to [sqlite3_create_function()], [sqlite3_create_function16()], or
 5215 ** [sqlite3_create_function_v2()].
 5216 **
 5217 ** <dl>
 5218 ** [[SQLITE_DETERMINISTIC]] <dt>SQLITE_DETERMINISTIC</dt><dd>
 5219 ** The SQLITE_DETERMINISTIC flag means that the new function always gives
 5220 ** the same output when the input parameters are the same.
 5221 ** The [abs|abs() function] is deterministic, for example, but
 5222 ** [randomblob|randomblob()] is not.  Functions must
 5223 ** be deterministic in order to be used in certain contexts such as
 5224 ** with the WHERE clause of [partial indexes] or in [generated columns].
 5225 ** SQLite might also optimize deterministic functions by factoring them
 5226 ** out of inner loops.
 5227 ** </dd>
 5228 ** 
 5229 ** [[SQLITE_DIRECTONLY]] <dt>SQLITE_DIRECTONLY</dt><dd>
 5230 ** The SQLITE_DIRECTONLY flag means that the function may only be invoked
 5231 ** from top-level SQL, and cannot be used in VIEWs or TRIGGERs nor in 
 5232 ** schema structures such as [CHECK constraints], [DEFAULT clauses],
 5233 ** [expression indexes], [partial indexes], or [generated columns].
 5234 ** The SQLITE_DIRECTONLY flags is a security feature which is recommended
 5235 ** for all [application-defined SQL functions], and especially for functions
 5236 ** that have side-effects or that could potentially leak sensitive
 5237 ** information.
 5238 ** </dd>
 5239 **
 5240 ** [[SQLITE_INNOCUOUS]] <dt>SQLITE_INNOCUOUS</dt><dd>
 5241 ** The SQLITE_INNOCUOUS flag means that the function is unlikely
 5242 ** to cause problems even if misused.  An innocuous function should have
 5243 ** no side effects and should not depend on any values other than its
 5244 ** input parameters. The [abs|abs() function] is an example of an
 5245 ** innocuous function.
 5246 ** The [load_extension() SQL function] is not innocuous because of its
 5247 ** side effects.
 5248 ** <p> SQLITE_INNOCUOUS is similar to SQLITE_DETERMINISTIC, but is not
 5249 ** exactly the same.  The [random|random() function] is an example of a
 5250 ** function that is innocuous but not deterministic.
 5251 ** <p>Some heightened security settings
 5252 ** ([SQLITE_DBCONFIG_TRUSTED_SCHEMA] and [PRAGMA trusted_schema=OFF])
 5253 ** disable the use of SQL functions inside views and triggers and in
 5254 ** schema structures such as [CHECK constraints], [DEFAULT clauses],
 5255 ** [expression indexes], [partial indexes], and [generated columns] unless
 5256 ** the function is tagged with SQLITE_INNOCUOUS.  Most built-in functions
 5257 ** are innocuous.  Developers are advised to avoid using the
 5258 ** SQLITE_INNOCUOUS flag for application-defined functions unless the
 5259 ** function has been carefully audited and found to be free of potentially
 5260 ** security-adverse side-effects and information-leaks.
 5261 ** </dd>
 5262 **
 5263 ** [[SQLITE_SUBTYPE]] <dt>SQLITE_SUBTYPE</dt><dd>
 5264 ** The SQLITE_SUBTYPE flag indicates to SQLite that a function may call
 5265 ** [sqlite3_value_subtype()] to inspect the sub-types of its arguments.
 5266 ** Specifying this flag makes no difference for scalar or aggregate user
 5267 ** functions. However, if it is not specified for a user-defined window
 5268 ** function, then any sub-types belonging to arguments passed to the window
 5269 ** function may be discarded before the window function is called (i.e.
 5270 ** sqlite3_value_subtype() will always return 0).
 5271 ** </dd>
 5272 ** </dl>
 5273 */
 5274 #define SQLITE_DETERMINISTIC    0x000000800
 5275 #define SQLITE_DIRECTONLY       0x000080000
 5276 #define SQLITE_SUBTYPE          0x000100000
 5277 #define SQLITE_INNOCUOUS        0x000200000
 5278 
 5279 /*
 5280 ** CAPI3REF: Deprecated Functions
 5281 ** DEPRECATED
 5282 **
 5283 ** These functions are [deprecated].  In order to maintain
 5284 ** backwards compatibility with older code, these functions continue 
 5285 ** to be supported.  However, new applications should avoid
 5286 ** the use of these functions.  To encourage programmers to avoid
 5287 ** these functions, we will not explain what they do.
 5288 */
 5289 #ifndef SQLITE_OMIT_DEPRECATED
 5290 SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
 5291 SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
 5292 SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
 5293 SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);
 5294 SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
 5295 SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),
 5296                       void*,sqlite3_int64);
 5297 #endif
 5298 
 5299 /*
 5300 ** CAPI3REF: Obtaining SQL Values
 5301 ** METHOD: sqlite3_value
 5302 **
 5303 ** <b>Summary:</b>
 5304 ** <blockquote><table border=0 cellpadding=0 cellspacing=0>
 5305 ** <tr><td><b>sqlite3_value_blob</b><td>&rarr;<td>BLOB value
 5306 ** <tr><td><b>sqlite3_value_double</b><td>&rarr;<td>REAL value
 5307 ** <tr><td><b>sqlite3_value_int</b><td>&rarr;<td>32-bit INTEGER value
 5308 ** <tr><td><b>sqlite3_value_int64</b><td>&rarr;<td>64-bit INTEGER value
 5309 ** <tr><td><b>sqlite3_value_pointer</b><td>&rarr;<td>Pointer value
 5310 ** <tr><td><b>sqlite3_value_text</b><td>&rarr;<td>UTF-8 TEXT value
 5311 ** <tr><td><b>sqlite3_value_text16</b><td>&rarr;<td>UTF-16 TEXT value in
 5312 ** the native byteorder
 5313 ** <tr><td><b>sqlite3_value_text16be</b><td>&rarr;<td>UTF-16be TEXT value
 5314 ** <tr><td><b>sqlite3_value_text16le</b><td>&rarr;<td>UTF-16le TEXT value
 5315 ** <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
 5316 ** <tr><td><b>sqlite3_value_bytes</b><td>&rarr;<td>Size of a BLOB
 5317 ** or a UTF-8 TEXT in bytes
 5318 ** <tr><td><b>sqlite3_value_bytes16&nbsp;&nbsp;</b>
 5319 ** <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
 5320 ** TEXT in bytes
 5321 ** <tr><td><b>sqlite3_value_type</b><td>&rarr;<td>Default
 5322 ** datatype of the value
 5323 ** <tr><td><b>sqlite3_value_numeric_type&nbsp;&nbsp;</b>
 5324 ** <td>&rarr;&nbsp;&nbsp;<td>Best numeric datatype of the value
 5325 ** <tr><td><b>sqlite3_value_nochange&nbsp;&nbsp;</b>
 5326 ** <td>&rarr;&nbsp;&nbsp;<td>True if the column is unchanged in an UPDATE
 5327 ** against a virtual table.
 5328 ** <tr><td><b>sqlite3_value_frombind&nbsp;&nbsp;</b>
 5329 ** <td>&rarr;&nbsp;&nbsp;<td>True if value originated from a [bound parameter]
 5330 ** </table></blockquote>
 5331 **
 5332 ** <b>Details:</b>
 5333 **
 5334 ** These routines extract type, size, and content information from
 5335 ** [protected sqlite3_value] objects.  Protected sqlite3_value objects
 5336 ** are used to pass parameter information into the functions that
 5337 ** implement [application-defined SQL functions] and [virtual tables].
 5338 **
 5339 ** These routines work only with [protected sqlite3_value] objects.
 5340 ** Any attempt to use these routines on an [unprotected sqlite3_value]
 5341 ** is not threadsafe.
 5342 **
 5343 ** ^These routines work just like the corresponding [column access functions]
 5344 ** except that these routines take a single [protected sqlite3_value] object
 5345 ** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
 5346 **
 5347 ** ^The sqlite3_value_text16() interface extracts a UTF-16 string
 5348 ** in the native byte-order of the host machine.  ^The
 5349 ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
 5350 ** extract UTF-16 strings as big-endian and little-endian respectively.
 5351 **
 5352 ** ^If [sqlite3_value] object V was initialized 
 5353 ** using [sqlite3_bind_pointer(S,I,P,X,D)] or [sqlite3_result_pointer(C,P,X,D)]
 5354 ** and if X and Y are strings that compare equal according to strcmp(X,Y),
 5355 ** then sqlite3_value_pointer(V,Y) will return the pointer P.  ^Otherwise,
 5356 ** sqlite3_value_pointer(V,Y) returns a NULL. The sqlite3_bind_pointer() 
 5357 ** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
 5358 **
 5359 ** ^(The sqlite3_value_type(V) interface returns the
 5360 ** [SQLITE_INTEGER | datatype code] for the initial datatype of the
 5361 ** [sqlite3_value] object V. The returned value is one of [SQLITE_INTEGER],
 5362 ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].)^
 5363 ** Other interfaces might change the datatype for an sqlite3_value object.
 5364 ** For example, if the datatype is initially SQLITE_INTEGER and
 5365 ** sqlite3_value_text(V) is called to extract a text value for that
 5366 ** integer, then subsequent calls to sqlite3_value_type(V) might return
 5367 ** SQLITE_TEXT.  Whether or not a persistent internal datatype conversion
 5368 ** occurs is undefined and may change from one release of SQLite to the next.
 5369 **
 5370 ** ^(The sqlite3_value_numeric_type() interface attempts to apply
 5371 ** numeric affinity to the value.  This means that an attempt is
 5372 ** made to convert the value to an integer or floating point.  If
 5373 ** such a conversion is possible without loss of information (in other
 5374 ** words, if the value is a string that looks like a number)
 5375 ** then the conversion is performed.  Otherwise no conversion occurs.
 5376 ** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
 5377 **
 5378 ** ^Within the [xUpdate] method of a [virtual table], the
 5379 ** sqlite3_value_nochange(X) interface returns true if and only if
 5380 ** the column corresponding to X is unchanged by the UPDATE operation
 5381 ** that the xUpdate method call was invoked to implement and if
 5382 ** and the prior [xColumn] method call that was invoked to extracted
 5383 ** the value for that column returned without setting a result (probably
 5384 ** because it queried [sqlite3_vtab_nochange()] and found that the column
 5385 ** was unchanging).  ^Within an [xUpdate] method, any value for which
 5386 ** sqlite3_value_nochange(X) is true will in all other respects appear
 5387 ** to be a NULL value.  If sqlite3_value_nochange(X) is invoked anywhere other
 5388 ** than within an [xUpdate] method call for an UPDATE statement, then
 5389 ** the return value is arbitrary and meaningless.
 5390 **
 5391 ** ^The sqlite3_value_frombind(X) interface returns non-zero if the
 5392 ** value X originated from one of the [sqlite3_bind_int|sqlite3_bind()]
 5393 ** interfaces.  ^If X comes from an SQL literal value, or a table column,
 5394 ** or an expression, then sqlite3_value_frombind(X) returns zero.
 5395 **
 5396 ** Please pay particular attention to the fact that the pointer returned
 5397 ** from [sqlite3_value_blob()], [sqlite3_value_text()], or
 5398 ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
 5399 ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
 5400 ** or [sqlite3_value_text16()].
 5401 **
 5402 ** These routines must be called from the same thread as
 5403 ** the SQL function that supplied the [sqlite3_value*] parameters.
 5404 **
 5405 ** As long as the input parameter is correct, these routines can only
 5406 ** fail if an out-of-memory error occurs during a format conversion.
 5407 ** Only the following subset of interfaces are subject to out-of-memory
 5408 ** errors:
 5409 **
 5410 ** <ul>
 5411 ** <li> sqlite3_value_blob()
 5412 ** <li> sqlite3_value_text()
 5413 ** <li> sqlite3_value_text16()
 5414 ** <li> sqlite3_value_text16le()
 5415 ** <li> sqlite3_value_text16be()
 5416 ** <li> sqlite3_value_bytes()
 5417 ** <li> sqlite3_value_bytes16()
 5418 ** </ul>
 5419 **
 5420 ** If an out-of-memory error occurs, then the return value from these
 5421 ** routines is the same as if the column had contained an SQL NULL value.
 5422 ** Valid SQL NULL returns can be distinguished from out-of-memory errors
 5423 ** by invoking the [sqlite3_errcode()] immediately after the suspect
 5424 ** return value is obtained and before any
 5425 ** other SQLite interface is called on the same [database connection].
 5426 */
 5427 SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
 5428 SQLITE_API double sqlite3_value_double(sqlite3_value*);
 5429 SQLITE_API int sqlite3_value_int(sqlite3_value*);
 5430 SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
 5431 SQLITE_API void *sqlite3_value_pointer(sqlite3_value*, const char*);
 5432 SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*);
 5433 SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);
 5434 SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
 5435 SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
 5436 SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
 5437 SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
 5438 SQLITE_API int sqlite3_value_type(sqlite3_value*);
 5439 SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
 5440 SQLITE_API int sqlite3_value_nochange(sqlite3_value*);
 5441 SQLITE_API int sqlite3_value_frombind(sqlite3_value*);
 5442 
 5443 /*
 5444 ** CAPI3REF: Finding The Subtype Of SQL Values
 5445 ** METHOD: sqlite3_value
 5446 **
 5447 ** The sqlite3_value_subtype(V) function returns the subtype for
 5448 ** an [application-defined SQL function] argument V.  The subtype
 5449 ** information can be used to pass a limited amount of context from
 5450 ** one SQL function to another.  Use the [sqlite3_result_subtype()]
 5451 ** routine to set the subtype for the return value of an SQL function.
 5452 */
 5453 SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*);
 5454 
 5455 /*
 5456 ** CAPI3REF: Copy And Free SQL Values
 5457 ** METHOD: sqlite3_value
 5458 **
 5459 ** ^The sqlite3_value_dup(V) interface makes a copy of the [sqlite3_value]
 5460 ** object D and returns a pointer to that copy.  ^The [sqlite3_value] returned
 5461 ** is a [protected sqlite3_value] object even if the input is not.
 5462 ** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a
 5463 ** memory allocation fails.
 5464 **
 5465 ** ^The sqlite3_value_free(V) interface frees an [sqlite3_value] object
 5466 ** previously obtained from [sqlite3_value_dup()].  ^If V is a NULL pointer
 5467 ** then sqlite3_value_free(V) is a harmless no-op.
 5468 */
 5469 SQLITE_API sqlite3_value *sqlite3_value_dup(const sqlite3_value*);
 5470 SQLITE_API void sqlite3_value_free(sqlite3_value*);
 5471 
 5472 /*
 5473 ** CAPI3REF: Obtain Aggregate Function Context
 5474 ** METHOD: sqlite3_context
 5475 **
 5476 ** Implementations of aggregate SQL functions use this
 5477 ** routine to allocate memory for storing their state.
 5478 **
 5479 ** ^The first time the sqlite3_aggregate_context(C,N) routine is called 
 5480 ** for a particular aggregate function, SQLite allocates
 5481 ** N bytes of memory, zeroes out that memory, and returns a pointer
 5482 ** to the new memory. ^On second and subsequent calls to
 5483 ** sqlite3_aggregate_context() for the same aggregate function instance,
 5484 ** the same buffer is returned.  Sqlite3_aggregate_context() is normally
 5485 ** called once for each invocation of the xStep callback and then one
 5486 ** last time when the xFinal callback is invoked.  ^(When no rows match
 5487 ** an aggregate query, the xStep() callback of the aggregate function
 5488 ** implementation is never called and xFinal() is called exactly once.
 5489 ** In those cases, sqlite3_aggregate_context() might be called for the
 5490 ** first time from within xFinal().)^
 5491 **
 5492 ** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer 
 5493 ** when first called if N is less than or equal to zero or if a memory
 5494 ** allocate error occurs.
 5495 **
 5496 ** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
 5497 ** determined by the N parameter on first successful call.  Changing the
 5498 ** value of N in any subsequent call to sqlite3_aggregate_context() within
 5499 ** the same aggregate function instance will not resize the memory
 5500 ** allocation.)^  Within the xFinal callback, it is customary to set
 5501 ** N=0 in calls to sqlite3_aggregate_context(C,N) so that no 
 5502 ** pointless memory allocations occur.
 5503 **
 5504 ** ^SQLite automatically frees the memory allocated by 
 5505 ** sqlite3_aggregate_context() when the aggregate query concludes.
 5506 **
 5507 ** The first parameter must be a copy of the
 5508 ** [sqlite3_context | SQL function context] that is the first parameter
 5509 ** to the xStep or xFinal callback routine that implements the aggregate
 5510 ** function.
 5511 **
 5512 ** This routine must be called from the same thread in which
 5513 ** the aggregate SQL function is running.
 5514 */
 5515 SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
 5516 
 5517 /*
 5518 ** CAPI3REF: User Data For Functions
 5519 ** METHOD: sqlite3_context
 5520 **
 5521 ** ^The sqlite3_user_data() interface returns a copy of
 5522 ** the pointer that was the pUserData parameter (the 5th parameter)
 5523 ** of the [sqlite3_create_function()]
 5524 ** and [sqlite3_create_function16()] routines that originally
 5525 ** registered the application defined function.
 5526 **
 5527 ** This routine must be called from the same thread in which
 5528 ** the application-defined function is running.
 5529 */
 5530 SQLITE_API void *sqlite3_user_data(sqlite3_context*);
 5531 
 5532 /*
 5533 ** CAPI3REF: Database Connection For Functions
 5534 ** METHOD: sqlite3_context
 5535 **
 5536 ** ^The sqlite3_context_db_handle() interface returns a copy of
 5537 ** the pointer to the [database connection] (the 1st parameter)
 5538 ** of the [sqlite3_create_function()]
 5539 ** and [sqlite3_create_function16()] routines that originally
 5540 ** registered the application defined function.
 5541 */
 5542 SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
 5543 
 5544 /*
 5545 ** CAPI3REF: Function Auxiliary Data
 5546 ** METHOD: sqlite3_context
 5547 **
 5548 ** These functions may be used by (non-aggregate) SQL functions to
 5549 ** associate metadata with argument values. If the same value is passed to
 5550 ** multiple invocations of the same SQL function during query execution, under
 5551 ** some circumstances the associated metadata may be preserved.  An example
 5552 ** of where this might be useful is in a regular-expression matching
 5553 ** function. The compiled version of the regular expression can be stored as
 5554 ** metadata associated with the pattern string.  
 5555 ** Then as long as the pattern string remains the same,
 5556 ** the compiled regular expression can be reused on multiple
 5557 ** invocations of the same function.
 5558 **
 5559 ** ^The sqlite3_get_auxdata(C,N) interface returns a pointer to the metadata
 5560 ** associated by the sqlite3_set_auxdata(C,N,P,X) function with the Nth argument
 5561 ** value to the application-defined function.  ^N is zero for the left-most
 5562 ** function argument.  ^If there is no metadata
 5563 ** associated with the function argument, the sqlite3_get_auxdata(C,N) interface
 5564 ** returns a NULL pointer.
 5565 **
 5566 ** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th
 5567 ** argument of the application-defined function.  ^Subsequent
 5568 ** calls to sqlite3_get_auxdata(C,N) return P from the most recent
 5569 ** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or
 5570 ** NULL if the metadata has been discarded.
 5571 ** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
 5572 ** SQLite will invoke the destructor function X with parameter P exactly
 5573 ** once, when the metadata is discarded.
 5574 ** SQLite is free to discard the metadata at any time, including: <ul>
 5575 ** <li> ^(when the corresponding function parameter changes)^, or
 5576 ** <li> ^(when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
 5577 **      SQL statement)^, or
 5578 ** <li> ^(when sqlite3_set_auxdata() is invoked again on the same
 5579 **       parameter)^, or
 5580 ** <li> ^(during the original sqlite3_set_auxdata() call when a memory 
 5581 **      allocation error occurs.)^ </ul>
 5582 **
 5583 ** Note the last bullet in particular.  The destructor X in 
 5584 ** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the
 5585 ** sqlite3_set_auxdata() interface even returns.  Hence sqlite3_set_auxdata()
 5586 ** should be called near the end of the function implementation and the
 5587 ** function implementation should not make any use of P after
 5588 ** sqlite3_set_auxdata() has been called.
 5589 **
 5590 ** ^(In practice, metadata is preserved between function calls for
 5591 ** function parameters that are compile-time constants, including literal
 5592 ** values and [parameters] and expressions composed from the same.)^
 5593 **
 5594 ** The value of the N parameter to these interfaces should be non-negative.
 5595 ** Future enhancements may make use of negative N values to define new
 5596 ** kinds of function caching behavior.
 5597 **
 5598 ** These routines must be called from the same thread in which
 5599 ** the SQL function is running.
 5600 */
 5601 SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
 5602 SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
 5603 
 5604 
 5605 /*
 5606 ** CAPI3REF: Constants Defining Special Destructor Behavior
 5607 **
 5608 ** These are special values for the destructor that is passed in as the
 5609 ** final argument to routines like [sqlite3_result_blob()].  ^If the destructor
 5610 ** argument is SQLITE_STATIC, it means that the content pointer is constant
 5611 ** and will never change.  It does not need to be destroyed.  ^The
 5612 ** SQLITE_TRANSIENT value means that the content will likely change in
 5613 ** the near future and that SQLite should make its own private copy of
 5614 ** the content before returning.
 5615 **
 5616 ** The typedef is necessary to work around problems in certain
 5617 ** C++ compilers.
 5618 */
 5619 typedef void (*sqlite3_destructor_type)(void*);
 5620 #define SQLITE_STATIC      ((sqlite3_destructor_type)0)
 5621 #define SQLITE_TRANSIENT   ((sqlite3_destructor_type)-1)
 5622 
 5623 /*
 5624 ** CAPI3REF: Setting The Result Of An SQL Function
 5625 ** METHOD: sqlite3_context
 5626 **
 5627 ** These routines are used by the xFunc or xFinal callbacks that
 5628 ** implement SQL functions and aggregates.  See
 5629 ** [sqlite3_create_function()] and [sqlite3_create_function16()]
 5630 ** for additional information.
 5631 **
 5632 ** These functions work very much like the [parameter binding] family of
 5633 ** functions used to bind values to host parameters in prepared statements.
 5634 ** Refer to the [SQL parameter] documentation for additional information.
 5635 **
 5636 ** ^The sqlite3_result_blob() interface sets the result from
 5637 ** an application-defined function to be the BLOB whose content is pointed
 5638 ** to by the second parameter and which is N bytes long where N is the
 5639 ** third parameter.
 5640 **
 5641 ** ^The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N)
 5642 ** interfaces set the result of the application-defined function to be
 5643 ** a BLOB containing all zero bytes and N bytes in size.
 5644 **
 5645 ** ^The sqlite3_result_double() interface sets the result from
 5646 ** an application-defined function to be a floating point value specified
 5647 ** by its 2nd argument.
 5648 **
 5649 ** ^The sqlite3_result_error() and sqlite3_result_error16() functions
 5650 ** cause the implemented SQL function to throw an exception.
 5651 ** ^SQLite uses the string pointed to by the
 5652 ** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
 5653 ** as the text of an error message.  ^SQLite interprets the error
 5654 ** message string from sqlite3_result_error() as UTF-8. ^SQLite
 5655 ** interprets the string from sqlite3_result_error16() as UTF-16 using
 5656 ** the same [byte-order determination rules] as [sqlite3_bind_text16()].
 5657 ** ^If the third parameter to sqlite3_result_error()
 5658 ** or sqlite3_result_error16() is negative then SQLite takes as the error
 5659 ** message all text up through the first zero character.
 5660 ** ^If the third parameter to sqlite3_result_error() or
 5661 ** sqlite3_result_error16() is non-negative then SQLite takes that many
 5662 ** bytes (not characters) from the 2nd parameter as the error message.
 5663 ** ^The sqlite3_result_error() and sqlite3_result_error16()
 5664 ** routines make a private copy of the error message text before
 5665 ** they return.  Hence, the calling function can deallocate or
 5666 ** modify the text after they return without harm.
 5667 ** ^The sqlite3_result_error_code() function changes the error code
 5668 ** returned by SQLite as a result of an error in a function.  ^By default,
 5669 ** the error code is SQLITE_ERROR.  ^A subsequent call to sqlite3_result_error()
 5670 ** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
 5671 **
 5672 ** ^The sqlite3_result_error_toobig() interface causes SQLite to throw an
 5673 ** error indicating that a string or BLOB is too long to represent.
 5674 **
 5675 ** ^The sqlite3_result_error_nomem() interface causes SQLite to throw an
 5676 ** error indicating that a memory allocation failed.
 5677 **
 5678 ** ^The sqlite3_result_int() interface sets the return value
 5679 ** of the application-defined function to be the 32-bit signed integer
 5680 ** value given in the 2nd argument.
 5681 ** ^The sqlite3_result_int64() interface sets the return value
 5682 ** of the application-defined function to be the 64-bit signed integer
 5683 ** value given in the 2nd argument.
 5684 **
 5685 ** ^The sqlite3_result_null() interface sets the return value
 5686 ** of the application-defined function to be NULL.
 5687 **
 5688 ** ^The sqlite3_result_text(), sqlite3_result_text16(),
 5689 ** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
 5690 ** set the return value of the application-defined function to be
 5691 ** a text string which is represented as UTF-8, UTF-16 native byte order,
 5692 ** UTF-16 little endian, or UTF-16 big endian, respectively.
 5693 ** ^The sqlite3_result_text64() interface sets the return value of an
 5694 ** application-defined function to be a text string in an encoding
 5695 ** specified by the fifth (and last) parameter, which must be one
 5696 ** of [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE].
 5697 ** ^SQLite takes the text result from the application from
 5698 ** the 2nd parameter of the sqlite3_result_text* interfaces.
 5699 ** ^If the 3rd parameter to the sqlite3_result_text* interfaces
 5700 ** is negative, then SQLite takes result text from the 2nd parameter
 5701 ** through the first zero character.
 5702 ** ^If the 3rd parameter to the sqlite3_result_text* interfaces
 5703 ** is non-negative, then as many bytes (not characters) of the text
 5704 ** pointed to by the 2nd parameter are taken as the application-defined
 5705 ** function result.  If the 3rd parameter is non-negative, then it
 5706 ** must be the byte offset into the string where the NUL terminator would
 5707 ** appear if the string where NUL terminated.  If any NUL characters occur
 5708 ** in the string at a byte offset that is less than the value of the 3rd
 5709 ** parameter, then the resulting string will contain embedded NULs and the
 5710 ** result of expressions operating on strings with embedded NULs is undefined.
 5711 ** ^If the 4th parameter to the sqlite3_result_text* interfaces
 5712 ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
 5713 ** function as the destructor on the text or BLOB result when it has
 5714 ** finished using that result.
 5715 ** ^If the 4th parameter to the sqlite3_result_text* interfaces or to
 5716 ** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
 5717 ** assumes that the text or BLOB result is in constant space and does not
 5718 ** copy the content of the parameter nor call a destructor on the content
 5719 ** when it has finished using that result.
 5720 ** ^If the 4th parameter to the sqlite3_result_text* interfaces
 5721 ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
 5722 ** then SQLite makes a copy of the result into space obtained
 5723 ** from [sqlite3_malloc()] before it returns.
 5724 **
 5725 ** ^For the sqlite3_result_text16(), sqlite3_result_text16le(), and
 5726 ** sqlite3_result_text16be() routines, and for sqlite3_result_text64()
 5727 ** when the encoding is not UTF8, if the input UTF16 begins with a
 5728 ** byte-order mark (BOM, U+FEFF) then the BOM is removed from the
 5729 ** string and the rest of the string is interpreted according to the
 5730 ** byte-order specified by the BOM.  ^The byte-order specified by
 5731 ** the BOM at the beginning of the text overrides the byte-order
 5732 ** specified by the interface procedure.  ^So, for example, if
 5733 ** sqlite3_result_text16le() is invoked with text that begins
 5734 ** with bytes 0xfe, 0xff (a big-endian byte-order mark) then the
 5735 ** first two bytes of input are skipped and the remaining input
 5736 ** is interpreted as UTF16BE text.
 5737 **
 5738 ** ^For UTF16 input text to the sqlite3_result_text16(),
 5739 ** sqlite3_result_text16be(), sqlite3_result_text16le(), and
 5740 ** sqlite3_result_text64() routines, if the text contains invalid
 5741 ** UTF16 characters, the invalid characters might be converted
 5742 ** into the unicode replacement character, U+FFFD.
 5743 **
 5744 ** ^The sqlite3_result_value() interface sets the result of
 5745 ** the application-defined function to be a copy of the
 5746 ** [unprotected sqlite3_value] object specified by the 2nd parameter.  ^The
 5747 ** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
 5748 ** so that the [sqlite3_value] specified in the parameter may change or
 5749 ** be deallocated after sqlite3_result_value() returns without harm.
 5750 ** ^A [protected sqlite3_value] object may always be used where an
 5751 ** [unprotected sqlite3_value] object is required, so either
 5752 ** kind of [sqlite3_value] object can be used with this interface.
 5753 **
 5754 ** ^The sqlite3_result_pointer(C,P,T,D) interface sets the result to an
 5755 ** SQL NULL value, just like [sqlite3_result_null(C)], except that it
 5756 ** also associates the host-language pointer P or type T with that 
 5757 ** NULL value such that the pointer can be retrieved within an
 5758 ** [application-defined SQL function] using [sqlite3_value_pointer()].
 5759 ** ^If the D parameter is not NULL, then it is a pointer to a destructor
 5760 ** for the P parameter.  ^SQLite invokes D with P as its only argument
 5761 ** when SQLite is finished with P.  The T parameter should be a static
 5762 ** string and preferably a string literal. The sqlite3_result_pointer()
 5763 ** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
 5764 **
 5765 ** If these routines are called from within the different thread
 5766 ** than the one containing the application-defined function that received
 5767 ** the [sqlite3_context] pointer, the results are undefined.
 5768 */
 5769 SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
 5770 SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*,
 5771                            sqlite3_uint64,void(*)(void*));
 5772 SQLITE_API void sqlite3_result_double(sqlite3_context*, double);
 5773 SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);
 5774 SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);
 5775 SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*);
 5776 SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*);
 5777 SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int);
 5778 SQLITE_API void sqlite3_result_int(sqlite3_context*, int);
 5779 SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
 5780 SQLITE_API void sqlite3_result_null(sqlite3_context*);
 5781 SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
 5782 SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64,
 5783                            void(*)(void*), unsigned char encoding);
 5784 SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
 5785 SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
 5786 SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
 5787 SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
 5788 SQLITE_API void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*));
 5789 SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
 5790 SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);
 5791 
 5792 
 5793 /*
 5794 ** CAPI3REF: Setting The Subtype Of An SQL Function
 5795 ** METHOD: sqlite3_context
 5796 **
 5797 ** The sqlite3_result_subtype(C,T) function causes the subtype of
 5798 ** the result from the [application-defined SQL function] with 
 5799 ** [sqlite3_context] C to be the value T.  Only the lower 8 bits 
 5800 ** of the subtype T are preserved in current versions of SQLite;
 5801 ** higher order bits are discarded.
 5802 ** The number of subtype bytes preserved by SQLite might increase
 5803 ** in future releases of SQLite.
 5804 */
 5805 SQLITE_API void sqlite3_result_subtype(sqlite3_context*,unsigned int);
 5806 
 5807 /*
 5808 ** CAPI3REF: Define New Collating Sequences
 5809 ** METHOD: sqlite3
 5810 **
 5811 ** ^These functions add, remove, or modify a [collation] associated
 5812 ** with the [database connection] specified as the first argument.
 5813 **
 5814 ** ^The name of the collation is a UTF-8 string
 5815 ** for sqlite3_create_collation() and sqlite3_create_collation_v2()
 5816 ** and a UTF-16 string in native byte order for sqlite3_create_collation16().
 5817 ** ^Collation names that compare equal according to [sqlite3_strnicmp()] are
 5818 ** considered to be the same name.
 5819 **
 5820 ** ^(The third argument (eTextRep) must be one of the constants:
 5821 ** <ul>
 5822 ** <li> [SQLITE_UTF8],
 5823 ** <li> [SQLITE_UTF16LE],
 5824 ** <li> [SQLITE_UTF16BE],
 5825 ** <li> [SQLITE_UTF16], or
 5826 ** <li> [SQLITE_UTF16_ALIGNED].
 5827 ** </ul>)^
 5828 ** ^The eTextRep argument determines the encoding of strings passed
 5829 ** to the collating function callback, xCompare.
 5830 ** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep
 5831 ** force strings to be UTF16 with native byte order.
 5832 ** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin
 5833 ** on an even byte address.
 5834 **
 5835 ** ^The fourth argument, pArg, is an application data pointer that is passed
 5836 ** through as the first argument to the collating function callback.
 5837 **
 5838 ** ^The fifth argument, xCompare, is a pointer to the collating function.
 5839 ** ^Multiple collating functions can be registered using the same name but
 5840 ** with different eTextRep parameters and SQLite will use whichever
 5841 ** function requires the least amount of data transformation.
 5842 ** ^If the xCompare argument is NULL then the collating function is
 5843 ** deleted.  ^When all collating functions having the same name are deleted,
 5844 ** that collation is no longer usable.
 5845 **
 5846 ** ^The collating function callback is invoked with a copy of the pArg 
 5847 ** application data pointer and with two strings in the encoding specified
 5848 ** by the eTextRep argument.  The two integer parameters to the collating
 5849 ** function callback are the length of the two strings, in bytes. The collating
 5850 ** function must return an integer that is negative, zero, or positive
 5851 ** if the first string is less than, equal to, or greater than the second,
 5852 ** respectively.  A collating function must always return the same answer
 5853 ** given the same inputs.  If two or more collating functions are registered
 5854 ** to the same collation name (using different eTextRep values) then all
 5855 ** must give an equivalent answer when invoked with equivalent strings.
 5856 ** The collating function must obey the following properties for all
 5857 ** strings A, B, and C:
 5858 **
 5859 ** <ol>
 5860 ** <li> If A==B then B==A.
 5861 ** <li> If A==B and B==C then A==C.
 5862 ** <li> If A&lt;B THEN B&gt;A.
 5863 ** <li> If A&lt;B and B&lt;C then A&lt;C.
 5864 ** </ol>
 5865 **
 5866 ** If a collating function fails any of the above constraints and that
 5867 ** collating function is registered and used, then the behavior of SQLite
 5868 ** is undefined.
 5869 **
 5870 ** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation()
 5871 ** with the addition that the xDestroy callback is invoked on pArg when
 5872 ** the collating function is deleted.
 5873 ** ^Collating functions are deleted when they are overridden by later
 5874 ** calls to the collation creation functions or when the
 5875 ** [database connection] is closed using [sqlite3_close()].
 5876 **
 5877 ** ^The xDestroy callback is <u>not</u> called if the 
 5878 ** sqlite3_create_collation_v2() function fails.  Applications that invoke
 5879 ** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should 
 5880 ** check the return code and dispose of the application data pointer
 5881 ** themselves rather than expecting SQLite to deal with it for them.
 5882 ** This is different from every other SQLite interface.  The inconsistency 
 5883 ** is unfortunate but cannot be changed without breaking backwards 
 5884 ** compatibility.
 5885 **
 5886 ** See also:  [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
 5887 */
 5888 SQLITE_API int sqlite3_create_collation(
 5889   sqlite3*, 
 5890   const char *zName, 
 5891   int eTextRep, 
 5892   void *pArg,
 5893   int(*xCompare)(void*,int,const void*,int,const void*)
 5894 );
 5895 SQLITE_API int sqlite3_create_collation_v2(
 5896   sqlite3*, 
 5897   const char *zName, 
 5898   int eTextRep, 
 5899   void *pArg,
 5900   int(*xCompare)(void*,int,const void*,int,const void*),
 5901   void(*xDestroy)(void*)
 5902 );
 5903 SQLITE_API int sqlite3_create_collation16(
 5904   sqlite3*, 
 5905   const void *zName,
 5906   int eTextRep, 
 5907   void *pArg,
 5908   int(*xCompare)(void*,int,const void*,int,const void*)
 5909 );
 5910 
 5911 /*
 5912 ** CAPI3REF: Collation Needed Callbacks
 5913 ** METHOD: sqlite3
 5914 **
 5915 ** ^To avoid having to register all collation sequences before a database
 5916 ** can be used, a single callback function may be registered with the
 5917 ** [database connection] to be invoked whenever an undefined collation
 5918 ** sequence is required.
 5919 **
 5920 ** ^If the function is registered using the sqlite3_collation_needed() API,
 5921 ** then it is passed the names of undefined collation sequences as strings
 5922 ** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
 5923 ** the names are passed as UTF-16 in machine native byte order.
 5924 ** ^A call to either function replaces the existing collation-needed callback.
 5925 **
 5926 ** ^(When the callback is invoked, the first argument passed is a copy
 5927 ** of the second argument to sqlite3_collation_needed() or
 5928 ** sqlite3_collation_needed16().  The second argument is the database
 5929 ** connection.  The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
 5930 ** or [SQLITE_UTF16LE], indicating the most desirable form of the collation
 5931 ** sequence function required.  The fourth parameter is the name of the
 5932 ** required collation sequence.)^
 5933 **
 5934 ** The callback function should register the desired collation using
 5935 ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
 5936 ** [sqlite3_create_collation_v2()].
 5937 */
 5938 SQLITE_API int sqlite3_collation_needed(
 5939   sqlite3*, 
 5940   void*, 
 5941   void(*)(void*,sqlite3*,int eTextRep,const char*)
 5942 );
 5943 SQLITE_API int sqlite3_collation_needed16(
 5944   sqlite3*, 
 5945   void*,
 5946   void(*)(void*,sqlite3*,int eTextRep,const void*)
 5947 );
 5948 
 5949 #ifdef SQLITE_ENABLE_CEROD
 5950 /*
 5951 ** Specify the activation key for a CEROD database.  Unless 
 5952 ** activated, none of the CEROD routines will work.
 5953 */
 5954 SQLITE_API void sqlite3_activate_cerod(
 5955   const char *zPassPhrase        /* Activation phrase */
 5956 );
 5957 #endif
 5958 
 5959 /*
 5960 ** CAPI3REF: Suspend Execution For A Short Time
 5961 **
 5962 ** The sqlite3_sleep() function causes the current thread to suspend execution
 5963 ** for at least a number of milliseconds specified in its parameter.
 5964 **
 5965 ** If the operating system does not support sleep requests with
 5966 ** millisecond time resolution, then the time will be rounded up to
 5967 ** the nearest second. The number of milliseconds of sleep actually
 5968 ** requested from the operating system is returned.
 5969 **
 5970 ** ^SQLite implements this interface by calling the xSleep()
 5971 ** method of the default [sqlite3_vfs] object.  If the xSleep() method
 5972 ** of the default VFS is not implemented correctly, or not implemented at
 5973 ** all, then the behavior of sqlite3_sleep() may deviate from the description
 5974 ** in the previous paragraphs.
 5975 */
 5976 SQLITE_API int sqlite3_sleep(int);
 5977 
 5978 /*
 5979 ** CAPI3REF: Name Of The Folder Holding Temporary Files
 5980 **
 5981 ** ^(If this global variable is made to point to a string which is
 5982 ** the name of a folder (a.k.a. directory), then all temporary files
 5983 ** created by SQLite when using a built-in [sqlite3_vfs | VFS]
 5984 ** will be placed in that directory.)^  ^If this variable
 5985 ** is a NULL pointer, then SQLite performs a search for an appropriate
 5986 ** temporary file directory.
 5987 **
 5988 ** Applications are strongly discouraged from using this global variable.
 5989 ** It is required to set a temporary folder on Windows Runtime (WinRT).
 5990 ** But for all other platforms, it is highly recommended that applications
 5991 ** neither read nor write this variable.  This global variable is a relic
 5992 ** that exists for backwards compatibility of legacy applications and should
 5993 ** be avoided in new projects.
 5994 **
 5995 ** It is not safe to read or modify this variable in more than one
 5996 ** thread at a time.  It is not safe to read or modify this variable
 5997 ** if a [database connection] is being used at the same time in a separate
 5998 ** thread.
 5999 ** It is intended that this variable be set once
 6000 ** as part of process initialization and before any SQLite interface
 6001 ** routines have been called and that this variable remain unchanged
 6002 ** thereafter.
 6003 **
 6004 ** ^The [temp_store_directory pragma] may modify this variable and cause
 6005 ** it to point to memory obtained from [sqlite3_malloc].  ^Furthermore,
 6006 ** the [temp_store_directory pragma] always assumes that any string
 6007 ** that this variable points to is held in memory obtained from 
 6008 ** [sqlite3_malloc] and the pragma may attempt to free that memory
 6009 ** using [sqlite3_free].
 6010 ** Hence, if this variable is modified directly, either it should be
 6011 ** made NULL or made to point to memory obtained from [sqlite3_malloc]
 6012 ** or else the use of the [temp_store_directory pragma] should be avoided.
 6013 ** Except when requested by the [temp_store_directory pragma], SQLite
 6014 ** does not free the memory that sqlite3_temp_directory points to.  If
 6015 ** the application wants that memory to be freed, it must do
 6016 ** so itself, taking care to only do so after all [database connection]
 6017 ** objects have been destroyed.
 6018 **
 6019 ** <b>Note to Windows Runtime users:</b>  The temporary directory must be set
 6020 ** prior to calling [sqlite3_open] or [sqlite3_open_v2].  Otherwise, various
 6021 ** features that require the use of temporary files may fail.  Here is an
 6022 ** example of how to do this using C++ with the Windows Runtime:
 6023 **
 6024 ** <blockquote><pre>
 6025 ** LPCWSTR zPath = Windows::Storage::ApplicationData::Current->
 6026 ** &nbsp;     TemporaryFolder->Path->Data();
 6027 ** char zPathBuf&#91;MAX_PATH + 1&#93;;
 6028 ** memset(zPathBuf, 0, sizeof(zPathBuf));
 6029 ** WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, sizeof(zPathBuf),
 6030 ** &nbsp;     NULL, NULL);
 6031 ** sqlite3_temp_directory = sqlite3_mprintf("%s", zPathBuf);
 6032 ** </pre></blockquote>
 6033 */
 6034 SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory;
 6035 
 6036 /*
 6037 ** CAPI3REF: Name Of The Folder Holding Database Files
 6038 **
 6039 ** ^(If this global variable is made to point to a string which is
 6040 ** the name of a folder (a.k.a. directory), then all database files
 6041 ** specified with a relative pathname and created or accessed by
 6042 ** SQLite when using a built-in windows [sqlite3_vfs | VFS] will be assumed
 6043 ** to be relative to that directory.)^ ^If this variable is a NULL
 6044 ** pointer, then SQLite assumes that all database files specified
 6045 ** with a relative pathname are relative to the current directory
 6046 ** for the process.  Only the windows VFS makes use of this global
 6047 ** variable; it is ignored by the unix VFS.
 6048 **
 6049 ** Changing the value of this variable while a database connection is
 6050 ** open can result in a corrupt database.
 6051 **
 6052 ** It is not safe to read or modify this variable in more than one
 6053 ** thread at a time.  It is not safe to read or modify this variable
 6054 ** if a [database connection] is being used at the same time in a separate
 6055 ** thread.
 6056 ** It is intended that this variable be set once
 6057 ** as part of process initialization and before any SQLite interface
 6058 ** routines have been called and that this variable remain unchanged
 6059 ** thereafter.
 6060 **
 6061 ** ^The [data_store_directory pragma] may modify this variable and cause
 6062 ** it to point to memory obtained from [sqlite3_malloc].  ^Furthermore,
 6063 ** the [data_store_directory pragma] always assumes that any string
 6064 ** that this variable points to is held in memory obtained from 
 6065 ** [sqlite3_malloc] and the pragma may attempt to free that memory
 6066 ** using [sqlite3_free].
 6067 ** Hence, if this variable is modified directly, either it should be
 6068 ** made NULL or made to point to memory obtained from [sqlite3_malloc]
 6069 ** or else the use of the [data_store_directory pragma] should be avoided.
 6070 */
 6071 SQLITE_API SQLITE_EXTERN char *sqlite3_data_directory;
 6072 
 6073 /*
 6074 ** CAPI3REF: Win32 Specific Interface
 6075 **
 6076 ** These interfaces are available only on Windows.  The
 6077 ** [sqlite3_win32_set_directory] interface is used to set the value associated
 6078 ** with the [sqlite3_temp_directory] or [sqlite3_data_directory] variable, to
 6079 ** zValue, depending on the value of the type parameter.  The zValue parameter
 6080 ** should be NULL to cause the previous value to be freed via [sqlite3_free];
 6081 ** a non-NULL value will be copied into memory obtained from [sqlite3_malloc]
 6082 ** prior to being used.  The [sqlite3_win32_set_directory] interface returns
 6083 ** [SQLITE_OK] to indicate success, [SQLITE_ERROR] if the type is unsupported,
 6084 ** or [SQLITE_NOMEM] if memory could not be allocated.  The value of the
 6085 ** [sqlite3_data_directory] variable is intended to act as a replacement for
 6086 ** the current directory on the sub-platforms of Win32 where that concept is
 6087 ** not present, e.g. WinRT and UWP.  The [sqlite3_win32_set_directory8] and
 6088 ** [sqlite3_win32_set_directory16] interfaces behave exactly the same as the
 6089 ** sqlite3_win32_set_directory interface except the string parameter must be
 6090 ** UTF-8 or UTF-16, respectively.
 6091 */
 6092 SQLITE_API int sqlite3_win32_set_directory(
 6093   unsigned long type, /* Identifier for directory being set or reset */
 6094   void *zValue        /* New value for directory being set or reset */
 6095 );
 6096 SQLITE_API int sqlite3_win32_set_directory8(unsigned long type, const char *zValue);
 6097 SQLITE_API int sqlite3_win32_set_directory16(unsigned long type, const void *zValue);
 6098 
 6099 /*
 6100 ** CAPI3REF: Win32 Directory Types
 6101 **
 6102 ** These macros are only available on Windows.  They define the allowed values
 6103 ** for the type argument to the [sqlite3_win32_set_directory] interface.
 6104 */
 6105 #define SQLITE_WIN32_DATA_DIRECTORY_TYPE  1
 6106 #define SQLITE_WIN32_TEMP_DIRECTORY_TYPE  2
 6107 
 6108 /*
 6109 ** CAPI3REF: Test For Auto-Commit Mode
 6110 ** KEYWORDS: {autocommit mode}
 6111 ** METHOD: sqlite3
 6112 **
 6113 ** ^The sqlite3_get_autocommit() interface returns non-zero or
 6114 ** zero if the given database connection is or is not in autocommit mode,
 6115 ** respectively.  ^Autocommit mode is on by default.
 6116 ** ^Autocommit mode is disabled by a [BEGIN] statement.
 6117 ** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
 6118 **
 6119 ** If certain kinds of errors occur on a statement within a multi-statement
 6120 ** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR],
 6121 ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
 6122 ** transaction might be rolled back automatically.  The only way to
 6123 ** find out whether SQLite automatically rolled back the transaction after
 6124 ** an error is to use this function.
 6125 **
 6126 ** If another thread changes the autocommit status of the database
 6127 ** connection while this routine is running, then the return value
 6128 ** is undefined.
 6129 */
 6130 SQLITE_API int sqlite3_get_autocommit(sqlite3*);
 6131 
 6132 /*
 6133 ** CAPI3REF: Find The Database Handle Of A Prepared Statement
 6134 ** METHOD: sqlite3_stmt
 6135 **
 6136 ** ^The sqlite3_db_handle interface returns the [database connection] handle
 6137 ** to which a [prepared statement] belongs.  ^The [database connection]
 6138 ** returned by sqlite3_db_handle is the same [database connection]
 6139 ** that was the first argument
 6140 ** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
 6141 ** create the statement in the first place.
 6142 */
 6143 SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
 6144 
 6145 /*
 6146 ** CAPI3REF: Return The Filename For A Database Connection
 6147 ** METHOD: sqlite3
 6148 **
 6149 ** ^The sqlite3_db_filename(D,N) interface returns a pointer to the filename
 6150 ** associated with database N of connection D.
 6151 ** ^If there is no attached database N on the database
 6152 ** connection D, or if database N is a temporary or in-memory database, then
 6153 ** this function will return either a NULL pointer or an empty string.
 6154 **
 6155 ** ^The string value returned by this routine is owned and managed by
 6156 ** the database connection.  ^The value will be valid until the database N
 6157 ** is [DETACH]-ed or until the database connection closes.
 6158 **
 6159 ** ^The filename returned by this function is the output of the
 6160 ** xFullPathname method of the [VFS].  ^In other words, the filename
 6161 ** will be an absolute pathname, even if the filename used
 6162 ** to open the database originally was a URI or relative pathname.
 6163 **
 6164 ** If the filename pointer returned by this routine is not NULL, then it
 6165 ** can be used as the filename input parameter to these routines:
 6166 ** <ul>
 6167 ** <li> [sqlite3_uri_parameter()]
 6168 ** <li> [sqlite3_uri_boolean()]
 6169 ** <li> [sqlite3_uri_int64()]
 6170 ** <li> [sqlite3_filename_database()]
 6171 ** <li> [sqlite3_filename_journal()]
 6172 ** <li> [sqlite3_filename_wal()]
 6173 ** </ul>
 6174 */
 6175 SQLITE_API const char *sqlite3_db_filename(sqlite3 *db, const char *zDbName);
 6176 
 6177 /*
 6178 ** CAPI3REF: Determine if a database is read-only
 6179 ** METHOD: sqlite3
 6180 **
 6181 ** ^The sqlite3_db_readonly(D,N) interface returns 1 if the database N
 6182 ** of connection D is read-only, 0 if it is read/write, or -1 if N is not
 6183 ** the name of a database on connection D.
 6184 */
 6185 SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName);
 6186 
 6187 /*
 6188 ** CAPI3REF: Find the next prepared statement
 6189 ** METHOD: sqlite3
 6190 **
 6191 ** ^This interface returns a pointer to the next [prepared statement] after
 6192 ** pStmt associated with the [database connection] pDb.  ^If pStmt is NULL
 6193 ** then this interface returns a pointer to the first prepared statement
 6194 ** associated with the database connection pDb.  ^If no prepared statement
 6195 ** satisfies the conditions of this routine, it returns NULL.
 6196 **
 6197 ** The [database connection] pointer D in a call to
 6198 ** [sqlite3_next_stmt(D,S)] must refer to an open database
 6199 ** connection and in particular must not be a NULL pointer.
 6200 */
 6201 SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
 6202 
 6203 /*
 6204 ** CAPI3REF: Commit And Rollback Notification Callbacks
 6205 ** METHOD: sqlite3
 6206 **
 6207 ** ^The sqlite3_commit_hook() interface registers a callback
 6208 ** function to be invoked whenever a transaction is [COMMIT | committed].
 6209 ** ^Any callback set by a previous call to sqlite3_commit_hook()
 6210 ** for the same database connection is overridden.
 6211 ** ^The sqlite3_rollback_hook() interface registers a callback
 6212 ** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
 6213 ** ^Any callback set by a previous call to sqlite3_rollback_hook()
 6214 ** for the same database connection is overridden.
 6215 ** ^The pArg argument is passed through to the callback.
 6216 ** ^If the callback on a commit hook function returns non-zero,
 6217 ** then the commit is converted into a rollback.
 6218 **
 6219 ** ^The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions
 6220 ** return the P argument from the previous call of the same function
 6221 ** on the same [database connection] D, or NULL for
 6222 ** the first call for each function on D.
 6223 **
 6224 ** The commit and rollback hook callbacks are not reentrant.
 6225 ** The callback implementation must not do anything that will modify
 6226 ** the database connection that invoked the callback.  Any actions
 6227 ** to modify the database connection must be deferred until after the
 6228 ** completion of the [sqlite3_step()] call that triggered the commit
 6229 ** or rollback hook in the first place.
 6230 ** Note that running any other SQL statements, including SELECT statements,
 6231 ** or merely calling [sqlite3_prepare_v2()] and [sqlite3_step()] will modify
 6232 ** the database connections for the meaning of "modify" in this paragraph.
 6233 **
 6234 ** ^Registering a NULL function disables the callback.
 6235 **
 6236 ** ^When the commit hook callback routine returns zero, the [COMMIT]
 6237 ** operation is allowed to continue normally.  ^If the commit hook
 6238 ** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
 6239 ** ^The rollback hook is invoked on a rollback that results from a commit
 6240 ** hook returning non-zero, just as it would be with any other rollback.
 6241 **
 6242 ** ^For the purposes of this API, a transaction is said to have been
 6243 ** rolled back if an explicit "ROLLBACK" statement is executed, or
 6244 ** an error or constraint causes an implicit rollback to occur.
 6245 ** ^The rollback callback is not invoked if a transaction is
 6246 ** automatically rolled back because the database connection is closed.
 6247 **
 6248 ** See also the [sqlite3_update_hook()] interface.
 6249 */
 6250 SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
 6251 SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
 6252 
 6253 /*
 6254 ** CAPI3REF: Data Change Notification Callbacks
 6255 ** METHOD: sqlite3
 6256 **
 6257 ** ^The sqlite3_update_hook() interface registers a callback function
 6258 ** with the [database connection] identified by the first argument
 6259 ** to be invoked whenever a row is updated, inserted or deleted in
 6260 ** a [rowid table].
 6261 ** ^Any callback set by a previous call to this function
 6262 ** for the same database connection is overridden.
 6263 **
 6264 ** ^The second argument is a pointer to the function to invoke when a
 6265 ** row is updated, inserted or deleted in a rowid table.
 6266 ** ^The first argument to the callback is a copy of the third argument
 6267 ** to sqlite3_update_hook().
 6268 ** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
 6269 ** or [SQLITE_UPDATE], depending on the operation that caused the callback
 6270 ** to be invoked.
 6271 ** ^The third and fourth arguments to the callback contain pointers to the
 6272 ** database and table name containing the affected row.
 6273 ** ^The final callback parameter is the [rowid] of the row.
 6274 ** ^In the case of an update, this is the [rowid] after the update takes place.
 6275 **
 6276 ** ^(The update hook is not invoked when internal system tables are
 6277 ** modified (i.e. sqlite_master and sqlite_sequence).)^
 6278 ** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified.
 6279 **
 6280 ** ^In the current implementation, the update hook
 6281 ** is not invoked when conflicting rows are deleted because of an
 6282 ** [ON CONFLICT | ON CONFLICT REPLACE] clause.  ^Nor is the update hook
 6283 ** invoked when rows are deleted using the [truncate optimization].
 6284 ** The exceptions defined in this paragraph might change in a future
 6285 ** release of SQLite.
 6286 **
 6287 ** The update hook implementation must not do anything that will modify
 6288 ** the database connection that invoked the update hook.  Any actions
 6289 ** to modify the database connection must be deferred until after the
 6290 ** completion of the [sqlite3_step()] call that triggered the update hook.
 6291 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
 6292 ** database connections for the meaning of "modify" in this paragraph.
 6293 **
 6294 ** ^The sqlite3_update_hook(D,C,P) function
 6295 ** returns the P argument from the previous call
 6296 ** on the same [database connection] D, or NULL for
 6297 ** the first call on D.
 6298 **
 6299 ** See also the [sqlite3_commit_hook()], [sqlite3_rollback_hook()],
 6300 ** and [sqlite3_preupdate_hook()] interfaces.
 6301 */
 6302 SQLITE_API void *sqlite3_update_hook(
 6303   sqlite3*, 
 6304   void(*)(void *,int ,char const *,char const *,sqlite3_int64),
 6305   void*
 6306 );
 6307 
 6308 /*
 6309 ** CAPI3REF: Enable Or Disable Shared Pager Cache
 6310 **
 6311 ** ^(This routine enables or disables the sharing of the database cache
 6312 ** and schema data structures between [database connection | connections]
 6313 ** to the same database. Sharing is enabled if the argument is true
 6314 ** and disabled if the argument is false.)^
 6315 **
 6316 ** ^Cache sharing is enabled and disabled for an entire process.
 6317 ** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]). 
 6318 ** In prior versions of SQLite,
 6319 ** sharing was enabled or disabled for each thread separately.
 6320 **
 6321 ** ^(The cache sharing mode set by this interface effects all subsequent
 6322 ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
 6323 ** Existing database connections continue to use the sharing mode
 6324 ** that was in effect at the time they were opened.)^
 6325 **
 6326 ** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled
 6327 ** successfully.  An [error code] is returned otherwise.)^
 6328 **
 6329 ** ^Shared cache is disabled by default. It is recommended that it stay
 6330 ** that way.  In other words, do not use this routine.  This interface
 6331 ** continues to be provided for historical compatibility, but its use is
 6332 ** discouraged.  Any use of shared cache is discouraged.  If shared cache
 6333 ** must be used, it is recommended that shared cache only be enabled for
 6334 ** individual database connections using the [sqlite3_open_v2()] interface
 6335 ** with the [SQLITE_OPEN_SHAREDCACHE] flag.
 6336 **
 6337 ** Note: This method is disabled on MacOS X 10.7 and iOS version 5.0
 6338 ** and will always return SQLITE_MISUSE. On those systems, 
 6339 ** shared cache mode should be enabled per-database connection via 
 6340 ** [sqlite3_open_v2()] with [SQLITE_OPEN_SHAREDCACHE].
 6341 **
 6342 ** This interface is threadsafe on processors where writing a
 6343 ** 32-bit integer is atomic.
 6344 **
 6345 ** See Also:  [SQLite Shared-Cache Mode]
 6346 */
 6347 SQLITE_API int sqlite3_enable_shared_cache(int);
 6348 
 6349 /*
 6350 ** CAPI3REF: Attempt To Free Heap Memory
 6351 **
 6352 ** ^The sqlite3_release_memory() interface attempts to free N bytes
 6353 ** of heap memory by deallocating non-essential memory allocations
 6354 ** held by the database library.   Memory used to cache database
 6355 ** pages to improve performance is an example of non-essential memory.
 6356 ** ^sqlite3_release_memory() returns the number of bytes actually freed,
 6357 ** which might be more or less than the amount requested.
 6358 ** ^The sqlite3_release_memory() routine is a no-op returning zero
 6359 ** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT].
 6360 **
 6361 ** See also: [sqlite3_db_release_memory()]
 6362 */
 6363 SQLITE_API int sqlite3_release_memory(int);
 6364 
 6365 /*
 6366 ** CAPI3REF: Free Memory Used By A Database Connection
 6367 ** METHOD: sqlite3
 6368 **
 6369 ** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap
 6370 ** memory as possible from database connection D. Unlike the
 6371 ** [sqlite3_release_memory()] interface, this interface is in effect even
 6372 ** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is
 6373 ** omitted.
 6374 **
 6375 ** See also: [sqlite3_release_memory()]
 6376 */
 6377 SQLITE_API int sqlite3_db_release_memory(sqlite3*);
 6378 
 6379 /*
 6380 ** CAPI3REF: Impose A Limit On Heap Size
 6381 **
 6382 ** These interfaces impose limits on the amount of heap memory that will be
 6383 ** by all database connections within a single process.
 6384 **
 6385 ** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the
 6386 ** soft limit on the amount of heap memory that may be allocated by SQLite.
 6387 ** ^SQLite strives to keep heap memory utilization below the soft heap
 6388 ** limit by reducing the number of pages held in the page cache
 6389 ** as heap memory usages approaches the limit.
 6390 ** ^The soft heap limit is "soft" because even though SQLite strives to stay
 6391 ** below the limit, it will exceed the limit rather than generate
 6392 ** an [SQLITE_NOMEM] error.  In other words, the soft heap limit 
 6393 ** is advisory only.
 6394 **
 6395 ** ^The sqlite3_hard_heap_limit64(N) interface sets a hard upper bound of
 6396 ** N bytes on the amount of memory that will be allocated.  ^The
 6397 ** sqlite3_hard_heap_limit64(N) interface is similar to
 6398 ** sqlite3_soft_heap_limit64(N) except that memory allocations will fail
 6399 ** when the hard heap limit is reached.
 6400 **
 6401 ** ^The return value from both sqlite3_soft_heap_limit64() and
 6402 ** sqlite3_hard_heap_limit64() is the size of
 6403 ** the heap limit prior to the call, or negative in the case of an
 6404 ** error.  ^If the argument N is negative
 6405 ** then no change is made to the heap limit.  Hence, the current
 6406 ** size of heap limits can be determined by invoking
 6407 ** sqlite3_soft_heap_limit64(-1) or sqlite3_hard_heap_limit(-1).
 6408 **
 6409 ** ^Setting the heap limits to zero disables the heap limiter mechanism.
 6410 **
 6411 ** ^The soft heap limit may not be greater than the hard heap limit.
 6412 ** ^If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N)
 6413 ** is invoked with a value of N that is greater than the hard heap limit,
 6414 ** the the soft heap limit is set to the value of the hard heap limit.
 6415 ** ^The soft heap limit is automatically enabled whenever the hard heap
 6416 ** limit is enabled. ^When sqlite3_hard_heap_limit64(N) is invoked and
 6417 ** the soft heap limit is outside the range of 1..N, then the soft heap
 6418 ** limit is set to N.  ^Invoking sqlite3_soft_heap_limit64(0) when the
 6419 ** hard heap limit is enabled makes the soft heap limit equal to the
 6420 ** hard heap limit.
 6421 **
 6422 ** The memory allocation limits can also be adjusted using
 6423 ** [PRAGMA soft_heap_limit] and [PRAGMA hard_heap_limit].
 6424 **
 6425 ** ^(The heap limits are not enforced in the current implementation
 6426 ** if one or more of following conditions are true:
 6427 **
 6428 ** <ul>
 6429 ** <li> The limit value is set to zero.
 6430 ** <li> Memory accounting is disabled using a combination of the
 6431 **      [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and
 6432 **      the [SQLITE_DEFAULT_MEMSTATUS] compile-time option.
 6433 ** <li> An alternative page cache implementation is specified using
 6434 **      [sqlite3_config]([SQLITE_CONFIG_PCACHE2],...).
 6435 ** <li> The page cache allocates from its own memory pool supplied
 6436 **      by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than
 6437 **      from the heap.
 6438 ** </ul>)^
 6439 **
 6440 ** The circumstances under which SQLite will enforce the heap limits may
 6441 ** changes in future releases of SQLite.
 6442 */
 6443 SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
 6444 SQLITE_API sqlite3_int64 sqlite3_hard_heap_limit64(sqlite3_int64 N);
 6445 
 6446 /*
 6447 ** CAPI3REF: Deprecated Soft Heap Limit Interface
 6448 ** DEPRECATED
 6449 **
 6450 ** This is a deprecated version of the [sqlite3_soft_heap_limit64()]
 6451 ** interface.  This routine is provided for historical compatibility
 6452 ** only.  All new applications should use the
 6453 ** [sqlite3_soft_heap_limit64()] interface rather than this one.
 6454 */
 6455 SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
 6456 
 6457 
 6458 /*
 6459 ** CAPI3REF: Extract Metadata About A Column Of A Table
 6460 ** METHOD: sqlite3
 6461 **
 6462 ** ^(The sqlite3_table_column_metadata(X,D,T,C,....) routine returns
 6463 ** information about column C of table T in database D
 6464 ** on [database connection] X.)^  ^The sqlite3_table_column_metadata()
 6465 ** interface returns SQLITE_OK and fills in the non-NULL pointers in
 6466 ** the final five arguments with appropriate values if the specified
 6467 ** column exists.  ^The sqlite3_table_column_metadata() interface returns
 6468 ** SQLITE_ERROR if the specified column does not exist.
 6469 ** ^If the column-name parameter to sqlite3_table_column_metadata() is a
 6470 ** NULL pointer, then this routine simply checks for the existence of the
 6471 ** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it
 6472 ** does not.  If the table name parameter T in a call to
 6473 ** sqlite3_table_column_metadata(X,D,T,C,...) is NULL then the result is
 6474 ** undefined behavior.
 6475 **
 6476 ** ^The column is identified by the second, third and fourth parameters to
 6477 ** this function. ^(The second parameter is either the name of the database
 6478 ** (i.e. "main", "temp", or an attached database) containing the specified
 6479 ** table or NULL.)^ ^If it is NULL, then all attached databases are searched
 6480 ** for the table using the same algorithm used by the database engine to
 6481 ** resolve unqualified table references.
 6482 **
 6483 ** ^The third and fourth parameters to this function are the table and column
 6484 ** name of the desired column, respectively.
 6485 **
 6486 ** ^Metadata is returned by writing to the memory locations passed as the 5th
 6487 ** and subsequent parameters to this function. ^Any of these arguments may be
 6488 ** NULL, in which case the corresponding element of metadata is omitted.
 6489 **
 6490 ** ^(<blockquote>
 6491 ** <table border="1">
 6492 ** <tr><th> Parameter <th> Output<br>Type <th>  Description
 6493 **
 6494 ** <tr><td> 5th <td> const char* <td> Data type
 6495 ** <tr><td> 6th <td> const char* <td> Name of default collation sequence
 6496 ** <tr><td> 7th <td> int         <td> True if column has a NOT NULL constraint
 6497 ** <tr><td> 8th <td> int         <td> True if column is part of the PRIMARY KEY
 6498 ** <tr><td> 9th <td> int         <td> True if column is [AUTOINCREMENT]
 6499 ** </table>
 6500 ** </blockquote>)^
 6501 **
 6502 ** ^The memory pointed to by the character pointers returned for the
 6503 ** declaration type and collation sequence is valid until the next
 6504 ** call to any SQLite API function.
 6505 **
 6506 ** ^If the specified table is actually a view, an [error code] is returned.
 6507 **
 6508 ** ^If the specified column is "rowid", "oid" or "_rowid_" and the table 
 6509 ** is not a [WITHOUT ROWID] table and an
 6510 ** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output
 6511 ** parameters are set for the explicitly declared column. ^(If there is no
 6512 ** [INTEGER PRIMARY KEY] column, then the outputs
 6513 ** for the [rowid] are set as follows:
 6514 **
 6515 ** <pre>
 6516 **     data type: "INTEGER"
 6517 **     collation sequence: "BINARY"