Lines Matching +full:int +full:- +full:array +full:- +full:variable +full:- +full:length +full:- +full:and +full:- +full:constrained +full:- +full:values
2 ** 2001-09-15
7 ** May you do good and not evil.
8 ** May you find forgiveness for yourself and forgive others.
13 ** presents to client programs. If a C-function, structure, datatype,
16 ** notice, and should not be referenced by programs that use SQLite.
24 ** The official C-language API documentation for SQLite is derived
30 ** the version number) and changes its name to "sqlite3.h" as
46 ** Facilitate override of interface linkage and calling conventions.
48 ** translation of the amalgamation and its associated header file.
50 ** The SQLITE_EXTERN and SQLITE_API macros are used to instruct the
54 ** public functions that accept a variable number of arguments.
59 ** The SQLITE_STDCALL macro is no longer used and is now deprecated.
67 ** Currently, the SQLITE_CDECL, SQLITE_APICALL, SQLITE_CALLBACK, and
69 ** that require non-default calling conventions.
94 ** These no-op macros are used in front of interfaces to mark those
96 ** should not use deprecated interfaces - they are supported for backwards
103 ** that we have taken it all out and gone back to using simple
120 ** CAPI3REF: Compile-Time Library Version Numbers
125 ** SQLite3) and Y is the minor version number and Z is the release number.)^
127 ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
131 ** be held constant and Z will be incremented or else Y will be incremented
132 ** and Z will be reset to zero.
136 ** <a href="http://www.fossil-scm.org/">Fossil configuration management
138 ** a string which identifies a particular check-in of SQLite
140 ** string contains the date and time of the check-in (UTC) and a SHA1
141 ** or SHA3-256 hash of the entire source tree. If the source code has
147 ** [sqlite_version()] and [sqlite_source_id()].
151 #define SQLITE_SOURCE_ID "2024-08-13 09:16:08 c9c2ab54ba1f5f46360f1b4f35d849cd3f080e6fc2b6c60e91b16c63f69a1e33"
154 ** CAPI3REF: Run-Time Library Version Numbers
158 ** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
161 ** verify that values returned by these interfaces match the macros in
162 ** the header, and thus ensure that the application is
163 ** compiled with matching library and header files.
183 ** See also: [sqlite_version()] and [sqlite_source_id()].
188 SQLITE_API int sqlite3_libversion_number(void);
191 ** CAPI3REF: Run-Time Library Compilation Options Diagnostics
200 ** returning the N-th compile time option string. ^If N is out of range,
206 ** and sqlite3_compileoption_get() may be omitted by specifying the
209 ** See also: SQL functions [sqlite_compileoption_used()] and
210 ** [sqlite_compileoption_get()] and the [compile_options pragma].
213 SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
214 SQLITE_API const char *sqlite3_compileoption_get(int N);
223 ** ^The sqlite3_threadsafe() function returns zero if and only if
225 ** [SQLITE_THREADSAFE] compile-time option being set to 0.
229 ** are enabled and SQLite is threadsafe. When the
243 ** This interface only reports on the compile-time mutex setting
249 ** sqlite3_threadsafe() function shows only the compile-time setting of
250 ** thread safety, not any run-time changes to that setting made by
256 SQLITE_API int sqlite3_threadsafe(void);
264 ** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and
265 ** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
266 ** and [sqlite3_close_v2()] are its destructors. There are many other
268 ** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
275 ** CAPI3REF: 64-Bit Integer Types
278 ** Because there is no cross-platform way to specify 64-bit integer types
279 ** SQLite includes typedefs for 64-bit signed and unsigned integers.
281 ** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
282 ** The sqlite_int64 and sqlite_uint64 types are supported for backwards
285 ** ^The sqlite3_int64 and sqlite_int64 types can store integer values
286 ** between -9223372036854775808 and +9223372036854775807 inclusive. ^The
287 ** sqlite3_uint64 and sqlite_uint64 types can store integer values
288 ** between 0 and +18446744073709551615 inclusive.
301 typedef long long int sqlite_int64;
302 typedef unsigned long long int sqlite_uint64;
309 ** substitute integer for floating-point.
319 ** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
321 ** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if
322 ** the [sqlite3] object is successfully destroyed and all associated
326 ** [prepared statements], [sqlite3_blob_close | close] all [BLOB handles], and
330 ** statements, BLOB handlers, and/or unfinished sqlite3_backup objects then
331 ** sqlite3_close() will leave the database connection open and return
333 ** statements, unclosed BLOB handlers, and/or unfinished sqlite3_backups,
336 ** "zombie" and makes arrangements to automatically deallocate the database
338 ** are closed, and all backups have finished. The sqlite3_close_v2() interface
339 ** is intended for use with host languages that are garbage collected, and
345 ** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]
349 ** [sqlite3_open_v2()], and not previously closed.
351 ** argument is a harmless no-op.
353 SQLITE_API int sqlite3_close(sqlite3*);
354 SQLITE_API int sqlite3_close_v2(sqlite3*);
358 ** This is legacy and deprecated. It is included for historical
359 ** compatibility and is not documented.
361 typedef int (*sqlite3_callback)(void*,int,char**, char**);
364 ** CAPI3REF: One-Step Query Execution Interface
368 ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
372 ** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
373 ** semicolon-separate SQL statements passed into its 2nd argument,
380 ** is NULL, then no callback is ever invoked and result rows are
384 ** sqlite3_exec(), then execution of the current statement stops and
387 ** from [sqlite3_malloc()] and passed back through the 5th parameter.
391 ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
395 ** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
396 ** routine returns SQLITE_ABORT without invoking the callback again and
401 ** callback is an array of pointers to strings obtained as if from
405 ** sqlite3_exec() callback is an array of pointers to strings where each
410 ** to an empty string, or a pointer that contains only whitespace and/or
411 ** SQL comments, then no SQL statements are evaluated and the database
418 ** is a valid and open [database connection].
424 ** passed as the 3rd and 4th callback parameters after it returns.
427 SQLITE_API int sqlite3_exec(
430 int (*callback)(void*,int,char**,char**), /* Callback function */
447 /* beginning-of-error-codes */
478 /* end-of-error-codes */
486 ** these result codes are too coarse-grained. They do not provide as
489 ** and later) include
578 ** These bit values are intended for use in the
579 ** 3rd parameter to the [sqlite3_open_v2()] interface and
592 ** [sqlite3_open_v2()] has historically be a no-op and might become an
628 ** bit values expressing I/O characteristics of the mass storage
633 ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
634 ** mean that writes of blocks that are nnn bytes in size and
644 ** and that adjacent bytes, even bytes within the same sector are
648 ** read-only media and cannot be changed even by processes with
653 ** write operations are bracketed by [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] and
675 ** SQLite uses one of these integer values as the second
676 ** argument to calls it makes to the xLock() and xUnlock() methods
677 ** of an [sqlite3_io_methods] object. These values are ordered from
694 ** these integer values as the second argument.
703 ** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
704 ** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
706 ** xSync VFS method occur and applies uniformly across all platforms.
707 ** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
708 ** energetic or rigorous or forceful the sync operations are and
710 ** (Third-party VFS implementations might also make the distinction
711 ** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
745 ** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
755 ** and not its inode needs to be synced.
757 ** The integer values to xLock() and xUnlock() are one of
769 ** requested lock, then the call to xLock() is a no-op.
772 ** to xUnlock() is a no-op.
776 ** if such a lock exists and false otherwise.
783 ** write return values. Potential uses for xFileControl() might be
785 ** locking strategy (for example to use dot-file locks), to inquire
820 ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
821 ** mean that writes of blocks that are nnn bytes in size and
832 ** fails to zero-fill short reads might seem to work. However,
833 ** failure to zero-fill short reads will eventually lead to
838 int iVersion;
839 int (*xClose)(sqlite3_file*);
840 int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
841 int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
842 int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
843 int (*xSync)(sqlite3_file*, int flags);
844 int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
845 int (*xLock)(sqlite3_file*, int);
846 int (*xUnlock)(sqlite3_file*, int);
847 int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
848 int (*xFileControl)(sqlite3_file*, int op, void *pArg);
849 int (*xSectorSize)(sqlite3_file*);
850 int (*xDeviceCharacteristics)(sqlite3_file*);
852 int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
853 int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
855 int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
857 int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
858 int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
868 ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
889 ** The [SQLITE_FCNTL_SIZE_LIMIT] opcode is used by in-memory VFS that
891 ** of the in-memory database. The argument is a pointer to a [sqlite3_int64].
894 ** of the integer pointed to and the current database size. The integer
899 ** extends and truncates the database file in chunks of a size specified
901 ** point to an integer (type int) containing the new chunk-size to use
903 ** chunks (say 1MB at a time), may reduce file-system fragmentation and
914 ** the [rollback journal] or the [write-ahead log]) for a particular database
921 ** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
927 ** this file-control is NULL. However, if the database file is being synced
928 ** as part of a multi-database commit, the argument points to a nul-terminated
929 ** string containing the transactions super-journal file name. VFSes that
936 ** and sent to the VFS after a transaction has been committed immediately
944 ** retry counts and intervals for certain disk I/O operations for the
946 ** anti-virus programs. By default, the windows VFS will retry file read,
947 ** file write, and file delete operations up to 10 times, with a delay
948 ** of 25 milliseconds before the first retry and with the delay increasing
950 ** opcode allows these two values (10 retries and 25 milliseconds of delay)
951 ** to be adjusted. The values are changed for all database connections
952 ** within the same process. The argument is a pointer to an array of two
953 ** integers where the first integer is the new retry count and the second
956 ** into the array entry, allowing the current retry settings to be
962 ** write ahead log ([WAL file]) and shared memory
968 ** to read the database file, as the WAL and shared memory files must exist
972 ** WAL mode. If the integer is -1, then it is overwritten with the current
977 ** persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting
981 ** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
982 ** mode. If the integer is -1, then it is overwritten with the current
983 ** zero-damage mode setting.
993 ** all [VFSes] in the VFS stack. The names are of all VFS shims and the
994 ** final bottom-level VFS are written into memory obtained from
995 ** [sqlite3_malloc()] and the result is stored in the char* variable
998 ** all file-control actions, there is no guarantee that this will actually
999 ** do anything. Callers should initialize the char* variable to a NULL
1000 ** pointer in case this file-control is not implemented. This file-control
1004 ** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
1008 ** to a pointer to the top-level VFS.)^
1010 ** upper-most shim only.
1016 ** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
1017 ** pointers to strings (char**) in which the second element of the array
1018 ** is the name of the pragma and the third element is the argument to the
1022 ** or the equivalent and that string will become the result of the pragma or
1027 ** VFS has handled the PRAGMA itself and the parser generates a no-op
1029 ** of the result string if the string is non-NULL.
1032 ** that the VFS encountered an error while handling the [PRAGMA] and the
1034 ** file control occurs at the beginning of pragma statement analysis and so
1035 ** it is able to override built-in [PRAGMA] statements.
1039 ** file-control may be invoked by SQLite on the database file handle
1041 ** to the connection's busy-handler callback. The argument is of type (void**)
1042 ** - an array of two (void *) values. The first (void *) actually points
1043 ** to a function of type (int (*)(void *)). In order to invoke the connection's
1044 ** busy-handler, this function should be invoked with the second (void *) in
1045 ** the array as the only argument. If it returns non-zero, then the operation
1050 ** ^Applications can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control
1053 ** temporary filenames for TEMP tables and other internal uses. The
1060 ** maximum number of bytes that will be used for memory-mapped I/O.
1064 ** the value originally pointed to is negative, and so the current limit
1066 ** file-control is used internally to implement [PRAGMA mmap_size].
1072 ** The argument is a zero-terminated string. Higher layers in the
1074 ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
1078 ** pointer to an integer and it writes a boolean into that integer depending
1085 ** control interprets its argument as a pointer to a native file handle and
1092 ** and only needs to be supported when SQLITE_TEST is defined.
1099 ** Applications should <em>not</em> use this file-control.
1113 ** means all subsequent write operations will be deferred and done
1116 ** ^Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to
1120 ** except for calls to the xWrite method and the xFileControl method
1127 ** This file control returns [SQLITE_OK] if and only if the writes were
1128 ** all performed successfully and have been committed to persistent storage.
1148 ** The parameter is a pointer to a 32-bit signed integer that contains
1149 ** the value that M is to be set to. Before returning, the 32-bit signed
1154 ** a database file. The argument is a pointer to a 32-bit unsigned integer.
1161 ** but that interface responds to changes on TEMP as well as MAIN and does
1163 ** [sqlite3_total_changes()] interface responds to internal changes only and
1169 ** happen either internally or externally and that are associated with
1180 ** file to the database file, but before the *-shm file is updated to
1185 ** whether or not there is a database client in another process with a wal-mode
1187 ** (void*) argument passed with this file-control should be a pointer to a
1188 ** value of type (int). The integer value is set to 1 if the database is a wal
1189 ** mode database and there exists at least one client in another process that
1191 ** the database is not a wal-mode db, or if there is no such connection in any
1200 ** If there is currently no transaction open on the database, and the
1201 ** database is not a temp db, then the [SQLITE_FCNTL_RESET_CACHE] file-control
1202 ** purges the contents of the in-memory page cache. If there is an open
1203 ** transaction, or if the db is a temp-db, this opcode is a no-op, not an error.
1280 ** xOpen method of a [VFS]. It may be cast to (const char*) and treated
1281 ** as a normal, nul-terminated, UTF-8 buffer containing the filename, but
1300 ** the SQLite core and the underlying operating system. The "vfs"
1308 ** with SQLite [version 3.7.0] on [dateof:3.7.0], and then increased
1310 ** may be appended to the sqlite3_vfs object and the iVersion value
1315 ** and yet the iVersion field was not increased.
1318 ** structure used by this VFS. mxPathname is the maximum length of
1323 ** and [sqlite3_vfs_unregister()] interfaces manage this list
1324 ** in a thread-safe way. The [sqlite3_vfs_find()] interface
1342 ** consist of a single "-" character followed by no more than
1343 ** 11 alphanumeric and/or "-" characters.
1345 ** the string will be valid and unchanged until xClose() is
1358 ** If xOpen() opens a file read-only then it sets *pOutFlags to
1378 ** the open of a journal file a no-op. Writes to this journal would
1379 ** also be no-ops, and any attempt to read the journal would return
1381 ** file will be doing page-aligned sector reads and writes in a random
1382 ** order and set up its I/O subsystem accordingly.
1393 ** will be set for TEMP databases and their journals, transient
1394 ** databases, and subjournals.
1398 ** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
1401 ** be created, and that it is an error if it already exists.
1418 ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
1420 ** flag is never actually used and is not implemented in the built-in
1421 ** VFSes of SQLite. The file is named by the second argument and can be a
1423 ** non-zero error code if there is an I/O error or if the name of
1425 ** is returned, then non-zero or zero is written into *pResOut to indicate
1435 ** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
1439 ** of good-quality randomness into zOut. The return value is
1443 ** method returns a Julian Day Number for the current date and time as
1447 ** a 24-hour day).
1449 ** date and time if that method is available (if iVersion is 2 or
1450 ** greater and the function pointer is not NULL) and will fall back
1453 ** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
1457 ** simulate faults and error conditions that would otherwise be difficult
1459 ** varies from one VFS to another, and from one version of the same VFS to the
1468 int iVersion; /* Structure version number (currently 3) */
1469 int szOsFile; /* Size of subclassed sqlite3_file */
1470 int mxPathname; /* Maximum file pathname length */
1473 void *pAppData; /* Pointer to application-specific data */
1474 int (*xOpen)(sqlite3_vfs*, sqlite3_filename zName, sqlite3_file*,
1475 int flags, int *pOutFlags);
1476 int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
1477 int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
1478 int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
1480 void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
1483 int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
1484 int (*xSleep)(sqlite3_vfs*, int microseconds);
1485 int (*xCurrentTime)(sqlite3_vfs*, double*);
1486 int (*xGetLastError)(sqlite3_vfs*, int, char *);
1491 int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
1493 ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
1494 ** Those below are for version 3 and greater.
1496 int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
1515 ** checks whether the named directory is both readable and writable
1516 ** (in other words, if files can be added, removed, and renamed within
1548 ** The xShmLock method can transition between unlocked and SHARED or
1549 ** between unlocked and EXCLUSIVE. It cannot transition between SHARED
1550 ** and EXCLUSIVE.
1560 ** The xShmLock method on [sqlite3_io_methods] may use values
1561 ** between 0 and this upper bound as its "offset" argument.
1574 ** These routines are designed to aid in process initialization and
1583 ** are harmless no-ops.)^
1588 ** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
1592 ** single thread. All open [database connections] must be closed and all
1611 ** compile-time option, then the automatic calls to sqlite3_initialize()
1612 ** are omitted and the application must call sqlite3_initialize() directly
1620 ** The sqlite3_os_init() routine does operating-system specific
1630 ** sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init()
1631 ** interface is called automatically by sqlite3_initialize() and
1633 ** implementations for sqlite3_os_init() and sqlite3_os_end()
1636 ** (using the [SQLITE_OS_OTHER=1] compile-time
1638 ** sqlite3_os_init() and sqlite3_os_end(). An application-supplied
1640 ** must return [SQLITE_OK] on success and some other [error code] upon
1643 SQLITE_API int sqlite3_initialize(void);
1644 SQLITE_API int sqlite3_shutdown(void);
1645 SQLITE_API int sqlite3_os_init(void);
1646 SQLITE_API int sqlite3_os_end(void);
1654 ** applications and so this routine is usually not necessary. It is
1672 ** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
1676 ** implementation of an application-defined [sqlite3_os_init()].
1680 ** then this routine returns a non-zero [error code].
1682 SQLITE_API int sqlite3_config(int, ...);
1694 ** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code
1698 ** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
1701 SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
1707 ** and low-level memory allocation routines.
1714 ** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
1719 ** Note that SQLite comes with several [built-in memory allocators]
1721 ** and that this object is only useful to a tiny minority of applications
1724 ** memory allocator that simulates memory out-of-memory conditions in
1728 ** The xMalloc, xRealloc, and xFree methods must work like the
1729 ** malloc(), realloc() and free() functions from the standard C library.
1748 ** [sqlite3_shutdown()] and should deallocate any resources acquired
1750 ** xInit and xShutdown.
1758 ** it is by default) and so the methods are automatically serialized.
1768 void *(*xMalloc)(int); /* Memory allocation function */
1770 void *(*xRealloc)(void*,int); /* Resize an allocation */
1771 int (*xSize)(void*); /* Return the size of an allocation */
1772 int (*xRoundup)(int); /* Round up request size to allocation size */
1773 int (*xInit)(void*); /* Initialize the memory allocator */
1775 void *pAppData; /* Argument to xInit() and xShutdown() */
1790 ** anytime configuration option in between calls to [sqlite3_initialize()] and
1791 ** [sqlite3_shutdown()] is a no-op that returns SQLITE_MISUSE.
1794 ** and/or deletions) from one release of SQLite to the next.
1806 ** non-zero [error code] if a discontinued or unsupported configuration option
1812 ** [threading mode] to Single-thread. In other words, it disables
1813 ** all mutexing and puts SQLite into a mode where it can only be used
1815 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1817 ** value of Single-thread and so [sqlite3_config()] will return
1823 ** [threading mode] to Multi-thread. In other words, it disables
1824 ** mutexing on [database connection] and [prepared statement] objects.
1826 ** [database connections] and [prepared statements]. But other mutexes
1827 ** are enabled so that SQLite will be safe to use in a multi-threaded
1830 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1831 ** it is not possible to set the Multi-thread [threading mode] and
1839 ** mutexes on [database connection] and [prepared statement] objects.
1842 ** to [database connections] and [prepared statements] so that the
1846 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1847 ** it is not possible to set the Serialized [threading mode] and
1855 ** alternative low-level memory allocation routines to be used in place of
1871 ** type int, interpreted as a boolean, which if true provides a hint to
1880 ** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
1883 ** disabled, the following SQLite interfaces become non-operational:
1904 ** This configuration option is a no-op if an application-defined page
1907 ** 8-byte aligned memory (pMem), the size of each page cache line (sz),
1908 ** and the number of cache lines (N).
1910 ** (a power of two between 512 and 65536) plus some extra bytes for each
1915 ** argument must be either a NULL pointer or a pointer to an 8-byte
1922 ** ^If pMem is NULL and N is non-zero, then each database connection
1925 ** of -1024*N bytes if N is negative, . ^If additional
1935 ** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
1938 ** An 8-byte aligned pointer to the memory,
1939 ** the number of bytes in the memory buffer, and the minimum allocation size.
1945 ** The first pointer (the memory pointer) must be aligned to an 8-byte
1947 ** The minimum allocation size is capped at 2**12. Reasonable values
1953 ** The argument specifies alternative low-level mutex routines to be used
1957 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1958 ** the entire mutexing subsystem is omitted from the build and hence calls to
1970 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1971 ** the entire mutexing subsystem is omitted from the build and hence calls to
1979 ** size of each lookaside buffer slot and the second is the number of
2000 ** function with a call signature of void(*)(void*,int,const char*),
2001 ** and a pointer to void. ^If the function pointer is not NULL, it is
2003 ** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
2005 ** passed through as the first parameter to the application-defined logger
2008 ** [sqlite3_log()] call and is intended to be a [result code] or an
2013 ** In a multi-threaded application, the application-defined logger
2017 ** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.
2018 ** If non-zero, then URI handling is globally enabled. If the parameter is zero,
2035 ** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
2036 ** if that compile-time option is omitted.
2044 ** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
2045 ** <dd> These options are obsolete and should not be used by new code.
2046 ** They are retained for backwards compatibility but are now no-ops.
2052 ** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should
2053 ** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
2068 ** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
2070 ** [PRAGMA mmap_size]) and the maximum allowed mmap size limit.
2075 ** compile-time maximum mmap size set by the
2076 ** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
2078 ** changed to its compile-time default.
2083 ** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro
2084 ** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
2090 ** is a pointer to an integer and writes into that integer the number of extra
2093 ** target platform, and SQLite version.
2098 ** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
2100 ** [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched
2102 ** is enabled (using the [PRAGMA threads] command) and the amount of content
2104 ** [PRAGMA cache_size] setting and this value.
2109 ** becomes the [statement journal] spill-to-disk threshold.
2112 ** Or if the threshold is -1, statement journals are always held
2118 ** [SQLITE_STMTJRNL_SPILL] compile-time option.
2123 ** of type (int) - the new value of the sorter-reference size threshold.
2127 ** of a table column that its values are likely to be very large - larger
2128 ** than the configured sorter-reference size threshold - then a reference
2129 ** is stored in each sorted record and the required column values loaded
2134 ** [SQLITE_ENABLE_SORTER_REFERENCES] compile-time option.
2139 ** [sqlite3_int64] parameter which is the default maximum size for an in-memory
2142 ** [SQLITE_FCNTL_SIZE_LIMIT] [sqlite3_file_control|file-control]. If this
2144 ** by the [SQLITE_MEMDB_DEFAULT_MAXSIZE] compile-time option. If that
2145 ** compile-time option is not set, then the default maximum is 1073741824.
2151 ** compiled with -DSQLITE_ALLOW_ROWID_IN_VIEW, in which case the capability
2159 ** is compiled without -DSQLITE_ALLOW_ROWID_IN_VIEW (which is the usual and
2170 #define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
2171 #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
2176 #define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
2177 #define SQLITE_CONFIG_PCACHE 14 /* no-op */
2178 #define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
2180 #define SQLITE_CONFIG_URI 17 /* int */
2183 #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */
2186 #define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */
2187 #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */
2188 #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */
2189 #define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */
2191 #define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */
2193 #define SQLITE_CONFIG_ROWID_IN_VIEW 30 /* int* */
2205 ** non-zero [error code] if a discontinued or unsupported configuration option
2220 ** or equal to the product of the second and third arguments. The buffer
2221 ** must be aligned to an 8-byte boundary. ^If the second argument to
2229 ** memory is in use leaves the configuration unchanged and returns
2257 ** triggers in the main database schema or in the schemas of ATTACH-ed
2274 ** views in the main database schema or in the schemas of ATTACH-ed
2281 ** [FTS3] full-text search engine extension.
2296 ** C-API [sqlite3_load_extension()] and the SQL function [load_extension()].
2298 ** When the first argument to this interface is 1, then only the C-API is
2299 ** enabled and the SQL function remains disabled. If the first argument to
2300 ** this interface is 0, then both the C-API and the SQL function are disabled.
2301 ** If the first argument is -1, then no changes are made to state of either the
2302 ** C-API or the SQL function.
2325 ** is an integer - positive to disable checkpoints-on-close, or zero (the
2326 ** default) to enable them, and negative to leave the setting unchanged.
2328 ** into which is written 0 or 1 to indicate whether checkpoints-on-close
2329 ** have been disabled - 0 if they are not disabled, 1 if they are.
2336 ** of values of [bound parameters].)^ The QPSG disables some query optimizations
2337 ** that look at the values of bound parameters, which can make some queries
2352 ** behavior. The first parameter passed to this operation is an integer -
2356 ** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if
2361 ** <dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run
2363 ** with no schema and no content. The following process works even for
2376 ** Because resetting a database is destructive and irreversible, the
2377 ** process requires the use of this obscure API and multiple steps to
2379 ** feature must be capable of resetting corrupt databases, and
2401 ** "writable_schema" flag. This has the same effect and is logically equivalent
2414 ** behaves as it did prior to [version 3.24.0] (2018-06-04). See the
2416 ** additional information. This feature can also be turned on and off
2423 ** the legacy [double-quoted string literal] misfeature for DML statements
2424 ** only, that is DELETE, INSERT, SELECT, and UPDATE statements. The
2425 ** default value of this setting is determined by the [-DSQLITE_DQS]
2426 ** compile-time option.
2432 ** the legacy [double-quoted string literal] misfeature for DDL statements,
2433 ** such as CREATE TABLE and CREATE INDEX. The
2434 ** default value of this setting is determined by the [-DSQLITE_DQS]
2435 ** compile-time option.
2462 ** created database file to have a schema format version number (the 4-byte
2464 ** means that the resulting database file will be readable and writable by
2469 ** all the way back to version 3.0.0, and so this setting is of little
2475 ** process a table with generated columns and a descending index. This is
2476 ** not considered a bug since SQLite versions 3.3.0 and earlier do not support
2486 ** the database handle both when the SQL statement is prepared and when it
2488 ** by default. This option takes two arguments: an integer and a pointer to
2489 ** an integer.. The first argument is 1, 0, or -1 to enable, disable, or
2499 ** in which tables and indexes are scanned so that the scans start at the end
2500 ** and work toward the beginning rather than starting at the beginning and
2503 ** two arguments which are an integer and a pointer to an integer. The first
2504 ** argument is 1, 0, or -1 to enable, disable, or leave unchanged the
2514 #define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */
2515 #define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */
2516 #define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */
2517 #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */
2518 #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */
2519 #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */
2520 #define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */
2521 #define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */
2522 #define SQLITE_DBCONFIG_RESET_DATABASE 1009 /* int int* */
2523 #define SQLITE_DBCONFIG_DEFENSIVE 1010 /* int int* */
2524 #define SQLITE_DBCONFIG_WRITABLE_SCHEMA 1011 /* int int* */
2525 #define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE 1012 /* int int* */
2526 #define SQLITE_DBCONFIG_DQS_DML 1013 /* int int* */
2527 #define SQLITE_DBCONFIG_DQS_DDL 1014 /* int int* */
2528 #define SQLITE_DBCONFIG_ENABLE_VIEW 1015 /* int int* */
2529 #define SQLITE_DBCONFIG_LEGACY_FILE_FORMAT 1016 /* int int* */
2530 #define SQLITE_DBCONFIG_TRUSTED_SCHEMA 1017 /* int int* */
2531 #define SQLITE_DBCONFIG_STMT_SCANSTATUS 1018 /* int int* */
2532 #define SQLITE_DBCONFIG_REVERSE_SCANORDER 1019 /* int int* */
2543 SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
2550 ** has a unique 64-bit signed
2583 ** successful [INSERT] and does not change the value returned by this
2585 ** and INSERT OR ABORT make no changes to the return value of this
2600 ** function is running and thus changes the last insert [rowid],
2602 ** unpredictable and might not equal either the old or the new
2625 ** and that if the number of rows modified by the most recent INSERT, UPDATE
2626 ** or DELETE is greater than the maximum value supported by type "int", then
2631 ** considered - auxiliary changes caused by [CREATE TRIGGER | triggers],
2650 ** <li> ^(Within a trigger program each INSERT, UPDATE and DELETE
2653 ** any changes performed by sub-triggers, as the sqlite3_changes()
2654 ** value will be saved and restored after each sub-trigger has run.)^
2666 ** is unpredictable and not meaningful.
2676 SQLITE_API int sqlite3_changes(sqlite3*);
2687 ** type of the return value and that if the number of rows modified by the
2688 ** connection exceeds the maximum value supported by type "int", then
2707 ** returned is unpredictable and not meaningful.
2718 SQLITE_API int sqlite3_total_changes(sqlite3*);
2722 ** CAPI3REF: Interrupt A Long-Running Query
2725 ** ^This function causes any pending database operation to abort and
2728 ** or Ctrl-C where the user wants a long query operation to halt
2738 ** to be interrupted and might continue to completion.
2747 ** that are started after the sqlite3_interrupt() call and before the
2753 ** SQL statements is a no-op and has no effect on SQL statements
2761 SQLITE_API int sqlite3_is_interrupted(sqlite3*);
2766 ** These routines are useful during command-line input to determine if the
2771 ** complete if it ends with a semicolon token and is not a prefix of a
2772 ** well-formed CREATE TRIGGER statement. ^Semicolons that are embedded within
2775 ** embedded) and thus do not count as a statement terminator. ^Whitespace
2776 ** and comments that follow the final semicolon are ignored.
2787 ** then the return value from sqlite3_complete16() will be non-zero
2790 ** The input to [sqlite3_complete()] must be a zero-terminated
2791 ** UTF-8 string.
2793 ** The input to [sqlite3_complete16()] must be a zero-terminated
2794 ** UTF-16 string in native byte order.
2796 SQLITE_API int sqlite3_complete(const char *sql);
2797 SQLITE_API int sqlite3_complete16(const void *sql);
2801 ** KEYWORDS: {busy-handler callback} {busy handler}
2810 ** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout].
2821 ** access the database and [SQLITE_BUSY] is returned
2823 ** ^If the callback returns non-zero, then another attempt
2824 ** is made to access the database and the cycle repeats.
2828 ** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
2832 ** it is trying to promote to a reserved lock and
2835 ** because it is blocked by the second and the second process cannot
2839 ** will induce the first process to release its read lock and allow
2848 ** busy handler and thus clear any previously set busy handler.
2858 SQLITE_API int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*);
2881 SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
2894 ** The table conceptually has a number of rows and columns. But
2897 ** and M be the number of columns.
2899 ** A result table is an array of pointers to zero-terminated UTF-8 strings.
2900 ** There are (N+1)*M elements in the array. The first M pointers point
2901 ** to zero-terminated strings that contain the names of the columns.
2902 ** The remaining entries all point to query results. NULL values result
2903 ** in NULL pointers. All other values are in their UTF-8 zero-terminated
2915 ** -----------------------
2921 ** There are two columns (M==2) and three rows (N==3). Thus the
2923 ** in an array named azResult. Then azResult holds this content:
2937 ** semicolon-separated SQL statements in the zero-terminated UTF-8
2938 ** string of its 2nd parameter and returns a result table to the
2946 ** [sqlite3_free_table()] is able to release the memory properly and safely.
2956 SQLITE_API int sqlite3_get_table(
2960 int *pnRow, /* Number of result rows written here */
2961 int *pnColumn, /* Number of result columns written here */
2969 ** These routines are work-alikes of the "printf()" family of functions
2973 ** plus some additional non-standard formats ([%q], [%Q], [%w], and [%z]).
2974 ** See the [built-in printf()] documentation for details.
2976 ** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
2997 ** guarantees that the buffer is always zero-terminated. ^The first
3000 ** written will be n-1 characters.
3004 ** See also: [built-in printf()], [printf() SQL function]
3008 SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
3009 SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
3016 ** does not include operating-system specific [VFS] implementation. The
3017 ** Windows VFS uses native malloc() and free() for some operations.
3020 ** of memory at least N bytes in length, where N is the parameter.
3027 ** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
3028 ** of a signed 32-bit integer.
3033 ** a no-op if is called with a NULL pointer. Passing a NULL pointer
3038 ** might result if sqlite3_free() is called with a non-NULL pointer that
3053 ** by sqlite3_realloc(X,N) and the prior allocation is freed.
3054 ** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the
3058 ** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
3059 ** of a 32-bit signed integer.
3069 ** of sqlite3_msize(X) is undefined and possibly harmful.
3072 ** sqlite3_malloc64(), and sqlite3_realloc64()
3074 ** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
3077 ** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
3086 SQLITE_API void *sqlite3_malloc(int);
3088 SQLITE_API void *sqlite3_realloc(void*, int);
3097 ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
3098 ** routines, which form the built-in memory allocation subsystem.
3103 ** value of [sqlite3_memory_used()] since the high-water mark
3104 ** was last reset. ^The values returned by [sqlite3_memory_used()] and
3110 ** ^The memory high-water mark is reset to the current value of
3111 ** [sqlite3_memory_used()] if and only if the parameter to
3113 ** by [sqlite3_memory_highwater(1)] is the high-water mark
3117 SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
3120 ** CAPI3REF: Pseudo-Random Number Generator
3122 ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
3125 ** the built-in random() and randomblob() SQL functions. This interface allows
3135 ** ^If the previous call to this routine had an N of 1 or more and a
3136 ** non-NULL P then the pseudo-randomness is generated
3137 ** internally and without recourse to the [sqlite3_vfs] xRandomness
3140 SQLITE_API void sqlite3_randomness(int N, void *P);
3143 ** CAPI3REF: Compile-Time Authorization Callbacks
3152 ** and [sqlite3_prepare16_v3()]. ^At various
3174 ** to the callback are either NULL pointers or zero-terminated strings
3180 ** and the callback returns [SQLITE_IGNORE] then the
3186 ** ^When a table is referenced by a [SELECT] but no column values are
3190 ** ^If the action code is [SQLITE_DELETE] and the callback returns
3192 ** [truncate optimization] is disabled and all rows are deleted individually.
3202 ** user-entered SQL is being [sqlite3_prepare | prepared] that
3207 ** and limiting database size using the [max_page_count] [PRAGMA]
3217 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
3221 ** statement might be re-prepared during [sqlite3_step()] due to a
3231 SQLITE_API int sqlite3_set_authorizer(
3233 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
3261 ** These action code values signify what kind of operation is to be
3262 ** authorized. The 3rd and 4th parameters to the authorization
3267 ** is the name of the inner-most trigger or view that is responsible for
3269 ** top-level SQL code.
3308 ** CAPI3REF: Deprecated Tracing And Profiling Functions
3315 ** tracing and profiling the execution of SQL statements.
3319 ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
3323 ** contain a UTF-8 SQL comment that identifies the trigger.)^
3325 ** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
3326 ** the length of [bound parameter] expansion in the output of sqlite3_trace().
3330 ** the original statement text and an estimate of wall-clock time
3350 ** to [sqlite3_trace_v2(D,M,X,P)] is an OR-ed combination of one or more of
3360 ** The P and X arguments are pointers whose meanings depend on T.
3365 ** first begins running and possibly at other times during the
3372 ** interface by using the X argument when X begins with "--" and invoking
3378 ** ^The P argument is a pointer to the [prepared statement] and the
3379 ** X argument points to a 64-bit integer which is approximately
3386 ** ^The P argument is a pointer to the [prepared statement] and the
3393 ** and the X argument is unused.
3407 ** and context pointer P. ^If the X callback is
3409 ** M argument should be the bitwise OR-ed combination of
3426 ** The P and X arguments are pointers whose meanings depend on T.
3429 ** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which
3432 SQLITE_API int sqlite3_trace_v2(
3435 int(*xCallback)(unsigned,void*,void*,void*),
3445 ** [sqlite3_step()] and [sqlite3_prepare()] and similar for
3461 ** ^If the progress callback returns non-zero, the operation is
3467 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
3472 ** and similar because those routines might force a reparse of the schema
3475 ** invoked directly from [sqlite3_prepare()] while analyzing and generating
3478 SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
3485 ** filename argument. ^The filename argument is interpreted as UTF-8 for
3486 ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
3491 ** object.)^ ^(If the database is opened (and/or created) successfully, then
3497 ** ^The default encoding will be UTF-8 for databases created using
3499 ** created using sqlite3_open16() will be UTF-16 in the native byte order.
3513 ** <dd>The database is opened in read-only mode. If the database does
3517 ** <dd>The database is opened for reading and writing if possible, or
3521 ** read-write mode fails due to OS-level permissions, an attempt is
3522 ** made to open it in read-only mode. [sqlite3_db_readonly()] can be
3524 ** read-write.</dd>)^
3527 ** <dd>The database is opened for reading and writing, and is created if
3529 ** sqlite3_open() and sqlite3_open16().</dd>)^
3540 ** <dd>The database will be opened as an in-memory database. The database
3541 ** is named by the "filename" argument for the purposes of cache-sharing,
3546 ** <dd>The new database connection will use the "multi-thread"
3562 ** The [use of shared cache mode is discouraged] and hence shared cache
3564 ** this option is a no-op.
3589 ** into future versions of SQLite and so applications should not rely
3590 ** upon it. Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op
3593 ** flag is intended for use by the [sqlite3_vfs|VFS interface] only, and not
3601 ** ^If the filename is ":memory:", then a private, temporary in-memory database
3602 ** is created for the connection. ^This in-memory database will vanish when
3610 ** on-disk database will be created. ^This private database will be
3615 ** ^If [URI filename] interpretation is enabled, and the filename argument
3620 ** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
3643 ** SQLite and its built-in [VFSes] interpret the
3651 ** VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
3658 ** ^If "ro" is specified, then the database is opened for read-only
3661 ** "rw", then the database is opened for read-write (but not create)
3664 ** SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If the mode option is
3665 ** set to "memory" then a pure [in-memory database] that never reads
3675 ** ^If sqlite3_open_v2() is used and the "cache" parameter is present in
3687 ** or more processes write to the same database and any one of those
3692 ** read-only media. ^When immutable is set, SQLite assumes that the
3694 ** privilege, and so the database is opened read-only and all locking
3695 ** and change detection is disabled. Caution: Setting the immutable
3697 ** in incorrect query results and/or [SQLITE_CORRUPT] errors.
3719 ** <tr><td style="white-space:nowrap">
3720 ** file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
3723 ** necessary - space characters can be used literally
3726 ** Open file "data.db" in the current directory for read-only access.
3727 ** Regardless of whether or not shared-cache mode is enabled by
3729 ** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
3730 ** Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
3731 ** that uses dot-files in place of posix advisory locking.
3737 ** ^URI hexadecimal escape sequences (%HH) are supported within the path and
3739 ** percent sign - "%" - followed by exactly two hexadecimal digits
3741 ** URI filename are interpreted, they are encoded using UTF-8 and all
3743 ** corresponding octet. If this process generates an invalid UTF-8 encoding,
3747 ** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
3749 ** characters must be converted to UTF-8 prior to passing them into
3758 SQLITE_API int sqlite3_open(
3759 const char *filename, /* Database filename (UTF-8) */
3762 SQLITE_API int sqlite3_open16(
3763 const void *filename, /* Database filename (UTF-16) */
3766 SQLITE_API int sqlite3_open_v2(
3767 const char *filename, /* Database filename (UTF-8) */
3769 int flags, /* Flags */
3774 ** CAPI3REF: Obtain Values For URI Parameters
3778 ** parameter, and if so obtains the value of that query parameter.
3783 ** <li> A database filename pointer created by the SQLite core and
3789 ** undefined and probably undesirable. Older versions of SQLite were
3793 ** and if P is the name of the query parameter, then
3796 ** query parameter on F. If P is a query parameter of F and it
3801 ** parameter and returns true (1) or false (0) according to the value
3804 ** case or if the value begins with a non-zero number. The
3812 ** 64-bit signed integer and returns that integer, or D if P does not
3817 ** the value) of the N-th query parameter for filename F, or a NULL
3819 ** parameters minus 1. The N value is zero-based so N should be 0 to obtain
3820 ** the name of the first query parameter, 1 for the second parameter, and
3823 ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
3824 ** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and
3827 ** and probably undesirable.
3840 SQLITE_API int sqlite3_uri_boolean(sqlite3_filename z, const char *zParam, int bDefault);
3842 SQLITE_API const char *sqlite3_uri_key(sqlite3_filename z, int N);
3849 ** and the WAL file.
3867 ** filename passed into the VFS from the SQLite core and F is not the
3869 ** undefined and is likely a memory access violation.
3878 ** ^If X is the name of a rollback or WAL-mode journal file that is
3884 ** only. It is not a general-purpose interface.
3889 ** of this routine results in undefined and probably undesirable
3895 ** CAPI3REF: Create and Destroy VFS Filenames
3897 ** These interfaces are provided for use by [VFS shim] implementations and
3901 ** database filename D with corresponding journal file J and WAL file W and
3902 ** with N URI parameters key/values pairs in the array P. The result from
3918 ** The P parameter in sqlite3_create_filename(D,J,W,N,P) should be an array
3919 ** of 2*N pointers to strings. Each pair of pointers in this array corresponds
3920 ** to a key and value for a query parameter. The P parameter may be a NULL
3921 ** pointer if N is zero. None of the 2*N pointers in the P array may be
3922 ** NULL pointers and key pointers should not be empty strings.
3928 ** sqlite3_free_filename(Y) where Y is a NULL pointer is a harmless no-op.
3943 int nParam,
3949 ** CAPI3REF: Error Codes And Messages
3961 ** The values returned by sqlite3_errcode() and/or
3964 ** change the value of the error code. The error-code preserving
3975 ** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
3976 ** text that describes the error, as either UTF-8 or UTF-16 respectively,
3984 ** ^The sqlite3_errstr(E) interface returns the English-language text
3985 ** that describes the [result code] E, as UTF-8, or NULL if E is not an
3988 ** and must not be freed by the application)^.
3995 ** SQL, then the sqlite3_error_offset() function returns -1.
3999 ** the time of the first error and the call to these interfaces.
4004 ** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
4009 ** error code and message may or may not be set.
4011 SQLITE_API int sqlite3_errcode(sqlite3 *db);
4012 SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
4015 SQLITE_API const char *sqlite3_errstr(int);
4016 SQLITE_API int sqlite3_error_offset(sqlite3 *db);
4023 ** has been compiled into binary form and is ready to be evaluated.
4030 ** The life-cycle of a prepared statement object usually goes like this:
4034 ** <li> Bind values to [parameters] using the sqlite3_bind_*()
4045 ** CAPI3REF: Run-time Limits
4058 ** set at compile-time by a C preprocessor macro called
4067 ** simply invoke this interface with the third parameter set to -1.
4069 ** Run-time limits are intended for use in applications that manage
4070 ** both their own internal database and also databases that are controlled
4072 ** web browser that has its own databases for storing history and
4082 ** New run-time limit categories may be added in future releases.
4084 SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
4087 ** CAPI3REF: Run-Time Limit Categories
4091 ** that can be lowered at run-time using [sqlite3_limit()].
4100 ** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
4127 ** <dd>The maximum length of the pattern argument to the [LIKE] or
4159 ** "prepFlags" parameter of the [sqlite3_prepare_v3()] and
4167 ** that the prepared statement will be retained for a long time and
4169 ** and [sqlite3_prepare16_v3()] assume that the prepared statement will
4170 ** be used just once or at most a few times and then destroyed using
4177 ** <dd>The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used
4200 ** To execute an SQL statement, it must first be compiled into a byte-code
4205 ** [sqlite3_prepare()] interface is legacy and should be avoided.
4209 ** The use of the UTF-8 interfaces is preferred, as SQLite currently
4210 ** does all parsing using UTF-8. The UTF-16 interfaces are provided
4211 ** as a convenience. The UTF-16 interfaces work by converting the
4212 ** input text into UTF-8, then invoking the corresponding UTF-8 interface.
4219 ** as either UTF-8 or UTF-16. The sqlite3_prepare(), sqlite3_prepare_v2(),
4220 ** and sqlite3_prepare_v3()
4221 ** interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),
4222 ** and sqlite3_prepare16_v3() use UTF-16.
4228 ** If the caller knows that the supplied string is nul-terminated, then
4231 ** the nul-terminator.
4250 ** and sqlite3_prepare16_v3() interfaces are recommended for all new programs.
4251 ** The older interfaces (sqlite3_prepare() and sqlite3_prepare16())
4262 ** statement and try to run it again. As many as [SQLITE_MAX_SCHEMA_RETRY]
4263 ** retries will occur before sqlite3_step() gives up and returns an error.
4270 ** and the application would have to make a second call to [sqlite3_reset()]
4281 ** ^The specific value of a WHERE-clause [parameter] might influence the
4282 ** choice of query plan if the parameter is the left-hand side of a [LIKE]
4284 ** and the [SQLITE_ENABLE_STAT4] compile-time option is enabled.
4289 ** the extra prepFlags parameter, which is a bit array consisting of zero or
4294 SQLITE_API int sqlite3_prepare(
4296 const char *zSql, /* SQL statement, UTF-8 encoded */
4297 int nByte, /* Maximum length of zSql in bytes. */
4301 SQLITE_API int sqlite3_prepare_v2(
4303 const char *zSql, /* SQL statement, UTF-8 encoded */
4304 int nByte, /* Maximum length of zSql in bytes. */
4308 SQLITE_API int sqlite3_prepare_v3(
4310 const char *zSql, /* SQL statement, UTF-8 encoded */
4311 int nByte, /* Maximum length of zSql in bytes. */
4312 unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
4316 SQLITE_API int sqlite3_prepare16(
4318 const void *zSql, /* SQL statement, UTF-16 encoded */
4319 int nByte, /* Maximum length of zSql in bytes. */
4323 SQLITE_API int sqlite3_prepare16_v2(
4325 const void *zSql, /* SQL statement, UTF-16 encoded */
4326 int nByte, /* Maximum length of zSql in bytes. */
4330 SQLITE_API int sqlite3_prepare16_v3(
4332 const void *zSql, /* SQL statement, UTF-16 encoded */
4333 int nByte, /* Maximum length of zSql in bytes. */
4334 unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
4343 ** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
4347 ** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
4350 ** ^The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8
4352 ** semantics used to normalize a SQL statement are unspecified and subject
4353 ** to change. At a minimum, literal values will be replaced with suitable
4357 ** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
4358 ** and parameter :xyz is unbound, then sqlite3_sql() will return
4364 ** the maximum string length determined by the [SQLITE_LIMIT_LENGTH].
4366 ** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of
4367 ** bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time
4370 ** ^The strings returned by sqlite3_sql(P) and sqlite3_normalized_sql(P)
4371 ** are managed by SQLite and are automatically freed when the prepared
4374 ** is obtained from [sqlite3_malloc()] and must be freed by the application
4378 ** the [SQLITE_ENABLE_NORMALIZE] compile-time option is defined.
4390 ** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
4391 ** and only if the [prepared statement] X makes no direct changes to
4394 ** Note that [application-defined SQL functions] or
4398 ** change the database file through side-effects:
4408 ** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
4411 ** database. ^The [ATTACH] and [DETACH] statements also cause
4416 ** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and
4417 ** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so
4424 ** makes it a no-op, but the sqlite3_stmt_readonly() result would still
4426 ** read-only no-op if the table already exists, but
4433 SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
4445 SQLITE_API int sqlite3_stmt_isexplain(sqlite3_stmt *pStmt);
4464 ** the newer [sqlite3_prepare_v2()] or [sqlite3_prepare_v3()] interfaces and
4480 SQLITE_API int sqlite3_stmt_explain(sqlite3_stmt *pStmt, int eMode);
4486 ** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
4492 ** NULL pointer and is not a pointer to a valid [prepared statement]
4493 ** object, then the behavior is undefined and probably undesirable.
4501 SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
4507 ** SQLite uses the sqlite3_value object to represent all values
4509 ** for the values it stores. ^Values stored in sqlite3_value objects
4510 ** can be integers, floating point values, strings, BLOBs, or NULL.
4520 ** The terms "protected" and "unprotected" refer to whether or not
4523 ** sqlite3_value object. If SQLite is compiled to be single-threaded
4524 ** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
4527 ** then there is no distinction between protected and unprotected
4528 ** sqlite3_value objects and they can be used interchangeably. However,
4530 ** still make the distinction between protected and unprotected
4534 ** implementation of [application-defined SQL functions] are protected.
4540 ** to [sqlite3_result_value()], [sqlite3_bind_value()], and
4552 ** is always first parameter to [application-defined SQL functions].
4553 ** The application-defined SQL function implementation will pass this
4557 ** and/or [sqlite3_set_auxdata()].
4562 ** CAPI3REF: Binding Values To Prepared Statements
4567 ** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
4580 ** and VVV represents an alphanumeric identifier.)^ ^The values of these
4590 ** SQL parameter is used more than once, second and subsequent
4595 ** ^The NNN value must be between 1 and the [sqlite3_limit()]
4601 ** is ignored and the end result is the same as sqlite3_bind_null().
4603 ** it should be a pointer to well-formed UTF8 text.
4605 ** it should be a pointer to well-formed UTF16 text.
4607 ** it should be a pointer to a well-formed unicode string that is
4611 ** [[byte-order determination rules]] ^The byte-order of
4612 ** UTF16 input text is determined by the byte-order mark (BOM, U+FEFF)
4625 ** is negative, then the length of the string is
4629 ** If a non-negative fourth parameter is provided to sqlite3_bind_text()
4638 ** ^The fifth argument to the BLOB and string binding interfaces controls
4647 ** case, the object and the provided pointer to it must remain valid until
4652 ** object and pointer to it must remain valid until then. ^SQLite will then
4659 ** allowed values shown above, or if the text encoding is different
4663 ** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
4669 ** ^A negative value for the zeroblob results in a zero-length BLOB.
4671 ** ^The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in
4685 ** result is undefined and probably harmful.
4699 ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
4701 SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
4702 SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
4704 SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
4705 SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
4706 SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
4707 SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
4708 SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
4709 SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
4710 SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
4712 SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
4713 SQLITE_API int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*));
4714 SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
4715 SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
4724 ** placeholders for values that are [sqlite3_bind_blob | bound]
4733 ** [sqlite3_bind_parameter_name()], and
4736 SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
4743 ** the name of the N-th [SQL parameter] in the [prepared statement] P.
4750 ** and are referred to as "nameless" or "anonymous parameters".
4754 ** ^If the value N is out of range or if the N-th parameter is
4756 ** always in UTF-8 encoding even if the named parameter was
4757 ** originally specified as UTF-16 in [sqlite3_prepare16()],
4761 ** [sqlite3_bind_parameter_count()], and
4764 SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
4774 ** name must be given in UTF-8 even if the original statement
4775 ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()] or
4779 ** [sqlite3_bind_parameter_count()], and
4782 SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
4792 SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
4804 ** WHERE clause constraints and the table content, it might return no rows.
4808 SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
4816 ** interface returns a pointer to a zero-terminated UTF-8 string
4817 ** and sqlite3_column_name16() returns a pointer to a zero-terminated
4818 ** UTF-16 string. ^The first parameter is the [prepared statement]
4829 ** (for example during a conversion from UTF-8 to UTF-16) then a
4834 ** then the name of the column is unspecified and may change from
4837 SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
4838 SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
4844 ** ^These routines provide a means to determine the database, table, and
4848 ** either a UTF-8 or UTF-16 string. ^The _database_ routines return
4849 ** the database name, the _table_ routines return the table name, and
4857 ** ^The names returned are the original un-aliased names of the
4858 ** database, table, and column.
4863 ** ^The left-most column is column 0 for these routines.
4866 ** subquery and is not a column value, then all of these functions return
4872 ** UTF-16 encoded strings and the other functions return UTF-8.
4875 ** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
4879 ** for the same [prepared statement] and result column
4882 SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);
4883 SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
4884 SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);
4885 SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
4886 SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
4887 SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
4894 ** If this statement is a [SELECT] statement and the Nth column of the
4899 ** ^The returned string is always UTF-8 encoded.
4905 ** and the following statement to be compiled:
4910 ** column (i==1), and a NULL pointer for the first result column (i==0).)^
4912 ** ^SQLite uses dynamic run-time typing. ^So just because a column
4916 ** is associated with individual values, not with the containers
4917 ** used to hold those values.
4919 SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
4920 SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
4936 ** interfaces [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the
4948 ** statement. If the statement is not a [COMMIT] and occurs within an
4959 ** caller. The values may be accessed using the [column access functions].
4962 ** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
4966 ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
4978 ** For all versions of SQLite up to and including 3.6.23.1, a call to
4988 ** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option
4993 ** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call
5000 ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
5004 SQLITE_API int sqlite3_step(sqlite3_stmt*);
5018 ** will return non-zero if previous call to [sqlite3_step](P) returned
5020 ** where it always returns zero since each step of that multi-step
5025 SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
5034 ** <li> 64-bit signed integer
5035 ** <li> 64-bit IEEE floating point number
5045 ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
5060 ** CAPI3REF: Result Values From A Query
5068 ** <tr><td><b>sqlite3_column_int</b><td>→<td>32-bit INTEGER result
5069 ** <tr><td><b>sqlite3_column_int64</b><td>→<td>64-bit INTEGER result
5070 ** <tr><td><b>sqlite3_column_text</b><td>→<td>UTF-8 TEXT result
5071 ** <tr><td><b>sqlite3_column_text16</b><td>→<td>UTF-16 TEXT result
5076 ** or a UTF-8 TEXT result in bytes
5078 ** <td>→ <td>Size of UTF-16
5090 ** and the second argument is the index of the column for which information
5098 ** [sqlite3_step()] has returned [SQLITE_ROW] and neither
5107 ** The first six interfaces (_blob, _double, _int, _int64, _text, and _text16)
5130 ** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
5132 ** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
5133 ** the string to UTF-8 and then returns the number of bytes.
5135 ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
5139 ** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
5141 ** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
5142 ** the string to UTF-16 and then returns the number of bytes.
5144 ** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
5148 ** ^The values returned by [sqlite3_column_bytes()] and
5150 ** of the string. ^For clarity: the values returned by
5151 ** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of
5154 ** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
5155 ** even empty strings, are always zero-terminated. ^The return
5156 ** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
5165 ** [sqlite3_bind_value()] and [sqlite3_result_value()].
5172 ** [application-defined SQL functions] or [virtual tables], not within
5173 ** top-level application code.
5176 ** ^For example, if the internal representation is FLOAT and a text result
5191 ** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT
5205 ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
5207 ** Type conversions and pointer invalidations might occur
5211 ** <li> The initial content is a BLOB and sqlite3_column_text() or
5212 ** sqlite3_column_text16() is called. A zero-terminator might
5214 ** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
5216 ** to UTF-16.</li>
5217 ** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
5219 ** to UTF-8.</li>
5222 ** ^Conversions between UTF-16be and UTF-16le are always done in place and do
5226 ** are not possible and in those cases prior pointers are invalidated.
5242 ** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
5248 ** and BLOBs is freed automatically. Do not pass the pointers returned
5253 ** fail if an out-of-memory error occurs during a format conversion.
5254 ** Only the following subset of interfaces are subject to out-of-memory
5265 ** If an out-of-memory error occurs, then the return value from these
5267 ** Valid SQL NULL returns can be distinguished from out-of-memory errors
5269 ** return value is obtained and before any
5272 SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
5273 SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
5274 SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
5275 SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
5276 SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
5277 SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
5278 SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
5279 SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
5280 SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
5281 SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
5301 ** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
5306 ** statement after it has been finalized can result in undefined and
5307 ** undesirable behavior such as segfaults and heap corruption.
5309 SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
5316 ** object back to its initial state, ready to be re-executed.
5317 ** ^Any SQL statement variables that had values bound to them using
5318 ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
5339 ** the overall statement might still fail and the [sqlite3_reset(S)] call
5345 ** ^The [sqlite3_reset(S)] interface does not change the values
5348 SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
5361 ** created) and the presence or absence of a destructor callback for
5368 ** connection then application-defined SQL functions must be added
5372 ** redefined. ^The length of the name is limited to 255 bytes in a UTF-8
5373 ** representation, exclusive of the zero-terminator. ^Note that the name
5374 ** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
5380 ** aggregate takes. ^If this parameter is -1, then the SQL function or
5381 ** aggregate may take any number of arguments between 0 and the limit
5383 ** parameter is less than -1 or greater than 127 then the behavior is
5402 ** deterministic. The built-in [random()] SQL function is an example of a
5413 ** all application-defined SQL functions that do not need to be
5420 ** the database file is opened and read.
5425 ** ^The sixth, seventh and eighth parameters passed to the three
5426 ** "sqlite3_create_function*" functions, xFunc, xStep and xFinal, are
5427 ** pointers to C-language functions that implement the SQL function or
5429 ** callback only; NULL pointers must be passed as the xStep and xFinal
5431 ** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing
5435 ** ^The sixth, seventh, eighth and ninth parameters (xStep, xFinal, xValue
5436 ** and xInverse) passed to sqlite3_create_window_function are pointers to
5437 ** C-language callbacks that implement the new function. xStep and xFinal
5438 ** must both be non-NULL. xValue and xInverse may either both be NULL, in
5440 ** non-NULL, in which case the new function may be used as either an aggregate
5443 ** [user-defined window functions|available here].
5458 ** SQL function is used. ^A function implementation with a non-negative
5463 ** ^A function where the encoding difference is between UTF16le and UTF16be
5465 ** between UTF8 and UTF16.
5467 ** ^Built-in functions may be overloaded by new application-defined functions.
5469 ** ^An application-defined function is permitted to call other
5474 SQLITE_API int sqlite3_create_function(
5477 int nArg,
5478 int eTextRep,
5480 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
5481 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
5484 SQLITE_API int sqlite3_create_function16(
5487 int nArg,
5488 int eTextRep,
5490 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
5491 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
5494 SQLITE_API int sqlite3_create_function_v2(
5497 int nArg,
5498 int eTextRep,
5500 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
5501 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
5505 SQLITE_API int sqlite3_create_window_function(
5508 int nArg,
5509 int eTextRep,
5511 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
5514 void (*xInverse)(sqlite3_context*,int,sqlite3_value**),
5524 #define SQLITE_UTF8 1 /* IMP: R-37514-35566 */
5525 #define SQLITE_UTF16LE 2 /* IMP: R-03371-37637 */
5526 #define SQLITE_UTF16BE 3 /* IMP: R-51971-34154 */
5553 ** from top-level SQL, and cannot be used in VIEWs or TRIGGERs nor in
5558 ** [application-defined SQL function]
5559 ** that has side-effects or that could potentially leak sensitive information.
5562 ** modified to invoke the application-defined function in ways that are
5566 ** [application-defined SQL functions], regardless of whether or not they
5568 ** inside of the database schema, and thus ensures that the database
5569 ** can be inspected and modified using generic tools (such as the [CLI])
5570 ** that do not have access to the application-defined functions.
5576 ** no side effects and should not depend on any values other than its
5585 ** ([SQLITE_DBCONFIG_TRUSTED_SCHEMA] and [PRAGMA trusted_schema=OFF])
5586 ** disable the use of SQL functions inside views and triggers and in
5588 ** [expression indexes], [partial indexes], and [generated columns] unless
5589 ** the function is tagged with SQLITE_INNOCUOUS. Most built-in functions
5591 ** SQLITE_INNOCUOUS flag for application-defined functions unless the
5592 ** function has been carefully audited and found to be free of potentially
5593 ** security-adverse side-effects and information-leaks.
5598 ** [sqlite3_value_subtype()] to inspect the sub-types of its arguments.
5599 ** This flag instructs SQLite to omit some corner-case optimizations that
5605 ** a non-zero subtype was specified by the function argument expression.
5609 ** [sqlite3_result_subtype()] to cause a sub-type to be associated with its
5613 ** might become a no-op if the function is used as term in an
5638 SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
5639 SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
5640 SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
5641 SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);
5643 SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),
5648 ** CAPI3REF: Obtaining SQL Values
5655 ** <tr><td><b>sqlite3_value_int</b><td>→<td>32-bit INTEGER value
5656 ** <tr><td><b>sqlite3_value_int64</b><td>→<td>64-bit INTEGER value
5658 ** <tr><td><b>sqlite3_value_text</b><td>→<td>UTF-8 TEXT value
5659 ** <tr><td><b>sqlite3_value_text16</b><td>→<td>UTF-16 TEXT value in
5661 ** <tr><td><b>sqlite3_value_text16be</b><td>→<td>UTF-16be TEXT value
5662 ** <tr><td><b>sqlite3_value_text16le</b><td>→<td>UTF-16le TEXT value
5665 ** or a UTF-8 TEXT in bytes
5667 ** <td>→ <td>Size of UTF-16
5682 ** These routines extract type, size, and content information from
5685 ** implement [application-defined SQL functions] and [virtual tables].
5693 ** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
5695 ** ^The sqlite3_value_text16() interface extracts a UTF-16 string
5696 ** in the native byte-order of the host machine. ^The
5697 ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
5698 ** extract UTF-16 strings as big-endian and little-endian respectively.
5702 ** and if X and Y are strings that compare equal according to strcmp(X,Y),
5712 ** For example, if the datatype is initially SQLITE_INTEGER and
5716 ** occurs is undefined and may change from one release of SQLite to the next.
5727 ** sqlite3_value_nochange(X) interface returns true if and only if
5729 ** that the xUpdate method call was invoked to implement and if
5730 ** and the prior [xColumn] method call that was invoked to extracted
5732 ** because it queried [sqlite3_vtab_nochange()] and found that the column
5737 ** the return value is arbitrary and meaningless.
5739 ** ^The sqlite3_value_frombind(X) interface returns non-zero if the
5754 ** fail if an out-of-memory error occurs during a format conversion.
5755 ** Only the following subset of interfaces are subject to out-of-memory
5768 ** If an out-of-memory error occurs, then the return value from these
5770 ** Valid SQL NULL returns can be distinguished from out-of-memory errors
5772 ** return value is obtained and before any
5777 SQLITE_API int sqlite3_value_int(sqlite3_value*);
5784 SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
5785 SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
5786 SQLITE_API int sqlite3_value_type(sqlite3_value*);
5787 SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
5788 SQLITE_API int sqlite3_value_nochange(sqlite3_value*);
5789 SQLITE_API int sqlite3_value_frombind(sqlite3_value*);
5802 ** [sqlite3_value_bytes16(X)] might change the encoding of the value X and
5805 ** This routine is intended for used by applications that test and validate
5808 ** not need to know what the internal state of an sqlite3_value object is and
5811 SQLITE_API int sqlite3_value_encoding(sqlite3_value*);
5814 ** CAPI3REF: Finding The Subtype Of SQL Values
5818 ** an [application-defined SQL function] argument V. The subtype
5823 ** Every [application-defined SQL function] that invoke this interface
5829 SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*);
5832 ** CAPI3REF: Copy And Free SQL Values
5836 ** object D and returns a pointer to that copy. ^The [sqlite3_value] returned
5844 ** then sqlite3_value_free(V) is a harmless no-op.
5858 ** N bytes of memory, zeroes out that memory, and returns a pointer
5859 ** to the new memory. ^On second and subsequent calls to
5862 ** called once for each invocation of the xStep callback and then one
5865 ** implementation is never called and xFinal() is called exactly once.
5892 SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
5901 ** and [sqlite3_create_function16()] routines that originally
5905 ** the application-defined function is running.
5916 ** and [sqlite3_create_function16()] routines that originally
5925 ** These functions may be used by (non-aggregate) SQL functions to
5926 ** associate auxiliary data with argument values. If the same argument
5930 ** regular-expression matching function. The compiled version of the regular
5938 ** value to the application-defined function. ^N is zero for the left-most
5944 ** N-th argument of the application-defined function. ^Subsequent
5966 ** should be called near the end of the function implementation and the
5970 ** to sqlite3_set_auxdata() might still return NULL if an out-of-memory
5976 ** function parameters that are compile-time constants, including literal
5977 ** values and [parameters] and expressions composed from the same.)^
5979 ** The value of the N parameter to these interfaces should be non-negative.
5980 ** Future enhancements may make use of negative N values to define new
5986 ** See also: [sqlite3_get_clientdata()] and [sqlite3_set_clientdata()].
5988 SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
5989 SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
6001 ** sqlite3_set_clientdata() with the same values of D and N.
6002 ** Names are compared using strcmp() and are thus case sensitive.
6004 ** If P and X are both non-NULL, then the destructor X is invoked with
6007 ** <li> An out-of-memory error occurs during the call to
6010 ** with the same D and N parameters.
6026 ** Applications and wrapper libraries are discouraged from using more than
6040 ** version 3.44.0 ([dateof:3.44.0]) and later.
6042 ** See also: [sqlite3_set_auxdata()] and [sqlite3_get_auxdata()].
6045 SQLITE_API int sqlite3_set_clientdata(sqlite3*, const char*, void*, void(*)(void*));
6050 ** These are special values for the destructor that is passed in as the
6053 ** and will never change. It does not need to be destroyed. ^The
6055 ** the near future and that SQLite should make its own private copy of
6063 #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)
6070 ** implement SQL functions and aggregates. See
6071 ** [sqlite3_create_function()] and [sqlite3_create_function16()]
6075 ** functions used to bind values to host parameters in prepared statements.
6079 ** an application-defined function to be the BLOB whose content is pointed
6080 ** to by the second parameter and which is N bytes long where N is the
6083 ** ^The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N)
6084 ** interfaces set the result of the application-defined function to be
6085 ** a BLOB containing all zero bytes and N bytes in size.
6088 ** an application-defined function to be a floating point value specified
6091 ** ^The sqlite3_result_error() and sqlite3_result_error16() functions
6096 ** message string from sqlite3_result_error() as UTF-8. ^SQLite
6097 ** interprets the string from sqlite3_result_error16() as UTF-16 using
6098 ** the same [byte-order determination rules] as [sqlite3_bind_text16()].
6103 ** sqlite3_result_error16() is non-negative then SQLite takes that many
6105 ** ^The sqlite3_result_error() and sqlite3_result_error16()
6121 ** of the application-defined function to be the 32-bit signed integer
6124 ** of the application-defined function to be the 64-bit signed integer
6128 ** of the application-defined function to be NULL.
6131 ** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
6132 ** set the return value of the application-defined function to be
6133 ** a text string which is represented as UTF-8, UTF-16 native byte order,
6134 ** UTF-16 little endian, or UTF-16 big endian, respectively.
6136 ** application-defined function to be a text string in an encoding
6137 ** specified by the fifth (and last) parameter, which must be one
6143 ** the string length itself by searching the 2nd parameter for the first
6146 ** is non-negative, then as many bytes (not characters) of the text
6147 ** pointed to by the 2nd parameter are taken as the application-defined
6148 ** function result. If the 3rd parameter is non-negative, then it
6152 ** parameter, then the resulting string will contain embedded NULs and the
6155 ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
6160 ** assumes that the text or BLOB result is in constant space and does not
6168 ** ^For the sqlite3_result_text16(), sqlite3_result_text16le(), and
6169 ** sqlite3_result_text16be() routines, and for sqlite3_result_text64()
6171 ** byte-order mark (BOM, U+FEFF) then the BOM is removed from the
6172 ** string and the rest of the string is interpreted according to the
6173 ** byte-order specified by the BOM. ^The byte-order specified by
6174 ** the BOM at the beginning of the text overrides the byte-order
6177 ** with bytes 0xfe, 0xff (a big-endian byte-order mark) then the
6178 ** first two bytes of input are skipped and the remaining input
6182 ** sqlite3_result_text16be(), sqlite3_result_text16le(), and
6188 ** the application-defined function to be a copy of the
6199 ** also associates the host-language pointer P or type T with that
6201 ** [application-defined SQL function] using [sqlite3_value_pointer()].
6205 ** string and preferably a string literal. The sqlite3_result_pointer()
6209 ** than the one containing the application-defined function that received
6212 SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
6216 SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);
6217 SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);
6220 SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int);
6221 SQLITE_API void sqlite3_result_int(sqlite3_context*, int);
6224 SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
6227 SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
6228 SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
6229 SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
6232 SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
6233 SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);
6241 ** the result from the [application-defined SQL function] with
6248 ** Every [application-defined SQL function] that invokes this interface
6256 ** If SQLite is compiled with -DSQLITE_STRICT_SUBTYPE=1, then any
6258 ** and that does not have the SQLITE_RESULT_SUBTYPE property will raise
6259 ** an error. Future versions of SQLite might enable -DSQLITE_STRICT_SUBTYPE=1
6262 SQLITE_API void sqlite3_result_subtype(sqlite3_context*,unsigned int);
6271 ** ^The name of the collation is a UTF-8 string
6272 ** for sqlite3_create_collation() and sqlite3_create_collation_v2()
6273 ** and a UTF-16 string in native byte order for sqlite3_create_collation16().
6287 ** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep
6297 ** with different eTextRep parameters and SQLite will use whichever
6304 ** application data pointer and with two strings in the encoding specified
6306 ** function callback are the length of the two strings, in bytes. The collating
6311 ** to the same collation name (using different eTextRep values) then all
6314 ** strings A, B, and C:
6318 ** <li> If A==B and B==C then A==C.
6320 ** <li> If A<B and B<C then A<C.
6323 ** If a collating function fails any of the above constraints and that
6324 ** collating function is registered and used, then the behavior of SQLite
6336 ** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should
6337 ** check the return code and dispose of the application data pointer
6343 ** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
6345 SQLITE_API int sqlite3_create_collation(
6348 int eTextRep,
6350 int(*xCompare)(void*,int,const void*,int,const void*)
6352 SQLITE_API int sqlite3_create_collation_v2(
6355 int eTextRep,
6357 int(*xCompare)(void*,int,const void*,int,const void*),
6360 SQLITE_API int sqlite3_create_collation16(
6363 int eTextRep,
6365 int(*xCompare)(void*,int,const void*,int,const void*)
6379 ** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
6380 ** the names are passed as UTF-16 in machine native byte order.
6381 ** ^A call to either function replaces the existing collation-needed callback.
6395 SQLITE_API int sqlite3_collation_needed(
6398 void(*)(void*,sqlite3*,int eTextRep,const char*)
6400 SQLITE_API int sqlite3_collation_needed16(
6403 void(*)(void*,sqlite3*,int eTextRep,const void*)
6434 ** VFS and operating system. Some system treat a negative argument as an
6436 ** at all. ^In SQLite version 3.42.0 and later, a negative
6440 SQLITE_API int sqlite3_sleep(int);
6445 ** ^(If this global variable is made to point to a string which is
6447 ** created by SQLite when using a built-in [sqlite3_vfs | VFS]
6448 ** will be placed in that directory.)^ ^If this variable
6452 ** Applications are strongly discouraged from using this global variable.
6455 ** neither read nor write this variable. This global variable is a relic
6456 ** that exists for backwards compatibility of legacy applications and should
6459 ** It is not safe to read or modify this variable in more than one
6460 ** thread at a time. It is not safe to read or modify this variable
6463 ** It is intended that this variable be set once
6464 ** as part of process initialization and before any SQLite interface
6465 ** routines have been called and that this variable remain unchanged
6468 ** ^The [temp_store_directory pragma] may modify this variable and cause
6471 ** that this variable points to is held in memory obtained from
6472 ** [sqlite3_malloc] and the pragma may attempt to free that memory
6474 ** Hence, if this variable is modified directly, either it should be
6489 ** LPCWSTR zPath = Windows::Storage::ApplicationData::Current->
6490 ** TemporaryFolder->Path->Data();
6493 ** WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, sizeof(zPathBuf),
6503 ** ^(If this global variable is made to point to a string which is
6505 ** specified with a relative pathname and created or accessed by
6506 ** SQLite when using a built-in windows [sqlite3_vfs | VFS] will be assumed
6507 ** to be relative to that directory.)^ ^If this variable is a NULL
6511 ** variable; it is ignored by the unix VFS.
6513 ** Changing the value of this variable while a database connection is
6516 ** It is not safe to read or modify this variable in more than one
6517 ** thread at a time. It is not safe to read or modify this variable
6520 ** It is intended that this variable be set once
6521 ** as part of process initialization and before any SQLite interface
6522 ** routines have been called and that this variable remain unchanged
6525 ** ^The [data_store_directory pragma] may modify this variable and cause
6528 ** that this variable points to is held in memory obtained from
6529 ** [sqlite3_malloc] and the pragma may attempt to free that memory
6531 ** Hence, if this variable is modified directly, either it should be
6542 ** with the [sqlite3_temp_directory] or [sqlite3_data_directory] variable, to
6545 ** a non-NULL value will be copied into memory obtained from [sqlite3_malloc]
6549 ** [sqlite3_data_directory] variable is intended to act as a replacement for
6550 ** the current directory on the sub-platforms of Win32 where that concept is
6551 ** not present, e.g. WinRT and UWP. The [sqlite3_win32_set_directory8] and
6554 ** UTF-8 or UTF-16, respectively.
6556 SQLITE_API int sqlite3_win32_set_directory(
6560 SQLITE_API int sqlite3_win32_set_directory8(unsigned long type, const char *zValue);
6561 SQLITE_API int sqlite3_win32_set_directory16(unsigned long type, const void *zValue);
6566 ** These macros are only available on Windows. They define the allowed values
6573 ** CAPI3REF: Test For Auto-Commit Mode
6577 ** ^The sqlite3_get_autocommit() interface returns non-zero or
6581 ** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
6583 ** If certain kinds of errors occur on a statement within a multi-statement
6585 ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
6594 SQLITE_API int sqlite3_get_autocommit(sqlite3*);
6614 ** for the N-th database on database connection D, or a NULL pointer of N is
6616 ** the "temp" schema. Larger values of N correspond to various ATTACH-ed
6624 ** remember the string long-term should make their own copy. Applications that
6626 ** threads should mutex-protect calls to this API and should make their own
6629 SQLITE_API const char *sqlite3_db_name(sqlite3 *db, int N);
6638 ** connection D, or if database N is a temporary or in-memory database, then
6641 ** ^The string value returned by this routine is owned and managed by
6643 ** is [DETACH]-ed or until the database connection closes.
6664 ** CAPI3REF: Determine if a database is read-only
6668 ** of connection D is read-only, 0 if it is read/write, or -1 if N is not
6671 SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName);
6687 ** a valid schema, then -1 is returned.
6689 SQLITE_API int sqlite3_txn_state(sqlite3*,const char *zSchema);
6692 ** CAPI3REF: Allowed return values from sqlite3_txn_state()
6709 ** will advanced to SQLITE_TXN_WRITE if any changes occur and there are
6736 ** connection and in particular must not be a NULL pointer.
6741 ** CAPI3REF: Commit And Rollback Notification Callbacks
6753 ** ^If the callback on a commit hook function returns non-zero,
6756 ** ^The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions
6761 ** The commit and rollback hook callbacks are not reentrant.
6768 ** or merely calling [sqlite3_prepare_v2()] and [sqlite3_step()] will modify
6775 ** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
6777 ** hook returning non-zero, just as it would be with any other rollback.
6787 SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
6797 ** the schema-name of the attached database that is being autovacuumed,
6799 ** and the number of bytes per page, respectively. The callback should
6805 ** <p>^If there are multiple ATTACH-ed database files that are being
6811 ** things may happen, including segmentation faults and corrupt database
6813 ** does some arithmetic on its input parameters and returns a result.
6837 ** unsigned int demonstration_autovac_pages_callback(
6840 ** unsigned int nDbPage,
6841 ** unsigned int nFreePage,
6842 ** unsigned int nBytePerPage
6848 SQLITE_API int sqlite3_autovacuum_pages(
6850 unsigned int(*)(void*,const char*,unsigned int,unsigned int,unsigned int),
6874 ** ^The third and fourth arguments to the callback contain pointers to the
6875 ** database and table name containing the affected row.
6891 ** corresponding change is currently unspecified and may differ
6900 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
6909 ** and [sqlite3_preupdate_hook()] interfaces.
6913 void(*)(void *,int ,char const *,char const *,sqlite3_int64),
6921 ** and schema data structures between [database connection | connections]
6923 ** and disabled if the argument is false.)^
6926 ** [-DSQLITE_OMIT_SHARED_CACHE]. The [-DSQLITE_OMIT_SHARED_CACHE]
6927 ** compile-time option is recommended because the
6930 ** ^Cache sharing is enabled and disabled for an entire process.
6936 ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
6951 ** Note: This method is disabled on MacOS X 10.7 and iOS version 5.0
6952 ** and will always return SQLITE_MISUSE. On those systems,
6953 ** shared cache mode should be enabled per-database connection via
6957 ** 32-bit integer is atomic.
6959 ** See Also: [SQLite Shared-Cache Mode]
6961 SQLITE_API int sqlite3_enable_shared_cache(int);
6967 ** of heap memory by deallocating non-essential memory allocations
6969 ** pages to improve performance is an example of non-essential memory.
6972 ** ^The sqlite3_release_memory() routine is a no-op returning zero
6977 SQLITE_API int sqlite3_release_memory(int);
6986 ** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is
6991 SQLITE_API int sqlite3_db_release_memory(sqlite3*);
6999 ** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the
7015 ** ^The return value from both sqlite3_soft_heap_limit64() and
7021 ** sqlite3_soft_heap_limit64(-1) or sqlite3_hard_heap_limit(-1).
7026 ** ^If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N)
7030 ** limit is enabled. ^When sqlite3_hard_heap_limit64(N) is invoked and
7037 ** [PRAGMA soft_heap_limit] and [PRAGMA hard_heap_limit].
7045 ** [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and
7046 ** the [SQLITE_DEFAULT_MEMSTATUS] compile-time option.
7069 SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
7079 ** interface returns SQLITE_OK and fills in the non-NULL pointers in
7080 ** the final five arguments with appropriate values if the specified
7083 ** ^If the column-name parameter to sqlite3_table_column_metadata() is a
7085 ** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it
7090 ** ^The column is identified by the second, third and fourth parameters to
7097 ** ^The third and fourth parameters to this function are the table and column
7101 ** and subsequent parameters to this function. ^Any of these arguments may be
7110 ** <tr><td> 7th <td> int <td> True if column has a NOT NULL constraint
7111 ** <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY
7112 ** <tr><td> 9th <td> int <td> True if column is [AUTOINCREMENT]
7117 ** declaration type and collation sequence is valid until the next
7122 ** ^If the specified column is "rowid", "oid" or "_rowid_" and the table
7123 ** is not a [WITHOUT ROWID] table and an
7137 ** ^This function causes all database schemas to be read from disk and
7138 ** parsed, if that has not already been done, and returns an error if
7141 SQLITE_API int sqlite3_table_column_metadata(
7148 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
7149 int *pPrimaryKey, /* OUTPUT: True if column part of PK */
7150 int *pAutoinc /* OUTPUT: True if column is auto-increment */
7162 ** with various operating-system specific extensions added.
7171 ** X is consists of the lower-case equivalent of all ASCII alphabetic
7173 ** "." and omitting any initial "lib".)^
7175 ** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
7176 ** ^If an error occurs and pzErrMsg is not 0, then the
7192 ** disabled and prevent SQL injections from giving attackers
7197 SQLITE_API int sqlite3_load_extension(
7209 ** unprepared to deal with [extension loading], and as a means of disabling
7210 ** [extension loading] while evaluating user-entered SQL, the following API
7211 ** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
7215 ** to turn extension loading on and call it with onoff==0 to turn
7218 ** ^This interface enables or disables both the C-API
7219 ** [sqlite3_load_extension()] and the SQL function [load_extension()].
7221 ** to enable or disable only the C-API.)^
7229 SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
7240 ** no arguments and returns void, SQLite invokes xEntryPoint() with three
7241 ** arguments and expects an integer result as if the signature of the
7245 ** int xEntryPoint(
7254 ** and return an appropriate [error code]. ^SQLite ensures that *pzErrMsg
7261 ** on the list of automatic extensions is a harmless no-op. ^No entry point
7265 ** and [sqlite3_cancel_auto_extension()]
7267 SQLITE_API int sqlite3_auto_extension(void(*xEntryPoint)(void));
7276 ** unregistered and it returns 0 if X was not on the list of initialization
7279 SQLITE_API int sqlite3_cancel_auto_extension(void(*xEntryPoint)(void));
7306 ** instance of this structure and passing a pointer to that instance
7314 int iVersion;
7315 int (*xCreate)(sqlite3*, void *pAux,
7316 int argc, const char *const*argv,
7318 int (*xConnect)(sqlite3*, void *pAux,
7319 int argc, const char *const*argv,
7321 int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
7322 int (*xDisconnect)(sqlite3_vtab *pVTab);
7323 int (*xDestroy)(sqlite3_vtab *pVTab);
7324 int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
7325 int (*xClose)(sqlite3_vtab_cursor*);
7326 int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
7327 int argc, sqlite3_value **argv);
7328 int (*xNext)(sqlite3_vtab_cursor*);
7329 int (*xEof)(sqlite3_vtab_cursor*);
7330 int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
7331 int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
7332 int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
7333 int (*xBegin)(sqlite3_vtab *pVTab);
7334 int (*xSync)(sqlite3_vtab *pVTab);
7335 int (*xCommit)(sqlite3_vtab *pVTab);
7336 int (*xRollback)(sqlite3_vtab *pVTab);
7337 int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
7338 void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
7340 int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
7342 ** below are for version 2 and greater. */
7343 int (*xSavepoint)(sqlite3_vtab *pVTab, int);
7344 int (*xRelease)(sqlite3_vtab *pVTab, int);
7345 int (*xRollbackTo)(sqlite3_vtab *pVTab, int);
7346 /* The methods above are in versions 1 and 2 of the sqlite_module object.
7347 ** Those below are for version 3 and greater. */
7348 int (*xShadowName)(const char*);
7350 ** Those below are for version 4 and greater. */
7351 int (*xIntegrity)(sqlite3_vtab *pVTab, const char *zSchema,
7352 const char *zTabName, int mFlags, char **pzErr);
7359 ** The sqlite3_index_info structure and its substructures is used as part
7361 ** pass information into and receive the reply from the [xBestIndex]
7363 ** inputs to xBestIndex and are read-only. xBestIndex inserts its
7366 ** ^(The aConstraint[] array records WHERE clause constraints of the form:
7372 ** [SQLITE_INDEX_CONSTRAINT_EQ | SQLITE_INDEX_CONSTRAINT_ values].)^
7375 ** expr on the right-hand side can be evaluated (and thus the constraint
7376 ** is usable) and false if it cannot.)^
7379 ** and makes other simplifications to the WHERE clause in an attempt to
7381 ** ^The aConstraint[] array only reports WHERE clause terms that are
7390 ** passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62),
7392 ** required by SQLite. If the table has at least 64 columns and any column
7396 ** non-zero.
7400 ** the right-hand side of the corresponding aConstraint[] is evaluated
7401 ** and becomes the argvIndex-th entry in argv. ^(If aConstraintUsage[].omit
7403 ** virtual table and might not be checked again by the byte code.)^ ^(The
7411 ** ^The idxNum and idxStr values are recorded and passed into the
7413 ** ^[sqlite3_free()] is used to free idxStr if and only if
7430 ** mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag -
7436 ** part of the same statement to delete or update a virtual table row and the
7441 ** set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by
7459 int nConstraint; /* Number of entries in aConstraint */
7461 int iColumn; /* Column constrained. -1 for ROWID */
7464 int iTermOffset; /* Used internally - xBestIndex should ignore */
7466 int nOrderBy; /* Number of terms in the ORDER BY clause */
7468 int iColumn; /* Column number */
7473 int argvIndex; /* if >0, constraint is part of argv to xFilter */
7476 int idxNum; /* Number used to identify the index */
7478 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
7479 int orderByConsumed; /* True if output is already ordered */
7481 /* Fields below are only available in SQLite 3.8.2 and later */
7483 /* Fields below are only available in SQLite 3.9.0 and later */
7484 int idxFlags; /* Mask of SQLITE_INDEX_SCAN_* flags */
7485 /* Fields below are only available in SQLite 3.10.0 and later */
7501 ** These macros define the allowed values for the
7506 ** ^The left-hand operand of the operator is given by the corresponding
7507 ** aConstraint[].iColumn field. ^An iColumn of -1 indicates the left-hand
7509 ** The SQLITE_INDEX_CONSTRAINT_LIMIT and SQLITE_INDEX_CONSTRAINT_OFFSET
7510 ** operators have no left-hand operand, and so for those operators the
7511 ** corresponding aConstraint[].iColumn is meaningless and should not be
7514 ** All operator values from SQLITE_INDEX_CONSTRAINT_FUNCTION through
7519 ** The right-hand operands for each constraint might be accessible using
7520 ** the [sqlite3_vtab_rhs_value()] interface. Usually the right-hand
7522 ** in the input SQL. If the right-hand operand is another column or an
7525 ** ^The SQLITE_INDEX_CONSTRAINT_ISNULL and
7526 ** SQLITE_INDEX_CONSTRAINT_ISNOTNULL operators have no right-hand operand
7527 ** and hence calls to sqlite3_vtab_rhs_value() for those operators will
7531 ** the [sqlite3_vtab_collation()] interface. For most real-world virtual
7533 ** because the constraints are numeric) and so the sqlite3_vtab_collation()
7560 ** creating a new [virtual table] using the module and before using a
7568 ** into the [xCreate] and [xConnect] methods of the virtual table module
7581 ** NULL then no new module is created and any existing modules with the
7586 SQLITE_API int sqlite3_create_module(
7592 SQLITE_API int sqlite3_create_module_v2(
7606 ** The L parameter must be either NULL or a pointer to an array of pointers
7607 ** to strings where the array is terminated by a single NULL pointer.
7612 SQLITE_API int sqlite3_drop_modules(
7633 ** freed by sqlite3_free() and the zErrMsg field will be zeroed.
7637 int nRef; /* Number of open cursors */
7648 ** [virtual table] and are used
7650 ** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed
7652 ** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods
7667 ** ^The [xCreate] and [xConnect] methods of a
7669 ** to declare the format (the names and datatypes of the columns) of
7672 SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
7684 ** name and number of parameters exists. If no such function exists
7691 SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
7700 ** and destroyed by [sqlite3_blob_close()].
7701 ** ^The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
7726 ** ^If the flags parameter is non-zero, then the BLOB is opened for read
7727 ** and write access. ^If the flags parameter is zero, the BLOB is opened for
7728 ** read-only access.
7730 ** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is stored
7731 ** in *ppBlob. Otherwise an [error code] is returned and, unless the error
7746 ** constraint and the blob is being opened for read/write access)^,
7748 ** column zColumn is part of a [child key] definition and the blob is
7753 ** [database connection] error code and message accessible via
7754 ** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.
7757 ** [sqlite3_blob_read()] interface and modified by using
7764 ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
7768 ** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
7779 ** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
7780 ** and the built-in [zeroblob] SQL function may be used to create a
7781 ** zero-filled blob to read or write using the incremental-blob interface.
7790 SQLITE_API int sqlite3_blob_open(
7796 int flags,
7807 ** changed. ^The database, table and column on which the blob handle is open
7809 ** faster than closing the existing handle and opening a new one.
7811 ** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] -
7812 ** it must exist and there must be either a blob or text value stored in
7815 ** SQLite error code is returned and the blob handle is considered aborted.
7821 ** ^This function sets the database handle error code and message.
7823 SQLITE_API int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
7833 ** ^If the blob handle being closed was opened for read-write access, and if
7834 ** the database is in auto-commit mode and there are no other open read-write
7837 ** code is returned and the transaction rolled back.
7842 ** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function
7843 ** is passed a valid open blob handle, the values returned by the
7844 ** sqlite3_errcode() and sqlite3_errmsg() functions are set before returning.
7846 SQLITE_API int sqlite3_blob_close(sqlite3_blob *);
7858 ** by a prior successful call to [sqlite3_blob_open()] and which has not
7860 ** to this routine results in undefined and probably undesirable behavior.
7862 SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *);
7869 ** caller-supplied buffer. N bytes of data are copied into buffer Z
7873 ** [SQLITE_ERROR] is returned and no data is read. ^If N or iOffset is
7874 ** less than zero, [SQLITE_ERROR] is returned and no data is read.
7875 ** ^The size of the blob (and hence the maximum value of N+iOffset)
7885 ** by a prior successful call to [sqlite3_blob_open()] and which has not
7887 ** to this routine results in undefined and probably undesirable behavior.
7891 SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
7898 ** caller-supplied buffer. N bytes of data are copied from the buffer Z
7904 ** [database connection] error code and message accessible via
7905 ** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.
7914 ** [SQLITE_ERROR] is returned and no data is written. The size of the
7915 ** BLOB (and hence the maximum value of N+iOffset) can be determined
7917 ** than zero [SQLITE_ERROR] is returned and no data is written.
7927 ** by a prior successful call to [sqlite3_blob_open()] and which has not
7929 ** to this routine results in undefined and probably undesirable behavior.
7933 SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
7942 ** New VFSes can be registered and existing VFSes can be unregistered.
7947 ** ^Names are zero-terminated UTF-8 strings.
7965 SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
7966 SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
7978 ** is selected automatically at compile-time. The following
7988 ** that does no real locking and is appropriate for use in
7989 ** a single-threaded application. The SQLITE_MUTEX_PTHREADS and
7991 ** and Windows.
7994 ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
8002 ** mutex and returns a pointer to it. ^The sqlite3_mutex_alloc()
8024 ** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
8029 ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
8031 ** cases where it really needs one. If a faster non-recursive mutex
8036 ** than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return
8054 ** ^The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
8056 ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
8080 ** then any of the four routines behaves as a no-op.
8082 ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
8084 SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int);
8087 SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*);
8093 ** An instance of this structure defines the low-level routines
8094 ** used to allocate and use mutexes.
8100 ** creates and populates an instance of this structure to pass
8103 ** output variable when querying the system for the current mutex
8119 ** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and
8141 ** invoke xMutexInit() multiple times within the same process and without
8142 ** intervening calls to xMutexEnd(). Second and subsequent calls to
8143 ** xMutexInit() must be no-ops.
8146 ** and its associates). Similarly, xMutexAlloc() must not use SQLite memory
8157 int (*xMutexInit)(void);
8158 int (*xMutexEnd)(void);
8159 sqlite3_mutex *(*xMutexAlloc)(int);
8162 int (*xMutexTry)(sqlite3_mutex *);
8164 int (*xMutexHeld)(sqlite3_mutex *);
8165 int (*xMutexNotheld)(sqlite3_mutex *);
8171 ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
8173 ** never uses these routines except inside an assert() and applications
8178 ** defined and if NDEBUG is not defined.
8189 ** the routine should return 1. This seems counter-intuitive since
8192 ** using mutexes. And we do not want the assert() containing the
8193 ** call to sqlite3_mutex_held() to fail, so a non-zero return is
8198 SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*);
8199 SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*);
8209 ** next. Applications that override the built-in mutex logic must be
8225 #define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */
8240 ** ^If the [threading mode] is Single-thread or Multi-thread then this
8246 ** CAPI3REF: Low-Level Control Of Database Files
8258 ** ^The third and fourth parameters to this routine
8259 ** are passed directly through to the second and third parameters of
8264 ** by the SQLite core and never invoke the
8278 ** code is not remembered and will not be recalled by [sqlite3_errcode()]
8281 ** an incorrect zDbName and an SQLITE_ERROR return from the underlying
8286 SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
8292 ** state of SQLite and to inject faults into SQLite for testing
8294 ** the number, meaning, and operation of all subsequent parameters.
8301 ** they take, and what they do are all subject to change without notice.
8305 SQLITE_API int sqlite3_test_control(int op, ...);
8313 ** These parameters and their meanings are subject to change
8314 ** without notice. These values are for testing purposes only.
8361 ** by enclosing in double-quotes) so as not to confuse the parser.
8366 ** The sqlite3_keyword_name(N,Z,L) interface finds the 0-based N-th keyword and
8367 ** makes *Z point to that keyword expressed as UTF8 and writes the number
8369 ** zero-terminated. The sqlite3_keyword_name(N,Z,L) routine returns
8370 ** SQLITE_OK if N is within bounds and SQLITE_ERROR if not. If either Z
8375 ** the L-byte UTF8 identifier that Z points to is a keyword, returning non-zero
8376 ** if it is and zero if not.
8381 ** "CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" is accepted by SQLite, and
8383 ** "REPLACE", "PRAGMA", and "END". Nevertheless, best practice is to avoid
8387 ** <li> Put all identifier names inside double-quotes. This is the official
8390 ** but it is what SQL Server does and so lots of programmers use this
8398 ** compile-time options. For example, "VACUUM" is not a keyword if
8399 ** SQLite is compiled with the [-DSQLITE_OMIT_VACUUM] option. Also,
8402 SQLITE_API int sqlite3_keyword_count(void);
8403 SQLITE_API int sqlite3_keyword_name(int,const char**,int*);
8404 SQLITE_API int sqlite3_keyword_check(const char*,int);
8410 ** An instance of the sqlite3_str object contains a dynamically-sized
8418 ** <li> ^The sqlite3_str object is destroyed and the string it created
8428 ** ^The [sqlite3_str_new(D)] interface allocates and initializes
8434 ** valid [sqlite3_str] object, though in the event of an out-of-memory
8438 ** [sqlite3_str_length()], and always return NULL from
8445 ** length of the string contained in the [sqlite3_str] object will be
8456 ** and returns a pointer to a memory buffer obtained from [sqlite3_malloc64()]
8473 ** ^The [sqlite3_str_appendf(X,F,...)] and
8474 ** [sqlite3_str_vappendf(X,F,V)] interfaces uses the [built-in printf]
8479 ** onto the end of the [sqlite3_str] object X. N must be non-negative.
8480 ** S must contain at least N non-zero bytes of content. To append a
8481 ** zero-terminated string in its entirety, use the [sqlite3_str_appendall()]
8485 ** zero-terminated string S onto the end of [sqlite3_str] object X.
8488 ** single-byte character C onto the end of [sqlite3_str] object X.
8492 ** inside [sqlite3_str] object X back to zero bytes in length.
8495 ** is recorded in the [sqlite3_str] object and can be recovered by a
8500 SQLITE_API void sqlite3_str_append(sqlite3_str*, const char *zIn, int N);
8502 SQLITE_API void sqlite3_str_appendchar(sqlite3_str*, int N, char C);
8514 ** [SQLITE_NOMEM] following any out-of-memory error, or
8518 ** ^The [sqlite3_str_length(X)] method returns the current length, in bytes,
8520 ** ^The length returned by [sqlite3_str_length(X)] does not include the
8521 ** zero-termination byte.
8526 ** and might be freed or altered by any subsequent method on the same
8531 ** outside the range of 0 to [sqlite3_str_length(X)] and do not read or
8534 SQLITE_API int sqlite3_str_errcode(sqlite3_str*);
8535 SQLITE_API int sqlite3_str_length(sqlite3_str*);
8542 ** about the performance of SQLite, and optionally to reset various
8551 ** nothing is written into *pHighwater and the resetFlag is ignored.)^
8552 ** ^(Other parameters record only the highwater mark and not the current
8555 ** ^The sqlite3_status() and sqlite3_status64() routines return
8556 ** SQLITE_OK on success and a non-zero [error code] on failure.
8559 ** be represented by a 32-bit integer, then the values returned by
8564 SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
8565 SQLITE_API int sqlite3_status64(
8566 int op,
8569 int resetFlag
8577 ** These integer constants designate various run-time status parameters
8585 ** and internal memory usage by the SQLite library. Auxiliary page-cache
8611 ** buffer and where forced to overflow to [sqlite3_malloc()]. The
8614 ** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because
8665 ** and the highest instantaneous value is written into *pHiwtr. ^If
8669 ** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a
8670 ** non-zero [error code] on failure.
8672 ** See also: [sqlite3_status()] and [sqlite3_stmt_status()].
8674 SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
8686 ** The [sqlite3_db_status()] interface will return a non-zero error code
8696 ** satisfied using lookaside memory. Only the high-water value is meaningful;
8704 ** Only the high-water value is meaningful;
8712 ** Only the high-water value is meaningful;
8735 ** with the connection - main, temp, and any [ATTACH]-ed databases.)^
8743 ** and lookaside memory used by all prepared statements associated with
8775 ** to disk all at once. When pages spill mid-transaction, that introduces
8781 ** <dd>This parameter returns zero for the current value if and only if
8816 ** ^(This interface is used to retrieve and reset counter values from
8825 ** See also: [sqlite3_status()] and [sqlite3_db_status()].
8827 SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
8834 ** values associated with the [sqlite3_stmt_status()] interface.
8846 ** A non-zero value in this counter may indicate an opportunity to
8852 ** A non-zero value in this counter may indicate an opportunity to
8881 ** step was bypassed because a Bloom filter returned not-found. The
8883 ** times that the Bloom filter returned a find, and thus the join step
8889 ** a counter, and so the resetFlg parameter to sqlite3_stmt_status()
8909 ** its size or internal structure and never deals with the
8910 ** sqlite3_pcache object except by holding and passing pointers
8945 ** that memory is allocated and released, and the policies used to
8946 ** determine exactly which parts of a database file are cached and for
8951 ** The built-in page cache is recommended for most uses.
8966 ** built-in default page cache is used instead of the application defined
8995 ** on the SQLite version, the target platform, and how SQLite was compiled.
8998 ** false if it is used for an in-memory database. The cache implementation
9009 ** suggested maximum cache-size (number of pages stored by) the cache
9017 ** stored in the cache, both pinned and unpinned.
9020 ** The xFetch() method locates a page in the cache and returns a pointer to
9041 ** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
9051 ** pinned pages to disk and synching the operating system disk cache.
9055 ** as its second argument. If the third parameter, discard, is non-zero,
9083 ** handle invalid, and will not use it with any other sqlite3_pcache_methods2
9089 ** is not obligated to free any memory, but well-behaved implementations should
9094 int iVersion;
9096 int (*xInit)(void*);
9098 sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable);
9099 void (*xCachesize)(sqlite3_pcache*, int nCachesize);
9100 int (*xPagecount)(sqlite3_pcache*);
9101 sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
9102 void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard);
9118 int (*xInit)(void*);
9120 sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable);
9121 void (*xCachesize)(sqlite3_pcache*, int nCachesize);
9122 int (*xPagecount)(sqlite3_pcache*);
9123 void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
9124 void (*xUnpin)(sqlite3_pcache*, void*, int discard);
9136 ** a call to [sqlite3_backup_init()] and is destroyed by a call to
9148 ** for copying in-memory databases to or from persistent files.
9154 ** ^The source database is read-locked only while it is being read;
9165 ** the data between the two databases, and finally
9174 ** ^The D and N arguments to sqlite3_backup_init(D,N,S,M) are the
9176 ** and the database name, respectively.
9180 ** ^The S and M arguments passed to
9182 ** and database name of the source database, respectively.
9183 ** ^The source and destination [database connections] (parameters S and D)
9188 ** there is already a read or read-write transaction open on the
9192 ** returned and an error code and error message are stored in the
9194 ** ^The error code and message for the failed call to sqlite3_backup_init()
9195 ** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or
9199 ** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and
9206 ** the source and destination databases specified by [sqlite3_backup] object B.
9208 ** ^If sqlite3_backup_step(B,N) successfully copies N pages and there
9213 ** then an [error code] is returned. ^As well as [SQLITE_OK] and
9220 ** <li> the destination database was opened read-only, or
9221 ** <li> the destination database is using write-ahead-log journaling
9222 ** and the destination and source page sizes differ, or
9223 ** <li> the destination database is an in-memory database and the
9224 ** destination and source page sizes differ.
9227 ** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
9228 ** the [sqlite3_busy_handler | busy-handler function]
9230 ** busy-handler returns non-zero before the lock is available, then
9241 ** that the backup operation has failed and pass the backup operation handle
9247 ** and sqlite3_backup_step() returns [SQLITE_DONE]. ^Every call to
9251 ** sqlite3_backup_step(), the source database may be modified mid-way
9268 ** active write-transaction on the destination database is rolled back.
9270 ** and may not be used following a call to sqlite3_backup_finish().
9275 ** ^If an out-of-memory condition or IO error occurred during any prior
9280 ** is not a permanent error and does not affect the return value of
9284 ** <b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b>
9291 ** ^(The values returned by these functions are only updated by
9295 ** and sqlite3_backup_remaining() until after the next
9302 ** ^If SQLite is compiled and configured to support threadsafe database
9308 ** sqlite3_backup_init() is called and before the corresponding call to
9311 ** and so no error code is reported, but the operations may malfunction
9324 ** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
9327 ** possible that they return invalid values.
9335 SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage);
9336 SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p);
9337 SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
9338 SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
9344 ** ^When running in shared-cache mode, a database operation may fail with
9345 ** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
9346 ** individual tables within the shared-cache cannot be obtained. See
9347 ** [SQLite Shared-Cache Mode] for a description of shared-cache locking.
9351 ** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
9355 ** ^Shared-cache locks are released when a database connection concludes
9359 ** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
9369 ** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
9375 ** ^If the blocked connection is attempting to obtain a write-lock on a
9376 ** shared-cache table, and more than one other connection currently holds
9377 ** a read-lock on the same table, then SQLite arbitrarily selects one of
9380 ** ^(There may be at most one unlock-notify callback registered by a
9382 ** blocked connection already has a registered unlock-notify callback,
9385 ** unlock-notify callback is canceled. ^The blocked connections
9386 ** unlock-notify callback may also be canceled by closing the blocked
9389 ** The unlock-notify callback is not reentrant. If an application invokes
9390 ** any sqlite3_xxx API functions from within an unlock-notify callback, a
9398 ** When an unlock-notify callback is registered, the application provides a
9401 ** it an array of void* context pointers. The first argument passed to
9402 ** an unlock-notify callback is a pointer to an array of void* pointers,
9403 ** and the second is the number of entries in the array.
9406 ** more than one blocked connection that has registered for an unlock-notify
9410 ** specified by the blocked connections bundled together into an array.
9416 ** Assuming that after registering for an unlock-notify callback a
9420 ** connection Y's transaction to be concluded, and similarly connection
9422 ** will proceed and the system may remain deadlocked indefinitely.
9426 ** system in a deadlocked state, then SQLITE_LOCKED is returned and no
9427 ** unlock-notify callback is registered. The system is said to be in
9428 ** a deadlocked state if connection A has registered for an unlock-notify
9429 ** callback on the conclusion of connection B's transaction, and connection
9430 ** B has itself registered for an unlock-notify callback when connection
9433 ** registered for an unlock-notify callback on the conclusion of connection
9445 ** sqlite3_unlock_notify() results in the unlock-notify callback being
9446 ** invoked immediately. If the application then re-attempts the "DROP TABLE"
9455 SQLITE_API int sqlite3_unlock_notify(
9457 void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */
9465 ** ^The [sqlite3_stricmp()] and [sqlite3_strnicmp()] APIs allow applications
9466 ** and extensions to compare the contents of two buffers containing UTF-8
9467 ** strings in a case-independent fashion, using the same definition of "case
9470 SQLITE_API int sqlite3_stricmp(const char *, const char *);
9471 SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
9476 ** ^The [sqlite3_strglob(P,X)] interface returns zero if and only if
9483 ** Note that this routine returns zero on a match and non-zero if the strings
9484 ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
9488 SQLITE_API int sqlite3_strglob(const char *zGlob, const char *zStr);
9493 ** ^The [sqlite3_strlike(P,X,E)] interface returns zero if and only if
9500 ** insensitive - equivalent upper and lower case ASCII characters match
9506 ** Note that this routine returns zero on a match and non-zero if the strings
9507 ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
9511 SQLITE_API int sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc);
9518 ** ^If logging is enabled, the zFormat string and subsequent arguments are
9522 ** virtual tables, collating functions, and SQL functions. While there is
9528 ** To avoid deadlocks and other threading problems, the sqlite3_log() routine
9530 ** a fixed-length buffer on the stack. If the log message is longer than
9531 ** a few hundred characters, it will be truncated to the length of the
9534 SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
9537 ** CAPI3REF: Write-Ahead Log Commit Hook
9543 ** ^(The callback is invoked by SQLite after the commit has taken place and
9544 ** the associated write-lock on the database released)^, so the implementation
9550 ** ^The third parameter is the name of the database that was written to -
9551 ** either "main" or the name of an [ATTACH]-ed database. ^The fourth parameter
9552 ** is the number of pages currently in the write-ahead log file,
9563 ** A single database handle may have at most a single write-ahead log callback
9565 ** previously registered write-ahead log callback. ^The return value is
9567 ** ^Note that the [sqlite3_wal_autocheckpoint()] interface and the
9568 ** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will
9573 int(*)(void *,sqlite3*,const char*,int),
9578 ** CAPI3REF: Configure an auto-checkpoint
9585 ** more frames in the [write-ahead log] file. ^Passing zero or
9600 ** ^Every new [database connection] defaults to having the auto-checkpoint
9606 SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
9616 ** [write-ahead log] for database X on [database connection] D to be
9617 ** transferred into the database file and for the write-ahead log to
9622 ** occur. But then the newer and more powerful [sqlite3_wal_checkpoint_v2()]
9624 ** compatibility and as a convenience for applications that need to manually
9625 ** start a callback but which do not need the full power (and corresponding
9628 SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
9636 ** information is written back into integers pointed to by L and C.)^
9643 ** in the log were checkpointed. ^The [busy-handler callback]
9650 ** [sqlite3_busy_handler|busy-handler callback]) until there is no
9651 ** database writer and all readers are reading from the most recent database
9652 ** snapshot. ^It then checkpoints all frames in the log file and syncs the
9659 ** [busy-handler callback])
9672 ** the log file or to -1 if the checkpoint could not run because
9676 ** was called) or to -1 if the checkpoint could not run due to an error or
9679 ** truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.
9683 ** lock cannot be obtained and SQLITE_BUSY is returned. ^Even if there is a
9684 ** busy-handler configured, it will not be invoked in this case.
9686 ** ^The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the
9688 ** obtained immediately, and a busy-handler is configured, it is invoked and
9689 ** the writer lock retried until either the busy-handler returns 0 or the lock
9690 ** is successfully obtained. ^The busy-handler is also invoked while waiting for
9691 ** database readers as described above. ^If the busy-handler returns 0 before
9694 ** SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
9697 ** ^If parameter zDb is NULL or points to a zero length string, then the
9700 ** values written to output parameters *pnLog and *pnCkpt are undefined. ^If
9703 ** attached databases and SQLITE_BUSY is returned at the end. ^If any other
9705 ** and the error code is returned to the caller immediately. ^If no error
9710 ** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. ^If
9711 ** zDb is not NULL (or a zero length string) and is not the name of any
9717 ** [sqlite3_errcode()] and [sqlite3_errmsg()].
9722 SQLITE_API int sqlite3_wal_checkpoint_v2(
9725 int eMode, /* SQLITE_CHECKPOINT_* value */
9726 int *pnLog, /* OUT: Size of WAL log in frames */
9727 int *pnCkpt /* OUT: Total number of frames checkpointed */
9731 ** CAPI3REF: Checkpoint Mode Values
9734 ** These constants define all valid values for the "checkpoint mode" passed
9755 ** [database connection] in which the virtual table is being created and
9758 ** of the [virtual table configuration options]. The presence and meaning
9762 SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...);
9771 ** can use to customize and optimize their behavior.
9786 ** If X is non-zero, then the virtual table implementation guarantees
9790 ** is able to roll back a statement or database transaction, and abandon
9792 ** If the ON CONFLICT mode is REPLACE and the [xUpdate] method returns
9800 ** silently replace the appropriate rows within the xUpdate callback and
9810 ** prohibits that virtual table from being used from within triggers and
9819 ** and views. Conceptually, the SQLITE_VTAB_INNOCUOUS tag means that the
9830 ** all schemas ("main", "temp", and any ATTACH-ed databases) whenever the
9850 SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *);
9860 ** expensive to compute and that the corresponding
9861 ** [xUpdate] method understands as a "no-change" value.
9863 ** If the [xColumn] method calls sqlite3_vtab_nochange() and finds that
9876 SQLITE_API int sqlite3_vtab_nochange(sqlite3_context*);
9889 ** must be an index into the aConstraint[] array belonging to the
9911 SQLITE_API const char *sqlite3_vtab_collation(sqlite3_index_info*,int);
9919 ** interface from outside of xBestIndex() is undefined and probably harmful.
9921 ** ^The sqlite3_vtab_distinct() interface returns an integer between 0 and
9931 ** sort order defined by the "nOrderBy" and "aOrderBy" fields of the
9939 ** as long as all rows with the same values in all columns identified by the
9945 ** order, as long as rows with the same values in all columns identified
9947 ** contain the same values for all columns identified by "colUsed", all but
9957 ** two or more rows in the result have the same values for all columns
9964 ** that have both DISTINCT and ORDER BY clauses.
9984 ** ^For the purposes of comparing virtual table output values to see if the
9985 ** values are same value for sorting purposes, two NULL values are considered
9987 ** (or "IS NOT DISTINCT FROM") and not "==".
9997 ** ordered correctly. The use of the "orderByConsumed" flag and the
9999 ** use of the sqlite3_vtab_distinct() interface and the "orderByConsumed"
10001 ** overly aggressive and setting the "orderByConsumed" flag when it is not
10005 SQLITE_API int sqlite3_vtab_distinct(sqlite3_index_info*);
10008 ** CAPI3REF: Identify and handle IN constraints in xBestIndex
10013 ** undefined and probably harmful.
10023 ** on the right-hand side of the IN operator.)^ Thus the virtual table
10024 ** only sees a single value from the right-hand side of the IN operator
10028 ** table to see all values on the right-hand of the IN operator all at
10033 ** ^A call to sqlite3_vtab_in(P,N,-1) will return true (non-zero)
10034 ** if and only if the [sqlite3_index_info|P->aConstraint][N] constraint
10036 ** sqlite3_vtab_in() with -1 in the third argument is a mechanism
10037 ** by which the virtual table can ask SQLite if all-at-once processing
10043 ** the IN operator all-at-once, respectively. ^Thus when the third
10044 ** parameter (F) is non-negative, this interface is the mechanism by
10053 ** (non-zero), that means that the constraint is an IN operator
10054 ** that can be processed all-at-once. ^If the constraint is not an IN
10055 ** operator or cannot be processed all-at-once, then the interface returns
10058 ** ^(All-at-once processing of the IN operator is selected if both of the
10062 ** <li><p> The P->aConstraintUsage[N].argvIndex value is set to a positive
10064 ** use the N-th constraint.
10067 ** non-negative had F>=1.
10071 ** the traditional one-at-a-time processing strategy for the IN constraint.
10072 ** ^If both conditions are true, then the argvIndex-th parameter to the
10074 ** but which can be passed to [sqlite3_vtab_in_first()] and
10075 ** [sqlite3_vtab_in_next()] to find all values on the right-hand side
10078 SQLITE_API int sqlite3_vtab_in(sqlite3_index_info*, int iCons, int bHandle);
10081 ** CAPI3REF: Find all elements on the right-hand side of an IN constraint.
10086 ** is undefined and probably harmful.
10090 ** xFilter method which invokes these routines, and specifically
10091 ** a parameter that was previously selected for all-at-once IN constraint
10094 ** an xFilter argument that was selected for all-at-once IN constraint
10097 ** ^(Use these routines to access all values on the right-hand side
10112 ** ^On success, the sqlite3_vtab_in_first(X,P) and sqlite3_vtab_in_next(X,P)
10113 ** routines return SQLITE_OK and set *P to point to the first or next value
10114 ** on the RHS of the IN constraint. ^If there are no more values on the
10115 ** right hand side of the IN constraint, then *P is set to NULL and these
10119 ** The *ppOut values returned by these routines are only valid until the
10122 ** implementation needs to retain the *ppOut values for longer, it must make
10123 ** copies. The *ppOut values are [protected sqlite3_value|protected].
10125 SQLITE_API int sqlite3_vtab_in_first(sqlite3_value *pVal, sqlite3_value **ppOut);
10126 SQLITE_API int sqlite3_vtab_in_next(sqlite3_value *pVal, sqlite3_value **ppOut);
10129 ** CAPI3REF: Constraint values in xBestIndex()
10134 ** from outside of an xBestIndex method are undefined and probably harmful.
10138 ** a copy of the [sqlite3_index_info] object pointer passed into xBestIndex and
10139 ** J being a 0-based index into P->aConstraint[], then this routine
10140 ** attempts to set *V to the value of the right-hand operand of
10141 ** that constraint if the right-hand operand is known. ^If the
10142 ** right-hand operand is not known, then *V is set to a NULL pointer.
10144 ** and only if *V is set to a value. ^The sqlite3_vtab_rhs_value(P,J,V)
10145 ** inteface returns SQLITE_NOTFOUND if the right-hand side of the J-th
10151 ** the right-hand operand of a constraint is a literal value in the original
10152 ** SQL statement. If the right-hand operand is an expression or a reference
10156 ** ^(Some constraints, such as [SQLITE_INDEX_CONSTRAINT_ISNULL] and
10157 ** [SQLITE_INDEX_CONSTRAINT_ISNOTNULL], have no right-hand operand. For such
10161 ** and remains valid for the duration of the xBestIndex method call.
10166 ** "Right-Hand Side".
10168 SQLITE_API int sqlite3_vtab_rhs_value(sqlite3_index_info*, int, sqlite3_value **ppVal);
10179 ** return value from the [sqlite3_set_authorizer()] callback and that
10197 ** managed by the prepared statement S and will be automatically freed when
10200 ** Not all values are available for all query elements. When a value is
10201 ** not available, the output variable is set to -1 if the value is numeric,
10206 ** <dd>^The [sqlite3_int64] variable pointed to by the V parameter will be
10207 ** set to the total number of times that the X-th loop has run.</dd>
10210 ** <dd>^The [sqlite3_int64] variable pointed to by the V parameter will be set
10211 ** to the total number of rows examined by all iterations of the X-th loop.</dd>
10214 ** <dd>^The "double" variable pointed to by the V parameter will be set to the
10216 ** iteration of the X-th loop. If the query planner's estimates was accurate,
10217 ** then this value will approximate the quotient NVISIT/NLOOP and the
10222 ** <dd>^The "const char *" variable pointed to by the V parameter will be set
10223 ** to a zero-terminated UTF-8 string containing the name of the index or table
10224 ** used for the X-th loop.
10227 ** <dd>^The "const char *" variable pointed to by the V parameter will be set
10228 ** to a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN]
10229 ** description for the X-th loop.
10232 ** <dd>^The "int" variable pointed to by the V parameter will be set to the
10233 ** id for the X-th query plan element. The id value is unique within the
10234 ** statement. The select-id is the same value as is output in the first
10238 ** <dd>The "int" variable pointed to by the V parameter will be set to the
10245 ** according to the processor time-stamp counter, that elapsed while the
10247 ** all query elements - if it is unavailable the output variable is
10248 ** set to -1.
10264 ** These interfaces return information about the predicted and measured
10266 ** interface to compare the predicted and the measured performance and
10267 ** issue warnings and/or rerun [ANALYZE] if discrepancies are found.
10271 ** compile-time option.
10276 ** a variable pointed to by the "pOut" parameter.
10279 ** one flag is defined - SQLITE_SCANSTAT_COMPLEX. If SQLITE_SCANSTAT_COMPLEX
10283 ** that correspond to query loops (the "SCAN..." and "SEARCH..." elements of
10289 ** for. Query elements are numbered starting from zero. A value of -1 may be
10291 ** - less than -1 or greater than or equal to the total number of query
10292 ** elements used to implement the statement - a non-zero value is returned and
10293 ** the variable that pOut points to is unchanged.
10297 SQLITE_API int sqlite3_stmt_scanstatus(
10299 int idx, /* Index of loop to report on */
10300 int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */
10303 SQLITE_API int sqlite3_stmt_scanstatus_v2(
10305 int idx, /* Index of loop to report on */
10306 int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */
10307 int flags, /* Mask of flags defined below */
10318 ** CAPI3REF: Zero Scan-Status Counters
10323 ** This API is only available if the library is built with pre-processor
10329 ** CAPI3REF: Flush caches to disk mid-transaction
10332 ** ^If a write-transaction is open on [database connection] D when the
10334 ** pages in the pager-cache that are not currently in use are written out
10338 ** interface flushes caches for all schemas - "main", "temp", and
10343 ** immediately and there is a busy-handler callback configured, it is invoked
10345 ** the database is skipped and an attempt made to flush any dirty pages
10351 ** example an IO error or out-of-memory condition), then processing is
10352 ** abandoned and an SQLite [error code] is returned to the caller immediately.
10357 ** returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions.
10359 SQLITE_API int sqlite3_db_cacheflush(sqlite3*);
10362 ** CAPI3REF: The pre-update hook.
10366 ** [SQLITE_ENABLE_PREUPDATE_HOOK] compile-time option.
10369 ** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation
10411 ** [sqlite3_preupdate_count()], and [sqlite3_preupdate_depth()] interfaces
10416 ** to the preupdate callback results in undefined and probably undesirable
10425 ** and one less than the number of columns or the behavior will be
10426 ** undefined. This must only be used within SQLITE_UPDATE and SQLITE_DELETE
10434 ** and one less than the number of columns or the behavior will be
10435 ** undefined. This must only be used within SQLITE_INSERT and SQLITE_UPDATE
10442 ** operation; or 1 for inserts, updates, or deletes invoked by top-level
10443 ** triggers; or 2 for changes resulting from triggers called by top-level
10444 ** triggers; and so forth.
10447 ** the pre-update hook is invoked with SQLITE_DELETE. This is because the
10448 ** in this case the new values are not available. In this case, when a
10452 ** pre-update hook is being invoked for some other reason, including a
10453 ** regular DELETE, sqlite3_preupdate_blobwrite() returns -1.
10463 int op, /* SQLITE_UPDATE, DELETE or INSERT */
10471 SQLITE_API int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **);
10472 SQLITE_API int sqlite3_preupdate_count(sqlite3 *);
10473 SQLITE_API int sqlite3_preupdate_depth(sqlite3 *);
10474 SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);
10475 SQLITE_API int sqlite3_preupdate_blobwrite(sqlite3 *);
10479 ** CAPI3REF: Low-level system error code
10484 ** The return value is OS-dependent. For example, on unix systems, after
10487 ** as ENOSPC, EAUTH, EISDIR, and so forth.
10489 SQLITE_API int sqlite3_system_errno(sqlite3*);
10523 ** created [sqlite3_snapshot] object into *P and returns SQLITE_OK.
10524 ** If there is not already a read-transaction open on schema S when
10556 ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
10558 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_get(
10590 ** is returned. If another error code - for example SQLITE_PROTOCOL or an
10591 ** SQLITE_IOERR error code - is returned, then the final state of the
10605 ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
10607 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_open(
10622 ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
10646 ** snapshot, and a positive value if P1 is a newer snapshot than P2.
10651 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp(
10663 ** calling [sqlite3_close()]) and a new connection is subsequently opened
10664 ** on that database and [WAL file], the [sqlite3_snapshot_open()] interface
10669 ** of database handle db and make all valid snapshots available to
10679 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb);
10689 ** For an ordinary on-disk database file, the serialization is just a
10690 ** copy of the disk file. For an in-memory database or a "TEMP" database,
10695 ** the database into memory obtained from [sqlite3_malloc64()] and returns
10699 ** are made, and the sqlite3_serialize() function will return a pointer
10705 ** values of D and S.
10711 ** the returned buffer content will remain accessible and unchanged
10713 ** the connection is closed, and applications must not modify the
10728 unsigned int mFlags /* Zero or more SQLITE_SERIALIZE_* flags */
10734 ** Zero or more of the following constants can be OR-ed together for
10738 ** a pointer to contiguous in-memory database that it is currently using,
10740 ** a contiguous in-memory database, then this option causes
10742 ** using a contiguous in-memory database if it has been initialized by a
10751 ** [database connection] D to disconnect from database S and then
10752 ** reopen S as an in-memory database based on the serialization contained
10754 ** the buffer P, which might be larger than N. If M is larger than N, and
10756 ** permitted to add content to the in-memory database as long as the total
10779 ** [file format version numbers] (bytes 18 and 19) of the input database P
10781 ** database file into rollback mode and work around this limitation.
10783 ** If sqlite3_deserialize(D,S,P,N,M,F) fails for any reason and if the
10790 SQLITE_API int sqlite3_deserialize(
10802 ** The following are allowed values for 6th argument (the F argument) to
10807 ** and that SQLite should take ownership of this memory and automatically
10818 ** should be treated as read-only.
10822 #define SQLITE_DESERIALIZE_READONLY 4 /* Database is read-only */
10857 ** May you do good and not evil.
10858 ** May you find forgiveness for yourself and forgive others.
10875 /* The double-precision datatype used by RTree depends on the
10876 ** SQLITE_RTREE_INT_ONLY compile-time option.
10886 ** R-Tree geometry query as follows:
10890 SQLITE_API int sqlite3_rtree_geometry_callback(
10893 int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*),
10904 int nParam; /* Size of array aParam[] */
10911 ** Register a 2nd-generation geometry callback named zScore that can be
10912 ** used as part of an R-Tree geometry query as follows:
10916 SQLITE_API int sqlite3_rtree_query_callback(
10919 int (*xQueryFunc)(sqlite3_rtree_query_info*),
10936 int nParam; /* Number of function parameters */
10941 unsigned int *anQueue; /* Number of pending entries in the queue */
10942 int nCoord; /* Number of coordinates */
10943 int iLevel; /* Level of current node or entry */
10944 int mxLevel; /* The largest iLevel value in the tree */
10947 int eParentWithin; /* Visibility of parent node */
10948 int eWithin; /* OUT: Visibility */
10950 /* The following fields are only available in 3.8.11 and later */
10951 sqlite3_value **apSqlParam; /* Original SQL values of parameters */
10955 ** Allowed values for sqlite3_rtree_query.eWithin and .eParentWithin.
11003 ** a pointer to the new object is written to *ppSession and SQLITE_OK is
11004 ** returned. If an error occurs, *ppSession is set to NULL and an SQLite
11018 ** is not possible for an application to register a pre-update hook on a
11021 ** which a pre-update hook is already defined. The results of attempting
11029 SQLITE_API int sqlite3session_create(
11055 ** created. At present the only valid values for the second parameter are
11056 ** [SQLITE_SESSION_OBJCONFIG_SIZE] and [SQLITE_SESSION_OBJCONFIG_ROWID].
11059 SQLITE_API int sqlite3session_object_config(sqlite3_session*, int op, void *pArg);
11064 ** The following values may passed as the the 2nd parameter to
11071 ** pArg must point to a value of type (int). If the value is initially
11074 ** value is less than zero, no change is made. In all cases the (int)
11075 ** variable is set to 1 if the sqlite3session_changeset_size() API is
11102 ** disabled - it does not. A newly created session object is enabled.
11104 ** details regarding how enabling and disabling a session object affects
11109 ** no-op, and may be used to query the current state of the session.
11114 SQLITE_API int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
11138 ** of the indirect flag, and may be used to query the current state of the
11144 SQLITE_API int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect);
11169 ** Changes are not recorded for individual rows that have NULL values stored
11186 ** rows a zero-length blob (SQL value X'') is stored in the changeset or
11189 ** concat() and similar.
11192 ** zero-length blob back to a NULL value when updating the sqlite_stat1
11196 ** conflict-handler callback) then the X'' value is returned. The application
11204 SQLITE_API int sqlite3session_attach(
11221 int(*xFilter)(
11235 ** and *pnChangeset to the size of the changeset in bytes before returning
11236 ** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
11237 ** zero and return an SQLite error code.
11239 ** A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes,
11241 ** change contains the values of each field of a new database row. A DELETE
11242 ** contains the original values of each field of a deleted database row. An
11243 ** UPDATE change contains the original values of each field of an updated
11244 ** database row along with the updated values for each updated non-primary-key
11246 ** modifies the values of primary key columns. If such a change is made, it
11249 ** Changes are not recorded for rows that have NULL values stored in one or
11252 ** function. If an existing row with one or more NULL values stored in
11253 ** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,
11255 ** with non-NULL PRIMARY KEY values is updated so that one or more of its
11268 ** are sorted in the same order in which they were attached (or auto-attached)
11279 ** records the primary key values of all new rows inserted into the table.
11280 ** It also records the original primary key and other column values of any
11282 ** recorded once - the first time a row with said primary key is inserted,
11289 ** The session object therefore accumulates two types of records - those
11290 ** that consist of primary key values only (created when the user inserts
11291 ** a new record) and those that consist of the primary key values and the
11292 ** original values of other table columns (created when the users deletes
11296 ** both the accumulated records and the current contents of the database
11307 ** found and one or more of the non-primary key fields have been
11308 ** modified from their original values, an UPDATE change is added to
11312 ** values, no change is added to the changeset.
11315 ** This means, amongst other things, that if a row is inserted and then later
11317 ** will be present in the changeset. Or if a row is deleted and then later a
11318 ** row with the same primary key values inserted while a session object is
11320 ** a DELETE and an INSERT.
11324 ** This may appear to have some counter-intuitive effects if a single row
11329 ** Or, if one field of a row is updated while a session is disabled, and
11333 SQLITE_API int sqlite3session_changeset(
11335 int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */
11340 ** CAPI3REF: Return An Upper-limit For The Size Of The Changeset
11362 ** does not have a primary key, this function is a no-op (but does not return
11372 ** <li> Has the same set of columns declared in the same order, and
11382 ** used to update the table in database zFrom (call this the "from-table")
11384 ** object (call this the "to-table"). Specifically:
11387 ** <li> For each row (primary key) that exists in the to-table but not in
11388 ** the from-table, an INSERT record is added to the session object.
11390 ** <li> For each row (primary key) that exists in the to-table but not in
11391 ** the from-table, a DELETE record is added to the session object.
11394 ** different non-PK values in each, an UPDATE record is added to the
11398 ** To clarify, if this function is called and then a changeset constructed
11412 SQLITE_API int sqlite3session_diff(
11424 ** The differences between a patchset and a changeset are that:
11428 ** original values of other fields are omitted.
11429 ** <li> The original values of any modified fields are omitted from
11439 ** Because the non-primary key "old.*" fields are omitted, no
11449 SQLITE_API int sqlite3session_patchset(
11451 int *pnPatchset, /* OUT: Size of buffer at *ppPatchset */
11458 ** Return non-zero if no changes to attached tables have been recorded by
11465 ** an attached table is modified and then later on the original values
11466 ** are restored. However, if this function returns non-zero, then it is
11470 SQLITE_API int sqlite3session_isempty(sqlite3_session *pSession);
11485 ** If successful, *pp is set to point to the iterator handle and SQLITE_OK
11486 ** is returned. Otherwise, if an error occurs, *pp is set to zero and an
11489 ** The following functions can be used to advance and query a changeset
11511 ** the applies to table X, then one for table Y, and then later on visit
11514 ** The behavior of sqlite3changeset_start_v2() and its streaming equivalent
11519 ** and therefore subject to change.
11521 SQLITE_API int sqlite3changeset_start(
11523 int nChangeset, /* Size of changeset blob in bytes */
11526 SQLITE_API int sqlite3changeset_start_v2(
11528 int nChangeset, /* Size of changeset blob in bytes */
11530 int flags /* SESSION_CHANGESETSTART_* flags */
11537 ** [sqlite3changeset_start_v2] and [sqlite3changeset_start_v2_strm]:
11553 ** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE
11554 ** is returned and the call has no effect.
11561 ** no error occurs and the iterator points to a valid change after a call
11570 SQLITE_API int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
11577 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
11582 ** Arguments pOp, pnCol and pzTab may not be NULL. Upon return, three
11588 ** *pnCol is set to the number of columns in the table affected by the change; and
11590 ** *pzTab is set to point to a nul-terminated utf-8 encoded string containing
11593 ** or until the conflict-handler function returns.
11597 ** [sqlite3session_indirect()] for a description of direct and indirect
11601 ** SQLite error code is returned. The values of the output variables may not
11604 SQLITE_API int sqlite3changeset_op(
11607 int *pnCol, /* OUT: Number of columns in table */
11608 int *pOp, /* OUT: SQLITE_INSERT, DELETE or UPDATE */
11609 int *pbIndirect /* OUT: True for an 'indirect' change */
11619 ** <li> The number of columns in the table, and
11625 ** If successful, *pabPK is set to point to an array of nCol entries, where
11634 ** entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise,
11635 ** SQLITE_OK is returned and the output variables populated as described
11638 SQLITE_API int sqlite3changeset_pk(
11640 unsigned char **pabPK, /* OUT: Array of boolean - true for PK cols */
11641 int *pnCol /* OUT: Number of entries in output array */
11645 ** CAPI3REF: Obtain old.* Values From A Changeset Iterator
11649 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
11654 ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
11656 ** Argument iVal must be greater than or equal to 0, and less than the number
11658 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
11662 ** original row values stored as part of the UPDATE or DELETE change and
11667 ** is returned and *ppValue is set to NULL.
11669 SQLITE_API int sqlite3changeset_old(
11671 int iVal, /* Column number */
11676 ** CAPI3REF: Obtain new.* Values From A Changeset Iterator
11680 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
11685 ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
11687 ** Argument iVal must be greater than or equal to 0, and less than the number
11689 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
11693 ** new row values stored as part of the UPDATE or INSERT change and
11694 ** returns SQLITE_OK. If the change is an UPDATE and does not include
11695 ** a new value for the requested column, *ppValue is set to NULL and
11701 ** is returned and *ppValue is set to NULL.
11703 SQLITE_API int sqlite3changeset_new(
11705 int iVal, /* Column number */
11710 ** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator
11714 ** conflict-handler callback by [sqlite3changeset_apply()] with either
11716 ** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue
11719 ** Argument iVal must be greater than or equal to 0, and less than the number
11721 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
11725 ** "conflicting row" associated with the current conflict-handler callback
11726 ** and returns SQLITE_OK.
11729 ** is returned and *ppValue is set to NULL.
11731 SQLITE_API int sqlite3changeset_conflict(
11733 int iVal, /* Column number */
11743 ** it sets the output variable to the total number of known foreign key
11744 ** violations in the destination database and returns SQLITE_OK.
11748 SQLITE_API int sqlite3changeset_fk_conflicts(
11750 int *pnOut /* OUT: Number of FK violations */
11763 ** function with an iterator passed to a conflict-handler by
11764 ** [sqlite3changeset_apply()], [SQLITE_MISUSE] is immediately returned and the
11771 ** returned. This is to allow the following pattern (pseudo-code):
11784 SQLITE_API int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
11794 ** <li> Each DELETE change is changed to an INSERT, and
11795 ** <li> Each INSERT change is changed to a DELETE, and
11796 ** <li> For each UPDATE change, the old.* and new.* values are exchanged.
11803 ** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and
11804 ** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are
11805 ** zeroed and an SQLite error code returned.
11814 SQLITE_API int sqlite3changeset_invert(
11815 int nIn, const void *pIn, /* Input changeset */
11816 int *pnOut, void **ppOut /* OUT: Inverse of input */
11822 ** This function is used to concatenate two changesets, A and B, into a
11845 SQLITE_API int sqlite3changeset_concat(
11846 int nA, /* Number of bytes in buffer pA */
11848 int nB, /* Number of bytes in buffer pB */
11850 int *pnOut, /* OUT: Number of bytes in output changeset */
11858 SQLITE_API int sqlite3changeset_upgrade(
11861 int nIn, const void *pIn, /* Input changeset */
11862 int *pnOut, void **ppOut /* OUT: Inverse of input */
11884 ** If successful, this function returns SQLITE_OK and populates (*pp) with
11888 ** (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL.
11904 ** Any number of calls to add() and output() may be made between the calls to
11905 ** new() and delete(), and in any order.
11907 ** As well as the regular sqlite3changegroup_add() and
11909 ** versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm().
11911 SQLITE_API int sqlite3changegroup_new(sqlite3_changegroup **pp);
11921 ** with the configured schema, SQLITE_SCHEMA is returned and the changegroup
11929 ** <li> The name identified by the changeset, and
11930 ** <li> at least as many columns as recorded in the changeset, and
11939 ** values from the database schema. This makes it possible to combined
11943 SQLITE_API int sqlite3changegroup_schema(sqlite3_changegroup*, sqlite3*, const char *zDb);
11955 ** function. Otherwise, SQLITE_ERROR is returned and no changes are added
11958 ** Rows within the changeset and changegroup are identified by the values in
11964 ** simply copied into it. Or, if both the new changeset and the changegroup
11968 ** <table border=1 style="margin-left:8ex;margin-right:8ex">
11969 ** <tr><th style="white-space:pre">Existing Change </th>
11970 ** <th style="white-space:pre">New Change </th>
11977 ** The INSERT change remains in the changegroup. The values in the
11979 ** existing change and then updated according to the new change.
11989 ** so that the accompanying values are as if the row was updated once
11990 ** by the existing change and then again by the new change.
11995 ** If one or more of the column values in the row inserted by the
12011 ** in the changegroup, then the number of columns and the position of the
12019 ** If the input changeset appears to be corrupt and the corruption is
12020 ** detected, SQLITE_CORRUPT is returned. Or, if an out-of-memory condition
12026 SQLITE_API int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData);
12040 ** If it does not, SQLITE_ERROR is returned and no change is added to the
12045 SQLITE_API int sqlite3changegroup_add_change(
12061 ** As with the output of the sqlite3session_changeset() and
12070 ** If an error occurs, an SQLite error code is returned and the output
12071 ** variables (*pnData) and (*ppData) are set to 0. Otherwise, SQLITE_OK
12072 ** is returned and the output variables are set to the size of and a
12077 SQLITE_API int sqlite3changegroup_output(
12079 int *pnData, /* OUT: Size of output buffer in bytes */
12094 ** the changeset passed via the second and third arguments.
12099 ** the table name as the second argument, and a copy of the context pointer
12102 ** Otherwise, if the return value is non-zero or the xFilter argument to
12111 ** changeset, and
12113 ** changeset, and
12138 ** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler
12139 ** returns an illegal value, any changes already made are rolled back and
12142 ** returned by each invocation of the conflict-handler function. Refer to
12144 ** [SQLITE_CHANGESET_OMIT|available return values] for details.
12149 ** contains a row with the same primary key value (or values) as the
12150 ** original row values stored in the changeset. If it does, and the values
12151 ** stored in all non-primary key columns also match the values stored in
12154 ** If a row with matching primary key values is found, but one or more of
12155 ** the non-primary key fields contains a value different from the original
12156 ** row value stored in the changeset, the conflict-handler function is
12159 ** only the values of those non-primary key fields are compared against
12160 ** the current database contents - any trailing database table columns
12163 ** If no row with matching primary key values is found in the database,
12164 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
12169 ** conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT]
12178 ** values.
12181 ** contains a row with the same primary key values, the conflict handler
12188 ** This includes the case where the INSERT operation is re-attempted because
12194 ** contains a row with the same primary key value (or values) as the
12195 ** original row values stored in the changeset. If it does, and the values
12196 ** stored in all modified non-primary key columns also match the values
12199 ** If a row with matching primary key values is found, but one or more of
12200 ** the modified non-primary key fields contains a value different from an
12201 ** original row value stored in the changeset, the conflict-handler function
12203 ** UPDATE changes only contain values for non-primary key fields that are
12204 ** to be modified, only those fields need to match the original values to
12205 ** avoid the SQLITE_CHANGESET_DATA conflict-handler callback.
12207 ** If no row with matching primary key values is found in the database,
12208 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
12212 ** SQLITE_CONSTRAINT, the conflict-handler function is invoked with
12227 ** rolled back, restoring the target database to its original state, and an
12230 ** If the output parameters (ppRebase) and (pnRebase) are non-NULL and
12236 ** is only allocated and populated if one or more conflicts were encountered
12240 ** The behavior of sqlite3changeset_apply_v2() and its streaming equivalent
12245 ** and therefore subject to change.
12247 SQLITE_API int sqlite3changeset_apply(
12249 int nChangeset, /* Size of changeset in bytes */
12251 int(*xFilter)(
12255 int(*xConflict)(
12257 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
12258 sqlite3_changeset_iter *p /* Handle describing change and conflict */
12262 SQLITE_API int sqlite3changeset_apply_v2(
12264 int nChangeset, /* Size of changeset in bytes */
12266 int(*xFilter)(
12270 int(*xConflict)(
12272 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
12273 sqlite3_changeset_iter *p /* Handle describing change and conflict */
12276 void **ppRebase, int *pnRebase, /* OUT: Rebase data */
12277 int flags /* SESSION_CHANGESETAPPLY_* flags */
12284 ** [sqlite3changeset_apply_v2] and [sqlite3changeset_apply_v2_strm]:
12309 ** their new values in the conflicting row, or
12328 ** Values that may be passed as the second argument to a conflict-handler.
12335 ** (non primary-key) fields modified by the update do not contain the
12336 ** expected "before" values.
12352 ** in duplicate primary key values.
12358 ** If foreign key handling is enabled, and applying a changeset leaves the
12389 ** A conflict handler callback must return one of the following three values.
12400 ** is not the case, any changes applied so far are rolled back and the
12408 ** handler, then the conflicting row is removed from the database and a
12414 ** and the call to sqlite3changeset_apply() returns SQLITE_ABORT.
12425 ** Suppose there is a site hosting a database in state S0. And that
12426 ** modifications are made that move that database to state S1 and a
12428 ** on S0 is received from another site (the "remote" changeset) and
12436 ** For example, if both the local and remote changesets contain an
12439 ** local: INSERT INTO t1 VALUES(1, 'v1');
12440 ** remote: INSERT INTO t1 VALUES(1, 'v2');
12442 ** and the conflict resolution is REPLACE, then the INSERT change is
12463 ** to reflect the new.* values in the UPDATE.
12467 ** with a DELETE, and the conflict resolution was OMIT, then the update
12468 ** is changed into an INSERT. Any undefined values in the new.* record
12469 ** from the update change are filled in using the old.* values from
12473 ** If conflict is with a remote UPDATE and the resolution is OMIT, then
12474 ** the old.* values are rebased using the new.* values in the remote
12496 ** combined on a per-field basis, not per-row. This means that in the
12502 ** be applied to the local database using sqlite3changeset_apply_v2() and
12526 ** point to the new object and return SQLITE_OK. Otherwise, if an error
12527 ** occurs, return an SQLite error code (e.g. SQLITE_NOMEM) and set (*ppNew)
12530 SQLITE_API int sqlite3rebaser_create(sqlite3_rebaser **ppNew);
12541 SQLITE_API int sqlite3rebaser_configure(
12543 int nRebase, const void *pRebase
12551 ** in size. This function allocates and populates a buffer with a copy
12554 ** is set to point to the new buffer containing the rebased changeset and
12555 ** (*pnOut) to its size in bytes and SQLITE_OK returned. It is the
12557 ** sqlite3_free(). Otherwise, if an error occurs, (*ppOut) and (*pnOut)
12558 ** are set to zero and an SQLite error code returned.
12560 SQLITE_API int sqlite3rebaser_rebase(
12562 int nIn, const void *pIn,
12563 int *pnOut, void **ppOut
12570 ** Delete the changeset rebaser object and all associated resources. There
12580 ** corresponding non-streaming API functions:
12582 ** <table border=1 style="margin-left:8ex;margin-right:8ex">
12583 ** <tr><th>Streaming function<th>Non-streaming equivalent</th>
12593 ** Non-streaming functions that accept changesets (or patchsets) as input
12598 ** low-memory environment is required to handle very large changesets, the
12607 ** int nChangeset,
12614 ** int (*xInput)(void *pIn, void *pData, int *pnData),
12622 ** into the buffer and set (*pnData) to the actual number of bytes copied
12626 ** an error, all processing is abandoned and the streaming API function
12641 ** int *pnChangeset,
12648 ** int (*xOutput)(void *pOut, const void *pData, int nData),
12659 ** is immediately abandoned and the streaming API function returns a copy
12666 SQLITE_API int sqlite3changeset_apply_strm(
12668 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
12670 int(*xFilter)(
12674 int(*xConflict)(
12676 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
12677 sqlite3_changeset_iter *p /* Handle describing change and conflict */
12681 SQLITE_API int sqlite3changeset_apply_v2_strm(
12683 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
12685 int(*xFilter)(
12689 int(*xConflict)(
12691 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
12692 sqlite3_changeset_iter *p /* Handle describing change and conflict */
12695 void **ppRebase, int *pnRebase,
12696 int flags
12698 SQLITE_API int sqlite3changeset_concat_strm(
12699 int (*xInputA)(void *pIn, void *pData, int *pnData),
12701 int (*xInputB)(void *pIn, void *pData, int *pnData),
12703 int (*xOutput)(void *pOut, const void *pData, int nData),
12706 SQLITE_API int sqlite3changeset_invert_strm(
12707 int (*xInput)(void *pIn, void *pData, int *pnData),
12709 int (*xOutput)(void *pOut, const void *pData, int nData),
12712 SQLITE_API int sqlite3changeset_start_strm(
12714 int (*xInput)(void *pIn, void *pData, int *pnData),
12717 SQLITE_API int sqlite3changeset_start_v2_strm(
12719 int (*xInput)(void *pIn, void *pData, int *pnData),
12721 int flags
12723 SQLITE_API int sqlite3session_changeset_strm(
12725 int (*xOutput)(void *pOut, const void *pData, int nData),
12728 SQLITE_API int sqlite3session_patchset_strm(
12730 int (*xOutput)(void *pOut, const void *pData, int nData),
12733 SQLITE_API int sqlite3changegroup_add_strm(sqlite3_changegroup*,
12734 int (*xInput)(void *pIn, void *pData, int *pnData),
12737 SQLITE_API int sqlite3changegroup_output_strm(sqlite3_changegroup*,
12738 int (*xOutput)(void *pOut, const void *pData, int nData),
12741 SQLITE_API int sqlite3rebaser_rebase_strm(
12743 int (*xInput)(void *pIn, void *pData, int *pnData),
12745 int (*xOutput)(void *pOut, const void *pData, int nData),
12763 ** interpretation of the (void*) value passed as the second parameter and
12770 ** and output data in approximately 1 KiB chunks. This operand may be used
12771 ** to set and query the value of this configuration setting. The pointer
12772 ** passed as the second argument must point to a value of type (int).
12774 ** chunk size for both input and output. Before returning, the (int) value
12782 SQLITE_API int sqlite3session_config(int op, void *pArg);
12785 ** CAPI3REF: Values for sqlite3session_config().
12806 ** May you do good and not evil.
12807 ** May you find forgiveness for yourself and forgive others.
12815 ** * custom tokenizers, and
12843 int nVal, /* Number of values in apVal[] array */
12844 sqlite3_value **apVal /* Array of trailing arguments */
12860 ** If parameter iCol is less than zero, set output variable *pnToken
12862 ** non-negative but less than the number of columns in the table, return
12875 ** If parameter iCol is less than zero, set output variable *pnToken
12877 ** non-negative but less than the number of columns in the table, set
12894 ** containing the text in utf-8 encoding, (*pn) is set to the size in bytes
12895 ** (not characters) of the buffer and SQLITE_OK is returned. Otherwise,
12896 ** if an error occurs, an SQLite error code is returned and the final values
12897 ** of (*pz) and (*pn) are undefined.
12915 ** with either "detail=none" or "detail=column" and "content=" option
12921 ** should be greater than or equal to zero and smaller than the value
12926 ** to the column in which it occurs and *piOff the token offset of the
12949 ** is invoked. The context and API objects passed to the callback
12959 ** query is abandoned and the xQueryPhrase function returns immediately.
12989 ** the auxiliary data is set to NULL and an error code returned. If the
12999 ** If the bClear argument is non-zero, then the auxiliary data is cleared
13012 ** This function is used, along with type Fts5PhraseIter and the xPhraseNext
13020 ** int iCol, iOff;
13021 ** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff);
13023 ** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff)
13029 ** modify this structure directly - it should only be used as shown above
13030 ** with the xPhraseFirst() and xPhraseNext() API methods (and by
13031 ** xPhraseFirstColumn() and xPhraseNextColumn() as illustrated below).
13035 ** with either "detail=none" or "detail=column" and "content=" option
13037 ** through an empty set (all calls to xPhraseFirst() set iCol to -1).
13043 ** This function and xPhraseNextColumn() are similar to the xPhraseFirst()
13044 ** and xPhraseNext() APIs described above. The difference is that instead
13050 ** int iCol;
13051 ** for(pApi->xPhraseFirstColumn(pFts, iPhrase, &iter, &iCol);
13053 ** pApi->xPhraseNextColumn(pFts, &iter, &iCol)
13062 ** xPhraseFirstColumn() set iCol to -1).
13064 ** The information accessed using this API and its companion
13076 ** to a buffer containing the requested token, and *pnToken to the
13082 ** tokens in the phrase, SQLITE_RANGE is returned and *ppToken and *pnToken
13087 ** tables, this includes any embedded 0x00 and trailing data.
13093 ** output variable (*ppToken) is set to point to a buffer containing the
13094 ** matching document token, and (*pnToken) to the size of that buffer in
13101 ** includes any embedded 0x00 and trailing data.
13107 int iVersion; /* Currently always set to 3 */
13111 int (*xColumnCount)(Fts5Context*);
13112 int (*xRowCount)(Fts5Context*, sqlite3_int64 *pnRow);
13113 int (*xColumnTotalSize)(Fts5Context*, int iCol, sqlite3_int64 *pnToken);
13115 int (*xTokenize)(Fts5Context*,
13116 const char *pText, int nText, /* Text to tokenize */
13118 int (*xToken)(void*, int, const char*, int, int, int) /* Callback */
13121 int (*xPhraseCount)(Fts5Context*);
13122 int (*xPhraseSize)(Fts5Context*, int iPhrase);
13124 int (*xInstCount)(Fts5Context*, int *pnInst);
13125 int (*xInst)(Fts5Context*, int iIdx, int *piPhrase, int *piCol, int *piOff);
13128 int (*xColumnText)(Fts5Context*, int iCol, const char **pz, int *pn);
13129 int (*xColumnSize)(Fts5Context*, int iCol, int *pnToken);
13131 int (*xQueryPhrase)(Fts5Context*, int iPhrase, void *pUserData,
13132 int(*)(const Fts5ExtensionApi*,Fts5Context*,void*)
13134 int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*));
13135 void *(*xGetAuxdata)(Fts5Context*, int bClear);
13137 int (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*);
13138 void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff);
13140 int (*xPhraseFirstColumn)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*);
13141 void (*xPhraseNextColumn)(Fts5Context*, Fts5PhraseIter*, int *piCol);
13144 int (*xQueryToken)(Fts5Context*,
13145 int iPhrase, int iToken,
13146 const char **ppToken, int *pnToken
13148 int (*xInstToken)(Fts5Context*, int iIdx, int iToken, const char**, int*);
13165 ** This function is used to allocate and initialize a tokenizer instance.
13171 ** The second and third arguments are an array of nul-terminated strings
13176 ** The final argument is an output variable. If successful, (*ppOut)
13177 ** should be set to point to the new tokenizer handle and SQLITE_OK
13189 ** by argument pText. pText may or may not be nul-terminated. The first
13195 ** four values:
13197 ** <ul><li> <b>FTS5_TOKENIZE_DOCUMENT</b> - A document is being inserted into
13202 ** <li> <b>FTS5_TOKENIZE_QUERY</b> - A MATCH query is being executed
13206 ** <li> <b>(FTS5_TOKENIZE_QUERY | FTS5_TOKENIZE_PREFIX)</b> - Same as
13211 ** <li> <b>FTS5_TOKENIZE_AUX</b> - The tokenizer is being invoked to
13219 ** passed as the second argument to xTokenize(). The third and fourth
13220 ** arguments are a pointer to a buffer containing the token text, and the
13221 ** size of the token in bytes. The 4th and 5th arguments are the byte offsets
13222 ** of the first byte of and first byte immediately following the text from
13233 ** the tokenization should be abandoned and the xTokenize() method should
13237 ** may abandon the tokenization and return any error code other than
13244 ** built-in tokenizers, the FTS5 query 'first + place' will match instances
13254 ** same token for inputs "first" and "1st". Say that token is in
13257 ** "first" and "place". If the user then queries for '1st + place',
13258 ** the tokenizer substitutes "first" for "1st" and the query works
13270 ** the tokenizer offers both "1st" and "first" as synonyms for the
13271 ** first token in the MATCH query and FTS5 effectively runs a query
13278 ** still appears to contain just two phrases - "(first OR 1st)"
13285 ** added to the FTS index for "i", "won", "first", "1st" and
13289 ** when tokenizing query text (it should not - to do so would be
13317 ** so it is efficient in terms of disk space and query speed. However, it
13328 ** because the index contains entries for both "first" and "1st", prefix
13333 ** Method (2) offers a midpoint between (1) and (3). Using this method,
13336 ** provide synonyms for prefixes). However, a non-prefix query like '1st'
13337 ** will match against "1st" and "first". This method does not require
13350 int (*xCreate)(void*, const char **azArg, int nArg, Fts5Tokenizer **ppOut);
13352 int (*xTokenize)(Fts5Tokenizer*,
13354 int flags, /* Mask of FTS5_TOKENIZE_* flags */
13355 const char *pText, int nText,
13356 int (*xToken)(
13358 int tflags, /* Mask of FTS5_TOKEN_* flags */
13360 int nToken, /* Size of token in bytes */
13361 int iStart, /* Byte offset of token within input text */
13362 int iEnd /* Byte offset of end of token within input text */
13386 int iVersion; /* Currently always set to 2 */
13389 int (*xCreateTokenizer)(
13398 int (*xFindTokenizer)(
13406 int (*xCreateFunction)(