Lines Matching refs:to
4 ** The author disclaims copyright to this source code. In place of
13 ** presents to client programs. If a C-function, structure, datatype,
15 ** not a published API of SQLite, is subject to change without
20 ** features recently added to SQLite. We do not anticipate changes
21 ** to experimental interfaces but reserve the right to make minor changes
26 ** on how SQLite interfaces are supposed to operate.
29 ** The makefile makes some minor changes to this file (such as inserting
30 ** the version number) and changes its name to "sqlite3.h" as
50 ** The SQLITE_EXTERN and SQLITE_API macros are used to instruct the
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
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
94 ** These no-op macros are used in front of interfaces to mark those
98 ** experimental interfaces are subject to change in point releases.
100 ** These macros used to resolve to various kinds of compiler magic that
103 ** that we have taken it all out and gone back to using simple
123 ** evaluates to a string literal that is the SQLite version in the
126 ** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
132 ** and Z will be reset to zero.
137 ** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to
160 ** programmers might include assert() statements in their application to
172 ** macro. ^The sqlite3_libversion() function returns a pointer to the
173 ** to the sqlite3_version[] string constant. The sqlite3_libversion()
175 ** direct access to string constants within the DLL. ^The
176 ** sqlite3_libversion_number() function returns an integer equal to
178 ** a pointer to a string constant whose value is the same as the
196 ** option name passed to sqlite3_compileoption_used().
224 ** SQLite was compiled with mutexing code omitted due to the
225 ** [SQLITE_THREADSAFE] compile-time option being set to 0.
232 ** to use SQLite concurrently from more than one thread.
235 ** So if speed is of utmost importance, it makes sense to disable
237 ** ^The default behavior is for mutexes to be enabled.
239 ** This interface can be used by an application to make sure that the
246 ** can be fully or partially disabled using a call to [sqlite3_config()]
250 ** thread safety, not any run-time changes to that setting made by
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
269 ** [sqlite3_busy_timeout()] to name but three) that are methods on an
278 ** Because there is no cross-platform way to specify 64-bit integer types
321 ** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if
328 ** with the [sqlite3] object prior to attempting to close the object.
336 ** "zombie" and makes arrangements to automatically deallocate the database
345 ** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]
369 ** that allows an application to run multiple statements of SQL
370 ** without having to use a lot of C code.
375 ** argument. ^If the callback function of the 3rd argument to
377 ** coming out of the evaluated SQL statements. ^The 4th argument to
378 ** sqlite3_exec() is relayed through to the 1st argument of each
379 ** callback invocation. ^If the callback pointer to sqlite3_exec()
385 ** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec()
391 ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
392 ** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
399 ** ^The 2nd argument to the sqlite3_exec() callback function is the
400 ** number of columns in the result. ^The 3rd argument to the sqlite3_exec()
401 ** callback is an array of pointers to strings obtained as if from
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
410 ** to an empty string, or a pointer that contains only whitespace and/or
417 ** <li> The application must ensure that the 1st parameter to sqlite3_exec()
420 ** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
427 const char *sql, /* SQL to be evaluated */
429 void *, /* 1st argument to callback */
438 ** here in order to indicate success or failure.
453 #define SQLITE_READONLY 8 /* Attempt to write a readonly database */
459 #define SQLITE_CANTOPEN 14 /* Unable to open the database file */
464 #define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
470 #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
485 ** much information about problems as programmers might like. In an effort to
575 ** 3rd parameter to the [sqlite3_open_v2()] interface and
576 ** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
579 ** used as the third argument to the [sqlite3_open_v2()] interface.
587 ** to be opened using O_EXCL. Passing SQLITE_OPEN_EXCLUSIVE into
626 ** refers to.
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
636 ** information is written to disk in the same order as calls
637 ** to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
641 ** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
672 ** argument to calls it makes to the xLock() and xUnlock() methods
674 ** lest restrictive to most restrictive.
676 ** The argument to xLock() is always SHARED or higher. The argument to
693 ** sync operation only needs to flush data to mass storage. Inode
695 ** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
697 ** to use Mac OS X style fullsync instead of fsync().
701 ** settings. The [synchronous pragma] determines when calls to the
721 ** want to subclass this object by appending additional fields
722 ** for their own use. The pMethods entry is a pointer to an
736 ** [sqlite3_file] object) with a pointer to an instance of this object.
737 ** This object defines the methods used to perform various operations
741 ** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
743 ** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
744 ** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
745 ** to NULL.
747 ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
750 ** flag may be ORed in to indicate that only the data of the file
751 ** and not its inode needs to be synced.
753 ** The integer values to xLock() and xUnlock() are one of
762 ** database file lock in the direction NONE toward EXCLUSIVE. The argument to
765 ** requested lock, then the call to xLock() is a no-op.
766 ** xUnlock() downgrades the database file lock to either SHARED or NONE.
768 ** to xUnlock() is a no-op.
775 ** VFS implementations to directly control an open file using the
777 ** integer opcode. The third argument is a generic pointer intended to
778 ** point to a structure that may contain arguments or space in which to
780 ** functions to enable blocking locks with timeouts, to change the
781 ** locking strategy (for example to use dot-file locks), to inquire
782 ** about the status of a lock, or to break stale locks. The SQLite
786 ** greater than 100 to avoid conflicts. VFS implementations should
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
823 ** information is written to disk in the same order as calls
824 ** to xWrite().
828 ** fails to zero-fill short reads might seem to work. However,
829 ** failure to zero-fill short reads will eventually lead to
870 ** opcode causes the xFileControl method to write the current state of
873 ** into an integer that the pArg argument points to.
877 ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
878 ** layer a hint of how large the database file will grow to be during the
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
881 ** file space based on this hint in order to help writes to the database
886 ** implements [sqlite3_deserialize()] to set an upper bound on the size
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
890 ** of the integer pointed to and the current database size. The integer
891 ** pointed to is set to the new limit.
894 ** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
896 ** by the user. The fourth argument to [sqlite3_file_control()] should
897 ** point to an integer (type int) containing the new chunk-size to use
903 ** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
904 ** to the [sqlite3_file] object associated with a particular database
908 ** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
909 ** to the [sqlite3_file] object associated with the journal file (either
918 ** sent to the VFS immediately before the xSync method is invoked on a
924 ** as part of a multi-database commit, the argument points to a nul-terminated
932 ** and sent to the VFS after a transaction has been committed immediately
939 ** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
941 ** windows [VFS] in order to provide robustness in the presence of
943 ** file write, and file delete operations up to 10 times, with a delay
947 ** to be adjusted. The values are changed for all database connections
948 ** within the same process. The argument is a pointer to an array of two
952 ** into the array entry, allowing the current retry settings to be
956 ** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
960 ** are automatically deleted when the latest connection to the database
961 ** closes. Setting persistent WAL mode causes those files to persist after
964 ** to read the database file, as the WAL and shared memory files must exist
965 ** in order for the database to be readable. The fourth parameter to
966 ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
967 ** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
972 ** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
975 ** xDeviceCharacteristics methods. The fourth parameter to
976 ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
977 ** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
983 ** a write transaction to indicate that, unless it is rolled back for some
988 ** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of
992 ** that the fourth parameter of [sqlite3_file_control()] points to.
995 ** do anything. Callers should initialize the char* variable to a NULL
1000 ** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
1004 ** to a pointer to the top-level VFS.)^
1010 ** file control is sent to the open [sqlite3_file] object corresponding
1011 ** to the database file to which the pragma statement refers. ^The argument
1012 ** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
1013 ** pointers to strings (char**) in which the second element of the array
1014 ** is the name of the pragma and the third element is the argument to the
1017 ** of the char** argument point to a string obtained from [sqlite3_mprintf()]
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**)
1039 ** to a function of type (int (*)(void *)). In order to invoke the connection's
1047 ** to have SQLite generate a
1048 ** temporary filename using the same algorithm that is followed to generate
1052 ** invoke [sqlite3_free()] on the result to avoid a memory leak.
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
1060 ** the value originally pointed to is negative, and so the current limit
1061 ** can be queried by passing in a pointer to a negative number. This
1062 ** file-control is used internally to implement [PRAGMA mmap_size].
1066 ** to the VFS about what the higher layers of the SQLite stack are doing.
1074 ** pointer to an integer and it writes a boolean into that integer depending
1079 ** The [SQLITE_FCNTL_WIN32_GET_HANDLE] opcode can be used to obtain the
1081 ** control interprets its argument as a pointer to a native file handle and
1086 ** opcode causes the xFileControl method to swap the file handle with the one
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
1094 ** circumstances in order to fix a problem with priority inversion.
1112 ** ^Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to
1116 ** except for calls to the xWrite method and the xFileControl method
1121 ** operations since the previous successful call to
1122 ** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be performed atomically.
1124 ** all performed successfully and have been committed to persistent storage.
1129 ** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
1133 ** operations since the previous successful call to
1134 ** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be rolled back.
1138 ** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
1141 ** The [SQLITE_FCNTL_LOCK_TIMEOUT] opcode is used to configure a VFS
1142 ** to block for up to M milliseconds before failing when attempting to
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
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.
1152 ** "data version" changes whenever any change occurs to the corresponding
1156 ** interface can be used to find if any database on the connection has changed,
1157 ** but that interface responds to changes on TEMP as well as MAIN and does
1158 ** not provide a mechanism to detect changes to MAIN only. Also, the
1159 ** [sqlite3_total_changes()] interface responds to internal changes only and
1161 ** [PRAGMA data_version] command provides a mechanism to detect changes to
1162 ** a single attached database that occur due to other database connections,
1164 ** called. This file control is the only mechanism to detect changes that
1170 ** in wal mode before the client starts to copy pages from the wal
1171 ** file to the database file.
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
1184 ** (void*) argument passed with this file-control should be a pointer to a
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
1189 ** other process. This opcode cannot be used to detect transactions opened
1247 ** The mutex module within SQLite defines [sqlite3_mutex] to be an
1250 ** deals with pointers to the [sqlite3_mutex] object.
1259 ** A pointer to the opaque sqlite3_api_routines structure is passed as
1260 ** the third parameter to entry points of [loadable extensions]. This
1261 ** structure must be typedefed in order to work around compiler warnings
1269 ** Type [sqlite3_filename] is used by SQLite to pass filenames to the
1270 ** xOpen method of a [VFS]. It may be cast to (const char*) and treated
1272 ** may also be passed to special APIs such as:
1297 ** SQLite [version 3.5.0] on [dateof:3.5.0], then increased to 2
1299 ** to 3 with SQLite [version 3.7.6] on [dateof:3.7.6]. Additional fields
1300 ** may be appended to the sqlite3_vfs object and the iVersion value
1302 ** Note that due to an oversight, the structure
1304 ** SQLite [version 3.5.9] to [version 3.6.0] on [dateof:3.6.0]
1328 ** ^SQLite guarantees that the zFilename parameter to xOpen
1331 ** ^If a suffix is added to the zFilename parameter, it will
1337 ** the [sqlite3_file] can safely store a pointer to the
1338 ** filename if it needs to remember the filename for some reason.
1339 ** If the zFilename parameter to xOpen is a NULL pointer then xOpen
1344 ** The flags argument to xOpen() includes all bits set in
1345 ** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]
1348 ** If xOpen() opens a file read-only then it sets *pOutFlags to
1351 ** ^(SQLite will also add one of the following flags to the xOpen()
1365 ** The file I/O implementation can use the object type flags to
1368 ** the open of a journal file a no-op. Writes to this journal would
1369 ** also be no-ops, and any attempt to read the journal would return
1374 ** SQLite might also add one of the following flags to the xOpen method:
1388 ** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
1390 ** SQLITE_OPEN_CREATE, is used to indicate that file should always
1392 ** It is <i>not</i> used to indicate the file should be opened
1396 ** to hold the [sqlite3_file] structure passed as the third
1397 ** argument to xOpen. The xOpen method does not have to
1399 ** the xOpen method must set the sqlite3_file.pMethods to either
1400 ** a valid [sqlite3_io_methods] object or to NULL. xOpen must do
1406 ** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
1407 ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
1409 ** to test whether a file is at least readable. The SQLITE_ACCESS_READ
1415 ** is returned, then non-zero or zero is written into *pResOut to indicate
1420 ** is also passed as a parameter to both methods. If the output buffer
1423 ** to prevent this by setting mxPathname to a sufficiently large value.
1428 ** The xRandomness() function attempts to return nBytes bytes
1431 ** The xSleep() method causes the calling thread to sleep for at
1438 ** ^SQLite will use the xCurrentTimeInt64() method to get the current
1441 ** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
1445 ** by some VFSes to facilitate testing of the VFS code. By overriding
1448 ** or impossible to induce. The set of system calls that can be overridden
1449 ** varies from one VFS to another, and from one version of the same VFS to the
1451 ** or all of these interfaces to be NULL or for their behavior to change
1452 ** from one release to the next. Applications must not attempt to access
1463 void *pAppData; /* Pointer to application-specific data */
1499 ** These integer constants can be used as the third parameter to
1525 ** following are the only legal combinations of flags to the
1552 ** The SQLite core will never attempt to acquire or release a
1564 ** These routines are designed to aid in process initialization and
1566 ** SQLite normally do not need to invoke either of these routines.
1568 ** A call to sqlite3_initialize() is an "effective" call if it is
1571 ** following a call to sqlite3_shutdown(). ^(Only an effective call
1575 ** A call to sqlite3_shutdown() is an "effective" call if it is the first
1576 ** call to sqlite3_shutdown() since the last sqlite3_initialize(). ^(Only
1577 ** an effective call to sqlite3_shutdown() does any deinitialization.
1578 ** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
1583 ** other SQLite resources must be deallocated prior to invoking
1591 ** ^If for some reason, sqlite3_initialize() is unable to initialize
1592 ** the library (perhaps it is unable to allocate a needed resource such
1596 ** SQLite interfaces so that an application usually does not need to
1601 ** compile-time option, then the automatic calls to sqlite3_initialize()
1603 ** prior to using any other SQLite interface. For maximum portability,
1605 ** directly prior to using any other SQLite interface. Future releases
1641 ** The sqlite3_config() interface is used to make global configuration
1642 ** changes to SQLite in order to tune SQLite to the specific needs of
1645 ** provided to support rare applications with unusual needs.
1652 ** may only be invoked prior to library initialization using
1659 ** The first argument to sqlite3_config() is an integer
1661 ** what property of SQLite is to be configured. Subsequent arguments
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
1677 ** [sqlite3_config()] except that the changes apply to a single
1680 ** The second argument to sqlite3_db_config(D,V,...) is the
1685 ** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
1697 ** A pointer to an instance of this object is the argument to
1701 ** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
1703 ** memory allocation subsystem for SQLite to use for all of its
1708 ** and that this object is only useful to a tiny minority of applications
1710 ** also used during testing of SQLite in order to specify an alternative
1712 ** order to verify that SQLite recovers gracefully from such
1717 ** ^SQLite guarantees that the second argument to
1718 ** xRealloc is always a value returned by a prior call to xRoundup.
1726 ** allocators round up memory allocations at least to the next multiple
1727 ** of 8. Some allocators round up to a larger multiple or to a power of 2.
1730 ** that causes the corresponding memory allocation to fail.
1736 ** by xInit. The pAppData pointer is used as the only parameter to
1742 ** not need to be threadsafe either. For all other methods, SQLite
1751 ** call to xShutdown().
1759 int (*xRoundup)(int); /* Round up request size to allocation size */
1762 void *pAppData; /* Argument to xInit() and xShutdown() */
1770 ** can be passed as the first argument to the [sqlite3_config()] interface.
1774 ** should check the return code from [sqlite3_config()] to make sure that
1781 ** <dd>There are no arguments to this option. ^This option sets the
1782 ** [threading mode] to Single-thread. In other words, it disables
1786 ** it is not possible to change the [threading mode] from its default
1792 ** <dd>There are no arguments to this option. ^This option sets the
1793 ** [threading mode] to Multi-thread. In other words, it disables
1795 ** The application is responsible for serializing access to
1797 ** are enabled so that SQLite will be safe to use in a multi-threaded
1798 ** environment as long as no two threads attempt to use the same
1801 ** it is not possible to set the Multi-thread [threading mode] and
1806 ** <dd>There are no arguments to this option. ^This option sets the
1807 ** [threading mode] to Serialized. In other words, this option enables
1812 ** to [database connections] and [prepared statements] so that the
1813 ** application is free to use the same [database connection] or the
1817 ** it is not possible to set the Serialized [threading mode] and
1823 ** a pointer to an instance of the [sqlite3_mem_methods] structure.
1825 ** alternative low-level memory allocation routines to be used in place of
1832 ** is a pointer to an instance of the [sqlite3_mem_methods] structure.
1835 ** This option can be used to overload the default memory allocation
1841 ** type int, interpreted as a boolean, which if true provides a hint to
1843 ** SQLite will run faster if it is free to make large memory allocations,
1844 ** but some application might prefer to run slower in exchange for
1876 ** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
1884 ** for the sz parameter to be larger than necessary. The pMem
1885 ** argument must be either a NULL pointer or a pointer to an 8-byte
1888 ** ^When pMem is not NULL, SQLite will strive to use the memory provided
1889 ** to satisfy page cache needs, falling back to [sqlite3_malloc()] if
1897 ** allocation, then SQLite goes to [sqlite3_malloc()] separately for each
1907 ** ^There are three arguments to SQLITE_CONFIG_HEAP:
1908 ** An 8-byte aligned pointer to the memory,
1911 ** to using its default memory allocator (the system malloc() implementation),
1914 ** allocator is engaged to handle all of SQLites memory allocation needs.
1915 ** The first pointer (the memory pointer) must be aligned to an 8-byte
1922 ** pointer to an instance of the [sqlite3_mutex_methods] structure.
1923 ** The argument specifies alternative low-level mutex routines to be used
1925 ** the content of the [sqlite3_mutex_methods] structure before the call to
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
1937 ** This option can be used to overload the default mutex allocation
1938 ** routines with a wrapper used to track mutex usage for performance
1941 ** the entire mutexing subsystem is omitted from the build and hence calls to
1950 ** slots allocated to each database connection.)^ ^(SQLITE_CONFIG_LOOKASIDE
1952 ** option to [sqlite3_db_config()] can be used to change the lookaside
1957 ** a pointer to an [sqlite3_pcache_methods2] object. This object specifies
1958 ** the interface to a custom page cache implementation.)^
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
1969 ** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
1971 ** and a pointer to void. ^If the function pointer is not NULL, it is
1972 ** invoked by [sqlite3_log()] to process each logging event. ^If the
1974 ** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
1975 ** passed through as the first parameter to the application-defined logger
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
1990 ** enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()],
2002 ** argument which is interpreted as a boolean in order to enable or disable
2007 ** The ability to disable the use of covering indices for full table scans
2009 ** when the optimization is enabled. Providing the ability to
2010 ** disable the optimization allows the older, buggy application code to work
2023 ** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
2028 ** points to a buffer containing the name of the main database file. If the
2030 ** points to has just been executed. Or, if the fourth parameter is 2, then
2047 ** ^If either argument to this option is negative, then that argument is
2048 ** changed to its compile-time default.
2060 ** is a pointer to an integer and writes into that integer the number of extra
2069 ** sorter to that integer. The default minimum PMA Size is set by the
2071 ** to help with sort operations when multithreaded sorting
2073 ** to be sorted exceeds the page size times the minimum of the
2079 ** becomes the [statement journal] spill-to-disk threshold.
2081 ** exceeds this threshold, at which point they are written to disk.
2085 ** threshold to a value such as 64KiB can greatly reduce the amount of
2086 ** I/O required to support statement rollback.
2094 ** Usually, when SQLite uses an external sort to order records according
2095 ** to an ORDER BY clause, all fields required by the caller are present in the
2097 ** of a table column that its values are likely to be very large - larger
2101 ** value for this option is to never use this optimization. Specifying a
2152 ** can be passed as the second argument to the [sqlite3_db_config()] interface.
2156 ** should check the return code from [sqlite3_db_config()] to make sure that
2166 ** ^The first argument (the third parameter to [sqlite3_db_config()] is a
2167 ** pointer to a memory buffer to use for lookaside memory.
2173 ** or equal to the product of the second and third arguments. The buffer
2174 ** must be aligned to an 8-byte boundary. ^If the second argument to
2176 ** rounded down to the next smaller multiple of 8. ^(The lookaside memory
2181 ** Any attempt to change the lookaside memory configuration when lookaside
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,
2190 ** positive to enable FK enforcement or negative to leave 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
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,
2201 ** positive to enable triggers or negative to leave the setting unchanged.
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
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,
2218 ** positive to enable views or negative to leave the setting unchanged.
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
2232 ** <dd> ^This option is used to enable or disable the
2236 ** The first argument is an integer which is 0 to disable fts3_tokenizer() or
2237 ** positive to enable fts3_tokenizer() or negative to leave the setting
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
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
2252 ** enabled and the SQL function remains disabled. If the first argument to
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
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
2275 ** connections at all to the database. If so, it performs a checkpoint
2276 ** operation before closing the connection. This option may be used to
2277 ** override this behaviour. The first parameter passed to this operation
2278 ** is an integer - positive to disable checkpoints-on-close, or zero (the
2279 ** default) to enable them, and negative to leave the setting unchanged.
2280 ** The second parameter is a pointer to an integer
2281 ** into which is written 0 or 1 to indicate whether checkpoints-on-close
2294 ** The first argument to this setting is an integer which is 0 to disable
2295 ** the QPSG, positive to enable QPSG, or negative to leave the setting
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 -
2306 ** positive to enable output for trigger programs, or zero to disable it,
2307 ** or negative to leave the setting unchanged.
2308 ** The second parameter is a pointer to an integer into which is written
2309 ** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if
2315 ** [VACUUM] in order to reset a database back to an empty database
2322 ** errors. This step is only necessary if the application desires to keep
2330 ** process requires the use of this obscure API and multiple steps to help
2336 ** flag is enabled, language features that allow ordinary SQL to
2338 ** features include but are not limited to the following:
2343 ** <li> Writes to the [sqlite_dbpage] virtual table.
2344 ** <li> Direct writes to [shadow tables].
2351 ** to setting [PRAGMA writable_schema=ON] or [PRAGMA writable_schema=OFF].
2352 ** The first argument to this setting is an integer which is 0 to disable
2353 ** the writable_schema, positive to enable writable_schema, or negative to
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
2363 ** behaves as it did prior to [version 3.24.0] (2018-06-04). See the
2389 ** <dd>The SQLITE_DBCONFIG_TRUSTED_SCHEMA option tells SQLite to
2392 ** takes additional defensive steps to protect the application from harm
2402 ** This setting defaults to "on" for legacy compatibility, however
2403 ** all applications are advised to turn it off if possible. This setting
2411 ** created database file to have a schema format version number (the 4-byte
2414 ** any SQLite version back to 3.0.0 ([dateof:3.0.0]). Without this setting,
2416 ** prior to 3.3.0 ([dateof:3.3.0]). As these words are written, there
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
2420 ** ability to generate new database files that are compatible with version
2423 ** the [VACUUM] command will fail with an obscure error when attempting to
2484 ** part of committing a transaction (e.g. to flush data accumulated in memory
2485 ** to disk). In this case subsequent calls to this function return the rowid
2486 ** associated with these internal INSERT operations, which leads to
2487 ** unintuitive results. Virtual table implementations that do write to rowid
2490 ** control to the user.
2495 ** by this routine reverts to what it was before the trigger was fired.)^
2497 ** ^An [INSERT] that fails due to a constraint violation is not a
2500 ** and INSERT OR ABORT make no changes to the return value of this
2503 ** INSERT continues to completion after deleting rows that caused
2507 ** ^For the purposes of this routine, an [INSERT] is considered to
2510 ** This function is accessible to SQL statements via the
2526 ** The sqlite3_set_last_insert_rowid(D, R) method allows the application to
2527 ** set the value returned by calling sqlite3_last_insert_rowid(D) to R
2549 ** Changes to a view that are intercepted by
2552 ** DELETE statement run on a view is always zero. Only changes made to real
2610 ** not. ^Changes to a view that are intercepted by INSTEAD OF triggers
2614 ** of rows that changed due to SQL statement run against database
2640 ** ^This function causes any pending database operation to abort and
2642 ** called in response to a user action such as pressing "Cancel"
2643 ** or Ctrl-C where the user wants a long query operation to halt
2646 ** ^It is safe to call this routine from a thread different from the
2648 ** is not safe to call this routine with a [database connection] that
2653 ** to be interrupted and might continue to completion.
2664 ** running prior to the sqlite3_interrupt() call. ^New SQL statements
2667 ** ^A call to sqlite3_interrupt(D) that occurs when there are no running
2676 ** These routines are useful during command-line input to determine if the
2677 ** currently entered text seems to form a complete SQL statement or
2680 ** appears to be a complete SQL statement. ^A statement is judged to be
2695 ** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
2700 ** The input to [sqlite3_complete()] must be a zero-terminated
2703 ** The input to [sqlite3_complete16()] must be a zero-terminated
2716 ** an attempt is made to access a database table associated with
2719 ** The sqlite3_busy_handler() interface is used to implement
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
2730 ** busy callback returns 0, then no additional attempts are made to
2732 ** to the application.
2734 ** is made to access the database and the cycle repeats.
2739 ** to the application instead of invoking the
2742 ** it is trying to promote to a reserved lock and
2744 ** to promote to an exclusive lock. The first process cannot proceed
2749 ** will induce the first process to release its read lock and allow
2750 ** the second process to proceed.
2778 ** the handler returns 0 which causes [sqlite3_step()] to return
2781 ** ^Calling this routine with an argument less than or equal to zero
2786 ** was defined (using [sqlite3_busy_handler()]) prior to calling
2809 ** A result table is an array of pointers to zero-terminated UTF-8 strings.
2811 ** to zero-terminated strings that contain the names of the columns.
2812 ** The remaining entries all point to query results. NULL values result
2817 ** It is not safe to pass a result table directly to [sqlite3_free()].
2848 ** string of its 2nd parameter and returns a result table to the
2852 ** it must pass the result table pointer to sqlite3_free_table() in order to
2855 ** function must not try to call [sqlite3_free()] directly. Only
2856 ** [sqlite3_free_table()] is able to release the memory properly and safely.
2860 ** to any internal data structures of SQLite. It uses only the public
2863 ** reflected in subsequent calls to [sqlite3_errcode()] or
2868 const char *zSql, /* SQL to be evaluated */
2890 ** NULL pointer if [sqlite3_malloc64()] is unable to allocate enough
2891 ** memory to hold the resulting string.
2893 ** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
2900 ** returns a pointer to its buffer instead of the number of
2929 ** ^The sqlite3_malloc() routine returns a pointer to a block
2931 ** ^If sqlite3_malloc() is unable to obtain sufficient free
2932 ** memory, it returns a NULL pointer. ^If the parameter N to
2944 ** to sqlite3_free() is harmless. After being freed, memory
2951 ** ^The sqlite3_realloc(X,N) interface attempts to resize a
2952 ** prior memory allocation X to be at least N bytes.
2953 ** ^If the X parameter to sqlite3_realloc(X,N)
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
2959 ** ^sqlite3_realloc(X,N) returns a pointer to a memory allocation
2976 ** sqlite3_msize(X) returns zero. If X points to something that is not
2977 ** the beginning of memory allocation, or if it points to a formerly
2983 ** is always aligned to at least an 8 byte boundary, or to a
2987 ** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
3020 ** ^The memory high-water mark is reset to the current value of
3021 ** [sqlite3_memory_used()] if and only if the parameter to
3024 ** prior to the reset.
3032 ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
3036 ** applications to access the same PRNG for other purposes.
3038 ** ^A call to this routine stores N bytes of randomness into buffer P.
3045 ** ^If the previous call to this routine had an N of 1 or more and a
3047 ** internally and without recourse to the [sqlite3_vfs] xRandomness
3064 ** to perform various actions, the authorizer callback is invoked to
3066 ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
3067 ** specific action but allow the SQL statement to continue to be
3068 ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
3080 ** ^The first parameter to the authorizer callback is a copy of the third
3081 ** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
3082 ** to the callback is an integer [SQLITE_COPY | action code] that specifies
3083 ** the particular action to be authorized. ^The third through sixth parameters
3084 ** to the callback are either NULL pointers or zero-terminated strings
3085 ** that contain additional details about the action to be authorized.
3086 ** Applications must always be prepared to encounter a NULL pointer in any
3091 ** [prepared statement] statement is constructed to substitute
3094 ** return can be used to deny an untrusted user access to individual
3105 ** SQL statements from an untrusted source, to ensure that the SQL statements
3106 ** do not try to access data they are not allowed to see, or that they do not
3107 ** try to execute malicious statements that damage the database. For
3108 ** example, an application may allow a user to enter arbitrary
3110 ** not want the user to be able to make arbitrary changes to the
3115 ** Applications that need to process SQL from untrusted sources
3118 ** in addition to using an authorizer.
3121 ** at a time. Each call to sqlite3_set_authorizer overrides the
3130 ** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
3131 ** statement might be re-prepared during [sqlite3_step()] due to a
3139 ** sqlite3_prepare_v2() to reprepare a statement after a schema change.
3152 ** to signal SQLite whether or not the action is permitted. See the
3166 ** that is invoked to authorize certain SQL statement actions. The
3167 ** second parameter to the callback is an integer code that specifies
3171 ** These action code values signify what kind of operation is to be
3172 ** authorized. The 3rd and 4th parameters to the authorization
3174 ** codes is used as the second parameter. ^(The 5th parameter to the
3176 ** etc.) if applicable.)^ ^The 6th parameter to the authorizer callback
3235 ** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
3241 ** of how long that statement took to run. ^The profile callback
3260 ** to [sqlite3_trace_v2(D,M,X,P)] is an OR-ed combination of one or more of
3261 ** the following constants. ^The first argument to the trace callback
3269 ** fourth argument to [sqlite3_trace_v2()].
3277 ** trigger subprogram. ^The P argument is a pointer to the
3278 ** [prepared statement]. ^The X argument is a pointer to a string which
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
3290 ** the number of nanosecond that the prepared statement took to run.
3296 ** ^The P argument is a pointer to the [prepared statement] and the
3302 ** ^The P argument is a pointer to the [database connection] object
3322 ** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides
3323 ** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2().
3328 ** implementations should return zero to ensure future compatibility.
3332 ** constants to indicate why the callback was invoked.
3336 ** The sqlite3_trace_v2() interface is intended to replace the legacy
3352 ** function X to be invoked periodically during long running calls to
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
3365 ** old one. ^Setting parameter X to NULL disables the progress handler.
3366 ** ^The progress handler is also disabled by setting N to a value less
3370 ** interrupted. This feature can be used to implement a
3390 ** if SQLite is unable to allocate memory to hold the [sqlite3] object,
3391 ** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
3394 ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
3404 ** passing it to [sqlite3_close()] when it is no longer required.
3408 ** over the new database connection. ^(The flags parameter to
3428 ** In addition to the required flags, the following optional flags are
3444 ** to use SQLite at the same time, as long as each thread is using
3450 ** attempt to use the same database connection at the same time.
3471 ** connection as soon as the connection is created. In addition to setting
3473 ** to return an extended result code.</dd>
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
3483 ** have silently ignored surplus bits in the flags parameter to
3488 ** the open to fail if the database already exists. The SQLITE_OPEN_EXCLUSIVE
3492 ** ^The fourth parameter to sqlite3_open_v2() is the name of the
3503 ** "./" to avoid ambiguity.
3514 ** set in the third argument to sqlite3_open_v2(), or if it has
3522 ** URI filenames are parsed according to RFC 3986. ^If the URI contains an
3525 ** error is returned to the caller. ^The fragment component of a URI, if
3543 ** <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
3545 ** be used to access the database file on disk. ^If this option is set to
3549 ** the value passed as the fourth parameter to sqlite3_open_v2().
3551 ** <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw",
3552 ** "rwc", or "memory". Attempting to set it to any other value is
3556 ** third argument to sqlite3_open_v2(). ^If the mode option is set to
3559 ** been set. ^Value "rwc" is equivalent to setting both
3561 ** set to "memory" then a pure [in-memory database] that never reads
3562 ** or writes from disk is used. ^It is an error to specify a value for
3564 ** the flags passed in the third parameter to sqlite3_open_v2().
3566 ** <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
3567 ** "private". ^Setting it to "shared" is equivalent to setting the
3568 ** SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
3569 ** sqlite3_open_v2(). ^Setting the cache parameter to "private" is
3570 ** equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
3576 ** [powersafe overwrite] property does or does not apply to the
3583 ** or more processes write to the same database and any one of those
3600 ** parameters. See "[query parameters with special meaning to SQLite]" for
3642 ** <b>Note to Windows users:</b> The encoding used for the filename argument
3645 ** characters must be converted to UTF-8 prior to passing them into
3648 ** <b>Note to Windows Runtime users:</b> The temporary directory must be set
3649 ** prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various
3666 const char *zVfs /* Name of VFS module to use */
3672 ** These are utility routines, useful to [VFS|custom VFS implementations],
3676 ** The first parameter to these interfaces (hereafter referred to
3694 ** a pointer to an empty string.
3697 ** parameter and returns true (1) or false (0) according to the value
3712 ** The sqlite3_uri_key(F,N) returns a pointer to the name (not
3715 ** parameters minus 1. The N value is zero-based so N should be 0 to obtain
3727 ** in addition to the main database file. Prior to version 3.31.0, these
3730 ** it has access to all the same query parameters as were found on the
3743 ** These routines are available to [VFS|custom VFS implementations] for
3776 ** sqlite3_database_file_object(X) returns a pointer to the [sqlite3_file]
3783 ** flags parameter to xOpen contains one of the bits
3796 ** The sqlite3_create_filename(D,J,W,N,P) allocates memory to hold a version of
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:
3812 ** must be released by a corresponding call to sqlite3_free_filename(Y).
3815 ** of 2*N pointers to strings. Each pair of pointers in this array corresponds
3816 ** to a key and value for a query parameter. The P parameter may be a NULL
3819 ** None of the D, J, or W parameters to sqlite3_create_filename(D,J,W,N,P) may
3826 ** If the Y parameter to sqlite3_free_filename(Y) is anything other
3833 ** invoked prior to calling sqlite3_free_filename(Y).
3859 ** Except, there are some interfaces that are guaranteed to never
3873 ** ^(Memory to hold the error message string is managed internally.
3874 ** The application does not need to worry about freeing the result.
3876 ** subsequent calls to other SQLite interface functions.)^
3880 ** ^(Memory to hold the error message string is managed internally
3892 ** the time of the first error and the call to these interfaces.
3897 ** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
3898 ** all calls to the interfaces listed here are completed.
3916 ** has been compiled into binary form and is ready to be evaluated.
3927 ** <li> Bind values to [parameters] using the sqlite3_bind_*()
3931 ** to step 2. Do this zero or more times.
3941 ** ^(This interface allows the size of various constructs to be limited
3943 ** [database connection] whose limit is to be set or queried. The
3945 ** class of constructs to be size limited. The third parameter is the
3953 ** (The "_LIMIT_" in the name is changed to "_MAX_".))^
3954 ** ^Attempts to increase a limit above its hard upper bound are
3955 ** silently truncated to the hard upper bound.
3959 ** ^Hence, to find the current value of a limit without changing it,
3960 ** simply invoke this interface with the third parameter set to -1.
3969 ** be given much smaller limits designed to prevent a denial of service
3970 ** attack. Developers might also want to use the [sqlite3_set_authorizer()]
3971 ** interface to further control untrusted SQL. The size of the database
4008 ** used to implement an SQL statement. If [sqlite3_prepare_v2()] or
4009 ** the equivalent tries to allocate space for more than this many opcodes
4020 ** <dd>The maximum length of the pattern argument to the [LIKE] or
4059 ** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
4065 ** on this hint by avoiding the use of [lookaside memory] so as not to
4071 ** to be required for any prepared statement that wanted to use the
4073 ** [sqlite3_normalized_sql()] interface is now available to all
4079 ** to return an error (error code SQLITE_ERROR) if the statement uses
4097 ** The preferred routine to use is [sqlite3_prepare_v2()]. The
4108 ** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
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
4122 ** there is a small performance advantage to passing an nByte parameter that
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
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.
4148 ** original SQL text. This causes the [sqlite3_step()] interface to
4154 ** always used to do, [sqlite3_step()] will automatically recompile the SQL
4155 ** statement and try to run it again. As many as [SQLITE_MAX_SCHEMA_RETRY]
4163 ** and the application would have to make a second call to [sqlite3_reset()]
4164 ** in order to find the underlying cause of the problem. With the "v2" prepare
4169 ** ^If the specific value bound to a [parameter | host parameter] in the
4173 ** to the [sqlite3_bind_text | bindings] of that [parameter].
4176 ** or [GLOB] operator or if the parameter is compared to an indexed column
4192 const char **pzTail /* OUT: Pointer to unused portion of zSql */
4199 const char **pzTail /* OUT: Pointer to unused portion of zSql */
4207 const char **pzTail /* OUT: Pointer to unused portion of zSql */
4214 const void **pzTail /* OUT: Pointer to unused portion of zSql */
4221 const void **pzTail /* OUT: Pointer to unused portion of zSql */
4229 const void **pzTail /* OUT: Pointer to unused portion of zSql */
4236 ** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
4237 ** SQL text used to create [prepared statement] P if P was
4240 ** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
4243 ** ^The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8
4245 ** semantics used to normalize a SQL statement are unspecified and subject
4246 ** to change. At a minimum, literal values will be replaced with suitable
4250 ** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
4256 ** is available to hold the result, or if the result would exceed the
4261 ** option causes sqlite3_expanded_sql() to always return NULL.
4268 ** by passing it to [sqlite3_free()].
4284 ** and only if the [prepared statement] X makes no direct changes to
4301 ** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
4305 ** sqlite3_stmt_readonly() to return true since, while those statements
4307 ** changes to the content of the database files on disk.
4346 ** [sqlite3_step(S)] but has neither run to completion (returned
4350 ** NULL pointer and is not a pointer to a valid [prepared statement]
4354 ** to locate all prepared statements associated with a database
4356 ** for example, in diagnostic routines to search for prepared
4365 ** SQLite uses the sqlite3_value object to represent all values
4375 ** [sqlite3_value_dup()] interface can be used to construct a new
4378 ** The terms "protected" and "unprotected" refer to whether or not
4381 ** sqlite3_value object. If SQLite is compiled to be single-threaded
4398 ** to [sqlite3_result_value()], [sqlite3_bind_value()], and
4409 ** sqlite3_context object. ^A pointer to an sqlite3_context object
4410 ** is always first parameter to [application-defined SQL functions].
4412 ** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
4425 ** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
4442 ** ^The first argument to the sqlite3_bind_*() routines is always
4443 ** a pointer to the [sqlite3_stmt] object returned from
4446 ** ^The second argument is the index of the SQL parameter to be set.
4456 ** ^The third argument is the value to bind to the parameter.
4457 ** ^If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
4460 ** ^If the third parameter to sqlite3_bind_text() is not NULL, then
4461 ** it should be a pointer to well-formed UTF8 text.
4462 ** ^If the third parameter to sqlite3_bind_text16() is not NULL, then
4463 ** it should be a pointer to well-formed UTF16 text.
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
4482 ** ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
4484 ** the number of bytes up to the first zero terminator.
4485 ** If the fourth parameter to sqlite3_bind_blob() is negative, then
4487 ** If a non-negative fourth parameter is provided to sqlite3_bind_text()
4496 ** ^The fifth argument to the BLOB and string binding interfaces controls
4499 ** ^ (1) A destructor to dispose of the BLOB or string after SQLite has finished
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
4503 ** ^ (2) The special constant, [SQLITE_STATIC], may be passsed to indicate that
4505 ** case, the object and the provided pointer to it must remain valid until
4507 ** bound to something else, whichever occurs sooner.
4508 ** ^ (3) The constant, [SQLITE_TRANSIENT], may be passed to indicate that the
4509 ** object is to be copied prior to the return from sqlite3_bind_*(). ^The
4510 ** object and pointer to it must remain valid until then. ^SQLite will then
4513 ** ^The sixth argument to sqlite3_bind_text64() must be one of
4515 ** to specify the encoding of the text in the third parameter. If
4516 ** the sixth argument to sqlite3_bind_text64() is not one of the
4523 ** (just an integer to hold its size) while it is being processed.
4524 ** Zeroblobs are intended to serve as placeholders for BLOBs whose
4530 ** [prepared statement] S to have an SQL value of NULL, but to also be
4532 ** a pointer to a destructor function for P. ^SQLite will invoke the
4579 ** ^This routine can be used to find the number of [SQL parameters]
4583 ** to the parameters at a later time.
4586 ** parameter. For all forms except ?NNN, this will correspond to the
4608 ** and are referred to as "nameless" or "anonymous parameters".
4630 ** parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero
4646 ** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
4648 ** ^Use this routine to reset all host parameters to NULL.
4672 ** ^These routines return the name assigned to a particular column
4674 ** interface returns a pointer to a zero-terminated UTF-8 string
4675 ** and sqlite3_column_name16() returns a pointer to a zero-terminated
4682 ** reprepared by the first call to [sqlite3_step()] for a particular run
4683 ** or until the next call to
4687 ** (for example during a conversion from UTF-8 to UTF-16) then a
4693 ** one release of SQLite to the next.
4702 ** ^These routines provide a means to determine the database, table, and
4711 ** reprepared by the first call to [sqlite3_step()] for a particular run
4718 ** ^The first argument to these interfaces is a [prepared statement].
4763 ** and the following statement to be compiled:
4771 ** is declared to contain a particular type does not mean that the
4775 ** used to hold those values.
4788 ** must be called one or more times to evaluate the statement.
4796 ** interface will continue to be supported.
4803 ** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
4804 ** database locks it needs to do its job. ^If the statement is a [COMMIT]
4812 ** machine without first calling [sqlite3_reset()] to reset the virtual
4813 ** machine back to its initial state.
4818 ** sqlite3_step() is called again to retrieve the next row of data.
4836 ** For all versions of SQLite up to and including 3.6.23.1, a call to
4839 ** sqlite3_step(). Failure to reset the prepared statement using
4847 ** can be used to restore the legacy behavior.
4852 ** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
4870 ** ^If prepared statement P does not have results ready to return
4871 ** (via calls to the [sqlite3_column_int | sqlite3_column()] family of
4874 ** ^The sqlite3_data_count(P) routine returns 0 if the previous call to
4876 ** will return non-zero if previous call to [sqlite3_step](P) returned
4946 ** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
4953 ** If the SQL statement does not currently point to a valid row, or if the
4955 ** These routines may only be called when the most recent call to
4969 ** is used to extract the value) then an automatic type conversion is performed.
4975 ** The return value of sqlite3_column_type() can be used to decide which
4976 ** of the first six interface should be used to extract the column value.
4985 ** or sqlite3_column_bytes16() interfaces can be used to determine the size
4991 ** the string to UTF-8 and then returns the number of bytes.
4993 ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
5000 ** the string to UTF-16 and then returns the number of bytes.
5002 ** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
5017 ** which is native to the platform, regardless of the text encoding set
5026 ** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
5033 ** These routines may attempt to convert the datatype of the result.
5035 ** is requested, [sqlite3_snprintf()] is used internally to perform the
5047 ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
5050 ** <tr><td> FLOAT <td> INTEGER <td> [CAST] to INTEGER
5052 ** <tr><td> FLOAT <td> BLOB <td> [CAST] to BLOB
5053 ** <tr><td> TEXT <td> INTEGER <td> [CAST] to INTEGER
5054 ** <tr><td> TEXT <td> FLOAT <td> [CAST] to REAL
5056 ** <tr><td> BLOB <td> INTEGER <td> [CAST] to INTEGER
5057 ** <tr><td> BLOB <td> FLOAT <td> [CAST] to REAL
5058 ** <tr><td> BLOB <td> TEXT <td> [CAST] to TEXT, ensure zero terminator
5063 ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
5071 ** need to be added to the string.</li>
5074 ** to UTF-16.</li>
5077 ** to UTF-8.</li>
5086 ** The safest policy is to invoke these routines
5096 ** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
5098 ** sqlite3_column_bytes16() to find the size of the result. Do not mix calls
5099 ** to sqlite3_column_text() or sqlite3_column_blob() with calls to
5100 ** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
5101 ** with calls to sqlite3_column_bytes().
5105 ** [sqlite3_finalize()] is called. ^The memory space used to hold strings
5112 ** Only the following subset of interfaces are subject to out-of-memory
5145 ** ^The sqlite3_finalize() function is called to delete a [prepared statement].
5155 ** one or more calls to [sqlite3_reset()], or after any call
5156 ** to [sqlite3_step()] regardless of whether or not the statement has
5161 ** The application must finalize every [prepared statement] in order to avoid
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]
5174 ** object back to its initial state, ready to be re-executed.
5175 ** ^Any SQL statement variables that had values bound to them using
5177 ** Use [sqlite3_clear_bindings()] to reset the bindings.
5180 ** back to the beginning of its program.
5182 ** ^If the most recent call to [sqlite3_step(S)] for the
5187 ** ^If the most recent call to [sqlite3_step(S)] for the
5202 ** are used to add SQL functions or aggregates or to redefine the behavior
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
5214 ** to each database connection separately.
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
5220 ** ^Any attempt to create a function with a longer name
5233 ** its parameters. The application should set this parameter to
5245 ** to signal that the function will always return the same result given
5248 ** function that is not deterministic. The SQLite query planner is able to
5258 ** all application-defined SQL functions that do not need to be
5262 ** Without this flag, an attacker might be able to modify the schema of
5263 ** a database file to include invocations of the function with parameters
5268 ** function can gain access to this pointer using [sqlite3_user_data()].)^
5270 ** ^The sixth, seventh and eighth parameters passed to the three
5272 ** pointers to C-language functions that implement the SQL function or
5281 ** and xInverse) passed to sqlite3_create_window_function are pointers to
5290 ** ^(If the final parameter to sqlite3_create_function_v2() or
5294 ** closes.)^ ^The destructor is also invoked if the call to
5297 ** data pointer which was the fifth parameter to sqlite3_create_function_v2().
5299 ** ^It is permitted to register multiple implementations of the same
5314 ** ^An application-defined function is permitted to call other
5381 ** to [sqlite3_create_function()], [sqlite3_create_function16()], or
5390 ** be deterministic in order to be used in certain contexts such as
5409 ** to cause problems even if misused. An innocuous function should have
5415 ** <p> SQLITE_INNOCUOUS is similar to SQLITE_DETERMINISTIC, but is not
5424 ** are innocuous. Developers are advised to avoid using the
5426 ** function has been carefully audited and found to be free of potentially
5431 ** The SQLITE_SUBTYPE flag indicates to SQLite that a function may call
5432 ** [sqlite3_value_subtype()] to inspect the sub-types of its arguments.
5435 ** function, then any sub-types belonging to arguments passed to the window
5450 ** These functions are [deprecated]. In order to maintain
5452 ** to be supported. However, new applications should avoid
5453 ** the use of these functions. To encourage programmers to avoid
5503 ** are used to pass parameter information into the functions that
5507 ** Any attempt to use these routines on an [unprotected sqlite3_value]
5521 ** and if X and Y are strings that compare equal according to strcmp(X,Y),
5532 ** sqlite3_value_text(V) is called to extract a text value for that
5533 ** integer, then subsequent calls to sqlite3_value_type(V) might return
5535 ** occurs is undefined and may change from one release of SQLite to the next.
5537 ** ^(The sqlite3_value_numeric_type() interface attempts to apply
5538 ** numeric affinity to the value. This means that an attempt is
5539 ** made to convert the value to an integer or floating point. If
5546 ** [SQLITE_UTF16BE], or [SQLITE_UTF16LE] according to the current encoding
5549 ** sqlite3_value_encoding(X) is meaningless. ^Calls to
5553 ** thus change the return from subsequent calls to sqlite3_value_encoding(X).
5557 ** the column corresponding to X is unchanged by the UPDATE operation
5558 ** that the xUpdate method call was invoked to implement and if
5559 ** and the prior [xColumn] method call that was invoked to extracted
5564 ** to be a NULL value. If sqlite3_value_nochange(X) is invoked anywhere other
5573 ** Please pay particular attention to the fact that the pointer returned
5575 ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
5584 ** Only the following subset of interfaces are subject to out-of-memory
5627 ** information can be used to pass a limited amount of context from
5628 ** one SQL function to another. Use the [sqlite3_result_subtype()]
5629 ** routine to set the subtype for the return value of an SQL function.
5638 ** object D and returns a pointer to that copy. ^The [sqlite3_value] returned
5656 ** routine to allocate memory for storing their state.
5661 ** to the new memory. ^On second and subsequent calls to
5672 ** when first called if N is less than or equal to zero or if a memory
5677 ** value of N in any subsequent call to sqlite3_aggregate_context() within
5679 ** allocation.)^ Within the xFinal callback, it is customary to set
5680 ** N=0 in calls to sqlite3_aggregate_context(C,N) so that no
5688 ** to the xStep or xFinal callback routine that implements the aggregate
5716 ** the pointer to the [database connection] (the 1st parameter)
5727 ** These functions may be used by (non-aggregate) SQL functions to
5728 ** associate metadata with argument values. If the same value is passed to
5738 ** ^The sqlite3_get_auxdata(C,N) interface returns a pointer to the metadata
5740 ** value to the application-defined function. ^N is zero for the left-most
5747 ** calls to sqlite3_get_auxdata(C,N) return P from the most recent
5750 ** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
5753 ** SQLite is free to discard the metadata at any time, including: <ul>
5773 ** The value of the N parameter to these interfaces should be non-negative.
5774 ** Future enhancements may make use of negative N values to define new
5788 ** final argument to routines like [sqlite3_result_blob()]. ^If the destructor
5790 ** and will never change. It does not need to be destroyed. ^The
5795 ** The typedef is necessary to work around problems in certain
5812 ** functions used to bind values to host parameters in prepared statements.
5813 ** Refer to the [SQL parameter] documentation for additional information.
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
5821 ** interfaces set the result of the application-defined function to be
5825 ** an application-defined function to be a floating point value specified
5829 ** cause the implemented SQL function to throw an exception.
5830 ** ^SQLite uses the string pointed to by the
5836 ** ^If the third parameter to sqlite3_result_error()
5839 ** ^If the third parameter to sqlite3_result_error() or
5848 ** the error code is SQLITE_ERROR. ^A subsequent call to sqlite3_result_error()
5849 ** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
5851 ** ^The sqlite3_result_error_toobig() interface causes SQLite to throw an
5852 ** error indicating that a string or BLOB is too long to represent.
5854 ** ^The sqlite3_result_error_nomem() interface causes SQLite to throw an
5858 ** of the application-defined function to be the 32-bit signed integer
5861 ** of the application-defined function to be the 64-bit signed integer
5865 ** of the application-defined function to be NULL.
5869 ** set the return value of the application-defined function to be
5873 ** application-defined function to be a text string in an encoding
5878 ** ^If the 3rd parameter to any of the sqlite3_result_text* interfaces
5882 ** ^If the 3rd parameter to the sqlite3_result_text* interfaces
5884 ** pointed to by the 2nd parameter are taken as the application-defined
5891 ** ^If the 4th parameter to the sqlite3_result_text* interfaces
5895 ** ^If the 4th parameter to the sqlite3_result_text* interfaces or to
5900 ** ^If the 4th parameter to the sqlite3_result_text* interfaces
5909 ** string and the rest of the string is interpreted according to the
5918 ** ^For UTF16 input text to the sqlite3_result_text16(),
5925 ** the application-defined function to be a copy of the
5934 ** ^The sqlite3_result_pointer(C,P,T,D) interface sets the result to an
5939 ** ^If the D parameter is not NULL, then it is a pointer to a destructor
5979 ** [sqlite3_context] C to be the value T. Only the lower 8 bits
5997 ** ^Collation names that compare equal according to [sqlite3_strnicmp()] are
5998 ** considered to be the same name.
6009 ** to the collating function callback, xCompare.
6011 ** force strings to be UTF16 with native byte order.
6012 ** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin
6016 ** through as the first argument to the collating function callback.
6018 ** ^The fifth argument, xCompare, is a pointer to the collating function.
6028 ** by the eTextRep argument. The two integer parameters to the collating
6031 ** if the first string is less than, equal to, or greater than the second,
6034 ** to the same collation name (using different eTextRep values) then all
6054 ** calls to the collation creation functions or when the
6061 ** themselves rather than expecting SQLite to deal with it for them.
6095 ** ^To avoid having to register all collation sequences before a database
6097 ** [database connection] to be invoked whenever an undefined collation
6104 ** ^A call to either function replaces the existing collation-needed callback.
6107 ** of the second argument to sqlite3_collation_needed() or
6142 ** The sqlite3_sleep() function causes the current thread to suspend execution
6146 ** millisecond time resolution, then the time will be rounded up to
6161 ** ^(If this global variable is made to point to a string which is
6169 ** It is required to set a temporary folder on Windows Runtime (WinRT).
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
6185 ** it to point to memory obtained from [sqlite3_malloc]. ^Furthermore,
6187 ** that this variable points to is held in memory obtained from
6188 ** [sqlite3_malloc] and the pragma may attempt to free that memory
6191 ** made NULL or made to point to memory obtained from [sqlite3_malloc]
6194 ** does not free the memory that sqlite3_temp_directory points to. If
6195 ** the application wants that memory to be freed, it must do
6196 ** so itself, taking care to only do so after all [database connection]
6199 ** <b>Note to Windows Runtime users:</b> The temporary directory must be set
6200 ** prior to calling [sqlite3_open] or [sqlite3_open_v2]. Otherwise, various
6202 ** example of how to do this using C++ with the Windows Runtime:
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
6225 ** with a relative pathname are relative to the current directory
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
6242 ** it to point to memory obtained from [sqlite3_malloc]. ^Furthermore,
6244 ** that this variable points to is held in memory obtained from
6245 ** [sqlite3_malloc] and the pragma may attempt to free that memory
6248 ** made NULL or made to point to memory obtained from [sqlite3_malloc]
6257 ** [sqlite3_win32_set_directory] interface is used to set the value associated
6258 ** with the [sqlite3_temp_directory] or [sqlite3_data_directory] variable, to
6260 ** should be NULL to cause the previous value to be freed via [sqlite3_free];
6262 ** prior to being used. The [sqlite3_win32_set_directory] interface returns
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
6283 ** for the type argument to the [sqlite3_win32_set_directory] interface.
6302 ** transaction might be rolled back automatically. The only way to
6304 ** an error is to use this function.
6317 ** to which a [prepared statement] belongs. ^The [database connection]
6320 ** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
6329 ** ^The sqlite3_db_name(D,N) interface returns a pointer to the schema name
6332 ** the "temp" schema. Larger values of N correspond to various ATTACH-ed
6335 ** Space to hold the string that is returned by sqlite3_db_name() is managed
6337 ** changes the schema, including [ATTACH] or [DETACH] or calls to
6339 ** occur on a different thread. Applications that need to
6342 ** threads should mutex-protect calls to this API and should make their own
6343 ** private copy of the result prior to releasing the mutex.
6351 ** ^The sqlite3_db_filename(D,N) interface returns a pointer to the filename
6364 ** to open the database originally was a URI or relative pathname.
6367 ** can be used as the filename input parameter to these routines:
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
6413 ** constants in order to describe the transaction state of schema S
6425 ** will advanced to SQLITE_TXN_WRITE if any changes occur and there are
6427 ** state will revert to SQLITE_TXN_NONE following a [ROLLBACK] or
6432 ** in a write transaction. Content has been written to the database file
6433 ** but has not yet committed. The transaction state will change to
6434 ** to SQLITE_TXN_NONE at the next [ROLLBACK] or [COMMIT].</dd>
6444 ** ^This interface returns a pointer to the next [prepared statement] after
6446 ** then this interface returns a pointer to the first prepared statement
6450 ** The [database connection] pointer D in a call to
6451 ** [sqlite3_next_stmt(D,S)] must refer to an open database
6461 ** function to be invoked whenever a transaction is [COMMIT | committed].
6462 ** ^Any callback set by a previous call to sqlite3_commit_hook()
6465 ** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
6466 ** ^Any callback set by a previous call to sqlite3_rollback_hook()
6468 ** ^The pArg argument is passed through to the callback.
6480 ** to modify the database connection must be deferred until after the
6490 ** operation is allowed to continue normally. ^If the commit hook
6495 ** ^For the purposes of this API, a transaction is said to have been
6497 ** an error or constraint causes an implicit rollback to occur.
6511 ** function C that is invoked prior to each autovacuum of the database
6518 ** ^If the value returned is greater than or equal to the number of
6526 ** not attempt to invoke any other SQLite interface. If it does, bad
6531 ** ^The X parameter to sqlite3_autovacuum_pages(D,C,P,X) is an optional
6537 ** ^Each call to the sqlite3_autovacuum_pages() interface overrides all
6539 ** argument (C) to sqlite3_autovacuum_pages(D,C,P,X) is a NULL pointer,
6548 ** then the default behavior is to vacuum all free pages. So, in other
6578 ** to be invoked whenever a row is updated, inserted or deleted in
6580 ** ^Any callback set by a previous call to this function
6583 ** ^The second argument is a pointer to the function to invoke when a
6585 ** ^The first argument to the callback is a copy of the third argument
6586 ** to sqlite3_update_hook().
6589 ** to be invoked.
6590 ** ^The third and fourth arguments to the callback contain pointers to the
6608 ** to modify the database connection must be deferred until after the
6632 ** to the same database. Sharing is enabled if the argument is true
6646 ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
6647 ** Existing database connections continue to use the sharing mode
6655 ** continues to be provided for historical compatibility, but its use is
6676 ** ^The sqlite3_release_memory() interface attempts to free N bytes
6678 ** held by the database library. Memory used to cache database
6679 ** pages to improve performance is an example of non-essential memory.
6693 ** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap
6711 ** ^SQLite strives to keep heap memory utilization below the soft heap
6714 ** ^The soft heap limit is "soft" because even though SQLite strives to stay
6721 ** sqlite3_hard_heap_limit64(N) interface is similar to
6727 ** the heap limit prior to the call, or negative in the case of an
6729 ** then no change is made to the heap limit. Hence, the current
6733 ** ^Setting the heap limits to zero disables the heap limiter mechanism.
6738 ** the soft heap limit is set to the value of the hard heap limit.
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.
6793 ** ^If the column-name parameter to sqlite3_table_column_metadata() is a
6796 ** does not. If the table name parameter T in a call to
6800 ** ^The column is identified by the second, third and fourth parameters to
6804 ** for the table using the same algorithm used by the database engine to
6807 ** ^The third and fourth parameters to this function are the table and column
6810 ** ^Metadata is returned by writing to the memory locations passed as the 5th
6811 ** and subsequent parameters to this function. ^Any of these arguments may be
6826 ** ^The memory pointed to by the character pointers returned for the
6828 ** call to any SQLite API function.
6847 ** ^This function causes all database schemas to be read from disk and
6869 ** ^The sqlite3_load_extension() interface attempts to load an
6871 ** the file cannot be loaded directly, attempts are made to load
6878 ** ^(zProc may be 0, in which case SQLite will try to come up with an
6882 ** characters in the filename from the last "/" to the first following
6887 ** [sqlite3_load_extension()] interface shall attempt to
6895 ** prior to calling this API,
6899 ** [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method be used to enable only this
6903 ** access to extension loading capabilities.
6918 ** ^So as not to open security holes in older applications that are
6919 ** unprepared to deal with [extension loading], and as a means of disabling
6921 ** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
6925 ** to turn extension loading on and call it with onoff==0 to turn
6931 ** to enable or disable only the C-API.)^
6937 ** access to extension loading capabilities.
6944 ** ^This interface causes the xEntryPoint() function to be invoked for
6947 ** that is to be automatically loaded into all new database connections.
6963 ** point to an appropriate error message (obtained from [sqlite3_mprintf()])
6983 ** initialization routine X that was registered using a prior call to
7000 ** The interface to the virtual-table mechanism is currently considered
7001 ** to be experimental. The interface might change in incompatible ways.
7025 ** instance of this structure and passing a pointer to that instance
7026 ** to [sqlite3_create_module()] or [sqlite3_create_module_v2()].
7075 ** of the [virtual table] interface to
7078 ** inputs to xBestIndex and are read-only. xBestIndex inserts its
7094 ** and makes other simplifications to the WHERE clause in an attempt to
7097 ** relevant to the particular virtual table being queried.
7105 ** passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62),
7108 ** to the right of the first 63 is required, then bit 63 of colUsed is also
7110 ** (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to
7114 ** about what parameters to pass to xFilter. ^If argvIndex>0 then
7117 ** is true, then the constraint is assumed to be fully handled by the
7121 ** checked separately in byte code. If the omit flag is change to true, then
7128 ** ^[sqlite3_free()] is used to free idxPtr if and only if
7132 ** the correct order to satisfy the ORDER BY clause so that no separate
7137 ** to a linear scan of an SQLite table with N rows. A cost of log(N)
7138 ** indicates that the expense of the operation is similar to that of a
7150 ** SQLite also assumes that if a call to the xUpdate() method is made as
7151 ** part of the same statement to delete or update a virtual table row and the
7152 ** implementation returns SQLITE_CONSTRAINT, then there is no need to rollback
7159 ** IMPORTANT: The estimatedRows field was added to the sqlite3_index_info
7163 ** to read or write the estimatedRows field are undefined (but are likely
7164 ** to include crashing the application). The estimatedRows field should
7166 ** value greater than or equal to 3008002. Similarly, the idxFlags field
7169 ** sqlite3_libversion_number() returns a value greater than or equal to
7188 int argvIndex; /* if >0, constraint is part of argv to xFilter */
7191 int idxNum; /* Number used to identify the index */
7207 ** Virtual table implementations are allowed to set the
7208 ** [sqlite3_index_info].idxFlags field to some combination of
7230 ** value 255 are reserved to represent functions that are overloaded
7239 ** sqlite3_vtab_rhs_value() probably will not be able to extract it.
7242 ** and hence calls to sqlite3_vtab_rhs_value() for those operators will
7245 ** The collating sequence to be used for comparison can be found using
7273 ** ^These routines are used to register a new [virtual table module] name.
7280 ** second parameter. ^The third parameter is a pointer to
7287 ** is a pointer to a destructor for the pClientData. ^SQLite will
7290 ** be invoked if the call to sqlite3_create_module_v2() fails.
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
7302 sqlite3 *db, /* SQLite connection to register module with */
7308 sqlite3 *db, /* SQLite connection to register module with */
7321 ** The L parameter must be either NULL or a pointer to an array of pointers
7322 ** to strings where the array is terminated by a single NULL pointer.
7337 ** of this object to describe a particular instance
7339 ** be tailored to the specific needs of the module implementation.
7340 ** The purpose of this superclass is to define certain fields that are
7341 ** common to all module implementations.
7344 ** string obtained from [sqlite3_mprintf()] to zErrMsg. The method should
7345 ** take care that any prior string is freed by a call to [sqlite3_free()]
7346 ** prior to assigning a new string to zErrMsg. ^After the error message
7347 ** is delivered up to the client application, the string will be automatically
7362 ** following structure to describe cursors that point into the
7364 ** to loop through the virtual table. Cursors are created using the
7369 ** the content of a cursor structure to suit its own needs.
7371 ** This superclass exists in order to define fields of the cursor that
7372 ** are common to all implementations.
7384 ** to declare the format (the names and datatypes of the columns) of
7396 ** must exist in order to be overloaded.)^
7401 ** of the new function always causes an exception to be thrown. So
7403 ** purpose is to be a placeholder function that can be overloaded
7409 ** The interface to the virtual-table mechanism defined above (back up
7410 ** to a comment remarkably similar to this one) is currently considered
7411 ** to be experimental. The interface might change in incompatible ways.
7427 ** can be used to read or write small subsections of the BLOB.
7437 ** ^(This interfaces opens a [BLOB handle | handle] to the BLOB located
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()]
7483 ** [sqlite3_blob_write()]. The [BLOB handle] can be moved to a
7488 ** ^(If the row that a BLOB handle points to is modified by an
7493 ** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
7495 ** ^(Changes written into a BLOB prior to the BLOB expiring are not
7497 ** commit if the transaction continues to completion.)^
7499 ** ^Use the [sqlite3_blob_bytes()] interface to determine the size of
7501 ** interface. Use the [UPDATE] SQL command to change the size of a
7505 ** and the built-in [zeroblob] SQL function may be used to create a
7506 ** zero-filled blob to read or write using the incremental-blob interface.
7509 ** be released by a call to [sqlite3_blob_close()].
7526 ** CAPI3REF: Move a BLOB Handle to a New Row
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
7533 ** remain the same. Moving an existing [BLOB handle] to a new row is
7541 ** ^All subsequent calls to [sqlite3_blob_read()], [sqlite3_blob_write()] or
7566 ** with a null pointer (such as would be returned by a failed call to
7583 ** by a prior successful call to [sqlite3_blob_open()] and which has not
7585 ** to this routine results in undefined and probably undesirable behavior.
7593 ** ^(This function is used to read data from an open [BLOB handle] into a
7603 ** ^An attempt to read from an expired [BLOB handle] fails with an
7610 ** by a prior successful call to [sqlite3_blob_open()] and which has not
7612 ** to this routine results in undefined and probably undesirable behavior.
7622 ** ^(This function is used to write data into an open [BLOB handle] from a
7633 ** writing (the flags parameter to [sqlite3_blob_open()] was zero),
7637 ** not possible to increase the size of a BLOB using this API.
7644 ** ^An attempt to write to an expired [BLOB handle] fails with an
7645 ** error code of [SQLITE_ABORT]. ^Writes to the BLOB that occurred
7652 ** by a prior successful call to [sqlite3_blob_open()] and which has not
7654 ** to this routine results in undefined and probably undesirable behavior.
7664 ** that SQLite uses to interact
7670 ** ^The sqlite3_vfs_find() interface returns a pointer to a VFS given its name.
7699 ** permitted to use any of these routines.
7727 ** mutex and returns a pointer to it. ^The sqlite3_mutex_alloc()
7728 ** routine returns NULL if it is unable to allocate the requested
7729 ** mutex. The argument to sqlite3_mutex_alloc() must one of these
7750 ** cause sqlite3_mutex_alloc() to create
7753 ** The mutex implementation does not need to make a distinction
7755 ** not want to. SQLite will only request a recursive mutex in
7758 ** might return such a mutex in response to SQLITE_MUTEX_FAST.
7760 ** ^The other allowed parameters to sqlite3_mutex_alloc() (anything other
7762 ** a pointer to a static preexisting mutex. ^Nine static mutexes are
7776 ** allocated dynamic mutex. Attempting to deallocate a static
7780 ** to enter a mutex. ^If another thread is already within the mutex,
7787 ** can enter.)^ If the same thread tries to enter any mutex other
7801 ** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
7817 ** used to allocate and use mutexes.
7823 ** creates and populates an instance of this structure to pass
7824 ** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option.
7832 ** effective call to [sqlite3_initialize()].
7836 ** implementation of this method is expected to release all outstanding
7839 ** interface is invoked exactly once for each call to [sqlite3_shutdown()].
7858 ** by this structure are not required to handle this case. The results
7860 ** (i.e. it is acceptable to provide an implementation that segfaults if
7863 ** The xMutexInit() method must be threadsafe. It must be harmless to
7865 ** intervening calls to xMutexEnd(). Second and subsequent calls to
7874 ** called, but only if the prior call to xMutexInit returned SQLITE_OK.
7875 ** If xMutexInit fails in any way, it is expected to clean up after itself
7876 ** prior to returning.
7897 ** are advised to follow the lead of the core. The SQLite core only
7900 ** are only required to provide these routines if SQLITE_DEBUG is
7906 ** The implementation is not required to provide versions of these
7911 ** If the argument to sqlite3_mutex_held() is a NULL pointer then
7916 ** call to sqlite3_mutex_held() to fail, so a non-zero return is
7917 ** the appropriate thing to do. The sqlite3_mutex_notheld()
7931 ** The set of static mutexes may change from one SQLite release to the
7933 ** prepared to accommodate additional static mutexes.
7961 ** serializes access to the [database connection] given in the argument
7973 ** ^The [sqlite3_file_control()] interface makes a direct call to the
7979 ** ^A NULL pointer can be used in place of "main" to refer to the
7981 ** ^The third and fourth parameters to this routine
7982 ** are passed directly through to the second and third parameters of
7990 ** a pointer to the underlying [sqlite3_file] object to be written into
7991 ** the space pointed to by the 4th parameter. The
7995 ** a pointer to the underlying [sqlite3_vfs] object for the file.
8003 ** also return SQLITE_ERROR. There is no way to distinguish between
8014 ** ^The sqlite3_test_control() interface is used to read out internal
8015 ** state of SQLite and to inject faults into SQLite for testing
8024 ** they take, and what they do are all subject to change without notice.
8025 ** Unlike most of the SQLite API, this function is not guaranteed to
8026 ** operate consistently from one release to the next.
8034 ** as the first argument to [sqlite3_test_control()].
8036 ** These parameters and their meanings are subject to change
8078 ** These routines provide access to the set of SQL language keywords
8079 ** recognized by SQLite. Applications can uses these routines to determine
8080 ** whether or not a specific identifier needs to be escaped (for example,
8081 ** by enclosing in double-quotes) so as not to confuse the parser.
8087 ** makes *Z point to that keyword expressed as UTF8 and writes the number
8088 ** of bytes in the keyword into *L. The string that *Z points to is not
8091 ** or L are NULL or invalid pointers then calls to
8094 ** The sqlite3_keyword_check(Z,L) interface checks to see whether or not
8095 ** the L-byte UTF8 identifier that Z points to is a keyword, returning non-zero
8098 ** The parser used by SQLite is forgiving. It is often possible to use
8103 ** "REPLACE", "PRAGMA", and "END". Nevertheless, best practice is to avoid
8104 ** using keywords as identifiers. Common techniques used to avoid keyword
8108 ** SQL way to escape identifier names.
8120 ** new keywords may be added to future releases of SQLite.
8136 ** <li> ^Text is appended to the sqlite3_str object using various
8150 ** [sqlite3_str_new()] must be freed by a subsequent call to
8153 ** ^The [sqlite3_str_new(D)] interface always returns a pointer to a
8159 ** [sqlite3_str_finish(X)]. It is always safe to use the value
8161 ** to any of the other [sqlite3_str] methods.
8163 ** The D parameter to [sqlite3_str_new(D)] may be NULL. If the
8176 ** and returns a pointer to a memory buffer obtained from [sqlite3_malloc64()]
8178 ** pass the returned value to [sqlite3_free()] to avoid a memory leak.
8190 ** These interfaces add content to an sqlite3_str object previously obtained
8195 ** functionality of SQLite to append formatted text onto the end of
8209 ** ^This method can be used, for example, to add whitespace indentation.
8212 ** inside [sqlite3_str] object X back to zero bytes in length.
8216 ** subsequent call to [sqlite3_str_errcode(X)].
8243 ** ^The [sqlite3_str_value(X)] method returns a pointer to the current
8251 ** outside the range of 0 to [sqlite3_str_length(X)] and do not read or
8261 ** ^These interfaces are used to retrieve runtime status information
8262 ** about the performance of SQLite, and optionally to reset various
8264 ** the specific parameter to measure. ^(Recognized integer codes
8278 ** If either the current value or the highwater mark is too large to
8304 ** figure includes calls made to [sqlite3_malloc()] by the application
8312 ** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their
8314 ** *pHighwater parameter to [sqlite3_status()] is of interest.
8331 ** buffer and where forced to overflow to [sqlite3_malloc()]. The
8333 ** where too large (they were larger than the "sz" parameter to
8339 ** handed to the [pagecache memory allocator]. Only the value returned in the
8340 ** *pHighwater parameter to [sqlite3_status()] is of interest.
8358 ** New status parameters may be added from time to time.
8375 ** ^This interface is used to retrieve runtime status information
8377 ** database connection object to be interrogated. ^The second argument
8380 ** determines the parameter to interrogate. The set of
8382 ** to grow in future releases of SQLite.
8387 ** reset back down to the current value.
8401 ** the second argument to the [sqlite3_db_status()] interface.
8405 ** [sqlite3_db_status()] to make sure that the call worked.
8422 ** been satisfied using lookaside memory but failed due to the amount of
8430 ** been satisfied using lookaside memory but failed due to all lookaside
8442 ** <dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a
8454 ** memory used to store the schema for all databases associated
8457 ** schema memory is shared with other database connections due to
8482 ** been written to disk. Specifically, the number of pages written to the
8483 ** wal file in wal mode databases, or the number of pages written to the
8486 ** If an IO or other error occurs while writing a page to disk, the effect
8493 ** been written to disk in the middle of a transaction due to the page
8495 ** to disk all at once. When pages spill mid-transaction, that introduces
8530 ** be used to monitor the performance characteristics of the prepared
8532 ** the number of table searches or result rows, that would tend to indicate
8536 ** ^(This interface is used to retrieve and reset counter values from
8538 ** object to be interrogated. The second argument
8540 ** to be interrogated.)^
8542 ** ^If the resetFlg is true, then the counter is reset to zero after this
8566 ** A non-zero value in this counter may indicate an opportunity to
8571 ** were created automatically in order to help joins run faster.
8572 ** A non-zero value in this counter may indicate an opportunity to
8574 ** need to be reinitialized each time the statement is run.</dd>
8579 ** to 2147483647. The number of virtual machine operations can be
8586 ** automatically regenerated due to schema changes or changes to
8592 ** or more calls to [sqlite3_step()] followed by a call to [sqlite3_reset()].
8604 ** had to be processed as normal.
8608 ** used to store the prepared statement. ^This value is not actually
8609 ** a counter, and so the resetFlg parameter to sqlite3_stmt_status()
8631 ** to the object.
8642 ** object. Various methods of the page cache use pointers to instances
8665 ** that memory is allocated and released, and the policies used to
8673 ** ^(The contents of the sqlite3_pcache_methods2 structure are copied to an
8674 ** internal buffer by SQLite within the call to [sqlite3_config]. Hence
8675 ** the application may discard the parameter after the call to
8680 ** call to [sqlite3_initialize()])^
8683 ** The intent of the xInit() method is to set up global data structures
8691 ** It can be used to clean up
8695 ** ^SQLite automatically serializes calls to the xInit method,
8698 ** not need to be threadsafe either. All other methods must be threadsafe
8702 ** call to xShutdown().
8705 ** ^SQLite invokes the xCreate() method to construct a new cache instance.
8713 ** extra szExtra bytes on each page to store metadata about the underlying
8716 ** ^The third argument to xCreate(), bPurgeable, is true if the cache being
8717 ** created will be used to cache database pages of a file stored on disk, or
8719 ** does not have to do anything special based with the value of bPurgeable;
8721 ** never invoke xUnpin() except to deliberately delete a page.
8722 ** ^In other words, calls to xUnpin() on a cache with bPurgeable set to
8723 ** false will always have the "discard" flag set to true.
8728 ** ^(The xCachesize() method may be called at any time by SQLite to set the
8732 ** parameter, the implementation is not required to do anything with this
8740 ** The xFetch() method locates a page in the cache and returns a pointer to
8743 ** pointer to a buffer of szPage bytes used to store the content of a
8745 ** a pointer to the szExtra bytes of extra storage that SQLite has requested
8748 ** The page to be fetched is determined by the key. ^The minimum key value
8750 ** to be "pinned".
8753 ** implementation must return a pointer to the page buffer with its content
8756 ** parameter to help it determined what action to take:
8761 ** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
8763 ** <tr><td> 2 <td> Make every effort to allocate a new page. Only return
8770 ** attempt to unpin one or more cache pages by spilling the content of
8771 ** pinned pages to disk and synching the operating system disk cache.
8774 ** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
8780 ** may choose to evict unpinned pages at any time.
8783 ** call to xUnpin() unpins the page regardless of the number of prior calls
8784 ** to xFetch().
8787 ** The xRekey() method is used to change the key value associated with the
8791 ** to be pinned.
8795 ** to the value of the iLimit parameter passed to xTruncate(). If any
8800 ** ^The xDestroy() method is used to delete a cache allocated by xCreate().
8807 ** ^SQLite invokes the xShrink() method when it wants the page cache to
8809 ** is not obligated to free any memory, but well-behaved implementations should
8856 ** a call to [sqlite3_backup_init()] and is destroyed by a call to
8868 ** for copying in-memory databases to or from persistent files.
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
8889 ** There should be exactly one call to sqlite3_backup_finish() for each
8890 ** successful call to sqlite3_backup_init().
8894 ** ^The D and N arguments to sqlite3_backup_init(D,N,S,M) are the
8900 ** ^The S and M arguments passed to
8907 ** ^A call to sqlite3_backup_init() will fail, returning NULL, if
8914 ** ^The error code and message for the failed call to sqlite3_backup_init()
8917 ** ^A successful call to sqlite3_backup_init() returns a pointer to an
8920 ** sqlite3_backup_finish() functions to perform the specified backup
8925 ** ^Function sqlite3_backup_step(B,N) will copy up to N pages between
8929 ** are still more pages to be copied, then the function returns [SQLITE_OK].
8931 ** from source to destination, then it returns [SQLITE_DONE].
8934 ** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
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()
8956 ** case the call to sqlite3_backup_step() can be retried later on. ^(If
8959 ** there is no point in retrying the call to sqlite3_backup_step(). These
8962 ** to the sqlite3_backup_finish() to release associated resources.
8964 ** ^The first call to sqlite3_backup_step() obtains an exclusive lock
8967 ** and sqlite3_backup_step() returns [SQLITE_DONE]. ^Every call to
8970 ** ^Because the source database is not locked between calls to
8975 ** restarted by the next call to sqlite3_backup_step(). ^If the source
8983 ** application wishes to abandon the backup operation, the application
8984 ** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish().
8990 ** and may not be used following a call to sqlite3_backup_finish().
9007 ** to be backed up at the conclusion of the most recent sqlite3_backup_step().
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
9029 ** sqlite3_backup_finish(). SQLite does not currently check to see
9039 ** backed up to is not accessed by any connection within the process,
9040 ** not just the specific connection that was passed to sqlite3_backup_init().
9043 ** threads may safely make multiple concurrent calls to sqlite3_backup_step().
9068 ** ^This API may be used to register a callback that SQLite will invoke
9078 ** ^When a connection (known as the blocked connection) fails to obtain a
9079 ** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
9084 ** the first argument to register for a callback that will be invoked
9093 ** from within the call to sqlite3_unlock_notify().)^
9095 ** ^If the blocked connection is attempting to obtain a write-lock on a
9098 ** the other connections to use as the blocking connection.
9119 ** single void* pointer that is passed to the callback when it is invoked.
9120 ** However, the signature of the callback function allows SQLite to pass
9121 ** it an array of void* context pointers. The first argument passed to
9122 ** an unlock-notify callback is a pointer to an array of void* pointers,
9131 ** This gives the application an opportunity to prioritize any actions
9132 ** related to the set of unblocked database connections.
9137 ** database waits for the callback to be issued before taking any further
9139 ** application to deadlock. For example, if connection X is waiting for
9140 ** connection Y's transaction to be concluded, and similarly connection
9145 ** detection. ^If a given call to sqlite3_unlock_notify() would put the
9147 ** unlock-notify callback is registered. The system is said to be in
9152 ** the system is also considered to be deadlocked if connection B has
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
9169 ** One way around this problem is to check the extended error code returned
9171 ** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
9177 void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */
9178 void *pNotifyArg /* Argument to pass to xNotify */
9186 ** and extensions to compare the contents of two buffers containing UTF-8
9218 ** the ESCAPE clause, set the E parameter of [sqlite3_strlike(P,X,E)] to 0.
9237 ** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()].
9239 ** used with [sqlite3_snprintf()] to generate the final output string.
9243 ** nothing to prevent an application from calling sqlite3_log(), doing so
9251 ** a few hundred characters, it will be truncated to the length of the
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.
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
9270 ** ^The third parameter is the name of the database that was written to -
9277 ** SQLite code base to cause the statement that provoked the callback
9278 ** to report an error, though the commit will have still occurred. If the
9280 ** that does not correspond to any valid SQLite error code, the results
9303 ** to automatically [checkpoint]
9314 ** ^The [wal_autocheckpoint pragma] can be used to invoke this interface
9320 ** ^Every new [database connection] defaults to having the auto-checkpoint
9323 ** is only necessary if the default setting is found to be suboptimal
9332 ** ^(The sqlite3_wal_checkpoint(D,X) is equivalent to
9336 ** [write-ahead log] for database X on [database connection] D to be
9337 ** transferred into the database file and for the write-ahead log to
9341 ** This interface used to be the only way to cause a checkpoint to
9344 ** compatibility and as a convenience for applications that need to manually
9356 ** information is written back into integers pointed to by L and C.)^
9362 ** readers or writers to finish, then sync the database file if all frames
9374 ** but new database readers are allowed to continue unimpeded.
9387 ** addition that it also truncates the log file to zero bytes just prior
9388 ** to a successful return.
9391 ** ^If pnLog is not NULL, then *pnLog is set to the total number of frames in
9392 ** the log file or to -1 if the checkpoint could not run because
9394 ** NULL,then *pnCkpt is set to the total number of checkpointed frames in the
9396 ** was called) or to -1 if the checkpoint could not run due to an error or
9399 ** truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.
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
9420 ** values written to output parameters *pnLog and *pnCkpt are undefined. ^If
9425 ** and the error code is returned to the caller immediately. ^If no error
9430 ** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. ^If
9432 ** attached database, SQLITE_ERROR is returned to the caller.
9439 ** ^The [PRAGMA wal_checkpoint] command can be used to invoke this interface
9455 ** as the third parameter to the [sqlite3_wal_checkpoint_v2()] interface.
9468 ** of a [virtual table] implementation to configure
9476 ** which is passed in as the first argument to the [xConnect] or [xCreate]
9489 ** These macros define the various options to the
9491 ** can use to customize and optimize their behavior.
9501 ** a call to the [xUpdate] method returns [SQLITE_CONSTRAINT], then the entire
9508 ** any modifications to internal or persistent data structures have been made.
9510 ** is able to roll back a statement or database transaction, and abandon
9516 ** Virtual table implementations that are required to handle OR REPLACE
9517 ** must do so within the [xUpdate] method. If a call to the
9522 ** SQLITE_CONSTRAINT, in which case SQLite falls back to OR ABORT
9538 ** identify that virtual table as being safe to use from within triggers
9553 ** This function may only be called from within a call to the [xUpdate] method
9556 ** [SQLITE_ABORT], or [SQLITE_REPLACE], according to the [ON CONFLICT] mode
9557 ** of the SQL statement that triggered the call to the [xUpdate] method of the
9569 ** this hint as permission to substitute a return value that is less
9570 ** expensive to compute and that the corresponding
9581 ** implementations should continue to give a correct answer even if the
9582 ** sqlite3_vtab_nochange() interface were to always return false. In the
9592 ** This function may only be called from within a call to the [xBestIndex]
9593 ** method of a [virtual table]. This function returns a pointer to a string
9594 ** that is the name of the appropriate collation sequence to use for text
9597 ** The first argument must be the pointer to the [sqlite3_index_info] object
9598 ** that is the first parameter to the xBestIndex() method. The second argument
9599 ** must be an index into the aConstraint[] array belonging to the
9600 ** sqlite3_index_info structure passed to xBestIndex.
9604 ** xBestMethod() method. The first parameter may not be a pointer to a
9634 ** planner wants the output to be ordered. As long as the virtual table
9640 ** that the query planner needs the virtual table to return all rows in the
9644 ** the xBestIndex method to set the "orderByConsumed" flag, regardless of
9648 ** that the query planner does not need the rows to be returned in sorted order
9658 ** needs to be returned.)^ ^It is always ok for two or more rows with the same
9659 ** values in all "aOrderBy" columns to be returned, as long as all such rows
9667 ** rows to be sorted.)^ ^The virtual table implementation is free to omit
9668 ** rows that are identical in all aOrderBy columns, if it wants to, but
9669 ** it is not required to omit any rows. This mode is used for queries
9673 ** ^For the purposes of comparing virtual table output values to see if the
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
9685 ** [bytecode] to ensure that the final results returned by the SQL query are
9689 ** flag might help queries against a virtual table to run faster. Being
9691 ** valid to do so, on the other hand, might cause SQLite to return incorrect
9706 ** communicated to the xBestIndex method as a
9707 ** [SQLITE_INDEX_CONSTRAINT_EQ] constraint.)^ If xBestIndex wants to use
9709 ** aConstraintUsage[].argvIndex to a postive integer. ^(Then, under
9717 ** table to see all values on the right-hand of the IN operator all at
9722 ** ^A call to sqlite3_vtab_in(P,N,-1) will return true (non-zero)
9730 ** ^A call to sqlite3_vtab_in(P,N,F) with F==1 or F==0 indicates
9731 ** to SQLite that the virtual table does or does not want to process
9734 ** which the virtual table tells SQLite how it wants to process 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
9755 ** <li><p> The last call to sqlite3_vtab_in(P,N,F) for which F was
9761 ** ^If both conditions are true, then the argvIndex-th parameter to the
9762 ** xFilter method will be an [sqlite3_value] that appears to be NULL,
9763 ** but which can be passed to [sqlite3_vtab_in_first()] and
9764 ** [sqlite3_vtab_in_next()] to find all values on the right-hand side
9777 ** The X parameter in a call to sqlite3_vtab_in_first(X,P) or
9778 ** sqlite3_vtab_in_next(X,P) must be one of the parameters to the
9787 ** ^(Use these routines to access all values on the right-hand side
9803 ** routines return SQLITE_OK and set *P to point to the first or next value
9805 ** right hand side of the IN constraint, then *P is set to NULL and these
9810 ** next call to either of these routines or until the end of the xFilter
9812 ** implementation needs to retain the *ppOut values for longer, it must make
9830 ** attempts to set *V to the value of the right-hand operand of
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)
9843 ** to some other column or a [host parameter], then sqlite3_vtab_rhs_value()
9864 ** These constants are returned by [sqlite3_vtab_on_conflict()] to
9882 ** The following constants can be used for the T parameter to the
9884 ** different metric for sqlite3_stmt_scanstatus() to return.
9886 ** When the value returned to V is a string, space to hold that string is
9892 ** <dd>^The [sqlite3_int64] variable pointed to by the V parameter will be
9893 ** set to the total number of times that the X-th loop has run.</dd>
9896 ** <dd>^The [sqlite3_int64] variable pointed to by the V parameter will be set
9897 ** to the total number of rows examined by all iterations of the X-th loop.</dd>
9900 ** <dd>^The "double" variable pointed to by the V parameter will be set to the
9908 ** <dd>^The "const char *" variable pointed to by the V parameter will be set
9909 ** to a zero-terminated UTF-8 string containing the name of the index or table
9913 ** <dd>^The "const char *" variable pointed to by the V parameter will be set
9914 ** to a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN]
9918 ** <dd>^The "int" variable pointed to by the V parameter will be set to the
9938 ** interface to compare the predicted and the measured performance and
9941 ** Since this interface is expected to be rarely used, it is only
9945 ** The "iScanStatusOp" parameter determines which status information to return.
9948 ** ^The requested measurement is written into a variable pointed to by
9950 ** Parameter "idx" identifies the specific loop to retrieve statistics for.
9952 ** zero or greater than or equal to the total number of loops used to implement
9954 ** points to is unchanged.
9959 ** that pOut points to unchanged.
9965 int idx, /* Index of loop to report on */
9982 ** CAPI3REF: Flush caches to disk mid-transaction
9988 ** to disk. A dirty page may be in use if a database cursor created by an
9994 ** ^If this function needs to obtain extra database locks before dirty pages
9995 ** can be flushed to disk, it does so. ^If those locks cannot be obtained
9998 ** the database is skipped and an attempt made to flush any dirty pages
9999 ** belonging to the next (if any) database. ^If any databases are skipped
10003 ** ^If any other error occurs while flushing dirty pages to disk (for
10005 ** abandoned and an SQLite [error code] is returned to the caller immediately.
10022 ** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation
10025 ** [database connection]; each call to [sqlite3_preupdate_hook()] overrides
10029 ** ^The third parameter to [sqlite3_preupdate_hook()] is passed through as
10030 ** the first parameter to callbacks.
10032 ** ^The preupdate hook only fires for changes to real database tables; the
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
10039 ** [SQLITE_INSERT], [SQLITE_DELETE], or [SQLITE_UPDATE] to identify the
10040 ** kind of update operation that is about to occur.
10041 ** ^(The fourth parameter to the preupdate callback is the name of the
10046 ** ^The fifth parameter to the preupdate callback is the name of the
10050 ** parameter passed to the preupdate callback is the initial [rowid] of the
10055 ** or updated. The value of the seventh parameter passed to the callback
10065 ** to the preupdate callback results in undefined and probably undesirable
10071 ** ^The [sqlite3_preupdate_old(D,N,P)] interface writes into P a pointer to
10077 ** behavior is undefined. The [sqlite3_value] that P points to
10080 ** ^The [sqlite3_preupdate_new(D,N,P)] interface writes into P a pointer to
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,
10110 void *pCtx, /* Copy of third arg to preupdate_hook() */
10115 sqlite3_int64 iKey1, /* Rowid of row about to be deleted/updated */
10131 ** ^Attempt to return the underlying operating system error code or error
10132 ** number that caused the most recent I/O error or failure to open a file.
10135 ** called to get back the underlying "errno" that caused the problem, such
10152 ** Subsequent changes to the database from other connections are not seen
10156 ** version of the database file so that it is possible to later open a new read
10168 ** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a
10171 ** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly
10176 ** The following must be true for this function to succeed. If any of
10189 ** <li> One or more transactions must have been written to the current wal
10193 ** must be written to it first.
10200 ** The [sqlite3_snapshot] object returned from a successful call to
10202 ** to avoid a memory leak.
10219 ** [database connection] D such that the read transaction refers to
10220 ** historical [snapshot] P, rather than the most recent change to the
10224 ** ^In order to succeed, the database connection must not be in
10228 ** to sqlite3_step() but not sqlite3_reset() or sqlite3_finalize()).
10232 ** ^A call to sqlite3_snapshot_open() will fail to open if the specified
10244 ** ^(A call to [sqlite3_snapshot_open(D,S,P)] will fail if the
10251 ** database connection in order to make it ready to use snapshots.)
10268 ** using this routine to avoid a memory leak.
10279 ** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages
10288 ** database is changed back to rollback mode or when the number of database
10289 ** clients drops to zero. If either snapshot handle was obtained before the
10293 ** Otherwise, this API returns a negative value if P1 refers to an older
10294 ** snapshot than P2, zero if the two handles refer to the same database
10311 ** or because the last process to have the database opened exited without
10314 ** will only be able to open the last transaction added to the WAL file
10317 ** This function attempts to scan the WAL file associated with database zDb
10318 ** of database handle db and make all valid snapshots available to
10333 ** The sqlite3_serialize(D,S,P,F) interface returns a pointer to memory
10341 ** to disk if that database where backed up to disk.
10345 ** a pointer to that memory. The caller is responsible for freeing the
10346 ** returned value to avoid a memory leak. However, if the F argument
10349 ** to the contiguous memory representation of the database that SQLite
10353 ** been a prior call to [sqlite3_deserialize(D,S,...)] with the same
10359 ** A call to sqlite3_serialize(D,S,P,F) might return NULL even if the
10368 const char *zSchema, /* Which DB to serialize. ex: "main", "temp", ... */
10377 ** the F argument to [sqlite3_serialize(D,S,P,F)].
10380 ** a pointer to contiguous in-memory database that it is currently using,
10383 ** [sqlite3_serialize()] to return a NULL pointer. SQLite will only be
10385 ** prior call to [sqlite3_deserialize()].
10393 ** [database connection] D to disconnect from database S and then
10398 ** permitted to add content to the in-memory database as long as the total
10404 ** SQLite will try to increase the buffer size using sqlite3_realloc64()
10405 ** if writes on the database cause it to grow larger than M bytes.
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
10417 ** [sqlite3_free()] is invoked on argument P prior to returning.
10424 const char *zSchema, /* Which DB to reopen with the deserialization */
10434 ** The following are allowed values for 6th argument (the F argument) to
10443 ** The SQLITE_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed to
10444 ** grow the size of the database using calls to [sqlite3_realloc64()]. This
10457 ** Undo the hack that converts floating point types to integer for