Lines Matching defs:is
2 ** This file is an amalgamation of many separate C source files from SQLite
7 ** of 5% or more are commonly seen when SQLite is compiled as a single
10 ** This file is all you need to compile SQLite. To use SQLite in other
17 ** language. The code for the "sqlite3" command-line shell is also in a
30 ** a legal notice, here is a blessing:
49 ** measured by branch coverage. This is
53 ** OPTIMIZATION-IF-TRUE - This branch is allowed to alway be false
54 ** and the correct answer is still obtained,
57 ** OPTIMIZATION-IF-FALSE - This branch is allowed to alway be true
58 ** and the correct answer is still obtained,
71 ** Make sure the Tcl calling convention macro is defined. This macro is
79 ** Make sure that rand_s() is available on Windows systems with MSVC 2005
98 ** a legal notice, here is a blessing:
106 ** This file contains code that is specific to MSVC.
143 ** a legal notice, here is a blessing:
151 ** This file contains code that is specific to Wind River's VxWorks
154 /* This is VxWorks. Set up things specially for that OS
165 /* This is not VxWorks. */
178 ** large file support, or if the OS is windows, these should be no-ops.
185 ** on the compiler command line. This is necessary if you are compiling
188 ** without this option, LFS is enable. But LFS does not exist in the kernel
192 ** The previous paragraph was written in 2005. (This paragraph is written
197 ** Similar is true for Mac OS X. LFS is only supported on Mac OS X 9 and later.
207 /* What version of GCC is being used. 0 means GCC is not being used */
227 ** files; however, the contained version information is now required by this
229 ** this is the only known way to reliably obtain it. This entire #if block
245 ** define is required to maintain binary compatibility with the MSVC runtime
265 ** a legal notice, here is a blessing:
274 ** or constant definition does not appear in this file, then it is
275 ** not a published API of SQLite, is subject to change without
284 ** The official C-language API documentation for SQLite is derived
285 ** from comments in this file. This file is the authoritative source
288 ** The name of this file under configuration management is "sqlite.h.in".
360 ** evaluates to a string literal that is the SQLite version in the
361 ** format "X.Y.Z" where X is the major version number (always 3 for
362 ** SQLite3) and Y is the minor version number and Z is the release number.)^
367 ** be larger than the release from which it is derived. Either Y will
396 ** the header, and thus ensure that the application is
408 ** function is provided for use in DLLs since DLL users usually do not have
412 ** a pointer to a string constant whose value is the same as the
432 ** returning the N-th compile time option string. ^If N is out of range,
434 ** prefix is omitted from any strings returned by
457 ** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
458 ** are enabled and SQLite is threadsafe. When the
459 ** [SQLITE_THREADSAFE] macro is 0,
460 ** the mutexes are omitted. Without the mutexes, it is not safe
464 ** So if speed is of utmost importance, it makes sense to disable
466 ** ^The default behavior is for mutexes to be enabled.
469 ** version of SQLite that it is linking against was compiled with
473 ** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with
481 ** is unchanged by calls to sqlite3_config().)^
491 ** Each open SQLite database is represented by a pointer to an instance of
492 ** the opaque structure named "sqlite3". It is useful to think of an sqlite3
507 ** Because there is no cross-platform way to specify 64-bit integer types
547 ** the [sqlite3] object is successfully destroyed and all associated
550 ** ^If the database connection is associated with unfinalized prepared
553 ** ^If sqlite3_close_v2() is called with unfinalized prepared statements
556 ** last prepared statement is finalized or the last sqlite3_backup is
557 ** finished. The sqlite3_close_v2() interface is intended for use with
559 ** destructors are called is arbitrary.
565 ** sqlite3_close_v2() is called on a [database connection] that still has
568 ** of resources is deferred until all [prepared statements], [BLOB handles],
571 ** ^If an [sqlite3] object is destroyed while a transaction is open,
572 ** the transaction is automatically rolled back.
580 ** argument is a harmless no-op.
587 ** This is legacy and deprecated. It is included for historical
588 ** compatibility and is not documented.
596 ** The sqlite3_exec() interface is a convenience wrapper around
605 ** sqlite3_exec() is not NULL, then it is invoked for each result row
607 ** sqlite3_exec() is relayed through to the 1st argument of each
609 ** is NULL, then no callback is ever invoked and result rows are
615 ** is not NULL then any error message is written into memory obtained
619 ** sqlite3_exec() after the error message string is no longer needed.
620 ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
628 ** ^The 2nd argument to the sqlite3_exec() callback function is the
630 ** callback is an array of pointers to strings obtained as if from
632 ** result row is NULL then the corresponding string pointer for the
633 ** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
634 ** sqlite3_exec() callback is an array of pointers to strings where each
638 ** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
641 ** is not changed.
647 ** is a valid and open [database connection].
649 ** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
651 ** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
679 #define SQLITE_BUSY 5 /* The database file is locked */
680 #define SQLITE_LOCKED 6 /* A table in the database is locked */
685 #define SQLITE_CORRUPT 11 /* The database disk image is malformed */
687 #define SQLITE_FULL 13 /* Insertion failed because database is full */
690 #define SQLITE_EMPTY 16 /* Database is empty */
700 #define SQLITE_NOTADB 26 /* File opened that is not a database file */
814 ** object returns an integer which is a vector of these
822 ** are aligned to an address which is an integer multiple of
824 ** that when data is appended to a file, the data is appended
825 ** first then the size of the file is extended, never the other
827 ** information is written to disk in the same order as calls
834 ** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
873 ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
903 ** for their own use. The pMethods entry is a pointer to an
925 ** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
929 ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
930 ** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
944 ** either in this process or in some other process, is holding a RESERVED,
948 ** The xFileControl() method is a generic interface that allows custom
950 ** [sqlite3_file_control()] interface. The second "op" argument is an
951 ** integer opcode. The third argument is a generic pointer intended to
958 ** A [file control opcodes | list of opcodes] less than 100 is available.
965 ** device that underlies the file. The sector size is the
988 ** are aligned to an address which is an integer multiple of
990 ** that when data is appended to a file, the data is appended
991 ** first then the size of the file is extended, never the other
993 ** information is written to disk in the same order as calls
1039 ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
1044 ** is used during testing and is only available when the SQLITE_TEST
1045 ** compile-time option is used.
1048 ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
1050 ** current transaction. This hint is not guaranteed to be accurate but it
1051 ** is often close. The underlying VFS might choose to preallocate database
1056 ** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
1065 ** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
1070 ** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
1079 ** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
1080 ** sent to the VFS immediately before the xSync method is invoked on a
1081 ** database file descriptor. Or, if the xSync method is not invoked
1083 ** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place
1085 ** this file-control is NULL. However, if the database file is being synced
1093 ** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite
1095 ** but before the database is unlocked. VFSes that do not need this signal
1101 ** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
1110 ** within the same process. The argument is a pointer to an array of two
1112 ** integer is the delay. If either integer is negative, then the setting
1113 ** is not changed but instead the prior value of that setting is written
1115 ** interrogated. The zDbName parameter is ignored.
1118 ** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
1123 ** close. Persisting the files is useful when other processes that do not
1128 ** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
1129 ** WAL mode. If the integer is -1, then it is overwritten with the current
1133 ** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
1138 ** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
1139 ** mode. If the integer is -1, then it is overwritten with the current
1143 ** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening
1144 ** a write transaction to indicate that, unless it is rolled back for some
1146 ** transaction. This is used by VACUUM operations.
1152 ** [sqlite3_malloc()] and the result is stored in the char* variable
1154 ** The caller is responsible for freeing the memory when done. As with
1155 ** all file-control actions, there is no guarantee that this will actually
1157 ** pointer in case this file-control is not implemented. This file-control
1158 ** is intended for diagnostic use only.
1170 ** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]
1171 ** file control is sent to the open [sqlite3_file] object corresponding
1173 ** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
1175 ** is the name of the pragma and the third element is the argument to the
1185 ** prepared statement if result string is NULL, or that returns a copy
1186 ** of the result string if the string is non-NULL.
1192 ** it is able to override built-in [PRAGMA] statements.
1197 ** shortly after it is opened in order to provide a custom VFS with access
1198 ** to the connections busy-handler callback. The argument is of type (void **)
1209 ** temporary filename using the same algorithm that is followed to generate
1216 ** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the
1218 ** The argument is a pointer to a value of type sqlite3_int64 that
1219 ** is an advisory maximum number of bytes in the file to memory map. The
1220 ** pointer is overwritten with the old value. The limit is not changed if
1221 ** the value originally pointed to is negative, and so the current limit
1223 ** file-control is used internally to implement [PRAGMA mmap_size].
1228 ** This file control is used by some VFS activity tracing [shims].
1229 ** The argument is a zero-terminated string. Higher layers in the
1231 ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
1240 ** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This
1242 ** pointed to by the pArg argument. This capability is used during testing
1243 ** and only needs to be supported when SQLITE_TEST is defined.
1246 ** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might
1247 ** be advantageous to block on the next WAL lock if the lock is not immediately
1253 ** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other
1257 ** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
1311 ** A pointer to the opaque sqlite3_api_routines structure is passed as
1326 ** The value of the iVersion field is initially 1 but may be larger in
1328 ** object when the iVersion value is increased. Note that the structure
1333 ** The szOsFile field is the size of the subclassed [sqlite3_file]
1334 ** structure used by this VFS. mxPathname is the maximum length of
1344 ** The pNext field is the only field in the sqlite3_vfs
1355 ** is either a NULL pointer or string obtained
1357 ** ^If a suffix is added to the zFilename parameter, it will
1361 ** the string will be valid and unchanged until xClose() is
1365 ** If the zFilename parameter to xOpen is a NULL pointer then xOpen
1367 ** xFilename parameter is NULL it will also be the case that the
1372 ** or [sqlite3_open16()] is used, then flags includes at least
1408 ** deleted when it is closed. ^The [SQLITE_OPEN_DELETEONCLOSE]
1412 ** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
1416 ** SQLITE_OPEN_CREATE, is used to indicate that file should always
1417 ** be created, and that it is an error if it already exists.
1418 ** It is <i>not</i> used to indicate the file should be opened
1434 ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
1435 ** to test whether a file is at least readable. The file can be a
1440 ** is also passed as a parameter to both methods. If the output buffer
1441 ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
1449 ** of good-quality randomness into zOut. The return value is
1459 ** date and time if that method is available (if iVersion is 2 or
1460 ** greater and the function pointer is not NULL) and will fall back
1461 ** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
1473 ** any of these methods if the iVersion of the VFS is less than 3.
1521 ** what kind of permissions the xAccess method is looking for.
1525 ** checks whether the named directory is both readable and writable
1528 ** The SQLITE_ACCESS_READWRITE constant is currently used only by the
1532 ** checks whether the file is readable. The SQLITE_ACCESS_READ constant is
1588 ** A call to sqlite3_initialize() is an "effective" call if it is
1589 ** the first time sqlite3_initialize() is invoked during the lifetime of
1590 ** the process, or if it is the first time sqlite3_initialize() is invoked
1595 ** A call to sqlite3_shutdown() is an "effective" call if it is the first
1600 ** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
1601 ** is not. The sqlite3_shutdown() interface must only be called from a
1611 ** ^If for some reason, sqlite3_initialize() is unable to initialize
1612 ** the library (perhaps it is unable to allocate a needed resource such
1615 ** ^The sqlite3_initialize() routine is called internally by many other
1619 ** initialized when [sqlite3_open()] is called if it has not be initialized
1620 ** already. ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
1624 ** it is recommended that applications always invoke sqlite3_initialize()
1627 ** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
1641 ** interface is called automatically by sqlite3_initialize() and
1642 ** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
1644 ** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
1661 ** The sqlite3_config() interface is used to make global configuration
1663 ** the application. The default configuration is recommended for most
1664 ** applications and so this routine is usually not necessary. It is
1667 ** <b>The sqlite3_config() interface is not threadsafe. The application
1669 ** threads while sqlite3_config() is running.</b>
1674 ** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
1679 ** The first argument to sqlite3_config() is an integer
1681 ** what property of SQLite is to be configured. Subsequent arguments
1685 ** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
1686 ** ^If the option is unknown or SQLite is unable to set the option
1695 ** The sqlite3_db_config() interface is used to make configuration
1696 ** changes to a [database connection]. The interface is similar to
1700 ** The second argument to sqlite3_db_config(D,V,...) is the
1702 ** that indicates what aspect of the [database connection] is being configured.
1706 ** the call is considered successful.
1716 ** This object is used in only one place in the SQLite interface.
1717 ** A pointer to an instance of this object is the argument to
1718 ** [sqlite3_config()] when the configuration option is
1728 ** and that this object is only useful to a tiny minority of applications
1729 ** with specialized memory allocation requirements. This object is
1738 ** xRealloc is always a value returned by a prior call to xRoundup.
1742 ** is always at least as big as the requested size but may be larger.
1754 ** structures. The xShutdown method is invoked (indirectly) by
1756 ** by xInit. The pAppData pointer is used as the only parameter to
1761 ** xShutdown method is only called from [sqlite3_shutdown()] so it does
1764 ** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
1765 ** it is by default) and so the methods are automatically serialized.
1766 ** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
1797 ** is invoked.
1804 ** by a single thread. ^If SQLite is compiled with
1806 ** it is not possible to change the [threading mode] from its default
1815 ** The application is responsible for serializing access to
1819 ** [database connection] at the same time. ^If SQLite is compiled with
1821 ** it is not possible to set the Multi-thread [threading mode] and
1830 ** In this mode (which is the default when SQLite is compiled with
1833 ** application is free to use the same [database connection] or the
1835 ** ^If SQLite is compiled with
1837 ** it is not possible to set the Serialized [threading mode] and
1842 ** <dd> ^(The SQLITE_CONFIG_MALLOC option takes a single argument which is
1852 ** is a pointer to an instance of the [sqlite3_mem_methods] structure.
1854 ** structure is filled with the currently defined memory allocation routines.)^
1870 ** ^Memory allocation statistics are enabled by default unless SQLite is
1885 ** ^SQLite will never request a scratch buffer that is more than 6
1888 ** scratch memory beyond what is provided by this configuration option, then
1901 ** This configuration option is a no-op if an application-define page
1902 ** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
1910 ** ^It is harmless, apart from the wasted memory,
1914 ** subsequent behavior is undefined.
1915 ** ^When pMem is not NULL, SQLite will strive to use the memory provided
1917 ** a page cache line is larger than sz bytes or if all of the pMem buffer
1918 ** is exhausted.
1919 ** ^If pMem is NULL and N is non-zero, then each database connection
1921 ** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
1922 ** of -1024*N bytes if N is negative, . ^If additional
1923 ** page cache memory is needed beyond what is provided by the initial
1932 ** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
1938 ** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
1941 ** memory pointer is not NULL then the alternative memory
1942 ** allocator is engaged to handle all of SQLites memory allocation needs.
1945 ** The minimum allocation size is capped at 2**12. Reasonable values
1949 ** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
1954 ** [sqlite3_config()] returns. ^If SQLite is compiled with
1956 ** the entire mutexing subsystem is omitted from the build and hence calls to
1962 ** is a pointer to an instance of the [sqlite3_mutex_methods] structure. The
1964 ** structure is filled with the currently defined mutex routines.)^
1967 ** profiling or testing, for example. ^If SQLite is compiled with
1969 ** the entire mutexing subsystem is omitted from the build and hence calls to
1976 ** The first argument is the
1977 ** size of each lookaside buffer slot and the second is the number of
1984 ** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
1991 ** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies of
1995 ** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
1999 ** and a pointer to void. ^If the function pointer is not NULL, it is
2001 ** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
2002 ** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
2004 ** function whenever that function is invoked. ^The second parameter to
2005 ** the logger function is a copy of the first parameter to the corresponding
2006 ** [sqlite3_log()] call and is intended to be a [result code] or an
2007 ** [extended result code]. ^The third parameter passed to the logger is
2009 ** The SQLite logging interface is not reentrant; the logger function
2016 ** If non-zero, then URI handling is globally enabled. If the parameter is zero,
2017 ** then URI handling is globally disabled.)^ ^If URI handling is globally
2021 ** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
2022 ** connection is opened. ^If it is globally disabled, filenames are
2023 ** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
2024 ** database connection is opened. ^(By default, URI handling is globally
2030 ** argument which is interpreted as a boolean in order to enable or disable
2032 ** ^The default setting is determined
2033 ** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
2034 ** if that compile-time option is omitted.
2036 ** is because some incorrectly coded legacy applications might malfunction
2037 ** when the optimization is enabled. Providing the ability to
2049 ** <dd>This option is only available if sqlite is compiled with the
2052 ** The second should be of type (void*). The callback is invoked by the library
2054 ** fourth parameter. If the fourth parameter is 0, then the database connection
2057 ** fourth parameter is 1, then the SQL statement that the third parameter
2058 ** points to has just been executed. Or, if the fourth parameter is 2, then
2059 ** the connection being passed as the second parameter is being closed. The
2060 ** third parameter is passed NULL In this case. An example of using this
2075 ** ^If either argument to this option is negative, then that argument is
2080 ** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
2088 ** is a pointer to an integer and writes into that integer the number of extra
2096 ** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
2097 ** sorter to that integer. The default minimum PMA Size is set by the
2100 ** is enabled (using the [PRAGMA threads] command) and the amount of content
2110 ** Or if the threshold is -1, statement journals are always held
2115 ** The default value for this setting is controlled by the
2130 /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
2157 ** is invoked.
2163 ** ^The first argument (the third parameter to [sqlite3_db_config()] is a
2167 ** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
2168 ** size of each lookaside buffer slot. ^The third argument is the number of
2172 ** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
2175 ** connection is not currently using lookaside memory, or in other words
2177 ** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
2179 ** memory is in use leaves the configuration unchanged and returns
2183 ** <dd> ^This option is used to enable or disable the enforcement of
2185 ** The first argument is an integer which is 0 to disable FK enforcement,
2187 ** unchanged. The second parameter is a pointer to an integer into which
2188 ** is written 0 or 1 to indicate whether FK enforcement is off or on
2190 ** which case the FK enforcement setting is not reported back. </dd>
2193 ** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
2195 ** The first argument is an integer which is 0 to disable triggers,
2197 ** The second parameter is a pointer to an integer into which
2198 ** is written 0 or 1 to indicate whether triggers are disabled or enabled
2200 ** which case the trigger setting is not reported back. </dd>
2203 ** <dd> ^This option is used to enable or disable the two-argument
2204 ** version of the [fts3_tokenizer()] function which is part of the
2207 ** The first argument is an integer which is 0 to disable fts3_tokenizer() or
2210 ** The second parameter is a pointer to an integer into which
2211 ** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled
2213 ** which case the new setting is not reported back. </dd>
2216 ** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()]
2221 ** When the first argument to this interface is 1, then only the C-API is
2223 ** this interface is 0, then both the C-API and the SQL function are disabled.
2224 ** If the first argument is -1, then no changes are made to state of either the
2226 ** The second parameter is a pointer to an integer into which
2227 ** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface
2228 ** is disabled or enabled following this call. The second parameter may
2229 ** be a NULL pointer, in which case the new setting is not reported back.
2257 ** integer key called the [ROWID | "rowid"]. ^The rowid is always available
2261 ** is another alias for the rowid.
2273 ** row as long as the trigger or virtual table method is running.
2278 ** ^An [INSERT] that fails due to a constraint violation is not a
2288 ** ^For the purposes of this routine, an [INSERT] is considered to
2289 ** be successful even if it is subsequently rolled back.
2291 ** This function is accessible to SQL statements via the
2296 ** function is running and thus changes the last insert [rowid],
2297 ** then the value returned by [sqlite3_last_insert_rowid()] is
2320 ** DELETE statement run on a view is always zero. Only changes made to real
2323 ** Things are more complicated if the sqlite3_changes() function is
2324 ** executed while a trigger program is running. This may happen if the
2330 ** sqlite3_changes() function is saved. After the trigger program
2331 ** has finished, the original value is restored.)^
2340 ** ^This means that if the changes() SQL function (or similar) is used
2343 ** ^If it is used by the second or subsequent such statement within a trigger
2351 ** while [sqlite3_changes()] is running then the value returned
2352 ** is unpredictable and not meaningful.
2375 ** while [sqlite3_total_changes()] is running then the value
2376 ** returned is unpredictable and not meaningful.
2385 ** return at its earliest opportunity. This routine is typically
2390 ** ^It is safe to call this routine from a thread different from the
2391 ** thread that is currently running the database operation. But it
2392 ** is not safe to call this routine with a [database connection] that
2393 ** is closed or might close before sqlite3_interrupt() returns.
2395 ** ^If an SQL operation is very nearly finished at the time when
2396 ** sqlite3_interrupt() is called, then it might not have an opportunity
2399 ** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
2400 ** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
2401 ** that is inside an explicit transaction, then the entire transaction
2404 ** ^The sqlite3_interrupt(D) call is in effect until all currently running
2412 ** SQL statements is a no-op and has no effect on SQL statements
2416 ** is running then bad things will likely happen.
2425 ** if additional input is needed before sending the text into
2427 ** appears to be a complete SQL statement. ^A statement is judged to be
2428 ** complete if it ends with a semicolon token and is not a prefix of a
2435 ** ^These routines return 0 if the statement is incomplete. ^If a
2436 ** memory allocation fails, then SQLITE_NOMEM is returned.
2442 ** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
2445 ** regardless of whether or not the input SQL is complete.)^
2463 ** an attempt is made to access a database table associated with
2466 ** The sqlite3_busy_handler() interface is used to implement
2469 ** ^If the busy callback is NULL, then [SQLITE_BUSY]
2470 ** is returned immediately upon encountering the lock. ^If the busy callback
2471 ** is not NULL, then the callback might be invoked with two arguments.
2473 ** ^The first argument to the busy handler is a copy of the void* pointer which
2474 ** is the third argument to sqlite3_busy_handler(). ^The second argument to
2475 ** the busy handler callback is the number of times that the busy handler has
2478 ** access the database and [SQLITE_BUSY] is returned
2481 ** is made to access the database and the cycle repeats.
2484 ** when there is lock contention. ^If SQLite determines that invoking the busy
2488 ** Consider a scenario where one process is holding a read lock that
2489 ** it is trying to promote to a reserved lock and
2490 ** a second process is holding a reserved lock that it is trying
2492 ** because it is blocked by the second and the second process cannot
2493 ** proceed because it is blocked by the first. If both processes
2499 ** ^The default busy callback is NULL.
2509 ** the busy handler is not reentrant. Any such actions
2522 ** for a specified amount of time when a table is locked. ^The handler
2534 ** this routine, that other busy handler is cleared.)^
2544 ** This is a legacy interface that is preserved for backwards compatibility.
2545 ** Use of this interface is not recommended.
2547 ** Definition: A <b>result table</b> is memory data structure created by the
2556 ** A result table is an array of pointers to zero-terminated UTF-8 strings.
2564 ** It is not safe to pass a result table directly to [sqlite3_free()].
2568 ** is as follows:
2579 ** result table has 8 entries. Suppose the result table is stored
2603 ** [sqlite3_free_table()] is able to release the memory properly and safely.
2605 ** The sqlite3_get_table() interface is implemented as a wrapper around
2637 ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
2640 ** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
2641 ** the standard C library. The result is written into the
2642 ** buffer supplied as the second parameter whose size is given by
2644 ** first two parameters is reversed from snprintf().)^ This is an
2653 ** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
2654 ** guarantees that the buffer is always zero-terminated. ^The first
2655 ** parameter "n" is the total size of the buffer, including space for
2659 ** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
2664 ** is are "%q", "%Q", "%w" and "%z" options.
2668 ** %q is designed for use inside a string literal.)^ By doubling each '\''
2686 ** Because the %q format string is used, the '\'' character in zText
2687 ** is escaped and the SQL generated is as follows:
2693 ** This is correct. Had we used %s instead of %q, the generated SQL
2700 ** This second example is an SQL syntax error. As a general rule you should
2705 ** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
2715 ** variable even if the zText variable is a NULL pointer.
2717 ** ^(The "%w" formatting option is like "%q" except that it expects to
2720 ** character.)^ The "%w" formatting option is intended for safely inserting
2725 ** the result, [sqlite3_free()] is called on the input string.)^
2741 ** of memory at least N bytes in length, where N is the parameter.
2742 ** ^If sqlite3_malloc() is unable to obtain sufficient free
2744 ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
2748 ** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
2753 ** that it might be reused. ^The sqlite3_free() routine is
2754 ** a no-op if is called with a NULL pointer. Passing a NULL pointer
2755 ** to sqlite3_free() is harmless. After being freed, memory
2759 ** might result if sqlite3_free() is called with a non-NULL pointer that
2765 ** is a NULL pointer then its behavior is identical to calling
2767 ** ^If the N parameter to sqlite3_realloc(X,N) is zero or
2768 ** negative then the behavior is exactly the same as calling
2771 ** of at least N bytes in size or NULL if insufficient memory is available.
2772 ** ^If M is the size of the prior allocation, then min(N,M) bytes
2774 ** by sqlite3_realloc(X,N) and the prior allocation is freed.
2775 ** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the
2776 ** prior allocation is not freed.
2779 ** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
2782 ** ^If X is a memory allocation previously obtained from sqlite3_malloc(),
2786 ** of bytes requested when X was allocated. ^If X is a NULL pointer then
2787 ** sqlite3_msize(X) returns zero. If X points to something that is not
2790 ** of sqlite3_msize(X) is undefined and possibly harmful.
2794 ** is always aligned to at least an 8 byte boundary, or to a
2796 ** option is used.
2801 ** is no longer provided. Only built-in memory allocators can be used.
2806 ** and whatever filename encoding is used by the particular Windows
2844 ** ^The memory high-water mark is reset to the current value of
2846 ** [sqlite3_memory_highwater()] is true. ^The value returned
2847 ** by [sqlite3_memory_highwater(1)] is the high-water mark
2858 ** already uses the largest possible [ROWID]. The PRNG is also used for
2866 ** call had N less than one or a NULL pointer for P, then the PRNG is
2870 ** non-NULL P then the pseudo-randomness is generated
2882 ** ^The authorizer callback is invoked as SQL statements are being compiled
2885 ** points during the compilation process, as logic is being created
2886 ** to perform various actions, the authorizer callback is invoked to
2897 ** requested is ok. ^When the callback returns [SQLITE_DENY], the
2900 ** access is denied.
2902 ** ^The first parameter to the authorizer callback is a copy of the third
2904 ** to the callback is an integer [SQLITE_COPY | action code] that specifies
2909 ** ^If the action code is [SQLITE_READ]
2911 ** [prepared statement] statement is constructed to substitute
2916 ** ^If the action code is [SQLITE_DELETE] and the callback returns
2918 ** [truncate optimization] is disabled and all rows are deleted individually.
2920 ** An authorizer is used when [sqlite3_prepare | preparing]
2928 ** user-entered SQL is being [sqlite3_prepare | prepared] that
2939 ** The authorizer is disabled by default.
2946 ** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
2951 ** ^Note that the authorizer callback is invoked only during
2952 ** [sqlite3_prepare()] or its variants. Authorization is not
2968 ** to signal SQLite whether or not the action is permitted. See the
2972 ** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
2982 ** that is invoked to authorize certain SQL statement actions. The
2983 ** second parameter to the callback is an integer code that specifies
2984 ** what action is being authorized. These are the integer action codes that
2987 ** These action code values signify what kind of operation is to be
2990 ** codes is used as the second parameter. ^(The 5th parameter to the
2991 ** authorizer callback is the name of the database ("main", "temp",
2993 ** is the name of the inner-most trigger or view that is responsible for
2994 ** the access attempt or NULL if this access attempt is directly from
3043 ** ^The callback function registered by sqlite3_trace() is invoked at
3044 ** various times when an SQL statement is being run by [sqlite3_step()].
3045 ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
3048 ** as each triggered subprogram is entered. The callbacks for triggers
3054 ** ^The callback function registered by sqlite3_profile() is invoked
3058 ** time is in units of nanoseconds, however the current implementation
3059 ** is only capable of millisecond resolution so the six least significant
3062 ** sqlite3_profile() function is considered experimental and is
3076 ** to [sqlite3_trace_v2()] is an OR-ed combination of one or more of
3078 ** is one of the following constants.
3083 ** ^The T argument is one of the integer type codes above.
3084 ** ^The C argument is a copy of the context pointer passed in as the
3090 ** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement
3093 ** trigger subprogram. ^The P argument is a pointer to the
3094 ** [prepared statement]. ^The X argument is a pointer to a string which
3095 ** is the unexpanded SQL text of the prepared statement or an SQL comment
3103 ** information as is provided by the [sqlite3_profile()] callback.
3104 ** ^The P argument is a pointer to the [prepared statement] and the
3105 ** X argument points to a 64-bit integer which is the estimated of
3107 ** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
3110 ** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
3112 ** ^The P argument is a pointer to the [prepared statement] and the
3113 ** X argument is unused.
3116 ** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database
3118 ** ^The P argument is a pointer to the [database connection] object
3119 ** and the X argument is unused.
3133 ** and context pointer P. ^If the X callback is
3134 ** NULL or if the M mask is zero, then tracing is disabled. The
3141 ** ^The X callback is invoked whenever any of the events identified by
3142 ** mask M occur. ^The integer return value from the callback is currently
3146 ** ^A trace callback is invoked with four arguments: callback(T,C,P,X).
3147 ** ^The T argument is one of the [SQLITE_TRACE]
3149 ** ^The C argument is a copy of the context pointer.
3152 ** The sqlite3_trace_v2() interface is intended to replace the legacy
3171 ** interface is to keep a GUI updated during a large query.
3173 ** ^The parameter P is passed through as the only parameter to the
3174 ** callback function X. ^The parameter N is the approximate number of
3176 ** invocations of the callback X. ^If N is less than one then the progress
3177 ** handler is disabled.
3182 ** ^The progress handler is also disabled by setting N to a value less
3185 ** ^If the progress callback returns non-zero, the operation is
3202 ** filename argument. ^The filename argument is interpreted as UTF-8 for
3204 ** order for sqlite3_open16(). ^(A [database connection] handle is usually
3205 ** returned in *ppDb, even if an error occurs. The only exception is that
3206 ** if SQLite is unable to allocate memory to hold the [sqlite3] object,
3208 ** object.)^ ^(If the database is opened (and/or created) successfully, then
3209 ** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The
3218 ** Whether or not an error occurs when it is opened, resources
3220 ** passing it to [sqlite3_close()] when it is no longer required.
3232 ** <dd>The database is opened in read-only mode. If the database does not
3233 ** already exist, an error is returned.</dd>)^
3236 ** <dd>The database is opened for reading and writing if possible, or reading
3237 ** only if the file is write protected by the operating system. In either
3238 ** case the database must already exist, otherwise an error is returned.</dd>)^
3241 ** <dd>The database is opened for reading and writing, and is created if
3242 ** it does not already exist. This is the behavior that is always used for
3246 ** If the 3rd parameter to sqlite3_open_v2() is not one of the
3249 ** then the behavior is undefined.
3251 ** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
3254 ** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
3259 ** cache is enabled using [sqlite3_enable_shared_cache()]. ^The
3261 ** participate in [shared cache mode] even if it is enabled.
3263 ** ^The fourth parameter to sqlite3_open_v2() is the name of the
3265 ** the new database connection should use. ^If the fourth parameter is
3266 ** a NULL pointer then the default [sqlite3_vfs] object is used.
3268 ** ^If the filename is ":memory:", then a private, temporary in-memory database
3269 ** is created for the connection. ^This in-memory database will vanish when
3270 ** the database connection is closed. Future versions of SQLite might
3272 ** It is recommended that when a database filename actually does begin with
3276 ** ^If the filename is an empty string, then a private, temporary
3278 ** automatically deleted as soon as the database connection is closed.
3282 ** ^If [URI filename] interpretation is enabled, and the filename argument
3283 ** begins with "file:", then the filename is interpreted as a URI. ^URI
3284 ** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
3288 ** As of SQLite version 3.7.7, URI filename interpretation is turned off
3295 ** "localhost". ^If the authority is not an empty string or "localhost", an
3296 ** error is returned to the caller. ^The fragment component of a URI, if
3297 ** present, is ignored.
3301 ** then it is interpreted as an absolute path. ^If the path does not begin
3302 ** with a '/' (meaning that the authority section is omitted from the URI)
3303 ** then the path is interpreted as a relative path.
3305 ** is a drive specification (e.g. "C:").)^
3316 ** be used to access the database file on disk. ^If this option is set to
3317 ** an empty string the default VFS object is used. ^Specifying an unknown
3318 ** VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
3323 ** "rwc", or "memory". Attempting to set it to any other value is
3325 ** ^If "ro" is specified, then the database is opened for read-only
3327 ** third argument to sqlite3_open_v2(). ^If the mode option is set to
3328 ** "rw", then the database is opened for read-write (but not create)
3330 ** been set. ^Value "rwc" is equivalent to setting both
3331 ** SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If the mode option is
3333 ** or writes from disk is used. ^It is an error to specify a value for
3334 ** the mode parameter that is less restrictive than that specified by
3338 ** "private". ^Setting it to "shared" is equivalent to setting the
3340 ** sqlite3_open_v2(). ^Setting the cache parameter to "private" is
3342 ** ^If sqlite3_open_v2() is used and the "cache" parameter is present in
3350 ** <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
3352 ** is useful for accessing a database on a filesystem that does not
3357 ** <li> <b>immutable</b>: ^The immutable parameter is a boolean query
3358 ** parameter that indicates that the database file is stored on
3359 ** read-only media. ^When immutable is set, SQLite assumes that the
3361 ** privilege, and so the database is opened read-only and all locking
3362 ** and change detection is disabled. Caution: Setting the immutable
3369 ** ^Specifying an unknown parameter in the query component of a URI is not an
3385 ** An error. "darkstar" is not a recognized authority.
3389 ** C:. Note that the %20 escaping in this example is not strictly
3394 ** Regardless of whether or not shared-cache mode is enabled by
3400 ** An error. "readonly" is not a valid option for the "mode" parameter.
3414 ** codepage is currently defined. Filenames containing international
3446 ** If F is the database filename pointer passed into the xOpen() method of
3449 ** P is the name of the query parameter, then
3452 ** query parameter on F. If P is a query parameter of F
3456 ** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
3459 ** value of query parameter P is one of "yes", "true", or "on" in any
3462 ** query parameter P is one of "no", "false", or "off" in any case or
3463 ** if the value begins with a numeric zero. If P is not a query
3464 ** parameter on F or if the value of P is does not match any of the
3469 ** exist. If the value of P is something other than an integer, then
3470 ** zero is returned.
3472 ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
3473 ** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and
3474 ** is not a database file pathname pointer that SQLite passed into the xOpen
3475 ** VFS method, then the behavior of this routine is undefined and probably
3492 ** then the return value from sqlite3_errcode() is undefined.
3494 ** interface is the same except that it always returns the
3500 ** ^(Memory to hold the error message string is managed internally.
3507 ** ^(Memory to hold the error message string is managed internally
3510 ** When the serialized [threading mode] is in use, it might be the
3535 ** has been compiled into binary form and is ready to be evaluated.
3538 ** original SQL text is source code. A prepared statement object
3539 ** is the compiled object code. All SQL must be converted into a
3561 ** on a connection by connection basis. The first parameter is the
3562 ** [database connection] whose limit is to be set or queried. The
3563 ** second parameter is one of the [limit categories] that define a
3564 ** class of constructs to be size limited. The third parameter is the
3567 ** ^If the new limit is a negative number, the limit is unchanged.
3568 ** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a
3572 ** (The "_LIMIT_" in the name is changed to "_MAX_".))^
3604 ** The synopsis of the meanings of the various limits is shown below.
3605 ** Additional information is available at [limits | Limits in SQLite].
3627 ** used to implement an SQL statement. This limit is not currently
3676 ** The first argument, "db", is a [database connection] obtained from a
3680 ** The second argument, "zSql", is the statement to be compiled, encoded
3685 ** ^If the nByte argument is negative, then zSql is read up to the
3686 ** first zero terminator. ^If nByte is positive, then it is the
3687 ** number of bytes read from zSql. ^If nByte is zero, then no prepared
3688 ** statement is generated.
3689 ** If the caller knows that the supplied string is nul-terminated, then
3690 ** there is a small performance advantage to passing an nByte parameter that
3691 ** is the number of bytes in the input string <i>including</i>
3694 ** ^If pzTail is not NULL then *pzTail is made to point to the first byte
3696 ** compile the first statement in zSql, so *pzTail is left pointing to
3699 ** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
3700 ** executed using [sqlite3_step()]. ^If there is an error, *ppStmt is set
3701 ** to NULL. ^If the input text contains no SQL (if the input is an empty
3702 ** string or a comment) then *ppStmt is set to NULL.
3703 ** The calling procedure is responsible for deleting the compiled
3708 ** otherwise an [error code] is returned.
3712 ** for backwards compatibility, but their use is discouraged.
3714 ** that is returned (the [sqlite3_stmt] object) contains a copy of the
3732 ** interfaces, the underlying reason for the error is returned immediately.
3742 ** choice of query plan if the parameter is the left-hand side of a [LIKE]
3743 ** or [GLOB] operator or if the parameter is compared to an indexed column
3744 ** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled.
3788 ** ^(For example, if a prepared statement is created using the SQL
3789 ** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
3790 ** and parameter :xyz is unbound, then sqlite3_sql() will return
3795 ** is available to hold the result, or if the result would exceed the
3802 ** ^The string returned by sqlite3_sql(P) is managed by SQLite and is
3803 ** automatically freed when the prepared statement is finalized.
3805 ** is obtained from [sqlite3_malloc()] and must be free by the application
3852 ** interface returns false if S is a NULL pointer. If S is not a
3853 ** NULL pointer and is not a pointer to a valid [prepared statement]
3854 ** object, then the behavior is undefined and probably undesirable.
3882 ** a mutex is held. An internal mutex is held for a protected
3883 ** sqlite3_value object but no mutex is held for an unprotected
3884 ** sqlite3_value object. If SQLite is compiled to be single-threaded
3886 ** or if SQLite is run in one of reduced mutex modes
3888 ** then there is no distinction between protected and unprotected
3890 ** for maximum code portability it is recommended that applications
3897 ** [sqlite3_column_value()] is unprotected.
3908 ** The context in which an SQL function executes is stored in an
3910 ** is always first parameter to [application-defined SQL functions].
3942 ** ^The first argument to the sqlite3_bind_*() routines is always
3946 ** ^The second argument is the index of the SQL parameter to be set.
3948 ** SQL parameter is used more than once, second and subsequent
3952 ** for "?NNN" parameters is the value of NNN.
3956 ** ^The third argument is the value to bind to the parameter.
3958 ** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
3959 ** is ignored and the end result is the same as sqlite3_bind_null().
3961 ** ^(In those routines that have a fourth argument, its value is the
3962 ** number of bytes in the parameter. To be clear: the value is the
3965 ** is negative, then the length of the string is
3967 ** If the fourth parameter to sqlite3_bind_blob() is negative, then
3968 ** the behavior is undefined.
3969 ** If a non-negative fourth parameter is provided to sqlite3_bind_text()
3976 ** with embedded NULs is undefined.
3979 ** is a destructor used to dispose of the BLOB or
3980 ** string after SQLite has finished with it. ^The destructor is called
3982 ** ^If the fifth argument is
3984 ** information is in static, unmanaged space and does not need to be freed.
3992 ** the sixth argument to sqlite3_bind_text64() is not one of the
3993 ** allowed values shown above, or if the text encoding is different
3995 ** is undefined.
3998 ** is filled with zeroes. ^A zeroblob uses a fixed amount of memory
3999 ** (just an integer to hold its size) while it is being processed.
4001 ** content is later written using
4009 ** routine is passed a [prepared statement] that has been finalized, the
4010 ** result is undefined and probably harmful.
4020 ** ^[SQLITE_RANGE] is returned if the parameter
4021 ** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails.
4069 ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
4072 ** is included as part of the name.)^
4078 ** ^If the value N is out of range or if the N-th parameter is
4079 ** nameless, then NULL is returned. ^The returned string is
4095 ** index value returned is suitable for use as the second
4097 ** is returned if no matching parameter is found. ^The parameter
4122 ** [prepared statement]. ^This routine returns 0 if pStmt is an SQL
4137 ** UTF-16 string. ^The first parameter is the [prepared statement]
4138 ** that implements the [SELECT] statement. ^The second parameter is the
4139 ** column number. ^The leftmost column is number 0.
4141 ** ^The returned string pointer is valid until either the [prepared statement]
4142 ** is destroyed by [sqlite3_finalize()] or until the statement is automatically
4149 ** NULL pointer is returned.
4151 ** ^The name of a result column is the value of the "AS" clause for
4152 ** that column, if there is an AS clause. If there is no AS clause
4153 ** then the name of the column is unspecified and may change from
4164 ** table column that is the origin of a particular result column in
4170 ** ^The returned string is valid until the [prepared statement] is destroyed
4171 ** using [sqlite3_finalize()] or until the statement is automatically
4173 ** or until the same information is requested
4179 ** ^The first argument to these interfaces is a [prepared statement].
4181 ** the statement, where N is the second function argument.
4182 ** ^The left-most column is column 0 for these routines.
4184 ** ^If the Nth column returned by the statement is an expression or
4185 ** subquery and is not a column value, then all of these functions return
4216 ** ^(The first parameter is a [prepared statement].
4217 ** If this statement is a [SELECT] statement and the Nth column of the
4218 ** returned result set of that [SELECT] is a table column (not an
4220 ** column is returned.)^ ^If the Nth column of the result set is an
4221 ** expression or subquery, then a NULL pointer is returned.
4222 ** ^The returned string is always UTF-8 encoded.
4236 ** is declared to contain a particular type does not mean that the
4237 ** data stored in that column is of the declared type. SQLite is
4238 ** strongly typed, but the typing is dynamic not static. ^Type
4239 ** is associated with individual values, not with the containers
4258 ** new "v2" interface is recommended for new applications but the legacy
4267 ** database locks it needs to do its job. ^If the statement is a [COMMIT]
4269 ** statement. If the statement is not a [COMMIT] and occurs within an
4279 ** is returned each time a new row of data is ready for processing by the
4281 ** sqlite3_step() is called again to retrieve the next row of data.
4290 ** the more specific error code is returned directly by sqlite3_step().
4296 ** be the case that the same database connection is being used by two or
4306 ** than returning [SQLITE_MISUSE]. This is not considered a compatibility
4308 ** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option
4316 ** We admit that this is a goofy design. The problem has been fixed
4321 ** by sqlite3_step(). The use of the "v2" interface is recommended.
4334 ** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
4384 ** result row of a query. ^In every case the first argument is a pointer
4385 ** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
4387 ** and the second argument is the index of the column for which information
4393 ** column index is out of range, the result is undefined.
4406 ** of the result column. ^The returned value is one of [SQLITE_INTEGER],
4408 ** returned by sqlite3_column_type() is only meaningful if no type
4410 ** the value returned by sqlite3_column_type() is undefined. Future
4414 ** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
4416 ** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
4418 ** ^If the result is a numeric value then sqlite3_column_bytes() uses
4421 ** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
4423 ** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
4425 ** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
4427 ** ^If the result is a numeric value then sqlite3_column_bytes16() uses
4430 ** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
4440 ** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
4442 ** <b>Warning:</b> ^The object returned by [sqlite3_column_value()] is an
4447 ** [sqlite3_column_value()] is used in any other way, including calls
4449 ** or [sqlite3_value_bytes()], the behavior is not threadsafe.
4452 ** example, if the internal representation is FLOAT and a text result
4453 ** is requested, [sqlite3_snprintf()] is used internally to perform the
4461 ** <tr><td> NULL <td> INTEGER <td> Result is 0
4462 ** <tr><td> NULL <td> FLOAT <td> Result is 0.0
4463 ** <tr><td> NULL <td> TEXT <td> Result is a NULL pointer
4464 ** <tr><td> NULL <td> BLOB <td> Result is a NULL pointer
4487 ** <li> The initial content is a BLOB and sqlite3_column_text() or
4488 ** sqlite3_column_text16() is called. A zero-terminator might
4490 ** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
4491 ** sqlite3_column_text16() is called. The content must be converted
4493 ** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
4494 ** sqlite3_column_text() is called. The content must be converted
4501 ** of conversion are done in place when it is possible, but sometimes they
4504 ** The safest policy is to invoke these routines
4523 ** [sqlite3_finalize()] is called. ^The memory space used to hold strings
4524 ** and BLOBs is freed automatically. Do <em>not</em> pass the pointers returned
4529 ** of these routines, a default value is returned. The default value
4530 ** is either the integer 0, the floating point number 0.0, or a NULL
4549 ** ^The sqlite3_finalize() function is called to delete a [prepared statement].
4551 ** or if the statement is never been evaluated, then sqlite3_finalize() returns
4558 ** before statement S is ever evaluated, after
4563 ** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
4566 ** resource leaks. It is a grievous error for the application to try to use
4577 ** The sqlite3_reset() function is called to reset a [prepared statement]
4615 ** ^The first parameter is the [database connection] to which the SQL
4616 ** function is to be added. ^If an application uses more than one database
4620 ** ^The second parameter is the name of the SQL function to be created or
4621 ** redefined. ^The length of the name is limited to 255 bytes in a UTF-8
4623 ** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
4628 ** is the number of arguments that the SQL function or
4629 ** aggregate takes. ^If this parameter is -1, then the SQL function or
4632 ** parameter is less than -1 or greater than 127 then the behavior is
4641 ** [SQLITE_UTF16] if [sqlite3_value_text16()] is used, or [SQLITE_UTF8]
4651 ** deterministic. The built-in [random()] SQL function is an example of a
4652 ** function that is not deterministic. The SQLite query planner is able to
4654 ** of the [SQLITE_DETERMINISTIC] flag is recommended where possible.
4656 ** ^(The fifth parameter is an arbitrary pointer. The implementation of the
4668 ** ^(If the ninth parameter to sqlite3_create_function_v2() is not NULL,
4669 ** then it is destructor for the application data pointer.
4670 ** The destructor is invoked when the function is deleted, either by being
4672 ** ^The destructor is also invoked if the call to
4674 ** ^When the destructor callback of the tenth parameter is invoked, it
4675 ** is passed a single argument which is a copy of the application data
4678 ** ^It is permitted to register multiple implementations of the same
4682 ** SQL function is used. ^A function implementation with a non-negative
4683 ** nArg parameter is a better match than a function implementation with
4685 ** matches the database encoding is a better
4686 ** match than a function where the encoding is different.
4687 ** ^A function where the encoding difference is between UTF16le and UTF16be
4688 ** is a closer match than a function where the encoding difference is
4693 ** ^An application-defined function is permitted to call other
4696 ** statement in which the function is running.
4784 ** The 3rd parameter to these callbacks is an array of pointers to
4785 ** [protected sqlite3_value] objects. There is one [sqlite3_value] object for
4803 ** numeric affinity to the value. This means that an attempt is
4805 ** such a conversion is possible without loss of information (in other
4806 ** words, if the value is a string that looks like a number)
4807 ** then the conversion is performed. Otherwise no conversion occurs.
4808 ** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
4854 ** is a [protected sqlite3_value] object even if the input is not.
4855 ** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a
4859 ** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer
4860 ** then sqlite3_value_free(V) is a harmless no-op.
4872 ** ^The first time the sqlite3_aggregate_context(C,N) routine is called
4877 ** the same buffer is returned. Sqlite3_aggregate_context() is normally
4879 ** last time when the xFinal callback is invoked. ^(When no rows match
4881 ** implementation is never called and xFinal() is called exactly once.
4886 ** when first called if N is less than or equal to zero or if a memory
4889 ** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
4893 ** allocation.)^ Within the xFinal callback, it is customary to set
4901 ** [sqlite3_context | SQL function context] that is the first parameter
4906 ** the aggregate SQL function is running.
4921 ** the application-defined function is running.
4942 ** associate metadata with argument values. If the same value is passed to
4945 ** of where this might be useful is in a regular-expression matching
4954 ** value to the application-defined function. ^If there is no metadata
4961 ** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or
4963 ** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
4965 ** once, when the metadata is discarded.
4966 ** SQLite is free to discard the metadata at any time, including: <ul>
4968 ** <li> ^(when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
4970 ** <li> ^(when sqlite3_set_auxdata() is invoked again on the same
4982 ** ^(In practice, metadata is preserved between function calls for
4987 ** the SQL function is running.
4996 ** These are special values for the destructor that is passed in as the
4998 ** argument is SQLITE_STATIC, it means that the content pointer is constant
5004 ** The typedef is necessary to work around problems in certain
5025 ** an application-defined function to be the BLOB whose content is pointed
5026 ** to by the second parameter and which is N bytes long where N is the
5045 ** or sqlite3_result_error16() is negative then SQLite takes as the error
5048 ** sqlite3_result_error16() is non-negative then SQLite takes that many
5056 ** the error code is SQLITE_ERROR. ^A subsequent call to sqlite3_result_error()
5060 ** error indicating that a string or BLOB is too long to represent.
5078 ** a text string which is represented as UTF-8, UTF-16 native byte order,
5087 ** is negative, then SQLite takes result text from the 2nd parameter
5090 ** is non-negative, then as many bytes (not characters) of the text
5092 ** function result. If the 3rd parameter is non-negative, then it
5095 ** in the string at a byte offset that is less than the value of the 3rd
5097 ** result of expressions operating on strings with embedded NULs is undefined.
5099 ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
5103 ** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
5104 ** assumes that the text or BLOB result is in constant space and does not
5108 ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
5119 ** [unprotected sqlite3_value] object is required, so either
5170 ** ^The name of the collation is a UTF-8 string
5191 ** ^The fourth argument, pArg, is an application data pointer that is passed
5194 ** ^The fifth argument, xCallback, is a pointer to the collating function.
5198 ** ^If the xCallback argument is NULL then the collating function is
5200 ** that collation is no longer usable.
5202 ** ^The collating function callback is invoked with a copy of the pArg
5205 ** integer that is negative, zero, or positive
5206 ** if the first string is less than, equal to, or greater than the second,
5222 ** collating function is registered and used, then the behavior of SQLite
5223 ** is undefined.
5226 ** with the addition that the xDestroy callback is invoked on pArg when
5227 ** the collating function is deleted.
5230 ** [database connection] is closed using [sqlite3_close()].
5232 ** ^The xDestroy callback is <u>not</u> called if the
5237 ** This is different from every other SQLite interface. The inconsistency
5238 ** is unfortunate but cannot be changed without breaking backwards
5273 ** sequence is required.
5275 ** ^If the function is registered using the sqlite3_collation_needed() API,
5276 ** then it is passed the names of undefined collation sequences as strings
5277 ** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
5281 ** ^(When the callback is invoked, the first argument passed is a copy
5283 ** sqlite3_collation_needed16(). The second argument is the database
5284 ** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
5286 ** sequence function required. The fourth parameter is the name of the
5309 ** The code to implement this API is not available in the public release
5323 ** Change the key on an open database. If the current database is not
5325 ** database is decrypted.
5327 ** The code to implement this API is not available in the public release
5368 ** requested from the operating system is returned.
5372 ** of the default VFS is not implemented correctly, or not implemented at
5381 ** ^(If this global variable is made to point to a string which is
5385 ** is a NULL pointer, then SQLite performs a search for an appropriate
5389 ** It is required to set a temporary folder on Windows Runtime (WinRT).
5390 ** But for all other platforms, it is highly recommended that applications
5391 ** neither read nor write this variable. This global variable is a relic
5395 ** It is not safe to read or modify this variable in more than one
5396 ** thread at a time. It is not safe to read or modify this variable
5397 ** if a [database connection] is being used at the same time in a separate
5399 ** It is intended that this variable be set once
5407 ** that this variable points to is held in memory obtained from
5410 ** Hence, if this variable is modified directly, either it should be
5421 ** features that require the use of temporary files may fail. Here is an
5439 ** ^(If this global variable is made to point to a string which is
5443 ** to be relative to that directory.)^ ^If this variable is a NULL
5447 ** variable; it is ignored by the unix VFS.
5449 ** Changing the value of this variable while a database connection is
5452 ** It is not safe to read or modify this variable in more than one
5453 ** thread at a time. It is not safe to read or modify this variable
5454 ** if a [database connection] is being used at the same time in a separate
5456 ** It is intended that this variable be set once
5464 ** that this variable points to is held in memory obtained from
5467 ** Hence, if this variable is modified directly, either it should be
5479 ** zero if the given database connection is or is not in autocommit mode,
5480 ** respectively. ^Autocommit mode is on by default.
5481 ** ^Autocommit mode is disabled by a [BEGIN] statement.
5482 ** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
5489 ** an error is to use this function.
5492 ** connection while this routine is running, then the return value
5493 ** is undefined.
5503 ** returned by sqlite3_db_handle is the same [database connection]
5516 ** has the name "main". If there is no attached database N on the database
5517 ** connection D, or if database N is a temporary or in-memory database, then
5518 ** a NULL pointer is returned.
5520 ** ^The filename returned by this function is the output of the
5528 ** CAPI3REF: Determine if a database is read-only
5532 ** of connection D is read-only, 0 if it is read/write, or -1 if N is not
5542 ** pStmt associated with the [database connection] pDb. ^If pStmt is NULL
5558 ** function to be invoked whenever a transaction is [COMMIT | committed].
5560 ** for the same database connection is overridden.
5562 ** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
5564 ** for the same database connection is overridden.
5565 ** ^The pArg argument is passed through to the callback.
5567 ** then the commit is converted into a rollback.
5587 ** operation is allowed to continue normally. ^If the commit hook
5588 ** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
5589 ** ^The rollback hook is invoked on a rollback that results from a commit
5592 ** ^For the purposes of this API, a transaction is said to have been
5593 ** rolled back if an explicit "ROLLBACK" statement is executed, or
5595 ** ^The rollback callback is not invoked if a transaction is
5596 ** automatically rolled back because the database connection is closed.
5609 ** to be invoked whenever a row is updated, inserted or deleted in
5612 ** for the same database connection is overridden.
5614 ** ^The second argument is a pointer to the function to invoke when a
5615 ** row is updated, inserted or deleted in a rowid table.
5616 ** ^The first argument to the callback is a copy of the third argument
5618 ** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
5623 ** ^The final callback parameter is the [rowid] of the row.
5624 ** ^In the case of an update, this is the [rowid] after the update takes place.
5626 ** ^(The update hook is not invoked when internal system tables are
5628 ** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified.
5631 ** is not invoked when duplication rows are deleted because of an
5632 ** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook
5663 ** to the same database. Sharing is enabled if the argument is true
5664 ** and disabled if the argument is false.)^
5666 ** ^Cache sharing is enabled and disabled for an entire process.
5667 ** This is a change as of SQLite version 3.5.0. In prior versions of SQLite,
5676 ** successfully. An [error code] is returned otherwise.)^
5678 ** ^Shared cache is disabled by default. But this might change in
5682 ** Note: This method is disabled on MacOS X 10.7 and iOS version 5.0
5687 ** This interface is threadsafe on processors where writing a
5688 ** 32-bit integer is atomic.
5700 ** pages to improve performance is an example of non-essential memory.
5703 ** ^The sqlite3_release_memory() routine is a no-op returning zero
5704 ** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT].
5716 ** [sqlite3_release_memory()] interface, this interface is in effect even
5717 ** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is
5732 ** ^The soft heap limit is "soft" because even though SQLite strives to stay
5735 ** is advisory only.
5737 ** ^The return value from sqlite3_soft_heap_limit64() is the size of
5739 ** error. ^If the argument N is negative
5740 ** then no change is made to the soft heap limit. Hence, the current
5744 ** ^If the argument N is zero then the soft heap limit is disabled.
5746 ** ^(The soft heap limit is not enforced in the current implementation
5750 ** <li> The soft heap limit is set to zero.
5751 ** <li> Memory accounting is disabled using a combination of the
5754 ** <li> An alternative page cache implementation is specified using
5761 ** Beginning with SQLite version 3.7.3, the soft heap limit is enforced
5763 ** compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT],
5764 ** the soft heap limit is enforced on every memory allocation. Without
5765 ** [SQLITE_ENABLE_MEMORY_MANAGEMENT], the soft heap limit is only enforced
5766 ** when memory is allocated by the page cache. Testing suggests that because
5767 ** the page cache is the predominate memory user in SQLite, most
5780 ** This is a deprecated version of the [sqlite3_soft_heap_limit64()]
5781 ** interface. This routine is provided for historical compatibility
5799 ** ^If the column-name parameter to sqlite3_table_column_metadata() is a
5804 ** ^The column is identified by the second, third and fourth parameters to
5805 ** this function. ^(The second parameter is either the name of the database
5807 ** table or NULL.)^ ^If it is NULL, then all attached databases are searched
5814 ** ^Metadata is returned by writing to the memory locations passed as the 5th
5816 ** NULL, in which case the corresponding element of metadata is omitted.
5825 ** <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY
5826 ** <tr><td> 9th <td> int <td> True if column is [AUTOINCREMENT]
5831 ** declaration type and collation sequence is valid until the next
5834 ** ^If the specified table is actually a view, an [error code] is returned.
5836 ** ^If the specified column is "rowid", "oid" or "_rowid_" and the table
5837 ** is not a [WITHOUT ROWID] table and an
5839 ** parameters are set for the explicitly declared column. ^(If there is no
5864 int *pAutoinc /* OUTPUT: True if column is auto-increment */
5881 ** ^The entry point is zProc.
5885 ** X is consists of the lower-case equivalent of all ASCII alphabetic
5890 ** ^If an error occurs and pzErrMsg is not 0, then the
5902 ** <b>Security warning:</b> It is recommended that the
5925 ** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
5927 ** ^Extension loading is off by default.
5937 ** <b>Security warning:</b> It is recommended that extension loading
5949 ** each new [database connection] that is created. The idea here is that
5950 ** xEntryPoint() is the entry point for a statically linked [SQLite extension]
5951 ** that is to be automatically loaded into all new database connections.
5969 ** is NULL before calling the xEntryPoint(). ^SQLite will invoke
5974 ** ^Calling sqlite3_auto_extension(X) with an entry point X that is already
5975 ** on the list of automatic extensions is a harmless no-op. ^No entry point
5976 ** will be called more than once for each database connection that is opened.
6004 ** The interface to the virtual-table mechanism is currently considered
6006 ** If this is a problem for you, do not use the interface at this time.
6028 ** ^A virtual table module is created by filling in a persistent
6031 ** ^The registration remains valid until it is replaced by a different
6033 ** of this structure must not change while it is registered with
6075 ** The sqlite3_index_info structure and its substructures is used as part
6086 ** where OP is =, <, <=, >, or >=.)^ ^(The particular operator is
6089 ** ^(The index of the column is stored in
6090 ** aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the
6092 ** is usable) and false if it cannot.)^
6100 ** ^Information about the ORDER BY clause is stored in aOrderBy[].
6107 ** the corresponding bit is set within the colUsed mask if the column may be
6109 ** to the right of the first 63 is required, then bit 63 of colUsed is also
6116 ** the right-hand side of the corresponding aConstraint[] is evaluated
6118 ** is true, then the constraint is assumed to be fully handled by the
6119 ** virtual table and is not checked again by SQLite.)^
6123 ** ^[sqlite3_free()] is used to free idxPtr if and only if
6124 ** needToFreeIdxPtr is true.
6128 ** sorting step is required.
6130 ** ^The estimatedCost value is an estimate of the cost of a particular
6131 ** strategy. A cost of N indicates that the cost of the strategy is similar
6133 ** indicates that the expense of the operation is similar to that of a
6136 ** ^The estimatedRows value is an estimate of the number of rows that
6140 ** mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag -
6145 ** SQLite also assumes that if a call to the xUpdate() method is made as
6147 ** implementation returns SQLITE_CONSTRAINT, then there is no need to rollback
6150 ** before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not
6155 ** structure for SQLite version 3.8.2. If a virtual table extension is
6171 unsigned char usable; /* True if this constraint is usable */
6181 int argvIndex; /* if >0, constraint is part of argv to xFilter */
6187 int orderByConsumed; /* True if output is already ordered */
6207 ** an operator that is part of a constraint term in the wHERE clause of
6229 ** ^The module name is registered on the [database connection] specified
6230 ** by the first parameter. ^The name of the module is given by the
6231 ** second parameter. ^The third parameter is a pointer to
6233 ** parameter is an arbitrary client data pointer that is passed through
6235 ** when a new virtual table is be being created or reinitialized.
6238 ** is a pointer to a destructor for the pClientData. ^SQLite will
6239 ** invoke the destructor function (if it is not NULL) when SQLite
6243 ** interface is equivalent to sqlite3_create_module_v2() with a NULL
6268 ** The purpose of this superclass is to define certain fields that are
6273 ** take care that any prior string is freed by a call to [sqlite3_free()]
6275 ** is delivered up to the client application, the string will be automatically
6328 ** before this API is called, a new function is created.)^ ^The implementation
6330 ** the new function is not good for anything by itself. Its only
6331 ** purpose is to be a placeholder function that can be overloaded
6338 ** to a comment remarkably similar to this one) is currently considered
6340 ** If this is a problem for you, do not use the interface at this time.
6373 ** ^(Parameter zDb is not the filename that contains the database, but
6374 ** rather the symbolic name of the database. For attached databases, this is
6376 ** For the main database file, the database name is "main". For TEMP
6377 ** tables, the database name is "temp".)^
6379 ** ^If the flags parameter is non-zero, then the BLOB is opened for read
6380 ** and write access. ^If the flags parameter is zero, the BLOB is opened for
6383 ** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is stored
6384 ** in *ppBlob. Otherwise an [error code] is returned and, unless the error
6385 ** code is SQLITE_MISUSE, *ppBlob is set to NULL.)^ ^This means that, provided
6386 ** the API is not misused, it is always safe to call [sqlite3_blob_close()]
6393 ** <li> ^(Table zTable is a WITHOUT ROWID table)^,
6395 ** <li> ^(Row iRow is not present in the table)^,
6396 ** <li> ^(The specified column of row iRow contains a value that is not
6398 ** <li> ^(Column zColumn is part of an index, PRIMARY KEY or UNIQUE
6399 ** constraint and the blob is being opened for read/write access)^,
6401 ** column zColumn is part of a [child key] definition and the blob is
6410 ** ^(If the row that a BLOB handle points to is modified by an
6412 ** then the BLOB handle is marked as "expired".
6413 ** This is true if any column of the row is changed, even a column
6414 ** other than the one the BLOB handle is open on.)^
6447 ** ^This function is used to move an existing blob handle so that it points
6448 ** to a different row of the same database table. ^The new row is identified
6450 ** changed. ^The database, table and column on which the blob handle is open
6456 ** the nominated column.)^ ^If the new row is not present in the table, or if
6458 ** SQLite error code is returned and the blob handle is considered aborted.
6472 ** ^This function closes an open [BLOB handle]. ^(The BLOB handle is closed
6474 ** handle is still closed.)^
6477 ** the database is in auto-commit mode and there are no other open read-write
6478 ** blob handles or active write statements, the current transaction is
6480 ** code is returned and the transaction rolled back.
6482 ** Calling this function with an argument that is not a NULL pointer or an
6485 ** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function
6486 ** is passed a valid open blob handle, the values returned by the
6511 ** ^(This function is used to read data from an open [BLOB handle] into a
6515 ** ^If offset iOffset is less than N bytes from the end of the BLOB,
6516 ** [SQLITE_ERROR] is returned and no data is read. ^If N or iOffset is
6517 ** less than zero, [SQLITE_ERROR] is returned and no data is read.
6525 ** Otherwise, an [error code] or an [extended error code] is returned.)^
6540 ** ^(This function is used to write data into an open [BLOB handle] from a
6545 ** Otherwise, an [error code] or an [extended error code] is returned.)^
6546 ** ^Unless SQLITE_MISUSE is returned, this function sets the
6554 ** This function may only modify the contents of the BLOB; it is
6556 ** ^If offset iOffset is less than N bytes from the end of the BLOB,
6557 ** [SQLITE_ERROR] is returned and no data is written. The size of the
6560 ** than zero [SQLITE_ERROR] is returned and no data is written.
6581 ** A virtual filesystem (VFS) is an [sqlite3_vfs] object
6584 ** single default VFS that is appropriate for the host computer.
6591 ** ^If there is no match, a NULL pointer is returned.
6592 ** ^If zVfsName is NULL then the default VFS is returned.
6595 ** ^Each new VFS becomes the default VFS if the makeDflt flag is set.
6599 ** same name are registered, the behavior is undefined. If a
6600 ** VFS is registered with a name that is NULL or an empty string,
6601 ** then the behavior is undefined.
6604 ** ^(If the default VFS is unregistered, another VFS is chosen as
6605 ** the default. The choice for the new VFS is arbitrary.)^
6616 ** use by SQLite, code that links against SQLite is
6621 ** is selected automatically at compile-time. The following
6630 ** The SQLITE_MUTEX_NOOP implementation is a set of routines
6631 ** that does no real locking and is appropriate for use in
6636 ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
6638 ** implementation is included with the library. In this case the
6646 ** routine returns NULL if it is unable to allocate the requested
6669 ** a new mutex. ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
6670 ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
6675 ** implementation is available on the host platform, the mutex subsystem
6688 ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
6690 ** mutex types, the same mutex is returned on every call that has
6698 ** to enter a mutex. ^If another thread is already within the mutex,
6706 ** than an SQLITE_MUTEX_RECURSIVE more than once, the behavior is undefined.
6711 ** sqlite3_mutex_try() as an optimization so this is acceptable
6716 ** is undefined if the mutex is not currently entered by the
6717 ** calling thread or is not currently allocated.
6720 ** sqlite3_mutex_leave() is a NULL pointer, then all three routines
6747 ** ^The xMutexInit method defined by this structure is invoked as
6749 ** ^The xMutexInit routine is called by SQLite exactly once for each
6752 ** ^The xMutexEnd method defined by this structure is invoked as
6754 ** implementation of this method is expected to release all outstanding
6757 ** interface is invoked exactly once for each call to [sqlite3_shutdown()].
6773 ** The only difference is that the public sqlite3_XXX functions enumerated
6778 ** (i.e. it is acceptable to provide an implementation that segfaults if
6779 ** it is passed a NULL pointer).
6791 ** ^SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is
6793 ** If xMutexInit fails in any way, it is expected to clean up after itself
6816 ** provides implementations for these routines when it is compiled
6818 ** are only required to provide these routines if SQLITE_DEBUG is
6819 ** defined and if NDEBUG is not defined.
6822 ** is held or not held, respectively, by the calling thread.
6824 ** The implementation is not required to provide versions of these
6829 ** If the argument to sqlite3_mutex_held() is a NULL pointer then
6832 ** the reason the mutex does not exist is because the build is not
6834 ** call to sqlite3_mutex_held() to fail, so a non-zero return is
6847 ** which is one of these integer constants.
6876 ** when the [threading mode] is Serialized.
6877 ** ^If the [threading mode] is Single-thread or Multi-thread then this
6889 ** name of the database is "main" for the main database or "temp" for the
6902 ** case is a short-circuit path which does not actually invoke the
6906 ** open database file, then SQLITE_ERROR is returned. ^This error
6907 ** code is not remembered and will not be recalled by [sqlite3_errcode()]
6909 ** also return SQLITE_ERROR. There is no way to distinguish between
6920 ** ^The sqlite3_test_control() interface is used to read out internal
6922 ** purposes. ^The first parameter is an operation code that determines
6925 ** This interface is not for use by applications. It exists solely
6927 ** on how the SQLite library is compiled, this interface might not exist.
6931 ** Unlike most of the SQLite API, this function is not guaranteed to
6976 ** highwater marks. ^The first argument is an integer code for
6979 ** ^The current value of the parameter is returned into *pCurrent.
6980 ** ^The highest recorded value is returned in *pHighwater. ^If the
6981 ** resetFlag is true, then the highest record value is reset after
6982 ** *pHighwater is written. ^(Some parameters do not record the highest
6984 ** nothing is written into *pHighwater and the resetFlag is ignored.)^
6986 ** value. For these latter parameters nothing is written into *pCurrent.)^
6991 ** If either the current value or the highwater mark is too large to
7015 ** <dd>This parameter is the current amount of memory checked out
7020 ** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
7021 ** this parameter. The amount returned is the sum of the allocation
7028 ** *pHighwater parameter to [sqlite3_status()] is of interest.
7029 ** The value written into the *pCurrent parameter is undefined.</dd>)^
7039 ** value returned is in pages, not in bytes.</dd>)^
7054 ** *pHighwater parameter to [sqlite3_status()] is of interest.
7055 ** The value written into the *pCurrent parameter is undefined.</dd>)^
7060 ** [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not
7070 ** larger (that is, because the requested allocation was larger than the
7078 ** *pHighwater parameter to [sqlite3_status()] is of interest.
7079 ** The value written into the *pCurrent parameter is undefined.</dd>)^
7083 ** The *pCurrent value is undefined. The *pHighwater value is only
7084 ** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
7104 ** ^This interface is used to retrieve runtime status information
7105 ** about a single [database connection]. ^The first argument is the
7107 ** is an integer constant, taken from the set of
7110 ** [SQLITE_DBSTATUS options] is likely
7113 ** ^The current value of the requested parameter is written into *pCur
7114 ** and the highest instantaneous value is written into *pHiwtr. ^If
7115 ** the resetFlg is true, then the highest instantaneous value is
7136 ** if a discontinued or unsupported verb is invoked.
7145 ** satisfied using lookaside memory. Only the high-water value is meaningful;
7146 ** the current value is always zero.)^
7153 ** Only the high-water value is meaningful;
7154 ** the current value is always zero.)^
7161 ** Only the high-water value is meaningful;
7162 ** the current value is always zero.)^
7167 ** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.
7171 ** <dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a
7172 ** pager cache is shared between two or more connections the bytes of heap
7173 ** memory used by that pager cache is divided evenly between the attached
7179 ** SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0.
7185 ** ^The full amount of memory used by the schemas is reported, even if the
7186 ** schema memory is shared with other database connections due to
7188 ** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.
7194 ** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.
7200 ** is always 0.
7206 ** is always 0.
7216 ** on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined.)^ ^The
7217 ** highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0.
7223 ** resolved.)^ ^The highwater mark is always 0.
7252 ** that the prepared statement is using a full table scan rather than
7255 ** ^(This interface is used to retrieve and reset counter values from
7256 ** a [prepared statement]. The first argument is the prepared statement
7258 ** is an integer code for a specific [SQLITE_STMTSTATUS counter]
7260 ** ^The current value of the requested counter is returned.
7261 ** ^If the resetFlg is true, then the counter is reset to zero after this
7278 ** <dd>^This is the number of times that SQLite has stepped forward in
7284 ** <dd>^This is the number of sort operations that have occurred.
7289 ** <dd>^This is the number of rows inserted into transient indices that
7293 ** need to be reinitialized each time the statement is run.</dd>
7296 ** <dd>^This is the number of virtual machine operations executed
7297 ** by the prepared statement if that number is less than or equal
7301 ** then the value returned by this statement status code is undefined.
7313 ** The sqlite3_pcache type is opaque. It is implemented by
7347 ** SQLite is used for the page cache.
7351 ** that memory is allocated and released, and the policies used to
7355 ** The alternative page cache mechanism is an
7356 ** extreme measure that is only needed by the most demanding applications.
7357 ** The built-in page cache is recommended for most uses.
7365 ** ^(The xInit() method is called once for each effective
7368 ** method is passed a copy of the sqlite3_pcache_methods2.pArg value.)^
7369 ** The intent of the xInit() method is to set up global data structures
7371 ** ^(If the xInit() method is NULL, then the
7372 ** built-in default page cache is used instead of the application defined
7376 ** ^The xShutdown() method is called by [sqlite3_shutdown()].
7383 ** xShutdown method is only called from [sqlite3_shutdown()] so it does
7393 ** though this is not guaranteed. ^The
7394 ** first parameter, szPage, is the size in bytes of the pages that must
7396 ** second parameter szExtra is a number of bytes of extra storage
7402 ** ^The third argument to xCreate(), bPurgeable, is true if the cache being
7404 ** false if it is used for an in-memory database. The cache implementation
7406 ** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will
7416 ** instance passed as the first argument. This is the value configured using
7418 ** parameter, the implementation is not required to do anything with this
7419 ** value; it is advisory only.
7434 ** The page to be fetched is determined by the key. ^The minimum key value
7435 ** is 1. After it has been retrieved using xFetch, the page is considered
7438 ** If the requested page is already in the page cache, then the page cache
7440 ** intact. If the requested page is not already in the cache, then the
7445 ** <tr><th> createFlag <th> Behavior when page is not already in cache
7450 ** NULL if allocating a new page is effectively impossible.
7460 ** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
7461 ** as its second argument. If the third parameter, discard, is non-zero,
7463 ** ^If the discard parameter is
7473 ** The xRekey() method is used to change the key value associated with the
7476 ** discarded. ^Any prior cache entry associated with newKey is guaranteed not
7486 ** ^The xDestroy() method is used to delete a cache allocated by xCreate().
7495 ** is not obligated to free any memory, but well-behaved implementations should
7517 ** This is the obsolete pcache_methods object that has now been replaced
7518 ** by sqlite3_pcache_methods2. This object is not used by SQLite. It is
7541 ** online backup operation. ^The sqlite3_backup object is created by
7542 ** a call to [sqlite3_backup_init()] and is destroyed by a call to
7553 ** It is useful either for creating backups of databases or
7560 ** ^The source database is read-locked only while it is being read;
7561 ** it is not locked continuously for the entire backup operation.
7564 ** reading or writing to the source database while the backup is underway.
7568 ** <li><b>sqlite3_backup_init()</b> is called once to initialize the
7570 ** <li><b>sqlite3_backup_step()</b> is called one or more times to transfer
7572 ** <li><b>sqlite3_backup_finish()</b> is called to release all resources
7583 ** ^The database name is "main" for the main database, "temp" for the
7594 ** there is already a read or read-write transaction open on the
7597 ** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
7613 ** ^If N is negative, all remaining source pages are copied.
7619 ** then an [error code] is returned. ^As well as [SQLITE_OK] and
7627 ** <li> the destination database is using write-ahead-log journaling
7629 ** <li> the destination database is an in-memory database and the
7635 ** is invoked (if one is specified). ^If the
7636 ** busy-handler returns non-zero before the lock is available, then
7637 ** [SQLITE_BUSY] is returned to the caller. ^In this case the call to
7640 ** is being used to write to the source database when sqlite3_backup_step()
7641 ** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
7644 ** [SQLITE_READONLY] is returned, then
7645 ** there is no point in retrying the call to sqlite3_backup_step(). These
7651 ** on the destination file. ^The exclusive lock is not released until either
7652 ** sqlite3_backup_finish() is called or the backup operation is complete
7656 ** ^Because the source database is not locked between calls to
7658 ** through the backup process. ^If the source database is modified by an
7662 ** database is modified by the using the same database connection as is used
7663 ** by the backup operation, then the backup database is automatically
7674 ** active write-transaction on the destination database is rolled back.
7675 ** The [sqlite3_backup] object is invalid
7678 ** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
7686 ** is not a permanent error and does not affect the return value of
7698 ** sqlite3_backup_step(). If the source database is modified in a way that
7707 ** purposes while a backup operation is underway or being initialized.
7708 ** ^If SQLite is compiled and configured to support threadsafe database
7713 ** [database connection] is not passed to any other API (by any thread) after
7714 ** sqlite3_backup_init() is called and before the corresponding call to
7717 ** and so no error code is reported, but the operations may malfunction
7719 ** backup is in progress might also also cause a mutex deadlock.
7723 ** is not accessed while the backup is running. In practice this means
7725 ** backed up to is not accessed by any connection within the process,
7728 ** The [sqlite3_backup] object itself is partially threadsafe. Multiple
7732 ** same time as another thread is invoking sqlite3_backup_step() it is
7756 ** ^This API is only available if the library was compiled with the
7765 ** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
7767 ** has locked the required resource is stored internally. ^After an
7771 ** when the blocking connections current transaction is concluded. ^The
7772 ** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
7775 ** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
7776 ** there is a chance that the blocking connection will have already
7777 ** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
7778 ** If this happens, then the specified callback is invoked immediately,
7781 ** ^If the blocked connection is attempting to obtain a write-lock on a
7787 ** blocked connection. If sqlite3_unlock_notify() is called when the
7789 ** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
7791 ** unlock-notify callback is canceled. ^The blocked connections
7795 ** The unlock-notify callback is not reentrant. If an application invokes
7799 ** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always
7804 ** When an unlock-notify callback is registered, the application provides a
7805 ** single void* pointer that is passed to the callback when it is invoked.
7808 ** an unlock-notify callback is a pointer to an array of void* pointers,
7809 ** and the second is the number of entries in the array.
7811 ** When a blocking connections transaction is concluded, there may be
7815 ** multiple times, it is invoked once with the set of void* context pointers
7825 ** application to deadlock. For example, if connection X is waiting for
7827 ** Y is waiting on connection X's transaction, then neither connection
7832 ** system in a deadlocked state, then SQLITE_LOCKED is returned and no
7833 ** unlock-notify callback is registered. The system is said to be in
7837 ** A's transaction is concluded. ^Indirect deadlock is also detected, so
7838 ** the system is also considered to be deadlocked if connection B has
7840 ** C's transaction, where connection C is waiting on connection A. ^Any
7845 ** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost
7846 ** always appropriate to call sqlite3_unlock_notify(). There is however,
7849 ** that belong to the same connection. If there are, SQLITE_LOCKED is
7850 ** returned. In this case there is no "blocking connection", so invoking
7855 ** One way around this problem is to check the extended error code returned
7856 ** by an sqlite3_step() call. ^(If there is a blocking connection, then the
7857 ** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
7858 ** the special "DROP TABLE/INDEX" case, the extended error code is just
7885 ** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the
7887 ** is case sensitive.
7902 ** [sqlite3_strlike(P,X,E)] is the same as for the "X LIKE P ESCAPE E"
7905 ** ^As with the LIKE operator, the [sqlite3_strlike(P,X,E)] function is case
7924 ** ^If logging is enabled, the zFormat string and subsequent arguments are
7927 ** The sqlite3_log() interface is intended for use by extensions such as
7928 ** virtual tables, collating functions, and SQL functions. While there is
7930 ** is considered bad form.
7935 ** will not use dynamically allocated memory. The log message is stored in
7936 ** a fixed-length buffer on the stack. If the log message is longer than
7946 ** ^The [sqlite3_wal_hook()] function is used to register a callback that
7947 ** is invoked each time data is committed to a database in wal mode.
7949 ** ^(The callback is invoked by SQLite after the commit has taken place and
7953 ** ^The first parameter passed to the callback function when it is invoked
7954 ** is a copy of the third parameter passed to sqlite3_wal_hook() when
7955 ** registering the callback. ^The second is a copy of the database handle.
7956 ** ^The third parameter is the name of the database that was written to -
7958 ** is the number of pages currently in the write-ahead log file,
7962 ** code is returned, that error will propagate back up through the
7986 ** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around
8008 ** is only necessary if the default setting is found to be suboptimal
8017 ** ^(The sqlite3_wal_checkpoint(D,X) is equivalent to
8028 ** interface was added. This interface is retained for backwards
8041 ** information is written back into integers pointed to by L and C.)^
8049 ** is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.
8055 ** [sqlite3_busy_handler|busy-handler callback]) until there is no
8058 ** database file. ^This mode blocks new database writers while it is pending,
8068 ** database writer attempts while it is pending, but does not impede readers.
8076 ** ^If pnLog is not NULL, then *pnLog is set to the total number of frames in
8078 ** of an error or because the database is not in [WAL mode]. ^If pnCkpt is not
8079 ** NULL,then *pnCkpt is set to the total number of checkpointed frames in the
8082 ** because the database is not in WAL mode. ^Note that upon successful
8087 ** any other process is running a checkpoint operation at the same time, the
8088 ** lock cannot be obtained and SQLITE_BUSY is returned. ^Even if there is a
8093 ** obtained immediately, and a busy-handler is configured, it is invoked and
8095 ** is successfully obtained. ^The busy-handler is also invoked while waiting for
8097 ** the writer lock is obtained or while waiting for database readers, the
8100 ** without blocking any further. ^SQLITE_BUSY is returned in this case.
8102 ** ^If parameter zDb is NULL or points to a zero length string, then the
8103 ** specified operation is attempted on all WAL databases [attached] to
8106 ** an SQLITE_BUSY error is encountered when processing one or more of the
8107 ** attached WAL databases, the operation is still attempted on any remaining
8108 ** attached databases and SQLITE_BUSY is returned at the end. ^If any other
8109 ** error occurs while processing an attached database, processing is abandoned
8110 ** and the error code is returned to the caller immediately. ^If no error
8111 ** (SQLITE_BUSY or otherwise) is encountered while processing the attached
8112 ** databases, SQLITE_OK is returned.
8114 ** ^If database zDb is the name of an attached database that is not in WAL
8115 ** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. ^If
8116 ** zDb is not NULL (or a zero length string) and is not the name of any
8117 ** attached database, SQLITE_ERROR is returned to the caller.
8121 ** sets the error information that is queried by
8156 ** If this interface is invoked outside the context of an xConnect or
8157 ** xCreate virtual table method then the behavior is undefined.
8159 ** At present, there is only one option that may be configured using
8176 ** where X is an integer. If X is zero, then the [virtual table] whose
8178 ** support constraints. In this configuration (which is the default) if
8180 ** statement is rolled back as if [ON CONFLICT | OR ABORT] had been
8184 ** If X is non-zero, then the virtual table implementation guarantees
8187 ** If the [ON CONFLICT] mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite
8188 ** is able to roll back a statement or database transaction, and abandon
8190 ** If the ON CONFLICT mode is REPLACE and the [xUpdate] method returns
8197 ** CONFLICT policy is REPLACE, the virtual table implementation should
8199 ** return SQLITE_OK. Or, if this is not possible, it may return
8211 ** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL],
8224 ** is for the SQL statement being evaluated.
8226 ** Note that the [SQLITE_IGNORE] constant is also used as a potential
8228 ** [SQLITE_ABORT] is also a [result code].
8244 ** When the value returned to V is a string, space to hold that string is
8246 ** S is finalized.
8278 ** subquery the loop is part of. The main query has a select-id of zero.
8279 ** The select-id is the same value as is output in the first column
8299 ** Since this interface is expected to be rarely used, it is only
8300 ** available if SQLite is compiled using the [SQLITE_ENABLE_STMT_SCANSTATUS]
8305 ** of this interface is undefined.
8306 ** ^The requested measurement is written into a variable pointed to by
8309 ** Loops are numbered starting from zero. ^If idx is out of range - less than
8311 ** the statement - a non-zero value is returned and the variable that pOut
8312 ** points to is unchanged.
8334 ** This API is only available if the library is built with pre-processor
8342 ** ^If a write-transaction is open on [database connection] D when the
8346 ** active SQL statement is reading from it, or if it is page 1 of a database
8347 ** file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)]
8353 ** immediately and there is a busy-handler callback configured, it is invoked
8355 ** the database is skipped and an attempt made to flush any dirty pages
8361 ** example an IO error or out-of-memory condition), then processing is
8362 ** abandoned and an SQLite [error code] is returned to the caller immediately.
8374 ** ^These interfaces are only available if SQLite is compiled using the
8378 ** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation
8383 ** ^The preupdate hook is disabled by invoking [sqlite3_preupdate_hook()]
8385 ** ^The third parameter to [sqlite3_preupdate_hook()] is passed through as
8389 ** hook is not invoked for changes to [virtual tables] or [WITHOUT ROWID]
8392 ** ^The second parameter to the preupdate callback is a pointer to
8394 ** ^The third parameter to the preupdate callback is one of the constants
8396 ** kind of update operation that is about to occur.
8397 ** ^(The fourth parameter to the preupdate callback is the name of the
8398 ** database within the database connection that is being modified. This
8402 ** ^The fifth parameter to the preupdate callback is the name of the
8403 ** table that is being modified.
8404 ** ^The sixth parameter to the preupdate callback is the initial [rowid] of the
8405 ** row being changes for SQLITE_UPDATE and SQLITE_DELETE changes and is
8407 ** ^The seventh parameter to the preupdate callback is the final [rowid] of
8408 ** the row being changed for SQLITE_UPDATE and SQLITE_INSERT changes and is
8416 ** [database connection] pointer that is different from the one supplied
8421 ** in the row that is being inserted, updated, or deleted.
8425 ** the table row before it is updated. The N parameter must be between 0
8428 ** preupdate callbacks; if it is used by an SQLITE_INSERT callback then the
8429 ** behavior is undefined. The [sqlite3_value] that P points to
8434 ** the table row after it is updated. The N parameter must be between 0
8437 ** preupdate callbacks; if it is used by an SQLITE_DELETE callback then the
8438 ** behavior is undefined. The [sqlite3_value] that P points to
8472 ** The return value is OS-dependent. For example, on unix systems, after
8493 ** by the reader until a new read transaction is started.
8496 ** version of the database file so that it is possible to later open a new read
8500 ** The constructor for this object is [sqlite3_snapshot_get()]. The
8503 ** sqlite3_snapshot objects is [sqlite3_snapshot_free()].
8516 ** ^If schema S of [database connection] D is not a [WAL mode] database
8517 ** that is in a read transaction, then [sqlite3_snapshot_get(D,S,P)]
8524 ** The [sqlite3_snapshot_get()] interface is only available when the
8525 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
8555 ** schema S is in [WAL mode]. A database connection might not know
8556 ** that the database file is in [WAL mode] if there has been no prior
8562 ** The [sqlite3_snapshot_open()] interface is only available when the
8563 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
8579 ** The [sqlite3_snapshot_free()] interface is only available when the
8580 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
8588 ** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages
8592 ** file, the result of the comparison is undefined.
8594 ** Additionally, the result of the comparison is only valid if both of the
8596 ** last time the wal file was deleted. The wal file is deleted when the
8597 ** database is changed back to rollback mode or when the number of database
8600 ** is undefined.
8604 ** snapshot, and a positive value if P1 is a newer snapshot than P2.
8629 ** a legal notice, here is a blessing:
8673 ** A pointer to a structure of the following type is passed as the first
8700 ** A pointer to a structure of the following type is passed as the
8705 ** sqlite3_rtree_geometry. This structure is a subclass of
8770 ** a pointer to the new object is written to *ppSession and SQLITE_OK is
8771 ** returned. If an error occurs, *ppSession is set to NULL and an SQLite
8772 ** error code (e.g. SQLITE_NOMEM) is returned.
8774 ** It is possible to create multiple session objects attached to a single
8779 ** are attached to is itself closed. If the database handle is closed before
8780 ** the session object is deleted, then the results of calling any session
8785 ** is not possible for an application to register a pre-update hook on a
8786 ** database handle that has one or more session objects attached. Nor is
8788 ** which a pre-update hook is already defined. The results of attempting
8792 ** database zDb, where zDb is either "main", or "temp", or the name of an
8793 ** attached database. It is not an error if database zDb is not attached
8794 ** to the database when the session object is created.
8811 ** are attached is closed. Refer to the documentation for
8822 ** disabled - it does not. A newly created session object is enabled.
8828 ** greater than zero enables it. Passing a value less than zero is a
8832 ** the session is disabled, or 1 if it is enabled.
8839 ** Each change recorded by a session object is marked as either direct or
8840 ** indirect. A change is marked as indirect if either:
8843 ** <li> The session object "indirect" flag is set when the change is
8845 ** <li> The change is made by an SQL trigger or foreign key action
8849 ** If a single row is affected by more than one operation within a session,
8850 ** then the change is considered indirect if all operations meet the criteria
8853 ** This function is used to set, clear or query the session object indirect
8854 ** flag. If the second argument passed to this function is zero, then the
8855 ** indirect flag is cleared. If it is greater than zero, the indirect flag
8856 ** is set. Passing a value less than zero does not modify the current value
8861 ** it is clear, or 1 if it is set.
8868 ** If argument zTab is not NULL, then it is the name of a table to attach
8870 ** made to the table while the session object is enabled will be recorded. See
8873 ** Or, if argument zTab is NULL, then changes are recorded for all tables
8875 ** executing "CREATE TABLE" statements) after this call is made, changes for
8880 ** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY
8883 ** It is not an error if the named table does not exist in the database. Nor
8884 ** is it an error if the named table does not have a PRIMARY KEY. However,
8890 ** SQLITE_OK is returned if the call completes without error. Or, if an error
8891 ** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.
8901 ** The second argument (xFilter) is the "filter callback". For changes to rows
8902 ** in tables that are not attached to the Session oject, the filter is called
8904 ** If xFilter returns 0, changes is not tracked. Note that once a table is
8932 ** column. It is not possible for an UPDATE change to represent a change that
8933 ** modifies the values of primary key columns. If such a change is made, it
8934 ** is represented in a changeset as a DELETE followed by an INSERT.
8937 ** more of their PRIMARY KEY columns. If such a row is inserted or deleted,
8938 ** no corresponding change is present in the changesets returned by this
8940 ** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,
8941 ** only an INSERT is appears in the changeset. Similarly, if an existing row
8942 ** with non-NULL PRIMARY KEY values is updated so that one or more of its
8957 ** a single table are stored is undefined.
8959 ** Following a successful call to this function, it is the responsibility of
8968 ** deleted or updated rows. For each unique primary key value, data is only
8969 ** recorded once - the first time a row with said primary key is inserted,
8972 ** There is one exception to the previous paragraph: when a row is inserted,
8974 ** NULL value, no record of the change is made.
8982 ** When this function is called, the requested changeset is created using
8987 ** <li> For each record generated by an insert, the database is queried
8988 ** for a row with a matching primary key. If one is found, an INSERT
8989 ** change is added to the changeset. If no such row is found, no change
8990 ** is added to the changeset.
8992 ** <li> For each record generated by an update or delete, the database is
8993 ** queried for a row with a matching primary key. If such a row is
8995 ** modified from their original values, an UPDATE change is added to
8996 ** the changeset. Or, if no such row is found in the table, a DELETE
8997 ** change is added to the changeset. If there is a row with a matching
8999 ** values, no change is added to the changeset.
9002 ** This means, amongst other things, that if a row is inserted and then later
9003 ** deleted while a session object is active, neither the insert nor the delete
9004 ** will be present in the changeset. Or if a row is deleted and then later a
9005 ** row with the same primary key values inserted while a session object is
9009 ** When a session object is disabled (see the [sqlite3session_enable()] API),
9012 ** is written to more than once during a session. For example, if a row
9013 ** is inserted while a session object is enabled, then later deleted while
9014 ** the same session object is disabled, no INSERT record will appear in the
9016 ** Or, if one field of a row is updated while a session is disabled, and
9017 ** another field of the same row is updated while the session is enabled, the
9029 ** If it is not already attached to the session object passed as the first
9032 ** does not have a primary key, this function is a no-op (but does not return
9038 ** A table is considered compatible if it:
9046 ** If the tables are not compatible, SQLITE_SCHEMA is returned. If the tables
9047 ** are compatible but do not have any PRIMARY KEY columns, it is not an error
9053 ** so that its content is the same as the table attached to the session
9058 ** the from-table, an INSERT record is added to the session object.
9061 ** the from-table, a DELETE record is added to the session object.
9064 ** different in each, an UPDATE record is added to the session.
9067 ** To clarify, if this function is called and then a changeset constructed
9075 ** If the operation successful, SQLITE_OK is returned. Otherwise, an SQLite
9076 ** error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg
9078 ** message. It is the responsibility of the caller to free this buffer using
9103 ** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly,
9109 ** is passed to the sqlite3changeset_apply() API. Other conflict types work
9130 ** Even if this function returns zero, it is possible that calling
9133 ** an attached table is modified and then later on the original values
9134 ** are restored. However, if this function returns non-zero, then it is
9144 ** If successful, *pp is set to point to the iterator handle and SQLITE_OK
9145 ** is returned. Otherwise, if an error occurs, *pp is set to zero and an
9146 ** SQLite error code is returned.
9158 ** It is the responsibility of the caller to eventually destroy the iterator
9160 ** changeset (pChangeset) must remain valid until after the iterator is
9169 ** consecutively. There is no chance that the iterator will visit a change
9184 ** [sqlite3changeset_start()]. If it is called on an iterator passed to
9186 ** is returned and the call has no effect.
9188 ** Immediately after an iterator is created by sqlite3changeset_start(), it
9190 ** is not empty, the first call to this function advances the iterator to
9194 ** to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned.
9196 ** SQLITE_DONE is returned.
9198 ** If an error occurs, an SQLite error code is returned. Possible error
9199 ** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or
9211 ** is not the case, this function returns [SQLITE_MISUSE].
9213 ** If argument pzTab is not NULL, then *pzTab is set to point to a
9216 ** sqlite3changeset_next() is called on the iterator or until the
9217 ** conflict-handler function returns. If pnCol is not NULL, then *pnCol is
9219 ** pbIncorrect is not NULL, then *pbIndirect is set to true (1) if the change
9220 ** is an indirect change, or false (0) otherwise. See the documentation for
9222 ** changes. Finally, if pOp is not NULL, then *pOp is set to one of
9226 ** If no error occurs, SQLITE_OK is returned. If an error does occur, an
9227 ** SQLite error code is returned. The values of the output variables may not
9248 ** This function is used to find which columns comprise the PRIMARY KEY of
9250 ** If successful, *pabPK is set to point to an array of nCol entries, where
9251 ** nCol is the number of columns in the table. Elements of *pabPK are set to
9252 ** 0x01 if the corresponding column is part of the tables primary key, or
9253 ** 0x00 if it is not.
9255 ** If argumet pnCol is not NULL, then *pnCol is set to the number of columns
9258 ** If this function is called when the iterator does not point to a valid
9259 ** entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise,
9260 ** SQLITE_OK is returned and the output variables populated as described
9277 ** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise,
9282 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
9288 ** is similar to the "old.*" columns available to update or delete triggers.
9291 ** is returned and *ppValue is set to NULL.
9307 ** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise,
9312 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
9317 ** returns SQLITE_OK. If the change is an UPDATE and does not include
9318 ** a new value for the requested column, *ppValue is set to NULL and
9320 ** this is similar to the "new.*" columns available to update or delete
9324 ** is returned and *ppValue is set to NULL.
9338 ** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue
9339 ** is set to NULL.
9343 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
9351 ** is returned and *ppValue is set to NULL.
9378 ** This function is used to finalize an iterator allocated with
9384 ** [sqlite3changeset_apply()], [SQLITE_MISUSE] is immediately returned and the
9390 ** to that error is returned by this function. Otherwise, SQLITE_OK is
9391 ** returned. This is to allow the following pattern (pseudo-code):
9407 ** This function is used to "invert" a changeset object. Applying an inverted
9412 ** <li> Each DELETE change is changed to an INSERT, and
9413 ** <li> Each INSERT change is changed to a DELETE, and
9421 ** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and
9422 ** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are
9425 ** It is the responsibility of the caller to eventually call sqlite3_free()
9429 ** WARNING/TODO: This function currently assumes that the input is a valid
9430 ** changeset. If it is not, the results are undefined.
9440 ** This function is used to concatenate two changesets, A and B, into a
9441 ** single changeset. The result is a changeset equivalent to applying
9479 ** An sqlite3_changegroup object is used to combine two or more changesets
9481 ** object may combine changesets or patchsets, but not both. The output is
9488 ** (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL.
9490 ** The usual usage pattern for an sqlite3_changegroup object is as follows:
9493 ** <li> It is created using a call to sqlite3changegroup_new().
9498 ** <li> The result of combining all input changesets together is obtained
9501 ** <li> The object is deleted using a call to sqlite3changegroup_delete().
9520 ** function. Otherwise, SQLITE_ERROR is returned and no changes are added
9524 ** their PRIMARY KEY columns. A change in the changeset is considered to
9538 ** The new change is ignored. This case does not occur if the new
9546 ** The existing INSERT is removed from the changegroup. The DELETE is
9549 ** The new change is ignored. This case does not occur if the new
9553 ** The existing UPDATE remains within the changegroup. It is amended
9557 ** The existing UPDATE is replaced by the new DELETE within the
9562 ** change, the existing DELETE is replaced by an UPDATE within the
9563 ** changegroup. Otherwise, if the inserted row is exactly the same
9564 ** as the deleted row, the existing DELETE is simply discarded.
9566 ** The new change is ignored. This case does not occur if the new
9570 ** The new change is ignored. This case does not occur if the new
9575 ** If the new changeset contains changes to a table that is already present
9577 ** primary key columns for the table must be consistent. If this is not the
9579 ** appears to be corrupt and the corruption is detected, SQLITE_CORRUPT is
9582 ** final contents of the changegroup is undefined.
9584 ** If no error occurs, SQLITE_OK is returned.
9591 ** were themselves changesets, the output is a changeset. Or, if the
9592 ** inputs were patchsets, the output is also a patchset.
9603 ** If an error occurs, an SQLite error code is returned and the output
9605 ** is returned and the output variables are set to the size of and a
9606 ** pointer to the output buffer, respectively. In this case it is the
9628 ** The fourth argument (xFilter) passed to this function is the "filter
9629 ** callback". If it is not NULL, then for each table affected by at least one
9630 ** change in the changeset, the filter callback is invoked with
9633 ** callback" returns zero, then no attempt is made to apply any changes to
9634 ** the table. Otherwise, if the return value is non-zero or the xFilter
9635 ** argument to this function is NULL, all changes related to the table are
9638 ** For each table that is not excluded by the filter callback, this function
9639 ** tests that the target database contains a compatible table. A table is
9651 ** If there is no compatible table, it is not an error, but none of the
9652 ** changes associated with the table are applied. A warning message is issued
9654 ** one such warning is issued for each table in the changeset.
9656 ** For each change for which there is a compatible table, an attempt is made
9660 ** invoked. A description of exactly when the conflict handler is invoked for
9661 ** each type of change is below.
9667 ** Each time the conflict handler function is invoked, it must return one
9670 ** if the second argument passed to the conflict handler is either
9685 ** the changeset the row is deleted from the target database.
9687 ** If a row with matching primary key values is found, but one or more of
9689 ** row value stored in the changeset, the conflict-handler function is
9692 ** If no row with matching primary key values is found in the database,
9693 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
9696 ** If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT
9697 ** (which can only happen if a foreign key constraint is violated), the
9698 ** conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT]
9700 ** operation is attempted because an earlier call to the conflict handler
9704 ** For each INSERT change, an attempt is made to insert the new row into
9709 ** function is invoked with the second argument set to
9713 ** violation (e.g. NOT NULL or UNIQUE), the conflict handler function is
9715 ** This includes the case where the INSERT operation is re-attempted because
9724 ** the changeset the row is updated within the target database.
9726 ** If a row with matching primary key values is found, but one or more of
9728 ** row value stored in the changeset, the conflict-handler function is
9734 ** If no row with matching primary key values is found in the database,
9735 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
9738 ** If the UPDATE operation is attempted, but SQLite returns
9739 ** SQLITE_CONSTRAINT, the conflict-handler function is invoked with
9741 ** This includes the case where the UPDATE operation is attempted after
9746 ** It is safe to execute SQL statements, including those that write to the
9753 ** write to the target database) occurs, then the savepoint transaction is
9780 ** The conflict handler is invoked with CHANGESET_DATA as the second argument
9782 ** PRIMARY KEY fields is present in the database, but one or more other
9786 ** The conflicting row, in this case, is the database row with the matching
9790 ** The conflict handler is invoked with CHANGESET_NOTFOUND as the second
9792 ** required PRIMARY KEY fields is not present in the database.
9794 ** There is no conflicting row in this case. The results of invoking the
9798 ** CHANGESET_CONFLICT is passed as the second argument to the conflict
9802 ** The conflicting row in this case is the database row with the matching
9806 ** If foreign key handling is enabled, and applying a changeset leaves the
9808 ** handler is invoked with CHANGESET_FOREIGN_KEY as the second argument
9809 ** exactly once before the changeset is committed. If the conflict handler
9812 ** CHANGESET_ABORT, the changeset is rolled back.
9814 ** No current or conflicting row information is provided. The only function
9815 ** it is possible to call on the supplied sqlite3_changeset_iter handle
9816 ** is sqlite3changeset_fk_conflicts().
9820 ** a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is
9823 ** There is no conflicting row in this case. The results of invoking the
9841 ** If a conflict handler returns this value no special action is taken. The
9842 ** change that caused the conflict is not applied. The session module
9848 ** is not the case, any changes applied so far are rolled back and the
9851 ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict
9852 ** handler, then the conflicting row is either updated or deleted, depending
9855 ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_CONFLICT conflict
9856 ** handler, then the conflicting row is removed from the database and a
9857 ** second attempt to apply the change is made. If this second attempt fails,
9858 ** the original row is restored to the database before continuing.
9861 ** If this value is returned, any changes applied so far are rolled back
9889 ** Normally this is convenient. However, if an application running in a
9890 ** low-memory environment is required to handle very large changesets, the
9894 ** is passed to a streaming API functions by way of a callback function that
9895 ** the sessions module invokes to incrementally request input data as it is
9910 ** Each time the xInput callback is invoked by the sessions module, the first
9911 ** argument passed is a copy of the supplied pIn context pointer. The second
9915 ** before returning SQLITE_OK. If the input is completely exhausted, (*pnData)
9918 ** an error, all processing is abandoned and the streaming API function
9944 ** The xOutput callback is invoked zero or more times to return data to
9945 ** the application. The first parameter passed to each call is a copy of the
9951 ** is immediately abandoned and the streaming API function returns a copy
10027 ** a legal notice, here is a blessing:
10083 ** If parameter iCol is less than zero, set output variable *pnToken
10084 ** to the total number of tokens in the FTS5 table. Or, if iCol is
10089 ** If parameter iCol is greater than or equal to the number of columns
10090 ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
10091 ** an OOM condition or IO error), an appropriate SQLite error code is
10098 ** If parameter iCol is less than zero, set output variable *pnToken
10099 ** to the total number of tokens in the current row. Or, if iCol is
10103 ** If parameter iCol is greater than or equal to the number of columns
10104 ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
10105 ** an OOM condition or IO error), an appropriate SQLite error code is
10113 ** current document. If successful, (*pz) is set to point to a buffer
10114 ** containing the text in utf-8 encoding, (*pn) is set to the size in bytes
10115 ** (not characters) of the buffer and SQLITE_OK is returned. Otherwise,
10116 ** if an error occurs, an SQLite error code is returned and the final values
10132 ** "detail=none" or "detail=column" option. If the FTS5 table is created
10134 ** (i.e. if it is a contentless table), then this API always returns 0.
10142 ** Usually, output parameter *piPhrase is set to the phrase number, *piCol
10144 ** first token of the phrase. The exception is if the table was created
10145 ** with the offsets=0 option specified. In this case *piOff is always
10161 ** This API function is used to query the FTS table for phrase iPhrase
10167 ** current query is executed. Any column filter that applies to
10168 ** phrase iPhrase of the current query is included in $p. For each
10170 ** is invoked. The context and API objects passed to the callback
10176 ** query is abandoned and the xQueryPhrase function returns immediately.
10177 ** If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK.
10178 ** Otherwise, the error code is propagated upwards.
10180 ** If the query runs to completion without incident, SQLITE_OK is returned.
10181 ** Or, if some error occurs before the query completes or is aborted by
10182 ** the callback, an SQLite error code is returned.
10192 ** Each extension function is allocated a single auxiliary data slot for
10193 ** each FTS query (MATCH expression). If the extension function is invoked
10197 ** If there is already an auxiliary data pointer when this function is
10198 ** invoked, then it is replaced by the new pointer. If an xDelete callback
10199 ** was specified along with the original pointer, it is invoked at this
10202 ** The xDelete callback, if one is specified, is also invoked on the
10206 ** the auxiliary data is set to NULL and an error code returned. If the
10207 ** xDelete parameter was not NULL, it is invoked on the auxiliary data
10216 ** If the bClear argument is non-zero, then the auxiliary data is cleared
10218 ** if any, is not invoked.
10223 ** This function is used to retrieve the total number of rows in the table.
10229 ** This function is used, along with type Fts5PhraseIter and the xPhraseNext
10231 ** the current row. This is the same information as is accessible via the
10245 ** The Fts5PhraseIter structure is defined above. Applications should not
10251 ** "detail=none" or "detail=column" option. If the FTS5 table is created
10253 ** (i.e. if it is a contentless table), then this API always iterates
10261 ** and xPhraseNext() APIs described above. The difference is that instead
10276 ** "detail=none" option. If the FTS5 table is created with either
10277 ** "detail=none" "content=" option (i.e. if it is a contentless table),
10283 ** (or xInst/xInstCount). The chief advantage of this API is that it is
10336 ** is registered by providing fts5 with a populated instance of the
10342 ** This function is used to allocate and initialize a tokenizer instance.
10343 ** A tokenizer instance is required to actually tokenize text.
10345 ** The first argument passed to this function is a copy of the (void*)
10353 ** The final argument is an output variable. If successful, (*ppOut)
10357 ** is undefined.
10360 ** This function is invoked to delete a tokenizer handle previously
10365 ** This function is expected to tokenize the nText byte string indicated
10367 ** argument passed to this function is a pointer to an Fts5Tokenizer object
10370 ** The second argument indicates the reason that FTS5 is requesting
10371 ** tokenization of the supplied text. This is always one of the following
10374 ** <ul><li> <b>FTS5_TOKENIZE_DOCUMENT</b> - A document is being inserted into
10375 ** or removed from the FTS table. The tokenizer is being invoked to
10379 ** <li> <b>FTS5_TOKENIZE_QUERY</b> - A MATCH query is being executed
10380 ** against the FTS index. The tokenizer is being called to tokenize
10384 ** FTS5_TOKENIZE_QUERY, except that the bareword or quoted string is
10388 ** <li> <b>FTS5_TOKENIZE_AUX</b> - The tokenizer is being invoked to
10400 ** which the token is derived within the input.
10403 ** normally be set to 0. The exception is if the tokenizer supports
10406 ** FTS5 assumes the xToken() callback is invoked for each token in the
10412 ** input buffer is exhausted, xTokenize() should return SQLITE_OK. Finally,
10431 ** same token for inputs "first" and "1st". Say that token is in
10461 ** document such as "I won first place" is tokenized, entries are
10472 ** Whether it is parsing document or query text, any call to xToken that
10474 ** is considered to supply a synonym for the previous token. For example,
10486 ** It is an error to specify the FTS5_TOKEN_COLOCATED flag the first time
10487 ** xToken() is called. Multiple synonyms may be specified for a single token
10489 ** There is no limit to the number of synonyms that may be provided for a
10492 ** In many cases, method (1) above is the best approach. It does not add
10494 ** so it is efficient in terms of disk space and query speed. However, it
10496 ** token "first" is subsituted for "1st" by the tokenizer, then the query:
10512 ** token "1st", but not "first" (assuming the tokenizer is not able to
10519 ** When using methods (2) or (3), it is important that the tokenizer only
10521 ** text (method (3)), not both. Doing so will not cause any errors, but is
10621 ** a legal notice, here is a blessing:
10636 ** The hard limit is the ability of a 32-bit signed integer
10644 ** This is the maximum number of
10654 ** The hard upper limit here is 32676. Most database people will
10657 ** that is the case, there is no point in having more than a few
10668 ** turn the limit off. That is no longer true. It is not possible
10676 ** The maximum depth of an expression tree. This is limited to
10682 ** But that is no longer true. The limit is now strictly enforced
10693 ** if the number of terms is too large. In practice, most SQL
10720 ** IMPLEMENTATION-OF: R-30185-15359 The default suggested cache size is -2000,
10721 ** which means the cache size is limited to 2048000 bytes of memory.
10739 ** and 125. The upper bound of 125 is because the attached databases are
10755 /* Maximum page size. The upper bound on this value is 65536. This a limit
10759 ** compile time. This is no longer permitted, on the grounds that it creates
10760 ** a library that is technically incompatible with an SQLite library
10784 ** Ordinarily, if no value is explicitly provided, SQLite creates databases
10787 ** SQLite may choose a larger value. This constant is the maximum value
10802 ** This is really just the default value for the max_page_count pragma.
10835 #pragma warn -ccc /* Condition is always true or false */
10836 #pragma warn -aus /* Assigned value is never used */
10857 ** The correct "ANSI" way to do this is to use the intptr_t type.
10858 ** Unfortunately, that typedef is not available on all compilers, or
10859 ** if it is available, it requires an #include of specific headers
10913 ** 0 means mutexes are permanently disable and the library is never
10914 ** threadsafe. 1 means the library is serialized which is the highest
10915 ** level of threadsafety. 2 means the library is multithreaded - multiple
10931 ** Powersafe overwrite is on by default. But can be turned off using
10940 ** default unless SQLite is compiled with SQLITE_DEFAULT_MEMSTATUS=0 in
10956 ** On Windows, if the SQLITE_WIN32_MALLOC_VALIDATE macro is defined and the
10957 ** assert() macro is enabled, each call into the Win32 native heap subsystem
10969 are defined but at most one is allowed:\
10981 ** If SQLITE_MALLOC_SOFT_LIMIT is not zero, then try to keep the
11000 ** defined(NDEBUG)==!defined(SQLITE_DEBUG). If this is not currently true,
11006 ** is set. Thus NDEBUG becomes an opt-in rather than an opt-out
11017 ** Enable SQLITE_ENABLE_EXPLAIN_COMMENTS if SQLITE_DEBUG is turned on.
11024 ** The testcase() macro is used to aid in coverage testing. When
11027 ** get full branch coverage. The testcase() macro is inserted
11029 ** condition/decision coverage is inadequate. For example, testcase()
11032 ** is significant and used at least once. On switch statements
11045 ** The TESTONLY macro is used to enclose variable declarations or
11058 ** appear when assert() is disabled. The following macro is therefore
11096 ** Some malloc failures are only possible if SQLITE_TEST_REALLOC_STRESS is
11100 ** that are always false except when SQLITE_TEST_REALLOC_STRESS is set.
11125 ** it is needed by "mutex_w32.c" (when debugging), "os_win.c" (when
11126 ** OSTRACE is enabled), and by several "test*.c" files (which are
11137 ** SQLITE_ENABLE_EXPLAIN_COMMENTS is incompatible with SQLITE_OMIT_EXPLAIN
11144 ** Return true (non-zero) if the input is an integer that is too large
11145 ** to fit in 32-bits. This macro is used inside of various testcase()
11151 ** The macro unlikely() is a hint that surrounds a boolean
11152 ** expression that is usually false. Macro likely() surrounds
11153 ** a boolean expression that is usually true. These hints could,
11166 ** a legal notice, here is a blessing:
11173 ** This is the header file for the generic hash-table implementation
11183 /* A complete hash table is an instance of the following structure.
11198 ** Hash.htsize and Hash.ht may be zero. In that case lookup is done
11200 ** Hash.ht table is never allocated because if there are few elements
11201 ** in the table, it is faster to do a linear search than to manage
11214 /* Each element in the hash table is an instance of the following
11217 ** Again, this structure is intended to be opaque, but it can't really
11218 ** be opaque because it is used by macros.
11235 ** Macros for looping over all elements of a hash table. The idiom is
11428 /* Flags that can be added to a token code when it is not
11461 ** OMIT_TEMPDB is set to 1 if SQLITE_OMIT_TEMPDB is defined, or 0
11472 ** The "file format" number is an integer that is incremented whenever
11491 ** Provide a default value for SQLITE_TEMP_STORE in case it is not specified
11501 ** SQLITE_TEMP_STORE is set to 3 (never use temporary files), set it
11521 ** pagecaches for each database connection. A positive number is the
11523 ** of -1024*N bytes is allocated and used for as many pages as it will hold.
11616 ** SQLITE_MAX_U32 is a u64 constant that is the maximum u64 value
11618 ** is 0x00000000ffffffff. But because of quirks of some compilers, we
11625 ** table or index. This is an unsigned integer type. For 99.9% of
11626 ** the world, a 32-bit integer is sufficient. But a 64-bit integer
11632 typedef u32 tRowcnt; /* 32-bit is the default */
11637 ** logarithms. For quantity X, the value stored is 10*log2(X). This
11639 ** But the allowed values are "grainy". Not every value is representable.
11642 ** not exact values, this imprecision is not a problem.
11644 ** "LogEst" is short for "Logarithmic Estimate".
11674 /* The uptr type is an unsigned integer large enough to hold a pointer
11688 ** In other words, S is a buffer and E is a pointer to the first byte after
11696 ** Macros to determine whether the machine is big or little endian,
11697 ** and whether or not that determination is run-time or compile-time.
11699 ** For best performance, an attempt is made to guess at the byte-order
11700 ** using C-preprocessor macros. If that is unsuccessful, or if
11701 ** -DSQLITE_RUNTIME_BYTEORDER=1 is set, then byte-order is determined
11741 ** Round up a number to the next larger multiple of 8. This is used
11752 ** Assert that the pointer X is aligned to an 8-byte boundary. This
11753 ** macro is used only within assert() to verify that the code gets
11756 ** Except, if SQLITE_4_BYTE_ALIGNED_MALLOC is defined, then the
11767 ** Disable MMAP on platforms where it is known to not work
11795 ** The default MMAP_SIZE is zero on all platforms. Or, even if a larger
11796 ** default MMAP_SIZE is specified at compile-time, make sure that it does
11810 ** Priority is given to SQLITE_ENABLE_STAT4. If either are defined, also
11824 ** the Select query generator tracing logic is turned on.
11833 ** An instance of the following structure is used to store the busy-handler
11838 ** handle is passed a pointer to sqlite.busyHandler. The busy-handler
11839 ** callback is currently invoked only from within pager.c.
11850 ** is a special table that holds the names and attributes of all
11873 ** Determine if the argument is a power of two
11882 ** pointer will work here as long as it is distinct from SQLITE_STATIC
11888 ** When SQLITE_OMIT_WSD is defined, it means that the target platform does
11891 ** the heap. When WSD is unsupported, the variable declarations scattered
11893 ** macro is used for this purpose. And instead of referencing the variable
11895 ** buffer that holds real variable. The constant is also the initializer
11898 ** In the usual case where WSD is supported, the SQLITE_WSD and GLOBAL
11915 ** make it clear to human readers when a function parameter is deliberately
11917 ** a function is called via a function pointer. For example the
11920 ** if it knows that this is enforced elsewhere.
11922 ** When a function parameter is not used at all within the body of a function,
11923 ** it is generally named "NotUsed" or "NotUsed2" to make things even clearer.
11994 ** a legal notice, here is a blessing:
12008 /* TODO: This definition is just included so other modules compile. It
12014 ** If defined as non-zero, auto-vacuum is enabled by default. Otherwise
12050 #define BTREE_MEMORY 2 /* This is an in-memory DB */
12052 #define BTREE_UNORDERED 8 /* Use of a hash implementation is OK */
12095 ** With BTREE_INTKEY, the table key is a 64-bit integer and arbitrary data
12096 ** is stored in the leaves. (BTREE_INTKEY is used for SQL tables.) With
12097 ** BTREE_BLOBKEY, the key is an arbitrary BLOB and no content is stored
12098 ** anywhere - the key is the content. (BTREE_BLOBKEY is used for SQL
12122 ** For example, the free-page-count field is located at byte offset 36 of
12123 ** the database file header. The incr-vacuum-flag field is located at
12126 ** The BTREE_DATA_VERSION value is not really a value stored in the header.
12127 ** It is a read-only number computed by the pager. But we merge it with
12128 ** the header value access routines since its access pattern is the same.
12148 ** The first argument is an Expr* (which is guaranteed to be constant for
12153 ** then the value of the node is the value in Mem[pExpr.iTable]. Any
12159 ** The design of the _RANGE hint is aid b-tree implementations that try
12164 ** Note that BTREE_HINT_FLAGS with BTREE_BULKLOAD is the only hint used by
12175 ** The BTREE_BULKLOAD flag is set on index cursors when the index is going
12176 ** to be filled with content that is already in sorted order.
12178 ** The BTREE_SEEK_EQ flag is set on cursors that will get OP_SeekGE or
12190 ** For read-only cursors the wrFlag argument is always zero. For read-write
12192 ** (BTREE_WRCSR). If the BTREE_FORDELETE bit is set, then the cursor will
12200 ** The BTREE_FORDELETE flag is an optimization hint. It is not used by
12201 ** by this, the native b-tree engine of SQLite, but it is available to
12211 #define BTREE_FORDELETE 0x00000008 /* Cursor is for seek/delete only */
12251 ** the key and passed in the nKey field. The pKey field is zero.
12255 ** This object is used to pass information into sqlite3BtreeInsert(). The
12311 ** If we are not using shared cache, then there is no need to
12361 ** a legal notice, here is a blessing:
12379 ** A single VDBE is an opaque structure named "Vdbe". Only routines
12394 ** and as many as three operands. The instruction is recorded
12401 u8 p5; /* Fifth parameter is an unsigned character */
12409 i64 *pI64; /* Used when p4type is P4_INT64 */
12410 double *pReal; /* Used when p4type is P4_REAL */
12411 FuncDef *pFunc; /* Used when p4type is P4_FUNCDEF */
12412 sqlite3_context *pCtx; /* Used when p4type is P4_FUNCCTX */
12413 CollSeq *pColl; /* Used when p4type is P4_COLLSEQ */
12414 Mem *pMem; /* Used when p4type is P4_MEM */
12415 VTable *pVtab; /* Used when p4type is P4_VTAB */
12416 KeyInfo *pKeyInfo; /* Used when p4type is P4_KEYINFO */
12417 int *ai; /* Used when p4type is P4_INTARRAY */
12418 SubProgram *pProgram; /* Used when p4type is P4_SUBPROGRAM */
12419 Table *pTab; /* Used when p4type is P4_TABLE */
12421 Expr *pExpr; /* Used when p4type is P4_EXPR */
12467 #define P4_NOTUSED 0 /* The P4 parameter is not used */
12470 #define P4_COLLSEQ (-4) /* P4 is a pointer to a CollSeq structure */
12471 #define P4_FUNCDEF (-5) /* P4 is a pointer to a FuncDef structure */
12472 #define P4_KEYINFO (-6) /* P4 is a pointer to a KeyInfo structure */
12473 #define P4_EXPR (-7) /* P4 is a pointer to an Expr tree */
12474 #define P4_MEM (-8) /* P4 is a pointer to a Mem* structure */
12475 #define P4_TRANSIENT 0 /* P4 is a pointer to a transient string */
12476 #define P4_VTAB (-10) /* P4 is a pointer to an sqlite3_vtab structure */
12477 #define P4_MPRINTF (-11) /* P4 is a string obtained from sqlite3_mprintf() */
12478 #define P4_REAL (-12) /* P4 is a 64-bit floating point value */
12479 #define P4_INT64 (-13) /* P4 is a 64-bit signed integer */
12480 #define P4_INT32 (-14) /* P4 is a 32-bit signed integer */
12481 #define P4_INTARRAY (-15) /* P4 is a vector of 32-bit integers */
12482 #define P4_SUBPROGRAM (-18) /* P4 is a pointer to a SubProgram structure */
12483 #define P4_ADVANCE (-19) /* P4 is a pointer to BtreeNext() or BtreePrev() */
12484 #define P4_TABLE (-20) /* P4 is a pointer to a Table structure */
12485 #define P4_FUNCCTX (-21) /* P4 is a pointer to an sqlite3_context object */
12494 ** The Vdbe.aColName array contains 5n Mem structures, where n is the
12515 ** sqlite3VdbeAddOpList() knows that the address is relative. Calling
12696 #define OPFLG_IN1 0x02 /* in1: P1 is an input */
12697 #define OPFLG_IN2 0x04 /* in2: P2 is an input */
12698 #define OPFLG_IN3 0x08 /* in3: P3 is an input */
12699 #define OPFLG_OUT2 0x10 /* out2: P2 is an output */
12700 #define OPFLG_OUT3 0x20 /* out3: P3 is an output */
12724 /* The sqlite3P2Values() routine is able to run faster if it knows
12847 ** VdbeCoverageAlwaysTaken(v) // Previous branch is always taken
12849 ** VdbeCoverageNeverTaken(v) // Previous branch is never taken
12852 ** If not, then when "make test" is run with -DSQLITE_VDBE_COVERAGE and
12887 ** a legal notice, here is a blessing:
12913 ** is called page 1. 0 is used to represent "not a page".
12918 ** Each open file is managed by a separate instance of the "Pager" structure.
12928 ** Page number PAGER_MJ_PGNO is never used in an SQLite database (it is
12929 ** reserved for working around a windows/posix incompatibility). It is
12931 ** is devoted to storing a master journal name - there are no more pages to
12971 #define PAGER_GET_READONLY 0x02 /* Read-only page is acceptable */
13125 ** a legal notice, here is a blessing:
13142 ** Every page in the cache is controlled by an instance of the following
13150 Pager *pPager; /* The pager this page is part of */
13158 ** Elements above are public. All that follows is private to pcache.c
13170 #define PGHDR_DIRTY 0x002 /* Page is on the PCache.pDirty list */
13175 #define PGHDR_MMAP 0x020 /* This is an mmap page object */
13209 /* One release per successful fetch. Page is pinned until released.
13218 SQLITE_PRIVATE void sqlite3PcacheMakeDirty(PgHdr*); /* Make sure page is marked dirty */
13254 ** interface is only available if SQLITE_CHECK_PAGES is defined when the
13255 ** library is built.
13267 ** If no global maximum is configured, then the system attempts to limit
13278 ** The spill-size is the minimum number of pages in cache before the cache
13314 ** a legal notice, here is a blessing:
13322 ** This header file (together with is companion C source-code file
13326 ** This header file is #include-ed by sqliteInt.h and thus ends up
13342 ** a legal notice, here is a blessing:
13399 /* If the SET_FULLSYNC macro is not defined above, then make it
13417 ** If sqlite is being embedded in another program, you may wish to change the
13428 ** For this reason, the default name prefix is changed to be "sqlite"
13430 ** anybody smart enough to figure out the code is also likely smart
13469 ** A SHARED_LOCK is obtained by locking a single randomly-chosen
13470 ** byte out of a specific range of bytes. The lock byte is obtained at
13473 ** An EXCLUSIVE_LOCK is obtained by locking all bytes in the range.
13474 ** There can only be one writer. A RESERVED_LOCK is obtained by locking
13475 ** a single byte of the file that is designated as the reserved lock byte.
13476 ** A PENDING_LOCK is obtained by locking a designated byte different from
13481 ** are used, the lock is placed on the same range of bytes that is used
13488 ** SHARED_SIZE is the number of bytes available in the pool from which
13489 ** a random byte is selected for a shared lock. The pool of bytes for
13496 ** tool is being used for file sharing) implements locks correctly between
13500 ** Locking in windows is manditory. For this reason, we cannot store
13502 ** the pages involved in locking therefore. SHARED_SIZE is selected so
13505 ** is set high so that we don't have to allocate an unused page except
13510 ** file format. Depending on how it is changed, you might not notice
13512 ** The default location of PENDING_BYTE is the first byte past the
13590 ** a legal notice, here is a blessing:
13599 ** The sqliteInt.h header #includes this file so that it is available
13617 ** mutual exclusion is provided. But this
13640 ** If this is a no-op implementation, implement everything as macros.
13661 ** synchronous setting to EXTRA. It is no longer supported.
13692 ** Each database file to be accessed by the system is an instance
13694 ** in the sqlite.aDb[] array. aDb[0] is the main database file and
13695 ** aDb[1] is the database file used to hold temporary tables. Additional
13709 ** Most Schema objects are associated with a Btree. The exception is
13710 ** the Schema for the TEMP databaes (sqlite3.aDb[1]) which is free-standing.
13715 ** references them is destroyed. The TEMP Schema is manually freed by
13721 ** For a TEMP Schema, only the connection mutex is required.
13749 ** The DB_SchemaLoaded flag is set after the database schema has been
13758 #define DB_Empty 0x0004 /* The file is empty (length 0 bytes) */
13767 ** Lookaside malloc is a set of fixed-size buffers that can be used
13776 ** the lookaside subsystem is stored on a linked list of LookasideSlot
13782 ** is shared by multiple database connections. Therefore, while parsing
13783 ** schema information, the Lookaside.bEnabled flag is cleared so that
13852 /* This is an extra SQLITE_TRACE macro that indicates "legacy" tracing
13862 ** Each database connection is an instance of the following structure.
13888 u8 isTransactionSavepoint; /* True if the outermost savepoint is a TS */
13898 u8 iDb; /* Which db file is being initialized */
13900 u8 orphanTrigger; /* Last statement is orphaned TEMP trigger */
13971 ** When X.pUnlockConnection==Y, that means that X is waiting for Y to
14014 /* result set is empty */
14072 ** code. The argument is a Parse object for the code generator.
14081 #define SQLITE_MAGIC_OPEN 0xa029a697 /* Database is open */
14082 #define SQLITE_MAGIC_CLOSED 0x9f3c2d33 /* Database is closed */
14089 ** Each SQL function is defined by an instance of the following
14091 ** a pointer to this structure is held in the sqlite3BuiltinFunctions object.
14093 ** structure is held in the db->aHash hash table.
14095 ** The u.pHash field is used by the global built-ins. The u.pDestructor
14096 ** field is used by per-connection app-def functions.
14115 ** create_function_v2() is called to create a function with a destructor,
14116 ** a single object of this type is allocated. FuncDestructor.nRef is set to
14118 ** or not the specified encoding is SQLITE_ANY). The FuncDef.pDestructor
14119 ** member of each of the new FuncDef objects is set to point to the allocated
14122 ** Thereafter, when one of the FuncDef objects is deleted, the reference
14123 ** count on this object is decremented. When it reaches 0, the destructor
14124 ** is invoked and the FuncDestructor structure freed.
14167 ** value passed as iArg is cast to a (void*) and made available
14169 ** argument bNC is true, then the SQLITE_FUNC_NEEDCOLL flag is set.
14188 ** that accepts nArg arguments and is implemented by a call to C
14189 ** function likeFunc. Argument pArg is cast to a (void *) and made
14191 ** FuncDef.flags variable is set to the value passed as the flags
14221 ** sqlite3.pSavepoint. The first element in the list is the most recently
14242 ** Each SQLite module (virtual table definition) is defined by an
14255 ** information about each column of an SQL table is held in an instance
14270 #define COLFLAG_PRIMKEY 0x0001 /* Column is part of the primary key */
14275 ** A "Collating Sequence" is defined by an instance of the following
14279 ** If CollSeq.xCmp is NULL, it means that the
14280 ** collating sequence is undefined. Indices built on an undefined
14310 ** for a numeric type is a single comparison. And the BLOB type is first.
14330 ** The SQLITE_NOTNULL flag is a combination of NULLEQ and JUMPIFNULL.
14332 ** operator is NULL. It is added to certain comparison operators to
14335 #define SQLITE_JUMPIFNULL 0x10 /* jumps if either operand is NULL */
14341 ** An object of this type is created for each virtual table present in
14344 ** If the database schema is shared, then there is one instance of this
14346 ** schema. This is because each database connection requires its own unique
14350 ** schema is shared, as the implementation often stores the database
14361 ** When an sqlite3_prepare() operation is required to access the virtual
14366 ** When an in-memory Table object is deleted (for example when the
14367 ** schema is being reloaded for some reason), the VTable objects are not
14372 ** next time a statement is prepared using said sqlite3*. This is done
14375 ** explanation as to why it is safe to add an entry to an sqlite3.pDisconnect
14378 ** The memory for objects of this type is always allocated by
14393 ** The schema for each SQL table and view is represented in memory
14434 ** vtab1(a HIDDEN, b);". Since "b" is a non-hidden column but "a" is hidden,
14441 #define TF_Autoincrement 0x08 /* Integer primary key is autoincrement */
14443 #define TF_WithoutRowid 0x20 /* No rowid. PRIMARY KEY is the key */
14449 ** Test to see whether or not a table is a virtual table. This is
14451 ** table support is omitted from the build.
14460 ** Macros to determine if a column is hidden. IsOrdinaryHiddenColumn()
14461 ** only works for non-virtual tables (ordinary tables and views) and is
14462 ** always false unless SQLITE_ENABLE_HIDDEN_COLUMNS is defined. The
14463 ** IsHiddenColumn() macro is general purpose.
14482 ** Each foreign key constraint is an instance of the following structure.
14484 ** A foreign key is associated with two tables. The "from" table is
14486 ** key. The "to" table is the table that is named in the REFERENCES clause.
14494 ** For foreign key "fk1", the from-table is "ex1" and the to-table is "ex2".
14501 ** which is attached to the from-table. The to-table need not exist when
14502 ** the from-table is created. The existence of the to-table is not checked.
14504 ** The list of all parents for child Table X is held at X.pFKey.
14507 ** is held in Schema.fkeyHash with a hash key of Z.
14517 u8 isDeferred; /* True if constraint checking is deferred till COMMIT */
14532 ** but the transaction is not rolled back. FAIL processing means that
14536 ** error is not inserted or updated. Processing continues and no error
14537 ** is returned. REPLACE means that preexisting database rows that caused
14539 ** update can proceed. Processing continues and no error is reported.
14542 ** RESTRICT is the same as ABORT for IMMEDIATE foreign keys and the
14544 ** key is set to NULL. CASCADE means that a DELETE or UPDATE of the
14545 ** referenced table row is propagated into the row that holds the
14551 #define OE_None 0 /* There is no constraint to check */
14563 #define OE_Default 10 /* Do whatever the default action is */
14567 ** An instance of the following structure is passed as the first
14568 ** argument to sqlite3VdbeKeyCompare and is used to control the
14589 ** A record is an object that contains one or more fields of data.
14591 ** the key of an index. A blob encoding of a record is created by
14592 ** the OP_MakeRecord opcode of the VDBE and is disassembled by the
14596 ** an index b+tree. The goal of the search is to find the entry that
14597 ** is closed to the key described by this object. This object might hold
14598 ** just a prefix of the key. The number of fields is given by
14601 ** The r1 and r2 fields are the values to return if this key is less than
14604 ** is in DESC order.
14633 ** Each SQL index is represented in memory by an
14646 ** The value of aiColumn is {2, 0}. aiColumn[0]==2 because the
14653 ** it means this is not a unique index. Otherwise it is a unique index
14655 ** algorithm to employ whenever an attempt is made to insert a non-unique
14661 ** of this structure may be created. In this case the Index.tnum variable is
14663 ** number (it cannot - the database page is not allocated until the VDBE
14664 ** program is executed). See convertToWithoutRowidTable() for details.
14668 i16 *aiColumn; /* Which columns are used by this index. 1st is 0 */
14687 unsigned isCovering:1; /* True if this is a covering index */
14706 /* Return true if index X is a PRIMARY KEY index */
14709 /* Return true if index X is a UNIQUE index */
14715 #define XN_ROWID (-1) /* Indexed column is the rowid */
14716 #define XN_EXPR (-2) /* Indexed column is an expression */
14719 ** Each sample stored in the sqlite_stat3 table is represented in memory
14727 tRowcnt *anLt; /* Est. number of rows where key is less than this sample */
14732 ** Each token coming out of the lexer is an instance of
14748 ** If Expr.op==TK_AGG_COLUMN or TK_AGG_FUNCTION then Expr.pAggInfo is a
14749 ** pointer to this structure. The Expr.iColumn field is the index in
14789 ** The datatype ynVar is a signed integer, either 16-bit or 32-bit.
14790 ** Usually it is 16-bits. But if SQLITE_MAX_VARIABLE_NUMBER is greater
14791 ** than 32767 we have to make it 32-bit. 16-bit is preferred because
14792 ** it uses less memory in the Expr object, which is a big memory user
14796 ** the option is available (at compile-time).
14805 ** Each node of an expression in the parse tree is an instance
14808 ** Expr.op is the opcode. The integer parser token codes are reused
14810 ** code representing the ">=" operator. This same integer code is reused
14814 ** If the expression is an SQL literal (TK_INTEGER, TK_FLOAT, TK_BLOB,
14816 ** the expression is a variable (TK_VARIABLE), then Expr.token contains the
14817 ** variable name. Finally, if the expression is an SQL function (TK_FUNCTION),
14823 ** Expr.x.pList is a list of arguments if the expression is an SQL function,
14825 ** Expr.x.pSelect is used if the expression is a sub-select or an expression of
14826 ** the form "<lhs> IN (SELECT ...)". If the EP_xIsSelect bit is set in the
14827 ** Expr.flags mask, then Expr.x.pSelect is valid. Otherwise, Expr.x.pList is
14831 ** For such expressions, Expr.op is set to TK_COLUMN and Expr.iTable is
14833 ** Expr.iColumn is the column number for the specific column. If the
14834 ** expression is used as a result in an aggregate SELECT, then the
14835 ** value is also stored in the Expr.iAgg column in the aggregate so that
14838 ** If the expression is an unbound variable marker (a question mark
14842 ** If the expression is a subquery then Expr.iColumn holds an integer
14844 ** subquery gives a constant result, then iTable is -1. If the subquery
14846 ** then iTable is the address of a subroutine that computes the subquery.
14848 ** If the Expr is of type OP_Column, and the table it is selecting from
14849 ** is a disk table or the "old.*" pseudo-table, then pTab points to the
14861 ** an Expr object is truncated. When EP_Reduced is set, then all
14865 ** allocated, regardless of whether or not EP_Reduced is set.
14876 /* If the EP_TokenOnly flag is set in the Expr.flags mask, then no
14877 ** space is allocated for the fields below this point. An attempt to
14888 /* If the EP_Reduced flag is set in the Expr.flags mask, then no
14889 ** space is allocated for the fields below this point. An attempt to
14919 #define EP_VarSelect 0x000020 /* pSelect is correlated, not constant */
14925 #define EP_xIsSelect 0x000800 /* x.pSelect is valid (otherwise x.pList is) */
14952 /* The ExprSetVVAProperty() macro is used for Verification, Validation,
14954 ** processes but is a no-op for delivery.
14983 ** field is not used.
14986 ** the expression that is used in the generation of error messages and
14987 ** column labels. In this case, Expr.zSpan is typically the text of a
14989 ** the bSpanIsTab flag is set, then zSpan is overloaded to mean the name
14991 ** form is used for name resolution with nested FROM clauses.
15000 unsigned done :1; /* A flag to indicate when processing is finished */
15002 unsigned reusable :1; /* Constant expression is reusable */
15008 int iConstExprReg; /* Register in which Expr value is cached */
15014 ** An instance of this structure is used by the parser to record both
15032 ** The IdList.a.idx field is used when the IdList represents the list of
15037 ** If "a" is the k-th column of table "t", then IdList.a[0].idx==k.
15048 ** The bitmask datatype defined below is used for various optimizations.
15074 ** Each table or subquery in the FROM clause is a separate element of
15079 ** is modified by an INSERT, DELETE, or UPDATE statement. In standard SQL,
15088 ** In the colUsed field, the high-order bit (bit 63) is set if the table
15089 ** contains more than 63 columns and the 64-th or later column is used.
15095 Schema *pSchema; /* Schema to which this item is fixed */
15098 char *zAlias; /* The "B" part of a "A AS B" phrase. zName is the "A" */
15106 unsigned notIndexed :1; /* True if there is a NOT INDEXED clause */
15107 unsigned isIndexedBy :1; /* True if there is an INDEXED BY clause */
15109 unsigned isCorrelated :1; /* True if sub-query is correlated */
15119 Bitmask colUsed; /* Bit N (1<<N) set if column N of pTab is used */
15136 #define JT_OUTER 0x0020 /* The "OUTER" keyword is present */
15151 #define WHERE_ONEPASS_MULTIROW 0x0008 /* ONEPASS is ok with multiple rows */
15155 #define WHERE_GROUPBY 0x0040 /* pOrderBy is really a GROUP BY */
15156 #define WHERE_DISTINCTBY 0x0080 /* pOrderby is really a DISTINCT clause */
15179 ** pEList corresponds to the result set of a SELECT and is NULL for
15183 ** context is searched first. If no match is found, the next outer
15184 ** context is checked. If there is still no match, the next context
15185 ** is checked. This process continues until either a match is found
15186 ** or all contexts are check. When a match is found, the nRef member of
15187 ** the context containing the match is incremented.
15226 ** nLimit is set to -1 if there is no LIMIT clause. nOffset is set to 0.
15227 ** If there is a LIMIT clause, the parser sets nLimit to the value of the
15228 ** limit and nOffset to the value of the offset (or 0 if there is not
15236 ** as the OP_OpenEphm instruction is coded because not
15237 ** enough information about the compound query is known at that point.
15304 ** set is not empty.
15306 ** SRT_Discard Throw the results away. This is used by SELECT
15307 ** statements within triggers whose only purpose is
15316 ** SRT_Mem Only valid if the result is a single column.
15327 ** the result there. The cursor is left open after
15328 ** returning. This is like SRT_Table except that
15333 ** results each time it is invoked. The entry point
15334 ** of the co-routine is stored in register pDest->iSDParm
15335 ** and the result row is stored in pDest->nDest registers
15339 ** SRT_Fifo This is like SRT_EphemTab except that the table
15340 ** is assumed to already be open. SRT_Fifo has
15359 #define SRT_Exists 3 /* Store 1 if the result is not empty */
15366 /* The ORDER BY clause is ignored for all of the above */
15391 ** tables, the following information is attached to the Table.u.autoInc.p
15413 ** At least one instance of the following structure is created for each
15421 ** TriggerPrg.orconf, is stored in the TriggerPrg.pProgram variable.
15425 ** The TriggerPrg.aColmask[0] variable is set to a mask of old.* columns
15427 ** statements). Similarly, the TriggerPrg.aColmask[1] variable is set to
15458 ** An SQL parser context. A copy of this structure is passed through
15460 ** carry around information that is global to the entire parse.
15462 ** The structure is divided into two parts. When the parser and code
15464 ** is constant but the second part is reset at the beginning and end of
15468 ** feature is enabled (if sqlite3Tsd()->useSharedData is true). They are
15470 ** compiled. Function sqlite3TableLock() is used to add entries to the
15508 u8 tempReg; /* iReg is a temp register that needs to be freed */
15543 ** Above is constant between recursions. Below is reset before and after
15544 ** each recursion. The boundary between these two regions is determined
15552 u8 explain; /* True if the EXPLAIN flag is found on the query */
15613 #define OPFLAG_EPHEM 0x01 /* OP_Column: Ephemeral output is ok */
15615 #define OPFLAG_ISUPDATE 0x04 /* This OP_Insert is an sql UPDATE */
15616 #define OPFLAG_APPEND 0x08 /* This is likely to be an append */
15626 #define OPFLAG_P2ISREG 0x10 /* P2 to OP_Open** is a register number */
15632 * Each trigger present in the database schema is stored as an instance of
15640 * linked list is stored as the "pTrigger" member of the associated
15652 IdList *pColumns; /* If this is an UPDATE OF <column-list> trigger,
15653 the <column-list> is stored here */
15661 ** A trigger is either a BEFORE or an AFTER trigger. The following constants
15671 * An instance of struct TriggerStep is used to store a single SQL statement
15672 * that is a part of a trigger-program.
15676 * associated struct Trigger instance. The first element of the linked list is
15679 * The "op" member indicates whether this is a "DELETE", "INSERT", "UPDATE" or
15680 * "SELECT" statement. The meanings of the other members is determined by the
15685 * pSelect -> If this is an INSERT INTO ... SELECT ... statement, then
15688 * pExprList -> If this is an INSERT INTO ... VALUES ... statement, then
15690 * pIdList -> If this is an INSERT INTO ... (<column-names>) VALUES ...
15696 * pWhere -> The WHERE clause of the DELETE statement if one is specified.
15701 * pWhere -> The WHERE clause of the UPDATE statement if one is specified.
15711 Trigger *pTrig; /* The trigger that this step is a part of */
15754 #define SQLITE_PRINTF_MALLOCED 0x04 /* True if xText is allocated space */
15760 ** A pointer to this structure is used to communicate information
15782 int neverCorrupt; /* Database is always well-formed */
15808 int isMallocInit; /* True after malloc is initialized */
15809 int isPCacheInit; /* True after malloc is initialized */
15819 /* The following callback (if not NULL) is invoked on every VDBE branch
15832 ** This macro is used inside of assert() statements to indicate that
15833 ** the assert is only valid on a well-formed database. Instead of:
15841 ** CORRUPT_DB is true during normal operation. CORRUPT_DB does not indicate
15842 ** that the database is definitely corrupt, only that it might be corrupt.
15843 ** For most test cases, CORRUPT_DB is set to false using a special
15904 ** An instance of the TreeView object is used for printing the content of
15909 u8 bLine[100]; /* Draw vertical in column i if bLine[i] is true */
15955 ** FTS4 is really an extension for FTS3. It is enabled using the
15964 ** The ctype.h header is needed for non-ASCII systems. It is also
15965 ** needed by FTS3 when FTS3 is included in the amalgamation.
16269 #define ONEPASS_MULTI 2 /* ONEPASS is valid for multiple rows */
16463 ** The common case is for a varint to be a single byte. They following
16696 ** no-op macros if OMIT_FOREIGN_KEY is defined. In this case no foreign
16697 ** key functionality is available. If OMIT_TRIGGER is defined but
16698 ** OMIT_FOREIGN_KEY is not, only some of the functions are no-oped. In
16699 ** this case foreign keys are parsed, but no other functionality is
16733 ** malloc failures. This is only present if SQLITE_OMIT_BUILTIN_TEST
16734 ** is not defined.
16797 ** sqlite3IoTrace is a pointer to a printf-like routine used to
16820 ** sqlite3MemdebugHasType() is intended for use inside assert() statements.
16825 ** Perhaps the most important point is the difference between MEMTYPE_HEAP
16826 ** and MEMTYPE_LOOKASIDE. If an allocation is MEMTYPE_LOOKASIDE, that means
16828 ** too large or lookaside was already full. It is important to verify
16834 ** All of this is no-op for a production build. It only comes into
16835 ** play when the SQLITE_MEMDEBUG compile-time option is used.
16871 ** a legal notice, here is a blessing:
16929 ** The following 256 byte lookup table is used to support SQLites built-in
16941 ** Bit 0x20 is set if the mapped character requires translation to upper
16942 ** case. i.e. if the character is a lower-case ASCII character.
16943 ** If x is a lower-case ASCII character, then its upper-case equivalent
16944 ** is (x - 0x20). Therefore toupper() can be implemented as:
16948 ** Standard function tolower() is implemented using the sqlite3UpperToLower[]
16949 ** array. tolower() is used more often than toupper() by SQLite.
16951 ** Bit 0x40 is set if the character non-alphanumeric and can be used in an
16953 ** non-ASCII UTF character. Hence the test for whether or not a character is
16954 ** part of an identifier is 0x46.
17000 ** compatibility for legacy applications, the URI filename capability is
17006 ** EVIDENCE-OF: R-43642-56306 By default, URI handling is globally
17014 /* EVIDENCE-OF: R-38720-18127 The default setting is determined by the
17015 ** SQLITE_ALLOW_COVERING_INDEX_SCAN compile-time option, or is "on" if
17016 ** that compile-time option is omitted.
17022 /* The minimum PMA size is set to this value multiplied by the database
17033 ** memory. (The statement journal is also always held entirely in memory
17099 ** database connections. After initialization, this table is
17117 ** to read or write that page. The pending byte page is set assign
17120 ** During testing, it is often desirable to move the pending byte to
17137 ** Properties of opcodes. The OPFLG_INITIALIZER macro is
17138 ** created by mkopcodeh.awk during compilation. Data is obtained
17155 ** a legal notice, here is a blessing:
17176 ** only a handful of compile-time options, so most times this array is usually
17182 ** for those options in which the value is meaningful. */
17564 ** is not required for a match.
17578 /* Since ArraySize(azCompileOpt) is normally in single digits, a
17579 ** linear search is adequate. No need for a binary search. */
17591 ** Return the N-th compile-time option string. If N is out of range,
17609 ** a legal notice, here is a blessing:
17627 ** a legal notice, here is a blessing:
17634 ** This is the header file for information that is private to the
17652 ** VDBE_DISPLAY_P4 is true or false depending on whether or not the
17653 ** "explain" P4 display logic is enabled.
17663 ** SQL is translated into a sequence of instructions to be
17664 ** executed by a virtual machine. Each instruction is an instance
17690 ** A VdbeCursor is an superclass (a wrapper) for various cursor objects:
17704 u8 deferredMoveto; /* A call to sqlite3BtreeMoveto() is needed */
17712 Bool isOrdered:1; /* True if the table is not BTREE_UNORDERED */
17734 ** cursor is currently pointing to. Only valid if cacheStatus matches
17737 ** the cache is out of date.
17742 u32 cacheStatus; /* Cache is valid if this matches Vdbe.cacheCtr */
17755 ** When a sub-program is executed (OP_Program), a structure of this type
17756 ** is allocated to store the current value of the program counter, as
17758 ** values stored in the Vdbe struct. When the sub-program is finished,
17763 ** The memory for a VdbeFrame object is allocated and managed by a memory
17764 ** cell in the parent (calling) frame. When the memory cell is deleted or
17765 ** overwritten, the VdbeFrame object is not freed immediately. Instead, it
17766 ** is linked into the Vdbe.pDelFrame list. The contents of the Vdbe.pDelFrame
17767 ** list is deleted when the VM is reset in VdbeHalt(). The reason for doing
17768 ** this instead of deleting the VdbeFrame immediately is to avoid recursive
17772 ** The currently executing frame is stored in Vdbe.pFrame. Vdbe.pFrame is
17773 ** set to NULL if the currently executing frame is the main program.
17778 VdbeFrame *pParent; /* Parent of this frame, or NULL if parent is main */
17801 ** A value for VdbeCursor.cacheValid that means the cache is always invalid.
17812 double r; /* Real value used when MEM_Real is set in flags */
17813 i64 i; /* Integer value used when MEM_Int is set in flags */
17814 int nZero; /* Used when bit MEM_Zero is set in flags */
17831 Mem *pScopyFrom; /* This Mem is a shallow copy of pScopyFrom */
17832 void *pFiller; /* So that sizeof(Mem) is a multiple of 8 */
17845 ** If the MEM_Null flag is set, then the value is an SQL NULL value.
17848 ** If the MEM_Str flag is set then Mem.z points at a string representation.
17849 ** Usually this is encoded in the same unicode encoding as the main
17850 ** database (see below for exceptions). If the MEM_Term flag is also
17851 ** set, then the string is nul terminated. The MEM_Int and MEM_Real
17854 #define MEM_Null 0x0001 /* Value is NULL */
17855 #define MEM_Str 0x0002 /* Value is a string */
17856 #define MEM_Int 0x0004 /* Value is an integer */
17857 #define MEM_Real 0x0008 /* Value is a real number */
17858 #define MEM_Blob 0x0010 /* Value is a BLOB */
17860 #define MEM_RowSet 0x0020 /* Value is a RowSet object */
17861 #define MEM_Frame 0x0040 /* Value is a VdbeFrame object */
17862 #define MEM_Undefined 0x0080 /* Value is undefined */
17870 ** string is \000 or \u0000 terminated
17872 #define MEM_Term 0x0200 /* String rep is nul terminated */
17878 #define MEM_Subtype 0x8000 /* Mem.eSubtype is valid */
17897 ** Return true if a memory cell is not marked as invalid. This macro
17898 ** is for use inside assert() statements only.
17906 ** implementation calling sqlite3_set_auxdata() is stored in an instance
17909 ** when the VM is halted (if not before).
17921 ** instance of this structure is the first argument to the routines used
17924 ** There is a typedef for this structure in sqlite.h. So all routines,
17926 ** But this file is the only place where the internal details of this
17929 ** This structure is defined inside of vdbeInt.h because it uses substructures
17933 Mem *pOut; /* The return value is stored here */
17946 ** An Explain object accumulates indented output which is helpful
17958 ** N is the number of bits.
17976 ** The "sqlite3_stmt" structure pointer that is returned by sqlite3_prepare()
17977 ** is really a pointer to an instance of this structure.
18049 #define VDBE_MAGIC_RUN 0xbdf20da3 /* VDBE is ready to execute */
18221 ** state vector. If writable static data is unsupported on the target,
18223 ** case where writable static data is supported, wsdStat can refer directly
18249 ** appropriate mutex. (Locking is checked by assert()).
18252 ** The value of N is added to the current status value and the high-water
18253 ** mark is adjusted if necessary.
18256 ** mark is unchanged. N must be non-negative for StatusDown().
18347 sqlite3 *db, /* The database connection whose status is desired */
18389 ** highwater mark is meaningless and is returned as zero.
18416 ** databases. *pHighwater is set to zero.
18459 ** *pHighwater is set to zero.
18480 ** pagers the database handle is connected to. *pHighwater is always set
18506 ** have been satisfied. The *pHighwater is always set to zero.
18528 ** a legal notice, here is a blessing:
18538 ** There is only one exported symbol in this file - the function
18547 ** 1970-01-01 00:00:00 is JD 2440587.5
18548 ** 2000-01-01 00:00:00 is JD 2451544.5
18555 ** The Gregorian calendar system is used for all dates and times,
18578 ** So declare a substitute. The substitute function itself is
18598 char validJD; /* True (1) if iJD is valid */
18599 char validTZ; /* True (1) if tz is valid */
18609 ** the last integer which is specified by three characters. The meaning
18610 ** of a four-character format specifiers ABCD is:
18621 ** D: the separator character, or \000 to indicate this is the
18627 ** the 2-digit day which is the last integer in the set.
18671 ** The extension is of the form:
18679 ** If the parse is successful, write the number of minutes
18683 ** A missing specifier is not considered an error.
18719 ** Return 1 if there is a parsing error and 0 on success.
18759 ** that the YYYY-MM-DD is according to the Gregorian calendar.
18806 ** on success and 1 if the input string is not a well-formed
18866 ** In the first form, the +/-HH:MM is always optional. The fractional
18867 ** seconds extension (the ".FFF") is optional. The seconds portion
18868 ** (":SS.FFF") is option. The year and date can be omitted as long
18869 ** as there is a time string. The time string can be omitted as long
18870 ** as there is a year and date.
18955 ** On recent Windows platforms, the localtime_s() function is available
18956 ** as part of the "Secure CRT". It is essentially equivalent to
18958 ** order of the parameters is reversed.
18975 ** is available. This routine returns 0 on success and
18978 ** If the sqlite3GlobalConfig.bLocaltimeFault variable is true then this
18982 ** library function localtime_r() is used to assist in the calculation of
19018 ** (a.k.a. GMT) for the time value p where p is in UTC. If no error occurs,
19022 ** is undefined in this case.
19098 ** Return 0 on success and 1 if there is any kind of error. If the error
19099 ** is in a system call (i.e. localtime()), then an error message is written
19100 ** to context pCtx. If the error is an unrecognized modifier, no error is
19118 ** Assuming the current time value is UTC (a.k.a. GMT), shift it to
19166 ** date is already on the appropriate weekday, this is a no-op.
19305 ** Process time function arguments. argv[0] is a date-time stamp.
19310 ** If there are zero parameters (if even argv[0] is undefined)
19621 ** If the library is compiled to omit the full-scale date and time
19624 ** are included instead. This is to support column declarations that
19628 ** and strftime(). The format string to pass to strftime() is supplied
19695 ** a legal notice, here is a blessing:
19703 ** This file contains OS interface code that is common to all
19711 ** is used for testing the I/O recovery logic.
19768 ** of the sqlite3_file object. This is mostly just syntactic sugar. All
19814 ** is only a hint and can be safely ignored. The sqlite3OsFileControlHint()
19821 ** is using a regular VFS, it is called after the corresponding
19824 ** but the transaction is committed anyway.
19876 /* No-op stubs to use when memory-mapped I/O is disabled */
19899 /* 0x87f7f is a mask of SQLITE_OPEN_ flags that are valid to be passed
19957 ** method to get the current date and time if that method is available
19958 ** (if iVersion is 2 or greater and the function pointer is not NULL) and
19959 ** will fall back to xCurrentTime() if xCurrentTimeInt64() is
20001 ** This function is a wrapper around the OS specific implementation of
20002 ** sqlite3_os_init(). The purpose of the wrapper is to provide the
20020 ** Locate a VFS by name. If no name is given, simply return the
20065 ** Register a VFS with the system. It is harmless to register the same
20066 ** VFS multiple times. The new VFS becomes the default if makeDflt is
20095 ** Unregister a VFS so that it is no longer accessible.
20113 ** a legal notice, here is a blessing:
20128 ** SQLITE_NOMEM) to the user. However, sometimes a fault is not necessarily
20130 ** is completely recoverable simply by not carrying out the resize. The
20132 ** during a hash table resize is a benign fault.
20149 ** structure. If writable static data is unsupported on the target,
20151 ** case where writable static data is supported, wsdHooks can refer directly
20178 ** This (sqlite3EndBenignMalloc()) is called by SQLite code to indicate that
20203 ** a legal notice, here is a blessing:
20212 ** SQLITE_ZERO_MALLOC is defined. The allocation drivers implemented
20220 ** This version of the memory allocator is the default. It is
20221 ** used when no other memory allocator is specified using compile-time
20238 ** This routine is the only routine in this file with external linkage.
20265 ** a legal notice, here is a blessing:
20279 ** this file is only used if SQLITE_SYSTEM_MALLOC is defined. The
20280 ** SQLITE_SYSTEM_MALLOC macro is defined automatically if neither the
20282 ** default configuration is to use memory allocation routines in this
20307 ** This version of the memory allocator is the default. It is
20308 ** used when no other memory allocator is specified using compile-time
20316 ** SQLITE_WITHOUT_ZONEMALLOC symbol is defined.
20332 ** Also used by Apple systems if SQLITE_WITHOUT_ZONEMALLOC is defined.
20339 ** The malloc.h header file is needed for malloc_usable_size() function
20346 ** The MSVCRT has malloc_usable_size(), but it is called _msize(). The
20347 ** use of _msize() is automatic, but can be disabled by compiling with
20358 ** SQLITE_MALLOCSIZE to the appropriate function name, which is _msize()
20537 ** This routine is the only routine in this file with external linkage.
20564 ** a legal notice, here is a blessing:
20584 ** This version of the memory allocator is used only if the
20585 ** SQLITE_MEMDEBUG macro is defined
20590 ** The backtrace functionality is only available with GLIBC
20611 ** backtrace pointers. There is also a guard word at the end of the
20637 ** into a single structure named "mem". This is to keep the
20639 ** when this module is combined with other in the amalgamation.
20674 ** nAlloc[i] is the number of allocation attempts of i*8
20675 ** bytes. i==NCSIZE is the number of allocation attempts for
20751 /* If memory status is enabled, then the malloc.c wrapper will already
20774 ** Fill a buffer with pseudo-random bytes. This is used to preset
20898 ** higher level code is using pointer to the old allocation, it is
20953 ** This routine is designed for use within an assert() statement, to
20963 assert( pHdr->iForeGuard==FOREGUARD ); /* Allocation is valid */
20975 ** This routine is designed for use within an assert() statement, to
20985 assert( pHdr->iForeGuard==FOREGUARD ); /* Allocation is valid */
20995 ** A value of zero turns off backtracing. The number is always rounded
21095 ** a legal notice, here is a blessing:
21110 ** the amount of memory available to SQLite is fixed and cannot
21113 ** This version of the memory allocation subsystem is included
21114 ** in the build only if SQLITE_ENABLE_MEMSYS3 is defined.
21119 ** This version of the memory allocator is only built into the library
21120 ** SQLITE_ENABLE_MEMSYS3 is defined. Defining this symbol does not
21122 ** it is available. The mempool allocator is activated by calling
21140 ** more blocks where each block is 8 bytes. The first 8 bytes are
21141 ** a header that is not returned to the user.
21143 ** A chunk is two or more blocks that is either checked out or
21144 ** free. The first block has format u.hdr. u.hdr.size4x is 4 times the
21145 ** size of the allocation in blocks if the allocation is free.
21146 ** The u.hdr.size4x&1 bit is true if the chunk is checked out and
21147 ** false if the chunk is on the freelist. The u.hdr.size4x&2 bit
21148 ** is true if the previous chunk is checked out and false if the
21149 ** previous chunk is free. The u.hdr.prevSize field is the size of
21150 ** the previous chunk in blocks if the previous chunk is on the
21151 ** freelist. If the previous chunk is checked out, then
21156 ** this is done, the chunk index refers to the second block of
21158 ** A chunk index of 0 means "no such chunk" and is the equivalent
21161 ** The second block of free chunks is of the form u.list. The
21166 ** The second block of a chunk is user data if the chunk is checked
21167 ** out. If a chunk is checked out, the user data may extend into
21186 ** into a single structure named "mem3". This is to keep the
21188 ** when this module is combined with other in the amalgamation.
21192 ** Memory available for allocation. nPool is the size of the array
21214 ** iMaster is the index of the master chunk. Most new allocations
21215 ** occur off of this chunk. szMaster is the size (in Mem3Blocks)
21216 ** of the current master. iMaster is 0 if there is not master chunk.
21217 ** The master chunk is not in either the aiHash[] or aiSmall[].
21234 ** Unlink the chunk at mem3.aPool[i] from list it is currently
21235 ** on. *pRoot is the list that i is a member of.
21255 ** whatever list is currently a member of.
21274 ** Link the chunk at mem3.aPool[i] so that is on the list rooted
21308 ** If the STATIC_MEM mutex is not already held, obtain it now. The mutex
21310 ** sqlite3GlobalConfig.bMemStat is true.
21338 ** Chunk i is a free chunk that has been unlinked. Adjust its
21358 ** is not large enough, return 0.
21390 ** *pRoot is the head of a list of free chunks of the same size
21391 ** or same size hash. In other words, *pRoot is an entry in either
21397 ** If it sees a chunk that is larger than mem3.iMaster, it replaces
21400 ** linked into the hash tables. That is not the normal state of
21460 ** chunk table or in the large chunk hash table. This is
21709 fprintf(out, "%p tail checkout bit is incorrect\n", &mem3.aPool[i]);
21753 ** This routine is the only routine in this file with external
21760 ** This routine is only called by sqlite3_config(), and therefore
21761 ** is not required to be threadsafe (it is not).
21785 ** a legal notice, here is a blessing:
21800 ** the amount of memory available to SQLite is fixed and cannot
21803 ** This version of the memory allocation subsystem is included
21804 ** in the build only if SQLITE_ENABLE_MEMSYS5 is defined.
21813 ** 3. New memory is allocated from the first available free block.
21815 ** This algorithm is described in: J. M. Robson. "Bounds for Some Functions
21834 ** This version of the memory allocator is used only when
21835 ** SQLITE_ENABLE_MEMSYS5 is defined.
21840 ** A minimum allocation is an instance of the following structure.
21842 ** size of the array is a power of 2.
21844 ** The size of this object must be a power of two. That fact is
21854 ** Maximum size of any allocation is ((1<<LOGMAX)*mem5.szAtom). Since
21855 ** mem5.szAtom is always at least 8 and 32-bit integers are used,
21856 ** it is not actually possible to reach this limit.
21868 ** into a single structure named "mem5". This is to keep the
21870 ** when this module is combined with other in the amalgamation.
21900 ** Lists of free blocks. aiFreelist[0] is a list of free blocks of
21920 ** Assuming mem5.zPool is divided up into an array of Mem5Link
21926 ** Unlink the chunk at mem5.aPool[i] from list it is currently
21948 ** Link the chunk at mem5.aPool[i] so that is on the iLogsize
21994 ** The caller guarantees that nByte is positive.
21997 ** routine so there is never any chance that two or more
22058 /* Make sure the allocated memory does not assume that it is set to zero
22125 /* Overwrite freed memory with the 0x55 bit pattern to verify that it is
22165 ** nBytes is always a value obtained from a prior call to
22166 ** memsys5Round(). Hence nBytes is always a non-negative power
22194 ** the allocation is too large to be handled by this allocation system,
22198 ** 32-bit signed integer. Hence the largest allocation is 0x40000000
22227 ** This routine is not threadsafe. The caller must be holding a mutex
22243 ** this is case.
22277 /* If a mutex is required for normal operation, allocate one */
22338 ** This routine is the only routine in this file with external
22364 ** a legal notice, here is a blessing:
22373 ** This file contains code that is common across all mutex implementations.
22379 ** For debugging purposes, record when the mutex subsystem is initialized
22380 ** and uninitialized so that we can assert() if there is an attempt to
22381 ** allocate a mutex while the system is uninitialized.
22502 ** entered by the same thread. The behavior is undefined if the mutex
22503 ** is not currently entered. If a NULL pointer is passed as an argument
22504 ** this function is a no-op.
22536 ** a legal notice, here is a blessing:
22546 ** exclusion and is thus suitable for use only in applications
22555 ** If compiled with SQLITE_DEBUG, then additional logic is inserted
22603 ** In this implementation, error checking is provided for testing
22685 ** to enter a mutex. If another thread is already within the mutex,
22692 ** more than once, the behavior is undefined.
22709 ** is undefined if the mutex is not currently entered or
22710 ** is not currently allocated. SQLite will never do either.
22739 ** is used regardless of the run-time threadsafety setting.
22754 ** a legal notice, here is a blessing:
22766 ** The code in this file is only used if we are compiling threadsafe
22788 ** Each recursive mutex is an instance of the following structure.
22797 volatile pthread_t owner; /* Thread that is within this mutex */
22813 ** deliver incorrect results. In particular, if pthread_equal() is
22815 ** incorrect results. On most platforms, pthread_equal() is a
22816 ** comparison of two integers and is therefore atomic. But we are
22817 ** told that HPUX is not such a platform. If so, then these routines
22820 ** On those platforms where pthread_equal() is not atomic, SQLite
22837 ** where SQLite is compiled without mutexes.
22858 ** to sqlite3_mutex_alloc() is one of these integer constants:
22878 ** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
22879 ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
22884 ** implementation is available on the host platform, the mutex subsystem
22896 ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
22898 ** mutex types, the same mutex is returned on every call that has
22926 /* Use a recursive mutex if it is available */
22963 ** allocated mutex. SQLite is careful to deallocate every
22984 ** to enter a mutex. If another thread is already within the mutex,
22991 ** more than once, the behavior is undefined.
22999 ** is atomic - that it cannot be deceived into thinking self
23001 ** that are not equal to self while the comparison is taking place.
23042 ** is atomic - that it cannot be deceived into thinking self
23044 ** that are not equal to self while the comparison is taking place.
23089 ** is undefined if the mutex is not currently entered or
23090 ** is not currently allocated. SQLite will never do either.
23144 ** a legal notice, here is a blessing:
23157 ** Include code that is common to all os_*.c files
23165 ** a legal notice, here is a blessing:
23173 ** This file contains macros and a little bit of code that is common to
23174 ** all of the platform-specific files (os_*.c) and is #included into those
23177 ** This file should be #included by the os_*.c files only. It is not a
23189 # error "The MEMORY_DEBUG macro is obsolete. Use SQLITE_DEBUG instead."
23208 ** a legal notice, here is a blessing:
23307 ** is used for testing the I/O recovery logic.
23368 ** a legal notice, here is a blessing:
23376 ** This file contains code that is specific to Windows.
23405 ** everything is Windows NT unless the programmer explicitly says otherwise
23458 ** The code in this file is only used if we are compiling multithreaded
23464 ** Each recursive mutex is an instance of the following structure.
23511 ** and also for the xShmBarrier method of the VFS in cases when SQLite is
23550 ** "interlocked" magic used here is probably not strictly necessary.
23570 /* Another thread is (in the process of) initializing the static
23599 ** to sqlite3_mutex_alloc() is one of these integer constants:
23619 ** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
23620 ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
23625 ** implementation is available on the host platform, the mutex subsystem
23637 ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
23639 ** mutex types, the same mutex is returned on every call that has
23687 ** allocated mutex. SQLite is careful to deallocate every
23705 ** to enter a mutex. If another thread is already within the mutex,
23712 ** more than once, the behavior is undefined.
23745 ** The sqlite3_mutex_try() routine is very rarely used, and when it
23746 ** is used it is merely an optimization. So it is OK for it to always
23749 ** The TryEnterCriticalSection() interface is only available on WinNT.
23784 ** is undefined if the mutex is not currently entered or
23785 ** is not currently allocated. SQLite will never do either.
23837 ** a legal notice, here is a blessing:
23852 ** held by SQLite. An example of non-essential memory is memory used to
23860 ** is a no-op returning zero if SQLite is not compiled with
23893 ** True if heap is nearly "full" where "full" is defined by the
23911 ** that was invoked when memory usage grew too large. Now it is a
24000 ** Return true if the heap is currently under memory pressure - in other
24001 ** words if the amount of heap used is close to the limit set by
24050 ** lock is already held.
24084 ** Allocate memory. This routine is like sqlite3_malloc() except that it
24090 /* A memory allocation of a number of bytes which is near the maximum
24094 ** this amount. The only way to reach the limit is with sqlite3_malloc() */
24108 ** This version of the memory allocation is for use by the application.
24109 ** First make sure the memory subsystem is initialized, then do the
24129 ** is outstanding clearing it when the allocation is freed.
24137 ** Allocate memory that is to be used and released right away.
24138 ** This routine is similar to alloca() in that it is not intended
24140 ** routine is intended to get memory to old large transient data
24186 ** is outstanding at one time. (This is only checked in the
24225 ** TRUE if p is a lookaside memory allocation from db
24340 /* The 0x7ffff00 limit term is explained in comments on sqlite3Malloc() */
24345 ** argument to xRealloc is always a value returned by a prior call to
24377 ** subsystem is initialized prior to invoking sqliteRealloc.
24436 ** If db!=0 and db->mallocFailed is true (indicating a prior malloc
24439 ** failing, it fails consistently until mallocFailed is reset.
24440 ** This is an important assumption. There are many places in the
24447 ** In other words, if a subsequent malloc (ex: "b") worked, it is assumed
24450 ** The sqlite3MallocRawNN() variant guarantees that the "db" parameter is
24551 ** is because when memory debugging is turned on, these two functions are
24612 ** The memory allocator is not restarted if there are running
24638 ** The returned value is normally a copy of the second argument to this
24640 ** invocation SQLITE_NOMEM is returned instead.
24643 ** returned by sqlite3_errcode()) is set to SQLITE_NOMEM.
24648 ** is unsafe, as is the call to sqlite3Error().
24661 ** The "printf" code that follows dates from the 1980's. It is in
24700 ** An "etByte" is an 8-bit unsigned value.
24705 ** Each builtin conversion character (ex: the 'd' in "%d") is described
24720 #define FLAG_SIGNED 1 /* True if the value to convert is signed */
24726 ** The following table is searched linearly, so it is good to put the
24763 ** If SQLITE_OMIT_FLOATING_POINT is defined, then none of the floating point
24768 ** "*val" is a double such that 0.1 <= *val < 10.0
24776 ** The counter *cnt is incremented each time. After counter exceeds
24777 ** 16 (the number of significant digits in a 64-bit float) '0' is
24842 etByte flag_leftjustify; /* True if "-" flag is present */
24843 etByte flag_plussign; /* True if "+" flag is present */
24844 etByte flag_blanksign; /* True if " " flag is present */
24845 etByte flag_alternateform; /* True if "#" flag is present */
24846 etByte flag_altform2; /* True if "!" flag is present */
24848 etByte flag_long; /* True if "l" flag is present */
24849 etByte flag_longlong; /* True if the "ll" flag is present */
25002 ** flag_alternateform TRUE if a '#' is present.
25003 ** flag_altform2 TRUE if a '!' is present.
25004 ** flag_plussign TRUE if a '+' is present.
25005 ** flag_leftjustify TRUE if a '-' is present or if the
25012 ** flag_blanksign TRUE if a ' ' is present.
25013 ** width The specified field width. This is
25014 ** always non-negative. Zero is the default.
25016 ** is -1.
25158 ** If the field type is etGENERIC, then convert to either etEXP
25247 /* The converted number is in buf[] and zero terminated. Output it.
25248 ** Note that the number is in the usual order, not reversed as with
25253 /* Special case: Add leading zeros if the flag_zeropad flag is
25391 ** The text of the conversion is pointed to by "bufpt" and is
25392 ** "length" characters long. The field width is "width". Do
25408 ** Enlarge the memory allocation on a StrAccum object so that it is
25411 ** Return the number of bytes of text that StrAccum is able to accept
25476 ** The StrAccum "p" is not large enough to accept N new bytes of z[].
25479 ** This is a helper routine to sqlite3StrAccumAppend() that does special-case
25519 ** Finish off a string by making sure it is zero-terminated.
25557 ** memory is used if not NULL. db->mallocFailed is set appropriately
25560 ** is malloced.
25651 ** current locale settings. This is important for SQLite because we
25656 ** from the snprintf() standard. Unfortunately, it is too late to change
25660 ** sqlite3_vsnprintf() is the varargs version.
25686 ** This is the routine that actually formats the sqlite3_log() message.
25688 ** stack space on small-stack systems when logging is disabled.
25692 ** mutex is held.
25697 ** memory mutex is held do not use these mechanisms.
25710 ** Format and write a message to the log if logging is enabled.
25759 ** a legal notice, here is a blessing:
25771 ** The interfaces in this file is only available when compiling
25779 ** is not the last item in the tree.
26153 ** This is equivalent to
26157 ** X is stored in pExpr->pLeft.
26158 ** Y is stored in pExpr->pList->a[0].pExpr.
26159 ** Z is stored in pExpr->pList->a[1].pExpr.
26172 /* If the opcode is TK_TRIGGER, then the expression is a reference
26174 ** trigger programs. In this case Expr.iTable is set to 1 for the
26176 ** is set to the column of the pseudo-table to read, or to -1 to
26261 ** a legal notice, here is a blessing:
26278 ** This structure is the current state of the generator.
26294 ** state vector. If writable static data is unsupported on the target,
26296 ** case where writable static data is supported, wsdPrng can refer directly
26326 ** the first time this routine is called. The seed value does
26331 ** encryption. The RC4 algorithm is being used as a PRNG (pseudo-random
26398 ** a legal notice, here is a blessing:
26410 ** runs independently of its creator until it is joined using
26414 ** "thread" is done by the main thread at either the sqlite3ThreadCreate()
26415 ** or sqlite3ThreadJoin() call. This is, in fact, what happens in
26454 /* This routine is never used in single-threaded mode */
26463 /* If the SQLITE_TESTCTRL_FAULT_INSTALL callback is registered to a
26551 /* If the SQLITE_TESTCTRL_FAULT_INSTALL callback is registered to a
26607 ** work of the thread in the main thread, when either the thread is created
26608 ** or when it is joined
26675 ** a legal notice, here is a blessing:
26712 ** The following constant value is used by the SQLITE_BIGENDIAN and
26719 ** This lookup table is used to help decode the first byte of
26802 ** is a 0x00.
26810 ** attempts to encode a value between 0x00 and 0x7f is rendered as 0xfffd.
26814 ** 0xd800 and 0xe000 then it is rendered as 0xfffd.
26842 ** For this routine, we assume the UTF8 string is always zero-terminated.
26861 ** If the TRANSLATE_TRACE macro is defined, the value of each Mem is
26869 ** desiredEnc. It is an error if the string is already of the desired
26894 /* If the translation is between UTF-16 little and big endian, then
26895 ** all that is required is to swap the byte order. This case is handled
26922 ** A single byte is required for the output string
26928 /* When converting from UTF-8 to UTF-16 the maximum growth is caused
26929 ** when a 1-byte UTF-8 character is translated into a 2-byte UTF-16
26939 ** Variable zOut is set to point at the output buffer, space obtained
27008 ** UTF-16 string stored in *pMem. If one is present, it is removed and
27047 ** pZ is a UTF-8 encoded unicode string. If nByte is less than zero,
27049 ** the first 0x00 byte. If nByte is not less than zero, return the
27070 /* This test function is not currently used by the automated test-suite.
27071 ** Hence it is only available in debug builds.
27077 ** This has the effect of making sure that the string is well-formed
27080 ** The translation is done in-place and aborted if the output
27102 ** Memory to hold the UTF-8 string is obtained from sqlite3_malloc and must
27105 ** NULL is returned if there is an allocation error.
27124 ** zIn is a UTF-16 encoded unicode string at least nChar characters long.
27149 ** This routine is called from the TCL test function "translate_selftest".
27208 ** a legal notice, here is a blessing:
27239 ** in places where it is difficult or expensive to do so purely by means
27242 ** The intent of the integer argument is to let the fault simulator know
27246 ** SQLITE_OK if no test callback is installed.
27257 ** Return true if the floating point value is Not a Number (NaN).
27269 ** this implementation is provided as an alternative.
27285 ** involving NaN. For example, x != x evaluates to true if x is NaN
27303 ** Compute a string length that is limited to what can be stored in
27319 ** The column type is an extra string stored after the zero-terminator on
27320 ** the column name if and only if the COLFLAG_HASTYPE flag is set.
27349 ** Load the sqlite3.iSysErrno field if that is an appropriate thing
27362 ** handle "db". The error code is set to "err_code".
27364 ** If it is not NULL, string zFormat specifies the format of the
27409 ** last thing the sqlite3_prepare() function does is copy the error
27433 ** the quote characters. The conversion is done in-place. If the
27435 ** is a no-op.
27438 ** is added to the dequoted string.
27440 ** The return value is -1 if no dequoting occurs or the length of the
27444 ** 2002-Feb-14: This routine is extended to remove MS-Access style
27484 ** there is no consistency, we will define our own.
27527 ** The string z[] is an text representation of a real number.
27530 ** The string z[] is length bytes in length (bytes, not characters) and
27531 ** uses the encoding enc. The string is not necessarily zero-terminated.
27533 ** Return TRUE if the result is a valid real number (or integer) and FALSE
27534 ** if the string is empty or contains extraneous text. Valid numbers
27541 ** Leading and trailing whitespace is ignored for the purpose of determining
27544 ** If some prefix of the input string is a valid number, this routine
27558 int eValid = 1; /* True exponent is either not used or is well-formed */
27601 /* if decimal point is present */
27616 /* if exponent is present */
27621 /* This branch is needed to avoid a (harmless) buffer overread. The
27623 ** is obtained even if the branch is omitted */
27655 /* In the IEEE 754 standard, zero is signed. */
27701 /* 1.0e+22 is the largest power of 10 than can be
27727 ** if zNum is less than, equal to, or greater than the string.
27730 ** Unlike memcmp() this routine is guaranteed to return the difference
27731 ** in the values of the last digit if the only difference is in the
27759 ** If the zNum value is representable as a 64-bit twos-complement
27762 ** If zNum is exactly 9223372036854775808, return 2. This special
27763 ** case is broken out because while 9223372036854775808 cannot be a
27766 ** If zNum is too big for a 64-bit integer and is not
27770 ** length is the number of bytes in the string (bytes, not characters).
27771 ** The string is not necessarily zero-terminated. The encoding is
27823 /* zNum is empty or contains non-numeric text or is longer
27824 ** than 19 digits (thus guaranteeing that it is too large) */
27831 /* zNum is a 19-digit numbers. Compare it against 9223372036854775808. */
27834 /* zNum is less than 9223372036854775808 so it fits */
27838 /* zNum is greater than 9223372036854775808 so it overflows */
27841 /* zNum is exactly 9223372036854775808. Fits if negative. The
27857 ** 1 Integer too large for a 64-bit signed integer or is malformed
27887 ** This is different from sqlite3Atoi64() which requires the
27924 /* The longest decimal representation of a 32 bit integer is 10 digits:
27946 ** string is not an integer, just return 0.
27955 ** The variable-length integer encoding is as follows:
27976 ** of bytes written is returned.
27981 ** 8 bits and is the last byte.
28035 ** Return the number of bytes read. The value is stored in *v.
28199 ** Return the number of bytes read. The value is stored in *v.
28201 ** If the varint stored in p[0] is larger than can fit in a 32-bit unsigned
28204 ** A MACRO version, getVarint32, is provided which inlines the
28252 /* A 32-bit varint is used to store size information in btrees.
28254 ** A 3-byte varint is sufficient, for example, to record the size
28279 ** unrolling for the 3- and 4-byte varint cases. This code is
28280 ** slightly faster, but it is also larger and much harder to test.
28384 ** This routine only works if h really is a valid hexadecimal
28422 ** Log an error that is an API call on a connection pointer that should
28423 ** not have been used. The "type" of connection pointer is given as the
28424 ** argument. The zType is a word like "NULL" or "closed" or "invalid".
28434 ** Check to make sure we have a valid db pointer. This test is not
28438 ** 1 it means that the db pointer is valid and 0 if it should not be
28444 ** open properly and is not fit for general use but which can be
28556 ** If SQLITE_ENABLE_8_3_NAMES is set at compile-time and if the database
28557 ** filename in zBaseFilename is a URI with the "8_3_names=1" parameter and
28558 ** if filename in z[] has a suffix (a.k.a. "extension") that is longer than
28562 ** If SQLITE_ENABLE_8_3_NAMES is set to 2 at compile-time, then always
28586 ** Find (an approximate) sum of two LogEst values. This computation is
28587 ** not a simple "+" operator because LogEst is stored as a logarithmic
28654 ** Note that this routine is only used when one or more of various
28655 ** non-standard compile-time options is enabled.
28667 /* If only SQLITE_ENABLE_STAT3_OR_STAT4 is on, then the largest input
28668 ** possible to this routine is 310, resulting in a maximum x of 31 */
28681 ** a legal notice, here is a blessing:
28688 ** This is the implementation of generic hash-tables
28697 ** "pNew" is a pointer to the hash table that is to be initialized.
28746 struct _ht *pEntry, /* The entry into which pNew is inserted */
28775 ** if the new size is the same as the prior size.
28789 /* The inability to allocates space for a larger hash table is
28790 ** a performance hit but it is not a fatal error. So mark the
28815 ** hash table that matches the given key. The hash for this key is
28884 ** that matches pKey. Return the data for this element if it is
28885 ** found, or NULL if there is no match.
28897 /* Insert an element into the hash table pH. The key is pKey
28898 ** and the data is "data".
28901 ** element is created and NULL is returned.
28904 ** new data replaces the old data and the old data is returned.
28905 ** The key is not copied in this instance. If a malloc fails, then
28906 ** the new data is returned and the hash table is unchanged.
28908 ** If the "data" parameter to this function is NULL, then the
28909 ** element corresponding to "key" is removed from the hash table.
29132 ** a legal notice, here is a blessing:
29144 ** The differences are in the way that file locking is done. The default
29149 ** This source file is organized into divisions where the logic for various
29150 ** subfunctions is contained within the appropriate division. PLEASE
29154 ** The layout of divisions is as follows:
29174 #if SQLITE_OS_UNIX /* This file is used on unix only */
29189 ** is defined to 1. The SQLITE_ENABLE_LOCKING_STYLE also enables automatic
29191 ** where the database is located.
29240 # warning "gethostuuid() is disabled."
29302 ** Only set the lastErrno if the error code is a real error and not
29314 ** Sometimes, after a file handle is closed by SQLite, the file descriptor
29326 ** The unixFile structure is subclass of sqlite3_file specific to the unix
29367 ** occur if a file is updated without also updating the transaction
29368 ** counter. This test is made to avoid new problems similar to the
29379 ** it is larger than the struct CrashFile defined in test6.c.
29386 ** method was called. If xOpen() is called from a different process id,
29395 #define UNIXFILE_RDONLY 0x02 /* Connection is read only */
29408 ** Include code that is common to all os_*.c files
29416 ** a legal notice, here is a blessing:
29424 ** This file contains macros and a little bit of code that is common to
29425 ** all of the platform-specific files (os_*.c) and is #included into those
29428 ** This file should be #included by the os_*.c files only. It is not a
29440 # error "The MEMORY_DEBUG macro is obsolete. Use SQLITE_DEBUG instead."
29459 ** a legal notice, here is a blessing:
29558 ** is used for testing the I/O recovery logic.
29650 ** is the 32-bit version, even if _FILE_OFFSET_BITS=64 is defined.
29659 ** The difference is important when using a pointer to the function.
29661 ** The safest way to deal with the problem is to always use this wrapper
29702 ** DJGPP. But it is DOS - what did you expect?
29845 ** This is the xSetSystemCall() method of sqlite3_vfs for all of the
29847 ** system call pointer, or SQLITE_NOTFOUND if there is no configurable
29860 /* If no zName is given, restore all system calls to their default
29870 /* If zName is specified, operate on only the one system call
29889 ** Return the value of a system call. Return NULL if zName is not a
29890 ** recognized system call name. NULL is also returned if the system call
29891 ** is currently undefined.
29909 ** is the last system call or if zName is not the name of a valid
29940 ** If the file creation mode "m" is 0 then set it to the default for
29941 ** SQLite. The default is SQLITE_DEFAULT_FILE_PERMISSIONS (normally
29942 ** 0644) as modified by the system umask. If m is not 0, then
29948 ** In that way, if a database file is -rw-rw-rw or -rw-rw-r-, and a
29950 ** process that is able to write to the database will also be able to
29992 ** global mutex is used to protect the unixInodeInfo and
29996 ** Function unixMutexHeld() is used to assert() that the global mutex
29997 ** is held when required. This function is only used as part of assert()
30039 ** This routine is used for troubleshooting locks on multithreaded
30041 ** command-line option on the compiler. This code is normally
30106 ** _FILE_OFFSET_BITS=64 is defined. This means it is unsafe to attempt to
30119 ** useful to the clients of the sqlite3 functions. Specifically, it is
30161 ** a copy of the canonical filename. There is also a reference count.
30162 ** The structure is reclaimed when the number of pointers to it drops to
30166 ** a performance-critical path, so it is sufficient to put these
30189 ** * convert /A/../ where A is any simple name into just /
30193 ** The original filename is in z[0..n-1]. Return the number of
30221 ** a pointer to the vxworksFileId object. This pointer is the unique
30224 ** The nRef field of the vxworksFileId object is incremented before
30225 ** the object is returned. A new vxworksFileId object is created
30304 ** one is a hard or symbolic link to the other) then if you set
30318 ** on its own. Whenever a new database is opened, we have to find the
30319 ** specific inode of the database file (the inode is determined by the
30330 ** The sqlite3_file structure for POSIX is no longer just an integer file
30331 ** descriptor. It is now a structure that holds the integer file
30333 ** locks on the corresponding inode. There is one locking structure
30334 ** per inode, so if the same inode is opened twice, both unixFile structures
30338 ** file is unlocked. cnt==-1 means the file has an exclusive lock.
30342 ** structure. The fcntl() system call is only invoked to set a
30352 ** When an attempt is made to close an unixFile, if there are
30354 ** to close() the file descriptor is deferred until all of the locks clear.
30356 ** be closed and that list is walked (and cleared) when the last lock
30361 ** Many older versions of linux use the LinuxThreads library which is
30364 ** Only thread A can modify the lock. Locking behavior is correct
30367 ** in thread B. But there is no way to know at compile-time which
30368 ** threading library is being used. So there is no way to know at
30375 ** LinuxThreads provided that (1) there is no more than one connection
30394 ** An instance of the following structure is allocated for each open
30395 ** inode. Or, on LinuxThreads, there is one of these structures for
30406 unsigned char bProcessLock; /* An exclusive process lock is held */
30429 ** This function - unixLogErrorAtLine(), is only ever called via the macro
30432 ** It is invoked after an error occurs in an OS function and errno has been
30453 /* If this is not a threadsafe build (SQLITE_THREADSAFE==0), then use
30462 /* If STRERROR_R_CHAR_P (set by autoconf scripts) or __USE_GNU is defined,
30469 ** If the code incorrectly assumes that it is the POSIX version that is
30471 ** huge problem. Incorrectly concluding that the GNU version is available
30480 /* This is a threadsafe build, but strerror_r() is not available. */
30499 ** We assume that close() almost always works, since it is only in a
30504 ** Note that it is not safe to retry close() after EINTR since the
30543 ** when this function is called.
30575 ** when this function is called.
30605 /* On OS X on an msdos filesystem, the inode number is reported
30609 ** prior to accessing the inode number. The one byte written is
30612 ** is a race condition such that another thread has already populated
30613 ** the first page of the database, no damage is done.
30674 ** Check a unixFile that is a database. Verify the following:
30676 ** (1) There is exactly one hard link on the file
30677 ** (2) The file is not a symbolic link
30680 ** Issue sqlite3_log(SQLITE_WARNING,...) messages if anything is not right.
30710 ** This routine checks if there is a RESERVED lock held on the specified
30711 ** file by this or any other process. If such a lock is held, set *pResOut
30712 ** to a non-zero value otherwise *pResOut is set to zero. The return value
30713 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
30724 unixEnterMutex(); /* Because pFile->pInode is shared across threads */
30757 ** Attempt to set a system-lock on the file pFile. The lock is
30761 ** ever obtained is an exclusive lock, and it is obtained exactly once
30762 ** the first time any lock is attempted. All subsequent system locking
30765 ** within this process, but all of that is handled in memory and the
30768 ** This function is a pass-through to fcntl(F_SETLK) if pFile is using
30769 ** any VFS other than "unix-excl" or if pFile is opened on "unix-excl"
30770 ** and is read-only.
30772 ** Zero is returned if the call completes successfully, or -1 if a call
30773 ** to fcntl() fails. In this case, errno is set appropriately (by fcntl()).
30831 ** accessing the same database file, in case that is ever required.
30837 ** To obtain a SHARED lock, a read-lock is obtained on the 'pending
30838 ** byte'. If this is successful, 'shared byte range' is read-locked
30842 ** single randomly selected by from the 'shared byte range' is locked.
30843 ** Windows95 is now pretty much extinct, but this work-around for the
30848 ** A RESERVED lock is implemented by grabbing a write-lock on the
30852 ** SHARED lock. A PENDING lock is implemented by obtaining a write-lock
30856 ** This property is used by the algorithm for rolling back a journal file
30859 ** An EXCLUSIVE lock, obtained after a PENDING lock is held, is
30877 /* If there is already a lock of this type or more restrictive on the
30887 /* Make sure the locking sequence is correct.
30890 ** (3) A shared lock is always held when a reserve lock is requested.
30896 /* This mutex is needed because pFile->pInode is shared across threads
30911 /* If a SHARED lock is requested, and some thread using this PID already
30927 /* A PENDING lock is needed before acquiring a SHARED lock and before
30987 ** same process is still holding a shared lock. */
30990 /* The request was for a RESERVED or EXCLUSIVE lock. It is
30991 ** assumed that there is a SHARED or greater lock on the file
31065 ** If the locking level of the file descriptor is already at or below
31066 ** the requested locking level, this routine is a no-op.
31068 ** If handleNFSUnlock is true, then on downgrading an EXCLUSIVE_LOCK to SHARED
31069 ** the byte range is divided into 2 parts and the first part is unlocked then
31070 ** set to a read lock, then the other part is simply unlocked. This works
31072 ** remove the write lock on a region when a read lock is set.
31099 ** file changed. If the transaction counter is not updated,
31110 ** write lock until the rest is covered by a read lock:
31167 ** process is holding an incompatible lock. If it does, this
31168 ** indicates that the other process is not following the locking
31231 ** If the locking level of the file descriptor is already at or below
31232 ** the requested locking level, this routine is a no-op.
31252 ** It is *not* necessary to hold the mutex when this routine is called,
31298 /* unixFile.pInode is always valid here. Otherwise, a different close
31306 ** when the last lock is cleared.
31322 ** Of the various locking implementations available, this is by far the
31323 ** simplest: locking is ignored. No attempt is made to lock the database
31326 ** This locking mode is appropriate for use on read-only databases
31330 ** database connections. But there is a serious risk of database
31331 ** corruption if this locking mode is used in situations where multiple
31367 ** (1) There is zero concurrency. A single reader blocks all other
31373 ** Nevertheless, a dotlock is an appropriate locking mode for use if no
31374 ** other locking strategy is available.
31389 ** This routine checks if there is a RESERVED lock held on the specified
31390 ** file by this or any other process. If such a lock is held, set *pResOut
31391 ** to a non-zero value otherwise *pResOut is set to zero. The return value
31392 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
31395 ** variation of CheckReservedLock(), *pResOut is set to true if any lock
31396 ** is held on the file and false if the file is unlocked.
31446 ** to do is adjust our internal record of the lock level.
31484 ** If the locking level of the file descriptor is already at or below
31485 ** the requested locking level, this routine is a no-op.
31547 ** flock() locking is like dot-file locking in that the various
31551 ** still works when you do this, but concurrency is reduced since
31554 ** Omit this section if SQLITE_ENABLE_LOCKING_STYLE is turned off
31573 ** This routine checks if there is a RESERVED lock held on the specified
31574 ** file by this or any other process. If such a lock is held, set *pResOut
31575 ** to a non-zero value otherwise *pResOut is set to zero. The return value
31576 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
31664 /* if we already have a lock, it is exclusive.
31699 ** If the locking level of the file descriptor is already at or below
31700 ** the requested locking level, this routine is a no-op.
31750 ** Named semaphore locking is only supported on VxWorks.
31752 ** Semaphore locking is like dot-lock and flock in that it really only
31760 ** This routine checks if there is a RESERVED lock held on the specified
31761 ** file by this or any other process. If such a lock is held, set *pResOut
31762 ** to a non-zero value otherwise *pResOut is set to zero. The return value
31763 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
31837 /* if we already have a lock, it is exclusive.
31862 ** If the locking level of the file descriptor is already at or below
31863 ** the requested locking level, this routine is a no-op.
31917 ** Named semaphore locking is only available on VxWorks.
31926 ** AFP is the Apple Filing Protocol. AFP is a network filesystem found
31956 ** This is a utility for setting or clearing a bit-range lock on an
32002 ** This routine checks if there is a RESERVED lock held on the specified
32003 ** file by this or any other process. If such a lock is held, set *pResOut
32004 ** to a non-zero value otherwise *pResOut is set to zero. The return value
32005 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
32021 unixEnterMutex(); /* Because pFile->pInode is shared across threads */
32088 /* If there is already a lock of this type or more restrictive on the
32098 /* Make sure the locking sequence is correct
32101 ** (3) A shared lock is always held when a reserve lock is requested.
32107 /* This mutex is needed because pFile->pInode is shared across threads
32122 /* If a SHARED lock is requested, and some thread using this PID already
32137 /* A PENDING lock is needed before acquiring a SHARED lock and before
32191 ** same process is still holding a shared lock. */
32194 /* The request was for a RESERVED or EXCLUSIVE lock. It is
32195 ** assumed that there is a SHARED or greater lock on the file
32221 /* Can't reestablish the shared lock. Sqlite can't deal, this is
32256 ** If the locking level of the file descriptor is already at or below
32257 ** the requested locking level, this routine is a no-op.
32291 ** file changed. If the transaction counter is not updated,
32372 ** the last lock is cleared.
32385 ** The code above is the AFP lock implementation. The code is specific
32387 ** is available. If you don't compile for a mac, then the "unix-afp"
32388 ** VFS is not available.
32401 ** If the locking level of the file descriptor is already at or below
32402 ** the requested locking level, this routine is a no-op.
32410 ** The code above is the NFS lock implementation. The code is specific
32412 ** is available.
32438 ** is set before returning.
32501 /* If this is a database file (not a journal, master-journal or temp
32592 ** is set before returning.
32614 /* If this is a database file (not a journal, master-journal or temp
32627 ** has changed. If the transaction counter is modified, record that
32685 ** Count the number of fullsyncs and normal syncs. This is used to test
32704 ** the F_FULLFSYNC macro is defined. F_FULLFSYNC is currently
32716 ** unix systems. The following procedure is an attempt to make
32719 ** The SQLITE_NO_SYNC macro disables all fsync()s. This is useful
32725 ** SQLite sets the dataOnly flag if the size of the file is unchanged.
32726 ** The idea behind dataOnly is that it should only write the file content
32727 ** to disk, not the inode. We only set dataOnly if the file size is
32728 ** unchanged since the file size is part of the inode. However,
32731 ** and fsync(), Ted tells us, is that fdatasync() will not flush the
32734 ** as far as SQLite is concerned, an fdatasync() is always adequate.
32735 ** So, we always use fdatasync() if it is available, regardless of
32742 ** the one below. It is replicated here solely to avoid cluttering
32757 ** FULLSYNC. This is used during testing to verify that this procedure
32765 /* If we compiled with the SQLITE_NO_SYNC flag, then syncing is a
32787 ** the fcntl call every time sync is called.
32813 ** If successful, *pFd is set to the opened file descriptor and
32814 ** SQLITE_OK is returned. If an error occurs, either SQLITE_NOMEM
32815 ** or SQLITE_CANTOPEN is returned and *pFd is set to an undefined
32818 ** The directory file descriptor is used for only one thing - to
32825 ** chromium sandbox. Opening a directory is a security risk (we are
32831 ** If SQLITE_OK is returned, the caller is responsible for closing
32861 ** file data is synced.
32884 ** line is to test that doing so does not cause any problems.
32898 ** is set. This is a one-time occurrence. Many systems (examples: AIX)
32986 ** layers, we need to report this file size as zero even though it is
33004 ** This function is called to handle the SQLITE_FCNTL_SIZE_HINT
33006 ** (rounded up to the next chunk-size). If the database is already
33007 ** nBytes or larger, this routine is a no-op.
33022 /* The code below is handling the return value of osFallocate()
33023 ** correctly. posix_fallocate() is defined to "returns zero on success,
33035 ** This is a similar technique to that used by glibc on systems
33073 ** If *pArg is initially negative then this is a query. Set *pArg to
33074 ** 1 or 0 depending on whether or not bit mask of pFile->ctrlFlags is set.
33076 ** If *pArg is 0 or 1, then clear or set the mask bit of pFile->ctrlFlags.
33160 ** a rollback and that the database is therefore unchanged and
33161 ** it hence it is OK for the transaction change counter to be
33181 ** the specified file. This is almost always 512 bytes, but may be
33197 ** The following version of unixSectorSize() is optimized for QNX.
33221 ** so it is ordered */
33231 ** so it is ordered */
33240 ** so it is ordered */
33248 ** so it is ordered */
33256 ** so it is ordered */
33279 ** This VFS is set up to return SQLITE_IOCAP_POWERSAFE_OVERWRITE by default.
33280 ** However, that choice is controversial since technically the underlying
33283 ** written might end up being altered.) However, non-PSOW behavior is very,
33285 ** of required I/O for journaling, since a lot of padding is eliminated.
33286 ** Hence, while POWERSAFE_OVERWRITE is on by default, there is a file-control
33329 ** of this unixShmNode object. In other words, each wal-index is opened
33332 ** Each unixShmNode object is connected to a single unixInodeInfo object.
33337 ** and the unixShmNode object is created only when needed.
33344 ** The following fields are read-only after the object is created:
33350 ** unixMutexHeld() is true when reading or writing any other field
33375 ** The following fields are initialized when this object is created and
33402 ** Locks block if the mask is exactly UNIX_SHM_C and are non-blocking
33415 /* Access to the unixShmNode object is serialized by the caller */
33480 ** Usually, this is 1. The exception seems to be systems that are configured
33495 ** This is not a VFS shared-memory method; it is a utility function called
33527 ** The file used to implement shared-memory is in the same directory
33530 ** is "/home/user1/config.db" then the file that is created and mmapped
33533 ** Another approach to is to use files in /dev/shm or /dev/tmp or an
33535 ** from the database file is used, then differing access permissions
33545 ** result. The SQLITE_SHM_DIRECTORY compile-time option is considered
33552 ** If the original database file (pDbFd) is using the "unix-excl" VFS
33553 ** that means that an exclusive lock is held on the database file and
33556 ** file is created. The shared memory will be simulated with heap memory.
33585 ** a new *-shm file is created, an attempt will be made to create it
33636 /* If this process is running as root, make sure that the SHM file
33637 ** is owned by the same user that owns the original database. Otherwise,
33642 /* Check to see if another process is holding the dead-man switch.
33669 ** new (struct unixShm) object to the pShmNode has been set. All that is
33670 ** left to do is to link the new object into the linked list starting
33689 ** This function is called to obtain a pointer to region iRegion of the
33691 ** are numbered starting from zero. Each shared-memory region is szRegion
33694 ** If an error occurs, an error code is returned and *pp is set to NULL.
33696 ** Otherwise, if the bExtend parameter is 0 and the requested shared-memory
33698 ** separate process), then *pp is set to NULL and SQLITE_OK returned. If
33699 ** bExtend is non-zero and the requested shared-memory region has not yet
33700 ** been allocated, it is allocated by this function.
33702 ** If the shared-memory region has already been allocated or is allocated by
33703 ** this call as described above, then it is mapped into this processes
33704 ** address space (if it is not already), *pp is set to point to the mapped
33746 /* The requested region is not mapped into this processes address space.
33747 ** Check to see if it has been allocated (i.e. if the wal-index file is
33756 /* The requested memory region does not exist. If bExtend is set to
33763 /* Alternatively, if bExtend is true, extend the file. Do this by
33840 ** Note that the relationship between SHAREd and EXCLUSIVE locks is a little
33968 ** storage if deleteFlag is true.
33970 ** If there is no shared memory associated with the connection then this
33971 ** routine is a harmless no-op.
34027 ** If it is currently memory mapped, unmap file pFd.
34041 ** descriptor pFd to nNew bytes. Any existing mapping is discarded.
34049 ** If unsuccessful, an error message is logged via sqlite3_log() and
34111 /* If pNew is still NULL, try to create an entirely new mapping. */
34132 ** is already mapped, the existing mapping is replaced by the new). Or, if
34134 ** outstanding xFetch() references to it, this function is a no-op.
34136 ** If parameter nByte is non-negative, then it is the requested size of
34137 ** the mapping to create. Otherwise, if nByte is less than zero, then the
34138 ** requested size is the size of the file on disk. The actual size of the
34139 ** created mapping is either the requested size or the value configured
34140 ** using SQLITE_FCNTL_MMAP_LIMIT, whichever is smaller.
34142 ** SQLITE_OK is returned if no error occurs (even if the mapping is not
34178 ** value of *pp is undefined in this case.
34205 ** If the third argument is non-NULL, then this function releases a
34210 ** Or, if the third argument is NULL, then this function is being called
34220 ** xFetch references. Or, if p!=0 (meaning it is an xFetch reference),
34251 ** of "finder" functions. A finder-function is used to locate the appropriate
34257 ** object. The only interesting finder-function is autolockIoFinder, which
34268 ** A pointer to the F pointer is used as the pAppData value for VFS
34329 3, /* shared memory is disabled */
34339 1, /* shared memory is disabled */
34351 1, /* shared memory is disabled */
34364 1, /* shared memory is disabled */
34377 1, /* shared memory is disabled */
34387 ** The proxy locking method is a "super-method" in the sense that it
34391 ** proxy locking is located much further down in the file. But we need
34403 1, /* shared memory is disabled */
34412 /* nfs lockd on OSX 10.3+ doesn't clear write locks when a read lock is set */
34417 1, /* shared memory is disabled */
34432 ** This is for MacOSX only.
34495 ** locking works. If it does, then that is what is used. If it does not
34510 /* Test if fcntl() is supported and use POSIX style locks.
34558 ** exception is when opening the proxy "conch" file in builds that
34601 ** proxyLock activation is possible (remote proxy is based on db name)
34602 ** zFilename remains valid until file is closed, to support */
34622 ** Scenario (b) may only occur if the process is holding no other
34625 ** findInodeInfo(). If this is the case, it is quite safe to close
34626 ** handle h - as it is guaranteed that no posix locks will be released
34630 ** implicit assumption here is that if fstat() fails, things are in
34649 /* NB: zFilename exists and remains valid until the file is closed
34769 /* It's odd to simulate an io-error here, but really this is just
34794 ** if SQLITE_PREFER_PROXY_LOCKING is defined.
34807 ** other file descriptor open on the same file is holding a file-lock.
34812 ** If a suitable file descriptor is found, then it is returned. If no
34813 ** such file descriptor is located, -1 is returned.
34820 ** but because no way to test it is currently available. It is better
34826 /* A stat() call may fail for various reasons. If this happens, it is
34828 ** For this reason, if an error occurs in the stat() call here, it is
34829 ** ignored and -1 is returned. The caller will try to open a new file
34858 ** This function is called by unixOpen() to determine the unix permissions
34859 ** to create new files with. If no error occurs, then SQLITE_OK is returned
34860 ** and a value suitable for passing as the third argument to open(2) is
34861 ** written to *pMode. If an IO error occurs, an SQLite error code is
34862 ** returned and the value of *pMode is not modified.
34867 ** But if the file being opened is a WAL or regular journal file, then
34873 ** If the SQLITE_ENABLE_8_3_NAMES option is enabled, then the
34874 ** original filename is unavailable. But 8_3_NAMES is only used for
34894 /* zPath is a path to a WAL or journal file. The following block derives
34903 ** where NN is a decimal number. The NN naming schemes are
34910 ** is guaranteed to contain a '-' character. */
34959 sqlite3_vfs *pVfs, /* The VFS for which this is the xOpen method */
34987 ** is called the directory file descriptor will be fsync()ed and close()d.
34995 /* If argument zPath is a NULL pointer, this function is required to open
35004 ** (b) if CREATE is set, then READWRITE must also be set, and
35005 ** (c) if EXCLUSIVE is set, then CREATE must also be set.
35006 ** (d) if DELETEONCLOSE is set, then CREATE must also be set.
35027 /* Detect a pid change and reset the PRNG. There is a race condition
35058 /* If zName is NULL, the upper layer is requesting a temp file. */
35072 ** open(). These must be calculated even if open() is not called, as
35108 /* If this process is running as root and if creating a new rollback
35211 ** Delete the file at zPath. If the dirSync argument is true, fsync()
35257 ** SQLITE_ACCESS_READWRITE: Return 1 if the file is read and writable.
35258 ** SQLITE_ACCESS_READONLY: Return 1 if the file is readable.
35314 ** is stored as a nul-terminated string in the buffer pointed to by
35318 ** (in this case, MAX_PATHNAME bytes). The full-path is written to
35339 /* It's odd to simulate an io-error here, but really this is just
35348 /* Call stat() on path zIn. Set bLink to true if the path is a symbolic
35419 ** message is available, it is written to zBufOut. If no error message
35420 ** is available, zBufOut is left unmodified and SQLite uses a default
35437 ** returns a void* which is really a pointer to a function. So how do we
35440 ** Variable x below is defined to be a pointer to a function taking
35446 ** This work-around is unlikely to work correctly on any system where
35460 #else /* if SQLITE_OMIT_LOAD_EXTENSION is defined: */
35482 ** When testing, initializing zBuf[] to zero is all we do. That means
35511 ** The argument is the number of microseconds we want to sleep.
35512 ** The return value is the number of microseconds of sleep actually
35539 ** The following variable, if set to a non-zero value, is interpreted as
35540 ** the number of seconds since 1970 and is used to set the result of
35602 ** The xGetLastError() method is designed to return a better
35604 ** during SQLite operation. Only the integer return code is currently
35622 ** Proxy locking is a "uber-locking-method" in this sense: It uses the
35623 ** other locking methods on secondary lock files. Proxy locking is a
35625 ** this reason, the division that implements of proxy locking is deferred
35640 ** address in the shared range is taken for a SHARED lock, the entire
35641 ** shared range is taken for an EXCLUSIVE lock):
35650 ** cache exposes a cache coherency problem that is present on all OS X
35659 ** changes the way database access is controlled by limiting access to a
35680 ** Specifying ":auto:" means that if there is a conch file with a matching
35684 ** actual proxy file name is generated from the name and path of the
35690 ** Once a lock proxy is configured for a database connection, it can not
35692 ** the above APIs (assuming the conch file is not being held by another
35710 ** proxy path against the values stored in the conch. The conch file is
35712 ** is patterned after the database file name as ".<databasename>-conch".
35714 ** host ID and/or proxy path, then the lock is escalated to an exclusive
35715 ** lock and the conch file contents is updated with the host ID and proxy
35716 ** path and the lock is downgraded to a shared lock again. If the conch
35717 ** is held by another process (with a shared lock), the exclusive lock
35718 ** will fail and SQLITE_BUSY is returned.
35725 ** Requesting the lock proxy does not immediately take the conch, it is
35726 ** only taken when the first request to lock database file is made.
35730 ** the connection to the database is closed.
35758 ** lock proxy files, only used when LOCKPROXYDIR is not set.
35766 ** sqlite_file_control API is not affected by SQLITE_FORCE_PROXY_LOCKING).
35770 ** Proxy locking is only available on MacOSX
35785 int conchHeld; /* 1 if the conch is held, -1 if lockless */
35792 ** The proxy lock file path for the database at dbPath is written into lPath,
35874 ** The caller is responsible not only for closing the file descriptor
35891 ** 2. if that fails, and this is a lock file (not-conch), try creating
35927 return SQLITE_IOERR_LOCK; /* even though it is the conch */
36010 ** it back. The newly created file's file descriptor is assigned to the
36011 ** conch file structure and finally the original conch file descriptor is
36088 * 2nd try: fail if the mod time changed or host id is different, wait
36147 ** lockPath is non-NULL, the host ID and lock file path must match. A NULL
36222 /* create a copy of the lock path if the conch is taken */
36244 /* create a copy of the lock path _only_ if the conch is taken */
36255 ** same process is still holding a shared lock. */
36399 ** The caller is responsible for ensuring that the allocated memory
36400 ** space is eventually freed.
36402 ** *pConchPath is set to NULL if a memory allocation error occurs.
36450 /* nothing to do if the path is NULL, :auto: or matches the existing path */
36471 ** pFile is a file that has been opened by a prior xOpen call. dbPath
36472 ** is a string buffer at least MAXPATHLEN+1 characters in size.
36538 ** (c) the file system is read-only, then enable no-locking access.
36569 /* all memory is allocated, proxys are created and assigned,
36618 /* turn off proxy locking - not supported. If support is added for
36620 ** the journal mode is WAL mode.
36663 ** This routine checks if there is a RESERVED lock held on the specified
36664 ** file by this or any other process. If such a lock is held, set *pResOut
36665 ** to a non-zero value otherwise *pResOut is set to zero. The return value
36666 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
36676 }else{ /* conchHeld < 0 is lockless */
36717 /* conchHeld < 0 is lockless */
36728 ** If the locking level of the file descriptor is already at or below
36729 ** the requested locking level, this routine is a no-op.
36741 /* conchHeld < 0 is lockless */
36791 ** The proxy locking style is intended for use with AFP filesystems.
36792 ** And since AFP is only supported on MacOSX, the proxy locking is also
36807 ** This routine is called once during SQLite initialization and by a
36809 ** necessarily been initialized when this routine is called, and so they
36815 ** The name of the VFS is NAME. The pAppData is a pointer to a pointer
36816 ** to the "finder" function. (pAppData is a pointer to a pointer because
36821 ** The FINDER parameter to this macro is the name of the pointer to the
36861 ** Note that the sqlite3_vfs.pNext field of the VFS object is modified
36862 ** by the SQLite core when the VFS is registered. So the following
36909 ** This routine is a no-op for unix.
36923 ** a legal notice, here is a blessing:
36931 ** This file contains code that is specific to Windows.
36934 #if SQLITE_OS_WIN /* This file is used for Windows only */
36937 ** Include code that is common to all os_*.c files
36945 ** a legal notice, here is a blessing:
36953 ** This file contains macros and a little bit of code that is common to
36954 ** all of the platform-specific files (os_*.c) and is #included into those
36957 ** This file should be #included by the os_*.c files only. It is not a
36969 # error "The MEMORY_DEBUG macro is obsolete. Use SQLITE_DEBUG instead."
36988 ** a legal notice, here is a blessing:
37087 ** is used for testing the I/O recovery logic.
37176 ** Make sure at least one set of Win32 APIs is available.
37205 # define SQLITE_WIN32_GETVERSIONEX 0 /* GetVersionEx() is deprecated */
37207 # define SQLITE_WIN32_GETVERSIONEX 1 /* GetVersionEx() is current */
37212 ** Check to see if the CreateFileMappingA function is supported on the
37213 ** target system. It is unavailable when using "mincore.lib" on Win10.
37214 ** When compiling for Windows 10, always assume "mincore.lib" is in use.
37255 ** Maximum pathname length (in bytes) for Win32. The MAX_PATH macro is in
37288 ** This macro is used when a local variable is set to a value that is
37375 ** The winFile structure is a subclass of sqlite3_file* specific to the win32
37410 ** The winVfsAppData structure is used for the pAppData member for all of the
37417 BOOL bNoLock; /* Non-zero if locking is disabled. */
37423 #define WINFILE_RDONLY 0x02 /* Connection is read only */
37457 * If this is non-zero, an isolated heap will be created by the native Win32
37459 * setting has no effect when compiling for WinRT. By default, this is enabled
37463 * WARNING: It is important to note that when this setting is non-zero and the
37464 * winMemShutdown function is called (e.g. by the sqlite3_shutdown
37475 * This is cache size used in the calculation of the initial size of the
37565 ** The following variable is (normally) set once and never changes
37566 ** thereafter. It records whether the operating system is Win9x
37570 ** 1: Operating system is Win9x.
37571 ** 2: Operating system is WinNT.
37587 ** This function is not available on Windows CE or WinRT.
37826 /* The GetProcAddressA() routine is only available on Windows CE. */
38213 ** is really just a macro that uses a compiler intrinsic (e.g. x64).
38214 ** So do not try to make this is into a redefinable interface.
38256 ** This is the xSetSystemCall() method of sqlite3_vfs for all of the
38258 ** system call pointer, or SQLITE_NOTFOUND if there is no configurable
38271 /* If no zName is given, restore all system calls to their default
38281 /* If zName is specified, operate on only the one system call
38300 ** Return the value of a system call. Return NULL if zName is not a
38301 ** recognized system call name. NULL is also returned if the system call
38302 ** is currently undefined.
38320 ** is the last system call or if zName is not the name of a valid
38382 ** destroy and recreate it. If the Win32 native heap is not isolated and/or
38471 ** milliseconds. This is equivalent to the Win32 Sleep() interface.
38504 ** Here is an interesting observation: Win95, Win98, and WinME lack
38507 ** this routine is used to determine if the host is Win95/98/ME or
38523 ** This function determines if the machine is running a version of Windows
38529 ** NOTE: The WinRT sub-platform is always assumed to be based on the NT
38598 if( !pPrior ) return; /* Passing NULL to HeapFree is undefined. */
38744 ** This routine is only called by sqlite3_config(), and therefore
38745 ** is not required to be threadsafe (it is not).
38769 ** Space to hold the returned string is obtained from sqlite3_malloc().
38795 ** Space to hold the returned string is obtained from sqlite3_malloc().
38822 ** Space to hold the returned string is obtained from sqlite3_malloc().
38851 ** Space to hold the returned string is obtained from sqlite3_malloc().
38878 ** Space to hold the returned string is obtained from sqlite3_malloc().
38896 ** Space to hold the returned string is obtained from sqlite3_malloc().
38912 ** This is a public wrapper for the winUtf8ToUnicode() function.
38928 ** This is a public wrapper for the winUnicodeToUtf8() function.
38944 ** This is a public wrapper for the winMbcsToUtf8() function.
38960 ** This is a public wrapper for the winMbcsToUtf8() function.
38976 ** This is a public wrapper for the winUtf8ToMbcs() function.
38992 ** This is a public wrapper for the winUtf8ToMbcs() function.
39011 ** argument is the name of the directory to use. The return value will be
39046 ** is zero if the error message fits in the buffer, or non-zero
39126 ** This function - winLogErrorAtLine() - is only ever called via the macro
39129 ** This routine is invoked after an error occurs in an OS function.
39180 ** The "winIoerrCanRetry1" macro is used to determine if a particular I/O
39181 ** error code obtained via GetLastError() is eligible to be retried. It
39183 ** non-zero if the error code is transient in nature and the operation
39188 ** is defined, it will be consulted only when the macro "winIoerrCanRetry1"
39189 ** returns zero. The "winIoerrCanRetry2" macro is completely optional and
39579 ** NOTE: Windows CE is handled differently here due its lack of the Win32
39610 ** NOTE: Windows CE is handled differently here due its lack of the Win32
39662 ** whether an error has actually occurred, it is also necessary to call
39711 ** It is reported that an attempt to close a handle might sometimes
39712 ** fail. This is a very unreasonable result, but Windows is notorious
40011 ** Count the number of fullsyncs and normal syncs. This is used to test
40024 ** Used only when SQLITE_NO_SYNC is not defined.
40031 ** Used when SQLITE_NO_SYNC is not defined and by the assert() and/or
40046 ** line is to test that doing so does not cause any problems.
40063 /* If we compiled with the SQLITE_NO_SYNC flag, then syncing is a
40149 ** LOCKFILE_FAIL_IMMEDIATELY is undefined on some Windows systems.
40182 ** is Win9x or WinNT.
40190 ** NOTE: Windows CE is handled differently here due its lack of the Win32
40263 ** It is not possible to lower the locking level one step at a time. You
40278 /* If there is already a lock of this type or more restrictive on the
40293 /* Make sure the locking sequence is correct
40301 ** the PENDING_LOCK byte is temporary.
40310 /* Try 3 times to get the pending lock. This is needed to work
40314 ** copy this retry logic. It is a hack intended for Windows only.
40405 ** This routine checks if there is a RESERVED lock held on the specified
40406 ** file by this or any other process. If such a lock is held, return
40438 ** If the locking level of the file descriptor is already at or below
40439 ** the requested locking level, this routine is a no-op.
40441 ** It is not possible for this routine to fail if the second argument
40442 ** is NO_LOCK. If the second argument is SHARED_LOCK then this routine
40481 ** Of the various locking implementations available, this is by far the
40482 ** simplest: locking is ignored. No attempt is made to lock the database
40485 ** This locking mode is appropriate for use on read-only databases
40489 ** database connections. But there is a serious risk of database
40490 ** corruption if this locking mode is used in situations where multiple
40517 ** If *pArg is initially negative then this is a query. Set *pArg to
40518 ** 1 or 0 depending on whether or not bit mask of pFile->ctrlFlags is set.
40520 ** If *pArg is 0 or 1, then clear or set the mask bit of pFile->ctrlFlags.
40653 ** the specified file. This is almost always 512 bytes, but may be
40687 ** global mutex is used to protect the winLockInfo objects used by
40690 ** Function winShmMutexHeld() is used to assert() that the global mutex
40691 ** is held when required. This function is only used as part of assert()
40715 ** log-summary is opened only once per process.
40723 ** The following fields are read-only after the object is created:
40729 ** winShmMutexHeld() is true when reading or writing any other field
40765 ** The following fields are initialized when this object is created and
40805 /* Access to the winShmNode object is serialized by the caller */
40842 ** This is not a VFS shared-memory method; it is a utility function called
40918 /* Look to see if there is an existing winShmNode that can be used.
40954 /* Check to see if another process is holding the dead-man switch.
40982 ** new (struct winShm) object to the pShmNode has been set. All that is
40983 ** left to do is to link the new object into the linked list starting
41005 ** storage if deleteFlag is true.
41167 ** This function is called to obtain a pointer to region iRegion of the
41169 ** are numbered starting from zero. Each shared-memory region is szRegion
41172 ** If an error occurs, an error code is returned and *pp is set to NULL.
41174 ** Otherwise, if the isWrite parameter is 0 and the requested shared-memory
41176 ** separate process), then *pp is set to NULL and SQLITE_OK returned. If
41177 ** isWrite is non-zero and the requested shared-memory region has not yet
41178 ** been allocated, it is allocated by this function.
41180 ** If the shared-memory region has already been allocated or is allocated by
41181 ** this call as described above, then it is mapped into this processes
41182 ** address space (if it is not already), *pp is set to point to the mapped
41214 /* The requested region is not mapped into this processes address space.
41215 ** Check to see if it has been allocated (i.e. if the wal-index file is
41226 /* The requested memory region does not exist. If isWrite is set to
41229 ** Alternatively, if isWrite is non-zero, use ftruncate() to allocate
41361 ** is already mapped, the existing mapping is replaced by the new). Or, if
41363 ** outstanding xFetch() references to it, this function is a no-op.
41365 ** If parameter nByte is non-negative, then it is the requested size of
41366 ** the mapping to create. Otherwise, if nByte is less than zero, then the
41367 ** requested size is the size of the file on disk. The actual size of the
41368 ** created mapping is either the requested size or the value configured
41369 ** using SQLITE_FCNTL_MMAP_SIZE, whichever is smaller.
41371 ** SQLITE_OK is returned if no error occurs (even if the mapping is not
41469 ** value of *pp is undefined in this case.
41506 ** If the third argument is non-NULL, then this function releases a
41511 ** Or, if the third argument is NULL, then this function is being called
41520 ** xFetch references. Or, if p!=0 (meaning it is an xFetch reference),
41534 ** file while a mapping is held, then the following winUnmapfile() call
41535 ** is unnecessary can be omitted - potentially improving
41628 ** supports for filenames into UTF-8. Space to hold the result is
41649 ** is obtained from malloc and must be freed by the calling
41701 /* It's odd to simulate an io-error here, but really this is just
41763 ** character, assume it is already a native Win32 path; otherwise,
41799 ** its name into UTF-8 (i.e. if it is UTF-16 right now).
41875 ** separator. If it does not and there is not enough space left to add
41885 ** Check that the output buffer is large enough for the temporary file
41890 ** If not, return SQLITE_ERROR. The number 17 is used here in order to
41918 ** Return TRUE if the named file is really a directory. Return false if
41919 ** it is something other than a directory, or if there is any kind of memory
41971 /* If argument zPath is a NULL pointer, this function is required to open
42001 ** (b) if CREATE is set, then READWRITE must also be set, and
42002 ** (c) if EXCLUSIVE is set, then CREATE must also be set.
42003 ** (d) if DELETEONCLOSE is set, then CREATE must also be set.
42035 /* If the second argument to this function is NULL, generate a
42076 /* SQLITE_OPEN_EXCLUSIVE is used to make sure that a new file is
42078 ** as it is usually understood.
42106 /* Reports from the internet are that performance is always
42107 ** better if FILE_FLAG_RANDOM_ACCESS is used. Ticket #2699. */
42239 ** will open a journal file shortly after it is created in order to do
42240 ** whatever it does. While this other process is holding the
42440 ** non-zero is returned from this function, the calling function must simply
42448 ** If the path name starts with a forward slash or a backslash, it is either
42450 ** "Unix" format on Windows. There is no easy way to differentiate between
42459 ** If the path name starts with a letter and a colon it is either a volume
42492 /* If this path name begins with "/X:", where "X" is any alphabetic
42576 /* It's odd to simulate an io-error here, but really this is just
42722 #else /* if SQLITE_OMIT_LOAD_EXTENSION is defined: */
42764 rand_s((unsigned int*)zBuf); /* rand_s() is not available with MinGW */
42821 ** The following variable, if set to a non-zero value, is interpreted as
42822 ** the number of seconds since 1970 and is used to set the result of
42840 /* FILETIME structure is a 64-bit value representing the number of
42893 ** The idea is that this function works like a combination of
42895 ** strerror_r() on Unix). After an error is returned by an OS
42902 ** If the error message is too large for the supplied buffer,
42904 ** is zero if the error message fits in the buffer, or non-zero
42905 ** otherwise (if the message was truncated). If non-zero is returned,
42906 ** then it is not necessary to include the nul-terminator character
42910 ** on SQLite. It is fine to have an implementation that never
42918 ** However if an error message is supplied, it will be incorporated
43081 ** a legal notice, here is a blessing:
43091 ** A bitmap is used to record which pages of a database file have been
43094 ** So the bitmap is usually sparse and has low cardinality.
43100 ** The size of the bitmap is fixed when the object is created.
43102 ** All bits are clear when the bitmap is created. Individual bits
43109 ** Bitvec object is the number of pages in the database file at the
43110 ** start of a transaction, and is thus usually less than a few thousand,
43150 ** A bitmap is an instance of the following structure.
43156 ** If iSize<=BITVEC_NBIT, then Bitvec.u.aBitmap[] is a straight
43157 ** bitmap. The least significant bit is bit 1.
43159 ** If iSize>BITVEC_NBIT and iDivisor==0 then Bitvec.u.aHash[] is
43162 ** Otherwise, the value i is redirected into one of BITVEC_NPTR
43167 ** N*iDivisor+1 and (N+1)*iDivisor. Each subbitmap is normalized
43171 u32 iSize; /* Maximum bit index. Max iSize is 4,294,967,296. */
43173 ** element. Max is BITVEC_NINT. For BITVEC_SZ of 512,
43177 /* Max iDivisor is max(u32) / BITVEC_NPTR + 1. */
43202 ** Check to see if the i-th bit is set. Return true or false.
43203 ** If p is NULL (if the bitmap has not been created) or if
43204 ** i is out of range, then return false.
43238 ** to get the memory needed to hold the sub-bitmap is the only
43241 ** The calling function must ensure that p is a valid Bitvec object
43242 ** and that the value for "i" is within range of the Bitvec object.
43243 ** Otherwise the behavior is undefined.
43283 /* available free spot. check to see if this is going to */
43386 ** The input is an array of integers that acts as a program
43391 ** There are 6 opcodes numbered from 0 through 5. 0 is the
43404 ** Opcode 5 is used to deliberately induce a fault in order to
43407 ** At the conclusion of the test the linear array is compared
43409 ** an error is returned. If they are the same, zero is returned.
43468 ** is found.
43495 ** a legal notice, here is a blessing:
43507 ** A complete page cache is an instance of this structure. Every
43511 ** A page cache entry is "clean" if it exactly matches what is currently
43512 ** on disk. A page is "dirty" if it has been modified and needs to be
43517 ** PgHdr.pDirtyNext and pDirtyPrev. The list is maintained in LRU order
43522 ** The PCache.pSynced variable is used to optimize searching for a dirty
43523 ** page to eject from the cache mid-transaction. It is better to eject
43525 ** Therefore, pSynced is maintained to that it *almost* always points
43527 ** clear PGHDR_NEED_SYNC flag or to a page that is older than this one
43551 ** When sqlite3PcacheTrace is 1, single line trace messages are issued.
43552 ** When sqlite3PcacheTrace is 2, a dump of the pcache showing all cache entries
43553 ** is displayed for many operations, resulting in a lot of output.
43589 ** Check invariants on a PgHdr entry. Return true if everything is OK.
43590 ** Return false if any invariant is violated.
43592 ** This routine is for use inside of assert() statements only. For
43601 assert( pPg->pgno>0 ); /* Page number is 1 or more */
43615 ** (1) Page X is journalled, and gets WRITEABLE and NEED_SEEK.
43616 ** (2) Page X moved to freelist, WRITEABLE is cleared
43617 ** (3) Page X reused, WRITEABLE is set again
43623 ** Another example is when the database page size is smaller than the
43624 ** disk sector size. When any page of a sector is journalled, all pages
43673 ** This is an optimization that allows sqlite3PcacheFetch() to skip
43703 /* If pSynced is NULL and this page has a clear NEED_SYNC flag, set
43704 ** pSynced to point to it. Checking the NEED_SYNC flag is an
43718 ** Wrapper around the pluggable caches xUnpin method. If the cache is
43719 ** being used for an in-memory database, this function is a no-op.
43730 ** Compute the number of pages of cache requested. p->szCache is the
43735 /* IMPLEMENTATION-OF: R-42059-47211 If the argument N is positive then the
43736 ** suggested cache size is set to N. */
43739 /* IMPLEMENTATION-OF: R-61436-13639 If the argument N is negative, then
43740 ** the number of cache pages is adjusted to use approximately abs(N*1024)
43753 /* IMPLEMENTATION-OF: R-26801-64137 If the xInit() method is NULL, then the
43754 ** built-in default page cache is used instead of the application defined
43774 ** has already been allocated and is passed in as the p pointer.
43801 ** are no outstanding page references when this function is called.
43827 ** such an object is already in cache, or if a new one is created.
43834 ** If the createFlag is 0, then NULL is always returned if the page
43835 ** is not already in the cache. If createFlag is 1, then a new page
43836 ** is created only if that can be done without spilling dirty pages
43863 ** 1 Allocate a new page if doing so is inexpensive.
43865 ** 2 Allocate a new page even it doing so is difficult.
43879 ** If the sqlite3PcacheFetch() routine is unable to allocate a new
43900 ** cleared), but if that is not possible settle for any other
43904 ** flag is currently referenced, then the following may leave pSynced
43906 ** cleared). This is Ok, as pSynced is just an optimization. */
43937 ** This is a helper routine for sqlite3PcacheFetchFinish()
43940 ** initialized, this routine is invoked to do the initialization.
43941 ** This routine is broken out into a separate function since it
43991 ** Decrement the reference count on a page. If the page is clean and the
43992 ** reference count drops to 0, then it is made eligible for recycling.
44002 ** then page p is already at the head of the dirty list and the
44023 ** page pointed to by p is invalid.
44036 ** Make sure the page is marked as dirty. If it isn't dirty already,
44055 ** Make sure the page is marked as clean. If it isn't clean already,
44124 ** Drop every cache entry whose page number is greater than "pgno". The
44128 ** If there is a reference to page 1 and the pgno parameter passed to this
44129 ** function is 0, then the data area associated with page 1 is zeroed, but
44130 ** the page object is not dropped.
44152 if( ALWAYS(pPage1) ){ /* Page 1 is always available in cache, because
44215 ** One extra bucket is added to catch overflow in case something
44238 ** the input list. But that is impossible.
44265 ** This is not the total number of pages referenced, but the sum of the
44308 ** argument is zero. Return the effective cache-spill size, which will
44354 ** callback. This is only used if the SQLITE_CHECK_PAGES macro is
44371 ** a legal notice, here is a blessing:
44382 ** If the default page cache implementation is overridden, then neither of
44391 ** The database page content is up front (so that buffer overreads tend to
44393 ** is the extension added by the btree.c module containing information such
44394 ** as the database page number and how that database page is used. PgHdr
44395 ** is added by the pcache.c layer and contains information used to keep track
44396 ** of which pages are "dirty". PgHdr1 is an extension added by this
44397 ** module (pcache1.c). The PgHdr1 header is a subclass of sqlite3_pcache_page.
44408 ** If SQLITE_PCACHE_SEPARATE_HEADER is defined, then the extension is obtained
44416 ** with this module. Information is passed back and forth as PgHdr1 pointers.
44430 ** The third case is a chunk of heap memory (defaulting to 100 pages worth)
44431 ** that is allocated when the page cache is created. The size of the local
44436 ** If N is positive, then N pages worth of memory are allocated using a single
44437 ** sqlite3Malloc() call and that memory is used for the first N pages allocated.
44438 ** Or if N is negative, then -1024*N bytes of memory are allocated and used
44442 ** (3) is exhausted, subsequent allocations fail over to the general-purpose
44457 ** Each cache entry is represented by an instance of the following
44458 ** structure. Unless SQLITE_PCACHE_SEPARATE_HEADER is defined, a buffer of
44459 ** PgHdr1.pCache->szPage bytes is allocated directly before this structure
44467 u8 isAnchor; /* This is the PGroup.lru element */
44474 /* Each page cache (or PCache) belongs to a PGroup. A PGroup is a set
44476 ** pages when they are under memory pressure. A PGroup is an instance of
44481 ** (1) Every PCache is the sole member of its own PGroup. There is
44484 ** (2) There is a single global PGroup that all PCaches are a member
44489 ** and is therefore often faster. Mode 2 requires a mutex in order to be
44492 ** For mode (1), PGroup.mutex is NULL. For mode (2) there is only a single
44493 ** PGroup which is the pcache1.grp global variable and its mutex is
44505 /* Each page cache is an instance of the following object. Every
44508 ** is an instance of this object.
44515 ** flag (bPurgeable) are set when the cache is created. nMax may be
44523 int bPurgeable; /* True if cache is purgeable */
44530 ** when the accessor is holding the PGroup mutex.
44572 ** (2) even if an incorrect value is read, no great harm is done since this
44573 ** is really just an optimization. */
44579 ** alias "pcache1". This ensures that the WSD emulation is used when
44602 ** This function is called during initialization if a static buffer is
44607 ** This routine is called from sqlite3_initialize() and so it is guaranteed
44608 ** to be serialized already. There is no need for further mutexing.
44672 ** such buffer exists or there is no space left in it, this function falls
44695 /* Memory is not available in the SQLITE_CONFIG_PAGECACHE pool. Get
44777 /* The group mutex must be released before pcache1Alloc() is called. This
44778 ** is because it might call sqlite3_release_memory(), which assumes that
44779 ** this mutex is not held. */
44858 ** it is desirable to avoid allocating a new page cache entry because
44863 ** Or, the heap is used for all page cache memory but the heap is
44864 ** under memory pressure, then again it is desirable to avoid
44880 ** This function is used to resize the hash table used by the cache passed
44883 ** The PCache mutex must be held when this function is called.
44920 ** This function is used internally to remove the page pPage from the
44921 ** PGroup LRU list, if is part of it. If pPage is not part of the PGroup
44922 ** LRU list, then this function is a no-op.
44924 ** The PGroup mutex must be held when this function is called.
44949 ** (PCache1.apHash structure) that it is currently stored in.
44950 ** Also free the page if freePage is true.
44952 ** The PGroup mutex must be held when this function is called.
44995 ** The PCache mutex must be held when this function is called.
45001 TESTONLY( int nPage = 0; ) /* To assert pCache->nPage is correct */
45008 ** cache, then there is no point in scanning the entire hash table.
45015 /* This is the general case where many pages are being removed.
45016 ** It is necessary to scan the entire hash table */
45055 ** The pcache1.separateCache variable is true if each PCache has its own
45056 ** private PGroup (mode-1). pcache1.separateCache is false if the single
45057 ** PGroup in pcache1.grp is used for all page caches (mode-2).
45225 /* Step 3: Abort if createFlag is 1 but the cache is nearly full */
45292 ** page. 1 means allocate a new page if space is easily available. 2
45296 ** database) there is really no difference between createFlag 1 and 2. So
45303 ** 1. Regardless of the value of createFlag, the cache is searched for a
45304 ** copy of the requested page. If one is found, it is returned.
45306 ** 2. If createFlag==0 and the page is not already in the cache, NULL is
45309 ** 3. If createFlag is 1, and the page is not already in the cache, then
45313 ** (a) the number of pages pinned by the cache is greater than
45316 ** (b) the number of pages pinned by the cache is greater than
45320 ** 4. If none of the first three conditions apply and the cache is marked
45321 ** as purgeable, and if one of the following is true:
45323 ** (a) The number of pages allocated for the cache is already
45326 ** (b) The number of pages allocated for all purgeable caches is
45330 ** (c) The system is under memory pressure and wants to avoid
45333 ** then attempt to recycle a page from the LRU list. If it is the right
45339 ** There are two versions of this routine. pcache1FetchWithMutex() is
45340 ** the general case. pcache1FetchNoMutex() is a faster implementation for
45341 ** the common case where pGroup->mutex is NULL. The pcache1Fetch() wrapper
45357 ** If the page was not in the hash table and createFlag is 0, abort.
45432 /* It is an error to call this function if the page is already
45530 ** This function is called during initialization (sqlite3_initialize()) to
45568 ** This function is called to free superfluous dynamically allocated memory
45572 ** nReq is the number of bytes of memory required. Once this much has
45573 ** been released, the function returns. The return value is the total number
45603 ** This function is used by test procedures to inspect the internal state
45631 ** a legal notice, here is a blessing:
45641 ** The RowSet object is a collection of rowids. Rowids
45646 ** After all inserts are finished, it is possible to extract the
45660 ** TEST checks to see if an element is already in the RowSet. SMALLEST
45663 ** The INSERT primitive might allocate additional memory. Memory is
45664 ** allocated in chunks so most INSERTs do no allocation. There is an
45665 ** upper bound on the size of allocated memory. No memory is freed
45673 ** The initial batch number is zero, so if the very first TEST contains
45677 ** that is attempted.
45679 ** The cost of an INSERT is roughly constant. (Sometimes new memory
45681 ** batch number is O(NlogN) where N is the number of elements in the RowSet.
45682 ** The cost of a TEST using the same batch number is O(logN). The cost
45683 ** of the first SMALLEST is O(NlogN). Second and subsequent SMALLEST
45684 ** primitives are constant time. The cost of DESTROY is O(N).
45705 ** Each entry in a RowSet is an instance of the following object.
45707 ** This same object is reused to store a linked list of trees of RowSetEntry
45709 ** in the list, pLeft points to the tree, and v is unused. The
45722 ** when the RowSet is destroyed.
45749 #define ROWSET_SORTED 0x01 /* True if RowSet.pEntry is sorted */
45754 ** are available at pSpace. The db pointer is used as a memory context
45758 ** It must be the case that N is sufficient to make a Rowset. If not
45761 ** If N is larger than the minimum, use the surplus as an initial
45782 ** the RowSet has allocated over its lifetime. This routine is
45800 ** Allocate a new RowSetEntry object that is associated with the
45804 ** In an OOM situation, the RowSet.db->mallocFailed flag is set and this
45810 /* We could allocate a fresh RowSetEntry each time one is needed, but it
45811 ** is more efficient to pull a preallocated entry from the pool */
45829 ** The mallocFailed flag of the database connection is set if a
45836 /* This routine is never called after sqlite3RowSetNext() */
45923 ** The input, pIn, is a binary tree (or subtree) of RowSetEntry objects.
45974 ** is still generated without this branch, but the tree is wildly
45979 /* It is safe to always return here, but the resulting tree
46020 ** 0 if the RowSet is already empty.
46060 ** If this is the first test of a new batch and if there exist entries
46067 /* This routine is never called after sqlite3RowSetNext() */
46132 ** a legal notice, here is a blessing:
46139 ** This is the implementation of the page cache subsystem or "pager".
46141 ** The pager is used to access a database disk file. It implements
46143 ** is separate from the database file. The pager also implements file
46146 ** another is writing.
46156 ** a legal notice, here is a blessing:
46204 ** There is one object of this type for each pager.
46216 ** snapshot is like a read-transaction. It is the state of the database
46225 /* Read a page from the write-ahead log, if it is present. */
46229 /* If the WAL is not empty, return the size of the database. */
46275 /* Return true if the argument is non-NULL and the WAL module is using
46276 ** heap-memory for the wal-index. Otherwise, if the argument is NULL or the
46277 ** WAL module is using shared-memory, return false.
46287 /* If the WAL file is not empty, return the number of bytes of content
46309 ** Within this comment block, a page is deemed to have been synced
46310 ** automatically as soon as it is written when PRAGMA synchronous=OFF.
46311 ** Otherwise, the page is not synced until the xSync method of the VFS
46312 ** is called successfully on the file containing the page.
46314 ** Definition: A page of the database file is said to be "overwriteable" if
46323 ** (c) The page number is greater than the largest page that existed in
46326 ** (1) A page of the database file is never overwritten unless one of the
46331 ** (b) The atomic page write optimization is enabled, and the entire
46350 ** (6) If a master journal file is used, then all writes to the database file
46361 ** journal is rolled back, the resulting database file will be logically
46364 ** (8) When a transaction is rolled back, the xTruncate method of the VFS
46365 ** is called to restore the database file to the same size it was at
46367 ** method is a no-op, but that does not change the fact the SQLite will
46370 ** (9) Whenever the database file is modified, at least one bit in the range
46378 ** (11) A database file is well-formed at the beginning and at the conclusion
46381 ** (12) An EXCLUSIVE lock is held on the database file when writing to
46384 ** (13) A SHARED lock is held on the database file while reading any
46405 ** associated file-descriptor is returned. FILEHANDLEID() takes an sqlite3_file
46451 ** The pager starts up in this state. Nothing is guaranteed in this
46452 ** state - the file may or may not be locked and the database size is
46455 ** * No read or write transaction is active.
46462 ** rollback (non-WAL) mode are met. Unless the pager is (or recently
46463 ** was) in exclusive-locking mode, a user-level read transaction is
46464 ** open. The database size is known in this state.
46468 ** OPEN after the read-transaction is completed. However a connection
46470 ** this state even after the read-transaction is closed. The only way
46472 ** is via the ERROR state (see below).
46475 ** * A SHARED or greater lock is held on the database file.
46477 ** transaction is not active). The dbOrigSize and dbFileSize variables
46479 ** * If the database is a WAL database, then the WAL connection is open.
46480 ** * Even if a read-transaction is not open, it is guaranteed that
46481 ** there is no hot-journal in the file-system.
46486 ** is first opened on the database. In WRITER_LOCKED state, all locks
46491 ** BEGIN EXCLUSIVE) EXCLUSIVE lock is obtained on the database file when
46492 ** moving to this state, but the journal file is not written to or opened
46493 ** to in this state. If the transaction is committed or rolled back while
46494 ** in WRITER_LOCKED state, all that is required is to unlock the database
46497 ** IN WAL mode, WalBeginWriteTransaction() is called to lock the log file.
46498 ** If the connection is running with locking_mode=exclusive, an attempt
46499 ** is made to obtain an EXCLUSIVE lock on the database file.
46501 ** * A write transaction is active.
46502 ** * If the connection is open in rollback-mode, a RESERVED or greater
46503 ** lock is held on the database file.
46504 ** * If the connection is open in WAL-mode, a WAL write transaction
46505 ** is open (i.e. sqlite3WalBeginWriteTransaction() has been successfully
46514 ** A pager moves from WRITER_LOCKED state to this state when a page is
46516 ** is opened (if it is not already open) and a header written to the
46519 ** * A write transaction is active.
46520 ** * A RESERVED or greater lock is held on the database file.
46521 ** * The journal file is open and the first header has been written
46532 ** * A write transaction is active.
46533 ** * An EXCLUSIVE or greater lock is held on the database file.
46534 ** * The journal file is open and the first header has been written
46541 ** It is not possible for a WAL connection to enter this state.
46546 ** by finalizing the journal file. Once in WRITER_FINISHED state, it is
46550 ** * A write transaction is active.
46551 ** * An EXCLUSIVE or greater lock is held on the database file.
46553 ** If no error occurred, all that remains is to finalize the journal to
46559 ** The ERROR state is entered when an IO or disk-full error (including
46578 ** outstanding transactions have been abandoned, the pager is able to
46581 ** is reloaded from disk (and, if necessary, hot-journal rollback peformed)
46582 ** when a read-transaction is next opened on the pager (transitioning
46598 ** In other cases, the error is returned to the b-tree layer. The b-tree
46602 ** Condition (3) is necessary because it can be triggered by a read-only
46609 ** * The Pager.errCode variable is set to something other than SQLITE_OK.
46611 ** last reference is dropped the pager should move back to OPEN state).
46612 ** * The pager is not an in-memory pager.
46617 ** * A pager is never in WRITER_DBMOD or WRITER_FINISHED state if the
46618 ** connection is open in WAL mode. A WAL connection is always in one
46621 ** * Normally, a connection open in exclusive mode is never in PAGER_OPEN
46624 ** executed), and when the pager is leaving the "error state".
46637 ** The Pager.eLock variable is almost always set to one of the
46640 ** This variable is kept up to date as locks are taken and released by
46644 ** (i.e. one of the SQLITE_IOERR subtypes), it is not clear whether or not
46646 ** pagerUnlockDb() take a conservative approach - eLock is always updated
46648 ** VFS call is successful. This way, the Pager.eLock variable may be set
46649 ** to a less exclusive (lower) value than the lock that is actually held
46650 ** at the system level, but it is never set to a more exclusive value.
46652 ** This is usually safe. If an xUnlock fails or appears to fail, there may
46656 ** The exception is when the database file is unlocked as the pager moves
46660 ** fails at this point and the pager is left holding an EXCLUSIVE lock, this
46664 ** xCheckReservedLock() is defined as returning true "if there is a RESERVED
46666 ** return true because the caller itself is holding an EXCLUSIVE lock (but
46673 ** database in the ERROR state, Pager.eLock is set to UNKNOWN_LOCK. It
46674 ** is only changed back to a real locking state after a successful call
46676 ** omits the check for a hot-journal if Pager.eLock is set to UNKNOWN_LOCK
46681 ** Pager.eLock may only be set to UNKNOWN_LOCK when the pager is in
46687 ** A macro used for invoking the codec if there is one
46702 ** returns a value larger than this, then MAX_SECTOR_SIZE is used instead.
46704 ** such a system. This is currently an undocumented limit.
46710 ** An instance of the following structure is allocated for each active
46712 ** are stored in the Pager.aSavepoint[] array, which is allocated and
46715 ** When a savepoint is created, the PagerSavepoint.iHdrOffset field is
46716 ** set to 0. If a journal-header is written into the main journal while
46717 ** the savepoint is active, then iHdrOffset is set to the byte offset
46719 ** journal before the journal-header. This is required during savepoint
46739 #define SPILLFLAG_NOSYNC 0x04 /* Spill is ok, but do not sync */
46742 ** An open page cache is an instance of struct Pager. A description of
46756 ** locks), this variable is always set to EXCLUSIVE_LOCK. Since such
46767 ** This boolean variable is used to make sure that the change-counter
46768 ** (the 4-byte header field at byte offset 24 of the database file) is
46771 ** It is set to true when the change-counter field is updated, which
46772 ** can only happen if an exclusive lock is held on the database file.
46773 ** It is cleared (set to false) whenever an exclusive lock is
46774 ** relinquished on the database file. Each time a transaction is committed,
46775 ** The changeCountDone flag is inspected. If it is true, the work of
46776 ** updating the change-counter is omitted for the current transaction.
46784 ** When PagerCommitPhaseOne() is called to commit a transaction, it may
46786 ** journal file before it is synced to disk.
46789 ** the way in which the journal file is finalized after the transaction is
46791 ** If a journal file does not contain a master-journal pointer, it is
46793 ** it does contain a master-journal pointer the journal file is finalized
46802 ** The flag is cleared as soon as the journal file is finalized (either
46805 ** is cleared anyway (and the pager will move to ERROR state).
46814 ** writing to the database from pagerStress() is disabled altogether.
46815 ** The SPILLFLAG_ROLLBACK case is done in a very obscure case that
46818 ** while it is being traversed by code in pager_playback(). The SPILLFLAG_OFF
46819 ** case is a user preference.
46821 ** If the SPILLFLAG_NOSYNC bit is set, writing to the database from
46822 ** pagerStress() is permitted, but syncing the journal file is not.
46823 ** This flag is set by sqlite3PagerWrite() when the file-system sector-size
46824 ** is larger than the database page-size in order to prevent a journal sync
46829 ** This is a boolean variable. If true, then any required sub-journal
46830 ** is opened as an in-memory journal file. If false, then in-memory
46833 ** This variable is updated by the upper layer each time a new
46834 ** write-transaction is opened.
46838 ** Variable dbSize is set to the number of pages in the database file.
46839 ** It is valid in PAGER_READER and higher states (all states except for
46842 ** dbSize is set based on the size of the database file, which may be
46845 ** is not an integer multiple of the page-size, the value stored in
46846 ** dbSize is rounded down (i.e. a 5KB file with 2K page-size has dbSize==2).
46847 ** Except, any file that is greater than 0 bytes in size is considered
46852 ** dbSize are modified in the cache, dbSize is updated accordingly.
46853 ** Similarly, if the database is truncated using PagerTruncateImage(),
46854 ** dbSize is updated.
46857 ** PAGER_WRITER_LOCKED and higher. dbOrigSize is a copy of the dbSize
46858 ** variable at the start of the transaction. It is used during rollback,
46863 ** the file on disk in pages. It is set to a copy of dbSize when the
46864 ** write-transaction is first opened, and updated when VFS calls are made
46867 ** The only reason the dbFileSize variable is required is to suppress
46869 ** when a transaction is committed, the dbFileSize variable indicates
46870 ** that the database file is larger than the database image (Pager.dbSize),
46871 ** pager_truncate() is called. The pager_truncate() call uses xFilesize()
46873 ** dbFileSize is not used when rolling back a transaction. In this case
46874 ** pager_truncate() is called unconditionally (which means there may be
46875 ** a call to xFilesize() that is not strictly required). In either case,
46880 ** The dbHintSize variable is used to limit the number of calls made to
46883 ** dbHintSize is set to a copy of the dbSize variable when a
46884 ** write-transaction is opened (at the same time as dbFileSize and
46885 ** dbOrigSize). If the xFileControl(FCNTL_SIZE_HINT) method is called,
46886 ** dbHintSize is increased to the number of pages that correspond to the
46892 ** The Pager.errCode variable is only ever used in PAGER_ERROR state. It
46893 ** is set to zero in all other states. In PAGER_ERROR state, Pager.errCode
46894 ** is always set to SQLITE_FULL, SQLITE_IOERR or one of the SQLITE_IOERR_XXX
46908 u8 tempFile; /* zFilename is a temporary or immutable file */
46916 ** when the pager is first created or else only change when there is a
47014 ** was obtained from /dev/random. It is used only as a sanity check.
47017 ** checking information. If the power fails while the journal is being
47019 ** file after power is restored. If an attempt is then made
47021 ** sanity checking data is an attempt to discover the garbage in the
47027 ** This cksum is initialized to a 32-bit random value that appears in the
47028 ** journal file right after the header. The random initializer is important,
47029 ** because garbage data that appears at the end of a journal is likely
47033 ** is different for every journal, we minimize that risk.
47040 ** The size of the of each page record in the journal is given by
47046 ** The journal header size for this pager. This is usually the same
47052 ** The macro MEMDB is true if we are dealing with an in-memory database.
47053 ** We do this as a macro so that if the SQLITE_OMIT_MEMORYDB macro is set,
47064 ** The macro USEFETCH is true if we are allowed to use the xFetch and xUnfetch
47074 ** The maximum legal page number is (2^31 - 1).
47079 ** The argument to this macro is a file descriptor (type sqlite3_file*).
47080 ** Return 0 if it is not open, or non-zero (but not 1) if it is.
47082 ** This is so that expressions can be written as:
47132 ** the change-counter field, so the changeCountDone flag is always set.
47137 /* If the useJournal flag is clear, the journal-mode must be "OFF".
47138 ** And if the journal-mode is "OFF", the journal file must not be open.
47147 ** return SQLITE_IOERR_NOMEM while the journal file is being written). It
47148 ** is therefore not possible for an in-memory pager to enter the ERROR
47161 /* If changeCountDone is set, a RESERVED lock or greater must be held
47196 /* It is possible that if journal_mode=wal here that neither the
47251 ** is intended to be used within debuggers. For example, as an alternative
47299 ** Return true if it is necessary to write page *pPg into the sub-journal.
47303 ** * The page-number is less than or equal to PagerSavepoint.nOrig, and
47304 ** * The bit corresponding to the page-number is not set in
47323 ** Return true if the page is already in the journal file.
47332 ** that is read in *pRes. Return SQLITE_OK if everything worked, or an
47333 ** error code is something goes wrong.
47354 ** on success or an error code is something goes wrong.
47367 ** Except, if Pager.eLock is set to UNKNOWN_LOCK when this function is
47390 ** RESERVED_LOCK or EXCLUSIVE_LOCK. If the caller is successful, set the
47393 ** Except, if Pager.eLock is set to UNKNOWN_LOCK when this function is
47394 ** called, do not modify it unless the new locking state is EXCLUSIVE_LOCK.
47418 ** (b) the value returned by OsSectorSize() is less than or equal
47421 ** The optimization is also always enabled for temporary files. It is
47422 ** an error to call this function if pPager is opened on an in-memory
47425 ** If the optimization cannot be used, 0 is returned. If it can be used,
47426 ** then the value returned is the size of the journal file when it
47456 ** If SQLITE_CHECK_PAGES is defined then we do some sanity checking
47457 ** on the cache using a hash function. This is used for testing
47481 ** is defined, and NDEBUG is not defined, an assert() statement checks
47482 ** that the page is either dirty or still matches the calculated page-hash.
47499 ** When this is called the journal file for pager pPager must be open.
47506 ** the caller. This should be sqlite3_vfs.mxPathname+1 (to ensure there is
47508 ** name in the journal is longer than nMaster bytes (including a
47509 ** nul-terminator), then this is handled as if no master journal name
47512 ** If a master journal file name is present at the end of the journal
47513 ** file, then it is copied into the buffer pointed to by zMaster. A
47514 ** nul-terminator byte is appended to the buffer following the master
47517 ** If it is determined that no master journal file name is present
47518 ** zMaster[0] is set to 0 and SQLITE_OK returned.
47521 ** error code is returned.
47551 ** containing the master journal filename is corrupted. This means
47590 ** The journal file must be open when this function is called.
47592 ** This function is a no-op if the journal file has not been written to
47595 ** If doTruncate is non-zero or the Pager.journalSizeLimit variable is
47598 ** if the pager is not in no-sync mode, sync the journal file immediately
47601 ** If Pager.journalSizeLimit is set to a positive, non-zero value, and
47603 ** journal file in bytes is larger than this value, then truncate the
47628 /* At this point the transaction is committed but the write lock
47629 ** is still held on the file. If there is a size limit configured for
47631 ** space than that limit allows for, truncate it now. There is no need
47646 ** The journal file must be open when this routine is called. A journal
47647 ** header (JOURNAL_HDR_SZ bytes) is written into the journal file at the
47650 ** The format for the journal header is as follows:
47652 ** - 4 bytes: Number of records in journal, or -1 no-sync mode is on.
47687 ** journal header. Normally, zero is written to this value at this time.
47689 ** if in full-sync mode), the zero is overwritten with the true number
47692 ** A faster alternative is to write 0xFFFFFFFF to the nRec field. When
47695 ** is dangerous, as if a failure occurred whilst writing to the journal
47699 ** * When the pager is in no-sync mode. Corruption can follow a
47702 ** * When the SQLITE_IOCAP_SAFE_APPEND flag is set. This guarantees
47703 ** that garbage data is never appended to the journal file.
47726 /* Initializing the tail of the buffer is not necessary. Everything
47727 ** works find if the following memset() is omitted. But initializing
47734 /* In theory, it is only necessary to write the 28 bytes that the
47737 ** record is written to the following sector (leaving a gap in the file
47743 ** (JOURNAL_HDR_SZ - 28) bytes that will not be used. So that is what
47744 ** is done.
47746 ** The loop is required here in case the sector-size is larger than the
47747 ** database page size. Since the zHeader buffer is only Pager.pageSize
47762 ** The journal file must be open when this is called. A journal header file
47763 ** (JOURNAL_HDR_SZ bytes) is read from the current location in the journal
47764 ** file. The current location in the journal file is given by
47768 ** If the header is read successfully, *pNRec is set to the number of
47769 ** page records following this header and *pDbSize is set to the size of the
47771 ** is set to the value read from the journal header. SQLITE_OK is returned
47774 ** If the journal header file appears to be corrupted, SQLITE_DONE is
47776 ** cannot be read from the journal file an error code is returned.
47792 ** journal file is too small for there to be a header stored at this
47840 ** variable is already set to the correct page size.
47855 /* If the either the page-size or sector-size in the journal-header is
47865 ** PagerSetPagesize() is tested.
47873 ** is being called from within pager_playback(). The local value
47874 ** of Pager.sectorSize is restored at the end of that routine.
47887 ** thing written to a journal file. If the pager is in full-sync mode, the
47888 ** journal file descriptor is advanced to the next sector boundary before
47889 ** anything is written. The format is:
47897 ** The master journal page checksum is the sum of the bytes in the master
47898 ** journal name, where each byte is interpreted as a signed 8-bit integer.
47900 ** If zMaster is a NULL pointer (occurs for a single database transaction),
47901 ** this call is a no-op.
47928 ** the master journal name. This is in case the previous page written to
47950 /* If the pager is in peristent-journal mode, then the physical
47952 ** and 8 bytes of magic data just written to the file. This is
47955 ** whether or not the journal is hot.
47957 ** Easiest thing to do in this scenario is to truncate the journal
47988 ** if it is open and the pager is not in exclusive mode.
48025 ** This function is a no-op if the pager is in exclusive mode and not
48029 ** If the pager is not in exclusive-access mode, the database file is
48030 ** completely unlocked. If the file is unlocked and the file-system does
48031 ** not exhibit the UNDELETABLE_WHEN_OPEN property, the journal file is
48032 ** closed (if it is open).
48034 ** If the pager is in ERROR state when this function is called, the
48036 ** the OPEN state. Regardless of whether the pager is in exclusive-mode
48039 ** is opened (by this or by any other connection).
48077 /* If the pager is in the ERROR state and the call to unlock the database
48080 ** is necessary.
48088 ** without clearing the error code. This is intentional - the error
48089 ** code is cleared and the cache reset in the block below.
48096 /* If Pager.errCode is set, the contents of the pager cache cannot be
48120 ** This function is called whenever an IOERR or FULL error that requires
48122 ** The first argument is a pointer to the pager structure, the second
48124 ** value returned is a copy of the second argument to this function.
48126 ** If the second argument is SQLITE_FULL, SQLITE_IOERR or one of the
48128 ** is stored in Pager.errCode. While the pager remains in the ERROR state,
48156 ** The write transaction open on pPager is being committed (bCommit==1)
48163 ** * For non-TEMP databases, always sync to disk. This is necessary
48179 ** This routine ends a transaction. A transaction is usually ended by
48185 ** This routine is never called in PAGER_ERROR state. If it is called
48186 ** in PAGER_NONE or PAGER_SHARED state and the lock held is less
48187 ** exclusive than a RESERVED lock, it is a no-op.
48191 ** If the journal file is open, then it is "finalized". Once a journal
48192 ** file has been finalized it is not possible to use it to roll back a
48194 ** or any other database connection. Exactly how a journal is finalized
48195 ** depends on whether or not the pager is running in exclusive mode and
48199 ** Journal file descriptor is simply closed. This destroys an
48203 ** Journal file is truncated to zero bytes in size.
48211 ** The journal file is closed and deleted using sqlite3OsDelete().
48213 ** If the pager is running in exclusive mode, this method of finalizing
48214 ** the journal file is never used. Instead, if the journalMode is
48215 ** DELETE and the pager is in exclusive mode, the method described under
48216 ** journalMode==PERSIST is used instead.
48218 ** After the journal is finalized, the pager moves to PAGER_READER state.
48219 ** If running in non-exclusive rollback mode, the lock on the file is
48222 ** SQLITE_OK is returned if no error occurs. If an error occurs during
48224 ** database then the IO error code is returned to the user. If the
48228 ** to the first error encountered (the journal finalization one) is
48237 ** is no write-transaction active but a RESERVED or greater lock is
48240 ** 1. After a successful hot-journal rollback, it is called with
48245 ** read-transaction, this function is called with eState==PAGER_READER
48246 ** and eLock==EXCLUSIVE_LOCK when the read-transaction is closed.
48269 /* Make sure the new file size is written into the inode right away.
48327 ** locking_mode=exclusive mode but is no longer, drop the EXCLUSIVE
48333 /* This branch is taken when committing a transaction in rollback-journal
48334 ** mode if the database file on disk is larger than the database image.
48336 ** successfully committed, but the EXCLUSIVE lock is still held on the
48337 ** file. So it is safe to truncate the database file to its minimum
48361 ** Execute a rollback if a transaction is active and unlock the
48365 ** the rollback at this time. Instead, pager_unlock() is called. The
48368 ** means that there is a hot-journal left in the file-system, the next
48397 ** This is not a real checksum. It is really just the sum of the
48400 ** Each byte is interpreted as an 8-bit unsigned integer.
48406 ** scenario is that one end or the other of the record will be changed.
48407 ** It is much less likely that the two ends of the journal record will be
48438 ** Make sure the number of reserved bits is the same in the destination
48439 ** pager as it is in the source. This comes up when a VACUUM changes the
48454 ** value is increased to the start of the next page in the journal.
48460 ** is greater than the current value of Pager.dbSize, then playback is
48461 ** skipped and SQLITE_OK is returned.
48463 ** If pDone is not NULL, then it is a record of pages that have already
48465 ** (if the corresponding pDone bit is set) then skip the playback.
48466 ** Make sure the pDone bit corresponding to the *pOffset page is set
48469 ** If the page record is successfully read from the (sub-)journal file
48470 ** and played back, then SQLITE_OK is returned. If an IO error occurs
48472 ** to the database file, then the IO error code is returned. If data
48473 ** is successfully read from the (sub-)journal file but appears to be
48474 ** corrupted, SQLITE_DONE is returned. Data is considered corrupted in
48477 ** * If the record page-number is illegal (0 or PAGER_MJ_PGNO), or
48478 ** * If the record is being rolled back from the main journal file
48483 ** If this is a savepoint rollback, then memory may have to be dynamically
48484 ** allocated by this function. If this is the case and an allocation fails,
48485 ** SQLITE_NOMEM is returned.
48500 int isSynced; /* True if journal page is synced */
48502 assert( (isMainJrnl&~1)==0 ); /* isMainJrnl is 0 or 1 */
48503 assert( (isSavepnt&~1)==0 ); /* isSavepnt is 0 or 1 */
48511 /* Either the state is greater than PAGER_WRITER_CACHEMOD (a transaction
48512 ** or savepoint rollback done at the request of the caller) or this is
48513 ** a hot-journal rollback. If it is a hot-journal rollback, the pager
48514 ** is in state OPEN and holds an EXCLUSIVE lock. Hot-journal rollback
48532 /* Sanity checking on the page. This is more important that I originally
48533 ** thought. If a power failure occurs while the journal is being written,
48566 /* If the pager is in CACHEMOD state, then there must be a copy of this
48568 ** not the database file. The page is left marked dirty in this case.
48570 ** An exception to the above rule: If the database is in no-sync mode
48571 ** and a page is moved during an incremental vacuum then the page may
48574 ** either. So the condition described in the above paragraph is not
48578 ** pager cache if it exists and the main file. The page is then marked
48579 ** not dirty. Since this code is only executed in PAGER_OPEN state for
48580 ** a hot-journal rollback, it is guaranteed that the page-cache is empty
48581 ** if the pager is in OPEN state.
48583 ** Ticket #1171: The statement journal might contain page content that is
48585 ** This occurs when a page is changed prior to the start of a statement
48593 ** locked. (2) we know that the original page content is fully synced
48594 ** in the main journal either because the page is not in cache or else
48595 ** the page is marked as needSync==0.
48598 ** is possible to fail a statement on a database that does not yet exist.
48634 /* If this is a rollback of a savepoint and data was not written to
48635 ** the database and the page is not in-memory, there is a potential
48636 ** problem. When the page is next fetched by the b-tree layer, it
48642 ** if the page is on the free-list at the start of the transaction, then
48645 ** The solution is to add an in-memory page to the cache containing
48648 ** requiring a journal-sync before it is written.
48660 /* No page should ever be explicitly rolled back that is in use, except
48661 ** for page 1 which is held in use in order to keep the lock on the
48672 ** is normally cleaned by sqlite3PcacheCleanAll() after rollback and so
48690 ** Parameter zMaster is the name of a master journal file. A single journal
48692 ** This routine checks if it is possible to delete the master journal file,
48693 ** and does so if it is.
48695 ** Argument zMaster may point to Pager.pTmpSpace. So that buffer is not
48698 ** When a master journal file is created, it is populated with the names
48700 ** encoded text. The end of each child journal file is marked with a
48719 ** no such child journal can be found, file zMaster is deleted from
48722 ** If an IO error within this function, an error code is returned. This
48724 ** fails, SQLITE_NOMEM is returned. Otherwise, if no IO or malloc errors
48725 ** occur, SQLITE_OK is returned.
48823 ** This function is used to change the actual size of the database
48827 ** If the main database file is not open, or the pager is not in either
48828 ** DBMOD or OPEN state, this function is a no-op. Otherwise, the size
48829 ** of the file is changed to nPage pages (nPage*pPager->pageSize bytes).
48830 ** If the file on disk is currently larger than nPage pages, then use the VFS
48833 ** Or, it might be the case that the file on disk is smaller than
48835 ** you try to truncate a file to some size that is larger than it
48836 ** currently is, so detect this case and write a single zero byte to
48876 ** return value is guaranteed to lie between 32 and MAX_SECTOR_SIZE.
48896 ** For temporary files the effective sector size is always 512 bytes.
48898 ** Otherwise, for non-temporary files, the effective sector size is
48900 ** it is less than 32, or rounded down to MAX_SECTOR_SIZE if it
48901 ** is greater than MAX_SECTOR_SIZE.
48905 ** pPager->sectorSize is to define the "blast radius" of bytes that
48907 ** that range. But with POWERSAFE_OVERWRITE, the blast radius is zero
48908 ** (that is what POWERSAFE_OVERWRITE means), so we minimize the sector
48932 ** The journal file format is as follows:
48935 ** (2) 4 byte big-endian integer which is the number of valid page records
48936 ** in the journal. If this value is 0xffffffff, then compute the
48938 ** (3) 4 byte big-endian integer which is the initial value for the
48940 ** (4) 4 byte integer which is the number of pages to truncate the
48942 ** (5) 4 byte big-endian integer which is the sector size. The header
48943 ** is this many bytes in size.
48944 ** (6) 4 byte big-endian integer which is the page size.
48952 ** Each entry in the journal is an instance of the 8th item.
48954 ** Call the value from the second bullet "nRec". nRec is the number of
48963 ** If the nRec value is 0xffffffff it means that nRec should be computed
48964 ** from the file size. This value is used when the user selects the
48967 ** deleted when the power is restored) we don't care.
48969 ** If the file opened as the journal file is not a well-formed
48971 ** back (or no pages if the journal header is corrupted). The journal file
48972 ** is then deleted and SQLITE_OK returned, just as if no corruption had
48975 ** If an I/O or malloc() error occurs, the journal-file is not deleted
48976 ** and an error code is returned.
48979 ** that might be a hot journal. Or, it could be that the journal is
48981 ** If the journal really is hot, reset the pager cache prior rolling
48982 ** back any content. If the journal is merely persistent, no reset is
48998 ** the journal is empty.
49006 /* Read the master journal name from the journal, if it is present.
49007 ** If a master journal file name is specified, but the file is not
49008 ** present on disk, then the journal is not hot and does not need to be
49011 ** TODO: Technically the following is an error because it assumes that
49012 ** buffer Pager.pTmpSpace is (mxPathname+1) bytes or larger. i.e. that
49014 ** mxPathname is 512, which is the same as the minimum allowable value
49036 ** it is corrupted, then a process must have failed while writing it.
49047 /* If nRec is 0xffffffff, then this journal was created by a process
49057 /* If nRec is 0 and this rollback is of a transaction created by this
49058 ** process and if this is the final header in the journal, then it means
49066 ** when doing a ROLLBACK and the nRec==0 chunk is the last chunk in
49076 /* If this is the first header read from the journal, truncate the
49107 ** first place so it is OK to simply abandon the rollback. */
49136 /* If this playback is happening automatically as a result of an IO or
49163 ** see if it is possible to delete the master journal.
49185 ** file before this function is called.
49187 ** If page 1 is read, then the value of Pager.dbFileVers[] is set to
49190 ** If an IO error occurs, then the IO error is returned to the caller.
49191 ** Otherwise, SQLITE_OK is returned.
49218 /* If the read is unsuccessful, set the dbFileVers[] to something
49219 ** that will never be a valid file version. dbFileVers[] is a copy
49225 ** For an encrypted database, the situation is more complex: bytes
49227 ** white noise equaling 16 bytes of 0xff is vanishingly small so
49251 ** This is an unconditional update. See also the pager_incr_changecounter()
49252 ** routine which only updates the change-counter if the update is actually
49264 ** is valid. */
49271 ** This function is invoked once for each page that has already been
49272 ** written into the log file when a WAL transaction is rolled back.
49273 ** Parameter iPg is the page number of said page. The pCtx argument
49274 ** is actually a pointer to the Pager structure.
49276 ** If page iPg is present in the cache, and has no outstanding references,
49277 ** it is discarded. Otherwise, if there are one or more outstanding
49278 ** references, the page content is reloaded from the database. If the
49279 ** attempt to reload content from the database is required and fails,
49305 /* Normally, if a transaction is rolled back, any backup processes are
49306 ** updated as data is copied out of the rollback journal and into the
49307 ** database. This is not generally possible with a WAL database, as
49319 ** This function is called to rollback a transaction on a WAL database.
49345 ** This function is a wrapper around sqlite3WalFrames(). As well as logging
49350 ** The list of pages passed into this routine is always sorted by page number.
49357 int isCommit /* True if this is a commit */
49366 /* Verify that the page list is in accending order */
49374 /* If a WAL transaction is being committed, there is no point in writing
49430 ** the duplicate call is harmless.
49445 ** This function is called as part of the transition from PAGER_OPEN
49449 ** If no error occurs, SQLITE_OK is returned and the size of the database
49450 ** in pages is stored in *pnPage. Otherwise, an error code (perhaps
49451 ** SQLITE_IOERR_FSTAT) is returned and *pnPage is left unmodified.
49457 ** function returns zero if the WAL is not open (i.e. Pager.pWal==0), or
49458 ** if the database size is not available. The database size is not
49459 ** available from the WAL sub-system if the log file is empty or
49468 /* If the number of pages in the database is not available from the
49470 ** the database file. If the size of the database file is not an
49482 /* If the current number of pages in the file is greater than the
49497 ** exists if the database is not empy, or verify that the *-wal file does
49498 ** not exist (by deleting it) if the database file is empty.
49500 ** If the database is not empty and the *-wal file exists, open the pager
49501 ** in WAL mode. If the database is empty or if no *-wal file exists and
49502 ** if no error occurs, make sure Pager.journalMode is not set to
49508 ** function. Because an EXCLUSIVE lock on the db file is required to delete
49509 ** a WAL on a none-empty database, this ensures there is no race condition
49549 ** a ROLLBACK TO command is invoked on a SAVEPOINT that is a transaction
49552 ** When pSavepoint is not NULL (meaning a non-transaction savepoint is
49559 ** file if PagerSavepoint.iHdrOffset is zero.
49561 ** * If PagerSavepoint.iHdrOffset is not zero, then pages are played
49569 ** Throughout the rollback process, each time a page is rolled back, the
49570 ** corresponding bit is set in a bitvec structure (variable pDone in the
49571 ** implementation below). This is used to ensure that a page is only
49572 ** rolled back the first time it is encountered in either journal.
49574 ** If pSavepoint is NULL, then pages are only played back from the main
49575 ** journal file. There is no need for a bitvec in this case.
49578 ** is reset to the value that it held at the start of the savepoint
49580 ** is played back. If one is encountered it is simply skipped.
49612 ** past pPager->journalOff is off-limits to us.
49649 ** test is related to ticket #2565. See the discussion in the
49744 ** OFF sqlite3OsSync() is never called. This is the default
49747 ** NORMAL The journal is synced once before writes begin on the
49748 ** database. This is normally adequate protection, but
49749 ** it is theoretically possible, though very unlikely,
49752 ** when it is rolled back.
49754 ** FULL The journal is synced twice before writes begin on the
49758 ** single disk sector is atomic, then this mode provides
49762 ** EXTRA This is like FULL except that is also syncs the directory
49764 ** journal is unlinked.
49766 ** The above is for a rollback-journal mode. For WAL mode, OFF continues
49767 ** to mean that no syncs ever occur. NORMAL means that the WAL is synced
49768 ** prior to the start of checkpoint and that the database file is synced
49772 ** file is synced following each commit operation, in addition to the
49773 ** syncs associated with NORMAL. There is no difference between FULL
49779 ** ordinary fsync() call. There is no difference between SQLITE_SYNC_FULL
49782 ** the xSync primitive is called and is relevant to all platforms.
49828 ** The following global variable is incremented whenever the library
49829 ** attempts to open a temporary file. This information is used for
49841 ** delete the temporary file when it is closed.
49886 ** If the busy-handler callback returns non-zero, the lock is
49887 ** retried. If it returns zero, then the SQLITE_BUSY error is
49908 ** is passed in *pPageSize.
49910 ** If the pager is in the error state when this function is called, it
49911 ** is a no-op. The value returned is the error state error code (i.e.
49916 ** * the new page size (value of *pPageSize) is valid (a power
49921 ** * the database is either not an in-memory database or it is
49924 ** then the pager object page size is set to *pPageSize.
49926 ** If the page size is changed, then this function uses sqlite3PagerMalloc()
49928 ** fails, SQLITE_NOMEM is returned and the page size remains unchanged.
49929 ** In all other cases, SQLITE_OK is returned.
49931 ** If the page size is not changed, either because one of the enumerated
49932 ** conditions above is not true, the pager was in error state when this
49934 ** then *pPageSize is set to the old, retained page size before returning.
49939 /* It is not possible to do a full assert_pager_state() here, as this
49941 ** of the Pager object is internally consistent.
49945 ** there is at least one outstanding page reference, this function
49946 ** is a no-op for that case anyhow.
49993 ** by the pager. This is a buffer that is big enough to hold the
49994 ** entire content of a database page. This buffer is used internally
50004 ** Attempt to set the maximum database page count if mxPage is positive.
50005 ** Make no changes if mxPage is zero or negative. And never reduce the
50024 ** Unless -DSQLITE_TEST=1 is used, these routines are all no-ops
50048 ** opened on a file less than N bytes in size, the output buffer is
50049 ** zeroed and SQLITE_OK returned. The rationale for this is that this
50050 ** function is used to read database headers, and a new transient or
50053 ** If any IO error apart from SQLITE_IOERR_SHORT_READ is encountered,
50054 ** the error code is returned to the caller and the contents of the
50062 /* This routine is only called by btree immediately after creating
50079 ** This function may only be called when a read-transaction is open on
50082 ** However, if the file is between 1 and <page-size> bytes in size, then
50083 ** this is considered a 1 page file.
50094 ** a similar or greater lock is already held, this function is a no-op
50098 ** the busy callback if the lock is currently not available. Repeat
50103 ** the lock. If the lock is obtained successfully, set the Pager.state
50109 /* Check that this is either a no-op (because the requested lock is
50127 ** following is true for all dirty pages currently in the page-cache:
50129 ** a) The page number is less than or equal to the size of the
50141 ** content of the page. However, since this content is not present in either
50144 ** database image would become corrupt. It is therefore fortunate that
50163 ** truncation will be done when the current transaction is committed.
50165 ** This function is only called right before committing a transaction.
50167 ** rolled back or committed. It is not safe to call this function and
50178 ** journal so that they can be restored if the savepoint is rolled
50179 ** back. This is no longer necessary as this function is now only
50183 ** is no longer correct. */
50188 ** This function is called before attempting a hot-journal rollback. It
50198 ** If everything goes as planned, SQLITE_OK is returned. Otherwise,
50290 ** If a transaction was in progress when this routine is called, that
50291 ** transaction is rolled back. All outstanding pages are invalidated
50292 ** and their memory is freed. Any attempt to use a page associated
50296 ** This function always succeeds. If a transaction is active an attempt
50297 ** is made to roll it back. If an error occurs during the rollback
50298 ** a hot journal may be left in the filesystem but no error is returned
50318 /* If it is open, sync the journal file before calling UnlockAndRollback.
50319 ** If this is not done, then an unsynced portion of the open journal
50321 ** while this is happening, the database could become corrupt.
50375 ** If the Pager.noSync flag is set, then this function is a no-op.
50379 ** * If the journal file is an in-memory journal file, no action need
50384 ** is updated to contain the number of journal records that have
50385 ** been written following it. If the pager is operating in full-sync
50386 ** mode, then the journal file is synced before this field is updated.
50389 ** journal file is synced.
50403 ** error is encountered, then the IO error code is returned to the caller.
50430 ** occurs after nRec is updated but before this connection writes
50441 ** Variable iNextHdrOffset is set to the offset at which this
50442 ** problematic header will occur, if it exists. aMagic is used
50465 ** all data has really hit the disk before nRec is updated to mark
50468 ** This is not required if the persistent media supports the
50469 ** SAFE_APPEND property. Because in this case it is not possible
50471 ** is populated with 0xFFFFFFFF when the journal header is written
50506 /* Unless the pager is in noSync mode, the journal file was just
50517 ** The argument is the first in a linked list of dirty pages connected
50520 ** be NULL, representing an empty list. In this case this function is
50524 ** is called. Before writing anything to the database file, this lock
50525 ** is upgraded to an EXCLUSIVE lock. If the lock cannot be obtained,
50526 ** SQLITE_BUSY is returned and no data is written to the database file.
50528 ** If the pager is a temp-file pager and the actual file-system file
50529 ** is not yet open, it is created and opened before any data is
50534 ** a page is skipped if it meets either of the following criteria:
50536 ** * The page number is greater than Pager.dbSize, or
50537 ** * The PGHDR_DONT_WRITE flag is set on the page.
50540 ** is updated accordingly. If page 1 is written out, then the value cached
50541 ** in Pager.dbFileVers[] is updated to match the new value stored in
50544 ** If everything is successful, SQLITE_OK is returned. If an IO error
50545 ** occurs, an IO error code is returned. Or, if the EXCLUSIVE lock cannot
50546 ** be obtained, SQLITE_BUSY is returned.
50551 /* This function is only called for rollback pagers in WRITER_DBMOD state. */
50557 /* If the file is a temp-file has not yet been opened, open it now. It
50558 ** is not possible for rc to be other than SQLITE_OK if this branch
50559 ** is taken, as pager_wait_on_lock() is a no-op for temp-files.
50633 ** Ensure that the sub-journal file is open. If it is already open, this
50634 ** function is a no-op.
50636 ** SQLITE_OK is returned if everything goes according to plan. An
50637 ** SQLITE_IOERR_XXX error code is returned if a call to sqlite3OsOpen()
50661 ** This function returns SQLITE_OK if everything is successful, an IO
50712 ** This function is called by the pcache layer when it has reached some
50713 ** soft memory limit. The first argument is a pointer to a Pager object
50714 ** (cast as a void*). The pager is always 'purgeable' (not an in-memory
50715 ** database). The second argument is a reference to a page that is
50717 ** is always associated with the Pager object passed as the first
50720 ** The job of this function is to make pPg clean by writing its contents
50724 ** If successful, sqlite3PcacheMakeClean() is called on the page and
50726 ** page clean, the IO error code is returned. If the page cannot be
50728 ** is returned by sqlite3PcacheMakeClean() is not called.
50737 /* The doNotSpill NOSYNC bit is set during times when doing a sync of
50738 ** journal (and adding a new header) is not allowed. This occurs
50743 ** regardless of whether or not a sync is required. This is set during
50746 ** Spilling is also prohibited when in an error state since that could
50748 ** is impossible for sqlite3PcacheFetch() to be called with createFlag==3
50749 ** while in the error state, hence it is impossible for this routine to
50821 ** The zFilename argument is the path to the database file to open.
50822 ** If zFilename is NULL then a randomly-named temporary file is created
50824 ** automatically when they are closed. If zFilename is ":memory:" then
50825 ** all information is held in cache. It is never written to disk.
50829 ** along with each page reference. This space is available to the user
50832 ** The flags argument is used to specify properties that affect the
50836 ** The vfsFlags parameter is a bitmask to pass to the flags parameter
50839 ** If the pager object is allocated and the specified file opened
50840 ** successfully, SQLITE_OK is returned and *ppPager set to point to
50841 ** the new pager object. If an error occurs, *ppPager is set to NULL
50843 ** (sqlite3Malloc() is used to allocate memory), SQLITE_CANTOPEN or
50859 int memDb = 0; /* True if this is an in-memory file */
50860 int readOnly = 0; /* True if this is a read-only file */
50870 /* Figure out how much space is required for each journal file-handle
50890 ** to by zPathname, length nPathname. Or, if this is a temporary file,
50911 /* This branch is taken when the journal path required by
50927 ** file name. The layout in memory is as follows:
50991 ** database file. The default page size is the maximum of:
51031 /* If a temporary file is requested, it is not opened immediately.
51035 ** This branch is also run for an in-memory database. An in-memory
51036 ** database is the same as a temp-file that is never written out to
51135 ** under the pager. Return SQLITE_OK if the database is still were it ought
51148 /* If the HAS_MOVED file-control is unimplemented, assume that the file
51149 ** has not been moved. That is the historical behavior of SQLite: prior to
51160 ** This function is called after transitioning from PAGER_UNLOCK to
51161 ** PAGER_SHARED state. It tests if there is a hot journal present in
51162 ** the file-system for the given pager. A hot journal is one that
51168 ** * The database file itself is greater than 0 bytes in size, and
51169 ** * The first byte of the journal file exists and is not 0x00.
51171 ** If the current size of the database file is 0 but a journal file
51172 ** exists, that is probably an old journal left over from a prior
51173 ** database with the same name. In this case the journal file is
51174 ** just deleted using OsDelete, *pExists is set to 0 and SQLITE_OK
51175 ** is returned.
51177 ** This routine does not check if there is a master journal filename
51178 ** at the end of the file. If there is, and that master journal file
51179 ** does not exist, then the journal file is not really hot. In this
51181 ** routine will discover that the journal file is not really hot and
51184 ** If a hot-journal file is found to exist, *pExists is set to 1 and
51185 ** SQLITE_OK returned. If no hot-journal file is present, *pExists is
51188 ** code is returned and the value of *pExists is undefined.
51193 int exists = 1; /* True if a journal file is present */
51215 ** is the case, this routine might think there is a hot journal when
51216 ** in fact there is none. This results in a false-positive which will
51226 /* If the database is zero pages in size, that means that either (1) the
51227 ** journal is a remnant from a prior database with the same name where
51229 ** transaction that populates a new database is being rolled back.
51231 ** not to delete the journal file if it is already open due to
51243 ** or greater lock on the database file. Now check that there is
51245 ** If there is, then we consider this journal to be hot. If not,
51266 ** ticket #3883. Either way, assume that the journal is hot.
51267 ** This might be a false positive. But if it is, then the
51284 ** This function is called to obtain a shared lock on the database file.
51285 ** It is illegal to call sqlite3PagerGet() until after this function
51286 ** has been successfully called. If a shared-lock is already held when
51287 ** this function is called, it is a no-op.
51291 ** 1) If the pager is currently in PAGER_OPEN state (no lock held
51292 ** on the database file), then an attempt is made to obtain a
51294 ** the SHARED lock, the file-system is checked for a hot-journal,
51295 ** which is played back if present. Following any hot-journal
51300 ** 2) If the pager is running in exclusive-mode, and there are currently
51301 ** no outstanding references to any pages, and is in the error state,
51302 ** then an attempt is made to clear the error state by discarding
51306 ** If everything is successful, SQLITE_OK is returned. If an IO error
51308 ** rolling back a journal file, the IO error code is returned.
51313 /* This routine is only called from b-tree and only when there are no
51315 ** be OPEN or READER. READER is only possible if the pager is or was in
51334 /* If a journal file exists, and there is no RESERVED lock on the
51349 /* Get an EXCLUSIVE lock on the database file. At this point it is
51350 ** important that a RESERVED lock is not obtained on the way to the
51353 ** database is safe to read while this process is still rolling the
51356 ** Because the intermediate RESERVED lock is not requested, any
51361 ** Unless the pager is in locking_mode=exclusive mode, the lock is
51369 /* If it is not already open and the file exists on disk, open the
51370 ** journal for read/write access. Write access is required because
51373 ** is usually required to finalize the journal in journal_mode=persist
51420 /* This branch is taken if an error occurs while trying to open
51428 ** PAGER_ERROR now. This is not actually counted as a transition
51455 ** a 32-bit counter that is incremented with each change. The
51457 ** a codec is in use.
51459 ** There is a vanishingly small chance that a change will not be
51460 ** detected. The chance of an undetected change is so small that
51482 /* Unmap the database file. It is possible that external processes
51486 ** to be the right size but is not actually valid. Avoid this
51494 /* If there is a WAL file in the file-system, open this database in WAL
51495 ** mode. Otherwise, the following function call is a no-op.
51528 ** Except, in locking_mode=EXCLUSIVE when there is nothing to in
51529 ** the rollback journal, the unlock is not performed and there is
51530 ** nothing to rollback, so this routine is a no-op.
51540 ** reference has type DbPage*). If the requested reference is
51541 ** successfully obtained, it is copied to *ppPage and SQLITE_OK returned.
51543 ** If the requested page is already in the cache, it is returned.
51544 ** Otherwise, a new page object is allocated and populated with data
51549 ** The extra data appended to a page is always initialized to zeros the
51550 ** first time a page is loaded into memory. If the page requested is
51551 ** already in the cache when this function is called, then the extra
51552 ** data is left as it was when the page object was last used.
51554 ** If the database image is smaller than the requested page or if a
51555 ** non-zero value is passed as the noContent parameter and the
51556 ** requested page is not already stored in the cache, then no
51558 ** page is initialized to all zeros.
51560 ** If noContent is true, it means that we do not care about the contents
51565 ** b) When a savepoint is being rolled back and we need to load
51569 ** If noContent is true, then the data returned is zeroed instead of
51573 ** savepoints are set. This means if the page is made writable at any
51578 ** an appropriate error code is returned and *ppPage is set to NULL.
51581 ** to find a page in the in-memory cache first. If the page is not already
51599 /* It is acceptable to use a read-only (mmap) page for any page except
51600 ** page 1 if there is no write-transaction open or the ACQUIRE_READONLY
51601 ** flag was specified by the caller. And so long as the db is not a
51613 ** common case where pgno is large. */
51623 /* If the pager is in the error state, return an error immediately.
51701 /* The maximum page number is 2^31. Return SQLITE_CORRUPT if a page
51702 ** number greater than this, or the unused locking-page, is requested. */
51715 /* Failure to set the bits in the InJournal bit-vectors is benign.
51761 ** Acquire a page if it is already in the in-memory cache. Do
51763 ** or 0 if the page is not in cache.
51766 ** and sqlite3PagerGet() is that _get() will go to the disk and read
51767 ** in the page if the page is not already in cache. This routine
51768 ** returns NULL if the page is not in cache or if a disk I/O error
51786 ** page is added to the LRU list. When all references to all pages
51787 ** are released, a rollback occurs and the lock on the database is
51806 ** This function is called at the start of every write transaction.
51808 ** file when this routine is called.
51812 ** as well. This function is only used when the journal file is being
51813 ** opened to write a rollback log for a transaction. It is not used
51816 ** If the journal file is already open (as it may be in exclusive mode),
51820 ** Whether or not the journal file is opened by this function, the
51821 ** Pager.pInJournal bitvec structure is allocated.
51823 ** Return SQLITE_OK if everything is successful. Otherwise, return
51835 /* If already in the error state, this function is a no-op. But on
51836 ** the other hand, this routine is never called if we are already in
51846 /* Open the journal file if it is not already open. */
51901 ** write-transaction has already been opened, this function is a no-op.
51903 ** If the exFlag argument is false, then acquire at least a RESERVED
51904 ** lock on the database file. If exFlag is true, then acquire at least
51905 ** an EXCLUSIVE lock. If such a lock is already held, no locking
51908 ** If the subjInMemory argument is non-zero, then any sub-journal opened
51910 ** has no effect if the sub-journal is already opened (as it may be when
51912 ** sub-journal. If the subjInMemory argument is zero, then any required
51913 ** sub-journal is implemented in-memory if pPager is an in-memory database,
51927 /* If the pager is configured to use locking_mode=exclusive, and an
51928 ** exclusive lock on the database is not already held, obtain it now.
51940 ** The busy-handler is not invoked if another connection already
51946 ** is true, then immediately upgrade this to an EXCLUSIVE lock. The
51961 ** This is because in those states the code to roll back savepoint
52003 ** Otherwise, when the transaction is rolled back, the logic in
52036 ** Mark a single data page as writeable. The page is written into the
52037 ** main journal or sub-journal as required. If the page is written into
52038 ** one of the journals, the corresponding bit is set in the
52046 /* This routine is not called unless a write-transaction has already
52048 ** It is never called in the ERROR state.
52061 ** rollback journal might not yet be open. Open it now if this is the case.
52063 ** This is done before calling sqlite3PcacheMakeDirty() on the page.
52075 /* Mark the page that is about to be modified as dirty. */
52078 /* If a rollback journal is in use, them make sure the page that is about
52079 ** to change is in the rollback journal, or if the page is a new page off
52080 ** then end of the file, make sure it is marked as PGHDR_NEED_SYNC.
52102 /* The PGHDR_DIRTY bit is set above when the page was added to the dirty-list
52109 /* If the statement journal is open and the page is not in it,
52124 ** This is a variant of sqlite3PagerWrite() that runs when the sector size
52125 ** is larger than the page size. SQLite makes the (reasonable) assumption that
52130 ** Usually, the sector size is less than or equal to the page size, in which
52132 ** exceptional case where the page size is smaller than the sector size.
52137 Pgno pg1; /* First page of the sector pPg is located on. */
52144 /* Set the doNotSpill NOSYNC bit to 1. This is because we cannot allow
52154 ** of the first page of the sector pPg is located on.
52192 /* If the PGHDR_NEED_SYNC flag is set for any of the nPage pages
52220 ** The difference between this function and pager_write() is that this
52225 ** If an error occurs, SQLITE_NOMEM or an IO error code is returned
52248 ** to sqlite3PagerWrite(). In other words, return TRUE if it is ok
52258 ** A call to this routine tells the pager that it is not necessary to
52265 ** on the given page is unused. The pager marks the page as clean so
52275 ** current transaction is rolled back.
52290 ** This routine is called to increment the value of the database file
52293 ** 92 is also updated, as is the SQLite version number at offset 96.
52295 ** But this only happens if the pPager->changeCountDone flag is false.
52300 ** If the isDirectMode flag is zero, then this is done by calling
52303 ** transaction is committed.
52307 ** if isDirect is non-zero, then the database file is updated directly
52320 ** atomic-write optimization is enabled in this build, then isDirect
52321 ** is initialized to the value passed as the isDirectMode parameter
52322 ** to this function. Otherwise, it is always set to zero.
52324 ** The idea is that if the atomic-write optimization is not
52346 /* If page one was fetched successfully, and this function is not
52348 ** direct mode, page 1 is always held in cache and hence the PagerGet()
52349 ** above is always successful - hence the ALWAYS on rc==SQLITE_OK.
52370 ** next time a read transaction is opened the cache will be
52388 ** Sync the database file to disk. This is a no-op for in-memory databases
52391 ** If successful, or if called on a pager for which it is a no-op, this
52392 ** function returns SQLITE_OK. Otherwise, an IO error code is returned.
52410 ** This function may only be called while a write-transaction is active in
52411 ** rollback. If the connection is in WAL mode, this call is a no-op.
52413 ** the database file, an attempt is made to obtain one.
52415 ** If the EXCLUSIVE lock is already held or the attempt to obtain it is
52416 ** successful, or the connection is in WAL mode, SQLITE_OK is returned.
52417 ** Otherwise, either SQLITE_BUSY or an SQLITE_IOERR_XXX error code is
52439 ** journal file. zMaster may be NULL, which is interpreted as no master
52444 ** * The database file change-counter is updated,
52445 ** * the journal is synced (unless the atomic-write optimization is used),
52447 ** * the database file is truncated (if required), and
52450 ** The only thing that remains to commit the transaction is to finalize
52457 ** If the final parameter - noSync - is true, then the database file itself
52458 ** is not synced. The caller must call sqlite3PagerSync() directly to
52491 /* If this is an in-memory db, or no pages have been written to, or this
52492 ** function has already been called, it is mostly a no-op. However, any
52522 ** * This commit is not part of a multi-file transaction, and
52526 ** pager_incr_changecounter() function is called to update the change
52527 ** counter in 'indirect-mode'. If the optimization is compiled in but
52528 ** is not applicable to this transaction, call sqlite3JournalCreate()
52533 ** Otherwise, if the optimization is both enabled and applicable,
52553 ** property of the host file-system, this is safe.
52569 ** or if zMaster is NULL (no master journal), then this call is a no-op.
52575 ** If the atomic-update optimization is being used, this sync will not
52579 ** atomic-update optimization is used it is almost certain that the
52581 ** on a system under memory pressure it is just possible that this is
52582 ** not the case. In this case it is likely enough that the redundant
52595 /* If the file on disk is smaller than the database image, use
52599 ** last page is never written out to disk, leaving the database file
52600 ** undersized. Fix this now if it is the case. */
52625 ** When this function is called, the database file has been completely
52633 ** for hot-journal rollback. Once this is done the transaction is
52636 ** If an error occurs, an IO error code is returned and the pager
52637 ** moves into the error state. Otherwise, SQLITE_OK is returned.
52654 ** this transaction, the pager is running in exclusive-mode and is
52655 ** using persistent journals, then this function is a no-op.
52658 ** header with the nRec field set to 0. If such a journal is used as
52660 ** to the database file. So there is no need to zero the journal
52661 ** header. Since the pager is in exclusive mode, there is no need
52680 ** If a write transaction is open, then all changes made within the
52681 ** transaction are reverted and the current write-transaction is closed.
52685 ** If the pager is already in PAGER_ERROR state when this function is called,
52686 ** it returns Pager.errCode immediately. No work is performed in this case.
52694 ** 2) It finalizes the journal file, so that it is not used for hot
52697 ** Finalization of the journal file (task 2) is only performed if the
52698 ** rollback is successful.
52703 ** WAL files. The WAL transaction is then closed.
52709 /* PagerRollback() is a no-op if called in READER or OPEN state. If
52710 ** the pager is already in the ERROR state, the rollback is not
52711 ** attempted here. Instead, the error code is returned to the caller.
52751 ** Return TRUE if the database file is opened read-only. Return FALSE
52752 ** if the database is (in theory) writable.
52788 ** This routine is used for testing and analysis only.
52809 ** SQLITE_DBSTATUS_CACHE_MISS. Before returning, *pnVal is incremented by the
52811 ** reset parameter is non-zero, the cache hit or miss count is zeroed before
52832 ** Return true if this is an in-memory or temp-file backed pager.
52841 ** to make up the difference. If the number of savepoints is already
52842 ** equal to nSavepoint, then this function is a no-op.
52844 ** If a memory allocation fails, SQLITE_NOMEM is returned. If an error
52845 ** occurs while opening the sub-journal file, then an IO error code is
52906 ** This function is called to rollback or release (commit) a savepoint.
52910 ** Parameter op is always either SAVEPOINT_ROLLBACK or SAVEPOINT_RELEASE.
52911 ** If it is SAVEPOINT_RELEASE, then release and destroy the savepoint with
52912 ** index iSavepoint. If it is SAVEPOINT_ROLLBACK, then rollback all changes
52915 ** The savepoint to rollback or release is identified by parameter
52918 ** on the most recently created savepoint. If iSavepoint is greater than
52919 ** (Pager.nSavepoint-1), then this function is a no-op.
52921 ** If a negative value is passed to this function, then the current
52922 ** transaction is rolled back. This is different to calling
52928 ** are destroyed. If this is a release operation (op==SAVEPOINT_RELEASE),
52929 ** then savepoint iSavepoint is also destroyed.
52933 ** savepoint. If no errors occur, SQLITE_OK is returned.
52955 /* If this is a release of the outermost savepoint, truncate
52959 /* Only truncate if it is an in-memory sub-journal. */
52967 /* Else this is a rollback operation, playback the specified savepoint.
52968 ** If this is a temp-file, it is possible that the journal file has
52985 ** Except, if the pager is in-memory only, then return an empty string if
52986 ** nullIfMemDb is true. This routine is called with nullIfMemDb==1 when
53054 ** This function is called by the wal module when writing page content
53079 ** pgno (which we call pPgOld) though that page is allowed to be
53080 ** in cache. If the page previously located at pgno is not already
53081 ** in the rollback journal, it is not put there by by this routine.
53085 ** allocated along with the page) is the responsibility of the caller.
53087 ** A transaction must be active when this routine is called. It used to be
53090 ** transaction is active).
53092 ** If the fourth argument, isCommit, is non-zero, then this page is being
53094 ** is being committed. In this case, it is guaranteed that the database page
53102 Pgno needSyncPgno = 0; /* Old value of pPg->pgno, if sync is required */
53121 /* If the page being moved is dirty and has not been saved by the latest
53123 ** sub-journal now. This is required to handle the following scenario:
53133 ** statement were is processed.
53136 ** one or more savepoint bitvecs. This is the reason this function
53152 ** If the isCommit flag is set, there is no need to remember that
53196 /* If needSyncPgno is non-zero, then the journal file needs to be
53197 ** sync()ed before any data is written to database file page needSyncPgno.
53199 ** "is journaled" bitvec flag has been set. This needs to be remedied by
53205 ** array. Otherwise, if the page is loaded and written again in
53207 ** it is synced into the journal file. This way, it may end up in
53208 ** the journal file twice, but that is not a problem.
53259 ** PAGER_LOCKINGMODE_EXCLUSIVE. If the parameter is not _QUERY, then
53260 ** the locking-mode is set to the value specified.
53262 ** The returned value is either PAGER_LOCKINGMODE_NORMAL or
53289 ** The journalmode is set to the value specified if the change is allowed.
53303 /* The print_pager_state() routine is intended to be used by the debugger
53309 /* The eMode parameter is always valid */
53317 /* This routine is only called from the OP_JournalMode opcode, and
53340 ** mode except WAL, unless the pager is in locking_mode=exclusive mode,
53353 /* In this case we would like to delete the journal file. If it is
53354 ** not possible, then that is not a problem. Deleting the journal file
53355 ** here is an optimization only.
53358 ** database file. This ensures that the journal file is not deleted
53359 ** while it is in use by some other client.
53402 ** Return TRUE if the pager is in a state where it is OK to change the
53404 ** is unmodified.
53416 ** Setting the size limit to -1 means no limit is enforced.
53417 ** An attempt to set a limit smaller than -1 is a no-op.
53439 ** Unless this is an in-memory or temporary database, clear the pager cache.
53450 ** This function is called when the user invokes "PRAGMA wal_checkpoint",
53454 ** Parameter eMode is one of SQLITE_CHECKPOINT_PASSIVE, FULL or RESTART.
53485 ** is obtained instead, immediately release it.
53502 ** Call sqlite3WalOpen() to open the WAL handle. If the pager is in
53503 ** exclusive-locking mode when this function is called, take an EXCLUSIVE
53513 /* If the pager is already in exclusive-mode, the WAL module will use
53516 ** file, to make sure this is safe.
53541 ** If the pager passed as the first argument is open on a real database
53543 ** is not already open, make an attempt to open it now. If successful,
53545 ** not support the xShmXXX() methods, return an error code. *pbOpen is
53548 ** If the pager is open on a temp-file (or in-memory database), or if
53549 ** the WAL file is already open, set *pbOpen to 1 and return SQLITE_OK
53554 int *pbOpen /* OUT: Set to true if call is a no-op */
53583 ** This function is called to close the connection to the log file prior
53588 ** error (SQLITE_BUSY) is returned and the log connection is not closed.
53589 ** If successful, the EXCLUSIVE lock is not released before returning.
53596 /* If the log file is not already open, but does exist in the file-system,
53613 /* Checkpoint and close the log. Because an EXCLUSIVE lock is held on
53631 ** If this is a WAL database, obtain a snapshot handle for the snapshot
53643 ** If this is a WAL database, store a pointer to pSnapshot. Next time a
53644 ** read transaction is opened, attempt to read from the snapshot it
53645 ** identifies. If this is not a WAL database, return an error.
53661 ** A read-lock must be held on the pager when this function is called. If
53662 ** the pager is in WAL mode and the WAL file currently contains one or more
53664 ** WAL frames. Otherwise, if this is not a WAL database or the WAL file
53665 ** is empty, return 0.
53681 ** a legal notice, here is a blessing:
53697 ** frames into the WAL. Transactions commit when a frame is written that
53699 ** multiple transactions. Periodically, the content of the WAL is
53710 ** The WAL header is 32 bytes in size and consists of the following eight
53724 ** of page data. The frame-header is six big-endian 32-bit unsigned
53735 ** A frame is considered valid if and only if the following conditions are
53746 ** The checksum is computed using 32-bit big-endian integers if the
53747 ** magic number in the first 4 bytes of the WAL is 0x377f0683 and it
53748 ** is computed using little-endian if the magic number is 0x377f0682.
53750 ** big-endian format regardless of which byte order is used to compute
53751 ** the checksum. The checksum is computed by interpreting the input as
53753 ** algorithm used for the checksum is as follows:
53765 ** On a checkpoint, the WAL is first VFS.xSync-ed, then valid content of the
53766 ** WAL is transferred into the database, then the database is VFS.xSync-ed.
53771 ** After each checkpoint, the salt-1 value is incremented and the salt-2
53772 ** value is randomized. This prevents old and new frames in the WAL from
53780 ** last valid instance of page P that is a followed by a commit frame
53781 ** or is a commit frame itself becomes the value read. If the WAL
53783 ** frame or are followed by a commit frame, then page P is read from
53798 ** WAL is large (multiple megabytes is typical) that scan can be slow,
53800 ** data structure called the wal-index is maintained to expedite the
53805 ** Conceptually, the wal-index is shared memory, though VFS implementations
53807 ** the wal-index is shared memory, SQLite does not support journal_mode=WAL
53811 ** The wal-index is transient. After a crash, the wal-index can (and should
53812 ** be) reconstructed from the original WAL file. In fact, the VFS is required
53814 ** connection to it closes. Because the wal-index is transient, it can
53820 ** The purpose of the wal-index is to answer this question quickly: Given
53841 ** The page-mapping is an array of HASHTABLE_NPAGE (or HASHTABLE_NPAGE_ONE
53862 ** HASHTABLE_NSLOT = 2*HASHTABLE_NPAGE, and there is one entry in the
53864 ** table is never more than half full. The expected number of collisions
53865 ** prior to finding a match is 1. Each entry of the hash table is an
53879 ** (wrapping around to the beginning when the end of the hash table is
53880 ** reached) until an unused hash slot is found. Let the first unused slot
53882 ** wrap-around.) Because the hash table is never more than half full,
53883 ** the search is guaranteed to eventually hit an unused entry. Let
53885 ** where aHash[iMax]==P. If there is no iMax entry (if there exists
53886 ** no hash slot such that aHash[i]==p) then page P is not in the
53900 ** is much faster than scanning the entire 10MB WAL.
53911 ** in the first place - which is what reader one wants. Meanwhile, the
53913 ** later, which is exactly what reader two wants.
53915 ** When a rollback occurs, the value of K is decreased. Hash table entries
53938 ** values in the wal-header are correct and (b) the version field is not
53942 ** checksum test is successful) and finds that the version field is not
53943 ** WALINDEX_MAX_VERSION, then no read-transaction is opened and SQLite
53950 ** Indices of various locking bytes. WAL_NREADER is the number
53952 ** is SQLITE_SHM_NLOCK==8 and WAL_NREADER==5.
53975 ** the total header size is 136 bytes.
54000 ** nBackfill is the number of frames in the WAL that have been written
54002 ** database "backfilling".) The nBackfill number is never greater than
54006 ** mxFrame back to zero when the WAL is reset.
54008 ** nBackfillAttempted is the largest value of nBackfill that a checkpoint
54010 ** the nBackfillAttempted is set before any backfilling is done and the
54011 ** nBackfill is only set after all backfilling completes. So if a checkpoint
54015 ** The aLock[] field is a set of bytes used for locking. These bytes should
54018 ** There is one entry in aReadMark[] for each reader lock. If a reader
54019 ** holds read-lock K, then the value in aReadMark[K] is no greater than
54021 ** for any aReadMark[] means that entry is unused. aReadMark[0] is
54022 ** a special case; its value is never used and it exists as a place-holder
54028 ** is holding an exclusive lock on WAL_READ_LOCK(K). Thus, the value of
54029 ** aReadMark[K] cannot changed while there is a reader is using that mark
54033 ** the frame numbers are less than or equal to every aReadMark[] that is
54034 ** in use (that is, every aReadMark[j] for which there is a corresponding
54037 ** is not already an aReadMark[] equal to mxFrame. The exception to the
54038 ** previous sentence is when nBackfill equals mxFrame (meaning that everything
54065 ** WALINDEX_LOCK_OFFSET is reserved for locks. Since some systems
54080 ** significant bit also set (WAL_MAGIC | 0x00000001) is stored in 32-bit
54083 ** If the LSB is set, then the checksums for each frame within the WAL
54093 ** is to the start of the write-ahead log frame-header.
54100 ** An open write-ahead log file is represented by an instance of the
54113 i16 readLock; /* Which read lock is being held. -1 for none */
54115 u8 exclusiveMode; /* Non-zero if connection is in exclusive mode */
54146 #define WAL_RDONLY 1 /* The WAL file is readonly */
54147 #define WAL_SHM_RDONLY 2 /* The SHM file is readonly */
54156 ** This structure is used to implement an iterator that loops through
54168 ** This functionality is used by the checkpoint code (see walCheckpoint()).
54184 ** is a hash-table following every HASHTABLE_NPAGE page numbers in the
54196 ** wal-index is smaller than usual. This is so that there is a complete
54201 /* The wal-index is divided into pages of WALINDEX_PGSZ bytes each. */
54208 ** is broken into pages of WALINDEX_PGSZ bytes. Wal-index pages are
54211 ** If this call is successful, *ppPage is set to point to the wal-index
54212 ** page and SQLITE_OK is returned. If an error (an OOM or VFS error) occurs,
54213 ** then an SQLite error code is returned and *ppPage is set to 0.
54287 ** The checksum is written back into aOut[] before returning.
54338 ** The checksum on pWal->hdr is updated before it is written.
54355 ** supplied by the caller. A frame-header is made up of a series of
54394 ** in aData[] is valid. If it is a valid frame, fill *piPage and
54395 ** *pnTruncate and return true. Return if the frame is not valid.
54409 /* A frame is only valid if the salt values in the frame-header
54416 /* A frame is only valid if the page number is creater than zero.
54423 /* A frame is only valid if a checksum of the WAL header,
54438 /* If we reach this point, the frame is valid. Return the page number
54449 ** Names of locks. This routine is used to provide debugging output and is not
54526 ** page iHash of the wal-index. The wal-index is broken into 32KB pages
54532 ** slot in the hash table is set to N, it refers to frame number
54535 ** Finally, set *paPgno so that *paPgno[1] is the page number of the
54573 ** iFrame. The wal-index is broken up into 32KB pages. Wal-index pages
54602 ** This function is called whenever pWal->hdr.mxFrame is decreased due
54626 ** the entry that corresponds to frame pWal->hdr.mxFrame. It is guaranteed
54627 ** that the page said hash-table and array reside on is already mapped.
54651 /* Verify that the every entry in the mapping region is still reachable
54691 /* If this is the first entry to be added to this hash-table, zero the
54699 /* If the entry in aPgno[] is already set, then the previous writer
54729 /* Verify that the every entry in the mapping region is reachable
54756 ** with the WAL or wal-index while recovery is running. The
54757 ** WAL_RECOVER_LOCK is also held so that other threads will know
54758 ** that this thread is running recovery. If unable to establish
54769 ** locked by the caller. The caller is guaranteed to have locked the
54803 int isValid; /* True if this frame is valid */
54811 /* If the database page size is not a power of two, or is greater than
54813 ** data. Similarly, if the 'magic' value is invalid, ignore the whole
54830 /* Verify that the WAL header checksum is correct */
54840 /* Verify that the version number on the WAL format is one that
54872 /* If nTruncate is non-zero, this is a commit record. */
54895 /* Reset the checkpoint-header. This is safe because this thread is
54907 ** event via sqlite3_log(). This is to help with identifying performance
54946 ** is called. The purpose of this SHARED lock is to prevent any other
54951 ** If the log file is successfully opened, SQLITE_OK is returned and
54952 ** *ppWal is set to point to a new WAL handle. If an error occurs,
54953 ** an SQLite error code is returned and *ppWal is left unmodified.
54974 ** value of 120, we need to know that so there is an assert() to check it.
55027 ** Change the size to which the WAL file is trucated on each reset.
55049 u32 iRet = 0xFFFFFFFF; /* 0xffffffff is never a valid page number */
55076 ** aLeft[] and aRight[] are arrays of indices. The sort key is
55078 ** is guaranteed for all J<K:
55086 ** above is still met.
55227 ** returns an error, the value of *pp is undefined.
55242 ** it only runs if there is actually content in the log (mxFrame>0).
55310 ** n. If the attempt fails and parameter xBusy is not NULL, then it is a
55312 ** lock is successfully obtained or the busy-handler returns 0.
55337 ** The following is guaranteed when this function is called:
55339 ** a) the WRITER lock is held,
55349 ** The value of parameter salt1 is used as the aSalt[1] value in the
55378 ** SQLite is in WAL-mode in synchronous=NORMAL. That means that if
55382 ** Fsync is called on the WAL before writing content out of the WAL and
55383 ** into the database. This ensures that if the new content is persistent
55386 ** Fsync is also called on the database file if (and only if) the entire
55387 ** WAL content is copied into the database file. This second fsync makes
55392 ** This is the only routine that will increase the value of nBackfill.
55397 ** checkpoint is running (in any other thread or process) at the same
55431 /* EVIDENCE-OF: R-62920-47450 The busy-handler callback is never invoked
55435 /* Compute in mxSafeFrame the index of the last frame of the WAL that is
55443 /* Thread-sanitizer reports that the following is an unsafe read,
55445 ** of the aReadMark[] slot. The assumption here is that if that is
55448 ** "new" version of the value is read, and not some arbitrary value
55535 /* If this is an SQLITE_CHECKPOINT_RESTART or TRUNCATE operation, and the
55578 ** If the WAL file is currently larger than nMax bytes in size, truncate
55610 ** connection associated with this log file is the only connection to
55614 ** The EXCLUSIVE lock is not released before returning.
55637 ** WAL mode (bPersist) and if the PRAGMA journal_size_limit is a
55662 ** there is a problem.
55664 ** The wal-index is in shared memory. Another thread or process might
55665 ** be writing the header at the same time this procedure is trying to
55666 ** read it, which might result in inconsistency. A dirty read is detected
55670 ** If and only if the read is consistent and the header is different from
55671 ** pWal->hdr, then pWal->hdr is updated to the content of the new header
55672 ** and *pChanged is set to 1.
55675 ** is read successfully and the checksum verified, return zero.
55687 ** meaning it is possible that an inconsistent snapshot is read
55728 ** Set *pChanged to 1 if the wal-index header value in pWal->hdr is
55729 ** changed by this operation. If pWal->hdr is unchanged, set *pChanged
55732 ** If the wal-index header is successfully read, return SQLITE_OK.
55741 ** wal-index header) is mapped. Return early if an error occurs here.
55752 ** works, but may fail if the wal-index header is corrupt or currently
55772 /* If the wal-index header is still malformed even while holding
55773 ** a WRITE lock, it can only mean that the header is corrupted and
55785 /* If the header is read successfully, check the version number to make
55797 ** This is the value that walTryBeginRead returns when it needs to
55805 ** indicate to the caller that it is safe to retry immediately.
55808 ** I/O error or an SQLITE_BUSY because another process is running
55811 ** The useWal parameter is true to force the use of the WAL and disable
55812 ** the case where the WAL is bypassed because it has been completely
55815 ** wal-index header has changed, *pChanged is set to 1 (as an indication
55816 ** to the caller that the local paget cache is obsolete and needs to be
55817 ** flushed.) When useWal==1, the wal-index header is assumed to already
55818 ** be loaded and the pChanged parameter is unused.
55826 ** and is not honoring the locking protocol. There is a vanishingly small
55828 ** bad luck when there is lots of contention for the wal-index, but that
55829 ** possibility is so small that it can be safely neglected, we believe.
55832 ** WAL_READ_LOCK(pWal->readLock). The pWal->readLock integer is
55835 ** access any database page that is modified by a WAL frame up to and
55840 ** If the useWal parameter is 1 then the WAL will never be ignored and
55842 ** When the read transaction is completed, the caller must release the
55862 /* Take steps to avoid spinning forever if there is a protocol error.
55867 ** if we are unlucky, another process that is holding a lock might get
55868 ** paged out or take a page-fault that is time-consuming to resolve,
55869 ** during the few nanoseconds that it is holding the lock. In that case,
55874 ** is more of a scheduler yield than an actual delay. But on the 10th
55877 ** The total delay time before giving up is less than 10 seconds.
55892 /* If there is not a recovery running in another thread or process
55893 ** then convert BUSY errors to WAL_RETRY. If recovery is known to
55894 ** be running, convert BUSY to BUSY_RECOVERY. There is a race here
55896 ** would be technically correct. But the race is benign since with
55901 /* This branch is taken when the xShmMap() method returns SQLITE_BUSY.
55902 ** We assume this is a transient condition, so return WAL_RETRY. The
55906 ** must be zeroed before the requested page is returned.
55928 /* The WAL has been completely backfilled (or it is empty).
55935 /* It is not safe to allow the reader to continue here if frames
55940 ** happening, this is usually correct.
55943 ** is wrapped and written for that matter) before the READ_LOCK(0)
55944 ** is obtained, that is not necessarily true. A checkpointer may
55959 ** the WAL to get at content from recent commits. The job now is
55960 ** to select one of the aReadMark[] entries that is closest to
56007 ** It is necessary to check that the wal-index header did not change
56023 ** Because a ShmBarrier() call is made between taking the copy of
56025 ** matches the one cached in pWal->hdr, it is guaranteed that the
56030 ** A) on the basis that there is a newer version (version B) of the same
56058 ** that extra content is ignored by the current thread.
56061 ** transaction, then *pChanged is set to 1 before returning. The
56062 ** Pager layer will use this to know that is cache is stale and
56090 ** is populated with the wal-index header corresponding to the head
56091 ** of the wal file. Verify that pSnapshot is still valid before
56106 /* It is possible that there is a checkpointer thread running
56107 ** concurrent with this code. If this is the case, it may be that the
56109 ** snapshot X, where X is later in the wal file than pSnapshot, but
56112 ** there is no checkpointer process by taking a shared CKPT lock
56148 ** Finish with a read transaction. All this does is release the
56161 ** contains the page. Otherwise, if pgno is not in the wal file, set *piRead
56165 ** error does occur, the final value of *piRead is undefined.
56177 /* This routine is only be called from within a read transaction. */
56180 /* If the "last page" field of the wal-index header snapshot is 0, then
56183 ** then the WAL is ignored by the reader so return early, as if the
56206 ** loop of the following block is more stringent that would be required
56266 ** (which is nOut bytes in size). Return SQLITE_OK if successful, or an
56304 ** the read transaction was started, then it is not possible for this
56306 ** returns SQLITE_BUSY in that case and no write transaction is started.
56333 ** the write is disallowed.
56362 ** Additionally, the callback function is invoked for each frame written
56364 ** other than SQLITE_OK, it is not invoked again and the error code is
56386 ** is passed as the second argument is (a) in the cache and
56387 ** (b) has an outstanding reference, then xUndo is either a no-op
56388 ** (if (a) is false) or simply expels the page from the cache (if (b)
56389 ** is false).
56391 ** If the upper layer is doing a rollback, it is guaranteed that there
56393 ** page 1 is never written to the log until the transaction is
56450 ** This function is called just before writing a set of frames to the log
56452 ** to the current log file, it is possible to overwrite the start of the
56454 ** it sets pWal->hdr.mxFrame to 0. Otherwise, pWal->hdr.mxFrame is left
56457 ** SQLITE_OK is returned if no error is encountered (regardless of whether
56458 ** or not pWal->hdr.mxFrame is modified). An SQLite error code is returned
56479 ** at this point. But updating the actual wal-index header is also
56480 ** safe and means there is no special case for sqlite3WalUndo()
56481 ** to handle if this transaction is rolled back. */
56520 ** In other words, if iSyncPoint is in between iOffset and iOffset+iAmt,
56572 ** This function is called as part of committing a transaction within which
56577 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
56591 ** first checksum. If the first frame is frame 1 (implying that the current
56633 int isCommit, /* True if this is a commit */
56666 /* See if it is possible to write these frames into the start of the
56673 /* If this is the first frame written into the log, write the WAL
56704 /* Sync the header (unless SQLITE_IOCAP_SEQUENTIAL is true or unless
56705 ** all syncing is turned off by PRAGMA synchronous=OFF). Otherwise
56734 ** checksums must be recomputed when the transaction is committed. */
56773 /* If this is the end of a transaction, then we might need to pad
56780 ** If SQLITE_IOCAP_POWERSAFE_OVERWRITE is defined, then padding is not
56781 ** needed and only the sync is done. If padding is needed, then the
56782 ** final frame is repeated (with its commit mark) until the next sector
56783 ** boundary is crossed. Only the part of the WAL prior to the last
56784 ** sector boundary is synced; the part of the last frame that extends
56785 ** past the sector boundary is written after the sync.
56808 ** if PRAGMA journal_size_limit is set, then truncate the WAL to the
56820 /* Append data to the wal-index. It is not necessary to lock the
56823 ** be in use by existing readers is being overwritten.
56847 /* If this is a commit, update the wal-index header too. */
56859 ** This routine is called to implement sqlite3_wal_checkpoint() and
56865 ** If parameter xBusy is not NULL, it is a pointer to a busy-handler
56880 int isChanged = 0; /* True if a new wal-index header is loaded */
56887 /* EVIDENCE-OF: R-62920-47450 The busy-handler callback is never invoked
56898 /* EVIDENCE-OF: R-10421-19736 If any other process is running a
56900 ** SQLITE_BUSY is returned.
56901 ** EVIDENCE-OF: R-53820-33897 Even if there is a busy-handler configured,
56915 ** immediately, and a busy-handler is configured, it is invoked and the
56917 ** lock is successfully obtained.
56956 ** performed, then the pager-cache associated with pWal is now
56987 ** This function is called to change the WAL subsystem into or out
56990 ** If op is zero, then attempt to change from locking_mode=EXCLUSIVE
56992 ** on the pWal->readLock byte. If the WAL is already in locking_mode=NORMAL
56994 ** transition out of exclusive-mode is successful, return 1. This
56995 ** operation must occur while the pager is still holding the exclusive
56998 ** If op is one, then change from locking_mode=NORMAL into
57000 ** be released. Return 1 if the transition is made and 0 if the
57001 ** WAL is already in exclusive-locking mode - meaning that this
57002 ** routine is a no-op. The pager must already hold the exclusive lock
57005 ** If op is negative, then do a dry-run of the op==1 case but do
57015 /* pWal->readLock is usually set, but might be -1 if there was a
57017 ** happen if the connection is actually in exclusive mode (as no xShmLock
57048 ** Return true if the argument is non-NULL and the WAL module is using
57049 ** heap-memory for the wal-index. Otherwise, if the argument is NULL or the
57050 ** WAL module is using shared-memory, return false.
57057 /* Create a snapshot object. The content of a snapshot is opaque to
57085 ** Return a +ve value if snapshot p1 is newer than p2. A -ve value if
57086 ** p1 is older than p2 and zero if p1 and p2 are the same snapshot.
57092 /* aSalt[0] is a copy of the value stored in the wal file header. It
57093 ** is incremented each time the wal file is restarted. */
57104 ** If the argument is not NULL, it points to a Wal object that holds a
57105 ** read-lock. This function returns the database page-size if it is known,
57106 ** or zero if it is not (or if pWal is NULL).
57128 ** a legal notice, here is a blessing:
57137 ** This code really belongs in btree.c. But btree.c is getting too
57147 ** a legal notice, here is a blessing:
57161 ** The basic idea is that each page of the file contains N database
57175 ** disk where M is the number of entries in the tree.
57178 ** BTrees. Each BTree is identified by the index of its root page. The
57181 ** page. If the payload is larger than the preset amount then surplus
57189 ** The file is divided into pages. The first page is called page 1,
57190 ** the second is page 2, and so forth. A page number of zero indicates
57195 ** The first page is always a btree page. The first 100 bytes of the first
57197 ** The format of the file header is as follows:
57228 ** The file change counter is incremented when the database is changed
57232 ** The max embedded payload fraction is the amount of the total usable
57235 ** is to limit the maximum cell size so that at least 4 cells will fit
57236 ** on one page. Thus the default max embedded payload fraction is 64.
57238 ** If the payload for a cell is larger than the max payload, then extra
57239 ** payload is spilled to overflow pages. Once an overflow page is allocated,
57243 ** The min leaf payload fraction is like the min embedded payload fraction
57245 ** payload fraction for a LEAFDATA tree is always 100% (or 255) and it
57248 ** Each btree pages is divided into three sections: The header, the
57280 ** only keys and no data. The intkey flag means that the key is an integer
57281 ** which is stored in the key size entry of the cell header rather than in
57291 ** Cell content is stored at the very end of the page and grows toward the
57294 ** Unused space within the cell content area is collected into a linked list of
57295 ** freeblocks. Each freeblock is at least 4 bytes in size. The byte offset
57296 ** to the first freeblock is given in the header. Freeblocks occur in
57299 ** exist on the freeblock chain. A group of 3 or fewer free bytes is called
57300 ** a fragment. The total number of bytes in all fragments is recorded.
57309 ** that immediately follows the page header. Cells is not necessarily
57313 ** length integer is 1 to 9 bytes where the lower 7 bits of each
57334 ** 4 Page number of the left child. Omitted if leaf flag is set.
57335 ** var Number of bytes of data. Omitted if the zerodata flag is set.
57336 ** var Number of bytes of key. Or the key itself if intkey flag is set.
57340 ** Overflow pages form a linked list. Each page except the last is completely
57350 ** page points to multiple leaf pages. The content of a leaf page is
57361 /* The following value is the maximum cell size assuming a maximum page
57379 ** This is a magic string that appears at the beginning of every
57404 ** As each page of the file is loaded into memory, an instance of the following
57405 ** structure is appended and initialized to zero. This structure stores
57406 ** information about the page that is decoded from the raw file page.
57410 ** unref() the parent page pointer when this page is no longer referenced.
57413 ** Access to all fields of this structure is controlled by the mutex
57435 BtShared *pBt; /* Pointer to BtShared that this page is part of */
57448 ** to the end. EXTRA_SIZE is the number of bytes of space needed to hold
57454 ** A linked list of the following structures is stored at BtShared.pLock.
57456 ** is opened on the table with root page BtShared.iTable. Locks are removed
57457 ** from this list when a transaction is committed or rolled back, or when
57458 ** a btree handle is closed.
57475 ** is opaque to the database connection. The database connection cannot
57512 ** If the shared-data extension is enabled, there may be multiple users
57527 ** to this one BtShared object. BtShared.nRef is the number of
57533 ** may not be modified once it is initially set as long as nRef>0.
57535 ** thereafter is unchanged as long as nRef>0.
57541 ** the shared-cache enters 'pending-lock' state and isPending is
57553 ** This feature is included to help prevent writer-starvation.
57562 u8 autoVacuum; /* True if auto-vacuum is enabled */
57563 u8 incrVacuum; /* True if incr-vacuum is enabled */
57596 #define BTS_READ_ONLY 0x0001 /* Underlying file is readonly */
57598 #define BTS_SECURE_DELETE 0x0004 /* PRAGMA secure_delete is enabled */
57605 ** An instance of the following structure is used to hold information
57619 ** this will be declared corrupt. This value is calculated based on a
57623 ** If a tree that appears to be taller than this is encountered, it is
57624 ** assumed that the database is corrupt.
57629 ** A cursor is a pointer to a particular entry within a particular
57632 ** The entry is identified by its MemPage and the index in
57636 ** but cursors cannot be shared. Each cursor is associated with a
57643 ** eState==SKIPNEXT && skipNext>0: Next sqlite3BtreeNext() is no-op.
57644 ** eState==SKIPNEXT && skipNext<0: Next sqlite3BtreePrevious() is no-op.
57657 int skipNext; /* Prev() is noop if negative. Next() is noop if positive.
57663 /* All fields above are zeroed when the cursor is allocated. See
57678 #define BTCF_ValidNKey 0x02 /* True if info.nKey is valid */
57679 #define BTCF_ValidOvfl 0x04 /* True if aOverflow is valid */
57680 #define BTCF_AtLast 0x08 /* Cursor is pointing ot the last entry */
57689 ** because the table is empty or because BtreeCursorFirst() has not been
57696 ** Cursor is valid except that the Cursor.skipNext field is non-zero
57702 ** modified since the cursor was last used. The cursor position is saved
57703 ** in variables BtCursor.pKey and BtCursor.nKey. When a cursor is in
57721 ** The database page the PENDING_BYTE occupies. This page is never used.
57727 ** database page. The first argument to each is the number of usable
57728 ** bytes on each page of the database (often 1024). The second is the
57735 ** If the pgno argument passed to PTRMAP_PAGENO is a pointer-map page,
57736 ** then pgno is returned. So (pgno==PTRMAP_PAGENO(pgsz, pgno)) can be
57737 ** used to test if pgno is a pointer-map page. PTRMAP_ISPAGE implements
57745 ** The pointer map is a lookup table that identifies the parent page for
57746 ** each child page in the database file. The parent page is the page that
57749 ** to any page that is not part of the pointer map itself.) Each pointer map
57753 ** The purpose of the pointer map is to facility moving pages from one
57755 ** is moved, the pointer in its parent must be updated to point to the
57756 ** new location. The pointer map is used to locate the parent page quickly.
57758 ** PTRMAP_ROOTPAGE: The database page is a root-page. The page-number is not
57761 ** PTRMAP_FREEPAGE: The database page is an unused (free) page. The page-number
57762 ** is not used in this case.
57764 ** PTRMAP_OVERFLOW1: The database page is the first page in a list of
57768 ** PTRMAP_OVERFLOW2: The database page is the second or later page in a list of
57772 ** PTRMAP_BTREE: The database page is a non-root btree page. The page number
57790 ** The ISAUTOVACUUM macro is used within balance_nonroot() to determine
57791 ** if the database supports auto-vacuum or not. Because it is used
57792 ** within an expression that is an argument to another macro
57793 ** (sqliteMallocRaw), it is not possible to use conditional compilation.
57794 ** So, this macro is defined instead.
57804 ** This structure is passed around through all the sanity checking routines
57807 ** The aRef[] array is allocated so that there is 1 bit for each page in
57809 ** the database the corresponding bit is set. This allows integrity-check to
57838 ** two-byte aligned address. get2bytea() is only used for accessing the
57894 ** If the object is not sharable, then no mutex is ever required
57895 ** and this routine is a no-op. The underlying mutex is non-recursive.
57897 ** of this interface is recursive.
57900 ** by all database connections. The p->pNext is a list of other
57925 /* Unless the database is sharable and unlocked, then BtShared.db
57935 /* This is a helper function for sqlite3BtreeLock(). By moving
57992 ** Return true if the BtShared mutex is held on the btree, or if the
57993 ** B-Tree is not marked as sharable.
57995 ** This routine is used only from within assert() statements.
58010 ** connection. This is needed (for example) prior to parsing
58015 ** There is a corresponding leave-all procedures.
58046 ** This routine is used inside assert() statements only.
58074 ** If pSchema is not NULL, then iDb is computed from pSchema and
58097 ** If shared cache is disabled, then all btree mutex routines, including
58119 ** These entry points are used by incremental I/O only. Enter() is required
58120 ** any time OMIT_SHARED_CACHE is not defined, regardless of whether or not
58121 ** the build is threadsafe. Leave() is only required by threadsafe builds.
58141 ** a legal notice, here is a blessing:
58173 ** But if the value is zero, make it 65536.
58175 ** This routine is used to extract the "offset to cell content area" value
58176 ** from the header of a btree page. If the page size is 65536 and the page
58177 ** is empty, the offset should be 65536, but the 2-byte value stores zero.
58190 ** Macro IfNotOmitAV(x) returns (x) if SQLITE_OMIT_AUTOVACUUM is not
58191 ** defined, or 0 if it is. For example:
58208 ** Access to this variable is protected by SQLITE_MUTEX_STATIC_MASTER.
58238 ** shared-cache table level locks. If the library is compiled with the
58239 ** shared-cache feature disabled, then there is only ever one user
58240 ** of each BtShared structure and so this locking is not necessary.
58255 **** This function is only used as part of an assert() statement. ***
58273 ** hold a write-lock on the schema table (root page 1). This is also
58279 int isIndex, /* True if iRoot is the root of an index b-tree */
58286 /* If this database is not shareable, or if the client is reading
58287 ** and has the read-uncommitted flag set, then no lock is required.
58296 /* If the client is reading or writing an index and the schema is
58297 ** not loaded, then it is too difficult to actually check to see if
58306 ** b-trees, this is just the root page of the b-tree being read or
58307 ** written. For index b-trees, it is the root page of the associated
58316 ** be imposter tables. So just return true. The assert is not
58328 ** write-lock on the schema table, or (if the client is reading) a
58352 ** It is illegal for pBtree to write if some other Btree object that
58353 ** shares the same BtShared object is currently reading or writing
58355 ** read-uncommitted flag set, then it is OK for the other object to
58399 /* This routine is a no-op if the shared-cache is not enabled */
58404 /* If some other connection is holding an exclusive lock, the
58414 ** statement is a simplification of:
58445 ** (a) The specified Btree object p is connected to a sharable
58452 ** SQLITE_OK is returned if the lock is added successfully. SQLITE_NOMEM
58453 ** is returned if a malloc attempt fails.
58466 ** by a connection in read-uncommitted mode is on the sqlite_master
58467 ** table, and that lock is obtained in BtreeBeginTrans(). */
58547 /* This function is called when Btree p is concluding its
58548 ** transaction. If there currently exists a writer, and p is not
58553 ** If there is not currently a writer, then BTS_PENDING must
58554 ** be zero already. So this next line is harmless in that case.
58581 ***** This routine is used inside of assert() only ****
58590 /* Verify that the cursor and the BtShared agree about what is the current
58591 ** database connetion. This is important in shared-cache mode. If the database
58592 ** connection pointers get out-of-sync, it is possible for routines like
58594 ** a connection that has already closed. This routine is used inside assert()
58624 ** This function is called before modifying the contents of a table
58628 ** If argument isClearTable is true, then the entire contents of the
58629 ** table is about to be deleted. In this case invalidate all incrblob
58632 ** Otherwise, if argument isClearTable is false, then the row with
58633 ** rowid iRow is being replaced or deleted. In this case invalidate
58656 /* Stub function when INCRBLOB is omitted */
58661 ** Set bit pgno of the BtShared.pHasContent bitvec. This is called
58669 ** 1) When all data is deleted from a page and the page becomes
58670 ** a free-list leaf page, the page is not written to the database
58672 ** such a page is not even journalled (as it will not be modified,
58675 ** 2) When a free-list leaf page is reused, its content is not read
58677 ** be, if it is not at all meaningful?).
58681 ** a page is moved to the free-list and then reused within the same
58682 ** transaction, a problem comes up. If the page is not journalled when
58683 ** it is moved to the free-list and it is also not journalled when it
58684 ** is extracted from the free-list and reused, then the original data
58688 ** The solution is the BtShared.pHasContent bitvec. Whenever a page is
58689 ** moved to become a free-list leaf page, the corresponding bit is
58690 ** set in the bitvec. Whenever a leaf page is extracted from the free-list,
58691 ** optimization 2 above is omitted if the corresponding bit is already
58713 ** This function is called when a free-list leaf page is removed from the
58714 ** free-list for reuse. It returns false if it is safe to retrieve the
58745 ** when this function is called (i.e. have eState==CURSOR_VALID). This
58747 ** pCur->pKey. SQLITE_OK is returned if successful or an SQLite error
58750 ** If the cursor is open on an intkey table, then the integer key
58751 ** (the rowid) is stored in pCur->nKey and pCur->pKey is left set to
58752 ** NULL. If the cursor is open on a non-intkey table, then pCur->pKey is
58763 /* Only the rowid is required for a table btree */
58787 ** and BtCursor.pKey. The cursor's state is set to CURSOR_REQUIRESEEK.
58789 ** The caller must ensure that the cursor is valid (has eState==CURSOR_VALID)
58821 ** the location in the btree is remembered in such a way that it can be
58823 ** routine is called just before cursor pExcept is used to modify the
58832 ** then the BTCF_Multiple flag on pExpect is cleared, to avoid another
58852 ** the cursors if and when a cursor is found that actually requires saving.
58853 ** The common case is that no cursors need to be saved, so this routine is
58889 ** In this version of BtreeMoveto, pKey is a packed index record
58890 ** such as is generated by the OP_MakeRecord opcode. Unpack the
58895 const void *pKey, /* Packed key if the btree is an index */
58963 ** Cursors can move when the row they are pointing at is deleted out
58965 ** is rebalanced.
58981 ** On success, the *pDifferentRow parameter is false if the cursor is left
58982 ** pointing at exactly the same row. *pDifferntRow is the row the cursor
59011 ** and number of the varargs parameters) is determined by the eHintType
59034 ** Return 0 (not a valid page) for pgno==1 since there is
59058 ** If *pRC is initially non-zero (non-SQLITE_OK) then this routine is
59059 ** a no-op. If an error occurs, the appropriate error code is written
59112 ** An error code is returned if something goes wrong, otherwise SQLITE_OK.
59157 ** 4-byte child pointer found on interior pages, if there is one.
59168 ** This is common tail processing for btreeParseCellPtr() and
59180 ** overflow pages. The strategy is to minimize the amount of unused
59184 ** Warning: changing the way overflow payload is distributed in any
59214 ** There is also a wrapper function btreeParseCell() that works for
59250 /* The next block of code is equivalent to:
59254 ** The code is inlined to avoid a function call.
59266 /* The next block of code is equivalent to:
59270 ** The code is inlined to avoid a function call.
59293 /* This is the (easy) common case where the entire payload fits
59294 ** on the local page. No overflow is required.
59330 /* This is the (easy) common case where the entire payload fits
59331 ** on the local page. No overflow is required.
59342 int iCell, /* The cell index. First cell is 0 */
59368 ** cell. If SQLITE_DEBUG is defined, an assert() at the bottom of
59369 ** this function verifies that this invariant is not violated. */
59415 ** cell. If SQLITE_DEBUG is defined, an assert() at the bottom of
59416 ** this function verifies that this invariant is not violated. */
59432 /* This variation on cellSizePtr() is used inside of assert() statements
59460 ** end of the page and all free space is collected into one
59552 ** This function may detect corruption within pPg. If corruption is
59553 ** detected then *pRc is set to SQLITE_CORRUPT and NULL is returned.
59577 ** freeblock form a big-endian integer which is the size of the freeblock
59615 ** The caller guarantees that there is sufficient space to make the
59619 ** allocation is being made in order to insert a new cell, so we will
59632 assert( nByte>=0 ); /* Minimum cell size is 4 */
59641 ** and the reserved space is zero (the usual value for reserved space)
59643 ** However, that integer is too large to be stored in a 2-byte unsigned
59644 ** integer, so a value of 0 is used in its place. */
59655 /* If there is enough space between gap and top for one more cell pointer
59656 ** array entry offset, and if the freelist is not empty, then search the
59674 ** to see if defragmentation is necessary.
59688 ** validated the freelist. Given that the freelist is valid, there
59689 ** is no way that the allocation can extend off the end of the page.
59701 ** The first byte of the new free block is pPage->aData[iStart]
59702 ** and the size of the block is iSize bytes.
59727 assert( iSize>=4 ); /* Minimum cell size is 4 */
59731 ** option is enabled */
59742 iFreeBlk = 0; /* Shortcut for the case when the freelist is empty */
59766 /* If iPtr is another freeblock (that is, if iPtr is not the freelist
59783 /* The new freeblock is at the beginning of the cell content area,
59822 /* EVIDENCE-OF: R-07291-35328 A value of 5 (0x05) means the page is an
59825 /* EVIDENCE-OF: R-26900-09176 A value of 13 (0x0d) means the page is a
59840 /* EVIDENCE-OF: R-43316-37308 A value of 2 (0x02) means the page is an
59843 /* EVIDENCE-OF: R-59615-42828 A value of 10 (0x0a) means the page is a
59852 /* EVIDENCE-OF: R-47608-56469 Any other value for the b-tree page type is
59866 ** guarantee that the page is well-formed. It only shows that
59906 ** the start of the cell content area. A zero value for this integer is
59917 /* EVIDENCE-OF: R-24089-57979 If a page contains no cells (which is only
59955 ** start of the first freeblock on the page, or is zero if there are no
59965 ** Or, the freeblock is off the end of the page
59982 ** the cell-content area. If this is greater than the usable-size
60054 ** If the PAGER_GET_NOCONTENT flag is set, it means that we do not care
60079 ** Retrieve a page from the pager cache. If the requested page is not
60094 ** Return the size of the database file in pages. If there is any kind of
60109 ** If pCur!=0 then the page is being fetched as part of a moveToChild()
60113 ** The page is fetched as read-write unless pCur is not NULL and is
60116 ** If an error occurs, then *ppPage is undefined. It
60153 /* If obtaining a child page for a cursor, we must verify that the page is
60191 ** * If the page is already in use for some other purpose, immediately
60193 ** * Make sure the isInit flag is clear
60218 ** so that the cache is restored to its original state at the start of
60219 ** the transaction, for each page restored this routine is called.
60235 ** But no harm is done by this. And it is very important that
60256 ** zFilename is the name of the database file. If zFilename is NULL
60257 ** then an ephemeral database is created. The ephemeral database might
60260 ** when sqlite3BtreeClose() is called.
60262 ** If zFilename is ":memory:" then an in-memory database is created
60263 ** that is automatically destroyed when it is closed.
60265 ** The "flags" parameter is a bitmask that might contain bits like
60268 ** If the database is already opened in the same database connection
60311 /* A BTREE_SINGLE database is always a temporary and/or ephemeral */
60333 ** If this Btree is a candidate for shared cache, try to find an
60403 ** the right size. This is to guard against size changes that result
60437 /* EVIDENCE-OF: R-51873-39618 The page size for a database file is
60447 ** SQLITE_DEFAULT_AUTOVACUUM is true. On the other hand, if
60448 ** SQLITE_OMIT_MEMORYDB has been defined, then ":memory:" is just a
60458 /* EVIDENCE-OF: R-37497-42412 The size of the reserved region is
60498 ** The list is kept in ascending order by pBt address.
60557 ** false if it is still positive.
60602 /* One of the uses of pBt->pTmpSpace is to format cells before
60604 ** a cell is less than 4 bytes in size, it is rounded up to 4 bytes
60608 ** it into a database page. This is not actually a problem, but it
60610 ** data is passed to system call write(). So to avoid this error,
60667 /* The pBt is no longer on the sharing list, so we can access
60697 ** cache is allowed to grow larger than this limit if it contains
60715 ** The value returned is the current spill size. If zero is passed
60717 ** using mxPage of 0 is a way to query the current spill size.
60745 ** Change the way data is synced to disk in order to increase or decrease
60747 ** failures. Level 1 is the same as asynchronous (no syncs() occur and
60748 ** there is a high probability of damage) Level 2 is the default. There
60749 ** is a very low but non-zero probability of damage. Level 3 reduces the
60772 ** size supplied does not meet this constraint then the page size is not
60780 ** If parameter nReserve is less than zero, then the number of reserved
60781 ** bytes per page is left unchanged.
60783 ** If the iFix!=0 then the BTS_PAGESIZE_FIXED flag is set so that the page size
60824 ** This function is similar to sqlite3BtreeGetReserve(), except that it
60825 ** may only be called if it is guaranteed that the b-tree mutex is already
60828 ** This is useful in one special case in the backup API code where it is
60829 ** known that the shared b-tree mutex is held, but the mutex on the
60830 ** database handle that owns *p is not. In this case if sqlite3BtreeEnter()
60843 ** are intentually left unused. This is the "reserved" space that is
60846 ** If SQLITE_HAS_MUTEX is defined then the number returned is the
60863 ** Set the maximum page count for a database if mxPage is positive.
60864 ** No changes are made if mxPage is 0 or negative.
60876 ** Set the BTS_SECURE_DELETE flag if newFlag is 0 or 1. If newFlag is -1,
60895 ** parameter is non-zero, then auto-vacuum mode is enabled. If zero, it
60896 ** is disabled. The default value for the auto-vacuum property is
60920 ** Return the value of the 'auto-vacuum' property. If auto-vacuum is
60921 ** enabled 1 is returned. Otherwise 0.
60944 ** SQLITE_OK is returned on success. If the file is not a
60945 ** well-formed database file, then SQLITE_CORRUPT is returned.
60946 ** SQLITE_BUSY is returned if the database is locked. SQLITE_NOMEM
60947 ** is returned if we run out of memory.
60963 /* Do some checking to help insure the file we opened really is
60998 /* If the write version is set to 2, this database should be accessed
60999 ** in WAL mode. If the log is not already open, open it now. Then
61001 ** The caller detects this and calls this function again. This is
61044 /* EVIDENCE-OF: R-51873-39618 The page size for a database file is
61048 /* EVIDENCE-OF: R-25008-21688 The size of a page is a power of two
61058 ** integer at offset 20 is the number of bytes of space at the end of
61061 ** EVIDENCE-OF: R-37497-42412 The size of the reserved region is
61067 ** of BtShared.pageSize, we have discovered that the page-size is
61084 /* EVIDENCE-OF: R-28312-64704 However, the usable size is not allowed to
61085 ** be less than 480. In other words, if the page size is 512, then the
61098 /* maxLocal is the maximum amount of payload to store locally for
61099 ** a cell. Make sure it is small enough so that at least minFanout
61107 ** So a cell consists of a 2-byte pointer, a header which is as much as
61133 ** Return the number of cursors open on pBt. This is for use
61134 ** in assert() expressions, so it is only compiled if NDEBUG is not
61137 ** Only write cursors are counted if wrOnly is true. If wrOnly is
61140 ** For the purposes of this routine, a cursor is any cursor that
61141 ** is capable of reading or writing to the database. Cursors that
61157 ** of a transaction but there is a read lock on the database, then
61161 ** If there is a transaction in progress, this routine is a no-op.
61235 ** is started if the second argument is nonzero, otherwise a read-
61236 ** transaction. If the second argument is 2 or more and exclusive
61237 ** transaction is started, meaning that no other process is allowed
61244 ** will work unless a transaction is started first:
61256 ** if there is one. But if there was previously a read-lock, do not
61257 ** invoke the busy handler - just return SQLITE_BUSY. SQLITE_BUSY is
61258 ** returned when there is already a read-lock in order to avoid a deadlock.
61261 ** a reserved lock. B tries to promote to exclusive but is blocked because
61262 ** of A's read lock. A tries to promote to reserved but is blocked by B.
61275 /* If the btree is already in a write-transaction, or it
61276 ** is already in a read-transaction and a read-transaction
61277 ** is requested, this is a no-op.
61294 ** on this shared-btree structure and a second write transaction is
61327 /* Call lockBtree() until either pBt->pPage1 is populated or
61331 ** file is not pBt->pageSize. In this case lockBtree() will update
61378 /* If the db-size header field is incorrect (as it may be if an old
61397 ** open savepoints. If the second parameter is greater than 0 and
61398 ** the sub-journal is not already open, then it will be opened here.
61452 ** Somewhere on pPage is a pointer to page iFrom. Modify this pointer so
61456 ** PTRMAP_BTREE: pPage is a btree-page. The pointer points at a child
61459 ** PTRMAP_OVERFLOW1: pPage is a btree-page. The pointer points at an overflow
61462 ** PTRMAP_OVERFLOW2: pPage is an overflow-page. The pointer points at the next
61469 /* The pointer is always the first 4 bytes of the page in this case. */
61522 ** The isCommit flag indicates that there is no need to remember that
61558 ** If pDbPage is an overflow page, then the first 4 bytes may store a
61559 ** pointer to a subsequent overflow page. If this is the case, then
61605 ** SQLITE_OK. If there is no work to do (and therefore no point in
61610 ** that the last page of the file currently in use is no longer in use.
61612 ** Parameter nFin is the number of pages that this database would contain
61615 ** If the bCommit parameter is non-zero, this function assumes that the
61617 ** or an error. bCommit is passed true for an auto-vacuum-on-commit
61646 /* Remove the page from the files free-list. This is not required
61647 ** if bCommit is non-zero. In that case, the free-list will be
61671 /* If bCommit is zero, this loop runs exactly once and page pLastPg
61672 ** is swapped with the first free page pulled off the free list.
61674 ** On the other hand, if bCommit is greater than zero, then keep
61676 ** of the file is found.
61712 ** The database opened by the first argument is an auto-vacuum database
61738 ** If the incremental vacuum is finished after this function has run,
61739 ** SQLITE_DONE is returned. If it is not finished, but no error occurred,
61740 ** SQLITE_OK is returned. Otherwise an SQLite error code.
61776 ** This routine is called prior to sqlite3PagerCommit when a transaction
61777 ** is committed for an auto-vacuum database.
61779 ** If SQLITE_OK is returned, then *pnTrunc is set to the number of pages
61800 /* It is not possible to create a database for which the final page
61801 ** is either a pointer-map page or the pending-byte page. If one
61802 ** is encountered, this indicates corruption.
61843 ** the disk. After the journal is safely on oxide, the changes to the
61850 ** This call is a no-op if no write-transaction is currently active on pBt.
61854 ** individual journal file, or is NULL, indicating no master journal file
61857 ** When this is called, the master journal should already have been
61860 ** Once this is routine has returned, the only thing required to commit
61861 ** the write-transaction for this database file is to delete the journal.
61887 ** This function is called from both BtreeCommitPhaseTwo() and BtreeRollback()
61934 ** routine has to do is delete or truncate or zero the header in the
61938 ** Normally, if an error occurs while the pager layer is attempting to
61941 ** is non-zero then this b-tree transaction is part of a multi-file
61946 ** transaction has been closed. This is quite safe, as the pager will have
61998 ** references. Or if the writeOnly flag is set to 1, then only
62001 ** Every cursor is a candidate to be tripped, including cursors
62006 ** flag is true, then only write-cursors need be tripped - read-only
62008 ** following the rollback. Or, if writeOnly is false, all cursors are
62009 ** tripped. In general, writeOnly is false if the transaction being
62014 ** If the writeOnly flag is true and an error is encountered while
62018 ** SQLITE_OK is returned if successful, or if an error occurs while
62056 ** If tripCode is not SQLITE_OK then cursors will be invalidated (tripped).
62057 ** Only write cursors are tripped if writeOnly is true but all cursors are
62058 ** tripped if writeOnly is false. Any attempt to use
62096 ** sure pPage1->aData is set correctly. */
62118 ** before starting a subtransaction. The subtransaction is ended automatically
62126 ** A statement sub-transaction is implemented as an anonymous savepoint. The
62127 ** value passed as the second parameter is the total number of savepoints,
62130 ** iStatement is 1. This anonymous savepoint can be released or rolled back
62142 /* At the pager level, a statement transaction is a savepoint with
62144 ** SQL statements. It is illegal to open, release or rollback any
62145 ** such savepoints while the statement transaction savepoint is active.
62153 ** The second argument to this function, op, is always SAVEPOINT_ROLLBACK
62158 ** Normally, iSavepoint is greater than or equal to zero. However, if op is
62160 ** contents of the entire transaction are rolled back. This is different
62181 ** 28 is nonzero. */
62190 ** Create a new cursor for the BTree whose root is on the page
62191 ** iTable. If a read-only cursor is requested, it is assumed that
62193 ** on the database already. If a write-cursor is requested, then
62194 ** the caller is assumed to have an open write transaction.
62196 ** If the BTREE_WRCSR bit of wrFlag is clear, then the cursor can only
62197 ** be used for reading. If the BTREE_WRCSR bit is set, then the cursor
62215 ** is set. If FORDELETE is set, that is a hint to the implementation that
62217 ** as part of a larger DELETE statement. The FORDELETE hint is not used by
62220 ** rows are deleted, the FORDELETE flag is a hint that all SEEK and DELETE
62224 ** No checking is done to make sure that page iTable really is the
62225 ** root page of a b-tree. If it is not, then the cursor acquired
62228 ** It is assumed that the sqlite3BtreeCursorZero() has been called
62247 /* The following assert statements verify that if this is a sharable
62248 ** b-tree database, the connection is holding the required table locks,
62312 ** This interfaces is needed so that users of cursors can preallocate
62313 ** sufficient storage to hold a cursor. The BtCursor object is opaque
62334 ** Close a cursor. The read lock on the database file is released
62335 ** when the last cursor is closed.
62370 ** BtCursor.info structure. If it is not already valid, call
62373 ** BtCursor.info is a cache of the information in the current cell.
62399 ** Return true if the given BtCursor is valid. A valid cursor is one
62400 ** that is currently pointing to a row in a (non-empty) table.
62401 ** This is a verification routine is used only within assert() statements.
62410 ** This routine is only valid for a cursor that is pointing into a
62412 ** is invalid, the result of this routine is undefined.
62423 ** Return the number of bytes of payload for the entry that pCur is
62427 ** The caller must guarantee that the cursor is pointing to a non-NULL
62444 ** If an error occurs an SQLite error code is returned. Otherwise:
62446 ** The page number of the next overflow page in the linked list is
62447 ** written to *pPgnoNext. If page ovfl is the last page in its linked
62448 ** list, *pPgnoNext is set to zero.
62450 ** If ppPage is not NULL, and a reference to the MemPage object corresponding
62451 ** to page number pOvfl was obtained, then *ppPage is set to point to that
62452 ** reference. It is the responsibility of the caller to call releasePage()
62455 ** *ppPage is set to zero.
62473 ** the overflow list is page number (ovfl+1). If that guess turns
62517 ** pPayload is a pointer to data stored on database page pDbPage.
62518 ** If argument eOp is false, then nByte bytes of data are copied
62519 ** from pPayload to the buffer pointed at by pBuf. If eOp is true,
62520 ** then sqlite3PagerWrite() is called on pDbPage and nByte bytes
62523 ** SQLITE_OK is returned on success, otherwise an error code.
62547 ** This function is used to read or overwrite payload information
62548 ** for the entry that the pCur cursor is pointing to. The eOp
62549 ** argument is interpreted as follows:
62551 ** 0: The operation is a read. Populate the overflow cache.
62552 ** 1: The operation is a write. Populate the overflow cache.
62553 ** 2: The operation is a read. Do not populate the overflow cache.
62556 ** Data is read to or from the buffer pBuf.
62562 ** eOp argument is not 2, this function may allocate space for and lazily
62569 ** the cursor is moved to a different row. Additionally, in auto-vacuum
62608 /* Trying to read or write past the end of the data is an error. The
62609 ** conditional above is really:
62611 ** but is recast into its current form to avoid integer overflow problems
62640 ** The aOverflow[] array is sized at one entry for each overflow page
62641 ** in the overflow chain. The page number of the first overflow page is
62643 ** means "not yet known" (the cache is lazily populated).
62665 ** entry for the first required overflow page is valid, skip
62687 /* The only reason to read this page is to obtain the page
62689 ** data is not required. So first try to lookup the overflow
62694 ** here. If eOp==2, then offset==0 and this branch is never taken.
62707 ** range of data that is being read (eOp==0) or written (eOp!=0).
62720 ** 1) this is a read operation, and
62721 ** 2) data is required from the start of this overflow page, and
62722 ** 3) the database is file-backed, and
62723 ** 4) there is no open write-transaction, and
62724 ** 5) the database is not a WAL database,
62725 ** 6) all data from the page is being read.
62780 ** The caller must ensure that pCur is pointing to a valid row
62784 ** wrong. An error is returned if "offset+amt" is larger than
62801 ** wrong. An error is returned if "offset+amt" is larger than
62826 ** pCur cursor is pointing to. The pointer is to the beginning of
62827 ** the key if index btrees (pPage->intKey==0) and is the data for
62829 ** key/data is written into *pAmt. If *pAmt==0, then the value
62832 ** This routine is an optimization. It is common for the entire key
62834 ** pages. When that is so, this routine can be used to access the
62841 ** any btree routine is called.
62864 ** For the entry that cursor pCur is point to, return as
62868 ** The pointer returned is ephemeral. The key/data may move
62874 ** These routines is used to get quick access to key and data
62883 ** Move the cursor down to a new child page. The newPgno argument is the
62911 ** Page pParent is an internal (non-leaf) tree page. This function
62912 ** asserts that page number iChild is the left-child if the iIdx'th
62913 ** cell in page pParent. Or, if iIdx is equal to the total number of
62914 ** cells in pParent, that page number iChild is the right-child of
62934 ** pCur->idx is set to the cell index that contains the pointer
62936 ** right-most child page then pCur->idx is set to one more than
62958 ** If the table has a virtual root page, then the cursor is moved to point
62963 ** If the b-tree structure is empty, the cursor state is set to
62964 ** CURSOR_INVALID. Otherwise, the cursor is set to point to the first
62966 ** is set to CURSOR_VALID.
62969 ** page-header flags indicate that the [virtual] root-page is the expected
62971 ** specify a KeyInfo structure the flags byte is set to 0x05 or 0x0D,
62973 ** structure the flags byte is set to 0x02 or 0x0A, indicating an index
63014 /* If pCur->pKeyInfo is not NULL, then the caller that opened this cursor
63015 ** expected to open it on an index b-tree. Otherwise, if pKeyInfo is
63016 ** NULL, the caller expects a table b-tree. If this is not the case,
63021 ** if pCur->iPage>=0). But this is not so if the database is corrupted
63022 ** in such a way that page pRoot is linked into a second b-tree table
63049 ** entry to which it is currently pointing.
63051 ** The left-most leaf is the one with the smallest key - the first
63071 ** page to which it is currently pointing. Notice the difference
63076 ** The right-most entry is the one with the largest key - the last
63100 ** or set *pRes to 1 if the table is empty.
63123 ** or set *pRes to 1 if the table is empty.
63131 /* If the cursor already points to the last entry, this is a no-op. */
63169 ** For INTKEY tables, the intKey parameter is used. pIdxKey
63170 ** must be NULL. For index tables, pIdxKey is used and intKey
63171 ** is ignored.
63173 ** If an exact match is not found, then the cursor is always
63178 ** An integer is written into *pRes which is the result of
63179 ** comparing the key with the entry to which the cursor is
63181 ** *pRes is as follows:
63183 ** *pRes<0 The cursor is left pointing at an entry that
63184 ** is smaller than intKey/pIdxKey or if the table is empty
63185 ** and the cursor is therefore left point to nothing.
63187 ** *pRes==0 The cursor is left pointing at an entry that
63190 ** *pRes>0 The cursor is left pointing at an entry that
63191 ** is larger than intKey/pIdxKey.
63193 ** For index tables, the pIdxKey->eqSeen field is set to 1 if there
63212 /* If the cursor is already positioned at the point we are trying
63258 /* pPage->nCell must be greater than zero. If this is the root-page
63260 ** not run. If this is not the root-page, then the moveToChild() routine
63309 /* The maximum supported page-size is 65536 bytes. This means that
63311 ** page is less than 16384 bytes and may be stored as a 2-byte
63312 ** varint. This information is used to attempt to avoid parsing
63313 ** the entire cell by checking for the cases where the record is
63319 /* This branch runs if the record-size field of the cell is a
63327 /* The record-size field is a 2 byte varint and the record
63337 ** If the record is corrupt, the xRecordCompare routine may read
63339 ** bytes of padding is allocated at the end of the buffer in
63345 testcase( nCell<0 ); /* True if key size is 2^32 or more */
63415 ** Return TRUE if the cursor is not pointing at an entry of the table.
63419 ** the first entry. TRUE is also returned if the table is empty.
63422 /* TODO: What if the cursor is in CURSOR_REQUIRESEEK but all table entries
63435 ** The main entry point is sqlite3BtreeNext(). That routine is optimized
63438 ** routine is called when it is necessary to move to a different page or
63445 ** Zero is the common case. The btree implementation is free to use the
63483 /* If the database file is corrupt, it is possible for the value of idx
63485 ** the page while cursor pCur is holding a reference to it. Which can
63486 ** only happen if the database is corrupt in such a way as to link the
63545 ** The main entry point is sqlite3BtreePrevious(). That routine is optimized
63548 ** helper routine is called when it is necessary to move to a different page
63555 ** Zero is the common case. The btree implementation is free to use the
63640 ** The new page is marked as dirty. (In other words, sqlite3PagerWrite()
63642 ** been referenced and the calling routine is responsible for calling
63643 ** sqlite3PagerUnref() on the new page when it is done.
63645 ** SQLITE_OK is returned on success. Any other return value indicates
63646 ** an error. *ppPage is set to NULL in the event of an error.
63648 ** If the "nearby" parameter is not 0, then an effort is made to
63653 ** If the eMode parameter is BTALLOC_EXACT and the nearby page exists
63654 ** anywhere on the free-list, then it is guaranteed to be returned. If
63655 ** eMode is BTALLOC_LT then the page returned will be less than or equal
63656 ** to nearby if any such page exists. If eMode is BTALLOC_ANY then there
63657 ** are no restrictions on which page is returned.
63692 ** shows that the page 'nearby' is somewhere on the free-list, then
63713 ** first free-list trunk page. iPrevTrunk is initially 1.
63719 /* The code within this loop is run only once if the 'searchList' variable
63720 ** is not true. Otherwise, it runs once for each trunk-page on the
63721 ** free-list until the page 'nearby' is located (eMode==BTALLOC_EXACT)
63722 ** or until a page less than 'nearby' is located (eMode==BTALLOC_LT)
63728 ** is the page number of the next freelist trunk page in the list or
63729 ** zero if this is the last freelist trunk page. */
63734 ** the freelist is empty. */
63750 ** is the number of leaf page pointers to follow. */
63753 /* The trunk has no leaves and the list is not being searched.
63767 /* Value of k is out of range. Database corruption */
63774 /* The list is being searched and this trunk page is the page
63795 /* The trunk page is required by the caller but it contains
63909 ** that is required in the event of a rollback. In this case, do
63930 ** becomes a new pointer-map page, the second is used by the caller.
63970 ** This function is used to add page iPage to the database file free-list.
63971 ** It is assumed that the page is not already a part of the free-list.
63973 ** The value passed as the second argument to this function is optional.
63978 ** If a pointer to a MemPage object is passed as the second argument,
63979 ** its reference count is not altered by this function.
64008 /* If the secure_delete option is enabled, then
64020 ** to indicate that the page is free.
64028 ** possibilities. If the free-list is currently empty, or if the first
64029 ** trunk page in the free-list is full, then this page will become a
64032 ** is possible to add the page as a new free-list leaf.
64050 /* In this case there is room on the trunk page to insert the page
64053 ** Note that the trunk page is not really full until it contains
64085 ** Possibly because the free-list is empty, or possibly because the
64086 ** first trunk in the free-list is full. Either way, the page being freed
64152 /* 0 is not a legal page number and page 1 cannot be an
64165 /* There is no reason any cursor should have an outstanding reference
64166 ** to an overflow page belonging to a cell that is being deleted/updated.
64169 ** It is helpful to detect this before calling freePage2(), as
64170 ** freePage2() may zero the page contents if secure-delete mode is
64172 ** caller is iterating through or using in some other way, this
64193 ** is responsible for making sure sufficient space has been allocated
64221 /* pPage is not necessarily writeable since pCell might be auxiliary
64222 ** buffer space that is separate from the pPage buffer area */
64304 ** overflow page is being allocated, add an entry to the pointer-map
64307 ** If this is the first overflow page, then write a partial entry
64326 /* If pToRelease is not zero than pPrior points into the data area
64327 ** of pToRelease. Make sure pToRelease is still writeable. */
64330 /* If pPrior is part of the data area of pPage, then make sure pPage
64331 ** is still writeable */
64346 /* If pToRelease is not zero than pPayload points into the data area
64347 ** of pToRelease. Make sure pToRelease is still writeable. */
64350 /* If pPayload is part of the data area of pPage, then make sure pPage
64351 ** is still writeable */
64374 ** The cell content is not freed or deallocated. It is assumed that
64428 ** pTemp is not null. Regardless of pTemp, allocate a new entry
64432 ** pPage->nOverflow is incremented.
64434 ** *pRC must be SQLITE_OK when this routine is called.
64578 ** The MemPage.nFree field is invalidated by this function. It is the
64614 /* The pPg->nFree field is now set incorrectly. The caller will fix it. */
64630 ** is returned. Otherwise, if the cells are added successfully, zero is
64634 ** (part of page pPg) to populate. After cell apCell[0] is written to the
64635 ** page body, a 16-bit offset is written to pCellptr. And so on, for each
64636 ** cell in the array. It is the responsibility of the caller to ensure
64637 ** that it is safe to overwrite this part of the cell-pointer array.
64639 ** When this function is called, *ppData points to the start of the
64640 ** content area on page pPg. If the size of the content area is extended,
64641 ** *ppData is updated to point to the new start of the content area
64648 ** cells in apCell[], then the cells do not fit and non-zero is returned.
64690 ** space associated with each cell in the array that is currently stored
64750 ** The pPg->nFree field is invalid when this function returns. It is the
64849 ** in a balancing operation. NN is the number of neighbors on either side
64850 ** of the page that participate in the balancing operation. NB is the
64854 ** The minimum value of NN is 1 (of course). Increasing NN above 1
64866 ** a new entry is being inserted on the extreme right-end of the
64877 ** pPage is the leaf page which is the right-most page in the tree.
64878 ** pParent is its parent. pPage must have a single overflow entry
64879 ** which is also the right-most entry on the page.
64881 ** The pSpace buffer is used to store a temporary copy of the divider
64897 /* This error condition is now caught prior to reaching this function */
64920 /* If this is an auto-vacuum database, update the pointer map
64923 ** operations fails, the return code is set, but the contents
64925 ** That is Ok, at this point the parent page is guaranteed to
64975 ** it is sometimes activated temporarily while debugging code responsible
65015 ** This function is used to copy the contents of the b-tree node stored
65018 ** parent page stored in the pointer map is page pTo. If pFrom contained
65020 ** map entries are also updated so that the parent page is page pTo.
65022 ** If pFrom is currently carrying any overflow cells (entries in the
65025 ** Before returning, page pTo is reinitialized using btreeInitPage().
65027 ** The performance of this function is not critical. It is only used by
65053 ** fairly obscure circumstances, even though it is a copy of initialized
65063 /* If this is an auto-vacuum database, update the pointer-map entries
65077 ** side if the page is the first or last child of its parent. If the page
65079 ** is a root page or a child of a root page) then all available siblings
65085 ** Note that when this routine is called, some of the cells on the page
65087 ** if the page is overfull. This routine ensures that all cells allocated
65093 ** happens, it is the responsibility of the caller to invoke the correct
65100 ** The third argument to this function, aOvflSpace, is a pointer to a
65102 ** page (pParent) the parent page becomes overfull, this buffer is
65105 ** size of a cell stored within an internal node is always less than 1/4
65106 ** of the page-size, the aOvflSpace[] buffer is guaranteed to be large
65109 ** If aOvflSpace is set to a null pointer, this function returns
65116 int isRoot, /* True if pParent is a root-page */
65117 int bBulk /* True if this call is part of a bulk load */
65126 u16 leafCorrection; /* 4 if pPage is a leaf. 0 if not */
65127 int leafData; /* True if pPage is a leaf of a LEAFDATA tree */
65142 u8 abDone[NB+2]; /* True after i'th new page is populated */
65160 ** this overflow cell is present, it must be the cell with
65162 ** is called (indirectly) from sqlite3BtreeDelete().
65172 ** that divide the siblings. An attempt is made to find NN siblings on
65224 ** This is safe because dropping a cell only overwrites the first
65226 ** four bytes of the divider cell. So the pointer is safe to use
65233 ** is allocated. */
65264 ** that is more than 6 times the database page size. */
65288 ** leafCorrection: 4 if pPage is a leaf. 0 if pPage is not a leaf.
65314 ** Note that when there are multiple overflow cells, it is always the
65318 ** adjacent and are inserted in order. There is an assert() tagged
65324 ** long be able to find the cells if a pointer to each cell is not saved
65386 ** Store this number in "k". Also compute szNew[] which is the total
65387 ** size of all cells on the i-th page and cntNew[] which is the index
65455 ** The packing computed by the previous block is biased toward the siblings
65461 ** This adjustment is more than an optimization. The packing above might
65463 ** sibling might be completely empty. This adjustment is not optional.
65499 ** (2) pPage is a virtual root page. A virtual root page is when
65500 ** the real root page is page 1 and we are the only child of
65544 ** of the table is closer to a linear scan through the file. That in turn
65547 ** An O(n^2) insertion sort algorithm is used, but since n is never more
65558 /* This branch is taken if the set of sibling pages somehow contains
65559 ** duplicate entries. This can happen if the database is corrupt.
65603 ** of the right-most new sibling page is set to the value that was
65646 /* Cell pCell is destined for new sibling page pNew. Originally, it
65683 /* If the tree is a leaf-data tree, and the siblings are leaves,
65684 ** then there is no divider cell in b.apCell[]. Instead, the divider
65699 ** (see btreeParseCellPtr(), 4 bytes is the minimum size of
65700 ** any cell). But it is important to pass the correct size to
65704 ** and WITHOUT ROWID tables with exactly one column which is the
65721 ** is important, as this code needs to avoid disrupting any page from which
65725 ** then it is not safe to update page apNew[iPg] until after
65729 ** then it is not safe to update page apNew[iPg] until after
65732 ** If neither of the above apply, the page is safe to update.
65747 || cntOld[iPg-1]>=cntNew[iPg-1] /* Condition (1) is true */
65787 ** page is the right-child of the parent. Copy the contents of the
65789 ** b-tree structure by one. This is described as the "balance-shallower"
65792 ** If this is an auto-vacuum database, the call to copyNodeContent()
65794 ** for which the pointer is stored within the content being copied.
65796 ** It is critical that the child page be defragmented before being
65797 ** copied into the parent, because if the parent is page 1 then it will
65833 ** all pointer map pages are set correctly. This is helpful while
65834 ** debugging. This is usually disabled because a corrupt database may
65858 ** This function is called when the root page of a b-tree structure is
65861 ** A new child page is allocated and the contents of the current root
65863 ** page is then overwritten to make it an empty page with the right-child
65869 ** page is also updated.
65871 ** If successful, *ppChild is set to contain a reference to the child
65872 ** page and SQLITE_OK is returned. In this case the caller is required
65874 ** an error code is returned and *ppChild is set to 0.
65948 /* The root page of the b-tree is overfull. In this case call the
65985 ** happens, the overflow cell is stored in the aBalanceQuickSpace[]
65988 ** The purpose of the following assert() is to check that only a
65989 ** single call to balance_quick() is made for each call to this
66011 ** has completed, it is safe to release the pSpace buffer used by
66020 /* If pFree is not NULL, it points to the pSpace buffer used
66052 ** is described by the pX object. The pCur cursor is used only to
66053 ** define what table the record should be inserted into, and is left
66057 ** the key is used. The pX.pKey value must be NULL. The pX.nKey is the
66062 ** key is an arbitrary byte sequence stored in pX.pKey,nKey. The
66065 ** If the seekResult parameter is non-zero, then a successful call to
66067 ** been performed. seekResult is the search result returned (a negative
66068 ** number if pCur points at an entry that is smaller than (pKey, nKey), or
66069 ** a positive value if pCur points at an entry that is larger than
66072 ** If the seekResult parameter is non-zero, then the caller guarantees that
66073 ** cursor pCur is pointing at the existing copy of a row that is to be
66074 ** overwritten. If the seekResult parameter is 0, then cursor pCur may
66081 int appendBias, /* True if this is likely an append */
66114 ** In some cases, the call to btreeMoveto() below is a no-op. For
66119 ** that the cursor is already where it needs to be and returns without
66120 ** doing any work. To avoid thwarting these optimizations, it is important
66130 /* If this is an insert into a table b-tree, invalidate any incrblob
66134 /* If the cursor is currently on the last row and we are appending a
66200 ** There is a subtle but important optimization here too. When inserting
66203 ** is advantageous to leave the cursor pointing to the last entry in
66204 ** the b-tree if possible. If the cursor is left pointing to the last
66206 ** larger than the largest existing key, it is possible to insert the
66215 /* Must make sure nOverflow is reset to zero even if the balance()
66229 ** Delete the entry that the cursor is pointing to.
66231 ** If the BTREE_SAVEPOSITION bit of the flags parameter is zero, then
66232 ** the cursor is left pointing at an arbitrary location after the delete.
66233 ** But if that bit is set, then the cursor is left in a state such that
66237 ** The BTREE_AUXDELETE bit of flags indicates that is one of several deletes
66239 ** deletes is considered the "primary" delete. The primary delete occurs
66240 ** on a cursor that is not a BTREE_FORDELETE cursor. All but one delete
66241 ** operation on non-FORDELETE cursors is tagged with the AUXDELETE flag.
66242 ** The BTREE_AUXDELETE bit is a hint that is not used by this implementation,
66272 /* If the bPreserve flag is set to true, then the cursor position must
66274 ** will cause a b-tree rebalance, then this is done by saving the cursor
66294 /* If the page containing the entry to delete is not a leaf page, move
66295 ** the cursor to the largest entry in the tree that is smaller than
66297 ** from the internal node. The 'previous' entry is used for this instead
66298 ** of the 'next' entry, as the previous entry is always a part of the
66314 /* If this is a delete operation to remove a row from a table b-tree,
66330 ** is currently pointing to the largest entry in the sub-tree headed
66356 ** call to balance() repairs the tree, and the if(...) condition is
66360 ** pCur is pointing to the leaf page from which a cell was removed to
66361 ** replace the cell deleted from the internal node. This is slightly
66403 ** The type of type is determined by the flags parameter. Only the
66439 ** root page of the new table should go. meta[3] is the largest root-page
66440 ** created so far, so the new root-page is (meta[3]+1).
66465 /* pgnoRoot is the page that will be used for the root-page of
66469 ** is already journaled.
66474 /* Save the positions of any open cursors. This is required in
66620 ** Delete all information from a single table in the database. iTable is
66622 ** the root page is empty, but still exists.
66628 ** If pnChange is not NULL, then table iTable must be an intkey table. The
66629 ** integer value pointed to by pnChange is incremented by the number of
66642 ** is the root of a table b-tree - if it is not, the following call is
66652 ** Delete all information from the single table that pCur is open on.
66663 ** page 1) is never added to the freelist.
66668 ** If AUTOVACUUM is enabled and the page at iTable is not the last
66670 ** in the database file is moved into the slot formerly occupied by
66672 ** is added to the freelist instead of iTable. In this say, all
66674 ** is necessary for AUTOVACUUM to work right. *piMoved is set to the
66676 ** the move. If no page gets moved, *piMoved is set to 0.
66677 ** The last root page is recorded in meta[3] and the value of
66678 ** meta[3] is updated by this procedure.
66688 /* It is illegal to drop a table if any cursors are open on the
66689 ** database. This is because in auto-vacuum mode the backend may
66694 ** This error is caught long before control reaches this point.
66702 ** It is illegal to drop the sqlite_master table on page 1. But again,
66703 ** this error is caught long before reaching this point.
66728 /* If the table being dropped is the table with the largest root-page
66763 ** is the old value less one, less one more if that happens to
66764 ** be a root-page number, less one again if that is the
66796 ** is the number of free pages currently in the database. Meta[1]
66798 ** is read-only, the others are read/write.
66802 ** free pages is not visible. So Cookie[0] is the same as Meta[1].
66806 ** from the pager. The BTREE_DATA_VERSION value is not actually stored in the
66807 ** database file. It is a number computed by the pager. But its access
66808 ** pattern is the same as header meta values, and so it is convenient to
66826 /* If auto-vacuum is disabled in this build and this is an auto-vacuum
66838 ** Write meta-information back into the database. Meta[0] is
66867 ** The first argument, pCur, is a cursor opened on some b-tree. Count the
66870 ** SQLITE_OK is returned if the operation is successfully executed.
66871 ** Otherwise, if an error is encountered (i.e. an IO error or database
66872 ** corruption) an SQLite error code is returned.
66891 /* If this is a leaf page or the tree is not an int-key tree, then
66900 /* pPage is a leaf node. This loop navigates the cursor so that it
66903 ** pCur->aiIdx[pCur->iPage] value is set to the index of the parent cell
66905 ** to visit is the right-child of its parent.
66925 ** points at. This is the right-child if (iIdx==pPage->nCell).
66941 ** Return the pager associated with a BTree. This routine is used for
66980 ** corresponds to page iPg is already set.
66997 ** Add 1 to the reference count for page iPage. If this is the second
67000 ** if this is the first reference to the page.
67002 ** Also check that the page number is in bounds.
67051 ** Verify that the number of pages on the list is N.
67103 /* If this database supports auto-vacuum and iPage is not the last
67117 checkAppendMsg(pCheck, "free-page count in header is too small");
67126 ** aHeap[0] is the number of elements on the heap. aHeap[1] is the
67130 ** The heap property is this: Every node is less than or equal to both
67131 ** of its daughter nodes. A consequence of the heap property is that the
67132 ** root node aHeap[1] is always the minimum value currently in the heap.
67140 ** This heap is used for cell overlap and coverage testing. Each u32
67187 ** 5. Verify that the depth of all children is the same.
67236 ** btreeInitPage() is executed. */
67370 ** is the offset of the first freeblock, or zero if there are no
67381 ** big-endian integer which is the offset in the b-tree page of the next
67382 ** freeblock in the chain, or zero if the freeblock is the last on the
67394 ** Each min-heap entry is of the form: (start_address<<16)|end_address.
67395 ** There is an implied first entry the covers the page header, the cell
67400 ** the start_address against the previous end_address. If there is an
67401 ** overlap, that means bytes are used multiple times. If there is a gap,
67402 ** that gap is added to the fragmentation count.
67418 ** is stored in the fifth field of the b-tree page header.
67441 ** This routine does a complete check of the given BTree file. aRoot[] is
67442 ** an array of pages numbers were each page number is the root page of
67443 ** a table. nRoot is the number of entries in aRoot.
67450 ** malloc is returned if *pnErr is non-zero. If *pnErr==0 then NULL is
67451 ** returned. If a memory allocation error occurs, NULL is returned.
67525 /* Make sure every page in the file is referenced
67530 checkAppendMsg(&sCheck, "Page %d is never used", i);
67538 checkAppendMsg(&sCheck, "Page %d is never used", i);
67542 checkAppendMsg(&sCheck, "Pointer map page %d is referenced", i);
67567 ** an empty string if the database is in-memory or a TEMP database.
67569 ** The pager filename is invariant as long as the pager is
67570 ** open so it is safe to access without the BtShared mutex.
67579 ** value of this routine is the same regardless of whether the journal file
67582 ** The pager journal filename is invariant as long as the pager is
67583 ** open so it is safe to access without the BtShared mutex.
67591 ** Return non-zero if a transaction is active.
67603 ** transaction on the shared-cache the argument Btree is connected to.
67605 ** Parameter eMode is one of SQLITE_CHECKPOINT_PASSIVE, FULL or RESTART.
67624 ** Return non-zero if a read (or write) transaction is active.
67640 ** a single shared-btree. The memory is used by client code for its own
67644 ** The first time this is called on a shared-btree, nBytes bytes of memory
67646 ** call the nBytes parameter is ignored and a pointer to the same blob
67649 ** If the nBytes parameter is 0 and the blob of memory has not yet been
67650 ** allocated, a null pointer is returned. If the blob has already been
67651 ** allocated, it is returned as normal.
67653 ** Just before the shared-btree is closed, the function passed as the
67654 ** xFree argument when the memory allocation was made is invoked on the
67687 ** Obtain a lock on the table whose root page is iTab. The
67688 ** lock is a write lock if isWritelock is true or a read lock
67689 ** if it is false.
67716 ** Only the data content may only be modified, it is not possible to
67717 ** change the length of the data stored. If this function is called with
67719 ** no modifications are made and SQLITE_CORRUPT is returned.
67736 /* Save the positions of all other cursors open on this table. This is
67748 ** (a) the cursor is open for writing,
67749 ** (b) there is a read/write transaction open,
67812 ** Return true if the cursor has a hint specified. This routine is
67820 ** Return true if the given Btree is read-only.
67833 ** Return true if the Btree passed as the only argument is sharable.
67842 ** this is always 1. For shared caches it may be 1 or greater.
67856 ** a legal notice, here is a blessing:
67876 int bDestLocked; /* True once a write-transaction is open on pDest */
67913 ** while some other thread is calling backup_step() or backup_finish(),
67914 ** the values returned may be invalid. There is no way for a call to
67929 ** If the "temp" database is requested, it may need to be opened by this
67977 ** Check that there is no open read-transaction on the b-tree passed as the
67978 ** second argument. If there is not, return SQLITE_OK. Otherwise, if there
67979 ** is an open read-transaction, return SQLITE_ERROR and leave an error
67984 sqlite3ErrorWithMsg(db, SQLITE_ERROR, "destination database is in use");
67995 ** If an error occurs, NULL is returned and an error code and error message
68014 ** handle is not locked in this routine, but it is locked in
68015 ** sqlite3_backup_step(). The user is required to ensure that no
68018 ** database connection while a backup is in progress may cause
68031 ** EVIDENCE-OF: R-64852-21591 The sqlite3_backup object is created by a
68032 ** call to sqlite3_backup_init() and is destroyed by a call to
68054 ** error was hit. Or there is a transaction open on the destination
68056 ** handle. All that is left to do here is free the sqlite3_backup
68072 ** Argument rc is an SQLite error code. Return true if this error is
68097 /* Use BtreeGetReserveNoMutex() for the source b-tree, as although it is
68098 ** guaranteed that the shared-mutex is held by this thread, handle
68112 /* Catch the case where the destination is an in-memory database and the
68120 /* Backup is not possible if the page size of the destination is changing
68121 ** and a codec is in use.
68127 /* Backup is not possible if the number of bytes of reserve space differ
68128 ** between source and destination. If there is a difference, try to
68129 ** fix the destination to agree with the source. If that is not possible,
68140 ** page. For each iteration, variable iOff is set to the byte offset
68158 ** cached parse of the page). MemPage.isInit is marked
68174 ** If pFile is currently larger than iSize bytes, then truncate it to
68175 ** exactly iSize bytes. If pFile is not larger than iSize bytes, then
68176 ** this function is a no-op.
68178 ** Return SQLITE_OK if everything is successful, or an SQLite error
68229 /* If the source pager is currently in a write-transaction, return
68238 /* Lock the destination database, if it is not locked already. */
68246 /* If there is no open read-transaction on the source database, open
68247 ** one now. If a transaction is opened here, then it will be closed
68255 /* Do not allow backup if the destination database is in WAL mode
68264 /* Now that there is a read-lock on the source database, query the
68292 ** is to make sure that the schema-version really does change in
68315 ** database. The complication here is that the destination page
68318 ** If the source page size is smaller than the destination page size,
68320 ** fix the size of the file. However it is important to call
68340 /* If the source page-size is smaller than the destination page-size,
68422 /* If bCloseTrans is true, then this function opened a read transaction
68423 ** on the source database. Close the read transaction here. There is
68476 /* If a transaction is still open on the Btree, roll it back. */
68489 /* EVIDENCE-OF: R-64852-21591 The sqlite3_backup object is created by a
68490 ** call to sqlite3_backup_init() and is destroyed by a call to
68527 ** This function is called after the contents of page iPage of the
68530 ** destination is now invalidated. The destination copy of iPage needs
68531 ** to be updated with the new data before the backup operation is
68534 ** It is assumed that the mutex associated with the BtShared object
68535 ** corresponding to the source database is held when this function is
68568 ** Restart the backup process. This is called when the pager layer
68570 ** connection. In this case there is no way of knowing which of the
68574 ** It is assumed that the mutex associated with the BtShared object
68575 ** corresponding to the source database is held when this function is
68592 ** goes wrong, the transaction on pTo is rolled back. If successful, the
68593 ** transaction is committed before returning.
68612 ** to 0. This is used by the implementations of sqlite3_backup_step()
68626 /* 0x7FFFFFFF is the hard limit for the number of pages in a database
68656 ** a legal notice, here is a blessing:
68665 ** stores a single value in the VDBE. Mem is an opaque structure visible
68676 ** This routine is intended for use inside of assert() statements, like
68680 /* If MEM_Dyn is set then Mem.xDel!=0.
68681 ** Mem.xDel is might not be initialized if MEM_Dyn is clear.
68686 ** ensure that if Mem.szMalloc>0 then it is safe to do
68720 ** If pMem is an object with a valid string representation, this routine
68721 ** ensures the internal encoding for the string representation is
68724 ** If pMem is not a string object, or the encoding of the string
68725 ** representation is already stored using the requested encoding, then this
68726 ** routine is a no-op.
68728 ** SQLITE_OK is returned if the conversion is successful (or not required).
68747 /* MemTranslate() may return SQLITE_OK or SQLITE_NOMEM. If NOMEM is returned,
68762 ** If the bPreserve argument is true, then copy of the content of
68764 ** blob if bPreserve is true. If bPreserve is false, any prior content
68765 ** in pMem->z is discarded.
68772 /* If the bPreserve flag is set to true, then the memory cell must already
68814 ** routine is a no-op.
68817 ** The pMem->xDel destructor is called, if it exists. Though MEM_Str
68837 ** Change pMem so that its MEM_Str or MEM_Blob value is stored in
68894 ** It is already known that pMem contains an unterminated string.
68908 ** Make sure the given Mem is \u0000 terminated.
68924 ** is a no-op.
68927 ** bForce is true but are retained if bForce is false.
68929 ** A MEM_Null value will never be passed to this function. This function is
68932 ** keys are strings. In the former case a NULL pointer is returned the
68933 ** user and the latter is an internal programming error.
68953 ** is UTF-16le or UTF-16be do a translation.
68974 ** result of the aggregate is stored back into pMem.
69007 ** This is a helper routine for sqlite3VdbeMemSetNull() and
69037 ** This is a helper routine invoked by sqlite3VdbeMemRelease() in
69038 ** the unusual case where there really is memory in p that needs
69053 ** Release any memory resources held by the Mem. Both the memory that is
69071 ** If the double is out of range of a 64-bit signed integer then
69076 /* When floating-point is omitted, double and int64 are the same thing */
69100 ** Return some kind of integer value which is the best we can do
69102 ** If pMem is an integer, then the value is exact. If pMem is
69103 ** a floating-point then the value returned is the integer part.
69104 ** If pMem is a string or blob, then we make an attempt to convert
69131 ** double. If pMem is already a double or an integer, return its
69132 ** value. If it is a string or blob, try to convert it to a double.
69133 ** If it is a NULL, return 0.0.
69154 ** The MEM structure is already a MEM_Real. Try to also make it a
69168 ** (1) the round-trip conversion real->int->real is a no-op, and
69169 ** (2) The integer is neither the largest nor the smallest
69196 ** Convert pMem so that it is of type MEM_Real.
69212 ** Every effort is made to force the conversion, even if the input
69213 ** is a string that does not look completely like a number. Convert
69235 ** "aff". Casting is different from applying affinity in that a cast
69236 ** is forced. In other words, the value is converted into the desired
69237 ** affinity even if that results in loss of data. This routine is
69280 ** The minimum amount of initialization feasible is performed.
69328 ** The pMem is known to contain content that needs to be destroyed prior
69388 ** Return true if the Mem object contains a TEXT or BLOB that is
69409 ** This is used for testing and debugging only - to make sure shallow
69428 ** pTo are freed. The pFrom->z field is not duplicated. If
69429 ** pFrom->z is used, then pTo->z points to the same thing as pFrom->z
69451 ** freed before the copy is made.
69471 ** Transfer the contents of pFrom to pTo. Any existing value in pTo is
69472 ** freed. If pFrom contains ephemeral data, a copy is made.
69491 ** parameter. If the value passed is SQLITE_TRANSIENT, then the
69492 ** string is copied into a (possibly existing) buffer managed by the
69493 ** Mem structure. Otherwise, any existing buffer is freed and the
69496 ** If the string is too large (if it exceeds the SQLITE_LIMIT_LENGTH
69498 ** stored without allocating memory, then it is. If a memory allocation
69499 ** is required to store the string, then value of pMem is unchanged. In
69500 ** either case, SQLITE_TOOBIG is returned.
69516 /* If z is a NULL pointer, set pMem to contain an SQL NULL. */
69588 ** The data or key is taken from the entry that pCur is currently pointing
69590 ** key is true to get the key or false to get data. The result is written
69596 ** is responsible for making sure that the pMem object is eventually
69600 ** to read from the disk) then the pMem is left in an inconsistent state.
69660 ** The pVal argument is known to be a value other than NULL.
69698 /* This function is only available internally, it is not part of the
69700 ** except the data returned is in the encoding specified by the second
69705 ** If that is the case, then the result must be aligned on an even byte
69747 ** the second argument to this function is NULL, the object is allocated
69750 ** Otherwise, if the second argument is non-zero, then this function is
69798 ** The expression object indicated by the second argument is guaranteed
69802 ** * one of the SQLITE_FUNC_CONSTANT or _SLOCHNG function flags is set, and
69803 ** * the SQLITE_FUNC_NEEDCOLL function flag is not set,
69806 ** error occurs, output parameter (*ppVal) is set to point to a value
69809 ** Affinity aff is applied to the result of the function before returning.
69810 ** If the result is a text value, the sqlite3_value object uses encoding
69814 ** and sets (*ppVal) to NULL. Or, if an error occurs, (*ppVal) is set to
69907 ** If pCtx is NULL and an error occurs after the sqlite3_value object
69908 ** has been allocated, it is freed before returning. Or, if pCtx is not
69909 ** NULL, it is assumed that the caller will free any allocated object
69936 ** check ensures that an EP_TokenOnly expression is never passed down
69951 /* Handle negative integers in a single step. This is needed in the
69952 ** case when the value is -9223372036854775808.
70042 ** be converted directly into a value, then the value is allocated and
70043 ** a pointer written to *ppVal. The caller is responsible for deallocating
70045 ** cannot be converted to a value, then *ppVal is set to NULL.
70060 ** a single argument of any type. The return value is a formatted database
70063 ** This is used to convert the value stored in the 'sample' column of the
70110 ** If pAlloc is not NULL, then an UnpackedRecord object is created for
70111 ** pAlloc if one does not exist and the new value is added to the
70114 ** A value is extracted in the following cases:
70116 ** * (pExpr==0). In this case the value is assumed to be an SQL NULL,
70118 ** * The expression is a bound variable, and this is a reprepare, or
70120 ** * The expression is a literal value.
70122 ** On success, *ppVal is made to point to the extracted value. The caller
70123 ** is responsible for ensuring that the value is eventually freed.
70170 ** This function is used to allocate and populate UnpackedRecord
70175 ** is 0 etc.) of the unpacked record with a value extracted from expression
70176 ** pExpr. Extraction of values is possible if:
70178 ** * (pExpr==0). In this case the value is assumed to be an SQL NULL,
70180 ** * The expression is a bound variable, and this is a reprepare, or
70182 ** * The sqlite3ValueFromExpr() function is able to extract a value
70183 ** from the expression (i.e. the expression is a literal value).
70186 ** is applied to it before it is copied into the UnpackedRecord. Output
70187 ** parameter *pbOk is set to true if a value is extracted, or false
70190 ** When this function is called, *ppRec must either point to an object
70192 ** is NULL and a value can be successfully extracted, a new UnpackedRecord
70193 ** is allocated (and *ppRec set to point to it) before returning.
70195 ** Unless an error is encountered, SQLITE_OK is returned. It is not an
70197 ** occur, an SQLite error code is returned.
70231 ** is undefined in this case.
70244 ** the column value into *ppVal. If *ppVal is initially NULL then a new
70245 ** sqlite3_value object is allocated.
70247 ** If *ppVal is initially NULL then the caller is responsible for
70248 ** ensuring that the value written into *ppVal is eventually freed.
70291 ** Unless it is NULL, the argument must be an UnpackedRecord object returned
70335 ** The valueBytes() routine is a helper function.
70363 ** a legal notice, here is a blessing:
70371 ** a VDBE (or an "sqlite3_stmt" as it is known to the outside world.)
70448 ** Resize the Vdbe.aOp array so that it is at least nOp elements larger
70449 ** than its current size. nOp is guaranteed to be less than or equal
70454 ** unchanged (this is so that any opcodes already allocated can be
70461 /* The SQLITE_TEST_REALLOC_STRESS compile-time option is designed to force
70463 ** simulated OOM faults. SQLITE_TEST_REALLOC_STRESS is generally used
70466 ** operation (without SQLITE_TEST_REALLOC_STRESS) is to double the current
70467 ** size of the op array or add 1KB of space, whichever is smaller. */
70487 /* This routine is just a convenient place to set a breakpoint that will
70488 ** fire after each opcode is inserted and displayed using
70591 ** One register is initialized for each characgter in zTypes[]. For each
70592 ** "s" character in zTypes[], the register is a string if the argument is
70593 ** not NULL, or OP_Null if the value is a null pointer. For each "i" character
70594 ** in zTypes[], the register is initialized to an integer.
70649 ** Add an OP_ParseSchema opcode. This routine is broken out from
70695 ** coded. The symbolic label is really just a negative number. The
70697 ** the label is resolved to a specific address, the VDBE will scan
70701 ** The VDBE knows that a P2 value is a label because labels are
70703 ** Hence, a negative P2 value is a label that has yet to be resolved.
70705 ** Zero is returned if a malloc() fails.
70763 ** sIter.v = v; // v is of type Vdbe*
70825 ** to be rolled back). This condition is true if the main program or any
70836 ** Then check that the value of Parse.mayAbort is true if an
70838 ** match, or false otherwise. This function is intended to be used as
70883 ** This routine is called after all opcodes have been inserted. It loops
70917 ** it is larger than SQLITE_MX_JUMP_OPCODE, as a performance optimization.
70995 ** SQLITE_TEST_REALLOC_STRESS). This interface is used during testing
71008 ** the Vdbe passed as the first argument. It is the callers responsibility
71012 ** Before returning, *pnOp is set to the number of entries in the returned
71013 ** array. Also, *pnMaxArg is set to the larger of its current value and
71035 ** so that the jump target is relative to the first operation inserted.
71140 ** If the input FuncDef structure is ephemeral, then free it. If
71141 ** the FuncDef is not ephermal, then do nothing.
71211 ** opcodes contained within. If aOp is not NULL it is assumed to contain
71229 ** list at Vdbe.pSubProgram. This list is used to delete all sub-program
71230 ** objects when the VM is no longer required.
71253 ** If the last opcode is "op" and it is not a jump destination,
71266 ** This routine is useful when a large program is loaded from a
71270 ** If n>=0 then the P4 operand is dynamic, meaning that a copy of
71271 ** the string is made into memory obtained from sqlite3_malloc().
71276 ** to a string or structure that is guaranteed to exist for the lifetime of
71322 /* Note: this cast is safe, because the origin data point was an int
71391 ** Return the opcode for a given address. If the address is -1, then
71396 ** is readable but not writable, though it is cast to a writable value.
71399 ** this routine is a valid pointer. But because the dummy.opcode is 0,
71400 ** dummy will never be written to. This is verified by code inspection and
71405 ** zeros, which is correct. MSVC generates a warning, nevertheless. */
71436 ** to an extra string that is appended to the sqlite3OpcodeName(). In the
71441 ** "PX@PY" -> "r[X..X+Y-1]" or "r[x]" if y is 0 or 1
71442 ** "PX@PY+1" -> "r[X..X+Y]" or "r[x]" if y is 0
71669 int n = ai[0]; /* The first element of an INTARRAY is always the
71705 ** Declare to the Vdbe that the BTree object at db->aDb[i] is used.
71709 ** is maintained in p->btreeMask. The p->lockMask value is the subset of
71723 ** If SQLite is compiled to support shared-cache mode and to be threadsafe,
71727 ** that the correct busy-handler callback is invoked if required.
71729 ** If SQLite is not threadsafe but does support shared-cache mode, then
71730 ** sqlite3BtreeEnter() is invoked to set the BtShared.db variables
71734 ** If SQLite is not threadsafe and does not support shared-cache mode, this
71735 ** function is a no-op.
71737 ** The p->btreeMask field is a bitmask of all btrees that the prepared
71740 ** this routine is N*N. But as N is rarely more than 1, this should not
71786 ** Print a single opcode. This routine is used for debugging only.
71800 /* NB: The sqlite3OpcodeName() function is implemented by code created
71828 /* This block is really an inlined version of sqlite3VdbeMemRelease()
71829 ** that takes advantage of the fact that the memory cell value is
71832 ** The justification for duplicating code is that according to
71836 ** to 6.6 percent. The test case is inserting 1000 rows into a table
71876 ** The interface is the same as sqlite3VdbeExec(). But instead of
71878 ** This feature is used to implement "EXPLAIN".
71880 ** When p->explain==1, each instruction is listed. When
71882 ** are shown in a different format. p->explain==2 is used to implement
71885 ** When p->explain==1, first the main program is listed, then each of
71920 ** nRow is the sum of the number of rows in the main program, plus
71929 ** to trigger subprograms. The VDBE is guaranteed to have at least 9
71934 /* On the first call to sqlite3_step(), pSub will hold a NULL. It is
71958 /* The output line number is small enough that we are still in the
71983 /* When an OP_Program opcode is encounter (the only opcode that has
72113 ** by subcomponents of a prepared statement. Space is allocated out
72124 ** memory on success. If insufficient memory is available in the
72128 ** If pBuf is not initially NULL, that means that the memory has already
72132 ** This allocator is employed to repurpose unused slots at the end of the
72202 ** After this routine is called the VM has been "packaged" and is ready
72203 ** to run. After this routine is called, further calls to
72240 ** use aMem[0] which is not otherwise used by the VDBE program. Allocate
72247 /* Figure out how much reusable memory is available at the end of the
72268 /* Memory for registers, parameters, cursor, etc, is allocated in one or two
72373 ** is used, for example, when a trigger sub-program is halted to restore
72403 ** cell array. This is necessary as the memory cell array may contain
72454 ** statement. This is now set at compile time, rather than during
72483 ** or SQLITE_TRANSIENT. If it is SQLITE_DYNAMIC, then the buffer pointed
72484 ** to by zName will be freed by sqlite3DbFree() when the vdbe is destroyed.
72510 ** db. If a transaction is active, commit it. If there is a
72523 /* With this option, sqlite3VtabSync() is defined to be simply
72524 ** SQLITE_OK so p is not used.
72531 ** be done before determining whether a master journal file is
72539 ** including the temp database. (b) is important because if more than
72541 ** file is required for an atomic commit.
72584 ** TEMP database) has a transaction active. There is no need for the
72587 ** If the return value of sqlite3BtreeGetFilename() is a zero length
72588 ** string, it means the main database is :memory: or a temp file. In
72604 ** IO error while deleting or truncating a journal file. It is unlikely,
72618 /* The complex case - There is a multi-file write-transaction active.
72619 ** This requires a master journal file to ensure the transaction is
72696 ** flag is set this is not required.
72712 ** sqlite3BtreeCommitPhaseOne(), then there is a chance that the
72731 ** doing this the directory is synced again before any individual
72744 ** this is happening we don't really care. The integrity of the
72745 ** transaction is already guaranteed, but some stray 'cold' journals
72770 ** This is an internal self-check only - it is not an essential processing
72773 ** This is a no-op if NDEBUG is defined.
72801 ** SAVEPOINT_RELEASE. If it is SAVEPOINT_ROLLBACK, then the statement
72802 ** transaction is rolled back. If eOp is SAVEPOINT_RELEASE, then the
72803 ** statement transaction is committed.
72805 ** If an IO error occurs, an SQLITE_IOERR_XXX error code is returned.
72812 /* If p->iStatement is greater than zero, then this Vdbe opened a
72814 ** is that an IO error may have occurred, causing an emergency rollback.
72815 ** In this case (db->nStatement==0), and there is nothing to do.
72852 /* If the statement transaction is being rolled back, also restore the
72864 ** This function is called when a transaction opened by the database
72865 ** handle associated with the VM passed as an argument is about to be
72889 ** This routine is called the when a VDBE tries to halt. If the VDBE
72890 ** has made changes and is in autocommit mode, then commit those
72891 ** changes. If a rollback is needed, then do the rollback.
72893 ** This routine is the only way to move the state of a VM from
72894 ** SQLITE_MAGIC_RUN to SQLITE_MAGIC_HALT. It is harmless to
72895 ** call this on a VM that is in the SQLITE_MAGIC_HALT state.
72898 ** lock contention, return SQLITE_BUSY. If SQLITE_BUSY is returned, it
72917 ** state. We need to rollback the statement transaction, if there is
72918 ** one, or the complete transaction if there is no statement transaction.
72946 /* If the query was read-only and the error code is SQLITE_INTERRUPT,
72947 ** no rollback is necessary. Otherwise, at least a savepoint
72951 ** Even if the statement is read-only, it is important to perform
72955 ** pagerStress() in pager.c), the rollback is required to restore
72978 /* If the auto-commit flag is set and this is the only active writer
72997 /* The auto-commit flag is true, the vdbe program was successful
73000 ** is required. */
73034 /* If eStatementOp is non-zero, then a statement transaction needs to
73037 ** error code is SQLITE_OK or SQLITE_CONSTRAINT, then promote the
73086 /* If the auto-commit flag is set to true, then any locks that were held
73134 ** If an SQLITE_CONFIG_SQLLOG hook is registered and the VM has been run,
73157 ** After this routine is run, the VDBE should be ready to be executed
73241 ** Clean up and delete a VDBE after execution. Return an integer which is
73255 ** If parameter iOp is less than zero, then invoke the destructor for
73259 ** Or, if iOp is greater than or equal to zero, then the destructor is
73264 ** * the associated function parameter is the 32nd or later (counting
73267 ** * the corresponding bit in argument mask is clear (where the first
73290 ** except for object itself, which is preserved.
73292 ** The difference between this function and sqlite3VdbeDelete() is that
73373 ** is supposed to be pointing. If the row was deleted out from under the
73388 ** Check to ensure that the cursor is valid. Restore the cursor
73400 ** Make sure the cursor p is ready to read or write the row to which it
73404 ** If a MoveTo operation is pending on the given cursor, then do that
73405 ** MoveTo now. If no move is pending, check to see if the row has been
73409 ** If the cursor is already pointing to the correct row and that row has
73410 ** not been deleted out from under the cursor, then this routine is a no-op.
73442 ** 'serial-type' and a blob of data. The serial type is an 8-byte unsigned
73445 ** In an SQLite index record, the serial type is stored directly before
73567 ** For most architectures, this is a no-op.
73569 ** (later): It is reported to me that the mixed-endian problem
73570 ** on ARM7 is an issue with GCC, not with the ARM7 chip. It seems
73573 ** ever since. The blame is not necessarily with GCC, though.
73581 ** floating point values is correct.
73587 ** 48-bits as required by the IEEE standard. (This is the
73590 ** the necessary byte swapping is carried out using a 64-bit integer
73593 ** verify this, but Frank seems to know what he is talking about
73617 ** buf. It is assumed that the caller has allocated sufficient space.
73620 ** nBuf is the amount of space left in buf[]. The caller is responsible
73625 ** of bytes in the zero-filled tail is included in the return value only
73664 /* Input "x" is a sequence of unsigned characters that represent a
73677 ** This function is implemented as two separate routines for performance.
73680 ** is avoided.
73691 /* EVIDENCE-OF: R-29851-52272 Value is a big-endian 64-bit
73697 /* EVIDENCE-OF: R-57343-49114 Value is a big-endian IEEE 754-2008 64-bit
73701 ** byte order. Or, that if SQLITE_MIXED_ENDIAN_64BIT_FLOAT is
73727 /* EVIDENCE-OF: R-24078-09375 Value is a NULL. */
73732 /* EVIDENCE-OF: R-44885-25196 Value is an 8-bit twos-complement
73740 /* EVIDENCE-OF: R-49794-35026 Value is a big-endian 16-bit
73748 /* EVIDENCE-OF: R-37839-54301 Value is a big-endian 24-bit
73756 /* EVIDENCE-OF: R-01849-26079 Value is a big-endian 32-bit
73768 /* EVIDENCE-OF: R-50385-09674 Value is a big-endian 48-bit
73783 /* EVIDENCE-OF: R-12976-22893 Value is the integer 0. */
73784 /* EVIDENCE-OF: R-18143-12121 Value is the integer 1. */
73790 /* EVIDENCE-OF: R-14606-31564 Value is a BLOB that is (N-12)/2 bytes in
73792 ** EVIDENCE-OF: R-28401-00140 Value is a string in the text encoding and
73804 ** This routine is used to allocate sufficient space for an UnpackedRecord
73806 ** the first argument is a pointer to KeyInfo structure pKeyInfo.
73808 ** The space is either allocated using sqlite3DbMallocRaw() or from within
73810 ** stack space). If the former, then *ppFree is set to a pointer that should
73812 ** allocation comes from the pSpace/szSpace buffer, *ppFree is set to NULL
73815 ** If an OOM error occurs, NULL is returned.
73827 /* We want to shift the pointer pSpace up such that it is 8-byte aligned.
73829 ** it by. If pSpace is already 8-byte aligned, nOff should be zero.
73894 ** sqlite3VdbeSerialGet() and sqlite3MemCompare() functions. It is used
73898 ** Return true if the result of comparison is equivalent to desiredResult.
73899 ** Return false if there is a disagreement.
73922 /* Compilers may complain that mem1.u.i is potentially uninitialized.
73926 ** impact, since this routine is a very high runner. And so, we choose
73944 /* Verify that there is enough key space remaining to avoid
73973 /* No memory allocation is ever used on mem1. Prove this using
73997 ** pKey,nKey. The verify that this count is less than or equal to the
74000 ** If this constraint is not satisfied, it means that the high-speed
74033 ** or positive value if *pMem1 is less than, equal to or greater than
74070 ** is less than, equal to, or greater than the second, respectively.
74071 ** If one blob is a prefix of the other, then the shorter is the lessor.
74081 ** number. Return negative, zero, or positive if the first (i64) is less than,
74110 ** negative, zero or positive if pMem1 is less than, equal to, or greater
74111 ** than pMem2. Sorting order is NULL's first, followed by numbers (integers
74126 /* If one value is NULL, it is less than the other. If both values
74133 /* At least one of the two values is a number
74163 /* If one value is a string and the other is a blob, the string is less.
74179 ** the user deletes the collation sequence after the vdbe program is
74197 ** The first argument passed to this function is a serial-type that
74240 ** or positive integer if key1 is less than, equal to or
74246 ** If argument bSkip is non-zero, it is assumed that the caller has already
74250 ** fields that appear in both keys are equal, then pPKey2->default_rc is
74253 ** If database corruption is discovered, set pPKey2->errCode to
74254 ** SQLITE_CORRUPT and return 0. If an OOM error is encountered,
74255 ** pPKey2->errCode is set to SQLITE_NOMEM and, if it is not NULL, the
74273 /* If bSkip is true, then the caller has already determined that the first
74302 /* RHS is an integer */
74324 /* RHS is real */
74349 /* RHS is a string */
74380 /* RHS is a blob */
74401 /* RHS is null */
74422 /* No memory allocation is ever used on mem1. Prove this using
74446 ** This function is an optimized version of sqlite3VdbeRecordCompare()
74447 ** that (a) the first field of pPKey2 is an integer, and (b) the
74449 ** byte (i.e. is less than 128).
74451 ** To avoid concerns about buffer overreads, this routine is only used
74452 ** on schemas where the maximum valid header size is 63 bytes or less.
74512 ** is contiguous) but does not cause any duplicate code to be generated
74513 ** (as gcc is clever enough to combine the two like cases). Other
74542 ** This function is an optimized version of sqlite3VdbeRecordCompare()
74543 ** that (a) the first field of pPKey2 is a string, that (b) the first field
74559 res = pPKey2->r1; /* (pKey1/nKey1) is a number or a null */
74561 res = pPKey2->r2; /* (pKey1/nKey1) is a blob */
74611 ** fits in a single byte (i.e. is 127 or less). varintRecordCompareInt()
74612 ** also assumes that it is safe to overread a buffer by at least the
74613 ** maximum possible legal header size plus 8 bytes. Because there is
74617 ** is an integer.
74619 ** The easiest way to enforce this limit is to consider only records with
74620 ** 13 fields or less. If the first field is an integer, the maximum legal
74621 ** header size is (12*5 + 1 + 1) bytes. */
74664 ** Any corruption is detected in sqlite3BtreeParseCellPtr(), though, so
74665 ** this code can safely assume that nCellKey is 32-bits
74687 ** Verify that the last entry really is an integer. */
74712 /* Jump here if database corruption is detected after m has been
74721 ** Compare the key of the index entry that cursor pC is pointing to against
74723 ** that is negative, zero, or positive if pC is less than, equal to,
74726 ** pUnpacked is either created without a rowid or is truncated so that it
74728 ** is ignored as well. Hence, this routine only compares the prefixes
74773 ** Set a flag in the vdbe to update the change counter when it is finalised
74784 ** An expired statement means that recompilation of the statement is
74806 ** parameter iVar of VM v. Except, if the value is an SQL NULL, return
74807 ** 0 instead. Unless it is NULL, apply affinity aff (one of the SQLITE_AFF_*
74862 ** If the second argument is not NULL, release any allocations associated
74866 ** This function is used to free UnpackedRecord structures allocated by
74883 ** Invoke the pre-update hook. If this is an UPDATE or DELETE pre-update call,
74889 Vdbe *v, /* Vdbe pre-update hook is invoked by */
74949 ** a legal notice, here is a blessing:
74969 ** collating sequences are registered or if an authorizer function is
74980 ** an error and return true if it has been finalized (or is otherwise
74981 ** invalid). Return false if it is ok.
75002 ** Invoke the profile callback. This routine is only called if we already
75003 ** know that the profile callback is defined and needs to be invoked.
75024 ** is needed, and it invokes the callback if it is needed.
75033 ** The following routine destroys a virtual machine that is created by
75034 ** the sqlite3_compile() routine. The integer returned is an SQLITE_
75045 ** pointer is a harmless no-op. */
75063 ** the prior execution is returned.
75236 ** result as a string or blob but if the string or blob is too large, it
75240 ** on value P is not going to be used and need to be destroyed.
75431 ** This function is called after a transaction has been committed. It
75456 ** Execute the statement pStmt, either until a row of data is ready, the
75457 ** statement is completely executed or an error occurs.
75460 ** API. The only thing omitted is the automatic recompile if a
75461 ** schema change has occurred. That detail is handled by the
75474 ** This "automatic-reset" change is not technically an incompatibility,
75475 ** since any application that receives an SQLITE_MISUSE is broken by
75590 ** This is the top-level implementation of sqlite3_step(). Call
75621 ** program counter to 0 to ensure that when the statement is
75622 ** finalized or reset the parser error message is available via
75667 ** is requested more than once within the same run of a single prepared
75668 ** statement, the exact same time is returned for each invocation regardless
75670 ** the time returned is always the time of the first call.
75689 ** The following is the implementation of an SQL function that always
75690 ** fails with an error message stating that the function is used in the
75733 ** context is allocated on the first call. Subsequent calls return the
75769 ** argument to the user-function defined by pCtx. Any previous value is
75822 ** This function is deprecated. Do not use it for new code. It is
75860 ** that a Mem structure is located on an 8-byte boundary. To prevent
75889 ** Check to see if column iCol of the given statement is valid. If
75890 ** it is, return a pointer to the Mem for the value of that column.
75891 ** If iCol is not valid, return a pointer to a Mem which has a value
75913 ** This function is called after invoking an sqlite3_value_XXX function on a
75916 ** malloc() has failed, the threads mallocFailed flag is cleared and the result
75919 ** Specifically, this is called from within:
75951 /* Even though there is no encoding conversion, value_blob() might
76012 ** xFunc() then return that string. If N is out of range, return 0.
76015 ** name is returned. Here are the names:
76023 ** If the result is not a simple column reference (if it is an expression
76053 ** is the case, clear the mallocFailed flag and return NULL.
76108 ** NULL is returned if the result column is an expression or constant or
76109 ** anything else which is not an unambiguous reference to a database column.
76124 ** NULL is returned if the result column is an expression or constant or
76125 ** anything else which is not an unambiguous reference to a database column.
76140 ** NULL is returned if the result column is an expression or constant or
76141 ** anything else which is not an unambiguous reference to a database column.
76161 ** Unbind the value bound to variable i in virtual machine p. This is the
76162 ** the same as binding a NULL value to the column. If the "i" parameter is
76163 ** out of range, then SQLITE_RANGE is returned. Othewise SQLITE_OK.
76166 ** the mutex is released if any kind of error occurs.
76168 ** The error code stored in database p->db is overwritten with the return
76195 /* If the bit corresponding to this variable in Vdbe.expmask is set, then
76401 ** This routine is added to support DBD::SQLite.
76410 ** is out of range or if the wildcard is unnamed.
76412 ** The result is always UTF-8.
76424 ** with that name. If there is no variable with the given name,
76468 ** It is misuse to call this routine with statements from different
76469 ** database connections. But as this is a deprecated interface, we
76473 ** an SQLITE_ERROR is returned. Nothing else can go wrong, so otherwise
76474 ** SQLITE_OK is returned.
76494 ** in the argument belongs. This is the same database handle that was
76503 ** Return true if the prepared statement is guaranteed to not modify the
76511 ** Return true if the prepared statement is in need of being reset.
76520 ** with database connection pDb. If pStmt is NULL, return the first
76569 ** bound parameters expanded. Space to hold the returned string is
76570 ** obtained from sqlite3_malloc(). The caller is responsible for
76596 ** if successful, or a NULL pointer if an OOM error is encountered.
76615 ** This function is called from within a pre-update callback to retrieve
76622 /* Test that this call is being made from within an SQLITE_DELETE or
76623 ** SQLITE_UPDATE pre-update callback, and that iIdx is within range. */
76670 ** This function is called from within a pre-update callback to retrieve
76681 ** This function is designed to be called from within a pre-update callback
76689 ** or SET DEFAULT action is considered a trigger.
76699 ** This function is called from within a pre-update callback to retrieve
76718 ** that is being inserted. Deserialize it. */
76742 ** It is not safe to return a pointer to the memory cell itself as the
76847 ** a legal notice, here is a blessing:
76858 ** The Vdbe parse-tree explainer is also found here.
76866 ** zSql is a zero-terminated string of UTF-8 SQL text. Return the number of
76892 ** obtained from sqlite3DbMalloc(). If sqlite3.nVdbeExec is 1, then the
76894 ** their current bindings. Or, if sqlite3.nVdbeExec is greater than 1,
76898 ** If the SQLITE_TRACE_SIZE_LIMIT macro is defined to an integer, then
76903 ** The calling function is responsible for making sure the memory returned
76904 ** is eventually freed.
76909 ** the host parameter index is found by scanning the prepared
76911 ** parameter index is known, locate the value in p->aVar[]. Then render
77044 ** a legal notice, here is a blessing:
77056 ** of the code in this file is, therefore, important. See other comments
77068 ** is changed while the copy is still in use, the string or blob might
77079 ** The following global variable is incremented every time a cursor
77090 ** When this global variable is positive, it gets decremented once before
77092 ** field of the sqlite3 structure is set in order to simulate an interrupt.
77094 ** This facility is used for testing purposes only. It does not function
77102 ** The next global variable is incremented each type the OP_Sort opcode
77103 ** is executed. The test procedures use this information to make sure that
77104 ** sorting is occurring or not occurring at appropriate times. This variable
77116 ** is working correctly. This variable has no function other than to
77139 ** The next global variable is incremented each time the OP_Found opcode
77140 ** is executed. This is used to test whether or not the foreign key
77141 ** operation implemented using OP_FkIsZero is working. This variable
77160 ** Invoke the VDBE coverage callback, if that callback is defined. This
77161 ** feature is used for test suite validation only and does not appear an
77164 ** M is an integer, 2 or 3, that indices how many different ways the
77165 ** branch can go. It is usually 2. "I" is the direction the branch
77166 ** goes. 0 means falls through. 1 means branch is taken. 2 means the
77167 ** second alternative branch is taken.
77169 ** iSrcLine is the source code line (from the __LINE__ macro) that
77171 ** source code is in a single file (the amalgamation). Special values 1
77172 ** and 2 for the iSrcLine parameter mean that this particular branch is
77204 ** is responsible for deallocating that string. Because the register
77231 ** required for this VdbeCursor structure. It is convenient to use a
77244 ** The memory cell for cursor 0 is aMem[0]. The rest are allocated from
77245 ** the top of the register space. Cursor 1 is at Mem[p->nMem-1].
77246 ** Cursor 2 is at Mem[p->nMem-2]. And so forth.
77283 ** If the bTryForInt flag is true, then extra effort is made to give
77286 ** will have a MEM_Int representation when bTryForInt is true.
77288 ** If bTryForInt is false, then if the input string contains a decimal
77289 ** point or exponential notation, the result is only MEM_Real, even
77290 ** if there is an exact integer representation of the quantity.
77309 ** Processing is determine by the affinity parameter:
77316 ** is not possible. Note that the integer representation is
77317 ** always preferred, even if the affinity is REAL, because
77318 ** an integer representation is more space efficient on disk.
77324 ** No-op. pRec is unchanged.
77342 /* Only attempt the conversion to TEXT if there is an integer or real
77345 ** there is already a string rep, but it is pointless to waste those
77359 ** is appropriate. But only do the conversion if it is possible without
77554 ** a legal notice, here is a blessing:
77643 ** This function is only called from within an assert() expression. It
77644 ** checks that the sqlite3.nTransaction variable is correctly set to
77687 ** This is the core of sqlite3_step().
77785 /* Only allow tracing if SQLITE_DEBUG is defined.
77850 ** What follows is a massive switch statement where each case implements a
77853 ** that is a lot of wasted space on the left margin. So the code within
77858 ** The formatting of each case is important. The makefile for SQLite
77862 ** opcode and the opcodes.c file is filled with an array of strings where
77863 ** each string is the symbolic name for the corresponding opcode. If the
77864 ** case statement is followed by a comment of the form "/# same as ... #/"
77865 ** that comment is used to determine the particular value of the opcode.
77872 ** Documentation about VDBE opcodes is generated by scanning this file
77879 ** Formatting is important to scripts that scan this file.
77891 ** The P1 parameter is not actually used by this opcode. However, it
77892 ** is sometimes set to 1 instead of 0 as a hint to the command-line shell
77893 ** that this Goto is the bottom of a loop and that the lines from P2 down
77906 ** But that is not due to sloppy coding habits. The code is written this
77913 /* Call the progress callback if it is configured and the required number
77991 ** The instruction at the address in register P1 is a Yield.
78015 ** If the coroutine that is launched by this instruction ends with
78038 ** Check the value in register P3. If it is NULL then Halt using
78040 ** value in register P3 is not NULL, then this routine is a no-op.
78054 ** P1 is the result code returned by sqlite3_exec(), sqlite3_reset(),
78062 ** If P4 is not null then it is an error message string.
78064 ** P5 is a value between 0 and 4, inclusive, that modifies the P4 string.
78072 ** If P5 is not zero and P4 is NULL, then everything after the ":" is
78075 ** There is an implied "Halt 0 0 0" instruction inserted at the very end of
78077 ** is the same as executing Halt.
78093 /* Instruction pcx is the OP_Program that invoked the sub-program
78095 ** instruction is set to OE_Ignore, then the sub-program is throwing
78141 ** The 32-bit integer value P1 is written into register P2.
78152 ** P4 is a pointer to a 64-bit integer value.
78166 ** P4 is a pointer to a 64-bit floating point value.
78181 ** P4 points to a nul terminated UTF-8 string. This opcode is transformed
78182 ** into a String opcode before it is executed for the first time. During
78183 ** this transformation, the length of string P4 is computed and stored
78220 ** The string value P4 of length P1 (bytes) is stored in register P2.
78222 ** If P3 is not zero and the content of register P3 is equal to P5, then
78223 ** the datatype of the register P2 is converted to BLOB. The content is
78224 ** the same sequence of bytes, it is merely interpreted as a BLOB instead
78253 ** is less than P2 (typically P3 is zero) then only register P2 is
78256 ** If the P1 value is non-zero, then also set the MEM_Cleared flag so that
78257 ** NULL values will not compare equal even if SQLITE_NULLEQ is set on
78312 ** If the parameter is named, then its name appears in P4.
78313 ** The P4 value is used by sqlite3_bind_parameter_name().
78335 ** left holding a NULL. It is an error for register ranges
78336 ** P1..P1+P3-1 and P2..P2+P3-1 to overlap. It is an error
78377 ** is made of any string or blob constant. See also OP_SCopy.
78406 ** is a string or blob, then the copy is only a pointer to the
78408 ** Worse, if the original is deallocated, the copy becomes invalid.
78429 ** This is an optimized version of SCopy that works only for integer
78477 /* If the SQLITE_CountRows flag is set in sqlite3.flags mask, then
78479 ** modified to the user. This is the only way that a VM that
78482 ** In case this is such a statement, close any statement transaction
78483 ** opened by this VM before returning control to the user. This is to
78485 ** If the open statement-transaction is not closed here, then the user
78489 ** The statement transaction is never a top-level transaction. Hence
78534 ** It is illegal for P1 and P3 to be the same register. Sometimes,
78535 ** if P3 is the same register as P2, the implementation is able
78578 ** If either input is NULL, the result is NULL.
78586 ** If either input is NULL, the result is NULL.
78593 ** If either input is NULL, the result is NULL.
78600 ** register P1 is zero, then the result is NULL. If either input is
78601 ** NULL, the result is NULL.
78606 ** Compute the remainder after integer register P2 is divided by
78608 ** If the value in register P1 is zero the result is NULL.
78609 ** If either operand is NULL, the result is NULL.
78702 ** P4 is a pointer to a CollSeq struct. If the next call to a user function
78704 ** be returned. This is used by the built-in min(), max() and nullif()
78707 ** If P1 is not zero, then it is a register that a subsequent min() or
78708 ** max() aggregate will set to 1 if the current row is not the minimum or
78709 ** maximum. The P1 register is initialized to 0 by this instruction.
78712 ** to retrieve the collation sequence set by this opcode is not available
78726 ** Invoke a user function (P4 is a pointer to a FuncDef object that
78728 ** successors. The result of the function is stored in register P3.
78731 ** P1 is a 32-bit bitmask indicating whether or not each argument to the
78733 ** argument was constant then bit 0 of P1 is set. This is used to determine
78743 ** Invoke a user function (P4 is a pointer to an sqlite3_context object that
78745 ** from register P2 and successors. The result of the function is stored
78748 ** P1 is a 32-bit bitmask indicating whether or not each argument to the
78750 ** argument was constant then bit 0 of P1 is set. This is used to determine
78756 ** to a FuncDef object. But on first evaluation, the P4 operand is
78792 /* If this function is inside of a trigger, the register array in aMem[]
78841 ** If either input is NULL, the result is NULL.
78848 ** If either input is NULL, the result is NULL.
78856 ** If either input is NULL, the result is NULL.
78864 ** If either input is NULL, the result is NULL.
78922 ** The result is always an integer.
78937 ** in P1 is not an integer and cannot be converted into an integer
78964 ** This opcode is used when extracting information from a column that
78992 ** A NULL value is not changed by this routine. It remains NULL.
79017 ** If the SQLITE_JUMPIFNULL bit of P5 is set and either reg(P1) or
79018 ** reg(P3) is NULL then take the jump. If the SQLITE_JUMPIFNULL
79019 ** bit is clear then fall through if either operand is NULL.
79022 ** SQLITE_AFF_TEXT, SQLITE_AFF_INTEGER, and so forth. An attempt is made
79024 ** comparison is made. If the SQLITE_AFF_MASK is 0x00, then numeric
79025 ** affinity is used. Note that the affinity conversions are stored
79029 ** Once any conversions have taken place, and neither value is NULL,
79030 ** the values are compared. If both values are blobs then memcmp() is
79033 ** P4 is used to do the comparison. If P4 is not specified then
79034 ** memcmp() is used to compare text string. If both values are
79035 ** numeric, then a numeric comparison is used. If the two values
79039 ** If the SQLITE_STOREP2 bit of P5 is set, then do not jump. Instead,
79042 ** If the SQLITE_NULLEQ bit is set in P5, then NULL values are considered
79049 ** This works just like the Lt opcode except that the jump is taken if
79053 ** If SQLITE_NULLEQ is set in P5 then the result of comparison is always either
79054 ** true or false and is never NULL. If both operands are NULL then the result
79055 ** of comparison is false. If either operand is NULL then the result is true.
79056 ** If neither operand is NULL the result is the same as it would be if
79062 ** This works just like the Lt opcode except that the jump is taken if
79066 ** If SQLITE_NULLEQ is set in P5 then the result of comparison is always either
79067 ** true or false and is never NULL. If both operands are NULL then the result
79068 ** of comparison is true. If either operand is NULL then the result is false.
79069 ** If neither operand is NULL the result is the same as it would be if
79075 ** This works just like the Lt opcode except that the jump is taken if
79076 ** the content of register P3 is less than or equal to the content of
79082 ** This works just like the Lt opcode except that the jump is taken if
79083 ** the content of register P3 is greater than the content of
79089 ** This works just like the Lt opcode except that the jump is taken if
79090 ** the content of register P3 is greater than or equal to the content of
79111 /* If SQLITE_NULLEQ is set (which will only happen if the operator is
79127 /* SQLITE_NULLEQ is clear and at least one operand is NULL,
79128 ** then the result is always NULL.
79129 ** The jump is taken if the SQLITE_JUMPIFNULL bit is set.
79145 /* Neither operand is NULL. Do a comparison. */
79220 ** The permutation is only valid until the next OP_Compare that has
79224 ** The first integer in the P4 integer array is the length of the array
79241 ** If P5 has the OPFLAG_PERMUTE bit set, then the order of comparison is
79243 ** OPFLAG_PERMUTE bit is clear, then register are compared in sequential
79246 ** P4 is a KeyInfo structure that defines collating sequences and sort
79250 ** The comparison is a sort comparison, so NULLs compare equal,
79324 ** If either P1 or P2 is 0 (false) then the result is 0 even if
79325 ** the other input is NULL. A NULL and true or two NULLs give
79334 ** If either P1 or P2 is nonzero (true) then the result is 1 (true)
79335 ** even if the other input is NULL. A NULL and false or two NULLs
79376 ** boolean complement in register P2. If the value in register P1 is
79377 ** NULL, then a NULL is stored in P2.
79410 ** Check the "once" flag number P1. If it is set, jump to instruction P2.
79432 ** Jump to P2 if the value in register P1 is true. The value
79433 ** is considered true if it is numeric and non-zero. If the value
79434 ** in P1 is NULL then take the jump if and only if P3 is non-zero.
79438 ** Jump to P2 if the value in register P1 is False. The value
79439 ** is considered false if it has a numeric value of zero. If the value
79440 ** in P1 is NULL then take the jump if and only if P3 is non-zero.
79466 ** Jump to P2 if the value in register P1 is NULL.
79480 ** Jump to P2 if the value in register P1 is not NULL.
79500 ** The value extracted is stored in register P3.
79503 ** if the P4 argument is a P4_MEM use the value of the P4 argument as
79506 ** If the OPFLAG_CLEARCACHE bit is set on P5 and P1 is a pseudo-table cursor,
79507 ** then the cache of the cursor is reset prior to extracting the column.
79512 ** the result is guaranteed to only be used as the argument of a length()
79520 u32 *aOffset; /* aOffset[i] is offset to start of data for i-th column */
79537 /* If the cursor cache is stale, bring it up-to-date */
79572 assert( avail<=65536 ); /* Maximum page size is 64KiB */
79609 /* The following goto is an optimization. It can be omitted and
79610 ** everything will still work. But OP_Column is measurably faster
79611 ** by skipping the subsequent conditional, which is always true.
79620 ** parsed and valid information is in aOffset[] and pC->aType[].
79623 /* If there is more header available for parsing in the record, try
79655 /* The record is corrupt if any of the following are true:
79675 /* If after trying to extract new entries from the header, nHdrParsed is
79703 /* This is the common case where the desired content fits on the original
79704 ** page - where the content is not on an overflow page */
79709 /* If the column value is a string, we need a persistent value, not
79710 ** a MEM_Ephem value. This branch is a fast short-cut that is equivalent
79729 /* This branch happens only when content is on overflow pages */
79734 /* Content is irrelevant for
79736 ** 2. the length(X) function if X is a blob, and
79737 ** 3. if the content length is zero.
79740 static u8 aZero[8]; /* This is the bogus content */
79762 ** P4 is a string that is P2 characters long. The nth character of the
79790 ** P4 may be a string that is P2 characters long. The nth character of the
79794 ** The mapping from character to affinity is given by the SQLITE_AFF_
79797 ** If P4 is NULL then all index fields have the affinity BLOB.
79824 ** Data(0) is taken from register P1. Data(1) comes from register P1+1
79827 ** Each type field is a varint representing the serial type of the
79829 ** hdr-size field is also a varint which is the offset from the beginning
79860 ** out how much space is required for the new record.
79884 ** value is the size of the header in bytes including the size varint
79903 ** the new record. The output register (pOp->p3) is not allowed to
79905 ** sqlite3VdbeMemClearAndResize() could clobber the value before it is used).
79936 pOut->enc = SQLITE_UTF8; /* In case the blob is ever converted to text */
79984 /* Assert that the p1 parameter is valid. Also that if there is no open
80004 /* This call is Ok even if this savepoint is actually a transaction
80006 ** If this is a transaction savepoint being opened, it is guaranteed
80007 ** that the db->aVTrans[] array is empty. */
80020 /* If there is no open transaction, then mark this as a special
80039 /* Find the named savepoint. If there is no such savepoint, then an
80040 ** an error is returned to the user. */
80052 /* It is not possible to release (commit) a savepoint if there are
80060 /* Determine whether or not this is a transaction savepoint. If so,
80061 ** and this is a RELEASE command, then the current transaction
80062 ** is committed.
80105 /* Regardless of whether this is a RELEASE or ROLLBACK, destroy all
80114 /* If it is a RELEASE, then destroy the savepoint being operated on
80115 ** too. If it is a ROLLBACK TO, then set the number of deferred
80143 ** Set the database auto-commit flag to P1 (1 or 0). If P2 is true, roll
80158 assert( db->nVdbeActive>0 ); /* At least this one VM is active */
80196 (iRollback)?"cannot rollback - no transaction is active":
80197 "cannot commit - no transaction is active"));
80207 ** Begin a transaction on database P1 if a transaction is not already
80209 ** If P2 is non-zero, then a write-transaction is started, or if a
80210 ** read-transaction is already active, it is upgraded to a write-transaction.
80211 ** If P2 is zero, then a read-transaction is started.
80213 ** P1 is the index of the database file on which the transaction is
80214 ** started. Index 0 is the main database file and index 1 is the
80218 ** If a write-transaction is started and the Vdbe.usesStmtJournal flag is
80219 ** true (this flag is set if the Vdbe may modify more than one row and may
80221 ** More specifically, a statement transaction is opened iff the database
80222 ** connection is currently not in autocommit mode, or if there are other
80225 ** entire transaction. If no error is encountered, the statement transaction
80231 ** This operation is used to detect when that the cookie has changed
80235 ** generation counter, then an SQLITE_SCHEMA error is raised and execution
80290 ** IMPLEMENTATION-OF: R-32195-19465 The schema version is used by SQLite
80291 ** each time a query is executed to ensure that the internal cache of the
80293 ** database against which the compiled query is actually executed.
80308 ** If virtual-tables are in use, this is not just an optimization.
80311 ** prepared queries. If such a query is out-of-date, we do not want to
80314 ** to be invalidated whenever sqlite3_step() is called from within
80330 ** P3==1 is the schema version. P3==2 is the database format.
80331 ** P3==3 is the recommended pager cache size, and so forth. P1==0 is
80332 ** the main database file and P1==1 is the database file used to store
80361 ** P2==1 is the schema version. P2==2 is the database format.
80362 ** P2==3 is the recommended pager cache
80363 ** size, and so forth. P1==0 is the main database file and P1==1 is the
80389 ** schema is changed. Ticket #1644 */
80400 ** Open a read-only cursor for the database table whose root page is
80401 ** P2 in a database file. The database file is determined by P3.
80406 ** It is an error for P1 to be negative.
80411 ** There will be a read lock on the database whenever there is an
80413 ** then a read lock is acquired as part of this instruction. A read
80415 ** any other process from modifying the database. The read lock is
80421 ** a KeyInfo structure (P4_KEYINFO). If it is a pointer to a KeyInfo
80423 ** sequence of the index being opened. Otherwise, if P4 is an integer
80424 ** value, it is set to the number of columns in the table.
80432 ** checks to see if the cursor on P1 is already open with a root page
80433 ** number of P2 and if it is this opcode becomes a no-op. In other words,
80434 ** if the cursor is already open, do not reopen it.
80446 ** page is P2. Or if P5!=0 use the content of register P2 to find the
80450 ** a KeyInfo structure (P4_KEYINFO). If it is a pointer to a KeyInfo
80452 ** sequence of the index being opened. Otherwise, if P4 is an integer
80453 ** value, it is set to the number of columns in the table, or to the
80454 ** largest index of any column of the table that is actually used.
80479 /* If the cursor is not currently open or is open on a different
80571 ** The cursor is always opened read/write even if
80572 ** the main database is read-only. The ephemeral
80573 ** table is deleted automatically when the cursor is closed.
80575 ** P2 is the number of columns in the ephemeral table.
80577 ** if P4 is not 0. If P4 is not NULL, it points to a KeyInfo structure
80616 /* If a transient index is required, create it by calling
80618 ** opening it. If a transient table is required, just use the
80648 ** a transient index that is specifically designed to sort large
80651 ** If argument P3 is non-zero, then it indicates that the sorter may
80653 ** key is sufficient to produce the required results.
80673 ** P1 is a sorter cursor. If the sequence counter is currently zero, jump
80674 ** to P2. Regardless of whether or not the jump is taken, increment the
80692 ** row of data. The content of that one row is the content of memory
80696 ** A pseudo-table created by this opcode is used to hold a single
80699 ** is the only cursor opcode that works with a pseudo-table.
80701 ** P3 is the number of fields in the records that will be stored by
80720 ** Close a cursor previously opened as P1. If P1 is not
80721 ** currently open, this instruction is a no-op.
80735 ** table or index for cursor P1 are used. P4 is a 64-bit integer
80738 ** by the cursor. The high-order bit is set if any column after
80739 ** the 64th is used.
80755 ** to an SQL index, then P3 is the first in an array of P4 registers
80759 ** is greater than or equal to the key value. If there are no records
80760 ** greater than or equal to the key and P2 is not zero, then jump to P2.
80764 ** else jump immediately to P2. When the cursor is OPFLAG_SEEKEQ, this
80770 ** from the beginning toward the end. In other words, the cursor is
80780 ** to an SQL index, then P3 is the first in an array of P4 registers
80784 ** is greater than the key value. If there are no records greater than
80785 ** the key and P2 is not zero, then jump to P2.
80788 ** from the beginning toward the end. In other words, the cursor is
80798 ** to an SQL index, then P3 is the first in an array of P4 registers
80802 ** is less than the key value. If there are no records less than
80803 ** the key and P2 is not zero, then jump to P2.
80806 ** from the end toward the beginning. In other words, the cursor is
80816 ** to an SQL index, then P3 is the first in an array of P4 registers
80820 ** is less than or equal to the key value. If there are no records
80821 ** less than or equal to the key and P2 is not zero, then jump to P2.
80824 ** from the end toward the beginning. In other words, the cursor is
80829 ** else jump immediately to P2. When the cursor is OPFLAG_SEEKEQ, this
80866 /* The BTREE_SEEK_EQ flag is only set on index cursors */
80879 ** loss of information, then special processing is required... */
80883 ** then the seek is not possible, so jump to P2 */
80888 /* If the approximation iKey is larger than the actual real search
80890 ** is 4.9 and the integer approximation 5:
80902 /* If the approximation iKey is smaller than the actual real search
80985 /* res might be negative because the table is empty. Check to
80986 ** see if this is the case.
81008 ** P4>0 then register P3 is the first of P4 registers that form an unpacked
81011 ** Cursor P1 is on an index btree. If the record identified by P3 and P4
81012 ** is a prefix of any entry in P1 then a jump is made to P2 and
81013 ** P1 is left pointing at the matching entry.
81025 ** P4>0 then register P3 is the first of P4 registers that form an unpacked
81028 ** Cursor P1 is on an index btree. If the record identified by P3 and P4
81029 ** is not the prefix of any entry in P1 then a jump is made to P2. If P1
81031 ** falls through to the next instruction and P1 is left pointing at the
81044 ** P4>0 then register P3 is the first of P4 registers that form an unpacked
81047 ** Cursor P1 is on an index btree. If the record identified by P3 and P4
81049 ** record are not-NULL then a check is done to determine if any row in the
81051 ** immediately to P2. If there is a match, fall through and leave the P1
81054 ** This opcode is similar to OP_NotFound with the exceptions that the
81055 ** branch is always taken if any part of the search key input is NULL.
81149 ** P1 is the index of a cursor open on an SQL table btree (with integer
81152 ** Or, if P2 is 0, raise an SQLITE_CORRUPT error. If P1 does contain
81173 ** P1 is the index of a cursor open on an SQL table btree (with integer
81174 ** keys). P3 is an integer rowid. If P1 does not contain a record with
81175 ** rowid P3 then jump immediately to P2. Or, if P2 is 0, raise an
81181 ** P3 register to contain a non-integer value, in which case the jump is
81245 ** The sequence number on the cursor is incremented after this
81262 ** The record number is not previously used as a key in the database
81263 ** table that cursor P1 points to. The new record number is written
81266 ** If P3>0 then P3 is a register in the root frame of this VDBE that holds
81269 ** an SQLITE_FULL error is generated. The P3 register is updated with the '
81270 ** generated record number. This P3 mechanism is used to help implement the
81291 ** thing) is obtained in a two-step algorithm.
81294 ** to that. But if the largest existing rowid is already the maximum
81298 ** The second algorithm is to select a rowid at random and see if
81335 /* Assert that P3 is a valid memory cell. */
81339 /* Assert that P3 is a valid memory cell. */
81343 /* Assert that P3 is a valid memory cell. */
81364 /* IMPLEMENTATION-OF: R-07677-41881 If the largest ROWID is equal to the
81367 ** it finds one that is not previously used. */
81368 assert( pOp->p3==0 ); /* We cannot be in random rowid mode if this is
81373 v &= (MAX_ROWID>>1); v++; /* Ensure that v is greater than zero */
81395 ** Write an entry into the table of cursor P1. A new entry is
81397 ** entry is overwritten. The data is the value MEM_Blob stored in register
81398 ** number P2. The key is stored in register P3. The key must
81401 ** If the OPFLAG_NCHANGE flag of P5 is set, then the row change count is
81402 ** incremented (otherwise not). If the OPFLAG_LASTROWID flag of P5 is set,
81403 ** then rowid is stored for subsequent return by the
81404 ** sqlite3_last_insert_rowid() function (otherwise it is unmodified).
81406 ** If the OPFLAG_USESEEKRESULT flag of P5 is set and if the result of
81410 ** the insert but will instead overwrite the row that the cursor is
81413 ** has already positioned the cursor correctly. This is an optimization
81416 ** If the OPFLAG_ISUPDATE flag is set, then this opcode is part of an
81417 ** UPDATE operation. Otherwise (if the flag is clear) then this opcode
81418 ** is part of an INSERT operation. The difference is only important to
81421 ** Parameter P4 may point to a Table structure, or may be NULL. If it is
81422 ** not NULL, then the update-hook (sqlite3.xUpdateCallback) is invoked
81425 ** (WARNING/TODO: If P1 is a pseudo-cursor and P2 is dynamically
81426 ** allocated, then ownership of P2 is transferred to the pseudo-cursor
81427 ** and register P2 becomes ephemeral. If the cursor is changed, the
81432 ** for indices is OP_IdxInsert.
81437 ** This works exactly like OP_Insert except that the key is the
81444 VdbeCursor *pC; /* Cursor to table into which insert is written */
81529 ** Delete the record at which the P1 cursor is currently pointing.
81531 ** If the OPFLAG_SAVEPOSITION bit of the P5 parameter is set, then
81533 ** record in the table. If it is left pointing at the next record, then
81535 ** it is ok to delete a record from within a Next loop. If
81536 ** OPFLAG_SAVEPOSITION bit of P5 is clear, then the cursor will be
81539 ** If the OPFLAG_AUXDELETE bit is set on P5, that indicates that this
81541 ** associated index entries. Exactly one of those deletes is the "primary"
81545 ** If the OPFLAG_NCHANGE flag of P2 (NB: P2 not P5) is set, then the row
81546 ** change count is incremented (otherwise not).
81551 ** If P4 is not NULL then it points to a Table struture. In this case either
81554 ** this case. Specifically, if one is configured, the pre-update hook is
81555 ** invoked if P4 is not NULL. The update-hook is invoked if one is configured,
81556 ** P4 is not NULL, and the OPFLAG_NCHANGE flag is set in P2.
81558 ** If the OPFLAG_ISUPDATE flag is set in P2, then P3 contains the address
81578 /* If p5 is zero, the seek operation that positioned the cursor prior to
81580 ** the row that is being deleted */
81588 ** of p4.pTab. Finally, if p5 is true, indicating that this cursor was
81654 ** The value of the change counter is copied to the database handle
81657 ** This is used by trigger programs.
81668 ** P1 is a sorter cursor. This instruction compares a prefix of the
81675 ** the comparison is assumed to be equal.
81704 ** This opcode is normally use to move a record out of the sorter and into
81705 ** a register that is the source for a pseudo-table cursor created using
81706 ** OpenPseudo. That pseudo-table cursor is the one that is identified by
81728 ** There is no interpretation of the data.
81729 ** It is just copied onto the P2 register exactly as
81730 ** it is found in the database file.
81739 ** There is no interpretation of the data.
81740 ** The key is copied onto the P2 register exactly as
81741 ** it is found in the database file.
81798 pOut->enc = SQLITE_UTF8; /* In case the blob is ever cast to text */
81807 ** Store in register P2 an integer which is the key of the table entry that
81808 ** P1 is currently point to.
81858 ** that occur while the cursor is on the null row will always
81880 ** If the table or index is empty and P2>0, then jump immediately to P2.
81881 ** If P2 is 0 or if the table or index is not empty, fall through
81885 ** from the end toward the beginning. In other words, the cursor is
81922 ** Sorting is accomplished by writing records into a sorting index,
81926 ** regression tests can determine whether or not the optimizer is
81942 ** If the table or index is empty, jump immediately to P2.
81943 ** If the table or index is not empty, fall through to the following
81947 ** from the beginning toward the end. In other words, the cursor is
81988 ** The Next opcode is only valid following an SeekGT, SeekGE, or
81989 ** OP_Rewind opcode used to position the cursor. Next is not allowed
81995 ** The P3 value is a hint to the btree implementation. If P3==1, that
81996 ** means P1 is an SQL index and that this instruction could have been
81997 ** omitted if that index had been unique. P3 is usually 0. P3 is
82000 ** P4 is always of type P4_ADVANCE. The function pointer points to
82003 ** If P5 is positive and the jump is taken, then event counter
82004 ** number P5-1 in the prepared statement is incremented.
82010 ** This opcode works just like Next except that if cursor P1 is not
82016 ** table or index. If there is no previous key/value pairs then fall through
82021 ** The Prev opcode is only valid following an SeekLT, SeekLE, or
82022 ** OP_Last opcode used to position the cursor. Prev is not allowed
82025 ** The P1 cursor must be for a real table, not a pseudo-table. If P1 is
82026 ** not open then the behavior is undefined.
82028 ** The P3 value is a hint to the btree implementation. If P3==1, that
82029 ** means P1 is an SQL index and that this instruction could have been
82030 ** omitted if that index had been unique. P3 is usually 0. P3 is
82033 ** P4 is always of type P4_ADVANCE. The function pointer points to
82036 ** If P5 is positive and the jump is taken, then event counter
82037 ** number P5-1 in the prepared statement is incremented.
82041 ** This opcode works just like Prev except that if cursor P1 is not
82073 /* The Next opcode is only used after SeekGT, SeekGE, and Rewind.
82074 ** The Prev opcode is only used after SeekLT, SeekLE, and Last. */
82105 ** into the index P1. Data for the entry is nil.
82107 ** P3 is a flag that provides a hint to the b-tree layer that this
82108 ** insert is likely to be an append.
82110 ** If P5 has the OPFLAG_NCHANGE bit set, then the change counter is
82111 ** incremented by this instruction. If the OPFLAG_NCHANGE bit is clear,
82112 ** then the change counter is unchanged.
82115 ** just done a seek to the spot where the new entry is to be inserted.
82119 ** for tables is OP_Insert.
82195 ** P1 is an open index cursor and P3 is a cursor on the corresponding
82199 ** This is a deferred seek. Nothing actually happens until
82200 ** the cursor is used to read a record. That way, if no reads
82205 ** is non-zero, then reading column a(i)-1 from cursor P3 is
82207 ** from P1. This information is stored in P3 and used to redirect
82214 ** Write into register P2 an integer which is the last entry in the record at
82280 ** that P1 is currently pointing to, ignoring the PRIMARY KEY or ROWID
82283 ** If the P1 index entry is greater than or equal to the key value
82291 ** that P1 is currently pointing to, ignoring the PRIMARY KEY or ROWID
82294 ** If the P1 index entry is greater than the key value
82302 ** the index that P1 is currently pointing to, ignoring the PRIMARY KEY or
82305 ** If the P1 index entry is less than the key value then jump to P2.
82313 ** the index that P1 is currently pointing to, ignoring the PRIMARY KEY or
82316 ** If the P1 index entry is less than or equal to the key value then jump
82368 ** file is given by P1.
82370 ** The table being destroyed is in the main database file if P3==0. If
82371 ** P3==1 then the table to be clear is in the auxiliary database file
82372 ** that is used to store tables create using CREATE TEMPORARY TABLE.
82374 ** If AUTOVACUUM is enabled then it is possible that another root page
82378 ** is stored in register P2. If no page
82380 ** the last one in the database) then a zero is stored in register P2.
82381 ** If AUTOVACUUM is disabled then a zero is stored in register P2.
82420 ** in the database file is given by P1. But, unlike Destroy, do not
82423 ** The table being clear is in the main database file if P2==0. If
82424 ** P2==1 then the table to be clear is in the auxiliary database file
82425 ** that is used to store tables create using CREATE TEMPORARY TABLE.
82427 ** If the P3 value is non-zero, then the table referred to must be an
82429 ** count is incremented by the number of rows in the table being cleared.
82430 ** If P3 is greater than zero, then the value stored in register P3 is
82459 ** that is open on cursor P1.
82489 ** The difference between a table and an index is this: A table must
82536 ** then runs the new virtual machine. It is thus a re-entrant opcode.
82545 ** on every btree. This is a prerequisite for invoking
82606 ** the table named P4 in database P1. This is called after a table
82607 ** is dropped from disk (using the Destroy opcode) in order to keep
82609 ** schema consistent with what is on disk.
82619 ** the index named P4 in database P1. This is called after an index
82620 ** is dropped from disk (using the Destroy opcode)
82622 ** schema consistent with what is on disk.
82632 ** the trigger named P4 in database P1. This is called after a trigger
82633 ** is dropped from disk (using the Destroy opcode) in order to keep
82635 ** schema consistent with what is on disk.
82653 ** seen. Reg(P1) is updated with the number of errors remaining.
82658 ** If P5 is not zero, the check is done on the auxiliary database
82661 ** This opcode is used to implement the integrity_check pragma.
82705 ** An assertion fails if P2 is not an integer.
82723 ** register P3. Or, if boolean index P1 is initially empty, leave P3
82733 /* The boolean index is empty */
82748 ** Register P3 is assumed to hold a 64-bit integer value. If register P1
82754 ** The RowSet object is optimized for the case where successive sets
82756 ** of values is identified by a unique P4 value. The first set
82761 ** This allows optimizations: (a) when P4==0 there is no need to test
82762 ** the rowset object for P3, as it is guaranteed not to contain it,
82763 ** (b) when P4==-1 there is no need to insert the value, as it will
82764 ** never be tested for, and (c) when a value that is part of set X is
82765 ** inserted, there is no need to search to see if the same value was
82778 /* If there is anything other than a rowset object in memory cell P1,
82810 ** of a memory cell in this (the parent) VM that is used to allocate the
82813 ** P4 is a pointer to the VM containing the trigger program.
82815 ** If P5 is non-zero, then recursive program invocation is enabled.
82831 /* If the p5 flag is clear, then recursive invocation of triggers is
82832 ** disabled for backwards compatibility (p5 is set if this sub-program
82833 ** is really a trigger, not a foreign key action, and the flag set
82834 ** and cleared by the "PRAGMA recursive_triggers" command is clear).
82836 ** It is recursive invocation of triggers, at the SQL level, that is
82854 /* Register pRt is used to store the memory required to save the state
82857 ** is already allocated. Otherwise, it must be initialized. */
82859 /* SubProgram.nMem is set to the number of memory cells used by the
82861 ** cell is required for each cursor used by the program. Set local
82938 ** This opcode is only ever present in sub-programs called via the
82941 ** address space. This is used by trigger programs to access the new.*
82944 ** The address of the cell in the parent frame is determined by adding
82965 ** If P1 is non-zero, the database constraint counter is incremented
82966 ** (deferred foreign key constraints). Otherwise, if P1 is zero, the
82967 ** statement counter is incremented (immediate foreign key constraints).
82983 ** This opcode tests if a foreign key constraint-counter is currently zero.
82987 ** If P1 is non-zero, then the jump is taken if the database constraint-counter
82988 ** is zero (the one that counts deferred constraint violations). If P1 is
82989 ** zero, the jump is taken if the statement constraint-counter is zero
83008 ** P1 is a register in the root frame of this VM (the root frame is
83009 ** different from the current frame if this instruction is being executed
83013 ** This instruction throws an error if the memory cell is not initially
83039 ** If the value of register P1 is 1 or greater, subtract P3 from the
83042 ** If the initial value of register P1 is less than 1, then the
83043 ** value is unchanged and control passes through to the next instruction.
83063 ** value computed is the total number of rows that will need to be
83066 ** If r[P3] is zero or negative, that means there is no OFFSET
83067 ** and r[P2] is set to be the value of the LIMIT, r[P1].
83069 ** if r[P1] is zero or negative, that means there is no LIMIT
83070 ** and r[P2] is set to -1.
83072 ** Otherwise, r[P2] is set to the sum of r[P1] and r[P3].
83087 ** Register P1 must contain an integer. If the content of register P1 is
83089 ** jump to P2. If register P1 is initially zero, leave it unchanged
83107 ** then jump to P2 if the new value is exactly zero.
83123 ** function has P5 arguments. P4 is a pointer to the FuncDef
83124 ** structure that specifies the function. Register P3 is the
83134 ** function has P5 arguments. P4 is a pointer to an sqlite3_context
83135 ** object that is used to run the function. Register P3 is
83141 ** This opcode is initially coded as OP_AggStep0. On first evaluation,
83142 ** the FuncDef stored in P4 is converted into an sqlite3_context and
83143 ** the opcode is changed. In this way, the initialization of the
83178 /* If this function is inside of a trigger, the register array in aMem[]
83221 ** Execute the finalizer function for an aggregate. P1 is
83222 ** the memory location that is the accumulator for the aggregate.
83224 ** P2 is the number of arguments that the step function takes and
83225 ** P4 is a pointer to the FuncDef for this function. The P2
83226 ** argument is not used by this opcode. It is only there to disambiguate
83228 ** P4 argument is only needed for the degenerate case where
83252 ** Checkpoint database P1. This is a no-op if P1 is not currently in
83253 ** WAL mode. Parameter P2 is one of SQLITE_CHECKPOINT_PASSIVE, FULL,
83292 ** modes (delete, truncate, persist, off and memory), this is a simple
83293 ** operation. No IO is required.
83295 ** If changing into or out of WAL mode the procedure is more complicated.
83435 ** is executed using sqlite3_step() it will either automatically
83439 ** If P1 is 0, then all SQL statements become expired. If P1 is non-zero,
83440 ** then only the currently executing statement is expired.
83455 ** Obtain a lock on a particular table. This instruction is only used when
83456 ** the shared-cache feature is enabled.
83458 ** P1 is the index of the database in sqlite3.aDb[] of the database
83459 ** on which the lock is acquired. A readlock is obtained if P3==0 or
83464 ** P4 contains a pointer to the name of the table being locked. This is only
83478 sqlite3VdbeError(p, "database table is locked: %s", z);
83493 ** Also, whether or not P4 is set, check that this is not being called from
83494 ** within a callback to a virtual table xSync() method. If it is, the error
83510 ** P2 is a register that holds the name of a virtual table in database
83519 /* Because P2 is always a static string, it is impossible for the
83539 ** P4 is the name of a virtual table in database P1. Call the xDestroy method
83554 ** P4 is a pointer to a virtual table object, an sqlite3_vtab structure.
83555 ** P1 is a cursor number. This opcode opens a cursor to the virtual
83598 ** P1 is a cursor opened using VOpen. P2 is an address to jump to if
83599 ** the filtered result set is empty.
83601 ** P4 is either NULL or a string that was generated by the xBestIndex
83602 ** method of the module. The interpretation of the P4 string is left
83606 ** by P1. The integer query plan parameter to xFilter is stored in register
83612 ** A jump is made to P2 if the result set after filtering would be empty.
83665 ** P1 cursor is pointing to into register P3.
83728 /* Invoke the xNext() method of the module. There is no way for the
83730 ** xNext(). Instead, if an error occurs, true is returned (indicating that
83731 ** data is available) and the error code returned when xColumn or
83732 ** some other method is next invoked on the save virtual table cursor.
83740 /* If there is data, jump to P2 */
83750 ** P4 is a pointer to a virtual table object, an sqlite3_vtab structure.
83752 ** in register P1 is passed as the zName argument to the xRename method.
83782 ** P4 is a pointer to a virtual table object, an sqlite3_vtab structure.
83790 ** is the rowid of a row to delete. If argv[0] is NULL then no
83791 ** deletion occurs. The argv[1] element is the rowid of the new
83796 ** If P2==1 then no insert is performed. argv[0] is the rowid of
83799 ** P1 is a boolean flag. If it is set to true and the xUpdate call
83800 ** is successful, then the value returned by sqlite3_last_insert_rowid()
83801 ** is set to the value of the rowid for the row just inserted.
83803 ** P5 is the error actions (OE_Replace, OE_Fail, OE_Ignore, etc) to
83905 ** If tracing is enabled (by the sqlite3_trace()) interface, then
83906 ** the UTF-8 string contained in P4 is emitted on the trace callback.
83907 ** Or if P4 is blank, use the string returned by sqlite3_sql().
83909 ** If P2 is not zero, jump to instruction P2.
83914 /* If the P4 argument is not NULL, then it must be an SQL comment string.
83915 ** The "--" string is broken up to prevent false-positives with srcck1.c.
83970 ** expression refer to columns in the b-tree to which cursor P1 is pointing.
83989 ** Do nothing. This instruction is often useful as a jump
83994 ** is to say when the EXPLAIN QUERY PLAN syntax is used.)
83995 ** This opcode records information from the optimizer. It is the
83998 default: { /* This is really OP_Noop and OP_Explain */
84020 ** of the program. It is only here for testing and debugging.
84022 ** the evaluator loop. So we can leave it out when NDEBUG is defined.
84042 /* If we reach this point, it means that execution is finished with
84063 /* This is the only way out of this procedure. We have to
84077 ** is encountered.
84110 ** a legal notice, here is a blessing:
84134 int iCol; /* Table column this handle is open on */
84144 ** This function is used by both blob_open() and blob_reopen(). It seeks
84146 ** If successful, SQLITE_OK is returned and subsequent calls to
84151 ** blob handle was opened, then an error code is returned and *pzErr may
84152 ** be set to point to a buffer containing an error message. It is the
84156 ** If an error does occur, then the b-tree cursor is closed. All subsequent
84166 ** This is done directly instead of using sqlite3_bind_int64() to avoid
84300 /* If the value is being opened for writing, check that the
84301 ** column is not indexed, and that it is not part of a foreign key.
84302 ** It is against the rules to open a column to which either of these
84309 /* Check that the column is not part of an FK child key definition. It
84310 ** is not necessary to check if it is part of a parent key, as parent
84348 ** of writing code to use the b-tree layer directly is that the
84383 /* Make sure a mutex is held on the table to be accessed */
84409 ** always return an SQL NULL. This is useful because it means
84493 /* Request is out of range. Return a transient error. */
84496 /* If there is no statement handle, then the blob-handle has
84501 /* Call either BtreeData() or BtreePutData(). If SQLITE_ABORT is
84509 /* If a pre-update hook is registered and this is a write cursor,
84512 ** TODO: The preupdate-hook is passed SQLITE_DELETE, even though this
84513 ** operation should really be an SQLITE_UPDATE. This is probably
84514 ** incorrect, but is convenient because at this point the new.* values
84516 ** SQLITE_UPDATE where the PK columns do not change is handled in the
84517 ** same way as an SQLITE_DELETE (the SQLITE_DELETE code is actually
84562 ** The Incrblob.nByte field is fixed for the lifetime of the Incrblob
84563 ** so no mutex is required for access.
84575 ** contain a blob or text value, then an error code is returned and the
84590 /* If there is no statement handle, then the blob-handle has
84618 ** a legal notice, here is a blessing:
84631 ** algorithm that is efficient even if the number of elements being sorted
84634 ** Here is the (internal, non-API) interface between this module and the
84640 ** object. The row is a binary blob in the
84660 ** X is strictly less than the read cursor.
84668 ** is like Close() followed by Init() only
84686 ** a threshold, when Rewind() is called the set of records is sorted using
84694 ** A PMA created at this point is known as a "level-0 PMA". Higher levels
84699 ** records to a PMA is roughly the same as the limit configured for the
84700 ** page-cache of the main database. Specifically, the threshold is set to
84704 ** If the sorter is running in single-threaded mode, then all PMAs generated
84705 ** are appended to a single temporary file. Or, if the sorter is running in
84707 ** N is the configured number of worker threads. In this case, instead of
84713 ** The sorter is running in multi-threaded mode if (a) the library was built
84718 ** When Rewind() is called, any data remaining in memory is flushed to a
84719 ** final PMA. So at this point the data is stored in some number of sorted
84723 ** sorter is running in single-threaded mode, then these PMAs are merged
84728 ** Or, if running in multi-threaded mode, then a background thread is
84734 ** Parameter T is set to half the value of the memory threshold used
84738 ** Rewind() is called, then a hierarchy of incremental-merges is used.
84742 ** PMAs at a time. This done is to improve locality.
84745 ** SORTER_MAX_MERGE_COUNT PMAs on disk when Rewind() is called, then more
84755 ** If SQLITE_DEBUG_SORTER_THREADS is defined, this module outputs various
84765 ** to a level 0 PMA. The purpose of this limit is to prevent various integer
84794 ** If aMemory==0 then each object is allocated separately and the objects
84806 ** The MergeEngine object is used to combine two or more smaller PMAs into
84812 ** merged. An aReadr[] object either points to a valid key or else is at EOF.
84813 ** ("EOF" means "End Of File". When aReadr[] is at EOF there is no more data.)
84814 ** For the purposes of the paragraphs below, we assume that the array is
84815 ** actually N elements in size, where N is the smallest power of 2 greater
84819 ** The aTree[] array is also N elements in size. The value of N is stored in
84824 ** comparing aReadr[2*i-N] and aReadr[2*i-N+1]. Whichever key is smaller, the
84825 ** aTree element is set to the index of it.
84827 ** For the purposes of this comparison, EOF is considered greater than any
84829 ** values), it doesn't matter which index is stored.
84834 ** currently points to the smallest key value. aTree[0] is unused.
84849 ** The current element is "Apple" (the value of the key indicated by
84850 ** PmaReader 5). When the Next() operation is invoked, PmaReader 5 will
84851 ** be advanced to the next key in its segment. Say the next key is
84858 ** 5 value is still smaller, so aTree[6] is set to 5. And so on up the tree.
84859 ** The value of PmaReader 6 - "Durian" - is now smaller than that of PmaReader
84860 ** 5, so aTree[3] is set to 6. Key 0 is smaller than key 6 (Banana<Durian),
84861 ** so the value written into element 1 of the array is 0. As follows:
84866 ** key comparison operations are required, where N is the number of segments
84880 ** other way. VdbeSorter.nTask is set to the number of worker threads allowed
84882 ** single-threaded operation, there is exactly one instance of this object
84890 ** Before a background thread is launched, variable bDone is set to 0. Then,
84891 ** right before it exits, the thread itself sets bDone to 1. This is used for
84895 ** attempt to select a SortSubtask for which there is not already an
84899 ** 2. If SQLITE_DEBUG_SORTER_THREADS is defined, to determine if a call
84900 ** to sqlite3ThreadJoin() is likely to block. Cases that are likely to
84910 int bDone; /* Set if thread is finished but not joined */
84922 ** Main sorter structure. A single instance of this is allocated for each
84927 ** this variable is updated so as to be set to the size on disk of the
84955 ** An instance of the following object is used to read records out of a
84956 ** PMA, in sorted order. The next key to be read is cached in nKey/aKey.
84958 ** contain a contiguous representation of the key, then aAlloc is allocated
84959 ** and the key is copied into aAlloc and aKey is made to poitn to aAlloc.
84987 ** and aFile[1]. Neither file is allowed to grow to more than mxSz bytes in
84988 ** size. When the IncrMerger is initialized, it reads enough data from
85005 ** threaded IncrMerger the allocate part of pTask->file2 is "refilled" with
85014 int bEof; /* Set to true when merge is finished */
85020 ** An instance of this object is used for writing a PMA.
85022 ** The PMA is written one record at a time. Each record is of an arbitrary
85023 ** size. But I/O is more efficient if it occurs in page-sized blocks where
85024 ** each block is aligned on a page boundary. This object caches writes to
85038 ** This object is the header on a single record while that record is being
85041 ** How the linked list is connected depends on how memory is being managed
85043 ** (VdbeSorter.list.aMemory==0), then the list is always connected using the
85047 ** then while records are being accumulated the list is linked using the
85048 ** SorterRecord.u.iNext offset. This is because the aMemory[] array may
85051 ** is full, the list is sorted. As part of the sorting process, it is
85096 ** The buffer returned in *ppOut is only valid until the
85115 /* If there is no more data to be read from the buffer, read the next
85139 /* The requested data is available in the in-memory buffer. In this
85140 ** case there is no need to make a copy of the data, just return a
85145 /* The requested data is not all available in the in-memory buffer.
85161 /* Copy as much data as is available in the buffer into the start of
85219 ** new mapping and return SQLITE_OK. If the mapping is not attempted
85220 ** (because the file is too large or the VFS layer is configured not to use
85224 ** *pp is undefined in this case.
85239 ** Attach PmaReader pReadr to file pFile (if it is not already attached to
85245 PmaReader *pReadr, /* Reader whose cursor is to be moved */
85309 /* This is an EOF condition */
85332 ** PMA is empty).
85334 ** If the pnByte parameter is NULL, then it is assumed that the file
85367 ** determined that the first field of key1 is equal to the first field of
85372 int *pbKey2Cached, /* True if pTask->pUnpacked is pKey2 */
85389 ** If IN/OUT parameter *pbKey2Cached is true when this function is called,
85390 ** it is assumed that (pTask->pUnpacked) contains the unpacked version
85391 ** of key2. If it is false, (pTask->pUnpacked) is populated with the unpacked
85394 ** If an OOM error is encountered, (pTask->pUnpacked->error_rc) is set
85399 int *pbKey2Cached, /* True if pTask->pUnpacked is pKey2 */
85413 ** the first field of each key is a TEXT value and that the collation
85414 ** sequence to compare them with is BINARY.
85418 int *pbKey2Cached, /* True if pTask->pUnpacked is pKey2 */
85455 ** the first field of each key is an INTEGER value.
85459 int *pbKey2Cached, /* True if pTask->pUnpacked is pKey2 */
85527 ** is non-zero and the sorter is able to guarantee a stable sort, nField
85528 ** is used instead. This is used when sorting records for a CREATE INDEX
85531 ** of the records being sorted. So if the sort is stable, there is never
85538 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
85609 /* A negative cache-size value C indicates that the cache is abs(C)
85760 /* This function is always called by the main user thread.
85762 ** If this function is being called after SorterRewind() has been called,
85763 ** it is possible that thread pSorter->aTask[pSorter->nTask-1].pThread
85764 ** is currently attempt to join one of the other threads. To avoid a race
85783 ** nReader is automatically rounded up to the next power of two.
85887 ** The first argument is a file-handle open on a temporary file. The file
85888 ** is guaranteed to be nByte bytes or smaller in size. This function
86120 ** Return SQLITE_OK if flushing the buffered data succeeds or is not
86157 ** The format of a PMA is:
86164 ** key). The varint is the number of bytes in the blob of data.
86173 ** This is used by an assert() statement at the end of this function. */
86225 ** Set *pbEof to true there is no next entry because
86268 ** case there is no cache of pReadr2 in pTask->pUnpacked, so set
86279 ** is sorted from oldest to newest, so pReadr1 contains older values
86330 ** records to disk. If the sorter is running in multi-threaded mode,
86332 ** the background thread from a sub-tasks previous turn is still running,
86411 ** flush the contents of memory to a new PMA if (a) at least one value is
86417 ** * The total memory allocated for the in-memory list is greater
86420 ** * The total memory allocated for the in-memory list is greater
86487 ** of the data stored in aFile[1] is the same as that used by regular PMAs,
86488 ** except that the number-of-bytes varint is omitted from the start.
86509 /* Check if the output file is full or if the input has been exhausted.
86550 ** This function is called when the PmaReader corresponding to pIncr has
86551 ** finished reading the contents of aFile[0]. Its purpose is to "refill"
86555 ** For single-threaded objects, this is accomplished by literally reading
86558 ** For multi-threaded objects, all that is required is to wait until the
86559 ** background thread is finished (if it is not already) and then swap
86564 ** SQLITE_OK is returned on success, or an SQLite error code otherwise.
86602 ** If an OOM condition is encountered, return NULL. In this case free the
86691 ** Only INCRINIT_NORMAL is valid in single-threaded builds (when
86711 ** If argument eMode is INCRINIT_ROOT, then it is assumed that any IncrMerge
86714 ** set the PmaReader objects up to read from it. In this case all that is
86715 ** required is to call vdbePmaReaderNext() on each PmaReader to point it at
86718 ** Otherwise, if eMode is any value other than INCRINIT_ROOT, then use
86722 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
86733 /* eMode is always INCRINIT_NORMAL in single-threaded mode */
86736 /* Verify that the MergeEngine is assigned to a single thread */
86744 ** However, in the INCRINIT_ROOT case, if PmaReader aReadr[nTask-1] is
86763 ** The PmaReader passed as the first argument is guaranteed to be an
86768 ** If argument eMode is set to INCRINIT_NORMAL, then all PmaReaders
86769 ** in the sub-tree headed by pReadr are also initialized. Data is then
86770 ** loaded into the buffers belonging to pReadr and it is set to point to
86773 ** If argument eMode is set to INCRINIT_TASK, then pReadr is guaranteed
86774 ** to be a multi-threaded PmaReader and this function is being called in a
86777 ** pReadr is populated. However, pReadr itself is not set up to point
86778 ** to its first key. A call to vdbePmaReaderNext() is still required to do
86782 ** in the INCRINIT_TASK case is that vdbePmaReaderNext() assumes that it has
86784 ** this entire function is being run by thread (pTask->thread), that will
86787 ** Finally, if argument eMode is set to INCRINIT_ROOT, it may be assumed
86788 ** that pReadr->pIncr is a multi-threaded IncrMerge objects, and that all
86790 ** In this case vdbePmaReaderNext() is called on all child PmaReaders and
86793 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
86801 /* eMode is always INCRINIT_NORMAL in single-threaded mode */
86836 ** PmaReader is multi-threaded. If this is an INCRINIT_TASK object,
86837 ** then this function is already running in background thread
86840 ** If this is the INCRINIT_ROOT object, then it is running in the
86841 ** main VDBE thread. But that is Ok, as that thread cannot return
86873 ** If the PmaReader passed as the first argument is not an incremental-reader
86874 ** (if pReadr->pIncr==0), then this function is a no-op. Otherwise, it invokes
86878 ** If the IncrMerger object is multi-threaded (IncrMerger.bUseThread==1),
86879 ** then a background thread is launched to call vdbePmaReaderIncrMergeInit().
86880 ** Or, if the IncrMerger is single threaded, the same function is called
86907 ** When this function is called, *piOffset is set to the offset of the
86908 ** first PMA to read from pTask->file. Assuming no error occurs, it is
86911 ** *piOffset is undefined.
86963 ** pRoot is the root of an incremental merge-tree with depth nDepth (according
86964 ** to vdbeSorterTreeDepth()). pLeaf is the iSeq'th leaf to be added to the
86967 ** If successful, SQLITE_OK is returned. If an error occurs, an SQLite error
86968 ** code is returned and pLeaf is freed.
87016 ** This function is called as part of a SorterRewind() operation on a sorter
87021 ** If successful, SQLITE_OK is returned and *ppOut set to point to the
87023 ** error occurs, an SQLite error code is returned and the final value
87024 ** of *ppOut is undefined.
87097 ** This function is called as part of an sqlite3VdbeSorterRewind() operation
87103 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
87146 ** a) The incremental merge object is configured to use the
87148 ** b) If it is using task (nTask-1), it is configured to run
87149 ** in single-threaded mode. This is important, as the
87184 ** this function is called to prepare for iterating through the records
87211 ** So the list is never empty at this point. */
87326 ** key in pVal is smaller than, equal to or larger than the current sorter
87330 ** turn is used to verify uniqueness when constructing a UNIQUE INDEX.
87376 ** a legal notice, here is a blessing:
87385 ** The in-memory rollback journal is used to journal transactions for
87386 ** ":memory:" databases and when the journal_mode=MEMORY pragma is used.
87388 ** Update: The in-memory journal is also used to temporarily cache
87405 ** The rollback journal is composed of a linked list of these structures.
87407 ** The zChunk array is always at least 8 bytes in size - usually much more.
87408 ** Its actual size is stored in the MemJournal.nChunkSize variable.
87436 ** This structure is a subclass of sqlite3_file. Each open memory-journal
87437 ** is an instance of this class.
87455 ** Read data from the in-memory journal file. This is the implementation
87584 ** access writes are not required. The only exception to this is when
87585 ** the in-memory journal is being used by a connection using the
87604 /* New chunk is required to extend the file. */
87635 ** If the journal file is already on disk, truncate it there. Or, if it
87636 ** is still in main memory but is being truncated to zero bytes in size,
87665 ** syncing an in-memory journal is a no-op.
87710 ** nSpill. If nSpill is 0, then the journal file is always create and
87711 ** accessed using the underlying VFS. If nSpill is less than zero, then
87712 ** all content is always stored in main-memory. Finally, if nSpill is a
87713 ** positive value, then the journal file is initially created in-memory
87714 ** but may be flushed to disk later on. In this case the journal file is
87716 ** or when sqlite3JournalCreate() is called.
87729 ** case none of the code in this module is executed as a result of calls
87760 ** If the argument p points to a MemJournal structure that is not an
87761 ** in-memory-only journal file (i.e. is one that was opened with a +ve
87775 ** The file-handle passed as the only argument is open on a journal file.
87776 ** Return true if this "journal file" is currently stored in heap memory,
87797 ** a legal notice, here is a blessing:
87815 ** is invoked before visiting children.)
87828 ** The return value from this routine is WRC_Abort to abandon the tree walk
87854 ** an abort request is seen.
87917 ** If it is not NULL, the xSelectCallback() callback is invoked before
87919 ** method, if it is not NULL, is invoked following the walk of the
87923 ** there is an abort request.
87926 ** is a no-op returning WRC_Continue.
87961 ** a legal notice, here is a blessing:
87983 ** incrAggFunctionDepth(pExpr,n) is the main routine. incrAggDepth(..)
87984 ** is a helper function - a callback for the tree walker.
88004 ** If the reference is followed by a COLLATE operator, then make sure
88005 ** the COLLATE operator is preserved. For example:
88014 ** alias is removed from the original expression. The usual value is
88015 ** zero but it might be more if the alias is contained within a subquery
88025 int nSubquery /* Number of subqueries that the label is moving */
88065 ** Return FALSE if the USING clause is NULL or if it does not contain
88115 ** (even if X is implied).
88122 ** pExpr->pLeft Any expression this points to is deleted
88123 ** pExpr->pRight Any expression this points to is deleted.
88125 ** The zDb variable is the name of the database (the "X"). This value may be
88126 ** NULL meaning that name is of the form Y.Z or Z. Any available database
88127 ** can be used. The zTable variable is the name of the table (the "Y"). This
88128 ** value can be NULL if zDb is also NULL. If zTable is NULL it
88129 ** means that the form of the name is Z and that columns from any table
88189 /* Start at the inner-most context and move outward until a match is found */
88229 ** is for the right-hand table of a NATURAL JOIN or is in a
88258 ** it is a new.* or old.* trigger argument reference
88311 ** Perhaps the name is a reference to the ROWID
88326 ** If the input is of the form Z (not Y.Z or X.Y.Z) then the name Z
88335 ** resolved by the time the WHERE clause is resolved.
88339 ** clause is not standard SQL. This is a (goofy) SQLite extension, that
88340 ** is supported for backwards compatibility only. Hence, we issue a warning
88341 ** on sqlite3_log() whenever the capability is used.
88378 ** If X and Y are NULL (in other words if only the column name Z is
88379 ** supplied) and the value of Z is enclosed in double-quotes, then
88380 ** Z is a string literal if it doesn't match any column names. In that
88411 /* If a column from a table in pSrcList is referenced, then record
88414 ** column number is greater than the number of bits in the bitmask
88478 ** Report an error that an expression is not valid for some set of
88500 ** Return 1024 times this value. Or return -1 if p is not a floating point
88513 ** This routine is callback for sqlite3WalkExpr().
88520 ** function names. The operator for aggregate functions is changed
88547 ** column in the FROM clause. This is used by the LIMIT and ORDER BY
88565 /* A lone identifier is the name of a column.
88604 int is_agg = 0; /* True if is an aggregate function */
88636 /* EVIDENCE-OF: R-61304-29449 The unlikely(X) function is
88638 ** EVIDENCE-OF: R-01283-11636 The unlikely(X) function is
88640 ** EVIDENCE-OF: R-36850-34127 The likely(X) function is short-hand
88642 ** EVIDENCE-OF: R-53436-40973 The likely(X) function is equivalent
88644 /* TUNING: unlikely() probability is 0.0625. likely() is 0.9375 */
88740 ** pEList is a list of expressions which are really the result set of the
88741 ** a SELECT statement. pE is a term in an ORDER BY or GROUP BY clause.
88742 ** This routine checks to see if pE is a simple identifier which corresponds
88743 ** to the AS-name of one of the terms of the expression list. If it is,
88744 ** this routine return an integer between 1 and N where N is the number of
88745 ** elements in pEList, corresponding to the matching entry. If there is
88746 ** no match, or if pE is not a simple identifier, then this routine
88773 ** pE is a pointer to an expression which is a single term in the
88777 ** At the point this routine is called, we already know that the
88778 ** ORDER BY term is not an integer index into the result set. That
88779 ** case is handled by the calling routine.
88784 ** The left-most column is 1. In other words, the value returned is the
88788 ** If there is no match, return 0. Return -1 if an error occurs.
88850 ** each term of the ORDER BY clause is a constant integer between 1
88851 ** and N where N is the number of columns in the compound SELECT.
88858 ** At the first match, the ORDER BY expression is transformed into
88953 ** the SELECT statement pSelect. If any term is reference to a
88995 ** pOrderBy is an ORDER BY or GROUP BY clause in SELECT statement pSelect.
88996 ** The Name context of the SELECT statement is pNC. zType is either
88997 ** "ORDER" or "GROUP" depending on which type of clause pOrderBy is.
89000 ** If the order-by term is an integer I between 1 and N (where N is the
89002 ** in the resolution is a copy of the I-th result-set expression. If
89003 ** the order-by term is an identifier that corresponds to the AS-name of
89005 ** result-set expression. Otherwise, the expression is resolved in
89033 /* If an AS-name match is found, mark this ORDER BY column as being
89042 /* The ORDER BY term is an integer constant. Again, set the column
89073 int isCompound; /* True if p is a compound select */
89091 ** already expanded this SELECT. However, if this is a subquery within
89121 /* If the SF_Converted flags is set, then this Select object was
89148 ** pItem->fg.isCorrelated flag if this is the case. */
89184 /* If a HAVING clause is present, then there must be a GROUP BY clause.
89187 sqlite3ErrorMsg(pParse, "a GROUP BY clause is required before HAVING");
89192 ** other expressions in the SELECT statement. This is so that
89196 ** Minor point: If this is the case, then the expression will be
89219 /* If this is a converted compound query, move the ORDER BY clause from
89231 ** The ORDER BY clause for compounds SELECT statements is handled
89235 ** If there is an ORDER BY clause on a term of a compound-select other
89236 ** than the right-most term, then that is a syntax error. But the error
89237 ** is not detected until much later, and so we need to go ahead and
89267 /* If this is part of a compound SELECT, check that it has the right
89307 ** The node at the root of the subtree is modified as follows:
89318 ** is replaced by a copy of the left-hand side of the result-set expression.
89324 ** The "x" term of the order by is replaced by "a+b" to render:
89328 ** Function calls are checked to make sure that the function is
89330 ** If the function is an aggregate function, then the NC_HasAgg flag is
89331 ** set and the opcode is changed from TK_FUNCTION to TK_AGG_FUNCTION.
89333 ** property on the expression is set.
89335 ** An error message is left in pParse if anything is amiss. The number
89336 ** if errors is returned.
89379 ** Resolve all names for all expression in an expression list. This is
89431 ** is set to -1 and the Expr.iColumn value is set to the column number.
89465 ** a legal notice, here is a blessing:
89480 ** If pExpr is a column, a reference to a column via an 'AS' alias,
89482 ** affinity of that column is returned. Otherwise, 0x00 is returned,
89526 ** If a memory allocation error occurs, that fact is recorded in pParse->db
89527 ** and the pExpr parameter is returned unchanged.
89573 ** there is no defined collating sequence, return NULL.
89613 /* The Expr.x union is never used at the same time as Expr.pRight */
89640 ** pExpr is an operand of a comparison operator. aff2 is the
89656 /* Neither side of the comparison is a column. Compare the
89661 /* One side is a column, the other is not. Use the columns affinity. */
89668 ** pExpr is a comparison operator. Return the type affinity that should
89689 ** pExpr is a comparison expression, eg. '=', '<', IN(...) etc.
89690 ** idx_affinity is the affinity of an indexed column. Return true
89720 ** If the left hand expression has a collating sequence type, then it is
89722 ** is used, or the default (BINARY) if neither expression has a collating
89726 ** it is not considered.
89758 int jumpIfNull /* If true, jump if either operand is NULL */
89774 ** Check that argument nHeight is less than or equal to the maximum
89775 ** expression depth allowed. If it is not, leave an error message in
89783 "Expression tree is too large (maximum depth %d)", mxHeight
89795 ** If this maximum height is greater than the current value pointed
89852 ** the height is greater than the maximum allowed expression depth,
89887 ** This routine is the core allocator for Expr nodes.
89890 ** for this node and for the pToken argument is a single allocation
89892 ** is responsible for making sure the node eventually gets freed.
89894 ** If dequote is true, then the token (if it exists) is dequoted.
89895 ** If dequote is false, no dequoting is performed. The deQuote
89896 ** parameter is ignored if pToken is NULL or if the token does not
89898 ** then the EP_DblQuoted flag is set on the expression node.
89901 ** can be translated into a 32-bit integer, then the token is not
89902 ** stored in u.zToken. Instead, the integer values is written
89903 ** into u.iValue and the EP_IntValue flag is set. No extra storage
89904 ** is allocated to hold the integer text and the dequote flag is ignored.
90024 ** Add pSelect to the Expr.x.pSelect field. Or, if pExpr is NULL (due
90040 ** If the expression is always either TRUE or FALSE (respectively),
90044 ** This is an optimization. If is OK to return 0 here even if
90045 ** the expression really is always false or false (a false negative).
90046 ** But it is a bug to return 1 if the expression might have different
90049 ** Note that if the expression is part of conditional for a
90051 ** is it true or false, so always return 0.
90067 ** Join two expressions using an AND operator. If either expression is
90070 ** If one side or the other of the AND is known to be false, then instead
90117 ** sure "nnn" is not too be to avoid a denial of service attack when
90121 ** as the previous instance of the same wildcard. Or if this is the first
90122 ** instance of the wildcard, the next sequential variable number is
90201 /* Sanity check: Assert that the IntValue is non-negative if it exists */
90204 /* The Expr.x union is never used at the same time as Expr.pRight */
90225 ** passed as the first argument. This is always one of EXPR_FULLSIZE,
90237 ** how much of the tree is measured.
90248 ** The return values is always one of:
90260 ** During expression analysis, extra information is computed and moved into
90262 ** off if the expression is reduced. Note also that it does not work to
90263 ** make an EXPRDUP_REDUCE copy of a reduced expression. It is only legal
90293 ** string is defined.)
90305 ** expression passed as the first argument. The second argument is a
90311 ** If the EXPRDUP_REDUCE flag is set, then the return value includes
90328 ** This function is similar to sqlite3ExprDup(), except that if pzBuffer
90329 ** is not NULL then *pzBuffer is assumed to point to a buffer large enough
90332 ** if any. Before returning, *pzBuffer is set to the first byte past the
90357 ** by pNew. This is either EXPR_FULLSIZE, EXPR_REDUCEDSIZE or
90358 ** EXPR_TOKENONLYSIZE. nToken is set to the number of bytes consumed
90424 ** argument. If an OOM condition is encountered, NULL is returned
90462 ** If the EXPRDUP_REDUCE flag is set, then the structure returned is a
90502 ** sqlite3SelectDup(), can be called. sqlite3SelectDup() is sometimes
90561 /* Note that because the size of the allocation for p->a[] is not
90609 ** Add a new element to the end of an expression list. If pList is
90612 ** If a memory allocation error occurs, the entire list is freed and
90613 ** NULL is returned. If non-NULL is returned, then it is guaranteed
90675 ** is set.
90700 ** is set.
90786 ** is found to not be a constant.
90788 ** The sqlite3ExprIsConstantOrFunction() is used for evaluating expressions
90789 ** in a CREATE TABLE statement. The Walker.eCode value is 5 when parsing
90791 ** parameter raises an error for new statements, but is silently converted
90799 /* If pWalker->eCode is 2 then any term of the expression that comes from
90868 ** Walk an expression tree. Return non-zero if the expression is constant
90872 ** is considered a variable but a single-quoted string (ex: 'abc') is
90880 ** Walk an expression tree. Return non-zero if the expression is constant
90890 ** Walk an expression tree. Return non-zero if the expression is constant
90900 ** Walk an expression tree. Return non-zero if the expression is constant
90905 ** is considered a variable but a single-quoted string (ex: 'abc') is
90930 ** If the expression p codes a constant integer that is small enough
90932 ** in *pValue. If the expression is not an integer or if it is too big
90938 /* If an expression is an integer literal that fits in a signed 32-bit
90967 ** Return FALSE if there is no chance that the expression can be NULL.
90969 ** If the expression might be NULL or if the expression is too complex
90972 ** This routine is used as an optimization, to skip OP_IsNull opcodes
90975 ** be a small performance hit but is otherwise harmless. On the other
91001 ** Return TRUE if the given expression is a constant which would be
91005 ** This routine is used to determine if the OP_Affinity operation
91007 ** is harmless. A false positive, however, can result in the wrong
91041 ** Return TRUE if the given string is a row-id column name.
91051 ** pX is the RHS of an IN operator. If pX is a SELECT statement
91053 ** a pointer to the SELECT statement. If pX is not a SELECT statement,
91080 if( pSrc->a[0].pSelect ) return 0; /* FROM is not a subquery or view */
91083 assert( pTab->pSelect==0 ); /* FROM clause is not a view */
91088 if( pRes->op!=TK_COLUMN ) return 0; /* Result is a column */
91122 ** The argument is an IN operator with a list (not a subquery) on the
91123 ** right-hand side. Return TRUE if that list is constant.
91138 ** This function is used by the implementation of the IN (...) operator.
91139 ** The pX parameter is the expression on the RHS of the IN operator, which
91142 ** The job of this routine is to find or create a b-tree object that can
91146 ** A cursor is opened on the b-tree object that is the RHS of the IN operator
91147 ** and pX->iTable is set to the index of that cursor.
91159 ** An existing b-tree might be used if the RHS expression pX is a simple
91164 ** If the RHS of the IN operator is a list or a more complex subquery, then
91172 ** fast membership test. When the IN_INDEX_LOOP bit is set, the
91176 ** When IN_INDEX_LOOP is used (and the b-tree will be used to iterate
91178 ** An epheremal table must be used unless the selected <column> is guaranteed
91179 ** to be unique - either because it is an INTEGER PRIMARY KEY or it
91182 ** When IN_INDEX_MEMBERSHIP is used (and the b-tree will be used
91184 ** be used unless <column> is an INTEGER PRIMARY KEY or an index can
91188 ** if the RHS of the IN operator is a list (not a subquery) then this
91190 ** testing is too expensive and return IN_INDEX_NOOP. In that case, the
91194 ** When the b-tree is being used for membership tests, the calling function
91196 ** contains a NULL. If prRhsHasNull is not a NULL pointer and
91197 ** if there is any chance that the (...) might contain a NULL value at
91198 ** runtime, then a register is allocated and the register number written
91199 ** to *prRhsHasNull. If there is no chance that the (...) contains a
91200 ** NULL value, then *prRhsHasNull is left unchanged.
91202 ** If a register is allocated and its location stored in *prRhsHasNull, then
91219 ** satisfy the query. This is preferable to generating a new
91241 /* This function is only called from two places. In both cases the vdbe
91242 ** has already been allocated. So assume sqlite3GetVdbe() is always
91257 /* The collation sequence used by the comparison. If an index is to
91263 ** comparison is the same as the affinity of the column. If
91264 ** it is not, it is not possible to use any index.
91295 /* If no preexisting index is available for the IN clause
91296 ** and IN_INDEX_NOOP is an allowed reply
91297 ** and the RHS of the IN operator is a list, not a subquery
91298 ** and the RHS is not constant or has two or fewer terms,
91299 ** then it is not worth creating an ephemeral table to evaluate
91347 ** If parameter isRowid is non-zero, then expression pExpr is guaranteed
91348 ** to be of the form "<rowid> IN (?, ?, ?)", where <rowid> is a reference
91353 ** If rMayHaveNull is non-zero, that means that the operation is an IN
91355 ** All this routine does is initialize the register given by rMayHaveNull
91357 ** value to non-NULL if the RHS is NULL-free.
91360 ** result. For IN operators or if an error occurs, the return value is 0.
91367 int isRowid /* If true, LHS of IN operator is a rowid */
91375 /* This code must be run in its entirety every time it is encountered
91376 ** if any of the following is true:
91378 ** * The right-hand side is a correlated subquery
91379 ** * The right-hand side is an expression list containing variables
91409 /* Whether this is an 'x IN(SELECT...)' or an 'x IN(<exprlist>)'
91410 ** expression it is handled the same way. An ephemeral table is
91414 ** If the 'x' expression is a column value, or the SELECT...
91416 ** column is used to build the index keys. If both 'x' and the
91417 ** SELECT... statement are columns, then numeric affinity is used
91420 ** is used.
91458 ** store it in the temporary table. If <expr> is a column, then use
91459 ** that columns affinity when building index keys. If <expr> is not
91483 /* If the expression is not constant then we will need to
91524 ** of the memory cell in iColumn. If this is an EXISTS, write
91582 ** The left-hand side (LHS) is a scalar expression. The right-hand side (RHS)
91583 ** is an array of zero or more values. The expression is true if the LHS is
91584 ** contained within the RHS. The value of the expression is unknown (NULL)
91585 ** if the LHS is NULL or if the LHS is not contained within the RHS and the
91588 ** This routine generates code that jumps to destIfFalse if the LHS is not
91590 ** is contained in the RHS then jump to destIfNull. If the LHS is contained
91596 int destIfFalse, /* Jump here if LHS is not contained in the RHS */
91599 int rRhsHasNull = 0; /* Register that is true if RHS contains NULL values */
91627 /* If sqlite3FindInIndex() did not find or create an index that is
91670 /* If the LHS is NULL, then the result is either false or NULL depending
91671 ** on whether the RHS is empty or not, respectively.
91688 /* In this case, the RHS is the ROWID of table b-tree
91693 /* In this case, the RHS is an index b-tree.
91699 ** contains no NULL values, then the result is 0. If the set
91701 ** expression is also NULL.
91705 /* This branch runs if it is known at compile time that the RHS
91709 ** Also run this branch if NULL is equivalent to FALSE
91721 /* First check to see if the LHS is contained in the RHS. If so,
91722 ** then the answer is TRUE the presence of NULLs in the RHS does
91723 ** not matter. If the LHS is not contained in the RHS, then the
91724 ** answer is NULL if the RHS contains NULLs and the answer is
91725 ** FALSE if the RHS is NULL-free.
91748 ** z[n] character is guaranteed to be something that does not look
91767 ** Expr.u.zToken is always UTF8 and zero-terminated.
91833 ** particular table is stored in a particular register.
91845 /* The SQLITE_ColumnCache flag disables the column cache. This is used
91853 ** Actually, the way the column cache is currently used, we are guaranteed
91951 ** When a cached column is reused, make sure that its register is
91966 /* Generate code that will load into register regOut a value that is
91971 Index *pIdx, /* The index whose column is to be loaded */
92017 ** An effort is made to store the column value in register iReg. This
92018 ** is not garanteeed for GetColumn() - the result can be stored in
92019 ** any register. But the result is guaranteed to land in register iReg
92023 ** is called. If iColumn<0 then code is generated that extracts the rowid.
92105 ** is used as part of the column cache.
92107 ** This routine is used within assert() and testcase() macros only
92137 ** With this routine, there is no guarantee that results will
92139 ** register if it is convenient to do so. The calling function
92187 /* Coding an expression that is part of an index where column names
92436 /* The UNLIKELY() function is a no-op. The result is the value
92489 /* Possibly overload the function if the first argument is
92494 ** see if it is a column in a virtual table. This is done because
92497 ** function. The expression "A glob B" is equivalent to
92544 ** This is equivalent to
92548 ** X is stored in pExpr->pLeft.
92549 ** Y is stored in pExpr->pList->a[0].pExpr.
92550 ** Z is stored in pExpr->pList->a[1].pExpr.
92585 /* If the opcode is TK_TRIGGER, then the expression is a reference
92587 ** trigger programs. In this case Expr.iTable is set to 1 for the
92589 ** is set to the column of the pseudo-table to read, or to -1 to
92592 ** The expression is implemented using an OP_Param opcode. The p1
92593 ** parameter is set to 0 for an old.rowid reference, or to (i+1)
92595 ** i is the index of the column. For a new.rowid reference, p1 is
92596 ** set to (n+1), where n is the number of columns in each pseudo-table.
92598 ** is set to (n+2+i), where n and i are as defined previously. For
92599 ** example, if the table on which triggers are being fired is
92604 ** Then p1 is interpreted as follows:
92627 ** integer. Use OP_RealAffinity to make sure it is really real.
92648 ** Form A is can be transformed into the equivalent form B as follows:
92652 ** X (if it exists) is in pExpr->pLeft.
92653 ** Y is in the last element of pExpr->x.pList if pExpr->x.pList->nExpr is
92654 ** odd. The Y is also optional. If the number of elements in x.pList
92655 ** is even, then Y is omitted and the "otherwise" result is NULL.
92656 ** Ei is in pExpr->pList->a[i*2] and Ri is pExpr->pList->a[i*2+1].
92658 ** The result of the expression is the Ri for the first matching Ei,
92659 ** or if there is no matching Ei, the ELSE term Y, or if there is
92690 ** So make sure that the regFree1 register is not reused for other
92764 u8 reusable /* True if this expression is reusable */
92784 ** If the register is a temporary register that can be deallocated,
92785 ** then write its number into *pReg. If the result register is not
92788 ** If pExpr is a constant, then this routine might generate this
92848 ** except that the input expression is guaranteed to be unchanged.
92860 ** in register target. If the expression is constant, then this routine
92876 ** and modify the expression so that the next time it is evaluated,
92877 ** the result is a copy of the cache register.
92879 ** This routine is used for expressions that are used multiple
92957 ** The above is equivalent to
92967 int dest, /* Jump here if the jump is taken */
92968 int jumpIfTrue, /* Take the jump if the BETWEEN is true */
92969 int jumpIfNull /* Take the jump if the BETWEEN is NULL */
93008 ** Generate code for a boolean expression such that a jump is made
93009 ** to the label "dest" if the expression is true but execution
93010 ** continues straight thru if the expression is false.
93013 ** take the jump if the jumpIfNull flag is SQLITE_JUMPIFNULL.
93134 ** Generate code for a boolean expression such that a jump is made
93135 ** to the label "dest" if the expression is false but execution
93136 ** continues straight thru if the expression is true.
93139 ** jump if jumpIfNull is SQLITE_JUMPIFNULL or fall through if jumpIfNull
93140 ** is 0.
93166 ** For other values of pExpr->op, op is undefined and unused.
93169 ** Assert()s verify that the computation is correct.
93286 ** Like sqlite3ExprIfFalse() except that a copy is made of pExpr before
93287 ** code generation, and that copy is deleted after code generation. This
93288 ** ensures that the original pExpr is unchanged.
93306 ** If any subelement of pB has Expr.iTable==(-1) then it is allowed
93309 ** The pA side might be using TK_REGISTER. If that is the case and pB is
93310 ** not using TK_REGISTER but is otherwise equivalent, then still return 0.
93318 ** this routine is used, it does not hurt to get an extra 2 - that
93369 ** If any subelement of pB has Expr.iTable==(-1) then it is allowed
93395 ** Return true if we can prove the pE2 will always be true if pE1 is
93412 ** it will always give the correct answer and is hence always safe.
93434 ** An instance of the following structure is used by the tree walker
93437 ** table entry. The IdxCover.pIdx field is the index. IdxCover.iCur
93438 ** is the cursor for the table.
93489 ** An instance of the following structure is used by the tree walker
93504 /* The NEVER() on the second term is because sqlite3FunctionUsesThisSrc()
93505 ** is always called before sqlite3ExprAnalyzeAggregates() and so the
93507 ** sqlite3FunctionUsesThisSrc() is used differently in the future, the
93579 ** This is the xExprCallback for a tree walker. It is used to
93595 /* Check to see if the column is in one of the tables in the FROM
93604 ** that is in the FROM clause of the aggregate query.
93607 ** is not an entry there already.
93645 /* There is now an entry for pExpr in pAggInfo->aCol[] (either
93664 /* Check to see if pExpr is a duplicate of another aggregate
93665 ** function that is already in the pAggInfo structure
93674 /* pExpr is original. Make a new entry in pAggInfo->aFunc[]
93737 ** If an error is found, the analysis is cut short.
93763 ** If a register is currently being used by the column cache, then
93764 ** the deallocation is deferred until the column cache line that uses
93816 ** iFirst..iLast, inclusive. This routine is only call from within assert()
93843 ** a legal notice, here is a blessing:
93863 ** This function is used by SQL generated to implement the
93864 ** ALTER TABLE command. The first argument is the text of a CREATE TABLE or
93865 ** CREATE INDEX command. The second is a table name. The table name in
93866 ** the CREATE TABLE or CREATE INDEX statement is replaced with the third
93894 ** statement is that the table name is the first non-space token that
93895 ** is immediately followed by a TK_LP or TK_USING token.
93925 ** This C function implements an SQL user function that is used by SQL code
93928 ** parent table. It is passed three arguments:
93990 /* This function is used by SQL generated to implement the
93991 ** ALTER TABLE command. The first argument is the text of a CREATE TRIGGER
93992 ** statement. The second is a table name. The table name in the CREATE
93993 ** TRIGGER statement is replaced with the third argument and the result
93994 ** returned. This is analagous to renameTableFunc() above, except for CREATE
94016 ** statement is that the table name is the first token that is immediately
94043 ** token is read and 'dist' equals 2, the condition stated above
94047 ** there is no need to worry about syntax like
94056 /* Variable tname now contains the token that is the old table-name
94083 ** This function is used to create the text of expressions of the form:
94087 ** If argument zWhere is NULL, then a pointer string containing the text
94088 ** "name=<constant>" is returned, where <constant> is the quoted version
94089 ** of the string passed as argument zConstant. The returned buffer is
94090 ** allocated using sqlite3DbMalloc(). It is the responsibility of the
94091 ** caller to ensure that it is eventually freed.
94093 ** If argument zWhere is not NULL, then the string returned is
94094 ** "<where> OR name=<constant>", where <where> is the contents of zWhere.
94095 ** In this case zWhere is passed to sqlite3DbFree() before returning.
94113 ** constraints for which pTab is the parent table) from the sqlite_master
94129 ** table pTab has no temporary triggers, or is itself stored in the
94130 ** temporary database, NULL is returned.
94137 /* If the table is not located in the temp-db (in which case NULL is
94139 ** that is not part of the temp-db schema, add a clause to the WHERE
94161 ** Argument zName is the name of the table in the database schema at
94162 ** the time the generated code is executed. This can be different from
94163 ** pTab->zName if this function is being called to code part of an
94198 /* Now, if the table is not stored in the temp database, reload any temp
94199 ** triggers. Don't use IN(...) in case SQLITE_OMIT_SUBQUERY is defined.
94208 ** Parameter zName is the name of a table that is about to be altered
94210 ** If the table is a system table, this function leaves an error message
94213 ** Or, if zName is not a system table, zero is returned.
94243 VTable *pVTab = 0; /* Non-zero if this is a v-tab with an xRename() */
94262 ** in database iDb. If so, this is an error.
94266 "there is already another table or index with this name: %s", zName);
94270 /* Make sure it is not a system table being altered, or a reserved name
94271 ** that the table is being renamed to.
94308 ** schema). Open a statement transaction if the table is a virtual
94318 /* If this is a virtual table, invoke the xRename() function if
94319 ** one is defined. The xRename() callback will modify the names
94338 /* If foreign-key support is enabled, rewrite the CREATE TABLE
94340 ** for which the renamed table is the parent table. */
94389 ** table. Don't do this if the table being ALTERed is itself located in
94424 ** This function is called after an "ALTER TABLE ... ADD" statement
94475 /* Check that the new column is not specified as PRIMARY KEY or UNIQUE.
94476 ** If there is a NOT NULL constraint, then the default value for the
94498 /* Ensure the default expression is something that sqlite3ValueFromExpr()
94537 /* Make sure the schema version is at least 3. But do not upgrade
94555 ** This function is called by the parser after the table-name in
94556 ** an "ALTER TABLE <table-name> ADD" statement is parsed. Argument
94557 ** pSrc is the full-name of the table being altered.
94562 ** is parsed (i.e. sqlite3AddColumn()) add the new Column data to
94563 ** the copy. The copy of the Table structure is deleted by tokenize.c
94564 ** after parsing is finished.
94592 /* Make sure this is not an attempt to ALTER a view. */
94654 ** a legal notice, here is a blessing:
94675 ** The sqlite_stat2 table is not created or used unless the SQLite version
94676 ** is between 3.6.18 and 3.7.8, inclusive, and unless SQLite is compiled
94677 ** with SQLITE_ENABLE_STAT2. The sqlite_stat2 table is deprecated.
94678 ** The sqlite_stat2 table is superseded by sqlite_stat3, which is only
94681 ** is a superset of sqlite_stat2. The sqlite_stat4 is an enhanced
94682 ** version of sqlite_stat3 and is only available when compiled with
94683 ** SQLITE_ENABLE_STAT4 and in SQLite versions 3.8.1 and later. It is
94692 ** There is normally one row per index, with the index identified by the
94693 ** name in the idx column. The tbl column is the name of the table to
94696 ** list is the number of rows in the index. (This is the same as the
94698 ** integer is the average number of rows in the index that have the same
94699 ** value in the first column of the index. The third integer is the average
94701 ** columns. The N-th integer (for N>1) is the average number of rows in
94704 ** the index is unique, then the last integer will be 1.
94707 ** by the keyword "unordered". The "unordered" keyword, if it is present,
94709 ** "unordered" keyword is present, then the query planner assumes that
94710 ** the index is unordered and will not use the index for a range query.
94712 ** If the sqlite_stat1.idx column is NULL, then the sqlite_stat1.stat
94713 ** column contains a single integer which is the (estimated) number of
94718 ** The sqlite_stat2 is only created and is only used if SQLite is compiled
94719 ** with SQLITE_ENABLE_STAT2 and if the SQLite version number is between
94721 ** about the distribution of keys within an index. The index is identified by
94722 ** the "idx" column and the "tbl" column is the name of the table to which
94734 ** For i between 0 and S-1. Conceptually, the index space is divided into
94737 ** The format for sqlite_stat2 is recorded here for legacy reference. This
94744 ** The sqlite_stat3 format is a subset of sqlite_stat4. Hence, the
94756 ** The idx column names the index and the tbl column is the table of the
94757 ** index. If the idx and tbl columns are the same, then the sample is
94758 ** of the INTEGER PRIMARY KEY. The sample column is a blob which is the
94759 ** binary encoding of a key from the index. The nEq column is a
94760 ** list of integers. The first integer is the approximate number
94763 ** is the approximate number of entries in the index where the
94765 ** And so forth. nLt is another list of integers that show the approximate
94768 ** left-most column is less than the left-most column of the sample.
94769 ** The K-th integer in the nLt entry is the number of index entries
94771 ** sample. The nDLt column is like nLt except that it contains the
94783 ** The sqlite_stat3 table is like sqlite_stat4 except that it only
94786 ** of a blob encoding of the complete index key as is found in
94788 ** all contain just a single integer which is the same as the first
94810 ** The sqlite_stat1 table is always relevant. sqlite_stat2 is now
94814 ** If the sqlite_statN tables do not previously exist, it is created.
94817 ** or it may be a NULL pointer. If it is not NULL, then all entries in
94819 ** If zWhere==0, then code is generated to delete all stat table entries.
94865 ** side-effect of the CREATE TABLE statement is to leave the rootpage
94866 ** of the new table in register pParse->regRoot. This is important
94875 /* The table already exists. If zWhere is not NULL, delete all entries
94876 ** associated with the table zWhere. If zWhere is NULL, delete the
95028 ** WITHOUT ROWID table, N is the number of PRIMARY KEY columns, not the
95031 ** Note 2: C is only used for STAT3 and STAT4.
95034 ** WITHOUT ROWID tables, N=K+P where P is the number of columns in the
95039 ** value is a pointer to the Stat4Accum object. The datatype of the
95040 ** return value is BLOB, but it is really just a pointer to the Stat4Accum
95121 ** (given by the 3rd parameter) is never used and can be any positive
95141 ** function returns true if sample pNew is to be preferred over pOld.
95143 ** column for pNew and pOld are equal, is pNew to be preferred over pOld.
95167 ** Return true if pNew is to be preferred over pOld.
95210 /* This sample is being added because the prefix that ends in column
95212 ** added a sample that shares this prefix, there is no need to add
95317 /* Check if this is to be a periodic sample. If so, add it. */
95324 /* Or if it is a non-periodic sample. Add it in this case too. */
95353 ** The R parameter is only used for STAT3 and STAT4
95372 /* This is the first call to this function. Do initialization. */
95406 /* Check if this is to be a periodic sample. If so, add it. */
95442 ** Implementation of the stat_get(P,J) SQL function. This routine is
95445 ** has type BLOB but it is really just a pointer to the Stat4Accum object.
95446 ** The content to returned is determined by the parameter J
95447 ** which is one of the STAT_GET_xxxx values defined above.
95449 ** If neither STAT3 nor STAT4 are enabled, then J is always
95450 ** STAT_GET_STAT1 and is hence omitted and this routine becomes
95476 ** The value is a string composed of a list of integers describing
95477 ** the index. The first integer in the list is the total number of
95478 ** entries in the index. There is one additional integer in the list
95479 ** for each indexed column. This additional integer is an estimate of
95482 ** if the index is on columns (a,b) and the sqlite_stat1 value is
95489 ** If D is the count of distinct values and K is the total number of
95490 ** rows, then each estimate is computed as:
95612 int jZeroRows = -1; /* Jump from here if number of rows is zero */
95653 ** to use for scanning indexes (iIdxCur). No index cursor is opened at
95718 ** the regPrev array and a trailing rowid (the rowid slot is required
95737 ** The third argument is only used for STAT3 and STAT4
95922 ** be loaded into internal hash tables where is can be used.
95958 ** a database. If pOnlyIdx is not NULL then it is a single index
96128 ** This callback is invoked once for each index when reading the
96193 ** If the Index.aSample variable is not NULL, delete the aSample[] array
96228 /* If this is stat4 data, then calculate aAvgEq[] values for all
96229 ** sample columns except the last. The last is always set to 1, as
96278 ** is supplied instead, find the PRIMARY KEY index for that table.
96304 ** where %Q is replaced with the database name before the SQL is executed.
96343 /* Index.nSample is non-zero at this point if data has already been
96393 /* This next condition is true if data has already been loaded from
96407 ** This is in case the sample record is corrupted. In that case, the
96409 ** end of the allocated buffer before it realizes it is dealing with
96460 ** If the sqlite_stat1 table is not present in the database, SQLITE_ERROR
96461 ** is returned. In this case, even if SQLITE_ENABLE_STAT3/4 was defined
96462 ** during compilation and the sqlite_stat3/4 table is present, no data is
96466 ** sqlite_stat4 table is not present in the database, SQLITE_ERROR is
96467 ** returned. However, in this case, data is read from the sqlite_stat1
96468 ** table (if it is present) before returning.
96544 ** a legal notice, here is a blessing:
96558 ** is slightly different from resolving a normal SQL expression, because simple
96595 ** If the optional "KEY z" syntax is omitted, an SQL NULL is passed as the
96642 zErrDyn = sqlite3MPrintf(db, "database %s is already in use", zName);
96662 /* Open the database file. If the btree is successfully opened, use
96681 zErrDyn = sqlite3MPrintf(db, "database is already attached");
96834 sqlite3_snprintf(sizeof(zErr),zErr, "database %s is locked", zName);
96966 int iDb, /* This is the database that must be used */
96991 ** allowed to refer to anything.) If a reference is explicitly made
96992 ** to an object in a different database, an error message is added to
97128 ** a legal notice, here is a blessing:
97136 ** API. This facility is an optional feature of the library. Embedded
97151 ** The access authorization function is be called during the compilation
97154 ** is a copy of the 3rd argument to this routine. The second argument
97155 ** to the auth function is one of these constants:
97184 ** SQLITE_OK is returned, it means that access is allowed. SQLITE_DENY
97191 ** setting of the auth function is NULL.
97221 ** callback has been registered (i.e. that sqlite3.xAuth is not NULL).
97223 ** If SQLITE_IGNORE is returned and pExpr is not NULL, then pExpr is changed
97224 ** to an SQL NULL expression. Otherwise, if pExpr is NULL, then SQLITE_IGNORE
97225 ** is treated as SQLITE_DENY. In this case an error is left in pParse.
97245 sqlite3ErrorMsg(pParse, "access to %s.%s.%s is prohibited",zDb,zTab,zCol);
97247 sqlite3ErrorMsg(pParse, "access to %s.%s is prohibited", zTab, zCol);
97258 ** is in pTabList or else it is the NEW or OLD table of a trigger.
97259 ** Check to see if it is OK to read this particular column.
97319 ** is returned, then the error count and error message in pParse are
97332 /* Don't do any authorization checks if the database is initialising
97333 ** or if the parser is being invoked from within sqlite3_declare_vtab.
97358 ** Push an authorization context. After this routine is called, the
97360 ** popped. Or if pParse==0, this routine is a no-op.
97392 ** a legal notice, here is a blessing:
97416 ** The TableLock structure is only used by the sqlite3TableLock() and
97429 ** The table to be locked has root page iTab and is found in database iDb.
97432 ** This routine just records the fact that the lock is desired. The
97433 ** code to make the lock occur is generated by a later call to
97495 ** Return TRUE if the given yDbMask object is empty - if it contains no
97496 ** 1 bits. This routine is used by the DbMaskAllZero() and DbMaskNotZero()
97497 ** macros when SQLITE_MAX_ATTACHED is greater than 30.
97508 ** This routine is called after a single SQL statement has been
97551 ** (Bit 0 is for main, bit 1 is for temp, and so forth.) Bits are
97552 ** set for each database that is used. Generate code to start a
97585 ** obtain the required table-locks. This is a no-op unless the
97586 ** shared-cache feature is enabled.
97613 /* A minimum of one cursor is required if autoincrement is used
97622 /* We are done with this Parse object. There is no need to de-initialize it */
97636 ** currently under construction. When the parser is run recursively
97637 ** this way, the final OP_Halt is not appended and other initialization
97641 ** Not everything is nestable. This facility is designed to permit
97673 ** Return TRUE if zTable is the name of the system table that stores the
97686 ** If zDatabase is 0, all databases are searched for the table and the
97687 ** first matching table is returned. (No checking for duplicate table
97688 ** names is done.) The search order is TEMP first, then MAIN, then any
97700 /* Only the admin user is allowed to know that the sqlite_user table
97722 ** The difference between this routine and sqlite3FindTable() is that this
97745 /* If zName is the not the name of a table in the schema created using
97746 ** CREATE, then check to see if it is the name of an virtual table that
97770 ** This is a wrapper around sqlite3LocateTable(). The difference between
97771 ** sqlite3LocateTable() and this function is that this function restricts
97772 ** the search to schema (p->pSchema) if it is not NULL. p->pSchema may be
97773 ** non-NULL if it is part of a view or trigger program definition. See
97798 ** If zDatabase is 0, all databases are searched for the
97799 ** table and the first matching index is returned. (No checking
97800 ** for duplicate index names is done.) The search order is
97839 ** For the index called zIdxName which is found in the database iDb,
97913 /* If any database other than TEMP is reset, then also reset TEMP
97945 ** This routine is called when a commit occurs.
97978 ** The db parameter is optional. It is needed if the Table object
98058 ** is obtained from sqliteMalloc() and must be freed by the calling
98066 ** is \000 terminated and is persistent.
98081 ** writing. The table is opened using cursor 0.
98124 /* The table or view or trigger name is passed to this routine via tokens
98129 ** Then pName1 is set to "xxx" and pName2 "yyy". On the other hand if
98130 ** the table name is not fully qualified, i.e.:
98134 ** Then pName1 is set to "yyy" and pName2 is "".
98138 ** database "xxx" is returned.
98170 ** This routine is used to check if the UTF-8 string zName is a legal
98174 ** is reserved for internal use.
98208 ** Begin constructing a new table representation in memory. This is
98210 ** to a CREATE TABLE statement. In particular, this routine is called
98212 ** flag is true if the table should be stored in the auxiliary database
98213 ** file instead of in the main database file. This is normally the case
98217 ** The new table record is initialized and put in pParse->pNewTable.
98218 ** As more of the CREATE TABLE statement is parsed, additional action
98221 ** is called to complete the construction of the new table record.
98227 int isTemp, /* True if this is a TEMP table */
98228 int isView, /* True if this is a VIEW */
98229 int isVirtual, /* True if this is a VIRTUAL table */
98250 ** the database name is "temp" anyway. */
98286 ** it does. The exception is if the statement being parsed was passed
98288 ** and types will be used, so there is no need to test for namespace
98307 sqlite3ErrorMsg(pParse, "there is already an index named %s", zName);
98327 /* If this is the magic sqlite_sequence table used by autoincrement,
98350 /* nullRow[] is an OP_Record encoding of a row containing 5 NULLs */
98379 ** The rowid for the new entry is left in register pParse->regRowid.
98380 ** The root page number of the new table is left in reg pParse->regRoot.
98428 ** first to get things going. Then this routine is called for each
98472 /* If there is no type specified, columns have the default affinity
98489 ** This routine is called by the parser while in the middle of
98506 ** substrings in the following table. If one of the substrings is
98507 ** found, the corresponding affinity is returned. If zType contains
98509 ** the table take priority. For example, if zType is 'BLOBINT',
98510 ** SQLITE_AFF_INTEGER is returned.
98524 ** SQLITE_AFF_NUMERIC is returned.
98563 /* If pszEst is not NULL, store an estimate of the field size. The
98564 ** estimate is scaled so that the size of an integer is 1. */
98566 *pszEst = 1; /* default size is approx 4 bytes */
98589 ** The expression is the default value for the most recently added column
98593 ** is not the case.
98595 ** This routine is called by the parser while in the middle of
98606 sqlite3ErrorMsg(pParse, "default value of column [%s] is not constant",
98609 /* A copy of pExpr is used instead of the original, as pExpr contains
98611 ** is required by pragma table_info.
98637 ** This is goofy. But to preserve backwards compatibility we continue to
98640 ** if the expression is just a TK_STRING with an optional COLLATE clause.
98641 ** If the epxression is anything other than TK_STRING, the expression is
98653 ** Designate the PRIMARY KEY for the table. pList is a list of names
98654 ** of columns that form the primary key. If pList is NULL, then the
98655 ** most recently added column of the table is the primary key.
98658 ** a primary key (and this is the second primary key) then create an
98661 ** If the PRIMARY KEY is on a single column whose datatype is INTEGER,
98664 ** INTEGER PRIMARY KEY column. Table.iPKey is set to -1 if there is
98667 ** If the key is not an INTEGER PRIMARY KEY, then create a unique
98668 ** index for the key. No index is created for INTEGER PRIMARY KEYs.
98674 int autoInc, /* True if the AUTOINCREMENT keyword is present */
98723 sqlite3ErrorMsg(pParse, "AUTOINCREMENT is only allowed on an "
98782 /* If the column is declared as "<name> PRIMARY KEY COLLATE <type>",
98784 ** collation type was added. Correct this if it is the case.
98801 ** If the requested collation sequence is not available, or not available
98802 ** in the database native encoding, the collation factory is invoked to
98804 ** and the sequence is available in another text encoding, then that is
98808 ** another error occurs, NULL is returned and an error message written into
98811 ** This routine is a wrapper around sqlite3FindCollSeq(). This routine
98835 ** The schema cookie is used to determine when the schema for the
98842 ** This plan is not completely bullet-proof. It is possible for
98845 ** and the probability of hitting the same cookie value is only
98861 ** The estimate is conservative. It might be larger that what is
98873 ** The first parameter is a pointer to an output buffer. The second
98874 ** parameter is a pointer to an integer that contains the offset at
98881 ** characters, does not begin with a digit and is not an SQL keyword,
98882 ** then it is copied to the output buffer exactly as it is. Otherwise,
98883 ** it is quoted using double-quotes.
98910 ** table. Memory to hold the text of the statement is obtained
99031 /* Return true if value x is found any of the first nCol entries of aiCol[]
99040 ** has a WITHOUT ROWID clause. The job of this routine is to convert both
99046 ** (2) Convert the OP_CreateTable into an OP_CreateIndex. There is
99048 ** data storage is a covering index btree.
99050 ** for the PRIMARY KEY as the primary key index is now
99055 ** so that the PRIMARY KEY is a covering index. The surplus
99061 ** For virtual tables, only (1) is performed.
99115 ** table entry. This is only required if currently generating VDBE
99142 /* The root page of the PRIMARY KEY is the table root page */
99155 /* This index is a superset of the primary key */
99191 ** This routine is called to report the final ")" that terminates
99195 ** is added to the internal hash tables, assuming no errors have
99198 ** An entry for the table is made in the master table on disk, unless
99199 ** this is a temporary table or db->init.busy==1. When db->init.busy==1
99205 ** If the pSelect argument is not NULL, it means that this routine
99231 /* If the db->init.busy is 1 it means we are reading the SQL off the
99237 ** If the root page number is 1, that means this is the sqlite_master
99279 ** If this is a TEMPORARY table, write the entry into the auxiliary
99309 /* If this is a CREATE TABLE xx AS SELECT ..., execute the SELECT
99311 ** new table is in register pParse->regRoot.
99313 ** Once the SELECT has been coded by sqlite3Select(), it is in a
99317 ** A shared-cache write-lock is not required to write to the new table,
99520 ** The Table structure pTable is really a VIEW. Fill in the names of
99522 ** of errors. If an error is seen leave an error message in pParse->zErrMsg.
99547 /* A negative nCol is a special marker meaning that we are currently
99554 ** Actually, the error above is now caught prior to reaching this point.
99555 ** But the following test is still important as it does come up
99563 sqlite3ErrorMsg(pParse, "view %s is circularly defined", pTable->zName);
99572 ** to be permanent. So the computation is done on a copy of the SELECT
99594 ** arglist which is stored in pTable->pCheck. The pCheck field
99655 ** This function is called by the VDBE to adjust the internal schema
99663 ** have the same rootpage number as the real table or index that is
99666 ** or tables and not the table/index that is actually being moved.
99699 ** if a root-page of another table is moved by the btree-layer whilst
99710 ** is non-zero, then it is the root page number of a table moved to
99714 ** The "#NNN" in the SQL is a special constant that means whatever value
99715 ** is in register NNN. See grammar rules associated with the TK_REGISTER
99728 ** in case a root-page belonging to another table is moved by the btree layer
99729 ** is also added (this can happen with an auto-vacuum database).
99741 ** is not defined), then it is important to call OP_Destroy on the
99744 ** to be destroyed is relocated by an earlier OP_Destroy. i.e. if the
99829 ** is generated to remove entries from sqlite_master and/or
99842 ** the table being dropped. This is done before the table is dropped
99880 ** This routine is called to do the work of a DROP TABLE statement.
99881 ** pName is the name of the table to be dropped.
99907 /* If pTab is a virtual table, call ViewGetColumnNames() to ensure
99908 ** it is initialized.
99955 /* Ensure DROP TABLE is not used on a view, and DROP VIEW is not used
99984 ** This routine is called to create a new foreign key on the table
99987 ** connect the key to the last column inserted. pTo is the name of
99988 ** the table referred to (a.k.a the "parent" table). pToCol is a list
99993 ** An FKey structure is created and added to the table currently
99996 ** The foreign key is set for IMMEDIATE processing. A subsequent call
100114 ** This routine is called when an INITIALLY IMMEDIATE or INITIALLY DEFERRED
100115 ** clause is seen as part of a foreign key definition. The isDeferred
100116 ** parameter is 1 for INITIALLY DEFERRED and 0 for INITIALLY IMMEDIATE.
100117 ** The behavior of the most recently created foreign key is adjusted
100131 ** Generate code that will erase and refill index *pIdx. This is
100135 ** if memRootPage is not negative, it means that the index is newly
100137 ** root page number of the index. If memRootPage is negative, then
100139 ** the root page number of the index is taken from pIndex->tnum.
100142 Table *pTab = pIndex->pTable; /* The table that is indexed */
100257 ** Create a new index for an SQL table. pName1.pName2 is the name of the index
100258 ** and pTblList is the name of the table that is to be indexed. Both will
100259 ** be NULL for a primary key or an index that is created to satisfy a
100261 ** as the table to be indexed. pParse->pNewTable is a table that is
100264 ** pList is a list of columns to be indexed. pList will be NULL if this
100265 ** is a primary key or unique-constraint on the most recent column added
100290 int iDb; /* Index of the database that is being written */
100309 ** Find the table that is to be indexed. Return early if not found.
100324 ** is a temp table. If so, set the database to 1. Do not do this
100385 ** Find the name of the index. Make sure there is not already another
100406 sqlite3ErrorMsg(pParse, "there is already a table named %s", zName);
100516 ** report any errors. In the common case where the expression is exactly
100521 ** TODO: Issue a warning if the table primary key is used as part of the
100666 ** ON CONFLICT clauses this is an error. Otherwise, use the
100704 /* If this is the initial CREATE INDEX statement (or CREATE TABLE if the
100705 ** index is an implied index for a UNIQUE or PRIMARY KEY constraint) then
100709 ** table to parse the schema, or if this index is the PRIMARY KEY index
100712 ** If pTblName==0 it means this index is generated as an implied PRIMARY KEY
100729 ** Index.tnum. This is required in case this index is actually a
100730 ** PRIMARY KEY and the table is actually a WITHOUT ROWID table. In
100779 ** OE_Ignore. This is necessary for the correct constraint check
100812 ** aiRowEst[0] is supposed to contain the number of elements in the index.
100813 ** Since we do not know, guess 1 million. aiRowEst[1] is an estimate of the
100815 ** first column of the index. aiRowEst[2] is an estimate of the number
100840 /* Estimate that a[1] is 10, a[2] is 9, a[3] is 8, a[4] is 7, a[5] is
100841 ** 6 and each subsequent value (if any) is 5. */
100920 ** pArray is a pointer to an array of objects. Each object in the
100921 ** array is szEntry bytes in size. This routine uses sqlite3DbRealloc()
100922 ** to extend the array so that there is space for a new object at the end.
100924 ** When this function is called, *pnEntry contains the current size of
100925 ** the array (in entries - so the allocation is ((*pnEntry) * szEntry) bytes
100928 ** If the realloc() is successful (i.e. if no OOM condition occurs), the
100929 ** space allocated for the new object is zeroed, *pnEntry updated to
100931 ** returned. *pIdx is set to the index of the new array entry in this case.
100933 ** Otherwise, if the realloc() fails, *pIdx is set to -1, *pnEntry remains
100965 ** A new IdList is returned, or NULL if malloc() fails.
101016 ** creating nExtra new slots beginning at iStart. iStart is zero based.
101030 ** If a memory allocation fails the SrcList is unchanged. The
101083 ** need be. A new entry is created in the SrcList even if pTable is NULL.
101085 ** A SrcList is returned, or NULL if there is an OOM error. The returned
101088 ** that is input to this routine is automatically freed.
101090 ** If pDatabase is not null, it means that the table has an optional
101093 ** The SrcList.a[].zName field is filled with the table name which might
101094 ** come from pTable (if pDatabase is NULL) or from pDatabase.
101095 ** SrcList.a[].zDatabase is filled with the database name from pTable,
101096 ** or with NULL if no database is specified.
101102 ** Then B is a table name and the database name is unspecified. If called
101107 ** Then C is the table name and B is the database name. If C is defined
101108 ** then so is B. In other words, we never have a case where:
101189 ** This routine is called by the parser to add a new term to the
101190 ** end of a growing FROM clause. The "p" parameter is the part of
101191 ** the FROM clause that has already been constructed. "p" is NULL
101192 ** if this is the first term of the FROM clause. pTable and pDatabase
101194 ** pDatabase is NULL if the database name qualifier is missing - the
101196 ** alias token. If the term is a subquery, then pSubquery is the
101201 ** Return a new SrcList which encodes is the FROM with the new
101217 sqlite3ErrorMsg(pParse, "a JOIN clause is required before %s",
101285 ** is initially attached to the left operand. But the code generator
101290 ** Example: Suppose the join is like this:
101294 ** The operator is "natural cross join". The A and B operands are stored
101368 ** This function is called by the parser when it parses a command to create,
101388 ** Make sure the TEMP database is open and available for use. Return
101444 ** If argument zDb is NULL, then call sqlite3CodeVerifySchema() for each
101464 ** is set if the setStatement parameter is true. A checkpoint should
101468 ** can be checked before any changes are made to the database, it is never
101491 ** The code generator calls this routine if is discovers that it is
101494 ** sure that the statement is protected by a statement transaction.
101497 ** isMultiWrite flag was previously set. There is a time dependency
101501 ** makes it more difficult to prove that the code is correct (in
101514 ** and/or current transaction is rolled back.
101718 ** Return a KeyInfo structure that is appropriate for the given Index.
101752 ** This routine is invoked once per CTE by the parser while parsing a
101766 /* Check that the CTE name is unique within this WITH clause. If
101825 ** a legal notice, here is a blessing:
101866 ** This routine is called if the collation factory fails to deliver a
101889 ** This function is responsible for invoking the collation factory callback
101891 ** requested collation sequence is not available in the desired encoding.
101893 ** If it is not NULL, then pColl must point to the database native encoding
101896 ** The return value is either the collation sequence to be used in database
101898 ** sequence can be found. If no collation is found, leave an error message.
101916 /* No collation sequence of this type for this encoding is registered.
101933 ** This routine is called on a collation sequence before it is used to
101934 ** check that it is defined. An undefined collation sequence exists when
101935 ** a database is loaded that contains references to collation sequences
101941 ** from the main database is substituted, if one is available.
101960 ** specified by zName and nName is not found and parameter 'create' is
101964 ** array of three CollSeq structures. The first is the collation sequence
101967 ** Stored immediately after the three collation sequences is a copy of
101968 ** the collation sequence name. A pointer to this string is stored in
102014 ** If the entry specified is not found and 'create' is true, then create a
102017 ** A separate function sqlite3LocateCollSeq() is a wrapper around
102043 ** is called to test how well the function passed as the first argument
102046 ** request is matched. A higher value indicates a better match.
102048 ** If nArg is -1 that means to only return a match (non-zero) if p->nArg
102049 ** is also -1. In other words, we are searching for a function that
102052 ** If nArg is -2 that means that we are searching for any function
102056 ** The returned value is always between 0 and 6, as follows:
102066 ** If nArg==(-2) then any function with a non-null xSFunc is
102067 ** a perfect match and any function with xSFunc NULL is
102078 /* nArg of -2 is a special case */
102104 ** a pointer to the matching FuncDef if found, or 0 if there is no match.
102153 ** If the createFlag argument is true, then a new (blank) FuncDef
102154 ** structure is created and liked into the "db" structure if a
102157 ** If nArg is -2, then the first valid function found is returned. A
102158 ** function is valid if xSFunc is non-zero. The nArg==(-2)
102159 ** case is used to see if zName is a valid function name for some number
102160 ** of arguments. If nArg is -2, then createFlag must be 0.
102162 ** If createFlag is false, then a function with the required name and
102195 /* If no match is found, search the built-in functions.
102197 ** If the SQLITE_PreferBuiltin flag is set, then search the built-in
102201 ** Except, if createFlag is true, that means that we are trying to
102202 ** install a new function. Whatever FuncDef structure is returned it will
102221 /* If the createFlag parameter is true and the search did not reveal an
102254 ** The Schema.cache_size variable is not cleared.
102313 ** a legal notice, here is a blessing:
102331 ** name is not found or if any other error occurs.
102336 ** pSrc->a[0].pIndex Pointer to the INDEXED BY index, if there is one
102356 ** Check to make sure the given table is writable. If it is not
102357 ** writable, generate an error message and return 1. If it is
102361 /* A table is not writable under the following circumstances:
102363 ** 1) It is a virtual table and no implementation of the xUpdate method
102365 ** 2) It is a system table (i.e. sqlite_master), this call is not
102383 sqlite3ErrorMsg(pParse,"cannot modify %s because it is a view",pTab->zName);
102394 ** pWhere argument is an optional WHERE clause that restricts the
102458 ** is a limit/offset term to enforce.
102461 /* if pLimit is null, pOffset will always be null as well. */
102480 /* duplicate the FROM clause as it is needed by both the DELETE/UPDATE tree
102539 u8 *aToOpen = 0; /* Open cursor iTabCur+j if aToOpen[j] is true */
102574 ** deleted from is a view
102589 /* If pTab is really a view, make sure it has been initialized.
102660 ** It is easier just to erase the whole table. Prior to version 3.6.5,
102740 /* For ONEPASS, no need to store the rowid/primary-key. There is only
102769 /* If this DELETE cannot use the ONEPASS strategy, this is the
102777 /* Unless this is a view, open cursors for the table we are
102778 ** deleting from and all its indices. If this is a view, then the
102779 ** only effect this statement has is to fire the INSTEAD OF
102868 /* Return the number of rows that were deleted. If this routine is
102902 ** 1. iDataCur is an open cursor on the btree that is the canonical data
102912 ** that a search record formed from OP_MakeRecord is contained in the
102917 ** ONEPASS_MULTI. If eMode is not ONEPASS_OFF, then the cursor
102918 ** iDataCur already points to the row to delete. If eMode is ONEPASS_OFF
102922 ** If eMode is ONEPASS_MULTI, then this call is being made as part
102924 ** iIdxNoSeek is a valid cursor number (>=0), then its position should
102925 ** be preserved following the delete operation. Or, if iIdxNoSeek is not
102930 ** If iIdxNoSeek is a valid cursor number (>=0), then it identifies an
102938 int iDataCur, /* Cursor from which column data is extracted */
102952 /* Vdbe is guaranteed to have been allocated by this stage. */
103018 /* Delete the index and table entries. Skip this step if pTab is really
103019 ** a view (in which case the only effect of the DELETE statement is to
103022 ** If variable 'count' is non-zero, then this OP_Delete instruction should
103024 ** be invoked unless table pTab is a system table. The difference is that
103025 ** the update-hook is not invoked for rows removed by REPLACE, but the
103026 ** pre-update-hook is.
103073 ** index is the 0-th index.)
103076 ** that is to be deleted.
103113 ** regOut. The key with be for index pIdx which is an index on pTab.
103114 ** iCur is the index of a cursor open on the pTab table and pointing to
103115 ** the entry that needs indexing. If pTab is a WITHOUT ROWID table, then
103118 ** Return a register number which is the first in a block of
103123 ** If *piPartIdxLabel is not NULL, fill it in with a label and jump
103124 ** to that label if pIdx is a partial index that should be skipped.
103127 ** to false or null. If pIdx is not a partial index, *piPartIdxLabel
103128 ** will be set to zero which is an empty label that is ignored by
103132 ** avoid unnecessary register loads. If pPrior is not NULL, then it is
103134 ** computed into register regPrior. If the current pIdx index is generating
103137 ** holds the correct value and the loading of that register is skipped.
103138 ** This optimization is helpful when doing a DELETE or an INTEGRITY_CHECK
103180 /* If the column affinity is REAL but the number is an integer, then it
103185 ** opcode if it is present */
103213 ** a legal notice, here is a blessing:
103351 /* IMP: R-31676-45509 If X is the integer -9223372036854775808
103352 ** then abs(X) throws an integer overflow error since there is no
103363 /* IMP: R-37434-19929 Abs(X) returns NULL if X is NULL. */
103368 /* Because sqlite3_value_double() returns 0.0 if the argument is not
103370 ** IMP: R-01992-00519 Abs(X) returns 0.0 if X is a string or blob
103388 ** If both haystack and needle are BLOBs, then the result is one more than
103462 ** p1 is 1-indexed. So substr(x,1,1) returns the first character
103463 ** of x. If x is text, then we actually count UTF-8 characters.
103464 ** If x is a blob, then we count bytes.
103466 ** If p1 is negative, then we begin abs(p1) from the end of x[].
103468 ** If p2 is negative, return the p2 characters preceding p1.
103506 /* If SUBSTR_COMPATIBILITY is defined then substr(X,0,N) work the same as
103508 ** is essentially a back-out of the bug-fix in check-in [5fc125d362df4b8]
103603 ** If nByte is larger than the maximum string or blob length, then
103672 ** is. We might as well use the "version()" function as a substitute.
103691 ** in a way that is testable, mask the sign bit off of negative
103703 ** that is N bytes long.
103727 ** value is the same as the sqlite3_last_insert_rowid() API function.
103736 /* IMP: R-51513-12026 The last_insert_rowid() SQL function is a
103745 ** IMP: R-62073-11209 The changes() SQL function is a wrapper
103760 ** Implementation of the total_changes() SQL function. The return value is
103770 /* IMP: R-52756-41993 This function is a wrapper around the
103787 ** character is exactly one byte in size. Also, provde the Utf8Read()
103789 ** the next character is ASCII.
103799 /* The correct SQL-92 behavior is for the LIKE operator to ignore
103802 /* If SQLITE_CASE_SENSITIVE_LIKE is defined, then the LIKE operator
103803 ** is case sensitive causing 'a' LIKE 'A' to be false */
103834 ** Ec Where E is the "esc" character and c is any other
103839 ** This routine is usually quick, but can be N**2 in the worst case.
103871 ** recursive search in this case, but it is an unusual case. */
103872 assert( matchOther<0x80 ); /* '[' is a single-byte character */
103975 ** Count the number of times that the LIKE operator (or GLOB which is
103976 ** just a variation of LIKE) gets called. This is used for testing
103986 ** the build-in LIKE operator. The first argument to the function is the
103987 ** pattern and the second argument is the string. So, the SQL statements:
103991 ** is implemented as like(B,A).
104057 ** Implementation of the NULLIF(x,y) function. The result is the first
104058 ** argument if the arguments are different. The result is NULL if the
104074 ** Implementation of the sqlite_version() function. The result is the version
104075 ** of the SQLite library that is running.
104083 /* IMP: R-48699-48617 This function is an SQL wrapper around the
104089 ** Implementation of the sqlite_source_id() function. The result is a string
104099 /* IMP: R-24470-31136 This function is an SQL wrapper around the
104105 ** Implementation of the sqlite_log() function. This is a wrapper around
104106 ** sqlite3_log(). The return value is NULL. The function exists purely for
104121 ** The result is an integer that identifies if the compiler option
104134 ** function is a wrapper around the sqlite3_compileoption_used() C/C++
104145 ** The result is a string that identifies the compiler options
104158 ** is a wrapper around the sqlite3_compileoption_get() C/C++ function.
104174 ** argument. If the argument is numeric, the return value is the same as
104175 ** the argument. If the argument is NULL, the return value is the string
104176 ** "NULL". Otherwise, the argument is enclosed in single quotes with
104266 ** The char() function takes zero or more arguments, each of which is
104268 ** is the unicode character for the corresponding integer argument.
104358 ** them A, B, and C. The result is also a string which is derived
104444 ** The userdata is 0x1 for left trim, 0x2 for right trim, 0x3 for both.
104529 ** The "unknown" function is automatically substituted in place of
104531 ** when the SQLITE_ENABLE_UNKNOWN_FUNCTION compile-time option is used.
104532 ** When the "sqlite3" command-line shell is built using this functionality,
104547 /* IMP: R-25361-16150 This function is omitted from SQLite by default. It
104548 ** is only available if the SQLITE_SOUNDEX compile-time option is used
104549 ** when SQLite is built.
104555 ** IMP: R-59782-00072 The soundex(X) function returns a string that is the
104600 /* IMP: R-64894-50321 The string "?000" is returned if the argument
104601 ** is NULL or contains no ASCII alphabetic characters. */
104618 ** flag is set. See the sqlite3_enable_load_extension() API.
104729 /* The sqlite3_aggregate_count() function is deprecated. But just to make
104764 /* This step function is used for both the min() and max() aggregates,
104766 ** comparison is inverted. For the max() aggregate, the
104768 ** returns (void *)db, where db is the sqlite3* database pointer.
104871 ** parameter determines whether or not the LIKE operator is case
104872 ** sensitive. GLOB is always case sensitive.
104892 ** it is appropriate to apply the LIKE optimization to that function
104894 ** return TRUE. If the function is not a LIKE-style function then
104897 ** *pIsNocase is set to true if uppercase and lowercase are equivalent for
104899 ** between uppercase and lowercase (as does GLOB) then *pIsNocase is set to
104942 ** are read-only after initialization is complete.
105062 ** a legal notice, here is a blessing:
105082 ** If an immediate foreign key constraint is violated,
105083 ** SQLITE_CONSTRAINT_FOREIGNKEY is returned and the current
105085 ** deferred foreign key constraint is violated, no action is taken
105090 ** with the database handle. The counter is set to zero each time a
105091 ** database transaction is opened. Each time a statement is executed
105092 ** that causes a foreign key violation, the counter is incremented. Each
105093 ** time a statement is executed that removes an existing violation from
105094 ** the database, the counter is decremented. When the transaction is
105095 ** committed, the commit fails if the current value of the counter is
105099 ** there is no way to tell which foreign constraint is not satisfied,
105100 ** or which row it is not satisfied for.
105103 ** transaction is opened, this may cause the mechanism to malfunction.
105105 ** Despite these problems, this approach is adopted as it seems simpler
105110 ** I.1) For each FK for which the table is the child table, search
105111 ** the parent table for a match. If none is found increment the
105114 ** I.2) For each FK for which the table is the parent table,
105117 ** found (as the constraint is now satisfied).
105121 ** D.1) For each FK for which the table is the child table,
105123 ** deleted row in the child table. If such a row is not found,
105126 ** D.2) For each FK for which the table is the parent table, search
105140 ** resolution is considered to delete rows before the new row is inserted.
105142 ** is thrown, even if the FK constraint would be satisfied after the new
105143 ** row is inserted.
105146 ** is that the counter used is stored as part of each individual statement
105148 ** constraint counter is greater than zero,
105150 ** and the statement transaction is rolled back. An exception is an INSERT
105152 ** instead of using a counter, an exception is thrown immediately if the
105153 ** INSERT violates a foreign key constraint. This is necessary as such
105168 ** accessed). No information is required by the code-generator before
105172 ** sqlite3FkRequired() - Test to see if FK processing is required.
105204 ** Given that pParent is the parent table for foreign key constraint pFKey,
105207 ** If successful, zero is returned. If the parent key is an INTEGER PRIMARY
105208 ** KEY column, then output variable *ppIdx is set to NULL. Otherwise, *ppIdx
105209 ** is set to point to the unique index.
105212 ** is not a composite foreign key), output variable *paiCol is set to NULL.
105213 ** Otherwise, it is set to point to an allocated array of size N, where
105214 ** N is the number of columns in the parent key. The first element of the
105215 ** array is the index of the child table column that is mapped by the FK
105217 ** of index *ppIdx. The second element of the array is the index of the
105237 ** then non-zero is returned, and a "foreign key mismatch" error loaded
105238 ** into pParse. If an OOM error occurs, non-zero is returned and the
105239 ** pParse->db->mallocFailed flag is set.
105253 /* The caller is responsible for zeroing output parameters. */
105258 /* If this is a non-composite (single column) foreign key, check if it
105269 ** 1) There is an INTEGER PRIMARY KEY column and the FK is implicitly
105271 ** 2) The FK is explicitly mapped to a column declared as INTEGER
105287 /* pIdx is a UNIQUE index (or a PRIMARY KEY) and has the right number
105289 ** column of pFKey, then this index is a winner. */
105292 /* If zKey is NULL, then this foreign key is implicitly mapped to
105303 /* If zKey is non-NULL, then this foreign key was declared to
105315 /* If the index uses a collation sequence that is different from
105316 ** the default collation sequence for the column, this index is
105331 if( i==nCol ) break; /* pIdx is usable */
105351 ** This function is called when a row is inserted into or deleted from the
105352 ** child table of foreign key constraint pFKey. If an SQL UPDATE is executed
105353 ** on the child table of pFKey, this function is invoked twice for each row
105357 ** Each time it is called, this function generates VDBE code to locate the
105360 ** special action is taken. Otherwise, if the parent row can *not* be
105392 /* If nIncr is less than zero, then check at runtime if there are any
105393 ** outstanding constraints to resolve. If there are not, there is no need
105397 ** any are, then the constraint is considered satisfied. No need to
105410 /* If pIdx is NULL, then the parent key is the INTEGER PRIMARY KEY
105417 ** is no matching parent key. Before using MustBeInt, make a copy of
105424 /* If the parent table is the same as the child table, and we are about
105425 ** to increment the constraint-counter (i.e. this is an INSERT operation),
105450 /* If the parent table is the same as the child table, and we are about
105451 ** to increment the constraint-counter (i.e. this is an INSERT operation),
105457 ** of the parent-key values are NULL (at this point it is known that
105468 /* The parent key is a composite key that includes the IPK column */
105490 /* Special case: If this is an INSERT statement that will insert exactly
105492 ** incrementing a counter. This is necessary as the VM code is being
105513 ** regBase is the first of an array of register that contains the data
105519 Table *pTab, /* The table whose content is at r[regBase]... */
105521 i16 iCol /* Which column of pTab is desired */
105551 Table *pTab, /* The table whose column is desired */
105553 i16 iCol /* The column that is wanted */
105565 ** This function is called to generate code executed when a row is deleted
105566 ** from the parent table of foreign key constraint pFKey and, if pFKey is
105567 ** deferred, when a row is inserted into the same table. When generating
105571 ** Parameter nIncr is passed -1 when inserting a row (as this may decrease
105577 ** For each child row found, one of the following actions is taken:
105582 ** Or, if the ON (UPDATE|DELETE) action is RESTRICT,
105588 ** Or, if the ON (UPDATE|DELETE) action is RESTRICT,
105649 /* If the child table is the same as the parent table, then add terms
105656 ** The first form is used for rowid tables. The second form is used
105657 ** for WITHOUT ROWID tables. In the second form, the primary key is
105718 ** NULL pointer (as there are no FK constraints for which t2 is the parent
105726 ** The second argument is a Trigger structure allocated by the
105745 ** This function is called to generate code that runs when table pTab is
105750 ** Normally, no code is required. However, if either
105752 ** (a) The table is the parent table of a FK constraint, or
105753 ** (b) The table is the child table of a deferred FK constraint and it is
105757 ** then the equivalent of "DELETE FROM <tbl>" is executed before dropping
105770 ** is the child table. If one cannot be found, return without
105773 ** when this statement is run. */
105789 ** any modifications to the schema are made. This is because statement
105792 ** If the SQLITE_DeferFKs flag is set, then this is not required, as
105812 ** for which pTab is the child table. An UPDATE statement against pTab
105813 ** is currently being processed. For each column of the table that is
105815 ** is zero or greater (if a column is unmodified the corresponding element
105816 ** is set to -1). If the rowid column is modified by the UPDATE statement
105817 ** the bChngRowid argument is non-zero.
105824 FKey *p, /* Foreign key for which pTab is the child */
105826 int bChngRowid /* True if rowid is modified by this update */
105839 ** for which pTab is the parent table. An UPDATE statement against pTab
105840 ** is currently being processed. For each column of the table that is
105842 ** is zero or greater (if a column is unmodified the corresponding element
105843 ** is set to -1). If the rowid column is modified by the UPDATE statement
105844 ** the bChngRowid argument is non-zero.
105874 ** Return true if the parser passed as the first argument is being
105875 ** used to code a trigger that is really a "SET NULL" action belonging
105892 ** This function is called when inserting, deleting or updating a row of
105896 ** For a DELETE operation, parameter regOld is passed the index of the
105899 ** of the row being deleted, from left to right. Parameter regNew is passed
105902 ** For an INSERT operation, regOld is passed zero and regNew is passed the
105906 ** For an UPDATE operation, this function is called twice. Once before
105907 ** the original record is deleted from the table using the calling convention
105908 ** described for DELETE. Then again after the original record is deleted
105909 ** but before the new record is inserted using the INSERT convention.
105913 Table *pTab, /* Row is being deleted from this table */
105914 int regOld, /* Previous row data is stored here */
105915 int regNew, /* New row data is stored here */
105917 int bChngRowid /* True if rowid is UPDATEd */
105928 /* If foreign-keys are disabled, this function is a no-op. */
105934 /* Loop through all the foreign key constraints for which pTab is the
105935 ** child table (the table that the foreign key definition is part of). */
105965 /* If isIgnoreErrors is true, then a table is being dropped. In this
105968 ** If the parent table of an FK constraint on the current table is
105969 ** missing, behave as if it is empty. i.e. decrement the relevant
106015 /* A row is being removed from the child table. Search for the parent.
106021 /* A row is being added to the child table. If a parent row cannot
106024 ** If this operation is being performed as part of a trigger program
106025 ** that is actually a "SET NULL" action belonging to this very
106027 ** values are guaranteed to be NULL, it is not possible for adding
106077 /* If this is a deferred FK constraint, or a CASCADE or SET NULL
106082 ** Note 1: If the FK is declared "ON UPDATE CASCADE", then the
106084 ** (when this function is called as part of processing the UPDATE
106108 ** This function is called before generating code to update or delete a
106138 ** This function is called before generating code to update or delete a
106139 ** row contained in table pTab. If the operation is a DELETE, then
106140 ** parameter aChange is passed a NULL value. For an UPDATE, aChange points
106141 ** to an array of size N, where N is the number of columns in table pTab.
106142 ** If the i'th column is not modified by the UPDATE, then the corresponding
106143 ** entry in the aChange[] array is set to -1. If the column is modified,
106144 ** the value is 0 or greater. Parameter chngRowid is set to true if the
106148 ** true. If there is no foreign key related processing, this function
106159 /* A DELETE operation. Foreign key processing is required if the
106160 ** table in question is either the child or parent table for any
106164 /* This is an UPDATE. Foreign key processing is only required if the
106183 ** This function is called when an UPDATE or DELETE operation is being
106184 ** compiled on table pTab, which is the parent table of foreign-key pFKey.
106185 ** If the current operation is an UPDATE, then the pChanges parameter is
106186 ** passed a pointer to the list of columns being modified. If it is a
106187 ** DELETE, pChanges is passed a NULL pointer.
106191 ** If the action is "NO ACTION" or "RESTRICT", then a NULL pointer is
106193 ** sub-system, code for them is created by fkScanChildren()).
106195 ** For example, if pFKey is the foreign key and pTab is table "p" in
106201 ** then the returned trigger structure is equivalent to:
106207 ** The returned pointer is cached as part of the foreign key object. It
106208 ** is eventually freed along with the rest of the foreign key object by
106259 /* Create the expression "OLD.zToCol = zFromCol". It is important
106260 ** that the "OLD.zToCol" term is on the LHS of the = operator, so
106394 ** This function is called when deleting or updating a row to implement
106403 int bChngRowid /* True if rowid is UPDATEd */
106405 /* If foreign-key support is enabled, iterate through all FKs that
106406 ** refer to table pTab. If there is an action associated with the FK
106451 /* EV: R-30323-21917 Each foreign key constraint in SQLite is
106474 ** a legal notice, here is a blessing:
106492 ** If pTab is a WITHOUT ROWID table, then it is the PRIMARY KEY index
106493 ** for that table that is actually opened.
106534 ** An extra 'D' is appended to the end of the string to cover the
106538 ** is managed along with the rest of the Index structure. It will be
106539 ** released when sqlite3DeleteIndex() is called.
106543 /* The first time a column affinity string for a particular index is
106544 ** required, it is allocated and populated here. It is then stored as
106548 ** sqliteDeleteIndex() when the Index structure itself is cleaned
106583 ** If the affinity exists (if it is no entirely SQLITE_AFF_BLOB values) and
106630 ** have been opened at any point in the VDBE program. This is used to see if
106671 ** which is in database iDb. Return the register number for the register
106674 ** There is at most one AutoincInfo structure per table even if the
106675 ** same table is autoincremented multiple times due to inserts within
106676 ** triggers. A new AutoincInfo structure is created if this is the
106678 ** AutoincInfo structure is used.
106686 ** The 2nd register is the one that is returned. That is all the
106728 /* This routine is never called during trigger-generation. It is
106733 assert( v ); /* We failed long ago if this is not so */
106772 ** new rowid that is about to be inserted. If that new rowid is
106774 ** memory cell is updated.
106829 ** If SQLITE_OMIT_AUTOINCREMENT is defined, then the three routines
106847 ** This routine is called to handle SQL of the following forms:
106853 ** The IDLIST following the table name is always optional. If omitted,
106854 ** then a list of all (non-hidden) columns for the table is substituted.
106855 ** The IDLIST appears in the pColumn parameter. pColumn is NULL if IDLIST
106856 ** is omitted.
106859 ** first two forms shown above. A VALUES clause is really just short-hand
106861 ** that follows. If the pSelect parameter is NULL, that means that the
106862 ** DEFAULT VALUES form of the INSERT statement is intended.
106874 ** The three remaining templates assume the statement is of the form
106878 ** If the SELECT clause is of the restricted form "SELECT * FROM <table2>" -
106880 ** and there is no WHERE or LIMIT or GROUP BY or ORDER BY clauses, and
106883 ** is invoked that copies raw records from <table2> over to <table1>.
106885 ** template. This is the 2nd template.
106898 ** The 3rd template is for when the second template does not apply
106917 ** The 4th template is used if the insert statement takes its
106918 ** values from a SELECT but the data is being inserted into a table
106919 ** that is also read as part of the SELECT. In the third form,
106921 ** the select. The template is like this:
106958 int nHidden = 0; /* Number of hidden columns if TABLE is virtual */
106959 int iDataCur = 0; /* VDBE cursor that is the main data repository */
106961 int ipkColumn = -1; /* Column that is the INTEGER PRIMARY KEY */
106970 u8 appendFlag = 0; /* True if the insert is likely to be an append */
106972 u8 bIdListInOrder; /* True if IDLIST is in table order */
106996 /* If the Select object is really just a simple VALUES() list with a
107026 ** inserted into is a view
107042 /* If pTab is really a view, make sure it has been initialized.
107043 ** ViewGetColumnNames() is a no-op if pTab is not a view.
107063 /* If the statement is of the form
107070 ** This is the 2nd template.
107079 /* If this is an AUTOINCREMENT table, look up the sequence number in the
107100 ** is named in the IDLIST, then record in the ipkColumn variable
107101 ** the index into IDLIST of the primary key column. ipkColumn is
107103 ** is appears in the original table. (The index of the INTEGER
107104 ** PRIMARY KEY in the original table is pTab->iPKey.)
107137 ** is coming from a SELECT statement, then generate a co-routine that
107139 ** co-routine is the common header to the 3rd and 4th templates.
107142 /* Data is coming from a SELECT or from a multi-row VALUES clause.
107167 ** A temp table must be used if the table being updated is also one
107178 ** here is from the 4th template:
107204 /* This is the case if the data for the INSERT is coming from a
107222 /* If there is no IDLIST term but the table has an integer primary
107254 /* If this is not a view, open the table and and all indices */
107268 /* This is the top of the main insertion loop */
107270 /* This block codes the top of loop only. The complete loop is the
107282 /* This block codes the top of loop only. The complete loop is the
107300 /* build the NEW.* reference row. Note that if there is an INTEGER
107301 ** PRIMARY KEY into which a NULL is being inserted, that NULL will be
107314 assert( pSelect==0 ); /* Otherwise useTempTable is true */
107342 assert( pSelect==0 ); /* Otherwise useTempTable is true */
107348 /* If this is an INSERT on a view with an INSTEAD OF INSERT trigger,
107350 ** If this is a real table, attempt conversions as required by the
107389 /* If the PRIMARY KEY expression is NULL, then use OP_NewRowid
107419 /* The value of the INTEGER PRIMARY KEY column is always a NULL.
107420 ** Whenever this column is read, the rowid will be substituted
107488 ** is a SELECT statement.
107518 ** Return the number of rows inserted. If this routine is
107555 /* This is the Walker callback from checkConstraintUnchanged(). Set
107575 ** pExpr is a CHECK constraint on a row that is being UPDATE-ed. The
107577 ** aiChng[i]>=0, and also the ROWID is modified if chngRowid is true.
107580 ** changing columns (or the rowid if it is changing). In other words,
107606 ** The regNewData parameter is the first register in a range that contains
107614 ** The regOldData parameter is similar to regNewData except that it contains
107615 ** the data prior to an UPDATE rather than afterwards. regOldData is zero
107619 ** For an UPDATE, the pkChng boolean is true if the true primary key (the
107621 ** might be modified by the UPDATE. If pkChng is false, then the key of
107622 ** the iDataCur content table is guaranteed to be unchanged by the UPDATE.
107626 ** is zero, it means that the either rowid is computed automatically or
107627 ** that the table is a WITHOUT ROWID table and has no rowid. On an INSERT,
107632 ** registers identified by aRegIdx[]. No index entry is created for
107633 ** indices where aRegIdx[i]==0. The order of indices in aRegIdx[] is
107638 ** table and all applicable indices (that is to say, all indices for which
107639 ** aRegIdx[] is not zero). iDataCur is the cursor for the main table when
107641 ** index when operating on a WITHOUT ROWID table. iIdxCur is the cursor
107647 ** then the appropriate action is performed. There are five possible
107652 ** any ROLLBACK The current transaction is rolled back and
107663 ** transaction is not rolled back and any
107667 ** row is skipped, without throwing an error.
107669 ** (There is an immediate jump to ignoreDest.)
107671 ** NOT NULL REPLACE The NULL value is replace by the default
107673 ** is NULL, the action is the same as ABORT.
107676 ** being inserted is removed.
107680 ** Which action to take is determined by the overrideError parameter.
107682 ** is used. Or if pParse->onError==OE_Default then the onError value
107683 ** for the constraint is used.
107697 int *aiChng /* column i is unchanged if aiChng[i]<0 */
107708 int seenReplace = 0; /* True if REPLACE is used to resolve INT PK conflict */
107712 u8 isUpdate; /* True if this is an UPDATE operation */
107720 assert( pTab->pSelect==0 ); /* This table is not a VIEW */
107723 /* pPk is the PRIMARY KEY index for WITHOUT ROWID tables and NULL for
107724 ** normal rowid tables. nPkField is the number of key fields in the
107725 ** pPk index or 1 for a rowid table. In other words, nPkField is the
107743 continue; /* ROWID is never NULL */
107750 if( onError==OE_None ) continue; /* This column is allowed to be NULL */
107819 /* If rowid is changing, make sure the new rowid does not previously
107836 ** is unchanged. */
107842 /* If the response to a rowid conflict is REPLACE but the response
107843 ** to some other UNIQUE constraint is FAIL or IGNORE, then we need
107875 ** recursive-triggers flag is set, call GenerateRowDelete() to
107880 ** flag is not set, but the table has one or more indexes, call
107883 ** when it is inserted.
107885 ** If either GenerateRowDelete() or GenerateRowIndexDelete() is called,
107887 ** statement rollback (if the statement is aborted after the delete
107908 ** not modify the b-tree. It is more efficient to let the coming
107909 ** OP_Insert replace the existing entry than it is to delete the
107947 int addrUniqueOk; /* Jump here if the UNIQUE constraint is satisfied */
107957 /* Skip partial indices for which the WHERE clause is not true */
107994 /* In an UPDATE operation, if this index is the PRIMARY KEY index
107996 ** primary key, then no collision is possible. The collision detection
108003 /* Find out what action to take in case there is a uniqueness conflict */
108008 continue; /* pIdx is not a UNIQUE index */
108026 ** is different from old-rowid */
108076 /* Generate code that executes if the new index entry is not unique */
108134 int appendBias, /* True if this is likely to be an append */
108147 assert( pTab->pSelect==0 ); /* This table is not a VIEW */
108195 ** ROWID table) is returned in *piDataCur. The first index cursor is
108196 ** returned in *piIdxCur. The number of indices is returned.
108199 ** or the first index for WITHOUT ROWID tables) if it is non-negative.
108200 ** If iBase is negative, then allocate the next available cursor.
108207 ** If pTab is a virtual table, then this routine is a no-op and the
108215 int iBase, /* Use this for the table cursor, if there is one */
108229 /* This routine is a no-op for virtual tables. Leave the output
108267 ** The following global variable is incremented whenever the
108268 ** transfer optimization is used. This is used for testing
108270 ** is happening when it is supposed to.
108278 ** Check to see if index pSrc is compatible as a source of data
108282 ** * The index is over the same set of columns
108333 ** The xfer optimization is only attempted if tab1 and tab2 are compatible.
108337 ** This routine returns TRUE if the optimization is guaranteed to be used.
108339 ** is empty - a factor that can only be determined at run-time. In that
108341 ** does a test to see if the destination table is empty and jumps over the
108345 ** is no chance that the xfer optimization can be applied.
108347 ** This optimization is particularly useful at making VACUUM run faster.
108393 assert(pSelect->pSrc); /* allocated even if there is no FROM clause */
108406 /* Do not need to test for a HAVING clause. If HAVING is present but
108407 ** there is no ORDER BY, we will get an error. */
108431 /* At this point we have established that the statement is of the
108477 return 0; /* tab2 must be NOT NULL if tab1 is */
108509 ** any foreign key constraints. This is more restrictive than necessary.
108510 ** But the main beneficiary of the transfer optimization is the VACUUM
108512 ** the extra complication to make this rule less restrictive is probably
108523 /* If we get this far, it means that the xfer optimization is at
108525 ** table (tab1) is initially empty.
108546 ** only if the destination table is initially empty. Unless the
108547 ** SQLITE_Vacuum flag is set, this block generates code to make
108548 ** that determination. If SQLITE_Vacuum is set, then the destination
108549 ** table is always empty.
108553 ** (1) There is no INTEGER PRIMARY KEY but there are indices.
108554 ** (If the destination is not initially empty, the rowid fields
108558 ** is unable to test uniqueness.)
108560 ** (3) onError is something other than OE_Abort and OE_Rollback.
108609 /* This INSERT command is part of a VACUUM operation, which guarantees
108610 ** that the destination table is empty. If all indexed columns use
108614 ** of every OP_IdxInsert opcode, an OP_Last is added before the
108616 ** should be inserted. This is faster.
108619 ** BINARY, this optimization is disabled. This is because the user
108664 ** a legal notice, here is a blessing:
108684 ** If the SQL is a query, then for each row in the query result
108685 ** the xCallback() function is called. pArg becomes the first
108687 ** is invoked, even for queries.
108700 int callbackIsInit; /* True if callback data is initialized */
108742 ** strings so there is no way for sqlite3_column_name() to fail. */
108811 ** a legal notice, here is a blessing:
108831 ** a legal notice, here is a blessing:
109114 ** This is the function signature used for all extension entry points. It
109115 ** is also defined in the file "loadext.c".
109127 ** This header file is also used by the loadext.c source file
109132 ** SQLITE_CORE macros is undefined.
109372 /* This case when the file really is being compiled as a loadable
109379 /* This case when the file is being statically linked into the
109489 ** A pointer to this structure is passed into extensions when they are
109498 ** intend to use is supported by the library. Extensions should
109499 ** also check to make sure that the pointer to the function is
109574 0, /* Was sqlite3_global_recover(), but that function is deprecated */
109636 ** of the APIs above provided that the pointer is not NULL. But
109639 ** a library that is new enough to support that API.
109800 ** zFile. The entry point is zProc. zProc may be 0 in which case a
109801 ** default entry point name (sqlite3_extension_init) is used. Use
109802 ** of the default name is recommended.
109806 ** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with
109843 ** ability to run load_extension is turned off by default. One
109881 ** construct an entry point name "sqlite3_X_init" where the X is
109966 ** Call this routine when the database connection is closing in order
109979 ** Enable or disable extension loading. Extension loading is disabled by
109997 ** loading is supported. We need a dummy sqlite3Apis pointer for that
109998 ** code if regular extension loading is not available. This is that
110010 ** This list is shared across threads. The SQLITE_MUTEX_STATIC_MASTER
110020 ** state vector. If writable static data is unsupported on the target,
110022 ** case where writable static data is supported, wsdStat can refer directly
110036 ** Register a statically linked extension that is automatically
110079 ** set of routines that is invoked for each new database connection, if it
110080 ** is currently on the list. If xInit is not on the list, then this
110081 ** routine is a no-op.
110173 ** a legal notice, here is a blessing:
110193 ** The "pragma.h" include file is an automatically generated file that
110195 ** object. This ensures that the aPragmaName[] table is arranged in
110202 ** This file is automatically generated by the script at
110672 ** unrecognized string argument. The FULL and EXTRA option is disallowed
110676 ** should be passed into sqlite3BtreeSetSafetyLevel(). The is done
110709 /* The sqlite3GetBoolean() function is used by other modules but the
110710 ** remainder of this file is specific to PRAGMA processing. So omit
110764 ** Invalidate temp storage, either when the temp storage is changed
110785 ** If the TEMP database is open, close it and mark the database schema
110923 ** The identifier might also be a string. The value is a string, and
110924 ** identifier, or a number. If minusFlag is true, then the value is
110927 ** If the left side is "database.id" then pId1 is the database name
110928 ** and pId2 is the id. If the left side is just "id" then pId1 is the
110929 ** id and pId2 is any empty string.
110955 /* Interpret the [schema.] part of the pragma statement. iDb is the
110956 ** index of the database this pragma is being applied to in db.aDb[]. */
110962 ** pragma, make sure it is open.
110986 ** IMPLEMENTATION-OF: R-12238-55120 Whenever a PRAGMA statement is parsed,
110987 ** an SQLITE_FCNTL_PRAGMA file control is sent to the open sqlite3_file
110992 ** file control is an array of pointers to strings (char**) in which the
110993 ** second element of the array is the name of the pragma and the third
110994 ** element is the argument to the pragma or NULL if the pragma has no
111034 /* Make sure the database schema is loaded if the pragma requires that */
111048 ** page cache size. The value returned is the maximum number of
111055 ** is always on by default regardless of the sign of the default cache
111112 /* Malloc may fail when setting the page-size, as there is an internal
111158 ** The absolute value of N is used. This is undocumented and might
111159 ** change. The only purpose is to provide an easy way to test
111191 /* Simple "PRAGMA locking_mode;" statement. This is a query for
111203 ** Also, the sqlite3.dfltLockMode variable is set so that
111239 /* If there is no "=MODE" part of the pragma, do a query for the
111294 ** The value is one of: 0 NONE 1 FULL 2 INCREMENTAL
111307 ** incr-vacuum flags. This is required in case this connection
111308 ** creates the database file. It is important that it is created
111316 ** that this really is an auto-vacuum capable database.
111372 ** page cache size value. If N is positive then that is the
111373 ** number of pages in the cache. If N is negative, then the
111374 ** number of pages is adjusted so that the cache uses -N kibibytes
111396 ** or off. When turnning cache spill on, the size is set to the
111399 ** If N is positive then that is the
111400 ** number of pages in the cache. If N is negative, then the
111401 ** number of pages is adjusted so that the cache uses -N kibibytes
111404 ** If the number of cache_spill pages is less then the number of
111435 ** Used to set mapping size limit. The mapping size limit is
111437 ** database file. If this parameter is set to zero, then memory mapping
111438 ** is not used at all. If N is negative, then the default memory map
111439 ** limit determined by sqlite3_config(SQLITE_CONFIG_MMAP_SIZE) is set.
111440 ** The parameter N is measured in bytes.
111442 ** This value is advisory. The underlying VFS is free to memory map
111443 ** as little or as much as it wants. Except, if N is set to 0 then the
111482 ** value will be restored the next time the database is opened.
111484 ** Note that it is possible for the library compile-time options to
111503 ** If temporary directory is changed, then invalidateTempStorage.
111618 ** default value will be restored the next time the database is
111686 ** notnull: True if 'NOT NULL' is part of column declaration
111848 sqlite3VdbeMultiLoad(v, 1, "is", i++, pColl->zName);
111910 int addrOk; /* Jump here if the key is OK */
112034 /* Pragma "quick_check" is reduced version of
112044 ** then iDb is set to the index of the database identified by <db>.
112045 ** In this case, the integrity of database iDb only is verified by
112049 ** "PRAGMA quick_check"), then iDb is set to 0. In this case, set iDb
112199 ** current key. The entry is unique if (1) any column is NULL
112272 ** database. If the database is not initialized, it is initialized now.
112274 ** The second form of this pragma is a no-op if the main database file
112277 ** is created. If an existing main database file is opened, then the
112278 ** default text encoding for the existing database is used.
112283 ** is executed, this is done before the ATTACH operation.
112286 ** new database files created using this database handle. It is only
112312 /* Only change the value of sqlite.enc if the database handle is not
112314 ** will be overwritten when the schema is next loaded. If it does not
112357 ** The schema-cookie is usually only manipulated internally by SQLite. It
112358 ** is incremented by SQLite whenever the database schema is modified (by
112359 ** creating or dropping a table or index). The schema version is used by
112360 ** SQLite each time a query is executed to ensure that the internal cache
112362 ** the database against which the compiled query is actually executed.
112364 ** the schema-version is potentially dangerous and may lead to program
112367 ** The user-version is not used internally by SQLite. It may be used by
112479 ** connection on which it is invoked to free up as much memory as it
112492 ** if one is set. If no busy handler or a different busy handler is set
112493 ** then 0 is returned. Setting the busy_timeout to 0 or negative
112510 ** sqlite3_soft_heap_limit64() interface with the argument N, if N is
112511 ** specified and is a non-negative integer.
112634 ** a legal notice, here is a blessing:
112649 ** that the database is corrupt.
112669 ** This is the callback routine for the code that initializes the
112671 ** This routine is also called from the OP_ParseSchema opcode of the VDBE.
112700 ** But because db->init.busy is set to 1, no VDBE code is generated
112701 ** or executed. All the parser does is build the internal data
112732 /* If the SQL column is blank it means this is an index that
112736 ** to do here is record the root page number for that index.
112743 ** the permanent table is hidden by the TEMP table, we can also
112757 ** database file is given by iDb. iDb==0 is used for the main
112758 ** database. iDb==1 should never be used. iDb>=2 is used for
112810 /* If there is not already a read-only (or read-write) transaction opened
112811 ** on the b-tree database, open one now. If a transaction is opened, it
112847 ** For an attached db, it is an error if the encoding is not the same
112943 /* Black magic: If the SQLITE_RecoveryMode flag is set, then consider
112948 ** purpose of this is to allow access to the sqlite_master table
112978 ** After a database is initialized, the DB_SchemaLoaded bit is set
112979 ** bit is set in the flags field of the Db structure. If the database
112980 ** file was of zero-length, then the DB_Empty flag is also set.
113001 ** for the TEMP database. This is loaded last, as the TEMP database
113023 ** This routine is a no-op if the database schema is already initialized.
113024 ** Otherwise, the schema is loaded. An error code is returned.
113042 ** Check schema cookies in all databases. If any cookie is out
113055 int openedTransaction = 0; /* True if a transaction is opened */
113059 /* If there is not already a read-only (or read-write) transaction opened
113060 ** on the b-tree database, open one now. If a transaction is opened, it
113092 ** If the same database is attached more than once, the first
113093 ** attached database is returned.
113098 /* If pSchema is NULL, then return -1000000. This happens when code in
113099 ** expr.c is trying to resolve a reference to a transient table (i.e. one
113104 ** -1000000 as the incorrect index into db->aDb[] is much
113164 /* Check to verify that it is possible to get a read lock on all
113166 ** some other database connection is holding a write-lock, which in
113176 ** This thread is currently holding mutexes on all Btrees (because
113178 ** is not possible for another thread to start a new schema change
113179 ** while this routine is running. Hence, we do not need to hold
113180 ** locks on the schema, we just need to make sure nobody else is
113185 ** works even if READ_UNCOMMITTED is set.
113194 sqlite3ErrorWithMsg(db, rc, "database schema is locked: %s", zDb);
113330 ** If the statement is successfully recompiled, return SQLITE_OK. Otherwise,
113366 ** version, the original SQL text is not saved in the prepared statement
113367 ** and so if a schema change occurs, SQLITE_SCHEMA is returned by
113368 ** sqlite3_step(). In the new version, the original SQL text is retained
113369 ** and the statement is automatically recompiled if an schema change
113412 ** tricky bit is figuring out the pointer to return in *pzTail.
113454 ** version, the original SQL text is not saved in the prepared statement
113455 ** and so if a schema change occurs, SQLITE_SCHEMA is returned by
113456 ** sqlite3_step(). In the new version, the original SQL text is retained
113457 ** and the statement is automatically recompiled if an schema change
113493 ** a legal notice, here is a blessing:
113521 ** An instance of the following object is used to record information about
113527 u8 isTnct; /* True if the DISTINCT keyword is present */
113534 ** An instance of the following object is used to record information about
113535 ** the ORDER BY (or GROUP BY) clause of query is being coded.
113553 ** itself only if bFree is true.
113684 ** A full outer join is the combination of JT_LEFT and JT_RIGHT.
113686 ** If an illegal or unsupported join type is seen, then still return
113748 ** is not contained in the table.
113792 ** This function is used to add terms implied by JOIN syntax to the
113794 ** is ANDed with the existing WHERE clause, is of the form:
113798 ** where tab1 is the iSrc'th table in SrcList pSrc and tab2 is the
113799 ** (iSrc+1)'th. Column col1 is column iColLeft of tab1, and col2 is
113809 int isOuterJoin, /* True if this is an OUTER join */
113840 ** The EP_FromJoin property is used on terms of an expression to tell
113841 ** the LEFT OUTER JOIN processing logic that this term is part of the
113848 ** expression depends on table iRightJoinTable even if that table is not
113849 ** explicitly mentioned in the expression. That information is needed
113859 ** the output, which is incorrect.
113884 ** The left most table is the first entry in Select.pSrc. The right-most
113885 ** table is the last entry. The join operator is held in the entry to
113909 /* When the NATURAL keyword is present, add WHERE clause terms for
113952 ** Report an error if any column mentioned in the USING clause is
114083 ** register is initialized with value of LIMIT+OFFSET.) After the sorter
114095 /* If the inner loop is driven by an index such that values from
114125 ** form a distinct entry. iTab is a sorting index that holds previously
114126 ** seen combinations of the N values. A new entry is made in iTab
114129 ** A jump to addrRepeat is made and the N+1 values are popped from the
114152 ** Generate an error message when a SELECT is used within a subexpression
114166 "a SELECT that is part of an expression");
114178 ** If srcTab is negative, then the pEList expressions
114179 ** are evaluated in order to get the data for this row. If srcTab is
114180 ** zero or more, then data is pulled from srcTab and pEList is used only
114196 int hasDistinct; /* True if the DISTINCT keyword is present */
114225 /* This is an error condition that can result, for example, when a SELECT
114228 ** and reported later. But we need to make sure enough memory is allocated
114240 /* If the destination is an EXISTS(...) expression, the actual
114271 ** row is all NULLs.
114352 /* If the destination is DistFifo, then cursor (iParm+1) is open
114353 ** on an ephemeral index. If the current row is already present
114410 /* If this is a scalar select that is part of an expression, then
114443 /* Write the results into a priority queue that is order according to
114444 ** pDest->pOrderBy (in pSO). pDest->iSDParm (in iParm) is the cursor for an
114447 ** final OP_Sequence column. The last column is the record as a blob.
114462 /* If the destination is DistQueue, then cursor (iParm+1) is open
114492 /* Discard the results. This is used for SELECT statements inside
114493 ** the body of a TRIGGER. The purpose of such selects is to call
114504 /* Jump to the end of the loop if the LIMIT is reached. Except, if
114505 ** there is a sorter, in which case the sorter has already limited
114559 ** can only be changed if this is just a single reference to the object.
114561 ** This routine is used only inside of assert() statements.
114570 ** If the ExprList is an ORDER BY or GROUP BY clause then the resulting
114571 ** KeyInfo structure is appropriate for initializing a virtual index to
114572 ** implement that clause. If the ExprList is the result set of a SELECT
114573 ** then the KeyInfo structure is appropriate for initializing a virtual
114576 ** Space to hold the KeyInfo structure is obtained from malloc. The calling
114577 ** function is responsible for seeing that this structure is eventually
114623 ** Unless an "EXPLAIN QUERY PLAN" command is being processed, this function
114624 ** is a no-op. Otherwise, it adds a single row of output to the EQP result,
114625 ** where the caption is of the form:
114629 ** where xxx is one of "DISTINCT", "ORDER BY" or "GROUP BY". Exactly which
114630 ** is determined by the zUsage argument.
114642 ** is provided when SQLITE_OMIT_EXPLAIN is defined. This allows the code
114644 ** only exist if SQLITE_OMIT_EXPLAIN is not defined without polluting the
114657 ** Unless an "EXPLAIN QUERY PLAN" command is being processed, this function
114658 ** is a no-op. Otherwise, it adds a single row of output to the EQP result,
114659 ** where the caption is of one of the two forms:
114665 ** function parameters, and op is the text representation of the parameter
114667 ** TK_INTERSECT or TK_ALL. The first form is used if argument bUseTmp is
114668 ** false, or the second form if it is true.
114694 ** then the results were placed in a sorter. After the loop is terminated
114824 ** The declaration type is the exact datatype definition extracted from the
114825 ** original CREATE TABLE statement if the expression is a column. The
114826 ** declaration type for a ROWID field is INTEGER. Exactly when an expression
114827 ** is considered a column can be complex in the presence of subqueries. The
114828 ** result-set expression in all of the following SELECT statements is
114836 ** The declaration type for any expression other than a column is NULL.
114839 ** the SQLITE_ENABLE_COLUMN_METADATA compile-time option is used.
114870 /* The expression is a column. Locate the table the column is being
114874 Table *pTab = 0; /* Table structure column is extracted from */
114875 Select *pS = 0; /* Select the column is extracted from */
114893 ** trigger code is generated and so this condition is no longer
114900 ** when columnType() is called on the expression "t1.col" in the
114904 ** This is not a problem, as the column type of "t1.col" is never
114905 ** used. When columnType() is called on the expression
114906 ** "(SELECT t1.col)", the correct type is returned (see the TK_SELECT
114913 /* The "table" is actually a sub-select or a view in the FROM clause
114918 /* If iCol is less than zero, then the expression requests the
114919 ** rowid of the sub-select or view. This expression is legal (see
114922 ** The ALWAYS() is because iCol>=pS->pEList->nExpr will have been
114964 /* The expression is a sub-select. Return the declaration type and
115018 ** column specific strings, in case the schema is reset before this
115019 ** virtual machine is deleted.
115034 ** in the result set. This information is used to provide the
115048 /* If this is an EXPLAIN, skip this step */
115104 ** Given an expression list (which is really the list of expressions
115152 Expr *pColExpr = p; /* The expression that is the result column name */
115174 /* Make sure the column name is unique. If the name is not unique,
115282 /* The sqlite3ResultSetOfSelect() is only used n contexts where lookaside
115283 ** is disabled */
115324 ** the limit and offset. If there is no limit and/or offset, then
115328 ** a limit or offset is defined by pLimit and pOffset. iLimit and
115332 ** The iOffset register (if it exists) is initialized to the value
115333 ** of the OFFSET. The iLimit register is initialized to LIMIT. Register
115334 ** iOffset+1 is initialized to LIMIT+OFFSET.
115349 ** "LIMIT -1" always shows all rows. There is some
115393 ** The collating sequence for the compound select is taken from the
115414 ** The select statement passed as the second parameter is a compound SELECT
115418 ** Space to hold the KeyInfo structure is obtained from malloc. The calling
115419 ** function is responsible for ensuring that this structure is eventually
115461 ** There is exactly one reference to the recursive-table in the FROM clause
115466 ** one. Each row extracted from Queue is output to pDest. Then the single
115469 ** is added back into the Queue table. Then another row is extracted from Queue
115470 ** and the iteration continues until the Queue table is empty.
115472 ** If the compound query operator is UNION then no duplicate rows are ever
115475 ** discarded. If the operator is UNION ALL, then duplicates are allowed.
115478 ** ORDER BY order and the first entry is extracted for each cycle. Without
115479 ** an ORDER BY, the Queue table is just a FIFO.
115481 ** If a LIMIT clause is provided, then the iteration stops after LIMIT rows
115483 ** negative LIMIT means to output all rows. If there is also an OFFSET clause
115606 /* Keep running the loop until the Queue is empty */
115635 ** (3) There is no ORDER BY clause
115670 ** This routine is called to process a compound query form from
115675 ** left is p->pPrior. The left query could also be a compound query
115685 ** This statement is parsed up as follows:
115694 ** So if this routine is called with p equal to the t3 query, then
115716 /* Make sure there is no ORDER BY or LIMIT clause on prior SELECTs. Only
115894 ** it is that we currently need.
115927 /* INTERSECT is different from the others since it requires
116005 ** This section is run by the right-most SELECT statement only.
116035 /* If [0] is unused then [1] is also unused. So we can
116036 ** always safely abort as soon as the first unused slot is found */
116074 ** The data to be output is contained in pIn->iSdst. There are
116075 ** pIn->nSdst columns to be output. pDest is where the output should
116078 ** regReturn is the number of the register holding the subroutine
116081 ** If regPrev>0 then it is the first register in a vector that
116082 ** records the previous output. mem[regPrev] is a flag that is false
116083 ** if there has been no previous output. If regPrev>0 then code is
116084 ** generated to suppress duplicates. pKeyInfo is used for comparing
116087 ** If the LIMIT found in p->iLimit is reached, jump immediately to
116121 /* Suppress the first OFFSET entries if there is an OFFSET clause
116160 /* If this is a scalar select that is part of an expression, then
116186 ** SRT_Output. This routine is never called with any other
116190 ** Then the OP_ResultRow opcode is used to cause sqlite3_step() to
116201 /* Jump to the end of the loop if the LIMIT is reached.
116217 ** is an ORDER BY clause.
116223 ** <operator> is one of UNION ALL, UNION, EXCEPT, or INTERSECT. The idea
116224 ** is to code both <selectA> and <selectB> with the ORDER BY clause as
116237 ** AltB: Called when there is data from both coroutines and A<B.
116239 ** AeqB: Called when there is data from both coroutines and A==B.
116241 ** AgtB: Called when there is data from both coroutines and A>B.
116243 ** EofA: Called when data is exhausted from selectA.
116245 ** EofB: Called when data is exhausted from selectB.
116248 ** <operator> is used:
116268 ** Duplicate removal in the UNION, EXCEPT, and INTERSECT cases is handled
116270 ** output value. A comparison is made against this value and the output
116271 ** is skipped if the next results would be the same as the previous.
116273 ** The implementation plan is to implement the two coroutines and seven
116297 ** until all data is exhausted then jump to the "end" labe. AltB, AeqB,
116320 int addrEofA_noB; /* Alternate addrEofA if B is uninitialized */
116385 /* Compute the comparison permutation and keyinfo that is used with
116413 ** operator is UNION, EXCEPT, or INTERSECT (but not UNION ALL).
116623 ** This routine is part of the flattening procedure. A subquery
116624 ** whose result set is defined by pEList appears as entry in the
116626 ** FORM clause entry is iTable. This routine make the necessary
116710 ** The default way of implementing this query is to execute the
116727 ** Flattening is only attempted if all of the following are true:
116731 ** (2) The subquery is not an aggregate or (2a) the outer query is not a join
116733 ** FROM-clause subquery that is a candidate for flattening. (2b is
116736 ** (3) The subquery is not the right operand of a left outer join
116739 ** (4) The subquery is not DISTINCT.
116745 ** (6) The subquery does not use aggregates or the outer query is not
116753 ** (8) The subquery does not use LIMIT or the outer query is not a join.
116772 ** (15) The outer query is not part of a compound select or the
116776 ** (16) The outer query is not an aggregate or the subquery does
116780 ** (17) The sub-query is not a compound select, or it is a UNION ALL
116784 ** * is not itself part of a compound select,
116785 ** * is not an aggregate or DISTINCT query, and
116786 ** * is not a join
116792 ** operators have an implied DISTINCT which is disallowed by
116796 ** of result columns. This is actually a requirement for any compound
116797 ** SELECT statement, but all the code here does is make sure that no
116798 ** such (illegal) sub-query is flattened. The caller will detect the
116801 ** (18) If the sub-query is a compound select, then all terms of the
116808 ** (20) If the sub-query is a compound select, then it must not use
116814 ** (21) The subquery does not use LIMIT or the outer query is not
116817 ** (22) The subquery is not a recursive CTE.
116819 ** (23) The parent is not a recursive CTE, or the sub-query is not a
116820 ** compound query. This restriction is because transforming the
116824 ** (24) The subquery is not an aggregate that uses the built-in min() or
116830 ** In this routine, the "p" parameter is a pointer to the outer query.
116831 ** The subquery is p->pSrc->a[iFrom]. isAgg is true if the outer query
116832 ** uses aggregates and subqueryIsAgg is true if the subquery uses aggregates.
116834 ** If flattening is not attempted, this routine is a no-op and returns 0.
116835 ** If flattening is attempted this routine returns 1.
116860 /* Check to see if flattening is permitted. Return 0 if not.
116920 ** Restriction 3: If the subquery is a join, make sure the subquery is
116922 ** is not allowed:
116930 ** which is not at all the same thing.
116933 ** Restriction 12: If the subquery is the right operand of a left outer
116935 ** An examples of why this is not allowed:
116948 ** is fraught with danger. Best to avoid the whole thing. If the
116949 ** subquery is the right term of a LEFT JOIN, then do not flatten.
116955 /* Restriction 17: If the sub-query is a compound SELECT, then it must
116990 /***** If we reach this point, flattening is permitted. *****/
117000 /* If the sub-query is a compound SELECT statement, then (by restrictions
117009 ** using UNION ALL operators. In this case N is the number of simple
117082 ** subquery until code generation is
117086 ** pSubitem->pTab is always non-NULL by test restrictions and tests above.
117142 ** outer query (the middle slot) is used by the subquery. The next
117144 ** The middle slot is expanded to two slots in order to make space
117187 ** ORDER BY column expression is identical to the iOrderByCol'th
117194 ** (the only way this can happen is if the compound sub-query is
117219 /* The flattened query is distinct if either the inner or the
117220 ** outer query is distinct.
117227 ** One is tempted to try to add a and b to combine the limits. But this
117228 ** does not work if either limit is negative.
117236 /* Finially, delete what is left of the subquery and return
117266 ** The hope is that the terms added to the inner query will make it more
117271 ** (1) The inner query is an aggregate. (In that case, we'd really want
117275 ** (2) The inner query is the recursive part of a common table expression.
117280 ** (4) The inner query is the right operand of a LEFT JOIN. (The caller
117292 Select *pSubq, /* The subquery whose WHERE clause is to be augmented */
117334 ** * the aggregate function is either min() or max(), and
117335 ** * the argument to the aggregate function is a column value.
117338 ** is returned as appropriate. Also, *ppMinMax is set to point to the
117341 ** Or, if the conditions above are not met, *ppMinMax is set to 0 and
117342 ** WHERE_ORDERBY_NORMAL is returned.
117370 ** The select statement passed as the first argument is an aggregate query.
117371 ** The second argument is the associated aggregate-info object. This
117372 ** function tests if the SELECT is of the form:
117376 ** where table is a database table, not a sub-select or view. If the query
117378 ** <tbl> is returned. Otherwise, 0 is returned.
117440 ** This transformation is necessary because the multiSelectOrderBy() routine
117446 ** This transformation is only needed for EXCEPT, INTERSECT, and UNION.
117470 /* If we reach this point, that means the transformation is required. */
117503 ** non-zero, since pFrom is not allowed to be a table-valued function.
117507 sqlite3ErrorMsg(pParse, "'%s' is not a function", pFrom->zName);
117517 ** FROM clause element pItem is really a common-table-expression (CTE)
117521 ** If a non-NULL value is returned, set *ppContext to point to the With
117549 ** onto the top of the stack. If argument bFree is true, then this
117553 ** statement with which it is associated.
117568 ** if currently processing a CTE expression, if it is a recursive
117576 ** Whether or not a match is found, SQLITE_OK is returned if no error
117577 ** occurs. If an error does occur, an error message is stored in the
117600 /* If pCte->zCteErr is non-NULL at this point, then this is an illegal
117602 ** early. If pCte->zCteErr is NULL, then this is not a recursive reference.
117622 /* Check if this is a recursive CTE. */
117642 /* Only one recursive reference is permitted. */
117692 ** This function is used as the xSelectCallback2() callback by
117709 ** This routine is a Walker callback for "expanding" a SELECT statement.
117718 ** that implements the view. A copy is made of the view's SELECT
117761 ** an entry of the FROM clause is a subquery instead of a table or view,
117880 /* This expression is a "*" or a "TABLE.*" and needs to be
117920 /* If a column is marked as 'hidden', omit it from the expanded
118005 ** When this routine is the Walker.xExprCallback then expression trees
118007 ** when this routine is used for Walker.xExprCallback then
118008 ** Walker.xSelectCallback is set to do something useful for every
118021 ** Expanding a SELECT statement is the first step in processing a
118023 ** name resolution is performed.
118025 ** If anything goes wrong, an error message is written into pParse.
118048 ** This is a Walker.xSelectCallback callback for the sqlite3SelectTypeInfo()
118058 ** routine is called after identifier resolution.
118108 ** following is accomplished:
118138 ** The aggregate accumulator is a set of memory cells that hold
118257 ** to pC->iMem. But by the time the value is used, the original register
118311 ** encountered, then an appropriate error message is left in
118463 ** once, if the subquery is part of the WHERE clause in a LEFT JOIN,
118466 ** is sufficient, though the subroutine to manifest the view does need
118478 ** (SQLITE_MAX_EXPR_DEPTH-Parse.nHeight) height. This is a bit
118500 ** The subquery is implemented as a co-routine if all of these are true:
118501 ** (1) The subquery is guaranteed to be the outer loop (so that it
118503 ** (2) The ALL keyword after SELECT is omitted. (Applications are
118539 ** is a register allocated to hold the subroutine return address
118549 /* If the subquery is not correlated and if we are not inside of
118587 /* If the query is DISTINCT with an ORDER BY but is not an aggregate, and
118588 ** if the select-list is the same as the ORDER BY list, then this query
118593 ** is transformed to:
118597 ** The second form is preferred as a single index (or temp-table) may be
118608 ** the sDistinct.isTnct is still set. Hence, isTnct represents the
118620 /* If there is an ORDER BY clause, then create an ephemeral index to
118623 ** If that is the case, then the OP_OpenEphemeral instruction will be
118624 ** changed to an OP_Noop once we figure out that the sorting index is
118625 ** not needed. The sSort.addrSortIndex variable is used to facilitate
118641 /* If the output is destined for a temporary table, open that table.
118747 /* If there is both a GROUP BY and an ORDER BY clause and they are
118788 /* Processing for aggregates with GROUP BY is very different and
118802 /* If there is a GROUP BY clause we might need a sorting index to
118842 /* The optimizer is able to deliver rows in group by order so
118905 ** This is an optimization - the correct answer should result regardless.
118916 ** (b0 is memory location iBMem+0, b1 is iBMem+1, and so forth)
118941 ** block. If there were no changes, this block is skipped.
118985 ** is less than or equal to zero, the subroutine is a no-op. If
119021 ** the SQL statement is of the form:
119027 ** This statement is so common that it is optimized specially. The
119028 ** OP_Count instruction is executed either on the intkey table that
119030 ** is better to execute the op on an index, as indexes are almost
119049 ** In practice the KeyInfo structure will not be used. It is only
119078 /* Check if the query is of one of the following forms:
119083 ** If it is, then ask the code in where.c to attempt to sort results
119085 ** If where.c is able to produce results sorted in this order, then
119087 ** first iteration (since the first iteration of the loop is
119094 ** + If the query is a "SELECT min(x)", then the loop coded by
119124 ** processing is much simpler since there is only a single row
119158 /* If there is an ORDER BY clause, then we need to sort the results
119171 /* The SELECT has been coded. If there is an error in the Parse structure,
119175 /* Control jumps to here if an error is encountered above, or upon
119202 ** a legal notice, here is a blessing:
119223 ** This structure is used to pass data from sqlite3_get_table() through
119224 ** to the callback function is uses to build the result.
119237 ** This routine is called once for each row in the result table. Its job
119238 ** is to fill in the TabResult structure appropriately, allocating new
119247 /* Make sure there is enough space in p->azResult to hold everything
119263 /* If this is the first row, then generate an extra row containing
119310 ** The result that is written to ***pazResult is held in memory obtained
119313 ** the calling procedure is finished using it.
119357 db->errCode = res.rc; /* Assume 32-bit assignment is atomic */
119404 ** a legal notice, here is a blessing:
119435 ** the table. The list is connected by Trigger.pNext pointers.
119473 ** This is called by the parser when it sees a CREATE TRIGGER statement
119475 ** structure is generated based on the information available and stored
119477 ** sqlite3FinishTrigger() function is called to complete the trigger
119486 IdList *pColumns, /* column list if this is an UPDATE OF trigger */
119489 int isTemp, /* True if the TEMPORARY keyword is present */
119524 /* A long-standing parser bug is that this syntax was allowed:
119537 /* If the trigger name was unqualified, and the table is a temp table,
119540 ** exist, the error is caught by the block below.
119560 ** Normally, whenever a table is dropped, all associated triggers are
119561 ** dropped too. But if a TEMP trigger is created on a non-TEMP table
119562 ** and the table is dropped by a different database connection, the
119563 ** trigger is not visible to the database connection that does the
119565 ** "orphaned trigger" - a trigger whose associated table is missing.
119576 /* Check that the trigger name is not reserved and that no trigger of the
119666 ** This routine is called after all of the trigger actions have been parsed
119765 ** If an OOM error occurs, NULL is returned and db->mallocFailed is set.
119876 ** This function is called to drop a trigger from the database schema.
119923 ** is set on.
119993 ** pEList is the SET clause of an UPDATE statement. Each entry
119994 ** in pEList is of the format <id>=<expr>. If any of the entries
119996 ** then return TRUE. If pIdList==NULL, then it is considered a
119999 ** if there is no match.
120012 ** one trigger that must be fired when an operation of type 'op' is
120013 ** performed on the table, and, if that operation is an UPDATE, if at
120014 ** least one of the columns in pChanges is being modified.
120048 ** referring to a target in another database. An exception is when the
120049 ** trigger is in TEMP in which case it can refer to any other database it
120151 ** This function is used to add VdbeComment() annotations to a VDBE
120152 ** program. It is not used in production code, only for debugging.
120191 Table *pTab, /* The table pTrigger is attached to */
120202 int iEndTrigger = 0; /* Label to jump to if WHEN is false */
120252 ** (or NULL) the sub-vdbe is immediately halted by jumping to the
120299 ** TriggerPrg object exists, a new object is allocated and populated before
120305 Table *pTab, /* The table trigger pTrigger is attached to */
120313 /* It may be that this trigger has already been coded (or is in the
120314 ** process of being coded). If this is the case, then an entry with
120350 ** is a pointer to the sub-vdbe containing the trigger program. */
120360 ** recursive invocation of this trigger program is disallowed. Recursive
120361 ** invocation is disallowed if (a) the sub-program is really a trigger,
120363 ** is clear. */
120369 ** This is called to code the required FOR EACH ROW triggers for an operation
120371 ** is given by the op parameter. The tr_tm parameter determines whether the
120372 ** BEFORE or AFTER triggers are coded. If the operation is an UPDATE, then
120373 ** parameter pChanges is passed the list of columns being modified.
120376 ** operation on pTab, this function is a no-op.
120378 ** The reg argument is the address of the first in an array of registers
120380 ** in the trigger program. If N is the number of columns in table pTab
120396 ** populated by the caller (there is no data to populate them with anyway).
120400 ** is not a readable register, although registers (reg+N) through
120403 ** Parameter orconf is the default conflict resolution algorithm for the
120405 ** is the instruction that control should jump to if a trigger program
120452 ** Bit 0 of the returned mask is set if the left-most column of the
120453 ** table may be accessed using an [old|new].<col> reference. Bit 1 is set if
120454 ** the second leftmost column value is required, and so on. If there
120456 ** with an index greater than 32 may be accessed, 0xffffffff is returned.
120458 ** It is not possible to determine if the old.rowid or new.rowid column is
120459 ** accessed by triggers. The caller must always assume that it is.
120461 ** Parameter isNew must be either 1 or 0. If it is 0, then the mask returned
120466 ** included in the returned mask if the TRIGGER_BEFORE bit is set in the
120468 ** included in the returned mask if the TRIGGER_AFTER bit is set in tr_tm.
120507 ** a legal notice, here is a blessing:
120538 ** The default value of a column is specified by a DEFAULT clause in the
120543 ** from the P4 parameter of the OP_Column instruction, is returned instead.
120545 ** for the column and the P4 value is not required.
120549 ** complicated default expression value was provided, it is evaluated
120550 ** when the ALTER TABLE is executed and one of the literal values written
120553 ** Therefore, the P4 parameter is only required if the default value for
120554 ** the column is a literal number, string or null. The sqlite3ValueFromExpr()
120555 ** function is capable of transforming these types of expressions into
120558 ** If parameter iReg is not negative, code an OP_RealAffinity instruction
120559 ** on register iReg. This is used when an equivalent integer value is
120611 int *aXRef = 0; /* aXRef[i] is the index in pChanges->a[] of the
120613 ** aXRef[i]==-1 if the i-th column is not changed. */
120623 int hasFK; /* True if foreign key processing is required */
120660 ** updated is a view.
120769 ** So reset the colUsed mask. Unless this is a virtual table. In that
120777 /* There is one entry in the aRegIdx[] array for each index on the table
120967 ** contain the new value. If the record number is not being modified,
120968 ** then regNewRowid is the same register as regOldRowid, which is
120977 ** information is needed */
121000 ** row data. This array is used to check constants, create the new
121024 ** into a register. This is done if there are no BEFORE triggers, or
121038 ** verified. One could argue that this is wrong.
121048 ** is deleted or renamed by a BEFORE trigger - is left undefined in the
121101 ** That (regNew==regnewRowid+1) is true is also important for the
121103 ** value is copied from memory cell (regNewRowid+1+iCol), where iCol
121104 ** is the column index supplied by the user.
121180 ** Return the number of rows that were changed. If this routine is
121213 ** "onepass" strategy. Onepass is only used if the virtual table
121216 ** The default strategy is to create an ephemeral table that contains
121289 ** above. Also, if this is a top-level parse (not a trigger), clear the
121340 ** a legal notice, here is a blessing:
121410 ** The VACUUM command is used to clean up the database,
121411 ** collapse free space, etc. It is modelled after the VACUUM command
121424 ** Hence, temporary disk space that is approximately 2x the size of the
121425 ** original database is required. Every page of the database is written
121489 ** can be set to 'off' for this file, as it is not recovered if a crash
121490 ** occurs anyway. The integrity of the database is maintained by a
121492 ** sqlite3BtreeCopyFile() is called.
121497 ** actually occurs when doing a vacuum since the vacuum_db is initially
121498 ** empty. Only the journal header is written. Apparently it takes more
121541 ** file. This is done before the sqlite3BtreeGetPageSize(pMain) call below,
121620 ** associated storage, so all we have to do is copy their entries
121632 /* At this point, there is a write transaction open on both the
121645 ** The increment is used to increase the schema cookie so that other
121688 /* Currently there is an SQL level transaction open on the vacuum
121692 ** vacuum database. The vacuum_db journal file is deleted when the pager
121693 ** is closed by the DETACH.
121718 ** a legal notice, here is a blessing:
121731 ** Before a virtual table xCreate() or xConnect() method is invoked, the
121732 ** sqlite3.pVtabCtx member variable is set to point to an instance of
121733 ** this struct allocated on the stack. It is used by the implementation of
121741 int bDeclared; /* True after sqlite3_declare_vtab() is called */
121750 sqlite3 *db, /* Database in which module is registered */
121795 sqlite3 *db, /* Database in which module is registered */
121810 sqlite3 *db, /* Database in which module is registered */
121825 ** If an unlock is omitted, resources leaks will occur.
121827 ** If a disconnect is attempted while a virtual table is locked,
121828 ** the disconnect is deferred until all locks have been removed.
121836 ** pTab is a pointer to a Table structure representing a virtual-table.
121869 ** Table p is a virtual table. This function moves all elements in the
121872 ** Except, if argument db is not NULL, then the entry associated with
121873 ** connection db is left in the p->pVTable list.
121881 ** that contains table p is held by the caller. See header comments
121908 ** Table *p is a virtual table. This function removes the VTable object
121910 ** list in p->pVTab. It also decrements the VTable ref count. This is
121938 ** caller. This is done to protect the sqlite3.pDisconnect list. The
121939 ** sqlite3.pDisconnect list is accessed only as follows:
121946 ** associated with the database the virtual table is stored in is held
121947 ** or, if the virtual table is stored in a non-sharable database, then
121948 ** the database handle mutex is held.
121951 ** by multiple threads. It is thread-safe.
121972 ** This routine is called, for example, just before deleting the Table
121975 ** Since it is a virtual-table, the Table structure contains a pointer
121977 ** structure is associated with a single sqlite3* user of the schema.
121979 ** connection db is decremented immediately (which may lead to the
121997 ** The string is not copied - the pointer is stored. The
121998 ** string will be freed automatically when the table is
122027 int iDb; /* The database the table is being created in */
122056 ** The second call, to obtain permission to create the table, is made now.
122092 /* If the CREATE VIRTUAL TABLE statement is being entered for the
122093 ** first time (in other words if the virtual table is actually being
122144 ** record of the table. The xConnect() method is not called until
122145 ** the first time the virtual table is used in an SQL statement. This
122190 ** pointer to the function to invoke is passed as the fourth parameter
122210 /* Check that the virtual-table is not already being initialized */
122316 ** This function is invoked by the parser to call the xConnect() method
122317 ** of the virtual table pTab. If an error occurs, an error code is returned
122320 ** This call is a no-op if table pTab is not a virtual table.
122353 ** Grow the db->aVTrans[] array so that there is room for at least one
122385 ** This function is invoked by the vdbe to call the xCreate method
122388 ** If an error occurs, *pzErr is set to point an an English language
122389 ** description of the error and an SQLITE_XXX error code is returned.
122416 /* Justification of ALWAYS(): The xConstructor method is required to
122429 ** This function is used to set the schema of a virtual table. It is only
122512 ** This function is invoked by the vdbe to call the xDestroy method
122514 ** when a DROP TABLE is mentioned.
122516 ** This call is a no-op if zTab is not a virtual table.
122534 assert( xDestroy!=0 ); /* Checked before the virtual table is created */
122551 ** called is identified by the second argument, "offset", which is
122554 ** The array is cleared after invoking the callbacks.
122582 ** If an error message is available, leave it in p->zErrMsg.
122622 ** (xBegin/xRollback/xCommit and optionally xSync) and a transaction is
122625 ** If the xBegin call is successful, place the sqlite3_vtab pointer
122632 /* Special case: If db->aVTrans is NULL and db->nVTrans is greater
122633 ** than zero, then this function is being called from within a
122634 ** virtual module xSync() callback. It is illegal to write to
122648 /* If pVtab is already in the aVTrans array, return early */
122678 ** If op is SAVEPOINT_BEGIN, the xSavepoint method is invoked. If it is
122679 ** SAVEPOINT_ROLLBACK, the xRollbackTo method. Otherwise, if op is
122681 ** an open transaction is invoked.
122684 ** processing is abandoned and the error returned to the caller of this
122686 ** SQLITE_OK is returned.
122722 ** The first parameter (pDef) is a function implementation. The
122723 ** second parameter (pExpr) is the first argument to this function.
122724 ** If pExpr is a column in a virtual table, then let the virtual
122727 ** This routine is used to allow virtual table implementations to
122731 ** new FuncDef structure that is marked as ephemeral using the
122751 /* Check to see the left operand is a column in a virtual table */
122795 ** Make sure virtual table pTab is contained in the pParse->apVirtualLock[]
122797 ** array if it is missing. If pTab is already in the array, this routine
122798 ** is a no-op.
122825 ** An eponymous virtual table instance is one that is named after its
122875 ** sqlite3DeleteTable() routine will know that it is not stored in
122887 ** The results of this routine are undefined unless it is called from
122947 ** a legal notice, here is a blessing:
122969 ** a legal notice, here is a blessing:
123021 ** each term in the FROM clause (which is to say, for each of the
123057 int addrVisit; /* Address at which row is visited */
123065 ** prevent a query solution - which is an error) and many terms of the
123093 u8 needFree; /* True if sqlite3_free(idxStr) is needed */
123135 ** showing dependencies and costs for travelling between nodes. (That is
123138 ** one-to-one as are graph nodes. But it is a useful visualization aid.)
123139 ** Then a WherePath object is a path through the graph that visits some
123146 ** at the end is the chosen query plan.
123161 ** clause subexpression is separated from the others by AND operators,
123169 ** When a term is of the form:
123173 ** where X is a column name and <op> is one of certain operators,
123186 ** is collected about the OR clause.
123189 ** categories, then eOperator==0. The WhereTerm.pExpr field is still set
123190 ** to the original subexpression content and wtFlags is set up appropriately
123195 ** cursor number into bits and the translated bit is stored in the prereq
123196 ** fields. The translation is used in order to maximize the number of
123205 ** The number of terms in a join is limited by the number of bits
123206 ** in prereqRight and prereqAll. The default is 64 bits, hence SQLite
123207 ** is only able to process joins with 64 or fewer tables.
123210 Expr *pExpr; /* Pointer to the subexpression that is this term */
123223 WhereClause *pWC; /* The clause this term is part of */
123233 #define TERM_CODED 0x04 /* This term is already coded */
123246 #define TERM_IS 0x800 /* Term.pExpr is an IS operator */
123249 ** An instance of the WhereScan object is used as an iterator for locating
123268 ** WHERE clause. Mostly this is a container for one or more WhereTerms.
123322 ** corresponds VDBE cursor number B. The A-th bit of a bitmask is 1<<A.
123328 ** Note that the mapping is not necessarily ordered. In the example
123331 ** does not really matter. What is important is that sparse cursor
123346 ** This object is a convenience wrapper holding all information needed
123365 ** this structure is returned by the first half and passed
123387 u8 bOrderedInnerLoop; /* True if only the inner-most loop is ordered */
123503 #define WHERE_IPK 0x00000100 /* x is the INTEGER PRIMARY KEY */
123504 #define WHERE_INDEXED 0x00000200 /* WhereLoop.u.btree.pIndex is valid */
123505 #define WHERE_VIRTUALTABLE 0x00000400 /* WhereLoop.u.vtab is valid */
123512 #define WHERE_PARTIALIDX 0x00020000 /* The automatic index is partial */
123519 ** This routine is a helper for explainIndexRange() below
123528 int iTerm, /* Index of this term. First is zero */
123557 ** is run and there is an index on (a, b), then this function returns a
123589 ** This function is a no-op unless currently processing an EXPLAIN QUERY PLAN
123591 ** defined at compile-time. If it is not a no-op, a single OP_Explain opcode
123592 ** is added to the output to describe the table scan strategy in pLevel.
123594 ** If an OP_Explain opcode is added to the VM, its address is returned.
123595 ** Otherwise, if no OP_Explain is coded, zero is returned.
123703 ** implement level pLvl. Argument pSrclist is a pointer to the FROM
123706 ** If argument addrExplain is not 0, it must be the address of an
123740 ** The t2.z='ok' is disabled in the in (2) because it originates
123741 ** in the ON clause. The term is disabled in (3) because it is not part
123742 ** of a LEFT OUTER JOIN. In (1), the term is not disabled.
123745 ** of the join. Disabling is an optimization. When terms are satisfied
123748 ** but joins might run a little slower. The trick is to disable as much
123752 ** If all the children of a term are disabled, then that term is also
123765 ** Usually the parent term is marked as TERM_CODED. But if the parent
123768 ** a conditional such that is only evaluated on the second pass of a
123799 ** This routine makes its own copy of zAff so that the caller is free
123822 /* Code the OP_Affinity opcode if there is anything left to do. */
123832 ** term can be either X=expr or X IN (...). pTerm is the term to be
123835 ** The current value for the constraint is left in register iReg.
123837 ** For a constraint of the form X=expr, the expression is evaluated and its
123838 ** result is left on the stack. For constraints of the form X IN (...)
123919 ** Suppose the WHERE clause is this: a==5 AND b IN (1,2,3) AND c>5 AND c<10
123921 ** example, the third "c" value is an inequality. So only two
123924 ** in consecutive registers and the index of the first register is returned.
123927 ** of nEq including 0. If nEq==0, this routine is nearly a no-op.
123928 ** The only thing it does is allocate the pLevel->iMem memory cell and
123931 ** The nExtraReg parameter is 0 or 1. It is 0 if all WHERE clause constraints
123932 ** are == or IN and are covered by the nEq. nExtraReg is 1 if there is
123944 ** Before returning, *pzAff is set to point to a buffer containing a
123948 ** SQLITE_AFF_BLOB. This is to deal with SQL such as the following:
123977 /* This module is only called on query plans that use an index. */
124020 /* The following testcase is true for indices with redundant columns.
124057 ** If the most recently coded instruction is a constant range constraint
124069 ** Except, of course, if SQLITE_LIKE_DOESNT_MATCH_BLOBS is defined, then
124070 ** only the one pass through the string space is required, so this routine
124095 ** Information is passed from codeCursorHint() down to individual nodes of
124106 ** This function is called for every node of an expression that is a candidate
124125 ** should be included in the cursor-hint for a table that is on the rhs
124127 ** expression is not suitable.
124129 ** An expression is unsuitable if it might evaluate to non NULL even if
124130 ** a TK_COLUMN node that does affect the value of the expression is set
124157 ** This function is called on every node of an expression tree used as an
124158 ** argument to the OP_CursorHint instruction. If the node is a TK_COLUMN
124168 ** Also, if the node is a TK_COLUMN that does access the table idenified
124169 ** by pCCurHint.iTabCur, and an index is being used (which we will
124192 ** be a correlated sub-query, and expression pExpr is an aggregate from
124204 ** Insert an OP_CursorHint instruction if it is appropriate to do so.
124240 ** JOIN for which the current table is not the rhs are omitted
124243 ** If this table is the rhs of a LEFT JOIN, "IS" or "IS NULL" terms
124245 ** This is to address the following:
124249 ** Say there is a single row in t2 that matches (t1.a=t2.b), but its
124250 ** t2.c values is not NULL. If the (t2.c IS NULL) constraint is
124251 ** pushed down to the cursor, this row is filtered out, causing
124253 ** WHERE clause, and so the query returns a row. Which is incorrect.
124295 /* If we survive all prior tests, that means this term is worth hinting */
124311 ** Cursor iCur is open on an intkey b-tree (a table). Register iRowid contains
124316 ** Normally, this is just:
124320 ** However, if the scan currently being coded is a branch of an OR-loop and
124321 ** the statement currently being coded is a SELECT, then P3 of the OP_Seek
124322 ** is set to iIdxCur and P4 is set to point to an array of integers
124323 ** containing one entry for each column of the table cursor iCur is open
124324 ** on. For each table column, if the column is the i'th column of the
124325 ** index, then the corresponding array entry is set to (i+1). If the column
124326 ** does not appear in the index at all, the array entry is set to 0.
124330 Index *pIdx, /* Index scan is using */
124382 int iRowidReg = 0; /* Rowid is stored in this register, if not zero */
124404 ** When there is an IN operator, we also have a "addrNxt" label that
124407 ** is the same as "addrBrk".
124412 /* If this is the right table of a LEFT OUTER JOIN, allocate and
124434 /* Case 1: The table is a virtual-table. Use the VFilter and VNext
124492 ** the IN constraint is not satisfied */
124507 /* These registers need to be preserved in case there is an IN operator
124579 assert( TK_GE==TK_GT+3 ); /* ... is correcct. */
124643 ** index is on (x,y,z), then the following clauses are all
124658 ** If there are no inequality constraints, then N is at
124661 ** This case is also used when there are no WHERE clause
124662 ** constraints but an index is selected anyway, in order
124687 int start_constraints; /* Start of range is constrained */
124706 ** should not have a NULL value stored in 'x'. If column 'x' is
124745 ** bottom bit indicates whether the search order is ASC or DESC. */
124805 /* Since the comparison is to be performed with no conversions
124827 ** so no further seeking is needed */
124873 /* Check if the index cursor is past the end of the range. */
124887 /* pIdx is a covering index. No need to access the main table. */
124947 ** RowSetTest are such that the rowid of the current row is inserted
124948 ** into the RowSet. If it is already present, control skips the
124960 ** Goto B # The loop is finished.
124968 ** Added 2014-05-26: If the table is a WITHOUT ROWID table, then
125019 /* Initialize the rowset register to contain NULL. An SQL NULL is
125025 ** is required in a few obscure LEFT JOIN cases where control jumps
125027 ** correct response for the end-of-loop code (the OP_Return) is to
125045 /* If the original WHERE clause is z of the form: (x1 OR x2 OR ...) AND y
125050 ** Actually, each subexpression is converted to "xN AND w" where w is
125056 ** is not contained in the ON clause of a LEFT JOIN.
125080 ** sub-WHERE clause is to to invoke the main loop body as a subroutine.
125105 /* This is the sub-WHERE clause body. First skip over
125137 ** is zero, assume that the key cannot already be present in
125138 ** the temp table. And if iSet is -1, assume that there is no
125160 ** current sub-WHERE row is a duplicate from prior sub-WHEREs. */
125171 ** index, and the index is opened using the same cursor number
125176 ** uses an index, and this is either the first OR-connected term
125177 ** processed or the index is the same as that used by all previous
125215 /* Case 6: There is no usable index. We must do a complete
125222 /* Tables marked isRecursive have only a single row that is stored in
125261 /* If the TERM_LIKECOND flag is set, that means that the range search
125262 ** is sufficient to guarantee that the LIKE operator is true, so we
125347 ** a legal notice, here is a blessing:
125385 ** The new WhereTerm object is constructed from Expr p and with wtFlags.
125386 ** The index in pWC->a[] of the new WhereTerm is returned on success.
125387 ** 0 is returned if the new WhereTerm could not be added due to a memory
125394 ** for freeing the expression p is assumed by the WhereClause object pWC.
125395 ** This is true even if this routine fails to allocate a new WhereTerm.
125438 ** Return TRUE if the given operator is one of the operators that is
125460 ** is not commuted.
125469 /* Both X and Y have COLLATE operators. Make sure X is always
125520 ** Check to see if the given expression is a LIKE or GLOB operator that
125521 ** can be optimized using inequality constraints. Return TRUE if it is
125535 int *pisComplete, /* True if the only wildcard is % in the last character */
125536 int *pnoCase /* True if uppercase is equivalent to lowercase */
125596 /* If the rhs of the LIKE expression is a variable, and the current
125597 ** value of the variable means there is no need to invoke the LIKE
125622 ** Check to see if the given expression is of the form
125626 ** where OP is one of MATCH, GLOB, LIKE or REGEXP and "column" is a
125629 ** If it is then return TRUE. If not, return FALSE.
125690 ** Return the N-th AND-connected subterm of pTerm. Or if pTerm is not
125691 ** a conjunction, then return just pTerm when N==0. If N is exceeds
125710 ** compatible (if one is = and the other is <, for example) then
125711 ** add a new virtual AND term to pWC that is the combination of the
125720 ** The following is NOT generated:
125771 ** A WhereOrTerm object is computed and attached to the term under
125792 ** term that is an equivalent IN expression. In other words, if the term
125793 ** being analyzed is:
125818 ** A subterm is "indexable" if it is of the form
125819 ** "T.C <op> <expr>" where C is any column of table T and
125820 ** <op> is one of "=", "<", "<=", ">", ">=", "IS NULL", or "IN".
125821 ** A subterm is also indexable if it is an AND of two or more
125822 ** subsubterms at least one of which is indexable. Indexable AND
125829 ** is decided elsewhere. This analysis only looks at whether subterms
125834 ** always prefer case 1, so in that case we pretend that case 3 is not
125838 ** (E) above is indexable on tables P, Q, and R.
125842 ** the union of all rowids using a RowSet object. This is similar
125848 ** zero. This term is not useful for search.
125870 ** object that is attached to the original OR clause term.
125965 ** is satisfied.
125968 ** that there is no possibility of transforming the OR clause into an
125971 ** case means that every term of the OR clause is of the form
125972 ** "table.column=expr" for some single table. The one bit that is set
125974 ** sure the same column is used on all terms. The 2-bit case is when
125977 ** or table2.column as the LHS if either is common to every term of
125984 int okToChngToIN = 0; /* True if the conversion to IN is valid */
125993 ** and column is found but leave okToChngToIN false if not found.
126001 /* This is the 2-bit case and we are on the second iteration and
126002 ** current term is from the first iteration. So skip this term. */
126008 /* This term must be of the form t1.a==t2.b where t2 is in the
126009 ** chngToIN set but t1 is not. This term will be either preceded
126032 ** table and column is common to every term in the OR clause */
126042 /* If the right-hand side is also a column, then the affinities
126057 /* At this point, okToChngToIN is true if original pTerm satisfies
126058 ** case 1. In that case, construct a new virtual term that is
126099 ** We already know that pExpr is a binary operator where both operands are
126100 ** column references. This routine checks to see if pExpr is an equivalence
126107 ** 5b. The overall collating sequence is BINARY
126110 ** This is an optimization. No harm comes from returning 0. But if 1 is
126163 ** Expression pExpr is one operand of a comparison operator that might
126165 ** in any index. Return TRUE (1) if pExpr is an indexed term and return
126166 ** FALSE (0) if not. If TRUE is returned, also set *piCur to the cursor
126167 ** number of the table that is indexed and *piColumn to the column number
126168 ** of the column that is indexed, or -2 if an expression is being indexed.
126170 ** If pExpr is a TK_COLUMN column reference, then this routine always returns
126171 ** true even if that particular column is not indexed, because the column
126208 ** The input to this routine is an WhereTerm structure with only the
126209 ** "pExpr" field filled in. The job of this routine is to analyze the
126213 ** If the expression is of the form "<expr> <op> X" it gets commuted
126216 ** If the expression is of the form "X <op> Y" where both X and Y are
126217 ** columns, then the original expression is unchanged and a new virtual
126218 ** term of the form "Y <op> X" is added to the WHERE clause and
126219 ** analyzed separately. The original term is marked with TERM_COPIED
126220 ** and the new term is marked with TERM_DYNAMIC (because it's pExpr
126222 ** is a commuted copy of a prior term.) The original term has nChild=1
126328 /* If a term is the BETWEEN operator, create two new virtual terms
126333 ** is converted into:
126339 ** term. That means that if the BETWEEN term is coded, the children are
126341 ** BETWEEN term is skipped.
126366 /* Analyze a term that is composed of two or more subterms connected by
126380 ** A like pattern of the form "x LIKE 'aBc%'" is changed into constraints
126384 ** The last character of the prefix "abc" is incremented to form the
126385 ** termination condition "abd". If case is not significant (the default
126386 ** for LIKE) then the lower-bound is made all uppercase and the upper-
126387 ** bound is made all lowercase so that the bounds also work when comparing
126406 ** lower-case (upper-case is less than lower-case in ASCII) so that
126424 /* The point is to increment the last character before the first
126462 ** current expression is of the form: column MATCH expr.
126463 ** This information is used by the xBestIndex methods of
126498 /* When sqlite_stat3 histogram data is available an operator of the
126500 ** as "x>NULL" if x is not an INTEGER PRIMARY KEY. So construct a
126548 ** each subexpression is separated by the AND operator or some other
126550 ** is filled with pointers to subexpressions. For example:
126556 ** The original WHERE clause in pExpr is unaltered. All this routine
126557 ** does is make slot[] entries point to substructure within pExpr.
126591 ** itself is not freed. This routine is the inverse of
126711 ** a legal notice, here is a blessing:
126719 ** the WHERE clause of SQL statements. This module is responsible for
126722 ** so is applicable. Because this module is responsible for selecting
126790 ** Return ONEPASS_OFF (0) if an UPDATE or DELETE statement is unable to
126793 ** a single row is to be changed. Return ONEPASS_MULTI (2) if the one-pass
126796 ** If the ONEPASS optimization is used (if this routine returns true)
126800 ** Either value may be -1, indicating that cursor is not used.
126803 ** aiCur[0] and aiCur[1] both get -1 if the where-clause logic is
126830 ** appended, or it might be discarded. Do whatever is the right thing
126868 ** iCursor is not in the set.
126884 ** There is one cursor per table in the FROM clause. The number of
126885 ** tables in the FROM clause is limited by a test early in the
126981 ** for terms of the form "X <op> <expr>" where X is column iColumn of table
126982 ** iCur. Or if pIdx!=0 then X is column iColumn of index pIdx. pIdx
126987 ** If the search is for X and the WHERE clause contains terms of the
126989 ** "Y <op> <expr>". The number of levels of transitivity is limited,
126990 ** but is enough to handle most commonly occurring SQL statements.
126992 ** If X is not the INTEGER PRIMARY KEY then X must be compatible with
127032 ** Search for a term in the WHERE clause that is of the form "X <op> <expr>"
127033 ** where X is a reference to the iColumn of table iCur or of index pIdx
127034 ** if pIdx!=0 and <op> is one of the WO_xx operator codes specified by
127041 ** The term returned might by Y=<expr> if there is another constraint in
127051 ** <expr> is a constant expression of some kind. Only return entries of
127052 ** the form "X <op> Y" where Y is a column in another table if no terms of
127087 ** If such an expression is found, its index in pList->a[] is returned. If
127088 ** no expression is found, -1 is returned.
127117 ** Return TRUE if the iCol-th column of index pIdx is NOT NULL
127137 ** is redundant.
127139 ** A DISTINCT list is redundant if any subset of the columns in the
127153 /* If there is more than one table or sub-select in the FROM clause of
127155 ** clause is redundant. */
127160 /* If any of the expressions is an IPK column on table iBase, then return
127162 ** current SELECT is a correlated sub-query.
127172 ** 1. The index is itself UNIQUE, and
127176 ** where X is a constant value. The collation sequences of the
127191 /* This index implies that the DISTINCT qualifier is redundant. */
127211 ** opcodes into OP_Copy when the table is being accessed via co-routine
127214 ** If the bIncrRowid parameter is 0, then any OP_Rowid instructions on
127215 ** cursor iTabCur are transformed into OP_Null. Or, if bIncrRowid is non-zero,
127216 ** then each OP_Rowid is transformed into an instruction to increment the
127223 int iRegister, /* The first column is in this register */
127297 ** Return TRUE if the WHERE clause term pTerm is of a form where it
127353 int addrCounter = 0; /* Address where integer counter is initialized */
127354 int regBase; /* Array of registers where record is assembled */
127407 ** covering index. A "covering index" is an index that contains all
127526 ** Allocate and populate an sqlite3_index_info structure. It is the
127623 /* The direct assignment in the previous line is possible only because
127650 ** If an error occurs, pParse is populated with an error message and a
127651 ** non-zero value is returned. Otherwise, 0 is returned and the output
127652 ** part of the sqlite3_index_info structure is left populated.
127654 ** Whether or not an error is returned, it is the responsibility of the
127656 ** that this is required.
127679 /* This error is now caught by the caller.
127701 ** Return the index of the sample that is the smallest sample that
127702 ** is greater than or equal to pRec. Note that this index is not an index
127703 ** into the aSample[] array - it is an index into a virtual set of samples
127722 tRowcnt iLower = 0; /* anLt[] + anEq[] of largest sample pRec is > */
127733 ** is simply the aSample[] array. If the samples in aSample[] contain more
127736 ** If pRec contains N fields, where N is more than one, then as well as the
127739 ** in aSample is:
127748 ** unique prefixes [a], [b] and [c]. But since that is hard to organize,
127767 ** Except, each sample may be extended to ensure that it is greater than or
127769 ** sample 2 is the first sample of a block of N samples, so at first it
127772 ** it is extended to two fields. The duplicates that this creates do not
127785 /* The proposed effective sample is a prefix of sample aSample[iSamp].
127787 ** fields that is greater than the previous effective sample. */
127817 /* If (res==0) is true, then pRec must be equal to sample i. */
127825 /* Unless i==pIdx->nSample, indicating that pRec is larger than
127834 /* if i==0 and iCol==0, then record pRec is smaller than all samples
127853 /* Record pRec is equal to sample i */
127858 /* At this point, the (iCol+1) field prefix of aSample[i] is the first
127859 ** sample that is greater than pRec. Or, if i==pIdx->nSample then pRec
127860 ** is larger than all samples in the array. */
127889 ** If it is not NULL, pTerm is a term that provides an upper or lower
127890 ** bound on a range scan. Without considering pTerm, it is estimated
127895 ** then the return value is the likelihood multiplied by the number of
127928 ** This function is called to estimate the number of rows visited by a
127934 ** Value pLoop->nOut is currently set to the estimated number of rows
127938 ** times (once for each (a,b) combination that matches a=?) is dealt with
127945 ** N is the total number of samples, the pLoop->nOut value is adjusted
127950 ** If pLower is NULL, or a value cannot be extracted from the term, L is
127951 ** set to zero. If pUpper is NULL, or a value cannot be extracted from it,
127952 ** U is set to N.
127957 ** is left as is.
127959 ** If an error occurs, an SQLite error code is returned. Otherwise,
128009 /* If there is both an upper and lower bound specified, and the
128035 ** This function is used to estimate the number of rows that will be visited
128039 ** example, assuming that index p is on t1(a):
128046 ** If either of the upper or lower bound is not present, then NULL is passed in
128049 ** The value in (pBuilder->pNew->u.btree.nEq) is the number of the index
128052 ** assuming index p is on t1(a, b), and the SQL query is:
128056 ** then nEq is set to 1 (as the range restricted column, b, is the second
128057 ** left-most column of the index). Or, if the query is:
128061 ** then nEq is set to 0.
128063 ** When this function is called, *pnOut is set to the sqlite3LogEst() of the
128064 ** number of rows that the index scan is expected to visit without
128065 ** considering the range constraints. If nEq is 0, then *pnOut is the number of
128066 ** rows in the index. Assuming no error occurs, *pnOut is adjusted (reduced)
128097 ** lower bound being the concatenation of $P and $L, where $P is the
128099 ** columns of the index, and $L is the value in pLower.
128101 ** Or, if pLower is NULL or $L cannot be extracted from it (because it
128102 ** is not a simple variable or literal value), the lower bound of the
128103 ** range is $P. Due to a quirk in the way whereKeyStats() works, even
128104 ** if $L is available, whereKeyStats() is called for both ($P) and
128105 ** ($P:$L) and the larger of the two returned values is used.
128107 ** Similarly, iUpper is to be set to the estimate of the number of rows
128109 ** is either ($P) or ($P:$U). Again, even if $U is available, both values
128112 ** The number of rows between the two bounds is then just iUpper-iLower.
128147 int bOk; /* True if value is extracted from pExpr */
128162 int bOk; /* True if value is extracted from pExpr */
128208 /* TUNING: If there is both an upper and lower limit and neither limit
128209 ** has an application-defined likelihood(), assume the range is
128211 ** range query (e.g. col > ?) is assumed to match 1/4 of the rows in the
128212 ** index. While a closed range (e.g. col BETWEEN ? AND ?) is estimated to
128235 ** the histogram data. This only works when x is the left-most
128236 ** column of an index and sqlite_stat3 histogram data is available
128237 ** for that index. When pExpr==NULL that means the constraint is
128244 ** This routine can fail if it is unable to load a collating sequence
128246 ** for a UTF conversion required for comparison. The error is stored
128275 /* This is an optimization only. The call to sqlite3Stat4ProbeSetValue()
128302 ** is a list of values. Example:
128310 ** This routine can fail if it is unable to load a collating sequence
128312 ** for a UTF conversion required for comparison. The error is stored
128550 ** (2) X is a proper subset of Y
128554 ** than Y and that every WHERE clause term used by X is also used
128557 ** If X is a proper subset of Y then Y is a better choice and ought
128559 ** relationship is inverted and needs to be adjusted. The third rule
128561 ** deserve a lower cost even if it is a proper subset of Y.
128569 return 0; /* X is not a subset of Y */
128594 ** is a proper subset.
128596 ** To say "WhereLoop X is a proper subset of Y" means that X uses fewer
128597 ** WHERE clause terms than Y and that every WHERE clause term used by X is
128606 /* Adjust pTemplate cost downward so that it is cheaper than its
128613 /* Adjust pTemplate cost upward so that it is costlier than p since
128614 ** pTemplate is a proper subset of p */
128630 ** If pX is a WhereLoop that pTemplate can supplant, then return the
128644 ** then those WhereLoops need to be considered separately. Neither is
128648 /* In the current implementation, the rSetup value is either zero
128650 ** is the same for compatible WhereLoops. */
128660 ** UNIQUE constraint) with one or more == constraints is better
128661 ** than an automatic index. Unless it is a skip-scan. */
128671 /* If existing WhereLoop p is better than pTemplate, pTemplate can be
128672 ** discarded. WhereLoop p is better if:
128684 /* If pTemplate is always better than p, then cause p to be overwritten
128685 ** with pTemplate. pTemplate is better than p if:
128704 ** is better and has fewer dependencies. Or the template will be ignored
128705 ** and no insert will occur if an existing WhereLoop is faster and has
128706 ** fewer dependencies than the template. Otherwise a new WhereLoop is
128709 ** If pBuilder->pOrSet is not NULL then we care about only the
128711 ** information is gathered in the pBuilder->pOrSet object. This special
128712 ** processing mode is used only for OR clause processing.
128714 ** When accumulating multiple loops (when pBuilder->pOrSet is NULL) we
128716 ** new template is better. Loops may be overwritten if the following
128730 /* If pBuilder->pOrSet is defined, then only keep track of the costs
128757 /* There already exists a WhereLoop on the list that is better
128826 ** For every WHERE clause term that is not used by the index
128831 ** TUNING: For every WHERE clause term that is not used by the index
128834 ** TODO --> Perhaps this is something that could be improved by better
128842 ** form "x==EXPR" and EXPR is not a constant 0 or 1, then make sure the
128843 ** final output row estimate is no greater than 1/4 of the total number
128845 ** out at least 3 out of 4 rows. If EXPR is -1 or 0 or 1, then maybe the
128846 ** "x" column is boolean or else -1 or 0 or 1 is a common default value
128873 /* If a truth probability is specified using the likelihood() hints,
128910 ** When this function is called, pBuilder->pNew->nOut contains the
128912 ** terms only. If it is modified, this value is restored before this
128915 ** If pProbe->tnum==0, that means pIndex is a fake index used for the
129066 /* At this point pNew->nOut is set to the number of rows expected to
129073 /* Adjust nOut using stat3/stat4 data. Or, if there is no stat3/stat4
129116 /* TUNING: If there is no likelihood() value, assume that a
129126 ** it to pNew->rRun, which is currently set to the cost of the index
129127 ** seek only. Then, if this is a non-covering index, add the cost of
129167 ** number of repeats in the left-most terms is at least 18.
129169 ** The magic number 18 is selected on the basis that scanning 17 rows
129170 ** is almost always quicker than an index seek (even though if the index
129172 ** the code). And, even if it is not, it should not be too much slower.
129203 ** Return True if it is possible that pIndex might be useful in
129207 ** if there is no way for pIndex to be useful in implementing that
129242 ** the table is used by an index. Only the first 63 columns are considered.
129281 ** is idenfied by pBuilder->pNew->iTab. That table is guaranteed to be
129293 ** where K is a value between 1.1 and 3.0 set based on the relative
129296 ** For an index scan, where nVisit is the number of index rows visited
129297 ** by the scan, and nSeek is the number of seek operations required on
129303 ** Normally, nSeek is 1. nSeek values greater than 1 come about if the
129308 ** of uncertainty. For this reason, scoring is designed to pick plans that
129310 ** log(nRow) factor is omitted from a non-covering index scan in order to
129312 ** performance of using an index is far better than the worst-case performance
129349 /* There is no INDEXED BY clause. Create a fake Index object in local
129367 ** NOT INDEXED qualifier is omitted from the FROM clause */
129397 /* TUNING: One-time cost for computing the automatic index is
129398 ** estimated to be X*N*log2(N) where N is the number of rows in
129399 ** the table being indexed and where X is 7 (LogEst=28) for normal
129401 ** of X is smaller for views and subqueries so that the query planner
129403 ** those objects, since there is no opportunity to add schema
129412 ** is more than the usual guess of 10 rows, since we have no way
129451 /* TUNING: Cost of full table scan is (N*3.0). */
129482 /* The cost of visiting the index rows is N*K, where K is
129487 /* If this is a non-covering index scan, add in the cost of
129528 /* If there was an INDEXED BY clause, then only that one index is
129538 ** Argument pIdxInfo is already populated with all constraints that may
129543 ** A constraint is marked usable if:
129547 ** * It is not one of the operators specified in the mExclude mask passed
129548 ** as the fourth argument (which in practice is either WO_IN or 0).
129550 ** Argument mPrereq is a mask of tables that must be scanned before the
129552 ** before it is added to pBuilder.
129554 ** Output parameter *pbIn is set to true if the plan added to pBuilder
129640 /* A virtual table that is constrained by an IN clause may not
129642 ** is not necessarily related to the order of output terms and
129686 ** pBuilder->pNew->iTab. That table is guaranteed to be a virtual table.
129689 ** mUnusable are set to 0. Otherwise, mPrereq is a mask of all FROM clause
129750 ** then there is no point in making any further calls to xBestIndex()
129752 ** implementation is sane). */
129921 /* TUNING: Currently sSum.a[i].rRun is set to the sum of the costs
129923 ** errors, it may be that the cost of the OR-scan is equal to its
129927 ** following where there is an index on "y":
129968 /* This condition is true when pItem is the FROM clause term on the
130007 ** Note that processing for WHERE_GROUPBY and WHERE_DISTINCTBY is not as
130008 ** strict. With GROUP BY and DISTINCT the only requirement is that
130024 u8 revSet; /* True if rev is known */
130050 ** We say the WhereLoop is "one-row" if it generates no more than one
130051 ** row of output. A WhereLoop is one-row if all of the following are true:
130053 ** (b) The index is unique
130054 ** Any WhereLoop with an WHERE_COLUMN_EQ constraint on the rowid is one-row.
130057 ** We say the WhereLoop is "order-distinct" if the set of columns from
130059 ** row of the WhereLoop. Every one-row WhereLoop is automatically
130061 ** is not order-distinct. To be order-distinct is not quite the same as being
130066 ** The rowid for a table is always UNIQUE and NOT NULL so whenever the
130067 ** rowid appears in the ORDER BY clause, the corresponding WhereLoop is
130097 /* Mark off any ORDER BY term X that is a column in the table of
130098 ** the current loop for which there is term in the WHERE
130175 ** WhereLoop is not well-ordered
130214 /* Make sure the sort order is compatible in an ORDER BY clause.
130215 ** Sort order is irrelevant for a GROUP BY clause. */
130274 ** If the WHERE_GROUPBY flag is set in the mask passed to sqlite3WhereBegin(),
130275 ** the planner assumes that the specified pOrderBy list is actually a GROUP
130279 ** Normally, in this case it is not possible for the caller to determine
130282 ** if the WHERE_SORTBYGROUP flag is also passed to sqlite3WhereBegin(), then
130325 /* TUNING: Estimated cost of a full external sort, where N is
130326 ** the number of rows to sort is:
130336 ** The (Y/X) term is implemented using stack variable rScale
130343 /* Multiple by log(M) where M is the number of output rows.
130344 ** Use the LIMIT for M if it is smaller */
130355 ** once. This path is then loaded into the pWInfo->a[].pWLoop fields.
130389 /* TUNING: For simple queries, only the best path is tracked.
130396 /* If nRowEst is zero and there is an ORDER BY clause, ignore it. In this
130397 ** case the purpose of this call is to estimate the number of rows returned
130420 /* If there is an ORDER BY clause and it is not being ignored, set up
130422 ** is either zero - meaning it has not yet been initialized - or the
130424 ** the ORDER BY clause are already in order, where X is the array
130435 ** of computing an automatic index is not paid back within the first 28
130441 /* If nLoop is zero, then there are no FROM terms in the query. Since
130444 ** indicate this. Or, if nLoop is greater than zero, set isOrdered to
130467 /* Do not use an automatic index if the this loop is expected
130472 /* At this point, pWLoop is a candidate to be the next loop.
130508 ** The term "((pTo->isOrdered^isOrdered)&0x80)==0" is equivalent
130525 /* The current candidate is no better than any of the mxChoice
130576 /* Control reaches here if the candidate path is better than the
130590 /* pWLoop is a winner. Add it to the set of best so far */
130755 /* TUNING: Cost of a rowid lookup is 10 */
130780 /* TUNING: Cost of a unique index lookup is 15 */
130805 ** The return value is a pointer to an opaque structure that contains
130812 ** The basic idea is to do a nested loop, one loop for each table in
130815 ** example, if the SQL is this:
130819 ** Then the code generated is conceptually like the following:
130830 ** appear in the FROM clause if a different order is better able to make
130845 ** If the WHERE clause is empty, the foreach loops must each scan their
130846 ** entire tables. Thus a three-way join is an O(N^3) operation. But if
130849 ** code will run much faster. Most of the work of this routine is checking
130855 ** loops are evaluated and if false a jump is made around all subsequent
130861 ** An outer join of tables t1 and t2 is conceptally coded as follows:
130878 ** pOrderBy is a pointer to the ORDER BY clause (or the GROUP BY clause
130879 ** if the WHERE_GROUPBY flag is set in wctrlFlags) of a SELECT statement
130880 ** if there is one. If there is no ORDER BY clause or if this routine
130881 ** is called from an UPDATE or DELETE statement, then pOrderBy is NULL.
130883 ** The iIdxCur parameter is the cursor number of an index. If
130884 ** WHERE_OR_SUBCLAUSE is set, iIdxCur is the cursor number of an index
130886 ** specific cursor. If WHERE_ONEPASS_DESIRED is set, then iIdxCur is
130888 ** be used to compute the appropriate cursor depending on which index is
130898 int iAuxArg /* If WHERE_OR_SUBCLAUSE is set, index cursor number
130933 /* Disable the DISTINCT optimization if SQLITE_DistinctOpt is set via
130939 /* The number of tables in the FROM clause is limited by the number of
130949 ** pTabList. But if the WHERE_OR_SUBCLAUSE flag is set, then we should
130956 ** return value. A single allocation is used to store the WhereInfo
130991 ** subexpression is separated by an AND operator.
130997 /* Special case: a WHERE clause that is constant. Evaluate the
131019 ** The N-th term of the FROM clause is assigned a bitmask of 1<<N.
131021 ** The rule of the previous sentence ensures thta if X is the bitmask for
131022 ** a table T, then X-1 is the bitmask for all other tables to the left of T.
131023 ** Knowing the bitmask for all tables to the left of a left join is
131027 ** pTabList, not just the first nTabList tables. nTabList is normally
131029 ** WHERE_OR_SUBCLAUSE flag is set.
131048 /* The DISTINCT marking is pointless. Ignore it. */
131163 /* If the caller is an UPDATE or DELETE statement that is requesting
131164 ** to use a one-pass algorithm, determine if this is appropriate.
131245 /* iAuxArg is always set if to a positive value if ONEPASS is possible */
131250 /* This is one term of an OR-optimization using the PRIMARY KEY of a
131424 /* The "break" point is here, just past the end of the outer loop.
131530 ** a legal notice, here is a blessing:
131542 ** interstitial "-" characters) contained in this template is changed into
131544 ** of this template is copied straight through into the generate parser
131547 ** The following is the concatenation of all %include directives from the
131574 ** into sqlite3ParserAlloc(). The default is size_t.
131583 Expr *pLimit; /* The LIMIT expression. NULL if there is no limit */
131584 Expr *pOffset; /* The OFFSET expression. NULL if there is none */
131588 ** An instance of this structure is used to store the LIKE,
131593 int bNot; /* True if the NOT keyword is present */
131598 ** TRIGGER. "a" is the event type, one of TK_UPDATE, TK_INSERT,
131599 ** TK_DELETE, or TK_INSTEAD. If the event is of the form
131644 /* This is a utility routine used to set the ExprSpan.zStart and
131676 /* If doNot is true, then add a TK_NOT Expr-node wrapper around the
131722 /* Add a single new term to an ExprList that is used to store a
131746 ** in a format understandable to "makeheaders". This section is blank unless
131747 ** "lemon" is run with the "-m" command-line option.
131751 /* The next sections is a series of control #defines.
131753 ** YYCODETYPE is the data type used to store the integer codes
131755 ** "unsigned char" is used if there are fewer than
131757 ** YYNOCODE is a number of type YYCODETYPE that is not used for
131764 ** YYACTIONTYPE is the data type used for "action codes" - numbers
131767 ** sqlite3ParserTOKENTYPE is the data type used for minor type for terminal
131768 ** symbols. Background: A "minor type" is a semantic
131776 ** YYMINORTYPE is the data type used for all minor types.
131777 ** This is typically a union of many types, one of
131778 ** which is sqlite3ParserTOKENTYPE. The entry in the union
131779 ** for terminal symbols is called "yy0".
131780 ** YYSTACKDEPTH is the maximum depth of the parser's stack. If
131781 ** zero the stack is dynamically sized using realloc()
131786 ** YYERRORSYMBOL is the code number of the error symbol. If not
131844 /* Define the yytestcase() macro to be a no-op if is not already defined
131849 ** code the yytestcase() macro should be turned off. But it is useful
131862 ** Suppose the action integer is N. Then the action is determined as
131865 ** 0 <= N <= YY_MAX_SHIFT Shift N. That is, push the lookahead
131881 ** The action table is constructed as a single large table named yy_action[].
131882 ** Given state S and lookahead X, the action is computed as
131886 ** If the index value yy_shift_ofst[S]+X is out of range or if the value
131887 ** yy_lookahead[yy_shift_ofst[S]+X] is not equal to X or if yy_shift_ofst[S]
131888 ** is equal to YY_SHIFT_USE_DFLT, it means that the action is not in the table
131891 ** The formula above is for computing the action when the lookahead is
131892 ** a terminal symbol. If the lookahead is a non-terminal (as occurs after
131893 ** a reduce action) then the yy_reduce_ofst[] array is used in place of
131894 ** the yy_shift_ofst[] array and YY_REDUCE_USE_DFLT is used in place of
132360 ** and Z. Whenever one of the tokens X, Y, or Z is input to the parser
132361 ** but it does not parse, the type of the token is changed to ID and
132362 ** the parse is retried before an error is thrown.
132477 ** + The semantic value stored at this level of the stack. This is
132479 ** It is sometimes called the "minor" token.
132487 YYCODETYPE major; /* The major token value. This is the code
132490 ** is the value of the token */
132494 /* The state of the parser is completely contained in an instance of
132524 ** and a prompt to preface each trace message. Tracing is turned off
132530 ** If NULL, then tracing is turned off.
132532 ** line of trace output. If NULL, then tracing is
132997 ** The only argument is a pointer to a function which works like
133004 ** A pointer to a parser. This pointer is used in subsequent calls
133035 ** or nonterminal. "yymajor" is the symbol code, and "yypminor" is
133037 ** deletions is derived from the %destructor and/or %token_destructor
133047 /* Here is inserted the actions which take place when a
133048 ** terminal or non-terminal is destroyed. This can happen
133049 ** when the symbol is popped from the stack during a
133050 ** reduce or during error processing or when a parser is
133051 ** being destroyed before it is finished parsing.
133139 ** If there is a destructor routine associated with the token which
133140 ** is popped from the stack, then call it.
133162 ** is defined in a %include section of the input grammar) then it is
133163 ** assumed that the input pointer is never NULL.
133288 ** The following routine is called if the stack overflows.
133299 /* Here code is inserted which will execute if the parser
133369 ** is used during the reduce.
133729 /* Check that the stack is large enough to grow by a single entry
133730 ** if the RHS of the rule is empty. This ensures that there is room
134081 /* Populate the Select.zSelName[] string that is used to help with
134085 ** If the SELECT keyword is immediately followed by a C-style comment
134087 ** comment to be the zSelName value. Otherwise, the label is #N where
134088 ** is an integer that is incremented with each SELECT statement seen.
134393 ** in the virtual machine. #N is the N-th register. */
134556 ** But, the RHS of the == or <> is marked with the EP_Generic flag
134767 "the INDEXED BY clause is not allowed on UPDATE or DELETE statements "
134774 "the NOT INDEXED clause is not allowed on UPDATE or DELETE statements "
134990 /* Here code is inserted which will be executed whenever the
135018 ** The following is executed when the parser accepts
135033 /* Here code is inserted which will be executed whenever the
135041 ** The first argument is a pointer to a structure obtained from
135043 ** The second argument is the major token number. The third is
135044 ** the minor token. The fourth optional argument is whatever the
135045 ** user wants (and specified in the grammar) and is available for
135114 ** This is what we do if the grammar does define ERROR:
135119 ** it is legal to shift the error symbol, then shift
135165 /* If the YYNOERRORRECOVERY macro is defined, then do not attempt to
135176 #else /* YYERRORSYMBOL is not defined */
135177 /* This is what we do if the grammar does not define ERROR:
135181 ** * If the input token is $, then fail the parse.
135222 ** a legal notice, here is a blessing:
135240 ** In the sqlite3GetToken() function, a switch() on aiClass[c] is implemented
135242 ** The lookup table is much faster. To maximize speed, and to ensure that
135243 ** a lookup table is used, all of the classes need to be small integers and
135318 ** lower-case ASCII equivalent. On ASCII machines, this is just
135320 ** to adjust the encoding. The mapping is only valid for alphabetics
135321 ** which are the only characters for which this feature is used.
135353 ** it is a keyword. If it is a keyword, the token code of that keyword is
135354 ** returned. If the input is not a keyword, TK_ID is returned.
135358 ** The output of the mkkeywordhash.c program is written into a file
135371 ** or not a given identifier is really an SQL keyword. The same thing
135374 ** is substantially reduced. This is important for embedded applications
135655 ** If X is a character that can be used in an identifier then
135656 ** IdChar(X) will be true. Otherwise it is false.
135658 ** For ASCII, any character with the high-order bit set is
135668 ** But the feature is undocumented.
135854 /* If the next character is a digit, this is a floating point
135936 ** but z[i] is a character not allowed within keywords, so this must
135958 /* If it is not a BLOB literal, then it must be an ID, since no
135976 ** Run the parser on the given SQL string. The parser structure is
135977 ** passed in. An SQLITE_ status code is returned. If an error occurs
135978 ** then an and attempt is made to write an error message into
136085 /* If the pParse->declareVtab flag is set, do not delete any table
136116 ** a legal notice, here is a blessing:
136134 ** This is defined in tokenize.c. We just have to import the definition.
136165 ** Special handling is require for CREATE TRIGGER statements.
136208 ** Whitespace never causes a state transition and is always ignored.
136209 ** This means that a SQL string of all whitespace is invalid.
136213 ** is look for a semicolon that is not part of an string or comment.
136221 ** statement. This is the normal case.
136237 ** used to detect the end of a statement is much simpler
136265 case '\f': { /* White space is ignored */
136376 ** This routine is the same as the sqlite3_complete() routine described
136377 ** above, except that the parameter is required to be UTF-16 encoded, not
136409 ** a legal notice, here is a blessing:
136430 ** a legal notice, here is a blessing:
136438 ** This header file is used by programs that want to link against the
136439 ** FTS3 library. All it does is declare the sqlite3Fts3Init() interface.
136463 ** a legal notice, here is a blessing:
136471 ** This header file is used by programs that want to link against the
136472 ** RTREE library. All it does is declare the sqlite3RtreeInit() interface.
136496 ** a legal notice, here is a blessing:
136504 ** This header file is used by programs that want to link against the
136505 ** ICU extension. All it does is declare the sqlite3IcuInit() interface.
136543 ** pointer to a string constant whose value is the same as the
136573 ** If the following function pointer is not NULL and if
136574 ** SQLITE_ENABLE_IOTRACE is enabled, then messages describing
136582 ** If the following global variable points to a string which is the
136591 ** If the following global variable points to a string which is the
136608 ** This routine is a no-op except on its very first call for the process,
136621 ** thread. Then while the initial invocation of this routine by X is
136622 ** incomplete, it is required that:
136645 ** combination, the work-around is to set the correct pointer
136649 /* If SQLite is already completely initialized, then this call
136656 /* Make sure the mutex subsystem is initialized. If unable to
136658 ** If the system is so sick that we are unable to allocate a mutex,
136659 ** there is not much SQLite is going to be able to do.
136668 ** This operation is protected by the STATIC_MASTER mutex. Note that
136669 ** MutexAlloc() is called for a static mutex prior to initializing the
136694 /* If rc is not SQLITE_OK at this point, then either the malloc
136710 ** The following mutex is what serializes access to the appdef pcache xInit
136711 ** methods. The sqlite3_pcache_methods.xInit() all is embedded in the
136756 /* The following is just a sanity check to make sure SQLite has
136757 ** been compiled correctly. It is important to run this code, but
136763 /* This section of code's only "output" is via assert() statements. */
136791 ** while any part of SQLite is otherwise in use in any thread. This
136792 ** routine is not threadsafe. But it is safe to invoke this routine
136793 ** on when SQLite is already shut down. If SQLite is already shut down
136794 ** when this routine is invoked, then this routine is a harmless no-op.
136826 ** heap subsystem was shutdown. This is only done if the current call to
136846 ** database connections or memory allocations. This routine is not
136854 /* sqlite3_config() shall return SQLITE_MISUSE if it is invoked while
136855 ** the SQLite library is in use. */
136908 ** single argument which is a pointer to an instance of the
136917 ** single argument which is a pointer to an instance of the
136918 ** sqlite3_mem_methods structure. The sqlite3_mem_methods structure is
136953 ** a single parameter which is a pointer to an integer and writes into
136975 ** single argument which is a pointer to an sqlite3_pcache_methods2
136983 ** single argument which is a pointer to an sqlite3_pcache_methods2
136993 /* EVIDENCE-OF: R-06626-12911 The SQLITE_CONFIG_HEAP option is only
136994 ** available if SQLite is compiled with either SQLITE_ENABLE_MEMSYS3 or
137015 ** is NULL, then SQLite reverts to using its default memory allocator
137020 ** revert to its default implementation when sqlite3_initialize() is run
137024 /* EVIDENCE-OF: R-61006-08918 If the memory pointer is not NULL then the
137025 ** alternative memory allocator is engaged to handle all of SQLites
137045 ** The default is NULL. Logging is disabled if the function pointer is
137049 /* MSVC is picky about pulling func ptrs from va lists.
137066 ** argument of type int. If non-zero, then URI handling is globally
137067 ** enabled. If the parameter is zero, then URI handling is globally
137075 ** option takes a single integer argument which is interpreted as a
137098 /* EVIDENCE-OF: R-53367-43190 If either argument to this option is
137099 ** negative, then that argument is changed to its compile-time default.
137148 ** If lookaside is already active, return SQLITE_BUSY.
137150 ** The sz parameter is the number of bytes in each lookaside slot.
137151 ** The cnt parameter is the number of slots. If pStart is NULL the
137152 ** space for the lookaside memory is obtained from sqlite3_malloc().
137153 ** If pStart is not NULL then it is sz*cnt bytes of memory to use for
137343 ** This is the default collating function named "BINARY" which is always
137346 ** If the padFlag argument is not NULL then space padding at the end
137347 ** of strings is ignored. This implements the RTRIM collation.
137365 /* EVIDENCE-OF: R-31624-24737 RTRIM is like BINARY except that extra
137380 ** This collating sequence is intended to be used for "case independent
137384 ** At the moment there is only a UTF-8 implementation.
137457 ** if this is not the last copy of the function, do not invoke it. Multiple
137458 ** copies of a single function are created when create_function() is called
137474 ** db. This is called when db is being closed.
137524 ** sqlite3_close_v2() with a NULL pointer argument is a harmless no-op. */
137538 /* If a transaction is open, the disconnectAllVtab() call above
137547 /* Legacy behavior (sqlite3_close() behavior) is to return
137559 /* Closing the handle. Fourth parameter is passed the value 2. */
137587 ** Furthermore, if database connection db is a zombie (meaning that there
137607 ** passed to sqlite3_close (meaning that it is a zombie). Therefore,
137611 /* If a transaction is open, roll it back. This also ensures that if
137613 ** they are reset. And that the required b-tree mutex is held to make
137691 /* The temp-database schema is allocated differently from the other schema
137709 ** Rollback all database files. If tripCode is not SQLITE_OK, then
137723 ** This is important in case the transaction being rolled back has
137880 /* SQLITE_BUSY */ "database is locked",
137881 /* SQLITE_LOCKED */ "database table is locked",
137886 /* SQLITE_CORRUPT */ "database disk image is malformed",
137888 /* SQLITE_FULL */ "database or disk is full",
137897 /* SQLITE_NOLFS */ "large file support is disabled",
137901 /* SQLITE_NOTADB */ "file is encrypted or is not a database",
137922 ** again until a timeout value is reached. The timeout value is
137968 ** This routine is called when an operation failed with a lock.
137969 ** If this routine returns non-zero, the lock is retried. If it
138070 ** This function is exactly the same as sqlite3_create_function(), except
138071 ** that it is designed to be called by internal code. The difference is
138073 ** is returned and the mallocFailed flag cleared.
138105 /* If SQLITE_UTF16 is specified as the encoding type, transform this
138107 ** SQLITE_UTF16NATIVE macro. SQLITE_UTF16 is not used internally.
138109 ** If SQLITE_ANY is specified, add three versions of the function
138131 /* Check if an existing function is being overridden or deleted. If so,
138133 ** is being overridden/deleted but there are no active VMs, allow the
138154 /* If an older version of the function with a configured destructor is
138263 ** this routine is a no-op. If the function does not exist, then create
138296 ** is returned.
138298 ** A NULL trace function means that no tracing is executes. A non-NULL
138299 ** trace is a pointer to a function that is invoked at the start of each
138346 ** profile function is returned.
138348 ** A NULL profile function means that no profiling is executes. A non-NULL
138349 ** profile is a pointer to a function that is invoked at the conclusion of
138350 ** each SQL statement that is run.
138402 ** Register a callback to be invoked each time a row is updated,
138427 ** Register a callback to be invoked each time a transaction is rolled
138453 ** Register a callback to be invoked each time a row is updated,
138476 ** is greater than sqlite3.pWalArg cast to an integer (the value configured by
138523 ** Register a callback to be invoked each time a transaction is written
138604 ** Checkpoint database zDb. If zDb is NULL, or if the buffer zDb points
138609 /* EVIDENCE-OF: R-41613-20553 The sqlite3_wal_checkpoint(D,X) is equivalent to
138616 ** Run a checkpoint on database iDb. This is a no-op if database iDb is
138619 ** If a transaction is open on the database being checkpointed, this
138620 ** function returns SQLITE_LOCKED and a checkpoint is not attempted. If
138621 ** an error occurs while running the checkpoint, an SQLite error code is
138625 ** associated with the specific b-tree being checkpointed is taken by
138626 ** this function while the checkpoint is running.
138628 ** If iDb is passed SQLITE_MAX_ATTACHED, then all attached databases are
138629 ** checkpointed. If an error is encountered it is returned immediately -
138630 ** no attempt is made to checkpoint any remaining databases.
138632 ** Parameter eMode is one of SQLITE_CHECKPOINT_PASSIVE, FULL or RESTART.
138757 ** above. If this is the case, then the db->mallocFailed flag needs to
138769 ** Return the most recent error code generated by an SQLite routine. If NULL is
138804 ** Create a new collating function for database "db". The name is zName
138805 ** and the encoding is enc.
138820 /* If SQLITE_UTF16 is specified as the encoding type, transform this
138822 ** SQLITE_UTF16NATIVE macro. SQLITE_UTF16 is not used internally.
138834 /* Check if this call is removing or replacing an existing collation
138939 ** If an invalid limit index is supplied, report -1.
138941 ** new limit is negative.
138958 ** there is a hard upper bound set at compile-time by a C preprocessor
138959 ** macro called SQLITE_MAX_NAME. (The "_LIMIT_" in the name is changed to
138992 ** This function is used to parse both URIs and non-URI filenames passed by the
138996 ** The first argument to this function is the name of the VFS to use (or
138999 ** itself. When this function is called the *pFlags variable should contain
139004 ** If successful, SQLITE_OK is returned. In this case *ppVfs is set to point to
139005 ** the VFS that should be used to open the database file. *pzFile is set to
139006 ** point to a buffer containing the name of the file to open. It is the
139010 ** If an error occurs, then an SQLite error code is returned and *pzErrMsg
139012 ** message. It is the responsibility of the caller to eventually release
139042 /* Make sure the SQLITE_OPEN_URI flag is set to indicate to the VFS xOpen
139057 ** file://host/path or file:////host/path. But 5 leading slashes is a
139099 /* This branch is taken when "%00" appears within the URI. In this
139240 ** is UTF-8 encoded.
139264 ** Throw an error if any non-sense combination is used. If we
139382 ** conversions. The only error that can occur here is a malloc() failure.
139396 ** strings is BINARY.
139427 /* The default safety_level for the main database is FULL; for the temp
139428 ** database it is OFF. This matches the pager layer defaults.
139441 ** database schema yet. This is delayed until the first time the database
139442 ** is accessed.
139544 /* Opening a db handle. Fourth parameter is passed 0. */
139738 ** This function is now an anachronism. It used to be used to recover from a
139747 ** Test to see whether or not the database connection is in autocommit
139748 ** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on
139749 ** by default. Autocommit is disabled by a BEGIN statement and reenabled
139771 ** a low-level error is first detected.
139803 ** This is a convenience routine that makes sure that all thread-specific
139806 ** SQLite no longer uses thread-specific data so this routine is now a
139807 ** no-op. It is retained for historical compatibility.
139826 int *pAutoinc /* OUTPUT: True if column is auto-increment */
139861 /* Find the column for which info is requested */
139887 ** and there is no explicitly declared IPK column.
139889 ** 2. The table is not a view and the column name identified an
140045 ** is an array of integers that defines the test. Return -1 on a
140059 ** Arrange to invoke xCallback() whenever sqlite3FaultSim() is called,
140060 ** if xCallback is not NULL.
140063 ** is called immediately after installing the new callback and the return
140068 /* MSVC is picky about pulling func ptrs from va lists.
140103 ** while any database connection is open results in undefined and
140121 ** assert() was enabled at compile-time. If X is true and assert()
140122 ** is enabled, then the return value is true. If X is true and
140123 ** assert() is disabled, then the return value is zero. If X is
140124 ** false and assert() is enabled, then the assertion fires and the
140125 ** process aborts. If X is false and assert() is disabled, then the
140126 ** return value is zero.
140142 ** The return value is ALWAYS(X).
140144 ** The recommended test is X==2. If the return value is 2, that means
140145 ** ALWAYS() and NEVER() are both no-op pass-through macros, which is the
140146 ** default setting. If the return value is 1, then ALWAYS() is either
140147 ** hard-coded to true or else it asserts if its argument is false.
140148 ** The first behavior (hard-coded to true) is the case if
140149 ** SQLITE_TESTCTRL_ASSERT shows that assert() is disabled and the second
140150 ** behavior (assert if the argument to ALWAYS() is false) is the case if
140151 ** SQLITE_TESTCTRL_ASSERT shows that assert() is enabled.
140158 ** // ALWAYS(x) asserts that x is true. NEVER(x) asserts x is false.
140160 ** // ALWAYS(x) is a constant 1. NEVER(x) is a constant 0.
140173 ** SQLite is running:
140202 ** argument N is a bitmask of optimizations to be disabled. For normal
140203 ** operation N should be 0. The idea is that a test program (like the
140206 ** is obtained in every case.
140217 ** If zWord is a keyword recognized by the parser, then return the
140218 ** number of keywords. Or if zWord is not a keyword, return 0.
140220 ** This test feature is only available in the amalgamation since
140221 ** the SQLITE_N_KEYWORD macro is not defined in this file if SQLite
140222 ** is built using separate source files.
140250 ** If parameter onoff is non-zero, configure the wrappers so that all
140251 ** subsequent calls to localtime() and variants fail. If onoff is zero,
140261 ** Set or clear a flag that indicates that the database file is always well-
140262 ** formed and never corrupt. This flag is clear by default, indicating that
140306 ** This test control is used to create imposter tables. "db" is a pointer
140307 ** to the database connection. dbName is the database name (ex: "main" or
140309 ** or off. "tnum" is the root page of the b-tree to which the imposter
140317 ** the schema to be reparsed the next time it is needed. This has the
140339 ** This is a utility routine, useful to VFS implementations, that checks
140343 ** The zFilename argument is the filename pointer passed into the xOpen()
140344 ** method of a VFS implementation. The zParam argument is the name of the
140376 sqlite3_int64 bDflt /* return if parameter is missing */
140418 ** Return 1 if database is read-only or 0 if read/write. Return -1 if
140521 ** a legal notice, here is a blessing:
140535 /* Omit this entire file if SQLITE_ENABLE_UNLOCK_NOTIFY is not defined. */
140553 ** is not NULL. This variable may only accessed while the STATIC_MASTER
140554 ** mutex is held.
140560 ** This function is a complex assert() that verifies the following
140569 ** 3) If the argument db is not NULL, then none of the entries in the
140571 ** set to db. This is used when closing connection db.
140597 ** db is not currently a part of the list, this function is a no-op.
140611 ** Add connection db to the blocked connections list. It is assumed
140612 ** that it is not already a part of the list.
140646 ** This is called after connection "db" has attempted some operation
140649 ** cache. pOther is found by looking at db->pBlockingConnection.
140651 ** If there is no blocking connection, the callback is invoked immediately,
140654 ** If pOther is already blocked on db, then report SQLITE_LOCKED, to indicate
140703 sqlite3ErrorWithMsg(db, rc, (rc?"database is deadlocked":0));
140709 ** This function is called while stepping or preparing a statement
140724 ** This function is called when
140731 ** 1) If the sqlite3.pBlockingConnection member of a list entry is
140734 ** 2) If the sqlite3.pUnlockConnection member of a list entry is
140784 ** be passed to the unlock-notify callback is larger than the
140788 ** This is a difficult situation to handle. Returning an error
140789 ** code to the caller is insufficient, as even if an error code
140790 ** is returned the transaction on connection db will still be
140799 ** requiring any dynamic allocation. This is sub-optimal because
140804 ** connections. But it is the best that can be done under the
140838 ** This is called when the database connection passed as an argument is
140839 ** being closed. The connection is removed from the blocked list.
140856 ** a legal notice, here is a blessing:
140864 ** This is an SQLite module implementing full-text search.
140868 ** The code in this file is only compiled if:
140870 ** * The FTS3 module is being built as an extension
140871 ** (in which case SQLITE_CORE is not defined), or
140873 ** * The FTS3 module is being built into the core of
140874 ** SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
140877 /* The full-text index is stored in a series of b+tree (-like)
140886 ** The basic unit of encoding is a variable-length integer called a
140899 ** This is similar in concept to how sqlite encodes "varints" but
140900 ** the encoding is not the same. SQLite varints are big-endian
140914 ** A docid is the unique integer identifier for a single document.
140915 ** A position is the index of a word within the document. The first
140919 ** option. But that functionality is no longer supported.
140921 ** A doclist is stored like this:
140939 ** memory. A "position" is an index of a token in the token stream
140942 ** ending a position list array. POS_END is 0. POS_COLUMN is 1.
140950 ** The 123 value is the first docid. For column zero in this document
140953 ** new column is column number 1. There are two positions at 12 and 45
140955 ** 234 at I is the delta to next docid (357). It has one position 70
140958 ** A "position-list" is the list of positions for multiple columns for
140959 ** a single docid. A "column-list" is the set of positions for a single
140993 ** of a node is reached, the next term is in the node with the next
140996 ** New data is spilled to a new leaf node when the current node
140997 ** exceeds LEAF_MAX bytes (default 2048). New data which itself is
140998 ** larger than STANDALONE_MIN (default 1024) is placed in a standalone
141000 ** these settings is to pack together groups of small doclists while
141002 ** assumption is that large doclists represent terms which are more
141007 ** node rather than splitting into 2k and .5k nodes. My intuition is
141013 ** to describe what data is stored by the each subtree. Interior
141038 ** is encoded. The subtree at iBlockid will contain all terms less
141039 ** than the first term encoded (or all terms if no term is encoded).
141044 ** child is "something", and the leftmost term of the right child is
141045 ** "wicked", only "w" is stored).
141047 ** New data is spilled to a new interior node at the same height when
141060 ** The root node is the top node of the segment's tree after encoding
141063 ** node requires more than ROOT_MAX bytes, it is flushed to %_segments
141064 ** and a new root interior node is generated (which should always fit
141068 ** The meta-information in the segment directory is:
141077 ** If the root node is a leaf node, then start_block,
141090 ** is populated like level 0, and eventually MERGE_COUNT level 1
141105 ** sorting). 8 is about 20% slower than 16, 4 about 50% slower than
141124 ** argument for MERGE_COUNT of 16. Also, it is possible/likely that
141133 ** index when a document is deleted or updated. For deletions, we
141148 ** a legal notice, here is a blessing:
141171 ** FTS4 is really an extension for FTS3. It is enabled using the
141199 ** sqlite3_tokenizer_module is a singleton defining the tokenizer
141200 ** interface functions. This is essentially the class structure for
141203 ** sqlite3_tokenizer is used to define a particular tokenizer, perhaps
141206 ** sqlite3_tokenizer_cursor is generated by a tokenizer to generate
141220 ** implementation is registered, the caller provides a pointer to
141224 ** When an fts3 table is created, it passes any arguments passed to
141232 ** method is called. It returns an sqlite3_tokenizer_cursor object
141252 ** the following SQL is executed:
141256 ** then argc is set to 2, and the argv[] array contains pointers
141260 ** code. If SQLITE_OK is returned, then *ppTokenizer should be set
141279 ** is responsible for ensuring that the input buffer remains valid
141280 ** until the cursor is closed (using the xClose() method).
141303 ** of this buffer in bytes. The input text that generated the token is
141310 ** The buffer *ppToken is set to point at is managed by the tokenizer
141311 ** implementation. It is only required to be valid until the next call
141360 ** a legal notice, here is a blessing:
141367 ** This is the header file for the generic hash-table implementation
141379 /* A complete hash table is an instance of the following structure.
141399 /* Each element in the hash table is an instance of the following
141402 ** Again, this structure is intended to be opaque, but it can't really
141403 ** be opaque because it is used by macros.
141414 ** FTS3_HASH_STRING pKey points to a string that is nKey bytes long
141416 ** is respected in comparisons.
141419 ** memcmp() is used to compare keys.
141421 ** A copy of the key is made if the copyKey parameter to fts3HashInit is 1.
141445 ** Macros for looping over all elements of a hash table. The idiom is
141476 ** limit is that it may allow very large queries to use large amounts
141492 ** This is the maximum amount of data (in bytes) to store in the
141493 ** Fts3Table.pendingTerms hash table. Normally, the hash table is
141495 ** and used to create a new segment when the transaction is committed.
141496 ** However if this limit is reached midway through a transaction, a new
141497 ** segment is created and the hash table cleared immediately.
141517 ** Maximum length of a varint encoded integer. The varint format is different
141518 ** from that used by SQLite, so the maximum length is 10, not 9.
141527 ** It is possible to determine which index a b+-tree belongs to based on the
141529 ** that the b+-tree belongs to is (L<<10). In other words, all b+-trees with
141533 ** It is considered impossible for an index to use more than 1024 levels. In
141541 ** The testcase() macro is only used by the amalgamation. If undefined,
141592 ** Activate assert() only if SQLITE_TEST is enabled.
141599 ** The TESTONLY macro is used to enclose variable declarations or
141633 ** A connection to a fulltext index is an instance of the following
141654 ** statements is run and reset within a single virtual table API call.
141672 ** The following array of hash tables is used to buffer pending index
141675 ** The current language id is stored in variable iPrevLangid.
141678 ** there is an entry in the aIndex[] array. Index 0 is an index of all the
141680 ** is an index of prefixes of a specific length.
141685 ** tables are flushed to disk. Variable iPrevDocid is the docid of the most
141710 /* True to disable the incremental doclist optimization. This is controled
141750 ** The Fts3Cursor.eSearch member is always set to one of the following.
141752 ** FTS3_FULLTEXT_SEARCH. If so, then Fts3Cursor.eSearch - 2 is the index
141758 ** Because the LHS of the MATCH operator is 2nd column "b",
141790 ** A "phrase" is a sequence of one or more tokens that must match in
141791 ** sequence. A single token is the base case and the most common case.
141801 /* Variables above this point are populated when the expression is
141811 int bIncr; /* True if doclist is loaded incrementally */
141814 /* Used by sqlite3Fts3EvalPhrasePoslist() if this is a descendent of an
141820 ** a MATCH expression. Everything above is part of the evaluation phase.
141830 ** If Fts3Expr.eType is FTSQUERY_PHRASE and isLoaded is true, then aDoclist
141833 ** "Length" field found in doclists stored on disk is omitted from this
141836 ** Variable aMI is used only for FTSQUERY_NEAR nodes to store the global
141837 ** matchinfo data. If it is not NULL, it points to an array of size nCol*3,
141838 ** where nCol is the number of columns in the queried FTS table. The array
141839 ** is populated as follows:
141845 ** The aMI array is allocated using sqlite3_malloc(). It should be freed
141846 ** when the expression node is.
141858 u8 bEof; /* True this expression is at EOF already */
141859 u8 bStart; /* True if iDocid is valid */
141860 u8 bDeferred; /* True if this expression is entirely deferred */
141869 ** four values is in order of precedence when parsing expressions. For
141874 ** is equivalent to:
142079 ** The number of bytes written is returned.
142103 ** The value is stored in *v.
142127 ** Similar to sqlite3Fts3GetVarint(), except that the output is truncated to a
142128 ** 32-bit integer before it is returned.
142162 ** the quote characters. The conversion is done in-place. If the
142164 ** is a no-op.
142182 /* If the first byte was a '[', then the close-quote character is a ']' */
142210 ** When this function is called, *pp points to the first byte following a
142211 ** varint that is part of a doclist (or position-list, or any other list
142216 ** varint is part of.
142227 ** interested in. So, unless the doclist is corrupt, the 0x80 bit is
142277 ** and then evaluate those statements. The success code is written
142280 ** If *pRc is initially non-zero then this routine is a no-op.
142330 ** passed as the first argument. This is done as part of the xConnect()
142333 ** If *pRc is non-zero when this function is called, it is a no-op.
142334 ** Otherwise, if an error occurs, an SQLite error code is stored in *pRc
142385 ** required by the FTS3 table passed as the only argument. This is done
142388 ** If the p->bHasDocsize boolean is true (indicating that this is an
142453 ** If *pRc is non-zero when this function is called, it is a no-op.
142454 ** Otherwise, if an error occurs, an SQLite error code is stored in *pRc
142546 ** is the callers responsibility to call sqlite3_free() to release this
142575 ** from left to write. If parameter zFunc is not NULL, then instead of
142576 ** being returned directly each column of text data is passed to an SQL
142577 ** function named zFunc first. For example, if zFunc is "unzip" and the
142579 ** string is returned:
142584 ** is the responsibility of the caller to eventually free it.
142586 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op (and
142587 ** a NULL pointer is returned). Otherwise, if an OOM error is encountered
142588 ** by this function, NULL is returned and *pRc is set to SQLITE_NOMEM. If
142589 ** no error occurs, *pRc is left unmodified.
142629 ** Return a list of N comma separated question marks, where N is the number
142633 ** If argument zFunc is not NULL, then all but the first question mark
142634 ** is preceded by zFunc and an open bracket, and followed by a closed
142635 ** bracket. For example, if zFunc is "zip" and the FTS3 table has three
142636 ** user-defined text columns, the following string is returned:
142641 ** is the responsibility of the caller to eventually free it.
142643 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op (and
142644 ** a NULL pointer is returned). Otherwise, if an OOM error is encountered
142645 ** by this function, NULL is returned and *pRc is set to SQLITE_NOMEM. If
142646 ** no error occurs, *pRc is left unmodified.
142678 ** If *pp does not being with a decimal digit SQLITE_ERROR is returned and
142679 ** the output value undefined. Otherwise SQLITE_OK is returned.
142681 ** This function is used when parsing the "prefix=" FTS4 parameter.
142702 ** This function is called to allocate an array of Fts3Index structures
142708 ** Argument zParam is passed the value of the "prefix=" option if one was
142711 ** If no error occurs, SQLITE_OK is returned and *apIndex set to point to
142712 ** the allocated array. *pnIndex is set to the number of elements in the
142713 ** array. If an error does occur, an SQLite error code is returned.
142715 ** Regardless of whether or not an error is returned, it is the responsibility
142763 ** This function is called when initializing an FTS4 table that uses the
142767 ** The third argument passed to this function is the value passed to the
142777 ** *pazCol: Set to point to an array of *pnCol strings. Each string is
142780 ** is the responsibility of the caller to free this allocation
142783 ** If the table cannot be found, an error code is returned and the output
142784 ** variables are undefined. Or, if an OOM is encountered, SQLITE_NOMEM is
142852 ** This function is the implementation of both the xConnect and xCreate
142930 ** + If there is a tokenizer specification included in the arguments,
142938 /* Check if this is a tokenizer specification */
142947 /* Check if it is an FTS4 special argument. */
143037 /* Otherwise, the argument is a column name. */
143190 /* If this is an xCreate call, create the underlying tables in the
143204 /* Figure out the page-size for the database. This is required in order to
143237 ** work is done in function fts3InitVtab().
143262 ** extension is currently being used by a version of SQLite too old to
143263 ** support estimatedRows. In that case this function is a no-op.
143275 ** extension is currently being used by a version of SQLite too old to
143276 ** support index-info flags. In that case this function is a no-op.
143304 /* By default use a full table scan. This is an expensive option,
143306 ** strategy is possible.
143311 int bDocid; /* True if this constraint is on docid */
143339 ** If there is more than one MATCH constraint available, use the first
143340 ** one encountered. If there is both a MATCH constraint and a direct
143341 ** rowid/docid lookup, prefer the MATCH strategy. This is done even
143342 ** though the rowid/docid lookup is faster than a MATCH query, selecting
143479 ** Position the pCsr->pStmt statement so that it is on the row
143498 ** table is missing a row that is present in the full-text index.
143514 ** This function is used to process a single interior node when searching
143515 ** a b-tree for a term or term prefix. The node data is passed to this
143516 ** function via the zNode/nNode parameters. The term to search for is
143519 ** If piFirst is not NULL, then this function sets *piFirst to the blockid
143522 ** If piLast is not NULL, then *piLast is set to the right-most child node
143523 ** that heads a sub-tree that may contain a term for which zTerm/nTerm is
143526 ** If an OOM error occurs, SQLITE_NOMEM is returned. Otherwise, SQLITE_OK.
143548 ** Even if the data structure on disk is corrupted, this (reading two
143549 ** varints from the buffer) does not risk an overread. If zNode is a
143553 ** contents, or two zero bytes. Or, if the node is read from the %_segments
143597 ** the interior node. If the specified term is greater than or equal
143602 ** If the interior node term is larger than the specified term, then
143633 ** or terms for which the specified term is a prefix.
143635 ** If piLeaf is not NULL, then *piLeaf is set to the blockid of the
143637 ** If piLeaf2 is not NULL, then *piLeaf2 is set to the blockid of the
143639 ** term is a prefix.
143641 ** It is possible that the range of returned leaf nodes does not contain
143642 ** the specified term or any terms for which it is a prefix. However, if the
143645 ** never loads leaf nodes into memory), it is not possible to be sure.
143647 ** If an error occurs, an error code other than SQLITE_OK is returned.
143694 ** This function is used to create delta-encoded serialized lists of FTS3
143708 ** When this function is called, *ppPoslist is assumed to point to the
143712 ** A position list is list of positions (delta encoded) and columns for
143717 ** If pp is not NULL, then the contents of the position list are copied
143718 ** to *pp. *pp is set to point to the first byte past the last byte copied
143725 /* The end of a position list is marked by a zero encoded as an FTS3
143726 ** varint. A single POS_END (0) byte. Except, if the 0 byte is preceded by
143727 ** a byte with the 0x80 bit set, then it is not a varint 0, but the tail
143730 ** The following while-loop moves pEnd to point to the first byte that is not
143752 ** When this function is called, *ppPoslist is assumed to point to the
143756 ** A column-list is list of delta-encoded positions for a single column
143759 ** The column-list is terminated either by a POS_COLUMN varint (1) or
143763 ** If pp is not NULL, then the contents of the column-list are copied
143764 ** to *pp. *pp is set to point to the first byte past the last byte copied
143766 ** is not copied into *pp.
143772 /* A column-list is terminated by either a 0x01 or 0x00 byte that is
143790 ** Value used to signify the end of an position-list. This is safe because
143791 ** it is not possible to have a document with 2^31 terms.
143796 ** This function is used to help parse position-lists. When this function is
143810 ** of the previous position is needed in order to compute the value of
143826 ** If parameter iCol is not 0, write an POS_COLUMN (1) byte followed by
143849 ** updated appropriately. The caller is responsible for insuring
143850 ** that there is enough space in *pp to hold the complete output.
143883 ** A column-list is a list of non-negative delta-encoded varints, each
143884 ** incremented by 2 before being stored. Each list is terminated by a
143886 ** and writes the results to buffer p. p is left pointing to the byte
143887 ** after the list written. No terminator (POS_END or POS_COLUMN) is
143920 ** This function is used to merge two position lists into one. When it is
143921 ** called, *pp1 and *pp2 must both point to position lists. A position-list is
143934 ** If isSaveLeft is 0, an entry is added to the output position list for
143946 int isExact, /* If *pp1 is exactly nTokens before *pp2 */
144063 ** The output position list - written to *pp - is a copy of *pp2 with those
144101 ** An instance of this function is used to merge together the (potentially
144112 ** This function is used to read a single varint from a buffer. Parameter
144113 ** pEnd points 1 byte past the end of the buffer. When this function is
144115 ** has been reached. In this case *pp is set to 0 and the function returns.
144117 ** If *pp does not point to or past pEnd, then a single varint is read
144118 ** from *pp. *pp is then set to point 1 byte past the end of the read varint.
144120 ** If bDescIdx is false, the value read is added to *pVal before returning.
144121 ** If it is true, the value read is subtracted from *pVal before this
144144 ** This function is used to write a single varint to a buffer. The varint
144145 ** is written to *pp. Before returning, *pp is set to point 1 byte past the
144148 ** If *pbFirst is zero when this function is called, the value written to
144149 ** the buffer is that of parameter iVal.
144151 ** If *pbFirst is non-zero when this function is called, then the value
144152 ** written is either (iVal-*piPrev) (if bDescIdx is zero) or (*piPrev-iVal)
144153 ** (if bDescIdx is non-zero).
144180 ** This macro is used by various functions that merge doclists. The two
144182 ** bDescDoclist is 0 when this macro is invoked, then it returns (i1-i2).
144197 ** If no error occurs, *paOut is set to point at an sqlite3_malloc'd buffer
144198 ** containing the output doclist and SQLITE_OK is returned. In this case
144199 ** *pnOut is set to the number of bytes in the output doclist.
144201 ** If an error occurs, an SQLite error code is returned. The output values
144226 ** then the first docid in each list is simply encoded as a varint. For
144227 ** each subsequent docid, the varint stored is the difference between the
144228 ** current and previous docid (a positive number - since the list is in
144231 ** The first docid written to the output is therefore encoded using the
144232 ** same number of bytes as it is in whichever of the input lists it is
144241 ** However, if the first docid copied to the output is a negative number,
144246 ** The space required to store the output is therefore the sum of the
144287 ** doclist for which there is a position in the left-hand input doclist
144294 ** The right-hand input doclist is overwritten by this function.
144365 ** The value returned is the number of bytes written to pOut (if any).
144415 ** If an OOM error occurs, return SQLITE_NOMEM. In this case it is
144461 ** as the first argument. The merge is an "OR" merge (see function
144464 ** This function is called with the doclist for each term that matches
144467 ** doclists to merge, the merging is done pair-wise using the TermSelect
144470 ** This function returns SQLITE_OK if the merge is successful, or an
144480 /* If this is the first term selected, copy the doclist to the output
144484 ** allocation. This is so as to ensure that the buffer is big enough
144487 ** required (since the size of [doclistA AND doclistB] is always less
144488 ** than or equal to the size of [doclistA] in that case). But this is
144494 ** Similar padding is added in the fts3DoclistOrMerge() function.
144585 /* If iLevel is less than 0 and this is not a scan, include a seg-reader
144586 ** for the pending-terms. If this is a scan, then this call must be being
144614 /* If zTerm is not NULL, and this segment is not stored entirely on its
144674 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
144690 ** if isPrefix is true, to scan the doclist for all terms for which
144691 ** zTerm/nTerm is a prefix. If successful, return SQLITE_OK and write
144695 ** It is the responsibility of the caller to free this object by eventually
144698 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
144699 ** Output parameter *ppSegcsr is set to 0 if an error occurs.
144819 ** If the isPoslist argument is true, then it is assumed that the doclist
144820 ** contains a position-list following each docid. Otherwise, it is assumed
144821 ** that the doclist is simply a list of docids stored as delta encoded
144846 ** Return SQLITE_OK if nothing goes wrong. SQLITE_OK is returned
144881 ** If the numeric type of argument pVal is "integer", then return it
144896 ** This is the xFilter interface for the virtual table. See
144907 ** column on the left-hand side of the MATCH operator is column
144908 ** number idxNum-FTS3_FULLTEXT_SEARCH, 0 indexed. argv[0] is the right-hand
145025 ** This is the xEof method of the virtual table. SQLite calls this
145033 ** This is the xRowid method. The SQLite core calls this routine to
145045 ** This is the xColumn method, called by SQLite to request a value from
145068 /* This call is a request for the "docid" column. Since "docid" is an
145073 /* The extra column whose name is the same as the table.
145074 ** Return a blob which is a pointer to the cursor. */
145079 /* The requested column is either a user column (one that contains
145101 ** This function is the implementation of the xUpdate callback used by
145102 ** FTS3 virtual tables. It is invoked by SQLite each time a row is to be
145125 ** if the height of the input segment b-trees is N, and input segments
145127 ** of an incremental-merge requires writing (8*(1+N)) blocks. N is usually
145129 ** merge is somewhere between 8 and 24 blocks. To avoid this overhead
145131 ** is only attempted if it will write at least 64 leaf blocks. Hence
145135 ** of blocks from the segments table. But this is not considered overhead
145162 ** If it is currently unknown whether or not the FTS table has an %_stat
145204 ** Implementation of xCommit() method. This is a no-op. The contents of
145246 ** poslist). This is an 0x00 byte preceded by some byte that does not
145257 ** Normally. The other case is that p==pStart and the poslist to return
145258 ** is the first in the doclist. In this case do not skip forward 2 bytes.
145260 ** is required for cases where the first byte of a doclist and the
145261 ** doclist is empty. For example, if the first docid is 10, a doclist
145275 ** If the value passed as the third argument is a blob of size
145277 ** output variable *ppCsr and SQLITE_OK is returned. Otherwise, an error
145278 ** message is written to context pContext and SQLITE_ERROR returned. The
145279 ** string passed via zFunc is used as part of the error message.
145367 ** Example usage is:
145371 ** where 't' is the name of an FTS3 table.
145475 /* As it happens, the pending terms table is always empty here. This is
145536 ** This is a no-op.
145590 ** This function is registered as the module destructor (called when an
145591 ** FTS3 enabled database connection is closed). It frees the memory
145620 ** Initialize the fts3 extension. If this extension is built as part
145621 ** of the sqlite library, then this function is called directly by
145622 ** SQLite. If fts3 is built as a dynamically loadable extension, this
145623 ** function is called by the sqlite3_extension_init() entry point.
145685 ** the two scalar functions. If this is successful, register the
145724 ** An Fts3SegReader object is a cursor that can seek or scan a range of
145730 ** segment b-tree (if the term is not a prefix or it is a prefix for which
145769 ** It is merged into the main doclist stored in p->doclist.aAll/nAll.
145775 ** SQLITE_OK is returned if successful, or SQLITE_NOMEM if an error occurs.
145839 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
145868 ** This function is called on each phrase after the position lists for
145875 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
145978 ** This function is called for each Fts3Phrase in a full-text query
145983 ** If parameter bOptOk is true, then the phrase may (or may not) use the
145984 ** incremental loading strategy. Otherwise, the entire doclist is loaded into
145987 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
145994 /* Determine if doclists may be loaded from disk incrementally. This is
145995 ** possible if the bOptOk argument is true, the FTS doclists will be
146037 ** This function is used to iterate backwards (from the end to start)
146038 ** through doclists. It is used by this module to iterate through phrase
146047 int bDescIdx, /* True if the doclist is desc */
146103 int bDescIdx, /* True if the doclist is desc */
146137 ** to true if EOF is reached.
146194 ** Token pToken is an incrementally loaded token that is part of a
146207 u8 *pbEof /* OUT: True if iterator is at EOF */
146247 ** If there is no "next" entry and no error occurs, then *pbEof is set to
146248 ** 1 before returning. Otherwise, if no error occurs and the iterator is
146249 ** successfully advanced, *pbEof is set to 0.
146264 /* This is only called if it is guaranteed that the phrase has at least
146265 ** one incremental token. In which case the bIncr flag is set. */
146350 ** If there is no "next" entry and no error occurs, then *pbEof is set to
146351 ** 1 before returning. Otherwise, if no error occurs and the iterator is
146352 ** successfully advanced, *pbEof is set to 0.
146379 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
146380 ** Otherwise, fts3EvalPhraseStart() is called on all phrases within the
146381 ** expression. Also the Fts3Expr.bDeferred variable is set to true for any
146384 ** If parameter bOptOk is zero, then it is guaranteed that the
146387 ** Or, if bOptOk is non-zero, then one or more tokens within the expression
146388 ** may be loaded incrementally, meaning doclist.aAll/nAll is not available.
146390 ** If an error occurs within this function, *pRc is set to an SQLite error
146418 ** An array of the following structures is assembled as part of the process
146420 ** of the xFilter() method). There is one element in the array for each
146425 ** NOT). When determining tokens to defer, each AND/NEAR cluster is considered
146426 ** separately. The root of a tokens AND/NEAR cluster is stored in
146440 ** This function is used to populate an allocated Fts3TokenAndCost array.
146442 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
146443 ** Otherwise, if an error occurs during execution, *pRc is set to an
146494 ** The average document size in pages is calculated by first calculating
146495 ** determining the average size in bytes, B. If B is less than the amount
146497 ** this database, then the average docsize is 1. Otherwise, it is 1 plus
146502 /* The average document size, which is required to calculate the cost
146506 ** Entry 0 of the %_stat table is a blob containing (nCol+1) FTS3
146507 ** varints, where nCol is the number of columns in the FTS3 table.
146508 ** The first varint is the number of documents currently stored in
146548 ** This function is called to select the tokens (if any) that will be
146549 ** deferred. The array aTC[] has already been populated when this is
146552 ** This function is called once for each AND/NEAR cluster in the
146557 ** If no error occurs, SQLITE_OK is returned and sqlite3Fts3DeferToken()
146558 ** called on each token to defer. Otherwise, an SQLite error code is
146578 ** option. The reason being that it is not guaranteed that the content
146580 ** causing any problems, the deferred token optimization is completely
146587 ** associated with the tokens spill onto overflow pages, or if there is
146612 ** After each token doclist is loaded, merge it with the others from the
146616 ** Let nOther be the number of other phrases for which it is certain that
146620 ** loading N or more overflow pages into memory, where N is computed as:
146640 ** subsequent) tokens is greater than the estimated number of pages
146650 ** overflowing the 32-bit integer it is stored in. */
146654 /* Either this is the cheapest token in the entire query, or it is
146683 ** This function is called from within the xFilter method. It initializes
146754 ** This function is called to edit the position list associated with
146760 ** Parameter nNear is passed the NEAR distance of the expression (5 in
146761 ** the example above). When this function is called, *paPoslist points to
146762 ** the position list, and *pnToken is the number of phrase tokens in, the
146769 ** leaves 0 positions, zero is returned. Otherwise, non-zero.
146771 ** Before returning, *paPoslist is set to point to the position lsit
146772 ** associated with pPhrase. And *pnToken is set to the number of tokens in
146809 ** This function is a no-op if *pRc is other than SQLITE_OK when it is called.
146812 ** matching rows in docid order. Ascending order if Fts3Cursor.bDesc is zero,
146813 ** or descending if it is non-zero.
146815 ** If an error occurs, *pRc is set to an SQLite error code. Otherwise, if
146818 ** Fts3Expr.bEof (non-zero if EOF - there is no next row)
146821 ** If the expression is of type FTSQUERY_PHRASE, and the expression is not
146829 ** matching row. This is usually true, but there are the following exceptions:
146832 ** entirely of deferred tokens, it is assumed to match every row in
146833 ** the db. In this case the position-list is not populated at all.
146836 ** more non-deferred tokens, then the expression is advanced to the
146838 ** words, if the phrase is "A B C", and "B" is deferred, the expression
146839 ** is advanced to the next row that contains an instance of "A * C",
146841 ** is populated as for "A * C" before returning.
146843 ** 2. NEAR is treated as AND. If the expression is "x NEAR y", it is
146846 ** See sqlite3Fts3EvalTestDeferred() for details on testing if a row is
146867 /* LHS is entirely deferred. So we assume it matches every row.
146873 /* RHS is entirely deferred. So we assume it matches every row.
146976 ** If *pRc is not SQLITE_OK, or if pExpr is not the root node of a NEAR
146983 ** If the current row is a match, the position list associated with each
146984 ** phrase in the NEAR expression is edited in place to contain only those
146987 ** match the current row, 0 is returned. The position lists may or may not
146988 ** be edited if 0 is returned.
146993 /* The following block runs if pExpr is the root of a NEAR query.
146998 ** which is represented in tree form as:
147009 ** The right-hand child of a NEAR node is always a phrase. The
147066 ** This function is a helper function for sqlite3Fts3EvalTestDeferred().
147071 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
147072 ** If an error occurs during execution of this function, *pRc is set to
147073 ** the appropriate SQLite error code. In this case the returned value is
147093 ** all phrases involved in the NEAR. This is because the snippet(),
147100 ** is matched against a row containing:
147105 ** (as "b" is part of a non-matching NEAR clause).
147164 ** This function is called as the second part of each xNext operation when
147174 ** If *pRc is not SQLITE_OK when this function is called, it immediately
147176 ** operators and deferred tokens the current row is still a match for the
147179 ** 1. *pRc is SQLITE_OK when this function returns, and
147182 ** it is determined that the row does *not* match the query.
147194 ** token. Then, see if this row is really a match, considering deferred
147237 /* Check if the cursor is past the end of the docid range specified
147254 ** If *pRc is other than SQLITE_OK when this function is called, it is
147255 ** a no-op. If an error occurs within this function, *pRc is set to an
147336 ** If it is not already allocated and populated, this function allocates and
147337 ** populates the Fts3Expr.aMI[] array for expression pExpr. If pExpr is part
147341 ** SQLITE_OK is returned if the aMI[] array is successfully allocated and
147342 ** populated. Otherwise, if an error occurs, an SQLite error code is returned.
147383 /* Ensure the %_content statement is reset. */
147426 ** This function is used by the matchinfo() module to query a phrase
147435 ** If no error occurs, SQLITE_OK is returned and the values for each column
147452 ** * If the phrase is part of a NEAR expression, then only phrase instances
147488 ** The returned value is either NULL or a pointer to a buffer containing
147494 ** compression and is terminated by either an 0x01 or 0x00 byte. For example,
147496 ** for 'X' is requested, the buffer returned may contain:
147500 ** This function works regardless of whether or not the phrase is deferred,
147515 /* If this phrase is applies specifically to some column other than
147537 ** tree that the node is part of has been marked as EOF, but the node
147538 ** itself is not EOF, then it may point to an earlier entry. */
147547 /* This is the descendent of an OR node. In this case we cannot use
147685 ** a legal notice, here is a blessing:
147715 int isEof; /* True if cursor is at EOF */
147997 ** The only difference between state 1 and state 2 is that if the
147998 ** integer encountered in state 1 is not 0 or 1, then we need to
148020 /* State 3. The integer just read is a column number. */
148084 /* In case this cursor is being reused, close and zero it. */
148134 ** xEof - Return true if the cursor is at EOF, or false otherwise.
148238 ** a legal notice, here is a blessing:
148248 ** syntax is relatively simple, the whole tokenizer/parser system is
148257 ** is defined, then it uses the new syntax. The differences between
148264 ** c) The old syntax supports the "-" token qualifier. This is not
148265 ** supported by the new syntax (it is replaced by the NOT operator).
148273 ** to zero causes the module to use the old syntax. If it is set to
148274 ** non-zero the new syntax is activated. This is so both syntaxes can
148319 ** This variable is used by function getNextNode(). When getNextNode() is
148320 ** called, it sets ParseContext.isNot to true if the 'next node' is a
148322 ** FTS3 query "sqlite -mysql". Otherwise, ParseContext.isNot is set to
148339 ** This function is equivalent to the standard isspace() function.
148342 ** is defined to accept an argument of type int, its behavior when passed
148344 ** is undefined (and sometimes, "undefined" means segfault). This wrapper
148345 ** is defined to accept an argument of type char, and always returns 0 for
148392 ** Function getNextNode(), which is called by fts3ExprParse(), may itself
148393 ** call fts3ExprParse(). So this forward declaration is required.
148401 ** single token and set *ppExpr to point to it. If the end of the buffer is
148402 ** reached before a token is found, set *ppExpr to zero. It is the
148499 ** is included in the buffer. This function attempts to tokenize the entire
148503 ** If successful, SQLITE_OK is returned and *ppExpr set to point at the
148505 ** error) or SQLITE_ERROR (tokenization error) is returned and *ppExpr set
148619 ** The output variable *ppExpr is populated with an allocated Fts3Expr
148620 ** structure, or set to 0 if the end of the input buffer is reached.
148623 ** if a malloc failure occurs, or SQLITE_ERROR if a parse error is encountered.
148624 ** If SQLITE_ERROR is returned, pContext is populated with an error message.
148678 /* If this is a "NEAR" keyword, check for an explicit nearness. */
148689 /* At this point this is probably a keyword. But for that to be true,
148714 /* See if we are dealing with a quoted phrase. If this is the case, then
148716 ** for processing. This is easy to do, as fts3 has no syntax for escaping
148746 ** interface. Before doing so, figure out if there is an explicit
148749 ** TODO: Strangely, it is not possible to associate a column specifier
148774 ** The argument is an Fts3Expr structure for a binary operator (any type
148781 ** is defined), the order of the operators in precedence from highest to
148782 ** lowest is:
148807 ** expression tree being parsed. pPrev is the expression node most recently
148808 ** inserted into the tree. This function adds pNew, which is always a binary
148811 ** of the tree changing, in which case *ppHead is set to the new root node.
148836 ** returns either when the end of the buffer is reached or an unmatched
148837 ** closing bracket - ')' - is encountered.
148839 ** If successful, SQLITE_OK is returned, *ppExpr is set to point to the
148840 ** parsed form of the expression and *pnConsumed is set to the number of
148841 ** bytes read from buffer z. Otherwise, *ppExpr is set to 0 and SQLITE_NOMEM
148842 ** (out of memory error) or SQLITE_ERROR (parse error) is returned.
148891 /* The isRequirePhrase variable is set to true if a phrase or
148892 ** an expression contained in parenthesis is required. If a
148893 ** binary operator (AND, OR, NOT or NEAR) is encounted when
148894 ** isRequirePhrase is set, this is a syntax error.
148991 ** as the only argument is more than nMaxDepth.
149010 ** an equivalent but more balanced form. The tree is modified in place.
149011 ** If successful, SQLITE_OK is returned and (*pp) set to point to the
149014 ** nMaxDepth is the maximum allowable depth of the balanced sub-tree.
149016 ** Otherwise, if an error occurs, an SQLite error code is returned and
149132 ** and pFree list. Everything else is cleaned up by the call to
149183 ** This function is similar to sqlite3Fts3ExprParse(), with the following
149236 ** parsed expression. If successful, *ppExpr is set to point to the head
149237 ** of the parsed expression tree and SQLITE_OK is returned. If an error
149239 ** error) is returned and *ppExpr is set to 0.
149241 ** If parameter n is a negative number, then z is assumed to point to a
149242 ** nul-terminated string and the length is determined using strlen().
149244 ** The first parameter, pTokenizer, is passed the fts3 tokenizer module to
149246 ** array, which is assumed to contain nCol entries, should contain the names
149252 ** column to match against for tokens for which a column name is not explicitly
149285 "FTS expression tree is too large (maximum depth %d)",
149337 ** Everything after this point is just test code.
149374 ** expression passed as the first argument. The buffer is obtained from
149375 ** sqlite3_malloc(). It is the responsibility of the caller to use
149376 ** sqlite3_free() to release the memory. If an OOM condition is encountered,
149377 ** NULL is returned.
149379 ** If the second argument is not NULL, then its contents are prepended to
149426 ** This is the implementation of a scalar SQL function used to test the
149431 ** The first argument, <tokenizer>, is the name of the fts3 tokenizer used
149433 ** is the query expression to parse. Each subsequent argument is the name
149550 ** a legal notice, here is a blessing:
149557 ** This is the implementation of generic hash-tables used in SQLite.
149563 ** The code in this file is only compiled if:
149565 ** * The FTS3 module is being built as an extension
149566 ** (in which case SQLITE_CORE is not defined), or
149568 ** * The FTS3 module is being built into the core of
149569 ** SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
149597 ** "pNew" is a pointer to the hash table that is to be initialized.
149598 ** keyClass is one of the constants
149600 ** determines what kind of key the hash table will use. "copyKey" is
149640 ** Hash and comparison functions when the mode is FTS3_HASH_STRING
149658 ** Hash and comparison functions when the mode is FTS3_HASH_BINARY
149679 ** The name of the function is "ftsHashFunction". The function takes a
149681 ** is a pointer to another function. Specifically, the return value
149682 ** of ftsHashFunction() is a pointer to a function that takes two parameters
149713 struct _fts3ht *pEntry, /* The entry into which pNew is inserted */
149763 ** already been computed and is passed as the 4th parameter.
149845 ** that matches pKey,nKey. Return the data for this element if it is
149846 ** found, or NULL if there is no match.
149855 /* Insert an element into the hash table pH. The key is pKey,nKey
149856 ** and the data is "data".
149859 ** element is created. A copy of the key is made if the copyKey
149860 ** flag is set. NULL is returned.
149863 ** new data replaces the old data and the old data is returned.
149864 ** The key is not copied in this instance. If a malloc fails, then
149865 ** the new data is returned and the hash table is unchanged.
149867 ** If the "data" parameter to this function is NULL, then the
149868 ** element corresponding to "key" is removed from the hash table.
149936 ** a legal notice, here is a blessing:
149948 ** The code in this file is only compiled if:
149950 ** * The FTS3 module is being built as an extension
149951 ** (in which case SQLITE_CORE is not defined), or
149953 ** * The FTS3 module is being built into the core of
149954 ** SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
150016 ** string to be tokenized is zInput[0..nInput-1]. A cursor
150017 ** used to incrementally tokenize this string is returned in
150069 ** the string they point to is a consonant or a vowel, according
150072 ** A consonate is any letter other than 'a', 'e', 'i', 'o', or 'u'.
150073 ** 'Y' is a consonant unless it follows another consonant,
150074 ** in which case it is a vowel.
150077 ** is that 'y' is a consonant unless it is followed by another
150107 ** In prose: A word is an optional consonant followed by zero or
150108 ** vowel-consonant pairs followed by an optional vowel. "m" is the
150112 ** Return true if the m-value for z is 1 or more. In other words,
150113 ** return true if z contains at least one vowel that is followed
150116 ** In this routine z[] is in reverse order. So we are really looking
150126 /* Like mgt0 above except we are looking for a value of m which is
150155 ** Return TRUE if there is a vowel anywhere within z[0..n-1]
150165 ** The text is reversed here. So we are really looking at
150175 ** is not 'w', 'x', or 'y'.
150177 ** The word is reversed here. So we are really checking the
150189 ** If the word ends with zFrom and xCond() is true for the stem
150194 ** is in normal order.
150197 ** match. Not that TRUE is returned even if xCond() fails and
150218 ** This is the fallback stemmer used when the porter stemmer is
150219 ** inappropriate. The input word is copied into the output with
150220 ** US-ASCII case folding. If the input word is too long (more
150222 ** it contains digits) then word is truncated to 20 or 6 bytes
150251 ** zOut is at least big enough to hold nIn bytes. Write the actual
150265 ** in [a-zA-Z] then no stemming is attempted and this routine just
150269 ** Stemming never increases the length of the word. So there is
150277 /* The word is too big or too small for the porter stemmer.
150495 /* z[] is now the stemmed word in reverse order. Flip it back
150507 ** whose value is greater than 0x80 (any UTF character) can be
150527 const char **pzToken, /* OUT: *pzToken is the token text */
150601 ** a legal notice, here is a blessing:
150609 ** This is part of an SQLite module implementing full-text search.
150614 ** The code in this file is only compiled if:
150616 ** * The FTS3 module is being built as an extension
150617 ** (in which case SQLITE_CORE is not defined), or
150619 ** * The FTS3 module is being built into the core of
150620 ** SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
150647 ** where <function-name> is the name passed as the second argument
150650 ** If the <pointer> argument is specified, it must be a blob value
150652 ** to the string <key-name>. If <pointer> is not specified, then
150654 ** an error is returned.
150656 ** Whether or not the <pointer> argument is specified, the value returned
150657 ** is a blob containing the pointer stored as the hash data corresponding
150658 ** to string <key-name> (after the hash-table is updated, if applicable).
150837 ** where <function-name> is the name passed as the second argument
150841 ** The return value is a string that may be interpreted as a Tcl
150843 ** added to the returned list. The first is the token position, the
150844 ** second is the token text (folded, stemmed, etc.) and the third is the
150999 ** This function is used for testing only, it is not included in the
151000 ** build unless SQLITE_TEST is defined.
151002 ** The purpose of this is to test that the fts3_tokenizer() function
151005 ** in the README.tokenizer file as an example, so it is important to
151009 ** function with no arguments. An assert() will fail if a problem is
151056 ** of the key when a value is inserted. i.e. by a call similar to:
151061 ** fts3TokenizerFunc() in this file for details) and, if ENABLE_TABLE is
151066 ** The third argument to this function, zName, is used as the name
151120 ** a legal notice, here is a blessing:
151132 ** The code in this file is only compiled if:
151134 ** * The FTS3 module is being built as an extension
151135 ** (in which case SQLITE_CORE is not defined), or
151137 ** * The FTS3 module is being built into the core of
151138 ** SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
151224 ** string to be tokenized is pInput[0..nBytes-1]. A cursor
151225 ** used to incrementally tokenize this string is returned in
151274 const char **ppToken, /* OUT: *ppToken is the token text */
151357 ** a legal notice, here is a blessing:
151366 ** An fts3tokenize virtual table is created as follows:
151449 ** The second argument, argv[], is an array of pointers to nul-terminated
151454 ** If successful, output parameter *pazDequote is set to point at the
151455 ** array of dequoted strings and SQLITE_OK is returned. The caller is
151457 ** in this case. Or, if an error occurs, an SQLite error code is returned.
151458 ** The final value of *pazDequote is undefined in this case.
151719 ** xEof - Return true if the cursor is at EOF, or false otherwise.
151814 ** a legal notice, here is a blessing:
151822 ** This file is part of the SQLite FTS3 extension module. Specifically,
151842 ** of it. i.e. if a full-text index node is 900 bytes in size, then a buffer
151843 ** of 920 bytes is allocated for it.
151846 ** it is always safe to read up to two varints from it without risking an
151847 ** overread, even if the node data is corrupted.
151858 ** Incremental loading is used for b-tree nodes FTS3_NODE_CHUNK_THRESHOLD
151860 ** The code is written so that the hard lower-limit for each of these values
151861 ** is 1. Clearly such small values would be inefficient, but can be useful
151864 ** If this module is built with SQLITE_TEST defined, these constants may
151887 ** If FTS_LOG_MERGES is defined, call sqlite3_log() to report each automatic
151888 ** and incremental merge operation that takes place. This is used for
151906 ** An instance of the following data structure is used to build doclists
151926 PendingList *pList; /* Doclist is assembled here */
151930 ** An instance of this structure is used to iterate through the terms on
151986 ** An instance of this structure is used to create a segment b-tree in the
152009 ** Type SegmentNode is used by the following three functions to create
152018 ** When a b+tree is written to the database (either as a result of a merge
152021 ** the tree is assembled in memory and written out only once all leaves have
152022 ** been populated and stored. This is Ok, as the b+-tree fanout is usually
152086 ** This function is used to obtain an SQLite prepared statement handle
152088 ** *pp is set to the requested statement handle and SQLITE_OK returned.
152089 ** Otherwise, an SQLite error code is returned and *pp is set to 0.
152091 ** If argument apVal is not NULL, then it must point to an array with
152140 /* This statement is used to determine which level to read the input from
152177 ** Return a single row if the segment with end_block=? is appendable. Or
152294 ** is executed.
152296 ** Returns SQLITE_OK if the statement is successfully executed, or an
152319 ** shared-cache table-lock on the %_segdir table. This is required before
152320 ** writing data to the fts3 table. If this lock is not acquired first, then
152325 ** It is best to avoid this because if FTS3 returns any error when
152327 ** And this is not what users expect when they get SQLITE_LOCKED_SHAREDCACHE.
152349 ** Within each language id, a separate index is maintained to store the
152356 ** in the %_segdir table on disk. This function is used to convert three
152360 ** Specifically, each language-id/index combination is allocated 1024
152362 ** for language-id 0 is allocate values 0-1023. The first prefix index
152363 ** (if any) for language-id 0 is allocated values 1024-2047. And so on.
152391 ** There is only ever one instance of this SQL statement compiled for
152438 ** Append a single varint to a PendingList buffer. SQLITE_OK is returned
152486 ** is returned if the structure is sqlite3_realloced as part of adding
152489 ** If an OOM error occurs, *pRc is set to SQLITE_NOMEM before returning.
152490 ** Zero is always returned in this case. Otherwise, if no OOM error occurs,
152491 ** it is set to SQLITE_OK.
152588 ** pending-terms hash-table. The docid used is that currently stored in
152589 ** p->iPrevDocid, and the column is specified by argument iCol.
152591 ** If successful, SQLITE_OK is returned. Otherwise, an SQLite error code.
152597 int iCol, /* Column into which text is being inserted */
152650 /* Add the term to each of the prefix indexes that it is not too
152673 int bDelete, /* True if this op is a delete */
152718 ** This function is called by the xUpdate() method as part of an INSERT
152722 ** Argument apVal is the same as the similarly named argument passed to
152723 ** fts3InsertData(). Parameter iDocid is the docid of the new row.
152747 ** This function is called by the xUpdate() method for an INSERT operation.
152748 ** The apVal parameter is passed a copy of the apVal argument passed by
152781 ** table. The SQL for this statement is:
152785 ** The statement features N '?' variables, where N is the number of user
152797 /* There is a quirk here. The users INSERT statement may have specified
152799 ** Which is a problem, since "rowid" and "docid" are aliases for the
152804 ** In FTS3, this is an error. It is an error to specify non-NULL values
152841 ** is if bContent is false. */
152865 ** The first element in the apVal[] array is assumed to contain the docid
152919 ** with 0, so the allocated index is one greater than the value returned
152926 ** allocated index is 0.
152928 ** If successful, *piIdx is set to the allocated index slot and SQLITE_OK
152929 ** returned. Otherwise, an SQLite error code is returned.
152958 /* If iNext is FTS3_MERGE_COUNT, indicating that level iLevel is already
152961 ** if iNext is less than FTS3_MERGE_COUNT, allocate index iNext.
152976 ** The %_segments table is declared as follows:
152981 ** specific row is identified by the iBlockid parameter. If paBlob is not
152982 ** NULL, then a buffer is allocated using sqlite3_malloc() and populated
152984 ** identified table row is. Whether or not paBlob is NULL, *pnBlob is set
152988 ** an SQLite error code is returned. Otherwise, SQLITE_OK is returned. If
152989 ** paBlob is non-NULL, then it is the responsibility of the caller to
152993 ** Fts3Table.pSegments variable. This handle is reused by subsequent calls
152995 ** sqlite3Fts3SegmentsClose() function. Reusing a blob handle is a handy
152997 ** before control is returned to the user (to prevent a lock being held
153053 ** Close the blob handle at p->pSegments, if it is open. See comments above
153112 ** segment. If successful, SQLITE_OK is returned. If there is no next term,
153156 /* If iCurrentBlock>=iLeafEndBlock, this is an EOF condition. All leaf
153181 /* Because of the FTS3_NODE_PADDING bytes of padding, the following is
153182 ** safe (no risk of overread) even if the node data is corrupted. */
153212 ** b-tree node. And that the final byte of the doclist is 0x00. If either
153213 ** of these statements is untrue, then the data structure is corrupt.
153254 ** *ppOffsetList is set to point to the first column-offset list
153256 ** *pnOffsetList is set to the length of the set of column-offset
153297 /* The following line of code (and the "p++" below the while() loop) is
153298 ** normally all that is required to move pointer p to the desired
153299 ** position. The exception is if this node is being loaded from disk
153432 /* The entire segment is stored in the root node. */
153446 ** This is a comparison function used as a qsort() callback when sorting
153468 ** This function is used to allocate an Fts3SegReader that iterates through
153471 ** If the isPrefixIter parameter is zero, then the returned SegReader iterates
153472 ** through each term in the pending-terms table. Or, if isPrefixIter is
153482 ** Whereas if isPrefixIter is zero, the terms visited are:
153529 ** callback as is used when flushing terms to disk.
153536 /* The query is a simple term lookup that matches at most one term in
153537 ** the index. All that is required is a straight hash-lookup.
153540 ** below, the "Fts3HashElem *pE" must be declared so that it is valid
153572 ** Comparison is as follows:
153574 ** 1) EOF is greater than not EOF.
153577 ** term is a prefix of another, the longer term is considered the
153580 ** 3) By segment age. An older segment is considered larger.
153606 ** version, it is assumed that each SegReader points to an entry in
153607 ** a doclist for identical terms. Comparison is made as follows:
153609 ** 1) EOF (end of doclist in this case) is greater than not EOF.
153613 ** 3) By segment age. An older segment is considered larger.
153644 ** If the pSeg iterator is already at EOF, return 0. Otherwise, return
153645 ** -ve if the pSeg term is less than zTerm/nTerm, 0 if the two terms are
153646 ** equal, or +ve if the pSeg term is greater than zTerm/nTerm.
153668 ** Argument apSegment is an array of nSegment elements. It is known that
153696 /* Check that the list really is sorted now. */
153800 ** Add term zTerm to the SegmentNode. It is guaranteed that zTerm is larger
153806 int isCopyTerm, /* True if zTerm/nTerm is transient */
153815 ** this is possible.
153830 /* An unusual case: this is the first term to be added to the node
153831 ** and the static node buffer (p->nNodeSize bytes) is not large
153835 ** this is not expected to be a serious problem.
153845 /* There is no prefix-length field for first term in a node */
153876 ** If this is the first node in the tree, the term is added to it.
153878 ** Otherwise, the term is not added to the new node, it is left empty for
153879 ** now. Instead, the term is inserted into the parent of pTree. If pTree
153880 ** has no parent, one is created here.
153932 ** Except, if pTree is a root node, do not write it to the database. Instead,
153935 ** If successful, SQLITE_OK is returned and output variable *piLast is
153937 ** blocks were written to the db). Otherwise, an SQLite error code is
154007 ** If successful, SQLITE_OK is returned. Otherwise, an SQLite error code.
154064 /* The current leaf node is full. Write it out to the database. */
154100 /* If the buffer currently allocated is too small for this entry, realloc
154121 ** If the isCopyTerm parameter is true, then the buffer pointed to by
154122 ** zTerm is transient, so take a copy of the term data. Otherwise, just
154148 ** to the segment using fts3SegWriterAdd(). If successful, SQLITE_OK is
154197 ** The first value in the apVal[] array is assumed to contain an integer.
154202 ** If successful, *pisEmpty is set to true if the table is empty except for
154203 ** document pRowid, or false otherwise, and SQLITE_OK is returned. If an
154204 ** error occurs, an SQLite error code is returned.
154210 /* If using the content=xxx option, assume the table is never empty */
154247 ** (1024 is actually the value of macro FTS3_SEGDIR_PREFIXLEVEL_STR).
154262 ** iAbsLevel is an absolute level that may be assumed to exist within
154263 ** the database. This function checks if it is the largest level number
154264 ** within its index. Assuming no error occurs, *pbMax is set to 1 if
154265 ** iAbsLevel is indeed the largest level, or 0 otherwise, and SQLITE_OK
154266 ** is returned. If an error occurs, an error code is returned and the
154267 ** final value of *pbMax is undefined.
154275 ** (1024 is actually the value of macro FTS3_SEGDIR_PREFIXLEVEL_STR).
154316 ** This function is used after merging multiple segments into a single large
154327 ** SQLITE_OK is returned if successful, otherwise an SQLite error code.
154375 ** When this function is called, buffer *ppList (size *pnList bytes) contains
154381 ** *pnList is set to zero before returning.
154383 ** If parameter bZero is non-zero, then any part of the input list following
154384 ** the end of the output list is zeroed before returning.
154428 ** If successful, return SQLITE_OK. Otherwise, if an OOM error is encountered
154601 ** This function is called on a MultiSegReader that has been started using
154609 ** then the entire doclist for the term is available in
154680 /* If this is a prefix-search, and if the term that apSegment[0] points
154684 ** Similarly, if this is a search for an exact match, and the first term
154685 ** of segment apSegment[0] is not a match, exit early.
154724 ** of Fts3SegReader objects is the same. The doclists must be merged
154886 ** segments in this index on levels greater than iAbsLevel. If there is
154887 ** at least one such segment, and it is possible to determine that all
154898 ** old version of FTS. In this case it is not possible to determine
154923 ** levels equal to or greater than iAbsLevel. As each entry is visited,
154924 ** updated it to set (level = -1) and (idx = N), where N is 0 for the
154929 ** order. The contents of level -1 (which is never used, except
154967 ** If this function is called with iLevel<0, but there is only one
154968 ** segment in the database, SQLITE_DONE is returned immediately.
154969 ** Otherwise, if successful, SQLITE_OK is returned. If an error occurs,
154970 ** an SQLite error code is returned.
155003 /* This call is to merge all segments in the database to a single
155004 ** segment. The level of the new segment is equal to the numerically
155006 ** index. The idx of the new segment is always 0. */
155015 /* This call is to merge all segments at level iLevel. find the next
155173 ** where N is the number of user defined columns in the fts3 table plus
155174 ** two. If nCol is the number of user defined columns, then values of the
155258 ** Merge the entire database so that there is one segment for each
155293 ** This function is called when the user executes the following statement:
155297 ** The entire FTS index is discarded and rebuilt. If the table is one
155298 ** created using the content=xxx option, then the new index is based on
155299 ** the current contents of the xxx table. Otherwise, it is rebuilt based
155432 ** An instance of the following structure is used as a dynamic buffer
155435 ** The function blobGrowBuffer() is used to extend the allocation.
155444 ** This structure is used to build up buffers containing segment b-tree
155470 ** An object of the following type is used to read data from a single
155490 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
155491 ** Otherwise, if the allocation at pBlob->a is not already at least nMin
155515 ** Return an error code if an error occurs (SQLITE_NOMEM is possible).
155516 ** Otherwise return SQLITE_OK. If there is no next entry on the node
155517 ** (e.g. because the current entry is the last) set NodeReader->aNode to
155566 ** If successful, SQLITE_OK is returned and the NodeReader object set to
155568 ** error code is returned.
155575 /* Figure out if this is a leaf or an internal node. */
155587 ** This function is called while writing an FTS segment each time a leaf o
155588 ** node is finished and written to disk. The key (zTerm/nTerm) is guaranteed
155594 ** (pWriter->aNodeWriter[0].iBlock) when this function is called.
155614 /* Figure out how much space the key will consume if it is written to
155616 ** the space required changes depending on which node the key is to
155676 ** header must be written before this function is called.
155678 ** A node header is a single 0x00 byte for a leaf node, or a height varint
155681 ** The term to be appended is passed via arguments zTerm/nTerm. For a
155682 ** leaf node, the doclist is passed as aDoclist/nDoclist. For an internal
155685 ** If the size of the value in blob pPrev is zero, then this is the first
155687 ** previous term. Before this function returns, it is updated to contain a
155690 ** It is assumed that the buffer associated with pNode is already large
155692 ** is extended by this function if requrired.
155694 ** If an error (i.e. OOM condition) occurs, an SQLite error code is
155706 int bFirst = (pPrev->n==0); /* True if this is the first term written */
155770 /* If the current block is not empty, and if adding this term/doclist
155820 ** This function is called to release all dynamic resources held by the
155824 ** If *pRc is not SQLITE_OK when this function is called, then no attempt
155825 ** is made to write any data to disk. Instead, this function serves only
155828 ** Otherwise, if *pRc is initially SQLITE_OK and an error occurs while
155829 ** flushing buffers to disk, *pRc is set to an SQLite error code before
155844 ** will be set to 0. If the root node is the parent of the leaves, iRoot
155855 /* Empty output segment. This is a no-op. */
155860 ** table. However, this is not permitted in this case. The problem is that
155871 ** table until we are sure it is needed.
155916 ** zRhs (size in bytes nRhs) using memcmp. If one term is a prefix of
155917 ** the other, it is considered to be smaller than the other.
155919 ** Return -ve if zLhs is smaller than zRhs, 0 if it is equal, or +ve
155920 ** if it is greater.
155937 ** Query to see if the entry in the %_segments table with blockid iEnd is
155938 ** NULL. If no error occurs and the entry is NULL, set *pbRes 1 before
155942 ** error code. The final value of *pbRes is undefined in this case.
155944 ** This is used to test if a segment is an "appendable" segment. If it
155945 ** is, then a NULL entry has been inserted into the %_segments table
155965 ** This function is called when initializing an incremental-merge operation.
155968 ** merge-writer object *pWriter is initialized to write to it.
155975 ** * The first key read from the input (arguments zKey and nKey) is
155998 int bAppendable = 0; /* Set to true if segment is appendable */
156020 /* Check that zKey/nKey is larger than the largest key the candidate */
156043 /* It is possible to append to this segment. Set up the IncrmergeWriter
156109 ** *piIdx is undefined in this case.
156134 ** In the %_segdir table, a segment is defined by the values in three
156141 ** When an appendable segment is allocated, it is estimated that the
156142 ** maximum number of leaf blocks that may be required is the sum of the
156144 ** of input segments, multiplied by two. This value is stored in stack
156148 ** is created ((1 + end_block - start_block)==16*nLeafEst). The contiguous
156153 ** In the actual code below, the value "16" is replaced with the
156194 ** to steal the space just allocated. This is also used to identify
156372 ** SQLITE_OK is returned if the segment is updated successfully. Or an
156451 ** This function is called after an incrmental-merge operation has run to
156455 ** Each input segment is either removed from the db completely (if all of
156474 /* Find the Fts3SegReader object with Fts3SegReader.iIdx==i. It is hiding
156483 /* Seg-reader is at EOF. Remove the entire input segment. */
156491 ** segment to the upper level. The segment is modified in place
156528 ** exists, is stored in the rowid==1 row of the %_stat table.
156562 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
156644 ** If one is found, set iAbsLevel to the absolute level number and
156659 /* If the hint read from the %_stat table is not empty, check if the
156677 ** is removed from the hint blob. */
156682 /* If nSeg is less that zero, then there is no level with at least
156688 ** indexes of absolute level iAbsLevel. If this cursor is opened using
156689 ** the 'hint' parameters, it is possible that there are less than nSeg
156690 ** segments available in level iAbsLevel. In this case, no work is
156798 /* If the first integer value is followed by a ',', read the second
156826 ** where X is an integer. X==0 means to turn automerge off. X!=0 means
156827 ** turn it on. The setting is persistent.
156880 ** language id iLangid. The checksum is calculated by XORing the checksums
156883 ** If successful, the checksum value is returned and *pRc set to SQLITE_OK.
156884 ** Otherwise, if an error occurs, *pRc is set to an SQLite error code. The
156885 ** return value is undefined in this case.
156959 ** code. The final value of *pbOk is undefined in this case.
157053 ** prefix in the document set, a 64-bit checksum is calculated (by code
157072 ** If the two checksums are identical, the integrity-check is deemed to have
157091 ** meaningful value to insert is the text 'optimize'.
157160 ** A deferred-doclist is like any other doclist with position information
157272 ** present in the FTS3 table. If it is, delete it and adjust the contents
157278 int *pnChng, /* IN/OUT: Decrement if row is deleted */
157282 int bFound = 0; /* True if *pRowid really is in the table */
157290 /* Deleting this row means the whole table is empty. In this case
157377 /* If this is an INSERT operation, or an UPDATE that modifies the rowid
157380 ** If the on-conflict mode is REPLACE, this means that the existing row
157382 ** if the on-conflict mode is other than REPLACE, then this method must
157397 /* The new rowid is not NULL (in this case the rowid will be
157398 ** automatically assigned and there is no chance of a conflict), and
157399 ** the statement is either an INSERT or an UPDATE that modifies the
157400 ** rowid column. So if the conflict mode is REPLACE, then delete any
157403 ** Or, if the conflict mode is not REPLACE, insert the new record into
157410 ** function) will return SQLITE_MISMATCH. If fts3DeleteByRowid is
157412 ** docid=$pNewRowid if $pNewRowid is not an integer value).
157426 /* If this is a DELETE or UPDATE operation, remove the old record. */
157433 /* If this is an INSERT or UPDATE operation, insert the new record. */
157495 ** a legal notice, here is a blessing:
157549 Fts3Cursor *pCsr; /* Cursor snippet is being generated from */
157567 int iCol; /* Column snippet is extracted from */
157574 ** This type is used as an fts3ExprIterate() context object while
157588 ** An instance of this structure is used to manage a pair of buffers, each
157595 int bGlobal; /* Set if global data is loaded */
157603 ** of the following structure is used to accumulate those values while the
157706 ** This function is used to help iterate through a position-list. A position
157707 ** list is a list of unique integers, sorted from smallest to largest. Each
157708 ** element of the list is represented by an FTS3 varint that takes the value
157720 ** When this function is called, *pp points to the start of an element of
157723 ** list and *pp is advanced to the following varint.
157758 ** are part of a sub-tree that is the right-hand-side of a NOT operator.
157759 ** For each phrase node found, the supplied callback function is invoked.
157762 ** the iteration is abandoned and the error code returned immediately.
157763 ** Otherwise, SQLITE_OK is returned after a callback has been made for
157777 ** This is an fts3ExprIterate() callback used while loading the doclists
157798 ** If pnPhrase is not NULL, then *pnPhrase is set to the number of matchable
157801 ** pnToken is not NULL, then it is set to the number of tokens in all
157867 ** is greater than or equal to (iNext+nSnippet).
157952 ** This function is an fts3ExprIterate() callback used by fts3BestSnippet().
157985 ** is the snippet with the highest score, where scores are calculated
157991 ** the snippet for which the corresponding mCovered bit is not set.
157994 ** returning. The score of the selected snippet is stored in *piScore
158023 /* Now that it is known how many phrases there are, allocate and zero
158080 ** If nAppend is negative, then the length of the string zAppend is
158092 /* If there is insufficient space allocated at StrBuffer.z, use realloc()
158093 ** to grow the buffer until so that it is big enough to accomadate the
158117 ** query term. That is, the final term of the snippet is always a term
158118 ** that requires highlighting. For example, if 'X' is a highlighted term
158119 ** and '.' is a non-highlighted term, BestSnippet() may select:
158130 ** This is done as part of extracting the snippet text, not when selecting
158131 ** the snippet. Snippet selection is done based on doclists only, so there
158132 ** is no way for fts3BestSnippet() to know whether or not the document
158159 ** right. Otherwise, the snippet is shifted by the number of tokens
158216 int isShiftDone = 0; /* True after snippet is shifted */
158246 /* Variable DUMMY1 is initialized to a negative value above. Elsewhere
158248 ** is initialized to zero before the first (*but not necessarily
158249 ** subsequent*) call to xNext(). This is done for a particular application
158250 ** that needs to know whether or not the tokenizer is being used for
158253 ** Extreme care is required when writing code to depend on this
158254 ** initialization. It is not a documented part of the tokenizer interface.
158255 ** If a tokenizer is used directly by any code outside of FTS, this
158260 /* Special case - the last token of the snippet is also the last token
158278 ** required. They are required if (a) this is not the first fragment,
158315 ** This function is used to count the entries in a column-list (a
158317 ** row). When this function is called, *ppCollist should point to the
158320 ** Before returning, *ppCollist is set to point to the first byte after
158325 ** The number of elements in the column-list is returned.
158332 /* A column-list is terminated by either a 0x01 or 0x00. */
158405 ** Argument pCtx is actually a pointer to a struct of type MatchInfo. This
158413 ** where X is the number of matches for phrase iPhrase is column iCol of all
158414 ** rows of the table. Y is the number of rows for which column iCol contains
158418 ** Y values are set to nDoc, where nDoc is the number of documents in the
158419 ** file system. This is done because the full-text index doclist is required
158420 ** to calculate these values properly, and the full-text index doclist is
158543 ** An instance of the following structure is used to store state while
158557 ** If LcsIterator.iCol is set to the following value, the iterator has
158574 ** 1 if the iterator is at EOF or if it now points to the start of the
158597 ** If the call is successful, the longest-common-substring lengths for each
158599 ** array before returning. SQLITE_OK is returned in this case.
158601 ** Otherwise, if an error occurs, an SQLite error code is returned and the
158602 ** data written to the first nCol elements of pInfo->aMatchinfo[] is
158648 /* This iterator is already at EOF for this column. */
158678 ** is guaranteed to be large enough for the output.
158680 ** If bGlobal is true, then populate all fields of the matchinfo() output.
158681 ** If it is false, then assume that those fields that do not change between
158686 ** occurs. If a value other than SQLITE_OK is returned, the state the
158687 ** pInfo->aMatchinfo[] buffer is left in is undefined.
158799 ** 'matchinfo' data is an array of 32-bit unsigned integers (C type u32).
158818 /* If there is cached matchinfo() data, but the format string for the
158826 /* If Fts3Cursor.pMIBuffer is NULL, then this is the first time the
158938 ** columns of the FTS3 table. Otherwise, only column iCol is considered.
159003 ** This function is an fts3ExprIterate() callback used by sqlite3Fts3Offsets().
159080 /* Initialize the contents of sCtx.aTerm[] for column iCol. There is
159088 /* Retreive the text stored in column iCol. If an SQL NULL is stored
159204 ** a legal notice, here is a blessing:
159229 ** from the sqlite3 source file utf.c. If this file is compiled as part
159320 ** If so, no action is taken. Otherwise, the codepoint is added to the
159322 ** the return value of sqlite3FtsUnicodeIsalnum() is inverted for all
159326 ** identifies as a diacritic) occurs in the zIn/nIn string it is ignored.
159327 ** It is not possible to change the behavior of the tokenizer with respect
159406 ** Return true if, for the purposes of tokenization, codepoint iCode is
159463 ** string to be tokenized is pInput[0..nBytes-1]. A cursor
159464 ** used to incrementally tokenize this string is returned in
159557 /* If the cursor is not at EOF, read the next character */
159600 ** a legal notice, here is a blessing:
159623 ** is less than zero.
159634 ** C. It is not possible to represent a range larger than 1023 codepoints
159750 ** If the argument is a codepoint corresponding to a lowercase letter
159805 ** is a diacritical modifier character.
159819 ** is an upper case character that has a lower case equivalent,
159824 ** is less than zero.
159831 ** If the least significant bit in flags is clear, then the rule applies
159833 ** need to be folded). Or, if it is set, then the rule only applies to
159838 ** case equivalent is ((C + aiOff[flags>>1]) & 0xFFFF).
159968 ** a legal notice, here is a blessing:
159983 ** The data structure for a single virtual r-tree table is stored in three
159985 ** in the table name is replaced with the user-supplied name of the r-tree
159992 ** The data for each node of the r-tree structure is stored in the %_node
159993 ** table. For each node that is not the root node of the r-tree, there is
159995 ** And for each row of data in the table, there is an entry in the %_rowid
159997 ** is stored on.
159999 ** The root node of an r-tree always exists, even if the r-tree table is
160000 ** empty. The nodeno of the root node is always 1. All other nodes in the
160002 ** is formatted as follows:
160004 ** 1. If the node is the root node (node 1), then the first 2 bytes
160013 ** of 4-byte coordinates. For leaf nodes the integer is the rowid
160014 ** of a record. For internal nodes it is the node number of a
160039 /* The following macro is used to suppress compiler warnings.
160058 /* Size of hash table Rtree.aHash. This hash table is not expected to
160059 ** ever contain very many entries, so a fixed number of buckets is
160066 ** various strategies. If possible, this estimate is loaded from the
160068 ** Otherwise, if no sqlite_stat1 entry is available, use
160090 /* List of nodes removed during a CondenseTree operation. List is
160121 ** If SQLITE_RTREE_INT_ONLY is defined, then this virtual table will
160139 ** The id is always a node-id. For iLevel>=1 the id is the node-id of
160141 ** the id is of the parent node and the cell that RtreeSearchPoint
160142 ** represents is the iCell-th entry in the parent node.
160153 ** The minimum number of cells allowed for a node is a third of the
160158 ** If an R*-tree "Reinsert" operation is required, the same number of
160166 ** The smallest possible node-size is (512-64)==448 bytes. And the largest
160167 ** supported cell size is 48 bytes (8 byte rowid + ten 4 byte coordinates).
160169 ** 2^40 is greater than 2^64, an r-tree structure always has a depth of
160176 ** Number of entries in the cursor RtreeNode cache. The first entry is
160188 u8 bPoint; /* True if sPoint is valid */
160215 ** The argument is an RtreeCoord. Return the value stored within the RtreeCoord
160285 ** xGeom and xQueryFunc fields is non-NULL, depending on whether the
160289 ** This object is deleted automatically by the destructor mechanism in
160308 ** An instance of this structure (in the form of a BLOB) is returned by
160310 ** sqlite3_rtree_query_callback() create, and is read as the right-hand
160330 ** 64 bit integer. The deserialized value is returned.
160358 ** 64 bit integer. The value returned is the number of bytes written
160450 ** indicating that node has not yet been assigned a node number. It is
160451 ** assigned a node number when nodeWrite() is called to write the
160481 /* Check if the requested node is already in the hash table. If so,
160519 ** of the r-tree structure. A height of zero means all data is stored on
160522 ** is greater than RTREE_MAX_DEPTH, the r-tree structure must be corrupt.
160532 ** field on the node is too large. If so, set the return code to
160561 RtreeNode *pNode, /* The node into which the cell is to be written */
160563 int iCell /* Index into pNode into which pCell is written */
160588 ** is successful, return SQLITE_OK.
160590 ** If there is not enough free space in pNode, return SQLITE_FULL.
160614 ** If the node is dirty, write it out to the database.
160638 ** Release a reference to a node. If the node is dirty and the reference
160639 ** count drops to zero, the node data is written to the database.
160665 ** node pNode. If pNode is a leaf node, this is a rowid. If it is
160666 ** an internal node, then the 64-bit integer is a child page number.
160754 ** zero the structure is deleted.
160871 ** The on-disk format is big-endian and needs to be converted for little-
160873 ** eInt is true and it stores 32-bit floating point records if eInt is
160874 ** false. a[] is the four bytes of the on-disk record to be decoded.
160880 ** processor endianness is known at compile-time. The SQLITE_BYTEORDER
160881 ** macro is part of sqliteInt.h and hence the endian-specific
160882 ** implementation will only be used if this module is compiled as part
160996 ** If this constraint is not satisfied, set *peWithin to NOT_WITHIN.
160997 ** If the constraint is satisfied, leave *peWithin unchanged.
160999 ** The constraint is of the form: xN op $val
161001 ** The op is given by p->op. The xN is p->iCoord-th coordinate in
161002 ** pCellData. $val is given by p->u.rValue.
161027 ** One of the cells in node pNode is guaranteed to have a 64-bit
161050 ** in its parent. If pNode is the root node, return -1.
161063 ** is less than, equal to, or greater than the second.
161065 ** The rScore is the primary key. Smaller rScore values come first.
161066 ** If the rScore is a tie, then use iLevel as the tie breaker with smaller
161067 ** iLevel values coming first. In this way, if rScore is the same for all
161069 ** is a depth-first search, which is the desired default behavior.
161276 ** or until the RtreeSearchPoint queue is empty, indicating that the
161408 ** return SQLITE_OK. If there is no such record in the table, set
161433 ** This function is called to configure the RtreeConstraint object passed
161435 ** first argument to this function is the right-hand operand to the MATCH
161444 /* Check that value is actually a blob. */
161447 /* Check that the blob is roughly the right size. */
161587 ** extension is currently being used by a version of SQLite too old to
161588 ** support estimatedRows. In that case this function is a no-op.
161609 ** If strategy 1 is used, then idxStr is not meaningful. If strategy
161610 ** 2 is used, idxStr is formatted to contain 2 bytes for each
161630 ** is 'a', the second from the left 'b' etc.
161644 ** is, do not consider the lookup-by-rowid plan as using such a plan would
161645 ** require the VDBE to evaluate the MATCH constraint, which is not currently
161673 ** sqlite uses an internal cost of 0.0). It is expected to return
161727 ** Return the margin length of cell p. The margin length is the sum
161758 ** Return true if the area covered by p2 is a subset of the area covered
161845 ** is inserted into it. Resolve ties by choosing the entry with
161943 ** The aSpare array is used as temporary working space by the
162006 ** minimum value of dimension iDim is considered first, the
162009 ** The aSpare array is used as temporary working space by the
162325 ** If node pLeaf is not the root of the r-tree and its pParent pointer is
162329 ** This operation is required when a row is deleted (or updated - an update
162330 ** is implemented as a delete followed by an insert). SQLite provides the
162332 ** the entry resides (argument pLeaf). Once the leaf is located, this
162333 ** function is called to determine its ancestry.
162456 /* If the node is not the tree root and now has less than the minimum
162496 /* Allocate the buffers used by this operation. The allocation is
162576 ** Insert cell pCell into node pNode. Node pNode is the head of a
162697 ** This is equivalent to copying the contents of the child into
162772 ** Parameter iCol is the index of the leftmost column involved in the
162773 ** constraint failure. If it is 0, then the constraint that failed is
162774 ** the unique constraint on the id column. Otherwise, it is the rtree
162777 ** If an OOM occurs, SQLITE_NOMEM is returned instead of SQLITE_CONSTRAINT.
162826 int bHaveRowid = 0; /* Set to 1 after new rowid is determined */
162839 ** In the first case, if the conflict-handling mode is REPLACE, then
162847 /* Populate the cell.aCoord[] array. The first coordinate is azData[3].
162849 ** NB: nData can only be less than nDim*2+3 if the rtree is mis-declared
162880 /* If a rowid value was supplied, check if it is already present in
162904 /* If azData[0] is not an SQL NULL value, it is the rowid of a
162968 ** of the number of rows in the virtual table. If possible, this is based
163110 ** that returns a single integer value. The statement is compiled and executed
163112 ** is written to *piVal and SQLITE_OK returned. Otherwise, an SQLite error
163113 ** code is returned and the value of *piVal after returning is not defined.
163131 ** This function is called from within the xConnect() or xCreate() method to
163133 ** to. If successful, pRtree->iNodeSize is populated and SQLITE_OK returned.
163134 ** Otherwise, an SQLite error code is returned.
163136 ** If this function is being called as part of an xConnect(), then the rtree
163137 ** table already exists. In this case the node-size is determined by inspecting
163141 ** This ensures that each node is stored on a single database page. If the
163142 ** database page-size is so large that more than RTREE_MAXCELLS entries
163181 ** This function is the implementation of both the xConnect and xCreate
163240 ** that is successful, call sqlite3_declare_vtab() to configure
163292 ** entry for each cell in the r-tree node. Each entry is itself a
163342 ** from the front of a blob that is an r-tree node. For example:
163346 ** The depth value is 0 for all nodes other than the root node, and the root
163347 ** node always has nodeno=1, so the example above is the primary use for this
163348 ** routine. This routine is intended for testing and analysis only.
163394 ** or sqlite3_rtree_query_callback(). In other words, this routine is the
163395 ** destructor for an RtreeGeomCallback objecct. This routine is called when
163396 ** the corresponding SQL function is deleted.
163405 ** This routine frees the BLOB that is returned by geomCallback().
163419 ** scalar function that is implemented by this routine.
163421 ** All this function does is construct an RtreeMatchArg object that
163535 ** a legal notice, here is a blessing:
163587 ** Version of sqlite3_free() that is always a function, never a macro.
163594 ** This lookup table is used to help decode the first byte of
163595 ** a multi-byte UTF8 character. It is copied here from SQLite source
163626 ** Compare two UTF-8 strings for equality where the first string is
163649 ** 1. uPattern is an unescaped match-all character "%",
163650 ** 2. uPattern is an unescaped match-one character "_",
163651 ** 3. uPattern is an unescaped escape character, or
163652 ** 4. uPattern is to be handled as an ordinary character
163707 ** the build-in LIKE operator. The first argument to the function is the
163708 ** pattern and the second argument is the string. So, the SQL statements:
163712 ** is implemented as like(B, A). If there is an escape character E,
163716 ** is mapped to like(B, A, E).
163758 ** This function is called when an ICU function called from within
163761 ** The scalar function context passed as the first argument is
163786 ** two arguments. The first is a regular expression pattern to compile
163787 ** the second is a string to match against that pattern. If either
163788 ** argument is an SQL NULL, then NULL Is returned. Otherwise, the result
163789 ** is 1 if the string matches the pattern, or 0 otherwise.
163811 /* If the left hand side of the regexp operator is NULL,
163812 ** then the result is also NULL.
163850 ** pointer. This is not really necessary, but it is tidier than
163876 ** should be invoked with two arguments. The second argument is the name
163878 ** as the second argument is the same as invoking the 1 argument version
163975 ** This scalar function is used to add ICU collation based collation
163976 ** types to an SQLite database connection. It is intended to be called
163981 ** Where <locale> is a string containing an ICU locale identifier (i.e.
163982 ** "en_AU", "tr_TR" etc.) and <collation-name> is the name of the
164086 ** a legal notice, here is a blessing:
164171 ** string to be tokenized is pInput[0..nBytes-1]. A cursor
164172 ** used to incrementally tokenize this string is returned in
164260 const char **ppToken, /* OUT: *ppToken is the token text */
164351 ** a legal notice, here is a blessing:
164365 ** that the user wishes to write to, a corresponding data_xyz table is
164371 ** 1) The database is updated. The modified database pages are written
164372 ** to a *-oal file. A *-oal file is just like a *-wal file, except
164373 ** that it is named "<database>-oal" instead of "<database>-wal".
164376 ** rollback mode while the *-oal file is being generated.
164385 ** 2) The "<database>-oal" file is moved to the equivalent "<database>-wal"
164390 ** Once the EXCLUSIVE lock is released, any other database readers
164395 ** 3) The new *-wal file is checkpointed. This proceeds in the same way
164396 ** as a regular database checkpoint, except that a single frame is
164397 ** checkpointed each time sqlite3rbu_step() is called. If the RBU
164398 ** handle is closed before the entire *-wal file is checkpointed,
164399 ** the checkpoint progress is saved in the RBU database and the
164405 ** The rename() call might not be portable. And RBU is not currently
164408 ** When state is saved, any commit to the *-oal file and the commit to
164425 ** update database than is strictly necessary.
164442 ** a legal notice, here is a blessing:
164460 ** The problem is that in order to update a b-tree, the leaf page (at least)
164462 ** working set of leaves is larger than the available cache memory, then a
164463 ** single leaf that is modified more than once as part of the transaction
164466 ** random order, access to pages within the database is also likely to be in
164467 ** random order, which is itself quite inefficient.
164469 ** One way to improve the situation is to sort the operations on each index
164472 ** and all but guarantees each modified leaf page is loaded and stored
164479 ** sequentially by separate processes. This is useful if the system cannot
164481 ** the entire update, for example because the update is being applied on a
164482 ** mobile device that is frequently rebooted. Even after the writer process
164489 ** applied using this extension is hence refered to as an "RBU update".
164494 ** An "RBU update" transaction is subject to the following limitations:
164514 ** * No constraint handling mode except for "OR ROLLBACK" is supported.
164519 ** An "RBU update" is stored as a separate SQLite database. A database
164520 ** containing an RBU update is an "RBU database". For each table in the
164541 ** may also be named data<integer>_<target>, where <integer> is any sequence
164549 ** If the target database table is a virtual table or a table that has no
164551 ** named "rbu_rowid". This column is mapped to the tables implicit primary
164582 ** If the target database table has an INTEGER PRIMARY KEY, it is not
164602 ** each column that is being updated, the corresponding character is set to
164609 ** is represented by the data_t1 row created by:
164616 ** user-defined SQL function "rbu_delta()" is invoked and the result stored in
164617 ** the target table column. rbu_delta() is invoked with two arguments - the
164625 ** is similar to an UPDATE statement such as:
164630 ** ota_control string, the contents of the data_xxx table column is assumed
164634 ** It is replaced by the result of applying the specified fossil delta to
164637 ** If the target database table is a virtual table or a table with no PRIMARY
164649 ** However, RBU is more efficient if reading the rows in from each data_xxx
164650 ** table in "rowid" order is roughly the same as reading them sorted by
164675 ** is marked as fully applied. Otherwise, the state of the RBU
164676 ** update application is saved in the RBU database for later
164681 ** If an update is only partially applied to the target database by the
164682 ** time sqlite3rbu_close() is called, various state information is saved
164687 ** to its original contents, it is sufficient to drop all tables that begin
164693 ** to do so is an error (SQLITE_ERROR).
164695 ** While an RBU handle is open, a SHARED lock may be held on the target
164696 ** database file. This means it is possible for other clients to read the
164699 ** If an RBU update is started and then suspended before it is completed,
164701 ** the suspended RBU update is also an error (SQLITE_BUSY).
164718 ** Argument zTarget is the path to the target database. Argument zRbu is
164725 ** If the zState argument is passed a NULL value, the RBU extension stores
164729 ** organize removing a separate state file after the update is concluded.
164730 ** Or, if zState is non-NULL, it must be a path to a database file in which
164736 ** Once the RBU update is finished, the RBU extension does not
164756 ** An RBU vacuum is similar to SQLite's built-in VACUUM command, except
164761 ** it is suspended. The first time sqlite3rbu_vacuum() is called, to start
164763 ** be empty (contain no tables). If an RBU vacuum is suspended by calling
164765 ** returned SQLITE_DONE, the vacuum state is stored in the state database.
164770 ** is completed, even if it created it. However, if the call to
164812 ** when sqlite3rbu_close() is called.
164824 ** the RBU update. If an error does occur, some other error code is
164841 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
164854 ** SQLite error code is returned. Additionally, *pzErrmsg may be set to
164856 ** message. It is the responsibility of the caller to eventually free any
164873 ** Obtain permyriadage (permyriadage is to 10000 as percentage is to 100)
164877 ** An RBU update is divided into two stages:
164883 ** The update is visible to non-RBU clients during stage 2. During stage 1
164886 ** If this API is called during stage 2 of the update, output variable
164887 ** (*pnOne) is set to 10000 to indicate that stage 1 has finished and (*pnTwo)
164889 ** stage 2. A value of 5000 indicates that stage 2 is half finished,
164890 ** 9000 indicates that it is 90% finished, and so on.
164892 ** If this API is called during stage 1 of the update, output variable
164893 ** (*pnTwo) is set to 0 to indicate that stage 2 has not yet started. The
164894 ** value to which (*pnOne) is set depends on whether or not the RBU
164905 ** If the rbu_count table is present and populated correctly and this
164906 ** API is called during stage 1, the *pnOne output variable is set to the
164908 ** not exist, then (*pnOne) is set to -1 during stage 1. If the rbu_count
164909 ** table exists but is not correctly populated, the value of the *pnOne
164910 ** output variable during stage 1 is undefined.
164920 ** RBU is currently building a *-oal file. The next call to sqlite3rbu_step()
164927 ** operation is an RBU update, then the updated version of the database
164932 ** RBU is currently performing an incremental checkpoint. The next call to
164954 ** via existing VFS zParent. Or, if the zParent parameter is passed NULL,
164956 ** The new object is registered as a non-default VFS with SQLite before
164960 ** object is created and deleted automatically by RBU.
164962 ** The exception is for applications that also use zipvfs. In this case,
164964 ** handle is opened. The RBU VFS should be installed so that the zipvfs
164989 ** The overhead of adding the "rbu" VFS to the system is negligible for
164990 ** non-RBU users. There is no harm in an application accessing the
165000 ** VFS objects are not reference counted. If a VFS object is destroyed
165030 ** The rbu_state table is used to save the state of a partially applied
165036 ** 1: the *-rbu file is currently under construction.
165039 ** 4: the checkpoint is underway.
165048 ** currently being written, or NULL if the main table is currently being
165061 ** header created by recovering the *-wal file. This is used to detect
165140 ** An iterator of this type is used to iterate through all objects in
165149 ** If the table has no indexes on it, abIndexed is set to NULL. Otherwise,
165150 ** it points to an array of flags nTblCol elements in size. The flag is
165151 ** set for each column that is either a part of the PK or a part of an
165174 int bUnique; /* Current index is unique */
165195 ** 4: Table is WITHOUT ROWID.
165196 ** 5: Table is a virtual table.
165231 ** If the RBU database contains an rbu_count table, this value is set to
165239 ** nPhaseOneStep is initialized to the sum of:
165243 ** for all source tables in the RBU database, where nRow is the number
165247 ** This estimate is accurate if the RBU update consists entirely of
165248 ** INSERT operations. However, it is inaccurate if:
165263 ** nPhaseOneStep is updated to account for the conditions above during the
165264 ** first pass of each source table. The updated nPhaseOneStep value is
165265 ** stored in the rbu_state table if the RBU update is suspended.
165303 ** An rbu VFS is implemented using an instance of this structure.
165313 ** Each file opened by an rbu VFS is represented by an instance of
165357 ** in *pz and is decremented once for each character in the integer.
165431 ** the final NUL terminator character). Except, if the delta string is
165542 ** arguments must be passed to this function. The first is the blob to
165595 ** point to a buffer containing an error message. It is the responsibility
165617 ** containing an error message. It is the responsibility of the caller
165629 ** Unless it is NULL, argument zSql points to a buffer allocated using
165632 ** compilation is successful, *ppStmt is set to point to the new statement
165633 ** handle and SQLITE_OK is returned.
165635 ** Otherwise, if an error occurs, *ppStmt is set to NULL and an error code
165637 ** message. It is the responsibility of the caller to free this error message
165640 ** If argument zSql is NULL, this function assumes that an OOM has occurred.
165641 ** In this case SQLITE_NOMEM is returned and *ppStmt set to NULL.
165723 ** If no error occurs, SQLITE_OK is returned and the iterator is left
165724 ** pointing to the next entry. Otherwise, an error code and message is
165726 ** error code is returned.
165789 ** accepts one or two arguments. The first argument is the name of a table -
165790 ** the name of a table in the RBU database. The second, if it is present, is 1
165797 ** where <name> is any sequence of 1 or more characters, <name> is returned.
165799 ** NULL is returned.
165805 ** For an rbu vacuum handle, a copy of the first argument is returned if
165806 ** the second argument is either missing or 0 (not a view).
165838 ** If no error occurs, SQLITE_OK is returned and the iterator is left
165839 ** pointing to the first entry. Otherwise, an error code and message is
165841 ** error code is returned.
165870 ** This is a wrapper around "sqlite3_mprintf(zFmt, ...)". If an OOM occurs,
165871 ** an error code is stored in the RBU handle passed as the first argument.
165873 ** If an error has already occurred (p->rc is already set to something other
165894 ** Argument zFmt is a sqlite3_mprintf() style format string. The trailing
165899 ** If an error occurs, an error code and error message is stored in the
165900 ** RBU handle. If an error has already occurred when this function is
165901 ** called, it is a no-op.
165926 ** error has already occurred when this function is called, return NULL
165947 ** there is room for at least nCol elements. If an OOM occurs, store an
165968 ** It is the responsibility of the caller to eventually free this memory
165971 ** If an OOM condition is encountered when attempting to allocate memory,
165972 ** output variable (*pRc) is set to SQLITE_NOMEM before returning. Otherwise,
165973 ** if the allocation succeeds, (*pRc) is left unchanged.
165996 ** rbu handle error code is not already set, set the error code and error
166010 ** peType is of type (int*), a pointer to an output parameter of type
166018 ** RBU_PK_WITHOUT_ROWID: Table is WITHOUT ROWID.
166019 ** RBU_PK_VTAB: Table is a virtual table.
166021 ** Argument *piPk is also of type (int*), and also points to an output
166023 ** (i.e. unless *peType is set to 3), then *piPk is set to zero. Or,
166025 ** is set to the root page number of the primary key index before
166035 ** if( the index that is the pk exists in sqlite_master ){
166128 ** This is a helper function for rbuObjIterCacheTableInfo(). It populates
166303 ** This function is used to create a SELECT list (the list of SQL
166307 ** second argument. A "PRAGMA index_xinfo = <idxname>" statement is used
166310 ** If the index is of the following form:
166314 ** and "t1" is a table with an explicit INTEGER PRIMARY KEY column
166315 ** "ipk", the returned string is:
166421 ** paramter is passed "old", return a string of the form:
166463 ** primary key of the current table. For example, if the table is:
166508 ** is something wrong with the rbu_control value in the rbu_control value
166523 ** column of the data_xxx table entry is set to zMask.
166525 ** The memory for the returned string is obtained from sqlite3_malloc().
166526 ** It is the responsibility of the caller to eventually free it using
166529 ** If an OOM error is encountered when allocating space for the new
166530 ** string, an error code is left in the rbu handle passed as the first
166531 ** argument and NULL is returned. Or, if an error has already occurred
166532 ** when this function is called, NULL is returned immediately, without
166576 ** "?" expressions. For example, if nByte is 3, return a pointer to
166579 ** The memory for the returned string is obtained from sqlite3_malloc().
166580 ** It is the responsibility of the caller to eventually free it using
166583 ** If an OOM error is encountered when allocating space for the new
166584 ** string, an error code is left in the rbu handle passed as the first
166585 ** argument and NULL is returned. Or, if an error has already occurred
166586 ** when this function is called, NULL is returned immediately, without
166660 ** a table (not index) with an external primary key, this function is a
166665 ** used to access that PK index. For example, if the target table is
166670 ** then the imposter table schema is:
166686 ** This is needed for the argument to "PRAGMA index_xinfo". Set
166730 ** If an error has already occurred when this function is called, it
166736 ** The iterator passed as the second argument is guaranteed to point to
166737 ** a table (not an index) when this function is called. This function
166739 ** table b-tree of the table before returning. Non-zero is returned if
166742 ** An imposter table is required in all cases except RBU_PK_VTAB. Only
166767 /* If the target table column is an "INTEGER PRIMARY KEY", add
166800 ** The number of bound variables is equal to the number of columns in
166802 ** (for the rbu_rowid column) if the target table is an implicit IPK or
166984 ** Because it only performs INSERT operations, this is not required for
167078 ** is not an error. Output variable *ppStmt is set to NULL in this case.
167093 /* Search for an existing statement. If one is found, shift it to the front
167179 ** table into it. Return a pointer to the new object. It is the
167394 ** this call returns SQLITE_NOTFOUND, then the RBU vfs is not in use.
167395 ** This is an error. */
167407 ** This routine is a copy of the sqlite3FileSuffix3() routine from the core.
167408 ** It is a no-op unless SQLITE_ENABLE_8_3_NAMES is defined.
167410 ** If SQLITE_ENABLE_8_3_NAMES is set at compile-time and if the database
167411 ** filename in zBaseFilename is a URI with the "8_3_names=1" parameter and
167412 ** if filename in z[] has a suffix (a.k.a. "extension") that is longer than
167416 ** If SQLITE_ENABLE_8_3_NAMES is set to 2 at compile-time, then always
167444 ** The checksum is store in the first page of xShmMap memory as an 8-byte
167461 ** This function is called as part of initializing or reinitializing an
167469 ** If argument pState is not NULL, then the incremental checkpoint is
167471 ** following recovery is not the same as the checksum saved in the RbuState
167472 ** object, then the rbu handle is set to DONE state. This occurs if some
167478 /* If pState is NULL, then the wal file may not have been opened and
167504 ** is closed.
167512 ** WRITER, CHECKPOINT and READ0 locks are still held, it is safe to copy
167538 ** the rbu object is in capture mode. Record the frame number of the frame
167569 ** Called when a page of data is written to offset iOff of the database
167570 ** file while the rbu handle is in capture mode. Record the page number
167579 ** This is called as part of an incremental checkpoint operation. Copy
167635 ** The RBU handle is currently in RBU_STAGE_OAL state, with a SHARED lock
167658 /* Move the *-oal file to *-wal. At this point connection p->db is
167659 ** holding a SHARED lock on the target database file (because it is
167663 ** lock is obtained here before the *-oal is moved to *-wal.
167726 ** If RBU_UPDATE is returned, then output variable *pzMask is set to
167773 ** Assert that column iCol of statement pStmt is named zName.
167800 /* If this is a delete, decrement nPhaseOneStep by nIndex. If the DELETE
167803 ** is invoked by the trigger. */
167815 /* If this is an INSERT into a table b-tree and the table has an
167816 ** explicit INTEGER PRIMARY KEY, check that this is not an attempt
167817 ** to write a NULL into the IPK column. That is not permitted. */
167841 ** SELECT statement is:
167865 ** input row. Perform whatever processing is required and return.
167867 ** If no error occurs, SQLITE_OK is returned. Otherwise, an error code
167868 ** and message is left in the RBU handle and a copy of the error code
167932 ** Or, if this is an RBU vacuum, set the schema cookie of the main db
167947 ** is already a transaction open, so the prepared statement cannot
167949 ** statement reads is page 1, which is guaranteed to be in the cache.
167964 ** value stored in the RBU_STATE_STAGE column is eStage. All other values
168010 ** The second argument passed to this function is the name of a PRAGMA
168016 ** where $zPragma is the string passed as the second argument, then
168021 ** where $val is the value returned by the first PRAGMA invocation.
168043 ** the state database is empty. If this RBU handle was opened for an
168104 /* If this is an RBU vacuum operation and the state table was empty
168208 ** considered equal, and NULL is considered distinct from all other values.
168217 ** This function is called as part of sqlite3rbu_open() when initializing
168219 ** the rbu_state table was empty) it is a no-op. Otherwise, it arranges
168254 ** If there is a "*-oal" file in the file-system corresponding to the
168301 ** This user-defined SQL function is invoked with a single argument - the
168342 ** is assumed to contain the same columns as:
168350 ** sqlite3rbu.nPhaseOneStep is initialized to the sum of (1 + nIndex) * cnt
168351 ** for all rows in the rbu_count table, where nIndex is the number of
168469 ** transaction is committed in rollback mode) currently stored on
168499 /* Open transactions both databases. The *-oal file is opened or
168505 /* Check if the main database is a zipvfs db. If it is, set the upper
168573 ** If the error code currently stored in the RBU handle is SQLITE_CONSTRAINT,
168613 /* If this is an RBU vacuum handle and the vacuum has either finished
168746 ** 1. Whenever the first page of a main database file is read or
168747 ** written, the value of the change-counter cookie is stored in
168749 ** database header field is stored in rbu_file.iWriteVer. This ensures
168752 ** 2. Whenever an SQLITE_OPEN_WAL file is opened, the (rbu_file.pWalFd)
168753 ** member variable of the associated database file descriptor is set
168755 ** db fds opened using a particular RBU VFS is maintained at
168762 ** 3a. If xAccess() is called to check if there exists a *-wal file
168773 ** Then, when xOpen() is called to open the *-wal file associated with
168778 ** RBU_STAGE_OAL mode are actually stored in heap memory. This is to
168780 ** are no-ops on target database files in RBU_STAGE_OAL mode. This is
168782 ** xShmLock() is called before xShmMap().
168784 ** 3c. If an EXCLUSIVE lock is attempted on a target database file in any
168786 ** fails with an SQLITE_BUSY error. This is to stop RBU connections
168899 /* If this is being called to read the first page of the target
169004 /* If this is an RBU vacuum operation and this is the target database,
169070 ** one is found, this vfs will operate in pass-through mode. The lower
169076 ** one is found, this is an error. */
169140 /* Magic number 1 is the WAL_CKPT_LOCK lock. Preventing SQLite from
169180 ** rbu is in the RBU_STAGE_OAL state, use heap memory for *-shm space
169341 /* This call is to open a *-wal file. Intead, open the *-oal. This
169342 ** code ensures that the string passed to xOpen() is terminated by a
169384 ** pointer and, if the file is a main database file, link it into the
169410 ** is available, or false otherwise.
169424 /* If this call is to check if a *-wal file associated with an RBU target
169425 ** database connection exists, and the RBU update is in RBU_STAGE_OAL,
169426 ** the following special handling is activated:
169454 ** to the pathname in zPath. zOut is guaranteed to point to a buffer
169555 ** via existing VFS zParent. The new object is registered as a non-default
169644 ** a legal notice, here is a blessing:
169654 ** The dbstat virtual table is used to extract low-level formatting
169659 ** Additional information is available on the "dbstat.html" page of the
169672 ** root-node path is '/'.
169675 ** a b-tree is '/000/'. (Btrees store content ordered from left to right
169677 ** The next to left-most child of the root page is
169721 u32 iChildPg; /* Child node (or 0 if this is a leaf) */
169827 ** There is no "best-index". This virtual table always does a linear
169831 ** idxNum is normally 0, but will be 1 if a schema=? constraint exists.
170385 sqlite3 *db; /* Database handle session is attached to */
170386 char *zDb; /* Name of database session is attached to */
170408 ** An object of this type is used internally as an abstraction for
170432 int bPatchset; /* True if this is a patchset */
170445 ** for each table the session object is monitoring. The structures are
170452 ** The data associated with each hash-table entry is a structure containing
170470 ** The following record format is similar to (but not compatible with) that
170471 ** used in SQLite database files. This format is used as part of the
170474 ** Unlike the SQLite database record format, each field is self-contained -
170475 ** there is no separation of header and data. Each field begins with a
170488 ** is followed by:
170493 ** of the text value. There is no nul terminator.
170510 ** A changeset is a collection of DELETE, UPDATE and INSERT operations on
170530 ** format described above under "RECORD FORMAT", where N is the number of
170531 ** columns in the table. The i'th field of each record is associated with
170535 ** The new.* record that is part of each INSERT change contains the values
170536 ** that make up the new row. Similarly, the old.* record that is part of each
170553 ** A patchset is also a collection of changes. It is similar to a changeset,
170555 ** resolution is required when applying the changeset.
170571 ** As in the changeset format, each field of the single record that is part
170572 ** of a patchset change is associated with the correspondingly positioned
170586 ** changesets. It is not possible for a record associated with an INSERT
170596 int bIndirect; /* True if this change is "indirect" */
170654 ** This function is used to serialize the contents of value pValue (see
170657 ** If it is non-NULL, the serialized form of the value is written to
170658 ** buffer aBuf. *pnWrite is set to the number of bytes written before
170659 ** returning. Or, if aBuf is NULL, the only thing this function does is
170662 ** If no error occurs, SQLITE_OK is returned. Or, if an OOM error occurs
170663 ** within a call to sqlite3_value_text() (may fail if the db is utf-16))
170664 ** SQLITE_NOMEM is returned.
170741 ** This macro is used to calculate hash key values for data structures. In
170752 ** In practice, the data structures this macro is used for are the primary
170789 ** values, *pbNullPK is set to true before returning.
170791 ** If an error occurs, an SQLite error code is returned and the final values
170792 ** of *piHash asn *pbNullPK are undefined. Otherwise, SQLITE_OK is returned
170874 ** The bPkOnly argument is non-zero if the record at aRecord[] is from
170892 /* It is not possible for eType to be SQLITE_NULL here. The session
170959 ** a single records which is written to the buffer at *paOut. *paOut is
170963 ** The merging of records is done as follows: For each column, if the
170998 ** This is a helper function used by sessionMergeUpdate().
171000 ** When this function is called, both *paOne and *paTwo point to a value
171004 ** If, when this function is called, *paTwo points to a valid value (i.e.
171005 ** *paTwo[0] is not 0x00 - the "no value" placeholder), a copy of the *paTwo
171006 ** pointer is returned and *pnVal is set to the number of bytes in the
171007 ** serialized value. Otherwise, a copy of *paOne is returned and *pnVal
171009 ** to the "no value" placeholder, *pnVal is set to 1. In other words:
171011 ** if( *paTwo is valid ) return *paTwo;
171046 ** This function is used by changeset_concat() to merge two UPDATE changes
171120 ** This function is only called from within a pre-update-hook callback.
171145 ** fail. This is because they cache their return values, and by the
171201 ** It is possible that a non-fatal OOM error occurs in this function. In
171202 ** that case the hash-table does not grow, but SQLITE_OK is returned anyway.
171203 ** Growing the hash table in this case is a performance optimization only,
171204 ** it is not required for correct operation.
171243 ** zThis, in schema zDb. It is expected that the table has nCol columns. If
171244 ** not, SQLITE_SCHEMA is returned and none of the output variables are
171247 ** Otherwise, if they are not NULL, variable *pnCol is set to the number
171248 ** of columns in the database table and variable *pzTab is set to point to a
171249 ** nul-terminated copy of the table name. *pazCol (if not NULL) is set to
171251 ** NULL) is set to point to an array of booleans - true if the corresponding
171252 ** column is part of the primary key.
171254 ** For example, if the table is declared as:
171268 ** *pabPK. It is illegal for both pazCol and pabPK to be NULL.
171359 ** This function is only called from within a pre-update handler for a
171360 ** write to table pTab, part of session pSession. If this is the first
171364 ** If an error occurs, an error code is stored in sqlite3_session.rc and
171366 ** key, sqlite3_session.rc is left set to SQLITE_OK and non-zero returned to
171368 ** is set to NULL in this case.
171391 ** This function is only called from with a pre-update-hook reporting a
171393 ** (UPDATE, INSERT, DELETE) is specified by the first argument.
171395 ** Unless one is already present or an error occurs, an entry is added
171400 sqlite3_session *pSession, /* Session object pTab is attached to */
171440 ** this is an SQLITE_UPDATE or SQLITE_DELETE), or just the PK
171441 ** values (if this is an INSERT). */
171449 /* Figure out how large an allocation is required */
171480 ** It is not possible for an OOM to occur in this block. */
171502 /* If the existing change is considered "indirect", but this current
171503 ** change is "direct", mark the change object as direct. */
171534 /* If there is a table-filter configured, invoke it. If it returns 0,
171572 /* If this session is attached to a different database ("main", "temp"
171573 ** etc.), or if it is not currently enabled, there is nothing to do. Skip
172000 ** while the session object is enabled will be recorded.
172003 ** not matter if the PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias)
172019 /* First search for an existing entry. If one is found, this call is
172035 ** appear in the correct order when a changeset or patchset is
172052 ** Ensure that there is room in the buffer to append nByte bytes of data.
172053 ** If not, use sqlite3_realloc() to grow the buffer so that there is.
172055 ** If successful, return zero. Otherwise, if an OOM condition is encountered,
172081 ** This function is a no-op if *pRc is non-zero when it is called.
172082 ** Otherwise, if an error occurs, *pRc is set to an SQLite error code
172101 ** This function is a no-op if *pRc is other than SQLITE_OK when it is
172104 ** If an OOM condition is encountered, set *pRc to SQLITE_NOMEM before
172114 ** This function is a no-op if *pRc is other than SQLITE_OK when it is
172117 ** If an OOM condition is encountered, set *pRc to SQLITE_NOMEM before
172127 ** This function is a no-op if *pRc is other than SQLITE_OK when it is
172130 ** If an OOM condition is encountered, set *pRc to SQLITE_NOMEM before
172146 ** This function is a no-op if *pRc is other than SQLITE_OK when it is
172150 ** If an OOM condition is encountered, set *pRc to SQLITE_NOMEM before
172166 ** This function is a no-op if *pRc is other than SQLITE_OK when it is
172168 ** to the buffer. No nul-terminator is written.
172170 ** If an OOM condition is encountered, set *pRc to SQLITE_NOMEM before
172184 ** This function is a no-op if *pRc is other than SQLITE_OK when it is
172187 ** nul-terminator byte is written.
172189 ** If an OOM condition is encountered, set *pRc to SQLITE_NOMEM before
172212 ** This function is a no-op if *pRc is other than SQLITE_OK when it is
172273 ** (i.e. nothing has changed), then no data at all is appended to the buffer.
172339 /* If at least one field has been modified, this is not a no-op. */
172342 /* Add a field to the old.* record. This is omitted if this modules is
172375 ** the changeset format if argument bPatchset is zero, or the patchset
172471 ** is as prepared by function sessionSelectStmt().
172542 ** This function is a no-op if *pRc is set to other than SQLITE_OK when it
172543 ** is called. Otherwise, append a serialized table header (part of the binary
172561 ** Generate either a changeset (if argument bPatchset is zero) or a patchset
172562 ** (if it is non-zero) based on the current contents of the session object
172565 ** If no error occurs, SQLITE_OK is returned and the new changeset/patchset
172567 ** occurs, an SQLite error code is returned and both output variables set
172586 ** object is already in the error state (sqlite3_session.rc != SQLITE_OK),
172610 /* Check the table schema is still Ok. */
172650 /* If the buffer is now larger than SESSIONS_STRM_CHUNK_SIZE, pass
172693 ** It is the responsibility of the caller to eventually free the buffer
172730 ** It is the responsibility of the caller to eventually free the buffer
172843 ** If the SessionInput object passed as the only argument is a streaming
172844 ** object and the buffer is full, discard some data to free up space.
172862 ** data is in the buffer.
172890 ** When this function is called, *ppRec points to the start of a record
172917 ** buffer. SQLITE_OK is returned if successful, or SQLITE_NOMEM if an OOM
172941 ** When this function is called, *paChange points to the start of the record
172942 ** to deserialize. Assuming no error occurs, *paChange is set to point to
172944 ** If the argument abPK is NULL, then the record contains nCol values. Or,
172945 ** if abPK is other than NULL, then the record contains only the PK fields
172946 ** (in other words, it is a patchset DELETE record).
172949 ** is set to point to an sqlite3_value object containing the value read
172950 ** from the corresponding position in the record. If that value is not
172951 ** included in the record (i.e. because the record is part of an UPDATE change
172952 ** and the field was not modified), the corresponding element of apOut[] is
172955 ** It is the responsibility of the caller to free all sqlite_value structures
172958 ** If an error occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.
173021 ** This function ensures that all of the above is present in the input
173023 ** If successful, SQLITE_OK is returned. Otherwise, an SQLite error code.
173024 ** The input pointer is not moved.
173052 ** record is buffered. It does not move the input pointer.
173054 ** If successful, SQLITE_OK is returned and *pnByte is set to the size of
173055 ** the record in bytes. Otherwise, an SQLite error code is returned. The
173056 ** final value of *pnByte is undefined in this case.
173094 ** p->zTab and p->abPK[] variables accordingly. The p->apValue[] array is
173096 ** input pointer is left pointing to the byte following the table header.
173098 ** If successful, SQLITE_OK is returned. Otherwise, an SQLite error code
173099 ** is returned and the final values of the various fields enumerated above
173136 ** API sqlite3changeset_next(). If SQLITE_ROW is returned, then the
173140 ** record is written to *paRec before returning and the number of bytes in
173143 ** Either way, this function returns SQLITE_ROW if the iterator is
173158 /* If the iterator is in the error-state, return immediately. */
173170 ** remaining data if there are less than 10 bytes available. This is
173176 /* If the iterator is already at the end of the changeset, return DONE. */
173215 /* If this is an UPDATE or DELETE, read the old.* record. */
173222 /* If this is an INSERT or UPDATE, read the new.* record. */
173229 /* If this is an UPDATE that is part of a patchset, then all PK and
173231 ** is currently completely empty. This block shifts the PK fields from
173269 int *pbIndirect /* OUT: True if change is indirect */
173295 ** This function may only be called while the iterator is pointing to an
173297 ** Otherwise, SQLITE_MISUSE is returned.
173300 ** iVal'th value in the old.* record. Or, if that particular value is not
173301 ** included in the record (because the change is an UPDATE and the field
173302 ** was not modified and is not a PK column), set *ppValue to NULL.
173304 ** If value iVal is out-of-range, SQLITE_RANGE is returned and *ppValue is
173323 ** This function may only be called while the iterator is pointing to an
173325 ** Otherwise, SQLITE_MISUSE is returned.
173328 ** iVal'th value in the new.* record. Or, if that particular value is not
173329 ** included in the record (because the change is an UPDATE and the field
173332 ** If value iVal is out-of-range, SQLITE_RANGE is returned and *ppValue is
173361 ** conflict-handler function. Otherwise, SQLITE_MISUSE is returned.
173363 ** If successful, *ppValue is set to point to an sqlite3_value structure
173366 ** If value iVal is out-of-range or some other error occurs, an SQLite error
173367 ** code is returned. Otherwise, SQLITE_OK.
173631 u8 *abPK; /* Boolean array - true if column is in PK */
173647 ** Variable :5 (nCol+1) is a boolean. It should be set to 0 if we require
173649 ** conflict handler is invoked with NOTFOUND and returns CHANGESET_REPLACE.
173651 ** If successful, SQLITE_OK is returned and SessionApplyCtx.pDelete is left
173726 ** ?(i*3+2) A boolean flag indicating that the value is being modified.
173730 ** a row even if the non-PK values do not match. This is required if the
173731 ** conflict-handler is invoked with CHANGESET_DATA and returns
173732 ** CHANGESET_REPLACE. This is variable "?(nCol*3+1)".
173734 ** If successful, SQLITE_OK is returned and SessionApplyCtx.pUpdate is left
173812 ** If successful, SQLITE_OK is returned and SessionApplyCtx.pSelect is left
173830 ** If successful, SQLITE_OK is returned and SessionApplyCtx.pInsert is left
173867 /* COVERAGE: The (pVal->z==0) branch is never true using current versions
173869 ** the (pVal->z) variable remains as it was or the type of the value is
173885 ** New.* value $i from the iterator is bound to variable ($i+1) of
173886 ** statement pStmt. If parameter abPK is NULL, all values from 0 to (nCol-1)
173887 ** are transfered to the statement. Otherwise, if abPK is not NULL, it points
173889 ** which abPK[$i] is true are read from the iterator and bound to the
173892 ** An SQLite error code is returned if an error occurs. Otherwise, SQLITE_OK.
173906 ** is one of these to guarantee that it is safe to ignore the return
173921 ** SQL statement pSelect is as generated by the sessionSelectRow() function.
173924 ** entry. If a row is found, the SELECT statement left pointing at the row
173925 ** and SQLITE_ROW is returned. Otherwise, if no row is found and no error
173926 ** has occured, the statement is reset and SQLITE_OK is returned. If an
173927 ** error occurs, the statement is reset and an SQLite error code is returned.
173930 ** statement pSelect. If any other value is returned, the statement does
173967 ** If argument pbReplace is NULL, then the type of conflict handler invoked
173975 ** Or, if pbReplace is not NULL, then an attempt is made to find an existing
173977 ** or inserted. If such a record can be found, it is available to the conflict
173979 ** handler invoked is as follows:
173988 ** If pbReplace is not NULL, and a record with a matching PK is found, and
173990 ** is set to non-zero before returning SQLITE_OK.
173992 ** If the conflict handler returns SQLITE_CHANGESET_ABORT, SQLITE_ABORT is
174003 int *pbReplace /* OUT: Set to true if PK row is found */
174070 ** currently points to to the database. If a conflict is encountered, invoke
174073 ** If argument pbRetry is NULL, then ignore any CHANGESET_DATA conflict. If
174074 ** one is encountered, update or delete the row with the matching primary key
174075 ** instead. Or, if pbRetry is not NULL and a CHANGESET_DATA conflict occurs,
174080 ** If argument pbReplace is NULL and a CHANGESET_CONFLICT conflict is
174082 ** Or, if pbReplace is not NULL, invoke it with CHANGESET_CONFLICT. If such
174089 ** returns SQLITE_ABORT. Otherwise, if no error occurs, SQLITE_OK is
174113 /* Bind values to the DELETE statement. If conflict handling is required,
174115 ** Or, if conflict handling is not required, bind just the PK column
174117 ** is not required if:
174119 ** * this is a patchset, or
174121 ** * all columns of the table are PK columns (in this case there is
174171 ** a row with a matching primary key. If so, this is a DATA conflict.
174172 ** Otherwise, if there is no primary key match, it is a NOTFOUND. */
174179 /* This is always a CONSTRAINT conflict. */
174204 ** currently points to to the database. If a conflict is encountered, invoke
174207 ** The difference between this function and sessionApplyOne() is that this
174208 ** function handles the case where the conflict-handler is invoked and
174226 /* If the bRetry flag is set, the change has not been applied due to an
174227 ** SQLITE_CHANGESET_DATA problem (i.e. this is an UPDATE or DELETE and
174228 ** a row with the correct PK is present in the db, but one or more other
174238 /* If the bReplace flag is set, the change is an INSERT that has not
174317 ** Argument pIter is a changeset iterator that has been initialized, but
174320 ** conflict handler callback is invoked to resolve any conflicts encountered
174427 /* If there is a schema mismatch on the current table, proceed to the
174544 ** This function is called to merge two changes to the same row together as
174545 ** part of an sqlite3changeset_concat() operation. A new change object is
174553 int bIndirect, /* True if second change is indirect */
174602 ** buffer of the new object is large enough to hold any record that
174724 ** simply added to the start of it. This is to ensure that the
174780 ** If xOutput is not NULL, then the changeset/patchset is returned to the
174784 ** Or, if xOutput is NULL, then (*ppOut) is populated with a pointer to a
174786 ** this case (*pnOut) is set to the size of the output buffer in bytes. It
174787 ** is the responsibility of the caller to free the output buffer using
174788 ** sqlite3_free() when it is no longer required.
174790 ** If successful, SQLITE_OK is returned. Or, if an error occurs, an SQLite
174791 ** error code. If an error occurs and xOutput is NULL, (*ppOut) and (*pnOut)
174993 ** a legal notice, here is a blessing:
175001 ** This SQLite extension implements JSON functions. The interface is
175006 ** For the time being, all JSON is stored as pure text. (We might add
175008 ** a BLOB, but there is no support for JSONB in the current implementation.
175009 ** This implementation parses JSON text at 250 MB/s, so it is hard to see
175034 ** Versions of isspace(), isalnum() and isdigit() to which it is safe
175038 /* Use the SQLite core versions if this routine is part of the
175050 ** Growing our own isspace() routine this way is twice as fast as
175088 ** under construction. Really, this is a generic string accumulator
175089 ** that can be and is used to create strings other than JSON.
175096 u8 bStatic; /* True if zBuf is static space */
175124 #define JNODE_RAW 0x01 /* Content is raw, not JSON encoded */
175125 #define JNODE_ESCAPE 0x02 /* Content is text with \ escapes */
175252 ** character is not '[' or '{'.
175365 ** the parsed JSON at pNode. The minimum answer is 1. For ARRAY and
175368 ** Appended elements are not counted. The value returned is the number
175391 ** append to pOut. Subsubstructure is also included. Return
175551 #if 0 /* Never happens because JNODE_RAW is only set by json_set(),
175698 ** first non-whitespace character is '}' and return -3 if the first
175699 ** non-whitespace character is ']'.
175840 ** pParse is uninitialized when this routine is called.
175932 ** to that node, or NULL if zPath is malformed or if there is no such
175935 ** If pApnd!=0, then try to append new nodes to complete zPath if it is
175937 ** new nodes are appended *pApnd is set to 1.
176075 ** Return the text of a syntax error message on a JSON path. Space is
176084 ** Return NULL if not found or if there is an error.
176147 ** a parse of the JSON provided. Or it returns NULL if JSON is not
176184 ** The json_test1(JSON) function return true (1) if the input is JSON
176186 ** is not known to be JSON.
176225 ** is a BLOB, throw an error.
176252 ** Return 0 if the input is not a well-formed JSON array.
176287 ** Return the element described by PATH. Return NULL if there is no
176290 ** is malformed.
176334 ** is not a string or if any value is a BLOB, throw an error.
176409 ** this routine is a no-op. If JSON or PATH is malformed, throw an error.
176451 ** If JSON or PATH is malformed, throw an error.
176456 ** routine is a no-op. If JSON or PATH is malformed, throw an error.
176533 ** Return 1 if JSON is a well-formed JSON string according to RFC-7159.
176936 /* The query strategy is to look for an equality constraint on the json
176937 ** column. Without such a constraint, the table cannot operate. idxNum is
176938 ** 1 if the constraint is found, 3 if the constraint and zRoot are found,
177220 ** a legal notice, here is a blessing:
177277 ** If parameter iCol is less than zero, set output variable *pnToken
177278 ** to the total number of tokens in the FTS5 table. Or, if iCol is
177283 ** If parameter iCol is greater than or equal to the number of columns
177284 ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
177285 ** an OOM condition or IO error), an appropriate SQLite error code is
177292 ** If parameter iCol is less than zero, set output variable *pnToken
177293 ** to the total number of tokens in the current row. Or, if iCol is
177297 ** If parameter iCol is greater than or equal to the number of columns
177298 ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
177299 ** an OOM condition or IO error), an appropriate SQLite error code is
177307 ** current document. If successful, (*pz) is set to point to a buffer
177308 ** containing the text in utf-8 encoding, (*pn) is set to the size in bytes
177309 ** (not characters) of the buffer and SQLITE_OK is returned. Otherwise,
177310 ** if an error occurs, an SQLite error code is returned and the final values
177326 ** "detail=none" or "detail=column" option. If the FTS5 table is created
177328 ** (i.e. if it is a contentless table), then this API always returns 0.
177336 ** Usually, output parameter *piPhrase is set to the phrase number, *piCol
177338 ** first token of the phrase. The exception is if the table was created
177339 ** with the offsets=0 option specified. In this case *piOff is always
177355 ** This API function is used to query the FTS table for phrase iPhrase
177361 ** current query is executed. Any column filter that applies to
177362 ** phrase iPhrase of the current query is included in $p. For each
177364 ** is invoked. The context and API objects passed to the callback
177370 ** query is abandoned and the xQueryPhrase function returns immediately.
177371 ** If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK.
177372 ** Otherwise, the error code is propagated upwards.
177374 ** If the query runs to completion without incident, SQLITE_OK is returned.
177375 ** Or, if some error occurs before the query completes or is aborted by
177376 ** the callback, an SQLite error code is returned.
177386 ** Each extension function is allocated a single auxiliary data slot for
177387 ** each FTS query (MATCH expression). If the extension function is invoked
177391 ** If there is already an auxiliary data pointer when this function is
177392 ** invoked, then it is replaced by the new pointer. If an xDelete callback
177393 ** was specified along with the original pointer, it is invoked at this
177396 ** The xDelete callback, if one is specified, is also invoked on the
177400 ** the auxiliary data is set to NULL and an error code returned. If the
177401 ** xDelete parameter was not NULL, it is invoked on the auxiliary data
177410 ** If the bClear argument is non-zero, then the auxiliary data is cleared
177412 ** if any, is not invoked.
177417 ** This function is used to retrieve the total number of rows in the table.
177423 ** This function is used, along with type Fts5PhraseIter and the xPhraseNext
177425 ** the current row. This is the same information as is accessible via the
177439 ** The Fts5PhraseIter structure is defined above. Applications should not
177445 ** "detail=none" or "detail=column" option. If the FTS5 table is created
177447 ** (i.e. if it is a contentless table), then this API always iterates
177455 ** and xPhraseNext() APIs described above. The difference is that instead
177470 ** "detail=none" option. If the FTS5 table is created with either
177471 ** "detail=none" "content=" option (i.e. if it is a contentless table),
177477 ** (or xInst/xInstCount). The chief advantage of this API is that it is
177530 ** is registered by providing fts5 with a populated instance of the
177536 ** This function is used to allocate and initialize a tokenizer instance.
177537 ** A tokenizer instance is required to actually tokenize text.
177539 ** The first argument passed to this function is a copy of the (void*)
177547 ** The final argument is an output variable. If successful, (*ppOut)
177551 ** is undefined.
177554 ** This function is invoked to delete a tokenizer handle previously
177559 ** This function is expected to tokenize the nText byte string indicated
177561 ** argument passed to this function is a pointer to an Fts5Tokenizer object
177564 ** The second argument indicates the reason that FTS5 is requesting
177565 ** tokenization of the supplied text. This is always one of the following
177568 ** <ul><li> <b>FTS5_TOKENIZE_DOCUMENT</b> - A document is being inserted into
177569 ** or removed from the FTS table. The tokenizer is being invoked to
177573 ** <li> <b>FTS5_TOKENIZE_QUERY</b> - A MATCH query is being executed
177574 ** against the FTS index. The tokenizer is being called to tokenize
177578 ** FTS5_TOKENIZE_QUERY, except that the bareword or quoted string is
177582 ** <li> <b>FTS5_TOKENIZE_AUX</b> - The tokenizer is being invoked to
177594 ** which the token is derived within the input.
177597 ** normally be set to 0. The exception is if the tokenizer supports
177600 ** FTS5 assumes the xToken() callback is invoked for each token in the
177606 ** input buffer is exhausted, xTokenize() should return SQLITE_OK. Finally,
177625 ** same token for inputs "first" and "1st". Say that token is in
177655 ** document such as "I won first place" is tokenized, entries are
177666 ** Whether it is parsing document or query text, any call to xToken that
177668 ** is considered to supply a synonym for the previous token. For example,
177680 ** It is an error to specify the FTS5_TOKEN_COLOCATED flag the first time
177681 ** xToken() is called. Multiple synonyms may be specified for a single token
177683 ** There is no limit to the number of synonyms that may be provided for a
177686 ** In many cases, method (1) above is the best approach. It does not add
177688 ** so it is efficient in terms of disk space and query speed. However, it
177690 ** token "first" is subsituted for "1st" by the tokenizer, then the query:
177706 ** token "1st", but not "first" (assuming the tokenizer is not able to
177713 ** When using methods (2) or (3), it is important that the tokenizer only
177715 ** text (method (3)), not both. Doing so will not cause any errors, but is
177800 ** a legal notice, here is a blessing:
177845 /* Truncate very long tokens to this many bytes. Hard limit is
177846 ** (65536-1-1-4-9)==65521 bytes. The limiting factor is the 16-bit offset
177852 ** less than 32. If it is set to anything large than that, an #error
177872 ** The assert_nc() macro is similar to the assert() macro, except that it
177873 ** is used for assert() conditions that are true only if it can be
177874 ** guranteed that the database is not corrupt.
177897 ** then an object of the following type is used to record the set of columns.
177898 ** Each entry in the aiCol[] array is a column that may be matched.
177900 ** This object is used by fts5_expr.c and fts5_index.c.
177931 ** the string "rowid" otherwise. This text is not quoted - if it is
177942 ** True if the %_docsize table is created.
177945 ** This is only used for debugging. If set to false, any prefix indexes
177946 ** are ignored. This value is configured using:
177970 int iCookie; /* Incremented when %_config is modified */
178172 ** Argument p points to a buffer containing utf-8 text that is n bytes in
178207 ** This interface is used by the fts5vocab module.
178214 ** Insert or remove data to or from the index. Each time a document is
178215 ** added to or removed from the index, this function is called one or more
178219 ** If the operation is a delete, it must be called (at least) once for each
178221 ** argument is ignored for a delete.
178236 int bDelete, /* True if current operation is a delete */
178242 ** If the bCommit flag is true, also close any open blob handles.
178490 ** The fts5_expr.c API above this point is used by the other hand-written
178603 ** a legal notice, here is a blessing:
178615 ** interstitial "-" characters) contained in this template is changed into
178617 ** of this template is copied straight through into the generate parser
178620 ** The following is the concatenation of all %include directives from the
178648 ** into sqlite3ParserAlloc(). The default is size_t.
178654 ** in a format understandable to "makeheaders". This section is blank unless
178655 ** "lemon" is run with the "-m" command-line option.
178659 /* The next sections is a series of control #defines.
178661 ** fts5YYCODETYPE is the data type used to store the integer codes
178663 ** "unsigned char" is used if there are fewer than
178665 ** fts5YYNOCODE is a number of type fts5YYCODETYPE that is not used for
178672 ** fts5YYACTIONTYPE is the data type used for "action codes" - numbers
178675 ** sqlite3Fts5ParserFTS5TOKENTYPE is the data type used for minor type for terminal
178676 ** symbols. Background: A "minor type" is a semantic
178684 ** fts5YYMINORTYPE is the data type used for all minor types.
178685 ** This is typically a union of many types, one of
178686 ** which is sqlite3Fts5ParserFTS5TOKENTYPE. The entry in the union
178687 ** for terminal symbols is called "fts5yy0".
178688 ** fts5YYSTACKDEPTH is the maximum depth of the parser's stack. If
178689 ** zero the stack is dynamically sized using realloc()
178694 ** fts5YYERRORSYMBOL is the code number of the error symbol. If not
178742 /* Define the fts5yytestcase() macro to be a no-op if is not already defined
178747 ** code the fts5yytestcase() macro should be turned off. But it is useful
178760 ** Suppose the action integer is N. Then the action is determined as
178763 ** 0 <= N <= fts5YY_MAX_SHIFT Shift N. That is, push the lookahead
178779 ** The action table is constructed as a single large table named fts5yy_action[].
178780 ** Given state S and lookahead X, the action is computed as
178784 ** If the index value fts5yy_shift_ofst[S]+X is out of range or if the value
178785 ** fts5yy_lookahead[fts5yy_shift_ofst[S]+X] is not equal to X or if fts5yy_shift_ofst[S]
178786 ** is equal to fts5YY_SHIFT_USE_DFLT, it means that the action is not in the table
178789 ** The formula above is for computing the action when the lookahead is
178790 ** a terminal symbol. If the lookahead is a non-terminal (as occurs after
178791 ** a reduce action) then the fts5yy_reduce_ofst[] array is used in place of
178792 ** the fts5yy_shift_ofst[] array and fts5YY_REDUCE_USE_DFLT is used in place of
178858 ** and Z. Whenever one of the tokens X, Y, or Z is input to the parser
178859 ** but it does not parse, the type of the token is changed to ID and
178860 ** the parse is retried before an error is thrown.
178879 ** + The semantic value stored at this level of the stack. This is
178881 ** It is sometimes called the "minor" token.
178889 fts5YYCODETYPE major; /* The major token value. This is the code
178892 ** is the value of the token */
178896 /* The state of the parser is completely contained in an instance of
178926 ** and a prompt to preface each trace message. Tracing is turned off
178932 ** If NULL, then tracing is turned off.
178934 ** line of trace output. If NULL, then tracing is
179039 ** The only argument is a pointer to a function which works like
179046 ** A pointer to a parser. This pointer is used in subsequent calls
179077 ** or nonterminal. "fts5yymajor" is the symbol code, and "fts5yypminor" is
179079 ** deletions is derived from the %destructor and/or %token_destructor
179089 /* Here is inserted the actions which take place when a
179090 ** terminal or non-terminal is destroyed. This can happen
179091 ** when the symbol is popped from the stack during a
179092 ** reduce or during error processing or when a parser is
179093 ** being destroyed before it is finished parsing.
179137 ** If there is a destructor routine associated with the token which
179138 ** is popped from the stack, then call it.
179160 ** is defined in a %include section of the input grammar) then it is
179161 ** assumed that the input pointer is never NULL.
179286 ** The following routine is called if the stack overflows.
179297 /* Here code is inserted which will execute if the parser
179367 ** is used during the reduce.
179423 /* Check that the stack is large enough to grow by a single entry
179424 ** if the RHS of the rule is empty. This ensures that there is room
179614 /* Here code is inserted which will be executed whenever the
179643 ** The following is executed when the parser accepts
179658 /* Here code is inserted which will be executed whenever the
179666 ** The first argument is a pointer to a structure obtained from
179668 ** The second argument is the major token number. The third is
179669 ** the minor token. The fourth optional argument is whatever the
179670 ** user wants (and specified in the grammar) and is available for
179739 ** This is what we do if the grammar does define ERROR:
179744 ** it is legal to shift the error symbol, then shift
179790 /* If the fts5YYNOERRORRECOVERY macro is defined, then do not attempt to
179801 #else /* fts5YYERRORSYMBOL is not defined */
179802 /* This is what we do if the grammar does not define ERROR:
179806 ** * If the input token is $, then fail the parse.
179845 ** a legal notice, here is a blessing:
179863 ** common), each set of overlapping instances is treated as a single
179867 ** Usage is:
179967 ** z points to a buffer containing n bytes of text to append. If n is
179968 ** negative, everything up until the first '\0' is appended to the output.
179970 ** If *pRc is set to any value other than SQLITE_OK when this function is
179971 ** called, it is a no-op. If an error (i.e. an OOM condition) is encountered,
179972 ** *pRc is set to an error code before returning.
180215 ** The first time the bm25() function is called for a query, an instance
180216 ** of the following structure is allocated and populated.
180286 ** This is done using the standard BM25 formula as found on wikipedia:
180290 ** where "N" is the total number of documents in the set and nHit
180291 ** is the number that contain at least one instance of the phrase
180294 ** The problem with this is that if (N < 2*nHit), the IDF is
180295 ** negative. Which is undesirable. So the mimimum allowable IDF is
180408 ** a legal notice, here is a blessing:
180464 ** is called, it is a no-op.
180480 ** ensures that the byte following the buffer data is set to 0x00, even
180481 ** though this byte is not included in the pBuf->n count.
180494 ** Argument zFmt is a printf() style format string. This function performs
180498 ** following the buffer data is set to 0x00, even though this byte is not
180556 ** is called, it is a no-op.
180619 ** The previous position written to this list is *piPrev. *piPrev is set
180663 ** is non-negative, then it is the length of the string in bytes. Otherwise,
180664 ** the length of the string is determined using strlen().
180666 ** It is the responsibility of the caller to eventually free the returned
180667 ** buffer using sqlite3_free(). If an OOM error occurs, NULL is returned.
180746 /* Calculate a hash value for this term. This is the same hash checksum
180747 ** used by the fts5_hash.c module. This is not important for correct
180748 ** operation of the module, but is necessary to ensure that some tests
180801 ** a legal notice, here is a blessing:
180809 ** This is an SQLite module implementing full-text search.
180833 ** Argument pIn points to a character that is part of a nul-terminated
180835 ** the string that is not a white-space character.
180846 ** Argument pIn points to a character that is part of a nul-terminated
180848 ** the string that is not a "bareword" character.
180911 /* At this point, if the literal was an integer, the parse is
180912 ** finished. Or, if it is a floating point value, it may continue
180927 ** The first character of the string pointed to by argument z is guaranteed
180934 ** If the close-quote is found, the value returned is the byte offset of
180935 ** the character immediately following it. Or, if the close-quote is not
180936 ** found, -1 is returned. If -1 is returned, the buffer is left in an
180973 ** the quote characters. The conversion is done in-place. If the
180975 ** is a no-op.
181025 ** If successful, object pConfig is updated and SQLITE_OK returned. If
181026 ** an error occurs, an SQLite error code is returned and an error message
181027 ** may be left in *pzErr. It is the responsibility of the caller to
181209 ** quoted, *pbQuoted is also set to 1 before returning.
181211 ** If *pRc is other than SQLITE_OK when this function is called, it is
181212 ** a no-op (NULL is returned). Otherwise, if an OOM occurs within this
181213 ** function, *pRc is set to SQLITE_NOMEM before returning. *pRc is *not*
181311 ** If successful, SQLITE_OK is returned and *ppOut is set to point to the
181312 ** new Fts5Config object. If an error occurs, an SQLite error code is
181313 ** returned, *ppOut is set to NULL and an error message may be left in
181314 ** *pzErr. It is the responsibility of the caller to eventually free any
181489 ** The callback is invoked once for each token in the input text. The
181497 ** int iPos // Position of token in input (first token is 0)
181499 ** If the callback returns a non-zero value the tokenization is abandoned
181504 ** the callback returned SQLITE_DONE, this is not an error and this function
181506 ** because the callback returned another non-zero value, it is assumed
181523 ** Argument pIn points to the first character in what is expected to be
181525 ** If it actually is this, return a pointer to the ')'. Otherwise, return
181548 ** this is:
181763 ** a legal notice, here is a blessing:
181821 int bNomatch; /* True if entry is not a match */
181859 Fts5ExprNode *pNode; /* FTS5_STRING node this phrase is part of */
182155 ** pointing to the same rowid when this function is called. This function
182156 ** checks if the current rowid really is a match, and if so populates
182158 ** is set to true if this is really a match, or false otherwise.
182160 ** SQLITE_OK is returned if an error occurs, or an SQLite error code
182161 ** otherwise. It is not considered an error code if the current rowid is
182177 /* If the aStatic[] array is not large enough, allocate a large array
182287 ** close together to meet the NEAR constraint. Non-zero is returned if it
182290 ** If in/out parameter (*pRc) is set to other than SQLITE_OK when this
182291 ** function is called, it is a no-op. Or, if an error (e.g. SQLITE_NOMEM)
182292 ** occurs within this function (*pRc) is set accordingly before returning.
182293 ** The return value is undefined in both these cases.
182295 ** If no error occurs and non-zero (a match) is returned, the position-list
182296 ** of each phrase object is edited to contain only those entries that
182310 /* If the aStatic[] array is not large enough, allocate a large array
182327 ** of the NEAR constraint) is written over the original even as it is
182328 ** being read. This is safe as the entries for the new poslist are a
182329 ** subset of the old, so it is not possible for data yet to be read to
182400 int bDesc, /* True if iterator is "rowid DESC" */
182426 int bDesc, /* True if iterator is "rowid DESC" */
182456 Fts5Expr *pExpr, /* Expression that pNear is a part of */
182480 ** phrase is not a match, break out of the loop early. */
182503 ** Initialize all term iterators in the pNear object. If any term is found
182552 ** If pExpr is an ASC iterator, this function returns a value with the
182557 ** Otherwise, if this is a DESC iterator, the opposite is returned:
182611 ** This means that if the iteration order is ASC, then numerically larger
182612 ** rowids are considered larger. Or if it is the default DESC, numerically
182627 ** this function is called. This function checks if all term iterators
182629 ** If an EOF is reached before this happens, *pbEof is set to true before
182632 ** SQLITE_OK is returned if an error occurs, or an SQLite error code
182633 ** otherwise. It is not considered an error code if an iterator reaches
182656 ** the maximum rowid. Or, if the iterator is "ORDER BY rowid DESC", then it
182723 ** is valid - each iterator that points to a rowid before iFrom. */
182771 Fts5Expr *pExpr, /* Expression that pNear is a part of */
182774 /* As this "NEAR" object is actually a single phrase that consists
182776 ** fts5_index.c iterator object. This is much faster than synthesizing
182823 Fts5Expr *pExpr, /* Expression of which pNode is a part */
182868 ** Argument pNode is an FTS5_AND node.
182892 /* If the child node is now at EOF, so is the parent AND node. Otherwise,
182893 ** the child node is guaranteed to have advanced at least as far as
182894 ** rowid iLast. So if it is not at exactly iLast, pChild->iRowid is the
182975 ** without modifying it. Otherwise, pNode is advanced until it does point
182976 ** to a match or EOF is reached.
182979 Fts5Expr *pExpr, /* Expression of which pNode is a part */
183017 ** Set node pNode, which is part of expression pExpr, to point to the first
183021 ** It is not an error if there are no matches.
183070 ** parameter is passed a non-zero value, iteration is in descending rowid
183071 ** order. Or, if it is zero, in ascending order.
183074 ** visited is that with the smallest rowid that is larger than or equal
183080 ** is not considered an error if the query does not match any documents.
183096 /* If the iterator is not at a real match, skip forward until it is. */
183108 ** is not considered an error if the query does not match any documents.
183163 ** If argument pNear is NULL, then a new Fts5ExprNearset object is allocated
183164 ** and populated with pPhrase. Or, if pNear is not NULL, phrase pPhrase is
183252 /* If an error has already occurred, this is a no-op */
183326 ** This function is called by the parser to process a string token. The
183327 ** string may or may not be quoted. In any case it is tokenized and a
183334 int bPrefix /* True if there is a trailing "*" */
183472 ** is expected. If token pTok does not contain "NEAR", store an error
183516 ** The old colset object (if any) is not freed in this case.
183546 /* Check that the array is in order and contains no duplicate entries. */
183842 ** pointer to a buffer containing that representation. It is the
184107 ** single integer as an argument. If the integer is an alpha-numeric
184108 ** unicode code point, 1 is returned. Otherwise 0.
184145 ** This is called during initialization to register the fts5_expr() scalar
184167 /* Avoid a warning indicating that sqlite3Fts5ParserTrace() is unused */
184191 ** This function is used to access the current position list for phrase
184379 ** This function is only called for detail=columns tables.
184421 ** a legal notice, here is a blessing:
184439 ** to accumuluate "term -> doclist" content before it is flused to a level-0
184454 ** Each entry in the hash table is represented by an object of the
184459 ** The data that follows the key is in a similar, but not identical format
184460 ** to the doclist data stored in the database. It is:
184637 ** Add an entry to the in-memory hash table. The key is the concatenation
184638 ** of bByte and (pToken/nToken). The value is (iRowid/iCol/iPos).
184642 ** Or, if iCol is negative, then the value is a delete marker.
184712 /* Appending to an existing hash-entry. Check that there is enough
184714 ** is:
184739 /* If this is a new rowid, append the 4-byte size field for the previous
184779 /* This is a delete. Set the delete flag. */
184815 /* p2 is smaller */
184820 /* p1 is smaller */
184834 ** in sorted order. The hash table is cleared before returning. It is
184949 ** a legal notice, here is a blessing:
184971 ** The format is similar to FTS3/4, except that:
184973 ** * all segment b-tree leaf data is stored in fixed size page records
184974 ** (e.g. 1000 bytes). A single doclist may span multiple pages. Care is
184975 ** taken to ensure it is possible to iterate in either direction through
184981 ** the doclist. This is used to speed up seek operations, and merges of
184998 # error "FTS5_MAX_PREFIX_INDEXES is too large"
185018 ** there are one or more prefix indexes), it is guaranteed that all share
185039 ** A single record within the %_data table. The data is a list of varints.
185040 ** The first value is the number of rows in the index. Then, for each column
185048 ** Most of each segment leaf is taken up by term/doclist data. The
185050 ** on the leaf page, is:
185098 ** footer is 0 bytes in size, then this field is the same as the
185102 ** on the page. Each varint is the byte offset of the current term
185104 ** other words, the first varint in the footer is the byte offset of
185105 ** the first term, the second is the byte offset of the second less that
185108 ** The term/doclist format described above is accurate if the entire
185109 ** term/doclist data fits on a single leaf page. If this is not the case,
185110 ** the format is changed in two ways:
185113 ** is stored as a literal value:
185117 ** + the first term on each page is stored in the same way as the
185127 ** is:
185130 ** 0x01: Clear if leaf is also the root page, otherwise set.
185167 ** The rowid for each segment leaf is found by passing the segment id and
185197 ** Each time a blob is read from the %_data table, it is padded with this
185238 int bDelete; /* Current write is a delete */
185280 Fts5StructureSegment *aSeg; /* Array of segments. aSeg[0] is oldest. */
185291 ** An object of type Fts5SegWriter is used to write to segments.
185302 int bPrevValid; /* True if iPrev is valid */
185310 u8 bFirstRowidInDoclist; /* True if next rowid is first in doclist */
185311 u8 bFirstRowidInPage; /* True if next rowid is first in page */
185342 ** Byte offset within the current leaf that is the first byte of the
185344 ** rowid field of the current entry. Usually this is the size field of the
185345 ** position list data. The exception is if the rowid for the current entry
185346 ** is the last thing on the leaf page.
185363 ** This flag is only ever set if FTS5_SEGITER_ONETERM is also set. If
185364 ** it is set, iterate through rowid in descending order instead of the
185368 ** These are used if the FTS5_SEGITER_REVERSE flag is set.
185371 ** corresponding aRowidOffset[] entry is set to the byte offset of the
185389 ** is the offset of the first rowid in the current doclist. */
185396 /* The following are only used if the FTS5_SEGITER_REVERSE flag is set. */
185401 Fts5DlidxIter *pDlidx; /* If there is a doclist-index */
185407 u8 bDel; /* True if the delete flag is set */
185411 ** Argument is a pointer to an Fts5Data structure that contains a
185422 ** Argument is a pointer to an Fts5Data structure that contains a leaf
185436 ** nSeg is always a power of two greater than or equal to the number of
185437 ** segments that this object is merging data from. Both the aSeg[] and
185438 ** aFirst[] arrays are sized at nSeg entries. The aSeg[] array is padded
185442 ** The results of comparing segments aSeg[N] and aSeg[N+1], where N is an
185443 ** even number, is stored in aFirst[(nSeg+N)/2]. The "result" of the
185444 ** comparison in this context is the index of the iterator that currently
185449 ** the smallest key overall. aFirst[0] is unused.
185453 ** There is no way to tell if this is populated or not.
185477 ** An instance of the following type is used to iterate through the contents
185517 ** If an OOM error is encountered, return NULL and set the error code in
185527 ** Return -ve if pLeft is smaller than pRight, 0 if they are equal or
185528 ** +ve if pRight is smaller than pLeft. In other words:
185545 ** is a prefix of the other, it is considered the lesser.
185547 ** Return -ve if pLeft is smaller than pRight, 0 if they are equal or
185548 ** +ve if pRight is smaller than pLeft. In other words:
185565 ** Close the read-only blob handle, if it is open.
185579 ** If an error occurs, NULL is returned and an error left in the
185590 ** is required. */
185602 /* If the blob handle is not open at this point, open it and seek
185777 ** If an error occurs, *ppOut is set to NULL and an SQLite error code
185778 ** returned. Otherwise, *ppOut is set to point to the new object and
185878 ** Extend level iLvl so that there is room for at least nExtra more
185918 /* TODO: Do we need this if the leaf-index is appended? Probably... */
185961 ** If an error occurs, NULL is returned and an error code left in the
185963 ** is called, it is a no-op.
186013 ** function is only ever used as part of assert() conditions.
186045 ** error has already occurred, this function is a no-op.
186108 ** segments as possible to level iPromote. If an OOM occurs, NULL is
186117 int il, is;
186124 for(is=pLvl->nSeg-1; is>=0; is--){
186125 int sz = fts5SegmentSize(&pLvl->aSeg[is]);
186129 memcpy(pOut->aSeg, &pLvl->aSeg[is], sizeof(Fts5StructureSegment));
186142 ** a) If the segment just written is smaller than one or more segments
186143 ** within the previous populated level, it is promoted to the previous
186146 ** b) If the segment just written is larger than the newest segment on
186151 ** If one or more segments are promoted, the structure object is updated
186183 /* Condition (a) is true. Promote the newest segment on level
186190 /* If condition (a) is not met, assume (b) is true. StructurePromoteTo()
186191 ** is a no-op if it is not. */
186203 ** doclist-index page is reached, return non-zero.
186269 ** When this function is called pIter->iLeafPgno is the page number the
186270 ** doclist is associated with (the one featuring the term).
186340 ** set. So the last 0x00 is only a varint 0 if there are 8 more 0x80
186490 ** list, and *pbDel to true if the delete flag is set, or false otherwise.
186563 ** of the "nPrefix" field (if there was one - it is passed 0 if this is
186619 ** segment pSeg. The iterator is left pointing to the first entry when
186622 ** If an error occurs, Fts5Index.rc is set to an appropriate error code. If
186623 ** an error has already occurred when this function is called, it is a no-op.
186631 /* This happens if the segment is being used as an input to an incremental
186634 ** The caller will see the (pIter->pLeaf==0) and assume the iterator is
186659 ** This function is only ever called on iterators created by calls to
186662 ** The iterator is in an unusual state when this function is called: the
186663 ** Fts5SegIter.iLeafOffset variable is set to the offset of the start of
186665 ** Fts5SegIter.rowid is set, but nPos and bDel are not.
186670 ** is in its regular state - Fts5SegIter.iLeafOffset points to the first
186739 /* iTermLeafOffset may be equal to szLeaf if the term is the last
186740 ** thing on the page - i.e. the first rowid is on the following page.
186741 ** In this case leave pIter->pLeaf==0, this iterator is at EOF. */
186775 ** points to a delete marker. A delete marker is an entry with a 0 byte
186786 ** This version of fts5SegIterNext() is only used by reverse iterators.
186819 ** This version of fts5SegIterNext() is only used if detail=none and the
186820 ** iterator is not a reverse direction iterator.
186836 /* Next entry is on the next page */
186845 /* Next entry is on the current page */
186890 ** If an error occurs, Fts5Index.rc is set to an appropriate error code. It
186891 ** is not considered an error if the iterator reaches EOF. If an error has
186892 ** already occurred when this function is called, it is a no-op.
186917 /* The next entry is on the current page. */
186956 /* Next entry is not on the current page */
186989 /* Check if the iterator is now at EOF. If so, return early. */
187002 ** this block is particularly performance critical, so equivalent
187003 ** code is inlined.
187054 /* If this condition is true then the largest rowid for the current
187056 ** see where said rowid really is. */
187081 /* If pLast is NULL at this point, then the last rowid for this doclist
187083 ** pIter->iLeafOffset is already set to point to the position-list size
187086 ** Or, if pLast is non-NULL, then it is the page that contains the last
187112 ** There is a doclist-index associated with the final term on the current
187113 ** page. If the current term is the last term on the page, load the
187141 ** If the specified term is found on the page, then the iterator is left
187142 ** pointing to it. If argument bGe is zero and the term is not found,
187143 ** the iterator is left pointing at EOF.
187145 ** If bGe is non-zero and the specified term is not found, then the
187146 ** iterator is left pointing to the smallest term in the segment that
187147 ** is larger than the specified term, even if this term is not on the
187282 ** pSeg. If there is no such term in the index, the iterator is set to EOF.
187284 ** If an error occurs, Fts5Index.rc is set to an appropriate error code. If
187285 ** an error has already occurred when this function is called, it is a no-op.
187296 int bDlidx = 0; /* True if there is a doclist-index */
187305 ** contain term (pTerm/nTerm), if it is present in the segment. */
187363 ** in-memory hash table. If there is no such term in the hash-table, the
187364 ** iterator is set to EOF.
187366 ** If an error occurs, Fts5Index.rc is set to an appropriate error code. If
187367 ** an error has already occurred when this function is called, it is a no-op.
187431 ** This function is used as part of the big assert() procedure implemented by
187433 ** in *pRes is the correct result of comparing the current positions of the
187473 ** This function is a no-op unless SQLITE_DEBUG is defined when this module
187474 ** is compiled. In that case, this function is essentially an assert()
187485 /* Check that pIter->iSwitchRowid is set correctly. */
187518 ** If the returned value is non-zero, then it is the index of an entry
187519 ** in the pIter->aSeg[] array that is (a) not at EOF, and (b) pointing
187520 ** to a key that is a duplicate of another, higher priority,
187545 if( p1->pLeaf==0 ){ /* If p1 is at EOF */
187547 }else if( p2->pLeaf==0 ){ /* If p2 is at EOF */
187575 ** It is an error if leaf iLeafPgno does not exist or contains no rowids.
187611 ** Advance the iterator passed as the second argument until it is at or
187612 ** past rowid iFrom. Regardless of the value of iFrom, the iterator is
187703 ** If it does so successfully, 0 is returned. Otherwise 1.
187705 ** If non-zero is returned, the caller should call fts5MultiIterAdvanced()
187761 ** If an error occurs, an error code is left in Fts5Index.rc. It is not
187762 ** considered an error if the iterator reaches EOF, or if it is already at
187763 ** EOF when this function is called.
187768 int bFrom, /* True if argument iFrom is valid */
187927 /* Search through to find the first varint with value 1. This is the
188047 ** the position list contains entries for column iCol, then (*pa) is set
188057 int iCurrent = 0; /* Anything before the first 0x01 is col 0 */
188062 /* Advance pointer p until it points to pEnd or an 0x01 byte that is
188063 ** not part of a varint. Note that it is not possible for a negative
188080 /* Advance pointer p until it points to pEnd or an 0x01 byte that is
188129 /* All data is stored on the current page. Populate the output
188133 /* The data is distributed over two or more pages. Copy it into the
188143 ** xSetOutputs callback used by detail=col when there is a column filter
188159 ** * there is a column filter, and
188162 ** The last point is to ensure all column numbers are stored as
188203 ** xSetOutputs callback used by detail=full when there is a column filter.
188213 /* All data is stored on the current page. Populate the output
188226 /* The data is distributed over two or more pages. Copy it into the
188268 ** If iLevel is -ve, then all data in all segments is merged. Or, if iLevel
188269 ** is zero or greater, data from the first nSegment segments on level iLevel
188270 ** is merged.
188413 ** Return true if the iterator is at EOF or if an error has occurred.
188425 ** to. If the iterator points to EOF when this function is called the
188465 ** SQLITE_FULL is returned.
188467 ** If an error has already occurred, this function is a no-op. 0 is
188477 /* FTS5_MAX_SEGMENT is currently defined as 2000. So the following
188478 ** array is 63 elements, or 252 bytes, in size. */
188538 ** Buffer (pNew/<length-unknown>) is guaranteed to be greater
188597 ** If the current doclist-index accumulating in pWriter->aDlidx[] is large
188615 ** This function is called whenever processing of the doclist for the
188616 ** last term on leaf page (pWriter->iBtPage) is completed.
188618 ** The doclist-index for that term is currently stored in-memory within the
188619 ** Fts5SegWriter.aDlidx[] array. If it is large enough, this function
188620 ** writes it out to disk. Or, if it is too small to bother with, discards
188645 ** This is called once for each leaf page except the first that contains
188646 ** at least one term. Argument (nTerm/pTerm) is the split-key - a term that
188647 ** is larger than all terms written to earlier leaves, and equal to or
188650 ** If an error occurs, an error code is left in Fts5Index.rc. If an error
188651 ** has already occurred when this function is called, it is a no-op.
188664 ** This function is called when flushing a leaf page that contains no
188693 ** Rowid iRowid has just been appended to the current leaf page. It is the
188710 /* The current doclist-index page is full. Write it to disk and push
188713 ** hierarchy. If the node being flushed is currently the root node,
188804 ** already occurred, this function is a no-op.
188819 /* If the current leaf page is full, flush it to disk. */
188840 /* This is the first term on a leaf that is not the leftmost leaf in
188841 ** the segment b-tree. In this case it is necessary to add a term to
188842 ** the b-tree hierarchy that is (a) larger than the largest term
188844 ** this term. In other words, a prefix of (pTerm/nTerm) that is one
188848 ** Usually, the previous term is available in pPage->term. The exception
188849 ** is if this is the first term written in an incremental-merge step.
188850 ** In this case the previous term is not available, so just write a
188851 ** copy of (pTerm/nTerm) into the parent node. This is slightly
188896 /* If this is to be the first rowid written to the page, set the
188898 ** buffer, in case a doclist-index is required. */
189014 /* Bind the current output segment id to the index-writer. This is an
189023 ** incremental merge operation. This function is called if the incremental
189037 ** segment is now empty. */
189110 int bOldest; /* True if the output segment is the oldest */
189175 /* This is a new term. Append a term to the output segment. */
189270 /* If nBest is still 0, then the index must be empty. */
189296 ** already occurred, this function is a no-op.
189373 ** already occurred, this function is a no-op.
189502 /* Update the Fts5Structure. It is written back to the database by the
189528 /* Unless it is empty, flush the hash table to disk */
189580 ** the new Fts5Level object so that pLvl->aSeg[0] is the oldest
189629 ** This is called to implement the special "VALUES('merge', $nMerge)"
189761 ** This is the equivalent of fts5MergePrefixLists() for detail=none mode.
189808 ** If an error occurs, an error code is left in p->rc. If an error has
189809 ** already occurred, this function is a no-op.
190070 ** The %_data table is completely empty when this function is called. This
190084 ** Open a new Fts5Index handle. If the bCreate argument is true, create
190150 ** Argument p points to a buffer containing utf-8 text that is n bytes in
190171 ** pIn is a UTF-8 encoded string, nIn bytes in size. Return the number of
190187 ** Insert or remove data to or from the index. Each time a document is
190188 ** added to or removed from the index, this function is called one or more
190192 ** If the operation is a delete, it must be called (at least) once for each
190194 ** argument is ignored for a delete.
190243 /* If the QUERY_SCAN flag is set, all other flags must be clear. */
190251 ** is a prefix query for which there is no prefix index, set iIdx to
190257 ** evaluate the prefix query using the main FTS index. This is used
190309 ** Return true if the iterator passed as the only argument is at EOF.
190379 ** Parameter anSize must point to an array of size nCol, where nCol is
190457 ** Below this point is the implementation of the integrity-check
190483 ** This function is purely an internal test. It does not contribute to
190488 ** iSegid/iLeaf is iterated in forwards or reverse order.
190567 ** This function is also purely an internal test. It does not contribute to
190599 /* If this is a prefix query, check that the results returned if the
190600 ** the index is disabled are the same. In both ASC and DESC order.
190602 ** This check may only be performed if the hash table is empty. This
190603 ** is because the hash table only supports a single scan query at
190604 ** a time, and the multi-iter loop from which this function is called
190605 ** is already performing such a scan. */
190750 /* Check that the leaf contains at least one term, and that it is equal
190752 ** is also a rowid pointer within the leaf page header, it points to a
190785 /* If there is a doclist-index, check that it looks right. */
190832 /* TODO: Check there is no doclist index */
190851 ** Run internal checks to ensure that the FTS index (a) is internally
190853 ** as calculated by sqlite3Fts5IndexEntryCksum() is cksum.
190868 /* Used by extra internal tests only run if NDEBUG is not defined */
190888 /* The cksum argument passed to this function is a checksum calculated
190891 ** actual contents of FTS index is identical.
190898 ** same term is performed. cksum3 is calculated based on the entries
190911 /* If this is a new term, query for it. Update cksum3 with the results. */
190943 ** Below this point is the implementation of the fts5_decode() scalar
190948 ** Decode a segment-data rowid from the %_data table. This function is
191011 ** This is part of the fts5_decode() debugging aid.
191036 ** This is part of the fts5_decode() debugging aid.
191059 ** Buffer (a/n) is assumed to contain a list of serialized varints. Read
191061 ** after either the input buffer is exhausted or a 0 value is read.
191063 ** The return value is the number of bytes read from the input buffer.
191078 ** representation of the part of the doclist that is present to buffer
191081 ** The return value is the number of bytes read from the input buffer.
191109 ** This function is part of the fts5_decode() debugging function. It is
191116 ** If *pRc is other than SQLITE_OK when this function is called, it is a
191117 ** no-op. If an OOM or other error occurs within this function, *pRc is
191119 ** pBuf is undefined in this case.
191172 ** copy is followed by FTS5_DATA_ZERO_PADDING 0x00 bytes, which prevents
191173 ** buffer overreads even if the record is corrupt. */
191371 ** This is called as part of registering the FTS5 module with database
191375 ** If successful, SQLITE_OK is returned. If an error occurs, some other
191376 ** SQLite error code is returned instead.
191411 ** a legal notice, here is a blessing:
191419 ** This is an SQLite module implementing full-text search.
191426 ** This variable is set to false when running tests for which the on disk
191427 ** structures should not be corrupt. Otherwise, true. If it is false, extra
191429 ** only true if it is guaranteed that the fts5 database is not corrupt.
191452 ** Anything that is required as part of a commit that may fail is performed
191463 ** in-memory. It is flushed to disk whenever xSync(), xRelease() or
191464 ** xSavepoint() is called. And discarded whenever xRollback() or xRollbackTo()
191465 ** is called.
191467 ** Additionally, if SQLITE_DEBUG is defined, an instance of the following
191468 ** structure is used to record the current transaction state. This information
191469 ** is not required, but it is used in the assert() statements executed by
191478 ** A single object of this type is allocated when the FTS5 module is
191479 ** registered with a database handle. It is used to store pointers to
191493 ** Each auxiliary function registered with the FTS5 module is represented
191507 ** Each tokenizer module registered with the FTS5 module is represented
191544 ** There is one entry in the aIdx[] array for each phrase in the query,
191545 ** the value of which is the offset within aPoslist[] following the last
191561 ** If this is a 'special' query (refer to function fts5SpecialMatch()),
191566 ** cursor iterates in ascending order of rowids, iFirstRowid is the lower
191573 ** is the upper limit (i.e. the "first" rowid visited) and iLastRowid
191713 ** Return true if pTab is a contentless table.
191752 ** This function is the implementation of both the xConnect and xCreate
191826 ** work is done in function fts5InitVtab().
191861 ** extension is currently being used by a version of SQLite too old to
191862 ** support index-info flags. In that case this function is a no-op.
191892 ** a) If an unusable MATCH operator is present in the WHERE clause, the
191893 ** cost is unconditionally set to 1e50 (a really big number).
191895 ** a) If a MATCH operator is present, the cost depends on the other
191903 ** b) Otherwise, if there is no MATCH:
191954 /* As there exists an unusable MATCH constraint this is an
192051 ** This function is called after the cursor passed as the only argument
192052 ** is moved to point at a different row. It clears all cached data
192178 ** If the REQUIRE_RESEEK flag is set on the cursor passed as the first
192180 ** is using. Then attempt to move the cursor to a rowid equal to or laster
192183 ** If the new rowid is not equal to the old, set output parameter *pbSkip
192217 ** Return SQLITE_OK if nothing goes wrong. SQLITE_OK is returned
192311 ** is not possible as SQLite reference counts the virtual table objects.
192353 ** Process a "special" query. A special query is identified as one with a
192390 ** pTab. If one is found, return a pointer to the corresponding Fts5Auxiliary
192503 ** This is the xFilter interface for the virtual table. See
192567 ** actually use them. This is ok, as the xBestIndex() method leaves the
192582 /* If pSortCsr is non-NULL, then this call is being made as part of
192583 ** processing for a "... MATCH <expr> ORDER BY rank" query (ePlan is
192584 ** set to FTS5_PLAN_SORTED_MATCH). pSortCsr is the cursor that will
192586 ** (pCursor) is used to execute the query issued by function
192603 ** indicates that the MATCH expression is not a full text query,
192626 /* This is either a full-table scan (ePlan==FTS5_PLAN_SCAN) or a lookup
192648 ** This is the xEof method of the virtual table. SQLite calls this
192672 ** This is the xRowid method. The SQLite core calls this routine to
192702 ** If the cursor requires seeking (bSeekRequired flag is set), seek it.
192705 ** If argument bErrormsg is true and an error occurs, an error message may
192749 ** This function is called to handle an FTS INSERT command. In other words,
192755 ** Argument pVal is the value assigned to column "fts" by the INSERT
192848 ** This function is the implementation of the xUpdate callback used by
192849 ** FTS3 virtual tables. It is invoked by SQLite each time a row is to be
192872 /* A transaction must be open when this is called. */
192901 /* A regular INSERT, UPDATE or DELETE statement. The trick here is that
192921 ** This is not suported. */
192938 /* If this is a REPLACE, first remove the current entry (if any) */
193003 ** Implementation of xCommit() method. This is a no-op. The contents of
193008 UNUSED_PARAM(pVtab); /* Call below is a no-op for NDEBUG builds */
193639 ** A position-list blob begins with (nPhrase-1) varints, where nPhrase is
193645 ** list 1. And so on. There is no size field for the final position list,
193702 ** This is the xColumn method, called by SQLite to request a value from
193724 /* User is requesting the value of the special column with the same name
193725 ** as the table. Return the cursor integer id number. This value is only
193796 UNUSED_PARAM(iSavepoint); /* Call below is a no-op for NDEBUG builds */
193805 ** This is a no-op.
193809 UNUSED_PARAM(iSavepoint); /* Call below is a no-op for NDEBUG builds */
193822 UNUSED_PARAM(iSavepoint); /* Call below is a no-op for NDEBUG builds */
193867 ** Register a new tokenizer. This is the implementation of the
193923 ** Find a tokenizer. This is the implementation of the
194085 /* If SQLITE_FTS5_ENABLE_TEST_MI is defined, assume that the file
194086 ** fts5_test_mi.c is compiled and linked into the executable. And call
194100 ** this module is being built as part of the SQLite core (SQLITE_CORE is
194103 ** Or, if this module is being built as a loadable extension,
194104 ** sqlite3Fts5Init() is omitted and the two standard entry points
194143 ** a legal notice, here is a blessing:
194200 /* If there is no %_docsize table, there should be no requests for
194406 ** Open a new Fts5Index handle. If the bCreate argument is true, create
194522 ** If a row with rowid iDel is present in the %_content table, add the
194581 ** If there is no %_docsize table (as happens if the columnsize=0 option
194582 ** is specified when the FTS5 table is created), this function is a no-op.
194606 ** argument bCache is true, set the p->bTotalsValid flag to indicate
194791 ** Allocate a new rowid. This is used for "external content" tables when
194792 ** a NULL value is inserted into the rowid column. The new rowid is allocated
194796 ** If the %_docsize table does not exist, SQLITE_MISMATCH is returned. In
194797 ** this case the user is required to provide a rowid explicitly.
195174 ** An SQLite error code is returned if an error occurs, or SQLITE_OK
195278 ** a legal notice, here is a blessing:
195296 ** is the same as the set of ASCII range alphanumeric characters.
195400 int is = 0;
195409 while( is<nText && rc==SQLITE_OK ){
195413 while( is<nText && ((pText[is]&0x80)==0 && a[(int)pText[is]]==0) ){
195414 is++;
195416 if( is==nText ) break;
195419 ie = is+1;
195425 nByte = ie-is;
195435 asciiFold(pFold, &pText[is], nByte);
195438 rc = xToken(pCtx, 0, pFold, nByte, is, ie);
195439 is = ie+1;
195454 ** from the sqlite3 source file utf.c. If this file is compiled as part
195510 int bRemoveDiacritic; /* True if remove_diacritics=1 is set */
195656 ** passed as the first argument, codepoint iCode is considered a token
195690 int is;
195697 /* A character outside of the ascii range. Skip past it if it is
195698 ** a separator character. Or break out of the loop if it is not. */
195699 is = zCsr - (unsigned char*)pText;
195706 is = zCsr - (unsigned char*)pText;
195717 /* Grow the output buffer so that there is sufficient space to fit the
195735 ** it is a token character, or break out of the loop if it is not. */
195760 rc = xToken(pCtx, 0, aFold, zOut-aFold, is, ie);
196521 ** a legal notice, here is a blessing:
196542 ** is less than zero.
196553 ** C. It is not possible to represent a range larger than 1023 codepoints
196669 ** If the argument is a codepoint corresponding to a lowercase letter
196724 ** is a diacritical modifier character.
196738 ** is an upper case character that has a lower case equivalent,
196743 ** is less than zero.
196750 ** If the least significant bit in flags is clear, then the rule applies
196752 ** need to be folded). Or, if it is set, then the rule only applies to
196757 ** case equivalent is ((C + aiOff[flags>>1]) & 0xFFFF).
196882 ** a legal notice, here is a blessing:
196897 ** This is a copy of the sqlite3GetVarint32() routine from the SQLite core.
196899 ** version depends on being handled before its function is called.
196942 /* A 32-bit varint is used to store size information in btrees.
196944 ** A 3-byte varint is sufficient, for example, to record the size
196977 ** Return the number of bytes read. The value is stored in *v.
197139 ** The variable-length integer encoding is as follows:
197166 ** of bytes written is returned.
197171 ** 8 bits and is the last byte.
197228 ** a legal notice, here is a blessing:
197236 ** This is an SQLite virtual table module implementing direct access to an
197243 ** One row for each term/column combination. The value of $doc is set to
197245 ** $term within column $col. Field $cnt is set to the total number of
197251 ** One row for each term in the database. The value of $doc is set to
197253 ** $term. Field $cnt is set to the total number of instances of term
197278 int bEof; /* True if this cursor is at EOF */
197357 ** This function is the implementation of both the xConnect and xCreate
197436 ** work is done in function fts5VocabInitVtab().
197711 ** This is the xFilter implementation for the virtual table.
197772 ** This is the xEof method of the virtual table. SQLite calls this
197820 ** This is the xRowid method. The SQLite core calls this routine to