"Fossies" - the Fresh Open Source Software Archive

Member "cells-3.0.3/vendor/github.com/mattn/go-sqlite3/sqlite3-binding.c" (30 Nov 2021, 7077276 Bytes) of package /linux/misc/pydio-cells-3.0.3.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.

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