sqlite3.h

1/*2** 2001-09-153**4** The author disclaims copyright to this source code.  In place of5** a legal notice, here is a blessing:6**7**    May you do good and not evil.8**    May you find forgiveness for yourself and forgive others.9**    May you share freely, never taking more than you give.10**11*************************************************************************12** This header file defines the interface that the SQLite library13** presents to client programs.  If a C-function, structure, datatype,14** or constant definition does not appear in this file, then it is15** not a published API of SQLite, is subject to change without16** notice, and should not be referenced by programs that use SQLite.17**18** Some of the definitions that are in this file are marked as19** "experimental".  Experimental interfaces are normally new20** features recently added to SQLite.  We do not anticipate changes21** to experimental interfaces but reserve the right to make minor changes22** if experience from use "in the wild" suggest such changes are prudent.23**24** The official C-language API documentation for SQLite is derived25** from comments in this file.  This file is the authoritative source26** on how SQLite interfaces are supposed to operate.27**28** The name of this file under configuration management is "sqlite.h.in".29** The makefile makes some minor changes to this file (such as inserting30** the version number) and changes its name to "sqlite3.h" as31** part of the build process.32*/33#ifndef SQLITE3_H34#define SQLITE3_H35#include <stdarg.h>     /* Needed for the definition of va_list */3637/*38** Make sure we can call this stuff from C++.39*/40#ifdef __cplusplus41extern "C" {42#endif434445/*46** Facilitate override of interface linkage and calling conventions.47** Be aware that these macros may not be used within this particular48** translation of the amalgamation and its associated header file.49**50** The SQLITE_EXTERN and SQLITE_API macros are used to instruct the51** compiler that the target identifier should have external linkage.52**53** The SQLITE_CDECL macro is used to set the calling convention for54** public functions that accept a variable number of arguments.55**56** The SQLITE_APICALL macro is used to set the calling convention for57** public functions that accept a fixed number of arguments.58**59** The SQLITE_STDCALL macro is no longer used and is now deprecated.60**61** The SQLITE_CALLBACK macro is used to set the calling convention for62** function pointers.63**64** The SQLITE_SYSAPI macro is used to set the calling convention for65** functions provided by the operating system.66**67** Currently, the SQLITE_CDECL, SQLITE_APICALL, SQLITE_CALLBACK, and68** SQLITE_SYSAPI macros are used only when building for environments69** that require non-default calling conventions.70*/71#ifndef SQLITE_EXTERN72# define SQLITE_EXTERN extern73#endif74#ifndef SQLITE_API75# define SQLITE_API76#endif77#ifndef SQLITE_CDECL78# define SQLITE_CDECL79#endif80#ifndef SQLITE_APICALL81# define SQLITE_APICALL82#endif83#ifndef SQLITE_STDCALL84# define SQLITE_STDCALL SQLITE_APICALL85#endif86#ifndef SQLITE_CALLBACK87# define SQLITE_CALLBACK88#endif89#ifndef SQLITE_SYSAPI90# define SQLITE_SYSAPI91#endif9293/*94** These no-op macros are used in front of interfaces to mark those95** interfaces as either deprecated or experimental.  New applications96** should not use deprecated interfaces - they are supported for backwards97** compatibility only.  Application writers should be aware that98** experimental interfaces are subject to change in point releases.99**100** These macros used to resolve to various kinds of compiler magic that101** would generate warning messages when they were used.  But that102** compiler magic ended up generating such a flurry of bug reports103** that we have taken it all out and gone back to using simple104** noop macros.105*/106#define SQLITE_DEPRECATED107#define SQLITE_EXPERIMENTAL108109/*110** Ensure these symbols were not defined by some previous header file.111*/112#ifdef SQLITE_VERSION113# undef SQLITE_VERSION114#endif115#ifdef SQLITE_VERSION_NUMBER116# undef SQLITE_VERSION_NUMBER117#endif118119/*120** CAPI3REF: Compile-Time Library Version Numbers121**122** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header123** evaluates to a string literal that is the SQLite version in the124** format "X.Y.Z" where X is the major version number (always 3 for125** SQLite3) and Y is the minor version number and Z is the release number.)^126** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer127** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same128** numbers used in [SQLITE_VERSION].)^129** The SQLITE_VERSION_NUMBER for any given release of SQLite will also130** be larger than the release from which it is derived.  Either Y will131** be held constant and Z will be incremented or else Y will be incremented132** and Z will be reset to zero.133**134** Since [version 3.6.18] ([dateof:3.6.18]),135** SQLite source code has been stored in the136** <a href="http://www.fossil-scm.org/">Fossil configuration management137** system</a>.  ^The SQLITE_SOURCE_ID macro evaluates to138** a string which identifies a particular check-in of SQLite139** within its configuration management system.  ^The SQLITE_SOURCE_ID140** string contains the date and time of the check-in (UTC) and a SHA1141** or SHA3-256 hash of the entire source tree.  If the source code has142** been edited in any way since it was last checked in, then the last143** four hexadecimal digits of the hash may be modified.144**145** See also: [sqlite3_libversion()],146** [sqlite3_libversion_number()], [sqlite3_sourceid()],147** [sqlite_version()] and [sqlite_source_id()].148*/149#define SQLITE_VERSION        "3.49.1"150#define SQLITE_VERSION_NUMBER 3049001151#define SQLITE_SOURCE_ID      "2025-02-18 13:38:58 873d4e274b4988d260ba8354a9718324a1c26187a4ab4c1cc0227c03d0f10e70"152153/*154** CAPI3REF: Run-Time Library Version Numbers155** KEYWORDS: sqlite3_version sqlite3_sourceid156**157** These interfaces provide the same information as the [SQLITE_VERSION],158** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros159** but are associated with the library instead of the header file.  ^(Cautious160** programmers might include assert() statements in their application to161** verify that values returned by these interfaces match the macros in162** the header, and thus ensure that the application is163** compiled with matching library and header files.164**165** <blockquote><pre>166** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );167** assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 );168** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );169** </pre></blockquote>)^170**171** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]172** macro.  ^The sqlite3_libversion() function returns a pointer to the173** to the sqlite3_version[] string constant.  The sqlite3_libversion()174** function is provided for use in DLLs since DLL users usually do not have175** direct access to string constants within the DLL.  ^The176** sqlite3_libversion_number() function returns an integer equal to177** [SQLITE_VERSION_NUMBER].  ^(The sqlite3_sourceid() function returns178** a pointer to a string constant whose value is the same as the179** [SQLITE_SOURCE_ID] C preprocessor macro.  Except if SQLite is built180** using an edited copy of [the amalgamation], then the last four characters181** of the hash might be different from [SQLITE_SOURCE_ID].)^182**183** See also: [sqlite_version()] and [sqlite_source_id()].184*/185SQLITE_API SQLITE_EXTERN const char sqlite3_version[];186SQLITE_API const char *sqlite3_libversion(void);187SQLITE_API const char *sqlite3_sourceid(void);188SQLITE_API int sqlite3_libversion_number(void);189190/*191** CAPI3REF: Run-Time Library Compilation Options Diagnostics192**193** ^The sqlite3_compileoption_used() function returns 0 or 1194** indicating whether the specified option was defined at195** compile time.  ^The SQLITE_ prefix may be omitted from the196** option name passed to sqlite3_compileoption_used().197**198** ^The sqlite3_compileoption_get() function allows iterating199** over the list of options that were defined at compile time by200** returning the N-th compile time option string.  ^If N is out of range,201** sqlite3_compileoption_get() returns a NULL pointer.  ^The SQLITE_202** prefix is omitted from any strings returned by203** sqlite3_compileoption_get().204**205** ^Support for the diagnostic functions sqlite3_compileoption_used()206** and sqlite3_compileoption_get() may be omitted by specifying the207** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.208**209** See also: SQL functions [sqlite_compileoption_used()] and210** [sqlite_compileoption_get()] and the [compile_options pragma].211*/212#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS213SQLITE_API int sqlite3_compileoption_used(const char *zOptName);214SQLITE_API const char *sqlite3_compileoption_get(int N);215#else216# define sqlite3_compileoption_used(X) 0217# define sqlite3_compileoption_get(X)  ((void*)0)218#endif219220/*221** CAPI3REF: Test To See If The Library Is Threadsafe222**223** ^The sqlite3_threadsafe() function returns zero if and only if224** SQLite was compiled with mutexing code omitted due to the225** [SQLITE_THREADSAFE] compile-time option being set to 0.226**227** SQLite can be compiled with or without mutexes.  When228** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes229** are enabled and SQLite is threadsafe.  When the230** [SQLITE_THREADSAFE] macro is 0,231** the mutexes are omitted.  Without the mutexes, it is not safe232** to use SQLite concurrently from more than one thread.233**234** Enabling mutexes incurs a measurable performance penalty.235** So if speed is of utmost importance, it makes sense to disable236** the mutexes.  But for maximum safety, mutexes should be enabled.237** ^The default behavior is for mutexes to be enabled.238**239** This interface can be used by an application to make sure that the240** version of SQLite that it is linking against was compiled with241** the desired setting of the [SQLITE_THREADSAFE] macro.242**243** This interface only reports on the compile-time mutex setting244** of the [SQLITE_THREADSAFE] flag.  If SQLite is compiled with245** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but246** can be fully or partially disabled using a call to [sqlite3_config()]247** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],248** or [SQLITE_CONFIG_SERIALIZED].  ^(The return value of the249** sqlite3_threadsafe() function shows only the compile-time setting of250** thread safety, not any run-time changes to that setting made by251** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()252** is unchanged by calls to sqlite3_config().)^253**254** See the [threading mode] documentation for additional information.255*/256SQLITE_API int sqlite3_threadsafe(void);257258/*259** CAPI3REF: Database Connection Handle260** KEYWORDS: {database connection} {database connections}261**262** Each open SQLite database is represented by a pointer to an instance of263** the opaque structure named "sqlite3".  It is useful to think of an sqlite3264** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and265** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]266** and [sqlite3_close_v2()] are its destructors.  There are many other267** interfaces (such as268** [sqlite3_prepare_v2()], [sqlite3_create_function()], and269** [sqlite3_busy_timeout()] to name but three) that are methods on an270** sqlite3 object.271*/272typedef struct sqlite3 sqlite3;273274/*275** CAPI3REF: 64-Bit Integer Types276** KEYWORDS: sqlite_int64 sqlite_uint64277**278** Because there is no cross-platform way to specify 64-bit integer types279** SQLite includes typedefs for 64-bit signed and unsigned integers.280**281** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.282** The sqlite_int64 and sqlite_uint64 types are supported for backwards283** compatibility only.284**285** ^The sqlite3_int64 and sqlite_int64 types can store integer values286** between -9223372036854775808 and +9223372036854775807 inclusive.  ^The287** sqlite3_uint64 and sqlite_uint64 types can store integer values288** between 0 and +18446744073709551615 inclusive.289*/290#ifdef SQLITE_INT64_TYPE291  typedef SQLITE_INT64_TYPE sqlite_int64;292# ifdef SQLITE_UINT64_TYPE293    typedef SQLITE_UINT64_TYPE sqlite_uint64;294# else295    typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;296# endif297#elif defined(_MSC_VER) || defined(__BORLANDC__)298  typedef __int64 sqlite_int64;299  typedef unsigned __int64 sqlite_uint64;300#else301  typedef long long int sqlite_int64;302  typedef unsigned long long int sqlite_uint64;303#endif304typedef sqlite_int64 sqlite3_int64;305typedef sqlite_uint64 sqlite3_uint64;306307/*308** If compiling for a processor that lacks floating point support,309** substitute integer for floating-point.310*/311#ifdef SQLITE_OMIT_FLOATING_POINT312# define double sqlite3_int64313#endif314315/*316** CAPI3REF: Closing A Database Connection317** DESTRUCTOR: sqlite3318**319** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors320** for the [sqlite3] object.321** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if322** the [sqlite3] object is successfully destroyed and all associated323** resources are deallocated.324**325** Ideally, applications should [sqlite3_finalize | finalize] all326** [prepared statements], [sqlite3_blob_close | close] all [BLOB handles], and327** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated328** with the [sqlite3] object prior to attempting to close the object.329** ^If the database connection is associated with unfinalized prepared330** statements, BLOB handlers, and/or unfinished sqlite3_backup objects then331** sqlite3_close() will leave the database connection open and return332** [SQLITE_BUSY]. ^If sqlite3_close_v2() is called with unfinalized prepared333** statements, unclosed BLOB handlers, and/or unfinished sqlite3_backups,334** it returns [SQLITE_OK] regardless, but instead of deallocating the database335** connection immediately, it marks the database connection as an unusable336** "zombie" and makes arrangements to automatically deallocate the database337** connection after all prepared statements are finalized, all BLOB handles338** are closed, and all backups have finished. The sqlite3_close_v2() interface339** is intended for use with host languages that are garbage collected, and340** where the order in which destructors are called is arbitrary.341**342** ^If an [sqlite3] object is destroyed while a transaction is open,343** the transaction is automatically rolled back.344**345** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]346** must be either a NULL347** pointer or an [sqlite3] object pointer obtained348** from [sqlite3_open()], [sqlite3_open16()], or349** [sqlite3_open_v2()], and not previously closed.350** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer351** argument is a harmless no-op.352*/353SQLITE_API int sqlite3_close(sqlite3*);354SQLITE_API int sqlite3_close_v2(sqlite3*);355356/*357** The type for a callback function.358** This is legacy and deprecated.  It is included for historical359** compatibility and is not documented.360*/361typedef int (*sqlite3_callback)(void*,int,char**, char**);362363/*364** CAPI3REF: One-Step Query Execution Interface365** METHOD: sqlite3366**367** The sqlite3_exec() interface is a convenience wrapper around368** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],369** that allows an application to run multiple statements of SQL370** without having to use a lot of C code.371**372** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,373** semicolon-separate SQL statements passed into its 2nd argument,374** in the context of the [database connection] passed in as its 1st375** argument.  ^If the callback function of the 3rd argument to376** sqlite3_exec() is not NULL, then it is invoked for each result row377** coming out of the evaluated SQL statements.  ^The 4th argument to378** sqlite3_exec() is relayed through to the 1st argument of each379** callback invocation.  ^If the callback pointer to sqlite3_exec()380** is NULL, then no callback is ever invoked and result rows are381** ignored.382**383** ^If an error occurs while evaluating the SQL statements passed into384** sqlite3_exec(), then execution of the current statement stops and385** subsequent statements are skipped.  ^If the 5th parameter to sqlite3_exec()386** is not NULL then any error message is written into memory obtained387** from [sqlite3_malloc()] and passed back through the 5th parameter.388** To avoid memory leaks, the application should invoke [sqlite3_free()]389** on error message strings returned through the 5th parameter of390** sqlite3_exec() after the error message string is no longer needed.391** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors392** occur, then sqlite3_exec() sets the pointer in its 5th parameter to393** NULL before returning.394**395** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()396** routine returns SQLITE_ABORT without invoking the callback again and397** without running any subsequent SQL statements.398**399** ^The 2nd argument to the sqlite3_exec() callback function is the400** number of columns in the result.  ^The 3rd argument to the sqlite3_exec()401** callback is an array of pointers to strings obtained as if from402** [sqlite3_column_text()], one for each column.  ^If an element of a403** result row is NULL then the corresponding string pointer for the404** sqlite3_exec() callback is a NULL pointer.  ^The 4th argument to the405** sqlite3_exec() callback is an array of pointers to strings where each406** entry represents the name of corresponding result column as obtained407** from [sqlite3_column_name()].408**409** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer410** to an empty string, or a pointer that contains only whitespace and/or411** SQL comments, then no SQL statements are evaluated and the database412** is not changed.413**414** Restrictions:415**416** <ul>417** <li> The application must ensure that the 1st parameter to sqlite3_exec()418**      is a valid and open [database connection].419** <li> The application must not close the [database connection] specified by420**      the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.421** <li> The application must not modify the SQL statement text passed into422**      the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.423** <li> The application must not dereference the arrays or string pointers424**       passed as the 3rd and 4th callback parameters after it returns.425** </ul>426*/427SQLITE_API int sqlite3_exec(428  sqlite3*,                                  /* An open database */429  const char *sql,                           /* SQL to be evaluated */430  int (*callback)(void*,int,char**,char**),  /* Callback function */431  void *,                                    /* 1st argument to callback */432  char **errmsg                              /* Error msg written here */433);434435/*436** CAPI3REF: Result Codes437** KEYWORDS: {result code definitions}438**439** Many SQLite functions return an integer result code from the set shown440** here in order to indicate success or failure.441**442** New error codes may be added in future versions of SQLite.443**444** See also: [extended result code definitions]445*/446#define SQLITE_OK           0   /* Successful result */447/* beginning-of-error-codes */448#define SQLITE_ERROR        1   /* Generic error */449#define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */450#define SQLITE_PERM         3   /* Access permission denied */451#define SQLITE_ABORT        4   /* Callback routine requested an abort */452#define SQLITE_BUSY         5   /* The database file is locked */453#define SQLITE_LOCKED       6   /* A table in the database is locked */454#define SQLITE_NOMEM        7   /* A malloc() failed */455#define SQLITE_READONLY     8   /* Attempt to write a readonly database */456#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/457#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */458#define SQLITE_CORRUPT     11   /* The database disk image is malformed */459#define SQLITE_NOTFOUND    12   /* Unknown opcode in sqlite3_file_control() */460#define SQLITE_FULL        13   /* Insertion failed because database is full */461#define SQLITE_CANTOPEN    14   /* Unable to open the database file */462#define SQLITE_PROTOCOL    15   /* Database lock protocol error */463#define SQLITE_EMPTY       16   /* Internal use only */464#define SQLITE_SCHEMA      17   /* The database schema changed */465#define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */466#define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */467#define SQLITE_MISMATCH    20   /* Data type mismatch */468#define SQLITE_MISUSE      21   /* Library used incorrectly */469#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */470#define SQLITE_AUTH        23   /* Authorization denied */471#define SQLITE_FORMAT      24   /* Not used */472#define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */473#define SQLITE_NOTADB      26   /* File opened that is not a database file */474#define SQLITE_NOTICE      27   /* Notifications from sqlite3_log() */475#define SQLITE_WARNING     28   /* Warnings from sqlite3_log() */476#define SQLITE_ROW         100  /* sqlite3_step() has another row ready */477#define SQLITE_DONE        101  /* sqlite3_step() has finished executing */478/* end-of-error-codes */479480/*481** CAPI3REF: Extended Result Codes482** KEYWORDS: {extended result code definitions}483**484** In its default configuration, SQLite API routines return one of 30 integer485** [result codes].  However, experience has shown that many of486** these result codes are too coarse-grained.  They do not provide as487** much information about problems as programmers might like.  In an effort to488** address this, newer versions of SQLite (version 3.3.8 [dateof:3.3.8]489** and later) include490** support for additional result codes that provide more detailed information491** about errors. These [extended result codes] are enabled or disabled492** on a per database connection basis using the493** [sqlite3_extended_result_codes()] API.  Or, the extended code for494** the most recent error can be obtained using495** [sqlite3_extended_errcode()].496*/497#define SQLITE_ERROR_MISSING_COLLSEQ   (SQLITE_ERROR | (1<<8))498#define SQLITE_ERROR_RETRY             (SQLITE_ERROR | (2<<8))499#define SQLITE_ERROR_SNAPSHOT          (SQLITE_ERROR | (3<<8))500#define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))501#define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))502#define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))503#define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))504#define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))505#define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))506#define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7<<8))507#define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8<<8))508#define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9<<8))509#define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10<<8))510#define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11<<8))511#define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12<<8))512#define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))513#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))514#define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))515#define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))516#define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))517#define SQLITE_IOERR_SHMOPEN           (SQLITE_IOERR | (18<<8))518#define SQLITE_IOERR_SHMSIZE           (SQLITE_IOERR | (19<<8))519#define SQLITE_IOERR_SHMLOCK           (SQLITE_IOERR | (20<<8))520#define SQLITE_IOERR_SHMMAP            (SQLITE_IOERR | (21<<8))521#define SQLITE_IOERR_SEEK              (SQLITE_IOERR | (22<<8))522#define SQLITE_IOERR_DELETE_NOENT      (SQLITE_IOERR | (23<<8))523#define SQLITE_IOERR_MMAP              (SQLITE_IOERR | (24<<8))524#define SQLITE_IOERR_GETTEMPPATH       (SQLITE_IOERR | (25<<8))525#define SQLITE_IOERR_CONVPATH          (SQLITE_IOERR | (26<<8))526#define SQLITE_IOERR_VNODE             (SQLITE_IOERR | (27<<8))527#define SQLITE_IOERR_AUTH              (SQLITE_IOERR | (28<<8))528#define SQLITE_IOERR_BEGIN_ATOMIC      (SQLITE_IOERR | (29<<8))529#define SQLITE_IOERR_COMMIT_ATOMIC     (SQLITE_IOERR | (30<<8))530#define SQLITE_IOERR_ROLLBACK_ATOMIC   (SQLITE_IOERR | (31<<8))531#define SQLITE_IOERR_DATA              (SQLITE_IOERR | (32<<8))532#define SQLITE_IOERR_CORRUPTFS         (SQLITE_IOERR | (33<<8))533#define SQLITE_IOERR_IN_PAGE           (SQLITE_IOERR | (34<<8))534#define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED |  (1<<8))535#define SQLITE_LOCKED_VTAB             (SQLITE_LOCKED |  (2<<8))536#define SQLITE_BUSY_RECOVERY           (SQLITE_BUSY   |  (1<<8))537#define SQLITE_BUSY_SNAPSHOT           (SQLITE_BUSY   |  (2<<8))538#define SQLITE_BUSY_TIMEOUT            (SQLITE_BUSY   |  (3<<8))539#define SQLITE_CANTOPEN_NOTEMPDIR      (SQLITE_CANTOPEN | (1<<8))540#define SQLITE_CANTOPEN_ISDIR          (SQLITE_CANTOPEN | (2<<8))541#define SQLITE_CANTOPEN_FULLPATH       (SQLITE_CANTOPEN | (3<<8))542#define SQLITE_CANTOPEN_CONVPATH       (SQLITE_CANTOPEN | (4<<8))543#define SQLITE_CANTOPEN_DIRTYWAL       (SQLITE_CANTOPEN | (5<<8)) /* Not Used */544#define SQLITE_CANTOPEN_SYMLINK        (SQLITE_CANTOPEN | (6<<8))545#define SQLITE_CORRUPT_VTAB            (SQLITE_CORRUPT | (1<<8))546#define SQLITE_CORRUPT_SEQUENCE        (SQLITE_CORRUPT | (2<<8))547#define SQLITE_CORRUPT_INDEX           (SQLITE_CORRUPT | (3<<8))548#define SQLITE_READONLY_RECOVERY       (SQLITE_READONLY | (1<<8))549#define SQLITE_READONLY_CANTLOCK       (SQLITE_READONLY | (2<<8))550#define SQLITE_READONLY_ROLLBACK       (SQLITE_READONLY | (3<<8))551#define SQLITE_READONLY_DBMOVED        (SQLITE_READONLY | (4<<8))552#define SQLITE_READONLY_CANTINIT       (SQLITE_READONLY | (5<<8))553#define SQLITE_READONLY_DIRECTORY      (SQLITE_READONLY | (6<<8))554#define SQLITE_ABORT_ROLLBACK          (SQLITE_ABORT | (2<<8))555#define SQLITE_CONSTRAINT_CHECK        (SQLITE_CONSTRAINT | (1<<8))556#define SQLITE_CONSTRAINT_COMMITHOOK   (SQLITE_CONSTRAINT | (2<<8))557#define SQLITE_CONSTRAINT_FOREIGNKEY   (SQLITE_CONSTRAINT | (3<<8))558#define SQLITE_CONSTRAINT_FUNCTION     (SQLITE_CONSTRAINT | (4<<8))559#define SQLITE_CONSTRAINT_NOTNULL      (SQLITE_CONSTRAINT | (5<<8))560#define SQLITE_CONSTRAINT_PRIMARYKEY   (SQLITE_CONSTRAINT | (6<<8))561#define SQLITE_CONSTRAINT_TRIGGER      (SQLITE_CONSTRAINT | (7<<8))562#define SQLITE_CONSTRAINT_UNIQUE       (SQLITE_CONSTRAINT | (8<<8))563#define SQLITE_CONSTRAINT_VTAB         (SQLITE_CONSTRAINT | (9<<8))564#define SQLITE_CONSTRAINT_ROWID        (SQLITE_CONSTRAINT |(10<<8))565#define SQLITE_CONSTRAINT_PINNED       (SQLITE_CONSTRAINT |(11<<8))566#define SQLITE_CONSTRAINT_DATATYPE     (SQLITE_CONSTRAINT |(12<<8))567#define SQLITE_NOTICE_RECOVER_WAL      (SQLITE_NOTICE | (1<<8))568#define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))569#define SQLITE_NOTICE_RBU              (SQLITE_NOTICE | (3<<8))570#define SQLITE_WARNING_AUTOINDEX       (SQLITE_WARNING | (1<<8))571#define SQLITE_AUTH_USER               (SQLITE_AUTH | (1<<8))572#define SQLITE_OK_LOAD_PERMANENTLY     (SQLITE_OK | (1<<8))573#define SQLITE_OK_SYMLINK              (SQLITE_OK | (2<<8)) /* internal use only */574575/*576** CAPI3REF: Flags For File Open Operations577**578** These bit values are intended for use in the579** 3rd parameter to the [sqlite3_open_v2()] interface and580** in the 4th parameter to the [sqlite3_vfs.xOpen] method.581**582** Only those flags marked as "Ok for sqlite3_open_v2()" may be583** used as the third argument to the [sqlite3_open_v2()] interface.584** The other flags have historically been ignored by sqlite3_open_v2(),585** though future versions of SQLite might change so that an error is586** raised if any of the disallowed bits are passed into sqlite3_open_v2().587** Applications should not depend on the historical behavior.588**589** Note in particular that passing the SQLITE_OPEN_EXCLUSIVE flag into590** [sqlite3_open_v2()] does *not* cause the underlying database file591** to be opened using O_EXCL.  Passing SQLITE_OPEN_EXCLUSIVE into592** [sqlite3_open_v2()] has historically be a no-op and might become an593** error in future versions of SQLite.594*/595#define SQLITE_OPEN_READONLY         0x00000001  /* Ok for sqlite3_open_v2() */596#define SQLITE_OPEN_READWRITE        0x00000002  /* Ok for sqlite3_open_v2() */597#define SQLITE_OPEN_CREATE           0x00000004  /* Ok for sqlite3_open_v2() */598#define SQLITE_OPEN_DELETEONCLOSE    0x00000008  /* VFS only */599#define SQLITE_OPEN_EXCLUSIVE        0x00000010  /* VFS only */600#define SQLITE_OPEN_AUTOPROXY        0x00000020  /* VFS only */601#define SQLITE_OPEN_URI              0x00000040  /* Ok for sqlite3_open_v2() */602#define SQLITE_OPEN_MEMORY           0x00000080  /* Ok for sqlite3_open_v2() */603#define SQLITE_OPEN_MAIN_DB          0x00000100  /* VFS only */604#define SQLITE_OPEN_TEMP_DB          0x00000200  /* VFS only */605#define SQLITE_OPEN_TRANSIENT_DB     0x00000400  /* VFS only */606#define SQLITE_OPEN_MAIN_JOURNAL     0x00000800  /* VFS only */607#define SQLITE_OPEN_TEMP_JOURNAL     0x00001000  /* VFS only */608#define SQLITE_OPEN_SUBJOURNAL       0x00002000  /* VFS only */609#define SQLITE_OPEN_SUPER_JOURNAL    0x00004000  /* VFS only */610#define SQLITE_OPEN_NOMUTEX          0x00008000  /* Ok for sqlite3_open_v2() */611#define SQLITE_OPEN_FULLMUTEX        0x00010000  /* Ok for sqlite3_open_v2() */612#define SQLITE_OPEN_SHAREDCACHE      0x00020000  /* Ok for sqlite3_open_v2() */613#define SQLITE_OPEN_PRIVATECACHE     0x00040000  /* Ok for sqlite3_open_v2() */614#define SQLITE_OPEN_WAL              0x00080000  /* VFS only */615#define SQLITE_OPEN_NOFOLLOW         0x01000000  /* Ok for sqlite3_open_v2() */616#define SQLITE_OPEN_EXRESCODE        0x02000000  /* Extended result codes */617618/* Reserved:                         0x00F00000 */619/* Legacy compatibility: */620#define SQLITE_OPEN_MASTER_JOURNAL   0x00004000  /* VFS only */621622623/*624** CAPI3REF: Device Characteristics625**626** The xDeviceCharacteristics method of the [sqlite3_io_methods]627** object returns an integer which is a vector of these628** bit values expressing I/O characteristics of the mass storage629** device that holds the file that the [sqlite3_io_methods]630** refers to.631**632** The SQLITE_IOCAP_ATOMIC property means that all writes of633** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values634** mean that writes of blocks that are nnn bytes in size and635** are aligned to an address which is an integer multiple of636** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means637** that when data is appended to a file, the data is appended638** first then the size of the file is extended, never the other639** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that640** information is written to disk in the same order as calls641** to xWrite().  The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that642** after reboot following a crash or power loss, the only bytes in a643** file that were written at the application level might have changed644** and that adjacent bytes, even bytes within the same sector are645** guaranteed to be unchanged.  The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN646** flag indicates that a file cannot be deleted when open.  The647** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on648** read-only media and cannot be changed even by processes with649** elevated privileges.650**651** The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying652** filesystem supports doing multiple write operations atomically when those653** write operations are bracketed by [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] and654** [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE].655**656** The SQLITE_IOCAP_SUBPAGE_READ property means that it is ok to read657** from the database file in amounts that are not a multiple of the658** page size and that do not begin at a page boundary.  Without this659** property, SQLite is careful to only do full-page reads and write660** on aligned pages, with the one exception that it will do a sub-page661** read of the first page to access the database header.662*/663#define SQLITE_IOCAP_ATOMIC                 0x00000001664#define SQLITE_IOCAP_ATOMIC512              0x00000002665#define SQLITE_IOCAP_ATOMIC1K               0x00000004666#define SQLITE_IOCAP_ATOMIC2K               0x00000008667#define SQLITE_IOCAP_ATOMIC4K               0x00000010668#define SQLITE_IOCAP_ATOMIC8K               0x00000020669#define SQLITE_IOCAP_ATOMIC16K              0x00000040670#define SQLITE_IOCAP_ATOMIC32K              0x00000080671#define SQLITE_IOCAP_ATOMIC64K              0x00000100672#define SQLITE_IOCAP_SAFE_APPEND            0x00000200673#define SQLITE_IOCAP_SEQUENTIAL             0x00000400674#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN  0x00000800675#define SQLITE_IOCAP_POWERSAFE_OVERWRITE    0x00001000676#define SQLITE_IOCAP_IMMUTABLE              0x00002000677#define SQLITE_IOCAP_BATCH_ATOMIC           0x00004000678#define SQLITE_IOCAP_SUBPAGE_READ           0x00008000679680/*681** CAPI3REF: File Locking Levels682**683** SQLite uses one of these integer values as the second684** argument to calls it makes to the xLock() and xUnlock() methods685** of an [sqlite3_io_methods] object.  These values are ordered from686** lest restrictive to most restrictive.687**688** The argument to xLock() is always SHARED or higher.  The argument to689** xUnlock is either SHARED or NONE.690*/691#define SQLITE_LOCK_NONE          0       /* xUnlock() only */692#define SQLITE_LOCK_SHARED        1       /* xLock() or xUnlock() */693#define SQLITE_LOCK_RESERVED      2       /* xLock() only */694#define SQLITE_LOCK_PENDING       3       /* xLock() only */695#define SQLITE_LOCK_EXCLUSIVE     4       /* xLock() only */696697/*698** CAPI3REF: Synchronization Type Flags699**700** When SQLite invokes the xSync() method of an701** [sqlite3_io_methods] object it uses a combination of702** these integer values as the second argument.703**704** When the SQLITE_SYNC_DATAONLY flag is used, it means that the705** sync operation only needs to flush data to mass storage.  Inode706** information need not be flushed. If the lower four bits of the flag707** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.708** If the lower four bits equal SQLITE_SYNC_FULL, that means709** to use Mac OS X style fullsync instead of fsync().710**711** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags712** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL713** settings.  The [synchronous pragma] determines when calls to the714** xSync VFS method occur and applies uniformly across all platforms.715** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how716** energetic or rigorous or forceful the sync operations are and717** only make a difference on Mac OSX for the default SQLite code.718** (Third-party VFS implementations might also make the distinction719** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the720** operating systems natively supported by SQLite, only Mac OSX721** cares about the difference.)722*/723#define SQLITE_SYNC_NORMAL        0x00002724#define SQLITE_SYNC_FULL          0x00003725#define SQLITE_SYNC_DATAONLY      0x00010726727/*728** CAPI3REF: OS Interface Open File Handle729**730** An [sqlite3_file] object represents an open file in the731** [sqlite3_vfs | OS interface layer].  Individual OS interface732** implementations will733** want to subclass this object by appending additional fields734** for their own use.  The pMethods entry is a pointer to an735** [sqlite3_io_methods] object that defines methods for performing736** I/O operations on the open file.737*/738typedef struct sqlite3_file sqlite3_file;739struct sqlite3_file {740  const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */741};742743/*744** CAPI3REF: OS Interface File Virtual Methods Object745**746** Every file opened by the [sqlite3_vfs.xOpen] method populates an747** [sqlite3_file] object (or, more commonly, a subclass of the748** [sqlite3_file] object) with a pointer to an instance of this object.749** This object defines the methods used to perform various operations750** against the open file represented by the [sqlite3_file] object.751**752** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element753** to a non-NULL pointer, then the sqlite3_io_methods.xClose method754** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed.  The755** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]756** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element757** to NULL.758**759** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or760** [SQLITE_SYNC_FULL].  The first choice is the normal fsync().761** The second choice is a Mac OS X style fullsync.  The [SQLITE_SYNC_DATAONLY]762** flag may be ORed in to indicate that only the data of the file763** and not its inode needs to be synced.764**765** The integer values to xLock() and xUnlock() are one of766** <ul>767** <li> [SQLITE_LOCK_NONE],768** <li> [SQLITE_LOCK_SHARED],769** <li> [SQLITE_LOCK_RESERVED],770** <li> [SQLITE_LOCK_PENDING], or771** <li> [SQLITE_LOCK_EXCLUSIVE].772** </ul>773** xLock() upgrades the database file lock.  In other words, xLock() moves the774** database file lock in the direction NONE toward EXCLUSIVE. The argument to775** xLock() is always one of SHARED, RESERVED, PENDING, or EXCLUSIVE, never776** SQLITE_LOCK_NONE.  If the database file lock is already at or above the777** requested lock, then the call to xLock() is a no-op.778** xUnlock() downgrades the database file lock to either SHARED or NONE.779** If the lock is already at or below the requested lock state, then the call780** to xUnlock() is a no-op.781** The xCheckReservedLock() method checks whether any database connection,782** either in this process or in some other process, is holding a RESERVED,783** PENDING, or EXCLUSIVE lock on the file.  It returns, via its output784** pointer parameter, true if such a lock exists and false otherwise.785**786** The xFileControl() method is a generic interface that allows custom787** VFS implementations to directly control an open file using the788** [sqlite3_file_control()] interface.  The second "op" argument is an789** integer opcode.  The third argument is a generic pointer intended to790** point to a structure that may contain arguments or space in which to791** write return values.  Potential uses for xFileControl() might be792** functions to enable blocking locks with timeouts, to change the793** locking strategy (for example to use dot-file locks), to inquire794** about the status of a lock, or to break stale locks.  The SQLite795** core reserves all opcodes less than 100 for its own use.796** A [file control opcodes | list of opcodes] less than 100 is available.797** Applications that define a custom xFileControl method should use opcodes798** greater than 100 to avoid conflicts.  VFS implementations should799** return [SQLITE_NOTFOUND] for file control opcodes that they do not800** recognize.801**802** The xSectorSize() method returns the sector size of the803** device that underlies the file.  The sector size is the804** minimum write that can be performed without disturbing805** other bytes in the file.  The xDeviceCharacteristics()806** method returns a bit vector describing behaviors of the807** underlying device:808**809** <ul>810** <li> [SQLITE_IOCAP_ATOMIC]811** <li> [SQLITE_IOCAP_ATOMIC512]812** <li> [SQLITE_IOCAP_ATOMIC1K]813** <li> [SQLITE_IOCAP_ATOMIC2K]814** <li> [SQLITE_IOCAP_ATOMIC4K]815** <li> [SQLITE_IOCAP_ATOMIC8K]816** <li> [SQLITE_IOCAP_ATOMIC16K]817** <li> [SQLITE_IOCAP_ATOMIC32K]818** <li> [SQLITE_IOCAP_ATOMIC64K]819** <li> [SQLITE_IOCAP_SAFE_APPEND]820** <li> [SQLITE_IOCAP_SEQUENTIAL]821** <li> [SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN]822** <li> [SQLITE_IOCAP_POWERSAFE_OVERWRITE]823** <li> [SQLITE_IOCAP_IMMUTABLE]824** <li> [SQLITE_IOCAP_BATCH_ATOMIC]825** <li> [SQLITE_IOCAP_SUBPAGE_READ]826** </ul>827**828** The SQLITE_IOCAP_ATOMIC property means that all writes of829** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values830** mean that writes of blocks that are nnn bytes in size and831** are aligned to an address which is an integer multiple of832** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means833** that when data is appended to a file, the data is appended834** first then the size of the file is extended, never the other835** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that836** information is written to disk in the same order as calls837** to xWrite().838**839** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill840** in the unread portions of the buffer with zeros.  A VFS that841** fails to zero-fill short reads might seem to work.  However,842** failure to zero-fill short reads will eventually lead to843** database corruption.844*/845typedef struct sqlite3_io_methods sqlite3_io_methods;846struct sqlite3_io_methods {847  int iVersion;848  int (*xClose)(sqlite3_file*);849  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);850  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);851  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);852  int (*xSync)(sqlite3_file*, int flags);853  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);854  int (*xLock)(sqlite3_file*, int);855  int (*xUnlock)(sqlite3_file*, int);856  int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);857  int (*xFileControl)(sqlite3_file*, int op, void *pArg);858  int (*xSectorSize)(sqlite3_file*);859  int (*xDeviceCharacteristics)(sqlite3_file*);860  /* Methods above are valid for version 1 */861  int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);862  int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);863  void (*xShmBarrier)(sqlite3_file*);864  int (*xShmUnmap)(sqlite3_file*, int deleteFlag);865  /* Methods above are valid for version 2 */866  int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);867  int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);868  /* Methods above are valid for version 3 */869  /* Additional methods may be added in future releases */870};871872/*873** CAPI3REF: Standard File Control Opcodes874** KEYWORDS: {file control opcodes} {file control opcode}875**876** These integer constants are opcodes for the xFileControl method877** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]878** interface.879**880** <ul>881** <li>[[SQLITE_FCNTL_LOCKSTATE]]882** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This883** opcode causes the xFileControl method to write the current state of884** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],885** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])886** into an integer that the pArg argument points to.887** This capability is only available if SQLite is compiled with [SQLITE_DEBUG].888**889** <li>[[SQLITE_FCNTL_SIZE_HINT]]890** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS891** layer a hint of how large the database file will grow to be during the892** current transaction.  This hint is not guaranteed to be accurate but it893** is often close.  The underlying VFS might choose to preallocate database894** file space based on this hint in order to help writes to the database895** file run faster.896**897** <li>[[SQLITE_FCNTL_SIZE_LIMIT]]898** The [SQLITE_FCNTL_SIZE_LIMIT] opcode is used by in-memory VFS that899** implements [sqlite3_deserialize()] to set an upper bound on the size900** of the in-memory database.  The argument is a pointer to a [sqlite3_int64].901** If the integer pointed to is negative, then it is filled in with the902** current limit.  Otherwise the limit is set to the larger of the value903** of the integer pointed to and the current database size.  The integer904** pointed to is set to the new limit.905**906** <li>[[SQLITE_FCNTL_CHUNK_SIZE]]907** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS908** extends and truncates the database file in chunks of a size specified909** by the user. The fourth argument to [sqlite3_file_control()] should910** point to an integer (type int) containing the new chunk-size to use911** for the nominated database. Allocating database file space in large912** chunks (say 1MB at a time), may reduce file-system fragmentation and913** improve performance on some systems.914**915** <li>[[SQLITE_FCNTL_FILE_POINTER]]916** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer917** to the [sqlite3_file] object associated with a particular database918** connection.  See also [SQLITE_FCNTL_JOURNAL_POINTER].919**920** <li>[[SQLITE_FCNTL_JOURNAL_POINTER]]921** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer922** to the [sqlite3_file] object associated with the journal file (either923** the [rollback journal] or the [write-ahead log]) for a particular database924** connection.  See also [SQLITE_FCNTL_FILE_POINTER].925**926** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]927** No longer in use.928**929** <li>[[SQLITE_FCNTL_SYNC]]930** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and931** sent to the VFS immediately before the xSync method is invoked on a932** database file descriptor. Or, if the xSync method is not invoked933** because the user has configured SQLite with934** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place935** of the xSync method. In most cases, the pointer argument passed with936** this file-control is NULL. However, if the database file is being synced937** as part of a multi-database commit, the argument points to a nul-terminated938** string containing the transactions super-journal file name. VFSes that939** do not need this signal should silently ignore this opcode. Applications940** should not call [sqlite3_file_control()] with this opcode as doing so may941** disrupt the operation of the specialized VFSes that do require it.942**943** <li>[[SQLITE_FCNTL_COMMIT_PHASETWO]]944** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite945** and sent to the VFS after a transaction has been committed immediately946** but before the database is unlocked. VFSes that do not need this signal947** should silently ignore this opcode. Applications should not call948** [sqlite3_file_control()] with this opcode as doing so may disrupt the949** operation of the specialized VFSes that do require it.950**951** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]]952** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic953** retry counts and intervals for certain disk I/O operations for the954** windows [VFS] in order to provide robustness in the presence of955** anti-virus programs.  By default, the windows VFS will retry file read,956** file write, and file delete operations up to 10 times, with a delay957** of 25 milliseconds before the first retry and with the delay increasing958** by an additional 25 milliseconds with each subsequent retry.  This959** opcode allows these two values (10 retries and 25 milliseconds of delay)960** to be adjusted.  The values are changed for all database connections961** within the same process.  The argument is a pointer to an array of two962** integers where the first integer is the new retry count and the second963** integer is the delay.  If either integer is negative, then the setting964** is not changed but instead the prior value of that setting is written965** into the array entry, allowing the current retry settings to be966** interrogated.  The zDbName parameter is ignored.967**968** <li>[[SQLITE_FCNTL_PERSIST_WAL]]969** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the970** persistent [WAL | Write Ahead Log] setting.  By default, the auxiliary971** write ahead log ([WAL file]) and shared memory972** files used for transaction control973** are automatically deleted when the latest connection to the database974** closes.  Setting persistent WAL mode causes those files to persist after975** close.  Persisting the files is useful when other processes that do not976** have write permission on the directory containing the database file want977** to read the database file, as the WAL and shared memory files must exist978** in order for the database to be readable.  The fourth parameter to979** [sqlite3_file_control()] for this opcode should be a pointer to an integer.980** That integer is 0 to disable persistent WAL mode or 1 to enable persistent981** WAL mode.  If the integer is -1, then it is overwritten with the current982** WAL persistence setting.983**984** <li>[[SQLITE_FCNTL_POWERSAFE_OVERWRITE]]985** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the986** persistent "powersafe-overwrite" or "PSOW" setting.  The PSOW setting987** determines the [SQLITE_IOCAP_POWERSAFE_OVERWRITE] bit of the988** xDeviceCharacteristics methods. The fourth parameter to989** [sqlite3_file_control()] for this opcode should be a pointer to an integer.990** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage991** mode.  If the integer is -1, then it is overwritten with the current992** zero-damage mode setting.993**994** <li>[[SQLITE_FCNTL_OVERWRITE]]995** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening996** a write transaction to indicate that, unless it is rolled back for some997** reason, the entire database file will be overwritten by the current998** transaction. This is used by VACUUM operations.999**1000** <li>[[SQLITE_FCNTL_VFSNAME]]1001** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of1002** all [VFSes] in the VFS stack.  The names are of all VFS shims and the1003** final bottom-level VFS are written into memory obtained from1004** [sqlite3_malloc()] and the result is stored in the char* variable1005** that the fourth parameter of [sqlite3_file_control()] points to.1006** The caller is responsible for freeing the memory when done.  As with1007** all file-control actions, there is no guarantee that this will actually1008** do anything.  Callers should initialize the char* variable to a NULL1009** pointer in case this file-control is not implemented.  This file-control1010** is intended for diagnostic use only.1011**1012** <li>[[SQLITE_FCNTL_VFS_POINTER]]1013** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level1014** [VFSes] currently in use.  ^(The argument X in1015** sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be1016** of type "[sqlite3_vfs] **".  This opcodes will set *X1017** to a pointer to the top-level VFS.)^1018** ^When there are multiple VFS shims in the stack, this opcode finds the1019** upper-most shim only.1020**1021** <li>[[SQLITE_FCNTL_PRAGMA]]1022** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]1023** file control is sent to the open [sqlite3_file] object corresponding1024** to the database file to which the pragma statement refers. ^The argument1025** to the [SQLITE_FCNTL_PRAGMA] file control is an array of1026** pointers to strings (char**) in which the second element of the array1027** is the name of the pragma and the third element is the argument to the1028** pragma or NULL if the pragma has no argument.  ^The handler for an1029** [SQLITE_FCNTL_PRAGMA] file control can optionally make the first element1030** of the char** argument point to a string obtained from [sqlite3_mprintf()]1031** or the equivalent and that string will become the result of the pragma or1032** the error message if the pragma fails. ^If the1033** [SQLITE_FCNTL_PRAGMA] file control returns [SQLITE_NOTFOUND], then normal1034** [PRAGMA] processing continues.  ^If the [SQLITE_FCNTL_PRAGMA]1035** file control returns [SQLITE_OK], then the parser assumes that the1036** VFS has handled the PRAGMA itself and the parser generates a no-op1037** prepared statement if result string is NULL, or that returns a copy1038** of the result string if the string is non-NULL.1039** ^If the [SQLITE_FCNTL_PRAGMA] file control returns1040** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means1041** that the VFS encountered an error while handling the [PRAGMA] and the1042** compilation of the PRAGMA fails with an error.  ^The [SQLITE_FCNTL_PRAGMA]1043** file control occurs at the beginning of pragma statement analysis and so1044** it is able to override built-in [PRAGMA] statements.1045**1046** <li>[[SQLITE_FCNTL_BUSYHANDLER]]1047** ^The [SQLITE_FCNTL_BUSYHANDLER]1048** file-control may be invoked by SQLite on the database file handle1049** shortly after it is opened in order to provide a custom VFS with access1050** to the connection's busy-handler callback. The argument is of type (void**)1051** - an array of two (void *) values. The first (void *) actually points1052** to a function of type (int (*)(void *)). In order to invoke the connection's1053** busy-handler, this function should be invoked with the second (void *) in1054** the array as the only argument. If it returns non-zero, then the operation1055** should be retried. If it returns zero, the custom VFS should abandon the1056** current operation.1057**1058** <li>[[SQLITE_FCNTL_TEMPFILENAME]]1059** ^Applications can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control1060** to have SQLite generate a1061** temporary filename using the same algorithm that is followed to generate1062** temporary filenames for TEMP tables and other internal uses.  The1063** argument should be a char** which will be filled with the filename1064** written into memory obtained from [sqlite3_malloc()].  The caller should1065** invoke [sqlite3_free()] on the result to avoid a memory leak.1066**1067** <li>[[SQLITE_FCNTL_MMAP_SIZE]]1068** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the1069** maximum number of bytes that will be used for memory-mapped I/O.1070** The argument is a pointer to a value of type sqlite3_int64 that1071** is an advisory maximum number of bytes in the file to memory map.  The1072** pointer is overwritten with the old value.  The limit is not changed if1073** the value originally pointed to is negative, and so the current limit1074** can be queried by passing in a pointer to a negative number.  This1075** file-control is used internally to implement [PRAGMA mmap_size].1076**1077** <li>[[SQLITE_FCNTL_TRACE]]1078** The [SQLITE_FCNTL_TRACE] file control provides advisory information1079** to the VFS about what the higher layers of the SQLite stack are doing.1080** This file control is used by some VFS activity tracing [shims].1081** The argument is a zero-terminated string.  Higher layers in the1082** SQLite stack may generate instances of this file control if1083** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.1084**1085** <li>[[SQLITE_FCNTL_HAS_MOVED]]1086** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a1087** pointer to an integer and it writes a boolean into that integer depending1088** on whether or not the file has been renamed, moved, or deleted since it1089** was first opened.1090**1091** <li>[[SQLITE_FCNTL_WIN32_GET_HANDLE]]1092** The [SQLITE_FCNTL_WIN32_GET_HANDLE] opcode can be used to obtain the1093** underlying native file handle associated with a file handle.  This file1094** control interprets its argument as a pointer to a native file handle and1095** writes the resulting value there.1096**1097** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]]1098** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging.  This1099** opcode causes the xFileControl method to swap the file handle with the one1100** pointed to by the pArg argument.  This capability is used during testing1101** and only needs to be supported when SQLITE_TEST is defined.1102**1103** <li>[[SQLITE_FCNTL_NULL_IO]]1104** The [SQLITE_FCNTL_NULL_IO] opcode sets the low-level file descriptor1105** or file handle for the [sqlite3_file] object such that it will no longer1106** read or write to the database file.1107**1108** <li>[[SQLITE_FCNTL_WAL_BLOCK]]1109** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might1110** be advantageous to block on the next WAL lock if the lock is not immediately1111** available.  The WAL subsystem issues this signal during rare1112** circumstances in order to fix a problem with priority inversion.1113** Applications should <em>not</em> use this file-control.1114**1115** <li>[[SQLITE_FCNTL_ZIPVFS]]1116** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other1117** VFS should return SQLITE_NOTFOUND for this opcode.1118**1119** <li>[[SQLITE_FCNTL_RBU]]1120** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by1121** the RBU extension only.  All other VFS should return SQLITE_NOTFOUND for1122** this opcode.1123**1124** <li>[[SQLITE_FCNTL_BEGIN_ATOMIC_WRITE]]1125** If the [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] opcode returns SQLITE_OK, then1126** the file descriptor is placed in "batch write mode", which1127** means all subsequent write operations will be deferred and done1128** atomically at the next [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE].  Systems1129** that do not support batch atomic writes will return SQLITE_NOTFOUND.1130** ^Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to1131** the closing [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] or1132** [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE], SQLite will make1133** no VFS interface calls on the same [sqlite3_file] file descriptor1134** except for calls to the xWrite method and the xFileControl method1135** with [SQLITE_FCNTL_SIZE_HINT].1136**1137** <li>[[SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]]1138** The [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] opcode causes all write1139** operations since the previous successful call to1140** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be performed atomically.1141** This file control returns [SQLITE_OK] if and only if the writes were1142** all performed successfully and have been committed to persistent storage.1143** ^Regardless of whether or not it is successful, this file control takes1144** the file descriptor out of batch write mode so that all subsequent1145** write operations are independent.1146** ^SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without1147** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].1148**1149** <li>[[SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE]]1150** The [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE] opcode causes all write1151** operations since the previous successful call to1152** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be rolled back.1153** ^This file control takes the file descriptor out of batch write mode1154** so that all subsequent write operations are independent.1155** ^SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without1156** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].1157**1158** <li>[[SQLITE_FCNTL_LOCK_TIMEOUT]]1159** The [SQLITE_FCNTL_LOCK_TIMEOUT] opcode is used to configure a VFS1160** to block for up to M milliseconds before failing when attempting to1161** obtain a file lock using the xLock or xShmLock methods of the VFS.1162** The parameter is a pointer to a 32-bit signed integer that contains1163** the value that M is to be set to. Before returning, the 32-bit signed1164** integer is overwritten with the previous value of M.1165**1166** <li>[[SQLITE_FCNTL_DATA_VERSION]]1167** The [SQLITE_FCNTL_DATA_VERSION] opcode is used to detect changes to1168** a database file.  The argument is a pointer to a 32-bit unsigned integer.1169** The "data version" for the pager is written into the pointer.  The1170** "data version" changes whenever any change occurs to the corresponding1171** database file, either through SQL statements on the same database1172** connection or through transactions committed by separate database1173** connections possibly in other processes. The [sqlite3_total_changes()]1174** interface can be used to find if any database on the connection has changed,1175** but that interface responds to changes on TEMP as well as MAIN and does1176** not provide a mechanism to detect changes to MAIN only.  Also, the1177** [sqlite3_total_changes()] interface responds to internal changes only and1178** omits changes made by other database connections.  The1179** [PRAGMA data_version] command provides a mechanism to detect changes to1180** a single attached database that occur due to other database connections,1181** but omits changes implemented by the database connection on which it is1182** called.  This file control is the only mechanism to detect changes that1183** happen either internally or externally and that are associated with1184** a particular attached database.1185**1186** <li>[[SQLITE_FCNTL_CKPT_START]]1187** The [SQLITE_FCNTL_CKPT_START] opcode is invoked from within a checkpoint1188** in wal mode before the client starts to copy pages from the wal1189** file to the database file.1190**1191** <li>[[SQLITE_FCNTL_CKPT_DONE]]1192** The [SQLITE_FCNTL_CKPT_DONE] opcode is invoked from within a checkpoint1193** in wal mode after the client has finished copying pages from the wal1194** file to the database file, but before the *-shm file is updated to1195** record the fact that the pages have been checkpointed.1196**1197** <li>[[SQLITE_FCNTL_EXTERNAL_READER]]1198** The EXPERIMENTAL [SQLITE_FCNTL_EXTERNAL_READER] opcode is used to detect1199** whether or not there is a database client in another process with a wal-mode1200** transaction open on the database or not. It is only available on unix.The1201** (void*) argument passed with this file-control should be a pointer to a1202** value of type (int). The integer value is set to 1 if the database is a wal1203** mode database and there exists at least one client in another process that1204** currently has an SQL transaction open on the database. It is set to 0 if1205** the database is not a wal-mode db, or if there is no such connection in any1206** other process. This opcode cannot be used to detect transactions opened1207** by clients within the current process, only within other processes.1208**1209** <li>[[SQLITE_FCNTL_CKSM_FILE]]1210** The [SQLITE_FCNTL_CKSM_FILE] opcode is for use internally by the1211** [checksum VFS shim] only.1212**1213** <li>[[SQLITE_FCNTL_RESET_CACHE]]1214** If there is currently no transaction open on the database, and the1215** database is not a temp db, then the [SQLITE_FCNTL_RESET_CACHE] file-control1216** purges the contents of the in-memory page cache. If there is an open1217** transaction, or if the db is a temp-db, this opcode is a no-op, not an error.1218** </ul>1219*/1220#define SQLITE_FCNTL_LOCKSTATE               11221#define SQLITE_FCNTL_GET_LOCKPROXYFILE       21222#define SQLITE_FCNTL_SET_LOCKPROXYFILE       31223#define SQLITE_FCNTL_LAST_ERRNO              41224#define SQLITE_FCNTL_SIZE_HINT               51225#define SQLITE_FCNTL_CHUNK_SIZE              61226#define SQLITE_FCNTL_FILE_POINTER            71227#define SQLITE_FCNTL_SYNC_OMITTED            81228#define SQLITE_FCNTL_WIN32_AV_RETRY          91229#define SQLITE_FCNTL_PERSIST_WAL            101230#define SQLITE_FCNTL_OVERWRITE              111231#define SQLITE_FCNTL_VFSNAME                121232#define SQLITE_FCNTL_POWERSAFE_OVERWRITE    131233#define SQLITE_FCNTL_PRAGMA                 141234#define SQLITE_FCNTL_BUSYHANDLER            151235#define SQLITE_FCNTL_TEMPFILENAME           161236#define SQLITE_FCNTL_MMAP_SIZE              181237#define SQLITE_FCNTL_TRACE                  191238#define SQLITE_FCNTL_HAS_MOVED              201239#define SQLITE_FCNTL_SYNC                   211240#define SQLITE_FCNTL_COMMIT_PHASETWO        221241#define SQLITE_FCNTL_WIN32_SET_HANDLE       231242#define SQLITE_FCNTL_WAL_BLOCK              241243#define SQLITE_FCNTL_ZIPVFS                 251244#define SQLITE_FCNTL_RBU                    261245#define SQLITE_FCNTL_VFS_POINTER            271246#define SQLITE_FCNTL_JOURNAL_POINTER        281247#define SQLITE_FCNTL_WIN32_GET_HANDLE       291248#define SQLITE_FCNTL_PDB                    301249#define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE     311250#define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE    321251#define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE  331252#define SQLITE_FCNTL_LOCK_TIMEOUT           341253#define SQLITE_FCNTL_DATA_VERSION           351254#define SQLITE_FCNTL_SIZE_LIMIT             361255#define SQLITE_FCNTL_CKPT_DONE              371256#define SQLITE_FCNTL_RESERVE_BYTES          381257#define SQLITE_FCNTL_CKPT_START             391258#define SQLITE_FCNTL_EXTERNAL_READER        401259#define SQLITE_FCNTL_CKSM_FILE              411260#define SQLITE_FCNTL_RESET_CACHE            421261#define SQLITE_FCNTL_NULL_IO                4312621263/* deprecated names */1264#define SQLITE_GET_LOCKPROXYFILE      SQLITE_FCNTL_GET_LOCKPROXYFILE1265#define SQLITE_SET_LOCKPROXYFILE      SQLITE_FCNTL_SET_LOCKPROXYFILE1266#define SQLITE_LAST_ERRNO             SQLITE_FCNTL_LAST_ERRNO126712681269/*1270** CAPI3REF: Mutex Handle1271**1272** The mutex module within SQLite defines [sqlite3_mutex] to be an1273** abstract type for a mutex object.  The SQLite core never looks1274** at the internal representation of an [sqlite3_mutex].  It only1275** deals with pointers to the [sqlite3_mutex] object.1276**1277** Mutexes are created using [sqlite3_mutex_alloc()].1278*/1279typedef struct sqlite3_mutex sqlite3_mutex;12801281/*1282** CAPI3REF: Loadable Extension Thunk1283**1284** A pointer to the opaque sqlite3_api_routines structure is passed as1285** the third parameter to entry points of [loadable extensions].  This1286** structure must be typedefed in order to work around compiler warnings1287** on some platforms.1288*/1289typedef struct sqlite3_api_routines sqlite3_api_routines;12901291/*1292** CAPI3REF: File Name1293**1294** Type [sqlite3_filename] is used by SQLite to pass filenames to the1295** xOpen method of a [VFS]. It may be cast to (const char*) and treated1296** as a normal, nul-terminated, UTF-8 buffer containing the filename, but1297** may also be passed to special APIs such as:1298**1299** <ul>1300** <li>  sqlite3_filename_database()1301** <li>  sqlite3_filename_journal()1302** <li>  sqlite3_filename_wal()1303** <li>  sqlite3_uri_parameter()1304** <li>  sqlite3_uri_boolean()1305** <li>  sqlite3_uri_int64()1306** <li>  sqlite3_uri_key()1307** </ul>1308*/1309typedef const char *sqlite3_filename;13101311/*1312** CAPI3REF: OS Interface Object1313**1314** An instance of the sqlite3_vfs object defines the interface between1315** the SQLite core and the underlying operating system.  The "vfs"1316** in the name of the object stands for "virtual file system".  See1317** the [VFS | VFS documentation] for further information.1318**1319** The VFS interface is sometimes extended by adding new methods onto1320** the end.  Each time such an extension occurs, the iVersion field1321** is incremented.  The iVersion value started out as 1 in1322** SQLite [version 3.5.0] on [dateof:3.5.0], then increased to 21323** with SQLite [version 3.7.0] on [dateof:3.7.0], and then increased1324** to 3 with SQLite [version 3.7.6] on [dateof:3.7.6].  Additional fields1325** may be appended to the sqlite3_vfs object and the iVersion value1326** may increase again in future versions of SQLite.1327** Note that due to an oversight, the structure1328** of the sqlite3_vfs object changed in the transition from1329** SQLite [version 3.5.9] to [version 3.6.0] on [dateof:3.6.0]1330** and yet the iVersion field was not increased.1331**1332** The szOsFile field is the size of the subclassed [sqlite3_file]1333** structure used by this VFS.  mxPathname is the maximum length of1334** a pathname in this VFS.1335**1336** Registered sqlite3_vfs objects are kept on a linked list formed by1337** the pNext pointer.  The [sqlite3_vfs_register()]1338** and [sqlite3_vfs_unregister()] interfaces manage this list1339** in a thread-safe way.  The [sqlite3_vfs_find()] interface1340** searches the list.  Neither the application code nor the VFS1341** implementation should use the pNext pointer.1342**1343** The pNext field is the only field in the sqlite3_vfs1344** structure that SQLite will ever modify.  SQLite will only access1345** or modify this field while holding a particular static mutex.1346** The application should never modify anything within the sqlite3_vfs1347** object once the object has been registered.1348**1349** The zName field holds the name of the VFS module.  The name must1350** be unique across all VFS modules.1351**1352** [[sqlite3_vfs.xOpen]]1353** ^SQLite guarantees that the zFilename parameter to xOpen1354** is either a NULL pointer or string obtained1355** from xFullPathname() with an optional suffix added.1356** ^If a suffix is added to the zFilename parameter, it will1357** consist of a single "-" character followed by no more than1358** 11 alphanumeric and/or "-" characters.1359** ^SQLite further guarantees that1360** the string will be valid and unchanged until xClose() is1361** called. Because of the previous sentence,1362** the [sqlite3_file] can safely store a pointer to the1363** filename if it needs to remember the filename for some reason.1364** If the zFilename parameter to xOpen is a NULL pointer then xOpen1365** must invent its own temporary name for the file.  ^Whenever the1366** xFilename parameter is NULL it will also be the case that the1367** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].1368**1369** The flags argument to xOpen() includes all bits set in1370** the flags argument to [sqlite3_open_v2()].  Or if [sqlite3_open()]1371** or [sqlite3_open16()] is used, then flags includes at least1372** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].1373** If xOpen() opens a file read-only then it sets *pOutFlags to1374** include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be set.1375**1376** ^(SQLite will also add one of the following flags to the xOpen()1377** call, depending on the object being opened:1378**1379** <ul>1380** <li>  [SQLITE_OPEN_MAIN_DB]1381** <li>  [SQLITE_OPEN_MAIN_JOURNAL]1382** <li>  [SQLITE_OPEN_TEMP_DB]1383** <li>  [SQLITE_OPEN_TEMP_JOURNAL]1384** <li>  [SQLITE_OPEN_TRANSIENT_DB]1385** <li>  [SQLITE_OPEN_SUBJOURNAL]1386** <li>  [SQLITE_OPEN_SUPER_JOURNAL]1387** <li>  [SQLITE_OPEN_WAL]1388** </ul>)^1389**1390** The file I/O implementation can use the object type flags to1391** change the way it deals with files.  For example, an application1392** that does not care about crash recovery or rollback might make1393** the open of a journal file a no-op.  Writes to this journal would1394** also be no-ops, and any attempt to read the journal would return1395** SQLITE_IOERR.  Or the implementation might recognize that a database1396** file will be doing page-aligned sector reads and writes in a random1397** order and set up its I/O subsystem accordingly.1398**1399** SQLite might also add one of the following flags to the xOpen method:1400**1401** <ul>1402** <li> [SQLITE_OPEN_DELETEONCLOSE]1403** <li> [SQLITE_OPEN_EXCLUSIVE]1404** </ul>1405**1406** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be1407** deleted when it is closed.  ^The [SQLITE_OPEN_DELETEONCLOSE]1408** will be set for TEMP databases and their journals, transient1409** databases, and subjournals.1410**1411** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction1412** with the [SQLITE_OPEN_CREATE] flag, which are both directly1413** analogous to the O_EXCL and O_CREAT flags of the POSIX open()1414** API.  The SQLITE_OPEN_EXCLUSIVE flag, when paired with the1415** SQLITE_OPEN_CREATE, is used to indicate that file should always1416** be created, and that it is an error if it already exists.1417** It is <i>not</i> used to indicate the file should be opened1418** for exclusive access.1419**1420** ^At least szOsFile bytes of memory are allocated by SQLite1421** to hold the [sqlite3_file] structure passed as the third1422** argument to xOpen.  The xOpen method does not have to1423** allocate the structure; it should just fill it in.  Note that1424** the xOpen method must set the sqlite3_file.pMethods to either1425** a valid [sqlite3_io_methods] object or to NULL.  xOpen must do1426** this even if the open fails.  SQLite expects that the sqlite3_file.pMethods1427** element will be valid after xOpen returns regardless of the success1428** or failure of the xOpen call.1429**1430** [[sqlite3_vfs.xAccess]]1431** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]1432** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to1433** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]1434** to test whether a file is at least readable.  The SQLITE_ACCESS_READ1435** flag is never actually used and is not implemented in the built-in1436** VFSes of SQLite.  The file is named by the second argument and can be a1437** directory. The xAccess method returns [SQLITE_OK] on success or some1438** non-zero error code if there is an I/O error or if the name of1439** the file given in the second argument is illegal.  If SQLITE_OK1440** is returned, then non-zero or zero is written into *pResOut to indicate1441** whether or not the file is accessible.1442**1443** ^SQLite will always allocate at least mxPathname+1 bytes for the1444** output buffer xFullPathname.  The exact size of the output buffer1445** is also passed as a parameter to both  methods. If the output buffer1446** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is1447** handled as a fatal error by SQLite, vfs implementations should endeavor1448** to prevent this by setting mxPathname to a sufficiently large value.1449**1450** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()1451** interfaces are not strictly a part of the filesystem, but they are1452** included in the VFS structure for completeness.1453** The xRandomness() function attempts to return nBytes bytes1454** of good-quality randomness into zOut.  The return value is1455** the actual number of bytes of randomness obtained.1456** The xSleep() method causes the calling thread to sleep for at1457** least the number of microseconds given.  ^The xCurrentTime()1458** method returns a Julian Day Number for the current date and time as1459** a floating point value.1460** ^The xCurrentTimeInt64() method returns, as an integer, the Julian1461** Day Number multiplied by 86400000 (the number of milliseconds in1462** a 24-hour day).1463** ^SQLite will use the xCurrentTimeInt64() method to get the current1464** date and time if that method is available (if iVersion is 2 or1465** greater and the function pointer is not NULL) and will fall back1466** to xCurrentTime() if xCurrentTimeInt64() is unavailable.1467**1468** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces1469** are not used by the SQLite core.  These optional interfaces are provided1470** by some VFSes to facilitate testing of the VFS code. By overriding1471** system calls with functions under its control, a test program can1472** simulate faults and error conditions that would otherwise be difficult1473** or impossible to induce.  The set of system calls that can be overridden1474** varies from one VFS to another, and from one version of the same VFS to the1475** next.  Applications that use these interfaces must be prepared for any1476** or all of these interfaces to be NULL or for their behavior to change1477** from one release to the next.  Applications must not attempt to access1478** any of these methods if the iVersion of the VFS is less than 3.1479*/1480typedef struct sqlite3_vfs sqlite3_vfs;1481typedef void (*sqlite3_syscall_ptr)(void);1482struct sqlite3_vfs {1483  int iVersion;            /* Structure version number (currently 3) */1484  int szOsFile;            /* Size of subclassed sqlite3_file */1485  int mxPathname;          /* Maximum file pathname length */1486  sqlite3_vfs *pNext;      /* Next registered VFS */1487  const char *zName;       /* Name of this virtual file system */1488  void *pAppData;          /* Pointer to application-specific data */1489  int (*xOpen)(sqlite3_vfs*, sqlite3_filename zName, sqlite3_file*,1490               int flags, int *pOutFlags);1491  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);1492  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);1493  int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);1494  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);1495  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);1496  void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);1497  void (*xDlClose)(sqlite3_vfs*, void*);1498  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);1499  int (*xSleep)(sqlite3_vfs*, int microseconds);1500  int (*xCurrentTime)(sqlite3_vfs*, double*);1501  int (*xGetLastError)(sqlite3_vfs*, int, char *);1502  /*1503  ** The methods above are in version 1 of the sqlite_vfs object1504  ** definition.  Those that follow are added in version 2 or later1505  */1506  int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);1507  /*1508  ** The methods above are in versions 1 and 2 of the sqlite_vfs object.1509  ** Those below are for version 3 and greater.1510  */1511  int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);1512  sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);1513  const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);1514  /*1515  ** The methods above are in versions 1 through 3 of the sqlite_vfs object.1516  ** New fields may be appended in future versions.  The iVersion1517  ** value will increment whenever this happens.1518  */1519};15201521/*1522** CAPI3REF: Flags for the xAccess VFS method1523**1524** These integer constants can be used as the third parameter to1525** the xAccess method of an [sqlite3_vfs] object.  They determine1526** what kind of permissions the xAccess method is looking for.1527** With SQLITE_ACCESS_EXISTS, the xAccess method1528** simply checks whether the file exists.1529** With SQLITE_ACCESS_READWRITE, the xAccess method1530** checks whether the named directory is both readable and writable1531** (in other words, if files can be added, removed, and renamed within1532** the directory).1533** The SQLITE_ACCESS_READWRITE constant is currently used only by the1534** [temp_store_directory pragma], though this could change in a future1535** release of SQLite.1536** With SQLITE_ACCESS_READ, the xAccess method1537** checks whether the file is readable.  The SQLITE_ACCESS_READ constant is1538** currently unused, though it might be used in a future release of1539** SQLite.1540*/1541#define SQLITE_ACCESS_EXISTS    01542#define SQLITE_ACCESS_READWRITE 1   /* Used by PRAGMA temp_store_directory */1543#define SQLITE_ACCESS_READ      2   /* Unused */15441545/*1546** CAPI3REF: Flags for the xShmLock VFS method1547**1548** These integer constants define the various locking operations1549** allowed by the xShmLock method of [sqlite3_io_methods].  The1550** following are the only legal combinations of flags to the1551** xShmLock method:1552**1553** <ul>1554** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_SHARED1555** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE1556** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED1557** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE1558** </ul>1559**1560** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as1561** was given on the corresponding lock.1562**1563** The xShmLock method can transition between unlocked and SHARED or1564** between unlocked and EXCLUSIVE.  It cannot transition between SHARED1565** and EXCLUSIVE.1566*/1567#define SQLITE_SHM_UNLOCK       11568#define SQLITE_SHM_LOCK         21569#define SQLITE_SHM_SHARED       41570#define SQLITE_SHM_EXCLUSIVE    815711572/*1573** CAPI3REF: Maximum xShmLock index1574**1575** The xShmLock method on [sqlite3_io_methods] may use values1576** between 0 and this upper bound as its "offset" argument.1577** The SQLite core will never attempt to acquire or release a1578** lock outside of this range1579*/1580#define SQLITE_SHM_NLOCK        8158115821583/*1584** CAPI3REF: Initialize The SQLite Library1585**1586** ^The sqlite3_initialize() routine initializes the1587** SQLite library.  ^The sqlite3_shutdown() routine1588** deallocates any resources that were allocated by sqlite3_initialize().1589** These routines are designed to aid in process initialization and1590** shutdown on embedded systems.  Workstation applications using1591** SQLite normally do not need to invoke either of these routines.1592**1593** A call to sqlite3_initialize() is an "effective" call if it is1594** the first time sqlite3_initialize() is invoked during the lifetime of1595** the process, or if it is the first time sqlite3_initialize() is invoked1596** following a call to sqlite3_shutdown().  ^(Only an effective call1597** of sqlite3_initialize() does any initialization.  All other calls1598** are harmless no-ops.)^1599**1600** A call to sqlite3_shutdown() is an "effective" call if it is the first1601** call to sqlite3_shutdown() since the last sqlite3_initialize().  ^(Only1602** an effective call to sqlite3_shutdown() does any deinitialization.1603** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^1604**1605** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()1606** is not.  The sqlite3_shutdown() interface must only be called from a1607** single thread.  All open [database connections] must be closed and all1608** other SQLite resources must be deallocated prior to invoking1609** sqlite3_shutdown().1610**1611** Among other things, ^sqlite3_initialize() will invoke1612** sqlite3_os_init().  Similarly, ^sqlite3_shutdown()1613** will invoke sqlite3_os_end().1614**1615** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.1616** ^If for some reason, sqlite3_initialize() is unable to initialize1617** the library (perhaps it is unable to allocate a needed resource such1618** as a mutex) it returns an [error code] other than [SQLITE_OK].1619**1620** ^The sqlite3_initialize() routine is called internally by many other1621** SQLite interfaces so that an application usually does not need to1622** invoke sqlite3_initialize() directly.  For example, [sqlite3_open()]1623** calls sqlite3_initialize() so the SQLite library will be automatically1624** initialized when [sqlite3_open()] is called if it has not be initialized1625** already.  ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]1626** compile-time option, then the automatic calls to sqlite3_initialize()1627** are omitted and the application must call sqlite3_initialize() directly1628** prior to using any other SQLite interface.  For maximum portability,1629** it is recommended that applications always invoke sqlite3_initialize()1630** directly prior to using any other SQLite interface.  Future releases1631** of SQLite may require this.  In other words, the behavior exhibited1632** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the1633** default behavior in some future release of SQLite.1634**1635** The sqlite3_os_init() routine does operating-system specific1636** initialization of the SQLite library.  The sqlite3_os_end()1637** routine undoes the effect of sqlite3_os_init().  Typical tasks1638** performed by these routines include allocation or deallocation1639** of static resources, initialization of global variables,1640** setting up a default [sqlite3_vfs] module, or setting up1641** a default configuration using [sqlite3_config()].1642**1643** The application should never invoke either sqlite3_os_init()1644** or sqlite3_os_end() directly.  The application should only invoke1645** sqlite3_initialize() and sqlite3_shutdown().  The sqlite3_os_init()1646** interface is called automatically by sqlite3_initialize() and1647** sqlite3_os_end() is called by sqlite3_shutdown().  Appropriate1648** implementations for sqlite3_os_init() and sqlite3_os_end()1649** are built into SQLite when it is compiled for Unix, Windows, or OS/2.1650** When [custom builds | built for other platforms]1651** (using the [SQLITE_OS_OTHER=1] compile-time1652** option) the application must supply a suitable implementation for1653** sqlite3_os_init() and sqlite3_os_end().  An application-supplied1654** implementation of sqlite3_os_init() or sqlite3_os_end()1655** must return [SQLITE_OK] on success and some other [error code] upon1656** failure.1657*/1658SQLITE_API int sqlite3_initialize(void);1659SQLITE_API int sqlite3_shutdown(void);1660SQLITE_API int sqlite3_os_init(void);1661SQLITE_API int sqlite3_os_end(void);16621663/*1664** CAPI3REF: Configuring The SQLite Library1665**1666** The sqlite3_config() interface is used to make global configuration1667** changes to SQLite in order to tune SQLite to the specific needs of1668** the application.  The default configuration is recommended for most1669** applications and so this routine is usually not necessary.  It is1670** provided to support rare applications with unusual needs.1671**1672** <b>The sqlite3_config() interface is not threadsafe. The application1673** must ensure that no other SQLite interfaces are invoked by other1674** threads while sqlite3_config() is running.</b>1675**1676** The first argument to sqlite3_config() is an integer1677** [configuration option] that determines1678** what property of SQLite is to be configured.  Subsequent arguments1679** vary depending on the [configuration option]1680** in the first argument.1681**1682** For most configuration options, the sqlite3_config() interface1683** may only be invoked prior to library initialization using1684** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].1685** The exceptional configuration options that may be invoked at any time1686** are called "anytime configuration options".1687** ^If sqlite3_config() is called after [sqlite3_initialize()] and before1688** [sqlite3_shutdown()] with a first argument that is not an anytime1689** configuration option, then the sqlite3_config() call will return SQLITE_MISUSE.1690** Note, however, that ^sqlite3_config() can be called as part of the1691** implementation of an application-defined [sqlite3_os_init()].1692**1693** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].1694** ^If the option is unknown or SQLite is unable to set the option1695** then this routine returns a non-zero [error code].1696*/1697SQLITE_API int sqlite3_config(int, ...);16981699/*1700** CAPI3REF: Configure database connections1701** METHOD: sqlite31702**1703** The sqlite3_db_config() interface is used to make configuration1704** changes to a [database connection].  The interface is similar to1705** [sqlite3_config()] except that the changes apply to a single1706** [database connection] (specified in the first argument).1707**1708** The second argument to sqlite3_db_config(D,V,...)  is the1709** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code1710** that indicates what aspect of the [database connection] is being configured.1711** Subsequent arguments vary depending on the configuration verb.1712**1713** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if1714** the call is considered successful.1715*/1716SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);17171718/*1719** CAPI3REF: Memory Allocation Routines1720**1721** An instance of this object defines the interface between SQLite1722** and low-level memory allocation routines.1723**1724** This object is used in only one place in the SQLite interface.1725** A pointer to an instance of this object is the argument to1726** [sqlite3_config()] when the configuration option is1727** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].1728** By creating an instance of this object1729** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])1730** during configuration, an application can specify an alternative1731** memory allocation subsystem for SQLite to use for all of its1732** dynamic memory needs.1733**1734** Note that SQLite comes with several [built-in memory allocators]1735** that are perfectly adequate for the overwhelming majority of applications1736** and that this object is only useful to a tiny minority of applications1737** with specialized memory allocation requirements.  This object is1738** also used during testing of SQLite in order to specify an alternative1739** memory allocator that simulates memory out-of-memory conditions in1740** order to verify that SQLite recovers gracefully from such1741** conditions.1742**1743** The xMalloc, xRealloc, and xFree methods must work like the1744** malloc(), realloc() and free() functions from the standard C library.1745** ^SQLite guarantees that the second argument to1746** xRealloc is always a value returned by a prior call to xRoundup.1747**1748** xSize should return the allocated size of a memory allocation1749** previously obtained from xMalloc or xRealloc.  The allocated size1750** is always at least as big as the requested size but may be larger.1751**1752** The xRoundup method returns what would be the allocated size of1753** a memory allocation given a particular requested size.  Most memory1754** allocators round up memory allocations at least to the next multiple1755** of 8.  Some allocators round up to a larger multiple or to a power of 2.1756** Every memory allocation request coming in through [sqlite3_malloc()]1757** or [sqlite3_realloc()] first calls xRoundup.  If xRoundup returns 0,1758** that causes the corresponding memory allocation to fail.1759**1760** The xInit method initializes the memory allocator.  For example,1761** it might allocate any required mutexes or initialize internal data1762** structures.  The xShutdown method is invoked (indirectly) by1763** [sqlite3_shutdown()] and should deallocate any resources acquired1764** by xInit.  The pAppData pointer is used as the only parameter to1765** xInit and xShutdown.1766**1767** SQLite holds the [SQLITE_MUTEX_STATIC_MAIN] mutex when it invokes1768** the xInit method, so the xInit method need not be threadsafe.  The1769** xShutdown method is only called from [sqlite3_shutdown()] so it does1770** not need to be threadsafe either.  For all other methods, SQLite1771** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the1772** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which1773** it is by default) and so the methods are automatically serialized.1774** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other1775** methods must be threadsafe or else make their own arrangements for1776** serialization.1777**1778** SQLite will never invoke xInit() more than once without an intervening1779** call to xShutdown().1780*/1781typedef struct sqlite3_mem_methods sqlite3_mem_methods;1782struct sqlite3_mem_methods {1783  void *(*xMalloc)(int);         /* Memory allocation function */1784  void (*xFree)(void*);          /* Free a prior allocation */1785  void *(*xRealloc)(void*,int);  /* Resize an allocation */1786  int (*xSize)(void*);           /* Return the size of an allocation */1787  int (*xRoundup)(int);          /* Round up request size to allocation size */1788  int (*xInit)(void*);           /* Initialize the memory allocator */1789  void (*xShutdown)(void*);      /* Deinitialize the memory allocator */1790  void *pAppData;                /* Argument to xInit() and xShutdown() */1791};17921793/*1794** CAPI3REF: Configuration Options1795** KEYWORDS: {configuration option}1796**1797** These constants are the available integer configuration options that1798** can be passed as the first argument to the [sqlite3_config()] interface.1799**1800** Most of the configuration options for sqlite3_config()1801** will only work if invoked prior to [sqlite3_initialize()] or after1802** [sqlite3_shutdown()].  The few exceptions to this rule are called1803** "anytime configuration options".1804** ^Calling [sqlite3_config()] with a first argument that is not an1805** anytime configuration option in between calls to [sqlite3_initialize()] and1806** [sqlite3_shutdown()] is a no-op that returns SQLITE_MISUSE.1807**1808** The set of anytime configuration options can change (by insertions1809** and/or deletions) from one release of SQLite to the next.1810** As of SQLite version 3.42.0, the complete set of anytime configuration1811** options is:1812** <ul>1813** <li> SQLITE_CONFIG_LOG1814** <li> SQLITE_CONFIG_PCACHE_HDRSZ1815** </ul>1816**1817** New configuration options may be added in future releases of SQLite.1818** Existing configuration options might be discontinued.  Applications1819** should check the return code from [sqlite3_config()] to make sure that1820** the call worked.  The [sqlite3_config()] interface will return a1821** non-zero [error code] if a discontinued or unsupported configuration option1822** is invoked.1823**1824** <dl>1825** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt>1826** <dd>There are no arguments to this option.  ^This option sets the1827** [threading mode] to Single-thread.  In other words, it disables1828** all mutexing and puts SQLite into a mode where it can only be used1829** by a single thread.   ^If SQLite is compiled with1830** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then1831** it is not possible to change the [threading mode] from its default1832** value of Single-thread and so [sqlite3_config()] will return1833** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD1834** configuration option.</dd>1835**1836** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt>1837** <dd>There are no arguments to this option.  ^This option sets the1838** [threading mode] to Multi-thread.  In other words, it disables1839** mutexing on [database connection] and [prepared statement] objects.1840** The application is responsible for serializing access to1841** [database connections] and [prepared statements].  But other mutexes1842** are enabled so that SQLite will be safe to use in a multi-threaded1843** environment as long as no two threads attempt to use the same1844** [database connection] at the same time.  ^If SQLite is compiled with1845** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then1846** it is not possible to set the Multi-thread [threading mode] and1847** [sqlite3_config()] will return [SQLITE_ERROR] if called with the1848** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>1849**1850** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt>1851** <dd>There are no arguments to this option.  ^This option sets the1852** [threading mode] to Serialized. In other words, this option enables1853** all mutexes including the recursive1854** mutexes on [database connection] and [prepared statement] objects.1855** In this mode (which is the default when SQLite is compiled with1856** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access1857** to [database connections] and [prepared statements] so that the1858** application is free to use the same [database connection] or the1859** same [prepared statement] in different threads at the same time.1860** ^If SQLite is compiled with1861** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then1862** it is not possible to set the Serialized [threading mode] and1863** [sqlite3_config()] will return [SQLITE_ERROR] if called with the1864** SQLITE_CONFIG_SERIALIZED configuration option.</dd>1865**1866** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>1867** <dd> ^(The SQLITE_CONFIG_MALLOC option takes a single argument which is1868** a pointer to an instance of the [sqlite3_mem_methods] structure.1869** The argument specifies1870** alternative low-level memory allocation routines to be used in place of1871** the memory allocation routines built into SQLite.)^ ^SQLite makes1872** its own private copy of the content of the [sqlite3_mem_methods] structure1873** before the [sqlite3_config()] call returns.</dd>1874**1875** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>1876** <dd> ^(The SQLITE_CONFIG_GETMALLOC option takes a single argument which1877** is a pointer to an instance of the [sqlite3_mem_methods] structure.1878** The [sqlite3_mem_methods]1879** structure is filled with the currently defined memory allocation routines.)^1880** This option can be used to overload the default memory allocation1881** routines with a wrapper that simulations memory allocation failure or1882** tracks memory usage, for example. </dd>1883**1884** [[SQLITE_CONFIG_SMALL_MALLOC]] <dt>SQLITE_CONFIG_SMALL_MALLOC</dt>1885** <dd> ^The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of1886** type int, interpreted as a boolean, which if true provides a hint to1887** SQLite that it should avoid large memory allocations if possible.1888** SQLite will run faster if it is free to make large memory allocations,1889** but some application might prefer to run slower in exchange for1890** guarantees about memory fragmentation that are possible if large1891** allocations are avoided.  This hint is normally off.1892** </dd>1893**1894** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>1895** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,1896** interpreted as a boolean, which enables or disables the collection of1897** memory allocation statistics. ^(When memory allocation statistics are1898** disabled, the following SQLite interfaces become non-operational:1899**   <ul>1900**   <li> [sqlite3_hard_heap_limit64()]1901**   <li> [sqlite3_memory_used()]1902**   <li> [sqlite3_memory_highwater()]1903**   <li> [sqlite3_soft_heap_limit64()]1904**   <li> [sqlite3_status64()]1905**   </ul>)^1906** ^Memory allocation statistics are enabled by default unless SQLite is1907** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory1908** allocation statistics are disabled by default.1909** </dd>1910**1911** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>1912** <dd> The SQLITE_CONFIG_SCRATCH option is no longer used.1913** </dd>1914**1915** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>1916** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool1917** that SQLite can use for the database page cache with the default page1918** cache implementation.1919** This configuration option is a no-op if an application-defined page1920** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].1921** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to1922** 8-byte aligned memory (pMem), the size of each page cache line (sz),1923** and the number of cache lines (N).1924** The sz argument should be the size of the largest database page1925** (a power of two between 512 and 65536) plus some extra bytes for each1926** page header.  ^The number of extra bytes needed by the page header1927** can be determined using [SQLITE_CONFIG_PCACHE_HDRSZ].1928** ^It is harmless, apart from the wasted memory,1929** for the sz parameter to be larger than necessary.  The pMem1930** argument must be either a NULL pointer or a pointer to an 8-byte1931** aligned block of memory of at least sz*N bytes, otherwise1932** subsequent behavior is undefined.1933** ^When pMem is not NULL, SQLite will strive to use the memory provided1934** to satisfy page cache needs, falling back to [sqlite3_malloc()] if1935** a page cache line is larger than sz bytes or if all of the pMem buffer1936** is exhausted.1937** ^If pMem is NULL and N is non-zero, then each database connection1938** does an initial bulk allocation for page cache memory1939** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or1940** of -1024*N bytes if N is negative, . ^If additional1941** page cache memory is needed beyond what is provided by the initial1942** allocation, then SQLite goes to [sqlite3_malloc()] separately for each1943** additional cache line. </dd>1944**1945** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>1946** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer1947** that SQLite will use for all of its dynamic memory allocation needs1948** beyond those provided for by [SQLITE_CONFIG_PAGECACHE].1949** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled1950** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns1951** [SQLITE_ERROR] if invoked otherwise.1952** ^There are three arguments to SQLITE_CONFIG_HEAP:1953** An 8-byte aligned pointer to the memory,1954** the number of bytes in the memory buffer, and the minimum allocation size.1955** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts1956** to using its default memory allocator (the system malloc() implementation),1957** undoing any prior invocation of [SQLITE_CONFIG_MALLOC].  ^If the1958** memory pointer is not NULL then the alternative memory1959** allocator is engaged to handle all of SQLites memory allocation needs.1960** The first pointer (the memory pointer) must be aligned to an 8-byte1961** boundary or subsequent behavior of SQLite will be undefined.1962** The minimum allocation size is capped at 2**12. Reasonable values1963** for the minimum allocation size are 2**5 through 2**8.</dd>1964**1965** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>1966** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a1967** pointer to an instance of the [sqlite3_mutex_methods] structure.1968** The argument specifies alternative low-level mutex routines to be used1969** in place the mutex routines built into SQLite.)^  ^SQLite makes a copy of1970** the content of the [sqlite3_mutex_methods] structure before the call to1971** [sqlite3_config()] returns. ^If SQLite is compiled with1972** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then1973** the entire mutexing subsystem is omitted from the build and hence calls to1974** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will1975** return [SQLITE_ERROR].</dd>1976**1977** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>1978** <dd> ^(The SQLITE_CONFIG_GETMUTEX option takes a single argument which1979** is a pointer to an instance of the [sqlite3_mutex_methods] structure.  The1980** [sqlite3_mutex_methods]1981** structure is filled with the currently defined mutex routines.)^1982** This option can be used to overload the default mutex allocation1983** routines with a wrapper used to track mutex usage for performance1984** profiling or testing, for example.   ^If SQLite is compiled with1985** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then1986** the entire mutexing subsystem is omitted from the build and hence calls to1987** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will1988** return [SQLITE_ERROR].</dd>1989**1990** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>1991** <dd> ^(The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine1992** the default size of lookaside memory on each [database connection].1993** The first argument is the1994** size of each lookaside buffer slot and the second is the number of1995** slots allocated to each database connection.)^  ^(SQLITE_CONFIG_LOOKASIDE1996** sets the <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]1997** option to [sqlite3_db_config()] can be used to change the lookaside1998** configuration on individual connections.)^ </dd>1999**2000** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>2001** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is2002** a pointer to an [sqlite3_pcache_methods2] object.  This object specifies2003** the interface to a custom page cache implementation.)^2004** ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.</dd>2005**2006** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>2007** <dd> ^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which2008** is a pointer to an [sqlite3_pcache_methods2] object.  SQLite copies of2009** the current page cache implementation into that object.)^ </dd>2010**2011** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>2012** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite2013** global [error log].2014** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a2015** function with a call signature of void(*)(void*,int,const char*),2016** and a pointer to void. ^If the function pointer is not NULL, it is2017** invoked by [sqlite3_log()] to process each logging event.  ^If the2018** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.2019** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is2020** passed through as the first parameter to the application-defined logger2021** function whenever that function is invoked.  ^The second parameter to2022** the logger function is a copy of the first parameter to the corresponding2023** [sqlite3_log()] call and is intended to be a [result code] or an2024** [extended result code].  ^The third parameter passed to the logger is2025** log message after formatting via [sqlite3_snprintf()].2026** The SQLite logging interface is not reentrant; the logger function2027** supplied by the application must not invoke any SQLite interface.2028** In a multi-threaded application, the application-defined logger2029** function must be threadsafe. </dd>2030**2031** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI2032** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.2033** If non-zero, then URI handling is globally enabled. If the parameter is zero,2034** then URI handling is globally disabled.)^ ^If URI handling is globally2035** enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()],2036** [sqlite3_open16()] or2037** specified as part of [ATTACH] commands are interpreted as URIs, regardless2038** of whether or not the [SQLITE_OPEN_URI] flag is set when the database2039** connection is opened. ^If it is globally disabled, filenames are2040** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the2041** database connection is opened. ^(By default, URI handling is globally2042** disabled. The default value may be changed by compiling with the2043** [SQLITE_USE_URI] symbol defined.)^2044**2045** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN2046** <dd>^The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer2047** argument which is interpreted as a boolean in order to enable or disable2048** the use of covering indices for full table scans in the query optimizer.2049** ^The default setting is determined2050** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"2051** if that compile-time option is omitted.2052** The ability to disable the use of covering indices for full table scans2053** is because some incorrectly coded legacy applications might malfunction2054** when the optimization is enabled.  Providing the ability to2055** disable the optimization allows the older, buggy application code to work2056** without change even with newer versions of SQLite.2057**2058** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]]2059** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE2060** <dd> These options are obsolete and should not be used by new code.2061** They are retained for backwards compatibility but are now no-ops.2062** </dd>2063**2064** [[SQLITE_CONFIG_SQLLOG]]2065** <dt>SQLITE_CONFIG_SQLLOG2066** <dd>This option is only available if sqlite is compiled with the2067** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should2068** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).2069** The second should be of type (void*). The callback is invoked by the library2070** in three separate circumstances, identified by the value passed as the2071** fourth parameter. If the fourth parameter is 0, then the database connection2072** passed as the second argument has just been opened. The third argument2073** points to a buffer containing the name of the main database file. If the2074** fourth parameter is 1, then the SQL statement that the third parameter2075** points to has just been executed. Or, if the fourth parameter is 2, then2076** the connection being passed as the second parameter is being closed. The2077** third parameter is passed NULL In this case.  An example of using this2078** configuration option can be seen in the "test_sqllog.c" source file in2079** the canonical SQLite source tree.</dd>2080**2081** [[SQLITE_CONFIG_MMAP_SIZE]]2082** <dt>SQLITE_CONFIG_MMAP_SIZE2083** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values2084** that are the default mmap size limit (the default setting for2085** [PRAGMA mmap_size]) and the maximum allowed mmap size limit.2086** ^The default setting can be overridden by each database connection using2087** either the [PRAGMA mmap_size] command, or by using the2088** [SQLITE_FCNTL_MMAP_SIZE] file control.  ^(The maximum allowed mmap size2089** will be silently truncated if necessary so that it does not exceed the2090** compile-time maximum mmap size set by the2091** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^2092** ^If either argument to this option is negative, then that argument is2093** changed to its compile-time default.2094**2095** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]2096** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE2097** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is2098** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro2099** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value2100** that specifies the maximum size of the created heap.2101**2102** [[SQLITE_CONFIG_PCACHE_HDRSZ]]2103** <dt>SQLITE_CONFIG_PCACHE_HDRSZ2104** <dd>^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which2105** is a pointer to an integer and writes into that integer the number of extra2106** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE].2107** The amount of extra space required can change depending on the compiler,2108** target platform, and SQLite version.2109**2110** [[SQLITE_CONFIG_PMASZ]]2111** <dt>SQLITE_CONFIG_PMASZ2112** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which2113** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded2114** sorter to that integer.  The default minimum PMA Size is set by the2115** [SQLITE_SORTER_PMASZ] compile-time option.  New threads are launched2116** to help with sort operations when multithreaded sorting2117** is enabled (using the [PRAGMA threads] command) and the amount of content2118** to be sorted exceeds the page size times the minimum of the2119** [PRAGMA cache_size] setting and this value.2120**2121** [[SQLITE_CONFIG_STMTJRNL_SPILL]]2122** <dt>SQLITE_CONFIG_STMTJRNL_SPILL2123** <dd>^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which2124** becomes the [statement journal] spill-to-disk threshold.2125** [Statement journals] are held in memory until their size (in bytes)2126** exceeds this threshold, at which point they are written to disk.2127** Or if the threshold is -1, statement journals are always held2128** exclusively in memory.2129** Since many statement journals never become large, setting the spill2130** threshold to a value such as 64KiB can greatly reduce the amount of2131** I/O required to support statement rollback.2132** The default value for this setting is controlled by the2133** [SQLITE_STMTJRNL_SPILL] compile-time option.2134**2135** [[SQLITE_CONFIG_SORTERREF_SIZE]]2136** <dt>SQLITE_CONFIG_SORTERREF_SIZE2137** <dd>The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter2138** of type (int) - the new value of the sorter-reference size threshold.2139** Usually, when SQLite uses an external sort to order records according2140** to an ORDER BY clause, all fields required by the caller are present in the2141** sorted records. However, if SQLite determines based on the declared type2142** of a table column that its values are likely to be very large - larger2143** than the configured sorter-reference size threshold - then a reference2144** is stored in each sorted record and the required column values loaded2145** from the database as records are returned in sorted order. The default2146** value for this option is to never use this optimization. Specifying a2147** negative value for this option restores the default behavior.2148** This option is only available if SQLite is compiled with the2149** [SQLITE_ENABLE_SORTER_REFERENCES] compile-time option.2150**2151** [[SQLITE_CONFIG_MEMDB_MAXSIZE]]2152** <dt>SQLITE_CONFIG_MEMDB_MAXSIZE2153** <dd>The SQLITE_CONFIG_MEMDB_MAXSIZE option accepts a single parameter2154** [sqlite3_int64] parameter which is the default maximum size for an in-memory2155** database created using [sqlite3_deserialize()].  This default maximum2156** size can be adjusted up or down for individual databases using the2157** [SQLITE_FCNTL_SIZE_LIMIT] [sqlite3_file_control|file-control].  If this2158** configuration setting is never used, then the default maximum is determined2159** by the [SQLITE_MEMDB_DEFAULT_MAXSIZE] compile-time option.  If that2160** compile-time option is not set, then the default maximum is 1073741824.2161**2162** [[SQLITE_CONFIG_ROWID_IN_VIEW]]2163** <dt>SQLITE_CONFIG_ROWID_IN_VIEW2164** <dd>The SQLITE_CONFIG_ROWID_IN_VIEW option enables or disables the ability2165** for VIEWs to have a ROWID.  The capability can only be enabled if SQLite is2166** compiled with -DSQLITE_ALLOW_ROWID_IN_VIEW, in which case the capability2167** defaults to on.  This configuration option queries the current setting or2168** changes the setting to off or on.  The argument is a pointer to an integer.2169** If that integer initially holds a value of 1, then the ability for VIEWs to2170** have ROWIDs is activated.  If the integer initially holds zero, then the2171** ability is deactivated.  Any other initial value for the integer leaves the2172** setting unchanged.  After changes, if any, the integer is written with2173** a 1 or 0, if the ability for VIEWs to have ROWIDs is on or off.  If SQLite2174** is compiled without -DSQLITE_ALLOW_ROWID_IN_VIEW (which is the usual and2175** recommended case) then the integer is always filled with zero, regardless2176** if its initial value.2177** </dl>2178*/2179#define SQLITE_CONFIG_SINGLETHREAD         1  /* nil */2180#define SQLITE_CONFIG_MULTITHREAD          2  /* nil */2181#define SQLITE_CONFIG_SERIALIZED           3  /* nil */2182#define SQLITE_CONFIG_MALLOC               4  /* sqlite3_mem_methods* */2183#define SQLITE_CONFIG_GETMALLOC            5  /* sqlite3_mem_methods* */2184#define SQLITE_CONFIG_SCRATCH              6  /* No longer used */2185#define SQLITE_CONFIG_PAGECACHE            7  /* void*, int sz, int N */2186#define SQLITE_CONFIG_HEAP                 8  /* void*, int nByte, int min */2187#define SQLITE_CONFIG_MEMSTATUS            9  /* boolean */2188#define SQLITE_CONFIG_MUTEX               10  /* sqlite3_mutex_methods* */2189#define SQLITE_CONFIG_GETMUTEX            11  /* sqlite3_mutex_methods* */2190/* previously SQLITE_CONFIG_CHUNKALLOC    12 which is now unused. */2191#define SQLITE_CONFIG_LOOKASIDE           13  /* int int */2192#define SQLITE_CONFIG_PCACHE              14  /* no-op */2193#define SQLITE_CONFIG_GETPCACHE           15  /* no-op */2194#define SQLITE_CONFIG_LOG                 16  /* xFunc, void* */2195#define SQLITE_CONFIG_URI                 17  /* int */2196#define SQLITE_CONFIG_PCACHE2             18  /* sqlite3_pcache_methods2* */2197#define SQLITE_CONFIG_GETPCACHE2          19  /* sqlite3_pcache_methods2* */2198#define SQLITE_CONFIG_COVERING_INDEX_SCAN 20  /* int */2199#define SQLITE_CONFIG_SQLLOG              21  /* xSqllog, void* */2200#define SQLITE_CONFIG_MMAP_SIZE           22  /* sqlite3_int64, sqlite3_int64 */2201#define SQLITE_CONFIG_WIN32_HEAPSIZE      23  /* int nByte */2202#define SQLITE_CONFIG_PCACHE_HDRSZ        24  /* int *psz */2203#define SQLITE_CONFIG_PMASZ               25  /* unsigned int szPma */2204#define SQLITE_CONFIG_STMTJRNL_SPILL      26  /* int nByte */2205#define SQLITE_CONFIG_SMALL_MALLOC        27  /* boolean */2206#define SQLITE_CONFIG_SORTERREF_SIZE      28  /* int nByte */2207#define SQLITE_CONFIG_MEMDB_MAXSIZE       29  /* sqlite3_int64 */2208#define SQLITE_CONFIG_ROWID_IN_VIEW       30  /* int* */22092210/*2211** CAPI3REF: Database Connection Configuration Options2212**2213** These constants are the available integer configuration options that2214** can be passed as the second parameter to the [sqlite3_db_config()] interface.2215**2216** The [sqlite3_db_config()] interface is a var-args functions.  It takes a2217** variable number of parameters, though always at least two.  The number of2218** parameters passed into sqlite3_db_config() depends on which of these2219** constants is given as the second parameter.  This documentation page2220** refers to parameters beyond the second as "arguments".  Thus, when this2221** page says "the N-th argument" it means "the N-th parameter past the2222** configuration option" or "the (N+2)-th parameter to sqlite3_db_config()".2223**2224** New configuration options may be added in future releases of SQLite.2225** Existing configuration options might be discontinued.  Applications2226** should check the return code from [sqlite3_db_config()] to make sure that2227** the call worked.  ^The [sqlite3_db_config()] interface will return a2228** non-zero [error code] if a discontinued or unsupported configuration option2229** is invoked.2230**2231** <dl>2232** [[SQLITE_DBCONFIG_LOOKASIDE]]2233** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>2234** <dd> The SQLITE_DBCONFIG_LOOKASIDE option is used to adjust the2235** configuration of the lookaside memory allocator within a database2236** connection.2237** The arguments to the SQLITE_DBCONFIG_LOOKASIDE option are <i>not</i>2238** in the [DBCONFIG arguments|usual format].2239** The SQLITE_DBCONFIG_LOOKASIDE option takes three arguments, not two,2240** so that a call to [sqlite3_db_config()] that uses SQLITE_DBCONFIG_LOOKASIDE2241** should have a total of five parameters.2242** ^The first argument (the third parameter to [sqlite3_db_config()] is a2243** pointer to a memory buffer to use for lookaside memory.2244** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb2245** may be NULL in which case SQLite will allocate the2246** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the2247** size of each lookaside buffer slot.  ^The third argument is the number of2248** slots.  The size of the buffer in the first argument must be greater than2249** or equal to the product of the second and third arguments.  The buffer2250** must be aligned to an 8-byte boundary.  ^If the second argument to2251** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally2252** rounded down to the next smaller multiple of 8.  ^(The lookaside memory2253** configuration for a database connection can only be changed when that2254** connection is not currently using lookaside memory, or in other words2255** when the "current value" returned by2256** [sqlite3_db_status](D,[SQLITE_DBSTATUS_LOOKASIDE_USED],...) is zero.2257** Any attempt to change the lookaside memory configuration when lookaside2258** memory is in use leaves the configuration unchanged and returns2259** [SQLITE_BUSY].)^</dd>2260**2261** [[SQLITE_DBCONFIG_ENABLE_FKEY]]2262** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>2263** <dd> ^This option is used to enable or disable the enforcement of2264** [foreign key constraints].  This is the same setting that is2265** enabled or disabled by the [PRAGMA foreign_keys] statement.2266** The first argument is an integer which is 0 to disable FK enforcement,2267** positive to enable FK enforcement or negative to leave FK enforcement2268** unchanged.  The second parameter is a pointer to an integer into which2269** is written 0 or 1 to indicate whether FK enforcement is off or on2270** following this call.  The second parameter may be a NULL pointer, in2271** which case the FK enforcement setting is not reported back. </dd>2272**2273** [[SQLITE_DBCONFIG_ENABLE_TRIGGER]]2274** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>2275** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].2276** There should be two additional arguments.2277** The first argument is an integer which is 0 to disable triggers,2278** positive to enable triggers or negative to leave the setting unchanged.2279** The second parameter is a pointer to an integer into which2280** is written 0 or 1 to indicate whether triggers are disabled or enabled2281** following this call.  The second parameter may be a NULL pointer, in2282** which case the trigger setting is not reported back.2283**2284** <p>Originally this option disabled all triggers.  ^(However, since2285** SQLite version 3.35.0, TEMP triggers are still allowed even if2286** this option is off.  So, in other words, this option now only disables2287** triggers in the main database schema or in the schemas of [ATTACH]-ed2288** databases.)^ </dd>2289**2290** [[SQLITE_DBCONFIG_ENABLE_VIEW]]2291** <dt>SQLITE_DBCONFIG_ENABLE_VIEW</dt>2292** <dd> ^This option is used to enable or disable [CREATE VIEW | views].2293** There must be two additional arguments.2294** The first argument is an integer which is 0 to disable views,2295** positive to enable views or negative to leave the setting unchanged.2296** The second parameter is a pointer to an integer into which2297** is written 0 or 1 to indicate whether views are disabled or enabled2298** following this call.  The second parameter may be a NULL pointer, in2299** which case the view setting is not reported back.2300**2301** <p>Originally this option disabled all views.  ^(However, since2302** SQLite version 3.35.0, TEMP views are still allowed even if2303** this option is off.  So, in other words, this option now only disables2304** views in the main database schema or in the schemas of ATTACH-ed2305** databases.)^ </dd>2306**2307** [[SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER]]2308** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt>2309** <dd> ^This option is used to enable or disable the2310** [fts3_tokenizer()] function which is part of the2311** [FTS3] full-text search engine extension.2312** There must be two additional arguments.2313** The first argument is an integer which is 0 to disable fts3_tokenizer() or2314** positive to enable fts3_tokenizer() or negative to leave the setting2315** unchanged.2316** The second parameter is a pointer to an integer into which2317** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled2318** following this call.  The second parameter may be a NULL pointer, in2319** which case the new setting is not reported back. </dd>2320**2321** [[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION]]2322** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt>2323** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()]2324** interface independently of the [load_extension()] SQL function.2325** The [sqlite3_enable_load_extension()] API enables or disables both the2326** C-API [sqlite3_load_extension()] and the SQL function [load_extension()].2327** There must be two additional arguments.2328** When the first argument to this interface is 1, then only the C-API is2329** enabled and the SQL function remains disabled.  If the first argument to2330** this interface is 0, then both the C-API and the SQL function are disabled.2331** If the first argument is -1, then no changes are made to state of either the2332** C-API or the SQL function.2333** The second parameter is a pointer to an integer into which2334** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface2335** is disabled or enabled following this call.  The second parameter may2336** be a NULL pointer, in which case the new setting is not reported back.2337** </dd>2338**2339** [[SQLITE_DBCONFIG_MAINDBNAME]] <dt>SQLITE_DBCONFIG_MAINDBNAME</dt>2340** <dd> ^This option is used to change the name of the "main" database2341** schema.  This option does not follow the2342** [DBCONFIG arguments|usual SQLITE_DBCONFIG argument format].2343** This option takes exactly one additional argument so that the2344** [sqlite3_db_config()] call has a total of three parameters.  The2345** extra argument must be a pointer to a constant UTF8 string which2346** will become the new schema name in place of "main".  ^SQLite does2347** not make a copy of the new main schema name string, so the application2348** must ensure that the argument passed into SQLITE_DBCONFIG MAINDBNAME2349** is unchanged until after the database connection closes.2350** </dd>2351**2352** [[SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE]]2353** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt>2354** <dd> Usually, when a database in [WAL mode] is closed or detached from a2355** database handle, SQLite checks if if there are other connections to the2356** same database, and if there are no other database connection (if the2357** connection being closed is the last open connection to the database),2358** then SQLite performs a [checkpoint] before closing the connection and2359** deletes the WAL file.  The SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE option can2360** be used to override that behavior. The first argument passed to this2361** operation (the third parameter to [sqlite3_db_config()]) is an integer2362** which is positive to disable checkpoints-on-close, or zero (the default)2363** to enable them, and negative to leave the setting unchanged.2364** The second argument (the fourth parameter) is a pointer to an integer2365** into which is written 0 or 1 to indicate whether checkpoints-on-close2366** have been disabled - 0 if they are not disabled, 1 if they are.2367** </dd>2368**2369** [[SQLITE_DBCONFIG_ENABLE_QPSG]] <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt>2370** <dd>^(The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates2371** the [query planner stability guarantee] (QPSG).  When the QPSG is active,2372** a single SQL query statement will always use the same algorithm regardless2373** of values of [bound parameters].)^ The QPSG disables some query optimizations2374** that look at the values of bound parameters, which can make some queries2375** slower.  But the QPSG has the advantage of more predictable behavior.  With2376** the QPSG active, SQLite will always use the same query plan in the field as2377** was used during testing in the lab.2378** The first argument to this setting is an integer which is 0 to disable2379** the QPSG, positive to enable QPSG, or negative to leave the setting2380** unchanged. The second parameter is a pointer to an integer into which2381** is written 0 or 1 to indicate whether the QPSG is disabled or enabled2382** following this call.2383** </dd>2384**2385** [[SQLITE_DBCONFIG_TRIGGER_EQP]] <dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt>2386** <dd> By default, the output of EXPLAIN QUERY PLAN commands does not2387** include output for any operations performed by trigger programs. This2388** option is used to set or clear (the default) a flag that governs this2389** behavior. The first parameter passed to this operation is an integer -2390** positive to enable output for trigger programs, or zero to disable it,2391** or negative to leave the setting unchanged.2392** The second parameter is a pointer to an integer into which is written2393** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if2394** it is not disabled, 1 if it is.2395** </dd>2396**2397** [[SQLITE_DBCONFIG_RESET_DATABASE]] <dt>SQLITE_DBCONFIG_RESET_DATABASE</dt>2398** <dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run2399** [VACUUM] in order to reset a database back to an empty database2400** with no schema and no content. The following process works even for2401** a badly corrupted database file:2402** <ol>2403** <li> If the database connection is newly opened, make sure it has read the2404**      database schema by preparing then discarding some query against the2405**      database, or calling sqlite3_table_column_metadata(), ignoring any2406**      errors.  This step is only necessary if the application desires to keep2407**      the database in WAL mode after the reset if it was in WAL mode before2408**      the reset.2409** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0);2410** <li> [sqlite3_exec](db, "[VACUUM]", 0, 0, 0);2411** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0);2412** </ol>2413** Because resetting a database is destructive and irreversible, the2414** process requires the use of this obscure API and multiple steps to2415** help ensure that it does not happen by accident. Because this2416** feature must be capable of resetting corrupt databases, and2417** shutting down virtual tables may require access to that corrupt2418** storage, the library must abandon any installed virtual tables2419** without calling their xDestroy() methods.2420**2421** [[SQLITE_DBCONFIG_DEFENSIVE]] <dt>SQLITE_DBCONFIG_DEFENSIVE</dt>2422** <dd>The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the2423** "defensive" flag for a database connection.  When the defensive2424** flag is enabled, language features that allow ordinary SQL to2425** deliberately corrupt the database file are disabled.  The disabled2426** features include but are not limited to the following:2427** <ul>2428** <li> The [PRAGMA writable_schema=ON] statement.2429** <li> The [PRAGMA journal_mode=OFF] statement.2430** <li> The [PRAGMA schema_version=N] statement.2431** <li> Writes to the [sqlite_dbpage] virtual table.2432** <li> Direct writes to [shadow tables].2433** </ul>2434** </dd>2435**2436** [[SQLITE_DBCONFIG_WRITABLE_SCHEMA]] <dt>SQLITE_DBCONFIG_WRITABLE_SCHEMA</dt>2437** <dd>The SQLITE_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates the2438** "writable_schema" flag. This has the same effect and is logically equivalent2439** to setting [PRAGMA writable_schema=ON] or [PRAGMA writable_schema=OFF].2440** The first argument to this setting is an integer which is 0 to disable2441** the writable_schema, positive to enable writable_schema, or negative to2442** leave the setting unchanged. The second parameter is a pointer to an2443** integer into which is written 0 or 1 to indicate whether the writable_schema2444** is enabled or disabled following this call.2445** </dd>2446**2447** [[SQLITE_DBCONFIG_LEGACY_ALTER_TABLE]]2448** <dt>SQLITE_DBCONFIG_LEGACY_ALTER_TABLE</dt>2449** <dd>The SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates2450** the legacy behavior of the [ALTER TABLE RENAME] command such it2451** behaves as it did prior to [version 3.24.0] (2018-06-04).  See the2452** "Compatibility Notice" on the [ALTER TABLE RENAME documentation] for2453** additional information. This feature can also be turned on and off2454** using the [PRAGMA legacy_alter_table] statement.2455** </dd>2456**2457** [[SQLITE_DBCONFIG_DQS_DML]]2458** <dt>SQLITE_DBCONFIG_DQS_DML</dt>2459** <dd>The SQLITE_DBCONFIG_DQS_DML option activates or deactivates2460** the legacy [double-quoted string literal] misfeature for DML statements2461** only, that is DELETE, INSERT, SELECT, and UPDATE statements. The2462** default value of this setting is determined by the [-DSQLITE_DQS]2463** compile-time option.2464** </dd>2465**2466** [[SQLITE_DBCONFIG_DQS_DDL]]2467** <dt>SQLITE_DBCONFIG_DQS_DDL</dt>2468** <dd>The SQLITE_DBCONFIG_DQS option activates or deactivates2469** the legacy [double-quoted string literal] misfeature for DDL statements,2470** such as CREATE TABLE and CREATE INDEX. The2471** default value of this setting is determined by the [-DSQLITE_DQS]2472** compile-time option.2473** </dd>2474**2475** [[SQLITE_DBCONFIG_TRUSTED_SCHEMA]]2476** <dt>SQLITE_DBCONFIG_TRUSTED_SCHEMA</dt>2477** <dd>The SQLITE_DBCONFIG_TRUSTED_SCHEMA option tells SQLite to2478** assume that database schemas are untainted by malicious content.2479** When the SQLITE_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite2480** takes additional defensive steps to protect the application from harm2481** including:2482** <ul>2483** <li> Prohibit the use of SQL functions inside triggers, views,2484** CHECK constraints, DEFAULT clauses, expression indexes,2485** partial indexes, or generated columns2486** unless those functions are tagged with [SQLITE_INNOCUOUS].2487** <li> Prohibit the use of virtual tables inside of triggers or views2488** unless those virtual tables are tagged with [SQLITE_VTAB_INNOCUOUS].2489** </ul>2490** This setting defaults to "on" for legacy compatibility, however2491** all applications are advised to turn it off if possible. This setting2492** can also be controlled using the [PRAGMA trusted_schema] statement.2493** </dd>2494**2495** [[SQLITE_DBCONFIG_LEGACY_FILE_FORMAT]]2496** <dt>SQLITE_DBCONFIG_LEGACY_FILE_FORMAT</dt>2497** <dd>The SQLITE_DBCONFIG_LEGACY_FILE_FORMAT option activates or deactivates2498** the legacy file format flag.  When activated, this flag causes all newly2499** created database file to have a schema format version number (the 4-byte2500** integer found at offset 44 into the database header) of 1.  This in turn2501** means that the resulting database file will be readable and writable by2502** any SQLite version back to 3.0.0 ([dateof:3.0.0]).  Without this setting,2503** newly created databases are generally not understandable by SQLite versions2504** prior to 3.3.0 ([dateof:3.3.0]).  As these words are written, there2505** is now scarcely any need to generate database files that are compatible2506** all the way back to version 3.0.0, and so this setting is of little2507** practical use, but is provided so that SQLite can continue to claim the2508** ability to generate new database files that are compatible with  version2509** 3.0.0.2510** <p>Note that when the SQLITE_DBCONFIG_LEGACY_FILE_FORMAT setting is on,2511** the [VACUUM] command will fail with an obscure error when attempting to2512** process a table with generated columns and a descending index.  This is2513** not considered a bug since SQLite versions 3.3.0 and earlier do not support2514** either generated columns or descending indexes.2515** </dd>2516**2517** [[SQLITE_DBCONFIG_STMT_SCANSTATUS]]2518** <dt>SQLITE_DBCONFIG_STMT_SCANSTATUS</dt>2519** <dd>The SQLITE_DBCONFIG_STMT_SCANSTATUS option is only useful in2520** SQLITE_ENABLE_STMT_SCANSTATUS builds. In this case, it sets or clears2521** a flag that enables collection of the sqlite3_stmt_scanstatus_v2()2522** statistics. For statistics to be collected, the flag must be set on2523** the database handle both when the SQL statement is prepared and when it2524** is stepped. The flag is set (collection of statistics is enabled)2525** by default. <p>This option takes two arguments: an integer and a pointer to2526** an integer..  The first argument is 1, 0, or -1 to enable, disable, or2527** leave unchanged the statement scanstatus option.  If the second argument2528** is not NULL, then the value of the statement scanstatus setting after2529** processing the first argument is written into the integer that the second2530** argument points to.2531** </dd>2532**2533** [[SQLITE_DBCONFIG_REVERSE_SCANORDER]]2534** <dt>SQLITE_DBCONFIG_REVERSE_SCANORDER</dt>2535** <dd>The SQLITE_DBCONFIG_REVERSE_SCANORDER option changes the default order2536** in which tables and indexes are scanned so that the scans start at the end2537** and work toward the beginning rather than starting at the beginning and2538** working toward the end. Setting SQLITE_DBCONFIG_REVERSE_SCANORDER is the2539** same as setting [PRAGMA reverse_unordered_selects]. <p>This option takes2540** two arguments which are an integer and a pointer to an integer.  The first2541** argument is 1, 0, or -1 to enable, disable, or leave unchanged the2542** reverse scan order flag, respectively.  If the second argument is not NULL,2543** then 0 or 1 is written into the integer that the second argument points to2544** depending on if the reverse scan order flag is set after processing the2545** first argument.2546** </dd>2547**2548** [[SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE]]2549** <dt>SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE</dt>2550** <dd>The SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE option enables or disables2551** the ability of the [ATTACH DATABASE] SQL command to create a new database2552** file if the database filed named in the ATTACH command does not already2553** exist.  This ability of ATTACH to create a new database is enabled by2554** default.  Applications can disable or reenable the ability for ATTACH to2555** create new database files using this DBCONFIG option.<p>2556** This option takes two arguments which are an integer and a pointer2557** to an integer.  The first argument is 1, 0, or -1 to enable, disable, or2558** leave unchanged the attach-create flag, respectively.  If the second2559** argument is not NULL, then 0 or 1 is written into the integer that the2560** second argument points to depending on if the attach-create flag is set2561** after processing the first argument.2562** </dd>2563**2564** [[SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE]]2565** <dt>SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE</dt>2566** <dd>The SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE option enables or disables the2567** ability of the [ATTACH DATABASE] SQL command to open a database for writing.2568** This capability is enabled by default.  Applications can disable or2569** reenable this capability using the current DBCONFIG option.  If the2570** the this capability is disabled, the [ATTACH] command will still work,2571** but the database will be opened read-only.  If this option is disabled,2572** then the ability to create a new database using [ATTACH] is also disabled,2573** regardless of the value of the [SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE]2574** option.<p>2575** This option takes two arguments which are an integer and a pointer2576** to an integer.  The first argument is 1, 0, or -1 to enable, disable, or2577** leave unchanged the ability to ATTACH another database for writing,2578** respectively.  If the second argument is not NULL, then 0 or 1 is written2579** into the integer to which the second argument points, depending on whether2580** the ability to ATTACH a read/write database is enabled or disabled2581** after processing the first argument.2582** </dd>2583**2584** [[SQLITE_DBCONFIG_ENABLE_COMMENTS]]2585** <dt>SQLITE_DBCONFIG_ENABLE_COMMENTS</dt>2586** <dd>The SQLITE_DBCONFIG_ENABLE_COMMENTS option enables or disables the2587** ability to include comments in SQL text.  Comments are enabled by default.2588** An application can disable or reenable comments in SQL text using this2589** DBCONFIG option.<p>2590** This option takes two arguments which are an integer and a pointer2591** to an integer.  The first argument is 1, 0, or -1 to enable, disable, or2592** leave unchanged the ability to use comments in SQL text,2593** respectively.  If the second argument is not NULL, then 0 or 1 is written2594** into the integer that the second argument points to depending on if2595** comments are allowed in SQL text after processing the first argument.2596** </dd>2597**2598** </dl>2599**2600** [[DBCONFIG arguments]] <h3>Arguments To SQLITE_DBCONFIG Options</h3>2601**2602** <p>Most of the SQLITE_DBCONFIG options take two arguments, so that the2603** overall call to [sqlite3_db_config()] has a total of four parameters.2604** The first argument (the third parameter to sqlite3_db_config()) is a integer.2605** The second argument is a pointer to an integer.  If the first argument is 1,2606** then the option becomes enabled.  If the first integer argument is 0, then the2607** option is disabled.  If the first argument is -1, then the option setting2608** is unchanged.  The second argument, the pointer to an integer, may be NULL.2609** If the second argument is not NULL, then a value of 0 or 1 is written into2610** the integer to which the second argument points, depending on whether the2611** setting is disabled or enabled after applying any changes specified by2612** the first argument.2613**2614** <p>While most SQLITE_DBCONFIG options use the argument format2615** described in the previous paragraph, the [SQLITE_DBCONFIG_MAINDBNAME]2616** and [SQLITE_DBCONFIG_LOOKASIDE] options are different.  See the2617** documentation of those exceptional options for details.2618*/2619#define SQLITE_DBCONFIG_MAINDBNAME            1000 /* const char* */2620#define SQLITE_DBCONFIG_LOOKASIDE             1001 /* void* int int */2621#define SQLITE_DBCONFIG_ENABLE_FKEY           1002 /* int int* */2622#define SQLITE_DBCONFIG_ENABLE_TRIGGER        1003 /* int int* */2623#define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */2624#define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */2625#define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE      1006 /* int int* */2626#define SQLITE_DBCONFIG_ENABLE_QPSG           1007 /* int int* */2627#define SQLITE_DBCONFIG_TRIGGER_EQP           1008 /* int int* */2628#define SQLITE_DBCONFIG_RESET_DATABASE        1009 /* int int* */2629#define SQLITE_DBCONFIG_DEFENSIVE             1010 /* int int* */2630#define SQLITE_DBCONFIG_WRITABLE_SCHEMA       1011 /* int int* */2631#define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE    1012 /* int int* */2632#define SQLITE_DBCONFIG_DQS_DML               1013 /* int int* */2633#define SQLITE_DBCONFIG_DQS_DDL               1014 /* int int* */2634#define SQLITE_DBCONFIG_ENABLE_VIEW           1015 /* int int* */2635#define SQLITE_DBCONFIG_LEGACY_FILE_FORMAT    1016 /* int int* */2636#define SQLITE_DBCONFIG_TRUSTED_SCHEMA        1017 /* int int* */2637#define SQLITE_DBCONFIG_STMT_SCANSTATUS       1018 /* int int* */2638#define SQLITE_DBCONFIG_REVERSE_SCANORDER     1019 /* int int* */2639#define SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE  1020 /* int int* */2640#define SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE   1021 /* int int* */2641#define SQLITE_DBCONFIG_ENABLE_COMMENTS       1022 /* int int* */2642#define SQLITE_DBCONFIG_MAX                   1022 /* Largest DBCONFIG */26432644/*2645** CAPI3REF: Enable Or Disable Extended Result Codes2646** METHOD: sqlite32647**2648** ^The sqlite3_extended_result_codes() routine enables or disables the2649** [extended result codes] feature of SQLite. ^The extended result2650** codes are disabled by default for historical compatibility.2651*/2652SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);26532654/*2655** CAPI3REF: Last Insert Rowid2656** METHOD: sqlite32657**2658** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables)2659** has a unique 64-bit signed2660** integer key called the [ROWID | "rowid"]. ^The rowid is always available2661** as an undeclared column named ROWID, OID, or _ROWID_ as long as those2662** names are not also used by explicitly declared columns. ^If2663** the table has a column of type [INTEGER PRIMARY KEY] then that column2664** is another alias for the rowid.2665**2666** ^The sqlite3_last_insert_rowid(D) interface usually returns the [rowid] of2667** the most recent successful [INSERT] into a rowid table or [virtual table]2668** on database connection D. ^Inserts into [WITHOUT ROWID] tables are not2669** recorded. ^If no successful [INSERT]s into rowid tables have ever occurred2670** on the database connection D, then sqlite3_last_insert_rowid(D) returns2671** zero.2672**2673** As well as being set automatically as rows are inserted into database2674** tables, the value returned by this function may be set explicitly by2675** [sqlite3_set_last_insert_rowid()]2676**2677** Some virtual table implementations may INSERT rows into rowid tables as2678** part of committing a transaction (e.g. to flush data accumulated in memory2679** to disk). In this case subsequent calls to this function return the rowid2680** associated with these internal INSERT operations, which leads to2681** unintuitive results. Virtual table implementations that do write to rowid2682** tables in this way can avoid this problem by restoring the original2683** rowid value using [sqlite3_set_last_insert_rowid()] before returning2684** control to the user.2685**2686** ^(If an [INSERT] occurs within a trigger then this routine will2687** return the [rowid] of the inserted row as long as the trigger is2688** running. Once the trigger program ends, the value returned2689** by this routine reverts to what it was before the trigger was fired.)^2690**2691** ^An [INSERT] that fails due to a constraint violation is not a2692** successful [INSERT] and does not change the value returned by this2693** routine.  ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,2694** and INSERT OR ABORT make no changes to the return value of this2695** routine when their insertion fails.  ^(When INSERT OR REPLACE2696** encounters a constraint violation, it does not fail.  The2697** INSERT continues to completion after deleting rows that caused2698** the constraint problem so INSERT OR REPLACE will always change2699** the return value of this interface.)^2700**2701** ^For the purposes of this routine, an [INSERT] is considered to2702** be successful even if it is subsequently rolled back.2703**2704** This function is accessible to SQL statements via the2705** [last_insert_rowid() SQL function].2706**2707** If a separate thread performs a new [INSERT] on the same2708** database connection while the [sqlite3_last_insert_rowid()]2709** function is running and thus changes the last insert [rowid],2710** then the value returned by [sqlite3_last_insert_rowid()] is2711** unpredictable and might not equal either the old or the new2712** last insert [rowid].2713*/2714SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);27152716/*2717** CAPI3REF: Set the Last Insert Rowid value.2718** METHOD: sqlite32719**2720** The sqlite3_set_last_insert_rowid(D, R) method allows the application to2721** set the value returned by calling sqlite3_last_insert_rowid(D) to R2722** without inserting a row into the database.2723*/2724SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);27252726/*2727** CAPI3REF: Count The Number Of Rows Modified2728** METHOD: sqlite32729**2730** ^These functions return the number of rows modified, inserted or2731** deleted by the most recently completed INSERT, UPDATE or DELETE2732** statement on the database connection specified by the only parameter.2733** The two functions are identical except for the type of the return value2734** and that if the number of rows modified by the most recent INSERT, UPDATE,2735** or DELETE is greater than the maximum value supported by type "int", then2736** the return value of sqlite3_changes() is undefined. ^Executing any other2737** type of SQL statement does not modify the value returned by these functions.2738** For the purposes of this interface, a CREATE TABLE AS SELECT statement2739** does not count as an INSERT, UPDATE or DELETE statement and hence the rows2740** added to the new table by the CREATE TABLE AS SELECT statement are not2741** counted.2742**2743** ^Only changes made directly by the INSERT, UPDATE or DELETE statement are2744** considered - auxiliary changes caused by [CREATE TRIGGER | triggers],2745** [foreign key actions] or [REPLACE] constraint resolution are not counted.2746**2747** Changes to a view that are intercepted by2748** [INSTEAD OF trigger | INSTEAD OF triggers] are not counted. ^The value2749** returned by sqlite3_changes() immediately after an INSERT, UPDATE or2750** DELETE statement run on a view is always zero. Only changes made to real2751** tables are counted.2752**2753** Things are more complicated if the sqlite3_changes() function is2754** executed while a trigger program is running. This may happen if the2755** program uses the [changes() SQL function], or if some other callback2756** function invokes sqlite3_changes() directly. Essentially:2757**2758** <ul>2759**   <li> ^(Before entering a trigger program the value returned by2760**        sqlite3_changes() function is saved. After the trigger program2761**        has finished, the original value is restored.)^2762**2763**   <li> ^(Within a trigger program each INSERT, UPDATE and DELETE2764**        statement sets the value returned by sqlite3_changes()2765**        upon completion as normal. Of course, this value will not include2766**        any changes performed by sub-triggers, as the sqlite3_changes()2767**        value will be saved and restored after each sub-trigger has run.)^2768** </ul>2769**2770** ^This means that if the changes() SQL function (or similar) is used2771** by the first INSERT, UPDATE or DELETE statement within a trigger, it2772** returns the value as set when the calling statement began executing.2773** ^If it is used by the second or subsequent such statement within a trigger2774** program, the value returned reflects the number of rows modified by the2775** previous INSERT, UPDATE or DELETE statement within the same trigger.2776**2777** If a separate thread makes changes on the same database connection2778** while [sqlite3_changes()] is running then the value returned2779** is unpredictable and not meaningful.2780**2781** See also:2782** <ul>2783** <li> the [sqlite3_total_changes()] interface2784** <li> the [count_changes pragma]2785** <li> the [changes() SQL function]2786** <li> the [data_version pragma]2787** </ul>2788*/2789SQLITE_API int sqlite3_changes(sqlite3*);2790SQLITE_API sqlite3_int64 sqlite3_changes64(sqlite3*);27912792/*2793** CAPI3REF: Total Number Of Rows Modified2794** METHOD: sqlite32795**2796** ^These functions return the total number of rows inserted, modified or2797** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed2798** since the database connection was opened, including those executed as2799** part of trigger programs. The two functions are identical except for the2800** type of the return value and that if the number of rows modified by the2801** connection exceeds the maximum value supported by type "int", then2802** the return value of sqlite3_total_changes() is undefined. ^Executing2803** any other type of SQL statement does not affect the value returned by2804** sqlite3_total_changes().2805**2806** ^Changes made as part of [foreign key actions] are included in the2807** count, but those made as part of REPLACE constraint resolution are2808** not. ^Changes to a view that are intercepted by INSTEAD OF triggers2809** are not counted.2810**2811** The [sqlite3_total_changes(D)] interface only reports the number2812** of rows that changed due to SQL statement run against database2813** connection D.  Any changes by other database connections are ignored.2814** To detect changes against a database file from other database2815** connections use the [PRAGMA data_version] command or the2816** [SQLITE_FCNTL_DATA_VERSION] [file control].2817**2818** If a separate thread makes changes on the same database connection2819** while [sqlite3_total_changes()] is running then the value2820** returned is unpredictable and not meaningful.2821**2822** See also:2823** <ul>2824** <li> the [sqlite3_changes()] interface2825** <li> the [count_changes pragma]2826** <li> the [changes() SQL function]2827** <li> the [data_version pragma]2828** <li> the [SQLITE_FCNTL_DATA_VERSION] [file control]2829** </ul>2830*/2831SQLITE_API int sqlite3_total_changes(sqlite3*);2832SQLITE_API sqlite3_int64 sqlite3_total_changes64(sqlite3*);28332834/*2835** CAPI3REF: Interrupt A Long-Running Query2836** METHOD: sqlite32837**2838** ^This function causes any pending database operation to abort and2839** return at its earliest opportunity. This routine is typically2840** called in response to a user action such as pressing "Cancel"2841** or Ctrl-C where the user wants a long query operation to halt2842** immediately.2843**2844** ^It is safe to call this routine from a thread different from the2845** thread that is currently running the database operation.  But it2846** is not safe to call this routine with a [database connection] that2847** is closed or might close before sqlite3_interrupt() returns.2848**2849** ^If an SQL operation is very nearly finished at the time when2850** sqlite3_interrupt() is called, then it might not have an opportunity2851** to be interrupted and might continue to completion.2852**2853** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].2854** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE2855** that is inside an explicit transaction, then the entire transaction2856** will be rolled back automatically.2857**2858** ^The sqlite3_interrupt(D) call is in effect until all currently running2859** SQL statements on [database connection] D complete.  ^Any new SQL statements2860** that are started after the sqlite3_interrupt() call and before the2861** running statement count reaches zero are interrupted as if they had been2862** running prior to the sqlite3_interrupt() call.  ^New SQL statements2863** that are started after the running statement count reaches zero are2864** not effected by the sqlite3_interrupt().2865** ^A call to sqlite3_interrupt(D) that occurs when there are no running2866** SQL statements is a no-op and has no effect on SQL statements2867** that are started after the sqlite3_interrupt() call returns.2868**2869** ^The [sqlite3_is_interrupted(D)] interface can be used to determine whether2870** or not an interrupt is currently in effect for [database connection] D.2871** It returns 1 if an interrupt is currently in effect, or 0 otherwise.2872*/2873SQLITE_API void sqlite3_interrupt(sqlite3*);2874SQLITE_API int sqlite3_is_interrupted(sqlite3*);28752876/*2877** CAPI3REF: Determine If An SQL Statement Is Complete2878**2879** These routines are useful during command-line input to determine if the2880** currently entered text seems to form a complete SQL statement or2881** if additional input is needed before sending the text into2882** SQLite for parsing.  ^These routines return 1 if the input string2883** appears to be a complete SQL statement.  ^A statement is judged to be2884** complete if it ends with a semicolon token and is not a prefix of a2885** well-formed CREATE TRIGGER statement.  ^Semicolons that are embedded within2886** string literals or quoted identifier names or comments are not2887** independent tokens (they are part of the token in which they are2888** embedded) and thus do not count as a statement terminator.  ^Whitespace2889** and comments that follow the final semicolon are ignored.2890**2891** ^These routines return 0 if the statement is incomplete.  ^If a2892** memory allocation fails, then SQLITE_NOMEM is returned.2893**2894** ^These routines do not parse the SQL statements thus2895** will not detect syntactically incorrect SQL.2896**2897** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior2898** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked2899** automatically by sqlite3_complete16().  If that initialization fails,2900** then the return value from sqlite3_complete16() will be non-zero2901** regardless of whether or not the input SQL is complete.)^2902**2903** The input to [sqlite3_complete()] must be a zero-terminated2904** UTF-8 string.2905**2906** The input to [sqlite3_complete16()] must be a zero-terminated2907** UTF-16 string in native byte order.2908*/2909SQLITE_API int sqlite3_complete(const char *sql);2910SQLITE_API int sqlite3_complete16(const void *sql);29112912/*2913** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors2914** KEYWORDS: {busy-handler callback} {busy handler}2915** METHOD: sqlite32916**2917** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X2918** that might be invoked with argument P whenever2919** an attempt is made to access a database table associated with2920** [database connection] D when another thread2921** or process has the table locked.2922** The sqlite3_busy_handler() interface is used to implement2923** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout].2924**2925** ^If the busy callback is NULL, then [SQLITE_BUSY]2926** is returned immediately upon encountering the lock.  ^If the busy callback2927** is not NULL, then the callback might be invoked with two arguments.2928**2929** ^The first argument to the busy handler is a copy of the void* pointer which2930** is the third argument to sqlite3_busy_handler().  ^The second argument to2931** the busy handler callback is the number of times that the busy handler has2932** been invoked previously for the same locking event.  ^If the2933** busy callback returns 0, then no additional attempts are made to2934** access the database and [SQLITE_BUSY] is returned2935** to the application.2936** ^If the callback returns non-zero, then another attempt2937** is made to access the database and the cycle repeats.2938**2939** The presence of a busy handler does not guarantee that it will be invoked2940** when there is lock contention. ^If SQLite determines that invoking the busy2941** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]2942** to the application instead of invoking the2943** busy handler.2944** Consider a scenario where one process is holding a read lock that2945** it is trying to promote to a reserved lock and2946** a second process is holding a reserved lock that it is trying2947** to promote to an exclusive lock.  The first process cannot proceed2948** because it is blocked by the second and the second process cannot2949** proceed because it is blocked by the first.  If both processes2950** invoke the busy handlers, neither will make any progress.  Therefore,2951** SQLite returns [SQLITE_BUSY] for the first process, hoping that this2952** will induce the first process to release its read lock and allow2953** the second process to proceed.2954**2955** ^The default busy callback is NULL.2956**2957** ^(There can only be a single busy handler defined for each2958** [database connection].  Setting a new busy handler clears any2959** previously set handler.)^  ^Note that calling [sqlite3_busy_timeout()]2960** or evaluating [PRAGMA busy_timeout=N] will change the2961** busy handler and thus clear any previously set busy handler.2962**2963** The busy callback should not take any actions which modify the2964** database connection that invoked the busy handler.  In other words,2965** the busy handler is not reentrant.  Any such actions2966** result in undefined behavior.2967**2968** A busy handler must not close the database connection2969** or [prepared statement] that invoked the busy handler.2970*/2971SQLITE_API int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*);29722973/*2974** CAPI3REF: Set A Busy Timeout2975** METHOD: sqlite32976**2977** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps2978** for a specified amount of time when a table is locked.  ^The handler2979** will sleep multiple times until at least "ms" milliseconds of sleeping2980** have accumulated.  ^After at least "ms" milliseconds of sleeping,2981** the handler returns 0 which causes [sqlite3_step()] to return2982** [SQLITE_BUSY].2983**2984** ^Calling this routine with an argument less than or equal to zero2985** turns off all busy handlers.2986**2987** ^(There can only be a single busy handler for a particular2988** [database connection] at any given moment.  If another busy handler2989** was defined  (using [sqlite3_busy_handler()]) prior to calling2990** this routine, that other busy handler is cleared.)^2991**2992** See also:  [PRAGMA busy_timeout]2993*/2994SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);29952996/*2997** CAPI3REF: Convenience Routines For Running Queries2998** METHOD: sqlite32999**3000** This is a legacy interface that is preserved for backwards compatibility.3001** Use of this interface is not recommended.3002**3003** Definition: A <b>result table</b> is memory data structure created by the3004** [sqlite3_get_table()] interface.  A result table records the3005** complete query results from one or more queries.3006**3007** The table conceptually has a number of rows and columns.  But3008** these numbers are not part of the result table itself.  These3009** numbers are obtained separately.  Let N be the number of rows3010** and M be the number of columns.3011**3012** A result table is an array of pointers to zero-terminated UTF-8 strings.3013** There are (N+1)*M elements in the array.  The first M pointers point3014** to zero-terminated strings that  contain the names of the columns.3015** The remaining entries all point to query results.  NULL values result3016** in NULL pointers.  All other values are in their UTF-8 zero-terminated3017** string representation as returned by [sqlite3_column_text()].3018**3019** A result table might consist of one or more memory allocations.3020** It is not safe to pass a result table directly to [sqlite3_free()].3021** A result table should be deallocated using [sqlite3_free_table()].3022**3023** ^(As an example of the result table format, suppose a query result3024** is as follows:3025**3026** <blockquote><pre>3027**        Name        | Age3028**        -----------------------3029**        Alice       | 433030**        Bob         | 283031**        Cindy       | 213032** </pre></blockquote>3033**3034** There are two columns (M==2) and three rows (N==3).  Thus the3035** result table has 8 entries.  Suppose the result table is stored3036** in an array named azResult.  Then azResult holds this content:3037**3038** <blockquote><pre>3039**        azResult&#91;0] = "Name";3040**        azResult&#91;1] = "Age";3041**        azResult&#91;2] = "Alice";3042**        azResult&#91;3] = "43";3043**        azResult&#91;4] = "Bob";3044**        azResult&#91;5] = "28";3045**        azResult&#91;6] = "Cindy";3046**        azResult&#91;7] = "21";3047** </pre></blockquote>)^3048**3049** ^The sqlite3_get_table() function evaluates one or more3050** semicolon-separated SQL statements in the zero-terminated UTF-83051** string of its 2nd parameter and returns a result table to the3052** pointer given in its 3rd parameter.3053**3054** After the application has finished with the result from sqlite3_get_table(),3055** it must pass the result table pointer to sqlite3_free_table() in order to3056** release the memory that was malloced.  Because of the way the3057** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling3058** function must not try to call [sqlite3_free()] directly.  Only3059** [sqlite3_free_table()] is able to release the memory properly and safely.3060**3061** The sqlite3_get_table() interface is implemented as a wrapper around3062** [sqlite3_exec()].  The sqlite3_get_table() routine does not have access3063** to any internal data structures of SQLite.  It uses only the public3064** interface defined here.  As a consequence, errors that occur in the3065** wrapper layer outside of the internal [sqlite3_exec()] call are not3066** reflected in subsequent calls to [sqlite3_errcode()] or3067** [sqlite3_errmsg()].3068*/3069SQLITE_API int sqlite3_get_table(3070  sqlite3 *db,          /* An open database */3071  const char *zSql,     /* SQL to be evaluated */3072  char ***pazResult,    /* Results of the query */3073  int *pnRow,           /* Number of result rows written here */3074  int *pnColumn,        /* Number of result columns written here */3075  char **pzErrmsg       /* Error msg written here */3076);3077SQLITE_API void sqlite3_free_table(char **result);30783079/*3080** CAPI3REF: Formatted String Printing Functions3081**3082** These routines are work-alikes of the "printf()" family of functions3083** from the standard C library.3084** These routines understand most of the common formatting options from3085** the standard library printf()3086** plus some additional non-standard formats ([%q], [%Q], [%w], and [%z]).3087** See the [built-in printf()] documentation for details.3088**3089** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their3090** results into memory obtained from [sqlite3_malloc64()].3091** The strings returned by these two routines should be3092** released by [sqlite3_free()].  ^Both routines return a3093** NULL pointer if [sqlite3_malloc64()] is unable to allocate enough3094** memory to hold the resulting string.3095**3096** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from3097** the standard C library.  The result is written into the3098** buffer supplied as the second parameter whose size is given by3099** the first parameter. Note that the order of the3100** first two parameters is reversed from snprintf().)^  This is an3101** historical accident that cannot be fixed without breaking3102** backwards compatibility.  ^(Note also that sqlite3_snprintf()3103** returns a pointer to its buffer instead of the number of3104** characters actually written into the buffer.)^  We admit that3105** the number of characters written would be a more useful return3106** value but we cannot change the implementation of sqlite3_snprintf()3107** now without breaking compatibility.3108**3109** ^As long as the buffer size is greater than zero, sqlite3_snprintf()3110** guarantees that the buffer is always zero-terminated.  ^The first3111** parameter "n" is the total size of the buffer, including space for3112** the zero terminator.  So the longest string that can be completely3113** written will be n-1 characters.3114**3115** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().3116**3117** See also:  [built-in printf()], [printf() SQL function]3118*/3119SQLITE_API char *sqlite3_mprintf(const char*,...);3120SQLITE_API char *sqlite3_vmprintf(const char*, va_list);3121SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);3122SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);31233124/*3125** CAPI3REF: Memory Allocation Subsystem3126**3127** The SQLite core uses these three routines for all of its own3128** internal memory allocation needs. "Core" in the previous sentence3129** does not include operating-system specific [VFS] implementation.  The3130** Windows VFS uses native malloc() and free() for some operations.3131**3132** ^The sqlite3_malloc() routine returns a pointer to a block3133** of memory at least N bytes in length, where N is the parameter.3134** ^If sqlite3_malloc() is unable to obtain sufficient free3135** memory, it returns a NULL pointer.  ^If the parameter N to3136** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns3137** a NULL pointer.3138**3139** ^The sqlite3_malloc64(N) routine works just like3140** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead3141** of a signed 32-bit integer.3142**3143** ^Calling sqlite3_free() with a pointer previously returned3144** by sqlite3_malloc() or sqlite3_realloc() releases that memory so3145** that it might be reused.  ^The sqlite3_free() routine is3146** a no-op if is called with a NULL pointer.  Passing a NULL pointer3147** to sqlite3_free() is harmless.  After being freed, memory3148** should neither be read nor written.  Even reading previously freed3149** memory might result in a segmentation fault or other severe error.3150** Memory corruption, a segmentation fault, or other severe error3151** might result if sqlite3_free() is called with a non-NULL pointer that3152** was not obtained from sqlite3_malloc() or sqlite3_realloc().3153**3154** ^The sqlite3_realloc(X,N) interface attempts to resize a3155** prior memory allocation X to be at least N bytes.3156** ^If the X parameter to sqlite3_realloc(X,N)3157** is a NULL pointer then its behavior is identical to calling3158** sqlite3_malloc(N).3159** ^If the N parameter to sqlite3_realloc(X,N) is zero or3160** negative then the behavior is exactly the same as calling3161** sqlite3_free(X).3162** ^sqlite3_realloc(X,N) returns a pointer to a memory allocation3163** of at least N bytes in size or NULL if insufficient memory is available.3164** ^If M is the size of the prior allocation, then min(N,M) bytes3165** of the prior allocation are copied into the beginning of buffer returned3166** by sqlite3_realloc(X,N) and the prior allocation is freed.3167** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the3168** prior allocation is not freed.3169**3170** ^The sqlite3_realloc64(X,N) interfaces works the same as3171** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead3172** of a 32-bit signed integer.3173**3174** ^If X is a memory allocation previously obtained from sqlite3_malloc(),3175** sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then3176** sqlite3_msize(X) returns the size of that memory allocation in bytes.3177** ^The value returned by sqlite3_msize(X) might be larger than the number3178** of bytes requested when X was allocated.  ^If X is a NULL pointer then3179** sqlite3_msize(X) returns zero.  If X points to something that is not3180** the beginning of memory allocation, or if it points to a formerly3181** valid memory allocation that has now been freed, then the behavior3182** of sqlite3_msize(X) is undefined and possibly harmful.3183**3184** ^The memory returned by sqlite3_malloc(), sqlite3_realloc(),3185** sqlite3_malloc64(), and sqlite3_realloc64()3186** is always aligned to at least an 8 byte boundary, or to a3187** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time3188** option is used.3189**3190** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]3191** must be either NULL or else pointers obtained from a prior3192** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have3193** not yet been released.3194**3195** The application must not read or write any part of3196** a block of memory after it has been released using3197** [sqlite3_free()] or [sqlite3_realloc()].3198*/3199SQLITE_API void *sqlite3_malloc(int);3200SQLITE_API void *sqlite3_malloc64(sqlite3_uint64);3201SQLITE_API void *sqlite3_realloc(void*, int);3202SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64);3203SQLITE_API void sqlite3_free(void*);3204SQLITE_API sqlite3_uint64 sqlite3_msize(void*);32053206/*3207** CAPI3REF: Memory Allocator Statistics3208**3209** SQLite provides these two interfaces for reporting on the status3210** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]3211** routines, which form the built-in memory allocation subsystem.3212**3213** ^The [sqlite3_memory_used()] routine returns the number of bytes3214** of memory currently outstanding (malloced but not freed).3215** ^The [sqlite3_memory_highwater()] routine returns the maximum3216** value of [sqlite3_memory_used()] since the high-water mark3217** was last reset.  ^The values returned by [sqlite3_memory_used()] and3218** [sqlite3_memory_highwater()] include any overhead3219** added by SQLite in its implementation of [sqlite3_malloc()],3220** but not overhead added by the any underlying system library3221** routines that [sqlite3_malloc()] may call.3222**3223** ^The memory high-water mark is reset to the current value of3224** [sqlite3_memory_used()] if and only if the parameter to3225** [sqlite3_memory_highwater()] is true.  ^The value returned3226** by [sqlite3_memory_highwater(1)] is the high-water mark3227** prior to the reset.3228*/3229SQLITE_API sqlite3_int64 sqlite3_memory_used(void);3230SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);32313232/*3233** CAPI3REF: Pseudo-Random Number Generator3234**3235** SQLite contains a high-quality pseudo-random number generator (PRNG) used to3236** select random [ROWID | ROWIDs] when inserting new records into a table that3237** already uses the largest possible [ROWID].  The PRNG is also used for3238** the built-in random() and randomblob() SQL functions.  This interface allows3239** applications to access the same PRNG for other purposes.3240**3241** ^A call to this routine stores N bytes of randomness into buffer P.3242** ^The P parameter can be a NULL pointer.3243**3244** ^If this routine has not been previously called or if the previous3245** call had N less than one or a NULL pointer for P, then the PRNG is3246** seeded using randomness obtained from the xRandomness method of3247** the default [sqlite3_vfs] object.3248** ^If the previous call to this routine had an N of 1 or more and a3249** non-NULL P then the pseudo-randomness is generated3250** internally and without recourse to the [sqlite3_vfs] xRandomness3251** method.3252*/3253SQLITE_API void sqlite3_randomness(int N, void *P);32543255/*3256** CAPI3REF: Compile-Time Authorization Callbacks3257** METHOD: sqlite33258** KEYWORDS: {authorizer callback}3259**3260** ^This routine registers an authorizer callback with a particular3261** [database connection], supplied in the first argument.3262** ^The authorizer callback is invoked as SQL statements are being compiled3263** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],3264** [sqlite3_prepare_v3()], [sqlite3_prepare16()], [sqlite3_prepare16_v2()],3265** and [sqlite3_prepare16_v3()].  ^At various3266** points during the compilation process, as logic is being created3267** to perform various actions, the authorizer callback is invoked to3268** see if those actions are allowed.  ^The authorizer callback should3269** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the3270** specific action but allow the SQL statement to continue to be3271** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be3272** rejected with an error.  ^If the authorizer callback returns3273** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]3274** then the [sqlite3_prepare_v2()] or equivalent call that triggered3275** the authorizer will fail with an error message.3276**3277** When the callback returns [SQLITE_OK], that means the operation3278** requested is ok.  ^When the callback returns [SQLITE_DENY], the3279** [sqlite3_prepare_v2()] or equivalent call that triggered the3280** authorizer will fail with an error message explaining that3281** access is denied.3282**3283** ^The first parameter to the authorizer callback is a copy of the third3284** parameter to the sqlite3_set_authorizer() interface. ^The second parameter3285** to the callback is an integer [SQLITE_COPY | action code] that specifies3286** the particular action to be authorized. ^The third through sixth parameters3287** to the callback are either NULL pointers or zero-terminated strings3288** that contain additional details about the action to be authorized.3289** Applications must always be prepared to encounter a NULL pointer in any3290** of the third through the sixth parameters of the authorization callback.3291**3292** ^If the action code is [SQLITE_READ]3293** and the callback returns [SQLITE_IGNORE] then the3294** [prepared statement] statement is constructed to substitute3295** a NULL value in place of the table column that would have3296** been read if [SQLITE_OK] had been returned.  The [SQLITE_IGNORE]3297** return can be used to deny an untrusted user access to individual3298** columns of a table.3299** ^When a table is referenced by a [SELECT] but no column values are3300** extracted from that table (for example in a query like3301** "SELECT count(*) FROM tab") then the [SQLITE_READ] authorizer callback3302** is invoked once for that table with a column name that is an empty string.3303** ^If the action code is [SQLITE_DELETE] and the callback returns3304** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the3305** [truncate optimization] is disabled and all rows are deleted individually.3306**3307** An authorizer is used when [sqlite3_prepare | preparing]3308** SQL statements from an untrusted source, to ensure that the SQL statements3309** do not try to access data they are not allowed to see, or that they do not3310** try to execute malicious statements that damage the database.  For3311** example, an application may allow a user to enter arbitrary3312** SQL queries for evaluation by a database.  But the application does3313** not want the user to be able to make arbitrary changes to the3314** database.  An authorizer could then be put in place while the3315** user-entered SQL is being [sqlite3_prepare | prepared] that3316** disallows everything except [SELECT] statements.3317**3318** Applications that need to process SQL from untrusted sources3319** might also consider lowering resource limits using [sqlite3_limit()]3320** and limiting database size using the [max_page_count] [PRAGMA]3321** in addition to using an authorizer.3322**3323** ^(Only a single authorizer can be in place on a database connection3324** at a time.  Each call to sqlite3_set_authorizer overrides the3325** previous call.)^  ^Disable the authorizer by installing a NULL callback.3326** The authorizer is disabled by default.3327**3328** The authorizer callback must not do anything that will modify3329** the database connection that invoked the authorizer callback.3330** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their3331** database connections for the meaning of "modify" in this paragraph.3332**3333** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the3334** statement might be re-prepared during [sqlite3_step()] due to a3335** schema change.  Hence, the application should ensure that the3336** correct authorizer callback remains in place during the [sqlite3_step()].3337**3338** ^Note that the authorizer callback is invoked only during3339** [sqlite3_prepare()] or its variants.  Authorization is not3340** performed during statement evaluation in [sqlite3_step()], unless3341** as stated in the previous paragraph, sqlite3_step() invokes3342** sqlite3_prepare_v2() to reprepare a statement after a schema change.3343*/3344SQLITE_API int sqlite3_set_authorizer(3345  sqlite3*,3346  int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),3347  void *pUserData3348);33493350/*3351** CAPI3REF: Authorizer Return Codes3352**3353** The [sqlite3_set_authorizer | authorizer callback function] must3354** return either [SQLITE_OK] or one of these two constants in order3355** to signal SQLite whether or not the action is permitted.  See the3356** [sqlite3_set_authorizer | authorizer documentation] for additional3357** information.3358**3359** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]3360** returned from the [sqlite3_vtab_on_conflict()] interface.3361*/3362#define SQLITE_DENY   1   /* Abort the SQL statement with an error */3363#define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */33643365/*3366** CAPI3REF: Authorizer Action Codes3367**3368** The [sqlite3_set_authorizer()] interface registers a callback function3369** that is invoked to authorize certain SQL statement actions.  The3370** second parameter to the callback is an integer code that specifies3371** what action is being authorized.  These are the integer action codes that3372** the authorizer callback may be passed.3373**3374** These action code values signify what kind of operation is to be3375** authorized.  The 3rd and 4th parameters to the authorization3376** callback function will be parameters or NULL depending on which of these3377** codes is used as the second parameter.  ^(The 5th parameter to the3378** authorizer callback is the name of the database ("main", "temp",3379** etc.) if applicable.)^  ^The 6th parameter to the authorizer callback3380** is the name of the inner-most trigger or view that is responsible for3381** the access attempt or NULL if this access attempt is directly from3382** top-level SQL code.3383*/3384/******************************************* 3rd ************ 4th ***********/3385#define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */3386#define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */3387#define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */3388#define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */3389#define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */3390#define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */3391#define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */3392#define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */3393#define SQLITE_DELETE                9   /* Table Name      NULL            */3394#define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */3395#define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */3396#define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */3397#define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */3398#define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */3399#define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */3400#define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */3401#define SQLITE_DROP_VIEW            17   /* View Name       NULL            */3402#define SQLITE_INSERT               18   /* Table Name      NULL            */3403#define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */3404#define SQLITE_READ                 20   /* Table Name      Column Name     */3405#define SQLITE_SELECT               21   /* NULL            NULL            */3406#define SQLITE_TRANSACTION          22   /* Operation       NULL            */3407#define SQLITE_UPDATE               23   /* Table Name      Column Name     */3408#define SQLITE_ATTACH               24   /* Filename        NULL            */3409#define SQLITE_DETACH               25   /* Database Name   NULL            */3410#define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */3411#define SQLITE_REINDEX              27   /* Index Name      NULL            */3412#define SQLITE_ANALYZE              28   /* Table Name      NULL            */3413#define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */3414#define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */3415#define SQLITE_FUNCTION             31   /* NULL            Function Name   */3416#define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */3417#define SQLITE_COPY                  0   /* No longer used */3418#define SQLITE_RECURSIVE            33   /* NULL            NULL            */34193420/*3421** CAPI3REF: Deprecated Tracing And Profiling Functions3422** DEPRECATED3423**3424** These routines are deprecated. Use the [sqlite3_trace_v2()] interface3425** instead of the routines described here.3426**3427** These routines register callback functions that can be used for3428** tracing and profiling the execution of SQL statements.3429**3430** ^The callback function registered by sqlite3_trace() is invoked at3431** various times when an SQL statement is being run by [sqlite3_step()].3432** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the3433** SQL statement text as the statement first begins executing.3434** ^(Additional sqlite3_trace() callbacks might occur3435** as each triggered subprogram is entered.  The callbacks for triggers3436** contain a UTF-8 SQL comment that identifies the trigger.)^3437**3438** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit3439** the length of [bound parameter] expansion in the output of sqlite3_trace().3440**3441** ^The callback function registered by sqlite3_profile() is invoked3442** as each SQL statement finishes.  ^The profile callback contains3443** the original statement text and an estimate of wall-clock time3444** of how long that statement took to run.  ^The profile callback3445** time is in units of nanoseconds, however the current implementation3446** is only capable of millisecond resolution so the six least significant3447** digits in the time are meaningless.  Future versions of SQLite3448** might provide greater resolution on the profiler callback.  Invoking3449** either [sqlite3_trace()] or [sqlite3_trace_v2()] will cancel the3450** profile callback.3451*/3452SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*,3453   void(*xTrace)(void*,const char*), void*);3454SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,3455   void(*xProfile)(void*,const char*,sqlite3_uint64), void*);34563457/*3458** CAPI3REF: SQL Trace Event Codes3459** KEYWORDS: SQLITE_TRACE3460**3461** These constants identify classes of events that can be monitored3462** using the [sqlite3_trace_v2()] tracing logic.  The M argument3463** to [sqlite3_trace_v2(D,M,X,P)] is an OR-ed combination of one or more of3464** the following constants.  ^The first argument to the trace callback3465** is one of the following constants.3466**3467** New tracing constants may be added in future releases.3468**3469** ^A trace callback has four arguments: xCallback(T,C,P,X).3470** ^The T argument is one of the integer type codes above.3471** ^The C argument is a copy of the context pointer passed in as the3472** fourth argument to [sqlite3_trace_v2()].3473** The P and X arguments are pointers whose meanings depend on T.3474**3475** <dl>3476** [[SQLITE_TRACE_STMT]] <dt>SQLITE_TRACE_STMT</dt>3477** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement3478** first begins running and possibly at other times during the3479** execution of the prepared statement, such as at the start of each3480** trigger subprogram. ^The P argument is a pointer to the3481** [prepared statement]. ^The X argument is a pointer to a string which3482** is the unexpanded SQL text of the prepared statement or an SQL comment3483** that indicates the invocation of a trigger.  ^The callback can compute3484** the same text that would have been returned by the legacy [sqlite3_trace()]3485** interface by using the X argument when X begins with "--" and invoking3486** [sqlite3_expanded_sql(P)] otherwise.3487**3488** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt>3489** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same3490** information as is provided by the [sqlite3_profile()] callback.3491** ^The P argument is a pointer to the [prepared statement] and the3492** X argument points to a 64-bit integer which is approximately3493** the number of nanoseconds that the prepared statement took to run.3494** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.3495**3496** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>3497** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared3498** statement generates a single row of result.3499** ^The P argument is a pointer to the [prepared statement] and the3500** X argument is unused.3501**3502** [[SQLITE_TRACE_CLOSE]] <dt>SQLITE_TRACE_CLOSE</dt>3503** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database3504** connection closes.3505** ^The P argument is a pointer to the [database connection] object3506** and the X argument is unused.3507** </dl>3508*/3509#define SQLITE_TRACE_STMT       0x013510#define SQLITE_TRACE_PROFILE    0x023511#define SQLITE_TRACE_ROW        0x043512#define SQLITE_TRACE_CLOSE      0x0835133514/*3515** CAPI3REF: SQL Trace Hook3516** METHOD: sqlite33517**3518** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback3519** function X against [database connection] D, using property mask M3520** and context pointer P.  ^If the X callback is3521** NULL or if the M mask is zero, then tracing is disabled.  The3522** M argument should be the bitwise OR-ed combination of3523** zero or more [SQLITE_TRACE] constants.3524**3525** ^Each call to either sqlite3_trace(D,X,P) or sqlite3_trace_v2(D,M,X,P)3526** overrides (cancels) all prior calls to sqlite3_trace(D,X,P) or3527** sqlite3_trace_v2(D,M,X,P) for the [database connection] D.  Each3528** database connection may have at most one trace callback.3529**3530** ^The X callback is invoked whenever any of the events identified by3531** mask M occur.  ^The integer return value from the callback is currently3532** ignored, though this may change in future releases.  Callback3533** implementations should return zero to ensure future compatibility.3534**3535** ^A trace callback is invoked with four arguments: callback(T,C,P,X).3536** ^The T argument is one of the [SQLITE_TRACE]3537** constants to indicate why the callback was invoked.3538** ^The C argument is a copy of the context pointer.3539** The P and X arguments are pointers whose meanings depend on T.3540**3541** The sqlite3_trace_v2() interface is intended to replace the legacy3542** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which3543** are deprecated.3544*/3545SQLITE_API int sqlite3_trace_v2(3546  sqlite3*,3547  unsigned uMask,3548  int(*xCallback)(unsigned,void*,void*,void*),3549  void *pCtx3550);35513552/*3553** CAPI3REF: Query Progress Callbacks3554** METHOD: sqlite33555**3556** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback3557** function X to be invoked periodically during long running calls to3558** [sqlite3_step()] and [sqlite3_prepare()] and similar for3559** database connection D.  An example use for this3560** interface is to keep a GUI updated during a large query.3561**3562** ^The parameter P is passed through as the only parameter to the3563** callback function X.  ^The parameter N is the approximate number of3564** [virtual machine instructions] that are evaluated between successive3565** invocations of the callback X.  ^If N is less than one then the progress3566** handler is disabled.3567**3568** ^Only a single progress handler may be defined at one time per3569** [database connection]; setting a new progress handler cancels the3570** old one.  ^Setting parameter X to NULL disables the progress handler.3571** ^The progress handler is also disabled by setting N to a value less3572** than 1.3573**3574** ^If the progress callback returns non-zero, the operation is3575** interrupted.  This feature can be used to implement a3576** "Cancel" button on a GUI progress dialog box.3577**3578** The progress handler callback must not do anything that will modify3579** the database connection that invoked the progress handler.3580** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their3581** database connections for the meaning of "modify" in this paragraph.3582**3583** The progress handler callback would originally only be invoked from the3584** bytecode engine.  It still might be invoked during [sqlite3_prepare()]3585** and similar because those routines might force a reparse of the schema3586** which involves running the bytecode engine.  However, beginning with3587** SQLite version 3.41.0, the progress handler callback might also be3588** invoked directly from [sqlite3_prepare()] while analyzing and generating3589** code for complex queries.3590*/3591SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);35923593/*3594** CAPI3REF: Opening A New Database Connection3595** CONSTRUCTOR: sqlite33596**3597** ^These routines open an SQLite database file as specified by the3598** filename argument. ^The filename argument is interpreted as UTF-8 for3599** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte3600** order for sqlite3_open16(). ^(A [database connection] handle is usually3601** returned in *ppDb, even if an error occurs.  The only exception is that3602** if SQLite is unable to allocate memory to hold the [sqlite3] object,3603** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]3604** object.)^ ^(If the database is opened (and/or created) successfully, then3605** [SQLITE_OK] is returned.  Otherwise an [error code] is returned.)^ ^The3606** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain3607** an English language description of the error following a failure of any3608** of the sqlite3_open() routines.3609**3610** ^The default encoding will be UTF-8 for databases created using3611** sqlite3_open() or sqlite3_open_v2().  ^The default encoding for databases3612** created using sqlite3_open16() will be UTF-16 in the native byte order.3613**3614** Whether or not an error occurs when it is opened, resources3615** associated with the [database connection] handle should be released by3616** passing it to [sqlite3_close()] when it is no longer required.3617**3618** The sqlite3_open_v2() interface works like sqlite3_open()3619** except that it accepts two additional parameters for additional control3620** over the new database connection.  ^(The flags parameter to3621** sqlite3_open_v2() must include, at a minimum, one of the following3622** three flag combinations:)^3623**3624** <dl>3625** ^(<dt>[SQLITE_OPEN_READONLY]</dt>3626** <dd>The database is opened in read-only mode.  If the database does3627** not already exist, an error is returned.</dd>)^3628**3629** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>3630** <dd>The database is opened for reading and writing if possible, or3631** reading only if the file is write protected by the operating3632** system.  In either case the database must already exist, otherwise3633** an error is returned.  For historical reasons, if opening in3634** read-write mode fails due to OS-level permissions, an attempt is3635** made to open it in read-only mode. [sqlite3_db_readonly()] can be3636** used to determine whether the database is actually3637** read-write.</dd>)^3638**3639** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>3640** <dd>The database is opened for reading and writing, and is created if3641** it does not already exist. This is the behavior that is always used for3642** sqlite3_open() and sqlite3_open16().</dd>)^3643** </dl>3644**3645** In addition to the required flags, the following optional flags are3646** also supported:3647**3648** <dl>3649** ^(<dt>[SQLITE_OPEN_URI]</dt>3650** <dd>The filename can be interpreted as a URI if this flag is set.</dd>)^3651**3652** ^(<dt>[SQLITE_OPEN_MEMORY]</dt>3653** <dd>The database will be opened as an in-memory database.  The database3654** is named by the "filename" argument for the purposes of cache-sharing,3655** if shared cache mode is enabled, but the "filename" is otherwise ignored.3656** </dd>)^3657**3658** ^(<dt>[SQLITE_OPEN_NOMUTEX]</dt>3659** <dd>The new database connection will use the "multi-thread"3660** [threading mode].)^  This means that separate threads are allowed3661** to use SQLite at the same time, as long as each thread is using3662** a different [database connection].3663**3664** ^(<dt>[SQLITE_OPEN_FULLMUTEX]</dt>3665** <dd>The new database connection will use the "serialized"3666** [threading mode].)^  This means the multiple threads can safely3667** attempt to use the same database connection at the same time.3668** (Mutexes will block any actual concurrency, but in this mode3669** there is no harm in trying.)3670**3671** ^(<dt>[SQLITE_OPEN_SHAREDCACHE]</dt>3672** <dd>The database is opened [shared cache] enabled, overriding3673** the default shared cache setting provided by3674** [sqlite3_enable_shared_cache()].)^3675** The [use of shared cache mode is discouraged] and hence shared cache3676** capabilities may be omitted from many builds of SQLite.  In such cases,3677** this option is a no-op.3678**3679** ^(<dt>[SQLITE_OPEN_PRIVATECACHE]</dt>3680** <dd>The database is opened [shared cache] disabled, overriding3681** the default shared cache setting provided by3682** [sqlite3_enable_shared_cache()].)^3683**3684** [[OPEN_EXRESCODE]] ^(<dt>[SQLITE_OPEN_EXRESCODE]</dt>3685** <dd>The database connection comes up in "extended result code mode".3686** In other words, the database behaves as if3687** [sqlite3_extended_result_codes(db,1)] were called on the database3688** connection as soon as the connection is created. In addition to setting3689** the extended result code mode, this flag also causes [sqlite3_open_v2()]3690** to return an extended result code.</dd>3691**3692** [[OPEN_NOFOLLOW]] ^(<dt>[SQLITE_OPEN_NOFOLLOW]</dt>3693** <dd>The database filename is not allowed to contain a symbolic link</dd>3694** </dl>)^3695**3696** If the 3rd parameter to sqlite3_open_v2() is not one of the3697** required combinations shown above optionally combined with other3698** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]3699** then the behavior is undefined.  Historic versions of SQLite3700** have silently ignored surplus bits in the flags parameter to3701** sqlite3_open_v2(), however that behavior might not be carried through3702** into future versions of SQLite and so applications should not rely3703** upon it.  Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op3704** for sqlite3_open_v2().  The SQLITE_OPEN_EXCLUSIVE does *not* cause3705** the open to fail if the database already exists.  The SQLITE_OPEN_EXCLUSIVE3706** flag is intended for use by the [sqlite3_vfs|VFS interface] only, and not3707** by sqlite3_open_v2().3708**3709** ^The fourth parameter to sqlite3_open_v2() is the name of the3710** [sqlite3_vfs] object that defines the operating system interface that3711** the new database connection should use.  ^If the fourth parameter is3712** a NULL pointer then the default [sqlite3_vfs] object is used.3713**3714** ^If the filename is ":memory:", then a private, temporary in-memory database3715** is created for the connection.  ^This in-memory database will vanish when3716** the database connection is closed.  Future versions of SQLite might3717** make use of additional special filenames that begin with the ":" character.3718** It is recommended that when a database filename actually does begin with3719** a ":" character you should prefix the filename with a pathname such as3720** "./" to avoid ambiguity.3721**3722** ^If the filename is an empty string, then a private, temporary3723** on-disk database will be created.  ^This private database will be3724** automatically deleted as soon as the database connection is closed.3725**3726** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>3727**3728** ^If [URI filename] interpretation is enabled, and the filename argument3729** begins with "file:", then the filename is interpreted as a URI. ^URI3730** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is3731** set in the third argument to sqlite3_open_v2(), or if it has3732** been enabled globally using the [SQLITE_CONFIG_URI] option with the3733** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.3734** URI filename interpretation is turned off3735** by default, but future releases of SQLite might enable URI filename3736** interpretation by default.  See "[URI filenames]" for additional3737** information.3738**3739** URI filenames are parsed according to RFC 3986. ^If the URI contains an3740** authority, then it must be either an empty string or the string3741** "localhost". ^If the authority is not an empty string or "localhost", an3742** error is returned to the caller. ^The fragment component of a URI, if3743** present, is ignored.3744**3745** ^SQLite uses the path component of the URI as the name of the disk file3746** which contains the database. ^If the path begins with a '/' character,3747** then it is interpreted as an absolute path. ^If the path does not begin3748** with a '/' (meaning that the authority section is omitted from the URI)3749** then the path is interpreted as a relative path.3750** ^(On windows, the first component of an absolute path3751** is a drive specification (e.g. "C:").)^3752**3753** [[core URI query parameters]]3754** The query component of a URI may contain parameters that are interpreted3755** either by SQLite itself, or by a [VFS | custom VFS implementation].3756** SQLite and its built-in [VFSes] interpret the3757** following query parameters:3758**3759** <ul>3760**   <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of3761**     a VFS object that provides the operating system interface that should3762**     be used to access the database file on disk. ^If this option is set to3763**     an empty string the default VFS object is used. ^Specifying an unknown3764**     VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is3765**     present, then the VFS specified by the option takes precedence over3766**     the value passed as the fourth parameter to sqlite3_open_v2().3767**3768**   <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw",3769**     "rwc", or "memory". Attempting to set it to any other value is3770**     an error)^.3771**     ^If "ro" is specified, then the database is opened for read-only3772**     access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the3773**     third argument to sqlite3_open_v2(). ^If the mode option is set to3774**     "rw", then the database is opened for read-write (but not create)3775**     access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had3776**     been set. ^Value "rwc" is equivalent to setting both3777**     SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE.  ^If the mode option is3778**     set to "memory" then a pure [in-memory database] that never reads3779**     or writes from disk is used. ^It is an error to specify a value for3780**     the mode parameter that is less restrictive than that specified by3781**     the flags passed in the third parameter to sqlite3_open_v2().3782**3783**   <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or3784**     "private". ^Setting it to "shared" is equivalent to setting the3785**     SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to3786**     sqlite3_open_v2(). ^Setting the cache parameter to "private" is3787**     equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.3788**     ^If sqlite3_open_v2() is used and the "cache" parameter is present in3789**     a URI filename, its value overrides any behavior requested by setting3790**     SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.3791**3792**  <li> <b>psow</b>: ^The psow parameter indicates whether or not the3793**     [powersafe overwrite] property does or does not apply to the3794**     storage media on which the database file resides.3795**3796**  <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter3797**     which if set disables file locking in rollback journal modes.  This3798**     is useful for accessing a database on a filesystem that does not3799**     support locking.  Caution:  Database corruption might result if two3800**     or more processes write to the same database and any one of those3801**     processes uses nolock=1.3802**3803**  <li> <b>immutable</b>: ^The immutable parameter is a boolean query3804**     parameter that indicates that the database file is stored on3805**     read-only media.  ^When immutable is set, SQLite assumes that the3806**     database file cannot be changed, even by a process with higher3807**     privilege, and so the database is opened read-only and all locking3808**     and change detection is disabled.  Caution: Setting the immutable3809**     property on a database file that does in fact change can result3810**     in incorrect query results and/or [SQLITE_CORRUPT] errors.3811**     See also: [SQLITE_IOCAP_IMMUTABLE].3812**3813** </ul>3814**3815** ^Specifying an unknown parameter in the query component of a URI is not an3816** error.  Future versions of SQLite might understand additional query3817** parameters.  See "[query parameters with special meaning to SQLite]" for3818** additional information.3819**3820** [[URI filename examples]] <h3>URI filename examples</h3>3821**3822** <table border="1" align=center cellpadding=5>3823** <tr><th> URI filenames <th> Results3824** <tr><td> file:data.db <td>3825**          Open the file "data.db" in the current directory.3826** <tr><td> file:/home/fred/data.db<br>3827**          file:///home/fred/data.db <br>3828**          file://localhost/home/fred/data.db <br> <td>3829**          Open the database file "/home/fred/data.db".3830** <tr><td> file://darkstar/home/fred/data.db <td>3831**          An error. "darkstar" is not a recognized authority.3832** <tr><td style="white-space:nowrap">3833**          file:///C:/Documents%20and%20Settings/fred/Desktop/data.db3834**     <td> Windows only: Open the file "data.db" on fred's desktop on drive3835**          C:. Note that the %20 escaping in this example is not strictly3836**          necessary - space characters can be used literally3837**          in URI filenames.3838** <tr><td> file:data.db?mode=ro&cache=private <td>3839**          Open file "data.db" in the current directory for read-only access.3840**          Regardless of whether or not shared-cache mode is enabled by3841**          default, use a private cache.3842** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>3843**          Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"3844**          that uses dot-files in place of posix advisory locking.3845** <tr><td> file:data.db?mode=readonly <td>3846**          An error. "readonly" is not a valid option for the "mode" parameter.3847**          Use "ro" instead:  "file:data.db?mode=ro".3848** </table>3849**3850** ^URI hexadecimal escape sequences (%HH) are supported within the path and3851** query components of a URI. A hexadecimal escape sequence consists of a3852** percent sign - "%" - followed by exactly two hexadecimal digits3853** specifying an octet value. ^Before the path or query components of a3854** URI filename are interpreted, they are encoded using UTF-8 and all3855** hexadecimal escape sequences replaced by a single byte containing the3856** corresponding octet. If this process generates an invalid UTF-8 encoding,3857** the results are undefined.3858**3859** <b>Note to Windows users:</b>  The encoding used for the filename argument3860** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever3861** codepage is currently defined.  Filenames containing international3862** characters must be converted to UTF-8 prior to passing them into3863** sqlite3_open() or sqlite3_open_v2().3864**3865** <b>Note to Windows Runtime users:</b>  The temporary directory must be set3866** prior to calling sqlite3_open() or sqlite3_open_v2().  Otherwise, various3867** features that require the use of temporary files may fail.3868**3869** See also: [sqlite3_temp_directory]3870*/3871SQLITE_API int sqlite3_open(3872  const char *filename,   /* Database filename (UTF-8) */3873  sqlite3 **ppDb          /* OUT: SQLite db handle */3874);3875SQLITE_API int sqlite3_open16(3876  const void *filename,   /* Database filename (UTF-16) */3877  sqlite3 **ppDb          /* OUT: SQLite db handle */3878);3879SQLITE_API int sqlite3_open_v2(3880  const char *filename,   /* Database filename (UTF-8) */3881  sqlite3 **ppDb,         /* OUT: SQLite db handle */3882  int flags,              /* Flags */3883  const char *zVfs        /* Name of VFS module to use */3884);38853886/*3887** CAPI3REF: Obtain Values For URI Parameters3888**3889** These are utility routines, useful to [VFS|custom VFS implementations],3890** that check if a database file was a URI that contained a specific query3891** parameter, and if so obtains the value of that query parameter.3892**3893** The first parameter to these interfaces (hereafter referred to3894** as F) must be one of:3895** <ul>3896** <li> A database filename pointer created by the SQLite core and3897** passed into the xOpen() method of a VFS implementation, or3898** <li> A filename obtained from [sqlite3_db_filename()], or3899** <li> A new filename constructed using [sqlite3_create_filename()].3900** </ul>3901** If the F parameter is not one of the above, then the behavior is3902** undefined and probably undesirable.  Older versions of SQLite were3903** more tolerant of invalid F parameters than newer versions.3904**3905** If F is a suitable filename (as described in the previous paragraph)3906** and if P is the name of the query parameter, then3907** sqlite3_uri_parameter(F,P) returns the value of the P3908** parameter if it exists or a NULL pointer if P does not appear as a3909** query parameter on F.  If P is a query parameter of F and it3910** has no explicit value, then sqlite3_uri_parameter(F,P) returns3911** a pointer to an empty string.3912**3913** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean3914** parameter and returns true (1) or false (0) according to the value3915** of P.  The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the3916** value of query parameter P is one of "yes", "true", or "on" in any3917** case or if the value begins with a non-zero number.  The3918** sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of3919** query parameter P is one of "no", "false", or "off" in any case or3920** if the value begins with a numeric zero.  If P is not a query3921** parameter on F or if the value of P does not match any of the3922** above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).3923**3924** The sqlite3_uri_int64(F,P,D) routine converts the value of P into a3925** 64-bit signed integer and returns that integer, or D if P does not3926** exist.  If the value of P is something other than an integer, then3927** zero is returned.3928**3929** The sqlite3_uri_key(F,N) returns a pointer to the name (not3930** the value) of the N-th query parameter for filename F, or a NULL3931** pointer if N is less than zero or greater than the number of query3932** parameters minus 1.  The N value is zero-based so N should be 0 to obtain3933** the name of the first query parameter, 1 for the second parameter, and3934** so forth.3935**3936** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and3937** sqlite3_uri_boolean(F,P,B) returns B.  If F is not a NULL pointer and3938** is not a database file pathname pointer that the SQLite core passed3939** into the xOpen VFS method, then the behavior of this routine is undefined3940** and probably undesirable.3941**3942** Beginning with SQLite [version 3.31.0] ([dateof:3.31.0]) the input F3943** parameter can also be the name of a rollback journal file or WAL file3944** in addition to the main database file.  Prior to version 3.31.0, these3945** routines would only work if F was the name of the main database file.3946** When the F parameter is the name of the rollback journal or WAL file,3947** it has access to all the same query parameters as were found on the3948** main database file.3949**3950** See the [URI filename] documentation for additional information.3951*/3952SQLITE_API const char *sqlite3_uri_parameter(sqlite3_filename z, const char *zParam);3953SQLITE_API int sqlite3_uri_boolean(sqlite3_filename z, const char *zParam, int bDefault);3954SQLITE_API sqlite3_int64 sqlite3_uri_int64(sqlite3_filename, const char*, sqlite3_int64);3955SQLITE_API const char *sqlite3_uri_key(sqlite3_filename z, int N);39563957/*3958** CAPI3REF:  Translate filenames3959**3960** These routines are available to [VFS|custom VFS implementations] for3961** translating filenames between the main database file, the journal file,3962** and the WAL file.3963**3964** If F is the name of an sqlite database file, journal file, or WAL file3965** passed by the SQLite core into the VFS, then sqlite3_filename_database(F)3966** returns the name of the corresponding database file.3967**3968** If F is the name of an sqlite database file, journal file, or WAL file3969** passed by the SQLite core into the VFS, or if F is a database filename3970** obtained from [sqlite3_db_filename()], then sqlite3_filename_journal(F)3971** returns the name of the corresponding rollback journal file.3972**3973** If F is the name of an sqlite database file, journal file, or WAL file3974** that was passed by the SQLite core into the VFS, or if F is a database3975** filename obtained from [sqlite3_db_filename()], then3976** sqlite3_filename_wal(F) returns the name of the corresponding3977** WAL file.3978**3979** In all of the above, if F is not the name of a database, journal or WAL3980** filename passed into the VFS from the SQLite core and F is not the3981** return value from [sqlite3_db_filename()], then the result is3982** undefined and is likely a memory access violation.3983*/3984SQLITE_API const char *sqlite3_filename_database(sqlite3_filename);3985SQLITE_API const char *sqlite3_filename_journal(sqlite3_filename);3986SQLITE_API const char *sqlite3_filename_wal(sqlite3_filename);39873988/*3989** CAPI3REF:  Database File Corresponding To A Journal3990**3991** ^If X is the name of a rollback or WAL-mode journal file that is3992** passed into the xOpen method of [sqlite3_vfs], then3993** sqlite3_database_file_object(X) returns a pointer to the [sqlite3_file]3994** object that represents the main database file.3995**3996** This routine is intended for use in custom [VFS] implementations3997** only.  It is not a general-purpose interface.3998** The argument sqlite3_file_object(X) must be a filename pointer that3999** has been passed into [sqlite3_vfs].xOpen method where the4000** flags parameter to xOpen contains one of the bits4001** [SQLITE_OPEN_MAIN_JOURNAL] or [SQLITE_OPEN_WAL].  Any other use4002** of this routine results in undefined and probably undesirable4003** behavior.4004*/4005SQLITE_API sqlite3_file *sqlite3_database_file_object(const char*);40064007/*4008** CAPI3REF: Create and Destroy VFS Filenames4009**4010** These interfaces are provided for use by [VFS shim] implementations and4011** are not useful outside of that context.4012**4013** The sqlite3_create_filename(D,J,W,N,P) allocates memory to hold a version of4014** database filename D with corresponding journal file J and WAL file W and4015** with N URI parameters key/values pairs in the array P.  The result from4016** sqlite3_create_filename(D,J,W,N,P) is a pointer to a database filename that4017** is safe to pass to routines like:4018** <ul>4019** <li> [sqlite3_uri_parameter()],4020** <li> [sqlite3_uri_boolean()],4021** <li> [sqlite3_uri_int64()],4022** <li> [sqlite3_uri_key()],4023** <li> [sqlite3_filename_database()],4024** <li> [sqlite3_filename_journal()], or4025** <li> [sqlite3_filename_wal()].4026** </ul>4027** If a memory allocation error occurs, sqlite3_create_filename() might4028** return a NULL pointer.  The memory obtained from sqlite3_create_filename(X)4029** must be released by a corresponding call to sqlite3_free_filename(Y).4030**4031** The P parameter in sqlite3_create_filename(D,J,W,N,P) should be an array4032** of 2*N pointers to strings.  Each pair of pointers in this array corresponds4033** to a key and value for a query parameter.  The P parameter may be a NULL4034** pointer if N is zero.  None of the 2*N pointers in the P array may be4035** NULL pointers and key pointers should not be empty strings.4036** None of the D, J, or W parameters to sqlite3_create_filename(D,J,W,N,P) may4037** be NULL pointers, though they can be empty strings.4038**4039** The sqlite3_free_filename(Y) routine releases a memory allocation4040** previously obtained from sqlite3_create_filename().  Invoking4041** sqlite3_free_filename(Y) where Y is a NULL pointer is a harmless no-op.4042**4043** If the Y parameter to sqlite3_free_filename(Y) is anything other4044** than a NULL pointer or a pointer previously acquired from4045** sqlite3_create_filename(), then bad things such as heap4046** corruption or segfaults may occur. The value Y should not be4047** used again after sqlite3_free_filename(Y) has been called.  This means4048** that if the [sqlite3_vfs.xOpen()] method of a VFS has been called using Y,4049** then the corresponding [sqlite3_module.xClose() method should also be4050** invoked prior to calling sqlite3_free_filename(Y).4051*/4052SQLITE_API sqlite3_filename sqlite3_create_filename(4053  const char *zDatabase,4054  const char *zJournal,4055  const char *zWal,4056  int nParam,4057  const char **azParam4058);4059SQLITE_API void sqlite3_free_filename(sqlite3_filename);40604061/*4062** CAPI3REF: Error Codes And Messages4063** METHOD: sqlite34064**4065** ^If the most recent sqlite3_* API call associated with4066** [database connection] D failed, then the sqlite3_errcode(D) interface4067** returns the numeric [result code] or [extended result code] for that4068** API call.4069** ^The sqlite3_extended_errcode()4070** interface is the same except that it always returns the4071** [extended result code] even when extended result codes are4072** disabled.4073**4074** The values returned by sqlite3_errcode() and/or4075** sqlite3_extended_errcode() might change with each API call.4076** Except, there are some interfaces that are guaranteed to never4077** change the value of the error code.  The error-code preserving4078** interfaces include the following:4079**4080** <ul>4081** <li> sqlite3_errcode()4082** <li> sqlite3_extended_errcode()4083** <li> sqlite3_errmsg()4084** <li> sqlite3_errmsg16()4085** <li> sqlite3_error_offset()4086** </ul>4087**4088** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language4089** text that describes the error, as either UTF-8 or UTF-16 respectively,4090** or NULL if no error message is available.4091** (See how SQLite handles [invalid UTF] for exceptions to this rule.)4092** ^(Memory to hold the error message string is managed internally.4093** The application does not need to worry about freeing the result.4094** However, the error string might be overwritten or deallocated by4095** subsequent calls to other SQLite interface functions.)^4096**4097** ^The sqlite3_errstr(E) interface returns the English-language text4098** that describes the [result code] E, as UTF-8, or NULL if E is not an4099** result code for which a text error message is available.4100** ^(Memory to hold the error message string is managed internally4101** and must not be freed by the application)^.4102**4103** ^If the most recent error references a specific token in the input4104** SQL, the sqlite3_error_offset() interface returns the byte offset4105** of the start of that token.  ^The byte offset returned by4106** sqlite3_error_offset() assumes that the input SQL is UTF8.4107** ^If the most recent error does not reference a specific token in the input4108** SQL, then the sqlite3_error_offset() function returns -1.4109**4110** When the serialized [threading mode] is in use, it might be the4111** case that a second error occurs on a separate thread in between4112** the time of the first error and the call to these interfaces.4113** When that happens, the second error will be reported since these4114** interfaces always report the most recent result.  To avoid4115** this, each thread can obtain exclusive use of the [database connection] D4116** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning4117** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after4118** all calls to the interfaces listed here are completed.4119**4120** If an interface fails with SQLITE_MISUSE, that means the interface4121** was invoked incorrectly by the application.  In that case, the4122** error code and message may or may not be set.4123*/4124SQLITE_API int sqlite3_errcode(sqlite3 *db);4125SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);4126SQLITE_API const char *sqlite3_errmsg(sqlite3*);4127SQLITE_API const void *sqlite3_errmsg16(sqlite3*);4128SQLITE_API const char *sqlite3_errstr(int);4129SQLITE_API int sqlite3_error_offset(sqlite3 *db);41304131/*4132** CAPI3REF: Prepared Statement Object4133** KEYWORDS: {prepared statement} {prepared statements}4134**4135** An instance of this object represents a single SQL statement that4136** has been compiled into binary form and is ready to be evaluated.4137**4138** Think of each SQL statement as a separate computer program.  The4139** original SQL text is source code.  A prepared statement object4140** is the compiled object code.  All SQL must be converted into a4141** prepared statement before it can be run.4142**4143** The life-cycle of a prepared statement object usually goes like this:4144**4145** <ol>4146** <li> Create the prepared statement object using [sqlite3_prepare_v2()].4147** <li> Bind values to [parameters] using the sqlite3_bind_*()4148**      interfaces.4149** <li> Run the SQL by calling [sqlite3_step()] one or more times.4150** <li> Reset the prepared statement using [sqlite3_reset()] then go back4151**      to step 2.  Do this zero or more times.4152** <li> Destroy the object using [sqlite3_finalize()].4153** </ol>4154*/4155typedef struct sqlite3_stmt sqlite3_stmt;41564157/*4158** CAPI3REF: Run-time Limits4159** METHOD: sqlite34160**4161** ^(This interface allows the size of various constructs to be limited4162** on a connection by connection basis.  The first parameter is the4163** [database connection] whose limit is to be set or queried.  The4164** second parameter is one of the [limit categories] that define a4165** class of constructs to be size limited.  The third parameter is the4166** new limit for that construct.)^4167**4168** ^If the new limit is a negative number, the limit is unchanged.4169** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a4170** [limits | hard upper bound]4171** set at compile-time by a C preprocessor macro called4172** [limits | SQLITE_MAX_<i>NAME</i>].4173** (The "_LIMIT_" in the name is changed to "_MAX_".))^4174** ^Attempts to increase a limit above its hard upper bound are4175** silently truncated to the hard upper bound.4176**4177** ^Regardless of whether or not the limit was changed, the4178** [sqlite3_limit()] interface returns the prior value of the limit.4179** ^Hence, to find the current value of a limit without changing it,4180** simply invoke this interface with the third parameter set to -1.4181**4182** Run-time limits are intended for use in applications that manage4183** both their own internal database and also databases that are controlled4184** by untrusted external sources.  An example application might be a4185** web browser that has its own databases for storing history and4186** separate databases controlled by JavaScript applications downloaded4187** off the Internet.  The internal databases can be given the4188** large, default limits.  Databases managed by external sources can4189** be given much smaller limits designed to prevent a denial of service4190** attack.  Developers might also want to use the [sqlite3_set_authorizer()]4191** interface to further control untrusted SQL.  The size of the database4192** created by an untrusted script can be contained using the4193** [max_page_count] [PRAGMA].4194**4195** New run-time limit categories may be added in future releases.4196*/4197SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);41984199/*4200** CAPI3REF: Run-Time Limit Categories4201** KEYWORDS: {limit category} {*limit categories}4202**4203** These constants define various performance limits4204** that can be lowered at run-time using [sqlite3_limit()].4205** The synopsis of the meanings of the various limits is shown below.4206** Additional information is available at [limits | Limits in SQLite].4207**4208** <dl>4209** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt>4210** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^4211**4212** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>4213** <dd>The maximum length of an SQL statement, in bytes.</dd>)^4214**4215** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt>4216** <dd>The maximum number of columns in a table definition or in the4217** result set of a [SELECT] or the maximum number of columns in an index4218** or in an ORDER BY or GROUP BY clause.</dd>)^4219**4220** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>4221** <dd>The maximum depth of the parse tree on any expression.</dd>)^4222**4223** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>4224** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^4225**4226** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>4227** <dd>The maximum number of instructions in a virtual machine program4228** used to implement an SQL statement.  If [sqlite3_prepare_v2()] or4229** the equivalent tries to allocate space for more than this many opcodes4230** in a single prepared statement, an SQLITE_NOMEM error is returned.</dd>)^4231**4232** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>4233** <dd>The maximum number of arguments on a function.</dd>)^4234**4235** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>4236** <dd>The maximum number of [ATTACH | attached databases].)^</dd>4237**4238** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]4239** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>4240** <dd>The maximum length of the pattern argument to the [LIKE] or4241** [GLOB] operators.</dd>)^4242**4243** [[SQLITE_LIMIT_VARIABLE_NUMBER]]4244** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>4245** <dd>The maximum index number of any [parameter] in an SQL statement.)^4246**4247** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>4248** <dd>The maximum depth of recursion for triggers.</dd>)^4249**4250** [[SQLITE_LIMIT_WORKER_THREADS]] ^(<dt>SQLITE_LIMIT_WORKER_THREADS</dt>4251** <dd>The maximum number of auxiliary worker threads that a single4252** [prepared statement] may start.</dd>)^4253** </dl>4254*/4255#define SQLITE_LIMIT_LENGTH                    04256#define SQLITE_LIMIT_SQL_LENGTH                14257#define SQLITE_LIMIT_COLUMN                    24258#define SQLITE_LIMIT_EXPR_DEPTH                34259#define SQLITE_LIMIT_COMPOUND_SELECT           44260#define SQLITE_LIMIT_VDBE_OP                   54261#define SQLITE_LIMIT_FUNCTION_ARG              64262#define SQLITE_LIMIT_ATTACHED                  74263#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH       84264#define SQLITE_LIMIT_VARIABLE_NUMBER           94265#define SQLITE_LIMIT_TRIGGER_DEPTH            104266#define SQLITE_LIMIT_WORKER_THREADS           1142674268/*4269** CAPI3REF: Prepare Flags4270**4271** These constants define various flags that can be passed into4272** "prepFlags" parameter of the [sqlite3_prepare_v3()] and4273** [sqlite3_prepare16_v3()] interfaces.4274**4275** New flags may be added in future releases of SQLite.4276**4277** <dl>4278** [[SQLITE_PREPARE_PERSISTENT]] ^(<dt>SQLITE_PREPARE_PERSISTENT</dt>4279** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner4280** that the prepared statement will be retained for a long time and4281** probably reused many times.)^ ^Without this flag, [sqlite3_prepare_v3()]4282** and [sqlite3_prepare16_v3()] assume that the prepared statement will4283** be used just once or at most a few times and then destroyed using4284** [sqlite3_finalize()] relatively soon. The current implementation acts4285** on this hint by avoiding the use of [lookaside memory] so as not to4286** deplete the limited store of lookaside memory. Future versions of4287** SQLite may act on this hint differently.4288**4289** [[SQLITE_PREPARE_NORMALIZE]] <dt>SQLITE_PREPARE_NORMALIZE</dt>4290** <dd>The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used4291** to be required for any prepared statement that wanted to use the4292** [sqlite3_normalized_sql()] interface.  However, the4293** [sqlite3_normalized_sql()] interface is now available to all4294** prepared statements, regardless of whether or not they use this4295** flag.4296**4297** [[SQLITE_PREPARE_NO_VTAB]] <dt>SQLITE_PREPARE_NO_VTAB</dt>4298** <dd>The SQLITE_PREPARE_NO_VTAB flag causes the SQL compiler4299** to return an error (error code SQLITE_ERROR) if the statement uses4300** any virtual tables.4301**4302** [[SQLITE_PREPARE_DONT_LOG]] <dt>SQLITE_PREPARE_DONT_LOG</dt>4303** <dd>The SQLITE_PREPARE_DONT_LOG flag prevents SQL compiler4304** errors from being sent to the error log defined by4305** [SQLITE_CONFIG_LOG].  This can be used, for example, to do test4306** compiles to see if some SQL syntax is well-formed, without generating4307** messages on the global error log when it is not.  If the test compile4308** fails, the sqlite3_prepare_v3() call returns the same error indications4309** with or without this flag; it just omits the call to [sqlite3_log()] that4310** logs the error.4311** </dl>4312*/4313#define SQLITE_PREPARE_PERSISTENT              0x014314#define SQLITE_PREPARE_NORMALIZE               0x024315#define SQLITE_PREPARE_NO_VTAB                 0x044316#define SQLITE_PREPARE_DONT_LOG                0x1043174318/*4319** CAPI3REF: Compiling An SQL Statement4320** KEYWORDS: {SQL statement compiler}4321** METHOD: sqlite34322** CONSTRUCTOR: sqlite3_stmt4323**4324** To execute an SQL statement, it must first be compiled into a byte-code4325** program using one of these routines.  Or, in other words, these routines4326** are constructors for the [prepared statement] object.4327**4328** The preferred routine to use is [sqlite3_prepare_v2()].  The4329** [sqlite3_prepare()] interface is legacy and should be avoided.4330** [sqlite3_prepare_v3()] has an extra "prepFlags" option that is used4331** for special purposes.4332**4333** The use of the UTF-8 interfaces is preferred, as SQLite currently4334** does all parsing using UTF-8.  The UTF-16 interfaces are provided4335** as a convenience.  The UTF-16 interfaces work by converting the4336** input text into UTF-8, then invoking the corresponding UTF-8 interface.4337**4338** The first argument, "db", is a [database connection] obtained from a4339** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or4340** [sqlite3_open16()].  The database connection must not have been closed.4341**4342** The second argument, "zSql", is the statement to be compiled, encoded4343** as either UTF-8 or UTF-16.  The sqlite3_prepare(), sqlite3_prepare_v2(),4344** and sqlite3_prepare_v3()4345** interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),4346** and sqlite3_prepare16_v3() use UTF-16.4347**4348** ^If the nByte argument is negative, then zSql is read up to the4349** first zero terminator. ^If nByte is positive, then it is the maximum4350** number of bytes read from zSql.  When nByte is positive, zSql is read4351** up to the first zero terminator or until the nByte bytes have been read,4352** whichever comes first.  ^If nByte is zero, then no prepared4353** statement is generated.4354** If the caller knows that the supplied string is nul-terminated, then4355** there is a small performance advantage to passing an nByte parameter that4356** is the number of bytes in the input string <i>including</i>4357** the nul-terminator.4358** Note that nByte measure the length of the input in bytes, not4359** characters, even for the UTF-16 interfaces.4360**4361** ^If pzTail is not NULL then *pzTail is made to point to the first byte4362** past the end of the first SQL statement in zSql.  These routines only4363** compile the first statement in zSql, so *pzTail is left pointing to4364** what remains uncompiled.4365**4366** ^*ppStmt is left pointing to a compiled [prepared statement] that can be4367** executed using [sqlite3_step()].  ^If there is an error, *ppStmt is set4368** to NULL.  ^If the input text contains no SQL (if the input is an empty4369** string or a comment) then *ppStmt is set to NULL.4370** The calling procedure is responsible for deleting the compiled4371** SQL statement using [sqlite3_finalize()] after it has finished with it.4372** ppStmt may not be NULL.4373**4374** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];4375** otherwise an [error code] is returned.4376**4377** The sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(),4378** and sqlite3_prepare16_v3() interfaces are recommended for all new programs.4379** The older interfaces (sqlite3_prepare() and sqlite3_prepare16())4380** are retained for backwards compatibility, but their use is discouraged.4381** ^In the "vX" interfaces, the prepared statement4382** that is returned (the [sqlite3_stmt] object) contains a copy of the4383** original SQL text. This causes the [sqlite3_step()] interface to4384** behave differently in three ways:4385**4386** <ol>4387** <li>4388** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it4389** always used to do, [sqlite3_step()] will automatically recompile the SQL4390** statement and try to run it again. As many as [SQLITE_MAX_SCHEMA_RETRY]4391** retries will occur before sqlite3_step() gives up and returns an error.4392** </li>4393**4394** <li>4395** ^When an error occurs, [sqlite3_step()] will return one of the detailed4396** [error codes] or [extended error codes].  ^The legacy behavior was that4397** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code4398** and the application would have to make a second call to [sqlite3_reset()]4399** in order to find the underlying cause of the problem. With the "v2" prepare4400** interfaces, the underlying reason for the error is returned immediately.4401** </li>4402**4403** <li>4404** ^If the specific value bound to a [parameter | host parameter] in the4405** WHERE clause might influence the choice of query plan for a statement,4406** then the statement will be automatically recompiled, as if there had been4407** a schema change, on the first [sqlite3_step()] call following any change4408** to the [sqlite3_bind_text | bindings] of that [parameter].4409** ^The specific value of a WHERE-clause [parameter] might influence the4410** choice of query plan if the parameter is the left-hand side of a [LIKE]4411** or [GLOB] operator or if the parameter is compared to an indexed column4412** and the [SQLITE_ENABLE_STAT4] compile-time option is enabled.4413** </li>4414** </ol>4415**4416** <p>^sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having4417** the extra prepFlags parameter, which is a bit array consisting of zero or4418** more of the [SQLITE_PREPARE_PERSISTENT|SQLITE_PREPARE_*] flags.  ^The4419** sqlite3_prepare_v2() interface works exactly the same as4420** sqlite3_prepare_v3() with a zero prepFlags parameter.4421*/4422SQLITE_API int sqlite3_prepare(4423  sqlite3 *db,            /* Database handle */4424  const char *zSql,       /* SQL statement, UTF-8 encoded */4425  int nByte,              /* Maximum length of zSql in bytes. */4426  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */4427  const char **pzTail     /* OUT: Pointer to unused portion of zSql */4428);4429SQLITE_API int sqlite3_prepare_v2(4430  sqlite3 *db,            /* Database handle */4431  const char *zSql,       /* SQL statement, UTF-8 encoded */4432  int nByte,              /* Maximum length of zSql in bytes. */4433  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */4434  const char **pzTail     /* OUT: Pointer to unused portion of zSql */4435);4436SQLITE_API int sqlite3_prepare_v3(4437  sqlite3 *db,            /* Database handle */4438  const char *zSql,       /* SQL statement, UTF-8 encoded */4439  int nByte,              /* Maximum length of zSql in bytes. */4440  unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */4441  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */4442  const char **pzTail     /* OUT: Pointer to unused portion of zSql */4443);4444SQLITE_API int sqlite3_prepare16(4445  sqlite3 *db,            /* Database handle */4446  const void *zSql,       /* SQL statement, UTF-16 encoded */4447  int nByte,              /* Maximum length of zSql in bytes. */4448  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */4449  const void **pzTail     /* OUT: Pointer to unused portion of zSql */4450);4451SQLITE_API int sqlite3_prepare16_v2(4452  sqlite3 *db,            /* Database handle */4453  const void *zSql,       /* SQL statement, UTF-16 encoded */4454  int nByte,              /* Maximum length of zSql in bytes. */4455  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */4456  const void **pzTail     /* OUT: Pointer to unused portion of zSql */4457);4458SQLITE_API int sqlite3_prepare16_v3(4459  sqlite3 *db,            /* Database handle */4460  const void *zSql,       /* SQL statement, UTF-16 encoded */4461  int nByte,              /* Maximum length of zSql in bytes. */4462  unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */4463  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */4464  const void **pzTail     /* OUT: Pointer to unused portion of zSql */4465);44664467/*4468** CAPI3REF: Retrieving Statement SQL4469** METHOD: sqlite3_stmt4470**4471** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-84472** SQL text used to create [prepared statement] P if P was4473** created by [sqlite3_prepare_v2()], [sqlite3_prepare_v3()],4474** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].4475** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-84476** string containing the SQL text of prepared statement P with4477** [bound parameters] expanded.4478** ^The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-84479** string containing the normalized SQL text of prepared statement P.  The4480** semantics used to normalize a SQL statement are unspecified and subject4481** to change.  At a minimum, literal values will be replaced with suitable4482** placeholders.4483**4484** ^(For example, if a prepared statement is created using the SQL4485** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 23454486** and parameter :xyz is unbound, then sqlite3_sql() will return4487** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql()4488** will return "SELECT 2345,NULL".)^4489**4490** ^The sqlite3_expanded_sql() interface returns NULL if insufficient memory4491** is available to hold the result, or if the result would exceed the4492** the maximum string length determined by the [SQLITE_LIMIT_LENGTH].4493**4494** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of4495** bound parameter expansions.  ^The [SQLITE_OMIT_TRACE] compile-time4496** option causes sqlite3_expanded_sql() to always return NULL.4497**4498** ^The strings returned by sqlite3_sql(P) and sqlite3_normalized_sql(P)4499** are managed by SQLite and are automatically freed when the prepared4500** statement is finalized.4501** ^The string returned by sqlite3_expanded_sql(P), on the other hand,4502** is obtained from [sqlite3_malloc()] and must be freed by the application4503** by passing it to [sqlite3_free()].4504**4505** ^The sqlite3_normalized_sql() interface is only available if4506** the [SQLITE_ENABLE_NORMALIZE] compile-time option is defined.4507*/4508SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);4509SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt);4510#ifdef SQLITE_ENABLE_NORMALIZE4511SQLITE_API const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt);4512#endif45134514/*4515** CAPI3REF: Determine If An SQL Statement Writes The Database4516** METHOD: sqlite3_stmt4517**4518** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if4519** and only if the [prepared statement] X makes no direct changes to4520** the content of the database file.4521**4522** Note that [application-defined SQL functions] or4523** [virtual tables] might change the database indirectly as a side effect.4524** ^(For example, if an application defines a function "eval()" that4525** calls [sqlite3_exec()], then the following SQL statement would4526** change the database file through side-effects:4527**4528** <blockquote><pre>4529**    SELECT eval('DELETE FROM t1') FROM t2;4530** </pre></blockquote>4531**4532** But because the [SELECT] statement does not change the database file4533** directly, sqlite3_stmt_readonly() would still return true.)^4534**4535** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],4536** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,4537** since the statements themselves do not actually modify the database but4538** rather they control the timing of when other statements modify the4539** database.  ^The [ATTACH] and [DETACH] statements also cause4540** sqlite3_stmt_readonly() to return true since, while those statements4541** change the configuration of a database connection, they do not make4542** changes to the content of the database files on disk.4543** ^The sqlite3_stmt_readonly() interface returns true for [BEGIN] since4544** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and4545** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so4546** sqlite3_stmt_readonly() returns false for those commands.4547**4548** ^This routine returns false if there is any possibility that the4549** statement might change the database file.  ^A false return does4550** not guarantee that the statement will change the database file.4551** ^For example, an UPDATE statement might have a WHERE clause that4552** makes it a no-op, but the sqlite3_stmt_readonly() result would still4553** be false.  ^Similarly, a CREATE TABLE IF NOT EXISTS statement is a4554** read-only no-op if the table already exists, but4555** sqlite3_stmt_readonly() still returns false for such a statement.4556**4557** ^If prepared statement X is an [EXPLAIN] or [EXPLAIN QUERY PLAN]4558** statement, then sqlite3_stmt_readonly(X) returns the same value as4559** if the EXPLAIN or EXPLAIN QUERY PLAN prefix were omitted.4560*/4561SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);45624563/*4564** CAPI3REF: Query The EXPLAIN Setting For A Prepared Statement4565** METHOD: sqlite3_stmt4566**4567** ^The sqlite3_stmt_isexplain(S) interface returns 1 if the4568** prepared statement S is an EXPLAIN statement, or 2 if the4569** statement S is an EXPLAIN QUERY PLAN.4570** ^The sqlite3_stmt_isexplain(S) interface returns 0 if S is4571** an ordinary statement or a NULL pointer.4572*/4573SQLITE_API int sqlite3_stmt_isexplain(sqlite3_stmt *pStmt);45744575/*4576** CAPI3REF: Change The EXPLAIN Setting For A Prepared Statement4577** METHOD: sqlite3_stmt4578**4579** The sqlite3_stmt_explain(S,E) interface changes the EXPLAIN4580** setting for [prepared statement] S.  If E is zero, then S becomes4581** a normal prepared statement.  If E is 1, then S behaves as if4582** its SQL text began with "[EXPLAIN]".  If E is 2, then S behaves as if4583** its SQL text began with "[EXPLAIN QUERY PLAN]".4584**4585** Calling sqlite3_stmt_explain(S,E) might cause S to be reprepared.4586** SQLite tries to avoid a reprepare, but a reprepare might be necessary4587** on the first transition into EXPLAIN or EXPLAIN QUERY PLAN mode.4588**4589** Because of the potential need to reprepare, a call to4590** sqlite3_stmt_explain(S,E) will fail with SQLITE_ERROR if S cannot be4591** reprepared because it was created using [sqlite3_prepare()] instead of4592** the newer [sqlite3_prepare_v2()] or [sqlite3_prepare_v3()] interfaces and4593** hence has no saved SQL text with which to reprepare.4594**4595** Changing the explain setting for a prepared statement does not change4596** the original SQL text for the statement.  Hence, if the SQL text originally4597** began with EXPLAIN or EXPLAIN QUERY PLAN, but sqlite3_stmt_explain(S,0)4598** is called to convert the statement into an ordinary statement, the EXPLAIN4599** or EXPLAIN QUERY PLAN keywords will still appear in the sqlite3_sql(S)4600** output, even though the statement now acts like a normal SQL statement.4601**4602** This routine returns SQLITE_OK if the explain mode is successfully4603** changed, or an error code if the explain mode could not be changed.4604** The explain mode cannot be changed while a statement is active.4605** Hence, it is good practice to call [sqlite3_reset(S)]4606** immediately prior to calling sqlite3_stmt_explain(S,E).4607*/4608SQLITE_API int sqlite3_stmt_explain(sqlite3_stmt *pStmt, int eMode);46094610/*4611** CAPI3REF: Determine If A Prepared Statement Has Been Reset4612** METHOD: sqlite3_stmt4613**4614** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the4615** [prepared statement] S has been stepped at least once using4616** [sqlite3_step(S)] but has neither run to completion (returned4617** [SQLITE_DONE] from [sqlite3_step(S)]) nor4618** been reset using [sqlite3_reset(S)].  ^The sqlite3_stmt_busy(S)4619** interface returns false if S is a NULL pointer.  If S is not a4620** NULL pointer and is not a pointer to a valid [prepared statement]4621** object, then the behavior is undefined and probably undesirable.4622**4623** This interface can be used in combination [sqlite3_next_stmt()]4624** to locate all prepared statements associated with a database4625** connection that are in need of being reset.  This can be used,4626** for example, in diagnostic routines to search for prepared4627** statements that are holding a transaction open.4628*/4629SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);46304631/*4632** CAPI3REF: Dynamically Typed Value Object4633** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}4634**4635** SQLite uses the sqlite3_value object to represent all values4636** that can be stored in a database table. SQLite uses dynamic typing4637** for the values it stores.  ^Values stored in sqlite3_value objects4638** can be integers, floating point values, strings, BLOBs, or NULL.4639**4640** An sqlite3_value object may be either "protected" or "unprotected".4641** Some interfaces require a protected sqlite3_value.  Other interfaces4642** will accept either a protected or an unprotected sqlite3_value.4643** Every interface that accepts sqlite3_value arguments specifies4644** whether or not it requires a protected sqlite3_value.  The4645** [sqlite3_value_dup()] interface can be used to construct a new4646** protected sqlite3_value from an unprotected sqlite3_value.4647**4648** The terms "protected" and "unprotected" refer to whether or not4649** a mutex is held.  An internal mutex is held for a protected4650** sqlite3_value object but no mutex is held for an unprotected4651** sqlite3_value object.  If SQLite is compiled to be single-threaded4652** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)4653** or if SQLite is run in one of reduced mutex modes4654** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]4655** then there is no distinction between protected and unprotected4656** sqlite3_value objects and they can be used interchangeably.  However,4657** for maximum code portability it is recommended that applications4658** still make the distinction between protected and unprotected4659** sqlite3_value objects even when not strictly required.4660**4661** ^The sqlite3_value objects that are passed as parameters into the4662** implementation of [application-defined SQL functions] are protected.4663** ^The sqlite3_value objects returned by [sqlite3_vtab_rhs_value()]4664** are protected.4665** ^The sqlite3_value object returned by4666** [sqlite3_column_value()] is unprotected.4667** Unprotected sqlite3_value objects may only be used as arguments4668** to [sqlite3_result_value()], [sqlite3_bind_value()], and4669** [sqlite3_value_dup()].4670** The [sqlite3_value_blob | sqlite3_value_type()] family of4671** interfaces require protected sqlite3_value objects.4672*/4673typedef struct sqlite3_value sqlite3_value;46744675/*4676** CAPI3REF: SQL Function Context Object4677**4678** The context in which an SQL function executes is stored in an4679** sqlite3_context object.  ^A pointer to an sqlite3_context object4680** is always first parameter to [application-defined SQL functions].4681** The application-defined SQL function implementation will pass this4682** pointer through into calls to [sqlite3_result_int | sqlite3_result()],4683** [sqlite3_aggregate_context()], [sqlite3_user_data()],4684** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],4685** and/or [sqlite3_set_auxdata()].4686*/4687typedef struct sqlite3_context sqlite3_context;46884689/*4690** CAPI3REF: Binding Values To Prepared Statements4691** KEYWORDS: {host parameter} {host parameters} {host parameter name}4692** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}4693** METHOD: sqlite3_stmt4694**4695** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,4696** literals may be replaced by a [parameter] that matches one of following4697** templates:4698**4699** <ul>4700** <li>  ?4701** <li>  ?NNN4702** <li>  :VVV4703** <li>  @VVV4704** <li>  $VVV4705** </ul>4706**4707** In the templates above, NNN represents an integer literal,4708** and VVV represents an alphanumeric identifier.)^  ^The values of these4709** parameters (also called "host parameter names" or "SQL parameters")4710** can be set using the sqlite3_bind_*() routines defined here.4711**4712** ^The first argument to the sqlite3_bind_*() routines is always4713** a pointer to the [sqlite3_stmt] object returned from4714** [sqlite3_prepare_v2()] or its variants.4715**4716** ^The second argument is the index of the SQL parameter to be set.4717** ^The leftmost SQL parameter has an index of 1.  ^When the same named4718** SQL parameter is used more than once, second and subsequent4719** occurrences have the same index as the first occurrence.4720** ^The index for named parameters can be looked up using the4721** [sqlite3_bind_parameter_index()] API if desired.  ^The index4722** for "?NNN" parameters is the value of NNN.4723** ^The NNN value must be between 1 and the [sqlite3_limit()]4724** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 32766).4725**4726** ^The third argument is the value to bind to the parameter.4727** ^If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()4728** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter4729** is ignored and the end result is the same as sqlite3_bind_null().4730** ^If the third parameter to sqlite3_bind_text() is not NULL, then4731** it should be a pointer to well-formed UTF8 text.4732** ^If the third parameter to sqlite3_bind_text16() is not NULL, then4733** it should be a pointer to well-formed UTF16 text.4734** ^If the third parameter to sqlite3_bind_text64() is not NULL, then4735** it should be a pointer to a well-formed unicode string that is4736** either UTF8 if the sixth parameter is SQLITE_UTF8, or UTF164737** otherwise.4738**4739** [[byte-order determination rules]] ^The byte-order of4740** UTF16 input text is determined by the byte-order mark (BOM, U+FEFF)4741** found in first character, which is removed, or in the absence of a BOM4742** the byte order is the native byte order of the host4743** machine for sqlite3_bind_text16() or the byte order specified in4744** the 6th parameter for sqlite3_bind_text64().)^4745** ^If UTF16 input text contains invalid unicode4746** characters, then SQLite might change those invalid characters4747** into the unicode replacement character: U+FFFD.4748**4749** ^(In those routines that have a fourth argument, its value is the4750** number of bytes in the parameter.  To be clear: the value is the4751** number of <u>bytes</u> in the value, not the number of characters.)^4752** ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()4753** is negative, then the length of the string is4754** the number of bytes up to the first zero terminator.4755** If the fourth parameter to sqlite3_bind_blob() is negative, then4756** the behavior is undefined.4757** If a non-negative fourth parameter is provided to sqlite3_bind_text()4758** or sqlite3_bind_text16() or sqlite3_bind_text64() then4759** that parameter must be the byte offset4760** where the NUL terminator would occur assuming the string were NUL4761** terminated.  If any NUL characters occurs at byte offsets less than4762** the value of the fourth parameter then the resulting string value will4763** contain embedded NULs.  The result of expressions involving strings4764** with embedded NULs is undefined.4765**4766** ^The fifth argument to the BLOB and string binding interfaces controls4767** or indicates the lifetime of the object referenced by the third parameter.4768** These three options exist:4769** ^ (1) A destructor to dispose of the BLOB or string after SQLite has finished4770** with it may be passed. ^It is called to dispose of the BLOB or string even4771** if the call to the bind API fails, except the destructor is not called if4772** the third parameter is a NULL pointer or the fourth parameter is negative.4773** ^ (2) The special constant, [SQLITE_STATIC], may be passed to indicate that4774** the application remains responsible for disposing of the object. ^In this4775** case, the object and the provided pointer to it must remain valid until4776** either the prepared statement is finalized or the same SQL parameter is4777** bound to something else, whichever occurs sooner.4778** ^ (3) The constant, [SQLITE_TRANSIENT], may be passed to indicate that the4779** object is to be copied prior to the return from sqlite3_bind_*(). ^The4780** object and pointer to it must remain valid until then. ^SQLite will then4781** manage the lifetime of its private copy.4782**4783** ^The sixth argument to sqlite3_bind_text64() must be one of4784** [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE]4785** to specify the encoding of the text in the third parameter.  If4786** the sixth argument to sqlite3_bind_text64() is not one of the4787** allowed values shown above, or if the text encoding is different4788** from the encoding specified by the sixth parameter, then the behavior4789** is undefined.4790**4791** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that4792** is filled with zeroes.  ^A zeroblob uses a fixed amount of memory4793** (just an integer to hold its size) while it is being processed.4794** Zeroblobs are intended to serve as placeholders for BLOBs whose4795** content is later written using4796** [sqlite3_blob_open | incremental BLOB I/O] routines.4797** ^A negative value for the zeroblob results in a zero-length BLOB.4798**4799** ^The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in4800** [prepared statement] S to have an SQL value of NULL, but to also be4801** associated with the pointer P of type T.  ^D is either a NULL pointer or4802** a pointer to a destructor function for P. ^SQLite will invoke the4803** destructor D with a single argument of P when it is finished using4804** P.  The T parameter should be a static string, preferably a string4805** literal. The sqlite3_bind_pointer() routine is part of the4806** [pointer passing interface] added for SQLite 3.20.0.4807**4808** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer4809** for the [prepared statement] or with a prepared statement for which4810** [sqlite3_step()] has been called more recently than [sqlite3_reset()],4811** then the call will return [SQLITE_MISUSE].  If any sqlite3_bind_()4812** routine is passed a [prepared statement] that has been finalized, the4813** result is undefined and probably harmful.4814**4815** ^Bindings are not cleared by the [sqlite3_reset()] routine.4816** ^Unbound parameters are interpreted as NULL.4817**4818** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an4819** [error code] if anything goes wrong.4820** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB4821** exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or4822** [SQLITE_MAX_LENGTH].4823** ^[SQLITE_RANGE] is returned if the parameter4824** index is out of range.  ^[SQLITE_NOMEM] is returned if malloc() fails.4825**4826** See also: [sqlite3_bind_parameter_count()],4827** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].4828*/4829SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));4830SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,4831                        void(*)(void*));4832SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);4833SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);4834SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);4835SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);4836SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));4837SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));4838SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,4839                         void(*)(void*), unsigned char encoding);4840SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);4841SQLITE_API int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*));4842SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);4843SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);48444845/*4846** CAPI3REF: Number Of SQL Parameters4847** METHOD: sqlite3_stmt4848**4849** ^This routine can be used to find the number of [SQL parameters]4850** in a [prepared statement].  SQL parameters are tokens of the4851** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as4852** placeholders for values that are [sqlite3_bind_blob | bound]4853** to the parameters at a later time.4854**4855** ^(This routine actually returns the index of the largest (rightmost)4856** parameter. For all forms except ?NNN, this will correspond to the4857** number of unique parameters.  If parameters of the ?NNN form are used,4858** there may be gaps in the list.)^4859**4860** See also: [sqlite3_bind_blob|sqlite3_bind()],4861** [sqlite3_bind_parameter_name()], and4862** [sqlite3_bind_parameter_index()].4863*/4864SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);48654866/*4867** CAPI3REF: Name Of A Host Parameter4868** METHOD: sqlite3_stmt4869**4870** ^The sqlite3_bind_parameter_name(P,N) interface returns4871** the name of the N-th [SQL parameter] in the [prepared statement] P.4872** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"4873** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"4874** respectively.4875** In other words, the initial ":" or "$" or "@" or "?"4876** is included as part of the name.)^4877** ^Parameters of the form "?" without a following integer have no name4878** and are referred to as "nameless" or "anonymous parameters".4879**4880** ^The first host parameter has an index of 1, not 0.4881**4882** ^If the value N is out of range or if the N-th parameter is4883** nameless, then NULL is returned.  ^The returned string is4884** always in UTF-8 encoding even if the named parameter was4885** originally specified as UTF-16 in [sqlite3_prepare16()],4886** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].4887**4888** See also: [sqlite3_bind_blob|sqlite3_bind()],4889** [sqlite3_bind_parameter_count()], and4890** [sqlite3_bind_parameter_index()].4891*/4892SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);48934894/*4895** CAPI3REF: Index Of A Parameter With A Given Name4896** METHOD: sqlite3_stmt4897**4898** ^Return the index of an SQL parameter given its name.  ^The4899** index value returned is suitable for use as the second4900** parameter to [sqlite3_bind_blob|sqlite3_bind()].  ^A zero4901** is returned if no matching parameter is found.  ^The parameter4902** name must be given in UTF-8 even if the original statement4903** was prepared from UTF-16 text using [sqlite3_prepare16_v2()] or4904** [sqlite3_prepare16_v3()].4905**4906** See also: [sqlite3_bind_blob|sqlite3_bind()],4907** [sqlite3_bind_parameter_count()], and4908** [sqlite3_bind_parameter_name()].4909*/4910SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);49114912/*4913** CAPI3REF: Reset All Bindings On A Prepared Statement4914** METHOD: sqlite3_stmt4915**4916** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset4917** the [sqlite3_bind_blob | bindings] on a [prepared statement].4918** ^Use this routine to reset all host parameters to NULL.4919*/4920SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);49214922/*4923** CAPI3REF: Number Of Columns In A Result Set4924** METHOD: sqlite3_stmt4925**4926** ^Return the number of columns in the result set returned by the4927** [prepared statement]. ^If this routine returns 0, that means the4928** [prepared statement] returns no data (for example an [UPDATE]).4929** ^However, just because this routine returns a positive number does not4930** mean that one or more rows of data will be returned.  ^A SELECT statement4931** will always have a positive sqlite3_column_count() but depending on the4932** WHERE clause constraints and the table content, it might return no rows.4933**4934** See also: [sqlite3_data_count()]4935*/4936SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);49374938/*4939** CAPI3REF: Column Names In A Result Set4940** METHOD: sqlite3_stmt4941**4942** ^These routines return the name assigned to a particular column4943** in the result set of a [SELECT] statement.  ^The sqlite3_column_name()4944** interface returns a pointer to a zero-terminated UTF-8 string4945** and sqlite3_column_name16() returns a pointer to a zero-terminated4946** UTF-16 string.  ^The first parameter is the [prepared statement]4947** that implements the [SELECT] statement. ^The second parameter is the4948** column number.  ^The leftmost column is number 0.4949**4950** ^The returned string pointer is valid until either the [prepared statement]4951** is destroyed by [sqlite3_finalize()] or until the statement is automatically4952** reprepared by the first call to [sqlite3_step()] for a particular run4953** or until the next call to4954** sqlite3_column_name() or sqlite3_column_name16() on the same column.4955**4956** ^If sqlite3_malloc() fails during the processing of either routine4957** (for example during a conversion from UTF-8 to UTF-16) then a4958** NULL pointer is returned.4959**4960** ^The name of a result column is the value of the "AS" clause for4961** that column, if there is an AS clause.  If there is no AS clause4962** then the name of the column is unspecified and may change from4963** one release of SQLite to the next.4964*/4965SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);4966SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);49674968/*4969** CAPI3REF: Source Of Data In A Query Result4970** METHOD: sqlite3_stmt4971**4972** ^These routines provide a means to determine the database, table, and4973** table column that is the origin of a particular result column in4974** [SELECT] statement.4975** ^The name of the database or table or column can be returned as4976** either a UTF-8 or UTF-16 string.  ^The _database_ routines return4977** the database name, the _table_ routines return the table name, and4978** the origin_ routines return the column name.4979** ^The returned string is valid until the [prepared statement] is destroyed4980** using [sqlite3_finalize()] or until the statement is automatically4981** reprepared by the first call to [sqlite3_step()] for a particular run4982** or until the same information is requested4983** again in a different encoding.4984**4985** ^The names returned are the original un-aliased names of the4986** database, table, and column.4987**4988** ^The first argument to these interfaces is a [prepared statement].4989** ^These functions return information about the Nth result column returned by4990** the statement, where N is the second function argument.4991** ^The left-most column is column 0 for these routines.4992**4993** ^If the Nth column returned by the statement is an expression or4994** subquery and is not a column value, then all of these functions return4995** NULL.  ^These routines might also return NULL if a memory allocation error4996** occurs.  ^Otherwise, they return the name of the attached database, table,4997** or column that query result column was extracted from.4998**4999** ^As with all other SQLite APIs, those whose names end with "16" return5000** UTF-16 encoded strings and the other functions return UTF-8.5001**5002** ^These APIs are only available if the library was compiled with the5003** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.5004**5005** If two or more threads call one or more5006** [sqlite3_column_database_name | column metadata interfaces]5007** for the same [prepared statement] and result column5008** at the same time then the results are undefined.5009*/5010SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);5011SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);5012SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);5013SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);5014SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);5015SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);50165017/*5018** CAPI3REF: Declared Datatype Of A Query Result5019** METHOD: sqlite3_stmt5020**5021** ^(The first parameter is a [prepared statement].5022** If this statement is a [SELECT] statement and the Nth column of the5023** returned result set of that [SELECT] is a table column (not an5024** expression or subquery) then the declared type of the table5025** column is returned.)^  ^If the Nth column of the result set is an5026** expression or subquery, then a NULL pointer is returned.5027** ^The returned string is always UTF-8 encoded.5028**5029** ^(For example, given the database schema:5030**5031** CREATE TABLE t1(c1 VARIANT);5032**5033** and the following statement to be compiled:5034**5035** SELECT c1 + 1, c1 FROM t1;5036**5037** this routine would return the string "VARIANT" for the second result5038** column (i==1), and a NULL pointer for the first result column (i==0).)^5039**5040** ^SQLite uses dynamic run-time typing.  ^So just because a column5041** is declared to contain a particular type does not mean that the5042** data stored in that column is of the declared type.  SQLite is5043** strongly typed, but the typing is dynamic not static.  ^Type5044** is associated with individual values, not with the containers5045** used to hold those values.5046*/5047SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);5048SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);50495050/*5051** CAPI3REF: Evaluate An SQL Statement5052** METHOD: sqlite3_stmt5053**5054** After a [prepared statement] has been prepared using any of5055** [sqlite3_prepare_v2()], [sqlite3_prepare_v3()], [sqlite3_prepare16_v2()],5056** or [sqlite3_prepare16_v3()] or one of the legacy5057** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function5058** must be called one or more times to evaluate the statement.5059**5060** The details of the behavior of the sqlite3_step() interface depend5061** on whether the statement was prepared using the newer "vX" interfaces5062** [sqlite3_prepare_v3()], [sqlite3_prepare_v2()], [sqlite3_prepare16_v3()],5063** [sqlite3_prepare16_v2()] or the older legacy5064** interfaces [sqlite3_prepare()] and [sqlite3_prepare16()].  The use of the5065** new "vX" interface is recommended for new applications but the legacy5066** interface will continue to be supported.5067**5068** ^In the legacy interface, the return value will be either [SQLITE_BUSY],5069** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].5070** ^With the "v2" interface, any of the other [result codes] or5071** [extended result codes] might be returned as well.5072**5073** ^[SQLITE_BUSY] means that the database engine was unable to acquire the5074** database locks it needs to do its job.  ^If the statement is a [COMMIT]5075** or occurs outside of an explicit transaction, then you can retry the5076** statement.  If the statement is not a [COMMIT] and occurs within an5077** explicit transaction then you should rollback the transaction before5078** continuing.5079**5080** ^[SQLITE_DONE] means that the statement has finished executing5081** successfully.  sqlite3_step() should not be called again on this virtual5082** machine without first calling [sqlite3_reset()] to reset the virtual5083** machine back to its initial state.5084**5085** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]5086** is returned each time a new row of data is ready for processing by the5087** caller. The values may be accessed using the [column access functions].5088** sqlite3_step() is called again to retrieve the next row of data.5089**5090** ^[SQLITE_ERROR] means that a run-time error (such as a constraint5091** violation) has occurred.  sqlite3_step() should not be called again on5092** the VM. More information may be found by calling [sqlite3_errmsg()].5093** ^With the legacy interface, a more specific error code (for example,5094** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)5095** can be obtained by calling [sqlite3_reset()] on the5096** [prepared statement].  ^In the "v2" interface,5097** the more specific error code is returned directly by sqlite3_step().5098**5099** [SQLITE_MISUSE] means that the this routine was called inappropriately.5100** Perhaps it was called on a [prepared statement] that has5101** already been [sqlite3_finalize | finalized] or on one that had5102** previously returned [SQLITE_ERROR] or [SQLITE_DONE].  Or it could5103** be the case that the same database connection is being used by two or5104** more threads at the same moment in time.5105**5106** For all versions of SQLite up to and including 3.6.23.1, a call to5107** [sqlite3_reset()] was required after sqlite3_step() returned anything5108** other than [SQLITE_ROW] before any subsequent invocation of5109** sqlite3_step().  Failure to reset the prepared statement using5110** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from5111** sqlite3_step().  But after [version 3.6.23.1] ([dateof:3.6.23.1],5112** sqlite3_step() began5113** calling [sqlite3_reset()] automatically in this circumstance rather5114** than returning [SQLITE_MISUSE].  This is not considered a compatibility5115** break because any application that ever receives an SQLITE_MISUSE error5116** is broken by definition.  The [SQLITE_OMIT_AUTORESET] compile-time option5117** can be used to restore the legacy behavior.5118**5119** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()5120** API always returns a generic error code, [SQLITE_ERROR], following any5121** error other than [SQLITE_BUSY] and [SQLITE_MISUSE].  You must call5122** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the5123** specific [error codes] that better describes the error.5124** We admit that this is a goofy design.  The problem has been fixed5125** with the "v2" interface.  If you prepare all of your SQL statements5126** using [sqlite3_prepare_v3()] or [sqlite3_prepare_v2()]5127** or [sqlite3_prepare16_v2()] or [sqlite3_prepare16_v3()] instead5128** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,5129** then the more specific [error codes] are returned directly5130** by sqlite3_step().  The use of the "vX" interfaces is recommended.5131*/5132SQLITE_API int sqlite3_step(sqlite3_stmt*);51335134/*5135** CAPI3REF: Number of columns in a result set5136** METHOD: sqlite3_stmt5137**5138** ^The sqlite3_data_count(P) interface returns the number of columns in the5139** current row of the result set of [prepared statement] P.5140** ^If prepared statement P does not have results ready to return5141** (via calls to the [sqlite3_column_int | sqlite3_column()] family of5142** interfaces) then sqlite3_data_count(P) returns 0.5143** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.5144** ^The sqlite3_data_count(P) routine returns 0 if the previous call to5145** [sqlite3_step](P) returned [SQLITE_DONE].  ^The sqlite3_data_count(P)5146** will return non-zero if previous call to [sqlite3_step](P) returned5147** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum]5148** where it always returns zero since each step of that multi-step5149** pragma returns 0 columns of data.5150**5151** See also: [sqlite3_column_count()]5152*/5153SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);51545155/*5156** CAPI3REF: Fundamental Datatypes5157** KEYWORDS: SQLITE_TEXT5158**5159** ^(Every value in SQLite has one of five fundamental datatypes:5160**5161** <ul>5162** <li> 64-bit signed integer5163** <li> 64-bit IEEE floating point number5164** <li> string5165** <li> BLOB5166** <li> NULL5167** </ul>)^5168**5169** These constants are codes for each of those types.5170**5171** Note that the SQLITE_TEXT constant was also used in SQLite version 25172** for a completely different meaning.  Software that links against both5173** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not5174** SQLITE_TEXT.5175*/5176#define SQLITE_INTEGER  15177#define SQLITE_FLOAT    25178#define SQLITE_BLOB     45179#define SQLITE_NULL     55180#ifdef SQLITE_TEXT5181# undef SQLITE_TEXT5182#else5183# define SQLITE_TEXT     35184#endif5185#define SQLITE3_TEXT     351865187/*5188** CAPI3REF: Result Values From A Query5189** KEYWORDS: {column access functions}5190** METHOD: sqlite3_stmt5191**5192** <b>Summary:</b>5193** <blockquote><table border=0 cellpadding=0 cellspacing=0>5194** <tr><td><b>sqlite3_column_blob</b><td>&rarr;<td>BLOB result5195** <tr><td><b>sqlite3_column_double</b><td>&rarr;<td>REAL result5196** <tr><td><b>sqlite3_column_int</b><td>&rarr;<td>32-bit INTEGER result5197** <tr><td><b>sqlite3_column_int64</b><td>&rarr;<td>64-bit INTEGER result5198** <tr><td><b>sqlite3_column_text</b><td>&rarr;<td>UTF-8 TEXT result5199** <tr><td><b>sqlite3_column_text16</b><td>&rarr;<td>UTF-16 TEXT result5200** <tr><td><b>sqlite3_column_value</b><td>&rarr;<td>The result as an5201** [sqlite3_value|unprotected sqlite3_value] object.5202** <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;5203** <tr><td><b>sqlite3_column_bytes</b><td>&rarr;<td>Size of a BLOB5204** or a UTF-8 TEXT result in bytes5205** <tr><td><b>sqlite3_column_bytes16&nbsp;&nbsp;</b>5206** <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-165207** TEXT in bytes5208** <tr><td><b>sqlite3_column_type</b><td>&rarr;<td>Default5209** datatype of the result5210** </table></blockquote>5211**5212** <b>Details:</b>5213**5214** ^These routines return information about a single column of the current5215** result row of a query.  ^In every case the first argument is a pointer5216** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]5217** that was returned from [sqlite3_prepare_v2()] or one of its variants)5218** and the second argument is the index of the column for which information5219** should be returned. ^The leftmost column of the result set has the index 0.5220** ^The number of columns in the result can be determined using5221** [sqlite3_column_count()].5222**5223** If the SQL statement does not currently point to a valid row, or if the5224** column index is out of range, the result is undefined.5225** These routines may only be called when the most recent call to5226** [sqlite3_step()] has returned [SQLITE_ROW] and neither5227** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.5228** If any of these routines are called after [sqlite3_reset()] or5229** [sqlite3_finalize()] or after [sqlite3_step()] has returned5230** something other than [SQLITE_ROW], the results are undefined.5231** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]5232** are called from a different thread while any of these routines5233** are pending, then the results are undefined.5234**5235** The first six interfaces (_blob, _double, _int, _int64, _text, and _text16)5236** each return the value of a result column in a specific data format.  If5237** the result column is not initially in the requested format (for example,5238** if the query returns an integer but the sqlite3_column_text() interface5239** is used to extract the value) then an automatic type conversion is performed.5240**5241** ^The sqlite3_column_type() routine returns the5242** [SQLITE_INTEGER | datatype code] for the initial data type5243** of the result column.  ^The returned value is one of [SQLITE_INTEGER],5244** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].5245** The return value of sqlite3_column_type() can be used to decide which5246** of the first six interface should be used to extract the column value.5247** The value returned by sqlite3_column_type() is only meaningful if no5248** automatic type conversions have occurred for the value in question.5249** After a type conversion, the result of calling sqlite3_column_type()5250** is undefined, though harmless.  Future5251** versions of SQLite may change the behavior of sqlite3_column_type()5252** following a type conversion.5253**5254** If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()5255** or sqlite3_column_bytes16() interfaces can be used to determine the size5256** of that BLOB or string.5257**5258** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()5259** routine returns the number of bytes in that BLOB or string.5260** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts5261** the string to UTF-8 and then returns the number of bytes.5262** ^If the result is a numeric value then sqlite3_column_bytes() uses5263** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns5264** the number of bytes in that string.5265** ^If the result is NULL, then sqlite3_column_bytes() returns zero.5266**5267** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()5268** routine returns the number of bytes in that BLOB or string.5269** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts5270** the string to UTF-16 and then returns the number of bytes.5271** ^If the result is a numeric value then sqlite3_column_bytes16() uses5272** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns5273** the number of bytes in that string.5274** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.5275**5276** ^The values returned by [sqlite3_column_bytes()] and5277** [sqlite3_column_bytes16()] do not include the zero terminators at the end5278** of the string.  ^For clarity: the values returned by5279** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of5280** bytes in the string, not the number of characters.5281**5282** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),5283** even empty strings, are always zero-terminated.  ^The return5284** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.5285**5286** ^Strings returned by sqlite3_column_text16() always have the endianness5287** which is native to the platform, regardless of the text encoding set5288** for the database.5289**5290** <b>Warning:</b> ^The object returned by [sqlite3_column_value()] is an5291** [unprotected sqlite3_value] object.  In a multithreaded environment,5292** an unprotected sqlite3_value object may only be used safely with5293** [sqlite3_bind_value()] and [sqlite3_result_value()].5294** If the [unprotected sqlite3_value] object returned by5295** [sqlite3_column_value()] is used in any other way, including calls5296** to routines like [sqlite3_value_int()], [sqlite3_value_text()],5297** or [sqlite3_value_bytes()], the behavior is not threadsafe.5298** Hence, the sqlite3_column_value() interface5299** is normally only useful within the implementation of5300** [application-defined SQL functions] or [virtual tables], not within5301** top-level application code.5302**5303** These routines may attempt to convert the datatype of the result.5304** ^For example, if the internal representation is FLOAT and a text result5305** is requested, [sqlite3_snprintf()] is used internally to perform the5306** conversion automatically.  ^(The following table details the conversions5307** that are applied:5308**5309** <blockquote>5310** <table border="1">5311** <tr><th> Internal<br>Type <th> Requested<br>Type <th>  Conversion5312**5313** <tr><td>  NULL    <td> INTEGER   <td> Result is 05314** <tr><td>  NULL    <td>  FLOAT    <td> Result is 0.05315** <tr><td>  NULL    <td>   TEXT    <td> Result is a NULL pointer5316** <tr><td>  NULL    <td>   BLOB    <td> Result is a NULL pointer5317** <tr><td> INTEGER  <td>  FLOAT    <td> Convert from integer to float5318** <tr><td> INTEGER  <td>   TEXT    <td> ASCII rendering of the integer5319** <tr><td> INTEGER  <td>   BLOB    <td> Same as INTEGER->TEXT5320** <tr><td>  FLOAT   <td> INTEGER   <td> [CAST] to INTEGER5321** <tr><td>  FLOAT   <td>   TEXT    <td> ASCII rendering of the float5322** <tr><td>  FLOAT   <td>   BLOB    <td> [CAST] to BLOB5323** <tr><td>  TEXT    <td> INTEGER   <td> [CAST] to INTEGER5324** <tr><td>  TEXT    <td>  FLOAT    <td> [CAST] to REAL5325** <tr><td>  TEXT    <td>   BLOB    <td> No change5326** <tr><td>  BLOB    <td> INTEGER   <td> [CAST] to INTEGER5327** <tr><td>  BLOB    <td>  FLOAT    <td> [CAST] to REAL5328** <tr><td>  BLOB    <td>   TEXT    <td> [CAST] to TEXT, ensure zero terminator5329** </table>5330** </blockquote>)^5331**5332** Note that when type conversions occur, pointers returned by prior5333** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or5334** sqlite3_column_text16() may be invalidated.5335** Type conversions and pointer invalidations might occur5336** in the following cases:5337**5338** <ul>5339** <li> The initial content is a BLOB and sqlite3_column_text() or5340**      sqlite3_column_text16() is called.  A zero-terminator might5341**      need to be added to the string.</li>5342** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or5343**      sqlite3_column_text16() is called.  The content must be converted5344**      to UTF-16.</li>5345** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or5346**      sqlite3_column_text() is called.  The content must be converted5347**      to UTF-8.</li>5348** </ul>5349**5350** ^Conversions between UTF-16be and UTF-16le are always done in place and do5351** not invalidate a prior pointer, though of course the content of the buffer5352** that the prior pointer references will have been modified.  Other kinds5353** of conversion are done in place when it is possible, but sometimes they5354** are not possible and in those cases prior pointers are invalidated.5355**5356** The safest policy is to invoke these routines5357** in one of the following ways:5358**5359** <ul>5360**  <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>5361**  <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>5362**  <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>5363** </ul>5364**5365** In other words, you should call sqlite3_column_text(),5366** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result5367** into the desired format, then invoke sqlite3_column_bytes() or5368** sqlite3_column_bytes16() to find the size of the result.  Do not mix calls5369** to sqlite3_column_text() or sqlite3_column_blob() with calls to5370** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()5371** with calls to sqlite3_column_bytes().5372**5373** ^The pointers returned are valid until a type conversion occurs as5374** described above, or until [sqlite3_step()] or [sqlite3_reset()] or5375** [sqlite3_finalize()] is called.  ^The memory space used to hold strings5376** and BLOBs is freed automatically.  Do not pass the pointers returned5377** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into5378** [sqlite3_free()].5379**5380** As long as the input parameters are correct, these routines will only5381** fail if an out-of-memory error occurs during a format conversion.5382** Only the following subset of interfaces are subject to out-of-memory5383** errors:5384**5385** <ul>5386** <li> sqlite3_column_blob()5387** <li> sqlite3_column_text()5388** <li> sqlite3_column_text16()5389** <li> sqlite3_column_bytes()5390** <li> sqlite3_column_bytes16()5391** </ul>5392**5393** If an out-of-memory error occurs, then the return value from these5394** routines is the same as if the column had contained an SQL NULL value.5395** Valid SQL NULL returns can be distinguished from out-of-memory errors5396** by invoking the [sqlite3_errcode()] immediately after the suspect5397** return value is obtained and before any5398** other SQLite interface is called on the same [database connection].5399*/5400SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);5401SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);5402SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);5403SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);5404SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);5405SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);5406SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);5407SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);5408SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);5409SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);54105411/*5412** CAPI3REF: Destroy A Prepared Statement Object5413** DESTRUCTOR: sqlite3_stmt5414**5415** ^The sqlite3_finalize() function is called to delete a [prepared statement].5416** ^If the most recent evaluation of the statement encountered no errors5417** or if the statement is never been evaluated, then sqlite3_finalize() returns5418** SQLITE_OK.  ^If the most recent evaluation of statement S failed, then5419** sqlite3_finalize(S) returns the appropriate [error code] or5420** [extended error code].5421**5422** ^The sqlite3_finalize(S) routine can be called at any point during5423** the life cycle of [prepared statement] S:5424** before statement S is ever evaluated, after5425** one or more calls to [sqlite3_reset()], or after any call5426** to [sqlite3_step()] regardless of whether or not the statement has5427** completed execution.5428**5429** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.5430**5431** The application must finalize every [prepared statement] in order to avoid5432** resource leaks.  It is a grievous error for the application to try to use5433** a prepared statement after it has been finalized.  Any use of a prepared5434** statement after it has been finalized can result in undefined and5435** undesirable behavior such as segfaults and heap corruption.5436*/5437SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);54385439/*5440** CAPI3REF: Reset A Prepared Statement Object5441** METHOD: sqlite3_stmt5442**5443** The sqlite3_reset() function is called to reset a [prepared statement]5444** object back to its initial state, ready to be re-executed.5445** ^Any SQL statement variables that had values bound to them using5446** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.5447** Use [sqlite3_clear_bindings()] to reset the bindings.5448**5449** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S5450** back to the beginning of its program.5451**5452** ^The return code from [sqlite3_reset(S)] indicates whether or not5453** the previous evaluation of prepared statement S completed successfully.5454** ^If [sqlite3_step(S)] has never before been called on S or if5455** [sqlite3_step(S)] has not been called since the previous call5456** to [sqlite3_reset(S)], then [sqlite3_reset(S)] will return5457** [SQLITE_OK].5458**5459** ^If the most recent call to [sqlite3_step(S)] for the5460** [prepared statement] S indicated an error, then5461** [sqlite3_reset(S)] returns an appropriate [error code].5462** ^The [sqlite3_reset(S)] interface might also return an [error code]5463** if there were no prior errors but the process of resetting5464** the prepared statement caused a new error. ^For example, if an5465** [INSERT] statement with a [RETURNING] clause is only stepped one time,5466** that one call to [sqlite3_step(S)] might return SQLITE_ROW but5467** the overall statement might still fail and the [sqlite3_reset(S)] call5468** might return SQLITE_BUSY if locking constraints prevent the5469** database change from committing.  Therefore, it is important that5470** applications check the return code from [sqlite3_reset(S)] even if5471** no prior call to [sqlite3_step(S)] indicated a problem.5472**5473** ^The [sqlite3_reset(S)] interface does not change the values5474** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.5475*/5476SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);547754785479/*5480** CAPI3REF: Create Or Redefine SQL Functions5481** KEYWORDS: {function creation routines}5482** METHOD: sqlite35483**5484** ^These functions (collectively known as "function creation routines")5485** are used to add SQL functions or aggregates or to redefine the behavior5486** of existing SQL functions or aggregates. The only differences between5487** the three "sqlite3_create_function*" routines are the text encoding5488** expected for the second parameter (the name of the function being5489** created) and the presence or absence of a destructor callback for5490** the application data pointer. Function sqlite3_create_window_function()5491** is similar, but allows the user to supply the extra callback functions5492** needed by [aggregate window functions].5493**5494** ^The first parameter is the [database connection] to which the SQL5495** function is to be added.  ^If an application uses more than one database5496** connection then application-defined SQL functions must be added5497** to each database connection separately.5498**5499** ^The second parameter is the name of the SQL function to be created or5500** redefined.  ^The length of the name is limited to 255 bytes in a UTF-85501** representation, exclusive of the zero-terminator.  ^Note that the name5502** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.5503** ^Any attempt to create a function with a longer name5504** will result in [SQLITE_MISUSE] being returned.5505**5506** ^The third parameter (nArg)5507** is the number of arguments that the SQL function or5508** aggregate takes. ^If this parameter is -1, then the SQL function or5509** aggregate may take any number of arguments between 0 and the limit5510** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]).  If the third5511** parameter is less than -1 or greater than 127 then the behavior is5512** undefined.5513**5514** ^The fourth parameter, eTextRep, specifies what5515** [SQLITE_UTF8 | text encoding] this SQL function prefers for5516** its parameters.  The application should set this parameter to5517** [SQLITE_UTF16LE] if the function implementation invokes5518** [sqlite3_value_text16le()] on an input, or [SQLITE_UTF16BE] if the5519** implementation invokes [sqlite3_value_text16be()] on an input, or5520** [SQLITE_UTF16] if [sqlite3_value_text16()] is used, or [SQLITE_UTF8]5521** otherwise.  ^The same SQL function may be registered multiple times using5522** different preferred text encodings, with different implementations for5523** each encoding.5524** ^When multiple implementations of the same function are available, SQLite5525** will pick the one that involves the least amount of data conversion.5526**5527** ^The fourth parameter may optionally be ORed with [SQLITE_DETERMINISTIC]5528** to signal that the function will always return the same result given5529** the same inputs within a single SQL statement.  Most SQL functions are5530** deterministic.  The built-in [random()] SQL function is an example of a5531** function that is not deterministic.  The SQLite query planner is able to5532** perform additional optimizations on deterministic functions, so use5533** of the [SQLITE_DETERMINISTIC] flag is recommended where possible.5534**5535** ^The fourth parameter may also optionally include the [SQLITE_DIRECTONLY]5536** flag, which if present prevents the function from being invoked from5537** within VIEWs, TRIGGERs, CHECK constraints, generated column expressions,5538** index expressions, or the WHERE clause of partial indexes.5539**5540** For best security, the [SQLITE_DIRECTONLY] flag is recommended for5541** all application-defined SQL functions that do not need to be5542** used inside of triggers, view, CHECK constraints, or other elements of5543** the database schema.  This flags is especially recommended for SQL5544** functions that have side effects or reveal internal application state.5545** Without this flag, an attacker might be able to modify the schema of5546** a database file to include invocations of the function with parameters5547** chosen by the attacker, which the application will then execute when5548** the database file is opened and read.5549**5550** ^(The fifth parameter is an arbitrary pointer.  The implementation of the5551** function can gain access to this pointer using [sqlite3_user_data()].)^5552**5553** ^The sixth, seventh and eighth parameters passed to the three5554** "sqlite3_create_function*" functions, xFunc, xStep and xFinal, are5555** pointers to C-language functions that implement the SQL function or5556** aggregate. ^A scalar SQL function requires an implementation of the xFunc5557** callback only; NULL pointers must be passed as the xStep and xFinal5558** parameters. ^An aggregate SQL function requires an implementation of xStep5559** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing5560** SQL function or aggregate, pass NULL pointers for all three function5561** callbacks.5562**5563** ^The sixth, seventh, eighth and ninth parameters (xStep, xFinal, xValue5564** and xInverse) passed to sqlite3_create_window_function are pointers to5565** C-language callbacks that implement the new function. xStep and xFinal5566** must both be non-NULL. xValue and xInverse may either both be NULL, in5567** which case a regular aggregate function is created, or must both be5568** non-NULL, in which case the new function may be used as either an aggregate5569** or aggregate window function. More details regarding the implementation5570** of aggregate window functions are5571** [user-defined window functions|available here].5572**5573** ^(If the final parameter to sqlite3_create_function_v2() or5574** sqlite3_create_window_function() is not NULL, then it is destructor for5575** the application data pointer. The destructor is invoked when the function5576** is deleted, either by being overloaded or when the database connection5577** closes.)^ ^The destructor is also invoked if the call to5578** sqlite3_create_function_v2() fails.  ^When the destructor callback is5579** invoked, it is passed a single argument which is a copy of the application5580** data pointer which was the fifth parameter to sqlite3_create_function_v2().5581**5582** ^It is permitted to register multiple implementations of the same5583** functions with the same name but with either differing numbers of5584** arguments or differing preferred text encodings.  ^SQLite will use5585** the implementation that most closely matches the way in which the5586** SQL function is used.  ^A function implementation with a non-negative5587** nArg parameter is a better match than a function implementation with5588** a negative nArg.  ^A function where the preferred text encoding5589** matches the database encoding is a better5590** match than a function where the encoding is different.5591** ^A function where the encoding difference is between UTF16le and UTF16be5592** is a closer match than a function where the encoding difference is5593** between UTF8 and UTF16.5594**5595** ^Built-in functions may be overloaded by new application-defined functions.5596**5597** ^An application-defined function is permitted to call other5598** SQLite interfaces.  However, such calls must not5599** close the database connection nor finalize or reset the prepared5600** statement in which the function is running.5601*/5602SQLITE_API int sqlite3_create_function(5603  sqlite3 *db,5604  const char *zFunctionName,5605  int nArg,5606  int eTextRep,5607  void *pApp,5608  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),5609  void (*xStep)(sqlite3_context*,int,sqlite3_value**),5610  void (*xFinal)(sqlite3_context*)5611);5612SQLITE_API int sqlite3_create_function16(5613  sqlite3 *db,5614  const void *zFunctionName,5615  int nArg,5616  int eTextRep,5617  void *pApp,5618  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),5619  void (*xStep)(sqlite3_context*,int,sqlite3_value**),5620  void (*xFinal)(sqlite3_context*)5621);5622SQLITE_API int sqlite3_create_function_v2(5623  sqlite3 *db,5624  const char *zFunctionName,5625  int nArg,5626  int eTextRep,5627  void *pApp,5628  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),5629  void (*xStep)(sqlite3_context*,int,sqlite3_value**),5630  void (*xFinal)(sqlite3_context*),5631  void(*xDestroy)(void*)5632);5633SQLITE_API int sqlite3_create_window_function(5634  sqlite3 *db,5635  const char *zFunctionName,5636  int nArg,5637  int eTextRep,5638  void *pApp,5639  void (*xStep)(sqlite3_context*,int,sqlite3_value**),5640  void (*xFinal)(sqlite3_context*),5641  void (*xValue)(sqlite3_context*),5642  void (*xInverse)(sqlite3_context*,int,sqlite3_value**),5643  void(*xDestroy)(void*)5644);56455646/*5647** CAPI3REF: Text Encodings5648**5649** These constant define integer codes that represent the various5650** text encodings supported by SQLite.5651*/5652#define SQLITE_UTF8           1    /* IMP: R-37514-35566 */5653#define SQLITE_UTF16LE        2    /* IMP: R-03371-37637 */5654#define SQLITE_UTF16BE        3    /* IMP: R-51971-34154 */5655#define SQLITE_UTF16          4    /* Use native byte order */5656#define SQLITE_ANY            5    /* Deprecated */5657#define SQLITE_UTF16_ALIGNED  8    /* sqlite3_create_collation only */56585659/*5660** CAPI3REF: Function Flags5661**5662** These constants may be ORed together with the5663** [SQLITE_UTF8 | preferred text encoding] as the fourth argument5664** to [sqlite3_create_function()], [sqlite3_create_function16()], or5665** [sqlite3_create_function_v2()].5666**5667** <dl>5668** [[SQLITE_DETERMINISTIC]] <dt>SQLITE_DETERMINISTIC</dt><dd>5669** The SQLITE_DETERMINISTIC flag means that the new function always gives5670** the same output when the input parameters are the same.5671** The [abs|abs() function] is deterministic, for example, but5672** [randomblob|randomblob()] is not.  Functions must5673** be deterministic in order to be used in certain contexts such as5674** with the WHERE clause of [partial indexes] or in [generated columns].5675** SQLite might also optimize deterministic functions by factoring them5676** out of inner loops.5677** </dd>5678**5679** [[SQLITE_DIRECTONLY]] <dt>SQLITE_DIRECTONLY</dt><dd>5680** The SQLITE_DIRECTONLY flag means that the function may only be invoked5681** from top-level SQL, and cannot be used in VIEWs or TRIGGERs nor in5682** schema structures such as [CHECK constraints], [DEFAULT clauses],5683** [expression indexes], [partial indexes], or [generated columns].5684** <p>5685** The SQLITE_DIRECTONLY flag is recommended for any5686** [application-defined SQL function]5687** that has side-effects or that could potentially leak sensitive information.5688** This will prevent attacks in which an application is tricked5689** into using a database file that has had its schema surreptitiously5690** modified to invoke the application-defined function in ways that are5691** harmful.5692** <p>5693** Some people say it is good practice to set SQLITE_DIRECTONLY on all5694** [application-defined SQL functions], regardless of whether or not they5695** are security sensitive, as doing so prevents those functions from being used5696** inside of the database schema, and thus ensures that the database5697** can be inspected and modified using generic tools (such as the [CLI])5698** that do not have access to the application-defined functions.5699** </dd>5700**5701** [[SQLITE_INNOCUOUS]] <dt>SQLITE_INNOCUOUS</dt><dd>5702** The SQLITE_INNOCUOUS flag means that the function is unlikely5703** to cause problems even if misused.  An innocuous function should have5704** no side effects and should not depend on any values other than its5705** input parameters. The [abs|abs() function] is an example of an5706** innocuous function.5707** The [load_extension() SQL function] is not innocuous because of its5708** side effects.5709** <p> SQLITE_INNOCUOUS is similar to SQLITE_DETERMINISTIC, but is not5710** exactly the same.  The [random|random() function] is an example of a5711** function that is innocuous but not deterministic.5712** <p>Some heightened security settings5713** ([SQLITE_DBCONFIG_TRUSTED_SCHEMA] and [PRAGMA trusted_schema=OFF])5714** disable the use of SQL functions inside views and triggers and in5715** schema structures such as [CHECK constraints], [DEFAULT clauses],5716** [expression indexes], [partial indexes], and [generated columns] unless5717** the function is tagged with SQLITE_INNOCUOUS.  Most built-in functions5718** are innocuous.  Developers are advised to avoid using the5719** SQLITE_INNOCUOUS flag for application-defined functions unless the5720** function has been carefully audited and found to be free of potentially5721** security-adverse side-effects and information-leaks.5722** </dd>5723**5724** [[SQLITE_SUBTYPE]] <dt>SQLITE_SUBTYPE</dt><dd>5725** The SQLITE_SUBTYPE flag indicates to SQLite that a function might call5726** [sqlite3_value_subtype()] to inspect the sub-types of its arguments.5727** This flag instructs SQLite to omit some corner-case optimizations that5728** might disrupt the operation of the [sqlite3_value_subtype()] function,5729** causing it to return zero rather than the correct subtype().5730** All SQL functions that invoke [sqlite3_value_subtype()] should have this5731** property.  If the SQLITE_SUBTYPE property is omitted, then the return5732** value from [sqlite3_value_subtype()] might sometimes be zero even though5733** a non-zero subtype was specified by the function argument expression.5734**5735** [[SQLITE_RESULT_SUBTYPE]] <dt>SQLITE_RESULT_SUBTYPE</dt><dd>5736** The SQLITE_RESULT_SUBTYPE flag indicates to SQLite that a function might call5737** [sqlite3_result_subtype()] to cause a sub-type to be associated with its5738** result.5739** Every function that invokes [sqlite3_result_subtype()] should have this5740** property.  If it does not, then the call to [sqlite3_result_subtype()]5741** might become a no-op if the function is used as term in an5742** [expression index].  On the other hand, SQL functions that never invoke5743** [sqlite3_result_subtype()] should avoid setting this property, as the5744** purpose of this property is to disable certain optimizations that are5745** incompatible with subtypes.5746**5747** [[SQLITE_SELFORDER1]] <dt>SQLITE_SELFORDER1</dt><dd>5748** The SQLITE_SELFORDER1 flag indicates that the function is an aggregate5749** that internally orders the values provided to the first argument.  The5750** ordered-set aggregate SQL notation with a single ORDER BY term can be5751** used to invoke this function.  If the ordered-set aggregate notation is5752** used on a function that lacks this flag, then an error is raised. Note5753** that the ordered-set aggregate syntax is only available if SQLite is5754** built using the -DSQLITE_ENABLE_ORDERED_SET_AGGREGATES compile-time option.5755** </dd>5756** </dl>5757*/5758#define SQLITE_DETERMINISTIC    0x0000008005759#define SQLITE_DIRECTONLY       0x0000800005760#define SQLITE_SUBTYPE          0x0001000005761#define SQLITE_INNOCUOUS        0x0002000005762#define SQLITE_RESULT_SUBTYPE   0x0010000005763#define SQLITE_SELFORDER1       0x00200000057645765/*5766** CAPI3REF: Deprecated Functions5767** DEPRECATED5768**5769** These functions are [deprecated].  In order to maintain5770** backwards compatibility with older code, these functions continue5771** to be supported.  However, new applications should avoid5772** the use of these functions.  To encourage programmers to avoid5773** these functions, we will not explain what they do.5774*/5775#ifndef SQLITE_OMIT_DEPRECATED5776SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);5777SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);5778SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);5779SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);5780SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);5781SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),5782                      void*,sqlite3_int64);5783#endif57845785/*5786** CAPI3REF: Obtaining SQL Values5787** METHOD: sqlite3_value5788**5789** <b>Summary:</b>5790** <blockquote><table border=0 cellpadding=0 cellspacing=0>5791** <tr><td><b>sqlite3_value_blob</b><td>&rarr;<td>BLOB value5792** <tr><td><b>sqlite3_value_double</b><td>&rarr;<td>REAL value5793** <tr><td><b>sqlite3_value_int</b><td>&rarr;<td>32-bit INTEGER value5794** <tr><td><b>sqlite3_value_int64</b><td>&rarr;<td>64-bit INTEGER value5795** <tr><td><b>sqlite3_value_pointer</b><td>&rarr;<td>Pointer value5796** <tr><td><b>sqlite3_value_text</b><td>&rarr;<td>UTF-8 TEXT value5797** <tr><td><b>sqlite3_value_text16</b><td>&rarr;<td>UTF-16 TEXT value in5798** the native byteorder5799** <tr><td><b>sqlite3_value_text16be</b><td>&rarr;<td>UTF-16be TEXT value5800** <tr><td><b>sqlite3_value_text16le</b><td>&rarr;<td>UTF-16le TEXT value5801** <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;5802** <tr><td><b>sqlite3_value_bytes</b><td>&rarr;<td>Size of a BLOB5803** or a UTF-8 TEXT in bytes5804** <tr><td><b>sqlite3_value_bytes16&nbsp;&nbsp;</b>5805** <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-165806** TEXT in bytes5807** <tr><td><b>sqlite3_value_type</b><td>&rarr;<td>Default5808** datatype of the value5809** <tr><td><b>sqlite3_value_numeric_type&nbsp;&nbsp;</b>5810** <td>&rarr;&nbsp;&nbsp;<td>Best numeric datatype of the value5811** <tr><td><b>sqlite3_value_nochange&nbsp;&nbsp;</b>5812** <td>&rarr;&nbsp;&nbsp;<td>True if the column is unchanged in an UPDATE5813** against a virtual table.5814** <tr><td><b>sqlite3_value_frombind&nbsp;&nbsp;</b>5815** <td>&rarr;&nbsp;&nbsp;<td>True if value originated from a [bound parameter]5816** </table></blockquote>5817**5818** <b>Details:</b>5819**5820** These routines extract type, size, and content information from5821** [protected sqlite3_value] objects.  Protected sqlite3_value objects5822** are used to pass parameter information into the functions that5823** implement [application-defined SQL functions] and [virtual tables].5824**5825** These routines work only with [protected sqlite3_value] objects.5826** Any attempt to use these routines on an [unprotected sqlite3_value]5827** is not threadsafe.5828**5829** ^These routines work just like the corresponding [column access functions]5830** except that these routines take a single [protected sqlite3_value] object5831** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.5832**5833** ^The sqlite3_value_text16() interface extracts a UTF-16 string5834** in the native byte-order of the host machine.  ^The5835** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces5836** extract UTF-16 strings as big-endian and little-endian respectively.5837**5838** ^If [sqlite3_value] object V was initialized5839** using [sqlite3_bind_pointer(S,I,P,X,D)] or [sqlite3_result_pointer(C,P,X,D)]5840** and if X and Y are strings that compare equal according to strcmp(X,Y),5841** then sqlite3_value_pointer(V,Y) will return the pointer P.  ^Otherwise,5842** sqlite3_value_pointer(V,Y) returns a NULL. The sqlite3_bind_pointer()5843** routine is part of the [pointer passing interface] added for SQLite 3.20.0.5844**5845** ^(The sqlite3_value_type(V) interface returns the5846** [SQLITE_INTEGER | datatype code] for the initial datatype of the5847** [sqlite3_value] object V. The returned value is one of [SQLITE_INTEGER],5848** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].)^5849** Other interfaces might change the datatype for an sqlite3_value object.5850** For example, if the datatype is initially SQLITE_INTEGER and5851** sqlite3_value_text(V) is called to extract a text value for that5852** integer, then subsequent calls to sqlite3_value_type(V) might return5853** SQLITE_TEXT.  Whether or not a persistent internal datatype conversion5854** occurs is undefined and may change from one release of SQLite to the next.5855**5856** ^(The sqlite3_value_numeric_type() interface attempts to apply5857** numeric affinity to the value.  This means that an attempt is5858** made to convert the value to an integer or floating point.  If5859** such a conversion is possible without loss of information (in other5860** words, if the value is a string that looks like a number)5861** then the conversion is performed.  Otherwise no conversion occurs.5862** The [SQLITE_INTEGER | datatype] after conversion is returned.)^5863**5864** ^Within the [xUpdate] method of a [virtual table], the5865** sqlite3_value_nochange(X) interface returns true if and only if5866** the column corresponding to X is unchanged by the UPDATE operation5867** that the xUpdate method call was invoked to implement and if5868** and the prior [xColumn] method call that was invoked to extracted5869** the value for that column returned without setting a result (probably5870** because it queried [sqlite3_vtab_nochange()] and found that the column5871** was unchanging).  ^Within an [xUpdate] method, any value for which5872** sqlite3_value_nochange(X) is true will in all other respects appear5873** to be a NULL value.  If sqlite3_value_nochange(X) is invoked anywhere other5874** than within an [xUpdate] method call for an UPDATE statement, then5875** the return value is arbitrary and meaningless.5876**5877** ^The sqlite3_value_frombind(X) interface returns non-zero if the5878** value X originated from one of the [sqlite3_bind_int|sqlite3_bind()]5879** interfaces.  ^If X comes from an SQL literal value, or a table column,5880** or an expression, then sqlite3_value_frombind(X) returns zero.5881**5882** Please pay particular attention to the fact that the pointer returned5883** from [sqlite3_value_blob()], [sqlite3_value_text()], or5884** [sqlite3_value_text16()] can be invalidated by a subsequent call to5885** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],5886** or [sqlite3_value_text16()].5887**5888** These routines must be called from the same thread as5889** the SQL function that supplied the [sqlite3_value*] parameters.5890**5891** As long as the input parameter is correct, these routines can only5892** fail if an out-of-memory error occurs during a format conversion.5893** Only the following subset of interfaces are subject to out-of-memory5894** errors:5895**5896** <ul>5897** <li> sqlite3_value_blob()5898** <li> sqlite3_value_text()5899** <li> sqlite3_value_text16()5900** <li> sqlite3_value_text16le()5901** <li> sqlite3_value_text16be()5902** <li> sqlite3_value_bytes()5903** <li> sqlite3_value_bytes16()5904** </ul>5905**5906** If an out-of-memory error occurs, then the return value from these5907** routines is the same as if the column had contained an SQL NULL value.5908** Valid SQL NULL returns can be distinguished from out-of-memory errors5909** by invoking the [sqlite3_errcode()] immediately after the suspect5910** return value is obtained and before any5911** other SQLite interface is called on the same [database connection].5912*/5913SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);5914SQLITE_API double sqlite3_value_double(sqlite3_value*);5915SQLITE_API int sqlite3_value_int(sqlite3_value*);5916SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);5917SQLITE_API void *sqlite3_value_pointer(sqlite3_value*, const char*);5918SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*);5919SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);5920SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);5921SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);5922SQLITE_API int sqlite3_value_bytes(sqlite3_value*);5923SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);5924SQLITE_API int sqlite3_value_type(sqlite3_value*);5925SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);5926SQLITE_API int sqlite3_value_nochange(sqlite3_value*);5927SQLITE_API int sqlite3_value_frombind(sqlite3_value*);59285929/*5930** CAPI3REF: Report the internal text encoding state of an sqlite3_value object5931** METHOD: sqlite3_value5932**5933** ^(The sqlite3_value_encoding(X) interface returns one of [SQLITE_UTF8],5934** [SQLITE_UTF16BE], or [SQLITE_UTF16LE] according to the current text encoding5935** of the value X, assuming that X has type TEXT.)^  If sqlite3_value_type(X)5936** returns something other than SQLITE_TEXT, then the return value from5937** sqlite3_value_encoding(X) is meaningless.  ^Calls to5938** [sqlite3_value_text(X)], [sqlite3_value_text16(X)], [sqlite3_value_text16be(X)],5939** [sqlite3_value_text16le(X)], [sqlite3_value_bytes(X)], or5940** [sqlite3_value_bytes16(X)] might change the encoding of the value X and5941** thus change the return from subsequent calls to sqlite3_value_encoding(X).5942**5943** This routine is intended for used by applications that test and validate5944** the SQLite implementation.  This routine is inquiring about the opaque5945** internal state of an [sqlite3_value] object.  Ordinary applications should5946** not need to know what the internal state of an sqlite3_value object is and5947** hence should not need to use this interface.5948*/5949SQLITE_API int sqlite3_value_encoding(sqlite3_value*);59505951/*5952** CAPI3REF: Finding The Subtype Of SQL Values5953** METHOD: sqlite3_value5954**5955** The sqlite3_value_subtype(V) function returns the subtype for5956** an [application-defined SQL function] argument V.  The subtype5957** information can be used to pass a limited amount of context from5958** one SQL function to another.  Use the [sqlite3_result_subtype()]5959** routine to set the subtype for the return value of an SQL function.5960**5961** Every [application-defined SQL function] that invokes this interface5962** should include the [SQLITE_SUBTYPE] property in the text5963** encoding argument when the function is [sqlite3_create_function|registered].5964** If the [SQLITE_SUBTYPE] property is omitted, then sqlite3_value_subtype()5965** might return zero instead of the upstream subtype in some corner cases.5966*/5967SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*);59685969/*5970** CAPI3REF: Copy And Free SQL Values5971** METHOD: sqlite3_value5972**5973** ^The sqlite3_value_dup(V) interface makes a copy of the [sqlite3_value]5974** object D and returns a pointer to that copy.  ^The [sqlite3_value] returned5975** is a [protected sqlite3_value] object even if the input is not.5976** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a5977** memory allocation fails. ^If V is a [pointer value], then the result5978** of sqlite3_value_dup(V) is a NULL value.5979**5980** ^The sqlite3_value_free(V) interface frees an [sqlite3_value] object5981** previously obtained from [sqlite3_value_dup()].  ^If V is a NULL pointer5982** then sqlite3_value_free(V) is a harmless no-op.5983*/5984SQLITE_API sqlite3_value *sqlite3_value_dup(const sqlite3_value*);5985SQLITE_API void sqlite3_value_free(sqlite3_value*);59865987/*5988** CAPI3REF: Obtain Aggregate Function Context5989** METHOD: sqlite3_context5990**5991** Implementations of aggregate SQL functions use this5992** routine to allocate memory for storing their state.5993**5994** ^The first time the sqlite3_aggregate_context(C,N) routine is called5995** for a particular aggregate function, SQLite allocates5996** N bytes of memory, zeroes out that memory, and returns a pointer5997** to the new memory. ^On second and subsequent calls to5998** sqlite3_aggregate_context() for the same aggregate function instance,5999** the same buffer is returned.  Sqlite3_aggregate_context() is normally6000** called once for each invocation of the xStep callback and then one6001** last time when the xFinal callback is invoked.  ^(When no rows match6002** an aggregate query, the xStep() callback of the aggregate function6003** implementation is never called and xFinal() is called exactly once.6004** In those cases, sqlite3_aggregate_context() might be called for the6005** first time from within xFinal().)^6006**6007** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer6008** when first called if N is less than or equal to zero or if a memory6009** allocation error occurs.6010**6011** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is6012** determined by the N parameter on first successful call.  Changing the6013** value of N in any subsequent call to sqlite3_aggregate_context() within6014** the same aggregate function instance will not resize the memory6015** allocation.)^  Within the xFinal callback, it is customary to set6016** N=0 in calls to sqlite3_aggregate_context(C,N) so that no6017** pointless memory allocations occur.6018**6019** ^SQLite automatically frees the memory allocated by6020** sqlite3_aggregate_context() when the aggregate query concludes.6021**6022** The first parameter must be a copy of the6023** [sqlite3_context | SQL function context] that is the first parameter6024** to the xStep or xFinal callback routine that implements the aggregate6025** function.6026**6027** This routine must be called from the same thread in which6028** the aggregate SQL function is running.6029*/6030SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);60316032/*6033** CAPI3REF: User Data For Functions6034** METHOD: sqlite3_context6035**6036** ^The sqlite3_user_data() interface returns a copy of6037** the pointer that was the pUserData parameter (the 5th parameter)6038** of the [sqlite3_create_function()]6039** and [sqlite3_create_function16()] routines that originally6040** registered the application defined function.6041**6042** This routine must be called from the same thread in which6043** the application-defined function is running.6044*/6045SQLITE_API void *sqlite3_user_data(sqlite3_context*);60466047/*6048** CAPI3REF: Database Connection For Functions6049** METHOD: sqlite3_context6050**6051** ^The sqlite3_context_db_handle() interface returns a copy of6052** the pointer to the [database connection] (the 1st parameter)6053** of the [sqlite3_create_function()]6054** and [sqlite3_create_function16()] routines that originally6055** registered the application defined function.6056*/6057SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);60586059/*6060** CAPI3REF: Function Auxiliary Data6061** METHOD: sqlite3_context6062**6063** These functions may be used by (non-aggregate) SQL functions to6064** associate auxiliary data with argument values. If the same argument6065** value is passed to multiple invocations of the same SQL function during6066** query execution, under some circumstances the associated auxiliary data6067** might be preserved.  An example of where this might be useful is in a6068** regular-expression matching function. The compiled version of the regular6069** expression can be stored as auxiliary data associated with the pattern string.6070** Then as long as the pattern string remains the same,6071** the compiled regular expression can be reused on multiple6072** invocations of the same function.6073**6074** ^The sqlite3_get_auxdata(C,N) interface returns a pointer to the auxiliary data6075** associated by the sqlite3_set_auxdata(C,N,P,X) function with the Nth argument6076** value to the application-defined function.  ^N is zero for the left-most6077** function argument.  ^If there is no auxiliary data6078** associated with the function argument, the sqlite3_get_auxdata(C,N) interface6079** returns a NULL pointer.6080**6081** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as auxiliary data for the6082** N-th argument of the application-defined function.  ^Subsequent6083** calls to sqlite3_get_auxdata(C,N) return P from the most recent6084** sqlite3_set_auxdata(C,N,P,X) call if the auxiliary data is still valid or6085** NULL if the auxiliary data has been discarded.6086** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,6087** SQLite will invoke the destructor function X with parameter P exactly6088** once, when the auxiliary data is discarded.6089** SQLite is free to discard the auxiliary data at any time, including: <ul>6090** <li> ^(when the corresponding function parameter changes)^, or6091** <li> ^(when [sqlite3_reset()] or [sqlite3_finalize()] is called for the6092**      SQL statement)^, or6093** <li> ^(when sqlite3_set_auxdata() is invoked again on the same6094**       parameter)^, or6095** <li> ^(during the original sqlite3_set_auxdata() call when a memory6096**      allocation error occurs.)^6097** <li> ^(during the original sqlite3_set_auxdata() call if the function6098**      is evaluated during query planning instead of during query execution,6099**      as sometimes happens with [SQLITE_ENABLE_STAT4].)^ </ul>6100**6101** Note the last two bullets in particular.  The destructor X in6102** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the6103** sqlite3_set_auxdata() interface even returns.  Hence sqlite3_set_auxdata()6104** should be called near the end of the function implementation and the6105** function implementation should not make any use of P after6106** sqlite3_set_auxdata() has been called.  Furthermore, a call to6107** sqlite3_get_auxdata() that occurs immediately after a corresponding call6108** to sqlite3_set_auxdata() might still return NULL if an out-of-memory6109** condition occurred during the sqlite3_set_auxdata() call or if the6110** function is being evaluated during query planning rather than during6111** query execution.6112**6113** ^(In practice, auxiliary data is preserved between function calls for6114** function parameters that are compile-time constants, including literal6115** values and [parameters] and expressions composed from the same.)^6116**6117** The value of the N parameter to these interfaces should be non-negative.6118** Future enhancements may make use of negative N values to define new6119** kinds of function caching behavior.6120**6121** These routines must be called from the same thread in which6122** the SQL function is running.6123**6124** See also: [sqlite3_get_clientdata()] and [sqlite3_set_clientdata()].6125*/6126SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);6127SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));61286129/*6130** CAPI3REF: Database Connection Client Data6131** METHOD: sqlite36132**6133** These functions are used to associate one or more named pointers6134** with a [database connection].6135** A call to sqlite3_set_clientdata(D,N,P,X) causes the pointer P6136** to be attached to [database connection] D using name N.  Subsequent6137** calls to sqlite3_get_clientdata(D,N) will return a copy of pointer P6138** or a NULL pointer if there were no prior calls to6139** sqlite3_set_clientdata() with the same values of D and N.6140** Names are compared using strcmp() and are thus case sensitive.6141**6142** If P and X are both non-NULL, then the destructor X is invoked with6143** argument P on the first of the following occurrences:6144** <ul>6145** <li> An out-of-memory error occurs during the call to6146**      sqlite3_set_clientdata() which attempts to register pointer P.6147** <li> A subsequent call to sqlite3_set_clientdata(D,N,P,X) is made6148**      with the same D and N parameters.6149** <li> The database connection closes.  SQLite does not make any guarantees6150**      about the order in which destructors are called, only that all6151**      destructors will be called exactly once at some point during the6152**      database connection closing process.6153** </ul>6154**6155** SQLite does not do anything with client data other than invoke6156** destructors on the client data at the appropriate time.  The intended6157** use for client data is to provide a mechanism for wrapper libraries6158** to store additional information about an SQLite database connection.6159**6160** There is no limit (other than available memory) on the number of different6161** client data pointers (with different names) that can be attached to a6162** single database connection.  However, the implementation is optimized6163** for the case of having only one or two different client data names.6164** Applications and wrapper libraries are discouraged from using more than6165** one client data name each.6166**6167** There is no way to enumerate the client data pointers6168** associated with a database connection.  The N parameter can be thought6169** of as a secret key such that only code that knows the secret key is able6170** to access the associated data.6171**6172** Security Warning:  These interfaces should not be exposed in scripting6173** languages or in other circumstances where it might be possible for an6174** an attacker to invoke them.  Any agent that can invoke these interfaces6175** can probably also take control of the process.6176**6177** Database connection client data is only available for SQLite6178** version 3.44.0 ([dateof:3.44.0]) and later.6179**6180** See also: [sqlite3_set_auxdata()] and [sqlite3_get_auxdata()].6181*/6182SQLITE_API void *sqlite3_get_clientdata(sqlite3*,const char*);6183SQLITE_API int sqlite3_set_clientdata(sqlite3*, const char*, void*, void(*)(void*));61846185/*6186** CAPI3REF: Constants Defining Special Destructor Behavior6187**6188** These are special values for the destructor that is passed in as the6189** final argument to routines like [sqlite3_result_blob()].  ^If the destructor6190** argument is SQLITE_STATIC, it means that the content pointer is constant6191** and will never change.  It does not need to be destroyed.  ^The6192** SQLITE_TRANSIENT value means that the content will likely change in6193** the near future and that SQLite should make its own private copy of6194** the content before returning.6195**6196** The typedef is necessary to work around problems in certain6197** C++ compilers.6198*/6199typedef void (*sqlite3_destructor_type)(void*);6200#define SQLITE_STATIC      ((sqlite3_destructor_type)0)6201#define SQLITE_TRANSIENT   ((sqlite3_destructor_type)-1)62026203/*6204** CAPI3REF: Setting The Result Of An SQL Function6205** METHOD: sqlite3_context6206**6207** These routines are used by the xFunc or xFinal callbacks that6208** implement SQL functions and aggregates.  See6209** [sqlite3_create_function()] and [sqlite3_create_function16()]6210** for additional information.6211**6212** These functions work very much like the [parameter binding] family of6213** functions used to bind values to host parameters in prepared statements.6214** Refer to the [SQL parameter] documentation for additional information.6215**6216** ^The sqlite3_result_blob() interface sets the result from6217** an application-defined function to be the BLOB whose content is pointed6218** to by the second parameter and which is N bytes long where N is the6219** third parameter.6220**6221** ^The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N)6222** interfaces set the result of the application-defined function to be6223** a BLOB containing all zero bytes and N bytes in size.6224**6225** ^The sqlite3_result_double() interface sets the result from6226** an application-defined function to be a floating point value specified6227** by its 2nd argument.6228**6229** ^The sqlite3_result_error() and sqlite3_result_error16() functions6230** cause the implemented SQL function to throw an exception.6231** ^SQLite uses the string pointed to by the6232** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()6233** as the text of an error message.  ^SQLite interprets the error6234** message string from sqlite3_result_error() as UTF-8. ^SQLite6235** interprets the string from sqlite3_result_error16() as UTF-16 using6236** the same [byte-order determination rules] as [sqlite3_bind_text16()].6237** ^If the third parameter to sqlite3_result_error()6238** or sqlite3_result_error16() is negative then SQLite takes as the error6239** message all text up through the first zero character.6240** ^If the third parameter to sqlite3_result_error() or6241** sqlite3_result_error16() is non-negative then SQLite takes that many6242** bytes (not characters) from the 2nd parameter as the error message.6243** ^The sqlite3_result_error() and sqlite3_result_error16()6244** routines make a private copy of the error message text before6245** they return.  Hence, the calling function can deallocate or6246** modify the text after they return without harm.6247** ^The sqlite3_result_error_code() function changes the error code6248** returned by SQLite as a result of an error in a function.  ^By default,6249** the error code is SQLITE_ERROR.  ^A subsequent call to sqlite3_result_error()6250** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.6251**6252** ^The sqlite3_result_error_toobig() interface causes SQLite to throw an6253** error indicating that a string or BLOB is too long to represent.6254**6255** ^The sqlite3_result_error_nomem() interface causes SQLite to throw an6256** error indicating that a memory allocation failed.6257**6258** ^The sqlite3_result_int() interface sets the return value6259** of the application-defined function to be the 32-bit signed integer6260** value given in the 2nd argument.6261** ^The sqlite3_result_int64() interface sets the return value6262** of the application-defined function to be the 64-bit signed integer6263** value given in the 2nd argument.6264**6265** ^The sqlite3_result_null() interface sets the return value6266** of the application-defined function to be NULL.6267**6268** ^The sqlite3_result_text(), sqlite3_result_text16(),6269** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces6270** set the return value of the application-defined function to be6271** a text string which is represented as UTF-8, UTF-16 native byte order,6272** UTF-16 little endian, or UTF-16 big endian, respectively.6273** ^The sqlite3_result_text64() interface sets the return value of an6274** application-defined function to be a text string in an encoding6275** specified by the fifth (and last) parameter, which must be one6276** of [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE].6277** ^SQLite takes the text result from the application from6278** the 2nd parameter of the sqlite3_result_text* interfaces.6279** ^If the 3rd parameter to any of the sqlite3_result_text* interfaces6280** other than sqlite3_result_text64() is negative, then SQLite computes6281** the string length itself by searching the 2nd parameter for the first6282** zero character.6283** ^If the 3rd parameter to the sqlite3_result_text* interfaces6284** is non-negative, then as many bytes (not characters) of the text6285** pointed to by the 2nd parameter are taken as the application-defined6286** function result.  If the 3rd parameter is non-negative, then it6287** must be the byte offset into the string where the NUL terminator would6288** appear if the string where NUL terminated.  If any NUL characters occur6289** in the string at a byte offset that is less than the value of the 3rd6290** parameter, then the resulting string will contain embedded NULs and the6291** result of expressions operating on strings with embedded NULs is undefined.6292** ^If the 4th parameter to the sqlite3_result_text* interfaces6293** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that6294** function as the destructor on the text or BLOB result when it has6295** finished using that result.6296** ^If the 4th parameter to the sqlite3_result_text* interfaces or to6297** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite6298** assumes that the text or BLOB result is in constant space and does not6299** copy the content of the parameter nor call a destructor on the content6300** when it has finished using that result.6301** ^If the 4th parameter to the sqlite3_result_text* interfaces6302** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT6303** then SQLite makes a copy of the result into space obtained6304** from [sqlite3_malloc()] before it returns.6305**6306** ^For the sqlite3_result_text16(), sqlite3_result_text16le(), and6307** sqlite3_result_text16be() routines, and for sqlite3_result_text64()6308** when the encoding is not UTF8, if the input UTF16 begins with a6309** byte-order mark (BOM, U+FEFF) then the BOM is removed from the6310** string and the rest of the string is interpreted according to the6311** byte-order specified by the BOM.  ^The byte-order specified by6312** the BOM at the beginning of the text overrides the byte-order6313** specified by the interface procedure.  ^So, for example, if6314** sqlite3_result_text16le() is invoked with text that begins6315** with bytes 0xfe, 0xff (a big-endian byte-order mark) then the6316** first two bytes of input are skipped and the remaining input6317** is interpreted as UTF16BE text.6318**6319** ^For UTF16 input text to the sqlite3_result_text16(),6320** sqlite3_result_text16be(), sqlite3_result_text16le(), and6321** sqlite3_result_text64() routines, if the text contains invalid6322** UTF16 characters, the invalid characters might be converted6323** into the unicode replacement character, U+FFFD.6324**6325** ^The sqlite3_result_value() interface sets the result of6326** the application-defined function to be a copy of the6327** [unprotected sqlite3_value] object specified by the 2nd parameter.  ^The6328** sqlite3_result_value() interface makes a copy of the [sqlite3_value]6329** so that the [sqlite3_value] specified in the parameter may change or6330** be deallocated after sqlite3_result_value() returns without harm.6331** ^A [protected sqlite3_value] object may always be used where an6332** [unprotected sqlite3_value] object is required, so either6333** kind of [sqlite3_value] object can be used with this interface.6334**6335** ^The sqlite3_result_pointer(C,P,T,D) interface sets the result to an6336** SQL NULL value, just like [sqlite3_result_null(C)], except that it6337** also associates the host-language pointer P or type T with that6338** NULL value such that the pointer can be retrieved within an6339** [application-defined SQL function] using [sqlite3_value_pointer()].6340** ^If the D parameter is not NULL, then it is a pointer to a destructor6341** for the P parameter.  ^SQLite invokes D with P as its only argument6342** when SQLite is finished with P.  The T parameter should be a static6343** string and preferably a string literal. The sqlite3_result_pointer()6344** routine is part of the [pointer passing interface] added for SQLite 3.20.0.6345**6346** If these routines are called from within the different thread6347** than the one containing the application-defined function that received6348** the [sqlite3_context] pointer, the results are undefined.6349*/6350SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));6351SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*,6352                           sqlite3_uint64,void(*)(void*));6353SQLITE_API void sqlite3_result_double(sqlite3_context*, double);6354SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);6355SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);6356SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*);6357SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*);6358SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int);6359SQLITE_API void sqlite3_result_int(sqlite3_context*, int);6360SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);6361SQLITE_API void sqlite3_result_null(sqlite3_context*);6362SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));6363SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64,6364                           void(*)(void*), unsigned char encoding);6365SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));6366SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));6367SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));6368SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);6369SQLITE_API void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*));6370SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);6371SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);637263736374/*6375** CAPI3REF: Setting The Subtype Of An SQL Function6376** METHOD: sqlite3_context6377**6378** The sqlite3_result_subtype(C,T) function causes the subtype of6379** the result from the [application-defined SQL function] with6380** [sqlite3_context] C to be the value T.  Only the lower 8 bits6381** of the subtype T are preserved in current versions of SQLite;6382** higher order bits are discarded.6383** The number of subtype bytes preserved by SQLite might increase6384** in future releases of SQLite.6385**6386** Every [application-defined SQL function] that invokes this interface6387** should include the [SQLITE_RESULT_SUBTYPE] property in its6388** text encoding argument when the SQL function is6389** [sqlite3_create_function|registered].  If the [SQLITE_RESULT_SUBTYPE]6390** property is omitted from the function that invokes sqlite3_result_subtype(),6391** then in some cases the sqlite3_result_subtype() might fail to set6392** the result subtype.6393**6394** If SQLite is compiled with -DSQLITE_STRICT_SUBTYPE=1, then any6395** SQL function that invokes the sqlite3_result_subtype() interface6396** and that does not have the SQLITE_RESULT_SUBTYPE property will raise6397** an error.  Future versions of SQLite might enable -DSQLITE_STRICT_SUBTYPE=16398** by default.6399*/6400SQLITE_API void sqlite3_result_subtype(sqlite3_context*,unsigned int);64016402/*6403** CAPI3REF: Define New Collating Sequences6404** METHOD: sqlite36405**6406** ^These functions add, remove, or modify a [collation] associated6407** with the [database connection] specified as the first argument.6408**6409** ^The name of the collation is a UTF-8 string6410** for sqlite3_create_collation() and sqlite3_create_collation_v2()6411** and a UTF-16 string in native byte order for sqlite3_create_collation16().6412** ^Collation names that compare equal according to [sqlite3_strnicmp()] are6413** considered to be the same name.6414**6415** ^(The third argument (eTextRep) must be one of the constants:6416** <ul>6417** <li> [SQLITE_UTF8],6418** <li> [SQLITE_UTF16LE],6419** <li> [SQLITE_UTF16BE],6420** <li> [SQLITE_UTF16], or6421** <li> [SQLITE_UTF16_ALIGNED].6422** </ul>)^6423** ^The eTextRep argument determines the encoding of strings passed6424** to the collating function callback, xCompare.6425** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep6426** force strings to be UTF16 with native byte order.6427** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin6428** on an even byte address.6429**6430** ^The fourth argument, pArg, is an application data pointer that is passed6431** through as the first argument to the collating function callback.6432**6433** ^The fifth argument, xCompare, is a pointer to the collating function.6434** ^Multiple collating functions can be registered using the same name but6435** with different eTextRep parameters and SQLite will use whichever6436** function requires the least amount of data transformation.6437** ^If the xCompare argument is NULL then the collating function is6438** deleted.  ^When all collating functions having the same name are deleted,6439** that collation is no longer usable.6440**6441** ^The collating function callback is invoked with a copy of the pArg6442** application data pointer and with two strings in the encoding specified6443** by the eTextRep argument.  The two integer parameters to the collating6444** function callback are the length of the two strings, in bytes. The collating6445** function must return an integer that is negative, zero, or positive6446** if the first string is less than, equal to, or greater than the second,6447** respectively.  A collating function must always return the same answer6448** given the same inputs.  If two or more collating functions are registered6449** to the same collation name (using different eTextRep values) then all6450** must give an equivalent answer when invoked with equivalent strings.6451** The collating function must obey the following properties for all6452** strings A, B, and C:6453**6454** <ol>6455** <li> If A==B then B==A.6456** <li> If A==B and B==C then A==C.6457** <li> If A&lt;B THEN B&gt;A.6458** <li> If A&lt;B and B&lt;C then A&lt;C.6459** </ol>6460**6461** If a collating function fails any of the above constraints and that6462** collating function is registered and used, then the behavior of SQLite6463** is undefined.6464**6465** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation()6466** with the addition that the xDestroy callback is invoked on pArg when6467** the collating function is deleted.6468** ^Collating functions are deleted when they are overridden by later6469** calls to the collation creation functions or when the6470** [database connection] is closed using [sqlite3_close()].6471**6472** ^The xDestroy callback is <u>not</u> called if the6473** sqlite3_create_collation_v2() function fails.  Applications that invoke6474** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should6475** check the return code and dispose of the application data pointer6476** themselves rather than expecting SQLite to deal with it for them.6477** This is different from every other SQLite interface.  The inconsistency6478** is unfortunate but cannot be changed without breaking backwards6479** compatibility.6480**6481** See also:  [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].6482*/6483SQLITE_API int sqlite3_create_collation(6484  sqlite3*,6485  const char *zName,6486  int eTextRep,6487  void *pArg,6488  int(*xCompare)(void*,int,const void*,int,const void*)6489);6490SQLITE_API int sqlite3_create_collation_v2(6491  sqlite3*,6492  const char *zName,6493  int eTextRep,6494  void *pArg,6495  int(*xCompare)(void*,int,const void*,int,const void*),6496  void(*xDestroy)(void*)6497);6498SQLITE_API int sqlite3_create_collation16(6499  sqlite3*,6500  const void *zName,6501  int eTextRep,6502  void *pArg,6503  int(*xCompare)(void*,int,const void*,int,const void*)6504);65056506/*6507** CAPI3REF: Collation Needed Callbacks6508** METHOD: sqlite36509**6510** ^To avoid having to register all collation sequences before a database6511** can be used, a single callback function may be registered with the6512** [database connection] to be invoked whenever an undefined collation6513** sequence is required.6514**6515** ^If the function is registered using the sqlite3_collation_needed() API,6516** then it is passed the names of undefined collation sequences as strings6517** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,6518** the names are passed as UTF-16 in machine native byte order.6519** ^A call to either function replaces the existing collation-needed callback.6520**6521** ^(When the callback is invoked, the first argument passed is a copy6522** of the second argument to sqlite3_collation_needed() or6523** sqlite3_collation_needed16().  The second argument is the database6524** connection.  The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],6525** or [SQLITE_UTF16LE], indicating the most desirable form of the collation6526** sequence function required.  The fourth parameter is the name of the6527** required collation sequence.)^6528**6529** The callback function should register the desired collation using6530** [sqlite3_create_collation()], [sqlite3_create_collation16()], or6531** [sqlite3_create_collation_v2()].6532*/6533SQLITE_API int sqlite3_collation_needed(6534  sqlite3*,6535  void*,6536  void(*)(void*,sqlite3*,int eTextRep,const char*)6537);6538SQLITE_API int sqlite3_collation_needed16(6539  sqlite3*,6540  void*,6541  void(*)(void*,sqlite3*,int eTextRep,const void*)6542);65436544#ifdef SQLITE_ENABLE_CEROD6545/*6546** Specify the activation key for a CEROD database.  Unless6547** activated, none of the CEROD routines will work.6548*/6549SQLITE_API void sqlite3_activate_cerod(6550  const char *zPassPhrase        /* Activation phrase */6551);6552#endif65536554/*6555** CAPI3REF: Suspend Execution For A Short Time6556**6557** The sqlite3_sleep() function causes the current thread to suspend execution6558** for at least a number of milliseconds specified in its parameter.6559**6560** If the operating system does not support sleep requests with6561** millisecond time resolution, then the time will be rounded up to6562** the nearest second. The number of milliseconds of sleep actually6563** requested from the operating system is returned.6564**6565** ^SQLite implements this interface by calling the xSleep()6566** method of the default [sqlite3_vfs] object.  If the xSleep() method6567** of the default VFS is not implemented correctly, or not implemented at6568** all, then the behavior of sqlite3_sleep() may deviate from the description6569** in the previous paragraphs.6570**6571** If a negative argument is passed to sqlite3_sleep() the results vary by6572** VFS and operating system.  Some system treat a negative argument as an6573** instruction to sleep forever.  Others understand it to mean do not sleep6574** at all. ^In SQLite version 3.42.0 and later, a negative6575** argument passed into sqlite3_sleep() is changed to zero before it is relayed6576** down into the xSleep method of the VFS.6577*/6578SQLITE_API int sqlite3_sleep(int);65796580/*6581** CAPI3REF: Name Of The Folder Holding Temporary Files6582**6583** ^(If this global variable is made to point to a string which is6584** the name of a folder (a.k.a. directory), then all temporary files6585** created by SQLite when using a built-in [sqlite3_vfs | VFS]6586** will be placed in that directory.)^  ^If this variable6587** is a NULL pointer, then SQLite performs a search for an appropriate6588** temporary file directory.6589**6590** Applications are strongly discouraged from using this global variable.6591** It is required to set a temporary folder on Windows Runtime (WinRT).6592** But for all other platforms, it is highly recommended that applications6593** neither read nor write this variable.  This global variable is a relic6594** that exists for backwards compatibility of legacy applications and should6595** be avoided in new projects.6596**6597** It is not safe to read or modify this variable in more than one6598** thread at a time.  It is not safe to read or modify this variable6599** if a [database connection] is being used at the same time in a separate6600** thread.6601** It is intended that this variable be set once6602** as part of process initialization and before any SQLite interface6603** routines have been called and that this variable remain unchanged6604** thereafter.6605**6606** ^The [temp_store_directory pragma] may modify this variable and cause6607** it to point to memory obtained from [sqlite3_malloc].  ^Furthermore,6608** the [temp_store_directory pragma] always assumes that any string6609** that this variable points to is held in memory obtained from6610** [sqlite3_malloc] and the pragma may attempt to free that memory6611** using [sqlite3_free].6612** Hence, if this variable is modified directly, either it should be6613** made NULL or made to point to memory obtained from [sqlite3_malloc]6614** or else the use of the [temp_store_directory pragma] should be avoided.6615** Except when requested by the [temp_store_directory pragma], SQLite6616** does not free the memory that sqlite3_temp_directory points to.  If6617** the application wants that memory to be freed, it must do6618** so itself, taking care to only do so after all [database connection]6619** objects have been destroyed.6620**6621** <b>Note to Windows Runtime users:</b>  The temporary directory must be set6622** prior to calling [sqlite3_open] or [sqlite3_open_v2].  Otherwise, various6623** features that require the use of temporary files may fail.  Here is an6624** example of how to do this using C++ with the Windows Runtime:6625**6626** <blockquote><pre>6627** LPCWSTR zPath = Windows::Storage::ApplicationData::Current->6628** &nbsp;     TemporaryFolder->Path->Data();6629** char zPathBuf&#91;MAX_PATH + 1&#93;;6630** memset(zPathBuf, 0, sizeof(zPathBuf));6631** WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, sizeof(zPathBuf),6632** &nbsp;     NULL, NULL);6633** sqlite3_temp_directory = sqlite3_mprintf("%s", zPathBuf);6634** </pre></blockquote>6635*/6636SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory;66376638/*6639** CAPI3REF: Name Of The Folder Holding Database Files6640**6641** ^(If this global variable is made to point to a string which is6642** the name of a folder (a.k.a. directory), then all database files6643** specified with a relative pathname and created or accessed by6644** SQLite when using a built-in windows [sqlite3_vfs | VFS] will be assumed6645** to be relative to that directory.)^ ^If this variable is a NULL6646** pointer, then SQLite assumes that all database files specified6647** with a relative pathname are relative to the current directory6648** for the process.  Only the windows VFS makes use of this global6649** variable; it is ignored by the unix VFS.6650**6651** Changing the value of this variable while a database connection is6652** open can result in a corrupt database.6653**6654** It is not safe to read or modify this variable in more than one6655** thread at a time.  It is not safe to read or modify this variable6656** if a [database connection] is being used at the same time in a separate6657** thread.6658** It is intended that this variable be set once6659** as part of process initialization and before any SQLite interface6660** routines have been called and that this variable remain unchanged6661** thereafter.6662**6663** ^The [data_store_directory pragma] may modify this variable and cause6664** it to point to memory obtained from [sqlite3_malloc].  ^Furthermore,6665** the [data_store_directory pragma] always assumes that any string6666** that this variable points to is held in memory obtained from6667** [sqlite3_malloc] and the pragma may attempt to free that memory6668** using [sqlite3_free].6669** Hence, if this variable is modified directly, either it should be6670** made NULL or made to point to memory obtained from [sqlite3_malloc]6671** or else the use of the [data_store_directory pragma] should be avoided.6672*/6673SQLITE_API SQLITE_EXTERN char *sqlite3_data_directory;66746675/*6676** CAPI3REF: Win32 Specific Interface6677**6678** These interfaces are available only on Windows.  The6679** [sqlite3_win32_set_directory] interface is used to set the value associated6680** with the [sqlite3_temp_directory] or [sqlite3_data_directory] variable, to6681** zValue, depending on the value of the type parameter.  The zValue parameter6682** should be NULL to cause the previous value to be freed via [sqlite3_free];6683** a non-NULL value will be copied into memory obtained from [sqlite3_malloc]6684** prior to being used.  The [sqlite3_win32_set_directory] interface returns6685** [SQLITE_OK] to indicate success, [SQLITE_ERROR] if the type is unsupported,6686** or [SQLITE_NOMEM] if memory could not be allocated.  The value of the6687** [sqlite3_data_directory] variable is intended to act as a replacement for6688** the current directory on the sub-platforms of Win32 where that concept is6689** not present, e.g. WinRT and UWP.  The [sqlite3_win32_set_directory8] and6690** [sqlite3_win32_set_directory16] interfaces behave exactly the same as the6691** sqlite3_win32_set_directory interface except the string parameter must be6692** UTF-8 or UTF-16, respectively.6693*/6694SQLITE_API int sqlite3_win32_set_directory(6695  unsigned long type, /* Identifier for directory being set or reset */6696  void *zValue        /* New value for directory being set or reset */6697);6698SQLITE_API int sqlite3_win32_set_directory8(unsigned long type, const char *zValue);6699SQLITE_API int sqlite3_win32_set_directory16(unsigned long type, const void *zValue);67006701/*6702** CAPI3REF: Win32 Directory Types6703**6704** These macros are only available on Windows.  They define the allowed values6705** for the type argument to the [sqlite3_win32_set_directory] interface.6706*/6707#define SQLITE_WIN32_DATA_DIRECTORY_TYPE  16708#define SQLITE_WIN32_TEMP_DIRECTORY_TYPE  267096710/*6711** CAPI3REF: Test For Auto-Commit Mode6712** KEYWORDS: {autocommit mode}6713** METHOD: sqlite36714**6715** ^The sqlite3_get_autocommit() interface returns non-zero or6716** zero if the given database connection is or is not in autocommit mode,6717** respectively.  ^Autocommit mode is on by default.6718** ^Autocommit mode is disabled by a [BEGIN] statement.6719** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].6720**6721** If certain kinds of errors occur on a statement within a multi-statement6722** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR],6723** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the6724** transaction might be rolled back automatically.  The only way to6725** find out whether SQLite automatically rolled back the transaction after6726** an error is to use this function.6727**6728** If another thread changes the autocommit status of the database6729** connection while this routine is running, then the return value6730** is undefined.6731*/6732SQLITE_API int sqlite3_get_autocommit(sqlite3*);67336734/*6735** CAPI3REF: Find The Database Handle Of A Prepared Statement6736** METHOD: sqlite3_stmt6737**6738** ^The sqlite3_db_handle interface returns the [database connection] handle6739** to which a [prepared statement] belongs.  ^The [database connection]6740** returned by sqlite3_db_handle is the same [database connection]6741** that was the first argument6742** to the [sqlite3_prepare_v2()] call (or its variants) that was used to6743** create the statement in the first place.6744*/6745SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);67466747/*6748** CAPI3REF: Return The Schema Name For A Database Connection6749** METHOD: sqlite36750**6751** ^The sqlite3_db_name(D,N) interface returns a pointer to the schema name6752** for the N-th database on database connection D, or a NULL pointer of N is6753** out of range.  An N value of 0 means the main database file.  An N of 1 is6754** the "temp" schema.  Larger values of N correspond to various ATTACH-ed6755** databases.6756**6757** Space to hold the string that is returned by sqlite3_db_name() is managed6758** by SQLite itself.  The string might be deallocated by any operation that6759** changes the schema, including [ATTACH] or [DETACH] or calls to6760** [sqlite3_serialize()] or [sqlite3_deserialize()], even operations that6761** occur on a different thread.  Applications that need to6762** remember the string long-term should make their own copy.  Applications that6763** are accessing the same database connection simultaneously on multiple6764** threads should mutex-protect calls to this API and should make their own6765** private copy of the result prior to releasing the mutex.6766*/6767SQLITE_API const char *sqlite3_db_name(sqlite3 *db, int N);67686769/*6770** CAPI3REF: Return The Filename For A Database Connection6771** METHOD: sqlite36772**6773** ^The sqlite3_db_filename(D,N) interface returns a pointer to the filename6774** associated with database N of connection D.6775** ^If there is no attached database N on the database6776** connection D, or if database N is a temporary or in-memory database, then6777** this function will return either a NULL pointer or an empty string.6778**6779** ^The string value returned by this routine is owned and managed by6780** the database connection.  ^The value will be valid until the database N6781** is [DETACH]-ed or until the database connection closes.6782**6783** ^The filename returned by this function is the output of the6784** xFullPathname method of the [VFS].  ^In other words, the filename6785** will be an absolute pathname, even if the filename used6786** to open the database originally was a URI or relative pathname.6787**6788** If the filename pointer returned by this routine is not NULL, then it6789** can be used as the filename input parameter to these routines:6790** <ul>6791** <li> [sqlite3_uri_parameter()]6792** <li> [sqlite3_uri_boolean()]6793** <li> [sqlite3_uri_int64()]6794** <li> [sqlite3_filename_database()]6795** <li> [sqlite3_filename_journal()]6796** <li> [sqlite3_filename_wal()]6797** </ul>6798*/6799SQLITE_API sqlite3_filename sqlite3_db_filename(sqlite3 *db, const char *zDbName);68006801/*6802** CAPI3REF: Determine if a database is read-only6803** METHOD: sqlite36804**6805** ^The sqlite3_db_readonly(D,N) interface returns 1 if the database N6806** of connection D is read-only, 0 if it is read/write, or -1 if N is not6807** the name of a database on connection D.6808*/6809SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName);68106811/*6812** CAPI3REF: Determine the transaction state of a database6813** METHOD: sqlite36814**6815** ^The sqlite3_txn_state(D,S) interface returns the current6816** [transaction state] of schema S in database connection D.  ^If S is NULL,6817** then the highest transaction state of any schema on database connection D6818** is returned.  Transaction states are (in order of lowest to highest):6819** <ol>6820** <li value="0"> SQLITE_TXN_NONE6821** <li value="1"> SQLITE_TXN_READ6822** <li value="2"> SQLITE_TXN_WRITE6823** </ol>6824** ^If the S argument to sqlite3_txn_state(D,S) is not the name of6825** a valid schema, then -1 is returned.6826*/6827SQLITE_API int sqlite3_txn_state(sqlite3*,const char *zSchema);68286829/*6830** CAPI3REF: Allowed return values from sqlite3_txn_state()6831** KEYWORDS: {transaction state}6832**6833** These constants define the current transaction state of a database file.6834** ^The [sqlite3_txn_state(D,S)] interface returns one of these6835** constants in order to describe the transaction state of schema S6836** in [database connection] D.6837**6838** <dl>6839** [[SQLITE_TXN_NONE]] <dt>SQLITE_TXN_NONE</dt>6840** <dd>The SQLITE_TXN_NONE state means that no transaction is currently6841** pending.</dd>6842**6843** [[SQLITE_TXN_READ]] <dt>SQLITE_TXN_READ</dt>6844** <dd>The SQLITE_TXN_READ state means that the database is currently6845** in a read transaction.  Content has been read from the database file6846** but nothing in the database file has changed.  The transaction state6847** will advanced to SQLITE_TXN_WRITE if any changes occur and there are6848** no other conflicting concurrent write transactions.  The transaction6849** state will revert to SQLITE_TXN_NONE following a [ROLLBACK] or6850** [COMMIT].</dd>6851**6852** [[SQLITE_TXN_WRITE]] <dt>SQLITE_TXN_WRITE</dt>6853** <dd>The SQLITE_TXN_WRITE state means that the database is currently6854** in a write transaction.  Content has been written to the database file6855** but has not yet committed.  The transaction state will change to6856** to SQLITE_TXN_NONE at the next [ROLLBACK] or [COMMIT].</dd>6857*/6858#define SQLITE_TXN_NONE  06859#define SQLITE_TXN_READ  16860#define SQLITE_TXN_WRITE 268616862/*6863** CAPI3REF: Find the next prepared statement6864** METHOD: sqlite36865**6866** ^This interface returns a pointer to the next [prepared statement] after6867** pStmt associated with the [database connection] pDb.  ^If pStmt is NULL6868** then this interface returns a pointer to the first prepared statement6869** associated with the database connection pDb.  ^If no prepared statement6870** satisfies the conditions of this routine, it returns NULL.6871**6872** The [database connection] pointer D in a call to6873** [sqlite3_next_stmt(D,S)] must refer to an open database6874** connection and in particular must not be a NULL pointer.6875*/6876SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);68776878/*6879** CAPI3REF: Commit And Rollback Notification Callbacks6880** METHOD: sqlite36881**6882** ^The sqlite3_commit_hook() interface registers a callback6883** function to be invoked whenever a transaction is [COMMIT | committed].6884** ^Any callback set by a previous call to sqlite3_commit_hook()6885** for the same database connection is overridden.6886** ^The sqlite3_rollback_hook() interface registers a callback6887** function to be invoked whenever a transaction is [ROLLBACK | rolled back].6888** ^Any callback set by a previous call to sqlite3_rollback_hook()6889** for the same database connection is overridden.6890** ^The pArg argument is passed through to the callback.6891** ^If the callback on a commit hook function returns non-zero,6892** then the commit is converted into a rollback.6893**6894** ^The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions6895** return the P argument from the previous call of the same function6896** on the same [database connection] D, or NULL for6897** the first call for each function on D.6898**6899** The commit and rollback hook callbacks are not reentrant.6900** The callback implementation must not do anything that will modify6901** the database connection that invoked the callback.  Any actions6902** to modify the database connection must be deferred until after the6903** completion of the [sqlite3_step()] call that triggered the commit6904** or rollback hook in the first place.6905** Note that running any other SQL statements, including SELECT statements,6906** or merely calling [sqlite3_prepare_v2()] and [sqlite3_step()] will modify6907** the database connections for the meaning of "modify" in this paragraph.6908**6909** ^Registering a NULL function disables the callback.6910**6911** ^When the commit hook callback routine returns zero, the [COMMIT]6912** operation is allowed to continue normally.  ^If the commit hook6913** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].6914** ^The rollback hook is invoked on a rollback that results from a commit6915** hook returning non-zero, just as it would be with any other rollback.6916**6917** ^For the purposes of this API, a transaction is said to have been6918** rolled back if an explicit "ROLLBACK" statement is executed, or6919** an error or constraint causes an implicit rollback to occur.6920** ^The rollback callback is not invoked if a transaction is6921** automatically rolled back because the database connection is closed.6922**6923** See also the [sqlite3_update_hook()] interface.6924*/6925SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);6926SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);69276928/*6929** CAPI3REF: Autovacuum Compaction Amount Callback6930** METHOD: sqlite36931**6932** ^The sqlite3_autovacuum_pages(D,C,P,X) interface registers a callback6933** function C that is invoked prior to each autovacuum of the database6934** file.  ^The callback is passed a copy of the generic data pointer (P),6935** the schema-name of the attached database that is being autovacuumed,6936** the size of the database file in pages, the number of free pages,6937** and the number of bytes per page, respectively.  The callback should6938** return the number of free pages that should be removed by the6939** autovacuum.  ^If the callback returns zero, then no autovacuum happens.6940** ^If the value returned is greater than or equal to the number of6941** free pages, then a complete autovacuum happens.6942**6943** <p>^If there are multiple ATTACH-ed database files that are being6944** modified as part of a transaction commit, then the autovacuum pages6945** callback is invoked separately for each file.6946**6947** <p><b>The callback is not reentrant.</b> The callback function should6948** not attempt to invoke any other SQLite interface.  If it does, bad6949** things may happen, including segmentation faults and corrupt database6950** files.  The callback function should be a simple function that6951** does some arithmetic on its input parameters and returns a result.6952**6953** ^The X parameter to sqlite3_autovacuum_pages(D,C,P,X) is an optional6954** destructor for the P parameter.  ^If X is not NULL, then X(P) is6955** invoked whenever the database connection closes or when the callback6956** is overwritten by another invocation of sqlite3_autovacuum_pages().6957**6958** <p>^There is only one autovacuum pages callback per database connection.6959** ^Each call to the sqlite3_autovacuum_pages() interface overrides all6960** previous invocations for that database connection.  ^If the callback6961** argument (C) to sqlite3_autovacuum_pages(D,C,P,X) is a NULL pointer,6962** then the autovacuum steps callback is canceled.  The return value6963** from sqlite3_autovacuum_pages() is normally SQLITE_OK, but might6964** be some other error code if something goes wrong.  The current6965** implementation will only return SQLITE_OK or SQLITE_MISUSE, but other6966** return codes might be added in future releases.6967**6968** <p>If no autovacuum pages callback is specified (the usual case) or6969** a NULL pointer is provided for the callback,6970** then the default behavior is to vacuum all free pages.  So, in other6971** words, the default behavior is the same as if the callback function6972** were something like this:6973**6974** <blockquote><pre>6975** &nbsp;   unsigned int demonstration_autovac_pages_callback(6976** &nbsp;     void *pClientData,6977** &nbsp;     const char *zSchema,6978** &nbsp;     unsigned int nDbPage,6979** &nbsp;     unsigned int nFreePage,6980** &nbsp;     unsigned int nBytePerPage6981** &nbsp;   ){6982** &nbsp;     return nFreePage;6983** &nbsp;   }6984** </pre></blockquote>6985*/6986SQLITE_API int sqlite3_autovacuum_pages(6987  sqlite3 *db,6988  unsigned int(*)(void*,const char*,unsigned int,unsigned int,unsigned int),6989  void*,6990  void(*)(void*)6991);699269936994/*6995** CAPI3REF: Data Change Notification Callbacks6996** METHOD: sqlite36997**6998** ^The sqlite3_update_hook() interface registers a callback function6999** with the [database connection] identified by the first argument7000** to be invoked whenever a row is updated, inserted or deleted in7001** a [rowid table].7002** ^Any callback set by a previous call to this function7003** for the same database connection is overridden.7004**7005** ^The second argument is a pointer to the function to invoke when a7006** row is updated, inserted or deleted in a rowid table.7007** ^The first argument to the callback is a copy of the third argument7008** to sqlite3_update_hook().7009** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],7010** or [SQLITE_UPDATE], depending on the operation that caused the callback7011** to be invoked.7012** ^The third and fourth arguments to the callback contain pointers to the7013** database and table name containing the affected row.7014** ^The final callback parameter is the [rowid] of the row.7015** ^In the case of an update, this is the [rowid] after the update takes place.7016**7017** ^(The update hook is not invoked when internal system tables are7018** modified (i.e. sqlite_sequence).)^7019** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified.7020**7021** ^In the current implementation, the update hook7022** is not invoked when conflicting rows are deleted because of an7023** [ON CONFLICT | ON CONFLICT REPLACE] clause.  ^Nor is the update hook7024** invoked when rows are deleted using the [truncate optimization].7025** The exceptions defined in this paragraph might change in a future7026** release of SQLite.7027**7028** Whether the update hook is invoked before or after the7029** corresponding change is currently unspecified and may differ7030** depending on the type of change. Do not rely on the order of the7031** hook call with regards to the final result of the operation which7032** triggers the hook.7033**7034** The update hook implementation must not do anything that will modify7035** the database connection that invoked the update hook.  Any actions7036** to modify the database connection must be deferred until after the7037** completion of the [sqlite3_step()] call that triggered the update hook.7038** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their7039** database connections for the meaning of "modify" in this paragraph.7040**7041** ^The sqlite3_update_hook(D,C,P) function7042** returns the P argument from the previous call7043** on the same [database connection] D, or NULL for7044** the first call on D.7045**7046** See also the [sqlite3_commit_hook()], [sqlite3_rollback_hook()],7047** and [sqlite3_preupdate_hook()] interfaces.7048*/7049SQLITE_API void *sqlite3_update_hook(7050  sqlite3*,7051  void(*)(void *,int ,char const *,char const *,sqlite3_int64),7052  void*7053);70547055/*7056** CAPI3REF: Enable Or Disable Shared Pager Cache7057**7058** ^(This routine enables or disables the sharing of the database cache7059** and schema data structures between [database connection | connections]7060** to the same database. Sharing is enabled if the argument is true7061** and disabled if the argument is false.)^7062**7063** This interface is omitted if SQLite is compiled with7064** [-DSQLITE_OMIT_SHARED_CACHE].  The [-DSQLITE_OMIT_SHARED_CACHE]7065** compile-time option is recommended because the7066** [use of shared cache mode is discouraged].7067**7068** ^Cache sharing is enabled and disabled for an entire process.7069** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]).7070** In prior versions of SQLite,7071** sharing was enabled or disabled for each thread separately.7072**7073** ^(The cache sharing mode set by this interface effects all subsequent7074** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].7075** Existing database connections continue to use the sharing mode7076** that was in effect at the time they were opened.)^7077**7078** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled7079** successfully.  An [error code] is returned otherwise.)^7080**7081** ^Shared cache is disabled by default. It is recommended that it stay7082** that way.  In other words, do not use this routine.  This interface7083** continues to be provided for historical compatibility, but its use is7084** discouraged.  Any use of shared cache is discouraged.  If shared cache7085** must be used, it is recommended that shared cache only be enabled for7086** individual database connections using the [sqlite3_open_v2()] interface7087** with the [SQLITE_OPEN_SHAREDCACHE] flag.7088**7089** Note: This method is disabled on MacOS X 10.7 and iOS version 5.07090** and will always return SQLITE_MISUSE. On those systems,7091** shared cache mode should be enabled per-database connection via7092** [sqlite3_open_v2()] with [SQLITE_OPEN_SHAREDCACHE].7093**7094** This interface is threadsafe on processors where writing a7095** 32-bit integer is atomic.7096**7097** See Also:  [SQLite Shared-Cache Mode]7098*/7099SQLITE_API int sqlite3_enable_shared_cache(int);71007101/*7102** CAPI3REF: Attempt To Free Heap Memory7103**7104** ^The sqlite3_release_memory() interface attempts to free N bytes7105** of heap memory by deallocating non-essential memory allocations7106** held by the database library.   Memory used to cache database7107** pages to improve performance is an example of non-essential memory.7108** ^sqlite3_release_memory() returns the number of bytes actually freed,7109** which might be more or less than the amount requested.7110** ^The sqlite3_release_memory() routine is a no-op returning zero7111** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT].7112**7113** See also: [sqlite3_db_release_memory()]7114*/7115SQLITE_API int sqlite3_release_memory(int);71167117/*7118** CAPI3REF: Free Memory Used By A Database Connection7119** METHOD: sqlite37120**7121** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap7122** memory as possible from database connection D. Unlike the7123** [sqlite3_release_memory()] interface, this interface is in effect even7124** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is7125** omitted.7126**7127** See also: [sqlite3_release_memory()]7128*/7129SQLITE_API int sqlite3_db_release_memory(sqlite3*);71307131/*7132** CAPI3REF: Impose A Limit On Heap Size7133**7134** These interfaces impose limits on the amount of heap memory that will be7135** by all database connections within a single process.7136**7137** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the7138** soft limit on the amount of heap memory that may be allocated by SQLite.7139** ^SQLite strives to keep heap memory utilization below the soft heap7140** limit by reducing the number of pages held in the page cache7141** as heap memory usages approaches the limit.7142** ^The soft heap limit is "soft" because even though SQLite strives to stay7143** below the limit, it will exceed the limit rather than generate7144** an [SQLITE_NOMEM] error.  In other words, the soft heap limit7145** is advisory only.7146**7147** ^The sqlite3_hard_heap_limit64(N) interface sets a hard upper bound of7148** N bytes on the amount of memory that will be allocated.  ^The7149** sqlite3_hard_heap_limit64(N) interface is similar to7150** sqlite3_soft_heap_limit64(N) except that memory allocations will fail7151** when the hard heap limit is reached.7152**7153** ^The return value from both sqlite3_soft_heap_limit64() and7154** sqlite3_hard_heap_limit64() is the size of7155** the heap limit prior to the call, or negative in the case of an7156** error.  ^If the argument N is negative7157** then no change is made to the heap limit.  Hence, the current7158** size of heap limits can be determined by invoking7159** sqlite3_soft_heap_limit64(-1) or sqlite3_hard_heap_limit(-1).7160**7161** ^Setting the heap limits to zero disables the heap limiter mechanism.7162**7163** ^The soft heap limit may not be greater than the hard heap limit.7164** ^If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N)7165** is invoked with a value of N that is greater than the hard heap limit,7166** the soft heap limit is set to the value of the hard heap limit.7167** ^The soft heap limit is automatically enabled whenever the hard heap7168** limit is enabled. ^When sqlite3_hard_heap_limit64(N) is invoked and7169** the soft heap limit is outside the range of 1..N, then the soft heap7170** limit is set to N.  ^Invoking sqlite3_soft_heap_limit64(0) when the7171** hard heap limit is enabled makes the soft heap limit equal to the7172** hard heap limit.7173**7174** The memory allocation limits can also be adjusted using7175** [PRAGMA soft_heap_limit] and [PRAGMA hard_heap_limit].7176**7177** ^(The heap limits are not enforced in the current implementation7178** if one or more of following conditions are true:7179**7180** <ul>7181** <li> The limit value is set to zero.7182** <li> Memory accounting is disabled using a combination of the7183**      [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and7184**      the [SQLITE_DEFAULT_MEMSTATUS] compile-time option.7185** <li> An alternative page cache implementation is specified using7186**      [sqlite3_config]([SQLITE_CONFIG_PCACHE2],...).7187** <li> The page cache allocates from its own memory pool supplied7188**      by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than7189**      from the heap.7190** </ul>)^7191**7192** The circumstances under which SQLite will enforce the heap limits may7193** changes in future releases of SQLite.7194*/7195SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);7196SQLITE_API sqlite3_int64 sqlite3_hard_heap_limit64(sqlite3_int64 N);71977198/*7199** CAPI3REF: Deprecated Soft Heap Limit Interface7200** DEPRECATED7201**7202** This is a deprecated version of the [sqlite3_soft_heap_limit64()]7203** interface.  This routine is provided for historical compatibility7204** only.  All new applications should use the7205** [sqlite3_soft_heap_limit64()] interface rather than this one.7206*/7207SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);720872097210/*7211** CAPI3REF: Extract Metadata About A Column Of A Table7212** METHOD: sqlite37213**7214** ^(The sqlite3_table_column_metadata(X,D,T,C,....) routine returns7215** information about column C of table T in database D7216** on [database connection] X.)^  ^The sqlite3_table_column_metadata()7217** interface returns SQLITE_OK and fills in the non-NULL pointers in7218** the final five arguments with appropriate values if the specified7219** column exists.  ^The sqlite3_table_column_metadata() interface returns7220** SQLITE_ERROR if the specified column does not exist.7221** ^If the column-name parameter to sqlite3_table_column_metadata() is a7222** NULL pointer, then this routine simply checks for the existence of the7223** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it7224** does not.  If the table name parameter T in a call to7225** sqlite3_table_column_metadata(X,D,T,C,...) is NULL then the result is7226** undefined behavior.7227**7228** ^The column is identified by the second, third and fourth parameters to7229** this function. ^(The second parameter is either the name of the database7230** (i.e. "main", "temp", or an attached database) containing the specified7231** table or NULL.)^ ^If it is NULL, then all attached databases are searched7232** for the table using the same algorithm used by the database engine to7233** resolve unqualified table references.7234**7235** ^The third and fourth parameters to this function are the table and column7236** name of the desired column, respectively.7237**7238** ^Metadata is returned by writing to the memory locations passed as the 5th7239** and subsequent parameters to this function. ^Any of these arguments may be7240** NULL, in which case the corresponding element of metadata is omitted.7241**7242** ^(<blockquote>7243** <table border="1">7244** <tr><th> Parameter <th> Output<br>Type <th>  Description7245**7246** <tr><td> 5th <td> const char* <td> Data type7247** <tr><td> 6th <td> const char* <td> Name of default collation sequence7248** <tr><td> 7th <td> int         <td> True if column has a NOT NULL constraint7249** <tr><td> 8th <td> int         <td> True if column is part of the PRIMARY KEY7250** <tr><td> 9th <td> int         <td> True if column is [AUTOINCREMENT]7251** </table>7252** </blockquote>)^7253**7254** ^The memory pointed to by the character pointers returned for the7255** declaration type and collation sequence is valid until the next7256** call to any SQLite API function.7257**7258** ^If the specified table is actually a view, an [error code] is returned.7259**7260** ^If the specified column is "rowid", "oid" or "_rowid_" and the table7261** is not a [WITHOUT ROWID] table and an7262** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output7263** parameters are set for the explicitly declared column. ^(If there is no7264** [INTEGER PRIMARY KEY] column, then the outputs7265** for the [rowid] are set as follows:7266**7267** <pre>7268**     data type: "INTEGER"7269**     collation sequence: "BINARY"7270**     not null: 07271**     primary key: 17272**     auto increment: 07273** </pre>)^7274**7275** ^This function causes all database schemas to be read from disk and7276** parsed, if that has not already been done, and returns an error if7277** any errors are encountered while loading the schema.7278*/7279SQLITE_API int sqlite3_table_column_metadata(7280  sqlite3 *db,                /* Connection handle */7281  const char *zDbName,        /* Database name or NULL */7282  const char *zTableName,     /* Table name */7283  const char *zColumnName,    /* Column name */7284  char const **pzDataType,    /* OUTPUT: Declared data type */7285  char const **pzCollSeq,     /* OUTPUT: Collation sequence name */7286  int *pNotNull,              /* OUTPUT: True if NOT NULL constraint exists */7287  int *pPrimaryKey,           /* OUTPUT: True if column part of PK */7288  int *pAutoinc               /* OUTPUT: True if column is auto-increment */7289);72907291/*7292** CAPI3REF: Load An Extension7293** METHOD: sqlite37294**7295** ^This interface loads an SQLite extension library from the named file.7296**7297** ^The sqlite3_load_extension() interface attempts to load an7298** [SQLite extension] library contained in the file zFile.  If7299** the file cannot be loaded directly, attempts are made to load7300** with various operating-system specific extensions added.7301** So for example, if "samplelib" cannot be loaded, then names like7302** "samplelib.so" or "samplelib.dylib" or "samplelib.dll" might7303** be tried also.7304**7305** ^The entry point is zProc.7306** ^(zProc may be 0, in which case SQLite will try to come up with an7307** entry point name on its own.  It first tries "sqlite3_extension_init".7308** If that does not work, it constructs a name "sqlite3_X_init" where the7309** X is consists of the lower-case equivalent of all ASCII alphabetic7310** characters in the filename from the last "/" to the first following7311** "." and omitting any initial "lib".)^7312** ^The sqlite3_load_extension() interface returns7313** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.7314** ^If an error occurs and pzErrMsg is not 0, then the7315** [sqlite3_load_extension()] interface shall attempt to7316** fill *pzErrMsg with error message text stored in memory7317** obtained from [sqlite3_malloc()]. The calling function7318** should free this memory by calling [sqlite3_free()].7319**7320** ^Extension loading must be enabled using7321** [sqlite3_enable_load_extension()] or7322** [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],1,NULL)7323** prior to calling this API,7324** otherwise an error will be returned.7325**7326** <b>Security warning:</b> It is recommended that the7327** [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method be used to enable only this7328** interface.  The use of the [sqlite3_enable_load_extension()] interface7329** should be avoided.  This will keep the SQL function [load_extension()]7330** disabled and prevent SQL injections from giving attackers7331** access to extension loading capabilities.7332**7333** See also the [load_extension() SQL function].7334*/7335SQLITE_API int sqlite3_load_extension(7336  sqlite3 *db,          /* Load the extension into this database connection */7337  const char *zFile,    /* Name of the shared library containing extension */7338  const char *zProc,    /* Entry point.  Derived from zFile if 0 */7339  char **pzErrMsg       /* Put error message here if not 0 */7340);73417342/*7343** CAPI3REF: Enable Or Disable Extension Loading7344** METHOD: sqlite37345**7346** ^So as not to open security holes in older applications that are7347** unprepared to deal with [extension loading], and as a means of disabling7348** [extension loading] while evaluating user-entered SQL, the following API7349** is provided to turn the [sqlite3_load_extension()] mechanism on and off.7350**7351** ^Extension loading is off by default.7352** ^Call the sqlite3_enable_load_extension() routine with onoff==17353** to turn extension loading on and call it with onoff==0 to turn7354** it back off again.7355**7356** ^This interface enables or disables both the C-API7357** [sqlite3_load_extension()] and the SQL function [load_extension()].7358** ^(Use [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],..)7359** to enable or disable only the C-API.)^7360**7361** <b>Security warning:</b> It is recommended that extension loading7362** be enabled using the [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method7363** rather than this interface, so the [load_extension()] SQL function7364** remains disabled. This will prevent SQL injections from giving attackers7365** access to extension loading capabilities.7366*/7367SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);73687369/*7370** CAPI3REF: Automatically Load Statically Linked Extensions7371**7372** ^This interface causes the xEntryPoint() function to be invoked for7373** each new [database connection] that is created.  The idea here is that7374** xEntryPoint() is the entry point for a statically linked [SQLite extension]7375** that is to be automatically loaded into all new database connections.7376**7377** ^(Even though the function prototype shows that xEntryPoint() takes7378** no arguments and returns void, SQLite invokes xEntryPoint() with three7379** arguments and expects an integer result as if the signature of the7380** entry point where as follows:7381**7382** <blockquote><pre>7383** &nbsp;  int xEntryPoint(7384** &nbsp;    sqlite3 *db,7385** &nbsp;    const char **pzErrMsg,7386** &nbsp;    const struct sqlite3_api_routines *pThunk7387** &nbsp;  );7388** </pre></blockquote>)^7389**7390** If the xEntryPoint routine encounters an error, it should make *pzErrMsg7391** point to an appropriate error message (obtained from [sqlite3_mprintf()])7392** and return an appropriate [error code].  ^SQLite ensures that *pzErrMsg7393** is NULL before calling the xEntryPoint().  ^SQLite will invoke7394** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns.  ^If any7395** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()],7396** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail.7397**7398** ^Calling sqlite3_auto_extension(X) with an entry point X that is already7399** on the list of automatic extensions is a harmless no-op. ^No entry point7400** will be called more than once for each database connection that is opened.7401**7402** See also: [sqlite3_reset_auto_extension()]7403** and [sqlite3_cancel_auto_extension()]7404*/7405SQLITE_API int sqlite3_auto_extension(void(*xEntryPoint)(void));74067407/*7408** CAPI3REF: Cancel Automatic Extension Loading7409**7410** ^The [sqlite3_cancel_auto_extension(X)] interface unregisters the7411** initialization routine X that was registered using a prior call to7412** [sqlite3_auto_extension(X)].  ^The [sqlite3_cancel_auto_extension(X)]7413** routine returns 1 if initialization routine X was successfully7414** unregistered and it returns 0 if X was not on the list of initialization7415** routines.7416*/7417SQLITE_API int sqlite3_cancel_auto_extension(void(*xEntryPoint)(void));74187419/*7420** CAPI3REF: Reset Automatic Extension Loading7421**7422** ^This interface disables all automatic extensions previously7423** registered using [sqlite3_auto_extension()].7424*/7425SQLITE_API void sqlite3_reset_auto_extension(void);74267427/*7428** Structures used by the virtual table interface7429*/7430typedef struct sqlite3_vtab sqlite3_vtab;7431typedef struct sqlite3_index_info sqlite3_index_info;7432typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;7433typedef struct sqlite3_module sqlite3_module;74347435/*7436** CAPI3REF: Virtual Table Object7437** KEYWORDS: sqlite3_module {virtual table module}7438**7439** This structure, sometimes called a "virtual table module",7440** defines the implementation of a [virtual table].7441** This structure consists mostly of methods for the module.7442**7443** ^A virtual table module is created by filling in a persistent7444** instance of this structure and passing a pointer to that instance7445** to [sqlite3_create_module()] or [sqlite3_create_module_v2()].7446** ^The registration remains valid until it is replaced by a different7447** module or until the [database connection] closes.  The content7448** of this structure must not change while it is registered with7449** any database connection.7450*/7451struct sqlite3_module {7452  int iVersion;7453  int (*xCreate)(sqlite3*, void *pAux,7454               int argc, const char *const*argv,7455               sqlite3_vtab **ppVTab, char**);7456  int (*xConnect)(sqlite3*, void *pAux,7457               int argc, const char *const*argv,7458               sqlite3_vtab **ppVTab, char**);7459  int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);7460  int (*xDisconnect)(sqlite3_vtab *pVTab);7461  int (*xDestroy)(sqlite3_vtab *pVTab);7462  int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);7463  int (*xClose)(sqlite3_vtab_cursor*);7464  int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,7465                int argc, sqlite3_value **argv);7466  int (*xNext)(sqlite3_vtab_cursor*);7467  int (*xEof)(sqlite3_vtab_cursor*);7468  int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);7469  int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);7470  int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);7471  int (*xBegin)(sqlite3_vtab *pVTab);7472  int (*xSync)(sqlite3_vtab *pVTab);7473  int (*xCommit)(sqlite3_vtab *pVTab);7474  int (*xRollback)(sqlite3_vtab *pVTab);7475  int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,7476                       void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),7477                       void **ppArg);7478  int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);7479  /* The methods above are in version 1 of the sqlite_module object. Those7480  ** below are for version 2 and greater. */7481  int (*xSavepoint)(sqlite3_vtab *pVTab, int);7482  int (*xRelease)(sqlite3_vtab *pVTab, int);7483  int (*xRollbackTo)(sqlite3_vtab *pVTab, int);7484  /* The methods above are in versions 1 and 2 of the sqlite_module object.7485  ** Those below are for version 3 and greater. */7486  int (*xShadowName)(const char*);7487  /* The methods above are in versions 1 through 3 of the sqlite_module object.7488  ** Those below are for version 4 and greater. */7489  int (*xIntegrity)(sqlite3_vtab *pVTab, const char *zSchema,7490                    const char *zTabName, int mFlags, char **pzErr);7491};74927493/*7494** CAPI3REF: Virtual Table Indexing Information7495** KEYWORDS: sqlite3_index_info7496**7497** The sqlite3_index_info structure and its substructures is used as part7498** of the [virtual table] interface to7499** pass information into and receive the reply from the [xBestIndex]7500** method of a [virtual table module].  The fields under **Inputs** are the7501** inputs to xBestIndex and are read-only.  xBestIndex inserts its7502** results into the **Outputs** fields.7503**7504** ^(The aConstraint[] array records WHERE clause constraints of the form:7505**7506** <blockquote>column OP expr</blockquote>7507**7508** where OP is =, &lt;, &lt;=, &gt;, or &gt;=.)^  ^(The particular operator is7509** stored in aConstraint[].op using one of the7510** [SQLITE_INDEX_CONSTRAINT_EQ | SQLITE_INDEX_CONSTRAINT_ values].)^7511** ^(The index of the column is stored in7512** aConstraint[].iColumn.)^  ^(aConstraint[].usable is TRUE if the7513** expr on the right-hand side can be evaluated (and thus the constraint7514** is usable) and false if it cannot.)^7515**7516** ^The optimizer automatically inverts terms of the form "expr OP column"7517** and makes other simplifications to the WHERE clause in an attempt to7518** get as many WHERE clause terms into the form shown above as possible.7519** ^The aConstraint[] array only reports WHERE clause terms that are7520** relevant to the particular virtual table being queried.7521**7522** ^Information about the ORDER BY clause is stored in aOrderBy[].7523** ^Each term of aOrderBy records a column of the ORDER BY clause.7524**7525** The colUsed field indicates which columns of the virtual table may be7526** required by the current scan. Virtual table columns are numbered from7527** zero in the order in which they appear within the CREATE TABLE statement7528** passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62),7529** the corresponding bit is set within the colUsed mask if the column may be7530** required by SQLite. If the table has at least 64 columns and any column7531** to the right of the first 63 is required, then bit 63 of colUsed is also7532** set. In other words, column iCol may be required if the expression7533** (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to7534** non-zero.7535**7536** The [xBestIndex] method must fill aConstraintUsage[] with information7537** about what parameters to pass to xFilter.  ^If argvIndex>0 then7538** the right-hand side of the corresponding aConstraint[] is evaluated7539** and becomes the argvIndex-th entry in argv.  ^(If aConstraintUsage[].omit7540** is true, then the constraint is assumed to be fully handled by the7541** virtual table and might not be checked again by the byte code.)^ ^(The7542** aConstraintUsage[].omit flag is an optimization hint. When the omit flag7543** is left in its default setting of false, the constraint will always be7544** checked separately in byte code.  If the omit flag is change to true, then7545** the constraint may or may not be checked in byte code.  In other words,7546** when the omit flag is true there is no guarantee that the constraint will7547** not be checked again using byte code.)^7548**7549** ^The idxNum and idxStr values are recorded and passed into the7550** [xFilter] method.7551** ^[sqlite3_free()] is used to free idxStr if and only if7552** needToFreeIdxStr is true.7553**7554** ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in7555** the correct order to satisfy the ORDER BY clause so that no separate7556** sorting step is required.7557**7558** ^The estimatedCost value is an estimate of the cost of a particular7559** strategy. A cost of N indicates that the cost of the strategy is similar7560** to a linear scan of an SQLite table with N rows. A cost of log(N)7561** indicates that the expense of the operation is similar to that of a7562** binary search on a unique indexed field of an SQLite table with N rows.7563**7564** ^The estimatedRows value is an estimate of the number of rows that7565** will be returned by the strategy.7566**7567** The xBestIndex method may optionally populate the idxFlags field with a7568** mask of SQLITE_INDEX_SCAN_* flags. One such flag is7569** [SQLITE_INDEX_SCAN_HEX], which if set causes the [EXPLAIN QUERY PLAN]7570** output to show the idxNum has hex instead of as decimal.  Another flag is7571** SQLITE_INDEX_SCAN_UNIQUE, which if set indicates that the query plan will7572** return at most one row.7573**7574** Additionally, if xBestIndex sets the SQLITE_INDEX_SCAN_UNIQUE flag, then7575** SQLite also assumes that if a call to the xUpdate() method is made as7576** part of the same statement to delete or update a virtual table row and the7577** implementation returns SQLITE_CONSTRAINT, then there is no need to rollback7578** any database changes. In other words, if the xUpdate() returns7579** SQLITE_CONSTRAINT, the database contents must be exactly as they were7580** before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not7581** set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by7582** the xUpdate method are automatically rolled back by SQLite.7583**7584** IMPORTANT: The estimatedRows field was added to the sqlite3_index_info7585** structure for SQLite [version 3.8.2] ([dateof:3.8.2]).7586** If a virtual table extension is7587** used with an SQLite version earlier than 3.8.2, the results of attempting7588** to read or write the estimatedRows field are undefined (but are likely7589** to include crashing the application). The estimatedRows field should7590** therefore only be used if [sqlite3_libversion_number()] returns a7591** value greater than or equal to 3008002. Similarly, the idxFlags field7592** was added for [version 3.9.0] ([dateof:3.9.0]).7593** It may therefore only be used if7594** sqlite3_libversion_number() returns a value greater than or equal to7595** 3009000.7596*/7597struct sqlite3_index_info {7598  /* Inputs */7599  int nConstraint;           /* Number of entries in aConstraint */7600  struct sqlite3_index_constraint {7601     int iColumn;              /* Column constrained.  -1 for ROWID */7602     unsigned char op;         /* Constraint operator */7603     unsigned char usable;     /* True if this constraint is usable */7604     int iTermOffset;          /* Used internally - xBestIndex should ignore */7605  } *aConstraint;            /* Table of WHERE clause constraints */7606  int nOrderBy;              /* Number of terms in the ORDER BY clause */7607  struct sqlite3_index_orderby {7608     int iColumn;              /* Column number */7609     unsigned char desc;       /* True for DESC.  False for ASC. */7610  } *aOrderBy;               /* The ORDER BY clause */7611  /* Outputs */7612  struct sqlite3_index_constraint_usage {7613    int argvIndex;           /* if >0, constraint is part of argv to xFilter */7614    unsigned char omit;      /* Do not code a test for this constraint */7615  } *aConstraintUsage;7616  int idxNum;                /* Number used to identify the index */7617  char *idxStr;              /* String, possibly obtained from sqlite3_malloc */7618  int needToFreeIdxStr;      /* Free idxStr using sqlite3_free() if true */7619  int orderByConsumed;       /* True if output is already ordered */7620  double estimatedCost;           /* Estimated cost of using this index */7621  /* Fields below are only available in SQLite 3.8.2 and later */7622  sqlite3_int64 estimatedRows;    /* Estimated number of rows returned */7623  /* Fields below are only available in SQLite 3.9.0 and later */7624  int idxFlags;              /* Mask of SQLITE_INDEX_SCAN_* flags */7625  /* Fields below are only available in SQLite 3.10.0 and later */7626  sqlite3_uint64 colUsed;    /* Input: Mask of columns used by statement */7627};76287629/*7630** CAPI3REF: Virtual Table Scan Flags7631**7632** Virtual table implementations are allowed to set the7633** [sqlite3_index_info].idxFlags field to some combination of7634** these bits.7635*/7636#define SQLITE_INDEX_SCAN_UNIQUE 0x00000001 /* Scan visits at most 1 row */7637#define SQLITE_INDEX_SCAN_HEX    0x00000002 /* Display idxNum as hex */7638                                            /* in EXPLAIN QUERY PLAN */76397640/*7641** CAPI3REF: Virtual Table Constraint Operator Codes7642**7643** These macros define the allowed values for the7644** [sqlite3_index_info].aConstraint[].op field.  Each value represents7645** an operator that is part of a constraint term in the WHERE clause of7646** a query that uses a [virtual table].7647**7648** ^The left-hand operand of the operator is given by the corresponding7649** aConstraint[].iColumn field.  ^An iColumn of -1 indicates the left-hand7650** operand is the rowid.7651** The SQLITE_INDEX_CONSTRAINT_LIMIT and SQLITE_INDEX_CONSTRAINT_OFFSET7652** operators have no left-hand operand, and so for those operators the7653** corresponding aConstraint[].iColumn is meaningless and should not be7654** used.7655**7656** All operator values from SQLITE_INDEX_CONSTRAINT_FUNCTION through7657** value 255 are reserved to represent functions that are overloaded7658** by the [xFindFunction|xFindFunction method] of the virtual table7659** implementation.7660**7661** The right-hand operands for each constraint might be accessible using7662** the [sqlite3_vtab_rhs_value()] interface.  Usually the right-hand7663** operand is only available if it appears as a single constant literal7664** in the input SQL.  If the right-hand operand is another column or an7665** expression (even a constant expression) or a parameter, then the7666** sqlite3_vtab_rhs_value() probably will not be able to extract it.7667** ^The SQLITE_INDEX_CONSTRAINT_ISNULL and7668** SQLITE_INDEX_CONSTRAINT_ISNOTNULL operators have no right-hand operand7669** and hence calls to sqlite3_vtab_rhs_value() for those operators will7670** always return SQLITE_NOTFOUND.7671**7672** The collating sequence to be used for comparison can be found using7673** the [sqlite3_vtab_collation()] interface.  For most real-world virtual7674** tables, the collating sequence of constraints does not matter (for example7675** because the constraints are numeric) and so the sqlite3_vtab_collation()7676** interface is not commonly needed.7677*/7678#define SQLITE_INDEX_CONSTRAINT_EQ          27679#define SQLITE_INDEX_CONSTRAINT_GT          47680#define SQLITE_INDEX_CONSTRAINT_LE          87681#define SQLITE_INDEX_CONSTRAINT_LT         167682#define SQLITE_INDEX_CONSTRAINT_GE         327683#define SQLITE_INDEX_CONSTRAINT_MATCH      647684#define SQLITE_INDEX_CONSTRAINT_LIKE       657685#define SQLITE_INDEX_CONSTRAINT_GLOB       667686#define SQLITE_INDEX_CONSTRAINT_REGEXP     677687#define SQLITE_INDEX_CONSTRAINT_NE         687688#define SQLITE_INDEX_CONSTRAINT_ISNOT      697689#define SQLITE_INDEX_CONSTRAINT_ISNOTNULL  707690#define SQLITE_INDEX_CONSTRAINT_ISNULL     717691#define SQLITE_INDEX_CONSTRAINT_IS         727692#define SQLITE_INDEX_CONSTRAINT_LIMIT      737693#define SQLITE_INDEX_CONSTRAINT_OFFSET     747694#define SQLITE_INDEX_CONSTRAINT_FUNCTION  15076957696/*7697** CAPI3REF: Register A Virtual Table Implementation7698** METHOD: sqlite37699**7700** ^These routines are used to register a new [virtual table module] name.7701** ^Module names must be registered before7702** creating a new [virtual table] using the module and before using a7703** preexisting [virtual table] for the module.7704**7705** ^The module name is registered on the [database connection] specified7706** by the first parameter.  ^The name of the module is given by the7707** second parameter.  ^The third parameter is a pointer to7708** the implementation of the [virtual table module].   ^The fourth7709** parameter is an arbitrary client data pointer that is passed through7710** into the [xCreate] and [xConnect] methods of the virtual table module7711** when a new virtual table is be being created or reinitialized.7712**7713** ^The sqlite3_create_module_v2() interface has a fifth parameter which7714** is a pointer to a destructor for the pClientData.  ^SQLite will7715** invoke the destructor function (if it is not NULL) when SQLite7716** no longer needs the pClientData pointer.  ^The destructor will also7717** be invoked if the call to sqlite3_create_module_v2() fails.7718** ^The sqlite3_create_module()7719** interface is equivalent to sqlite3_create_module_v2() with a NULL7720** destructor.7721**7722** ^If the third parameter (the pointer to the sqlite3_module object) is7723** NULL then no new module is created and any existing modules with the7724** same name are dropped.7725**7726** See also: [sqlite3_drop_modules()]7727*/7728SQLITE_API int sqlite3_create_module(7729  sqlite3 *db,               /* SQLite connection to register module with */7730  const char *zName,         /* Name of the module */7731  const sqlite3_module *p,   /* Methods for the module */7732  void *pClientData          /* Client data for xCreate/xConnect */7733);7734SQLITE_API int sqlite3_create_module_v2(7735  sqlite3 *db,               /* SQLite connection to register module with */7736  const char *zName,         /* Name of the module */7737  const sqlite3_module *p,   /* Methods for the module */7738  void *pClientData,         /* Client data for xCreate/xConnect */7739  void(*xDestroy)(void*)     /* Module destructor function */7740);77417742/*7743** CAPI3REF: Remove Unnecessary Virtual Table Implementations7744** METHOD: sqlite37745**7746** ^The sqlite3_drop_modules(D,L) interface removes all virtual7747** table modules from database connection D except those named on list L.7748** The L parameter must be either NULL or a pointer to an array of pointers7749** to strings where the array is terminated by a single NULL pointer.7750** ^If the L parameter is NULL, then all virtual table modules are removed.7751**7752** See also: [sqlite3_create_module()]7753*/7754SQLITE_API int sqlite3_drop_modules(7755  sqlite3 *db,                /* Remove modules from this connection */7756  const char **azKeep         /* Except, do not remove the ones named here */7757);77587759/*7760** CAPI3REF: Virtual Table Instance Object7761** KEYWORDS: sqlite3_vtab7762**7763** Every [virtual table module] implementation uses a subclass7764** of this object to describe a particular instance7765** of the [virtual table].  Each subclass will7766** be tailored to the specific needs of the module implementation.7767** The purpose of this superclass is to define certain fields that are7768** common to all module implementations.7769**7770** ^Virtual tables methods can set an error message by assigning a7771** string obtained from [sqlite3_mprintf()] to zErrMsg.  The method should7772** take care that any prior string is freed by a call to [sqlite3_free()]7773** prior to assigning a new string to zErrMsg.  ^After the error message7774** is delivered up to the client application, the string will be automatically7775** freed by sqlite3_free() and the zErrMsg field will be zeroed.7776*/7777struct sqlite3_vtab {7778  const sqlite3_module *pModule;  /* The module for this virtual table */7779  int nRef;                       /* Number of open cursors */7780  char *zErrMsg;                  /* Error message from sqlite3_mprintf() */7781  /* Virtual table implementations will typically add additional fields */7782};77837784/*7785** CAPI3REF: Virtual Table Cursor Object7786** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor}7787**7788** Every [virtual table module] implementation uses a subclass of the7789** following structure to describe cursors that point into the7790** [virtual table] and are used7791** to loop through the virtual table.  Cursors are created using the7792** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed7793** by the [sqlite3_module.xClose | xClose] method.  Cursors are used7794** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods7795** of the module.  Each module implementation will define7796** the content of a cursor structure to suit its own needs.7797**7798** This superclass exists in order to define fields of the cursor that7799** are common to all implementations.7800*/7801struct sqlite3_vtab_cursor {7802  sqlite3_vtab *pVtab;      /* Virtual table of this cursor */7803  /* Virtual table implementations will typically add additional fields */7804};78057806/*7807** CAPI3REF: Declare The Schema Of A Virtual Table7808**7809** ^The [xCreate] and [xConnect] methods of a7810** [virtual table module] call this interface7811** to declare the format (the names and datatypes of the columns) of7812** the virtual tables they implement.7813*/7814SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL);78157816/*7817** CAPI3REF: Overload A Function For A Virtual Table7818** METHOD: sqlite37819**7820** ^(Virtual tables can provide alternative implementations of functions7821** using the [xFindFunction] method of the [virtual table module].7822** But global versions of those functions7823** must exist in order to be overloaded.)^7824**7825** ^(This API makes sure a global version of a function with a particular7826** name and number of parameters exists.  If no such function exists7827** before this API is called, a new function is created.)^  ^The implementation7828** of the new function always causes an exception to be thrown.  So7829** the new function is not good for anything by itself.  Its only7830** purpose is to be a placeholder function that can be overloaded7831** by a [virtual table].7832*/7833SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);78347835/*7836** CAPI3REF: A Handle To An Open BLOB7837** KEYWORDS: {BLOB handle} {BLOB handles}7838**7839** An instance of this object represents an open BLOB on which7840** [sqlite3_blob_open | incremental BLOB I/O] can be performed.7841** ^Objects of this type are created by [sqlite3_blob_open()]7842** and destroyed by [sqlite3_blob_close()].7843** ^The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces7844** can be used to read or write small subsections of the BLOB.7845** ^The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes.7846*/7847typedef struct sqlite3_blob sqlite3_blob;78487849/*7850** CAPI3REF: Open A BLOB For Incremental I/O7851** METHOD: sqlite37852** CONSTRUCTOR: sqlite3_blob7853**7854** ^(This interfaces opens a [BLOB handle | handle] to the BLOB located7855** in row iRow, column zColumn, table zTable in database zDb;7856** in other words, the same BLOB that would be selected by:7857**7858** <pre>7859**     SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow;7860** </pre>)^7861**7862** ^(Parameter zDb is not the filename that contains the database, but7863** rather the symbolic name of the database. For attached databases, this is7864** the name that appears after the AS keyword in the [ATTACH] statement.7865** For the main database file, the database name is "main". For TEMP7866** tables, the database name is "temp".)^7867**7868** ^If the flags parameter is non-zero, then the BLOB is opened for read7869** and write access. ^If the flags parameter is zero, the BLOB is opened for7870** read-only access.7871**7872** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is stored7873** in *ppBlob. Otherwise an [error code] is returned and, unless the error7874** code is SQLITE_MISUSE, *ppBlob is set to NULL.)^ ^This means that, provided7875** the API is not misused, it is always safe to call [sqlite3_blob_close()]7876** on *ppBlob after this function it returns.7877**7878** This function fails with SQLITE_ERROR if any of the following are true:7879** <ul>7880**   <li> ^(Database zDb does not exist)^,7881**   <li> ^(Table zTable does not exist within database zDb)^,7882**   <li> ^(Table zTable is a WITHOUT ROWID table)^,7883**   <li> ^(Column zColumn does not exist)^,7884**   <li> ^(Row iRow is not present in the table)^,7885**   <li> ^(The specified column of row iRow contains a value that is not7886**         a TEXT or BLOB value)^,7887**   <li> ^(Column zColumn is part of an index, PRIMARY KEY or UNIQUE7888**         constraint and the blob is being opened for read/write access)^,7889**   <li> ^([foreign key constraints | Foreign key constraints] are enabled,7890**         column zColumn is part of a [child key] definition and the blob is7891**         being opened for read/write access)^.7892** </ul>7893**7894** ^Unless it returns SQLITE_MISUSE, this function sets the7895** [database connection] error code and message accessible via7896** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.7897**7898** A BLOB referenced by sqlite3_blob_open() may be read using the7899** [sqlite3_blob_read()] interface and modified by using7900** [sqlite3_blob_write()].  The [BLOB handle] can be moved to a7901** different row of the same table using the [sqlite3_blob_reopen()]7902** interface.  However, the column, table, or database of a [BLOB handle]7903** cannot be changed after the [BLOB handle] is opened.7904**7905** ^(If the row that a BLOB handle points to is modified by an7906** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects7907** then the BLOB handle is marked as "expired".7908** This is true if any column of the row is changed, even a column7909** other than the one the BLOB handle is open on.)^7910** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for7911** an expired BLOB handle fail with a return code of [SQLITE_ABORT].7912** ^(Changes written into a BLOB prior to the BLOB expiring are not7913** rolled back by the expiration of the BLOB.  Such changes will eventually7914** commit if the transaction continues to completion.)^7915**7916** ^Use the [sqlite3_blob_bytes()] interface to determine the size of7917** the opened blob.  ^The size of a blob may not be changed by this7918** interface.  Use the [UPDATE] SQL command to change the size of a7919** blob.7920**7921** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces7922** and the built-in [zeroblob] SQL function may be used to create a7923** zero-filled blob to read or write using the incremental-blob interface.7924**7925** To avoid a resource leak, every open [BLOB handle] should eventually7926** be released by a call to [sqlite3_blob_close()].7927**7928** See also: [sqlite3_blob_close()],7929** [sqlite3_blob_reopen()], [sqlite3_blob_read()],7930** [sqlite3_blob_bytes()], [sqlite3_blob_write()].7931*/7932SQLITE_API int sqlite3_blob_open(7933  sqlite3*,7934  const char *zDb,7935  const char *zTable,7936  const char *zColumn,7937  sqlite3_int64 iRow,7938  int flags,7939  sqlite3_blob **ppBlob7940);79417942/*7943** CAPI3REF: Move a BLOB Handle to a New Row7944** METHOD: sqlite3_blob7945**7946** ^This function is used to move an existing [BLOB handle] so that it points7947** to a different row of the same database table. ^The new row is identified7948** by the rowid value passed as the second argument. Only the row can be7949** changed. ^The database, table and column on which the blob handle is open7950** remain the same. Moving an existing [BLOB handle] to a new row is7951** faster than closing the existing handle and opening a new one.7952**7953** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] -7954** it must exist and there must be either a blob or text value stored in7955** the nominated column.)^ ^If the new row is not present in the table, or if7956** it does not contain a blob or text value, or if another error occurs, an7957** SQLite error code is returned and the blob handle is considered aborted.7958** ^All subsequent calls to [sqlite3_blob_read()], [sqlite3_blob_write()] or7959** [sqlite3_blob_reopen()] on an aborted blob handle immediately return7960** SQLITE_ABORT. ^Calling [sqlite3_blob_bytes()] on an aborted blob handle7961** always returns zero.7962**7963** ^This function sets the database handle error code and message.7964*/7965SQLITE_API int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);79667967/*7968** CAPI3REF: Close A BLOB Handle7969** DESTRUCTOR: sqlite3_blob7970**7971** ^This function closes an open [BLOB handle]. ^(The BLOB handle is closed7972** unconditionally.  Even if this routine returns an error code, the7973** handle is still closed.)^7974**7975** ^If the blob handle being closed was opened for read-write access, and if7976** the database is in auto-commit mode and there are no other open read-write7977** blob handles or active write statements, the current transaction is7978** committed. ^If an error occurs while committing the transaction, an error7979** code is returned and the transaction rolled back.7980**7981** Calling this function with an argument that is not a NULL pointer or an7982** open blob handle results in undefined behavior. ^Calling this routine7983** with a null pointer (such as would be returned by a failed call to7984** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function7985** is passed a valid open blob handle, the values returned by the7986** sqlite3_errcode() and sqlite3_errmsg() functions are set before returning.7987*/7988SQLITE_API int sqlite3_blob_close(sqlite3_blob *);79897990/*7991** CAPI3REF: Return The Size Of An Open BLOB7992** METHOD: sqlite3_blob7993**7994** ^Returns the size in bytes of the BLOB accessible via the7995** successfully opened [BLOB handle] in its only argument.  ^The7996** incremental blob I/O routines can only read or overwriting existing7997** blob content; they cannot change the size of a blob.7998**7999** This routine only works on a [BLOB handle] which has been created8000** by a prior successful call to [sqlite3_blob_open()] and which has not8001** been closed by [sqlite3_blob_close()].  Passing any other pointer in8002** to this routine results in undefined and probably undesirable behavior.8003*/8004SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *);80058006/*8007** CAPI3REF: Read Data From A BLOB Incrementally8008** METHOD: sqlite3_blob8009**8010** ^(This function is used to read data from an open [BLOB handle] into a8011** caller-supplied buffer. N bytes of data are copied into buffer Z8012** from the open BLOB, starting at offset iOffset.)^8013**8014** ^If offset iOffset is less than N bytes from the end of the BLOB,8015** [SQLITE_ERROR] is returned and no data is read.  ^If N or iOffset is8016** less than zero, [SQLITE_ERROR] is returned and no data is read.8017** ^The size of the blob (and hence the maximum value of N+iOffset)8018** can be determined using the [sqlite3_blob_bytes()] interface.8019**8020** ^An attempt to read from an expired [BLOB handle] fails with an8021** error code of [SQLITE_ABORT].8022**8023** ^(On success, sqlite3_blob_read() returns SQLITE_OK.8024** Otherwise, an [error code] or an [extended error code] is returned.)^8025**8026** This routine only works on a [BLOB handle] which has been created8027** by a prior successful call to [sqlite3_blob_open()] and which has not8028** been closed by [sqlite3_blob_close()].  Passing any other pointer in8029** to this routine results in undefined and probably undesirable behavior.8030**8031** See also: [sqlite3_blob_write()].8032*/8033SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);80348035/*8036** CAPI3REF: Write Data Into A BLOB Incrementally8037** METHOD: sqlite3_blob8038**8039** ^(This function is used to write data into an open [BLOB handle] from a8040** caller-supplied buffer. N bytes of data are copied from the buffer Z8041** into the open BLOB, starting at offset iOffset.)^8042**8043** ^(On success, sqlite3_blob_write() returns SQLITE_OK.8044** Otherwise, an  [error code] or an [extended error code] is returned.)^8045** ^Unless SQLITE_MISUSE is returned, this function sets the8046** [database connection] error code and message accessible via8047** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.8048**8049** ^If the [BLOB handle] passed as the first argument was not opened for8050** writing (the flags parameter to [sqlite3_blob_open()] was zero),8051** this function returns [SQLITE_READONLY].8052**8053** This function may only modify the contents of the BLOB; it is8054** not possible to increase the size of a BLOB using this API.8055** ^If offset iOffset is less than N bytes from the end of the BLOB,8056** [SQLITE_ERROR] is returned and no data is written. The size of the8057** BLOB (and hence the maximum value of N+iOffset) can be determined8058** using the [sqlite3_blob_bytes()] interface. ^If N or iOffset are less8059** than zero [SQLITE_ERROR] is returned and no data is written.8060**8061** ^An attempt to write to an expired [BLOB handle] fails with an8062** error code of [SQLITE_ABORT].  ^Writes to the BLOB that occurred8063** before the [BLOB handle] expired are not rolled back by the8064** expiration of the handle, though of course those changes might8065** have been overwritten by the statement that expired the BLOB handle8066** or by other independent statements.8067**8068** This routine only works on a [BLOB handle] which has been created8069** by a prior successful call to [sqlite3_blob_open()] and which has not8070** been closed by [sqlite3_blob_close()].  Passing any other pointer in8071** to this routine results in undefined and probably undesirable behavior.8072**8073** See also: [sqlite3_blob_read()].8074*/8075SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);80768077/*8078** CAPI3REF: Virtual File System Objects8079**8080** A virtual filesystem (VFS) is an [sqlite3_vfs] object8081** that SQLite uses to interact8082** with the underlying operating system.  Most SQLite builds come with a8083** single default VFS that is appropriate for the host computer.8084** New VFSes can be registered and existing VFSes can be unregistered.8085** The following interfaces are provided.8086**8087** ^The sqlite3_vfs_find() interface returns a pointer to a VFS given its name.8088** ^Names are case sensitive.8089** ^Names are zero-terminated UTF-8 strings.8090** ^If there is no match, a NULL pointer is returned.8091** ^If zVfsName is NULL then the default VFS is returned.8092**8093** ^New VFSes are registered with sqlite3_vfs_register().8094** ^Each new VFS becomes the default VFS if the makeDflt flag is set.8095** ^The same VFS can be registered multiple times without injury.8096** ^To make an existing VFS into the default VFS, register it again8097** with the makeDflt flag set.  If two different VFSes with the8098** same name are registered, the behavior is undefined.  If a8099** VFS is registered with a name that is NULL or an empty string,8100** then the behavior is undefined.8101**8102** ^Unregister a VFS with the sqlite3_vfs_unregister() interface.8103** ^(If the default VFS is unregistered, another VFS is chosen as8104** the default.  The choice for the new VFS is arbitrary.)^8105*/8106SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);8107SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);8108SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);81098110/*8111** CAPI3REF: Mutexes8112**8113** The SQLite core uses these routines for thread8114** synchronization. Though they are intended for internal8115** use by SQLite, code that links against SQLite is8116** permitted to use any of these routines.8117**8118** The SQLite source code contains multiple implementations8119** of these mutex routines.  An appropriate implementation8120** is selected automatically at compile-time.  The following8121** implementations are available in the SQLite core:8122**8123** <ul>8124** <li>   SQLITE_MUTEX_PTHREADS8125** <li>   SQLITE_MUTEX_W328126** <li>   SQLITE_MUTEX_NOOP8127** </ul>8128**8129** The SQLITE_MUTEX_NOOP implementation is a set of routines8130** that does no real locking and is appropriate for use in8131** a single-threaded application.  The SQLITE_MUTEX_PTHREADS and8132** SQLITE_MUTEX_W32 implementations are appropriate for use on Unix8133** and Windows.8134**8135** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor8136** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex8137** implementation is included with the library. In this case the8138** application must supply a custom mutex implementation using the8139** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function8140** before calling sqlite3_initialize() or any other public sqlite3_8141** function that calls sqlite3_initialize().8142**8143** ^The sqlite3_mutex_alloc() routine allocates a new8144** mutex and returns a pointer to it. ^The sqlite3_mutex_alloc()8145** routine returns NULL if it is unable to allocate the requested8146** mutex.  The argument to sqlite3_mutex_alloc() must one of these8147** integer constants:8148**8149** <ul>8150** <li>  SQLITE_MUTEX_FAST8151** <li>  SQLITE_MUTEX_RECURSIVE8152** <li>  SQLITE_MUTEX_STATIC_MAIN8153** <li>  SQLITE_MUTEX_STATIC_MEM8154** <li>  SQLITE_MUTEX_STATIC_OPEN8155** <li>  SQLITE_MUTEX_STATIC_PRNG8156** <li>  SQLITE_MUTEX_STATIC_LRU8157** <li>  SQLITE_MUTEX_STATIC_PMEM8158** <li>  SQLITE_MUTEX_STATIC_APP18159** <li>  SQLITE_MUTEX_STATIC_APP28160** <li>  SQLITE_MUTEX_STATIC_APP38161** <li>  SQLITE_MUTEX_STATIC_VFS18162** <li>  SQLITE_MUTEX_STATIC_VFS28163** <li>  SQLITE_MUTEX_STATIC_VFS38164** </ul>8165**8166** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)8167** cause sqlite3_mutex_alloc() to create8168** a new mutex.  ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE8169** is used but not necessarily so when SQLITE_MUTEX_FAST is used.8170** The mutex implementation does not need to make a distinction8171** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does8172** not want to.  SQLite will only request a recursive mutex in8173** cases where it really needs one.  If a faster non-recursive mutex8174** implementation is available on the host platform, the mutex subsystem8175** might return such a mutex in response to SQLITE_MUTEX_FAST.8176**8177** ^The other allowed parameters to sqlite3_mutex_alloc() (anything other8178** than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return8179** a pointer to a static preexisting mutex.  ^Nine static mutexes are8180** used by the current version of SQLite.  Future versions of SQLite8181** may add additional static mutexes.  Static mutexes are for internal8182** use by SQLite only.  Applications that use SQLite mutexes should8183** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or8184** SQLITE_MUTEX_RECURSIVE.8185**8186** ^Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST8187** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()8188** returns a different mutex on every call.  ^For the static8189** mutex types, the same mutex is returned on every call that has8190** the same type number.8191**8192** ^The sqlite3_mutex_free() routine deallocates a previously8193** allocated dynamic mutex.  Attempting to deallocate a static8194** mutex results in undefined behavior.8195**8196** ^The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt8197** to enter a mutex.  ^If another thread is already within the mutex,8198** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return8199** SQLITE_BUSY.  ^The sqlite3_mutex_try() interface returns [SQLITE_OK]8200** upon successful entry.  ^(Mutexes created using8201** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.8202** In such cases, the8203** mutex must be exited an equal number of times before another thread8204** can enter.)^  If the same thread tries to enter any mutex other8205** than an SQLITE_MUTEX_RECURSIVE more than once, the behavior is undefined.8206**8207** ^(Some systems (for example, Windows 95) do not support the operation8208** implemented by sqlite3_mutex_try().  On those systems, sqlite3_mutex_try()8209** will always return SQLITE_BUSY. In most cases the SQLite core only uses8210** sqlite3_mutex_try() as an optimization, so this is acceptable8211** behavior. The exceptions are unix builds that set the8212** SQLITE_ENABLE_SETLK_TIMEOUT build option. In that case a working8213** sqlite3_mutex_try() is required.)^8214**8215** ^The sqlite3_mutex_leave() routine exits a mutex that was8216** previously entered by the same thread.   The behavior8217** is undefined if the mutex is not currently entered by the8218** calling thread or is not currently allocated.8219**8220** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(),8221** sqlite3_mutex_leave(), or sqlite3_mutex_free() is a NULL pointer,8222** then any of the four routines behaves as a no-op.8223**8224** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].8225*/8226SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int);8227SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*);8228SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*);8229SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*);8230SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);82318232/*8233** CAPI3REF: Mutex Methods Object8234**8235** An instance of this structure defines the low-level routines8236** used to allocate and use mutexes.8237**8238** Usually, the default mutex implementations provided by SQLite are8239** sufficient, however the application has the option of substituting a custom8240** implementation for specialized deployments or systems for which SQLite8241** does not provide a suitable implementation. In this case, the application8242** creates and populates an instance of this structure to pass8243** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option.8244** Additionally, an instance of this structure can be used as an8245** output variable when querying the system for the current mutex8246** implementation, using the [SQLITE_CONFIG_GETMUTEX] option.8247**8248** ^The xMutexInit method defined by this structure is invoked as8249** part of system initialization by the sqlite3_initialize() function.8250** ^The xMutexInit routine is called by SQLite exactly once for each8251** effective call to [sqlite3_initialize()].8252**8253** ^The xMutexEnd method defined by this structure is invoked as8254** part of system shutdown by the sqlite3_shutdown() function. The8255** implementation of this method is expected to release all outstanding8256** resources obtained by the mutex methods implementation, especially8257** those obtained by the xMutexInit method.  ^The xMutexEnd()8258** interface is invoked exactly once for each call to [sqlite3_shutdown()].8259**8260** ^(The remaining seven methods defined by this structure (xMutexAlloc,8261** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and8262** xMutexNotheld) implement the following interfaces (respectively):8263**8264** <ul>8265**   <li>  [sqlite3_mutex_alloc()] </li>8266**   <li>  [sqlite3_mutex_free()] </li>8267**   <li>  [sqlite3_mutex_enter()] </li>8268**   <li>  [sqlite3_mutex_try()] </li>8269**   <li>  [sqlite3_mutex_leave()] </li>8270**   <li>  [sqlite3_mutex_held()] </li>8271**   <li>  [sqlite3_mutex_notheld()] </li>8272** </ul>)^8273**8274** The only difference is that the public sqlite3_XXX functions enumerated8275** above silently ignore any invocations that pass a NULL pointer instead8276** of a valid mutex handle. The implementations of the methods defined8277** by this structure are not required to handle this case. The results8278** of passing a NULL pointer instead of a valid mutex handle are undefined8279** (i.e. it is acceptable to provide an implementation that segfaults if8280** it is passed a NULL pointer).8281**8282** The xMutexInit() method must be threadsafe.  It must be harmless to8283** invoke xMutexInit() multiple times within the same process and without8284** intervening calls to xMutexEnd().  Second and subsequent calls to8285** xMutexInit() must be no-ops.8286**8287** xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]8288** and its associates).  Similarly, xMutexAlloc() must not use SQLite memory8289** allocation for a static mutex.  ^However xMutexAlloc() may use SQLite8290** memory allocation for a fast or recursive mutex.8291**8292** ^SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is8293** called, but only if the prior call to xMutexInit returned SQLITE_OK.8294** If xMutexInit fails in any way, it is expected to clean up after itself8295** prior to returning.8296*/8297typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;8298struct sqlite3_mutex_methods {8299  int (*xMutexInit)(void);8300  int (*xMutexEnd)(void);8301  sqlite3_mutex *(*xMutexAlloc)(int);8302  void (*xMutexFree)(sqlite3_mutex *);8303  void (*xMutexEnter)(sqlite3_mutex *);8304  int (*xMutexTry)(sqlite3_mutex *);8305  void (*xMutexLeave)(sqlite3_mutex *);8306  int (*xMutexHeld)(sqlite3_mutex *);8307  int (*xMutexNotheld)(sqlite3_mutex *);8308};83098310/*8311** CAPI3REF: Mutex Verification Routines8312**8313** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines8314** are intended for use inside assert() statements.  The SQLite core8315** never uses these routines except inside an assert() and applications8316** are advised to follow the lead of the core.  The SQLite core only8317** provides implementations for these routines when it is compiled8318** with the SQLITE_DEBUG flag.  External mutex implementations8319** are only required to provide these routines if SQLITE_DEBUG is8320** defined and if NDEBUG is not defined.8321**8322** These routines should return true if the mutex in their argument8323** is held or not held, respectively, by the calling thread.8324**8325** The implementation is not required to provide versions of these8326** routines that actually work. If the implementation does not provide working8327** versions of these routines, it should at least provide stubs that always8328** return true so that one does not get spurious assertion failures.8329**8330** If the argument to sqlite3_mutex_held() is a NULL pointer then8331** the routine should return 1.   This seems counter-intuitive since8332** clearly the mutex cannot be held if it does not exist.  But8333** the reason the mutex does not exist is because the build is not8334** using mutexes.  And we do not want the assert() containing the8335** call to sqlite3_mutex_held() to fail, so a non-zero return is8336** the appropriate thing to do.  The sqlite3_mutex_notheld()8337** interface should also return 1 when given a NULL pointer.8338*/8339#ifndef NDEBUG8340SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*);8341SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*);8342#endif83438344/*8345** CAPI3REF: Mutex Types8346**8347** The [sqlite3_mutex_alloc()] interface takes a single argument8348** which is one of these integer constants.8349**8350** The set of static mutexes may change from one SQLite release to the8351** next.  Applications that override the built-in mutex logic must be8352** prepared to accommodate additional static mutexes.8353*/8354#define SQLITE_MUTEX_FAST             08355#define SQLITE_MUTEX_RECURSIVE        18356#define SQLITE_MUTEX_STATIC_MAIN      28357#define SQLITE_MUTEX_STATIC_MEM       3  /* sqlite3_malloc() */8358#define SQLITE_MUTEX_STATIC_MEM2      4  /* NOT USED */8359#define SQLITE_MUTEX_STATIC_OPEN      4  /* sqlite3BtreeOpen() */8360#define SQLITE_MUTEX_STATIC_PRNG      5  /* sqlite3_randomness() */8361#define SQLITE_MUTEX_STATIC_LRU       6  /* lru page list */8362#define SQLITE_MUTEX_STATIC_LRU2      7  /* NOT USED */8363#define SQLITE_MUTEX_STATIC_PMEM      7  /* sqlite3PageMalloc() */8364#define SQLITE_MUTEX_STATIC_APP1      8  /* For use by application */8365#define SQLITE_MUTEX_STATIC_APP2      9  /* For use by application */8366#define SQLITE_MUTEX_STATIC_APP3     10  /* For use by application */8367#define SQLITE_MUTEX_STATIC_VFS1     11  /* For use by built-in VFS */8368#define SQLITE_MUTEX_STATIC_VFS2     12  /* For use by extension VFS */8369#define SQLITE_MUTEX_STATIC_VFS3     13  /* For use by application VFS */83708371/* Legacy compatibility: */8372#define SQLITE_MUTEX_STATIC_MASTER    2837383748375/*8376** CAPI3REF: Retrieve the mutex for a database connection8377** METHOD: sqlite38378**8379** ^This interface returns a pointer the [sqlite3_mutex] object that8380** serializes access to the [database connection] given in the argument8381** when the [threading mode] is Serialized.8382** ^If the [threading mode] is Single-thread or Multi-thread then this8383** routine returns a NULL pointer.8384*/8385SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);83868387/*8388** CAPI3REF: Low-Level Control Of Database Files8389** METHOD: sqlite38390** KEYWORDS: {file control}8391**8392** ^The [sqlite3_file_control()] interface makes a direct call to the8393** xFileControl method for the [sqlite3_io_methods] object associated8394** with a particular database identified by the second argument. ^The8395** name of the database is "main" for the main database or "temp" for the8396** TEMP database, or the name that appears after the AS keyword for8397** databases that are added using the [ATTACH] SQL command.8398** ^A NULL pointer can be used in place of "main" to refer to the8399** main database file.8400** ^The third and fourth parameters to this routine8401** are passed directly through to the second and third parameters of8402** the xFileControl method.  ^The return value of the xFileControl8403** method becomes the return value of this routine.8404**8405** A few opcodes for [sqlite3_file_control()] are handled directly8406** by the SQLite core and never invoke the8407** sqlite3_io_methods.xFileControl method.8408** ^The [SQLITE_FCNTL_FILE_POINTER] value for the op parameter causes8409** a pointer to the underlying [sqlite3_file] object to be written into8410** the space pointed to by the 4th parameter.  The8411** [SQLITE_FCNTL_JOURNAL_POINTER] works similarly except that it returns8412** the [sqlite3_file] object associated with the journal file instead of8413** the main database.  The [SQLITE_FCNTL_VFS_POINTER] opcode returns8414** a pointer to the underlying [sqlite3_vfs] object for the file.8415** The [SQLITE_FCNTL_DATA_VERSION] returns the data version counter8416** from the pager.8417**8418** ^If the second parameter (zDbName) does not match the name of any8419** open database file, then SQLITE_ERROR is returned.  ^This error8420** code is not remembered and will not be recalled by [sqlite3_errcode()]8421** or [sqlite3_errmsg()].  The underlying xFileControl method might8422** also return SQLITE_ERROR.  There is no way to distinguish between8423** an incorrect zDbName and an SQLITE_ERROR return from the underlying8424** xFileControl method.8425**8426** See also: [file control opcodes]8427*/8428SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);84298430/*8431** CAPI3REF: Testing Interface8432**8433** ^The sqlite3_test_control() interface is used to read out internal8434** state of SQLite and to inject faults into SQLite for testing8435** purposes.  ^The first parameter is an operation code that determines8436** the number, meaning, and operation of all subsequent parameters.8437**8438** This interface is not for use by applications.  It exists solely8439** for verifying the correct operation of the SQLite library.  Depending8440** on how the SQLite library is compiled, this interface might not exist.8441**8442** The details of the operation codes, their meanings, the parameters8443** they take, and what they do are all subject to change without notice.8444** Unlike most of the SQLite API, this function is not guaranteed to8445** operate consistently from one release to the next.8446*/8447SQLITE_API int sqlite3_test_control(int op, ...);84488449/*8450** CAPI3REF: Testing Interface Operation Codes8451**8452** These constants are the valid operation code parameters used8453** as the first argument to [sqlite3_test_control()].8454**8455** These parameters and their meanings are subject to change8456** without notice.  These values are for testing purposes only.8457** Applications should not use any of these parameters or the8458** [sqlite3_test_control()] interface.8459*/8460#define SQLITE_TESTCTRL_FIRST                    58461#define SQLITE_TESTCTRL_PRNG_SAVE                58462#define SQLITE_TESTCTRL_PRNG_RESTORE             68463#define SQLITE_TESTCTRL_PRNG_RESET               7  /* NOT USED */8464#define SQLITE_TESTCTRL_FK_NO_ACTION             78465#define SQLITE_TESTCTRL_BITVEC_TEST              88466#define SQLITE_TESTCTRL_FAULT_INSTALL            98467#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS     108468#define SQLITE_TESTCTRL_PENDING_BYTE            118469#define SQLITE_TESTCTRL_ASSERT                  128470#define SQLITE_TESTCTRL_ALWAYS                  138471#define SQLITE_TESTCTRL_RESERVE                 14  /* NOT USED */8472#define SQLITE_TESTCTRL_JSON_SELFCHECK          148473#define SQLITE_TESTCTRL_OPTIMIZATIONS           158474#define SQLITE_TESTCTRL_ISKEYWORD               16  /* NOT USED */8475#define SQLITE_TESTCTRL_GETOPT                  168476#define SQLITE_TESTCTRL_SCRATCHMALLOC           17  /* NOT USED */8477#define SQLITE_TESTCTRL_INTERNAL_FUNCTIONS      178478#define SQLITE_TESTCTRL_LOCALTIME_FAULT         188479#define SQLITE_TESTCTRL_EXPLAIN_STMT            19  /* NOT USED */8480#define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD    198481#define SQLITE_TESTCTRL_NEVER_CORRUPT           208482#define SQLITE_TESTCTRL_VDBE_COVERAGE           218483#define SQLITE_TESTCTRL_BYTEORDER               228484#define SQLITE_TESTCTRL_ISINIT                  238485#define SQLITE_TESTCTRL_SORTER_MMAP             248486#define SQLITE_TESTCTRL_IMPOSTER                258487#define SQLITE_TESTCTRL_PARSER_COVERAGE         268488#define SQLITE_TESTCTRL_RESULT_INTREAL          278489#define SQLITE_TESTCTRL_PRNG_SEED               288490#define SQLITE_TESTCTRL_EXTRA_SCHEMA_CHECKS     298491#define SQLITE_TESTCTRL_SEEK_COUNT              308492#define SQLITE_TESTCTRL_TRACEFLAGS              318493#define SQLITE_TESTCTRL_TUNE                    328494#define SQLITE_TESTCTRL_LOGEST                  338495#define SQLITE_TESTCTRL_USELONGDOUBLE           34  /* NOT USED */8496#define SQLITE_TESTCTRL_LAST                    34  /* Largest TESTCTRL */84978498/*8499** CAPI3REF: SQL Keyword Checking8500**8501** These routines provide access to the set of SQL language keywords8502** recognized by SQLite.  Applications can uses these routines to determine8503** whether or not a specific identifier needs to be escaped (for example,8504** by enclosing in double-quotes) so as not to confuse the parser.8505**8506** The sqlite3_keyword_count() interface returns the number of distinct8507** keywords understood by SQLite.8508**8509** The sqlite3_keyword_name(N,Z,L) interface finds the 0-based N-th keyword and8510** makes *Z point to that keyword expressed as UTF8 and writes the number8511** of bytes in the keyword into *L.  The string that *Z points to is not8512** zero-terminated.  The sqlite3_keyword_name(N,Z,L) routine returns8513** SQLITE_OK if N is within bounds and SQLITE_ERROR if not. If either Z8514** or L are NULL or invalid pointers then calls to8515** sqlite3_keyword_name(N,Z,L) result in undefined behavior.8516**8517** The sqlite3_keyword_check(Z,L) interface checks to see whether or not8518** the L-byte UTF8 identifier that Z points to is a keyword, returning non-zero8519** if it is and zero if not.8520**8521** The parser used by SQLite is forgiving.  It is often possible to use8522** a keyword as an identifier as long as such use does not result in a8523** parsing ambiguity.  For example, the statement8524** "CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" is accepted by SQLite, and8525** creates a new table named "BEGIN" with three columns named8526** "REPLACE", "PRAGMA", and "END".  Nevertheless, best practice is to avoid8527** using keywords as identifiers.  Common techniques used to avoid keyword8528** name collisions include:8529** <ul>8530** <li> Put all identifier names inside double-quotes.  This is the official8531**      SQL way to escape identifier names.8532** <li> Put identifier names inside &#91;...&#93;.  This is not standard SQL,8533**      but it is what SQL Server does and so lots of programmers use this8534**      technique.8535** <li> Begin every identifier with the letter "Z" as no SQL keywords start8536**      with "Z".8537** <li> Include a digit somewhere in every identifier name.8538** </ul>8539**8540** Note that the number of keywords understood by SQLite can depend on8541** compile-time options.  For example, "VACUUM" is not a keyword if8542** SQLite is compiled with the [-DSQLITE_OMIT_VACUUM] option.  Also,8543** new keywords may be added to future releases of SQLite.8544*/8545SQLITE_API int sqlite3_keyword_count(void);8546SQLITE_API int sqlite3_keyword_name(int,const char**,int*);8547SQLITE_API int sqlite3_keyword_check(const char*,int);85488549/*8550** CAPI3REF: Dynamic String Object8551** KEYWORDS: {dynamic string}8552**8553** An instance of the sqlite3_str object contains a dynamically-sized8554** string under construction.8555**8556** The lifecycle of an sqlite3_str object is as follows:8557** <ol>8558** <li> ^The sqlite3_str object is created using [sqlite3_str_new()].8559** <li> ^Text is appended to the sqlite3_str object using various8560** methods, such as [sqlite3_str_appendf()].8561** <li> ^The sqlite3_str object is destroyed and the string it created8562** is returned using the [sqlite3_str_finish()] interface.8563** </ol>8564*/8565typedef struct sqlite3_str sqlite3_str;85668567/*8568** CAPI3REF: Create A New Dynamic String Object8569** CONSTRUCTOR: sqlite3_str8570**8571** ^The [sqlite3_str_new(D)] interface allocates and initializes8572** a new [sqlite3_str] object.  To avoid memory leaks, the object returned by8573** [sqlite3_str_new()] must be freed by a subsequent call to8574** [sqlite3_str_finish(X)].8575**8576** ^The [sqlite3_str_new(D)] interface always returns a pointer to a8577** valid [sqlite3_str] object, though in the event of an out-of-memory8578** error the returned object might be a special singleton that will8579** silently reject new text, always return SQLITE_NOMEM from8580** [sqlite3_str_errcode()], always return 0 for8581** [sqlite3_str_length()], and always return NULL from8582** [sqlite3_str_finish(X)].  It is always safe to use the value8583** returned by [sqlite3_str_new(D)] as the sqlite3_str parameter8584** to any of the other [sqlite3_str] methods.8585**8586** The D parameter to [sqlite3_str_new(D)] may be NULL.  If the8587** D parameter in [sqlite3_str_new(D)] is not NULL, then the maximum8588** length of the string contained in the [sqlite3_str] object will be8589** the value set for [sqlite3_limit](D,[SQLITE_LIMIT_LENGTH]) instead8590** of [SQLITE_MAX_LENGTH].8591*/8592SQLITE_API sqlite3_str *sqlite3_str_new(sqlite3*);85938594/*8595** CAPI3REF: Finalize A Dynamic String8596** DESTRUCTOR: sqlite3_str8597**8598** ^The [sqlite3_str_finish(X)] interface destroys the sqlite3_str object X8599** and returns a pointer to a memory buffer obtained from [sqlite3_malloc64()]8600** that contains the constructed string.  The calling application should8601** pass the returned value to [sqlite3_free()] to avoid a memory leak.8602** ^The [sqlite3_str_finish(X)] interface may return a NULL pointer if any8603** errors were encountered during construction of the string.  ^The8604** [sqlite3_str_finish(X)] interface will also return a NULL pointer if the8605** string in [sqlite3_str] object X is zero bytes long.8606*/8607SQLITE_API char *sqlite3_str_finish(sqlite3_str*);86088609/*8610** CAPI3REF: Add Content To A Dynamic String8611** METHOD: sqlite3_str8612**8613** These interfaces add content to an sqlite3_str object previously obtained8614** from [sqlite3_str_new()].8615**8616** ^The [sqlite3_str_appendf(X,F,...)] and8617** [sqlite3_str_vappendf(X,F,V)] interfaces uses the [built-in printf]8618** functionality of SQLite to append formatted text onto the end of8619** [sqlite3_str] object X.8620**8621** ^The [sqlite3_str_append(X,S,N)] method appends exactly N bytes from string S8622** onto the end of the [sqlite3_str] object X.  N must be non-negative.8623** S must contain at least N non-zero bytes of content.  To append a8624** zero-terminated string in its entirety, use the [sqlite3_str_appendall()]8625** method instead.8626**8627** ^The [sqlite3_str_appendall(X,S)] method appends the complete content of8628** zero-terminated string S onto the end of [sqlite3_str] object X.8629**8630** ^The [sqlite3_str_appendchar(X,N,C)] method appends N copies of the8631** single-byte character C onto the end of [sqlite3_str] object X.8632** ^This method can be used, for example, to add whitespace indentation.8633**8634** ^The [sqlite3_str_reset(X)] method resets the string under construction8635** inside [sqlite3_str] object X back to zero bytes in length.8636**8637** These methods do not return a result code.  ^If an error occurs, that fact8638** is recorded in the [sqlite3_str] object and can be recovered by a8639** subsequent call to [sqlite3_str_errcode(X)].8640*/8641SQLITE_API void sqlite3_str_appendf(sqlite3_str*, const char *zFormat, ...);8642SQLITE_API void sqlite3_str_vappendf(sqlite3_str*, const char *zFormat, va_list);8643SQLITE_API void sqlite3_str_append(sqlite3_str*, const char *zIn, int N);8644SQLITE_API void sqlite3_str_appendall(sqlite3_str*, const char *zIn);8645SQLITE_API void sqlite3_str_appendchar(sqlite3_str*, int N, char C);8646SQLITE_API void sqlite3_str_reset(sqlite3_str*);86478648/*8649** CAPI3REF: Status Of A Dynamic String8650** METHOD: sqlite3_str8651**8652** These interfaces return the current status of an [sqlite3_str] object.8653**8654** ^If any prior errors have occurred while constructing the dynamic string8655** in sqlite3_str X, then the [sqlite3_str_errcode(X)] method will return8656** an appropriate error code.  ^The [sqlite3_str_errcode(X)] method returns8657** [SQLITE_NOMEM] following any out-of-memory error, or8658** [SQLITE_TOOBIG] if the size of the dynamic string exceeds8659** [SQLITE_MAX_LENGTH], or [SQLITE_OK] if there have been no errors.8660**8661** ^The [sqlite3_str_length(X)] method returns the current length, in bytes,8662** of the dynamic string under construction in [sqlite3_str] object X.8663** ^The length returned by [sqlite3_str_length(X)] does not include the8664** zero-termination byte.8665**8666** ^The [sqlite3_str_value(X)] method returns a pointer to the current8667** content of the dynamic string under construction in X.  The value8668** returned by [sqlite3_str_value(X)] is managed by the sqlite3_str object X8669** and might be freed or altered by any subsequent method on the same8670** [sqlite3_str] object.  Applications must not used the pointer returned8671** [sqlite3_str_value(X)] after any subsequent method call on the same8672** object.  ^Applications may change the content of the string returned8673** by [sqlite3_str_value(X)] as long as they do not write into any bytes8674** outside the range of 0 to [sqlite3_str_length(X)] and do not read or8675** write any byte after any subsequent sqlite3_str method call.8676*/8677SQLITE_API int sqlite3_str_errcode(sqlite3_str*);8678SQLITE_API int sqlite3_str_length(sqlite3_str*);8679SQLITE_API char *sqlite3_str_value(sqlite3_str*);86808681/*8682** CAPI3REF: SQLite Runtime Status8683**8684** ^These interfaces are used to retrieve runtime status information8685** about the performance of SQLite, and optionally to reset various8686** highwater marks.  ^The first argument is an integer code for8687** the specific parameter to measure.  ^(Recognized integer codes8688** are of the form [status parameters | SQLITE_STATUS_...].)^8689** ^The current value of the parameter is returned into *pCurrent.8690** ^The highest recorded value is returned in *pHighwater.  ^If the8691** resetFlag is true, then the highest record value is reset after8692** *pHighwater is written.  ^(Some parameters do not record the highest8693** value.  For those parameters8694** nothing is written into *pHighwater and the resetFlag is ignored.)^8695** ^(Other parameters record only the highwater mark and not the current8696** value.  For these latter parameters nothing is written into *pCurrent.)^8697**8698** ^The sqlite3_status() and sqlite3_status64() routines return8699** SQLITE_OK on success and a non-zero [error code] on failure.8700**8701** If either the current value or the highwater mark is too large to8702** be represented by a 32-bit integer, then the values returned by8703** sqlite3_status() are undefined.8704**8705** See also: [sqlite3_db_status()]8706*/8707SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);8708SQLITE_API int sqlite3_status64(8709  int op,8710  sqlite3_int64 *pCurrent,8711  sqlite3_int64 *pHighwater,8712  int resetFlag8713);871487158716/*8717** CAPI3REF: Status Parameters8718** KEYWORDS: {status parameters}8719**8720** These integer constants designate various run-time status parameters8721** that can be returned by [sqlite3_status()].8722**8723** <dl>8724** [[SQLITE_STATUS_MEMORY_USED]] ^(<dt>SQLITE_STATUS_MEMORY_USED</dt>8725** <dd>This parameter is the current amount of memory checked out8726** using [sqlite3_malloc()], either directly or indirectly.  The8727** figure includes calls made to [sqlite3_malloc()] by the application8728** and internal memory usage by the SQLite library.  Auxiliary page-cache8729** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in8730** this parameter.  The amount returned is the sum of the allocation8731** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^8732**8733** [[SQLITE_STATUS_MALLOC_SIZE]] ^(<dt>SQLITE_STATUS_MALLOC_SIZE</dt>8734** <dd>This parameter records the largest memory allocation request8735** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their8736** internal equivalents).  Only the value returned in the8737** *pHighwater parameter to [sqlite3_status()] is of interest.8738** The value written into the *pCurrent parameter is undefined.</dd>)^8739**8740** [[SQLITE_STATUS_MALLOC_COUNT]] ^(<dt>SQLITE_STATUS_MALLOC_COUNT</dt>8741** <dd>This parameter records the number of separate memory allocations8742** currently checked out.</dd>)^8743**8744** [[SQLITE_STATUS_PAGECACHE_USED]] ^(<dt>SQLITE_STATUS_PAGECACHE_USED</dt>8745** <dd>This parameter returns the number of pages used out of the8746** [pagecache memory allocator] that was configured using8747** [SQLITE_CONFIG_PAGECACHE].  The8748** value returned is in pages, not in bytes.</dd>)^8749**8750** [[SQLITE_STATUS_PAGECACHE_OVERFLOW]]8751** ^(<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>8752** <dd>This parameter returns the number of bytes of page cache8753** allocation which could not be satisfied by the [SQLITE_CONFIG_PAGECACHE]8754** buffer and where forced to overflow to [sqlite3_malloc()].  The8755** returned value includes allocations that overflowed because they8756** where too large (they were larger than the "sz" parameter to8757** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because8758** no space was left in the page cache.</dd>)^8759**8760** [[SQLITE_STATUS_PAGECACHE_SIZE]] ^(<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>8761** <dd>This parameter records the largest memory allocation request8762** handed to the [pagecache memory allocator].  Only the value returned in the8763** *pHighwater parameter to [sqlite3_status()] is of interest.8764** The value written into the *pCurrent parameter is undefined.</dd>)^8765**8766** [[SQLITE_STATUS_SCRATCH_USED]] <dt>SQLITE_STATUS_SCRATCH_USED</dt>8767** <dd>No longer used.</dd>8768**8769** [[SQLITE_STATUS_SCRATCH_OVERFLOW]] ^(<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>8770** <dd>No longer used.</dd>8771**8772** [[SQLITE_STATUS_SCRATCH_SIZE]] <dt>SQLITE_STATUS_SCRATCH_SIZE</dt>8773** <dd>No longer used.</dd>8774**8775** [[SQLITE_STATUS_PARSER_STACK]] ^(<dt>SQLITE_STATUS_PARSER_STACK</dt>8776** <dd>The *pHighwater parameter records the deepest parser stack.8777** The *pCurrent value is undefined.  The *pHighwater value is only8778** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^8779** </dl>8780**8781** New status parameters may be added from time to time.8782*/8783#define SQLITE_STATUS_MEMORY_USED          08784#define SQLITE_STATUS_PAGECACHE_USED       18785#define SQLITE_STATUS_PAGECACHE_OVERFLOW   28786#define SQLITE_STATUS_SCRATCH_USED         3  /* NOT USED */8787#define SQLITE_STATUS_SCRATCH_OVERFLOW     4  /* NOT USED */8788#define SQLITE_STATUS_MALLOC_SIZE          58789#define SQLITE_STATUS_PARSER_STACK         68790#define SQLITE_STATUS_PAGECACHE_SIZE       78791#define SQLITE_STATUS_SCRATCH_SIZE         8  /* NOT USED */8792#define SQLITE_STATUS_MALLOC_COUNT         987938794/*8795** CAPI3REF: Database Connection Status8796** METHOD: sqlite38797**8798** ^This interface is used to retrieve runtime status information8799** about a single [database connection].  ^The first argument is the8800** database connection object to be interrogated.  ^The second argument8801** is an integer constant, taken from the set of8802** [SQLITE_DBSTATUS options], that8803** determines the parameter to interrogate.  The set of8804** [SQLITE_DBSTATUS options] is likely8805** to grow in future releases of SQLite.8806**8807** ^The current value of the requested parameter is written into *pCur8808** and the highest instantaneous value is written into *pHiwtr.  ^If8809** the resetFlg is true, then the highest instantaneous value is8810** reset back down to the current value.8811**8812** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a8813** non-zero [error code] on failure.8814**8815** See also: [sqlite3_status()] and [sqlite3_stmt_status()].8816*/8817SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);88188819/*8820** CAPI3REF: Status Parameters for database connections8821** KEYWORDS: {SQLITE_DBSTATUS options}8822**8823** These constants are the available integer "verbs" that can be passed as8824** the second argument to the [sqlite3_db_status()] interface.8825**8826** New verbs may be added in future releases of SQLite. Existing verbs8827** might be discontinued. Applications should check the return code from8828** [sqlite3_db_status()] to make sure that the call worked.8829** The [sqlite3_db_status()] interface will return a non-zero error code8830** if a discontinued or unsupported verb is invoked.8831**8832** <dl>8833** [[SQLITE_DBSTATUS_LOOKASIDE_USED]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>8834** <dd>This parameter returns the number of lookaside memory slots currently8835** checked out.</dd>)^8836**8837** [[SQLITE_DBSTATUS_LOOKASIDE_HIT]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_HIT</dt>8838** <dd>This parameter returns the number of malloc attempts that were8839** satisfied using lookaside memory. Only the high-water value is meaningful;8840** the current value is always zero.)^8841**8842** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE]]8843** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE</dt>8844** <dd>This parameter returns the number malloc attempts that might have8845** been satisfied using lookaside memory but failed due to the amount of8846** memory requested being larger than the lookaside slot size.8847** Only the high-water value is meaningful;8848** the current value is always zero.)^8849**8850** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL]]8851** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL</dt>8852** <dd>This parameter returns the number malloc attempts that might have8853** been satisfied using lookaside memory but failed due to all lookaside8854** memory already being in use.8855** Only the high-water value is meaningful;8856** the current value is always zero.)^8857**8858** [[SQLITE_DBSTATUS_CACHE_USED]] ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt>8859** <dd>This parameter returns the approximate number of bytes of heap8860** memory used by all pager caches associated with the database connection.)^8861** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.8862**8863** [[SQLITE_DBSTATUS_CACHE_USED_SHARED]]8864** ^(<dt>SQLITE_DBSTATUS_CACHE_USED_SHARED</dt>8865** <dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a8866** pager cache is shared between two or more connections the bytes of heap8867** memory used by that pager cache is divided evenly between the attached8868** connections.)^  In other words, if none of the pager caches associated8869** with the database connection are shared, this request returns the same8870** value as DBSTATUS_CACHE_USED. Or, if one or more or the pager caches are8871** shared, the value returned by this call will be smaller than that returned8872** by DBSTATUS_CACHE_USED. ^The highwater mark associated with8873** SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0.8874**8875** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt>8876** <dd>This parameter returns the approximate number of bytes of heap8877** memory used to store the schema for all databases associated8878** with the connection - main, temp, and any [ATTACH]-ed databases.)^8879** ^The full amount of memory used by the schemas is reported, even if the8880** schema memory is shared with other database connections due to8881** [shared cache mode] being enabled.8882** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.8883**8884** [[SQLITE_DBSTATUS_STMT_USED]] ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt>8885** <dd>This parameter returns the approximate number of bytes of heap8886** and lookaside memory used by all prepared statements associated with8887** the database connection.)^8888** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.8889** </dd>8890**8891** [[SQLITE_DBSTATUS_CACHE_HIT]] ^(<dt>SQLITE_DBSTATUS_CACHE_HIT</dt>8892** <dd>This parameter returns the number of pager cache hits that have8893** occurred.)^ ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_HIT8894** is always 0.8895** </dd>8896**8897** [[SQLITE_DBSTATUS_CACHE_MISS]] ^(<dt>SQLITE_DBSTATUS_CACHE_MISS</dt>8898** <dd>This parameter returns the number of pager cache misses that have8899** occurred.)^ ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_MISS8900** is always 0.8901** </dd>8902**8903** [[SQLITE_DBSTATUS_CACHE_WRITE]] ^(<dt>SQLITE_DBSTATUS_CACHE_WRITE</dt>8904** <dd>This parameter returns the number of dirty cache entries that have8905** been written to disk. Specifically, the number of pages written to the8906** wal file in wal mode databases, or the number of pages written to the8907** database file in rollback mode databases. Any pages written as part of8908** transaction rollback or database recovery operations are not included.8909** If an IO or other error occurs while writing a page to disk, the effect8910** on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined.)^ ^The8911** highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0.8912** </dd>8913**8914** [[SQLITE_DBSTATUS_CACHE_SPILL]] ^(<dt>SQLITE_DBSTATUS_CACHE_SPILL</dt>8915** <dd>This parameter returns the number of dirty cache entries that have8916** been written to disk in the middle of a transaction due to the page8917** cache overflowing. Transactions are more efficient if they are written8918** to disk all at once. When pages spill mid-transaction, that introduces8919** additional overhead. This parameter can be used help identify8920** inefficiencies that can be resolved by increasing the cache size.8921** </dd>8922**8923** [[SQLITE_DBSTATUS_DEFERRED_FKS]] ^(<dt>SQLITE_DBSTATUS_DEFERRED_FKS</dt>8924** <dd>This parameter returns zero for the current value if and only if8925** all foreign key constraints (deferred or immediate) have been8926** resolved.)^  ^The highwater mark is always 0.8927** </dd>8928** </dl>8929*/8930#define SQLITE_DBSTATUS_LOOKASIDE_USED       08931#define SQLITE_DBSTATUS_CACHE_USED           18932#define SQLITE_DBSTATUS_SCHEMA_USED          28933#define SQLITE_DBSTATUS_STMT_USED            38934#define SQLITE_DBSTATUS_LOOKASIDE_HIT        48935#define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE  58936#define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL  68937#define SQLITE_DBSTATUS_CACHE_HIT            78938#define SQLITE_DBSTATUS_CACHE_MISS           88939#define SQLITE_DBSTATUS_CACHE_WRITE          98940#define SQLITE_DBSTATUS_DEFERRED_FKS        108941#define SQLITE_DBSTATUS_CACHE_USED_SHARED   118942#define SQLITE_DBSTATUS_CACHE_SPILL         128943#define SQLITE_DBSTATUS_MAX                 12   /* Largest defined DBSTATUS */894489458946/*8947** CAPI3REF: Prepared Statement Status8948** METHOD: sqlite3_stmt8949**8950** ^(Each prepared statement maintains various8951** [SQLITE_STMTSTATUS counters] that measure the number8952** of times it has performed specific operations.)^  These counters can8953** be used to monitor the performance characteristics of the prepared8954** statements.  For example, if the number of table steps greatly exceeds8955** the number of table searches or result rows, that would tend to indicate8956** that the prepared statement is using a full table scan rather than8957** an index.8958**8959** ^(This interface is used to retrieve and reset counter values from8960** a [prepared statement].  The first argument is the prepared statement8961** object to be interrogated.  The second argument8962** is an integer code for a specific [SQLITE_STMTSTATUS counter]8963** to be interrogated.)^8964** ^The current value of the requested counter is returned.8965** ^If the resetFlg is true, then the counter is reset to zero after this8966** interface call returns.8967**8968** See also: [sqlite3_status()] and [sqlite3_db_status()].8969*/8970SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);89718972/*8973** CAPI3REF: Status Parameters for prepared statements8974** KEYWORDS: {SQLITE_STMTSTATUS counter} {SQLITE_STMTSTATUS counters}8975**8976** These preprocessor macros define integer codes that name counter8977** values associated with the [sqlite3_stmt_status()] interface.8978** The meanings of the various counters are as follows:8979**8980** <dl>8981** [[SQLITE_STMTSTATUS_FULLSCAN_STEP]] <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt>8982** <dd>^This is the number of times that SQLite has stepped forward in8983** a table as part of a full table scan.  Large numbers for this counter8984** may indicate opportunities for performance improvement through8985** careful use of indices.</dd>8986**8987** [[SQLITE_STMTSTATUS_SORT]] <dt>SQLITE_STMTSTATUS_SORT</dt>8988** <dd>^This is the number of sort operations that have occurred.8989** A non-zero value in this counter may indicate an opportunity to8990** improvement performance through careful use of indices.</dd>8991**8992** [[SQLITE_STMTSTATUS_AUTOINDEX]] <dt>SQLITE_STMTSTATUS_AUTOINDEX</dt>8993** <dd>^This is the number of rows inserted into transient indices that8994** were created automatically in order to help joins run faster.8995** A non-zero value in this counter may indicate an opportunity to8996** improvement performance by adding permanent indices that do not8997** need to be reinitialized each time the statement is run.</dd>8998**8999** [[SQLITE_STMTSTATUS_VM_STEP]] <dt>SQLITE_STMTSTATUS_VM_STEP</dt>9000** <dd>^This is the number of virtual machine operations executed9001** by the prepared statement if that number is less than or equal9002** to 2147483647.  The number of virtual machine operations can be9003** used as a proxy for the total work done by the prepared statement.9004** If the number of virtual machine operations exceeds 21474836479005** then the value returned by this statement status code is undefined.9006**9007** [[SQLITE_STMTSTATUS_REPREPARE]] <dt>SQLITE_STMTSTATUS_REPREPARE</dt>9008** <dd>^This is the number of times that the prepare statement has been9009** automatically regenerated due to schema changes or changes to9010** [bound parameters] that might affect the query plan.9011**9012** [[SQLITE_STMTSTATUS_RUN]] <dt>SQLITE_STMTSTATUS_RUN</dt>9013** <dd>^This is the number of times that the prepared statement has9014** been run.  A single "run" for the purposes of this counter is one9015** or more calls to [sqlite3_step()] followed by a call to [sqlite3_reset()].9016** The counter is incremented on the first [sqlite3_step()] call of each9017** cycle.9018**9019** [[SQLITE_STMTSTATUS_FILTER_MISS]]9020** [[SQLITE_STMTSTATUS_FILTER HIT]]9021** <dt>SQLITE_STMTSTATUS_FILTER_HIT<br>9022** SQLITE_STMTSTATUS_FILTER_MISS</dt>9023** <dd>^SQLITE_STMTSTATUS_FILTER_HIT is the number of times that a join9024** step was bypassed because a Bloom filter returned not-found.  The9025** corresponding SQLITE_STMTSTATUS_FILTER_MISS value is the number of9026** times that the Bloom filter returned a find, and thus the join step9027** had to be processed as normal.9028**9029** [[SQLITE_STMTSTATUS_MEMUSED]] <dt>SQLITE_STMTSTATUS_MEMUSED</dt>9030** <dd>^This is the approximate number of bytes of heap memory9031** used to store the prepared statement.  ^This value is not actually9032** a counter, and so the resetFlg parameter to sqlite3_stmt_status()9033** is ignored when the opcode is SQLITE_STMTSTATUS_MEMUSED.9034** </dd>9035** </dl>9036*/9037#define SQLITE_STMTSTATUS_FULLSCAN_STEP     19038#define SQLITE_STMTSTATUS_SORT              29039#define SQLITE_STMTSTATUS_AUTOINDEX         39040#define SQLITE_STMTSTATUS_VM_STEP           49041#define SQLITE_STMTSTATUS_REPREPARE         59042#define SQLITE_STMTSTATUS_RUN               69043#define SQLITE_STMTSTATUS_FILTER_MISS       79044#define SQLITE_STMTSTATUS_FILTER_HIT        89045#define SQLITE_STMTSTATUS_MEMUSED           9990469047/*9048** CAPI3REF: Custom Page Cache Object9049**9050** The sqlite3_pcache type is opaque.  It is implemented by9051** the pluggable module.  The SQLite core has no knowledge of9052** its size or internal structure and never deals with the9053** sqlite3_pcache object except by holding and passing pointers9054** to the object.9055**9056** See [sqlite3_pcache_methods2] for additional information.9057*/9058typedef struct sqlite3_pcache sqlite3_pcache;90599060/*9061** CAPI3REF: Custom Page Cache Object9062**9063** The sqlite3_pcache_page object represents a single page in the9064** page cache.  The page cache will allocate instances of this9065** object.  Various methods of the page cache use pointers to instances9066** of this object as parameters or as their return value.9067**9068** See [sqlite3_pcache_methods2] for additional information.9069*/9070typedef struct sqlite3_pcache_page sqlite3_pcache_page;9071struct sqlite3_pcache_page {9072  void *pBuf;        /* The content of the page */9073  void *pExtra;      /* Extra information associated with the page */9074};90759076/*9077** CAPI3REF: Application Defined Page Cache.9078** KEYWORDS: {page cache}9079**9080** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE2], ...) interface can9081** register an alternative page cache implementation by passing in an9082** instance of the sqlite3_pcache_methods2 structure.)^9083** In many applications, most of the heap memory allocated by9084** SQLite is used for the page cache.9085** By implementing a9086** custom page cache using this API, an application can better control9087** the amount of memory consumed by SQLite, the way in which9088** that memory is allocated and released, and the policies used to9089** determine exactly which parts of a database file are cached and for9090** how long.9091**9092** The alternative page cache mechanism is an9093** extreme measure that is only needed by the most demanding applications.9094** The built-in page cache is recommended for most uses.9095**9096** ^(The contents of the sqlite3_pcache_methods2 structure are copied to an9097** internal buffer by SQLite within the call to [sqlite3_config].  Hence9098** the application may discard the parameter after the call to9099** [sqlite3_config()] returns.)^9100**9101** [[the xInit() page cache method]]9102** ^(The xInit() method is called once for each effective9103** call to [sqlite3_initialize()])^9104** (usually only once during the lifetime of the process). ^(The xInit()9105** method is passed a copy of the sqlite3_pcache_methods2.pArg value.)^9106** The intent of the xInit() method is to set up global data structures9107** required by the custom page cache implementation.9108** ^(If the xInit() method is NULL, then the9109** built-in default page cache is used instead of the application defined9110** page cache.)^9111**9112** [[the xShutdown() page cache method]]9113** ^The xShutdown() method is called by [sqlite3_shutdown()].9114** It can be used to clean up9115** any outstanding resources before process shutdown, if required.9116** ^The xShutdown() method may be NULL.9117**9118** ^SQLite automatically serializes calls to the xInit method,9119** so the xInit method need not be threadsafe.  ^The9120** xShutdown method is only called from [sqlite3_shutdown()] so it does9121** not need to be threadsafe either.  All other methods must be threadsafe9122** in multithreaded applications.9123**9124** ^SQLite will never invoke xInit() more than once without an intervening9125** call to xShutdown().9126**9127** [[the xCreate() page cache methods]]9128** ^SQLite invokes the xCreate() method to construct a new cache instance.9129** SQLite will typically create one cache instance for each open database file,9130** though this is not guaranteed. ^The9131** first parameter, szPage, is the size in bytes of the pages that must9132** be allocated by the cache.  ^szPage will always a power of two.  ^The9133** second parameter szExtra is a number of bytes of extra storage9134** associated with each page cache entry.  ^The szExtra parameter will9135** a number less than 250.  SQLite will use the9136** extra szExtra bytes on each page to store metadata about the underlying9137** database page on disk.  The value passed into szExtra depends9138** on the SQLite version, the target platform, and how SQLite was compiled.9139** ^The third argument to xCreate(), bPurgeable, is true if the cache being9140** created will be used to cache database pages of a file stored on disk, or9141** false if it is used for an in-memory database. The cache implementation9142** does not have to do anything special based with the value of bPurgeable;9143** it is purely advisory.  ^On a cache where bPurgeable is false, SQLite will9144** never invoke xUnpin() except to deliberately delete a page.9145** ^In other words, calls to xUnpin() on a cache with bPurgeable set to9146** false will always have the "discard" flag set to true.9147** ^Hence, a cache created with bPurgeable false will9148** never contain any unpinned pages.9149**9150** [[the xCachesize() page cache method]]9151** ^(The xCachesize() method may be called at any time by SQLite to set the9152** suggested maximum cache-size (number of pages stored by) the cache9153** instance passed as the first argument. This is the value configured using9154** the SQLite "[PRAGMA cache_size]" command.)^  As with the bPurgeable9155** parameter, the implementation is not required to do anything with this9156** value; it is advisory only.9157**9158** [[the xPagecount() page cache methods]]9159** The xPagecount() method must return the number of pages currently9160** stored in the cache, both pinned and unpinned.9161**9162** [[the xFetch() page cache methods]]9163** The xFetch() method locates a page in the cache and returns a pointer to9164** an sqlite3_pcache_page object associated with that page, or a NULL pointer.9165** The pBuf element of the returned sqlite3_pcache_page object will be a9166** pointer to a buffer of szPage bytes used to store the content of a9167** single database page.  The pExtra element of sqlite3_pcache_page will be9168** a pointer to the szExtra bytes of extra storage that SQLite has requested9169** for each entry in the page cache.9170**9171** The page to be fetched is determined by the key. ^The minimum key value9172** is 1.  After it has been retrieved using xFetch, the page is considered9173** to be "pinned".9174**9175** If the requested page is already in the page cache, then the page cache9176** implementation must return a pointer to the page buffer with its content9177** intact.  If the requested page is not already in the cache, then the9178** cache implementation should use the value of the createFlag9179** parameter to help it determined what action to take:9180**9181** <table border=1 width=85% align=center>9182** <tr><th> createFlag <th> Behavior when page is not already in cache9183** <tr><td> 0 <td> Do not allocate a new page.  Return NULL.9184** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.9185**                 Otherwise return NULL.9186** <tr><td> 2 <td> Make every effort to allocate a new page.  Only return9187**                 NULL if allocating a new page is effectively impossible.9188** </table>9189**9190** ^(SQLite will normally invoke xFetch() with a createFlag of 0 or 1.  SQLite9191** will only use a createFlag of 2 after a prior call with a createFlag of 19192** failed.)^  In between the xFetch() calls, SQLite may9193** attempt to unpin one or more cache pages by spilling the content of9194** pinned pages to disk and synching the operating system disk cache.9195**9196** [[the xUnpin() page cache method]]9197** ^xUnpin() is called by SQLite with a pointer to a currently pinned page9198** as its second argument.  If the third parameter, discard, is non-zero,9199** then the page must be evicted from the cache.9200** ^If the discard parameter is9201** zero, then the page may be discarded or retained at the discretion of9202** page cache implementation. ^The page cache implementation9203** may choose to evict unpinned pages at any time.9204**9205** The cache must not perform any reference counting. A single9206** call to xUnpin() unpins the page regardless of the number of prior calls9207** to xFetch().9208**9209** [[the xRekey() page cache methods]]9210** The xRekey() method is used to change the key value associated with the9211** page passed as the second argument. If the cache9212** previously contains an entry associated with newKey, it must be9213** discarded. ^Any prior cache entry associated with newKey is guaranteed not9214** to be pinned.9215**9216** When SQLite calls the xTruncate() method, the cache must discard all9217** existing cache entries with page numbers (keys) greater than or equal9218** to the value of the iLimit parameter passed to xTruncate(). If any9219** of these pages are pinned, they are implicitly unpinned, meaning that9220** they can be safely discarded.9221**9222** [[the xDestroy() page cache method]]9223** ^The xDestroy() method is used to delete a cache allocated by xCreate().9224** All resources associated with the specified cache should be freed. ^After9225** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]9226** handle invalid, and will not use it with any other sqlite3_pcache_methods29227** functions.9228**9229** [[the xShrink() page cache method]]9230** ^SQLite invokes the xShrink() method when it wants the page cache to9231** free up as much of heap memory as possible.  The page cache implementation9232** is not obligated to free any memory, but well-behaved implementations should9233** do their best.9234*/9235typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2;9236struct sqlite3_pcache_methods2 {9237  int iVersion;9238  void *pArg;9239  int (*xInit)(void*);9240  void (*xShutdown)(void*);9241  sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable);9242  void (*xCachesize)(sqlite3_pcache*, int nCachesize);9243  int (*xPagecount)(sqlite3_pcache*);9244  sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);9245  void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard);9246  void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*,9247      unsigned oldKey, unsigned newKey);9248  void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);9249  void (*xDestroy)(sqlite3_pcache*);9250  void (*xShrink)(sqlite3_pcache*);9251};92529253/*9254** This is the obsolete pcache_methods object that has now been replaced9255** by sqlite3_pcache_methods2.  This object is not used by SQLite.  It is9256** retained in the header file for backwards compatibility only.9257*/9258typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;9259struct sqlite3_pcache_methods {9260  void *pArg;9261  int (*xInit)(void*);9262  void (*xShutdown)(void*);9263  sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable);9264  void (*xCachesize)(sqlite3_pcache*, int nCachesize);9265  int (*xPagecount)(sqlite3_pcache*);9266  void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);9267  void (*xUnpin)(sqlite3_pcache*, void*, int discard);9268  void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);9269  void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);9270  void (*xDestroy)(sqlite3_pcache*);9271};927292739274/*9275** CAPI3REF: Online Backup Object9276**9277** The sqlite3_backup object records state information about an ongoing9278** online backup operation.  ^The sqlite3_backup object is created by9279** a call to [sqlite3_backup_init()] and is destroyed by a call to9280** [sqlite3_backup_finish()].9281**9282** See Also: [Using the SQLite Online Backup API]9283*/9284typedef struct sqlite3_backup sqlite3_backup;92859286/*9287** CAPI3REF: Online Backup API.9288**9289** The backup API copies the content of one database into another.9290** It is useful either for creating backups of databases or9291** for copying in-memory databases to or from persistent files.9292**9293** See Also: [Using the SQLite Online Backup API]9294**9295** ^SQLite holds a write transaction open on the destination database file9296** for the duration of the backup operation.9297** ^The source database is read-locked only while it is being read;9298** it is not locked continuously for the entire backup operation.9299** ^Thus, the backup may be performed on a live source database without9300** preventing other database connections from9301** reading or writing to the source database while the backup is underway.9302**9303** ^(To perform a backup operation:9304**   <ol>9305**     <li><b>sqlite3_backup_init()</b> is called once to initialize the9306**         backup,9307**     <li><b>sqlite3_backup_step()</b> is called one or more times to transfer9308**         the data between the two databases, and finally9309**     <li><b>sqlite3_backup_finish()</b> is called to release all resources9310**         associated with the backup operation.9311**   </ol>)^9312** There should be exactly one call to sqlite3_backup_finish() for each9313** successful call to sqlite3_backup_init().9314**9315** [[sqlite3_backup_init()]] <b>sqlite3_backup_init()</b>9316**9317** ^The D and N arguments to sqlite3_backup_init(D,N,S,M) are the9318** [database connection] associated with the destination database9319** and the database name, respectively.9320** ^The database name is "main" for the main database, "temp" for the9321** temporary database, or the name specified after the AS keyword in9322** an [ATTACH] statement for an attached database.9323** ^The S and M arguments passed to9324** sqlite3_backup_init(D,N,S,M) identify the [database connection]9325** and database name of the source database, respectively.9326** ^The source and destination [database connections] (parameters S and D)9327** must be different or else sqlite3_backup_init(D,N,S,M) will fail with9328** an error.9329**9330** ^A call to sqlite3_backup_init() will fail, returning NULL, if9331** there is already a read or read-write transaction open on the9332** destination database.9333**9334** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is9335** returned and an error code and error message are stored in the9336** destination [database connection] D.9337** ^The error code and message for the failed call to sqlite3_backup_init()9338** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or9339** [sqlite3_errmsg16()] functions.9340** ^A successful call to sqlite3_backup_init() returns a pointer to an9341** [sqlite3_backup] object.9342** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and9343** sqlite3_backup_finish() functions to perform the specified backup9344** operation.9345**9346** [[sqlite3_backup_step()]] <b>sqlite3_backup_step()</b>9347**9348** ^Function sqlite3_backup_step(B,N) will copy up to N pages between9349** the source and destination databases specified by [sqlite3_backup] object B.9350** ^If N is negative, all remaining source pages are copied.9351** ^If sqlite3_backup_step(B,N) successfully copies N pages and there9352** are still more pages to be copied, then the function returns [SQLITE_OK].9353** ^If sqlite3_backup_step(B,N) successfully finishes copying all pages9354** from source to destination, then it returns [SQLITE_DONE].9355** ^If an error occurs while running sqlite3_backup_step(B,N),9356** then an [error code] is returned. ^As well as [SQLITE_OK] and9357** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],9358** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an9359** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.9360**9361** ^(The sqlite3_backup_step() might return [SQLITE_READONLY] if9362** <ol>9363** <li> the destination database was opened read-only, or9364** <li> the destination database is using write-ahead-log journaling9365** and the destination and source page sizes differ, or9366** <li> the destination database is an in-memory database and the9367** destination and source page sizes differ.9368** </ol>)^9369**9370** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then9371** the [sqlite3_busy_handler | busy-handler function]9372** is invoked (if one is specified). ^If the9373** busy-handler returns non-zero before the lock is available, then9374** [SQLITE_BUSY] is returned to the caller. ^In this case the call to9375** sqlite3_backup_step() can be retried later. ^If the source9376** [database connection]9377** is being used to write to the source database when sqlite3_backup_step()9378** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this9379** case the call to sqlite3_backup_step() can be retried later on. ^(If9380** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or9381** [SQLITE_READONLY] is returned, then9382** there is no point in retrying the call to sqlite3_backup_step(). These9383** errors are considered fatal.)^  The application must accept9384** that the backup operation has failed and pass the backup operation handle9385** to the sqlite3_backup_finish() to release associated resources.9386**9387** ^The first call to sqlite3_backup_step() obtains an exclusive lock9388** on the destination file. ^The exclusive lock is not released until either9389** sqlite3_backup_finish() is called or the backup operation is complete9390** and sqlite3_backup_step() returns [SQLITE_DONE].  ^Every call to9391** sqlite3_backup_step() obtains a [shared lock] on the source database that9392** lasts for the duration of the sqlite3_backup_step() call.9393** ^Because the source database is not locked between calls to9394** sqlite3_backup_step(), the source database may be modified mid-way9395** through the backup process.  ^If the source database is modified by an9396** external process or via a database connection other than the one being9397** used by the backup operation, then the backup will be automatically9398** restarted by the next call to sqlite3_backup_step(). ^If the source9399** database is modified by the using the same database connection as is used9400** by the backup operation, then the backup database is automatically9401** updated at the same time.9402**9403** [[sqlite3_backup_finish()]] <b>sqlite3_backup_finish()</b>9404**9405** When sqlite3_backup_step() has returned [SQLITE_DONE], or when the9406** application wishes to abandon the backup operation, the application9407** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish().9408** ^The sqlite3_backup_finish() interfaces releases all9409** resources associated with the [sqlite3_backup] object.9410** ^If sqlite3_backup_step() has not yet returned [SQLITE_DONE], then any9411** active write-transaction on the destination database is rolled back.9412** The [sqlite3_backup] object is invalid9413** and may not be used following a call to sqlite3_backup_finish().9414**9415** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no9416** sqlite3_backup_step() errors occurred, regardless or whether or not9417** sqlite3_backup_step() completed.9418** ^If an out-of-memory condition or IO error occurred during any prior9419** sqlite3_backup_step() call on the same [sqlite3_backup] object, then9420** sqlite3_backup_finish() returns the corresponding [error code].9421**9422** ^A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step()9423** is not a permanent error and does not affect the return value of9424** sqlite3_backup_finish().9425**9426** [[sqlite3_backup_remaining()]] [[sqlite3_backup_pagecount()]]9427** <b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b>9428**9429** ^The sqlite3_backup_remaining() routine returns the number of pages still9430** to be backed up at the conclusion of the most recent sqlite3_backup_step().9431** ^The sqlite3_backup_pagecount() routine returns the total number of pages9432** in the source database at the conclusion of the most recent9433** sqlite3_backup_step().9434** ^(The values returned by these functions are only updated by9435** sqlite3_backup_step(). If the source database is modified in a way that9436** changes the size of the source database or the number of pages remaining,9437** those changes are not reflected in the output of sqlite3_backup_pagecount()9438** and sqlite3_backup_remaining() until after the next9439** sqlite3_backup_step().)^9440**9441** <b>Concurrent Usage of Database Handles</b>9442**9443** ^The source [database connection] may be used by the application for other9444** purposes while a backup operation is underway or being initialized.9445** ^If SQLite is compiled and configured to support threadsafe database9446** connections, then the source database connection may be used concurrently9447** from within other threads.9448**9449** However, the application must guarantee that the destination9450** [database connection] is not passed to any other API (by any thread) after9451** sqlite3_backup_init() is called and before the corresponding call to9452** sqlite3_backup_finish().  SQLite does not currently check to see9453** if the application incorrectly accesses the destination [database connection]9454** and so no error code is reported, but the operations may malfunction9455** nevertheless.  Use of the destination database connection while a9456** backup is in progress might also cause a mutex deadlock.9457**9458** If running in [shared cache mode], the application must9459** guarantee that the shared cache used by the destination database9460** is not accessed while the backup is running. In practice this means9461** that the application must guarantee that the disk file being9462** backed up to is not accessed by any connection within the process,9463** not just the specific connection that was passed to sqlite3_backup_init().9464**9465** The [sqlite3_backup] object itself is partially threadsafe. Multiple9466** threads may safely make multiple concurrent calls to sqlite3_backup_step().9467** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()9468** APIs are not strictly speaking threadsafe. If they are invoked at the9469** same time as another thread is invoking sqlite3_backup_step() it is9470** possible that they return invalid values.9471**9472** <b>Alternatives To Using The Backup API</b>9473**9474** Other techniques for safely creating a consistent backup of an SQLite9475** database include:9476**9477** <ul>9478** <li> The [VACUUM INTO] command.9479** <li> The [sqlite3_rsync] utility program.9480** </ul>9481*/9482SQLITE_API sqlite3_backup *sqlite3_backup_init(9483  sqlite3 *pDest,                        /* Destination database handle */9484  const char *zDestName,                 /* Destination database name */9485  sqlite3 *pSource,                      /* Source database handle */9486  const char *zSourceName                /* Source database name */9487);9488SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage);9489SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p);9490SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);9491SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);94929493/*9494** CAPI3REF: Unlock Notification9495** METHOD: sqlite39496**9497** ^When running in shared-cache mode, a database operation may fail with9498** an [SQLITE_LOCKED] error if the required locks on the shared-cache or9499** individual tables within the shared-cache cannot be obtained. See9500** [SQLite Shared-Cache Mode] for a description of shared-cache locking.9501** ^This API may be used to register a callback that SQLite will invoke9502** when the connection currently holding the required lock relinquishes it.9503** ^This API is only available if the library was compiled with the9504** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.9505**9506** See Also: [Using the SQLite Unlock Notification Feature].9507**9508** ^Shared-cache locks are released when a database connection concludes9509** its current transaction, either by committing it or rolling it back.9510**9511** ^When a connection (known as the blocked connection) fails to obtain a9512** shared-cache lock and SQLITE_LOCKED is returned to the caller, the9513** identity of the database connection (the blocking connection) that9514** has locked the required resource is stored internally. ^After an9515** application receives an SQLITE_LOCKED error, it may call the9516** sqlite3_unlock_notify() method with the blocked connection handle as9517** the first argument to register for a callback that will be invoked9518** when the blocking connections current transaction is concluded. ^The9519** callback is invoked from within the [sqlite3_step] or [sqlite3_close]9520** call that concludes the blocking connection's transaction.9521**9522** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,9523** there is a chance that the blocking connection will have already9524** concluded its transaction by the time sqlite3_unlock_notify() is invoked.9525** If this happens, then the specified callback is invoked immediately,9526** from within the call to sqlite3_unlock_notify().)^9527**9528** ^If the blocked connection is attempting to obtain a write-lock on a9529** shared-cache table, and more than one other connection currently holds9530** a read-lock on the same table, then SQLite arbitrarily selects one of9531** the other connections to use as the blocking connection.9532**9533** ^(There may be at most one unlock-notify callback registered by a9534** blocked connection. If sqlite3_unlock_notify() is called when the9535** blocked connection already has a registered unlock-notify callback,9536** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is9537** called with a NULL pointer as its second argument, then any existing9538** unlock-notify callback is canceled. ^The blocked connections9539** unlock-notify callback may also be canceled by closing the blocked9540** connection using [sqlite3_close()].9541**9542** The unlock-notify callback is not reentrant. If an application invokes9543** any sqlite3_xxx API functions from within an unlock-notify callback, a9544** crash or deadlock may be the result.9545**9546** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always9547** returns SQLITE_OK.9548**9549** <b>Callback Invocation Details</b>9550**9551** When an unlock-notify callback is registered, the application provides a9552** single void* pointer that is passed to the callback when it is invoked.9553** However, the signature of the callback function allows SQLite to pass9554** it an array of void* context pointers. The first argument passed to9555** an unlock-notify callback is a pointer to an array of void* pointers,9556** and the second is the number of entries in the array.9557**9558** When a blocking connection's transaction is concluded, there may be9559** more than one blocked connection that has registered for an unlock-notify9560** callback. ^If two or more such blocked connections have specified the9561** same callback function, then instead of invoking the callback function9562** multiple times, it is invoked once with the set of void* context pointers9563** specified by the blocked connections bundled together into an array.9564** This gives the application an opportunity to prioritize any actions9565** related to the set of unblocked database connections.9566**9567** <b>Deadlock Detection</b>9568**9569** Assuming that after registering for an unlock-notify callback a9570** database waits for the callback to be issued before taking any further9571** action (a reasonable assumption), then using this API may cause the9572** application to deadlock. For example, if connection X is waiting for9573** connection Y's transaction to be concluded, and similarly connection9574** Y is waiting on connection X's transaction, then neither connection9575** will proceed and the system may remain deadlocked indefinitely.9576**9577** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock9578** detection. ^If a given call to sqlite3_unlock_notify() would put the9579** system in a deadlocked state, then SQLITE_LOCKED is returned and no9580** unlock-notify callback is registered. The system is said to be in9581** a deadlocked state if connection A has registered for an unlock-notify9582** callback on the conclusion of connection B's transaction, and connection9583** B has itself registered for an unlock-notify callback when connection9584** A's transaction is concluded. ^Indirect deadlock is also detected, so9585** the system is also considered to be deadlocked if connection B has9586** registered for an unlock-notify callback on the conclusion of connection9587** C's transaction, where connection C is waiting on connection A. ^Any9588** number of levels of indirection are allowed.9589**9590** <b>The "DROP TABLE" Exception</b>9591**9592** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost9593** always appropriate to call sqlite3_unlock_notify(). There is however,9594** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,9595** SQLite checks if there are any currently executing SELECT statements9596** that belong to the same connection. If there are, SQLITE_LOCKED is9597** returned. In this case there is no "blocking connection", so invoking9598** sqlite3_unlock_notify() results in the unlock-notify callback being9599** invoked immediately. If the application then re-attempts the "DROP TABLE"9600** or "DROP INDEX" query, an infinite loop might be the result.9601**9602** One way around this problem is to check the extended error code returned9603** by an sqlite3_step() call. ^(If there is a blocking connection, then the9604** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in9605** the special "DROP TABLE/INDEX" case, the extended error code is just9606** SQLITE_LOCKED.)^9607*/9608SQLITE_API int sqlite3_unlock_notify(9609  sqlite3 *pBlocked,                          /* Waiting connection */9610  void (*xNotify)(void **apArg, int nArg),    /* Callback function to invoke */9611  void *pNotifyArg                            /* Argument to pass to xNotify */9612);961396149615/*9616** CAPI3REF: String Comparison9617**9618** ^The [sqlite3_stricmp()] and [sqlite3_strnicmp()] APIs allow applications9619** and extensions to compare the contents of two buffers containing UTF-89620** strings in a case-independent fashion, using the same definition of "case9621** independence" that SQLite uses internally when comparing identifiers.9622*/9623SQLITE_API int sqlite3_stricmp(const char *, const char *);9624SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);96259626/*9627** CAPI3REF: String Globbing9628*9629** ^The [sqlite3_strglob(P,X)] interface returns zero if and only if9630** string X matches the [GLOB] pattern P.9631** ^The definition of [GLOB] pattern matching used in9632** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the9633** SQL dialect understood by SQLite.  ^The [sqlite3_strglob(P,X)] function9634** is case sensitive.9635**9636** Note that this routine returns zero on a match and non-zero if the strings9637** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].9638**9639** See also: [sqlite3_strlike()].9640*/9641SQLITE_API int sqlite3_strglob(const char *zGlob, const char *zStr);96429643/*9644** CAPI3REF: String LIKE Matching9645*9646** ^The [sqlite3_strlike(P,X,E)] interface returns zero if and only if9647** string X matches the [LIKE] pattern P with escape character E.9648** ^The definition of [LIKE] pattern matching used in9649** [sqlite3_strlike(P,X,E)] is the same as for the "X LIKE P ESCAPE E"9650** operator in the SQL dialect understood by SQLite.  ^For "X LIKE P" without9651** the ESCAPE clause, set the E parameter of [sqlite3_strlike(P,X,E)] to 0.9652** ^As with the LIKE operator, the [sqlite3_strlike(P,X,E)] function is case9653** insensitive - equivalent upper and lower case ASCII characters match9654** one another.9655**9656** ^The [sqlite3_strlike(P,X,E)] function matches Unicode characters, though9657** only ASCII characters are case folded.9658**9659** Note that this routine returns zero on a match and non-zero if the strings9660** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].9661**9662** See also: [sqlite3_strglob()].9663*/9664SQLITE_API int sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc);96659666/*9667** CAPI3REF: Error Logging Interface9668**9669** ^The [sqlite3_log()] interface writes a message into the [error log]9670** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()].9671** ^If logging is enabled, the zFormat string and subsequent arguments are9672** used with [sqlite3_snprintf()] to generate the final output string.9673**9674** The sqlite3_log() interface is intended for use by extensions such as9675** virtual tables, collating functions, and SQL functions.  While there is9676** nothing to prevent an application from calling sqlite3_log(), doing so9677** is considered bad form.9678**9679** The zFormat string must not be NULL.9680**9681** To avoid deadlocks and other threading problems, the sqlite3_log() routine9682** will not use dynamically allocated memory.  The log message is stored in9683** a fixed-length buffer on the stack.  If the log message is longer than9684** a few hundred characters, it will be truncated to the length of the9685** buffer.9686*/9687SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);96889689/*9690** CAPI3REF: Write-Ahead Log Commit Hook9691** METHOD: sqlite39692**9693** ^The [sqlite3_wal_hook()] function is used to register a callback that9694** is invoked each time data is committed to a database in wal mode.9695**9696** ^(The callback is invoked by SQLite after the commit has taken place and9697** the associated write-lock on the database released)^, so the implementation9698** may read, write or [checkpoint] the database as required.9699**9700** ^The first parameter passed to the callback function when it is invoked9701** is a copy of the third parameter passed to sqlite3_wal_hook() when9702** registering the callback. ^The second is a copy of the database handle.9703** ^The third parameter is the name of the database that was written to -9704** either "main" or the name of an [ATTACH]-ed database. ^The fourth parameter9705** is the number of pages currently in the write-ahead log file,9706** including those that were just committed.9707**9708** The callback function should normally return [SQLITE_OK].  ^If an error9709** code is returned, that error will propagate back up through the9710** SQLite code base to cause the statement that provoked the callback9711** to report an error, though the commit will have still occurred. If the9712** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value9713** that does not correspond to any valid SQLite error code, the results9714** are undefined.9715**9716** A single database handle may have at most a single write-ahead log callback9717** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any9718** previously registered write-ahead log callback. ^The return value is9719** a copy of the third parameter from the previous call, if any, or 0.9720** ^Note that the [sqlite3_wal_autocheckpoint()] interface and the9721** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will9722** overwrite any prior [sqlite3_wal_hook()] settings.9723*/9724SQLITE_API void *sqlite3_wal_hook(9725  sqlite3*,9726  int(*)(void *,sqlite3*,const char*,int),9727  void*9728);97299730/*9731** CAPI3REF: Configure an auto-checkpoint9732** METHOD: sqlite39733**9734** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around9735** [sqlite3_wal_hook()] that causes any database on [database connection] D9736** to automatically [checkpoint]9737** after committing a transaction if there are N or9738** more frames in the [write-ahead log] file.  ^Passing zero or9739** a negative value as the nFrame parameter disables automatic9740** checkpoints entirely.9741**9742** ^The callback registered by this function replaces any existing callback9743** registered using [sqlite3_wal_hook()].  ^Likewise, registering a callback9744** using [sqlite3_wal_hook()] disables the automatic checkpoint mechanism9745** configured by this function.9746**9747** ^The [wal_autocheckpoint pragma] can be used to invoke this interface9748** from SQL.9749**9750** ^Checkpoints initiated by this mechanism are9751** [sqlite3_wal_checkpoint_v2|PASSIVE].9752**9753** ^Every new [database connection] defaults to having the auto-checkpoint9754** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT]9755** pages.  The use of this interface9756** is only necessary if the default setting is found to be suboptimal9757** for a particular application.9758*/9759SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);97609761/*9762** CAPI3REF: Checkpoint a database9763** METHOD: sqlite39764**9765** ^(The sqlite3_wal_checkpoint(D,X) is equivalent to9766** [sqlite3_wal_checkpoint_v2](D,X,[SQLITE_CHECKPOINT_PASSIVE],0,0).)^9767**9768** In brief, sqlite3_wal_checkpoint(D,X) causes the content in the9769** [write-ahead log] for database X on [database connection] D to be9770** transferred into the database file and for the write-ahead log to9771** be reset.  See the [checkpointing] documentation for addition9772** information.9773**9774** This interface used to be the only way to cause a checkpoint to9775** occur.  But then the newer and more powerful [sqlite3_wal_checkpoint_v2()]9776** interface was added.  This interface is retained for backwards9777** compatibility and as a convenience for applications that need to manually9778** start a callback but which do not need the full power (and corresponding9779** complication) of [sqlite3_wal_checkpoint_v2()].9780*/9781SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);97829783/*9784** CAPI3REF: Checkpoint a database9785** METHOD: sqlite39786**9787** ^(The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint9788** operation on database X of [database connection] D in mode M.  Status9789** information is written back into integers pointed to by L and C.)^9790** ^(The M parameter must be a valid [checkpoint mode]:)^9791**9792** <dl>9793** <dt>SQLITE_CHECKPOINT_PASSIVE<dd>9794**   ^Checkpoint as many frames as possible without waiting for any database9795**   readers or writers to finish, then sync the database file if all frames9796**   in the log were checkpointed. ^The [busy-handler callback]9797**   is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.9798**   ^On the other hand, passive mode might leave the checkpoint unfinished9799**   if there are concurrent readers or writers.9800**9801** <dt>SQLITE_CHECKPOINT_FULL<dd>9802**   ^This mode blocks (it invokes the9803**   [sqlite3_busy_handler|busy-handler callback]) until there is no9804**   database writer and all readers are reading from the most recent database9805**   snapshot. ^It then checkpoints all frames in the log file and syncs the9806**   database file. ^This mode blocks new database writers while it is pending,9807**   but new database readers are allowed to continue unimpeded.9808**9809** <dt>SQLITE_CHECKPOINT_RESTART<dd>9810**   ^This mode works the same way as SQLITE_CHECKPOINT_FULL with the addition9811**   that after checkpointing the log file it blocks (calls the9812**   [busy-handler callback])9813**   until all readers are reading from the database file only. ^This ensures9814**   that the next writer will restart the log file from the beginning.9815**   ^Like SQLITE_CHECKPOINT_FULL, this mode blocks new9816**   database writer attempts while it is pending, but does not impede readers.9817**9818** <dt>SQLITE_CHECKPOINT_TRUNCATE<dd>9819**   ^This mode works the same way as SQLITE_CHECKPOINT_RESTART with the9820**   addition that it also truncates the log file to zero bytes just prior9821**   to a successful return.9822** </dl>9823**9824** ^If pnLog is not NULL, then *pnLog is set to the total number of frames in9825** the log file or to -1 if the checkpoint could not run because9826** of an error or because the database is not in [WAL mode]. ^If pnCkpt is not9827** NULL,then *pnCkpt is set to the total number of checkpointed frames in the9828** log file (including any that were already checkpointed before the function9829** was called) or to -1 if the checkpoint could not run due to an error or9830** because the database is not in WAL mode. ^Note that upon successful9831** completion of an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been9832** truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.9833**9834** ^All calls obtain an exclusive "checkpoint" lock on the database file. ^If9835** any other process is running a checkpoint operation at the same time, the9836** lock cannot be obtained and SQLITE_BUSY is returned. ^Even if there is a9837** busy-handler configured, it will not be invoked in this case.9838**9839** ^The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the9840** exclusive "writer" lock on the database file. ^If the writer lock cannot be9841** obtained immediately, and a busy-handler is configured, it is invoked and9842** the writer lock retried until either the busy-handler returns 0 or the lock9843** is successfully obtained. ^The busy-handler is also invoked while waiting for9844** database readers as described above. ^If the busy-handler returns 0 before9845** the writer lock is obtained or while waiting for database readers, the9846** checkpoint operation proceeds from that point in the same way as9847** SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible9848** without blocking any further. ^SQLITE_BUSY is returned in this case.9849**9850** ^If parameter zDb is NULL or points to a zero length string, then the9851** specified operation is attempted on all WAL databases [attached] to9852** [database connection] db.  In this case the9853** values written to output parameters *pnLog and *pnCkpt are undefined. ^If9854** an SQLITE_BUSY error is encountered when processing one or more of the9855** attached WAL databases, the operation is still attempted on any remaining9856** attached databases and SQLITE_BUSY is returned at the end. ^If any other9857** error occurs while processing an attached database, processing is abandoned9858** and the error code is returned to the caller immediately. ^If no error9859** (SQLITE_BUSY or otherwise) is encountered while processing the attached9860** databases, SQLITE_OK is returned.9861**9862** ^If database zDb is the name of an attached database that is not in WAL9863** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. ^If9864** zDb is not NULL (or a zero length string) and is not the name of any9865** attached database, SQLITE_ERROR is returned to the caller.9866**9867** ^Unless it returns SQLITE_MISUSE,9868** the sqlite3_wal_checkpoint_v2() interface9869** sets the error information that is queried by9870** [sqlite3_errcode()] and [sqlite3_errmsg()].9871**9872** ^The [PRAGMA wal_checkpoint] command can be used to invoke this interface9873** from SQL.9874*/9875SQLITE_API int sqlite3_wal_checkpoint_v2(9876  sqlite3 *db,                    /* Database handle */9877  const char *zDb,                /* Name of attached database (or NULL) */9878  int eMode,                      /* SQLITE_CHECKPOINT_* value */9879  int *pnLog,                     /* OUT: Size of WAL log in frames */9880  int *pnCkpt                     /* OUT: Total number of frames checkpointed */9881);98829883/*9884** CAPI3REF: Checkpoint Mode Values9885** KEYWORDS: {checkpoint mode}9886**9887** These constants define all valid values for the "checkpoint mode" passed9888** as the third parameter to the [sqlite3_wal_checkpoint_v2()] interface.9889** See the [sqlite3_wal_checkpoint_v2()] documentation for details on the9890** meaning of each of these checkpoint modes.9891*/9892#define SQLITE_CHECKPOINT_PASSIVE  0  /* Do as much as possible w/o blocking */9893#define SQLITE_CHECKPOINT_FULL     1  /* Wait for writers, then checkpoint */9894#define SQLITE_CHECKPOINT_RESTART  2  /* Like FULL but wait for readers */9895#define SQLITE_CHECKPOINT_TRUNCATE 3  /* Like RESTART but also truncate WAL */98969897/*9898** CAPI3REF: Virtual Table Interface Configuration9899**9900** This function may be called by either the [xConnect] or [xCreate] method9901** of a [virtual table] implementation to configure9902** various facets of the virtual table interface.9903**9904** If this interface is invoked outside the context of an xConnect or9905** xCreate virtual table method then the behavior is undefined.9906**9907** In the call sqlite3_vtab_config(D,C,...) the D parameter is the9908** [database connection] in which the virtual table is being created and9909** which is passed in as the first argument to the [xConnect] or [xCreate]9910** method that is invoking sqlite3_vtab_config().  The C parameter is one9911** of the [virtual table configuration options].  The presence and meaning9912** of parameters after C depend on which [virtual table configuration option]9913** is used.9914*/9915SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...);99169917/*9918** CAPI3REF: Virtual Table Configuration Options9919** KEYWORDS: {virtual table configuration options}9920** KEYWORDS: {virtual table configuration option}9921**9922** These macros define the various options to the9923** [sqlite3_vtab_config()] interface that [virtual table] implementations9924** can use to customize and optimize their behavior.9925**9926** <dl>9927** [[SQLITE_VTAB_CONSTRAINT_SUPPORT]]9928** <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT</dt>9929** <dd>Calls of the form9930** [sqlite3_vtab_config](db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported,9931** where X is an integer.  If X is zero, then the [virtual table] whose9932** [xCreate] or [xConnect] method invoked [sqlite3_vtab_config()] does not9933** support constraints.  In this configuration (which is the default) if9934** a call to the [xUpdate] method returns [SQLITE_CONSTRAINT], then the entire9935** statement is rolled back as if [ON CONFLICT | OR ABORT] had been9936** specified as part of the users SQL statement, regardless of the actual9937** ON CONFLICT mode specified.9938**9939** If X is non-zero, then the virtual table implementation guarantees9940** that if [xUpdate] returns [SQLITE_CONSTRAINT], it will do so before9941** any modifications to internal or persistent data structures have been made.9942** If the [ON CONFLICT] mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite9943** is able to roll back a statement or database transaction, and abandon9944** or continue processing the current SQL statement as appropriate.9945** If the ON CONFLICT mode is REPLACE and the [xUpdate] method returns9946** [SQLITE_CONSTRAINT], SQLite handles this as if the ON CONFLICT mode9947** had been ABORT.9948**9949** Virtual table implementations that are required to handle OR REPLACE9950** must do so within the [xUpdate] method. If a call to the9951** [sqlite3_vtab_on_conflict()] function indicates that the current ON9952** CONFLICT policy is REPLACE, the virtual table implementation should9953** silently replace the appropriate rows within the xUpdate callback and9954** return SQLITE_OK. Or, if this is not possible, it may return9955** SQLITE_CONSTRAINT, in which case SQLite falls back to OR ABORT9956** constraint handling.9957** </dd>9958**9959** [[SQLITE_VTAB_DIRECTONLY]]<dt>SQLITE_VTAB_DIRECTONLY</dt>9960** <dd>Calls of the form9961** [sqlite3_vtab_config](db,SQLITE_VTAB_DIRECTONLY) from within the9962** the [xConnect] or [xCreate] methods of a [virtual table] implementation9963** prohibits that virtual table from being used from within triggers and9964** views.9965** </dd>9966**9967** [[SQLITE_VTAB_INNOCUOUS]]<dt>SQLITE_VTAB_INNOCUOUS</dt>9968** <dd>Calls of the form9969** [sqlite3_vtab_config](db,SQLITE_VTAB_INNOCUOUS) from within the9970** the [xConnect] or [xCreate] methods of a [virtual table] implementation9971** identify that virtual table as being safe to use from within triggers9972** and views.  Conceptually, the SQLITE_VTAB_INNOCUOUS tag means that the9973** virtual table can do no serious harm even if it is controlled by a9974** malicious hacker.  Developers should avoid setting the SQLITE_VTAB_INNOCUOUS9975** flag unless absolutely necessary.9976** </dd>9977**9978** [[SQLITE_VTAB_USES_ALL_SCHEMAS]]<dt>SQLITE_VTAB_USES_ALL_SCHEMAS</dt>9979** <dd>Calls of the form9980** [sqlite3_vtab_config](db,SQLITE_VTAB_USES_ALL_SCHEMA) from within the9981** the [xConnect] or [xCreate] methods of a [virtual table] implementation9982** instruct the query planner to begin at least a read transaction on9983** all schemas ("main", "temp", and any ATTACH-ed databases) whenever the9984** virtual table is used.9985** </dd>9986** </dl>9987*/9988#define SQLITE_VTAB_CONSTRAINT_SUPPORT 19989#define SQLITE_VTAB_INNOCUOUS          29990#define SQLITE_VTAB_DIRECTONLY         39991#define SQLITE_VTAB_USES_ALL_SCHEMAS   499929993/*9994** CAPI3REF: Determine The Virtual Table Conflict Policy9995**9996** This function may only be called from within a call to the [xUpdate] method9997** of a [virtual table] implementation for an INSERT or UPDATE operation. ^The9998** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL],9999** [SQLITE_ABORT], or [SQLITE_REPLACE], according to the [ON CONFLICT] mode10000** of the SQL statement that triggered the call to the [xUpdate] method of the10001** [virtual table].10002*/10003SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *);1000410005/*10006** CAPI3REF: Determine If Virtual Table Column Access Is For UPDATE10007**10008** If the sqlite3_vtab_nochange(X) routine is called within the [xColumn]10009** method of a [virtual table], then it might return true if the10010** column is being fetched as part of an UPDATE operation during which the10011** column value will not change.  The virtual table implementation can use10012** this hint as permission to substitute a return value that is less10013** expensive to compute and that the corresponding10014** [xUpdate] method understands as a "no-change" value.10015**10016** If the [xColumn] method calls sqlite3_vtab_nochange() and finds that10017** the column is not changed by the UPDATE statement, then the xColumn10018** method can optionally return without setting a result, without calling10019** any of the [sqlite3_result_int|sqlite3_result_xxxxx() interfaces].10020** In that case, [sqlite3_value_nochange(X)] will return true for the10021** same column in the [xUpdate] method.10022**10023** The sqlite3_vtab_nochange() routine is an optimization.  Virtual table10024** implementations should continue to give a correct answer even if the10025** sqlite3_vtab_nochange() interface were to always return false.  In the10026** current implementation, the sqlite3_vtab_nochange() interface does always10027** returns false for the enhanced [UPDATE FROM] statement.10028*/10029SQLITE_API int sqlite3_vtab_nochange(sqlite3_context*);1003010031/*10032** CAPI3REF: Determine The Collation For a Virtual Table Constraint10033** METHOD: sqlite3_index_info10034**10035** This function may only be called from within a call to the [xBestIndex]10036** method of a [virtual table].  This function returns a pointer to a string10037** that is the name of the appropriate collation sequence to use for text10038** comparisons on the constraint identified by its arguments.10039**10040** The first argument must be the pointer to the [sqlite3_index_info] object10041** that is the first parameter to the xBestIndex() method. The second argument10042** must be an index into the aConstraint[] array belonging to the10043** sqlite3_index_info structure passed to xBestIndex.10044**10045** Important:10046** The first parameter must be the same pointer that is passed into the10047** xBestMethod() method.  The first parameter may not be a pointer to a10048** different [sqlite3_index_info] object, even an exact copy.10049**10050** The return value is computed as follows:10051**10052** <ol>10053** <li><p> If the constraint comes from a WHERE clause expression that contains10054**         a [COLLATE operator], then the name of the collation specified by10055**         that COLLATE operator is returned.10056** <li><p> If there is no COLLATE operator, but the column that is the subject10057**         of the constraint specifies an alternative collating sequence via10058**         a [COLLATE clause] on the column definition within the CREATE TABLE10059**         statement that was passed into [sqlite3_declare_vtab()], then the10060**         name of that alternative collating sequence is returned.10061** <li><p> Otherwise, "BINARY" is returned.10062** </ol>10063*/10064SQLITE_API const char *sqlite3_vtab_collation(sqlite3_index_info*,int);1006510066/*10067** CAPI3REF: Determine if a virtual table query is DISTINCT10068** METHOD: sqlite3_index_info10069**10070** This API may only be used from within an [xBestIndex|xBestIndex method]10071** of a [virtual table] implementation. The result of calling this10072** interface from outside of xBestIndex() is undefined and probably harmful.10073**10074** ^The sqlite3_vtab_distinct() interface returns an integer between 0 and10075** 3.  The integer returned by sqlite3_vtab_distinct()10076** gives the virtual table additional information about how the query10077** planner wants the output to be ordered. As long as the virtual table10078** can meet the ordering requirements of the query planner, it may set10079** the "orderByConsumed" flag.10080**10081** <ol><li value="0"><p>10082** ^If the sqlite3_vtab_distinct() interface returns 0, that means10083** that the query planner needs the virtual table to return all rows in the10084** sort order defined by the "nOrderBy" and "aOrderBy" fields of the10085** [sqlite3_index_info] object.  This is the default expectation.  If the10086** virtual table outputs all rows in sorted order, then it is always safe for10087** the xBestIndex method to set the "orderByConsumed" flag, regardless of10088** the return value from sqlite3_vtab_distinct().10089** <li value="1"><p>10090** ^(If the sqlite3_vtab_distinct() interface returns 1, that means10091** that the query planner does not need the rows to be returned in sorted order10092** as long as all rows with the same values in all columns identified by the10093** "aOrderBy" field are adjacent.)^  This mode is used when the query planner10094** is doing a GROUP BY.10095** <li value="2"><p>10096** ^(If the sqlite3_vtab_distinct() interface returns 2, that means10097** that the query planner does not need the rows returned in any particular10098** order, as long as rows with the same values in all columns identified10099** by "aOrderBy" are adjacent.)^  ^(Furthermore, when two or more rows10100** contain the same values for all columns identified by "colUsed", all but10101** one such row may optionally be omitted from the result.)^10102** The virtual table is not required to omit rows that are duplicates10103** over the "colUsed" columns, but if the virtual table can do that without10104** too much extra effort, it could potentially help the query to run faster.10105** This mode is used for a DISTINCT query.10106** <li value="3"><p>10107** ^(If the sqlite3_vtab_distinct() interface returns 3, that means the10108** virtual table must return rows in the order defined by "aOrderBy" as10109** if the sqlite3_vtab_distinct() interface had returned 0.  However if10110** two or more rows in the result have the same values for all columns10111** identified by "colUsed", then all but one such row may optionally be10112** omitted.)^  Like when the return value is 2, the virtual table10113** is not required to omit rows that are duplicates over the "colUsed"10114** columns, but if the virtual table can do that without10115** too much extra effort, it could potentially help the query to run faster.10116** This mode is used for queries10117** that have both DISTINCT and ORDER BY clauses.10118** </ol>10119**10120** <p>The following table summarizes the conditions under which the10121** virtual table is allowed to set the "orderByConsumed" flag based on10122** the value returned by sqlite3_vtab_distinct().  This table is a10123** restatement of the previous four paragraphs:10124**10125** <table border=1 cellspacing=0 cellpadding=10 width="90%">10126** <tr>10127** <td valign="top">sqlite3_vtab_distinct() return value10128** <td valign="top">Rows are returned in aOrderBy order10129** <td valign="top">Rows with the same value in all aOrderBy columns are adjacent10130** <td valign="top">Duplicates over all colUsed columns may be omitted10131** <tr><td>0<td>yes<td>yes<td>no10132** <tr><td>1<td>no<td>yes<td>no10133** <tr><td>2<td>no<td>yes<td>yes10134** <tr><td>3<td>yes<td>yes<td>yes10135** </table>10136**10137** ^For the purposes of comparing virtual table output values to see if the10138** values are same value for sorting purposes, two NULL values are considered10139** to be the same.  In other words, the comparison operator is "IS"10140** (or "IS NOT DISTINCT FROM") and not "==".10141**10142** If a virtual table implementation is unable to meet the requirements10143** specified above, then it must not set the "orderByConsumed" flag in the10144** [sqlite3_index_info] object or an incorrect answer may result.10145**10146** ^A virtual table implementation is always free to return rows in any order10147** it wants, as long as the "orderByConsumed" flag is not set.  ^When the10148** the "orderByConsumed" flag is unset, the query planner will add extra10149** [bytecode] to ensure that the final results returned by the SQL query are10150** ordered correctly.  The use of the "orderByConsumed" flag and the10151** sqlite3_vtab_distinct() interface is merely an optimization.  ^Careful10152** use of the sqlite3_vtab_distinct() interface and the "orderByConsumed"10153** flag might help queries against a virtual table to run faster.  Being10154** overly aggressive and setting the "orderByConsumed" flag when it is not10155** valid to do so, on the other hand, might cause SQLite to return incorrect10156** results.10157*/10158SQLITE_API int sqlite3_vtab_distinct(sqlite3_index_info*);1015910160/*10161** CAPI3REF: Identify and handle IN constraints in xBestIndex10162**10163** This interface may only be used from within an10164** [xBestIndex|xBestIndex() method] of a [virtual table] implementation.10165** The result of invoking this interface from any other context is10166** undefined and probably harmful.10167**10168** ^(A constraint on a virtual table of the form10169** "[IN operator|column IN (...)]" is10170** communicated to the xBestIndex method as a10171** [SQLITE_INDEX_CONSTRAINT_EQ] constraint.)^  If xBestIndex wants to use10172** this constraint, it must set the corresponding10173** aConstraintUsage[].argvIndex to a positive integer.  ^(Then, under10174** the usual mode of handling IN operators, SQLite generates [bytecode]10175** that invokes the [xFilter|xFilter() method] once for each value10176** on the right-hand side of the IN operator.)^  Thus the virtual table10177** only sees a single value from the right-hand side of the IN operator10178** at a time.10179**10180** In some cases, however, it would be advantageous for the virtual10181** table to see all values on the right-hand of the IN operator all at10182** once.  The sqlite3_vtab_in() interfaces facilitates this in two ways:10183**10184** <ol>10185** <li><p>10186**   ^A call to sqlite3_vtab_in(P,N,-1) will return true (non-zero)10187**   if and only if the [sqlite3_index_info|P->aConstraint][N] constraint10188**   is an [IN operator] that can be processed all at once.  ^In other words,10189**   sqlite3_vtab_in() with -1 in the third argument is a mechanism10190**   by which the virtual table can ask SQLite if all-at-once processing10191**   of the IN operator is even possible.10192**10193** <li><p>10194**   ^A call to sqlite3_vtab_in(P,N,F) with F==1 or F==0 indicates10195**   to SQLite that the virtual table does or does not want to process10196**   the IN operator all-at-once, respectively.  ^Thus when the third10197**   parameter (F) is non-negative, this interface is the mechanism by10198**   which the virtual table tells SQLite how it wants to process the10199**   IN operator.10200** </ol>10201**10202** ^The sqlite3_vtab_in(P,N,F) interface can be invoked multiple times10203** within the same xBestIndex method call.  ^For any given P,N pair,10204** the return value from sqlite3_vtab_in(P,N,F) will always be the same10205** within the same xBestIndex call.  ^If the interface returns true10206** (non-zero), that means that the constraint is an IN operator10207** that can be processed all-at-once.  ^If the constraint is not an IN10208** operator or cannot be processed all-at-once, then the interface returns10209** false.10210**10211** ^(All-at-once processing of the IN operator is selected if both of the10212** following conditions are met:10213**10214** <ol>10215** <li><p> The P->aConstraintUsage[N].argvIndex value is set to a positive10216** integer.  This is how the virtual table tells SQLite that it wants to10217** use the N-th constraint.10218**10219** <li><p> The last call to sqlite3_vtab_in(P,N,F) for which F was10220** non-negative had F>=1.10221** </ol>)^10222**10223** ^If either or both of the conditions above are false, then SQLite uses10224** the traditional one-at-a-time processing strategy for the IN constraint.10225** ^If both conditions are true, then the argvIndex-th parameter to the10226** xFilter method will be an [sqlite3_value] that appears to be NULL,10227** but which can be passed to [sqlite3_vtab_in_first()] and10228** [sqlite3_vtab_in_next()] to find all values on the right-hand side10229** of the IN constraint.10230*/10231SQLITE_API int sqlite3_vtab_in(sqlite3_index_info*, int iCons, int bHandle);1023210233/*10234** CAPI3REF: Find all elements on the right-hand side of an IN constraint.10235**10236** These interfaces are only useful from within the10237** [xFilter|xFilter() method] of a [virtual table] implementation.10238** The result of invoking these interfaces from any other context10239** is undefined and probably harmful.10240**10241** The X parameter in a call to sqlite3_vtab_in_first(X,P) or10242** sqlite3_vtab_in_next(X,P) should be one of the parameters to the10243** xFilter method which invokes these routines, and specifically10244** a parameter that was previously selected for all-at-once IN constraint10245** processing use the [sqlite3_vtab_in()] interface in the10246** [xBestIndex|xBestIndex method].  ^(If the X parameter is not10247** an xFilter argument that was selected for all-at-once IN constraint10248** processing, then these routines return [SQLITE_ERROR].)^10249**10250** ^(Use these routines to access all values on the right-hand side10251** of the IN constraint using code like the following:10252**10253** <blockquote><pre>10254** &nbsp;  for(rc=sqlite3_vtab_in_first(pList, &pVal);10255** &nbsp;      rc==SQLITE_OK && pVal;10256** &nbsp;      rc=sqlite3_vtab_in_next(pList, &pVal)10257** &nbsp;  ){10258** &nbsp;    // do something with pVal10259** &nbsp;  }10260** &nbsp;  if( rc!=SQLITE_OK ){10261** &nbsp;    // an error has occurred10262** &nbsp;  }10263** </pre></blockquote>)^10264**10265** ^On success, the sqlite3_vtab_in_first(X,P) and sqlite3_vtab_in_next(X,P)10266** routines return SQLITE_OK and set *P to point to the first or next value10267** on the RHS of the IN constraint.  ^If there are no more values on the10268** right hand side of the IN constraint, then *P is set to NULL and these10269** routines return [SQLITE_DONE].  ^The return value might be10270** some other value, such as SQLITE_NOMEM, in the event of a malfunction.10271**10272** The *ppOut values returned by these routines are only valid until the10273** next call to either of these routines or until the end of the xFilter10274** method from which these routines were called.  If the virtual table10275** implementation needs to retain the *ppOut values for longer, it must make10276** copies.  The *ppOut values are [protected sqlite3_value|protected].10277*/10278SQLITE_API int sqlite3_vtab_in_first(sqlite3_value *pVal, sqlite3_value **ppOut);10279SQLITE_API int sqlite3_vtab_in_next(sqlite3_value *pVal, sqlite3_value **ppOut);1028010281/*10282** CAPI3REF: Constraint values in xBestIndex()10283** METHOD: sqlite3_index_info10284**10285** This API may only be used from within the [xBestIndex|xBestIndex method]10286** of a [virtual table] implementation. The result of calling this interface10287** from outside of an xBestIndex method are undefined and probably harmful.10288**10289** ^When the sqlite3_vtab_rhs_value(P,J,V) interface is invoked from within10290** the [xBestIndex] method of a [virtual table] implementation, with P being10291** a copy of the [sqlite3_index_info] object pointer passed into xBestIndex and10292** J being a 0-based index into P->aConstraint[], then this routine10293** attempts to set *V to the value of the right-hand operand of10294** that constraint if the right-hand operand is known.  ^If the10295** right-hand operand is not known, then *V is set to a NULL pointer.10296** ^The sqlite3_vtab_rhs_value(P,J,V) interface returns SQLITE_OK if10297** and only if *V is set to a value.  ^The sqlite3_vtab_rhs_value(P,J,V)10298** inteface returns SQLITE_NOTFOUND if the right-hand side of the J-th10299** constraint is not available.  ^The sqlite3_vtab_rhs_value() interface10300** can return an result code other than SQLITE_OK or SQLITE_NOTFOUND if10301** something goes wrong.10302**10303** The sqlite3_vtab_rhs_value() interface is usually only successful if10304** the right-hand operand of a constraint is a literal value in the original10305** SQL statement.  If the right-hand operand is an expression or a reference10306** to some other column or a [host parameter], then sqlite3_vtab_rhs_value()10307** will probably return [SQLITE_NOTFOUND].10308**10309** ^(Some constraints, such as [SQLITE_INDEX_CONSTRAINT_ISNULL] and10310** [SQLITE_INDEX_CONSTRAINT_ISNOTNULL], have no right-hand operand.  For such10311** constraints, sqlite3_vtab_rhs_value() always returns SQLITE_NOTFOUND.)^10312**10313** ^The [sqlite3_value] object returned in *V is a protected sqlite3_value10314** and remains valid for the duration of the xBestIndex method call.10315** ^When xBestIndex returns, the sqlite3_value object returned by10316** sqlite3_vtab_rhs_value() is automatically deallocated.10317**10318** The "_rhs_" in the name of this routine is an abbreviation for10319** "Right-Hand Side".10320*/10321SQLITE_API int sqlite3_vtab_rhs_value(sqlite3_index_info*, int, sqlite3_value **ppVal);1032210323/*10324** CAPI3REF: Conflict resolution modes10325** KEYWORDS: {conflict resolution mode}10326**10327** These constants are returned by [sqlite3_vtab_on_conflict()] to10328** inform a [virtual table] implementation what the [ON CONFLICT] mode10329** is for the SQL statement being evaluated.10330**10331** Note that the [SQLITE_IGNORE] constant is also used as a potential10332** return value from the [sqlite3_set_authorizer()] callback and that10333** [SQLITE_ABORT] is also a [result code].10334*/10335#define SQLITE_ROLLBACK 110336/* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */10337#define SQLITE_FAIL     310338/* #define SQLITE_ABORT 4  // Also an error code */10339#define SQLITE_REPLACE  51034010341/*10342** CAPI3REF: Prepared Statement Scan Status Opcodes10343** KEYWORDS: {scanstatus options}10344**10345** The following constants can be used for the T parameter to the10346** [sqlite3_stmt_scanstatus(S,X,T,V)] interface.  Each constant designates a10347** different metric for sqlite3_stmt_scanstatus() to return.10348**10349** When the value returned to V is a string, space to hold that string is10350** managed by the prepared statement S and will be automatically freed when10351** S is finalized.10352**10353** Not all values are available for all query elements. When a value is10354** not available, the output variable is set to -1 if the value is numeric,10355** or to NULL if it is a string (SQLITE_SCANSTAT_NAME).10356**10357** <dl>10358** [[SQLITE_SCANSTAT_NLOOP]] <dt>SQLITE_SCANSTAT_NLOOP</dt>10359** <dd>^The [sqlite3_int64] variable pointed to by the V parameter will be10360** set to the total number of times that the X-th loop has run.</dd>10361**10362** [[SQLITE_SCANSTAT_NVISIT]] <dt>SQLITE_SCANSTAT_NVISIT</dt>10363** <dd>^The [sqlite3_int64] variable pointed to by the V parameter will be set10364** to the total number of rows examined by all iterations of the X-th loop.</dd>10365**10366** [[SQLITE_SCANSTAT_EST]] <dt>SQLITE_SCANSTAT_EST</dt>10367** <dd>^The "double" variable pointed to by the V parameter will be set to the10368** query planner's estimate for the average number of rows output from each10369** iteration of the X-th loop.  If the query planner's estimates was accurate,10370** then this value will approximate the quotient NVISIT/NLOOP and the10371** product of this value for all prior loops with the same SELECTID will10372** be the NLOOP value for the current loop.10373**10374** [[SQLITE_SCANSTAT_NAME]] <dt>SQLITE_SCANSTAT_NAME</dt>10375** <dd>^The "const char *" variable pointed to by the V parameter will be set10376** to a zero-terminated UTF-8 string containing the name of the index or table10377** used for the X-th loop.10378**10379** [[SQLITE_SCANSTAT_EXPLAIN]] <dt>SQLITE_SCANSTAT_EXPLAIN</dt>10380** <dd>^The "const char *" variable pointed to by the V parameter will be set10381** to a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN]10382** description for the X-th loop.10383**10384** [[SQLITE_SCANSTAT_SELECTID]] <dt>SQLITE_SCANSTAT_SELECTID</dt>10385** <dd>^The "int" variable pointed to by the V parameter will be set to the10386** id for the X-th query plan element. The id value is unique within the10387** statement. The select-id is the same value as is output in the first10388** column of an [EXPLAIN QUERY PLAN] query.10389**10390** [[SQLITE_SCANSTAT_PARENTID]] <dt>SQLITE_SCANSTAT_PARENTID</dt>10391** <dd>The "int" variable pointed to by the V parameter will be set to the10392** the id of the parent of the current query element, if applicable, or10393** to zero if the query element has no parent. This is the same value as10394** returned in the second column of an [EXPLAIN QUERY PLAN] query.10395**10396** [[SQLITE_SCANSTAT_NCYCLE]] <dt>SQLITE_SCANSTAT_NCYCLE</dt>10397** <dd>The sqlite3_int64 output value is set to the number of cycles,10398** according to the processor time-stamp counter, that elapsed while the10399** query element was being processed. This value is not available for10400** all query elements - if it is unavailable the output variable is10401** set to -1.10402** </dl>10403*/10404#define SQLITE_SCANSTAT_NLOOP    010405#define SQLITE_SCANSTAT_NVISIT   110406#define SQLITE_SCANSTAT_EST      210407#define SQLITE_SCANSTAT_NAME     310408#define SQLITE_SCANSTAT_EXPLAIN  410409#define SQLITE_SCANSTAT_SELECTID 510410#define SQLITE_SCANSTAT_PARENTID 610411#define SQLITE_SCANSTAT_NCYCLE   71041210413/*10414** CAPI3REF: Prepared Statement Scan Status10415** METHOD: sqlite3_stmt10416**10417** These interfaces return information about the predicted and measured10418** performance for pStmt.  Advanced applications can use this10419** interface to compare the predicted and the measured performance and10420** issue warnings and/or rerun [ANALYZE] if discrepancies are found.10421**10422** Since this interface is expected to be rarely used, it is only10423** available if SQLite is compiled using the [SQLITE_ENABLE_STMT_SCANSTATUS]10424** compile-time option.10425**10426** The "iScanStatusOp" parameter determines which status information to return.10427** The "iScanStatusOp" must be one of the [scanstatus options] or the behavior10428** of this interface is undefined. ^The requested measurement is written into10429** a variable pointed to by the "pOut" parameter.10430**10431** The "flags" parameter must be passed a mask of flags. At present only10432** one flag is defined - SQLITE_SCANSTAT_COMPLEX. If SQLITE_SCANSTAT_COMPLEX10433** is specified, then status information is available for all elements10434** of a query plan that are reported by "EXPLAIN QUERY PLAN" output. If10435** SQLITE_SCANSTAT_COMPLEX is not specified, then only query plan elements10436** that correspond to query loops (the "SCAN..." and "SEARCH..." elements of10437** the EXPLAIN QUERY PLAN output) are available. Invoking API10438** sqlite3_stmt_scanstatus() is equivalent to calling10439** sqlite3_stmt_scanstatus_v2() with a zeroed flags parameter.10440**10441** Parameter "idx" identifies the specific query element to retrieve statistics10442** for. Query elements are numbered starting from zero. A value of -1 may be10443** to query for statistics regarding the entire query. ^If idx is out of range10444** - less than -1 or greater than or equal to the total number of query10445** elements used to implement the statement - a non-zero value is returned and10446** the variable that pOut points to is unchanged.10447**10448** See also: [sqlite3_stmt_scanstatus_reset()]10449*/10450SQLITE_API int sqlite3_stmt_scanstatus(10451  sqlite3_stmt *pStmt,      /* Prepared statement for which info desired */10452  int idx,                  /* Index of loop to report on */10453  int iScanStatusOp,        /* Information desired.  SQLITE_SCANSTAT_* */10454  void *pOut                /* Result written here */10455);10456SQLITE_API int sqlite3_stmt_scanstatus_v2(10457  sqlite3_stmt *pStmt,      /* Prepared statement for which info desired */10458  int idx,                  /* Index of loop to report on */10459  int iScanStatusOp,        /* Information desired.  SQLITE_SCANSTAT_* */10460  int flags,                /* Mask of flags defined below */10461  void *pOut                /* Result written here */10462);1046310464/*10465** CAPI3REF: Prepared Statement Scan Status10466** KEYWORDS: {scan status flags}10467*/10468#define SQLITE_SCANSTAT_COMPLEX 0x00011046910470/*10471** CAPI3REF: Zero Scan-Status Counters10472** METHOD: sqlite3_stmt10473**10474** ^Zero all [sqlite3_stmt_scanstatus()] related event counters.10475**10476** This API is only available if the library is built with pre-processor10477** symbol [SQLITE_ENABLE_STMT_SCANSTATUS] defined.10478*/10479SQLITE_API void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*);1048010481/*10482** CAPI3REF: Flush caches to disk mid-transaction10483** METHOD: sqlite310484**10485** ^If a write-transaction is open on [database connection] D when the10486** [sqlite3_db_cacheflush(D)] interface invoked, any dirty10487** pages in the pager-cache that are not currently in use are written out10488** to disk. A dirty page may be in use if a database cursor created by an10489** active SQL statement is reading from it, or if it is page 1 of a database10490** file (page 1 is always "in use").  ^The [sqlite3_db_cacheflush(D)]10491** interface flushes caches for all schemas - "main", "temp", and10492** any [attached] databases.10493**10494** ^If this function needs to obtain extra database locks before dirty pages10495** can be flushed to disk, it does so. ^If those locks cannot be obtained10496** immediately and there is a busy-handler callback configured, it is invoked10497** in the usual manner. ^If the required lock still cannot be obtained, then10498** the database is skipped and an attempt made to flush any dirty pages10499** belonging to the next (if any) database. ^If any databases are skipped10500** because locks cannot be obtained, but no other error occurs, this10501** function returns SQLITE_BUSY.10502**10503** ^If any other error occurs while flushing dirty pages to disk (for10504** example an IO error or out-of-memory condition), then processing is10505** abandoned and an SQLite [error code] is returned to the caller immediately.10506**10507** ^Otherwise, if no error occurs, [sqlite3_db_cacheflush()] returns SQLITE_OK.10508**10509** ^This function does not set the database handle error code or message10510** returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions.10511*/10512SQLITE_API int sqlite3_db_cacheflush(sqlite3*);1051310514/*10515** CAPI3REF: The pre-update hook.10516** METHOD: sqlite310517**10518** ^These interfaces are only available if SQLite is compiled using the10519** [SQLITE_ENABLE_PREUPDATE_HOOK] compile-time option.10520**10521** ^The [sqlite3_preupdate_hook()] interface registers a callback function10522** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation10523** on a database table.10524** ^At most one preupdate hook may be registered at a time on a single10525** [database connection]; each call to [sqlite3_preupdate_hook()] overrides10526** the previous setting.10527** ^The preupdate hook is disabled by invoking [sqlite3_preupdate_hook()]10528** with a NULL pointer as the second parameter.10529** ^The third parameter to [sqlite3_preupdate_hook()] is passed through as10530** the first parameter to callbacks.10531**10532** ^The preupdate hook only fires for changes to real database tables; the10533** preupdate hook is not invoked for changes to [virtual tables] or to10534** system tables like sqlite_sequence or sqlite_stat1.10535**10536** ^The second parameter to the preupdate callback is a pointer to10537** the [database connection] that registered the preupdate hook.10538** ^The third parameter to the preupdate callback is one of the constants10539** [SQLITE_INSERT], [SQLITE_DELETE], or [SQLITE_UPDATE] to identify the10540** kind of update operation that is about to occur.10541** ^(The fourth parameter to the preupdate callback is the name of the10542** database within the database connection that is being modified.  This10543** will be "main" for the main database or "temp" for TEMP tables or10544** the name given after the AS keyword in the [ATTACH] statement for attached10545** databases.)^10546** ^The fifth parameter to the preupdate callback is the name of the10547** table that is being modified.10548**10549** For an UPDATE or DELETE operation on a [rowid table], the sixth10550** parameter passed to the preupdate callback is the initial [rowid] of the10551** row being modified or deleted. For an INSERT operation on a rowid table,10552** or any operation on a WITHOUT ROWID table, the value of the sixth10553** parameter is undefined. For an INSERT or UPDATE on a rowid table the10554** seventh parameter is the final rowid value of the row being inserted10555** or updated. The value of the seventh parameter passed to the callback10556** function is not defined for operations on WITHOUT ROWID tables, or for10557** DELETE operations on rowid tables.10558**10559** ^The sqlite3_preupdate_hook(D,C,P) function returns the P argument from10560** the previous call on the same [database connection] D, or NULL for10561** the first call on D.10562**10563** The [sqlite3_preupdate_old()], [sqlite3_preupdate_new()],10564** [sqlite3_preupdate_count()], and [sqlite3_preupdate_depth()] interfaces10565** provide additional information about a preupdate event. These routines10566** may only be called from within a preupdate callback.  Invoking any of10567** these routines from outside of a preupdate callback or with a10568** [database connection] pointer that is different from the one supplied10569** to the preupdate callback results in undefined and probably undesirable10570** behavior.10571**10572** ^The [sqlite3_preupdate_count(D)] interface returns the number of columns10573** in the row that is being inserted, updated, or deleted.10574**10575** ^The [sqlite3_preupdate_old(D,N,P)] interface writes into P a pointer to10576** a [protected sqlite3_value] that contains the value of the Nth column of10577** the table row before it is updated.  The N parameter must be between 010578** and one less than the number of columns or the behavior will be10579** undefined. This must only be used within SQLITE_UPDATE and SQLITE_DELETE10580** preupdate callbacks; if it is used by an SQLITE_INSERT callback then the10581** behavior is undefined.  The [sqlite3_value] that P points to10582** will be destroyed when the preupdate callback returns.10583**10584** ^The [sqlite3_preupdate_new(D,N,P)] interface writes into P a pointer to10585** a [protected sqlite3_value] that contains the value of the Nth column of10586** the table row after it is updated.  The N parameter must be between 010587** and one less than the number of columns or the behavior will be10588** undefined. This must only be used within SQLITE_INSERT and SQLITE_UPDATE10589** preupdate callbacks; if it is used by an SQLITE_DELETE callback then the10590** behavior is undefined.  The [sqlite3_value] that P points to10591** will be destroyed when the preupdate callback returns.10592**10593** ^The [sqlite3_preupdate_depth(D)] interface returns 0 if the preupdate10594** callback was invoked as a result of a direct insert, update, or delete10595** operation; or 1 for inserts, updates, or deletes invoked by top-level10596** triggers; or 2 for changes resulting from triggers called by top-level10597** triggers; and so forth.10598**10599** When the [sqlite3_blob_write()] API is used to update a blob column,10600** the pre-update hook is invoked with SQLITE_DELETE. This is because the10601** in this case the new values are not available. In this case, when a10602** callback made with op==SQLITE_DELETE is actually a write using the10603** sqlite3_blob_write() API, the [sqlite3_preupdate_blobwrite()] returns10604** the index of the column being written. In other cases, where the10605** pre-update hook is being invoked for some other reason, including a10606** regular DELETE, sqlite3_preupdate_blobwrite() returns -1.10607**10608** See also:  [sqlite3_update_hook()]10609*/10610#if defined(SQLITE_ENABLE_PREUPDATE_HOOK)10611SQLITE_API void *sqlite3_preupdate_hook(10612  sqlite3 *db,10613  void(*xPreUpdate)(10614    void *pCtx,                   /* Copy of third arg to preupdate_hook() */10615    sqlite3 *db,                  /* Database handle */10616    int op,                       /* SQLITE_UPDATE, DELETE or INSERT */10617    char const *zDb,              /* Database name */10618    char const *zName,            /* Table name */10619    sqlite3_int64 iKey1,          /* Rowid of row about to be deleted/updated */10620    sqlite3_int64 iKey2           /* New rowid value (for a rowid UPDATE) */10621  ),10622  void*10623);10624SQLITE_API int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **);10625SQLITE_API int sqlite3_preupdate_count(sqlite3 *);10626SQLITE_API int sqlite3_preupdate_depth(sqlite3 *);10627SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);10628SQLITE_API int sqlite3_preupdate_blobwrite(sqlite3 *);10629#endif1063010631/*10632** CAPI3REF: Low-level system error code10633** METHOD: sqlite310634**10635** ^Attempt to return the underlying operating system error code or error10636** number that caused the most recent I/O error or failure to open a file.10637** The return value is OS-dependent.  For example, on unix systems, after10638** [sqlite3_open_v2()] returns [SQLITE_CANTOPEN], this interface could be10639** called to get back the underlying "errno" that caused the problem, such10640** as ENOSPC, EAUTH, EISDIR, and so forth.10641*/10642SQLITE_API int sqlite3_system_errno(sqlite3*);1064310644/*10645** CAPI3REF: Database Snapshot10646** KEYWORDS: {snapshot} {sqlite3_snapshot}10647**10648** An instance of the snapshot object records the state of a [WAL mode]10649** database for some specific point in history.10650**10651** In [WAL mode], multiple [database connections] that are open on the10652** same database file can each be reading a different historical version10653** of the database file.  When a [database connection] begins a read10654** transaction, that connection sees an unchanging copy of the database10655** as it existed for the point in time when the transaction first started.10656** Subsequent changes to the database from other connections are not seen10657** by the reader until a new read transaction is started.10658**10659** The sqlite3_snapshot object records state information about an historical10660** version of the database file so that it is possible to later open a new read10661** transaction that sees that historical version of the database rather than10662** the most recent version.10663*/10664typedef struct sqlite3_snapshot {10665  unsigned char hidden[48];10666} sqlite3_snapshot;1066710668/*10669** CAPI3REF: Record A Database Snapshot10670** CONSTRUCTOR: sqlite3_snapshot10671**10672** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a10673** new [sqlite3_snapshot] object that records the current state of10674** schema S in database connection D.  ^On success, the10675** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly10676** created [sqlite3_snapshot] object into *P and returns SQLITE_OK.10677** If there is not already a read-transaction open on schema S when10678** this function is called, one is opened automatically.10679**10680** If a read-transaction is opened by this function, then it is guaranteed10681** that the returned snapshot object may not be invalidated by a database10682** writer or checkpointer until after the read-transaction is closed. This10683** is not guaranteed if a read-transaction is already open when this10684** function is called. In that case, any subsequent write or checkpoint10685** operation on the database may invalidate the returned snapshot handle,10686** even while the read-transaction remains open.10687**10688** The following must be true for this function to succeed. If any of10689** the following statements are false when sqlite3_snapshot_get() is10690** called, SQLITE_ERROR is returned. The final value of *P is undefined10691** in this case.10692**10693** <ul>10694**   <li> The database handle must not be in [autocommit mode].10695**10696**   <li> Schema S of [database connection] D must be a [WAL mode] database.10697**10698**   <li> There must not be a write transaction open on schema S of database10699**        connection D.10700**10701**   <li> One or more transactions must have been written to the current wal10702**        file since it was created on disk (by any connection). This means10703**        that a snapshot cannot be taken on a wal mode database with no wal10704**        file immediately after it is first opened. At least one transaction10705**        must be written to it first.10706** </ul>10707**10708** This function may also return SQLITE_NOMEM.  If it is called with the10709** database handle in autocommit mode but fails for some other reason,10710** whether or not a read transaction is opened on schema S is undefined.10711**10712** The [sqlite3_snapshot] object returned from a successful call to10713** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()]10714** to avoid a memory leak.10715**10716** The [sqlite3_snapshot_get()] interface is only available when the10717** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.10718*/10719SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_get(10720  sqlite3 *db,10721  const char *zSchema,10722  sqlite3_snapshot **ppSnapshot10723);1072410725/*10726** CAPI3REF: Start a read transaction on an historical snapshot10727** METHOD: sqlite3_snapshot10728**10729** ^The [sqlite3_snapshot_open(D,S,P)] interface either starts a new read10730** transaction or upgrades an existing one for schema S of10731** [database connection] D such that the read transaction refers to10732** historical [snapshot] P, rather than the most recent change to the10733** database. ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK10734** on success or an appropriate [error code] if it fails.10735**10736** ^In order to succeed, the database connection must not be in10737** [autocommit mode] when [sqlite3_snapshot_open(D,S,P)] is called. If there10738** is already a read transaction open on schema S, then the database handle10739** must have no active statements (SELECT statements that have been passed10740** to sqlite3_step() but not sqlite3_reset() or sqlite3_finalize()).10741** SQLITE_ERROR is returned if either of these conditions is violated, or10742** if schema S does not exist, or if the snapshot object is invalid.10743**10744** ^A call to sqlite3_snapshot_open() will fail to open if the specified10745** snapshot has been overwritten by a [checkpoint]. In this case10746** SQLITE_ERROR_SNAPSHOT is returned.10747**10748** If there is already a read transaction open when this function is10749** invoked, then the same read transaction remains open (on the same10750** database snapshot) if SQLITE_ERROR, SQLITE_BUSY or SQLITE_ERROR_SNAPSHOT10751** is returned. If another error code - for example SQLITE_PROTOCOL or an10752** SQLITE_IOERR error code - is returned, then the final state of the10753** read transaction is undefined. If SQLITE_OK is returned, then the10754** read transaction is now open on database snapshot P.10755**10756** ^(A call to [sqlite3_snapshot_open(D,S,P)] will fail if the10757** database connection D does not know that the database file for10758** schema S is in [WAL mode].  A database connection might not know10759** that the database file is in [WAL mode] if there has been no prior10760** I/O on that database connection, or if the database entered [WAL mode]10761** after the most recent I/O on the database connection.)^10762** (Hint: Run "[PRAGMA application_id]" against a newly opened10763** database connection in order to make it ready to use snapshots.)10764**10765** The [sqlite3_snapshot_open()] interface is only available when the10766** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.10767*/10768SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_open(10769  sqlite3 *db,10770  const char *zSchema,10771  sqlite3_snapshot *pSnapshot10772);1077310774/*10775** CAPI3REF: Destroy a snapshot10776** DESTRUCTOR: sqlite3_snapshot10777**10778** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P.10779** The application must eventually free every [sqlite3_snapshot] object10780** using this routine to avoid a memory leak.10781**10782** The [sqlite3_snapshot_free()] interface is only available when the10783** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.10784*/10785SQLITE_API SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*);1078610787/*10788** CAPI3REF: Compare the ages of two snapshot handles.10789** METHOD: sqlite3_snapshot10790**10791** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages10792** of two valid snapshot handles.10793**10794** If the two snapshot handles are not associated with the same database10795** file, the result of the comparison is undefined.10796**10797** Additionally, the result of the comparison is only valid if both of the10798** snapshot handles were obtained by calling sqlite3_snapshot_get() since the10799** last time the wal file was deleted. The wal file is deleted when the10800** database is changed back to rollback mode or when the number of database10801** clients drops to zero. If either snapshot handle was obtained before the10802** wal file was last deleted, the value returned by this function10803** is undefined.10804**10805** Otherwise, this API returns a negative value if P1 refers to an older10806** snapshot than P2, zero if the two handles refer to the same database10807** snapshot, and a positive value if P1 is a newer snapshot than P2.10808**10809** This interface is only available if SQLite is compiled with the10810** [SQLITE_ENABLE_SNAPSHOT] option.10811*/10812SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp(10813  sqlite3_snapshot *p1,10814  sqlite3_snapshot *p210815);1081610817/*10818** CAPI3REF: Recover snapshots from a wal file10819** METHOD: sqlite3_snapshot10820**10821** If a [WAL file] remains on disk after all database connections close10822** (either through the use of the [SQLITE_FCNTL_PERSIST_WAL] [file control]10823** or because the last process to have the database opened exited without10824** calling [sqlite3_close()]) and a new connection is subsequently opened10825** on that database and [WAL file], the [sqlite3_snapshot_open()] interface10826** will only be able to open the last transaction added to the WAL file10827** even though the WAL file contains other valid transactions.10828**10829** This function attempts to scan the WAL file associated with database zDb10830** of database handle db and make all valid snapshots available to10831** sqlite3_snapshot_open(). It is an error if there is already a read10832** transaction open on the database, or if the database is not a WAL mode10833** database.10834**10835** SQLITE_OK is returned if successful, or an SQLite error code otherwise.10836**10837** This interface is only available if SQLite is compiled with the10838** [SQLITE_ENABLE_SNAPSHOT] option.10839*/10840SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb);1084110842/*10843** CAPI3REF: Serialize a database10844**10845** The sqlite3_serialize(D,S,P,F) interface returns a pointer to10846** memory that is a serialization of the S database on10847** [database connection] D.  If S is a NULL pointer, the main database is used.10848** If P is not a NULL pointer, then the size of the database in bytes10849** is written into *P.10850**10851** For an ordinary on-disk database file, the serialization is just a10852** copy of the disk file.  For an in-memory database or a "TEMP" database,10853** the serialization is the same sequence of bytes which would be written10854** to disk if that database where backed up to disk.10855**10856** The usual case is that sqlite3_serialize() copies the serialization of10857** the database into memory obtained from [sqlite3_malloc64()] and returns10858** a pointer to that memory.  The caller is responsible for freeing the10859** returned value to avoid a memory leak.  However, if the F argument10860** contains the SQLITE_SERIALIZE_NOCOPY bit, then no memory allocations10861** are made, and the sqlite3_serialize() function will return a pointer10862** to the contiguous memory representation of the database that SQLite10863** is currently using for that database, or NULL if the no such contiguous10864** memory representation of the database exists.  A contiguous memory10865** representation of the database will usually only exist if there has10866** been a prior call to [sqlite3_deserialize(D,S,...)] with the same10867** values of D and S.10868** The size of the database is written into *P even if the10869** SQLITE_SERIALIZE_NOCOPY bit is set but no contiguous copy10870** of the database exists.10871**10872** After the call, if the SQLITE_SERIALIZE_NOCOPY bit had been set,10873** the returned buffer content will remain accessible and unchanged10874** until either the next write operation on the connection or when10875** the connection is closed, and applications must not modify the10876** buffer. If the bit had been clear, the returned buffer will not10877** be accessed by SQLite after the call.10878**10879** A call to sqlite3_serialize(D,S,P,F) might return NULL even if the10880** SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory10881** allocation error occurs.10882**10883** This interface is omitted if SQLite is compiled with the10884** [SQLITE_OMIT_DESERIALIZE] option.10885*/10886SQLITE_API unsigned char *sqlite3_serialize(10887  sqlite3 *db,           /* The database connection */10888  const char *zSchema,   /* Which DB to serialize. ex: "main", "temp", ... */10889  sqlite3_int64 *piSize, /* Write size of the DB here, if not NULL */10890  unsigned int mFlags    /* Zero or more SQLITE_SERIALIZE_* flags */10891);1089210893/*10894** CAPI3REF: Flags for sqlite3_serialize10895**10896** Zero or more of the following constants can be OR-ed together for10897** the F argument to [sqlite3_serialize(D,S,P,F)].10898**10899** SQLITE_SERIALIZE_NOCOPY means that [sqlite3_serialize()] will return10900** a pointer to contiguous in-memory database that it is currently using,10901** without making a copy of the database.  If SQLite is not currently using10902** a contiguous in-memory database, then this option causes10903** [sqlite3_serialize()] to return a NULL pointer.  SQLite will only be10904** using a contiguous in-memory database if it has been initialized by a10905** prior call to [sqlite3_deserialize()].10906*/10907#define SQLITE_SERIALIZE_NOCOPY 0x001   /* Do no memory allocations */1090810909/*10910** CAPI3REF: Deserialize a database10911**10912** The sqlite3_deserialize(D,S,P,N,M,F) interface causes the10913** [database connection] D to disconnect from database S and then10914** reopen S as an in-memory database based on the serialization contained10915** in P.  The serialized database P is N bytes in size.  M is the size of10916** the buffer P, which might be larger than N.  If M is larger than N, and10917** the SQLITE_DESERIALIZE_READONLY bit is not set in F, then SQLite is10918** permitted to add content to the in-memory database as long as the total10919** size does not exceed M bytes.10920**10921** If the SQLITE_DESERIALIZE_FREEONCLOSE bit is set in F, then SQLite will10922** invoke sqlite3_free() on the serialization buffer when the database10923** connection closes.  If the SQLITE_DESERIALIZE_RESIZEABLE bit is set, then10924** SQLite will try to increase the buffer size using sqlite3_realloc64()10925** if writes on the database cause it to grow larger than M bytes.10926**10927** Applications must not modify the buffer P or invalidate it before10928** the database connection D is closed.10929**10930** The sqlite3_deserialize() interface will fail with SQLITE_BUSY if the10931** database is currently in a read transaction or is involved in a backup10932** operation.10933**10934** It is not possible to deserialized into the TEMP database.  If the10935** S argument to sqlite3_deserialize(D,S,P,N,M,F) is "temp" then the10936** function returns SQLITE_ERROR.10937**10938** The deserialized database should not be in [WAL mode].  If the database10939** is in WAL mode, then any attempt to use the database file will result10940** in an [SQLITE_CANTOPEN] error.  The application can set the10941** [file format version numbers] (bytes 18 and 19) of the input database P10942** to 0x01 prior to invoking sqlite3_deserialize(D,S,P,N,M,F) to force the10943** database file into rollback mode and work around this limitation.10944**10945** If sqlite3_deserialize(D,S,P,N,M,F) fails for any reason and if the10946** SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F, then10947** [sqlite3_free()] is invoked on argument P prior to returning.10948**10949** This interface is omitted if SQLite is compiled with the10950** [SQLITE_OMIT_DESERIALIZE] option.10951*/10952SQLITE_API int sqlite3_deserialize(10953  sqlite3 *db,            /* The database connection */10954  const char *zSchema,    /* Which DB to reopen with the deserialization */10955  unsigned char *pData,   /* The serialized database content */10956  sqlite3_int64 szDb,     /* Number bytes in the deserialization */10957  sqlite3_int64 szBuf,    /* Total size of buffer pData[] */10958  unsigned mFlags         /* Zero or more SQLITE_DESERIALIZE_* flags */10959);1096010961/*10962** CAPI3REF: Flags for sqlite3_deserialize()10963**10964** The following are allowed values for 6th argument (the F argument) to10965** the [sqlite3_deserialize(D,S,P,N,M,F)] interface.10966**10967** The SQLITE_DESERIALIZE_FREEONCLOSE means that the database serialization10968** in the P argument is held in memory obtained from [sqlite3_malloc64()]10969** and that SQLite should take ownership of this memory and automatically10970** free it when it has finished using it.  Without this flag, the caller10971** is responsible for freeing any dynamically allocated memory.10972**10973** The SQLITE_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed to10974** grow the size of the database using calls to [sqlite3_realloc64()].  This10975** flag should only be used if SQLITE_DESERIALIZE_FREEONCLOSE is also used.10976** Without this flag, the deserialized database cannot increase in size beyond10977** the number of bytes specified by the M parameter.10978**10979** The SQLITE_DESERIALIZE_READONLY flag means that the deserialized database10980** should be treated as read-only.10981*/10982#define SQLITE_DESERIALIZE_FREEONCLOSE 1 /* Call sqlite3_free() on close */10983#define SQLITE_DESERIALIZE_RESIZEABLE  2 /* Resize using sqlite3_realloc64() */10984#define SQLITE_DESERIALIZE_READONLY    4 /* Database is read-only */1098510986/*10987** Undo the hack that converts floating point types to integer for10988** builds on processors without floating point support.10989*/10990#ifdef SQLITE_OMIT_FLOATING_POINT10991# undef double10992#endif1099310994#if defined(__wasi__)10995# undef SQLITE_WASI10996# define SQLITE_WASI 110997# ifndef SQLITE_OMIT_LOAD_EXTENSION10998#  define SQLITE_OMIT_LOAD_EXTENSION10999# endif11000# ifndef SQLITE_THREADSAFE11001#  define SQLITE_THREADSAFE 011002# endif11003#endif1100411005#ifdef __cplusplus11006}  /* End of the 'extern "C"' block */11007#endif11008/* #endif for SQLITE3_H will be added by mksqlite3.tcl */1100911010/******** Begin file sqlite3rtree.h *********/11011/*11012** 2010 August 3011013**11014** The author disclaims copyright to this source code.  In place of11015** a legal notice, here is a blessing:11016**11017**    May you do good and not evil.11018**    May you find forgiveness for yourself and forgive others.11019**    May you share freely, never taking more than you give.11020**11021*************************************************************************11022*/1102311024#ifndef _SQLITE3RTREE_H_11025#define _SQLITE3RTREE_H_110261102711028#ifdef __cplusplus11029extern "C" {11030#endif1103111032typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry;11033typedef struct sqlite3_rtree_query_info sqlite3_rtree_query_info;1103411035/* The double-precision datatype used by RTree depends on the11036** SQLITE_RTREE_INT_ONLY compile-time option.11037*/11038#ifdef SQLITE_RTREE_INT_ONLY11039  typedef sqlite3_int64 sqlite3_rtree_dbl;11040#else11041  typedef double sqlite3_rtree_dbl;11042#endif1104311044/*11045** Register a geometry callback named zGeom that can be used as part of an11046** R-Tree geometry query as follows:11047**11048**   SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...)11049*/11050SQLITE_API int sqlite3_rtree_geometry_callback(11051  sqlite3 *db,11052  const char *zGeom,11053  int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*),11054  void *pContext11055);110561105711058/*11059** A pointer to a structure of the following type is passed as the first11060** argument to callbacks registered using rtree_geometry_callback().11061*/11062struct sqlite3_rtree_geometry {11063  void *pContext;                 /* Copy of pContext passed to s_r_g_c() */11064  int nParam;                     /* Size of array aParam[] */11065  sqlite3_rtree_dbl *aParam;      /* Parameters passed to SQL geom function */11066  void *pUser;                    /* Callback implementation user data */11067  void (*xDelUser)(void *);       /* Called by SQLite to clean up pUser */11068};1106911070/*11071** Register a 2nd-generation geometry callback named zScore that can be11072** used as part of an R-Tree geometry query as follows:11073**11074**   SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...)11075*/11076SQLITE_API int sqlite3_rtree_query_callback(11077  sqlite3 *db,11078  const char *zQueryFunc,11079  int (*xQueryFunc)(sqlite3_rtree_query_info*),11080  void *pContext,11081  void (*xDestructor)(void*)11082);110831108411085/*11086** A pointer to a structure of the following type is passed as the11087** argument to scored geometry callback registered using11088** sqlite3_rtree_query_callback().11089**11090** Note that the first 5 fields of this structure are identical to11091** sqlite3_rtree_geometry.  This structure is a subclass of11092** sqlite3_rtree_geometry.11093*/11094struct sqlite3_rtree_query_info {11095  void *pContext;                   /* pContext from when function registered */11096  int nParam;                       /* Number of function parameters */11097  sqlite3_rtree_dbl *aParam;        /* value of function parameters */11098  void *pUser;                      /* callback can use this, if desired */11099  void (*xDelUser)(void*);          /* function to free pUser */11100  sqlite3_rtree_dbl *aCoord;        /* Coordinates of node or entry to check */11101  unsigned int *anQueue;            /* Number of pending entries in the queue */11102  int nCoord;                       /* Number of coordinates */11103  int iLevel;                       /* Level of current node or entry */11104  int mxLevel;                      /* The largest iLevel value in the tree */11105  sqlite3_int64 iRowid;             /* Rowid for current entry */11106  sqlite3_rtree_dbl rParentScore;   /* Score of parent node */11107  int eParentWithin;                /* Visibility of parent node */11108  int eWithin;                      /* OUT: Visibility */11109  sqlite3_rtree_dbl rScore;         /* OUT: Write the score here */11110  /* The following fields are only available in 3.8.11 and later */11111  sqlite3_value **apSqlParam;       /* Original SQL values of parameters */11112};1111311114/*11115** Allowed values for sqlite3_rtree_query.eWithin and .eParentWithin.11116*/11117#define NOT_WITHIN       0   /* Object completely outside of query region */11118#define PARTLY_WITHIN    1   /* Object partially overlaps query region */11119#define FULLY_WITHIN     2   /* Object fully contained within query region */111201112111122#ifdef __cplusplus11123}  /* end of the 'extern "C"' block */11124#endif1112511126#endif  /* ifndef _SQLITE3RTREE_H_ */1112711128/******** End of sqlite3rtree.h *********/11129/******** Begin file sqlite3session.h *********/1113011131#if !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION)11132#define __SQLITESESSION_H_ 11113311134/*11135** Make sure we can call this stuff from C++.11136*/11137#ifdef __cplusplus11138extern "C" {11139#endif111401114111142/*11143** CAPI3REF: Session Object Handle11144**11145** An instance of this object is a [session] that can be used to11146** record changes to a database.11147*/11148typedef struct sqlite3_session sqlite3_session;1114911150/*11151** CAPI3REF: Changeset Iterator Handle11152**11153** An instance of this object acts as a cursor for iterating11154** over the elements of a [changeset] or [patchset].11155*/11156typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;1115711158/*11159** CAPI3REF: Create A New Session Object11160** CONSTRUCTOR: sqlite3_session11161**11162** Create a new session object attached to database handle db. If successful,11163** a pointer to the new object is written to *ppSession and SQLITE_OK is11164** returned. If an error occurs, *ppSession is set to NULL and an SQLite11165** error code (e.g. SQLITE_NOMEM) is returned.11166**11167** It is possible to create multiple session objects attached to a single11168** database handle.11169**11170** Session objects created using this function should be deleted using the11171** [sqlite3session_delete()] function before the database handle that they11172** are attached to is itself closed. If the database handle is closed before11173** the session object is deleted, then the results of calling any session11174** module function, including [sqlite3session_delete()] on the session object11175** are undefined.11176**11177** Because the session module uses the [sqlite3_preupdate_hook()] API, it11178** is not possible for an application to register a pre-update hook on a11179** database handle that has one or more session objects attached. Nor is11180** it possible to create a session object attached to a database handle for11181** which a pre-update hook is already defined. The results of attempting11182** either of these things are undefined.11183**11184** The session object will be used to create changesets for tables in11185** database zDb, where zDb is either "main", or "temp", or the name of an11186** attached database. It is not an error if database zDb is not attached11187** to the database when the session object is created.11188*/11189SQLITE_API int sqlite3session_create(11190  sqlite3 *db,                    /* Database handle */11191  const char *zDb,                /* Name of db (e.g. "main") */11192  sqlite3_session **ppSession     /* OUT: New session object */11193);1119411195/*11196** CAPI3REF: Delete A Session Object11197** DESTRUCTOR: sqlite3_session11198**11199** Delete a session object previously allocated using11200** [sqlite3session_create()]. Once a session object has been deleted, the11201** results of attempting to use pSession with any other session module11202** function are undefined.11203**11204** Session objects must be deleted before the database handle to which they11205** are attached is closed. Refer to the documentation for11206** [sqlite3session_create()] for details.11207*/11208SQLITE_API void sqlite3session_delete(sqlite3_session *pSession);1120911210/*11211** CAPI3REF: Configure a Session Object11212** METHOD: sqlite3_session11213**11214** This method is used to configure a session object after it has been11215** created. At present the only valid values for the second parameter are11216** [SQLITE_SESSION_OBJCONFIG_SIZE] and [SQLITE_SESSION_OBJCONFIG_ROWID].11217**11218*/11219SQLITE_API int sqlite3session_object_config(sqlite3_session*, int op, void *pArg);1122011221/*11222** CAPI3REF: Options for sqlite3session_object_config11223**11224** The following values may passed as the the 2nd parameter to11225** sqlite3session_object_config().11226**11227** <dt>SQLITE_SESSION_OBJCONFIG_SIZE <dd>11228**   This option is used to set, clear or query the flag that enables11229**   the [sqlite3session_changeset_size()] API. Because it imposes some11230**   computational overhead, this API is disabled by default. Argument11231**   pArg must point to a value of type (int). If the value is initially11232**   0, then the sqlite3session_changeset_size() API is disabled. If it11233**   is greater than 0, then the same API is enabled. Or, if the initial11234**   value is less than zero, no change is made. In all cases the (int)11235**   variable is set to 1 if the sqlite3session_changeset_size() API is11236**   enabled following the current call, or 0 otherwise.11237**11238**   It is an error (SQLITE_MISUSE) to attempt to modify this setting after11239**   the first table has been attached to the session object.11240**11241** <dt>SQLITE_SESSION_OBJCONFIG_ROWID <dd>11242**   This option is used to set, clear or query the flag that enables11243**   collection of data for tables with no explicit PRIMARY KEY.11244**11245**   Normally, tables with no explicit PRIMARY KEY are simply ignored11246**   by the sessions module. However, if this flag is set, it behaves11247**   as if such tables have a column "_rowid_ INTEGER PRIMARY KEY" inserted11248**   as their leftmost columns.11249**11250**   It is an error (SQLITE_MISUSE) to attempt to modify this setting after11251**   the first table has been attached to the session object.11252*/11253#define SQLITE_SESSION_OBJCONFIG_SIZE  111254#define SQLITE_SESSION_OBJCONFIG_ROWID 21125511256/*11257** CAPI3REF: Enable Or Disable A Session Object11258** METHOD: sqlite3_session11259**11260** Enable or disable the recording of changes by a session object. When11261** enabled, a session object records changes made to the database. When11262** disabled - it does not. A newly created session object is enabled.11263** Refer to the documentation for [sqlite3session_changeset()] for further11264** details regarding how enabling and disabling a session object affects11265** the eventual changesets.11266**11267** Passing zero to this function disables the session. Passing a value11268** greater than zero enables it. Passing a value less than zero is a11269** no-op, and may be used to query the current state of the session.11270**11271** The return value indicates the final state of the session object: 0 if11272** the session is disabled, or 1 if it is enabled.11273*/11274SQLITE_API int sqlite3session_enable(sqlite3_session *pSession, int bEnable);1127511276/*11277** CAPI3REF: Set Or Clear the Indirect Change Flag11278** METHOD: sqlite3_session11279**11280** Each change recorded by a session object is marked as either direct or11281** indirect. A change is marked as indirect if either:11282**11283** <ul>11284**   <li> The session object "indirect" flag is set when the change is11285**        made, or11286**   <li> The change is made by an SQL trigger or foreign key action11287**        instead of directly as a result of a users SQL statement.11288** </ul>11289**11290** If a single row is affected by more than one operation within a session,11291** then the change is considered indirect if all operations meet the criteria11292** for an indirect change above, or direct otherwise.11293**11294** This function is used to set, clear or query the session object indirect11295** flag.  If the second argument passed to this function is zero, then the11296** indirect flag is cleared. If it is greater than zero, the indirect flag11297** is set. Passing a value less than zero does not modify the current value11298** of the indirect flag, and may be used to query the current state of the11299** indirect flag for the specified session object.11300**11301** The return value indicates the final state of the indirect flag: 0 if11302** it is clear, or 1 if it is set.11303*/11304SQLITE_API int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect);1130511306/*11307** CAPI3REF: Attach A Table To A Session Object11308** METHOD: sqlite3_session11309**11310** If argument zTab is not NULL, then it is the name of a table to attach11311** to the session object passed as the first argument. All subsequent changes11312** made to the table while the session object is enabled will be recorded. See11313** documentation for [sqlite3session_changeset()] for further details.11314**11315** Or, if argument zTab is NULL, then changes are recorded for all tables11316** in the database. If additional tables are added to the database (by11317** executing "CREATE TABLE" statements) after this call is made, changes for11318** the new tables are also recorded.11319**11320** Changes can only be recorded for tables that have a PRIMARY KEY explicitly11321** defined as part of their CREATE TABLE statement. It does not matter if the11322** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY11323** KEY may consist of a single column, or may be a composite key.11324**11325** It is not an error if the named table does not exist in the database. Nor11326** is it an error if the named table does not have a PRIMARY KEY. However,11327** no changes will be recorded in either of these scenarios.11328**11329** Changes are not recorded for individual rows that have NULL values stored11330** in one or more of their PRIMARY KEY columns.11331**11332** SQLITE_OK is returned if the call completes without error. Or, if an error11333** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.11334**11335** <h3>Special sqlite_stat1 Handling</h3>11336**11337** As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception to11338** some of the rules above. In SQLite, the schema of sqlite_stat1 is:11339**  <pre>11340**  &nbsp;     CREATE TABLE sqlite_stat1(tbl,idx,stat)11341**  </pre>11342**11343** Even though sqlite_stat1 does not have a PRIMARY KEY, changes are11344** recorded for it as if the PRIMARY KEY is (tbl,idx). Additionally, changes11345** are recorded for rows for which (idx IS NULL) is true. However, for such11346** rows a zero-length blob (SQL value X'') is stored in the changeset or11347** patchset instead of a NULL value. This allows such changesets to be11348** manipulated by legacy implementations of sqlite3changeset_invert(),11349** concat() and similar.11350**11351** The sqlite3changeset_apply() function automatically converts the11352** zero-length blob back to a NULL value when updating the sqlite_stat111353** table. However, if the application calls sqlite3changeset_new(),11354** sqlite3changeset_old() or sqlite3changeset_conflict on a changeset11355** iterator directly (including on a changeset iterator passed to a11356** conflict-handler callback) then the X'' value is returned. The application11357** must translate X'' to NULL itself if required.11358**11359** Legacy (older than 3.22.0) versions of the sessions module cannot capture11360** changes made to the sqlite_stat1 table. Legacy versions of the11361** sqlite3changeset_apply() function silently ignore any modifications to the11362** sqlite_stat1 table that are part of a changeset or patchset.11363*/11364SQLITE_API int sqlite3session_attach(11365  sqlite3_session *pSession,      /* Session object */11366  const char *zTab                /* Table name */11367);1136811369/*11370** CAPI3REF: Set a table filter on a Session Object.11371** METHOD: sqlite3_session11372**11373** The second argument (xFilter) is the "filter callback". For changes to rows11374** in tables that are not attached to the Session object, the filter is called11375** to determine whether changes to the table's rows should be tracked or not.11376** If xFilter returns 0, changes are not tracked. Note that once a table is11377** attached, xFilter will not be called again.11378*/11379SQLITE_API void sqlite3session_table_filter(11380  sqlite3_session *pSession,      /* Session object */11381  int(*xFilter)(11382    void *pCtx,                   /* Copy of third arg to _filter_table() */11383    const char *zTab              /* Table name */11384  ),11385  void *pCtx                      /* First argument passed to xFilter */11386);1138711388/*11389** CAPI3REF: Generate A Changeset From A Session Object11390** METHOD: sqlite3_session11391**11392** Obtain a changeset containing changes to the tables attached to the11393** session object passed as the first argument. If successful,11394** set *ppChangeset to point to a buffer containing the changeset11395** and *pnChangeset to the size of the changeset in bytes before returning11396** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to11397** zero and return an SQLite error code.11398**11399** A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes,11400** each representing a change to a single row of an attached table. An INSERT11401** change contains the values of each field of a new database row. A DELETE11402** contains the original values of each field of a deleted database row. An11403** UPDATE change contains the original values of each field of an updated11404** database row along with the updated values for each updated non-primary-key11405** column. It is not possible for an UPDATE change to represent a change that11406** modifies the values of primary key columns. If such a change is made, it11407** is represented in a changeset as a DELETE followed by an INSERT.11408**11409** Changes are not recorded for rows that have NULL values stored in one or11410** more of their PRIMARY KEY columns. If such a row is inserted or deleted,11411** no corresponding change is present in the changesets returned by this11412** function. If an existing row with one or more NULL values stored in11413** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,11414** only an INSERT is appears in the changeset. Similarly, if an existing row11415** with non-NULL PRIMARY KEY values is updated so that one or more of its11416** PRIMARY KEY columns are set to NULL, the resulting changeset contains a11417** DELETE change only.11418**11419** The contents of a changeset may be traversed using an iterator created11420** using the [sqlite3changeset_start()] API. A changeset may be applied to11421** a database with a compatible schema using the [sqlite3changeset_apply()]11422** API.11423**11424** Within a changeset generated by this function, all changes related to a11425** single table are grouped together. In other words, when iterating through11426** a changeset or when applying a changeset to a database, all changes related11427** to a single table are processed before moving on to the next table. Tables11428** are sorted in the same order in which they were attached (or auto-attached)11429** to the sqlite3_session object. The order in which the changes related to11430** a single table are stored is undefined.11431**11432** Following a successful call to this function, it is the responsibility of11433** the caller to eventually free the buffer that *ppChangeset points to using11434** [sqlite3_free()].11435**11436** <h3>Changeset Generation</h3>11437**11438** Once a table has been attached to a session object, the session object11439** records the primary key values of all new rows inserted into the table.11440** It also records the original primary key and other column values of any11441** deleted or updated rows. For each unique primary key value, data is only11442** recorded once - the first time a row with said primary key is inserted,11443** updated or deleted in the lifetime of the session.11444**11445** There is one exception to the previous paragraph: when a row is inserted,11446** updated or deleted, if one or more of its primary key columns contain a11447** NULL value, no record of the change is made.11448**11449** The session object therefore accumulates two types of records - those11450** that consist of primary key values only (created when the user inserts11451** a new record) and those that consist of the primary key values and the11452** original values of other table columns (created when the users deletes11453** or updates a record).11454**11455** When this function is called, the requested changeset is created using11456** both the accumulated records and the current contents of the database11457** file. Specifically:11458**11459** <ul>11460**   <li> For each record generated by an insert, the database is queried11461**        for a row with a matching primary key. If one is found, an INSERT11462**        change is added to the changeset. If no such row is found, no change11463**        is added to the changeset.11464**11465**   <li> For each record generated by an update or delete, the database is11466**        queried for a row with a matching primary key. If such a row is11467**        found and one or more of the non-primary key fields have been11468**        modified from their original values, an UPDATE change is added to11469**        the changeset. Or, if no such row is found in the table, a DELETE11470**        change is added to the changeset. If there is a row with a matching11471**        primary key in the database, but all fields contain their original11472**        values, no change is added to the changeset.11473** </ul>11474**11475** This means, amongst other things, that if a row is inserted and then later11476** deleted while a session object is active, neither the insert nor the delete11477** will be present in the changeset. Or if a row is deleted and then later a11478** row with the same primary key values inserted while a session object is11479** active, the resulting changeset will contain an UPDATE change instead of11480** a DELETE and an INSERT.11481**11482** When a session object is disabled (see the [sqlite3session_enable()] API),11483** it does not accumulate records when rows are inserted, updated or deleted.11484** This may appear to have some counter-intuitive effects if a single row11485** is written to more than once during a session. For example, if a row11486** is inserted while a session object is enabled, then later deleted while11487** the same session object is disabled, no INSERT record will appear in the11488** changeset, even though the delete took place while the session was disabled.11489** Or, if one field of a row is updated while a session is disabled, and11490** another field of the same row is updated while the session is enabled, the11491** resulting changeset will contain an UPDATE change that updates both fields.11492*/11493SQLITE_API int sqlite3session_changeset(11494  sqlite3_session *pSession,      /* Session object */11495  int *pnChangeset,               /* OUT: Size of buffer at *ppChangeset */11496  void **ppChangeset              /* OUT: Buffer containing changeset */11497);1149811499/*11500** CAPI3REF: Return An Upper-limit For The Size Of The Changeset11501** METHOD: sqlite3_session11502**11503** By default, this function always returns 0. For it to return11504** a useful result, the sqlite3_session object must have been configured11505** to enable this API using sqlite3session_object_config() with the11506** SQLITE_SESSION_OBJCONFIG_SIZE verb.11507**11508** When enabled, this function returns an upper limit, in bytes, for the size11509** of the changeset that might be produced if sqlite3session_changeset() were11510** called. The final changeset size might be equal to or smaller than the11511** size in bytes returned by this function.11512*/11513SQLITE_API sqlite3_int64 sqlite3session_changeset_size(sqlite3_session *pSession);1151411515/*11516** CAPI3REF: Load The Difference Between Tables Into A Session11517** METHOD: sqlite3_session11518**11519** If it is not already attached to the session object passed as the first11520** argument, this function attaches table zTbl in the same manner as the11521** [sqlite3session_attach()] function. If zTbl does not exist, or if it11522** does not have a primary key, this function is a no-op (but does not return11523** an error).11524**11525** Argument zFromDb must be the name of a database ("main", "temp" etc.)11526** attached to the same database handle as the session object that contains11527** a table compatible with the table attached to the session by this function.11528** A table is considered compatible if it:11529**11530** <ul>11531**   <li> Has the same name,11532**   <li> Has the same set of columns declared in the same order, and11533**   <li> Has the same PRIMARY KEY definition.11534** </ul>11535**11536** If the tables are not compatible, SQLITE_SCHEMA is returned. If the tables11537** are compatible but do not have any PRIMARY KEY columns, it is not an error11538** but no changes are added to the session object. As with other session11539** APIs, tables without PRIMARY KEYs are simply ignored.11540**11541** This function adds a set of changes to the session object that could be11542** used to update the table in database zFrom (call this the "from-table")11543** so that its content is the same as the table attached to the session11544** object (call this the "to-table"). Specifically:11545**11546** <ul>11547**   <li> For each row (primary key) that exists in the to-table but not in11548**     the from-table, an INSERT record is added to the session object.11549**11550**   <li> For each row (primary key) that exists in the to-table but not in11551**     the from-table, a DELETE record is added to the session object.11552**11553**   <li> For each row (primary key) that exists in both tables, but features11554**     different non-PK values in each, an UPDATE record is added to the11555**     session.11556** </ul>11557**11558** To clarify, if this function is called and then a changeset constructed11559** using [sqlite3session_changeset()], then after applying that changeset to11560** database zFrom the contents of the two compatible tables would be11561** identical.11562**11563** It an error if database zFrom does not exist or does not contain the11564** required compatible table.11565**11566** If the operation is successful, SQLITE_OK is returned. Otherwise, an SQLite11567** error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg11568** may be set to point to a buffer containing an English language error11569** message. It is the responsibility of the caller to free this buffer using11570** sqlite3_free().11571*/11572SQLITE_API int sqlite3session_diff(11573  sqlite3_session *pSession,11574  const char *zFromDb,11575  const char *zTbl,11576  char **pzErrMsg11577);115781157911580/*11581** CAPI3REF: Generate A Patchset From A Session Object11582** METHOD: sqlite3_session11583**11584** The differences between a patchset and a changeset are that:11585**11586** <ul>11587**   <li> DELETE records consist of the primary key fields only. The11588**        original values of other fields are omitted.11589**   <li> The original values of any modified fields are omitted from11590**        UPDATE records.11591** </ul>11592**11593** A patchset blob may be used with up to date versions of all11594** sqlite3changeset_xxx API functions except for sqlite3changeset_invert(),11595** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly,11596** attempting to use a patchset blob with old versions of the11597** sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error.11598**11599** Because the non-primary key "old.*" fields are omitted, no11600** SQLITE_CHANGESET_DATA conflicts can be detected or reported if a patchset11601** is passed to the sqlite3changeset_apply() API. Other conflict types work11602** in the same way as for changesets.11603**11604** Changes within a patchset are ordered in the same way as for changesets11605** generated by the sqlite3session_changeset() function (i.e. all changes for11606** a single table are grouped together, tables appear in the order in which11607** they were attached to the session object).11608*/11609SQLITE_API int sqlite3session_patchset(11610  sqlite3_session *pSession,      /* Session object */11611  int *pnPatchset,                /* OUT: Size of buffer at *ppPatchset */11612  void **ppPatchset               /* OUT: Buffer containing patchset */11613);1161411615/*11616** CAPI3REF: Test if a changeset has recorded any changes.11617**11618** Return non-zero if no changes to attached tables have been recorded by11619** the session object passed as the first argument. Otherwise, if one or11620** more changes have been recorded, return zero.11621**11622** Even if this function returns zero, it is possible that calling11623** [sqlite3session_changeset()] on the session handle may still return a11624** changeset that contains no changes. This can happen when a row in11625** an attached table is modified and then later on the original values11626** are restored. However, if this function returns non-zero, then it is11627** guaranteed that a call to sqlite3session_changeset() will return a11628** changeset containing zero changes.11629*/11630SQLITE_API int sqlite3session_isempty(sqlite3_session *pSession);1163111632/*11633** CAPI3REF: Query for the amount of heap memory used by a session object.11634**11635** This API returns the total amount of heap memory in bytes currently11636** used by the session object passed as the only argument.11637*/11638SQLITE_API sqlite3_int64 sqlite3session_memory_used(sqlite3_session *pSession);1163911640/*11641** CAPI3REF: Create An Iterator To Traverse A Changeset11642** CONSTRUCTOR: sqlite3_changeset_iter11643**11644** Create an iterator used to iterate through the contents of a changeset.11645** If successful, *pp is set to point to the iterator handle and SQLITE_OK11646** is returned. Otherwise, if an error occurs, *pp is set to zero and an11647** SQLite error code is returned.11648**11649** The following functions can be used to advance and query a changeset11650** iterator created by this function:11651**11652** <ul>11653**   <li> [sqlite3changeset_next()]11654**   <li> [sqlite3changeset_op()]11655**   <li> [sqlite3changeset_new()]11656**   <li> [sqlite3changeset_old()]11657** </ul>11658**11659** It is the responsibility of the caller to eventually destroy the iterator11660** by passing it to [sqlite3changeset_finalize()]. The buffer containing the11661** changeset (pChangeset) must remain valid until after the iterator is11662** destroyed.11663**11664** Assuming the changeset blob was created by one of the11665** [sqlite3session_changeset()], [sqlite3changeset_concat()] or11666** [sqlite3changeset_invert()] functions, all changes within the changeset11667** that apply to a single table are grouped together. This means that when11668** an application iterates through a changeset using an iterator created by11669** this function, all changes that relate to a single table are visited11670** consecutively. There is no chance that the iterator will visit a change11671** the applies to table X, then one for table Y, and then later on visit11672** another change for table X.11673**11674** The behavior of sqlite3changeset_start_v2() and its streaming equivalent11675** may be modified by passing a combination of11676** [SQLITE_CHANGESETSTART_INVERT | supported flags] as the 4th parameter.11677**11678** Note that the sqlite3changeset_start_v2() API is still <b>experimental</b>11679** and therefore subject to change.11680*/11681SQLITE_API int sqlite3changeset_start(11682  sqlite3_changeset_iter **pp,    /* OUT: New changeset iterator handle */11683  int nChangeset,                 /* Size of changeset blob in bytes */11684  void *pChangeset                /* Pointer to blob containing changeset */11685);11686SQLITE_API int sqlite3changeset_start_v2(11687  sqlite3_changeset_iter **pp,    /* OUT: New changeset iterator handle */11688  int nChangeset,                 /* Size of changeset blob in bytes */11689  void *pChangeset,               /* Pointer to blob containing changeset */11690  int flags                       /* SESSION_CHANGESETSTART_* flags */11691);1169211693/*11694** CAPI3REF: Flags for sqlite3changeset_start_v211695**11696** The following flags may passed via the 4th parameter to11697** [sqlite3changeset_start_v2] and [sqlite3changeset_start_v2_strm]:11698**11699** <dt>SQLITE_CHANGESETAPPLY_INVERT <dd>11700**   Invert the changeset while iterating through it. This is equivalent to11701**   inverting a changeset using sqlite3changeset_invert() before applying it.11702**   It is an error to specify this flag with a patchset.11703*/11704#define SQLITE_CHANGESETSTART_INVERT        0x0002117051170611707/*11708** CAPI3REF: Advance A Changeset Iterator11709** METHOD: sqlite3_changeset_iter11710**11711** This function may only be used with iterators created by the function11712** [sqlite3changeset_start()]. If it is called on an iterator passed to11713** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE11714** is returned and the call has no effect.11715**11716** Immediately after an iterator is created by sqlite3changeset_start(), it11717** does not point to any change in the changeset. Assuming the changeset11718** is not empty, the first call to this function advances the iterator to11719** point to the first change in the changeset. Each subsequent call advances11720** the iterator to point to the next change in the changeset (if any). If11721** no error occurs and the iterator points to a valid change after a call11722** to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned.11723** Otherwise, if all changes in the changeset have already been visited,11724** SQLITE_DONE is returned.11725**11726** If an error occurs, an SQLite error code is returned. Possible error11727** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or11728** SQLITE_NOMEM.11729*/11730SQLITE_API int sqlite3changeset_next(sqlite3_changeset_iter *pIter);1173111732/*11733** CAPI3REF: Obtain The Current Operation From A Changeset Iterator11734** METHOD: sqlite3_changeset_iter11735**11736** The pIter argument passed to this function may either be an iterator11737** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator11738** created by [sqlite3changeset_start()]. In the latter case, the most recent11739** call to [sqlite3changeset_next()] must have returned [SQLITE_ROW]. If this11740** is not the case, this function returns [SQLITE_MISUSE].11741**11742** Arguments pOp, pnCol and pzTab may not be NULL. Upon return, three11743** outputs are set through these pointers:11744**11745** *pOp is set to one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],11746** depending on the type of change that the iterator currently points to;11747**11748** *pnCol is set to the number of columns in the table affected by the change; and11749**11750** *pzTab is set to point to a nul-terminated utf-8 encoded string containing11751** the name of the table affected by the current change. The buffer remains11752** valid until either sqlite3changeset_next() is called on the iterator11753** or until the conflict-handler function returns.11754**11755** If pbIndirect is not NULL, then *pbIndirect is set to true (1) if the change11756** is an indirect change, or false (0) otherwise. See the documentation for11757** [sqlite3session_indirect()] for a description of direct and indirect11758** changes.11759**11760** If no error occurs, SQLITE_OK is returned. If an error does occur, an11761** SQLite error code is returned. The values of the output variables may not11762** be trusted in this case.11763*/11764SQLITE_API int sqlite3changeset_op(11765  sqlite3_changeset_iter *pIter,  /* Iterator object */11766  const char **pzTab,             /* OUT: Pointer to table name */11767  int *pnCol,                     /* OUT: Number of columns in table */11768  int *pOp,                       /* OUT: SQLITE_INSERT, DELETE or UPDATE */11769  int *pbIndirect                 /* OUT: True for an 'indirect' change */11770);1177111772/*11773** CAPI3REF: Obtain The Primary Key Definition Of A Table11774** METHOD: sqlite3_changeset_iter11775**11776** For each modified table, a changeset includes the following:11777**11778** <ul>11779**   <li> The number of columns in the table, and11780**   <li> Which of those columns make up the tables PRIMARY KEY.11781** </ul>11782**11783** This function is used to find which columns comprise the PRIMARY KEY of11784** the table modified by the change that iterator pIter currently points to.11785** If successful, *pabPK is set to point to an array of nCol entries, where11786** nCol is the number of columns in the table. Elements of *pabPK are set to11787** 0x01 if the corresponding column is part of the tables primary key, or11788** 0x00 if it is not.11789**11790** If argument pnCol is not NULL, then *pnCol is set to the number of columns11791** in the table.11792**11793** If this function is called when the iterator does not point to a valid11794** entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise,11795** SQLITE_OK is returned and the output variables populated as described11796** above.11797*/11798SQLITE_API int sqlite3changeset_pk(11799  sqlite3_changeset_iter *pIter,  /* Iterator object */11800  unsigned char **pabPK,          /* OUT: Array of boolean - true for PK cols */11801  int *pnCol                      /* OUT: Number of entries in output array */11802);1180311804/*11805** CAPI3REF: Obtain old.* Values From A Changeset Iterator11806** METHOD: sqlite3_changeset_iter11807**11808** The pIter argument passed to this function may either be an iterator11809** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator11810** created by [sqlite3changeset_start()]. In the latter case, the most recent11811** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.11812** Furthermore, it may only be called if the type of change that the iterator11813** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise,11814** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.11815**11816** Argument iVal must be greater than or equal to 0, and less than the number11817** of columns in the table affected by the current change. Otherwise,11818** [SQLITE_RANGE] is returned and *ppValue is set to NULL.11819**11820** If successful, this function sets *ppValue to point to a protected11821** sqlite3_value object containing the iVal'th value from the vector of11822** original row values stored as part of the UPDATE or DELETE change and11823** returns SQLITE_OK. The name of the function comes from the fact that this11824** is similar to the "old.*" columns available to update or delete triggers.11825**11826** If some other error occurs (e.g. an OOM condition), an SQLite error code11827** is returned and *ppValue is set to NULL.11828*/11829SQLITE_API int sqlite3changeset_old(11830  sqlite3_changeset_iter *pIter,  /* Changeset iterator */11831  int iVal,                       /* Column number */11832  sqlite3_value **ppValue         /* OUT: Old value (or NULL pointer) */11833);1183411835/*11836** CAPI3REF: Obtain new.* Values From A Changeset Iterator11837** METHOD: sqlite3_changeset_iter11838**11839** The pIter argument passed to this function may either be an iterator11840** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator11841** created by [sqlite3changeset_start()]. In the latter case, the most recent11842** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.11843** Furthermore, it may only be called if the type of change that the iterator11844** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise,11845** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.11846**11847** Argument iVal must be greater than or equal to 0, and less than the number11848** of columns in the table affected by the current change. Otherwise,11849** [SQLITE_RANGE] is returned and *ppValue is set to NULL.11850**11851** If successful, this function sets *ppValue to point to a protected11852** sqlite3_value object containing the iVal'th value from the vector of11853** new row values stored as part of the UPDATE or INSERT change and11854** returns SQLITE_OK. If the change is an UPDATE and does not include11855** a new value for the requested column, *ppValue is set to NULL and11856** SQLITE_OK returned. The name of the function comes from the fact that11857** this is similar to the "new.*" columns available to update or delete11858** triggers.11859**11860** If some other error occurs (e.g. an OOM condition), an SQLite error code11861** is returned and *ppValue is set to NULL.11862*/11863SQLITE_API int sqlite3changeset_new(11864  sqlite3_changeset_iter *pIter,  /* Changeset iterator */11865  int iVal,                       /* Column number */11866  sqlite3_value **ppValue         /* OUT: New value (or NULL pointer) */11867);1186811869/*11870** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator11871** METHOD: sqlite3_changeset_iter11872**11873** This function should only be used with iterator objects passed to a11874** conflict-handler callback by [sqlite3changeset_apply()] with either11875** [SQLITE_CHANGESET_DATA] or [SQLITE_CHANGESET_CONFLICT]. If this function11876** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue11877** is set to NULL.11878**11879** Argument iVal must be greater than or equal to 0, and less than the number11880** of columns in the table affected by the current change. Otherwise,11881** [SQLITE_RANGE] is returned and *ppValue is set to NULL.11882**11883** If successful, this function sets *ppValue to point to a protected11884** sqlite3_value object containing the iVal'th value from the11885** "conflicting row" associated with the current conflict-handler callback11886** and returns SQLITE_OK.11887**11888** If some other error occurs (e.g. an OOM condition), an SQLite error code11889** is returned and *ppValue is set to NULL.11890*/11891SQLITE_API int sqlite3changeset_conflict(11892  sqlite3_changeset_iter *pIter,  /* Changeset iterator */11893  int iVal,                       /* Column number */11894  sqlite3_value **ppValue         /* OUT: Value from conflicting row */11895);1189611897/*11898** CAPI3REF: Determine The Number Of Foreign Key Constraint Violations11899** METHOD: sqlite3_changeset_iter11900**11901** This function may only be called with an iterator passed to an11902** SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case11903** it sets the output variable to the total number of known foreign key11904** violations in the destination database and returns SQLITE_OK.11905**11906** In all other cases this function returns SQLITE_MISUSE.11907*/11908SQLITE_API int sqlite3changeset_fk_conflicts(11909  sqlite3_changeset_iter *pIter,  /* Changeset iterator */11910  int *pnOut                      /* OUT: Number of FK violations */11911);119121191311914/*11915** CAPI3REF: Finalize A Changeset Iterator11916** METHOD: sqlite3_changeset_iter11917**11918** This function is used to finalize an iterator allocated with11919** [sqlite3changeset_start()].11920**11921** This function should only be called on iterators created using the11922** [sqlite3changeset_start()] function. If an application calls this11923** function with an iterator passed to a conflict-handler by11924** [sqlite3changeset_apply()], [SQLITE_MISUSE] is immediately returned and the11925** call has no effect.11926**11927** If an error was encountered within a call to an sqlite3changeset_xxx()11928** function (for example an [SQLITE_CORRUPT] in [sqlite3changeset_next()] or an11929** [SQLITE_NOMEM] in [sqlite3changeset_new()]) then an error code corresponding11930** to that error is returned by this function. Otherwise, SQLITE_OK is11931** returned. This is to allow the following pattern (pseudo-code):11932**11933** <pre>11934**   sqlite3changeset_start();11935**   while( SQLITE_ROW==sqlite3changeset_next() ){11936**     // Do something with change.11937**   }11938**   rc = sqlite3changeset_finalize();11939**   if( rc!=SQLITE_OK ){11940**     // An error has occurred11941**   }11942** </pre>11943*/11944SQLITE_API int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);1194511946/*11947** CAPI3REF: Invert A Changeset11948**11949** This function is used to "invert" a changeset object. Applying an inverted11950** changeset to a database reverses the effects of applying the uninverted11951** changeset. Specifically:11952**11953** <ul>11954**   <li> Each DELETE change is changed to an INSERT, and11955**   <li> Each INSERT change is changed to a DELETE, and11956**   <li> For each UPDATE change, the old.* and new.* values are exchanged.11957** </ul>11958**11959** This function does not change the order in which changes appear within11960** the changeset. It merely reverses the sense of each individual change.11961**11962** If successful, a pointer to a buffer containing the inverted changeset11963** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and11964** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are11965** zeroed and an SQLite error code returned.11966**11967** It is the responsibility of the caller to eventually call sqlite3_free()11968** on the *ppOut pointer to free the buffer allocation following a successful11969** call to this function.11970**11971** WARNING/TODO: This function currently assumes that the input is a valid11972** changeset. If it is not, the results are undefined.11973*/11974SQLITE_API int sqlite3changeset_invert(11975  int nIn, const void *pIn,       /* Input changeset */11976  int *pnOut, void **ppOut        /* OUT: Inverse of input */11977);1197811979/*11980** CAPI3REF: Concatenate Two Changeset Objects11981**11982** This function is used to concatenate two changesets, A and B, into a11983** single changeset. The result is a changeset equivalent to applying11984** changeset A followed by changeset B.11985**11986** This function combines the two input changesets using an11987** sqlite3_changegroup object. Calling it produces similar results as the11988** following code fragment:11989**11990** <pre>11991**   sqlite3_changegroup *pGrp;11992**   rc = sqlite3_changegroup_new(&pGrp);11993**   if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA);11994**   if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nB, pB);11995**   if( rc==SQLITE_OK ){11996**     rc = sqlite3changegroup_output(pGrp, pnOut, ppOut);11997**   }else{11998**     *ppOut = 0;11999**     *pnOut = 0;12000**   }12001** </pre>12002**12003** Refer to the sqlite3_changegroup documentation below for details.12004*/12005SQLITE_API int sqlite3changeset_concat(12006  int nA,                         /* Number of bytes in buffer pA */12007  void *pA,                       /* Pointer to buffer containing changeset A */12008  int nB,                         /* Number of bytes in buffer pB */12009  void *pB,                       /* Pointer to buffer containing changeset B */12010  int *pnOut,                     /* OUT: Number of bytes in output changeset */12011  void **ppOut                    /* OUT: Buffer containing output changeset */12012);120131201412015/*12016** CAPI3REF: Upgrade the Schema of a Changeset/Patchset12017*/12018SQLITE_API int sqlite3changeset_upgrade(12019  sqlite3 *db,12020  const char *zDb,12021  int nIn, const void *pIn,       /* Input changeset */12022  int *pnOut, void **ppOut        /* OUT: Inverse of input */12023);12024120251202612027/*12028** CAPI3REF: Changegroup Handle12029**12030** A changegroup is an object used to combine two or more12031** [changesets] or [patchsets]12032*/12033typedef struct sqlite3_changegroup sqlite3_changegroup;1203412035/*12036** CAPI3REF: Create A New Changegroup Object12037** CONSTRUCTOR: sqlite3_changegroup12038**12039** An sqlite3_changegroup object is used to combine two or more changesets12040** (or patchsets) into a single changeset (or patchset). A single changegroup12041** object may combine changesets or patchsets, but not both. The output is12042** always in the same format as the input.12043**12044** If successful, this function returns SQLITE_OK and populates (*pp) with12045** a pointer to a new sqlite3_changegroup object before returning. The caller12046** should eventually free the returned object using a call to12047** sqlite3changegroup_delete(). If an error occurs, an SQLite error code12048** (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL.12049**12050** The usual usage pattern for an sqlite3_changegroup object is as follows:12051**12052** <ul>12053**   <li> It is created using a call to sqlite3changegroup_new().12054**12055**   <li> Zero or more changesets (or patchsets) are added to the object12056**        by calling sqlite3changegroup_add().12057**12058**   <li> The result of combining all input changesets together is obtained12059**        by the application via a call to sqlite3changegroup_output().12060**12061**   <li> The object is deleted using a call to sqlite3changegroup_delete().12062** </ul>12063**12064** Any number of calls to add() and output() may be made between the calls to12065** new() and delete(), and in any order.12066**12067** As well as the regular sqlite3changegroup_add() and12068** sqlite3changegroup_output() functions, also available are the streaming12069** versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm().12070*/12071SQLITE_API int sqlite3changegroup_new(sqlite3_changegroup **pp);1207212073/*12074** CAPI3REF: Add a Schema to a Changegroup12075** METHOD: sqlite3_changegroup_schema12076**12077** This method may be used to optionally enforce the rule that the changesets12078** added to the changegroup handle must match the schema of database zDb12079** ("main", "temp", or the name of an attached database). If12080** sqlite3changegroup_add() is called to add a changeset that is not compatible12081** with the configured schema, SQLITE_SCHEMA is returned and the changegroup12082** object is left in an undefined state.12083**12084** A changeset schema is considered compatible with the database schema in12085** the same way as for sqlite3changeset_apply(). Specifically, for each12086** table in the changeset, there exists a database table with:12087**12088** <ul>12089**   <li> The name identified by the changeset, and12090**   <li> at least as many columns as recorded in the changeset, and12091**   <li> the primary key columns in the same position as recorded in12092**        the changeset.12093** </ul>12094**12095** The output of the changegroup object always has the same schema as the12096** database nominated using this function. In cases where changesets passed12097** to sqlite3changegroup_add() have fewer columns than the corresponding table12098** in the database schema, these are filled in using the default column12099** values from the database schema. This makes it possible to combined12100** changesets that have different numbers of columns for a single table12101** within a changegroup, provided that they are otherwise compatible.12102*/12103SQLITE_API int sqlite3changegroup_schema(sqlite3_changegroup*, sqlite3*, const char *zDb);1210412105/*12106** CAPI3REF: Add A Changeset To A Changegroup12107** METHOD: sqlite3_changegroup12108**12109** Add all changes within the changeset (or patchset) in buffer pData (size12110** nData bytes) to the changegroup.12111**12112** If the buffer contains a patchset, then all prior calls to this function12113** on the same changegroup object must also have specified patchsets. Or, if12114** the buffer contains a changeset, so must have the earlier calls to this12115** function. Otherwise, SQLITE_ERROR is returned and no changes are added12116** to the changegroup.12117**12118** Rows within the changeset and changegroup are identified by the values in12119** their PRIMARY KEY columns. A change in the changeset is considered to12120** apply to the same row as a change already present in the changegroup if12121** the two rows have the same primary key.12122**12123** Changes to rows that do not already appear in the changegroup are12124** simply copied into it. Or, if both the new changeset and the changegroup12125** contain changes that apply to a single row, the final contents of the12126** changegroup depends on the type of each change, as follows:12127**12128** <table border=1 style="margin-left:8ex;margin-right:8ex">12129**   <tr><th style="white-space:pre">Existing Change  </th>12130**       <th style="white-space:pre">New Change       </th>12131**       <th>Output Change12132**   <tr><td>INSERT <td>INSERT <td>12133**       The new change is ignored. This case does not occur if the new12134**       changeset was recorded immediately after the changesets already12135**       added to the changegroup.12136**   <tr><td>INSERT <td>UPDATE <td>12137**       The INSERT change remains in the changegroup. The values in the12138**       INSERT change are modified as if the row was inserted by the12139**       existing change and then updated according to the new change.12140**   <tr><td>INSERT <td>DELETE <td>12141**       The existing INSERT is removed from the changegroup. The DELETE is12142**       not added.12143**   <tr><td>UPDATE <td>INSERT <td>12144**       The new change is ignored. This case does not occur if the new12145**       changeset was recorded immediately after the changesets already12146**       added to the changegroup.12147**   <tr><td>UPDATE <td>UPDATE <td>12148**       The existing UPDATE remains within the changegroup. It is amended12149**       so that the accompanying values are as if the row was updated once12150**       by the existing change and then again by the new change.12151**   <tr><td>UPDATE <td>DELETE <td>12152**       The existing UPDATE is replaced by the new DELETE within the12153**       changegroup.12154**   <tr><td>DELETE <td>INSERT <td>12155**       If one or more of the column values in the row inserted by the12156**       new change differ from those in the row deleted by the existing12157**       change, the existing DELETE is replaced by an UPDATE within the12158**       changegroup. Otherwise, if the inserted row is exactly the same12159**       as the deleted row, the existing DELETE is simply discarded.12160**   <tr><td>DELETE <td>UPDATE <td>12161**       The new change is ignored. This case does not occur if the new12162**       changeset was recorded immediately after the changesets already12163**       added to the changegroup.12164**   <tr><td>DELETE <td>DELETE <td>12165**       The new change is ignored. This case does not occur if the new12166**       changeset was recorded immediately after the changesets already12167**       added to the changegroup.12168** </table>12169**12170** If the new changeset contains changes to a table that is already present12171** in the changegroup, then the number of columns and the position of the12172** primary key columns for the table must be consistent. If this is not the12173** case, this function fails with SQLITE_SCHEMA. Except, if the changegroup12174** object has been configured with a database schema using the12175** sqlite3changegroup_schema() API, then it is possible to combine changesets12176** with different numbers of columns for a single table, provided that12177** they are otherwise compatible.12178**12179** If the input changeset appears to be corrupt and the corruption is12180** detected, SQLITE_CORRUPT is returned. Or, if an out-of-memory condition12181** occurs during processing, this function returns SQLITE_NOMEM.12182**12183** In all cases, if an error occurs the state of the final contents of the12184** changegroup is undefined. If no error occurs, SQLITE_OK is returned.12185*/12186SQLITE_API int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData);1218712188/*12189** CAPI3REF: Add A Single Change To A Changegroup12190** METHOD: sqlite3_changegroup12191**12192** This function adds the single change currently indicated by the iterator12193** passed as the second argument to the changegroup object. The rules for12194** adding the change are just as described for [sqlite3changegroup_add()].12195**12196** If the change is successfully added to the changegroup, SQLITE_OK is12197** returned. Otherwise, an SQLite error code is returned.12198**12199** The iterator must point to a valid entry when this function is called.12200** If it does not, SQLITE_ERROR is returned and no change is added to the12201** changegroup. Additionally, the iterator must not have been opened with12202** the SQLITE_CHANGESETAPPLY_INVERT flag. In this case SQLITE_ERROR is also12203** returned.12204*/12205SQLITE_API int sqlite3changegroup_add_change(12206  sqlite3_changegroup*,12207  sqlite3_changeset_iter*12208);12209122101221112212/*12213** CAPI3REF: Obtain A Composite Changeset From A Changegroup12214** METHOD: sqlite3_changegroup12215**12216** Obtain a buffer containing a changeset (or patchset) representing the12217** current contents of the changegroup. If the inputs to the changegroup12218** were themselves changesets, the output is a changeset. Or, if the12219** inputs were patchsets, the output is also a patchset.12220**12221** As with the output of the sqlite3session_changeset() and12222** sqlite3session_patchset() functions, all changes related to a single12223** table are grouped together in the output of this function. Tables appear12224** in the same order as for the very first changeset added to the changegroup.12225** If the second or subsequent changesets added to the changegroup contain12226** changes for tables that do not appear in the first changeset, they are12227** appended onto the end of the output changeset, again in the order in12228** which they are first encountered.12229**12230** If an error occurs, an SQLite error code is returned and the output12231** variables (*pnData) and (*ppData) are set to 0. Otherwise, SQLITE_OK12232** is returned and the output variables are set to the size of and a12233** pointer to the output buffer, respectively. In this case it is the12234** responsibility of the caller to eventually free the buffer using a12235** call to sqlite3_free().12236*/12237SQLITE_API int sqlite3changegroup_output(12238  sqlite3_changegroup*,12239  int *pnData,                    /* OUT: Size of output buffer in bytes */12240  void **ppData                   /* OUT: Pointer to output buffer */12241);1224212243/*12244** CAPI3REF: Delete A Changegroup Object12245** DESTRUCTOR: sqlite3_changegroup12246*/12247SQLITE_API void sqlite3changegroup_delete(sqlite3_changegroup*);1224812249/*12250** CAPI3REF: Apply A Changeset To A Database12251**12252** Apply a changeset or patchset to a database. These functions attempt to12253** update the "main" database attached to handle db with the changes found in12254** the changeset passed via the second and third arguments.12255**12256** The fourth argument (xFilter) passed to these functions is the "filter12257** callback". If it is not NULL, then for each table affected by at least one12258** change in the changeset, the filter callback is invoked with12259** the table name as the second argument, and a copy of the context pointer12260** passed as the sixth argument as the first. If the "filter callback"12261** returns zero, then no attempt is made to apply any changes to the table.12262** Otherwise, if the return value is non-zero or the xFilter argument to12263** is NULL, all changes related to the table are attempted.12264**12265** For each table that is not excluded by the filter callback, this function12266** tests that the target database contains a compatible table. A table is12267** considered compatible if all of the following are true:12268**12269** <ul>12270**   <li> The table has the same name as the name recorded in the12271**        changeset, and12272**   <li> The table has at least as many columns as recorded in the12273**        changeset, and12274**   <li> The table has primary key columns in the same position as12275**        recorded in the changeset.12276** </ul>12277**12278** If there is no compatible table, it is not an error, but none of the12279** changes associated with the table are applied. A warning message is issued12280** via the sqlite3_log() mechanism with the error code SQLITE_SCHEMA. At most12281** one such warning is issued for each table in the changeset.12282**12283** For each change for which there is a compatible table, an attempt is made12284** to modify the table contents according to the UPDATE, INSERT or DELETE12285** change. If a change cannot be applied cleanly, the conflict handler12286** function passed as the fifth argument to sqlite3changeset_apply() may be12287** invoked. A description of exactly when the conflict handler is invoked for12288** each type of change is below.12289**12290** Unlike the xFilter argument, xConflict may not be passed NULL. The results12291** of passing anything other than a valid function pointer as the xConflict12292** argument are undefined.12293**12294** Each time the conflict handler function is invoked, it must return one12295** of [SQLITE_CHANGESET_OMIT], [SQLITE_CHANGESET_ABORT] or12296** [SQLITE_CHANGESET_REPLACE]. SQLITE_CHANGESET_REPLACE may only be returned12297** if the second argument passed to the conflict handler is either12298** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler12299** returns an illegal value, any changes already made are rolled back and12300** the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different12301** actions are taken by sqlite3changeset_apply() depending on the value12302** returned by each invocation of the conflict-handler function. Refer to12303** the documentation for the three12304** [SQLITE_CHANGESET_OMIT|available return values] for details.12305**12306** <dl>12307** <dt>DELETE Changes<dd>12308**   For each DELETE change, the function checks if the target database12309**   contains a row with the same primary key value (or values) as the12310**   original row values stored in the changeset. If it does, and the values12311**   stored in all non-primary key columns also match the values stored in12312**   the changeset the row is deleted from the target database.12313**12314**   If a row with matching primary key values is found, but one or more of12315**   the non-primary key fields contains a value different from the original12316**   row value stored in the changeset, the conflict-handler function is12317**   invoked with [SQLITE_CHANGESET_DATA] as the second argument. If the12318**   database table has more columns than are recorded in the changeset,12319**   only the values of those non-primary key fields are compared against12320**   the current database contents - any trailing database table columns12321**   are ignored.12322**12323**   If no row with matching primary key values is found in the database,12324**   the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]12325**   passed as the second argument.12326**12327**   If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT12328**   (which can only happen if a foreign key constraint is violated), the12329**   conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT]12330**   passed as the second argument. This includes the case where the DELETE12331**   operation is attempted because an earlier call to the conflict handler12332**   function returned [SQLITE_CHANGESET_REPLACE].12333**12334** <dt>INSERT Changes<dd>12335**   For each INSERT change, an attempt is made to insert the new row into12336**   the database. If the changeset row contains fewer fields than the12337**   database table, the trailing fields are populated with their default12338**   values.12339**12340**   If the attempt to insert the row fails because the database already12341**   contains a row with the same primary key values, the conflict handler12342**   function is invoked with the second argument set to12343**   [SQLITE_CHANGESET_CONFLICT].12344**12345**   If the attempt to insert the row fails because of some other constraint12346**   violation (e.g. NOT NULL or UNIQUE), the conflict handler function is12347**   invoked with the second argument set to [SQLITE_CHANGESET_CONSTRAINT].12348**   This includes the case where the INSERT operation is re-attempted because12349**   an earlier call to the conflict handler function returned12350**   [SQLITE_CHANGESET_REPLACE].12351**12352** <dt>UPDATE Changes<dd>12353**   For each UPDATE change, the function checks if the target database12354**   contains a row with the same primary key value (or values) as the12355**   original row values stored in the changeset. If it does, and the values12356**   stored in all modified non-primary key columns also match the values12357**   stored in the changeset the row is updated within the target database.12358**12359**   If a row with matching primary key values is found, but one or more of12360**   the modified non-primary key fields contains a value different from an12361**   original row value stored in the changeset, the conflict-handler function12362**   is invoked with [SQLITE_CHANGESET_DATA] as the second argument. Since12363**   UPDATE changes only contain values for non-primary key fields that are12364**   to be modified, only those fields need to match the original values to12365**   avoid the SQLITE_CHANGESET_DATA conflict-handler callback.12366**12367**   If no row with matching primary key values is found in the database,12368**   the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]12369**   passed as the second argument.12370**12371**   If the UPDATE operation is attempted, but SQLite returns12372**   SQLITE_CONSTRAINT, the conflict-handler function is invoked with12373**   [SQLITE_CHANGESET_CONSTRAINT] passed as the second argument.12374**   This includes the case where the UPDATE operation is attempted after12375**   an earlier call to the conflict handler function returned12376**   [SQLITE_CHANGESET_REPLACE].12377** </dl>12378**12379** It is safe to execute SQL statements, including those that write to the12380** table that the callback related to, from within the xConflict callback.12381** This can be used to further customize the application's conflict12382** resolution strategy.12383**12384** All changes made by these functions are enclosed in a savepoint transaction.12385** If any other error (aside from a constraint failure when attempting to12386** write to the target database) occurs, then the savepoint transaction is12387** rolled back, restoring the target database to its original state, and an12388** SQLite error code returned.12389**12390** If the output parameters (ppRebase) and (pnRebase) are non-NULL and12391** the input is a changeset (not a patchset), then sqlite3changeset_apply_v2()12392** may set (*ppRebase) to point to a "rebase" that may be used with the12393** sqlite3_rebaser APIs buffer before returning. In this case (*pnRebase)12394** is set to the size of the buffer in bytes. It is the responsibility of the12395** caller to eventually free any such buffer using sqlite3_free(). The buffer12396** is only allocated and populated if one or more conflicts were encountered12397** while applying the patchset. See comments surrounding the sqlite3_rebaser12398** APIs for further details.12399**12400** The behavior of sqlite3changeset_apply_v2() and its streaming equivalent12401** may be modified by passing a combination of12402** [SQLITE_CHANGESETAPPLY_NOSAVEPOINT | supported flags] as the 9th parameter.12403**12404** Note that the sqlite3changeset_apply_v2() API is still <b>experimental</b>12405** and therefore subject to change.12406*/12407SQLITE_API int sqlite3changeset_apply(12408  sqlite3 *db,                    /* Apply change to "main" db of this handle */12409  int nChangeset,                 /* Size of changeset in bytes */12410  void *pChangeset,               /* Changeset blob */12411  int(*xFilter)(12412    void *pCtx,                   /* Copy of sixth arg to _apply() */12413    const char *zTab              /* Table name */12414  ),12415  int(*xConflict)(12416    void *pCtx,                   /* Copy of sixth arg to _apply() */12417    int eConflict,                /* DATA, MISSING, CONFLICT, CONSTRAINT */12418    sqlite3_changeset_iter *p     /* Handle describing change and conflict */12419  ),12420  void *pCtx                      /* First argument passed to xConflict */12421);12422SQLITE_API int sqlite3changeset_apply_v2(12423  sqlite3 *db,                    /* Apply change to "main" db of this handle */12424  int nChangeset,                 /* Size of changeset in bytes */12425  void *pChangeset,               /* Changeset blob */12426  int(*xFilter)(12427    void *pCtx,                   /* Copy of sixth arg to _apply() */12428    const char *zTab              /* Table name */12429  ),12430  int(*xConflict)(12431    void *pCtx,                   /* Copy of sixth arg to _apply() */12432    int eConflict,                /* DATA, MISSING, CONFLICT, CONSTRAINT */12433    sqlite3_changeset_iter *p     /* Handle describing change and conflict */12434  ),12435  void *pCtx,                     /* First argument passed to xConflict */12436  void **ppRebase, int *pnRebase, /* OUT: Rebase data */12437  int flags                       /* SESSION_CHANGESETAPPLY_* flags */12438);1243912440/*12441** CAPI3REF: Flags for sqlite3changeset_apply_v212442**12443** The following flags may passed via the 9th parameter to12444** [sqlite3changeset_apply_v2] and [sqlite3changeset_apply_v2_strm]:12445**12446** <dl>12447** <dt>SQLITE_CHANGESETAPPLY_NOSAVEPOINT <dd>12448**   Usually, the sessions module encloses all operations performed by12449**   a single call to apply_v2() or apply_v2_strm() in a [SAVEPOINT]. The12450**   SAVEPOINT is committed if the changeset or patchset is successfully12451**   applied, or rolled back if an error occurs. Specifying this flag12452**   causes the sessions module to omit this savepoint. In this case, if the12453**   caller has an open transaction or savepoint when apply_v2() is called,12454**   it may revert the partially applied changeset by rolling it back.12455**12456** <dt>SQLITE_CHANGESETAPPLY_INVERT <dd>12457**   Invert the changeset before applying it. This is equivalent to inverting12458**   a changeset using sqlite3changeset_invert() before applying it. It is12459**   an error to specify this flag with a patchset.12460**12461** <dt>SQLITE_CHANGESETAPPLY_IGNORENOOP <dd>12462**   Do not invoke the conflict handler callback for any changes that12463**   would not actually modify the database even if they were applied.12464**   Specifically, this means that the conflict handler is not invoked12465**   for:12466**    <ul>12467**    <li>a delete change if the row being deleted cannot be found,12468**    <li>an update change if the modified fields are already set to12469**        their new values in the conflicting row, or12470**    <li>an insert change if all fields of the conflicting row match12471**        the row being inserted.12472**    </ul>12473**12474** <dt>SQLITE_CHANGESETAPPLY_FKNOACTION <dd>12475**   If this flag it set, then all foreign key constraints in the target12476**   database behave as if they were declared with "ON UPDATE NO ACTION ON12477**   DELETE NO ACTION", even if they are actually CASCADE, RESTRICT, SET NULL12478**   or SET DEFAULT.12479*/12480#define SQLITE_CHANGESETAPPLY_NOSAVEPOINT   0x000112481#define SQLITE_CHANGESETAPPLY_INVERT        0x000212482#define SQLITE_CHANGESETAPPLY_IGNORENOOP    0x000412483#define SQLITE_CHANGESETAPPLY_FKNOACTION    0x00081248412485/*12486** CAPI3REF: Constants Passed To The Conflict Handler12487**12488** Values that may be passed as the second argument to a conflict-handler.12489**12490** <dl>12491** <dt>SQLITE_CHANGESET_DATA<dd>12492**   The conflict handler is invoked with CHANGESET_DATA as the second argument12493**   when processing a DELETE or UPDATE change if a row with the required12494**   PRIMARY KEY fields is present in the database, but one or more other12495**   (non primary-key) fields modified by the update do not contain the12496**   expected "before" values.12497**12498**   The conflicting row, in this case, is the database row with the matching12499**   primary key.12500**12501** <dt>SQLITE_CHANGESET_NOTFOUND<dd>12502**   The conflict handler is invoked with CHANGESET_NOTFOUND as the second12503**   argument when processing a DELETE or UPDATE change if a row with the12504**   required PRIMARY KEY fields is not present in the database.12505**12506**   There is no conflicting row in this case. The results of invoking the12507**   sqlite3changeset_conflict() API are undefined.12508**12509** <dt>SQLITE_CHANGESET_CONFLICT<dd>12510**   CHANGESET_CONFLICT is passed as the second argument to the conflict12511**   handler while processing an INSERT change if the operation would result12512**   in duplicate primary key values.12513**12514**   The conflicting row in this case is the database row with the matching12515**   primary key.12516**12517** <dt>SQLITE_CHANGESET_FOREIGN_KEY<dd>12518**   If foreign key handling is enabled, and applying a changeset leaves the12519**   database in a state containing foreign key violations, the conflict12520**   handler is invoked with CHANGESET_FOREIGN_KEY as the second argument12521**   exactly once before the changeset is committed. If the conflict handler12522**   returns CHANGESET_OMIT, the changes, including those that caused the12523**   foreign key constraint violation, are committed. Or, if it returns12524**   CHANGESET_ABORT, the changeset is rolled back.12525**12526**   No current or conflicting row information is provided. The only function12527**   it is possible to call on the supplied sqlite3_changeset_iter handle12528**   is sqlite3changeset_fk_conflicts().12529**12530** <dt>SQLITE_CHANGESET_CONSTRAINT<dd>12531**   If any other constraint violation occurs while applying a change (i.e.12532**   a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is12533**   invoked with CHANGESET_CONSTRAINT as the second argument.12534**12535**   There is no conflicting row in this case. The results of invoking the12536**   sqlite3changeset_conflict() API are undefined.12537**12538** </dl>12539*/12540#define SQLITE_CHANGESET_DATA        112541#define SQLITE_CHANGESET_NOTFOUND    212542#define SQLITE_CHANGESET_CONFLICT    312543#define SQLITE_CHANGESET_CONSTRAINT  412544#define SQLITE_CHANGESET_FOREIGN_KEY 51254512546/*12547** CAPI3REF: Constants Returned By The Conflict Handler12548**12549** A conflict handler callback must return one of the following three values.12550**12551** <dl>12552** <dt>SQLITE_CHANGESET_OMIT<dd>12553**   If a conflict handler returns this value no special action is taken. The12554**   change that caused the conflict is not applied. The session module12555**   continues to the next change in the changeset.12556**12557** <dt>SQLITE_CHANGESET_REPLACE<dd>12558**   This value may only be returned if the second argument to the conflict12559**   handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this12560**   is not the case, any changes applied so far are rolled back and the12561**   call to sqlite3changeset_apply() returns SQLITE_MISUSE.12562**12563**   If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict12564**   handler, then the conflicting row is either updated or deleted, depending12565**   on the type of change.12566**12567**   If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_CONFLICT conflict12568**   handler, then the conflicting row is removed from the database and a12569**   second attempt to apply the change is made. If this second attempt fails,12570**   the original row is restored to the database before continuing.12571**12572** <dt>SQLITE_CHANGESET_ABORT<dd>12573**   If this value is returned, any changes applied so far are rolled back12574**   and the call to sqlite3changeset_apply() returns SQLITE_ABORT.12575** </dl>12576*/12577#define SQLITE_CHANGESET_OMIT       012578#define SQLITE_CHANGESET_REPLACE    112579#define SQLITE_CHANGESET_ABORT      21258012581/*12582** CAPI3REF: Rebasing changesets12583** EXPERIMENTAL12584**12585** Suppose there is a site hosting a database in state S0. And that12586** modifications are made that move that database to state S1 and a12587** changeset recorded (the "local" changeset). Then, a changeset based12588** on S0 is received from another site (the "remote" changeset) and12589** applied to the database. The database is then in state12590** (S1+"remote"), where the exact state depends on any conflict12591** resolution decisions (OMIT or REPLACE) made while applying "remote".12592** Rebasing a changeset is to update it to take those conflict12593** resolution decisions into account, so that the same conflicts12594** do not have to be resolved elsewhere in the network.12595**12596** For example, if both the local and remote changesets contain an12597** INSERT of the same key on "CREATE TABLE t1(a PRIMARY KEY, b)":12598**12599**   local:  INSERT INTO t1 VALUES(1, 'v1');12600**   remote: INSERT INTO t1 VALUES(1, 'v2');12601**12602** and the conflict resolution is REPLACE, then the INSERT change is12603** removed from the local changeset (it was overridden). Or, if the12604** conflict resolution was "OMIT", then the local changeset is modified12605** to instead contain:12606**12607**           UPDATE t1 SET b = 'v2' WHERE a=1;12608**12609** Changes within the local changeset are rebased as follows:12610**12611** <dl>12612** <dt>Local INSERT<dd>12613**   This may only conflict with a remote INSERT. If the conflict12614**   resolution was OMIT, then add an UPDATE change to the rebased12615**   changeset. Or, if the conflict resolution was REPLACE, add12616**   nothing to the rebased changeset.12617**12618** <dt>Local DELETE<dd>12619**   This may conflict with a remote UPDATE or DELETE. In both cases the12620**   only possible resolution is OMIT. If the remote operation was a12621**   DELETE, then add no change to the rebased changeset. If the remote12622**   operation was an UPDATE, then the old.* fields of change are updated12623**   to reflect the new.* values in the UPDATE.12624**12625** <dt>Local UPDATE<dd>12626**   This may conflict with a remote UPDATE or DELETE. If it conflicts12627**   with a DELETE, and the conflict resolution was OMIT, then the update12628**   is changed into an INSERT. Any undefined values in the new.* record12629**   from the update change are filled in using the old.* values from12630**   the conflicting DELETE. Or, if the conflict resolution was REPLACE,12631**   the UPDATE change is simply omitted from the rebased changeset.12632**12633**   If conflict is with a remote UPDATE and the resolution is OMIT, then12634**   the old.* values are rebased using the new.* values in the remote12635**   change. Or, if the resolution is REPLACE, then the change is copied12636**   into the rebased changeset with updates to columns also updated by12637**   the conflicting remote UPDATE removed. If this means no columns would12638**   be updated, the change is omitted.12639** </dl>12640**12641** A local change may be rebased against multiple remote changes12642** simultaneously. If a single key is modified by multiple remote12643** changesets, they are combined as follows before the local changeset12644** is rebased:12645**12646** <ul>12647**    <li> If there has been one or more REPLACE resolutions on a12648**         key, it is rebased according to a REPLACE.12649**12650**    <li> If there have been no REPLACE resolutions on a key, then12651**         the local changeset is rebased according to the most recent12652**         of the OMIT resolutions.12653** </ul>12654**12655** Note that conflict resolutions from multiple remote changesets are12656** combined on a per-field basis, not per-row. This means that in the12657** case of multiple remote UPDATE operations, some fields of a single12658** local change may be rebased for REPLACE while others are rebased for12659** OMIT.12660**12661** In order to rebase a local changeset, the remote changeset must first12662** be applied to the local database using sqlite3changeset_apply_v2() and12663** the buffer of rebase information captured. Then:12664**12665** <ol>12666**   <li> An sqlite3_rebaser object is created by calling12667**        sqlite3rebaser_create().12668**   <li> The new object is configured with the rebase buffer obtained from12669**        sqlite3changeset_apply_v2() by calling sqlite3rebaser_configure().12670**        If the local changeset is to be rebased against multiple remote12671**        changesets, then sqlite3rebaser_configure() should be called12672**        multiple times, in the same order that the multiple12673**        sqlite3changeset_apply_v2() calls were made.12674**   <li> Each local changeset is rebased by calling sqlite3rebaser_rebase().12675**   <li> The sqlite3_rebaser object is deleted by calling12676**        sqlite3rebaser_delete().12677** </ol>12678*/12679typedef struct sqlite3_rebaser sqlite3_rebaser;1268012681/*12682** CAPI3REF: Create a changeset rebaser object.12683** EXPERIMENTAL12684**12685** Allocate a new changeset rebaser object. If successful, set (*ppNew) to12686** point to the new object and return SQLITE_OK. Otherwise, if an error12687** occurs, return an SQLite error code (e.g. SQLITE_NOMEM) and set (*ppNew)12688** to NULL.12689*/12690SQLITE_API int sqlite3rebaser_create(sqlite3_rebaser **ppNew);1269112692/*12693** CAPI3REF: Configure a changeset rebaser object.12694** EXPERIMENTAL12695**12696** Configure the changeset rebaser object to rebase changesets according12697** to the conflict resolutions described by buffer pRebase (size nRebase12698** bytes), which must have been obtained from a previous call to12699** sqlite3changeset_apply_v2().12700*/12701SQLITE_API int sqlite3rebaser_configure(12702  sqlite3_rebaser*,12703  int nRebase, const void *pRebase12704);1270512706/*12707** CAPI3REF: Rebase a changeset12708** EXPERIMENTAL12709**12710** Argument pIn must point to a buffer containing a changeset nIn bytes12711** in size. This function allocates and populates a buffer with a copy12712** of the changeset rebased according to the configuration of the12713** rebaser object passed as the first argument. If successful, (*ppOut)12714** is set to point to the new buffer containing the rebased changeset and12715** (*pnOut) to its size in bytes and SQLITE_OK returned. It is the12716** responsibility of the caller to eventually free the new buffer using12717** sqlite3_free(). Otherwise, if an error occurs, (*ppOut) and (*pnOut)12718** are set to zero and an SQLite error code returned.12719*/12720SQLITE_API int sqlite3rebaser_rebase(12721  sqlite3_rebaser*,12722  int nIn, const void *pIn,12723  int *pnOut, void **ppOut12724);1272512726/*12727** CAPI3REF: Delete a changeset rebaser object.12728** EXPERIMENTAL12729**12730** Delete the changeset rebaser object and all associated resources. There12731** should be one call to this function for each successful invocation12732** of sqlite3rebaser_create().12733*/12734SQLITE_API void sqlite3rebaser_delete(sqlite3_rebaser *p);1273512736/*12737** CAPI3REF: Streaming Versions of API functions.12738**12739** The six streaming API xxx_strm() functions serve similar purposes to the12740** corresponding non-streaming API functions:12741**12742** <table border=1 style="margin-left:8ex;margin-right:8ex">12743**   <tr><th>Streaming function<th>Non-streaming equivalent</th>12744**   <tr><td>sqlite3changeset_apply_strm<td>[sqlite3changeset_apply]12745**   <tr><td>sqlite3changeset_apply_strm_v2<td>[sqlite3changeset_apply_v2]12746**   <tr><td>sqlite3changeset_concat_strm<td>[sqlite3changeset_concat]12747**   <tr><td>sqlite3changeset_invert_strm<td>[sqlite3changeset_invert]12748**   <tr><td>sqlite3changeset_start_strm<td>[sqlite3changeset_start]12749**   <tr><td>sqlite3session_changeset_strm<td>[sqlite3session_changeset]12750**   <tr><td>sqlite3session_patchset_strm<td>[sqlite3session_patchset]12751** </table>12752**12753** Non-streaming functions that accept changesets (or patchsets) as input12754** require that the entire changeset be stored in a single buffer in memory.12755** Similarly, those that return a changeset or patchset do so by returning12756** a pointer to a single large buffer allocated using sqlite3_malloc().12757** Normally this is convenient. However, if an application running in a12758** low-memory environment is required to handle very large changesets, the12759** large contiguous memory allocations required can become onerous.12760**12761** In order to avoid this problem, instead of a single large buffer, input12762** is passed to a streaming API functions by way of a callback function that12763** the sessions module invokes to incrementally request input data as it is12764** required. In all cases, a pair of API function parameters such as12765**12766**  <pre>12767**  &nbsp;     int nChangeset,12768**  &nbsp;     void *pChangeset,12769**  </pre>12770**12771** Is replaced by:12772**12773**  <pre>12774**  &nbsp;     int (*xInput)(void *pIn, void *pData, int *pnData),12775**  &nbsp;     void *pIn,12776**  </pre>12777**12778** Each time the xInput callback is invoked by the sessions module, the first12779** argument passed is a copy of the supplied pIn context pointer. The second12780** argument, pData, points to a buffer (*pnData) bytes in size. Assuming no12781** error occurs the xInput method should copy up to (*pnData) bytes of data12782** into the buffer and set (*pnData) to the actual number of bytes copied12783** before returning SQLITE_OK. If the input is completely exhausted, (*pnData)12784** should be set to zero to indicate this. Or, if an error occurs, an SQLite12785** error code should be returned. In all cases, if an xInput callback returns12786** an error, all processing is abandoned and the streaming API function12787** returns a copy of the error code to the caller.12788**12789** In the case of sqlite3changeset_start_strm(), the xInput callback may be12790** invoked by the sessions module at any point during the lifetime of the12791** iterator. If such an xInput callback returns an error, the iterator enters12792** an error state, whereby all subsequent calls to iterator functions12793** immediately fail with the same error code as returned by xInput.12794**12795** Similarly, streaming API functions that return changesets (or patchsets)12796** return them in chunks by way of a callback function instead of via a12797** pointer to a single large buffer. In this case, a pair of parameters such12798** as:12799**12800**  <pre>12801**  &nbsp;     int *pnChangeset,12802**  &nbsp;     void **ppChangeset,12803**  </pre>12804**12805** Is replaced by:12806**12807**  <pre>12808**  &nbsp;     int (*xOutput)(void *pOut, const void *pData, int nData),12809**  &nbsp;     void *pOut12810**  </pre>12811**12812** The xOutput callback is invoked zero or more times to return data to12813** the application. The first parameter passed to each call is a copy of the12814** pOut pointer supplied by the application. The second parameter, pData,12815** points to a buffer nData bytes in size containing the chunk of output12816** data being returned. If the xOutput callback successfully processes the12817** supplied data, it should return SQLITE_OK to indicate success. Otherwise,12818** it should return some other SQLite error code. In this case processing12819** is immediately abandoned and the streaming API function returns a copy12820** of the xOutput error code to the application.12821**12822** The sessions module never invokes an xOutput callback with the third12823** parameter set to a value less than or equal to zero. Other than this,12824** no guarantees are made as to the size of the chunks of data returned.12825*/12826SQLITE_API int sqlite3changeset_apply_strm(12827  sqlite3 *db,                    /* Apply change to "main" db of this handle */12828  int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */12829  void *pIn,                                          /* First arg for xInput */12830  int(*xFilter)(12831    void *pCtx,                   /* Copy of sixth arg to _apply() */12832    const char *zTab              /* Table name */12833  ),12834  int(*xConflict)(12835    void *pCtx,                   /* Copy of sixth arg to _apply() */12836    int eConflict,                /* DATA, MISSING, CONFLICT, CONSTRAINT */12837    sqlite3_changeset_iter *p     /* Handle describing change and conflict */12838  ),12839  void *pCtx                      /* First argument passed to xConflict */12840);12841SQLITE_API int sqlite3changeset_apply_v2_strm(12842  sqlite3 *db,                    /* Apply change to "main" db of this handle */12843  int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */12844  void *pIn,                                          /* First arg for xInput */12845  int(*xFilter)(12846    void *pCtx,                   /* Copy of sixth arg to _apply() */12847    const char *zTab              /* Table name */12848  ),12849  int(*xConflict)(12850    void *pCtx,                   /* Copy of sixth arg to _apply() */12851    int eConflict,                /* DATA, MISSING, CONFLICT, CONSTRAINT */12852    sqlite3_changeset_iter *p     /* Handle describing change and conflict */12853  ),12854  void *pCtx,                     /* First argument passed to xConflict */12855  void **ppRebase, int *pnRebase,12856  int flags12857);12858SQLITE_API int sqlite3changeset_concat_strm(12859  int (*xInputA)(void *pIn, void *pData, int *pnData),12860  void *pInA,12861  int (*xInputB)(void *pIn, void *pData, int *pnData),12862  void *pInB,12863  int (*xOutput)(void *pOut, const void *pData, int nData),12864  void *pOut12865);12866SQLITE_API int sqlite3changeset_invert_strm(12867  int (*xInput)(void *pIn, void *pData, int *pnData),12868  void *pIn,12869  int (*xOutput)(void *pOut, const void *pData, int nData),12870  void *pOut12871);12872SQLITE_API int sqlite3changeset_start_strm(12873  sqlite3_changeset_iter **pp,12874  int (*xInput)(void *pIn, void *pData, int *pnData),12875  void *pIn12876);12877SQLITE_API int sqlite3changeset_start_v2_strm(12878  sqlite3_changeset_iter **pp,12879  int (*xInput)(void *pIn, void *pData, int *pnData),12880  void *pIn,12881  int flags12882);12883SQLITE_API int sqlite3session_changeset_strm(12884  sqlite3_session *pSession,12885  int (*xOutput)(void *pOut, const void *pData, int nData),12886  void *pOut12887);12888SQLITE_API int sqlite3session_patchset_strm(12889  sqlite3_session *pSession,12890  int (*xOutput)(void *pOut, const void *pData, int nData),12891  void *pOut12892);12893SQLITE_API int sqlite3changegroup_add_strm(sqlite3_changegroup*,12894    int (*xInput)(void *pIn, void *pData, int *pnData),12895    void *pIn12896);12897SQLITE_API int sqlite3changegroup_output_strm(sqlite3_changegroup*,12898    int (*xOutput)(void *pOut, const void *pData, int nData),12899    void *pOut12900);12901SQLITE_API int sqlite3rebaser_rebase_strm(12902  sqlite3_rebaser *pRebaser,12903  int (*xInput)(void *pIn, void *pData, int *pnData),12904  void *pIn,12905  int (*xOutput)(void *pOut, const void *pData, int nData),12906  void *pOut12907);1290812909/*12910** CAPI3REF: Configure global parameters12911**12912** The sqlite3session_config() interface is used to make global configuration12913** changes to the sessions module in order to tune it to the specific needs12914** of the application.12915**12916** The sqlite3session_config() interface is not threadsafe. If it is invoked12917** while any other thread is inside any other sessions method then the12918** results are undefined. Furthermore, if it is invoked after any sessions12919** related objects have been created, the results are also undefined.12920**12921** The first argument to the sqlite3session_config() function must be one12922** of the SQLITE_SESSION_CONFIG_XXX constants defined below. The12923** interpretation of the (void*) value passed as the second parameter and12924** the effect of calling this function depends on the value of the first12925** parameter.12926**12927** <dl>12928** <dt>SQLITE_SESSION_CONFIG_STRMSIZE<dd>12929**    By default, the sessions module streaming interfaces attempt to input12930**    and output data in approximately 1 KiB chunks. This operand may be used12931**    to set and query the value of this configuration setting. The pointer12932**    passed as the second argument must point to a value of type (int).12933**    If this value is greater than 0, it is used as the new streaming data12934**    chunk size for both input and output. Before returning, the (int) value12935**    pointed to by pArg is set to the final value of the streaming interface12936**    chunk size.12937** </dl>12938**12939** This function returns SQLITE_OK if successful, or an SQLite error code12940** otherwise.12941*/12942SQLITE_API int sqlite3session_config(int op, void *pArg);1294312944/*12945** CAPI3REF: Values for sqlite3session_config().12946*/12947#define SQLITE_SESSION_CONFIG_STRMSIZE 11294812949/*12950** Make sure we can call this stuff from C++.12951*/12952#ifdef __cplusplus12953}12954#endif1295512956#endif  /* !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION) */1295712958/******** End of sqlite3session.h *********/12959/******** Begin file fts5.h *********/12960/*12961** 2014 May 3112962**12963** The author disclaims copyright to this source code.  In place of12964** a legal notice, here is a blessing:12965**12966**    May you do good and not evil.12967**    May you find forgiveness for yourself and forgive others.12968**    May you share freely, never taking more than you give.12969**12970******************************************************************************12971**12972** Interfaces to extend FTS5. Using the interfaces defined in this file,12973** FTS5 may be extended with:12974**12975**     * custom tokenizers, and12976**     * custom auxiliary functions.12977*/129781297912980#ifndef _FTS5_H12981#define _FTS5_H129821298312984#ifdef __cplusplus12985extern "C" {12986#endif1298712988/*************************************************************************12989** CUSTOM AUXILIARY FUNCTIONS12990**12991** Virtual table implementations may overload SQL functions by implementing12992** the sqlite3_module.xFindFunction() method.12993*/1299412995typedef struct Fts5ExtensionApi Fts5ExtensionApi;12996typedef struct Fts5Context Fts5Context;12997typedef struct Fts5PhraseIter Fts5PhraseIter;1299812999typedef void (*fts5_extension_function)(13000  const Fts5ExtensionApi *pApi,   /* API offered by current FTS version */13001  Fts5Context *pFts,              /* First arg to pass to pApi functions */13002  sqlite3_context *pCtx,          /* Context for returning result/error */13003  int nVal,                       /* Number of values in apVal[] array */13004  sqlite3_value **apVal           /* Array of trailing arguments */13005);1300613007struct Fts5PhraseIter {13008  const unsigned char *a;13009  const unsigned char *b;13010};1301113012/*13013** EXTENSION API FUNCTIONS13014**13015** xUserData(pFts):13016**   Return a copy of the pUserData pointer passed to the xCreateFunction()13017**   API when the extension function was registered.13018**13019** xColumnTotalSize(pFts, iCol, pnToken):13020**   If parameter iCol is less than zero, set output variable *pnToken13021**   to the total number of tokens in the FTS5 table. Or, if iCol is13022**   non-negative but less than the number of columns in the table, return13023**   the total number of tokens in column iCol, considering all rows in13024**   the FTS5 table.13025**13026**   If parameter iCol is greater than or equal to the number of columns13027**   in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.13028**   an OOM condition or IO error), an appropriate SQLite error code is13029**   returned.13030**13031** xColumnCount(pFts):13032**   Return the number of columns in the table.13033**13034** xColumnSize(pFts, iCol, pnToken):13035**   If parameter iCol is less than zero, set output variable *pnToken13036**   to the total number of tokens in the current row. Or, if iCol is13037**   non-negative but less than the number of columns in the table, set13038**   *pnToken to the number of tokens in column iCol of the current row.13039**13040**   If parameter iCol is greater than or equal to the number of columns13041**   in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.13042**   an OOM condition or IO error), an appropriate SQLite error code is13043**   returned.13044**13045**   This function may be quite inefficient if used with an FTS5 table13046**   created with the "columnsize=0" option.13047**13048** xColumnText:13049**   If parameter iCol is less than zero, or greater than or equal to the13050**   number of columns in the table, SQLITE_RANGE is returned.13051**13052**   Otherwise, this function attempts to retrieve the text of column iCol of13053**   the current document. If successful, (*pz) is set to point to a buffer13054**   containing the text in utf-8 encoding, (*pn) is set to the size in bytes13055**   (not characters) of the buffer and SQLITE_OK is returned. Otherwise,13056**   if an error occurs, an SQLite error code is returned and the final values13057**   of (*pz) and (*pn) are undefined.13058**13059** xPhraseCount:13060**   Returns the number of phrases in the current query expression.13061**13062** xPhraseSize:13063**   If parameter iCol is less than zero, or greater than or equal to the13064**   number of phrases in the current query, as returned by xPhraseCount,13065**   0 is returned. Otherwise, this function returns the number of tokens in13066**   phrase iPhrase of the query. Phrases are numbered starting from zero.13067**13068** xInstCount:13069**   Set *pnInst to the total number of occurrences of all phrases within13070**   the query within the current row. Return SQLITE_OK if successful, or13071**   an error code (i.e. SQLITE_NOMEM) if an error occurs.13072**13073**   This API can be quite slow if used with an FTS5 table created with the13074**   "detail=none" or "detail=column" option. If the FTS5 table is created13075**   with either "detail=none" or "detail=column" and "content=" option13076**   (i.e. if it is a contentless table), then this API always returns 0.13077**13078** xInst:13079**   Query for the details of phrase match iIdx within the current row.13080**   Phrase matches are numbered starting from zero, so the iIdx argument13081**   should be greater than or equal to zero and smaller than the value13082**   output by xInstCount(). If iIdx is less than zero or greater than13083**   or equal to the value returned by xInstCount(), SQLITE_RANGE is returned.13084**13085**   Otherwise, output parameter *piPhrase is set to the phrase number, *piCol13086**   to the column in which it occurs and *piOff the token offset of the13087**   first token of the phrase. SQLITE_OK is returned if successful, or an13088**   error code (i.e. SQLITE_NOMEM) if an error occurs.13089**13090**   This API can be quite slow if used with an FTS5 table created with the13091**   "detail=none" or "detail=column" option.13092**13093** xRowid:13094**   Returns the rowid of the current row.13095**13096** xTokenize:13097**   Tokenize text using the tokenizer belonging to the FTS5 table.13098**13099** xQueryPhrase(pFts5, iPhrase, pUserData, xCallback):13100**   This API function is used to query the FTS table for phrase iPhrase13101**   of the current query. Specifically, a query equivalent to:13102**13103**       ... FROM ftstable WHERE ftstable MATCH $p ORDER BY rowid13104**13105**   with $p set to a phrase equivalent to the phrase iPhrase of the13106**   current query is executed. Any column filter that applies to13107**   phrase iPhrase of the current query is included in $p. For each13108**   row visited, the callback function passed as the fourth argument13109**   is invoked. The context and API objects passed to the callback13110**   function may be used to access the properties of each matched row.13111**   Invoking Api.xUserData() returns a copy of the pointer passed as13112**   the third argument to pUserData.13113**13114**   If parameter iPhrase is less than zero, or greater than or equal to13115**   the number of phrases in the query, as returned by xPhraseCount(),13116**   this function returns SQLITE_RANGE.13117**13118**   If the callback function returns any value other than SQLITE_OK, the13119**   query is abandoned and the xQueryPhrase function returns immediately.13120**   If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK.13121**   Otherwise, the error code is propagated upwards.13122**13123**   If the query runs to completion without incident, SQLITE_OK is returned.13124**   Or, if some error occurs before the query completes or is aborted by13125**   the callback, an SQLite error code is returned.13126**13127**13128** xSetAuxdata(pFts5, pAux, xDelete)13129**13130**   Save the pointer passed as the second argument as the extension function's13131**   "auxiliary data". The pointer may then be retrieved by the current or any13132**   future invocation of the same fts5 extension function made as part of13133**   the same MATCH query using the xGetAuxdata() API.13134**13135**   Each extension function is allocated a single auxiliary data slot for13136**   each FTS query (MATCH expression). If the extension function is invoked13137**   more than once for a single FTS query, then all invocations share a13138**   single auxiliary data context.13139**13140**   If there is already an auxiliary data pointer when this function is13141**   invoked, then it is replaced by the new pointer. If an xDelete callback13142**   was specified along with the original pointer, it is invoked at this13143**   point.13144**13145**   The xDelete callback, if one is specified, is also invoked on the13146**   auxiliary data pointer after the FTS5 query has finished.13147**13148**   If an error (e.g. an OOM condition) occurs within this function,13149**   the auxiliary data is set to NULL and an error code returned. If the13150**   xDelete parameter was not NULL, it is invoked on the auxiliary data13151**   pointer before returning.13152**13153**13154** xGetAuxdata(pFts5, bClear)13155**13156**   Returns the current auxiliary data pointer for the fts5 extension13157**   function. See the xSetAuxdata() method for details.13158**13159**   If the bClear argument is non-zero, then the auxiliary data is cleared13160**   (set to NULL) before this function returns. In this case the xDelete,13161**   if any, is not invoked.13162**13163**13164** xRowCount(pFts5, pnRow)13165**13166**   This function is used to retrieve the total number of rows in the table.13167**   In other words, the same value that would be returned by:13168**13169**        SELECT count(*) FROM ftstable;13170**13171** xPhraseFirst()13172**   This function is used, along with type Fts5PhraseIter and the xPhraseNext13173**   method, to iterate through all instances of a single query phrase within13174**   the current row. This is the same information as is accessible via the13175**   xInstCount/xInst APIs. While the xInstCount/xInst APIs are more convenient13176**   to use, this API may be faster under some circumstances. To iterate13177**   through instances of phrase iPhrase, use the following code:13178**13179**       Fts5PhraseIter iter;13180**       int iCol, iOff;13181**       for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff);13182**           iCol>=0;13183**           pApi->xPhraseNext(pFts, &iter, &iCol, &iOff)13184**       ){13185**         // An instance of phrase iPhrase at offset iOff of column iCol13186**       }13187**13188**   The Fts5PhraseIter structure is defined above. Applications should not13189**   modify this structure directly - it should only be used as shown above13190**   with the xPhraseFirst() and xPhraseNext() API methods (and by13191**   xPhraseFirstColumn() and xPhraseNextColumn() as illustrated below).13192**13193**   This API can be quite slow if used with an FTS5 table created with the13194**   "detail=none" or "detail=column" option. If the FTS5 table is created13195**   with either "detail=none" or "detail=column" and "content=" option13196**   (i.e. if it is a contentless table), then this API always iterates13197**   through an empty set (all calls to xPhraseFirst() set iCol to -1).13198**13199**   In all cases, matches are visited in (column ASC, offset ASC) order.13200**   i.e. all those in column 0, sorted by offset, followed by those in13201**   column 1, etc.13202**13203** xPhraseNext()13204**   See xPhraseFirst above.13205**13206** xPhraseFirstColumn()13207**   This function and xPhraseNextColumn() are similar to the xPhraseFirst()13208**   and xPhraseNext() APIs described above. The difference is that instead13209**   of iterating through all instances of a phrase in the current row, these13210**   APIs are used to iterate through the set of columns in the current row13211**   that contain one or more instances of a specified phrase. For example:13212**13213**       Fts5PhraseIter iter;13214**       int iCol;13215**       for(pApi->xPhraseFirstColumn(pFts, iPhrase, &iter, &iCol);13216**           iCol>=0;13217**           pApi->xPhraseNextColumn(pFts, &iter, &iCol)13218**       ){13219**         // Column iCol contains at least one instance of phrase iPhrase13220**       }13221**13222**   This API can be quite slow if used with an FTS5 table created with the13223**   "detail=none" option. If the FTS5 table is created with either13224**   "detail=none" "content=" option (i.e. if it is a contentless table),13225**   then this API always iterates through an empty set (all calls to13226**   xPhraseFirstColumn() set iCol to -1).13227**13228**   The information accessed using this API and its companion13229**   xPhraseFirstColumn() may also be obtained using xPhraseFirst/xPhraseNext13230**   (or xInst/xInstCount). The chief advantage of this API is that it is13231**   significantly more efficient than those alternatives when used with13232**   "detail=column" tables.13233**13234** xPhraseNextColumn()13235**   See xPhraseFirstColumn above.13236**13237** xQueryToken(pFts5, iPhrase, iToken, ppToken, pnToken)13238**   This is used to access token iToken of phrase iPhrase of the current13239**   query. Before returning, output parameter *ppToken is set to point13240**   to a buffer containing the requested token, and *pnToken to the13241**   size of this buffer in bytes.13242**13243**   If iPhrase or iToken are less than zero, or if iPhrase is greater than13244**   or equal to the number of phrases in the query as reported by13245**   xPhraseCount(), or if iToken is equal to or greater than the number of13246**   tokens in the phrase, SQLITE_RANGE is returned and *ppToken and *pnToken13247     are both zeroed.13248**13249**   The output text is not a copy of the query text that specified the13250**   token. It is the output of the tokenizer module. For tokendata=113251**   tables, this includes any embedded 0x00 and trailing data.13252**13253** xInstToken(pFts5, iIdx, iToken, ppToken, pnToken)13254**   This is used to access token iToken of phrase hit iIdx within the13255**   current row. If iIdx is less than zero or greater than or equal to the13256**   value returned by xInstCount(), SQLITE_RANGE is returned.  Otherwise,13257**   output variable (*ppToken) is set to point to a buffer containing the13258**   matching document token, and (*pnToken) to the size of that buffer in13259**   bytes.13260**13261**   The output text is not a copy of the document text that was tokenized.13262**   It is the output of the tokenizer module. For tokendata=1 tables, this13263**   includes any embedded 0x00 and trailing data.13264**13265**   This API may be slow in some cases if the token identified by parameters13266**   iIdx and iToken matched a prefix token in the query. In most cases, the13267**   first call to this API for each prefix token in the query is forced13268**   to scan the portion of the full-text index that matches the prefix13269**   token to collect the extra data required by this API. If the prefix13270**   token matches a large number of token instances in the document set,13271**   this may be a performance problem.13272**13273**   If the user knows in advance that a query may use this API for a13274**   prefix token, FTS5 may be configured to collect all required data as part13275**   of the initial querying of the full-text index, avoiding the second scan13276**   entirely. This also causes prefix queries that do not use this API to13277**   run more slowly and use more memory. FTS5 may be configured in this way13278**   either on a per-table basis using the [FTS5 insttoken | 'insttoken']13279**   option, or on a per-query basis using the13280**   [fts5_insttoken | fts5_insttoken()] user function.13281**13282**   This API can be quite slow if used with an FTS5 table created with the13283**   "detail=none" or "detail=column" option.13284**13285** xColumnLocale(pFts5, iIdx, pzLocale, pnLocale)13286**   If parameter iCol is less than zero, or greater than or equal to the13287**   number of columns in the table, SQLITE_RANGE is returned.13288**13289**   Otherwise, this function attempts to retrieve the locale associated13290**   with column iCol of the current row. Usually, there is no associated13291**   locale, and output parameters (*pzLocale) and (*pnLocale) are set13292**   to NULL and 0, respectively. However, if the fts5_locale() function13293**   was used to associate a locale with the value when it was inserted13294**   into the fts5 table, then (*pzLocale) is set to point to a nul-terminated13295**   buffer containing the name of the locale in utf-8 encoding. (*pnLocale)13296**   is set to the size in bytes of the buffer, not including the13297**   nul-terminator.13298**13299**   If successful, SQLITE_OK is returned. Or, if an error occurs, an13300**   SQLite error code is returned. The final value of the output parameters13301**   is undefined in this case.13302**13303** xTokenize_v2:13304**   Tokenize text using the tokenizer belonging to the FTS5 table. This13305**   API is the same as the xTokenize() API, except that it allows a tokenizer13306**   locale to be specified.13307*/13308struct Fts5ExtensionApi {13309  int iVersion;                   /* Currently always set to 4 */1331013311  void *(*xUserData)(Fts5Context*);1331213313  int (*xColumnCount)(Fts5Context*);13314  int (*xRowCount)(Fts5Context*, sqlite3_int64 *pnRow);13315  int (*xColumnTotalSize)(Fts5Context*, int iCol, sqlite3_int64 *pnToken);1331613317  int (*xTokenize)(Fts5Context*,13318    const char *pText, int nText, /* Text to tokenize */13319    void *pCtx,                   /* Context passed to xToken() */13320    int (*xToken)(void*, int, const char*, int, int, int)       /* Callback */13321  );1332213323  int (*xPhraseCount)(Fts5Context*);13324  int (*xPhraseSize)(Fts5Context*, int iPhrase);1332513326  int (*xInstCount)(Fts5Context*, int *pnInst);13327  int (*xInst)(Fts5Context*, int iIdx, int *piPhrase, int *piCol, int *piOff);1332813329  sqlite3_int64 (*xRowid)(Fts5Context*);13330  int (*xColumnText)(Fts5Context*, int iCol, const char **pz, int *pn);13331  int (*xColumnSize)(Fts5Context*, int iCol, int *pnToken);1333213333  int (*xQueryPhrase)(Fts5Context*, int iPhrase, void *pUserData,13334    int(*)(const Fts5ExtensionApi*,Fts5Context*,void*)13335  );13336  int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*));13337  void *(*xGetAuxdata)(Fts5Context*, int bClear);1333813339  int (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*);13340  void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff);1334113342  int (*xPhraseFirstColumn)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*);13343  void (*xPhraseNextColumn)(Fts5Context*, Fts5PhraseIter*, int *piCol);1334413345  /* Below this point are iVersion>=3 only */13346  int (*xQueryToken)(Fts5Context*,13347      int iPhrase, int iToken,13348      const char **ppToken, int *pnToken13349  );13350  int (*xInstToken)(Fts5Context*, int iIdx, int iToken, const char**, int*);1335113352  /* Below this point are iVersion>=4 only */13353  int (*xColumnLocale)(Fts5Context*, int iCol, const char **pz, int *pn);13354  int (*xTokenize_v2)(Fts5Context*,13355    const char *pText, int nText,      /* Text to tokenize */13356    const char *pLocale, int nLocale,  /* Locale to pass to tokenizer */13357    void *pCtx,                        /* Context passed to xToken() */13358    int (*xToken)(void*, int, const char*, int, int, int)       /* Callback */13359  );13360};1336113362/*13363** CUSTOM AUXILIARY FUNCTIONS13364*************************************************************************/1336513366/*************************************************************************13367** CUSTOM TOKENIZERS13368**13369** Applications may also register custom tokenizer types. A tokenizer13370** is registered by providing fts5 with a populated instance of the13371** following structure. All structure methods must be defined, setting13372** any member of the fts5_tokenizer struct to NULL leads to undefined13373** behaviour. The structure methods are expected to function as follows:13374**13375** xCreate:13376**   This function is used to allocate and initialize a tokenizer instance.13377**   A tokenizer instance is required to actually tokenize text.13378**13379**   The first argument passed to this function is a copy of the (void*)13380**   pointer provided by the application when the fts5_tokenizer_v2 object13381**   was registered with FTS5 (the third argument to xCreateTokenizer()).13382**   The second and third arguments are an array of nul-terminated strings13383**   containing the tokenizer arguments, if any, specified following the13384**   tokenizer name as part of the CREATE VIRTUAL TABLE statement used13385**   to create the FTS5 table.13386**13387**   The final argument is an output variable. If successful, (*ppOut)13388**   should be set to point to the new tokenizer handle and SQLITE_OK13389**   returned. If an error occurs, some value other than SQLITE_OK should13390**   be returned. In this case, fts5 assumes that the final value of *ppOut13391**   is undefined.13392**13393** xDelete:13394**   This function is invoked to delete a tokenizer handle previously13395**   allocated using xCreate(). Fts5 guarantees that this function will13396**   be invoked exactly once for each successful call to xCreate().13397**13398** xTokenize:13399**   This function is expected to tokenize the nText byte string indicated13400**   by argument pText. pText may or may not be nul-terminated. The first13401**   argument passed to this function is a pointer to an Fts5Tokenizer object13402**   returned by an earlier call to xCreate().13403**13404**   The third argument indicates the reason that FTS5 is requesting13405**   tokenization of the supplied text. This is always one of the following13406**   four values:13407**13408**   <ul><li> <b>FTS5_TOKENIZE_DOCUMENT</b> - A document is being inserted into13409**            or removed from the FTS table. The tokenizer is being invoked to13410**            determine the set of tokens to add to (or delete from) the13411**            FTS index.13412**13413**       <li> <b>FTS5_TOKENIZE_QUERY</b> - A MATCH query is being executed13414**            against the FTS index. The tokenizer is being called to tokenize13415**            a bareword or quoted string specified as part of the query.13416**13417**       <li> <b>(FTS5_TOKENIZE_QUERY | FTS5_TOKENIZE_PREFIX)</b> - Same as13418**            FTS5_TOKENIZE_QUERY, except that the bareword or quoted string is13419**            followed by a "*" character, indicating that the last token13420**            returned by the tokenizer will be treated as a token prefix.13421**13422**       <li> <b>FTS5_TOKENIZE_AUX</b> - The tokenizer is being invoked to13423**            satisfy an fts5_api.xTokenize() request made by an auxiliary13424**            function. Or an fts5_api.xColumnSize() request made by the same13425**            on a columnsize=0 database.13426**   </ul>13427**13428**   The sixth and seventh arguments passed to xTokenize() - pLocale and13429**   nLocale - are a pointer to a buffer containing the locale to use for13430**   tokenization (e.g. "en_US") and its size in bytes, respectively. The13431**   pLocale buffer is not nul-terminated. pLocale may be passed NULL (in13432**   which case nLocale is always 0) to indicate that the tokenizer should13433**   use its default locale.13434**13435**   For each token in the input string, the supplied callback xToken() must13436**   be invoked. The first argument to it should be a copy of the pointer13437**   passed as the second argument to xTokenize(). The third and fourth13438**   arguments are a pointer to a buffer containing the token text, and the13439**   size of the token in bytes. The 4th and 5th arguments are the byte offsets13440**   of the first byte of and first byte immediately following the text from13441**   which the token is derived within the input.13442**13443**   The second argument passed to the xToken() callback ("tflags") should13444**   normally be set to 0. The exception is if the tokenizer supports13445**   synonyms. In this case see the discussion below for details.13446**13447**   FTS5 assumes the xToken() callback is invoked for each token in the13448**   order that they occur within the input text.13449**13450**   If an xToken() callback returns any value other than SQLITE_OK, then13451**   the tokenization should be abandoned and the xTokenize() method should13452**   immediately return a copy of the xToken() return value. Or, if the13453**   input buffer is exhausted, xTokenize() should return SQLITE_OK. Finally,13454**   if an error occurs with the xTokenize() implementation itself, it13455**   may abandon the tokenization and return any error code other than13456**   SQLITE_OK or SQLITE_DONE.13457**13458**   If the tokenizer is registered using an fts5_tokenizer_v2 object,13459**   then the xTokenize() method has two additional arguments - pLocale13460**   and nLocale. These specify the locale that the tokenizer should use13461**   for the current request. If pLocale and nLocale are both 0, then the13462**   tokenizer should use its default locale. Otherwise, pLocale points to13463**   an nLocale byte buffer containing the name of the locale to use as utf-813464**   text. pLocale is not nul-terminated.13465**13466** FTS5_TOKENIZER13467**13468** There is also an fts5_tokenizer object. This is an older, deprecated,13469** version of fts5_tokenizer_v2. It is similar except that:13470**13471**  <ul>13472**    <li> There is no "iVersion" field, and13473**    <li> The xTokenize() method does not take a locale argument.13474**  </ul>13475**13476** Legacy fts5_tokenizer tokenizers must be registered using the13477** legacy xCreateTokenizer() function, instead of xCreateTokenizer_v2().13478**13479** Tokenizer implementations registered using either API may be retrieved13480** using both xFindTokenizer() and xFindTokenizer_v2().13481**13482** SYNONYM SUPPORT13483**13484**   Custom tokenizers may also support synonyms. Consider a case in which a13485**   user wishes to query for a phrase such as "first place". Using the13486**   built-in tokenizers, the FTS5 query 'first + place' will match instances13487**   of "first place" within the document set, but not alternative forms13488**   such as "1st place". In some applications, it would be better to match13489**   all instances of "first place" or "1st place" regardless of which form13490**   the user specified in the MATCH query text.13491**13492**   There are several ways to approach this in FTS5:13493**13494**   <ol><li> By mapping all synonyms to a single token. In this case, using13495**            the above example, this means that the tokenizer returns the13496**            same token for inputs "first" and "1st". Say that token is in13497**            fact "first", so that when the user inserts the document "I won13498**            1st place" entries are added to the index for tokens "i", "won",13499**            "first" and "place". If the user then queries for '1st + place',13500**            the tokenizer substitutes "first" for "1st" and the query works13501**            as expected.13502**13503**       <li> By querying the index for all synonyms of each query term13504**            separately. In this case, when tokenizing query text, the13505**            tokenizer may provide multiple synonyms for a single term13506**            within the document. FTS5 then queries the index for each13507**            synonym individually. For example, faced with the query:13508**13509**   <codeblock>13510**     ... MATCH 'first place'</codeblock>13511**13512**            the tokenizer offers both "1st" and "first" as synonyms for the13513**            first token in the MATCH query and FTS5 effectively runs a query13514**            similar to:13515**13516**   <codeblock>13517**     ... MATCH '(first OR 1st) place'</codeblock>13518**13519**            except that, for the purposes of auxiliary functions, the query13520**            still appears to contain just two phrases - "(first OR 1st)"13521**            being treated as a single phrase.13522**13523**       <li> By adding multiple synonyms for a single term to the FTS index.13524**            Using this method, when tokenizing document text, the tokenizer13525**            provides multiple synonyms for each token. So that when a13526**            document such as "I won first place" is tokenized, entries are13527**            added to the FTS index for "i", "won", "first", "1st" and13528**            "place".13529**13530**            This way, even if the tokenizer does not provide synonyms13531**            when tokenizing query text (it should not - to do so would be13532**            inefficient), it doesn't matter if the user queries for13533**            'first + place' or '1st + place', as there are entries in the13534**            FTS index corresponding to both forms of the first token.13535**   </ol>13536**13537**   Whether it is parsing document or query text, any call to xToken that13538**   specifies a <i>tflags</i> argument with the FTS5_TOKEN_COLOCATED bit13539**   is considered to supply a synonym for the previous token. For example,13540**   when parsing the document "I won first place", a tokenizer that supports13541**   synonyms would call xToken() 5 times, as follows:13542**13543**   <codeblock>13544**       xToken(pCtx, 0, "i",                      1,  0,  1);13545**       xToken(pCtx, 0, "won",                    3,  2,  5);13546**       xToken(pCtx, 0, "first",                  5,  6, 11);13547**       xToken(pCtx, FTS5_TOKEN_COLOCATED, "1st", 3,  6, 11);13548**       xToken(pCtx, 0, "place",                  5, 12, 17);13549**</codeblock>13550**13551**   It is an error to specify the FTS5_TOKEN_COLOCATED flag the first time13552**   xToken() is called. Multiple synonyms may be specified for a single token13553**   by making multiple calls to xToken(FTS5_TOKEN_COLOCATED) in sequence.13554**   There is no limit to the number of synonyms that may be provided for a13555**   single token.13556**13557**   In many cases, method (1) above is the best approach. It does not add13558**   extra data to the FTS index or require FTS5 to query for multiple terms,13559**   so it is efficient in terms of disk space and query speed. However, it13560**   does not support prefix queries very well. If, as suggested above, the13561**   token "first" is substituted for "1st" by the tokenizer, then the query:13562**13563**   <codeblock>13564**     ... MATCH '1s*'</codeblock>13565**13566**   will not match documents that contain the token "1st" (as the tokenizer13567**   will probably not map "1s" to any prefix of "first").13568**13569**   For full prefix support, method (3) may be preferred. In this case,13570**   because the index contains entries for both "first" and "1st", prefix13571**   queries such as 'fi*' or '1s*' will match correctly. However, because13572**   extra entries are added to the FTS index, this method uses more space13573**   within the database.13574**13575**   Method (2) offers a midpoint between (1) and (3). Using this method,13576**   a query such as '1s*' will match documents that contain the literal13577**   token "1st", but not "first" (assuming the tokenizer is not able to13578**   provide synonyms for prefixes). However, a non-prefix query like '1st'13579**   will match against "1st" and "first". This method does not require13580**   extra disk space, as no extra entries are added to the FTS index.13581**   On the other hand, it may require more CPU cycles to run MATCH queries,13582**   as separate queries of the FTS index are required for each synonym.13583**13584**   When using methods (2) or (3), it is important that the tokenizer only13585**   provide synonyms when tokenizing document text (method (3)) or query13586**   text (method (2)), not both. Doing so will not cause any errors, but is13587**   inefficient.13588*/13589typedef struct Fts5Tokenizer Fts5Tokenizer;13590typedef struct fts5_tokenizer_v2 fts5_tokenizer_v2;13591struct fts5_tokenizer_v2 {13592  int iVersion;             /* Currently always 2 */1359313594  int (*xCreate)(void*, const char **azArg, int nArg, Fts5Tokenizer **ppOut);13595  void (*xDelete)(Fts5Tokenizer*);13596  int (*xTokenize)(Fts5Tokenizer*,13597      void *pCtx,13598      int flags,            /* Mask of FTS5_TOKENIZE_* flags */13599      const char *pText, int nText,13600      const char *pLocale, int nLocale,13601      int (*xToken)(13602        void *pCtx,         /* Copy of 2nd argument to xTokenize() */13603        int tflags,         /* Mask of FTS5_TOKEN_* flags */13604        const char *pToken, /* Pointer to buffer containing token */13605        int nToken,         /* Size of token in bytes */13606        int iStart,         /* Byte offset of token within input text */13607        int iEnd            /* Byte offset of end of token within input text */13608      )13609  );13610};1361113612/*13613** New code should use the fts5_tokenizer_v2 type to define tokenizer13614** implementations. The following type is included for legacy applications13615** that still use it.13616*/13617typedef struct fts5_tokenizer fts5_tokenizer;13618struct fts5_tokenizer {13619  int (*xCreate)(void*, const char **azArg, int nArg, Fts5Tokenizer **ppOut);13620  void (*xDelete)(Fts5Tokenizer*);13621  int (*xTokenize)(Fts5Tokenizer*,13622      void *pCtx,13623      int flags,            /* Mask of FTS5_TOKENIZE_* flags */13624      const char *pText, int nText,13625      int (*xToken)(13626        void *pCtx,         /* Copy of 2nd argument to xTokenize() */13627        int tflags,         /* Mask of FTS5_TOKEN_* flags */13628        const char *pToken, /* Pointer to buffer containing token */13629        int nToken,         /* Size of token in bytes */13630        int iStart,         /* Byte offset of token within input text */13631        int iEnd            /* Byte offset of end of token within input text */13632      )13633  );13634};136351363613637/* Flags that may be passed as the third argument to xTokenize() */13638#define FTS5_TOKENIZE_QUERY     0x000113639#define FTS5_TOKENIZE_PREFIX    0x000213640#define FTS5_TOKENIZE_DOCUMENT  0x000413641#define FTS5_TOKENIZE_AUX       0x00081364213643/* Flags that may be passed by the tokenizer implementation back to FTS513644** as the third argument to the supplied xToken callback. */13645#define FTS5_TOKEN_COLOCATED    0x0001      /* Same position as prev. token */1364613647/*13648** END OF CUSTOM TOKENIZERS13649*************************************************************************/1365013651/*************************************************************************13652** FTS5 EXTENSION REGISTRATION API13653*/13654typedef struct fts5_api fts5_api;13655struct fts5_api {13656  int iVersion;                   /* Currently always set to 3 */1365713658  /* Create a new tokenizer */13659  int (*xCreateTokenizer)(13660    fts5_api *pApi,13661    const char *zName,13662    void *pUserData,13663    fts5_tokenizer *pTokenizer,13664    void (*xDestroy)(void*)13665  );1366613667  /* Find an existing tokenizer */13668  int (*xFindTokenizer)(13669    fts5_api *pApi,13670    const char *zName,13671    void **ppUserData,13672    fts5_tokenizer *pTokenizer13673  );1367413675  /* Create a new auxiliary function */13676  int (*xCreateFunction)(13677    fts5_api *pApi,13678    const char *zName,13679    void *pUserData,13680    fts5_extension_function xFunction,13681    void (*xDestroy)(void*)13682  );1368313684  /* APIs below this point are only available if iVersion>=3 */1368513686  /* Create a new tokenizer */13687  int (*xCreateTokenizer_v2)(13688    fts5_api *pApi,13689    const char *zName,13690    void *pUserData,13691    fts5_tokenizer_v2 *pTokenizer,13692    void (*xDestroy)(void*)13693  );1369413695  /* Find an existing tokenizer */13696  int (*xFindTokenizer_v2)(13697    fts5_api *pApi,13698    const char *zName,13699    void **ppUserData,13700    fts5_tokenizer_v2 **ppTokenizer13701  );13702};1370313704/*13705** END OF REGISTRATION API13706*************************************************************************/1370713708#ifdef __cplusplus13709}  /* end of the 'extern "C"' block */13710#endif1371113712#endif /* _FTS5_H */1371313714/******** End of fts5.h *********/13715#endif /* SQLITE3_H */