Lines Matching defs:be
4 ** single large file, the entire code can be compiled as a single translation
5 ** unit. This allows many compilers to do optimizations that would not be
15 ** of the embedded sqlite3.h header file.) Additional code files may be needed
49 ** large file support, or if the OS is windows, these should be no-ops.
52 ** system #includes. Hence, this block of code must be the very first
55 ** Large file support can be disabled using the -DSQLITE_DISABLE_LFS switch
133 ** It used to be the case that setting this value to zero would
202 ** The maximum number of attached databases. This must be between 0
226 ** compiled with the default page-size limit will not be able to rollback
266 ** This value can be lowered (or raised) at run-time using that the
284 ** A value of 1 means that a trigger program will not be able to itself
286 ** may be executed.
350 ** The SQLITE_THREADSAFE macro must be defined as 0, 1, or 2.
369 ** Powersafe overwrite is on by default. But can be turned off using
377 ** The SQLITE_DEFAULT_MEMSTATUS macro must be defined as either 0 or 1.
380 ** be overridden at runtime using the sqlite3_config() API.
387 ** Exactly one of the following macros must be defined in order to
396 ** will cause HeapValidate to be called. If heap validation should fail, an
397 ** assertion will be triggered.
399 ** (Historical note: There used to be several other options, but we've
459 ** testcase() must be evaluated both true and false in order to
463 ** can be used to make sure boundary values are tested. For
464 ** bitmask tests, testcase() can be used to make sure each bit
504 ** are intended to always be true or false, respectively. Such
505 ** expressions could be omitted from the code completely. But they
514 ** be true and false so that the unreachable code then specify will
515 ** not be counted as untested code.
566 ** notice, and should not be referenced by programs that use SQLite.
611 ** compatibility only. Application writers should be aware that
644 ** be larger than the release from which it is derived. Either Y will
645 ** be held constant and Z will be incremented or else Y will be incremented
646 ** and Z will be reset to zero.
704 ** compile time. ^The SQLITE_ prefix may be omitted from the
715 ** and sqlite3_compileoption_get() may be omitted by specifying the
733 ** SQLite can be compiled with or without mutexes. When
742 ** the mutexes. But for maximum safety, mutexes should be enabled.
743 ** ^The default behavior is for mutexes to be enabled.
745 ** This interface can be used by an application to make sure that the
752 ** can be fully or partially disabled using a call to [sqlite3_config()]
833 ** The C parameter to [sqlite3_close(C)] must be either a NULL
912 const char *sql, /* SQL to be evaluated */
926 ** New error codes may be added in future versions of SQLite.
979 ** One may expect the number of extended result codes will be expand
983 ** The SQLITE_OK result code will never be extended. It will always
984 ** be exactly zero.
1067 ** guaranteed to be unchanged.
1105 ** information need not be flushed. If the lower four bits of the flag
1153 ** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed. The
1158 ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
1161 ** flag may be ORed in to indicate that only the data of the file
1162 ** and not its inode needs to be synced.
1183 ** write return values. Potential uses for xFileControl() might be
1196 ** minimum write that can be performed without disturbing
1253 /* Additional methods may be added in future releases */
1268 ** is used during testing and only needs to be supported when SQLITE_TEST
1273 ** layer a hint of how large the database file will grow to be during the
1274 ** current transaction. This hint is not guaranteed to be accurate but it
1314 ** to be adjusted. The values are changed for all database connections
1319 ** into the array entry, allowing the current retry settings to be
1331 ** in order for the database to be readable. The fourth parameter to
1332 ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
1342 ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
1350 ** reason, the entire database file will be overwritten by the current
1354 ** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of
1407 ** The mutex module within SQLite defines [sqlite3_mutex] to be an
1424 ** The value of the iVersion field is initially 1 but may be larger in
1425 ** future versions of SQLite. Additional fields may be appended to this
1449 ** be unique across all VFS modules.
1459 ** the string will be valid and unchanged until xClose() is
1465 ** xFilename parameter is NULL it will also be the case that the
1473 ** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set.
1493 ** also be no-ops, and any attempt to read the journal would return
1495 ** file will be doing page-aligned sector reads and writes in a random
1505 ** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
1507 ** will be set for TEMP databases and their journals, transient
1515 ** be created, and that it is an error if it already exists.
1516 ** It is <i>not</i> used to indicate the file should be opened
1526 ** element will be valid after xOpen returns regardless of the success
1530 ** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
1533 ** to test whether a file is at least readable. The file can be a
1539 ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
1565 ** simulate faults and error conditions that would otherwise be difficult
1566 ** or impossible to induce. The set of system calls that can be overridden
1568 ** next. Applications that use these interfaces must be prepared for any
1569 ** or all of these interfaces to be NULL or for their behavior to change
1609 ** New fields may be appended in figure versions. The iVersion
1617 ** These integer constants can be used as the third parameter to
1624 ** (in other words, if files can be added, removed, and renamed within
1631 ** currently unused, though it might be used in a future release of
1653 ** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
1699 ** is not. The sqlite3_shutdown() interface must only be called from a
1700 ** single thread. All open [database connections] must be closed and all
1701 ** other SQLite resources must be deallocated prior to invoking
1716 ** calls sqlite3_initialize() so the SQLite library will be automatically
1717 ** initialized when [sqlite3_open()] is called if it has not be initialized
1768 ** may only be invoked prior to library initialization using
1772 ** Note, however, that ^sqlite3_config() can be called as part of the
1777 ** what property of SQLite is to be configured. Subsequent arguments
1837 ** is always at least as big as the requested size but may be larger.
1839 ** The xRoundup method returns what would be the allocated size of
1855 ** the xInit method, so the xInit method need not be threadsafe. The
1857 ** not need to be
1862 ** methods must be threadsafe or else make their own arrangements for
1885 ** can be passed as the first argument to the [sqlite3_config()] interface.
1887 ** New configuration options may be added in future releases of SQLite.
1888 ** Existing configuration options might be discontinued. Applications
1898 ** all mutexing and puts SQLite into a mode where it can only be used
1912 ** are enabled so that SQLite will be safe to use in a multi-threaded
1939 ** alternative low-level memory allocation routines to be used in place of
1948 ** This option can be used to overload the default memory allocation
1971 ** aligned memory buffer from which the scratch allocations will be
1974 ** argument must be a multiple of 16.
1975 ** The first argument must be a pointer to an 8-byte aligned buffer
1978 ** N should be set to twice the expected maximum number of threads.
1982 ** [sqlite3_malloc()] will be used to obtain the memory needed.</dd>
1987 ** This configuration should not be used if an application-define page
1991 ** The sz argument should be the size of the largest database page
2002 ** be aligned to an 8-byte boundary or subsequent behavior of SQLite
2003 ** will be undefined.</dd>
2017 ** The first pointer (the memory pointer) must be aligned to an 8-byte
2018 ** boundary or subsequent behavior of SQLite will be undefined.
2025 ** alternative low-level mutex routines to be used in place
2039 ** This option can be used to overload the default mutex allocation
2054 ** verb to [sqlite3_db_config()] can be used to change the lookaside
2078 ** [sqlite3_log()] call and is intended to be a [result code] or an
2084 ** function must be threadsafe. </dd>
2096 ** disabled. The default value may be changed by compiling with the
2101 ** <dd> These options are obsolete and should not be used by new code.
2129 ** can be passed as the second argument to the [sqlite3_db_config()] interface.
2131 ** New configuration options may be added in future releases of SQLite.
2132 ** Existing configuration options might be discontinued. Applications
2145 ** may be
2148 ** slots. The size of the buffer in the first argument must be greater than
2150 ** must be aligned to an 8-byte boundary. ^If the second argument to
2153 ** configuration for a database connection can only be changed when that
2163 ** [foreign key constraints]. There should be two additional arguments.
2168 ** following this call. The second parameter may be a NULL pointer, in
2173 ** There should be two additional arguments.
2178 ** following this call. The second parameter may be a NULL pointer, in
2232 ** be successful even if it is subsequently rolled back.
2285 ** the sqlite3_changes() interface can be called to find the number of
2342 ** to be interrupted and might continue to completion.
2347 ** will be rolled back automatically.
2372 ** appears to be a complete SQL statement. ^A statement is judged to be
2389 ** then the return value from sqlite3_complete16() will be non-zero
2392 ** The input to [sqlite3_complete()] must be a zero-terminated
2395 ** The input to [sqlite3_complete16()] must be a zero-terminated
2404 ** ^This routine sets a callback function that might be invoked whenever
2410 ** is not NULL, then the callback might be invoked with two arguments.
2421 ** The presence of a busy handler does not guarantee that it will be invoked
2445 ** cache will be left in an inconsistent state and so the error
2453 ** ^(There can only be a single busy handler defined for each
2480 ** ^(There can only be a single busy handler for a particular
2499 ** numbers are obtained separately. Let N be the number of rows
2500 ** and M be the number of columns.
2511 ** A result table should be deallocated using [sqlite3_free_table()].
2561 const char *zSql, /* SQL to be evaluated */
2577 ** The strings returned by these two routines should be
2587 ** historical accident that cannot be fixed without breaking
2591 ** the number of characters written would be a more useful return
2598 ** the zero terminator. So the longest string that can be completely
2599 ** written will be n-1 characters.
2611 ** character it escapes that character and allows it to be inserted into
2685 ** that it might be reused. ^The sqlite3_free() routine is
2688 ** should neither be read nor written. Even reading previously freed
2695 ** prior memory allocation to be at least N bytes, where N is the
2696 ** second parameter. The memory allocation to be resized is the first
2718 ** implementation of these routines to be omitted. That capability
2719 ** is no longer provided. Only built-in memory allocators can be used.
2730 ** must be either NULL or else pointers obtained from a prior
2800 ** specific action but allow the SQL statement to continue to be
2801 ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
2816 ** the particular action to be authorized. ^The third through sixth parameters
2818 ** details about the action to be authorized.
2825 ** return can be used to deny an untrusted user access to individual
2837 ** not want the user to be able to make arbitrary changes to the
2838 ** database. An authorizer could then be put in place while the
2847 ** ^(Only a single authorizer can be in place on a database connection
2858 ** statement might be re-prepared during [sqlite3_step()] due to a
2896 ** the authorizer callback may be passed.
2898 ** These action code values signify what kind of operation is to be
2900 ** callback function will be parameters or NULL depending on which of these
2946 ** These routines register callback functions that can be used for
2976 ** function X to be invoked periodically during long running calls to
2986 ** ^Only a single progress handler may be defined at one time per
2993 ** interrupted. This feature can be used to implement a
3013 ** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
3016 ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
3020 ** ^The default encoding for the database will be UTF-8 if
3025 ** associated with the [database connection] handle should be released by
3063 ** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
3083 ** on-disk database will be created. ^This private database will be
3100 ** authority, then it must be either an empty string or the string
3119 ** <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
3121 ** be used to access the database file on disk. ^If this option is set to
3127 ** <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw" or
3140 ** <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
3171 ** necessary - space characters can be used literally
3193 ** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
3195 ** characters must be converted to UTF-8 prior to passing them into
3273 ** However, the error string might be overwritten or deallocated by
3276 ** When the serialized [threading mode] is in use, it might be the
3279 ** When that happens, the second error will be reported since these
3288 ** error code and message may or may not be set.
3324 ** ^(This interface allows the size of various constructs to be limited
3326 ** [database connection] whose limit is to be set or queried. The
3328 ** class of constructs to be size limited. The third parameter is the
3347 ** by untrusted external sources. An example application might be a
3350 ** off the Internet. The internal databases can be given the
3352 ** be given much smaller limits designed to prevent a denial of service
3355 ** created by an untrusted script can be contained using the
3358 ** New run-time limit categories may be added in future releases.
3367 ** that can be lowered at run-time using [sqlite3_limit()].
3392 ** enforced, though that might be added in some future release of
3430 ** To execute an SQL query, it must first be compiled into a byte-code
3437 ** The second argument, "zSql", is the statement to be compiled, encoded
3448 ** performance advantage to be gained by passing an nByte parameter that
3458 ** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
3464 ** ppStmt may not be NULL.
3496 ** then the statement will be automatically recompiled, as if there had been
3539 ** ^This interface can be used to retrieve a saved copy of the original
3587 ** This interface can be used in combination [sqlite3_next_stmt()]
3589 ** connection that are in need of being reset. This can be used,
3600 ** that can be stored in a database table. SQLite uses dynamic typing
3602 ** can be integers, floating point values, strings, BLOBs, or NULL.
3604 ** An sqlite3_value object may be either "protected" or "unprotected".
3613 ** sqlite3_value object. If SQLite is compiled to be single-threaded
3618 ** sqlite3_value objects and they can be used interchangeably. However,
3627 ** Unprotected sqlite3_value objects may only be used with
3654 ** literals may be replaced by a [parameter] that matches one of following
3668 ** can be set using the sqlite3_bind_*() routines defined here.
3674 ** ^The second argument is the index of the SQL parameter to be set.
3678 ** ^The index for named parameters can be looked up using the
3681 ** ^The NNN value must be between 1 and the [sqlite3_limit()]
3687 ** number of bytes in the parameter. To be clear: the value is the
3692 ** or sqlite3_bind_text16() then that parameter must be the byte offset
3706 ** information is in static, unmanaged space and does not need to be freed.
3750 ** ^This routine can be used to find the number of [SQL parameters]
3759 ** there may be gaps in the list.)^
3801 ** name must be given in UTF-8 even if the original statement
3865 ** ^The name of the database or table or column can be returned as
3926 ** and the following statement to be compiled:
3949 ** must be called one or more times to evaluate the statement.
3956 ** interface will continue to be supported.
3958 ** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
3961 ** [extended result codes] might be returned as well.
3971 ** successfully. sqlite3_step() should not be called again on this virtual
3977 ** caller. The values may be accessed using the [column access functions].
3981 ** violation) has occurred. sqlite3_step() should not be called again on
3982 ** the VM. More information may be found by calling [sqlite3_errmsg()].
3985 ** can be obtained by calling [sqlite3_reset()] on the
3993 ** be the case that the same database connection is being used by two or
4006 ** can be used to restore the legacy behavior.
4085 ** should be returned. ^The leftmost column of the result set has the index 0.
4086 ** ^The number of columns in the result can be determined using
4091 ** These routines may only be called when the most recent call to
4141 ** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
4184 ** sqlite3_column_text16() may be invalidated.
4191 ** need to be added to the string.</li>
4193 ** sqlite3_column_text16() is called. The content must be converted
4196 ** sqlite3_column_text() is called. The content must be converted
4200 ** ^Conversions between UTF-16be and UTF-16le are always done in place and do
4257 ** ^The sqlite3_finalize(S) routine can be called at any point during
4278 ** object back to its initial state, ready to be re-executed.
4315 ** function is to be added. ^If an application uses more than one database
4316 ** connection then application-defined SQL functions must be added
4319 ** ^The second parameter is the name of the SQL function to be created or
4336 ** its parameters. Every SQL function implementation must be able to work
4337 ** with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
4344 ** encoding is used, then the fourth argument should be [SQLITE_ANY].
4352 ** callback only; NULL pointers must be passed as the xStep and xFinal
4354 ** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing
4381 ** ^Built-in functions may be overloaded by new application-defined functions.
4439 ** to be supported. However, new applications should avoid
4490 ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
4494 ** These routines must be called from the same thread as
4526 ** In those cases, sqlite3_aggregate_context() might be called for the
4541 ** The first parameter must be a copy of the
4546 ** This routine must be called from the same thread in which
4560 ** This routine must be called from the same thread in which
4579 ** The following two functions may be used by scalar SQL functions to
4582 ** some circumstances the associated metadata may be preserved. This may
4583 ** be used, for example, to add a regular-expression matching scalar
4586 ** pattern. The compiled regular expression can be reused on multiple
4588 ** does not need to be recompiled on each invocation.
4609 ** the destructor will be called before the metadata is dropped.
4615 ** These routines must be called from the same thread in which
4628 ** and will never change. It does not need to be destroyed. ^The
4653 ** an application-defined function to be the BLOB whose content is pointed
4658 ** the application-defined function to be a BLOB containing all zero
4662 ** an application-defined function to be a floating point value specified
4694 ** of the application-defined function to be the 32-bit signed integer
4697 ** of the application-defined function to be the 64-bit signed integer
4701 ** of the application-defined function to be NULL.
4705 ** set the return value of the application-defined function to be
4717 ** must be the byte offset into the string where the NUL terminator would
4737 ** the application-defined function to be a copy the
4741 ** be deallocated after sqlite3_result_value() returns without harm.
4742 ** ^A [protected sqlite3_value] object may always be used where an
4744 ** kind of [sqlite3_value] object can be used with this interface.
4777 ** considered to be the same name.
4779 ** ^(The third argument (eTextRep) must be one of the constants:
4790 ** force strings to be UTF16 with native byte order.
4798 ** ^Multiple collating functions can be registered using the same name but
4841 ** is unfortunate but cannot be changed without breaking backwards
4873 ** can be used, a single callback function may be registered with the
4874 ** [database connection] to be invoked whenever an undefined collation
4908 ** Specify the key for an encrypted database. This routine should be
4915 sqlite3 *db, /* Database to be rekeyed */
4928 sqlite3 *db, /* Database to be rekeyed */
4958 ** millisecond time resolution, then the time will be rounded up to
4976 ** will be placed in that directory.)^ ^If this variable
4984 ** It is intended that this variable be set once
4995 ** Hence, if this variable is modified directly, either it should be
4997 ** or else the use of the [temp_store_directory pragma] should be avoided.
5014 ** transaction might be rolled back automatically. The only way to
5047 ** will be an absolute pathname, even if the filename used
5072 ** connection and in particular must not be a NULL pointer.
5080 ** function to be invoked whenever a transaction is [COMMIT | committed].
5084 ** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
5099 ** to modify the database connection must be deferred until after the
5112 ** hook returning non-zero, just as it would be with any other rollback.
5130 ** to be invoked whenever a row is updated, inserted or deleted.
5140 ** to be invoked.
5158 ** to modify the database connection must be deferred until after the
5214 ** which might be more or less than the amount requested.
5239 ** soft limit on the amount of heap memory that may be allocated by SQLite.
5252 ** size of the soft heap limit can be determined by invoking
5315 ** may be NULL.
5318 ** and subsequent parameters to this function. ^Any of these arguments may be
5355 ** cannot be found, an [error code] is returned and an error message left
5356 ** in the [database connection] (to be retrieved using sqlite3_errmsg()).)^
5382 ** ^zProc may be 0, in which case the name of the entry point
5392 ** ^Extension loading must be enabled using
5394 ** otherwise an error will be returned.
5423 ** ^This interface causes the xEntryPoint() function to be invoked for
5426 ** that is to be automatically loaded into all new database connections.
5451 ** will be called more than once for each database connection that is opened.
5467 ** to be experimental. The interface might change in incompatible ways.
5553 ** expr on the right-hand side can be evaluated (and thus the constraint
5569 ** is true, then the constraint is assumed to be fully handled by the
5631 ** ^Module names must be registered before
5641 ** when a new virtual table is be being created or reinitialized.
5647 ** be invoked if the call to sqlite3_create_module_v2() fails.
5673 ** be tailored to the specific needs of the module implementation.
5681 ** is delivered up to the client application, the string will be automatically
5682 ** freed by sqlite3_free() and the zErrMsg field will be zeroed.
5729 ** must exist in order to be overloaded.)^
5734 ** of the new function always causes an exception to be thrown. So
5736 ** purpose is to be a placeholder function that can be overloaded
5744 ** to be experimental. The interface might change in incompatible ways.
5756 ** [sqlite3_blob_open | incremental BLOB I/O] can be performed.
5760 ** can be used to read or write small subsections of the BLOB.
5770 ** in other words, the same BLOB that would be selected by:
5790 ** to be a null pointer.)^
5809 ** the opened blob. ^The size of a blob may not be changed by this
5814 ** and the built-in [zeroblob] SQL function can be used, if desired,
5819 ** be released by a call to [sqlite3_blob_close()].
5836 ** by the rowid value passed as the second argument. Only the row can be
5838 ** remain the same. Moving an existing blob handle to a new row can be
5842 ** it must exist and there must be either a blob or text value stored in
5863 ** ^If any writes were made to the BLOB, they might be held in cache
5874 ** ^Calling this routine with a null pointer (such as would be returned
5905 ** can be determined using the [sqlite3_blob_bytes()] interface.
5939 ** can be determined using the [sqlite3_blob_bytes()] interface.
5967 ** New VFSes can be registered and existing VFSes can be unregistered.
5978 ** ^The same VFS can be registered multiple times without injury.
6029 ** that means that a mutex could not be allocated. ^SQLite
6072 ** dynamic mutex that it allocates. The dynamic mutexes must not be in
6082 ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
6084 ** mutex must be exited an equal number of times before another thread
6125 ** Additionally, an instance of this structure can be used as an
6163 ** The xMutexInit() method must be threadsafe. ^It must be harmless to
6166 ** xMutexInit() must be no-ops.
6213 ** clearly the mutex cannot be held if it does not exist. But
6232 ** next. Applications that override the built-in mutex logic must be
6266 ** ^A NULL pointer can be used in place of "main" to refer to the
6274 ** a pointer to the underlying [sqlite3_file] object to be written into
6281 ** code is not remembered and will not be recalled by [sqlite3_errcode()]
6359 ** This routine is threadsafe but is not atomic. This routine can be
6376 ** that can be returned by [sqlite3_status()].
6409 ** allocation which could not be satisfied by the [SQLITE_CONFIG_PAGECACHE]
6432 ** allocation which could not be satisfied by the [SQLITE_CONFIG_SCRATCH]
6451 ** New status parameters may be added from time to time.
6469 ** database connection object to be interrogated. ^The second argument
6492 ** These constants are the available integer "verbs" that can be passed as
6495 ** New verbs may be added in future releases of SQLite. Existing verbs
6496 ** might be discontinued. Applications should check the return code from
6579 ** be used to monitor the performance characteristics of the prepared
6587 ** object to be interrogated. The second argument
6589 ** to be interrogated.)^
6623 ** need to be reinitialized each time the statement is run.</dd>
6697 ** It can be used to clean up
6699 ** ^The xShutdown() method may be NULL.
6702 ** so the xInit method need not be threadsafe. ^The
6704 ** not need to be threadsafe either. All other methods must be threadsafe
6715 ** be allocated by the cache. ^szPage will always a power of two. ^The
6723 ** created will be used to cache database pages of a file stored on disk, or
6734 ** ^(The xCachesize() method may be called at any time by SQLite to set the
6748 ** The pBuf element of the returned sqlite3_pcache_page object will be a
6750 ** single database page. The pExtra element of sqlite3_pcache_page will be
6754 ** The page to be fetched is determined by the key. ^The minimum key value
6756 ** to be "pinned".
6782 ** then the page must be evicted from the cache.
6784 ** zero, then the page may be discarded or retained at the discretion of
6795 ** previously contains an entry associated with newKey, it must be
6797 ** to be pinned.
6803 ** they can be safely discarded.
6807 ** All resources associated with the specified cache should be freed. ^After
6882 ** ^Thus, the backup may be performed on a live source database without
6895 ** There should be exactly one call to sqlite3_backup_finish() for each
6910 ** must be different or else sqlite3_backup_init(D,N,S,M) will fail with
6917 ** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or
6921 ** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and
6931 ** are still more pages to be copied, then the function returns [SQLITE_OK].
6954 ** sqlite3_backup_step() can be retried later. ^If the source
6958 ** case the call to sqlite3_backup_step() can be retried later on. ^(If
6973 ** sqlite3_backup_step(), the source database may be modified mid-way
6976 ** used by the backup operation, then the backup will be automatically
6992 ** and may not be used following a call to sqlite3_backup_finish().
7009 ** the [sqlite3_backup] object: the number of pages still to be backed
7017 ** pages that need to be updated or the size of the source database file
7022 ** ^The source [database connection] may be used by the application for other
7025 ** connections, then the source database connection may be used concurrently
7067 ** individual tables within the shared-cache cannot be obtained. See
7069 ** ^This API may be used to register a callback that SQLite will invoke
7085 ** the first argument to register for a callback that will be invoked
7101 ** ^(There may be at most one unlock-notify callback registered by a
7107 ** unlock-notify callback may also be canceled by closing the blocked
7112 ** crash or deadlock may be the result.
7126 ** When a blocking connections transaction is concluded, there may be
7138 ** database waits for the callback to be issued before taking any further
7141 ** connection Y's transaction to be concluded, and similarly connection
7148 ** unlock-notify callback is registered. The system is said to be in
7153 ** the system is also considered to be deadlocked if connection B has
7168 ** or "DROP INDEX" query, an infinite loop might be the result.
7207 ** The zFormat string must not be NULL.
7212 ** a few hundred characters, it will be truncated to the length of the
7221 ** will be invoked each time a database connection commits data to a
7274 ** ^The [wal_autocheckpoint pragma] can be used to invoke this interface
7280 ** is only necessary if the default setting is found to be suboptimal
7289 ** on [database connection] D to be [checkpointed]. ^If X is NULL or an
7294 ** ^The [wal_checkpoint pragma] can be used to invoke this interface
7296 ** [wal_autocheckpoint pragma] can be used to cause this interface to be
7336 ** checkpointed when this function is called). *pnLog and *pnCkpt may be
7343 ** lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a
7344 ** busy-handler configured, it will not be invoked in this case.
7347 ** "writer" lock on the database file. If the writer lock cannot be obtained
7384 ** These constants can be used as the 3rd parameter to
7396 ** This function may be called by either the [xConnect] or [xCreate] method
7403 ** At present, there is only one option that may be configured using
7405 ** may be added in the future.
7453 ** This function may only be called from within a call to the [xUpdate] method
7518 ** Register a geometry callback named zGeom that can be used as part of an
7577 ** The internals of this structure are intended to be opaque -- client
7591 ** Hash.htsize and Hash.ht may be zero. In that case lookup is done
7610 ** Again, this structure is intended to be opaque, but it can't really
7611 ** be opaque because it is used by macros.
7865 ** Determine whether triggers are recursive by default. This can be
7901 ** types can be conveniently redefined at compile-type. Like this:
7953 ** that can be stored in a u32 without loss of data. The value
7963 ** can be used at compile-time if desired.
8079 ** All variables must either be on the stack or dynamically allocated from
8113 ** However, these macros may also be used to suppress warnings related to
8114 ** parameters that may or may not be used depending on compilation options.
8194 ** needs to be revisited.
8200 ** it must be turned on for each database using "PRAGMA auto_vacuum = 1".
8227 /* The flags parameter to sqlite3BtreeOpen can be the bitwise or of the
8271 /* The flags parameter to sqlite3BtreeCreateTable can be the bitwise OR
8293 ** should be one of the following values. The integer values are assigned
8295 ** SQLite database header may be found using the following formula:
8505 void *token; /* id that may be used to recursive triggers */
8545 ** gets freed when the Vdbe is finalized so it still should be obtained
8870 ** value means no limit. This value may be overridden using the
9078 ** and should not be accessed by other modules.
9106 ** Only clean and unpinned pages can be reclaimed.
9231 ** will defined to either 1 or 0. One of the four will be 1. The other
9232 ** three will be 0.
9280 # include <os2safe.h> /* has to be included before os2.h for linking to work */
9299 ** We ought to be able to determine if we are compiling for win98 or winNT
9347 ** prematurely, old temporary files can be easily identified. This can be done
9350 ** 2006-10-31: The default prefix used to be "sqlite_". But then
9356 ** For this reason, the default name prefix is changed to be "sqlite"
9367 ** The following values may be passed as the second argument to
9375 ** SHARED locks may be obtained by other processes.
9378 ** PENDING_LOCK may not be passed directly to sqlite3OsLock(). Instead, a
9380 ** lock. This can be upgraded to an EXCLUSIVE lock by a subsequent call to
9402 ** There can only be one writer. A RESERVED_LOCK is obtained by locking
9538 ** mutexes implemention cannot be overridden
9543 ** implementation can be overridden at
9591 ** Each database file to be accessed by the system is an instance
9595 ** databases may be attached.
9610 ** In shared cache mode, a single Schema object can be shared by multiple
9617 ** A thread must be holding a mutex on the corresponding Btree in order
9618 ** to access Schema content. This implies that the thread must also be
9637 ** These macros can be used to test, set, or clear bits in the
9653 ** changes and so the view will need to be reset.
9660 ** The number of different kinds of things that can be limited
9666 ** Lookaside malloc is a set of fixed-size buffers that can be used
9680 ** be stored in lookaside because in shared cache mode the schema information
9859 ** These must be the low-order bits of the flags field.
9891 u8 iPrefEnc; /* Preferred text encoding (SQLITE_UTF8, 16LE, 16BE) */
9929 #define SQLITE_FUNC_NEEDCOLL 0x08 /* sqlite3GetFuncCollSeq() might be called */
10040 ** collating sequence may not be read or written.
10051 ** A sort order can be either ASC or DESC.
10065 ** used as the P4 operand, they will be more readable.
10085 ** Additional bit values that can be ORed with an affinity without
10100 ** implementation. sqlite3_vtab* handles can not be shared between
10105 ** then be used by the virtual table implementation to access real tables
10107 ** transaction, these accesses need to be made via the same database
10157 ** that the datatype of the PRIMARY KEY must be INTEGER for this field to
10158 ** be set. An INTEGER PRIMARY KEY is used as the rowid for each row of
10216 ** done as a macro so that it will be optimized out when virtual
10267 ** to be rolled back. ABORT processing means the operation in process
10312 u8 *aSortOrder; /* Sort order for each column. May be NULL */
10349 ** The columns of the table that are to be indexed are described
10360 ** first column to be indexed (c3) has an index of 2 in Ex1.aCol[].
10361 ** The second column to be indexed (c1) has an index of 0 in
10365 ** must be unique and what to do if they are not. When Index.onError=OE_None,
10435 ** fields do not need to be freed when deallocating the AggInfo structure.
10488 ** as opcodes here. For example, the parser defines TK_GE to be an integer
10500 ** binary operator. Either or both may be NULL.
10515 ** it can be accessed after all aggregates are computed.
10534 ** help reduce memory requirements, sometimes an Expr object will be
10536 ** two or more Expr objects will be stored in a single memory allocation,
10628 ** These macros can be used to test, set, or clear bits in the
10653 ** name. An expr/name combination can be used in several ways, such
10656 ** also be used as the argument to a function, in which case the a.zName
10727 ** can also be used to describe a particular table such as the table that
10729 ** such a table must be a simple name: ID. But in SQLite, the table can
10730 ** now be identified by a database name, a dot, then the table name: ID.ID.
10782 ** This object is intended to be opaque outside of the where.c module.
10784 ** is. None of the fields in this object should be used outside of
10806 ** is intended to be private the the where.c module and should not be
10892 ** be NULL. The pSrc corresponds to the FROM clause of a SELECT or
10897 ** NameContexts can be nested. When resolving names, the inner-most
10934 ** These addresses must be stored so that we can go back and fill in
10936 ** the number of columns in P2 can be computed at the same time
10967 #define SF_Distinct 0x01 /* Output should be DISTINCT */
10978 ** The results of a select can be distributed in several ways. The
11034 ** trigger that may be fired while parsing an INSERT, UPDATE or DELETE
11111 u8 tempReg; /* iReg is a temp register that needs to be freed */
11182 ** An instance of the following structure can be declared on a stack and used
11183 ** to save the Parse.zAuthContext value so that it can be restored later.
11196 #define OPFLAG_APPEND 0x08 /* This is likely to be an append */
11206 * database). This allows Trigger structures to be retrieved by name.
11220 Expr *pWhen; /* The WHEN clause of the expression (may be NULL) */
11234 ** In that cases, the constants below can be ORed together.
11258 * this stores values to be inserted. Otherwise NULL.
11260 * statement, then this stores the column-names to be
11305 ** do not necessarily know how big the string will be in the end.
11308 sqlite3 *db; /* Optional database for lookaside. Can be NULL */
11357 /* The above might be initialized to non-zero. The following need to always
11358 ** initially be zero, however. */
11500 ** that deal with sqlite3StackAlloc() failures to be unreachable.
11827 ** be defined locally, but now we use the varint routines in the util.c
12065 ** Available fault injectors. Should be numbered beginning with 0.
12147 ** the MEMTYPE_* macros defined below. The type must be a bitmask with
12263 ** is (x - 0x20). Therefore toupper() can be implemented as:
12270 ** Bit 0x40 is set if the character non-alphanumeric and can be used in an
12348 /* All the rest should always be initialized to zero */
12379 ** The value of the "pending" byte must be 0x40000000 (1 byte past the
12388 ** than 1 GiB. The sqlite3_test_control() interface can be used to
12431 ** be sorted A-Z.
12840 ** VDBE. This information used to all be at the top of the single
12849 ** SQL is translated into a sequence of instructions to be
12911 ** be NULL.
13001 ** No other flags may be set in this case.
13020 ** the following flags must be set to determine the memory management
13054 ** that can be associated with a constant argument to a function. This
13082 FuncDef *pFunc; /* Pointer to function information. MUST BE FIRST */
13146 u8 expired; /* True if the VM needs to be recompiled */
13566 ** This implemention requires years to be expressed as a 4-digit number
13568 ** be represented, even though julian day numbers allow a much wider
13704 ** The HH, MM, and SS must each be exactly 2 digits. The
13705 ** fractional seconds FFFF can be one or more digits.
13856 ** (":SS.FFF") is option. The year and date can be omitted as long
13857 ** as there is a time string. The time string can be omitted as long
14207 ** to the time. The ".FFF" may be omitted. The ":SS.FFF" may be
14639 ** functions. This should be the only routine in this file with
14727 ** of this would be completely automatic if SQLite were coded using
14774 ** is only a hint and can be safely ignored. The sqlite3OsFileControlHint()
14775 ** routine has no return value since the return value would be meaningless.
14825 /* 0x87f7f is a mask of SQLITE_OPEN_ flags that are valid to be passed
14927 ** error in sqlite3_os_init() by the upper layers can be tested.
15132 ** are merely placeholders. Real drivers must be substituted using
15207 ** can be set manually, if desired.
15218 ** be necessary when compiling for Delphi,
15231 ** The use of _msize() is automatic, but can be disabled by compiling
15283 ** cases of nByte<=0 will be intercepted and dealt with by higher level
16009 ** be changed.
16049 ** u.hdr.prevSize can be part of the data for that chunk and should
16050 ** not be read or written.
16206 ** will already be held (obtained by code in malloc.c) if
16296 ** this mem3.iMaster replacement to work, the master chunk must be
16658 ** is not required to be threadsafe (it is not).
16698 ** be changed.
16716 ** Let n be the size of the largest allocation divided by the minimum
16718 ** be the maximum amount of memory ever outstanding at one time. Let
16719 ** N be the total amount of memory available for allocation. Robson
16740 ** The size of this object must be a power of two. That fact is
16774 u8 *zPool; /* Memory available to be allocated */
16821 ** on. It should be found on mem5.aiFreelist[iLogsize].
16863 ** will already be held (obtained by code in malloc.c) if
16915 ** threads can be in this routine at the same time.
16923 /* nByte must be a positive */
17095 ** the allocation is too large to be handled by this allocation system,
17098 ** All allocations must be a power of two and must be expressed by a
17128 ** This routine is not threadsafe. The caller must be holding a mutex
17143 /* The size of a Mem5Link object must be a power of two. Verify that
17367 ** until it can be obtained.
17377 ** thread holds the mutex and it cannot be obtained, return SQLITE_BUSY.
17521 ** that means that a mutex could not be allocated.
17563 ** be entered multiple times by the same thread. In such cases the,
17564 ** mutex must be exited an equal number of times before another thread
17676 ** that means that a mutex could not be allocated.
17838 ** be entered multiple times by the same thread. In such cases the,
17839 ** mutex must be exited an equal number of times before another thread
17957 ** there might be race conditions that can cause these routines to
17966 ** should be compiled without -DSQLITE_DEBUG and with -DNDEBUG to
17988 ** that means that a mutex could not be allocated. SQLite
18101 ** be entered multiple times by the same thread. In such cases the,
18102 ** mutex must be exited an equal number of times before another thread
18112 ** is atomic - that it cannot be deceived into thinking self
18155 ** is atomic - that it cannot be deceived into thinking self
18382 ** (which should be the last to shutdown.) */
18398 ** that means that a mutex could not be allocated. SQLite
18486 ** be entered multiple times by the same thread. In such cases the,
18487 ** mutex must be exited an equal number of times before another thread
18636 ** be held while the callback is running. Recursive calls into
18637 ** the memory subsystem are allowed, but no new callbacks will be
18646 ** (so that a range test can be used to determine if an allocation
18928 ** Allocate memory that is to be used and released right away.
18930 ** for situations where the memory might be held long-term. This
18966 ** would be much more complicated.) */
18980 ** would be much more complicated.) */
19067 ** Free memory that might be associated with a particular database
19339 ** This function must be called before exiting any API function (i.e.
19370 ** completeness. They are very out-of-date but might be useful as
19517 ** SQLITE_PRINT_BUF_SIZE to be something smaller, if desired.
19560 etByte flag_dp; /* True if decimal point should be shown */
19561 etByte flag_rtz; /* True if trailing zeros should be removed */
20192 ** the string and before returnning. This routine is intended to be used
20278 ** allocate memory because it might be called while the memory allocator
20369 ** must be held while executing this routine.
20374 ** well be good enough. But maybe not. Or maybe lrand48() has some
20498 ** UTF-16, UTF-16BE, and UTF-16LE.
20622 ** be encoded as a multi-byte character. Any multi-byte character that
20625 ** * This routine never allows a UTF16 surrogate value to be encoded.
20828 ** The allocation (static, dynamic etc.) and encoding of the Mem may be
20919 ** be freed by the calling function.
20969 ** in pZ. nChar must be non-negative.
21099 ** This option [-ffast-math] should never be turned on by any
21127 ** Compute a string length that is limited to what can be stored in
21130 ** The value returned will never be negative. Nor will it ever be greater
21132 ** than 1GiB) the value returned might be less than the true string length.
21150 ** %z A string that should be freed after use
21155 ** zFormat and any string tokens that follow it are assumed to be
21159 ** should be called with err_code set to SQLITE_OK and zFormat set
21183 ** %z A string that should be freed after use
21188 ** This function should be used to report any error that occurs whilst
21192 ** Function sqlite3Error() should be used during statement execution
21218 ** The input string must be zero-terminated. A new zero-terminator
21437 /* 1.0e+22 is the largest power of 10 than can be
21501 ** case is broken out because while 9223372036854665808 cannot be a
21502 ** signed 64-bit integer, its negative -9223372036854665808 can be.
21578 ** input number to be zero-terminated.
21646 ** The length of data write will be between 1 and 9 bytes. The number
21939 ** rare larger cases can be handled by the slower 64-bit varint
22009 ** Return the number of bytes that will be needed to store the given
22057 ** binary value has been obtained from malloc and must be freed by
22093 ** 1 it means that the db pointer is valid and 0 if it should not be
22097 ** sqlite3SafetyCheckOk() requires that the db pointer be valid for
22099 ** open properly and is not fit for general use but which can be
22206 ** three characters, then shorten the suffix on z[] to be the last three
22253 ** "pNew" is a pointer to the hash table that is to be initialized.
22304 HashElem *pNew /* The element to be inserted */
22372 const Hash *pH, /* The pH to be searched */
22402 HashElem* elem, /* The element to be removed from the pH */
22709 ** be exercised on Linux (which does not need to malloc() in the driver)
22747 ** This file should be #included by the os_*.c files only. It is not a
22805 ** processor and returns that value. This can be used for high-res
23024 /* Unread portions of the input buffer must be zero-filled */
23036 const void *pBuf, /* The bytes to be written */
23075 ** actual file size after the operation may be larger than the requested
23302 /* If we are holding a PENDING lock that ought to be released, then
23372 ** must be either NO_LOCK or SHARED_LOCK.
23402 /* This should never happen. We should always be able to
23465 ** the specified file. This is almost always 512 bytes, but may be
23470 ** a database and its journal file) that the sector size will be the
23519 ** The returned char pointer has to be freed.
23535 /* conversion for current codepage which can be used for paths */
23545 ** The returned char pointer has to be freed.
23547 ** This function is non-static to be able to use this in shell.c and
23560 /* conversion for current codepage which can be used for paths */
23575 ** a separate file is created for this purpose. The file will be
23576 ** used only to set file locks. There will be no data written to it.
23628 ** os2ShmMutexHeld() must be true when creating or destroying
23640 ** Either os2ShmNode.mutex must be held or os2ShmNode.nRef==0 and
23672 ** All other fields are read/write. The os2Shm.pShmNode->mutex must be held
23689 ** The os2ShmMutexHeld() must be true while reading or writing this list.
23714 int ofst, /* Offset to first byte to be locked/unlocked */
24253 ** Create a temporary file name in zBuf. zBuf must be big enough to
24315 ** pathname into zFull[]. zFull[] will be at least pVfs->mxPathname
24376 ** (a) Exactly one of the READWRITE and READONLY flags must be set, and
24377 ** (b) if CREATE is set, then READWRITE must also be set, and
24378 ** (c) if EXCLUSIVE is set, then CREATE must also be set.
24379 ** (d) if DELETEONCLOSE is set, then CREATE must also be set.
24423 ** The handle should not be inherited by child processes and we don't
24583 * symbol with an extra underscore, that might be needed depending
24654 ** might be greater than or equal to the argument, but not less
24677 ** On success, return 0. Return 1 if the time and date cannot be found.
24719 ** return 0. Return 1 if the time and date cannot be found.
24742 ** it should be truncated. The return value of xGetLastError
24757 ** However if an error message is supplied, it will be incorporated
24832 ** KEEP THE STRUCTURE OF THIS FILE INTACT. New code should be placed
24833 ** in the correct division and should be clearly labeled.
24903 ** large file support, these should be no-ops.
24905 ** Large file support can be disabled using the -DSQLITE_DISABLE_LFS switch
24916 ** lack LFS in which case the SQLITE_DISABLE_LFS macro might still be useful.
24966 ** If we are to be thread-safe, include the pthreads header and define
25007 ** cannot be closed immediately. In these cases, instances of the following
25102 ** This file should be #included by the os_*.c files only. It is not a
25160 ** processor and returns that value. This can be used for high-res
25338 ** they may be overridden at runtime to facilitate fault injection during
25364 ** lacks the fcntl() system call. So redefine fcntl() to be something
25553 ** make the file creation mode be exactly m ignoring the umask.
25555 ** The m parameter will be non-zero only when creating -wal, -journal,
25560 ** process that is able to write to the database will also be able to
25583 ** vxworksFileId objects used by this file, all of which may be
25708 ** should never be hit, as this function should only be called after
25711 ** errno should be non-zero.
25714 ** SQLITE_OK. The system call failed, and *some* SQLite error should be
25716 ** will be handled by the "default:" case below.
25747 ** the default SQLITE_IOERR_XXX code will be returned. */
25788 ** On VxWorks, a unique file id must be based on the canonical filename.
25790 ** A pointer to an instance of the following structure can be used as a
25987 ** be closed and that list is walked (and cleared) when the last lock
25994 ** A cannot be modified or overridden by a different thread B.
26068 ** The first argument passed to the macro should be the error code that
26069 ** will be returned to SQLite (e.g. SQLITE_IOERR_DELETE, SQLITE_CANTOPEN).
26070 ** The two subsequent arguments should be the name of the OS function that
26101 ** available, the error message will often be an empty string. Not a
26166 ** The mutex entered using the unixEnterMutex() function must be held
26196 ** return value might be uninitialized if an error occurs.
26198 ** The mutex entered using the unixEnterMutex() function must be held
26234 ** an ASCII 'S' character which also happens to be the first byte
26406 ** slightly in order to be compatible with windows systems simultaneously
26423 ** on the 'pending byte'. This ensures that no new SHARED locks can be
26435 ** The reason a single byte cannot be used instead of the 'shared byte
26503 ** be released.
26637 ** must be either NO_LOCK or SHARED_LOCK.
26683 ** the lock in 2 blocks, so that part of the range will be covered by a
26808 ** must be either NO_LOCK or SHARED_LOCK.
26824 ** even on VxWorks. A mutex will be acquired on VxWorks by the
26859 ** routine (e.g. nolockClose()) would be called instead.
26865 ** descriptor to pInode->pUnused list. It will be automatically closed
26888 ** also be used if the application employs some external mechanism to
26931 ** sitting around that need to be cleared manually.
27052 ** must be either NO_LOCK or SHARED_LOCK.
27127 ** only a single process can be reading the database at a time.
27253 /* didn't get, must be busy */
27275 ** must be either NO_LOCK or SHARED_LOCK.
27293 /* shared can just be set because we always have an exclusive */
27441 ** must be either NO_LOCK or SHARED_LOCK.
27461 /* shared can just be set because we always have an exclusive */
27543 const char *path, /* Name of the file to be locked or unlocked */
27545 unsigned long long offset, /* First byte to be locked */
27720 ** be released.
27835 ** must be either NO_LOCK or SHARED_LOCK.
27952 ** descriptor to pInode->aPending. It will be automatically closed when
27981 ** must be either NO_LOCK or SHARED_LOCK.
28014 ** be necessary to define _XOPEN_SOURCE to be 500. This varies from
28084 ** file), the bytes in the locking range should never be read or written. */
28100 /* Unread parts of the buffer must be zero-filled */
28164 ** file), the bytes in the locking range should never be read or written. */
28226 ** Others do no. To be safe, we will stick with the (slightly slower)
28309 ** It shouldn't be possible for fullfsync to fail on the local
28313 ** It'd be better to detect fullfsync support once and avoid
28350 ** This routine can be overridden using the xSetSysCall interface.
28454 ** actual file size after the operation may be larger than the requested
28628 ** it hence it is OK for the transaction change counter to be
28648 ** the specified file. This is almost always 512 bytes, but may be
28653 ** a database and its journal file) that the sector size will be the
28701 ** unixMutexHeld() must be true when creating or destroying
28711 ** Either unixShmNode.mutex must be held or unixShmNode.nRef==0 and
28743 ** All other fields are read/write. The unixShm.pFile->mutex must be held
28874 ** for shared memory will be called "/home/user1/config.db-shm".
28881 ** meaning that their memory would not really be shared - resulting
28883 ** can be enabled at compile-time using -DSQLITE_SHM_DIRECTORY="/dev/shm"
28893 ** the file must be truncated to zero length or have its header cleared.
28899 ** file is created. The shared memory will be simulated with heap memory.
28902 struct unixShm *p = 0; /* The connection to be opened */
28925 ** a new *-shm file is created, an attempt will be made to create it
28976 ** the original owner will not be able to connect. If this process is
29014 ** at pShmNode->pFirst. This must be done while holding the pShmNode->mutex
29095 ** false, exit early. *pp will be set to NULL and SQLITE_OK returned.
29300 unixShm *p; /* The connection to be closed */
29357 ** field of the sqlite3_vfs VFS objects are initialized to be pointers to
29375 ** from be cast into a function pointer.
29549 ** that does not need to be locked. */
29602 ** that does not need to be locked. */
29653 /* Usually the path zFilename should not be a relative pathname. The
29717 ** descriptors on this file, then no malloc would be required by
29719 ** handle h - as it is guaranteed that no posix locks will be released
29734 /* AFP locking uses the file path so it needs to be included in
29761 /* Dotfile locking uses the file path so it needs to be included in
29779 /* Named semaphore locking uses the file path so it needs to be
29822 ** If no suitable temporary file directory can be found, return NULL.
29850 ** Create a temporary file name in zBuf. zBuf must be allocated
29851 ** by the calling process and must be big enough to hold at least
29907 ** but the associated file descriptor could not be closed because some
30051 ** true, the file was configured to be automatically deleted when the
30058 const char *zPath, /* Pathname of file to be opened */
30059 sqlite3_file *pFile, /* The file descriptor to be filled in */
30085 ** is called the directory file descriptor will be fsync()ed and close()d.
30101 ** (a) Exactly one of the READWRITE and READONLY flags must be set, and
30102 ** (b) if CREATE is set, then READWRITE must also be set, and
30103 ** (c) if EXCLUSIVE is set, then CREATE must also be set.
30104 ** (d) if DELETEONCLOSE is set, then CREATE must also be set.
30141 ** URIs with parameters. Hence, they can always be passed into
30160 ** open(). These must be calculated even if open() is not called, as
30161 ** they may be stored as part of the file handle and used by the
30196 ** journal or WAL file, set the ownership of the journal or WAL to be
30289 ** pFile->pMethods will be NULL so sqlite3OsClose will be a no-op
30316 const char *zPath, /* Name of file to be deleted */
30462 ** GCC with -pedantic-errors says that C90 does not allow a void* to be
30467 ** Variable x below is defined to be a pointer to a function taking
30503 ** prefer that the randomness be increased by making use of the
30541 ** might be greater than or equal to the argument, but not less
30582 ** cannot be found.
30616 be found.
30707 ** host ID in it, the proxy path in the conch file will be used, otherwise
30709 ** (via confstr(_CS_DARWIN_USER_TEMP_DIR,...)) will be used and the
30714 ** The lock path will be "<tmpdir>/sqliteplocks/_Users_me_foo.db:auto:")
30717 ** be removed, however it may be switched to a different proxy path via
30759 ** to be created the first time they are used.
30789 ** force proxy locking to be used for every database file opened, and 0
30790 ** will force automatic proxy locking to be disabled for all database
30905 int islockfile /* if non zero missing dirs will be created */
30991 /* Not always defined in the headers as it ought to be */
31172 ** lockPath means that the lockPath in the conch file will be used if the
31173 ** host IDs match, or a new lock path will be generated automatically
31523 ** will be performed on the local proxy lock file. The following fields
31524 ** are preserved in the locking context so that they can be restored and
31744 ** must be either NO_LOCK or SHARED_LOCK.
31822 ** should be the only routines in this file that are visible from other
31828 ** should not be used.
31881 ** array cannot be const.
31976 ** This file should be #included by the os_*.c files only. It is not a
32034 ** processor and returns that value. This can be used for high-res
32198 const sqlite3_io_methods *pMethod; /*** Must be first ***/
32229 * The initial size of the Win32-specific heap. This value may be zero.
32237 * The maximum size of the Win32-specific heap. This value may be zero.
32244 * The extra flags to use in calls to the Win32 heap APIs. This value may be
32314 ** they may be overridden at runtime to facilitate fault injection during
33028 ** is not required to be threadsafe (it is not).
33273 ** The first argument passed to the macro should be the error code that
33274 ** will be returned to SQLite (e.g. SQLITE_IOERR_DELETE, SQLITE_CANTOPEN).
33275 ** The two subsequent arguments should be the name of the OS function that
33305 ** will be retried following a locking error - probably caused by
33320 ** to see if it should be retried. Return TRUE to retry. Return FALSE
33450 ** must be zero-initialized */
33471 /* If shared memory could not be created, then close the mutex and fail */
33705 ** INVALID_SET_FILE_POINTER may also be a valid new offset. So to determine
33797 /* Unread parts of the buffer must be zero-filled */
33811 const void *pBuf, /* The bytes to be written */
33828 u8 *aRem = (u8 *)pBuf; /* Data yet to be written */
33829 int nRem = amt; /* Number of bytes yet to be written */
33875 ** actual file size after the operation may be larger than the requested
34175 /* If we are holding a PENDING lock that ought to be released, then
34226 ** must be either NO_LOCK or SHARED_LOCK.
34247 /* This should never happen. We should always be able to
34348 ** the specified file. This is almost always 512 bytes, but may be
34353 ** a database and its journal file) that the sector size will be the
34383 ** this file, all of which may be shared by multiple threads.
34412 ** winShmMutexHeld() must be true when creating or destroying
34423 ** Either winShmNode.mutex must be held or winShmNode.nRef==0 and
34452 ** The winShmMutexHeld() must be true while reading or writing this list.
34466 ** All other fields are read/write. The winShm.pShmNode->mutex must be held
34495 int ofst, /* Offset to first byte to be locked/unlocked */
34591 ** the file must be truncated to zero length or have its header cleared.
34594 struct winShm *p; /* The connection to be opened */
34619 /* Look to see if there is an existing winShmNode that can be used.
34683 ** at pShmNode->pFirst. This must be done while holding the pShmNode->mutex
34711 winShm *p; /* The connection to be closed */
34926 ** zero, exit early. *pp will be set to NULL and SQLITE_OK returned.
35044 ** is obtained from malloc and must be freed by the calling
35063 ** Create a temporary file name in zBuf. zBuf must be big enough to
35188 ** (a) Exactly one of the READWRITE and READONLY flags must be set, and
35189 ** (b) if CREATE is set, then READWRITE must also be set, and
35190 ** (c) if EXCLUSIVE is set, then CREATE must also be set.
35191 ** (d) if DELETEONCLOSE is set, then CREATE must also be set.
35230 ** URIs with parameters. Hence, they can always be passed into
35368 ** Note that Windows does not allow a file to be deleted if some other
35372 ** file open, we will be unable to delete it. To work around this
35499 ** pathname into zOut[]. zOut[] will be at least pVfs->mxPathname
35701 ** cannot be found.
35743 ** return 0. Return 1 if the time and date cannot be found.
35766 ** it should be truncated. The return value of xGetLastError
35781 ** However if an error message is supplied, it will be incorporated
35868 ** may be set or cleared one at a time.
35876 ** but can be as large as 2 billion for a really big database.
35883 ** it will be aligned within the Bitvec struct. */
35887 ** Should be a power of 2, and ideally, evenly divide into BITVEC_USIZE.
35937 ** this would be 125. */
35941 /* For a BITVEC_SZ of 512, this would be 34,359,739. */
35997 ** This routine might cause sub-bitmaps to be allocated. Failing
36073 ** pBuf must be a pointer to at least BITVEC_SZ bytes of temporary storage
36134 ** Let V[] be an array of unsigned characters sufficient to hold
36135 ** up to N bits. Let I be an integer between 0 and N. 0<=I<N.
36136 ** Then the following macros can be used to set, clear, or test
36180 /* Allocate the Bitvec to be tested and a linear array of
36404 /* IMPLEMENTATION-OF: R-26000-56589 The xShutdown() method may be NULL. */
36417 ** The caller discovers how much space needs to be allocated by
36592 ** Drop a page from the cache. There must be exactly one reference to the
36690 ** it must be that pgno==0.
36755 ** Since there cannot be more than 2^31 distinct pages in a database,
36756 ** there cannot be more than 31 buckets required by the merge sorter.
36779 /* To get here, there need to be 2^(N_SORT_BUCKET) elements in
36913 ** and is therefore often faster. Mode 2 requires a mutex in order to be
36939 ** flag (bPurgeable) are set when the cache is created. nMax may be
36941 ** The PGroup mutex must be held when accessing nMax.
36952 /* Hash table of all pages. The following variables may only be accessed
37034 ** to be serialized already. There is no need for further mutexing.
37063 ** in pcache1 need to be protected via mutex.
37151 /* The group mutex must be released before pcache1Alloc() is called. This
37184 ** The pointer is allowed to be NULL, which is prudent. But it turns out
37226 ** presumably SQLITE_CONFIG_PAGECACHE was suppose to be sufficient
37250 ** The PCache mutex must be held when this function is called.
37294 ** The PGroup mutex must be held when this function is called.
37330 ** The PGroup mutex must be held when this function is called.
37365 ** The PCache mutex must be held when this function is called.
37414 ** not need to be freed.
37533 ** Whether or not a new page may be allocated by this function depends on
37544 ** depending on the value of parameter createFlag (which may be 0, 1 or 2).
37610 /* The pGroup local variable will normally be initialized by the
37840 ** by the current thread may be sqlite3_free()ed.
37909 ** can be intermixed with tests to see if a given rowid has been
37914 ** process has started, no new elements may be inserted.
37938 ** value added by the INSERT will not be visible to the second TEST.
37946 ** has to be allocated on an INSERT.) The cost of a TEST with a new
37980 ** chunks are kept on a linked list so that they can be deallocated
38011 ** It must be the case that N is sufficient to make a Rowset. If not
38015 ** allocation of entries available to be filled.
38094 ** assumed to each already be in sorted order.
38097 struct RowSetEntry *pA, /* First sorted list to be merged */
38098 struct RowSetEntry *pB /* Second sorted list to be merged */
38227 ** as deep as it needs to be in order to contain the entire list.
38271 ** routine may not be called again.
38360 /* Additional values that can be added to the sync_flags argument of
38491 ** Definition: A page of the database file is said to be "overwriteable" if
38531 ** are said to be "logically equivalent" if they give the same answer to
38533 ** pages can be changed arbitarily without effecting the logical equivalence
38538 ** journal is rolled back, the resulting database file will be logical
38548 ** of bytes from 24 through 39 inclusive will be changed prior to releasing
38590 ** pager may be in any one of the seven states shown in the following
38629 ** state - the file may or may not be locked and the database size is
38630 ** unknown. The database may not be read or written.
38633 ** * Any lock, or no lock at all, may be held on the database file.
38634 ** * The dbSize, dbOrigSize and dbFileSize variables may not be trusted.
38651 ** * A read transaction may be active (but a write-transaction cannot).
38653 ** * The dbSize variable may be trusted (even if a user-level read
38655 ** may not be trusted at this point.
38686 ** * The journal file may or may not be open.
38722 ** database file. In this state the transaction may be committed simply
38738 ** difficult to be sure that the in-memory pager state (cache contents,
38745 ** the contents of the page-cache may be left in an inconsistent state.
38746 ** At this point it would be dangerous to change back to READER state
38779 ** Condition (3) is necessary because it can be triggered by a read-only
38825 ** VFS call is successful. This way, the Pager.eLock variable may be set
38830 ** be a few redundant xLock() calls or a lock may be held for longer than
38834 ** from ERROR to OPEN state. At this point there may be a hot-journal file
38835 ** in the file-system that needs to be rolled back (as part of a OPEN->SHARED
38845 ** a hot-journal may be mistaken for a journal being created by an active
38858 ** Pager.eLock may only be set to UNKNOWN_LOCK when the pager is in
38930 ** In some (obscure) circumstances, this variable may also be set to
38954 ** (or may not) specify a master-journal name to be written into the
38966 ** Journal files that contain master journal pointers cannot be finalized
39009 ** dbSize is set based on the size of the database file, which may be
39026 ** and to determine whether or not pages need to be journalled before
39041 ** pager_truncate() is called unconditionally (which means there may be
39170 ** to roll the journal back, the database could be corrupted. The additional
39182 ** be correct. But by initializing the checksum to random value which
39204 ** the value of MEMDB will be a constant and the compiler will optimize
39222 ** This is so that expressions can be written as:
39260 /* State must be valid. */
39277 /* If the useJournal flag is clear, the journal-mode must be "OFF".
39278 ** And if the journal-mode is "OFF", the journal file must not be open.
39300 /* If changeCountDone is set, a RESERVED lock or greater must be held
39373 /* There must be at least one outstanding reference to the pager if
39390 ** is intended to be used within debuggers. For example, as an alternative
39439 ** A page needs to be written into the sub-journal if there exists one
39499 ** Unlock the database file to level eLock, which must be either NO_LOCK
39525 ** Lock the database file to level eLock, which must be either SHARED_LOCK,
39550 ** can be used with this pager. The optimization can be used if:
39553 ** a database page may be written atomically, and
39561 ** If the optimization cannot be used, 0 is returned. If it can be used,
39633 ** When this is called the journal file for pager pPager must be open.
39640 ** the caller. This should be sqlite3_vfs.mxPathname+1 (to ensure there is
39723 ** The journal file must be open when this function is called.
39738 ** not need to be synced following this operation.
39778 ** The journal file must be open when this routine is called. A journal
39799 assert( isOpen(pPager->jfd) ); /* Journal file must be open. */
39829 ** where this risk can be ignored:
39870 ** that will be implicitly filled in by the OS).
39873 ** be significantly slower than contiguously writing data to the file,
39875 ** (JOURNAL_HDR_SZ - 28) bytes that will not be used. So that is what
39880 ** bytes in size, more than one call to sqlite3OsWrite() may be required
39894 ** The journal file must be open when this is called. A journal header file
39906 ** If the journal header file appears to be corrupted, SQLITE_DONE is
39908 ** cannot be read from the journal file an error code is returned.
39921 assert( isOpen(pPager->jfd) ); /* Journal file must be open. */
39924 ** journal file is too small for there to be a header stored at this
39979 ** are within range. To be 'in range', both values need to be a power
40018 ** pPager at the current location. The master journal name must be the last
40086 ** will not be able to find the master-journal name to determine
40109 ** fail, since no attempt to allocate dynamic memory will be made.
40175 ** or not, any journal file left in the file-system will be treated
40225 /* The pager state may be changed from PAGER_ERROR to PAGER_OPEN here
40234 /* If Pager.errCode is set, the contents of the pager cache cannot be
40256 ** the error-code about to be returned by a pager API function. The
40265 ** cannot be trusted. This state can be cleared by completely discarding
40268 ** to be replayed to restore the contents of the database file (as if
40288 ** either a COMMIT or a ROLLBACK operation. This routine may be called
40301 ** transaction. Nor will it be considered to be a hot-journal by this
40316 ** file. An invalid journal file cannot be rolled back.
40344 ** or at least a RESERVED lock. This function may be called when there
40384 /* This branch may be executed with Pager.journalMode==MEMORY if
40386 ** file should be closed and deleted. If this connection writes to
40446 ** connection to obtain a shared lock on the pager (which may be this one)
40451 ** the pager to enter the ERROR state. Which will be cleared by the
40483 ** scenario is that one end or the other of the record will be changed.
40484 ** It is much less likely that the two ends of the journal record will be
40485 ** correct and the middle be corrupt. Thus, this "checksum" scheme,
40536 ** is successfully read from the (sub-)journal file but appears to be
40546 ** If this is a savepoint rollback, then memory may have to be dynamically
40597 ** it could cause invalid data to be written into the journal. We need to
40629 /* If the pager is in CACHEMOD state, then there must be a copy of this
40635 ** not be in the pager cache. Later: if a malloc() or IO error occurs
40636 ** during a Movepage() call, then the page may not be in the cache
40654 ** restore the database to its original form. Two conditions must be
40655 ** met before writing to the database files. (1) the database must be
40700 ** will be read from the database file, which may or may not be
40724 /* No page should ever be explicitly rolled back that is in use, except
40726 ** database active. However such a page may be rolled back as a result
40736 ** journal file, then its content must be as they were when the
40738 ** as clean, since there will be no need to write it out to the
40748 ** again within this transaction, it will be marked as dirty but
40749 ** the PGHDR_NEED_SYNC flag will not be set. It could then potentially
40750 ** be written out into the database file before its journal file
40785 ** file for a transaction involving two databases might be:
40789 ** A master journal file may only be deleted once all of its child
40800 ** If a child journal can be found that matches both of the criteria
40802 ** no such child journal can be found, file zMaster is deleted from
40811 ** the entire contents of the master journal file. This could be
40916 ** Or, it might might be the case that the file on disk is smaller than
40960 ** of the open database file. The sector size will be used used
41032 ** failure occurred while the journal was being written, it could be the
41035 ** the value of nRec computed from the file size would be too large. For
41038 ** If the nRec value is 0xffffffff it means that nRec should be computed
41041 ** in this case. But for things like temporary table (which will be
41054 ** that might be a hot journal. Or, it could be that the journal is
41082 ** present on disk, then the journal is not hot and does not need to be
41111 ** This indicates nothing more needs to be rolled back.
41139 ** chunk of the journal contains zero pages to be rolled back. But
41142 ** pages that need to be rolled back and that the number of pages
41143 ** should be computed based on the journal file size.
41185 ** so that no further harm will be done. Perhaps the next
41186 ** process to come along will be able to rollback the database.
41197 /* Following a rollback, the database file should be back in its original
41252 ** pPg->pData. A shared lock or greater must be held on the database
41292 ** that will never be a valid file version. dbFileVers[] is a copy
41293 ** of bytes 24..39 of the database. Bytes 28..31 should always be
41295 ** should be page numbers which are never 0xffffffff. So filling
41301 ** we should still be ok.
41379 ** the backups must be restarted.
41419 ** Hence, if page 1 appears anywhere on the list, it will be the first page.
41444 ** They will never be read by any client. So remove them from the pDirty
41478 ** This routine used to be called "pagerOpenSnapshot()" because it essentially
41485 int changed = 0; /* True if cache must be reset */
41548 ** that the file can be read.
41673 ** journal. The actual file might be larger than this in
41682 ** There might be records in the main journal that have a page number
41684 ** will be skipped automatically. Pages are added to pDone as they
41729 ** will be skipped. Out-of-range pages are also skipped.
41787 ** assurance that the journal will not be corrupted to the
41946 ** function may be called from within PagerOpen(), before the state
41996 ** during rollback and will be overwritten whenever a rollback
42080 ** This function may only be called when a read-transaction is open on
42112 ** may be invoked during, according to the comment above
42134 ** be necessary to write the current content out to the sub-journal
42138 ** dirty page were to be discarded from the cache via the pagerStress()
42141 ** this happened, the correct behaviour would be to restore the current
42144 ** sub-journal rolled back the content could not be restored and the
42164 ** truncation will be done when the current transaction is committed.
42210 ** a hot journal may be left in the filesystem but no error is returned
42231 ** file may be played back into the database. If a power failure occurs
42284 ** disk and can be restored in the event of a hot-journal rollback.
42291 ** be taken.
42337 ** mode, then the journal file may at this point actually be larger
42339 ** file happens to be a journal-header (written as part of the
42381 ** for garbage data to be appended to the file, the nRec field
42383 ** and never needs to be updated.
42431 ** be NULL, representing an empty list. In this case this function is
42436 ** is upgraded to an EXCLUSIVE lock. If the lock cannot be obtained,
42457 ** be obtained, SQLITE_BUSY is returned.
42468 ** is not possible for rc to be other than SQLITE_OK if this branch
42477 ** file size will be.
42625 ** page clean, the IO error code is returned. If the page cannot be
42646 ** is impossible for sqlite3PcacheFetch() to be called with createFlag==1
42648 ** be called in the error state. Nevertheless, we include a NEVER()
42676 ** the database image, it may need to be written to the sub-journal.
42690 ** If (X>Y), then when pagerStress is called page X will not be written
42691 ** out to the database file, but will be dropped from the cache. Then,
42693 ** data from the database file. This will be the copy of page X as it
42699 ** be restored to its current value when the "ROLLBACK TO sp" is
42727 ** in *ppPager. The pager should eventually be freed by passing it
42732 ** and used as the file to be cached. Temporary files are be deleted
42735 ** This can be used to implement an in-memory database.
42742 ** operation of the pager. It should be passed some bitwise combination
42783 ** may be a wrapper capable of caching the first portion of the journal
42826 ** the database being opened will be more than pVfs->mxPathname
42827 ** bytes in length. This means the database cannot be opened,
42828 ** as it will not be possible to open the journal file or even
42909 ** + The largest page size that can be written atomically.
43040 ** needs to be played back. According to this function, a hot-journal
43094 ** be dealt with by the playback routine. Ticket #3883.
43119 ** If there is, then we consider this journal to be hot. If not,
43120 ** it can be ignored.
43138 ** its has a zero header, that might be due to an I/O error, or
43139 ** it might be due to the race condition described above and in
43141 ** This might be a false positive. But if it is, then the
43172 ** discarded if they are found to be invalid.
43189 ** be OPEN or READER. READER is only possible if the pager is or was in
43209 ** database file, then it either needs to be played back or deleted.
43240 ** in exclusive-access mode the file descriptor will be kept open
43291 ** pager_unlock() routine will be called before returning to unlock
43292 ** the file. If the unlock attempt fails, then Pager.eLock must be
43301 ** assert_pager_state() would fail now, as it should not be possible
43302 ** to be in ERROR state when there are zero outstanding page
43330 ** There is a vanishingly small chance that a change will not be
43332 ** it can be neglected.
43426 ** a new page into the cache to be filled with the data read
43435 ** will not be journaled. This saves IO.
43491 ** be initialized. */
43511 ** page that does not need to be journaled. Nevertheless, be sure
43589 ** There must already be a RESERVED or EXCLUSIVE lock on the database
43598 ** If the journal file is already open (as it may be in exclusive mode),
43682 ** functions need be called.
43685 ** within this transaction will be opened as an in-memory file. This
43686 ** has no effect if the sub-journal is already opened (as it may be when
43723 ** busy-handler callback can be used when upgrading to the EXCLUSIVE
43739 ** file as well as into the page cache. Which would be incorrect in
43771 ** been started. The journal file may or may not be open at this point.
43790 /* The journal file needs to be opened. Higher level routines have already
43792 ** rollback journal might not yet be open. Open it now if this is the case.
43837 ** playback_one_page() will think that the page needs to be restored
43897 ** Mark a data page as writeable. This routine must be called before
43899 ** of this function and be careful not to change any page data unless
43929 ** a journal header to be written between the pages journaled by
43977 ** starting at pg1, then it needs to be set for all of them. Because
43980 ** before any of them can be written out to the database file.
44015 ** that page might be marked as dirty. This happens, for example, when
44049 ** page data. In this case the file will be updated when the current
44052 ** The isDirectMode flag may only be non-zero if the library was compiled
44151 ** This function may only be called while a write-transaction is active in
44176 ** of a master journal file that should be written into the individual
44177 ** journal file. zMaster may be NULL, which is interpreted as no master
44226 ** backup in progress needs to be restarted.
44269 ** in 'direct' mode. In this case the journal file will never be
44302 ** being discarded by the truncation must be written to the journal
44349 ** xSync() call will be changed to a no-op by the OS anyhow.
44392 ** be used as a hot-journal and the current transaction rolled back.
44395 ** truncating or partially zeroing it, so that it cannot be used
44405 /* This routine should not be called if a prior error has occurred.
44422 ** a hot-journal during hot-journal rollback, 0 changes will be made
44489 ** state to indicate that the contents of the cache may not be trusted.
44558 a[8] = 0; /* Used to be pPager->nOvfl */
44566 ** Parameter eStat must be either SQLITE_DBSTATUS_CACHE_HIT or
44658 ** The savepoint to release or rollback need not be the most recently
44696 /* Figure out how many savepoints will still be active after this
44721 ** the database file, so the playback operation can be skipped.
44798 ** There must be no references to the page previously located at
44799 ** pgno (which we call pPgOld) though that page is allowed to be
44807 ** A transaction must be active when this routine is called. It used to be
44815 ** pPg refers to will not be written to again within this transaction.
44832 /* In order to be able to rollback, an in-memory database must journal
44851 ** be possible to restore its contents when the "ROLLBACK TO one"
44869 /* If the journal needs to be sync()ed before page pPg->pgno can
44870 ** be written to, store pPg->pgno in local variable needSyncPgno.
44873 ** the journal needs to be sync()ed before database page pPg->pgno
44874 ** can be written to. The caller has already promised not to write to it.
44884 ** page pgno before the 'move' operation, it needs to be retained
44916 /* If needSyncPgno is non-zero, then the journal file needs to be
44919 ** "is journaled" bitvec flag has been set. This needs to be remedied by
44926 ** this transaction, it may be written to the database file before
44965 ** Get/set the locking-mode for this pager. Parameter eMode must be one
44988 ** Set the journal-mode for this pager. Parameter eMode must be one of:
44998 ** The change may be disallowed for the following reasons:
45011 /* The print_pager_state() routine is intended to be used by the debugger
45026 ** the logic there will never allow a temporary file to be changed
45031 /* Do allow the journalmode of an in-memory database to be set to
45239 ** The caller must be holding a SHARED lock on the database file to call
45288 ** EXCLUSIVE lock on the database file. If this cannot be obtained, an
45298 ** it may need to be checkpointed before the connection can switch to
45315 ** the database file, the log and log-summary files will be deleted.
45330 ** A read-lock must be held on the pager when this function is called. If
45389 ** A single WAL file can be used multiple times. In other words, the
45390 ** WAL can fill up with frames and then be checkpointed and then new
45474 ** for all subsequent read operations. New transactions can be appended
45484 ** WAL is large (multiple megabytes is typical) that scan can be slow,
45494 ** on a network filesystem. All users of the database must be able to
45498 ** be) reconstructed from the original WAL file. In fact, the VFS is required
45501 ** use an architecture-specific format; it does not have to be cross-platform.
45540 ** can be found by scanning the page-mapping sections of each index block
45552 ** index block. Let K be the 1-based index of the largest entry in
45554 ** always be exactly HASHTABLE_NPAGE (4096) and for the last index block
45555 ** K will be (mxFrame%HASHTABLE_NPAGE).) Unused slots of the hash table
45566 ** be at index iUnused. (iUnused might be less than iKey if there was
45569 ** iMax be the value between iKey and iUnused, closest to iUnused,
45578 ** average, only two or three slots in each index block need to be
45588 ** reader might be using some value K0 and a second reader that started
45590 ** and to the wal-index) might be using a different value K1, where K1>K0.
45592 ** the correct result. There may be entries in the hash table with
45593 ** K>K0 but to the first reader, those entries will appear to be unused
45619 ** that may be interpreted by this version of SQLite.
45635 ** of available reader locks and should be at least 3.
45657 ** The szPage value can be any power of 2 between 512 and 32768, inclusive.
45658 ** Or it can be 1 to represent a 65536-byte page. The latter case was
45683 ** WalIndexHdr.mxFrame. nBackfill can only be increased by threads
45697 ** The value of aReadMark[K] may only be changed by a thread that
45700 ** since the reader will be holding a shared lock on WAL_READ_LOCK(K).
45853 #define HASHTABLE_NPAGE 4096 /* Must be power of 2 */
45854 #define HASHTABLE_HASH_1 383 /* Should be prime */
45855 #define HASHTABLE_NSLOT (HASHTABLE_NPAGE*2) /* Must be a power of 2 */
45934 ** The argument to this macro must be of type u32. On a little-endian
45937 ** returns the value that would be produced by intepreting the 4 bytes
45952 ** nByte must be a positive multiple of 8.
45956 u8 *a, /* Content to be checksummed */
45957 int nByte, /* Bytes of content in a[]. Must be a multiple of 8. */
46130 ** A lock cannot be moved directly between shared and exclusive - it must go
46264 ** At most only the hash table containing pWal->hdr.mxFrame needs to be
46265 ** updated. Any later hash tables will be automatically cleared when
46350 /* If this is the first entry to be added to this hash-table, zero the
46389 ** via the hash table. This turns out to be a really, really expensive
46598 ** already be opened on connection pDbFd. The buffer that zWalName points
46601 ** A SHARED lock should be held on the database file when this function
46605 ** system would be badly broken.
46700 u32 iMin; /* Result pgno must be greater than iMin */
46740 ** The aContent[aLeft[X]] values will be unique for all X. And the
46741 ** aContent[aRight[X]] values will be unique too. But there might be
46794 ** aList[] are to be sorted so that for all J<K:
46818 ht_slot *aMerge = 0; /* List to be merged */
46869 ** Construct a WalInterator object that can be used to loop over all
46908 ** of memory will be freed before this function returns.
46977 ** The cache of the wal-index header must be valid to call this function.
46988 ** The amount of information copies from WAL to database might be limited
46990 ** that a concurrent reader might be using.
46999 ** in the WAL and can be recovered following a power-loss or hard reset.
47011 ** The caller must be holding sufficient locks to ensure that no other
47028 u32 mxSafeFrame; /* Max frame that can be backfilled */
47052 ** cannot be backfilled from the WAL.
47189 /* If an EXCLUSIVE lock can be obtained on the database file (using the
47246 ** be writing the header at the same time this procedure is trying to
47255 ** If the checksum cannot be verified return non-zero. If the header
47263 /* The first page of the wal-index must be mapped at this point. */
47306 ** If the wal-header appears to be corrupt, try to reconstruct the
47355 ** needs to be reconstructed. So run recovery to do exactly that.
47379 ** be retried.
47397 ** to the caller that the local paget cache is obsolete and needs to be
47399 ** be loaded and the pChanged parameter is unused.
47408 ** chance that SQLITE_PROTOCOL could be returned because of a run of really
47410 ** possibility is so small that it can be safely neglected, we believe.
47421 ** If the useWal parameter is 1 then the WAL will never be ignored and
47446 ** locks are held, so the locks should not be held for very long. But
47474 ** be running, convert BUSY to BUSY_RECOVERY. There is a race here
47475 ** which might cause WAL_RETRY to be returned even if BUSY_RECOVERY
47476 ** would be technically correct. But the race is benign since with
47477 ** WAL_RETRY this routine will be called again and will probably be
47486 ** must be zeroed before the requested page is returned.
47504 ** and can be safely ignored.
47589 ** date before proceeding. That would not be possible without somehow
47611 ** This routine used to be called sqlite3OpenSnapshot() and with good reason:
47620 ** needs to be flushed.
47654 ** the WAL and needs to be read out of the database.
47667 /* This routine is only be called from within a read transaction. */
47671 ** no data will be read from the wal under any circumstances. Return early
47696 ** loop of the following block is more stringent that would be required
47791 ** There can only be a single writer active at a time.
47961 ** In theory it would be Ok to update the cache of the header only
48020 void *pContent, /* Content to be written */
48045 PgHdr *pPage, /* The page of the frame to be written */
48218 ** be in use by existing readers is being overwritten.
48286 ** also be SQLITE_IOERR. */
48293 ** This has to be done before the call to walIndexReadHdr() below.
48295 ** If the writer lock cannot be obtained, then a passive checkpoint is
48335 ** the cache needs to be reset.
48376 ** be released. Return 1 if the transition is made and 0 if the
48391 /* pWal->readLock is usually set, but might be -1 if there was a
48504 ** fixed amount of payload can be carried directly on the database
48515 ** "no such page". The page size can be any power of 2 between 512 and 65536.
48516 ** Each page can be either a btree page, a freelist page, an overflow
48556 ** space in a page that can be consumed by a single cell for standard
48612 ** be easily added without having to defragment the page.
48620 ** increasing order. Because a freeblock must be at least 4 bytes in size,
48639 ** appears first. A variable-length integer may not be more than 9 bytes long.
48641 ** allows a 64-bit integer to be encoded in 9 bytes.
48691 ** small cells will be rare, but they are possible.
48705 ** header must be exactly 16 bytes including the zero-terminator so
48706 ** the string itself should be 15 characters long. If you change
48707 ** the header, then your custom library will not be able to read
48709 ** will not be able to read databases created by your custom library.
48730 ** walk up the BTree from any leaf to the root. Care must be taken to
48738 u8 isInit; /* True if previously initialized. MUST BE FIRST! */
48796 ** For some database files, the same underlying database cache might be
48804 ** The pBt pointer itself may not be changed while there exists cursors
48827 ** If the shared-data extension is enabled, there may be multiple users
48838 ** A single database file can be in use at the same time by two
48848 ** may not be modified once it is initially set as long as nRef>0.
48849 ** The pSchema field may be set once under BtShared.mutex and
48908 #define BTS_PAGESIZE_FIXED 0x0002 /* Page size can no longer be changed */
48934 ** this will be declared corrupt. This value is calculated based on a
48938 ** If a tree that appears to be taller than this is encountered, it is
48950 ** A single database file can be shared by two more database connections,
48951 ** but cursors cannot be shared. Each cursor is associated with a
48987 ** Cursor points to a valid entry. getPayload() etc. may be called.
48998 ** this state, restoreCursorPosition() can be called to attempt to
49029 ** then pgno is returned. So (pgno==PTRMAP_PAGENO(pgsz, pgno)) can be
49048 ** is moved, the pointer in its parent must be updated to point to the
49166 ** which need to be locked after p. If we cannot get a lock on
49175 ** connected by pNext and pPrev should be in sorted order by
49192 ** should already be set correctly. */
49199 /* In most cases, we should be able to acquire the lock we
49201 ** procedure that follows. Just be sure not to block.
49264 ** Btree. These entry points are used by incremental I/O and can be
49279 ** a statement since we will be comparing table and column names
49433 ** is empty, the offset should be 65536, but the 2-byte value stores zero.
49542 /* Figure out the root-page that the lock should be held on. For table
49577 **** This function may be used as part of assert() statements only. ****
49579 ** Return true if it would be illegal for pBtree to write into the
49611 ** SQLITE_OK if the lock may be obtained (by calling
49624 ** transaction on this file. And, obviously, for this to be so there
49625 ** must be an open write transaction on the file itself.
49636 ** requested lock may not be obtained.
49651 ** only be a single writer).
49671 ** by Btree handle p. Parameter eLock must be either READ_LOCK or
49701 /* This function should only be called on a sharable b-tree after it
49748 ** may be incorrectly cleared.
49781 ** than the writer must be about to drop to zero. In this case
49785 ** be zero already. So this next line is harmless in that case.
49851 ** table is about to be deleted. In this case invalidate all incrblob
49860 i64 iRow, /* The rowid that might be changing */
49892 ** such a page is not even journalled (as it will not be modified,
49897 ** be, if it is not at all meaningful?).
49905 ** may be lost. In the event of a rollback, it may not be possible
49943 ** Clear (destroy) the BtShared.pHasContent bitvec. This should be
50040 BtCursor *pCur, /* Cursor open on the btree to be searched */
50071 ** saved position info stored by saveCursorPosition(), so there can be
50165 /* The master-journal page number must never be used as a pointer map page */
50282 ** Within this file, the parseCell() macro can be called instead of
50283 ** btreeParseCellPtr(). Using some compilers, this will be faster.
50372 /* The value returned by this function should always be the same as
50806 /* To many cells for a single page. The page must be corrupt */
50815 ** past the end of a page boundary and causes SQLITE_CORRUPT to be
50855 /* Free blocks must be in ascending order. And the last byte of
50866 ** of the page, then the page must be corrupted. This check also
50938 ** means we have started to be concerned about content and the disk
50991 ** may remain unchanged, or it may be set to an invalid value.
51019 ** Release a MemPage. This should be called once for each prior
51049 /* pPage might not be a btree page; it might be an overflow page
51053 ** btreeInitPage() be called on every btree page so we make
51075 ** be exclusively in memory, or it might use a disk-based memory cache.
51076 ** Either way, the ephemeral database will be automatically deleted
51124 /* Only a BTREE_SINGLE database can be BTREE_UNORDERED */
51479 ** and the database cannot be corrupted if this program
51482 ** could be left in an inconsistent and unrecoverable state.
51540 ** The page size must be a power of 2 between 512 and 65536. If the page
51544 ** Page sizes are constrained to be a power of two so that the region
51553 ** and autovacuum mode can no longer be changed.
51737 /* If the write version is set to 2, this database should be accessed
51742 ** may not be the latest version - there may be a newer one in the log
51758 /* The maximum embedded fraction must be exactly 25%. And the minimum
51759 ** embedded fraction must be 12.5% for both leaf-data and non-leaf-data.
51761 ** version 3.6.0, we require them to be fixed.
51907 ** to access the database. A preexisting transaction may not be
51911 ** A write-transaction must be started before attempting any
51932 ** One or the other of the two processes must give way or there can be
51986 ** on page 1, the transaction cannot be opened. */
52044 /* If the db-size header field is incorrect (as it may be if an old
52064 ** the sub-journal is not already open, then it will be opened here.
52120 ** be modified, as follows:
52187 ** the journal needs to be sync()ed before database page pDbPage->pgno
52188 ** can be written to. The caller has already promised not to write to that
52220 ** pages need to be changed.
52224 ** the pointer map needs to be updated for the subsequent overflow page.
52281 ** incrVacuumStep() will be called a finite amount of times
52312 ** if nFin is non-zero. In that case, the free-list will be
52387 ** A write-transaction must be opened before calling this function.
52419 ** the database file should be truncated to during the commit process.
52434 Pgno nPtrmap; /* Number of PtrMap pages to be freed */
52435 Pgno iFree; /* The next page to be freed */
52486 ** causes a rollback journal to be created (if it does not already exist)
52488 ** the database can be restored to its original state by playing back
52500 ** the name of a master journal file that should be written into the
52542 ** may still be reading from the database. */
52572 ** be invoked prior to calling this routine. The sqlite3BtreeCommitPhaseOne()
52642 ** originally opened for writing and the cursor has not be disabled
52661 ** to other database connections that happen to be sharing
52665 ** All cursors using the same cache must be tripped
52669 ** save the state of the cursor. The cursor must be
52690 ** Rollback the transaction in progress. All cursors will be
52744 ** Start a statement subtransaction. The subtransaction can can be rolled
52752 ** can be rolled back without having to rollback the entire transaction.
52758 ** iStatement is 1. This anonymous savepoint can be released or rolled back
52787 ** SAVEPOINT_ROLLBACK, then iSavepoint may also be -1. In this case the
52824 ** If wrFlag==0, then the cursor can only be used for reading.
52825 ** If wrFlag==1, then the cursor can be used for reading or for
52827 ** are the conditions that must be met in order for writing to
52828 ** be allowed:
52835 ** the changes made by this write cursor would be visible to
52838 ** 3: The database must be writable (not on read-only media)
52840 ** 4: There must be an active transaction.
52925 ** Initialize memory that will be converted into a BtCursor object.
52927 ** The simple approach here would be to memset() the entire object
52929 ** do not need to be zeroed and they are large, so we can save a lot
52946 ** or negative rowids are very uncommon so this should not be a problem.
52958 ** return value indicates that the rowid cache is invalid and should be
53089 ** It might just as well be a procedure (returning void) but we continue
53122 MemPage **ppPage, /* OUT: MemPage handle (may be NULL) */
53136 ** out to be wrong, fall back to loading the data of page
53219 ** or be scattered out on multiple overflow pages.
53227 ** Once an overflow page-list cache has been allocated, it may be
53266 /* Check if data must be read/written to/from the btree page itself. */
53360 ** then data can be read directly from the database file into the
53404 ** "amt" bytes will be transfered into pBuf[]. The transfer
53424 ** "amt" bytes will be transfered into pBuf[]. The transfer
53456 ** into *pAmt. If *pAmt==0, then the value returned will not be
53460 ** and data to fit on the local page and for there to be no overflow
53461 ** pages. When that is so, this routine can be used to access the
53463 ** onto overflow pages, then accessPayload() must be used to reassemble
53514 ** or be destroyed on the next call to any Btree routine,
53516 ** Hence, a mutex on the BtShared should be held prior to calling
53548 ** if an intkey page appears to be the parent of a non-intkey page, or
53612 ** below to be untrue if the database file is corrupt. This can occur if
53644 ** If this function returns successfully, it may be assumed that the
53697 /* Assert that the root page is of the correct type. This must be the
53843 ** must be NULL. For index tables, pIdxKey is used and intKey
53868 BtCursor *pCur, /* The cursor to be moved */
53915 /* pPage->nCell must be greater than zero. If this is the root-page
53919 ** be the right kind (index or table) of b-tree page. Otherwise
53956 ** page is less than 16384 bytes and may be stored as a 2-byte
53981 ** this case the whole cell needs to be parsed, a buffer allocated
53983 ** buffer before VdbeRecordCompare() can be called. */
54051 ** TRUE will be returned after a call to sqlite3BtreeNext() moves
54096 ** to be invalid here. This can only occur if a second cursor modifies
54211 ** locate a page close to the page number "nearby". This can be used in an
54216 ** anywhere on the free-list, then it is guarenteed to be returned. This
54245 u8 searchList = 0; /* If the free-list must be searched for 'nearby' */
54249 ** the entire-list will be searched for that page.
54504 MemPage *pPage; /* Page being freed. May be NULL. */
54575 ** usableSize/4 - 8 entries will be reported as corrupt. In order
54656 /* 0 is not a legal page number and page 1 cannot be an
54658 ** file the database must be corrupt. */
54672 ** must not really be an overflow page and the database must be corrupt.
54675 ** enabled. If this 'overflow' page happens to be a page that the
54677 ** can be problematic.
54702 ** be constructed in this temporary area then copied into pPage->aData
54728 /* pPage is not necessarily writeable since pCell might be auxiliary
54861 ** "sz" must be the number of bytes in the cell.
54947 /* The cell should normally be sized correctly. However, when moving a
54949 ** wanted to be less than 4 but got rounded up to 4 on the leaf, then size
54950 ** might be less than 8 (leaf-size + pointer) on the interior node. Hence
55009 ** Add a list of cells to a page. The page should be initially empty.
55013 MemPage *pPage, /* The page to be assemblied */
55076 ** unbalanced. But odds are that we will be inserting new entries
55085 ** cell that will be inserted into pParent. Such a cell consists of a 4
55087 ** words, at most 13 bytes. Hence the pSpace buffer must be at
55105 ** may be inserted. If both these operations are successful, proceed.
55127 ** be marked as dirty. Returning an error code will cause a
55139 ** a variable length key value (which must be the same value as the
55281 ** The number of siblings of the page might be increased or decreased by
55285 ** might not actually be stored in MemPage.aData[]. This can happen
55289 ** In the course of balancing the page and its siblings, cells may be
55297 ** be rolled back.
55305 ** of the page-size, the aOvflSpace[] buffer is guaranteed to be large
55354 ** this overflow cell is present, it must be the cell with
55426 ** buffer. It will be copied out again as soon as the aSpace[] buffer
55490 ** that the original pages since the original pages will be in the
55582 ** right-most sibling might be nearly empty. This block of code attempts
55586 ** be so out of balance as to be illegal. For example, the right-most
55587 ** sibling might be completely empty. This adjustment is not optional.
55615 ** file is corrupt. The corruption will be detected and reported later
55680 ** not be a problem.
55758 ** bytes, then it may actually be smaller than this
55803 ** (it must be, as it was just reconstructed using assemblePage()). This
55804 ** is important if the parent page happens to be page 1 of the database
55815 ** be dealt with by this routine. Some of these have been set already, but
55829 ** cells stored on the sibling pages may need to be updated.
55832 ** overflow pages used by these cells may need to be updated
55837 ** to be updated.
55890 ** with any child or overflow pages need to be updated. */
56007 ** tree needs to be balanced, and if so calls the appropriate balancing
56087 ** calling balance_nonroot() (balance_deeper() may be called first,
56101 ** new pSpace buffer, so it may be safely freed here. */
56105 /* The pSpace buffer will be freed after the next call to
56130 ** define what table the record should be inserted into. The cursor
56144 ** cursor pCur is pointing at the existing copy of a row that is to be
56147 ** the cursor before the new key can be inserted.
56178 ** expecting an index b-tree, then the caller should be inserting blob
56180 ** intkey table, the caller should be inserting integer keys with a
56198 ** that the cursor is already where it needs to be and returns without
56268 ** row without seeking the cursor. This can be a big performance boost.
56339 ** making any modifications. Make the page containing the entry to be
56354 ** node. The cell from the leaf node needs to be moved to the internal
56383 ** tricky as the leaf node may be underfull, and the internal node may
56384 ** be either under or overfull. In this case run the balancing algorithm
56386 ** tree that we can be sure that any problem in the internal node has
56387 ** been corrected, so be it. Otherwise, after balancing the leaf node,
56438 ** out to be an overflow page, delete all overflow page-map caches
56450 /* The new root-page may not be allocated on a pointer-map page, or the
56460 ** be moved to the allocated page (unless the allocated page happens
56469 /* pgnoRoot is the page that will be used for the root-page of
56616 ** If pnChange is not NULL, then table iTable must be an intkey table. The
56654 ** page number that used to be the last root page in the file before
56736 ** be a root-page number, less one again if that is the
56772 ** This function may only be called if the b-tree connection already
56808 ** read-only and may not be written.
57306 ** A read-only or read-write transaction must be opened before calling
57315 Btree *p, /* The btree to be checked */
57566 ** Argument pCsr must be a cursor opened for writing on an
57570 ** Only the data content may only be modified, it is not possible to
57715 ** structure may be accessed via two groups of thread-safe entry points:
57726 ** be held when either of these functions are invoked.
57731 ** the values returned may be invalid. There is no way for a call to
57743 ** in connection handle pDb. If such a database cannot be found, return
57746 ** If the "temp" database is requested, it may need to be opened by this
57821 pDestDb, SQLITE_ERROR, "source and destination must be distinct"
57944 ** "MUST BE FIRST" for this purpose.
58026 ** one now. If a transaction is opened here, then it will be closed
58089 ** size may be different to the source page size.
58116 ** * The destination may need to be truncated, and
58119 ** pending-byte page in the source database may need to be
58137 ** occurs, the original database will be reconstructed from the
58255 ** Return the number of pages still to be backed up as of the most recent
58275 ** to be updated with the new data before the backup operation is
58309 ** valid and which are not, so the entire process needs to be restarted.
58326 ** must be active for both files.
58328 ** The size of file pTo may be reduced by this operation. If anything
58348 /* Set up an sqlite3_backup object. sqlite3_backup.pDestDb must be set
58363 ** checks this assumption - (p->rc) should be set to either SQLITE_DONE
58413 ** SQLITE_NOMEM may be returned if a malloc() fails during conversion
58447 ** be discarded.
58494 ** malloc(). In this way, we know that the memory is safe to be
58574 ** A MEM_Null value will never be passed to this function. This function is
58576 ** sqlite3_value_text()), or for ensuring that values to be used as btree
58599 ** is UTF-16le or UTF-16be do a translation.
58601 ** FIX ME: It would be better if sqlite3_snprintf() could do UTF-16.
58645 ** If the memory cell contains a string value that must be freed by
58730 ** If pMem represents a string value, its encoding might be changed.
58797 ** true and could be omitted. But we leave it in because other
58880 ** Delete any previous value and set the value to be a BLOB of length
58930 ** Delete any previous value and set the value of pMem to be an
59052 ** Change the value of a Mem to be a string or a BLOB.
59061 ** size limit) then no memory allocation occurs. If the string can be
59223 /* The collation sequence must be defined at this point, even if
59257 /* Both values must be blobs. Compare using memcmp(). */
59272 ** The pMem structure is assumed to be uninitialized. Any prior content
59328 ** parameter, which must be one of SQLITE_UTF16BE, SQLITE_UTF16LE or
59331 ** (2006-02-16:) The enc value can be or-ed with SQLITE_UTF16_ALIGNED.
59332 ** If that is the case, then the result must be aligned on an even byte
59389 ** be converted directly into a value, then the value is allocated and
59392 ** cannot be converted to a value, then *ppVal is set to NULL.
59413 /* op can only be TK_REGISTER if we have compiled with SQLITE_ENABLE_STAT3.
59505 sqlite3_value *v, /* Value to be set */
59562 ** set the sqlite3VdbeAddopTrace to 1 and all opcodes will be printed
59646 ** unchanged (this is so that any opcodes already allocated can be
59767 ** Create a new symbolic label for an instruction that has yet to be
59769 ** label can be used as the P2 value of an operation. Later, when
59775 ** always negative and P2 values are suppose to be non-negative.
59776 ** Hence, a negative P2 value is a label that has yet to be resolved.
59794 ** Resolve label "x" to be the address of the next instruction to
59795 ** be inserted. The parameter "x" must have been obtained from
59808 ** Mark the VDBE as one that can only be run one time.
59819 ** invoke directly or indirectly. It should be used as follows:
59887 ** to be rolled back). This condition is true if the main program or any
59898 ** ABORT may be thrown, or false otherwise. Return true if it does
59899 ** match, or false otherwise. This function is intended to be used as
59928 ** through all opcodes and hasAbort may be set incorrectly. Return
59992 ** Return the address of the next instruction to be inserted.
60002 ** to arrange for the returned array to be eventually freed using the
60111 ** the address of the next instruction to be coded.
60234 ** sqlite3_malloc, to be freed when the Vdbe is finalized.
60237 ** caller should not free the allocation, it will be freed when the Vdbe is
60353 ** routine, then a pointer to a dummy VdbeOp will be returned. That opcode
60358 ** dummy will never be written to. This is verified by code inspection and
60370 /* C89 specifies that the constant "dummy" will be
60502 ** attached databases that will be use. A mask of these databases
60517 ** If SQLite is compiled to support shared-cache mode and to be threadsafe,
60519 ** that may be accessed by the VM passed as an argument. In doing so it also
60532 ** statement p will ever use. Let N be the number of bits in p->btreeMask
60535 ** be a problem.
60925 void *pBuf, /* Where return pointer will be stored */
60929 int *pnByte /* If allocation cannot be made, increment *pnByte */
60954 /* There should be at least one opcode.
60987 ** After the VDBE has be prepped, it can be executed by one or more
60990 ** This function may be called exact once on a each virtual machine.
60995 ** the Vdbe becomes an independent entity and the Parse object can be
61030 ** cells (nMem+1-nCursor)..nMem, inclusive, will never be used by
61119 /* The pCx->pCursor will be close automatically, if it exists, by
61218 ** Set the number of result columns that will be returned by this SQL
61221 ** be called on an SQL statement before sqlite3_step().
61242 ** Set the name of the idx'th column to be returned by the SQL statement.
61243 ** zName must be a pointer to a nul terminated string.
61245 ** This call must be made after a call to sqlite3VdbeSetNumCols().
61247 ** The final parameter, xDel, must be one of SQLITE_DYNAMIC, SQLITE_STATIC
61249 ** to by zName will be freed by sqlite3DbFree() when the vdbe is destroyed.
61274 ** A read or write transaction may or may not be active on database handle
61286 /* With this option, sqlite3VtabSync() is defined to be simply
61294 ** be done before determining whether a master journal file is
61300 /* This loop determines (a) if the commit hook should be invoked and
61397 ** be "9" to avoid name collisions when using 8+3 filenames. */
61461 ** master journal file will be orphaned. But we cannot delete it,
61494 ** may be lying around. Returning an error code won't help matters.
61545 ** close it now. Argument eOp must be either SAVEPOINT_ROLLBACK or
61558 ** statement transaction that should be closed here. The only exception
61609 ** handle associated with the VM passed as an argument is about to be
61641 ** means the close did not happen and needs to be repeated.
61648 ** transaction will be committed or rolled back as a result of the
61690 ** transaction must be rolled back to restore the database to a
61771 ** be committed or rolled back. Call sqlite3VdbeCloseStatement() to
61843 ** as the first argument to its database handle (so that they will be
61869 ** After this routine is run, the VDBE should be ready to be executed
61886 /* If the VDBE has be run even partially, then transfer the error code
62222 ** nBuf is the amount of space left in buf[]. nBuf must always be
62224 ** a blob with a zero-filled tail, then buf[] might be just the right
62380 ** structure large enough to be used with sqlite3VdbeRecordUnpack() if
62386 ** be eventually freed by the caller using sqlite3DbFree(). Or, if the
62404 ** it by. If pSpace is already 8-byte aligned, nOff should be zero.
62466 ** greater than key2. The {nKey1, pKey1} key must be a blob
62468 ** key must be a parsed key such as obtained from
62476 ** equal, then the keys are considered to be equal and
62496 /* mem1.flags = 0; // Will be initialized by sqlite3VdbeSerialGet() */
62501 ** But in fact, mem1.u.i will never actually be used uninitialized, and doing
62518 /* Extract the values to be compared.
62561 ** are considered to be equal. Otherwise, the longer key is the
62562 ** larger. As it happens, the pPKey2 will always be the longer
62582 ** pCur might be pointing to text obtained from a corrupt database file.
62583 ** So the content cannot be trusted. Do appropriate checks on the content.
62596 ** than 2GiB are support - anything large must be database corruption.
62620 /* The last field of the index should be an integer - the ROWID.
62678 /* nCellKey will always be between 0 and 0xffffffff because of the say
62696 ** This routine sets the value to be returned by subsequent calls to
62743 ** The returned value must be freed by the caller using sqlite3ValueFree().
62797 ** to be recompiled. A statement needs to be recompiled whenever the
62866 ** back to its starting state so that it can be reused. A success code from
63122 /* We used to require that sqlite3_reset() be called before retrying
63125 ** be called automatically instead of throwing the SQLITE_MISUSE error.
63216 /* At this point local variable rc holds the value that should be
63219 ** be one of the values in the first assert() below. Variable p->rc
63220 ** contains the value that would be returned if sqlite3_finalize()
63484 ** using gcc, we force nullMem to be 8-byte aligned using the magical
63617 ** 0 The column name as it should be displayed for output
63792 ** for a statement, then the statement will be automatically recompiled,
63810 const void *zData, /* Pointer to the data to be bound */
63811 int nData, /* Number of bytes of data to be bound */
63945 ** Return the number of wildcards that can be potentially bound to.
64313 ** Push a new indentation level. Subsequent lines will be indented
64505 ** does not control the string, it might be deleted without the register
64524 ** Argument pMem points at a register that will be passed to a
64558 /* Find the memory cell that will be used to store the blob of memory
64569 ** be freed lazily via the sqlite3_release_memory() API. This
64650 char affinity, /* The affinity to be applied */
64708 static const char *const encnames[] = {"(X)", "(8)", "(16LE)", "(16BE)"};
64849 ** processor and returns that value. This can be used for high-res
64925 ** implement a loop. This test used to be on every single instruction,
64970 ** sqlite3VdbeMakeReady() must be called before this routine in order to
64987 ** immediately. There will be no error message but the p->rc field is
64990 ** A memory allocation error causes p->rc to be set to SQLITE_NOMEM and this
64995 ** After this routine has finished, sqlite3VdbeFinalize() should be
65124 const char *zAffinity; /* The affinity to be applied */
65136 Mem *pData0; /* First field to be combined into the record */
65226 } be;
65242 Mem *pData; /* MEM cell holding data for the record to be inserted */
65244 i64 iKey; /* The integer ROWID or key for the record to be inserted */
65336 int *aRoot; /* Array of rootpage numbers for tables to be checked */
65533 ** external allocations out of mem[p2] and set mem[p2] to be
65584 ** indentation conventions, each case should be indented by 6 spaces. But
65586 ** the switch statement will break with convention and be flush-left. Another
65593 ** will be filled with #defines that give unique integer values to each
65619 ** The next instruction executed will be
65693 ** or sqlite3_finalize(). For a normal halt, this should be SQLITE_OK (0).
65694 ** For errors, it can be some other value. If P1!=0 then P2 will determine
65999 ** transaction. It needs to be rolled back. */
66061 ** It is illegal for P1 and P3 to be the same register. Sometimes,
66225 ** be returned. This is used by the built-in min(), max() and nullif()
66249 ** Register P3 must not be one of the function inputs.
66252 ** function was determined to be constant at compile time. If the first
66255 ** sqlite3_set_auxdata() API may be safely retained until the next
66449 ** To force any register to be an integer, just add 0.
66461 ** Force the value in register P1 to be an integer. If the value
66462 ** in P1 is not an integer and cannot be converted into an integer
66488 ** has REAL affinity. Such column values may still be stored as
66504 ** Force the value in register P1 to be text.
66527 ** Force the value in register P1 to be a BLOB.
66550 ** Force the value in register P1 to be numeric (either an
66567 ** Force the value in register P1 to be an integer. If
66585 ** Force the value in register P1 to be a floating point number.
66611 ** The SQLITE_AFF_MASK portion of P5 must be an affinity character -
66641 ** If neither operand is NULL the result is the same as it would be if
66653 ** If neither operand is NULL the result is the same as it would be if
66755 ** Set the permutation used by the OP_Compare operator to be the array
67068 /* This block sets the variable u.an.payloadSize to be the total number of
67071 ** u.an.zRec is set to be the complete text of the record if it is available.
67074 ** might be available in the u.an.pC->aRow cache. Or it might not be.
67100 ** payload size, so it is impossible for u.an.payloadSize64 to be
67118 /* Consider the row to be NULL */
67179 ** Type entries can be between 1 and 5 bytes each. But 4 and 5 byte
67180 ** types use so much data space that there can only be 4096 and 32 of
67192 ** u.an.nField might be significantly less than the true number of columns
67193 ** in the table, and in that case, 5*u.an.nField+3 might be smaller than u.an.offset.
67196 ** to be oversized. Offset is limited to 98307 above. But 98307 might
67199 ** will likely be much smaller since u.an.nField will likely be less than
67259 ** or if the end of the last field appears to be past the end of the
67260 ** record, or if the end of the last field appears to be before the end
67261 ** of the record (when all fields present), then we must be dealing
67329 ** string indicates the column affinity that should be used for the nth
67334 const char *zAffinity; /* The affinity to be applied */
67358 ** P4 may be a string that is P2 characters long. The nth character of the
67359 ** string indicates the column affinity that should be used for the nth
67377 Mem *pData0; /* First field to be combined into the record */
67433 /* Only pure zero-filled BLOBs can be input to this Opcode.
67453 ** be one of the input registers (because the following call to
67531 ** transaction, then there cannot be any savepoints.
67540 /* A new savepoint cannot be created if there are active write
67756 ** transaction might also be rolled back if an error is encountered.
67767 ** write transaction must be started before any changes can be made to the
67773 ** throw an ABORT exception), a statement transaction may also be opened.
67777 ** VDBE to be rolled back after an error without having to roll back the
67819 ** counter. If the statement transaction needs to be rolled back,
67820 ** the value of this counter needs to be restored too. */
67835 ** There must be a read-lock on the database (either a transaction
67836 ** must be started or there must be an open cursor) before
67866 ** A transaction must be started before executing this opcode.
67914 ** to be executed (to establish a read lock) before this opcode is
67946 ** v-table would have to be ready for the sqlite3_vtab structure itself
67947 ** to be invalidated whenever sqlite3_step() is called from within
67967 ** values need not be contiguous but all P1 values should be small integers.
67968 ** It is an error for P1 to be negative.
67973 ** There will be a read lock on the database whenever there is an
67982 ** The P4 value may be either an integer (P4_INT32) or a pointer to
67996 ** The P4 value may be either an integer (P4_INT32) or a pointer to
68004 ** in read/write mode. For a given table, there can be one or more read-only
68108 ** The P5 parameter can be a mask of the BTREE_* flags defined
68117 ** by this opcode will be used for automatically created transient
68201 ** row output from the sorter so that the row can be decomposed into
68205 ** P3 is the number of fields in the records that will be stored by
68313 /* The input value in P3 might be of any type: integer, real, string,
68314 ** blob, or NULL. But it needs to be an integer before we can do
68321 /* If the P3 value could not be converted into an integer without
68325 /* If the P3 value cannot be converted into any kind of a number,
68330 /* If we reach this point, then the P3 value must be a floating
68335 /* The P3 value is too large in magnitude to be expressed as an
68421 /* u.bb.res might be negative because the table is empty. Check to
68566 ** that make up an unpacked index key that can be used with cursor P1.
68567 ** The value of N can be inferred from the cursor. N includes the rowid
68569 ** or may not be the same as R.
68584 #if 0 /* local variables moved into u.be */
68592 #endif /* local variables moved into u.be */
68595 u.be.aMx = &aMem[pOp->p4.i];
68602 u.be.pCx = p->apCsr[pOp->p1];
68603 assert( u.be.pCx->deferredMoveto==0 );
68604 u.be.pCx->seekResult = 0;
68605 u.be.pCx->cacheStatus = CACHE_STALE;
68606 u.be.pCrsr = u.be.pCx->pCursor;
68609 u.be.nField = u.be.pCx->pKeyInfo->nField;
68610 for(u.be.ii=0; u.be.ii<u.be.nField; u.be.ii++){
68611 if( u.be.aMx[u.be.ii].flags & MEM_Null ){
68613 u.be.pCrsr = 0;
68617 assert( (u.be.aMx[u.be.nField].flags & MEM_Null)==0 );
68619 if( u.be.pCrsr!=0 ){
68621 u.be.r.pKeyInfo = u.be.pCx->pKeyInfo;
68622 u.be.r.nField = u.be.nField + 1;
68623 u.be.r.flags = UNPACKED_PREFIX_SEARCH;
68624 u.be.r.aMem = u.be.aMx;
68626 { int i; for(i=0; i<u.be.r.nField; i++) assert( memIsValid(&u.be.r.aMem[i]) ); }
68629 /* Extract the value of u.be.R from register P3. */
68631 u.be.R = pIn3->u.i;
68636 rc = sqlite3BtreeMovetoUnpacked(u.be.pCrsr, &u.be.r, 0, 0, &u.be.pCx->seekResult);
68637 if( (u.be.r.flags & UNPACKED_PREFIX_SEARCH) || u.be.r.rowid==u.be.R ){
68640 pIn3->u.i = u.be.r.rowid;
68725 ** allowed to be less than this value. When this value reaches its maximum,
68832 assert( pOp->p3==0 ); /* We cannot be in random rowid mode if this is
68873 ** be a MEM_Int.
68894 ** may be NULL. If it is not NULL, then the update-hook
68914 Mem *pData; /* MEM cell holding data for the record to be inserted */
68916 i64 iKey; /* The integer ROWID or key for the record to be inserted */
68985 ** The cursor will be left pointing at either the next or the previous
68987 ** the next Next instruction will be a no-op. Hence it is OK to delete
68993 ** P1 must not be pseudo-table. It has to be a real table with
68997 ** pointing to. The update hook will be invoked, if it exists.
69013 /* If the update-hook will be invoked, set u.bi.iKey to the rowid of the
69025 ** to the row to be deleted and the sqlite3VdbeCursorMoveto() operation
69110 ** If the P1 cursor must be pointing to a valid row (not a NULL row)
69120 ** If the P1 cursor must be pointing to a valid row (not a NULL row)
69193 ** P1 can be either an ordinary table or a virtual table. There used to
69194 ** be a separate OP_VRowid opcode for use with virtual tables, but this
69302 ** rewinding so that the global variable will be incremented and
69364 ** The P1 cursor must be for a real table, not a pseudo-table.
69381 ** The P1 cursor must be for a real table, not a pseudo-table.
69439 ** insert is likely to be an append.
69524 ** the end of the index key pointed to by cursor P1. This integer should be
69570 ** the result is false whereas it would be true with IdxGT.
69631 ** P3==1 then the table to be clear is in the auxiliary database file
69635 ** might be moved into the newly deleted root page in order to keep all
69692 ** P2==1 then the table to be clear is in the auxiliary database file
69695 ** If the P3 value is non-zero, then the table referred to must be an
69799 /* Used to be a conditional */ {
69832 ** the analysis to be used when preparing all subsequent queries.
69886 ** At most reg(P3) errors will be reported.
69902 int *aRoot; /* Array of rootpage numbers for tables to be checked */
69997 ** must have P4==0, the final set P4=-1. P4 must be either -1 or
70004 ** never be tested for, and (c) when a value that is part of set X is
70084 ** SubProgram (if the trigger may be executed with more than one different
70103 ** is already allocated. Otherwise, it must be initialized. */
70197 ** Increment a "constraint counter" by P2 (P2 may be negative or positive).
70451 ** Change the journal mode of database P1 to P3. P3 must be one of the
70514 ** file. An EXCLUSIVE lock may still be held on the database file
70557 ** machines to be created and run. It may not be called from within
70621 ** used to generate an error message if the lock cannot be obtained.
70643 ** P4 may be a pointer to an sqlite3_vtab structure. If so, call the
70648 ** code will be set to SQLITE_LOCKED.
70739 ** P3. Register P3+1 stores the argc parameter to be passed to the
70744 ** A jump is made to P2 if the result set after filtering would be empty.
70954 ** row. This can be NULL to have the virtual table select the new
71099 ** The cases of the switch statement above this line should all be indented
71246 ** be set to point to a buffer containing an error message. It is the
71424 ** key columns must be indexed. The check below will pick up this
71472 /* Make sure a mutex is held on the table to be accessed */
71686 ** a VdbeCursor to sort large numbers of keys (as may be required, for
71704 ** all PMAs currently stored on disk must be merged together. This comment
71748 ** be advanced to the next key in its segment. Say the next key is
71971 ** be less than key2. Even if key2 also contains NULL values.
72303 /* See if the contents of the sorter should now be written out. They
72404 ** These iterators will be incrementally merged as the VDBE layer calls
72576 ** be used to service read() and write() requests. The actual file
72668 const void *zBuf, /* Take data to be written from here */
72853 ** The cursor can be either for reading or writing.
72865 sqlite3_io_methods *pMethod; /* Parent class. MUST BE FIRST */
72922 const void *zBuf, /* Take data to be written from here */
72930 /* An in-memory journal file should only ever be appended to. Random
73000 ** part of SQLite causes Sync to be called by mistake.
73089 ** The return value from the callback should be one of the WRC_*
73230 ** TK_AS operator. The TK_AS operator causes the expression to be
73234 ** column reference is so that the column reference will be recognized as
73295 ** allowing it to be repopulated by the memcpy() on the following line.
73338 ** The zDb variable is the name of the database (the "X"). This value may be
73340 ** can be used. The zTable variable is the name of the table (the "Y"). This
73341 ** value can be NULL if zDb is also NULL. If zTable is NULL it
73343 ** can be used.
73345 ** If the name cannot be resolved unambiguously, leave an error message
73366 assert( pNC ); /* the name context cannot be NULL. */
73367 assert( zCol ); /* The Z in X.Y.Z cannot be NULL */
73573 ** bit 0 to be set. Column 1 sets bit 1. And so forth. If the
73864 ** same integer value that would be used in the SQL statement to indicate
73923 "%r %s BY term out of range - should be "
74035 ExprList *pOrderBy, /* The ORDER BY or GROUP BY clause to be processed */
74079 ** an appropriate error message might be left in pParse. (OOM errors
74153 /* Normally sqlite3SelectExpand() will be called first and will have
74155 ** an expression, sqlite3ResolveExprNames() will be called without a
74213 ** SELECT statement pItem->pSelect must be correlated. Set the
74239 /* If a HAVING clause is present, then there must be a GROUP BY clause.
74251 ** Minor point: If this is the case, then the expression will be
74363 Expr *pExpr /* The expression to be analyzed. */
74498 ** Set the collating sequence for expression pExpr to be the collating
74556 ** type affinity that should be used for the comparison operator.
74583 ** be applied to both operands prior to doing the comparison.
74605 ** if the index with affinity idx_affinity may be used to implement
74621 ** Return the P5 value that should be used for a binary comparison
74631 ** Return a pointer to the collation sequence that should be used by
74639 ** Argument pRight (but not pLeft) may be a null pointer. In this case,
74796 ** appear to be quoted. If the quotes were of the form "..." (double-quotes)
74800 ** can be translated into a 32-bit integer, then the token is not
74806 sqlite3 *db, /* Handle for sqlite3DbMallocZero() (may be null) */
74808 const Token *pToken, /* Token argument. Might be NULL */
74855 sqlite3 *db, /* Handle for sqlite3DbMallocZero() (may be null) */
74857 const char *zToken /* Token argument. Might be NULL */
74903 ** One or both of the subtrees can be NULL. Return a pointer to the new
74965 ** sure "nnn" is not too be to avoid a denial of service attack when
75000 sqlite3ErrorMsg(pParse, "variable number must be between ?1 and ?%d",
75089 ** (2) the EP_xxx flags that indicate what the structure size should be.
75096 ** The size of the structure can be found by masking the return value
75097 ** of this routine with 0xfff. The flags can be found by masking the
75261 ** be deleted (by being passed to their respective ...Delete() routines)
75265 ** sqlite3IdListDup(), and sqlite3SrcListDup() can not be further expanded
75272 ** truncated version of the usual Expr structure that will be stored as
75310 ** sqlite3SelectDup(), can be called. sqlite3SelectDup() is sometimes
75363 ** necessarily a power of two, sqlite3IdListAppend() may not be called
75417 ExprList *pList, /* List to which to append. Might be NULL */
75418 Expr *pExpr /* Expression to be appended. Might be NULL */
75456 ** pList might be NULL following an OOM error. But pName should never be
75463 Token *pName, /* Name to be added */
75464 int dequote /* True to cause the name to be dequoted */
75481 ** pList might be NULL following an OOM error. But pSpan should never be
75488 ExprSpan *pSpan /* The span to be added */
75560 /* Consider functions to be constant if all their arguments are constant
75667 ** Return FALSE if there is no chance that the expression can be NULL.
75669 ** If the expression might be NULL or if the expression is too complex
75673 ** when we know that a value cannot be NULL. Hence, a false positive
75674 ** (returning TRUE when in fact the expression can never be NULL) might
75675 ** be a small performance hit but is otherwise harmless. On the other
75676 ** hand, a false negative (returning FALSE when the result could be NULL)
75701 ** can be omitted.
75705 const Expr *pExpr, /* Only generate OP_IsNull if this expr can be NULL */
75715 ** Return TRUE if the given expression is a constant which would be
75720 ** can be omitted. When in doubt return FALSE. A false negative
75744 assert( p->iTable>=0 ); /* p cannot be part of a CHECK constraint */
75818 ** It's job is to find or create a b-tree structure that may be used
75831 ** An existing b-tree may only be used if the SELECT is of the simple
75836 ** If the prNotFound parameter is 0, then the b-tree will be used to iterate
75838 ** epheremal table must be used unless the selected <column> is guaranteed
75839 ** to be unique - either because it is an INTEGER PRIMARY KEY or it
75842 ** If the prNotFound parameter is not 0, then the b-tree will be used
75844 ** be used unless <column> is an INTEGER PRIMARY KEY or an index can
75845 ** be found with <column> as its left-most column.
75875 int mustBeUnique = (prNotFound==0); /* True if RHS must be unique */
75880 /* Check to see if an existing table or index can be used to
75923 ** be used in place of a temp-table, it must be ordered according
75927 /* Check that the affinity that will be used to perform the
75999 ** to be of the form "<rowid> IN (?, ?, ?)", where <rowid> is a reference
76032 /* This code must be run in its entirety every time it is encountered
76174 /* If this has to be a scalar SELECT. Generate code to put the
76296 ** "x IN (...)" expression must be either 0 or NULL. If the set
76371 ** The z[] string will probably not be zero-terminated. But the
76372 ** z[n] character is guaranteed to be something that does not look
76458 ** that the object will never already be in cache. Verify this guarantee.
76557 ** register might be in the cache in multiple places, so be sure to
76597 ** There must be an open cursor to pTab in iTable when this routine
76701 ** be stored in target. The result might be stored in some other
77174 /* If the column has REAL affinity, it may currently be stored as an
77193 ** Form A is can be transformed into the equivalent form B as follows:
77282 "RAISE() may only be used within a trigger-program");
77310 ** If the register is a temporary register that can be deallocated,
77365 ** other place where expressions can be converted into TK_REGISTER is
77646 ** or OP_Variable that does not need to be placed in a
77650 ** expressions that need to be placed in a particular register.
77778 ExprList *pList, /* The expression list to be coded */
78133 ** identical, we return 2 just to be safe. So if this routine
78136 ** can be sure the expressions are the same. In the places where
78176 ** only consequence will be disabled optimizations. But this routine
78180 ** Two NULL pointers are considered to be the same. But a NULL pointer
78298 ** Convert the pExpr to be a TK_AGG_COLUMN referring to that
78313 ** to be ignored */
78371 ** for variables that need to be added to the pParse->aAgg[] array.
78374 ** This routine should only be called after the expression has been
78538 ** and its length in 'len' (to be used next iteration of this loop).
78660 ** and its length in 'len' (to be used next iteration of this loop).
78671 ** to be met.
78673 ** Note that ON cannot be a database, table or column name, so
78744 ** Generate the text of a WHERE expression which can be used to select all
78760 ** Generate the text of a WHERE expression which can be used to select all
78795 ** the time the generated code is executed. This can be different from
78841 ** Parameter zName is the name of a table that is about to be altered
78844 ** in pParse->zErr (system tables may not be altered) and returns non-zero.
78850 sqlite3ErrorMsg(pParse, "table %s may not be altered", zName);
78915 sqlite3ErrorMsg(pParse, "view %s may not be altered", pTab->zName);
79132 ** column must not be NULL.
79211 ** Routine sqlite3AlterFinishAddColumn() will be called to complete
79232 sqlite3ErrorMsg(pParse, "virtual tables may not be altered");
79320 ** Additional tables might be added in future releases of SQLite.
79333 ** which the index belongs. In each such row, the stat column will be
79341 ** a K-column index, there will be K+1 integers in the stat column. If
79342 ** the index is unique, then the last integer will be 1.
79344 ** The list of integers in the stat column can optionally be followed
79346 ** must be separated from the last integer by a single space. If the
79366 ** evenly spaced points along the index. Let the number of samples be S
79367 ** (10 in the standard build) and let C be the number of rows in the index.
79399 ** integer will be the number of prior index entires that are distinct in
79400 ** the left-most column. The second integer will be the number of prior index
79402 ** will be the number of prior index entries that are distinct in the first
79406 ** There can be an arbitrary number of sqlite_stat3 entries per index.
79424 ** Argument zWhere may be a pointer to a buffer containing a table name,
79425 ** or it may be a NULL pointer. If it is not NULL, then all entries in
79469 ** because the OpenWrite opcode below will be needing it. */
79726 Table *pTab, /* Table whose indices are to be analyzed */
79808 /* Open a cursor to the index to be analyzed. */
80001 ** be loaded into internal hash tables where is can be used.
80036 ** in pTab that should be analyzed.
80065 ** Form 1 causes all indices in all attached databases to be analyzed.
80141 ** argv[1] = name of the index (might be NULL)
80363 ** code may be ignored.
80455 ** will fail because neither abc or def can be resolved.
80551 ** or may not be initialised.
80839 ** Initialize a DbFixer structure. This routine must be called prior
80846 DbFixer *pFix, /* The fixer to be initialized */
80847 Parse *pParse, /* Error messages will be written here */
80848 int iDb, /* This is the database that must be used */
80907 Select *pSelect /* The SELECT statement to be fixed to one database */
80928 Expr *pExpr /* The expression to be fixed to one database */
80946 ExprList *pList /* The expression to be fixed to one database */
80963 TriggerStep *pStep /* The trigger step be fixed to one database */
81001 ** All of the code in this file may be omitted by defining a single
81009 ** The access authorization function is be called during the compilation
81046 ** and attempts to write the column will be ignored.
81107 ** The pExpr should be a TK_COLUMN expression. The table referred to
81205 ** zArg3 argument to authorization callbacks will be zContext until
81261 ** be parsed. Initialize the pParse structure as needed.
81274 int iDb; /* The database containing the table to be locked */
81275 int iTab; /* The root page of the table to be locked */
81283 ** The table to be locked has root page iTab and is found in database iDb.
81284 ** A read or a write lock can be taken depending on isWritelock.
81293 int iTab, /* Root page number of the table to be locked */
81295 const char *zName /* Name of the table to be locked */
81355 ** Note that if an error occurred, it might be the case that
81470 assert( pParse->nested<10 ); /* Nesting should only be of limited depth */
81531 const char *zDbase /* Name of the database. Might be NULL */
81615 /* Justification of ALWAYS(); The index must be on the list of
81651 ** since TEMP might be holding triggers that reference tables in the
81803 ** is obtained from sqliteMalloc() and must be freed by the calling
81842 ** -1 if the named db cannot be found.
81942 ** flag is true if the table should be stored in the auxiliary database
81949 ** routines will be called to add more information to this record.
81983 ** set to the index of the database that the table or view is to be
81989 /* If creating a temp table, the name may not be qualified. Unless
81991 sqlite3ErrorMsg(pParse, "temporary table name must be unqualified");
82034 ** and types will be used, so there is no need to test for namespace
82088 ** indices to be created and the table record must come before the
82089 ** indices. Hence, the record number for the table must be allocated
82122 ** The record created does not contain anything yet. It will be replaced
82213 ** be called next to set pCol->affinity correctly.
82318 ** Default value expressions must be constant. Raise an exception if this
82360 ** field of the table under construction to be the index of the
82369 ExprList *pList, /* List of field names to be indexed */
82497 ** invokes the collation factory if the named collation cannot be found
82531 ** the schema to change multiple times and for the cookie to be
82551 ** The estimate is conservative. It might be larger that what is
82601 ** from sqliteMalloc() and must be freed by the calling function.
82777 ** suitable state to query for the column names and types to be used
82783 ** be redundant.
82933 ** This will force all the Expr.token.z values to be dynamically
83020 ** to be permanent. So the computation is done on a copy of the SELECT
83096 ** because the first match might be for one of the deleted indices
83100 ** in order to be certain that we got the right one.
83170 /* If the database may be auto-vacuum capable (if SQLITE_OMIT_AUTOVACUUM
83174 ** to be destroyed is relocated by an earlier OP_Destroy. i.e. if the
83181 ** and root page 5 happened to be the largest root-page number in the
83182 ** database, then root page 5 would be moved to page 4 by the
83286 ** dropped. Triggers are handled seperately because a trigger can be
83310 ** pName is the name of the table to be dropped.
83378 sqlite3ErrorMsg(pParse, "table %s may not be dropped", pTab->zName);
83566 ** the index already exists and must be cleared before being refilled and
83659 ** we can be sure that no other temp registers have been allocated
83680 ** and pTblList is the name of the table that is to be indexed. Both will
83681 ** be NULL for a primary key or an index that is created to satisfy a
83683 ** as the table to be indexed. pParse->pNewTable is a table that is
83686 ** pList is a list of columns to be indexed. pList will be NULL if this
83696 Token *pName1, /* First part of index name. May be NULL */
83697 Token *pName2, /* Second part of index name. May be NULL */
83699 ExprList *pList, /* A list of columns to be indexed */
83707 Table *pTab = 0; /* Table to be indexed */
83708 Index *pIndex = 0; /* The index to be created */
83724 assert( pStart==0 || pEnd!=0 ); /* pEnd must be non-NULL if pStart is */
83734 ** Find the table that is to be indexed. Return early if not found.
83784 sqlite3ErrorMsg(pParse, "table %s may not be indexed", pTab->zName);
83789 sqlite3ErrorMsg(pParse, "views may not be indexed");
83795 sqlite3ErrorMsg(pParse, "virtual tables may not be indexed");
83932 /* Scan the names of the columns of the table to be indexed and
83938 ** the column will ever be used by the optimizer. Note that using the
83939 ** same column more than once cannot be an error because that would
83940 ** break backwards compatibility - it needs to be a warning.
84080 ** step can be skipped.
84173 ** to be used when we have not run the ANALYZE command.
84180 ** of the index. And so forth. It must always be the case that
84186 ** how aiRowEst[] should be initialized. The numbers generated here
84236 "or PRIMARY KEY constraint cannot be dropped", 0);
84286 ** might be the same as the pArray parameter or it might be a different
84291 void *pArray, /* Array of objects. Might be reallocated */
84316 ** need be.
84380 ** the iStart value would be 0. The result then would
84381 ** be: nil, nil, nil, A, B.
84384 ** db->mallocFailed flag will be set to true.
84388 SrcList *pSrc, /* The SrcList to be enlarged */
84436 ** need be. A new entry is created in the SrcList even if pTable is NULL.
84439 ** SrcList might be the same as the SrcList that was input or it might be
84465 ** Both pTable and pDatabase are assumed to be quoted. They are dequoted
84616 ** expects the join operator to be on the right operand. This routine
84756 ** It is important that all schema cookies be verified and all
84757 ** read transactions be started before anything else happens in
84758 ** the VDBE program. But this routine can be called after much other
84766 ** starts the transactions will be coded and the OP_Goto P2 value
84767 ** will be made to point to that subroutine. The generation of the
84771 ** schema on any databases. This can be used to position the OP_Goto
84772 ** early in the code, before we know if any database tables will be used.
84823 ** be set for operations that might fail (due to a constraint) part of
84826 ** can be checked before any changes are made to the database, it is never
84827 ** necessary to undo a write and the checkpoint should not be set.
84841 ** be necessary to undo the completed writes.
84951 ** Form 1 causes all indices in all attached databases to be rebuilt.
84958 CollSeq *pColl; /* Collating sequence to be reindexed, or NULL */
84965 Token *pObjName; /* Name of the table or index to be reindexed */
85007 sqlite3ErrorMsg(pParse, "unable to identify the object to be reindexed");
85012 ** Return a dynamicly allocated KeyInfo structure that can be used
85095 ** collation function in the best encoding but there may be other versions
85124 ** The return value is either the collation sequence to be used in database
85126 ** sequence can be found.
85191 ** prefferred for UTF-8, the second UTF-16le, and the third UTF-16be.
85221 ** return the pColl pointer to be deleted (because it wasn't added
85246 ** cannot be found.
85279 ** 2: A variable arguments function that uses UTF-16BE when UTF-16LE is
85285 ** prefers UTF-16LE when UTF-16BE is requested, or vice versa.
85363 ** any number of arguments will be returned.
85370 ** number of arguments may be returned even if the eTextRep flag does not
85576 sqlite3ErrorMsg(pParse, "table %s may not be modified", pTab->zName);
85594 ** set of rows in the view that are to be added to the ephemeral table.
85599 Expr *pWhere, /* Optional WHERE clause to be added */
85641 Expr *pWhere, /* The WHERE clause. May be null */
85642 ExprList *pOrderBy, /* The ORDER BY clause. May be null */
85643 Expr *pLimit, /* The LIMIT clause. May be null */
85644 Expr *pOffset, /* The OFFSET clause. May be null */
85665 /* if pLimit is null, pOffset will always be null as well. */
85732 Expr *pWhere /* The WHERE clause. May be null */
85735 Table *pTab; /* The table from which records will be deleted */
85761 /* Locate the table which we want to delete. This table has to be
85763 ** will be calling are designed to work with multiple tables and expect
85856 ** API function sqlite3_count_changes) to be set incorrectly. */
85877 /* Collect rowids of every row to be deleted.
85970 ** single table to be deleted.
85972 ** The VDBE must be in a particular state when this routine is called.
85976 ** to be deleted, must be opened as cursor number $iCur.
85978 ** 2. Read/write cursors for all indices of pTab must be open as
85981 ** 3. The record number of the row to be deleted must be stored in
85989 Table *pTab, /* Table containing the row to be deleted */
86024 /* Populate the OLD.* pseudo-table register array. These values will be
86038 /* Seek the cursor to the row to be deleted again. It may be that
86081 ** The VDBE must be in a particular state when this routine is called.
86085 ** to be deleted, must be opened as cursor number "iCur".
86087 ** 2. Read/write cursors for all indices of pTab must be open as
86090 ** 3. The "iCur" cursor must be pointing to the row that is to be
86095 Table *pTab, /* Table containing the row to be deleted */
86112 ** regOut. The key with be for index pIdx which is an index on pTab.
86191 ** Indicate that the accumulator load should be skipped on this
86318 ** something that can be converted into a number, we have:
86320 ** cannot be converted to a numeric value.
86532 ** The COALESCE() and IFNULL() functions used to be implemented as shown
86534 ** do not have to be computed. This legacy implementation is retained as
86576 ** therefore be no less than -9223372036854775807.
86682 ** case. Thus 'a' LIKE 'A' would be true. */
86685 ** is case sensitive causing 'a' LIKE 'A' to be false */
86690 ** potentially be a "glob" expression. Return true (1) if they
86704 ** With the [...] and [^...] matching, a ']' character can be included
86706 ** range of characters can be specified using '-'. Example:
86710 ** This routine is usually quick, but can be N**2 in the worst case.
86879 "ESCAPE expression must be a single character", -1);
87137 ** must be exact. Collating sequences are not used.
87480 ** internal count when using count(*) and when the total count can be
87687 ** The array cannot be constant since changes are made to the
87852 ** modified (values must be compared at runtime).
87860 ** is thrown, even if the FK constraint would be satisfied after the new
87873 ** TODO: How should dropping a table be handled? How should renaming a
87874 ** table be handled?
87884 ** implemented using triggers, which of the old.* columns would be
87938 ** If the required index cannot be found, either because:
88010 ** the PRIMARY KEY of table pParent. The PRIMARY KEY index may be
88074 ** or deleted from the child table. If the parent row can be found, no
88075 ** special action is taken. Otherwise, if the parent row can *not* be
88133 ** will have INTEGER affinity applied to it, which may not be correct. */
88222 ** code for an SQL UPDATE operation, this function may be called twice -
88274 ** The collation sequence used for the comparison should be that of
88276 ** be applied to each child key value before the comparison takes place.
88380 ** The Trigger structure or any of its sub-components may be allocated from
88420 ** is the child table. If one cannot be found, return without
88421 ** generating any VDBE code. If one can be found, then jump over
88484 /* Exactly one of regOld and regNew should be non-zero. */
88506 ** schema items cannot be located, set an error in pParse and return
88573 ** be found, adding the child row has violated the FK constraint. */
88667 ** If any foreign key processing will be required, this function returns
88806 ** The final WHEN clause will be like this:
89022 Table *pTab, /* The table to be opened */
89052 be
89061 ** The column affinity string will eventually be deleted by
89102 ** The column affinity string will eventually be deleted by
89259 ** This routine should be called when the top of the stack holds a
89260 ** new rowid that is about to be inserted. If that new rowid is
89435 ExprList *pList, /* List of values to be inserted */
89460 int appendFlag = 0; /* True if the insert is likely to be an append */
89484 /* Locate the table into which we will be inserting new information.
89546 ** Then special optimizations can be applied that make the transfer
89620 ** should be written into a temporary table (template 4). Set to
89621 ** FALSE if each* row of the SELECT can be written directly into
89624 ** A temp table must be used if the table being updated is also one
89681 ** of columns to be inserted into the table.
89745 /* Initialize the count of rows to be inserted
89812 ** PRIMARY KEY into which a NULL is being inserted, that NULL will be
89814 ** we do not know what the unique ID will be (because the insert has
89933 ** Whenever this column is read, the record number will be substituted
89935 ** taking up data space with information that will never be used. */
90135 ** cursors do not need to be open for indices where aRegIdx[i]==0.
90193 zMsg = sqlite3MPrintf(pParse->db, "%s.%s may not be NULL",
90255 pParse, onError, "PRIMARY KEY must be unique", P4_STATIC);
90267 ** only. The table b-tree entry will be replaced by the new entry
90350 /* Check to see if the new index entry will be unique */
90418 ** rowid and the content to be inserted.
90420 ** The arguments to this routine should be the same as the first six
90430 int appendBias, /* True if this is likely to be an append */
90485 Table *pTab, /* Table to be opened */
90571 /* If no test above fails then the indices must be compatible */
90588 ** This routine returns TRUE if the optimization is guaranteed to be used.
90590 ** is empty - a factor that can only be determined at run-time. In that
90596 ** is no chance that the xfer optimization can be applied.
90624 return 0; /* Must be of the form INSERT INTO ... SELECT ... */
90631 return 0; /* tab1 must not be a virtual table */
90659 assert( pSelect->pOffset==0 ); /* Must be so if pLimit==0 */
90661 return 0; /* SELECT may not be a compound query */
90664 return 0; /* SELECT may not be DISTINCT */
90673 return 0; /* The result set must be the special operator "*" */
90686 return 0; /* tab1 and tab2 may not be the same table */
90690 return 0; /* tab2 must not be a virtual table */
90694 return 0; /* tab2 may not be a view */
90697 return 0; /* Number of columns must be the same in tab1 and tab2 */
90704 return 0; /* Affinity must be the same on all columns */
90707 return 0; /* Collating sequence must be the same on all columns */
90710 return 0; /* tab2 must be NOT NULL if tab1 is */
90766 ** be empty:
90791 pParse, onError, "PRIMARY KEY must be unique", P4_STATIC);
90857 ** other files are for internal use by SQLite and should not be
90874 const char *zSql, /* The SQL to be executed */
91023 ** shared libraries that want to be imported as extensions into
91024 ** an SQLite instance. Shared libraries that intend to be loaded
91040 ** versions of SQLite will not be able to load each others' shared
91824 ** zFile. The entry point is zProc. zProc may be 0 in which case a
91975 ** mutex must be held while accessing this list.
92122 ** should be passed into sqlite3BtreeSetSafetyLevel(). The is done
92123 ** to support legacy SQL code. The safety level used to be boolean
92214 sqlite3ErrorMsg(pParse, "temporary storage cannot be changed "
92229 ** as needing reloading. This must be done when using the SQLITE_TEMP_STORE
92293 /* TODO: Maybe it shouldn't be possible to change the ReadUncommitted
92298 /* This flag may only be set if both foreign-key and trigger support
92318 /* Foreign key support may not be enabled or disabled while not
92364 ** Parameter eMode must be one of the PAGER_JOURNALMODE_XXX constants
92394 ** The identifier might also be a string. The value is a string, and
92537 ** database page size value. The value can only be set if
92627 ** the current default locking mode (which may be different to
92635 ** of the PRAGMA command. In this case the locking-mode must be
92673 /* Force the schema to be loaded on all databases. This causes all
92674 ** database files to be opened and the journal_modes set. This is
92848 ** value will be restored the next time the database is opened.
92866 ** the value sets a specific directory to be used for temporary files.
92919 ** the value sets a specific file to be used for database access locks.
92962 ** default value will be restored the next time the database is
92972 "Safety level may not be changed inside a transaction");
93183 ** used will be case sensitive or not depending on the RHS.
93362 ** PRAGMA encoding = "utf-8"|"utf-16"|"utf-16le"|"utf-16be"
93369 ** encoding that will be used for the main database file if a new file
93378 ** In the second form this pragma sets the text encoding to be used in
93388 { "UTF-8", SQLITE_UTF8 }, /* Must be element [1] */
93389 { "UTF-16le", SQLITE_UTF16LE }, /* Must be element [2] */
93390 { "UTF-16be", SQLITE_UTF16BE }, /* Must be element [3] */
93411 ** will be overwritten when the schema is next loaded. If it does not
93412 ** already exists, it will be created to use the new encoding value.
93455 ** The user-version is not used internally by SQLite. It may be used by
93778 ** was created to be the PRIMARY KEY or to fulfill a UNIQUE
93803 ** database. iDb==1 should never be used. iDb>=2 is used for
93893 ** will be closed before this function returns. */
93911 ** meta[4] Db text encoding. 1:UTF-8 2:UTF-16LE 3:UTF-16BE
94136 ** will be closed immediately after reading the meta-value. */
94176 ** function should never be used.
94389 ** if the statement cannot be recompiled because another connection has
94832 ** NULL t2 row will be inserted whenever t1.x!=5. If we do not
94833 ** defer the handling of t1.x=5, it will be processed immediately
94919 ** in the USING clause. Example: If the two tables to be joined are
94923 ** not contained in both tables to be joined.
94958 int regData /* Register holding data to be sorted */
95190 ** then there should be a single item on the stack. Write this
95199 ** does not matter. But there might be a LIMIT clause, in which
95383 ** of the same name. The parameter "op" must be one of TK_UNION, TK_EXCEPT,
95523 ** expression pExpr. The string may be treated as static by the caller.
95528 ** is considered a column can be complex in the presence of subqueries. The
95557 ** extracted from in NameContext.pSrcList. This table may be real
95580 ** possible. However, it can still be true for statements like
95588 ** though it should really be "INTEGER".
95775 ** All column names will be unique.
95875 ** statement be resolved.
95991 ** contraversy about what the correct behavior should be.
96060 Select *p, /* The right-most of SELECTs to be coded */
96072 ** left is p->pPrior. The left query could also be a compound query
96073 ** in which case this routine will be called recursively.
96075 ** The results of the total query are to be written into a destination
96092 ** pPrior will be the t2 query. p->op will be TK_UNION in this case.
96099 Select *p, /* The right-most of SELECTs to be coded */
96270 ** Be sure to delete p->pOrderBy, therefore, to avoid a memory leak. */
96454 ** The data to be output is contained in pIn->iMem. There are
96455 ** pIn->nMem columns to be output. pDest is where the output should
96456 ** be sent.
96526 ** then there should be a single item on the stack. Write this
96577 /* If none of the above, then the result destination must be
96663 ** is skipped if the next results would be the same as the previous.
96695 Select *p, /* The right-most of SELECTs to be coded */
97029 /* Reassembly the compound query so that it will be freed correctly
97064 int iTable, /* Table to be substituted */
97096 int iTable, /* Table to be substituted */
97108 int iTable, /* Table to be replaced */
97145 ** has no indices, the WHERE clause on the outer query cannot be
97155 ** exist on the table t1, a complete scan of the data might be
97222 ** ORDER by clause of the parent must be simple references to
97282 /* Prior to version 3.1.2, when LIMIT and OFFSET had to be simple constants,
97284 ** because they could be computed at compile-time. But when LIMIT and OFFSET
97347 ** that make up the compound SELECT are allowed to be aggregate or distinct
97387 ** 17 and 18 above) it must be a UNION ALL and the parent query must
97388 ** be of the form:
97487 ** iParent. The iParent cursor will never be used. Subsequent code
97624 ** it is, or 0 otherwise. At present, a query is considered to be
97689 ** was such a clause and the named index cannot be found, return
97732 ** If found, expand each "*" to be every column in every table
97733 ** and TABLE.* to be every column in TABLE.
97838 ** operators that need to be expanded. Loop through each expression
97851 /* This particular expression does not need to be expanded.
97862 /* This expression is a "*" or a "TABLE.*" and needs to be
97888 char *zToFree; /* Malloced string that needs to be freed */
97975 ** SELECT statement. The SELECT statement must be expanded before
98194 ** Another solution would be to change the OP_SCopy used to copy cached
98254 ** SRT_Set The result must be a single column. Store each
98265 ** is assumed to already be open.
98302 Expr *pWhere; /* The WHERE clause. May be NULL */
98303 ExprList *pOrderBy; /* The ORDER BY clause. May be NULL */
98304 ExprList *pGroupBy; /* The GROUP BY clause. May be NULL */
98305 Expr *pHaving; /* The HAVING clause. May be NULL */
98331 ** DISTINCT so it can be removed too. */
98352 ** only a single column may be output.
98386 /* This subquery can be absorbed into its parent. */
98477 ** can be rewritten as a GROUP BY. In other words, this:
98485 ** The second form is preferred as a single index (or temp-table) may be
98500 ** index might end up being unused if the data can be
98502 ** OP_OpenEphemeral instruction will be changed to an OP_Noop once
98691 ** will be converted into a Noop.
98719 ** it might be a single loop that uses an index to extract information
98727 ** we do not have to sort. The OP_OpenEphemeral table will be
98919 ** will therefore be cheaper to scan to determine the query result.
98926 ** In practice the KeyInfo structure will not be used. It is only
98963 ** A special flag must be passed to sqlite3WhereBegin() to slightly
99044 /* Identify column names if results of the SELECT are to be output.
99168 ** These routines are in a separate files so that they will not be linked
99266 ** Instead, the entire table should be passed to sqlite3_free_table() when
99271 const char *zSql, /* The SQL to be executed */
99388 ** are already attached to pTab->pTrigger. But there might be additional
99451 assert( pName1!=0 ); /* pName1->z might be NULL, but not pName1 itself */
99456 /* If TEMP was specified, then the trigger name may not be qualified. */
99464 /* Figure out the db that the the trigger will be created in */
99514 ** drop so the trigger cannot be dropped. This results in an
99748 ExprList *pEList, /* The VALUE clause: a list of values to be inserted */
99779 Token *pTableName, /* Name of the table to be updated */
99834 ** This may be called directly from the parser and therefore identifies
99989 ** one trigger that must be fired when an operation of type 'op' is
100034 SrcList *pSrc; /* SrcList to be returned */
100067 /* Figure out the ON CONFLICT policy that will be used for this step
100288 /* It may be that this trigger has already been coded (or is in the
100290 ** a matching TriggerPrg.pTrigger field will be present somewhere
100297 /* If an existing TriggerPrg could not be located, create a new one. */
100370 ** never be accessed by the trigger program, so they are not allocated or
100403 ** always defined. The trigger must be in the same schema as the table
100404 ** or else it must be a TEMP trigger. */
100424 ** may be used by the caller, for example, to avoid having to load the entire
100428 ** table may be accessed using an [old|new].<col> reference. Bit 1 is set if
100431 ** with an index greater than 32 may be accessed, 0xffffffff is returned.
100436 ** Parameter isNew must be either 1 or 0. If it is 0, then the mask returned
100439 ** Parameter tr_tm must be a mask with one or both of the TRIGGER_BEFORE
100497 SrcList *pSrc, /* The virtual table to be modified */
100568 ExprList *pChanges, /* Things to be changed */
100569 Expr *pWhere, /* The WHERE clause. May be null */
100573 Table *pTab; /* The table to be updated */
100581 int *aRegIdx = 0; /* One register assigned to each index to be updated */
100587 int openAll = 0; /* True if all indices need to be opened */
100607 int regRowSet = 0; /* Rowset of rows to be updated */
100650 ** The index cursors might not be used, but if they are used they
100666 ** for each column to be updated in the pChanges array. For each
100667 ** column to be updated, make sure we have authorization to change
100713 ** the value with a register number for indices that are to be used
100744 /* Virtual tables must be handled separately */
100797 /* Remember the rowid of every item to be updated.
100820 ** to be deleting some records.
100896 ** values for registers not modified by the UPDATE must be reloaded from
100899 ** be used eliminates some redundant opcodes.
100913 /* This branch loads the value of a column that will not be changed
101002 /* Repeat the above with the next record to be updated, until
101060 ** for each row to be changed:
101077 SrcList *pSrc, /* The virtual table to be modified */
101117 ** be stored.
101166 ** Most of the code in this file may be omitted by defining the
101268 /* Save the current value of the database flags so that it can be
101283 ** can be set to 'off' for this file, as it is not recovered if a crash
101288 ** An optimisation would be to use a non-journaled pager.
101598 ** Lock the virtual table so that it cannot be disconnected.
101646 ** database connections to be disconnected at the next opportunity.
101686 ** This function may only be called when the mutexes associated with all
101692 ** associated with the database handle itself must be held.
101700 ** As a result, a sqlite3.pDisconnect cannot be accessed simultaneously
101748 ** string will be freed automatically when the table is
101894 ** allows a schema that contains virtual tables to be loaded before
102280 ** Set *pzErrmsg to point to a buffer that should be released using
102632 ** A WhereTerm might also be two or more subterms connected by OR:
102649 ** bits that will fit in a Bitmask. The VDBE cursor numbers might be
102651 ** numbers might be 3, 8, 9, 10, 20, 23, 41, and 45. The WhereMaskSet
102655 ** would be mapped into integers 0 through 7.
102762 ** 57->5, 73->4. Or one of 719 other combinations might be used. It
102784 ** OR-ed combination of these values can be used when searching for
102810 ** is set to WO_IN|WO_EQ. The WhereLevel.wsFlags field can then be used as
102812 ** ISNULL constraints will then not be used on the right table of a left
102840 WhereClause *pWC, /* The WhereClause to be initialized */
102901 ** 0 is returned if the new WhereTerm could not be added due to a memory
102902 ** allocation error. The memory allocation failure will be recorded in
102912 ** WhereTerms. All pointers to WhereTerms should be invalidated after
102913 ** calling this routine. Such pointers may be reinitialized by referencing
103074 ** IMPLEMENTATION-OF: R-59926-26393 To be usable by an index a term must be
103157 WhereClause *pWC, /* The WHERE clause to be searched */
103162 Index *pIdx /* Must be compatible with this index, if not NULL */
103186 ** it to be useful for optimising expression pX. Store this
103215 WhereClause *pWC /* the WHERE clause to be analyzed */
103226 ** can be optimized using inequality constraints. Return TRUE if it is
103229 ** In order for the operator to be optimizible, the RHS must be a string
103259 ** be the name of an indexed column with TEXT affinity. */
103298 ** function, then no OP_Variable will be added to the program.
103374 ** A single subterm might be a set of AND-connected sub-subterms.
103412 ** potentially be used with an index if an appropriate index exists.
103422 ** It might be the case that multiple tables are indexable. For example,
103438 int idxTerm /* Index of the OR-term to be analyzed */
103442 WhereTerm *pTerm = &pWC->a[idxTerm]; /* The term to be analyzed */
103525 ** Record the set of tables that satisfy case 2. The set might be
103545 ** might be possible to form an IN operator with either table1.column
103550 ** same table on both sizes of the ==) cannot be optimized.
103560 ** will be recorded in iCursor and iColumn. There might not be any
103576 /* This term must be of the form t1.a==t2.b where t2 is in the
103577 ** chngToIN set but t1 is not. This term will be either preceeded
103611 ** of both right and left sides must be such that no type
103684 ** needs to be freed with the WhereClause) and TERM_VIRTUAL (because it
103691 int idxTerm /* Index of the term to be analyzed */
103693 WhereTerm *pTerm; /* The term to be analyzed */
103695 Expr *pExpr; /* The expression to be analyzed */
103730 extraRight = x-1; /* ON clause terms may not be used with an index
103929 ** form "x IS NOT NULL" can sometimes be evaluated more efficiently
103933 ** Note that the virtual term must be tagged with TERM_VNULL. This
103981 int iFirst, /* Be searching with the iFirst-th expression */
104030 ** This routine determines if pIdx can be used to assist in processing a
104058 ** can be ignored. If it does not, and the column does not belong to the
104091 be distinct
104106 ** this query, then it will not be possible to show that the DISTINCT
104113 ** true. Note: The (p->iTable==iBase) part of this test may be false if the
104151 ** This routine decides if pIdx can be used to satisfy the ORDER BY
104160 ** constraints. Any of these columns may be missing from the ORDER BY
104161 ** clause and the match can still be a success.
104163 ** All terms of the ORDER BY that match against the index must be either
104173 int base, /* Cursor number for the table to be sorted */
104258 /* Indices can only be used if all ORDER BY terms past the
104270 ** tables in the join, then we are assured that the index can be used
104281 ** this index can be used for sorting. */
104300 ** The results need not be exact. This is only used for estimating
104367 ** This routine attempts to find an scanning strategy that can be used
104370 ** The table associated with FROM clause term pSrc may be either a
104383 const int iCur = pSrc->iCursor; /* The cursor of the table to be accessed */
104465 ** could be used with an index to access pSrc, assuming an appropriate
104504 Table *pTable; /* Table tht might be indexed */
104533 /* The cost of creating the transient table would be greater than
104594 /* Count the number of columns that will be added to the index
104618 ** original table never needs to be accessed. Automatic indices must
104619 ** be a covering index because the index will not be updated if the
104620 ** original table changes and the index and table cannot both be used
104870 ** In a join, this routine might be called multiple times for the
104922 /* The module name must be defined. Also, by this point there must
104923 ** be a pointer to an sqlite3_vtab structure. Otherwise
104946 ** join might be different so we have to recompute the usable flag
104991 /* The cost is not allowed to be larger than SQLITE_BIG_DBL (the
104993 ** (cost<lowestCost) test below will never be true.
105215 ** This function is used to estimate the number of rows that will be visited
105236 ** then nEq should be passed the value 1 (as the range restricted column,
105241 ** then nEq should be passed 0.
105257 WhereTerm *pLower, /* Lower bound on the range. ex: "x>123" Might be NULL */
105258 WhereTerm *pUpper, /* Upper bound on the range. ex: "x<455" Might be NULL */
105321 ** Estimate the number of rows that will be returned based on
105371 ** Estimate the number of rows that will be returned based on
105422 ** * The estimated number of rows that will be retrieved. (The
105427 ** * Whether or not there must be separate lookups in the
105451 be accessed */
105525 ** Number of equality terms that can be implemented using the index.
105552 ** IN operator must be a SELECT, not a value list, for this variable
105553 ** to be true.
105628 ** there is a range constraint on indexed column (nEq+1) that can be
105682 ** index), determine if all required column data may be obtained without
105715 ** data is available for column x, then it might be possible
105744 ** on one page and hence more pages have to be fetched.
105759 ** it seems to be working well enough at the moment.
105791 ** adds C*N*log10(N) to the cost, where N is the number of rows to be
105805 ** be used with the current index, but which might lower the number
105808 ** with this step if we already know this index will not be chosen.
105811 ** It is critical that the notValid mask be used here instead of
105817 ** might be selected even when there exists an optimal index that has
105895 ** is set, then reverse the order that the index will be scanned
105968 ** Disabling a term causes that term to not be tested in the inner loop
106033 ** term can be either X=expr or X IN (...). pTerm is the term to be
106044 WhereTerm *pTerm, /* The term of the WHERE clause to be coded */
106105 ** a==5 and b IN (1,2,3). The current values for a and b will be stored
106131 ** no conversion should be attempted before using a t2.b value as part of
106133 ** string in this example would be set to SQLITE_AFF_NONE.
106371 int iLevel, /* Which level of pWInfo->a[] should be coded */
106380 WhereLevel *pLevel; /* The where level to be coded */
106573 ** the right-most column can be an inequality - the rest must
106584 ** The z<10 term of the following cannot be used, only
106589 ** N may be zero if there are inequality constraints.
106622 Index *pIdx; /* The index we will be using */
106701 /* Since the comparison is to be performed with no conversions
106742 /* Since the comparison is to be performed with no conversions
106911 ** be picked up by the recursive calls to sqlite3WhereBegin() below.
106962 ** terms from the notReady table could not be tested and will
106963 ** need to be tested later.
107000 /* Insert code to test every subexpression that can be completely
107003 ** IMPLEMENTATION-OF: R-49525-50935 Terms that cannot be satisfied through
107121 ** Note that the loops might not be nested in the order in which they
107140 ** refer to those indices, a complete table scan can be avoided and the
107142 ** to see if there are indices that can be used to speed up the loop.
107174 ** If an index can be used so that the natural output order of the table
107180 ** If the where clause loops cannot be arranged to provide the correct
107185 SrcList *pTabList, /* A list of all tables to be scanned */
107225 ** field (type Bitmask) it must be aligned on an 8-byte boundary on
107271 ** When assigning bitmask values to FROM clause cursors, it must be
107287 ** equal to pTabList->nSrc but might be shortened to 1 if the
107369 ** for the given FROM clause entry as would be selected if the entry
107371 ** is chosen such that the cost of running that table cannot be reduced
107379 ** not be as small as it would be if the table really were the innermost
107380 ** join. The nRow value can be reduced by WHERE clause constraints
107409 int doNotReorder; /* True if this table should not be reordered */
107465 ** will be detected and relayed back to the application later.
107469 ** (4) The plan cost must be lower than prior plans or else the
107470 ** cost must be the same and the number of rows must be lower.
107779 ** the table need never be read from. This is a performance boost,
107905 ** new Expr to populate pOut. Set the span of pOut to be the identifier
107968 ** This section will be null unless lemon is run with the -m switch.
107993 ** have fall-back values which should be used if the
108057 /* Define the yytestcase() macro to be a no-op if is not already defined
108062 ** code the yytestcase() macro should be turned off. But it is useful
108098 ** and that yy_default[S] should be used instead.
108724 ** <li> A FILE* to which trace output should be written.
109200 ** symbol. The symbol can be either a terminal or nonterminal.
109207 YYMINORTYPE *yypminor /* The object to be destroyed */
109309 /* There is no mechanism by which the parser stack can be popped below
109331 ** <li> A pointer to the parser. This should be a pointer
109338 void *p, /* The parser to be deleted */
109486 yyParser *yypParser, /* The parser to be shifted */
111083 /* Here code is inserted which will be executed whenever the
111119 /* Here code is inserted which will be executed whenever the
111323 ** need to be translated.
111372 ** might be implemented more directly using a hand-written hash table.
111640 ** If X is a character that can be used in an identifier then
111641 ** IdChar(X) will be true. Otherwise it is false.
111645 ** sqlite3IsIdChar[X] must be 1.
112115 ** This code used to be part of the tokenizer.c source file. But by
112116 ** separating it out, the code will be automatically omitted from
112175 ** (5) TRIGGER We are in the middle of a trigger definition that must be
112200 ** to recognize the end of a trigger can be omitted. All we have to do
112358 ** above, except that the parameter is required to be UTF-16 encoded, not
112399 ** other files are for internal use by SQLite and should not be
112542 ** name of a directory, then that directory will be used to store
112552 ** This routine must be called to initialize the memory allocation,
112555 ** this routine will be called automatically by key routines such as
112570 ** Let X be the first thread to enter this routine. Let Y be some other
112592 ** to sqlite3_initialize() should be a no-op. But the initialization
112593 ** must be complete. So isInit must not be set until the very end
112601 ** there is not much SQLite is going to be able to do.
112637 ** subsystem could not be initialized or the system failed to allocate
112644 ** that we will be able to handle recursive calls into
112647 ** recursive calls might also be possible.
112650 ** to the xInit method, so the xInit method need not be threadsafe.
112723 ** Undo the effects of sqlite3_initialize(). Must not be called while
112760 ** This routine should only be called when there are no outstanding
112961 /* The size of a lookaside slot after ROUNDDOWN8 needs to be larger
112962 ** than a pointer to be useful.
113121 ** This collating sequence is intended to be used for "case independant
113164 ** database handle object, it does not close any savepoints that may be open
113217 ** SQL statements below, as the v-table implementation may be storing
113307 ** So it needs to be freed here. Todo: Why not roll the temp schema into
113497 ** be invoked every nOps opcodes.
113544 ** that it is designed to be called by internal code. The difference is
113788 ** Register a function to be invoked when a transaction commits.
113807 ** Register a callback to be invoked each time a row is updated,
113825 ** Register a callback to be invoked each time a transaction is rolled
113890 ** Register a callback to be invoked each time a transaction is written
113975 ** The mutex on database handle db should be held by the caller. The mutex
114011 ** This function returns true if main-memory should be used instead of
114107 ** be cleared before returning. Do this directly, instead of via
114187 ** then any copies made by synthCollSeq() need to be invalidated.
114189 ** to be called.
114219 ** initializer must be kept in sync with the SQLITE_LIMIT_*
114240 # error SQLITE_MAX_LENGTH must be at least 100
114243 # error SQLITE_MAX_SQL_LENGTH must be at least 100
114246 # error SQLITE_MAX_SQL_LENGTH must not be greater than SQLITE_MAX_LENGTH
114249 # error SQLITE_MAX_COMPOUND_SELECT must be at least 2
114252 # error SQLITE_MAX_VDBE_OP must be at least 40
114255 # error SQLITE_MAX_FUNCTION_ARG must be between 0 and 1000
114258 # error SQLITE_MAX_ATTACHED must be between 0 and 62
114261 # error SQLITE_MAX_LIKE_PATTERN_LENGTH must be at least 1
114267 # error SQLITE_MAX_TRIGGER_DEPTH must be at least 1
114328 ** *pFlags may be updated before returning if the URI filename contains
114332 ** the VFS that should be used to open the database file. *pzFile is set to
114338 ** may be set to point to a buffer containing an English language error
114369 ** method that there may be extra parameters following the file-name. */
114394 ** Within this loop, variable eState may be set to 0, 1 or 2, depending
114449 /* Check if there were any options specified that should be interpreted
114451 ** correspond to flags that may be passed to the sqlite3_open_v2()
114969 ** This function is now an anachronism. It used to be used to recover from a
115097 /* The following block stores the meta information that will be returned
115366 ** argument N is a bitmask of optimizations to be disabled. For normal
115367 ** operation N should be 0. The idea is that a test program (like the
115721 ** to the user because it requires a lock that will not be available
115794 ** be passed to the unlock-notify callback is larger than the
115800 ** is returned the transaction on connection db will still be
115814 ** connections. But it is the best that can be done under the
115891 ** are built from the bottom up, things will be described from the
115912 ** little-endian and can be up to 10 bytes in length (in theory).
116013 ** likely to be query targets.
116015 ** TODO(shess) It may be useful for blocking decisions to be more
116027 ** itself grows too big and must be split. The format of interior
116051 ** than pTerm[i+1], the subtree for that term will be rooted at
116072 ** This could be either a leaf node or an interior node. If the top
116111 ** MERGE_COUNT controls how often we merge segments. 16 seems to be
116119 ** which need to be scanned and merged. For instance, with 100k docs
116130 ** costs), and infrequent and non-existent terms still seem to be fast
116133 ** TODO(shess) That said, it would be nice to have a better query-side
116215 ** If tokenizers are to be allowed to call sqlite3_*() functions, then
116230 ** be used for the fts3 table (customized by the tokenizer clause arguments).
116234 ** that may be used to tokenize a specific input buffer based on
116245 ** Structure version. Should always be set to 0 or 1.
116261 ** code. If SQLITE_OK is returned, then *ppTokenizer should be set
116263 ** sqlite3_tokenizer.pModule variable should not be initialised by
116301 ** *ppToken should be set to point at a buffer containing the
116303 ** stemming has been performed). *pnBytes should be set to the length
116306 ** *piEndOffset. *piStartOffset should be set to the index of the first
116307 ** byte of the token in the input buffer. *piEndOffset should be set
116312 ** implementation. It is only required to be valid until the next call
116315 /* TODO(shess) current implementation requires pInput to be
116316 ** nul-terminated. This should either be fixed, or pInput/nBytes
116317 ** should be converted to zInput.
116381 ** The internals of this structure are intended to be opaque -- client
116403 ** Again, this structure is intended to be opaque, but it can't really
116404 ** be opaque because it is used by macros.
116542 ** FTS3 extension to be compiled outside of the
116715 ** Actualy, Fts3Cursor.eSearch can be greater than or equal to
116717 ** of the column to be searched. For example, in
116723 ** Fts3Cursor.eSearch will be set to FTS3_FULLTEXT_SEARCH+1. (+0 for a,
116725 ** indicating that all columns should be searched,
116726 ** then eSearch would be set to FTS3_FULLTEXT_SEARCH+4.
116739 int bFreeList; /* True if pList should be sqlite3_free()d */
116748 ** nToken will be the number of tokens in the string.
116795 ** The aMI array is allocated using sqlite3_malloc(). It should be freed
116989 ** The length of data written will be between 1 and FTS3_VARINT_MAX bytes.
117351 ** There may not be whitespace surrounding the "=" character. The <value>
117352 ** term may be quoted, but the <key> may not.
117433 ** could be used in a SELECT statement such as the following:
117539 ** Only decimal digits ('0'..'9') may be part of an integer value.
117635 ** If the table cannot be found, an error code is returned and the output
117763 ** the number of bytes of space that must be allocated to store copies
118371 ** never loads leaf nodes into memory), it is not possible to be sure.
118525 ** (in which case **pp will be a terminator bytes POS_END (0) or
118533 ** Before calling this routine *pi must be initialized to the value of
118920 ** should be false. If they are sorted in ascending order, it should be
118962 ** be a positive value less than or equal to the delta value read from
118965 ** that will be copied and merged from the input to the output.
118969 ** be larger in the output than it was in the input (since the delta value
118970 ** may be a larger positive integer than the actual docid).
118976 ** A symetric argument may be made if the doclists are in descending
119017 ** parameter bDescDoclist should be false. If they are sorted in ascending
119018 ** order, it should be passed a non-zero value.
119081 sqlite3_int64 iDelta, /* Varint that may be written to pOut */
119179 ** for the specified prefix. Since there can be a very large number of
119285 ** for the pending-terms. If this is a scan, then this call must be being
119314 ** root node, the range of leaves scanned can be reduced. Do this. */
119545 ** matches the search criteria. For a MATCH search, this will be
119546 ** the next row that matches. For a full-table scan, this will be
119551 ** even if we reach end-of-file. The fts3EofMethod() will be called
119693 ** rowid should be written to *pRowid.
119721 /* The column value supplied by SQLite must be in range. */
119759 ** FTS3 virtual tables. It is invoked by SQLite each time a row is to be
119888 /* There must be at least one argument passed to this function (otherwise
120283 ** there exists prefix b-tree of the right length) then it may be traversed
120284 ** and merged incrementally. Otherwise, it has to be merged into an in-memory
120520 ** function has been called successfully on an Fts3Phrase, it may be
120563 ** The doclist may be sorted in ascending (parameter bDescIdx==0) or
120704 ** may be loaded incrementally, meaning doclist.aAll/nAll is not available.
120863 ** This function is called to select the tokens (if any) that will be
120890 int nLoad4 = 1; /* (Phrases that will be loaded)^4. */
120918 ** of the number of overflow pages that will be loaded by the pager layer
120931 ** Let nOther be the number of other phrases for which it is certain that
120932 ** one or more tokens will not be deferred.
120956 ** that will be loaded if all subsequent tokens are deferred.
120971 ** (eventually) be loaded into memory. It may as well be now. */
121014 /* Determine which, if any, tokens in the expression should be deferred. */
121281 ** be edited if 0 is returned.
121303 ** left-hand child may be either a phrase or a NEAR node. There are
121367 Fts3Expr *pExpr, /* Expr to test. May or may not be root. */
121605 ** Expression pExpr must be of type FTSQUERY_PHRASE.
121682 ** do loop can not be written:
121758 ** must be of type FTSQUERY_PHRASE.
121886 Fts3MultiSegReader csr; /* Must be right after "base" */
122141 ** that the following integer will be a column number, or the
122157 if( v==0 ){ /* 0x00. Next integer will be a docid. */
122159 }else if( v==1 ){ /* 0x01. Next integer will be a column number. */
122374 ** be tested using a single build of testfixture.
122440 ** The standard isspace() can be awkward to use safely, because although it
122612 ** allocation so that the expression can be freed with a single call to
122781 /* At this point this is probably a keyword. But for that to be true,
122842 /* If control flows to this point, this must be a regular token, or
123096 ** Column names must be nul-terminated strings.
123098 ** The iDefaultCol parameter should be passed the index of the table column
123247 ** expression parser. It should be called as follows:
123398 ** "pNew" is a pointer to the hash table that is to be initialized.
123477 ** The C syntax in this function definition may be unfamilar to some
123515 Fts3HashElem *pNew /* The element to be inserted */
123537 ** "new_size" must be a power of 2. The hash table might fail
123567 const Fts3Hash *pH, /* The pH to be searched */
123596 Fts3HashElem* elem, /* The element to be removed from the pH */
123780 int iToken; /* index of next token to be returned */
123815 ** string to be tokenized is zInput[0..nInput-1]. A cursor
123821 const char *zInput, int nInput, /* String to be tokenized */
123900 ** Let any sequence of one or more vowels be represented by V and let
123901 ** C be sequence of one or more consonants. Then every word can be
123977 ** first three letters and the first one cannot be in [wxy].
124003 int (*xCond)(const char*) /* Condition that must be true */
124289 ** Characters that can be part of a token. We assume any character
124290 ** whose value is greater than 0x80 (any UTF character) can be
124412 ** hash table. This function may be called as follows:
124420 ** If the <pointer> argument is specified, it must be a blob value
124421 ** containing a pointer to be stored as the hash data corresponding
124589 ** designed to be used in concert with the Tcl testing framework. This
124590 ** function must be called with two arguments:
124599 ** The return value is a string that may be interpreted as a Tcl
124756 ** can be used as designed by the C-code in the queryTokenizer and
124912 int iToken; /* index of next token to be returned */
124939 ** else we need to reindex. One solution would be a meta-table to
124976 ** string to be tokenized is pInput[0..nBytes-1]. A cursor
124982 const char *pInput, int nBytes, /* String to be tokenized */
125143 ** Under certain circumstances, b-tree nodes (doclists) can be loaded into
125144 ** memory incrementally instead of all at once. This can be a big performance
125152 ** is 1. Clearly such small values would be inefficient, but can be useful
125156 ** be overridden at runtime for testing purposes. File fts3_test.c contains
125230 /* Variables set by fts3SegReaderNext(). These may be read directly
125509 ** a second connection will be able to write to the fts3 table, but
125515 ** a transaction, the whole transaction will be rolled back. And this is
125551 ** can be used to query the %_segdir table.
125580 ** Set *ppStmt to a statement handle that may be used to iterate through
125788 Fts3Table *p, /* Table into which text will be inserted */
125790 const char *zText, /* Text of document to be inserted */
125811 /* If the user has inserted a NULL value, this function may be called with
125831 /* Positions cannot be negative; we use -1 as a terminator internally.
126053 ** (an integer) of a row about to be deleted. Remove all terms from the
126059 sqlite3_value *pRowid, /* The docid to be deleted */
126173 ** to this function. The handle may be closed by calling the
126175 ** performance improvement, but the blob handle should always be closed
126190 /* pnBlob must be non-NULL. paBlob may be NULL or non-NULL. */
126706 ** Because the stack address of pE may be accessed via the aElem pointer
126707 ** below, the "Fts3HashElem *pE" must be declared so that it is valid
126969 /* An unusual case: this is the first term to be added to the node
126974 ** this is not expected to be a serious problem.
127143 ** be passed NULL. This function will allocate a new SegmentWriter object
127151 int isCopyTerm, /* True if buffer zTerm must be copied */
127210 ** a) be greater than the largest term on the leaf node just written
127213 ** b) be less than or equal to the term about to be added to the new
127216 ** In other words, it must be the prefix of zTerm 1 byte longer than
127255 /* Save the current term so that it can be used to prefix-compress the next.
127282 ** database. This function must be called after all terms have been added
127804 ** of Fts3SegReader objects is the same. The doclists must be merged
128449 ** SQLite value pRowid contains the rowid of a row that may or may not be
128548 ** should be deleted from the database before inserting the new row. Or,
128564 /* The new rowid is not NULL (in this case the rowid will be
128575 ** be losslessly converted to an integer. In this case, the eventual
129209 /* Ideally, the start of the snippet should be pushed forward in the
129337 /* Set isHighlight to true if this term should be highlighted. */
129646 ** be returned by the matchinfo() function. Argument zArg contains the
129650 ** is guaranteed to be large enough for the output.
129851 ** cannot be found, the second iteration of the loop attempts to locate
130027 ** fts3ExprIterate() can be discarded.
130199 ** table must be the same size as the root node. The content of each node
130226 /* Either, both or none of the following may be set to activate
130233 ** Exactly one of the following must be set to 1.
130443 ** An instance of this structure must be supplied as a blob argument to
130674 ** is greater than RTREE_MAX_DEPTH, the r-tree structure must be corrupt.
131021 ** guaranteed to be a MATCH constraint.
131095 ** would be filtered (excluded) by the constraints in the
131248 /* RtreeCursor.pNode must not be NULL. If is is NULL, then this cursor is
131437 /* A MATCH operator. The right-hand-side must be a blob that
131438 ** can be cast into an RtreeMatchArg object. One created using
131539 ** and then a linear search of an R-Tree node. This should be
131759 /* Select the child node which will be enlarged the least if pCell
132468 ** rowid of the row to delete, which can be used to find the leaf on which
132542 ** the Rtree.pDeleted list. Its contents will be re-inserted later on.
132806 ** about to be deleted.
132900 ** the conflicting row can be removed before proceeding. In the second
132901 ** case, SQLITE_CONSTRAINT must be returned regardless of the
133279 ** human readable strings. This can be used for debugging and analysis.
133370 ** A version of sqlite3_free() that can be used as a callback. This is used
133538 ** 4. uPattern is to be handled as an ordinary character
133633 "ESCAPE expression must be a single character", -1);
133762 ** should be invoked with two arguments. The second argument is the name
133848 ** types to an SQLite database connection. It is intended to be called
134037 ** string to be tokenized is pInput[0..nBytes-1]. A cursor
