"Fossies" - the Fresh Open Source Software Archive

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


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

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