Lines Matching refs:is
5 ** a legal notice, here is a blessing:
14 ** or constant definition does not appear in this file, then it is
15 ** not a published API of SQLite, is subject to change without
24 ** The official C-language API documentation for SQLite is derived
25 ** from comments in this file. This file is the authoritative source
28 ** The name of this file under configuration management is "sqlite.h.in".
53 ** The SQLITE_CDECL macro is used to set the calling convention for
56 ** The SQLITE_APICALL macro is used to set the calling convention for
59 ** The SQLITE_STDCALL macro is no longer used and is now deprecated.
61 ** The SQLITE_CALLBACK macro is used to set the calling convention for
64 ** The SQLITE_SYSAPI macro is used to set the calling convention for
123 ** evaluates to a string literal that is the SQLite version in the
124 ** format "X.Y.Z" where X is the major version number (always 3 for
125 ** SQLite3) and Y is the minor version number and Z is the release number.)^
130 ** be larger than the release from which it is derived. Either Y will
162 ** the header, and thus ensure that the application is
174 ** function is provided for use in DLLs since DLL users usually do not have
178 ** a pointer to a string constant whose value is the same as the
179 ** [SQLITE_SOURCE_ID] C preprocessor macro. Except if SQLite is built
200 ** returning the N-th compile time option string. ^If N is out of range,
202 ** prefix is omitted from any strings returned by
228 ** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
229 ** are enabled and SQLite is threadsafe. When the
230 ** [SQLITE_THREADSAFE] macro is 0,
231 ** the mutexes are omitted. Without the mutexes, it is not safe
235 ** So if speed is of utmost importance, it makes sense to disable
237 ** ^The default behavior is for mutexes to be enabled.
240 ** version of SQLite that it is linking against was compiled with
244 ** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with
252 ** is unchanged by calls to sqlite3_config().)^
262 ** Each open SQLite database is represented by a pointer to an instance of
263 ** the opaque structure named "sqlite3". It is useful to think of an sqlite3
278 ** Because there is no cross-platform way to specify 64-bit integer types
322 ** the [sqlite3] object is successfully destroyed and all associated
329 ** ^If the database connection is associated with unfinalized prepared
332 ** [SQLITE_BUSY]. ^If sqlite3_close_v2() is called with unfinalized prepared
339 ** is intended for use with host languages that are garbage collected, and
340 ** where the order in which destructors are called is arbitrary.
342 ** ^If an [sqlite3] object is destroyed while a transaction is open,
343 ** the transaction is automatically rolled back.
351 ** argument is a harmless no-op.
358 ** This is legacy and deprecated. It is included for historical
359 ** compatibility and is not documented.
367 ** The sqlite3_exec() interface is a convenience wrapper around
376 ** sqlite3_exec() is not NULL, then it is invoked for each result row
378 ** sqlite3_exec() is relayed through to the 1st argument of each
380 ** is NULL, then no callback is ever invoked and result rows are
386 ** is not NULL then any error message is written into memory obtained
390 ** sqlite3_exec() after the error message string is no longer needed.
391 ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
399 ** ^The 2nd argument to the sqlite3_exec() callback function is the
401 ** callback is an array of pointers to strings obtained as if from
403 ** result row is NULL then the corresponding string pointer for the
404 ** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
405 ** sqlite3_exec() callback is an array of pointers to strings where each
409 ** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
412 ** is not changed.
418 ** is a valid and open [database connection].
420 ** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
422 ** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
450 #define SQLITE_BUSY 5 /* The database file is locked */
451 #define SQLITE_LOCKED 6 /* A table in the database is locked */
456 #define SQLITE_CORRUPT 11 /* The database disk image is malformed */
458 #define SQLITE_FULL 13 /* Insertion failed because database is full */
471 #define SQLITE_NOTADB 26 /* File opened that is not a database file */
581 ** though future versions of SQLite might change so that an error is
623 ** object returns an integer which is a vector of these
631 ** are aligned to an address which is an integer multiple of
633 ** that when data is appended to a file, the data is appended
634 ** first then the size of the file is extended, never the other
636 ** information is written to disk in the same order as calls
643 ** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
676 ** The argument to xLock() is always SHARED or higher. The argument to
677 ** xUnlock is either SHARED or NONE.
692 ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
722 ** for their own use. The pMethods entry is a pointer to an
744 ** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
748 ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
749 ** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
763 ** xLock() is always on of SHARED, RESERVED, PENDING, or EXCLUSIVE, never
764 ** SQLITE_LOCK_NONE. If the database file lock is already at or above the
765 ** requested lock, then the call to xLock() is a no-op.
767 * If the lock is already at or below the requested lock state, then the call
768 ** to xUnlock() is a no-op.
770 ** either in this process or in some other process, is holding a RESERVED,
774 ** The xFileControl() method is a generic interface that allows custom
776 ** [sqlite3_file_control()] interface. The second "op" argument is an
777 ** integer opcode. The third argument is a generic pointer intended to
784 ** A [file control opcodes | list of opcodes] less than 100 is available.
791 ** device that underlies the file. The sector size is the
818 ** are aligned to an address which is an integer multiple of
820 ** that when data is appended to a file, the data is appended
821 ** first then the size of the file is extended, never the other
823 ** information is written to disk in the same order as calls
869 ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
874 ** This capability is only available if SQLite is compiled with [SQLITE_DEBUG].
877 ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
879 ** current transaction. This hint is not guaranteed to be accurate but it
880 ** is often close. The underlying VFS might choose to preallocate database
885 ** The [SQLITE_FCNTL_SIZE_LIMIT] opcode is used by in-memory VFS that
887 ** of the in-memory database. The argument is a pointer to a [sqlite3_int64].
888 ** If the integer pointed to is negative, then it is filled in with the
889 ** current limit. Otherwise the limit is set to the larger of the value
891 ** pointed to is set to the new limit.
894 ** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
903 ** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
908 ** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
917 ** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
918 ** sent to the VFS immediately before the xSync method is invoked on a
919 ** database file descriptor. Or, if the xSync method is not invoked
921 ** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place
923 ** this file-control is NULL. However, if the database file is being synced
931 ** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite
933 ** but before the database is unlocked. VFSes that do not need this signal
939 ** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
948 ** within the same process. The argument is a pointer to an array of two
949 ** integers where the first integer is the new retry count and the second
950 ** integer is the delay. If either integer is negative, then the setting
951 ** is not changed but instead the prior value of that setting is written
953 ** interrogated. The zDbName parameter is ignored.
956 ** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
962 ** close. Persisting the files is useful when other processes that do not
967 ** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
968 ** WAL mode. If the integer is -1, then it is overwritten with the current
972 ** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
977 ** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
978 ** mode. If the integer is -1, then it is overwritten with the current
982 ** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening
983 ** a write transaction to indicate that, unless it is rolled back for some
985 ** transaction. This is used by VACUUM operations.
991 ** [sqlite3_malloc()] and the result is stored in the char* variable
993 ** The caller is responsible for freeing the memory when done. As with
994 ** all file-control actions, there is no guarantee that this will actually
996 ** pointer in case this file-control is not implemented. This file-control
997 ** is intended for diagnostic use only.
1009 ** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]
1010 ** file control is sent to the open [sqlite3_file] object corresponding
1012 ** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
1014 ** is the name of the pragma and the third element is the argument to the
1024 ** prepared statement if result string is NULL, or that returns a copy
1025 ** of the result string if the string is non-NULL.
1031 ** it is able to override built-in [PRAGMA] statements.
1036 ** shortly after it is opened in order to provide a custom VFS with access
1037 ** to the connection's busy-handler callback. The argument is of type (void**)
1048 ** temporary filename using the same algorithm that is followed to generate
1055 ** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the
1057 ** The argument is a pointer to a value of type sqlite3_int64 that
1058 ** is an advisory maximum number of bytes in the file to memory map. The
1059 ** pointer is overwritten with the old value. The limit is not changed if
1060 ** the value originally pointed to is negative, and so the current limit
1062 ** file-control is used internally to implement [PRAGMA mmap_size].
1067 ** This file control is used by some VFS activity tracing [shims].
1068 ** The argument is a zero-terminated string. Higher layers in the
1070 ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
1085 ** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This
1087 ** pointed to by the pArg argument. This capability is used during testing
1088 ** and only needs to be supported when SQLITE_TEST is defined.
1091 ** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might
1092 ** be advantageous to block on the next WAL lock if the lock is not immediately
1098 ** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other
1102 ** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
1108 ** the file descriptor is placed in "batch write mode", which
1125 ** ^Regardless of whether or not it is successful, this file control takes
1141 ** The [SQLITE_FCNTL_LOCK_TIMEOUT] opcode is used to configure a VFS
1144 ** The parameter is a pointer to a 32-bit signed integer that contains
1145 ** the value that M is to be set to. Before returning, the 32-bit signed
1146 ** integer is overwritten with the previous value of M.
1149 ** The [SQLITE_FCNTL_DATA_VERSION] opcode is used to detect changes to
1150 ** a database file. The argument is a pointer to a 32-bit unsigned integer.
1151 ** The "data version" for the pager is written into the pointer. The
1163 ** but omits changes implemented by the database connection on which it is
1164 ** called. This file control is the only mechanism to detect changes that
1169 ** The [SQLITE_FCNTL_CKPT_START] opcode is invoked from within a checkpoint
1174 ** The [SQLITE_FCNTL_CKPT_DONE] opcode is invoked from within a checkpoint
1176 ** file to the database file, but before the *-shm file is updated to
1181 ** The EXPERIMENTAL [SQLITE_FCNTL_EXTERNAL_READER] opcode is used to detect
1182 ** whether or not there is a database client in another process with a wal-mode
1183 ** transaction open on the database or not. It is only available on unix.The
1185 ** value of type (int). The integer value is set to 1 if the database is a wal
1187 ** currently has an SQL transaction open on the database. It is set to 0 if
1188 ** the database is not a wal-mode db, or if there is no such connection in any
1259 ** A pointer to the opaque sqlite3_api_routines structure is passed as
1269 ** Type [sqlite3_filename] is used by SQLite to pass filenames to the
1294 ** The VFS interface is sometimes extended by adding new methods onto
1296 ** is incremented. The iVersion value started out as 1 in
1307 ** The szOsFile field is the size of the subclassed [sqlite3_file]
1308 ** structure used by this VFS. mxPathname is the maximum length of
1318 ** The pNext field is the only field in the sqlite3_vfs
1329 ** is either a NULL pointer or string obtained
1331 ** ^If a suffix is added to the zFilename parameter, it will
1335 ** the string will be valid and unchanged until xClose() is
1339 ** If the zFilename parameter to xOpen is a NULL pointer then xOpen
1341 ** xFilename parameter is NULL it will also be the case that the
1346 ** or [sqlite3_open16()] is used, then flags includes at least
1382 ** deleted when it is closed. ^The [SQLITE_OPEN_DELETEONCLOSE]
1386 ** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
1390 ** SQLITE_OPEN_CREATE, is used to indicate that file should always
1391 ** be created, and that it is an error if it already exists.
1392 ** It is <i>not</i> used to indicate the file should be opened
1408 ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
1409 ** to test whether a file is at least readable. The SQLITE_ACCESS_READ
1410 ** flag is never actually used and is not implemented in the built-in
1411 ** VFSes of SQLite. The file is named by the second argument and can be a
1413 ** non-zero error code if there is an I/O error or if the name of
1414 ** the file given in the second argument is illegal. If SQLITE_OK
1415 ** is returned, then non-zero or zero is written into *pResOut to indicate
1416 ** whether or not the file is accessible.
1420 ** is also passed as a parameter to both methods. If the output buffer
1421 ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
1429 ** of good-quality randomness into zOut. The return value is
1439 ** date and time if that method is available (if iVersion is 2 or
1440 ** greater and the function pointer is not NULL) and will fall back
1441 ** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
1453 ** any of these methods if the iVersion of the VFS is less than 3.
1501 ** what kind of permissions the xAccess method is looking for.
1505 ** checks whether the named directory is both readable and writable
1508 ** The SQLITE_ACCESS_READWRITE constant is currently used only by the
1512 ** checks whether the file is readable. The SQLITE_ACCESS_READ constant is
1568 ** A call to sqlite3_initialize() is an "effective" call if it is
1569 ** the first time sqlite3_initialize() is invoked during the lifetime of
1570 ** the process, or if it is the first time sqlite3_initialize() is invoked
1575 ** A call to sqlite3_shutdown() is an "effective" call if it is the first
1580 ** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
1581 ** is not. The sqlite3_shutdown() interface must only be called from a
1591 ** ^If for some reason, sqlite3_initialize() is unable to initialize
1592 ** the library (perhaps it is unable to allocate a needed resource such
1595 ** ^The sqlite3_initialize() routine is called internally by many other
1599 ** initialized when [sqlite3_open()] is called if it has not be initialized
1600 ** already. ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
1604 ** it is recommended that applications always invoke sqlite3_initialize()
1607 ** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
1621 ** interface is called automatically by sqlite3_initialize() and
1622 ** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
1624 ** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
1641 ** The sqlite3_config() interface is used to make global configuration
1643 ** the application. The default configuration is recommended for most
1644 ** applications and so this routine is usually not necessary. It is
1647 ** <b>The sqlite3_config() interface is not threadsafe. The application
1649 ** threads while sqlite3_config() is running.</b>
1654 ** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
1659 ** The first argument to sqlite3_config() is an integer
1661 ** what property of SQLite is to be configured. Subsequent arguments
1665 ** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
1666 ** ^If the option is unknown or SQLite is unable to set the option
1675 ** The sqlite3_db_config() interface is used to make configuration
1676 ** changes to a [database connection]. The interface is similar to
1680 ** The second argument to sqlite3_db_config(D,V,...) is the
1682 ** that indicates what aspect of the [database connection] is being configured.
1686 ** the call is considered successful.
1696 ** This object is used in only one place in the SQLite interface.
1697 ** A pointer to an instance of this object is the argument to
1698 ** [sqlite3_config()] when the configuration option is
1708 ** and that this object is only useful to a tiny minority of applications
1709 ** with specialized memory allocation requirements. This object is
1718 ** xRealloc is always a value returned by a prior call to xRoundup.
1722 ** is always at least as big as the requested size but may be larger.
1734 ** structures. The xShutdown method is invoked (indirectly) by
1736 ** by xInit. The pAppData pointer is used as the only parameter to
1741 ** xShutdown method is only called from [sqlite3_shutdown()] so it does
1744 ** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
1745 ** it is by default) and so the methods are automatically serialized.
1746 ** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
1777 ** is invoked.
1784 ** by a single thread. ^If SQLite is compiled with
1786 ** it is not possible to change the [threading mode] from its default
1795 ** The application is responsible for serializing access to
1799 ** [database connection] at the same time. ^If SQLite is compiled with
1801 ** it is not possible to set the Multi-thread [threading mode] and
1810 ** In this mode (which is the default when SQLite is compiled with
1813 ** application is free to use the same [database connection] or the
1815 ** ^If SQLite is compiled with
1817 ** it is not possible to set the Serialized [threading mode] and
1822 ** <dd> ^(The SQLITE_CONFIG_MALLOC option takes a single argument which is
1832 ** is a pointer to an instance of the [sqlite3_mem_methods] structure.
1834 ** structure is filled with the currently defined memory allocation routines.)^
1843 ** SQLite will run faster if it is free to make large memory allocations,
1846 ** allocations are avoided. This hint is normally off.
1861 ** ^Memory allocation statistics are enabled by default unless SQLite is
1867 ** <dd> The SQLITE_CONFIG_SCRATCH option is no longer used.
1874 ** This configuration option is a no-op if an application-defined page
1875 ** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
1883 ** ^It is harmless, apart from the wasted memory,
1887 ** subsequent behavior is undefined.
1888 ** ^When pMem is not NULL, SQLite will strive to use the memory provided
1890 ** a page cache line is larger than sz bytes or if all of the pMem buffer
1891 ** is exhausted.
1892 ** ^If pMem is NULL and N is non-zero, then each database connection
1894 ** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
1895 ** of -1024*N bytes if N is negative, . ^If additional
1896 ** page cache memory is needed beyond what is provided by the initial
1904 ** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
1910 ** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
1913 ** memory pointer is not NULL then the alternative memory
1914 ** allocator is engaged to handle all of SQLites memory allocation needs.
1917 ** The minimum allocation size is capped at 2**12. Reasonable values
1921 ** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
1926 ** [sqlite3_config()] returns. ^If SQLite is compiled with
1928 ** the entire mutexing subsystem is omitted from the build and hence calls to
1934 ** is a pointer to an instance of the [sqlite3_mutex_methods] structure. The
1936 ** structure is filled with the currently defined mutex routines.)^
1939 ** profiling or testing, for example. ^If SQLite is compiled with
1941 ** the entire mutexing subsystem is omitted from the build and hence calls to
1948 ** The first argument is the
1949 ** size of each lookaside buffer slot and the second is the number of
1956 ** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
1963 ** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies of
1967 ** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
1971 ** and a pointer to void. ^If the function pointer is not NULL, it is
1973 ** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
1974 ** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
1976 ** function whenever that function is invoked. ^The second parameter to
1977 ** the logger function is a copy of the first parameter to the corresponding
1978 ** [sqlite3_log()] call and is intended to be a [result code] or an
1979 ** [extended result code]. ^The third parameter passed to the logger is
1981 ** The SQLite logging interface is not reentrant; the logger function
1988 ** If non-zero, then URI handling is globally enabled. If the parameter is zero,
1989 ** then URI handling is globally disabled.)^ ^If URI handling is globally
1993 ** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
1994 ** connection is opened. ^If it is globally disabled, filenames are
1995 ** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
1996 ** database connection is opened. ^(By default, URI handling is globally
2002 ** argument which is interpreted as a boolean in order to enable or disable
2004 ** ^The default setting is determined
2005 ** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
2006 ** if that compile-time option is omitted.
2008 ** is because some incorrectly coded legacy applications might malfunction
2009 ** when the optimization is enabled. Providing the ability to
2021 ** <dd>This option is only available if sqlite is compiled with the
2024 ** The second should be of type (void*). The callback is invoked by the library
2026 ** fourth parameter. If the fourth parameter is 0, then the database connection
2029 ** fourth parameter is 1, then the SQL statement that the third parameter
2030 ** points to has just been executed. Or, if the fourth parameter is 2, then
2031 ** the connection being passed as the second parameter is being closed. The
2032 ** third parameter is passed NULL In this case. An example of using this
2047 ** ^If either argument to this option is negative, then that argument is
2052 ** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
2060 ** is a pointer to an integer and writes into that integer the number of extra
2068 ** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
2069 ** sorter to that integer. The default minimum PMA Size is set by the
2072 ** is enabled (using the [PRAGMA threads] command) and the amount of content
2082 ** Or if the threshold is -1, statement journals are always held
2087 ** The default value for this setting is controlled by the
2099 ** is stored in each sorted record and the required column values loaded
2101 ** value for this option is to never use this optimization. Specifying a
2103 ** This option is only available if SQLite is compiled with the
2109 ** [sqlite3_int64] parameter which is the default maximum size for an in-memory
2113 ** configuration setting is never used, then the default maximum is determined
2115 ** compile-time option is not set, then the default maximum is 1073741824.
2129 /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
2159 ** is invoked.
2166 ** ^The first argument (the third parameter to [sqlite3_db_config()] is a
2170 ** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
2171 ** size of each lookaside buffer slot. ^The third argument is the number of
2175 ** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
2178 ** connection is not currently using lookaside memory, or in other words
2180 ** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
2182 ** memory is in use leaves the configuration unchanged and returns
2187 ** <dd> ^This option is used to enable or disable the enforcement of
2189 ** The first argument is an integer which is 0 to disable FK enforcement,
2191 ** unchanged. The second parameter is a pointer to an integer into which
2192 ** is written 0 or 1 to indicate whether FK enforcement is off or on
2194 ** which case the FK enforcement setting is not reported back. </dd>
2198 ** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
2200 ** The first argument is an integer which is 0 to disable triggers,
2202 ** The second parameter is a pointer to an integer into which
2203 ** is written 0 or 1 to indicate whether triggers are disabled or enabled
2205 ** which case the trigger setting is not reported back.
2209 ** this option is off. So, in other words, this option now only disables
2215 ** <dd> ^This option is used to enable or disable [CREATE VIEW | views].
2217 ** The first argument is an integer which is 0 to disable views,
2219 ** The second parameter is a pointer to an integer into which
2220 ** is written 0 or 1 to indicate whether views are disabled or enabled
2222 ** which case the view setting is not reported back.
2226 ** this option is off. So, in other words, this option now only disables
2232 ** <dd> ^This option is used to enable or disable the
2233 ** [fts3_tokenizer()] function which is part of the
2236 ** The first argument is an integer which is 0 to disable fts3_tokenizer() or
2239 ** The second parameter is a pointer to an integer into which
2240 ** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled
2242 ** which case the new setting is not reported back. </dd>
2246 ** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()]
2251 ** When the first argument to this interface is 1, then only the C-API is
2253 ** this interface is 0, then both the C-API and the SQL function are disabled.
2254 ** If the first argument is -1, then no changes are made to state of either the
2256 ** The second parameter is a pointer to an integer into which
2257 ** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface
2258 ** is disabled or enabled following this call. The second parameter may
2259 ** be a NULL pointer, in which case the new setting is not reported back.
2263 ** <dd> ^This option is used to change the name of the "main" database
2264 ** schema. ^The sole argument is a pointer to a constant UTF8 string
2267 ** must ensure that the argument passed into this DBCONFIG option is unchanged
2273 ** <dd> Usually, when a database in wal mode is closed or detached from a
2278 ** is an integer - positive to disable checkpoints-on-close, or zero (the
2280 ** The second parameter is a pointer to an integer
2281 ** into which is written 0 or 1 to indicate whether checkpoints-on-close
2287 ** the [query planner stability guarantee] (QPSG). When the QPSG is active,
2294 ** The first argument to this setting is an integer which is 0 to disable
2296 ** unchanged. The second parameter is a pointer to an integer into which
2297 ** is written 0 or 1 to indicate whether the QPSG is disabled or enabled
2304 ** option is used to set or clear (the default) a flag that governs this
2305 ** behavior. The first parameter passed to this operation is an integer -
2308 ** The second parameter is a pointer to an integer into which is written
2310 ** it is not disabled, 1 if it is.
2319 ** <li> If the database connection is newly opened, make sure it has read the
2322 ** errors. This step is only necessary if the application desires to keep
2329 ** Because resetting a database is destructive and irreversible, the
2336 ** flag is enabled, language features that allow ordinary SQL to
2350 ** "writable_schema" flag. This has the same effect and is logically equivalent
2352 ** The first argument to this setting is an integer which is 0 to disable
2354 ** leave the setting unchanged. The second parameter is a pointer to an
2355 ** integer into which is written 0 or 1 to indicate whether the writable_schema
2356 ** is enabled or disabled following this call.
2373 ** only, that is DELETE, INSERT, SELECT, and UPDATE statements. The
2374 ** default value of this setting is determined by the [-DSQLITE_DQS]
2383 ** default value of this setting is determined by the [-DSQLITE_DQS]
2391 ** When the SQLITE_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite
2417 ** is now scarcely any need to generated database files that are compatible
2418 ** all the way back to version 3.0.0, and so this setting is of little
2419 ** practical use, but is provided so that SQLite can continue to claim the
2422 ** <p>Note that when the SQLITE_DBCONFIG_LEGACY_FILE_FORMAT setting is on,
2424 ** process a table with generated columns and a descending index. This is
2466 ** integer key called the [ROWID | "rowid"]. ^The rowid is always available
2470 ** is another alias for the rowid.
2493 ** return the [rowid] of the inserted row as long as the trigger is
2497 ** ^An [INSERT] that fails due to a constraint violation is not a
2507 ** ^For the purposes of this routine, an [INSERT] is considered to
2508 ** be successful even if it is subsequently rolled back.
2510 ** This function is accessible to SQL statements via the
2515 ** function is running and thus changes the last insert [rowid],
2516 ** then the value returned by [sqlite3_last_insert_rowid()] is
2541 ** or DELETE is greater than the maximum value supported by type "int", then
2542 ** the return value of sqlite3_changes() is undefined. ^Executing any other
2552 ** DELETE statement run on a view is always zero. Only changes made to real
2555 ** Things are more complicated if the sqlite3_changes() function is
2556 ** executed while a trigger program is running. This may happen if the
2562 ** sqlite3_changes() function is saved. After the trigger program
2563 ** has finished, the original value is restored.)^
2572 ** ^This means that if the changes() SQL function (or similar) is used
2575 ** ^If it is used by the second or subsequent such statement within a trigger
2580 ** while [sqlite3_changes()] is running then the value returned
2581 ** is unpredictable and not meaningful.
2604 ** the return value of sqlite3_total_changes() is undefined. ^Executing
2621 ** while [sqlite3_total_changes()] is running then the value
2622 ** returned is unpredictable and not meaningful.
2641 ** return at its earliest opportunity. This routine is typically
2646 ** ^It is safe to call this routine from a thread different from the
2647 ** thread that is currently running the database operation. But it
2648 ** is not safe to call this routine with a [database connection] that
2649 ** is closed or might close before sqlite3_interrupt() returns.
2651 ** ^If an SQL operation is very nearly finished at the time when
2652 ** sqlite3_interrupt() is called, then it might not have an opportunity
2655 ** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
2656 ** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
2657 ** that is inside an explicit transaction, then the entire transaction
2660 ** ^The sqlite3_interrupt(D) call is in effect until all currently running
2668 ** SQL statements is a no-op and has no effect on SQL statements
2678 ** if additional input is needed before sending the text into
2680 ** appears to be a complete SQL statement. ^A statement is judged to be
2681 ** complete if it ends with a semicolon token and is not a prefix of a
2688 ** ^These routines return 0 if the statement is incomplete. ^If a
2689 ** memory allocation fails, then SQLITE_NOMEM is returned.
2695 ** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
2698 ** regardless of whether or not the input SQL is complete.)^
2716 ** an attempt is made to access a database table associated with
2719 ** The sqlite3_busy_handler() interface is used to implement
2722 ** ^If the busy callback is NULL, then [SQLITE_BUSY]
2723 ** is returned immediately upon encountering the lock. ^If the busy callback
2724 ** is not NULL, then the callback might be invoked with two arguments.
2726 ** ^The first argument to the busy handler is a copy of the void* pointer which
2727 ** is the third argument to sqlite3_busy_handler(). ^The second argument to
2728 ** the busy handler callback is the number of times that the busy handler has
2731 ** access the database and [SQLITE_BUSY] is returned
2734 ** is made to access the database and the cycle repeats.
2737 ** when there is lock contention. ^If SQLite determines that invoking the busy
2741 ** Consider a scenario where one process is holding a read lock that
2742 ** it is trying to promote to a reserved lock and
2743 ** a second process is holding a reserved lock that it is trying
2745 ** because it is blocked by the second and the second process cannot
2746 ** proceed because it is blocked by the first. If both processes
2752 ** ^The default busy callback is NULL.
2762 ** the busy handler is not reentrant. Any such actions
2775 ** for a specified amount of time when a table is locked. ^The handler
2787 ** this routine, that other busy handler is cleared.)^
2797 ** This is a legacy interface that is preserved for backwards compatibility.
2798 ** Use of this interface is not recommended.
2800 ** Definition: A <b>result table</b> is memory data structure created by the
2809 ** A result table is an array of pointers to zero-terminated UTF-8 strings.
2817 ** It is not safe to pass a result table directly to [sqlite3_free()].
2821 ** is as follows:
2832 ** result table has 8 entries. Suppose the result table is stored
2856 ** [sqlite3_free_table()] is able to release the memory properly and safely.
2858 ** The sqlite3_get_table() interface is implemented as a wrapper around
2890 ** NULL pointer if [sqlite3_malloc64()] is unable to allocate enough
2893 ** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
2894 ** the standard C library. The result is written into the
2895 ** buffer supplied as the second parameter whose size is given by
2897 ** first two parameters is reversed from snprintf().)^ This is an
2906 ** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
2907 ** guarantees that the buffer is always zero-terminated. ^The first
2908 ** parameter "n" is the total size of the buffer, including space for
2912 ** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
2930 ** of memory at least N bytes in length, where N is the parameter.
2931 ** ^If sqlite3_malloc() is unable to obtain sufficient free
2933 ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
2937 ** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
2942 ** that it might be reused. ^The sqlite3_free() routine is
2943 ** a no-op if is called with a NULL pointer. Passing a NULL pointer
2944 ** to sqlite3_free() is harmless. After being freed, memory
2948 ** might result if sqlite3_free() is called with a non-NULL pointer that
2954 ** is a NULL pointer then its behavior is identical to calling
2956 ** ^If the N parameter to sqlite3_realloc(X,N) is zero or
2957 ** negative then the behavior is exactly the same as calling
2960 ** of at least N bytes in size or NULL if insufficient memory is available.
2961 ** ^If M is the size of the prior allocation, then min(N,M) bytes
2963 ** by sqlite3_realloc(X,N) and the prior allocation is freed.
2964 ** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the
2965 ** prior allocation is not freed.
2968 ** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
2971 ** ^If X is a memory allocation previously obtained from sqlite3_malloc(),
2975 ** of bytes requested when X was allocated. ^If X is a NULL pointer then
2976 ** sqlite3_msize(X) returns zero. If X points to something that is not
2979 ** of sqlite3_msize(X) is undefined and possibly harmful.
2983 ** is always aligned to at least an 8 byte boundary, or to a
2985 ** option is used.
3020 ** ^The memory high-water mark is reset to the current value of
3022 ** [sqlite3_memory_highwater()] is true. ^The value returned
3023 ** by [sqlite3_memory_highwater(1)] is the high-water mark
3034 ** already uses the largest possible [ROWID]. The PRNG is also used for
3042 ** call had N less than one or a NULL pointer for P, then the PRNG is
3046 ** non-NULL P then the pseudo-randomness is generated
3059 ** ^The authorizer callback is invoked as SQL statements are being compiled
3063 ** points during the compilation process, as logic is being created
3064 ** to perform various actions, the authorizer callback is invoked to
3075 ** requested is ok. ^When the callback returns [SQLITE_DENY], the
3078 ** access is denied.
3080 ** ^The first parameter to the authorizer callback is a copy of the third
3082 ** to the callback is an integer [SQLITE_COPY | action code] that specifies
3089 ** ^If the action code is [SQLITE_READ]
3091 ** [prepared statement] statement is constructed to substitute
3096 ** ^When a table is referenced by a [SELECT] but no column values are
3099 ** is invoked once for that table with a column name that is an empty string.
3100 ** ^If the action code is [SQLITE_DELETE] and the callback returns
3102 ** [truncate optimization] is disabled and all rows are deleted individually.
3104 ** An authorizer is used when [sqlite3_prepare | preparing]
3112 ** user-entered SQL is being [sqlite3_prepare | prepared] that
3123 ** The authorizer is disabled by default.
3130 ** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
3135 ** ^Note that the authorizer callback is invoked only during
3136 ** [sqlite3_prepare()] or its variants. Authorization is not
3152 ** to signal SQLite whether or not the action is permitted. See the
3156 ** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
3166 ** that is invoked to authorize certain SQL statement actions. The
3167 ** second parameter to the callback is an integer code that specifies
3168 ** what action is being authorized. These are the integer action codes that
3171 ** These action code values signify what kind of operation is to be
3174 ** codes is used as the second parameter. ^(The 5th parameter to the
3175 ** authorizer callback is the name of the database ("main", "temp",
3177 ** is the name of the inner-most trigger or view that is responsible for
3178 ** the access attempt or NULL if this access attempt is directly from
3227 ** ^The callback function registered by sqlite3_trace() is invoked at
3228 ** various times when an SQL statement is being run by [sqlite3_step()].
3229 ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
3232 ** as each triggered subprogram is entered. The callbacks for triggers
3238 ** ^The callback function registered by sqlite3_profile() is invoked
3242 ** time is in units of nanoseconds, however the current implementation
3243 ** is only capable of millisecond resolution so the six least significant
3260 ** to [sqlite3_trace_v2(D,M,X,P)] is an OR-ed combination of one or more of
3262 ** is one of the following constants.
3267 ** ^The T argument is one of the integer type codes above.
3268 ** ^The C argument is a copy of the context pointer passed in as the
3274 ** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement
3277 ** trigger subprogram. ^The P argument is a pointer to the
3278 ** [prepared statement]. ^The X argument is a pointer to a string which
3279 ** is the unexpanded SQL text of the prepared statement or an SQL comment
3287 ** information as is provided by the [sqlite3_profile()] callback.
3288 ** ^The P argument is a pointer to the [prepared statement] and the
3289 ** X argument points to a 64-bit integer which is the estimated of
3291 ** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
3294 ** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
3296 ** ^The P argument is a pointer to the [prepared statement] and the
3297 ** X argument is unused.
3300 ** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database
3302 ** ^The P argument is a pointer to the [database connection] object
3303 ** and the X argument is unused.
3317 ** and context pointer P. ^If the X callback is
3318 ** NULL or if the M mask is zero, then tracing is disabled. The
3325 ** ^The X callback is invoked whenever any of the events identified by
3326 ** mask M occur. ^The integer return value from the callback is currently
3330 ** ^A trace callback is invoked with four arguments: callback(T,C,P,X).
3331 ** ^The T argument is one of the [SQLITE_TRACE]
3333 ** ^The C argument is a copy of the context pointer.
3336 ** The sqlite3_trace_v2() interface is intended to replace the legacy
3355 ** interface is to keep a GUI updated during a large query.
3357 ** ^The parameter P is passed through as the only parameter to the
3358 ** callback function X. ^The parameter N is the approximate number of
3360 ** invocations of the callback X. ^If N is less than one then the progress
3361 ** handler is disabled.
3366 ** ^The progress handler is also disabled by setting N to a value less
3369 ** ^If the progress callback returns non-zero, the operation is
3386 ** filename argument. ^The filename argument is interpreted as UTF-8 for
3388 ** order for sqlite3_open16(). ^(A [database connection] handle is usually
3389 ** returned in *ppDb, even if an error occurs. The only exception is that
3390 ** if SQLite is unable to allocate memory to hold the [sqlite3] object,
3392 ** object.)^ ^(If the database is opened (and/or created) successfully, then
3393 ** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The
3402 ** Whether or not an error occurs when it is opened, resources
3404 ** passing it to [sqlite3_close()] when it is no longer required.
3414 ** <dd>The database is opened in read-only mode. If the database does not
3415 ** already exist, an error is returned.</dd>)^
3418 ** <dd>The database is opened for reading and writing if possible, or reading
3419 ** only if the file is write protected by the operating system. In either
3420 ** case the database must already exist, otherwise an error is returned.</dd>)^
3423 ** <dd>The database is opened for reading and writing, and is created if
3424 ** it does not already exist. This is the behavior that is always used for
3433 ** <dd>The filename can be interpreted as a URI if this flag is set.</dd>)^
3437 ** is named by the "filename" argument for the purposes of cache-sharing,
3438 ** if shared cache mode is enabled, but the "filename" is otherwise ignored.
3444 ** to use SQLite at the same time, as long as each thread is using
3452 ** there is no harm in trying.)
3455 ** <dd>The database is opened [shared cache] enabled, overriding
3458 ** The [use of shared cache mode is discouraged] and hence shared cache
3460 ** this option is a no-op.
3463 ** <dd>The database is opened [shared cache] disabled, overriding
3471 ** connection as soon as the connection is created. In addition to setting
3476 ** <dd>The database filename is not allowed to contain a symbolic link</dd>
3479 ** If the 3rd parameter to sqlite3_open_v2() is not one of the
3482 ** then the behavior is undefined. Historic versions of SQLite
3486 ** upon it. Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op
3489 ** flag is intended for use by the [sqlite3_vfs|VFS interface] only, and not
3492 ** ^The fourth parameter to sqlite3_open_v2() is the name of the
3494 ** the new database connection should use. ^If the fourth parameter is
3495 ** a NULL pointer then the default [sqlite3_vfs] object is used.
3497 ** ^If the filename is ":memory:", then a private, temporary in-memory database
3498 ** is created for the connection. ^This in-memory database will vanish when
3499 ** the database connection is closed. Future versions of SQLite might
3501 ** It is recommended that when a database filename actually does begin with
3505 ** ^If the filename is an empty string, then a private, temporary
3507 ** automatically deleted as soon as the database connection is closed.
3511 ** ^If [URI filename] interpretation is enabled, and the filename argument
3512 ** begins with "file:", then the filename is interpreted as a URI. ^URI
3513 ** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
3517 ** URI filename interpretation is turned off
3524 ** "localhost". ^If the authority is not an empty string or "localhost", an
3525 ** error is returned to the caller. ^The fragment component of a URI, if
3526 ** present, is ignored.
3530 ** then it is interpreted as an absolute path. ^If the path does not begin
3531 ** with a '/' (meaning that the authority section is omitted from the URI)
3532 ** then the path is interpreted as a relative path.
3534 ** is a drive specification (e.g. "C:").)^
3545 ** be used to access the database file on disk. ^If this option is set to
3546 ** an empty string the default VFS object is used. ^Specifying an unknown
3547 ** VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
3552 ** "rwc", or "memory". Attempting to set it to any other value is
3554 ** ^If "ro" is specified, then the database is opened for read-only
3556 ** third argument to sqlite3_open_v2(). ^If the mode option is set to
3557 ** "rw", then the database is opened for read-write (but not create)
3559 ** been set. ^Value "rwc" is equivalent to setting both
3560 ** SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If the mode option is
3562 ** or writes from disk is used. ^It is an error to specify a value for
3563 ** the mode parameter that is less restrictive than that specified by
3567 ** "private". ^Setting it to "shared" is equivalent to setting the
3569 ** sqlite3_open_v2(). ^Setting the cache parameter to "private" is
3571 ** ^If sqlite3_open_v2() is used and the "cache" parameter is present in
3579 ** <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
3581 ** is useful for accessing a database on a filesystem that does not
3586 ** <li> <b>immutable</b>: ^The immutable parameter is a boolean query
3587 ** parameter that indicates that the database file is stored on
3588 ** read-only media. ^When immutable is set, SQLite assumes that the
3590 ** privilege, and so the database is opened read-only and all locking
3591 ** and change detection is disabled. Caution: Setting the immutable
3598 ** ^Specifying an unknown parameter in the query component of a URI is not an
3614 ** An error. "darkstar" is not a recognized authority.
3618 ** C:. Note that the %20 escaping in this example is not strictly
3623 ** Regardless of whether or not shared-cache mode is enabled by
3629 ** An error. "readonly" is not a valid option for the "mode" parameter.
3644 ** codepage is currently defined. Filenames containing international
3684 ** If the F parameter is not one of the above, then the behavior is
3688 ** If F is a suitable filename (as described in the previous paragraph)
3689 ** and if P is the name of the query parameter, then
3692 ** query parameter on F. If P is a query parameter of F and it
3696 ** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
3699 ** value of query parameter P is one of "yes", "true", or "on" in any
3702 ** query parameter P is one of "no", "false", or "off" in any case or
3703 ** if the value begins with a numeric zero. If P is not a query
3709 ** exist. If the value of P is something other than an integer, then
3710 ** zero is returned.
3714 ** pointer if N is less than zero or greater than the number of query
3715 ** parameters minus 1. The N value is zero-based so N should be 0 to obtain
3719 ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
3720 ** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and
3721 ** is not a database file pathname pointer that the SQLite core passed
3722 ** into the xOpen VFS method, then the behavior of this routine is undefined
3729 ** When the F parameter is the name of the rollback journal or WAL file,
3747 ** If F is the name of an sqlite database file, journal file, or WAL file
3751 ** If F is the name of an sqlite database file, journal file, or WAL file
3752 ** passed by the SQLite core into the VFS, or if F is a database filename
3756 ** If F is the name of an sqlite database file, journal file, or WAL file
3757 ** that was passed by the SQLite core into the VFS, or if F is a database
3762 ** In all of the above, if F is not the name of a database, journal or WAL
3763 ** filename passed into the VFS from the SQLite core and F is not the
3764 ** return value from [sqlite3_db_filename()], then the result is
3765 ** undefined and is likely a memory access violation.
3774 ** ^If X is the name of a rollback or WAL-mode journal file that is
3779 ** This routine is intended for use in custom [VFS] implementations
3780 ** only. It is not a general-purpose interface.
3799 ** sqlite3_create_filename(D,J,W,N,P) is a pointer to a database filename that
3800 ** is safe to pass to routines like:
3817 ** pointer if N is zero. None of the 2*N pointers in the P array may be
3824 ** sqlite3_free_filename(Y) where Y is a NULL pointer is a harmless no-op.
3826 ** If the Y parameter to sqlite3_free_filename(Y) is anything other
3853 ** interface is the same except that it always returns the
3873 ** ^(Memory to hold the error message string is managed internally.
3880 ** ^(Memory to hold the error message string is managed internally
3886 ** sqlite3_error_offset() assumes that the input SQL is UTF8.
3890 ** When the serialized [threading mode] is in use, it might be the
3916 ** has been compiled into binary form and is ready to be evaluated.
3919 ** original SQL text is source code. A prepared statement object
3920 ** is the compiled object code. All SQL must be converted into a
3942 ** on a connection by connection basis. The first parameter is the
3943 ** [database connection] whose limit is to be set or queried. The
3944 ** second parameter is one of the [limit categories] that define a
3945 ** class of constructs to be size limited. The third parameter is the
3948 ** ^If the new limit is a negative number, the limit is unchanged.
3949 ** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a
3953 ** (The "_LIMIT_" in the name is changed to "_MAX_".))^
3985 ** The synopsis of the meanings of the various limits is shown below.
3986 ** Additional information is available at [limits | Limits in SQLite].
4010 ** in a single prepared statement, an SQLITE_NOMEM error is returned.</dd>)^
4059 ** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
4070 ** <dd>The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used
4073 ** [sqlite3_normalized_sql()] interface is now available to all
4097 ** The preferred routine to use is [sqlite3_prepare_v2()]. The
4098 ** [sqlite3_prepare()] interface is legacy and should be avoided.
4099 ** [sqlite3_prepare_v3()] has an extra "prepFlags" option that is used
4102 ** The use of the UTF-8 interfaces is preferred, as SQLite currently
4107 ** The first argument, "db", is a [database connection] obtained from a
4111 ** The second argument, "zSql", is the statement to be compiled, encoded
4117 ** ^If the nByte argument is negative, then zSql is read up to the
4118 ** first zero terminator. ^If nByte is positive, then it is the
4119 ** number of bytes read from zSql. ^If nByte is zero, then no prepared
4120 ** statement is generated.
4121 ** If the caller knows that the supplied string is nul-terminated, then
4122 ** there is a small performance advantage to passing an nByte parameter that
4123 ** is the number of bytes in the input string <i>including</i>
4126 ** ^If pzTail is not NULL then *pzTail is made to point to the first byte
4128 ** compile the first statement in zSql, so *pzTail is left pointing to
4131 ** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
4132 ** executed using [sqlite3_step()]. ^If there is an error, *ppStmt is set
4133 ** to NULL. ^If the input text contains no SQL (if the input is an empty
4134 ** string or a comment) then *ppStmt is set to NULL.
4135 ** The calling procedure is responsible for deleting the compiled
4140 ** otherwise an [error code] is returned.
4145 ** are retained for backwards compatibility, but their use is discouraged.
4147 ** that is returned (the [sqlite3_stmt] object) contains a copy of the
4165 ** interfaces, the underlying reason for the error is returned immediately.
4175 ** choice of query plan if the parameter is the left-hand side of a [LIKE]
4176 ** or [GLOB] operator or if the parameter is compared to an indexed column
4177 ** and the [SQLITE_ENABLE_STAT4] compile-time option is enabled.
4182 ** the extra prepFlags parameter, which is a bit array consisting of zero or
4249 ** ^(For example, if a prepared statement is created using the SQL
4250 ** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
4251 ** and parameter :xyz is unbound, then sqlite3_sql() will return
4256 ** is available to hold the result, or if the result would exceed the
4265 ** statement is finalized.
4267 ** is obtained from [sqlite3_malloc()] and must be freed by the application
4270 ** ^The sqlite3_normalized_sql() interface is only available if
4271 ** the [SQLITE_ENABLE_NORMALIZE] compile-time option is defined.
4313 ** ^This routine returns false if there is any possibility that the
4318 ** be false. ^Similarly, a CREATE TABLE IF NOT EXISTS statement is a
4322 ** ^If prepared statement X is an [EXPLAIN] or [EXPLAIN QUERY PLAN]
4333 ** prepared statement S is an EXPLAIN statement, or 2 if the
4334 ** statement S is an EXPLAIN QUERY PLAN.
4335 ** ^The sqlite3_stmt_isexplain(S) interface returns 0 if S is
4349 ** interface returns false if S is a NULL pointer. If S is not a
4350 ** NULL pointer and is not a pointer to a valid [prepared statement]
4351 ** object, then the behavior is undefined and probably undesirable.
4379 ** a mutex is held. An internal mutex is held for a protected
4380 ** sqlite3_value object but no mutex is held for an unprotected
4381 ** sqlite3_value object. If SQLite is compiled to be single-threaded
4383 ** or if SQLite is run in one of reduced mutex modes
4385 ** then there is no distinction between protected and unprotected
4387 ** for maximum code portability it is recommended that applications
4396 ** [sqlite3_column_value()] is unprotected.
4408 ** The context in which an SQL function executes is stored in an
4410 ** is always first parameter to [application-defined SQL functions].
4442 ** ^The first argument to the sqlite3_bind_*() routines is always
4446 ** ^The second argument is the index of the SQL parameter to be set.
4448 ** SQL parameter is used more than once, second and subsequent
4452 ** for "?NNN" parameters is the value of NNN.
4456 ** ^The third argument is the value to bind to the parameter.
4458 ** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
4459 ** is ignored and the end result is the same as sqlite3_bind_null().
4460 ** ^If the third parameter to sqlite3_bind_text() is not NULL, then
4462 ** ^If the third parameter to sqlite3_bind_text16() is not NULL, then
4464 ** ^If the third parameter to sqlite3_bind_text64() is not NULL, then
4465 ** it should be a pointer to a well-formed unicode string that is
4466 ** either UTF8 if the sixth parameter is SQLITE_UTF8, or UTF16
4470 ** UTF16 input text is determined by the byte-order mark (BOM, U+FEFF)
4471 ** found in first character, which is removed, or in the absence of a BOM
4472 ** the byte order is the native byte order of the host
4479 ** ^(In those routines that have a fourth argument, its value is the
4480 ** number of bytes in the parameter. To be clear: the value is the
4483 ** is negative, then the length of the string is
4485 ** If the fourth parameter to sqlite3_bind_blob() is negative, then
4486 ** the behavior is undefined.
4487 ** If a non-negative fourth parameter is provided to sqlite3_bind_text()
4494 ** with embedded NULs is undefined.
4500 ** with it may be passed. ^It is called to dispose of the BLOB or string even
4501 ** if the call to the bind API fails, except the destructor is not called if
4502 ** the third parameter is a NULL pointer or the fourth parameter is negative.
4506 ** either the prepared statement is finalized or the same SQL parameter is
4509 ** object is to be copied prior to the return from sqlite3_bind_*(). ^The
4516 ** the sixth argument to sqlite3_bind_text64() is not one of the
4517 ** allowed values shown above, or if the text encoding is different
4519 ** is undefined.
4522 ** is filled with zeroes. ^A zeroblob uses a fixed amount of memory
4523 ** (just an integer to hold its size) while it is being processed.
4525 ** content is later written using
4531 ** associated with the pointer P of type T. ^D is either a NULL pointer or
4533 ** destructor D with a single argument of P when it is finished using
4535 ** literal. The sqlite3_bind_pointer() routine is part of the
4542 ** routine is passed a [prepared statement] that has been finalized, the
4543 ** result is undefined and probably harmful.
4553 ** ^[SQLITE_RANGE] is returned if the parameter
4554 ** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails.
4603 ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
4606 ** is included as part of the name.)^
4612 ** ^If the value N is out of range or if the N-th parameter is
4613 ** nameless, then NULL is returned. ^The returned string is
4629 ** index value returned is suitable for use as the second
4631 ** is returned if no matching parameter is found. ^The parameter
4676 ** UTF-16 string. ^The first parameter is the [prepared statement]
4677 ** that implements the [SELECT] statement. ^The second parameter is the
4678 ** column number. ^The leftmost column is number 0.
4680 ** ^The returned string pointer is valid until either the [prepared statement]
4681 ** is destroyed by [sqlite3_finalize()] or until the statement is automatically
4688 ** NULL pointer is returned.
4690 ** ^The name of a result column is the value of the "AS" clause for
4691 ** that column, if there is an AS clause. If there is no AS clause
4692 ** then the name of the column is unspecified and may change from
4703 ** table column that is the origin of a particular result column in
4709 ** ^The returned string is valid until the [prepared statement] is destroyed
4710 ** using [sqlite3_finalize()] or until the statement is automatically
4712 ** or until the same information is requested
4718 ** ^The first argument to these interfaces is a [prepared statement].
4720 ** the statement, where N is the second function argument.
4721 ** ^The left-most column is column 0 for these routines.
4723 ** ^If the Nth column returned by the statement is an expression or
4724 ** subquery and is not a column value, then all of these functions return
4751 ** ^(The first parameter is a [prepared statement].
4752 ** If this statement is a [SELECT] statement and the Nth column of the
4753 ** returned result set of that [SELECT] is a table column (not an
4755 ** column is returned.)^ ^If the Nth column of the result set is an
4756 ** expression or subquery, then a NULL pointer is returned.
4757 ** ^The returned string is always UTF-8 encoded.
4771 ** is declared to contain a particular type does not mean that the
4772 ** data stored in that column is of the declared type. SQLite is
4773 ** strongly typed, but the typing is dynamic not static. ^Type
4774 ** is associated with individual values, not with the containers
4795 ** new "vX" interface is recommended for new applications but the legacy
4804 ** database locks it needs to do its job. ^If the statement is a [COMMIT]
4806 ** statement. If the statement is not a [COMMIT] and occurs within an
4816 ** is returned each time a new row of data is ready for processing by the
4818 ** sqlite3_step() is called again to retrieve the next row of data.
4827 ** the more specific error code is returned directly by sqlite3_step().
4833 ** be the case that the same database connection is being used by two or
4844 ** than returning [SQLITE_MISUSE]. This is not considered a compatibility
4846 ** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option
4854 ** We admit that this is a goofy design. The problem has been fixed
4860 ** by sqlite3_step(). The use of the "vX" interfaces is recommended.
4873 ** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
4945 ** result row of a query. ^In every case the first argument is a pointer
4946 ** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
4948 ** and the second argument is the index of the column for which information
4954 ** column index is out of range, the result is undefined.
4967 ** the result column is not initially in the requested format (for example,
4969 ** is used to extract the value) then an automatic type conversion is performed.
4973 ** of the result column. ^The returned value is one of [SQLITE_INTEGER],
4977 ** The value returned by sqlite3_column_type() is only meaningful if no
4980 ** is undefined, though harmless. Future
4984 ** If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()
4988 ** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
4990 ** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
4992 ** ^If the result is a numeric value then sqlite3_column_bytes() uses
4995 ** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
4997 ** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
4999 ** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
5001 ** ^If the result is a numeric value then sqlite3_column_bytes16() uses
5004 ** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
5014 ** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
5017 ** which is native to the platform, regardless of the text encoding set
5020 ** <b>Warning:</b> ^The object returned by [sqlite3_column_value()] is an
5025 ** [sqlite3_column_value()] is used in any other way, including calls
5027 ** or [sqlite3_value_bytes()], the behavior is not threadsafe.
5029 ** is normally only useful within the implementation of
5034 ** ^For example, if the internal representation is FLOAT and a text result
5035 ** is requested, [sqlite3_snprintf()] is used internally to perform the
5043 ** <tr><td> NULL <td> INTEGER <td> Result is 0
5044 ** <tr><td> NULL <td> FLOAT <td> Result is 0.0
5045 ** <tr><td> NULL <td> TEXT <td> Result is a NULL pointer
5046 ** <tr><td> NULL <td> BLOB <td> Result is a NULL pointer
5069 ** <li> The initial content is a BLOB and sqlite3_column_text() or
5070 ** sqlite3_column_text16() is called. A zero-terminator might
5072 ** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
5073 ** sqlite3_column_text16() is called. The content must be converted
5075 ** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
5076 ** sqlite3_column_text() is called. The content must be converted
5083 ** of conversion are done in place when it is possible, but sometimes they
5086 ** The safest policy is to invoke these routines
5105 ** [sqlite3_finalize()] is called. ^The memory space used to hold strings
5106 ** and BLOBs is freed automatically. Do not pass the pointers returned
5124 ** routines is the same as if the column had contained an SQL NULL value.
5127 ** return value is obtained and before any
5128 ** other SQLite interface is called on the same [database connection].
5145 ** ^The sqlite3_finalize() function is called to delete a [prepared statement].
5147 ** or if the statement is never been evaluated, then sqlite3_finalize() returns
5154 ** before statement S is ever evaluated, after
5159 ** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
5162 ** resource leaks. It is a grievous error for the application to try to use
5173 ** The sqlite3_reset() function is called to reset a [prepared statement]
5208 ** is similar, but allows the user to supply the extra callback functions
5211 ** ^The first parameter is the [database connection] to which the SQL
5212 ** function is to be added. ^If an application uses more than one database
5216 ** ^The second parameter is the name of the SQL function to be created or
5217 ** redefined. ^The length of the name is limited to 255 bytes in a UTF-8
5219 ** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
5224 ** is the number of arguments that the SQL function or
5225 ** aggregate takes. ^If this parameter is -1, then the SQL function or
5228 ** parameter is less than -1 or greater than 127 then the behavior is
5237 ** [SQLITE_UTF16] if [sqlite3_value_text16()] is used, or [SQLITE_UTF8]
5247 ** deterministic. The built-in [random()] SQL function is an example of a
5248 ** function that is not deterministic. The SQLite query planner is able to
5250 ** of the [SQLITE_DETERMINISTIC] flag is recommended where possible.
5257 ** For best security, the [SQLITE_DIRECTONLY] flag is recommended for
5260 ** the database schema. This flags is especially recommended for SQL
5265 ** the database file is opened and read.
5267 ** ^(The fifth parameter is an arbitrary pointer. The implementation of the
5284 ** which case a regular aggregate function is created, or must both be
5291 ** sqlite3_create_window_function() is not NULL, then it is destructor for
5292 ** the application data pointer. The destructor is invoked when the function
5293 ** is deleted, either by being overloaded or when the database connection
5294 ** closes.)^ ^The destructor is also invoked if the call to
5295 ** sqlite3_create_function_v2() fails. ^When the destructor callback is
5296 ** invoked, it is passed a single argument which is a copy of the application
5299 ** ^It is permitted to register multiple implementations of the same
5303 ** SQL function is used. ^A function implementation with a non-negative
5304 ** nArg parameter is a better match than a function implementation with
5306 ** matches the database encoding is a better
5307 ** match than a function where the encoding is different.
5308 ** ^A function where the encoding difference is between UTF16le and UTF16be
5309 ** is a closer match than a function where the encoding difference is
5314 ** ^An application-defined function is permitted to call other
5317 ** statement in which the function is running.
5388 ** The [abs|abs() function] is deterministic, for example, but
5389 ** [randomblob|randomblob()] is not. Functions must
5401 ** The SQLITE_DIRECTONLY flags is a security feature which is recommended
5408 ** The SQLITE_INNOCUOUS flag means that the function is unlikely
5411 ** input parameters. The [abs|abs() function] is an example of an
5413 ** The [load_extension() SQL function] is not innocuous because of its
5415 ** <p> SQLITE_INNOCUOUS is similar to SQLITE_DETERMINISTIC, but is not
5416 ** exactly the same. The [random|random() function] is an example of a
5417 ** function that is innocuous but not deterministic.
5423 ** the function is tagged with SQLITE_INNOCUOUS. Most built-in functions
5434 ** functions. However, if it is not specified for a user-defined window
5436 ** function may be discarded before the window function is called (i.e.
5493 ** <td>→ <td>True if the column is unchanged in an UPDATE
5508 ** is not threadsafe.
5524 ** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
5528 ** [sqlite3_value] object V. The returned value is one of [SQLITE_INTEGER],
5531 ** For example, if the datatype is initially SQLITE_INTEGER and
5532 ** sqlite3_value_text(V) is called to extract a text value for that
5535 ** occurs is undefined and may change from one release of SQLite to the next.
5538 ** numeric affinity to the value. This means that an attempt is
5540 ** such a conversion is possible without loss of information (in other
5541 ** words, if the value is a string that looks like a number)
5542 ** then the conversion is performed. Otherwise no conversion occurs.
5543 ** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
5549 ** sqlite3_value_encoding(X) is meaningless. ^Calls to
5557 ** the column corresponding to X is unchanged by the UPDATE operation
5563 ** sqlite3_value_nochange(X) is true will in all other respects appear
5564 ** to be a NULL value. If sqlite3_value_nochange(X) is invoked anywhere other
5566 ** the return value is arbitrary and meaningless.
5582 ** As long as the input parameter is correct, these routines can only
5598 ** routines is the same as if the column had contained an SQL NULL value.
5601 ** return value is obtained and before any
5602 ** other SQLite interface is called on the same [database connection].
5639 ** is a [protected sqlite3_value] object even if the input is not.
5640 ** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a
5641 ** memory allocation fails. ^If V is a [pointer value], then the result
5642 ** of sqlite3_value_dup(V) is a NULL value.
5645 ** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer
5646 ** then sqlite3_value_free(V) is a harmless no-op.
5658 ** ^The first time the sqlite3_aggregate_context(C,N) routine is called
5663 ** the same buffer is returned. Sqlite3_aggregate_context() is normally
5665 ** last time when the xFinal callback is invoked. ^(When no rows match
5667 ** implementation is never called and xFinal() is called exactly once.
5672 ** when first called if N is less than or equal to zero or if a memory
5675 ** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
5679 ** allocation.)^ Within the xFinal callback, it is customary to set
5687 ** [sqlite3_context | SQL function context] that is the first parameter
5692 ** the aggregate SQL function is running.
5707 ** the application-defined function is running.
5728 ** associate metadata with argument values. If the same value is passed to
5731 ** of where this might be useful is in a regular-expression matching
5740 ** value to the application-defined function. ^N is zero for the left-most
5741 ** function argument. ^If there is no metadata
5748 ** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or
5750 ** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
5752 ** once, when the metadata is discarded.
5753 ** SQLite is free to discard the metadata at any time, including: <ul>
5755 ** <li> ^(when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
5757 ** <li> ^(when sqlite3_set_auxdata() is invoked again on the same
5769 ** ^(In practice, metadata is preserved between function calls for
5778 ** the SQL function is running.
5787 ** These are special values for the destructor that is passed in as the
5789 ** argument is SQLITE_STATIC, it means that the content pointer is constant
5795 ** The typedef is necessary to work around problems in certain
5816 ** an application-defined function to be the BLOB whose content is pointed
5817 ** to by the second parameter and which is N bytes long where N is the
5837 ** or sqlite3_result_error16() is negative then SQLite takes as the error
5840 ** sqlite3_result_error16() is non-negative then SQLite takes that many
5848 ** the error code is SQLITE_ERROR. ^A subsequent call to sqlite3_result_error()
5852 ** error indicating that a string or BLOB is too long to represent.
5870 ** a text string which is represented as UTF-8, UTF-16 native byte order,
5879 ** other than sqlite3_result_text64() is negative, then SQLite computes
5883 ** is non-negative, then as many bytes (not characters) of the text
5885 ** function result. If the 3rd parameter is non-negative, then it
5888 ** in the string at a byte offset that is less than the value of the 3rd
5890 ** result of expressions operating on strings with embedded NULs is undefined.
5892 ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
5896 ** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
5897 ** assumes that the text or BLOB result is in constant space and does not
5901 ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
5907 ** when the encoding is not UTF8, if the input UTF16 begins with a
5908 ** byte-order mark (BOM, U+FEFF) then the BOM is removed from the
5909 ** string and the rest of the string is interpreted according to the
5913 ** sqlite3_result_text16le() is invoked with text that begins
5916 ** is interpreted as UTF16BE text.
5931 ** [unprotected sqlite3_value] object is required, so either
5939 ** ^If the D parameter is not NULL, then it is a pointer to a destructor
5941 ** when SQLite is finished with P. The T parameter should be a static
5943 ** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
5994 ** ^The name of the collation is a UTF-8 string
6015 ** ^The fourth argument, pArg, is an application data pointer that is passed
6018 ** ^The fifth argument, xCompare, is a pointer to the collating function.
6022 ** ^If the xCompare argument is NULL then the collating function is
6024 ** that collation is no longer usable.
6026 ** ^The collating function callback is invoked with a copy of the pArg
6030 ** function must return an integer that is negative, zero, or positive
6031 ** if the first string is less than, equal to, or greater than the second,
6047 ** collating function is registered and used, then the behavior of SQLite
6048 ** is undefined.
6051 ** with the addition that the xDestroy callback is invoked on pArg when
6052 ** the collating function is deleted.
6055 ** [database connection] is closed using [sqlite3_close()].
6057 ** ^The xDestroy callback is <u>not</u> called if the
6062 ** This is different from every other SQLite interface. The inconsistency
6063 ** is unfortunate but cannot be changed without breaking backwards
6098 ** sequence is required.
6100 ** ^If the function is registered using the sqlite3_collation_needed() API,
6101 ** then it is passed the names of undefined collation sequences as strings
6102 ** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
6106 ** ^(When the callback is invoked, the first argument passed is a copy
6108 ** sqlite3_collation_needed16(). The second argument is the database
6109 ** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
6111 ** sequence function required. The fourth parameter is the name of the
6148 ** requested from the operating system is returned.
6152 ** of the default VFS is not implemented correctly, or not implemented at
6161 ** ^(If this global variable is made to point to a string which is
6165 ** is a NULL pointer, then SQLite performs a search for an appropriate
6169 ** It is required to set a temporary folder on Windows Runtime (WinRT).
6170 ** But for all other platforms, it is highly recommended that applications
6171 ** neither read nor write this variable. This global variable is a relic
6175 ** It is not safe to read or modify this variable in more than one
6176 ** thread at a time. It is not safe to read or modify this variable
6177 ** if a [database connection] is being used at the same time in a separate
6179 ** It is intended that this variable be set once
6187 ** that this variable points to is held in memory obtained from
6190 ** Hence, if this variable is modified directly, either it should be
6201 ** features that require the use of temporary files may fail. Here is an
6219 ** ^(If this global variable is made to point to a string which is
6223 ** to be relative to that directory.)^ ^If this variable is a NULL
6227 ** variable; it is ignored by the unix VFS.
6229 ** Changing the value of this variable while a database connection is
6232 ** It is not safe to read or modify this variable in more than one
6233 ** thread at a time. It is not safe to read or modify this variable
6234 ** if a [database connection] is being used at the same time in a separate
6236 ** It is intended that this variable be set once
6244 ** that this variable points to is held in memory obtained from
6247 ** Hence, if this variable is modified directly, either it should be
6257 ** [sqlite3_win32_set_directory] interface is used to set the value associated
6263 ** [SQLITE_OK] to indicate success, [SQLITE_ERROR] if the type is unsupported,
6265 ** [sqlite3_data_directory] variable is intended to act as a replacement for
6266 ** the current directory on the sub-platforms of Win32 where that concept is
6294 ** zero if the given database connection is or is not in autocommit mode,
6295 ** respectively. ^Autocommit mode is on by default.
6296 ** ^Autocommit mode is disabled by a [BEGIN] statement.
6297 ** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
6304 ** an error is to use this function.
6307 ** connection while this routine is running, then the return value
6308 ** is undefined.
6318 ** returned by sqlite3_db_handle is the same [database connection]
6330 ** for the N-th database on database connection D, or a NULL pointer of N is
6331 ** out of range. An N value of 0 means the main database file. An N of 1 is
6335 ** Space to hold the string that is returned by sqlite3_db_name() is managed
6353 ** ^If there is no attached database N on the database
6354 ** connection D, or if database N is a temporary or in-memory database, then
6357 ** ^The string value returned by this routine is owned and managed by
6359 ** is [DETACH]-ed or until the database connection closes.
6361 ** ^The filename returned by this function is the output of the
6366 ** If the filename pointer returned by this routine is not NULL, then it
6380 ** CAPI3REF: Determine if a database is read-only
6384 ** of connection D is read-only, 0 if it is read/write, or -1 if N is not
6394 ** [transaction state] of schema S in database connection D. ^If S is NULL,
6396 ** is returned. Transaction states are (in order of lowest to highest):
6402 ** ^If the S argument to sqlite3_txn_state(D,S) is not the name of
6403 ** a valid schema, then -1 is returned.
6418 ** <dd>The SQLITE_TXN_NONE state means that no transaction is currently
6422 ** <dd>The SQLITE_TXN_READ state means that the database is currently
6431 ** <dd>The SQLITE_TXN_WRITE state means that the database is currently
6445 ** pStmt associated with the [database connection] pDb. ^If pStmt is NULL
6461 ** function to be invoked whenever a transaction is [COMMIT | committed].
6463 ** for the same database connection is overridden.
6465 ** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
6467 ** for the same database connection is overridden.
6468 ** ^The pArg argument is passed through to the callback.
6470 ** then the commit is converted into a rollback.
6490 ** operation is allowed to continue normally. ^If the commit hook
6491 ** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
6492 ** ^The rollback hook is invoked on a rollback that results from a commit
6495 ** ^For the purposes of this API, a transaction is said to have been
6496 ** rolled back if an explicit "ROLLBACK" statement is executed, or
6498 ** ^The rollback callback is not invoked if a transaction is
6499 ** automatically rolled back because the database connection is closed.
6511 ** function C that is invoked prior to each autovacuum of the database
6512 ** file. ^The callback is passed a copy of the generic data pointer (P),
6513 ** the schema-name of the attached database that is being autovacuumed,
6518 ** ^If the value returned is greater than or equal to the number of
6523 ** callback is invoked separately for each file.
6525 ** <p><b>The callback is not reentrant.</b> The callback function should
6531 ** ^The X parameter to sqlite3_autovacuum_pages(D,C,P,X) is an optional
6532 ** destructor for the P parameter. ^If X is not NULL, then X(P) is
6534 ** is overwritten by another invocation of sqlite3_autovacuum_pages().
6536 ** <p>^There is only one autovacuum pages callback per database connection.
6539 ** argument (C) to sqlite3_autovacuum_pages(D,C,P,X) is a NULL pointer,
6540 ** then the autovacuum steps callback is cancelled. The return value
6541 ** from sqlite3_autovacuum_pages() is normally SQLITE_OK, but might
6546 ** <p>If no autovacuum pages callback is specified (the usual case) or
6547 ** a NULL pointer is provided for the callback,
6548 ** then the default behavior is to vacuum all free pages. So, in other
6549 ** words, the default behavior is the same as if the callback function
6578 ** to be invoked whenever a row is updated, inserted or deleted in
6581 ** for the same database connection is overridden.
6583 ** ^The second argument is a pointer to the function to invoke when a
6584 ** row is updated, inserted or deleted in a rowid table.
6585 ** ^The first argument to the callback is a copy of the third argument
6587 ** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
6592 ** ^The final callback parameter is the [rowid] of the row.
6593 ** ^In the case of an update, this is the [rowid] after the update takes place.
6595 ** ^(The update hook is not invoked when internal system tables are
6597 ** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified.
6600 ** is not invoked when conflicting rows are deleted because of an
6601 ** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook
6632 ** to the same database. Sharing is enabled if the argument is true
6633 ** and disabled if the argument is false.)^
6635 ** This interface is omitted if SQLite is compiled with
6637 ** compile-time option is recommended because the
6638 ** [use of shared cache mode is discouraged].
6640 ** ^Cache sharing is enabled and disabled for an entire process.
6641 ** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]).
6651 ** successfully. An [error code] is returned otherwise.)^
6653 ** ^Shared cache is disabled by default. It is recommended that it stay
6655 ** continues to be provided for historical compatibility, but its use is
6656 ** discouraged. Any use of shared cache is discouraged. If shared cache
6657 ** must be used, it is recommended that shared cache only be enabled for
6661 ** Note: This method is disabled on MacOS X 10.7 and iOS version 5.0
6666 ** This interface is threadsafe on processors where writing a
6667 ** 32-bit integer is atomic.
6679 ** pages to improve performance is an example of non-essential memory.
6682 ** ^The sqlite3_release_memory() routine is a no-op returning zero
6683 ** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT].
6695 ** [sqlite3_release_memory()] interface, this interface is in effect even
6696 ** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is
6714 ** ^The soft heap limit is "soft" because even though SQLite strives to stay
6717 ** is advisory only.
6721 ** sqlite3_hard_heap_limit64(N) interface is similar to
6723 ** when the hard heap limit is reached.
6726 ** sqlite3_hard_heap_limit64() is the size of
6728 ** error. ^If the argument N is negative
6729 ** then no change is made to the heap limit. Hence, the current
6736 ** ^If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N)
6737 ** is invoked with a value of N that is greater than the hard heap limit,
6738 ** the soft heap limit is set to the value of the hard heap limit.
6739 ** ^The soft heap limit is automatically enabled whenever the hard heap
6740 ** limit is enabled. ^When sqlite3_hard_heap_limit64(N) is invoked and
6741 ** the soft heap limit is outside the range of 1..N, then the soft heap
6742 ** limit is set to N. ^Invoking sqlite3_soft_heap_limit64(0) when the
6743 ** hard heap limit is enabled makes the soft heap limit equal to the
6753 ** <li> The limit value is set to zero.
6754 ** <li> Memory accounting is disabled using a combination of the
6757 ** <li> An alternative page cache implementation is specified using
6774 ** This is a deprecated version of the [sqlite3_soft_heap_limit64()]
6775 ** interface. This routine is provided for historical compatibility
6793 ** ^If the column-name parameter to sqlite3_table_column_metadata() is a
6797 ** sqlite3_table_column_metadata(X,D,T,C,...) is NULL then the result is
6800 ** ^The column is identified by the second, third and fourth parameters to
6801 ** this function. ^(The second parameter is either the name of the database
6803 ** table or NULL.)^ ^If it is NULL, then all attached databases are searched
6810 ** ^Metadata is returned by writing to the memory locations passed as the 5th
6812 ** NULL, in which case the corresponding element of metadata is omitted.
6821 ** <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY
6822 ** <tr><td> 9th <td> int <td> True if column is [AUTOINCREMENT]
6827 ** declaration type and collation sequence is valid until the next
6830 ** ^If the specified table is actually a view, an [error code] is returned.
6832 ** ^If the specified column is "rowid", "oid" or "_rowid_" and the table
6833 ** is not a [WITHOUT ROWID] table and an
6835 ** parameters are set for the explicitly declared column. ^(If there is no
6860 int *pAutoinc /* OUTPUT: True if column is auto-increment */
6877 ** ^The entry point is zProc.
6881 ** X is consists of the lower-case equivalent of all ASCII alphabetic
6886 ** ^If an error occurs and pzErrMsg is not 0, then the
6898 ** <b>Security warning:</b> It is recommended that the
6921 ** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
6923 ** ^Extension loading is off by default.
6933 ** <b>Security warning:</b> It is recommended that extension loading
6945 ** each new [database connection] that is created. The idea here is that
6946 ** xEntryPoint() is the entry point for a statically linked [SQLite extension]
6947 ** that is to be automatically loaded into all new database connections.
6965 ** is NULL before calling the xEntryPoint(). ^SQLite will invoke
6970 ** ^Calling sqlite3_auto_extension(X) with an entry point X that is already
6971 ** on the list of automatic extensions is a harmless no-op. ^No entry point
6972 ** will be called more than once for each database connection that is opened.
7000 ** The interface to the virtual-table mechanism is currently considered
7002 ** If this is a problem for you, do not use the interface at this time.
7024 ** ^A virtual table module is created by filling in a persistent
7027 ** ^The registration remains valid until it is replaced by a different
7029 ** of this structure must not change while it is registered with
7074 ** The sqlite3_index_info structure and its substructures is used as part
7085 ** where OP is =, <, <=, >, or >=.)^ ^(The particular operator is
7088 ** ^(The index of the column is stored in
7089 ** aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the
7091 ** is usable) and false if it cannot.)^
7099 ** ^Information about the ORDER BY clause is stored in aOrderBy[].
7106 ** the corresponding bit is set within the colUsed mask if the column may be
7108 ** to the right of the first 63 is required, then bit 63 of colUsed is also
7115 ** the right-hand side of the corresponding aConstraint[] is evaluated
7117 ** is true, then the constraint is assumed to be fully handled by the
7119 ** aConstraintUsage[].omit flag is an optimization hint. When the omit flag
7120 ** is left in its default setting of false, the constraint will always be
7121 ** checked separately in byte code. If the omit flag is change to true, then
7123 ** when the omit flag is true there is no guarantee that the constraint will
7128 ** ^[sqlite3_free()] is used to free idxPtr if and only if
7129 ** needToFreeIdxPtr is true.
7133 ** sorting step is required.
7135 ** ^The estimatedCost value is an estimate of the cost of a particular
7136 ** strategy. A cost of N indicates that the cost of the strategy is similar
7138 ** indicates that the expense of the operation is similar to that of a
7141 ** ^The estimatedRows value is an estimate of the number of rows that
7145 ** mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag -
7150 ** SQLite also assumes that if a call to the xUpdate() method is made as
7152 ** implementation returns SQLITE_CONSTRAINT, then there is no need to rollback
7155 ** before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not
7161 ** If a virtual table extension is
7178 unsigned char usable; /* True if this constraint is usable */
7188 int argvIndex; /* if >0, constraint is part of argv to xFilter */
7194 int orderByConsumed; /* True if output is already ordered */
7218 ** an operator that is part of a constraint term in the WHERE clause of
7221 ** ^The left-hand operand of the operator is given by the corresponding
7223 ** operand is the rowid.
7226 ** corresponding aConstraint[].iColumn is meaningless and should not be
7236 ** operand is only available if it appears as a single constant literal
7237 ** in the input SQL. If the right-hand operand is another column or an
7249 ** interface is no commonly needed.
7278 ** ^The module name is registered on the [database connection] specified
7279 ** by the first parameter. ^The name of the module is given by the
7280 ** second parameter. ^The third parameter is a pointer to
7282 ** parameter is an arbitrary client data pointer that is passed through
7284 ** when a new virtual table is be being created or reinitialized.
7287 ** is a pointer to a destructor for the pClientData. ^SQLite will
7288 ** invoke the destructor function (if it is not NULL) when SQLite
7292 ** interface is equivalent to sqlite3_create_module_v2() with a NULL
7295 ** ^If the third parameter (the pointer to the sqlite3_module object) is
7296 ** NULL then no new module is created and any existing modules with the
7322 ** to strings where the array is terminated by a single NULL pointer.
7323 ** ^If the L parameter is NULL, then all virtual table modules are removed.
7340 ** The purpose of this superclass is to define certain fields that are
7345 ** take care that any prior string is freed by a call to [sqlite3_free()]
7347 ** is delivered up to the client application, the string will be automatically
7400 ** before this API is called, a new function is created.)^ ^The implementation
7402 ** the new function is not good for anything by itself. Its only
7403 ** purpose is to be a placeholder function that can be overloaded
7410 ** to a comment remarkably similar to this one) is currently considered
7412 ** If this is a problem for you, do not use the interface at this time.
7445 ** ^(Parameter zDb is not the filename that contains the database, but
7446 ** rather the symbolic name of the database. For attached databases, this is
7448 ** For the main database file, the database name is "main". For TEMP
7449 ** tables, the database name is "temp".)^
7451 ** ^If the flags parameter is non-zero, then the BLOB is opened for read
7452 ** and write access. ^If the flags parameter is zero, the BLOB is opened for
7455 ** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is stored
7456 ** in *ppBlob. Otherwise an [error code] is returned and, unless the error
7457 ** code is SQLITE_MISUSE, *ppBlob is set to NULL.)^ ^This means that, provided
7458 ** the API is not misused, it is always safe to call [sqlite3_blob_close()]
7465 ** <li> ^(Table zTable is a WITHOUT ROWID table)^,
7467 ** <li> ^(Row iRow is not present in the table)^,
7468 ** <li> ^(The specified column of row iRow contains a value that is not
7470 ** <li> ^(Column zColumn is part of an index, PRIMARY KEY or UNIQUE
7471 ** constraint and the blob is being opened for read/write access)^,
7473 ** column zColumn is part of a [child key] definition and the blob is
7486 ** cannot be changed after the [BLOB handle] is opened.
7488 ** ^(If the row that a BLOB handle points to is modified by an
7490 ** then the BLOB handle is marked as "expired".
7491 ** This is true if any column of the row is changed, even a column
7492 ** other than the one the BLOB handle is open on.)^
7529 ** ^This function is used to move an existing [BLOB handle] so that it points
7530 ** to a different row of the same database table. ^The new row is identified
7532 ** changed. ^The database, table and column on which the blob handle is open
7533 ** remain the same. Moving an existing [BLOB handle] to a new row is
7538 ** the nominated column.)^ ^If the new row is not present in the table, or if
7540 ** SQLite error code is returned and the blob handle is considered aborted.
7554 ** ^This function closes an open [BLOB handle]. ^(The BLOB handle is closed
7556 ** handle is still closed.)^
7559 ** the database is in auto-commit mode and there are no other open read-write
7560 ** blob handles or active write statements, the current transaction is
7562 ** code is returned and the transaction rolled back.
7564 ** Calling this function with an argument that is not a NULL pointer or an
7567 ** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function
7568 ** is passed a valid open blob handle, the values returned by the
7593 ** ^(This function is used to read data from an open [BLOB handle] into a
7597 ** ^If offset iOffset is less than N bytes from the end of the BLOB,
7598 ** [SQLITE_ERROR] is returned and no data is read. ^If N or iOffset is
7599 ** less than zero, [SQLITE_ERROR] is returned and no data is read.
7607 ** Otherwise, an [error code] or an [extended error code] is returned.)^
7622 ** ^(This function is used to write data into an open [BLOB handle] from a
7627 ** Otherwise, an [error code] or an [extended error code] is returned.)^
7628 ** ^Unless SQLITE_MISUSE is returned, this function sets the
7636 ** This function may only modify the contents of the BLOB; it is
7638 ** ^If offset iOffset is less than N bytes from the end of the BLOB,
7639 ** [SQLITE_ERROR] is returned and no data is written. The size of the
7642 ** than zero [SQLITE_ERROR] is returned and no data is written.
7663 ** A virtual filesystem (VFS) is an [sqlite3_vfs] object
7666 ** single default VFS that is appropriate for the host computer.
7673 ** ^If there is no match, a NULL pointer is returned.
7674 ** ^If zVfsName is NULL then the default VFS is returned.
7677 ** ^Each new VFS becomes the default VFS if the makeDflt flag is set.
7681 ** same name are registered, the behavior is undefined. If a
7682 ** VFS is registered with a name that is NULL or an empty string,
7683 ** then the behavior is undefined.
7686 ** ^(If the default VFS is unregistered, another VFS is chosen as
7687 ** the default. The choice for the new VFS is arbitrary.)^
7698 ** use by SQLite, code that links against SQLite is
7703 ** is selected automatically at compile-time. The following
7712 ** The SQLITE_MUTEX_NOOP implementation is a set of routines
7713 ** that does no real locking and is appropriate for use in
7718 ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
7720 ** implementation is included with the library. In this case the
7728 ** routine returns NULL if it is unable to allocate the requested
7751 ** a new mutex. ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
7752 ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
7757 ** implementation is available on the host platform, the mutex subsystem
7770 ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
7772 ** mutex types, the same mutex is returned on every call that has
7780 ** to enter a mutex. ^If another thread is already within the mutex,
7788 ** than an SQLITE_MUTEX_RECURSIVE more than once, the behavior is undefined.
7793 ** sqlite3_mutex_try() as an optimization so this is acceptable
7798 ** is undefined if the mutex is not currently entered by the
7799 ** calling thread or is not currently allocated.
7802 ** sqlite3_mutex_leave() is a NULL pointer, then all three routines
7829 ** ^The xMutexInit method defined by this structure is invoked as
7831 ** ^The xMutexInit routine is called by SQLite exactly once for each
7834 ** ^The xMutexEnd method defined by this structure is invoked as
7836 ** implementation of this method is expected to release all outstanding
7839 ** interface is invoked exactly once for each call to [sqlite3_shutdown()].
7855 ** The only difference is that the public sqlite3_XXX functions enumerated
7860 ** (i.e. it is acceptable to provide an implementation that segfaults if
7861 ** it is passed a NULL pointer).
7873 ** ^SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is
7875 ** If xMutexInit fails in any way, it is expected to clean up after itself
7898 ** provides implementations for these routines when it is compiled
7900 ** are only required to provide these routines if SQLITE_DEBUG is
7901 ** defined and if NDEBUG is not defined.
7904 ** is held or not held, respectively, by the calling thread.
7906 ** The implementation is not required to provide versions of these
7911 ** If the argument to sqlite3_mutex_held() is a NULL pointer then
7914 ** the reason the mutex does not exist is because the build is not
7916 ** call to sqlite3_mutex_held() to fail, so a non-zero return is
7929 ** which is one of these integer constants.
7962 ** when the [threading mode] is Serialized.
7963 ** ^If the [threading mode] is Single-thread or Multi-thread then this
7976 ** name of the database is "main" for the main database or "temp" for the
8000 ** open database file, then SQLITE_ERROR is returned. ^This error
8001 ** code is not remembered and will not be recalled by [sqlite3_errcode()]
8003 ** also return SQLITE_ERROR. There is no way to distinguish between
8014 ** ^The sqlite3_test_control() interface is used to read out internal
8016 ** purposes. ^The first parameter is an operation code that determines
8019 ** This interface is not for use by applications. It exists solely
8021 ** on how the SQLite library is compiled, this interface might not exist.
8025 ** Unlike most of the SQLite API, this function is not guaranteed to
8088 ** of bytes in the keyword into *L. The string that *Z points to is not
8090 ** SQLITE_OK if N is within bounds and SQLITE_ERROR if not. If either Z
8095 ** the L-byte UTF8 identifier that Z points to is a keyword, returning non-zero
8096 ** if it is and zero if not.
8098 ** The parser used by SQLite is forgiving. It is often possible to use
8101 ** "CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" is accepted by SQLite, and
8103 ** "REPLACE", "PRAGMA", and "END". Nevertheless, best practice is to avoid
8107 ** <li> Put all identifier names inside double-quotes. This is the official
8109 ** <li> Put identifier names inside [...]. This is not standard SQL,
8110 ** but it is what SQL Server does and so lots of programmers use this
8118 ** compile-time options. For example, "VACUUM" is not a keyword if
8119 ** SQLite is compiled with the [-DSQLITE_OMIT_VACUUM] option. Also,
8133 ** The lifecycle of an sqlite3_str object is as follows:
8135 ** <li> ^The sqlite3_str object is created using [sqlite3_str_new()].
8136 ** <li> ^Text is appended to the sqlite3_str object using various
8138 ** <li> ^The sqlite3_str object is destroyed and the string it created
8139 ** is returned using the [sqlite3_str_finish()] interface.
8159 ** [sqlite3_str_finish(X)]. It is always safe to use the value
8164 ** D parameter in [sqlite3_str_new(D)] is not NULL, then the maximum
8182 ** string in [sqlite3_str] object X is zero bytes long.
8215 ** is recorded in the [sqlite3_str] object and can be recovered by a
8245 ** returned by [sqlite3_str_value(X)] is managed by the sqlite3_str object X
8263 ** highwater marks. ^The first argument is an integer code for
8266 ** ^The current value of the parameter is returned into *pCurrent.
8267 ** ^The highest recorded value is returned in *pHighwater. ^If the
8268 ** resetFlag is true, then the highest record value is reset after
8269 ** *pHighwater is written. ^(Some parameters do not record the highest
8271 ** nothing is written into *pHighwater and the resetFlag is ignored.)^
8273 ** value. For these latter parameters nothing is written into *pCurrent.)^
8278 ** If either the current value or the highwater mark is too large to
8302 ** <dd>This parameter is the current amount of memory checked out
8306 ** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
8307 ** this parameter. The amount returned is the sum of the allocation
8314 ** *pHighwater parameter to [sqlite3_status()] is of interest.
8315 ** The value written into the *pCurrent parameter is undefined.</dd>)^
8325 ** value returned is in pages, not in bytes.</dd>)^
8340 ** *pHighwater parameter to [sqlite3_status()] is of interest.
8341 ** The value written into the *pCurrent parameter is undefined.</dd>)^
8354 ** The *pCurrent value is undefined. The *pHighwater value is only
8355 ** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
8375 ** ^This interface is used to retrieve runtime status information
8376 ** about a single [database connection]. ^The first argument is the
8378 ** is an integer constant, taken from the set of
8381 ** [SQLITE_DBSTATUS options] is likely
8384 ** ^The current value of the requested parameter is written into *pCur
8385 ** and the highest instantaneous value is written into *pHiwtr. ^If
8386 ** the resetFlg is true, then the highest instantaneous value is
8407 ** if a discontinued or unsupported verb is invoked.
8416 ** satisfied using lookaside memory. Only the high-water value is meaningful;
8417 ** the current value is always zero.)^
8424 ** Only the high-water value is meaningful;
8425 ** the current value is always zero.)^
8432 ** Only the high-water value is meaningful;
8433 ** the current value is always zero.)^
8438 ** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.
8442 ** <dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a
8443 ** pager cache is shared between two or more connections the bytes of heap
8444 ** memory used by that pager cache is divided evenly between the attached
8450 ** SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0.
8456 ** ^The full amount of memory used by the schemas is reported, even if the
8457 ** schema memory is shared with other database connections due to
8459 ** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.
8465 ** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.
8471 ** is always 0.
8477 ** is always 0.
8487 ** on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined.)^ ^The
8488 ** highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0.
8503 ** resolved.)^ ^The highwater mark is always 0.
8533 ** that the prepared statement is using a full table scan rather than
8536 ** ^(This interface is used to retrieve and reset counter values from
8537 ** a [prepared statement]. The first argument is the prepared statement
8539 ** is an integer code for a specific [SQLITE_STMTSTATUS counter]
8541 ** ^The current value of the requested counter is returned.
8542 ** ^If the resetFlg is true, then the counter is reset to zero after this
8559 ** <dd>^This is the number of times that SQLite has stepped forward in
8565 ** <dd>^This is the number of sort operations that have occurred.
8570 ** <dd>^This is the number of rows inserted into transient indices that
8574 ** need to be reinitialized each time the statement is run.</dd>
8577 ** <dd>^This is the number of virtual machine operations executed
8578 ** by the prepared statement if that number is less than or equal
8582 ** then the value returned by this statement status code is undefined.
8585 ** <dd>^This is the number of times that the prepare statement has been
8590 ** <dd>^This is the number of times that the prepared statement has
8591 ** been run. A single "run" for the purposes of this counter is one
8593 ** The counter is incremented on the first [sqlite3_step()] call of each
8600 ** <dd>^SQLITE_STMTSTATUS_FILTER_HIT is the number of times that a join
8602 ** corresponding SQLITE_STMTSTATUS_FILTER_MISS value is the number of
8607 ** <dd>^This is the approximate number of bytes of heap memory
8608 ** used to store the prepared statement. ^This value is not actually
8610 ** is ignored when the opcode is SQLITE_STMTSTATUS_MEMUSED.
8627 ** The sqlite3_pcache type is opaque. It is implemented by
8661 ** SQLite is used for the page cache.
8665 ** that memory is allocated and released, and the policies used to
8669 ** The alternative page cache mechanism is an
8670 ** extreme measure that is only needed by the most demanding applications.
8671 ** The built-in page cache is recommended for most uses.
8679 ** ^(The xInit() method is called once for each effective
8682 ** method is passed a copy of the sqlite3_pcache_methods2.pArg value.)^
8683 ** The intent of the xInit() method is to set up global data structures
8685 ** ^(If the xInit() method is NULL, then the
8686 ** built-in default page cache is used instead of the application defined
8690 ** ^The xShutdown() method is called by [sqlite3_shutdown()].
8697 ** xShutdown method is only called from [sqlite3_shutdown()] so it does
8707 ** though this is not guaranteed. ^The
8708 ** first parameter, szPage, is the size in bytes of the pages that must
8710 ** second parameter szExtra is a number of bytes of extra storage
8716 ** ^The third argument to xCreate(), bPurgeable, is true if the cache being
8718 ** false if it is used for an in-memory database. The cache implementation
8720 ** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will
8730 ** instance passed as the first argument. This is the value configured using
8732 ** parameter, the implementation is not required to do anything with this
8733 ** value; it is advisory only.
8748 ** The page to be fetched is determined by the key. ^The minimum key value
8749 ** is 1. After it has been retrieved using xFetch, the page is considered
8752 ** If the requested page is already in the page cache, then the page cache
8754 ** intact. If the requested page is not already in the cache, then the
8759 ** <tr><th> createFlag <th> Behavior when page is not already in cache
8764 ** NULL if allocating a new page is effectively impossible.
8774 ** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
8775 ** as its second argument. If the third parameter, discard, is non-zero,
8777 ** ^If the discard parameter is
8787 ** The xRekey() method is used to change the key value associated with the
8790 ** discarded. ^Any prior cache entry associated with newKey is guaranteed not
8800 ** ^The xDestroy() method is used to delete a cache allocated by xCreate().
8809 ** is not obligated to free any memory, but well-behaved implementations should
8831 ** This is the obsolete pcache_methods object that has now been replaced
8832 ** by sqlite3_pcache_methods2. This object is not used by SQLite. It is
8855 ** online backup operation. ^The sqlite3_backup object is created by
8856 ** a call to [sqlite3_backup_init()] and is destroyed by a call to
8867 ** It is useful either for creating backups of databases or
8874 ** ^The source database is read-locked only while it is being read;
8875 ** it is not locked continuously for the entire backup operation.
8878 ** reading or writing to the source database while the backup is underway.
8882 ** <li><b>sqlite3_backup_init()</b> is called once to initialize the
8884 ** <li><b>sqlite3_backup_step()</b> is called one or more times to transfer
8886 ** <li><b>sqlite3_backup_finish()</b> is called to release all resources
8897 ** ^The database name is "main" for the main database, "temp" for the
8908 ** there is already a read or read-write transaction open on the
8911 ** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
8927 ** ^If N is negative, all remaining source pages are copied.
8933 ** then an [error code] is returned. ^As well as [SQLITE_OK] and
8941 ** <li> the destination database is using write-ahead-log journaling
8943 ** <li> the destination database is an in-memory database and the
8949 ** is invoked (if one is specified). ^If the
8950 ** busy-handler returns non-zero before the lock is available, then
8951 ** [SQLITE_BUSY] is returned to the caller. ^In this case the call to
8954 ** is being used to write to the source database when sqlite3_backup_step()
8955 ** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
8958 ** [SQLITE_READONLY] is returned, then
8959 ** there is no point in retrying the call to sqlite3_backup_step(). These
8965 ** on the destination file. ^The exclusive lock is not released until either
8966 ** sqlite3_backup_finish() is called or the backup operation is complete
8970 ** ^Because the source database is not locked between calls to
8972 ** through the backup process. ^If the source database is modified by an
8976 ** database is modified by the using the same database connection as is used
8977 ** by the backup operation, then the backup database is automatically
8988 ** active write-transaction on the destination database is rolled back.
8989 ** The [sqlite3_backup] object is invalid
8992 ** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
9000 ** is not a permanent error and does not affect the return value of
9012 ** sqlite3_backup_step(). If the source database is modified in a way that
9021 ** purposes while a backup operation is underway or being initialized.
9022 ** ^If SQLite is compiled and configured to support threadsafe database
9027 ** [database connection] is not passed to any other API (by any thread) after
9028 ** sqlite3_backup_init() is called and before the corresponding call to
9031 ** and so no error code is reported, but the operations may malfunction
9033 ** backup is in progress might also cause a mutex deadlock.
9037 ** is not accessed while the backup is running. In practice this means
9039 ** backed up to is not accessed by any connection within the process,
9042 ** The [sqlite3_backup] object itself is partially threadsafe. Multiple
9046 ** same time as another thread is invoking sqlite3_backup_step() it is
9070 ** ^This API is only available if the library was compiled with the
9079 ** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
9081 ** has locked the required resource is stored internally. ^After an
9085 ** when the blocking connections current transaction is concluded. ^The
9086 ** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
9089 ** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
9090 ** there is a chance that the blocking connection will have already
9091 ** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
9092 ** If this happens, then the specified callback is invoked immediately,
9095 ** ^If the blocked connection is attempting to obtain a write-lock on a
9101 ** blocked connection. If sqlite3_unlock_notify() is called when the
9103 ** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
9105 ** unlock-notify callback is canceled. ^The blocked connections
9109 ** The unlock-notify callback is not reentrant. If an application invokes
9113 ** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always
9118 ** When an unlock-notify callback is registered, the application provides a
9119 ** single void* pointer that is passed to the callback when it is invoked.
9122 ** an unlock-notify callback is a pointer to an array of void* pointers,
9123 ** and the second is the number of entries in the array.
9125 ** When a blocking connection's transaction is concluded, there may be
9129 ** multiple times, it is invoked once with the set of void* context pointers
9139 ** application to deadlock. For example, if connection X is waiting for
9141 ** Y is waiting on connection X's transaction, then neither connection
9146 ** system in a deadlocked state, then SQLITE_LOCKED is returned and no
9147 ** unlock-notify callback is registered. The system is said to be in
9151 ** A's transaction is concluded. ^Indirect deadlock is also detected, so
9152 ** the system is also considered to be deadlocked if connection B has
9154 ** C's transaction, where connection C is waiting on connection A. ^Any
9159 ** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost
9160 ** always appropriate to call sqlite3_unlock_notify(). There is however,
9163 ** that belong to the same connection. If there are, SQLITE_LOCKED is
9164 ** returned. In this case there is no "blocking connection", so invoking
9169 ** One way around this problem is to check the extended error code returned
9170 ** by an sqlite3_step() call. ^(If there is a blocking connection, then the
9171 ** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
9172 ** the special "DROP TABLE/INDEX" case, the extended error code is just
9199 ** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the
9201 ** is case sensitive.
9216 ** [sqlite3_strlike(P,X,E)] is the same as for the "X LIKE P ESCAPE E"
9219 ** ^As with the LIKE operator, the [sqlite3_strlike(P,X,E)] function is case
9238 ** ^If logging is enabled, the zFormat string and subsequent arguments are
9241 ** The sqlite3_log() interface is intended for use by extensions such as
9242 ** virtual tables, collating functions, and SQL functions. While there is
9244 ** is considered bad form.
9249 ** will not use dynamically allocated memory. The log message is stored in
9250 ** a fixed-length buffer on the stack. If the log message is longer than
9260 ** ^The [sqlite3_wal_hook()] function is used to register a callback that
9261 ** is invoked each time data is committed to a database in wal mode.
9263 ** ^(The callback is invoked by SQLite after the commit has taken place and
9267 ** ^The first parameter passed to the callback function when it is invoked
9268 ** is a copy of the third parameter passed to sqlite3_wal_hook() when
9269 ** registering the callback. ^The second is a copy of the database handle.
9270 ** ^The third parameter is the name of the database that was written to -
9272 ** is the number of pages currently in the write-ahead log file,
9276 ** code is returned, that error will propagate back up through the
9285 ** previously registered write-ahead log callback. ^The return value is
9301 ** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around
9323 ** is only necessary if the default setting is found to be suboptimal
9332 ** ^(The sqlite3_wal_checkpoint(D,X) is equivalent to
9343 ** interface was added. This interface is retained for backwards
9356 ** information is written back into integers pointed to by L and C.)^
9364 ** is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.
9370 ** [sqlite3_busy_handler|busy-handler callback]) until there is no
9373 ** database file. ^This mode blocks new database writers while it is pending,
9383 ** database writer attempts while it is pending, but does not impede readers.
9391 ** ^If pnLog is not NULL, then *pnLog is set to the total number of frames in
9393 ** of an error or because the database is not in [WAL mode]. ^If pnCkpt is not
9394 ** NULL,then *pnCkpt is set to the total number of checkpointed frames in the
9397 ** because the database is not in WAL mode. ^Note that upon successful
9402 ** any other process is running a checkpoint operation at the same time, the
9403 ** lock cannot be obtained and SQLITE_BUSY is returned. ^Even if there is a
9408 ** obtained immediately, and a busy-handler is configured, it is invoked and
9410 ** is successfully obtained. ^The busy-handler is also invoked while waiting for
9412 ** the writer lock is obtained or while waiting for database readers, the
9415 ** without blocking any further. ^SQLITE_BUSY is returned in this case.
9417 ** ^If parameter zDb is NULL or points to a zero length string, then the
9418 ** specified operation is attempted on all WAL databases [attached] to
9421 ** an SQLITE_BUSY error is encountered when processing one or more of the
9422 ** attached WAL databases, the operation is still attempted on any remaining
9423 ** attached databases and SQLITE_BUSY is returned at the end. ^If any other
9424 ** error occurs while processing an attached database, processing is abandoned
9425 ** and the error code is returned to the caller immediately. ^If no error
9426 ** (SQLITE_BUSY or otherwise) is encountered while processing the attached
9427 ** databases, SQLITE_OK is returned.
9429 ** ^If database zDb is the name of an attached database that is not in WAL
9430 ** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. ^If
9431 ** zDb is not NULL (or a zero length string) and is not the name of any
9432 ** attached database, SQLITE_ERROR is returned to the caller.
9436 ** sets the error information that is queried by
9471 ** If this interface is invoked outside the context of an xConnect or
9472 ** xCreate virtual table method then the behavior is undefined.
9474 ** In the call sqlite3_vtab_config(D,C,...) the D parameter is the
9475 ** [database connection] in which the virtual table is being created and
9476 ** which is passed in as the first argument to the [xConnect] or [xCreate]
9477 ** method that is invoking sqlite3_vtab_config(). The C parameter is one
9480 ** is used.
9498 ** where X is an integer. If X is zero, then the [virtual table] whose
9500 ** support constraints. In this configuration (which is the default) if
9502 ** statement is rolled back as if [ON CONFLICT | OR ABORT] had been
9506 ** If X is non-zero, then the virtual table implementation guarantees
9509 ** If the [ON CONFLICT] mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite
9510 ** is able to roll back a statement or database transaction, and abandon
9512 ** If the ON CONFLICT mode is REPLACE and the [xUpdate] method returns
9519 ** CONFLICT policy is REPLACE, the virtual table implementation should
9521 ** return SQLITE_OK. Or, if this is not possible, it may return
9540 ** virtual table can do no serious harm even if it is controlled by a
9555 ** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL],
9565 ** If the sqlite3_vtab_nochange(X) routine is called within the [xColumn]
9567 ** column is being fetched as part of an UPDATE operation during which the
9569 ** this hint as permission to substitute a return value that is less
9574 ** the column is not changed by the UPDATE statement, then the xColumn
9580 ** The sqlite3_vtab_nochange() routine is an optimization. Virtual table
9594 ** that is the name of the appropriate collation sequence to use for text
9598 ** that is the first parameter to the xBestIndex() method. The second argument
9603 ** The first parameter must be the same pointer that is passed into the
9607 ** The return value is computed as follows:
9612 ** that COLLATE operator is returned.
9613 ** <li><p> If there is no COLLATE operator, but the column that is the subject
9617 ** name of that alternative collating sequence is returned.
9618 ** <li><p> Otherwise, "BINARY" is returned.
9624 ** CAPI3REF: Determine if a virtual table query is DISTINCT
9629 ** interface from outside of xBestIndex() is undefined and probably harmful.
9642 ** [sqlite3_index_info] object. This is the default expectation. If the
9643 ** virtual table outputs all rows in sorted order, then it is always safe for
9650 ** "aOrderBy" field are adjacent.)^ This mode is used when the query planner
9651 ** is doing a GROUP BY.
9658 ** needs to be returned.)^ ^It is always ok for two or more rows with the same
9662 ** ^However omitting the extra rows is optional.
9663 ** This mode is used for a DISTINCT query.
9667 ** rows to be sorted.)^ ^The virtual table implementation is free to omit
9669 ** it is not required to omit any rows. This mode is used for queries
9675 ** to be the same. In other words, the comparison operator is "IS"
9678 ** If a virtual table implementation is unable to meet the requirements
9682 ** ^A virtual table implementation is always free to return rows in any order
9683 ** it wants, as long as the "orderByConsumed" flag is not set. ^When the
9684 ** the "orderByConsumed" flag is unset, the query planner will add extra
9687 ** sqlite3_vtab_distinct() interface is merely an optimization. ^Careful
9690 ** overly aggressive and setting the "orderByConsumed" flag when it is not
9701 ** The result of invoking this interface from any other context is
9705 ** "[IN operator|column IN (...)]" is
9724 ** is an [IN operator] that can be processed all at once. ^In other words,
9725 ** sqlite3_vtab_in() with -1 in the third argument is a mechanism
9727 ** of the IN operator is even possible.
9733 ** parameter (F) is non-negative, this interface is the mechanism by
9742 ** (non-zero), that means that the constraint is an IN operator
9743 ** that can be processed all-at-once. ^If the constraint is not an IN
9747 ** ^(All-at-once processing of the IN operator is selected if both of the
9751 ** <li><p> The P->aConstraintUsage[N].argvIndex value is set to a positive
9752 ** integer. This is how the virtual table tells SQLite that it wants to
9775 ** is undefined and probably harmful.
9782 ** [xBestIndex|xBestIndex method]. ^(If the X parameter is not
9805 ** right hand side of the IN constraint, then *P is set to NULL and these
9826 ** ^When the sqlite3_vtab_rhs_value(P,J,V) interface is invoked from within
9831 ** that constraint if the right-hand operand is known. ^If the
9832 ** right-hand operand is not known, then *V is set to a NULL pointer.
9834 ** and only if *V is set to a value. ^The sqlite3_vtab_rhs_value(P,J,V)
9836 ** constraint is not available. ^The sqlite3_vtab_rhs_value() interface
9840 ** The sqlite3_vtab_rhs_value() interface is usually only successful if
9841 ** the right-hand operand of a constraint is a literal value in the original
9842 ** SQL statement. If the right-hand operand is an expression or a reference
9850 ** ^The [sqlite3_value] object returned in *V is a protected sqlite3_value
9853 ** sqlite3_vtab_rhs_value() is automatically deallocated.
9855 ** The "_rhs_" in the name of this routine is an abbreviation for
9866 ** is for the SQL statement being evaluated.
9868 ** Note that the [SQLITE_IGNORE] constant is also used as a potential
9870 ** [SQLITE_ABORT] is also a [result code].
9886 ** When the value returned to V is a string, space to hold that string is
9888 ** S is finalized.
9920 ** subquery the loop is part of. The main query has a select-id of zero.
9921 ** The select-id is the same value as is output in the first column
9941 ** Since this interface is expected to be rarely used, it is only
9942 ** available if SQLite is compiled using the [SQLITE_ENABLE_STMT_SCANSTATUS]
9947 ** of this interface is undefined.
9948 ** ^The requested measurement is written into a variable pointed to by
9951 ** Loops are numbered starting from zero. ^If idx is out of range - less than
9953 ** the statement - a non-zero value is returned and the variable that pOut
9954 ** points to is unchanged.
9976 ** This API is only available if the library is built with pre-processor
9985 ** ^If a write-transaction is open on [database connection] D when the
9989 ** active SQL statement is reading from it, or if it is page 1 of a database
9990 ** file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)]
9996 ** immediately and there is a busy-handler callback configured, it is invoked
9998 ** the database is skipped and an attempt made to flush any dirty pages
10004 ** example an IO error or out-of-memory condition), then processing is
10005 ** abandoned and an SQLite [error code] is returned to the caller immediately.
10018 ** ^These interfaces are only available if SQLite is compiled using the
10022 ** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation
10027 ** ^The preupdate hook is disabled by invoking [sqlite3_preupdate_hook()]
10029 ** ^The third parameter to [sqlite3_preupdate_hook()] is passed through as
10033 ** preupdate hook is not invoked for changes to [virtual tables] or to
10036 ** ^The second parameter to the preupdate callback is a pointer to
10038 ** ^The third parameter to the preupdate callback is one of the constants
10040 ** kind of update operation that is about to occur.
10041 ** ^(The fourth parameter to the preupdate callback is the name of the
10042 ** database within the database connection that is being modified. This
10046 ** ^The fifth parameter to the preupdate callback is the name of the
10047 ** table that is being modified.
10050 ** parameter passed to the preupdate callback is the initial [rowid] of the
10053 ** parameter is undefined. For an INSERT or UPDATE on a rowid table the
10054 ** seventh parameter is the final rowid value of the row being inserted
10056 ** function is not defined for operations on WITHOUT ROWID tables, or for
10064 ** [database connection] pointer that is different from the one supplied
10069 ** in the row that is being inserted, updated, or deleted.
10073 ** the table row before it is updated. The N parameter must be between 0
10076 ** preupdate callbacks; if it is used by an SQLITE_INSERT callback then the
10077 ** behavior is undefined. The [sqlite3_value] that P points to
10082 ** the table row after it is updated. The N parameter must be between 0
10085 ** preupdate callbacks; if it is used by an SQLITE_DELETE callback then the
10086 ** behavior is undefined. The [sqlite3_value] that P points to
10095 ** When the [sqlite3_blob_write()] API is used to update a blob column,
10096 ** the pre-update hook is invoked with SQLITE_DELETE. This is because the
10098 ** callback made with op==SQLITE_DELETE is actuall a write using the
10101 ** pre-update hook is being invoked for some other reason, including a
10133 ** The return value is OS-dependent. For example, on unix systems, after
10153 ** by the reader until a new read transaction is started.
10156 ** version of the database file so that it is possible to later open a new read
10173 ** If there is not already a read-transaction open on schema S when
10174 ** this function is called, one is opened automatically.
10177 ** the following statements are false when sqlite3_snapshot_get() is
10178 ** called, SQLITE_ERROR is returned. The final value of *P is undefined
10192 ** file immediately after it is first opened. At least one transaction
10196 ** This function may also return SQLITE_NOMEM. If it is called with the
10198 ** whether or not a read transaction is opened on schema S is undefined.
10204 ** The [sqlite3_snapshot_get()] interface is only available when the
10205 ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
10225 ** [autocommit mode] when [sqlite3_snapshot_open(D,S,P)] is called. If there
10226 ** is already a read transaction open on schema S, then the database handle
10229 ** SQLITE_ERROR is returned if either of these conditions is violated, or
10230 ** if schema S does not exist, or if the snapshot object is invalid.
10234 ** SQLITE_ERROR_SNAPSHOT is returned.
10236 ** If there is already a read transaction open when this function is
10239 ** is returned. If another error code - for example SQLITE_PROTOCOL or an
10240 ** SQLITE_IOERR error code - is returned, then the final state of the
10241 ** read transaction is undefined. If SQLITE_OK is returned, then the
10242 ** read transaction is now open on database snapshot P.
10246 ** schema S is in [WAL mode]. A database connection might not know
10247 ** that the database file is in [WAL mode] if there has been no prior
10253 ** The [sqlite3_snapshot_open()] interface is only available when the
10254 ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
10270 ** The [sqlite3_snapshot_free()] interface is only available when the
10271 ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
10279 ** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages
10283 ** file, the result of the comparison is undefined.
10285 ** Additionally, the result of the comparison is only valid if both of the
10287 ** last time the wal file was deleted. The wal file is deleted when the
10288 ** database is changed back to rollback mode or when the number of database
10291 ** is undefined.
10295 ** snapshot, and a positive value if P1 is a newer snapshot than P2.
10297 ** This interface is only available if SQLite is compiled with the
10312 ** calling [sqlite3_close()]) and a new connection is subsequently opened
10319 ** sqlite3_snapshot_open(). It is an error if there is already a read
10320 ** transaction open on the database, or if the database is not a WAL mode
10323 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
10325 ** This interface is only available if SQLite is compiled with the
10334 ** that is a serialization of the S database on [database connection] D.
10335 ** If P is not a NULL pointer, then the size of the database in bytes
10336 ** is written into *P.
10338 ** For an ordinary on-disk database file, the serialization is just a
10340 ** the serialization is the same sequence of bytes which would be written
10343 ** The usual case is that sqlite3_serialize() copies the serialization of
10345 ** a pointer to that memory. The caller is responsible for freeing the
10350 ** is currently using for that database, or NULL if the no such contiguous
10355 ** The size of the database is written into *P even if the
10356 ** SQLITE_SERIALIZE_NOCOPY bit is set but no contiguous copy
10360 ** SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory
10363 ** This interface is omitted if SQLite is compiled with the
10380 ** a pointer to contiguous in-memory database that it is currently using,
10381 ** without making a copy of the database. If SQLite is not currently using
10395 ** in P. The serialized database P is N bytes in size. M is the size of
10396 ** the buffer P, which might be larger than N. If M is larger than N, and
10397 ** the SQLITE_DESERIALIZE_READONLY bit is not set in F, then SQLite is
10401 ** If the SQLITE_DESERIALIZE_FREEONCLOSE bit is set in F, then SQLite will
10403 ** connection closes. If the SQLITE_DESERIALIZE_RESIZEABLE bit is set, then
10408 ** database is currently in a read transaction or is involved in a backup
10411 ** It is not possible to deserialized into the TEMP database. If the
10412 ** S argument to sqlite3_deserialize(D,S,P,N,M,F) is "temp" then the
10416 ** SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F, then
10417 ** [sqlite3_free()] is invoked on argument P prior to returning.
10419 ** This interface is omitted if SQLite is compiled with the
10438 ** in the P argument is held in memory obtained from [sqlite3_malloc64()]
10441 ** is responsible for freeing any dynamically allocated memory.
10443 ** The SQLITE_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed to
10445 ** flag should only be used if SQLITE_DESERIALIZE_FREEONCLOSE is also used.
10454 #define SQLITE_DESERIALIZE_READONLY 4 /* Database is read-only */