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
33 ** a legal notice, here is a blessing:
52 ** measured by branch coverage. This is
56 ** OPTIMIZATION-IF-TRUE - This branch is allowed to always be false
57 ** and the correct answer is still obtained,
60 ** OPTIMIZATION-IF-FALSE - This branch is allowed to always be true
61 ** and the correct answer is still obtained,
74 ** Make sure the Tcl calling convention macro is defined. This macro is
93 ** a legal notice, here is a blessing:
101 ** This file contains code that is specific to MSVC.
147 ** a legal notice, here is a blessing:
155 ** This file contains code that is specific to Wind River's VxWorks
158 /* This is VxWorks. Set up things specially for that OS
169 /* This is not VxWorks. */
182 ** large file support, or if the OS is windows, these should be no-ops.
189 ** on the compiler command line. This is necessary if you are compiling
192 ** without this option, LFS is enable. But LFS does not exist in the kernel
196 ** The previous paragraph was written in 2005. (This paragraph is written
201 ** Similar is true for Mac OS X. LFS is only supported on Mac OS X 9 and later.
213 ** value of 0 means that compiler is not being used. The
237 ** is associated with Visual Studio 2013 or higher.
269 ** files; however, the contained version information is now required by this
271 ** this is the only known way to reliably obtain it. This entire #if block
287 ** define is required to maintain binary compatibility with the MSVC runtime
299 ** If SQLITE_CUSTOM_INCLUDE=? is defined, its value names the #include
318 ** a legal notice, here is a blessing:
327 ** or constant definition does not appear in this file, then it is
328 ** not a published API of SQLite, is subject to change without
337 ** The official C-language API documentation for SQLite is derived
338 ** from comments in this file. This file is the authoritative source
341 ** The name of this file under configuration management is "sqlite.h.in".
366 ** The SQLITE_CDECL macro is used to set the calling convention for
369 ** The SQLITE_APICALL macro is used to set the calling convention for
372 ** The SQLITE_STDCALL macro is no longer used and is now deprecated.
374 ** The SQLITE_CALLBACK macro is used to set the calling convention for
377 ** The SQLITE_SYSAPI macro is used to set the calling convention for
436 ** evaluates to a string literal that is the SQLite version in the
437 ** format "X.Y.Z" where X is the major version number (always 3 for
438 ** SQLite3) and Y is the minor version number and Z is the release number.)^
443 ** be larger than the release from which it is derived. Either Y will
475 ** the header, and thus ensure that the application is
487 ** function is provided for use in DLLs since DLL users usually do not have
491 ** a pointer to a string constant whose value is the same as the
492 ** [SQLITE_SOURCE_ID] C preprocessor macro. Except if SQLite is built
513 ** returning the N-th compile time option string. ^If N is out of range,
515 ** prefix is omitted from any strings returned by
541 ** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
542 ** are enabled and SQLite is threadsafe. When the
543 ** [SQLITE_THREADSAFE] macro is 0,
544 ** the mutexes are omitted. Without the mutexes, it is not safe
548 ** So if speed is of utmost importance, it makes sense to disable
550 ** ^The default behavior is for mutexes to be enabled.
553 ** version of SQLite that it is linking against was compiled with
557 ** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with
565 ** is unchanged by calls to sqlite3_config().)^
575 ** Each open SQLite database is represented by a pointer to an instance of
576 ** the opaque structure named "sqlite3". It is useful to think of an sqlite3
591 ** Because there is no cross-platform way to specify 64-bit integer types
635 ** the [sqlite3] object is successfully destroyed and all associated
642 ** ^If the database connection is associated with unfinalized prepared
645 ** [SQLITE_BUSY]. ^If sqlite3_close_v2() is called with unfinalized prepared
652 ** is intended for use with host languages that are garbage collected, and
653 ** where the order in which destructors are called is arbitrary.
655 ** ^If an [sqlite3] object is destroyed while a transaction is open,
656 ** the transaction is automatically rolled back.
664 ** argument is a harmless no-op.
671 ** This is legacy and deprecated. It is included for historical
672 ** compatibility and is not documented.
680 ** The sqlite3_exec() interface is a convenience wrapper around
689 ** sqlite3_exec() is not NULL, then it is invoked for each result row
691 ** sqlite3_exec() is relayed through to the 1st argument of each
693 ** is NULL, then no callback is ever invoked and result rows are
699 ** is not NULL then any error message is written into memory obtained
703 ** sqlite3_exec() after the error message string is no longer needed.
704 ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
712 ** ^The 2nd argument to the sqlite3_exec() callback function is the
714 ** callback is an array of pointers to strings obtained as if from
716 ** result row is NULL then the corresponding string pointer for the
717 ** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
718 ** sqlite3_exec() callback is an array of pointers to strings where each
722 ** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
725 ** is not changed.
731 ** is a valid and open [database connection].
733 ** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
735 ** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
763 #define SQLITE_BUSY 5 /* The database file is locked */
764 #define SQLITE_LOCKED 6 /* A table in the database is locked */
769 #define SQLITE_CORRUPT 11 /* The database disk image is malformed */
771 #define SQLITE_FULL 13 /* Insertion failed because database is full */
784 #define SQLITE_NOTADB 26 /* File opened that is not a database file */
896 ** though future versions of SQLite might change so that an error is
938 ** object returns an integer which is a vector of these
946 ** are aligned to an address which is an integer multiple of
948 ** that when data is appended to a file, the data is appended
949 ** first then the size of the file is extended, never the other
951 ** information is written to disk in the same order as calls
958 ** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
991 ** The argument to xLock() is always SHARED or higher. The argument to
992 ** xUnlock is either SHARED or NONE.
1007 ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
1037 ** for their own use. The pMethods entry is a pointer to an
1059 ** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
1063 ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
1064 ** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
1078 ** xLock() is always on of SHARED, RESERVED, PENDING, or EXCLUSIVE, never
1079 ** SQLITE_LOCK_NONE. If the database file lock is already at or above the
1080 ** requested lock, then the call to xLock() is a no-op.
1082 * If the lock is already at or below the requested lock state, then the call
1083 ** to xUnlock() is a no-op.
1085 ** either in this process or in some other process, is holding a RESERVED,
1089 ** The xFileControl() method is a generic interface that allows custom
1091 ** [sqlite3_file_control()] interface. The second "op" argument is an
1092 ** integer opcode. The third argument is a generic pointer intended to
1099 ** A [file control opcodes | list of opcodes] less than 100 is available.
1106 ** device that underlies the file. The sector size is the
1133 ** are aligned to an address which is an integer multiple of
1135 ** that when data is appended to a file, the data is appended
1136 ** first then the size of the file is extended, never the other
1138 ** information is written to disk in the same order as calls
1184 ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
1189 ** This capability is only available if SQLite is compiled with [SQLITE_DEBUG].
1192 ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
1194 ** current transaction. This hint is not guaranteed to be accurate but it
1195 ** is often close. The underlying VFS might choose to preallocate database
1200 ** The [SQLITE_FCNTL_SIZE_LIMIT] opcode is used by in-memory VFS that
1202 ** of the in-memory database. The argument is a pointer to a [sqlite3_int64].
1203 ** If the integer pointed to is negative, then it is filled in with the
1204 ** current limit. Otherwise the limit is set to the larger of the value
1206 ** pointed to is set to the new limit.
1209 ** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
1218 ** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
1223 ** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
1232 ** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
1233 ** sent to the VFS immediately before the xSync method is invoked on a
1234 ** database file descriptor. Or, if the xSync method is not invoked
1236 ** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place
1238 ** this file-control is NULL. However, if the database file is being synced
1246 ** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite
1248 ** but before the database is unlocked. VFSes that do not need this signal
1254 ** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
1263 ** within the same process. The argument is a pointer to an array of two
1264 ** integers where the first integer is the new retry count and the second
1265 ** integer is the delay. If either integer is negative, then the setting
1266 ** is not changed but instead the prior value of that setting is written
1268 ** interrogated. The zDbName parameter is ignored.
1271 ** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
1277 ** close. Persisting the files is useful when other processes that do not
1282 ** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
1283 ** WAL mode. If the integer is -1, then it is overwritten with the current
1287 ** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
1292 ** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
1293 ** mode. If the integer is -1, then it is overwritten with the current
1297 ** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening
1298 ** a write transaction to indicate that, unless it is rolled back for some
1300 ** transaction. This is used by VACUUM operations.
1306 ** [sqlite3_malloc()] and the result is stored in the char* variable
1308 ** The caller is responsible for freeing the memory when done. As with
1309 ** all file-control actions, there is no guarantee that this will actually
1311 ** pointer in case this file-control is not implemented. This file-control
1312 ** is intended for diagnostic use only.
1324 ** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]
1325 ** file control is sent to the open [sqlite3_file] object corresponding
1327 ** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
1329 ** is the name of the pragma and the third element is the argument to the
1339 ** prepared statement if result string is NULL, or that returns a copy
1340 ** of the result string if the string is non-NULL.
1346 ** it is able to override built-in [PRAGMA] statements.
1351 ** shortly after it is opened in order to provide a custom VFS with access
1352 ** to the connection's busy-handler callback. The argument is of type (void**)
1363 ** temporary filename using the same algorithm that is followed to generate
1370 ** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the
1372 ** The argument is a pointer to a value of type sqlite3_int64 that
1373 ** is an advisory maximum number of bytes in the file to memory map. The
1374 ** pointer is overwritten with the old value. The limit is not changed if
1375 ** the value originally pointed to is negative, and so the current limit
1377 ** file-control is used internally to implement [PRAGMA mmap_size].
1382 ** This file control is used by some VFS activity tracing [shims].
1383 ** The argument is a zero-terminated string. Higher layers in the
1385 ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
1400 ** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This
1402 ** pointed to by the pArg argument. This capability is used during testing
1403 ** and only needs to be supported when SQLITE_TEST is defined.
1406 ** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might
1407 ** be advantageous to block on the next WAL lock if the lock is not immediately
1413 ** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other
1417 ** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
1423 ** the file descriptor is placed in "batch write mode", which
1440 ** ^Regardless of whether or not it is successful, this file control takes
1456 ** The [SQLITE_FCNTL_LOCK_TIMEOUT] opcode is used to configure a VFS
1459 ** The parameter is a pointer to a 32-bit signed integer that contains
1460 ** the value that M is to be set to. Before returning, the 32-bit signed
1461 ** integer is overwritten with the previous value of M.
1464 ** The [SQLITE_FCNTL_DATA_VERSION] opcode is used to detect changes to
1465 ** a database file. The argument is a pointer to a 32-bit unsigned integer.
1466 ** The "data version" for the pager is written into the pointer. The
1478 ** but omits changes implemented by the database connection on which it is
1479 ** called. This file control is the only mechanism to detect changes that
1484 ** The [SQLITE_FCNTL_CKPT_START] opcode is invoked from within a checkpoint
1489 ** The [SQLITE_FCNTL_CKPT_DONE] opcode is invoked from within a checkpoint
1491 ** file to the database file, but before the *-shm file is updated to
1495 ** The EXPERIMENTAL [SQLITE_FCNTL_EXTERNAL_READER] opcode is used to detect
1496 ** whether or not there is a database client in another process with a wal-mode
1497 ** transaction open on the database or not. It is only available on unix.The
1499 ** value of type (int). The integer value is set to 1 if the database is a wal
1501 ** currently has an SQL transaction open on the database. It is set to 0 if
1502 ** the database is not a wal-mode db, or if there is no such connection in any
1507 ** The [SQLITE_FCNTL_CKSM_FILE] opcode is for use internally by the
1511 ** If there is currently no transaction open on the database, and the
1512 ** database is not a temp db, then the [SQLITE_FCNTL_RESET_CACHE] file-control
1513 ** purges the contents of the in-memory page cache. If there is an open
1514 ** transaction, or if the db is a temp-db, this opcode is a no-op, not an error.
1580 ** A pointer to the opaque sqlite3_api_routines structure is passed as
1590 ** Type [sqlite3_filename] is used by SQLite to pass filenames to the
1615 ** The VFS interface is sometimes extended by adding new methods onto
1617 ** is incremented. The iVersion value started out as 1 in
1628 ** The szOsFile field is the size of the subclassed [sqlite3_file]
1629 ** structure used by this VFS. mxPathname is the maximum length of
1639 ** The pNext field is the only field in the sqlite3_vfs
1650 ** is either a NULL pointer or string obtained
1652 ** ^If a suffix is added to the zFilename parameter, it will
1656 ** the string will be valid and unchanged until xClose() is
1660 ** If the zFilename parameter to xOpen is a NULL pointer then xOpen
1662 ** xFilename parameter is NULL it will also be the case that the
1667 ** or [sqlite3_open16()] is used, then flags includes at least
1703 ** deleted when it is closed. ^The [SQLITE_OPEN_DELETEONCLOSE]
1707 ** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
1711 ** SQLITE_OPEN_CREATE, is used to indicate that file should always
1712 ** be created, and that it is an error if it already exists.
1713 ** It is <i>not</i> used to indicate the file should be opened
1729 ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
1730 ** to test whether a file is at least readable. The SQLITE_ACCESS_READ
1731 ** flag is never actually used and is not implemented in the built-in
1732 ** VFSes of SQLite. The file is named by the second argument and can be a
1734 ** non-zero error code if there is an I/O error or if the name of
1735 ** the file given in the second argument is illegal. If SQLITE_OK
1736 ** is returned, then non-zero or zero is written into *pResOut to indicate
1737 ** whether or not the file is accessible.
1741 ** is also passed as a parameter to both methods. If the output buffer
1742 ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
1750 ** of good-quality randomness into zOut. The return value is
1760 ** date and time if that method is available (if iVersion is 2 or
1761 ** greater and the function pointer is not NULL) and will fall back
1762 ** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
1774 ** any of these methods if the iVersion of the VFS is less than 3.
1822 ** what kind of permissions the xAccess method is looking for.
1826 ** checks whether the named directory is both readable and writable
1829 ** The SQLITE_ACCESS_READWRITE constant is currently used only by the
1833 ** checks whether the file is readable. The SQLITE_ACCESS_READ constant is
1889 ** A call to sqlite3_initialize() is an "effective" call if it is
1890 ** the first time sqlite3_initialize() is invoked during the lifetime of
1891 ** the process, or if it is the first time sqlite3_initialize() is invoked
1896 ** A call to sqlite3_shutdown() is an "effective" call if it is the first
1901 ** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
1902 ** is not. The sqlite3_shutdown() interface must only be called from a
1912 ** ^If for some reason, sqlite3_initialize() is unable to initialize
1913 ** the library (perhaps it is unable to allocate a needed resource such
1916 ** ^The sqlite3_initialize() routine is called internally by many other
1920 ** initialized when [sqlite3_open()] is called if it has not be initialized
1921 ** already. ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
1925 ** it is recommended that applications always invoke sqlite3_initialize()
1928 ** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
1942 ** interface is called automatically by sqlite3_initialize() and
1943 ** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
1945 ** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
1962 ** The sqlite3_config() interface is used to make global configuration
1964 ** the application. The default configuration is recommended for most
1965 ** applications and so this routine is usually not necessary. It is
1968 ** <b>The sqlite3_config() interface is not threadsafe. The application
1970 ** threads while sqlite3_config() is running.</b>
1972 ** The first argument to sqlite3_config() is an integer
1974 ** what property of SQLite is to be configured. Subsequent arguments
1983 ** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
1984 ** [sqlite3_shutdown()] with a first argument that is not an anytime
1989 ** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
1990 ** ^If the option is unknown or SQLite is unable to set the option
1999 ** The sqlite3_db_config() interface is used to make configuration
2000 ** changes to a [database connection]. The interface is similar to
2004 ** The second argument to sqlite3_db_config(D,V,...) is the
2006 ** that indicates what aspect of the [database connection] is being configured.
2010 ** the call is considered successful.
2020 ** This object is used in only one place in the SQLite interface.
2021 ** A pointer to an instance of this object is the argument to
2022 ** [sqlite3_config()] when the configuration option is
2032 ** and that this object is only useful to a tiny minority of applications
2033 ** with specialized memory allocation requirements. This object is
2042 ** xRealloc is always a value returned by a prior call to xRoundup.
2046 ** is always at least as big as the requested size but may be larger.
2058 ** structures. The xShutdown method is invoked (indirectly) by
2060 ** by xInit. The pAppData pointer is used as the only parameter to
2065 ** xShutdown method is only called from [sqlite3_shutdown()] so it does
2068 ** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
2069 ** it is by default) and so the methods are automatically serialized.
2070 ** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
2100 ** ^Calling [sqlite3_config()] with a first argument that is not an
2102 ** [sqlite3_shutdown()] is a no-op that returns SQLITE_MISUSE.
2107 ** options is:
2118 ** is invoked.
2125 ** by a single thread. ^If SQLite is compiled with
2127 ** it is not possible to change the [threading mode] from its default
2136 ** The application is responsible for serializing access to
2140 ** [database connection] at the same time. ^If SQLite is compiled with
2142 ** it is not possible to set the Multi-thread [threading mode] and
2151 ** In this mode (which is the default when SQLite is compiled with
2154 ** application is free to use the same [database connection] or the
2156 ** ^If SQLite is compiled with
2158 ** it is not possible to set the Serialized [threading mode] and
2163 ** <dd> ^(The SQLITE_CONFIG_MALLOC option takes a single argument which is
2173 ** is a pointer to an instance of the [sqlite3_mem_methods] structure.
2175 ** structure is filled with the currently defined memory allocation routines.)^
2184 ** SQLite will run faster if it is free to make large memory allocations,
2187 ** allocations are avoided. This hint is normally off.
2202 ** ^Memory allocation statistics are enabled by default unless SQLite is
2208 ** <dd> The SQLITE_CONFIG_SCRATCH option is no longer used.
2215 ** This configuration option is a no-op if an application-defined page
2216 ** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
2224 ** ^It is harmless, apart from the wasted memory,
2228 ** subsequent behavior is undefined.
2229 ** ^When pMem is not NULL, SQLite will strive to use the memory provided
2231 ** a page cache line is larger than sz bytes or if all of the pMem buffer
2232 ** is exhausted.
2233 ** ^If pMem is NULL and N is non-zero, then each database connection
2235 ** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
2236 ** of -1024*N bytes if N is negative, . ^If additional
2237 ** page cache memory is needed beyond what is provided by the initial
2245 ** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
2251 ** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
2254 ** memory pointer is not NULL then the alternative memory
2255 ** allocator is engaged to handle all of SQLites memory allocation needs.
2258 ** The minimum allocation size is capped at 2**12. Reasonable values
2262 ** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
2267 ** [sqlite3_config()] returns. ^If SQLite is compiled with
2269 ** the entire mutexing subsystem is omitted from the build and hence calls to
2275 ** is a pointer to an instance of the [sqlite3_mutex_methods] structure. The
2277 ** structure is filled with the currently defined mutex routines.)^
2280 ** profiling or testing, for example. ^If SQLite is compiled with
2282 ** the entire mutexing subsystem is omitted from the build and hence calls to
2289 ** The first argument is the
2290 ** size of each lookaside buffer slot and the second is the number of
2297 ** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
2304 ** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies of
2308 ** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
2312 ** and a pointer to void. ^If the function pointer is not NULL, it is
2314 ** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
2315 ** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
2317 ** function whenever that function is invoked. ^The second parameter to
2318 ** the logger function is a copy of the first parameter to the corresponding
2319 ** [sqlite3_log()] call and is intended to be a [result code] or an
2320 ** [extended result code]. ^The third parameter passed to the logger is
2322 ** The SQLite logging interface is not reentrant; the logger function
2329 ** If non-zero, then URI handling is globally enabled. If the parameter is zero,
2330 ** then URI handling is globally disabled.)^ ^If URI handling is globally
2334 ** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
2335 ** connection is opened. ^If it is globally disabled, filenames are
2336 ** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
2337 ** database connection is opened. ^(By default, URI handling is globally
2343 ** argument which is interpreted as a boolean in order to enable or disable
2345 ** ^The default setting is determined
2346 ** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
2347 ** if that compile-time option is omitted.
2349 ** is because some incorrectly coded legacy applications might malfunction
2350 ** when the optimization is enabled. Providing the ability to
2362 ** <dd>This option is only available if sqlite is compiled with the
2365 ** The second should be of type (void*). The callback is invoked by the library
2367 ** fourth parameter. If the fourth parameter is 0, then the database connection
2370 ** fourth parameter is 1, then the SQL statement that the third parameter
2371 ** points to has just been executed. Or, if the fourth parameter is 2, then
2372 ** the connection being passed as the second parameter is being closed. The
2373 ** third parameter is passed NULL In this case. An example of using this
2388 ** ^If either argument to this option is negative, then that argument is
2393 ** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
2401 ** is a pointer to an integer and writes into that integer the number of extra
2409 ** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
2410 ** sorter to that integer. The default minimum PMA Size is set by the
2413 ** is enabled (using the [PRAGMA threads] command) and the amount of content
2423 ** Or if the threshold is -1, statement journals are always held
2428 ** The default value for this setting is controlled by the
2440 ** is stored in each sorted record and the required column values loaded
2442 ** value for this option is to never use this optimization. Specifying a
2444 ** This option is only available if SQLite is compiled with the
2450 ** [sqlite3_int64] parameter which is the default maximum size for an in-memory
2454 ** configuration setting is never used, then the default maximum is determined
2456 ** compile-time option is not set, then the default maximum is 1073741824.
2470 /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
2500 ** is invoked.
2507 ** ^The first argument (the third parameter to [sqlite3_db_config()] is a
2511 ** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
2512 ** size of each lookaside buffer slot. ^The third argument is the number of
2516 ** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
2519 ** connection is not currently using lookaside memory, or in other words
2521 ** [sqlite3_db_status](D,[SQLITE_DBSTATUS_LOOKASIDE_USED],...) is zero.
2523 ** memory is in use leaves the configuration unchanged and returns
2528 ** <dd> ^This option is used to enable or disable the enforcement of
2530 ** The first argument is an integer which is 0 to disable FK enforcement,
2532 ** unchanged. The second parameter is a pointer to an integer into which
2533 ** is written 0 or 1 to indicate whether FK enforcement is off or on
2535 ** which case the FK enforcement setting is not reported back. </dd>
2539 ** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
2541 ** The first argument is an integer which is 0 to disable triggers,
2543 ** The second parameter is a pointer to an integer into which
2544 ** is written 0 or 1 to indicate whether triggers are disabled or enabled
2546 ** which case the trigger setting is not reported back.
2550 ** this option is off. So, in other words, this option now only disables
2556 ** <dd> ^This option is used to enable or disable [CREATE VIEW | views].
2558 ** The first argument is an integer which is 0 to disable views,
2560 ** The second parameter is a pointer to an integer into which
2561 ** is written 0 or 1 to indicate whether views are disabled or enabled
2563 ** which case the view setting is not reported back.
2567 ** this option is off. So, in other words, this option now only disables
2573 ** <dd> ^This option is used to enable or disable the
2574 ** [fts3_tokenizer()] function which is part of the
2577 ** The first argument is an integer which is 0 to disable fts3_tokenizer() or
2580 ** The second parameter is a pointer to an integer into which
2581 ** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled
2583 ** which case the new setting is not reported back. </dd>
2587 ** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()]
2592 ** When the first argument to this interface is 1, then only the C-API is
2594 ** this interface is 0, then both the C-API and the SQL function are disabled.
2595 ** If the first argument is -1, then no changes are made to state of either the
2597 ** The second parameter is a pointer to an integer into which
2598 ** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface
2599 ** is disabled or enabled following this call. The second parameter may
2600 ** be a NULL pointer, in which case the new setting is not reported back.
2604 ** <dd> ^This option is used to change the name of the "main" database
2605 ** schema. ^The sole argument is a pointer to a constant UTF8 string
2608 ** must ensure that the argument passed into this DBCONFIG option is unchanged
2614 ** <dd> Usually, when a database in wal mode is closed or detached from a
2619 ** is an integer - positive to disable checkpoints-on-close, or zero (the
2621 ** The second parameter is a pointer to an integer
2622 ** into which is written 0 or 1 to indicate whether checkpoints-on-close
2628 ** the [query planner stability guarantee] (QPSG). When the QPSG is active,
2635 ** The first argument to this setting is an integer which is 0 to disable
2637 ** unchanged. The second parameter is a pointer to an integer into which
2638 ** is written 0 or 1 to indicate whether the QPSG is disabled or enabled
2645 ** option is used to set or clear (the default) a flag that governs this
2646 ** behavior. The first parameter passed to this operation is an integer -
2649 ** The second parameter is a pointer to an integer into which is written
2651 ** it is not disabled, 1 if it is.
2660 ** <li> If the database connection is newly opened, make sure it has read the
2663 ** errors. This step is only necessary if the application desires to keep
2670 ** Because resetting a database is destructive and irreversible, the
2681 ** flag is enabled, language features that allow ordinary SQL to
2695 ** "writable_schema" flag. This has the same effect and is logically equivalent
2697 ** The first argument to this setting is an integer which is 0 to disable
2699 ** leave the setting unchanged. The second parameter is a pointer to an
2700 ** integer into which is written 0 or 1 to indicate whether the writable_schema
2701 ** is enabled or disabled following this call.
2718 ** only, that is DELETE, INSERT, SELECT, and UPDATE statements. The
2719 ** default value of this setting is determined by the [-DSQLITE_DQS]
2728 ** default value of this setting is determined by the [-DSQLITE_DQS]
2736 ** When the SQLITE_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite
2762 ** is now scarcely any need to generate database files that are compatible
2763 ** all the way back to version 3.0.0, and so this setting is of little
2764 ** practical use, but is provided so that SQLite can continue to claim the
2767 ** <p>Note that when the SQLITE_DBCONFIG_LEGACY_FILE_FORMAT setting is on,
2769 ** process a table with generated columns and a descending index. This is
2776 ** <dd>The SQLITE_DBCONFIG_STMT_SCANSTATUS option is only useful in
2780 ** the database handle both when the SQL statement is prepared and when it
2781 ** is stepped. The flag is set (collection of statistics is enabled)
2783 ** an integer.. The first argument is 1, 0, or -1 to enable, disable, or
2785 ** is not NULL, then the value of the statement scanstatus setting after
2786 ** processing the first argument is written into the integer that the second
2795 ** working toward the end. Setting SQLITE_DBCONFIG_REVERSE_SCANORDER is the
2798 ** argument is 1, 0, or -1 to enable, disable, or leave unchanged the
2799 ** reverse scan order flag, respectively. If the second argument is not NULL,
2800 ** then 0 or 1 is written into the integer that the second argument points to
2801 ** depending on if the reverse scan order flag is set after processing the
2845 ** integer key called the [ROWID | "rowid"]. ^The rowid is always available
2849 ** is another alias for the rowid.
2872 ** return the [rowid] of the inserted row as long as the trigger is
2876 ** ^An [INSERT] that fails due to a constraint violation is not a
2886 ** ^For the purposes of this routine, an [INSERT] is considered to
2887 ** be successful even if it is subsequently rolled back.
2889 ** This function is accessible to SQL statements via the
2894 ** function is running and thus changes the last insert [rowid],
2895 ** then the value returned by [sqlite3_last_insert_rowid()] is
2920 ** or DELETE is greater than the maximum value supported by type "int", then
2921 ** the return value of sqlite3_changes() is undefined. ^Executing any other
2931 ** DELETE statement run on a view is always zero. Only changes made to real
2934 ** Things are more complicated if the sqlite3_changes() function is
2935 ** executed while a trigger program is running. This may happen if the
2941 ** sqlite3_changes() function is saved. After the trigger program
2942 ** has finished, the original value is restored.)^
2951 ** ^This means that if the changes() SQL function (or similar) is used
2954 ** ^If it is used by the second or subsequent such statement within a trigger
2959 ** while [sqlite3_changes()] is running then the value returned
2960 ** is unpredictable and not meaningful.
2983 ** the return value of sqlite3_total_changes() is undefined. ^Executing
3000 ** while [sqlite3_total_changes()] is running then the value
3001 ** returned is unpredictable and not meaningful.
3020 ** return at its earliest opportunity. This routine is typically
3025 ** ^It is safe to call this routine from a thread different from the
3026 ** thread that is currently running the database operation. But it
3027 ** is not safe to call this routine with a [database connection] that
3028 ** is closed or might close before sqlite3_interrupt() returns.
3030 ** ^If an SQL operation is very nearly finished at the time when
3031 ** sqlite3_interrupt() is called, then it might not have an opportunity
3034 ** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
3035 ** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
3036 ** that is inside an explicit transaction, then the entire transaction
3039 ** ^The sqlite3_interrupt(D) call is in effect until all currently running
3047 ** SQL statements is a no-op and has no effect on SQL statements
3051 ** or not an interrupt is currently in effect for [database connection] D.
3052 ** It returns 1 if an interrupt is currently in effect, or 0 otherwise.
3062 ** if additional input is needed before sending the text into
3064 ** appears to be a complete SQL statement. ^A statement is judged to be
3065 ** complete if it ends with a semicolon token and is not a prefix of a
3072 ** ^These routines return 0 if the statement is incomplete. ^If a
3073 ** memory allocation fails, then SQLITE_NOMEM is returned.
3079 ** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
3082 ** regardless of whether or not the input SQL is complete.)^
3100 ** an attempt is made to access a database table associated with
3103 ** The sqlite3_busy_handler() interface is used to implement
3106 ** ^If the busy callback is NULL, then [SQLITE_BUSY]
3107 ** is returned immediately upon encountering the lock. ^If the busy callback
3108 ** is not NULL, then the callback might be invoked with two arguments.
3110 ** ^The first argument to the busy handler is a copy of the void* pointer which
3111 ** is the third argument to sqlite3_busy_handler(). ^The second argument to
3112 ** the busy handler callback is the number of times that the busy handler has
3115 ** access the database and [SQLITE_BUSY] is returned
3118 ** is made to access the database and the cycle repeats.
3121 ** when there is lock contention. ^If SQLite determines that invoking the busy
3125 ** Consider a scenario where one process is holding a read lock that
3126 ** it is trying to promote to a reserved lock and
3127 ** a second process is holding a reserved lock that it is trying
3129 ** because it is blocked by the second and the second process cannot
3130 ** proceed because it is blocked by the first. If both processes
3136 ** ^The default busy callback is NULL.
3146 ** the busy handler is not reentrant. Any such actions
3159 ** for a specified amount of time when a table is locked. ^The handler
3171 ** this routine, that other busy handler is cleared.)^
3181 ** This is a legacy interface that is preserved for backwards compatibility.
3182 ** Use of this interface is not recommended.
3184 ** Definition: A <b>result table</b> is memory data structure created by the
3193 ** A result table is an array of pointers to zero-terminated UTF-8 strings.
3201 ** It is not safe to pass a result table directly to [sqlite3_free()].
3205 ** is as follows:
3216 ** result table has 8 entries. Suppose the result table is stored
3240 ** [sqlite3_free_table()] is able to release the memory properly and safely.
3242 ** The sqlite3_get_table() interface is implemented as a wrapper around
3274 ** NULL pointer if [sqlite3_malloc64()] is unable to allocate enough
3277 ** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
3278 ** the standard C library. The result is written into the
3279 ** buffer supplied as the second parameter whose size is given by
3281 ** first two parameters is reversed from snprintf().)^ This is an
3290 ** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
3291 ** guarantees that the buffer is always zero-terminated. ^The first
3292 ** parameter "n" is the total size of the buffer, including space for
3296 ** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
3314 ** of memory at least N bytes in length, where N is the parameter.
3315 ** ^If sqlite3_malloc() is unable to obtain sufficient free
3317 ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
3321 ** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
3326 ** that it might be reused. ^The sqlite3_free() routine is
3327 ** a no-op if is called with a NULL pointer. Passing a NULL pointer
3328 ** to sqlite3_free() is harmless. After being freed, memory
3332 ** might result if sqlite3_free() is called with a non-NULL pointer that
3338 ** is a NULL pointer then its behavior is identical to calling
3340 ** ^If the N parameter to sqlite3_realloc(X,N) is zero or
3341 ** negative then the behavior is exactly the same as calling
3344 ** of at least N bytes in size or NULL if insufficient memory is available.
3345 ** ^If M is the size of the prior allocation, then min(N,M) bytes
3347 ** by sqlite3_realloc(X,N) and the prior allocation is freed.
3348 ** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the
3349 ** prior allocation is not freed.
3352 ** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
3355 ** ^If X is a memory allocation previously obtained from sqlite3_malloc(),
3359 ** of bytes requested when X was allocated. ^If X is a NULL pointer then
3360 ** sqlite3_msize(X) returns zero. If X points to something that is not
3363 ** of sqlite3_msize(X) is undefined and possibly harmful.
3367 ** is always aligned to at least an 8 byte boundary, or to a
3369 ** option is used.
3404 ** ^The memory high-water mark is reset to the current value of
3406 ** [sqlite3_memory_highwater()] is true. ^The value returned
3407 ** by [sqlite3_memory_highwater(1)] is the high-water mark
3418 ** already uses the largest possible [ROWID]. The PRNG is also used for
3426 ** call had N less than one or a NULL pointer for P, then the PRNG is
3430 ** non-NULL P then the pseudo-randomness is generated
3443 ** ^The authorizer callback is invoked as SQL statements are being compiled
3447 ** points during the compilation process, as logic is being created
3448 ** to perform various actions, the authorizer callback is invoked to
3459 ** requested is ok. ^When the callback returns [SQLITE_DENY], the
3462 ** access is denied.
3464 ** ^The first parameter to the authorizer callback is a copy of the third
3466 ** to the callback is an integer [SQLITE_COPY | action code] that specifies
3473 ** ^If the action code is [SQLITE_READ]
3475 ** [prepared statement] statement is constructed to substitute
3480 ** ^When a table is referenced by a [SELECT] but no column values are
3483 ** is invoked once for that table with a column name that is an empty string.
3484 ** ^If the action code is [SQLITE_DELETE] and the callback returns
3486 ** [truncate optimization] is disabled and all rows are deleted individually.
3488 ** An authorizer is used when [sqlite3_prepare | preparing]
3496 ** user-entered SQL is being [sqlite3_prepare | prepared] that
3507 ** The authorizer is disabled by default.
3514 ** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
3519 ** ^Note that the authorizer callback is invoked only during
3520 ** [sqlite3_prepare()] or its variants. Authorization is not
3536 ** to signal SQLite whether or not the action is permitted. See the
3540 ** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
3550 ** that is invoked to authorize certain SQL statement actions. The
3551 ** second parameter to the callback is an integer code that specifies
3552 ** what action is being authorized. These are the integer action codes that
3555 ** These action code values signify what kind of operation is to be
3558 ** codes is used as the second parameter. ^(The 5th parameter to the
3559 ** authorizer callback is the name of the database ("main", "temp",
3561 ** is the name of the inner-most trigger or view that is responsible for
3562 ** the access attempt or NULL if this access attempt is directly from
3611 ** ^The callback function registered by sqlite3_trace() is invoked at
3612 ** various times when an SQL statement is being run by [sqlite3_step()].
3613 ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
3616 ** as each triggered subprogram is entered. The callbacks for triggers
3622 ** ^The callback function registered by sqlite3_profile() is invoked
3626 ** time is in units of nanoseconds, however the current implementation
3627 ** is only capable of millisecond resolution so the six least significant
3644 ** to [sqlite3_trace_v2(D,M,X,P)] is an OR-ed combination of one or more of
3646 ** is one of the following constants.
3651 ** ^The T argument is one of the integer type codes above.
3652 ** ^The C argument is a copy of the context pointer passed in as the
3658 ** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement
3661 ** trigger subprogram. ^The P argument is a pointer to the
3662 ** [prepared statement]. ^The X argument is a pointer to a string which
3663 ** is the unexpanded SQL text of the prepared statement or an SQL comment
3671 ** information as is provided by the [sqlite3_profile()] callback.
3672 ** ^The P argument is a pointer to the [prepared statement] and the
3673 ** X argument points to a 64-bit integer which is approximately
3675 ** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
3678 ** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
3680 ** ^The P argument is a pointer to the [prepared statement] and the
3681 ** X argument is unused.
3684 ** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database
3686 ** ^The P argument is a pointer to the [database connection] object
3687 ** and the X argument is unused.
3701 ** and context pointer P. ^If the X callback is
3702 ** NULL or if the M mask is zero, then tracing is disabled. The
3711 ** ^The X callback is invoked whenever any of the events identified by
3712 ** mask M occur. ^The integer return value from the callback is currently
3716 ** ^A trace callback is invoked with four arguments: callback(T,C,P,X).
3717 ** ^The T argument is one of the [SQLITE_TRACE]
3719 ** ^The C argument is a copy of the context pointer.
3722 ** The sqlite3_trace_v2() interface is intended to replace the legacy
3741 ** interface is to keep a GUI updated during a large query.
3743 ** ^The parameter P is passed through as the only parameter to the
3744 ** callback function X. ^The parameter N is the approximate number of
3746 ** invocations of the callback X. ^If N is less than one then the progress
3747 ** handler is disabled.
3752 ** ^The progress handler is also disabled by setting N to a value less
3755 ** ^If the progress callback returns non-zero, the operation is
3779 ** filename argument. ^The filename argument is interpreted as UTF-8 for
3781 ** order for sqlite3_open16(). ^(A [database connection] handle is usually
3782 ** returned in *ppDb, even if an error occurs. The only exception is that
3783 ** if SQLite is unable to allocate memory to hold the [sqlite3] object,
3785 ** object.)^ ^(If the database is opened (and/or created) successfully, then
3786 ** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The
3795 ** Whether or not an error occurs when it is opened, resources
3797 ** passing it to [sqlite3_close()] when it is no longer required.
3807 ** <dd>The database is opened in read-only mode. If the database does
3808 ** not already exist, an error is returned.</dd>)^
3811 ** <dd>The database is opened for reading and writing if possible, or
3812 ** reading only if the file is write protected by the operating
3814 ** an error is returned. For historical reasons, if opening in
3815 ** read-write mode fails due to OS-level permissions, an attempt is
3817 ** used to determine whether the database is actually
3821 ** <dd>The database is opened for reading and writing, and is created if
3822 ** it does not already exist. This is the behavior that is always used for
3831 ** <dd>The filename can be interpreted as a URI if this flag is set.</dd>)^
3835 ** is named by the "filename" argument for the purposes of cache-sharing,
3836 ** if shared cache mode is enabled, but the "filename" is otherwise ignored.
3842 ** to use SQLite at the same time, as long as each thread is using
3850 ** there is no harm in trying.)
3853 ** <dd>The database is opened [shared cache] enabled, overriding
3856 ** The [use of shared cache mode is discouraged] and hence shared cache
3858 ** this option is a no-op.
3861 ** <dd>The database is opened [shared cache] disabled, overriding
3869 ** connection as soon as the connection is created. In addition to setting
3874 ** <dd>The database filename is not allowed to contain a symbolic link</dd>
3877 ** If the 3rd parameter to sqlite3_open_v2() is not one of the
3880 ** then the behavior is undefined. Historic versions of SQLite
3884 ** upon it. Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op
3887 ** flag is intended for use by the [sqlite3_vfs|VFS interface] only, and not
3890 ** ^The fourth parameter to sqlite3_open_v2() is the name of the
3892 ** the new database connection should use. ^If the fourth parameter is
3893 ** a NULL pointer then the default [sqlite3_vfs] object is used.
3895 ** ^If the filename is ":memory:", then a private, temporary in-memory database
3896 ** is created for the connection. ^This in-memory database will vanish when
3897 ** the database connection is closed. Future versions of SQLite might
3899 ** It is recommended that when a database filename actually does begin with
3903 ** ^If the filename is an empty string, then a private, temporary
3905 ** automatically deleted as soon as the database connection is closed.
3909 ** ^If [URI filename] interpretation is enabled, and the filename argument
3910 ** begins with "file:", then the filename is interpreted as a URI. ^URI
3911 ** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
3915 ** URI filename interpretation is turned off
3922 ** "localhost". ^If the authority is not an empty string or "localhost", an
3923 ** error is returned to the caller. ^The fragment component of a URI, if
3924 ** present, is ignored.
3928 ** then it is interpreted as an absolute path. ^If the path does not begin
3929 ** with a '/' (meaning that the authority section is omitted from the URI)
3930 ** then the path is interpreted as a relative path.
3932 ** is a drive specification (e.g. "C:").)^
3943 ** be used to access the database file on disk. ^If this option is set to
3944 ** an empty string the default VFS object is used. ^Specifying an unknown
3945 ** VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
3950 ** "rwc", or "memory". Attempting to set it to any other value is
3952 ** ^If "ro" is specified, then the database is opened for read-only
3954 ** third argument to sqlite3_open_v2(). ^If the mode option is set to
3955 ** "rw", then the database is opened for read-write (but not create)
3957 ** been set. ^Value "rwc" is equivalent to setting both
3958 ** SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If the mode option is
3960 ** or writes from disk is used. ^It is an error to specify a value for
3961 ** the mode parameter that is less restrictive than that specified by
3965 ** "private". ^Setting it to "shared" is equivalent to setting the
3967 ** sqlite3_open_v2(). ^Setting the cache parameter to "private" is
3969 ** ^If sqlite3_open_v2() is used and the "cache" parameter is present in
3977 ** <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
3979 ** is useful for accessing a database on a filesystem that does not
3984 ** <li> <b>immutable</b>: ^The immutable parameter is a boolean query
3985 ** parameter that indicates that the database file is stored on
3986 ** read-only media. ^When immutable is set, SQLite assumes that the
3988 ** privilege, and so the database is opened read-only and all locking
3989 ** and change detection is disabled. Caution: Setting the immutable
3996 ** ^Specifying an unknown parameter in the query component of a URI is not an
4012 ** An error. "darkstar" is not a recognized authority.
4016 ** C:. Note that the %20 escaping in this example is not strictly
4021 ** Regardless of whether or not shared-cache mode is enabled by
4027 ** An error. "readonly" is not a valid option for the "mode" parameter.
4042 ** codepage is currently defined. Filenames containing international
4082 ** If the F parameter is not one of the above, then the behavior is
4086 ** If F is a suitable filename (as described in the previous paragraph)
4087 ** and if P is the name of the query parameter, then
4090 ** query parameter on F. If P is a query parameter of F and it
4094 ** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
4097 ** value of query parameter P is one of "yes", "true", or "on" in any
4100 ** query parameter P is one of "no", "false", or "off" in any case or
4101 ** if the value begins with a numeric zero. If P is not a query
4107 ** exist. If the value of P is something other than an integer, then
4108 ** zero is returned.
4112 ** pointer if N is less than zero or greater than the number of query
4113 ** parameters minus 1. The N value is zero-based so N should be 0 to obtain
4117 ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
4118 ** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and
4119 ** is not a database file pathname pointer that the SQLite core passed
4120 ** into the xOpen VFS method, then the behavior of this routine is undefined
4127 ** When the F parameter is the name of the rollback journal or WAL file,
4145 ** If F is the name of an sqlite database file, journal file, or WAL file
4149 ** If F is the name of an sqlite database file, journal file, or WAL file
4150 ** passed by the SQLite core into the VFS, or if F is a database filename
4154 ** If F is the name of an sqlite database file, journal file, or WAL file
4155 ** that was passed by the SQLite core into the VFS, or if F is a database
4160 ** In all of the above, if F is not the name of a database, journal or WAL
4161 ** filename passed into the VFS from the SQLite core and F is not the
4162 ** return value from [sqlite3_db_filename()], then the result is
4163 ** undefined and is likely a memory access violation.
4172 ** ^If X is the name of a rollback or WAL-mode journal file that is
4177 ** This routine is intended for use in custom [VFS] implementations
4178 ** only. It is not a general-purpose interface.
4197 ** sqlite3_create_filename(D,J,W,N,P) is a pointer to a database filename that
4198 ** is safe to pass to routines like:
4215 ** pointer if N is zero. None of the 2*N pointers in the P array may be
4222 ** sqlite3_free_filename(Y) where Y is a NULL pointer is a harmless no-op.
4224 ** If the Y parameter to sqlite3_free_filename(Y) is anything other
4251 ** interface is the same except that it always returns the
4271 ** or NULL if no error message is available.
4273 ** ^(Memory to hold the error message string is managed internally.
4279 ** that describes the [result code] E, as UTF-8, or NULL if E is not an
4280 ** result code for which a text error message is available.
4281 ** ^(Memory to hold the error message string is managed internally
4287 ** sqlite3_error_offset() assumes that the input SQL is UTF8.
4291 ** When the serialized [threading mode] is in use, it might be the
4317 ** has been compiled into binary form and is ready to be evaluated.
4320 ** original SQL text is source code. A prepared statement object
4321 ** is the compiled object code. All SQL must be converted into a
4343 ** on a connection by connection basis. The first parameter is the
4344 ** [database connection] whose limit is to be set or queried. The
4345 ** second parameter is one of the [limit categories] that define a
4346 ** class of constructs to be size limited. The third parameter is the
4349 ** ^If the new limit is a negative number, the limit is unchanged.
4350 ** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a
4354 ** (The "_LIMIT_" in the name is changed to "_MAX_".))^
4386 ** The synopsis of the meanings of the various limits is shown below.
4387 ** Additional information is available at [limits | Limits in SQLite].
4411 ** in a single prepared statement, an SQLITE_NOMEM error is returned.</dd>)^
4460 ** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
4471 ** <dd>The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used
4474 ** [sqlite3_normalized_sql()] interface is now available to all
4498 ** The preferred routine to use is [sqlite3_prepare_v2()]. The
4499 ** [sqlite3_prepare()] interface is legacy and should be avoided.
4500 ** [sqlite3_prepare_v3()] has an extra "prepFlags" option that is used
4503 ** The use of the UTF-8 interfaces is preferred, as SQLite currently
4508 ** The first argument, "db", is a [database connection] obtained from a
4512 ** The second argument, "zSql", is the statement to be compiled, encoded
4518 ** ^If the nByte argument is negative, then zSql is read up to the
4519 ** first zero terminator. ^If nByte is positive, then it is the
4520 ** number of bytes read from zSql. ^If nByte is zero, then no prepared
4521 ** statement is generated.
4522 ** If the caller knows that the supplied string is nul-terminated, then
4523 ** there is a small performance advantage to passing an nByte parameter that
4524 ** is the number of bytes in the input string <i>including</i>
4527 ** ^If pzTail is not NULL then *pzTail is made to point to the first byte
4529 ** compile the first statement in zSql, so *pzTail is left pointing to
4532 ** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
4533 ** executed using [sqlite3_step()]. ^If there is an error, *ppStmt is set
4534 ** to NULL. ^If the input text contains no SQL (if the input is an empty
4535 ** string or a comment) then *ppStmt is set to NULL.
4536 ** The calling procedure is responsible for deleting the compiled
4541 ** otherwise an [error code] is returned.
4546 ** are retained for backwards compatibility, but their use is discouraged.
4548 ** that is returned (the [sqlite3_stmt] object) contains a copy of the
4566 ** interfaces, the underlying reason for the error is returned immediately.
4576 ** choice of query plan if the parameter is the left-hand side of a [LIKE]
4577 ** or [GLOB] operator or if the parameter is compared to an indexed column
4578 ** and the [SQLITE_ENABLE_STAT4] compile-time option is enabled.
4583 ** the extra prepFlags parameter, which is a bit array consisting of zero or
4650 ** ^(For example, if a prepared statement is created using the SQL
4651 ** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
4652 ** and parameter :xyz is unbound, then sqlite3_sql() will return
4657 ** is available to hold the result, or if the result would exceed the
4666 ** statement is finalized.
4668 ** is obtained from [sqlite3_malloc()] and must be freed by the application
4671 ** ^The sqlite3_normalized_sql() interface is only available if
4672 ** the [SQLITE_ENABLE_NORMALIZE] compile-time option is defined.
4714 ** ^This routine returns false if there is any possibility that the
4719 ** be false. ^Similarly, a CREATE TABLE IF NOT EXISTS statement is a
4723 ** ^If prepared statement X is an [EXPLAIN] or [EXPLAIN QUERY PLAN]
4734 ** prepared statement S is an EXPLAIN statement, or 2 if the
4735 ** statement S is an EXPLAIN QUERY PLAN.
4736 ** ^The sqlite3_stmt_isexplain(S) interface returns 0 if S is
4746 ** setting for [prepared statement] S. If E is zero, then S becomes
4747 ** a normal prepared statement. If E is 1, then S behaves as if
4748 ** its SQL text began with "[EXPLAIN]". If E is 2, then S behaves as if
4764 ** is called to convert the statement into an ordinary statement, the EXPLAIN
4768 ** This routine returns SQLITE_OK if the explain mode is successfully
4770 ** The explain mode cannot be changed while a statement is active.
4771 ** Hence, it is good practice to call [sqlite3_reset(S)]
4785 ** interface returns false if S is a NULL pointer. If S is not a
4786 ** NULL pointer and is not a pointer to a valid [prepared statement]
4787 ** object, then the behavior is undefined and probably undesirable.
4815 ** a mutex is held. An internal mutex is held for a protected
4816 ** sqlite3_value object but no mutex is held for an unprotected
4817 ** sqlite3_value object. If SQLite is compiled to be single-threaded
4819 ** or if SQLite is run in one of reduced mutex modes
4821 ** then there is no distinction between protected and unprotected
4823 ** for maximum code portability it is recommended that applications
4832 ** [sqlite3_column_value()] is unprotected.
4844 ** The context in which an SQL function executes is stored in an
4846 ** is always first parameter to [application-defined SQL functions].
4878 ** ^The first argument to the sqlite3_bind_*() routines is always
4882 ** ^The second argument is the index of the SQL parameter to be set.
4884 ** SQL parameter is used more than once, second and subsequent
4888 ** for "?NNN" parameters is the value of NNN.
4892 ** ^The third argument is the value to bind to the parameter.
4894 ** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
4895 ** is ignored and the end result is the same as sqlite3_bind_null().
4896 ** ^If the third parameter to sqlite3_bind_text() is not NULL, then
4898 ** ^If the third parameter to sqlite3_bind_text16() is not NULL, then
4900 ** ^If the third parameter to sqlite3_bind_text64() is not NULL, then
4901 ** it should be a pointer to a well-formed unicode string that is
4902 ** either UTF8 if the sixth parameter is SQLITE_UTF8, or UTF16
4906 ** UTF16 input text is determined by the byte-order mark (BOM, U+FEFF)
4907 ** found in first character, which is removed, or in the absence of a BOM
4908 ** the byte order is the native byte order of the host
4915 ** ^(In those routines that have a fourth argument, its value is the
4916 ** number of bytes in the parameter. To be clear: the value is the
4919 ** is negative, then the length of the string is
4921 ** If the fourth parameter to sqlite3_bind_blob() is negative, then
4922 ** the behavior is undefined.
4923 ** If a non-negative fourth parameter is provided to sqlite3_bind_text()
4930 ** with embedded NULs is undefined.
4936 ** with it may be passed. ^It is called to dispose of the BLOB or string even
4937 ** if the call to the bind API fails, except the destructor is not called if
4938 ** the third parameter is a NULL pointer or the fourth parameter is negative.
4942 ** either the prepared statement is finalized or the same SQL parameter is
4945 ** object is to be copied prior to the return from sqlite3_bind_*(). ^The
4952 ** the sixth argument to sqlite3_bind_text64() is not one of the
4953 ** allowed values shown above, or if the text encoding is different
4955 ** is undefined.
4958 ** is filled with zeroes. ^A zeroblob uses a fixed amount of memory
4959 ** (just an integer to hold its size) while it is being processed.
4961 ** content is later written using
4967 ** associated with the pointer P of type T. ^D is either a NULL pointer or
4969 ** destructor D with a single argument of P when it is finished using
4971 ** literal. The sqlite3_bind_pointer() routine is part of the
4978 ** routine is passed a [prepared statement] that has been finalized, the
4979 ** result is undefined and probably harmful.
4989 ** ^[SQLITE_RANGE] is returned if the parameter
4990 ** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails.
5039 ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
5042 ** is included as part of the name.)^
5048 ** ^If the value N is out of range or if the N-th parameter is
5049 ** nameless, then NULL is returned. ^The returned string is
5065 ** index value returned is suitable for use as the second
5067 ** is returned if no matching parameter is found. ^The parameter
5112 ** UTF-16 string. ^The first parameter is the [prepared statement]
5113 ** that implements the [SELECT] statement. ^The second parameter is the
5114 ** column number. ^The leftmost column is number 0.
5116 ** ^The returned string pointer is valid until either the [prepared statement]
5117 ** is destroyed by [sqlite3_finalize()] or until the statement is automatically
5124 ** NULL pointer is returned.
5126 ** ^The name of a result column is the value of the "AS" clause for
5127 ** that column, if there is an AS clause. If there is no AS clause
5128 ** then the name of the column is unspecified and may change from
5139 ** table column that is the origin of a particular result column in
5145 ** ^The returned string is valid until the [prepared statement] is destroyed
5146 ** using [sqlite3_finalize()] or until the statement is automatically
5148 ** or until the same information is requested
5154 ** ^The first argument to these interfaces is a [prepared statement].
5156 ** the statement, where N is the second function argument.
5157 ** ^The left-most column is column 0 for these routines.
5159 ** ^If the Nth column returned by the statement is an expression or
5160 ** subquery and is not a column value, then all of these functions return
5187 ** ^(The first parameter is a [prepared statement].
5188 ** If this statement is a [SELECT] statement and the Nth column of the
5189 ** returned result set of that [SELECT] is a table column (not an
5191 ** column is returned.)^ ^If the Nth column of the result set is an
5192 ** expression or subquery, then a NULL pointer is returned.
5193 ** ^The returned string is always UTF-8 encoded.
5207 ** is declared to contain a particular type does not mean that the
5208 ** data stored in that column is of the declared type. SQLite is
5209 ** strongly typed, but the typing is dynamic not static. ^Type
5210 ** is associated with individual values, not with the containers
5231 ** new "vX" interface is recommended for new applications but the legacy
5240 ** database locks it needs to do its job. ^If the statement is a [COMMIT]
5242 ** statement. If the statement is not a [COMMIT] and occurs within an
5252 ** is returned each time a new row of data is ready for processing by the
5254 ** sqlite3_step() is called again to retrieve the next row of data.
5263 ** the more specific error code is returned directly by sqlite3_step().
5269 ** be the case that the same database connection is being used by two or
5280 ** than returning [SQLITE_MISUSE]. This is not considered a compatibility
5282 ** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option
5290 ** We admit that this is a goofy design. The problem has been fixed
5296 ** by sqlite3_step(). The use of the "vX" interfaces is recommended.
5309 ** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
5381 ** result row of a query. ^In every case the first argument is a pointer
5382 ** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
5384 ** and the second argument is the index of the column for which information
5390 ** column index is out of range, the result is undefined.
5403 ** the result column is not initially in the requested format (for example,
5405 ** is used to extract the value) then an automatic type conversion is performed.
5409 ** of the result column. ^The returned value is one of [SQLITE_INTEGER],
5413 ** The value returned by sqlite3_column_type() is only meaningful if no
5416 ** is undefined, though harmless. Future
5420 ** If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()
5424 ** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
5426 ** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
5428 ** ^If the result is a numeric value then sqlite3_column_bytes() uses
5431 ** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
5433 ** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
5435 ** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
5437 ** ^If the result is a numeric value then sqlite3_column_bytes16() uses
5440 ** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
5450 ** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
5453 ** which is native to the platform, regardless of the text encoding set
5456 ** <b>Warning:</b> ^The object returned by [sqlite3_column_value()] is an
5461 ** [sqlite3_column_value()] is used in any other way, including calls
5463 ** or [sqlite3_value_bytes()], the behavior is not threadsafe.
5465 ** is normally only useful within the implementation of
5470 ** ^For example, if the internal representation is FLOAT and a text result
5471 ** is requested, [sqlite3_snprintf()] is used internally to perform the
5479 ** <tr><td> NULL <td> INTEGER <td> Result is 0
5480 ** <tr><td> NULL <td> FLOAT <td> Result is 0.0
5481 ** <tr><td> NULL <td> TEXT <td> Result is a NULL pointer
5482 ** <tr><td> NULL <td> BLOB <td> Result is a NULL pointer
5505 ** <li> The initial content is a BLOB and sqlite3_column_text() or
5506 ** sqlite3_column_text16() is called. A zero-terminator might
5508 ** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
5509 ** sqlite3_column_text16() is called. The content must be converted
5511 ** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
5512 ** sqlite3_column_text() is called. The content must be converted
5519 ** of conversion are done in place when it is possible, but sometimes they
5522 ** The safest policy is to invoke these routines
5541 ** [sqlite3_finalize()] is called. ^The memory space used to hold strings
5542 ** and BLOBs is freed automatically. Do not pass the pointers returned
5560 ** routines is the same as if the column had contained an SQL NULL value.
5563 ** return value is obtained and before any
5564 ** other SQLite interface is called on the same [database connection].
5581 ** ^The sqlite3_finalize() function is called to delete a [prepared statement].
5583 ** or if the statement is never been evaluated, then sqlite3_finalize() returns
5590 ** before statement S is ever evaluated, after
5595 ** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
5598 ** resource leaks. It is a grievous error for the application to try to use
5609 ** The sqlite3_reset() function is called to reset a [prepared statement]
5631 ** [INSERT] statement with a [RETURNING] clause is only stepped one time,
5635 ** database change from committing. Therefore, it is important that
5657 ** is similar, but allows the user to supply the extra callback functions
5660 ** ^The first parameter is the [database connection] to which the SQL
5661 ** function is to be added. ^If an application uses more than one database
5665 ** ^The second parameter is the name of the SQL function to be created or
5666 ** redefined. ^The length of the name is limited to 255 bytes in a UTF-8
5668 ** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
5673 ** is the number of arguments that the SQL function or
5674 ** aggregate takes. ^If this parameter is -1, then the SQL function or
5677 ** parameter is less than -1 or greater than 127 then the behavior is
5686 ** [SQLITE_UTF16] if [sqlite3_value_text16()] is used, or [SQLITE_UTF8]
5696 ** deterministic. The built-in [random()] SQL function is an example of a
5697 ** function that is not deterministic. The SQLite query planner is able to
5699 ** of the [SQLITE_DETERMINISTIC] flag is recommended where possible.
5706 ** For best security, the [SQLITE_DIRECTONLY] flag is recommended for
5709 ** the database schema. This flags is especially recommended for SQL
5714 ** the database file is opened and read.
5716 ** ^(The fifth parameter is an arbitrary pointer. The implementation of the
5733 ** which case a regular aggregate function is created, or must both be
5740 ** sqlite3_create_window_function() is not NULL, then it is destructor for
5741 ** the application data pointer. The destructor is invoked when the function
5742 ** is deleted, either by being overloaded or when the database connection
5743 ** closes.)^ ^The destructor is also invoked if the call to
5744 ** sqlite3_create_function_v2() fails. ^When the destructor callback is
5745 ** invoked, it is passed a single argument which is a copy of the application
5748 ** ^It is permitted to register multiple implementations of the same
5752 ** SQL function is used. ^A function implementation with a non-negative
5753 ** nArg parameter is a better match than a function implementation with
5755 ** matches the database encoding is a better
5756 ** match than a function where the encoding is different.
5757 ** ^A function where the encoding difference is between UTF16le and UTF16be
5758 ** is a closer match than a function where the encoding difference is
5763 ** ^An application-defined function is permitted to call other
5766 ** statement in which the function is running.
5837 ** The [abs|abs() function] is deterministic, for example, but
5838 ** [randomblob|randomblob()] is not. Functions must
5851 ** The SQLITE_DIRECTONLY flag is recommended for any
5854 ** This will prevent attacks in which an application is tricked
5859 ** Some people say it is good practice to set SQLITE_DIRECTONLY on all
5868 ** The SQLITE_INNOCUOUS flag means that the function is unlikely
5871 ** input parameters. The [abs|abs() function] is an example of an
5873 ** The [load_extension() SQL function] is not innocuous because of its
5875 ** <p> SQLITE_INNOCUOUS is similar to SQLITE_DETERMINISTIC, but is not
5876 ** exactly the same. The [random|random() function] is an example of a
5877 ** function that is innocuous but not deterministic.
5883 ** the function is tagged with SQLITE_INNOCUOUS. Most built-in functions
5897 ** property. If the SQLITE_SUBTYPE property is omitted, then the return
5907 ** might become a no-op if the function is used as term in an
5910 ** purpose of this property is to disable certain optimizations that are
5968 ** <td>→ <td>True if the column is unchanged in an UPDATE
5983 ** is not threadsafe.
5999 ** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
6003 ** [sqlite3_value] object V. The returned value is one of [SQLITE_INTEGER],
6006 ** For example, if the datatype is initially SQLITE_INTEGER and
6007 ** sqlite3_value_text(V) is called to extract a text value for that
6010 ** occurs is undefined and may change from one release of SQLite to the next.
6013 ** numeric affinity to the value. This means that an attempt is
6015 ** such a conversion is possible without loss of information (in other
6016 ** words, if the value is a string that looks like a number)
6017 ** then the conversion is performed. Otherwise no conversion occurs.
6018 ** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
6022 ** the column corresponding to X is unchanged by the UPDATE operation
6028 ** sqlite3_value_nochange(X) is true will in all other respects appear
6029 ** to be a NULL value. If sqlite3_value_nochange(X) is invoked anywhere other
6031 ** the return value is arbitrary and meaningless.
6047 ** As long as the input parameter is correct, these routines can only
6063 ** routines is the same as if the column had contained an SQL NULL value.
6066 ** return value is obtained and before any
6067 ** other SQLite interface is called on the same [database connection].
6093 ** sqlite3_value_encoding(X) is meaningless. ^Calls to
6099 ** This routine is intended for used by applications that test and validate
6100 ** the SQLite implementation. This routine is inquiring about the opaque
6102 ** not need to know what the internal state of an sqlite3_value object is and
6119 ** encoding argument when the function is [sqlite3_create_function|registered].
6120 ** If the [SQLITE_SUBTYPE] property is omitted, then sqlite3_value_subtype()
6131 ** is a [protected sqlite3_value] object even if the input is not.
6132 ** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a
6133 ** memory allocation fails. ^If V is a [pointer value], then the result
6134 ** of sqlite3_value_dup(V) is a NULL value.
6137 ** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer
6138 ** then sqlite3_value_free(V) is a harmless no-op.
6150 ** ^The first time the sqlite3_aggregate_context(C,N) routine is called
6155 ** the same buffer is returned. Sqlite3_aggregate_context() is normally
6157 ** last time when the xFinal callback is invoked. ^(When no rows match
6159 ** implementation is never called and xFinal() is called exactly once.
6164 ** when first called if N is less than or equal to zero or if a memory
6167 ** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
6171 ** allocation.)^ Within the xFinal callback, it is customary to set
6179 ** [sqlite3_context | SQL function context] that is the first parameter
6184 ** the aggregate SQL function is running.
6199 ** the application-defined function is running.
6221 ** value is passed to multiple invocations of the same SQL function during
6223 ** might be preserved. An example of where this might be useful is in a
6232 ** value to the application-defined function. ^N is zero for the left-most
6233 ** function argument. ^If there is no auxiliary data
6240 ** sqlite3_set_auxdata(C,N,P,X) call if the auxiliary data is still valid or
6242 ** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
6244 ** once, when the auxiliary data is discarded.
6245 ** SQLite is free to discard the auxiliary data at any time, including: <ul>
6247 ** <li> ^(when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
6249 ** <li> ^(when sqlite3_set_auxdata() is invoked again on the same
6254 ** is evaluated during query planning instead of during query execution,
6266 ** function is being evaluated during query planning rather than during
6269 ** ^(In practice, auxiliary data is preserved between function calls for
6278 ** the SQL function is running.
6298 ** If P and X are both non-NULL, then the destructor X is invoked with
6303 ** <li> A subsequent call to sqlite3_set_clientdata(D,N,P,X) is made
6313 ** use for client data is to provide a mechanism for wrapper libraries
6316 ** There is no limit (other than available memory) on the number of different
6318 ** single database connection. However, the implementation is optimized
6323 ** There is no way to enumerate the client data pointers
6325 ** of as a secret key such that only code that knows the secret key is able
6333 ** Database connection client data is only available for SQLite
6344 ** These are special values for the destructor that is passed in as the
6346 ** argument is SQLITE_STATIC, it means that the content pointer is constant
6352 ** The typedef is necessary to work around problems in certain
6373 ** an application-defined function to be the BLOB whose content is pointed
6374 ** to by the second parameter and which is N bytes long where N is the
6394 ** or sqlite3_result_error16() is negative then SQLite takes as the error
6397 ** sqlite3_result_error16() is non-negative then SQLite takes that many
6405 ** the error code is SQLITE_ERROR. ^A subsequent call to sqlite3_result_error()
6409 ** error indicating that a string or BLOB is too long to represent.
6427 ** a text string which is represented as UTF-8, UTF-16 native byte order,
6436 ** other than sqlite3_result_text64() is negative, then SQLite computes
6440 ** is non-negative, then as many bytes (not characters) of the text
6442 ** function result. If the 3rd parameter is non-negative, then it
6445 ** in the string at a byte offset that is less than the value of the 3rd
6447 ** result of expressions operating on strings with embedded NULs is undefined.
6449 ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
6453 ** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
6454 ** assumes that the text or BLOB result is in constant space and does not
6458 ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
6464 ** when the encoding is not UTF8, if the input UTF16 begins with a
6465 ** byte-order mark (BOM, U+FEFF) then the BOM is removed from the
6466 ** string and the rest of the string is interpreted according to the
6470 ** sqlite3_result_text16le() is invoked with text that begins
6473 ** is interpreted as UTF16BE text.
6488 ** [unprotected sqlite3_value] object is required, so either
6496 ** ^If the D parameter is not NULL, then it is a pointer to a destructor
6498 ** when SQLite is finished with P. The T parameter should be a static
6500 ** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
6544 ** text encoding argument when the SQL function is
6546 ** property is omitted from the function that invokes sqlite3_result_subtype(),
6550 ** If SQLite is compiled with -DSQLITE_STRICT_SUBTYPE=1, then any
6565 ** ^The name of the collation is a UTF-8 string
6586 ** ^The fourth argument, pArg, is an application data pointer that is passed
6589 ** ^The fifth argument, xCompare, is a pointer to the collating function.
6593 ** ^If the xCompare argument is NULL then the collating function is
6595 ** that collation is no longer usable.
6597 ** ^The collating function callback is invoked with a copy of the pArg
6601 ** function must return an integer that is negative, zero, or positive
6602 ** if the first string is less than, equal to, or greater than the second,
6618 ** collating function is registered and used, then the behavior of SQLite
6619 ** is undefined.
6622 ** with the addition that the xDestroy callback is invoked on pArg when
6623 ** the collating function is deleted.
6626 ** [database connection] is closed using [sqlite3_close()].
6628 ** ^The xDestroy callback is <u>not</u> called if the
6633 ** This is different from every other SQLite interface. The inconsistency
6634 ** is unfortunate but cannot be changed without breaking backwards
6669 ** sequence is required.
6671 ** ^If the function is registered using the sqlite3_collation_needed() API,
6672 ** then it is passed the names of undefined collation sequences as strings
6673 ** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
6677 ** ^(When the callback is invoked, the first argument passed is a copy
6679 ** sqlite3_collation_needed16(). The second argument is the database
6680 ** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
6682 ** sequence function required. The fourth parameter is the name of the
6719 ** requested from the operating system is returned.
6723 ** of the default VFS is not implemented correctly, or not implemented at
6727 ** If a negative argument is passed to sqlite3_sleep() the results vary by
6731 ** argument passed into sqlite3_sleep() is changed to zero before it is relayed
6739 ** ^(If this global variable is made to point to a string which is
6743 ** is a NULL pointer, then SQLite performs a search for an appropriate
6747 ** It is required to set a temporary folder on Windows Runtime (WinRT).
6748 ** But for all other platforms, it is highly recommended that applications
6749 ** neither read nor write this variable. This global variable is a relic
6753 ** It is not safe to read or modify this variable in more than one
6754 ** thread at a time. It is not safe to read or modify this variable
6755 ** if a [database connection] is being used at the same time in a separate
6757 ** It is intended that this variable be set once
6765 ** that this variable points to is held in memory obtained from
6768 ** Hence, if this variable is modified directly, either it should be
6779 ** features that require the use of temporary files may fail. Here is an
6797 ** ^(If this global variable is made to point to a string which is
6801 ** to be relative to that directory.)^ ^If this variable is a NULL
6805 ** variable; it is ignored by the unix VFS.
6807 ** Changing the value of this variable while a database connection is
6810 ** It is not safe to read or modify this variable in more than one
6811 ** thread at a time. It is not safe to read or modify this variable
6812 ** if a [database connection] is being used at the same time in a separate
6814 ** It is intended that this variable be set once
6822 ** that this variable points to is held in memory obtained from
6825 ** Hence, if this variable is modified directly, either it should be
6835 ** [sqlite3_win32_set_directory] interface is used to set the value associated
6841 ** [SQLITE_OK] to indicate success, [SQLITE_ERROR] if the type is unsupported,
6843 ** [sqlite3_data_directory] variable is intended to act as a replacement for
6844 ** the current directory on the sub-platforms of Win32 where that concept is
6872 ** zero if the given database connection is or is not in autocommit mode,
6873 ** respectively. ^Autocommit mode is on by default.
6874 ** ^Autocommit mode is disabled by a [BEGIN] statement.
6875 ** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
6882 ** an error is to use this function.
6885 ** connection while this routine is running, then the return value
6886 ** is undefined.
6896 ** returned by sqlite3_db_handle is the same [database connection]
6908 ** for the N-th database on database connection D, or a NULL pointer of N is
6909 ** out of range. An N value of 0 means the main database file. An N of 1 is
6913 ** Space to hold the string that is returned by sqlite3_db_name() is managed
6931 ** ^If there is no attached database N on the database
6932 ** connection D, or if database N is a temporary or in-memory database, then
6935 ** ^The string value returned by this routine is owned and managed by
6937 ** is [DETACH]-ed or until the database connection closes.
6939 ** ^The filename returned by this function is the output of the
6944 ** If the filename pointer returned by this routine is not NULL, then it
6958 ** CAPI3REF: Determine if a database is read-only
6962 ** of connection D is read-only, 0 if it is read/write, or -1 if N is not
6972 ** [transaction state] of schema S in database connection D. ^If S is NULL,
6974 ** is returned. Transaction states are (in order of lowest to highest):
6980 ** ^If the S argument to sqlite3_txn_state(D,S) is not the name of
6981 ** a valid schema, then -1 is returned.
6996 ** <dd>The SQLITE_TXN_NONE state means that no transaction is currently
7000 ** <dd>The SQLITE_TXN_READ state means that the database is currently
7009 ** <dd>The SQLITE_TXN_WRITE state means that the database is currently
7023 ** pStmt associated with the [database connection] pDb. ^If pStmt is NULL
7039 ** function to be invoked whenever a transaction is [COMMIT | committed].
7041 ** for the same database connection is overridden.
7043 ** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
7045 ** for the same database connection is overridden.
7046 ** ^The pArg argument is passed through to the callback.
7048 ** then the commit is converted into a rollback.
7068 ** operation is allowed to continue normally. ^If the commit hook
7069 ** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
7070 ** ^The rollback hook is invoked on a rollback that results from a commit
7073 ** ^For the purposes of this API, a transaction is said to have been
7074 ** rolled back if an explicit "ROLLBACK" statement is executed, or
7076 ** ^The rollback callback is not invoked if a transaction is
7077 ** automatically rolled back because the database connection is closed.
7089 ** function C that is invoked prior to each autovacuum of the database
7090 ** file. ^The callback is passed a copy of the generic data pointer (P),
7091 ** the schema-name of the attached database that is being autovacuumed,
7096 ** ^If the value returned is greater than or equal to the number of
7101 ** callback is invoked separately for each file.
7103 ** <p><b>The callback is not reentrant.</b> The callback function should
7109 ** ^The X parameter to sqlite3_autovacuum_pages(D,C,P,X) is an optional
7110 ** destructor for the P parameter. ^If X is not NULL, then X(P) is
7112 ** is overwritten by another invocation of sqlite3_autovacuum_pages().
7114 ** <p>^There is only one autovacuum pages callback per database connection.
7117 ** argument (C) to sqlite3_autovacuum_pages(D,C,P,X) is a NULL pointer,
7118 ** then the autovacuum steps callback is canceled. The return value
7119 ** from sqlite3_autovacuum_pages() is normally SQLITE_OK, but might
7124 ** <p>If no autovacuum pages callback is specified (the usual case) or
7125 ** a NULL pointer is provided for the callback,
7126 ** then the default behavior is to vacuum all free pages. So, in other
7127 ** words, the default behavior is the same as if the callback function
7156 ** to be invoked whenever a row is updated, inserted or deleted in
7159 ** for the same database connection is overridden.
7161 ** ^The second argument is a pointer to the function to invoke when a
7162 ** row is updated, inserted or deleted in a rowid table.
7163 ** ^The first argument to the callback is a copy of the third argument
7165 ** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
7170 ** ^The final callback parameter is the [rowid] of the row.
7171 ** ^In the case of an update, this is the [rowid] after the update takes place.
7173 ** ^(The update hook is not invoked when internal system tables are
7175 ** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified.
7178 ** is not invoked when conflicting rows are deleted because of an
7179 ** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook
7210 ** to the same database. Sharing is enabled if the argument is true
7211 ** and disabled if the argument is false.)^
7213 ** This interface is omitted if SQLite is compiled with
7215 ** compile-time option is recommended because the
7216 ** [use of shared cache mode is discouraged].
7218 ** ^Cache sharing is enabled and disabled for an entire process.
7219 ** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]).
7229 ** successfully. An [error code] is returned otherwise.)^
7231 ** ^Shared cache is disabled by default. It is recommended that it stay
7233 ** continues to be provided for historical compatibility, but its use is
7234 ** discouraged. Any use of shared cache is discouraged. If shared cache
7235 ** must be used, it is recommended that shared cache only be enabled for
7239 ** Note: This method is disabled on MacOS X 10.7 and iOS version 5.0
7244 ** This interface is threadsafe on processors where writing a
7245 ** 32-bit integer is atomic.
7257 ** pages to improve performance is an example of non-essential memory.
7260 ** ^The sqlite3_release_memory() routine is a no-op returning zero
7261 ** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT].
7273 ** [sqlite3_release_memory()] interface, this interface is in effect even
7274 ** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is
7292 ** ^The soft heap limit is "soft" because even though SQLite strives to stay
7295 ** is advisory only.
7299 ** sqlite3_hard_heap_limit64(N) interface is similar to
7301 ** when the hard heap limit is reached.
7304 ** sqlite3_hard_heap_limit64() is the size of
7306 ** error. ^If the argument N is negative
7307 ** then no change is made to the heap limit. Hence, the current
7314 ** ^If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N)
7315 ** is invoked with a value of N that is greater than the hard heap limit,
7316 ** the soft heap limit is set to the value of the hard heap limit.
7317 ** ^The soft heap limit is automatically enabled whenever the hard heap
7318 ** limit is enabled. ^When sqlite3_hard_heap_limit64(N) is invoked and
7319 ** the soft heap limit is outside the range of 1..N, then the soft heap
7320 ** limit is set to N. ^Invoking sqlite3_soft_heap_limit64(0) when the
7321 ** hard heap limit is enabled makes the soft heap limit equal to the
7331 ** <li> The limit value is set to zero.
7332 ** <li> Memory accounting is disabled using a combination of the
7335 ** <li> An alternative page cache implementation is specified using
7352 ** This is a deprecated version of the [sqlite3_soft_heap_limit64()]
7353 ** interface. This routine is provided for historical compatibility
7371 ** ^If the column-name parameter to sqlite3_table_column_metadata() is a
7375 ** sqlite3_table_column_metadata(X,D,T,C,...) is NULL then the result is
7378 ** ^The column is identified by the second, third and fourth parameters to
7379 ** this function. ^(The second parameter is either the name of the database
7381 ** table or NULL.)^ ^If it is NULL, then all attached databases are searched
7388 ** ^Metadata is returned by writing to the memory locations passed as the 5th
7390 ** NULL, in which case the corresponding element of metadata is omitted.
7399 ** <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY
7400 ** <tr><td> 9th <td> int <td> True if column is [AUTOINCREMENT]
7405 ** declaration type and collation sequence is valid until the next
7408 ** ^If the specified table is actually a view, an [error code] is returned.
7410 ** ^If the specified column is "rowid", "oid" or "_rowid_" and the table
7411 ** is not a [WITHOUT ROWID] table and an
7413 ** parameters are set for the explicitly declared column. ^(If there is no
7438 int *pAutoinc /* OUTPUT: True if column is auto-increment */
7455 ** ^The entry point is zProc.
7459 ** X is consists of the lower-case equivalent of all ASCII alphabetic
7464 ** ^If an error occurs and pzErrMsg is not 0, then the
7476 ** <b>Security warning:</b> It is recommended that the
7499 ** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
7501 ** ^Extension loading is off by default.
7511 ** <b>Security warning:</b> It is recommended that extension loading
7523 ** each new [database connection] that is created. The idea here is that
7524 ** xEntryPoint() is the entry point for a statically linked [SQLite extension]
7525 ** that is to be automatically loaded into all new database connections.
7543 ** is NULL before calling the xEntryPoint(). ^SQLite will invoke
7548 ** ^Calling sqlite3_auto_extension(X) with an entry point X that is already
7549 ** on the list of automatic extensions is a harmless no-op. ^No entry point
7550 ** will be called more than once for each database connection that is opened.
7593 ** ^A virtual table module is created by filling in a persistent
7596 ** ^The registration remains valid until it is replaced by a different
7598 ** of this structure must not change while it is registered with
7647 ** The sqlite3_index_info structure and its substructures is used as part
7658 ** where OP is =, <, <=, >, or >=.)^ ^(The particular operator is
7661 ** ^(The index of the column is stored in
7662 ** aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the
7664 ** is usable) and false if it cannot.)^
7672 ** ^Information about the ORDER BY clause is stored in aOrderBy[].
7679 ** the corresponding bit is set within the colUsed mask if the column may be
7681 ** to the right of the first 63 is required, then bit 63 of colUsed is also
7688 ** the right-hand side of the corresponding aConstraint[] is evaluated
7690 ** is true, then the constraint is assumed to be fully handled by the
7692 ** aConstraintUsage[].omit flag is an optimization hint. When the omit flag
7693 ** is left in its default setting of false, the constraint will always be
7694 ** checked separately in byte code. If the omit flag is change to true, then
7696 ** when the omit flag is true there is no guarantee that the constraint will
7701 ** ^[sqlite3_free()] is used to free idxStr if and only if
7702 ** needToFreeIdxStr is true.
7706 ** sorting step is required.
7708 ** ^The estimatedCost value is an estimate of the cost of a particular
7709 ** strategy. A cost of N indicates that the cost of the strategy is similar
7711 ** indicates that the expense of the operation is similar to that of a
7714 ** ^The estimatedRows value is an estimate of the number of rows that
7718 ** mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag -
7723 ** SQLite also assumes that if a call to the xUpdate() method is made as
7725 ** implementation returns SQLITE_CONSTRAINT, then there is no need to rollback
7728 ** before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not
7734 ** If a virtual table extension is
7751 unsigned char usable; /* True if this constraint is usable */
7761 int argvIndex; /* if >0, constraint is part of argv to xFilter */
7767 int orderByConsumed; /* True if output is already ordered */
7791 ** an operator that is part of a constraint term in the WHERE clause of
7794 ** ^The left-hand operand of the operator is given by the corresponding
7796 ** operand is the rowid.
7799 ** corresponding aConstraint[].iColumn is meaningless and should not be
7809 ** operand is only available if it appears as a single constant literal
7810 ** in the input SQL. If the right-hand operand is another column or an
7822 ** interface is not commonly needed.
7851 ** ^The module name is registered on the [database connection] specified
7852 ** by the first parameter. ^The name of the module is given by the
7853 ** second parameter. ^The third parameter is a pointer to
7855 ** parameter is an arbitrary client data pointer that is passed through
7857 ** when a new virtual table is be being created or reinitialized.
7860 ** is a pointer to a destructor for the pClientData. ^SQLite will
7861 ** invoke the destructor function (if it is not NULL) when SQLite
7865 ** interface is equivalent to sqlite3_create_module_v2() with a NULL
7868 ** ^If the third parameter (the pointer to the sqlite3_module object) is
7869 ** NULL then no new module is created and any existing modules with the
7895 ** to strings where the array is terminated by a single NULL pointer.
7896 ** ^If the L parameter is NULL, then all virtual table modules are removed.
7913 ** The purpose of this superclass is to define certain fields that are
7918 ** take care that any prior string is freed by a call to [sqlite3_free()]
7920 ** is delivered up to the client application, the string will be automatically
7973 ** before this API is called, a new function is created.)^ ^The implementation
7975 ** the new function is not good for anything by itself. Its only
7976 ** purpose is to be a placeholder function that can be overloaded
8008 ** ^(Parameter zDb is not the filename that contains the database, but
8009 ** rather the symbolic name of the database. For attached databases, this is
8011 ** For the main database file, the database name is "main". For TEMP
8012 ** tables, the database name is "temp".)^
8014 ** ^If the flags parameter is non-zero, then the BLOB is opened for read
8015 ** and write access. ^If the flags parameter is zero, the BLOB is opened for
8018 ** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is stored
8019 ** in *ppBlob. Otherwise an [error code] is returned and, unless the error
8020 ** code is SQLITE_MISUSE, *ppBlob is set to NULL.)^ ^This means that, provided
8021 ** the API is not misused, it is always safe to call [sqlite3_blob_close()]
8028 ** <li> ^(Table zTable is a WITHOUT ROWID table)^,
8030 ** <li> ^(Row iRow is not present in the table)^,
8031 ** <li> ^(The specified column of row iRow contains a value that is not
8033 ** <li> ^(Column zColumn is part of an index, PRIMARY KEY or UNIQUE
8034 ** constraint and the blob is being opened for read/write access)^,
8036 ** column zColumn is part of a [child key] definition and the blob is
8049 ** cannot be changed after the [BLOB handle] is opened.
8051 ** ^(If the row that a BLOB handle points to is modified by an
8053 ** then the BLOB handle is marked as "expired".
8054 ** This is true if any column of the row is changed, even a column
8055 ** other than the one the BLOB handle is open on.)^
8092 ** ^This function is used to move an existing [BLOB handle] so that it points
8093 ** to a different row of the same database table. ^The new row is identified
8095 ** changed. ^The database, table and column on which the blob handle is open
8096 ** remain the same. Moving an existing [BLOB handle] to a new row is
8101 ** the nominated column.)^ ^If the new row is not present in the table, or if
8103 ** SQLite error code is returned and the blob handle is considered aborted.
8117 ** ^This function closes an open [BLOB handle]. ^(The BLOB handle is closed
8119 ** handle is still closed.)^
8122 ** the database is in auto-commit mode and there are no other open read-write
8123 ** blob handles or active write statements, the current transaction is
8125 ** code is returned and the transaction rolled back.
8127 ** Calling this function with an argument that is not a NULL pointer or an
8130 ** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function
8131 ** is passed a valid open blob handle, the values returned by the
8156 ** ^(This function is used to read data from an open [BLOB handle] into a
8160 ** ^If offset iOffset is less than N bytes from the end of the BLOB,
8161 ** [SQLITE_ERROR] is returned and no data is read. ^If N or iOffset is
8162 ** less than zero, [SQLITE_ERROR] is returned and no data is read.
8170 ** Otherwise, an [error code] or an [extended error code] is returned.)^
8185 ** ^(This function is used to write data into an open [BLOB handle] from a
8190 ** Otherwise, an [error code] or an [extended error code] is returned.)^
8191 ** ^Unless SQLITE_MISUSE is returned, this function sets the
8199 ** This function may only modify the contents of the BLOB; it is
8201 ** ^If offset iOffset is less than N bytes from the end of the BLOB,
8202 ** [SQLITE_ERROR] is returned and no data is written. The size of the
8205 ** than zero [SQLITE_ERROR] is returned and no data is written.
8226 ** A virtual filesystem (VFS) is an [sqlite3_vfs] object
8229 ** single default VFS that is appropriate for the host computer.
8236 ** ^If there is no match, a NULL pointer is returned.
8237 ** ^If zVfsName is NULL then the default VFS is returned.
8240 ** ^Each new VFS becomes the default VFS if the makeDflt flag is set.
8244 ** same name are registered, the behavior is undefined. If a
8245 ** VFS is registered with a name that is NULL or an empty string,
8246 ** then the behavior is undefined.
8249 ** ^(If the default VFS is unregistered, another VFS is chosen as
8250 ** the default. The choice for the new VFS is arbitrary.)^
8261 ** use by SQLite, code that links against SQLite is
8266 ** is selected automatically at compile-time. The following
8275 ** The SQLITE_MUTEX_NOOP implementation is a set of routines
8276 ** that does no real locking and is appropriate for use in
8281 ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
8283 ** implementation is included with the library. In this case the
8291 ** routine returns NULL if it is unable to allocate the requested
8314 ** a new mutex. ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
8315 ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
8320 ** implementation is available on the host platform, the mutex subsystem
8333 ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
8335 ** mutex types, the same mutex is returned on every call that has
8343 ** to enter a mutex. ^If another thread is already within the mutex,
8351 ** than an SQLITE_MUTEX_RECURSIVE more than once, the behavior is undefined.
8356 ** sqlite3_mutex_try() as an optimization, so this is acceptable
8359 ** sqlite3_mutex_try() is required.)^
8363 ** is undefined if the mutex is not currently entered by the
8364 ** calling thread or is not currently allocated.
8367 ** sqlite3_mutex_leave(), or sqlite3_mutex_free() is a NULL pointer,
8394 ** ^The xMutexInit method defined by this structure is invoked as
8396 ** ^The xMutexInit routine is called by SQLite exactly once for each
8399 ** ^The xMutexEnd method defined by this structure is invoked as
8401 ** implementation of this method is expected to release all outstanding
8404 ** interface is invoked exactly once for each call to [sqlite3_shutdown()].
8420 ** The only difference is that the public sqlite3_XXX functions enumerated
8425 ** (i.e. it is acceptable to provide an implementation that segfaults if
8426 ** it is passed a NULL pointer).
8438 ** ^SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is
8440 ** If xMutexInit fails in any way, it is expected to clean up after itself
8463 ** provides implementations for these routines when it is compiled
8465 ** are only required to provide these routines if SQLITE_DEBUG is
8466 ** defined and if NDEBUG is not defined.
8469 ** is held or not held, respectively, by the calling thread.
8471 ** The implementation is not required to provide versions of these
8476 ** If the argument to sqlite3_mutex_held() is a NULL pointer then
8479 ** the reason the mutex does not exist is because the build is not
8481 ** call to sqlite3_mutex_held() to fail, so a non-zero return is
8494 ** which is one of these integer constants.
8527 ** when the [threading mode] is Serialized.
8528 ** ^If the [threading mode] is Single-thread or Multi-thread then this
8541 ** name of the database is "main" for the main database or "temp" for the
8565 ** open database file, then SQLITE_ERROR is returned. ^This error
8566 ** code is not remembered and will not be recalled by [sqlite3_errcode()]
8568 ** also return SQLITE_ERROR. There is no way to distinguish between
8579 ** ^The sqlite3_test_control() interface is used to read out internal
8581 ** purposes. ^The first parameter is an operation code that determines
8584 ** This interface is not for use by applications. It exists solely
8586 ** on how the SQLite library is compiled, this interface might not exist.
8590 ** Unlike most of the SQLite API, this function is not guaranteed to
8656 ** of bytes in the keyword into *L. The string that *Z points to is not
8658 ** SQLITE_OK if N is within bounds and SQLITE_ERROR if not. If either Z
8663 ** the L-byte UTF8 identifier that Z points to is a keyword, returning non-zero
8664 ** if it is and zero if not.
8666 ** The parser used by SQLite is forgiving. It is often possible to use
8669 ** "CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" is accepted by SQLite, and
8671 ** "REPLACE", "PRAGMA", and "END". Nevertheless, best practice is to avoid
8675 ** <li> Put all identifier names inside double-quotes. This is the official
8677 ** <li> Put identifier names inside [...]. This is not standard SQL,
8678 ** but it is what SQL Server does and so lots of programmers use this
8686 ** compile-time options. For example, "VACUUM" is not a keyword if
8687 ** SQLite is compiled with the [-DSQLITE_OMIT_VACUUM] option. Also,
8701 ** The lifecycle of an sqlite3_str object is as follows:
8703 ** <li> ^The sqlite3_str object is created using [sqlite3_str_new()].
8704 ** <li> ^Text is appended to the sqlite3_str object using various
8706 ** <li> ^The sqlite3_str object is destroyed and the string it created
8707 ** is returned using the [sqlite3_str_finish()] interface.
8727 ** [sqlite3_str_finish(X)]. It is always safe to use the value
8732 ** D parameter in [sqlite3_str_new(D)] is not NULL, then the maximum
8750 ** string in [sqlite3_str] object X is zero bytes long.
8783 ** is recorded in the [sqlite3_str] object and can be recovered by a
8813 ** returned by [sqlite3_str_value(X)] is managed by the sqlite3_str object X
8831 ** highwater marks. ^The first argument is an integer code for
8834 ** ^The current value of the parameter is returned into *pCurrent.
8835 ** ^The highest recorded value is returned in *pHighwater. ^If the
8836 ** resetFlag is true, then the highest record value is reset after
8837 ** *pHighwater is written. ^(Some parameters do not record the highest
8839 ** nothing is written into *pHighwater and the resetFlag is ignored.)^
8841 ** value. For these latter parameters nothing is written into *pCurrent.)^
8846 ** If either the current value or the highwater mark is too large to
8870 ** <dd>This parameter is the current amount of memory checked out
8874 ** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
8875 ** this parameter. The amount returned is the sum of the allocation
8882 ** *pHighwater parameter to [sqlite3_status()] is of interest.
8883 ** The value written into the *pCurrent parameter is undefined.</dd>)^
8893 ** value returned is in pages, not in bytes.</dd>)^
8908 ** *pHighwater parameter to [sqlite3_status()] is of interest.
8909 ** The value written into the *pCurrent parameter is undefined.</dd>)^
8922 ** The *pCurrent value is undefined. The *pHighwater value is only
8923 ** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
8943 ** ^This interface is used to retrieve runtime status information
8944 ** about a single [database connection]. ^The first argument is the
8946 ** is an integer constant, taken from the set of
8949 ** [SQLITE_DBSTATUS options] is likely
8952 ** ^The current value of the requested parameter is written into *pCur
8953 ** and the highest instantaneous value is written into *pHiwtr. ^If
8954 ** the resetFlg is true, then the highest instantaneous value is
8975 ** if a discontinued or unsupported verb is invoked.
8984 ** satisfied using lookaside memory. Only the high-water value is meaningful;
8985 ** the current value is always zero.)^
8992 ** Only the high-water value is meaningful;
8993 ** the current value is always zero.)^
9000 ** Only the high-water value is meaningful;
9001 ** the current value is always zero.)^
9006 ** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.
9010 ** <dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a
9011 ** pager cache is shared between two or more connections the bytes of heap
9012 ** memory used by that pager cache is divided evenly between the attached
9018 ** SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0.
9024 ** ^The full amount of memory used by the schemas is reported, even if the
9025 ** schema memory is shared with other database connections due to
9027 ** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.
9033 ** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.
9039 ** is always 0.
9045 ** is always 0.
9055 ** on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined.)^ ^The
9056 ** highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0.
9071 ** resolved.)^ ^The highwater mark is always 0.
9101 ** that the prepared statement is using a full table scan rather than
9104 ** ^(This interface is used to retrieve and reset counter values from
9105 ** a [prepared statement]. The first argument is the prepared statement
9107 ** is an integer code for a specific [SQLITE_STMTSTATUS counter]
9109 ** ^The current value of the requested counter is returned.
9110 ** ^If the resetFlg is true, then the counter is reset to zero after this
9127 ** <dd>^This is the number of times that SQLite has stepped forward in
9133 ** <dd>^This is the number of sort operations that have occurred.
9138 ** <dd>^This is the number of rows inserted into transient indices that
9142 ** need to be reinitialized each time the statement is run.</dd>
9145 ** <dd>^This is the number of virtual machine operations executed
9146 ** by the prepared statement if that number is less than or equal
9150 ** then the value returned by this statement status code is undefined.
9153 ** <dd>^This is the number of times that the prepare statement has been
9158 ** <dd>^This is the number of times that the prepared statement has
9159 ** been run. A single "run" for the purposes of this counter is one
9161 ** The counter is incremented on the first [sqlite3_step()] call of each
9168 ** <dd>^SQLITE_STMTSTATUS_FILTER_HIT is the number of times that a join
9170 ** corresponding SQLITE_STMTSTATUS_FILTER_MISS value is the number of
9175 ** <dd>^This is the approximate number of bytes of heap memory
9176 ** used to store the prepared statement. ^This value is not actually
9178 ** is ignored when the opcode is SQLITE_STMTSTATUS_MEMUSED.
9195 ** The sqlite3_pcache type is opaque. It is implemented by
9229 ** SQLite is used for the page cache.
9233 ** that memory is allocated and released, and the policies used to
9237 ** The alternative page cache mechanism is an
9238 ** extreme measure that is only needed by the most demanding applications.
9239 ** The built-in page cache is recommended for most uses.
9247 ** ^(The xInit() method is called once for each effective
9250 ** method is passed a copy of the sqlite3_pcache_methods2.pArg value.)^
9251 ** The intent of the xInit() method is to set up global data structures
9253 ** ^(If the xInit() method is NULL, then the
9254 ** built-in default page cache is used instead of the application defined
9258 ** ^The xShutdown() method is called by [sqlite3_shutdown()].
9265 ** xShutdown method is only called from [sqlite3_shutdown()] so it does
9275 ** though this is not guaranteed. ^The
9276 ** first parameter, szPage, is the size in bytes of the pages that must
9278 ** second parameter szExtra is a number of bytes of extra storage
9284 ** ^The third argument to xCreate(), bPurgeable, is true if the cache being
9286 ** false if it is used for an in-memory database. The cache implementation
9288 ** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will
9298 ** instance passed as the first argument. This is the value configured using
9300 ** parameter, the implementation is not required to do anything with this
9301 ** value; it is advisory only.
9316 ** The page to be fetched is determined by the key. ^The minimum key value
9317 ** is 1. After it has been retrieved using xFetch, the page is considered
9320 ** If the requested page is already in the page cache, then the page cache
9322 ** intact. If the requested page is not already in the cache, then the
9327 ** <tr><th> createFlag <th> Behavior when page is not already in cache
9332 ** NULL if allocating a new page is effectively impossible.
9342 ** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
9343 ** as its second argument. If the third parameter, discard, is non-zero,
9345 ** ^If the discard parameter is
9355 ** The xRekey() method is used to change the key value associated with the
9358 ** discarded. ^Any prior cache entry associated with newKey is guaranteed not
9368 ** ^The xDestroy() method is used to delete a cache allocated by xCreate().
9377 ** is not obligated to free any memory, but well-behaved implementations should
9399 ** This is the obsolete pcache_methods object that has now been replaced
9400 ** by sqlite3_pcache_methods2. This object is not used by SQLite. It is
9423 ** online backup operation. ^The sqlite3_backup object is created by
9424 ** a call to [sqlite3_backup_init()] and is destroyed by a call to
9435 ** It is useful either for creating backups of databases or
9442 ** ^The source database is read-locked only while it is being read;
9443 ** it is not locked continuously for the entire backup operation.
9446 ** reading or writing to the source database while the backup is underway.
9450 ** <li><b>sqlite3_backup_init()</b> is called once to initialize the
9452 ** <li><b>sqlite3_backup_step()</b> is called one or more times to transfer
9454 ** <li><b>sqlite3_backup_finish()</b> is called to release all resources
9465 ** ^The database name is "main" for the main database, "temp" for the
9476 ** there is already a read or read-write transaction open on the
9479 ** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
9495 ** ^If N is negative, all remaining source pages are copied.
9501 ** then an [error code] is returned. ^As well as [SQLITE_OK] and
9509 ** <li> the destination database is using write-ahead-log journaling
9511 ** <li> the destination database is an in-memory database and the
9517 ** is invoked (if one is specified). ^If the
9518 ** busy-handler returns non-zero before the lock is available, then
9519 ** [SQLITE_BUSY] is returned to the caller. ^In this case the call to
9522 ** is being used to write to the source database when sqlite3_backup_step()
9523 ** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
9526 ** [SQLITE_READONLY] is returned, then
9527 ** there is no point in retrying the call to sqlite3_backup_step(). These
9533 ** on the destination file. ^The exclusive lock is not released until either
9534 ** sqlite3_backup_finish() is called or the backup operation is complete
9538 ** ^Because the source database is not locked between calls to
9540 ** through the backup process. ^If the source database is modified by an
9544 ** database is modified by the using the same database connection as is used
9545 ** by the backup operation, then the backup database is automatically
9556 ** active write-transaction on the destination database is rolled back.
9557 ** The [sqlite3_backup] object is invalid
9560 ** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
9568 ** is not a permanent error and does not affect the return value of
9580 ** sqlite3_backup_step(). If the source database is modified in a way that
9589 ** purposes while a backup operation is underway or being initialized.
9590 ** ^If SQLite is compiled and configured to support threadsafe database
9595 ** [database connection] is not passed to any other API (by any thread) after
9596 ** sqlite3_backup_init() is called and before the corresponding call to
9599 ** and so no error code is reported, but the operations may malfunction
9601 ** backup is in progress might also cause a mutex deadlock.
9605 ** is not accessed while the backup is running. In practice this means
9607 ** backed up to is not accessed by any connection within the process,
9610 ** The [sqlite3_backup] object itself is partially threadsafe. Multiple
9614 ** same time as another thread is invoking sqlite3_backup_step() it is
9638 ** ^This API is only available if the library was compiled with the
9647 ** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
9649 ** has locked the required resource is stored internally. ^After an
9653 ** when the blocking connections current transaction is concluded. ^The
9654 ** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
9657 ** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
9658 ** there is a chance that the blocking connection will have already
9659 ** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
9660 ** If this happens, then the specified callback is invoked immediately,
9663 ** ^If the blocked connection is attempting to obtain a write-lock on a
9669 ** blocked connection. If sqlite3_unlock_notify() is called when the
9671 ** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
9673 ** unlock-notify callback is canceled. ^The blocked connections
9677 ** The unlock-notify callback is not reentrant. If an application invokes
9681 ** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always
9686 ** When an unlock-notify callback is registered, the application provides a
9687 ** single void* pointer that is passed to the callback when it is invoked.
9690 ** an unlock-notify callback is a pointer to an array of void* pointers,
9691 ** and the second is the number of entries in the array.
9693 ** When a blocking connection's transaction is concluded, there may be
9697 ** multiple times, it is invoked once with the set of void* context pointers
9707 ** application to deadlock. For example, if connection X is waiting for
9709 ** Y is waiting on connection X's transaction, then neither connection
9714 ** system in a deadlocked state, then SQLITE_LOCKED is returned and no
9715 ** unlock-notify callback is registered. The system is said to be in
9719 ** A's transaction is concluded. ^Indirect deadlock is also detected, so
9720 ** the system is also considered to be deadlocked if connection B has
9722 ** C's transaction, where connection C is waiting on connection A. ^Any
9727 ** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost
9728 ** always appropriate to call sqlite3_unlock_notify(). There is however,
9731 ** that belong to the same connection. If there are, SQLITE_LOCKED is
9732 ** returned. In this case there is no "blocking connection", so invoking
9737 ** One way around this problem is to check the extended error code returned
9738 ** by an sqlite3_step() call. ^(If there is a blocking connection, then the
9739 ** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
9740 ** the special "DROP TABLE/INDEX" case, the extended error code is just
9767 ** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the
9769 ** is case sensitive.
9784 ** [sqlite3_strlike(P,X,E)] is the same as for the "X LIKE P ESCAPE E"
9787 ** ^As with the LIKE operator, the [sqlite3_strlike(P,X,E)] function is case
9806 ** ^If logging is enabled, the zFormat string and subsequent arguments are
9809 ** The sqlite3_log() interface is intended for use by extensions such as
9810 ** virtual tables, collating functions, and SQL functions. While there is
9812 ** is considered bad form.
9817 ** will not use dynamically allocated memory. The log message is stored in
9818 ** a fixed-length buffer on the stack. If the log message is longer than
9828 ** ^The [sqlite3_wal_hook()] function is used to register a callback that
9829 ** is invoked each time data is committed to a database in wal mode.
9831 ** ^(The callback is invoked by SQLite after the commit has taken place and
9835 ** ^The first parameter passed to the callback function when it is invoked
9836 ** is a copy of the third parameter passed to sqlite3_wal_hook() when
9837 ** registering the callback. ^The second is a copy of the database handle.
9838 ** ^The third parameter is the name of the database that was written to -
9840 ** is the number of pages currently in the write-ahead log file,
9844 ** code is returned, that error will propagate back up through the
9853 ** previously registered write-ahead log callback. ^The return value is
9869 ** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around
9891 ** is only necessary if the default setting is found to be suboptimal
9900 ** ^(The sqlite3_wal_checkpoint(D,X) is equivalent to
9911 ** interface was added. This interface is retained for backwards
9924 ** information is written back into integers pointed to by L and C.)^
9932 ** is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.
9938 ** [sqlite3_busy_handler|busy-handler callback]) until there is no
9941 ** database file. ^This mode blocks new database writers while it is pending,
9951 ** database writer attempts while it is pending, but does not impede readers.
9959 ** ^If pnLog is not NULL, then *pnLog is set to the total number of frames in
9961 ** of an error or because the database is not in [WAL mode]. ^If pnCkpt is not
9962 ** NULL,then *pnCkpt is set to the total number of checkpointed frames in the
9965 ** because the database is not in WAL mode. ^Note that upon successful
9970 ** any other process is running a checkpoint operation at the same time, the
9971 ** lock cannot be obtained and SQLITE_BUSY is returned. ^Even if there is a
9976 ** obtained immediately, and a busy-handler is configured, it is invoked and
9978 ** is successfully obtained. ^The busy-handler is also invoked while waiting for
9980 ** the writer lock is obtained or while waiting for database readers, the
9983 ** without blocking any further. ^SQLITE_BUSY is returned in this case.
9985 ** ^If parameter zDb is NULL or points to a zero length string, then the
9986 ** specified operation is attempted on all WAL databases [attached] to
9989 ** an SQLITE_BUSY error is encountered when processing one or more of the
9990 ** attached WAL databases, the operation is still attempted on any remaining
9991 ** attached databases and SQLITE_BUSY is returned at the end. ^If any other
9992 ** error occurs while processing an attached database, processing is abandoned
9993 ** and the error code is returned to the caller immediately. ^If no error
9994 ** (SQLITE_BUSY or otherwise) is encountered while processing the attached
9995 ** databases, SQLITE_OK is returned.
9997 ** ^If database zDb is the name of an attached database that is not in WAL
9998 ** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. ^If
9999 ** zDb is not NULL (or a zero length string) and is not the name of any
10000 ** attached database, SQLITE_ERROR is returned to the caller.
10004 ** sets the error information that is queried by
10039 ** If this interface is invoked outside the context of an xConnect or
10040 ** xCreate virtual table method then the behavior is undefined.
10042 ** In the call sqlite3_vtab_config(D,C,...) the D parameter is the
10043 ** [database connection] in which the virtual table is being created and
10044 ** which is passed in as the first argument to the [xConnect] or [xCreate]
10045 ** method that is invoking sqlite3_vtab_config(). The C parameter is one
10048 ** is used.
10066 ** where X is an integer. If X is zero, then the [virtual table] whose
10068 ** support constraints. In this configuration (which is the default) if
10070 ** statement is rolled back as if [ON CONFLICT | OR ABORT] had been
10074 ** If X is non-zero, then the virtual table implementation guarantees
10077 ** If the [ON CONFLICT] mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite
10078 ** is able to roll back a statement or database transaction, and abandon
10080 ** If the ON CONFLICT mode is REPLACE and the [xUpdate] method returns
10087 ** CONFLICT policy is REPLACE, the virtual table implementation should
10089 ** return SQLITE_OK. Or, if this is not possible, it may return
10108 ** virtual table can do no serious harm even if it is controlled by a
10119 ** virtual table is used.
10133 ** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL],
10143 ** If the sqlite3_vtab_nochange(X) routine is called within the [xColumn]
10145 ** column is being fetched as part of an UPDATE operation during which the
10147 ** this hint as permission to substitute a return value that is less
10152 ** the column is not changed by the UPDATE statement, then the xColumn
10158 ** The sqlite3_vtab_nochange() routine is an optimization. Virtual table
10172 ** that is the name of the appropriate collation sequence to use for text
10176 ** that is the first parameter to the xBestIndex() method. The second argument
10181 ** The first parameter must be the same pointer that is passed into the
10185 ** The return value is computed as follows:
10190 ** that COLLATE operator is returned.
10191 ** <li><p> If there is no COLLATE operator, but the column that is the subject
10195 ** name of that alternative collating sequence is returned.
10196 ** <li><p> Otherwise, "BINARY" is returned.
10202 ** CAPI3REF: Determine if a virtual table query is DISTINCT
10207 ** interface from outside of xBestIndex() is undefined and probably harmful.
10220 ** [sqlite3_index_info] object. This is the default expectation. If the
10221 ** virtual table outputs all rows in sorted order, then it is always safe for
10228 ** "aOrderBy" field are adjacent.)^ This mode is used when the query planner
10229 ** is doing a GROUP BY.
10236 ** needs to be returned.)^ ^It is always ok for two or more rows with the same
10240 ** ^However omitting the extra rows is optional.
10241 ** This mode is used for a DISTINCT query.
10245 ** rows to be sorted.)^ ^The virtual table implementation is free to omit
10247 ** it is not required to omit any rows. This mode is used for queries
10253 ** to be the same. In other words, the comparison operator is "IS"
10256 ** If a virtual table implementation is unable to meet the requirements
10260 ** ^A virtual table implementation is always free to return rows in any order
10261 ** it wants, as long as the "orderByConsumed" flag is not set. ^When the
10262 ** the "orderByConsumed" flag is unset, the query planner will add extra
10265 ** sqlite3_vtab_distinct() interface is merely an optimization. ^Careful
10268 ** overly aggressive and setting the "orderByConsumed" flag when it is not
10279 ** The result of invoking this interface from any other context is
10283 ** "[IN operator|column IN (...)]" is
10302 ** is an [IN operator] that can be processed all at once. ^In other words,
10303 ** sqlite3_vtab_in() with -1 in the third argument is a mechanism
10305 ** of the IN operator is even possible.
10311 ** parameter (F) is non-negative, this interface is the mechanism by
10320 ** (non-zero), that means that the constraint is an IN operator
10321 ** that can be processed all-at-once. ^If the constraint is not an IN
10325 ** ^(All-at-once processing of the IN operator is selected if both of the
10329 ** <li><p> The P->aConstraintUsage[N].argvIndex value is set to a positive
10330 ** integer. This is how the virtual table tells SQLite that it wants to
10353 ** is undefined and probably harmful.
10360 ** [xBestIndex|xBestIndex method]. ^(If the X parameter is not
10382 ** right hand side of the IN constraint, then *P is set to NULL and these
10403 ** ^When the sqlite3_vtab_rhs_value(P,J,V) interface is invoked from within
10408 ** that constraint if the right-hand operand is known. ^If the
10409 ** right-hand operand is not known, then *V is set to a NULL pointer.
10411 ** and only if *V is set to a value. ^The sqlite3_vtab_rhs_value(P,J,V)
10413 ** constraint is not available. ^The sqlite3_vtab_rhs_value() interface
10417 ** The sqlite3_vtab_rhs_value() interface is usually only successful if
10418 ** the right-hand operand of a constraint is a literal value in the original
10419 ** SQL statement. If the right-hand operand is an expression or a reference
10427 ** ^The [sqlite3_value] object returned in *V is a protected sqlite3_value
10430 ** sqlite3_vtab_rhs_value() is automatically deallocated.
10432 ** The "_rhs_" in the name of this routine is an abbreviation for
10443 ** is for the SQL statement being evaluated.
10445 ** Note that the [SQLITE_IGNORE] constant is also used as a potential
10447 ** [SQLITE_ABORT] is also a [result code].
10463 ** When the value returned to V is a string, space to hold that string is
10465 ** S is finalized.
10467 ** Not all values are available for all query elements. When a value is
10468 ** not available, the output variable is set to -1 if the value is numeric,
10469 ** or to NULL if it is a string (SQLITE_SCANSTAT_NAME).
10500 ** id for the X-th query plan element. The id value is unique within the
10501 ** statement. The select-id is the same value as is output in the first
10507 ** to zero if the query element has no parent. This is the same value as
10511 ** <dd>The sqlite3_int64 output value is set to the number of cycles,
10513 ** query element was being processed. This value is not available for
10514 ** all query elements - if it is unavailable the output variable is
10536 ** Since this interface is expected to be rarely used, it is only
10537 ** available if SQLite is compiled using the [SQLITE_ENABLE_STMT_SCANSTATUS]
10542 ** of this interface is undefined. ^The requested measurement is written into
10546 ** one flag is defined - SQLITE_SCANSTAT_COMPLEX. If SQLITE_SCANSTAT_COMPLEX
10547 ** is specified, then status information is available for all elements
10549 ** SQLITE_SCANSTAT_COMPLEX is not specified, then only query plan elements
10552 ** sqlite3_stmt_scanstatus() is equivalent to calling
10557 ** to query for statistics regarding the entire query. ^If idx is out of range
10559 ** elements used to implement the statement - a non-zero value is returned and
10560 ** the variable that pOut points to is unchanged.
10590 ** This API is only available if the library is built with pre-processor
10599 ** ^If a write-transaction is open on [database connection] D when the
10603 ** active SQL statement is reading from it, or if it is page 1 of a database
10604 ** file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)]
10610 ** immediately and there is a busy-handler callback configured, it is invoked
10612 ** the database is skipped and an attempt made to flush any dirty pages
10618 ** example an IO error or out-of-memory condition), then processing is
10619 ** abandoned and an SQLite [error code] is returned to the caller immediately.
10632 ** ^These interfaces are only available if SQLite is compiled using the
10636 ** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation
10641 ** ^The preupdate hook is disabled by invoking [sqlite3_preupdate_hook()]
10643 ** ^The third parameter to [sqlite3_preupdate_hook()] is passed through as
10647 ** preupdate hook is not invoked for changes to [virtual tables] or to
10650 ** ^The second parameter to the preupdate callback is a pointer to
10652 ** ^The third parameter to the preupdate callback is one of the constants
10654 ** kind of update operation that is about to occur.
10655 ** ^(The fourth parameter to the preupdate callback is the name of the
10656 ** database within the database connection that is being modified. This
10660 ** ^The fifth parameter to the preupdate callback is the name of the
10661 ** table that is being modified.
10664 ** parameter passed to the preupdate callback is the initial [rowid] of the
10667 ** parameter is undefined. For an INSERT or UPDATE on a rowid table the
10668 ** seventh parameter is the final rowid value of the row being inserted
10670 ** function is not defined for operations on WITHOUT ROWID tables, or for
10682 ** [database connection] pointer that is different from the one supplied
10687 ** in the row that is being inserted, updated, or deleted.
10691 ** the table row before it is updated. The N parameter must be between 0
10694 ** preupdate callbacks; if it is used by an SQLITE_INSERT callback then the
10695 ** behavior is undefined. The [sqlite3_value] that P points to
10700 ** the table row after it is updated. The N parameter must be between 0
10703 ** preupdate callbacks; if it is used by an SQLITE_DELETE callback then the
10704 ** behavior is undefined. The [sqlite3_value] that P points to
10713 ** When the [sqlite3_blob_write()] API is used to update a blob column,
10714 ** the pre-update hook is invoked with SQLITE_DELETE. This is because the
10716 ** callback made with op==SQLITE_DELETE is actually a write using the
10719 ** pre-update hook is being invoked for some other reason, including a
10751 ** The return value is OS-dependent. For example, on unix systems, after
10771 ** by the reader until a new read transaction is started.
10774 ** version of the database file so that it is possible to later open a new read
10791 ** If there is not already a read-transaction open on schema S when
10792 ** this function is called, one is opened automatically.
10795 ** the following statements are false when sqlite3_snapshot_get() is
10796 ** called, SQLITE_ERROR is returned. The final value of *P is undefined
10810 ** file immediately after it is first opened. At least one transaction
10814 ** This function may also return SQLITE_NOMEM. If it is called with the
10816 ** whether or not a read transaction is opened on schema S is undefined.
10822 ** The [sqlite3_snapshot_get()] interface is only available when the
10823 ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
10843 ** [autocommit mode] when [sqlite3_snapshot_open(D,S,P)] is called. If there
10844 ** is already a read transaction open on schema S, then the database handle
10847 ** SQLITE_ERROR is returned if either of these conditions is violated, or
10848 ** if schema S does not exist, or if the snapshot object is invalid.
10852 ** SQLITE_ERROR_SNAPSHOT is returned.
10854 ** If there is already a read transaction open when this function is
10857 ** is returned. If another error code - for example SQLITE_PROTOCOL or an
10858 ** SQLITE_IOERR error code - is returned, then the final state of the
10859 ** read transaction is undefined. If SQLITE_OK is returned, then the
10860 ** read transaction is now open on database snapshot P.
10864 ** schema S is in [WAL mode]. A database connection might not know
10865 ** that the database file is in [WAL mode] if there has been no prior
10871 ** The [sqlite3_snapshot_open()] interface is only available when the
10872 ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
10888 ** The [sqlite3_snapshot_free()] interface is only available when the
10889 ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
10897 ** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages
10901 ** file, the result of the comparison is undefined.
10903 ** Additionally, the result of the comparison is only valid if both of the
10905 ** last time the wal file was deleted. The wal file is deleted when the
10906 ** database is changed back to rollback mode or when the number of database
10909 ** is undefined.
10913 ** snapshot, and a positive value if P1 is a newer snapshot than P2.
10915 ** This interface is only available if SQLite is compiled with the
10930 ** calling [sqlite3_close()]) and a new connection is subsequently opened
10937 ** sqlite3_snapshot_open(). It is an error if there is already a read
10938 ** transaction open on the database, or if the database is not a WAL mode
10941 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
10943 ** This interface is only available if SQLite is compiled with the
10952 ** that is a serialization of the S database on [database connection] D.
10953 ** If P is not a NULL pointer, then the size of the database in bytes
10954 ** is written into *P.
10956 ** For an ordinary on-disk database file, the serialization is just a
10958 ** the serialization is the same sequence of bytes which would be written
10961 ** The usual case is that sqlite3_serialize() copies the serialization of
10963 ** a pointer to that memory. The caller is responsible for freeing the
10968 ** is currently using for that database, or NULL if the no such contiguous
10973 ** The size of the database is written into *P even if the
10974 ** SQLITE_SERIALIZE_NOCOPY bit is set but no contiguous copy
10980 ** the connection is closed, and applications must not modify the
10985 ** SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory
10988 ** This interface is omitted if SQLite is compiled with the
11005 ** a pointer to contiguous in-memory database that it is currently using,
11006 ** without making a copy of the database. If SQLite is not currently using
11020 ** in P. The serialized database P is N bytes in size. M is the size of
11021 ** the buffer P, which might be larger than N. If M is larger than N, and
11022 ** the SQLITE_DESERIALIZE_READONLY bit is not set in F, then SQLite is
11026 ** If the SQLITE_DESERIALIZE_FREEONCLOSE bit is set in F, then SQLite will
11028 ** connection closes. If the SQLITE_DESERIALIZE_RESIZEABLE bit is set, then
11033 ** the database connection D is closed.
11036 ** database is currently in a read transaction or is involved in a backup
11039 ** It is not possible to deserialized into the TEMP database. If the
11040 ** S argument to sqlite3_deserialize(D,S,P,N,M,F) is "temp" then the
11044 ** is in WAL mode, then any attempt to use the database file will result
11051 ** SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F, then
11052 ** [sqlite3_free()] is invoked on argument P prior to returning.
11054 ** This interface is omitted if SQLite is compiled with the
11073 ** in the P argument is held in memory obtained from [sqlite3_malloc64()]
11076 ** is responsible for freeing any dynamically allocated memory.
11078 ** The SQLITE_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed to
11080 ** flag should only be used if SQLITE_DESERIALIZE_FREEONCLOSE is also used.
11089 #define SQLITE_DESERIALIZE_READONLY 4 /* Database is read-only */
11122 ** a legal notice, here is a blessing:
11166 ** A pointer to a structure of the following type is passed as the first
11193 ** A pointer to a structure of the following type is passed as the
11198 ** sqlite3_rtree_geometry. This structure is a subclass of
11252 ** An instance of this object is a [session] that can be used to
11270 ** a pointer to the new object is written to *ppSession and SQLITE_OK is
11271 ** returned. If an error occurs, *ppSession is set to NULL and an SQLite
11272 ** error code (e.g. SQLITE_NOMEM) is returned.
11274 ** It is possible to create multiple session objects attached to a single
11279 ** are attached to is itself closed. If the database handle is closed before
11280 ** the session object is deleted, then the results of calling any session
11285 ** is not possible for an application to register a pre-update hook on a
11286 ** database handle that has one or more session objects attached. Nor is
11288 ** which a pre-update hook is already defined. The results of attempting
11292 ** database zDb, where zDb is either "main", or "temp", or the name of an
11293 ** attached database. It is not an error if database zDb is not attached
11294 ** to the database when the session object is created.
11312 ** are attached is closed. Refer to the documentation for
11321 ** This method is used to configure a session object after it has been
11335 ** This option is used to set, clear or query the flag that enables
11337 ** computational overhead, this API is disabled by default. Argument
11338 ** pArg must point to a value of type (int). If the value is initially
11339 ** 0, then the sqlite3session_changeset_size() API is disabled. If it
11340 ** is greater than 0, then the same API is enabled. Or, if the initial
11341 ** value is less than zero, no change is made. In all cases the (int)
11342 ** variable is set to 1 if the sqlite3session_changeset_size() API is
11345 ** It is an error (SQLITE_MISUSE) to attempt to modify this setting after
11349 ** This option is used to set, clear or query the flag that enables
11353 ** by the sessions module. However, if this flag is set, it behaves
11357 ** It is an error (SQLITE_MISUSE) to attempt to modify this setting after
11369 ** disabled - it does not. A newly created session object is enabled.
11375 ** greater than zero enables it. Passing a value less than zero is a
11379 ** the session is disabled, or 1 if it is enabled.
11387 ** Each change recorded by a session object is marked as either direct or
11388 ** indirect. A change is marked as indirect if either:
11391 ** <li> The session object "indirect" flag is set when the change is
11393 ** <li> The change is made by an SQL trigger or foreign key action
11397 ** If a single row is affected by more than one operation within a session,
11398 ** then the change is considered indirect if all operations meet the criteria
11401 ** This function is used to set, clear or query the session object indirect
11402 ** flag. If the second argument passed to this function is zero, then the
11403 ** indirect flag is cleared. If it is greater than zero, the indirect flag
11404 ** is set. Passing a value less than zero does not modify the current value
11409 ** it is clear, or 1 if it is set.
11417 ** If argument zTab is not NULL, then it is the name of a table to attach
11419 ** made to the table while the session object is enabled will be recorded. See
11422 ** Or, if argument zTab is NULL, then changes are recorded for all tables
11424 ** executing "CREATE TABLE" statements) after this call is made, changes for
11429 ** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY
11432 ** It is not an error if the named table does not exist in the database. Nor
11433 ** is it an error if the named table does not have a PRIMARY KEY. However,
11439 ** SQLITE_OK is returned if the call completes without error. Or, if an error
11440 ** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.
11444 ** As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception to
11445 ** some of the rules above. In SQLite, the schema of sqlite_stat1 is:
11451 ** recorded for it as if the PRIMARY KEY is (tbl,idx). Additionally, changes
11452 ** are recorded for rows for which (idx IS NULL) is true. However, for such
11453 ** rows a zero-length blob (SQL value X'') is stored in the changeset or
11463 ** conflict-handler callback) then the X'' value is returned. The application
11480 ** The second argument (xFilter) is the "filter callback". For changes to rows
11481 ** in tables that are not attached to the Session object, the filter is called
11483 ** If xFilter returns 0, changes are not tracked. Note that once a table is
11512 ** column. It is not possible for an UPDATE change to represent a change that
11513 ** modifies the values of primary key columns. If such a change is made, it
11514 ** is represented in a changeset as a DELETE followed by an INSERT.
11517 ** more of their PRIMARY KEY columns. If such a row is inserted or deleted,
11518 ** no corresponding change is present in the changesets returned by this
11520 ** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,
11521 ** only an INSERT is appears in the changeset. Similarly, if an existing row
11522 ** with non-NULL PRIMARY KEY values is updated so that one or more of its
11537 ** a single table are stored is undefined.
11539 ** Following a successful call to this function, it is the responsibility of
11548 ** deleted or updated rows. For each unique primary key value, data is only
11549 ** recorded once - the first time a row with said primary key is inserted,
11552 ** There is one exception to the previous paragraph: when a row is inserted,
11554 ** NULL value, no record of the change is made.
11562 ** When this function is called, the requested changeset is created using
11567 ** <li> For each record generated by an insert, the database is queried
11568 ** for a row with a matching primary key. If one is found, an INSERT
11569 ** change is added to the changeset. If no such row is found, no change
11570 ** is added to the changeset.
11572 ** <li> For each record generated by an update or delete, the database is
11573 ** queried for a row with a matching primary key. If such a row is
11575 ** modified from their original values, an UPDATE change is added to
11576 ** the changeset. Or, if no such row is found in the table, a DELETE
11577 ** change is added to the changeset. If there is a row with a matching
11579 ** values, no change is added to the changeset.
11582 ** This means, amongst other things, that if a row is inserted and then later
11583 ** deleted while a session object is active, neither the insert nor the delete
11584 ** will be present in the changeset. Or if a row is deleted and then later a
11585 ** row with the same primary key values inserted while a session object is
11589 ** When a session object is disabled (see the [sqlite3session_enable()] API),
11592 ** is written to more than once during a session. For example, if a row
11593 ** is inserted while a session object is enabled, then later deleted while
11594 ** the same session object is disabled, no INSERT record will appear in the
11596 ** Or, if one field of a row is updated while a session is disabled, and
11597 ** another field of the same row is updated while the session is enabled, the
11626 ** If it is not already attached to the session object passed as the first
11629 ** does not have a primary key, this function is a no-op (but does not return
11635 ** A table is considered compatible if it:
11643 ** If the tables are not compatible, SQLITE_SCHEMA is returned. If the tables
11644 ** are compatible but do not have any PRIMARY KEY columns, it is not an error
11650 ** so that its content is the same as the table attached to the session
11655 ** the from-table, an INSERT record is added to the session object.
11658 ** the from-table, a DELETE record is added to the session object.
11661 ** different non-PK values in each, an UPDATE record is added to the
11665 ** To clarify, if this function is called and then a changeset constructed
11673 ** If the operation is successful, SQLITE_OK is returned. Otherwise, an SQLite
11674 ** error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg
11676 ** message. It is the responsibility of the caller to free this buffer using
11702 ** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly,
11708 ** is passed to the sqlite3changeset_apply() API. Other conflict types work
11729 ** Even if this function returns zero, it is possible that calling
11732 ** an attached table is modified and then later on the original values
11733 ** are restored. However, if this function returns non-zero, then it is
11752 ** If successful, *pp is set to point to the iterator handle and SQLITE_OK
11753 ** is returned. Otherwise, if an error occurs, *pp is set to zero and an
11754 ** SQLite error code is returned.
11766 ** It is the responsibility of the caller to eventually destroy the iterator
11768 ** changeset (pChangeset) must remain valid until after the iterator is
11777 ** consecutively. There is no chance that the iterator will visit a change
11785 ** Note that the sqlite3changeset_start_v2() API is still <b>experimental</b>
11807 ** Invert the changeset while iterating through it. This is equivalent to
11809 ** It is an error to specify this flag with a patchset.
11819 ** [sqlite3changeset_start()]. If it is called on an iterator passed to
11821 ** is returned and the call has no effect.
11823 ** Immediately after an iterator is created by sqlite3changeset_start(), it
11825 ** is not empty, the first call to this function advances the iterator to
11829 ** to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned.
11831 ** SQLITE_DONE is returned.
11833 ** If an error occurs, an SQLite error code is returned. Possible error
11834 ** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or
11847 ** is not the case, this function returns [SQLITE_MISUSE].
11852 ** *pOp is set to one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],
11855 ** *pnCol is set to the number of columns in the table affected by the change; and
11857 ** *pzTab is set to point to a nul-terminated utf-8 encoded string containing
11859 ** valid until either sqlite3changeset_next() is called on the iterator
11862 ** If pbIndirect is not NULL, then *pbIndirect is set to true (1) if the change
11863 ** is an indirect change, or false (0) otherwise. See the documentation for
11867 ** If no error occurs, SQLITE_OK is returned. If an error does occur, an
11868 ** SQLite error code is returned. The values of the output variables may not
11890 ** This function is used to find which columns comprise the PRIMARY KEY of
11892 ** If successful, *pabPK is set to point to an array of nCol entries, where
11893 ** nCol is the number of columns in the table. Elements of *pabPK are set to
11894 ** 0x01 if the corresponding column is part of the tables primary key, or
11895 ** 0x00 if it is not.
11897 ** If argument pnCol is not NULL, then *pnCol is set to the number of columns
11900 ** If this function is called when the iterator does not point to a valid
11901 ** entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise,
11902 ** SQLITE_OK is returned and the output variables populated as described
11920 ** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise,
11925 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
11931 ** is similar to the "old.*" columns available to update or delete triggers.
11934 ** is returned and *ppValue is set to NULL.
11951 ** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise,
11956 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
11961 ** returns SQLITE_OK. If the change is an UPDATE and does not include
11962 ** a new value for the requested column, *ppValue is set to NULL and
11964 ** this is similar to the "new.*" columns available to update or delete
11968 ** is returned and *ppValue is set to NULL.
11983 ** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue
11984 ** is set to NULL.
11988 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
11996 ** is returned and *ppValue is set to NULL.
12025 ** This function is used to finalize an iterator allocated with
12031 ** [sqlite3changeset_apply()], [SQLITE_MISUSE] is immediately returned and the
12037 ** to that error is returned by this function. Otherwise, SQLITE_OK is
12038 ** returned. This is to allow the following pattern (pseudo-code):
12056 ** This function is used to "invert" a changeset object. Applying an inverted
12061 ** <li> Each DELETE change is changed to an INSERT, and
12062 ** <li> Each INSERT change is changed to a DELETE, and
12070 ** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and
12071 ** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are
12074 ** It is the responsibility of the caller to eventually call sqlite3_free()
12078 ** WARNING/TODO: This function currently assumes that the input is a valid
12079 ** changeset. If it is not, the results are undefined.
12089 ** This function is used to concatenate two changesets, A and B, into a
12090 ** single changeset. The result is a changeset equivalent to applying
12137 ** A changegroup is an object used to combine two or more
12146 ** An sqlite3_changegroup object is used to combine two or more changesets
12148 ** object may combine changesets or patchsets, but not both. The output is
12155 ** (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL.
12157 ** The usual usage pattern for an sqlite3_changegroup object is as follows:
12160 ** <li> It is created using a call to sqlite3changegroup_new().
12165 ** <li> The result of combining all input changesets together is obtained
12168 ** <li> The object is deleted using a call to sqlite3changegroup_delete().
12187 ** sqlite3changegroup_add() is called to add a changeset that is not compatible
12188 ** with the configured schema, SQLITE_SCHEMA is returned and the changegroup
12189 ** object is left in an undefined state.
12191 ** A changeset schema is considered compatible with the database schema in
12222 ** function. Otherwise, SQLITE_ERROR is returned and no changes are added
12226 ** their PRIMARY KEY columns. A change in the changeset is considered to
12240 ** The new change is ignored. This case does not occur if the new
12248 ** The existing INSERT is removed from the changegroup. The DELETE is
12251 ** The new change is ignored. This case does not occur if the new
12255 ** The existing UPDATE remains within the changegroup. It is amended
12259 ** The existing UPDATE is replaced by the new DELETE within the
12264 ** change, the existing DELETE is replaced by an UPDATE within the
12265 ** changegroup. Otherwise, if the inserted row is exactly the same
12266 ** as the deleted row, the existing DELETE is simply discarded.
12268 ** The new change is ignored. This case does not occur if the new
12272 ** The new change is ignored. This case does not occur if the new
12277 ** If the new changeset contains changes to a table that is already present
12279 ** primary key columns for the table must be consistent. If this is not the
12282 ** sqlite3changegroup_schema() API, then it is possible to combine changesets
12286 ** If the input changeset appears to be corrupt and the corruption is
12287 ** detected, SQLITE_CORRUPT is returned. Or, if an out-of-memory condition
12291 ** changegroup is undefined. If no error occurs, SQLITE_OK is returned.
12301 ** were themselves changesets, the output is a changeset. Or, if the
12302 ** inputs were patchsets, the output is also a patchset.
12313 ** If an error occurs, an SQLite error code is returned and the output
12315 ** is returned and the output variables are set to the size of and a
12316 ** pointer to the output buffer, respectively. In this case it is the
12339 ** The fourth argument (xFilter) passed to these functions is the "filter
12340 ** callback". If it is not NULL, then for each table affected by at least one
12341 ** change in the changeset, the filter callback is invoked with
12344 ** returns zero, then no attempt is made to apply any changes to the table.
12345 ** Otherwise, if the return value is non-zero or the xFilter argument to
12346 ** is NULL, all changes related to the table are attempted.
12348 ** For each table that is not excluded by the filter callback, this function
12349 ** tests that the target database contains a compatible table. A table is
12361 ** If there is no compatible table, it is not an error, but none of the
12362 ** changes associated with the table are applied. A warning message is issued
12364 ** one such warning is issued for each table in the changeset.
12366 ** For each change for which there is a compatible table, an attempt is made
12370 ** invoked. A description of exactly when the conflict handler is invoked for
12371 ** each type of change is below.
12377 ** Each time the conflict handler function is invoked, it must return one
12380 ** if the second argument passed to the conflict handler is either
12395 ** the changeset the row is deleted from the target database.
12397 ** If a row with matching primary key values is found, but one or more of
12399 ** row value stored in the changeset, the conflict-handler function is
12406 ** If no row with matching primary key values is found in the database,
12407 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
12410 ** If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT
12411 ** (which can only happen if a foreign key constraint is violated), the
12412 ** conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT]
12414 ** operation is attempted because an earlier call to the conflict handler
12418 ** For each INSERT change, an attempt is made to insert the new row into
12425 ** function is invoked with the second argument set to
12429 ** violation (e.g. NOT NULL or UNIQUE), the conflict handler function is
12431 ** This includes the case where the INSERT operation is re-attempted because
12440 ** stored in the changeset the row is updated within the target database.
12442 ** If a row with matching primary key values is found, but one or more of
12445 ** is invoked with [SQLITE_CHANGESET_DATA] as the second argument. Since
12450 ** If no row with matching primary key values is found in the database,
12451 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
12454 ** If the UPDATE operation is attempted, but SQLite returns
12455 ** SQLITE_CONSTRAINT, the conflict-handler function is invoked with
12457 ** This includes the case where the UPDATE operation is attempted after
12462 ** It is safe to execute SQL statements, including those that write to the
12469 ** write to the target database) occurs, then the savepoint transaction is
12474 ** the input is a changeset (not a patchset), then sqlite3changeset_apply_v2()
12477 ** is set to the size of the buffer in bytes. It is the responsibility of the
12479 ** is only allocated and populated if one or more conflicts were encountered
12487 ** Note that the sqlite3changeset_apply_v2() API is still <b>experimental</b>
12533 ** SAVEPOINT is committed if the changeset or patchset is successfully
12536 ** caller has an open transaction or savepoint when apply_v2() is called,
12540 ** Invert the changeset before applying it. This is equivalent to inverting
12541 ** a changeset using sqlite3changeset_invert() before applying it. It is
12547 ** Specifically, this means that the conflict handler is not invoked
12575 ** The conflict handler is invoked with CHANGESET_DATA as the second argument
12577 ** PRIMARY KEY fields is present in the database, but one or more other
12581 ** The conflicting row, in this case, is the database row with the matching
12585 ** The conflict handler is invoked with CHANGESET_NOTFOUND as the second
12587 ** required PRIMARY KEY fields is not present in the database.
12589 ** There is no conflicting row in this case. The results of invoking the
12593 ** CHANGESET_CONFLICT is passed as the second argument to the conflict
12597 ** The conflicting row in this case is the database row with the matching
12601 ** If foreign key handling is enabled, and applying a changeset leaves the
12603 ** handler is invoked with CHANGESET_FOREIGN_KEY as the second argument
12604 ** exactly once before the changeset is committed. If the conflict handler
12607 ** CHANGESET_ABORT, the changeset is rolled back.
12609 ** No current or conflicting row information is provided. The only function
12610 ** it is possible to call on the supplied sqlite3_changeset_iter handle
12611 ** is sqlite3changeset_fk_conflicts().
12615 ** a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is
12618 ** There is no conflicting row in this case. The results of invoking the
12636 ** If a conflict handler returns this value no special action is taken. The
12637 ** change that caused the conflict is not applied. The session module
12643 ** is not the case, any changes applied so far are rolled back and the
12646 ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict
12647 ** handler, then the conflicting row is either updated or deleted, depending
12650 ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_CONFLICT conflict
12651 ** handler, then the conflicting row is removed from the database and a
12652 ** second attempt to apply the change is made. If this second attempt fails,
12653 ** the original row is restored to the database before continuing.
12656 ** If this value is returned, any changes applied so far are rolled back
12668 ** Suppose there is a site hosting a database in state S0. And that
12671 ** on S0 is received from another site (the "remote" changeset) and
12672 ** applied to the database. The database is then in state
12675 ** Rebasing a changeset is to update it to take those conflict
12685 ** and the conflict resolution is REPLACE, then the INSERT change is
12687 ** conflict resolution was "OMIT", then the local changeset is modified
12703 ** only possible resolution is OMIT. If the remote operation was a
12711 ** is changed into an INSERT. Any undefined values in the new.* record
12714 ** the UPDATE change is simply omitted from the rebased changeset.
12716 ** If conflict is with a remote UPDATE and the resolution is OMIT, then
12718 ** change. Or, if the resolution is REPLACE, then the change is copied
12721 ** be updated, the change is omitted.
12725 ** simultaneously. If a single key is modified by multiple remote
12727 ** is rebased:
12731 ** key, it is rebased according to a REPLACE.
12734 ** the local changeset is rebased according to the most recent
12749 ** <li> An sqlite3_rebaser object is created by calling
12751 ** <li> The new object is configured with the rebase buffer obtained from
12753 ** If the local changeset is to be rebased against multiple remote
12757 ** <li> Each local changeset is rebased by calling sqlite3rebaser_rebase().
12758 ** <li> The sqlite3_rebaser object is deleted by calling
12797 ** is set to point to the new buffer containing the rebased changeset and
12798 ** (*pnOut) to its size in bytes and SQLITE_OK returned. It is the
12840 ** Normally this is convenient. However, if an application running in a
12841 ** low-memory environment is required to handle very large changesets, the
12845 ** is passed to a streaming API functions by way of a callback function that
12846 ** the sessions module invokes to incrementally request input data as it is
12861 ** Each time the xInput callback is invoked by the sessions module, the first
12862 ** argument passed is a copy of the supplied pIn context pointer. The second
12866 ** before returning SQLITE_OK. If the input is completely exhausted, (*pnData)
12869 ** an error, all processing is abandoned and the streaming API function
12895 ** The xOutput callback is invoked zero or more times to return data to
12896 ** the application. The first parameter passed to each call is a copy of the
12902 ** is immediately abandoned and the streaming API function returns a copy
12995 ** The sqlite3session_config() interface is used to make global configuration
12999 ** The sqlite3session_config() interface is not threadsafe. If it is invoked
13000 ** while any other thread is inside any other sessions method then the
13001 ** results are undefined. Furthermore, if it is invoked after any sessions
13016 ** If this value is greater than 0, it is used as the new streaming data
13018 ** pointed to by pArg is set to the final value of the streaming interface
13047 ** a legal notice, here is a blessing:
13103 ** If parameter iCol is less than zero, set output variable *pnToken
13104 ** to the total number of tokens in the FTS5 table. Or, if iCol is
13109 ** If parameter iCol is greater than or equal to the number of columns
13110 ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
13111 ** an OOM condition or IO error), an appropriate SQLite error code is
13118 ** If parameter iCol is less than zero, set output variable *pnToken
13119 ** to the total number of tokens in the current row. Or, if iCol is
13123 ** If parameter iCol is greater than or equal to the number of columns
13124 ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
13125 ** an OOM condition or IO error), an appropriate SQLite error code is
13132 ** If parameter iCol is less than zero, or greater than or equal to the
13133 ** number of columns in the table, SQLITE_RANGE is returned.
13136 ** the current document. If successful, (*pz) is set to point to a buffer
13137 ** containing the text in utf-8 encoding, (*pn) is set to the size in bytes
13138 ** (not characters) of the buffer and SQLITE_OK is returned. Otherwise,
13139 ** if an error occurs, an SQLite error code is returned and the final values
13146 ** If parameter iCol is less than zero, or greater than or equal to the
13148 ** 0 is returned. Otherwise, this function returns the number of tokens in
13157 ** "detail=none" or "detail=column" option. If the FTS5 table is created
13159 ** (i.e. if it is a contentless table), then this API always returns 0.
13165 ** output by xInstCount(). If iIdx is less than zero or greater than
13166 ** or equal to the value returned by xInstCount(), SQLITE_RANGE is returned.
13168 ** Otherwise, output parameter *piPhrase is set to the phrase number, *piCol
13170 ** first token of the phrase. SQLITE_OK is returned if successful, or an
13183 ** This API function is used to query the FTS table for phrase iPhrase
13189 ** current query is executed. Any column filter that applies to
13190 ** phrase iPhrase of the current query is included in $p. For each
13192 ** is invoked. The context and API objects passed to the callback
13197 ** If parameter iPhrase is less than zero, or greater than or equal to
13202 ** query is abandoned and the xQueryPhrase function returns immediately.
13203 ** If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK.
13204 ** Otherwise, the error code is propagated upwards.
13206 ** If the query runs to completion without incident, SQLITE_OK is returned.
13207 ** Or, if some error occurs before the query completes or is aborted by
13208 ** the callback, an SQLite error code is returned.
13218 ** Each extension function is allocated a single auxiliary data slot for
13219 ** each FTS query (MATCH expression). If the extension function is invoked
13223 ** If there is already an auxiliary data pointer when this function is
13224 ** invoked, then it is replaced by the new pointer. If an xDelete callback
13225 ** was specified along with the original pointer, it is invoked at this
13228 ** The xDelete callback, if one is specified, is also invoked on the
13232 ** the auxiliary data is set to NULL and an error code returned. If the
13233 ** xDelete parameter was not NULL, it is invoked on the auxiliary data
13242 ** If the bClear argument is non-zero, then the auxiliary data is cleared
13244 ** if any, is not invoked.
13249 ** This function is used to retrieve the total number of rows in the table.
13255 ** This function is used, along with type Fts5PhraseIter and the xPhraseNext
13257 ** the current row. This is the same information as is accessible via the
13271 ** The Fts5PhraseIter structure is defined above. Applications should not
13277 ** "detail=none" or "detail=column" option. If the FTS5 table is created
13279 ** (i.e. if it is a contentless table), then this API always iterates
13287 ** and xPhraseNext() APIs described above. The difference is that instead
13302 ** "detail=none" option. If the FTS5 table is created with either
13303 ** "detail=none" "content=" option (i.e. if it is a contentless table),
13309 ** (or xInst/xInstCount). The chief advantage of this API is that it is
13317 ** This is used to access token iToken of phrase iPhrase of the current
13318 ** query. Before returning, output parameter *ppToken is set to point
13322 ** If iPhrase or iToken are less than zero, or if iPhrase is greater than
13324 ** xPhraseCount(), or if iToken is equal to or greater than the number of
13325 ** tokens in the phrase, SQLITE_RANGE is returned and *ppToken and *pnToken
13328 ** The output text is not a copy of the query text that specified the
13329 ** token. It is the output of the tokenizer module. For tokendata=1
13333 ** This is used to access token iToken of phrase hit iIdx within the
13334 ** current row. If iIdx is less than zero or greater than or equal to the
13335 ** value returned by xInstCount(), SQLITE_RANGE is returned. Otherwise,
13336 ** output variable (*ppToken) is set to point to a buffer containing the
13338 ** bytes. This API is not available if the specified token matches a
13342 ** The output text is not a copy of the document text that was tokenized.
13343 ** It is the output of the tokenizer module. For tokendata=1 tables, this
13402 ** is registered by providing fts5 with a populated instance of the
13408 ** This function is used to allocate and initialize a tokenizer instance.
13409 ** A tokenizer instance is required to actually tokenize text.
13411 ** The first argument passed to this function is a copy of the (void*)
13419 ** The final argument is an output variable. If successful, (*ppOut)
13423 ** is undefined.
13426 ** This function is invoked to delete a tokenizer handle previously
13431 ** This function is expected to tokenize the nText byte string indicated
13433 ** argument passed to this function is a pointer to an Fts5Tokenizer object
13436 ** The second argument indicates the reason that FTS5 is requesting
13437 ** tokenization of the supplied text. This is always one of the following
13440 ** <ul><li> <b>FTS5_TOKENIZE_DOCUMENT</b> - A document is being inserted into
13441 ** or removed from the FTS table. The tokenizer is being invoked to
13445 ** <li> <b>FTS5_TOKENIZE_QUERY</b> - A MATCH query is being executed
13446 ** against the FTS index. The tokenizer is being called to tokenize
13450 ** FTS5_TOKENIZE_QUERY, except that the bareword or quoted string is
13454 ** <li> <b>FTS5_TOKENIZE_AUX</b> - The tokenizer is being invoked to
13466 ** which the token is derived within the input.
13469 ** normally be set to 0. The exception is if the tokenizer supports
13472 ** FTS5 assumes the xToken() callback is invoked for each token in the
13478 ** input buffer is exhausted, xTokenize() should return SQLITE_OK. Finally,
13497 ** same token for inputs "first" and "1st". Say that token is in
13527 ** document such as "I won first place" is tokenized, entries are
13538 ** Whether it is parsing document or query text, any call to xToken that
13540 ** is considered to supply a synonym for the previous token. For example,
13552 ** It is an error to specify the FTS5_TOKEN_COLOCATED flag the first time
13553 ** xToken() is called. Multiple synonyms may be specified for a single token
13555 ** There is no limit to the number of synonyms that may be provided for a
13558 ** In many cases, method (1) above is the best approach. It does not add
13560 ** so it is efficient in terms of disk space and query speed. However, it
13562 ** token "first" is substituted for "1st" by the tokenizer, then the query:
13578 ** token "1st", but not "first" (assuming the tokenizer is not able to
13585 ** When using methods (2) or (3), it is important that the tokenizer only
13587 ** text (method (2)), not both. Doing so will not cause any errors, but is
13693 ** a legal notice, here is a blessing:
13708 ** The hard limit is the ability of a 32-bit signed integer
13716 ** This is the maximum number of
13726 ** The hard upper limit here is 32676. Most database people will
13729 ** that is the case, there is no point in having more than a few
13740 ** turn the limit off. That is no longer true. It is not possible
13748 ** The maximum depth of an expression tree. This is limited to
13751 ** expression. A value of 0 means that there is no limit.
13761 ** if the number of terms is too large. In practice, most SQL
13788 ** IMPLEMENTATION-OF: R-30185-15359 The default suggested cache size is -2000,
13789 ** which means the cache size is limited to 2048000 bytes of memory.
13807 ** and 125. The upper bound of 125 is because the attached databases are
13818 ** If the value exceeds 32767 then extra space is required for the Expr
13826 /* Maximum page size. The upper bound on this value is 65536. This a limit
13830 ** compile time. This is no longer permitted, on the grounds that it creates
13831 ** a library that is technically incompatible with an SQLite library
13855 ** Ordinarily, if no value is explicitly provided, SQLite creates databases
13858 ** SQLite may choose a larger value. This constant is the maximum value
13873 ** This is really just the default value for the max_page_count pragma.
13906 #pragma warn -ccc /* Condition is always true or false */
13907 #pragma warn -aus /* Assigned value is never used */
13945 ** The correct "ANSI" way to do this is to use the intptr_t type.
13946 ** Unfortunately, that typedef is not available on all compilers, or
13947 ** if it is available, it requires an #include of specific headers
14009 ** SEH support if the -DSQLITE_OMIT_SEH option is given.
14032 ** 0 means mutexes are permanently disable and the library is never
14033 ** threadsafe. 1 means the library is serialized which is the highest
14034 ** level of threadsafety. 2 means the library is multithreaded - multiple
14041 ** To ensure that the correct value of "THREADSAFE" is reported when querying
14043 ** logic is partially replicated in ctime.c. If it is updated here, it should
14055 ** Powersafe overwrite is on by default. But can be turned off using
14064 ** default unless SQLite is compiled with SQLITE_DEFAULT_MEMSTATUS=0 in
14080 ** On Windows, if the SQLITE_WIN32_MALLOC_VALIDATE macro is defined and the
14081 ** assert() macro is enabled, each call into the Win32 native heap subsystem
14093 are defined but at most one is allowed:\
14105 ** If SQLITE_MALLOC_SOFT_LIMIT is not zero, then try to keep the
14124 ** defined(NDEBUG)==!defined(SQLITE_DEBUG). If this is not currently true,
14130 ** is set. Thus NDEBUG becomes an opt-in rather than an opt-out
14141 ** Enable SQLITE_ENABLE_EXPLAIN_COMMENTS if SQLITE_DEBUG is turned on.
14148 ** The testcase() macro is used to aid in coverage testing. When
14151 ** get full branch coverage. The testcase() macro is inserted
14153 ** condition/decision coverage is inadequate. For example, testcase()
14156 ** is significant and used at least once. On switch statements
14170 ** The TESTONLY macro is used to enclose variable declarations or
14183 ** appear when assert() is disabled. The following macro is therefore
14231 ** the correct answer is still obtained, though perhaps not as quickly.
14244 ** Some malloc failures are only possible if SQLITE_TEST_REALLOC_STRESS is
14248 ** that are always false except when SQLITE_TEST_REALLOC_STRESS is set.
14273 ** it is needed by "mutex_w32.c" (when debugging), "os_win.c" (when
14274 ** OSTRACE is enabled), and by several "test*.c" files (which are
14285 ** SQLITE_ENABLE_EXPLAIN_COMMENTS is incompatible with SQLITE_OMIT_EXPLAIN
14299 ** Return true (non-zero) if the input is an integer that is too large
14300 ** to fit in 32-bits. This macro is used inside of various testcase()
14306 ** The macro unlikely() is a hint that surrounds a boolean
14307 ** expression that is usually false. Macro likely() surrounds
14308 ** a boolean expression that is usually true. These hints could,
14321 ** a legal notice, here is a blessing:
14328 ** This is the header file for the generic hash-table implementation
14338 /* A complete hash table is an instance of the following structure.
14353 ** Hash.htsize and Hash.ht may be zero. In that case lookup is done
14355 ** Hash.ht table is never allocated because if there are few elements
14356 ** in the table, it is faster to do a linear search than to manage
14369 /* Each element in the hash table is an instance of the following
14372 ** Again, this structure is intended to be opaque, but it can't really
14373 ** be opaque because it is used by macros.
14390 ** Macros for looping over all elements of a hash table. The idiom is
14613 ** This allows better measurements of where memcpy() is used when running
14614 ** cachegrind. But this macro version of memcpy() is very slow so it
14615 ** should not be used in production. This is a performance measurement
14644 ** OMIT_TEMPDB is set to 1 if SQLITE_OMIT_TEMPDB is defined, or 0
14655 ** The "file format" number is an integer that is incremented whenever
14674 ** Provide a default value for SQLITE_TEMP_STORE in case it is not specified
14683 ** SQLITE_TEMP_STORE is set to 3 (never use temporary files), set it
14703 ** pagecaches for each database connection. A positive number is the
14705 ** of -1024*N bytes is allocated and used for as many pages as it will hold.
14817 ** SQLITE_MAX_U32 is a u64 constant that is the maximum u64 value
14819 ** is 0x00000000ffffffff. But because of quirks of some compilers, we
14832 ** logarithms. For quantity X, the value stored is 10*log2(X). This
14834 ** But the allowed values are "grainy". Not every value is representable.
14837 ** not exact values, this imprecision is not a problem.
14839 ** "LogEst" is short for "Logarithmic Estimate".
14871 /* The uptr type is an unsigned integer large enough to hold a pointer
14885 ** In other words, S is a buffer and E is a pointer to the first byte after
14892 ** P is one byte past the end of a large buffer. Return true if a span of bytes
14894 ** if the sub-buffer S..E-1 overflows the buffer whose last byte is P-1.
14896 ** S is the start of the span. E is one byte past the end of end of span.
14916 ** Macros to determine whether the machine is big or little endian,
14917 ** and whether or not that determination is run-time or compile-time.
14919 ** For best performance, an attempt is made to guess at the byte-order
14920 ** using C-preprocessor macros. If that is unsuccessful, or if
14921 ** -DSQLITE_BYTEORDER=0 is set, then byte-order is determined
14983 ** Round up a number to the next larger multiple of 8. This is used
14988 ** ROUND8P() assumes that the argument is already an integer number of
14989 ** pointers in size, and so it is a no-op on systems where the pointer
14990 ** size is 8.
15005 ** Assert that the pointer X is aligned to an 8-byte boundary. This
15006 ** macro is used only within assert() to verify that the code gets
15009 ** Except, if SQLITE_4_BYTE_ALIGNED_MALLOC is defined, then the
15020 ** Disable MMAP on platforms where it is known to not work
15047 ** The default MMAP_SIZE is zero on all platforms. Or, even if a larger
15048 ** default MMAP_SIZE is specified at compile-time, make sure that it does
15061 ** the Abstract Syntax Tree tracing logic is turned on.
15146 ** An instance of the following structure is used to store the busy-handler
15151 ** handle is passed a pointer to sqlite.busyHandler. The busy-handler
15152 ** callback is currently invoked only from within pager.c.
15164 ** The PREFERRED names are used wherever possible. But LEGACY is also
15190 ** The name of the schema table. The name is different for TEMP.
15202 ** Determine if the argument is a power of two
15211 ** pointer will work here as long as it is distinct from SQLITE_STATIC
15217 ** When SQLITE_OMIT_WSD is defined, it means that the target platform does
15220 ** the heap. When WSD is unsupported, the variable declarations scattered
15222 ** macro is used for this purpose. And instead of referencing the variable
15224 ** buffer that holds real variable. The constant is also the initializer
15227 ** In the usual case where WSD is supported, the SQLITE_WSD and GLOBAL
15244 ** make it clear to human readers when a function parameter is deliberately
15246 ** a function is called via a function pointer. For example the
15249 ** if it knows that this is enforced elsewhere.
15251 ** When a function parameter is not used at all within the body of a function,
15252 ** it is generally named "NotUsed" or "NotUsed2" to make things even clearer.
15327 ** The bitmask datatype defined below is used for various optimizations.
15357 ** on the sqlite3VListAdd() routine for more information. A VList is really
15373 ** a legal notice, here is a blessing:
15381 ** This header file (together with is companion C source-code file
15385 ** This header file is #include-ed by sqliteInt.h and thus ends up
15401 ** a legal notice, here is a blessing:
15430 ** If SQLITE_OS_OTHER=1 is specified at compile-time, then the application
15492 /* If the SET_FULLSYNC macro is not defined above, then make it
15523 ** If sqlite is being embedded in another program, you may wish to change the
15534 ** For this reason, the default name prefix is changed to be "sqlite"
15536 ** anybody smart enough to figure out the code is also likely smart
15575 ** A SHARED_LOCK is obtained by locking a single randomly-chosen
15576 ** byte out of a specific range of bytes. The lock byte is obtained at
15579 ** An EXCLUSIVE_LOCK is obtained by locking all bytes in the range.
15580 ** There can only be one writer. A RESERVED_LOCK is obtained by locking
15581 ** a single byte of the file that is designated as the reserved lock byte.
15582 ** A PENDING_LOCK is obtained by locking a designated byte different from
15587 ** are used, the lock is placed on the same range of bytes that is used
15594 ** SHARED_SIZE is the number of bytes available in the pool from which
15595 ** a random byte is selected for a shared lock. The pool of bytes for
15602 ** tool is being used for file sharing) implements locks correctly between
15606 ** Locking in windows is manditory. For this reason, we cannot store
15608 ** the pages involved in locking therefore. SHARED_SIZE is selected so
15611 ** is set high so that we don't have to allocate an unused page except
15616 ** file format. Depending on how it is changed, you might not notice
15618 ** The default location of PENDING_BYTE is the first byte past the
15698 ** a legal notice, here is a blessing:
15724 ** is called page 1. 0 is used to represent "not a page".
15729 ** Each open file is managed by a separate instance of the "Pager" structure.
15739 ** Page number PAGER_SJ_PGNO is never used in an SQLite database (it is
15740 ** reserved for working around a windows/posix incompatibility). It is
15742 ** is devoted to storing a super-journal name - there are no more pages to
15783 #define PAGER_GET_READONLY 0x02 /* Read-only page is acceptable */
15950 ** a legal notice, here is a blessing:
15964 /* TODO: This definition is just included so other modules compile. It
15970 ** If defined as non-zero, auto-vacuum is enabled by default. Otherwise
16006 #define BTREE_MEMORY 2 /* This is an in-memory DB */
16008 #define BTREE_UNORDERED 8 /* Use of a hash implementation is OK */
16061 ** With BTREE_INTKEY, the table key is a 64-bit integer and arbitrary data
16062 ** is stored in the leaves. (BTREE_INTKEY is used for SQL tables.) With
16063 ** BTREE_BLOBKEY, the key is an arbitrary BLOB and no content is stored
16064 ** anywhere - the key is the content. (BTREE_BLOBKEY is used for SQL
16088 ** For example, the free-page-count field is located at byte offset 36 of
16089 ** the database file header. The incr-vacuum-flag field is located at
16092 ** The BTREE_DATA_VERSION value is not really a value stored in the header.
16093 ** It is a read-only number computed by the pager. But we merge it with
16094 ** the header value access routines since its access pattern is the same.
16114 ** The first argument is an Expr* (which is guaranteed to be constant for
16119 ** then the value of the node is the value in Mem[pExpr.iTable]. Any
16125 ** The design of the _RANGE hint is aid b-tree implementations that try
16130 ** Note that BTREE_HINT_FLAGS with BTREE_BULKLOAD is the only hint used by
16141 ** The BTREE_BULKLOAD flag is set on index cursors when the index is going
16142 ** to be filled with content that is already in sorted order.
16144 ** The BTREE_SEEK_EQ flag is set on cursors that will get OP_SeekGE or
16156 ** For read-only cursors the wrFlag argument is always zero. For read-write
16158 ** (BTREE_WRCSR). If the BTREE_FORDELETE bit is set, then the cursor will
16166 ** The BTREE_FORDELETE flag is an optimization hint. It is not used by
16167 ** by this, the native b-tree engine of SQLite, but it is available to
16177 #define BTREE_FORDELETE 0x00000008 /* Cursor is for seek/delete only */
16213 #define BTREE_APPEND 0x08 /* Insert is likely an append */
16214 #define BTREE_PREFORMAT 0x80 /* Inserted data is a preformated cell */
16223 ** The nMem field might be zero, indicating that no decomposition is available.
16226 ** the key and passed in the nKey field. The pKey field is zero.
16243 ** This object is used to pass information into sqlite3BtreeInsert(). The
16276 sqlite3 *db, /* Database connection that is running the check */
16325 ** If we are not using shared cache, then there is no need to
16375 ** a legal notice, here is a blessing:
16393 ** A single VDBE is an opaque structure named "Vdbe". Only routines
16408 ** and as many as three operands. The instruction is recorded
16414 u16 p5; /* Fifth parameter is an unsigned 16-bit integer */
16422 i64 *pI64; /* Used when p4type is P4_INT64 */
16423 double *pReal; /* Used when p4type is P4_REAL */
16424 FuncDef *pFunc; /* Used when p4type is P4_FUNCDEF */
16425 sqlite3_context *pCtx; /* Used when p4type is P4_FUNCCTX */
16426 CollSeq *pColl; /* Used when p4type is P4_COLLSEQ */
16427 Mem *pMem; /* Used when p4type is P4_MEM */
16428 VTable *pVtab; /* Used when p4type is P4_VTAB */
16429 KeyInfo *pKeyInfo; /* Used when p4type is P4_KEYINFO */
16430 u32 *ai; /* Used when p4type is P4_INTARRAY */
16431 SubProgram *pProgram; /* Used when p4type is P4_SUBPROGRAM */
16432 Table *pTab; /* Used when p4type is P4_TABLE */
16434 Expr *pExpr; /* Used when p4type is P4_EXPR */
16480 #define P4_NOTUSED 0 /* The P4 parameter is not used */
16481 #define P4_TRANSIENT 0 /* P4 is a pointer to a transient string */
16483 #define P4_COLLSEQ (-2) /* P4 is a pointer to a CollSeq structure */
16484 #define P4_INT32 (-3) /* P4 is a 32-bit signed integer */
16485 #define P4_SUBPROGRAM (-4) /* P4 is a pointer to a SubProgram structure */
16486 #define P4_TABLE (-5) /* P4 is a pointer to a Table structure */
16490 #define P4_FUNCDEF (-7) /* P4 is a pointer to a FuncDef structure */
16491 #define P4_KEYINFO (-8) /* P4 is a pointer to a KeyInfo structure */
16492 #define P4_EXPR (-9) /* P4 is a pointer to an Expr tree */
16493 #define P4_MEM (-10) /* P4 is a pointer to a Mem* structure */
16494 #define P4_VTAB (-11) /* P4 is a pointer to an sqlite3_vtab structure */
16495 #define P4_REAL (-12) /* P4 is a 64-bit floating point value */
16496 #define P4_INT64 (-13) /* P4 is a 64-bit signed integer */
16497 #define P4_INTARRAY (-14) /* P4 is a vector of 32-bit integers */
16498 #define P4_FUNCCTX (-15) /* P4 is a pointer to an sqlite3_context object */
16508 ** The Vdbe.aColName array contains 5n Mem structures, where n is the
16737 #define OPFLG_IN1 0x02 /* in1: P1 is an input */
16738 #define OPFLG_IN2 0x04 /* in2: P2 is an input */
16739 #define OPFLG_IN3 0x08 /* in3: P3 is an input */
16740 #define OPFLG_OUT2 0x10 /* out2: P2 is an output */
16741 #define OPFLG_OUT3 0x20 /* out3: P3 is an output */
16769 /* The resolve3P2Values() routine is able to run faster if it knows
16951 ** VdbeCoverageAlwaysTaken(v) // Previous branch is always taken
16953 ** VdbeCoverageNeverTaken(v) // Previous branch is never taken
16955 ** VdbeCoverageNeverNull(v) // Previous three-way branch is only
16957 ** // NULL option is not possible
16959 ** VdbeCoverageEqNe(v) // Previous OP_Jump is only interested
16963 ** If not, then when "make test" is run with -DSQLITE_VDBE_COVERAGE and
16969 ** routine that is invoked as each bytecode branch is taken. The callback
16972 ** is responsible for keeping track of this and reporting byte-code branches
17032 ** a legal notice, here is a blessing:
17049 ** Every page in the cache is controlled by an instance of the following
17058 Pager *pPager; /* The pager this page is part of */
17068 ** pCache is grouped with the public elements for efficiency.
17074 ** PgHdr object is not dirty */
17079 #define PGHDR_DIRTY 0x002 /* Page is on the PCache.pDirty list */
17084 #define PGHDR_MMAP 0x020 /* This is an mmap page object */
17118 /* One release per successful fetch. Page is pinned until released.
17127 SQLITE_PRIVATE void sqlite3PcacheMakeDirty(PgHdr*); /* Make sure page is marked dirty */
17163 ** interface is only available if SQLITE_CHECK_PAGES is defined when the
17164 ** library is built.
17176 ** If no global maximum is configured, then the system attempts to limit
17187 ** The spill-size is the minimum number of pages in cache before the cache
17227 ** a legal notice, here is a blessing:
17236 ** The sqliteInt.h header #includes this file so that it is available
17254 ** mutual exclusion is provided. But this
17277 ** If this is a no-op implementation, implement everything as macros.
17299 ** synchronous setting to EXTRA. It is no longer supported.
17330 ** Each database file to be accessed by the system is an instance
17332 ** in the sqlite.aDb[] array. aDb[0] is the main database file and
17333 ** aDb[1] is the database file used to hold temporary tables. Additional
17347 ** Most Schema objects are associated with a Btree. The exception is
17348 ** the Schema for the TEMP database (sqlite3.aDb[1]) which is free-standing.
17353 ** references them is destroyed. The TEMP Schema is manually freed by
17359 ** For a TEMP Schema, only the connection mutex is required.
17387 ** The DB_SchemaLoaded flag is set after the database schema has been
17405 ** Lookaside malloc is a set of fixed-size buffers that can be used
17414 ** the lookaside subsystem is stored on a linked list of LookasideSlot
17420 ** is shared by multiple database connections. Therefore, while parsing
17421 ** schema information, the Lookaside.bEnabled flag is cleared so that
17425 ** bDisable is greater than zero, sz is set to zero which effectively
17438 ** The default lookaside configuration is 100 slots of 1200 bytes each.
17536 /* This is an extra SQLITE_TRACE macro that indicates "legacy" tracing
17548 ** Maximum number of sqlite3.aDb[] entries. This is the number of attached
17554 ** Each database connection is an instance of the following structure.
17583 u8 isTransactionSavepoint; /* True if the outermost savepoint is a TS */
17595 u8 iDb; /* Which db file is being initialized */
17597 unsigned orphanTrigger : 1; /* Last statement is orphaned TEMP trigger */
17599 unsigned reopenMemdb : 1; /* ATTACH is really a reopen using MemDB */
17681 ** When X.pUnlockConnection==Y, that means that X is waiting for Y to
17730 /* result set is empty */
17750 #define SQLITE_Defensive 0x10000000 /* Input SQL is likely hostile */
17778 #define DBFLAG_SchemaKnownOk 0x0010 /* Schema is known to be valid */
17828 ** code. The argument is a Parse object for the code generator.
17836 #define SQLITE_STATE_OPEN 0x76 /* Database is open */
17837 #define SQLITE_STATE_CLOSED 0xce /* Database is closed */
17844 ** Each SQL function is defined by an instance of the following
17846 ** a pointer to this structure is held in the sqlite3BuiltinFunctions object.
17848 ** structure is held in the db->aHash hash table.
17850 ** The u.pHash field is used by the global built-ins. The u.pDestructor
17851 ** field is used by per-connection app-def functions.
17872 ** create_function_v2() is called to create a function with a destructor,
17873 ** a single object of this type is allocated. FuncDestructor.nRef is set to
17875 ** or not the specified encoding is SQLITE_ANY). The FuncDef.pDestructor
17876 ** member of each of the new FuncDef objects is set to point to the allocated
17879 ** Thereafter, when one of the FuncDef objects is deleted, the reference
17880 ** count on this object is decremented. When it reaches 0, the destructor
17881 ** is invoked and the FuncDestructor structure freed.
17907 ** same bit value, their meanings are inverted. SQLITE_FUNC_UNSAFE is
17909 ** SQLITE_INNOCUOUS is used by application code and means "not unsafe".
17935 #define SQLITE_FUNC_BUILTIN 0x00800000 /* This is a built-in function */
17956 ** value passed as iArg is cast to a (void*) and made available
17958 ** argument bNC is true, then the SQLITE_FUNC_NEEDCOLL flag is set.
17968 ** zName is the name of a function that is implemented by in-line
17970 ** parameter determines the function id. The mFlags parameter is
17974 ** zName is the name of a test-only function implemented by in-line
17976 ** parameter determines the function id. The mFlags parameter is
17983 ** a single query. The iArg is ignored. The user-data is always set
17984 ** to a NULL pointer. The bNC parameter is not used.
17987 ** For math-library functions. xPtr is an arbitrary pointer.
17990 ** Used for "pure" date/time functions, this macro is like DFUNCTION
17991 ** except that it does set the SQLITE_FUNC_CONSTANT flags. iArg is
17992 ** ignored and the user-data for these functions is set to an
17993 ** arbitrary non-NULL pointer. The bNC parameter is not used.
18009 ** that accepts nArg arguments and is implemented by a call to C
18010 ** function likeFunc. Argument pArg is cast to a (void *) and made
18012 ** FuncDef.flags variable is set to the value passed as the flags
18071 ** sqlite3.pSavepoint. The first element in the list is the most recently
18092 ** Each SQLite module (virtual table definition) is defined by an
18106 ** Information about each column of an SQL table is held in an instance
18111 ** "table column index" This is the index of the column in the
18115 ** "storage column index" This is the index of the column in the
18117 ** opcode. The storage column index is less than
18118 ** or equal to the table column index. It is
18125 ** a single allocation. Each string is 0x00 terminated. The datatype
18126 ** is only included if the COLFLAG_HASTYPE bit of colFlags is set and the
18127 ** collating sequence name is only included if the COLFLAG_HASCOLL bit is
18144 ** sqlite3StdTypeLen[] and sqlite3StdType[]. Each value is one more
18164 #define COLFLAG_PRIMKEY 0x0001 /* Column is part of the primary key */
18179 ** A "Collating Sequence" is defined by an instance of the following
18183 ** If CollSeq.xCmp is NULL, it means that the
18184 ** collating sequence is undefined. Indices built on an undefined
18214 ** for a numeric type is a single comparison. And the BLOB type is first.
18236 ** The SQLITE_NOTNULL flag is a combination of NULLEQ and JUMPIFNULL.
18238 ** operator is NULL. It is added to certain comparison operators to
18241 #define SQLITE_JUMPIFNULL 0x10 /* jumps if either operand is NULL */
18246 ** An object of this type is created for each virtual table present in
18249 ** If the database schema is shared, then there is one instance of this
18251 ** schema. This is because each database connection requires its own unique
18255 ** schema is shared, as the implementation often stores the database
18266 ** When an sqlite3_prepare() operation is required to access the virtual
18271 ** When an in-memory Table object is deleted (for example when the
18272 ** schema is being reloaded for some reason), the VTable objects are not
18277 ** next time a statement is prepared using said sqlite3*. This is done
18280 ** explanation as to why it is safe to add an entry to an sqlite3.pDisconnect
18283 ** The memory for objects of this type is always allocated by
18306 ** The schema for each SQL table, virtual table, and view is represented
18354 ** vtab1(a HIDDEN, b);". Since "b" is a non-hidden column but "a" is hidden,
18367 #define TF_Autoincrement 0x00000008 /* Integer primary key is autoincrement */
18372 #define TF_WithoutRowid 0x00000080 /* No rowid. PRIMARY KEY is the key */
18395 ** Test to see whether or not a table is a virtual table. This is
18397 ** table support is omitted from the build.
18409 ** Macros to determine if a column is hidden. IsOrdinaryHiddenColumn()
18410 ** only works for non-virtual tables (ordinary tables and views) and is
18411 ** always false unless SQLITE_ENABLE_HIDDEN_COLUMNS is defined. The
18412 ** IsHiddenColumn() macro is general purpose.
18431 ** Each foreign key constraint is an instance of the following structure.
18433 ** A foreign key is associated with two tables. The "from" table is
18435 ** key. The "to" table is the table that is named in the REFERENCES clause.
18443 ** For foreign key "fk1", the from-table is "ex1" and the to-table is "ex2".
18450 ** which is attached to the from-table. The to-table need not exist when
18451 ** the from-table is created. The existence of the to-table is not checked.
18453 ** The list of all parents for child Table X is held at X.pFKey.
18456 ** is held in Schema.fkeyHash with a hash key of Z.
18466 u8 isDeferred; /* True if constraint checking is deferred till COMMIT */
18481 ** but the transaction is not rolled back. FAIL processing means that
18485 ** error is not inserted or updated. Processing continues and no error
18486 ** is returned. REPLACE means that preexisting database rows that caused
18488 ** update can proceed. Processing continues and no error is reported.
18490 ** is omitted and the DO UPDATE clause of an upsert is run instead.
18493 ** RESTRICT is the same as ABORT for IMMEDIATE foreign keys and the
18495 ** key is set to NULL. SETDFLT means that the foreign key is set
18497 ** referenced table row is propagated into the row that holds the
18500 ** The OE_Default value is a place holder that means to use whatever
18501 ** conflict resolution algorithm is required from context.
18506 #define OE_None 0 /* There is no constraint to check */
18517 #define OE_Default 11 /* Do whatever the default action is */
18521 ** An instance of the following structure is passed as the first
18522 ** argument to sqlite3VdbeKeyCompare and is used to control the
18543 #define KEYINFO_ORDER_BIGNULL 0x02 /* NULL is larger than any other value */
18549 ** A record is an object that contains one or more fields of data.
18551 ** the key of an index. A blob encoding of a record is created by
18552 ** the OP_MakeRecord opcode of the VDBE and is disassembled by the
18556 ** an index b+tree. The goal of the search is to find the entry that
18557 ** is closed to the key described by this object. This object might hold
18558 ** just a prefix of the key. The number of fields is given by
18561 ** The r1 and r2 fields are the values to return if this key is less than
18564 ** is in DESC order.
18598 ** Each SQL index is represented in memory by an
18611 ** The value of aiColumn is {2, 0}. aiColumn[0]==2 because the
18618 ** it means this is not a unique index. Otherwise it is a unique index
18620 ** algorithm to employ when an attempt is made to insert a non-unique
18623 ** The colNotIdxed bitmask is used in combination with SrcItem.colUsed
18626 ** is *not* available in the index. Thus the expression
18627 ** "colUsed & colNotIdxed" will be non-zero if the index is not a
18630 ** table is used, the "colUsed & colNotIdxed" test will always be non-zero
18631 ** and we have to assume either that the index is not covering, or use
18633 ** the index is covering.
18638 ** of this structure may be created. In this case the Index.tnum variable is
18640 ** number (it cannot - the database page is not allocated until the VDBE
18641 ** program is executed). See convertToWithoutRowidTable() for details.
18645 i16 *aiColumn; /* Which columns are used by this index. 1st is 0 */
18664 unsigned isCovering:1; /* True if this is a covering index */
18667 unsigned bLowQual:1; /* sqlite_stat1 says this is a low-quality index */
18693 /* Return true if index X is a PRIMARY KEY index */
18696 /* Return true if index X is a UNIQUE index */
18702 #define XN_ROWID (-1) /* Indexed column is the rowid */
18703 #define XN_EXPR (-2) /* Indexed column is an expression */
18706 ** Each sample stored in the sqlite_stat4 table is represented in memory
18714 tRowcnt *anLt; /* Est. number of rows where key is less than this sample */
18721 #define SQLITE_TOKEN_QUOTED 0x1 /* Token is a quoted identifier. */
18722 #define SQLITE_TOKEN_KEYWORD 0x2 /* Token is a keyword. */
18725 ** Each token coming out of the lexer is an instance of
18728 ** The memory that "z" points to is owned by other objects. Take care
18743 ** If Expr.op==TK_AGG_COLUMN or TK_AGG_FUNCTION then Expr.pAggInfo is a
18744 ** pointer to this structure. The Expr.iAgg field is the index in
18802 ** The datatype ynVar is a signed integer, either 16-bit or 32-bit.
18803 ** Usually it is 16-bits. But if SQLITE_MAX_VARIABLE_NUMBER is greater
18804 ** than 32767 we have to make it 32-bit. 16-bit is preferred because
18805 ** it uses less memory in the Expr object, which is a big memory user
18809 ** the option is available (at compile-time).
18818 ** Each node of an expression in the parse tree is an instance
18821 ** Expr.op is the opcode. The integer parser token codes are reused
18823 ** code representing the ">=" operator. This same integer code is reused
18827 ** If the expression is an SQL literal (TK_INTEGER, TK_FLOAT, TK_BLOB,
18829 ** the expression is a variable (TK_VARIABLE), then Expr.u.zToken contains the
18830 ** variable name. Finally, if the expression is an SQL function (TK_FUNCTION),
18836 ** Expr.x.pList is a list of arguments if the expression is an SQL function,
18838 ** Expr.x.pSelect is used if the expression is a sub-select or an expression of
18839 ** the form "<lhs> IN (SELECT ...)". If the EP_xIsSelect bit is set in the
18840 ** Expr.flags mask, then Expr.x.pSelect is valid. Otherwise, Expr.x.pList is
18844 ** For such expressions, Expr.op is set to TK_COLUMN and Expr.iTable is
18846 ** Expr.iColumn is the column number for the specific column. If the
18847 ** expression is used as a result in an aggregate SELECT, then the
18848 ** value is also stored in the Expr.iAgg column in the aggregate so that
18851 ** If the expression is an unbound variable marker (a question mark
18855 ** If the expression is a subquery then Expr.iColumn holds an integer
18857 ** subquery gives a constant result, then iTable is -1. If the subquery
18859 ** then iTable is the address of a subroutine that computes the subquery.
18861 ** If the Expr is of type OP_Column, and the table it is selecting from
18862 ** is a disk table or the "old.*" pseudo-table, then pTab points to the
18874 ** an Expr object is truncated. When EP_Reduced is set, then all
18878 ** allocated, regardless of whether or not EP_Reduced is set.
18896 /* If the EP_TokenOnly flag is set in the Expr.flags mask, then no
18897 ** space is allocated for the fields below this point. An attempt to
18908 /* If the EP_Reduced flag is set in the Expr.flags mask, then no
18909 ** space is allocated for the fields below this point. An attempt to
18955 #define EP_VarSelect 0x000040 /* pSelect is correlated, not constant */
18961 #define EP_xIsSelect 0x001000 /* x.pSelect is valid (otherwise x.pList is) */
18982 /* The EP_Propagate mask is a set of properties that automatically propagate
19016 /* The ExprSetVVAProperty() macro is used for Verification, Validation,
19018 ** processes but is a no-op for delivery.
19063 ** field is not used.
19066 ** is used for multiple purposes:
19088 unsigned done :1; /* Indicates when processing is finished */
19089 unsigned reusable :1; /* Constant expression is reusable */
19094 unsigned bNoExpand: 1; /* Term is an auxiliary in NestedFrom and should
19102 int iConstExprReg; /* Register in which Expr value is cached. Used only
19124 ** The IdList.a.idx field is used when the IdList represents the list of
19129 ** If "a" is the k-th column of table "t", then IdList.a[0].idx==k.
19133 u8 eU4; /* Which element of a.u4 is valid */
19145 ** is valid.
19153 ** The SrcList object is mostly an array of SrcItems.
19160 ** In the colUsed field, the high-order bit (bit 63) is set if the table
19161 ** contains more than 63 columns and the 64-th or later column is used.
19171 Schema *pSchema; /* Schema to which this item is fixed */
19174 char *zAlias; /* The "B" part of a "A AS B" phrase. zName is the "A" */
19182 unsigned notIndexed :1; /* True if there is a NOT INDEXED clause */
19183 unsigned isIndexedBy :1; /* True if there is an INDEXED BY clause */
19185 unsigned isCorrelated :1; /* True if sub-query is correlated */
19186 unsigned isMaterialized:1; /* This is a materialized view */
19190 unsigned isCte :1; /* This is a CTE */
19192 unsigned isUsing :1; /* u3.pUsing is valid */
19194 unsigned isSynthUsing :1; /* u3.pUsing is synthesized from NATURAL */
19195 unsigned isNestedFrom :1; /* pSelect is a SF_NestedFrom subquery */
19209 CteUse *pCteUse; /* CTE Usage info when fg.isCte is true */
19225 ** is used to hold the FROM clause of a SELECT statement. SrcList also
19243 #define JT_OUTER 0x20 /* The "OUTER" keyword is present */
19259 #define WHERE_ONEPASS_MULTIROW 0x0008 /* ONEPASS is ok with multiple rows */
19263 #define WHERE_GROUPBY 0x0040 /* pOrderBy is really a GROUP BY */
19264 #define WHERE_DISTINCTBY 0x0080 /* pOrderby is really a DISTINCT clause */
19267 #define WHERE_AGG_DISTINCT 0x0400 /* Query is "SELECT agg(DISTINCT ...)" */
19287 ** pEList corresponds to the result set of a SELECT and is NULL for
19291 ** context is searched first. If no match is found, the next outer
19292 ** context is checked. If there is still no match, the next context
19293 ** is checked. This process continues until either a match is found
19294 ** or all contexts are check. When a match is found, the nRef member of
19295 ** the context containing the match is incremented.
19337 #define NC_UEList 0x000080 /* True if uNC.pEList is used */
19338 #define NC_UAggInfo 0x000100 /* True if uNC.pAggInfo is used */
19339 #define NC_UUpsert 0x000200 /* True if uNC.pUpsert is used */
19340 #define NC_UBaseReg 0x000400 /* True if uNC.iBaseReg is used */
19355 ** The pUpsertTarget field is only set if the ON CONFLICT clause includes
19356 ** conflict-target clause. (In "ON CONFLICT(a,b)" the "(a,b)" is the
19357 ** conflict-target clause.) The pUpsertTargetWhere is the optional
19360 ** pUpsertSet is the list of column=expr terms of the UPDATE statement.
19361 ** The pUpsertSet field is NULL for a ON CONFLICT DO NOTHING. The
19362 ** pUpsertWhere is the WHERE clause for the UPDATE and is NULL if the
19363 ** WHERE clause is omitted.
19372 /* Above this point is the parse tree for the ON CONFLICT clauses.
19376 ** when the Upsert is destroyed. The fields below are used to transfer
19398 ** as the OP_OpenEphm instruction is coded because not
19399 ** enough information about the compound query is known at that point.
19458 #define SF_View 0x0200000 /* SELECT statement is a view */
19459 #define SF_NoopOrderBy 0x0400000 /* ORDER BY is ignored for this query */
19463 #define SF_CopyCte 0x4000000 /* SELECT statement is a copy of a CTE */
19481 ** set is not empty.
19483 ** SRT_Discard Throw the results away. This is used by SELECT
19484 ** statements within triggers whose only purpose is
19490 ** SRT_Mem Only valid if the result is a single column.
19501 ** the result there. The cursor is left open after
19502 ** returning. This is like SRT_Table except that
19507 ** results each time it is invoked. The entry point
19508 ** of the co-routine is stored in register pDest->iSDParm
19509 ** and the result row is stored in pDest->nDest registers
19513 ** SRT_Fifo This is like SRT_EphemTab except that the table
19514 ** is assumed to already be open. SRT_Fifo has
19533 ** table is an intkey table - in this case the first
19534 ** column returned by the SELECT is used as the integer
19535 ** key. If (pDest->iSDParm>0), then the table is an index
19536 ** table. (pDest->iSDParm) is the number of key columns in
19541 #define SRT_Exists 3 /* Store 1 if the result is not empty */
19546 /* The DISTINCT clause is ignored for all of the above. Not that
19553 /* The ORDER BY clause is ignored for all of the above */
19580 ** tables, the following information is attached to the Table.u.autoInc.p
19595 ** At least one instance of the following structure is created for each
19603 ** TriggerPrg.orconf, is stored in the TriggerPrg.pProgram variable.
19607 ** The TriggerPrg.aColmask[0] variable is set to a mask of old.* columns
19609 ** statements). Similarly, the TriggerPrg.aColmask[1] variable is set to
19641 ** or the name of a virtual generated column, and if X is in scope such that
19643 ** there is an instance of this object on the Parse.pIdxExpr list.
19646 ** this list is consulted and if a matching expression is found, the value
19647 ** is read from the index rather than being recomputed.
19674 ** An SQL parser context. A copy of this structure is passed through
19676 ** carry around information that is global to the entire parse.
19678 ** The structure is divided into two parts. When the parser and code
19680 ** is constant but the second part is reset at the beginning and end of
19684 ** feature is enabled (if sqlite3Tsd()->useSharedData is true). They are
19686 ** compiled. Function sqlite3TableLock() is used to add entries to the
19759 ** initialized as they will be set before being used. The boundary is
19768 ** Above is constant between recursions. Below is reset before and after
19769 ** each recursion. The boundary between these two regions is determined
19777 u8 explain; /* True if the EXPLAIN flag is found on the query */
19866 #define OPFLAG_EPHEM 0x01 /* OP_Column: Ephemeral output is ok */
19868 #define OPFLAG_ISUPDATE 0x04 /* This OP_Insert is an sql UPDATE */
19869 #define OPFLAG_APPEND 0x08 /* This is likely to be an append */
19878 #define OPFLAG_P2ISREG 0x10 /* P2 to OP_Open** is a register number */
19882 #define OPFLAG_NOCHNG_MAGIC 0x6d /* OP_MakeRecord: serialtype 10 is ok */
19886 ** Each trigger present in the database schema is stored as an instance of
19894 ** linked list is stored as the "pTrigger" member of the associated
19907 IdList *pColumns; /* If this is an UPDATE OF <column-list> trigger,
19908 the <column-list> is stored here */
19916 ** A trigger is either a BEFORE or an AFTER trigger. The following constants
19926 ** An instance of struct TriggerStep is used to store a single SQL statement
19927 ** that is a part of a trigger-program.
19931 ** associated struct Trigger instance. The first element of the linked list is
19934 ** The "op" member indicates whether this is a "DELETE", "INSERT", "UPDATE" or
19935 ** "SELECT" statement. The meanings of the other members is determined by the
19943 ** pIdList -> If this is an INSERT INTO ... (<column-names>) VALUES ...
19950 ** pWhere -> The WHERE clause of the DELETE statement if one is specified.
19955 ** pWhere -> The WHERE clause of the UPDATE statement if one is specified.
19972 Trigger *pTrig; /* The trigger that this step is a part of */
20014 #define SQLITE_PRINTF_MALLOCED 0x04 /* True if xText is allocated space */
20019 ** The following object is the header for an "RCStr" or "reference-counted
20020 ** string". An RCStr is passed around and used like any other char*
20033 ** "String" is in the name, but an RCStr object can also be used to hold
20042 ** A pointer to this structure is used to communicate information
20097 int neverCorrupt; /* Database is always well-formed */
20120 int isMallocInit; /* True after malloc is initialized */
20121 int isPCacheInit; /* True after malloc is initialized */
20131 /* The following callback (if not NULL) is invoked on every VDBE branch
20155 ** This macro is used inside of assert() statements to indicate that
20156 ** the assert is only valid on a well-formed database. Instead of:
20164 ** CORRUPT_DB is true during normal operation. CORRUPT_DB does not indicate
20165 ** that the database is definitely corrupt, only that it might be corrupt.
20166 ** For most test cases, CORRUPT_DB is set to false using a special
20283 ** The Cte object is not guaranteed to persist for the entire duration
20290 ** than sqlite3SelectDelete(), which is what enables them to persist
20315 ** An instance of the TreeView object is used for printing the content of
20320 u8 bLine[100]; /* Draw vertical in column i if bLine[i] is true */
20325 ** This object is used in various ways, most (but not all) related to window
20328 ** (1) A single instance of this structure is attached to the
20335 ** fields point back to the expression that is the window function.
20341 ** of this object is stored in Expr.y.pWin with eFrmType set to
20342 ** TK_FILTER. In this case the only field used is Window.pFilter.
20369 Expr *pOwner; /* Expression object this window is attached to */
20451 ** FTS4 is really an extension for FTS3. It is enabled using the
20460 ** The ctype.h header is needed for non-ASCII systems. It is also
20461 ** needed by FTS3 when FTS3 is included in the amalgamation.
20885 #define ONEPASS_MULTI 2 /* ONEPASS is valid for multiple rows */
21107 ** The common case is for a varint to be a single byte. They following
21461 ** no-op macros if OMIT_FOREIGN_KEY is defined. In this case no foreign
21462 ** key functionality is available. If OMIT_TRIGGER is defined but
21463 ** OMIT_FOREIGN_KEY is not, only some of the functions are no-oped. In
21464 ** this case foreign keys are parsed, but no other functionality is
21501 ** malloc failures. This is only present if SQLITE_UNTESTABLE
21502 ** is not defined.
21570 ** sqlite3IoTrace is a pointer to a printf-like routine used to
21593 ** sqlite3MemdebugHasType() is intended for use inside assert() statements.
21598 ** Perhaps the most important point is the difference between MEMTYPE_HEAP
21599 ** and MEMTYPE_LOOKASIDE. If an allocation is MEMTYPE_LOOKASIDE, that means
21601 ** too large or lookaside was already full. It is important to verify
21607 ** All of this is no-op for a production build. It only comes into
21608 ** play when the SQLITE_MEMDEBUG compile-time option is used.
21672 ** a legal notice, here is a blessing:
21680 ** This file contains macros and a little bit of code that is common to
21681 ** all of the platform-specific files (os_*.c) and is #included into those
21684 ** This file should be #included by the os_*.c files only. It is not a
21696 # error "The MEMORY_DEBUG macro is obsolete. Use SQLITE_DEBUG instead."
21719 ** is used for testing the I/O recovery logic.
21771 ** This file is automatically generated by the script in the canonical
21782 ** a legal notice, here is a blessing:
21805 ** for those options in which the value is meaningful. */
21821 ** only a handful of compile-time options, so most times this array is usually
22570 ** a legal notice, here is a blessing:
22625 /* All of the upper-to-lower conversion data is above. The following
22627 ** sqlite3UpperToLower[] array to avoid UBSAN warnings. Here's what is
22632 ** returns negative, zero, or positive if A is less then, equal to, or
22633 ** greater than B, respectively. Then the true false results is found by
22636 ** is negative, zero, or positive, where opcode is the specific opcode.
22639 ** ensure that is the case.
22656 ** The following 256 byte lookup table is used to support SQLites built-in
22668 ** Bit 0x20 is set if the mapped character requires translation to upper
22669 ** case. i.e. if the character is a lower-case ASCII character.
22670 ** If x is a lower-case ASCII character, then its upper-case equivalent
22671 ** is (x - 0x20). Therefore toupper() can be implemented as:
22675 ** The equivalent of tolower() is implemented using the sqlite3UpperToLower[]
22676 ** array. tolower() is used more often than toupper() by SQLite.
22678 ** Bit 0x40 is set if the character is non-alphanumeric and can be used in an
22680 ** non-ASCII UTF character. Hence the test for whether or not a character is
22681 ** part of an identifier is 0x46.
22722 ** compatibility for legacy applications, the URI filename capability is
22728 ** EVIDENCE-OF: R-43642-56306 By default, URI handling is globally
22736 /* EVIDENCE-OF: R-38720-18127 The default setting is determined by the
22737 ** SQLITE_ALLOW_COVERING_INDEX_SCAN compile-time option, or is "on" if
22738 ** that compile-time option is omitted.
22745 -DSQLITE_ALLOW_COVERING_INDEX_SCAN=0 option is deprecated.\
22746 Contact SQLite developers if this is a problem for you, and\
22751 /* The minimum PMA size is set to this value multiplied by the database
22762 ** memory. (The statement journal is also always held entirely in memory
22771 ** The default lookaside-configuration, the format "SZ,N". SZ is the
22773 ** and N is the number of slots. The lookaside-configuration can be
22778 ** With the two-size-lookaside enhancement, less lookaside is required.
22780 ** and 93 128-byte slots, which is more lookaside than is available
22869 ** database connections. After initialization, this table is
22879 ** Access to this global variable is not mutex protected. This might
22889 ** sqlite3Hwtime() for profiling. This is a no-op on standard builds.
22898 ** to read or write that page. The pending byte page is set aside
22901 ** During testing, it is often desirable to move the pending byte to
22924 ** Properties of opcodes. The OPFLG_INITIALIZER macro is
22925 ** created by mkopcodeh.awk during compilation. Data is obtained
22972 ** a legal notice, here is a blessing:
22990 ** a legal notice, here is a blessing:
22997 ** This is the header file for information that is private to the
23015 ** VDBE_DISPLAY_P4 is true or false depending on whether or not the
23016 ** "explain" P4 display logic is enabled.
23027 ** SQL is translated into a sequence of instructions to be
23028 ** executed by a virtual machine. Each instruction is an instance
23054 ** A VdbeCursor is an superclass (a wrapper) for various cursor objects:
23068 u8 deferredMoveto; /* A call to sqlite3BtreeMoveto() is needed */
23076 Bool isOrdered:1; /* True if the table is not BTREE_UNORDERED */
23078 Bool colCache:1; /* pCache pointer is initialized and non-NULL */
23086 /* Cached OP_Column parse information is only valid if cacheStatus matches
23089 ** the cache is out of date. */
23090 u32 cacheStatus; /* Cache is valid if this matches Vdbe.cacheCtr */
23095 ** For CURTYPE_PSEUDO, seekResult is the register holding the record */
23097 /* When a new VdbeCursor is allocated, only the fields above are zeroed.
23127 /* Return true if P is a null-only cursor
23133 ** A value for VdbeCursor.cacheStatus that means the cache is always invalid.
23146 int iCol; /* Column for which the cache is valid */
23152 ** When a sub-program is executed (OP_Program), a structure of this type
23153 ** is allocated to store the current value of the program counter, as
23155 ** values stored in the Vdbe struct. When the sub-program is finished,
23160 ** The memory for a VdbeFrame object is allocated and managed by a memory
23161 ** cell in the parent (calling) frame. When the memory cell is deleted or
23162 ** overwritten, the VdbeFrame object is not freed immediately. Instead, it
23163 ** is linked into the Vdbe.pDelFrame list. The contents of the Vdbe.pDelFrame
23164 ** list is deleted when the VM is reset in VdbeHalt(). The reason for doing
23165 ** this instead of deleting the VdbeFrame immediately is to avoid recursive
23169 ** The currently executing frame is stored in Vdbe.pFrame. Vdbe.pFrame is
23170 ** set to NULL if the currently executing frame is the main program.
23175 VdbeFrame *pParent; /* Parent of this frame, or NULL if parent is main */
23212 double r; /* Real value used when MEM_Real is set in flags */
23213 i64 i; /* Integer value used when MEM_Int is set in flags */
23230 Mem *pScopyFrom; /* This Mem is a shallow copy of pScopyFrom */
23258 ** MEM_Term is set. This flag is
23276 ** If the MEM_Null flag is set, then the value is an SQL NULL value.
23280 ** If the MEM_Str flag is set then Mem.z points at a string representation.
23281 ** Usually this is encoded in the same unicode encoding as the main
23282 ** database (see below for exceptions). If the MEM_Term flag is also
23283 ** set, then the string is nul terminated. The MEM_Int and MEM_Real
23286 #define MEM_Undefined 0x0000 /* Value is undefined */
23287 #define MEM_Null 0x0001 /* Value is NULL (or a pointer) */
23288 #define MEM_Str 0x0002 /* Value is a string */
23289 #define MEM_Int 0x0004 /* Value is an integer */
23290 #define MEM_Real 0x0008 /* Value is a real number */
23291 #define MEM_Blob 0x0010 /* Value is a BLOB */
23300 #define MEM_Term 0x0200 /* String in Mem.z is zero terminated */
23302 #define MEM_Subtype 0x0800 /* Mem.eSubtype is valid */
23326 ** True if Mem X is a NULL-nochng type.
23333 ** Return true if a memory cell has been initialized and is valid.
23334 ** is for use inside assert() statements only.
23336 ** A Memory cell is initialized if at least one of the
23338 ** is set. It is "undefined" if all those bits are zero.
23346 ** implementation calling sqlite3_set_auxdata() is stored in an instance
23349 ** when the VM is halted (if not before).
23361 ** instance of this structure is the first argument to the routines used
23364 ** There is a typedef for this structure in sqlite.h. So all routines,
23366 ** But this file is the only place where the internal details of this
23369 ** This structure is defined inside of vdbeInt.h because it uses substructures
23373 Mem *pOut; /* The return value is stored here */
23386 ** N is the number of bits.
23394 ** This array is used by ScanStatus elements associated with EQP
23395 ** notes that make an SQLITE_SCANSTAT_NCYCLE value available. It is
23398 ** integer addresses is a start and end address (both inclusive) for a range
23414 ** is constructed during statement parsing and is held on Vdbe.pDblStr.
23416 ** list is consulted for each double-quoted identifier to see if the
23429 ** The "sqlite3_stmt" structure pointer that is returned by sqlite3_prepare()
23430 ** is really a pointer to an instance of this structure.
23530 Index *pPk; /* PK index if pTab is WITHOUT ROWID */
23534 ** An instance of this object is used to pass an vector of values into
23535 ** OP_VFilter, the xFilter method of a virtual table. The vector is the
23538 ** The value as passed into xFilter is an sqlite3_value with a "pointer"
23539 ** type, such as is generated by sqlite3_result_pointer() and read by
23754 ** state vector. If writable static data is unsupported on the target,
23756 ** case where writable static data is supported, wsdStat can refer directly
23782 ** appropriate mutex. (Locking is checked by assert()).
23785 ** The value of N is added to the current status value and the high-water
23786 ** mark is adjusted if necessary.
23789 ** mark is unchanged. N must be non-negative for StatusDown().
23905 sqlite3 *db, /* The database connection whose status is desired */
23961 ** highwater mark is meaningless and is returned as zero.
23988 ** databases. *pHighwater is set to zero.
24034 ** *pHighwater is set to zero.
24057 ** pagers the database handle is connected to. *pHighwater is always set
24086 ** have been satisfied. The *pHighwater is always set to zero.
24108 ** a legal notice, here is a blessing:
24118 ** There is only one exported symbol in this file - the function
24127 ** 1970-01-01 00:00:00 is JD 2440587.5
24128 ** 2000-01-01 00:00:00 is JD 2451544.5
24135 ** The Gregorian calendar system is used for all dates and times,
24158 ** So declare a substitute. The substitute function itself is
24176 char validJD; /* True (1) if iJD is valid */
24180 char validTZ; /* True (1) if tz is valid */
24192 ** the last integer which is specified by three characters. The meaning
24193 ** of a four-character format specifiers ABCD is:
24204 ** D: the separator character, or \000 to indicate this is the
24210 ** the 2-digit day which is the last integer in the set.
24254 ** The extension is of the form:
24262 ** If the parse is successful, write the number of minutes
24266 ** A missing specifier is not considered an error.
24302 ** Return 1 if there is a parsing error and 0 on success.
24351 ** that the YYYY-MM-DD is according to the Gregorian calendar.
24402 ** on success and 1 if the input string is not a well-formed
24453 ** Input "r" is a numeric quantity which might be a julian day number,
24454 ** or the number of seconds since 1970. If the value if r is within
24456 ** If the value is a valid unix timestamp, put it in p->s and set p->rawS.
24477 ** In the first form, the +/-HH:MM is always optional. The fractional
24478 ** seconds extension (the ".FFF") is optional. The seconds portion
24479 ** (":SS.FFF") is option. The year and date can be omitted as long
24480 ** as there is a time string. The time string can be omitted as long
24481 ** as there is a year and date.
24507 /* The julian day number for 9999-12-31 23:59:59.999 is 5373484.4999999.
24517 ** Return TRUE if the given julian day number is within range.
24519 ** The input is the JulianDay times 86400000.
24589 ** On recent Windows platforms, the localtime_s() function is available
24590 ** as part of the "Secure CRT". It is essentially equivalent to
24592 ** order of the parameters is reversed.
24609 ** is available. This routine returns 0 on success and
24612 ** If the sqlite3GlobalConfig.bLocaltimeFault variable is non-zero then this
24613 ** routine will always fail. If bLocaltimeFault is nonzero and
24614 ** sqlite3GlobalConfig.xAltLocaltime is not NULL, then xAltLocaltime() is
24618 ** library function localtime_r() is used to assist in the calculation of
24669 ** Assuming the input DateTime is UTC, move it to its localtime equivalent.
24727 ** Where NNN is an arbitrary floating-point number and "days" can be one
24745 ** If the DateTime p is raw number, try to figure out if it is
24782 ** Return 0 on success and 1 if there is any kind of error. If the error
24783 ** is in a system call (i.e. localtime()), then an error message is written
24784 ** to context pCtx. If the error is an unrecognized modifier, no error is
24801 ** If rawS is available, then interpret as a julian day number, or
24816 ** is not the first modifier, or if the prior argument is not a numeric
24833 ** Assuming the current time value is UTC (a.k.a. GMT), shift it to
24866 i64 iErr; /* Guess is off by this much */
24898 ** date is already on the appropriate weekday, this is a no-op.
24990 ** specified number of years, months, and days. MM is limited to
24991 ** the range 0-11 and DD is limited to 0-30.
25057 /* If control reaches this point, it means the transformation is
25111 ** Process time function arguments. argv[0] is a date-time stamp.
25116 ** If there are zero parameters (if even argv[0] is undefined)
25150 /* Make sure a YYYY-MM-DD is normalized.
25535 ** convert it into DATE2. The time difference format is:
25659 ** If the library is compiled to omit the full-scale date and time
25662 ** are included instead. This is to support column declarations that
25666 ** and strftime(). The format string to pass to strftime() is supplied
25735 ** a legal notice, here is a blessing:
25743 ** This file contains OS interface code that is common to all
25751 ** is used for testing the I/O recovery logic.
25808 ** of the sqlite3_file object. This is mostly just syntactic sugar. All
25856 ** is only a hint and can be safely ignored. The sqlite3OsFileControlHint()
25868 ** is using a regular VFS, it is called after the corresponding
25871 ** but the transaction is committed anyway.
25879 ** to the cksumvfs. Their return code is meaningless and is ignored
25880 ** by the SQLite core, so there is no point in simulating OOMs for them.
25931 /* No-op stubs to use when memory-mapped I/O is disabled */
25954 /* 0x87f7f is a mask of SQLITE_OPEN_ flags that are valid to be passed
26023 ** method to get the current date and time if that method is available
26024 ** (if iVersion is 2 or greater and the function pointer is not NULL) and
26025 ** will fall back to xCurrentTime() if xCurrentTimeInt64() is
26070 ** This function is a wrapper around the OS specific implementation of
26071 ** sqlite3_os_init(). The purpose of the wrapper is to provide the
26089 ** Locate a VFS by name. If no name is given, simply return the
26134 ** Register a VFS with the system. It is harmless to register the same
26135 ** VFS multiple times. The new VFS becomes the default if makeDflt is
26164 ** Unregister a VFS so that it is no longer accessible.
26185 ** a legal notice, here is a blessing:
26200 ** SQLITE_NOMEM) to the user. However, sometimes a fault is not necessarily
26202 ** is completely recoverable simply by not carrying out the resize. The
26204 ** during a hash table resize is a benign fault.
26221 ** structure. If writable static data is unsupported on the target,
26223 ** case where writable static data is supported, wsdHooks can refer directly
26250 ** This (sqlite3EndBenignMalloc()) is called by SQLite code to indicate that
26275 ** a legal notice, here is a blessing:
26284 ** SQLITE_ZERO_MALLOC is defined. The allocation drivers implemented
26292 ** This version of the memory allocator is the default. It is
26293 ** used when no other memory allocator is specified using compile-time
26310 ** This routine is the only routine in this file with external linkage.
26337 ** a legal notice, here is a blessing:
26351 ** this file is only used if SQLITE_SYSTEM_MALLOC is defined. The
26352 ** SQLITE_SYSTEM_MALLOC macro is defined automatically if neither the
26354 ** default configuration is to use memory allocation routines in this
26379 ** This version of the memory allocator is the default. It is
26380 ** used when no other memory allocator is specified using compile-time
26388 ** SQLITE_WITHOUT_ZONEMALLOC symbol is defined.
26406 ** Also used by Apple systems if SQLITE_WITHOUT_ZONEMALLOC is defined.
26413 ** The malloc.h header file is needed for malloc_usable_size() function
26420 ** The MSVCRT has malloc_usable_size(), but it is called _msize(). The
26421 ** use of _msize() is automatic, but can be disabled by compiling with
26432 ** SQLITE_MALLOCSIZE to the appropriate function name, which is _msize()
26604 ** This routine is the only routine in this file with external linkage.
26631 ** a legal notice, here is a blessing:
26651 ** This version of the memory allocator is used only if the
26652 ** SQLITE_MEMDEBUG macro is defined
26657 ** The backtrace functionality is only available with GLIBC
26678 ** backtrace pointers. There is also a guard word at the end of the
26704 ** into a single structure named "mem". This is to keep the
26706 ** when this module is combined with other in the amalgamation.
26741 ** nAlloc[i] is the number of allocation attempts of i*8
26742 ** bytes. i==NCSIZE is the number of allocation attempts for
26818 /* If memory status is enabled, then the malloc.c wrapper will already
26841 ** Fill a buffer with pseudo-random bytes. This is used to preset
26965 ** higher level code is using pointer to the old allocation, it is
27020 ** This routine is designed for use within an assert() statement, to
27030 assert( pHdr->iForeGuard==FOREGUARD ); /* Allocation is valid */
27042 ** This routine is designed for use within an assert() statement, to
27052 assert( pHdr->iForeGuard==FOREGUARD ); /* Allocation is valid */
27062 ** A value of zero turns off backtracing. The number is always rounded
27162 ** a legal notice, here is a blessing:
27177 ** the amount of memory available to SQLite is fixed and cannot
27180 ** This version of the memory allocation subsystem is included
27181 ** in the build only if SQLITE_ENABLE_MEMSYS3 is defined.
27186 ** This version of the memory allocator is only built into the library
27187 ** SQLITE_ENABLE_MEMSYS3 is defined. Defining this symbol does not
27189 ** it is available. The mempool allocator is activated by calling
27207 ** more blocks where each block is 8 bytes. The first 8 bytes are
27208 ** a header that is not returned to the user.
27210 ** A chunk is two or more blocks that is either checked out or
27211 ** free. The first block has format u.hdr. u.hdr.size4x is 4 times the
27212 ** size of the allocation in blocks if the allocation is free.
27213 ** The u.hdr.size4x&1 bit is true if the chunk is checked out and
27214 ** false if the chunk is on the freelist. The u.hdr.size4x&2 bit
27215 ** is true if the previous chunk is checked out and false if the
27216 ** previous chunk is free. The u.hdr.prevSize field is the size of
27217 ** the previous chunk in blocks if the previous chunk is on the
27218 ** freelist. If the previous chunk is checked out, then
27223 ** this is done, the chunk index refers to the second block of
27225 ** A chunk index of 0 means "no such chunk" and is the equivalent
27228 ** The second block of free chunks is of the form u.list. The
27233 ** The second block of a chunk is user data if the chunk is checked
27234 ** out. If a chunk is checked out, the user data may extend into
27253 ** into a single structure named "mem3". This is to keep the
27255 ** when this module is combined with other in the amalgamation.
27259 ** Memory available for allocation. nPool is the size of the array
27281 ** iKeyBlk is the index of the key chunk. Most new allocations
27282 ** occur off of this chunk. szKeyBlk is the size (in Mem3Blocks)
27283 ** of the current key chunk. iKeyBlk is 0 if there is no key chunk.
27284 ** The key chunk is not in either the aiHash[] or aiSmall[].
27301 ** Unlink the chunk at mem3.aPool[i] from list it is currently
27302 ** on. *pRoot is the list that i is a member of.
27322 ** whatever list is currently a member of.
27341 ** Link the chunk at mem3.aPool[i] so that is on the list rooted
27375 ** If the STATIC_MEM mutex is not already held, obtain it now. The mutex
27377 ** sqlite3GlobalConfig.bMemStat is true.
27405 ** Chunk i is a free chunk that has been unlinked. Adjust its
27425 ** is not large enough, return 0.
27457 ** *pRoot is the head of a list of free chunks of the same size
27458 ** or same size hash. In other words, *pRoot is an entry in either
27464 ** If it sees a chunk that is larger than mem3.iKeyBlk, it replaces
27467 ** linked into the hash tables. That is not the normal state of
27527 ** chunk table or in the large chunk hash table. This is
27776 fprintf(out, "%p tail checkout bit is incorrect\n", &mem3.aPool[i]);
27820 ** This routine is the only routine in this file with external
27827 ** This routine is only called by sqlite3_config(), and therefore
27828 ** is not required to be threadsafe (it is not).
27852 ** a legal notice, here is a blessing:
27867 ** the amount of memory available to SQLite is fixed and cannot
27870 ** This version of the memory allocation subsystem is included
27871 ** in the build only if SQLITE_ENABLE_MEMSYS5 is defined.
27880 ** 3. New memory is allocated from the first available free block.
27882 ** This algorithm is described in: J. M. Robson. "Bounds for Some Functions
27901 ** This version of the memory allocator is used only when
27902 ** SQLITE_ENABLE_MEMSYS5 is defined.
27907 ** A minimum allocation is an instance of the following structure.
27909 ** size of the array is a power of 2.
27911 ** The size of this object must be a power of two. That fact is
27921 ** Maximum size of any allocation is ((1<<LOGMAX)*mem5.szAtom). Since
27922 ** mem5.szAtom is always at least 8 and 32-bit integers are used,
27923 ** it is not actually possible to reach this limit.
27935 ** into a single structure named "mem5". This is to keep the
27937 ** when this module is combined with other in the amalgamation.
27967 ** Lists of free blocks. aiFreelist[0] is a list of free blocks of
27987 ** Assuming mem5.zPool is divided up into an array of Mem5Link
27993 ** Unlink the chunk at mem5.aPool[i] from list it is currently
28015 ** Link the chunk at mem5.aPool[i] so that is on the iLogsize
28061 ** The caller guarantees that nByte is positive.
28064 ** routine so there is never any chance that two or more
28125 /* Make sure the allocated memory does not assume that it is set to zero
28192 /* Overwrite freed memory with the 0x55 bit pattern to verify that it is
28232 ** nBytes is always a value obtained from a prior call to
28233 ** memsys5Round(). Hence nBytes is always a non-negative power
28261 ** the allocation is too large to be handled by this allocation system,
28265 ** 32-bit signed integer. Hence the largest allocation is 0x40000000
28303 ** This routine is not threadsafe. The caller must be holding a mutex
28319 ** this is case.
28353 /* If a mutex is required for normal operation, allocate one */
28414 ** This routine is the only routine in this file with external
28440 ** a legal notice, here is a blessing:
28449 ** This file contains code that is common across all mutex implementations.
28455 ** For debugging purposes, record when the mutex subsystem is initialized
28456 ** and uninitialized so that we can assert() if there is an attempt to
28457 ** allocate a mutex while the system is uninitialized.
28472 ** mutex implementation. Except, if a mutex is configured by calling
28473 ** sqlite3MutexWarnOnContention() on it, then if contention is ever
28474 ** encountered within xMutexEnter() a warning is emitted via sqlite3_log().
28476 ** This type of mutex is used as the database handle mutex when testing
28482 ** is defined. Variable CheckMutex.mutex is a pointer to the real mutex
28483 ** allocated by the system mutex implementation. Variable iType is usually set
28485 ** or one of the static mutex identifiers. Or, if this is a recursive mutex
28486 ** that has been configured using sqlite3MutexWarnOnContention(), it is
28770 ** entered by the same thread. The behavior is undefined if the mutex
28771 ** is not currently entered. If a NULL pointer is passed as an argument
28772 ** this function is a no-op.
28804 ** a legal notice, here is a blessing:
28814 ** exclusion and is thus suitable for use only in applications
28823 ** If compiled with SQLITE_DEBUG, then additional logic is inserted
28871 ** In this implementation, error checking is provided for testing
28953 ** to enter a mutex. If another thread is already within the mutex,
28960 ** more than once, the behavior is undefined.
28977 ** is undefined if the mutex is not currently entered or
28978 ** is not currently allocated. SQLite will never do either.
29007 ** is used regardless of the run-time threadsafety setting.
29022 ** a legal notice, here is a blessing:
29034 ** The code in this file is only used if we are compiling threadsafe
29056 ** Each recursive mutex is an instance of the following structure.
29065 volatile pthread_t owner; /* Thread that is within this mutex */
29082 ** deliver incorrect results. In particular, if pthread_equal() is
29084 ** incorrect results. On most platforms, pthread_equal() is a
29085 ** comparison of two integers and is therefore atomic. But we are
29086 ** told that HPUX is not such a platform. If so, then these routines
29089 ** On those platforms where pthread_equal() is not atomic, SQLite
29106 ** where SQLite is compiled without mutexes.
29127 ** to sqlite3_mutex_alloc() is one of these integer constants:
29147 ** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
29148 ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
29153 ** implementation is available on the host platform, the mutex subsystem
29165 ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
29167 ** mutex types, the same mutex is returned on every call that has
29195 /* Use a recursive mutex if it is available */
29238 ** allocated mutex. SQLite is careful to deallocate every
29259 ** to enter a mutex. If another thread is already within the mutex,
29266 ** more than once, the behavior is undefined.
29274 ** is atomic - that it cannot be deceived into thinking self
29276 ** that are not equal to self while the comparison is taking place.
29317 ** is atomic - that it cannot be deceived into thinking self
29319 ** that are not equal to self while the comparison is taking place.
29364 ** is undefined if the mutex is not currently entered or
29365 ** is not currently allocated. SQLite will never do either.
29419 ** a legal notice, here is a blessing:
29432 ** Include code that is common to all os_*.c files
29445 ** a legal notice, here is a blessing:
29453 ** This file contains code that is specific to Windows.
29482 ** everything is Windows NT unless the programmer explicitly says otherwise
29535 ** The code in this file is only used if we are compiling multithreaded
29541 ** Each recursive mutex is an instance of the following structure.
29588 ** and also for the xShmBarrier method of the VFS in cases when SQLite is
29626 ** "interlocked" magic used here is probably not strictly necessary.
29646 /* Another thread is (in the process of) initializing the static
29675 ** to sqlite3_mutex_alloc() is one of these integer constants:
29695 ** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
29696 ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
29701 ** implementation is available on the host platform, the mutex subsystem
29713 ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
29715 ** mutex types, the same mutex is returned on every call that has
29763 ** allocated mutex. SQLite is careful to deallocate every
29781 ** to enter a mutex. If another thread is already within the mutex,
29788 ** more than once, the behavior is undefined.
29821 ** The sqlite3_mutex_try() routine is very rarely used, and when it
29822 ** is used it is merely an optimization. So it is OK for it to always
29825 ** The TryEnterCriticalSection() interface is only available on WinNT.
29860 ** is undefined if the mutex is not currently entered or
29861 ** is not currently allocated. SQLite will never do either.
29913 ** a legal notice, here is a blessing:
29928 ** held by SQLite. An example of non-essential memory is memory used to
29936 ** is a no-op returning zero if SQLite is not compiled with
29959 ** True if heap is nearly "full" where "full" is defined by the
29977 ** that was invoked when memory usage grew too large. Now it is a
29994 ** zero disables the limit. A negative argument is a no-op used to
29997 ** The return value is the value of the heap limit just before this
30000 ** If the hard heap limit is enabled, then the soft heap limit cannot
30035 ** disables the hard heap limit. A negative argument is a no-op used
30038 ** The return value is the value of the hard heap limit just prior to
30084 ** Return true if the heap is currently under memory pressure - in other
30085 ** words if the amount of heap used is close to the limit set by
30134 ** lock is already held.
30142 /* In Firefox (circa 2017-02-08), xRoundup() is remapped to an internal
30144 ** mode and specifically when the DMD "Dark Matter Detector" is enabled
30184 ** This is not a limit on the total amount of memory used. This is
30187 ** The upper bound is slightly less than 2GiB: 0x7ffffeff == 2,147,483,391
30199 # error Maximum size for SQLITE_MAX_ALLOCATION_SIZE is 2147483391
30203 ** Allocate memory. This routine is like sqlite3_malloc() except that it
30222 ** This version of the memory allocation is for use by the application.
30223 ** First make sure the memory subsystem is initialized, then do the
30240 ** TRUE if p is a lookaside memory allocation from db
30326 ** connection. Calling sqlite3DbFree(D,X) for X==0 is a harmless no-op.
30426 /* The 0x7ffff00 limit term is explained in comments on sqlite3Malloc() */
30431 ** argument to xRealloc is always a value returned by a prior call to
30470 ** subsystem is initialized prior to invoking sqliteRealloc.
30529 ** If db!=0 and db->mallocFailed is true (indicating a prior malloc
30532 ** failing, it fails consistently until mallocFailed is reset.
30533 ** This is an important assumption. There are many places in the
30540 ** In other words, if a subsequent malloc (ex: "b") worked, it is assumed
30543 ** The sqlite3MallocRawNN() variant guarantees that the "db" parameter is
30667 ** is because when memory debugging is turned on, these two functions are
30705 /* Because of the way the parser works, the span is guaranteed to contain
30761 ** The memory allocator is not restarted if there are running
30790 ** The returned value is normally a copy of the second argument to this
30792 ** invocation SQLITE_NOMEM is returned instead.
30795 ** returned by sqlite3_errcode()) is set to SQLITE_NOMEM.
30800 ** is unsafe, as is the call to sqlite3Error().
30813 ** The "printf" code that follows dates from the 1980's. It is in
30853 ** An "etByte" is an 8-bit unsigned value.
30858 ** Each builtin conversion character (ex: the 'd' in "%d") is described
30873 #define FLAG_SIGNED 1 /* True if the value to convert is signed */
30878 ** The following table is searched linearly, so it is good to put the
30948 ** If the requested size of the temp buffer is larger than the size
30998 etByte flag_leftjustify; /* True if "-" flag is present */
31000 etByte flag_alternateform; /* True if "#" flag is present */
31001 etByte flag_altform2; /* True if "!" flag is present */
31023 ** malloc(). This precondition is required by the mprintf("%z...")
31167 ** flag_alternateform TRUE if a '#' is present.
31168 ** flag_altform2 TRUE if a '!' is present.
31170 ** flag_leftjustify TRUE if a '-' is present or if the
31174 ** width The specified field width. This is
31175 ** always non-negative. Zero is the default.
31177 ** is -1.
31350 ** If the field type is etGENERIC, then convert to either etEXP
31438 /* The converted number is in buf[] and zero terminated. Output it.
31439 ** Note that the number is in the usual order, not reversed as with
31444 /* Special case: Add leading zeros if the flag_zeropad flag is
31599 /* For %q, %Q, and %w, the precision is the number of bytes (or
31600 ** characters if the ! flags is present) to use from the input.
31685 ** The text of the conversion is pointed to by "bufpt" and is
31686 ** "length" characters long. The field width is "width". Do
31710 ** The z string points to the first character of a token that is
31747 ** Enlarge the memory allocation on a StrAccum object so that it is
31750 ** Return the number of bytes of text that StrAccum is able to accept
31812 ** The StrAccum "p" is not large enough to accept N new bytes of z[].
31815 ** This is a helper routine to sqlite3_str_append() that does special-case
31854 ** Finish off a string by making sure it is zero-terminated.
31898 ** This singleton is an sqlite3_str object that is returned if
31955 ** memory is used if not NULL. db->mallocFailed is set appropriately
31958 ** is malloced.
32061 ** current locale settings. This is important for SQLite because we
32066 ** from the snprintf() standard. Unfortunately, it is too late to change
32070 ** sqlite3_vsnprintf() is the varargs version.
32107 ** This is the routine that actually formats the sqlite3_log() message.
32109 ** stack space on small-stack systems when logging is disabled.
32113 ** mutex is held.
32118 ** memory mutex is held do not use these mechanisms.
32131 ** Format and write a message to the log if logging is enabled.
32189 ** The input parameter is returned.
32216 ** Create a new string that is capable of holding N bytes of text, not counting
32217 ** the zero byte at the end. The string is uninitialized.
32219 ** The reference count is initially 1. Call sqlite3RCStrUnref() to free the
32232 ** Change the size of the string so that it is able to hold N bytes.
32256 ** a legal notice, here is a blessing:
32268 ** The interfaces in this file is only available when compiling
32276 ** is not the last item in the tree.
33020 ** This is equivalent to
33024 ** X is stored in pExpr->pLeft.
33025 ** Y is stored in pExpr->pList->a[0].pExpr.
33026 ** Z is stored in pExpr->pList->a[1].pExpr.
33042 /* If the opcode is TK_TRIGGER, then the expression is a reference
33044 ** trigger programs. In this case Expr.iTable is set to 1 for the
33046 ** is set to the column of the pseudo-table to read, or to -1 to
33571 ** a legal notice, here is a blessing:
33588 ** This structure is the current state of the generator.
33629 ** state vector. If writable static data is unsupported on the target,
33631 ** case where writable static data is supported, wsdPrng can refer directly
33661 ** the first time this routine is called.
33731 ** a legal notice, here is a blessing:
33743 ** runs independently of its creator until it is joined using
33747 ** "thread" is done by the main thread at either the sqlite3ThreadCreate()
33748 ** or sqlite3ThreadJoin() call. This is, in fact, what happens in
33787 /* This routine is never used in single-threaded mode */
33796 /* If the SQLITE_TESTCTRL_FAULT_INSTALL callback is registered to a
33884 /* If the SQLITE_TESTCTRL_FAULT_INSTALL callback is registered to a
33940 ** work of the thread in the main thread, when either the thread is created
33941 ** or when it is joined
34008 ** a legal notice, here is a blessing:
34045 ** The following constant value is used by the SQLITE_BIGENDIAN and
34052 ** This lookup table is used to help decode the first byte of
34115 ** is a 0x00.
34123 ** attempts to encode a value between 0x00 and 0x7f is rendered as 0xfffd.
34127 ** 0xd800 and 0xe000 then it is rendered as 0xfffd.
34155 ** For this routine, we assume the UTF8 string is always zero-terminated.
34172 ** more than n characters from the buffer. z[] is not zero-terminated.
34176 ** Invalid UTF8 might generate a strange result. No effort is made
34205 ** If the TRANSLATE_TRACE macro is defined, the value of each Mem is
34213 ** desiredEnc. It is an error if the string is already of the desired
34240 /* If the translation is between UTF-16 little and big endian, then
34241 ** all that is required is to swap the byte order. This case is handled
34268 ** A single byte is required for the output string
34274 /* When converting from UTF-8 to UTF-16 the maximum growth is caused
34275 ** when a 1-byte UTF-8 character is translated into a 2-byte UTF-16
34285 ** Variable zOut is set to point at the output buffer, space obtained
34404 ** UTF-16 string stored in *pMem. If one is present, it is removed and
34443 ** pZ is a UTF-8 encoded unicode string. If nByte is less than zero,
34445 ** the first 0x00 byte. If nByte is not less than zero, return the
34466 /* This test function is not currently used by the automated test-suite.
34467 ** Hence it is only available in debug builds.
34473 ** This has the effect of making sure that the string is well-formed
34476 ** The translation is done in-place and aborted if the output
34498 ** Memory to hold the UTF-8 string is obtained from sqlite3_malloc and must
34501 ** NULL is returned if there is an allocation error.
34520 ** zIn is a UTF-16 encoded unicode string at least nChar characters long.
34542 ** This routine is called from the TCL test function "translate_selftest".
34577 ** a legal notice, here is a blessing:
34606 ** each call to sqlite3FaultSim() is relayed to that application-supplied
34608 ** callback is returned by sqlite3FaultSim().
34610 ** The integer argument to sqlite3FaultSim() is a code to identify which
34611 ** sqlite3FaultSim() instance is being invoked. Each call to sqlite3FaultSim()
34624 ** Return true if the floating point value is Not a Number (NaN).
34644 ** Compute a string length that is limited to what can be stored in
34660 ** The column type is an extra string stored after the zero-terminator on
34661 ** the column name if and only if the COLFLAG_HASTYPE flag is set.
34711 ** Load the sqlite3.iSysErrno field if that is an appropriate thing
34741 ** handle "db". The error code is set to "err_code".
34743 ** If it is not NULL, string zFormat specifies the format of the
34796 ** last thing the sqlite3_prepare() function does is copy the error
34828 ** If database connection db is currently parsing SQL, then transfer
34842 ** the quote characters. The conversion is done in-place. If the
34844 ** is a no-op.
34847 ** is added to the dequoted string.
34849 ** The return value is -1 if no dequoting occurs or the length of the
34853 ** 2002-02-14: This routine is extended to remove MS-Access style
34887 ** If the input token p is quoted, try to adjust the token to remove
34888 ** the quotes. This is not always possible:
34893 ** Remove the quotes if possible. This is a optimization. The overall
34895 ** is always a no-op.
34921 ** there is no consistency, we will define our own.
34970 ** Compute an 8-bit hash on a string that is insensitive to case differences
34993 ** format. The truncation is necessary for the Dekker algorithm to
35019 ** The string z[] is an text representation of a real number.
35022 ** The string z[] is length bytes in length (bytes, not characters) and
35023 ** uses the encoding enc. The string is not necessarily zero-terminated.
35025 ** Return TRUE if the result is a valid real number (or integer) and FALSE
35026 ** if the string is empty or contains extraneous text. More specifically
35028 ** 1 => The input string is a pure integer
35030 ** 0 or less => The input string is not a valid number
35040 ** Leading and trailing whitespace is ignored for the purpose of determining
35043 ** If some prefix of the input string is a valid number, this routine
35060 int eValid = 1; /* True exponent is either not used or is well-formed */
35108 /* if decimal point is present */
35125 /* if exponent is present */
35131 /* This branch is needed to avoid a (harmless) buffer overread. The
35133 ** is obtained even if the branch is omitted */
35155 /* Zero is a special case */
35259 ** The caller must ensure that zOut[] is at least 21 bytes in size.
35286 ** if zNum is less than, equal to, or greater than the string.
35289 ** Unlike memcmp() this routine is guaranteed to return the difference
35290 ** in the values of the last digit if the only difference is in the
35323 ** 2 Integer too large for a 64-bit signed integer or is malformed
35326 ** length is the number of bytes in the string (bytes, not characters).
35327 ** The string is not necessarily zero-terminated. The encoding is
35370 /* This test and assignment is needed only to suppress UB warnings
35400 /* zNum is a 19-digit numbers. Compare it against 9223372036854775808. */
35403 /* zNum is less than 9223372036854775808 so it fits */
35409 /* zNum is greater than 9223372036854775808 so it overflows */
35412 /* zNum is exactly 9223372036854775808. Fits if negative. The
35430 ** 2 Integer too large for a 64-bit signed integer or is malformed
35464 ** This is different from sqlite3Atoi64() which requires the
35502 /* The longest decimal representation of a 32 bit integer is 10 digits:
35524 ** string is not an integer, just return 0.
35537 ** n is positive. Or round to -n signficant digits after the
35538 ** decimal point if n is negative. No rounding is performed if
35539 ** n is zero.
35542 ** stored in p->z[] which is a often (but not always) a pointer
35544 ** The p->z[] array is *not* zero-terminated.
35592 /* If high-precision floating point is not available using "long double",
35681 ** success and false if there is an error.
35683 ** Only decimal notation is accepted.
35698 ** The variable-length integer encoding is as follows:
35719 ** of bytes written is returned.
35724 ** 8 bits and is the last byte.
35778 ** Return the number of bytes read. The value is stored in *v.
35932 ** Return the number of bytes read. The value is stored in *v.
35934 ** If the varint stored in p[0] is larger than can fit in a 32-bit unsigned
35937 ** A MACRO version, getVarint32, is provided which inlines the
35950 /* This is the two-byte case */
35955 /* This is the three-byte case */
36023 ** This routine only works if h really is a valid hexadecimal
36061 ** Log an error that is an API call on a connection pointer that should
36062 ** not have been used. The "type" of connection pointer is given as the
36063 ** argument. The zType is a word like "NULL" or "closed" or "invalid".
36073 ** Check to make sure we have a valid db pointer. This test is not
36077 ** 1 it means that the db pointer is valid and 0 if it should not be
36083 ** open properly and is not fit for general use but which can be
36192 ** If SQLITE_ENABLE_8_3_NAMES is set at compile-time and if the database
36193 ** filename in zBaseFilename is a URI with the "8_3_names=1" parameter and
36194 ** if filename in z[] has a suffix (a.k.a. "extension") that is longer than
36198 ** If SQLITE_ENABLE_8_3_NAMES is set to 2 at compile-time, then always
36222 ** Find (an approximate) sum of two LogEst values. This computation is
36223 ** not a simple "+" operator because LogEst is stored as a logarithmic
36305 ** db->mallocFailed flag is set.
36307 ** A VList is really just an array of integers. To destroy a VList,
36310 ** The first integer is the number of integers allocated for the whole
36311 ** VList. The second integer is the number of integers actually used.
36312 ** Each name/number pair is encoded by subsequent groups of 3 or more
36318 ** is always zero-terminated.
36333 ** VList are taken. When that happens, nAlloc is set to zero as an
36346 int i; /* Index in pIn[] where zName is stored */
36372 ** has the value iVal. Or return a NULL if there is no such variable in
36388 ** Return the number of the variable named zName, if it is in VList.
36389 ** or return 0 if there is no such variable.
36416 ** a legal notice, here is a blessing:
36485 ** asm() is needed for hardware timing support. Without asm(),
36488 ** sqlite3Hwtime() is only used for some obscure debugging
36508 ** a legal notice, here is a blessing:
36515 ** This is the implementation of generic hash-tables
36524 ** "pNew" is a pointer to the hash table that is to be initialized.
36563 ** 0x9e3779b1 is 2654435761 which is the closest prime number to
36577 struct _ht *pEntry, /* The entry into which pNew is inserted */
36606 ** if the new size is the same as the prior size.
36620 /* The inability to allocates space for a larger hash table is
36621 ** a performance hit but it is not a fatal error. So mark the
36646 ** hash table that matches the given key. If no element is found,
36647 ** a pointer to a static null element with HashElem.data==0 is returned.
36648 ** If pH is not NULL, then the hash for this key is written to *pH.
36718 ** that matches pKey. Return the data for this element if it is
36719 ** found, or NULL if there is no match.
36727 /* Insert an element into the hash table pH. The key is pKey
36728 ** and the data is "data".
36731 ** element is created and NULL is returned.
36734 ** new data replaces the old data and the old data is returned.
36735 ** The key is not copied in this instance. If a malloc fails, then
36736 ** the new data is returned and the hash table is unchanged.
36738 ** If the "data" parameter to this function is NULL, then the
36739 ** element corresponding to "key" is removed from the hash table.
36990 ** a legal notice, here is a blessing:
37009 /* SQLITE_KV_TRACE() is used for tracing calls to kvstorage routines. */
37016 /* SQLITE_KV_LOG() is used for tracing calls to the VFS interface */
37035 int isJournal; /* True if this is a journal file */
37162 ** zKeyOut[]. The zKeyOut[] buffer is assumed to hold at least
37173 /* Write content into a key. zClass is the particular namespace of the
37203 ** this routine is a no-op.
37215 ** nBuf bytes of zBuf[]. The value might be truncated if zBuf is not large
37217 ** terminated, even if it gets truncated because nBuf is not large enough.
37274 ** concerns, so it does not need an iVersion member. This file is
37292 ** That said, kvvfs is intended primarily for use in WASM builds.
37294 ** Note that this is not explicitly flagged as static because the
37311 ** The output text is stored in aOut[], which must be at least
37327 ** * Because there is no overlap between the encoding characters
37328 ** of hexadecimal and base-26 numbers, it is always clear where
37340 /* A sequence of 1 or more zeros is stored as a little-endian
37341 ** base-26 number using a..z as the digits. So one zero is "b".
37342 ** Two zeros is "c". 25 zeros is "z", 26 zeros is "ab", 27 is "bb",
37379 ** Decode the text encoding back to binary. The binary content is
37382 ** The return value is the number of bytes actually written into aOut[].
37420 ** if an error is encountered.
37423 ** base-26 number (digits a..z) that is the total number of bytes
37424 ** in the decoded journal file image. This base-26 number is followed
37426 ** separator is required to act as a terminator for the base-26 number.
37837 ** Delete the file located at zPath. If the dirSync argument is true,
37853 ** is available, or false otherwise.
37883 ** to the pathname in zPath. zOut is guaranteed to point to a buffer
37950 ** This routine is called initialize the KV-vfs as the default VFS.
37972 ** a legal notice, here is a blessing:
37984 ** The differences are in the way that file locking is done. The default
37989 ** This source file is organized into divisions where the logic for various
37990 ** subfunctions is contained within the appropriate division. PLEASE
37994 ** The layout of divisions is as follows:
38014 #if SQLITE_OS_UNIX /* This file is used on unix only */
38029 ** is defined to 1. The SQLITE_ENABLE_LOCKING_STYLE also enables automatic
38031 ** where the database is located.
38077 ** Try to determine if gethostuuid() is available based on standard
38098 # warning "gethostuuid() is disabled."
38196 ** Only set the lastErrno if the error code is a real error and not
38208 ** Sometimes, after a file handle is closed by SQLite, the file descriptor
38220 ** The unixFile structure is subclass of sqlite3_file specific to the unix
38262 ** occur if a file is updated without also updating the transaction
38263 ** counter. This test is made to avoid new problems similar to the
38274 ** it is larger than the struct CrashFile defined in test6.c.
38281 ** method was called. If xOpen() is called from a different process id,
38290 #define UNIXFILE_RDONLY 0x02 /* Connection is read only */
38303 ** Include code that is common to all os_*.c files
38347 ** is the 32-bit version, even if _FILE_OFFSET_BITS=64 is defined.
38370 ** The difference is important when using a pointer to the function.
38372 ** The safest way to deal with the problem is to always use this wrapper
38413 ** DJGPP. But it is DOS - what did you expect?
38578 ** This is the xSetSystemCall() method of sqlite3_vfs for all of the
38580 ** system call pointer, or SQLITE_NOTFOUND if there is no configurable
38593 /* If no zName is given, restore all system calls to their default
38603 /* If zName is specified, operate on only the one system call
38622 ** Return the value of a system call. Return NULL if zName is not a
38623 ** recognized system call name. NULL is also returned if the system call
38624 ** is currently undefined.
38642 ** is the last system call or if zName is not the name of a valid
38673 ** If the file creation mode "m" is 0 then set it to the default for
38674 ** SQLite. The default is SQLITE_DEFAULT_FILE_PERMISSIONS (normally
38675 ** 0644) as modified by the system umask. If m is not 0, then
38681 ** In that way, if a database file is -rw-rw-rw or -rw-rw-r-, and a
38683 ** process that is able to write to the database will also be able to
38728 ** global mutex is used to protect the unixInodeInfo and
38732 ** Function unixMutexHeld() is used to assert() that the global mutex
38733 ** is held when required. This function is only used as part of assert()
38741 ** before the unixInodeInfo.pLockMutex mutex, if both are held. It is
38744 ** pLockMutex is released.
38789 ** This routine is used for troubleshooting locks on multithreaded
38791 ** command-line option on the compiler. This code is normally
38856 ** _FILE_OFFSET_BITS=64 is defined. This means it is unsafe to attempt to
38869 ** useful to the clients of the sqlite3 functions. Specifically, it is
38911 ** a copy of the canonical filename. There is also a reference count.
38912 ** The structure is reclaimed when the number of pointers to it drops to
38916 ** a performance-critical path, so it is sufficient to put these
38939 ** * convert /A/../ where A is any simple name into just /
38943 ** The original filename is in z[0..n-1]. Return the number of
38971 ** a pointer to the vxworksFileId object. This pointer is the unique
38974 ** The nRef field of the vxworksFileId object is incremented before
38975 ** the object is returned. A new vxworksFileId object is created
39054 ** one is a hard or symbolic link to the other) then if you set
39068 ** on its own. Whenever a new database is opened, we have to find the
39069 ** specific inode of the database file (the inode is determined by the
39080 ** The sqlite3_file structure for POSIX is no longer just an integer file
39081 ** descriptor. It is now a structure that holds the integer file
39083 ** locks on the corresponding inode. There is one locking structure
39084 ** per inode, so if the same inode is opened twice, both unixFile structures
39088 ** file is unlocked. cnt==-1 means the file has an exclusive lock.
39092 ** structure. The fcntl() system call is only invoked to set a
39102 ** When an attempt is made to close an unixFile, if there are
39104 ** to close() the file descriptor is deferred until all of the locks clear.
39106 ** be closed and that list is walked (and cleared) when the last lock
39111 ** Many older versions of linux use the LinuxThreads library which is
39114 ** Only thread A can modify the lock. Locking behavior is correct
39117 ** in thread B. But there is no way to know at compile-time which
39118 ** threading library is being used. So there is no way to know at
39125 ** LinuxThreads provided that (1) there is no more than one connection
39151 ** An instance of the following structure is allocated for each open
39181 unsigned char bProcessLock; /* An exclusive process lock is held */
39205 ** True if the inode mutex (on the unixFile.pFileMutex field) is held, or not.
39206 ** This routine is used only within assert() to help verify correct mutex
39221 ** This function - unixLogErrorAtLine(), is only ever called via the macro
39224 ** It is invoked after an error occurs in an OS function and errno has been
39245 /* If this is not a threadsafe build (SQLITE_THREADSAFE==0), then use
39254 /* If STRERROR_R_CHAR_P (set by autoconf scripts) or __USE_GNU is defined,
39261 ** If the code incorrectly assumes that it is the POSIX version that is
39263 ** huge problem. Incorrectly concluding that the GNU version is available
39272 /* This is a threadsafe build, but strerror_r() is not available. */
39291 ** We assume that close() almost always works, since it is only in a
39296 ** Note that it is not safe to retry close() after EINTR since the
39335 ** The global mutex must be held when this routine is called, but the mutex
39401 /* On OS X on an msdos filesystem, the inode number is reported
39405 ** prior to accessing the inode number. The one byte written is
39408 ** is a race condition such that another thread has already populated
39409 ** the first page of the database, no damage is done.
39480 ** Check a unixFile that is a database. Verify the following:
39482 ** (1) There is exactly one hard link on the file
39483 ** (2) The file is not a symbolic link
39486 ** Issue sqlite3_log(SQLITE_WARNING,...) messages if anything is not right.
39516 ** This routine checks if there is a RESERVED lock held on the specified
39517 ** file by this or any other process. If such a lock is held, set *pResOut
39518 ** to a non-zero value otherwise *pResOut is set to zero. The return value
39519 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
39570 ** which is a pointer to a unixFile. If the unixFile->iBusyTimeout
39571 ** value is set, then it is the number of milliseconds to wait before
39572 ** failing the lock. The iBusyTimeout value is always reset back to
39575 ** If SQLITE_ENABLE_SETLK_TIMEOUT is not defined, then do a non-blocking
39591 ** generic posix, however, there is no such API. So we simply try the
39593 ** the lock is obtained. */
39604 ** Attempt to set a system-lock on the file pFile. The lock is
39608 ** ever obtained is an exclusive lock, and it is obtained exactly once
39609 ** the first time any lock is attempted. All subsequent system locking
39612 ** within this process, but all of that is handled in memory and the
39615 ** This function is a pass-through to fcntl(F_SETLK) if pFile is using
39616 ** any VFS other than "unix-excl" or if pFile is opened on "unix-excl"
39617 ** and is read-only.
39619 ** Zero is returned if the call completes successfully, or -1 if a call
39620 ** to fcntl() fails. In this case, errno is set appropriately (by fcntl()).
39678 ** accessing the same database file, in case that is ever required.
39684 ** To obtain a SHARED lock, a read-lock is obtained on the 'pending
39685 ** byte'. If this is successful, 'shared byte range' is read-locked
39689 ** single randomly selected by from the 'shared byte range' is locked.
39690 ** Windows95 is now pretty much extinct, but this work-around for the
39695 ** A RESERVED lock is implemented by grabbing a write-lock on the
39699 ** RESERVED lock is held. An EXCLUSIVE lock is implemented by obtaining
39705 ** a PENDING lock is obtained first. A PENDING lock is implemented by
39725 /* If there is already a lock of this type or more restrictive on the
39735 /* Make sure the locking sequence is correct.
39738 ** (3) A shared lock is always held when a reserve lock is requested.
39744 /* This mutex is needed because pFile->pInode is shared across threads
39759 /* If a SHARED lock is requested, and some thread using this PID already
39775 /* A PENDING lock is needed before acquiring a SHARED lock and before
39838 ** same process is still holding a shared lock. */
39841 /* The request was for a RESERVED or EXCLUSIVE lock. It is
39842 ** assumed that there is a SHARED or greater lock on the file
39913 ** If the locking level of the file descriptor is already at or below
39914 ** the requested locking level, this routine is a no-op.
39916 ** If handleNFSUnlock is true, then on downgrading an EXCLUSIVE_LOCK to SHARED
39917 ** the byte range is divided into 2 parts and the first part is unlocked then
39918 ** set to a read lock, then the other part is simply unlocked. This works
39920 ** remove the write lock on a region when a read lock is set.
39947 ** file changed. If the transaction counter is not updated,
39958 ** write lock until the rest is covered by a read lock:
40015 ** process is holding an incompatible lock. If it does, this
40016 ** indicates that the other process is not following the locking
40079 ** If the locking level of the file descriptor is already at or below
40080 ** the requested locking level, this routine is a no-op.
40100 ** It is *not* necessary to hold the mutex when this routine is called,
40150 /* unixFile.pInode is always valid here. Otherwise, a different close
40159 ** when the last lock is cleared.
40177 ** Of the various locking implementations available, this is by far the
40178 ** simplest: locking is ignored. No attempt is made to lock the database
40181 ** This locking mode is appropriate for use on read-only databases
40185 ** database connections. But there is a serious risk of database
40186 ** corruption if this locking mode is used in situations where multiple
40222 ** (1) There is zero concurrency. A single reader blocks all other
40228 ** Nevertheless, a dotlock is an appropriate locking mode for use if no
40229 ** other locking strategy is available.
40244 ** This routine checks if there is a RESERVED lock held on the specified
40245 ** file by this or any other process. If such a lock is held, set *pResOut
40246 ** to a non-zero value otherwise *pResOut is set to zero. The return value
40247 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
40250 ** variation of CheckReservedLock(), *pResOut is set to true if any lock
40251 ** is held on the file and false if the file is unlocked.
40301 ** to do is adjust our internal record of the lock level.
40339 ** If the locking level of the file descriptor is already at or below
40340 ** the requested locking level, this routine is a no-op.
40402 ** flock() locking is like dot-file locking in that the various
40406 ** still works when you do this, but concurrency is reduced since
40409 ** Omit this section if SQLITE_ENABLE_LOCKING_STYLE is turned off
40428 ** This routine checks if there is a RESERVED lock held on the specified
40429 ** file by this or any other process. If such a lock is held, set *pResOut
40430 ** to a non-zero value otherwise *pResOut is set to zero. The return value
40431 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
40519 /* if we already have a lock, it is exclusive.
40554 ** If the locking level of the file descriptor is already at or below
40555 ** the requested locking level, this routine is a no-op.
40605 ** Named semaphore locking is only supported on VxWorks.
40607 ** Semaphore locking is like dot-lock and flock in that it really only
40615 ** This routine checks if there is a RESERVED lock held on the specified
40616 ** file by this or any other process. If such a lock is held, set *pResOut
40617 ** to a non-zero value otherwise *pResOut is set to zero. The return value
40618 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
40692 /* if we already have a lock, it is exclusive.
40717 ** If the locking level of the file descriptor is already at or below
40718 ** the requested locking level, this routine is a no-op.
40773 ** Named semaphore locking is only available on VxWorks.
40782 ** AFP is the Apple Filing Protocol. AFP is a network filesystem found
40812 ** This is a utility for setting or clearing a bit-range lock on an
40858 ** This routine checks if there is a RESERVED lock held on the specified
40859 ** file by this or any other process. If such a lock is held, set *pResOut
40860 ** to a non-zero value otherwise *pResOut is set to zero. The return value
40861 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
40943 /* If there is already a lock of this type or more restrictive on the
40953 /* Make sure the locking sequence is correct
40956 ** (3) A shared lock is always held when a reserve lock is requested.
40962 /* This mutex is needed because pFile->pInode is shared across threads
40977 /* If a SHARED lock is requested, and some thread using this PID already
40992 /* A PENDING lock is needed before acquiring a SHARED lock and before
41046 ** same process is still holding a shared lock. */
41049 /* The request was for a RESERVED or EXCLUSIVE lock. It is
41050 ** assumed that there is a SHARED or greater lock on the file
41076 /* Can't reestablish the shared lock. Sqlite can't deal, this is
41111 ** If the locking level of the file descriptor is already at or below
41112 ** the requested locking level, this routine is a no-op.
41140 ** file changed. If the transaction counter is not updated,
41222 ** the last lock is cleared.
41237 ** The code above is the AFP lock implementation. The code is specific
41239 ** is available. If you don't compile for a mac, then the "unix-afp"
41240 ** VFS is not available.
41253 ** If the locking level of the file descriptor is already at or below
41254 ** the requested locking level, this routine is a no-op.
41262 ** The code above is the NFS lock implementation. The code is specific
41264 ** is available.
41284 ** is set before returning.
41347 /* If this is a database file (not a journal, super-journal or temp
41455 ** is set before returning.
41477 /* If this is a database file (not a journal, super-journal or temp
41490 ** has changed. If the transaction counter is modified, record that
41548 ** Count the number of fullsyncs and normal syncs. This is used to test
41567 ** the F_FULLFSYNC macro is defined. F_FULLFSYNC is currently
41579 ** unix systems. The following procedure is an attempt to make
41582 ** The SQLITE_NO_SYNC macro disables all fsync()s. This is useful
41588 ** SQLite sets the dataOnly flag if the size of the file is unchanged.
41589 ** The idea behind dataOnly is that it should only write the file content
41590 ** to disk, not the inode. We only set dataOnly if the file size is
41591 ** unchanged since the file size is part of the inode. However,
41594 ** and fsync(), Ted tells us, is that fdatasync() will not flush the
41597 ** as far as SQLite is concerned, an fdatasync() is always adequate.
41598 ** So, we always use fdatasync() if it is available, regardless of
41605 ** the one below. It is replicated here solely to avoid cluttering
41620 ** FULLSYNC. This is used during testing to verify that this procedure
41628 /* If we compiled with the SQLITE_NO_SYNC flag, then syncing is a
41650 ** the fcntl call every time sync is called.
41676 ** If successful, *pFd is set to the opened file descriptor and
41677 ** SQLITE_OK is returned. If an error occurs, either SQLITE_NOMEM
41678 ** or SQLITE_CANTOPEN is returned and *pFd is set to an undefined
41681 ** The directory file descriptor is used for only one thing - to
41688 ** chromium sandbox. Opening a directory is a security risk (we are
41694 ** If SQLITE_OK is returned, the caller is responsible for closing
41724 ** file data is synced.
41747 ** line is to test that doing so does not cause any problems.
41761 ** is set. This is a one-time occurrence. Many systems (examples: AIX)
41849 ** layers, we need to report this file size as zero even though it is
41867 ** This function is called to handle the SQLITE_FCNTL_SIZE_HINT
41869 ** (rounded up to the next chunk-size). If the database is already
41870 ** nBytes or larger, this routine is a no-op.
41885 /* The code below is handling the return value of osFallocate()
41886 ** correctly. posix_fallocate() is defined to "returns zero on success,
41898 ** This is a similar technique to that used by glibc on systems
41936 ** If *pArg is initially negative then this is a query. Set *pArg to
41937 ** 1 or 0 depending on whether or not bit mask of pFile->ctrlFlags is set.
41939 ** If *pArg is 0 or 1, then clear or set the mask bit of pFile->ctrlFlags.
42044 ** to mmap(). Restrict its value to 2GB if (size_t) is not at least a
42063 ** a rollback and that the database is therefore unchanged and
42064 ** it hence it is OK for the transaction change counter to be
42092 ** If pFd->sectorSize is non-zero when this function is called, it is a
42144 ** so it is ordered */
42154 ** so it is ordered */
42163 ** so it is ordered */
42171 ** so it is ordered */
42179 ** so it is ordered */
42200 ** the specified file. This is almost always 512 bytes, but may be
42217 ** This VFS is set up to return SQLITE_IOCAP_POWERSAFE_OVERWRITE by default.
42218 ** However, that choice is controversial since technically the underlying
42221 ** written might end up being altered.) However, non-PSOW behavior is very,
42223 ** of required I/O for journaling, since a lot of padding is eliminated.
42224 ** Hence, while POWERSAFE_OVERWRITE is on by default, there is a file-control
42260 ** of this unixShmNode object. In other words, each wal-index is opened
42263 ** Each unixShmNode object is connected to a single unixInodeInfo object.
42268 ** and the unixShmNode object is created only when needed.
42275 ** The following fields are read-only after the object is created:
42281 ** unixMutexHeld() is true when reading or writing any other field
42286 ** SQLITE_SHM_NLOCK slots. If the aLock[] entry is set to 0, then no
42287 ** locks are held by the process on this slot. If it is set to -1, then
42289 ** value is set to a positive value, then it is the number of shared
42293 ** Normally, when SQLITE_ENABLE_SETLK_TIMEOUT is not defined, mutex
42294 ** pShmMutex is used to protect the aLock[] array and the right to
42297 ** If SQLITE_ENABLE_SETLK_TIMEOUT is defined though, we use an array
42328 ** The following fields are initialized when this object is created and
42357 ** SQLite error code. The final value of *piOut is undefined in this
42389 ** Locks block if the mask is exactly UNIX_SHM_C and are non-blocking
42481 ** Usually, this is 1. The exception seems to be systems that are configured
42496 ** This is not a VFS shared-memory method; it is a utility function called
42534 ** If the DMS cannot be locked because this is a readonly_shm=1
42543 ** on the DMS byte. If it indicates that another process is holding
42547 ** Or, if no other process is holding any lock, then this process
42548 ** is the first to open it. In this case take an EXCLUSIVE lock on the
42552 ** If another process is holding an EXCLUSIVE lock on the DMS byte,
42573 ** immediately, it means some other connection is truncating the
42588 ** help detect if a -shm file truncation is legitimate or is the work
42609 ** The file used to implement shared-memory is in the same directory
42612 ** is "/home/user1/config.db" then the file that is created and mmapped
42615 ** Another approach to is to use files in /dev/shm or /dev/tmp or an
42617 ** from the database file is used, then differing access permissions
42627 ** result. The SQLITE_SHM_DIRECTORY compile-time option is considered
42634 ** If the original database file (pDbFd) is using the "unix-excl" VFS
42635 ** that means that an exclusive lock is held on the database file and
42638 ** file is created. The shared memory will be simulated with heap memory.
42668 ** a new *-shm file is created, an attempt will be made to create it
42734 /* If this process is running as root, make sure that the SHM file
42735 ** is owned by the same user that owns the original database. Otherwise,
42756 ** new (struct unixShm) object to the pShmNode has been set. All that is
42757 ** left to do is to link the new object into the linked list starting
42776 ** This function is called to obtain a pointer to region iRegion of the
42778 ** are numbered starting from zero. Each shared-memory region is szRegion
42781 ** If an error occurs, an error code is returned and *pp is set to NULL.
42783 ** Otherwise, if the bExtend parameter is 0 and the requested shared-memory
42785 ** separate process), then *pp is set to NULL and SQLITE_OK returned. If
42786 ** bExtend is non-zero and the requested shared-memory region has not yet
42787 ** been allocated, it is allocated by this function.
42789 ** If the shared-memory region has already been allocated or is allocated by
42790 ** this call as described above, then it is mapped into this processes
42791 ** address space (if it is not already), *pp is set to point to the mapped
42838 /* The requested region is not mapped into this processes address space.
42839 ** Check to see if it has been allocated (i.e. if the wal-index file is
42848 /* The requested memory region does not exist. If bExtend is set to
42855 /* Alternatively, if bExtend is true, extend the file. Do this by
42932 ** is to be used in an assert(). e.g.
42967 ** Note that the relationship between SHARED and EXCLUSIVE locks is a little
43010 ** In other words, if this is a blocking lock, none of the locks that
43014 ** It is not permitted to block on the RECOVER lock.
43028 /* Check if there is any work to do. There are three cases:
43031 ** b) An shared lock where the requested lock is not already held
43032 ** c) An exclusive lock where the requested lock is not already held
43035 ** This is assert()ed below.
43046 ** this is an attempt on an exclusive lock use sqlite3_mutex_try(). If any
43047 ** other thread is holding this mutex, then it is either holding or about
43082 /* If this is a SHARED lock being unlocked, it is possible that other
43084 ** this case, set bUnlock to 0 so that the posix lock is not removed
43108 /* An exclusive lock is held by some other connection. BUSY. */
43187 ** storage if deleteFlag is true.
43189 ** If there is no shared memory associated with the connection then this
43190 ** routine is a harmless no-op.
43247 ** If it is currently memory mapped, unmap file pFd.
43261 ** descriptor pFd to nNew bytes. Any existing mapping is discarded.
43269 ** If unsuccessful, an error message is logged via sqlite3_log() and
43331 /* If pNew is still NULL, try to create an entirely new mapping. */
43352 ** is already mapped, the existing mapping is replaced by the new). Or, if
43354 ** outstanding xFetch() references to it, this function is a no-op.
43356 ** If parameter nByte is non-negative, then it is the requested size of
43357 ** the mapping to create. Otherwise, if nByte is less than zero, then the
43358 ** requested size is the size of the file on disk. The actual size of the
43359 ** created mapping is either the requested size or the value configured
43360 ** using SQLITE_FCNTL_MMAP_LIMIT, whichever is smaller.
43362 ** SQLITE_OK is returned if no error occurs (even if the mapping is not
43398 ** value of *pp is undefined in this case.
43411 /* Ensure that there is always at least a 256 byte buffer of addressable
43412 ** memory following the returned page. If the database is corrupt,
43414 ** but 256 is safe, round, number). */
43430 ** If the third argument is non-NULL, then this function releases a
43435 ** Or, if the third argument is NULL, then this function is being called
43445 ** xFetch references. Or, if p!=0 (meaning it is an xFetch reference),
43476 ** of "finder" functions. A finder-function is used to locate the appropriate
43482 ** object. The only interesting finder-function is autolockIoFinder, which
43493 ** A pointer to the F pointer is used as the pAppData value for VFS
43564 1, /* shared memory is disabled */
43576 1, /* shared memory is disabled */
43589 1, /* shared memory is disabled */
43602 1, /* shared memory is disabled */
43612 ** The proxy locking method is a "super-method" in the sense that it
43616 ** proxy locking is located much further down in the file. But we need
43628 1, /* shared memory is disabled */
43637 /* nfs lockd on OSX 10.3+ doesn't clear write locks when a read lock is set */
43642 1, /* shared memory is disabled */
43657 ** This is for MacOSX only.
43720 ** locking works. If it does, then that is what is used. If it does not
43735 /* Test if fcntl() is supported and use POSIX style locks.
43815 ** proxyLock activation is possible (remote proxy is based on db name)
43816 ** zFilename remains valid until file is closed, to support */
43836 ** Scenario (b) may only occur if the process is holding no other
43839 ** findInodeInfo(). If this is the case, it is quite safe to close
43840 ** handle h - as it is guaranteed that no posix locks will be released
43844 ** implicit assumption here is that if fstat() fails, things are in
43863 /* NB: zFilename exists and remains valid until the file is closed
43994 /* It's odd to simulate an io-error here, but really this is just
44027 ** if SQLITE_PREFER_PROXY_LOCKING is defined.
44040 ** other file descriptor open on the same file is holding a file-lock.
44045 ** If a suitable file descriptor is found, then it is returned. If no
44046 ** such file descriptor is located, -1 is returned.
44053 ** but because no way to test it is currently available. It is better
44061 /* A stat() call may fail for various reasons. If this happens, it is
44063 ** For this reason, if an error occurs in the stat() call here, it is
44064 ** ignored and -1 is returned. The caller will try to open a new file
44117 ** This function is called by unixOpen() to determine the unix permissions
44118 ** to create new files with. If no error occurs, then SQLITE_OK is returned
44119 ** and a value suitable for passing as the third argument to open(2) is
44120 ** written to *pMode. If an IO error occurs, an SQLite error code is
44121 ** returned and the value of *pMode is not modified.
44126 ** But if the file being opened is a WAL or regular journal file, then
44132 ** If the SQLITE_ENABLE_8_3_NAMES option is enabled, then the
44133 ** original filename is unavailable. But 8_3_NAMES is only used for
44152 /* zPath is a path to a WAL or journal file. The following block derives
44161 ** where NN is a decimal number. The NN naming schemes are
44183 /* If this is a main database file and the file was opened using a URI
44218 sqlite3_vfs *pVfs, /* The VFS for which this is the xOpen method */
44246 ** is called the directory file descriptor will be fsync()ed and close()d.
44254 /* If argument zPath is a NULL pointer, this function is required to open
44263 ** (b) if CREATE is set, then READWRITE must also be set, and
44264 ** (c) if EXCLUSIVE is set, then CREATE must also be set.
44265 ** (d) if DELETEONCLOSE is set, then CREATE must also be set.
44286 /* Detect a pid change and reset the PRNG. There is a race condition
44321 /* If zName is NULL, the upper layer is requesting a temp file. */
44335 ** open(). These must be calculated even if open() is not called, as
44359 /* If unable to create a journal because the directory is not
44379 ** same as the owner of the database file. Try to ensure that this is
44383 ** behinds a journal/WAL that is owned by root and hence make the
44387 ** (probably because SQLite is configured to use 8+3 filename mode) and
44493 ** Delete the file at zPath. If the dirSync argument is true, fsync()
44539 ** SQLITE_ACCESS_READWRITE: Return 1 if the file is read and writable.
44540 ** SQLITE_ACCESS_READONLY: Return 1 if the file is readable.
44664 ** is stored as a nul-terminated string in the buffer pointed to by
44668 ** (in this case, MAX_PATHNAME bytes). The full-path is written to
44712 ** message is available, it is written to zBufOut. If no error message
44713 ** is available, zBufOut is left unmodified and SQLite uses a default
44730 ** returns a void* which is really a pointer to a function. So how do we
44733 ** Variable x below is defined to be a pointer to a function taking
44739 ** This work-around is unlikely to work correctly on any system where
44753 #else /* if SQLITE_OMIT_LOAD_EXTENSION is defined: */
44775 ** When testing, initializing zBuf[] to zero is all we do. That means
44804 ** The argument is the number of microseconds we want to sleep.
44805 ** The return value is the number of microseconds of sleep actually
44819 ** usleep() is available) in order to bypass the use of nanosleep() */
44838 ** The following variable, if set to a non-zero value, is interpreted as
44839 ** the number of seconds since 1970 and is used to set the result of
44901 ** The xGetLastError() method is designed to return a better
44903 ** during SQLite operation. Only the integer return code is currently
44921 ** Proxy locking is a "uber-locking-method" in this sense: It uses the
44922 ** other locking methods on secondary lock files. Proxy locking is a
44924 ** this reason, the division that implements of proxy locking is deferred
44939 ** address in the shared range is taken for a SHARED lock, the entire
44940 ** shared range is taken for an EXCLUSIVE lock):
44949 ** cache exposes a cache coherency problem that is present on all OS X
44958 ** changes the way database access is controlled by limiting access to a
44979 ** Specifying ":auto:" means that if there is a conch file with a matching
44983 ** actual proxy file name is generated from the name and path of the
44989 ** Once a lock proxy is configured for a database connection, it can not
44991 ** the above APIs (assuming the conch file is not being held by another
45009 ** proxy path against the values stored in the conch. The conch file is
45011 ** is patterned after the database file name as ".<databasename>-conch".
45013 ** host ID and/or proxy path, then the lock is escalated to an exclusive
45014 ** lock and the conch file contents is updated with the host ID and proxy
45015 ** path and the lock is downgraded to a shared lock again. If the conch
45016 ** is held by another process (with a shared lock), the exclusive lock
45017 ** will fail and SQLITE_BUSY is returned.
45024 ** Requesting the lock proxy does not immediately take the conch, it is
45025 ** only taken when the first request to lock database file is made.
45029 ** the connection to the database is closed.
45057 ** lock proxy files, only used when LOCKPROXYDIR is not set.
45065 ** sqlite_file_control API is not affected by SQLITE_FORCE_PROXY_LOCKING).
45069 ** Proxy locking is only available on MacOSX
45084 int conchHeld; /* 1 if the conch is held, -1 if lockless */
45091 ** The proxy lock file path for the database at dbPath is written into lPath,
45173 ** The caller is responsible not only for closing the file descriptor
45190 ** 2. if that fails, and this is a lock file (not-conch), try creating
45226 return SQLITE_IOERR_LOCK; /* even though it is the conch */
45309 ** it back. The newly created file's file descriptor is assigned to the
45310 ** conch file structure and finally the original conch file descriptor is
45387 * 2nd try: fail if the mod time changed or host id is different, wait
45446 ** lockPath is non-NULL, the host ID and lock file path must match. A NULL
45521 /* create a copy of the lock path if the conch is taken */
45543 /* create a copy of the lock path _only_ if the conch is taken */
45554 ** same process is still holding a shared lock. */
45698 ** The caller is responsible for ensuring that the allocated memory
45699 ** space is eventually freed.
45701 ** *pConchPath is set to NULL if a memory allocation error occurs.
45749 /* nothing to do if the path is NULL, :auto: or matches the existing path */
45770 ** pFile is a file that has been opened by a prior xOpen call. dbPath
45771 ** is a string buffer at least MAXPATHLEN+1 characters in size.
45837 ** (c) the file system is read-only, then enable no-locking access.
45868 /* all memory is allocated, proxys are created and assigned,
45917 /* turn off proxy locking - not supported. If support is added for
45919 ** the journal mode is WAL mode.
45962 ** This routine checks if there is a RESERVED lock held on the specified
45963 ** file by this or any other process. If such a lock is held, set *pResOut
45964 ** to a non-zero value otherwise *pResOut is set to zero. The return value
45965 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
45975 }else{ /* conchHeld < 0 is lockless */
46016 /* conchHeld < 0 is lockless */
46027 ** If the locking level of the file descriptor is already at or below
46028 ** the requested locking level, this routine is a no-op.
46040 /* conchHeld < 0 is lockless */
46090 ** The proxy locking style is intended for use with AFP filesystems.
46091 ** And since AFP is only supported on MacOSX, the proxy locking is also
46106 ** This routine is called once during SQLite initialization and by a
46108 ** necessarily been initialized when this routine is called, and so they
46114 ** The name of the VFS is NAME. The pAppData is a pointer to a pointer
46115 ** to the "finder" function. (pAppData is a pointer to a pointer because
46120 ** The FINDER parameter to this macro is the name of the pointer to the
46160 ** Note that the sqlite3_vfs.pNext field of the VFS object is modified
46161 ** by the SQLite core when the VFS is registered. So the following
46239 ** This routine is a no-op for unix.
46254 ** a legal notice, here is a blessing:
46262 ** This file contains code that is specific to Windows.
46265 #if SQLITE_OS_WIN /* This file is used for Windows only */
46268 ** Include code that is common to all os_*.c files
46309 ** Make sure at least one set of Win32 APIs is available.
46338 # define SQLITE_WIN32_GETVERSIONEX 0 /* GetVersionEx() is deprecated */
46340 # define SQLITE_WIN32_GETVERSIONEX 1 /* GetVersionEx() is current */
46345 ** Check to see if the CreateFileMappingA function is supported on the
46346 ** target system. It is unavailable when using "mincore.lib" on Win10.
46347 ** When compiling for Windows 10, always assume "mincore.lib" is in use.
46388 ** Maximum pathname length (in bytes) for Win32. The MAX_PATH macro is in
46421 ** This macro is used when a local variable is set to a value that is
46508 ** The winFile structure is a subclass of sqlite3_file* specific to the win32
46542 ** The winVfsAppData structure is used for the pAppData member for all of the
46549 BOOL bNoLock; /* Non-zero if locking is disabled. */
46555 #define WINFILE_RDONLY 0x02 /* Connection is read only */
46573 * If this is non-zero, an isolated heap will be created by the native Win32
46575 * setting has no effect when compiling for WinRT. By default, this is enabled
46579 * WARNING: It is important to note that when this setting is non-zero and the
46580 * winMemShutdown function is called (e.g. by the sqlite3_shutdown
46591 * This is the maximum possible initial size of the Win32-specific heap, in
46599 * This is the extra space for the initial size of the Win32-specific heap,
46618 * This is cache size used in the calculation of the initial size of the
46719 ** The following variable is (normally) set once and never changes
46720 ** thereafter. It records whether the operating system is Win9x
46724 ** 1: Operating system is Win9x.
46725 ** 2: Operating system is WinNT.
46741 ** This function is not available on Windows CE or WinRT.
46980 /* The GetProcAddressA() routine is only available on Windows CE. */
47367 ** is really just a macro that uses a compiler intrinsic (e.g. x64).
47368 ** So do not try to make this is into a redefinable interface.
47410 ** This is the xSetSystemCall() method of sqlite3_vfs for all of the
47412 ** system call pointer, or SQLITE_NOTFOUND if there is no configurable
47425 /* If no zName is given, restore all system calls to their default
47435 /* If zName is specified, operate on only the one system call
47454 ** Return the value of a system call. Return NULL if zName is not a
47455 ** recognized system call name. NULL is also returned if the system call
47456 ** is currently undefined.
47474 ** is the last system call or if zName is not the name of a valid
47536 ** destroy and recreate it. If the Win32 native heap is not isolated and/or
47625 ** milliseconds. This is equivalent to the Win32 Sleep() interface.
47658 ** Here is an interesting observation: Win95, Win98, and WinME lack
47661 ** this routine is used to determine if the host is Win95/98/ME or
47677 ** This function determines if the machine is running a version of Windows
47683 ** NOTE: The WinRT sub-platform is always assumed to be based on the NT
47752 if( !pPrior ) return; /* Passing NULL to HeapFree is undefined. */
47898 ** This routine is only called by sqlite3_config(), and therefore
47899 ** is not required to be threadsafe (it is not).
47923 ** Space to hold the returned string is obtained from sqlite3_malloc().
47949 ** Space to hold the returned string is obtained from sqlite3_malloc().
47976 ** Space to hold the returned string is obtained from sqlite3_malloc().
48005 ** Space to hold the returned string is obtained from sqlite3_malloc().
48032 ** Space to hold the returned string is obtained from sqlite3_malloc().
48050 ** Space to hold the returned string is obtained from sqlite3_malloc().
48066 ** This is a public wrapper for the winUtf8ToUnicode() function.
48082 ** This is a public wrapper for the winUnicodeToUtf8() function.
48098 ** This is a public wrapper for the winMbcsToUtf8() function.
48114 ** This is a public wrapper for the winMbcsToUtf8() function.
48130 ** This is a public wrapper for the winUtf8ToMbcs() function.
48146 ** This is a public wrapper for the winUtf8ToMbcs() function.
48162 ** This function is the same as sqlite3_win32_set_directory (below); however,
48206 ** This function is the same as sqlite3_win32_set_directory (below); however,
48228 ** argument is the name of the directory to use. The return value will be
48240 ** is zero if the error message fits in the buffer, or non-zero
48320 ** This function - winLogErrorAtLine() - is only ever called via the macro
48323 ** This routine is invoked after an error occurs in an OS function.
48374 ** The "winIoerrCanRetry1" macro is used to determine if a particular I/O
48375 ** error code obtained via GetLastError() is eligible to be retried. It
48377 ** non-zero if the error code is transient in nature and the operation
48382 ** is defined, it will be consulted only when the macro "winIoerrCanRetry1"
48383 ** returns zero. The "winIoerrCanRetry2" macro is completely optional and
48773 ** NOTE: Windows CE is handled differently here due its lack of the Win32
48804 ** NOTE: Windows CE is handled differently here due its lack of the Win32
48856 ** whether an error has actually occurred, it is also necessary to call
48905 ** It is reported that an attempt to close a handle might sometimes
48906 ** fail. This is a very unreasonable result, but Windows is notorious
49165 /* File truncation is a no-op if there are outstanding memory mapped
49166 ** pages. This is because truncating the file means temporarily unmapping
49170 ** if there is an active read cursor when the incremental vacuum occurs.
49171 ** No real harm comes of this - the database file is not corrupted,
49172 ** though some folks might complain that the file is bigger than it
49175 ** The only feasible work-around is to defer the truncation until after
49176 ** all references to memory-mapped content are closed. That is doable,
49237 ** Count the number of fullsyncs and normal syncs. This is used to test
49250 ** Used only when SQLITE_NO_SYNC is not defined.
49257 ** Used when SQLITE_NO_SYNC is not defined and by the assert() and/or
49272 ** line is to test that doing so does not cause any problems.
49289 /* If we compiled with the SQLITE_NO_SYNC flag, then syncing is a
49375 ** LOCKFILE_FAIL_IMMEDIATELY is undefined on some Windows systems.
49408 ** is Win9x or WinNT.
49416 ** NOTE: Windows CE is handled differently here due its lack of the Win32
49489 ** It is not possible to lower the locking level one step at a time. You
49504 /* If there is already a lock of this type or more restrictive on the
49519 /* Make sure the locking sequence is correct
49527 ** the PENDING_LOCK byte is temporary.
49536 /* Try 3 times to get the pending lock. This is needed to work
49540 ** copy this retry logic. It is a hack intended for Windows only.
49631 ** This routine checks if there is a RESERVED lock held on the specified
49632 ** file by this or any other process. If such a lock is held, return
49664 ** If the locking level of the file descriptor is already at or below
49665 ** the requested locking level, this routine is a no-op.
49667 ** It is not possible for this routine to fail if the second argument
49668 ** is NO_LOCK. If the second argument is SHARED_LOCK then this routine
49707 ** Of the various locking implementations available, this is by far the
49708 ** simplest: locking is ignored. No attempt is made to lock the database
49711 ** This locking mode is appropriate for use on read-only databases
49715 ** database connections. But there is a serious risk of database
49716 ** corruption if this locking mode is used in situations where multiple
49743 ** If *pArg is initially negative then this is a query. Set *pArg to
49744 ** 1 or 0 depending on whether or not bit mask of pFile->ctrlFlags is set.
49746 ** If *pArg is 0 or 1, then clear or set the mask bit of pFile->ctrlFlags.
49869 ** to MapViewOfFile(). Restrict its value to 2GB if (SIZE_T) is not at
49894 ** the specified file. This is almost always 512 bytes, but may be
49928 ** global mutex is used to protect the winLockInfo objects used by
49931 ** Function winShmMutexHeld() is used to assert() that the global mutex
49932 ** is held when required. This function is only used as part of assert()
49957 ** log-summary is opened only once per process.
49965 ** The following fields are read-only after the object is created:
49971 ** winShmMutexHeld() is true when reading or writing any other field
50010 ** The following fields are initialized when this object is created and
50050 /* Access to the winShmNode object is serialized by the caller */
50087 ** This is not a VFS shared-memory method; it is a utility function called
50137 ** If the DMS cannot be locked because this is a readonly_shm=1
50194 /* Look to see if there is an existing winShmNode that can be used.
50254 ** new (struct winShm) object to the pShmNode has been set. All that is
50255 ** left to do is to link the new object into the linked list starting
50277 ** storage if deleteFlag is true.
50443 ** This function is called to obtain a pointer to region iRegion of the
50445 ** are numbered starting from zero. Each shared-memory region is szRegion
50448 ** If an error occurs, an error code is returned and *pp is set to NULL.
50450 ** Otherwise, if the isWrite parameter is 0 and the requested shared-memory
50452 ** separate process), then *pp is set to NULL and SQLITE_OK returned. If
50453 ** isWrite is non-zero and the requested shared-memory region has not yet
50454 ** been allocated, it is allocated by this function.
50456 ** If the shared-memory region has already been allocated or is allocated by
50457 ** this call as described above, then it is mapped into this processes
50458 ** address space (if it is not already), *pp is set to point to the mapped
50498 /* The requested region is not mapped into this processes address space.
50499 ** Check to see if it has been allocated (i.e. if the wal-index file is
50510 /* The requested memory region does not exist. If isWrite is set to
50513 ** Alternatively, if isWrite is non-zero, use ftruncate() to allocate
50650 ** is already mapped, the existing mapping is replaced by the new). Or, if
50652 ** outstanding xFetch() references to it, this function is a no-op.
50654 ** If parameter nByte is non-negative, then it is the requested size of
50655 ** the mapping to create. Otherwise, if nByte is less than zero, then the
50656 ** requested size is the size of the file on disk. The actual size of the
50657 ** created mapping is either the requested size or the value configured
50658 ** using SQLITE_FCNTL_MMAP_SIZE, whichever is smaller.
50660 ** SQLITE_OK is returned if no error occurs (even if the mapping is not
50757 ** value of *pp is undefined in this case.
50773 /* Ensure that there is always at least a 256 byte buffer of addressable
50774 ** memory following the returned page. If the database is corrupt,
50776 ** but 256 is safe, round, number). */
50800 ** If the third argument is non-NULL, then this function releases a
50805 ** Or, if the third argument is NULL, then this function is being called
50814 ** xFetch references. Or, if p!=0 (meaning it is an xFetch reference),
50828 ** file while a mapping is held, then the following winUnmapfile() call
50829 ** is unnecessary can be omitted - potentially improving
50922 ** supports for filenames into UTF-8. Space to hold the result is
50943 ** is obtained from malloc and must be freed by the calling
50982 ** If sqlite3_temp_directory is defined, take the mutex and return true.
50984 ** If sqlite3_temp_directory is NULL (undefined), omit the mutex and
51009 /* It's odd to simulate an io-error here, but really this is just
51074 ** character, assume it is already a native Win32 path; otherwise,
51110 ** its name into UTF-8 (i.e. if it is UTF-16 right now).
51186 ** separator. If it does not and there is not enough space left to add
51196 ** Check that the output buffer is large enough for the temporary file
51201 ** If not, return SQLITE_ERROR. The number 17 is used here in order to
51232 ** Return TRUE if the named file is really a directory. Return false if
51233 ** it is something other than a directory, or if there is any kind of memory
51293 /* If argument zPath is a NULL pointer, this function is required to open
51323 ** (b) if CREATE is set, then READWRITE must also be set, and
51324 ** (c) if EXCLUSIVE is set, then CREATE must also be set.
51325 ** (d) if DELETEONCLOSE is set, then CREATE must also be set.
51357 /* If the second argument to this function is NULL, generate a
51398 /* SQLITE_OPEN_EXCLUSIVE is used to make sure that a new file is
51400 ** as it is usually understood.
51432 /* Reports from the internet are that performance is always
51433 ** better if FILE_FLAG_RANDOM_ACCESS is used. Ticket #2699. */
51587 ** will open a journal file shortly after it is created in order to do
51588 ** whatever it does. While this other process is holding the
51806 ** non-zero is returned from this function, the calling function must simply
51814 ** If the path name starts with a forward slash or a backslash, it is either
51816 ** "Unix" format on Windows. There is no easy way to differentiate between
51825 ** If the path name starts with a letter and a colon it is either a volume
51858 /* If this path name begins with "/X:" or "\\?\", where "X" is any
51943 /* It's odd to simulate an io-error here, but really this is just
52103 #else /* if SQLITE_OMIT_LOAD_EXTENSION is defined: */
52199 ** The following variable, if set to a non-zero value, is interpreted as
52200 ** the number of seconds since 1970 and is used to set the result of
52218 /* FILETIME structure is a 64-bit value representing the number of
52271 ** The idea is that this function works like a combination of
52273 ** strerror_r() on Unix). After an error is returned by an OS
52280 ** If the error message is too large for the supplied buffer,
52282 ** is zero if the error message fits in the buffer, or non-zero
52283 ** otherwise (if the message was truncated). If non-zero is returned,
52284 ** then it is not necessary to include the nul-terminator character
52288 ** on SQLite. It is fine to have an implementation that never
52296 ** However if an error message is supplied, it will be incorporated
52468 ** a legal notice, here is a blessing:
52476 ** This file implements an in-memory VFS. A database is held as a contiguous
52515 ** * .zFName is initialized when the object is created and afterwards
52516 ** is unchanged until the object is destroyed. So it can be accessed
52517 ** at any time as long as we know the object is not being destroyed,
52519 ** .pMutex is held or the object is not part of memdb_g.apMemStore[].
52522 ** SQLITE_MUTEX_STATIC_VFS1 mutex or while the object is not part
52526 ** or when the .nRef is less than zero and the object is not part of
52530 ** be changed (for resizing) when nMmap is zero.
52790 ** In rollback mode (which is always the case for memdb, as it does not
52791 ** support WAL mode) the truncate() method is only used to reduce
52914 ** This interface is only used for crash recovery, which does not
53085 ** files, none of which exist in memdb. So this routine is never used */
53087 ** Delete the file located at zPath. If the dirSync argument is true,
53098 ** is available, or false otherwise.
53117 ** to the pathname in zPath. zOut is guaranteed to point to a buffer
53367 ** Return true if the VFS is the memvfs.
53374 ** This routine is called when the extension is loaded.
53385 ** it in, to be safe, but it is marked as NO_TEST since there
53386 ** is no way to reach it under most builds. */
53399 ** a legal notice, here is a blessing:
53409 ** A bitmap is used to record which pages of a database file have been
53412 ** So the bitmap is usually sparse and has low cardinality.
53418 ** The size of the bitmap is fixed when the object is created.
53420 ** All bits are clear when the bitmap is created. Individual bits
53427 ** Bitvec object is the number of pages in the database file at the
53428 ** start of a transaction, and is thus usually less than a few thousand,
53468 ** A bitmap is an instance of the following structure.
53474 ** If iSize<=BITVEC_NBIT, then Bitvec.u.aBitmap[] is a straight
53475 ** bitmap. The least significant bit is bit 1.
53477 ** If iSize>BITVEC_NBIT and iDivisor==0 then Bitvec.u.aHash[] is
53480 ** Otherwise, the value i is redirected into one of BITVEC_NPTR
53485 ** N*iDivisor+1 and (N+1)*iDivisor. Each subbitmap is normalized
53489 u32 iSize; /* Maximum bit index. Max iSize is 4,294,967,296. */
53491 ** element. Max is BITVEC_NINT. For BITVEC_SZ of 512,
53495 /* Max iDivisor is max(u32) / BITVEC_NPTR + 1. */
53520 ** Check to see if the i-th bit is set. Return true or false.
53521 ** If p is NULL (if the bitmap has not been created) or if
53522 ** i is out of range, then return false.
53556 ** to get the memory needed to hold the sub-bitmap is the only
53559 ** The calling function must ensure that p is a valid Bitvec object
53560 ** and that the value for "i" is within range of the Bitvec object.
53561 ** Otherwise the behavior is undefined.
53601 /* available free spot. check to see if this is going to */
53704 ** The input is an array of integers that acts as a program
53709 ** There are 6 opcodes numbered from 0 through 5. 0 is the
53722 ** Opcode 5 is used to deliberately induce a fault in order to
53725 ** At the conclusion of the test the linear array is compared
53727 ** an error is returned. If they are the same, zero is returned.
53786 ** is found.
53813 ** a legal notice, here is a blessing:
53825 ** A complete page cache is an instance of this structure. Every
53829 ** A page cache entry is "clean" if it exactly matches what is currently
53830 ** on disk. A page is "dirty" if it has been modified and needs to be
53835 ** PgHdr.pDirtyNext and pDirtyPrev. The list is maintained in LRU order
53840 ** The PCache.pSynced variable is used to optimize searching for a dirty
53841 ** page to eject from the cache mid-transaction. It is better to eject
53843 ** Therefore, pSynced is maintained so that it *almost* always points
53845 ** clear PGHDR_NEED_SYNC flag or to a page that is older than this one
53869 ** When sqlite3PcacheTrace is 1, single line trace messages are issued.
53870 ** When sqlite3PcacheTrace is 2, a dump of the pcache showing all cache entries
53871 ** is displayed for many operations, resulting in a lot of output.
53915 ** Return 1 if pPg is on the dirty list for pCache. Return 0 if not.
53939 ** Check invariants on a PgHdr entry. Return true if everything is OK.
53940 ** Return false if any invariant is violated.
53942 ** This routine is for use inside of assert() statements only. For
53951 assert( pPg->pgno>0 || pPg->pPager==0 ); /* Page number is 1 or more */
53970 ** (1) Page X is journalled, and gets WRITEABLE and NEED_SEEK.
53971 ** (2) Page X moved to freelist, WRITEABLE is cleared
53972 ** (3) Page X reused, WRITEABLE is set again
53978 ** Another example is when the database page size is smaller than the
53979 ** disk sector size. When any page of a sector is journalled, all pages
54028 ** This is an optimization that allows sqlite3PcacheFetch() to skip
54055 /* If pSynced is NULL and this page has a clear NEED_SYNC flag, set
54056 ** pSynced to point to it. Checking the NEED_SYNC flag is an
54070 ** Wrapper around the pluggable caches xUnpin method. If the cache is
54071 ** being used for an in-memory database, this function is a no-op.
54082 ** Compute the number of pages of cache requested. p->szCache is the
54087 /* IMPLEMENTATION-OF: R-42059-47211 If the argument N is positive then the
54088 ** suggested cache size is set to N. */
54092 /* IMPLEMENTATION-OF: R-59858-46238 If the argument N is negative, then the
54093 ** number of cache pages is adjusted to be a number of pages that would
54109 /* IMPLEMENTATION-OF: R-26801-64137 If the xInit() method is NULL, then the
54110 ** built-in default page cache is used instead of the application defined
54131 ** has already been allocated and is passed in as the p pointer.
54135 ** szExtra is some extra space allocated for each page. The first
54136 ** 8 bytes of the extra space will be zeroed as the page is allocated,
54137 ** but remaining content will be uninitialized. Though it is opaque
54165 ** are no outstanding page references when this function is called.
54191 ** such an object is already in cache, or if a new one is created.
54198 ** If the createFlag is 0, then NULL is always returned if the page
54199 ** is not already in the cache. If createFlag is 1, then a new page
54200 ** is created only if that can be done without spilling dirty pages
54226 ** 1 Allocate a new page if doing so is inexpensive.
54228 ** 2 Allocate a new page even it doing so is difficult.
54243 ** If the sqlite3PcacheFetch() routine is unable to allocate a new
54264 ** cleared), but if that is not possible settle for any other
54268 ** flag is currently referenced, then the following may leave pSynced
54270 ** cleared). This is Ok, as pSynced is just an optimization. */
54301 ** This is a helper routine for sqlite3PcacheFetchFinish()
54304 ** initialized, this routine is invoked to do the initialization.
54305 ** This routine is broken out into a separate function since it
54355 ** Decrement the reference count on a page. If the page is clean and the
54356 ** reference count drops to 0, then it is made eligible for recycling.
54384 ** page pointed to by p is invalid.
54397 ** Make sure the page is marked as dirty. If it isn't dirty already,
54417 ** Make sure the page is marked as clean. If it isn't clean already,
54495 ** Drop every cache entry whose page number is greater than "pgno". The
54499 ** If there is a reference to page 1 and the pgno parameter passed to this
54500 ** function is 0, then the data area associated with page 1 is zeroed, but
54501 ** the page object is not dropped.
54523 if( ALWAYS(pPage1) ){ /* Page 1 is always available in cache, because
54586 ** One extra bucket is added to catch overflow in case something
54609 ** the input list. But that is impossible.
54636 ** This is not the total number of pages referenced, but the sum of the
54679 ** argument is zero. Return the effective cache-spill size, which will
54734 ** callback. This is only used if the SQLITE_CHECK_PAGES macro is
54751 ** a legal notice, here is a blessing:
54762 ** If the default page cache implementation is overridden, then neither of
54771 ** The database page content is up front (so that buffer overreads tend to
54773 ** is the extension added by the btree.c module containing information such
54774 ** as the database page number and how that database page is used. PgHdr
54775 ** is added by the pcache.c layer and contains information used to keep track
54776 ** of which pages are "dirty". PgHdr1 is an extension added by this
54777 ** module (pcache1.c). The PgHdr1 header is a subclass of sqlite3_pcache_page.
54797 ** with this module. Information is passed back and forth as PgHdr1 pointers.
54811 ** The third case is a chunk of heap memory (defaulting to 100 pages worth)
54812 ** that is allocated when the page cache is created. The size of the local
54817 ** If N is positive, then N pages worth of memory are allocated using a single
54818 ** sqlite3Malloc() call and that memory is used for the first N pages allocated.
54819 ** Or if N is negative, then -1024*N bytes of memory are allocated and used
54823 ** (3) is exhausted, subsequent allocations fail over to the general-purpose
54838 ** Each cache entry is represented by an instance of the following
54839 ** structure. A buffer of PgHdr1.pCache->szPage bytes is allocated
54840 ** directly before this structure and is used to cache the page content.
54842 ** When reading a corrupt database file, it is possible that SQLite might
54845 ** object is positioned immediately after the page buffer to serve as an
54850 ** pointers must be either 4 or 8-byte aligned). As this structure is located
54851 ** in memory directly after the associated page data, if the database is
54853 ** read part of this structure before the corruption is detected. This
54854 ** can cause a valgrind error if the uninitialized gap is accessed. Using u16
54855 ** ensures there is no such gap, and therefore no bytes of uninitialized
54867 u16 isAnchor; /* This is the PGroup.lru element */
54872 /* NB: pLruPrev is only valid if pLruNext!=0 */
54876 ** A page is pinned if it is not on the LRU list. To be "pinned" means
54877 ** that the page is in active use and must not be deallocated.
54882 /* Each page cache (or PCache) belongs to a PGroup. A PGroup is a set
54884 ** pages when they are under memory pressure. A PGroup is an instance of
54889 ** (1) Every PCache is the sole member of its own PGroup. There is
54892 ** (2) There is a single global PGroup that all PCaches are a member
54897 ** and is therefore often faster. Mode 2 requires a mutex in order to be
54900 ** For mode (1), PGroup.mutex is NULL. For mode (2) there is only a single
54901 ** PGroup which is the pcache1.grp global variable and its mutex is
54913 /* Each page cache is an instance of the following object. Every
54916 ** is an instance of this object.
54924 ** cache is created and are never changed thereafter. nMax may be
54933 int bPurgeable; /* True if cache is purgeable */
54941 ** when the accessor is holding the PGroup mutex.
54983 ** (2) even if an incorrect value is read, no great harm is done since this
54984 ** is really just an optimization. */
54990 ** alias "pcache1". This ensures that the WSD emulation is used when
55013 ** This function is called during initialization if a static buffer is
55018 ** This routine is called from sqlite3_initialize() and so it is guaranteed
55019 ** to be serialized already. There is no need for further mutexing.
55084 ** such buffer exists or there is no space left in it, this function falls
55107 /* Memory is not available in the SQLITE_CONFIG_PAGECACHE pool. Get
55190 /* The group mutex must be released before pcache1Alloc() is called. This
55191 ** is because it might call sqlite3_release_memory(), which assumes that
55192 ** this mutex is not held. */
55256 ** it is desirable to avoid allocating a new page cache entry because
55261 ** Or, the heap is used for all page cache memory but the heap is
55262 ** under memory pressure, then again it is desirable to avoid
55278 ** This function is used to resize the hash table used by the cache passed
55281 ** The PCache mutex must be held when this function is called.
55318 ** This function is used internally to remove the page pPage from the
55319 ** PGroup LRU list, if is part of it. If pPage is not part of the PGroup
55320 ** LRU list, then this function is a no-op.
55322 ** The PGroup mutex must be held when this function is called.
55334 ** No need to clear pLruPrev as it is never accessed if pLruNext is 0 */
55344 ** (PCache1.apHash structure) that it is currently stored in.
55345 ** Also free the page if freePage is true.
55347 ** The PGroup mutex must be held when this function is called.
55390 ** The PCache mutex must be held when this function is called.
55396 TESTONLY( int nPage = 0; ) /* To assert pCache->nPage is correct */
55403 ** cache, then there is no point in scanning the entire hash table.
55410 /* This is the general case where many pages are being removed.
55411 ** It is necessary to scan the entire hash table */
55450 ** The pcache1.separateCache variable is true if each PCache has its own
55451 ** private PGroup (mode-1). pcache1.separateCache is false if the single
55452 ** PGroup in pcache1.grp is used for all page caches (mode-2).
55629 /* Step 3: Abort if createFlag is 1 but the cache is nearly full */
55679 ** No need to clear pLruPrev since it is not accessed when pLruNext==0 */
55696 ** page. 1 means allocate a new page if space is easily available. 2
55700 ** database) there is really no difference between createFlag 1 and 2. So
55707 ** 1. Regardless of the value of createFlag, the cache is searched for a
55708 ** copy of the requested page. If one is found, it is returned.
55710 ** 2. If createFlag==0 and the page is not already in the cache, NULL is
55713 ** 3. If createFlag is 1, and the page is not already in the cache, then
55717 ** (a) the number of pages pinned by the cache is greater than
55720 ** (b) the number of pages pinned by the cache is greater than
55724 ** 4. If none of the first three conditions apply and the cache is marked
55725 ** as purgeable, and if one of the following is true:
55727 ** (a) The number of pages allocated for the cache is already
55730 ** (b) The number of pages allocated for all purgeable caches is
55734 ** (c) The system is under memory pressure and wants to avoid
55737 ** then attempt to recycle a page from the LRU list. If it is the right
55743 ** There are two versions of this routine. pcache1FetchWithMutex() is
55744 ** the general case. pcache1FetchNoMutex() is a faster implementation for
55745 ** the common case where pGroup->mutex is NULL. The pcache1Fetch() wrapper
55761 ** If the page was not in the hash table and createFlag is 0, abort.
55836 /* It is an error to call this function if the page is already
55871 assert( iOld!=iNew ); /* The page number really is changing */
55875 assert( pcache1FetchNoMutex(p, iOld, 0)==pPage ); /* pPg really is iOld */
55936 ** This function is called during initialization (sqlite3_initialize()) to
55974 ** This function is called to free superfluous dynamically allocated memory
55978 ** nReq is the number of bytes of memory required. Once this much has
55979 ** been released, the function returns. The return value is the total number
56006 ** This function is used by test procedures to inspect the internal state
56034 ** a legal notice, here is a blessing:
56044 ** The RowSet object is a collection of rowids. Rowids
56049 ** After all inserts are finished, it is possible to extract the
56063 ** TEST checks to see if an element is already in the RowSet. SMALLEST
56066 ** The INSERT primitive might allocate additional memory. Memory is
56067 ** allocated in chunks so most INSERTs do no allocation. There is an
56068 ** upper bound on the size of allocated memory. No memory is freed
56076 ** The initial batch number is zero, so if the very first TEST contains
56080 ** that is attempted.
56082 ** The cost of an INSERT is roughly constant. (Sometimes new memory
56084 ** batch number is O(NlogN) where N is the number of elements in the RowSet.
56085 ** The cost of a TEST using the same batch number is O(logN). The cost
56086 ** of the first SMALLEST is O(NlogN). Second and subsequent SMALLEST
56087 ** primitives are constant time. The cost of DESTROY is O(N).
56108 ** Each entry in a RowSet is an instance of the following object.
56110 ** This same object is reused to store a linked list of trees of RowSetEntry
56112 ** in the list, pLeft points to the tree, and v is unused. The
56125 ** when the RowSet is destroyed.
56152 #define ROWSET_SORTED 0x01 /* True if RowSet.pEntry is sorted */
56178 ** the RowSet has allocated over its lifetime. This routine is
56198 ** the RowSet has allocated over its lifetime. This routine is
56207 ** Allocate a new RowSetEntry object that is associated with the
56211 ** In an OOM situation, the RowSet.db->mallocFailed flag is set and this
56217 /* We could allocate a fresh RowSetEntry each time one is needed, but it
56218 ** is more efficient to pull a preallocated entry from the pool */
56236 ** The mallocFailed flag of the database connection is set if a
56243 /* This routine is never called after sqlite3RowSetNext() */
56330 ** The input, pIn, is a binary tree (or subtree) of RowSetEntry objects.
56381 ** is still generated without this branch, but the tree is wildly
56386 /* It is safe to always return here, but the resulting tree
56427 ** 0 if the RowSet is already empty.
56467 ** If this is the first test of a new batch and if there exist entries
56474 /* This routine is never called after sqlite3RowSetNext() */
56539 ** a legal notice, here is a blessing:
56546 ** This is the implementation of the page cache subsystem or "pager".
56548 ** The pager is used to access a database disk file. It implements
56550 ** is separate from the database file. The pager also implements file
56553 ** another is writing.
56563 ** a legal notice, here is a blessing:
56612 ** There is one object of this type for each pager.
56624 ** snapshot is like a read-transaction. It is the state of the database
56633 /* Read a page from the write-ahead log, if it is present. */
56637 /* If the WAL is not empty, return the size of the database. */
56684 /* Return true if the argument is non-NULL and the WAL module is using
56685 ** heap-memory for the wal-index. Otherwise, if the argument is NULL or the
56686 ** WAL module is using shared-memory, return false.
56699 /* If the WAL file is not empty, return the number of bytes of content
56730 ** Within this comment block, a page is deemed to have been synced
56731 ** automatically as soon as it is written when PRAGMA synchronous=OFF.
56732 ** Otherwise, the page is not synced until the xSync method of the VFS
56733 ** is called successfully on the file containing the page.
56735 ** Definition: A page of the database file is said to be "overwriteable" if
56744 ** (c) The page number is greater than the largest page that existed in
56747 ** (1) A page of the database file is never overwritten unless one of the
56752 ** (b) The atomic page write optimization is enabled, and the entire
56771 ** (6) If a super-journal file is used, then all writes to the database file
56782 ** journal is rolled back, the resulting database file will be logically
56785 ** (8) When a transaction is rolled back, the xTruncate method of the VFS
56786 ** is called to restore the database file to the same size it was at
56788 ** method is a no-op, but that does not change the fact the SQLite will
56791 ** (9) Whenever the database file is modified, at least one bit in the range
56799 ** (11) A database file is well-formed at the beginning and at the conclusion
56802 ** (12) An EXCLUSIVE lock is held on the database file when writing to
56805 ** (13) A SHARED lock is held on the database file while reading any
56826 ** associated file-descriptor is returned. FILEHANDLEID() takes an sqlite3_file
56872 ** The pager starts up in this state. Nothing is guaranteed in this
56873 ** state - the file may or may not be locked and the database size is
56876 ** * No read or write transaction is active.
56883 ** rollback (non-WAL) mode are met. Unless the pager is (or recently
56884 ** was) in exclusive-locking mode, a user-level read transaction is
56885 ** open. The database size is known in this state.
56889 ** OPEN after the read-transaction is completed. However a connection
56891 ** this state even after the read-transaction is closed. The only way
56893 ** is via the ERROR state (see below).
56896 ** * A SHARED or greater lock is held on the database file.
56898 ** transaction is not active). The dbOrigSize and dbFileSize variables
56900 ** * If the database is a WAL database, then the WAL connection is open.
56901 ** * Even if a read-transaction is not open, it is guaranteed that
56902 ** there is no hot-journal in the file-system.
56907 ** is first opened on the database. In WRITER_LOCKED state, all locks
56912 ** BEGIN EXCLUSIVE) EXCLUSIVE lock is obtained on the database file when
56913 ** moving to this state, but the journal file is not written to or opened
56914 ** to in this state. If the transaction is committed or rolled back while
56915 ** in WRITER_LOCKED state, all that is required is to unlock the database
56918 ** IN WAL mode, WalBeginWriteTransaction() is called to lock the log file.
56919 ** If the connection is running with locking_mode=exclusive, an attempt
56920 ** is made to obtain an EXCLUSIVE lock on the database file.
56922 ** * A write transaction is active.
56923 ** * If the connection is open in rollback-mode, a RESERVED or greater
56924 ** lock is held on the database file.
56925 ** * If the connection is open in WAL-mode, a WAL write transaction
56926 ** is open (i.e. sqlite3WalBeginWriteTransaction() has been successfully
56935 ** A pager moves from WRITER_LOCKED state to this state when a page is
56937 ** is opened (if it is not already open) and a header written to the
56940 ** * A write transaction is active.
56941 ** * A RESERVED or greater lock is held on the database file.
56942 ** * The journal file is open and the first header has been written
56953 ** * A write transaction is active.
56954 ** * An EXCLUSIVE or greater lock is held on the database file.
56955 ** * The journal file is open and the first header has been written
56962 ** It is not possible for a WAL connection to enter this state.
56967 ** by finalizing the journal file. Once in WRITER_FINISHED state, it is
56971 ** * A write transaction is active.
56972 ** * An EXCLUSIVE or greater lock is held on the database file.
56974 ** If no error occurred, all that remains is to finalize the journal to
56980 ** The ERROR state is entered when an IO or disk-full error (including
56999 ** outstanding transactions have been abandoned, the pager is able to
57002 ** is reloaded from disk (and, if necessary, hot-journal rollback performed)
57003 ** when a read-transaction is next opened on the pager (transitioning
57019 ** In other cases, the error is returned to the b-tree layer. The b-tree
57023 ** Condition (3) is necessary because it can be triggered by a read-only
57030 ** * The Pager.errCode variable is set to something other than SQLITE_OK.
57032 ** last reference is dropped the pager should move back to OPEN state).
57033 ** * The pager is not an in-memory pager.
57038 ** * A pager is never in WRITER_DBMOD or WRITER_FINISHED state if the
57039 ** connection is open in WAL mode. A WAL connection is always in one
57042 ** * Normally, a connection open in exclusive mode is never in PAGER_OPEN
57045 ** executed), and when the pager is leaving the "error state".
57058 ** The Pager.eLock variable is almost always set to one of the
57061 ** This variable is kept up to date as locks are taken and released by
57065 ** (i.e. one of the SQLITE_IOERR subtypes), it is not clear whether or not
57067 ** pagerUnlockDb() take a conservative approach - eLock is always updated
57069 ** VFS call is successful. This way, the Pager.eLock variable may be set
57070 ** to a less exclusive (lower) value than the lock that is actually held
57071 ** at the system level, but it is never set to a more exclusive value.
57073 ** This is usually safe. If an xUnlock fails or appears to fail, there may
57077 ** The exception is when the database file is unlocked as the pager moves
57081 ** fails at this point and the pager is left holding an EXCLUSIVE lock, this
57085 ** xCheckReservedLock() is defined as returning true "if there is a RESERVED
57087 ** return true because the caller itself is holding an EXCLUSIVE lock (but
57094 ** database in the ERROR state, Pager.eLock is set to UNKNOWN_LOCK. It
57095 ** is only changed back to a real locking state after a successful call
57097 ** omits the check for a hot-journal if Pager.eLock is set to UNKNOWN_LOCK
57102 ** Pager.eLock may only be set to UNKNOWN_LOCK when the pager is in
57109 ** returns a value larger than this, then MAX_SECTOR_SIZE is used instead.
57111 ** such a system. This is currently an undocumented limit.
57117 ** An instance of the following structure is allocated for each active
57119 ** are stored in the Pager.aSavepoint[] array, which is allocated and
57122 ** When a savepoint is created, the PagerSavepoint.iHdrOffset field is
57123 ** set to 0. If a journal-header is written into the main journal while
57124 ** the savepoint is active, then iHdrOffset is set to the byte offset
57126 ** journal before the journal-header. This is required during savepoint
57147 #define SPILLFLAG_NOSYNC 0x04 /* Spill is ok, but do not sync */
57150 ** An open page cache is an instance of struct Pager. A description of
57164 ** locks), this variable is always set to EXCLUSIVE_LOCK. Since such
57175 ** This boolean variable is used to make sure that the change-counter
57176 ** (the 4-byte header field at byte offset 24 of the database file) is
57179 ** It is set to true when the change-counter field is updated, which
57180 ** can only happen if an exclusive lock is held on the database file.
57181 ** It is cleared (set to false) whenever an exclusive lock is
57182 ** relinquished on the database file. Each time a transaction is committed,
57183 ** The changeCountDone flag is inspected. If it is true, the work of
57184 ** updating the change-counter is omitted for the current transaction.
57192 ** When PagerCommitPhaseOne() is called to commit a transaction, it may
57194 ** journal file before it is synced to disk.
57197 ** the way in which the journal file is finalized after the transaction is
57199 ** If a journal file does not contain a super-journal pointer, it is
57201 ** it does contain a super-journal pointer the journal file is finalized
57210 ** The flag is cleared as soon as the journal file is finalized (either
57213 ** is cleared anyway (and the pager will move to ERROR state).
57222 ** writing to the database from pagerStress() is disabled altogether.
57223 ** The SPILLFLAG_ROLLBACK case is done in a very obscure case that
57226 ** while it is being traversed by code in pager_playback(). The SPILLFLAG_OFF
57227 ** case is a user preference.
57229 ** If the SPILLFLAG_NOSYNC bit is set, writing to the database from
57230 ** pagerStress() is permitted, but syncing the journal file is not.
57231 ** This flag is set by sqlite3PagerWrite() when the file-system sector-size
57232 ** is larger than the database page-size in order to prevent a journal sync
57237 ** This is a boolean variable. If true, then any required sub-journal
57238 ** is opened as an in-memory journal file. If false, then in-memory
57241 ** This variable is updated by the upper layer each time a new
57242 ** write-transaction is opened.
57246 ** Variable dbSize is set to the number of pages in the database file.
57247 ** It is valid in PAGER_READER and higher states (all states except for
57250 ** dbSize is set based on the size of the database file, which may be
57253 ** is not an integer multiple of the page-size, the value stored in
57254 ** dbSize is rounded down (i.e. a 5KB file with 2K page-size has dbSize==2).
57255 ** Except, any file that is greater than 0 bytes in size is considered
57260 ** dbSize are modified in the cache, dbSize is updated accordingly.
57261 ** Similarly, if the database is truncated using PagerTruncateImage(),
57262 ** dbSize is updated.
57265 ** PAGER_WRITER_LOCKED and higher. dbOrigSize is a copy of the dbSize
57266 ** variable at the start of the transaction. It is used during rollback,
57271 ** the file on disk in pages. It is set to a copy of dbSize when the
57272 ** write-transaction is first opened, and updated when VFS calls are made
57275 ** The only reason the dbFileSize variable is required is to suppress
57277 ** when a transaction is committed, the dbFileSize variable indicates
57278 ** that the database file is larger than the database image (Pager.dbSize),
57279 ** pager_truncate() is called. The pager_truncate() call uses xFilesize()
57281 ** dbFileSize is not used when rolling back a transaction. In this case
57282 ** pager_truncate() is called unconditionally (which means there may be
57283 ** a call to xFilesize() that is not strictly required). In either case,
57288 ** The dbHintSize variable is used to limit the number of calls made to
57291 ** dbHintSize is set to a copy of the dbSize variable when a
57292 ** write-transaction is opened (at the same time as dbFileSize and
57293 ** dbOrigSize). If the xFileControl(FCNTL_SIZE_HINT) method is called,
57294 ** dbHintSize is increased to the number of pages that correspond to the
57300 ** The Pager.errCode variable is only ever used in PAGER_ERROR state. It
57301 ** is set to zero in all other states. In PAGER_ERROR state, Pager.errCode
57302 ** is always set to SQLITE_FULL, SQLITE_IOERR or one of the SQLITE_IOERR_XXX
57307 ** syncFlags is either SQLITE_SYNC_NORMAL (0x02) or SQLITE_SYNC_FULL (0x03).
57308 ** syncFlags is used for rollback mode. walSyncFlags is used for WAL mode
57314 ** that with synchronous=NORMAL in WAL mode, transaction commit is not synced
57327 u8 tempFile; /* zFilename is a temporary or immutable file */
57336 ** when the pager is first created or else only change when there is a
57345 u8 setSuper; /* Super-jrnl name is written into jrnl */
57431 ** was obtained from /dev/random. It is used only as a sanity check.
57434 ** checking information. If the power fails while the journal is being
57436 ** file after power is restored. If an attempt is then made
57438 ** sanity checking data is an attempt to discover the garbage in the
57444 ** This cksum is initialized to a 32-bit random value that appears in the
57445 ** journal file right after the header. The random initializer is important,
57446 ** because garbage data that appears at the end of a journal is likely
57450 ** is different for every journal, we minimize that risk.
57457 ** The size of the of each page record in the journal is given by
57463 ** The journal header size for this pager. This is usually the same
57469 ** The macro MEMDB is true if we are dealing with an in-memory database.
57470 ** We do this as a macro so that if the SQLITE_OMIT_MEMORYDB macro is set,
57481 ** The macro USEFETCH is true if we are allowed to use the xFetch and xUnfetch
57491 ** The argument to this macro is a file descriptor (type sqlite3_file*).
57492 ** Return 0 if it is not open, or non-zero (but not 1) if it is.
57494 ** This is so that expressions can be written as:
57507 ** by the b-tree layer. This is the case if:
57509 ** * the database file is open,
57511 ** * the desired page is not currently in the wal file.
57561 ** the change-counter field, so the changeCountDone flag is always set.
57566 /* If the useJournal flag is clear, the journal-mode must be "OFF".
57567 ** And if the journal-mode is "OFF", the journal file must not be open.
57576 ** return SQLITE_IOERR_NOMEM while the journal file is being written). It
57577 ** is therefore not possible for an in-memory pager to enter the ERROR
57590 /* If changeCountDone is set, a RESERVED lock or greater must be held
57625 /* It is possible that if journal_mode=wal here that neither the
57682 ** is intended to be used within debuggers. For example, as an alternative
57688 ** about an unused function. It is enclosed within SQLITE_DEBUG and so does
57757 ** Return true if it is necessary to write page *pPg into the sub-journal.
57761 ** * The page-number is less than or equal to PagerSavepoint.nOrig, and
57762 ** * The bit corresponding to the page-number is not set in
57784 ** Return true if the page is already in the journal file.
57793 ** that is read in *pRes. Return SQLITE_OK if everything worked, or an
57794 ** error code is something goes wrong.
57815 ** on success or an error code is something goes wrong.
57828 ** Except, if Pager.eLock is set to UNKNOWN_LOCK when this function is
57852 ** RESERVED_LOCK or EXCLUSIVE_LOCK. If the caller is successful, set the
57855 ** Except, if Pager.eLock is set to UNKNOWN_LOCK when this function is
57856 ** called, do not modify it unless the new locking state is EXCLUSIVE_LOCK.
57881 ** (b) the value returned by OsSectorSize() is less than or equal
57884 ** If it can be used, then the value returned is the size of the journal
57888 ** returns a value with the SQLITE_IOCAP_BATCH_ATOMIC bit set. -1 is
57891 ** If neither optimization can be used, 0 is returned.
57931 ** If SQLITE_CHECK_PAGES is defined then we do some sanity checking
57932 ** on the cache using a hash function. This is used for testing
57956 ** is defined, and NDEBUG is not defined, an assert() statement checks
57957 ** that the page is either dirty or still matches the calculated page-hash.
57974 ** When this is called the journal file for pager pPager must be open.
57981 ** the caller. This should be sqlite3_vfs.mxPathname+1 (to ensure there is
57983 ** name in the journal is longer than nSuper bytes (including a
57984 ** nul-terminator), then this is handled as if no super-journal name
57987 ** If a super-journal file name is present at the end of the journal
57988 ** file, then it is copied into the buffer pointed to by zSuper. A
57989 ** nul-terminator byte is appended to the buffer following the
57992 ** If it is determined that no super-journal file name is present
57993 ** zSuper[0] is set to 0 and SQLITE_OK returned.
57996 ** error code is returned.
58027 ** containing the super-journal filename is corrupted. This means
58067 ** The journal file must be open when this function is called.
58069 ** This function is a no-op if the journal file has not been written to
58072 ** If doTruncate is non-zero or the Pager.journalSizeLimit variable is
58075 ** if the pager is not in no-sync mode, sync the journal file immediately
58078 ** If Pager.journalSizeLimit is set to a positive, non-zero value, and
58080 ** journal file in bytes is larger than this value, then truncate the
58105 /* At this point the transaction is committed but the write lock
58106 ** is still held on the file. If there is a size limit configured for
58108 ** space than that limit allows for, truncate it now. There is no need
58123 ** The journal file must be open when this routine is called. A journal
58124 ** header (JOURNAL_HDR_SZ bytes) is written into the journal file at the
58127 ** The format for the journal header is as follows:
58129 ** - 4 bytes: Number of records in journal, or -1 no-sync mode is on.
58164 ** journal header. Normally, zero is written to this value at this time.
58166 ** if in full-sync mode), the zero is overwritten with the true number
58169 ** A faster alternative is to write 0xFFFFFFFF to the nRec field. When
58172 ** is dangerous, as if a failure occurred whilst writing to the journal
58176 ** * When the pager is in no-sync mode. Corruption can follow a
58179 ** * When the SQLITE_IOCAP_SAFE_APPEND flag is set. This guarantees
58180 ** that garbage data is never appended to the journal file.
58200 /* The Pager.cksumInit variable is usually randomized above to protect
58201 ** against there being existing records in the journal file. This is
58205 ** that this is not required in "journal_mode=memory" mode, as in that
58206 ** case the journal file is always 0 bytes in size at this point.
58207 ** It is advantageous to avoid the sqlite3_randomness() call if possible
58226 /* Initializing the tail of the buffer is not necessary. Everything
58227 ** works find if the following memset() is omitted. But initializing
58234 /* In theory, it is only necessary to write the 28 bytes that the
58237 ** record is written to the following sector (leaving a gap in the file
58243 ** (JOURNAL_HDR_SZ - 28) bytes that will not be used. So that is what
58244 ** is done.
58246 ** The loop is required here in case the sector-size is larger than the
58247 ** database page size. Since the zHeader buffer is only Pager.pageSize
58262 ** The journal file must be open when this is called. A journal header file
58263 ** (JOURNAL_HDR_SZ bytes) is read from the current location in the journal
58264 ** file. The current location in the journal file is given by
58268 ** If the header is read successfully, *pNRec is set to the number of
58269 ** page records following this header and *pDbSize is set to the size of the
58271 ** is set to the value read from the journal header. SQLITE_OK is returned
58274 ** If the journal header file appears to be corrupted, SQLITE_DONE is
58276 ** cannot be read from the journal file an error code is returned.
58292 ** journal file is too small for there to be a header stored at this
58340 ** variable is already set to the correct page size.
58355 /* If the either the page-size or sector-size in the journal-header is
58365 ** PagerSetPagesize() is tested.
58373 ** is being called from within pager_playback(). The local value
58374 ** of Pager.sectorSize is restored at the end of that routine.
58387 ** thing written to a journal file. If the pager is in full-sync mode, the
58388 ** journal file descriptor is advanced to the next sector boundary before
58389 ** anything is written. The format is:
58397 ** The super-journal page checksum is the sum of the bytes in the super-journal
58398 ** name, where each byte is interpreted as a signed 8-bit integer.
58400 ** If zSuper is a NULL pointer (occurs for a single database transaction),
58401 ** this call is a no-op.
58428 ** the super-journal name. This is in case the previous page written to
58450 /* If the pager is in persistent-journal mode, then the physical
58452 ** and 8 bytes of magic data just written to the file. This is
58455 ** whether or not the journal is hot.
58457 ** Easiest thing to do in this scenario is to truncate the journal
58487 ** if it is open and the pager is not in exclusive mode.
58524 ** This function is a no-op if the pager is in exclusive mode and not
58528 ** If the pager is not in exclusive-access mode, the database file is
58529 ** completely unlocked. If the file is unlocked and the file-system does
58530 ** not exhibit the UNDELETABLE_WHEN_OPEN property, the journal file is
58531 ** closed (if it is open).
58533 ** If the pager is in ERROR state when this function is called, the
58535 ** the OPEN state. Regardless of whether the pager is in exclusive-mode
58538 ** is opened (by this or by any other connection).
58576 /* If the pager is in the ERROR state and the call to unlock the database
58579 ** is necessary.
58587 ** without clearing the error code. This is intentional - the error
58588 ** code is cleared and the cache reset in the block below.
58594 /* If Pager.errCode is set, the contents of the pager cache cannot be
58619 ** This function is called whenever an IOERR or FULL error that requires
58621 ** The first argument is a pointer to the pager structure, the second
58623 ** value returned is a copy of the second argument to this function.
58625 ** If the second argument is SQLITE_FULL, SQLITE_IOERR or one of the
58627 ** is stored in Pager.errCode. While the pager remains in the ERROR state,
58656 ** The write transaction open on pPager is being committed (bCommit==1)
58663 ** * For non-TEMP databases, always sync to disk. This is necessary
58679 ** This routine ends a transaction. A transaction is usually ended by
58685 ** This routine is never called in PAGER_ERROR state. If it is called
58686 ** in PAGER_NONE or PAGER_SHARED state and the lock held is less
58687 ** exclusive than a RESERVED lock, it is a no-op.
58691 ** If the journal file is open, then it is "finalized". Once a journal
58692 ** file has been finalized it is not possible to use it to roll back a
58694 ** or any other database connection. Exactly how a journal is finalized
58695 ** depends on whether or not the pager is running in exclusive mode and
58699 ** Journal file descriptor is simply closed. This destroys an
58703 ** Journal file is truncated to zero bytes in size.
58711 ** The journal file is closed and deleted using sqlite3OsDelete().
58713 ** If the pager is running in exclusive mode, this method of finalizing
58714 ** the journal file is never used. Instead, if the journalMode is
58715 ** DELETE and the pager is in exclusive mode, the method described under
58716 ** journalMode==PERSIST is used instead.
58718 ** After the journal is finalized, the pager moves to PAGER_READER state.
58719 ** If running in non-exclusive rollback mode, the lock on the file is
58722 ** SQLITE_OK is returned if no error occurs. If an error occurs during
58724 ** database then the IO error code is returned to the user. If the
58728 ** to the first error encountered (the journal finalization one) is
58737 ** is no write-transaction active but a RESERVED or greater lock is
58740 ** 1. After a successful hot-journal rollback, it is called with
58745 ** read-transaction, this function is called with eState==PAGER_READER
58746 ** and eLock==EXCLUSIVE_LOCK when the read-transaction is closed.
58771 /* Make sure the new file size is written into the inode right away.
58829 ** locking_mode=exclusive mode but is no longer, drop the EXCLUSIVE
58835 /* This branch is taken when committing a transaction in rollback-journal
58836 ** mode if the database file on disk is larger than the database image.
58838 ** successfully committed, but the EXCLUSIVE lock is still held on the
58839 ** file. So it is safe to truncate the database file to its minimum
58865 ** Execute a rollback if a transaction is active and unlock the
58869 ** the rollback at this time. Instead, pager_unlock() is called. The
58872 ** means that there is a hot-journal left in the file-system, the next
58897 ** journal: We have to rollback immediately, before the journal is
58898 ** closed, because once it is closed, all content is forgotten. */
58916 ** This is not a real checksum. It is really just the sum of the
58919 ** Each byte is interpreted as an 8-bit unsigned integer.
58925 ** scenario is that one end or the other of the record will be changed.
58926 ** It is much less likely that the two ends of the journal record will be
58944 ** value is increased to the start of the next page in the journal.
58950 ** is greater than the current value of Pager.dbSize, then playback is
58951 ** skipped and SQLITE_OK is returned.
58953 ** If pDone is not NULL, then it is a record of pages that have already
58955 ** (if the corresponding pDone bit is set) then skip the playback.
58956 ** Make sure the pDone bit corresponding to the *pOffset page is set
58959 ** If the page record is successfully read from the (sub-)journal file
58960 ** and played back, then SQLITE_OK is returned. If an IO error occurs
58962 ** to the database file, then the IO error code is returned. If data
58963 ** is successfully read from the (sub-)journal file but appears to be
58964 ** corrupted, SQLITE_DONE is returned. Data is considered corrupted in
58967 ** * If the record page-number is illegal (0 or PAGER_SJ_PGNO), or
58968 ** * If the record is being rolled back from the main journal file
58973 ** If this is a savepoint rollback, then memory may have to be dynamically
58974 ** allocated by this function. If this is the case and an allocation fails,
58975 ** SQLITE_NOMEM is returned.
58990 int isSynced; /* True if journal page is synced */
58992 assert( (isMainJrnl&~1)==0 ); /* isMainJrnl is 0 or 1 */
58993 assert( (isSavepnt&~1)==0 ); /* isSavepnt is 0 or 1 */
59001 /* Either the state is greater than PAGER_WRITER_CACHEMOD (a transaction
59002 ** or savepoint rollback done at the request of the caller) or this is
59003 ** a hot-journal rollback. If it is a hot-journal rollback, the pager
59004 ** is in state OPEN and holds an EXCLUSIVE lock. Hot-journal rollback
59022 /* Sanity checking on the page. This is more important that I originally
59023 ** thought. If a power failure occurs while the journal is being written,
59055 /* If the pager is in CACHEMOD state, then there must be a copy of this
59057 ** not the database file. The page is left marked dirty in this case.
59059 ** An exception to the above rule: If the database is in no-sync mode
59060 ** and a page is moved during an incremental vacuum then the page may
59063 ** either. So the condition described in the above paragraph is not
59067 ** pager cache if it exists and the main file. The page is then marked
59068 ** not dirty. Since this code is only executed in PAGER_OPEN state for
59069 ** a hot-journal rollback, it is guaranteed that the page-cache is empty
59070 ** if the pager is in OPEN state.
59072 ** Ticket #1171: The statement journal might contain page content that is
59074 ** This occurs when a page is changed prior to the start of a statement
59082 ** locked. (2) we know that the original page content is fully synced
59083 ** in the main journal either because the page is not in cache or else
59084 ** the page is marked as needSync==0.
59087 ** is possible to fail a statement on a database that does not yet exist.
59115 ** This is usually safe even for an encrypted database - as the data
59117 ** is if the data was just read from an in-memory sub-journal. In that
59118 ** case it must be encrypted here before it is copied into the database
59129 /* If this is a rollback of a savepoint and data was not written to
59130 ** the database and the page is not in-memory, there is a potential
59131 ** problem. When the page is next fetched by the b-tree layer, it
59137 ** if the page is on the free-list at the start of the transaction, then
59140 ** The solution is to add an in-memory page to the cache containing
59143 ** requiring a journal-sync before it is written.
59155 /* No page should ever be explicitly rolled back that is in use, except
59156 ** for page 1 which is held in use in order to keep the lock on the
59167 ** is normally cleaned by sqlite3PcacheCleanAll() after rollback and so
59182 ** Parameter zSuper is the name of a super-journal file. A single journal
59184 ** This routine checks if it is possible to delete the super-journal file,
59185 ** and does so if it is.
59187 ** Argument zSuper may point to Pager.pTmpSpace. So that buffer is not
59190 ** When a super-journal file is created, it is populated with the names
59192 ** encoded text. The end of each child journal file is marked with a
59211 ** no such child journal can be found, file zSuper is deleted from
59214 ** If an IO error within this function, an error code is returned. This
59216 ** fails, SQLITE_NOMEM is returned. Otherwise, if no IO or malloc errors
59217 ** occur, SQLITE_OK is returned.
59282 ** NB: zJournal is really a MAIN_JOURNAL. But call it a
59323 ** This function is used to change the actual size of the database
59327 ** If the main database file is not open, or the pager is not in either
59328 ** DBMOD or OPEN state, this function is a no-op. Otherwise, the size
59329 ** of the file is changed to nPage pages (nPage*pPager->pageSize bytes).
59330 ** If the file on disk is currently larger than nPage pages, then use the VFS
59333 ** Or, it might be the case that the file on disk is smaller than
59335 ** you try to truncate a file to some size that is larger than it
59336 ** currently is, so detect this case and write a single zero byte to
59379 ** return value is guaranteed to lie between 32 and MAX_SECTOR_SIZE.
59399 ** For temporary files the effective sector size is always 512 bytes.
59401 ** Otherwise, for non-temporary files, the effective sector size is
59403 ** it is less than 32, or rounded down to MAX_SECTOR_SIZE if it
59404 ** is greater than MAX_SECTOR_SIZE.
59408 ** pPager->sectorSize is to define the "blast radius" of bytes that
59410 ** that range. But with POWERSAFE_OVERWRITE, the blast radius is zero
59411 ** (that is what POWERSAFE_OVERWRITE means), so we minimize the sector
59435 ** The journal file format is as follows:
59438 ** (2) 4 byte big-endian integer which is the number of valid page records
59439 ** in the journal. If this value is 0xffffffff, then compute the
59441 ** (3) 4 byte big-endian integer which is the initial value for the
59443 ** (4) 4 byte integer which is the number of pages to truncate the
59445 ** (5) 4 byte big-endian integer which is the sector size. The header
59446 ** is this many bytes in size.
59447 ** (6) 4 byte big-endian integer which is the page size.
59455 ** Each entry in the journal is an instance of the 8th item.
59457 ** Call the value from the second bullet "nRec". nRec is the number of
59466 ** If the nRec value is 0xffffffff it means that nRec should be computed
59467 ** from the file size. This value is used when the user selects the
59470 ** deleted when the power is restored) we don't care.
59472 ** If the file opened as the journal file is not a well-formed
59474 ** back (or no pages if the journal header is corrupted). The journal file
59475 ** is then deleted and SQLITE_OK returned, just as if no corruption had
59478 ** If an I/O or malloc() error occurs, the journal-file is not deleted
59479 ** and an error code is returned.
59482 ** that might be a hot journal. Or, it could be that the journal is
59484 ** If the journal really is hot, reset the pager cache prior rolling
59485 ** back any content. If the journal is merely persistent, no reset is
59502 ** the journal is empty.
59510 /* Read the super-journal name from the journal, if it is present.
59511 ** If a super-journal file name is specified, but the file is not
59512 ** present on disk, then the journal is not hot and does not need to be
59515 ** TODO: Technically the following is an error because it assumes that
59516 ** buffer Pager.pTmpSpace is (mxPathname+1) bytes or larger. i.e. that
59518 ** mxPathname is 512, which is the same as the minimum allowable value
59540 ** it is corrupted, then a process must have failed while writing it.
59551 /* If nRec is 0xffffffff, then this journal was created by a process
59561 /* If nRec is 0 and this rollback is of a transaction created by this
59562 ** process and if this is the final header in the journal, then it means
59570 ** when doing a ROLLBACK and the nRec==0 chunk is the last chunk in
59580 /* If this is the first header read from the journal, truncate the
59614 ** first place so it is OK to simply abandon the rollback. */
59644 /* If this playback is happening automatically as a result of an IO or
59657 ** This is because it may end up being passed to sqlite3OsOpen(), in
59675 ** see if it is possible to delete the super-journal.
59698 ** the WAL if that is where the most recent copy if found) into
59700 ** file before this function is called.
59702 ** If page 1 is read, then the value of Pager.dbFileVers[] is set to
59705 ** If an IO error occurs, then the IO error is returned to the caller.
59706 ** Otherwise, SQLITE_OK is returned.
59736 /* If the read is unsuccessful, set the dbFileVers[] to something
59737 ** that will never be a valid file version. dbFileVers[] is a copy
59743 ** For an encrypted database, the situation is more complex: bytes
59745 ** white noise equaling 16 bytes of 0xff is vanishingly small so
59767 ** This is an unconditional update. See also the pager_incr_changecounter()
59768 ** routine which only updates the change-counter if the update is actually
59781 ** is valid. */
59788 ** This function is invoked once for each page that has already been
59789 ** written into the log file when a WAL transaction is rolled back.
59790 ** Parameter iPg is the page number of said page. The pCtx argument
59791 ** is actually a pointer to the Pager structure.
59793 ** If page iPg is present in the cache, and has no outstanding references,
59794 ** it is discarded. Otherwise, if there are one or more outstanding
59795 ** references, the page content is reloaded from the database. If the
59796 ** attempt to reload content from the database is required and fails,
59818 /* Normally, if a transaction is rolled back, any backup processes are
59819 ** updated as data is copied out of the rollback journal and into the
59820 ** database. This is not generally possible with a WAL database, as
59832 ** This function is called to rollback a transaction on a WAL database.
59858 ** This function is a wrapper around sqlite3WalFrames(). As well as logging
59863 ** The list of pages passed into this routine is always sorted by page number.
59870 int isCommit /* True if this is a commit */
59879 /* Verify that the page list is in ascending order */
59887 /* If a WAL transaction is being committed, there is no point in writing
59943 ** the duplicate call is harmless.
59958 ** This function is called as part of the transition from PAGER_OPEN
59962 ** If no error occurs, SQLITE_OK is returned and the size of the database
59963 ** in pages is stored in *pnPage. Otherwise, an error code (perhaps
59964 ** SQLITE_IOERR_FSTAT) is returned and *pnPage is left unmodified.
59970 ** function returns zero if the WAL is not open (i.e. Pager.pWal==0), or
59971 ** if the database size is not available. The database size is not
59972 ** available from the WAL sub-system if the log file is empty or
59981 /* If the number of pages in the database is not available from the
59983 ** the database file. If the size of the database file is not an
59995 /* If the current number of pages in the file is greater than the
60010 ** exists if the database is not empty, or verify that the *-wal file does
60011 ** not exist (by deleting it) if the database file is empty.
60013 ** If the database is not empty and the *-wal file exists, open the pager
60014 ** in WAL mode. If the database is empty or if no *-wal file exists and
60015 ** if no error occurs, make sure Pager.journalMode is not set to
60021 ** function. Because an EXCLUSIVE lock on the db file is required to delete
60022 ** a WAL on a none-empty database, this ensures there is no race condition
60060 ** a ROLLBACK TO command is invoked on a SAVEPOINT that is a transaction
60063 ** When pSavepoint is not NULL (meaning a non-transaction savepoint is
60070 ** file if PagerSavepoint.iHdrOffset is zero.
60072 ** * If PagerSavepoint.iHdrOffset is not zero, then pages are played
60080 ** Throughout the rollback process, each time a page is rolled back, the
60081 ** corresponding bit is set in a bitvec structure (variable pDone in the
60082 ** implementation below). This is used to ensure that a page is only
60083 ** rolled back the first time it is encountered in either journal.
60085 ** If pSavepoint is NULL, then pages are only played back from the main
60086 ** journal file. There is no need for a bitvec in this case.
60089 ** is reset to the value that it held at the start of the savepoint
60091 ** is played back. If one is encountered it is simply skipped.
60123 ** past pPager->journalOff is off-limits to us.
60160 ** test is related to ticket #2565. See the discussion in the
60256 ** OFF sqlite3OsSync() is never called. This is the default
60259 ** NORMAL The journal is synced once before writes begin on the
60260 ** database. This is normally adequate protection, but
60261 ** it is theoretically possible, though very unlikely,
60264 ** when it is rolled back.
60266 ** FULL The journal is synced twice before writes begin on the
60270 ** single disk sector is atomic, then this mode provides
60274 ** EXTRA This is like FULL except that is also syncs the directory
60276 ** journal is unlinked.
60278 ** The above is for a rollback-journal mode. For WAL mode, OFF continues
60279 ** to mean that no syncs ever occur. NORMAL means that the WAL is synced
60280 ** prior to the start of checkpoint and that the database file is synced
60284 ** file is synced following each commit operation, in addition to the
60285 ** syncs associated with NORMAL. There is no difference between FULL
60291 ** ordinary fsync() call. There is no difference between SQLITE_SYNC_FULL
60294 ** the xSync primitive is called and is relevant to all platforms.
60335 ** The following global variable is incremented whenever the library
60336 ** attempts to open a temporary file. This information is used for
60348 ** delete the temporary file when it is closed.
60393 ** If the busy-handler callback returns non-zero, the lock is
60394 ** retried. If it returns zero, then the SQLITE_BUSY error is
60413 ** is passed in *pPageSize.
60415 ** If the pager is in the error state when this function is called, it
60416 ** is a no-op. The value returned is the error state error code (i.e.
60421 ** * the new page size (value of *pPageSize) is valid (a power
60426 ** * the database is either not an in-memory database or it is
60429 ** then the pager object page size is set to *pPageSize.
60431 ** If the page size is changed, then this function uses sqlite3PagerMalloc()
60433 ** fails, SQLITE_NOMEM is returned and the page size remains unchanged.
60434 ** In all other cases, SQLITE_OK is returned.
60436 ** If the page size is not changed, either because one of the enumerated
60437 ** conditions above is not true, the pager was in error state when this
60439 ** then *pPageSize is set to the old, retained page size before returning.
60444 /* It is not possible to do a full assert_pager_state() here, as this
60446 ** of the Pager object is internally consistent.
60450 ** there is at least one outstanding page reference, this function
60451 ** is a no-op for that case anyhow.
60467 /* 8 bytes of zeroed overrun space is sufficient so that the b-tree
60504 ** by the pager. This is a buffer that is big enough to hold the
60505 ** entire content of a database page. This buffer is used internally
60515 ** Attempt to set the maximum database page count if mxPage is positive.
60516 ** Make no changes if mxPage is zero or negative. And never reduce the
60527 /* OP_MaxPgcnt ensures that the parameter passed to this function is not
60529 ** may be less than Pager.dbSize, and so the assert() above is not valid */
60538 ** Unless -DSQLITE_TEST=1 is used, these routines are all no-ops
60562 ** opened on a file less than N bytes in size, the output buffer is
60563 ** zeroed and SQLITE_OK returned. The rationale for this is that this
60564 ** function is used to read database headers, and a new transient or
60567 ** If any IO error apart from SQLITE_IOERR_SHORT_READ is encountered,
60568 ** the error code is returned to the caller and the contents of the
60576 /* This routine is only called by btree immediately after creating
60593 ** This function may only be called when a read-transaction is open on
60596 ** However, if the file is between 1 and <page-size> bytes in size, then
60597 ** this is considered a 1 page file.
60608 ** a similar or greater lock is already held, this function is a no-op
60612 ** the busy callback if the lock is currently not available. Repeat
60617 ** the lock. If the lock is obtained successfully, set the Pager.state
60623 /* Check that this is either a no-op (because the requested lock is
60641 ** following is true for all dirty pages currently in the page-cache:
60643 ** a) The page number is less than or equal to the size of the
60654 ** content of the page. However, since this content is not present in either
60657 ** database image would become corrupt. It is therefore fortunate that
60664 if( pPg->pgno>pPager->dbSize ){ /* if (a) is false */
60684 ** truncation will be done when the current transaction is committed.
60686 ** This function is only called right before committing a transaction.
60688 ** rolled back or committed. It is not safe to call this function and
60699 ** journal so that they can be restored if the savepoint is rolled
60700 ** back. This is no longer necessary as this function is now only
60704 ** is no longer correct. */
60709 ** This function is called before attempting a hot-journal rollback. It
60719 ** If everything goes as planned, SQLITE_OK is returned. Otherwise,
60811 ** under the pager. Return SQLITE_OK if the database is still where it ought
60824 /* If the HAS_MOVED file-control is unimplemented, assume that the file
60825 ** has not been moved. That is the historical behavior of SQLite: prior to
60838 ** If a transaction was in progress when this routine is called, that
60839 ** transaction is rolled back. All outstanding pages are invalidated
60840 ** and their memory is freed. Any attempt to use a page associated
60844 ** This function always succeeds. If a transaction is active an attempt
60845 ** is made to roll it back. If an error occurs during the rollback
60846 ** a hot journal may be left in the filesystem but no error is returned
60875 /* If it is open, sync the journal file before calling UnlockAndRollback.
60876 ** If this is not done, then an unsynced portion of the open journal
60878 ** while this is happening, the database could become corrupt.
60927 ** If the Pager.noSync flag is set, then this function is a no-op.
60931 ** * If the journal file is an in-memory journal file, no action need
60936 ** is updated to contain the number of journal records that have
60937 ** been written following it. If the pager is operating in full-sync
60938 ** mode, then the journal file is synced before this field is updated.
60941 ** journal file is synced.
60955 ** error is encountered, then the IO error code is returned to the caller.
60982 ** occurs after nRec is updated but before this connection writes
60993 ** Variable iNextHdrOffset is set to the offset at which this
60994 ** problematic header will occur, if it exists. aMagic is used
61017 ** all data has really hit the disk before nRec is updated to mark
61020 ** This is not required if the persistent media supports the
61021 ** SAFE_APPEND property. Because in this case it is not possible
61023 ** is populated with 0xFFFFFFFF when the journal header is written
61058 /* Unless the pager is in noSync mode, the journal file was just
61069 ** The argument is the first in a linked list of dirty pages connected
61072 ** be NULL, representing an empty list. In this case this function is
61076 ** is called. Before writing anything to the database file, this lock
61077 ** is upgraded to an EXCLUSIVE lock. If the lock cannot be obtained,
61078 ** SQLITE_BUSY is returned and no data is written to the database file.
61080 ** If the pager is a temp-file pager and the actual file-system file
61081 ** is not yet open, it is created and opened before any data is
61086 ** a page is skipped if it meets either of the following criteria:
61088 ** * The page number is greater than Pager.dbSize, or
61089 ** * The PGHDR_DONT_WRITE flag is set on the page.
61092 ** is updated accordingly. If page 1 is written out, then the value cached
61093 ** in Pager.dbFileVers[] is updated to match the new value stored in
61096 ** If everything is successful, SQLITE_OK is returned. If an IO error
61097 ** occurs, an IO error code is returned. Or, if the EXCLUSIVE lock cannot
61098 ** be obtained, SQLITE_BUSY is returned.
61103 /* This function is only called for rollback pagers in WRITER_DBMOD state. */
61109 /* If the file is a temp-file has not yet been opened, open it now. It
61110 ** is not possible for rc to be other than SQLITE_OK if this branch
61111 ** is taken, as pager_wait_on_lock() is a no-op for temp-files.
61184 ** Ensure that the sub-journal file is open. If it is already open, this
61185 ** function is a no-op.
61187 ** SQLITE_OK is returned if everything goes according to plan. An
61188 ** SQLITE_IOERR_XXX error code is returned if a call to sqlite3OsOpen()
61212 ** This function returns SQLITE_OK if everything is successful, an IO
61262 ** This function is called by the pcache layer when it has reached some
61263 ** soft memory limit. The first argument is a pointer to a Pager object
61264 ** (cast as a void*). The pager is always 'purgeable' (not an in-memory
61265 ** database). The second argument is a reference to a page that is
61267 ** is always associated with the Pager object passed as the first
61270 ** The job of this function is to make pPg clean by writing its contents
61274 ** If successful, sqlite3PcacheMakeClean() is called on the page and
61276 ** page clean, the IO error code is returned. If the page cannot be
61278 ** is returned by sqlite3PcacheMakeClean() is not called.
61287 /* The doNotSpill NOSYNC bit is set during times when doing a sync of
61288 ** journal (and adding a new header) is not allowed. This occurs
61293 ** regardless of whether or not a sync is required. This is set during
61296 ** Spilling is also prohibited when in an error state since that could
61298 ** is impossible for sqlite3PcacheFetch() to be called with createFlag==3
61299 ** while in the error state, hence it is impossible for this routine to
61379 ** The zFilename argument is the path to the database file to open.
61380 ** If zFilename is NULL then a randomly-named temporary file is created
61382 ** automatically when they are closed. If zFilename is ":memory:" then
61383 ** all information is held in cache. It is never written to disk.
61387 ** along with each page reference. This space is available to the user
61388 ** via the sqlite3PagerGetExtra() API. When a new page is allocated, the
61389 ** first 8 bytes of this space are zeroed but the remainder is uninitialized.
61390 ** (The extra space is used by btree as the MemPage object.)
61392 ** The flags argument is used to specify properties that affect the
61396 ** The vfsFlags parameter is a bitmask to pass to the flags parameter
61399 ** If the pager object is allocated and the specified file opened
61400 ** successfully, SQLITE_OK is returned and *ppPager set to point to
61401 ** the new pager object. If an error occurs, *ppPager is set to NULL
61403 ** (sqlite3Malloc() is used to allocate memory), SQLITE_CANTOPEN or
61419 int memDb = 0; /* True if this is an in-memory file */
61421 int readOnly = 0; /* True if this is a read-only file */
61431 /* Figure out how much space is required for each journal file-handle
61451 ** to by zPathname, length nPathname. Or, if this is a temporary file,
61481 /* This branch is taken when the journal path required by
61497 ** file name. The layout in memory is as follows:
61515 ** filename without using the sqlite3_filename_database() API. This is a
61517 ** software is in widespread use, so we try to avoid changing the filename
61535 ** that is used by sqlite3_filename_database() and kin also depend on the
61625 ** database file. The default page size is the maximum of:
61665 /* If a temporary file is requested, it is not opened immediately.
61669 ** This branch is also run for an in-memory database. An in-memory
61670 ** database is the same as a temp-file that is never written out to
61774 ** This function is called after transitioning from PAGER_UNLOCK to
61775 ** PAGER_SHARED state. It tests if there is a hot journal present in
61776 ** the file-system for the given pager. A hot journal is one that
61782 ** * The database file itself is greater than 0 bytes in size, and
61783 ** * The first byte of the journal file exists and is not 0x00.
61785 ** If the current size of the database file is 0 but a journal file
61786 ** exists, that is probably an old journal left over from a prior
61787 ** database with the same name. In this case the journal file is
61788 ** just deleted using OsDelete, *pExists is set to 0 and SQLITE_OK
61789 ** is returned.
61791 ** This routine does not check if there is a super-journal filename
61792 ** at the end of the file. If there is, and that super-journal file
61793 ** does not exist, then the journal file is not really hot. In this
61795 ** routine will discover that the journal file is not really hot and
61798 ** If a hot-journal file is found to exist, *pExists is set to 1 and
61799 ** SQLITE_OK returned. If no hot-journal file is present, *pExists is
61802 ** code is returned and the value of *pExists is undefined.
61807 int exists = 1; /* True if a journal file is present */
61829 ** is the case, this routine might think there is a hot journal when
61830 ** in fact there is none. This results in a false-positive which will
61840 /* If the database is zero pages in size, that means that either (1) the
61841 ** journal is a remnant from a prior database with the same name where
61843 ** transaction that populates a new database is being rolled back.
61845 ** not to delete the journal file if it is already open due to
61857 ** or greater lock on the database file. Now check that there is
61859 ** If there is, then we consider this journal to be hot. If not,
61880 ** ticket #3883. Either way, assume that the journal is hot.
61881 ** This might be a false positive. But if it is, then the
61898 ** This function is called to obtain a shared lock on the database file.
61899 ** It is illegal to call sqlite3PagerGet() until after this function
61900 ** has been successfully called. If a shared-lock is already held when
61901 ** this function is called, it is a no-op.
61905 ** 1) If the pager is currently in PAGER_OPEN state (no lock held
61906 ** on the database file), then an attempt is made to obtain a
61908 ** the SHARED lock, the file-system is checked for a hot-journal,
61909 ** which is played back if present. Following any hot-journal
61914 ** 2) If the pager is running in exclusive-mode, and there are currently
61915 ** no outstanding references to any pages, and is in the error state,
61916 ** then an attempt is made to clear the error state by discarding
61920 ** If everything is successful, SQLITE_OK is returned. If an IO error
61922 ** rolling back a journal file, the IO error code is returned.
61927 /* This routine is only called from b-tree and only when there are no
61929 ** be OPEN or READER. READER is only possible if the pager is or was in
61948 /* If a journal file exists, and there is no RESERVED lock on the
61963 /* Get an EXCLUSIVE lock on the database file. At this point it is
61964 ** important that a RESERVED lock is not obtained on the way to the
61967 ** database is safe to read while this process is still rolling the
61970 ** Because the intermediate RESERVED lock is not requested, any
61975 ** Unless the pager is in locking_mode=exclusive mode, the lock is
61983 /* If it is not already open and the file exists on disk, open the
61984 ** journal for read/write access. Write access is required because
61987 ** is usually required to finalize the journal in journal_mode=persist
62034 /* This branch is taken if an error occurs while trying to open
62042 ** PAGER_ERROR now. This is not actually counted as a transition
62069 ** a 32-bit counter that is incremented with each change. The
62071 ** a codec is in use.
62073 ** There is a vanishingly small chance that a change will not be
62074 ** detected. The chance of an undetected change is so small that
62091 /* Unmap the database file. It is possible that external processes
62095 ** to be the right size but is not actually valid. Avoid this
62103 /* If there is a WAL file in the file-system, open this database in WAL
62104 ** mode. Otherwise, the following function call is a no-op.
62137 ** Except, in locking_mode=EXCLUSIVE when there is nothing to in
62138 ** the rollback journal, the unlock is not performed and there is
62139 ** nothing to rollback, so this routine is a no-op.
62143 assert( pPager->nMmapOut==0 ); /* because page1 is never memory mapped */
62150 ** page with page number pgno. If the requested reference is
62151 ** successfully obtained, it is copied to *ppPage and SQLITE_OK returned.
62157 ** getPageError() -- Used if the pager is in an error state
62158 ** getPageMmap() -- Used if memory-mapped I/O is enabled
62160 ** If the requested page is already in the cache, it is returned.
62161 ** Otherwise, a new page object is allocated and populated with data
62166 ** The extra data appended to a page is always initialized to zeros the
62167 ** first time a page is loaded into memory. If the page requested is
62168 ** already in the cache when this function is called, then the extra
62169 ** data is left as it was when the page object was last used.
62171 ** If the database image is smaller than the requested page or if
62173 ** requested page is not already stored in the cache, then no
62175 ** page is initialized to all zeros.
62177 ** If PAGER_GET_NOCONTENT is true, it means that we do not care about
62182 ** b) When a savepoint is being rolled back and we need to load
62186 ** If PAGER_GET_NOCONTENT is true, then the data returned is zeroed instead
62190 ** savepoints are set. This means if the page is made writable at any
62195 ** an appropriate error code is returned and *ppPage is set to NULL.
62198 ** to find a page in the in-memory cache first. If the page is not already
62213 u8 noContent; /* True if PAGER_GET_NOCONTENT is set */
62249 ** (*) obsolete. Was: maximum page number is 2^31
62270 /* Failure to set the bits in the InJournal bit-vectors is benign.
62310 /* The page getter for when memory-mapped I/O is enabled */
62321 /* It is acceptable to use a read-only (mmap) page for any page except
62322 ** page 1 if there is no write-transaction open or the ACQUIRE_READONLY
62323 ** flag was specified by the caller. And so long as the db is not a
62334 ** common case where pgno is large. */
62379 /* The page getter method for when the pager is an error state */
62419 ** Acquire a page if it is already in the in-memory cache. Do
62421 ** or 0 if the page is not in cache.
62424 ** and sqlite3PagerGet() is that _get() will go to the disk and read
62425 ** in the page if the page is not already in cache. This routine
62426 ** returns NULL if the page is not in cache or if a disk I/O error
62444 ** if we know that the page being released is not the last reference to page1.
62447 ** The assert() at tag-20230419-2 proves that this constraint is always
62458 assert( pPg->pgno!=1 ); /* Page1 is never memory mapped */
62473 assert( (pPg->flags & PGHDR_MMAP)==0 ); /* Page1 is never memory mapped */
62480 ** This function is called at the start of every write transaction.
62482 ** file when this routine is called.
62486 ** as well. This function is only used when the journal file is being
62487 ** opened to write a rollback log for a transaction. It is not used
62490 ** If the journal file is already open (as it may be in exclusive mode),
62494 ** Whether or not the journal file is opened by this function, the
62495 ** Pager.pInJournal bitvec structure is allocated.
62497 ** Return SQLITE_OK if everything is successful. Otherwise, return
62509 /* If already in the error state, this function is a no-op. But on
62510 ** the other hand, this routine is never called if we are already in
62520 /* Open the journal file if it is not already open. */
62577 ** write-transaction has already been opened, this function is a no-op.
62579 ** If the exFlag argument is false, then acquire at least a RESERVED
62580 ** lock on the database file. If exFlag is true, then acquire at least
62581 ** an EXCLUSIVE lock. If such a lock is already held, no locking
62584 ** If the subjInMemory argument is non-zero, then any sub-journal opened
62586 ** has no effect if the sub-journal is already opened (as it may be when
62588 ** sub-journal. If the subjInMemory argument is zero, then any required
62589 ** sub-journal is implemented in-memory if pPager is an in-memory database,
62603 /* If the pager is configured to use locking_mode=exclusive, and an
62604 ** exclusive lock on the database is not already held, obtain it now.
62616 ** The busy-handler is not invoked if another connection already
62622 ** is true, then immediately upgrade this to an EXCLUSIVE lock. The
62637 ** This is because in those states the code to roll back savepoint
62679 ** Otherwise, when the transaction is rolled back, the logic in
62712 ** Mark a single data page as writeable. The page is written into the
62713 ** main journal or sub-journal as required. If the page is written into
62714 ** one of the journals, the corresponding bit is set in the
62722 /* This routine is not called unless a write-transaction has already
62724 ** It is never called in the ERROR state.
62737 ** rollback journal might not yet be open. Open it now if this is the case.
62739 ** This is done before calling sqlite3PcacheMakeDirty() on the page.
62751 /* Mark the page that is about to be modified as dirty. */
62754 /* If a rollback journal is in use, them make sure the page that is about
62755 ** to change is in the rollback journal, or if the page is a new page off
62756 ** then end of the file, make sure it is marked as PGHDR_NEED_SYNC.
62778 /* The PGHDR_DIRTY bit is set above when the page was added to the dirty-list
62785 /* If the statement journal is open and the page is not in it,
62800 ** This is a variant of sqlite3PagerWrite() that runs when the sector size
62801 ** is larger than the page size. SQLite makes the (reasonable) assumption that
62806 ** Usually, the sector size is less than or equal to the page size, in which
62808 ** exceptional case where the page size is smaller than the sector size.
62813 Pgno pg1; /* First page of the sector pPg is located on. */
62820 /* Set the doNotSpill NOSYNC bit to 1. This is because we cannot allow
62830 ** of the first page of the sector pPg is located on.
62868 /* If the PGHDR_NEED_SYNC flag is set for any of the nPage pages
62896 ** The difference between this function and pager_write() is that this
62901 ** If an error occurs, SQLITE_NOMEM or an IO error code is returned
62924 ** to sqlite3PagerWrite(). In other words, return TRUE if it is ok
62934 ** A call to this routine tells the pager that it is not necessary to
62941 ** on the given page is unused. The pager marks the page as clean so
62951 ** current transaction is rolled back.
62966 ** This routine is called to increment the value of the database file
62969 ** 92 is also updated, as is the SQLite version number at offset 96.
62971 ** But this only happens if the pPager->changeCountDone flag is false.
62976 ** If the isDirectMode flag is zero, then this is done by calling
62979 ** transaction is committed.
62983 ** if isDirect is non-zero, then the database file is updated directly
62996 ** atomic-write optimization is enabled in this build, then isDirect
62997 ** is initialized to the value passed as the isDirectMode parameter
62998 ** to this function. Otherwise, it is always set to zero.
63000 ** The idea is that if the atomic-write optimization is not
63022 /* If page one was fetched successfully, and this function is not
63024 ** direct mode, page 1 is always held in cache and hence the PagerGet()
63025 ** above is always successful - hence the ALWAYS on rc==SQLITE_OK.
63046 ** next time a read transaction is opened the cache will be
63064 ** Sync the database file to disk. This is a no-op for in-memory databases
63067 ** If successful, or if called on a pager for which it is a no-op, this
63068 ** function returns SQLITE_OK. Otherwise, an IO error code is returned.
63083 ** This function may only be called while a write-transaction is active in
63084 ** rollback. If the connection is in WAL mode, this call is a no-op.
63086 ** the database file, an attempt is made to obtain one.
63088 ** If the EXCLUSIVE lock is already held or the attempt to obtain it is
63089 ** successful, or the connection is in WAL mode, SQLITE_OK is returned.
63090 ** Otherwise, either SQLITE_BUSY or an SQLITE_IOERR_XXX error code is
63112 ** journal file. zSuper may be NULL, which is interpreted as no
63117 ** * The database file change-counter is updated,
63118 ** * the journal is synced (unless the atomic-write optimization is used),
63120 ** * the database file is truncated (if required), and
63123 ** The only thing that remains to commit the transaction is to finalize
63130 ** If the final parameter - noSync - is true, then the database file itself
63131 ** is not synced. The caller must call sqlite3PagerSync() directly to
63164 /* If this is an in-memory db, or no pages have been written to, or this
63165 ** function has already been called, it is mostly a no-op. However, any
63189 /* The bBatch boolean is true if the batch-atomic-write commit method
63190 ** should be used. No rollback journal is created if batch-atomic-write
63191 ** is enabled.
63211 ** * This commit is not part of a multi-file transaction, and
63215 ** pager_incr_changecounter() function is called to update the change
63216 ** counter in 'indirect-mode'. If the optimization is compiled in but
63217 ** is not applicable to this transaction, call sqlite3JournalCreate()
63222 ** Otherwise, if the optimization is both enabled and applicable,
63242 ** property of the host file-system, this is safe.
63266 ** or if zSuper is NULL (no super-journal), then this call is a no-op.
63272 ** If the atomic-update optimization is being used, this sync will not
63276 ** atomic-update optimization is used it is almost certain that the
63278 ** on a system under memory pressure it is just possible that this is
63279 ** not the case. In this case it is likely enough that the redundant
63328 /* If the file on disk is smaller than the database image, use
63332 ** last page is never written out to disk, leaving the database file
63333 ** undersized. Fix this now if it is the case. */
63358 ** When this function is called, the database file has been completely
63366 ** for hot-journal rollback. Once this is done the transaction is
63369 ** If an error occurs, an IO error code is returned and the pager
63370 ** moves into the error state. Otherwise, SQLITE_OK is returned.
63388 ** this transaction, the pager is running in exclusive-mode and is
63389 ** using persistent journals, then this function is a no-op.
63392 ** header with the nRec field set to 0. If such a journal is used as
63394 ** to the database file. So there is no need to zero the journal
63395 ** header. Since the pager is in exclusive mode, there is no need
63413 ** If a write transaction is open, then all changes made within the
63414 ** transaction are reverted and the current write-transaction is closed.
63418 ** If the pager is already in PAGER_ERROR state when this function is called,
63419 ** it returns Pager.errCode immediately. No work is performed in this case.
63427 ** 2) It finalizes the journal file, so that it is not used for hot
63430 ** Finalization of the journal file (task 2) is only performed if the
63431 ** rollback is successful.
63436 ** WAL files. The WAL transaction is then closed.
63442 /* PagerRollback() is a no-op if called in READER or OPEN state. If
63443 ** the pager is already in the ERROR state, the rollback is not
63444 ** attempted here. Instead, the error code is returned to the caller.
63485 ** Return TRUE if the database file is opened read-only. Return FALSE
63486 ** if the database is (in theory) writable.
63522 ** This routine is used for testing and analysis only.
63543 ** or _WRITE+1. The SQLITE_DBSTATUS_CACHE_WRITE+1 case is a translation
63544 ** of SQLITE_DBSTATUS_CACHE_SPILL. The _SPILL case is not contiguous because
63547 ** Before returning, *pnVal is incremented by the
63549 ** reset parameter is non-zero, the cache hit or miss count is zeroed before
63573 ** Return true if this is an in-memory or temp-file backed pager.
63582 ** to make up the difference. If the number of savepoints is already
63583 ** equal to nSavepoint, then this function is a no-op.
63585 ** If a memory allocation fails, SQLITE_NOMEM is returned. If an error
63586 ** occurs while opening the sub-journal file, then an IO error code is
63648 ** This function is called to rollback or release (commit) a savepoint.
63652 ** Parameter op is always either SAVEPOINT_ROLLBACK or SAVEPOINT_RELEASE.
63653 ** If it is SAVEPOINT_RELEASE, then release and destroy the savepoint with
63654 ** index iSavepoint. If it is SAVEPOINT_ROLLBACK, then rollback all changes
63657 ** The savepoint to rollback or release is identified by parameter
63660 ** on the most recently created savepoint. If iSavepoint is greater than
63661 ** (Pager.nSavepoint-1), then this function is a no-op.
63663 ** If a negative value is passed to this function, then the current
63664 ** transaction is rolled back. This is different to calling
63670 ** are destroyed. If this is a release operation (op==SAVEPOINT_RELEASE),
63671 ** then savepoint iSavepoint is also destroyed.
63675 ** savepoint. If no errors occur, SQLITE_OK is returned.
63706 /* Only truncate if it is an in-memory sub-journal. */
63715 /* Else this is a rollback operation, playback the specified savepoint.
63716 ** If this is a temp-file, it is possible that the journal file has
63748 ** Except, if the pager is in-memory only, then return an empty string if
63749 ** nullIfMemDb is true. This routine is called with nullIfMemDb==1 when
63755 ** The return value to this routine is always safe to use with
63807 ** pgno (which we call pPgOld) though that page is allowed to be
63808 ** in cache. If the page previously located at pgno is not already
63809 ** in the rollback journal, it is not put there by by this routine.
63813 ** allocated along with the page) is the responsibility of the caller.
63815 ** A transaction must be active when this routine is called. It used to be
63818 ** transaction is active).
63820 ** If the fourth argument, isCommit, is non-zero, then this page is being
63822 ** is being committed. In this case, it is guaranteed that the database page
63830 Pgno needSyncPgno = 0; /* Old value of pPg->pgno, if sync is required */
63849 /* If the page being moved is dirty and has not been saved by the latest
63851 ** sub-journal now. This is required to handle the following scenario:
63861 ** statement were is processed.
63864 ** one or more savepoint bitvecs. This is the reason this function
63880 ** If the isCommit flag is set, there is no need to remember that
63928 /* If needSyncPgno is non-zero, then the journal file needs to be
63929 ** sync()ed before any data is written to database file page needSyncPgno.
63931 ** "is journaled" bitvec flag has been set. This needs to be remedied by
63937 ** array. Otherwise, if the page is loaded and written again in
63939 ** it is synced into the journal file. This way, it may end up in
63940 ** the journal file twice, but that is not a problem.
63991 ** PAGER_LOCKINGMODE_EXCLUSIVE. If the parameter is not _QUERY, then
63992 ** the locking-mode is set to the value specified.
63994 ** The returned value is either PAGER_LOCKINGMODE_NORMAL or
64021 ** The journalmode is set to the value specified if the change is allowed.
64034 /* The eMode parameter is always valid */
64042 /* This routine is only called from the OP_JournalMode opcode, and
64065 ** mode except WAL, unless the pager is in locking_mode=exclusive mode,
64077 /* In this case we would like to delete the journal file. If it is
64078 ** not possible, then that is not a problem. Deleting the journal file
64079 ** here is an optimization only.
64082 ** database file. This ensures that the journal file is not deleted
64083 ** while it is in use by some other client.
64126 ** Return TRUE if the pager is in a state where it is OK to change the
64128 ** is unmodified.
64140 ** Setting the size limit to -1 means no limit is enforced.
64141 ** An attempt to set a limit smaller than -1 is a no-op.
64163 ** Unless this is an in-memory or temporary database, clear the pager cache.
64174 ** This function is called when the user invokes "PRAGMA wal_checkpoint",
64178 ** Parameter eMode is one of SQLITE_CHECKPOINT_PASSIVE, FULL or RESTART.
64189 /* This only happens when a database file is zero bytes in size opened and
64190 ** then "PRAGMA journal_mode=WAL" is run and then sqlite3_wal_checkpoint()
64191 ** is invoked without any intervening transactions. We need to start
64192 ** a transaction to initialize pWal. The PRAGMA table_list statement is
64227 ** is obtained instead, immediately release it.
64246 ** Call sqlite3WalOpen() to open the WAL handle. If the pager is in
64247 ** exclusive-locking mode when this function is called, take an EXCLUSIVE
64257 /* If the pager is already in exclusive-mode, the WAL module will use
64260 ** file, to make sure this is safe.
64285 ** If the pager passed as the first argument is open on a real database
64287 ** is not already open, make an attempt to open it now. If successful,
64289 ** not support the xShmXXX() methods, return an error code. *pbOpen is
64292 ** If the pager is open on a temp-file (or in-memory database), or if
64293 ** the WAL file is already open, set *pbOpen to 1 and return SQLITE_OK
64298 int *pbOpen /* OUT: Set to true if call is a no-op */
64327 ** This function is called to close the connection to the log file prior
64332 ** error (SQLITE_BUSY) is returned and the log connection is not closed.
64333 ** If successful, the EXCLUSIVE lock is not released before returning.
64340 /* If the log file is not already open, but does exist in the file-system,
64357 /* Checkpoint and close the log. Because an EXCLUSIVE lock is held on
64375 ** If pager pPager is a wal-mode database not in exclusive locking mode,
64401 ** If this is a WAL database, obtain a snapshot handle for the snapshot
64413 ** If this is a WAL database, store a pointer to pSnapshot. Next time a
64414 ** read transaction is opened, attempt to read from the snapshot it
64415 ** identifies. If this is not a WAL database, return an error.
64431 ** If this is a WAL database, call sqlite3WalSnapshotRecover(). If this
64432 ** is not a WAL database, return an error.
64446 ** If this is not a WAL database, SQLITE_ERROR is returned. Otherwise,
64448 ** checks if the snapshot passed as the second argument is still
64449 ** available. If so, SQLITE_OK is returned.
64451 ** If the snapshot is not available, SQLITE_ERROR is returned. Or, if
64453 ** occurs (any value other than SQLITE_OK is returned), the CHECKPOINTER
64454 ** lock is released before returning.
64480 ** A read-lock must be held on the pager when this function is called. If
64481 ** the pager is in WAL mode and the WAL file currently contains one or more
64483 ** WAL frames. Otherwise, if this is not a WAL database or the WAL file
64484 ** is empty, return 0.
64506 ** a legal notice, here is a blessing:
64522 ** frames into the WAL. Transactions commit when a frame is written that
64524 ** multiple transactions. Periodically, the content of the WAL is
64535 ** The WAL header is 32 bytes in size and consists of the following eight
64549 ** of page data. The frame-header is six big-endian 32-bit unsigned
64560 ** A frame is considered valid if and only if the following conditions are
64571 ** The checksum is computed using 32-bit big-endian integers if the
64572 ** magic number in the first 4 bytes of the WAL is 0x377f0683 and it
64573 ** is computed using little-endian if the magic number is 0x377f0682.
64575 ** big-endian format regardless of which byte order is used to compute
64576 ** the checksum. The checksum is computed by interpreting the input as
64578 ** algorithm used for the checksum is as follows:
64590 ** On a checkpoint, the WAL is first VFS.xSync-ed, then valid content of the
64591 ** WAL is transferred into the database, then the database is VFS.xSync-ed.
64596 ** After each checkpoint, the salt-1 value is incremented and the salt-2
64597 ** value is randomized. This prevents old and new frames in the WAL from
64605 ** last valid instance of page P that is a followed by a commit frame
64606 ** or is a commit frame itself becomes the value read. If the WAL
64608 ** frame or are followed by a commit frame, then page P is read from
64623 ** WAL is large (multiple megabytes is typical) that scan can be slow,
64625 ** data structure called the wal-index is maintained to expedite the
64630 ** Conceptually, the wal-index is shared memory, though VFS implementations
64632 ** the wal-index is shared memory, SQLite does not support journal_mode=WAL
64636 ** In the default unix and windows implementation, the wal-index is a mmapped
64637 ** file whose name is the database name with a "-shm" suffix added. For that
64638 ** reason, the wal-index is sometimes called the "shm" file.
64640 ** The wal-index is transient. After a crash, the wal-index can (and should
64641 ** be) reconstructed from the original WAL file. In fact, the VFS is required
64643 ** connection to it closes. Because the wal-index is transient, it can
64649 ** The purpose of the wal-index is to answer this question quickly: Given
64673 ** The page-mapping is an array of HASHTABLE_NPAGE (or HASHTABLE_NPAGE_ONE
64694 ** HASHTABLE_NSLOT = 2*HASHTABLE_NPAGE, and there is one entry in the
64696 ** table is never more than half full. The expected number of collisions
64697 ** prior to finding a match is 1. Each entry of the hash table is an
64711 ** (wrapping around to the beginning when the end of the hash table is
64712 ** reached) until an unused hash slot is found. Let the first unused slot
64714 ** wrap-around.) Because the hash table is never more than half full,
64715 ** the search is guaranteed to eventually hit an unused entry. Let
64717 ** where aHash[iMax]==P. If there is no iMax entry (if there exists
64718 ** no hash slot such that aHash[i]==p) then page P is not in the
64732 ** is much faster than scanning the entire 10MB WAL.
64743 ** in the first place - which is what reader one wants. Meanwhile, the
64745 ** later, which is exactly what reader two wants.
64747 ** When a rollback occurs, the value of K is decreased. Hash table entries
64770 ** values in the wal-header are correct and (b) the version field is not
64774 ** checksum test is successful) and finds that the version field is not
64775 ** WALINDEX_MAX_VERSION, then no read-transaction is opened and SQLite
64782 ** Index numbers for various locking bytes. WAL_NREADER is the number
64784 ** is SQLITE_SHM_NLOCK==8 and WAL_NREADER==5.
64787 ** they see fit. However, compatibility is encouraged so that VFSes can
64789 ** is for the index number to indicate a byte offset into the
64792 ** should be 120) is the location in the shm file for the first locking
64816 ** the total header size is 136 bytes.
64841 ** nBackfill is the number of frames in the WAL that have been written
64843 ** database "backfilling".) The nBackfill number is never greater than
64847 ** mxFrame back to zero when the WAL is reset.
64849 ** nBackfillAttempted is the largest value of nBackfill that a checkpoint
64851 ** the nBackfillAttempted is set before any backfilling is done and the
64852 ** nBackfill is only set after all backfilling completes. So if a checkpoint
64856 ** The aLock[] field is a set of bytes used for locking. These bytes should
64859 ** There is one entry in aReadMark[] for each reader lock. If a reader
64860 ** holds read-lock K, then the value in aReadMark[K] is no greater than
64862 ** for any aReadMark[] means that entry is unused. aReadMark[0] is
64863 ** a special case; its value is never used and it exists as a place-holder
64869 ** is holding an exclusive lock on WAL_READ_LOCK(K). Thus, the value of
64870 ** aReadMark[K] cannot changed while there is a reader is using that mark
64874 ** the frame numbers are less than or equal to every aReadMark[] that is
64875 ** in use (that is, every aReadMark[j] for which there is a corresponding
64878 ** is not already an aReadMark[] equal to mxFrame. The exception to the
64879 ** previous sentence is when nBackfill equals mxFrame (meaning that everything
64905 ** This is a schematic view of the complete 136-byte header of the
64970 ** WALINDEX_LOCK_OFFSET is reserved for locks. Since some systems
64984 ** significant bit also set (WAL_MAGIC | 0x00000001) is stored in 32-bit
64987 ** If the LSB is set, then the checksums for each frame within the WAL
64997 ** is to the start of the write-ahead log frame-header.
65004 ** An open write-ahead log file is represented by an instance of the
65017 i16 readLock; /* Which read lock is being held. -1 for none */
65019 u8 exclusiveMode; /* Non-zero if connection is in exclusive mode */
65026 u8 bShmUnreliable; /* SHM content is read-only and unreliable */
65062 #define WAL_RDONLY 1 /* The WAL file is readonly */
65063 #define WAL_SHM_RDONLY 2 /* The SHM file is readonly */
65072 ** This structure is used to implement an iterator that loops through
65084 ** This functionality is used by the checkpoint code (see walCheckpoint()).
65100 ** is a hash-table following every HASHTABLE_NPAGE page numbers in the
65112 ** wal-index is smaller than usual. This is so that there is a complete
65117 /* The wal-index is divided into pages of WALINDEX_PGSZ bytes each. */
65123 ** Structured Exception Handling (SEH) is a Windows-specific technique
65151 ** The second argument is the return value of GetExceptionCode() for the
65161 ** ExceptionInformation[] array is a read-write flag - 0 if the exception
65162 ** was thrown while reading, 1 if while writing. The second element is
65173 ** If one is configured, invoke the xTestCallback callback with 650 as
65174 ** the argument. If it returns true, throw the same exception that is
65175 ** thrown by the system if the *-shm file mapping is accessed after it
65194 ** if an exception is thrown:
65210 ** to be set to pValue if an exception is thrown:
65231 ** is broken into pages of WALINDEX_PGSZ bytes. Wal-index pages are
65234 ** If the wal-index is currently smaller the iPage pages then the size
65235 ** of the wal-index might be increased, but only if it is safe to do
65236 ** so. It is safe to enlarge the wal-index if pWal->writeLock is true
65245 ** Scenario (3) can only occur when pWal->writeLock is false and iPage==0
65343 ** The checksum is written back into aOut[] before returning.
65408 ** If there is the possibility of concurrent access to the SHM file
65433 ** The checksum on pWal->hdr is updated before it is written.
65451 ** supplied by the caller. A frame-header is made up of a series of
65490 ** in aData[] is valid. If it is a valid frame, fill *piPage and
65491 ** *pnTruncate and return true. Return if the frame is not valid.
65505 /* A frame is only valid if the salt values in the frame-header
65512 /* A frame is only valid if the page number is greater than zero.
65519 /* A frame is only valid if a checksum of the WAL header,
65534 /* If we reach this point, the frame is valid. Return the page number
65545 ** Names of locks. This routine is used to provide debugging output and is not
65635 ** An instance of the WalHashLoc object is used to describe the location
65642 volatile u32 *aPgno; /* aPgno[1] is the page of first frame indexed */
65648 ** page iHash of the wal-index. The wal-index is broken into 32KB pages
65654 ** slot in the hash table is set to N, it refers to frame number
65657 ** Finally, set pLoc->aPgno so that pLoc->aPgno[0] is the page number of the
65687 ** iFrame. The wal-index is broken up into 32KB pages. Wal-index pages
65718 ** This function is called whenever pWal->hdr.mxFrame is decreased due
65740 ** the entry that corresponds to frame pWal->hdr.mxFrame. It is guaranteed
65741 ** that the page said hash-table and array reside on is already mapped.(1)
65746 if( NEVER(i) ) return; /* Defense-in-depth, in case (1) above is wrong */
65767 /* Verify that the every entry in the mapping region is still reachable
65805 /* If this is the first entry to be added to this hash-table, zero the
65814 /* If the entry in aPgno[] is already set, then the previous writer
65844 /* Verify that the every entry in the mapping region is reachable
65872 ** with the WAL or wal-index while recovery is running. The
65873 ** WAL_RECOVER_LOCK is also held so that other threads will know
65874 ** that this thread is running recovery. If unable to establish
65884 ** locked by the caller. The caller is guaranteed to have locked the
65917 int isValid; /* True if this frame is valid */
65927 /* If the database page size is not a power of two, or is greater than
65929 ** data. Similarly, if the 'magic' value is invalid, ignore the whole
65946 /* Verify that the WAL header checksum is correct */
65956 /* Verify that the version number on the WAL format is one that
66002 /* If nTruncate is non-zero, this is a commit record. */
66021 ** cause a concurrent reader to malfunction. Memcpy() is allowed to
66023 ** we know of actually does that, which is why we say that memcpy()
66024 ** is safe for this. Memcpy() is certainly a lot faster.
66028 /* In the event that some platform is found for which memcpy()
66030 ** setting the final value, this alternative copy routine is
66038 ** the value needs to be changed, that means it is not being
66061 /* Reset the checkpoint-header. This is safe because this thread is
66085 ** event via sqlite3_log(). This is to help with identifying performance
66125 ** is called. The purpose of this SHARED lock is to prevent any other
66130 ** If the log file is successfully opened, SQLITE_OK is returned and
66131 ** *ppWal is set to point to a new WAL handle. If an error occurs,
66132 ** an SQLite error code is returned and *ppWal is left unmodified.
66152 ** fail is a backward compatibility problem, even if the change otherwise
66184 ** value of 120, we need to know that so there is an assert() to check it.
66235 ** Change the size to which the WAL file is truncated on each reset.
66257 u32 iRet = 0xFFFFFFFF; /* 0xffffffff is never a valid page number */
66284 ** aLeft[] and aRight[] are arrays of indices. The sort key is
66286 ** is guaranteed for all J<K:
66294 ** above is still met.
66431 ** nBackfill or earlier may be included - excluding them is an optimization
66436 ** returns an error, the value of *pp is undefined.
66451 ** it only runs if there is actually content in the log (mxFrame>0).
66523 ** they are supported by the VFS, and (b) the database handle is configured
66547 ** If parameter bLock is true, attempt to enable blocking locks, take
66549 ** cannot be enabled, no attempt to obtain the WRITER lock is made. Return
66550 ** an SQLite error code if an error occurs, or SQLITE_OK otherwise. It is not
66553 ** If the bLock parameter is false and the WRITER lock is held, release it.
66591 ** n. If the attempt fails and parameter xBusy is not NULL, then it is a
66593 ** lock is successfully obtained or the busy-handler returns 0.
66624 ** The following is guaranteed when this function is called:
66626 ** a) the WRITER lock is held,
66636 ** The value of parameter salt1 is used as the aSalt[1] value in the
66665 ** SQLite is in WAL-mode in synchronous=NORMAL. That means that if
66669 ** Fsync is called on the WAL before writing content out of the WAL and
66670 ** into the database. This ensures that if the new content is persistent
66673 ** Fsync is also called on the database file if (and only if) the entire
66674 ** WAL content is copied into the database file. This second fsync makes
66679 ** This is the only routine that will increase the value of nBackfill.
66684 ** checkpoint is running (in any other thread or process) at the same
66712 /* EVIDENCE-OF: R-62920-47450 The busy-handler callback is never invoked
66716 /* Compute in mxSafeFrame the index of the last frame of the WAL that is
66766 /* If the size of the final database is larger than the current
66827 /* If this is an SQLITE_CHECKPOINT_RESTART or TRUNCATE operation, and the
66872 ** If the WAL file is currently larger than nMax bytes in size, truncate
66891 ** This is the "standard" exception handler used in a few places to handle
66893 ** invalid in SQLITE_USE_SEH builds. It is used as follows:
66937 ** by the connenction, is consistent with the Wal.readLock, Wal.writeLock
66961 ** EXCEPTION_IN_PAGE_ERROR exception is caught.
66994 ** connection associated with this log file is the only connection to
66998 ** The EXCLUSIVE lock is not released before returning.
67022 ** WAL mode (bPersist) and if the PRAGMA journal_size_limit is a
67047 ** there is a problem.
67049 ** The wal-index is in shared memory. Another thread or process might
67050 ** be writing the header at the same time this procedure is trying to
67051 ** read it, which might result in inconsistency. A dirty read is detected
67055 ** If and only if the read is consistent and the header is different from
67056 ** pWal->hdr, then pWal->hdr is updated to the content of the new header
67057 ** and *pChanged is set to 1.
67060 ** is read successfully and the checksum verified, return zero.
67072 ** meaning it is possible that an inconsistent snapshot is read
67082 ** here would be problematic as the memory being accessed is potentially
67115 ** This is the value that walTryBeginRead returns when it needs to
67125 ** Set *pChanged to 1 if the wal-index header value in pWal->hdr is
67126 ** changed by this operation. If pWal->hdr is unchanged, set *pChanged
67129 ** If the wal-index header is successfully read, return SQLITE_OK.
67138 ** wal-index header) is mapped. Return early if an error occurs here.
67146 ** was openable but is not writable, and this thread is unable to
67148 ** open, and hence the content of the shared-memory is unreliable,
67150 ** and there is no writer on hand to fix it. */
67158 return rc; /* Any other non-OK return is just an error */
67161 /* page0 can be NULL if the SHM is zero bytes in size and pWal->writeLock
67162 ** is zero, which prevents the SHM from growing */
67169 ** works, but may fail if the wal-index header is corrupt or currently
67192 /* If the wal-index header is still malformed even while holding
67193 ** a WRITE lock, it can only mean that the header is corrupted and
67209 /* If the header is read successfully, check the version number to make
67233 ** Open a transaction in a connection where the shared-memory is read-only
67234 ** and where we cannot verify that there is a separate write-capable connection
67237 ** This can happen, for example, when the shared-memory is implemented by
67239 ** left the *-shm file on disk, and now the present connection is trying
67251 ** is set to true before returning if the caller should discard the
67257 ** If an error occurs, an SQLite error code is returned.
67287 ** is SQLITE_READONLY instead of SQLITE_READONLY_CANTINIT.
67289 ** If the shared-memory is now "reliable" return WAL_RETRY, which will
67293 ** This step is important because, even though this connection is holding
67296 ** is active, wrap the WAL and start overwriting frames that this
67304 ** This is a requirement on the VFS implementation.
67313 /* We reach this point only if the real shared-memory is still unreliable.
67314 ** Assume the in-memory WAL-index substitute is correct and load it
67327 /* If the wal file is too small to contain a wal-header and the
67364 ** heap-memory wal-index is discarded and WAL_RETRY returned to
67380 /* If nTruncate is non-zero, then a complete transaction has been
67407 ** The final argument passed to walTryBeginRead() is of type (int*). The
67415 ** The final value of "cnt" is of no use to the caller. It is used by
67418 ** + Each time walTryBeginRead() is called, it is incremented. Once
67423 ** + If SQLITE_ENABLE_SETLK_TIMEOUT is defined and walTryBeginRead() failed
67425 ** layer), the WAL_RETRY_BLOCKED_MASK bit is set in "cnt". In this case
67440 ** indicate to the caller that it is safe to retry immediately.
67443 ** I/O error or an SQLITE_BUSY because another process is running
67446 ** The useWal parameter is true to force the use of the WAL and disable
67447 ** the case where the WAL is bypassed because it has been completely
67450 ** wal-index header has changed, *pChanged is set to 1 (as an indication
67451 ** to the caller that the local page cache is obsolete and needs to be
67452 ** flushed.) When useWal==1, the wal-index header is assumed to already
67453 ** be loaded and the pChanged parameter is unused.
67461 ** and is not honoring the locking protocol. There is a vanishingly small
67463 ** bad luck when there is lots of contention for the wal-index, but that
67464 ** possibility is so small that it can be safely neglected, we believe.
67467 ** WAL_READ_LOCK(pWal->readLock). The pWal->readLock integer is
67470 ** access any database page that is modified by a WAL frame up to and
67475 ** If the useWal parameter is 1 then the WAL will never be ignored and
67477 ** When the read transaction is completed, the caller must release the
67503 /* Take steps to avoid spinning forever if there is a protocol error.
67508 ** if we are unlucky, another process that is holding a lock might get
67509 ** paged out or take a page-fault that is time-consuming to resolve,
67510 ** during the few nanoseconds that it is holding the lock. In that case,
67515 ** is more of a scheduler yield than an actual delay. But on the 10th
67518 ** The total delay time before giving up is less than 10 seconds.
67563 /* If there is not a recovery running in another thread or process
67564 ** then convert BUSY errors to WAL_RETRY. If recovery is known to
67565 ** be running, convert BUSY to BUSY_RECOVERY. There is a race here
67567 ** would be technically correct. But the race is benign since with
67572 /* This branch is taken when the xShmMap() method returns SQLITE_BUSY.
67573 ** We assume this is a transient condition, so return WAL_RETRY. The
67577 ** must be zeroed before the requested page is returned.
67604 /* The WAL has been completely backfilled (or it is empty).
67611 /* It is not safe to allow the reader to continue here if frames
67616 ** happening, this is usually correct.
67619 ** is wrapped and written for that matter) before the READ_LOCK(0)
67620 ** is obtained, that is not necessarily true. A checkpointer may
67635 ** the WAL to get at content from recent commits. The job now is
67636 ** to select one of the aReadMark[] entries that is closest to
67694 ** It is necessary to check that the wal-index header did not change
67710 ** Because a ShmBarrier() call is made between taking the copy of
67712 ** matches the one cached in pWal->hdr, it is guaranteed that the
67717 ** A) on the basis that there is a newer version (version B) of the same
67795 ** This is only really safe if the file-system is such that any page
67797 ** is not always true. It is also possible that nBackfillAttempted
67802 ** SQLITE_OK is returned if successful, or an SQLite error code if an
67803 ** error occurs. It is not an error if nBackfillAttempted cannot be
67856 /* It is possible that there is a checkpointer thread running
67857 ** concurrent with this code. If this is the case, it may be that the
67859 ** snapshot X, where X is later in the wal file than pSnapshot, but
67862 ** there is no checkpointer process by taking a shared CKPT lock
67888 ** is populated with the wal-index header corresponding to the head
67889 ** of the wal file. Verify that pSnapshot is still valid before
67921 ** from the start of the wal file. This is because, for a system
67925 ** is the same database page. */
67950 ** that extra content is ignored by the current thread.
67953 ** transaction, then *pChanged is set to 1 before returning. The
67954 ** Pager layer will use this to know that its cache is stale and
67967 ** Finish with a read transaction. All this does is release the
67980 ** contains the page. Otherwise, if pgno is not in the wal file, set *piRead
67984 ** error does occur, the final value of *piRead is undefined.
67996 /* This routine is only be called from within a read transaction. */
67999 /* If the "last page" field of the wal-index header snapshot is 0, then
68002 ** then the WAL is ignored by the reader so return early, as if the
68025 ** loop of the following block is more stringent that would be required
68089 ** contains the page. Otherwise, if pgno is not in the wal file, set *piRead
68093 ** error does occur, the final value of *piRead is undefined.
68095 ** The difference between this function and walFindFrame() is that this
68113 ** (which is nOut bytes in size). Return SQLITE_OK if successful, or an
68151 ** the read transaction was started, then it is not possible for this
68153 ** returns SQLITE_BUSY in that case and no write transaction is started.
68161 /* If the write-lock is already held, then it was obtained before the
68190 ** the write is disallowed.
68224 ** Additionally, the callback function is invoked for each frame written
68226 ** other than SQLITE_OK, it is not invoked again and the error code is
68249 ** is passed as the second argument is (a) in the cache and
68250 ** (b) has an outstanding reference, then xUndo is either a no-op
68251 ** (if (a) is false) or simply expels the page from the cache (if (b)
68252 ** is false).
68254 ** If the upper layer is doing a rollback, it is guaranteed that there
68256 ** page 1 is never written to the log until the transaction is
68318 ** This function is called just before writing a set of frames to the log
68320 ** to the current log file, it is possible to overwrite the start of the
68322 ** it sets pWal->hdr.mxFrame to 0. Otherwise, pWal->hdr.mxFrame is left
68325 ** SQLITE_OK is returned if no error is encountered (regardless of whether
68326 ** or not pWal->hdr.mxFrame is modified). An SQLite error code is returned
68347 ** at this point. But updating the actual wal-index header is also
68348 ** safe and means there is no special case for sqlite3WalUndo()
68349 ** to handle if this transaction is rolled back. */
68388 ** In other words, if iSyncPoint is in between iOffset and iOffset+iAmt,
68436 ** This function is called as part of committing a transaction within which
68441 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
68455 ** first checksum. If the first frame is frame 1 (implying that the current
68497 int isCommit, /* True if this is a commit */
68530 /* See if it is possible to write these frames into the start of the
68537 /* If this is the first frame written into the log, write the WAL
68568 /* Sync the header (unless SQLITE_IOCAP_SEQUENTIAL is true or unless
68569 ** all syncing is turned off by PRAGMA synchronous=OFF). Otherwise
68600 ** checksums must be recomputed when the transaction is committed. */
68635 /* If this is the end of a transaction, then we might need to pad
68642 ** If SQLITE_IOCAP_POWERSAFE_OVERWRITE is defined, then padding is not
68643 ** needed and only the sync is done. If padding is needed, then the
68644 ** final frame is repeated (with its commit mark) until the next sector
68645 ** boundary is crossed. Only the part of the WAL prior to the last
68646 ** sector boundary is synced; the part of the last frame that extends
68647 ** past the sector boundary is written after the sync.
68671 ** if PRAGMA journal_size_limit is set, then truncate the WAL to the
68683 /* Append data to the wal-index. It is not necessary to lock the
68686 ** be in use by existing readers is being overwritten.
68711 /* If this is a commit, update the wal-index header too. */
68726 ** The difference between this function and walFrames() is that this
68734 int isCommit, /* True if this is a commit */
68746 ** This routine is called to implement sqlite3_wal_checkpoint() and
68752 ** If parameter xBusy is not NULL, it is a pointer to a busy-handler
68768 int isChanged = 0; /* True if a new wal-index header is loaded */
68775 /* EVIDENCE-OF: R-62920-47450 The busy-handler callback is never invoked
68788 ** EVIDENCE-OF: R-10421-19736 If any other process is running a
68790 ** SQLITE_BUSY is returned.
68791 ** EVIDENCE-OF: R-53820-33897 Even if there is a busy-handler configured,
68805 ** immediately, and a busy-handler is configured, it is invoked and the
68807 ** lock is successfully obtained.
68828 ** attempt to obtain is a lock on a read-slot, and it should give up
68858 ** performed, then the pager-cache associated with pWal is now
68897 ** This function is called to change the WAL subsystem into or out
68900 ** If op is zero, then attempt to change from locking_mode=EXCLUSIVE
68902 ** on the pWal->readLock byte. If the WAL is already in locking_mode=NORMAL
68904 ** transition out of exclusive-mode is successful, return 1. This
68905 ** operation must occur while the pager is still holding the exclusive
68908 ** If op is one, then change from locking_mode=NORMAL into
68910 ** be released. Return 1 if the transition is made and 0 if the
68911 ** WAL is already in exclusive-locking mode - meaning that this
68912 ** routine is a no-op. The pager must already hold the exclusive lock
68915 ** If op is negative, then do a dry-run of the op==1 case but do
68925 /* pWal->readLock is usually set, but might be -1 if there was a
68927 ** happen if the connection is actually in exclusive mode (as no xShmLock
68960 ** Return true if the argument is non-NULL and the WAL module is using
68961 ** heap-memory for the wal-index. Otherwise, if the argument is NULL or the
68962 ** WAL module is using shared-memory, return false.
68969 /* Create a snapshot object. The content of a snapshot is opaque to
69005 ** Return a +ve value if snapshot p1 is newer than p2. A -ve value if
69006 ** p1 is older than p2 and zero if p1 and p2 are the same snapshot.
69012 /* aSalt[0] is a copy of the value stored in the wal file header. It
69013 ** is incremented each time the wal file is restarted. */
69024 ** checks if the snapshot passed as the second argument is still
69025 ** available. If so, SQLITE_OK is returned.
69027 ** If the snapshot is not available, SQLITE_ERROR is returned. Or, if
69029 ** occurs (any value other than SQLITE_OK is returned), the CHECKPOINTER
69030 ** lock is released before returning.
69064 ** If the argument is not NULL, it points to a Wal object that holds a
69065 ** read-lock. This function returns the database page-size if it is known,
69066 ** or zero if it is not (or if pWal is NULL).
69088 ** a legal notice, here is a blessing:
69097 ** This code really belongs in btree.c. But btree.c is getting too
69107 ** a legal notice, here is a blessing:
69121 ** The basic idea is that each page of the file contains N database
69135 ** disk where M is the number of entries in the tree.
69138 ** BTrees. Each BTree is identified by the index of its root page. The
69141 ** page. If the payload is larger than the preset amount then surplus
69149 ** The file is divided into pages. The first page is called page 1,
69150 ** the second is page 2, and so forth. A page number of zero indicates
69155 ** The first page is always a btree page. The first 100 bytes of the first
69157 ** The format of the file header is as follows:
69188 ** The file change counter is incremented when the database is changed
69192 ** The max embedded payload fraction is the amount of the total usable
69195 ** is to limit the maximum cell size so that at least 4 cells will fit
69196 ** on one page. Thus the default max embedded payload fraction is 64.
69198 ** If the payload for a cell is larger than the max payload, then extra
69199 ** payload is spilled to overflow pages. Once an overflow page is allocated,
69203 ** The min leaf payload fraction is like the min embedded payload fraction
69205 ** payload fraction for a LEAFDATA tree is always 100% (or 255) and it
69208 ** Each btree pages is divided into three sections: The header, the
69240 ** only keys and no data. The intkey flag means that the key is an integer
69241 ** which is stored in the key size entry of the cell header rather than in
69251 ** Cell content is stored at the very end of the page and grows toward the
69254 ** Unused space within the cell content area is collected into a linked list of
69255 ** freeblocks. Each freeblock is at least 4 bytes in size. The byte offset
69256 ** to the first freeblock is given in the header. Freeblocks occur in
69259 ** exist on the freeblock chain. A group of 3 or fewer free bytes is called
69260 ** a fragment. The total number of bytes in all fragments is recorded.
69269 ** that immediately follows the page header. Cells is not necessarily
69273 ** length integer is 1 to 9 bytes where the lower 7 bits of each
69294 ** 4 Page number of the left child. Omitted if leaf flag is set.
69295 ** var Number of bytes of data. Omitted if the zerodata flag is set.
69296 ** var Number of bytes of key. Or the key itself if intkey flag is set.
69300 ** Overflow pages form a linked list. Each page except the last is completely
69310 ** page points to multiple leaf pages. The content of a leaf page is
69321 /* The following value is the maximum cell size assuming a maximum page
69339 ** This is a magic string that appears at the beginning of every
69366 ** is derived from the raw on-disk page content.
69368 ** As each database page is loaded into memory, the pager allocates an
69369 ** instance of this object and zeros the first 8 bytes. (This is the
69372 ** Access to all fields of this structure is controlled by the mutex
69381 ** is allocated. All fields that follow must be initialized before use */
69396 BtShared *pBt; /* Pointer to BtShared that this page is part of */
69409 ** A linked list of the following structures is stored at BtShared.pLock.
69411 ** is opened on the table with root page BtShared.iTable. Locks are removed
69412 ** from this list when a transaction is committed or rolled back, or when
69413 ** a btree handle is closed.
69430 ** is opaque to the database connection. The database connection cannot
69470 ** If the shared-data extension is enabled, there may be multiple users
69499 ** to this one BtShared object. BtShared.nRef is the number of
69505 ** may not be modified once it is initially set as long as nRef>0.
69507 ** thereafter is unchanged as long as nRef>0.
69513 ** the shared-cache enters 'pending-lock' state and isPending is
69525 ** This feature is included to help prevent writer-starvation.
69534 u8 autoVacuum; /* True if auto-vacuum is enabled */
69535 u8 incrVacuum; /* True if incr-vacuum is enabled */
69567 #define BTS_READ_ONLY 0x0001 /* Underlying file is readonly */
69569 #define BTS_SECURE_DELETE 0x0004 /* PRAGMA secure_delete is enabled */
69578 ** An instance of the following structure is used to hold information
69592 ** this will be declared corrupt. This value is calculated based on a
69596 ** If a tree that appears to be taller than this is encountered, it is
69597 ** assumed that the database is corrupt.
69602 ** A cursor is a pointer to a particular entry within a particular
69605 ** The entry is identified by its MemPage and the index in
69609 ** but cursors cannot be shared. Each cursor is associated with a
69619 ** VALID skipNext is meaningless and is ignored
69620 ** INVALID skipNext is meaningless and is ignored
69621 ** SKIPNEXT sqlite3BtreeNext() is a no-op if skipNext>0 and
69622 ** sqlite3BtreePrevious() is no-op if skipNext<0.
69632 int skipNext; /* Prev() is noop if negative. Next() is noop if positive.
69637 /* All fields above are zeroed when the cursor is allocated. See
69659 #define BTCF_ValidNKey 0x02 /* True if info.nKey is valid */
69660 #define BTCF_ValidOvfl 0x04 /* True if aOverflow is valid */
69661 #define BTCF_AtLast 0x08 /* Cursor is pointing to the last entry */
69664 #define BTCF_Pinned 0x40 /* Cursor is busy and cannot be moved */
69671 ** because the table is empty or because BtreeCursorFirst() has not been
69678 ** Cursor is valid except that the Cursor.skipNext field is non-zero
69684 ** modified since the cursor was last used. The cursor position is saved
69685 ** in variables BtCursor.pKey and BtCursor.nKey. When a cursor is in
69703 ** The database page the PENDING_BYTE occupies. This page is never used.
69709 ** database page. The first argument to each is the number of usable
69710 ** bytes on each page of the database (often 1024). The second is the
69717 ** If the pgno argument passed to PTRMAP_PAGENO is a pointer-map page,
69718 ** then pgno is returned. So (pgno==PTRMAP_PAGENO(pgsz, pgno)) can be
69719 ** used to test if pgno is a pointer-map page. PTRMAP_ISPAGE implements
69727 ** The pointer map is a lookup table that identifies the parent page for
69728 ** each child page in the database file. The parent page is the page that
69731 ** to any page that is not part of the pointer map itself.) Each pointer map
69735 ** The purpose of the pointer map is to facility moving pages from one
69737 ** is moved, the pointer in its parent must be updated to point to the
69738 ** new location. The pointer map is used to locate the parent page quickly.
69740 ** PTRMAP_ROOTPAGE: The database page is a root-page. The page-number is not
69743 ** PTRMAP_FREEPAGE: The database page is an unused (free) page. The page-number
69744 ** is not used in this case.
69746 ** PTRMAP_OVERFLOW1: The database page is the first page in a list of
69750 ** PTRMAP_OVERFLOW2: The database page is the second or later page in a list of
69754 ** PTRMAP_BTREE: The database page is a non-root btree page. The page number
69772 ** The ISAUTOVACUUM macro is used within balance_nonroot() to determine
69773 ** if the database supports auto-vacuum or not. Because it is used
69774 ** within an expression that is an argument to another macro
69775 ** (sqliteMallocRaw), it is not possible to use conditional compilation.
69776 ** So, this macro is defined instead.
69786 ** This structure is passed around through all the PRAGMA integrity_check
69789 ** The aRef[] array is allocated so that there is 1 bit for each page in
69791 ** the database the corresponding bit is set. This allows integrity-check to
69824 ** two-byte aligned address. get2byteAligned() is only used for accessing the
69878 ** If the object is not sharable, then no mutex is ever required
69879 ** and this routine is a no-op. The underlying mutex is non-recursive.
69881 ** of this interface is recursive.
69884 ** by all database connections. The p->pNext is a list of other
69909 /* Unless the database is sharable and unlocked, then BtShared.db
69919 /* This is a helper function for sqlite3BtreeLock(). By moving
69976 ** Return true if the BtShared mutex is held on the btree, or if the
69977 ** B-Tree is not marked as sharable.
69979 ** This routine is used only from within assert() statements.
69994 ** connection. This is needed (for example) prior to parsing
69999 ** There is a corresponding leave-all procedures.
70041 ** This routine is used inside assert() statements only.
70069 ** If pSchema is not NULL, then iDb is computed from pSchema and
70093 ** If shared cache is disabled, then all btree mutex routines, including
70115 ** These entry points are used by incremental I/O only. Enter() is required
70116 ** any time OMIT_SHARED_CACHE is not defined, regardless of whether or not
70117 ** the build is threadsafe. Leave() is only required by threadsafe builds.
70137 ** a legal notice, here is a blessing:
70169 ** But if the value is zero, make it 65536.
70171 ** This routine is used to extract the "offset to cell content area" value
70172 ** from the header of a btree page. If the page size is 65536 and the page
70173 ** is empty, the offset should be 65536, but the 2-byte value stores zero.
70186 ** Macro IfNotOmitAV(x) returns (x) if SQLITE_OMIT_AUTOVACUUM is not
70187 ** defined, or 0 if it is. For example:
70204 ** Access to this variable is protected by SQLITE_MUTEX_STATIC_MAIN.
70234 ** shared-cache table level locks. If the library is compiled with the
70235 ** shared-cache feature disabled, then there is only ever one user
70236 ** of each BtShared structure and so this locking is not necessary.
70262 ** If SQLITE_DEBUG is not defined, then this macro is equivalent to
70263 ** SQLITE_CORRUPT_BKPT. Or, if SQLITE_DEBUG is set, then the log message
70264 ** normally produced as a side-effect of SQLITE_CORRUPT_BKPT is augmented
70290 **** This function is only used as part of an assert() statement. ***
70308 ** hold a write-lock on the schema table (root page 1). This is also
70314 int isIndex, /* True if iRoot is the root of an index b-tree */
70321 /* If this database is not shareable, or if the client is reading
70322 ** and has the read-uncommitted flag set, then no lock is required.
70331 /* If the client is reading or writing an index and the schema is
70332 ** not loaded, then it is too difficult to actually check to see if
70341 ** b-trees, this is just the root page of the b-tree being read or
70342 ** written. For index b-trees, it is the root page of the associated
70352 ** be imposter tables. So just return true. The assert is not
70365 ** write-lock on the schema table, or (if the client is reading) a
70389 ** It is illegal for pBtree to write if some other Btree object that
70390 ** shares the same BtShared object is currently reading or writing
70392 ** read-uncommitted flag set, then it is OK for the other object to
70436 /* This routine is a no-op if the shared-cache is not enabled */
70441 /* If some other connection is holding an exclusive lock, the
70451 ** statement is a simplification of:
70482 ** (a) The specified Btree object p is connected to a sharable
70489 ** SQLITE_OK is returned if the lock is added successfully. SQLITE_NOMEM
70490 ** is returned if a malloc attempt fails.
70503 ** by a connection in read-uncommitted mode is on the sqlite_schema
70504 ** table, and that lock is obtained in BtreeBeginTrans(). */
70584 /* This function is called when Btree p is concluding its
70585 ** transaction. If there currently exists a writer, and p is not
70590 ** If there is not currently a writer, then BTS_PENDING must
70591 ** be zero already. So this next line is harmless in that case.
70620 ***** This routine is used inside of assert() only ****
70629 /* Verify that the cursor and the BtShared agree about what is the current
70630 ** database connetion. This is important in shared-cache mode. If the database
70631 ** connection pointers get out-of-sync, it is possible for routines like
70633 ** a connection that has already closed. This routine is used inside assert()
70663 ** This function is called before modifying the contents of a table
70667 ** If argument isClearTable is true, then the entire contents of the
70668 ** table is about to be deleted. In this case invalidate all incrblob
70671 ** Otherwise, if argument isClearTable is false, then the row with
70672 ** rowid iRow is being replaced or deleted. In this case invalidate
70696 /* Stub function when INCRBLOB is omitted */
70701 ** Set bit pgno of the BtShared.pHasContent bitvec. This is called
70709 ** 1) When all data is deleted from a page and the page becomes
70710 ** a free-list leaf page, the page is not written to the database
70712 ** such a page is not even journalled (as it will not be modified,
70715 ** 2) When a free-list leaf page is reused, its content is not read
70717 ** be, if it is not at all meaningful?).
70721 ** a page is moved to the free-list and then reused within the same
70722 ** transaction, a problem comes up. If the page is not journalled when
70723 ** it is moved to the free-list and it is also not journalled when it
70724 ** is extracted from the free-list and reused, then the original data
70728 ** The solution is the BtShared.pHasContent bitvec. Whenever a page is
70729 ** moved to become a free-list leaf page, the corresponding bit is
70730 ** set in the bitvec. Whenever a leaf page is extracted from the free-list,
70731 ** optimization 2 above is omitted if the corresponding bit is already
70753 ** This function is called when a free-list leaf page is removed from the
70754 ** free-list for reuse. It returns false if it is safe to retrieve the
70787 ** when this function is called (i.e. have eState==CURSOR_VALID). This
70789 ** pCur->pKey. SQLITE_OK is returned if successful or an SQLite error
70792 ** If the cursor is open on an intkey table, then the integer key
70793 ** (the rowid) is stored in pCur->nKey and pCur->pKey is left set to
70794 ** NULL. If the cursor is open on a non-intkey table, then pCur->pKey is
70805 /* Only the rowid is required for a table btree */
70808 /* For an index btree, save the complete key content. It is possible
70809 ** that the current key is corrupt. In that case, it is possible that
70812 ** position is restored. Hence the 17 bytes of padding allocated
70835 ** and BtCursor.pKey. The cursor's state is set to CURSOR_REQUIRESEEK.
70837 ** The caller must ensure that the cursor is valid (has eState==CURSOR_VALID)
70872 ** the location in the btree is remembered in such a way that it can be
70874 ** routine is called just before cursor pExcept is used to modify the
70883 ** then the BTCF_Multiple flag on pExpect is cleared, to avoid another
70903 ** the cursors if and when a cursor is found that actually requires saving.
70904 ** The common case is that no cursors need to be saved, so this routine is
70940 ** In this version of BtreeMoveto, pKey is a packed index record
70941 ** such as is generated by the OP_MakeRecord opcode. Unpack the
70946 const void *pKey, /* Packed key if the btree is an index */
71014 ** Cursors can move when the row they are pointing at is deleted out
71016 ** is rebalanced.
71047 ** On success, the *pDifferentRow parameter is false if the cursor is left
71048 ** pointing at exactly the same row. *pDifferntRow is the row the cursor
71076 ** and number of the varargs parameters) is determined by the eHintType
71116 ** Return 0 (not a valid page) for pgno==1 since there is
71140 ** If *pRC is initially non-zero (non-SQLITE_OK) then this routine is
71141 ** a no-op. If an error occurs, the appropriate error code is written
71169 /* The first byte of the extra data is the MemPage.isInit byte.
71170 ** If that byte is set, it means this page is also being used
71201 ** An error code is returned if something goes wrong, otherwise SQLITE_OK.
71246 ** 4-byte child pointer found on interior pages, if there is one.
71257 ** This is common tail processing for btreeParseCellPtr() and
71269 ** overflow pages. The strategy is to minimize the amount of unused
71273 ** Warning: changing the way overflow payload is distributed in any
71321 ** There is also a wrapper function btreeParseCell() that works for
71357 /* The next block of code is equivalent to:
71361 ** The code is inlined to avoid a function call.
71373 /* The next block of code is equivalent to:
71377 ** The code is inlined and the loop is unrolled for performance.
71378 ** This routine is a high-runner.
71418 /* This is the (easy) common case where the entire payload fits
71419 ** on the local page. No overflow is required.
71455 /* This is the (easy) common case where the entire payload fits
71456 ** on the local page. No overflow is required.
71467 int iCell, /* The cell index. First cell is 0 */
71495 ** cell. If SQLITE_DEBUG is defined, an assert() at the bottom of
71496 ** this function verifies that this invariant is not violated. */
71537 ** cell. If SQLITE_DEBUG is defined, an assert() at the bottom of
71538 ** this function verifies that this invariant is not violated. */
71578 ** cell. If SQLITE_DEBUG is defined, an assert() at the bottom of
71579 ** this function verifies that this invariant is not violated. */
71600 ** cell. If SQLITE_DEBUG is defined, an assert() at the bottom of
71601 ** this function verifies that this invariant is not violated. */
71647 /* This variation on cellSizePtr() is used inside of assert() statements
71656 ** The cell pCell is currently part of page pSrc but will ultimately be part
71684 ** Parameter nMaxFrag is the maximum amount of fragmented space that may be
71722 ** or fewer fragmented bytes. In this case it is faster to move the
71724 ** offsets to each pointer in the cell-pointer array than it is to
71819 ** This function may detect corruption within pPg. If corruption is
71820 ** detected then *pRc is set to SQLITE_CORRUPT and NULL is returned.
71839 ** freeblock form a big-endian integer which is the size of the freeblock
71891 ** The caller guarantees that there is sufficient space to make the
71895 ** allocation is being made in order to insert a new cell, so we will
71909 assert( nByte>=0 ); /* Minimum cell size is 4 */
71918 ** and the reserved space is zero (the usual value for reserved space)
71920 ** However, that integer is too large to be stored in a 2-byte unsigned
71921 ** integer, so a value of 0 is used in its place. */
71934 /* If there is enough space between gap and top for one more cell pointer,
71935 ** and if the freelist is not empty, then search the
71958 ** to see if defragmentation is necessary.
71973 ** validated the freelist. Given that the freelist is valid, there
71974 ** is no way that the allocation can extend off the end of the page.
71986 ** The first byte of the new free block is pPage->aData[iStart]
71987 ** and the size of the block is iSize bytes.
72013 assert( iSize>=4 ); /* Minimum cell size is 4 */
72022 iFreeBlk = 0; /* Shortcut for the case when the freelist is empty */
72053 /* If iPtr is another freeblock (that is, if iPtr is not the freelist
72073 ** option is enabled */
72077 /* The new freeblock is at the beginning of the cell content area,
72192 ** the start of the cell content area. A zero value for this integer is
72200 ** start of the first freeblock on the page, or is zero if there are no
72235 ** the cell-content area. If this is greater than the usable-size
72289 ** guarantee that the page is well-formed. It only shows that
72326 /* EVIDENCE-OF: R-24089-57979 If a page contains no cells (which is only
72333 pPage->nFree = -1; /* Indicate that this value is yet uncomputed */
72399 ** If the PAGER_GET_NOCONTENT flag is set, it means that we do not care
72424 ** Retrieve a page from the pager cache. If the requested page is not
72439 ** Return the size of the database file in pages. If there is any kind of
72493 ** Page1 is a special case and must be released using releasePageOne().
72523 ** * If the page is already in use for some other purpose, immediately
72525 ** * Make sure the isInit flag is clear
72550 ** so that the cache is restored to its original state at the start of
72551 ** the transaction, for each page restored this routine is called.
72567 ** But no harm is done by this. And it is very important that
72588 ** zFilename is the name of the database file. If zFilename is NULL
72589 ** then an ephemeral database is created. The ephemeral database might
72592 ** when sqlite3BtreeClose() is called.
72594 ** If zFilename is ":memory:" then an in-memory database is created
72595 ** that is automatically destroyed when it is closed.
72597 ** The "flags" parameter is a bitmask that might contain bits like
72600 ** If the database is already opened in the same database connection
72643 /* A BTREE_SINGLE database is always a temporary and/or ephemeral */
72665 ** If this Btree is a candidate for shared cache, try to find an
72739 ** the right size. This is to guard against size changes that result
72778 /* EVIDENCE-OF: R-51873-39618 The page size for a database file is
72788 ** SQLITE_DEFAULT_AUTOVACUUM is true. On the other hand, if
72789 ** SQLITE_OMIT_MEMORYDB has been defined, then ":memory:" is just a
72799 /* EVIDENCE-OF: R-37497-42412 The size of the reserved region is
72839 ** The list is kept in ascending order by pBt address.
72905 ** false if it is still positive.
72949 /* This routine is called only by btreeCursor() when allocating the
72960 /* One of the uses of pBt->pTmpSpace is to format cells before
72962 ** a cell is less than 4 bytes in size, it is rounded up to 4 bytes
72966 ** it into a database page. This is not actually a problem, but it
72968 ** data is passed to system call write(). So to avoid this error,
73027 /* The pBt is no longer on the sharing list, so we can access
73057 ** cache is allowed to grow larger than this limit if it contains
73075 ** The value returned is the current spill size. If zero is passed
73077 ** using mxPage of 0 is a way to query the current spill size.
73105 ** Change the way data is synced to disk in order to increase or decrease
73107 ** failures. Level 1 is the same as asynchronous (no syncs() occur and
73108 ** there is a high probability of damage) Level 2 is the default. There
73109 ** is a very low but non-zero probability of damage. Level 3 reduces the
73132 ** size supplied does not meet this constraint then the page size is not
73140 ** If parameter nReserve is less than zero, then the number of reserved
73141 ** bytes per page is left unchanged.
73143 ** If the iFix!=0 then the BTS_PAGESIZE_FIXED flag is set so that the page size
73183 ** This function is similar to sqlite3BtreeGetReserve(), except that it
73184 ** may only be called if it is guaranteed that the b-tree mutex is already
73187 ** This is useful in one special case in the backup API code where it is
73188 ** known that the shared b-tree mutex is held, but the mutex on the
73189 ** database handle that owns *p is not. In this case if sqlite3BtreeEnter()
73202 ** are intentionally left unused. This is the "reserved" space that is
73205 ** The value returned is the larger of the current reserve size and
73220 ** Set the maximum page count for a database if mxPage is positive.
73221 ** No changes are made if mxPage is 0 or negative.
73236 ** newFlag==1 BTS_SECURE_DELETE set and BTS_OVERWRITE is cleared
73237 ** newFlag==2 BTS_SECURE_DELETE cleared and BTS_OVERWRITE is set
73240 ** This routine acts as a query if newFlag is less than zero
73242 ** With BTS_OVERWRITE set, deleted content is overwritten by zeros, but
73244 ** deleted content is cleared, but freelist deleted content is not.
73246 ** With BTS_SECURE_DELETE, operation is like BTS_OVERWRITE with the addition
73267 ** parameter is non-zero, then auto-vacuum mode is enabled. If zero, it
73268 ** is disabled. The default value for the auto-vacuum property is
73292 ** Return the value of the 'auto-vacuum' property. If auto-vacuum is
73293 ** enabled 1 is returned. Otherwise 0.
73313 ** using "PRAGMA synchronous", and if the safety-level is not already
73346 ** SQLITE_OK is returned on success. If the file is not a
73347 ** well-formed database file, then SQLITE_CORRUPT is returned.
73348 ** SQLITE_BUSY is returned if the database is locked. SQLITE_NOMEM
73349 ** is returned if we run out of memory.
73364 /* Do some checking to help insure the file we opened really is
73402 /* If the read version is set to 2, this database should be accessed
73403 ** in WAL mode. If the log is not already open, open it now. Then
73405 ** The caller detects this and calls this function again. This is
73437 /* EVIDENCE-OF: R-51873-39618 The page size for a database file is
73441 /* EVIDENCE-OF: R-25008-21688 The size of a page is a power of two
73451 ** integer at offset 20 is the number of bytes of space at the end of
73454 ** EVIDENCE-OF: R-37497-42412 The size of the reserved region is
73460 ** of BtShared.pageSize, we have discovered that the page-size is
73482 /* EVIDENCE-OF: R-28312-64704 However, the usable size is not allowed to
73483 ** be less than 480. In other words, if the page size is 512, then the
73497 /* maxLocal is the maximum amount of payload to store locally for
73498 ** a cell. Make sure it is small enough so that at least minFanout
73506 ** So a cell consists of a 2-byte pointer, a header which is as much as
73532 ** Return the number of cursors open on pBt. This is for use
73533 ** in assert() expressions, so it is only compiled if NDEBUG is not
73536 ** Only write cursors are counted if wrOnly is true. If wrOnly is
73539 ** For the purposes of this routine, a cursor is any cursor that
73540 ** is capable of reading or writing to the database. Cursors that
73556 ** of a transaction but there is a read lock on the database, then
73560 ** If there is a transaction in progress, this routine is a no-op.
73634 ** is started if the second argument is nonzero, otherwise a read-
73635 ** transaction. If the second argument is 2 or more and exclusive
73636 ** transaction is started, meaning that no other process is allowed
73643 ** will work unless a transaction is started first:
73655 ** if there is one. But if there was previously a read-lock, do not
73656 ** invoke the busy handler - just return SQLITE_BUSY. SQLITE_BUSY is
73657 ** returned when there is already a read-lock in order to avoid a deadlock.
73660 ** a reserved lock. B tries to promote to exclusive but is blocked because
73661 ** of A's read lock. A tries to promote to reserved but is blocked by B.
73679 /* If the btree is already in a write-transaction, or it
73680 ** is already in a read-transaction and a read-transaction
73681 ** is requested, this is a no-op.
73704 ** on this shared-btree structure and a second write transaction is
73749 /* Call lockBtree() until either pBt->pPage1 is populated or
73753 ** file is not pBt->pageSize. In this case lockBtree() will update
73767 ** called and SQLITE_BUSY_SNAPSHOT is returned, change the error
73810 /* If the db-size header field is incorrect (as it may be if an old
73832 ** open savepoints. If the second parameter is greater than 0 and
73833 ** the sub-journal is not already open, then it will be opened here.
73857 ** open savepoints. If the second parameter is greater than 0 and
73858 ** the sub-journal is not already open, then it will be opened here.
73905 ** Somewhere on pPage is a pointer to page iFrom. Modify this pointer so
73909 ** PTRMAP_BTREE: pPage is a btree-page. The pointer points at a child
73912 ** PTRMAP_OVERFLOW1: pPage is a btree-page. The pointer points at an overflow
73915 ** PTRMAP_OVERFLOW2: pPage is an overflow-page. The pointer points at the next
73922 /* The pointer is always the first 4 bytes of the page in this case. */
73977 ** The isCommit flag indicates that there is no need to remember that
74014 ** If pDbPage is an overflow page, then the first 4 bytes may store a
74015 ** pointer to a subsequent overflow page. If this is the case, then
74061 ** SQLITE_OK. If there is no work to do (and therefore no point in
74066 ** that the last page of the file currently in use is no longer in use.
74068 ** Parameter nFin is the number of pages that this database would contain
74071 ** If the bCommit parameter is non-zero, this function assumes that the
74073 ** or an error. bCommit is passed true for an auto-vacuum-on-commit
74102 /* Remove the page from the files free-list. This is not required
74103 ** if bCommit is non-zero. In that case, the free-list will be
74127 /* If bCommit is zero, this loop runs exactly once and page pLastPg
74128 ** is swapped with the first free page pulled off the free list.
74130 ** On the other hand, if bCommit is greater than zero, then keep
74132 ** of the file is found.
74173 ** The database opened by the first argument is an auto-vacuum database
74199 ** If the incremental vacuum is finished after this function has run,
74200 ** SQLITE_DONE is returned. If it is not finished, but no error occurred,
74201 ** SQLITE_OK is returned. Otherwise an SQLite error code.
74237 ** This routine is called prior to sqlite3PagerCommit when a transaction
74238 ** is committed for an auto-vacuum database.
74264 /* It is not possible to create a database for which the final page
74265 ** is either a pointer-map page or the pending-byte page. If one
74266 ** is encountered, this indicates corruption.
74331 ** the disk. After the journal is safely on oxide, the changes to the
74338 ** This call is a no-op if no write-transaction is currently active on pBt.
74342 ** individual journal file, or is NULL, indicating no super-journal file
74345 ** When this is called, the super-journal should already have been
74348 ** Once this is routine has returned, the only thing required to commit
74349 ** the write-transaction for this database file is to delete the journal.
74375 ** This function is called from both BtreeCommitPhaseTwo() and BtreeRollback()
74422 ** routine has to do is delete or truncate or zero the header in the
74426 ** Normally, if an error occurs while the pager layer is attempting to
74429 ** is non-zero then this b-tree transaction is part of a multi-file
74434 ** transaction has been closed. This is quite safe, as the pager will have
74486 ** references. Or if the writeOnly flag is set to 1, then only
74489 ** Every cursor is a candidate to be tripped, including cursors
74494 ** flag is true, then only write-cursors need be tripped - read-only
74496 ** following the rollback. Or, if writeOnly is false, all cursors are
74497 ** tripped. In general, writeOnly is false if the transaction being
74502 ** If the writeOnly flag is true and an error is encountered while
74506 ** SQLITE_OK is returned if successful, or if an error occurs while
74539 ** state of the database. Assume pBt->pPage1 is valid.
74552 ** If tripCode is not SQLITE_OK then cursors will be invalidated (tripped).
74553 ** Only write cursors are tripped if writeOnly is true but all cursors are
74554 ** tripped if writeOnly is false. Any attempt to use
74592 ** sure pPage1->aData is set correctly. */
74610 ** before starting a subtransaction. The subtransaction is ended automatically
74618 ** A statement sub-transaction is implemented as an anonymous savepoint. The
74619 ** value passed as the second parameter is the total number of savepoints,
74622 ** iStatement is 1. This anonymous savepoint can be released or rolled back
74634 /* At the pager level, a statement transaction is a savepoint with
74636 ** SQL statements. It is illegal to open, release or rollback any
74637 ** such savepoints while the statement transaction savepoint is active.
74645 ** The second argument to this function, op, is always SAVEPOINT_ROLLBACK
74650 ** Normally, iSavepoint is greater than or equal to zero. However, if op is
74652 ** contents of the entire transaction are rolled back. This is different
74686 ** Create a new cursor for the BTree whose root is on the page
74687 ** iTable. If a read-only cursor is requested, it is assumed that
74689 ** on the database already. If a write-cursor is requested, then
74690 ** the caller is assumed to have an open write transaction.
74692 ** If the BTREE_WRCSR bit of wrFlag is clear, then the cursor can only
74693 ** be used for reading. If the BTREE_WRCSR bit is set, then the cursor
74711 ** is set. If FORDELETE is set, that is a hint to the implementation that
74713 ** as part of a larger DELETE statement. The FORDELETE hint is not used by
74716 ** rows are deleted, the FORDELETE flag is a hint that all SEEK and DELETE
74720 ** No checking is done to make sure that page iTable really is the
74721 ** root page of a b-tree. If it is not, then the cursor acquired
74724 ** It is assumed that the sqlite3BtreeCursorZero() has been called
74743 /* The following assert statements verify that if this is a sharable
74744 ** b-tree database, the connection is holding the required table locks,
74824 ** This interfaces is needed so that users of cursors can preallocate
74825 ** sufficient storage to hold a cursor. The BtCursor object is opaque
74846 ** Close a cursor. The read lock on the database file is released
74847 ** when the last cursor is closed.
74872 /* Since the BtShared is not sharable, there is no need to
74886 ** BtCursor.info structure. If it is not already valid, call
74889 ** BtCursor.info is a cache of the information in the current cell.
74921 ** Return true if the given BtCursor is valid. A valid cursor is one
74922 ** that is currently pointing to a row in a (non-empty) table.
74923 ** This is a verification routine is used only within assert() statements.
74936 ** This routine is only valid for a cursor that is pointing into a
74938 ** is invalid, the result of this routine is undefined.
74962 ** payload to which the cursor is pointing.
74973 ** Return the number of bytes of payload for the entry that pCur is
74977 ** The caller must guarantee that the cursor is pointing to a non-NULL
74990 ** that the cursor is pointing into.
74992 ** This is an optimization. Everything will still work if this
74993 ** routine always returns 2147483647 (which is the largest record
75013 ** If an error occurs an SQLite error code is returned. Otherwise:
75015 ** The page number of the next overflow page in the linked list is
75016 ** written to *pPgnoNext. If page ovfl is the last page in its linked
75017 ** list, *pPgnoNext is set to zero.
75019 ** If ppPage is not NULL, and a reference to the MemPage object corresponding
75020 ** to page number pOvfl was obtained, then *ppPage is set to point to that
75021 ** reference. It is the responsibility of the caller to call releasePage()
75024 ** *ppPage is set to zero.
75042 ** the overflow list is page number (ovfl+1). If that guess turns
75086 ** pPayload is a pointer to data stored on database page pDbPage.
75087 ** If argument eOp is false, then nByte bytes of data are copied
75088 ** from pPayload to the buffer pointed at by pBuf. If eOp is true,
75089 ** then sqlite3PagerWrite() is called on pDbPage and nByte bytes
75092 ** SQLITE_OK is returned on success, otherwise an error code.
75116 ** This function is used to read or overwrite payload information
75117 ** for the entry that the pCur cursor is pointing to. The eOp
75118 ** argument is interpreted as follows:
75120 ** 0: The operation is a read. Populate the overflow cache.
75121 ** 1: The operation is a write. Populate the overflow cache.
75124 ** Data is read to or from the buffer pBuf.
75137 ** the cursor is moved to a different row. Additionally, in auto-vacuum
75174 /* Trying to read or write past the end of the data is an error. The
75175 ** conditional above is really:
75177 ** but is recast into its current form to avoid integer overflow problems
75205 ** The aOverflow[] array is sized at one entry for each overflow page
75206 ** in the overflow chain. The page number of the first overflow page is
75208 ** means "not yet known" (the cache is lazily populated).
75228 ** entry for the first required overflow page is valid, skip
75248 /* The only reason to read this page is to obtain the page
75250 ** data is not required. So first try to lookup the overflow
75264 ** range of data that is being read (eOp==0) or written (eOp!=0).
75274 ** 1) this is a read operation, and
75275 ** 2) data is required from the start of this overflow page, and
75277 ** 4) the database is file-backed, and
75278 ** 5) the page is not in the WAL file
75331 ** Read part of the payload for the row at which that cursor pCur is currently
75336 ** If pointing to a table btree, then the content section is read. If
75337 ** pCur is pointing to an index b-tree then the key section is read.
75339 ** For sqlite3BtreePayload(), the caller must ensure that pCur is pointing
75344 ** wrong. An error is returned if "offset+amt" is larger than
75356 ** in the CURSOR_VALID state. It is only used by the sqlite3_blob_read()
75386 ** pCur cursor is pointing to. The pointer is to the beginning of
75387 ** the key if index btrees (pPage->intKey==0) and is the data for
75389 ** key/data is written into *pAmt. If *pAmt==0, then the value
75392 ** This routine is an optimization. It is common for the entire key
75394 ** pages. When that is so, this routine can be used to access the
75401 ** any btree routine is called.
75418 /* There is too little space on the page for the expected amount
75429 ** For the entry that cursor pCur is point to, return as
75433 ** The pointer returned is ephemeral. The key/data may move
75439 ** These routines is used to get quick access to key and data
75448 ** Move the cursor down to a new child page. The newPgno argument is the
75487 ** Page pParent is an internal (non-leaf) tree page. This function
75488 ** asserts that page number iChild is the left-child if the iIdx'th
75489 ** cell in page pParent. Or, if iIdx is equal to the total number of
75490 ** cells in pParent, that page number iChild is the right-child of
75510 ** pCur->idx is set to the cell index that contains the pointer
75512 ** right-most child page then pCur->idx is set to one more than
75538 ** If the table has a virtual root page, then the cursor is moved to point
75543 ** If the b-tree structure is empty, the cursor state is set to
75545 ** the cursor is set to point to the first cell located on the root
75546 ** (or virtual root) page and the cursor state is set to CURSOR_VALID.
75549 ** page-header flags indicate that the [virtual] root-page is the expected
75551 ** specify a KeyInfo structure the flags byte is set to 0x05 or 0x0D,
75553 ** structure the flags byte is set to 0x02 or 0x0A, indicating an index
75600 /* If pCur->pKeyInfo is not NULL, then the caller that opened this cursor
75601 ** expected to open it on an index b-tree. Otherwise, if pKeyInfo is
75602 ** NULL, the caller expects a table b-tree. If this is not the case,
75607 ** if pCur->iPage>=0). But this is not so if the database is corrupted
75608 ** in such a way that page pRoot is linked into a second b-tree table
75637 ** entry to which it is currently pointing.
75639 ** The left-most leaf is the one with the smallest key - the first
75659 ** page to which it is currently pointing. Notice the difference
75664 ** The right-most entry is the one with the largest key - the last
75688 ** or set *pRes to 1 if the table is empty.
75710 ** or set *pRes to 1 if the table is empty.
75734 /* If the cursor already points to the last entry, this is a no-op. */
75757 ** If an exact match is not found, then the cursor is always
75762 ** An integer is written into *pRes which is the result of
75763 ** comparing the key with the entry to which the cursor is
75765 ** *pRes is as follows:
75767 ** *pRes<0 The cursor is left pointing at an entry that
75768 ** is smaller than intKey or if the table is empty
75769 ** and the cursor is therefore left point to nothing.
75771 ** *pRes==0 The cursor is left pointing at an entry that
75774 ** *pRes>0 The cursor is left pointing at an entry that
75775 ** is larger than intKey.
75791 /* If the cursor is already positioned at the point we are trying
75803 /* If the requested key is one more than the previous key, then
75805 ** binary search. This is an optimization only. The correct answer
75806 ** is still obtained without this case, only a little more slowly. */
75848 /* pPage->nCell must be greater than zero. If this is the root-page
75850 ** not run. If this is not the root-page, then the moveToChild() routine
75920 ** Compare the "idx"-th cell on the page the cursor pCur is currently
75922 ** zero if the cell is less than or equal pIdxKey. Return positive
75927 ** Return value is zero: Cell at pCur[idx] equals pIdxKey
75929 ** Return value positive: Nothing is known about the relationship
75932 ** This routine is part of an optimization. It is always safe to return
75948 /* This branch runs if the record-size field of the cell is a
75956 /* The record-size field is a 2 byte varint and the record
75969 ** Return true (non-zero) if pCur is current pointing to the last
75985 ** If an exact match is not found, then the cursor is always
75990 ** An integer is written into *pRes which is the result of
75991 ** comparing the key with the entry to which the cursor is
75993 ** *pRes is as follows:
75995 ** *pRes<0 The cursor is left pointing at an entry that
75996 ** is smaller than pIdxKey or if the table is empty
75997 ** and the cursor is therefore left point to nothing.
75999 ** *pRes==0 The cursor is left pointing at an entry that
76002 ** *pRes>0 The cursor is left pointing at an entry that
76003 ** is larger than pIdxKey.
76005 ** The pIdxKey->eqSeen field is set to 1 if there
76035 ** (1) If the cursor is already pointing to the very last cell
76036 ** in the table and the pIdxKey search key is greater than or
76037 ** equal to that last cell, then no movement is required.
76039 ** (2) If the cursor is on the last page of the table and the first
76040 ** cell on that last page is less than or equal to the pIdxKey
76092 /* pPage->nCell must be greater than zero. If this is the root-page
76094 ** not run. If this is not the root-page, then the moveToChild() routine
76107 /* The maximum supported page-size is 65536 bytes. This means that
76109 ** page is less than 16384 bytes and may be stored as a 2-byte
76110 ** varint. This information is used to attempt to avoid parsing
76111 ** the entire cell by checking for the cases where the record is
76117 /* This branch runs if the record-size field of the cell is a
76125 /* The record-size field is a 2 byte varint and the record
76135 ** If the record is corrupt, the xRecordCompare routine may read
76137 ** bytes of padding is allocated at the end of the buffer in
76144 testcase( nCell<0 ); /* True if key size is 2^32 or more */
76203 /* This block is similar to an in-lined version of:
76240 ** Return TRUE if the cursor is not pointing at an entry of the table.
76244 ** the first entry. TRUE is also returned if the table is empty.
76247 /* TODO: What if the cursor is in CURSOR_REQUIRESEEK but all table entries
76255 ** Return an estimate for the number of rows in the table that pCur is
76256 ** pointing to. Return a negative number if no estimate is currently
76266 /* Currently this interface is only called by the OP_IfSmaller
76284 ** SQLITE_DONE cursor is already pointing at the last element
76287 ** The main entry point is sqlite3BtreeNext(). That routine is optimized
76290 ** routine is called when it is necessary to move to a different page or
76293 ** If bit 0x01 of the F argument in sqlite3BtreeNext(C,F) is 1, then the
76296 ** is a hint to the implement. SQLite btree implementation does not use
76378 ** SQLITE_DONE the cursor is already on the first element of the table
76381 ** The main entry point is sqlite3BtreePrevious(). That routine is optimized
76384 ** helper routine is called when it is necessary to move to a different page
76387 ** If bit 0x01 of the F argument to sqlite3BtreePrevious(C,F) is 1, then
76389 ** skipped if the SQL index had been a unique index. The F argument is a
76464 ** The new page is marked as dirty. (In other words, sqlite3PagerWrite()
76466 ** been referenced and the calling routine is responsible for calling
76467 ** sqlite3PagerUnref() on the new page when it is done.
76469 ** SQLITE_OK is returned on success. Any other return value indicates
76470 ** an error. *ppPage is set to NULL in the event of an error.
76472 ** If the "nearby" parameter is not 0, then an effort is made to
76477 ** If the eMode parameter is BTALLOC_EXACT and the nearby page exists
76478 ** anywhere on the free-list, then it is guaranteed to be returned. If
76479 ** eMode is BTALLOC_LT then the page returned will be less than or equal
76480 ** to nearby if any such page exists. If eMode is BTALLOC_ANY then there
76481 ** are no restrictions on which page is returned.
76516 ** shows that the page 'nearby' is somewhere on the free-list, then
76537 ** first free-list trunk page. iPrevTrunk is initially 1.
76543 /* The code within this loop is run only once if the 'searchList' variable
76544 ** is not true. Otherwise, it runs once for each trunk-page on the
76545 ** free-list until the page 'nearby' is located (eMode==BTALLOC_EXACT)
76546 ** or until a page less than 'nearby' is located (eMode==BTALLOC_LT)
76552 ** is the page number of the next freelist trunk page in the list or
76553 ** zero if this is the last freelist trunk page. */
76558 ** the freelist is empty. */
76574 ** is the number of leaf page pointers to follow. */
76577 /* The trunk has no leaves and the list is not being searched.
76591 /* Value of k is out of range. Database corruption */
76598 /* The list is being searched and this trunk page is the page
76619 /* The trunk page is required by the caller but it contains
76733 ** that is required in the event of a rollback. In this case, do
76754 ** becomes a new pointer-map page, the second is used by the caller.
76794 ** This function is used to add page iPage to the database file free-list.
76795 ** It is assumed that the page is not already a part of the free-list.
76797 ** The value passed as the second argument to this function is optional.
76802 ** If a pointer to a MemPage object is passed as the second argument,
76803 ** its reference count is not altered by this function.
76834 /* If the secure_delete option is enabled, then
76846 ** to indicate that the page is free.
76854 ** possibilities. If the free-list is currently empty, or if the first
76855 ** trunk page in the free-list is full, then this page will become a
76858 ** is possible to add the page as a new free-list leaf.
76880 /* In this case there is room on the trunk page to insert the page
76883 ** Note that the trunk page is not really full until it contains
76915 ** Possibly because the free-list is empty, or possibly because the
76916 ** first trunk in the free-list is full. Either way, the page being freed
76979 /* 0 is not a legal page number and page 1 cannot be an
76992 /* There is no reason any cursor should have an outstanding reference
76993 ** to an overflow page belonging to a cell that is being deleted/updated.
76996 ** It is helpful to detect this before calling freePage2(), as
76997 ** freePage2() may zero the page contents if secure-delete mode is
76999 ** caller is iterating through or using in some other way, this
77035 ** is responsible for making sure sufficient space has been allocated
77062 /* pPage is not necessarily writeable since pCell might be auxiliary
77063 ** buffer space that is separate from the pPage buffer area */
77086 /* This is the common case where everything fits on the btree page
77143 /* If pToRelease is not zero than pPayload points into the data area
77144 ** of pToRelease. Make sure pToRelease is still writeable. */
77147 /* If pPayload is part of the data area of pPage, then make sure pPage
77148 ** is still writeable */
77181 ** overflow page is being allocated, add an entry to the pointer-map
77184 ** If this is the first overflow page, then write a partial entry
77203 /* If pToRelease is not zero than pPrior points into the data area
77204 ** of pToRelease. Make sure pToRelease is still writeable. */
77207 /* If pPrior is part of the data area of pPage, then make sure pPage
77208 ** is still writeable */
77227 ** The cell content is not freed or deallocated. It is assumed that
77283 ** pTemp is not null. Regardless of pTemp, allocate a new entry
77287 ** pPage->nOverflow is incremented.
77387 ** for performance improvement, and also so that this variant is only
77388 ** called from that one place, and is thus inlined, and thus runs must
77470 ** in a balancing operation. NN is the number of neighbors on either side
77471 ** of the page that participate in the balancing operation. NB is the
77475 ** The minimum value of NN is 1 (of course). Increasing NN above 1
77482 ** But that is unlikely. NB has been 3 since the inception of SQLite and
77495 ** pRef is a pointer to one of the pages that contributes cells. This is
77517 ** The order of cells is in the array is for an index btree is:
77539 ** For a table-btree, the concept is similar, except only apEnd[0]..apEnd[2]
77548 ** entries, shift down. The end result is that each ixNx[] entry should
77607 ** The MemPage.nFree field is invalidated by this function. It is the
77666 /* The pPg->nFree field is now set incorrectly. The caller will fix it. */
77681 ** will fit), non-zero is returned. Otherwise, if the cells are added
77682 ** successfully, zero is returned.
77685 ** (part of page pPg) to populate. After cell apCell[0] is written to the
77686 ** page body, a 16-bit offset is written to pCellptr. And so on, for each
77687 ** cell in the array. It is the responsibility of the caller to ensure
77688 ** that it is safe to overwrite this part of the cell-pointer array.
77690 ** When this function is called, *ppData points to the start of the
77691 ** content area on page pPg. If the size of the content area is extended,
77692 ** *ppData is updated to point to the new start of the content area
77699 ** cells in apCell[], then the cells do not fit and non-zero is returned.
77761 ** that is currently stored within the body of pPg to the pPg free-list.
77833 ** The pPg->nFree field is invalid when this function returns. It is the
77945 ** a new entry is being inserted on the extreme right-end of the
77956 ** pPage is the leaf page which is the right-most page in the tree.
77957 ** pParent is its parent. pPage must have a single overflow entry
77958 ** which is also the right-most entry on the page.
77960 ** The pSpace buffer is used to store a temporary copy of the divider
78010 /* If this is an auto-vacuum database, update the pointer map
78013 ** operations fails, the return code is set, but the contents
78015 ** That is Ok, at this point the parent page is guaranteed to
78065 ** it is sometimes activated temporarily while debugging code responsible
78105 ** This function is used to copy the contents of the b-tree node stored
78108 ** parent page stored in the pointer map is page pTo. If pFrom contained
78110 ** map entries are also updated so that the parent page is page pTo.
78112 ** If pFrom is currently carrying any overflow cells (entries in the
78115 ** Before returning, page pTo is reinitialized using btreeInitPage().
78117 ** The performance of this function is not critical. It is only used by
78143 ** fairly obscure circumstances, even though it is a copy of initialized
78154 /* If this is an auto-vacuum database, update the pointer-map entries
78168 ** side if the page is the first or last child of its parent. If the page
78170 ** is a root page or a child of a root page) then all available siblings
78176 ** Note that when this routine is called, some of the cells on the page
78178 ** if the page is overfull. This routine ensures that all cells allocated
78184 ** happens, it is the responsibility of the caller to invoke the correct
78191 ** The third argument to this function, aOvflSpace, is a pointer to a
78193 ** page (pParent) the parent page becomes overfull, this buffer is
78196 ** size of a cell stored within an internal node is always less than 1/4
78197 ** of the page-size, the aOvflSpace[] buffer is guaranteed to be large
78200 ** If aOvflSpace is set to a null pointer, this function returns
78207 int isRoot, /* True if pParent is a root-page */
78208 int bBulk /* True if this call is part of a bulk load */
78217 u16 leafCorrection; /* 4 if pPage is a leaf. 0 if not */
78218 int leafData; /* True if pPage is a leaf of a LEAFDATA tree */
78233 u8 abDone[NB+2]; /* True after i'th new page is populated */
78244 ** this overflow cell is present, it must be the cell with
78246 ** is called (indirectly) from sqlite3BtreeDelete().
78257 ** that divide the siblings. An attempt is made to find NN siblings on
78318 ** This is safe because dropping a cell only overwrites the first
78320 ** four bytes of the divider cell. So the pointer is safe to use
78327 ** is allocated. */
78331 /* If the following if() condition is not true, the db is corrupted.
78378 ** leafCorrection: 4 if pPage is a leaf. 0 if pPage is not a leaf.
78405 ** Note that when there are multiple overflow cells, it is always the
78409 ** adjacent and are inserted in order. There is an assert() tagged
78415 ** long be able to find the cells if a pointer to each cell is not saved
78482 ** Store this number in "k". Also compute szNew[] which is the total
78483 ** size of all cells on the i-th page and cntNew[] which is the index
78561 ** The packing computed by the previous block is biased toward the siblings
78567 ** This adjustment is more than an optimization. The packing above might
78569 ** sibling might be completely empty. This adjustment is not optional.
78607 ** (2) pPage is a virtual root page. A virtual root page is when
78608 ** the real root page is page 1 and we are the only child of
78657 ** of the table is closer to a linear scan through the file. That in turn
78660 ** An O(N*N) sort algorithm is used, but since N is never more than NB+2
78661 ** (5), that is not a performance concern.
78677 /* If apNew[i] has a page number that is bigger than any of the
78715 ** of the right-most new sibling page is set to the value that was
78759 /* Cell pCell is destined for new sibling page pNew. Originally, it
78797 /* If the tree is a leaf-data tree, and the siblings are leaves,
78798 ** then there is no divider cell in b.apCell[]. Instead, the divider
78813 ** (see btreeParseCellPtr(), 4 bytes is the minimum size of
78814 ** any cell). But it is important to pass the correct size to
78818 ** and WITHOUT ROWID tables with exactly one column which is the
78841 ** is important, as this code needs to avoid disrupting any page from which
78845 ** then it is not safe to update page apNew[iPg] until after
78849 ** then it is not safe to update page apNew[iPg] until after
78852 ** If neither of the above apply, the page is safe to update.
78869 || cntOld[iPg-1]>=cntNew[iPg-1] /* Condition (1) is true */
78909 ** page is the right-child of the parent. Copy the contents of the
78911 ** b-tree structure by one. This is described as the "balance-shallower"
78914 ** If this is an auto-vacuum database, the call to copyNodeContent()
78916 ** for which the pointer is stored within the content being copied.
78918 ** It is critical that the child page be defragmented before being
78919 ** copied into the parent, because if the parent is page 1 then it will
78956 ** all pointer map pages are set correctly. This is helpful while
78957 ** debugging. This is usually disabled because a corrupt database may
78981 ** This function is called when the root page of a b-tree structure is
78984 ** A new child page is allocated and the contents of the current root
78986 ** page is then overwritten to make it an empty page with the right-child
78992 ** page is also updated.
78994 ** If successful, *ppChild is set to contain a reference to the child
78995 ** page and SQLITE_OK is returned. In this case the caller is required
78997 ** an error code is returned and *ppChild is set to 0.
79047 ** Return SQLITE_CORRUPT if any cursor other than pCur is currently valid
79050 ** This can occur if a database is corrupt with two or more SQL tables
79096 ** (2) The amount of free space on the page is less than 2/3rds of
79101 /* The root page of the b-tree is overfull. In this case call the
79121 /* The page being written is not a root page, and there is currently
79122 ** more than one reference to it. This only happens if the page is one
79146 ** happens, the overflow cell is stored in the aBalanceQuickSpace[]
79149 ** The purpose of the following assert() is to check that only a
79150 ** single call to balance_quick() is made for each call to this
79172 ** has completed, it is safe to release the pSpace buffer used by
79181 /* If pFree is not NULL, it points to the pSpace buffer used
79212 ** content is different from what is already there.
79243 /* In a corrupt database, it is possible for the source and destination
79244 ** buffers to overlap. This is harmless since the database is already
79254 ** Overwrite the cell that cursor pCur is pointing to with fresh content
79255 ** contained in pX. In this variant, pCur is pointing to an overflow
79270 assert( pCur->info.nLocal<nTotal ); /* pCur is an overflow cell */
79306 ** Overwrite the cell that cursor pCur is pointing to with fresh content
79319 /* The entire cell is local */
79331 ** is described by the pX object. The pCur cursor is used only to
79332 ** define what table the record should be inserted into, and is left
79336 ** the key is used. The pX.pKey value must be NULL. The pX.nKey is the
79341 ** key is an arbitrary byte sequence stored in pX.pKey,nKey. The
79344 ** If the seekResult parameter is non-zero, then a successful call to
79347 ** is currently pointing to a cell that will be adjacent to the cell
79348 ** to be inserted. If seekResult<0 then pCur points to a cell that is
79350 ** that is larger than (pKey,nKey).
79352 ** If seekResult==0, that means pCur is pointing at some unknown location.
79355 ** if pX->nMem is non-zero, then pX->aMem contains pointers to the unpacked
79362 int flags, /* True if this is likely an append */
79379 ** In some cases, the call to btreeMoveto() below is a no-op. For
79384 ** that the cursor is already where it needs to be and returns without
79385 ** doing any work. To avoid thwarting these optimizations, it is important
79392 /* This can only happen if the schema is corrupt such that there is more
79401 /* Ensure that the cursor is not in the CURSOR_FAULT state and that it
79426 /* If this is an insert into a table b-tree, invalidate any incrblob
79432 /* If BTREE_SAVEPOSITION is set, the cursor must already be pointing
79444 ** that the cursor is not pointing to a row to be overwritten.
79448 /* The cursor is pointing to the entry that is to be
79454 /* New entry is the same size as the old. Do an overwrite */
79459 /* The cursor is *not* pointing to the cell to be overwritten, nor
79460 ** to an adjacent cell. Move the cursor so that it is pointing either
79468 /* This is an index or a WITHOUT ROWID table */
79470 /* If BTREE_SAVEPOSITION is set, the cursor must already be pointing
79475 /* If the cursor is not already pointing either to the cell to be
79476 ** overwritten, or if a new cell is being inserted, if the cursor is
79496 /* If the cursor is currently pointing to an entry to be overwritten
79497 ** and the new content is the same as as the old, then use the
79576 ** We could also try to do this if the old cell is smaller, then add
79578 ** doing that is no faster then skipping this optimization and just
79582 ** new entry uses overflow pages, as the insertCell() call below is
79618 ** There is a subtle but important optimization here too. When inserting
79621 ** is advantageous to leave the cursor pointing to the last entry in
79622 ** the b-tree if possible. If the cursor is left pointing to the last
79624 ** larger than the largest existing key, it is possible to insert the
79632 /* Must make sure nOverflow is reset to zero even if the balance()
79660 ** This function is used as part of copying the current row from cursor
79662 ** parameter iKey is used as the rowid value when the record is copied
79663 ** into pDest. Otherwise, the record is copied verbatim.
79668 ** for the destination database. The size of the cell, in bytes, is left
79672 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
79772 ** Delete the entry that the cursor is pointing to.
79774 ** If the BTREE_SAVEPOSITION bit of the flags parameter is zero, then
79775 ** the cursor is left pointing at an arbitrary location after the delete.
79776 ** But if that bit is set, then the cursor is left in a state such that
79780 ** The BTREE_AUXDELETE bit of flags indicates that is one of several deletes
79782 ** deletes is considered the "primary" delete. The primary delete occurs
79783 ** on a cursor that is not a BTREE_FORDELETE cursor. All but one delete
79784 ** operation on non-FORDELETE cursors is tagged with the AUXDELETE flag.
79785 ** The BTREE_AUXDELETE bit is a hint that is not used by this implementation,
79831 /* If the BTREE_SAVEPOSITION bit is on, then the cursor position must
79833 ** will cause a b-tree rebalance, then this is done by saving the cursor
79841 ** The bPreserve value records which path is required:
79863 /* If the page containing the entry to delete is not a leaf page, move
79864 ** the cursor to the largest entry in the tree that is smaller than
79866 ** from the internal node. The 'previous' entry is used for this instead
79867 ** of the 'next' entry, as the previous entry is always a part of the
79883 /* If this is a delete operation to remove a row from a table b-tree,
79899 ** is currently pointing to the largest entry in the sub-tree headed
79934 ** call to balance() repairs the tree, and the if(...) condition is
79938 ** pCur is pointing to the leaf page from which a cell was removed to
79939 ** replace the cell deleted from the internal node. This is slightly
79950 /* Optimization: If the free space is less than 2/3rds of the page,
79994 ** The type of type is determined by the flags parameter. Only the
80030 ** root page of the new table should go. meta[3] is the largest root-page
80031 ** created so far, so the new root-page is (meta[3]+1).
80058 /* pgnoRoot is the page that will be used for the root-page of
80062 ** is already journaled.
80067 /* Save the positions of any open cursors. This is required in
80214 ** Delete all information from a single table in the database. iTable is
80216 ** the root page is empty, but still exists.
80222 ** If pnChange is not NULL, then the integer value pointed to by pnChange
80223 ** is incremented by the number of entries in the table.
80235 ** is the root of a table b-tree - if it is not, the following call is
80247 ** Delete all information from the single table that pCur is open on.
80258 ** page 1) is never added to the freelist.
80263 ** If AUTOVACUUM is enabled and the page at iTable is not the last
80265 ** in the database file is moved into the slot formerly occupied by
80267 ** is added to the freelist instead of iTable. In this say, all
80269 ** is necessary for AUTOVACUUM to work right. *piMoved is set to the
80271 ** the move. If no page gets moved, *piMoved is set to 0.
80272 ** The last root page is recorded in meta[3] and the value of
80273 ** meta[3] is updated by this procedure.
80306 /* If the table being dropped is the table with the largest root-page
80341 ** is the old value less one, less one more if that happens to
80342 ** be a root-page number, less one again if that is the
80374 ** is the number of free pages currently in the database. Meta[1]
80376 ** is read-only, the others are read/write.
80380 ** free pages is not visible. So Cookie[0] is the same as Meta[1].
80384 ** from the pager. The BTREE_DATA_VERSION value is not actually stored in the
80385 ** database file. It is a number computed by the pager. But its access
80386 ** pattern is the same as header meta values, and so it is convenient to
80404 /* If auto-vacuum is disabled in this build and this is an auto-vacuum
80416 ** Write meta-information back into the database. Meta[0] is
80444 ** The first argument, pCur, is a cursor opened on some b-tree. Count the
80447 ** SQLITE_OK is returned if the operation is successfully executed.
80448 ** Otherwise, if an error is encountered (i.e. an IO error or database
80449 ** corruption) an SQLite error code is returned.
80468 /* If this is a leaf page or the tree is not an int-key tree, then
80477 /* pPage is a leaf node. This loop navigates the cursor so that it
80480 ** pCur->aiIdx[pCur->iPage] value is set to the index of the parent cell
80482 ** to visit is the right-child of its parent.
80502 ** points at. This is the right-child if (iIdx==pPage->nCell).
80517 ** Return the pager associated with a BTree. This routine is used for
80593 ** corresponds to page iPg is already set.
80612 ** Add 1 to the reference count for page iPage. If this is the second
80615 ** if this is the first reference to the page.
80617 ** Also check that the page number is in bounds.
80665 ** Verify that the number of pages on the list is N.
80712 /* If this database supports auto-vacuum and iPage is not the last
80727 "%s is %u but should be %u",
80737 ** aHeap[0] is the number of elements on the heap. aHeap[1] is the
80741 ** The heap property is this: Every node is less than or equal to both
80742 ** of its daughter nodes. A consequence of the heap property is that the
80743 ** root node aHeap[1] is always the minimum value currently in the heap.
80751 ** This heap is used for cell overlap and coverage testing. Each u32
80800 ** 5. Verify that the depth of all children is the same.
80852 ** btreeInitPage() is executed. */
80992 ** is the offset of the first freeblock, or zero if there are no
81003 ** big-endian integer which is the offset in the b-tree page of the next
81004 ** freeblock in the chain, or zero if the freeblock is the last on the
81016 ** Each min-heap entry is of the form: (start_address<<16)|end_address.
81017 ** There is an implied first entry the covers the page header, the cell
81022 ** the start_address against the previous end_address. If there is an
81023 ** overlap, that means bytes are used multiple times. If there is a gap,
81024 ** that gap is added to the fragmentation count.
81040 ** is stored in the fifth field of the b-tree page header.
81063 ** This routine does a complete check of the given BTree file. aRoot[] is
81064 ** an array of pages numbers were each page number is the root page of
81065 ** a table. nRoot is the number of entries in aRoot.
81072 ** malloc is returned if *pnErr is non-zero. If *pnErr==0 then NULL is
81073 ** returned. If a memory allocation error occurs, NULL is returned.
81075 ** If the first entry in aRoot[] is 0, that indicates that the list of
81076 ** root pages is incomplete. This is a "partial integrity-check". This
81078 ** zero is skipped, of course. But in addition, the freelist checks
81079 ** and the checks to make sure every page is referenced are also skipped,
81080 ** since obviously it is not possible to know which pages are covered by
81081 ** the unverified btrees. Except, if aRoot[1] is 1, then the freelist
81085 sqlite3 *db, /* Database connection that is running the check */
81103 /* aRoot[0]==0 means this is a partial check */
81186 /* Make sure every page in the file is referenced
81231 ** an empty string if the database is in-memory or a TEMP database.
81233 ** The pager filename is invariant as long as the pager is
81234 ** open so it is safe to access without the BtShared mutex.
81243 ** value of this routine is the same regardless of whether the journal file
81246 ** The pager journal filename is invariant as long as the pager is
81247 ** open so it is safe to access without the BtShared mutex.
81268 ** transaction on the shared-cache the argument Btree is connected to.
81270 ** Parameter eMode is one of SQLITE_CHECKPOINT_PASSIVE, FULL or RESTART.
81289 ** Return true if there is currently a backup running on Btree p.
81299 ** a single shared-btree. The memory is used by client code for its own
81303 ** The first time this is called on a shared-btree, nBytes bytes of memory
81305 ** call the nBytes parameter is ignored and a pointer to the same blob
81308 ** If the nBytes parameter is 0 and the blob of memory has not yet been
81309 ** allocated, a null pointer is returned. If the blob has already been
81310 ** allocated, it is returned as normal.
81312 ** Just before the shared-btree is closed, the function passed as the
81313 ** xFree argument when the memory allocation was made is invoked on the
81346 ** Obtain a lock on the table whose root page is iTab. The
81347 ** lock is a write lock if isWritelock is true or a read lock
81348 ** if it is false.
81375 ** Only the data content may only be modified, it is not possible to
81376 ** change the length of the data stored. If this function is called with
81378 ** no modifications are made and SQLITE_CORRUPT is returned.
81395 /* Save the positions of all other cursors open on this table. This is
81407 ** (a) the cursor is open for writing,
81408 ** (b) there is a read/write transaction open,
81471 ** Return true if the cursor has a hint specified. This routine is
81479 ** Return true if the given Btree is read-only.
81491 ** If no transaction is active and the database is not a temp-db, clear
81503 ** Return true if the Btree passed as the only argument is sharable.
81512 ** this is always 1. For shared caches it may be 1 or greater.
81526 ** a legal notice, here is a blessing:
81546 int bDestLocked; /* True once a write-transaction is open on pDest */
81583 ** while some other thread is calling backup_step() or backup_finish(),
81584 ** the values returned may be invalid. There is no way for a call to
81599 ** If the "temp" database is requested, it may need to be opened by this
81640 ** Check that there is no open read-transaction on the b-tree passed as the
81641 ** second argument. If there is not, return SQLITE_OK. Otherwise, if there
81642 ** is an open read-transaction, return SQLITE_ERROR and leave an error
81647 sqlite3ErrorWithMsg(db, SQLITE_ERROR, "destination database is in use");
81658 ** If an error occurs, NULL is returned and an error code and error message
81677 ** handle is not locked in this routine, but it is locked in
81678 ** sqlite3_backup_step(). The user is required to ensure that no
81681 ** database connection while a backup is in progress may cause
81694 ** EVIDENCE-OF: R-64852-21591 The sqlite3_backup object is created by a
81695 ** call to sqlite3_backup_init() and is destroyed by a call to
81716 ** error was hit. Or there is a transaction open on the destination
81718 ** handle. All that is left to do here is free the sqlite3_backup
81734 ** Argument rc is an SQLite error code. Return true if this error is
81769 ** page. For each iteration, variable iOff is set to the byte offset
81787 ** cached parse of the page). MemPage.isInit is marked
81803 ** If pFile is currently larger than iSize bytes, then truncate it to
81804 ** exactly iSize bytes. If pFile is not larger than iSize bytes, then
81805 ** this function is a no-op.
81807 ** Return SQLITE_OK if everything is successful, or an SQLite error
81858 /* If the source pager is currently in a write-transaction, return
81867 /* If there is no open read-transaction on the source database, open
81868 ** one now. If a transaction is opened here, then it will be closed
81877 ** is the first call to backup_step() for the current backup operation),
81879 ** is especially important on ZipVFS systems, as in that case it is
81886 /* Lock the destination database, if it is not locked already. */
81894 /* Do not allow backup if the destination database is in WAL mode
81906 /* Now that there is a read-lock on the source database, query the
81934 ** is to make sure that the schema-version really does change in
81957 ** database. The complication here is that the destination page
81960 ** If the source page size is smaller than the destination page size,
81962 ** fix the size of the file. However it is important to call
81982 /* If the source page-size is smaller than the destination page-size,
82064 /* If bCloseTrans is true, then this function opened a read transaction
82065 ** on the source database. Close the read transaction here. There is
82120 /* If a transaction is still open on the Btree, roll it back. */
82133 /* EVIDENCE-OF: R-64852-21591 The sqlite3_backup object is created by a
82134 ** call to sqlite3_backup_init() and is destroyed by a call to
82171 ** This function is called after the contents of page iPage of the
82174 ** destination is now invalidated. The destination copy of iPage needs
82175 ** to be updated with the new data before the backup operation is
82178 ** It is assumed that the mutex associated with the BtShared object
82179 ** corresponding to the source database is held when this function is
82212 ** Restart the backup process. This is called when the pager layer
82214 ** connection. In this case there is no way of knowing which of the
82218 ** It is assumed that the mutex associated with the BtShared object
82219 ** corresponding to the source database is held when this function is
82236 ** goes wrong, the transaction on pTo is rolled back. If successful, the
82237 ** transaction is committed before returning.
82256 ** to 0. This is used by the implementations of sqlite3_backup_step()
82266 /* 0x7FFFFFFF is the hard limit for the number of pages in a database
82296 ** a legal notice, here is a blessing:
82305 ** stores a single value in the VDBE. Mem is an opaque structure visible
82312 /* True if X is a power of two. 0 is considered a power of two here.
82321 ** This routine is intended for use inside of assert() statements, like
82325 /* If MEM_Dyn is set then Mem.xDel!=0.
82326 ** Mem.xDel might not be initialized if MEM_Dyn is clear.
82331 ** ensure that if Mem.szMalloc>0 then it is safe to do
82343 /* If MEM_Null is set, then either the value is a pure NULL (the usual
82344 ** case) or it is a pointer set using sqlite3_bind_pointer() or
82349 /* This is a pointer type. There may be a flag to indicate what to
82363 /* The MEM_Cleared bit is only allowed on NULLs */
82394 ** Render a Mem object which is one of MEM_Int, MEM_Real, or MEM_IntReal
82427 ** (2) Check that the string is correctly zero terminated
82431 ** If a table contains a numeric value and an index is based on the
82432 ** corresponding string value, then it is important that the string be
82441 ** true if everything is ok and false if there is a problem.
82443 ** This routine is for use inside of assert() statements only.
82453 /* Insure that the string is properly zero-terminated. Pay particular
82454 ** attention to the case where p->n is odd */
82482 ** If pMem is an object with a valid string representation, this routine
82483 ** ensures the internal encoding for the string representation is
82486 ** If pMem is not a string object, or the encoding of the string
82487 ** representation is already stored using the requested encoding, then this
82488 ** routine is a no-op.
82490 ** SQLITE_OK is returned if the conversion is successful (or not required).
82514 /* MemTranslate() may return SQLITE_OK or SQLITE_NOMEM. If NOMEM is returned,
82528 ** If the bPreserve argument is true, then copy of the content of
82530 ** blob if bPreserve is true. If bPreserve is false, any prior content
82531 ** in pMem->z is discarded.
82538 /* If the bPreserve flag is set to true, then the memory cell must already
82586 ** routine is a no-op.
82589 ** The pMem->xDel destructor is called, if it exists. Though MEM_Str
82609 ** If pMem is already a string, detect if it is a zero-terminated
82612 ** This is an optimization. Correct operation continues even if
82613 ** this routine is a no-op.
82643 ** It is already known that pMem contains an unterminated string.
82646 ** Three bytes of zero are added. In this way, there is guaranteed
82649 ** is an odd number of bytes.
82663 ** Change pMem so that its MEM_Str or MEM_Blob value is stored in
82721 ** Make sure the given Mem is \u0000 terminated.
82737 ** routine is only called if pMem is a number of some kind, not a NULL
82741 ** if bForce is true but are retained if bForce is false.
82743 ** A MEM_Null value will never be passed to this function. This function is
82746 ** keys are strings. In the former case a NULL pointer is returned the
82747 ** user and the latter is an internal programming error.
82779 ** result of the aggregate is stored back into pMem.
82813 ** SQLITE_ERROR is returned if xValue() reports an error. SQLITE_OK
82840 ** This is a helper routine for sqlite3VdbeMemSetNull() and
82863 ** This is a helper routine invoked by sqlite3VdbeMemRelease() in
82864 ** the unusual case where there really is memory in p that needs
82879 ** Release any memory resources held by the Mem. Both the memory that is
82896 ** know in advance that the Mem is not MEM_Dyn or MEM_Agg.
82904 ** Return some kind of integer value which is the best we can do
82906 ** If pMem is an integer, then the value is exact. If pMem is
82907 ** a floating-point then the value returned is the integer part.
82908 ** If pMem is a string or blob, then we make an attempt to convert
82939 ** double. If pMem is already a double or an integer, return its
82940 ** value. If it is a string or blob, try to convert it to a double.
82941 ** If it is a NULL, return 0.0.
82968 ** Return the value ifNull if pMem is NULL.
82978 ** The MEM structure is already a MEM_Real or MEM_IntReal. Try to
82995 ** (1) the round-trip conversion real->int->real is a no-op, and
82996 ** (2) The integer is neither the largest nor the smallest
83025 ** Convert pMem so that it is of type MEM_Real.
83068 ** Every effort is made to force the conversion, even if the input
83069 ** is a string that does not look completely like a number. Convert
83100 ** "aff". Casting is different from applying affinity in that a cast
83101 ** is forced. In other words, the value is converted into the desired
83102 ** affinity even if that results in loss of data. This routine is
83150 ** The minimum amount of initialization feasible is performed.
83214 ** The pMem is known to contain content that needs to be destroyed prior
83275 ** Return true if the Mem holds a RowSet object. This routine is intended
83306 ** Return true if the Mem object contains a TEXT or BLOB that is
83327 ** This is used for testing and debugging only - to help ensure that shallow
83340 /* If pX is marked as a shallow copy of pMem, then try to verify that
83344 ** dual type, are allowed, as long as the underlying value is the
83349 /* pMem is the register that is changing. But also mark pX as
83361 ** pTo are freed. The pFrom->z field is not duplicated. If
83362 ** pFrom->z is used, then pTo->z points to the same thing as pFrom->z
83384 ** freed before the copy is made.
83404 ** Transfer the contents of pFrom to pTo. Any existing value in pTo is
83405 ** freed. If pFrom contains ephemeral data, a copy is made.
83424 ** parameter. If the value passed is SQLITE_TRANSIENT, then the
83425 ** string is copied into a (possibly existing) buffer managed by the
83426 ** Mem structure. Otherwise, any existing buffer is freed and the
83429 ** If the string is too large (if it exceeds the SQLITE_LIMIT_LENGTH
83431 ** stored without allocating memory, then it is. If a memory allocation
83432 ** is required to store the string, then value of pMem is unchanged. In
83433 ** either case, SQLITE_TOOBIG is returned.
83435 ** The "enc" parameter is the text encoding for the string, or zero
83438 ** If n is negative, then the string consists of all bytes up to but
83458 /* If z is a NULL pointer, set pMem to contain an SQL NULL. */
83539 ** The data is payload from the entry that pCur is currently pointing
83541 ** The result is written into the pMem element.
83546 ** is responsible for making sure that the pMem object is eventually
83550 ** to read from the disk) then the pMem is left in an inconsistent state.
83603 ** The pVal argument is known to be a value other than NULL.
83640 /* This function is only available internally, it is not part of the
83642 ** except the data returned is in the encoding specified by the second
83647 ** If that is the case, then the result must be aligned on an even byte
83665 /* Return true if sqlit3_value object pVal is a string or blob value
83708 ** the second argument to this function is NULL, the object is allocated
83711 ** Otherwise, if the second argument is non-zero, then this function is
83760 ** The expression object indicated by the second argument is guaranteed
83764 ** * one of the SQLITE_FUNC_CONSTANT or _SLOCHNG function flags is set, and
83765 ** * the SQLITE_FUNC_NEEDCOLL function flag is not set,
83768 ** error occurs, output parameter (*ppVal) is set to point to a value
83771 ** Affinity aff is applied to the result of the function before returning.
83772 ** If the result is a text value, the sqlite3_value object uses encoding
83776 ** and sets (*ppVal) to NULL. Or, if an error occurs, (*ppVal) is set to
83874 ** If pCtx is NULL and an error occurs after the sqlite3_value object
83875 ** has been allocated, it is freed before returning. Or, if pCtx is not
83876 ** NULL, it is assumed that the caller will free any allocated object
83900 ** check ensures that an EP_TokenOnly expression is never passed down
83924 /* Handle negative integers in a single step. This is needed in the
83925 ** case when the value is -9223372036854775808.
84037 ** be converted directly into a value, then the value is allocated and
84038 ** a pointer written to *ppVal. The caller is responsible for deallocating
84040 ** cannot be converted to a value, then *ppVal is set to NULL.
84056 ** If pAlloc is not NULL, then an UnpackedRecord object is created for
84057 ** pAlloc if one does not exist and the new value is added to the
84060 ** A value is extracted in the following cases:
84062 ** * (pExpr==0). In this case the value is assumed to be an SQL NULL,
84064 ** * The expression is a bound variable, and this is a reprepare, or
84066 ** * The expression is a literal value.
84068 ** On success, *ppVal is made to point to the extracted value. The caller
84069 ** is responsible for ensuring that the value is eventually freed.
84113 ** This function is used to allocate and populate UnpackedRecord
84119 ** right starting with 0). A single field is populated if:
84121 ** * (pExpr==0). In this case the value is assumed to be an SQL NULL,
84123 ** * The expression is a bound variable, and this is a reprepare, or
84125 ** * The sqlite3ValueFromExpr() function is able to extract a value
84126 ** from the expression (i.e. the expression is a literal value).
84128 ** Or, if pExpr is a TK_VECTOR, one field is populated for each of the
84132 ** Before any value is appended to the record, the affinity of the
84133 ** corresponding column within index pIdx is applied to it. Before
84134 ** this function returns, output parameter *pnExtract is set to the
84137 ** When this function is called, *ppRec must either point to an object
84139 ** is NULL and a value can be successfully extracted, a new UnpackedRecord
84140 ** is allocated (and *ppRec set to point to it) before returning.
84142 ** Unless an error is encountered, SQLITE_OK is returned. It is not an
84144 ** occur, an SQLite error code is returned.
84189 ** is undefined in this case.
84202 ** the column value into *ppVal. If *ppVal is initially NULL then a new
84203 ** sqlite3_value object is allocated.
84205 ** If *ppVal is initially NULL then the caller is responsible for
84206 ** ensuring that the value written into *ppVal is eventually freed.
84249 ** Unless it is NULL, the argument must be an UnpackedRecord object returned
84293 ** The valueBytes() routine is a helper function.
84324 ** a legal notice, here is a blessing:
84332 ** a VDBE (or an "sqlite3_stmt" as it is known to the outside world.)
84419 ** zId of length nId is a double-quoted identifier. Check to see if
84420 ** that identifier is really used as a string literal.
84442 ** so that pB can be run again. The old pB byte code is
84443 ** moved back to pA so that it will be cleaned up when pA is
84474 ** Resize the Vdbe.aOp array so that it is at least nOp elements larger
84475 ** than its current size. nOp is guaranteed to be less than or equal
84480 ** unchanged (this is so that any opcodes already allocated can be
84487 /* The SQLITE_TEST_REALLOC_STRESS compile-time option is designed to force
84489 ** simulated OOM faults. SQLITE_TEST_REALLOC_STRESS is generally used
84492 ** operation (without SQLITE_TEST_REALLOC_STRESS) is to double the current
84493 ** size of the op array or add 1KB of space, whichever is smaller. */
84521 /* This routine is just a convenient place to set a breakpoint that will
84522 ** fire after each opcode is inserted and displayed using
84537 if( n==LARGEST_UINT64 ) abort(); /* so that n is used, preventing a warning */
84702 ** One register is initialized for each characgter in zTypes[]. For each
84703 ** "s" character in zTypes[], the register is a string if the argument is
84704 ** not NULL, or OP_Null if the value is a null pointer. For each "i" character
84705 ** in zTypes[], the register is initialized to an integer.
84708 ** is generated for the values inserted.
84750 ** The eCallCtx argument is information (typically taken from Expr.op2)
84755 ** while computing a generated column value. 0 is the usual case.
84835 ** If the bPush flag is true, then make this opcode the parent for
84836 ** subsequent Explains until sqlite3VdbeExplainPop() is called.
84841 /* Always include the OP_Explain opcodes if SQLITE_DEBUG is defined.
84876 ** Add an OP_ParseSchema opcode. This routine is broken out from
84908 ** coded. The symbolic label is really just a negative number. The
84910 ** the label is resolved to a specific address, the VDBE will scan
84914 ** The VDBE knows that a P2 value is a label because labels are
84916 ** Hence, a negative P2 value is a label that has yet to be resolved.
84917 ** (Later:) This is only true for opcodes that have the OPFLG_JUMP
84924 ** labels stores -1, but that is not required.
84927 ** been issued. The negative is stored because
85008 ** sIter.v = v; // v is of type Vdbe*
85070 ** to be rolled back). This condition is true if the main program or any
85083 ** Then check that the value of Parse.mayAbort is true if an
85085 ** match, or false otherwise. This function is intended to be used as
85121 ** require one. This is not so bad - it is an inefficiency, not a bug. */
85147 ** Increment the nWrite counter in the VDBE if the cursor is not an
85148 ** ephemeral cursor, or if the cursor argument is NULL.
85172 ** This routine is called after all opcodes have been inserted. It loops
85208 ** it is larger than SQLITE_MX_JUMP_OPCODE, as a performance optimization.
85285 ** the subroutine. If a jump outside the subroutine is detected, add code
85289 ** locations within the subroutine are acceptable. iRetReg is a register
85291 ** through iLast are also acceptable as long as the jump destination is
85295 ** beyond the current address. That is normally a jump to an early
85296 ** termination and is consider acceptable.
85298 ** This routine only runs during debug builds. The purpose is (of course)
85300 ** is generated rather than an assert() or other error, so that ".eqp full"
85326 /* This is a deliberately taken illegal branch. tag-20230325-2 */
85353 "Opcode at %d jumps to %d which is outside the "
85381 ** SQLITE_TEST_REALLOC_STRESS). This interface is used during testing
85394 ** an OP_ResultRow opcode. Fail an assert() if it does. This is used
85421 ** the Vdbe passed as the first argument. It is the callers responsibility
85425 ** Before returning, *pnOp is set to the number of entries in the returned
85426 ** array. Also, *pnMaxArg is set to the larger of its current value and
85448 ** so that the jump target is relative to the first operation inserted.
85611 ** If the previous opcode is an OP_Column that delivers results
85633 ** the previous opcode (and is thus a no-op) then simply back up
85634 ** the next instruction counter by one slot so that the jump is
85637 ** This routine is an optimization of sqlite3VdbeJumpHere() that
85660 ** If the input FuncDef structure is ephemeral, then free it. If
85661 ** the FuncDef is not ephemeral, then do nothing.
85731 ** opcodes contained within. If aOp is not NULL it is assumed to contain
85753 ** list at Vdbe.pSubProgram. This list is used to delete all sub-program
85754 ** objects when the VM is no longer required.
85784 ** If the last opcode is "op" and it is not a jump destination,
85831 ** This routine is useful when a large program is loaded from a
85835 ** If n>=0 then the P4 operand is dynamic, meaning that a copy of
85836 ** the string is made into memory obtained from sqlite3_malloc().
85841 ** to a string or structure that is guaranteed to exist for the lifetime of
85887 /* Note: this cast is safe, because the origin data point was an int
85901 ** to the value defined by the arguments. This is a high-speed
85987 ** is readable but not writable, though it is cast to a writable value.
85990 ** this routine is a valid pointer. But because the dummy.opcode is 0,
85991 ** dummy will never be written to. This is verified by code inspection and
85996 ** zeros, which is correct. MSVC generates a warning, nevertheless. */
86030 ** to an extra string that is appended to the sqlite3OpcodeName(). In the
86035 ** "PX@PY" -> "r[X..X+Y-1]" or "r[x]" if y is 0 or 1
86036 ** "PX@PY+1" -> "r[X..X+Y]" or "r[x]" if y is 0
86289 u32 n = ai[0]; /* The first element of an INTARRAY is always the
86318 ** Declare to the Vdbe that the BTree object at db->aDb[i] is used.
86322 ** is maintained in p->btreeMask. The p->lockMask value is the subset of
86336 ** If SQLite is compiled to support shared-cache mode and to be threadsafe,
86340 ** that the correct busy-handler callback is invoked if required.
86342 ** If SQLite is not threadsafe but does support shared-cache mode, then
86343 ** sqlite3BtreeEnter() is invoked to set the BtShared.db variables
86347 ** If SQLite is not threadsafe and does not support shared-cache mode, this
86348 ** function is a no-op.
86350 ** The p->btreeMask field is a bitmask of all btrees that the prepared
86353 ** this routine is N*N. But as N is rarely more than 1, this should not
86399 ** Print a single opcode. This routine is used for debugging only.
86415 /* NB: The sqlite3OpcodeName() function is implemented by code created
86433 ** This is a high-runner, so only those fields that really do need to
86434 ** be initialized are set. The Mem structure is organized so that
86481 /* This block is really an inlined version of sqlite3VdbeMemRelease()
86482 ** that takes advantage of the fact that the memory cell value is
86485 ** The justification for duplicating code is that according to
86489 ** to 6.6 percent. The test case is inserting 1000 rows into a table
86515 ** Verify that pFrame is a valid VdbeFrame pointer. Return true if it is
86516 ** and false if something is wrong.
86518 ** This routine is intended for use inside of assert() statements only.
86528 ** This is a destructor on a Mem object (which is really an sqlite3_value)
86529 ** that deletes the Frame object that is attached to it as a blob.
86567 ** nRow is the sum of the number of rows in the main program, plus
86575 /* pSub is initiallly NULL. It is initialized to a BLOB by
86593 /* The rowid is small enough that we are still in the
86610 /* When an OP_Program opcode is encounter (the only opcode that has
86678 ** The interface is the same as sqlite3VdbeExec(). But instead of
86680 ** This feature is used to implement "EXPLAIN".
86682 ** When p->explain==1, each instruction is listed. When
86684 ** are shown in a different format. p->explain==2 is used to implement
86690 ** When p->explain==1, first the main program is listed, then each of
86725 ** to trigger subprograms. The VDBE is guaranteed to have at least 9
86733 /* Figure out which opcode is next to display */
86757 /* pMem+5 for p4 is done last */
86834 ** by subcomponents of a prepared statement. Space is allocated out
86845 ** memory on success. If insufficient memory is available in the
86849 ** If pBuf is not initially NULL, that means that the memory has already
86853 ** This allocator is employed to repurpose unused slots at the end of the
86924 ** After this routine is called the VM has been "packaged" and is ready
86925 ** to run. After this routine is called, further calls to
86961 ** use aMem[0] which is not otherwise used by the VDBE program. Allocate
86968 /* Figure out how much reusable memory is available at the end of the
86988 /* Memory for registers, parameters, cursor, etc, is allocated in one or two
87092 ** is used, for example, when a trigger sub-program is halted to restore
87117 ** cell array. This is necessary as the memory cell array may contain
87145 ** statement. This is now set at compile time, rather than during
87171 ** or SQLITE_TRANSIENT. If it is SQLITE_DYNAMIC, then the buffer pointed
87172 ** to by zName will be freed by sqlite3DbFree() when the vdbe is destroyed.
87198 ** db. If a transaction is active, commit it. If there is a
87211 /* With this option, sqlite3VtabSync() is defined to be simply
87212 ** SQLITE_OK so p is not used.
87219 ** be done before determining whether a super-journal file is
87227 ** including the temp database. (b) is important because if more than
87229 ** file is required for an atomic commit.
87273 ** TEMP database) has a transaction active. There is no need for the
87276 ** If the return value of sqlite3BtreeGetFilename() is a zero length
87277 ** string, it means the main database is :memory: or a temp file. In
87293 ** IO error while deleting or truncating a journal file. It is unlikely,
87307 /* The complex case - There is a multi-file write-transaction active.
87308 ** This requires a super-journal file to ensure the transaction is
87386 ** flag is set this is not required.
87402 ** sqlite3BtreeCommitPhaseOne(), then there is a chance that the
87421 ** doing this the directory is synced again before any individual
87434 ** this is happening we don't really care. The integrity of the
87435 ** transaction is already guaranteed, but some stray 'cold' journals
87460 ** This is an internal self-check only - it is not an essential processing
87463 ** This is a no-op if NDEBUG is defined.
87491 ** SAVEPOINT_RELEASE. If it is SAVEPOINT_ROLLBACK, then the statement
87492 ** transaction is rolled back. If eOp is SAVEPOINT_RELEASE, then the
87493 ** statement transaction is committed.
87495 ** If an IO error occurs, an SQLITE_IOERR_XXX error code is returned.
87535 /* If the statement transaction is being rolled back, also restore the
87553 ** This function is called when a transaction opened by the database
87554 ** handle associated with the VM passed as an argument is about to be
87579 ** This routine is called the when a VDBE tries to halt. If the VDBE
87580 ** has made changes and is in autocommit mode, then commit those
87581 ** changes. If a rollback is needed, then do the rollback.
87583 ** This routine is the only way to move the sqlite3eOpenState of a VM from
87584 ** SQLITE_STATE_RUN to SQLITE_STATE_HALT. It is harmless to
87585 ** call this on a VM that is in the SQLITE_STATE_HALT state.
87588 ** lock contention, return SQLITE_BUSY. If SQLITE_BUSY is returned, it
87607 ** state. We need to rollback the statement transaction, if there is
87608 ** one, or the complete transaction if there is no statement transaction.
87639 /* If the query was read-only and the error code is SQLITE_INTERRUPT,
87640 ** no rollback is necessary. Otherwise, at least a savepoint
87644 ** Even if the statement is read-only, it is important to perform
87648 ** pagerStress() in pager.c), the rollback is required to restore
87671 /* If the auto-commit flag is set and this is the only active writer
87693 /* The auto-commit flag is true, the vdbe program was successful
87696 ** is required. */
87733 /* If eStatementOp is non-zero, then a statement transaction needs to
87736 ** error code is SQLITE_OK or SQLITE_CONSTRAINT, then promote the
87783 /* If the auto-commit flag is set to true, then any locks that were held
87832 ** If an SQLITE_CONFIG_SQLLOG hook is registered and the VM has been run,
87855 ** After this routine is run, the VDBE should be ready to be executed
87950 ** Clean up and delete a VDBE after execution. Return an integer which is
87967 ** If parameter iOp is less than zero, then invoke the destructor for
87971 ** Or, if iOp is greater than or equal to zero, then the destructor is
87976 ** * the associated function parameter is the 32nd or later (counting
87979 ** * the corresponding bit in argument mask is clear (where the first
88004 ** except for object itself, which is preserved.
88006 ** The difference between this function and sqlite3VdbeDelete() is that
88100 ** is supposed to be pointing. If the row was deleted out from under the
88115 ** Check to ensure that the cursor is valid. Restore the cursor
88137 ** 'serial-type' and a blob of data. The serial type is an 8-byte unsigned
88140 ** In an SQLite index record, the serial type is stored directly before
88177 ** this routine is now only used by the STAT3 logic and STAT3 support has
88178 ** ended. The code is kept here for historical reference only.
88216 /* If the value is IntReal and is going to take up 8 bytes to store
88283 ** For most architectures, this is a no-op.
88285 ** (later): It is reported to me that the mixed-endian problem
88286 ** on ARM7 is an issue with GCC, not with the ARM7 chip. It seems
88289 ** ever since. The blame is not necessarily with GCC, though.
88297 ** floating point values is correct.
88303 ** 48-bits as required by the IEEE standard. (This is the
88306 ** the necessary byte swapping is carried out using a 64-bit integer
88309 ** verify this, but Frank seems to know what he is talking about
88329 /* Input "x" is a sequence of unsigned characters that represent a
88342 ** This function is implemented as two separate routines for performance.
88345 ** is avoided.
88356 /* EVIDENCE-OF: R-29851-52272 Value is a big-endian 64-bit
88362 /* EVIDENCE-OF: R-57343-49114 Value is a big-endian IEEE 754-2008 64-bit
88366 ** byte order. Or, that if SQLITE_MIXED_ENDIAN_64BIT_FLOAT is
88397 /* EVIDENCE-OF: R-24078-09375 Value is a NULL. */
88402 /* EVIDENCE-OF: R-44885-25196 Value is an 8-bit twos-complement
88410 /* EVIDENCE-OF: R-49794-35026 Value is a big-endian 16-bit
88418 /* EVIDENCE-OF: R-37839-54301 Value is a big-endian 24-bit
88426 /* EVIDENCE-OF: R-01849-26079 Value is a big-endian 32-bit
88438 /* EVIDENCE-OF: R-50385-09674 Value is a big-endian 48-bit
88454 /* EVIDENCE-OF: R-12976-22893 Value is the integer 0. */
88455 /* EVIDENCE-OF: R-18143-12121 Value is the integer 1. */
88461 /* EVIDENCE-OF: R-14606-31564 Value is a BLOB that is (N-12)/2 bytes in
88463 ** EVIDENCE-OF: R-28401-00140 Value is a string in the text encoding and
88475 ** This routine is used to allocate sufficient space for an UnpackedRecord
88477 ** the first argument is a pointer to KeyInfo structure pKeyInfo.
88479 ** The space is either allocated using sqlite3DbMallocRaw() or from within
88481 ** stack space). If the former, then *ppFree is set to a pointer that should
88483 ** allocation comes from the pSpace/szSpace buffer, *ppFree is set to NULL
88486 ** If an OOM error occurs, NULL is returned.
88556 ** sqlite3VdbeSerialGet() and sqlite3MemCompare() functions. It is used
88560 ** Return true if the result of comparison is equivalent to desiredResult.
88561 ** Return false if there is a disagreement.
88584 /* Compilers may complain that mem1.u.i is potentially uninitialized.
88588 ** impact, since this routine is a very high runner. And so, we choose
88606 /* Verify that there is enough key space remaining to avoid
88651 /* No memory allocation is ever used on mem1. Prove this using
88675 ** pKey,nKey. The verify that this count is less than or equal to the
88678 ** If this constraint is not satisfied, it means that the high-speed
88711 ** or positive value if *pMem1 is less than, equal to or greater than
88748 ** The input pBlob is guaranteed to be a Blob that is not marked
88761 ** is less than, equal to, or greater than the second, respectively.
88762 ** If one blob is a prefix of the other, then the shorter is the lessor.
88769 /* It is possible to have a Blob value that has some non-zero content
88804 ** number. Return negative, zero, or positive if the first (i64) is less than,
88837 ** negative, zero or positive if pMem1 is less than, equal to, or greater
88838 ** than pMem2. Sorting order is NULL's first, followed by numbers (integers
88853 /* If one value is NULL, it is less than the other. If both values
88860 /* At least one of the two values is a number
88903 /* If one value is a string and the other is a blob, the string is less.
88919 ** the user deletes the collation sequence after the vdbe program is
88937 ** The first argument passed to this function is a serial-type that
88980 ** or positive integer if key1 is less than, equal to or
88986 ** If argument bSkip is non-zero, it is assumed that the caller has already
88990 ** fields that appear in both keys are equal, then pPKey2->default_rc is
88993 ** If database corruption is discovered, set pPKey2->errCode to
88994 ** SQLITE_CORRUPT and return 0. If an OOM error is encountered,
88995 ** pPKey2->errCode is set to SQLITE_NOMEM and, if it is not NULL, the
89013 /* If bSkip is true, then the caller has already determined that the first
89050 /* RHS is an integer */
89074 /* RHS is real */
89099 /* RHS is a string */
89132 /* RHS is a blob */
89160 /* RHS is null */
89193 /* No memory allocation is ever used on mem1. Prove this using
89217 ** This function is an optimized version of sqlite3VdbeRecordCompare()
89218 ** that (a) the first field of pPKey2 is an integer, and (b) the
89220 ** byte (i.e. is less than 128).
89222 ** To avoid concerns about buffer overreads, this routine is only used
89223 ** on schemas where the maximum valid header size is 63 bytes or less.
89283 ** is contiguous) but does not cause any duplicate code to be generated
89284 ** (as gcc is clever enough to combine the two like cases). Other
89315 ** This function is an optimized version of sqlite3VdbeRecordCompare()
89316 ** that (a) the first field of pPKey2 is a string, that (b) the first field
89341 res = pPKey2->r1; /* (pKey1/nKey1) is a number or a null */
89343 res = pPKey2->r2; /* (pKey1/nKey1) is a blob */
89393 ** fits in a single byte (i.e. is 127 or less). varintRecordCompareInt()
89394 ** also assumes that it is safe to overread a buffer by at least the
89395 ** maximum possible legal header size plus 8 bytes. Because there is
89399 ** is an integer.
89401 ** The easiest way to enforce this limit is to consider only records with
89402 ** 13 fields or less. If the first field is an integer, the maximum legal
89403 ** header size is (12*5 + 1 + 1) bytes. */
89454 ** Any corruption is detected in sqlite3BtreeParseCellPtr(), though, so
89455 ** this code can safely assume that nCellKey is 32-bits
89479 ** Verify that the last entry really is an integer. */
89504 /* Jump here if database corruption is detected after m has been
89513 ** Compare the key of the index entry that cursor pC is pointing to against
89515 ** that is negative, zero, or positive if pC is less than, equal to,
89518 ** pUnpacked is either created without a rowid or is truncated so that it
89520 ** is ignored as well. Hence, this routine only compares the prefixes
89565 ** Set a flag in the vdbe to update the change counter when it is finalised
89576 ** An expired statement means that recompilation of the statement is
89582 ** If iCode is 1, then expiration is advisory. The statement should
89583 ** be reprepared before being restarted, but if it is already running
89584 ** it is allowed to run to completion.
89587 ** prepared statements. The flag is set to 1 for an immediate expiration
89613 ** parameter iVar of VM v. Except, if the value is an SQL NULL, return
89614 ** 0 instead. Unless it is NULL, apply affinity aff (one of the SQLITE_AFF_*
89656 ** throw an error if it is given inputs that would make it non-deterministic.
89657 ** This routine is invoked by date/time functions that use non-deterministic
89687 ** This Walker callback is used to help verify that calls to
89719 ** If the second argument is not NULL, release any allocations associated
89723 ** This function is used to free UnpackedRecord structures allocated by
89741 ** Invoke the pre-update hook. If this is an UPDATE or DELETE pre-update call,
89747 Vdbe *v, /* Vdbe pre-update hook is invoked by */
89826 ** a legal notice, here is a blessing:
89847 ** collating sequences are registered or if an authorizer function is
89858 ** an error and return true if it has been finalized (or is otherwise
89859 ** invalid). Return false if it is ok.
89880 ** Invoke the profile callback. This routine is only called if we already
89881 ** know that the profile callback is defined and needs to be invoked.
89904 ** is needed, and it invokes the callback if it is needed.
89913 ** The following routine destroys a virtual machine that is created by
89914 ** the sqlite3_compile() routine. The integer returned is an SQLITE_
89925 ** pointer is a harmless no-op. */
89945 ** the prior execution is returned.
90204 ** is too big or if an OOM occurs.
90207 ** on value P if P is not going to be used and need to be destroyed.
90542 ** This function is called after a transaction has been committed. It
90567 ** Execute the statement pStmt, either until a row of data is ready, the
90568 ** statement is completely executed or an error occurs.
90571 ** API. The only thing omitted is the automatic recompile if a
90572 ** schema change has occurred. That detail is handled by the
90631 ** This "automatic-reset" change is not technically an incompatibility,
90632 ** since any application that receives an SQLITE_MISUSE is broken by
90713 ** This is the top-level implementation of sqlite3_step(). Call
90737 ** program counter to 0 to ensure that when the statement is
90738 ** finalized or reset the parser error message is available via
90754 /* Setting minWriteFileFormat to 254 is a signal to the OP_Init and
90799 ** If this routine is invoked from within an xColumn method of a virtual
90800 ** table, then it returns true if and only if the the call is during an
90804 ** If this routine is called from any context other than within the
90805 ** xColumn method of a virtual table, then the return value is meaningless
90810 ** value, as a signal to the xUpdate routine that the column is unchanged.
90905 ** is requested more than once within the same run of a single prepared
90906 ** statement, the exact same time is returned for each invocation regardless
90908 ** the time returned is always the time of the first call.
90949 ** context is allocated on the first call. Subsequent calls return the
90967 ** The left-most argument is 0.
90969 ** Undocumented behavior: If iArg is negative then access a cache of
90970 ** auxiliary data pointers that is available to all functions within a
90995 ** argument to the user-function defined by pCtx. Any previous value is
90998 ** The left-most argument is 0.
91000 ** Undocumented behavior: If iArg is negative then make the data available
91056 ** This function is deprecated. Do not use it for new code. It is
91095 ** that a Mem structure is located on an 8-byte boundary. To prevent
91124 ** Check to see if column iCol of the given statement is valid. If
91125 ** it is, return a pointer to the Mem for the value of that column.
91126 ** If iCol is not valid, return a pointer to a Mem which has a value
91147 ** This function is called after invoking an sqlite3_value_XXX function on a
91150 ** malloc() has failed, the threads mallocFailed flag is cleared and the result
91153 ** Specifically, this is called from within:
91187 /* Even though there is no encoding conversion, value_blob() might
91274 ** xFunc() then return that string. If N is out of range, return 0.
91277 ** name is returned. Here are the names:
91285 ** If the result is not a simple column reference (if it is an expression
91336 ** is the case, clear the mallocFailed flag and return NULL.
91389 ** NULL is returned if the result column is an expression or constant or
91390 ** anything else which is not an unambiguous reference to a database column.
91403 ** NULL is returned if the result column is an expression or constant or
91404 ** anything else which is not an unambiguous reference to a database column.
91417 ** NULL is returned if the result column is an expression or constant or
91418 ** anything else which is not an unambiguous reference to a database column.
91436 ** Unbind the value bound to variable i in virtual machine p. This is the
91437 ** the same as binding a NULL value to the column. If the "i" parameter is
91438 ** out of range, then SQLITE_RANGE is returned. Otherwise SQLITE_OK.
91441 ** the mutex is released if any kind of error occurs.
91443 ** The error code stored in database p->db is overwritten with the return
91469 /* If the bit corresponding to this variable in Vdbe.expmask is set, then
91699 ** This routine is added to support DBD::SQLite.
91708 ** is out of range or if the wildcard is unnamed.
91710 ** The result is always UTF-8.
91720 ** with that name. If there is no variable with the given name,
91753 ** It is misuse to call this routine with statements from different
91754 ** database connections. But as this is a deprecated interface, we
91758 ** an SQLITE_ERROR is returned. Nothing else can go wrong, so otherwise
91759 ** SQLITE_OK is returned.
91781 ** in the argument belongs. This is the same database handle that was
91790 ** Return true if the prepared statement is guaranteed to not modify the
91798 ** Return 1 if the statement is an EXPLAIN and return 2 if the
91799 ** statement is an EXPLAIN QUERY PLAN
91842 ** Return true if the prepared statement is in need of being reset.
91851 ** with database connection pDb. If pStmt is NULL, return the first
91915 ** bound parameters expanded. Space to hold the returned string is
91916 ** obtained from sqlite3_malloc(). The caller is responsible for
91958 ** if successful, or a NULL pointer if an OOM error is encountered.
91976 ** This function is called from within a pre-update callback to retrieve
91990 /* Test that this call is being made from within an SQLITE_DELETE or
91991 ** SQLITE_UPDATE pre-update callback, and that iIdx is within range. */
92046 ** This function is called from within a pre-update callback to retrieve
92062 ** This function is designed to be called from within a pre-update callback
92070 ** or SET DEFAULT action is considered a trigger.
92085 ** This function is designed to be called from within a pre-update callback
92101 ** This function is called from within a pre-update callback to retrieve
92129 ** that is being inserted. Deserialize it. */
92151 ** It is not safe to return a pointer to the memory cell itself as the
92230 /* If the COMPLEX flag is clear, then this function must ignore any
92367 ** a legal notice, here is a blessing:
92378 ** The Vdbe parse-tree explainer is also found here.
92386 ** zSql is a zero-terminated string of UTF-8 SQL text. Return the number of
92412 ** obtained from sqlite3DbMalloc(). If sqlite3.nVdbeExec is 1, then the
92414 ** their current bindings. Or, if sqlite3.nVdbeExec is greater than 1,
92418 ** If the SQLITE_TRACE_SIZE_LIMIT macro is defined to an integer, then
92423 ** The calling function is responsible for making sure the memory returned
92424 ** is eventually freed.
92429 ** the host parameter index is found by scanning the prepared
92431 ** parameter index is known, locate the value in p->aVar[]. Then render
92562 ** a legal notice, here is a blessing:
92574 ** of the code in this file is, therefore, important. See other comments
92586 ** is changed while the copy is still in use, the string or blob might
92597 ** The following global variable is incremented every time a cursor
92608 ** When this global variable is positive, it gets decremented once before
92610 ** field of the sqlite3 structure is set in order to simulate an interrupt.
92612 ** This facility is used for testing purposes only. It does not function
92620 ** The next global variable is incremented each type the OP_Sort opcode
92621 ** is executed. The test procedures use this information to make sure that
92622 ** sorting is occurring or not occurring at appropriate times. This variable
92634 ** is working correctly. This variable has no function other than to
92657 ** The next global variable is incremented each time the OP_Found opcode
92658 ** is executed. This is used to test whether or not the foreign key
92659 ** operation implemented using OP_FkIsZero is working. This variable
92680 ** each opcode is printed. Variables "pc" (program counter) and pOp are
92697 if( n==LARGEST_UINT64 ) abort(); /* So that n is used, preventing a warning */
92702 ** Invoke the VDBE coverage callback, if that callback is defined. This
92703 ** feature is used for test suite validation only and does not appear an
92706 ** M is the type of branch. I is the direction taken for this instance of
92713 ** In other words, if M is 2, then I is either 0 (for fall-through) or
92714 ** 1 (for when the branch is taken). If M is 3, the I is 0 for an
92715 ** ordinary fall-through, I is 1 if the branch was taken, and I is 2
92716 ** if the result of comparison is NULL. For M=3, I=2 the jump may or
92718 ** When M is 4, that means that an OP_Jump is being run. I is 0, 1, or 2
92721 ** iSrcLine is the source code line (from the __LINE__ macro) that
92723 ** code line number is in the lower 24 bits of iSrcLine and the upper
92725 ** values for I that should never occur. For example, if the branch is
92727 ** alternate branch are never taken. If a branch is never taken then
92728 ** flags should be 0x06 since only the fall-through approach is allowed.
92730 ** Bit 0x08 of the flags indicates an OP_Jump opcode that is only
92734 ** Since only a line number is retained, not the filename, this macro
92735 ** only works for amalgamation builds. But that is ok, since these macros
92746 assert( I<M ); /* I can only be 2 if M is 3 or 4 */
92762 ** impossible cases (ex: if the comparison is never NULL)
92782 ** is responsible for deallocating that string. Because the register
92808 ** required for this VdbeCursor structure. It is convenient to use a
92821 ** The memory cell for cursor 0 is aMem[0]. The rest are allocated from
92822 ** the top of the register space. Cursor 1 is at Mem[p->nMem-1].
92823 ** Cursor 2 is at Mem[p->nMem-2]. And so forth.
92842 ** to hold cursors, it is faster to in-line the logic. */
92872 ** The string in pRec is known to look like an integer and to have a
92874 ** integer value if the string is in range to be an integer. Otherwise,
92893 ** If the bTryForInt flag is true, then extra effort is made to give
92896 ** will have a MEM_Int representation when bTryForInt is true.
92898 ** If bTryForInt is false, then if the input string contains a decimal
92899 ** point or exponential notation, the result is only MEM_Real, even
92900 ** if there is an exact integer representation of the quantity.
92916 /* TEXT->NUMERIC is many->one. Hence, it is important to invalidate the
92924 ** Processing is determine by the affinity parameter:
92931 ** is not possible. Note that the integer representation is
92932 ** always preferred, even if the affinity is REAL, because
92933 ** an integer representation is more space efficient on disk.
92936 ** If the value is text, then try to convert it into a number of
92944 ** No-op. pRec is unchanged.
92962 /* Only attempt the conversion to TEXT if there is an integer or real
92965 ** there is already a string rep, but it is pointless to waste those
92982 ** is appropriate. But only do the conversion if it is possible without
93190 ** This function is only called from within an assert() expression. It
93191 ** checks that the sqlite3.nTransaction variable is correctly set to
93258 ** For OP_Column, factor out the case where content is loaded from
93259 ** overflow pages, so that the code to implement this case is separate
93283 ** creating and managing the cache is such that this is only
93359 ** This is the core of sqlite3_step().
93369 u8 iCompareIsInit = 0; /* iCompare is initialized */
93466 /* Only allow tracing if SQLITE_DEBUG is defined.
93532 ** What follows is a massive switch statement where each case implements a
93535 ** that is a lot of wasted space on the left margin. So the code within
93540 ** The formatting of each case is important. The makefile for SQLite
93544 ** opcode and the opcodes.c file is filled with an array of strings where
93545 ** each string is the symbolic name for the corresponding opcode. If the
93546 ** case statement is followed by a comment of the form "/# same as ... #/"
93547 ** that comment is used to determine the particular value of the opcode.
93554 ** Documentation about VDBE opcodes is generated by scanning this file
93561 ** Formatting is important to scripts that scan this file.
93573 ** The P1 parameter is not actually used by this opcode. However, it
93574 ** is sometimes set to 1 instead of 0 as a hint to the command-line shell
93575 ** that this Goto is the bottom of a loop and that the lines from P2 down
93581 /* In debugging mode, when the p5 flags is set on an OP_Goto, that
93602 ** But that is not due to sloppy coding habits. The code is written this
93609 /* Call the progress callback if it is configured and the required number
93647 ** Jump to the address stored in register P1. If P1 is a return address
93650 ** If P3 is 1, then the jump is only taken if register P1 holds an integer
93652 ** OP_Return becomes a no-op. If P3 is 0, then register P1 must hold an
93653 ** integer or else an assert() is raised. P3 should be set to 1 when
93654 ** this opcode is used in combination with OP_BeginSubrtn, and set to 0
93657 ** The value in register P1 is unchanged by this opcode.
93659 ** P2 is not used by the byte-code engine. However, if P2 is positive
93663 ** in the subroutine from which this opcode is returning. Thus the P2
93664 ** value is a byte-code indentation hint. See tag-20220407a in
93710 ** The instruction at the address in register P1 is a Yield.
93734 ** If the coroutine that is launched by this instruction ends with
93757 ** Check the value in register P3. If it is NULL then Halt using
93759 ** value in register P3 is not NULL, then this routine is a no-op.
93777 ** P1 is the result code returned by sqlite3_exec(), sqlite3_reset(),
93785 ** If P4 is not null then it is an error message string.
93787 ** P5 is a value between 0 and 4, inclusive, that modifies the P4 string.
93795 ** If P5 is not zero and P4 is NULL, then everything after the ":" is
93798 ** There is an implied "Halt 0 0 0" instruction inserted at the very end of
93800 ** is the same as executing Halt.
93811 ** something is wrong with the code generator. Raise an assertion in order
93823 /* Instruction pcx is the OP_Program that invoked the sub-program
93825 ** instruction is set to OE_Ignore, then the sub-program is throwing
93871 ** The 32-bit integer value P1 is written into register P2.
93882 ** P4 is a pointer to a 64-bit integer value.
93896 ** P4 is a pointer to a 64-bit floating point value.
93911 ** P4 points to a nul terminated UTF-8 string. This opcode is transformed
93912 ** into a String opcode before it is executed for the first time. During
93913 ** this transformation, the length of string P4 is computed and stored
93951 ** The string value P4 of length P1 (bytes) is stored in register P2.
93953 ** If P3 is not zero and the content of register P3 is equal to P5, then
93954 ** the datatype of the register P2 is converted to BLOB. The content is
93955 ** the same sequence of bytes, it is merely interpreted as a BLOB instead
93985 ** is the same as the P2 operand to this opcode and that has P3 set to 1.
93986 ** If the subroutine is entered in-line, then the OP_Return will simply
93987 ** fall through. But if the subroutine is entered using OP_Gosub, then
93991 ** return address register contains a NULL, the OP_Return instruction is
93993 ** the OP_Return opcode has a P3 value of 1). Thus if the subroutine is
93995 ** continue. But if the subroutine is entered via OP_Gosub, then the
93998 ** This opcode is identical to OP_Null. It has a different name
94006 ** is less than P2 (typically P3 is zero) then only register P2 is
94009 ** If the P1 value is non-zero, then also set the MEM_Cleared flag so that
94010 ** NULL values will not compare equal even if SQLITE_NULLEQ is set on
94055 ** blob in register P2. If P4 is a NULL pointer, then construct
94056 ** a zero-filled blob that is P1 bytes long in P2.
94077 ** If the parameter is named, then its name appears in P4.
94078 ** The P4 value is used by sqlite3_bind_parameter_name().
94103 ** left holding a NULL. It is an error for register ranges
94104 ** P1..P1+P3-1 and P2..P2+P3-1 to overlap. It is an error
94149 ** If the 0x0002 bit of P5 is set then also clear the MEM_Subtype flag in the
94151 ** be merged. The 0x0001 bit is used by the query planner and does not
94155 ** is made of any string or blob constant. See also OP_SCopy.
94188 ** is a string or blob, then the copy is only a pointer to the
94190 ** Worse, if the original is deallocated, the copy becomes invalid.
94212 ** This is an optimized version of SCopy that works only for integer
94227 ** constraint violations, this is a no-op.
94230 ** exits. This opcode is used to raise foreign key constraint errors prior
94265 ** prepared statement restarts. This is because sqlite3_column()
94291 ** It is illegal for P1 and P3 to be the same register. Sometimes,
94292 ** if P3 is the same register as P2, the implementation is able
94358 ** If either input is NULL, the result is NULL.
94366 ** If either input is NULL, the result is NULL.
94373 ** If either input is NULL, the result is NULL.
94380 ** register P1 is zero, then the result is NULL. If either input is
94381 ** NULL, the result is NULL.
94386 ** Compute the remainder after integer register P2 is divided by
94388 ** If the value in register P1 is zero the result is NULL.
94389 ** If either operand is NULL, the result is NULL.
94479 ** P4 is a pointer to a CollSeq object. If the next call to a user function
94481 ** be returned. This is used by the built-in min(), max() and nullif()
94484 ** If P1 is not zero, then it is a register that a subsequent min() or
94485 ** max() aggregate will set to 1 if the current row is not the minimum or
94486 ** maximum. The P1 register is initialized to 0 by this instruction.
94489 ** to retrieve the collation sequence set by this opcode is not available
94505 ** If either input is NULL, the result is NULL.
94512 ** If either input is NULL, the result is NULL.
94520 ** If either input is NULL, the result is NULL.
94528 ** If either input is NULL, the result is NULL.
94586 ** The result is always an integer.
94601 ** in P1 is not an integer and cannot be converted into an integer
94629 ** This opcode is used when extracting information from a column that
94660 ** A NULL value is not changed by this routine. It remains NULL.
94688 ** SQLITE_AFF_TEXT, SQLITE_AFF_INTEGER, and so forth. An attempt is made
94690 ** comparison is made. If the SQLITE_AFF_MASK is 0x00, then numeric
94691 ** affinity is used. Note that the affinity conversions are stored
94695 ** Once any conversions have taken place, and neither value is NULL,
94696 ** the values are compared. If both values are blobs then memcmp() is
94699 ** P4 is used to do the comparison. If P4 is not specified then
94700 ** memcmp() is used to compare text string. If both values are
94701 ** numeric, then a numeric comparison is used. If the two values
94705 ** If SQLITE_NULLEQ is set in P5 then the result of comparison is always either
94706 ** true or false and is never NULL. If both operands are NULL then the result
94707 ** of comparison is true. If either operand is NULL then the result is false.
94708 ** If neither operand is NULL the result is the same as it would be if
94717 ** This works just like the Eq opcode except that the jump is taken if
94727 ** If the SQLITE_JUMPIFNULL bit of P5 is set and either reg(P1) or
94728 ** reg(P3) is NULL then the take the jump. If the SQLITE_JUMPIFNULL
94729 ** bit is clear then fall through if either operand is NULL.
94732 ** SQLITE_AFF_TEXT, SQLITE_AFF_INTEGER, and so forth. An attempt is made
94734 ** comparison is made. If the SQLITE_AFF_MASK is 0x00, then numeric
94735 ** affinity is used. Note that the affinity conversions are stored
94739 ** Once any conversions have taken place, and neither value is NULL,
94740 ** the values are compared. If both values are blobs then memcmp() is
94743 ** P4 is used to do the comparison. If P4 is not specified then
94744 ** memcmp() is used to compare text string. If both values are
94745 ** numeric, then a numeric comparison is used. If the two values
94755 ** This works just like the Lt opcode except that the jump is taken if
94756 ** the content of register P3 is less than or equal to the content of
94762 ** This works just like the Lt opcode except that the jump is taken if
94763 ** the content of register P3 is greater than the content of
94769 ** This works just like the Lt opcode except that the jump is taken if
94770 ** the content of register P3 is greater than or equal to the content of
94818 /* If SQLITE_NULLEQ is set (which will only happen if the operator is
94833 /* SQLITE_NULLEQ is clear and at least one operand is NULL,
94834 ** then the result is always NULL.
94835 ** The jump is taken if the SQLITE_JUMPIFNULL bit is set.
94846 /* Neither operand is NULL and we couldn't do the special high-speed
94883 /* At this point, res is negative, zero, or positive if reg[P1] is
94886 ** operator actually is. The next block of code depends on the fact
94948 ** instruction. The permutation is stored in the P4 operand.
94950 ** The permutation is only valid for the next opcode which must be
94953 ** The first integer in the P4 integer array is the length of the array
94971 ** If P5 has the OPFLAG_PERMUTE bit set, then the order of comparison is
94973 ** OPFLAG_PERMUTE bit is clear, then register are compared in sequential
94976 ** P4 is a KeyInfo structure that defines collating sequences and sort
94980 ** The comparison is a sort comparison, so NULLs compare equal,
95075 ** If either P1 or P2 is 0 (false) then the result is 0 even if
95076 ** the other input is NULL. A NULL and true or two NULLs give
95085 ** If either P1 or P2 is nonzero (true) then the result is 1 (true)
95086 ** even if the other input is NULL. A NULL and false or two NULLs
95120 ** boolean (a 0 or 1) in register P2. Or if the value in register P1 is
95121 ** NULL, then the P3 is stored in register P2. Invert the answer if P4
95122 ** is 1.
95124 ** The logic is summarized like this:
95146 ** boolean complement in register P2. If the value in register P1 is
95147 ** NULL, then a NULL is stored in P2.
95180 ** Fall through to the next instruction the first time this opcode is
95190 ** For subprograms, there is a bitmask in the VdbeFrame that determines
95191 ** whether or not the jump should be taken. The bitmask is necessary
95218 ** Jump to P2 if the value in register P1 is true. The value
95219 ** is considered true if it is numeric and non-zero. If the value
95220 ** in P1 is NULL then take the jump if and only if P3 is non-zero.
95232 ** Jump to P2 if the value in register P1 is False. The value
95233 ** is considered false if it has a numeric value of zero. If the value
95234 ** in P1 is NULL then take the jump if and only if P3 is non-zero.
95247 ** Jump to P2 if the value in register P1 is NULL.
95261 ** Jump to P2 if the type of a column in a btree is one of the types specified
95264 ** P1 is normally a cursor on a btree for which the row decode cache is
95266 ** a prior OP_Column for column P3 or greater. If the cursor is not valid,
95271 ** If P1 is -1, then P3 is a register number and the datatype is taken
95274 ** P5 is a bitmask of data types. SQLITE_INTEGER is the least significant
95275 ** (0x01) bit. SQLITE_FLOAT is the 0x02 bit. SQLITE_TEXT is 0x04.
95276 ** SQLITE_BLOB is 0x08. SQLITE_NULL is 0x10.
95280 ** that the datatype is REAL when it should be NULL. When P1<0 and the value
95281 ** is already stored in register P3, then this opcode does reliably
95372 ** Jump to P2 if the value in register P1 is not NULL.
95386 ** Check the cursor P1 to see if it is currently pointing at a NULL row.
95387 ** If it is, then set register P3 to NULL and jump immediately to P2.
95388 ** If P1 is not on a NULL row, then fall through without making any
95391 ** If P1 is not an open cursor, then this opcode is a no-op.
95408 ** Store in register r[P3] the byte offset into the database file that is the
95409 ** start of the payload for the record at which that cursor P1 is currently
95412 ** P2 is the column number for the argument to the sqlite_offset() function.
95413 ** This opcode does not use P2 itself, but the P2 value is used by the
95417 ** This opcode is only available if SQLite is compiled with the
95451 ** The value extracted is stored in register P3.
95454 ** if the P4 argument is a P4_MEM use the value of the P4 argument as
95457 ** If the OPFLAG_LENGTHARG bit is set in P5 then the result is guaranteed
95459 ** of large blobs is not loaded, thus saving CPU cycles. If the
95460 ** OPFLAG_TYPEOFARG bit is set then the result will only be used by the
95468 u32 *aOffset; /* aOffset[i] is offset to start of data for i-th column */
95534 assert( pC->szRow<=65536 ); /* Maximum page size is 64KiB */
95565 /* This is an optimization. By skipping over the first few tests
95569 ** This branch is taken even if aOffset[0]==0. Such a record is never
95575 ** this overread is harmless. Similar overreads can occur for a corrupt
95590 ** parsed and valid information is in aOffset[] and pC->aType[].
95593 /* If there is more header available for parsing in the record, try
95626 /* The record is corrupt if any of the following are true:
95650 /* If after trying to extract new entries from the header, nHdrParsed is
95682 /* This is the common case where the desired content fits on the original
95683 ** page - where the content is not on an overflow page */
95688 /* If the column value is a string, we need a persistent value, not
95689 ** a MEM_Ephem value. This branch is a fast short-cut that is equivalent
95711 /* This branch happens only when content is on overflow pages */
95719 /* Content is irrelevant for
95721 ** 2. the length(X) function if X is a blob, and
95722 ** 3. if the content length is zero.
95729 ** as that array is 256 bytes long (plenty for VdbeMemPrettyPrint())
95766 ** This opcode is similar to OP_Affinity except that this opcode
95767 ** forces the register type to the Table column type. This is used
95771 ** is zero. When P3 is non-zero, no type checking occurs for
95783 ** If any precondition is false, an assertion fault occurs.
95822 /* When applying REAL affinity, if the result is still an MEM_Int
95868 ** P4 is a string that is P2 characters long. The N-th character of the
95885 /* When applying REAL affinity, if the result is still an MEM_Int
95917 ** P4 may be a string that is P2 characters long. The N-th character of the
95921 ** The mapping from character to affinity is given by the SQLITE_AFF_
95924 ** If P4 is NULL then all index fields have the affinity BLOB.
95927 ** compile-time option is enabled:
95929 ** * If SQLITE_ENABLE_NULL_TRIM is enabled, then the P5 is the index
95932 ** * If SQLITE_ENABLE_NULL_TRIM is omitted, then P5 has the value
95933 ** OPFLAG_NOCHNG_MAGIC if the OP_MakeRecord opcode is allowed to
95934 ** accept no-change records with serial_type 10. This value is
95960 ** Data(0) is taken from register P1. Data(1) comes from register P1+1
95963 ** Each type field is a varint representing the serial type of the
95965 ** hdr-size field is also a varint which is the offset from the beginning
96003 ** as the schema format is 2 or more and none of the omitted columns
96016 ** out how much space is required for the new record. After this loop,
96099 /* If the value is IntReal and is going to take up 8 bytes to store
96138 ** value is the size of the header in bytes including the size varint
96154 ** the new record. The output register (pOp->p3) is not allowed to
96156 ** sqlite3VdbeMemClearAndResize() could clobber the value before it is used).
96159 /* The output register is already large enough to hold the record.
96160 ** No error checks or buffer enlargement is required */
96163 /* Need to make sure that the output is not too big and then enlarge
96255 ** If P3==0, then an exact count is obtained, which involves visiting
96256 ** every btree page of the table. But if P3 is non-zero, an estimate
96257 ** is returned based on the current cursor position.
96298 /* Assert that the p1 parameter is valid. Also that if there is no open
96318 /* This call is Ok even if this savepoint is actually a transaction
96320 ** If this is a transaction savepoint being opened, it is guaranteed
96321 ** that the db->aVTrans[] array is empty. */
96334 /* If there is no open transaction, then mark this as a special
96354 /* Find the named savepoint. If there is no such savepoint, then an
96355 ** an error is returned to the user. */
96367 /* It is not possible to release (commit) a savepoint if there are
96375 /* Determine whether or not this is a transaction savepoint. If so,
96376 ** and this is a RELEASE command, then the current transaction
96377 ** is committed.
96426 /* Regardless of whether this is a RELEASE or ROLLBACK, destroy all
96435 /* If it is a RELEASE, then destroy the savepoint being operated on
96436 ** too. If it is a ROLLBACK TO, then set the number of deferred
96468 ** Set the database auto-commit flag to P1 (1 or 0). If P2 is true, roll
96483 assert( db->nVdbeActive>0 ); /* At least this one VM is active */
96520 (iRollback)?"cannot rollback - no transaction is active":
96521 "cannot commit - no transaction is active"));
96531 ** Begin a transaction on database P1 if a transaction is not already
96533 ** If P2 is non-zero, then a write-transaction is started, or if a
96534 ** read-transaction is already active, it is upgraded to a write-transaction.
96535 ** If P2 is zero, then a read-transaction is started. If P2 is 2 or more
96536 ** then an exclusive transaction is started.
96538 ** P1 is the index of the database file on which the transaction is
96539 ** started. Index 0 is the main database file and index 1 is the
96543 ** If a write-transaction is started and the Vdbe.usesStmtJournal flag is
96544 ** true (this flag is set if the Vdbe may modify more than one row and may
96546 ** More specifically, a statement transaction is opened iff the database
96547 ** connection is currently not in autocommit mode, or if there are other
96550 ** entire transaction. If no error is encountered, the statement transaction
96556 ** This operation is used to detect when that the cookie has changed
96560 ** generation counter, then an SQLITE_SCHEMA error is raised and execution
96632 ** version is checked to ensure that the schema has not changed since the
96641 ** If virtual-tables are in use, this is not just an optimization.
96644 ** prepared queries. If such a query is out-of-date, we do not want to
96647 ** to be invalidated whenever sqlite3_step() is called from within
96657 ** from being modified in sqlite3VdbeHalt(). If this statement is
96668 ** P3==1 is the schema version. P3==2 is the database format.
96669 ** P3==3 is the recommended pager cache size, and so forth. P1==0 is
96670 ** the main database file and P1==1 is the database file used to store
96699 ** P2==1 is the schema version. P2==2 is the database format.
96700 ** P2==3 is the recommended pager cache
96701 ** size, and so forth. P1==0 is the main database file and P1==1 is the
96706 ** If P2 is the SCHEMA_VERSION cookie (cookie number 1) then the internal
96707 ** schema version is set to P3-P5. The "PRAGMA schema_version=N" statement
96735 ** schema is changed. Ticket #1644 */
96746 ** Open a read-only cursor for the database table whose root page is
96747 ** P2 in a database file. The database file is determined by P3.
96752 ** It is an error for P1 to be negative.
96762 ** a KeyInfo structure (P4_KEYINFO). If it is a pointer to a KeyInfo
96765 ** sequence of that index b-tree. Otherwise, if P4 is an integer
96775 ** checks to see if the cursor on P1 is already open on the same
96776 ** b-tree and if it is this opcode becomes a no-op. In other words,
96777 ** if the cursor is already open, do not reopen it.
96797 ** page is P2 (or whose root page is held in register P2 if the
96798 ** OPFLAG_P2ISREG bit is set in P5 - see below).
96801 ** a KeyInfo structure (P4_KEYINFO). If it is a pointer to a KeyInfo
96804 ** sequence of that index b-tree. Otherwise, if P4 is an integer
96813 ** <li> <b>0x08 OPFLAG_FORDELETE</b>: This cursor is used only to seek
96814 ** and subsequently delete entries in an index btree. This is a
96815 ** hint to the storage engine that the storage engine is allowed to
96816 ** ignore. The hint is not used by the official SQLite b*tree storage
96817 ** engine, but is used by COMDB2.
96846 /* If the cursor is not currently open or is open on a different
96964 ** opened for a database. Since there is already an open cursor when this
96965 ** opcode is run, the sqlite3BtreeCursor() cannot fail */
96975 ** The cursor is always opened read/write even if
96976 ** the main database is read-only. The ephemeral
96977 ** table is deleted automatically when the cursor is closed.
96979 ** If the cursor P1 is already opened on an ephemeral table, the table
96980 ** is cleared (all content is erased).
96982 ** P2 is the number of columns in the ephemeral table.
96984 ** if P4 is not 0. If P4 is not NULL, it points to a KeyInfo structure
96992 ** If P3 is positive, then reg[P3] is modified slightly so that it
96993 ** can be used as zero-length data for OP_Insert. This is an optimization
97019 ** form sqlite3BtreeInsert() where the length of the data is zero. */
97020 assert( pOp->p2==0 ); /* Only used when number of columns is zero */
97028 /* If the ephemeral table is already open and has no duplicates from
97029 ** OP_OpenDup, then erase all existing content so that the table is
97045 /* If a transient index is required, create it by calling
97047 ** opening it. If a transient table is required, just use the
97083 ** a transient index that is specifically designed to sort large
97086 ** If argument P3 is non-zero, then it indicates that the sorter may
97088 ** key is sufficient to produce the required results.
97108 ** P1 is a sorter cursor. If the sequence counter is currently zero, jump
97109 ** to P2. Regardless of whether or not the jump is taken, increment the
97127 ** row of data. The content of that one row is the content of memory
97131 ** A pseudo-table created by this opcode is used to hold a single
97134 ** is the only cursor opcode that works with a pseudo-table.
97136 ** P3 is the number of fields in the records that will be stored by
97152 ** which is a performance optimization */
97160 ** Close a cursor previously opened as P1. If P1 is not
97161 ** currently open, this instruction is a no-op.
97175 ** table or index for cursor P1 are used. P4 is a 64-bit integer
97178 ** by the cursor. The high-order bit is set if any column after
97179 ** the 64th is used.
97195 ** to an SQL index, then P3 is the first in an array of P4 registers
97199 ** is greater than or equal to the key value. If there are no records
97200 ** greater than or equal to the key and P2 is not zero, then jump to P2.
97204 ** else it will cause a jump to P2. When the cursor is OPFLAG_SEEKEQ,
97208 ** OPFLAG_SEEKEQ flags is a hint to the btree layer to say that this
97209 ** is an equality search.
97212 ** from the beginning toward the end. In other words, the cursor is
97222 ** to an SQL index, then P3 is the first in an array of P4 registers
97226 ** is greater than the key value. If there are no records greater than
97227 ** the key and P2 is not zero, then jump to P2.
97230 ** from the beginning toward the end. In other words, the cursor is
97240 ** to an SQL index, then P3 is the first in an array of P4 registers
97244 ** is less than the key value. If there are no records less than
97245 ** the key and P2 is not zero, then jump to P2.
97248 ** from the end toward the beginning. In other words, the cursor is
97258 ** to an SQL index, then P3 is the first in an array of P4 registers
97262 ** is less than or equal to the key value. If there are no records
97263 ** less than or equal to the key and P2 is not zero, then jump to P2.
97266 ** from the end toward the beginning. In other words, the cursor is
97271 ** else it will cause a jump to P2. When the cursor is OPFLAG_SEEKEQ,
97275 ** OPFLAG_SEEKEQ flags is a hint to the btree layer to say that this
97276 ** is an equality search.
97313 /* The OPFLAG_SEEKEQ/BTREE_SEEK_EQ flag is only set on index cursors */
97330 ** loss of information, then special processing is required... */
97345 /* If the approximation iKey is larger than the actual real search
97347 ** is 4.9 and the integer approximation 5:
97359 /* If the approximation iKey is smaller than the actual real search
97462 /* res might be negative because the table is empty. Check to
97463 ** see if this is the case.
97484 ** This opcode is a prefix opcode to OP_SeekGE. In other words, this
97485 ** opcode must be immediately followed by OP_SeekGE. This constraint is
97495 ** where the IN operator is on the later terms of the index by avoiding
97497 ** of the b-tree instead. A correct answer is obtained if this opcode
97498 ** is omitted or is a no-op.
97501 ** is the desired entry that we want the cursor SeekGE.P1 to be pointing
97504 ** If the SeekGE.P1 cursor is not currently pointing to a valid row,
97505 ** then this opcode is a no-op and control passes through into the OP_SeekGE.
97507 ** If the SeekGE.P1 cursor is pointing to a valid row, then that row
97509 ** target row, or it might be after the target row. If the cursor is
97514 ** The This.P5 parameter is a flag that indicates what to do if the
97515 ** cursor ends up pointing at a valid row that is past the target
97516 ** row. If This.P5 is false (0) then a jump is made to SeekGE.P2. If
97517 ** This.P5 is true (non-zero) then a jump is made to This.P2. The P5==0
97527 ** <li> If the cursor is initially not pointed to any valid row, then
97530 ** <li> If the cursor is left pointing to a row that is before the target
97534 ** <li> If the cursor is left pointing at the target row, either because it
97544 ** <li> If the cursor ends up on a valid row that is past the target row
97557 /* If pOp->p5 is clear, then pOp->p2 points to the first instruction past the
97662 ** so that it is no less than P2 and no greater than P3.
97665 ** there is known to be at least one match. If the seekHit value is smaller
97668 ** early, thus saving work. This is part of the IN-early-out optimization.
97699 ** If cursor P1 is not open or if P1 is set to a NULL row using the
97718 ** P4>0 then register P3 is the first of P4 registers that form an unpacked
97721 ** Cursor P1 is on an index btree. If the record identified by P3 and P4
97722 ** is a prefix of any entry in P1 then a jump is made to P2 and
97723 ** P1 is left pointing at the matching entry.
97735 ** P4>0 then register P3 is the first of P4 registers that form an unpacked
97738 ** Cursor P1 is on an index btree. If the record identified by P3 and P4
97739 ** is not the prefix of any entry in P1 then a jump is made to P2. If P1
97741 ** falls through to the next instruction and P1 is left pointing at the
97753 ** Register P3 is the first of P4 registers that form an unpacked
97754 ** record. Cursor P1 is an index btree. P2 is a jump destination.
97758 ** This opcode is an optimization attempt only. If this opcode always
97759 ** falls through, the correct answer is still obtained, but extra work
97760 ** is performed.
97764 ** if it is possible for a record P3:P4 to match some record in the
97765 ** index. If it is not possible, we can skip some work. So if seekHit
97766 ** is less than P4, attempt to find out if a match is possible by running
97769 ** This opcode is used in IN clause processing for a multi-column key.
97770 ** If an IN clause is attached to an element of the key other than the
97773 ** to the left is prohibiting a match, and hence there is "no hope" of
97777 ** jump is taken if there is "no hope" of achieving a match.
97785 ** P4>0 then register P3 is the first of P4 registers that form an unpacked
97788 ** Cursor P1 is on an index btree. If the record identified by P3 and P4
97790 ** record are not-NULL then a check is done to determine if any row in the
97792 ** immediately to P2. If there is a match, fall through and leave the P1
97795 ** This opcode is similar to OP_NotFound with the exceptions that the
97796 ** branch is always taken if any part of the search key input is NULL.
97811 printf("seekHit is %d\n", pC->seekHit);
97906 ** P1 is the index of a cursor open on an SQL table btree (with integer
97909 ** Or, if P2 is 0, raise an SQLITE_CORRUPT error. If P1 does contain
97930 ** P1 is the index of a cursor open on an SQL table btree (with integer
97931 ** keys). P3 is an integer rowid. If P1 does not contain a record with
97932 ** rowid P3 then jump immediately to P2. Or, if P2 is 0, raise an
97938 ** P3 register to contain a non-integer value, in which case the jump is
97965 ** changing the datatype of pIn3, however, as it is used by other
98016 ** The sequence number on the cursor is incremented after this
98033 ** The record number is not previously used as a key in the database
98034 ** table that cursor P1 points to. The new record number is written
98037 ** If P3>0 then P3 is a register in the root frame of this VDBE that holds
98040 ** an SQLITE_FULL error is generated. The P3 register is updated with the '
98041 ** generated record number. This P3 mechanism is used to help implement the
98065 ** thing) is obtained in a two-step algorithm.
98068 ** to that. But if the largest existing rowid is already the maximum
98072 ** The second algorithm is to select a rowid at random and see if
98109 /* Assert that P3 is a valid memory cell. */
98113 /* Assert that P3 is a valid memory cell. */
98117 /* Assert that P3 is a valid memory cell. */
98138 /* IMPLEMENTATION-OF: R-07677-41881 If the largest ROWID is equal to the
98141 ** it finds one that is not previously used. */
98142 assert( pOp->p3==0 ); /* We cannot be in random rowid mode if this is
98147 v &= (MAX_ROWID>>1); v++; /* Ensure that v is greater than zero */
98169 ** Write an entry into the table of cursor P1. A new entry is
98171 ** entry is overwritten. The data is the value MEM_Blob stored in register
98172 ** number P2. The key is stored in register P3. The key must
98175 ** If the OPFLAG_NCHANGE flag of P5 is set, then the row change count is
98176 ** incremented (otherwise not). If the OPFLAG_LASTROWID flag of P5 is set,
98177 ** then rowid is stored for subsequent return by the
98178 ** sqlite3_last_insert_rowid() function (otherwise it is unmodified).
98180 ** If the OPFLAG_USESEEKRESULT flag of P5 is set, the implementation might
98185 ** If the OPFLAG_ISUPDATE flag is set, then this opcode is part of an
98186 ** UPDATE operation. Otherwise (if the flag is clear) then this opcode
98187 ** is part of an INSERT operation. The difference is only important to
98190 ** Parameter P4 may point to a Table structure, or may be NULL. If it is
98191 ** not NULL, then the update-hook (sqlite3.xUpdateCallback) is invoked
98194 ** (WARNING/TODO: If P1 is a pseudo-cursor and P2 is dynamically
98195 ** allocated, then ownership of P2 is transferred to the pseudo-cursor
98196 ** and register P2 becomes ephemeral. If the cursor is changed, the
98201 ** for indices is OP_IdxInsert.
98206 VdbeCursor *pC; /* Cursor to table into which insert is written */
98294 ** of table - intkey or index. This opcode is used as part of copying
98297 ** P1. If they are opened on index tables, P3 is not used.
98320 ** Delete the record at which the P1 cursor is currently pointing.
98322 ** If the OPFLAG_SAVEPOSITION bit of the P5 parameter is set, then
98324 ** record in the table. If it is left pointing at the next record, then
98326 ** it is ok to delete a record from within a Next loop. If
98327 ** OPFLAG_SAVEPOSITION bit of P5 is clear, then the cursor will be
98330 ** If the OPFLAG_AUXDELETE bit is set on P5, that indicates that this
98331 ** delete is one of several associated with deleting a table row and
98332 ** all its associated index entries. Exactly one of those deletes is
98336 ** If the OPFLAG_NCHANGE (0x01) flag of P2 (NB: P2 not P5) is set, then
98337 ** the row change count is incremented (otherwise not).
98339 ** If the OPFLAG_ISNOOP (0x40) flag of P2 (not P5!) is set, then the
98340 ** pre-update-hook for deletes is run, but the btree is otherwise unchanged.
98341 ** This happens when the OP_Delete is to be shortly followed by an OP_Insert
98347 ** If P4 is not NULL then it points to a Table object. In this case either
98350 ** this case. Specifically, if one is configured, the pre-update hook is
98351 ** invoked if P4 is not NULL. The update-hook is invoked if one is configured,
98352 ** P4 is not NULL, and the OPFLAG_NCHANGE flag is set in P2.
98354 ** If the OPFLAG_ISUPDATE flag is set in P2, then P3 contains the address
98379 /* If p5 is zero, the seek operation that positioned the cursor prior to
98381 ** the row that is being deleted */
98389 ** of p4.pTab. Finally, if p5 is true, indicating that this cursor was
98461 ** The value of the change counter is copied to the database handle
98464 ** This is used by trigger programs.
98475 ** P1 is a sorter cursor. This instruction compares a prefix of the
98482 ** the comparison is assumed to be equal.
98511 ** This opcode is normally used to move a record out of the sorter and into
98512 ** a register that is the source for a pseudo-table cursor created using
98513 ** OpenPseudo. That pseudo-table cursor is the one that is identified by
98535 ** which cursor P1 is currently pointing.
98536 ** There is no interpretation of the data.
98537 ** It is just copied onto the P2 register exactly as
98538 ** it is found in the database file.
98540 ** If cursor P1 is an index, then the content is the key of the row.
98541 ** If cursor P2 is a table, then the content extracted is the data.
98546 ** If P3!=0 then this opcode is allowed to make an ephemeral pointer
98551 ** then a copy of the data is made into memory. P3!=0 is faster, but
98552 ** P3==0 is safer.
98554 ** If P3!=0 then the content of the P2 register is unsuitable for use
98556 ** The P2 register content is invalidated by opcodes like OP_Function or
98602 ** Store in register P2 an integer which is the key of the table entry that
98603 ** P1 is currently point to.
98653 ** that occur while the cursor is on the null row will always
98656 ** If cursor P1 is not previously opened, open it now to a special
98665 /* If the cursor is not already open, create a special kind of
98691 ** It is assumed that the cursor is used only for appending and so
98692 ** if the cursor is valid, then the cursor must already be pointing
98700 ** If the table or index is empty and P2>0, then jump immediately to P2.
98701 ** If P2 is 0 or if the table or index is not empty, fall through
98705 ** from the end toward the beginning. In other words, the cursor is
98746 ** estimate is less than approximately 2**(0.1*P3).
98777 ** This opcode is an alias for OP_Sort and OP_Rewind that is used
98785 ** Sorting is accomplished by writing records into a sorting index,
98789 ** regression tests can determine whether or not the optimizer is
98806 ** If the table or index is empty, jump immediately to P2.
98807 ** If the table or index is not empty, fall through to the following
98810 ** If P2 is zero, that is an assertion that the P1 table is never
98814 ** from the beginning toward the end. In other words, the cursor is
98859 ** The Next opcode is only valid following an SeekGT, SeekGE, or
98860 ** OP_Rewind opcode used to position the cursor. Next is not allowed
98866 ** The P3 value is a hint to the btree implementation. If P3==1, that
98867 ** means P1 is an SQL index and that this instruction could have been
98868 ** omitted if that index had been unique. P3 is usually 0. P3 is
98871 ** If P5 is positive and the jump is taken, then event counter
98872 ** number P5-1 in the prepared statement is incremented.
98879 ** table or index. If there is no previous key/value pairs then fall through
98884 ** The Prev opcode is only valid following an SeekLT, SeekLE, or
98885 ** OP_Last opcode used to position the cursor. Prev is not allowed
98888 ** The P1 cursor must be for a real table, not a pseudo-table. If P1 is
98889 ** not open then the behavior is undefined.
98891 ** The P3 value is a hint to the btree implementation. If P3==1, that
98892 ** means P1 is an SQL index and that this instruction could have been
98893 ** omitted if that index had been unique. P3 is usually 0. P3 is
98896 ** If P5 is positive and the jump is taken, then event counter
98897 ** number P5-1 in the prepared statement is incremented.
98966 ** into the index P1. Data for the entry is nil.
98968 ** If P4 is not zero, then it is the number of values in the unpacked
98969 ** key of reg(P2). In that case, P3 is the index of the first register
98973 ** If P5 has the OPFLAG_APPEND bit set, that is a hint to the b-tree layer
98974 ** that this insert is likely to be an append.
98976 ** If P5 has the OPFLAG_NCHANGE bit set, then the change counter is
98977 ** incremented by this instruction. If the OPFLAG_NCHANGE bit is clear,
98978 ** then the change counter is unchanged.
98980 ** If the OPFLAG_USESEEKRESULT flag of P5 is set, the implementation might
98987 ** for tables is OP_Insert.
99024 ** into the sorter P1. Data for the entry is nil.
99051 ** If P5 is not zero, then raise an SQLITE_CORRUPT_INDEX error
99052 ** if no matching index entry is found. This happens when running
99054 ** or deleted is not found. For some uses of IdxDelete
99056 ** entry is found. For those cases, P5 is zero. Also, do not raise
99096 ** P1 is an open index cursor and P3 is a cursor on the corresponding
99100 ** This is a deferred seek. Nothing actually happens until
99101 ** the cursor is used to read a record. That way, if no reads
99106 ** is non-zero, then reading column a(i)-1 from cursor P3 is
99108 ** from P1. This information is stored in P3 and used to redirect
99115 ** Write into register P2 an integer which is the last entry in the record at
99182 ** already occurred, this instruction is a no-op.
99201 ** that P1 is currently pointing to, ignoring the PRIMARY KEY or ROWID
99204 ** If the P1 index entry is greater than or equal to the key value
99212 ** that P1 is currently pointing to, ignoring the PRIMARY KEY or ROWID
99215 ** If the P1 index entry is greater than the key value
99223 ** the index that P1 is currently pointing to, ignoring the PRIMARY KEY or
99226 ** If the P1 index entry is less than the key value then jump to P2.
99234 ** the index that P1 is currently pointing to, ignoring the PRIMARY KEY or
99237 ** If the P1 index entry is less than or equal to the key value then jump
99317 ** file is given by P1.
99319 ** The table being destroyed is in the main database file if P3==0. If
99320 ** P3==1 then the table to be destroyed is in the auxiliary database file
99321 ** that is used to store tables create using CREATE TEMPORARY TABLE.
99323 ** If AUTOVACUUM is enabled then it is possible that another root page
99327 ** is stored in register P2. If no page movement was required (because the
99329 ** zero is stored in register P2. If AUTOVACUUM is disabled then a zero
99330 ** is stored in register P2.
99333 ** it is invoked. This is done to avoid the difficulty associated with
99334 ** updating existing cursors when a root page is moved in an AUTOVACUUM
99335 ** database. This error is thrown even if the database is not an AUTOVACUUM
99377 ** in the database file is given by P1. But, unlike Destroy, do not
99380 ** The table being cleared is in the main database file if P2==0. If
99381 ** P2==1 then the table to be cleared is in the auxiliary database file
99382 ** that is used to store tables create using CREATE TEMPORARY TABLE.
99384 ** If the P3 value is non-zero, then the row change count is incremented
99385 ** by the number of rows in the table being cleared. If P3 is greater
99386 ** than zero, then the value stored in register P3 is also incremented
99414 ** that is open on cursor P1.
99443 ** The root page number of the new b-tree is stored in register P2.
99468 ** P1 is true.
99508 ** that match the WHERE clause P4. If P4 is a NULL pointer, then the
99509 ** entire schema for P1 is reparsed.
99512 ** then runs the new virtual machine. It is thus a re-entrant opcode.
99521 ** on every btree. This is a prerequisite for invoking
99568 ** the sqlite_schema table is corrupt. */
99603 ** the table named P4 in database P1. This is called after a table
99604 ** is dropped from disk (using the Destroy opcode) in order to keep
99606 ** schema consistent with what is on disk.
99617 ** the index named P4 in database P1. This is called after an index
99618 ** is dropped from disk (using the Destroy opcode)
99620 ** schema consistent with what is on disk.
99631 ** the trigger named P4 in database P1. This is called after a trigger
99632 ** is dropped from disk (using the Destroy opcode) in order to keep
99634 ** schema consistent with what is on disk.
99653 ** seen. Reg(P1) is updated with the number of errors remaining.
99658 ** If P5 is not zero, the check is done on the auxiliary database
99661 ** This opcode is used to implement the integrity_check pragma.
99706 ** An assertion fails if P2 is not an integer.
99725 ** Or, if RowSet object P1 is initially empty, leave P3
99736 /* The boolean index is empty */
99751 ** Register P3 is assumed to hold a 64-bit integer value. If register P1
99757 ** The RowSet object is optimized for the case where sets of integers
99759 ** Each set is identified by a unique P4 value. The first set
99763 ** This allows optimizations: (a) when P4==0 there is no need to test
99764 ** the RowSet object for P3, as it is guaranteed not to contain it,
99765 ** (b) when P4==-1 there is no need to insert the value, as it will
99766 ** never be tested for, and (c) when a value that is part of set X is
99767 ** inserted, there is no need to search to see if the same value was
99780 /* If there is anything other than a rowset object in memory cell P1,
99811 ** of a memory cell in this (the parent) VM that is used to allocate the
99814 ** P4 is a pointer to the VM containing the trigger program.
99816 ** If P5 is non-zero, then recursive program invocation is enabled.
99832 /* If the p5 flag is clear, then recursive invocation of triggers is
99833 ** disabled for backwards compatibility (p5 is set if this sub-program
99834 ** is really a trigger, not a foreign key action, and the flag set
99835 ** and cleared by the "PRAGMA recursive_triggers" command is clear).
99837 ** It is recursive invocation of triggers, at the SQL level, that is
99855 /* Register pRt is used to store the memory required to save the state
99858 ** is already allocated. Otherwise, it must be initialized. */
99860 /* SubProgram.nMem is set to the number of memory cells used by the
99862 ** cell is required for each cursor used by the program. Set local
99936 MemSetTypeFlag(&aMem[i], MEM_Undefined); /* Fault if this reg is reused */
99946 ** This opcode is only ever present in sub-programs called via the
99949 ** address space. This is used by trigger programs to access the new.*
99952 ** The address of the cell in the parent frame is determined by adding
99973 ** If P1 is non-zero, the database constraint counter is incremented
99974 ** (deferred foreign key constraints). Otherwise, if P1 is zero, the
99975 ** statement counter is incremented (immediate foreign key constraints).
99991 ** This opcode tests if a foreign key constraint-counter is currently zero.
99995 ** If P1 is non-zero, then the jump is taken if the database constraint-counter
99996 ** is zero (the one that counts deferred constraint violations). If P1 is
99997 ** zero, the jump is taken if the statement constraint-counter is zero
100016 ** P1 is a register in the root frame of this VM (the root frame is
100017 ** different from the current frame if this instruction is being executed
100021 ** This instruction throws an error if the memory cell is not initially
100047 ** If the value of register P1 is 1 or greater, subtract P3 from the
100050 ** If the initial value of register P1 is less than 1, then the
100051 ** value is unchanged and control passes through to the next instruction.
100071 ** value computed is the total number of rows that will need to be
100074 ** If r[P3] is zero or negative, that means there is no OFFSET
100075 ** and r[P2] is set to be the value of the LIMIT, r[P1].
100077 ** if r[P1] is zero or negative, that means there is no LIMIT
100078 ** and r[P2] is set to -1.
100080 ** Otherwise, r[P2] is set to the sum of r[P1] and r[P3].
100091 /* If the LIMIT is less than or equal to zero, loop forever. This
100092 ** is documented. But also, if the LIMIT+OFFSET exceeds 2^63 then
100093 ** also loop forever. This is undocumented. In fact, one could argue
100097 ** looping forever is a reasonable approximation. */
100108 ** Register P1 must contain an integer. If the content of register P1 is
100110 ** If it is non-zero (negative or positive) and then also jump to P2.
100111 ** If register P1 is initially zero, leave it unchanged and fall through.
100128 ** and jump to P2 if the new value is exactly zero.
100144 ** The function has P5 arguments. P4 is a pointer to the
100145 ** FuncDef structure that specifies the function. Register P3 is the
100155 ** The function has P5 arguments. P4 is a pointer to the
100156 ** FuncDef structure that specifies the function. Register P3 is the
100166 ** aggregate. The function has P5 arguments. P4 is a pointer to the
100167 ** FuncDef structure that specifies the function. Register P3 is the
100173 ** This opcode is initially coded as OP_AggStep0. On first evaluation,
100174 ** the FuncDef stored in P4 is converted into an sqlite3_context and
100175 ** the opcode is changed. In this way, the initialization of the
100223 /* This is an OP_AggInverse call. Verify that xStep has always
100227 /* This is an OP_AggStep call. Mark it as such. */
100232 /* If this function is inside of a trigger, the register array in aMem[]
100283 ** P1 is the memory location that is the accumulator for an aggregate
100287 ** P2 is the number of arguments that the step function takes and
100288 ** P4 is a pointer to the FuncDef for this function. The P2
100289 ** argument is not used by this opcode. It is only there to disambiguate
100291 ** P4 argument is only needed for the case where
100299 ** P2 is the number of arguments that the step function takes and
100300 ** P4 is a pointer to the FuncDef for this function. The P2
100301 ** argument is not used by this opcode. It is only there to disambiguate
100303 ** P4 argument is only needed for the case where
100337 ** Checkpoint database P1. This is a no-op if P1 is not currently in
100338 ** WAL mode. Parameter P2 is one of SQLITE_CHECKPOINT_PASSIVE, FULL,
100377 ** modes (delete, truncate, persist, off and memory), this is a simple
100378 ** operation. No IO is required.
100380 ** If changing into or out of WAL mode the procedure is more complicated.
100481 ** Vacuum the entire database P1. P1 is 0 for "main", and 2 or more
100484 ** If P2 is not zero, then it is a register holding a string which is
100486 ** P2 is zero, the vacuum overwrites the original database.
100525 ** is executed using sqlite3_step() it will either automatically
100529 ** If P1 is 0, then all SQL statements become expired. If P1 is non-zero,
100530 ** then only the currently executing statement is expired.
100532 ** If P2 is 0, then SQL statements are expired immediately. If P2 is 1,
100550 ** Lock the btree to which cursor P1 is pointing so that the btree cannot be
100565 ** Unlock the btree to which cursor P1 is pointing so that it can be
100582 ** Obtain a lock on a particular table. This instruction is only used when
100583 ** the shared-cache feature is enabled.
100585 ** P1 is the index of the database in sqlite3.aDb[] of the database
100586 ** on which the lock is acquired. A readlock is obtained if P3==0 or
100591 ** P4 contains a pointer to the name of the table being locked. This is only
100605 sqlite3VdbeError(p, "database table is locked: %s", z);
100620 ** Also, whether or not P4 is set, check that this is not being called from
100621 ** within a callback to a virtual table xSync() method. If it is, the error
100637 ** P2 is a register that holds the name of a virtual table in database
100646 /* Because P2 is always a static string, it is impossible for the
100666 ** P4 is the name of a virtual table in database P1. Call the xDestroy method
100682 ** P4 is a pointer to a virtual table object, an sqlite3_vtab structure.
100683 ** P1 is a cursor number. This opcode opens a cursor to the virtual
100725 ** P4 is a pointer to a Table object that is a virtual table in schema P1
100728 ** an error is reported back, the table name is prepended to the error
100729 ** message and that message is stored in P2. If no errors are seen,
100730 ** register P2 is set to NULL.
100776 ** cursor. Register P3 is used to hold the values returned by
100800 ** P1 is a cursor opened using VOpen. P2 is an address to jump to if
100801 ** the filtered result set is empty.
100803 ** P4 is either NULL or a string that was generated by the xBestIndex
100804 ** method of the module. The interpretation of the P4 string is left
100808 ** by P1. The integer query plan parameter to xFilter is stored in register
100814 ** A jump is made to P2 if the result set after filtering would be empty.
100868 ** If the VColumn opcode is being used to fetch the value of
100870 ** value is OPFLAG_NOCHNG. This will cause the sqlite3_vtab_nochange()
100948 /* Invoke the xNext() method of the module. There is no way for the
100950 ** xNext(). Instead, if an error occurs, true is returned (indicating that
100951 ** data is available) and the error code returned when xColumn or
100952 ** some other method is next invoked on the save virtual table cursor.
100960 /* If there is data, jump to P2 */
100970 ** P4 is a pointer to a virtual table object, an sqlite3_vtab structure.
100972 ** in register P1 is passed as the zName argument to the xRename method.
101006 ** P4 is a pointer to a virtual table object, an sqlite3_vtab structure.
101014 ** is the rowid of a row to delete. If argv[0] is NULL then no
101015 ** deletion occurs. The argv[1] element is the rowid of the new
101020 ** If P2==1 then no insert is performed. argv[0] is the rowid of
101023 ** P1 is a boolean flag. If it is set to true and the xUpdate call
101024 ** is successful, then the value returned by sqlite3_last_insert_rowid()
101025 ** is set to the value of the rowid for the row just inserted.
101027 ** P5 is the error actions (OE_Replace, OE_Fail, OE_Ignore, etc) to
101127 ** Invoke a user function (P4 is a pointer to an sqlite3_context object that
101129 ** from register P2 and successors. The number of arguments is in
101131 ** The result of the function is stored
101134 ** P1 is a 32-bit bitmask indicating whether or not each argument to the
101136 ** argument was constant then bit 0 of P1 is set. This is used to determine
101146 ** Invoke a user function (P4 is a pointer to an sqlite3_context object that
101148 ** from register P2 and successors. The number of arguments is in
101150 ** The result of the function is stored
101153 ** P1 is a 32-bit bitmask indicating whether or not each argument to the
101155 ** argument was constant then bit 0 of P1 is set. This is used to determine
101160 ** This opcode works exactly like OP_Function. The only difference is in
101161 ** its name. This opcode is used in places where the function must be
101178 /* If this function is inside of a trigger, the register array in aMem[]
101255 ** If P1 is NULL, clear the subtype from p2.
101302 ** with r[P3]. Check to see if that hash is found in the
101303 ** bloom filter hosted by register P1. If it is not present then
101306 ** False negatives are harmless. It is always safe to fall through,
101307 ** even if the value is in the bloom filter. A false negative causes
101310 ** false positive - if the jump is taken when it should fall through.
101343 ** Write P4 on the statement trace output if statement tracing is
101354 ** If tracing is enabled (by the sqlite3_trace()) interface, then
101355 ** the UTF-8 string contained in P4 is emitted on the trace callback.
101356 ** Or if P4 is blank, use the string returned by sqlite3_sql().
101358 ** If P2 is not zero, jump to instruction P2.
101363 ** If P3 is not zero, then it is an address to jump to if an SQLITE_CORRUPT
101364 ** error is encountered.
101373 /* If the P4 argument is not NULL, then it must be an SQL comment string.
101374 ** The "--" string is broken up to prevent false-positives with srcck1.c.
101384 /* OP_Init is always instruction 0 */
101444 ** expression refer to columns in the b-tree to which cursor P1 is pointing.
101468 ** An Abort is safe if either there have been no writes, or if there is
101482 ** the registers is unreliable after this opcode completes.
101486 ** In other words, P3 is a mask of registers to preserve.
101493 ** If P5 is set, then all released registers have their type set
101495 ** register (before it is reinitialized) will generate an assertion fault.
101503 ** This opcode is only available in testing and debugging builds. It is
101504 ** not generated for release builds. The purpose of this opcode is to help
101528 ** Do nothing. This instruction is often useful as a jump
101533 ** is to say when the EXPLAIN QUERY PLAN syntax is used.)
101534 ** This opcode records information from the optimizer. It is the
101537 default: { /* This is really OP_Noop, OP_Explain */
101562 ** of the program. It is only here for testing and debugging.
101564 ** the evaluator loop. So we can leave it out when NDEBUG is defined.
101590 /* If we reach this point, it means that execution is finished with
101630 /* This is the only way out of this procedure. We have to
101666 ** is encountered.
101697 ** a legal notice, here is a blessing:
101720 u16 iCol; /* Table column this handle is open on */
101730 ** This function is used by both blob_open() and blob_reopen(). It seeks
101732 ** If successful, SQLITE_OK is returned and subsequent calls to
101737 ** blob handle was opened, then an error code is returned and *pzErr may
101738 ** be set to point to a buffer containing an error message. It is the
101742 ** If an error does occur, then the b-tree cursor is closed. All subsequent
101752 ** This is done directly as a performance optimization
101756 /* If the statement has been run before (and is paused at the OP_ResultRow)
101759 ** counter is faster. */
101895 /* If the value is being opened for writing, check that the
101896 ** column is not indexed, and that it is not part of a foreign key.
101903 /* Check that the column is not part of an FK child key definition. It
101904 ** is not necessary to check if it is part of a parent key, as parent
101943 ** of writing code to use the b-tree layer directly is that the
101977 /* Make sure a mutex is held on the table to be accessed */
102003 ** always return an SQL NULL. This is useful because it means
102087 /* Request is out of range. Return a transient error. */
102090 /* If there is no statement handle, then the blob-handle has
102095 /* Call either BtreeData() or BtreePutData(). If SQLITE_ABORT is
102103 /* If a pre-update hook is registered and this is a write cursor,
102106 ** TODO: The preupdate-hook is passed SQLITE_DELETE, even though this
102107 ** operation should really be an SQLITE_UPDATE. This is probably
102108 ** incorrect, but is convenient because at this point the new.* values
102110 ** SQLITE_UPDATE where the PK columns do not change is handled in the
102111 ** same way as an SQLITE_DELETE (the SQLITE_DELETE code is actually
102158 ** The Incrblob.nByte field is fixed for the lifetime of the Incrblob
102159 ** so no mutex is required for access.
102171 ** contain a blob or text value, then an error code is returned and the
102186 /* If there is no statement handle, then the blob-handle has
102215 ** a legal notice, here is a blessing:
102228 ** algorithm that is efficient even if the number of elements being sorted
102231 ** Here is the (internal, non-API) interface between this module and the
102237 ** object. The row is a binary blob in the
102257 ** X is strictly less than the read cursor.
102265 ** is like Close() followed by Init() only
102283 ** a threshold, when Rewind() is called the set of records is sorted using
102291 ** A PMA created at this point is known as a "level-0 PMA". Higher levels
102296 ** records to a PMA is roughly the same as the limit configured for the
102297 ** page-cache of the main database. Specifically, the threshold is set to
102301 ** If the sorter is running in single-threaded mode, then all PMAs generated
102302 ** are appended to a single temporary file. Or, if the sorter is running in
102304 ** N is the configured number of worker threads. In this case, instead of
102310 ** The sorter is running in multi-threaded mode if (a) the library was built
102315 ** When Rewind() is called, any data remaining in memory is flushed to a
102316 ** final PMA. So at this point the data is stored in some number of sorted
102320 ** sorter is running in single-threaded mode, then these PMAs are merged
102325 ** Or, if running in multi-threaded mode, then a background thread is
102331 ** Parameter T is set to half the value of the memory threshold used
102335 ** Rewind() is called, then a hierarchy of incremental-merges is used.
102339 ** PMAs at a time. This done is to improve locality.
102342 ** SORTER_MAX_MERGE_COUNT PMAs on disk when Rewind() is called, then more
102352 ** If SQLITE_DEBUG_SORTER_THREADS is defined, this module outputs various
102362 ** to a level 0 PMA. The purpose of this limit is to prevent various integer
102391 ** If aMemory==0 then each object is allocated separately and the objects
102403 ** The MergeEngine object is used to combine two or more smaller PMAs into
102409 ** merged. An aReadr[] object either points to a valid key or else is at EOF.
102410 ** ("EOF" means "End Of File". When aReadr[] is at EOF there is no more data.)
102411 ** For the purposes of the paragraphs below, we assume that the array is
102412 ** actually N elements in size, where N is the smallest power of 2 greater
102416 ** The aTree[] array is also N elements in size. The value of N is stored in
102421 ** comparing aReadr[2*i-N] and aReadr[2*i-N+1]. Whichever key is smaller, the
102422 ** aTree element is set to the index of it.
102424 ** For the purposes of this comparison, EOF is considered greater than any
102426 ** values), it doesn't matter which index is stored.
102431 ** currently points to the smallest key value. aTree[0] is unused.
102446 ** The current element is "Apple" (the value of the key indicated by
102447 ** PmaReader 5). When the Next() operation is invoked, PmaReader 5 will
102448 ** be advanced to the next key in its segment. Say the next key is
102455 ** 5 value is still smaller, so aTree[6] is set to 5. And so on up the tree.
102456 ** The value of PmaReader 6 - "Durian" - is now smaller than that of PmaReader
102457 ** 5, so aTree[3] is set to 6. Key 0 is smaller than key 6 (Banana<Durian),
102458 ** so the value written into element 1 of the array is 0. As follows:
102463 ** key comparison operations are required, where N is the number of segments
102477 ** other way. VdbeSorter.nTask is set to the number of worker threads allowed
102479 ** single-threaded operation, there is exactly one instance of this object
102487 ** Before a background thread is launched, variable bDone is set to 0. Then,
102488 ** right before it exits, the thread itself sets bDone to 1. This is used for
102492 ** attempt to select a SortSubtask for which there is not already an
102496 ** 2. If SQLITE_DEBUG_SORTER_THREADS is defined, to determine if a call
102497 ** to sqlite3ThreadJoin() is likely to block. Cases that are likely to
102507 int bDone; /* Set if thread is finished but not joined */
102519 ** Main sorter structure. A single instance of this is allocated for each
102524 ** this variable is updated so as to be set to the size on disk of the
102552 ** An instance of the following object is used to read records out of a
102553 ** PMA, in sorted order. The next key to be read is cached in nKey/aKey.
102555 ** contain a contiguous representation of the key, then aAlloc is allocated
102556 ** and the key is copied into aAlloc and aKey is made to point to aAlloc.
102584 ** and aFile[1]. Neither file is allowed to grow to more than mxSz bytes in
102585 ** size. When the IncrMerger is initialized, it reads enough data from
102602 ** threaded IncrMerger the allocate part of pTask->file2 is "refilled" with
102611 int bEof; /* Set to true when merge is finished */
102617 ** An instance of this object is used for writing a PMA.
102619 ** The PMA is written one record at a time. Each record is of an arbitrary
102620 ** size. But I/O is more efficient if it occurs in page-sized blocks where
102621 ** each block is aligned on a page boundary. This object caches writes to
102635 ** This object is the header on a single record while that record is being
102638 ** How the linked list is connected depends on how memory is being managed
102640 ** (VdbeSorter.list.aMemory==0), then the list is always connected using the
102644 ** then while records are being accumulated the list is linked using the
102645 ** SorterRecord.u.iNext offset. This is because the aMemory[] array may
102648 ** is full, the list is sorted. As part of the sorting process, it is
102693 ** The buffer returned in *ppOut is only valid until the
102712 /* If there is no more data to be read from the buffer, read the next
102736 /* The requested data is available in the in-memory buffer. In this
102737 ** case there is no need to make a copy of the data, just return a
102742 /* The requested data is not all available in the in-memory buffer.
102758 /* Copy as much data as is available in the buffer into the start of
102816 ** new mapping and return SQLITE_OK. If the mapping is not attempted
102817 ** (because the file is too large or the VFS layer is configured not to use
102821 ** *pp is undefined in this case.
102836 ** Attach PmaReader pReadr to file pFile (if it is not already attached to
102842 PmaReader *pReadr, /* Reader whose cursor is to be moved */
102906 /* This is an EOF condition */
102929 ** PMA is empty).
102931 ** If the pnByte parameter is NULL, then it is assumed that the file
102964 ** determined that the first field of key1 is equal to the first field of
102969 int *pbKey2Cached, /* True if pTask->pUnpacked is pKey2 */
102986 ** If IN/OUT parameter *pbKey2Cached is true when this function is called,
102987 ** it is assumed that (pTask->pUnpacked) contains the unpacked version
102988 ** of key2. If it is false, (pTask->pUnpacked) is populated with the unpacked
102991 ** If an OOM error is encountered, (pTask->pUnpacked->error_rc) is set
102996 int *pbKey2Cached, /* True if pTask->pUnpacked is pKey2 */
103010 ** the first field of each key is a TEXT value and that the collation
103011 ** sequence to compare them with is BINARY.
103015 int *pbKey2Cached, /* True if pTask->pUnpacked is pKey2 */
103053 ** the first field of each key is an INTEGER value.
103057 int *pbKey2Cached, /* True if pTask->pUnpacked is pKey2 */
103125 ** is non-zero and the sorter is able to guarantee a stable sort, nField
103126 ** is used instead. This is used when sorting records for a CREATE INDEX
103129 ** of the records being sorted. So if the sort is stable, there is never
103136 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
103210 /* A negative cache-size value C indicates that the cache is abs(C)
103361 /* This function is always called by the main user thread.
103363 ** If this function is being called after SorterRewind() has been called,
103364 ** it is possible that thread pSorter->aTask[pSorter->nTask-1].pThread
103365 ** is currently attempt to join one of the other threads. To avoid a race
103384 ** nReader is automatically rounded up to the next power of two.
103488 ** The first argument is a file-handle open on a temporary file. The file
103489 ** is guaranteed to be nByte bytes or smaller in size. This function
103712 ** Return SQLITE_OK if flushing the buffered data succeeds or is not
103749 ** The format of a PMA is:
103756 ** key). The varint is the number of bytes in the blob of data.
103765 ** This is used by an assert() statement at the end of this function. */
103817 ** Set *pbEof to true there is no next entry because
103860 ** case there is no cache of pReadr2 in pTask->pUnpacked, so set
103871 ** is sorted from oldest to newest, so pReadr1 contains older values
103922 ** records to disk. If the sorter is running in multi-threaded mode,
103924 ** the background thread from a sub-tasks previous turn is still running,
104006 ** flush the contents of memory to a new PMA if (a) at least one value is
104012 ** * The total memory allocated for the in-memory list is greater
104015 ** * The total memory allocated for the in-memory list is greater
104086 ** of the data stored in aFile[1] is the same as that used by regular PMAs,
104087 ** except that the number-of-bytes varint is omitted from the start.
104108 /* Check if the output file is full or if the input has been exhausted.
104149 ** This function is called when the PmaReader corresponding to pIncr has
104150 ** finished reading the contents of aFile[0]. Its purpose is to "refill"
104154 ** For single-threaded objects, this is accomplished by literally reading
104157 ** For multi-threaded objects, all that is required is to wait until the
104158 ** background thread is finished (if it is not already) and then swap
104163 ** SQLITE_OK is returned on success, or an SQLite error code otherwise.
104201 ** If an OOM condition is encountered, return NULL. In this case free the
104291 ** Only INCRINIT_NORMAL is valid in single-threaded builds (when
104311 ** If argument eMode is INCRINIT_ROOT, then it is assumed that any IncrMerge
104314 ** set the PmaReader objects up to read from it. In this case all that is
104315 ** required is to call vdbePmaReaderNext() on each PmaReader to point it at
104318 ** Otherwise, if eMode is any value other than INCRINIT_ROOT, then use
104322 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
104337 /* eMode is always INCRINIT_NORMAL in single-threaded mode */
104340 /* Verify that the MergeEngine is assigned to a single thread */
104349 ** However, in the INCRINIT_ROOT case, if PmaReader aReadr[nTask-1] is
104368 ** The PmaReader passed as the first argument is guaranteed to be an
104373 ** If argument eMode is set to INCRINIT_NORMAL, then all PmaReaders
104374 ** in the sub-tree headed by pReadr are also initialized. Data is then
104375 ** loaded into the buffers belonging to pReadr and it is set to point to
104378 ** If argument eMode is set to INCRINIT_TASK, then pReadr is guaranteed
104379 ** to be a multi-threaded PmaReader and this function is being called in a
104382 ** pReadr is populated. However, pReadr itself is not set up to point
104383 ** to its first key. A call to vdbePmaReaderNext() is still required to do
104387 ** in the INCRINIT_TASK case is that vdbePmaReaderNext() assumes that it has
104389 ** this entire function is being run by thread (pTask->thread), that will
104392 ** Finally, if argument eMode is set to INCRINIT_ROOT, it may be assumed
104393 ** that pReadr->pIncr is a multi-threaded IncrMerge objects, and that all
104395 ** In this case vdbePmaReaderNext() is called on all child PmaReaders and
104398 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
104406 /* eMode is always INCRINIT_NORMAL in single-threaded mode */
104441 ** PmaReader is multi-threaded. If this is an INCRINIT_TASK object,
104442 ** then this function is already running in background thread
104445 ** If this is the INCRINIT_ROOT object, then it is running in the
104446 ** main VDBE thread. But that is Ok, as that thread cannot return
104478 ** If the PmaReader passed as the first argument is not an incremental-reader
104479 ** (if pReadr->pIncr==0), then this function is a no-op. Otherwise, it invokes
104483 ** If the IncrMerger object is multi-threaded (IncrMerger.bUseThread==1),
104484 ** then a background thread is launched to call vdbePmaReaderIncrMergeInit().
104485 ** Or, if the IncrMerger is single threaded, the same function is called
104512 ** When this function is called, *piOffset is set to the offset of the
104513 ** first PMA to read from pTask->file. Assuming no error occurs, it is
104516 ** *piOffset is undefined.
104568 ** pRoot is the root of an incremental merge-tree with depth nDepth (according
104569 ** to vdbeSorterTreeDepth()). pLeaf is the iSeq'th leaf to be added to the
104572 ** If successful, SQLITE_OK is returned. If an error occurs, an SQLite error
104573 ** code is returned and pLeaf is freed.
104621 ** This function is called as part of a SorterRewind() operation on a sorter
104626 ** If successful, SQLITE_OK is returned and *ppOut set to point to the
104628 ** error occurs, an SQLite error code is returned and the final value
104629 ** of *ppOut is undefined.
104702 ** This function is called as part of an sqlite3VdbeSorterRewind() operation
104708 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
104751 ** a) The incremental merge object is configured to use the
104753 ** b) If it is using task (nTask-1), it is configured to run
104754 ** in single-threaded mode. This is important, as the
104789 ** this function is called to prepare for iterating through the records
104816 ** So the list is never empty at this point. */
104936 ** key in pVal is smaller than, equal to or larger than the current sorter
104940 ** turn is used to verify uniqueness when constructing a UNIQUE INDEX.
104984 ** a legal notice, here is a blessing:
105013 sqlite3_stmt *pStmt; /* The statement whose bytecode is displayed */
105083 ** This method is the destructor for bytecodevtab objects.
105175 ** is currently pointing.
105257 break; /* Result is NULL for the main program */
105298 ** rowid is the same as the output value.
105340 "argument to %s() is not a valid SQL statement",
105352 ** into the xFilter method. If there is no valid stmt=? constraint,
105433 ** a legal notice, here is a blessing:
105442 ** The in-memory rollback journal is used to journal transactions for
105443 ** ":memory:" databases and when the journal_mode=MEMORY pragma is used.
105445 ** Update: The in-memory journal is also used to temporarily cache
105462 ** The rollback journal is composed of a linked list of these structures.
105464 ** The zChunk array is always at least 8 bytes in size - usually much more.
105465 ** Its actual size is stored in the MemJournal.nChunkSize variable.
105493 ** This structure is a subclass of sqlite3_file. Each open memory-journal
105494 ** is an instance of this class.
105511 ** Read data from the in-memory journal file. This is the implementation
105638 ** access writes are not required. The only exception to this is when
105639 ** the in-memory journal is being used by a connection using the
105657 /* New chunk is required to extend the file. */
105728 ** syncing an in-memory journal is a no-op.
105773 ** nSpill. If nSpill is 0, then the journal file is always create and
105774 ** accessed using the underlying VFS. If nSpill is less than zero, then
105775 ** all content is always stored in main-memory. Finally, if nSpill is a
105776 ** positive value, then the journal file is initially created in-memory
105777 ** but may be flushed to disk later on. In this case the journal file is
105779 ** or when sqlite3JournalCreate() is called.
105794 ** case none of the code in this module is executed as a result of calls
105826 ** If the argument p points to a MemJournal structure that is not an
105827 ** in-memory-only journal file (i.e. is one that was opened with a +ve
105840 ** a NEVER(), in case our analysis is subtly flawed. */
105854 ** The file-handle passed as the only argument is open on a journal file.
105855 ** Return true if this "journal file" is currently stored in heap memory,
105876 ** a legal notice, here is a blessing:
105919 ** is invoked before visiting children.)
105932 ** The return value from this routine is WRC_Abort to abandon the tree walk
105975 ** an abort request is seen.
105989 ** This is a no-op callback for Walker->xSelectCallback2. If this
105990 ** callback is set, then the Select->pWinDefn list is traversed.
106063 ** If it is not NULL, the xSelectCallback() callback is invoked before
106065 ** method is invoked following the walk of the expressions and FROM clause,
106070 ** there is an abort request.
106073 ** is a no-op returning WRC_Continue.
106112 ** When this routine is the Walker.xExprCallback then expression trees
106114 ** when this routine is used for Walker.xExprCallback then
106115 ** Walker.xSelectCallback is set to do something useful for every
106138 ** a legal notice, here is a blessing:
106163 ** incrAggFunctionDepth(pExpr,n) is the main routine. incrAggDepth(..)
106164 ** is a helper function - a callback for the tree walker.
106186 ** If the reference is followed by a COLLATE operator, then make sure
106187 ** the COLLATE operator is preserved. For example:
106196 ** alias is removed from the original expression. The usual value is
106197 ** zero but it might be more if the alias is contained within a subquery
106206 int nSubquery /* Number of subqueries that the label is moving */
106247 ** NULL then those fields will match anything. Return true if there is a match,
106253 ** argument matches if zCol is a rowid alias. If it is not NULL, (*pbRowid)
106254 ** is set to 1 if there is this kind of match.
106307 ** The argument is guaranteed to be a non-NULL Expr node of type TK_COLUMN.
106336 ** in *ppList. Create a new *ppList if this is the first term in the
106357 ** Return TRUE (non-zero) if zTab is a valid name for the schema table pTab.
106362 Schema *pSchema /* non-NULL if a database qualifier is present */
106389 ** (even if X is implied).
106396 ** pExpr->pLeft Any expression this points to is deleted
106397 ** pExpr->pRight Any expression this points to is deleted.
106399 ** The zDb variable is the name of the database (the "X"). This value may be
106400 ** NULL meaning that name is of the form Y.Z or Z. Any available database
106401 ** can be used. The zTable variable is the name of the table (the "Y"). This
106402 ** value can be NULL if zDb is also NULL. If zTable is NULL it
106403 ** means that the form of the name is Z and that columns from any table
106462 /* This branch is taken when the main database has been renamed
106470 /* Start at the inner-most context and move outward until a match is found */
106484 /* In this case, pItem is a subquery that has been formed from a
106505 /* Two or more tables have the same column name which is
106506 ** not joined by USING. This is an error. Signal as much
106528 /* This is a potential rowid match, but there has already been
106571 /* Two or more tables have the same column name which is
106572 ** not joined by USING. This is an error. Signal as much
106619 ** it is a new.* or old.* trigger argument reference. Or
106620 ** maybe it is an excluded.* from an upsert. Or maybe it is
106726 ** Perhaps the name is a reference to the ROWID
106741 ** If the input is of the form Z (not Y.Z or X.Y.Z) then the name Z
106750 ** resolved by the time the WHERE clause is resolved.
106754 ** clause is not standard SQL. This is a (goofy) SQLite extension, that
106755 ** is supported for backwards compatibility only. Hence, we issue a warning
106756 ** on sqlite3_log() whenever the capability is used.
106810 ** If X and Y are NULL (in other words if only the column name Z is
106811 ** supplied) and the value of Z is enclosed in double-quotes, then
106812 ** Z is a string literal if it doesn't match any column names. In that
106829 ** I now sorely regret putting in this hack. The effect of this hack is
106834 ** Someday, I hope to get rid of this hack. Unfortunately there is
106856 ** cnt==0 is always an error. cnt>1 is often an error, but might
106908 /* If a column from a table in pSrcList is referenced, then record
106910 ** bit 0 to be set. Column 1 sets bit 1. And so forth. Bit 63 is
106911 ** set if the 63rd or any subsequent column is used.
106913 ** The colUsed mask is an optimization used to help determine if an
106914 ** index is a covering index. The correct answer is still obtained
106915 ** if the mask contains extra set bits. However, it is important to
106919 ** If a generated column is referenced, set bits for every column
106984 ** Report an error that an expression is not valid for some set of
106995 ** As an optimization, since the conditional is almost always false
106996 ** (because errors are rare), the conditional is moved outside of the
107024 ** Return 1024 times this value. Or return -1 if p is not a floating point
107038 ** This routine is callback for sqlite3WalkExpr().
107045 ** function names. The operator for aggregate functions is changed
107069 ** column in the FROM clause. This is used by the LIMIT and ORDER BY
107092 ** if we can prove that "expr" is never NULL. Call this the
107181 int is_agg = 0; /* True if is an aggregate function */
107213 /* EVIDENCE-OF: R-61304-29449 The unlikely(X) function is
107215 ** EVIDENCE-OF: R-01283-11636 The unlikely(X) function is
107217 ** EVIDENCE-OF: R-36850-34127 The likely(X) function is short-hand
107219 ** EVIDENCE-OF: R-53436-40973 The likely(X) function is equivalent
107221 /* TUNING: unlikely() probability is 0.0625. likely() is 0.9375 */
107265 ** SQL is being compiled using sqlite3NestedParse() or
107502 ** pEList is a list of expressions which are really the result set of the
107503 ** a SELECT statement. pE is a term in an ORDER BY or GROUP BY clause.
107504 ** This routine checks to see if pE is a simple identifier which corresponds
107505 ** to the AS-name of one of the terms of the expression list. If it is,
107506 ** this routine return an integer between 1 and N where N is the number of
107507 ** elements in pEList, corresponding to the matching entry. If there is
107508 ** no match, or if pE is not a simple identifier, then this routine
107538 ** pE is a pointer to an expression which is a single term in the
107542 ** At the point this routine is called, we already know that the
107543 ** ORDER BY term is not an integer index into the result set. That
107544 ** case is handled by the calling routine.
107549 ** The left-most column is 1. In other words, the value returned is the
107553 ** If there is no match, return 0. Return -1 if an error occurs.
107617 ** each term of the ORDER BY clause is a constant integer between 1
107618 ** and N where N is the number of columns in the compound SELECT.
107625 ** At the first match, the ORDER BY expression is transformed into
107675 ** by pSelect. In the usual case this is done by duplicating the
107679 ** is deleted.
107681 ** If this is running as part of an ALTER TABLE operation and
107735 ** the SELECT statement pSelect. If any term is reference to a
107804 ** pOrderBy is an ORDER BY or GROUP BY clause in SELECT statement pSelect.
107805 ** The Name context of the SELECT statement is pNC. zType is either
107806 ** "ORDER" or "GROUP" depending on which type of clause pOrderBy is.
107809 ** If the order-by term is an integer I between 1 and N (where N is the
107811 ** in the resolution is a copy of the I-th result-set expression. If
107812 ** the order-by term is an identifier that corresponds to the AS-name of
107814 ** result-set expression. Otherwise, the expression is resolved in
107843 /* If an AS-name match is found, mark this ORDER BY column as being
107852 /* The ORDER BY term is an integer constant. Again, set the column
107870 /* Since this expression is being changed into a reference
107887 int isCompound; /* True if p is a compound select */
107905 ** already expanded this SELECT. However, if this is a subquery within
107935 /* If the SF_Converted flags is set, then this Select object was
107966 ** is correlated. It is not required to check the refcount on any
108005 ** other expressions in the SELECT statement. This is so that
108009 ** Minor point: If this is the case, then the expression will be
108053 /* If this is a converted compound query, move the ORDER BY clause from
108065 ** The ORDER BY clause for compounds SELECT statements is handled
108069 ** If there is an ORDER BY clause on a term of a compound-select other
108070 ** than the right-most term, then that is a syntax error. But the error
108071 ** is not detected until much later, and so we need to go ahead and
108103 /* If this is part of a compound SELECT, check that it has the right
108143 ** The node at the root of the subtree is modified as follows:
108154 ** is replaced by a copy of the left-hand side of the result-set expression.
108160 ** The "x" term of the order by is replaced by "a+b" to render:
108164 ** Function calls are checked to make sure that the function is
108166 ** If the function is an aggregate function, then the NC_HasAgg flag is
108167 ** set and the opcode is changed from TK_FUNCTION to TK_AGG_FUNCTION.
108169 ** property on the expression is set.
108171 ** An error message is left in pParse if anything is amiss. The number
108172 ** if errors is returned.
108210 ** Resolve all names for all expression in an expression list. This is
108299 ** nodes of the expression is set to -1 and the Expr.iColumn value is
108345 ** a legal notice, here is a blessing:
108372 ** If pExpr is a column, a reference to a column via an 'AS' alias,
108374 ** affinity of that column is returned. Otherwise, 0x00 is returned,
108441 ** If the expression must return NULL, then 0x00 is returned.
108508 ** If a memory allocation error occurs, that fact is recorded in pParse->db
108509 ** and the pExpr parameter is returned unchanged.
108571 ** there is no defined collating sequence, return NULL.
108621 /* The Expr.x union is never used at the same time as Expr.pRight */
108646 ** there is no defined collating sequence, return a pointer to the
108652 ** returns NULL if there is no defined collation.
108671 ** pExpr is an operand of a comparison operator. aff2 is the
108687 /* One side is a column, the other is not. Use the columns affinity. */
108694 ** pExpr is a comparison operator. Return the type affinity that should
108715 ** pExpr is a comparison expression, eg. '=', '<', IN(...) etc.
108716 ** idx_affinity is the affinity of an indexed column. Return true
108749 ** If the left hand expression has a collating sequence type, then it is
108751 ** is used, or the default (BINARY) if neither expression has a collating
108755 ** it is not considered.
108777 /* Expression p is a comparison operator. Return a collation sequence
108780 ** This is normally just a wrapper around sqlite3BinaryCompareCollSeq().
108781 ** However, if the OP_Commuted flag is set, then the order of the operands
108782 ** is reversed in the sqlite3BinaryCompareCollSeq() call so that the
108783 ** correct collating sequence is found.
108803 int jumpIfNull, /* If true, jump if either operand is NULL */
108824 ** Return true if expression pExpr is a vector, or false otherwise.
108826 ** A vector is defined as any expression that results in two or more
108827 ** columns of result. Every TK_VECTOR node is an vector because the
108829 ** But a TK_SELECT might be either a vector or a scalar. It is only
108837 ** If the expression passed as the only argument is of type TK_VECTOR
108839 ** is a sub-select, return the number of columns in the sub-select. For
108857 ** Return a pointer to a subexpression of pVector that is the i-th
108859 ** ensure that i is within range.
108861 ** If pVector is really a scalar (and "scalar" here includes subqueries
108866 ** If the vector is a (SELECT ...) then the expression returned is
108891 ** It is ok for pVector to be a scalar (as long as iField==0).
108894 ** The caller owns the returned Expr object and is responsible for
108897 ** The caller retains ownership of pVector. If pVector is a TK_SELECT,
108899 ** valid for the life of the returned object. If pVector is a TK_VECTOR
108904 ** the returned Expr object is to attach the pVector to the pRight field
108923 ** if the result is not yet computed.
108926 ** pLeft on TK_SELECT_COLUMN nodes. But pRight is followed, so pVector
108957 ** If expression pExpr is of type TK_SELECT, generate code to evaluate
108958 ** it. Return the register in which the result is stored (or, if the
108960 ** of registers in which the result is stored).
108962 ** If pExpr is not a TK_SELECT expression, return 0.
108980 ** If pVector is a TK_SELECT expression, then code for it must have
108985 ** If pVector is of type TK_VECTOR, then code for the requested field
108986 ** is generated. In this case (*pRegFree) may be set to the number of
108989 ** Before returning, output parameter (*ppExpr) is set to point to the
109020 ** Expression pExpr is a comparison between two vector values. Compute
109121 ** Check that argument nHeight is less than or equal to the maximum
109122 ** expression depth allowed. If it is not, leave an error message in
109130 "Expression tree is too large (maximum depth %d)", mxHeight
109142 ** If this maximum height is greater than the current value pointed
109199 ** the height is greater than the maximum allowed expression depth,
109244 ** This routine is the core allocator for Expr nodes.
109247 ** for this node and for the pToken argument is a single allocation
109249 ** is responsible for making sure the node eventually gets freed.
109251 ** If dequote is true, then the token (if it exists) is dequoted.
109252 ** If dequote is false, no dequoting is performed. The deQuote
109253 ** parameter is ignored if pToken is NULL or if the token does not
109255 ** then the EP_DblQuoted flag is set on the expression node.
109258 ** can be translated into a 32-bit integer, then the token is not
109259 ** stored in u.zToken. Instead, the integer values is written
109260 ** into u.iValue and the EP_IntValue flag is set. No extra storage
109261 ** is allocated to hold the integer text and the dequote flag is ignored.
109391 ** Add pSelect to the Expr.x.pSelect field. Or, if pExpr is NULL (due
109406 ** Expression list pEList is a list of vector values. This function
109413 ** is translated to the equivalent of:
109418 ** If a list element that is not a vector or does not contain nElem terms,
109419 ** an error message is left in pParse.
109421 ** This is used as part of processing IN(...) expressions with a list
109464 ** Join two expressions using an AND operator. If either expression is
109467 ** If one side or the other of the AND is known to be false, and neither side
109468 ** is part of an ON clause, then instead of returning an AND expression,
109542 ** The ORDER BY clause is inserted into a new Expr node of type TK_ORDER
109547 Expr *pExpr, /* The function call to which ORDER BY is to be added */
109587 ** Check to see if a function is usable according to current access
109595 ** If the function is not usable, create an error.
109611 ** is tagged with SQLITE_FUNC_UNSAFE) and
109612 ** SQLITE_DBCONFIG_TRUSTED_SCHEMA is off (meaning
109613 ** that the schema is possibly tainted).
109628 ** sure "nnn" is not too big to avoid a denial of service attack when
109632 ** as the previous instance of the same wildcard. Or if this is the first
109633 ** instance of the wildcard, the next sequential variable number is
109722 /* The Expr.x union is never used at the same time as Expr.pRight */
109765 ** Arrange to cause pExpr to be deleted when the pParse is deleted.
109766 ** This is similar to sqlite3ExprDelete() except that the delete is
109767 ** deferred until the pParse is deleted.
109771 ** The deferred delete is (currently) implemented by adding the
109792 ** passed as the first argument. This is always one of EXPR_FULLSIZE,
109804 ** how much of the tree is measured.
109815 ** The return values is always one of:
109827 ** During expression analysis, extra information is computed and moved into
109829 ** off if the expression is reduced. Note also that it does not work to
109830 ** make an EXPRDUP_REDUCE copy of a reduced expression. It is only legal
109859 ** string is defined.)
109891 ** An EdupBuf is a memory allocation used to stored multiple Expr objects
109892 ** together with their Expr.zToken content. This is used to help implement
109907 ** This function is similar to sqlite3ExprDup(), except that if pEdupBuf
109908 ** is not NULL then it points to memory that can be used to store a copy
109910 ** is updated with the new buffer tail prior to returning.
109961 ** by pNew. This is either EXPR_FULLSIZE, EXPR_REDUCEDSIZE or
109962 ** EXPR_TOKENONLYSIZE. nToken is set to the number of bytes consumed
110057 ** argument. If an OOM condition is encountered, NULL is returned
110129 ** If the EXPRDUP_REDUCE flag is set, then the structure returned is a
110184 ** sqlite3SelectDup(), can be called. sqlite3SelectDup() is sometimes
110312 ** Add a new element to the end of an expression list. If pList is
110318 ** If a memory allocation error occurs, the entire list is freed and
110319 ** NULL is returned. If non-NULL is returned, then it is guaranteed
110383 ** pColumns and pExpr form a vector assignment which is part of the SET
110408 /* If the RHS is a vector, then we can immediately check to see that
110409 ** the size of the RHS and LHS match. But if the RHS is a SELECT,
110437 ** sqlite3ExprListDelete() is called */
110491 ** is set.
110526 ** is set.
110602 ** This is a SELECT-node callback for the expression walker that
110606 ** This callback is used by multiple expression walkers.
110615 ** Check the input string to see if it is "true" or "false" (in any case).
110617 ** If the string is.... Return
110630 ** If the input expression is an ID with the name "true" or "false"
110632 ** the conversion happened, and zero if the expression is unaltered.
110648 ** The argument must be a TK_TRUEFALSE Expr node. Return 1 if it is TRUE
110649 ** and 0 if it is FALSE.
110661 ** If pExpr is an AND or OR expression, try to simplify it by eliminating
110663 ** Or return the original expression if no simplification is possible.
110702 ** is found to not be a constant.
110704 ** The sqlite3ExprIsConstantOrFunction() is used for evaluating DEFAULT
110705 ** expressions in a CREATE TABLE statement. The Walker.eCode value is 5
110708 ** an error for new statements, but is silently converted
110716 /* If pWalker->eCode is 2 then any term of the expression that comes from
110800 ** Walk an expression tree. Return non-zero if the expression is constant
110804 ** is considered a variable but a single-quoted string (ex: 'abc') is
110814 ** (1) the expression is constant, and
110829 ** Walk an expression tree. Return non-zero if the expression is constant
110839 ** Check pExpr to see if it is an constraint on the single data source
110843 ** is a constraint on pSrc only.
110845 ** This is an optimization. False negatives will perhaps cause slower
110858 ** (4) If pSrc is the right operand of a LEFT JOIN, then...
110862 ** (5) If pSrc is not the right operand of a LEFT JOIN or the left
110870 ** (6b) The ON or USING clause from which pExpr is derived is
110918 /* Check if pExpr is identical to any GROUP BY term. If so, consider
110930 /* Check if pExpr is a sub-select. If so, consider it variable. */
110944 ** This routine is used to determine if a term of the HAVING clause can
110951 ** GROUP BY be BINARY is stricter than necessary. It would also work
110953 ** sequence as the GROUP BY term, but that is much harder to check,
110954 ** alternative collating sequences are uncommon, and this is only an
110971 ** in a CREATE TABLE statement. Return non-zero if the expression is
110972 ** acceptable for use as a DEFAULT. That is to say, return non-zero if
110973 ** the expression is constant or a function call with constant arguments.
110976 ** isInit is true when parsing from sqlite_schema. isInit is false when
110977 ** processing a new CREATE TABLE statement. When isInit is true, parameters
110979 ** isInit is false, parameters raise an error. Parameters should not be
110984 ** If isInit is true, set EP_FromDDL on every TK_FUNCTION node.
110987 ** is considered a variable but a single-quoted string (ex: 'abc') is
111014 ** If the expression p codes a constant integer that is small enough
111016 ** in *pValue. If the expression is not an integer or if it is too big
111023 /* If an expression is an integer literal that fits in a signed 32-bit
111052 ** Return FALSE if there is no chance that the expression can be NULL.
111054 ** If the expression might be NULL or if the expression is too complex
111057 ** This routine is used as an optimization, to skip OP_IsNull opcodes
111060 ** be a small performance hit but is otherwise harmless. On the other
111094 ** Return TRUE if the given expression is a constant which would be
111098 ** This routine is used to determine if the OP_Affinity operation
111100 ** is harmless. A false positive, however, can result in the wrong
111137 ** Return TRUE if the given string is a row-id column name.
111148 ** pTab. An alias is usable if there is not an explicit user-defined column
111168 ** pX is the RHS of an IN operator. If pX is a SELECT statement
111170 ** a pointer to the SELECT statement. If pX is not a SELECT statement,
111196 if( pSrc->a[0].pSelect ) return 0; /* FROM is not a subquery or view */
111199 assert( !IsView(pTab) ); /* FROM clause is not a view */
111234 ** The argument is an IN operator with a list (not a subquery) on the
111235 ** right-hand side. Return TRUE if that list is constant.
111250 ** This function is used by the implementation of the IN (...) operator.
111251 ** The pX parameter is the expression on the RHS of the IN operator, which
111254 ** The job of this routine is to find or create a b-tree object that can
111258 ** A cursor is opened on the b-tree object that is the RHS of the IN operator
111259 ** and the *piTab parameter is set to the index of that cursor.
111271 ** An existing b-tree might be used if the RHS expression pX is a simple
111276 ** If the RHS of the IN operator is a list or a more complex subquery, then
111282 ** the subroutine is coded.
111287 ** membership test. When the IN_INDEX_LOOP bit is set, the IN index will
111290 ** When IN_INDEX_LOOP is used (and the b-tree will be used to iterate
111293 ** to be unique - either because it is an INTEGER PRIMARY KEY or due to
111296 ** When IN_INDEX_MEMBERSHIP is used (and the b-tree will be used
111298 ** be used unless <columns> is a single INTEGER PRIMARY KEY column or an
111302 ** if the RHS of the IN operator is a list (not a subquery) then this
111304 ** testing is too expensive and return IN_INDEX_NOOP. In that case, the
111308 ** When the b-tree is being used for membership tests, the calling function
111310 ** contains a NULL. If prRhsHasNull is not a NULL pointer and
111311 ** if there is any chance that the (...) might contain a NULL value at
111312 ** runtime, then a register is allocated and the register number written
111313 ** to *prRhsHasNull. If there is no chance that the (...) contains a
111314 ** NULL value, then *prRhsHasNull is left unchanged.
111316 ** If a register is allocated and its location stored in *prRhsHasNull, then
111321 ** If the aiMap parameter is not NULL, it must point to an array containing
111323 ** of the IN(...) operator. The i'th entry of the array is populated with the
111330 ** then aiMap[] is populated with {2, 0, 1}.
111351 /* If the RHS of this IN(...) operator is a SELECT, and if it matters
111353 ** or not NULL is actually possible (it may not be, for example, due
111368 ** satisfy the query. This is preferable to generating a new
111405 ** comparison is the same as the affinity of each column in table
111406 ** on the RHS of the IN operator. If it not, it is not possible to
111420 ** other has no affinity and the other side is TEXT. Hence,
111421 ** the only way for cmpaff to be TEXT is for idxaff to be TEXT
111437 /* Maximum nColumn is BMS-2, not BMS-1, so that we can compute
111446 continue; /* This index is not unique over the IN RHS columns */
111474 /* If we reach this point, that means the index pIdx is usable */
111502 /* If no preexisting index is available for the IN clause
111503 ** and IN_INDEX_NOOP is an allowed reply
111504 ** and the RHS of the IN operator is a list, not a subquery
111505 ** and the RHS is not constant or has two or fewer terms,
111506 ** then it is not worth creating an ephemeral table to evaluate
111515 iTab = -1; /* Cursor is not allocated */
111551 ** Argument pExpr is an (?, ?...) IN(...) expression. This
111555 ** It is the responsibility of the caller to ensure that the returned
111556 ** string is eventually freed using sqlite3DbFree().
111599 ** Expression pExpr is a vector that has been used in a context where
111600 ** it is not permitted. If pExpr is a sub-select vector, this routine
111605 ** Or, if it is a regular scalar vector:
111629 ** The pExpr parameter is the IN operator. The cursor number for the
111630 ** constructed ephemeral table is returned. The first time the ephemeral
111631 ** table is computed, the cursor number is also stored in pExpr->iTable,
111635 ** If the LHS expression ("x" in the examples) is a column value, or
111637 ** column is used to build the index keys. If both 'x' and the
111638 ** SELECT... statement are columns, then numeric affinity is used
111641 ** is used.
111659 ** is encountered if any of the following is true:
111661 ** * The right-hand side is a correlated subquery
111662 ** * The right-hand side is an expression list containing variables
111669 /* Reuse of the RHS is allowed */
111699 /* Check to see if this is a vector IN operator */
111764 ** store it in the temporary table. If <expr> is a column, then use
111765 ** that columns affinity when building index keys. If <expr> is not
111790 /* If the expression is not constant then we will need to
111835 ** The pExpr parameter is the SELECT or EXISTS operator to be coded.
111838 ** the result is stored in a contiguous array of registers and the
111839 ** return value is the register of the left-most result column.
111882 ** is encountered if any of the following is true:
111884 ** * The right-hand side is a correlated subquery
111885 ** * The right-hand side is an expression list containing variables
111899 ** If this is an EXISTS, write an integer 0 (not exists) or 1 (exists)
111902 ** In both cases, the query is augmented with "LIMIT 1". Any
111903 ** preexisting limit is discarded in place of the new LIMIT 1.
111923 /* The subquery already has a limit. If the pre-existing limit is X
111924 ** then make the new limit X<>0 so that the new limit is either 1 or 0 */
111935 /* If there is no pre-existing limit add a limit of 1 */
111966 ** Expr pIn is an IN(...) expression. This function checks that the
111968 ** columns as the vector on the LHS. Or, if the RHS of the IN() is not
111969 ** a sub-query, that the LHS is a vector of size 1.
111993 ** The left-hand side (LHS) is a scalar or vector expression. The
111994 ** right-hand side (RHS) is an array of zero or more scalar values, or a
111995 ** subquery. If the RHS is a subquery, the number of result columns must
111996 ** match the number of columns in the vector on the LHS. If the RHS is
111999 ** The IN operator is true if the LHS value is contained within the RHS.
112000 ** The result is false if the LHS is definitely not in the RHS. The
112001 ** result is NULL if the presence of the LHS in the RHS cannot be
112004 ** This routine generates code that jumps to destIfFalse if the LHS is not
112006 ** is contained in the RHS then jump to destIfNull. If the LHS is contained
112015 int destIfFalse, /* Jump here if LHS is not contained in the RHS */
112018 int rRhsHasNull = 0; /* Register that is true if RHS contains NULL values */
112031 int addrTruthOp; /* Address of opcode that determines the IN is true */
112032 int destNotNull; /* Jump here if a comparison is not true in step 6 */
112048 ** IN_INDEX_NOOP is returned, the table opened with cursor iTab
112049 ** contains the values that make up the RHS. If IN_INDEX_NOOP is returned,
112072 /* Code the LHS, the <expr> from "<expr> IN (...)". If the LHS is a
112073 ** vector, then it is stored in an array of nVector registers starting
112082 ** even if it is constant, as OP_Affinity may be used on the register
112100 /* If sqlite3FindInIndex() did not find or create an index that is
112104 ** This is step (1) in the in-operator.md optimized algorithm.
112172 /* Step 3. The LHS is now known to be non-NULL. Do the binary search
112173 ** of the RHS using the LHS as a probe. If found, the result is
112177 /* In this case, the RHS is the ROWID of table b-tree and so we also
112178 ** know that the RHS is non-NULL. Hence, we combine steps 3 and 4
112196 /* Step 4. If the RHS is known to be non-NULL and we did not find
112210 ** If any comparison is NULL, then the result is NULL. If all
112211 ** comparisons are FALSE then the final result is FALSE.
112213 ** For a scalar LHS, it is sufficient to check just the first row
112223 ** FALSE if the first comparison is not NULL */
112267 ** z[n] character is guaranteed to be something that does not look
112286 ** Expr.u.zToken is always UTF8 and zero-terminated.
112323 /* Generate code that will load into register regOut a value that is
112328 Index *pIdx, /* The index whose column is to be loaded */
112434 ** is called. If iColumn<0 then code is generated that extracts the rowid.
112483 ** If the returned result register is a temporary scalar, then also write
112485 ** is not a temporary or if the expression is a vector set *piFreeable
112515 ** If the last opcode is a OP_Copy, then set the do-not-merge flag (p5)
112578 /* The UNLIKELY() function is a no-op. The result is the value
112626 ** the type affinity of the argument. This is used for testing of
112646 ** Check to see if pExpr is one of the indexed expressions on pParse->pIdxEpr.
112647 ** If it is, then resolve the expression by reading from the index and
112648 ** return the register into which the value has been read. If pExpr is
112680 /* If the index is on a NULL row due to an outer join, then we
112705 ** Expresion pExpr is guaranteed to be a TK_COLUMN or equivalent. This
112711 ** Or, if the TK_COLUMN cannot be replaced by a constant, zero is
112744 ** With this routine, there is no guarantee that results will
112746 ** register if it is convenient to do so. The calling function
112783 /* Happens when the left table of a RIGHT JOIN is null and
112784 ** is using an expression index */
112787 /* Verify that the OP_Null above is exercised by tests
112815 ** is rewritten by aggregateConvertIndexedExprRefToColumn() */
112826 /* This COLUMN expression is really a constant due to WHERE clause
112827 ** constraints, and that constant is coded by the pExpr->pLeft
112850 ** The row is unpacked into registers beginning at
112851 ** 0-(pParse->iSelfTab). The rowid (if any) is in a register
112892 /* Coding an expression that is part of an index where column names
113212 /* Possibly overload the function if the first argument is
113217 ** see if it is a column in a virtual table. This is done because
113220 ** function. The expression "A glob B" is equivalent to
113295 ** This is equivalent to
113299 ** X is stored in pExpr->pLeft.
113300 ** Y is stored in pExpr->pList->a[0].pExpr.
113301 ** Z is stored in pExpr->pList->a[1].pExpr.
113309 /* A TK_COLLATE Expr node without the EP_Collate tag is a so-called
113310 ** "SOFT-COLLATE" that is added to constraints that are pushed down
113330 /* If the opcode is TK_TRIGGER, then the expression is a reference
113332 ** trigger programs. In this case Expr.iTable is set to 1 for the
113334 ** is set to the column of the pseudo-table to read, or to -1 to
113337 ** The expression is implemented using an OP_Param opcode. The p1
113338 ** parameter is set to 0 for an old.rowid reference, or to (i+1)
113340 ** i is the index of the column. For a new.rowid reference, p1 is
113341 ** set to (n+1), where n is the number of columns in each pseudo-table.
113343 ** is set to (n+2+i), where n and i are as defined previously. For
113344 ** example, if the table on which triggers are being fired is
113349 ** Then p1 is interpreted as follows:
113378 ** integer. Use OP_RealAffinity to make sure it is really real.
113396 ** Expr.iTable value is the table number for the right-hand table.
113397 ** The expression is only evaluated if that table is not currently
113420 ** NULL. So we have to ensure that the result register is not a value
113421 ** that is suppose to be a constant. Two defenses are needed:
113423 ** (2) Make sure the computed value really is stored in register
113441 ** Form A is can be transformed into the equivalent form B as follows:
113445 ** X (if it exists) is in pExpr->pLeft.
113446 ** Y is in the last element of pExpr->x.pList if pExpr->x.pList->nExpr is
113447 ** odd. The Y is also optional. If the number of elements in x.pList
113448 ** is even, then Y is omitted and the "otherwise" result is NULL.
113449 ** Ei is in pExpr->pList->a[i*2] and Ri is pExpr->pList->a[i*2+1].
113451 ** The result of the expression is the Ri for the first matching Ei,
113452 ** or if there is no matching Ei, the ELSE term Y, or if there is
113489 ** So make sure that the regFree1 register is not reused for other
113558 ** guard them with an OP_Once opcode to ensure that the code is only executed
113562 ** If regDest>0 then the result is always stored in that register and the
113563 ** result is not reusable. If regDest<0 then this routine is free to
113565 ** is stored is returned. When regDest<0, two identical expressions might
113622 ** If the register is a temporary register that can be deallocated,
113623 ** then write its number into *pReg. If the result register is not
113626 ** If pExpr is a constant, then this routine might generate this
113684 ** except that the input expression is guaranteed to be unchanged.
113696 ** in register target. If the expression is constant, then this routine
113713 ** is defined.
113724 ** If SQLITE_ECEL_OMITREF is also set, then the values with u.x.iOrderByCol>0
113787 ** The above is equivalent to
113800 ** The jumpIfNull parameter is ignored if xJumpIf is NULL.
113807 int jumpIfNull /* Take the jump if the BETWEEN is NULL */
113836 /* Mark the expression is being from the ON or USING clause of a join
113861 ** Generate code for a boolean expression such that a jump is made
113862 ** to the label "dest" if the expression is true but execution
113863 ** continues straight thru if the expression is false.
113866 ** take the jump if the jumpIfNull flag is SQLITE_JUMPIFNULL.
114009 ** Generate code for a boolean expression such that a jump is made
114010 ** to the label "dest" if the expression is false but execution
114011 ** continues straight thru if the expression is true.
114014 ** jump if jumpIfNull is SQLITE_JUMPIFNULL or fall through if jumpIfNull
114015 ** is 0.
114042 ** For other values of pExpr->op, op is undefined and unused.
114045 ** Assert()s verify that the computation is correct.
114186 ** Like sqlite3ExprIfFalse() except that a copy is made of pExpr before
114187 ** code generation, and that copy is deleted after code generation. This
114188 ** ensures that the original pExpr is unchanged.
114200 ** Expression pVar is guaranteed to be an SQL variable. pExpr may be any
114203 ** If pExpr is a simple SQL value - an integer, real, string, blob
114204 ** or NULL value - then the VDBE currently being prepared is configured
114205 ** to re-prepare each time a new value is bound to variable pVar.
114207 ** Additionally, if pExpr is a simple SQL value and the value is the
114208 ** same as that currently bound to variable pVar, non-zero is returned.
114209 ** Otherwise, if the values are not the same or if pExpr is not a simple
114210 ** SQL value, zero is returned.
114228 sqlite3_value_text(pL); /* Make sure the encoding is UTF-8 */
114245 ** If any subelement of pB has Expr.iTable==(-1) then it is allowed
114248 ** The pA side might be using TK_REGISTER. If that is the case and pB is
114249 ** not using TK_REGISTER but is otherwise equivalent, then still return 0.
114257 ** this routine is used, it does not hurt to get an extra 2 - that
114261 ** If pParse is not NULL then TK_VARIABLE terms in pA with bindings in
114263 ** pParse->pVdbe->expmask bitmask is updated for each variable referenced.
114264 ** If pParse is NULL (the normal case) then any TK_VARIABLE term in
114265 ** Argument pParse should normally be NULL. If it is not NULL and pA or
114356 ** if they are certainly different, or 2 if it is not possible to
114359 ** If any subelement of pB has Expr.iTable==(-1) then it is allowed
114397 ** Return non-zero if Expr p can only be true if pNN is not NULL.
114399 ** Or if seenNot is true, return non-zero if Expr p can only be
114400 ** non-NULL if pNN is not NULL
114405 const Expr *pNN, /* The expression that is NOT NULL */
114475 ** Return true if we can prove the pE2 will always be true if pE1 is
114490 ** If pParse is not NULL, then the values of bound variables in pE1 are
114491 ** compared against literal values in pE2 and pParse->pVdbe->expmask is
114493 ** is NULL, then false will be returned if pE1 contains any bound variables.
114497 ** it will always give the correct answer and is hence always safe.
114522 /* This is a helper function to impliesNotNullRow(). In this routine,
114537 ** This is the Expr node callback for sqlite3ExprImpliesNonNullRow().
114541 ** pWalker->mWFlags is non-zero if this inquiry is being undertaking on
114547 ** (never setting pWalker->eCode) is a harmless missed optimization.
114554 /* If iCur is used in an inner-join ON clause to the left of a
114556 ** But it is difficult to check for that condition precisely.
114557 ** To keep things simple, any use of iCur from any inner-join is
114593 ** If only one of x or y is non-null-row, then the overall expression
114594 ** can be true if the other arm is false (case 1) or true (case 2).
114604 ** the left-hand side of the IN is NULL then the IN itself will be
114622 ** a term of the form x=y does not prove that y is not null if x
114623 ** is the column of a virtual table */
114660 ** one column of table iTab is non-null. In other words, return true
114662 ** is NULL.
114664 ** False negatives are acceptable. In other words, it is ok to return
114666 ** is NULL. A false negative is merely a missed optimization opportunity.
114674 ** This routine is used to check if a LEFT JOIN can be converted into
114675 ** an ordinary JOIN. The p argument is the WHERE clause. If the WHERE
114703 ** An instance of the following structure is used by the tree walker
114706 ** table entry. The IdxCover.pIdx field is the index. IdxCover.iCur
114707 ** is the cursor for the table.
114804 /* This is the Walker EXPR callback for sqlite3ReferencesSrcList().
114806 ** Set the 0x01 bit of pWalker->eCode if there is a reference to any
114809 ** Set the 0x02 bit of pWalker->eCode if there is a reference to a
114810 ** table is in neither RefSrcList.pRef nor RefSrcList.aiExclude.
114840 ** 0 pExpr references some table that is not defined in either
114846 ** As currently used, pExpr is always an aggregate function call. That
114847 ** fact is exploited for efficiency.
114886 ** This is a Walker expression node callback.
114889 ** object that is referenced does not refer directly to the Expr. If
114890 ** it does, make a copy. This is done because the pExpr argument is
114893 ** The copy is scheduled for deletion using the sqlite3ExprDeferredDelete()
114933 ** by the tree that is walked.
114978 ** If no prior entry is found, create a new one and return -1. The
115043 ** This is the xExprCallback for a tree walker. It is used to
115100 /* Check to see if the column is in one of the tables in the FROM
115119 /* Check to see if pExpr is a duplicate of another aggregate
115120 ** function that is already in the pAggInfo structure
115130 /* pExpr is original. Make a new entry in pAggInfo->aFunc[]
115219 ** If an error is found, the analysis is cut short.
115298 ** iReg is a valid register number.
115307 ** The value returned is no less than iMin. If any register iMin or
115308 ** greater is in permanent use, then return one more than that last
115329 ** iFirst..iLast, inclusive. This routine is only call from within assert()
115364 ** a legal notice, here is a blessing:
115383 ** Parameter zName is the name of a table that is about to be altered
115385 ** If the table is a system table, this function leaves an error message
115388 ** Or, if zName is not a system table, zero is returned.
115407 ** bTemp is not true, database "temp", can still be parsed. This is
115415 int bTemp, /* True if this is the temp db */
115445 ** database zDb with their single-quoted equivalents. If argument bTemp is
115496 VTable *pVTab = 0; /* Non-zero if this is a v-tab with an xRename() */
115512 ** in database iDb. If so, this is an error.
115519 "there is already another table or index with this name: %s", zName);
115523 /* Make sure it is not a system table being altered, or a reserved name
115524 ** that the table is being renamed to.
115612 /* If the table being renamed is not itself part of the temp database,
115627 /* If this is a virtual table, invoke the xRename() function if
115628 ** one is defined. The xRename() callback will modify the names
115650 ** zDb and zTab is not empty.
115665 ** This function is called after an "ALTER TABLE ... ADD" statement
115709 /* Check that the new column is not specified as PRIMARY KEY or UNIQUE.
115710 ** If there is a NOT NULL constraint, then the default value for the
115742 /* Ensure the default expression is something that sqlite3ValueFromExpr()
115772 /* substr() operations on characters, but addColOffset is in bytes. So we
115789 /* Make sure the schema version is at least 3. But do not upgrade
115828 ** This function is called by the parser after the table-name in
115829 ** an "ALTER TABLE <table-name> ADD" statement is parsed. Argument
115830 ** pSrc is the full-name of the table being altered.
115835 ** is parsed (i.e. sqlite3AddColumn()) add the new Column data to
115836 ** the copy. The copy of the Table structure is deleted by tokenize.c
115837 ** after parsing is finished.
115864 /* Make sure this is not an attempt to ALTER a view. */
115917 ** Parameter pTab is the subject of an ALTER TABLE ... RENAME COLUMN
115918 ** command. This function checks if the table is a view or virtual
115922 ** Or, if pTab is not a view or virtual table, zero is returned.
115990 /* Make sure the old name really is a column name in the table to be
116052 ** Each new object is created by sqlite3RenameTokenMap().
116053 ** As the parse tree is transformed, the sqlite3RenameTokenRemap()
116054 ** routine is used to keep the mapping current.
116063 RenameToken *pNext; /* Next is a list of all RenameToken objects */
116081 ** This function is only for debugging. It performs two tasks:
116088 ** The second is most effective when debugging under valgrind or
116090 ** point to valid objects, an exception is raised by the memory-checking
116093 ** The point of this is to prevent comparisons of invalid pointer values.
116094 ** Even though this always seems to work, it is undefined according to the
116130 ** The pPtr argument is returned so that this routine can be used
116156 ** It is assumed that there is already a RenameToken object associated
116253 if( ALWAYS(p->pSrc) ){ /* Every Select as a SrcList, even if it is empty */
116321 ** If the second argument passed to this function is not NULL and a matching
116322 ** RenameToken object is found, remove it from the Parse object and add it to
116350 ** This is a Walker select callback. It does nothing. It is only required
116365 ** This is a Walker expression callback.
116368 ** if the column being references is the column being renamed by an
116369 ** ALTER TABLE statement. If it is, then attach its associated
116392 ** is being renamed by an ALTER TABLE statement. Return the "last"
116395 ** the input SQL is parsed from left to right. Repeated calls to this routine
116417 ** sub-routine is currently stored in pParse->zErrMsg. This function
116490 ** is initialized by this function before it is used.
116497 int bTemp /* True if SQL is from temp schema */
116538 ** by the linked list pRename with the text of zNew. If argument bQuote is
116539 ** true, then zNew is always quoted first. If no error occurs, the result
116540 ** is loaded into context object pCtx as the result.
116542 ** Or, if an error occurs (i.e. an OOM condition), an error is left in
116588 ** All that remains is to construct and return the edited SQL string. */
116612 ** token. This is so that (SELECT "string"'alias') maps to
116711 ** ENAME_NAME). This is to prevent any ids in ON() clauses that are
116841 ** The iCol-th column (left-most is 0) of table zTable is renamed from zCol
116842 ** into zNew. The name should be quoted if bQuote is true.
116844 ** This function is used internally by the ALTER TABLE RENAME COLUMN command.
116845 ** It is only accessible to SQL created using sqlite3NestedParse(). It is
116847 ** SQLITE_TESTCTRL_INTERNAL_FUNCTIONS test setting is enabled.
117056 ** This C function implements an SQL user function that is used by SQL code
117059 ** parent table. It is passed three arguments:
117148 /* If this is the table being altered, fix any table refs in CHECK
117243 ** The returned value is the modified SQL statement. For example, given
117256 ** If there is a error in the input SQL, then raise an error, except
117353 ** After an ALTER TABLE .. RENAME operation is performed and the schema
117354 ** reloaded, this function is called on each SQL statement in the schema
117355 ** to ensure that it is still usable.
117361 ** 4: True if object is from temp schema.
117365 ** The return value is computed as follows:
117367 ** A. If an error is seen and not in PRAGMA writable_schema=ON mode,
117369 ** B. Else if a trigger is created and the the table that the trigger is
117370 ** attached to is in database zDb, then return 1.
117445 ** The value returned is a string containing the CREATE TABLE statement
117475 /* This can happen if the sqlite_schema table is corrupt */
117506 ** This function is called by the parser upon parsing an
117528 /* Make sure this is not an attempt to ALTER a view, virtual table or
117673 ** a legal notice, here is a blessing:
117694 ** The sqlite_stat2 table is not created or used unless the SQLite version
117695 ** is between 3.6.18 and 3.7.8, inclusive, and unless SQLite is compiled
117696 ** with SQLITE_ENABLE_STAT2. The sqlite_stat2 table is deprecated.
117697 ** The sqlite_stat2 table is superseded by sqlite_stat3, which is only
117700 ** is a superset of sqlite_stat2 and is also now deprecated. The
117701 ** sqlite_stat4 is an enhanced version of sqlite_stat3 and is only
117703 ** versions 3.8.1 and later. STAT4 is the only variant that is still
117711 ** There is normally one row per index, with the index identified by the
117712 ** name in the idx column. The tbl column is the name of the table to
117715 ** list is the number of rows in the index. (This is the same as the
117717 ** integer is the average number of rows in the index that have the same
117718 ** value in the first column of the index. The third integer is the average
117720 ** columns. The N-th integer (for N>1) is the average number of rows in
117723 ** the index is unique, then the last integer will be 1.
117726 ** by the keyword "unordered". The "unordered" keyword, if it is present,
117728 ** "unordered" keyword is present, then the query planner assumes that
117729 ** the index is unordered and will not use the index for a range query.
117731 ** If the sqlite_stat1.idx column is NULL, then the sqlite_stat1.stat
117732 ** column contains a single integer which is the (estimated) number of
117737 ** The sqlite_stat2 is only created and is only used if SQLite is compiled
117738 ** with SQLITE_ENABLE_STAT2 and if the SQLite version number is between
117740 ** about the distribution of keys within an index. The index is identified by
117741 ** the "idx" column and the "tbl" column is the name of the table to which
117753 ** For i between 0 and S-1. Conceptually, the index space is divided into
117756 ** The format for sqlite_stat2 is recorded here for legacy reference. This
117763 ** The sqlite_stat3 format is a subset of sqlite_stat4. Hence, the
117775 ** The idx column names the index and the tbl column is the table of the
117776 ** index. If the idx and tbl columns are the same, then the sample is
117777 ** of the INTEGER PRIMARY KEY. The sample column is a blob which is the
117778 ** binary encoding of a key from the index. The nEq column is a
117779 ** list of integers. The first integer is the approximate number
117782 ** is the approximate number of entries in the index where the
117784 ** And so forth. nLt is another list of integers that show the approximate
117787 ** left-most column is less than the left-most column of the sample.
117788 ** The K-th integer in the nLt entry is the number of index entries
117790 ** sample. The nDLt column is like nLt except that it contains the
117802 ** The sqlite_stat3 table is like sqlite_stat4 except that it only
117805 ** of a blob encoding of the complete index key as is found in
117807 ** all contain just a single integer which is the same as the first
117823 ** The sqlite_stat1 table is always relevant. sqlite_stat2 is now
117827 ** If the sqlite_statN tables do not previously exist, it is created.
117830 ** or it may be a NULL pointer. If it is not NULL, then all entries in
117832 ** If zWhere==0, then code is generated to delete all stat table entries.
117880 ** side-effect of the CREATE TABLE statement is to leave the rootpage
117881 ** of the new table in register pParse->regRoot. This is important
117890 /* The table already exists. If zWhere is not NULL, delete all entries
117891 ** associated with the table zWhere. If zWhere is NULL, delete the
118055 ** WITHOUT ROWID table, N is the number of PRIMARY KEY columns, not the
118059 ** WITHOUT ROWID tables, N=K+P where P is the number of columns in the
118064 ** value is a pointer to the StatAccum object. The datatype of the
118065 ** return value is BLOB, but it is really just a pointer to the StatAccum
118080 /* Maximum number of samples. 0 if STAT4 data is not collected */
118150 ** (given by the 3rd parameter) is never used and can be any positive
118171 ** function returns true if sample pNew is to be preferred over pOld.
118173 ** column for pNew and pOld are equal, is pNew to be preferred over pOld.
118197 ** Return true if pNew is to be preferred over pOld.
118231 /* StatAccum.nMaxEqZero is set to the maximum number of leading 0
118233 ** other words, if nMaxEqZero is n, then it is guaranteed that there
118242 /* This sample is being added because the prefix that ends in column
118244 ** added a sample that shares this prefix, there is no need to add
118359 ** The purpose of this routine is to collect statistical data and/or
118367 ** The R parameter is only used for STAT4
118386 /* This is the first call to this function. Do initialization. */
118425 /* Check if this is to be a periodic sample. If so, add it. */
118467 ** Implementation of the stat_get(P,J) SQL function. This routine is
118470 ** has type BLOB but it is really just a pointer to the StatAccum object.
118471 ** The content to returned is determined by the parameter J
118472 ** which is one of the STAT_GET_xxxx values defined above.
118474 ** The stat_get(P,J) function is not available to generic SQL. It is
118476 ** the callStatGet() routine below.) It is guaranteed that the P
118480 ** If STAT4 is not enabled, then J is always
118481 ** STAT_GET_STAT1 and is hence omitted and this routine becomes
118508 ** The value is a string composed of a list of integers describing
118509 ** the index. The first integer in the list is the total number of
118510 ** entries in the index. There is one additional integer in the list
118511 ** for each indexed column. This additional integer is an estimate of
118514 ** if the index is on columns (a,b) and the sqlite_stat1 value is
118521 ** If D is the count of distinct values and K is the total number of
118522 ** rows, then each estimate is usually computed as:
118526 ** In other words, I is K/D rounded up to the next whole integer.
118527 ** However, if I is between 1.0 and 1.1 (in other words if I is
118616 /* Add a comment to the most recent VDBE opcode that is the name
118621 Index *pIdx, /* Index whose column is being loaded */
118658 int jZeroRows = -1; /* Jump from here if number of rows is zero */
118717 ** to use for scanning indexes (iIdxCur). No index cursor is opened at
118782 ** the regPrev array and a trailing rowid (the rowid slot is required
118977 ** really is needed.
119036 ** be loaded into internal hash tables where is can be used.
119077 ** a database. If pOnlyIdx is not NULL then it is a single index
119235 ** from a full equality match is so large that a full table scan
119247 ** This callback is invoked once for each index when reading the
119317 ** If the Index.aSample variable is not NULL, delete the aSample[] array
119354 /* If this is stat4 data, then calculate aAvgEq[] values for all
119355 ** sample columns except the last. The last is always set to 1, as
119404 ** is supplied instead, find the PRIMARY KEY index for that table.
119429 ** where %Q is replaced with the database name before the SQL is executed.
119524 /* This next condition is true if data has already been loaded from
119537 ** This is in case the sample record is corrupted. In that case, the
119539 ** end of the allocated buffer before it realizes it is dealing with
119588 ** If the sqlite_stat1 table is not present in the database, SQLITE_ERROR
119589 ** is returned. In this case, even if SQLITE_ENABLE_STAT4 was defined
119590 ** during compilation and the sqlite_stat4 table is present, no data is
119594 ** sqlite_stat4 table is not present in the database, SQLITE_ERROR is
119595 ** returned. However, in this case, data is read from the sqlite_stat1
119596 ** table (if it is present) before returning.
119680 ** a legal notice, here is a blessing:
119694 ** is slightly different from resolving a normal SQL expression, because simple
119742 ** If the optional "KEY z" syntax is omitted, an SQL NULL is passed as the
119745 ** If the db->init.reopenMemdb flags is set, then instead of attaching a
119780 /* This is not a real ATTACH. Instead, this routine is being called
119804 /* This is a real ATTACH
119821 zErrDyn = sqlite3MPrintf(db, "database %s is already in use", zName);
119841 /* Open the database file. If the btree is successfully opened, use
119862 zErrDyn = sqlite3MPrintf(db, "database is already attached");
119987 sqlite3_snprintf(sizeof(zErr),zErr, "database %s is locked", zName);
120197 int iDb, /* This is the database that must be used */
120227 ** allowed to refer to anything.) If a reference is explicitly made
120228 ** to an object in a different database, an error message is added to
120300 ** a legal notice, here is a blessing:
120308 ** API. This facility is an optional feature of the library. Embedded
120323 ** The access authorization function is be called during the compilation
120326 ** is a copy of the 3rd argument to this routine. The second argument
120327 ** to the auth function is one of these constants:
120356 ** SQLITE_OK is returned, it means that access is allowed. SQLITE_DENY
120363 ** setting of the auth function is NULL.
120393 ** callback has been registered (i.e. that sqlite3.xAuth is not NULL).
120395 ** If SQLITE_IGNORE is returned and pExpr is not NULL, then pExpr is changed
120396 ** to an SQL NULL expression. Otherwise, if pExpr is NULL, then SQLITE_IGNORE
120397 ** is treated as SQLITE_DENY. In this case an error is left in pParse.
120418 sqlite3ErrorMsg(pParse, "access to %z is prohibited", z);
120428 ** is in pTabList or else it is the NEW or OLD table of a trigger.
120429 ** Check to see if it is OK to read this particular column.
120489 ** is returned, then the error count and error message in pParse are
120502 /* Don't do any authorization checks if the database is initializing
120503 ** or if the parser is being invoked from within sqlite3_declare_vtab.
120537 ** Push an authorization context. After this routine is called, the
120539 ** popped. Or if pParse==0, this routine is a no-op.
120571 ** a legal notice, here is a blessing:
120595 ** The TableLock structure is only used by the sqlite3TableLock() and
120608 ** The table to be locked has root page iTab and is found in database iDb.
120611 ** This routine just records the fact that the lock is desired. The
120612 ** code to make the lock occur is generated by a later call to
120684 ** Return TRUE if the given yDbMask object is empty - if it contains no
120685 ** 1 bits. This routine is used by the DbMaskAllZero() and DbMaskNotZero()
120686 ** macros when SQLITE_MAX_ATTACHED is greater than 30.
120697 ** This routine is called after a single SQL statement has been
120770 ** (Bit 0 is for main, bit 1 is for temp, and so forth.) Bits are
120771 ** set for each database that is used. Generate code to start a
120805 ** obtain the required table-locks. This is a no-op unless the
120806 ** shared-cache feature is enabled.
120842 /* A minimum of one cursor is required if autoincrement is used
120857 ** * The final OP_Halt is not appended and other initialization
120862 ** SQL functions. In other words, it is not possible to override a
120899 ** Return TRUE if zTable is the name of the system table that stores the
120912 ** If zDatabase is 0, all databases are searched for the table and the
120913 ** first matching table is returned. (No checking for duplicate table
120914 ** names is done.) The search order is TEMP first, then MAIN, then any
120926 /* Only the admin user is allowed to know that the sqlite_user table
120966 /* The main database is second */
120993 ** The difference between this routine and sqlite3FindTable() is that this
121017 /* If zName is the not the name of a table in the schema created using
121018 ** CREATE, then check to see if it is the name of an virtual table that
121054 ** This is a wrapper around sqlite3LocateTable(). The difference between
121055 ** sqlite3LocateTable() and this function is that this function restricts
121056 ** the search to schema (p->pSchema) if it is not NULL. p->pSchema may be
121057 ** non-NULL if it is part of a view or trigger program definition. See
121098 ** If zDatabase is 0, all databases are searched for the
121099 ** table and the first matching index is returned. (No checking
121100 ** for duplicate index names is done.) The search order is
121139 ** For the index called zIdxName which is found in the database iDb,
121201 ** TEMP schema. The reset is deferred if db->nSchemaLock is not zero.
121250 ** This routine is called when a commit occurs.
121257 ** Set the expression associated with a column. This is usually
121371 ** The db parameter is optional. It is needed if the Table object
121387 ** that no lookaside memory is used in this case either. */
121469 ** is obtained from sqliteMalloc() and must be freed by the calling
121477 ** is \000 terminated and is persistent.
121492 ** writing. The table is opened using cursor 0.
121515 /* "main" is always an acceptable alias for the primary database
121538 /* The table or view or trigger name is passed to this routine via tokens
121543 ** Then pName1 is set to "xxx" and pName2 "yyy". On the other hand if
121544 ** the table name is not fully qualified, i.e.:
121548 ** Then pName1 is set to "yyy" and pName2 is "".
121552 ** database "xxx" is returned.
121585 ** True if PRAGMA writable_schema is ON
121599 ** This routine is used to check if the UTF-8 string zName is a legal
121603 ** is reserved for internal use.
121654 ** Convert an table column number into a index column number. That is,
121657 ** if column iCol is not used in index pIdx.
121670 ** The storage column number (0,1,2,....) is the index of the value
121672 ** is the index (0,1,2,...) of the column in the CREATE TABLE statement.
121674 ** The storage column number is less than the table column number if
121677 ** If SQLITE_OMIT_GENERATED_COLUMNS, this routine is a no-op macro.
121693 ** The storage column number (0,1,2,....) is the index of the value
121694 ** as it appears in the record on disk. Or, if the input column is
121695 ** the N-th virtual column (zero-based) then the storage number is
121698 ** The true column number is the index (0,1,2,...) of the column in
121701 ** If the input column is a VIRTUAL column, then it should not appear
121702 ** in storage. But the value sometimes is cached in registers that
121706 ** input column is a VIRTUAL table, put it after all the other columns.
121714 ** Then the mapping from this function is as follows:
121723 ** this routine is a no-op macro. If the pTab does not have any virtual
121724 ** columns, then this routine is no-op that always return iCol. If iCol
121725 ** is negative (indicating the ROWID column) then this routine return iCol.
121736 /* iCol is a virtual column itself */
121739 /* iCol is a normal or stored column */
121748 ** is used by CREATE TABLE IF NOT EXISTS and similar if the table already
121751 ** is a read-only no-op.
121763 ** Begin constructing a new table representation in memory. This is
121765 ** to a CREATE TABLE statement. In particular, this routine is called
121767 ** flag is true if the table should be stored in the auxiliary database
121768 ** file instead of in the main database file. This is normally the case
121772 ** The new table record is initialized and put in pParse->pNewTable.
121773 ** As more of the CREATE TABLE statement is parsed, additional action
121776 ** is called to complete the construction of the new table record.
121782 int isTemp, /* True if this is a TEMP table */
121783 int isView, /* True if this is a VIEW */
121784 int isVirtual, /* True if this is a VIRTUAL table */
121805 ** the database name is "temp" anyway. */
121844 ** it does. The exception is if the statement being parsed was passed
121846 ** and types will be used, so there is no need to test for namespace
121867 sqlite3ErrorMsg(pParse, "there is already an index named %s", zName);
121903 /* nullRow[] is an OP_Record encoding of a row containing 5 NULLs */
121932 ** The rowid for the new entry is left in register pParse->regRowid.
121933 ** The root page number of the new table is left in reg pParse->regRoot.
121996 ** statement with a result set that is the argument of the RETURNING clause.
121999 ** knows to handle it specially. The TEMP trigger is automatically
122002 ** When this routine is called, we do not yet know if the RETURNING clause
122003 ** is attached to a DELETE, INSERT, or UPDATE, so construct it as a
122054 ** first to get things going. Then this routine is called for each
122139 /* If there is no type specified, columns have the default affinity
122165 ** This routine is called by the parser while in the middle of
122197 ** substrings in the following table. If one of the substrings is
122198 ** found, the corresponding affinity is returned. If zType contains
122200 ** the table take priority. For example, if zType is 'BLOBINT',
122201 ** SQLITE_AFF_INTEGER is returned.
122215 ** SQLITE_AFF_NUMERIC is returned.
122255 /* If pCol is not NULL, store an estimate of the field size. The
122256 ** estimate is scaled so that the size of an integer is 1. */
122258 int v = 0; /* default size is approx 4 bytes */
122286 ** The expression is the default value for the most recently added column
122290 ** is not the case.
122292 ** This routine is called by the parser while in the middle of
122309 sqlite3ErrorMsg(pParse, "default value of column [%s] is not constant",
122318 /* A copy of pExpr is used instead of the original, as pExpr contains
122347 ** This is goofy. But to preserve backwards compatibility we continue to
122350 ** if the expression is just a TK_STRING with an optional COLLATE clause.
122351 ** If the expression is anything other than TK_STRING, the expression is
122378 ** Designate the PRIMARY KEY for the table. pList is a list of names
122379 ** of columns that form the primary key. If pList is NULL, then the
122380 ** most recently added column of the table is the primary key.
122383 ** a primary key (and this is the second primary key) then create an
122386 ** If the PRIMARY KEY is on a single column whose datatype is INTEGER,
122389 ** INTEGER PRIMARY KEY column. Table.iPKey is set to -1 if there is
122392 ** If the key is not an INTEGER PRIMARY KEY, then create a unique
122393 ** index for the key. No index is created for INTEGER PRIMARY KEYs.
122399 int autoInc, /* True if the AUTOINCREMENT keyword is present */
122455 sqlite3ErrorMsg(pParse, "AUTOINCREMENT is only allowed on an "
122522 /* If the column is declared as "<name> PRIMARY KEY COLLATE <type>",
122524 ** collation type was added. Correct this if it is the case.
122574 ** optimizations to work correctly. So if the value is not an expression,
122590 ** SQLITE_OMIT_GENERATED_COLUMNS compile-time option is used. */
122599 ** The schema cookie is used to determine when the schema for the
122606 ** This plan is not completely bullet-proof. It is possible for
122609 ** and the probability of hitting the same cookie value is only
122628 ** The estimate is conservative. It might be larger that what is
122640 ** The first parameter is a pointer to an output buffer. The second
122641 ** parameter is a pointer to an integer that contains the offset at
122648 ** characters, does not begin with a digit and is not an SQL keyword,
122649 ** then it is copied to the output buffer exactly as it is. Otherwise,
122650 ** it is quoted using double-quotes.
122677 ** table. Memory to hold the text of the statement is obtained
122804 /* Return true if column number x is any of the first nCol entries of aiCol[].
122805 ** This is used to determine if the column number x appears in any of the
122819 ** match the iCol-th entry of pPk. pPk is always a WITHOUT ROWID
122820 ** PRIMARY KEY index. pIdx is an index on the same table. pIdx may
122853 ** colNotIdxed is a bitmask that has a 0 bit representing each indexed
122856 ** high-order bit of colNotIdxed is always 1. All unindexed columns
122867 ** The colNotIdxed mask is AND-ed with the SrcList.a[].colUsed mask
122868 ** to determine if the index is covering index.
122888 ** has a WITHOUT ROWID clause. The job of this routine is to convert both
122897 ** for the PRIMARY KEY as the primary key index is now
122902 ** so that the PRIMARY KEY is a covering index. The surplus
122908 ** For virtual tables, only (1) is performed.
122996 ** table entry. This is only required if currently generating VDBE
123004 /* The root page of the PRIMARY KEY is the table root page */
123020 /* This index is a superset of the primary key */
123067 ** Return true if pTab is a virtual table and zName is a shadow table name
123088 ** Table pTab is a virtual table. If it the virtual table implementation
123123 ** Return true if zName is a shadow table name in the current database
123126 ** zName is temporarily modified while this routine is running, but is
123131 Table *pTab; /* Table that zName is a shadow of */
123172 ** This routine is called to report the final ")" that terminates
123176 ** is added to the internal hash tables, assuming no errors have
123179 ** An entry for the table is made in the schema table on disk, unless
123180 ** this is a temporary table or db->init.busy==1. When db->init.busy==1
123186 ** If the pSelect argument is not NULL, it means that this routine
123213 /* If the db->init.busy is 1 it means we are reading the SQL off the
123219 ** If the root page number is 1, that means this is the sqlite_schema
123234 ** a datatype that is one of INT, INTEGER, REAL, TEXT, or BLOB.
123236 ** * If a PRIMARY KEY is defined, other than the INTEGER PRIMARY KEY,
123297 ** actually be used if PRAGMA writable_schema=ON is set. */
123320 ** tree that have been allocated from lookaside memory, which is
123346 ** If this is a TEMPORARY table, write the entry into the auxiliary
123376 /* If this is a CREATE TABLE xx AS SELECT ..., execute the SELECT
123378 ** new table is in register pParse->regRoot.
123380 ** Once the SELECT has been coded by sqlite3Select(), it is in a
123384 ** A shared-cache write-lock is not required to write to the new table,
123517 /* If this is the magic sqlite_sequence table used by autoincrement,
123632 ** The Table structure pTable is really a VIEW. Fill in the names of
123634 ** of errors. If an error is seen leave an error message in pParse->zErrMsg.
123661 ** already known. This routine is not called unless either the
123662 ** table is virtual or nCol is zero.
123666 /* A negative nCol is a special marker meaning that we are currently
123673 ** Actually, the error above is now caught prior to reaching this point.
123674 ** But the following test is still important as it does come up
123682 sqlite3ErrorMsg(pParse, "view %s is circularly defined", pTable->zName);
123691 ** to be permanent. So the computation is done on a copy of the SELECT
123720 ** arglist which is stored in pTable->pCheck. The pCheck field
123787 ** This function is called by the VDBE to adjust the internal schema
123795 ** have the same rootpage number as the real table or index that is
123798 ** or tables and not the table/index that is actually being moved.
123831 ** if a root-page of another table is moved by the btree-layer whilst
123842 ** is non-zero, then it is the root page number of a table moved to
123846 ** The "#NNN" in the SQL is a special constant that means whatever value
123847 ** is in register NNN. See grammar rules associated with the TK_REGISTER
123861 ** in case a root-page belonging to another table is moved by the btree layer
123862 ** is also added (this can happen with an auto-vacuum database).
123866 ** is not defined), then it is important to call OP_Destroy on the
123869 ** to be destroyed is relocated by an earlier OP_Destroy. i.e. if the
123953 ** is generated to remove entries from sqlite_schema and/or
123966 ** the table being dropped. This is done before the table is dropped
124023 ** Return true if it is not allowed to drop the given table
124041 ** This routine is called to do the work of a DROP TABLE statement.
124042 ** pName is the name of the table to be dropped.
124071 /* If pTab is a virtual table, call ViewGetColumnNames() to ensure
124072 ** it is initialized.
124118 /* Ensure DROP TABLE is not used on a view, and DROP VIEW is not used
124149 ** This routine is called to create a new foreign key on the table
124152 ** connect the key to the last column inserted. pTo is the name of
124153 ** the table referred to (a.k.a the "parent" table). pToCol is a list
124158 ** An FKey structure is created and added to the table currently
124161 ** The foreign key is set for IMMEDIATE processing. A subsequent call
124290 ** This routine is called when an INITIALLY IMMEDIATE or INITIALLY DEFERRED
124291 ** clause is seen as part of a foreign key definition. The isDeferred
124292 ** parameter is 1 for INITIALLY DEFERRED and 0 for INITIALLY IMMEDIATE.
124293 ** The behavior of the most recently created foreign key is adjusted
124309 ** Generate code that will erase and refill index *pIdx. This is
124313 ** if memRootPage is not negative, it means that the index is newly
124315 ** root page number of the index. If memRootPage is negative, then
124317 ** the root page number of the index is taken from pIndex->tnum.
124320 Table *pTab = pIndex->pTable; /* The table that is indexed */
124387 ** abort. The exception is if one of the indexed expressions contains a
124388 ** user function that throws an exception when it is evaluated. But the
124389 ** overhead of adding a statement journal to a CREATE INDEX statement is
124475 ** Create a new index for an SQL table. pName1.pName2 is the name of the index
124476 ** and pTblList is the name of the table that is to be indexed. Both will
124477 ** be NULL for a primary key or an index that is created to satisfy a
124479 ** as the table to be indexed. pParse->pNewTable is a table that is
124482 ** pList is a list of columns to be indexed. pList will be NULL if this
124483 ** is a primary key or unique-constraint on the most recent column added
124508 int iDb; /* Index of the database that is being written */
124532 ** Find the table that is to be indexed. Return early if not found.
124547 ** is a temp table. If so, set the database to 1. Do not do this
124608 ** Find the name of the index. Make sure there is not already another
124630 sqlite3ErrorMsg(pParse, "there is already a table named %s", zName);
124747 ** report any errors. In the common case where the expression is exactly
124752 ** TODO: Issue a warning if the table primary key is used as part of the
124908 ** ON CONFLICT clauses this is an error. Otherwise, use the
124958 /* If this is the initial CREATE INDEX statement (or CREATE TABLE if the
124959 ** index is an implied index for a UNIQUE or PRIMARY KEY constraint) then
124963 ** table to parse the schema, or if this index is the PRIMARY KEY index
124966 ** If pTblName==0 it means this index is generated as an implied PRIMARY KEY
124983 ** Index.tnum. This is required in case this index is actually a
124984 ** PRIMARY KEY and the table is actually a WITHOUT ROWID table. In
125085 ** aiRowEst[0] is supposed to contain the number of elements in the index.
125086 ** Since we do not know, guess 1 million. aiRowEst[1] is an estimate of the
125088 ** first column of the index. aiRowEst[2] is an estimate of the number
125114 ** 2020-05-27: If some of the stat data is coming from the sqlite_stat1
125128 /* Estimate that a[1] is 10, a[2] is 9, a[3] is 8, a[4] is 7, a[5] is
125129 ** 6 and each subsequent value (if any) is 5. */
125209 ** pArray is a pointer to an array of objects. Each object in the
125210 ** array is szEntry bytes in size. This routine uses sqlite3DbRealloc()
125211 ** to extend the array so that there is space for a new object at the end.
125213 ** When this function is called, *pnEntry contains the current size of
125214 ** the array (in entries - so the allocation is ((*pnEntry) * szEntry) bytes
125217 ** If the realloc() is successful (i.e. if no OOM condition occurs), the
125218 ** space allocated for the new object is zeroed, *pnEntry updated to
125220 ** returned. *pIdx is set to the index of the new array entry in this case.
125222 ** Otherwise, if the realloc() fails, *pIdx is set to -1, *pnEntry remains
125253 ** A new IdList is returned, or NULL if malloc() fails.
125286 assert( pList->eU4!=EU4_EXPR ); /* EU4_EXPR mode is not currently used */
125308 ** The SrcList object is used to represent the FROM clause of a
125311 ** is sufficient for most uses. Smaller values, like say 10, are
125320 ** creating nExtra new slots beginning at iStart. iStart is zero based.
125394 ** need be. A new entry is created in the SrcList even if pTable is NULL.
125396 ** A SrcList is returned, or NULL if there is an OOM error or if the
125400 ** that is input to this routine is automatically freed.
125402 ** If pDatabase is not null, it means that the table has an optional
125405 ** The SrcList.a[].zName field is filled with the table name which might
125406 ** come from pTable (if pDatabase is NULL) or from pDatabase.
125407 ** SrcList.a[].zDatabase is filled with the database name from pTable,
125408 ** or with NULL if no database is specified.
125414 ** Then B is a table name and the database name is unspecified. If called
125419 ** Then C is the table name and B is the database name. If C is defined
125420 ** then so is B. In other words, we never have a case where:
125513 ** This routine is called by the parser to add a new term to the
125514 ** end of a growing FROM clause. The "p" parameter is the part of
125515 ** the FROM clause that has already been constructed. "p" is NULL
125516 ** if this is the first term of the FROM clause. pTable and pDatabase
125518 ** pDatabase is NULL if the database name qualifier is missing - the
125520 ** alias token. If the term is a subquery, then pSubquery is the
125525 ** Return a new SrcList which encodes is the FROM with the new
125540 sqlite3ErrorMsg(pParse, "a JOIN clause is required before %s",
125651 ** is initially attached to the left operand. But the code generator
125656 ** Example: Suppose the join is like this:
125660 ** The operator is "natural cross join". The A and B operands are stored
125668 ** code generator can easily tell that the table is part of
125730 ** Code for ROLLBACK is generated if eType==TK_ROLLBACK. Otherwise
125731 ** code is generated for a COMMIT.
125752 ** This function is called by the parser when it parses a command to create,
125772 ** Make sure the TEMP database is open and available for use. Return
125828 ** If argument zDb is NULL, then call sqlite3CodeVerifySchema() for each
125848 ** is set if the setStatement parameter is true. A checkpoint should
125852 ** can be checked before any changes are made to the database, it is never
125875 ** The code generator calls this routine if is discovers that it is
125878 ** sure that the statement is protected by a statement transaction.
125881 ** isMultiWrite flag was previously set. There is a time dependency
125885 ** makes it more difficult to prove that the code is correct (in
125898 ** and/or current transaction is rolled back.
126110 ** Return a KeyInfo structure that is appropriate for the given Index.
126139 ** sequence. The only way to reactive the index is to reload the
126205 ** This routine is invoked once per CTE by the parser while parsing a
126206 ** WITH clause. The CTE described by the third argument is added to
126207 ** the WITH clause of the second argument. If the second argument is
126208 ** NULL, then a new WITH argument is created.
126223 /* Check that the CTE name is unique within this WITH clause. If
126277 ** a legal notice, here is a blessing:
126318 ** This routine is called if the collation factory fails to deliver a
126341 ** This routine is called on a collation sequence before it is used to
126342 ** check that it is defined. An undefined collation sequence exists when
126343 ** a database is loaded that contains references to collation sequences
126349 ** from the main database is substituted, if one is available.
126368 ** specified by zName and nName is not found and parameter 'create' is
126372 ** array of three CollSeq structures. The first is the collation sequence
126375 ** Stored immediately after the three collation sequences is a copy of
126376 ** the collation sequence name. A pointer to this string is stored in
126421 ** If the entry specified is not found and 'create' is true, then create a
126424 ** A separate function sqlite3LocateCollSeq() is a wrapper around
126457 ** strings is BINARY.
126464 ** This function is responsible for invoking the collation factory callback
126466 ** requested collation sequence is not available in the desired encoding.
126468 ** If it is not NULL, then pColl must point to the database native encoding
126471 ** The return value is either the collation sequence to be used in database
126473 ** sequence can be found. If no collation is found, leave an error message.
126491 /* No collation sequence of this type for this encoding is registered.
126512 ** If the requested collation sequence is not available, or not available
126513 ** in the database native encoding, the collation factory is invoked to
126515 ** and the sequence is available in another text encoding, then that is
126519 ** another error occurs, NULL is returned and an error message written into
126522 ** This routine is a wrapper around sqlite3FindCollSeq(). This routine
126543 ** is called to test how well the function passed as the first argument
126546 ** request is matched. A higher value indicates a better match.
126548 ** If nArg is -1 that means to only return a match (non-zero) if p->nArg
126549 ** is also -1. In other words, we are searching for a function that
126552 ** If nArg is -2 that means that we are searching for any function
126556 ** The returned value is always between 0 and 6, as follows:
126566 ** If nArg==(-2) then any function with a non-null xSFunc is
126567 ** a perfect match and any function with xSFunc NULL is
126605 ** a pointer to the matching FuncDef if found, or 0 if there is no match.
126656 ** If the createFlag argument is true, then a new (blank) FuncDef
126657 ** structure is created and liked into the "db" structure if a
126660 ** If nArg is -2, then the first valid function found is returned. A
126661 ** function is valid if xSFunc is non-zero. The nArg==(-2)
126662 ** case is used to see if zName is a valid function name for some number
126663 ** of arguments. If nArg is -2, then createFlag must be 0.
126665 ** If createFlag is false, then a function with the required name and
126698 /* If no match is found, search the built-in functions.
126700 ** If the DBFLAG_PreferBuiltin flag is set, then search the built-in
126704 ** Except, if createFlag is true, that means that we are trying to
126705 ** install a new function. Whatever FuncDef structure is returned it will
126724 /* If the createFlag parameter is true and the search did not reveal an
126759 ** The Schema.cache_size variable is not cleared.
126820 ** a legal notice, here is a blessing:
126838 ** name is not found or if any other error occurs.
126843 ** pSrc->a[0].pIndex Pointer to the INDEXED BY index, if there is one
126873 /* Return true if table pTab is read-only.
126875 ** A table is read-only if any of the following are true:
126877 ** 1) It is a virtual table and no implementation of the xUpdate method
126880 ** 2) A trigger is currently being coded and the table is a virtual table
126881 ** that is SQLITE_VTAB_DIRECTONLY or if PRAGMA trusted_schema=OFF and
126882 ** the table is not SQLITE_VTAB_INNOCUOUS.
126884 ** 3) It is a system table (i.e. sqlite_schema), this call is not
126888 ** 4) The table is a shadow table, the database connection is in
126890 ** is for a top-level SQL statement.
126927 ** Check to make sure the given table is writable.
126929 ** If pTab is not writable -> generate an error message and return 1.
126930 ** If pTab is writable but other errors have occurred -> return 1.
126931 ** If pTab is writable and no prior errors -> return 0;
126942 sqlite3ErrorMsg(pParse,"cannot modify %s because it is a view",pTab->zName);
126953 ** pWhere argument is an optional WHERE clause that restricts the
127021 ** is a limit/offset term to enforce.
127067 /* duplicate the FROM clause as it is needed by both the DELETE/UPDATE tree
127125 u8 *aToOpen = 0; /* Open cursor iTabCur+j if aToOpen[j] is true */
127162 ** deleted from is a view
127195 /* If pTab is really a view, make sure it has been initialized.
127274 ** It is easier just to erase the whole table. Prior to version 3.6.5,
127278 ** The "rcauth==SQLITE_OK" terms is the
127279 ** IMPLEMENTATION-OF: R-17228-37124 If the action code is SQLITE_DELETE and
127281 ** the truncate optimization is disabled and all rows are deleted
127369 /* For ONEPASS, no need to store the rowid/primary-key. There is only
127400 /* Unless this is a view, open cursors for the table we are
127401 ** deleting from and all its indices. If this is a view, then the
127402 ** only effect this statement has is to fire the INSTEAD OF
127488 /* Return the number of rows that were deleted. If this routine is
127524 ** 1. iDataCur is an open cursor on the btree that is the canonical data
127534 ** that a search record formed from OP_MakeRecord is contained in the
127539 ** ONEPASS_MULTI. If eMode is not ONEPASS_OFF, then the cursor
127540 ** iDataCur already points to the row to delete. If eMode is ONEPASS_OFF
127544 ** If eMode is ONEPASS_MULTI, then this call is being made as part
127546 ** iIdxNoSeek is a valid cursor number (>=0) and is not the same as
127548 ** operation. Or, if iIdxNoSeek is not a valid cursor number, the
127552 ** If iIdxNoSeek is a valid cursor number (>=0) not equal to iDataCur,
127555 ** Except, this optimization is disabled if there are BEFORE triggers since
127562 int iDataCur, /* Cursor from which column data is extracted */
127576 /* Vdbe is guaranteed to have been allocated by this stage. */
127648 /* Delete the index and table entries. Skip this step if pTab is really
127649 ** a view (in which case the only effect of the DELETE statement is to
127652 ** If variable 'count' is non-zero, then this OP_Delete instruction should
127654 ** be invoked unless table pTab is a system table. The difference is that
127655 ** the update-hook is not invoked for rows removed by REPLACE, but the
127656 ** pre-update-hook is.
127707 ** index is the 0-th index.)
127710 ** that is to be deleted.
127748 ** regOut. The key with be for index pIdx which is an index on pTab.
127749 ** iCur is the index of a cursor open on the pTab table and pointing to
127750 ** the entry that needs indexing. If pTab is a WITHOUT ROWID table, then
127753 ** Return a register number which is the first in a block of
127758 ** If *piPartIdxLabel is not NULL, fill it in with a label and jump
127759 ** to that label if pIdx is a partial index that should be skipped.
127762 ** to false or null. If pIdx is not a partial index, *piPartIdxLabel
127763 ** will be set to zero which is an empty label that is ignored by
127767 ** avoid unnecessary register loads. If pPrior is not NULL, then it is
127769 ** computed into register regPrior. If the current pIdx index is generating
127772 ** holds the correct value and the loading of that register is skipped.
127773 ** This optimization is helpful when doing a DELETE or an INTEGRITY_CHECK
127818 /* If the column affinity is REAL but the number is an integer, then it
127823 ** OP_RealAffinity opcode if it is present */
127851 ** a legal notice, here is a blessing:
127941 ** V. The returned value is one of SQLITE_INTEGER, SQLITE_FLOAT,
128048 /* IMP: R-31676-45509 If X is the integer -9223372036854775808
128049 ** then abs(X) throws an integer overflow error since there is no
128060 /* IMP: R-37434-19929 Abs(X) returns NULL if X is NULL. */
128065 /* Because sqlite3_value_double() returns 0.0 if the argument is not
128067 ** IMP: R-01992-00519 Abs(X) returns 0.0 if X is a string or blob
128085 ** If both haystack and needle are BLOBs, then the result is one more than
128185 ** p1 is 1-indexed. So substr(x,1,1) returns the first character
128186 ** of x. If x is text, then we actually count UTF-8 characters.
128187 ** If x is a blob, then we count bytes.
128189 ** If p1 is negative, then we begin abs(p1) from the end of x[].
128191 ** If p2 is negative, return the p2 characters preceding p1.
128229 /* If SUBSTR_COMPATIBILITY is defined then substr(X,0,N) work the same as
128231 ** is essentially a back-out of the bug-fix in check-in [5fc125d362df4b8]
128306 /* The value has no fractional part so there is nothing to round */
128326 ** If nByte is larger than the maximum string or blob length, then
128395 ** is. We might as well use the "version()" function as a substitute.
128414 ** in a way that is testable, mask the sign bit off of negative
128426 ** that is N bytes long.
128450 ** value is the same as the sqlite3_last_insert_rowid() API function.
128459 /* IMP: R-51513-12026 The last_insert_rowid() SQL function is a
128468 ** IMP: R-32760-32347 The changes() SQL function is a wrapper
128483 ** Implementation of the total_changes() SQL function. The return value is
128493 /* IMP: R-11217-42568 This function is a wrapper around the
128510 ** character is exactly one byte in size. Also, provide the Utf8Read()
128512 ** the next character is ASCII.
128522 /* The correct SQL-92 behavior is for the LIKE operator to ignore
128525 /* If SQLITE_CASE_SENSITIVE_LIKE is defined, then the LIKE operator
128526 ** is case sensitive causing 'a' LIKE 'A' to be false */
128537 ** Compare two UTF-8 strings for equality where the first string is
128567 ** Ec Where E is the "esc" character and c is any other
128572 ** This routine is usually quick, but can be N**2 in the worst case.
128605 ** recursive search in this case, but it is an unusual case. */
128606 assert( matchOther<0x80 ); /* '[' is a single-byte character */
128705 ** non-zero if there is no match.
128732 ** Count the number of times that the LIKE operator (or GLOB which is
128733 ** just a variation of LIKE) gets called. This is used for testing
128743 ** the built-in LIKE operator. The first argument to the function is the
128744 ** pattern and the second argument is the string. So, the SQL statements:
128748 ** is implemented as like(B,A).
128820 ** Implementation of the NULLIF(x,y) function. The result is the first
128821 ** argument if the arguments are different. The result is NULL if the
128837 ** Implementation of the sqlite_version() function. The result is the version
128838 ** of the SQLite library that is running.
128846 /* IMP: R-48699-48617 This function is an SQL wrapper around the
128852 ** Implementation of the sqlite_source_id() function. The result is a string
128862 /* IMP: R-24470-31136 This function is an SQL wrapper around the
128868 ** Implementation of the sqlite_log() function. This is a wrapper around
128869 ** sqlite3_log(). The return value is NULL. The function exists purely for
128884 ** The result is an integer that identifies if the compiler option
128897 ** function is a wrapper around the sqlite3_compileoption_used() C/C++
128908 ** The result is a string that identifies the compiler options
128921 ** is a wrapper around the sqlite3_compileoption_get() C/C++ function.
128936 ** Append to pStr text that is the SQL literal representation of the
129001 ** The quote(X) function returns the text of an SQL literal which is the
129006 ** and hence the returned string literal is truncated prior to the first NUL.
129038 ** The char() function takes zero or more arguments, each of which is
129040 ** is the unicode character for the corresponding integer argument.
129126 ** two arguments. In both cases the first argument is interpreted as text
129130 ** If there is only a single argument, then it must consist only of an
129133 ** Or, if there is a second argument, then any character that appears in
129134 ** the second argument is also allowed to appear between pairs of hexadecimal
129137 ** two hexadecimal digits that make up a single byte, NULL is returned.
129222 ** them A, B, and C. The result is also a string which is derived
129291 ** whose index is a power of two: 1, 2, 4, 8, 16, 32, ... */
129317 ** The userdata is 0x1 for left trim, 0x2 for right trim, 0x3 for both.
129403 ** Return a string value that is the concatenation of all non-null
129446 ** The CONCAT(...) function. Generate a string result that is the
129460 ** Generate a string that is the concatenation of 2nd through the Nth
129478 ** The "unknown" function is automatically substituted in place of
129480 ** when the SQLITE_ENABLE_UNKNOWN_SQL_FUNCTION compile-time option is used.
129481 ** When the "sqlite3" command-line shell is built using this functionality,
129499 /* IMP: R-25361-16150 This function is omitted from SQLite by default. It
129500 ** is only available if the SQLITE_SOUNDEX compile-time option is used
129501 ** when SQLite is built.
129507 ** IMP: R-59782-00072 The soundex(X) function returns a string that is the
129552 /* IMP: R-64894-50321 The string "?000" is returned if the argument
129553 ** is NULL or contains no ASCII alphabetic characters. */
129570 ** flag is set. See the sqlite3_enable_load_extension() API.
129711 /* p is always non-NULL because sumStep() will have been called first
129803 /* The sqlite3_aggregate_count() function is deprecated. But just to make
129820 /* p is always non-NULL since countStep() will have been called first */
129853 /* This step function is used for both the min() and max() aggregates,
129855 ** comparison is inverted. For the max() aggregate, the
129857 ** returns (void *)db, where db is the sqlite3* database pointer.
129898 ** The SEPARATOR goes before the EXPR string. This is tragic. The
129900 ** SEPARATOR were appended after EXPR. And the order is undocumented,
129912 ** If pnSepLengths==0, nFirstSepLength is the length used throughout.
129999 /* pGCC is always non-NULL since groupConcatStep() will have always
130004 ** to invoking sqlite3_value_bytes(), in case the text encoding is UTF16 */
130080 ** parameter determines whether or not the LIKE operator is case
130106 ** it is appropriate to apply the LIKE optimization to that function
130108 ** escape character and then return TRUE. If the function is not a
130111 ** The expression "a LIKE b ESCAPE c" is only considered a valid LIKE
130112 ** operator if c is a string literal that is exactly one byte in length.
130113 ** That one byte is stored in aWc[3]. aWc[3] is set to zero if there is
130116 ** *pIsNocase is set to true if uppercase and lowercase are equivalent for
130118 ** between uppercase and lowercase (as does GLOB) then *pIsNocase is set to
130189 ** The sqlite3_user_data() pointer is a pointer to the libm implementation
130377 ** x is a real number that is to be decoded. y is the precision.
130378 ** z is the maximum real precision.
130418 ** are read-only after initialization is complete.
130608 ** a legal notice, here is a blessing:
130628 ** If an immediate foreign key constraint is violated,
130629 ** SQLITE_CONSTRAINT_FOREIGNKEY is returned and the current
130631 ** deferred foreign key constraint is violated, no action is taken
130636 ** with the database handle. The counter is set to zero each time a
130637 ** database transaction is opened. Each time a statement is executed
130638 ** that causes a foreign key violation, the counter is incremented. Each
130639 ** time a statement is executed that removes an existing violation from
130640 ** the database, the counter is decremented. When the transaction is
130641 ** committed, the commit fails if the current value of the counter is
130645 ** there is no way to tell which foreign constraint is not satisfied,
130646 ** or which row it is not satisfied for.
130649 ** transaction is opened, this may cause the mechanism to malfunction.
130651 ** Despite these problems, this approach is adopted as it seems simpler
130656 ** I.1) For each FK for which the table is the child table, search
130657 ** the parent table for a match. If none is found increment the
130660 ** I.2) For each FK for which the table is the parent table,
130663 ** found (as the constraint is now satisfied).
130667 ** D.1) For each FK for which the table is the child table,
130669 ** deleted row in the child table. If such a row is not found,
130672 ** D.2) For each FK for which the table is the parent table, search
130686 ** resolution is considered to delete rows before the new row is inserted.
130688 ** is thrown, even if the FK constraint would be satisfied after the new
130689 ** row is inserted.
130692 ** is that the counter used is stored as part of each individual statement
130694 ** constraint counter is greater than zero,
130696 ** and the statement transaction is rolled back. An exception is an INSERT
130698 ** instead of using a counter, an exception is thrown immediately if the
130699 ** INSERT violates a foreign key constraint. This is necessary as such
130714 ** accessed). No information is required by the code-generator before
130718 ** sqlite3FkRequired() - Test to see if FK processing is required.
130750 ** Given that pParent is the parent table for foreign key constraint pFKey,
130753 ** If successful, zero is returned. If the parent key is an INTEGER PRIMARY
130754 ** KEY column, then output variable *ppIdx is set to NULL. Otherwise, *ppIdx
130755 ** is set to point to the unique index.
130758 ** is not a composite foreign key), output variable *paiCol is set to NULL.
130759 ** Otherwise, it is set to point to an allocated array of size N, where
130760 ** N is the number of columns in the parent key. The first element of the
130761 ** array is the index of the child table column that is mapped by the FK
130763 ** of index *ppIdx. The second element of the array is the index of the
130783 ** then non-zero is returned, and a "foreign key mismatch" error loaded
130784 ** into pParse. If an OOM error occurs, non-zero is returned and the
130785 ** pParse->db->mallocFailed flag is set.
130799 /* The caller is responsible for zeroing output parameters. */
130804 /* If this is a non-composite (single column) foreign key, check if it
130815 ** 1) There is an INTEGER PRIMARY KEY column and the FK is implicitly
130817 ** 2) The FK is explicitly mapped to a column declared as INTEGER
130835 /* pIdx is a UNIQUE index (or a PRIMARY KEY) and has the right number
130837 ** column of pFKey, then this index is a winner. */
130840 /* If zKey is NULL, then this foreign key is implicitly mapped to
130851 /* If zKey is non-NULL, then this foreign key was declared to
130863 /* If the index uses a collation sequence that is different from
130864 ** the default collation sequence for the column, this index is
130879 if( i==nCol ) break; /* pIdx is usable */
130899 ** This function is called when a row is inserted into or deleted from the
130900 ** child table of foreign key constraint pFKey. If an SQL UPDATE is executed
130901 ** on the child table of pFKey, this function is invoked twice for each row
130905 ** Each time it is called, this function generates VDBE code to locate the
130908 ** special action is taken. Otherwise, if the parent row can *not* be
130946 /* If nIncr is less than zero, then check at runtime if there are any
130947 ** outstanding constraints to resolve. If there are not, there is no need
130951 ** any are, then the constraint is considered satisfied. No need to
130964 /* If pIdx is NULL, then the parent key is the INTEGER PRIMARY KEY
130971 ** is no matching parent key. Before using MustBeInt, make a copy of
130979 /* If the parent table is the same as the child table, and we are about
130980 ** to increment the constraint-counter (i.e. this is an INSERT operation),
131006 /* If the parent table is the same as the child table, and we are about
131007 ** to increment the constraint-counter (i.e. this is an INSERT operation),
131013 ** of the parent-key values are NULL (at this point it is known that
131027 /* The parent key is a composite key that includes the IPK column */
131048 /* Special case: If this is an INSERT statement that will insert exactly
131050 ** incrementing a counter. This is necessary as the VM code is being
131071 ** regBase is the first of an array of register that contains the data
131077 Table *pTab, /* The table whose content is at r[regBase]... */
131079 i16 iCol /* Which column of pTab is desired */
131109 Table *pTab, /* The table whose column is desired */
131111 i16 iCol /* The column that is wanted */
131124 ** This function is called to generate code executed when a row is deleted
131125 ** from the parent table of foreign key constraint pFKey and, if pFKey is
131126 ** deferred, when a row is inserted into the same table. When generating
131130 ** Parameter nIncr is passed -1 when inserting a row (as this may decrease
131136 ** For each child row found, one of the following actions is taken:
131204 /* If the child table is the same as the parent table, then add terms
131211 ** The first form is used for rowid tables. The second form is used
131212 ** for WITHOUT ROWID tables. In the second form, the *parent* key is
131214 ** uniquely identify the current row, but the parent key is more convenient
131277 ** NULL pointer (as there are no FK constraints for which t2 is the parent
131285 ** The second argument is a Trigger structure allocated by the
131323 ** This function is called to generate code that runs when table pTab is
131328 ** Normally, no code is required. However, if either
131330 ** (a) The table is the parent table of a FK constraint, or
131331 ** (b) The table is the child table of a deferred FK constraint and it is
131335 ** then the equivalent of "DELETE FROM <tbl>" is executed before dropping
131349 ** is the child table. If one cannot be found, return without
131352 ** when this statement is run. */
131368 ** any modifications to the schema are made. This is because statement
131371 ** If the SQLITE_DeferFKs flag is set, then this is not required, as
131392 ** for which pTab is the child table. An UPDATE statement against pTab
131393 ** is currently being processed. For each column of the table that is
131395 ** is zero or greater (if a column is unmodified the corresponding element
131396 ** is set to -1). If the rowid column is modified by the UPDATE statement
131397 ** the bChngRowid argument is non-zero.
131404 FKey *p, /* Foreign key for which pTab is the child */
131406 int bChngRowid /* True if rowid is modified by this update */
131419 ** for which pTab is the parent table. An UPDATE statement against pTab
131420 ** is currently being processed. For each column of the table that is
131422 ** is zero or greater (if a column is unmodified the corresponding element
131423 ** is set to -1). If the rowid column is modified by the UPDATE statement
131424 ** the bChngRowid argument is non-zero.
131454 ** Return true if the parser passed as the first argument is being
131455 ** used to code a trigger that is really a "SET NULL" action belonging
131473 ** This function is called when inserting, deleting or updating a row of
131477 ** For a DELETE operation, parameter regOld is passed the index of the
131480 ** of the row being deleted, from left to right. Parameter regNew is passed
131483 ** For an INSERT operation, regOld is passed zero and regNew is passed the
131487 ** For an UPDATE operation, this function is called twice. Once before
131488 ** the original record is deleted from the table using the calling convention
131489 ** described for DELETE. Then again after the original record is deleted
131490 ** but before the new record is inserted using the INSERT convention.
131494 Table *pTab, /* Row is being deleted from this table */
131495 int regOld, /* Previous row data is stored here */
131496 int regNew, /* New row data is stored here */
131498 int bChngRowid /* True if rowid is UPDATEd */
131509 /* If foreign-keys are disabled, this function is a no-op. */
131516 /* Loop through all the foreign key constraints for which pTab is the
131517 ** child table (the table that the foreign key definition is part of). */
131547 /* If isIgnoreErrors is true, then a table is being dropped. In this
131550 ** If the parent table of an FK constraint on the current table is
131551 ** missing, behave as if it is empty. i.e. decrement the relevant
131599 /* A row is being removed from the child table. Search for the parent.
131605 /* A row is being added to the child table. If a parent row cannot
131608 ** If this operation is being performed as part of a trigger program
131609 ** that is actually a "SET NULL" action belonging to this very
131611 ** values are guaranteed to be NULL, it is not possible for adding
131663 /* If this is a deferred FK constraint, or a CASCADE or SET NULL
131668 ** Note 1: If the FK is declared "ON UPDATE CASCADE", then the
131670 ** (when this function is called as part of processing the UPDATE
131694 ** This function is called before generating code to update or delete a
131724 ** This function is called before generating code to update or delete a
131725 ** row contained in table pTab. If the operation is a DELETE, then
131726 ** parameter aChange is passed a NULL value. For an UPDATE, aChange points
131727 ** to an array of size N, where N is the number of columns in table pTab.
131728 ** If the i'th column is not modified by the UPDATE, then the corresponding
131729 ** entry in the aChange[] array is set to -1. If the column is modified,
131730 ** the value is 0 or greater. Parameter chngRowid is set to true if the
131734 ** non-zero. If there is no foreign key related processing, this function
131739 ** * There are any FKs for which pTab is the child and the parent table
131740 ** and any FK processing at all is required (even of a different FK), or
131742 ** * the UPDATE modifies one or more parent keys for which the action is
131743 ** not "NO ACTION" (i.e. is CASCADE, SET DEFAULT or SET NULL).
131745 ** Or, assuming some other foreign key processing is required, 1.
131753 int eRet = 1; /* Value to return if bHaveFK is true */
131754 int bHaveFK = 0; /* If FK processing is required */
131757 /* A DELETE operation. Foreign key processing is required if the
131758 ** table in question is either the child or parent table for any
131762 /* This is an UPDATE. Foreign key processing is only required if the
131791 ** This function is called when an UPDATE or DELETE operation is being
131792 ** compiled on table pTab, which is the parent table of foreign-key pFKey.
131793 ** If the current operation is an UPDATE, then the pChanges parameter is
131794 ** passed a pointer to the list of columns being modified. If it is a
131795 ** DELETE, pChanges is passed a NULL pointer.
131799 ** If the action is "NO ACTION" then a NULL pointer is returned (these actions
131800 ** require no special handling by the triggers sub-system, code for them is
131803 ** For example, if pFKey is the foreign key and pTab is table "p" in
131809 ** then the returned trigger structure is equivalent to:
131815 ** The returned pointer is cached as part of the foreign key object. It
131816 ** is eventually freed along with the rest of the foreign key object by
131868 /* Create the expression "OLD.zToCol = zFromCol". It is important
131869 ** that the "OLD.zToCol" term is on the LHS of the = operator, so
132014 ** This function is called when deleting or updating a row to implement
132023 int bChngRowid /* True if rowid is UPDATEd */
132025 /* If foreign-key support is enabled, iterate through all FKs that
132026 ** refer to table pTab. If there is an action associated with the FK
132071 /* EV: R-30323-21917 Each foreign key constraint in SQLite is
132094 ** a legal notice, here is a blessing:
132112 ** If pTab is a WITHOUT ROWID table, then it is the PRIMARY KEY index
132113 ** for that table that is actually opened.
132157 ** An extra 'D' is appended to the end of the string to cover the
132161 ** is managed along with the rest of the Index structure. It will be
132162 ** released when sqlite3DeleteIndex() is called.
132165 /* The first time a column affinity string for a particular index is
132166 ** required, it is allocated and populated here. It is then stored as
132170 ** sqliteDeleteIndex() when the Index structure itself is cleaned
132207 ** Compute an affinity string for a table. Space is obtained
132208 ** from sqlite3DbMalloc(). The caller is responsible for freeing
132238 ** If the affinity string is empty (because it was all SQLITE_AFF_BLOB entries
132264 ** register set as the OP_MakeRecord. If iReg>0 then register iReg is
132275 ** OP_MakeRecord is found */
132314 ** have been opened at any point in the VDBE program. This is used to see if
132394 ** columns. '@' is the no-op affinity and those columns have not
132410 /* If an OP_TypeCheck was generated because the table is STRICT,
132418 ** this is a two-pass algorithm. On the first pass, mark all generated
132474 ** which is in database iDb. Return the register number for the register
132475 ** that holds the maximum rowid. Return zero if pTab is not an AUTOINCREMENT
132479 ** There is at most one AutoincInfo structure per table even if the
132480 ** same table is autoincremented multiple times due to inserts within
132481 ** triggers. A new AutoincInfo structure is created if this is the
132483 ** AutoincInfo structure is used.
132492 ** The 2nd register is the one that is returned. That is all the
132509 /* Verify that the sqlite_sequence table exists and is an ordinary
132553 /* This routine is never called during trigger-generation. It is
132558 assert( v ); /* We failed long ago if this is not so */
132603 ** new rowid that is about to be inserted. If that new rowid is
132605 ** memory cell is updated.
132662 ** If SQLITE_OMIT_AUTOINCREMENT is defined, then the three routines
132680 ** This routine is called to handle SQL of the following forms:
132686 ** The IDLIST following the table name is always optional. If omitted,
132687 ** then a list of all (non-hidden) columns for the table is substituted.
132688 ** The IDLIST appears in the pColumn parameter. pColumn is NULL if IDLIST
132689 ** is omitted.
132692 ** first two forms shown above. A VALUES clause is really just short-hand
132694 ** that follows. If the pSelect parameter is NULL, that means that the
132695 ** DEFAULT VALUES form of the INSERT statement is intended.
132707 ** The three remaining templates assume the statement is of the form
132711 ** If the SELECT clause is of the restricted form "SELECT * FROM <table2>" -
132713 ** and there is no WHERE or LIMIT or GROUP BY or ORDER BY clauses, and
132716 ** is invoked that copies raw records from <table2> over to <table1>.
132718 ** template. This is the 2nd template.
132731 ** The 3rd template is for when the second template does not apply
132750 ** The 4th template is used if the insert statement takes its
132751 ** values from a SELECT but the data is being inserted into a table
132752 ** that is also read as part of the SELECT. In the third form,
132754 ** the select. The template is like this:
132790 int nHidden = 0; /* Number of hidden columns if TABLE is virtual */
132791 int iDataCur = 0; /* VDBE cursor that is the main data repository */
132793 int ipkColumn = -1; /* Column that is the INTEGER PRIMARY KEY */
132801 u8 appendFlag = 0; /* True if the insert is likely to be an append */
132803 u8 bIdListInOrder; /* True if IDLIST is in table order */
132830 /* If the Select object is really just a simple VALUES() list with a
132857 ** inserted into is a view
132881 /* If pTab is really a view, make sure it has been initialized.
132882 ** ViewGetColumnNames() is a no-op if pTab is not a view.
132902 /* If the statement is of the form
132909 ** This is the 2nd template.
132922 /* If this is an AUTOINCREMENT table, look up the sequence number in the
132943 ** is named in the IDLIST, then record in the ipkColumn variable
132944 ** the index into IDLIST of the primary key column. ipkColumn is
132946 ** is appears in the original table. (The index of the INTEGER
132947 ** PRIMARY KEY in the original table is pTab->iPKey.) After this
132949 ** is unspecified, and hence the table is either WITHOUT ROWID or
132952 ** bIdListInOrder is true if the columns in IDLIST are in storage
132998 ** is coming from a SELECT statement, then generate a co-routine that
133000 ** co-routine is the common header to the 3rd and 4th templates.
133003 /* Data is coming from a SELECT or from a multi-row VALUES clause.
133030 ** A temp table must be used if the table being updated is also one
133041 ** here is from the 4th template:
133067 /* This is the case if the data for the INSERT is coming from a
133085 /* If there is no IDLIST term but the table has an integer primary
133139 /* If this is not a view, open the table and and all indices */
133188 /* This is the top of the main insertion loop */
133190 /* This block codes the top of loop only. The complete loop is the
133202 /* This block codes the top of loop only. The complete loop is the
133214 /* tag-20191021-001: If the INTEGER PRIMARY KEY is being generated by the
133224 ** (if there is one) is computed later and generated columns are
133281 /* This is INSERT INTO ... DEFAULT VALUES. Load the default value. */
133313 /* build the NEW.* reference row. Note that if there is an INTEGER
133314 ** PRIMARY KEY into which a NULL is being inserted, that NULL will be
133327 assert( pSelect==0 ); /* Otherwise useTempTable is true */
133352 /* If this is an INSERT on a view with an INSTEAD OF INSERT trigger,
133354 ** If this is a real table, attempt conversions as required by the
133388 /* If the PRIMARY KEY expression is NULL, then use OP_NewRowid
133415 ** is derived from the INTEGER PRIMARY KEY. */
133444 ** constraints or (b) there are no triggers and this table is not a
133445 ** parent table in a foreign key constraint. It is safe to set the
133446 ** flag in the second case as if any REPLACE constraint is hit, an
133448 ** cursor that is disturbed. And these instructions both clear the
133458 /* If there is a RETURNING clause, populate the rowid register with
133478 ** is a SELECT statement.
133488 /* If we are jumping back to an OP_Yield that is preceded by an
133511 ** Return the number of rows inserted. If this routine is
133548 /* This is the Walker callback from sqlite3ExprReferencesUpdatedColumn().
133568 ** pExpr is a CHECK constraint on a row that is being UPDATE-ed. The
133570 ** aiChng[i]>=0, and also the ROWID is modified if chngRowid is true.
133573 ** changing columns (or the rowid if it is changing). In other words,
133578 ** The operation of this routine is the same - return true if an only if
133607 ** However, sometimes (rarely - when there is an upsert) it wants to visit
133611 ** The IndexIterator object is used to walk through all of the indexes
133631 /* When IndexIterator.eType==1, then each index is an array of instances
133636 int ix; /* Which entry in the original Table.pIndex list is this index*/
133672 ** The regNewData parameter is the first register in a range that contains
133680 ** The regOldData parameter is similar to regNewData except that it contains
133681 ** the data prior to an UPDATE rather than afterwards. regOldData is zero
133685 ** For an UPDATE, the pkChng boolean is true if the true primary key (the
133687 ** might be modified by the UPDATE. If pkChng is false, then the key of
133688 ** the iDataCur content table is guaranteed to be unchanged by the UPDATE.
133692 ** is zero, it means that the either rowid is computed automatically or
133693 ** that the table is a WITHOUT ROWID table and has no rowid. On an INSERT,
133698 ** registers identified by aRegIdx[]. No index entry is created for
133699 ** indices where aRegIdx[i]==0. The order of indices in aRegIdx[] is
133704 ** main table, if pTab is a rowid table, and stores that record in the
133706 ** entry of aRegIdx[] past the last index. It is important that the
133709 ** the new record is inserted.
133712 ** table and all applicable indices (that is to say, all indices for which
133713 ** aRegIdx[] is not zero). iDataCur is the cursor for the main table when
133715 ** index when operating on a WITHOUT ROWID table. iIdxCur is the cursor
133721 ** then the appropriate action is performed. There are five possible
133726 ** any ROLLBACK The current transaction is rolled back and
133737 ** transaction is not rolled back and any
133741 ** row is skipped, without throwing an error.
133743 ** (There is an immediate jump to ignoreDest.)
133745 ** NOT NULL REPLACE The NULL value is replace by the default
133747 ** is NULL, the action is the same as ABORT.
133750 ** being inserted is removed.
133754 ** Which action to take is determined by the overrideError parameter.
133756 ** is used. Or if pParse->onError==OE_Default then the onError value
133757 ** for the constraint is used.
133771 int *aiChng, /* column i is unchanged if aiChng[i]<0 */
133782 int seenReplace = 0; /* True if REPLACE is used to resolve INT PK conflict */
133785 u8 isUpdate; /* True if this is an UPDATE operation */
133804 assert( !IsView(pTab) ); /* This table is not a VIEW */
133807 /* pPk is the PRIMARY KEY index for WITHOUT ROWID tables and NULL for
133808 ** normal rowid tables. nPkField is the number of key fields in the
133809 ** pPk index or 1 for a rowid table. In other words, nPkField is the
133833 int isGenerated; /* non-zero if column is generated */
133837 continue; /* ROWID is never NULL */
133855 || pCol->iDflt==0 /* REPLACE is ABORT if no DEFAULT value */
133908 ** pass is sufficient */
133940 ** updated so there is no point it verifying the check constraint */
133988 ** Constraint checking code is generated in this order:
133994 ** The ordering of (2) and (3) is accomplished by making sure the linked
134004 /* There is just on ON CONFLICT clause and it has no constraint-target */
134058 /* Determine if it is possible that triggers (either explicitly coded
134063 ** But on the recheck, the resolution is OE_Abort instead of OE_Replace.
134069 ** fire. Constraint recheck only occurs if the number is positive.
134102 /* If rowid is changing, make sure the new rowid does not previously
134121 onError = OE_Ignore; /* DO NOTHING is the same as INSERT OR IGNORE */
134134 /* If the response to a rowid conflict is REPLACE but the response
134135 ** to some other UNIQUE constraint is FAIL or IGNORE, then we need
134139 if( onError==OE_Replace /* IPK rule is REPLACE */
134151 ** is unchanged. */
134180 ** recursive-triggers flag is set, call GenerateRowDelete() to
134185 ** flag is not set, but the table has one or more indexes, call
134188 ** when it is inserted.
134190 ** If either GenerateRowDelete() or GenerateRowIndexDelete() is called,
134192 ** statement rollback (if the statement is aborted after the delete
134211 ** not modify the b-tree. It is more efficient to let the coming
134212 ** OP_Insert replace the existing entry than it is to delete the
134260 int addrUniqueOk; /* Jump here if the UNIQUE constraint is satisfied */
134279 /* Skip partial indices for which the WHERE clause is not true */
134320 /* In an UPDATE operation, if this index is the PRIMARY KEY index
134322 ** primary key, then no collision is possible. The collision detection
134329 /* Find out what action to take in case there is a uniqueness conflict */
134333 continue; /* pIdx is not a UNIQUE index */
134344 onError = OE_Ignore; /* DO NOTHING is the same as INSERT OR IGNORE */
134351 ** (1) The conflict resolution algorithm is REPLACE
134352 ** (2) The table is a WITHOUT ROWID table
134354 ** (4) No delete triggers need to be fired if there is a conflict
134357 ** This is not possible for ENABLE_PREUPDATE_HOOK builds, as the row
134359 ** is invoked. */
134387 ** is different from old-rowid */
134438 /* Generate code that executes if the new index entry is not unique */
134496 /* Bypass the recheck if this partial index is not defined
134547 /* If the IPK constraint is a REPLACE, run it last */
134612 ** Table pTab is a WITHOUT ROWID table that is being written to. The cursor
134613 ** number is iCur, and register regData contains the new record for the
134615 ** if one is registered.
134654 int appendBias, /* True if this is likely to be an append */
134669 assert( !IsView(pTab) ); /* This table is not a VIEW */
134719 ** ROWID table) is returned in *piDataCur. The first index cursor is
134720 ** returned in *piIdxCur. The number of indices is returned.
134723 ** or the first index for WITHOUT ROWID tables) if it is non-negative.
134724 ** If iBase is negative, then allocate the next available cursor.
134731 ** If pTab is a virtual table, then this routine is a no-op and the
134739 int iBase, /* Use this for the table cursor, if there is one */
134755 /* This routine is a no-op for virtual tables. Leave the output
134794 ** The following global variable is incremented whenever the
134795 ** transfer optimization is used. This is used for testing
134797 ** is happening when it is supposed to.
134805 ** Check to see if index pSrc is compatible as a source of data
134809 ** * The index is over the same set of columns
134860 ** The xfer optimization is only attempted if tab1 and tab2 are compatible.
134864 ** This routine returns TRUE if the optimization is guaranteed to be used.
134866 ** is empty - a factor that can only be determined at run-time. In that
134868 ** does a test to see if the destination table is empty and jumps over the
134872 ** is no chance that the xfer optimization can be applied.
134874 ** This optimization is particularly useful at making VACUUM run faster.
134915 assert(pSelect->pSrc); /* allocated even if there is no FROM clause */
134928 /* Do not need to test for a HAVING clause. If HAVING is present but
134929 ** there is no ORDER BY, we will get an error. */
134952 /* At this point we have established that the statement is of the
134992 ** generated columns, then this statement is semantically incorrect:
134996 ** The reason is that generated column values are returned by the
135000 ** Nevertheless, this is a useful notational shorthand to tell SQLite
135004 ** VACUUM command where it is actually needed). But why do that? It
135011 /* But the transfer is only allowed if both the source and destination
135033 return 0; /* tab2 must be NOT NULL if tab1 is */
135076 ** any foreign key constraints. This is more restrictive than necessary.
135077 ** But the main beneficiary of the transfer optimization is the VACUUM
135079 ** the extra complication to make this rule less restrictive is probably
135091 /* If we get this far, it means that the xfer optimization is at
135093 ** table (tab1) is initially empty.
135115 ** only if the destination table is initially empty. Unless the
135116 ** DBFLAG_Vacuum flag is set, this block generates code to make
135117 ** that determination. If DBFLAG_Vacuum is set, then the destination
135118 ** table is always empty.
135122 ** (1) There is no INTEGER PRIMARY KEY but there are indices.
135123 ** (If the destination is not initially empty, the rowid fields
135127 ** is unable to test uniqueness.)
135129 ** (3) onError is something other than OE_Abort and OE_Rollback.
135199 /* This INSERT command is part of a VACUUM operation, which guarantees
135200 ** that the destination table is empty. If all indexed columns use
135204 ** of every OP_IdxInsert opcode, an OP_SeekEnd is added before the
135206 ** should be inserted. This is faster.
135209 ** BINARY, this optimization is disabled. This is because the user
135262 ** a legal notice, here is a blessing:
135282 ** If the SQL is a query, then for each row in the query result
135283 ** the xCallback() function is called. pArg becomes the first
135285 ** is invoked, even for queries.
135298 int callbackIsInit; /* True if callback data is initialized */
135339 ** strings so there is no way for sqlite3_column_name() to fail. */
135406 ** a legal notice, here is a blessing:
135426 ** a legal notice, here is a blessing:
135793 ** This is the function signature used for all extension entry points. It
135794 ** is also defined in the file "loadext.c".
135806 ** This header file is also used by the loadext.c source file
135811 ** SQLITE_CORE macros is undefined.
136126 /* This case when the file really is being compiled as a loadable
136133 /* This case when the file is being statically linked into the
136244 ** A pointer to this structure is passed into extensions when they are
136253 ** intend to use is supported by the library. Extensions should
136254 ** also check to make sure that the pointer to the function is
136329 0, /* Was sqlite3_global_recover(), but that function is deprecated */
136391 ** of the APIs above provided that the pointer is not NULL. But
136394 ** a library that is new enough to support that API.
136647 /* True if x is the directory separator character
136657 ** zFile. The entry point is zProc. zProc may be 0 in which case a
136658 ** default entry point name (sqlite3_extension_init) is used. Use
136659 ** of the default name is recommended.
136663 ** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with
136700 ** ability to run load_extension is turned off by default. One
136744 ** construct an entry point name "sqlite3_X_init" where the X is
136843 ** Call this routine when the database connection is closing in order
136856 ** Enable or disable extension loading. Extension loading is disabled by
136879 ** This list is shared across threads. The SQLITE_MUTEX_STATIC_MAIN
136889 ** state vector. If writable static data is unsupported on the target,
136891 ** case where writable static data is supported, wsdStat can refer directly
136905 ** Register a statically linked extension that is automatically
136951 ** set of routines that is invoked for each new database connection, if it
136952 ** is currently on the list. If xInit is not on the list, then this
136953 ** routine is a no-op.
137053 ** a legal notice, here is a blessing:
137073 ** The "pragma.h" include file is an automatically generated file that
137075 ** object. This ensures that the aPragmaName[] table is arranged in
137082 ** This file is automatically generated by the script at
137138 #define PragFlg_NoColumns1 0x04 /* zero columns if RHS argument is present */
137143 #define PragFlg_SchemaReq 0x80 /* Schema required - "main" is default */
137147 ** result column is different from the name of the pragma
137748 ** unrecognized string argument. The FULL and EXTRA option is disallowed
137752 ** should be passed into sqlite3BtreeSetSafetyLevel(). The is done
137785 /* The sqlite3GetBoolean() function is used by other modules but the
137786 ** remainder of this file is specific to PRAGMA processing. So omit
137840 ** Invalidate temp storage, either when the temp storage is changed
137863 ** If the TEMP database is open, close it and mark the database schema
138019 int isBuiltin, /* True if this is a built-in function */
138085 ** The identifier might also be a string. The value is a string, and
138086 ** identifier, or a number. If minusFlag is true, then the value is
138089 ** If the left side is "database.id" then pId1 is the database name
138090 ** and pId2 is the id. If the left side is just "id" then pId1 is the
138091 ** id and pId2 is any empty string.
138116 /* Interpret the [schema.] part of the pragma statement. iDb is the
138117 ** index of the database this pragma is being applied to in db.aDb[]. */
138123 ** pragma, make sure it is open.
138147 ** IMPLEMENTATION-OF: R-12238-55120 Whenever a PRAGMA statement is parsed,
138148 ** an SQLITE_FCNTL_PRAGMA file control is sent to the open sqlite3_file
138153 ** file control is an array of pointers to strings (char**) in which the
138154 ** second element of the array is the name of the pragma and the third
138155 ** element is the argument to the pragma or NULL if the pragma has no
138185 ** unknown pragma is issued. */
138189 /* Make sure the database schema is loaded if the pragma requires that */
138210 ** page cache size. The value returned is the maximum number of
138217 ** is always on by default regardless of the sign of the default cache
138273 /* Malloc may fail when setting the page-size, as there is an internal
138323 ** The absolute value of N is used. This is undocumented and might
138324 ** change. The only purpose is to provide an easy way to test
138360 /* Simple "PRAGMA locking_mode;" statement. This is a query for
138372 ** Also, the sqlite3.dfltLockMode variable is set so that
138407 /* If there is no "=MODE" part of the pragma, do a query for the
138423 ** can become corrupted using ordinary SQL when the journal is off */
138467 ** The value is one of: 0 NONE 1 FULL 2 INCREMENTAL
138480 ** incr-vacuum flags. This is required in case this connection
138481 ** creates the database file. It is important that it is created
138489 ** that this really is an auto-vacuum capable database.
138545 ** page cache size value. If N is positive then that is the
138546 ** number of pages in the cache. If N is negative, then the
138547 ** number of pages is adjusted so that the cache uses -N kibibytes
138569 ** or off. When turning cache spill on, the size is set to the
138572 ** If N is positive then that is the
138573 ** number of pages in the cache. If N is negative, then the
138574 ** number of pages is adjusted so that the cache uses -N kibibytes
138577 ** If the number of cache_spill pages is less then the number of
138608 ** Used to set mapping size limit. The mapping size limit is
138610 ** database file. If this parameter is set to zero, then memory mapping
138611 ** is not used at all. If N is negative, then the default memory map
138612 ** limit determined by sqlite3_config(SQLITE_CONFIG_MMAP_SIZE) is set.
138613 ** The parameter N is measured in bytes.
138615 ** This value is advisory. The underlying VFS is free to memory map
138616 ** as little or as much as it wants. Except, if N is set to 0 then the
138655 ** value will be restored the next time the database is opened.
138657 ** Note that it is possible for the library compile-time options to
138676 ** If temporary directory is changed, then invalidateTempStorage.
138797 ** default value will be restored the next time the database is
138850 /* IMP: R-60817-01178 If the argument is "RESET" then schema
138851 ** writing is disabled (as with "PRAGMA writable_schema=OFF") and,
138852 ** in addition, the schema is reloaded. */
138878 ** notnull: True if 'NOT NULL' is part of column declaration
138956 /* Ensure that the Table.nCol field is initialized for all views
139044 /* If there is no index named zRight, check to see if there is a
139045 ** WITHOUT ROWID table named zRight, and if there is, show the
139126 sqlite3VdbeMultiLoad(v, 1, "is", i++, pColl->zName);
139223 int addrOk; /* Jump here if the key is OK */
139292 ** key. If a match is found, jump to addrOk. */
139348 ** The "quick_check" is reduced version of
139351 ** is linear time whereas integrity_check is O(NlogN).
139353 ** The maximum number of errors is 100 by default. A different default
139357 ** the one table named is verified. The freelist is only verified if
139358 ** the named table is "sqlite_schema" (or one of its aliases).
139372 ** then iDb is set to the index of the database identified by <db>.
139373 ** In this case, the integrity of database iDb only is verified by
139377 ** "PRAGMA quick_check"), then iDb is set to 0. In this case, set iDb
139526 ** will also prepopulate the cursor column cache that is used
139527 ** by the OP_IsType code, so it is a required step.
139538 ** PK index column-count, so there is no need to account for them
139633 ** is REAL, we have to load the actual data using OP_Column
139634 ** to reliably determine if the value is a NULL. */
139745 /* The OP_IdxRowid opcode is an optimized version of OP_Column
139748 ** any extra bytes at the end. Verify that this is the case. */
139782 ** current key. The entry is unique if (1) any column is NULL
139860 ** database. If the database is not initialized, it is initialized now.
139862 ** The second form of this pragma is a no-op if the main database file
139865 ** is created. If an existing main database file is opened, then the
139866 ** default text encoding for the existing database is used.
139871 ** is executed, this is done before the ATTACH operation.
139874 ** new database files created using this database handle. It is only
139900 /* Only change the value of sqlite.enc if the database handle is not
139902 ** will be overwritten when the schema is next loaded. If it does not
139943 ** The schema-cookie is usually only manipulated internally by SQLite. It
139944 ** is incremented by SQLite whenever the database schema is modified (by
139945 ** creating or dropping a table or index). The schema version is used by
139946 ** SQLite each time a query is executed to ensure that the internal cache
139948 ** the database against which the compiled query is actually executed.
139950 ** the schema-version is potentially dangerous and may lead to program
139953 ** The user-version is not used internally by SQLite. It may be used by
140066 ** connection on which it is invoked to free up as much memory as it
140081 ** two forms, and only the specified schema is optimized in the latter two.
140087 ** The optional argument is a bitmask of optimizations to perform:
140104 ** The default MASK is and always shall be 0xfffe. 0xfffe means perform all
140112 ** In the current implementation, a table is analyzed if only if all of
140115 ** (1) MASK bit 0x02 is set.
140158 /* Reanalyze if the table is 25 times larger than the last analysis */
140192 ** if one is set. If no busy handler or a different busy handler is set
140193 ** then 0 is returned. Setting the busy_timeout to 0 or negative
140210 ** sqlite3_soft_heap_limit64() interface with the argument N, if N is
140211 ** specified and is a non-negative integer.
140323 /* The following block is a no-op unless SQLITE_DEBUG is defined. Its only
140324 ** purpose is to execute assert() statements to verify that if the
140325 ** PragFlg_NoColumns1 flag is set and the caller specified an argument
140632 ** Check to see if zTabName is really the name of a pragma. If it is,
140656 ** a legal notice, here is a blessing:
140671 ** that the database is corrupt.
140733 ** This is the callback routine for the code that initializes the
140735 ** This routine is also called from the OP_ParseSchema opcode of the VDBE.
140769 ** But because db->init.busy is set to 1, no VDBE code is generated
140770 ** or executed. All the parser does is build the internal data
140774 ** can begin with the letters "C" and "R". Thus, it is not possible run
140817 /* If the SQL column is blank it means this is an index that
140821 ** to do here is record the root page number for that index.
140844 ** database file is given by iDb. iDb==0 is used for the main
140845 ** database. iDb==1 should never be used. iDb>=2 is used for
140907 /* If there is not already a read-only (or read-write) transaction opened
140908 ** on the b-tree database, open one now. If a transaction is opened, it
140947 ** For an attached db, it is an error if the encoding is not the same
141051 /* Hack: If the SQLITE_NoSchemaError flag is set, then consider
141058 ** The primary purpose of this is to allow access to the sqlite_schema
141092 ** After a database is initialized, the DB_SchemaLoaded bit is set
141093 ** bit is set in the flags field of the Db structure.
141124 ** This routine is a no-op if the database schema is already initialized.
141125 ** Otherwise, the schema is loaded. An error code is returned.
141145 ** Check schema cookies in all databases. If any cookie is out
141158 int openedTransaction = 0; /* True if a transaction is opened */
141162 /* If there is not already a read-only (or read-write) transaction opened
141163 ** on the b-tree database, open one now. If a transaction is opened, it
141196 ** If the same database is attached more than once, the first
141197 ** attached database is returned.
141202 /* If pSchema is NULL, then return -32768. This happens when code in
141203 ** expr.c is trying to resolve a reference to a transient table (i.e. one
141208 ** -32768 as the incorrect index into db->aDb[] is much
141256 ** the parser object is destroyed. But, beware: the cleanup might happen
141259 ** Use this mechanism for uncommon cleanups. There is a higher setup
141267 ** pParse->earlyCleanup flag is set in that case. Calling code show verify
141269 ** use-after-free errors following an OOM. The preferred way to do this is
141276 ** another way to check for early cleanup is to check the return value.
141310 ** is generated by Lemon.
141375 /* Check to verify that it is possible to get a read lock on all
141377 ** some other database connection is holding a write-lock, which in
141387 ** This thread is currently holding mutexes on all Btrees (because
141389 ** is not possible for another thread to start a new schema change
141390 ** while this routine is running. Hence, we do not need to hold
141391 ** locks on the schema, we just need to make sure nobody else is
141396 ** works even if READ_UNCOMMITTED is set.
141406 sqlite3ErrorWithMsg(db, rc, "database schema is locked: %s", zDb);
141511 ** reset is considered a permanent error. */
141530 ** If the statement is successfully recompiled, return SQLITE_OK. Otherwise,
141568 ** version, the original SQL text is not saved in the prepared statement
141569 ** and so if a schema change occurs, SQLITE_SCHEMA is returned by
141570 ** sqlite3_step(). In the new version, the original SQL text is retained
141571 ** and the statement is automatically recompiled if an schema change
141598 ** Proof in that the 5th parameter to sqlite3LockAndPrepare is 0 */
141615 ** which is a bit array consisting of zero or more of the
141642 ** tricky bit is figuring out the pointer to return in *pzTail.
141684 ** version, the original SQL text is not saved in the prepared statement
141685 ** and so if a schema change occurs, SQLITE_SCHEMA is returned by
141686 ** sqlite3_step(). In the new version, the original SQL text is retained
141687 ** and the statement is automatically recompiled if an schema change
141738 ** a legal notice, here is a blessing:
141751 ** An instance of the following object is used to record information about
141764 ** An instance of the following object is used to record information about
141765 ** the ORDER BY (or GROUP BY) clause of query is being coded.
141767 ** The aDefer[] array is used by the sorter-references optimization. For
141768 ** example, assuming there is no index that can be used for the ORDER BY,
141777 ** When the sorter-reference optimization is used, there is one entry in the
141790 int labelOBLopt; /* Jump here when sorter is full */
141944 ** A full outer join is the combination of JT_LEFT and JT_RIGHT.
141946 ** If an illegal or unsupported join type is seen, then still return
141992 ** * If "OUTER" is present then there must also be one of
142051 ** is not contained in the table.
142081 ** table that has a column named zCol. The search is left-to-right.
142082 ** The first match found is returned.
142126 ** The EP_OuterON property is used on terms of an expression to tell
142127 ** the OUTER JOIN processing logic that this term is part of the
142134 ** expression depends on table w.iJoin even if that table is not
142135 ** explicitly mentioned in the expression. That information is needed
142145 ** the output, which is incorrect.
142168 /* Undo the work of sqlite3SetJoinExpr(). This is used when a LEFT JOIN
142169 ** is simplified into an ordinary JOIN, and when an ON expression is
142172 ** Convert every term that is marked with EP_OuterON and w.iJoin==iTable into
142176 ** If nullable is true, that means that Expr p might evaluate to NULL even
142177 ** if it is a reference to a NOT NULL column. This can happen, for example,
142178 ** if the table that p references is on the left side of a RIGHT JOIN.
142179 ** If nullable is true, then take care to not remove the EP_CanBeNull bit.
142209 ** * A NATURAL join is converted into a USING join. After that, we
142219 ** The left most table is the first entry in Select.pSrc. The right-most
142220 ** table is the last entry. The join operator is held in the entry to
142243 /* If this is a NATURAL join, synthesize an appropriate USING clause
142279 ** Report an error if any column mentioned in the USING clause is
142310 ** contains the zName column, then this branch is a no-op.
142314 ** to zName is not also within a prior USING clause.
142370 ** needed to load the next result row that is to be added to the sorter.
142405 ** Return the register in which the result is stored.
142460 ** regOrigData is 0 to prevent this routine from trying to copy
142534 ** less than LIMIT+OFFSET items or (b) the new record is smaller than
142535 ** the largest record currently in the sorter. If (b) is true and there
142542 ** value is not zero, then it is a label of where to jump. Otherwise,
142590 ** iMem form a distinct entry. This is used by both "SELECT DISTINCT ..." and
142592 ** are available. Which is used depends on the value of parameter eTnctType,
142599 ** Parameter iTab is the cursor number of an ephemeral table that must
142600 ** be opened before the VM code generated by this routine is executed.
142601 ** The ephemeral cursor table is queried for a record identical to the
142602 ** record formed by the current array of registers. If one is found,
142606 ** The returned value in this case is a copy of parameter iTab.
142610 ** table is not required. Instead, the current set of values
142611 ** is compared against previous row. If they match, the new row
142612 ** is not distinct and control jumps to VM address addrRepeat. Otherwise,
142615 ** The returned value in this case is the register number of the first
142618 ** register is initialized to NULL. (The fixDistinctOpenEph() routine
142623 ** No special action is required. The return value is zero.
142625 ** Parameter pEList is the list of expressions used to generated the
142626 ** contents of each row. It is used by this routine to determine (a)
142629 ** eTnctType is WHERE_DISTINCT_ORDERED.
142696 ** sometimes codeDistinct is called before the OP_OpenEphemeral is actually
142702 ** No adjustments necessary. This function is a no-op.
142706 ** The ephemeral table is not needed. So change the
142711 ** The ephemeral table is not needed. But we do need register
142733 ** the loop even if the first row is all NULLs. */
142744 ** This function is called as part of inner-loop generation for a SELECT
142745 ** statement with an ORDER BY that is not optimized by an index. It
142748 ** is used for SELECT queries like:
142752 ** If the optimization is used for expression "bigblob", then instead of
142754 ** the row from table t1 is stored instead. Then, as records are extracted from
142755 ** the sorter to return to the user, the required value of bigblob is
142759 ** The ExprList_item.fg.bSorterRef flag is set for each expression in pEList
142761 ** Additionally, the pSort->aDefer[] array is populated with entries
142763 ** output variable (*ppExtra) is set to an expression list containing
142832 ** If srcTab is negative, then the p->pEList expressions
142833 ** are evaluated in order to get the data for this row. If srcTab is
142834 ** zero or more, then data is pulled from srcTab and p->pEList is used only
142849 int hasDistinct; /* True if the DISTINCT keyword is present */
142856 /* Usually, regResult is the first cell in an array of memory cells
142857 ** containing the current result row. In this case regOrig is set to the
142860 ** from this array. In this case regOrig is set to zero. */
142886 /* This is an error condition that can result, for example, when a SELECT
142889 ** and reported later. But we need to make sure enough memory is allocated
142904 /* If the destination is an EXISTS(...) expression, the actual
142907 u8 ecelFlags; /* "ecel" is an abbreviation of "ExprCodeExprList" */
142915 /* For each expression in p->pEList that is a copy of an expression in
142934 ** instruction to account for the larger records. This is only
143040 ** that this is an "UPDATE ... FROM" on a virtual table or view. In this
143050 /* If the destination is DistFifo, then cursor (iParm+1) is open
143051 ** on an ephemeral index. If the current row is already present
143084 /* If the UPDATE FROM join is an aggregate that matches no rows, it
143085 ** might still be trying to return one row, because that is what
143133 /* If this is a scalar select that is part of an expression, then
143167 /* Write the results into a priority queue that is order according to
143168 ** pDest->pOrderBy (in pSO). pDest->iSDParm (in iParm) is the cursor for an
143171 ** final OP_Sequence column. The last column is the record as a blob.
143186 /* If the destination is DistQueue, then cursor (iParm+1) is open
143216 /* Discard the results. This is used for SELECT statements inside
143217 ** the body of a TRIGGER. The purpose of such selects is to call
143228 /* Jump to the end of the loop if the LIMIT is reached. Except, if
143229 ** there is a sorter, in which case the sorter has already limited
143284 ** can only be changed if this is just a single reference to the object.
143286 ** This routine is used only inside of assert() statements.
143295 ** If the ExprList is an ORDER BY or GROUP BY clause then the resulting
143296 ** KeyInfo structure is appropriate for initializing a virtual index to
143297 ** implement that clause. If the ExprList is the result set of a SELECT
143298 ** then the KeyInfo structure is appropriate for initializing a virtual
143301 ** Space to hold the KeyInfo structure is obtained from malloc. The calling
143302 ** function is responsible for seeing that this structure is eventually
143345 ** Unless an "EXPLAIN QUERY PLAN" command is being processed, this function
143346 ** is a no-op. Otherwise, it adds a single row of output to the EQP result,
143347 ** where the caption is of the form:
143351 ** where xxx is one of "DISTINCT", "ORDER BY" or "GROUP BY". Exactly which
143352 ** is determined by the zUsage argument.
143360 ** is provided when SQLITE_OMIT_EXPLAIN is defined. This allows the code
143362 ** only exist if SQLITE_OMIT_EXPLAIN is not defined without polluting the
143376 ** then the results were placed in a sorter. After the loop is terminated
143598 ** The declaration type is the exact datatype definition extracted from the
143599 ** original CREATE TABLE statement if the expression is a column. The
143600 ** declaration type for a ROWID field is INTEGER. Exactly when an expression
143601 ** is considered a column can be complex in the presence of subqueries. The
143602 ** result-set expression in all of the following SELECT statements is
143610 ** The declaration type for any expression other than a column is NULL.
143613 ** the SQLITE_ENABLE_COLUMN_METADATA compile-time option is used.
143643 /* The expression is a column. Locate the table the column is being
143647 Table *pTab = 0; /* Table structure column is extracted from */
143648 Select *pS = 0; /* Select the column is extracted from */
143664 ** trigger code is generated and so this condition is no longer
143671 ** when columnType() is called on the expression "t1.col" in the
143675 ** This is not a problem, as the column type of "t1.col" is never
143676 ** used. When columnType() is called on the expression
143677 ** "(SELECT t1.col)", the correct type is returned (see the TK_SELECT
143684 /* The "table" is actually a sub-select or a view in the FROM clause
143695 /* If iCol is less than zero, then the expression requests the
143696 ** rowid of the sub-select or view. This expression is legal (see
143737 /* The expression is a sub-select. Return the declaration type and
143793 ** column specific strings, in case the schema is reset before this
143794 ** virtual machine is deleted.
143811 ** The only guarantee that SQLite makes about column names is that if the
143813 ** That is the only documented guarantee. However, countless applications
143821 ** deprecated. The default setting is short=ON, full=OFF. 99.9% of all
143825 ** short=OFF, full=OFF: Column name is the text of the expression has it
143829 ** short=ON, full=OFF: (This is the default setting). If the result
143831 ** result column name is just the table column
143848 int fullName; /* TABLE.COLUMN if no AS clause and is a direct table ref */
143849 int srcName; /* COLUMN or TABLE.COLUMN if no AS clause and is direct */
143903 ** Given an expression list (which is really the list of expressions
143915 ** The only guarantee that SQLite makes about column names is that if the
143917 ** That is the only documented guarantee. However, countless applications
143990 /* Make sure the column name is unique. If the name is not unique,
144033 ** pTab is a transient Table object that represents a subquery of some
144184 ** the limit and offset. If there is no limit and/or offset, then
144188 ** a limit or offset is defined by pLimit->pLeft and pLimit->pRight. iLimit
144192 ** The iOffset register (if it exists) is initialized to the value
144193 ** of the OFFSET. The iLimit register is initialized to LIMIT. Register
144194 ** iOffset+1 is initialized to LIMIT+OFFSET.
144211 ** "LIMIT -1" always shows all rows. There is some
144255 ** The collating sequence for the compound select is taken from the
144276 ** The select statement passed as the second parameter is a compound SELECT
144280 ** Space to hold the KeyInfo structure is obtained from malloc. The calling
144281 ** function is responsible for ensuring that this structure is eventually
144323 ** There is exactly one reference to the recursive-table in the FROM clause
144328 ** one. Each row extracted from Queue is output to pDest. Then the single
144331 ** is added back into the Queue table. Then another row is extracted from Queue
144332 ** and the iteration continues until the Queue table is empty.
144334 ** If the compound query operator is UNION then no duplicate rows are ever
144337 ** discarded. If the operator is UNION ALL, then duplicates are allowed.
144340 ** ORDER BY order and the first entry is extracted for each cycle. Without
144341 ** an ORDER BY, the Queue table is just a FIFO.
144343 ** If a LIMIT clause is provided, then the iteration stops after LIMIT rows
144345 ** negative LIMIT means to output all rows. If there is also an OFFSET clause
144439 ** iDistinct table. pFirstRec is left pointing to the left-most
144491 /* Keep running the loop until the Queue is empty */
144517 ** (1) There is no LIMIT or OFFSET or else there is a LIMIT of exactly 1
144519 ** (3) There is no ORDER BY clause
144524 ** Since the limit is exactly 1, we only need to evaluate the left-most VALUES.
144559 ** Return true if the SELECT statement which is known to be the recursive
144569 ** This routine is called to process a compound query form from
144574 ** left is p->pPrior. The left query could also be a compound query
144584 ** This statement is parsed up as follows:
144593 ** So if this routine is called with p equal to the t3 query, then
144611 /* Make sure there is no ORDER BY or LIMIT clause on prior SELECTs. Only
144784 ** it is that we currently need.
144812 /* INTERSECT is different from the others since it requires
144894 ** This section is run by the right-most SELECT statement only.
144925 /* If [0] is unused then [1] is also unused. So we can
144926 ** always safely abort as soon as the first unused slot is found */
144967 ** The data to be output is contained in pIn->iSdst. There are
144968 ** pIn->nSdst columns to be output. pDest is where the output should
144971 ** regReturn is the number of the register holding the subroutine
144974 ** If regPrev>0 then it is the first register in a vector that
144975 ** records the previous output. mem[regPrev] is a flag that is false
144976 ** if there has been no previous output. If regPrev>0 then code is
144977 ** generated to suppress duplicates. pKeyInfo is used for comparing
144980 ** If the LIMIT found in p->iLimit is reached, jump immediately to
145014 /* Suppress the first OFFSET entries if there is an OFFSET clause
145050 /* If this is a scalar select that is part of an expression, then
145053 ** if it is the RHS of a row-value IN operator.
145077 ** SRT_Output. This routine is never called with any other
145081 ** Then the OP_ResultRow opcode is used to cause sqlite3_step() to
145091 /* Jump to the end of the loop if the LIMIT is reached.
145107 ** is an ORDER BY clause.
145113 ** <operator> is one of UNION ALL, UNION, EXCEPT, or INTERSECT. The idea
145114 ** is to code both <selectA> and <selectB> with the ORDER BY clause as
145127 ** AltB: Called when there is data from both coroutines and A<B.
145129 ** AeqB: Called when there is data from both coroutines and A==B.
145131 ** AgtB: Called when there is data from both coroutines and A>B.
145133 ** EofA: Called when data is exhausted from selectA.
145135 ** EofB: Called when data is exhausted from selectB.
145138 ** <operator> is used:
145158 ** Duplicate removal in the UNION, EXCEPT, and INTERSECT cases is handled
145160 ** output value. A comparison is made against this value and the output
145161 ** is skipped if the next results would be the same as the previous.
145163 ** The implementation plan is to implement the two coroutines and seven
145187 ** until all data is exhausted then jump to the "end" label. AltB, AeqB,
145212 int addrEofA_noB; /* Alternate addrEofA if B is uninitialized */
145273 /* Compute the comparison permutation and keyinfo that is used with
145297 ** operator is UNION, EXCEPT, or INTERSECT (but not UNION ALL).
145520 ** target slot in the parent is the right operand of a LEFT JOIN, or one of
145524 ** Suppose the original expression is an integer constant. Even though the table
145525 ** has the nullRow flag set, because the expression is an integer constant,
145527 ** that checks to see if the nullRow flag is set on the table. If the nullRow
145528 ** flag is set, then the value in the register is set to NULL and the original
145529 ** expression is bypassed. If the nullRow flag is not set, then the original
145532 ** Example where this is needed:
145539 ** When the subquery on the right side of the LEFT JOIN is flattened, we
145563 ** This routine is part of the flattening procedure. A subquery
145564 ** whose result set is defined by pEList appears as entry in the
145566 ** FORM clause entry is iTable. This routine makes the necessary
145713 ** pSelect is a SELECT statement and pSrcItem is one item in the FROM
145751 ** The array is guaranteed by the caller to be large enough for all
145752 ** existing cursor numbers in pSrc. aCsrMap[0] is the array size.
145781 ** *piCursor is a cursor number. Change it if it needs to be mapped.
145814 ** Argument aCsrMap is an array that may be used for temporary working
145817 ** * the array is larger than the largest cursor number used within the
145841 ** If pSel is not part of a compound SELECT, return a pointer to its
145890 ** The default way of implementing this query is to execute the
145907 ** Flattening is subject to the following constraints:
145913 ** (2) If the subquery is an aggregate then
145916 ** other than the one FROM-clause subquery that is a candidate
145917 ** for flattening. (This is due to ticket [2f7170d73bf9abf80]
145920 ** (3) If the subquery is the right operand of a LEFT JOIN then
145925 ** is now managed correctly
145936 ** If the subquery is aggregate, the outer query may not be DISTINCT.
145949 ** constraint: "If the subquery is aggregate then the outer query
145961 ** (15) If the outer query is part of a compound select, then the
145965 ** (16) If the outer query is aggregate, then the subquery may not
145969 ** (17) If the subquery is a compound select, then
145979 ** (17g) either the subquery is the first element of the outer
145981 ** of the subquery. (This is a duplicate of condition (27b).)
145989 ** operators have an implied DISTINCT which is disallowed by
145993 ** of result columns. This is actually a requirement for any compound
145994 ** SELECT statement, but all the code here does is make sure that no
145995 ** such (illegal) sub-query is flattened. The caller will detect the
145998 ** (18) If the sub-query is a compound select, then all terms of the
146005 ** (20) If the sub-query is a compound select, then it must not use
146016 ** (23) If the outer query is a recursive CTE, then the sub-query may not be
146017 ** a compound query. This restriction is because transforming the
146029 ** is not attempted.
146035 ** is the first element of the parent query. Two subcases:
146036 ** (27a) the subquery is not a compound query.
146037 ** (27b) the subquery is a compound query and the RIGHT JOIN occurs
146040 ** (28) The subquery is not a MATERIALIZED CTE. (This is handled
146044 ** In this routine, the "p" parameter is a pointer to the outer query.
146045 ** The subquery is p->pSrc->a[iFrom]. isAgg is true if the outer query
146048 ** If flattening is not attempted, this routine is a no-op and returns 0.
146049 ** If flattening is attempted this routine returns 1.
146068 int isOuterJoin = 0; /* True if pSub is the right side of a LEFT JOIN */
146076 /* Check to see if flattening is permitted. Return 0 if not.
146122 ** If the subquery is the right operand of a LEFT JOIN, then the
146123 ** subquery may not be a join itself (3a). Example of why this is not
146132 ** which is not at all the same thing.
146152 /* Condition (28) is blocked by the caller */
146155 /* Restriction (17): If the sub-query is a compound SELECT, then it must
146185 ** omitted on left-hand tables of the right join that is being
146213 /***** If we reach this point, flattening is permitted. *****/
146234 /* If the sub-query is a compound SELECT statement, then (by restrictions
146243 ** using UNION ALL operators. In this case N is the number of simple
146305 ** subquery until code generation is
146309 ** pSubitem->pTab is always non-NULL by test restrictions and tests above.
146360 ** outer query (the middle slot) is used by the subquery. The next
146362 ** The middle slot is expanded to two slots in order to make space
146400 ** ORDER BY column expression is identical to the iOrderByCol'th
146407 ** (the only way this can happen is if the compound sub-query is
146440 /* The flattened query is a compound if either the inner or the
146441 ** outer query is a compound. */
146448 ** One is tempted to try to add a and b to combine the limits. But this
146449 ** does not work if either limit is negative.
146463 /* Finally, delete what is left of the subquery and return success.
146489 int nChng; /* Number of times a constant is propagated */
146493 Expr **apExpr; /* [i*2] is COLUMN and [i*2+1] is VALUE */
146500 ** The caller guarantees the pColumn is a column and pValue is a constant.
146521 ** Make sure the same pColumn is not inserted more than once */
146548 ** is a constant expression and where the term must be true because it
146549 ** is part of the AND-connected terms of the expression. For each term
146579 ** This is a helper function for Walker callback propagateConstantExprRewrite().
146581 ** Argument pExpr is a candidate expression to be replaced by a value. If
146582 ** pExpr is equivalent to one of the columns named in pWalker->u.pConst,
146584 ** if argument bIgnoreAffBlob is non-zero and the affinity of pExpr
146585 ** is SQLITE_AFF_BLOB.
146609 /* A match is found. Add the EP_FixedCol property */
146622 ** This is a Walker expression callback. pExpr is a node from the WHERE
146627 ** A substitution is made if:
146629 ** + pExpr is a column with an affinity other than BLOB that matches
146632 ** + pExpr is a binary comparison operator (=, <=, >=, <, >) that
146634 ** children is a column that matches one of the columns in
146675 ** Implementation note: Constant propagation is tricky due to affinity
146684 ** is always true because the comparison uses numeric affinity, but b=123
146685 ** is false because it uses text affinity and '0123' is not the same as '123'.
146686 ** To work around this, the expression tree is not actually changed from
146687 ** "b=a" to "b=123" but rather the "a" in "b=a" is tagged with EP_FixedCol
146688 ** and the "123" value is hung off of the pLeft pointer. Code generator
146690 ** column value. Also, to avoid collation problems, this optimization is
146693 ** 2021-05-25 forum post 6a06202608: Another troublesome case is...
146699 ** The query should return no rows, because the t1.x value is '10.0' not '10'
146700 ** and '10.0' is not LIKE '10'. But if we are not careful, the first WHERE
146703 ** columns with BLOB affinity is only allowed if the constant is used with
146726 /* Do not propagate constants on any ON clause if there is a
146753 ** This function is called to determine whether or not it is safe to
146756 ** if it is safe and the expression should be pushed down, or 0
146759 ** It is only safe to push the expression down if it consists only
146761 ** BY clause of all window function used by the sub-query. It is safe
146765 ** At the time this function is called it is guaranteed that
146791 ** The hope is that the terms added to the inner query will make it more
146798 ** it is allowed by putting the extra terms on the HAVING clause.
146799 ** The added HAVING clause is pointless if the subquery lacks
146800 ** a GROUP BY clause. But such a HAVING clause is also harmless
146804 ** (2) The inner query is the recursive part of a common table expression.
146809 ** (4) The inner query is the right operand of a LEFT JOIN and the
146814 ** of a LEFT JOIN where iCursor is not the right-hand table of that
146822 ** The correct answer is three rows: (1,1,NULL),(2,2,8),(2,2,9).
146833 ** (6b) The inner query is a compound and uses window-functions.
146837 ** all window-functions used by the sub-query. It is safe to
146839 ** window over which any window-function is calculated.
146841 ** (7) The inner query is a Common Table Expression (CTE) that should
146842 ** be materialized. (This restriction is implemented in the calling
146845 ** (8) If the subquery is a compound that uses UNION, INTERSECT,
146854 ** (9b) The subquery is to the right of the ON/USING clause
146856 ** (9c) There is a RIGHT JOIN (or FULL JOIN) in between the ON/USING
146864 ** (10) The inner query is not the right-hand table of a RIGHT JOIN.
146866 ** (11) The subquery is not a VALUES clause
146873 Select *pSubq, /* The subquery whose WHERE clause is to be augmented */
146879 SrcItem *pSrc; /* The subquery FROM term into which WHERE is pushed */
147045 ** use UNION, INTERSECT, or EXCEPT. Only UNION ALL is allowed. */
147085 ** The pFunc is the only aggregate function in the query. Check to see
147086 ** if the query is a candidate for the min/max optimization.
147088 ** If the query is a candidate for the min/max optimization, then set
147091 ** whether pFunc is a min() or max() function.
147093 ** If the query is not a candidate for the min/max optimization, return
147139 ** The select statement passed as the first argument is an aggregate query.
147140 ** The second argument is the associated aggregate-info object. This
147141 ** function tests if the SELECT is of the form:
147145 ** where table is a database table, not a sub-select or view. If the query
147147 ** <tbl> is returned. Otherwise, NULL is returned.
147149 ** This routine checks to see if it is safe to use the count optimization.
147150 ** A correct answer is still obtained (though perhaps more slowly) if
147226 ** This transformation is necessary because the multiSelectOrderBy() routine
147232 ** This transformation is only needed for EXCEPT, INTERSECT, and UNION.
147252 /* If iOrderByCol is already non-zero, then it has already been matched
147254 ** SELECT is rewritten for window-functions processing and then passed
147256 ** by this function is not required in this case. */
147264 /* If we reach this point, that means the transformation is required. */
147299 ** non-zero, since pFrom is not allowed to be a table-valued function.
147303 sqlite3ErrorMsg(pParse, "'%s' is not a function", pFrom->zName);
147313 ** FROM clause element pItem is really a common-table-expression (CTE)
147317 ** If a non-NULL value is returned, set *ppContext to point to the With
147346 ** onto the top of the stack. If argument bFree is true, then this
147350 ** statement with which it is associated.
147352 ** This routine returns a copy of pWith. Or, if bFree is true and
147353 ** the pWith object is destroyed immediately due to an OOM condition,
147356 ** If bFree is true, do not continue to use the pWith pointer after
147379 ** CTE expression, through routine checks to see if the reference is
147385 ** Return 0 if no match is found.
147386 ** Return 1 if a match is found.
147387 ** Return 2 if an error condition is detected.
147399 /* There are no WITH clauses in the stack. No match is possible */
147413 /* The FROM term is specifically excluded from matching a CTE.
147414 ** (1) It is part of a trigger that used to have zDatabase but had
147416 ** (2) This is the first term in the FROM clause of an UPDATE.
147433 /* If pCte->zCteErr is non-NULL at this point, then this is an illegal
147435 ** early. If pCte->zCteErr is NULL, then this is not a recursive reference.
147475 /* Check if this is a recursive CTE. */
147566 ** This function is used as the xSelectCallback2() callback by
147586 ** SQLITE_OK is returned. Otherwise, if an OOM error is encountered,
147621 ** If N is zero, or none of the N SrcItem objects to the right of pBase
147642 ** This routine is a Walker callback for "expanding" a SELECT statement.
147651 ** that implements the view. A copy is made of the view's SELECT
147707 ** an entry of the FROM clause is a subquery instead of a table or view,
147843 /* This expression is a "*" or a "TABLE.*" and needs to be
147921 /* If pTab is actually an SF_NestedFrom sub-select, do not
147934 /* If a column is marked as 'hidden', omit it from the expanded
148050 ** xSelectCallback2 is never invoked.
148062 ** Expanding a SELECT statement is the first step in processing a
148064 ** name resolution is performed.
148066 ** If anything goes wrong, an error message is written into pParse.
148088 ** This is a Walker.xSelectCallback callback for the sqlite3SelectTypeInfo()
148098 ** This routine is called after identifier resolution.
148148 ** following is accomplished:
148207 ** would throw an error if there is a column reference that is not in the
148208 ** GROUP BY clause and that is not part of an aggregate function argument.
148213 ** aggregate functions. This routine is responsible for computing
148245 ** An index on expressions is being used in the inner loop of an
148314 ** those expressions that has pAppInfo set is changed into a TK_AGG_COLUMN
148329 ** Allocate a block of registers so that there is one register for each
148331 ** register in this block is stored in pAggInfo->iFirstReg.
148355 ** The aggregate accumulator is a set of memory cells that hold
148487 ** If regAcc is non-zero and there are no min() or max() aggregates
148493 ** is deferred until after all input rows have been received, so that they
148536 /* If this is the first row of the group (regAcc contains 0), clear the
148539 ** invocation of min() or max() altogether. Or, if this is not
148541 ** the accumulators are not populated unless the min()/max() is invoked
148684 ** If the node passed to the callback is a TK_AND node, return
148695 /* This routine is called before the HAVING clause of the current
148696 ** SELECT is analyzed for aggregates. So if pExpr->pAggInfo is set
148697 ** here, it indicates that the expression is a correlated reference to a
148722 ** Transfer eligible terms from the HAVING clause of a query, which is
148723 ** processed after grouping, to the WHERE clause, which is processed before
148732 ** A term of the HAVING expression is eligible for transfer if it consists
148752 ** Check to see if the pThis entry of pTabList is a self-join of another view.
148756 ** If pThis is a self-join, then return the SrcItem for the first other
148757 ** instance of that view found. If pThis is not a self-join then return 0.
148814 ** * The subquery is a UNION ALL of two or more terms
148816 ** * There is no WHERE or GROUP BY or HAVING clauses on the subqueries
148817 ** * The outer query is a simple count(*) with no WHERE clause or other
148820 ** Return TRUE if the optimization is undertaken.
148827 if( (p->selFlags & SF_Aggregate)==0 ) return 0; /* This is an aggregate */
148834 if( pExpr->op!=TK_AGG_FUNCTION ) return 0; /* Result is an aggregate */
148842 if( pSub==0 ) return 0; /* The FROM is a subquery */
148854 /* If we reach this point then it is OK to perform the transformation */
148896 ** If any term of pSrc, or any SF_NestedFrom sub-query, is not the same
148920 ** be implemented as a co-routine. The i-th entry is guaranteed to be
148923 ** The subquery is implemented as a co-routine if all of the following are
148929 ** (a) The subquery is the only term in the FROM clause
148930 ** (b) The subquery is the left-most term and a CROSS JOIN or similar
148933 ** (i) The subquery is the left-most subquery in the FROM clause
148934 ** (ii) There is nothing that would prevent the subquery from
148937 ** (iii) The query is not a UPDATE ... FROM
148938 ** (2) The subquery is not a CTE that should be materialized because
148939 ** (a) the AS MATERIALIZED keyword is used, or
148940 ** (b) the CTE is used multiple times and does not have the
148942 ** (3) The subquery is not part of a left operand for a RIGHT JOIN
148943 ** (4) The SQLITE_Coroutine optimization disable flag is not set
148944 ** (5) The subquery is not self-joined
148987 ** encountered, then an appropriate error message is left in
149072 /* If the SF_UFSrcCheck flag is set, then this function is being called
149074 ** In this case, it is an error if the target object (pSrc->a[0]) name
149075 ** or alias is duplicated within FROM clause (pSrc->a[1..n]).
149077 ** Postgres disallows this case too. The reason is that some other
149079 ** which is just confusing. To avoid this, we follow PG's lead and
149093 ** in p->pSrc is flattened into this query and this function called
149141 ** perform the appropriate simplification. This is called
149184 /* No further action if this term of the FROM clause is not a subquery */
149197 ** a MATERIALIZED common table expression is an optimization fence.
149205 ** Flattening an aggregate subquery is only possible if the outer query
149206 ** is not a join. But if the outer query is not a join, then the subquery
149207 ** will be implemented as a co-routine and there is no advantage to
149213 /* If a FROM-clause subquery has an ORDER BY clause that is not
149221 ** (1) There is also a LIMIT clause
149224 ** (3) The subquery is in the FROM clause of an UPDATE
149230 ** (b) The subquery is part of a join
149233 ** Also retain the ORDER BY if the OmitOrderBy optimization is disabled.
149249 /* If the outer query contains a "complex" result set (that is,
149258 ** The expensive_function() is only computed on the 10 rows that
149306 /* Do the WHERE-clause constant propagation optimization if this is
149354 ** The fake column name is an empty string. It is possible for a table to
149355 ** have a column named by the empty string, in which case there is no way to
149359 ** assume the column name is non-NULL and segfault. The use of an empty
149378 ** (SQLITE_MAX_EXPR_DEPTH-Parse.nHeight) height. This is a bit
149445 /* This is a CTE for which materialization code has already been
149465 /* Materialize the view. If the view is not correlated, generate a
149479 /* If the subquery is not correlated and if we are not inside of
149527 /* If the query is DISTINCT with an ORDER BY but is not an aggregate, and
149528 ** if the select-list is the same as the ORDER BY list, then this query
149533 ** is transformed to:
149537 ** The second form is preferred as a single index (or temp-table) may be
149552 ** the sDistinct.isTnct is still set. Hence, isTnct represents the
149565 /* If there is an ORDER BY clause, then create an ephemeral index to
149568 ** If that is the case, then the OP_OpenEphemeral instruction will be
149569 ** changed to an OP_Noop once we figure out that the sorting index is
149570 ** not needed. The sSort.addrSortIndex variable is used to facilitate
149587 /* If the output is destined for a temporary table, open that table.
149736 /* If there is both a GROUP BY and an ORDER BY clause and they are
149747 ** ASC or DESC order - only that each group is returned contiguously.
149824 /* Processing for aggregates with GROUP BY is very different and
149854 /* If there is a GROUP BY clause we might need a sorting index to
149904 /* The optimizer is able to deliver rows in group by order so
149974 ** is correctly pulled from the index rather than being recomputed. */
149991 ** This is an optimization - the correct answer should result regardless.
150002 ** (b0 is memory location iBMem+0, b1 is iBMem+1, and so forth)
150026 ** block. If there were no changes, this block is skipped.
150072 ** is less than or equal to zero, the subroutine is a no-op. If
150112 ** the SQL statement is of the form:
150118 ** This statement is so common that it is optimized specially. The
150119 ** OP_Count instruction is executed either on the intkey table that
150121 ** is better to execute the op on an index, as indexes are almost
150140 ** In practice the KeyInfo structure will not be used. It is only
150205 ** processing is much simpler since there is only a single row
150211 /* If this query is a candidate for the min/max optimization, then
150257 /* If there is an ORDER BY clause, then we need to sort the results
150269 /* The SELECT has been coded. If there is an error in the Parse structure,
150273 /* Control jumps to here if an error is encountered above, or upon
150313 ** a legal notice, here is a blessing:
150332 ** This structure is used to pass data from sqlite3_get_table() through
150333 ** to the callback function is uses to build the result.
150346 ** This routine is called once for each row in the result table. Its job
150347 ** is to fill in the TabResult structure appropriately, allocating new
150356 /* Make sure there is enough space in p->azResult to hold everything
150372 /* If this is the first row, then generate an extra row containing
150419 ** The result that is written to ***pazResult is held in memory obtained
150422 ** the calling procedure is finished using it.
150466 db->errCode = res.rc; /* Assume 32-bit assignment is atomic */
150513 ** a legal notice, here is a blessing:
150547 ** the table. The list is connected by Trigger.pNext pointers.
150605 ** This is called by the parser when it sees a CREATE TRIGGER statement
150607 ** structure is generated based on the information available and stored
150609 ** sqlite3FinishTrigger() function is called to complete the trigger
150618 IdList *pColumns, /* column list if this is an UPDATE OF trigger */
150621 int isTemp, /* True if the TEMPORARY keyword is present */
150655 /* A long-standing parser bug is that this syntax was allowed:
150668 /* If the trigger name was unqualified, and the table is a temp table,
150671 ** exist, the error is caught by the block below.
150700 /* Check that the trigger name is not reserved and that no trigger of the
150806 ** Normally, whenever a table is dropped, all associated triggers are
150807 ** dropped too. But if a TEMP trigger is created on a non-TEMP table
150808 ** and the table is dropped by a different database connection, the
150809 ** trigger is not visible to the database connection that does the
150811 ** "orphaned trigger" - a trigger whose associated table is missing.
150821 ** This routine is called after all of the trigger actions have been parsed
150868 /* If this is a new CREATE TABLE statement, and if shadow tables
150965 ** If an OOM error occurs, NULL is returned and db->mallocFailed is set.
151123 ** This function is called to drop a trigger from the database schema.
151170 ** is set on.
151244 ** pEList is the SET clause of an UPDATE statement. Each entry
151245 ** in pEList is of the format <id>=<expr>. If any of the entries
151247 ** then return TRUE. If pIdList==NULL, then it is considered a
151250 ** if there is no match.
151272 ** one trigger that must be fired when an operation of type 'op' is
151273 ** performed on the table, and, if that operation is an UPDATE, if at
151274 ** least one of the columns in pChanges is being modified.
151295 /* The SQLITE_DBCONFIG_ENABLE_TRIGGER setting is off. That means that
151310 /* The first time a RETURNING trigger is seen, the "op" value tells
151317 "%s RETURNING is not available on virtual tables",
151362 ** referring to a target in another database. An exception is when the
151363 ** trigger is in TEMP in which case it can refer to any other database it
151402 ** list is of the form "*". Raise an error if the terms if of the
151419 /* The input list pList is the list of result set terms from a RETURNING
151420 ** clause. The table that we are returning from is pTab.
151466 ** is generated in-line.
151490 /* This RETURNING trigger is for a different statement */
151634 ** This function is used to add VdbeComment() annotations to a VDBE
151635 ** program. It is not used in production code, only for debugging.
151674 Table *pTab, /* The table pTrigger is attached to */
151684 int iEndTrigger = 0; /* Label to jump to if WHEN is false */
151736 ** (or NULL) the sub-vdbe is immediately halted by jumping to the
151782 ** TriggerPrg object exists, a new object is allocated and populated before
151788 Table *pTab, /* The table trigger pTrigger is attached to */
151796 /* It may be that this trigger has already been coded (or is in the
151797 ** process of being coded). If this is the case, then an entry with
151834 ** is a pointer to the sub-vdbe containing the trigger program. */
151844 ** recursive invocation of this trigger program is disallowed. Recursive
151845 ** invocation is disallowed if (a) the sub-program is really a trigger,
151847 ** is clear. */
151853 ** This is called to code the required FOR EACH ROW triggers for an operation
151855 ** is given by the op parameter. The tr_tm parameter determines whether the
151856 ** BEFORE or AFTER triggers are coded. If the operation is an UPDATE, then
151857 ** parameter pChanges is passed the list of columns being modified.
151860 ** operation on pTab, this function is a no-op.
151862 ** The reg argument is the address of the first in an array of registers
151864 ** in the trigger program. If N is the number of columns in table pTab
151880 ** populated by the caller (there is no data to populate them with anyway).
151884 ** is not a readable register, although registers (reg+N) through
151887 ** Parameter orconf is the default conflict resolution algorithm for the
151889 ** is the instruction that control should jump to if a trigger program
151920 ** 1. The trigger is an exact match to the current DML statement
151921 ** 2. This is a RETURNING trigger for INSERT but we are currently
151944 ** Bit 0 of the returned mask is set if the left-most column of the
151945 ** table may be accessed using an [old|new].<col> reference. Bit 1 is set if
151946 ** the second leftmost column value is required, and so on. If there
151948 ** with an index greater than 32 may be accessed, 0xffffffff is returned.
151950 ** It is not possible to determine if the old.rowid or new.rowid column is
151951 ** accessed by triggers. The caller must always assume that it is.
151953 ** Parameter isNew must be either 1 or 0. If it is 0, then the mask returned
151958 ** included in the returned mask if the TRIGGER_BEFORE bit is set in the
151960 ** included in the returned mask if the TRIGGER_AFTER bit is set in tr_tm.
152007 ** a legal notice, here is a blessing:
152038 ** The default value of a column is specified by a DEFAULT clause in the
152043 ** from the P4 parameter of the OP_Column instruction, is returned instead.
152045 ** for the column and the P4 value is not required.
152049 ** complicated default expression value was provided, it is evaluated
152050 ** when the ALTER TABLE is executed and one of the literal values written
152053 ** Therefore, the P4 parameter is only required if the default value for
152054 ** the column is a literal number, string or null. The sqlite3ValueFromExpr()
152055 ** function is capable of transforming these types of expressions into
152058 ** If column as REAL affinity and the table is an ordinary b-tree table
152091 ** and false if not. This is an optimization. False-positives are a
152095 ** aXRef[j] will be non-negative if column j of the original table is
152096 ** being updated. chngRowid will be true if the rowid of the table is
152102 int *aXRef, /* aXRef[j]>=0 if column j is being updated */
152103 int chngRowid /* true if the rowid is being updated */
152118 ** Check to see if index pIdx is a partial index whose conditional
152120 ** the index is subject to change and false if the index is guaranteed
152121 ** to be unchanged. This is an optimization. False-positives are a
152125 ** aXRef[j] will be non-negative if column j of the original table is
152126 ** being updated. chngRowid will be true if the rowid of the table is
152131 int *aXRef, /* aXRef[j]>=0 if column j is being updated */
152132 int chngRowid /* true if the rowid is being updated */
152161 ** Or, if pLimit and pOrderBy are not NULL, and pTab is not a view:
152168 ** If pTab is a view, the GROUP BY clause is omitted.
152171 ** the <other-columns> in the query above are is determined by the type
152174 ** If the table is a WITHOUT ROWID table, then argument pPk must be its
152179 ** If the table is actually a view, then <other-columns> are all columns of
152183 ** If the table is a virtual or ordinary intkey table, then <other-columns>
152184 ** is its rowid. For a virtual table, the results are written to iEph as
152186 ** rowid value in <other-columns> is used as the integer key, and the
152192 Index *pPk, /* PK if table 0 is WITHOUT ROWID */
152311 int *aXRef = 0; /* aXRef[i] is the index in pChanges->a[] of the
152313 ** aXRef[i]==-1 if the i-th column is not changed. */
152324 int hasFK; /* True if foreign key processing is required */
152342 int bFinishSeek = 1; /* The OP_FinishSeek opcode is needed */
152343 int nChangeFrom = 0; /* If there is a FROM, pChanges->nExpr, else 0 */
152369 ** updated is a view.
152395 ** clause if this function is being called to generate code for part of
152471 /* If this is an UPDATE with a FROM clause, do not resolve expressions
152535 ** generated expressions is not used, other than to check to see that it
152536 ** is non-negative, so the value of aXRef[] for generated columns can be
152537 ** set to any non-negative number. We use 99999 so that the value is
152562 ** So reset the colUsed mask. Unless this is a virtual table. In that
152570 /* There is one entry in the aRegIdx[] array for each index on the table
152612 ** reallocated. aRegIdx[nAllIdx] is the register in which the main
152613 ** table record is written. regRowSet holds the RowSet for the
152719 /* If this is an UPSERT, then all cursors have already been opened by
152721 ** that is to be updated. So bypass the code that searches for the
152732 ** there is anything that might disrupt the cursor being used to do
152734 ** (1) This is a nested UPDATE
152754 ** be used if any column of the index used for the scan is being
152755 ** updated. Otherwise, if there is an index on "b", statements like
152793 ** is not required) and leave the PK fields in the array of registers. */
152891 ** contain the new value. If the rowid is not being modified,
152892 ** then regNewRowid is the same register as regOldRowid, which is
152906 ** information is needed */
152931 ** row data. This array is used to check constants, create the new
152963 ** into a register. This is done if there are no BEFORE triggers, or
152985 ** verified. One could argue that this is wrong.
152996 ** is deleted or renamed by a BEFORE trigger - is left undefined in the
153041 ** row is changing, then the GenerateConstraintChecks() above may have
153061 ** OP_DeferredSeek if there is any possibility that there have been
153073 ** That (regNew==regnewRowid+1) is true is also important for the
153075 ** value is copied from memory cell (regNewRowid+1+iCol), where iCol
153076 ** is the column index supplied by the user.
153184 ** "onepass" strategy. Onepass is only used if the virtual table
153187 ** The default strategy is to create an ephemeral table that contains
153313 /* There is no ONEPASS_MULTI on virtual tables */
153327 /* Signal an assert() within OP_MakeRecord that it is allowed to
153375 ** a legal notice, here is a blessing:
153457 ** Return SQLITE_OK if everything works, or an error code is something
153458 ** is wrong.
153503 /* The conflict-target is the rowid of the primary table */
153584 ** Return true if pUpsert is the last ON CONFLICT clause with a
153585 ** conflict target, or if pUpsert is followed by another ON CONFLICT
153601 ** clause that applies to the index. Or, if the index is not subject to
153618 ** If pIdx is NULL, then the UNIQUE constraint that failed was the IPK.
153619 ** In this case parameter iCur is a cursor open on the table b-tree that
153621 ** is not NULL, then pIdx is the constraint that failed and iCur is a
153694 ** a legal notice, here is a blessing:
153765 ** The VACUUM command is used to clean up the database,
153766 ** collapse free space, etc. It is modelled after the VACUUM command
153779 ** Hence, temporary disk space that is approximately 2x the size of the
153780 ** original database is required. Every page of the database is written
153801 /* Default behavior: Report an error if the argument to VACUUM is
153806 /* When SQLITE_BUG_COMPATIBLE_20160819 is defined, unrecognized arguments
153807 ** to VACUUM are silently ignored. This is a back-out of a bug fix that
153809 ** The buggy behavior is required for binary compatibility with some
153895 ** can be set to 'off' for this file, as it is not recovered if a crash
153896 ** occurs anyway. The integrity of the database is maintained by a
153898 ** sqlite3BtreeCopyFile() is called.
153903 ** actually occurs when doing a vacuum since the vacuum_db is initially
153904 ** empty. Only the journal header is written. Apparently it takes more
153928 ** is always set. */
153938 ** file. This is done before the sqlite3BtreeGetPageSize(pMain) call below,
154003 ** associated storage, so all we have to do is copy their entries
154015 /* At this point, there is a write transaction open on both the
154028 ** The increment is used to increase the schema cookie so that other
154080 /* Currently there is an SQL level transaction open on the vacuum
154084 ** vacuum database. The vacuum_db journal file is deleted when the pager
154085 ** is closed by the DETACH.
154110 ** a legal notice, here is a blessing:
154123 ** Before a virtual table xCreate() or xConnect() method is invoked, the
154124 ** sqlite3.pVtabCtx member variable is set to point to an instance of
154125 ** this struct allocated on the stack. It is used by the implementation of
154133 int bDeclared; /* True after sqlite3_declare_vtab() is called */
154138 ** routine is called, it is guaranteed that all appropriate locks are held
154139 ** and the module is not already part of the connection.
154145 sqlite3 *db, /* Database in which module is registered */
154193 sqlite3 *db, /* Database in which module is registered */
154214 sqlite3 *db, /* Database in which module is registered */
154229 sqlite3 *db, /* Database in which module is registered */
154282 ** If an unlock is omitted, resources leaks will occur.
154284 ** If a disconnect is attempted while a virtual table is locked,
154285 ** the disconnect is deferred until all locks have been removed.
154293 ** pTab is a pointer to a Table structure representing a virtual-table.
154328 ** Table p is a virtual table. This function moves all elements in the
154331 ** Except, if argument db is not NULL, then the entry associated with
154332 ** connection db is left in the p->u.vtab.p list.
154343 ** that contains table p is held by the caller. See header comments
154370 ** Table *p is a virtual table. This function removes the VTable object
154372 ** list in p->pVTab. It also decrements the VTable ref count. This is
154400 ** caller. This is done to protect the sqlite3.pDisconnect list. The
154401 ** sqlite3.pDisconnect list is accessed only as follows:
154408 ** associated with the database the virtual table is stored in is held
154409 ** or, if the virtual table is stored in a non-sharable database, then
154410 ** the database handle mutex is held.
154413 ** by multiple threads. It is thread-safe.
154433 ** This routine is called, for example, just before deleting the Table
154436 ** Since it is a virtual-table, the Table structure contains a pointer
154438 ** structure is associated with a single sqlite3* user of the schema.
154440 ** connection db is decremented immediately (which may lead to the
154460 ** The string is not copied - the pointer is stored. The
154461 ** string will be freed automatically when the table is
154523 ** The second call, to obtain permission to create the table, is made now.
154527 assert( iDb>=0 ); /* The database the table is being created in */
154562 /* If the CREATE VIRTUAL TABLE statement is being entered for the
154563 ** first time (in other words if the virtual table is actually being
154658 ** pointer to the function to invoke is passed as the fourth parameter
154681 /* Check that the virtual-table is not already being initialized */
154793 ** This function is invoked by the parser to call the xConnect() method
154794 ** of the virtual table pTab. If an error occurs, an error code is returned
154797 ** This call is a no-op if table pTab is not a virtual table.
154832 ** Grow the db->aVTrans[] array so that there is room for at least one
154865 ** This function is invoked by the vdbe to call the xCreate method
154868 ** If an error occurs, *pzErr is set to point to an English language
154869 ** description of the error and an SQLITE_XXX error code is returned.
154896 /* Justification of ALWAYS(): The xConstructor method is required to
154909 ** This function is used to set the schema of a virtual table. It is only
155001 ** This function is invoked by the vdbe to call the xDestroy method
155003 ** when a DROP TABLE is mentioned.
155005 ** This call is a no-op if zTab is not a virtual table.
155046 ** called is identified by the second argument, "offset", which is
155049 ** The array is cleared after invoking the callbacks.
155077 ** If an error message is available, leave it in p->zErrMsg.
155117 ** (xBegin/xRollback/xCommit and optionally xSync) and a transaction is
155120 ** If the xBegin call is successful, place the sqlite3_vtab pointer
155127 /* Special case: If db->aVTrans is NULL and db->nVTrans is greater
155128 ** than zero, then this function is being called from within a
155129 ** virtual module xSync() callback. It is illegal to write to
155143 /* If pVtab is already in the aVTrans array, return early */
155173 ** If op is SAVEPOINT_BEGIN, the xSavepoint method is invoked. If it is
155174 ** SAVEPOINT_ROLLBACK, the xRollbackTo method. Otherwise, if op is
155176 ** an open transaction is invoked.
155179 ** processing is abandoned and the error returned to the caller of this
155181 ** SQLITE_OK is returned.
155222 ** The first parameter (pDef) is a function implementation. The
155223 ** second parameter (pExpr) is the first argument to this function.
155224 ** If pExpr is a column in a virtual table, then let the virtual
155227 ** This routine is used to allow virtual table implementations to
155231 ** new FuncDef structure that is marked as ephemeral using the
155248 /* Check to see the left operand is a column in a virtual table */
155299 ** Make sure virtual table pTab is contained in the pParse->apVirtualLock[]
155301 ** array if it is missing. If pTab is already in the array, this routine
155302 ** is a no-op.
155330 ** An eponymous virtual table instance is one that is named after its
155380 ** sqlite3DeleteTable() routine will know that it is not stored in
155392 ** The results of this routine are undefined unless it is called from
155466 ** a legal notice, here is a blessing:
155488 ** a legal notice, here is a blessing:
155522 ** This object is a header on a block of allocated memory that will be
155523 ** automatically freed when its WInfo object is destructed.
155531 ** Extra information attached to a WhereLevel that is a RIGHT JOIN.
155551 ** each term in the FROM clause (which is to say, for each of the
155566 int regBignull; /* big-null flag reg. True if a NULL-scan is needed */
155593 int addrVisit; /* Address at which row is visited */
155601 ** prevent a query solution - which is an error) and many terms of the
155632 u32 needFree : 1; /* True if sqlite3_free(idxStr) is needed */
155676 ** showing dependencies and costs for travelling between nodes. (That is
155679 ** one-to-one as are graph nodes. But it is a useful visualization aid.)
155680 ** Then a WherePath object is a path through the graph that visits some
155687 ** at the end is the chosen query plan.
155702 ** clause subexpression is separated from the others by AND operators,
155710 ** When a term is of the form:
155714 ** where X is a column name and <op> is one of certain operators,
155727 ** is collected about the OR clause.
155730 ** categories, then eOperator==0. The WhereTerm.pExpr field is still set
155731 ** to the original subexpression content and wtFlags is set up appropriately
155736 ** cursor number into bits and the translated bit is stored in the prereq
155737 ** fields. The translation is used in order to maximize the number of
155746 ** The number of terms in a join is limited by the number of bits
155747 ** in prereqRight and prereqAll. The default is 64 bits, hence SQLite
155748 ** is only able to process joins with 64 or fewer tables.
155751 Expr *pExpr; /* Pointer to the subexpression that is this term */
155752 WhereClause *pWC; /* The clause this term is part of */
155777 #define TERM_CODED 0x0004 /* This term is already coded */
155786 #define TERM_IS 0x0800 /* Term.pExpr is an IS operator */
155797 ** An instance of the WhereScan object is used as an iterator for locating
155816 ** WHERE clause. Mostly this is a container for one or more WhereTerms.
155830 u8 hasOr; /* True if any a[].eOperator is WO_OR */
155872 ** corresponds VDBE cursor number B. The A-th bit of a bitmask is 1<<A.
155878 ** Note that the mapping is not necessarily ordered. In the example
155881 ** does not really matter. What is important is that sparse cursor
155892 ** This object is a convenience wrapper holding all information needed
155910 #define SQLITE_BLDF1_INDEXED 0x0001 /* An index is used */
155915 /* The WhereLoopBuilder.iPlanLimit is used to limit the number of
155917 ** particular query. If this parameter is unlimited, then certain
155919 ** routine. The limit is high enough that is should not impact real-world
155922 ** SQLITE_QUERY_PLANNER_LIMIT is the baseline limit. The limit is
155924 ** clause is processed, so that every table in a join is guaranteed to be
155939 ** this structure is returned by the first half and passed
155966 unsigned bOrderedInnerLoop:1;/* True if only the inner-most loop is ordered */
156102 #define WHERE_IPK 0x00000100 /* x is the INTEGER PRIMARY KEY */
156103 #define WHERE_INDEXED 0x00000200 /* WhereLoop.u.btree.pIndex is valid */
156104 #define WHERE_VIRTUALTABLE 0x00000400 /* WhereLoop.u.vtab is valid */
156111 #define WHERE_PARTIALIDX 0x00020000 /* The automatic index is partial */
156113 #define WHERE_BIGNULL_SORT 0x00080000 /* Column nEq of index is BIGNULL */
156140 ** This routine is a helper for explainIndexRange() below
156186 ** is run and there is an index on (a, b), then this function returns a
156217 ** This function is a no-op unless currently processing an EXPLAIN QUERY PLAN
156219 ** was defined at compile-time. If it is not a no-op, a single OP_Explain
156220 ** opcode is added to the output to describe the table scan strategy in pLevel.
156222 ** If an OP_Explain opcode is added to the VM, its address is returned.
156223 ** Otherwise, if no OP_Explain is coded, zero is returned.
156335 ** required and this routine is a no-op.
156337 ** If an OP_Explain opcode is added to the VM, its address is returned.
156338 ** Otherwise, if no OP_Explain is coded, zero is returned.
156387 ** implement level pLvl. Argument pSrclist is a pointer to the FROM
156390 ** If argument addrExplain is not 0, it must be the address of an
156445 ** The t2.z='ok' is disabled in the in (2) because it originates
156446 ** in the ON clause. The term is disabled in (3) because it is not part
156447 ** of a LEFT OUTER JOIN. In (1), the term is not disabled.
156450 ** of the join. Disabling is an optimization. When terms are satisfied
156453 ** but joins might run a little slower. The trick is to disable as much
156457 ** If all the children of a term are disabled, then that term is also
156470 ** Usually the parent term is marked as TERM_CODED. But if the parent
156473 ** a conditional such that is only evaluated on the second pass of a
156511 ** This routine makes its own copy of zAff so that the caller is free
156535 /* Code the OP_Affinity opcode if there is anything left to do. */
156542 ** Expression pRight, which is the RHS of a comparison operation, is
156544 ** Before the comparison operation, affinity zAff is to be applied
156549 ** * the affinity change in zAff is guaranteed not to change the value.
156569 ** pX is an expression of the form: (vector) IN (SELECT ...)
156570 ** In other words, it is a vector IN operator with a SELECT clause on the
156577 ** order. The modified IN expression is returned. The caller is responsible
156589 ** the modified IN expression that is returned will be:
156593 ** The reduced pX is different from the original (obviously) and thus is
156658 ** set correctly. Since setting them is just an optimization,
156680 ** term can be either X=expr or X IN (...). pTerm is the term to be
156683 ** The current value for the constraint is left in a register, the index
156684 ** of which is returned. An attempt is made store the result in iTarget but
156685 ** this is only guaranteed for TK_ISNULL and TK_IN constraints. If the
156686 ** constraint is a TK_EQ or TK_IS, then the current value might be left in
156687 ** some other register and it is the caller's responsibility to compensate.
156689 ** For a constraint of the form X=expr, the expression is evaluated in
156833 /* As an optimization, try to disable the WHERE clause term that is
156834 ** driving the index as it will always be true. The correct answer is
156838 ** But do not disable the term unless we are certain that the term is
156856 ** Suppose the WHERE clause is this: a==5 AND b IN (1,2,3) AND c>5 AND c<10
156858 ** example, the third "c" value is an inequality. So only two
156861 ** in consecutive registers and the index of the first register is returned.
156864 ** of nEq including 0. If nEq==0, this routine is nearly a no-op.
156865 ** The only thing it does is allocate the pLevel->iMem memory cell and
156868 ** The nExtraReg parameter is 0 or 1. It is 0 if all WHERE clause constraints
156869 ** are == or IN and are covered by the nEq. nExtraReg is 1 if there is
156881 ** Before returning, *pzAff is set to point to a buffer containing a
156885 ** SQLITE_AFF_BLOB. This is to deal with SQL such as the following:
156914 /* This module is only called on query plans that use an index. */
156959 /* The following testcase is true for indices with redundant columns.
157003 ** If the most recently coded instruction is a constant range constraint
157015 ** Except, of course, if SQLITE_LIKE_DOESNT_MATCH_BLOBS is defined, then
157016 ** only the one pass through the string space is required, so this routine
157041 ** Information is passed from codeCursorHint() down to individual nodes of
157052 ** This function is called for every node of an expression that is a candidate
157071 ** should be included in the cursor-hint for a table that is on the rhs
157073 ** expression is not suitable.
157075 ** An expression is unsuitable if it might evaluate to non NULL even if
157076 ** a TK_COLUMN node that does affect the value of the expression is set
157103 ** This function is called on every node of an expression tree used as an
157104 ** argument to the OP_CursorHint instruction. If the node is a TK_COLUMN
157114 ** Also, if the node is a TK_COLUMN that does access the table identified
157115 ** by pCCurHint.iTabCur, and an index is being used (which we will
157148 ** Insert an OP_CursorHint instruction if it is appropriate to do so.
157184 ** JOIN for which the current table is not the rhs are omitted
157187 ** If this table is the rhs of a LEFT JOIN, "IS" or "IS NULL" terms
157189 ** This is to address the following:
157193 ** Say there is a single row in t2 that matches (t1.a=t2.b), but its
157194 ** t2.c values is not NULL. If the (t2.c IS NULL) constraint is
157195 ** pushed down to the cursor, this row is filtered out, causing
157197 ** WHERE clause, and so the query returns a row. Which is incorrect.
157239 /* If we survive all prior tests, that means this term is worth hinting */
157255 ** Cursor iCur is open on an intkey b-tree (a table). Register iRowid contains
157260 ** Normally, this is just:
157266 ** However, if the scan currently being coded is a branch of an OR-loop and
157267 ** the statement currently being coded is a SELECT, then additional information
157268 ** is added that might allow OP_Column to omit the seek and instead do its
157270 ** enable this optimization, the P3 of OP_DeferredSeek is set to iIdxCur
157271 ** and P4 is set to an array of integers containing one entry for each column
157272 ** in the table. For each table column, if the column is the i'th
157273 ** column of the index, then the corresponding array entry is set to (i+1).
157274 ** If the column does not appear in the index at all, the array entry is set
157276 ** wants is in the index and if it is, it will substitute the index cursor
157282 Index *pIdx, /* Index scan is using */
157316 ** If the expression passed as the second argument is a vector, generate
157320 ** If the expression is not a vector, then nReg must be passed 1. In
157353 ** The pTruth expression is always true because it is the WHERE clause
157354 ** a partial index that is driving a query loop. Look through all of the
157356 ** true because pTruth is true, then mark those WHERE clause terms as
157381 ** This routine is called right after An OP_Filter has been generated and
157386 ** index lookup. The idea is that a Bloom filter check is way faster than
157391 ** WhereLevel.regFilter set. If an inner-loop Bloom filter is checked,
157393 ** from being checked a second time when the inner loop is evaluated.
157468 int iRowidReg = 0; /* Rowid is stored in this register, if not zero */
157504 ** When there is an IN operator, we also have a "addrNxt" label that
157507 ** is the same as "addrBrk".
157512 /* If this is the right table of a LEFT OUTER JOIN, allocate and
157526 ** this loop is empty and can never contribute content. */
157545 /* Case 1: The table is a virtual-table. Use the VFilter and VNext
157629 ** the IN constraint is not satisfied
157657 /* These registers need to be preserved in case there is an IN operator
157732 assert( TK_GE==TK_GT+3 ); /* ... is correct. */
157813 ** index is on (x,y,z), then the following clauses are all
157828 ** If there are no inequality constraints, then N is at
157831 ** This case is also used when there are no WHERE clause
157832 ** constraints but an index is selected anyway, in order
157859 int start_constraints; /* Start of range is constrained */
157899 ** bottom bit indicates whether the search order is ASC or DESC. */
157916 /* If the WHERE_BIGNULL_SORT flag is set, then index column nEq uses
157919 ** index entries for which the column is null and for those for which
157920 ** it is not. For an ASC sort, the non-NULL entries are scanned first.
157949 /* In case OP_SeekScan is used, ensure that the index cursor does not
158011 ** so no further seeking is needed */
158030 ** 1 or more step operations. The question is, how many steps
158032 ** of a seek is proportional to the logarithm of the of the number
158115 /* Check if the index cursor is past the end of the range. */
158157 /* pIdx is a covering index. No need to access the main table. */
158172 /* If a partial index is driving the loop, try to eliminate WHERE clause
158184 /* The following assert() is not a requirement, merely an observation:
158227 ** RowSetTest are such that the rowid of the current row is inserted
158228 ** into the RowSet. If it is already present, control skips the
158240 ** Goto B # The loop is finished.
158248 ** Added 2014-05-26: If the table is a WITHOUT ROWID table, then
158298 /* Initialize the rowset register to contain NULL. An SQL NULL is
158304 ** is required in a few obscure LEFT JOIN cases where control jumps
158306 ** correct response for the end-of-loop code (the OP_Return) is to
158324 /* If the original WHERE clause is z of the form: (x1 OR x2 OR ...) AND y
158329 ** Actually, each subexpression is converted to "xN AND w" where w is
158335 ** is not contained in the ON clause of a LEFT JOIN.
158341 ** might not occur, or might occur only in an OR branch that is not
158347 ** the OR branch in which the subroutine is coded. But if the subroutine
158348 ** is invoked from a different OR branch that uses a different index, such
158369 /* The extra 0x10000 bit on the opcode is masked off and does not
158380 ** sub-WHERE clause is to to invoke the main loop body as a subroutine.
158415 /* This is the sub-WHERE clause body. First skip over
158447 ** is zero, assume that the key cannot already be present in
158448 ** the temp table. And if iSet is -1, assume that there is no
158471 ** current sub-WHERE row is a duplicate from prior sub-WHEREs. */
158482 ** index, and the index is opened using the same cursor number
158487 ** uses an index, and this is either the first OR-connected term
158488 ** processed or the index is the same as that used by all previous
158530 ** loop to point to this spot, which is the top of the next containing
158543 /* Case 6: There is no usable index. We must do a complete
158550 /* Tables marked isRecursive have only a single row that is stored in
158580 ** An effort is made to skip unnecessary iterations of the loop.
158610 /* An ON clause that is not ripe */
158625 /* If the TERM_LIKECOND flag is set, that means that the range search
158626 ** is sufficient to guarantee that the LIKE operator is true, so we
158714 /* pTab is the right-hand table of the RIGHT JOIN. Generate code that
158716 ** least once. This is accomplished by storing the PK for the row in
158901 ** a legal notice, here is a blessing:
158939 ** The new WhereTerm object is constructed from Expr p and with wtFlags.
158940 ** The index in pWC->a[] of the new WhereTerm is returned on success.
158941 ** 0 is returned if the new WhereTerm could not be added due to a memory
158948 ** for freeing the expression p is assumed by the WhereClause object pWC.
158949 ** This is true even if this routine fails to allocate a new WhereTerm.
158991 ** Return TRUE if the given operator is one of the operators that is
159057 ** Check to see if the given expression is a LIKE or GLOB operator that
159058 ** can be optimized using inequality constraints. Return TRUE if it is
159072 int *pisComplete, /* True if the only wildcard is % in the last character */
159073 int *pnoCase /* True if uppercase is equivalent to lowercase */
159120 /* The optimization is possible only if (1) the pattern does not begin
159123 ** a single escape character. The second condition is necessary so
159125 ** range search. The third is because the caller assumes that the pattern
159149 /* If the LHS is not an ordinary column with TEXT affinity, then the
159189 /* If the RHS pattern is a bound parameter, make arrangements to
159190 ** reprepare the statement when that parameter is rebound */
159196 /* If the rhs of the LIKE expression is a variable, and the current
159197 ** value of the variable means there is no need to invoke the LIKE
159222 ** Check to see if the pExpr expression is a form that needs to be passed
159238 ** is a match, set *ppLeft to the "column" expression, set *ppRight to the
159239 ** "expr" expression (even though in forms (6) and (8) the column is on the
159240 ** right and the expression is on the left). Also set *peOp2 to the
159241 ** appropriate virtual table operator. The return value is 1 or 2 if there
159242 ** is a match. The usual return is 1, but if the RHS is also a column
159275 ** virtual table on their second argument, which is the same as
159302 ** names. But for this use case, xFindFunction is expected to deal
159374 ** Return the N-th AND-connected subterm of pTerm. Or if pTerm is not
159375 ** a conjunction, then return just pTerm when N==0. If N is exceeds
159394 ** compatible (if one is = and the other is <, for example) then
159395 ** add a new virtual AND term to pWC that is the combination of the
159404 ** The following is NOT generated:
159456 ** A WhereOrTerm object is computed and attached to the term under
159477 ** term that is an equivalent IN expression. In other words, if the term
159478 ** being analyzed is:
159503 ** A subterm is "indexable" if it is of the form
159504 ** "T.C <op> <expr>" where C is any column of table T and
159505 ** <op> is one of "=", "<", "<=", ">", ">=", "IS NULL", or "IN".
159506 ** A subterm is also indexable if it is an AND of two or more
159507 ** subsubterms at least one of which is indexable. Indexable AND
159514 ** is decided elsewhere. This analysis only looks at whether subterms
159519 ** always prefer case 1, so in that case we pretend that case 3 is not
159523 ** (E) above is indexable on tables P, Q, and R.
159527 ** the union of all rowids using a RowSet object. This is similar
159533 ** zero. This term is not useful for search.
159555 ** object that is attached to the original OR clause term.
159655 ** is satisfied.
159658 ** that there is no possibility of transforming the OR clause into an
159661 ** case means that every term of the OR clause is of the form
159662 ** "table.column=expr" for some single table. The one bit that is set
159664 ** sure the same column is used on all terms. The 2-bit case is when
159667 ** or table2.column as the LHS if either is common to every term of
159674 int okToChngToIN = 0; /* True if the conversion to IN is valid */
159683 ** and column is found but leave okToChngToIN false if not found.
159692 /* This is the 2-bit case and we are on the second iteration and
159693 ** current term is from the first iteration. So skip this term. */
159699 /* This term must be of the form t1.a==t2.b where t2 is in the
159700 ** chngToIN set but t1 is not. This term will be either preceded
159725 ** table and column is common to every term in the OR clause */
159738 /* If the right-hand side is also a column, then the affinities
159753 /* At this point, okToChngToIN is true if original pTerm satisfies
159754 ** case 1. In that case, construct a new virtual term that is
159795 ** We already know that pExpr is a binary operator where both operands are
159796 ** column references. This routine checks to see if pExpr is an equivalence
159803 ** 5b. The overall collating sequence is BINARY
159806 ** This is an optimization. No harm comes from returning 0. But if 1 is
159859 ** Expression pExpr is one operand of a comparison operator that might
159861 ** in any index. Return TRUE (1) if pExpr is an indexed term and return
159862 ** FALSE (0) if not. If TRUE is returned, also set aiCurCol[0] to the cursor
159863 ** number of the table that is indexed and aiCurCol[1] to the column number
159864 ** of the column that is indexed, or XN_EXPR (-2) if an expression is being
159867 ** If pExpr is a TK_COLUMN column reference, then this routine always returns
159868 ** true even if that particular column is not indexed, because the column
159907 /* If this expression is a vector to the left or right of a
159937 ** The input to this routine is an WhereTerm structure with only the
159938 ** "pExpr" field filled in. The job of this routine is to analyze the
159942 ** If the expression is of the form "<expr> <op> X" it gets commuted
159945 ** If the expression is of the form "X <op> Y" where both X and Y are
159946 ** columns, then the original expression is unchanged and a new virtual
159947 ** term of the form "Y <op> X" is added to the WHERE clause and
159948 ** analyzed separately. The original term is marked with TERM_COPIED
159949 ** and the new term is marked with TERM_DYNAMIC (because it's pExpr
159951 ** is a commuted copy of a prior term.) The original term has nChild=1
160032 ** if there is a RIGHT or FULL JOIN in the query. This makes SQLite
160119 /* If a term is the BETWEEN operator, create two new virtual terms
160124 ** is converted into:
160130 ** term. That means that if the BETWEEN term is coded, the children are
160132 ** BETWEEN term is skipped.
160159 /* Analyze a term that is composed of two or more subterms connected by
160169 ** as "x>NULL" if x is not an INTEGER PRIMARY KEY. So construct a
160209 ** A like pattern of the form "x LIKE 'aBc%'" is changed into constraints
160213 ** The last character of the prefix "abc" is incremented to form the
160214 ** termination condition "abd". If case is not significant (the default
160215 ** for LIKE) then the lower-bound is made all uppercase and the upper-
160216 ** bound is made all lowercase so that the bounds also work when comparing
160240 ** lower-case (upper-case is less than lower-case in ASCII) so that
160258 /* The point is to increment the last character before the first
160294 /* If there is a vector == or IS term - e.g. "(a, b) == (?, ?)" - create
160296 ** new terms completely replace the original vector comparison, which is
160299 ** This is only required if at least one side of the comparison operation
160300 ** is not a sub-select.
160328 /* If there is a vector IN term - e.g. "(a, b) IN (SELECT ...)" - create
160330 ** used by each such virtual term is pExpr (the full vector IN(...)
160334 ** This only works if the RHS is a simple SELECT (not a compound) that does
160359 ** current expression is of the form "column OP expr" where OP
160360 ** is an operator that gets passed into virtual tables but which is
160362 ** is one of MATCH, LIKE, GLOB, REGEXP, !=, IS, IS NOT, or NOT NULL.
160363 ** This information is used by the xBestIndex methods of
160418 ** each subexpression is separated by the AND operator or some other
160420 ** is filled with pointers to subexpressions. For example:
160426 ** The original WHERE clause in pExpr is unaltered. All this routine
160427 ** does is make slot[] entries point to substructure within pExpr.
160450 ** is found in register iReg.
160452 ** In the common case where the value is a simple integer
160498 ** 2. The SELECT statement is not an aggregate or DISTINCT query, and
160500 ** that object is a virtual table, and
160520 /* Check condition (4). Return early if it is not met. */
160523 /* This term is a vector operation that has been decomposed into
160539 /* Check condition (5). Return early if it is not met. */
160578 ** itself is not freed. This routine is the inverse of
160589 /* Verify that every term past pWC->nBase is virtual */
160623 ** be NULL, in which case 0 is returned.
160634 ** case 0 is returned.
160644 ** common case where it is not needed.
160774 ** a legal notice, here is a blessing:
160782 ** the WHERE clause of SQL statements. This module is responsible for
160785 ** so is applicable. Because this module is responsible for selecting
160796 ** This object is not an API and can be changed from one release to the
160808 ** because extra space is allocated to hold up
160834 ** terms means that no sorting is needed at all. A return that
160835 ** is positive but less than the number of ORDER BY terms means that
160836 ** block sorting is required.
160843 ** In the ORDER BY LIMIT optimization, if the inner-most loop is known
160851 ** holds LIMIT+OFFSET rows that are smaller), then a jump is made to the
160859 ** It is always safe for this routine to return the continuation of the
160861 ** Returning the continuation the second inner loop is an optimization
160880 ** additional looping is required. If the output order is such that
160884 ** Any extra OP_Goto that is coded here is an optimization. The
160921 ** Return ONEPASS_OFF (0) if an UPDATE or DELETE statement is unable to
160924 ** a single row is to be changed. Return ONEPASS_MULTI (2) if the one-pass
160927 ** If the ONEPASS optimization is used (if this routine returns true)
160931 ** Either value may be -1, indicating that cursor is not used.
160934 ** aiCur[0] and aiCur[1] both get -1 if the where-clause logic is
160969 ** appended, or it might be discarded. Do whatever is the right thing
161007 ** iCursor is not in the set.
161025 /* Allocate memory that is automatically freed when pWInfo is freed.
161052 ** There is one cursor per table in the FROM clause. The number of
161053 ** tables in the FROM clause is limited by a test early in the
161063 ** If the right-hand branch of the expression is a TK_COLUMN, then return
161176 ** This is whereScanInit() for the case of an index on an expression.
161177 ** It is factored out into a separate tail-recursion subroutine so that
161178 ** the normal whereScanInit() routine, which is a high-runner, does not
161191 ** for terms of the form "X <op> <expr>" where X is column iColumn of table
161192 ** iCur. Or if pIdx!=0 then X is column iColumn of index pIdx. pIdx
161197 ** If the search is for X and the WHERE clause contains terms of the
161199 ** "Y <op> <expr>". The number of levels of transitivity is limited,
161200 ** but is enough to handle most commonly occurring SQL statements.
161202 ** If X is not the INTEGER PRIMARY KEY then X must be compatible with
161245 ** Search for a term in the WHERE clause that is of the form "X <op> <expr>"
161246 ** where X is a reference to the iColumn of table iCur or of index pIdx
161247 ** if pIdx!=0 and <op> is one of the WO_xx operator codes specified by
161254 ** The term returned might by Y=<expr> if there is another constraint in
161264 ** <expr> is a constant expression of some kind. Only return entries of
161265 ** the form "X <op> Y" where Y is a column in another table if no terms of
161300 ** If such an expression is found, its index in pList->a[] is returned. If
161301 ** no expression is found, -1 is returned.
161331 ** Return TRUE if the iCol-th column of index pIdx is NOT NULL
161351 ** is redundant.
161353 ** A DISTINCT list is redundant if any subset of the columns in the
161367 /* If there is more than one table or sub-select in the FROM clause of
161369 ** clause is redundant. */
161374 /* If any of the expressions is an IPK column on table iBase, then return
161376 ** current SELECT is a correlated sub-query.
161388 ** 1. The index is itself UNIQUE, and
161392 ** where X is a constant value. The collation sequences of the
161408 /* This index implies that the DISTINCT qualifier is redundant. */
161428 ** opcodes into OP_Copy when the table is being accessed via co-routine
161431 ** If the iAutoidxCur is not zero, then any OP_Rowid instructions on
161440 int iRegister, /* The first column is in this register */
161526 ** We know that pSrc is an operand of an outer join. Return true if
161527 ** pTerm is a constraint that is compatible with that join.
161529 ** pTerm must be EP_OuterON if pSrc is the right operand of an
161531 ** is the left operand of a RIGHT join.
161564 ** Return TRUE if the WHERE clause term pTerm is of a form where it
161602 ** This is only required if sqlite3_stmt_scanstatus() is enabled, to
161605 ** the OP_Explain is not added if this is an EXPLAIN QUERY PLAN command.
161610 int bPartial, /* True if pIdx is a partial index */
161679 int addrCounter = 0; /* Address where integer counter is initialized */
161680 int regBase; /* Array of registers where record is assembled */
161740 ** covering index. A "covering index" is an index that contains all
161794 ** is not usually helpful. */
161889 ** Generate bytecode that will initialize a Bloom filter that is appropriate
161897 ** When the Bloom filter is initialized, the WHERE_BLOOMFILTER flag is cleared
161898 ** from the loop, but the regFilter value is set to a register that implements
161899 ** the Bloom filter. When regFilter is positive, the
161906 ** is set.
161910 int iLevel, /* Index in pWInfo->a[] that is pLevel */
161948 /* The Bloom filter is a Blob held in a register. Initialize it
161950 ** estimated size of the table is larger. We could actually
161954 ** sqlite_stat1 table, testing is much easier.
162014 /* This is a candidate for bloom-filter pull-down (early evaluation).
162015 ** The test that WHERE_COLUMN_IN is omitted is important, as we are
162030 ** Allocate and populate an sqlite3_index_info structure. It is the
162038 SrcItem *pSrc, /* The FROM clause term that is the vtab */
162187 /* The direct assignment in the previous line is possible only because
162251 ** If an error occurs, pParse is populated with an error message and an
162252 ** appropriate error code is returned. A return of SQLITE_CONSTRAINT from
162253 ** xBestIndex is not considered an error. SQLITE_CONSTRAINT indicates that
162257 ** Whether or not an error is returned, it is the responsibility of the
162259 ** that this is required.
162297 ** Return the index of the sample that is the smallest sample that
162298 ** is greater than or equal to pRec. Note that this index is not an index
162299 ** into the aSample[] array - it is an index into a virtual set of samples
162318 tRowcnt iLower = 0; /* anLt[] + anEq[] of largest sample pRec is > */
162330 ** is simply the aSample[] array. If the samples in aSample[] contain more
162333 ** If pRec contains N fields, where N is more than one, then as well as the
162336 ** in aSample is:
162345 ** unique prefixes [a], [b] and [c]. But since that is hard to organize,
162364 ** Except, each sample may be extended to ensure that it is greater than or
162366 ** sample 2 is the first sample of a block of N samples, so at first it
162369 ** it is extended to two fields. The duplicates that this creates do not
162387 /* The proposed effective sample is a prefix of sample aSample[iSamp].
162389 ** fields that is greater than the previous effective sample. */
162419 /* If (res==0) is true, then pRec must be equal to sample i. */
162427 /* Unless i==pIdx->nSample, indicating that pRec is larger than
162436 /* if i==0 and iCol==0, then record pRec is smaller than all samples
162455 /* Record pRec is equal to sample i */
162460 /* At this point, the (iCol+1) field prefix of aSample[i] is the first
162461 ** sample that is greater than pRec. Or, if i==pIdx->nSample then pRec
162462 ** is larger than all samples in the array. */
162491 ** If it is not NULL, pTerm is a term that provides an upper or lower
162492 ** bound on a range scan. Without considering pTerm, it is estimated
162497 ** then the return value is the likelihood multiplied by the number of
162531 ** This function is called to estimate the number of rows visited by a
162537 ** Value pLoop->nOut is currently set to the estimated number of rows
162541 ** times (once for each (a,b) combination that matches a=?) is dealt with
162548 ** N is the total number of samples, the pLoop->nOut value is adjusted
162553 ** If pLower is NULL, or a value cannot be extracted from the term, L is
162554 ** set to zero. If pUpper is NULL, or a value cannot be extracted from it,
162555 ** U is set to N.
162560 ** is left as is.
162562 ** If an error occurs, an SQLite error code is returned. Otherwise,
162612 /* If there is both an upper and lower bound specified, and the
162638 ** This function is used to estimate the number of rows that will be visited
162642 ** example, assuming that index p is on t1(a):
162649 ** If either of the upper or lower bound is not present, then NULL is passed in
162652 ** The value in (pBuilder->pNew->u.btree.nEq) is the number of the index
162655 ** assuming index p is on t1(a, b), and the SQL query is:
162659 ** then nEq is set to 1 (as the range restricted column, b, is the second
162660 ** left-most column of the index). Or, if the query is:
162664 ** then nEq is set to 0.
162666 ** When this function is called, *pnOut is set to the sqlite3LogEst() of the
162667 ** number of rows that the index scan is expected to visit without
162668 ** considering the range constraints. If nEq is 0, then *pnOut is the number of
162669 ** rows in the index. Assuming no error occurs, *pnOut is adjusted (reduced)
162703 ** lower bound being the concatenation of $P and $L, where $P is the
162705 ** columns of the index, and $L is the value in pLower.
162707 ** Or, if pLower is NULL or $L cannot be extracted from it (because it
162708 ** is not a simple variable or literal value), the lower bound of the
162709 ** range is $P. Due to a quirk in the way whereKeyStats() works, even
162710 ** if $L is available, whereKeyStats() is called for both ($P) and
162711 ** ($P:$L) and the larger of the two returned values is used.
162713 ** Similarly, iUpper is to be set to the estimate of the number of rows
162715 ** is either ($P) or ($P:$U). Again, even if $U is available, both values
162718 ** The number of rows between the two bounds is then just iUpper-iLower.
162818 /* TUNING: If there is both an upper and lower limit and neither limit
162819 ** has an application-defined likelihood(), assume the range is
162821 ** range query (e.g. col > ?) is assumed to match 1/4 of the rows in the
162822 ** index. While a closed range (e.g. col BETWEEN ? AND ?) is estimated to
162845 ** the histogram data. This only works when x is the left-most
162846 ** column of an index and sqlite_stat4 histogram data is available
162847 ** for that index. When pExpr==NULL that means the constraint is
162854 ** This routine can fail if it is unable to load a collating sequence
162856 ** for a UTF conversion required for comparison. The error is stored
162884 /* This is an optimization only. The call to sqlite3Stat4ProbeSetValue()
162910 ** is a list of values. Example:
162918 ** This routine can fail if it is unable to load a collating sequence
162920 ** for a UTF conversion required for comparison. The error is stored
163202 ** Return TRUE if X is a proper subset of Y but is of equal or less cost.
163205 ** but the cost of running X is not more than the cost of running Y.
163208 ** is inverted and needs to be adjusted.
163222 ** (2c) Every WHERE clause term used by X is also used by Y
163224 ** (2e) If X is a covering index, than Y is too
163238 return 1; /* Case 1 is true */
163255 return 1; /* Case 2 is true */
163266 ** is a proper subset.
163268 ** To say "WhereLoop X is a proper subset of Y" means that X uses fewer
163269 ** WHERE clause terms than Y and that every WHERE clause term used by X is
163278 /* Adjust pTemplate cost downward so that it is cheaper than its
163287 /* Adjust pTemplate cost upward so that it is costlier than p since
163288 ** pTemplate is a proper subset of p */
163306 ** If pX is a WhereLoop that pTemplate can replace, then return the
163321 ** then those WhereLoops need to be considered separately. Neither is
163325 /* In the current implementation, the rSetup value is either zero
163327 ** is the same for compatible WhereLoops. */
163337 ** UNIQUE constraint) with one or more == constraints is better
163338 ** than an automatic index. Unless it is a skip-scan. */
163348 /* If existing WhereLoop p is better than pTemplate, pTemplate can be
163349 ** discarded. WhereLoop p is better if:
163361 /* If pTemplate is always better than p, then cause p to be overwritten
163362 ** with pTemplate. pTemplate is better than p if:
163381 ** is better and has fewer dependencies. Or the template will be ignored
163382 ** and no insert will occur if an existing WhereLoop is faster and has
163383 ** fewer dependencies than the template. Otherwise a new WhereLoop is
163386 ** If pBuilder->pOrSet is not NULL then we care about only the
163388 ** information is gathered in the pBuilder->pOrSet object. This special
163389 ** processing mode is used only for OR clause processing.
163391 ** When accumulating multiple loops (when pBuilder->pOrSet is NULL) we
163393 ** new template is better. Loops may be overwritten if the following
163417 /* If pBuilder->pOrSet is defined, then only keep track of the costs
163443 /* There already exists a WhereLoop on the list that is better
163514 ** For every WHERE clause term that is not used by the index
163519 ** TUNING: For every WHERE clause term that is not used by the index
163522 ** TODO --> Perhaps this is something that could be improved by better
163530 ** form "x==EXPR" and EXPR is not a constant 0 or 1, then make sure the
163531 ** final output row estimate is no greater than 1/4 of the total number
163533 ** out at least 3 out of 4 rows. If EXPR is -1 or 0 or 1, then maybe the
163534 ** "x" column is boolean or else -1 or 0 or 1 is a common default value
163570 ** operand, or if the loop is not an OUTER JOIN.
163580 /* If a truth probability is specified using the likelihood() hints,
163612 ** Term pTerm is a vector range comparison operation. The first comparison
163617 ** For example, if the query is:
163626 ** this case is 3.
163640 /* Test if comparison i of pTerm is compatible with column (i+nEq)
163656 /* Check that the LHS of the comparison is a column reference to
163658 ** order of the index column is the same as the sort order of the
163694 ** When this function is called, pBuilder->pNew->nOut contains the
163696 ** terms only. If it is modified, this value is restored before this
163699 ** If pProbe->idxType==SQLITE_IDXTYPE_IPK, that means pIndex is
163823 ** In this case there is a separate term for each of (x) and (y).
163825 ** for each such term. The following loop checks that pTerm is the
163826 ** first such term in use, and sets nIn back to 0 if it is not. */
163840 ** to the left in the same index. If the IN operator is on
163843 ** Given the definitions above, it is better to omit the IN operator
163854 ** tables (less than 2 rows) as it is pointless in that case.
163933 /* At this point pNew->nOut is set to the number of rows expected to
163940 /* Adjust nOut using stat4 data. Or, if there is no stat4
164005 /* TUNING: If there is no likelihood() value, assume that a
164015 ** it to pNew->rRun, which is currently set to the cost of the index
164016 ** seek only. Then, if this is a non-covering index, add the cost of
164020 /* The pProbe->szIdxRow is low for an IPK table since the interior
164072 ** number of repeats in the left-most terms is at least 18.
164074 ** The magic number 18 is selected on the basis that scanning 17 rows
164075 ** is almost always quicker than an index seek (even though if the index
164077 ** the code). And, even if it is not, it should not be too much slower.
164113 ** Return True if it is possible that pIndex might be useful in
164117 ** if there is no way for pIndex to be useful in implementing that
164186 ** pIdx is an index containing expressions. Check it see if any of the
164217 ** Information passed in is pWalk->u.pCovIdxCk. Call it pCk.
164220 ** make sure that column is covered by the index pCk->pIdx. We know that
164263 ** pIdx is an index that covers all of the low-number columns used by
164265 ** expressions terms. Hence, we cannot determine whether or not it is
164267 ** to see if the index is covering. This routine does that search.
164269 ** The return value is one of these:
164271 ** 0 The index is definitely not a covering index
164273 ** WHERE_IDX_ONLY The index is definitely a covering index
164275 ** WHERE_EXPRIDX The index is likely a covering index, but it is
164281 ** This routine is an optimization. It is always safe to return zero.
164287 Index *pIdx, /* Index that is being tested */
164295 ** if pIdx is covering. Assume it is not. */
164304 ** colMask that columns greater than 62 are used, so this is not a
164329 ** This is an sqlite3ParserAddCleanup() callback that is invoked to
164330 ** free the Parse->pIdxEpr list when the Parse object is destroyed.
164343 ** This function is called for a partial index - one with a WHERE clause - in
164354 ** (a) <expr> is a constant expression, and
164358 ** If argument pItem is NULL, then pMask must not be NULL. In this case this
164359 ** function is being called as part of determining whether or not pIdx
164360 ** is a covering index. This function clears any bits in (*pMask)
164364 ** Otherwise, if pItem is not NULL, then this function is being called
164424 ** is identified by pBuilder->pNew->iTab. That table is guaranteed to be
164436 ** where K is a value between 1.1 and 3.0 set based on the relative
164439 ** For an index scan, where nVisit is the number of index rows visited
164440 ** by the scan, and nSeek is the number of seek operations required on
164446 ** Normally, nSeek is 1. nSeek values greater than 1 come about if the
164451 ** of uncertainty. For this reason, scoring is designed to pick plans that
164453 ** log(nRow) factor is omitted from a non-covering index scan in order to
164455 ** performance of using an index is far better than the worst-case performance
164492 /* There is no INDEXED BY clause. Create a fake Index object in local
164511 ** NOT INDEXED qualifier is omitted from the FROM clause */
164543 /* TUNING: One-time cost for computing the automatic index is
164544 ** estimated to be X*N*log2(N) where N is the number of rows in
164545 ** the table being indexed and where X is 7 (LogEst=28) for normal
164547 ** of X is smaller for views and subqueries so that the query planner
164549 ** those objects, since there is no opportunity to add schema
164561 ** is more than the usual guess of 10 rows, since we have no way
164608 /* TUNING: Cost of full table scan is 3.0*N. The 3.0 factor is an
164613 ** At 2.75, a full table scan is preferred over using an index on
164617 ** the scarcer of the two values, and in that case an index lookup is
164647 ("-> %s is not a covering index"
164655 ("-> %s is a covering expression index"
164667 pProbe->zName, m==0 ? "is" : "is not"));
164687 /* The cost of visiting the index rows is N*K, where K is
164692 /* If this is a non-covering index scan, add in the cost of
164736 /* If a non-unique index is used, or if a prefix of the key for
164737 ** unique index is used (making the index functionally non-unique)
164754 ** Return true if pTerm is a virtual table LIMIT or OFFSET term.
164763 ** Argument pIdxInfo is already populated with all constraints that may
164768 ** A constraint is marked usable if:
164772 ** * It is not one of the operators specified in the mExclude mask passed
164773 ** as the fourth argument (which in practice is either WO_IN or 0).
164775 ** Argument mPrereq is a mask of tables that must be scanned before the
164777 ** before it is added to pBuilder.
164779 ** Output parameter *pbIn is set to true if the plan added to pBuilder
164839 ** that the particular combination of parameters provided is unusable.
164892 /* A virtual table that is constrained by an IN clause may not
164894 ** is not necessarily related to the order of output terms and
164904 /* If there is an IN(...) term handled as an == (separate call to
164906 ** OFFSET term handled as well, the plan is unusable. Set output
164969 ** 1. If there is an explicit COLLATE operator on the constraint, return it.
164991 ** Return true if constraint iCons is really an IN(...) constraint, or
164992 ** false otherwise. If iCons is an IN(...) constraint, set (if bHandle!=0)
165010 ** This interface is callable from within the xBestIndex callback only.
165017 int iCons, /* Constraint for which RHS is wanted */
165055 ** Cause the prepared statement that is associated with a call to
165057 ** prepared is read-only, then just start read transactions on all
165058 ** schemas. But if this is a write operation, start writes on all
165061 ** This is used by the (built-in) sqlite_dbpage virtual table.
165078 ** pBuilder->pNew->iTab. That table is guaranteed to be a virtual table.
165081 ** mUnusable are set to 0. Otherwise, mPrereq is a mask of all FROM clause
165153 ** and does not use an IN(...) operator, then there is no point in making
165155 ** result (if the xBestIndex() implementation is sane). */
165333 /* TUNING: Currently sSum.a[i].rRun is set to the sum of the costs
165335 ** errors, it may be that the cost of the OR-scan is equal to its
165339 ** following where there is an index on "y":
165400 ** is itself on the left side of a RIGHT JOIN.
165450 ** Note that processing for WHERE_GROUPBY and WHERE_DISTINCTBY is not as
165451 ** strict. With GROUP BY and DISTINCT the only requirement is that
165467 u8 revSet; /* True if rev is known */
165493 ** We say the WhereLoop is "one-row" if it generates no more than one
165494 ** row of output. A WhereLoop is one-row if all of the following are true:
165496 ** (b) The index is unique
165497 ** Any WhereLoop with an WHERE_COLUMN_EQ constraint on the rowid is one-row.
165500 ** We say the WhereLoop is "order-distinct" if the set of columns from
165502 ** row of the WhereLoop. Every one-row WhereLoop is automatically
165504 ** is not order-distinct. To be order-distinct is not quite the same as being
165509 ** The rowid for a table is always UNIQUE and NOT NULL so whenever the
165510 ** rowid appears in the ORDER BY clause, the corresponding WhereLoop is
165548 /* Mark off any ORDER BY term X that is a column in the table of
165549 ** the current loop for which there is term in the WHERE
165621 ** terms imply that the index is not UNIQUE NOT NULL in which case
165625 ** If the current term is a column of an ((?,?) IN (SELECT...))
165627 ** check that it is the only column used by this loop. Otherwise,
165628 ** if it is one of two or more, none of the columns can be
165640 /* ALWAYS() justification: eOp is an equality operator due to the
165642 ** than WO_IN is captured by the previous "if". So this one
165668 ** WhereLoop is not well-ordered. tag-20210426-1
165714 /* Make sure the sort order is compatible in an ORDER BY clause.
165715 ** Sort order is irrelevant for a GROUP BY clause. */
165785 ** If the WHERE_GROUPBY flag is set in the mask passed to sqlite3WhereBegin(),
165786 ** the planner assumes that the specified pOrderBy list is actually a GROUP
165790 ** Normally, in this case it is not possible for the caller to determine
165793 ** if the WHERE_SORTBYGROUP flag is also passed to sqlite3WhereBegin(), then
165836 /* Estimated cost of a full external sort, where N is
165837 ** the number of rows to sort is:
165847 ** The constant K is at least 2.0 but will be larger if there are a
165848 ** large number of columns to be sorted, as the sorting time is
165854 ** And extra factor of 2.0 or 3.0 is added to the sorting cost if the sort
165855 ** is built using OP_IdxInsert and OP_Sort rather than with OP_SorterInsert.
165868 /* Multiple by log(M) where M is the number of output rows.
165869 ** Use the LIMIT for M if it is smaller. Or if this sort is for
165893 ** once. This path is then loaded into the pWInfo->a[].pWLoop fields.
165925 /* TUNING: For simple queries, only the best path is tracked.
165933 /* If nRowEst is zero and there is an ORDER BY clause, ignore it. In this
165934 ** case the purpose of this call is to estimate the number of rows returned
165957 /* If there is an ORDER BY clause and it is not being ignored, set up
165959 ** is either zero - meaning it has not yet been initialized - or the
165961 ** the ORDER BY clause are already in order, where X is the array
165972 ** of computing an automatic index is not paid back within the first 28
165978 /* If nLoop is zero, then there are no FROM terms in the query. Since
165981 ** indicate this. Or, if nLoop is greater than zero, set isOrdered to
166004 /* Do not use an automatic index if the this loop is expected
166005 ** to run less than 1.25 times. It is tempting to also exclude
166007 ** index is useful in the outer loop of a correlated subquery. */
166012 /* At this point, pWLoop is a candidate to be the next loop.
166055 ** The term "((pTo->isOrdered^isOrdered)&0x80)==0" is equivalent
166072 /* The current candidate is no better than any of the mxChoice
166107 ** The conditional is an expanded vector comparison equivalent to:
166133 /* Control reaches here if the candidate path is better than the
166147 /* pWLoop is a winner. Add it to the set of best so far */
166335 /* TUNING: Cost of a rowid lookup is 10 */
166361 /* TUNING: Cost of a unique index lookup is 15 */
166449 ** 5) The table must not have an inner-join ON or USING clause if there is
166452 ** Note: Due to (2), this condition can only arise if the table is
166548 ** (1) The SEARCH happens more than N times where N is the number
166549 ** of rows in the table that is being considered for the Bloom
166551 ** (2) Some searches are expected to find zero rows. (This is determined
166553 ** (3) Bloom-filter processing is not disabled. (Checked by the
166555 ** (4) The size of the table being searched is known by ANALYZE.
166560 ** down where the code for each WhereLoop is generated.
166579 /* vvvvvv--- Always the case if WHERE_COLUMN_EQ is defined */
166598 ** The index pIdx is used by a query and contains one or more expressions.
166599 ** In other words pIdx is an index on an expression. iIdxCur is the cursor
166600 ** number for the index and iDataCur is the cursor number for the corresponding
166702 ** The return value is a pointer to an opaque structure that contains
166709 ** The basic idea is to do a nested loop, one loop for each table in
166712 ** example, if the SQL is this:
166716 ** Then the code generated is conceptually like the following:
166727 ** appear in the FROM clause if a different order is better able to make
166742 ** If the WHERE clause is empty, the foreach loops must each scan their
166743 ** entire tables. Thus a three-way join is an O(N^3) operation. But if
166746 ** code will run much faster. Most of the work of this routine is checking
166752 ** loops are evaluated and if false a jump is made around all subsequent
166758 ** An outer join of tables t1 and t2 is conceptually coded as follows:
166775 ** pOrderBy is a pointer to the ORDER BY clause (or the GROUP BY clause
166776 ** if the WHERE_GROUPBY flag is set in wctrlFlags) of a SELECT statement
166777 ** if there is one. If there is no ORDER BY clause or if this routine
166778 ** is called from an UPDATE or DELETE statement, then pOrderBy is NULL.
166780 ** The iIdxCur parameter is the cursor number of an index. If
166781 ** WHERE_OR_SUBCLAUSE is set, iIdxCur is the cursor number of an index
166783 ** specific cursor. If WHERE_ONEPASS_DESIRED is set, then iIdxCur is
166785 ** be used to compute the appropriate cursor depending on which index is
166796 int iAuxArg /* If WHERE_OR_SUBCLAUSE is set, index cursor number
166833 /* The number of tables in the FROM clause is limited by the number of
166843 ** pTabList. But if the WHERE_OR_SUBCLAUSE flag is set, then we should
166850 ** return value. A single allocation is used to store the WhereInfo
166899 ** subexpression is separated by an AND operator.
166917 ** The N-th term of the FROM clause is assigned a bitmask of 1<<N.
166919 ** The rule of the previous sentence ensures that if X is the bitmask for
166920 ** a table T, then X-1 is the bitmask for all other tables to the left of T.
166921 ** Knowing the bitmask for all tables to the left of a left join is
166925 ** pTabList, not just the first nTabList tables. nTabList is normally
166927 ** WHERE_OR_SUBCLAUSE flag is set.
166966 ** that are not within a sub-select. This is not required
166998 /* Disable the DISTINCT optimization if SQLITE_DistinctOpt is set via
167003 /* The DISTINCT marking is pointless. Ignore it. */
167118 ** This query optimization is factored out into a separate "no-inline"
167122 ** sqlite3WhereCodeOneLoopStart() procedure, and it is important to
167154 /* If the caller is an UPDATE or DELETE statement that is requesting
167155 ** to use a one-pass algorithm, determine if this is appropriate.
167163 ** * the table is not a virtual table, and
167165 ** is a DELETE operation (WHERE_DUPLICATES_OK is only specified
167168 ** The last qualification is because an UPDATE statement uses
167170 ** use a one-pass approach, and this is not set accurately for scans
167237 ** it is advantageous to reduce the "column count" field in
167264 /* iAuxArg is always set to a positive value if ONEPASS is possible */
167269 /* This is one term of an OR-optimization using the PRIMARY KEY of a
167357 /* The nature of RIGHT JOIN processing is such that it messes up
167451 ** Return true if cursor iCur is opened by instruction k of the
167562 ** "a = ? AND b IN (...)", where the index is on (a, b). If
167563 ** the RHS of the (a=?) is NULL, then the "b IN (...)" may
167565 ** return the null-row. So, if the cursor is not open yet,
167578 ** it jumps past the OP_IfNoHope. This is because the
167579 ** OP_IsNull also bypasses the OP_Affinity opcode that is
167717 /* Proof that the "+1" on the k value above is safe */
167756 ** reference. Verify that this is harmless - that the
167757 ** table being referenced really is open.
167788 /* The "break" point is here, just past the end of the outer loop.
167807 ** a legal notice, here is a blessing:
167824 ** functions may be used) is transformed by function sqlite3WindowRewrite()
167834 ** is transformed to:
167840 ** The flattening optimization is disabled when processing this transformed
167855 ** If there is more than one window function in the SELECT that uses
167863 ** is transformed in the same way as the example above. However:
167884 ** sub-query, which is always implemented as a co-routine. It then calls
167889 ** by the sub-query a sub-routine (OP_Gosub) coded by select.c is invoked.
167890 ** When the sub-routine is invoked:
167901 ** This detail is encapsulated within this file, the code generated by
167902 ** select.c is the same in either case.
167929 ** window frame is sometimes modified before the SELECT statement is
167939 ** the start of the window frame is declared as anything other than
168005 ** implementation is used in "slow mode" only - when the EXCLUDE clause
168006 ** is not set to the default value "NO OTHERS".
168366 ** The noopValueFunc() is called but is expected to do nothing. The
168367 ** noopStepFunc() is never called, and so it is marked with NO_TEST to
168445 ** This function is called immediately after resolving the function name
168446 ** for a window function within a SELECT statement. Argument pList is a
168448 ** Argument pFunc is the function definition just resolved and pWin
168449 ** is the Window object representing the associated OVER clause. This
168457 ** * If the function is a built-in window function that requires the
168459 ** of this file), pWin is updated here.
168556 /* If this function is being called from within a scalar sub-select
168652 ** * window function with a Window object that is not a member of the
168657 ** pWin->iEphCsr, where N is the number of elements in (*ppSub) after
168755 ** any SQL window functions, this function is a no-op. Otherwise, it
168803 /* Create the ORDER BY clause for the sub-select. This is the concatenation
168819 ** The OpenEphemeral instruction is coded later, after it is known how
168860 /* If there is no ORDER BY or PARTITION BY clause, and the window
168862 ** selected (e.g. "SELECT row_number() OVER () FROM t1"), it is possible
168863 ** that pSublist is still NULL here. Add a constant expression here to
168892 ** pParse->nErr will be set, so if SQLITE_NOMEM is set, we will get
168922 ** Unlink the Window object from the Select to which it is attached,
168923 ** if it is attached.
168962 ** The argument expression is an PRECEDING or FOLLOWING offset. The
168963 ** value should be a non-negative integer. If the value is not a
168964 ** constant, change it to NULL. The fact that it is then a non-negative
168965 ** integer will be caught later. But it is important not to leave
169049 ** pWin. Also, if parameter pBase is not NULL, set pWin->zBase to the
169074 ** is the base window. Earlier windows from the same WINDOW clause are
169123 "DISTINCT is not supported for window functions"
169133 ** to be processed as part of SELECT statement pSel). The window is linked
169189 ** This is called by code in select.c before it calls sqlite3WhereBegin()
169190 ** to begin iterating through the sub-query results. It is used to allocate
169277 ** code to check that the value is a non-negative integer and throws an
169278 ** exception if it is not.
169346 ** A single instance of this structure is allocated on the stack by
169348 ** routines. This is to reduce the number of arguments required by each
169353 ** ordinary aggregate function does). This variable is set to the first
169359 ** that it processes in a temporary table. If it is not zero, this
169365 ** An input row can be discarded after it is returned to the caller.
169387 ** on (so that it is 2 groups ahead of current). And a third (start) that
169438 ** Generate VM code to invoke either xStep() (if bInverse is 0) or
169439 ** xInverse (if bInverse is non-zero) for each window function in the
169444 ** If argument csr is greater than or equal to 0, then argument reg is
169450 ** Or, if csr is less than zero, then the array of registers at reg is
169453 ** If argument regPartSize is non-zero, then it is a register containing the
169709 ** OP_Gosub instruction is all that this routine generates. Extra VM code
169710 ** for per-row processing is only generated for the following built-in window
169849 ** If the two arrays are not equal, the contents of regNew is copied to
169851 ** are equal, an OP_Goto is executed. The address of the OP_Goto is returned.
169877 ** This function is called as part of generating VM programs for RANGE
169879 ** the ORDER BY term in the window, and that argument op is OP_Ge, it generates
169885 ** operator in the above pseudo-code is replaced with ">" or "<=", respectively.
169887 ** If the sort-order for the ORDER BY term in the window is DESC, then the
169888 ** comparison is reversed. Instead of adding regVal to csr1.peerVal, it is
169889 ** subtracted. And the comparison operator is inverted to - ">=" becomes "<=",
169891 ** is OP_Ge, the generated code is equivalent to:
169895 ** A special type of arithmetic is used such that if csr1.peerVal is not
169897 ** or subtraction is a a copy of csr1.peerVal.
169905 int lbl /* Jump destination if condition is true */
169938 /* If the BIGNULL flag is set for the ORDER BY, then it is required to
169942 ** instead if the BIGNULL flag is set then cases where either reg1 or
169944 ** generated is equivalent to:
169954 ** Additionally, if either reg1 or reg2 are NULL but the jump to lbl is
169976 /* This block runs if reg1 is not NULL, but reg2 is. */
169985 ** from it. Or, if reg1 is not numeric (it is a NULL, a text value or a blob),
169986 ** then leave reg1 as it is. In pseudo-code, this is implemented as:
169993 ** the add/subtract is skipped for these, as required. If reg1 is a NULL,
169994 ** then the arithmetic is performed, but since adding or subtracting from
169995 ** NULL is always NULL anyway, this case is handled as required too. */
170006 ** control skips over this test if the BIGNULL flag is set and either
170048 /* Special case - WINDOW_AGGINVERSE is always a no-op if the frame
170085 /* If this is a (RANGE BETWEEN a FOLLOWING AND b FOLLOWING) or
170089 ** if the input cursor is still finding new rows, that the end
170229 ** pExpr evaluates to a value that, when cast to an integer, is greater
170249 ** passed as the second argument when this function is invoked. It generates
170252 ** sqlite3WhereEnd() is always called before returning.
170255 ** require slightly different processing. The following pseudo code is
170277 ** // First time this branch is taken, the eph table contains two
170293 ** if( csrCurrent is EOF ) break;
170388 ** assuming that it is equivalent to "infinity PRECEDING/FOLLOWING" and
170389 ** CURRENT ROW by assuming that it is equivalent to "0 PRECEDING/FOLLOWING".
170390 ** This is optimized of course - branches that will never be taken and
170392 ** exceptional case is:
170426 ** when (expr1 < expr2). This is detected at runtime, not by this function.
170450 ** ROWS. The VM code is modified slightly so that:
170452 ** 1. The else branch in the main loop is only taken if the row just
170453 ** added to the ephemeral table is the start of a new group. In
170504 ** if( csrCurrent is EOF ) break;
170512 ** expression (there is only ever 1 for a RANGE that uses an <expr> FOLLOWING
170685 /* If this is not a "ROWS BETWEEN ..." frame, then allocate arrays of
170708 ** VM code to check if the input row is the start of a new partition.
170710 ** address of the OP_Gosub is stored in local variable addrGosubFlush. */
170734 /* This block is run for the first row of each partition */
170908 /* This file is automatically generated by Lemon from input grammar
170915 ** a legal notice, here is a blessing:
170924 ** The canonical source code to this file ("parse.y") is a Lemon grammar
170926 ** That input file is processed by Lemon to generate a C-language
170966 ** into sqlite3ParserAlloc(). The default is size_t.
170972 ** TRIGGER. "a" is the event type, one of TK_UPDATE, TK_INSERT,
170973 ** TK_DELETE, or TK_INSTEAD. If the event is of the form
171049 ** object describing the query for which the WITH clause is a prefix.
171108 /* Add a single new term to an ExprList that is used to store a
171325 /* The next sections is a series of control #defines.
171327 ** YYCODETYPE is the data type used to store the integer codes
171329 ** "unsigned char" is used if there are fewer than
171331 ** YYNOCODE is a number of type YYCODETYPE that is not used for
171338 ** YYACTIONTYPE is the data type used for "action codes" - numbers
171341 ** sqlite3ParserTOKENTYPE is the data type used for minor type for terminal
171342 ** symbols. Background: A "minor type" is a semantic
171350 ** YYMINORTYPE is the data type used for all minor types.
171351 ** This is typically a union of many types, one of
171352 ** which is sqlite3ParserTOKENTYPE. The entry in the union
171353 ** for terminal symbols is called "yy0".
171354 ** YYSTACKDEPTH is the maximum depth of the parser's stack. If
171355 ** zero the stack is dynamically sized using realloc()
171362 ** YYERRORSYMBOL is the code number of the error symbol. If not
171436 /* Define the yytestcase() macro to be a no-op if is not already defined
171441 ** code the yytestcase() macro should be turned off. But it is useful
171454 ** Suppose the action integer is N. Then the action is determined as
171457 ** 0 <= N <= YY_MAX_SHIFT Shift N. That is, push the lookahead
171473 ** The action table is constructed as a single large table named yy_action[].
171474 ** Given state S and lookahead X, the action is computed as either:
171479 ** The (A) formula is preferred. The B formula is used instead if
171480 ** yy_lookahead[yy_shift_ofst[S]+X] is not equal to X.
171482 ** The formulas above are for computing the action when the lookahead is
171483 ** a terminal symbol. If the lookahead is a non-terminal (as occurs after
171484 ** a reduce action) then the yy_reduce_ofst[] array is used in place of
172121 ** and Z. Whenever one of the tokens X, Y, or Z is input to the parser
172122 ** but it does not parse, the type of the token is changed to ID and
172123 ** the parse is retried before an error is thrown.
172327 ** + The semantic value stored at this level of the stack. This is
172329 ** It is sometimes called the "minor" token.
172337 YYCODETYPE major; /* The major token value. This is the code
172340 ** is the value of the token */
172344 /* The state of the parser is completely contained in an instance of
172377 ** and a prompt to preface each trace message. Tracing is turned off
172383 ** If NULL, then tracing is turned off.
172385 ** line of trace output. If NULL, then tracing is
173212 ** The only argument is a pointer to a function which works like
173219 ** A pointer to a parser. This pointer is used in subsequent calls
173236 ** or nonterminal. "yymajor" is the symbol code, and "yypminor" is
173238 ** deletions is derived from the %destructor and/or %token_destructor
173249 /* Here is inserted the actions which take place when a
173250 ** terminal or non-terminal is destroyed. This can happen
173251 ** when the symbol is popped from the stack during a
173252 ** reduce or during error processing or when a parser is
173253 ** being destroyed before it is finished parsing.
173361 ** If there is a destructor routine associated with the token which
173362 ** is popped from the stack, then call it.
173396 ** is defined in a %include section of the input grammar) then it is
173397 ** assumed that the input pointer is never NULL.
173422 ** coverage. The element yycoverage[X][Y] is set when the parser
173423 ** is in state X and has a lookahead token Y. In a well-tested
173434 ** (2) is not a syntax error.
173554 ** The following routine is called if the stack overflows.
173565 /* Here code is inserted which will execute if the parser
174466 ** if the lookahead token has already been consumed. As this procedure is
175256 ** in the virtual machine. #N is the N-th register. */
175669 "the INDEXED BY clause is not allowed on UPDATE or DELETE statements "
175676 "the NOT INDEXED clause is not allowed on UPDATE or DELETE statements "
176039 /* It is not possible for a REDUCE to be followed by an error */
176065 /* Here code is inserted which will be executed whenever the
176099 ** The following is executed when the parser accepts
176115 /* Here code is inserted which will be executed whenever the
176124 ** The first argument is a pointer to a structure obtained from
176126 ** The second argument is the major token number. The third is
176127 ** the minor token. The fourth optional argument is whatever the
176128 ** user wants (and specified in the grammar) and is available for
176202 /* Check that the stack is large enough to grow by a single entry
176203 ** if the RHS of the rule is empty. This ensures that there is room
176254 ** This is what we do if the grammar does define ERROR:
176259 ** it is legal to shift the error symbol, then shift
176305 /* If the YYNOERRORRECOVERY macro is defined, then do not attempt to
176315 #else /* YYERRORSYMBOL is not defined */
176316 /* This is what we do if the grammar does not define ERROR:
176320 ** * If the input token is $, then fail the parse.
176375 ** a legal notice, here is a blessing:
176393 ** In the sqlite3GetToken() function, a switch() on aiClass[c] is implemented
176395 ** The lookup table is much faster. To maximize speed, and to ensure that
176396 ** a lookup table is used, all of the classes need to be small integers and
176474 ** lower-case ASCII equivalent. On ASCII machines, this is just
176476 ** to adjust the encoding. The mapping is only valid for alphabetics
176477 ** which are the only characters for which this feature is used.
176509 ** it is a keyword. If it is a keyword, the token code of that keyword is
176510 ** returned. If the input is not a keyword, TK_ID is returned.
176514 ** The output of the mkkeywordhash.c program is written into a file
176527 ** or not a given identifier is really an SQL keyword. The same thing
176530 ** is substantially reduced. This is important for embedded applications
176586 /* aKWHash[i] is the hash value for the i-th keyword */
176601 ** the next keyword with the same hash is aKWHash[i]-1. */
176616 /* aKWLen[i] is the length (in bytes) of the i-th keyword */
176631 /* aKWOffset[i] is the index into zKWText[] of the start of
176647 /* aKWCode[i] is the parser symbol code for the i-th keyword */
176809 /* Check to see if z[0..n-1] is a keyword. If it is, write the
177008 ** If X is a character that can be used in an identifier then
177009 ** IdChar(X) will be true. Otherwise it is false.
177011 ** For ASCII, any character with the high-order bit set is
177021 ** But the feature is undocumented.
177086 ** WINDOW is treated as a keyword if:
177088 ** * the following token is an identifier, or a keyword that can fallback
177090 ** * the token after than one is TK_AS.
177092 ** OVER is a keyword if:
177095 ** * the next token is either TK_LP or an identifier.
177097 ** FILTER is a keyword if:
177100 ** * the next token is TK_LP.
177284 /* If the next character is a digit, this is a floating point
177368 ** but z[i] is a character not allowed within keywords, so this must
177390 /* If it is not a BLOB literal, then it must be an ID, since no
177562 /* If the pParse->declareVtab flag is set, do not delete any table
177592 ** NULL if anything goes wrong or if zSql is NULL.
177718 ** a legal notice, here is a blessing:
177736 ** This is defined in tokenize.c. We just have to import the definition.
177767 ** Special handling is require for CREATE TRIGGER statements.
177810 ** Whitespace never causes a state transition and is always ignored.
177811 ** This means that a SQL string of all whitespace is invalid.
177815 ** is look for a semicolon that is not part of an string or comment.
177823 ** statement. This is the normal case.
177839 ** used to detect the end of a statement is much simpler
177867 case '\f': { /* White space is ignored */
177978 ** This routine is the same as the sqlite3_complete() routine described
177979 ** above, except that the parameter is required to be UTF-16 encoded, not
178011 ** a legal notice, here is a blessing:
178032 ** a legal notice, here is a blessing:
178040 ** This header file is used by programs that want to link against the
178041 ** FTS3 library. All it does is declare the sqlite3Fts3Init() interface.
178065 ** a legal notice, here is a blessing:
178073 ** This header file is used by programs that want to link against the
178074 ** RTREE library. All it does is declare the sqlite3RtreeInit() interface.
178102 ** a legal notice, here is a blessing:
178110 ** This header file is used by programs that want to link against the
178111 ** ICU extension. All it does is declare the sqlite3IcuInit() interface.
178130 ** This is an extension initializer that is a no-op and always
178131 ** succeeds, except that it fails if the fault-simulation is set
178204 ** pointer to a string constant whose value is the same as the
178205 ** SQLITE_SOURCE_ID C preprocessor macro. Except if SQLite is built using
178236 ** If the following function pointer is not NULL and if
178237 ** SQLITE_ENABLE_IOTRACE is enabled, then messages describing
178245 ** If the following global variable points to a string which is the
178254 ** If the following global variable points to a string which is the
178268 /* If the size of "long double" is not more than 8, then
178269 ** high-precision math is not possible. */
178277 ** actually works is to run an experiment. */
178297 ** This routine is a no-op except on its very first call for the process,
178310 ** thread. Then while the initial invocation of this routine by X is
178311 ** incomplete, it is required that:
178334 ** combination, the work-around is to set the correct pointer
178338 /* If SQLite is already completely initialized, then this call
178348 /* Make sure the mutex subsystem is initialized. If unable to
178350 ** If the system is so sick that we are unable to allocate a mutex,
178351 ** there is not much SQLite is going to be able to do.
178360 ** This operation is protected by the STATIC_MAIN mutex. Note that
178361 ** MutexAlloc() is called for a static mutex prior to initializing the
178386 /* If rc is not SQLITE_OK at this point, then either the malloc
178402 ** The following mutex is what serializes access to the appdef pcache xInit
178403 ** methods. The sqlite3_pcache_methods.xInit() all is embedded in the
178454 /* The following is just a sanity check to make sure SQLite has
178455 ** been compiled correctly. It is important to run this code, but
178461 /* This section of code's only "output" is via assert() statements. */
178483 /* Experimentally determine if high-precision floating point is
178495 ** while any part of SQLite is otherwise in use in any thread. This
178496 ** routine is not threadsafe. But it is safe to invoke this routine
178497 ** on when SQLite is already shut down. If SQLite is already shut down
178498 ** when this routine is invoked, then this routine is a harmless no-op.
178530 ** heap subsystem was shutdown. This is only done if the current call to
178550 ** database connections or memory allocations. This routine is not
178558 /* sqlite3_config() normally returns SQLITE_MISUSE if it is invoked while
178559 ** the SQLite library is in use. Except, a few selected opcodes
178624 ** single argument which is a pointer to an instance of the
178633 ** single argument which is a pointer to an instance of the
178634 ** sqlite3_mem_methods structure. The sqlite3_mem_methods structure is
178664 ** a single parameter which is a pointer to an integer and writes into
178686 ** single argument which is a pointer to an sqlite3_pcache_methods2
178694 ** single argument which is a pointer to an sqlite3_pcache_methods2
178704 /* EVIDENCE-OF: R-06626-12911 The SQLITE_CONFIG_HEAP option is only
178705 ** available if SQLite is compiled with either SQLITE_ENABLE_MEMSYS3 or
178726 ** is NULL, then SQLite reverts to using its default memory allocator
178731 ** revert to its default implementation when sqlite3_initialize() is run
178735 /* EVIDENCE-OF: R-61006-08918 If the memory pointer is not NULL then the
178736 ** alternative memory allocator is engaged to handle all of SQLites
178756 ** The default is NULL. Logging is disabled if the function pointer is
178760 /* MSVC is picky about pulling func ptrs from va lists.
178779 ** argument of type int. If non-zero, then URI handling is globally
178780 ** enabled. If the parameter is zero, then URI handling is globally
178789 ** option takes a single integer argument which is interpreted as a
178812 /* EVIDENCE-OF: R-53367-43190 If either argument to this option is
178813 ** negative, then that argument is changed to its compile-time default.
178880 ** If lookaside is already active, return SQLITE_BUSY.
178882 ** The sz parameter is the number of bytes in each lookaside slot.
178883 ** The cnt parameter is the number of slots. If pStart is NULL the
178884 ** space for the lookaside memory is obtained from sqlite3_malloc().
178885 ** If pStart is not NULL then it is sz*cnt bytes of memory to use for
179136 ** This is the default collating function named "BINARY" which is always
179159 ** This is the collating function named "RTRIM" which is always
179175 ** Return true if CollSeq is the default built-in BINARY.
179185 ** This collating sequence is intended to be used for "case independent
179189 ** At the moment there is only a UTF-8 implementation.
179283 ** if this is not the last copy of the function, do not invoke it. Multiple
179284 ** copies of a single function are created when create_function() is called
179302 ** db. This is called when db is being closed.
179352 ** sqlite3_close_v2() with a NULL pointer argument is a harmless no-op. */
179366 /* If a transaction is open, the disconnectAllVtab() call above
179375 /* Legacy behavior (sqlite3_close() behavior) is to return
179387 /* Closing the handle. Fourth parameter is passed the value 2. */
179409 ** transaction state over all attached databases if zSchema is null.
179453 ** Furthermore, if database connection db is a zombie (meaning that there
179473 ** passed to sqlite3_close (meaning that it is a zombie). Therefore,
179477 /* If a transaction is open, roll it back. This also ensures that if
179479 ** they are reset. And that the required b-tree mutex is held to make
179554 /* The temp-database schema is allocated differently from the other schema
179575 ** Rollback all database files. If tripCode is not SQLITE_OK, then
179589 ** This is important in case the transaction being rolled back has
179750 /* SQLITE_BUSY */ "database is locked",
179751 /* SQLITE_LOCKED */ "database table is locked",
179756 /* SQLITE_CORRUPT */ "database disk image is malformed",
179758 /* SQLITE_FULL */ "database or disk is full",
179768 /* SQLITE_NOLFS */ "large file support is disabled",
179775 /* SQLITE_NOTADB */ "file is not a database",
179806 ** again until a timeout value is reached. The timeout value is
179818 /* This case is for systems that have support for sleeping for fractions of
179859 ** This routine is called when an operation failed to acquire a
179862 ** If this routine returns non-zero, the lock is retried. If it
179965 ** Return true or false depending on whether or not an interrupt is
179981 ** This function is exactly the same as sqlite3_create_function(), except
179982 ** that it is designed to be called by internal code. The difference is
179984 ** is returned and the mallocFailed flag cleared.
180020 /* The SQLITE_INNOCUOUS flag is the same bit as SQLITE_FUNC_UNSAFE. But
180021 ** the meaning is inverted. So flip the bit. */
180027 /* If SQLITE_UTF16 is specified as the encoding type, transform this
180029 ** SQLITE_UTF16NATIVE macro. SQLITE_UTF16 is not used internally.
180031 ** If SQLITE_ANY is specified, add three versions of the function
180066 /* Check if an existing function is being overridden or deleted. If so,
180068 ** is being overridden/deleted but there are no active VMs, allow the
180082 /* Trying to delete a function that does not exist. This is a no-op.
180093 /* If an older version of the function with a configured destructor is
180244 ** The following is the implementation of an SQL function that always
180245 ** fails with an error message stating that the function is used in the
180269 ** this routine is a no-op. If the function does not exist, then create
180303 ** is returned.
180305 ** A NULL trace function means that no tracing is executes. A non-NULL
180306 ** trace is a pointer to a function that is invoked at the start of each
180355 ** profile function is returned.
180357 ** A NULL profile function means that no profiling is executes. A non-NULL
180358 ** profile is a pointer to a function that is invoked at the conclusion of
180359 ** each SQL statement that is run.
180413 ** Register a callback to be invoked each time a row is updated,
180438 ** Register a callback to be invoked each time a transaction is rolled
180464 ** Register a callback to be invoked each time a row is updated,
180521 ** is greater than sqlite3.pWalArg cast to an integer (the value configured by
180568 ** Register a callback to be invoked each time a transaction is written
180658 ** Checkpoint database zDb. If zDb is NULL, or if the buffer zDb points
180663 /* EVIDENCE-OF: R-41613-20553 The sqlite3_wal_checkpoint(D,X) is equivalent to
180670 ** Run a checkpoint on database iDb. This is a no-op if database iDb is
180673 ** If a transaction is open on the database being checkpointed, this
180674 ** function returns SQLITE_LOCKED and a checkpoint is not attempted. If
180675 ** an error occurs while running the checkpoint, an SQLite error code is
180679 ** associated with the specific b-tree being checkpointed is taken by
180680 ** this function while the checkpoint is running.
180682 ** If iDb is passed SQLITE_MAX_DB then all attached databases are
180683 ** checkpointed. If an error is encountered it is returned immediately -
180684 ** no attempt is made to checkpoint any remaining databases.
180686 ** Parameter eMode is one of SQLITE_CHECKPOINT_PASSIVE, FULL, RESTART
180824 ** above. If this is the case, then the db->mallocFailed flag needs to
180836 ** Return the most recent error code generated by an SQLite routine. If NULL is
180871 ** Create a new collating function for database "db". The name is zName
180872 ** and the encoding is enc.
180887 /* If SQLITE_UTF16 is specified as the encoding type, transform this
180889 ** SQLITE_UTF16NATIVE macro. SQLITE_UTF16 is not used internally.
180901 /* Check if this call is removing or replacing an existing collation
181006 ** If an invalid limit index is supplied, report -1.
181008 ** new limit is negative.
181025 ** there is a hard upper bound set at compile-time by a C preprocessor
181026 ** macro called SQLITE_MAX_NAME. (The "_LIMIT_" in the name is changed to
181061 ** This function is used to parse both URIs and non-URI filenames passed by the
181065 ** The first argument to this function is the name of the VFS to use (or
181068 ** itself. When this function is called the *pFlags variable should contain
181073 ** If successful, SQLITE_OK is returned. In this case *ppVfs is set to point to
181074 ** the VFS that should be used to open the database file. *pzFile is set to
181076 ** stored in *pzFile is a database name acceptable to sqlite3_uri_parameter()
181077 ** and is in the same format as names created using sqlite3_create_filename().
181081 ** If an error occurs, then an SQLite error code is returned and *pzErrMsg
181083 ** message. It is the responsibility of the caller to eventually release
181113 /* Make sure the SQLITE_OPEN_URI flag is set to indicate to the VFS xOpen
181121 memset(zFile, 0, 4); /* 4-byte of 0x00 is the start of DB name marker */
181131 ** file://host/path or file:////host/path. But 5 leading slashes is a
181174 /* This branch is taken when "%00" appears within the URI. In this
181187 /* If ENABLE_URI_00_ERROR is defined, "%00" in a URI is an error. */
181339 ** is UTF-8 encoded.
181439 ** is disabled. It can still be used either by defining
181462 ** Legacy behavior is 3 (double-quoted string literals are allowed anywhere)
181463 ** and so that is the default. But developers are encouraged to use
181523 ** conversions. The only error that can occur here is a malloc() failure.
181553 ** Throw an error if any non-sense combination is used. If we
181605 /* The default safety_level for the main database is FULL; for the temp
181606 ** database it is OFF. This matches the pager layer defaults.
181619 ** database schema yet. This is delayed until the first time the database
181620 ** is accessed.
181685 /* Opening a db handle. Fourth parameter is passed 0. */
181928 ** This function is now an anachronism. It used to be used to recover from a
181937 ** Test to see whether or not the database connection is in autocommit
181938 ** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on
181939 ** by default. Autocommit is disabled by a BEGIN statement and reenabled
181961 ** a low-level error is first detected.
182001 ** This is a convenience routine that makes sure that all thread-specific
182004 ** SQLite no longer uses thread-specific data so this routine is now a
182005 ** no-op. It is retained for historical compatibility.
182024 int *pAutoinc /* OUTPUT: True if column is auto-increment */
182059 /* Find the column for which info is requested */
182085 ** and there is no explicitly declared IPK column.
182087 ** 2. The table is not a view and the column name identified an
182245 ** is built into SQLite. Cases:
182249 ** x if the schema cookie is zero. This case
182250 ** is convenient to use with database fuzzers
182277 ** If b is true, then activate the SQLITE_FkNoAction setting. If b is
182278 ** false then clearn that setting. If the SQLITE_FkNoAction setting is
182301 ** is an array of integers that defines the test. Return -1 on a
182315 ** Arrange to invoke xCallback() whenever sqlite3FaultSim() is called,
182316 ** if xCallback is not NULL.
182319 ** is called immediately after installing the new callback and the return
182363 ** while any database connection is open results in undefined and
182381 ** assert() was enabled at compile-time. If X is true and assert()
182382 ** is enabled, then the return value is true. If X is true and
182383 ** assert() is disabled, then the return value is zero. If X is
182384 ** false and assert() is enabled, then the assertion fires and the
182385 ** process aborts. If X is false and assert() is disabled, then the
182386 ** return value is zero.
182426 ** The return value is ALWAYS(X) if X is true, or 0 if X is false.
182428 ** The recommended test is X==2. If the return value is 2, that means
182429 ** ALWAYS() and NEVER() are both no-op pass-through macros, which is the
182430 ** default setting. If the return value is 1, then ALWAYS() is either
182431 ** hard-coded to true or else it asserts if its argument is false.
182432 ** The first behavior (hard-coded to true) is the case if
182433 ** SQLITE_TESTCTRL_ASSERT shows that assert() is disabled and the second
182434 ** behavior (assert if the argument to ALWAYS() is false) is the case if
182435 ** SQLITE_TESTCTRL_ASSERT shows that assert() is enabled.
182442 ** // ALWAYS(x) asserts that x is true. NEVER(x) asserts x is false.
182444 ** // ALWAYS(x) is a constant 1. NEVER(x) is a constant 0.
182457 ** SQLite is running:
182472 ** argument N is a bitmask of optimizations to be disabled. For normal
182473 ** operation N should be 0. The idea is that a test program (like the
182476 ** is obtained in every case.
182486 ** If parameter onoff is 1, subsequent calls to localtime() fail.
182521 ** Set or clear a flag that indicates that the database file is always well-
182522 ** formed and never corrupt. This flag is clear by default, indicating that
182535 ** and tbl_name fields of the sqlite_schema table. This is normally
182536 ** on, but it is sometimes useful to turn it off for testing.
182540 ** is useful to make it easier to reach strange internal error states
182541 ** during testing. The EXTRA_SCHEMA_CHECKS setting is always enabled
182550 ** By default this is 0x7ffffffe (over 2 billion), but that value is
182551 ** too big to test in a reasonable amount of time, so this control is
182593 ** This test control is used to create imposter tables. "db" is a pointer
182594 ** to the database connection. dbName is the database name (ex: "main" or
182596 ** or off. "tnum" is the root page of the b-tree to which the imposter
182604 ** the schema to be reparsed the next time it is needed. This has the
182627 ** This test control (only available when SQLite is compiled with
182630 ** which are never exercised. If any state is missed, make the
182662 ** file. The seek-counter is written into *pnSeek and is then reset.
182663 ** The seek-count is only available if compiled with SQLITE_DEBUG.
182675 ** "ptr" is a pointer to a u32.
182736 ** If "id" is an integer between 1 and SQLITE_NTUNE then set the value
182737 ** of the id-th tuning parameter to *piValue. If "id" is between -1
182765 ** Activate or deactivate validation of JSONB that is generated from
182766 ** text. Off by default, as the validation is slow. Validation is
182769 ** If onOff is initially 1, then turn it on. If onOff is initially
182770 ** off, turn it off. If onOff is initially -1, then change onOff
182792 ** consecutively in memory, in that order. The database filename is prefixed
182817 ** and query parameters. The pointer returned is valid for use by
182856 ** Free memory obtained from sqlite3_create_filename(). It is a severe
182868 ** This is a utility routine, useful to VFS implementations, that checks
182872 ** The zFilename argument is the filename pointer passed into the xOpen()
182873 ** method of a VFS implementation. The zParam argument is the name of the
182913 sqlite3_int64 bDflt /* return if parameter is missing */
182927 ** It is an error to pass this routine a filename string that was not
182928 ** passed into the VFS from the SQLite core. Doing so is similar to
182929 ** passing free() a pointer that was not obtained from malloc() - it is
182966 ** Return the name of the N-th database schema. Return NULL if N is out
183000 ** Return 1 if database is read-only or 0 if read/write. Return -1 if
183154 ** is not required for a match.
183173 /* Since nOpt is normally in single digits, a linear search is
183186 ** Return the N-th compile-time option string. If N is out of range,
183206 ** a legal notice, here is a blessing:
183220 /* Omit this entire file if SQLITE_ENABLE_UNLOCK_NOTIFY is not defined. */
183238 ** is not NULL. This variable may only accessed while the STATIC_MAIN
183239 ** mutex is held.
183245 ** This function is a complex assert() that verifies the following
183254 ** 3) If the argument db is not NULL, then none of the entries in the
183256 ** set to db. This is used when closing connection db.
183282 ** db is not currently a part of the list, this function is a no-op.
183296 ** Add connection db to the blocked connections list. It is assumed
183297 ** that it is not already a part of the list.
183331 ** This is called after connection "db" has attempted some operation
183334 ** cache. pOther is found by looking at db->pBlockingConnection.
183336 ** If there is no blocking connection, the callback is invoked immediately,
183339 ** If pOther is already blocked on db, then report SQLITE_LOCKED, to indicate
183391 sqlite3ErrorWithMsg(db, rc, (rc?"database is deadlocked":0));
183397 ** This function is called while stepping or preparing a statement
183412 ** This function is called when
183419 ** 1) If the sqlite3.pBlockingConnection member of a list entry is
183422 ** 2) If the sqlite3.pUnlockConnection member of a list entry is
183472 ** be passed to the unlock-notify callback is larger than the
183476 ** This is a difficult situation to handle. Returning an error
183477 ** code to the caller is insufficient, as even if an error code
183478 ** is returned the transaction on connection db will still be
183487 ** requiring any dynamic allocation. This is sub-optimal because
183492 ** connections. But it is the best that can be done under the
183526 ** This is called when the database connection passed as an argument is
183527 ** being closed. The connection is removed from the blocked list.
183544 ** a legal notice, here is a blessing:
183552 ** This is an SQLite module implementing full-text search.
183556 ** The code in this file is only compiled if:
183558 ** * The FTS3 module is being built as an extension
183559 ** (in which case SQLITE_CORE is not defined), or
183561 ** * The FTS3 module is being built into the core of
183562 ** SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
183565 /* The full-text index is stored in a series of b+tree (-like)
183574 ** The basic unit of encoding is a variable-length integer called a
183587 ** This is similar in concept to how sqlite encodes "varints" but
183588 ** the encoding is not the same. SQLite varints are big-endian
183602 ** A docid is the unique integer identifier for a single document.
183603 ** A position is the index of a word within the document. The first
183607 ** option. But that functionality is no longer supported.
183609 ** A doclist is stored like this:
183627 ** memory. A "position" is an index of a token in the token stream
183630 ** ending a position list array. POS_END is 0. POS_COLUMN is 1.
183638 ** The 123 value is the first docid. For column zero in this document
183641 ** new column is column number 1. There are two positions at 12 and 45
183643 ** 234 at I is the delta to next docid (357). It has one position 70
183646 ** A "position-list" is the list of positions for multiple columns for
183647 ** a single docid. A "column-list" is the set of positions for a single
183681 ** of a node is reached, the next term is in the node with the next
183684 ** New data is spilled to a new leaf node when the current node
183685 ** exceeds LEAF_MAX bytes (default 2048). New data which itself is
183686 ** larger than STANDALONE_MIN (default 1024) is placed in a standalone
183688 ** these settings is to pack together groups of small doclists while
183690 ** assumption is that large doclists represent terms which are more
183695 ** node rather than splitting into 2k and .5k nodes. My intuition is
183701 ** to describe what data is stored by the each subtree. Interior
183726 ** is encoded. The subtree at iBlockid will contain all terms less
183727 ** than the first term encoded (or all terms if no term is encoded).
183732 ** child is "something", and the leftmost term of the right child is
183733 ** "wicked", only "w" is stored).
183735 ** New data is spilled to a new interior node at the same height when
183748 ** The root node is the top node of the segment's tree after encoding
183751 ** node requires more than ROOT_MAX bytes, it is flushed to %_segments
183752 ** and a new root interior node is generated (which should always fit
183756 ** The meta-information in the segment directory is:
183765 ** If the root node is a leaf node, then start_block,
183778 ** is populated like level 0, and eventually MERGE_COUNT level 1
183793 ** sorting). 8 is about 20% slower than 16, 4 about 50% slower than
183812 ** argument for MERGE_COUNT of 16. Also, it is possible/likely that
183821 ** index when a document is deleted or updated. For deletions, we
183836 ** a legal notice, here is a blessing:
183859 ** FTS4 is really an extension for FTS3. It is enabled using the
183887 ** sqlite3_tokenizer_module is a singleton defining the tokenizer
183888 ** interface functions. This is essentially the class structure for
183891 ** sqlite3_tokenizer is used to define a particular tokenizer, perhaps
183894 ** sqlite3_tokenizer_cursor is generated by a tokenizer to generate
183908 ** implementation is registered, the caller provides a pointer to
183912 ** When an fts3 table is created, it passes any arguments passed to
183920 ** method is called. It returns an sqlite3_tokenizer_cursor object
183940 ** the following SQL is executed:
183944 ** then argc is set to 2, and the argv[] array contains pointers
183948 ** code. If SQLITE_OK is returned, then *ppTokenizer should be set
183967 ** is responsible for ensuring that the input buffer remains valid
183968 ** until the cursor is closed (using the xClose() method).
183991 ** of this buffer in bytes. The input text that generated the token is
183998 ** The buffer *ppToken is set to point at is managed by the tokenizer
183999 ** implementation. It is only required to be valid until the next call
184048 ** a legal notice, here is a blessing:
184055 ** This is the header file for the generic hash-table implementation
184067 /* A complete hash table is an instance of the following structure.
184087 /* Each element in the hash table is an instance of the following
184090 ** Again, this structure is intended to be opaque, but it can't really
184091 ** be opaque because it is used by macros.
184102 ** FTS3_HASH_STRING pKey points to a string that is nKey bytes long
184104 ** is respected in comparisons.
184107 ** memcmp() is used to compare keys.
184109 ** A copy of the key is made if the copyKey parameter to fts3HashInit is 1.
184133 ** Macros for looping over all elements of a hash table. The idiom is
184164 ** limit is that it may allow very large queries to use large amounts
184180 ** This is the maximum amount of data (in bytes) to store in the
184181 ** Fts3Table.pendingTerms hash table. Normally, the hash table is
184183 ** and used to create a new segment when the transaction is committed.
184184 ** However if this limit is reached midway through a transaction, a new
184185 ** segment is created and the hash table cleared immediately.
184205 ** Maximum length of a varint encoded integer. The varint format is different
184206 ** from that used by SQLite, so the maximum length is 10, not 9.
184217 ** It is possible to determine which index a b+-tree belongs to based on the
184219 ** that the b+-tree belongs to is (L<<10). In other words, all b+-trees with
184223 ** It is considered impossible for an index to use more than 1024 levels. In
184231 ** The testcase() macro is only used by the amalgamation. If undefined,
184245 ** The assert_fts3_nc() macro is similar to the assert() macro, except that it
184246 ** is used for assert() conditions that are true only if it can be
184247 ** guranteed that the database is not corrupt.
184295 ** Activate assert() only if SQLITE_TEST is enabled.
184302 ** The TESTONLY macro is used to enclose variable declarations or
184341 ** A connection to a fulltext index is an instance of the following
184363 ** statements is run and reset within a single virtual table API call.
184383 ** The following array of hash tables is used to buffer pending index
184386 ** The current language id is stored in variable iPrevLangid.
184389 ** there is an entry in the aIndex[] array. Index 0 is an index of all the
184391 ** is an index of prefixes of a specific length.
184396 ** tables are flushed to disk. Variable iPrevDocid is the docid of the most
184421 /* True to disable the incremental doclist optimization. This is controled
184447 u8 bSeekStmt; /* True if pStmt is a seek */
184472 ** The Fts3Cursor.eSearch member is always set to one of the following.
184474 ** FTS3_FULLTEXT_SEARCH. If so, then Fts3Cursor.eSearch - 2 is the index
184480 ** Because the LHS of the MATCH operator is 2nd column "b",
184512 ** A "phrase" is a sequence of one or more tokens that must match in
184513 ** sequence. A single token is the base case and the most common case.
184523 /* Variables above this point are populated when the expression is
184533 int bIncr; /* True if doclist is loaded incrementally */
184536 /* Used by sqlite3Fts3EvalPhrasePoslist() if this is a descendent of an
184542 ** a MATCH expression. Everything above is part of the evaluation phase.
184552 ** If Fts3Expr.eType is FTSQUERY_PHRASE and isLoaded is true, then aDoclist
184555 ** "Length" field found in doclists stored on disk is omitted from this
184558 ** Variable aMI is used only for FTSQUERY_NEAR nodes to store the global
184559 ** matchinfo data. If it is not NULL, it points to an array of size nCol*3,
184560 ** where nCol is the number of columns in the queried FTS table. The array
184561 ** is populated as follows:
184567 ** The aMI array is allocated using sqlite3_malloc(). It should be freed
184568 ** when the expression node is.
184580 u8 bEof; /* True this expression is at EOF already */
184581 u8 bStart; /* True if iDocid is valid */
184582 u8 bDeferred; /* True if this expression is entirely deferred */
184591 ** four values is in order of precedence when parsing expressions. For
184596 ** is equivalent to:
184806 ** This variable is set to false when running tests for which the on disk
184807 ** structures should not be corrupt. Otherwise, true. If it is false, extra
184809 ** only true if it is guaranteed that the fts3 database is not corrupt.
184818 ** The number of bytes written is returned.
184864 ** The value is stored in *v.
184874 ** The value is stored in *v.
184897 ** Similar to sqlite3Fts3GetVarint(), except that the output is truncated to
184898 ** a non-negative 32-bit integer before it is returned.
184935 ** the quote characters. The conversion is done in-place. If the
184937 ** is a no-op.
184955 /* If the first byte was a '[', then the close-quote character is a ']' */
184983 ** When this function is called, *pp points to the first byte following a
184984 ** varint that is part of a doclist (or position-list, or any other list
184989 ** varint is part of.
185000 ** interested in. So, unless the doclist is corrupt, the 0x80 bit is
185051 ** and then evaluate those statements. The success code is written
185054 ** If *pRc is initially non-zero then this routine is a no-op.
185109 ** passed as the first argument. This is done as part of the xConnect()
185112 ** If *pRc is non-zero when this function is called, it is a no-op.
185113 ** Otherwise, if an error occurs, an SQLite error code is stored in *pRc
185165 ** required by the FTS3 table passed as the only argument. This is done
185168 ** If the p->bHasDocsize boolean is true (indicating that this is an
185233 ** If *pRc is non-zero when this function is called, it is a no-op.
185234 ** Otherwise, if an error occurs, an SQLite error code is stored in *pRc
185326 ** is the callers responsibility to call sqlite3_free() to release this
185355 ** from left to write. If parameter zFunc is not NULL, then instead of
185356 ** being returned directly each column of text data is passed to an SQL
185357 ** function named zFunc first. For example, if zFunc is "unzip" and the
185359 ** string is returned:
185364 ** is the responsibility of the caller to eventually free it.
185366 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op (and
185367 ** a NULL pointer is returned). Otherwise, if an OOM error is encountered
185368 ** by this function, NULL is returned and *pRc is set to SQLITE_NOMEM. If
185369 ** no error occurs, *pRc is left unmodified.
185409 ** Return a list of N comma separated question marks, where N is the number
185413 ** If argument zFunc is not NULL, then all but the first question mark
185414 ** is preceded by zFunc and an open bracket, and followed by a closed
185415 ** bracket. For example, if zFunc is "zip" and the FTS3 table has three
185416 ** user-defined text columns, the following string is returned:
185421 ** is the responsibility of the caller to eventually free it.
185423 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op (and
185424 ** a NULL pointer is returned). Otherwise, if an OOM error is encountered
185425 ** by this function, NULL is returned and *pRc is set to SQLITE_NOMEM. If
185426 ** no error occurs, *pRc is left unmodified.
185474 ** If *pp does not being with a decimal digit SQLITE_ERROR is returned and
185475 ** the output value undefined. Otherwise SQLITE_OK is returned.
185477 ** This function is used when parsing the "prefix=" FTS4 parameter.
185496 ** This function is called to allocate an array of Fts3Index structures
185502 ** Argument zParam is passed the value of the "prefix=" option if one was
185505 ** If no error occurs, SQLITE_OK is returned and *apIndex set to point to
185506 ** the allocated array. *pnIndex is set to the number of elements in the
185507 ** array. If an error does occur, an SQLite error code is returned.
185509 ** Regardless of whether or not an error is returned, it is the responsibility
185557 ** This function is called when initializing an FTS4 table that uses the
185561 ** The third argument passed to this function is the value passed to the
185571 ** *pazCol: Set to point to an array of *pnCol strings. Each string is
185574 ** is the responsibility of the caller to free this allocation
185577 ** If the table cannot be found, an error code is returned and the output
185578 ** variables are undefined. Or, if an OOM is encountered, SQLITE_NOMEM is
185646 ** This function is the implementation of both the xConnect and xCreate
185724 ** + If there is a tokenizer specification included in the arguments,
185732 /* Check if this is a tokenizer specification */
185741 /* Check if it is an FTS4 special argument. */
185832 /* Otherwise, the argument is a column name. */
185987 /* If this is an xCreate call, create the underlying tables in the
186001 /* Figure out the page-size for the database. This is required in order to
186038 ** work is done in function fts3InitVtab().
186063 ** extension is currently being used by a version of SQLite too old to
186064 ** support estimatedRows. In that case this function is a no-op.
186076 ** extension is currently being used by a version of SQLite too old to
186077 ** support index-info flags. In that case this function is a no-op.
186109 /* By default use a full table scan. This is an expensive option,
186111 ** strategy is possible.
186116 int bDocid; /* True if this constraint is on docid */
186144 ** If there is more than one MATCH constraint available, use the first
186145 ** one encountered. If there is both a MATCH constraint and a direct
186146 ** rowid/docid lookup, prefer the MATCH strategy. This is done even
186147 ** though the rowid/docid lookup is faster than a MATCH query, selecting
186244 ** Or, if that statement handle is one created by fts3CursorSeekStmt(),
186245 ** and the Fts3Table.pSeekStmt slot is currently NULL, save the statement
186320 ** Position the pCsr->pStmt statement so that it is on the row
186341 ** table is missing a row that is present in the full-text index.
186357 ** This function is used to process a single interior node when searching
186358 ** a b-tree for a term or term prefix. The node data is passed to this
186359 ** function via the zNode/nNode parameters. The term to search for is
186362 ** If piFirst is not NULL, then this function sets *piFirst to the blockid
186365 ** If piLast is not NULL, then *piLast is set to the right-most child node
186366 ** that heads a sub-tree that may contain a term for which zTerm/nTerm is
186369 ** If an OOM error occurs, SQLITE_NOMEM is returned. Otherwise, SQLITE_OK.
186392 ** Even if the data structure on disk is corrupted, this (reading two
186393 ** varints from the buffer) does not risk an overread. If zNode is a
186397 ** contents, or two zero bytes. Or, if the node is read from the %_segments
186445 ** the interior node. If the specified term is greater than or equal
186450 ** If the interior node term is larger than the specified term, then
186481 ** or terms for which the specified term is a prefix.
186483 ** If piLeaf is not NULL, then *piLeaf is set to the blockid of the
186485 ** If piLeaf2 is not NULL, then *piLeaf2 is set to the blockid of the
186487 ** term is a prefix.
186489 ** It is possible that the range of returned leaf nodes does not contain
186490 ** the specified term or any terms for which it is a prefix. However, if the
186493 ** never loads leaf nodes into memory), it is not possible to be sure.
186495 ** If an error occurs, an error code other than SQLITE_OK is returned.
186548 ** This function is used to create delta-encoded serialized lists of FTS3
186562 ** When this function is called, *ppPoslist is assumed to point to the
186566 ** A position list is list of positions (delta encoded) and columns for
186571 ** If pp is not NULL, then the contents of the position list are copied
186572 ** to *pp. *pp is set to point to the first byte past the last byte copied
186579 /* The end of a position list is marked by a zero encoded as an FTS3
186580 ** varint. A single POS_END (0) byte. Except, if the 0 byte is preceded by
186581 ** a byte with the 0x80 bit set, then it is not a varint 0, but the tail
186584 ** The following while-loop moves pEnd to point to the first byte that is not
186606 ** When this function is called, *ppPoslist is assumed to point to the
186610 ** A column-list is list of delta-encoded positions for a single column
186613 ** The column-list is terminated either by a POS_COLUMN varint (1) or
186617 ** If pp is not NULL, then the contents of the column-list are copied
186618 ** to *pp. *pp is set to point to the first byte past the last byte copied
186620 ** is not copied into *pp.
186626 /* A column-list is terminated by either a 0x01 or 0x00 byte that is
186651 ** This function is used to help parse position-lists. When this function is
186665 ** of the previous position is needed in order to compute the value of
186683 ** If parameter iCol is not 0, write an POS_COLUMN (1) byte followed by
186706 ** updated appropriately. The caller is responsible for insuring
186707 ** that there is enough space in *pp to hold the complete output.
186746 ** A column-list is a list of non-negative delta-encoded varints, each
186747 ** incremented by 2 before being stored. Each list is terminated by a
186749 ** and writes the results to buffer p. p is left pointing to the byte
186750 ** after the list written. No terminator (POS_END or POS_COLUMN) is
186787 ** This function is used to merge two position lists into one. When it is
186788 ** called, *pp1 and *pp2 must both point to position lists. A position-list is
186801 ** If isSaveLeft is 0, an entry is added to the output position list for
186813 int isExact, /* If *pp1 is exactly nTokens before *pp2 */
186929 ** The output position list - written to *pp - is a copy of *pp2 with those
186967 ** An instance of this function is used to merge together the (potentially
186978 ** This function is used to read a single varint from a buffer. Parameter
186979 ** pEnd points 1 byte past the end of the buffer. When this function is
186981 ** has been reached. In this case *pp is set to 0 and the function returns.
186983 ** If *pp does not point to or past pEnd, then a single varint is read
186984 ** from *pp. *pp is then set to point 1 byte past the end of the read varint.
186986 ** If bDescIdx is false, the value read is added to *pVal before returning.
186987 ** If it is true, the value read is subtracted from *pVal before this
187010 ** This function is used to write a single varint to a buffer. The varint
187011 ** is written to *pp. Before returning, *pp is set to point 1 byte past the
187014 ** If *pbFirst is zero when this function is called, the value written to
187015 ** the buffer is that of parameter iVal.
187017 ** If *pbFirst is non-zero when this function is called, then the value
187018 ** written is either (iVal-*piPrev) (if bDescIdx is zero) or (*piPrev-iVal)
187019 ** (if bDescIdx is non-zero).
187048 ** This macro is used by various functions that merge doclists. The two
187050 ** bDescDoclist is 0 when this macro is invoked, then it returns (i1-i2).
187066 ** If no error occurs, *paOut is set to point at an sqlite3_malloc'd buffer
187067 ** containing the output doclist and SQLITE_OK is returned. In this case
187068 ** *pnOut is set to the number of bytes in the output doclist.
187070 ** If an error occurs, an SQLite error code is returned. The output values
187096 ** then the first docid in each list is simply encoded as a varint. For
187097 ** each subsequent docid, the varint stored is the difference between the
187098 ** current and previous docid (a positive number - since the list is in
187101 ** The first docid written to the output is therefore encoded using the
187102 ** same number of bytes as it is in whichever of the input lists it is
187111 ** However, if the first docid copied to the output is a negative number,
187116 ** The space required to store the output is therefore the sum of the
187166 ** doclist for which there is a position in the left-hand input doclist
187173 ** The right-hand input doclist is overwritten by this function.
187244 ** The value returned is the number of bytes written to pOut (if any).
187294 ** If an OOM error occurs, return SQLITE_NOMEM. In this case it is
187340 ** as the first argument. The merge is an "OR" merge (see function
187343 ** This function is called with the doclist for each term that matches
187346 ** doclists to merge, the merging is done pair-wise using the TermSelect
187349 ** This function returns SQLITE_OK if the merge is successful, or an
187359 /* If this is the first term selected, copy the doclist to the output
187363 ** allocation. This is so as to ensure that the buffer is big enough
187366 ** required (since the size of [doclistA AND doclistB] is always less
187367 ** than or equal to the size of [doclistA] in that case). But this is
187373 ** Similar padding is added in the fts3DoclistOrMerge() function.
187465 /* If iLevel is less than 0 and this is not a scan, include a seg-reader
187466 ** for the pending-terms. If this is a scan, then this call must be being
187494 /* If zTerm is not NULL, and this segment is not stored entirely on its
187554 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
187570 ** if isPrefix is true, to scan the doclist for all terms for which
187571 ** zTerm/nTerm is a prefix. If successful, return SQLITE_OK and write
187575 ** It is the responsibility of the caller to free this object by eventually
187578 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
187579 ** Output parameter *ppSegcsr is set to 0 if an error occurs.
187699 ** If the isPoslist argument is true, then it is assumed that the doclist
187700 ** contains a position-list following each docid. Otherwise, it is assumed
187701 ** that the doclist is simply a list of docids stored as delta encoded
187726 ** Return SQLITE_OK if nothing goes wrong. SQLITE_OK is returned
187752 ** If the numeric type of argument pVal is "integer", then return it
187767 ** This is the xFilter interface for the virtual table. See
187778 ** column on the left-hand side of the MATCH operator is column
187779 ** number idxNum-FTS3_FULLTEXT_SEARCH, 0 indexed. argv[0] is the right-hand
187900 ** This is the xEof method of the virtual table. SQLite calls this
187913 ** This is the xRowid method. The SQLite core calls this routine to
187925 ** This is the xColumn method, called by SQLite to request a value from
187971 /* A user column. Or, if this is a full-table scan, possibly the
187985 ** This function is the implementation of the xUpdate callback used by
187986 ** FTS3 virtual tables. It is invoked by SQLite each time a row is to be
188009 ** if the height of the input segment b-trees is N, and input segments
188011 ** of an incremental-merge requires writing (8*(1+N)) blocks. N is usually
188013 ** merge is somewhere between 8 and 24 blocks. To avoid this overhead
188015 ** is only attempted if it will write at least 64 leaf blocks. Hence
188019 ** of blocks from the segments table. But this is not considered overhead
188049 ** If it is currently unknown whether or not the FTS table has an %_stat
188091 ** Implementation of xCommit() method. This is a no-op. The contents of
188133 ** poslist). This is an 0x00 byte preceded by some byte that does not
188144 ** Normally. The other case is that p==pStart and the poslist to return
188145 ** is the first in the doclist. In this case do not skip forward 2 bytes.
188147 ** is required for cases where the first byte of a doclist and the
188148 ** doclist is empty. For example, if the first docid is 10, a doclist
188162 ** If the value passed as the third argument is a blob of size
188164 ** output variable *ppCsr and SQLITE_OK is returned. Otherwise, an error
188165 ** message is written to context pContext and SQLITE_ERROR returned. The
188166 ** string passed via zFunc is used as part of the error message.
188257 ** Example usage is:
188261 ** where 't' is the name of an FTS3 table.
188365 /* As it happens, the pending terms table is always empty here. This is
188446 ** This is a no-op.
188474 ** Return true if zName is the extension on one of the shadow tables used
188496 int isQuick, /* True if this is a quick_check */
188549 ** This function is registered as the module destructor (called when an
188550 ** FTS3 enabled database connection is closed). It frees the memory
188582 ** Initialize the fts3 extension. If this extension is built as part
188583 ** of the sqlite library, then this function is called directly by
188584 ** SQLite. If fts3 is built as a dynamically loadable extension, this
188585 ** function is called by the sqlite3_extension_init() entry point.
188648 ** the four scalar functions. If this is successful, register the
188690 ** An Fts3SegReader object is a cursor that can seek or scan a range of
188696 ** segment b-tree (if the term is not a prefix or it is a prefix for which
188735 ** It is merged into the main doclist stored in p->doclist.aAll/nAll.
188741 ** SQLITE_OK is returned if successful, or SQLITE_NOMEM if an error occurs.
188805 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
188835 ** This function is called on each phrase after the position lists for
188842 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
188949 ** This function is called for each Fts3Phrase in a full-text query
188954 ** If parameter bOptOk is true, then the phrase may (or may not) use the
188955 ** incremental loading strategy. Otherwise, the entire doclist is loaded into
188958 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
188965 /* Determine if doclists may be loaded from disk incrementally. This is
188966 ** possible if the bOptOk argument is true, the FTS doclists will be
189008 ** This function is used to iterate backwards (from the end to start)
189009 ** through doclists. It is used by this module to iterate through phrase
189018 int bDescIdx, /* True if the doclist is desc */
189074 int bDescIdx, /* True if the doclist is desc */
189108 ** to true if EOF is reached.
189166 ** Token pToken is an incrementally loaded token that is part of a
189179 u8 *pbEof /* OUT: True if iterator is at EOF */
189219 ** If there is no "next" entry and no error occurs, then *pbEof is set to
189220 ** 1 before returning. Otherwise, if no error occurs and the iterator is
189221 ** successfully advanced, *pbEof is set to 0.
189236 /* This is only called if it is guaranteed that the phrase has at least
189237 ** one incremental token. In which case the bIncr flag is set. */
189323 ** If there is no "next" entry and no error occurs, then *pbEof is set to
189324 ** 1 before returning. Otherwise, if no error occurs and the iterator is
189325 ** successfully advanced, *pbEof is set to 0.
189352 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
189353 ** Otherwise, fts3EvalPhraseStart() is called on all phrases within the
189354 ** expression. Also the Fts3Expr.bDeferred variable is set to true for any
189357 ** If parameter bOptOk is zero, then it is guaranteed that the
189360 ** Or, if bOptOk is non-zero, then one or more tokens within the expression
189361 ** may be loaded incrementally, meaning doclist.aAll/nAll is not available.
189363 ** If an error occurs within this function, *pRc is set to an SQLite error
189391 ** An array of the following structures is assembled as part of the process
189393 ** of the xFilter() method). There is one element in the array for each
189398 ** NOT). When determining tokens to defer, each AND/NEAR cluster is considered
189399 ** separately. The root of a tokens AND/NEAR cluster is stored in
189413 ** This function is used to populate an allocated Fts3TokenAndCost array.
189415 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
189416 ** Otherwise, if an error occurs during execution, *pRc is set to an
189467 ** The average document size in pages is calculated by first calculating
189468 ** determining the average size in bytes, B. If B is less than the amount
189470 ** this database, then the average docsize is 1. Otherwise, it is 1 plus
189476 /* The average document size, which is required to calculate the cost
189480 ** Entry 0 of the %_stat table is a blob containing (nCol+1) FTS3
189481 ** varints, where nCol is the number of columns in the FTS3 table.
189482 ** The first varint is the number of documents currently stored in
189521 ** This function is called to select the tokens (if any) that will be
189522 ** deferred. The array aTC[] has already been populated when this is
189525 ** This function is called once for each AND/NEAR cluster in the
189530 ** If no error occurs, SQLITE_OK is returned and sqlite3Fts3DeferToken()
189531 ** called on each token to defer. Otherwise, an SQLite error code is
189551 ** option. The reason being that it is not guaranteed that the content
189553 ** causing any problems, the deferred token optimization is completely
189560 ** associated with the tokens spill onto overflow pages, or if there is
189585 ** After each token doclist is loaded, merge it with the others from the
189589 ** Let nOther be the number of other phrases for which it is certain that
189593 ** loading N or more overflow pages into memory, where N is computed as:
189613 ** subsequent) tokens is greater than the estimated number of pages
189623 ** overflowing the 32-bit integer it is stored in. */
189627 /* Either this is the cheapest token in the entire query, or it is
189656 ** This function is called from within the xFilter method. It initializes
189726 ** This function is called to edit the position list associated with
189732 ** Parameter nNear is passed the NEAR distance of the expression (5 in
189733 ** the example above). When this function is called, *paPoslist points to
189734 ** the position list, and *pnToken is the number of phrase tokens in the
189741 ** leaves 0 positions, zero is returned. Otherwise, non-zero.
189743 ** Before returning, *paPoslist is set to point to the position lsit
189744 ** associated with pPhrase. And *pnToken is set to the number of tokens in
189783 ** This function is a no-op if *pRc is other than SQLITE_OK when it is called.
189786 ** matching rows in docid order. Ascending order if Fts3Cursor.bDesc is zero,
189787 ** or descending if it is non-zero.
189789 ** If an error occurs, *pRc is set to an SQLite error code. Otherwise, if
189792 ** Fts3Expr.bEof (non-zero if EOF - there is no next row)
189795 ** If the expression is of type FTSQUERY_PHRASE, and the expression is not
189803 ** matching row. This is usually true, but there are the following exceptions:
189806 ** entirely of deferred tokens, it is assumed to match every row in
189807 ** the db. In this case the position-list is not populated at all.
189810 ** more non-deferred tokens, then the expression is advanced to the
189812 ** words, if the phrase is "A B C", and "B" is deferred, the expression
189813 ** is advanced to the next row that contains an instance of "A * C",
189815 ** is populated as for "A * C" before returning.
189817 ** 2. NEAR is treated as AND. If the expression is "x NEAR y", it is
189820 ** See sqlite3Fts3EvalTestDeferred() for details on testing if a row is
189840 /* LHS is entirely deferred. So we assume it matches every row.
189846 /* RHS is entirely deferred. So we assume it matches every row.
189951 ** If *pRc is not SQLITE_OK, or if pExpr is not the root node of a NEAR
189958 ** If the current row is a match, the position list associated with each
189959 ** phrase in the NEAR expression is edited in place to contain only those
189962 ** match the current row, 0 is returned. The position lists may or may not
189963 ** be edited if 0 is returned.
189968 /* The following block runs if pExpr is the root of a NEAR query.
189973 ** which is represented in tree form as:
189984 ** The right-hand child of a NEAR node is always a phrase. The
190037 ** This function is a helper function for sqlite3Fts3EvalTestDeferred().
190042 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
190043 ** If an error occurs during execution of this function, *pRc is set to
190044 ** the appropriate SQLite error code. In this case the returned value is
190064 ** all phrases involved in the NEAR. This is because the snippet(),
190071 ** is matched against a row containing:
190076 ** (as "b" is part of a non-matching NEAR clause).
190137 ** This function is called as the second part of each xNext operation when
190147 ** If *pRc is not SQLITE_OK when this function is called, it immediately
190149 ** operators and deferred tokens the current row is still a match for the
190152 ** 1. *pRc is SQLITE_OK when this function returns, and
190155 ** it is determined that the row does *not* match the query.
190167 ** token. Then, see if this row is really a match, considering deferred
190210 /* Check if the cursor is past the end of the docid range specified
190227 ** If *pRc is other than SQLITE_OK when this function is called, it is
190228 ** a no-op. If an error occurs within this function, *pRc is set to an
190306 ** This is an sqlite3Fts3ExprIterate() callback. If the Fts3Expr.aMI[] array
190324 ** If it is not already allocated and populated, this function allocates and
190325 ** populates the Fts3Expr.aMI[] array for expression pExpr. If pExpr is part
190329 ** SQLITE_OK is returned if the aMI[] array is successfully allocated and
190330 ** populated. Otherwise, if an error occurs, an SQLite error code is returned.
190366 /* Ensure the %_content statement is reset. */
190410 ** This function is used by the matchinfo() module to query a phrase
190419 ** If no error occurs, SQLITE_OK is returned and the values for each column
190436 ** * If the phrase is part of a NEAR expression, then only phrase instances
190472 ** The returned value is either NULL or a pointer to a buffer containing
190478 ** compression and is terminated by either an 0x01 or 0x00 byte. For example,
190480 ** for 'X' is requested, the buffer returned may contain:
190484 ** This function works regardless of whether or not the phrase is deferred,
190499 /* If this phrase is applies specifically to some column other than
190522 ** tree that the node is part of has been marked as EOF, but the node
190523 ** itself is not EOF, then it may point to an earlier entry. */
190537 /* This is the descendent of an OR node. In this case we cannot use
190678 ** a legal notice, here is a blessing:
190708 int isEof; /* True if cursor is at EOF */
190991 ** The only difference between state 1 and state 2 is that if the
190992 ** integer encountered in state 1 is not 0 or 1, then we need to
191014 /* State 3. The integer just read is a column number. */
191081 /* In case this cursor is being reused, close and zero it. */
191132 ** xEof - Return true if the cursor is at EOF, or false otherwise.
191238 ** a legal notice, here is a blessing:
191248 ** syntax is relatively simple, the whole tokenizer/parser system is
191257 ** is defined, then it uses the new syntax. The differences between
191264 ** c) The old syntax supports the "-" token qualifier. This is not
191265 ** supported by the new syntax (it is replaced by the NOT operator).
191273 ** to zero causes the module to use the old syntax. If it is set to
191274 ** non-zero the new syntax is activated. This is so both syntaxes can
191319 ** This variable is used by function getNextNode(). When getNextNode() is
191320 ** called, it sets ParseContext.isNot to true if the 'next node' is a
191322 ** FTS3 query "sqlite -mysql". Otherwise, ParseContext.isNot is set to
191339 ** This function is equivalent to the standard isspace() function.
191342 ** is defined to accept an argument of type int, its behavior when passed
191344 ** is undefined (and sometimes, "undefined" means segfault). This wrapper
191345 ** is defined to accept an argument of type char, and always returns 0 for
191392 ** Function getNextNode(), which is called by fts3ExprParse(), may itself
191393 ** call fts3ExprParse(). So this forward declaration is required.
191401 ** single token and set *ppExpr to point to it. If the end of the buffer is
191402 ** reached before a token is found, set *ppExpr to zero. It is the
191499 ** is included in the buffer. This function attempts to tokenize the entire
191503 ** If successful, SQLITE_OK is returned and *ppExpr set to point at the
191505 ** error) or SQLITE_ERROR (tokenization error) is returned and *ppExpr set
191619 ** The output variable *ppExpr is populated with an allocated Fts3Expr
191620 ** structure, or set to 0 if the end of the input buffer is reached.
191623 ** if a malloc failure occurs, or SQLITE_ERROR if a parse error is encountered.
191624 ** If SQLITE_ERROR is returned, pContext is populated with an error message.
191678 /* If this is a "NEAR" keyword, check for an explicit nearness. */
191686 /* At this point this is probably a keyword. But for that to be true,
191711 /* See if we are dealing with a quoted phrase. If this is the case, then
191713 ** for processing. This is easy to do, as fts3 has no syntax for escaping
191747 ** interface. Before doing so, figure out if there is an explicit
191750 ** TODO: Strangely, it is not possible to associate a column specifier
191775 ** The argument is an Fts3Expr structure for a binary operator (any type
191782 ** is defined), the order of the operators in precedence from highest to
191783 ** lowest is:
191808 ** expression tree being parsed. pPrev is the expression node most recently
191809 ** inserted into the tree. This function adds pNew, which is always a binary
191812 ** of the tree changing, in which case *ppHead is set to the new root node.
191837 ** returns either when the end of the buffer is reached or an unmatched
191838 ** closing bracket - ')' - is encountered.
191840 ** If successful, SQLITE_OK is returned, *ppExpr is set to point to the
191841 ** parsed form of the expression and *pnConsumed is set to the number of
191842 ** bytes read from buffer z. Otherwise, *ppExpr is set to 0 and SQLITE_NOMEM
191843 ** (out of memory error) or SQLITE_ERROR (parse error) is returned.
191892 /* The isRequirePhrase variable is set to true if a phrase or
191893 ** an expression contained in parenthesis is required. If a
191894 ** binary operator (AND, OR, NOT or NEAR) is encounted when
191895 ** isRequirePhrase is set, this is a syntax error.
191992 ** as the only argument is more than nMaxDepth.
192011 ** an equivalent but more balanced form. The tree is modified in place.
192012 ** If successful, SQLITE_OK is returned and (*pp) set to point to the
192015 ** nMaxDepth is the maximum allowable depth of the balanced sub-tree.
192017 ** Otherwise, if an error occurs, an SQLite error code is returned and
192133 ** and pFree list. Everything else is cleaned up by the call to
192184 ** This function is similar to sqlite3Fts3ExprParse(), with the following
192237 ** parsed expression. If successful, *ppExpr is set to point to the head
192238 ** of the parsed expression tree and SQLITE_OK is returned. If an error
192240 ** error) is returned and *ppExpr is set to 0.
192242 ** If parameter n is a negative number, then z is assumed to point to a
192243 ** nul-terminated string and the length is determined using strlen().
192245 ** The first parameter, pTokenizer, is passed the fts3 tokenizer module to
192247 ** array, which is assumed to contain nCol entries, should contain the names
192253 ** column to match against for tokens for which a column name is not explicitly
192286 "FTS expression tree is too large (maximum depth %d)",
192338 ** Everything after this point is just test code.
192347 ** expression passed as the first argument. The buffer is obtained from
192348 ** sqlite3_malloc(). It is the responsibility of the caller to use
192349 ** sqlite3_free() to release the memory. If an OOM condition is encountered,
192350 ** NULL is returned.
192352 ** If the second argument is not NULL, then its contents are prepended to
192399 ** This is the implementation of a scalar SQL function used to test the
192404 ** The first argument, <tokenizer>, is the name of the fts3 tokenizer used
192406 ** is the query expression to parse. Each subsequent argument is the name
192534 ** a legal notice, here is a blessing:
192541 ** This is the implementation of generic hash-tables used in SQLite.
192547 ** The code in this file is only compiled if:
192549 ** * The FTS3 module is being built as an extension
192550 ** (in which case SQLITE_CORE is not defined), or
192552 ** * The FTS3 module is being built into the core of
192553 ** SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
192581 ** "pNew" is a pointer to the hash table that is to be initialized.
192582 ** keyClass is one of the constants
192584 ** determines what kind of key the hash table will use. "copyKey" is
192624 ** Hash and comparison functions when the mode is FTS3_HASH_STRING
192642 ** Hash and comparison functions when the mode is FTS3_HASH_BINARY
192663 ** The name of the function is "ftsHashFunction". The function takes a
192665 ** is a pointer to another function. Specifically, the return value
192666 ** of ftsHashFunction() is a pointer to a function that takes two parameters
192697 struct _fts3ht *pEntry, /* The entry into which pNew is inserted */
192747 ** already been computed and is passed as the 4th parameter.
192829 ** that matches pKey,nKey. Return the data for this element if it is
192830 ** found, or NULL if there is no match.
192839 /* Insert an element into the hash table pH. The key is pKey,nKey
192840 ** and the data is "data".
192843 ** element is created. A copy of the key is made if the copyKey
192844 ** flag is set. NULL is returned.
192847 ** new data replaces the old data and the old data is returned.
192848 ** The key is not copied in this instance. If a malloc fails, then
192849 ** the new data is returned and the hash table is unchanged.
192851 ** If the "data" parameter to this function is NULL, then the
192852 ** element corresponding to "key" is removed from the hash table.
192920 ** a legal notice, here is a blessing:
192932 ** The code in this file is only compiled if:
192934 ** * The FTS3 module is being built as an extension
192935 ** (in which case SQLITE_CORE is not defined), or
192937 ** * The FTS3 module is being built into the core of
192938 ** SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
193000 ** string to be tokenized is zInput[0..nInput-1]. A cursor
193001 ** used to incrementally tokenize this string is returned in
193053 ** the string they point to is a consonant or a vowel, according
193056 ** A consonate is any letter other than 'a', 'e', 'i', 'o', or 'u'.
193057 ** 'Y' is a consonant unless it follows another consonant,
193058 ** in which case it is a vowel.
193061 ** is that 'y' is a consonant unless it is followed by another
193091 ** In prose: A word is an optional consonant followed by zero or
193092 ** vowel-consonant pairs followed by an optional vowel. "m" is the
193096 ** Return true if the m-value for z is 1 or more. In other words,
193097 ** return true if z contains at least one vowel that is followed
193100 ** In this routine z[] is in reverse order. So we are really looking
193110 /* Like mgt0 above except we are looking for a value of m which is
193139 ** Return TRUE if there is a vowel anywhere within z[0..n-1]
193149 ** The text is reversed here. So we are really looking at
193159 ** is not 'w', 'x', or 'y'.
193161 ** The word is reversed here. So we are really checking the
193173 ** If the word ends with zFrom and xCond() is true for the stem
193178 ** is in normal order.
193181 ** match. Not that TRUE is returned even if xCond() fails and
193202 ** This is the fallback stemmer used when the porter stemmer is
193203 ** inappropriate. The input word is copied into the output with
193204 ** US-ASCII case folding. If the input word is too long (more
193206 ** it contains digits) then word is truncated to 20 or 6 bytes
193235 ** zOut is at least big enough to hold nIn bytes. Write the actual
193249 ** in [a-zA-Z] then no stemming is attempted and this routine just
193253 ** Stemming never increases the length of the word. So there is
193261 /* The word is too big or too small for the porter stemmer.
193479 /* z[] is now the stemmed word in reverse order. Flip it back
193491 ** whose value is greater than 0x80 (any UTF character) can be
193511 const char **pzToken, /* OUT: *pzToken is the token text */
193585 ** a legal notice, here is a blessing:
193593 ** This is part of an SQLite module implementing full-text search.
193598 ** The code in this file is only compiled if:
193600 ** * The FTS3 module is being built as an extension
193601 ** (in which case SQLITE_CORE is not defined), or
193603 ** * The FTS3 module is being built into the core of
193604 ** SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
193631 ** where <function-name> is the name passed as the second argument
193634 ** If the <pointer> argument is specified, it must be a blob value
193636 ** to the string <key-name>. If <pointer> is not specified, then
193638 ** an error is returned.
193640 ** Whether or not the <pointer> argument is specified, the value returned
193641 ** is a blob containing the pointer stored as the hash data corresponding
193642 ** to string <key-name> (after the hash-table is updated, if applicable).
193823 ** where <function-name> is the name passed as the second argument
193827 ** The return value is a string that may be interpreted as a Tcl
193829 ** added to the returned list. The first is the token position, the
193830 ** second is the token text (folded, stemmed, etc.) and the third is the
193987 ** This function is used for testing only, it is not included in the
193988 ** build unless SQLITE_TEST is defined.
193990 ** The purpose of this is to test that the fts3_tokenizer() function
193993 ** in the README.tokenizer file as an example, so it is important to
193997 ** function with no arguments. An assert() will fail if a problem is
194044 ** of the key when a value is inserted. i.e. by a call similar to:
194049 ** fts3TokenizerFunc() in this file for details) and, if ENABLE_TABLE is
194054 ** The third argument to this function, zName, is used as the name
194108 ** a legal notice, here is a blessing:
194120 ** The code in this file is only compiled if:
194122 ** * The FTS3 module is being built as an extension
194123 ** (in which case SQLITE_CORE is not defined), or
194125 ** * The FTS3 module is being built into the core of
194126 ** SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
194212 ** string to be tokenized is pInput[0..nBytes-1]. A cursor
194213 ** used to incrementally tokenize this string is returned in
194262 const char **ppToken, /* OUT: *ppToken is the token text */
194345 ** a legal notice, here is a blessing:
194354 ** An fts3tokenize virtual table is created as follows:
194437 ** The second argument, argv[], is an array of pointers to nul-terminated
194442 ** If successful, output parameter *pazDequote is set to point at the
194443 ** array of dequoted strings and SQLITE_OK is returned. The caller is
194445 ** in this case. Or, if an error occurs, an SQLite error code is returned.
194446 ** The final value of *pazDequote is undefined in this case.
194708 ** xEof - Return true if the cursor is at EOF, or false otherwise.
194807 ** a legal notice, here is a blessing:
194815 ** This file is part of the SQLite FTS3 extension module. Specifically,
194835 ** of it. i.e. if a full-text index node is 900 bytes in size, then a buffer
194836 ** of 920 bytes is allocated for it.
194839 ** it is always safe to read up to two varints from it without risking an
194840 ** overread, even if the node data is corrupted.
194851 ** Incremental loading is used for b-tree nodes FTS3_NODE_CHUNK_THRESHOLD
194853 ** The code is written so that the hard lower-limit for each of these values
194854 ** is 1. Clearly such small values would be inefficient, but can be useful
194857 ** If this module is built with SQLITE_TEST defined, these constants may
194880 ** If FTS_LOG_MERGES is defined, call sqlite3_log() to report each automatic
194881 ** and incremental merge operation that takes place. This is used for
194899 ** An instance of the following data structure is used to build doclists
194919 PendingList *pList; /* Doclist is assembled here */
194923 ** An instance of this structure is used to iterate through the terms on
194979 ** An instance of this structure is used to create a segment b-tree in the
195002 ** Type SegmentNode is used by the following three functions to create
195011 ** When a b+tree is written to the database (either as a result of a merge
195014 ** the tree is assembled in memory and written out only once all leaves have
195015 ** been populated and stored. This is Ok, as the b+-tree fanout is usually
195079 ** This function is used to obtain an SQLite prepared statement handle
195081 ** *pp is set to the requested statement handle and SQLITE_OK returned.
195082 ** Otherwise, an SQLite error code is returned and *pp is set to 0.
195084 ** If argument apVal is not NULL, then it must point to an array with
195133 /* This statement is used to determine which level to read the input from
195172 ** Return a single row if the segment with end_block=? is appendable. Or
195291 ** is executed.
195293 ** Returns SQLITE_OK if the statement is successfully executed, or an
195316 ** shared-cache table-lock on the %_segdir table. This is required before
195317 ** writing data to the fts3 table. If this lock is not acquired first, then
195322 ** It is best to avoid this because if FTS3 returns any error when
195324 ** And this is not what users expect when they get SQLITE_LOCKED_SHAREDCACHE.
195346 ** Within each language id, a separate index is maintained to store the
195353 ** in the %_segdir table on disk. This function is used to convert three
195357 ** Specifically, each language-id/index combination is allocated 1024
195359 ** for language-id 0 is allocate values 0-1023. The first prefix index
195360 ** (if any) for language-id 0 is allocated values 1024-2047. And so on.
195388 ** There is only ever one instance of this SQL statement compiled for
195435 ** Append a single varint to a PendingList buffer. SQLITE_OK is returned
195483 ** is returned if the structure is sqlite3_realloced as part of adding
195486 ** If an OOM error occurs, *pRc is set to SQLITE_NOMEM before returning.
195487 ** Zero is always returned in this case. Otherwise, if no OOM error occurs,
195488 ** it is set to SQLITE_OK.
195585 ** pending-terms hash-table. The docid used is that currently stored in
195586 ** p->iPrevDocid, and the column is specified by argument iCol.
195588 ** If successful, SQLITE_OK is returned. Otherwise, an SQLite error code.
195594 int iCol, /* Column into which text is being inserted */
195647 /* Add the term to each of the prefix indexes that it is not too
195670 int bDelete, /* True if this op is a delete */
195715 ** This function is called by the xUpdate() method as part of an INSERT
195719 ** Argument apVal is the same as the similarly named argument passed to
195720 ** fts3InsertData(). Parameter iDocid is the docid of the new row.
195744 ** This function is called by the xUpdate() method for an INSERT operation.
195745 ** The apVal parameter is passed a copy of the apVal argument passed by
195778 ** table. The SQL for this statement is:
195782 ** The statement features N '?' variables, where N is the number of user
195794 /* There is a quirk here. The users INSERT statement may have specified
195796 ** Which is a problem, since "rowid" and "docid" are aliases for the
195801 ** In FTS3, this is an error. It is an error to specify non-NULL values
195838 ** is if bContent is false. */
195862 ** The first element in the apVal[] array is assumed to contain the docid
195916 ** with 0, so the allocated index is one greater than the value returned
195923 ** allocated index is 0.
195925 ** If successful, *piIdx is set to the allocated index slot and SQLITE_OK
195926 ** returned. Otherwise, an SQLite error code is returned.
195955 /* If iNext is FTS3_MERGE_COUNT, indicating that level iLevel is already
195958 ** if iNext is less than FTS3_MERGE_COUNT, allocate index iNext.
195973 ** The %_segments table is declared as follows:
195978 ** specific row is identified by the iBlockid parameter. If paBlob is not
195979 ** NULL, then a buffer is allocated using sqlite3_malloc() and populated
195981 ** identified table row is. Whether or not paBlob is NULL, *pnBlob is set
195985 ** an SQLite error code is returned. Otherwise, SQLITE_OK is returned. If
195986 ** paBlob is non-NULL, then it is the responsibility of the caller to
195990 ** Fts3Table.pSegments variable. This handle is reused by subsequent calls
195992 ** sqlite3Fts3SegmentsClose() function. Reusing a blob handle is a handy
195994 ** before control is returned to the user (to prevent a lock being held
196052 ** Close the blob handle at p->pSegments, if it is open. See comments above
196111 ** segment. If successful, SQLITE_OK is returned. If there is no next term,
196165 /* If iCurrentBlock>=iLeafEndBlock, this is an EOF condition. All leaf
196192 /* Because of the FTS3_NODE_PADDING bytes of padding, the following is
196193 ** safe (no risk of overread) even if the node data is corrupted. */
196227 ** b-tree node. And that the final byte of the doclist is 0x00. If either
196228 ** of these statements is untrue, then the data structure is corrupt.
196270 ** *ppOffsetList is set to point to the first column-offset list
196272 ** *pnOffsetList is set to the length of the set of column-offset
196313 /* The following line of code (and the "p++" below the while() loop) is
196314 ** normally all that is required to move pointer p to the desired
196315 ** position. The exception is if this node is being loaded from disk
196451 /* The entire segment is stored in the root node. */
196465 ** This is a comparison function used as a qsort() callback when sorting
196487 ** This function is used to allocate an Fts3SegReader that iterates through
196490 ** If the isPrefixIter parameter is zero, then the returned SegReader iterates
196491 ** through each term in the pending-terms table. Or, if isPrefixIter is
196501 ** Whereas if isPrefixIter is zero, the terms visited are:
196548 ** callback as is used when flushing terms to disk.
196555 /* The query is a simple term lookup that matches at most one term in
196556 ** the index. All that is required is a straight hash-lookup.
196559 ** below, the "Fts3HashElem *pE" must be declared so that it is valid
196592 ** Comparison is as follows:
196594 ** 1) EOF is greater than not EOF.
196597 ** term is a prefix of another, the longer term is considered the
196600 ** 3) By segment age. An older segment is considered larger.
196626 ** version, it is assumed that each SegReader points to an entry in
196627 ** a doclist for identical terms. Comparison is made as follows:
196629 ** 1) EOF (end of doclist in this case) is greater than not EOF.
196633 ** 3) By segment age. An older segment is considered larger.
196664 ** If the pSeg iterator is already at EOF, return 0. Otherwise, return
196665 ** -ve if the pSeg term is less than zTerm/nTerm, 0 if the two terms are
196666 ** equal, or +ve if the pSeg term is greater than zTerm/nTerm.
196688 ** Argument apSegment is an array of nSegment elements. It is known that
196716 /* Check that the list really is sorted now. */
196822 ** Add term zTerm to the SegmentNode. It is guaranteed that zTerm is larger
196828 int isCopyTerm, /* True if zTerm/nTerm is transient */
196837 ** this is possible.
196848 /* If nSuffix is zero or less, then zTerm/nTerm must be a prefix of
196857 /* An unusual case: this is the first term to be added to the node
196858 ** and the static node buffer (p->nNodeSize bytes) is not large
196862 ** this is not expected to be a serious problem.
196872 /* There is no prefix-length field for first term in a node */
196903 ** If this is the first node in the tree, the term is added to it.
196905 ** Otherwise, the term is not added to the new node, it is left empty for
196906 ** now. Instead, the term is inserted into the parent of pTree. If pTree
196907 ** has no parent, one is created here.
196959 ** Except, if pTree is a root node, do not write it to the database. Instead,
196962 ** If successful, SQLITE_OK is returned and output variable *piLast is
196964 ** blocks were written to the db). Otherwise, an SQLite error code is
197034 ** If successful, SQLITE_OK is returned. Otherwise, an SQLite error code.
197081 /* If nSuffix is zero or less, then zTerm/nTerm must be a prefix of
197096 /* The current leaf node is full. Write it out to the database. */
197133 /* If the buffer currently allocated is too small for this entry, realloc
197156 ** If the isCopyTerm parameter is true, then the buffer pointed to by
197157 ** zTerm is transient, so take a copy of the term data. Otherwise, just
197184 ** to the segment using fts3SegWriterAdd(). If successful, SQLITE_OK is
197233 ** The first value in the apVal[] array is assumed to contain an integer.
197238 ** If successful, *pisEmpty is set to true if the table is empty except for
197239 ** document pRowid, or false otherwise, and SQLITE_OK is returned. If an
197240 ** error occurs, an SQLite error code is returned.
197246 /* If using the content=xxx option, assume the table is never empty */
197283 ** (1024 is actually the value of macro FTS3_SEGDIR_PREFIXLEVEL_STR).
197298 ** iAbsLevel is an absolute level that may be assumed to exist within
197299 ** the database. This function checks if it is the largest level number
197300 ** within its index. Assuming no error occurs, *pbMax is set to 1 if
197301 ** iAbsLevel is indeed the largest level, or 0 otherwise, and SQLITE_OK
197302 ** is returned. If an error occurs, an error code is returned and the
197303 ** final value of *pbMax is undefined.
197311 ** (1024 is actually the value of macro FTS3_SEGDIR_PREFIXLEVEL_STR).
197352 ** This function is used after merging multiple segments into a single large
197363 ** SQLITE_OK is returned if successful, otherwise an SQLite error code.
197411 ** When this function is called, buffer *ppList (size *pnList bytes) contains
197417 ** *pnList is set to zero before returning.
197419 ** If parameter bZero is non-zero, then any part of the input list following
197420 ** the end of the output list is zeroed before returning.
197464 ** If successful, return SQLITE_OK. Otherwise, if an OOM error is encountered
197640 ** This function is called on a MultiSegReader that has been started using
197648 ** then the entire doclist for the term is available in
197732 /* If this is a prefix-search, and if the term that apSegment[0] points
197736 ** Similarly, if this is a search for an exact match, and the first term
197737 ** of segment apSegment[0] is not a match, exit early.
197777 ** of Fts3SegReader objects is the same. The doclists must be merged
197937 ** segments in this index on levels greater than iAbsLevel. If there is
197938 ** at least one such segment, and it is possible to determine that all
197949 ** old version of FTS. In this case it is not possible to determine
197974 ** levels equal to or greater than iAbsLevel. As each entry is visited,
197975 ** updated it to set (level = -1) and (idx = N), where N is 0 for the
197980 ** order. The contents of level -1 (which is never used, except
198018 ** If this function is called with iLevel<0, but there is only one
198019 ** segment in the database, SQLITE_DONE is returned immediately.
198020 ** Otherwise, if successful, SQLITE_OK is returned. If an error occurs,
198021 ** an SQLite error code is returned.
198054 /* This call is to merge all segments in the database to a single
198055 ** segment. The level of the new segment is equal to the numerically
198057 ** index. The idx of the new segment is always 0. */
198066 /* This call is to merge all segments at level iLevel. find the next
198231 ** where N is the number of user defined columns in the fts3 table plus
198232 ** two. If nCol is the number of user defined columns, then values of the
198317 ** Merge the entire database so that there is one segment for each
198354 ** This function is called when the user executes the following statement:
198358 ** The entire FTS index is discarded and rebuilt. If the table is one
198359 ** created using the content=xxx option, then the new index is based on
198360 ** the current contents of the xxx table. Otherwise, it is rebuilt based
198493 ** An instance of the following structure is used as a dynamic buffer
198496 ** The function blobGrowBuffer() is used to extend the allocation.
198505 ** This structure is used to build up buffers containing segment b-tree
198531 ** An object of the following type is used to read data from a single
198551 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
198552 ** Otherwise, if the allocation at pBlob->a is not already at least nMin
198576 ** Return an error code if an error occurs (SQLITE_NOMEM is possible).
198577 ** Otherwise return SQLITE_OK. If there is no next entry on the node
198578 ** (e.g. because the current entry is the last) set NodeReader->aNode to
198632 ** If successful, SQLITE_OK is returned and the NodeReader object set to
198634 ** error code is returned.
198641 /* Figure out if this is a leaf or an internal node. */
198653 ** This function is called while writing an FTS segment each time a leaf o
198654 ** node is finished and written to disk. The key (zTerm/nTerm) is guaranteed
198660 ** (pWriter->aNodeWriter[0].iBlock) when this function is called.
198680 /* Figure out how much space the key will consume if it is written to
198682 ** the space required changes depending on which node the key is to
198745 ** header must be written before this function is called.
198747 ** A node header is a single 0x00 byte for a leaf node, or a height varint
198750 ** The term to be appended is passed via arguments zTerm/nTerm. For a
198751 ** leaf node, the doclist is passed as aDoclist/nDoclist. For an internal
198754 ** If the size of the value in blob pPrev is zero, then this is the first
198756 ** previous term. Before this function returns, it is updated to contain a
198759 ** It is assumed that the buffer associated with pNode is already large
198761 ** is extended by this function if requrired.
198763 ** If an error (i.e. OOM condition) occurs, an SQLite error code is
198775 int bFirst = (pPrev->n==0); /* True if this is the first term written */
198843 /* If the current block is not empty, and if adding this term/doclist
198845 ** and if there is still room for another leaf page, write this block out to
198897 ** This function is called to release all dynamic resources held by the
198901 ** If *pRc is not SQLITE_OK when this function is called, then no attempt
198902 ** is made to write any data to disk. Instead, this function serves only
198905 ** Otherwise, if *pRc is initially SQLITE_OK and an error occurs while
198906 ** flushing buffers to disk, *pRc is set to an SQLite error code before
198921 ** will be set to 0. If the root node is the parent of the leaves, iRoot
198932 /* Empty output segment. This is a no-op. */
198937 ** table. However, this is not permitted in this case. The problem is that
198948 ** table until we are sure it is needed.
198993 ** zRhs (size in bytes nRhs) using memcmp. If one term is a prefix of
198994 ** the other, it is considered to be smaller than the other.
198996 ** Return -ve if zLhs is smaller than zRhs, 0 if it is equal, or +ve
198997 ** if it is greater.
199018 ** Query to see if the entry in the %_segments table with blockid iEnd is
199019 ** NULL. If no error occurs and the entry is NULL, set *pbRes 1 before
199023 ** error code. The final value of *pbRes is undefined in this case.
199025 ** This is used to test if a segment is an "appendable" segment. If it
199026 ** is, then a NULL entry has been inserted into the %_segments table
199046 ** This function is called when initializing an incremental-merge operation.
199049 ** merge-writer object *pWriter is initialized to write to it.
199056 ** * The first key read from the input (arguments zKey and nKey) is
199079 int bAppendable = 0; /* Set to true if segment is appendable */
199105 /* Check that zKey/nKey is larger than the largest key the candidate */
199128 /* It is possible to append to this segment. Set up the IncrmergeWriter
199210 ** *piIdx is undefined in this case.
199235 ** In the %_segdir table, a segment is defined by the values in three
199242 ** When an appendable segment is allocated, it is estimated that the
199243 ** maximum number of leaf blocks that may be required is the sum of the
199245 ** of input segments, multiplied by two. This value is stored in stack
199249 ** is created ((1 + end_block - start_block)==16*nLeafEst). The contiguous
199254 ** In the actual code below, the value "16" is replaced with the
199295 ** to steal the space just allocated. This is also used to identify
199476 ** SQLITE_OK is returned if the segment is updated successfully. Or an
199556 ** This function is called after an incrmental-merge operation has run to
199560 ** Each input segment is either removed from the db completely (if all of
199579 /* Find the Fts3SegReader object with Fts3SegReader.iIdx==i. It is hiding
199588 /* Seg-reader is at EOF. Remove the entire input segment. */
199596 ** segment to the upper level. The segment is modified in place
199634 ** exists, is stored in the rowid==1 row of the %_stat table.
199668 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
199754 ** If one is found, set iAbsLevel to the absolute level number and
199769 /* If the hint read from the %_stat table is not empty, check if the
199781 /* Based on the scan in the block above, it is known that there
199783 ** iAbsLevel with more than nSeg segments, or if nSeg is -1,
199786 ** merge-hint is corrupt*/
199793 ** is removed from the hint blob. */
199798 /* If nSeg is less that zero, then there is no level with at least
199810 ** indexes of absolute level iAbsLevel. If this cursor is opened using
199811 ** the 'hint' parameters, it is possible that there are less than nSeg
199812 ** segments available in level iAbsLevel. In this case, no work is
199932 /* If the first integer value is followed by a ',', read the second
199960 ** where X is an integer. X==0 means to turn automerge off. X!=0 means
199961 ** turn it on. The setting is persistent.
200014 ** language id iLangid. The checksum is calculated by XORing the checksums
200017 ** If successful, the checksum value is returned and *pRc set to SQLITE_OK.
200018 ** Otherwise, if an error occurs, *pRc is set to an SQLite error code. The
200019 ** return value is undefined in this case.
200097 ** code. The final value of *pbOk is undefined in this case.
200190 ** prefix in the document set, a 64-bit checksum is calculated (by code
200209 ** If the two checksums are identical, the integrity-check is deemed to have
200228 ** meaningful value to insert is the text 'optimize'.
200306 ** A deferred-doclist is like any other doclist with position information
200418 ** present in the FTS3 table. If it is, delete it and adjust the contents
200424 int *pnChng, /* IN/OUT: Decrement if row is deleted */
200428 int bFound = 0; /* True if *pRowid really is in the table */
200436 /* Deleting this row means the whole table is empty. In this case
200522 /* If this is an INSERT operation, or an UPDATE that modifies the rowid
200525 ** If the on-conflict mode is REPLACE, this means that the existing row
200527 ** if the on-conflict mode is other than REPLACE, then this method must
200542 /* The new rowid is not NULL (in this case the rowid will be
200543 ** automatically assigned and there is no chance of a conflict), and
200544 ** the statement is either an INSERT or an UPDATE that modifies the
200545 ** rowid column. So if the conflict mode is REPLACE, then delete any
200548 ** Or, if the conflict mode is not REPLACE, insert the new record into
200555 ** function) will return SQLITE_MISMATCH. If fts3DeleteByRowid is
200557 ** docid=$pNewRowid if $pNewRowid is not an integer value).
200571 /* If this is a DELETE or UPDATE operation, remove the old record. */
200577 /* If this is an INSERT or UPDATE operation, insert the new record. */
200639 ** a legal notice, here is a blessing:
200697 Fts3Cursor *pCsr; /* Cursor snippet is being generated from */
200715 int iCol; /* Column snippet is extracted from */
200722 ** This type is used as an sqlite3Fts3ExprIterate() context object while
200736 ** An instance of this structure is used to manage a pair of buffers, each
200743 int bGlobal; /* Set if global data is loaded */
200751 ** of the following structure is used to accumulate those values while the
200855 ** This function is used to help iterate through a position-list. A position
200856 ** list is a list of unique integers, sorted from smallest to largest. Each
200857 ** element of the list is represented by an FTS3 varint that takes the value
200869 ** When this function is called, *pp points to the start of an element of
200872 ** list and *pp is advanced to the following varint.
200907 ** are part of a sub-tree that is the right-hand-side of a NOT operator.
200908 ** For each phrase node found, the supplied callback function is invoked.
200911 ** the iteration is abandoned and the error code returned immediately.
200912 ** Otherwise, SQLITE_OK is returned after a callback has been made for
200925 ** This is an sqlite3Fts3ExprIterate() callback used while loading the
200946 ** If pnPhrase is not NULL, then *pnPhrase is set to the number of matchable
200949 ** pnToken is not NULL, then it is set to the number of tokens in all
201015 ** is greater than or equal to (iNext+nSnippet).
201101 ** This function is an sqlite3Fts3ExprIterate() callback used by
201138 ** is the snippet with the highest score, where scores are calculated
201144 ** the snippet for which the corresponding mCovered bit is not set.
201147 ** returning. The score of the selected snippet is stored in *piScore
201176 /* Now that it is known how many phrases there are, allocate and zero
201234 ** If nAppend is negative, then the length of the string zAppend is
201246 /* If there is insufficient space allocated at StrBuffer.z, use realloc()
201247 ** to grow the buffer until so that it is big enough to accomadate the
201271 ** query term. That is, the final term of the snippet is always a term
201272 ** that requires highlighting. For example, if 'X' is a highlighted term
201273 ** and '.' is a non-highlighted term, BestSnippet() may select:
201284 ** This is done as part of extracting the snippet text, not when selecting
201285 ** the snippet. Snippet selection is done based on doclists only, so there
201286 ** is no way for fts3BestSnippet() to know whether or not the document
201314 ** right. Otherwise, the snippet is shifted by the number of tokens
201371 int isShiftDone = 0; /* True after snippet is shifted */
201401 /* Variable DUMMY1 is initialized to a negative value above. Elsewhere
201403 ** is initialized to zero before the first (*but not necessarily
201404 ** subsequent*) call to xNext(). This is done for a particular application
201405 ** that needs to know whether or not the tokenizer is being used for
201408 ** Extreme care is required when writing code to depend on this
201409 ** initialization. It is not a documented part of the tokenizer interface.
201410 ** If a tokenizer is used directly by any code outside of FTS, this
201415 /* Special case - the last token of the snippet is also the last token
201433 ** required. They are required if (a) this is not the first fragment,
201470 ** This function is used to count the entries in a column-list (a
201472 ** row). When this function is called, *ppCollist should point to the
201475 ** Before returning, *ppCollist is set to point to the first byte after
201480 ** The number of elements in the column-list is returned.
201487 /* A column-list is terminated by either a 0x01 or 0x00. */
201564 ** Argument pCtx is actually a pointer to a struct of type MatchInfo. This
201572 ** where X is the number of matches for phrase iPhrase is column iCol of all
201573 ** rows of the table. Y is the number of rows for which column iCol contains
201577 ** Y values are set to nDoc, where nDoc is the number of documents in the
201578 ** file system. This is done because the full-text index doclist is required
201579 ** to calculate these values properly, and the full-text index doclist is
201714 ** An instance of the following structure is used to store state while
201728 ** If LcsIterator.iCol is set to the following value, the iterator has
201745 ** 1 if the iterator is at EOF or if it now points to the start of the
201770 ** If the call is successful, the longest-common-substring lengths for each
201772 ** array before returning. SQLITE_OK is returned in this case.
201774 ** Otherwise, if an error occurs, an SQLite error code is returned and the
201775 ** data written to the first nCol elements of pInfo->aMatchinfo[] is
201824 /* This iterator is already at EOF for this column. */
201855 ** is guaranteed to be large enough for the output.
201857 ** If bGlobal is true, then populate all fields of the matchinfo() output.
201858 ** If it is false, then assume that those fields that do not change between
201863 ** occurs. If a value other than SQLITE_OK is returned, the state the
201864 ** pInfo->aMatchinfo[] buffer is left in is undefined.
201986 ** 'matchinfo' data is an array of 32-bit unsigned integers (C type u32).
202005 /* If there is cached matchinfo() data, but the format string for the
202013 /* If Fts3Cursor.pMIBuffer is NULL, then this is the first time the
202129 ** columns of the FTS3 table. Otherwise, only column iCol is considered.
202194 ** This function is an sqlite3Fts3ExprIterate() callback used by sqlite3Fts3Offsets().
202281 /* Retreive the text stored in column iCol. If an SQL NULL is stored
202397 ** a legal notice, here is a blessing:
202422 ** from the sqlite3 source file utf.c. If this file is compiled as part
202513 ** If so, no action is taken. Otherwise, the codepoint is added to the
202515 ** the return value of sqlite3FtsUnicodeIsalnum() is inverted for all
202519 ** identifies as a diacritic) occurs in the zIn/nIn string it is ignored.
202520 ** It is not possible to change the behavior of the tokenizer with respect
202599 ** Return true if, for the purposes of tokenization, codepoint iCode is
202659 ** string to be tokenized is pInput[0..nBytes-1]. A cursor
202660 ** used to incrementally tokenize this string is returned in
202754 /* If the cursor is not at EOF, read the next character */
202797 ** a legal notice, here is a blessing:
202820 ** is less than zero.
202831 ** C. It is not possible to represent a range larger than 1023 codepoints
202947 ** If the argument is a codepoint corresponding to a lowercase letter
203019 ** is a diacritical modifier character.
203033 ** is an upper case character that has a lower case equivalent,
203038 ** is less than zero.
203045 ** If the least significant bit in flags is clear, then the rule applies
203047 ** need to be folded). Or, if it is set, then the rule only applies to
203052 ** case equivalent is ((C + aiOff[flags>>1]) & 0xFFFF).
203183 ** a legal notice, here is a blessing:
203199 ** with JSON-5 extensions is accepted as input.
203204 ** format SQLite JSONB is completely different and incompatible with
203207 ** Decoding and interpreting JSONB is still O(N) where N is the size of
203209 ** for JSONB is much smaller due to faster parsing. The size of each
203210 ** element in JSONB is encoded in its header, so there is no need to search
203212 ** 3x faster than text JSON as a result. JSONB is also tends to be slightly
203215 ** a JSONB blob is the same size as the equivalent RFC-8259 text.
203220 ** Every JSON element is encoded in JSONB as a header and a payload.
203221 ** The header is between 1 and 9 bytes in size. The payload is zero
203245 ** and sometimes also the size of the payload. If X is the first byte
203246 ** of the element and if X>>4 is between 0 and 11, then the payload
203247 ** will be that many bytes in size and the header is exactly one byte
203249 ** is more than one byte in size and that the payload size is determined
203261 ** if the payload size is 10, the size can be expressed in any of 5 different
203266 ** sometimes when generating JSONB, the payload size is not known in advance
203267 ** and it is convenient to reserve sufficient header space to cover the
203271 ** The value (X>>4)==15 is not actually used in the current implementation
203272 ** (as SQLite is currently unable handle BLOBs larger than about 2GB)
203273 ** but is included in the design to allow for future enhancements.
203277 ** FLOAT, FLOAT5, TEXT, TEXTJ, TEXT5, and TEXTROW is text. Note that the
203279 ** The payload for ARRAY and OBJECT is a list of additional elements that
203281 ** must be an even number of elements. The first element of each pair is
203286 ** elements as its content. But the overall blob is just a single element.
203289 ** code is between 0 and 12 and that the total size of the element
203290 ** (header plus payload) is the same as the size of the BLOB. If those
203291 ** checks are true, the BLOB is assumed to be JSONB and processing continues.
203292 ** Errors are only raised if some other miscoding is discovered during
203327 ** Growing our own isspace() routine this way is twice as fast as
203360 ** '"' and '\\' and '\''. Actually, '\'' is not special to
203361 ** canonical JSON, but it is special in JSON-5, so we include
203403 ** Each cache entry is a JsonParse object with the following restrictions:
203421 ** under construction. Really, this is a generic string accumulator
203422 ** that can be and is used to create strings other than JSON.
203424 ** If the generated string is longer than will fit into the zSpace[] buffer,
203433 u8 bStatic; /* True if zBuf is static space */
203452 #define JSON_JSON 0x01 /* Result is always JSON */
203453 #define JSON_SQL 0x02 /* Result is always SQL */
203461 ** 1. JSON comes in and is parsed into a JSONB value in aBlob. The
203462 ** original text is stored in zJson. This step is skipped if the
203463 ** input is JSONB instead of text JSON.
203465 ** 2. The aBlob[] array is searched using the JSON path notation, if needed.
203470 ** 4. New JSON text is generated from the aBlob[] for output. This step
203471 ** is skipped if the function is one of the jsonb_* functions that
203477 u32 nBlobAlloc; /* Bytes allocated to aBlob[]. 0 if aBlob is external */
203486 u8 bJsonIsRCStr; /* True if zJson is an RCStr */
203506 ** This limit is needed to avoid a stack overflow in the recursive
203507 ** descent parser. A depth of 1000 is far deeper than any sane JSON
203520 #define JSON_KEEPERROR 0x02 /* Return non-NULL even if there is an error */
203553 ** Insert a new entry into the cache. If the cache is full, expel
203596 ** When a match if found, the matching entry is moved to become the
203780 /* Make sure there is a zero terminator on p->zBuf[]
203792 ** character is not '[' or '{'.
203807 ** This routine is a high-runner. There is a measurable performance
203819 /* The following while() is the 4-way unwound equivalent of
203948 /* Make the text in p (which is probably a generated JSON text string)
203951 ** The JsonString is reset.
203953 ** If pParse and ctx are both non-NULL, then the SQL string in p is
203955 ** pParse is added to the cache.
204043 ** This routine only gives a correct answer if h really is a valid hexadecimal
204045 ** assert() if the digit is not hex.
204271 ** If pParse->aBlob is not previously editable (because it is taken
204336 ** If aPayload is not NULL, then it is a pointer to the payload which
204337 ** is also appended. If aPayload is NULL, the pParse->aBlob[] array
204338 ** is resized (if necessary) so that it is big enough to hold the
204339 ** payload, but the payload is not appended and pParse->nBlob is left
204448 ** If z[0] is 'u' and is followed by exactly 4 hexadecimal character,
204465 ** Return 0 if everything is correct. Return the 1-based byte offset of the
204466 ** error if a problem is detected. (In other words, if the error is at offset
204663 ** pParse->aBlob[] is increased as necessary.
204671 ** -3 ']' seen \___ For these returns, pParse->iErr is set to
204734 /* strspn() is not helpful here */
205178 ** The input string pStr is a well-formed JSON text string. Convert
205200 /* The byte at index i is a node type-code. This routine
205268 ** of the first byte past the end of the element that is translated.
205270 ** If an error is detected in the BLOB input, the pOut->eErr flag
205275 ** The pOut->eErr JSTRING_OOM flag is set on a OOM.
205417 /* '\' followed by either U+2028 or U+2029 is ignored as
205418 ** whitespace. Not that in UTF8, U+2028 is 0xe2 0x80 0x29.
205419 ** U+2029 is the same except for the last byte */
205486 ** input BLOB to ensure that it is well-formed. Hence, false positives are
205546 ** nDel may be zero, in which case no bytes are removed. But iDel is
205549 ** aIns may be zero, in which case space is created to hold nIns bytes
205550 ** beginning at iDel, but that space is uninitialized.
205555 JsonParse *pParse, /* The JSONB to be modified is in pParse->aBlob */
205578 ** An escaped newline is a one of the following byte sequences:
205620 ** If there is a syntax error of some kind (for example too few characters
205621 ** after the '\\' to complete the encoding) then *piOut is set to
205709 int rawRight /* True if zRight is escape-free */
205765 int rawRight /* True if zRight is escape-free */
205769 ** memcmp() is sufficient. */
205791 ** binary data that is to be inserted into pParse.
205803 ** is: {"a":{"b":{"c"::123}}}. This routine populates pIns with
205806 ** The caller is responsible for resetting pIns when it has finished
205810 JsonParse *pParse, /* The original JSONB that is being edited */
205819 /* No substructure. Just insert what is given in pParse. */
205840 ** If the value found by this routine is the value half of label/value pair
205846 ** This routine will also modify the blob. If pParse->eEdit is one of
205848 ** made to the selected value. If an edit is performed, then the return
205850 ** is performed, the return value is only useful for detecting error
205857 u32 iLabel /* Label if iRoot is a value of in an object */
205874 /* Already exists, so json_insert() is a no-op */
205908 j = iRoot + n; /* j is the index of a label */
205917 k = j+n; /* k is the index of the label text */
205922 u32 v = k+sz; /* v is the index of the value */
206062 ** If the value is a primitive, return it as an SQL value.
206063 ** If the value is an array or object, return it as either
206219 ** pArg is a function argument that might be an SQL value or a JSON
206220 ** value. Figure out what it is and encode it as a JSONB blob.
206223 ** pParse is uninitialized upon entry. This routine will handle the
206226 ** allocated (if pParse->nBlobAlloc is greater than zero) in which case
206227 ** the caller is responsible for freeing the space allocated to pParse->aBlob
206231 ** If the argument is a BLOB that is clearly not a JSONB, then this
206315 ** If ctx is not NULL then push the error message into ctx and return NULL.
206316 ** If ctx is NULL, then return the text of the error message.
206333 /* argv[0] is a BLOB that seems likely to be a JSONB. Subsequent
206338 ** The specific operation is determined by eEdit, which can be one
206403 ** If pArg is a blob that seems like a JSONB blob, then initialize
206407 ** This routine is only called if it is already known that pArg is a
206408 ** blob. The only open question is whether or not the blob appears
206439 ** Ownership of the new JsonParse object is passed to the caller. The
206443 ** If any errors are detected, an appropriate error messages is set
206446 ** is an SQL NULL value, but no error message is set in that case. This
206447 ** is so that SQL functions that are given NULL arguments will return
206496 /* If the blob is not valid JSONB, fall through into trying to cast
206497 ** the blob into text which is then interpreted as JSON. (tag-20240123-a)
206563 ** or make it JSON text, depending on whether the JSON_BLOB flag is
206715 ** Parse JSON using jsonParseFuncArg(). Return text that is a
206767 ** is a BLOB, throw an error.
206793 ** Return 0 if the input is not a well-formed JSON array.
206835 /* True if the string is all digits */
206842 /* True if the string is all alphanumerics and underscores */
206855 ** is not found.
206857 ** If JSON_JSON is set or if more that one PATH argument is supplied then
206858 ** always return a JSON representation of the result. If JSON_SQL is set,
206860 ** is present and argc==2, then return JSON for objects and arrays and SQL
206863 ** When multiple PATH arguments are supplied, the result is a JSON array
206898 ** is mostly for compatibility with PostgreSQL, but also for
206987 ** pTarget is the target. pPatch is the patch. The target is updated
206988 ** in place. The patch is read-only.
206990 ** The original RFC-7396 algorithm is this:
206993 ** if Patch is an Object:
206994 ** if Target is not an Object:
206997 ** if Value is null:
207006 ** Here is an equivalent algorithm restructured to show the actual
207010 ** 02 if Patch is not an Object:
207012 ** 04 else: // if Patch is an Object
207013 ** 05 if Target is not an Object:
207017 ** 09 if Value is null:
207021 ** 13 else if Value is not NULL:
207022 ** 14 if Value is not an Object:
207135 /* Patch value is NULL. Algorithm line 09 */
207148 /* No match and patch value is not NULL */
207177 ** object that is the result of running the RFC 7396 MergePatch() algorithm
207212 ** is not a string or if any value is a BLOB, throw an error.
207311 ** this routine is a no-op. If JSON or PATH is malformed, throw an error.
207332 ** If JSON or PATH is malformed, throw an error.
207337 ** routine is a no-op. If JSON or PATH is malformed, throw an error.
207404 ** Check the JSON argument to see if it is well-formed. The FLAGS argument
207405 ** encodes the various constraints on what is meant by "well-formed":
207412 ** If the FLAGS argument is omitted, it defaults to 1. Useful values for
207425 ** JSON text is also well-formed JSON-5 text, so FLAG values 2 and 3
207431 ** JSONB validation. Superficial JSONB validation is constant time,
207432 ** assuming the BLOB is already in memory. The performance advantage
207433 ** of superficial JSONB validation is why that option is provided.
207440 ** in FLAGS is set other than the lower four bits.
207444 ** function only accepted one argument. That is why the default value
207445 ** for the FLAGS argument is 1, since FLAGS=1 causes this routine to only
207452 ** * Raise an error if FLAGS is outside the range of 1 to 15.
207453 ** * Return NULL if the input is NULL
207454 ** * Return 1 if the input is well-formed.
207455 ** * Return 0 if the input is not well-formed.
207532 ** If the argument is NULL, return NULL
207534 ** If the argument is BLOB, do a full validity check and return non-zero
207535 ** if the check fails. The return value is the approximate 1-based offset
207538 ** Otherwise interpret the argument is TEXT (even if it is numeric) and
207569 assert( s.zJson!=0 ); /* Because s.oom is false */
207656 ** to the first comma (",") that is not within a string and deleting all
207674 /* pStr is always non-NULL since jsonArrayStep() or jsonObjectStep() will
207916 ** If the cursor is currently pointing at the label of a object entry,
207918 ** current pointer position, which is the value.
208152 /* The query strategy is to look for an equality constraint on the json
208153 ** column. Without such a constraint, the table cannot operate. idxNum is
208154 ** 1 if the constraint is found, 3 if the constraint and zRoot are found,
208471 ** a legal notice, here is a blessing:
208486 ** The data structure for a single virtual r-tree table is stored in three
208488 ** in the table name is replaced with the user-supplied name of the r-tree
208495 ** The data for each node of the r-tree structure is stored in the %_node
208496 ** table. For each node that is not the root node of the r-tree, there is
208498 ** And for each row of data in the table, there is an entry in the %_rowid
208500 ** is stored on. If the r-tree contains auxiliary columns, those are stored
208503 ** The root node of an r-tree always exists, even if the r-tree table is
208504 ** empty. The nodeno of the root node is always 1. All other nodes in the
208506 ** is formatted as follows:
208508 ** 1. If the node is the root node (node 1), then the first 2 bytes
208517 ** of 4-byte coordinates. For leaf nodes the integer is the rowid
208518 ** of a record. For internal nodes it is the node number of a
208534 ** If building separately, we will need some setup that is normally
208575 /* The following macro is used to suppress compiler warnings.
208597 /* Size of hash table Rtree.aHash. This hash table is not expected to
208598 ** ever contain very many entries, so a fixed number of buckets is
208605 ** various strategies. If possible, this estimate is loaded from the
208607 ** Otherwise, if no sqlite_stat1 entry is available, use
208642 /* List of nodes removed during a CondenseTree operation. List is
208677 ** If SQLITE_RTREE_INT_ONLY is defined, then this virtual table will
208704 ** The id is always a node-id. For iLevel>=1 the id is the node-id of
208706 ** the id is of the parent node and the cell that RtreeSearchPoint
208707 ** represents is the iCell-th entry in the parent node.
208718 ** The minimum number of cells allowed for a node is a third of the
208723 ** If an R*-tree "Reinsert" operation is required, the same number of
208731 ** The smallest possible node-size is (512-64)==448 bytes. And the largest
208732 ** supported cell size is 48 bytes (8 byte rowid + ten 4 byte coordinates).
208734 ** 3^40 is greater than 2^64, an r-tree structure always has a depth of
208741 ** Number of entries in the cursor RtreeNode cache. The first entry is
208753 u8 bPoint; /* True if sPoint is valid */
208754 u8 bAuxValid; /* True if pReadAux is valid */
208782 ** The argument is an RtreeCoord. Return the value stored within the RtreeCoord
208858 ** xGeom and xQueryFunc fields is non-NULL, depending on whether the
208862 ** This object is deleted automatically by the destructor mechanism in
208873 ** An instance of this structure (in the form of a BLOB) is returned by
208875 ** sqlite3_rtree_query_callback() create, and is read as the right-hand
208893 /* What version of GCC is being used. 0 means GCC is not being used .
208907 ** it is not, make it a no-op.
208936 ** Macros to determine whether the machine is big or little endian,
208937 ** and whether or not that determination is run-time or compile-time.
208939 ** For best performance, an attempt is made to guess at the byte-order
208940 ** using C-preprocessor macros. If that is unsuccessful, or if
208941 ** -DSQLITE_RUNTIME_BYTEORDER=1 is set, then byte-order is determined
208964 /* What version of MSVC is being used. 0 means MSVC is not being used */
208975 ** 64 bit integer. The deserialized value is returned.
209026 ** 64 bit integer. The value returned is the number of bytes written
209140 ** indicating that node has not yet been assigned a node number. It is
209141 ** assigned a node number when nodeWrite() is called to write the
209182 /* Check if the requested node is already in the hash table. If so,
209237 ** of the r-tree structure. A height of zero means all data is stored on
209240 ** is greater than RTREE_MAX_DEPTH, the r-tree structure must be corrupt.
209251 ** field on the node is too large. If so, set the return code to
209286 RtreeNode *pNode, /* The node into which the cell is to be written */
209288 int iCell /* Index into pNode into which pCell is written */
209313 ** is successful, return SQLITE_OK.
209315 ** If there is not enough free space in pNode, return SQLITE_FULL.
209339 ** If the node is dirty, write it out to the database.
209364 ** Release a reference to a node. If the node is dirty and the reference
209365 ** count drops to zero, the node data is written to the database.
209393 ** node pNode. If pNode is a leaf node, this is a rowid. If it is
209394 ** an internal node, then the 64-bit integer is a child page number.
209485 ** zero the structure is deleted.
209621 ** The on-disk format is big-endian and needs to be converted for little-
209623 ** eInt is true and it stores 32-bit floating point records if eInt is
209624 ** false. a[] is the four bytes of the on-disk record to be decoded.
209627 ** There are five versions of this macro. The last one is generic. The
209794 ** If this constraint is not satisfied, set *peWithin to NOT_WITHIN.
209795 ** If the constraint is satisfied, leave *peWithin unchanged.
209797 ** The constraint is of the form: xN op $val
209799 ** The op is given by p->op. The xN is p->iCoord-th coordinate in
209800 ** pCellData. $val is given by p->u.rValue.
209829 ** One of the cells in node pNode is guaranteed to have a 64-bit
209853 ** in its parent. If pNode is the root node, return -1.
209867 ** is less than, equal to, or greater than the second.
209869 ** The rScore is the primary key. Smaller rScore values come first.
209870 ** If the rScore is a tie, then use iLevel as the tie breaker with smaller
209871 ** iLevel values coming first. In this way, if rScore is the same for all
209873 ** is a depth-first search, which is the desired default behavior.
210081 ** or until the RtreeSearchPoint queue is empty, indicating that the
210247 ** return SQLITE_OK. If there is no such record in the table, set
210272 ** This function is called to configure the RtreeConstraint object passed
210274 ** first argument to this function is the right-hand operand to the MATCH
210450 ** If strategy 1 is used, then idxStr is not meaningful. If strategy
210451 ** 2 is used, idxStr is formatted to contain 2 bytes for each
210471 ** is 'a', the second from the left 'b' etc.
210485 ** is, do not consider the lookup-by-rowid plan as using such a plan would
210486 ** require the VDBE to evaluate the MATCH constraint, which is not currently
210514 ** sqlite uses an internal cost of 0.0). It is expected to return
210594 ** Return the margin length of cell p. The margin length is the sum
210628 ** Return true if the area covered by p2 is a subset of the area covered
210701 /* First check to see if there is are any cells in pNode that completely
210719 ** cell of pNode that grows by the least amount when pCell is added.
210819 ** minimum value of dimension iDim is considered first, the
210822 ** The aSpare array is used as temporary working space by the
211144 ** If node pLeaf is not the root of the r-tree and its pParent pointer is
211148 ** This operation is required when a row is deleted (or updated - an update
211149 ** is implemented as a delete followed by an insert). SQLite provides the
211151 ** the entry resides (argument pLeaf). Once the leaf is located, this
211152 ** function is called to determine its ancestry.
211279 /* If the node is not the tree root and now has less than the minimum
211298 ** Insert cell pCell into node pNode. Node pNode is the head of a
211418 ** This is equivalent to copying the contents of the child into
211494 ** Parameter iCol is the index of the leftmost column involved in the
211495 ** constraint failure. If it is 0, then the constraint that failed is
211496 ** the unique constraint on the id column. Otherwise, it is the rtree
211499 ** If an OOM occurs, SQLITE_NOMEM is returned instead of SQLITE_CONSTRAINT.
211548 int bHaveRowid = 0; /* Set to 1 after new rowid is determined */
211551 /* Unable to write to the btree while another cursor is reading from it,
211567 ** In the first case, if the conflict-handling mode is REPLACE, then
211577 /* Populate the cell.aCoord[] array. The first coordinate is aData[3].
211579 ** NB: nData can only be less than nDim*2+3 if the rtree is mis-declared
211609 /* If a rowid value was supplied, check if it is already present in
211633 /* If aData[0] is not an SQL NULL value, it is the rowid of a
211730 ** it uses this hook to close any open blob handle. This is done because a
211752 ** of the number of rows in the virtual table. If possible, this is based
211786 ** Return true if zName is the extension on one of the shadow tables used
211908 /* An UPSERT is very slightly slower than REPLACE, but it is needed
211959 ** that returns a single integer value. The statement is compiled and executed
211961 ** is written to *piVal and SQLITE_OK returned. Otherwise, an SQLite error
211962 ** code is returned and the value of *piVal after returning is not defined.
211980 ** This function is called from within the xConnect() or xCreate() method to
211982 ** to. If successful, pRtree->iNodeSize is populated and SQLITE_OK returned.
211983 ** Otherwise, an SQLite error code is returned.
211985 ** If this function is being called as part of an xConnect(), then the rtree
211986 ** table already exists. In this case the node-size is determined by inspecting
211990 ** This ensures that each node is stored on a single database page. If the
211991 ** database page-size is so large that more than RTREE_MAXCELLS entries
212043 ** This function is the implementation of both the xConnect and xCreate
212108 ** that is successful, call sqlite3_declare_vtab() to configure
212189 ** entry for each cell in the r-tree node. Each entry is itself a
212237 ** from the front of a blob that is an r-tree node. For example:
212241 ** The depth value is 0 for all nodes other than the root node, and the root
212242 ** node always has nodeno=1, so the example above is the primary use for this
212243 ** routine. This routine is intended for testing and analysis only.
212298 ** If successful, a pointer to the new SQL statement is returned. Otherwise,
212299 ** NULL is returned and an error code left in RtreeCheck.rc.
212351 ** This function is a no-op if there is already an error code stored
212352 ** in the RtreeCheck object indicated by the first argument. NULL is
212357 ** If no error occurs, a pointer to the buffer is returned and (*pnNode)
212358 ** is set to the size of the buffer in bytes.
212360 ** Or, if an error does occur, NULL is returned and an error code left
212361 ** in the RtreeCheck object. The final value of *pnNode is undefined in
212397 ** This function is used to check that the %_parent (if bLeaf==0) or %_rowid
212454 ** Additionally, if pParent is not NULL, then it is assumed to point to
212456 ** containing pCell. In this case it is also verified that the two
212478 "Dimension %d of cell %d on node %lld is corrupt", i, iCell, iNode
212490 "Dimension %d of cell %d on node %lld is corrupt relative to parent"
212499 ** Run rtreecheck() checks on node iNode, which is at depth iDepth within
212503 ** If any problems are discovered, an error message is appended to the
212522 "Node %lld is too small (%d bytes)", iNode, nNode
212538 "Node %lld is too small for cell count of %d (%d bytes)",
212565 ** %_rowid or %_parent table is exactly nExpect. If not, it adds
212591 ** It is called by rtreecheck(), which is the SQL function implementation.
212689 ** b) unless the cell is on the root node, that the cell is bounded
212692 ** c) for leaf nodes, that there is an entry in the %_rowid
212696 ** d) for cells on non-leaf nodes, that there is an entry in the
212702 ** is a leaf cell that corresponds to each entry in the %_rowid table.
212706 ** there is a non-leaf cell that corresponds to each entry in the
212747 ** a legal notice, here is a blessing:
212758 ** This file is #include-ed onto the end of "rtree.c" so that it has
212773 /* Use the SQLite core versions if this routine is part of the
212788 ** Growing our own isspace() routine this way is twice as fast as
212835 ** The polygon consists of a sequence of vertexes. There is a line
212838 ** standard in which the final vertex is a repeat of the first.)
212841 ** each segment is "outside" and the area to the left is "inside".
212844 ** the values. The 4-byte header is:
212849 ** Enough space is allocated for 4 coordinates, to work around over-zealous
212851 ** of each GeoPoly memory allocate is adjusted as necessary so that the
212852 ** GeoPoly.a[] array at the end is the appropriate size.
212868 ** to silence (incorrect) UBSAN warnings if the array index is too large.
212903 ** return non-zero on success and zero if the next token is not a number.
212942 /* The sqlite3AtoF() routine is much much faster than atof(), if it
212943 ** is available */
212956 ** If the input is a well-formed JSON array of coordinates with at least
212957 ** four coordinates and where each coordinate is itself a two-value array,
213037 ** return a pointer to that object. Or if the input is not a well-formed
213097 ** If the input is a well-formed Geopoly BLOB or JSON string
213119 ** of coordinates. Or, if X is not a valid polygon, return NULL.
213249 ** If the input is a well-formed Geopoly BLOB then return the area
213270 ** If the rotation of polygon X is clockwise (incorrect) instead of
213365 ** If pPoly is a polygon, compute its bounding box. Then:
213371 ** If pPoly is NULL but aCoord is not NULL, then compute a new GeoPoly from
213513 ** Determine if point (x0,y0) is beneath line segment (x1,y1)->(x2,y2).
213516 ** +2 x0,y0 is on the line segement
213518 ** +1 x0,y0 is beneath line segment
213520 ** 0 x0,y0 is not on or beneath the line segment or the line segment
213521 ** is vertical and x0,y0 is not on the line segment
213523 ** The left-most coordinate min(x1,x2) is not considered to be part of
213553 ** Return +2 if point X,Y is within polygon P.
213554 ** Return +1 if point X,Y is on the polygon boundary.
213555 ** Return 0 if point X,Y is outside the polygon
213598 ** Return +1 if P2 is contained within P1
213599 ** Return 0 if any part of P2 is on the outside of P1
213928 ** 2 P1 is completely contained within P2
213929 ** 3 P2 is completely contained within P1
213971 ** This function is the implementation of both the xConnect and xCreate
214022 ** that is successful, call sqlite3_declare_vtab() to configure
214028 pRtree->nAuxNotNull = 1; /* The _shape column is always not-null */
214355 int oldRowidValid; /* True if oldRowid is valid */
214357 int newRowidValid; /* True if newRowid is valid */
214361 /* Unable to write to the btree while another cursor is reading from it,
214391 /* If a rowid value was supplied, check if it is already present in
214408 /* If aData[0] is not an SQL NULL value, it is the rowid of a
214478 ** Report that geopoly_overlap() is an overloaded function suitable
214627 ** or sqlite3_rtree_query_callback(). In other words, this routine is the
214628 ** destructor for an RtreeGeomCallback objecct. This routine is called when
214629 ** the corresponding SQL function is deleted.
214638 ** This routine frees the BLOB that is returned by geomCallback().
214652 ** scalar function that is implemented by this routine.
214654 ** All this function does is construct an RtreeMatchArg object that
214771 ** a legal notice, here is a blessing:
214817 ** This function is called when an ICU function called from within
214820 ** The scalar function context passed as the first argument is
214845 ** Version of sqlite3_free() that is always a function, never a macro.
214852 ** This lookup table is used to help decode the first byte of
214853 ** a multi-byte UTF8 character. It is copied here from SQLite source
214884 ** Compare two UTF-8 strings for equality where the first string is
214907 ** 1. uPattern is an unescaped match-all character "%",
214908 ** 2. uPattern is an unescaped match-one character "_",
214909 ** 3. uPattern is an unescaped escape character, or
214910 ** 4. uPattern is to be handled as an ordinary character
214965 ** the build-in LIKE operator. The first argument to the function is the
214966 ** pattern and the second argument is the string. So, the SQL statements:
214970 ** is implemented as like(B, A). If there is an escape character E,
214974 ** is mapped to like(B, A, E).
215026 ** two arguments. The first is a regular expression pattern to compile
215027 ** the second is a string to match against that pattern. If either
215028 ** argument is an SQL NULL, then NULL Is returned. Otherwise, the result
215029 ** is 1 if the string matches the pattern, or 0 otherwise.
215051 /* If the left hand side of the regexp operator is NULL,
215052 ** then the result is also NULL.
215091 ** pointer. This is not really necessary, but it is tidier than
215117 ** should be invoked with two arguments. The second argument is the name
215119 ** as the second argument is the same as invoking the 1 argument version
215218 ** This scalar function is used to add ICU collation based collation
215219 ** types to an SQLite database connection. It is intended to be called
215224 ** Where <locale> is a string containing an ICU locale identifier (i.e.
215225 ** "en_AU", "tr_TR" etc.) and <collation-name> is the name of the
215329 ** a legal notice, here is a blessing:
215414 ** string to be tokenized is pInput[0..nBytes-1]. A cursor
215415 ** used to incrementally tokenize this string is returned in
215503 const char **ppToken, /* OUT: *ppToken is the token text */
215594 ** a legal notice, here is a blessing:
215608 ** that the user wishes to write to, a corresponding data_xyz table is
215614 ** 1) The database is updated. The modified database pages are written
215615 ** to a *-oal file. A *-oal file is just like a *-wal file, except
215616 ** that it is named "<database>-oal" instead of "<database>-wal".
215619 ** rollback mode while the *-oal file is being generated.
215628 ** 2) The "<database>-oal" file is moved to the equivalent "<database>-wal"
215633 ** Once the EXCLUSIVE lock is released, any other database readers
215638 ** 3) The new *-wal file is checkpointed. This proceeds in the same way
215639 ** as a regular database checkpoint, except that a single frame is
215640 ** checkpointed each time sqlite3rbu_step() is called. If the RBU
215641 ** handle is closed before the entire *-wal file is checkpointed,
215642 ** the checkpoint progress is saved in the RBU database and the
215648 ** The rename() call might not be portable. And RBU is not currently
215651 ** When state is saved, any commit to the *-oal file and the commit to
215668 ** update database than is strictly necessary.
215685 ** a legal notice, here is a blessing:
215703 ** The problem is that in order to update a b-tree, the leaf page (at least)
215705 ** working set of leaves is larger than the available cache memory, then a
215706 ** single leaf that is modified more than once as part of the transaction
215709 ** random order, access to pages within the database is also likely to be in
215710 ** random order, which is itself quite inefficient.
215712 ** One way to improve the situation is to sort the operations on each index
215715 ** and all but guarantees each modified leaf page is loaded and stored
215722 ** sequentially by separate processes. This is useful if the system cannot
215724 ** the entire update, for example because the update is being applied on a
215725 ** mobile device that is frequently rebooted. Even after the writer process
215732 ** applied using this extension is hence refered to as an "RBU update".
215737 ** An "RBU update" transaction is subject to the following limitations:
215757 ** * No constraint handling mode except for "OR ROLLBACK" is supported.
215762 ** An "RBU update" is stored as a separate SQLite database. A database
215763 ** containing an RBU update is an "RBU database". For each table in the
215784 ** may also be named data<integer>_<target>, where <integer> is any sequence
215792 ** If the target database table is a virtual table or a table that has no
215794 ** named "rbu_rowid". This column is mapped to the table's implicit primary
215825 ** If the target database table has an INTEGER PRIMARY KEY, it is not
215845 ** each column that is being updated, the corresponding character is set to
215852 ** is represented by the data_t1 row created by:
215859 ** user-defined SQL function "rbu_delta()" is invoked and the result stored in
215860 ** the target table column. rbu_delta() is invoked with two arguments - the
215868 ** is similar to an UPDATE statement such as:
215873 ** ota_control string, the contents of the data_xxx table column is assumed
215877 ** It is replaced by the result of applying the specified fossil delta to
215880 ** If the target database table is a virtual table or a table with no PRIMARY
215892 ** However, RBU is more efficient if reading the rows in from each data_xxx
215893 ** table in "rowid" order is roughly the same as reading them sorted by
215918 ** is marked as fully applied. Otherwise, the state of the RBU
215919 ** update application is saved in the RBU database for later
215924 ** If an update is only partially applied to the target database by the
215925 ** time sqlite3rbu_close() is called, various state information is saved
215930 ** to its original contents, it is sufficient to drop all tables that begin
215936 ** to do so is an error (SQLITE_ERROR).
215938 ** While an RBU handle is open, a SHARED lock may be held on the target
215939 ** database file. This means it is possible for other clients to read the
215942 ** If an RBU update is started and then suspended before it is completed,
215944 ** the suspended RBU update is also an error (SQLITE_BUSY).
215961 ** Argument zTarget is the path to the target database. Argument zRbu is
215968 ** If the zState argument is passed a NULL value, the RBU extension stores
215972 ** organize removing a separate state file after the update is concluded.
215973 ** Or, if zState is non-NULL, it must be a path to a database file in which
215979 ** Once the RBU update is finished, the RBU extension does not
215999 ** An RBU vacuum is similar to SQLite's built-in VACUUM command, except
216003 ** to store the state of the RBU vacuum operation if it is suspended. The
216004 ** first time sqlite3rbu_vacuum() is called, to start an RBU vacuum
216006 ** (contain no tables). If an RBU vacuum is suspended by calling
216008 ** returned SQLITE_DONE, the vacuum state is stored in the state database.
216012 ** If the second argument passed to this function is NULL, then the
216013 ** name of the state database is "<database>-vacuum", where <database>
216014 ** is the name of the target database file. In this case, on UNIX, if the
216015 ** state database is not already present in the file-system, it is created
216016 ** with the same permissions as the target db is made.
216018 ** With an RBU vacuum, it is an SQLITE_MISUSE error if the name of the
216019 ** state database ends with "-vactmp". This name is reserved for internal
216023 ** is completed, even if it created it. However, if the call to
216041 ** the RBU handle passed as the first argument. The new limit is specified
216042 ** in bytes by the second parameter. If it is positive, the limit is updated.
216043 ** If the second parameter to this function is passed zero, then the limit
216044 ** is removed entirely. If the second parameter is negative, the limit is
216045 ** not modified (this is useful for querying the current limit).
216047 ** In all cases the returned value is the current limit in bytes (zero
216050 ** If the temp space limit is exceeded during operation, an SQLITE_FULL
216051 ** error is returned.
216087 ** when sqlite3rbu_close() is called.
216099 ** the RBU update. If an error does occur, some other error code is
216116 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
216129 ** SQLite error code is returned. Additionally, if pzErrmsg is not NULL,
216131 ** English language error message. It is the responsibility of the caller to
216148 ** Obtain permyriadage (permyriadage is to 10000 as percentage is to 100)
216152 ** An RBU update is divided into two stages:
216158 ** The update is visible to non-RBU clients during stage 2. During stage 1
216161 ** If this API is called during stage 2 of the update, output variable
216162 ** (*pnOne) is set to 10000 to indicate that stage 1 has finished and (*pnTwo)
216164 ** stage 2. A value of 5000 indicates that stage 2 is half finished,
216165 ** 9000 indicates that it is 90% finished, and so on.
216167 ** If this API is called during stage 1 of the update, output variable
216168 ** (*pnTwo) is set to 0 to indicate that stage 2 has not yet started. The
216169 ** value to which (*pnOne) is set depends on whether or not the RBU
216180 ** If the rbu_count table is present and populated correctly and this
216181 ** API is called during stage 1, the *pnOne output variable is set to the
216183 ** not exist, then (*pnOne) is set to -1 during stage 1. If the rbu_count
216184 ** table exists but is not correctly populated, the value of the *pnOne
216185 ** output variable during stage 1 is undefined.
216195 ** RBU is currently building a *-oal file. The next call to sqlite3rbu_step()
216202 ** operation is an RBU update, then the updated version of the database
216207 ** RBU is currently performing an incremental checkpoint. The next call to
216235 ** If a callback is registered with an RBU handle, it invokes it instead
216237 ** first argument passed to the xRename() callback is a copy of the second
216238 ** argument (pArg) passed to this function. The second is the full path
216257 ** via existing VFS zParent. Or, if the zParent parameter is passed NULL,
216259 ** The new object is registered as a non-default VFS with SQLite before
216263 ** object is created and deleted automatically by RBU.
216265 ** The exception is for applications that also use zipvfs. In this case,
216267 ** handle is opened. The RBU VFS should be installed so that the zipvfs
216292 ** The overhead of adding the "rbu" VFS to the system is negligible for
216293 ** non-RBU users. There is no harm in an application accessing the
216303 ** VFS objects are not reference counted. If a VFS object is destroyed
216347 ** The rbu_state table is used to save the state of a partially applied
216353 ** 1: the *-rbu file is currently under construction.
216356 ** 4: the checkpoint is underway.
216365 ** currently being written, or NULL if the main table is currently being
216378 ** header created by recovering the *-wal file. This is used to detect
216469 ** An iterator of this type is used to iterate through all objects in
216478 ** If the table has no indexes on it, abIndexed is set to NULL. Otherwise,
216479 ** it points to an array of flags nTblCol elements in size. The flag is
216480 ** set for each column that is either a part of the PK or a part of an
216484 ** this array set set to 1. This is because in that case, the module has
216508 int bUnique; /* Current index is unique */
216532 ** 4: Table is WITHOUT ROWID.
216533 ** 5: Table is a virtual table.
216568 ** If the RBU database contains an rbu_count table, this value is set to
216576 ** nPhaseOneStep is initialized to the sum of:
216580 ** for all source tables in the RBU database, where nRow is the number
216584 ** This estimate is accurate if the RBU update consists entirely of
216585 ** INSERT operations. However, it is inaccurate if:
216600 ** nPhaseOneStep is updated to account for the conditions above during the
216601 ** first pass of each source table. The updated nPhaseOneStep value is
216602 ** stored in the rbu_state table if the RBU update is suspended.
216645 ** An rbu VFS is implemented using an instance of this structure.
216647 ** Variable pRbu is only non-NULL for automatically created RBU VFS objects.
216648 ** It is NULL for RBU VFS objects created explicitly using
216649 ** sqlite3rbu_create_vfs(). It is used to track the total amount of temp
216662 ** Each file opened by an rbu VFS is represented by an instance of
216665 ** If this is a temporary file (pRbu!=0 && flags&DELETE_ON_CLOSE), variable
216666 ** "sz" is set to the current size of the database file.
216711 ** in *pz and is decremented once for each character in the integer.
216787 ** the final NUL terminator character). Except, if the delta string is
216898 ** arguments must be passed to this function. The first is the blob to
216952 ** point to a buffer containing an error message. It is the responsibility
216974 ** containing an error message. It is the responsibility of the caller
216986 ** Unless it is NULL, argument zSql points to a buffer allocated using
216989 ** compilation is successful, *ppStmt is set to point to the new statement
216990 ** handle and SQLITE_OK is returned.
216992 ** Otherwise, if an error occurs, *ppStmt is set to NULL and an error code
216994 ** message. It is the responsibility of the caller to free this error message
216997 ** If argument zSql is NULL, this function assumes that an OOM has occurred.
216998 ** In this case SQLITE_NOMEM is returned and *ppStmt set to NULL.
217085 ** If no error occurs, SQLITE_OK is returned and the iterator is left
217086 ** pointing to the next entry. Otherwise, an error code and message is
217088 ** error code is returned.
217151 ** accepts one or two arguments. The first argument is the name of a table -
217152 ** the name of a table in the RBU database. The second, if it is present, is 1
217159 ** where <name> is any sequence of 1 or more characters, <name> is returned.
217161 ** NULL is returned.
217167 ** For an rbu vacuum handle, a copy of the first argument is returned if
217168 ** the second argument is either missing or 0 (not a view).
217201 ** If no error occurs, SQLITE_OK is returned and the iterator is left
217202 ** pointing to the first entry. Otherwise, an error code and message is
217204 ** error code is returned.
217233 ** This is a wrapper around "sqlite3_mprintf(zFmt, ...)". If an OOM occurs,
217234 ** an error code is stored in the RBU handle passed as the first argument.
217236 ** If an error has already occurred (p->rc is already set to something other
217257 ** Argument zFmt is a sqlite3_mprintf() style format string. The trailing
217262 ** If an error occurs, an error code and error message is stored in the
217263 ** RBU handle. If an error has already occurred when this function is
217264 ** called, it is a no-op.
217289 ** error has already occurred when this function is called, return NULL
217310 ** there is room for at least nCol elements. If an OOM occurs, store an
217331 ** It is the responsibility of the caller to eventually free this memory
217334 ** If an OOM condition is encountered when attempting to allocate memory,
217335 ** output variable (*pRc) is set to SQLITE_NOMEM before returning. Otherwise,
217336 ** if the allocation succeeds, (*pRc) is left unchanged.
217360 ** rbu handle error code is not already set, set the error code and error
217374 ** peType is of type (int*), a pointer to an output parameter of type
217382 ** RBU_PK_WITHOUT_ROWID: Table is WITHOUT ROWID.
217383 ** RBU_PK_VTAB: Table is a virtual table.
217385 ** Argument *piPk is also of type (int*), and also points to an output
217387 ** (i.e. unless *peType is set to 3), then *piPk is set to zero. Or,
217389 ** is set to the root page number of the primary key index before
217399 ** if( the index that is the pk exists in sqlite_schema ){
217494 ** This is a helper function for rbuObjIterCacheTableInfo(). It populates
217709 ** This function is called as part of restarting an RBU vacuum within
217710 ** stage 1 of the process (while the *-oal file is being built) while
217716 ** is of the form:
217773 ** This function is called as part of restating an RBU vacuum when the
217774 ** current operation is writing content to an index. If possible, it
217778 ** It is only possible to return such an expression if:
217784 ** The expression is of the form:
217790 ** If the expression cannot be created, NULL is returned. In this case,
217886 ** This function is used to create a SELECT list (the list of SQL
217890 ** second argument. A "PRAGMA index_xinfo = <idxname>" statement is used
217893 ** If the index is of the following form:
217897 ** and "t1" is a table with an explicit INTEGER PRIMARY KEY column
217898 ** "ipk", the returned string is:
218012 ** paramter is passed "old", return a string of the form:
218054 ** primary key of the current table. For example, if the table is:
218099 ** is something wrong with the rbu_control value in the rbu_control value
218114 ** column of the data_xxx table entry is set to zMask.
218116 ** The memory for the returned string is obtained from sqlite3_malloc().
218117 ** It is the responsibility of the caller to eventually free it using
218120 ** If an OOM error is encountered when allocating space for the new
218121 ** string, an error code is left in the rbu handle passed as the first
218122 ** argument and NULL is returned. Or, if an error has already occurred
218123 ** when this function is called, NULL is returned immediately, without
218167 ** "?" expressions. For example, if nByte is 3, return a pointer to
218170 ** The memory for the returned string is obtained from sqlite3_malloc().
218171 ** It is the responsibility of the caller to eventually free it using
218174 ** If an OOM error is encountered when allocating space for the new
218175 ** string, an error code is left in the rbu handle passed as the first
218176 ** argument and NULL is returned. Or, if an error has already occurred
218177 ** when this function is called, NULL is returned immediately, without
218251 ** a table (not index) with an external primary key, this function is a
218256 ** used to access that PK index. For example, if the target table is
218261 ** then the imposter table schema is:
218277 ** This is needed for the argument to "PRAGMA index_xinfo". Set
218321 ** If an error has already occurred when this function is called, it
218327 ** The iterator passed as the second argument is guaranteed to point to
218328 ** a table (not an index) when this function is called. This function
218330 ** table b-tree of the table before returning. Non-zero is returned if
218333 ** An imposter table is required in all cases except RBU_PK_VTAB. Only
218358 /* If the target table column is an "INTEGER PRIMARY KEY", add
218391 ** The number of bound variables is equal to the number of columns in
218393 ** (for the rbu_rowid column) if the target table is an implicit IPK or
218691 ** Because it only performs INSERT operations, this is not required for
218809 ** is not an error. Output variable *ppStmt is set to NULL in this case.
218824 /* Search for an existing statement. If one is found, shift it to the front
218911 ** table into it. Return a pointer to the new object. It is the
218995 ** If argument dbMain is not NULL, then it is a database handle already
219148 ** this call returns SQLITE_NOTFOUND, then the RBU vfs is not in use.
219149 ** This is an error. */
219161 ** This routine is a copy of the sqlite3FileSuffix3() routine from the core.
219162 ** It is a no-op unless SQLITE_ENABLE_8_3_NAMES is defined.
219164 ** If SQLITE_ENABLE_8_3_NAMES is set at compile-time and if the database
219165 ** filename in zBaseFilename is a URI with the "8_3_names=1" parameter and
219166 ** if filename in z[] has a suffix (a.k.a. "extension") that is longer than
219170 ** If SQLITE_ENABLE_8_3_NAMES is set to 2 at compile-time, then always
219198 ** The checksum is store in the first page of xShmMap memory as an 8-byte
219215 ** This function is called as part of initializing or reinitializing an
219223 ** If argument pState is not NULL, then the incremental checkpoint is
219225 ** following recovery is not the same as the checksum saved in the RbuState
219226 ** object, then the rbu handle is set to DONE state. This occurs if some
219232 /* If pState is NULL, then the wal file may not have been opened and
219258 ** is closed.
219266 ** WRITER, CHECKPOINT and READ0 locks are still held, it is safe to copy
219311 ** the rbu object is in capture mode. Record the frame number of the frame
219342 ** Called when a page of data is written to offset iOff of the database
219343 ** file while the rbu handle is in capture mode. Record the page number
219352 ** This is called as part of an incremental checkpoint operation. Copy
219371 ** This value is copied from the definition of ZIPVFS_CTRL_FILE_POINTER
219440 ** The RBU handle is currently in RBU_STAGE_OAL state, with a SHARED lock
219463 /* Move the *-oal file to *-wal. At this point connection p->db is
219464 ** holding a SHARED lock on the target database file (because it is
219468 ** lock is obtained here before the *-oal is moved to *-wal.
219520 ** If RBU_UPDATE is returned, then output variable *pzMask is set to
219567 ** Assert that column iCol of statement pStmt is named zName.
219594 /* If this is a delete, decrement nPhaseOneStep by nIndex. If the DELETE
219597 ** is invoked by the trigger. */
219609 /* If this is an INSERT into a table b-tree and the table has an
219610 ** explicit INTEGER PRIMARY KEY, check that this is not an attempt
219611 ** to write a NULL into the IPK column. That is not permitted. */
219635 ** SELECT statement is:
219659 ** input row. Perform whatever processing is required and return.
219661 ** If no error occurs, SQLITE_OK is returned. Otherwise, an error code
219662 ** and message is left in the RBU handle and a copy of the error code
219726 ** Or, if this is an RBU vacuum, set the schema cookie of the main db
219741 ** is already a transaction open, so the prepared statement cannot
219743 ** statement reads is page 1, which is guaranteed to be in the cache.
219758 ** value stored in the RBU_STATE_STAGE column is eStage. All other values
219806 ** The second argument passed to this function is the name of a PRAGMA
219812 ** where $zPragma is the string passed as the second argument, then
219817 ** where $val is the value returned by the first PRAGMA invocation.
219839 ** the state database is empty. If this RBU handle was opened for an
219900 /* If this is an RBU vacuum operation and the state table was empty
219987 ** However, if the sector-size is larger than the page-size, and the
220021 ** considered equal, and NULL is considered distinct from all other values.
220030 ** This function is called as part of sqlite3rbu_open() when initializing
220032 ** the rbu_state table was empty) it is a no-op. Otherwise, it arranges
220068 ** If there is a "*-oal" file in the file-system corresponding to the
220117 ** This user-defined SQL function is invoked with a single argument - the
220159 ** is assumed to contain the same columns as:
220167 ** sqlite3rbu.nPhaseOneStep is initialized to the sum of (1 + nIndex) * cnt
220168 ** for all rows in the rbu_count table, where nIndex is the number of
220251 ** If this is the case, it will have been checkpointed and deleted
220297 ** transaction is committed in rollback mode) currently stored on
220327 /* Open transactions both databases. The *-oal file is opened or
220333 /* Check if the main database is a zipvfs db. If it is, set the upper
220353 ** and an incremental checkpoint is being resumed, attempt an
220375 ** error code, which is set to SQLITE_MISUSE.
220430 ** If the error code currently stored in the RBU handle is SQLITE_CONSTRAINT,
220476 /* If this is an RBU vacuum handle and the vacuum has either finished
220672 ** 1. Whenever the first page of a main database file is read or
220673 ** written, the value of the change-counter cookie is stored in
220675 ** database header field is stored in rbu_file.iWriteVer. This ensures
220678 ** 2. Whenever an SQLITE_OPEN_WAL file is opened, the (rbu_file.pWalFd)
220679 ** member variable of the associated database file descriptor is set
220681 ** db fds opened using a particular RBU VFS is maintained at
220688 ** 3a. If xAccess() is called to check if there exists a *-wal file
220699 ** Then, when xOpen() is called to open the *-wal file associated with
220704 ** RBU_STAGE_OAL mode are actually stored in heap memory. This is to
220706 ** are no-ops on target database files in RBU_STAGE_OAL mode. This is
220708 ** xShmLock() is called before xShmMap().
220710 ** 3c. If an EXCLUSIVE lock is attempted on a target database file in any
220712 ** fails with an SQLITE_BUSY error. This is to stop RBU connections
220754 ** Add an item to the main-db lists, if it is not already present.
220758 ** rbu_file.pDb!=0, then it is assumed to already be present on the
220759 ** main list and is only added to the pDb!=0 list.
220801 ** If parameter bRbu is true, only search for file-descriptors with
220904 /* If this is being called to read the first page of the target
221021 /* If this is an RBU vacuum operation and this is the target database,
221087 ** one is found, this vfs will operate in pass-through mode. The lower
221093 ** one is found, this is an error. */
221163 ** is supplying heap memory to the upper layer in place of *-shm
221197 ** rbu is in the RBU_STAGE_OAL state, use heap memory for *-shm space
221204 /* This is an RBU connection that uses its own heap memory for the
221340 /* This call is to open a *-wal file. Intead, open the *-oal. */
221372 ** pointer and, if the file is a main database file, link it into the
221399 ** is available, or false otherwise.
221413 /* If this call is to check if a *-wal file associated with an RBU target
221414 ** database connection exists, and the RBU update is in RBU_STAGE_OAL,
221415 ** the following special handling is activated:
221446 ** to the pathname in zPath. zOut is guaranteed to point to a buffer
221547 ** via existing VFS zParent. The new object is registered as a non-default
221650 ** a legal notice, here is a blessing:
221660 ** The dbstat virtual table is used to extract low-level storage
221665 ** Additional information is available on the "dbstat.html" page of the
221687 ** root-node path is '/'.
221690 ** a b-tree is '/000/'. (Btrees store content ordered from left to right
221692 ** The next to left-most child of the root page is
221739 u32 iChildPg; /* Child node (or 0 if this is a leaf) */
221855 ** 0x01 There is a schema=? term in the WHERE clause
221856 ** 0x02 There is a name=? term in the WHERE clause
221857 ** 0x04 There is an aggregate=? term in the WHERE clause
221974 ** to sqlite3_reset() may cause the pager to be reset (emptied). It is
221975 ** important that statClearPage() is called to free any page refs before
222012 ** content (payload) stored on that page. That is to say, compute the
222212 ** the next entry is the next btree.
222293 ** an entire btree, this is the exit point from this function */
222398 /* schema=? constraint is present. Get its value */
222410 /* name=? constraint is present */
222414 /* aggregate=? constraint is present */
222558 ** a legal notice, here is a blessing:
222568 ** The sqlite_dbpage virtual table is used to read or write whole raw
222569 ** pages of the database file. The pager interface is used so that
222577 ** This is an eponymous virtual table so it does not need to be created before
222578 ** use. The optional argument to the sqlite_dbpage() table name is the
222579 ** schema for the database file that is to be read. The default schema is
222583 ** value must be a BLOB which is the correct page size, otherwise the
222673 /* If there is a schema= constraint, it must be honored. Report a
222674 ** ridiculously large estimated cost if the schema= constraint is
222691 /* If we reach this point, it means that either there is no schema=
222773 ** idxStr is not used
222788 /* Default setting is no rows of result */
222838 /* The pending byte page. Assume it is zeroed out. Attempting to
222839 ** request this page from the page is an SQLITE_CORRUPT error. */
223036 sqlite3 *db; /* Database handle session is attached to */
223037 char *zDb; /* Name of database session is attached to */
223064 ** An object of this type is used internally as an abstraction for
223088 int bPatchset; /* True if this is a patchset */
223103 ** for each table the session object is monitoring. The structures are
223110 ** The data associated with each hash-table entry is a structure containing
223115 ** This is only used by the sqlite3changegroup_xxx() APIs, not by
223116 ** regular sqlite3_session objects. It is a SELECT statement that
223118 ** if the table is
223122 ** then this variable is the compiled version of:
223130 int bStat1; /* True if this is sqlite_stat1 */
223144 ** The following record format is similar to (but not compatible with) that
223145 ** used in SQLite database files. This format is used as part of the
223148 ** Unlike the SQLite database record format, each field is self-contained -
223149 ** there is no separation of header and data. Each field begins with a
223162 ** is followed by:
223167 ** of the text value. There is no nul terminator.
223184 ** A changeset is a collection of DELETE, UPDATE and INSERT operations on
223204 ** format described above under "RECORD FORMAT", where N is the number of
223205 ** columns in the table. The i'th field of each record is associated with
223209 ** The new.* record that is part of each INSERT change contains the values
223210 ** that make up the new row. Similarly, the old.* record that is part of each
223227 ** A patchset is also a collection of changes. It is similar to a changeset,
223229 ** resolution is required when applying the changeset.
223245 ** As in the changeset format, each field of the single record that is part
223246 ** of a patchset change is associated with the correspondingly positioned
223260 ** changesets. It is not possible for a record associated with an INSERT
223271 ** The format used for a rebase blob is very similar to that used for
223287 ** In a rebase blob, the first field is set to SQLITE_INSERT if the change
223289 ** it was a DELETE. The second field is set to 0x01 if the conflict
223293 ** record is a copy of the old.* record from the original changeset. If it
223294 ** was an INSERT, then the single record is a copy of the new.* record. If
223295 ** the conflicting change was an UPDATE, then the single record is a copy
223306 u8 bIndirect; /* True if this change is "indirect" */
223366 ** This function is used to serialize the contents of value pValue (see
223369 ** If it is non-NULL, the serialized form of the value is written to
223370 ** buffer aBuf. *pnWrite is set to the number of bytes written before
223371 ** returning. Or, if aBuf is NULL, the only thing this function does is
223374 ** If no error occurs, SQLITE_OK is returned. Or, if an OOM error occurs
223375 ** within a call to sqlite3_value_text() (may fail if the db is utf-16))
223376 ** SQLITE_NOMEM is returned.
223451 ** pSession is not NULL, increase the sqlite3_session.nMalloc variable
223462 ** call to sessionMalloc64(). If pSession is not NULL, decrease the
223471 ** This macro is used to calculate hash key values for data structures. In
223482 ** In practice, the data structures this macro is used for are the primary
223519 ** values, *pbNullPK is set to true before returning.
223521 ** If an error occurs, an SQLite error code is returned and the final values
223522 ** of *piHash asn *pbNullPK are undefined. Otherwise, SQLITE_OK is returned
223613 ** The bPkOnly argument is non-zero if the record at aRecord[] is from
223631 /* It is not possible for eType to be SQLITE_NULL here. The session
223698 ** a single records which is written to the buffer at *paOut. *paOut is
223702 ** The merging of records is done as follows: For each column, if the
223737 ** This is a helper function used by sessionMergeUpdate().
223739 ** When this function is called, both *paOne and *paTwo point to a value
223743 ** If, when this function is called, *paTwo points to a valid value (i.e.
223744 ** *paTwo[0] is not 0x00 - the "no value" placeholder), a copy of the *paTwo
223745 ** pointer is returned and *pnVal is set to the number of bytes in the
223746 ** serialized value. Otherwise, a copy of *paOne is returned and *pnVal
223748 ** to the "no value" placeholder, *pnVal is set to 1. In other words:
223750 ** if( *paTwo is valid ) return *paTwo;
223785 ** This function is used by changeset_concat() to merge two UPDATE changes
223859 ** This function is only called from within a pre-update-hook callback.
223890 ** fail. This is because they cache their return values, and by the
223946 ** It is possible that a non-fatal OOM error occurs in this function. In
223947 ** that case the hash-table does not grow, but SQLITE_OK is returned anyway.
223948 ** Growing the hash table in this case is a performance optimization only,
223949 ** it is not required for correct operation.
223996 ** Otherwise, if they are not NULL, variable *pnCol is set to the number
223997 ** of columns in the database table and variable *pzTab is set to point to a
223998 ** nul-terminated copy of the table name. *pazCol (if not NULL) is set to
224000 ** NULL) is set to point to an array of booleans - true if the corresponding
224001 ** column is part of the primary key.
224003 ** For example, if the table is declared as:
224028 int *pbRowid /* OUT: True if only PK is a rowid */
224055 /* For sqlite_stat1, pretend that (tbl,idx) is the PRIMARY KEY. */
224162 ** This function is called to initialize the SessionTable.nCol, azCol[]
224164 ** fields are already initilialized, this function is a no-op.
224166 ** If an error occurs, an error code is stored in sqlite3_session.rc and
224168 ** key, sqlite3_session.rc is left set to SQLITE_OK and non-zero returned to
224170 ** is set to NULL in this case.
224364 ** Ensure that there is room in the buffer to append nByte bytes of data.
224365 ** If not, use sqlite3_realloc() to grow the buffer so that there is.
224367 ** If successful, return zero. Otherwise, if an OOM condition is encountered,
224381 /* The value of SESSION_MAX_BUFFER_SZ is copied from the implementation
224383 ** always fail. It is used here to ensure that this routine can always
224407 ** This function is a no-op if *pRc is other than SQLITE_OK when it is
224411 ** If an OOM condition is encountered, set *pRc to SQLITE_NOMEM before
224455 ** example, if pTab is declared as:
224518 ** sqlite_stat1 table. The purpose of this is to substitute a zero-length
224519 ** blob each time a NULL value is read from the "idx" column of the
224558 sqlite3_session *pSession, /* Session object pTab is attached to */
224660 ** This function is only called from with a pre-update-hook reporting a
224662 ** (UPDATE, INSERT, DELETE) is specified by the first argument.
224664 ** Unless one is already present or an error occurs, an entry is added
224670 sqlite3_session *pSession, /* Session object pTab is attached to */
224738 ** this is an SQLITE_UPDATE or SQLITE_DELETE), or just the PK
224739 ** values (if this is an INSERT). */
224746 /* Figure out how large an allocation is required */
224780 ** It is not possible for an OOM to occur in this block. */
224808 /* If the existing change is considered "indirect", but this current
224809 ** change is "direct", mark the change object as direct. */
224849 /* If there is a table-filter configured, invoke it. If it returns 0,
224893 /* If this session is attached to a different database ("main", "temp"
224894 ** etc.), or if it is not currently enabled, there is nothing to do. Skip
225361 ** while the session object is enabled will be recorded.
225364 ** not matter if the PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias)
225380 /* First search for an existing entry. If one is found, this call is
225397 ** appear in the correct order when a changeset or patchset is
225417 ** This function is a no-op if *pRc is non-zero when it is called.
225418 ** Otherwise, if an error occurs, *pRc is set to an SQLite error code
225437 ** This function is a no-op if *pRc is other than SQLITE_OK when it is
225440 ** If an OOM condition is encountered, set *pRc to SQLITE_NOMEM before
225450 ** This function is a no-op if *pRc is other than SQLITE_OK when it is
225453 ** If an OOM condition is encountered, set *pRc to SQLITE_NOMEM before
225463 ** This function is a no-op if *pRc is other than SQLITE_OK when it is
225466 ** If an OOM condition is encountered, set *pRc to SQLITE_NOMEM before
225482 ** This function is a no-op if *pRc is other than SQLITE_OK when it is
225484 ** to the buffer. No nul-terminator is written.
225486 ** If an OOM condition is encountered, set *pRc to SQLITE_NOMEM before
225500 ** This function is a no-op if *pRc is other than SQLITE_OK when it is
225503 ** nul-terminator byte is written.
225505 ** If an OOM condition is encountered, set *pRc to SQLITE_NOMEM before
225529 ** This function is a no-op if *pRc is other than SQLITE_OK when it is
225590 ** (i.e. nothing has changed), then no data at all is appended to the buffer.
225657 /* If at least one field has been modified, this is not a no-op. */
225660 /* Add a field to the old.* record. This is omitted if this module is
225693 ** the changeset format if argument bPatchset is zero, or the patchset
225751 ** where <noop-test> is:
225856 ** is as prepared by function sessionSelectStmt().
225927 ** This function is a no-op if *pRc is set to other than SQLITE_OK when it
225928 ** is called. Otherwise, append a serialized table header (part of the binary
225946 ** Generate either a changeset (if argument bPatchset is zero) or a patchset
225947 ** (if it is non-zero) based on the current contents of the session object
225950 ** If no error occurs, SQLITE_OK is returned and the new changeset/patchset
225952 ** occurs, an SQLite error code is returned and both output variables set
225972 ** object is already in the error state (sqlite3_session.rc != SQLITE_OK),
225995 /* Check the table schema is still Ok. */
226037 /* If the buffer is now larger than sessions_strm_chunk_size, pass
226079 ** It is the responsibility of the caller to eventually free the buffer
226125 ** It is the responsibility of the caller to eventually free the buffer
226314 ** If the SessionInput object passed as the only argument is a streaming
226315 ** object and the buffer is full, discard some data to free up space.
226333 ** data is in the buffer.
226361 ** When this function is called, *ppRec points to the start of a record
226388 ** buffer. SQLITE_OK is returned if successful, or SQLITE_NOMEM if an OOM
226412 ** When this function is called, *paChange points to the start of the record
226413 ** to deserialize. Assuming no error occurs, *paChange is set to point to
226415 ** If the argument abPK is NULL, then the record contains nCol values. Or,
226416 ** if abPK is other than NULL, then the record contains only the PK fields
226417 ** (in other words, it is a patchset DELETE record).
226420 ** is set to point to an sqlite3_value object containing the value read
226421 ** from the corresponding position in the record. If that value is not
226422 ** included in the record (i.e. because the record is part of an UPDATE change
226423 ** and the field was not modified), the corresponding element of apOut[] is
226426 ** It is the responsibility of the caller to free all sqlite_value structures
226429 ** If an error occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.
226507 ** This function ensures that all of the above is present in the input
226509 ** If successful, SQLITE_OK is returned. Otherwise, an SQLite error code.
226510 ** The input pointer is not moved.
226521 ** database table is, according to sqliteLimit.h, 32676. So
226523 ** columns to be corrupt. This is convenient because otherwise,
226549 ** record is buffered. It does not move the input pointer.
226551 ** If successful, SQLITE_OK is returned and *pnByte is set to the size of
226552 ** the record in bytes. Otherwise, an SQLite error code is returned. The
226553 ** final value of *pnByte is undefined in this case.
226591 ** p->zTab and p->abPK[] variables accordingly. The p->apValue[] array is
226593 ** input pointer is left pointing to the byte following the table header.
226595 ** If successful, SQLITE_OK is returned. Otherwise, an SQLite error code
226596 ** is returned and the final values of the various fields enumerated above
226642 ** * If pbEmpty is not NULL and the change is a no-op UPDATE (an UPDATE
226645 ** * If the iterator is configured to skip no-op UPDATEs,
226661 /* If the iterator is in the error-state, return immediately. */
226673 ** remaining data if there are less than 10 bytes available. This is
226679 /* If the iterator is already at the end of the changeset, return DONE. */
226699 /* The first record in the changeset is not a table header. Must be a
226729 /* If this is an UPDATE or DELETE, read the old.* record. */
226736 /* If this is an INSERT or UPDATE, read the new.* record. */
226743 /* If this is an UPDATE that is part of a patchset, then all PK and
226745 ** is currently completely empty. This block shifts the PK fields from
226761 /* If this is an UPDATE that is part of a changeset, then check that
226766 ** point generating them. Under most circumstances this is benign, but
226785 ** API sqlite3changeset_next(). If SQLITE_ROW is returned, then the
226789 ** record is written to *paRec before returning and the number of bytes in
226792 ** Either way, this function returns SQLITE_ROW if the iterator is
226834 int *pbIndirect /* OUT: True if change is indirect */
226860 ** This function may only be called while the iterator is pointing to an
226862 ** Otherwise, SQLITE_MISUSE is returned.
226865 ** iVal'th value in the old.* record. Or, if that particular value is not
226866 ** included in the record (because the change is an UPDATE and the field
226867 ** was not modified and is not a PK column), set *ppValue to NULL.
226869 ** If value iVal is out-of-range, SQLITE_RANGE is returned and *ppValue is
226888 ** This function may only be called while the iterator is pointing to an
226890 ** Otherwise, SQLITE_MISUSE is returned.
226893 ** iVal'th value in the new.* record. Or, if that particular value is not
226894 ** included in the record (because the change is an UPDATE and the field
226897 ** If value iVal is out-of-range, SQLITE_RANGE is returned and *ppValue is
226926 ** conflict-handler function. Otherwise, SQLITE_MISUSE is returned.
226928 ** If successful, *ppValue is set to point to an sqlite3_value structure
226931 ** If value iVal is out-of-range or some other error occurs, an SQLite error
226932 ** code is returned. Otherwise, SQLITE_OK.
227203 u8 *abPK; /* Boolean array - true if column is in PK */
227206 int bStat1; /* True if table is sqlite_stat1 */
227211 u8 bRebaseStarted; /* If table header is already in rebase */
227222 ** being visited by the iterator. The UPDATE is of the form:
227388 ** Variable :5 (nCol+1) is a boolean. It should be set to 0 if we require
227390 ** conflict handler is invoked with NOTFOUND and returns CHANGESET_REPLACE.
227392 ** If successful, SQLITE_OK is returned and SessionApplyCtx.pDelete is left
227457 ** If successful, SQLITE_OK is returned and SessionApplyCtx.pSelect is left
227477 ** If successful, SQLITE_OK is returned and SessionApplyCtx.pInsert is left
227549 /* COVERAGE: The (pVal->z==0) branch is never true using current versions
227551 ** the (pVal->z) variable remains as it was or the type of the value is
227567 ** New.* value $i from the iterator is bound to variable ($i+1) of
227568 ** statement pStmt. If parameter abPK is NULL, all values from 0 to (nCol-1)
227569 ** are transfered to the statement. Otherwise, if abPK is not NULL, it points
227571 ** which abPK[$i] is true are read from the iterator and bound to the
227574 ** An SQLite error code is returned if an error occurs. Otherwise, SQLITE_OK.
227588 ** is one of these to guarantee that it is safe to ignore the return
227609 ** SQL statement pSelect is as generated by the sessionSelectRow() function.
227612 ** entry. If a row is found, the SELECT statement left pointing at the row
227613 ** and SQLITE_ROW is returned. Otherwise, if no row is found and no error
227614 ** has occured, the statement is reset and SQLITE_OK is returned. If an
227615 ** error occurs, the statement is reset and an SQLite error code is returned.
227618 ** statement pSelect. If any other value is returned, the statement does
227663 ** This function is called from within sqlite3changeset_apply_v2() when
227664 ** a conflict is encountered and resolved using conflict resolution
227716 ** If argument pbReplace is NULL, then the type of conflict handler invoked
227724 ** Or, if pbReplace is not NULL, then an attempt is made to find an existing
227726 ** or inserted. If such a record can be found, it is available to the conflict
227728 ** handler invoked is as follows:
227737 ** If pbReplace is not NULL, and a record with a matching PK is found, and
227739 ** is set to non-zero before returning SQLITE_OK.
227741 ** If the conflict handler returns SQLITE_CHANGESET_ABORT, SQLITE_ABORT is
227752 int *pbReplace /* OUT: Set to true if PK row is found */
227828 ** currently points to to the database. If a conflict is encountered, invoke
227831 ** If argument pbRetry is NULL, then ignore any CHANGESET_DATA conflict. If
227832 ** one is encountered, update or delete the row with the matching primary key
227833 ** instead. Or, if pbRetry is not NULL and a CHANGESET_DATA conflict occurs,
227838 ** If argument pbReplace is NULL and a CHANGESET_CONFLICT conflict is
227840 ** Or, if pbReplace is not NULL, invoke it with CHANGESET_CONFLICT. If such
227847 ** returns SQLITE_ABORT. Otherwise, if no error occurs, SQLITE_OK is
227871 /* Bind values to the DELETE statement. If conflict handling is required,
227873 ** Or, if conflict handling is not required, bind just the PK column
227875 ** is not required if:
227877 ** * this is a patchset, or
227879 ** * all columns of the table are PK columns (in this case there is
227928 ** a row with a matching primary key. If so, this is a DATA conflict.
227929 ** Otherwise, if there is no primary key match, it is a NOTFOUND. */
227936 /* This is always a CONSTRAINT conflict. */
227945 /* Check if there is a conflicting row. For sqlite_stat1, this needs
227946 ** to be done using a SELECT, as there is no PRIMARY KEY in the
227947 ** database schema to throw an exception if a duplicate is inserted. */
227975 ** currently points to to the database. If a conflict is encountered, invoke
227978 ** The difference between this function and sessionApplyOne() is that this
227979 ** function handles the case where the conflict-handler is invoked and
227996 /* If the bRetry flag is set, the change has not been applied due to an
227997 ** SQLITE_CHANGESET_DATA problem (i.e. this is an UPDATE or DELETE and
227998 ** a row with the correct PK is present in the db, but one or more other
228008 /* If the bReplace flag is set, the change is an INSERT that has not
228090 ** Argument pIter is a changeset iterator that has been initialized, but
228093 ** conflict handler callback is invoked to resolve any conflicts encountered
228232 /* If there is a schema mismatch on the current table, proceed to the
228427 ** This function is called to merge two changes to the same row together as
228428 ** part of an sqlite3changeset_concat() operation. A new change object is
228437 int bIndirect, /* True if second change is indirect */
228545 ** buffer of the new object is large enough to hold any record that
228612 ** as the final argument to this function is compatible with SessionTable
228694 ** is an UPDATE, to the new.* record as well. */
228725 int bRebase /* True if hash table is for rebasing */
228744 ** of both, are being combined. It is an error to try to combine a
228789 ** simply added to the start of it. This is to ensure that the
228856 ** If xOutput is not NULL, then the changeset/patchset is returned to the
228860 ** Or, if xOutput is NULL, then (*ppOut) is populated with a pointer to a
228862 ** this case (*pnOut) is set to the size of the output buffer in bytes. It
228863 ** is the responsibility of the caller to free the output buffer using
228864 ** sqlite3_free() when it is no longer required.
228866 ** If successful, SQLITE_OK is returned. Or, if an error occurs, an SQLite
228867 ** error code. If an error occurs and xOutput is NULL, (*ppOut) and (*pnOut)
229096 ** record to buffer pBuf that is a copy of a1, except that for
229097 ** each field that is undefined in a1[], swap in the field from a2[].
229130 ** This function is called when rebasing a local UPDATE change against one
229133 ** record) is in aChange/nChange. The rebased change is appended to buffer
229139 ** in the rebase buffer is set to "replaced" (type 0xFF). If this
229140 ** means the UPDATE change updates no fields, nothing is appended
229144 ** corresponding field in the rebase buffer is not "undefined" (0x00)
229145 ** or "replaced" (0xFF), the old.* value is replaced by the value
229202 ** pIter is configured to iterate through a changeset. This function rebases
229205 ** is not NULL, then the changeset is returned to the caller by invoking
229206 ** xOutput zero or more times and SQLITE_OK returned. Or, if xOutput is NULL,
229207 ** then (*ppOut) is set to point to a buffer containing the rebased changeset
229208 ** before this function returns. In this case (*pnOut) is set to the size of
229209 ** the buffer in bytes. It is the responsibility of the caller to eventually
229212 ** If an error occurs, an SQLite error code is returned. If ppOut and
229469 ** a legal notice, here is a blessing:
229526 ** If parameter iCol is less than zero, set output variable *pnToken
229527 ** to the total number of tokens in the FTS5 table. Or, if iCol is
229532 ** If parameter iCol is greater than or equal to the number of columns
229533 ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
229534 ** an OOM condition or IO error), an appropriate SQLite error code is
229541 ** If parameter iCol is less than zero, set output variable *pnToken
229542 ** to the total number of tokens in the current row. Or, if iCol is
229546 ** If parameter iCol is greater than or equal to the number of columns
229547 ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
229548 ** an OOM condition or IO error), an appropriate SQLite error code is
229555 ** If parameter iCol is less than zero, or greater than or equal to the
229556 ** number of columns in the table, SQLITE_RANGE is returned.
229559 ** the current document. If successful, (*pz) is set to point to a buffer
229560 ** containing the text in utf-8 encoding, (*pn) is set to the size in bytes
229561 ** (not characters) of the buffer and SQLITE_OK is returned. Otherwise,
229562 ** if an error occurs, an SQLite error code is returned and the final values
229569 ** If parameter iCol is less than zero, or greater than or equal to the
229571 ** 0 is returned. Otherwise, this function returns the number of tokens in
229580 ** "detail=none" or "detail=column" option. If the FTS5 table is created
229582 ** (i.e. if it is a contentless table), then this API always returns 0.
229588 ** output by xInstCount(). If iIdx is less than zero or greater than
229589 ** or equal to the value returned by xInstCount(), SQLITE_RANGE is returned.
229591 ** Otherwise, output parameter *piPhrase is set to the phrase number, *piCol
229593 ** first token of the phrase. SQLITE_OK is returned if successful, or an
229606 ** This API function is used to query the FTS table for phrase iPhrase
229612 ** current query is executed. Any column filter that applies to
229613 ** phrase iPhrase of the current query is included in $p. For each
229615 ** is invoked. The context and API objects passed to the callback
229620 ** If parameter iPhrase is less than zero, or greater than or equal to
229625 ** query is abandoned and the xQueryPhrase function returns immediately.
229626 ** If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK.
229627 ** Otherwise, the error code is propagated upwards.
229629 ** If the query runs to completion without incident, SQLITE_OK is returned.
229630 ** Or, if some error occurs before the query completes or is aborted by
229631 ** the callback, an SQLite error code is returned.
229641 ** Each extension function is allocated a single auxiliary data slot for
229642 ** each FTS query (MATCH expression). If the extension function is invoked
229646 ** If there is already an auxiliary data pointer when this function is
229647 ** invoked, then it is replaced by the new pointer. If an xDelete callback
229648 ** was specified along with the original pointer, it is invoked at this
229651 ** The xDelete callback, if one is specified, is also invoked on the
229655 ** the auxiliary data is set to NULL and an error code returned. If the
229656 ** xDelete parameter was not NULL, it is invoked on the auxiliary data
229665 ** If the bClear argument is non-zero, then the auxiliary data is cleared
229667 ** if any, is not invoked.
229672 ** This function is used to retrieve the total number of rows in the table.
229678 ** This function is used, along with type Fts5PhraseIter and the xPhraseNext
229680 ** the current row. This is the same information as is accessible via the
229694 ** The Fts5PhraseIter structure is defined above. Applications should not
229700 ** "detail=none" or "detail=column" option. If the FTS5 table is created
229702 ** (i.e. if it is a contentless table), then this API always iterates
229710 ** and xPhraseNext() APIs described above. The difference is that instead
229725 ** "detail=none" option. If the FTS5 table is created with either
229726 ** "detail=none" "content=" option (i.e. if it is a contentless table),
229732 ** (or xInst/xInstCount). The chief advantage of this API is that it is
229740 ** This is used to access token iToken of phrase iPhrase of the current
229741 ** query. Before returning, output parameter *ppToken is set to point
229745 ** If iPhrase or iToken are less than zero, or if iPhrase is greater than
229747 ** xPhraseCount(), or if iToken is equal to or greater than the number of
229748 ** tokens in the phrase, SQLITE_RANGE is returned and *ppToken and *pnToken
229751 ** The output text is not a copy of the query text that specified the
229752 ** token. It is the output of the tokenizer module. For tokendata=1
229756 ** This is used to access token iToken of phrase hit iIdx within the
229757 ** current row. If iIdx is less than zero or greater than or equal to the
229758 ** value returned by xInstCount(), SQLITE_RANGE is returned. Otherwise,
229759 ** output variable (*ppToken) is set to point to a buffer containing the
229761 ** bytes. This API is not available if the specified token matches a
229765 ** The output text is not a copy of the document text that was tokenized.
229766 ** It is the output of the tokenizer module. For tokendata=1 tables, this
229825 ** is registered by providing fts5 with a populated instance of the
229831 ** This function is used to allocate and initialize a tokenizer instance.
229832 ** A tokenizer instance is required to actually tokenize text.
229834 ** The first argument passed to this function is a copy of the (void*)
229842 ** The final argument is an output variable. If successful, (*ppOut)
229846 ** is undefined.
229849 ** This function is invoked to delete a tokenizer handle previously
229854 ** This function is expected to tokenize the nText byte string indicated
229856 ** argument passed to this function is a pointer to an Fts5Tokenizer object
229859 ** The second argument indicates the reason that FTS5 is requesting
229860 ** tokenization of the supplied text. This is always one of the following
229863 ** <ul><li> <b>FTS5_TOKENIZE_DOCUMENT</b> - A document is being inserted into
229864 ** or removed from the FTS table. The tokenizer is being invoked to
229868 ** <li> <b>FTS5_TOKENIZE_QUERY</b> - A MATCH query is being executed
229869 ** against the FTS index. The tokenizer is being called to tokenize
229873 ** FTS5_TOKENIZE_QUERY, except that the bareword or quoted string is
229877 ** <li> <b>FTS5_TOKENIZE_AUX</b> - The tokenizer is being invoked to
229889 ** which the token is derived within the input.
229892 ** normally be set to 0. The exception is if the tokenizer supports
229895 ** FTS5 assumes the xToken() callback is invoked for each token in the
229901 ** input buffer is exhausted, xTokenize() should return SQLITE_OK. Finally,
229920 ** same token for inputs "first" and "1st". Say that token is in
229950 ** document such as "I won first place" is tokenized, entries are
229961 ** Whether it is parsing document or query text, any call to xToken that
229963 ** is considered to supply a synonym for the previous token. For example,
229975 ** It is an error to specify the FTS5_TOKEN_COLOCATED flag the first time
229976 ** xToken() is called. Multiple synonyms may be specified for a single token
229978 ** There is no limit to the number of synonyms that may be provided for a
229981 ** In many cases, method (1) above is the best approach. It does not add
229983 ** so it is efficient in terms of disk space and query speed. However, it
229985 ** token "first" is substituted for "1st" by the tokenizer, then the query:
230001 ** token "1st", but not "first" (assuming the tokenizer is not able to
230008 ** When using methods (2) or (3), it is important that the tokenizer only
230010 ** text (method (2)), not both. Doing so will not cause any errors, but is
230095 ** a legal notice, here is a blessing:
230154 /* Truncate very long tokens to this many bytes. Hard limit is
230155 ** (65536-1-1-4-9)==65521 bytes. The limiting factor is the 16-bit offset
230161 ** less than 32. If it is set to anything large than that, an #error
230186 ** The assert_nc() macro is similar to the assert() macro, except that it
230187 ** is used for assert() conditions that are true only if it can be
230188 ** guranteed that the database is not corrupt.
230199 ** parameters is NULL and the number of bytes to compare is zero.
230217 ** then an object of the following type is used to record the set of columns.
230218 ** Each entry in the aiCol[] array is a column that may be matched.
230220 ** This object is used by fts5_expr.c and fts5_index.c.
230255 ** the string "rowid" otherwise. This text is not quoted - if it is
230266 ** True if the %_docsize table is created.
230269 ** This is only used for debugging. If set to false, any prefix indexes
230270 ** are ignored. This value is configured using:
230294 int bLock; /* True when table is preparing statement */
230299 int iCookie; /* Incremented when %_config is modified */
230511 ** Argument p points to a buffer containing utf-8 text that is n bytes in
230546 ** Close the reader blob handle, if it is open.
230551 ** This interface is used by the fts5vocab module.
230565 ** Insert or remove data to or from the index. Each time a document is
230566 ** added to or removed from the index, this function is called one or more
230570 ** If the operation is a delete, it must be called (at least) once for each
230572 ** argument is ignored for a delete.
230587 int bDelete, /* True if current operation is a delete */
230732 ** Return true if the hash is empty, false otherwise.
230884 ** The fts5_expr.c API above this point is used by the other hand-written
231005 /* This file is automatically generated by Lemon from input grammar
231012 ** a legal notice, here is a blessing:
231024 ** interstitial "-" characters) contained in this template is changed into
231026 ** of this template is copied straight through into the generate parser
231029 ** The following is the concatenation of all %include directives from the
231056 ** into sqlite3ParserAlloc(). The default is size_t.
231082 /* The next sections is a series of control #defines.
231084 ** fts5YYCODETYPE is the data type used to store the integer codes
231086 ** "unsigned char" is used if there are fewer than
231088 ** fts5YYNOCODE is a number of type fts5YYCODETYPE that is not used for
231095 ** fts5YYACTIONTYPE is the data type used for "action codes" - numbers
231098 ** sqlite3Fts5ParserFTS5TOKENTYPE is the data type used for minor type for terminal
231099 ** symbols. Background: A "minor type" is a semantic
231107 ** fts5YYMINORTYPE is the data type used for all minor types.
231108 ** This is typically a union of many types, one of
231109 ** which is sqlite3Fts5ParserFTS5TOKENTYPE. The entry in the union
231110 ** for terminal symbols is called "fts5yy0".
231111 ** fts5YYSTACKDEPTH is the maximum depth of the parser's stack. If
231112 ** zero the stack is dynamically sized using realloc()
231119 ** fts5YYERRORSYMBOL is the code number of the error symbol. If not
231178 /* Define the fts5yytestcase() macro to be a no-op if is not already defined
231183 ** code the fts5yytestcase() macro should be turned off. But it is useful
231196 ** Suppose the action integer is N. Then the action is determined as
231199 ** 0 <= N <= fts5YY_MAX_SHIFT Shift N. That is, push the lookahead
231215 ** The action table is constructed as a single large table named fts5yy_action[].
231216 ** Given state S and lookahead X, the action is computed as either:
231221 ** The (A) formula is preferred. The B formula is used instead if
231222 ** fts5yy_lookahead[fts5yy_shift_ofst[S]+X] is not equal to X.
231224 ** The formulas above are for computing the action when the lookahead is
231225 ** a terminal symbol. If the lookahead is a non-terminal (as occurs after
231226 ** a reduce action) then the fts5yy_reduce_ofst[] array is used in place of
231300 ** and Z. Whenever one of the tokens X, Y, or Z is input to the parser
231301 ** but it does not parse, the type of the token is changed to ID and
231302 ** the parse is retried before an error is thrown.
231321 ** + The semantic value stored at this level of the stack. This is
231323 ** It is sometimes called the "minor" token.
231331 fts5YYCODETYPE major; /* The major token value. This is the code
231334 ** is the value of the token */
231338 /* The state of the parser is completely contained in an instance of
231371 ** and a prompt to preface each trace message. Tracing is turned off
231377 ** If NULL, then tracing is turned off.
231379 ** line of trace output. If NULL, then tracing is
231537 ** The only argument is a pointer to a function which works like
231544 ** A pointer to a parser. This pointer is used in subsequent calls
231561 ** or nonterminal. "fts5yymajor" is the symbol code, and "fts5yypminor" is
231563 ** deletions is derived from the %destructor and/or %token_destructor
231574 /* Here is inserted the actions which take place when a
231575 ** terminal or non-terminal is destroyed. This can happen
231576 ** when the symbol is popped from the stack during a
231577 ** reduce or during error processing or when a parser is
231578 ** being destroyed before it is finished parsing.
231622 ** If there is a destructor routine associated with the token which
231623 ** is popped from the stack, then call it.
231657 ** is defined in a %include section of the input grammar) then it is
231658 ** assumed that the input pointer is never NULL.
231683 ** coverage. The element fts5yycoverage[X][Y] is set when the parser
231684 ** is in state X and has a lookahead token Y. In a well-tested
231695 ** (2) is not a syntax error.
231815 ** The following routine is called if the stack overflows.
231826 /* Here code is inserted which will execute if the parser
231973 ** if the lookahead token has already been consumed. As this procedure is
232157 /* It is not possible for a REDUCE to be followed by an error */
232183 /* Here code is inserted which will be executed whenever the
232215 ** The following is executed when the parser accepts
232231 /* Here code is inserted which will be executed whenever the
232240 ** The first argument is a pointer to a structure obtained from
232242 ** The second argument is the major token number. The third is
232243 ** the minor token. The fourth optional argument is whatever the
232244 ** user wants (and specified in the grammar) and is available for
232318 /* Check that the stack is large enough to grow by a single entry
232319 ** if the RHS of the rule is empty. This ensures that there is room
232370 ** This is what we do if the grammar does define ERROR:
232375 ** it is legal to shift the error symbol, then shift
232421 /* If the fts5YYNOERRORRECOVERY macro is defined, then do not attempt to
232431 #else /* fts5YYERRORSYMBOL is not defined */
232432 /* This is what we do if the grammar does not define ERROR:
232436 ** * If the input token is $, then fail the parse.
232489 ** a legal notice, here is a blessing:
232507 ** common), each set of overlapping instances is treated as a single
232511 ** Usage is:
232609 int bOpen; /* True if highlight is open */
232615 ** z points to a buffer containing n bytes of text to append. If n is
232616 ** negative, everything up until the first '\0' is appended to the output.
232618 ** If *pRc is set to any value other than SQLITE_OK when this function is
232619 ** called, it is a no-op. If an error (i.e. an OOM condition) is encountered,
232620 ** *pRc is set to an error code before returning.
232659 /* If the parenthesis is open, and this token is not part of the current
232660 ** phrase, and the starting byte offset of this token is past the point
232671 /* If this is the start of a new phrase, and the highlight is not open:
232800 ** This function is an xTokenize() callback used by the auxiliary snippet()
232801 ** function. Its job is to identify tokens that are the first in a sentence.
232802 ** For each such token, an entry is added to the SFinder.aFirst[] array.
233053 ** The first time the bm25() function is called for a query, an instance
233054 ** of the following structure is allocated and populated.
233125 ** This is done using the standard BM25 formula as found on wikipedia:
233129 ** where "N" is the total number of documents in the set and nHit
233130 ** is the number that contain at least one instance of the phrase
233133 ** The problem with this is that if (N < 2*nHit), the IDF is
233134 ** negative. Which is undesirable. So the mimimum allowable IDF is
233243 ** a legal notice, here is a blessing:
233299 ** is called, it is a no-op.
233317 ** ensures that the byte following the buffer data is set to 0x00, even
233318 ** though this byte is not included in the pBuf->n count.
233331 ** Argument zFmt is a printf() style format string. This function performs
233335 ** following the buffer data is set to 0x00, even though this byte is not
233393 ** is called, it is a no-op.
233431 /* This is a corrupt record. So stop parsing it here. */
233471 ** The previous position written to this list is *piPrev. *piPrev is set
233517 ** is non-negative, then it is the length of the string in bytes. Otherwise,
233518 ** the length of the string is determined using strlen().
233520 ** It is the responsibility of the caller to eventually free the returned
233521 ** buffer using sqlite3_free(). If an OOM error occurs, NULL is returned.
233600 /* Calculate a hash value for this term. This is the same hash checksum
233601 ** used by the fts5_hash.c module. This is not important for correct
233602 ** operation of the module, but is necessary to ensure that some tests
233655 ** a legal notice, here is a blessing:
233663 ** This is an SQLite module implementing full-text search.
233689 ** Argument pIn points to a character that is part of a nul-terminated
233691 ** the string that is not a white-space character.
233702 ** Argument pIn points to a character that is part of a nul-terminated
233704 ** the string that is not a "bareword" character.
233767 /* At this point, if the literal was an integer, the parse is
233768 ** finished. Or, if it is a floating point value, it may continue
233783 ** The first character of the string pointed to by argument z is guaranteed
233790 ** If the close-quote is found, the value returned is the byte offset of
233791 ** the character immediately following it. Or, if the close-quote is not
233792 ** found, -1 is returned. If -1 is returned, the buffer is left in an
233829 ** the quote characters. The conversion is done in-place. If the
233831 ** is a no-op.
233881 ** If successful, object pConfig is updated and SQLITE_OK returned. If
233882 ** an error occurs, an SQLite error code is returned and an error message
233883 ** may be left in *pzErr. It is the responsibility of the caller to
234083 ** quoted, *pbQuoted is also set to 1 before returning.
234085 ** If *pRc is other than SQLITE_OK when this function is called, it is
234086 ** a no-op (NULL is returned). Otherwise, if an OOM occurs within this
234087 ** function, *pRc is set to SQLITE_NOMEM before returning. *pRc is *not*
234185 ** If successful, SQLITE_OK is returned and *ppOut is set to point to the
234186 ** new Fts5Config object. If an error occurs, an SQLite error code is
234187 ** returned, *ppOut is set to NULL and an error message may be left in
234188 ** *pzErr. It is the responsibility of the caller to eventually free any
234271 /* We only allow contentless_delete=1 if the table is indeed contentless. */
234282 /* We only allow contentless_delete=1 if columnsize=0 is not present.
234288 "contentless_delete=1 is incompatible with columnsize=0"
234391 ** The callback is invoked once for each token in the input text. The
234399 ** int iPos // Position of token in input (first token is 0)
234401 ** If the callback returns a non-zero value the tokenization is abandoned
234406 ** the callback returned SQLITE_DONE, this is not an error and this function
234408 ** because the callback returned another non-zero value, it is assumed
234425 ** Argument pIn points to the first character in what is expected to be
234427 ** If it actually is this, return a pointer to the ')'. Otherwise, return
234450 ** this is:
234696 ** a legal notice, here is a blessing:
234757 ** Distance from this node to furthest leaf. This is always 0 for nodes
234758 ** of type FTS5_STRING and FTS5_TERM. For all other nodes it is one
234764 int bNomatch; /* True if entry is not a match */
234806 Fts5ExprNode *pNode; /* FTS5_STRING node this phrase is part of */
235023 ** Assuming that buffer z is at least nByte bytes in size and contains a
235036 ** This function is only called when using the special 'trigram' tokenizer.
235040 ** GLOB. If successful, SQLITE_OK is returned. Otherwise, an SQLite error
235275 ** pointing to the same rowid when this function is called. This function
235276 ** checks if the current rowid really is a match, and if so populates
235278 ** is set to true if this is really a match, or false otherwise.
235280 ** SQLITE_OK is returned if an error occurs, or an SQLite error code
235281 ** otherwise. It is not considered an error code if the current rowid is
235298 /* If the aStatic[] array is not large enough, allocate a large array
235410 ** close together to meet the NEAR constraint. Non-zero is returned if it
235413 ** If in/out parameter (*pRc) is set to other than SQLITE_OK when this
235414 ** function is called, it is a no-op. Or, if an error (e.g. SQLITE_NOMEM)
235415 ** occurs within this function (*pRc) is set accordingly before returning.
235416 ** The return value is undefined in both these cases.
235418 ** If no error occurs and non-zero (a match) is returned, the position-list
235419 ** of each phrase object is edited to contain only those entries that
235433 /* If the aStatic[] array is not large enough, allocate a large array
235450 ** of the NEAR constraint) is written over the original even as it is
235451 ** being read. This is safe as the entries for the new poslist are a
235452 ** subset of the old, so it is not possible for data yet to be read to
235523 int bDesc, /* True if iterator is "rowid DESC" */
235549 int bDesc, /* True if iterator is "rowid DESC" */
235579 Fts5Expr *pExpr, /* Expression that pNear is a part of */
235603 ** phrase is not a match, break out of the loop early. */
235628 ** Initialize all term iterators in the pNear object. If any term is found
235633 ** SQLITE_OK. It is not considered an error if some term matches zero
235689 ** If pExpr is an ASC iterator, this function returns a value with the
235694 ** Otherwise, if this is a DESC iterator, the opposite is returned:
235748 ** This means that if the iteration order is ASC, then numerically larger
235749 ** rowids are considered larger. Or if it is the default DESC, numerically
235764 ** this function is called. This function checks if all term iterators
235766 ** If an EOF is reached before this happens, *pbEof is set to true before
235769 ** SQLITE_OK is returned if an error occurs, or an SQLite error code
235770 ** otherwise. It is not considered an error code if an iterator reaches
235794 ** the maximum rowid. Or, if the iterator is "ORDER BY rowid DESC", then it
235861 ** is valid - each iterator that points to a rowid before iFrom. */
235909 Fts5Expr *pExpr, /* Expression that pNear is a part of */
235912 /* As this "NEAR" object is actually a single phrase that consists
235914 ** fts5_index.c iterator object. This is much faster than synthesizing
235961 Fts5Expr *pExpr, /* Expression of which pNode is a part */
236009 ** Argument pNode is an FTS5_AND node.
236036 /* If the child node is now at EOF, so is the parent AND node. Otherwise,
236037 ** the child node is guaranteed to have advanced at least as far as
236038 ** rowid iLast. So if it is not at exactly iLast, pChild->iRowid is the
236124 ** without modifying it. Otherwise, pNode is advanced until it does point
236125 ** to a match or EOF is reached.
236128 Fts5Expr *pExpr, /* Expression of which pNode is a part */
236166 ** Set node pNode, which is part of expression pExpr, to point to the first
236170 ** It is not an error if there are no matches.
236219 ** parameter is passed a non-zero value, iteration is in descending rowid
236220 ** order. Or, if it is zero, in ascending order.
236223 ** visited is that with the smallest rowid that is larger than or equal
236229 ** is not considered an error if the query does not match any documents.
236248 /* If the iterator is not at a real match, skip forward until it is. */
236260 ** is not considered an error if the query does not match any documents.
236325 ** If argument pNear is NULL, then a new Fts5ExprNearset object is allocated
236326 ** and populated with pPhrase. Or, if pNear is not NULL, phrase pPhrase is
236420 /* If an error has already occurred, this is a no-op */
236516 ** This function is called by the parser to process a string token. The
236517 ** string may or may not be quoted. In any case it is tokenized and a
236524 int bPrefix /* True if there is a trailing "*" */
236672 ** is expected. If token pTok does not contain "NEAR", store an error
236716 ** The old colset object (if any) is not freed in this case.
236746 /* Check that the array is in order and contains no duplicate entries. */
236815 ** If argument pOrig is NULL, or if (*pRc) is set to anything other than
236816 ** SQLITE_OK when this function is called, NULL is returned.
236818 ** Otherwise, a copy of (*pOrig) is made into memory obtained from
236820 ** fails, (*pRc) is set to SQLITE_NOMEM and NULL is returned.
236861 ** its decendents. If (*ppFree) is not NULL, it contains a spare copy
236968 ** This function is used when parsing LIKE or GLOB patterns against
237105 "fts5 expression tree is too large (maximum depth %d)",
237240 ** pointer to a buffer containing that representation. It is the
237520 ** single integer as an argument. If the integer is an alpha-numeric
237521 ** unicode code point, 1 is returned. Otherwise 0.
237564 ** This is called during initialization to register the fts5_expr() scalar
237617 ** This function is used to access the current position list for phrase
237642 ** passed as the first argument. Argument bLive is true if the expression
237645 ** At present this function is only used for detail=col and detail=none
237690 ** pToken is a buffer nToken bytes in size that may or may not contain
237836 ** This function is only called for detail=columns tables.
237954 ** a legal notice, here is a blessing:
237972 ** to accumuluate "term -> doclist" content before it is flused to a level-0
237987 ** Each entry in the hash table is represented by an object of the
237993 ** The key is Fts5HashEntry.nKey bytes in size. It consists of a single
237995 ** followed by the term data. For example: "0token". There is no
237998 ** The data that follows the key is in a similar, but not identical format
237999 ** to the doclist data stored in the database. It is:
238187 ** Add an entry to the in-memory hash table. The key is the concatenation
238188 ** of bByte and (pToken/nToken). The value is (iRowid/iCol/iPos).
238192 ** Or, if iCol is negative, then the value is a delete marker.
238264 /* Appending to an existing hash-entry. Check that there is enough
238266 ** is:
238291 /* If this is a new rowid, append the 4-byte size field for the previous
238332 /* This is a delete. Set the delete flag. */
238375 /* p2 is smaller */
238380 /* p1 is smaller */
238501 ** Return true if the hash table is empty, false otherwise.
238545 ** a legal notice, here is a blessing:
238567 ** The format is similar to FTS3/4, except that:
238569 ** * all segment b-tree leaf data is stored in fixed size page records
238570 ** (e.g. 1000 bytes). A single doclist may span multiple pages. Care is
238571 ** taken to ensure it is possible to iterate in either direction through
238577 ** the doclist. This is used to speed up seek operations, and merges of
238594 # error "FTS5_MAX_PREFIX_INDEXES is too large"
238604 ** 2. the V2 format, which is used by contentless_delete=1 databases.
238609 ** 4 bytes [0xff 0x00 0x00 0x01]. This is unambiguous as the value of a
238611 ** maximum number of levels is 64.
238635 ** If the structure record is a V2 record, the configuration cookie is
238661 ** A single record within the %_data table. The data is a list of varints.
238662 ** The first value is the number of rows in the index. Then, for each column
238670 ** Most of each segment leaf is taken up by term/doclist data. The
238672 ** on the leaf page, is:
238720 ** footer is 0 bytes in size, then this field is the same as the
238724 ** on the page. Each varint is the byte offset of the current term
238726 ** other words, the first varint in the footer is the byte offset of
238727 ** the first term, the second is the byte offset of the second less that
238730 ** The term/doclist format described above is accurate if the entire
238731 ** term/doclist data fits on a single leaf page. If this is not the case,
238732 ** the format is changed in two ways:
238735 ** is stored as a literal value:
238739 ** + the first term on each page is stored in the same way as the
238749 ** is:
238752 ** 0x01: Clear if leaf is also the root page, otherwise set.
238794 ** 1-byte: rowid-0-tombstone flag. This flag is only valid on the
238797 ** Rowid 0 is handled specially.
238821 ** The rowid for each segment leaf is found by passing the segment id and
238847 ** Each time a blob is read from the %_data table, it is padded with this
238881 ** call to fts5IndexFlush() or fts5IndexDiscardData(). This is tracked
238897 int bDelete; /* Current write is a delete */
238938 ** This value is set to non-zero for structure records created for
238957 Fts5StructureSegment *aSeg; /* Array of segments. aSeg[0] is oldest. */
238969 ** An object of type Fts5SegWriter is used to write to segments.
238980 int bPrevValid; /* True if iPrev is valid */
238988 u8 bFirstRowidInDoclist; /* True if next rowid is first in doclist */
238989 u8 bFirstRowidInPage; /* True if next rowid is first in page */
239020 ** Byte offset within the current leaf that is the first byte of the
239038 ** This flag is only ever set if FTS5_SEGITER_ONETERM is also set. If
239039 ** it is set, iterate through rowid in descending order instead of the
239043 ** These are used if the FTS5_SEGITER_REVERSE flag is set.
239046 ** corresponding aRowidOffset[] entry is set to the byte offset of the
239054 ** is first allocated, the apTombstone[] array is allocated so that it
239055 ** is large enough for all tombstones hash pages associated with the
239072 ** is the offset of the first rowid in the current doclist. */
239079 /* The following are only used if the FTS5_SEGITER_REVERSE flag is set. */
239084 Fts5DlidxIter *pDlidx; /* If there is a doclist-index */
239090 u8 bDel; /* True if the delete flag is set */
239103 ** Argument is a pointer to an Fts5Data structure that contains a
239114 ** Argument is a pointer to an Fts5Data structure that contains a leaf
239128 ** nSeg is always a power of two greater than or equal to the number of
239129 ** segments that this object is merging data from. Both the aSeg[] and
239130 ** aFirst[] arrays are sized at nSeg entries. The aSeg[] array is padded
239134 ** The results of comparing segments aSeg[N] and aSeg[N+1], where N is an
239135 ** even number, is stored in aFirst[(nSeg+N)/2]. The "result" of the
239136 ** comparison in this context is the index of the iterator that currently
239141 ** the smallest key overall. aFirst[0] is unused.
239145 ** There is no way to tell if this is populated or not.
239150 ** The Fts5Iter does not own the Fts5Colset object, and so it is not
239151 ** freed when the iterator is closed - it is owned by the upper layer.
239174 ** An instance of the following type is used to iterate through the contents
239268 ** If an OOM error is encountered, return NULL and set the error code in
239278 ** Return -ve if pLeft is smaller than pRight, 0 if they are equal or
239279 ** +ve if pRight is smaller than pLeft. In other words:
239296 ** is a prefix of the other, it is considered the lesser.
239298 ** Return -ve if pLeft is smaller than pRight, 0 if they are equal or
239299 ** +ve if pRight is smaller than pLeft. In other words:
239319 ** Close the read-only blob handle, if it is open.
239332 ** If an error occurs, NULL is returned and an error left in the
239343 ** is required. */
239355 /* If the blob handle is not open at this point, open it and seek
239553 ** Ensure that structure object (*pp) is writable.
239555 ** This function is a no-op if (*pRc) is not SQLITE_OK when it is called. If
239556 ** an error occurs, (*pRc) is set to an SQLite error code before returning.
239596 ** If an error occurs, *ppOut is set to NULL and an SQLite error code
239597 ** returned. Otherwise, *ppOut is set to point to the new object and
239620 /* Check if this is a V2 structure record. Set bStructureV2 if it is. */
239735 ** Extend level iLvl so that there is room for at least nExtra more
239775 /* TODO: Do we need this if the leaf-index is appended? Probably... */
239818 ** If an error occurs, NULL is returned and an error code left in the
239820 ** is called, it is a no-op.
239870 ** function is only ever used as part of assert() conditions.
239902 ** error has already occurred, this function is a no-op.
239977 ** segments as possible to level iPromote. If an OOM occurs, NULL is
239986 int il, is;
239993 for(is=pLvl->nSeg-1; is>=0; is--){
239994 int sz = fts5SegmentSize(&pLvl->aSeg[is]);
239998 memcpy(pOut->aSeg, &pLvl->aSeg[is], sizeof(Fts5StructureSegment));
240011 ** a) If the segment just written is smaller than one or more segments
240012 ** within the previous populated level, it is promoted to the previous
240015 ** b) If the segment just written is larger than the newest segment on
240020 ** If one or more segments are promoted, the structure object is updated
240052 /* Condition (a) is true. Promote the newest segment on level
240059 /* If condition (a) is not met, assume (b) is true. StructurePromoteTo()
240060 ** is a no-op if it is not. */
240072 ** doclist-index page is reached, return non-zero.
240138 ** When this function is called pIter->iLeafPgno is the page number the
240139 ** doclist is associated with (the one featuring the term).
240342 ** list, and *pbDel to true if the delete flag is set, or false otherwise.
240415 ** of the "nPrefix" field (if there was one - it is passed 0 if this is
240491 ** segment pSeg. The iterator is left pointing to the first entry when
240494 ** If an error occurs, Fts5Index.rc is set to an appropriate error code. If
240495 ** an error has already occurred when this function is called, it is a no-op.
240503 /* This happens if the segment is being used as an input to an incremental
240506 ** The caller will see the (pIter->pLeaf==0) and assume the iterator is
240535 ** This function is only ever called on iterators created by calls to
240538 ** The iterator is in an unusual state when this function is called: the
240539 ** Fts5SegIter.iLeafOffset variable is set to the offset of the start of
240541 ** Fts5SegIter.rowid is set, but nPos and bDel are not.
240546 ** is in its regular state - Fts5SegIter.iLeafOffset points to the first
240615 /* iTermLeafOffset may be equal to szLeaf if the term is the last
240616 ** thing on the page - i.e. the first rowid is on the following page.
240617 ** In this case leave pIter->pLeaf==0, this iterator is at EOF. */
240655 ** points to a delete marker. A delete marker is an entry with a 0 byte
240666 ** This version of fts5SegIterNext() is only used by reverse iterators.
240699 ** This version of fts5SegIterNext() is only used if detail=none and the
240700 ** iterator is not a reverse direction iterator.
240716 /* Next entry is on the next page */
240725 /* Next entry is on the current page */
240771 ** If an error occurs, Fts5Index.rc is set to an appropriate error code. It
240772 ** is not considered an error if the iterator reaches EOF. If an error has
240773 ** already occurred when this function is called, it is a no-op.
240798 /* The next entry is on the current page. */
240837 /* Next entry is not on the current page */
240869 /* Check if the iterator is now at EOF. If so, return early. */
240882 ** this block is particularly performance critical, so equivalent
240883 ** code is inlined. */
240930 /* If this condition is true then the largest rowid for the current
240932 ** see where said rowid really is. */
240957 /* If pLast is NULL at this point, then the last rowid for this doclist
240959 ** pIter->iLeafOffset is already set to point to the position-list size
240962 ** Or, if pLast is non-NULL, then it is the page that contains the last
240991 ** There is a doclist-index associated with the final term on the current
240992 ** page. If the current term is the last term on the page, load the
241020 ** If the specified term is found on the page, then the iterator is left
241021 ** pointing to it. If argument bGe is zero and the term is not found,
241022 ** the iterator is left pointing at EOF.
241024 ** If bGe is non-zero and the specified term is not found, then the
241025 ** iterator is left pointing to the smallest term in the segment that
241026 ** is larger than the specified term, even if this term is not on the
241169 ** pSeg. If there is no such term in the index, the iterator is set to EOF.
241171 ** If an error occurs, Fts5Index.rc is set to an appropriate error code. If
241172 ** an error has already occurred when this function is called, it is a no-op.
241183 int bDlidx = 0; /* True if there is a doclist-index */
241192 ** contain term (pTerm/nTerm), if it is present in the segment. */
241270 ** This is similar to fts5SegIterSeekInit(), except that it initializes
241327 ** in-memory hash table. If there is no such term in the hash-table, the
241328 ** iterator is set to EOF.
241330 ** If an error occurs, Fts5Index.rc is set to an appropriate error code. If
241331 ** an error has already occurred when this function is called, it is a no-op.
241362 ** can be appended to is if the previous operation on this table was
241443 ** This function is used as part of the big assert() procedure implemented by
241445 ** in *pRes is the correct result of comparing the current positions of the
241485 ** This function is a no-op unless SQLITE_DEBUG is defined when this module
241486 ** is compiled. In that case, this function is essentially an assert()
241497 /* Check that pIter->iSwitchRowid is set correctly. */
241530 ** If the returned value is non-zero, then it is the index of an entry
241531 ** in the pIter->aSeg[] array that is (a) not at EOF, and (b) pointing
241532 ** to a key that is a duplicate of another, higher priority,
241557 if( p1->pLeaf==0 ){ /* If p1 is at EOF */
241559 }else if( p2->pLeaf==0 ){ /* If p2 is at EOF */
241586 ** It is an error if leaf iLeafPgno does not exist. Unless the db is
241587 ** a 'secure-delete' db, if it contains no rowids then this is also an error.
241625 ** Advance the iterator passed as the second argument until it is at or
241626 ** past rowid iFrom. Regardless of the value of iFrom, the iterator is
241715 ** If it does so successfully, 0 is returned. Otherwise 1.
241717 ** If non-zero is returned, the caller should call fts5MultiIterAdvanced()
241781 ** it is found or false otherwise. The tombstone hash table is one of
241817 ** to an segment entry for which there is a tombstone. Return false
241818 ** if there is no tombstone or if the iterator is already at EOF.
241852 ** If an error occurs, an error code is left in Fts5Index.rc. It is not
241853 ** considered an error if the iterator reaches EOF, or if it is already at
241854 ** EOF when this function is called.
241859 int bFrom, /* True if argument iFrom is valid */
242022 /* Search through to find the first varint with value 1. This is the
242152 ** If memory is required for the new position list, use buffer pIter->poslist.
242153 ** Or, if the new position list is a contiguous subset of the input, set
242156 ** This function is a no-op if *pRc is other than SQLITE_OK when it is
242157 ** called. If an OOM error is encountered, *pRc is set to SQLITE_NOMEM
242187 /* Advance pointer p until it points to pEnd or an 0x01 byte that is
242238 /* All data is stored on the current page. Populate the output
242242 /* The data is distributed over two or more pages. Copy it into the
242261 ** xSetOutputs callback used by detail=col when there is a column filter
242277 ** * there is a column filter, and
242280 ** The last point is to ensure all column numbers are stored as
242321 ** xSetOutputs callback used by detail=full when there is a column filter.
242331 /* All data is stored on the current page. Populate the output
242338 /* The data is distributed over two or more pages. Copy it into the
242411 ** If iLevel is -ve, then all data in all segments is merged. Or, if iLevel
242412 ** is zero or greater, data from the first nSegment segments on level iLevel
242413 ** is merged.
242543 ** Return true if the iterator is at EOF or if an error has occurred.
242556 ** to. If the iterator points to EOF when this function is called the
242596 ** SQLITE_FULL is returned.
242598 ** If an error has already occurred, this function is a no-op. 0 is
242608 /* FTS5_MAX_SEGMENT is currently defined as 2000. So the following
242609 ** array is 63 elements, or 252 bytes, in size. */
242673 ** Buffer (pNew/<length-unknown>) is guaranteed to be greater
242732 ** If the current doclist-index accumulating in pWriter->aDlidx[] is large
242750 ** This function is called whenever processing of the doclist for the
242751 ** last term on leaf page (pWriter->iBtPage) is completed.
242753 ** The doclist-index for that term is currently stored in-memory within the
242754 ** Fts5SegWriter.aDlidx[] array. If it is large enough, this function
242755 ** writes it out to disk. Or, if it is too small to bother with, discards
242781 ** This is called once for each leaf page except the first that contains
242782 ** at least one term. Argument (nTerm/pTerm) is the split-key - a term that
242783 ** is larger than all terms written to earlier leaves, and equal to or
242786 ** If an error occurs, an error code is left in Fts5Index.rc. If an error
242787 ** has already occurred when this function is called, it is a no-op.
242802 ** This function is called when flushing a leaf page that contains no
242831 ** Rowid iRowid has just been appended to the current leaf page. It is the
242848 /* The current doclist-index page is full. Write it to disk and push
242851 ** hierarchy. If the node being flushed is currently the root node,
242939 ** already occurred, this function is a no-op.
242955 /* If the current leaf page is full, flush it to disk. */
242977 /* This is the first term on a leaf that is not the leftmost leaf in
242978 ** the segment b-tree. In this case it is necessary to add a term to
242979 ** the b-tree hierarchy that is (a) larger than the largest term
242981 ** this term. In other words, a prefix of (pTerm/nTerm) that is one
242985 ** Usually, the previous term is available in pPage->term. The exception
242986 ** is if this is the first term written in an incremental-merge step.
242987 ** In this case the previous term is not available, so just write a
242988 ** copy of (pTerm/nTerm) into the parent node. This is slightly
243034 /* If this is to be the first rowid written to the page, set the
243036 ** buffer, in case a doclist-index is required. */
243154 /* Bind the current output segment id to the index-writer. This is an
243163 ** incremental merge operation. This function is called if the incremental
243177 ** segment is now empty. */
243259 int bOldest; /* True if the output segment is the oldest */
243335 /* This is a new term. Append a term to the output segment. */
243399 ** If this is not a contentless_delete=1 table, or if the 'deletemerge'
243400 ** configuration option is set to 0, then this function always returns -1.
243403 ** tombstones in the tombstone hash. If one is found, its index is returned.
243404 ** Otherwise, if there is no suitable level, -1.
243455 ** there is no level suitable to merge segments from. */
243494 ** already occurred, this function is a no-op.
243571 ** This is used when a secure-delete operation removes the last term
243572 ** from a segment leaf page. In that case the %_idx entry is removed
243573 ** too. This is done to ensure that if all instances of a token are
243600 ** This is called when a secure-delete operation removes a position-list
243605 ** Output variable (*pbLastInDoclist) is set to true if the position-list
243606 ** removed is followed by a new term or the end-of-segment, or false if
243607 ** it is followed by another rowid/position list.
243658 /* Unless the current page footer is 0 bytes in size (in which case
243683 ** in bytes. The new page is always smaller than the old. */
243735 ** In detail=full or detail=column mode, pSeg->iLeafOffset is the
243743 ** Or, in detail=none mode, there is a single varint prior to
243815 ** entry following the one we are removing) is equal to the
243816 ** offset of a key on this page, then the entry is the last
243829 /* If this is (a) the first rowid on a page and (b) is not followed by
243856 ** last offset in the footer that is not greater than iStart. */
243870 /* This is the only position-list associated with the term, and there
243871 ** is another term following it on this page. So the subsequent term
243995 ** This is called as part of flushing a delete to disk in 'secure-delete'
244034 ** already occurred, this function is a no-op.
244104 /* If in secure delete mode, and if this entry in the poslist is
244211 /* Update the Fts5Structure. It is written back to the database by the
244245 /* Unless it is empty, flush the hash table to disk */
244314 ** the new Fts5Level object so that pLvl->aSeg[0] is the oldest
244365 ** This is called to implement the special "VALUES('merge', $nMerge)"
244507 ** This is the equivalent of fts5MergePrefixLists() for detail=none mode.
244627 /* The maximum size of the output is equal to the sum of the
244628 ** input sizes + 1 varint (9 bytes). The extra varint is because if the
244629 ** first rowid in one input is a large negative number, and the first in
244782 /* If iIdx is non-zero, then it is the number of a prefix-index for
244785 ** corresponding to the prefix itself. That one is extracted from the
244932 ** The %_data table is completely empty when this function is called. This
244950 ** Open a new Fts5Index handle. If the bCreate argument is true, create
245018 ** Argument p points to a buffer containing utf-8 text that is n bytes in
245046 ** pIn is a UTF-8 encoded string, nIn bytes in size. Return the number of
245062 ** Insert or remove data to or from the index. Each time a document is
245063 ** added to or removed from the index, this function is called one or more
245067 ** If the operation is a delete, it must be called (at least) once for each
245069 ** argument is ignored for a delete.
245136 ** associated with position iPos of rowid iRowid. This is used by the
245140 i64 iRowid; /* Row this token is located in */
245314 /* Ensure the output buffer is large enough */
245319 /* Ensure the token-mapping is large enough */
245373 ** argument bFrom is false, then the iterator is advanced to the next
245374 ** entry. Or, if bFrom is true, it is advanced to the first entry with
245400 ** If the segment-iterator passed as the first argument is at EOF, then
245507 /* If pSmall is still NULL at this point, then the new iterator does
245566 /* If the QUERY_SCAN flag is set, all other flags must be clear. */
245580 ** is a prefix query for which there is no prefix index, set iIdx to
245586 ** evaluate the prefix query using the main FTS index. This is used
245646 ** Return true if the iterator passed as the only argument is at EOF.
245711 ** This is used by xInstToken() to access the token at offset iOff, column
245712 ** iCol of row iRowid. The token is returned via output variables *ppOut
245775 ** is used in detail=column or detail=none mode when a token is requested
245819 ** Parameter anSize must point to an array of size nCol, where nCol is
245896 ** being accumulated in the in-memory hash table when it is flushed to
245897 ** disk. If successful, SQLITE_OK is returned and (*piOrigin) set to
245898 ** the queried value. Or, if an error occurs, an error code is returned
245899 ** and the final value of (*piOrigin) is undefined.
245914 ** the hash table. The caller is required to guarantee that there is at
245917 ** If parameter bForce is false and the hash table is deemed to be full
245918 ** (more than half of the slots are occupied), then non-zero is returned
245919 ** and iRowid not inserted. Or, if bForce is true or if the hash table page
245920 ** is not full, iRowid is inserted and zero returned.
245970 ** Return 0 if the hash is successfully rebuilt into the nOut pages.
245971 ** Or non-zero if it is not (because one page became overfull). In this
245974 ** Parameter pData1 is page iPg1 of the hash table being rebuilt.
245980 int iPg1, /* Which page of the current hash is pData1 */
246021 /* If iVal is not 0 at this point, insert it into the new hash table */
246029 /* If this is page 0 of the old hash, copy the rowid-0-flag from the
246042 ** This is called to rebuild the hash table belonging to segment pSeg.
246043 ** If parameter pData1 is not NULL, then one page of the existing hash table
246044 ** has already been loaded - pData1, which is page iPg1. The key-size for
246045 ** the new hash table is szKey (4 or 8).
246047 ** If successful, the new hash table is not written to disk. Instead,
246048 ** output parameter (*pnOut) is set to the number of pages in the new
246052 ** If an error occurs, an error code is left in the Fts5Index object and
246059 int iPg1, /* Which page of the current hash is pData1 */
246075 ** 2. The hash table exists but is currently a single page. In this
246076 ** case an attempt is made to grow the page to accommodate the new
246077 ** entry. The page is allowed to grow up to nSlotPerPage (see above)
246083 ** slots each, where nPg is the current number of pages in the
246238 ** Below this point is the implementation of the integrity-check
246264 ** This function is purely an internal test. It does not contribute to
246269 ** iSegid/iLeaf is iterated in forwards or reverse order.
246381 ** This function is also purely an internal test. It does not contribute to
246413 /* If this is a prefix query, check that the results returned if the
246414 ** the index is disabled are the same. In both ASC and DESC order.
246416 ** This check may only be performed if the hash table is empty. This
246417 ** is because the hash table only supports a single scan query at
246418 ** a time, and the multi-iter loop from which this function is called
246419 ** is already performing such a scan.
246572 /* Check that the leaf contains at least one term, and that it is equal
246574 ** is also a rowid pointer within the leaf page header, it points to a
246619 /* If there is a doclist-index, check that it looks right. */
246669 /* TODO: Check there is no doclist index */
246688 ** Run internal checks to ensure that the FTS index (a) is internally
246690 ** as calculated by sqlite3Fts5IndexEntryCksum() is cksum.
246706 /* Used by extra internal tests only run if NDEBUG is not defined */
246727 /* The cksum argument passed to this function is a checksum calculated
246730 ** actual contents of FTS index is identical.
246737 ** same term is performed. cksum3 is calculated based on the entries
246750 /* If this is a new term, query for it. Update cksum3 with the results. */
246784 ** Below this point is the implementation of the fts5_decode() scalar
246790 ** Decode a segment-data rowid from the %_data table. This function is
246871 ** This is part of the fts5_decode() debugging aid.
246898 ** This is part of the fts5_decode() debugging aid.
246923 ** Buffer (a/n) is assumed to contain a list of serialized varints. Read
246925 ** after either the input buffer is exhausted or a 0 value is read.
246927 ** The return value is the number of bytes read from the input buffer.
246944 ** representation of the part of the doclist that is present to buffer
246947 ** The return value is the number of bytes read from the input buffer.
246977 ** This function is part of the fts5_decode() debugging function. It is
246984 ** If *pRc is other than SQLITE_OK when this function is called, it is a
246985 ** no-op. If an OOM or other error occurs within this function, *pRc is
246987 ** pBuf is undefined in this case.
247061 ** copy is followed by FTS5_DATA_ZERO_PADDING 0x00 bytes, which prevents
247062 ** buffer overreads even if the record is corrupt. */
247351 ** into the xFilter method. If there is no valid stmt=? constraint,
247377 ** This method is the destructor for bytecodevtab objects.
247450 ** is currently pointing.
247536 ** This is called as part of registering the FTS5 module with database
247540 ** If successful, SQLITE_OK is returned. If an error occurs, some other
247541 ** SQLite error code is returned instead.
247612 ** a legal notice, here is a blessing:
247620 ** This is an SQLite module implementing full-text search.
247627 ** This variable is set to false when running tests for which the on disk
247628 ** structures should not be corrupt. Otherwise, true. If it is false, extra
247630 ** only true if it is guaranteed that the fts5 database is not corrupt.
247655 ** Anything that is required as part of a commit that may fail is performed
247666 ** in-memory. It is flushed to disk whenever xSync(), xRelease() or
247667 ** xSavepoint() is called. And discarded whenever xRollback() or xRollbackTo()
247668 ** is called.
247670 ** Additionally, if SQLITE_DEBUG is defined, an instance of the following
247671 ** structure is used to record the current transaction state. This information
247672 ** is not required, but it is used in the assert() statements executed by
247681 ** A single object of this type is allocated when the FTS5 module is
247682 ** registered with a database handle. It is used to store pointers to
247696 ** Each auxiliary function registered with the FTS5 module is represented
247710 ** Each tokenizer module registered with the FTS5 module is represented
247744 ** There is one entry in the aIdx[] array for each phrase in the query,
247745 ** the value of which is the offset within aPoslist[] following the last
247761 ** If this is a 'special' query (refer to function fts5SpecialMatch()),
247766 ** cursor iterates in ascending order of rowids, iFirstRowid is the lower
247773 ** is the upper limit (i.e. the "first" rowid visited) and iLastRowid
247916 ** Return true if pTab is a contentless table.
247955 ** This function is the implementation of both the xConnect and xCreate
248036 ** work is done in function fts5InitVtab().
248071 ** extension is currently being used by a version of SQLite too old to
248072 ** support index-info flags. In that case this function is a no-op.
248118 ** Information for the xFilter call is passed via both the idxNum and
248119 ** idxStr variables. Specifically, idxNum is a bitmask of the following
248126 ** idxStr is used to encode data from the WHERE clause. For each argument
248127 ** passed to the xFilter method, the following is appended to idxStr:
248138 ** This function ensures that there is at most one "r" or "=". And that if
248139 ** there exists an "=" then there is no "<" or ">".
248143 ** a) If an unusable MATCH operator is present in the WHERE clause, the
248144 ** cost is unconditionally set to 1e50 (a really big number).
248146 ** a) If a MATCH operator is present, the cost depends on the other
248154 ** b) Otherwise, if there is no MATCH:
248207 /* As there exists an unusable MATCH constraint this is an
248346 ** This function is called after the cursor passed as the only argument
248347 ** is moved to point at a different row. It clears all cached data
248474 ** If the REQUIRE_RESEEK flag is set on the cursor passed as the first
248476 ** is using. Then attempt to move the cursor to a rowid equal to or laster
248479 ** If the new rowid is not equal to the old, set output parameter *pbSkip
248513 ** Return SQLITE_OK if nothing goes wrong. SQLITE_OK is returned
248526 /* If this cursor uses FTS5_PLAN_MATCH and this is a tokendata=1 table,
248631 ** is not possible as SQLite reference counts the virtual table objects.
248673 ** Process a "special" query. A special query is identified as one with a
248710 ** pTab. If one is found, return a pointer to the corresponding Fts5Auxiliary
248824 ** This is the xFilter interface for the virtual table. See
248897 ** indicates that the MATCH expression is not a full text query,
248947 ** actually use them. This is ok, as the xBestIndex() method leaves the
248965 /* If pSortCsr is non-NULL, then this call is being made as part of
248966 ** processing for a "... MATCH <expr> ORDER BY rank" query (ePlan is
248967 ** set to FTS5_PLAN_SORTED_MATCH). pSortCsr is the cursor that will
248969 ** (pCursor) is used to execute the query issued by function
249003 /* This is either a full-table scan (ePlan==FTS5_PLAN_SCAN) or a lookup
249028 ** This is the xEof method of the virtual table. SQLite calls this
249052 ** This is the xRowid method. The SQLite core calls this routine to
249082 ** If the cursor requires seeking (bSeekRequired flag is set), seek it.
249085 ** If argument bErrormsg is true and an error occurs, an error message may
249136 ** This function is called to handle an FTS INSERT command. In other words,
249142 ** Argument pVal is the value assigned to column "fts" by the INSERT
249250 ** This function is the implementation of the xUpdate callback used by
249251 ** FTS3 virtual tables. It is invoked by SQLite each time a row is to be
249275 /* A transaction must be open when this is called. */
249315 /* A regular INSERT, UPDATE or DELETE statement. The trick here is that
249335 ** This is not suported. Except - they are both supported if the CREATE
249364 /* An INSERT statement. If the conflict-mode is REPLACE, first remove
249443 ** Implementation of xCommit() method. This is a no-op. The contents of
249448 UNUSED_PARAM(pVtab); /* Call below is a no-op for NDEBUG builds */
250134 ** A position-list blob begins with (nPhrase-1) varints, where nPhrase is
250140 ** list 1. And so on. There is no size field for the final position list,
250197 ** This is the xColumn method, called by SQLite to request a value from
250219 /* User is requesting the value of the special column with the same name
250220 ** as the table. Return the cursor integer id number. This value is only
250319 ** This is a no-op.
250390 ** Register a new tokenizer. This is the implementation of the
250446 ** Find a tokenizer. This is the implementation of the
250554 ** Return true if zName is the extension on one of the shadow tables used
250570 ** if anything is found amiss. Return a NULL pointer if everything is
250577 int isQuick, /* True if this is a quick-check */
250662 /* If SQLITE_FTS5_ENABLE_TEST_MI is defined, assume that the file
250663 ** fts5_test_mi.c is compiled and linked into the executable. And call
250677 ** this module is being built as part of the SQLite core (SQLITE_CORE is
250680 ** Or, if this module is being built as a loadable extension,
250681 ** sqlite3Fts5Init() is omitted and the two standard entry points
250720 ** a legal notice, here is a blessing:
250777 /* If there is no %_docsize table, there should be no requests for
251000 ** Open a new Fts5Index handle. If the bCreate argument is true, create
251118 ** If a row with rowid iDel is present in the %_content table, add the
251182 ** This function is called to process a DELETE on a contentless_delete=1
251184 ** iDel. If successful, SQLITE_OK is returned. Or, if an error occurs,
251218 ** If there is no %_docsize table (as happens if the columnsize=0 option
251219 ** is specified when the FTS5 table is created), this function is a no-op.
251251 ** argument bCache is true, set the p->bTotalsValid flag to indicate
251444 ** Allocate a new rowid. This is used for "external content" tables when
251445 ** a NULL value is inserted into the rowid column. The new rowid is allocated
251449 ** If the %_docsize table does not exist, SQLITE_MISMATCH is returned. In
251450 ** this case the user is required to provide a rowid explicitly.
251830 ** An SQLite error code is returned if an error occurs, or SQLITE_OK
251885 ** rows. However this function is only called from the xRowCount() API,
251886 ** and there is no way for that API to be invoked if the table contains
251951 ** a legal notice, here is a blessing:
251969 ** is the same as the set of ASCII range alphanumeric characters.
252073 int is = 0;
252082 while( is<nText && rc==SQLITE_OK ){
252086 while( is<nText && ((pText[is]&0x80)==0 && a[(int)pText[is]]==0) ){
252087 is++;
252089 if( is==nText ) break;
252092 ie = is+1;
252098 nByte = ie-is;
252108 asciiFold(pFold, &pText[is], nByte);
252111 rc = xToken(pCtx, 0, pFold, nByte, is, ie);
252112 is = ie+1;
252127 ** from the sqlite3 source file utf.c. If this file is compiled as part
252189 int eRemoveDiacritic; /* True if remove_diacritics=1 is set */
252380 ** passed as the first argument, codepoint iCode is considered a token
252416 int is;
252423 /* A character outside of the ascii range. Skip past it if it is
252424 ** a separator character. Or break out of the loop if it is not. */
252425 is = zCsr - (unsigned char*)pText;
252432 is = zCsr - (unsigned char*)pText;
252443 /* Grow the output buffer so that there is sufficient space to fit the
252461 ** it is a token character, or break out of the loop if it is not. */
252486 rc = xToken(pCtx, 0, aFold, zOut-aFold, is, ie);
253354 ** Argument xCreate is a pointer to a constructor function for a tokenizer.
253355 ** pTok is a tokenizer previously created using the same method. This function
253358 ** In practice, this is:
253410 ** a legal notice, here is a blessing:
253429 ** If the argument is a codepoint corresponding to a lowercase letter
253501 ** is a diacritical modifier character.
253515 ** is an upper case character that has a lower case equivalent,
253520 ** is less than zero.
253527 ** If the least significant bit in flags is clear, then the rule applies
253529 ** need to be folded). Or, if it is set, then the rule only applies to
253534 ** case equivalent is ((C + aiOff[flags>>1]) & 0xFFFF).
254181 aAscii[0] = 0; /* 0x00 is never a token character */
254189 ** a legal notice, here is a blessing:
254204 ** This is a copy of the sqlite3GetVarint32() routine from the SQLite core.
254206 ** version depends on being handled before its function is called.
254249 /* A 32-bit varint is used to store size information in btrees.
254251 ** A 3-byte varint is sufficient, for example, to record the size
254284 ** Return the number of bytes read. The value is stored in *v.
254446 ** The variable-length integer encoding is as follows:
254473 ** of bytes written is returned.
254478 ** 8 bits and is the last byte.
254534 ** a legal notice, here is a blessing:
254542 ** This is an SQLite virtual table module implementing direct access to an
254549 ** One row for each term/column combination. The value of $doc is set to
254551 ** $term within column $col. Field $cnt is set to the total number of
254557 ** One row for each term in the database. The value of $doc is set to
254559 ** $term. Field $cnt is set to the total number of instances of term
254590 int bEof; /* True if this cursor is at EOF */
254678 ** This function is the implementation of both the xConnect and xCreate
254758 ** work is done in function fts5VocabInitVtab().
255128 ** This is the xFilter implementation for the virtual table.
255201 ** This is the xEof method of the virtual table. SQLite calls this
255277 ** This is the xRowid method. The SQLite core calls this routine to
255333 ** a legal notice, here is a blessing:
255371 /* stmt_vtab is a subclass of sqlite3_vtab which will
255380 /* stmt_cursor is a subclass of sqlite3_vtab_cursor which will
255392 ** The stmtConnect() method is invoked to create a new
255397 ** All this routine needs to do is:
255446 ** This method is the destructor for stmt_cursor objects.
255499 ** is currently pointing.
255518 ** rowid is the same as the output value.
255536 ** This method is called to "rewind" the stmt_cursor object back
255537 ** to the first row of output. This method is always called at least