diff options
| -rw-r--r-- | ext/sqlite3/libsqlite/sqlite3.c | 22265 | ||||
| -rw-r--r-- | ext/sqlite3/libsqlite/sqlite3.h | 4485 | ||||
| -rw-r--r-- | ext/sqlite3/libsqlite/sqlite3ext.h | 14 |
3 files changed, 17865 insertions, 8899 deletions
diff --git a/ext/sqlite3/libsqlite/sqlite3.c b/ext/sqlite3/libsqlite/sqlite3.c index d53588137a..95a4738903 100644 --- a/ext/sqlite3/libsqlite/sqlite3.c +++ b/ext/sqlite3/libsqlite/sqlite3.c @@ -1,6 +1,6 @@ /****************************************************************************** ** This file is an amalgamation of many separate C source files from SQLite -** version 3.5.9. By combining all the individual C code files into this +** version 3.6.1. By combining all the individual C code files into this ** single large file, the entire code can be compiled as a one translation ** unit. This allows many compilers to do optimizations that would not be ** possible if the files were compiled separately. Performance improvements @@ -11,13 +11,13 @@ ** programs, you need this file and the "sqlite3.h" header file that defines ** the programming interface to the SQLite library. (If you do not have ** the "sqlite3.h" header file at hand, you will find a copy in the first -** 5638 lines past this header comment.) Additional code files may be +** 6279 lines past this header comment.) Additional code files may be ** needed if you want a wrapper to interface SQLite with your choice of ** programming language. The code for the "sqlite3" command-line shell ** is also in a separate file. This file contains only code for the core ** SQLite library. ** -** This amalgamation was generated on 2008-05-14 16:20:58 UTC. +** This amalgamation was generated on 2008-08-05 21:36:42 UTC. */ #define SQLITE_CORE 1 #define SQLITE_AMALGAMATION 1 @@ -253,7 +253,9 @@ #endif /* Needed for various definitions... */ -#define _GNU_SOURCE +#ifndef _GNU_SOURCE +# define _GNU_SOURCE +#endif /* ** Include standard header files as necessary @@ -279,6 +281,26 @@ SQLITE_PRIVATE void sqlite3Coverage(int); # define testcase(X) #endif +/* +** The ALWAYS and NEVER macros surround boolean expressions which +** are intended to always be true or false, respectively. Such +** expressions could be omitted from the code completely. But they +** are included in a few cases in order to enhance the resilience +** of SQLite to unexpected behavior - to make the code "self-healing" +** or "ductile" rather than being "brittle" and crashing at the first +** hint of unplanned behavior. +** +** When doing coverage testing ALWAYS and NEVER are hard-coded to +** be true and false so that the unreachable code then specify will +** not be counted as untested code. +*/ +#ifdef SQLITE_COVERAGE_TEST +# define ALWAYS(X) (1) +# define NEVER(X) (0) +#else +# define ALWAYS(X) (X) +# define NEVER(X) (X) +#endif /* ** The macro unlikely() is a hint that surrounds a boolean @@ -294,6 +316,22 @@ SQLITE_PRIVATE void sqlite3Coverage(int); # define unlikely(X) !!(X) #endif +/* + * This macro is used to "hide" some ugliness in casting an int + * value to a ptr value under the MSVC 64-bit compiler. Casting + * non 64-bit values to ptr types results in a "hard" error with + * the MSVC 64-bit compiler which this attempts to avoid. + * + * A simple compiler pragma or casting sequence could not be found + * to correct this in all situations, so this macro was introduced. + * + * It could be argued that the intptr_t type could be used in this + * case, but that type is not available on all compilers, or + * requires the #include of specific headers which differs between + * platforms. + */ +#define SQLITE_INT_TO_PTR(X) ((void*)&((char*)0)[X]) +#define SQLITE_PTR_TO_INT(X) ((int)(((char*)X)-(char*)0)) /* ** These #defines should enable >2GB file support on Posix if the @@ -423,7 +461,7 @@ SQLITE_PRIVATE void sqlite3Coverage(int); ** ** Some of the definitions that are in this file are marked as ** "experimental". Experimental interfaces are normally new -** features recently added to SQLite. We do not anticipate changes +** features recently added to SQLite. We do not anticipate changes ** to experimental interfaces but reserve to make minor changes if ** experience from use "in the wild" suggest such changes are prudent. ** @@ -458,8 +496,7 @@ extern "C" { #endif /* -** Make sure these symbols where not defined by some previous header -** file. +** Ensure these symbols were not defined by some previous header file. */ #ifdef SQLITE_VERSION # undef SQLITE_VERSION @@ -469,7 +506,7 @@ extern "C" { #endif /* -** CAPI3REF: Compile-Time Library Version Numbers {F10010} +** CAPI3REF: Compile-Time Library Version Numbers {H10010} <S60100> ** ** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in ** the sqlite3.h file specify the version of SQLite with which @@ -478,39 +515,38 @@ extern "C" { ** The "version" of SQLite is a string of the form "X.Y.Z". ** The phrase "alpha" or "beta" might be appended after the Z. ** The X value is major version number always 3 in SQLite3. -** The X value only changes when backwards compatibility is -** broken and we intend to never break -** backwards compatibility. The Y value is the minor version -** number and only changes when +** The X value only changes when backwards compatibility is +** broken and we intend to never break backwards compatibility. +** The Y value is the minor version number and only changes when ** there are major feature enhancements that are forwards compatible -** but not backwards compatible. The Z value is release number -** and is incremented with -** each release but resets back to 0 when Y is incremented. +** but not backwards compatible. +** The Z value is the release number and is incremented with +** each release but resets back to 0 whenever Y is incremented. ** ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()]. ** ** INVARIANTS: ** -** {F10011} The SQLITE_VERSION #define in the sqlite3.h header file -** evaluates to a string literal that is the SQLite version +** {H10011} The SQLITE_VERSION #define in the sqlite3.h header file shall +** evaluate to a string literal that is the SQLite version ** with which the header file is associated. ** -** {F10014} The SQLITE_VERSION_NUMBER #define resolves to an integer -** with the value (X*1000000 + Y*1000 + Z) where X, Y, and -** Z are the major version, minor version, and release number. +** {H10014} The SQLITE_VERSION_NUMBER #define shall resolve to an integer +** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z +** are the major version, minor version, and release number. */ -#define SQLITE_VERSION "3.5.9" -#define SQLITE_VERSION_NUMBER 3005009 +#define SQLITE_VERSION "3.6.1" +#define SQLITE_VERSION_NUMBER 3006001 /* -** CAPI3REF: Run-Time Library Version Numbers {F10020} +** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100> ** KEYWORDS: sqlite3_version ** ** These features provide the same information as the [SQLITE_VERSION] ** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated ** with the library instead of the header file. Cautious programmers might -** include a check in their application to verify that -** sqlite3_libversion_number() always returns the value +** include a check in their application to verify that +** sqlite3_libversion_number() always returns the value ** [SQLITE_VERSION_NUMBER]. ** ** The sqlite3_libversion() function returns the same information as is @@ -520,13 +556,13 @@ extern "C" { ** ** INVARIANTS: ** -** {F10021} The [sqlite3_libversion_number()] interface returns an integer -** equal to [SQLITE_VERSION_NUMBER]. +** {H10021} The [sqlite3_libversion_number()] interface shall return +** an integer equal to [SQLITE_VERSION_NUMBER]. ** -** {F10022} The [sqlite3_version] string constant contains the text of the -** [SQLITE_VERSION] string. +** {H10022} The [sqlite3_version] string constant shall contain +** the text of the [SQLITE_VERSION] string. ** -** {F10023} The [sqlite3_libversion()] function returns +** {H10023} The [sqlite3_libversion()] function shall return ** a pointer to the [sqlite3_version] string constant. */ SQLITE_API const char sqlite3_version[]; @@ -534,64 +570,80 @@ SQLITE_API const char *sqlite3_libversion(void); SQLITE_API int sqlite3_libversion_number(void); /* -** CAPI3REF: Test To See If The Library Is Threadsafe {F10100} +** CAPI3REF: Test To See If The Library Is Threadsafe {H10100} <S60100> ** ** SQLite can be compiled with or without mutexes. When -** the SQLITE_THREADSAFE C preprocessor macro is true, mutexes +** the [SQLITE_THREADSAFE] C preprocessor macro is true, mutexes ** are enabled and SQLite is threadsafe. When that macro is false, ** the mutexes are omitted. Without the mutexes, it is not safe -** to use SQLite from more than one thread. +** to use SQLite concurrently from more than one thread. ** -** There is a measurable performance penalty for enabling mutexes. +** Enabling mutexes incurs a measurable performance penalty. ** So if speed is of utmost importance, it makes sense to disable ** the mutexes. But for maximum safety, mutexes should be enabled. ** The default behavior is for mutexes to be enabled. ** ** This interface can be used by a program to make sure that the ** version of SQLite that it is linking against was compiled with -** the desired setting of the SQLITE_THREADSAFE macro. +** the desired setting of the [SQLITE_THREADSAFE] macro. +** +** This interface only reports on the compile-time mutex setting +** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with +** SQLITE_THREADSAFE=1 then mutexes are enabled by default but +** can be fully or partially disabled using a call to [sqlite3_config()] +** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD], +** or [SQLITE_CONFIG_MUTEX]. The return value of this function shows +** only the default compile-time setting, not any run-time changes +** to that setting. ** ** INVARIANTS: ** -** {F10101} The [sqlite3_threadsafe()] function returns nonzero if -** SQLite was compiled with its mutexes enabled or zero -** if SQLite was compiled with mutexes disabled. +** {H10101} The [sqlite3_threadsafe()] function shall return nonzero if +** SQLite was compiled with the its mutexes enabled by default +** or zero if SQLite was compiled such that mutexes are +** permanently disabled. +** +** {H10102} The value returned by the [sqlite3_threadsafe()] function +** shall not change when mutex setting are modified at +** runtime using the [sqlite3_config()] interface and +** especially the [SQLITE_CONFIG_SINGLETHREAD], +** [SQLITE_CONFIG_MULTITHREAD], [SQLITE_CONFIG_SERIALIZED], +** and [SQLITE_CONFIG_MUTEX] verbs. */ SQLITE_API int sqlite3_threadsafe(void); /* -** CAPI3REF: Database Connection Handle {F12000} +** CAPI3REF: Database Connection Handle {H12000} <S40200> ** KEYWORDS: {database connection} {database connections} ** -** Each open SQLite database is represented by pointer to an instance of the -** opaque structure named "sqlite3". It is useful to think of an sqlite3 +** Each open SQLite database is represented by a pointer to an instance of +** the opaque structure named "sqlite3". It is useful to think of an sqlite3 ** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and -** [sqlite3_open_v2()] interfaces are its constructors -** and [sqlite3_close()] is its destructor. There are many other interfaces -** (such as [sqlite3_prepare_v2()], [sqlite3_create_function()], and -** [sqlite3_busy_timeout()] to name but three) that are methods on this -** object. +** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()] +** is its destructor. There are many other interfaces (such as +** [sqlite3_prepare_v2()], [sqlite3_create_function()], and +** [sqlite3_busy_timeout()] to name but three) that are methods on an +** sqlite3 object. */ typedef struct sqlite3 sqlite3; - /* -** CAPI3REF: 64-Bit Integer Types {F10200} +** CAPI3REF: 64-Bit Integer Types {H10200} <S10110> ** KEYWORDS: sqlite_int64 sqlite_uint64 ** ** Because there is no cross-platform way to specify 64-bit integer types ** SQLite includes typedefs for 64-bit signed and unsigned integers. ** -** The sqlite3_int64 and sqlite3_uint64 are the preferred type -** definitions. The sqlite_int64 and sqlite_uint64 types are -** supported for backwards compatibility only. +** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions. +** The sqlite_int64 and sqlite_uint64 types are supported for backwards +** compatibility only. ** ** INVARIANTS: ** -** {F10201} The [sqlite_int64] and [sqlite3_int64] types specify a -** 64-bit signed integer. +** {H10201} The [sqlite_int64] and [sqlite3_int64] type shall specify +** a 64-bit signed integer. ** -** {F10202} The [sqlite_uint64] and [sqlite3_uint64] types specify +** {H10202} The [sqlite_uint64] and [sqlite3_uint64] type shall specify ** a 64-bit unsigned integer. */ #ifdef SQLITE_INT64_TYPE @@ -609,50 +661,62 @@ typedef sqlite_uint64 sqlite3_uint64; /* ** If compiling for a processor that lacks floating point support, -** substitute integer for floating-point +** substitute integer for floating-point. */ #ifdef SQLITE_OMIT_FLOATING_POINT # define double sqlite3_int64 #endif /* -** CAPI3REF: Closing A Database Connection {F12010} +** CAPI3REF: Closing A Database Connection {H12010} <S30100><S40200> +** +** This routine is the destructor for the [sqlite3] object. ** -** This routine is the destructor for the [sqlite3] object. +** Applications should [sqlite3_finalize | finalize] all [prepared statements] +** and [sqlite3_blob_close | close] all [BLOB handles] associated with +** the [sqlite3] object prior to attempting to close the object. +** The [sqlite3_next_stmt()] interface can be used to locate all +** [prepared statements] associated with a [database connection] if desired. +** Typical code might look like this: ** -** Applications should [sqlite3_finalize | finalize] all -** [prepared statements] and -** [sqlite3_blob_close | close] all [sqlite3_blob | BLOBs] -** associated with the [sqlite3] object prior -** to attempting to close the [sqlite3] object. +** <blockquote><pre> +** sqlite3_stmt *pStmt; +** while( (pStmt = sqlite3_next_stmt(db, 0))!=0 ){ +** sqlite3_finalize(pStmt); +** } +** </pre></blockquote> ** -** <todo>What happens to pending transactions? Are they -** rolled back, or abandoned?</todo> +** If [sqlite3_close()] is invoked while a transaction is open, +** the transaction is automatically rolled back. ** ** INVARIANTS: ** -** {F12011} The [sqlite3_close()] interface destroys an [sqlite3] object -** allocated by a prior call to [sqlite3_open()], -** [sqlite3_open16()], or [sqlite3_open_v2()]. +** {H12011} A successful call to [sqlite3_close(C)] shall destroy the +** [database connection] object C. +** +** {H12012} A successful call to [sqlite3_close(C)] shall return SQLITE_OK. ** -** {F12012} The [sqlite3_close()] function releases all memory used by the -** connection and closes all open files. +** {H12013} A successful call to [sqlite3_close(C)] shall release all +** memory and system resources associated with [database connection] +** C. ** -** {F12013} If the database connection contains -** [prepared statements] that have not been -** finalized by [sqlite3_finalize()], then [sqlite3_close()] -** returns [SQLITE_BUSY] and leaves the connection open. +** {H12014} A call to [sqlite3_close(C)] on a [database connection] C that +** has one or more open [prepared statements] shall fail with +** an [SQLITE_BUSY] error code. ** -** {F12014} Giving sqlite3_close() a NULL pointer is a harmless no-op. +** {H12015} A call to [sqlite3_close(C)] where C is a NULL pointer shall +** return SQLITE_OK. ** -** LIMITATIONS: +** {H12019} When [sqlite3_close(C)] is invoked on a [database connection] C +** that has a pending transaction, the transaction shall be +** rolled back. ** -** {U12015} The parameter to [sqlite3_close()] must be an [sqlite3] object -** pointer previously obtained from [sqlite3_open()] or the -** equivalent, or NULL. +** ASSUMPTIONS: ** -** {U12016} The parameter to [sqlite3_close()] must not have been previously -** closed. +** {A12016} The C parameter to [sqlite3_close(C)] must be either a NULL +** pointer or an [sqlite3] object pointer obtained +** from [sqlite3_open()], [sqlite3_open16()], or +** [sqlite3_open_v2()], and not previously closed. */ SQLITE_API int sqlite3_close(sqlite3 *); @@ -664,115 +728,129 @@ SQLITE_API int sqlite3_close(sqlite3 *); typedef int (*sqlite3_callback)(void*,int,char**, char**); /* -** CAPI3REF: One-Step Query Execution Interface {F12100} +** CAPI3REF: One-Step Query Execution Interface {H12100} <S10000> ** -** The sqlite3_exec() interface is a convenient way of running -** one or more SQL statements without a lot of C code. The -** SQL statements are passed in as the second parameter to -** sqlite3_exec(). The statements are evaluated one by one -** until either an error or an interrupt is encountered or -** until they are all done. The 3rd parameter is an optional -** callback that is invoked once for each row of any query results -** produced by the SQL statements. The 5th parameter tells where +** The sqlite3_exec() interface is a convenient way of running one or more +** SQL statements without having to write a lot of C code. The UTF-8 encoded +** SQL statements are passed in as the second parameter to sqlite3_exec(). +** The statements are evaluated one by one until either an error or +** an interrupt is encountered, or until they are all done. The 3rd parameter +** is an optional callback that is invoked once for each row of any query +** results produced by the SQL statements. The 5th parameter tells where ** to write any error messages. ** +** The error message passed back through the 5th parameter is held +** in memory obtained from [sqlite3_malloc()]. To avoid a memory leak, +** the calling application should call [sqlite3_free()] on any error +** message returned through the 5th parameter when it has finished using +** the error message. +** +** If the SQL statement in the 2nd parameter is NULL or an empty string +** or a string containing only whitespace and comments, then no SQL +** statements are evaluated and the database is not changed. +** ** The sqlite3_exec() interface is implemented in terms of ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]. -** The sqlite3_exec() routine does nothing that cannot be done +** The sqlite3_exec() routine does nothing to the database that cannot be done ** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]. -** The sqlite3_exec() is just a convenient wrapper. ** ** INVARIANTS: -** -** {F12101} The [sqlite3_exec()] interface evaluates zero or more UTF-8 -** encoded, semicolon-separated, SQL statements in the -** zero-terminated string of its 2nd parameter within the -** context of the [sqlite3] object given in the 1st parameter. ** -** {F12104} The return value of [sqlite3_exec()] is SQLITE_OK if all -** SQL statements run successfully. +** {H12101} A successful invocation of [sqlite3_exec(D,S,C,A,E)] +** shall sequentially evaluate all of the UTF-8 encoded, +** semicolon-separated SQL statements in the zero-terminated +** string S within the context of the [database connection] D. +** +** {H12102} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL then +** the actions of the interface shall be the same as if the +** S parameter were an empty string. +** +** {H12104} The return value of [sqlite3_exec()] shall be [SQLITE_OK] if all +** SQL statements run successfully and to completion. ** -** {F12105} The return value of [sqlite3_exec()] is an appropriate -** non-zero error code if any SQL statement fails. +** {H12105} The return value of [sqlite3_exec()] shall be an appropriate +** non-zero [error code] if any SQL statement fails. ** -** {F12107} If one or more of the SQL statements handed to [sqlite3_exec()] +** {H12107} If one or more of the SQL statements handed to [sqlite3_exec()] ** return results and the 3rd parameter is not NULL, then -** the callback function specified by the 3rd parameter is +** the callback function specified by the 3rd parameter shall be ** invoked once for each row of result. ** -** {F12110} If the callback returns a non-zero value then [sqlite3_exec()] -** will aborted the SQL statement it is currently evaluating, +** {H12110} If the callback returns a non-zero value then [sqlite3_exec()] +** shall abort the SQL statement it is currently evaluating, ** skip all subsequent SQL statements, and return [SQLITE_ABORT]. -** <todo>What happens to *errmsg here? Does the result code for -** sqlite3_errcode() get set?</todo> ** -** {F12113} The [sqlite3_exec()] routine will pass its 4th parameter through +** {H12113} The [sqlite3_exec()] routine shall pass its 4th parameter through ** as the 1st parameter of the callback. ** -** {F12116} The [sqlite3_exec()] routine sets the 2nd parameter of its +** {H12116} The [sqlite3_exec()] routine shall set the 2nd parameter of its ** callback to be the number of columns in the current row of ** result. ** -** {F12119} The [sqlite3_exec()] routine sets the 3rd parameter of its +** {H12119} The [sqlite3_exec()] routine shall set the 3rd parameter of its ** callback to be an array of pointers to strings holding the ** values for each column in the current result set row as ** obtained from [sqlite3_column_text()]. ** -** {F12122} The [sqlite3_exec()] routine sets the 4th parameter of its +** {H12122} The [sqlite3_exec()] routine shall set the 4th parameter of its ** callback to be an array of pointers to strings holding the ** names of result columns as obtained from [sqlite3_column_name()]. ** -** {F12125} If the 3rd parameter to [sqlite3_exec()] is NULL then -** [sqlite3_exec()] never invokes a callback. All query -** results are silently discarded. +** {H12125} If the 3rd parameter to [sqlite3_exec()] is NULL then +** [sqlite3_exec()] shall silently discard query results. ** -** {F12128} If an error occurs while parsing or evaluating any of the SQL -** statements handed to [sqlite3_exec()] then [sqlite3_exec()] will -** return an [error code] other than [SQLITE_OK]. +** {H12131} If an error occurs while parsing or evaluating any of the SQL +** statements in the S parameter of [sqlite3_exec(D,S,C,A,E)] and if +** the E parameter is not NULL, then [sqlite3_exec()] shall store +** in *E an appropriate error message written into memory obtained +** from [sqlite3_malloc()]. ** -** {F12131} If an error occurs while parsing or evaluating any of the SQL -** handed to [sqlite3_exec()] and if the 5th parameter (errmsg) -** to [sqlite3_exec()] is not NULL, then an error message is -** allocated using the equivalent of [sqlite3_mprintf()] and -** *errmsg is made to point to that message. +** {H12134} The [sqlite3_exec(D,S,C,A,E)] routine shall set the value of +** *E to NULL if E is not NULL and there are no errors. ** -** {F12134} The [sqlite3_exec()] routine does not change the value of -** *errmsg if errmsg is NULL or if there are no errors. +** {H12137} The [sqlite3_exec(D,S,C,A,E)] function shall set the [error code] +** and message accessible via [sqlite3_errcode()], +** [sqlite3_errmsg()], and [sqlite3_errmsg16()]. ** -** {F12137} The [sqlite3_exec()] function sets the error code and message -** accessible via [sqlite3_errcode()], [sqlite3_errmsg()], and -** [sqlite3_errmsg16()]. +** {H12138} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL or an +** empty string or contains nothing other than whitespace, comments, +** and/or semicolons, then results of [sqlite3_errcode()], +** [sqlite3_errmsg()], and [sqlite3_errmsg16()] +** shall reset to indicate no errors. ** -** LIMITATIONS: +** ASSUMPTIONS: ** -** {U12141} The first parameter to [sqlite3_exec()] must be an valid and open +** {A12141} The first parameter to [sqlite3_exec()] must be an valid and open ** [database connection]. ** -** {U12142} The database connection must not be closed while +** {A12142} The database connection must not be closed while ** [sqlite3_exec()] is running. -** -** {U12143} The calling function is should use [sqlite3_free()] to free +** +** {A12143} The calling function should use [sqlite3_free()] to free ** the memory that *errmsg is left pointing at once the error ** message is no longer needed. ** -** {U12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()] +** {A12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()] ** must remain unchanged while [sqlite3_exec()] is running. */ SQLITE_API int sqlite3_exec( sqlite3*, /* An open database */ - const char *sql, /* SQL to be evaluted */ + const char *sql, /* SQL to be evaluated */ int (*callback)(void*,int,char**,char**), /* Callback function */ void *, /* 1st argument to callback */ char **errmsg /* Error msg written here */ ); /* -** CAPI3REF: Result Codes {F10210} +** CAPI3REF: Result Codes {H10210} <S10700> ** KEYWORDS: SQLITE_OK {error code} {error codes} +** KEYWORDS: {result code} {result codes} ** ** Many SQLite functions return an integer result code from the set shown ** here in order to indicates success or failure. ** +** New error codes may be added in future versions of SQLite. +** ** See also: [SQLITE_IOERR_READ | extended result codes] */ #define SQLITE_OK 0 /* Successful result */ @@ -808,20 +886,20 @@ SQLITE_API int sqlite3_exec( /* end-of-error-codes */ /* -** CAPI3REF: Extended Result Codes {F10220} +** CAPI3REF: Extended Result Codes {H10220} <S10700> ** KEYWORDS: {extended error code} {extended error codes} -** KEYWORDS: {extended result codes} +** KEYWORDS: {extended result code} {extended result codes} ** ** In its default configuration, SQLite API routines return one of 26 integer -** [SQLITE_OK | result codes]. However, experience has shown that -** many of these result codes are too course-grained. They do not provide as +** [SQLITE_OK | result codes]. However, experience has shown that many of +** these result codes are too coarse-grained. They do not provide as ** much information about problems as programmers might like. In an effort to ** address this, newer versions of SQLite (version 3.3.8 and later) include ** support for additional result codes that provide more detailed information ** about errors. The extended result codes are enabled or disabled -** for each database connection using the [sqlite3_extended_result_codes()] -** API. -** +** on a per database connection basis using the +** [sqlite3_extended_result_codes()] API. +** ** Some of the available extended result codes are listed here. ** One may expect the number of extended result codes will be expand ** over time. Software that uses extended result codes should expect @@ -829,35 +907,37 @@ SQLITE_API int sqlite3_exec( ** ** The SQLITE_OK result code will never be extended. It will always ** be exactly zero. -** +** ** INVARIANTS: ** -** {F10223} The symbolic name for an extended result code always contains +** {H10223} The symbolic name for an extended result code shall contains ** a related primary result code as a prefix. ** -** {F10224} Primary result code names contain a single "_" character. +** {H10224} Primary result code names shall contain a single "_" character. ** -** {F10225} Extended result code names contain two or more "_" characters. +** {H10225} Extended result code names shall contain two or more "_" characters. ** -** {F10226} The numeric value of an extended result code contains the +** {H10226} The numeric value of an extended result code shall contain the ** numeric value of its corresponding primary result code in ** its least significant 8 bits. */ -#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) -#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) -#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) -#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) -#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) -#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) -#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) -#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) -#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) -#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) -#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) -#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8)) +#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) +#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) +#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) +#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) +#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) +#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) +#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) +#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) +#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) +#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) +#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) +#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8)) +#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8)) +#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8)) /* -** CAPI3REF: Flags For File Open Operations {F10230} +** CAPI3REF: Flags For File Open Operations {H10230} <H11120> <H12700> ** ** These bit values are intended for use in the ** 3rd parameter to the [sqlite3_open_v2()] interface and @@ -876,9 +956,10 @@ SQLITE_API int sqlite3_exec( #define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 #define SQLITE_OPEN_SUBJOURNAL 0x00002000 #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 +#define SQLITE_OPEN_NOMUTEX 0x00008000 /* -** CAPI3REF: Device Characteristics {F10240} +** CAPI3REF: Device Characteristics {H10240} <H11120> ** ** The xDeviceCapabilities method of the [sqlite3_io_methods] ** object returns an integer which is a vector of the these @@ -910,7 +991,7 @@ SQLITE_API int sqlite3_exec( #define SQLITE_IOCAP_SEQUENTIAL 0x00000400 /* -** CAPI3REF: File Locking Levels {F10250} +** CAPI3REF: File Locking Levels {H10250} <H11120> <H11310> ** ** SQLite uses one of these integer values as the second ** argument to calls it makes to the xLock() and xUnlock() methods @@ -923,7 +1004,7 @@ SQLITE_API int sqlite3_exec( #define SQLITE_LOCK_EXCLUSIVE 4 /* -** CAPI3REF: Synchronization Type Flags {F10260} +** CAPI3REF: Synchronization Type Flags {H10260} <H11120> ** ** When SQLite invokes the xSync() method of an ** [sqlite3_io_methods] object it uses a combination of @@ -931,17 +1012,16 @@ SQLITE_API int sqlite3_exec( ** ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the ** sync operation only needs to flush data to mass storage. Inode -** information need not be flushed. The SQLITE_SYNC_NORMAL flag means -** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means +** information need not be flushed. The SQLITE_SYNC_NORMAL flag means +** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means ** to use Mac OS-X style fullsync instead of fsync(). */ #define SQLITE_SYNC_NORMAL 0x00002 #define SQLITE_SYNC_FULL 0x00003 #define SQLITE_SYNC_DATAONLY 0x00010 - /* -** CAPI3REF: OS Interface Open File Handle {F11110} +** CAPI3REF: OS Interface Open File Handle {H11110} <S20110> ** ** An [sqlite3_file] object represents an open file in the OS ** interface layer. Individual OS interface implementations will @@ -956,19 +1036,20 @@ struct sqlite3_file { }; /* -** CAPI3REF: OS Interface File Virtual Methods Object {F11120} +** CAPI3REF: OS Interface File Virtual Methods Object {H11120} <S20110> ** -** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to -** an instance of this object. This object defines the -** methods used to perform various operations against the open file. +** Every file opened by the [sqlite3_vfs] xOpen method populates an +** [sqlite3_file] object (or, more commonly, a subclass of the +** [sqlite3_file] object) with a pointer to an instance of this object. +** This object defines the methods used to perform various operations +** against the open file represented by the [sqlite3_file] object. ** ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync(). -* The second choice is an -** OS-X style fullsync. The SQLITE_SYNC_DATA flag may be ORed in to -** indicate that only the data of the file and not its inode needs to be -** synced. -** +** The second choice is a Mac OS-X style fullsync. The [SQLITE_SYNC_DATAONLY] +** flag may be ORed in to indicate that only the data of the file +** and not its inode needs to be synced. +** ** The integer values to xLock() and xUnlock() are one of ** <ul> ** <li> [SQLITE_LOCK_NONE], @@ -977,26 +1058,24 @@ struct sqlite3_file { ** <li> [SQLITE_LOCK_PENDING], or ** <li> [SQLITE_LOCK_EXCLUSIVE]. ** </ul> -** xLock() increases the lock. xUnlock() decreases the lock. -** The xCheckReservedLock() method looks -** to see if any database connection, either in this -** process or in some other process, is holding an RESERVED, +** xLock() increases the lock. xUnlock() decreases the lock. +** The xCheckReservedLock() method checks whether any database connection, +** either in this process or in some other process, is holding a RESERVED, ** PENDING, or EXCLUSIVE lock on the file. It returns true -** if such a lock exists and false if not. -** +** if such a lock exists and false otherwise. +** ** The xFileControl() method is a generic interface that allows custom ** VFS implementations to directly control an open file using the -** [sqlite3_file_control()] interface. The second "op" argument -** is an integer opcode. The third -** argument is a generic pointer which is intended to be a pointer -** to a structure that may contain arguments or space in which to +** [sqlite3_file_control()] interface. The second "op" argument is an +** integer opcode. The third argument is a generic pointer intended to +** point to a structure that may contain arguments or space in which to ** write return values. Potential uses for xFileControl() might be ** functions to enable blocking locks with timeouts, to change the ** locking strategy (for example to use dot-file locks), to inquire ** about the status of a lock, or to break stale locks. The SQLite -** core reserves opcodes less than 100 for its own use. +** core reserves all opcodes less than 100 for its own use. ** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available. -** Applications that define a custom xFileControl method should use opcodes +** Applications that define a custom xFileControl method should use opcodes ** greater than 100 to avoid conflicts. ** ** The xSectorSize() method returns the sector size of the @@ -1042,7 +1121,7 @@ struct sqlite3_io_methods { int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize); int (*xLock)(sqlite3_file*, int); int (*xUnlock)(sqlite3_file*, int); - int (*xCheckReservedLock)(sqlite3_file*); + int (*xCheckReservedLock)(sqlite3_file*, int *pResOut); int (*xFileControl)(sqlite3_file*, int op, void *pArg); int (*xSectorSize)(sqlite3_file*); int (*xDeviceCharacteristics)(sqlite3_file*); @@ -1050,10 +1129,10 @@ struct sqlite3_io_methods { }; /* -** CAPI3REF: Standard File Control Opcodes {F11310} +** CAPI3REF: Standard File Control Opcodes {H11310} <S30800> ** ** These integer constants are opcodes for the xFileControl method -** of the [sqlite3_io_methods] object and to the [sqlite3_file_control()] +** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()] ** interface. ** ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This @@ -1067,7 +1146,7 @@ struct sqlite3_io_methods { #define SQLITE_FCNTL_LOCKSTATE 1 /* -** CAPI3REF: Mutex Handle {F17110} +** CAPI3REF: Mutex Handle {H17110} <S20130> ** ** The mutex module within SQLite defines [sqlite3_mutex] to be an ** abstract type for a mutex object. The SQLite core never looks @@ -1079,15 +1158,18 @@ struct sqlite3_io_methods { typedef struct sqlite3_mutex sqlite3_mutex; /* -** CAPI3REF: OS Interface Object {F11140} +** CAPI3REF: OS Interface Object {H11140} <S20100> ** -** An instance of this object defines the interface between the -** SQLite core and the underlying operating system. The "vfs" +** An instance of the sqlite3_vfs object defines the interface between +** the SQLite core and the underlying operating system. The "vfs" ** in the name of the object stands for "virtual file system". ** -** The iVersion field is initially 1 but may be larger for future -** versions of SQLite. Additional fields may be appended to this -** object when the iVersion value is increased. +** The value of the iVersion field is initially 1 but may be larger in +** future versions of SQLite. Additional fields may be appended to this +** object when the iVersion value is increased. Note that the structure +** of the sqlite3_vfs object changes in the transaction between +** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not +** modified. ** ** The szOsFile field is the size of the subclassed [sqlite3_file] ** structure used by this VFS. mxPathname is the maximum length of @@ -1097,9 +1179,10 @@ typedef struct sqlite3_mutex sqlite3_mutex; ** the pNext pointer. The [sqlite3_vfs_register()] ** and [sqlite3_vfs_unregister()] interfaces manage this list ** in a thread-safe way. The [sqlite3_vfs_find()] interface -** searches the list. +** searches the list. Neither the application code nor the VFS +** implementation should use the pNext pointer. ** -** The pNext field is the only field in the sqlite3_vfs +** The pNext field is the only field in the sqlite3_vfs ** structure that SQLite will ever modify. SQLite will only access ** or modify this field while holding a particular static mutex. ** The application should never modify anything within the sqlite3_vfs @@ -1108,23 +1191,28 @@ typedef struct sqlite3_mutex sqlite3_mutex; ** The zName field holds the name of the VFS module. The name must ** be unique across all VFS modules. ** -** {F11141} SQLite will guarantee that the zFilename string passed to -** xOpen() is a full pathname as generated by xFullPathname() and -** that the string will be valid and unchanged until xClose() is -** called. {END} So the [sqlite3_file] can store a pointer to the +** {H11141} SQLite will guarantee that the zFilename parameter to xOpen +** is either a NULL pointer or string obtained +** from xFullPathname(). SQLite further guarantees that +** the string will be valid and unchanged until xClose() is +** called. {END} Because of the previous sentense, +** the [sqlite3_file] can safely store a pointer to the ** filename if it needs to remember the filename for some reason. +** If the zFilename parameter is xOpen is a NULL pointer then xOpen +** must invite its own temporary name for the file. Whenever the +** xFilename parameter is NULL it will also be the case that the +** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE]. ** -** {F11142} The flags argument to xOpen() includes all bits set in +** {H11142} The flags argument to xOpen() includes all bits set in ** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()] ** or [sqlite3_open16()] is used, then flags includes at least ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. {END} ** If xOpen() opens a file read-only then it sets *pOutFlags to -** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be -** set. -** -** {F11143} SQLite will also add one of the following flags to the xOpen() +** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set. +** +** {H11143} SQLite will also add one of the following flags to the xOpen() ** call, depending on the object being opened: -** +** ** <ul> ** <li> [SQLITE_OPEN_MAIN_DB] ** <li> [SQLITE_OPEN_MAIN_JOURNAL] @@ -1136,59 +1224,56 @@ typedef struct sqlite3_mutex sqlite3_mutex; ** </ul> {END} ** ** The file I/O implementation can use the object type flags to -** changes the way it deals with files. For example, an application +** change the way it deals with files. For example, an application ** that does not care about crash recovery or rollback might make ** the open of a journal file a no-op. Writes to this journal would -** also be no-ops, and any attempt to read the journal would return -** SQLITE_IOERR. Or the implementation might recognize that a database -** file will be doing page-aligned sector reads and writes in a random +** also be no-ops, and any attempt to read the journal would return +** SQLITE_IOERR. Or the implementation might recognize that a database +** file will be doing page-aligned sector reads and writes in a random ** order and set up its I/O subsystem accordingly. -** -** SQLite might also add one of the following flags to the xOpen -** method: -** +** +** SQLite might also add one of the following flags to the xOpen method: +** ** <ul> ** <li> [SQLITE_OPEN_DELETEONCLOSE] ** <li> [SQLITE_OPEN_EXCLUSIVE] ** </ul> -** -** {F11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be -** deleted when it is closed. {F11146} The [SQLITE_OPEN_DELETEONCLOSE] -** will be set for TEMP databases, journals and for subjournals. -** {F11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened +** +** {H11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be +** deleted when it is closed. {H11146} The [SQLITE_OPEN_DELETEONCLOSE] +** will be set for TEMP databases, journals and for subjournals. +** +** {H11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened ** for exclusive access. This flag is set for all files except -** for the main database file. {END} -** -** {F11148} At least szOsFile bytes of memory are allocated by SQLite -** to hold the [sqlite3_file] structure passed as the third -** argument to xOpen. {END} The xOpen method does not have to +** for the main database file. +** +** {H11148} At least szOsFile bytes of memory are allocated by SQLite +** to hold the [sqlite3_file] structure passed as the third +** argument to xOpen. {END} The xOpen method does not have to ** allocate the structure; it should just fill it in. -** -** {F11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] -** to test for the existance of a file, -** or [SQLITE_ACCESS_READWRITE] to test to see -** if a file is readable and writable, or [SQLITE_ACCESS_READ] -** to test to see if a file is at least readable. {END} The file can be a +** +** {H11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] +** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to +** test whether a file is readable and writable, or [SQLITE_ACCESS_READ] +** to test whether a file is at least readable. {END} The file can be a ** directory. -** -** {F11150} SQLite will always allocate at least mxPathname+1 bytes for -** the output buffers for xGetTempname and xFullPathname. {F11151} The exact -** size of the output buffer is also passed as a parameter to both -** methods. {END} If the output buffer is not large enough, SQLITE_CANTOPEN -** should be returned. As this is handled as a fatal error by SQLite, -** vfs implementations should endeavor to prevent this by setting -** mxPathname to a sufficiently large value. -** +** +** {H11150} SQLite will always allocate at least mxPathname+1 bytes for the +** output buffer xFullPathname. {H11151} The exact size of the output buffer +** is also passed as a parameter to both methods. {END} If the output buffer +** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is +** handled as a fatal error by SQLite, vfs implementations should endeavor +** to prevent this by setting mxPathname to a sufficiently large value. +** ** The xRandomness(), xSleep(), and xCurrentTime() interfaces ** are not strictly a part of the filesystem, but they are ** included in the VFS structure for completeness. ** The xRandomness() function attempts to return nBytes bytes ** of good-quality randomness into zOut. The return value is -** the actual number of bytes of randomness obtained. The -** xSleep() method causes the calling thread to sleep for at +** the actual number of bytes of randomness obtained. +** The xSleep() method causes the calling thread to sleep for at ** least the number of microseconds given. The xCurrentTime() -** method returns a Julian Day Number for the current date and -** time. +** method returns a Julian Day Number for the current date and time. */ typedef struct sqlite3_vfs sqlite3_vfs; struct sqlite3_vfs { @@ -1201,8 +1286,7 @@ struct sqlite3_vfs { int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*, int flags, int *pOutFlags); int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir); - int (*xAccess)(sqlite3_vfs*, const char *zName, int flags); - int (*xGetTempname)(sqlite3_vfs*, int nOut, char *zOut); + int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut); int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut); void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename); void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg); @@ -1211,50 +1295,399 @@ struct sqlite3_vfs { int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut); int (*xSleep)(sqlite3_vfs*, int microseconds); int (*xCurrentTime)(sqlite3_vfs*, double*); + int (*xGetLastError)(sqlite3_vfs*, int, char *); /* New fields may be appended in figure versions. The iVersion ** value will increment whenever this happens. */ }; /* -** CAPI3REF: Flags for the xAccess VFS method {F11190} +** CAPI3REF: Flags for the xAccess VFS method {H11190} <H11140> ** -** {F11191} These integer constants can be used as the third parameter to +** {H11191} These integer constants can be used as the third parameter to ** the xAccess method of an [sqlite3_vfs] object. {END} They determine -** what kind of permissions the xAccess method is -** looking for. {F11192} With SQLITE_ACCESS_EXISTS, the xAccess method -** simply checks to see if the file exists. {F11193} With -** SQLITE_ACCESS_READWRITE, the xAccess method checks to see -** if the file is both readable and writable. {F11194} With -** SQLITE_ACCESS_READ the xAccess method -** checks to see if the file is readable. +** what kind of permissions the xAccess method is looking for. +** {H11192} With SQLITE_ACCESS_EXISTS, the xAccess method +** simply checks whether the file exists. +** {H11193} With SQLITE_ACCESS_READWRITE, the xAccess method +** checks whether the file is both readable and writable. +** {H11194} With SQLITE_ACCESS_READ, the xAccess method +** checks whether the file is readable. */ #define SQLITE_ACCESS_EXISTS 0 #define SQLITE_ACCESS_READWRITE 1 #define SQLITE_ACCESS_READ 2 /* -** CAPI3REF: Enable Or Disable Extended Result Codes {F12200} +** CAPI3REF: Initialize The SQLite Library {H10130} <S20000><S30100> +** +** The sqlite3_initialize() routine initializes the +** SQLite library. The sqlite3_shutdown() routine +** deallocates any resources that were allocated by sqlite3_initialize(). +** +** A call to sqlite3_initialize() is an "effective" call if it is +** the first time sqlite3_initialize() is invoked during the lifetime of +** the process, or if it is the first time sqlite3_initialize() is invoked +** following a call to sqlite3_shutdown(). Only an effective call +** of sqlite3_initialize() does any initialization. All other calls +** are harmless no-ops. +** +** Among other things, sqlite3_initialize() shall invoke +** sqlite3_os_init(). Similarly, sqlite3_shutdown() +** shall invoke sqlite3_os_end(). +** +** The sqlite3_initialize() routine returns SQLITE_OK on success. +** If for some reason, sqlite3_initialize() is unable to initialize +** the library (perhaps it is unable to allocate a needed resource such +** as a mutex) it returns an [error code] other than SQLITE_OK. +** +** The sqlite3_initialize() routine is called internally by many other +** SQLite interfaces so that an application usually does not need to +** invoke sqlite3_initialize() directly. For example, [sqlite3_open()] +** calls sqlite3_initialize() so the SQLite library will be automatically +** initialized when [sqlite3_open()] is called if it has not be initialized +** already. However, if SQLite is compiled with the SQLITE_OMIT_AUTOINIT +** compile-time option, then the automatic calls to sqlite3_initialize() +** are omitted and the application must call sqlite3_initialize() directly +** prior to using any other SQLite interface. For maximum portability, +** it is recommended that applications always invoke sqlite3_initialize() +** directly prior to using any other SQLite interface. Future releases +** of SQLite may require this. In other words, the behavior exhibited +** when SQLite is compiled with SQLITE_OMIT_AUTOINIT might become the +** default behavior in some future release of SQLite. +** +** The sqlite3_os_init() routine does operating-system specific +** initialization of the SQLite library. The sqlite3_os_end() +** routine undoes the effect of sqlite3_os_init(). Typical tasks +** performed by these routines include allocation or deallocation +** of static resources, initialization of global variables, +** setting up a default [sqlite3_vfs] module, or setting up +** a default configuration using [sqlite3_config()]. +** +** The application should never invoke either sqlite3_os_init() +** or sqlite3_os_end() directly. The application should only invoke +** sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init() +** interface is called automatically by sqlite3_initialize() and +** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate +** implementations for sqlite3_os_init() and sqlite3_os_end() +** are built into SQLite when it is compiled for unix, windows, or os/2. +** When built for other platforms (using the SQLITE_OS_OTHER=1 compile-time +** option) the application must supply a suitable implementation for +** sqlite3_os_init() and sqlite3_os_end(). An application-supplied +** implementation of sqlite3_os_init() or sqlite3_os_end() +** must return SQLITE_OK on success and some other [error code] upon +** failure. +*/ +SQLITE_API int sqlite3_initialize(void); +SQLITE_API int sqlite3_shutdown(void); +SQLITE_API int sqlite3_os_init(void); +SQLITE_API int sqlite3_os_end(void); + +/* +** CAPI3REF: Configuring The SQLite Library {H10145} <S20000><S30200> +** EXPERIMENTAL +** +** The sqlite3_config() interface is used to make global configuration +** changes to SQLite in order to tune SQLite to the specific needs of +** the application. The default configuration is recommended for most +** applications and so this routine is usually not necessary. It is +** provided to support rare applications with unusual needs. +** +** The sqlite3_config() interface is not threadsafe. The application +** must insure that no other SQLite interfaces are invoked by other +** threads while sqlite3_config() is running. Furthermore, sqlite3_config() +** may only be invoked prior to library initialization using +** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()]. +** Note, however, that sqlite3_config() can be called as part of the +** implementation of an application-defined [sqlite3_os_init()]. +** +** The first argument to sqlite3_config() is an integer +** [SQLITE_CONFIG_SINGLETHREAD | configuration option] that determines +** what property of SQLite is to be configured. Subsequent arguments +** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option] +** in the first argument. +** +** When a configuration option is set, sqlite3_config() returns SQLITE_OK. +** If the option is unknown or SQLite is unable to set the option +** then this routine returns a non-zero [error code]. +*/ +SQLITE_API int sqlite3_config(int, ...); + +/* +** CAPI3REF: Configure database connections {H10180} <S20000> +** EXPERIMENTAL +** +** The sqlite3_db_config() interface is used to make configuration +** changes to a [database connection]. The interface is similar to +** [sqlite3_config()] except that the changes apply to a single +** [database connection] (specified in the first argument). The +** sqlite3_db_config() interface can only be used immediately after +** the database connection is created using [sqlite3_open()], +** [sqlite3_open16()], or [sqlite3_open_v2()]. +** +** The second argument to sqlite3_db_config(D,V,...) is the +** configuration verb - an integer code that indicates what +** aspect of the [database connection] is being configured. +** The only choice for this value is [SQLITE_DBCONFIG_LOOKASIDE]. +** New verbs are likely to be added in future releases of SQLite. +** Additional arguments depend on the verb. +*/ +SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...); + +/* +** CAPI3REF: Memory Allocation Routines {H10155} <S20120> +** EXPERIMENTAL +** +** An instance of this object defines the interface between SQLite +** and low-level memory allocation routines. +** +** This object is used in only one place in the SQLite interface. +** A pointer to an instance of this object is the argument to +** [sqlite3_config()] when the configuration option is +** [SQLITE_CONFIG_MALLOC]. By creating an instance of this object +** and passing it to [sqlite3_config()] during configuration, an +** application can specify an alternative memory allocation subsystem +** for SQLite to use for all of its dynamic memory needs. +** +** Note that SQLite comes with a built-in memory allocator that is +** perfectly adequate for the overwhelming majority of applications +** and that this object is only useful to a tiny minority of applications +** with specialized memory allocation requirements. This object is +** also used during testing of SQLite in order to specify an alternative +** memory allocator that simulates memory out-of-memory conditions in +** order to verify that SQLite recovers gracefully from such +** conditions. +** +** The xMalloc, xFree, and xRealloc methods must work like the +** malloc(), free(), and realloc() functions from the standard library. +** +** xSize should return the allocated size of a memory allocation +** previously obtained from xMalloc or xRealloc. The allocated size +** is always at least as big as the requested size but may be larger. +** +** The xRoundup method returns what would be the allocated size of +** a memory allocation given a particular requested size. Most memory +** allocators round up memory allocations at least to the next multiple +** of 8. Some allocators round up to a larger multiple or to a power of 2. +** +** The xInit method initializes the memory allocator. (For example, +** it might allocate any require mutexes or initialize internal data +** structures. The xShutdown method is invoked (indirectly) by +** [sqlite3_shutdown()] and should deallocate any resources acquired +** by xInit. The pAppData pointer is used as the only parameter to +** xInit and xShutdown. +*/ +typedef struct sqlite3_mem_methods sqlite3_mem_methods; +struct sqlite3_mem_methods { + void *(*xMalloc)(int); /* Memory allocation function */ + void (*xFree)(void*); /* Free a prior allocation */ + void *(*xRealloc)(void*,int); /* Resize an allocation */ + int (*xSize)(void*); /* Return the size of an allocation */ + int (*xRoundup)(int); /* Round up request size to allocation size */ + int (*xInit)(void*); /* Initialize the memory allocator */ + void (*xShutdown)(void*); /* Deinitialize the memory allocator */ + void *pAppData; /* Argument to xInit() and xShutdown() */ +}; + +/* +** CAPI3REF: Configuration Options {H10160} <S20000> +** EXPERIMENTAL +** +** These constants are the available integer configuration options that +** can be passed as the first argument to the [sqlite3_config()] interface. +** +** New configuration options may be added in future releases of SQLite. +** Existing configuration options might be discontinued. Applications +** should check the return code from [sqlite3_config()] to make sure that +** the call worked. The [sqlite3_config()] interface will return a +** non-zero [error code] if a discontinued or unsupported configuration option +** is invoked. +** +** <dl> +** <dt>SQLITE_CONFIG_SINGLETHREAD</dt> +** <dd>There are no arguments to this option. This option disables +** all mutexing and puts SQLite into a mode where it can only be used +** by a single thread.</dd> +** +** <dt>SQLITE_CONFIG_MULTITHREAD</dt> +** <dd>There are no arguments to this option. This option disables +** mutexing on [database connection] and [prepared statement] objects. +** The application is responsible for serializing access to +** [database connections] and [prepared statements]. But other mutexes +** are enabled so that SQLite will be safe to use in a multi-threaded +** environment.</dd> +** +** <dt>SQLITE_CONFIG_SERIALIZED</dt> +** <dd>There are no arguments to this option. This option enables +** all mutexes including the recursive +** mutexes on [database connection] and [prepared statement] objects. +** In this mode (which is the default when SQLite is compiled with +** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access +** to [database connections] and [prepared statements] so that the +** application is free to use the same [database connection] or the +** same [prepared statement] in different threads at the same time. +** +** <p>This configuration option merely sets the default mutex +** behavior to serialize access to [database connections]. Individual +** [database connections] can override this setting +** using the [SQLITE_OPEN_NOMUTEX] flag to [sqlite3_open_v2()].</p></dd> +** +** <dt>SQLITE_CONFIG_MALLOC</dt> +** <dd>This option takes a single argument which is a pointer to an +** instance of the [sqlite3_mem_methods] structure. The argument specifies +** alternative low-level memory allocation routines to be used in place of +** the memory allocation routines built into SQLite.</dd> +** +** <dt>SQLITE_CONFIG_GETMALLOC</dt> +** <dd>This option takes a single argument which is a pointer to an +** instance of the [sqlite3_mem_methods] structure. The [sqlite3_mem_methods] +** structure is filled with the currently defined memory allocation routines. +** This option can be used to overload the default memory allocation +** routines with a wrapper that simulations memory allocation failure or +** tracks memory usage, for example.</dd> +** +** <dt>SQLITE_CONFIG_MEMSTATUS</dt> +** <dd>This option takes single argument of type int, interpreted as a +** boolean, which enables or disables the collection of memory allocation +** statistics. When disabled, the following SQLite interfaces become +** non-operational: +** <ul> +** <li> [sqlite3_memory_used()] +** <li> [sqlite3_memory_highwater()] +** <li> [sqlite3_soft_heap_limit()] +** <li> [sqlite3_status()] +** </ul> +** </dd> +** +** <dt>SQLITE_CONFIG_SCRATCH</dt> +** <dd>This option specifies a static memory buffer that SQLite can use for +** scratch memory. There are three arguments: A pointer to the memory, the +** size of each scratch buffer (sz), and the number of buffers (N). The sz +** argument must be a multiple of 16. The sz parameter should be a few bytes +** larger than the actual scratch space required due internal overhead. +** The first +** argument should point to an allocation of at least sz*N bytes of memory. +** SQLite will use no more than one scratch buffer at once per thread, so +** N should be set to the expected maximum number of threads. The sz +** parameter should be 6 times the size of the largest database page size. +** Scratch buffers are used as part of the btree balance operation. If +** The btree balancer needs additional memory beyond what is provided by +** scratch buffers or if no scratch buffer space is specified, then SQLite +** goes to [sqlite3_malloc()] to obtain the memory it needs.</dd> +** +** <dt>SQLITE_CONFIG_PAGECACHE</dt> +** <dd>This option specifies a static memory buffer that SQLite can use for +** the database page cache. There are three arguments: A pointer to the +** memory, the size of each page buffer (sz), and the number of pages (N). +** The sz argument must be a power of two between 512 and 32768. The first +** argument should point to an allocation of at least sz*N bytes of memory. +** SQLite will use the memory provided by the first argument to satisfy its +** memory needs for the first N pages that it adds to cache. If additional +** page cache memory is needed beyond what is provided by this option, then +** SQLite goes to [sqlite3_malloc()] for the additional storage space. +** The implementation might use one or more of the N buffers to hold +** memory accounting information. </dd> +** +** <dt>SQLITE_CONFIG_HEAP</dt> +** <dd>This option specifies a static memory buffer that SQLite will use +** for all of its dynamic memory allocation needs beyond those provided +** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE]. +** There are three arguments: A pointer to the memory, the number of +** bytes in the memory buffer, and the minimum allocation size. If +** the first pointer (the memory pointer) is NULL, then SQLite reverts +** to using its default memory allocator (the system malloc() implementation), +** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. If the +** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or +** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory +** allocator is engaged to handle all of SQLites memory allocation needs.</dd> +** +** <dt>SQLITE_CONFIG_MUTEX</dt> +** <dd>This option takes a single argument which is a pointer to an +** instance of the [sqlite3_mutex_methods] structure. The argument specifies +** alternative low-level mutex routines to be used in place +** the mutex routines built into SQLite.</dd> +** +** <dt>SQLITE_CONFIG_GETMUTEX</dt> +** <dd>This option takes a single argument which is a pointer to an +** instance of the [sqlite3_mutex_methods] structure. The +** [sqlite3_mutex_methods] +** structure is filled with the currently defined mutex routines. +** This option can be used to overload the default mutex allocation +** routines with a wrapper used to track mutex usage for performance +** profiling or testing, for example.</dd> +** +** <dt>SQLITE_CONFIG_LOOKASIDE</dt> +** <dd>This option takes two arguments that determine the default +** memory allcation lookaside optimization. The first argument is the +** size of each lookaside buffer slot and the second is the number of +** slots allocated to each database connection.</dd> +** +** </dl> +*/ +#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ +#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ +#define SQLITE_CONFIG_SERIALIZED 3 /* nil */ +#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */ +#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */ +#define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */ +#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ +#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ +#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ +#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ +#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ +#define SQLITE_CONFIG_CHUNKALLOC 12 /* int threshold */ +#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */ + +/* +** CAPI3REF: Configuration Options {H10170} <S20000> +** EXPERIMENTAL +** +** These constants are the available integer configuration options that +** can be passed as the second argument to the [sqlite3_db_config()] interface. +** +** New configuration options may be added in future releases of SQLite. +** Existing configuration options might be discontinued. Applications +** should check the return code from [sqlite3_db_config()] to make sure that +** the call worked. The [sqlite3_db_config()] interface will return a +** non-zero [error code] if a discontinued or unsupported configuration option +** is invoked. +** +** <dl> +** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt> +** <dd>This option takes three additional arguments that determine the +** [lookaside memory allocator] configuration for the [database connection]. +** The first argument (the third parameter to [sqlite3_db_config()] is a +** pointer to a memory buffer to use for lookaside memory. The first +** argument may be NULL in which case SQLite will allocate the lookaside +** buffer itself using [sqlite3_malloc()]. The second argument is the +** size of each lookaside buffer slot and the third argument is the number of +** slots. The size of the buffer in the first argument must be greater than +** or equal to the product of the second and third arguments.</dd> +** +** </dl> +*/ +#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ + + +/* +** CAPI3REF: Enable Or Disable Extended Result Codes {H12200} <S10700> ** ** The sqlite3_extended_result_codes() routine enables or disables the -** [SQLITE_IOERR_READ | extended result codes] feature of SQLite. -** The extended result codes are disabled by default for historical -** compatibility. +** [extended result codes] feature of SQLite. The extended result +** codes are disabled by default for historical compatibility considerations. ** ** INVARIANTS: ** -** {F12201} Each new [database connection] has the -** [extended result codes] feature -** disabled by default. +** {H12201} Each new [database connection] shall have the +** [extended result codes] feature disabled by default. ** -** {F12202} The [sqlite3_extended_result_codes(D,F)] interface will enable -** [extended result codes] for the -** [database connection] D if the F parameter -** is true, or disable them if F is false. +** {H12202} The [sqlite3_extended_result_codes(D,F)] interface shall enable +** [extended result codes] for the [database connection] D +** if the F parameter is true, or disable them if F is false. */ SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff); /* -** CAPI3REF: Last Insert Rowid {F12220} +** CAPI3REF: Last Insert Rowid {H12220} <S10700> ** ** Each entry in an SQLite table has a unique 64-bit signed ** integer key called the "rowid". The rowid is always available @@ -1264,44 +1697,42 @@ SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff); ** is another alias for the rowid. ** ** This routine returns the rowid of the most recent -** successful INSERT into the database from the database connection -** shown in the first argument. If no successful inserts -** have ever occurred on this database connection, zero is returned. +** successful INSERT into the database from the [database connection] +** in the first argument. If no successful INSERTs +** have ever occurred on that database connection, zero is returned. ** -** If an INSERT occurs within a trigger, then the rowid of the -** inserted row is returned by this routine as long as the trigger -** is running. But once the trigger terminates, the value returned -** by this routine reverts to the last value inserted before the -** trigger fired. +** If an INSERT occurs within a trigger, then the rowid of the inserted +** row is returned by this routine as long as the trigger is running. +** But once the trigger terminates, the value returned by this routine +** reverts to the last value inserted before the trigger fired. ** ** An INSERT that fails due to a constraint violation is not a -** successful insert and does not change the value returned by this +** successful INSERT and does not change the value returned by this ** routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK, ** and INSERT OR ABORT make no changes to the return value of this -** routine when their insertion fails. When INSERT OR REPLACE +** routine when their insertion fails. When INSERT OR REPLACE ** encounters a constraint violation, it does not fail. The ** INSERT continues to completion after deleting rows that caused ** the constraint problem so INSERT OR REPLACE will always change -** the return value of this interface. +** the return value of this interface. ** -** For the purposes of this routine, an insert is considered to +** For the purposes of this routine, an INSERT is considered to ** be successful even if it is subsequently rolled back. ** ** INVARIANTS: ** -** {F12221} The [sqlite3_last_insert_rowid()] function returns the -** rowid of the most recent successful insert done -** on the same database connection and within the same -** trigger context, or zero if there have -** been no qualifying inserts on that connection. +** {H12221} The [sqlite3_last_insert_rowid()] function returns the rowid +** of the most recent successful INSERT performed on the same +** [database connection] and within the same or higher level +** trigger context, or zero if there have been no qualifying inserts. ** -** {F12223} The [sqlite3_last_insert_rowid()] function returns +** {H12223} The [sqlite3_last_insert_rowid()] function returns the ** same value when called from the same trigger context ** immediately before and after a ROLLBACK. ** -** LIMITATIONS: +** ASSUMPTIONS: ** -** {U12232} If a separate thread does a new insert on the same +** {A12232} If a separate thread performs a new INSERT on the same ** database connection while the [sqlite3_last_insert_rowid()] ** function is running and thus changes the last insert rowid, ** then the value returned by [sqlite3_last_insert_rowid()] is @@ -1311,13 +1742,13 @@ SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff); SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); /* -** CAPI3REF: Count The Number Of Rows Modified {F12240} +** CAPI3REF: Count The Number Of Rows Modified {H12240} <S10600> ** ** This function returns the number of database rows that were changed ** or inserted or deleted by the most recently completed SQL statement -** on the connection specified by the first parameter. Only -** changes that are directly specified by the INSERT, UPDATE, or -** DELETE statement are counted. Auxiliary changes caused by +** on the [database connection] specified by the first parameter. +** Only changes that are directly specified by the INSERT, UPDATE, +** or DELETE statement are counted. Auxiliary changes caused by ** triggers are not counted. Use the [sqlite3_total_changes()] function ** to find the total number of changes including changes caused by triggers. ** @@ -1341,84 +1772,89 @@ SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); ** most recent INSERT, UPDATE, or DELETE statement within the same ** trigger context. ** -** So when called from the top level, this function returns the +** Thus, when called from the top level, this function returns the ** number of changes in the most recent INSERT, UPDATE, or DELETE -** that also occurred at the top level. -** Within the body of a trigger, the sqlite3_changes() interface -** can be called to find the number of +** that also occurred at the top level. Within the body of a trigger, +** the sqlite3_changes() interface can be called to find the number of ** changes in the most recently completed INSERT, UPDATE, or DELETE ** statement within the body of the same trigger. -** However, the number returned does not include in changes -** caused by subtriggers since they have their own context. -** -** SQLite implements the command "DELETE FROM table" without -** a WHERE clause by dropping and recreating the table. (This is much -** faster than going through and deleting individual elements from the -** table.) Because of this optimization, the deletions in -** "DELETE FROM table" are not row changes and will not be counted -** by the sqlite3_changes() or [sqlite3_total_changes()] functions. -** To get an accurate count of the number of rows deleted, use +** However, the number returned does not include changes +** caused by subtriggers since those have their own context. +** +** SQLite implements the command "DELETE FROM table" without a WHERE clause +** by dropping and recreating the table. (This is much faster than going +** through and deleting individual elements from the table.) Because of this +** optimization, the deletions in "DELETE FROM table" are not row changes and +** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()] +** functions, regardless of the number of elements that were originally +** in the table. To get an accurate count of the number of rows deleted, use ** "DELETE FROM table WHERE 1" instead. ** ** INVARIANTS: ** -** {F12241} The [sqlite3_changes()] function returns the number of +** {H12241} The [sqlite3_changes()] function shall return the number of ** row changes caused by the most recent INSERT, UPDATE, ** or DELETE statement on the same database connection and -** within the same trigger context, or zero if there have +** within the same or higher trigger context, or zero if there have ** not been any qualifying row changes. ** -** LIMITATIONS: +** {H12243} Statements of the form "DELETE FROM tablename" with no +** WHERE clause shall cause subsequent calls to +** [sqlite3_changes()] to return zero, regardless of the +** number of rows originally in the table. ** -** {U12252} If a separate thread makes changes on the same database connection +** ASSUMPTIONS: +** +** {A12252} If a separate thread makes changes on the same database connection ** while [sqlite3_changes()] is running then the value returned -** is unpredictable and unmeaningful. +** is unpredictable and not meaningful. */ SQLITE_API int sqlite3_changes(sqlite3*); /* -** CAPI3REF: Total Number Of Rows Modified {F12260} -*** -** This function returns the number of row changes caused -** by INSERT, UPDATE or DELETE statements since the database handle -** was opened. The count includes all changes from all trigger -** contexts. But the count does not include changes used to -** implement REPLACE constraints, do rollbacks or ABORT processing, -** or DROP table processing. -** The changes -** are counted as soon as the statement that makes them is completed -** (when the statement handle is passed to [sqlite3_reset()] or +** CAPI3REF: Total Number Of Rows Modified {H12260} <S10600> +** +** This function returns the number of row changes caused by INSERT, +** UPDATE or DELETE statements since the [database connection] was opened. +** The count includes all changes from all trigger contexts. However, +** the count does not include changes used to implement REPLACE constraints, +** do rollbacks or ABORT processing, or DROP table processing. +** The changes are counted as soon as the statement that makes them is +** completed (when the statement handle is passed to [sqlite3_reset()] or ** [sqlite3_finalize()]). ** -** SQLite implements the command "DELETE FROM table" without -** a WHERE clause by dropping and recreating the table. (This is much -** faster than going -** through and deleting individual elements from the table.) Because of -** this optimization, the change count for "DELETE FROM table" will be -** zero regardless of the number of elements that were originally in the -** table. To get an accurate count of the number of rows deleted, use +** SQLite implements the command "DELETE FROM table" without a WHERE clause +** by dropping and recreating the table. (This is much faster than going +** through and deleting individual elements from the table.) Because of this +** optimization, the deletions in "DELETE FROM table" are not row changes and +** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()] +** functions, regardless of the number of elements that were originally +** in the table. To get an accurate count of the number of rows deleted, use ** "DELETE FROM table WHERE 1" instead. ** ** See also the [sqlite3_changes()] interface. ** ** INVARIANTS: -** -** {F12261} The [sqlite3_total_changes()] returns the total number +** +** {H12261} The [sqlite3_total_changes()] returns the total number ** of row changes caused by INSERT, UPDATE, and/or DELETE ** statements on the same [database connection], in any -** trigger context, since the database connection was -** created. +** trigger context, since the database connection was created. +** +** {H12263} Statements of the form "DELETE FROM tablename" with no +** WHERE clause shall not change the value returned +** by [sqlite3_total_changes()]. ** -** LIMITATIONS: +** ASSUMPTIONS: ** -** {U12264} If a separate thread makes changes on the same database connection -** while [sqlite3_total_changes()] is running then the value -** returned is unpredictable and unmeaningful. +** {A12264} If a separate thread makes changes on the same database connection +** while [sqlite3_total_changes()] is running then the value +** returned is unpredictable and not meaningful. */ SQLITE_API int sqlite3_total_changes(sqlite3*); /* -** CAPI3REF: Interrupt A Long-Running Query {F12270} +** CAPI3REF: Interrupt A Long-Running Query {H12270} <S30500> ** ** This function causes any pending database operation to abort and ** return at its earliest opportunity. This routine is typically @@ -1428,38 +1864,39 @@ SQLITE_API int sqlite3_total_changes(sqlite3*); ** ** It is safe to call this routine from a thread different from the ** thread that is currently running the database operation. But it -** is not safe to call this routine with a database connection that +** is not safe to call this routine with a [database connection] that ** is closed or might close before sqlite3_interrupt() returns. ** -** If an SQL is very nearly finished at the time when sqlite3_interrupt() -** is called, then it might not have an opportunity to be interrupted. -** It might continue to completion. -** An SQL operation that is interrupted will return -** [SQLITE_INTERRUPT]. If the interrupted SQL operation is an -** INSERT, UPDATE, or DELETE that is inside an explicit transaction, -** then the entire transaction will be rolled back automatically. +** If an SQL operation is very nearly finished at the time when +** sqlite3_interrupt() is called, then it might not have an opportunity +** to be interrupted and might continue to completion. +** +** An SQL operation that is interrupted will return [SQLITE_INTERRUPT]. +** If the interrupted SQL operation is an INSERT, UPDATE, or DELETE +** that is inside an explicit transaction, then the entire transaction +** will be rolled back automatically. +** ** A call to sqlite3_interrupt() has no effect on SQL statements ** that are started after sqlite3_interrupt() returns. ** ** INVARIANTS: ** -** {F12271} The [sqlite3_interrupt()] interface will force all running +** {H12271} The [sqlite3_interrupt()] interface will force all running ** SQL statements associated with the same database connection -** to halt after processing at most one additional row of -** data. +** to halt after processing at most one additional row of data. ** -** {F12272} Any SQL statement that is interrupted by [sqlite3_interrupt()] +** {H12272} Any SQL statement that is interrupted by [sqlite3_interrupt()] ** will return [SQLITE_INTERRUPT]. ** -** LIMITATIONS: +** ASSUMPTIONS: ** -** {U12279} If the database connection closes while [sqlite3_interrupt()] +** {A12279} If the database connection closes while [sqlite3_interrupt()] ** is running then bad things will likely happen. */ SQLITE_API void sqlite3_interrupt(sqlite3*); /* -** CAPI3REF: Determine If An SQL Statement Is Complete {F10510} +** CAPI3REF: Determine If An SQL Statement Is Complete {H10510} <S70200> ** ** These routines are useful for command-line input to determine if the ** currently entered text seems to form complete a SQL statement or @@ -1472,54 +1909,56 @@ SQLITE_API void sqlite3_interrupt(sqlite3*); ** independent tokens (they are part of the token in which they are ** embedded) and thus do not count as a statement terminator. ** -** These routines do not parse the SQL and -** so will not detect syntactically incorrect SQL. +** These routines do not parse the SQL statements thus +** will not detect syntactically incorrect SQL. ** ** INVARIANTS: ** -** {F10511} The sqlite3_complete() and sqlite3_complete16() functions -** return true (non-zero) if and only if the last -** non-whitespace token in their input is a semicolon that -** is not in between the BEGIN and END of a CREATE TRIGGER -** statement. +** {H10511} A successful evaluation of [sqlite3_complete()] or +** [sqlite3_complete16()] functions shall +** return a numeric 1 if and only if the last non-whitespace +** token in their input is a semicolon that is not in between +** the BEGIN and END of a CREATE TRIGGER statement. +** +** {H10512} If a memory allocation error occurs during an invocation +** of [sqlite3_complete()] or [sqlite3_complete16()] then the +** routine shall return [SQLITE_NOMEM]. ** -** LIMITATIONS: +** ASSUMPTIONS: ** -** {U10512} The input to sqlite3_complete() must be a zero-terminated +** {A10512} The input to [sqlite3_complete()] must be a zero-terminated ** UTF-8 string. ** -** {U10513} The input to sqlite3_complete16() must be a zero-terminated +** {A10513} The input to [sqlite3_complete16()] must be a zero-terminated ** UTF-16 string in native byte order. */ SQLITE_API int sqlite3_complete(const char *sql); SQLITE_API int sqlite3_complete16(const void *sql); /* -** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {F12310} -** -** This routine identifies a callback function that might be -** invoked whenever an attempt is made to open a database table -** that another thread or process has locked. -** If the busy callback is NULL, then [SQLITE_BUSY] -** or [SQLITE_IOERR_BLOCKED] -** is returned immediately upon encountering the lock. -** If the busy callback is not NULL, then the -** callback will be invoked with two arguments. The -** first argument to the handler is a copy of the void* pointer which -** is the third argument to this routine. The second argument to -** the handler is the number of times that the busy handler has -** been invoked for this locking event. If the +** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {H12310} <S40400> +** +** This routine sets a callback function that might be invoked whenever +** an attempt is made to open a database table that another thread +** or process has locked. +** +** If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] +** is returned immediately upon encountering the lock. If the busy callback +** is not NULL, then the callback will be invoked with two arguments. +** +** The first argument to the handler is a copy of the void* pointer which +** is the third argument to sqlite3_busy_handler(). The second argument to +** the handler callback is the number of times that the busy handler has +** been invoked for this locking event. If the ** busy callback returns 0, then no additional attempts are made to ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned. ** If the callback returns non-zero, then another attempt ** is made to open the database for reading and the cycle repeats. ** -** The presence of a busy handler does not guarantee that -** it will be invoked when there is lock contention. -** If SQLite determines that invoking the busy handler could result in -** a deadlock, it will go ahead and return [SQLITE_BUSY] or -** [SQLITE_IOERR_BLOCKED] instead of invoking the -** busy handler. +** The presence of a busy handler does not guarantee that it will be invoked +** when there is lock contention. If SQLite determines that invoking the busy +** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY] +** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler. ** Consider a scenario where one process is holding a read lock that ** it is trying to promote to a reserved lock and ** a second process is holding a reserved lock that it is trying @@ -1544,82 +1983,82 @@ SQLITE_API int sqlite3_complete16(const void *sql); ** code is promoted from the relatively benign [SQLITE_BUSY] to ** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion ** forces an automatic rollback of the changes. See the -** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError"> +** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError"> ** CorruptionFollowingBusyError</a> wiki page for a discussion of why ** this is important. -** -** There can only be a single busy handler defined for each database -** connection. Setting a new busy handler clears any previous one. -** Note that calling [sqlite3_busy_timeout()] will also set or clear -** the busy handler. +** +** There can only be a single busy handler defined for each +** [database connection]. Setting a new busy handler clears any +** previously set handler. Note that calling [sqlite3_busy_timeout()] +** will also set or clear the busy handler. ** ** INVARIANTS: ** -** {F12311} The [sqlite3_busy_handler()] function replaces the busy handler -** callback in the database connection identified by the 1st -** parameter with a new busy handler identified by the 2nd and 3rd -** parameters. +** {H12311} The [sqlite3_busy_handler(D,C,A)] function shall replace +** busy callback in the [database connection] D with a new +** a new busy handler C and application data pointer A. ** -** {F12312} The default busy handler for new database connections is NULL. +** {H12312} Newly created [database connections] shall have a busy +** handler of NULL. ** -** {F12314} When two or more database connection share a common cache, +** {H12314} When two or more [database connections] share a +** [sqlite3_enable_shared_cache | common cache], ** the busy handler for the database connection currently using -** the cache is invoked when the cache encounters a lock. +** the cache shall be invoked when the cache encounters a lock. ** -** {F12316} If a busy handler callback returns zero, then the SQLite -** interface that provoked the locking event will return -** [SQLITE_BUSY]. +** {H12316} If a busy handler callback returns zero, then the SQLite interface +** that provoked the locking event shall return [SQLITE_BUSY]. ** -** {F12318} SQLite will invokes the busy handler with two argument which +** {H12318} SQLite shall invokes the busy handler with two arguments which ** are a copy of the pointer supplied by the 3rd parameter to ** [sqlite3_busy_handler()] and a count of the number of prior ** invocations of the busy handler for the same locking event. ** -** LIMITATIONS: +** ASSUMPTIONS: ** -** {U12319} A busy handler should not call close the database connection -** or prepared statement that invoked the busy handler. +** {A12319} A busy handler must not close the database connection +** or [prepared statement] that invoked the busy handler. */ SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); /* -** CAPI3REF: Set A Busy Timeout {F12340} +** CAPI3REF: Set A Busy Timeout {H12340} <S40410> ** -** This routine sets a [sqlite3_busy_handler | busy handler] -** that sleeps for a while when a -** table is locked. The handler will sleep multiple times until -** at least "ms" milliseconds of sleeping have been done. {F12343} After -** "ms" milliseconds of sleeping, the handler returns 0 which -** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. +** This routine sets a [sqlite3_busy_handler | busy handler] that sleeps +** for a specified amount of time when a table is locked. The handler +** will sleep multiple times until at least "ms" milliseconds of sleeping +** have accumulated. {H12343} After "ms" milliseconds of sleeping, +** the handler returns 0 which causes [sqlite3_step()] to return +** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. ** ** Calling this routine with an argument less than or equal to zero ** turns off all busy handlers. ** -** There can only be a single busy handler for a particular database -** connection. If another busy handler was defined -** (using [sqlite3_busy_handler()]) prior to calling +** There can only be a single busy handler for a particular +** [database connection] any any given moment. If another busy handler +** was defined (using [sqlite3_busy_handler()]) prior to calling ** this routine, that other busy handler is cleared. ** ** INVARIANTS: ** -** {F12341} The [sqlite3_busy_timeout()] function overrides any prior +** {H12341} The [sqlite3_busy_timeout()] function shall override any prior ** [sqlite3_busy_timeout()] or [sqlite3_busy_handler()] setting -** on the same database connection. +** on the same [database connection]. ** -** {F12343} If the 2nd parameter to [sqlite3_busy_timeout()] is less than -** or equal to zero, then the busy handler is cleared so that +** {H12343} If the 2nd parameter to [sqlite3_busy_timeout()] is less than +** or equal to zero, then the busy handler shall be cleared so that ** all subsequent locking events immediately return [SQLITE_BUSY]. ** -** {F12344} If the 2nd parameter to [sqlite3_busy_timeout()] is a positive -** number N, then a busy handler is set that repeatedly calls -** the xSleep() method in the VFS interface until either the -** lock clears or until the cumulative sleep time reported back -** by xSleep() exceeds N milliseconds. +** {H12344} If the 2nd parameter to [sqlite3_busy_timeout()] is a positive +** number N, then a busy handler shall be set that repeatedly calls +** the xSleep() method in the [sqlite3_vfs | VFS interface] until +** either the lock clears or until the cumulative sleep time +** reported back by xSleep() exceeds N milliseconds. */ SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms); /* -** CAPI3REF: Convenience Routines For Running Queries {F12370} +** CAPI3REF: Convenience Routines For Running Queries {H12370} <S10000> ** ** Definition: A <b>result table</b> is memory data structure created by the ** [sqlite3_get_table()] interface. A result table records the @@ -1630,16 +2069,14 @@ SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms); ** numbers are obtained separately. Let N be the number of rows ** and M be the number of columns. ** -** A result table is an array of pointers to zero-terminated -** UTF-8 strings. There are (N+1)*M elements in the array. -** The first M pointers point to zero-terminated strings that -** contain the names of the columns. -** The remaining entries all point to query results. NULL -** values are give a NULL pointer. All other values are in -** their UTF-8 zero-terminated string representation as returned by -** [sqlite3_column_text()]. +** A result table is an array of pointers to zero-terminated UTF-8 strings. +** There are (N+1)*M elements in the array. The first M pointers point +** to zero-terminated strings that contain the names of the columns. +** The remaining entries all point to query results. NULL values result +** in NULL pointers. All other values are in their UTF-8 zero-terminated +** string representation as returned by [sqlite3_column_text()]. ** -** A result table might consists of one or more memory allocations. +** A result table might consist of one or more memory allocations. ** It is not safe to pass a result table directly to [sqlite3_free()]. ** A result table should be deallocated using [sqlite3_free_table()]. ** @@ -1674,11 +2111,11 @@ SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms); ** string of its 2nd parameter. It returns a result table to the ** pointer given in its 3rd parameter. ** -** After the calling function has finished using the result, it should -** pass the pointer to the result table to sqlite3_free_table() in order to -** release the memory that was malloc-ed. Because of the way the +** After the calling function has finished using the result, it should +** pass the pointer to the result table to sqlite3_free_table() in order to +** release the memory that was malloced. Because of the way the ** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling -** function must not try to call [sqlite3_free()] directly. Only +** function must not try to call [sqlite3_free()] directly. Only ** [sqlite3_free_table()] is able to release the memory properly and safely. ** ** The sqlite3_get_table() interface is implemented as a wrapper around @@ -1686,43 +2123,53 @@ SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms); ** to any internal data structures of SQLite. It uses only the public ** interface defined here. As a consequence, errors that occur in the ** wrapper layer outside of the internal [sqlite3_exec()] call are not -** reflected in subsequent calls to [sqlite3_errcode()] or -** [sqlite3_errmsg()]. +** reflected in subsequent calls to [sqlite3_errcode()] or [sqlite3_errmsg()]. ** ** INVARIANTS: ** -** {F12371} If a [sqlite3_get_table()] fails a memory allocation, then -** it frees the result table under construction, aborts the -** query in process, skips any subsequent queries, sets the -** *resultp output pointer to NULL and returns [SQLITE_NOMEM]. -** -** {F12373} If the ncolumn parameter to [sqlite3_get_table()] is not NULL -** then [sqlite3_get_table()] write the number of columns in the -** result set of the query into *ncolumn if the query is -** successful (if the function returns SQLITE_OK). +** {H12371} If a [sqlite3_get_table()] fails a memory allocation, then +** it shall free the result table under construction, abort the +** query in process, skip any subsequent queries, set the +** *pazResult output pointer to NULL and return [SQLITE_NOMEM]. +** +** {H12373} If the pnColumn parameter to [sqlite3_get_table()] is not NULL +** then a successful invocation of [sqlite3_get_table()] shall +** write the number of columns in the +** result set of the query into *pnColumn. +** +** {H12374} If the pnRow parameter to [sqlite3_get_table()] is not NULL +** then a successful invocation of [sqlite3_get_table()] shall +** writes the number of rows in the +** result set of the query into *pnRow. +** +** {H12376} A successful invocation of [sqlite3_get_table()] that computes +** N rows of result with C columns per row shall make *pazResult +** point to an array of pointers to (N+1)*C strings where the first +** C strings are column names as obtained from +** [sqlite3_column_name()] and the rest are column result values +** obtained from [sqlite3_column_text()]. ** -** {F12374} If the nrow parameter to [sqlite3_get_table()] is not NULL -** then [sqlite3_get_table()] write the number of rows in the -** result set of the query into *nrow if the query is -** successful (if the function returns SQLITE_OK). +** {H12379} The values in the pazResult array returned by [sqlite3_get_table()] +** shall remain valid until cleared by [sqlite3_free_table()]. ** -** {F12376} The [sqlite3_get_table()] function sets its *ncolumn value -** to the number of columns in the result set of the query in the -** sql parameter, or to zero if the query in sql has an empty -** result set. +** {H12382} When an error occurs during evaluation of [sqlite3_get_table()] +** the function shall set *pazResult to NULL, write an error message +** into memory obtained from [sqlite3_malloc()], make +** **pzErrmsg point to that error message, and return a +** appropriate [error code]. */ SQLITE_API int sqlite3_get_table( - sqlite3*, /* An open database */ - const char *sql, /* SQL to be evaluated */ - char ***pResult, /* Results of the query */ - int *nrow, /* Number of result rows written here */ - int *ncolumn, /* Number of result columns written here */ - char **errmsg /* Error msg written here */ + sqlite3 *db, /* An open database */ + const char *zSql, /* SQL to be evaluated */ + char ***pazResult, /* Results of the query */ + int *pnRow, /* Number of result rows written here */ + int *pnColumn, /* Number of result columns written here */ + char **pzErrmsg /* Error msg written here */ ); SQLITE_API void sqlite3_free_table(char **result); /* -** CAPI3REF: Formatted String Printing Functions {F17400} +** CAPI3REF: Formatted String Printing Functions {H17400} <S70000><S20000> ** ** These routines are workalikes of the "printf()" family of functions ** from the standard C library. @@ -1730,7 +2177,7 @@ SQLITE_API void sqlite3_free_table(char **result); ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their ** results into memory obtained from [sqlite3_malloc()]. ** The strings returned by these two routines should be -** released by [sqlite3_free()]. Both routines return a +** released by [sqlite3_free()]. Both routines return a ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough ** memory to hold the resulting string. ** @@ -1755,7 +2202,7 @@ SQLITE_API void sqlite3_free_table(char **result); ** ** These routines all implement some additional formatting ** options that are useful for constructing SQL statements. -** All of the usual printf formatting options apply. In addition, there +** All of the usual printf() formatting options apply. In addition, there ** is are "%q", "%Q", and "%z" options. ** ** The %q option works like %s in that it substitutes a null-terminated @@ -1764,7 +2211,7 @@ SQLITE_API void sqlite3_free_table(char **result); ** character it escapes that character and allows it to be inserted into ** the string. ** -** For example, so some string variable contains text as follows: +** For example, assume the string variable zText contains text as follows: ** ** <blockquote><pre> ** char *zText = "It's a happy day!"; @@ -1792,14 +2239,13 @@ SQLITE_API void sqlite3_free_table(char **result); ** INSERT INTO table1 VALUES('It's a happy day!'); ** </pre></blockquote> ** -** This second example is an SQL syntax error. As a general rule you -** should always use %q instead of %s when inserting text into a string -** literal. +** This second example is an SQL syntax error. As a general rule you should +** always use %q instead of %s when inserting text into a string literal. ** ** The %Q option works like %q except it also adds single quotes around -** the outside of the total string. Or if the parameter in the argument -** list is a NULL pointer, %Q substitutes the text "NULL" (without single -** quotes) in place of the %Q option. {END} So, for example, one could say: +** the outside of the total string. Additionally, if the parameter in the +** argument list is a NULL pointer, %Q substitutes the text "NULL" (without +** single quotes) in place of the %Q option. So, for example, one could say: ** ** <blockquote><pre> ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText); @@ -1816,33 +2262,32 @@ SQLITE_API void sqlite3_free_table(char **result); ** ** INVARIANTS: ** -** {F17403} The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces +** {H17403} The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces ** return either pointers to zero-terminated UTF-8 strings held in ** memory obtained from [sqlite3_malloc()] or NULL pointers if ** a call to [sqlite3_malloc()] fails. ** -** {F17406} The [sqlite3_snprintf()] interface writes a zero-terminated +** {H17406} The [sqlite3_snprintf()] interface writes a zero-terminated ** UTF-8 string into the buffer pointed to by the second parameter ** provided that the first parameter is greater than zero. ** -** {F17407} The [sqlite3_snprintf()] interface does not writes slots of +** {H17407} The [sqlite3_snprintf()] interface does not write slots of ** its output buffer (the second parameter) outside the range ** of 0 through N-1 (where N is the first parameter) ** regardless of the length of the string ** requested by the format specification. -** */ SQLITE_API char *sqlite3_mprintf(const char*,...); SQLITE_API char *sqlite3_vmprintf(const char*, va_list); SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...); /* -** CAPI3REF: Memory Allocation Subsystem {F17300} +** CAPI3REF: Memory Allocation Subsystem {H17300} <S20000> ** ** The SQLite core uses these three routines for all of its own ** internal memory allocation needs. "Core" in the previous sentence ** does not include operating-system specific VFS implementation. The -** windows VFS uses native malloc and free for some operations. +** Windows VFS uses native malloc() and free() for some operations. ** ** The sqlite3_malloc() routine returns a pointer to a block ** of memory at least N bytes in length, where N is the parameter. @@ -1871,7 +2316,7 @@ SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...); ** If the second parameter to sqlite3_realloc() is zero or ** negative then the behavior is exactly the same as calling ** sqlite3_free(P) where P is the first parameter to sqlite3_realloc(). -** Sqlite3_realloc() returns a pointer to a memory allocation +** sqlite3_realloc() returns a pointer to a memory allocation ** of at least N bytes in size or NULL if sufficient memory is unavailable. ** If M is the size of the prior allocation, then min(N,M) bytes ** of the prior allocation are copied into the beginning of buffer returned @@ -1882,128 +2327,123 @@ SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...); ** The memory returned by sqlite3_malloc() and sqlite3_realloc() ** is always aligned to at least an 8 byte boundary. {END} ** -** The default implementation -** of the memory allocation subsystem uses the malloc(), realloc() -** and free() provided by the standard C library. {F17382} However, if -** SQLite is compiled with the following C preprocessor macro -** -** <blockquote> SQLITE_MEMORY_SIZE=<i>NNN</i> </blockquote> -** -** where <i>NNN</i> is an integer, then SQLite create a static -** array of at least <i>NNN</i> bytes in size and use that array -** for all of its dynamic memory allocation needs. {END} Additional -** memory allocator options may be added in future releases. +** The default implementation of the memory allocation subsystem uses +** the malloc(), realloc() and free() provided by the standard C library. +** {H17382} However, if SQLite is compiled with the +** SQLITE_MEMORY_SIZE=<i>NNN</i> C preprocessor macro (where <i>NNN</i> +** is an integer), then SQLite create a static array of at least +** <i>NNN</i> bytes in size and uses that array for all of its dynamic +** memory allocation needs. {END} Additional memory allocator options +** may be added in future releases. ** ** In SQLite version 3.5.0 and 3.5.1, it was possible to define ** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in ** implementation of these routines to be omitted. That capability -** is no longer provided. Only built-in memory allocators can be -** used. +** is no longer provided. Only built-in memory allocators can be used. ** -** The windows OS interface layer calls +** The Windows OS interface layer calls ** the system malloc() and free() directly when converting ** filenames between the UTF-8 encoding used by SQLite -** and whatever filename encoding is used by the particular windows +** and whatever filename encoding is used by the particular Windows ** installation. Memory allocation errors are detected, but ** they are reported back as [SQLITE_CANTOPEN] or ** [SQLITE_IOERR] rather than [SQLITE_NOMEM]. ** ** INVARIANTS: ** -** {F17303} The [sqlite3_malloc(N)] interface returns either a pointer to -** newly checked-out block of at least N bytes of memory -** that is 8-byte aligned, -** or it returns NULL if it is unable to fulfill the request. +** {H17303} The [sqlite3_malloc(N)] interface returns either a pointer to +** a newly checked-out block of at least N bytes of memory +** that is 8-byte aligned, or it returns NULL if it is unable +** to fulfill the request. ** -** {F17304} The [sqlite3_malloc(N)] interface returns a NULL pointer if +** {H17304} The [sqlite3_malloc(N)] interface returns a NULL pointer if ** N is less than or equal to zero. ** -** {F17305} The [sqlite3_free(P)] interface releases memory previously +** {H17305} The [sqlite3_free(P)] interface releases memory previously ** returned from [sqlite3_malloc()] or [sqlite3_realloc()], ** making it available for reuse. ** -** {F17306} A call to [sqlite3_free(NULL)] is a harmless no-op. +** {H17306} A call to [sqlite3_free(NULL)] is a harmless no-op. ** -** {F17310} A call to [sqlite3_realloc(0,N)] is equivalent to a call +** {H17310} A call to [sqlite3_realloc(0,N)] is equivalent to a call ** to [sqlite3_malloc(N)]. ** -** {F17312} A call to [sqlite3_realloc(P,0)] is equivalent to a call +** {H17312} A call to [sqlite3_realloc(P,0)] is equivalent to a call ** to [sqlite3_free(P)]. ** -** {F17315} The SQLite core uses [sqlite3_malloc()], [sqlite3_realloc()], +** {H17315} The SQLite core uses [sqlite3_malloc()], [sqlite3_realloc()], ** and [sqlite3_free()] for all of its memory allocation and ** deallocation needs. ** -** {F17318} The [sqlite3_realloc(P,N)] interface returns either a pointer +** {H17318} The [sqlite3_realloc(P,N)] interface returns either a pointer ** to a block of checked-out memory of at least N bytes in size ** that is 8-byte aligned, or a NULL pointer. ** -** {F17321} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first -** copies the first K bytes of content from P into the newly allocated -** where K is the lessor of N and the size of the buffer P. +** {H17321} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first +** copies the first K bytes of content from P into the newly +** allocated block, where K is the lesser of N and the size of +** the buffer P. ** -** {F17322} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first +** {H17322} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first ** releases the buffer P. ** -** {F17323} When [sqlite3_realloc(P,N)] returns NULL, the buffer P is +** {H17323} When [sqlite3_realloc(P,N)] returns NULL, the buffer P is ** not modified or released. ** -** LIMITATIONS: +** ASSUMPTIONS: ** -** {U17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] -** must be either NULL or else a pointer obtained from a prior -** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that has -** not been released. +** {A17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] +** must be either NULL or else pointers obtained from a prior +** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have +** not yet been released. ** -** {U17351} The application must not read or write any part of +** {A17351} The application must not read or write any part of ** a block of memory after it has been released using ** [sqlite3_free()] or [sqlite3_realloc()]. -** */ SQLITE_API void *sqlite3_malloc(int); SQLITE_API void *sqlite3_realloc(void*, int); SQLITE_API void sqlite3_free(void*); /* -** CAPI3REF: Memory Allocator Statistics {F17370} +** CAPI3REF: Memory Allocator Statistics {H17370} <S30210> ** ** SQLite provides these two interfaces for reporting on the status ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()] -** the memory allocation subsystem included within the SQLite. +** routines, which form the built-in memory allocation subsystem. ** ** INVARIANTS: ** -** {F17371} The [sqlite3_memory_used()] routine returns the -** number of bytes of memory currently outstanding -** (malloced but not freed). +** {H17371} The [sqlite3_memory_used()] routine returns the number of bytes +** of memory currently outstanding (malloced but not freed). ** -** {F17373} The [sqlite3_memory_highwater()] routine returns the maximum -** value of [sqlite3_memory_used()] -** since the highwater mark was last reset. +** {H17373} The [sqlite3_memory_highwater()] routine returns the maximum +** value of [sqlite3_memory_used()] since the high-water mark +** was last reset. ** -** {F17374} The values returned by [sqlite3_memory_used()] and +** {H17374} The values returned by [sqlite3_memory_used()] and ** [sqlite3_memory_highwater()] include any overhead ** added by SQLite in its implementation of [sqlite3_malloc()], ** but not overhead added by the any underlying system library ** routines that [sqlite3_malloc()] may call. -** -** {F17375} The memory highwater mark is reset to the current value of +** +** {H17375} The memory high-water mark is reset to the current value of ** [sqlite3_memory_used()] if and only if the parameter to ** [sqlite3_memory_highwater()] is true. The value returned -** by [sqlite3_memory_highwater(1)] is the highwater mark +** by [sqlite3_memory_highwater(1)] is the high-water mark ** prior to the reset. */ SQLITE_API sqlite3_int64 sqlite3_memory_used(void); SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag); /* -** CAPI3REF: Pseudo-Random Number Generator {F17390} +** CAPI3REF: Pseudo-Random Number Generator {H17390} <S20000> ** ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to ** select random ROWIDs when inserting new records into a table that ** already uses the largest possible ROWID. The PRNG is also used for ** the build-in random() and randomblob() SQL functions. This interface allows -** appliations to access the same PRNG for other purposes. +** applications to access the same PRNG for other purposes. ** ** A call to this routine stores N bytes of randomness into buffer P. ** @@ -2016,13 +2456,13 @@ SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag); ** ** INVARIANTS: ** -** {F17392} The [sqlite3_randomness(N,P)] interface writes N bytes of +** {H17392} The [sqlite3_randomness(N,P)] interface writes N bytes of ** high-quality pseudo-randomness into buffer P. */ SQLITE_API void sqlite3_randomness(int N, void *P); /* -** CAPI3REF: Compile-Time Authorization Callbacks {F12500} +** CAPI3REF: Compile-Time Authorization Callbacks {H12500} <S70100> ** ** This routine registers a authorizer callback with a particular ** [database connection], supplied in the first argument. @@ -2035,9 +2475,9 @@ SQLITE_API void sqlite3_randomness(int N, void *P); ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the ** specific action but allow the SQL statement to continue to be ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be -** rejected with an error. If the authorizer callback returns +** rejected with an error. If the authorizer callback returns ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] -** then [sqlite3_prepare_v2()] or equivalent call that triggered +** then the [sqlite3_prepare_v2()] or equivalent call that triggered ** the authorizer will fail with an error message. ** ** When the callback returns [SQLITE_OK], that means the operation @@ -2052,19 +2492,17 @@ SQLITE_API void sqlite3_randomness(int N, void *P); ** return can be used to deny an untrusted user access to individual ** columns of a table. ** -** The first parameter to the authorizer callback is a copy of -** the third parameter to the sqlite3_set_authorizer() interface. -** The second parameter to the callback is an integer -** [SQLITE_COPY | action code] that specifies the particular action -** to be authorized. The third through sixth -** parameters to the callback are zero-terminated strings that contain -** additional details about the action to be authorized. +** The first parameter to the authorizer callback is a copy of the third +** parameter to the sqlite3_set_authorizer() interface. The second parameter +** to the callback is an integer [SQLITE_COPY | action code] that specifies +** the particular action to be authorized. The third through sixth parameters +** to the callback are zero-terminated strings that contain additional +** details about the action to be authorized. ** ** An authorizer is used when [sqlite3_prepare | preparing] -** SQL statements from an untrusted -** source, to ensure that the SQL statements do not try to access data -** that they are not allowed to see, or that they do not try to -** execute malicious statements that damage the database. For +** SQL statements from an untrusted source, to ensure that the SQL statements +** do not try to access data they are not allowed to see, or that they do not +** try to execute malicious statements that damage the database. For ** example, an application may allow a user to enter arbitrary ** SQL queries for evaluation by a database. But the application does ** not want the user to be able to make arbitrary changes to the @@ -2082,61 +2520,61 @@ SQLITE_API void sqlite3_randomness(int N, void *P); ** previous call. Disable the authorizer by installing a NULL callback. ** The authorizer is disabled by default. ** -** Note that the authorizer callback is invoked only during +** Note that the authorizer callback is invoked only during ** [sqlite3_prepare()] or its variants. Authorization is not ** performed during statement evaluation in [sqlite3_step()]. ** ** INVARIANTS: ** -** {F12501} The [sqlite3_set_authorizer(D,...)] interface registers a +** {H12501} The [sqlite3_set_authorizer(D,...)] interface registers a ** authorizer callback with database connection D. ** -** {F12502} The authorizer callback is invoked as SQL statements are -** being compiled +** {H12502} The authorizer callback is invoked as SQL statements are +** being compiled. ** -** {F12503} If the authorizer callback returns any value other than -** [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] then +** {H12503} If the authorizer callback returns any value other than +** [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY], then ** the [sqlite3_prepare_v2()] or equivalent call that caused ** the authorizer callback to run shall fail with an ** [SQLITE_ERROR] error code and an appropriate error message. ** -** {F12504} When the authorizer callback returns [SQLITE_OK], the operation -** described is coded normally. +** {H12504} When the authorizer callback returns [SQLITE_OK], the operation +** described is processed normally. ** -** {F12505} When the authorizer callback returns [SQLITE_DENY], the +** {H12505} When the authorizer callback returns [SQLITE_DENY], the ** [sqlite3_prepare_v2()] or equivalent call that caused the ** authorizer callback to run shall fail ** with an [SQLITE_ERROR] error code and an error message ** explaining that access is denied. ** -** {F12506} If the authorizer code (the 2nd parameter to the authorizer +** {H12506} If the authorizer code (the 2nd parameter to the authorizer ** callback) is [SQLITE_READ] and the authorizer callback returns -** [SQLITE_IGNORE] then the prepared statement is constructed to +** [SQLITE_IGNORE], then the prepared statement is constructed to ** insert a NULL value in place of the table column that would have ** been read if [SQLITE_OK] had been returned. ** -** {F12507} If the authorizer code (the 2nd parameter to the authorizer +** {H12507} If the authorizer code (the 2nd parameter to the authorizer ** callback) is anything other than [SQLITE_READ], then -** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY]. +** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY]. ** -** {F12510} The first parameter to the authorizer callback is a copy of +** {H12510} The first parameter to the authorizer callback is a copy of ** the third parameter to the [sqlite3_set_authorizer()] interface. ** -** {F12511} The second parameter to the callback is an integer +** {H12511} The second parameter to the callback is an integer ** [SQLITE_COPY | action code] that specifies the particular action ** to be authorized. ** -** {F12512} The third through sixth parameters to the callback are -** zero-terminated strings that contain +** {H12512} The third through sixth parameters to the callback are +** zero-terminated strings that contain ** additional details about the action to be authorized. ** -** {F12520} Each call to [sqlite3_set_authorizer()] overrides the +** {H12520} Each call to [sqlite3_set_authorizer()] overrides ** any previously installed authorizer. ** -** {F12521} A NULL authorizer means that no authorization +** {H12521} A NULL authorizer means that no authorization ** callback is invoked. ** -** {F12522} The default authorizer is NULL. +** {H12522} The default authorizer is NULL. */ SQLITE_API int sqlite3_set_authorizer( sqlite3*, @@ -2145,7 +2583,7 @@ SQLITE_API int sqlite3_set_authorizer( ); /* -** CAPI3REF: Authorizer Return Codes {F12590} +** CAPI3REF: Authorizer Return Codes {H12590} <H12500> ** ** The [sqlite3_set_authorizer | authorizer callback function] must ** return either [SQLITE_OK] or one of these two constants in order @@ -2157,44 +2595,44 @@ SQLITE_API int sqlite3_set_authorizer( #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ /* -** CAPI3REF: Authorizer Action Codes {F12550} +** CAPI3REF: Authorizer Action Codes {H12550} <H12500> ** ** The [sqlite3_set_authorizer()] interface registers a callback function -** that is invoked to authorizer certain SQL statement actions. The +** that is invoked to authorize certain SQL statement actions. The ** second parameter to the callback is an integer code that specifies ** what action is being authorized. These are the integer action codes that ** the authorizer callback may be passed. ** -** These action code values signify what kind of operation is to be +** These action code values signify what kind of operation is to be ** authorized. The 3rd and 4th parameters to the authorization ** callback function will be parameters or NULL depending on which of these ** codes is used as the second parameter. The 5th parameter to the -** authorizer callback is the name of the database ("main", "temp", +** authorizer callback is the name of the database ("main", "temp", ** etc.) if applicable. The 6th parameter to the authorizer callback ** is the name of the inner-most trigger or view that is responsible for -** the access attempt or NULL if this access attempt is directly from +** the access attempt or NULL if this access attempt is directly from ** top-level SQL code. ** ** INVARIANTS: ** -** {F12551} The second parameter to an -** [sqlite3_set_authorizer | authorizer callback is always an integer +** {H12551} The second parameter to an +** [sqlite3_set_authorizer | authorizer callback] is always an integer ** [SQLITE_COPY | authorizer code] that specifies what action ** is being authorized. ** -** {F12552} The 3rd and 4th parameters to the -** [sqlite3_set_authorizer | authorization callback function] -** will be parameters or NULL depending on which +** {H12552} The 3rd and 4th parameters to the +** [sqlite3_set_authorizer | authorization callback] +** will be parameters or NULL depending on which ** [SQLITE_COPY | authorizer code] is used as the second parameter. ** -** {F12553} The 5th parameter to the +** {H12553} The 5th parameter to the ** [sqlite3_set_authorizer | authorizer callback] is the name ** of the database (example: "main", "temp", etc.) if applicable. ** -** {F12554} The 6th parameter to the +** {H12554} The 6th parameter to the ** [sqlite3_set_authorizer | authorizer callback] is the name ** of the inner-most trigger or view that is responsible for -** the access attempt or NULL if this access attempt is directly from +** the access attempt or NULL if this access attempt is directly from ** top-level SQL code. */ /******************************************* 3rd ************ 4th ***********/ @@ -2232,7 +2670,8 @@ SQLITE_API int sqlite3_set_authorizer( #define SQLITE_COPY 0 /* No longer used */ /* -** CAPI3REF: Tracing And Profiling Functions {F12280} +** CAPI3REF: Tracing And Profiling Functions {H12280} <S60400> +** EXPERIMENTAL ** ** These routines register callback functions that can be used for ** tracing and profiling the execution of SQL statements. @@ -2241,54 +2680,46 @@ SQLITE_API int sqlite3_set_authorizer( ** various times when an SQL statement is being run by [sqlite3_step()]. ** The callback returns a UTF-8 rendering of the SQL statement text ** as the statement first begins executing. Additional callbacks occur -** as each triggersubprogram is entered. The callbacks for triggers +** as each triggered subprogram is entered. The callbacks for triggers ** contain a UTF-8 SQL comment that identifies the trigger. -** +** ** The callback function registered by sqlite3_profile() is invoked ** as each SQL statement finishes. The profile callback contains ** the original statement text and an estimate of wall-clock time ** of how long that statement took to run. ** -** The sqlite3_profile() API is currently considered experimental and -** is subject to change or removal in a future release. -** -** The trigger reporting feature of the trace callback is considered -** experimental and is subject to change or removal in future releases. -** Future versions of SQLite might also add new trace callback -** invocations. -** ** INVARIANTS: ** -** {F12281} The callback function registered by [sqlite3_trace()] is +** {H12281} The callback function registered by [sqlite3_trace()] is ** whenever an SQL statement first begins to execute and ** whenever a trigger subprogram first begins to run. ** -** {F12282} Each call to [sqlite3_trace()] overrides the previously +** {H12282} Each call to [sqlite3_trace()] overrides the previously ** registered trace callback. ** -** {F12283} A NULL trace callback disables tracing. +** {H12283} A NULL trace callback disables tracing. ** -** {F12284} The first argument to the trace callback is a copy of +** {H12284} The first argument to the trace callback is a copy of ** the pointer which was the 3rd argument to [sqlite3_trace()]. ** -** {F12285} The second argument to the trace callback is a -** zero-terminated UTF8 string containing the original text +** {H12285} The second argument to the trace callback is a +** zero-terminated UTF-8 string containing the original text ** of the SQL statement as it was passed into [sqlite3_prepare_v2()] ** or the equivalent, or an SQL comment indicating the beginning ** of a trigger subprogram. ** -** {F12287} The callback function registered by [sqlite3_profile()] is invoked +** {H12287} The callback function registered by [sqlite3_profile()] is invoked ** as each SQL statement finishes. ** -** {F12288} The first parameter to the profile callback is a copy of +** {H12288} The first parameter to the profile callback is a copy of ** the 3rd parameter to [sqlite3_profile()]. ** -** {F12289} The second parameter to the profile callback is a +** {H12289} The second parameter to the profile callback is a ** zero-terminated UTF-8 string that contains the complete text of ** the SQL statement as it was processed by [sqlite3_prepare_v2()] ** or the equivalent. ** -** {F12290} The third parameter to the profile callback is an estimate +** {H12290} The third parameter to the profile callback is an estimate ** of the number of nanoseconds of wall-clock time required to ** run the SQL statement from start to finish. */ @@ -2297,189 +2728,199 @@ SQLITE_API void *sqlite3_profile(sqlite3*, void(*xProfile)(void*,const char*,sqlite3_uint64), void*); /* -** CAPI3REF: Query Progress Callbacks {F12910} +** CAPI3REF: Query Progress Callbacks {H12910} <S60400> ** ** This routine configures a callback function - the ** progress callback - that is invoked periodically during long ** running calls to [sqlite3_exec()], [sqlite3_step()] and -** [sqlite3_get_table()]. An example use for this +** [sqlite3_get_table()]. An example use for this ** interface is to keep a GUI updated during a large query. ** -** If the progress callback returns non-zero, the opertion is +** If the progress callback returns non-zero, the operation is ** interrupted. This feature can be used to implement a ** "Cancel" button on a GUI dialog box. ** ** INVARIANTS: ** -** {F12911} The callback function registered by [sqlite3_progress_handler()] +** {H12911} The callback function registered by sqlite3_progress_handler() ** is invoked periodically during long running calls to ** [sqlite3_step()]. ** -** {F12912} The progress callback is invoked once for every N virtual -** machine opcodes, where N is the second argument to +** {H12912} The progress callback is invoked once for every N virtual +** machine opcodes, where N is the second argument to ** the [sqlite3_progress_handler()] call that registered -** the callback. <todo>What if N is less than 1?</todo> +** the callback. If N is less than 1, sqlite3_progress_handler() +** acts as if a NULL progress handler had been specified. ** -** {F12913} The progress callback itself is identified by the third -** argument to [sqlite3_progress_handler()]. +** {H12913} The progress callback itself is identified by the third +** argument to sqlite3_progress_handler(). ** -** {F12914} The fourth argument [sqlite3_progress_handler()] is a -*** void pointer passed to the progress callback +** {H12914} The fourth argument to sqlite3_progress_handler() is a +** void pointer passed to the progress callback ** function each time it is invoked. ** -** {F12915} If a call to [sqlite3_step()] results in fewer than -** N opcodes being executed, -** then the progress callback is never invoked. {END} -** -** {F12916} Every call to [sqlite3_progress_handler()] -** overwrites any previously registere progress handler. +** {H12915} If a call to [sqlite3_step()] results in fewer than N opcodes +** being executed, then the progress callback is never invoked. ** -** {F12917} If the progress handler callback is NULL then no progress +** {H12916} Every call to [sqlite3_progress_handler()] +** overwrites any previously registered progress handler. +** +** {H12917} If the progress handler callback is NULL then no progress ** handler is invoked. ** -** {F12918} If the progress callback returns a result other than 0, then +** {H12918} If the progress callback returns a result other than 0, then ** the behavior is a if [sqlite3_interrupt()] had been called. +** <S30500> */ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); /* -** CAPI3REF: Opening A New Database Connection {F12700} -** -** These routines open an SQLite database file whose name -** is given by the filename argument. -** The filename argument is interpreted as UTF-8 -** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16 -** in the native byte order for [sqlite3_open16()]. -** An [sqlite3*] handle is usually returned in *ppDb, even -** if an error occurs. The only exception is if SQLite is unable -** to allocate memory to hold the [sqlite3] object, a NULL will -** be written into *ppDb instead of a pointer to the [sqlite3] object. -** If the database is opened (and/or created) -** successfully, then [SQLITE_OK] is returned. Otherwise an -** error code is returned. The -** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain +** CAPI3REF: Opening A New Database Connection {H12700} <S40200> +** +** These routines open an SQLite database file whose name is given by the +** filename argument. The filename argument is interpreted as UTF-8 for +** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte +** order for sqlite3_open16(). A [database connection] handle is usually +** returned in *ppDb, even if an error occurs. The only exception is that +** if SQLite is unable to allocate memory to hold the [sqlite3] object, +** a NULL will be written into *ppDb instead of a pointer to the [sqlite3] +** object. If the database is opened (and/or created) successfully, then +** [SQLITE_OK] is returned. Otherwise an [error code] is returned. The +** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain ** an English language description of the error. ** ** The default encoding for the database will be UTF-8 if -** [sqlite3_open()] or [sqlite3_open_v2()] is called and -** UTF-16 in the native byte order if [sqlite3_open16()] is used. +** sqlite3_open() or sqlite3_open_v2() is called and +** UTF-16 in the native byte order if sqlite3_open16() is used. ** ** Whether or not an error occurs when it is opened, resources -** associated with the [sqlite3*] handle should be released by passing it -** to [sqlite3_close()] when it is no longer required. +** associated with the [database connection] handle should be released by +** passing it to [sqlite3_close()] when it is no longer required. ** -** The [sqlite3_open_v2()] interface works like [sqlite3_open()] -** except that it acccepts two additional parameters for additional control -** over the new database connection. The flags parameter can be -** one of: +** The sqlite3_open_v2() interface works like sqlite3_open() +** except that it accepts two additional parameters for additional control +** over the new database connection. The flags parameter can take one of +** the following three values, optionally combined with the +** [SQLITE_OPEN_NOMUTEX] flag: ** -** <ol> -** <li> [SQLITE_OPEN_READONLY] -** <li> [SQLITE_OPEN_READWRITE] -** <li> [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE] -** </ol> +** <dl> +** <dt>[SQLITE_OPEN_READONLY]</dt> +** <dd>The database is opened in read-only mode. If the database does not +** already exist, an error is returned.</dd> +** +** <dt>[SQLITE_OPEN_READWRITE]</dt> +** <dd>The database is opened for reading and writing if possible, or reading +** only if the file is write protected by the operating system. In either +** case the database must already exist, otherwise an error is returned.</dd> +** +** <dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt> +** <dd>The database is opened for reading and writing, and is creates it if +** it does not already exist. This is the behavior that is always used for +** sqlite3_open() and sqlite3_open16().</dd> +** </dl> ** -** The first value opens the database read-only. -** If the database does not previously exist, an error is returned. -** The second option opens -** the database for reading and writing if possible, or reading only if -** if the file is write protected. In either case the database -** must already exist or an error is returned. The third option -** opens the database for reading and writing and creates it if it does -** not already exist. -** The third options is behavior that is always used for [sqlite3_open()] -** and [sqlite3_open16()]. -** -** If the 3rd parameter to [sqlite3_open_v2()] is not one of the -** combinations shown above then the behavior is undefined. -** -** If the filename is ":memory:", then an private -** in-memory database is created for the connection. This in-memory -** database will vanish when the database connection is closed. Future -** version of SQLite might make use of additional special filenames -** that begin with the ":" character. It is recommended that -** when a database filename really does begin with -** ":" that you prefix the filename with a pathname like "./" to -** avoid ambiguity. -** -** If the filename is an empty string, then a private temporary +** If the 3rd parameter to sqlite3_open_v2() is not one of the +** combinations shown above or one of the combinations shown above combined +** with the [SQLITE_OPEN_NOMUTEX] flag, then the behavior is undefined. +** +** If the [SQLITE_OPEN_NOMUTEX] flag is set, then mutexes on the +** opened [database connection] are disabled and the appliation must +** insure that access to the [database connection] and its associated +** [prepared statements] is serialized. The [SQLITE_OPEN_NOMUTEX] flag +** is the default behavior is SQLite is configured using the +** [SQLITE_CONFIG_MULTITHREAD] or [SQLITE_CONFIG_SINGLETHREAD] options +** to [sqlite3_config()]. The [SQLITE_OPEN_NOMUTEX] flag only makes a +** difference when SQLite is in its default [SQLITE_CONFIG_SERIALIZED] mode. +** +** If the filename is ":memory:", then a private, temporary in-memory database +** is created for the connection. This in-memory database will vanish when +** the database connection is closed. Future versions of SQLite might +** make use of additional special filenames that begin with the ":" character. +** It is recommended that when a database filename actually does begin with +** a ":" character you should prefix the filename with a pathname such as +** "./" to avoid ambiguity. +** +** If the filename is an empty string, then a private, temporary ** on-disk database will be created. This private database will be ** automatically deleted as soon as the database connection is closed. ** ** The fourth parameter to sqlite3_open_v2() is the name of the -** [sqlite3_vfs] object that defines the operating system -** interface that the new database connection should use. If the -** fourth parameter is a NULL pointer then the default [sqlite3_vfs] -** object is used. +** [sqlite3_vfs] object that defines the operating system interface that +** the new database connection should use. If the fourth parameter is +** a NULL pointer then the default [sqlite3_vfs] object is used. ** -** <b>Note to windows users:</b> The encoding used for the filename argument -** of [sqlite3_open()] and [sqlite3_open_v2()] must be UTF-8, not whatever +** <b>Note to Windows users:</b> The encoding used for the filename argument +** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever ** codepage is currently defined. Filenames containing international ** characters must be converted to UTF-8 prior to passing them into -** [sqlite3_open()] or [sqlite3_open_v2()]. +** sqlite3_open() or sqlite3_open_v2(). ** ** INVARIANTS: ** -** {F12701} The [sqlite3_open()], [sqlite3_open16()], and +** {H12701} The [sqlite3_open()], [sqlite3_open16()], and ** [sqlite3_open_v2()] interfaces create a new ** [database connection] associated with ** the database file given in their first parameter. ** -** {F12702} The filename argument is interpreted as UTF-8 +** {H12702} The filename argument is interpreted as UTF-8 ** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16 ** in the native byte order for [sqlite3_open16()]. ** -** {F12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()], +** {H12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()], ** or [sqlite3_open_v2()] writes a pointer to a new ** [database connection] into *ppDb. ** -** {F12704} The [sqlite3_open()], [sqlite3_open16()], and +** {H12704} The [sqlite3_open()], [sqlite3_open16()], and ** [sqlite3_open_v2()] interfaces return [SQLITE_OK] upon success, ** or an appropriate [error code] on failure. ** -** {F12706} The default text encoding for a new database created using +** {H12706} The default text encoding for a new database created using ** [sqlite3_open()] or [sqlite3_open_v2()] will be UTF-8. ** -** {F12707} The default text encoding for a new database created using +** {H12707} The default text encoding for a new database created using ** [sqlite3_open16()] will be UTF-16. ** -** {F12709} The [sqlite3_open(F,D)] interface is equivalent to +** {H12709} The [sqlite3_open(F,D)] interface is equivalent to ** [sqlite3_open_v2(F,D,G,0)] where the G parameter is ** [SQLITE_OPEN_READWRITE]|[SQLITE_OPEN_CREATE]. ** -** {F12711} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the +** {H12711} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the ** bit value [SQLITE_OPEN_READONLY] then the database is opened ** for reading only. ** -** {F12712} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the +** {H12712} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the ** bit value [SQLITE_OPEN_READWRITE] then the database is opened ** reading and writing if possible, or for reading only if the ** file is write protected by the operating system. ** -** {F12713} If the G parameter to [sqlite3_open(v2(F,D,G,V)] omits the +** {H12713} If the G parameter to [sqlite3_open(v2(F,D,G,V)] omits the ** bit value [SQLITE_OPEN_CREATE] and the database does not ** previously exist, an error is returned. ** -** {F12714} If the G parameter to [sqlite3_open(v2(F,D,G,V)] contains the +** {H12714} If the G parameter to [sqlite3_open(v2(F,D,G,V)] contains the ** bit value [SQLITE_OPEN_CREATE] and the database does not ** previously exist, then an attempt is made to create and ** initialize the database. ** -** {F12717} If the filename argument to [sqlite3_open()], [sqlite3_open16()], +** {H12717} If the filename argument to [sqlite3_open()], [sqlite3_open16()], ** or [sqlite3_open_v2()] is ":memory:", then an private, ** ephemeral, in-memory database is created for the connection. ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required ** in sqlite3_open_v2()?</todo> ** -** {F12719} If the filename is NULL or an empty string, then a private, -** ephermeral on-disk database will be created. +** {H12719} If the filename is NULL or an empty string, then a private, +** ephemeral on-disk database will be created. ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required ** in sqlite3_open_v2()?</todo> ** -** {F12721} The [database connection] created by -** [sqlite3_open_v2(F,D,G,V)] will use the -** [sqlite3_vfs] object identified by the V parameter, or -** the default [sqlite3_vfs] object is V is a NULL pointer. +** {H12721} The [database connection] created by [sqlite3_open_v2(F,D,G,V)] +** will use the [sqlite3_vfs] object identified by the V parameter, +** or the default [sqlite3_vfs] object if V is a NULL pointer. +** +** {H12723} Two [database connections] will share a common cache if both were +** opened with the same VFS while [shared cache mode] was enabled and +** if both filenames compare equal using memcmp() after having been +** processed by the [sqlite3_vfs | xFullPathname] method of the VFS. */ SQLITE_API int sqlite3_open( const char *filename, /* Database filename (UTF-8) */ @@ -2497,44 +2938,45 @@ SQLITE_API int sqlite3_open_v2( ); /* -** CAPI3REF: Error Codes And Messages {F12800} +** CAPI3REF: Error Codes And Messages {H12800} <S60200> ** -** The sqlite3_errcode() interface returns the numeric -** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code] -** for the most recent failed sqlite3_* API call associated -** with [sqlite3] handle 'db'. If a prior API call failed but the -** most recent API call succeeded, the return value from sqlite3_errcode() -** is undefined. +** The sqlite3_errcode() interface returns the numeric [result code] or +** [extended result code] for the most recent failed sqlite3_* API call +** associated with a [database connection]. If a prior API call failed +** but the most recent API call succeeded, the return value from +** sqlite3_errcode() is undefined. ** ** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language -** text that describes the error, as either UTF8 or UTF16 respectively. +** text that describes the error, as either UTF-8 or UTF-16 respectively. ** Memory to hold the error message string is managed internally. -** The application does not need to worry with freeing the result. +** The application does not need to worry about freeing the result. ** However, the error string might be overwritten or deallocated by ** subsequent calls to other SQLite interface functions. ** +** If an interface fails with SQLITE_MISUSE, that means the interface +** was invoked incorrectly by the application. In that case, the +** error code and message may or may not be set. +** ** INVARIANTS: ** -** {F12801} The [sqlite3_errcode(D)] interface returns the numeric -** [SQLITE_OK | result code] or -** [SQLITE_IOERR_READ | extended result code] -** for the most recently failed interface call associated -** with [database connection] D. +** {H12801} The [sqlite3_errcode(D)] interface returns the numeric +** [result code] or [extended result code] for the most recently +** failed interface call associated with the [database connection] D. ** -** {F12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)] +** {H12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)] ** interfaces return English-language text that describes ** the error in the mostly recently failed interface call, -** encoded as either UTF8 or UTF16 respectively. +** encoded as either UTF-8 or UTF-16 respectively. ** -** {F12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()] +** {H12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()] ** are valid until the next SQLite interface call. ** -** {F12808} Calls to API routines that do not return an error code +** {H12808} Calls to API routines that do not return an error code ** (example: [sqlite3_data_count()]) do not ** change the error code or message returned by ** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()]. ** -** {F12809} Interfaces that are not associated with a specific +** {H12809} Interfaces that are not associated with a specific ** [database connection] (examples: ** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()] ** do not change the values returned by @@ -2545,20 +2987,20 @@ SQLITE_API const char *sqlite3_errmsg(sqlite3*); SQLITE_API const void *sqlite3_errmsg16(sqlite3*); /* -** CAPI3REF: SQL Statement Object {F13000} +** CAPI3REF: SQL Statement Object {H13000} <H13010> ** KEYWORDS: {prepared statement} {prepared statements} ** -** An instance of this object represent single SQL statements. This -** object is variously known as a "prepared statement" or a +** An instance of this object represents a single SQL statement. +** This object is variously known as a "prepared statement" or a ** "compiled SQL statement" or simply as a "statement". -** +** ** The life of a statement object goes something like this: ** ** <ol> ** <li> Create the object using [sqlite3_prepare_v2()] or a related ** function. -** <li> Bind values to host parameters using -** [sqlite3_bind_blob | sqlite3_bind_* interfaces]. +** <li> Bind values to [host parameters] using the sqlite3_bind_*() +** interfaces. ** <li> Run the SQL by calling [sqlite3_step()] one or more times. ** <li> Reset the statement using [sqlite3_reset()] then go back ** to step 2. Do this zero or more times. @@ -2571,7 +3013,7 @@ SQLITE_API const void *sqlite3_errmsg16(sqlite3*); typedef struct sqlite3_stmt sqlite3_stmt; /* -** CAPI3REF: Run-time Limits {F12760} +** CAPI3REF: Run-time Limits {H12760} <S20600> ** ** This interface allows the size of various constructs to be limited ** on a connection by connection basis. The first parameter is the @@ -2582,7 +3024,7 @@ typedef struct sqlite3_stmt sqlite3_stmt; ** ** If the new limit is a negative number, the limit is unchanged. ** For the limit category of SQLITE_LIMIT_XYZ there is a hard upper -** bound set by a compile-time C-preprocess macro named SQLITE_MAX_XYZ. +** bound set by a compile-time C preprocessor macro named SQLITE_MAX_XYZ. ** (The "_LIMIT_" in the name is changed to "_MAX_".) ** Attempts to increase a limit above its hard upper bound are ** silently truncated to the hard upper limit. @@ -2591,47 +3033,44 @@ typedef struct sqlite3_stmt sqlite3_stmt; ** both their own internal database and also databases that are controlled ** by untrusted external sources. An example application might be a ** webbrowser that has its own databases for storing history and -** separate databases controlled by javascript applications downloaded -** off the internet. The internal databases can be given the +** separate databases controlled by JavaScript applications downloaded +** off the Internet. The internal databases can be given the ** large, default limits. Databases managed by external sources can ** be given much smaller limits designed to prevent a denial of service -** attach. Developers might also want to use the [sqlite3_set_authorizer()] +** attack. Developers might also want to use the [sqlite3_set_authorizer()] ** interface to further control untrusted SQL. The size of the database ** created by an untrusted script can be contained using the ** [max_page_count] [PRAGMA]. ** -** This interface is currently considered experimental and is subject -** to change or removal without prior notice. +** New run-time limit categories may be added in future releases. ** ** INVARIANTS: ** -** {F12762} A successful call to [sqlite3_limit(D,C,V)] where V is -** positive changes the -** limit on the size of construct C in [database connection] D -** to the lessor of V and the hard upper bound on the size -** of C that is set at compile-time. +** {H12762} A successful call to [sqlite3_limit(D,C,V)] where V is +** positive changes the limit on the size of construct C in the +** [database connection] D to the lesser of V and the hard upper +** bound on the size of C that is set at compile-time. ** -** {F12766} A successful call to [sqlite3_limit(D,C,V)] where V is negative -** leaves the state of [database connection] D unchanged. +** {H12766} A successful call to [sqlite3_limit(D,C,V)] where V is negative +** leaves the state of the [database connection] D unchanged. ** -** {F12769} A successful call to [sqlite3_limit(D,C,V)] returns the -** value of the limit on the size of construct C in -** in [database connection] D as it was prior to the call. +** {H12769} A successful call to [sqlite3_limit(D,C,V)] returns the +** value of the limit on the size of construct C in the +** [database connection] D as it was prior to the call. */ SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal); /* -** CAPI3REF: Run-Time Limit Categories {F12790} +** CAPI3REF: Run-Time Limit Categories {H12790} <H12760> ** KEYWORDS: {limit category} {limit categories} -** +** ** These constants define various aspects of a [database connection] ** that can be limited in size by calls to [sqlite3_limit()]. ** The meanings of the various limits are as follows: ** ** <dl> ** <dt>SQLITE_LIMIT_LENGTH</dt> -** <dd>The maximum size of any -** string or blob or table row.<dd> +** <dd>The maximum size of any string or BLOB or table row.<dd> ** ** <dt>SQLITE_LIMIT_SQL_LENGTH</dt> ** <dd>The maximum length of an SQL statement.</dd> @@ -2678,52 +3117,50 @@ SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal); #define SQLITE_LIMIT_VARIABLE_NUMBER 9 /* -** CAPI3REF: Compiling An SQL Statement {F13010} +** CAPI3REF: Compiling An SQL Statement {H13010} <S10000> +** KEYWORDS: {SQL statement compiler} ** ** To execute an SQL query, it must first be compiled into a byte-code -** program using one of these routines. +** program using one of these routines. ** -** The first argument "db" is an [database connection] -** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()] -** or [sqlite3_open16()]. -** The second argument "zSql" is the statement to be compiled, encoded +** The first argument, "db", is a [database connection] obtained from a +** prior call to [sqlite3_open()], [sqlite3_open_v2()] or [sqlite3_open16()]. +** +** The second argument, "zSql", is the statement to be compiled, encoded ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() -** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2() -** use UTF-16. {END} -** -** If the nByte argument is less -** than zero, then zSql is read up to the first zero terminator. -** If nByte is non-negative, then it is the maximum number of -** bytes read from zSql. When nByte is non-negative, the -** zSql string ends at either the first '\000' or '\u0000' character or +** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2() +** use UTF-16. +** +** If the nByte argument is less than zero, then zSql is read up to the +** first zero terminator. If nByte is non-negative, then it is the maximum +** number of bytes read from zSql. When nByte is non-negative, the +** zSql string ends at either the first '\000' or '\u0000' character or ** the nByte-th byte, whichever comes first. If the caller knows ** that the supplied string is nul-terminated, then there is a small -** performance advantage to be had by passing an nByte parameter that -** is equal to the number of bytes in the input string <i>including</i> -** the nul-terminator bytes.{END} +** performance advantage to be gained by passing an nByte parameter that +** is equal to the number of bytes in the input string <i>including</i> +** the nul-terminator bytes. ** ** *pzTail is made to point to the first byte past the end of the -** first SQL statement in zSql. These routines only compiles the first +** first SQL statement in zSql. These routines only compile the first ** statement in zSql, so *pzTail is left pointing to what remains ** uncompiled. ** ** *ppStmt is left pointing to a compiled [prepared statement] that can be -** executed using [sqlite3_step()]. Or if there is an error, *ppStmt is -** set to NULL. If the input text contains no SQL (if the input -** is and empty string or a comment) then *ppStmt is set to NULL. -** {U13018} The calling procedure is responsible for deleting the -** compiled SQL statement -** using [sqlite3_finalize()] after it has finished with it. +** executed using [sqlite3_step()]. If there is an error, *ppStmt is set +** to NULL. If the input text contains no SQL (if the input is an empty +** string or a comment) then *ppStmt is set to NULL. +** {A13018} The calling procedure is responsible for deleting the compiled +** SQL statement using [sqlite3_finalize()] after it has finished with it. ** -** On success, [SQLITE_OK] is returned. Otherwise an -** [error code] is returned. +** On success, [SQLITE_OK] is returned, otherwise an [error code] is returned. ** ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are ** recommended for all new programs. The two older interfaces are retained ** for backwards compatibility, but their use is discouraged. ** In the "v2" interfaces, the prepared statement -** that is returned (the [sqlite3_stmt] object) contains a copy of the -** original SQL text. {END} This causes the [sqlite3_step()] interface to +** that is returned (the [sqlite3_stmt] object) contains a copy of the +** original SQL text. This causes the [sqlite3_step()] interface to ** behave a differently in two ways: ** ** <ol> @@ -2732,60 +3169,57 @@ SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal); ** always used to do, [sqlite3_step()] will automatically recompile the SQL ** statement and try to run it again. If the schema has changed in ** a way that makes the statement no longer valid, [sqlite3_step()] will still -** return [SQLITE_SCHEMA]. But unlike the legacy behavior, -** [SQLITE_SCHEMA] is now a fatal error. Calling -** [sqlite3_prepare_v2()] again will not make the +** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is +** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the ** error go away. Note: use [sqlite3_errmsg()] to find the text -** of the parsing error that results in an [SQLITE_SCHEMA] return. {END} +** of the parsing error that results in an [SQLITE_SCHEMA] return. ** </li> ** ** <li> -** When an error occurs, -** [sqlite3_step()] will return one of the detailed -** [error codes] or [extended error codes]. -** The legacy behavior was that [sqlite3_step()] would only return a generic -** [SQLITE_ERROR] result code and you would have to make a second call to -** [sqlite3_reset()] in order to find the underlying cause of the problem. -** With the "v2" prepare interfaces, the underlying reason for the error is -** returned immediately. +** When an error occurs, [sqlite3_step()] will return one of the detailed +** [error codes] or [extended error codes]. The legacy behavior was that +** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code +** and you would have to make a second call to [sqlite3_reset()] in order +** to find the underlying cause of the problem. With the "v2" prepare +** interfaces, the underlying reason for the error is returned immediately. ** </li> ** </ol> ** ** INVARIANTS: ** -** {F13011} The [sqlite3_prepare(db,zSql,...)] and +** {H13011} The [sqlite3_prepare(db,zSql,...)] and ** [sqlite3_prepare_v2(db,zSql,...)] interfaces interpret the ** text in their zSql parameter as UTF-8. ** -** {F13012} The [sqlite3_prepare16(db,zSql,...)] and +** {H13012} The [sqlite3_prepare16(db,zSql,...)] and ** [sqlite3_prepare16_v2(db,zSql,...)] interfaces interpret the ** text in their zSql parameter as UTF-16 in the native byte order. ** -** {F13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] -** and its variants is less than zero, then SQL text is +** {H13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] +** and its variants is less than zero, the SQL text is ** read from zSql is read up to the first zero terminator. ** -** {F13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] -** and its variants is non-negative, then at most nBytes bytes +** {H13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] +** and its variants is non-negative, then at most nBytes bytes of ** SQL text is read from zSql. ** -** {F13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants +** {H13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants ** if the zSql input text contains more than one SQL statement ** and pzTail is not NULL, then *pzTail is made to point to the ** first byte past the end of the first SQL statement in zSql. ** <todo>What does *pzTail point to if there is one statement?</todo> ** -** {F13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)] +** {H13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)] ** or one of its variants writes into *ppStmt a pointer to a new -** [prepared statement] or a pointer to NULL -** if zSql contains nothing other than whitespace or comments. +** [prepared statement] or a pointer to NULL if zSql contains +** nothing other than whitespace or comments. ** -** {F13019} The [sqlite3_prepare_v2()] interface and its variants return +** {H13019} The [sqlite3_prepare_v2()] interface and its variants return ** [SQLITE_OK] or an appropriate [error code] upon failure. ** -** {F13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its -** variants returns an error (any value other than [SQLITE_OK]) -** it first sets *ppStmt to NULL. +** {H13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its +** variants returns an error (any value other than [SQLITE_OK]), +** they first set *ppStmt to NULL. */ SQLITE_API int sqlite3_prepare( sqlite3 *db, /* Database handle */ @@ -2817,85 +3251,89 @@ SQLITE_API int sqlite3_prepare16_v2( ); /* -** CAPIREF: Retrieving Statement SQL {F13100} +** CAPIREF: Retrieving Statement SQL {H13100} <H13000> ** -** This intereface can be used to retrieve a saved copy of the original -** SQL text used to create a [prepared statement]. +** This interface can be used to retrieve a saved copy of the original +** SQL text used to create a [prepared statement] if that statement was +** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()]. ** ** INVARIANTS: ** -** {F13101} If the [prepared statement] passed as -** the an argument to [sqlite3_sql()] was compiled -** compiled using either [sqlite3_prepare_v2()] or -** [sqlite3_prepare16_v2()], -** then [sqlite3_sql()] function returns a pointer to a -** zero-terminated string containing a UTF-8 rendering +** {H13101} If the [prepared statement] passed as the argument to +** [sqlite3_sql()] was compiled using either [sqlite3_prepare_v2()] or +** [sqlite3_prepare16_v2()], then [sqlite3_sql()] returns +** a pointer to a zero-terminated string containing a UTF-8 rendering ** of the original SQL statement. ** -** {F13102} If the [prepared statement] passed as -** the an argument to [sqlite3_sql()] was compiled -** compiled using either [sqlite3_prepare()] or -** [sqlite3_prepare16()], -** then [sqlite3_sql()] function returns a NULL pointer. +** {H13102} If the [prepared statement] passed as the argument to +** [sqlite3_sql()] was compiled using either [sqlite3_prepare()] or +** [sqlite3_prepare16()], then [sqlite3_sql()] returns a NULL pointer. ** -** {F13103} The string returned by [sqlite3_sql(S)] is valid until the +** {H13103} The string returned by [sqlite3_sql(S)] is valid until the ** [prepared statement] S is deleted using [sqlite3_finalize(S)]. */ SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt); /* -** CAPI3REF: Dynamically Typed Value Object {F15000} +** CAPI3REF: Dynamically Typed Value Object {H15000} <S20200> ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value} ** ** SQLite uses the sqlite3_value object to represent all values -** that can be stored in a database table. -** SQLite uses dynamic typing for the values it stores. -** Values stored in sqlite3_value objects can be -** be integers, floating point values, strings, BLOBs, or NULL. +** that can be stored in a database table. SQLite uses dynamic typing +** for the values it stores. Values stored in sqlite3_value objects +** can be integers, floating point values, strings, BLOBs, or NULL. ** ** An sqlite3_value object may be either "protected" or "unprotected". ** Some interfaces require a protected sqlite3_value. Other interfaces ** will accept either a protected or an unprotected sqlite3_value. -** Every interface that accepts sqlite3_value arguments specifies +** Every interface that accepts sqlite3_value arguments specifies ** whether or not it requires a protected sqlite3_value. ** ** The terms "protected" and "unprotected" refer to whether or not ** a mutex is held. A internal mutex is held for a protected ** sqlite3_value object but no mutex is held for an unprotected ** sqlite3_value object. If SQLite is compiled to be single-threaded -** (with SQLITE_THREADSAFE=0 and with [sqlite3_threadsafe()] returning 0) -** then there is no distinction between -** protected and unprotected sqlite3_value objects and they can be -** used interchangable. However, for maximum code portability it -** is recommended that applications make the distinction between -** between protected and unprotected sqlite3_value objects even if -** they are single threaded. +** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0) +** or if SQLite is run in one of reduced mutex modes +** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD] +** then there is no distinction between protected and unprotected +** sqlite3_value objects and they can be used interchangeably. However, +** for maximum code portability it is recommended that applications +** still make the distinction between between protected and unprotected +** sqlite3_value objects even when not strictly required. ** ** The sqlite3_value objects that are passed as parameters into the -** implementation of application-defined SQL functions are protected. +** implementation of [application-defined SQL functions] are protected. ** The sqlite3_value object returned by ** [sqlite3_column_value()] is unprotected. ** Unprotected sqlite3_value objects may only be used with -** [sqlite3_result_value()] and [sqlite3_bind_value()]. All other -** interfaces that use sqlite3_value require protected sqlite3_value objects. +** [sqlite3_result_value()] and [sqlite3_bind_value()]. +** The [sqlite3_value_blob | sqlite3_value_type()] family of +** interfaces require protected sqlite3_value objects. */ typedef struct Mem sqlite3_value; /* -** CAPI3REF: SQL Function Context Object {F16001} +** CAPI3REF: SQL Function Context Object {H16001} <S20200> ** ** The context in which an SQL function executes is stored in an -** sqlite3_context object. A pointer to an sqlite3_context -** object is always first parameter to application-defined SQL functions. +** sqlite3_context object. A pointer to an sqlite3_context object +** is always first parameter to [application-defined SQL functions]. +** The application-defined SQL function implementation will pass this +** pointer through into calls to [sqlite3_result_int | sqlite3_result()], +** [sqlite3_aggregate_context()], [sqlite3_user_data()], +** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()], +** and/or [sqlite3_set_auxdata()]. */ typedef struct sqlite3_context sqlite3_context; /* -** CAPI3REF: Binding Values To Prepared Statements {F13500} +** CAPI3REF: Binding Values To Prepared Statements {H13500} <S70300> +** KEYWORDS: {host parameter} {host parameters} {host parameter name} +** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding} ** -** In the SQL strings input to [sqlite3_prepare_v2()] and its -** variants, literals may be replace by a parameter in one -** of these forms: +** In the SQL strings input to [sqlite3_prepare_v2()] and its variants, +** literals may be replaced by a parameter in one of these forms: ** ** <ul> ** <li> ? @@ -2906,32 +3344,31 @@ typedef struct sqlite3_context sqlite3_context; ** </ul> ** ** In the parameter forms shown above NNN is an integer literal, -** VVV alpha-numeric parameter name. -** The values of these parameters (also called "host parameter names" -** or "SQL parameters") +** and VVV is an alpha-numeric parameter name. The values of these +** parameters (also called "host parameter names" or "SQL parameters") ** can be set using the sqlite3_bind_*() routines defined here. ** -** The first argument to the sqlite3_bind_*() routines always -** is a pointer to the [sqlite3_stmt] object returned from -** [sqlite3_prepare_v2()] or its variants. The second -** argument is the index of the parameter to be set. The -** first parameter has an index of 1. When the same named -** parameter is used more than once, second and subsequent -** occurrences have the same index as the first occurrence. +** The first argument to the sqlite3_bind_*() routines is always +** a pointer to the [sqlite3_stmt] object returned from +** [sqlite3_prepare_v2()] or its variants. +** +** The second argument is the index of the SQL parameter to be set. +** The leftmost SQL parameter has an index of 1. When the same named +** SQL parameter is used more than once, second and subsequent +** occurrences have the same index as the first occurrence. ** The index for named parameters can be looked up using the -** [sqlite3_bind_parameter_name()] API if desired. The index +** [sqlite3_bind_parameter_index()] API if desired. The index ** for "?NNN" parameters is the value of NNN. -** The NNN value must be between 1 and the compile-time -** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999). +** The NNN value must be between 1 and the [sqlite3_limit()] +** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999). ** ** The third argument is the value to bind to the parameter. ** -** In those -** routines that have a fourth argument, its value is the number of bytes -** in the parameter. To be clear: the value is the number of <u>bytes</u> -** in the value, not the number of characters. +** In those routines that have a fourth argument, its value is the +** number of bytes in the parameter. To be clear: the value is the +** number of <u>bytes</u> in the value, not the number of characters. ** If the fourth parameter is negative, the length of the string is -** number of bytes up to the first zero terminator. +** the number of bytes up to the first zero terminator. ** ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or @@ -2943,12 +3380,12 @@ typedef struct sqlite3_context sqlite3_context; ** the sqlite3_bind_*() routine returns. ** ** The sqlite3_bind_zeroblob() routine binds a BLOB of length N that -** is filled with zeros. A zeroblob uses a fixed amount of memory -** (just an integer to hold it size) while it is being processed. -** Zeroblobs are intended to serve as place-holders for BLOBs whose -** content is later written using -** [sqlite3_blob_open | increment BLOB I/O] routines. A negative -** value for the zeroblob results in a zero-length BLOB. +** is filled with zeroes. A zeroblob uses a fixed amount of memory +** (just an integer to hold its size) while it is being processed. +** Zeroblobs are intended to serve as placeholders for BLOBs whose +** content is later written using +** [sqlite3_blob_open | incremental BLOB I/O] routines. +** A negative value for the zeroblob results in a zero-length BLOB. ** ** The sqlite3_bind_*() routines must be called after ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and @@ -2958,7 +3395,7 @@ typedef struct sqlite3_context sqlite3_context; ** ** These routines return [SQLITE_OK] on success or an error code if ** anything goes wrong. [SQLITE_RANGE] is returned if the parameter -** index is out of range. [SQLITE_NOMEM] is returned if malloc fails. +** index is out of range. [SQLITE_NOMEM] is returned if malloc() fails. ** [SQLITE_MISUSE] might be returned if these routines are called on a ** virtual machine that is the wrong state or which has already been finalized. ** Detection of misuse is unreliable. Applications should not depend @@ -2967,79 +3404,79 @@ typedef struct sqlite3_context sqlite3_context; ** panic rather than return SQLITE_MISUSE. ** ** See also: [sqlite3_bind_parameter_count()], -** [sqlite3_bind_parameter_name()], and -** [sqlite3_bind_parameter_index()]. +** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()]. ** ** INVARIANTS: ** -** {F13506} The [sqlite3_prepare | SQL statement compiler] recognizes -** tokens of the forms "?", "?NNN", "$VVV", ":VVV", and "@VVV" -** as SQL parameters, where NNN is any sequence of one or more -** digits and where VVV is any sequence of one or more -** alphanumeric characters or "::" optionally followed by -** a string containing no spaces and contained within parentheses. +** {H13506} The [SQL statement compiler] recognizes tokens of the forms +** "?", "?NNN", "$VVV", ":VVV", and "@VVV" as SQL parameters, +** where NNN is any sequence of one or more digits +** and where VVV is any sequence of one or more alphanumeric +** characters or "::" optionally followed by a string containing +** no spaces and contained within parentheses. ** -** {F13509} The initial value of an SQL parameter is NULL. +** {H13509} The initial value of an SQL parameter is NULL. ** -** {F13512} The index of an "?" SQL parameter is one larger than the +** {H13512} The index of an "?" SQL parameter is one larger than the ** largest index of SQL parameter to the left, or 1 if ** the "?" is the leftmost SQL parameter. ** -** {F13515} The index of an "?NNN" SQL parameter is the integer NNN. +** {H13515} The index of an "?NNN" SQL parameter is the integer NNN. ** -** {F13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is -** the same as the index of leftmost occurances of the same +** {H13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is +** the same as the index of leftmost occurrences of the same ** parameter, or one more than the largest index over all -** parameters to the left if this is the first occurrance +** parameters to the left if this is the first occurrence ** of this parameter, or 1 if this is the leftmost parameter. ** -** {F13521} The [sqlite3_prepare | SQL statement compiler] fail with -** an [SQLITE_RANGE] error if the index of an SQL parameter -** is less than 1 or greater than SQLITE_MAX_VARIABLE_NUMBER. +** {H13521} The [SQL statement compiler] fails with an [SQLITE_RANGE] +** error if the index of an SQL parameter is less than 1 +** or greater than the compile-time SQLITE_MAX_VARIABLE_NUMBER +** parameter. ** -** {F13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)] +** {H13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)] ** associate the value V with all SQL parameters having an ** index of N in the [prepared statement] S. ** -** {F13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)] +** {H13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)] ** override prior calls with the same values of S and N. ** -** {F13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)] +** {H13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)] ** persist across calls to [sqlite3_reset(S)]. ** -** {F13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)], +** {H13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)], ** [sqlite3_bind_text(S,N,V,L,D)], or ** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds the first L -** bytes of the blob or string pointed to by V, when L +** bytes of the BLOB or string pointed to by V, when L ** is non-negative. ** -** {F13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or +** {H13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or ** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds characters ** from V through the first zero character when L is negative. ** -** {F13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)], +** {H13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)], ** [sqlite3_bind_text(S,N,V,L,D)], or ** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special ** constant [SQLITE_STATIC], SQLite assumes that the value V ** is held in static unmanaged space that will not change ** during the lifetime of the binding. ** -** {F13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)], +** {H13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)], ** [sqlite3_bind_text(S,N,V,L,D)], or ** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special -** constant [SQLITE_TRANSIENT], the routine makes a -** private copy of V value before it returns. +** constant [SQLITE_TRANSIENT], the routine makes a +** private copy of the value V before it returns. ** -** {F13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)], +** {H13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)], ** [sqlite3_bind_text(S,N,V,L,D)], or ** [sqlite3_bind_text16(S,N,V,L,D)] when D is a pointer to ** a function, SQLite invokes that function to destroy the -** V value after it has finished using the V value. +** value V after it has finished using the value V. ** -** {F13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound -** is a blob of L bytes, or a zero-length blob if L is negative. +** {H13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound +** is a BLOB of L bytes, or a zero-length BLOB if L is negative. ** -** {F13551} In calls to [sqlite3_bind_value(S,N,V)] the V argument may +** {H13551} In calls to [sqlite3_bind_value(S,N,V)] the V argument may ** be either a [protected sqlite3_value] object or an ** [unprotected sqlite3_value] object. */ @@ -3054,18 +3491,18 @@ SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); /* -** CAPI3REF: Number Of SQL Parameters {F13600} +** CAPI3REF: Number Of SQL Parameters {H13600} <S70300> ** -** This routine can be used to find the number of SQL parameters -** in a prepared statement. SQL parameters are tokens of the +** This routine can be used to find the number of [SQL parameters] +** in a [prepared statement]. SQL parameters are tokens of the ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as -** place-holders for values that are [sqlite3_bind_blob | bound] +** placeholders for values that are [sqlite3_bind_blob | bound] ** to the parameters at a later time. ** -** This routine actually returns the index of the largest parameter. -** For all forms except ?NNN, this will correspond to the number of -** unique parameters. If parameters of the ?NNN are used, there may -** be gaps in the list. +** This routine actually returns the index of the largest (rightmost) +** parameter. For all forms except ?NNN, this will correspond to the +** number of unique parameters. If parameters of the ?NNN are used, +** there may be gaps in the list. ** ** See also: [sqlite3_bind_blob|sqlite3_bind()], ** [sqlite3_bind_parameter_name()], and @@ -3073,30 +3510,30 @@ SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); ** ** INVARIANTS: ** -** {F13601} The [sqlite3_bind_parameter_count(S)] interface returns +** {H13601} The [sqlite3_bind_parameter_count(S)] interface returns ** the largest index of all SQL parameters in the -** [prepared statement] S, or 0 if S -** contains no SQL parameters. +** [prepared statement] S, or 0 if S contains no SQL parameters. */ SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*); /* -** CAPI3REF: Name Of A Host Parameter {F13620} +** CAPI3REF: Name Of A Host Parameter {H13620} <S70300> ** ** This routine returns a pointer to the name of the n-th -** SQL parameter in a [prepared statement]. +** [SQL parameter] in a [prepared statement]. ** SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA" ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA" ** respectively. ** In other words, the initial ":" or "$" or "@" or "?" ** is included as part of the name. -** Parameters of the form "?" without a following integer have no name. +** Parameters of the form "?" without a following integer have no name +** and are also referred to as "anonymous parameters". ** ** The first host parameter has an index of 1, not 0. ** ** If the value n is out of range or if the n-th parameter is ** nameless, then NULL is returned. The returned string is -** always in the UTF-8 encoding even if the named parameter was +** always in UTF-8 encoding even if the named parameter was ** originally specified as UTF-16 in [sqlite3_prepare16()] or ** [sqlite3_prepare16_v2()]. ** @@ -3106,16 +3543,16 @@ SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*); ** ** INVARIANTS: ** -** {F13621} The [sqlite3_bind_parameter_name(S,N)] interface returns +** {H13621} The [sqlite3_bind_parameter_name(S,N)] interface returns ** a UTF-8 rendering of the name of the SQL parameter in -** [prepared statement] S having index N, or +** the [prepared statement] S having index N, or ** NULL if there is no SQL parameter with index N or if the ** parameter with index N is an anonymous parameter "?". */ SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); /* -** CAPI3REF: Index Of A Parameter With A Given Name {F13640} +** CAPI3REF: Index Of A Parameter With A Given Name {H13640} <S70300> ** ** Return the index of an SQL parameter given its name. The ** index value returned is suitable for use as the second @@ -3130,62 +3567,56 @@ SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); ** ** INVARIANTS: ** -** {F13641} The [sqlite3_bind_parameter_index(S,N)] interface returns -** the index of SQL parameter in [prepared statement] +** {H13641} The [sqlite3_bind_parameter_index(S,N)] interface returns +** the index of SQL parameter in the [prepared statement] ** S whose name matches the UTF-8 string N, or 0 if there is ** no match. */ SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); /* -** CAPI3REF: Reset All Bindings On A Prepared Statement {F13660} +** CAPI3REF: Reset All Bindings On A Prepared Statement {H13660} <S70300> ** -** Contrary to the intuition of many, [sqlite3_reset()] does not -** reset the [sqlite3_bind_blob | bindings] on a -** [prepared statement]. Use this routine to -** reset all host parameters to NULL. +** Contrary to the intuition of many, [sqlite3_reset()] does not reset +** the [sqlite3_bind_blob | bindings] on a [prepared statement]. +** Use this routine to reset all host parameters to NULL. ** ** INVARIANTS: ** -** {F13661} The [sqlite3_clear_bindings(S)] interface resets all -** SQL parameter bindings in [prepared statement] S -** back to NULL. +** {H13661} The [sqlite3_clear_bindings(S)] interface resets all SQL +** parameter bindings in the [prepared statement] S back to NULL. */ SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*); /* -** CAPI3REF: Number Of Columns In A Result Set {F13710} +** CAPI3REF: Number Of Columns In A Result Set {H13710} <S10700> ** -** Return the number of columns in the result set returned by the -** [prepared statement]. This routine returns 0 -** if pStmt is an SQL statement that does not return data (for -** example an UPDATE). +** Return the number of columns in the result set returned by the +** [prepared statement]. This routine returns 0 if pStmt is an SQL +** statement that does not return data (for example an [UPDATE]). ** ** INVARIANTS: ** -** {F13711} The [sqlite3_column_count(S)] interface returns the number of -** columns in the result set generated by the -** [prepared statement] S, or 0 if S does not generate -** a result set. +** {H13711} The [sqlite3_column_count(S)] interface returns the number of +** columns in the result set generated by the [prepared statement] S, +** or 0 if S does not generate a result set. */ SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt); /* -** CAPI3REF: Column Names In A Result Set {F13720} +** CAPI3REF: Column Names In A Result Set {H13720} <S10700> ** ** These routines return the name assigned to a particular column -** in the result set of a SELECT statement. The sqlite3_column_name() -** interface returns a pointer to a zero-terminated UTF8 string +** in the result set of a [SELECT] statement. The sqlite3_column_name() +** interface returns a pointer to a zero-terminated UTF-8 string ** and sqlite3_column_name16() returns a pointer to a zero-terminated -** UTF16 string. The first parameter is the -** [prepared statement] that implements the SELECT statement. -** The second parameter is the column number. The left-most column is -** number 0. +** UTF-16 string. The first parameter is the [prepared statement] +** that implements the [SELECT] statement. The second parameter is the +** column number. The leftmost column is number 0. ** -** The returned string pointer is valid until either the -** [prepared statement] is destroyed by [sqlite3_finalize()] -** or until the next call sqlite3_column_name() or sqlite3_column_name16() -** on the same column. +** The returned string pointer is valid until either the [prepared statement] +** is destroyed by [sqlite3_finalize()] or until the next call to +** sqlite3_column_name() or sqlite3_column_name16() on the same column. ** ** If sqlite3_malloc() fails during the processing of either routine ** (for example during a conversion from UTF-8 to UTF-16) then a @@ -3198,136 +3629,124 @@ SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt); ** ** INVARIANTS: ** -** {F13721} A successful invocation of the [sqlite3_column_name(S,N)] -** interface returns the name -** of the Nth column (where 0 is the left-most column) for the -** result set of [prepared statement] S as a -** zero-terminated UTF-8 string. +** {H13721} A successful invocation of the [sqlite3_column_name(S,N)] +** interface returns the name of the Nth column (where 0 is +** the leftmost column) for the result set of the +** [prepared statement] S as a zero-terminated UTF-8 string. ** -** {F13723} A successful invocation of the [sqlite3_column_name16(S,N)] -** interface returns the name -** of the Nth column (where 0 is the left-most column) for the -** result set of [prepared statement] S as a -** zero-terminated UTF-16 string in the native byte order. +** {H13723} A successful invocation of the [sqlite3_column_name16(S,N)] +** interface returns the name of the Nth column (where 0 is +** the leftmost column) for the result set of the +** [prepared statement] S as a zero-terminated UTF-16 string +** in the native byte order. ** -** {F13724} The [sqlite3_column_name()] and [sqlite3_column_name16()] +** {H13724} The [sqlite3_column_name()] and [sqlite3_column_name16()] ** interfaces return a NULL pointer if they are unable to -** allocate memory memory to hold there normal return strings. +** allocate memory to hold their normal return strings. ** -** {F13725} If the N parameter to [sqlite3_column_name(S,N)] or +** {H13725} If the N parameter to [sqlite3_column_name(S,N)] or ** [sqlite3_column_name16(S,N)] is out of range, then the -** interfaces returns a NULL pointer. -** -** {F13726} The strings returned by [sqlite3_column_name(S,N)] and +** interfaces return a NULL pointer. +** +** {H13726} The strings returned by [sqlite3_column_name(S,N)] and ** [sqlite3_column_name16(S,N)] are valid until the next ** call to either routine with the same S and N parameters ** or until [sqlite3_finalize(S)] is called. ** -** {F13727} When a result column of a [SELECT] statement contains -** an AS clause, the name of that column is the indentifier +** {H13727} When a result column of a [SELECT] statement contains +** an AS clause, the name of that column is the identifier ** to the right of the AS keyword. */ SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N); SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N); /* -** CAPI3REF: Source Of Data In A Query Result {F13740} +** CAPI3REF: Source Of Data In A Query Result {H13740} <S10700> ** ** These routines provide a means to determine what column of what -** table in which database a result of a SELECT statement comes from. +** table in which database a result of a [SELECT] statement comes from. ** The name of the database or table or column can be returned as -** either a UTF8 or UTF16 string. The _database_ routines return +** either a UTF-8 or UTF-16 string. The _database_ routines return ** the database name, the _table_ routines return the table name, and ** the origin_ routines return the column name. -** The returned string is valid until -** the [prepared statement] is destroyed using -** [sqlite3_finalize()] or until the same information is requested +** The returned string is valid until the [prepared statement] is destroyed +** using [sqlite3_finalize()] or until the same information is requested ** again in a different encoding. ** ** The names returned are the original un-aliased names of the ** database, table, and column. ** ** The first argument to the following calls is a [prepared statement]. -** These functions return information about the Nth column returned by +** These functions return information about the Nth column returned by ** the statement, where N is the second function argument. ** -** If the Nth column returned by the statement is an expression -** or subquery and is not a column value, then all of these functions -** return NULL. These routine might also return NULL if a memory -** allocation error occurs. Otherwise, they return the -** name of the attached database, table and column that query result -** column was extracted from. +** If the Nth column returned by the statement is an expression or +** subquery and is not a column value, then all of these functions return +** NULL. These routine might also return NULL if a memory allocation error +** occurs. Otherwise, they return the name of the attached database, table +** and column that query result column was extracted from. ** ** As with all other SQLite APIs, those postfixed with "16" return ** UTF-16 encoded strings, the other functions return UTF-8. {END} ** -** These APIs are only available if the library was compiled with the -** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. +** These APIs are only available if the library was compiled with the +** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined. ** -** {U13751} +** {A13751} ** If two or more threads call one or more of these routines against the same ** prepared statement and column at the same time then the results are ** undefined. ** ** INVARIANTS: ** -** {F13741} The [sqlite3_column_database_name(S,N)] interface returns either -** the UTF-8 zero-terminated name of the database from which the -** Nth result column of [prepared statement] S -** is extracted, or NULL if the the Nth column of S is a -** general expression or if unable to allocate memory -** to store the name. -** -** {F13742} The [sqlite3_column_database_name16(S,N)] interface returns either -** the UTF-16 native byte order -** zero-terminated name of the database from which the -** Nth result column of [prepared statement] S -** is extracted, or NULL if the the Nth column of S is a -** general expression or if unable to allocate memory -** to store the name. -** -** {F13743} The [sqlite3_column_table_name(S,N)] interface returns either -** the UTF-8 zero-terminated name of the table from which the -** Nth result column of [prepared statement] S -** is extracted, or NULL if the the Nth column of S is a -** general expression or if unable to allocate memory -** to store the name. -** -** {F13744} The [sqlite3_column_table_name16(S,N)] interface returns either -** the UTF-16 native byte order -** zero-terminated name of the table from which the -** Nth result column of [prepared statement] S -** is extracted, or NULL if the the Nth column of S is a -** general expression or if unable to allocate memory -** to store the name. -** -** {F13745} The [sqlite3_column_origin_name(S,N)] interface returns either -** the UTF-8 zero-terminated name of the table column from which the -** Nth result column of [prepared statement] S -** is extracted, or NULL if the the Nth column of S is a -** general expression or if unable to allocate memory -** to store the name. -** -** {F13746} The [sqlite3_column_origin_name16(S,N)] interface returns either -** the UTF-16 native byte order -** zero-terminated name of the table column from which the -** Nth result column of [prepared statement] S -** is extracted, or NULL if the the Nth column of S is a -** general expression or if unable to allocate memory +** {H13741} The [sqlite3_column_database_name(S,N)] interface returns either +** the UTF-8 zero-terminated name of the database from which the +** Nth result column of the [prepared statement] S is extracted, +** or NULL if the Nth column of S is a general expression +** or if unable to allocate memory to store the name. +** +** {H13742} The [sqlite3_column_database_name16(S,N)] interface returns either +** the UTF-16 native byte order zero-terminated name of the database +** from which the Nth result column of the [prepared statement] S is +** extracted, or NULL if the Nth column of S is a general expression +** or if unable to allocate memory to store the name. +** +** {H13743} The [sqlite3_column_table_name(S,N)] interface returns either +** the UTF-8 zero-terminated name of the table from which the +** Nth result column of the [prepared statement] S is extracted, +** or NULL if the Nth column of S is a general expression +** or if unable to allocate memory to store the name. +** +** {H13744} The [sqlite3_column_table_name16(S,N)] interface returns either +** the UTF-16 native byte order zero-terminated name of the table +** from which the Nth result column of the [prepared statement] S is +** extracted, or NULL if the Nth column of S is a general expression +** or if unable to allocate memory to store the name. +** +** {H13745} The [sqlite3_column_origin_name(S,N)] interface returns either +** the UTF-8 zero-terminated name of the table column from which the +** Nth result column of the [prepared statement] S is extracted, +** or NULL if the Nth column of S is a general expression +** or if unable to allocate memory to store the name. +** +** {H13746} The [sqlite3_column_origin_name16(S,N)] interface returns either +** the UTF-16 native byte order zero-terminated name of the table +** column from which the Nth result column of the +** [prepared statement] S is extracted, or NULL if the Nth column +** of S is a general expression or if unable to allocate memory ** to store the name. -** -** {F13748} The return values from -** [sqlite3_column_database_name|column metadata interfaces] -** are valid -** for the lifetime of the [prepared statement] +** +** {H13748} The return values from +** [sqlite3_column_database_name | column metadata interfaces] +** are valid for the lifetime of the [prepared statement] ** or until the encoding is changed by another metadata ** interface call for the same prepared statement and column. ** -** LIMITATIONS: +** ASSUMPTIONS: ** -** {U13751} If two or more threads call one or more -** [sqlite3_column_database_name|column metadata interfaces] -** the same [prepared statement] and result column +** {A13751} If two or more threads call one or more +** [sqlite3_column_database_name | column metadata interfaces] +** for the same [prepared statement] and result column ** at the same time then the results are undefined. */ SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int); @@ -3338,26 +3757,26 @@ SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int); SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); /* -** CAPI3REF: Declared Datatype Of A Query Result {F13760} +** CAPI3REF: Declared Datatype Of A Query Result {H13760} <S10700> ** -** The first parameter is a [prepared statement]. -** If this statement is a SELECT statement and the Nth column of the -** returned result set of that SELECT is a table column (not an +** The first parameter is a [prepared statement]. +** If this statement is a [SELECT] statement and the Nth column of the +** returned result set of that [SELECT] is a table column (not an ** expression or subquery) then the declared type of the table ** column is returned. If the Nth column of the result set is an ** expression or subquery, then a NULL pointer is returned. -** The returned string is always UTF-8 encoded. {END} -** For example, in the database schema: +** The returned string is always UTF-8 encoded. {END} +** +** For example, given the database schema: ** ** CREATE TABLE t1(c1 VARIANT); ** -** And the following statement compiled: +** and the following statement to be compiled: ** ** SELECT c1 + 1, c1 FROM t1; ** -** Then this routine would return the string "VARIANT" for the second -** result column (i==1), and a NULL pointer for the first result column -** (i==0). +** this routine would return the string "VARIANT" for the second result +** column (i==1), and a NULL pointer for the first result column (i==0). ** ** SQLite uses dynamic run-time typing. So just because a column ** is declared to contain a particular type does not mean that the @@ -3368,22 +3787,21 @@ SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); ** ** INVARIANTS: ** -** {F13761} A successful call to [sqlite3_column_decltype(S,N)] -** returns a zero-terminated UTF-8 string containing the -** the declared datatype of the table column that appears -** as the Nth column (numbered from 0) of the result set to the -** [prepared statement] S. +** {H13761} A successful call to [sqlite3_column_decltype(S,N)] returns a +** zero-terminated UTF-8 string containing the declared datatype +** of the table column that appears as the Nth column (numbered +** from 0) of the result set to the [prepared statement] S. ** -** {F13762} A successful call to [sqlite3_column_decltype16(S,N)] +** {H13762} A successful call to [sqlite3_column_decltype16(S,N)] ** returns a zero-terminated UTF-16 native byte order string ** containing the declared datatype of the table column that appears ** as the Nth column (numbered from 0) of the result set to the ** [prepared statement] S. ** -** {F13763} If N is less than 0 or N is greater than or equal to -** the number of columns in [prepared statement] S +** {H13763} If N is less than 0 or N is greater than or equal to +** the number of columns in the [prepared statement] S, ** or if the Nth column of S is an expression or subquery rather -** than a table column or if a memory allocation failure +** than a table column, or if a memory allocation failure ** occurs during encoding conversions, then ** calls to [sqlite3_column_decltype(S,N)] or ** [sqlite3_column_decltype16(S,N)] return NULL. @@ -3391,32 +3809,30 @@ SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int); SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int); -/* -** CAPI3REF: Evaluate An SQL Statement {F13200} +/* +** CAPI3REF: Evaluate An SQL Statement {H13200} <S10000> ** -** After an [prepared statement] has been prepared with a call -** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of -** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], -** then this function must be called one or more times to evaluate the -** statement. +** After a [prepared statement] has been prepared using either +** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy +** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function +** must be called one or more times to evaluate the statement. ** -** The details of the behavior of this sqlite3_step() interface depend +** The details of the behavior of the sqlite3_step() interface depend ** on whether the statement was prepared using the newer "v2" interface ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy ** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the ** new "v2" interface is recommended for new applications but the legacy ** interface will continue to be supported. ** -** In the legacy interface, the return value will be either [SQLITE_BUSY], +** In the legacy interface, the return value will be either [SQLITE_BUSY], ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE]. -** With the "v2" interface, any of the other [SQLITE_OK | result code] -** or [SQLITE_IOERR_READ | extended result code] might be returned as -** well. +** With the "v2" interface, any of the other [result codes] or +** [extended result codes] might be returned as well. ** ** [SQLITE_BUSY] means that the database engine was unable to acquire the -** database locks it needs to do its job. If the statement is a COMMIT +** database locks it needs to do its job. If the statement is a [COMMIT] ** or occurs outside of an explicit transaction, then you can retry the -** statement. If the statement is not a COMMIT and occurs within a +** statement. If the statement is not a [COMMIT] and occurs within a ** explicit transaction then you should rollback the transaction before ** continuing. ** @@ -3425,16 +3841,15 @@ SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int); ** machine without first calling [sqlite3_reset()] to reset the virtual ** machine back to its initial state. ** -** If the SQL statement being executed returns any data, then -** [SQLITE_ROW] is returned each time a new row of data is ready -** for processing by the caller. The values may be accessed using -** the [sqlite3_column_int | column access functions]. +** If the SQL statement being executed returns any data, then [SQLITE_ROW] +** is returned each time a new row of data is ready for processing by the +** caller. The values may be accessed using the [column access functions]. ** sqlite3_step() is called again to retrieve the next row of data. -** +** ** [SQLITE_ERROR] means that a run-time error (such as a constraint ** violation) has occurred. sqlite3_step() should not be called again on ** the VM. More information may be found by calling [sqlite3_errmsg()]. -** With the legacy interface, a more specific error code (example: +** With the legacy interface, a more specific error code (for example, ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth) ** can be obtained by calling [sqlite3_reset()] on the ** [prepared statement]. In the "v2" interface, @@ -3442,80 +3857,75 @@ SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int); ** ** [SQLITE_MISUSE] means that the this routine was called inappropriately. ** Perhaps it was called on a [prepared statement] that has -** already been [sqlite3_finalize | finalized] or on one that had +** already been [sqlite3_finalize | finalized] or on one that had ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could ** be the case that the same database connection is being used by two or ** more threads at the same moment in time. ** -** <b>Goofy Interface Alert:</b> -** In the legacy interface, -** the sqlite3_step() API always returns a generic error code, -** [SQLITE_ERROR], following any error other than [SQLITE_BUSY] -** and [SQLITE_MISUSE]. You must call [sqlite3_reset()] or -** [sqlite3_finalize()] in order to find one of the specific -** [error codes] that better describes the error. +** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step() +** API always returns a generic error code, [SQLITE_ERROR], following any +** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call +** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the +** specific [error codes] that better describes the error. ** We admit that this is a goofy design. The problem has been fixed ** with the "v2" interface. If you prepare all of your SQL statements ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead -** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the -** more specific [error codes] are returned directly +** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces, +** then the more specific [error codes] are returned directly ** by sqlite3_step(). The use of the "v2" interface is recommended. ** ** INVARIANTS: ** -** {F13202} If [prepared statement] S is ready to be -** run, then [sqlite3_step(S)] advances that prepared statement -** until to completion or until it is ready to return another -** row of the result set or an interrupt or run-time error occurs. +** {H13202} If the [prepared statement] S is ready to be run, then +** [sqlite3_step(S)] advances that prepared statement until +** completion or until it is ready to return another row of the +** result set, or until an [sqlite3_interrupt | interrupt] +** or a run-time error occurs. ** -** {F15304} When a call to [sqlite3_step(S)] causes the -** [prepared statement] S to run to completion, -** the function returns [SQLITE_DONE]. +** {H15304} When a call to [sqlite3_step(S)] causes the [prepared statement] +** S to run to completion, the function returns [SQLITE_DONE]. ** -** {F15306} When a call to [sqlite3_step(S)] stops because it is ready -** to return another row of the result set, it returns -** [SQLITE_ROW]. +** {H15306} When a call to [sqlite3_step(S)] stops because it is ready to +** return another row of the result set, it returns [SQLITE_ROW]. ** -** {F15308} If a call to [sqlite3_step(S)] encounters an -** [sqlite3_interrupt|interrupt] or a run-time error, -** it returns an appropraite error code that is not one of +** {H15308} If a call to [sqlite3_step(S)] encounters an +** [sqlite3_interrupt | interrupt] or a run-time error, +** it returns an appropriate error code that is not one of ** [SQLITE_OK], [SQLITE_ROW], or [SQLITE_DONE]. ** -** {F15310} If an [sqlite3_interrupt|interrupt] or run-time error +** {H15310} If an [sqlite3_interrupt | interrupt] or a run-time error ** occurs during a call to [sqlite3_step(S)] ** for a [prepared statement] S created using ** legacy interfaces [sqlite3_prepare()] or -** [sqlite3_prepare16()] then the function returns either +** [sqlite3_prepare16()], then the function returns either ** [SQLITE_ERROR], [SQLITE_BUSY], or [SQLITE_MISUSE]. */ SQLITE_API int sqlite3_step(sqlite3_stmt*); /* -** CAPI3REF: Number of columns in a result set {F13770} +** CAPI3REF: Number of columns in a result set {H13770} <S10700> ** -** Return the number of values in the current row of the result set. +** Returns the number of values in the current row of the result set. ** ** INVARIANTS: ** -** {F13771} After a call to [sqlite3_step(S)] that returns -** [SQLITE_ROW], the [sqlite3_data_count(S)] routine -** will return the same value as the -** [sqlite3_column_count(S)] function. +** {H13771} After a call to [sqlite3_step(S)] that returns [SQLITE_ROW], +** the [sqlite3_data_count(S)] routine will return the same value +** as the [sqlite3_column_count(S)] function. ** -** {F13772} After [sqlite3_step(S)] has returned any value other than -** [SQLITE_ROW] or before [sqlite3_step(S)] has been -** called on the [prepared statement] for -** the first time since it was [sqlite3_prepare|prepared] -** or [sqlite3_reset|reset], the [sqlite3_data_count(S)] -** routine returns zero. +** {H13772} After [sqlite3_step(S)] has returned any value other than +** [SQLITE_ROW] or before [sqlite3_step(S)] has been called on the +** [prepared statement] for the first time since it was +** [sqlite3_prepare | prepared] or [sqlite3_reset | reset], +** the [sqlite3_data_count(S)] routine returns zero. */ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt); /* -** CAPI3REF: Fundamental Datatypes {F10265} +** CAPI3REF: Fundamental Datatypes {H10265} <S10110><S10120> ** KEYWORDS: SQLITE_TEXT ** -** {F10266}Every value in SQLite has one of five fundamental datatypes: +** {H10266} Every value in SQLite has one of five fundamental datatypes: ** ** <ul> ** <li> 64-bit signed integer @@ -3529,7 +3939,7 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt); ** ** Note that the SQLITE_TEXT constant was also used in SQLite version 2 ** for a completely different meaning. Software that links against both -** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not +** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not ** SQLITE_TEXT. */ #define SQLITE_INTEGER 1 @@ -3544,33 +3954,31 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt); #define SQLITE3_TEXT 3 /* -** CAPI3REF: Results Values From A Query {F13800} +** CAPI3REF: Result Values From A Query {H13800} <S10700> +** KEYWORDS: {column access functions} ** ** These routines form the "result set query" interface. ** -** These routines return information about -** a single column of the current result row of a query. In every -** case the first argument is a pointer to the -** [prepared statement] that is being -** evaluated (the [sqlite3_stmt*] that was returned from -** [sqlite3_prepare_v2()] or one of its variants) and -** the second argument is the index of the column for which information -** should be returned. The left-most column of the result set -** has an index of 0. -** -** If the SQL statement is not currently point to a valid row, or if the -** the column index is out of range, the result is undefined. +** These routines return information about a single column of the current +** result row of a query. In every case the first argument is a pointer +** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*] +** that was returned from [sqlite3_prepare_v2()] or one of its variants) +** and the second argument is the index of the column for which information +** should be returned. The leftmost column of the result set has the index 0. +** +** If the SQL statement does not currently point to a valid row, or if the +** column index is out of range, the result is undefined. ** These routines may only be called when the most recent call to ** [sqlite3_step()] has returned [SQLITE_ROW] and neither -** [sqlite3_reset()] nor [sqlite3_finalize()] has been call subsequently. +** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently. ** If any of these routines are called after [sqlite3_reset()] or ** [sqlite3_finalize()] or after [sqlite3_step()] has returned ** something other than [SQLITE_ROW], the results are undefined. ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()] ** are called from a different thread while any of these routines -** are pending, then the results are undefined. +** are pending, then the results are undefined. ** -** The sqlite3_column_type() routine returns +** The sqlite3_column_type() routine returns the ** [SQLITE_INTEGER | datatype code] for the initial data type ** of the result column. The returned value is one of [SQLITE_INTEGER], ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value @@ -3580,7 +3988,7 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt); ** versions of SQLite may change the behavior of sqlite3_column_type() ** following a type conversion. ** -** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() +** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() ** routine returns the number of bytes in that BLOB or string. ** If the result is a UTF-16 string, then sqlite3_column_bytes() converts ** the string to UTF-8 and then returns the number of bytes. @@ -3593,11 +4001,11 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt); ** ** Strings returned by sqlite3_column_text() and sqlite3_column_text16(), ** even empty strings, are always zero terminated. The return -** value from sqlite3_column_blob() for a zero-length blob is an arbitrary +** value from sqlite3_column_blob() for a zero-length BLOB is an arbitrary ** pointer, possibly even a NULL pointer. ** ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes() -** but leaves the result in UTF-16 in native byte order instead of UTF-8. +** but leaves the result in UTF-16 in native byte order instead of UTF-8. ** The zero terminator is not included in this count. ** ** The object returned by [sqlite3_column_value()] is an @@ -3605,15 +4013,14 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt); ** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()]. ** If the [unprotected sqlite3_value] object returned by ** [sqlite3_column_value()] is used in any other way, including calls -** to routines like -** [sqlite3_value_int()], [sqlite3_value_text()], or [sqlite3_value_bytes()], -** then the behavior is undefined. +** to routines like [sqlite3_value_int()], [sqlite3_value_text()], +** or [sqlite3_value_bytes()], then the behavior is undefined. ** ** These routines attempt to convert the value where appropriate. For ** example, if the internal representation is FLOAT and a text result -** is requested, [sqlite3_snprintf()] is used internally to do the conversion -** automatically. The following table details the conversions that -** are applied: +** is requested, [sqlite3_snprintf()] is used internally to perform the +** conversion automatically. The following table details the conversions +** that are applied: ** ** <blockquote> ** <table border="1"> @@ -3625,7 +4032,7 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt); ** <tr><td> NULL <td> BLOB <td> Result is NULL pointer ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer -** <tr><td> INTEGER <td> BLOB <td> Same as for INTEGER->TEXT +** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT ** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer ** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float ** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT @@ -3640,57 +4047,56 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt); ** ** The table above makes reference to standard C library functions atoi() ** and atof(). SQLite does not really use these functions. It has its -** on equavalent internal routines. The atoi() and atof() names are +** own equivalent internal routines. The atoi() and atof() names are ** used in the table for brevity and because they are familiar to most ** C programmers. ** ** Note that when type conversions occur, pointers returned by prior ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or -** sqlite3_column_text16() may be invalidated. +** sqlite3_column_text16() may be invalidated. ** Type conversions and pointer invalidations might occur ** in the following cases: ** ** <ul> -** <li><p> The initial content is a BLOB and sqlite3_column_text() -** or sqlite3_column_text16() is called. A zero-terminator might -** need to be added to the string.</p></li> -** -** <li><p> The initial content is UTF-8 text and sqlite3_column_bytes16() or -** sqlite3_column_text16() is called. The content must be converted -** to UTF-16.</p></li> -** -** <li><p> The initial content is UTF-16 text and sqlite3_column_bytes() or -** sqlite3_column_text() is called. The content must be converted -** to UTF-8.</p></li> +** <li> The initial content is a BLOB and sqlite3_column_text() or +** sqlite3_column_text16() is called. A zero-terminator might +** need to be added to the string.</li> +** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or +** sqlite3_column_text16() is called. The content must be converted +** to UTF-16.</li> +** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or +** sqlite3_column_text() is called. The content must be converted +** to UTF-8.</li> ** </ul> ** ** Conversions between UTF-16be and UTF-16le are always done in place and do ** not invalidate a prior pointer, though of course the content of the buffer ** that the prior pointer points to will have been modified. Other kinds -** of conversion are done in place when it is possible, but sometime it is -** not possible and in those cases prior pointers are invalidated. +** of conversion are done in place when it is possible, but sometimes they +** are not possible and in those cases prior pointers are invalidated. ** ** The safest and easiest to remember policy is to invoke these routines ** in one of the following ways: ** -** <ul> +** <ul> ** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li> ** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li> ** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li> -** </ul> +** </ul> ** -** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(), -** or sqlite3_column_text16() first to force the result into the desired -** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to -** find the size of the result. Do not mix call to sqlite3_column_text() or -** sqlite3_column_blob() with calls to sqlite3_column_bytes16(). And do not -** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes(). +** In other words, you should call sqlite3_column_text(), +** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result +** into the desired format, then invoke sqlite3_column_bytes() or +** sqlite3_column_bytes16() to find the size of the result. Do not mix calls +** to sqlite3_column_text() or sqlite3_column_blob() with calls to +** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() +** with calls to sqlite3_column_bytes(). ** ** The pointers returned are valid until a type conversion occurs as ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or ** [sqlite3_finalize()] is called. The memory space used to hold strings -** and blobs is freed automatically. Do <b>not</b> pass the pointers returned -** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into +** and BLOBs is freed automatically. Do <b>not</b> pass the pointers returned +** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into ** [sqlite3_free()]. ** ** If a memory allocation error occurs during the evaluation of any @@ -3701,58 +4107,58 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt); ** ** INVARIANTS: ** -** {F13803} The [sqlite3_column_blob(S,N)] interface converts the +** {H13803} The [sqlite3_column_blob(S,N)] interface converts the ** Nth column in the current row of the result set for -** [prepared statement] S into a blob and then returns a +** the [prepared statement] S into a BLOB and then returns a ** pointer to the converted value. ** -** {F13806} The [sqlite3_column_bytes(S,N)] interface returns the -** number of bytes in the blob or string (exclusive of the +** {H13806} The [sqlite3_column_bytes(S,N)] interface returns the +** number of bytes in the BLOB or string (exclusive of the ** zero terminator on the string) that was returned by the ** most recent call to [sqlite3_column_blob(S,N)] or ** [sqlite3_column_text(S,N)]. ** -** {F13809} The [sqlite3_column_bytes16(S,N)] interface returns the +** {H13809} The [sqlite3_column_bytes16(S,N)] interface returns the ** number of bytes in the string (exclusive of the ** zero terminator on the string) that was returned by the ** most recent call to [sqlite3_column_text16(S,N)]. ** -** {F13812} The [sqlite3_column_double(S,N)] interface converts the -** Nth column in the current row of the result set for +** {H13812} The [sqlite3_column_double(S,N)] interface converts the +** Nth column in the current row of the result set for the ** [prepared statement] S into a floating point value and ** returns a copy of that value. ** -** {F13815} The [sqlite3_column_int(S,N)] interface converts the -** Nth column in the current row of the result set for +** {H13815} The [sqlite3_column_int(S,N)] interface converts the +** Nth column in the current row of the result set for the ** [prepared statement] S into a 64-bit signed integer and ** returns the lower 32 bits of that integer. ** -** {F13818} The [sqlite3_column_int64(S,N)] interface converts the -** Nth column in the current row of the result set for +** {H13818} The [sqlite3_column_int64(S,N)] interface converts the +** Nth column in the current row of the result set for the ** [prepared statement] S into a 64-bit signed integer and ** returns a copy of that integer. ** -** {F13821} The [sqlite3_column_text(S,N)] interface converts the +** {H13821} The [sqlite3_column_text(S,N)] interface converts the ** Nth column in the current row of the result set for -** [prepared statement] S into a zero-terminated UTF-8 +** the [prepared statement] S into a zero-terminated UTF-8 ** string and returns a pointer to that string. ** -** {F13824} The [sqlite3_column_text16(S,N)] interface converts the -** Nth column in the current row of the result set for +** {H13824} The [sqlite3_column_text16(S,N)] interface converts the +** Nth column in the current row of the result set for the ** [prepared statement] S into a zero-terminated 2-byte -** aligned UTF-16 native byte order -** string and returns a pointer to that string. +** aligned UTF-16 native byte order string and returns +** a pointer to that string. ** -** {F13827} The [sqlite3_column_type(S,N)] interface returns +** {H13827} The [sqlite3_column_type(S,N)] interface returns ** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT], ** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for ** the Nth column in the current row of the result set for -** [prepared statement] S. +** the [prepared statement] S. ** -** {F13830} The [sqlite3_column_value(S,N)] interface returns a +** {H13830} The [sqlite3_column_value(S,N)] interface returns a ** pointer to an [unprotected sqlite3_value] object for the ** Nth column in the current row of the result set for -** [prepared statement] S. +** the [prepared statement] S. */ SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol); @@ -3766,90 +4172,88 @@ SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol); SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); /* -** CAPI3REF: Destroy A Prepared Statement Object {F13300} +** CAPI3REF: Destroy A Prepared Statement Object {H13300} <S70300><S30100> ** -** The sqlite3_finalize() function is called to delete a -** [prepared statement]. If the statement was -** executed successfully, or not executed at all, then SQLITE_OK is returned. -** If execution of the statement failed then an -** [error code] or [extended error code] -** is returned. +** The sqlite3_finalize() function is called to delete a [prepared statement]. +** If the statement was executed successfully or not executed at all, then +** SQLITE_OK is returned. If execution of the statement failed then an +** [error code] or [extended error code] is returned. ** ** This routine can be called at any point during the execution of the -** [prepared statement]. If the virtual machine has not +** [prepared statement]. If the virtual machine has not ** completed execution when this routine is called, that is like -** encountering an error or an interrupt. (See [sqlite3_interrupt()].) -** Incomplete updates may be rolled back and transactions cancelled, -** depending on the circumstances, and the +** encountering an error or an [sqlite3_interrupt | interrupt]. +** Incomplete updates may be rolled back and transactions canceled, +** depending on the circumstances, and the ** [error code] returned will be [SQLITE_ABORT]. ** ** INVARIANTS: ** -** {F11302} The [sqlite3_finalize(S)] interface destroys the +** {H11302} The [sqlite3_finalize(S)] interface destroys the ** [prepared statement] S and releases all ** memory and file resources held by that object. ** -** {F11304} If the most recent call to [sqlite3_step(S)] for the +** {H11304} If the most recent call to [sqlite3_step(S)] for the ** [prepared statement] S returned an error, ** then [sqlite3_finalize(S)] returns that same error. */ SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt); /* -** CAPI3REF: Reset A Prepared Statement Object {F13330} +** CAPI3REF: Reset A Prepared Statement Object {H13330} <S70300> ** -** The sqlite3_reset() function is called to reset a -** [prepared statement] object. -** back to its initial state, ready to be re-executed. +** The sqlite3_reset() function is called to reset a [prepared statement] +** object back to its initial state, ready to be re-executed. ** Any SQL statement variables that had values bound to them using ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values. ** Use [sqlite3_clear_bindings()] to reset the bindings. ** -** {F11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S +** {H11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S ** back to the beginning of its program. ** -** {F11334} If the most recent call to [sqlite3_step(S)] for +** {H11334} If the most recent call to [sqlite3_step(S)] for the ** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE], ** or if [sqlite3_step(S)] has never before been called on S, ** then [sqlite3_reset(S)] returns [SQLITE_OK]. ** -** {F11336} If the most recent call to [sqlite3_step(S)] for +** {H11336} If the most recent call to [sqlite3_step(S)] for the ** [prepared statement] S indicated an error, then ** [sqlite3_reset(S)] returns an appropriate [error code]. ** -** {F11338} The [sqlite3_reset(S)] interface does not change the values -** of any [sqlite3_bind_blob|bindings] on [prepared statement] S. +** {H11338} The [sqlite3_reset(S)] interface does not change the values +** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S. */ SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt); /* -** CAPI3REF: Create Or Redefine SQL Functions {F16100} -** KEYWORDS: {function creation routines} +** CAPI3REF: Create Or Redefine SQL Functions {H16100} <S20200> +** KEYWORDS: {function creation routines} +** KEYWORDS: {application-defined SQL function} +** KEYWORDS: {application-defined SQL functions} ** -** These two functions (collectively known as -** "function creation routines") are used to add SQL functions or aggregates -** or to redefine the behavior of existing SQL functions or aggregates. The -** difference only between the two is that the second parameter, the -** name of the (scalar) function or aggregate, is encoded in UTF-8 for -** sqlite3_create_function() and UTF-16 for sqlite3_create_function16(). +** These two functions (collectively known as "function creation routines") +** are used to add SQL functions or aggregates or to redefine the behavior +** of existing SQL functions or aggregates. The only difference between the +** two is that the second parameter, the name of the (scalar) function or +** aggregate, is encoded in UTF-8 for sqlite3_create_function() and UTF-16 +** for sqlite3_create_function16(). ** ** The first parameter is the [database connection] to which the SQL -** function is to be added. If a single -** program uses more than one [database connection] internally, then SQL -** functions must be added individually to each [database connection]. -** -** The second parameter is the name of the SQL function to be created -** or redefined. -** The length of the name is limited to 255 bytes, exclusive of the -** zero-terminator. Note that the name length limit is in bytes, not +** function is to be added. If a single program uses more than one database +** connection internally, then SQL functions must be added individually to +** each database connection. +** +** The second parameter is the name of the SQL function to be created or +** redefined. The length of the name is limited to 255 bytes, exclusive of +** the zero-terminator. Note that the name length limit is in bytes, not ** characters. Any attempt to create a function with a longer name -** will result in an SQLITE_ERROR error. +** will result in [SQLITE_ERROR] being returned. ** ** The third parameter is the number of arguments that the SQL function or ** aggregate takes. If this parameter is negative, then the SQL function or ** aggregate may take any number of arguments. ** -** The fourth parameter, eTextRep, specifies what +** The fourth parameter, eTextRep, specifies what ** [SQLITE_UTF8 | text encoding] this SQL function prefers for ** its parameters. Any SQL function implementation should be able to work ** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be @@ -3858,90 +4262,86 @@ SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt); ** times with the same function but with different values of eTextRep. ** When multiple implementations of the same function are available, SQLite ** will pick the one that involves the least amount of data conversion. -** If there is only a single implementation which does not care what -** text encoding is used, then the fourth argument should be -** [SQLITE_ANY]. +** If there is only a single implementation which does not care what text +** encoding is used, then the fourth argument should be [SQLITE_ANY]. ** -** The fifth parameter is an arbitrary pointer. The implementation -** of the function can gain access to this pointer using -** [sqlite3_user_data()]. +** The fifth parameter is an arbitrary pointer. The implementation of the +** function can gain access to this pointer using [sqlite3_user_data()]. ** ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are -** pointers to C-language functions that implement the SQL -** function or aggregate. A scalar SQL function requires an implementation of -** the xFunc callback only, NULL pointers should be passed as the xStep -** and xFinal parameters. An aggregate SQL function requires an implementation -** of xStep and xFinal and NULL should be passed for xFunc. To delete an -** existing SQL function or aggregate, pass NULL for all three function -** callback. +** pointers to C-language functions that implement the SQL function or +** aggregate. A scalar SQL function requires an implementation of the xFunc +** callback only, NULL pointers should be passed as the xStep and xFinal +** parameters. An aggregate SQL function requires an implementation of xStep +** and xFinal and NULL should be passed for xFunc. To delete an existing +** SQL function or aggregate, pass NULL for all three function callbacks. ** ** It is permitted to register multiple implementations of the same ** functions with the same name but with either differing numbers of -** arguments or differing perferred text encodings. SQLite will use +** arguments or differing preferred text encodings. SQLite will use ** the implementation most closely matches the way in which the ** SQL function is used. ** ** INVARIANTS: ** -** {F16103} The [sqlite3_create_function16()] interface behaves exactly +** {H16103} The [sqlite3_create_function16()] interface behaves exactly ** like [sqlite3_create_function()] in every way except that it -** interprets the zFunctionName argument as -** zero-terminated UTF-16 native byte order instead of as a -** zero-terminated UTF-8. +** interprets the zFunctionName argument as zero-terminated UTF-16 +** native byte order instead of as zero-terminated UTF-8. ** -** {F16106} A successful invocation of +** {H16106} A successful invocation of ** the [sqlite3_create_function(D,X,N,E,...)] interface registers -** or replaces callback functions in [database connection] D +** or replaces callback functions in the [database connection] D ** used to implement the SQL function named X with N parameters -** and having a perferred text encoding of E. +** and having a preferred text encoding of E. ** -** {F16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)] +** {H16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)] ** replaces the P, F, S, and L values from any prior calls with ** the same D, X, N, and E values. ** -** {F16112} The [sqlite3_create_function(D,X,...)] interface fails with +** {H16112} The [sqlite3_create_function(D,X,...)] interface fails with ** a return code of [SQLITE_ERROR] if the SQL function name X is ** longer than 255 bytes exclusive of the zero terminator. ** -** {F16118} Either F must be NULL and S and L are non-NULL or else F +** {H16118} Either F must be NULL and S and L are non-NULL or else F ** is non-NULL and S and L are NULL, otherwise ** [sqlite3_create_function(D,X,N,E,P,F,S,L)] returns [SQLITE_ERROR]. ** -** {F16121} The [sqlite3_create_function(D,...)] interface fails with an +** {H16121} The [sqlite3_create_function(D,...)] interface fails with an ** error code of [SQLITE_BUSY] if there exist [prepared statements] ** associated with the [database connection] D. ** -** {F16124} The [sqlite3_create_function(D,X,N,...)] interface fails with an +** {H16124} The [sqlite3_create_function(D,X,N,...)] interface fails with an ** error code of [SQLITE_ERROR] if parameter N (specifying the number ** of arguments to the SQL function being registered) is less ** than -1 or greater than 127. ** -** {F16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)] +** {H16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)] ** interface causes callbacks to be invoked for the SQL function ** named X when the number of arguments to the SQL function is ** exactly N. ** -** {F16130} When N is -1, the [sqlite3_create_function(D,X,N,...)] +** {H16130} When N is -1, the [sqlite3_create_function(D,X,N,...)] ** interface causes callbacks to be invoked for the SQL function ** named X with any number of arguments. ** -** {F16133} When calls to [sqlite3_create_function(D,X,N,...)] +** {H16133} When calls to [sqlite3_create_function(D,X,N,...)] ** specify multiple implementations of the same function X ** and when one implementation has N>=0 and the other has N=(-1) ** the implementation with a non-zero N is preferred. ** -** {F16136} When calls to [sqlite3_create_function(D,X,N,E,...)] +** {H16136} When calls to [sqlite3_create_function(D,X,N,E,...)] ** specify multiple implementations of the same function X with ** the same number of arguments N but with different ** encodings E, then the implementation where E matches the ** database encoding is preferred. ** -** {F16139} For an aggregate SQL function created using -** [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finializer +** {H16139} For an aggregate SQL function created using +** [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finalizer ** function L will always be invoked exactly once if the ** step function S is called one or more times. ** -** {F16142} When SQLite invokes either the xFunc or xStep function of +** {H16142} When SQLite invokes either the xFunc or xStep function of ** an application-defined SQL function or aggregate created ** by [sqlite3_create_function()] or [sqlite3_create_function16()], ** then the array of [sqlite3_value] objects passed as the @@ -3969,7 +4369,7 @@ SQLITE_API int sqlite3_create_function16( ); /* -** CAPI3REF: Text Encodings {F10267} +** CAPI3REF: Text Encodings {H10267} <S50200> <H16100> ** ** These constant define integer codes that represent the various ** text encodings supported by SQLite. @@ -3982,11 +4382,12 @@ SQLITE_API int sqlite3_create_function16( #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ /* -** CAPI3REF: Obsolete Functions +** CAPI3REF: Deprecated Functions +** DEPRECATED ** -** These functions are all now obsolete. In order to maintain -** backwards compatibility with older code, we continue to support -** these functions. However, new development projects should avoid +** These functions are [deprecated]. In order to maintain +** backwards compatibility with older code, these functions continue +** to be supported. However, new applications should avoid ** the use of these functions. To help encourage people to avoid ** using these functions, we are not going to tell you want they do. */ @@ -3998,7 +4399,7 @@ SQLITE_API void sqlite3_thread_cleanup(void); SQLITE_API int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64); /* -** CAPI3REF: Obtaining SQL Function Parameter Values {F15100} +** CAPI3REF: Obtaining SQL Function Parameter Values {H15100} <S20200> ** ** The C-language implementation of SQL functions and aggregates uses ** this set of interface routines to access the parameter values on @@ -4016,95 +4417,93 @@ SQLITE_API int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlit ** Any attempt to use these routines on an [unprotected sqlite3_value] ** object results in undefined behavior. ** -** These routines work just like the corresponding -** [sqlite3_column_blob | sqlite3_column_* routines] except that -** these routines take a single [protected sqlite3_value] object pointer -** instead of an [sqlite3_stmt*] pointer and an integer column number. +** These routines work just like the corresponding [column access functions] +** except that these routines take a single [protected sqlite3_value] object +** pointer instead of a [sqlite3_stmt*] pointer and an integer column number. ** -** The sqlite3_value_text16() interface extracts a UTF16 string +** The sqlite3_value_text16() interface extracts a UTF-16 string ** in the native byte-order of the host machine. The ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces -** extract UTF16 strings as big-endian and little-endian respectively. +** extract UTF-16 strings as big-endian and little-endian respectively. ** ** The sqlite3_value_numeric_type() interface attempts to apply ** numeric affinity to the value. This means that an attempt is ** made to convert the value to an integer or floating point. If ** such a conversion is possible without loss of information (in other -** words if the value is a string that looks like a number) -** then the conversion is done. Otherwise no conversion occurs. The -** [SQLITE_INTEGER | datatype] after conversion is returned. +** words, if the value is a string that looks like a number) +** then the conversion is performed. Otherwise no conversion occurs. +** The [SQLITE_INTEGER | datatype] after conversion is returned. ** -** Please pay particular attention to the fact that the pointer that -** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or +** Please pay particular attention to the fact that the pointer returned +** from [sqlite3_value_blob()], [sqlite3_value_text()], or ** [sqlite3_value_text16()] can be invalidated by a subsequent call to ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], -** or [sqlite3_value_text16()]. +** or [sqlite3_value_text16()]. ** ** These routines must be called from the same thread as ** the SQL function that supplied the [sqlite3_value*] parameters. ** -** ** INVARIANTS: ** -** {F15103} The [sqlite3_value_blob(V)] interface converts the -** [protected sqlite3_value] object V into a blob and then returns a -** pointer to the converted value. +** {H15103} The [sqlite3_value_blob(V)] interface converts the +** [protected sqlite3_value] object V into a BLOB and then +** returns a pointer to the converted value. ** -** {F15106} The [sqlite3_value_bytes(V)] interface returns the -** number of bytes in the blob or string (exclusive of the +** {H15106} The [sqlite3_value_bytes(V)] interface returns the +** number of bytes in the BLOB or string (exclusive of the ** zero terminator on the string) that was returned by the ** most recent call to [sqlite3_value_blob(V)] or ** [sqlite3_value_text(V)]. ** -** {F15109} The [sqlite3_value_bytes16(V)] interface returns the +** {H15109} The [sqlite3_value_bytes16(V)] interface returns the ** number of bytes in the string (exclusive of the ** zero terminator on the string) that was returned by the ** most recent call to [sqlite3_value_text16(V)], ** [sqlite3_value_text16be(V)], or [sqlite3_value_text16le(V)]. ** -** {F15112} The [sqlite3_value_double(V)] interface converts the +** {H15112} The [sqlite3_value_double(V)] interface converts the ** [protected sqlite3_value] object V into a floating point value and ** returns a copy of that value. ** -** {F15115} The [sqlite3_value_int(V)] interface converts the +** {H15115} The [sqlite3_value_int(V)] interface converts the ** [protected sqlite3_value] object V into a 64-bit signed integer and ** returns the lower 32 bits of that integer. ** -** {F15118} The [sqlite3_value_int64(V)] interface converts the +** {H15118} The [sqlite3_value_int64(V)] interface converts the ** [protected sqlite3_value] object V into a 64-bit signed integer and ** returns a copy of that integer. ** -** {F15121} The [sqlite3_value_text(V)] interface converts the -** [protected sqlite3_value] object V into a zero-terminated UTF-8 +** {H15121} The [sqlite3_value_text(V)] interface converts the +** [protected sqlite3_value] object V into a zero-terminated UTF-8 ** string and returns a pointer to that string. ** -** {F15124} The [sqlite3_value_text16(V)] interface converts the +** {H15124} The [sqlite3_value_text16(V)] interface converts the ** [protected sqlite3_value] object V into a zero-terminated 2-byte ** aligned UTF-16 native byte order ** string and returns a pointer to that string. ** -** {F15127} The [sqlite3_value_text16be(V)] interface converts the +** {H15127} The [sqlite3_value_text16be(V)] interface converts the ** [protected sqlite3_value] object V into a zero-terminated 2-byte ** aligned UTF-16 big-endian ** string and returns a pointer to that string. ** -** {F15130} The [sqlite3_value_text16le(V)] interface converts the +** {H15130} The [sqlite3_value_text16le(V)] interface converts the ** [protected sqlite3_value] object V into a zero-terminated 2-byte ** aligned UTF-16 little-endian ** string and returns a pointer to that string. ** -** {F15133} The [sqlite3_value_type(V)] interface returns +** {H15133} The [sqlite3_value_type(V)] interface returns ** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT], ** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for ** the [sqlite3_value] object V. ** -** {F15136} The [sqlite3_value_numeric_type(V)] interface converts +** {H15136} The [sqlite3_value_numeric_type(V)] interface converts ** the [protected sqlite3_value] object V into either an integer or ** a floating point value if it can do so without loss of ** information, and returns one of [SQLITE_NULL], ** [SQLITE_INTEGER], [SQLITE_FLOAT], [SQLITE_TEXT], or -** [SQLITE_BLOB] as appropriate for -** the [protected sqlite3_value] object V after the conversion attempt. +** [SQLITE_BLOB] as appropriate for the +** [protected sqlite3_value] object V after the conversion attempt. */ SQLITE_API const void *sqlite3_value_blob(sqlite3_value*); SQLITE_API int sqlite3_value_bytes(sqlite3_value*); @@ -4120,46 +4519,44 @@ SQLITE_API int sqlite3_value_type(sqlite3_value*); SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*); /* -** CAPI3REF: Obtain Aggregate Function Context {F16210} +** CAPI3REF: Obtain Aggregate Function Context {H16210} <S20200> ** ** The implementation of aggregate SQL functions use this routine to allocate -** a structure for storing their state. -** The first time the sqlite3_aggregate_context() routine is -** is called for a particular aggregate, SQLite allocates nBytes of memory -** zeros that memory, and returns a pointer to it. -** On second and subsequent calls to sqlite3_aggregate_context() -** for the same aggregate function index, the same buffer is returned. -** The implementation -** of the aggregate can use the returned buffer to accumulate data. +** a structure for storing their state. +** +** The first time the sqlite3_aggregate_context() routine is called for a +** particular aggregate, SQLite allocates nBytes of memory, zeroes out that +** memory, and returns a pointer to it. On second and subsequent calls to +** sqlite3_aggregate_context() for the same aggregate function index, +** the same buffer is returned. The implementation of the aggregate can use +** the returned buffer to accumulate data. ** ** SQLite automatically frees the allocated buffer when the aggregate ** query concludes. ** -** The first parameter should be a copy of the -** [sqlite3_context | SQL function context] that is the first -** parameter to the callback routine that implements the aggregate -** function. +** The first parameter should be a copy of the +** [sqlite3_context | SQL function context] that is the first parameter +** to the callback routine that implements the aggregate function. ** ** This routine must be called from the same thread in which ** the aggregate SQL function is running. ** ** INVARIANTS: ** -** {F16211} The first invocation of [sqlite3_aggregate_context(C,N)] for +** {H16211} The first invocation of [sqlite3_aggregate_context(C,N)] for ** a particular instance of an aggregate function (for a particular -** context C) causes SQLite to allocation N bytes of memory, -** zero that memory, and return a pointer to the allocationed -** memory. +** context C) causes SQLite to allocate N bytes of memory, +** zero that memory, and return a pointer to the allocated memory. ** -** {F16213} If a memory allocation error occurs during +** {H16213} If a memory allocation error occurs during ** [sqlite3_aggregate_context(C,N)] then the function returns 0. ** -** {F16215} Second and subsequent invocations of +** {H16215} Second and subsequent invocations of ** [sqlite3_aggregate_context(C,N)] for the same context pointer C ** ignore the N parameter and return a pointer to the same ** block of memory returned by the first invocation. ** -** {F16217} The memory allocated by [sqlite3_aggregate_context(C,N)] is +** {H16217} The memory allocated by [sqlite3_aggregate_context(C,N)] is ** automatically freed on the next call to [sqlite3_reset()] ** or [sqlite3_finalize()] for the [prepared statement] containing ** the aggregate function associated with context C. @@ -4167,11 +4564,11 @@ SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*); SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); /* -** CAPI3REF: User Data For Functions {F16240} +** CAPI3REF: User Data For Functions {H16240} <S20200> ** ** The sqlite3_user_data() interface returns a copy of ** the pointer that was the pUserData parameter (the 5th parameter) -** of the the [sqlite3_create_function()] +** of the [sqlite3_create_function()] ** and [sqlite3_create_function16()] routines that originally ** registered the application defined function. {END} ** @@ -4180,71 +4577,67 @@ SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); ** ** INVARIANTS: ** -** {F16243} The [sqlite3_user_data(C)] interface returns a copy of the +** {H16243} The [sqlite3_user_data(C)] interface returns a copy of the ** P pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)] ** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that -** registered the SQL function associated with -** [sqlite3_context] C. +** registered the SQL function associated with [sqlite3_context] C. */ SQLITE_API void *sqlite3_user_data(sqlite3_context*); /* -** CAPI3REF: Database Connection For Functions {F16250} +** CAPI3REF: Database Connection For Functions {H16250} <S60600><S20200> ** ** The sqlite3_context_db_handle() interface returns a copy of ** the pointer to the [database connection] (the 1st parameter) -** of the the [sqlite3_create_function()] +** of the [sqlite3_create_function()] ** and [sqlite3_create_function16()] routines that originally ** registered the application defined function. ** ** INVARIANTS: ** -** {F16253} The [sqlite3_context_db_handle(C)] interface returns a copy of the +** {H16253} The [sqlite3_context_db_handle(C)] interface returns a copy of the ** D pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)] ** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that -** registered the SQL function associated with -** [sqlite3_context] C. +** registered the SQL function associated with [sqlite3_context] C. */ SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*); /* -** CAPI3REF: Function Auxiliary Data {F16270} +** CAPI3REF: Function Auxiliary Data {H16270} <S20200> ** ** The following two functions may be used by scalar SQL functions to -** associate meta-data with argument values. If the same value is passed to +** associate metadata with argument values. If the same value is passed to ** multiple invocations of the same SQL function during query execution, under -** some circumstances the associated meta-data may be preserved. This may +** some circumstances the associated metadata may be preserved. This may ** be used, for example, to add a regular-expression matching scalar ** function. The compiled version of the regular expression is stored as -** meta-data associated with the SQL value passed as the regular expression +** metadata associated with the SQL value passed as the regular expression ** pattern. The compiled regular expression can be reused on multiple ** invocations of the same function so that the original pattern string ** does not need to be recompiled on each invocation. ** -** The sqlite3_get_auxdata() interface returns a pointer to the meta-data +** The sqlite3_get_auxdata() interface returns a pointer to the metadata ** associated by the sqlite3_set_auxdata() function with the Nth argument -** value to the application-defined function. -** If no meta-data has been ever been set for the Nth -** argument of the function, or if the cooresponding function parameter -** has changed since the meta-data was set, then sqlite3_get_auxdata() -** returns a NULL pointer. -** -** The sqlite3_set_auxdata() interface saves the meta-data -** pointed to by its 3rd parameter as the meta-data for the N-th +** value to the application-defined function. If no metadata has been ever +** been set for the Nth argument of the function, or if the corresponding +** function parameter has changed since the meta-data was set, +** then sqlite3_get_auxdata() returns a NULL pointer. +** +** The sqlite3_set_auxdata() interface saves the metadata +** pointed to by its 3rd parameter as the metadata for the N-th ** argument of the application-defined function. Subsequent ** calls to sqlite3_get_auxdata() might return this data, if it has -** not been destroyed. -** If it is not NULL, SQLite will invoke the destructor +** not been destroyed. +** If it is not NULL, SQLite will invoke the destructor ** function given by the 4th parameter to sqlite3_set_auxdata() on -** the meta-data when the corresponding function parameter changes +** the metadata when the corresponding function parameter changes ** or when the SQL statement completes, whichever comes first. ** -** SQLite is free to call the destructor and drop meta-data on -** any parameter of any function at any time. The only guarantee -** is that the destructor will be called before the metadata is -** dropped. +** SQLite is free to call the destructor and drop metadata on any +** parameter of any function at any time. The only guarantee is that +** the destructor will be called before the metadata is dropped. ** -** In practice, meta-data is preserved between function calls for +** In practice, metadata is preserved between function calls for ** expressions that are constant at compile time. This includes literal ** values and SQL variables. ** @@ -4253,28 +4646,27 @@ SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*); ** ** INVARIANTS: ** -** {F16272} The [sqlite3_get_auxdata(C,N)] interface returns a pointer +** {H16272} The [sqlite3_get_auxdata(C,N)] interface returns a pointer ** to metadata associated with the Nth parameter of the SQL function ** whose context is C, or NULL if there is no metadata associated ** with that parameter. ** -** {F16274} The [sqlite3_set_auxdata(C,N,P,D)] interface assigns a metadata -** pointer P to the Nth parameter of the SQL function with context -** C. +** {H16274} The [sqlite3_set_auxdata(C,N,P,D)] interface assigns a metadata +** pointer P to the Nth parameter of the SQL function with context C. ** -** {F16276} SQLite will invoke the destructor D with a single argument +** {H16276} SQLite will invoke the destructor D with a single argument ** which is the metadata pointer P following a call to ** [sqlite3_set_auxdata(C,N,P,D)] when SQLite ceases to hold ** the metadata. ** -** {F16277} SQLite ceases to hold metadata for an SQL function parameter +** {H16277} SQLite ceases to hold metadata for an SQL function parameter ** when the value of that parameter changes. ** -** {F16278} When [sqlite3_set_auxdata(C,N,P,D)] is invoked, the destructor +** {H16278} When [sqlite3_set_auxdata(C,N,P,D)] is invoked, the destructor ** is called for any prior metadata associated with the same function ** context C and parameter N. ** -** {F16279} SQLite will call destructors for any metadata it is holding +** {H16279} SQLite will call destructors for any metadata it is holding ** in a particular [prepared statement] S when either ** [sqlite3_reset(S)] or [sqlite3_finalize(S)] is called. */ @@ -4283,12 +4675,12 @@ SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(voi /* -** CAPI3REF: Constants Defining Special Destructor Behavior {F10280} +** CAPI3REF: Constants Defining Special Destructor Behavior {H10280} <S30100> ** -** These are special value for the destructor that is passed in as the +** These are special values for the destructor that is passed in as the ** final argument to routines like [sqlite3_result_blob()]. If the destructor ** argument is SQLITE_STATIC, it means that the content pointer is constant -** and will never change. It does not need to be destroyed. The +** and will never change. It does not need to be destroyed. The ** SQLITE_TRANSIENT value means that the content will likely change in ** the near future and that SQLite should make its own private copy of ** the content before returning. @@ -4301,30 +4693,28 @@ typedef void (*sqlite3_destructor_type)(void*); #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) /* -** CAPI3REF: Setting The Result Of An SQL Function {F16400} +** CAPI3REF: Setting The Result Of An SQL Function {H16400} <S20200> ** ** These routines are used by the xFunc or xFinal callbacks that ** implement SQL functions and aggregates. See ** [sqlite3_create_function()] and [sqlite3_create_function16()] ** for additional information. ** -** These functions work very much like the -** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used -** to bind values to host parameters in prepared statements. -** Refer to the -** [sqlite3_bind_blob | sqlite3_bind_* documentation] for -** additional information. +** These functions work very much like the [parameter binding] family of +** functions used to bind values to host parameters in prepared statements. +** Refer to the [SQL parameter] documentation for additional information. ** ** The sqlite3_result_blob() interface sets the result from -** an application defined function to be the BLOB whose content is pointed +** an application-defined function to be the BLOB whose content is pointed ** to by the second parameter and which is N bytes long where N is the -** third parameter. -** The sqlite3_result_zeroblob() inerfaces set the result of -** the application defined function to be a BLOB containing all zero +** third parameter. +** +** The sqlite3_result_zeroblob() interfaces set the result of +** the application-defined function to be a BLOB containing all zero ** bytes and N bytes in size, where N is the value of the 2nd parameter. ** ** The sqlite3_result_double() interface sets the result from -** an application defined function to be a floating point value specified +** an application-defined function to be a floating point value specified ** by its 2nd argument. ** ** The sqlite3_result_error() and sqlite3_result_error16() functions @@ -4332,8 +4722,8 @@ typedef void (*sqlite3_destructor_type)(void*); ** SQLite uses the string pointed to by the ** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16() ** as the text of an error message. SQLite interprets the error -** message string from sqlite3_result_error() as UTF8. SQLite -** interprets the string from sqlite3_result_error16() as UTF16 in native +** message string from sqlite3_result_error() as UTF-8. SQLite +** interprets the string from sqlite3_result_error16() as UTF-16 in native ** byte order. If the third parameter to sqlite3_result_error() ** or sqlite3_result_error16() is negative then SQLite takes as the error ** message all text up through the first zero character. @@ -4341,7 +4731,7 @@ typedef void (*sqlite3_destructor_type)(void*); ** sqlite3_result_error16() is non-negative then SQLite takes that many ** bytes (not characters) from the 2nd parameter as the error message. ** The sqlite3_result_error() and sqlite3_result_error16() -** routines make a copy private copy of the error message text before +** routines make a private copy of the error message text before ** they return. Hence, the calling function can deallocate or ** modify the text after they return without harm. ** The sqlite3_result_error_code() function changes the error code @@ -4349,11 +4739,11 @@ typedef void (*sqlite3_destructor_type)(void*); ** the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error() ** or sqlite3_result_error16() resets the error code to SQLITE_ERROR. ** -** The sqlite3_result_toobig() interface causes SQLite -** to throw an error indicating that a string or BLOB is to long -** to represent. The sqlite3_result_nomem() interface -** causes SQLite to throw an exception indicating that the a -** memory allocation failed. +** The sqlite3_result_toobig() interface causes SQLite to throw an error +** indicating that a string or BLOB is to long to represent. +** +** The sqlite3_result_nomem() interface causes SQLite to throw an error +** indicating that a memory allocation failed. ** ** The sqlite3_result_int() interface sets the return value ** of the application-defined function to be the 32-bit signed integer @@ -4365,7 +4755,7 @@ typedef void (*sqlite3_destructor_type)(void*); ** The sqlite3_result_null() interface sets the return value ** of the application-defined function to be NULL. ** -** The sqlite3_result_text(), sqlite3_result_text16(), +** The sqlite3_result_text(), sqlite3_result_text16(), ** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces ** set the return value of the application-defined function to be ** a text string which is represented as UTF-8, UTF-16 native byte order, @@ -4373,7 +4763,7 @@ typedef void (*sqlite3_destructor_type)(void*); ** SQLite takes the text result from the application from ** the 2nd parameter of the sqlite3_result_text* interfaces. ** If the 3rd parameter to the sqlite3_result_text* interfaces -** is negative, then SQLite takes result text from the 2nd parameter +** is negative, then SQLite takes result text from the 2nd parameter ** through the first zero character. ** If the 3rd parameter to the sqlite3_result_text* interfaces ** is non-negative, then as many bytes (not characters) of the text @@ -4381,13 +4771,12 @@ typedef void (*sqlite3_destructor_type)(void*); ** function result. ** If the 4th parameter to the sqlite3_result_text* interfaces ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that -** function as the destructor on the text or blob result when it has -** finished using that result. -** If the 4th parameter to the sqlite3_result_text* interfaces -** or sqlite3_result_blob is the special constant SQLITE_STATIC, then -** SQLite assumes that the text or blob result is constant space and -** does not copy the space or call a destructor when it has +** function as the destructor on the text or BLOB result when it has ** finished using that result. +** If the 4th parameter to the sqlite3_result_text* interfaces or +** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite +** assumes that the text or BLOB result is in constant space and does not +** copy the it or call a destructor when it has finished using that result. ** If the 4th parameter to the sqlite3_result_text* interfaces ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT ** then SQLite makes a copy of the result into space obtained from @@ -4397,109 +4786,109 @@ typedef void (*sqlite3_destructor_type)(void*); ** the application-defined function to be a copy the ** [unprotected sqlite3_value] object specified by the 2nd parameter. The ** sqlite3_result_value() interface makes a copy of the [sqlite3_value] -** so that [sqlite3_value] specified in the parameter may change or +** so that the [sqlite3_value] specified in the parameter may change or ** be deallocated after sqlite3_result_value() returns without harm. ** A [protected sqlite3_value] object may always be used where an ** [unprotected sqlite3_value] object is required, so either ** kind of [sqlite3_value] object can be used with this interface. ** -** If these routines are called from within the different thread -** than the one containing the application-defined function that recieved +** If these routines are called from within the different thread +** than the one containing the application-defined function that received ** the [sqlite3_context] pointer, the results are undefined. ** ** INVARIANTS: ** -** {F16403} The default return value from any SQL function is NULL. +** {H16403} The default return value from any SQL function is NULL. ** -** {F16406} The [sqlite3_result_blob(C,V,N,D)] interface changes the -** return value of function C to be a blob that is N bytes +** {H16406} The [sqlite3_result_blob(C,V,N,D)] interface changes the +** return value of function C to be a BLOB that is N bytes ** in length and with content pointed to by V. ** -** {F16409} The [sqlite3_result_double(C,V)] interface changes the +** {H16409} The [sqlite3_result_double(C,V)] interface changes the ** return value of function C to be the floating point value V. ** -** {F16412} The [sqlite3_result_error(C,V,N)] interface changes the return +** {H16412} The [sqlite3_result_error(C,V,N)] interface changes the return ** value of function C to be an exception with error code -** [SQLITE_ERROR] and a UTF8 error message copied from V up to the +** [SQLITE_ERROR] and a UTF-8 error message copied from V up to the ** first zero byte or until N bytes are read if N is positive. ** -** {F16415} The [sqlite3_result_error16(C,V,N)] interface changes the return +** {H16415} The [sqlite3_result_error16(C,V,N)] interface changes the return ** value of function C to be an exception with error code -** [SQLITE_ERROR] and a UTF16 native byte order error message +** [SQLITE_ERROR] and a UTF-16 native byte order error message ** copied from V up to the first zero terminator or until N bytes ** are read if N is positive. ** -** {F16418} The [sqlite3_result_error_toobig(C)] interface changes the return +** {H16418} The [sqlite3_result_error_toobig(C)] interface changes the return ** value of the function C to be an exception with error code ** [SQLITE_TOOBIG] and an appropriate error message. ** -** {F16421} The [sqlite3_result_error_nomem(C)] interface changes the return +** {H16421} The [sqlite3_result_error_nomem(C)] interface changes the return ** value of the function C to be an exception with error code ** [SQLITE_NOMEM] and an appropriate error message. ** -** {F16424} The [sqlite3_result_error_code(C,E)] interface changes the return +** {H16424} The [sqlite3_result_error_code(C,E)] interface changes the return ** value of the function C to be an exception with error code E. ** The error message text is unchanged. ** -** {F16427} The [sqlite3_result_int(C,V)] interface changes the +** {H16427} The [sqlite3_result_int(C,V)] interface changes the ** return value of function C to be the 32-bit integer value V. ** -** {F16430} The [sqlite3_result_int64(C,V)] interface changes the +** {H16430} The [sqlite3_result_int64(C,V)] interface changes the ** return value of function C to be the 64-bit integer value V. ** -** {F16433} The [sqlite3_result_null(C)] interface changes the +** {H16433} The [sqlite3_result_null(C)] interface changes the ** return value of function C to be NULL. ** -** {F16436} The [sqlite3_result_text(C,V,N,D)] interface changes the -** return value of function C to be the UTF8 string +** {H16436} The [sqlite3_result_text(C,V,N,D)] interface changes the +** return value of function C to be the UTF-8 string ** V up to the first zero if N is negative ** or the first N bytes of V if N is non-negative. ** -** {F16439} The [sqlite3_result_text16(C,V,N,D)] interface changes the -** return value of function C to be the UTF16 native byte order -** string V up to the first zero if N is -** negative or the first N bytes of V if N is non-negative. +** {H16439} The [sqlite3_result_text16(C,V,N,D)] interface changes the +** return value of function C to be the UTF-16 native byte order +** string V up to the first zero if N is negative +** or the first N bytes of V if N is non-negative. ** -** {F16442} The [sqlite3_result_text16be(C,V,N,D)] interface changes the -** return value of function C to be the UTF16 big-endian -** string V up to the first zero if N is -** is negative or the first N bytes or V if N is non-negative. +** {H16442} The [sqlite3_result_text16be(C,V,N,D)] interface changes the +** return value of function C to be the UTF-16 big-endian +** string V up to the first zero if N is negative +** or the first N bytes or V if N is non-negative. ** -** {F16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the -** return value of function C to be the UTF16 little-endian -** string V up to the first zero if N is -** negative or the first N bytes of V if N is non-negative. +** {H16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the +** return value of function C to be the UTF-16 little-endian +** string V up to the first zero if N is negative +** or the first N bytes of V if N is non-negative. ** -** {F16448} The [sqlite3_result_value(C,V)] interface changes the -** return value of function C to be [unprotected sqlite3_value] +** {H16448} The [sqlite3_result_value(C,V)] interface changes the +** return value of function C to be the [unprotected sqlite3_value] ** object V. ** -** {F16451} The [sqlite3_result_zeroblob(C,N)] interface changes the -** return value of function C to be an N-byte blob of all zeros. +** {H16451} The [sqlite3_result_zeroblob(C,N)] interface changes the +** return value of function C to be an N-byte BLOB of all zeros. ** -** {F16454} The [sqlite3_result_error()] and [sqlite3_result_error16()] +** {H16454} The [sqlite3_result_error()] and [sqlite3_result_error16()] ** interfaces make a copy of their error message strings before ** returning. ** -** {F16457} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], +** {H16457} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)], ** [sqlite3_result_text16be(C,V,N,D)], or ** [sqlite3_result_text16le(C,V,N,D)] is the constant [SQLITE_STATIC] ** then no destructor is ever called on the pointer V and SQLite ** assumes that V is immutable. ** -** {F16460} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], +** {H16460} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)], ** [sqlite3_result_text16be(C,V,N,D)], or ** [sqlite3_result_text16le(C,V,N,D)] is the constant ** [SQLITE_TRANSIENT] then the interfaces makes a copy of the ** content of V and retains the copy. ** -** {F16463} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], +** {H16463} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)], ** [sqlite3_result_text16be(C,V,N,D)], or ** [sqlite3_result_text16le(C,V,N,D)] is some value other than -** the constants [SQLITE_STATIC] and [SQLITE_TRANSIENT] then +** the constants [SQLITE_STATIC] and [SQLITE_TRANSIENT] then ** SQLite will invoke the destructor D with V as its only argument ** when it has finished with the V value. */ @@ -4521,10 +4910,10 @@ SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*); SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n); /* -** CAPI3REF: Define New Collating Sequences {F16600} +** CAPI3REF: Define New Collating Sequences {H16600} <S20300> ** ** These functions are used to add new collation sequences to the -** [sqlite3*] handle specified as the first argument. +** [database connection] specified as the first argument. ** ** The name of the new collation sequence is specified as a UTF-8 string ** for sqlite3_create_collation() and sqlite3_create_collation_v2() @@ -4534,81 +4923,79 @@ SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n); ** The third argument may be one of the constants [SQLITE_UTF8], ** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied ** routine expects to be passed pointers to strings encoded using UTF-8, -** UTF-16 little-endian or UTF-16 big-endian respectively. The +** UTF-16 little-endian, or UTF-16 big-endian, respectively. The ** third argument might also be [SQLITE_UTF16_ALIGNED] to indicate that ** the routine expects pointers to 16-bit word aligned strings -** of UTF16 in the native byte order of the host computer. +** of UTF-16 in the native byte order of the host computer. ** ** A pointer to the user supplied routine must be passed as the fifth ** argument. If it is NULL, this is the same as deleting the collation ** sequence (so that SQLite cannot call it anymore). -** Each time the application -** supplied function is invoked, it is passed a copy of the void* passed as -** the fourth argument to sqlite3_create_collation() or -** sqlite3_create_collation16() as its first parameter. +** Each time the application supplied function is invoked, it is passed +** as its first parameter a copy of the void* passed as the fourth argument +** to sqlite3_create_collation() or sqlite3_create_collation16(). ** ** The remaining arguments to the application-supplied routine are two strings, ** each represented by a (length, data) pair and encoded in the encoding ** that was passed as the third argument when the collation sequence was -** registered. {END} The application defined collation routine should -** return negative, zero or positive if -** the first string is less than, equal to, or greater than the second -** string. i.e. (STRING1 - STRING2). +** registered. {END} The application defined collation routine should +** return negative, zero or positive if the first string is less than, +** equal to, or greater than the second string. i.e. (STRING1 - STRING2). ** ** The sqlite3_create_collation_v2() works like sqlite3_create_collation() -** excapt that it takes an extra argument which is a destructor for +** except that it takes an extra argument which is a destructor for ** the collation. The destructor is called when the collation is ** destroyed and is passed a copy of the fourth parameter void* pointer ** of the sqlite3_create_collation_v2(). -** Collations are destroyed when -** they are overridden by later calls to the collation creation functions -** or when the [sqlite3*] database handle is closed using [sqlite3_close()]. +** Collations are destroyed when they are overridden by later calls to the +** collation creation functions or when the [database connection] is closed +** using [sqlite3_close()]. ** ** INVARIANTS: ** -** {F16603} A successful call to the +** {H16603} A successful call to the ** [sqlite3_create_collation_v2(B,X,E,P,F,D)] interface ** registers function F as the comparison function used to -** implement collation X on [database connection] B for +** implement collation X on the [database connection] B for ** databases having encoding E. ** -** {F16604} SQLite understands the X parameter to +** {H16604} SQLite understands the X parameter to ** [sqlite3_create_collation_v2(B,X,E,P,F,D)] as a zero-terminated ** UTF-8 string in which case is ignored for ASCII characters and ** is significant for non-ASCII characters. ** -** {F16606} Successive calls to [sqlite3_create_collation_v2(B,X,E,P,F,D)] +** {H16606} Successive calls to [sqlite3_create_collation_v2(B,X,E,P,F,D)] ** with the same values for B, X, and E, override prior values ** of P, F, and D. ** -** {F16609} The destructor D in [sqlite3_create_collation_v2(B,X,E,P,F,D)] +** {H16609} If the destructor D in [sqlite3_create_collation_v2(B,X,E,P,F,D)] ** is not NULL then it is called with argument P when the ** collating function is dropped by SQLite. ** -** {F16612} A collating function is dropped when it is overloaded. +** {H16612} A collating function is dropped when it is overloaded. ** -** {F16615} A collating function is dropped when the database connection +** {H16615} A collating function is dropped when the database connection ** is closed using [sqlite3_close()]. ** -** {F16618} The pointer P in [sqlite3_create_collation_v2(B,X,E,P,F,D)] +** {H16618} The pointer P in [sqlite3_create_collation_v2(B,X,E,P,F,D)] ** is passed through as the first parameter to the comparison ** function F for all subsequent invocations of F. ** -** {F16621} A call to [sqlite3_create_collation(B,X,E,P,F)] is exactly +** {H16621} A call to [sqlite3_create_collation(B,X,E,P,F)] is exactly ** the same as a call to [sqlite3_create_collation_v2()] with ** the same parameters and a NULL destructor. ** -** {F16624} Following a [sqlite3_create_collation_v2(B,X,E,P,F,D)], +** {H16624} Following a [sqlite3_create_collation_v2(B,X,E,P,F,D)], ** SQLite uses the comparison function F for all text comparison -** operations on [database connection] B on text values that -** use the collating sequence name X. +** operations on the [database connection] B on text values that +** use the collating sequence named X. ** -** {F16627} The [sqlite3_create_collation16(B,X,E,P,F)] works the same +** {H16627} The [sqlite3_create_collation16(B,X,E,P,F)] works the same ** as [sqlite3_create_collation(B,X,E,P,F)] except that the ** collation name X is understood as UTF-16 in native byte order ** instead of UTF-8. ** -** {F16630} When multiple comparison functions are available for the same +** {H16630} When multiple comparison functions are available for the same ** collating sequence, SQLite chooses the one whose text encoding ** requires the least amount of conversion from the default ** text encoding of the database. @@ -4630,33 +5017,32 @@ SQLITE_API int sqlite3_create_collation_v2( ); SQLITE_API int sqlite3_create_collation16( sqlite3*, - const char *zName, + const void *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*) ); /* -** CAPI3REF: Collation Needed Callbacks {F16700} +** CAPI3REF: Collation Needed Callbacks {H16700} <S20300> ** ** To avoid having to register all collation sequences before a database ** can be used, a single callback function may be registered with the -** database handle to be called whenever an undefined collation sequence is -** required. +** [database connection] to be called whenever an undefined collation +** sequence is required. ** ** If the function is registered using the sqlite3_collation_needed() API, ** then it is passed the names of undefined collation sequences as strings -** encoded in UTF-8. {F16703} If sqlite3_collation_needed16() is used, the names -** are passed as UTF-16 in machine native byte order. A call to either -** function replaces any existing callback. +** encoded in UTF-8. {H16703} If sqlite3_collation_needed16() is used, +** the names are passed as UTF-16 in machine native byte order. +** A call to either function replaces any existing callback. ** ** When the callback is invoked, the first argument passed is a copy ** of the second argument to sqlite3_collation_needed() or ** sqlite3_collation_needed16(). The second argument is the database -** handle. The third argument is one of [SQLITE_UTF8], -** [SQLITE_UTF16BE], or [SQLITE_UTF16LE], indicating the most -** desirable form of the collation sequence function required. -** The fourth parameter is the name of the +** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], +** or [SQLITE_UTF16LE], indicating the most desirable form of the collation +** sequence function required. The fourth parameter is the name of the ** required collation sequence. ** ** The callback function should register the desired collation using @@ -4665,24 +5051,22 @@ SQLITE_API int sqlite3_create_collation16( ** ** INVARIANTS: ** -** {F16702} A successful call to [sqlite3_collation_needed(D,P,F)] +** {H16702} A successful call to [sqlite3_collation_needed(D,P,F)] ** or [sqlite3_collation_needed16(D,P,F)] causes ** the [database connection] D to invoke callback F with first ** parameter P whenever it needs a comparison function for a ** collating sequence that it does not know about. ** -** {F16704} Each successful call to [sqlite3_collation_needed()] or +** {H16704} Each successful call to [sqlite3_collation_needed()] or ** [sqlite3_collation_needed16()] overrides the callback registered ** on the same [database connection] by prior calls to either ** interface. ** -** {F16706} The name of the requested collating function passed in the +** {H16706} The name of the requested collating function passed in the ** 4th parameter to the callback is in UTF-8 if the callback ** was registered using [sqlite3_collation_needed()] and ** is in UTF-16 native byte order if the callback was ** registered using [sqlite3_collation_needed16()]. -** -** */ SQLITE_API int sqlite3_collation_needed( sqlite3*, @@ -4721,15 +5105,14 @@ SQLITE_API int sqlite3_rekey( ); /* -** CAPI3REF: Suspend Execution For A Short Time {F10530} +** CAPI3REF: Suspend Execution For A Short Time {H10530} <S40410> ** -** The sqlite3_sleep() function -** causes the current thread to suspend execution +** The sqlite3_sleep() function causes the current thread to suspend execution ** for at least a number of milliseconds specified in its parameter. ** -** If the operating system does not support sleep requests with -** millisecond time resolution, then the time will be rounded up to -** the nearest second. The number of milliseconds of sleep actually +** If the operating system does not support sleep requests with +** millisecond time resolution, then the time will be rounded up to +** the nearest second. The number of milliseconds of sleep actually ** requested from the operating system is returned. ** ** SQLite implements this interface by calling the xSleep() @@ -4737,27 +5120,27 @@ SQLITE_API int sqlite3_rekey( ** ** INVARIANTS: ** -** {F10533} The [sqlite3_sleep(M)] interface invokes the xSleep +** {H10533} The [sqlite3_sleep(M)] interface invokes the xSleep ** method of the default [sqlite3_vfs|VFS] in order to ** suspend execution of the current thread for at least ** M milliseconds. ** -** {F10536} The [sqlite3_sleep(M)] interface returns the number of +** {H10536} The [sqlite3_sleep(M)] interface returns the number of ** milliseconds of sleep actually requested of the operating ** system, which might be larger than the parameter M. */ SQLITE_API int sqlite3_sleep(int); /* -** CAPI3REF: Name Of The Folder Holding Temporary Files {F10310} +** CAPI3REF: Name Of The Folder Holding Temporary Files {H10310} <S20000> ** ** If this global variable is made to point to a string which is -** the name of a folder (a.ka. directory), then all temporary files +** the name of a folder (a.k.a. directory), then all temporary files ** created by SQLite will be placed in that directory. If this variable -** is NULL pointer, then SQLite does a search for an appropriate temporary -** file directory. +** is a NULL pointer, then SQLite performs a search for an appropriate +** temporary file directory. ** -** It is not safe to modify this variable once a database connection +** It is not safe to modify this variable once a [database connection] ** has been opened. It is intended that this variable be set once ** as part of process initialization and before any SQLite interface ** routines have been call and remain unchanged thereafter. @@ -4765,65 +5148,99 @@ SQLITE_API int sqlite3_sleep(int); SQLITE_API char *sqlite3_temp_directory; /* -** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode {F12930} +** CAPI3REF: Test For Auto-Commit Mode {H12930} <S60200> +** KEYWORDS: {autocommit mode} ** -** The sqlite3_get_autocommit() interfaces returns non-zero or +** The sqlite3_get_autocommit() interface returns non-zero or ** zero if the given database connection is or is not in autocommit mode, -** respectively. Autocommit mode is on -** by default. Autocommit mode is disabled by a [BEGIN] statement. -** Autocommit mode is reenabled by a [COMMIT] or [ROLLBACK]. +** respectively. Autocommit mode is on by default. +** Autocommit mode is disabled by a [BEGIN] statement. +** Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK]. ** ** If certain kinds of errors occur on a statement within a multi-statement -** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR], +** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR], ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the ** transaction might be rolled back automatically. The only way to -** find out if SQLite automatically rolled back the transaction after +** find out whether SQLite automatically rolled back the transaction after ** an error is to use this function. ** ** INVARIANTS: ** -** {F12931} The [sqlite3_get_autocommit(D)] interface returns non-zero or +** {H12931} The [sqlite3_get_autocommit(D)] interface returns non-zero or ** zero if the [database connection] D is or is not in autocommit ** mode, respectively. ** -** {F12932} Autocommit mode is on by default. +** {H12932} Autocommit mode is on by default. ** -** {F12933} Autocommit mode is disabled by a successful [BEGIN] statement. +** {H12933} Autocommit mode is disabled by a successful [BEGIN] statement. ** -** {F12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK] +** {H12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK] ** statement. -** ** -** LIMITATIONS: -*** -** {U12936} If another thread changes the autocommit status of the database +** ASSUMPTIONS: +** +** {A12936} If another thread changes the autocommit status of the database ** connection while this routine is running, then the return value ** is undefined. */ SQLITE_API int sqlite3_get_autocommit(sqlite3*); /* -** CAPI3REF: Find The Database Handle Of A Prepared Statement {F13120} +** CAPI3REF: Find The Database Handle Of A Prepared Statement {H13120} <S60600> ** -** The sqlite3_db_handle interface -** returns the [sqlite3*] database handle to which a -** [prepared statement] belongs. -** The database handle returned by sqlite3_db_handle -** is the same database handle that was -** the first argument to the [sqlite3_prepare_v2()] or its variants -** that was used to create the statement in the first place. +** The sqlite3_db_handle interface returns the [database connection] handle +** to which a [prepared statement] belongs. The database handle returned by +** sqlite3_db_handle is the same database handle that was the first argument +** to the [sqlite3_prepare_v2()] call (or its variants) that was used to +** create the statement in the first place. ** ** INVARIANTS: ** -** {F13123} The [sqlite3_db_handle(S)] interface returns a pointer -** to the [database connection] associated with +** {H13123} The [sqlite3_db_handle(S)] interface returns a pointer +** to the [database connection] associated with the ** [prepared statement] S. */ SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*); +/* +** CAPI3REF: Find the next prepared statement {H13140} <S60600> +** +** This interface returns a pointer to the next [prepared statement] after +** pStmt associated with the [database connection] pDb. If pStmt is NULL +** then this interface returns a pointer to the first prepared statement +** associated with the database connection pDb. If no prepared statement +** satisfies the conditions of this routine, it returns NULL. +** +** INVARIANTS: +** +** {H13143} If D is a [database connection] that holds one or more +** unfinalized [prepared statements] and S is a NULL pointer, +** then [sqlite3_next_stmt(D, S)] routine shall return a pointer +** to one of the prepared statements associated with D. +** +** {H13146} If D is a [database connection] that holds no unfinalized +** [prepared statements] and S is a NULL pointer, then +** [sqlite3_next_stmt(D, S)] routine shall return a NULL pointer. +** +** {H13149} If S is a [prepared statement] in the [database connection] D +** and S is not the last prepared statement in D, then +** [sqlite3_next_stmt(D, S)] routine shall return a pointer +** to the next prepared statement in D after S. +** +** {H13152} If S is the last [prepared statement] in the +** [database connection] D then the [sqlite3_next_stmt(D, S)] +** routine shall return a NULL pointer. +** +** ASSUMPTIONS: +** +** {A13154} The [database connection] pointer D in a call to +** [sqlite3_next_stmt(D,S)] must refer to an open database +** connection and in particular must not be a NULL pointer. +*/ +SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt); /* -** CAPI3REF: Commit And Rollback Notification Callbacks {F12950} +** CAPI3REF: Commit And Rollback Notification Callbacks {H12950} <S60400> ** ** The sqlite3_commit_hook() interface registers a callback ** function to be invoked whenever a transaction is committed. @@ -4833,16 +5250,16 @@ SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*); ** function to be invoked whenever a transaction is committed. ** Any callback set by a previous call to sqlite3_commit_hook() ** for the same database connection is overridden. -** The pArg argument is passed through -** to the callback. If the callback on a commit hook function -** returns non-zero, then the commit is converted into a rollback. +** The pArg argument is passed through to the callback. +** If the callback on a commit hook function returns non-zero, +** then the commit is converted into a rollback. ** ** If another function was previously registered, its ** pArg value is returned. Otherwise NULL is returned. ** ** Registering a NULL function disables the callback. ** -** For the purposes of this API, a transaction is said to have been +** For the purposes of this API, a transaction is said to have been ** rolled back if an explicit "ROLLBACK" statement is executed, or ** an error or constraint causes an implicit rollback to occur. ** The rollback callback is not invoked if a transaction is @@ -4851,71 +5268,65 @@ SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*); ** rolled back because a commit callback returned non-zero. ** <todo> Check on this </todo> ** -** These are experimental interfaces and are subject to change. -** ** INVARIANTS: ** -** {F12951} The [sqlite3_commit_hook(D,F,P)] interface registers the +** {H12951} The [sqlite3_commit_hook(D,F,P)] interface registers the ** callback function F to be invoked with argument P whenever -** a transaction commits on [database connection] D. +** a transaction commits on the [database connection] D. ** -** {F12952} The [sqlite3_commit_hook(D,F,P)] interface returns the P -** argument from the previous call with the same -** [database connection ] D , or NULL on the first call -** for a particular [database connection] D. +** {H12952} The [sqlite3_commit_hook(D,F,P)] interface returns the P argument +** from the previous call with the same [database connection] D, +** or NULL on the first call for a particular database connection D. ** -** {F12953} Each call to [sqlite3_commit_hook()] overwrites the callback +** {H12953} Each call to [sqlite3_commit_hook()] overwrites the callback ** registered by prior calls. ** -** {F12954} If the F argument to [sqlite3_commit_hook(D,F,P)] is NULL -** then the commit hook callback is cancelled and no callback +** {H12954} If the F argument to [sqlite3_commit_hook(D,F,P)] is NULL +** then the commit hook callback is canceled and no callback ** is invoked when a transaction commits. ** -** {F12955} If the commit callback returns non-zero then the commit is +** {H12955} If the commit callback returns non-zero then the commit is ** converted into a rollback. ** -** {F12961} The [sqlite3_rollback_hook(D,F,P)] interface registers the +** {H12961} The [sqlite3_rollback_hook(D,F,P)] interface registers the ** callback function F to be invoked with argument P whenever -** a transaction rolls back on [database connection] D. +** a transaction rolls back on the [database connection] D. ** -** {F12962} The [sqlite3_rollback_hook(D,F,P)] interface returns the P -** argument from the previous call with the same -** [database connection ] D , or NULL on the first call -** for a particular [database connection] D. +** {H12962} The [sqlite3_rollback_hook(D,F,P)] interface returns the P +** argument from the previous call with the same +** [database connection] D, or NULL on the first call +** for a particular database connection D. ** -** {F12963} Each call to [sqlite3_rollback_hook()] overwrites the callback +** {H12963} Each call to [sqlite3_rollback_hook()] overwrites the callback ** registered by prior calls. ** -** {F12964} If the F argument to [sqlite3_rollback_hook(D,F,P)] is NULL -** then the rollback hook callback is cancelled and no callback +** {H12964} If the F argument to [sqlite3_rollback_hook(D,F,P)] is NULL +** then the rollback hook callback is canceled and no callback ** is invoked when a transaction rolls back. */ SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); /* -** CAPI3REF: Data Change Notification Callbacks {F12970} -** -** The sqlite3_update_hook() interface -** registers a callback function with the database connection identified by the -** first argument to be invoked whenever a row is updated, inserted or deleted. -** Any callback set by a previous call to this function for the same -** database connection is overridden. -** -** The second argument is a pointer to the function to invoke when a -** row is updated, inserted or deleted. -** The first argument to the callback is -** a copy of the third argument to sqlite3_update_hook(). -** The second callback -** argument is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], -** depending on the operation that caused the callback to be invoked. -** The third and -** fourth arguments to the callback contain pointers to the database and -** table name containing the affected row. -** The final callback parameter is -** the rowid of the row. -** In the case of an update, this is the rowid after -** the update takes place. +** CAPI3REF: Data Change Notification Callbacks {H12970} <S60400> +** +** The sqlite3_update_hook() interface registers a callback function +** with the [database connection] identified by the first argument +** to be invoked whenever a row is updated, inserted or deleted. +** Any callback set by a previous call to this function +** for the same database connection is overridden. +** +** The second argument is a pointer to the function to invoke when a +** row is updated, inserted or deleted. +** The first argument to the callback is a copy of the third argument +** to sqlite3_update_hook(). +** The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE], +** or [SQLITE_UPDATE], depending on the operation that caused the callback +** to be invoked. +** The third and fourth arguments to the callback contain pointers to the +** database and table name containing the affected row. +** The final callback parameter is the rowid of the row. In the case of +** an update, this is the rowid after the update takes place. ** ** The update hook is not invoked when internal system tables are ** modified (i.e. sqlite_master and sqlite_sequence). @@ -4925,33 +5336,33 @@ SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); ** ** INVARIANTS: ** -** {F12971} The [sqlite3_update_hook(D,F,P)] interface causes callback +** {H12971} The [sqlite3_update_hook(D,F,P)] interface causes the callback ** function F to be invoked with first parameter P whenever ** a table row is modified, inserted, or deleted on -** [database connection] D. +** the [database connection] D. ** -** {F12973} The [sqlite3_update_hook(D,F,P)] interface returns the value +** {H12973} The [sqlite3_update_hook(D,F,P)] interface returns the value ** of P for the previous call on the same [database connection] D, ** or NULL for the first call. ** -** {F12975} If the update hook callback F in [sqlite3_update_hook(D,F,P)] +** {H12975} If the update hook callback F in [sqlite3_update_hook(D,F,P)] ** is NULL then the no update callbacks are made. ** -** {F12977} Each call to [sqlite3_update_hook(D,F,P)] overrides prior calls +** {H12977} Each call to [sqlite3_update_hook(D,F,P)] overrides prior calls ** to the same interface on the same [database connection] D. ** -** {F12979} The update hook callback is not invoked when internal system +** {H12979} The update hook callback is not invoked when internal system ** tables such as sqlite_master and sqlite_sequence are modified. ** -** {F12981} The second parameter to the update callback +** {H12981} The second parameter to the update callback ** is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], ** depending on the operation that caused the callback to be invoked. ** -** {F12983} The third and fourth arguments to the callback contain pointers +** {H12983} The third and fourth arguments to the callback contain pointers ** to zero-terminated UTF-8 strings which are the names of the ** database and table that is being updated. -** {F12985} The final callback parameter is the rowid of the row after +** {H12985} The final callback parameter is the rowid of the row after ** the change occurs. */ SQLITE_API void *sqlite3_update_hook( @@ -4961,96 +5372,92 @@ SQLITE_API void *sqlite3_update_hook( ); /* -** CAPI3REF: Enable Or Disable Shared Pager Cache {F10330} +** CAPI3REF: Enable Or Disable Shared Pager Cache {H10330} <S30900> +** KEYWORDS: {shared cache} {shared cache mode} ** ** This routine enables or disables the sharing of the database cache -** and schema data structures between connections to the same database. -** Sharing is enabled if the argument is true and disabled if the argument -** is false. +** and schema data structures between [database connection | connections] +** to the same database. Sharing is enabled if the argument is true +** and disabled if the argument is false. ** -** Cache sharing is enabled and disabled -** for an entire process. {END} This is a change as of SQLite version 3.5.0. -** In prior versions of SQLite, sharing was -** enabled or disabled for each thread separately. +** Cache sharing is enabled and disabled for an entire process. {END} +** This is a change as of SQLite version 3.5.0. In prior versions of SQLite, +** sharing was enabled or disabled for each thread separately. ** ** The cache sharing mode set by this interface effects all subsequent ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. ** Existing database connections continue use the sharing mode ** that was in effect at the time they were opened. ** -** Virtual tables cannot be used with a shared cache. When shared +** Virtual tables cannot be used with a shared cache. When shared ** cache is enabled, the [sqlite3_create_module()] API used to register ** virtual tables will always return an error. ** -** This routine returns [SQLITE_OK] if shared cache was -** enabled or disabled successfully. An [error code] -** is returned otherwise. +** This routine returns [SQLITE_OK] if shared cache was enabled or disabled +** successfully. An [error code] is returned otherwise. ** ** Shared cache is disabled by default. But this might change in ** future releases of SQLite. Applications that care about shared ** cache setting should set it explicitly. ** ** INVARIANTS: -** -** {F10331} A successful invocation of [sqlite3_enable_shared_cache(B)] +** +** {H10331} A successful invocation of [sqlite3_enable_shared_cache(B)] ** will enable or disable shared cache mode for any subsequently ** created [database connection] in the same process. ** -** {F10336} When shared cache is enabled, the [sqlite3_create_module()] +** {H10336} When shared cache is enabled, the [sqlite3_create_module()] ** interface will always return an error. ** -** {F10337} The [sqlite3_enable_shared_cache(B)] interface returns +** {H10337} The [sqlite3_enable_shared_cache(B)] interface returns ** [SQLITE_OK] if shared cache was enabled or disabled successfully. ** -** {F10339} Shared cache is disabled by default. +** {H10339} Shared cache is disabled by default. */ SQLITE_API int sqlite3_enable_shared_cache(int); /* -** CAPI3REF: Attempt To Free Heap Memory {F17340} +** CAPI3REF: Attempt To Free Heap Memory {H17340} <S30220> ** -** The sqlite3_release_memory() interface attempts to -** free N bytes of heap memory by deallocating non-essential memory -** allocations held by the database labrary. {END} Memory used -** to cache database pages to improve performance is an example of -** non-essential memory. Sqlite3_release_memory() returns -** the number of bytes actually freed, which might be more or less -** than the amount requested. +** The sqlite3_release_memory() interface attempts to free N bytes +** of heap memory by deallocating non-essential memory allocations +** held by the database library. {END} Memory used to cache database +** pages to improve performance is an example of non-essential memory. +** sqlite3_release_memory() returns the number of bytes actually freed, +** which might be more or less than the amount requested. ** ** INVARIANTS: ** -** {F17341} The [sqlite3_release_memory(N)] interface attempts to +** {H17341} The [sqlite3_release_memory(N)] interface attempts to ** free N bytes of heap memory by deallocating non-essential -** memory allocations held by the database labrary. +** memory allocations held by the database library. ** -** {F16342} The [sqlite3_release_memory(N)] returns the number +** {H16342} The [sqlite3_release_memory(N)] returns the number ** of bytes actually freed, which might be more or less ** than the amount requested. */ SQLITE_API int sqlite3_release_memory(int); /* -** CAPI3REF: Impose A Limit On Heap Size {F17350} +** CAPI3REF: Impose A Limit On Heap Size {H17350} <S30220> ** -** The sqlite3_soft_heap_limit() interface -** places a "soft" limit on the amount of heap memory that may be allocated -** by SQLite. If an internal allocation is requested -** that would exceed the soft heap limit, [sqlite3_release_memory()] is -** invoked one or more times to free up some space before the allocation -** is made. +** The sqlite3_soft_heap_limit() interface places a "soft" limit +** on the amount of heap memory that may be allocated by SQLite. +** If an internal allocation is requested that would exceed the +** soft heap limit, [sqlite3_release_memory()] is invoked one or +** more times to free up some space before the allocation is performed. ** -** The limit is called "soft", because if -** [sqlite3_release_memory()] cannot -** free sufficient memory to prevent the limit from being exceeded, +** The limit is called "soft", because if [sqlite3_release_memory()] +** cannot free sufficient memory to prevent the limit from being exceeded, ** the memory is allocated anyway and the current operation proceeds. ** ** A negative or zero value for N means that there is no soft heap limit and ** [sqlite3_release_memory()] will only be called when memory is exhausted. ** The default value for the soft heap limit is zero. ** -** SQLite makes a best effort to honor the soft heap limit. -** But if the soft heap limit cannot honored, execution will -** continue without error or notification. This is why the limit is +** SQLite makes a best effort to honor the soft heap limit. +** But if the soft heap limit cannot be honored, execution will +** continue without error or notification. This is why the limit is ** called a "soft" limit. It is advisory only. ** ** Prior to SQLite version 3.5.0, this routine only constrained the memory @@ -5063,81 +5470,79 @@ SQLITE_API int sqlite3_release_memory(int); ** ** INVARIANTS: ** -** {F16351} The [sqlite3_soft_heap_limit(N)] interface places a soft limit +** {H16351} The [sqlite3_soft_heap_limit(N)] interface places a soft limit ** of N bytes on the amount of heap memory that may be allocated ** using [sqlite3_malloc()] or [sqlite3_realloc()] at any point ** in time. ** -** {F16352} If a call to [sqlite3_malloc()] or [sqlite3_realloc()] would +** {H16352} If a call to [sqlite3_malloc()] or [sqlite3_realloc()] would ** cause the total amount of allocated memory to exceed the ** soft heap limit, then [sqlite3_release_memory()] is invoked ** in an attempt to reduce the memory usage prior to proceeding ** with the memory allocation attempt. ** -** {F16353} Calls to [sqlite3_malloc()] or [sqlite3_realloc()] that trigger +** {H16353} Calls to [sqlite3_malloc()] or [sqlite3_realloc()] that trigger ** attempts to reduce memory usage through the soft heap limit ** mechanism continue even if the attempt to reduce memory ** usage is unsuccessful. ** -** {F16354} A negative or zero value for N in a call to +** {H16354} A negative or zero value for N in a call to ** [sqlite3_soft_heap_limit(N)] means that there is no soft ** heap limit and [sqlite3_release_memory()] will only be ** called when memory is completely exhausted. ** -** {F16355} The default value for the soft heap limit is zero. +** {H16355} The default value for the soft heap limit is zero. ** -** {F16358} Each call to [sqlite3_soft_heap_limit(N)] overrides the +** {H16358} Each call to [sqlite3_soft_heap_limit(N)] overrides the ** values set by all prior calls. */ SQLITE_API void sqlite3_soft_heap_limit(int); /* -** CAPI3REF: Extract Metadata About A Column Of A Table {F12850} +** CAPI3REF: Extract Metadata About A Column Of A Table {H12850} <S60300> ** -** This routine -** returns meta-data about a specific column of a specific database -** table accessible using the connection handle passed as the first function -** argument. +** This routine returns metadata about a specific column of a specific +** database table accessible using the [database connection] handle +** passed as the first function argument. ** -** The column is identified by the second, third and fourth parameters to +** The column is identified by the second, third and fourth parameters to ** this function. The second parameter is either the name of the database ** (i.e. "main", "temp" or an attached database) containing the specified ** table or NULL. If it is NULL, then all attached databases are searched -** for the table using the same algorithm as the database engine uses to +** for the table using the same algorithm used by the database engine to ** resolve unqualified table references. ** -** The third and fourth parameters to this function are the table and column -** name of the desired column, respectively. Neither of these parameters +** The third and fourth parameters to this function are the table and column +** name of the desired column, respectively. Neither of these parameters ** may be NULL. ** -** Meta information is returned by writing to the memory locations passed as -** the 5th and subsequent parameters to this function. Any of these -** arguments may be NULL, in which case the corresponding element of meta -** information is ommitted. +** Metadata is returned by writing to the memory locations passed as the 5th +** and subsequent parameters to this function. Any of these arguments may be +** NULL, in which case the corresponding element of metadata is omitted. ** -** <pre> -** Parameter Output Type Description -** ----------------------------------- -** -** 5th const char* Data type -** 6th const char* Name of the default collation sequence -** 7th int True if the column has a NOT NULL constraint -** 8th int True if the column is part of the PRIMARY KEY -** 9th int True if the column is AUTOINCREMENT -** </pre> +** <blockquote> +** <table border="1"> +** <tr><th> Parameter <th> Output<br>Type <th> Description ** +** <tr><td> 5th <td> const char* <td> Data type +** <tr><td> 6th <td> const char* <td> Name of default collation sequence +** <tr><td> 7th <td> int <td> True if column has a NOT NULL constraint +** <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY +** <tr><td> 9th <td> int <td> True if column is AUTOINCREMENT +** </table> +** </blockquote> ** -** The memory pointed to by the character pointers returned for the -** declaration type and collation sequence is valid only until the next -** call to any sqlite API function. +** The memory pointed to by the character pointers returned for the +** declaration type and collation sequence is valid only until the next +** call to any SQLite API function. ** -** If the specified table is actually a view, then an error is returned. +** If the specified table is actually a view, an [error code] is returned. ** -** If the specified column is "rowid", "oid" or "_rowid_" and an -** INTEGER PRIMARY KEY column has been explicitly declared, then the output +** If the specified column is "rowid", "oid" or "_rowid_" and an +** INTEGER PRIMARY KEY column has been explicitly declared, then the output ** parameters are set for the explicitly declared column. If there is no -** explicitly declared IPK column, then the output parameters are set as -** follows: +** explicitly declared INTEGER PRIMARY KEY column, then the output +** parameters are set as follows: ** ** <pre> ** data type: "INTEGER" @@ -5149,11 +5554,11 @@ SQLITE_API void sqlite3_soft_heap_limit(int); ** ** This function may load one or more schemas from database files. If an ** error occurs during this process, or if the requested table or column -** cannot be found, an SQLITE error code is returned and an error message -** left in the database handle (to be retrieved using sqlite3_errmsg()). +** cannot be found, an [error code] is returned and an error message left +** in the [database connection] (to be retrieved using sqlite3_errmsg()). ** ** This API is only available if the library was compiled with the -** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. +** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined. */ SQLITE_API int sqlite3_table_column_metadata( sqlite3 *db, /* Connection handle */ @@ -5168,27 +5573,30 @@ SQLITE_API int sqlite3_table_column_metadata( ); /* -** CAPI3REF: Load An Extension {F12600} +** CAPI3REF: Load An Extension {H12600} <S20500> +** +** This interface loads an SQLite extension library from the named file. ** -** {F12601} The sqlite3_load_extension() interface -** attempts to load an SQLite extension library contained in the file -** zFile. {F12602} The entry point is zProc. {F12603} zProc may be 0 -** in which case the name of the entry point defaults -** to "sqlite3_extension_init". +** {H12601} The sqlite3_load_extension() interface attempts to load an +** SQLite extension library contained in the file zFile. ** -** {F12604} The sqlite3_load_extension() interface shall -** return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. +** {H12602} The entry point is zProc. ** -** {F12605} -** If an error occurs and pzErrMsg is not 0, then the -** sqlite3_load_extension() interface shall attempt to fill *pzErrMsg with -** error message text stored in memory obtained from [sqlite3_malloc()]. -** {END} The calling function should free this memory -** by calling [sqlite3_free()]. +** {H12603} zProc may be 0, in which case the name of the entry point +** defaults to "sqlite3_extension_init". ** -** {F12606} -** Extension loading must be enabled using [sqlite3_enable_load_extension()] -** prior to calling this API or an error will be returned. +** {H12604} The sqlite3_load_extension() interface shall return +** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. +** +** {H12605} If an error occurs and pzErrMsg is not 0, then the +** [sqlite3_load_extension()] interface shall attempt to +** fill *pzErrMsg with error message text stored in memory +** obtained from [sqlite3_malloc()]. {END} The calling function +** should free this memory by calling [sqlite3_free()]. +** +** {H12606} Extension loading must be enabled using +** [sqlite3_enable_load_extension()] prior to calling this API, +** otherwise an error will be returned. */ SQLITE_API int sqlite3_load_extension( sqlite3 *db, /* Load the extension into this database connection */ @@ -5198,65 +5606,64 @@ SQLITE_API int sqlite3_load_extension( ); /* -** CAPI3REF: Enable Or Disable Extension Loading {F12620} +** CAPI3REF: Enable Or Disable Extension Loading {H12620} <S20500> ** ** So as not to open security holes in older applications that are ** unprepared to deal with extension loading, and as a means of disabling -** extension loading while evaluating user-entered SQL, the following -** API is provided to turn the [sqlite3_load_extension()] mechanism on and -** off. {F12622} It is off by default. {END} See ticket #1863. +** extension loading while evaluating user-entered SQL, the following API +** is provided to turn the [sqlite3_load_extension()] mechanism on and off. +** +** Extension loading is off by default. See ticket #1863. +** +** {H12621} Call the sqlite3_enable_load_extension() routine with onoff==1 +** to turn extension loading on and call it with onoff==0 to turn +** it back off again. ** -** {F12621} Call the sqlite3_enable_load_extension() routine -** with onoff==1 to turn extension loading on -** and call it with onoff==0 to turn it back off again. {END} +** {H12622} Extension loading is off by default. */ SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff); /* -** CAPI3REF: Make Arrangements To Automatically Load An Extension {F12640} -** -** {F12641} This function -** registers an extension entry point that is automatically invoked -** whenever a new database connection is opened using -** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()]. {END} +** CAPI3REF: Automatically Load An Extensions {H12640} <S20500> ** ** This API can be invoked at program startup in order to register ** one or more statically linked extensions that will be available -** to all new database connections. +** to all new [database connections]. {END} ** -** {F12642} Duplicate extensions are detected so calling this routine multiple -** times with the same extension is harmless. +** This routine stores a pointer to the extension in an array that is +** obtained from [sqlite3_malloc()]. If you run a memory leak checker +** on your program and it reports a leak because of this array, invoke +** [sqlite3_reset_auto_extension()] prior to shutdown to free the memory. ** -** {F12643} This routine stores a pointer to the extension in an array -** that is obtained from sqlite_malloc(). {END} If you run a memory leak -** checker on your program and it reports a leak because of this -** array, then invoke [sqlite3_reset_auto_extension()] prior -** to shutdown to free the memory. +** {H12641} This function registers an extension entry point that is +** automatically invoked whenever a new [database connection] +** is opened using [sqlite3_open()], [sqlite3_open16()], +** or [sqlite3_open_v2()]. ** -** {F12644} Automatic extensions apply across all threads. {END} +** {H12642} Duplicate extensions are detected so calling this routine +** multiple times with the same extension is harmless. ** -** This interface is experimental and is subject to change or -** removal in future releases of SQLite. +** {H12643} This routine stores a pointer to the extension in an array +** that is obtained from [sqlite3_malloc()]. +** +** {H12644} Automatic extensions apply across all threads. */ SQLITE_API int sqlite3_auto_extension(void *xEntryPoint); - /* -** CAPI3REF: Reset Automatic Extension Loading {F12660} +** CAPI3REF: Reset Automatic Extension Loading {H12660} <S20500> ** -** {F12661} This function disables all previously registered -** automatic extensions. {END} This -** routine undoes the effect of all prior [sqlite3_auto_extension()] -** calls. +** This function disables all previously registered automatic +** extensions. {END} It undoes the effect of all prior +** [sqlite3_auto_extension()] calls. ** -** {F12662} This call disabled automatic extensions in all threads. {END} +** {H12661} This function disables all previously registered +** automatic extensions. ** -** This interface is experimental and is subject to change or -** removal in future releases of SQLite. +** {H12662} This function disables automatic extensions in all threads. */ SQLITE_API void sqlite3_reset_auto_extension(void); - /* ****** EXPERIMENTAL - subject to change without notice ************** ** @@ -5264,7 +5671,7 @@ SQLITE_API void sqlite3_reset_auto_extension(void); ** to be experimental. The interface might change in incompatible ways. ** If this is a problem for you, do not use the interface at this time. ** -** When the virtual-table mechanism stablizes, we will declare the +** When the virtual-table mechanism stabilizes, we will declare the ** interface fixed, support it indefinitely, and remove this comment. */ @@ -5277,12 +5684,16 @@ typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; typedef struct sqlite3_module sqlite3_module; /* -** CAPI3REF: Virtual Table Object {F18000} +** CAPI3REF: Virtual Table Object {H18000} <S20400> ** KEYWORDS: sqlite3_module +** EXPERIMENTAL ** ** A module is a class of virtual tables. Each module is defined ** by an instance of the following structure. This structure consists ** mostly of methods for the module. +** +** This interface is experimental and is subject to change or +** removal in future releases of SQLite. */ struct sqlite3_module { int iVersion; @@ -5311,13 +5722,13 @@ struct sqlite3_module { int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), void **ppArg); - int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); }; /* -** CAPI3REF: Virtual Table Indexing Information {F18100} +** CAPI3REF: Virtual Table Indexing Information {H18100} <S20400> ** KEYWORDS: sqlite3_index_info +** EXPERIMENTAL ** ** The sqlite3_index_info structure and its substructures is used to ** pass information into and receive the reply from the xBestIndex @@ -5325,14 +5736,12 @@ struct sqlite3_module { ** inputs to xBestIndex and are read-only. xBestIndex inserts its ** results into the **Outputs** fields. ** -** The aConstraint[] array records WHERE clause constraints of the -** form: +** The aConstraint[] array records WHERE clause constraints of the form: ** -** column OP expr +** <pre>column OP expr</pre> ** -** Where OP is =, <, <=, >, or >=. -** The particular operator is stored -** in aConstraint[].op. The index of the column is stored in +** where OP is =, <, <=, >, or >=. The particular operator is +** stored in aConstraint[].op. The index of the column is stored in ** aConstraint[].iColumn. aConstraint[].usable is TRUE if the ** expr on the right-hand side can be evaluated (and thus the constraint ** is usable) and false if it cannot. @@ -5364,6 +5773,9 @@ struct sqlite3_module { ** particular lookup. A full scan of a table with N entries should have ** a cost of N. A binary search of a table of N entries should have a ** cost of approximately log(N). +** +** This interface is experimental and is subject to change or +** removal in future releases of SQLite. */ struct sqlite3_index_info { /* Inputs */ @@ -5379,7 +5791,6 @@ struct sqlite3_index_info { int iColumn; /* Column number */ unsigned char desc; /* True for DESC. False for ASC. */ } *aOrderBy; /* The ORDER BY clause */ - /* Outputs */ struct sqlite3_index_constraint_usage { int argvIndex; /* if >0, constraint is part of argv to xFilter */ @@ -5399,12 +5810,16 @@ struct sqlite3_index_info { #define SQLITE_INDEX_CONSTRAINT_MATCH 64 /* -** CAPI3REF: Register A Virtual Table Implementation {F18200} +** CAPI3REF: Register A Virtual Table Implementation {H18200} <S20400> +** EXPERIMENTAL ** -** This routine is used to register a new module name with an SQLite -** connection. Module names must be registered before creating new -** virtual tables on the module, or before using preexisting virtual -** tables of the module. +** This routine is used to register a new module name with a +** [database connection]. Module names must be registered before +** creating new virtual tables on the module, or before using +** preexisting virtual tables of the module. +** +** This interface is experimental and is subject to change or +** removal in future releases of SQLite. */ SQLITE_API int sqlite3_create_module( sqlite3 *db, /* SQLite connection to register module with */ @@ -5414,9 +5829,10 @@ SQLITE_API int sqlite3_create_module( ); /* -** CAPI3REF: Register A Virtual Table Implementation {F18210} +** CAPI3REF: Register A Virtual Table Implementation {H18210} <S20400> +** EXPERIMENTAL ** -** This routine is identical to the sqlite3_create_module() method above, +** This routine is identical to the [sqlite3_create_module()] method above, ** except that it allows a destructor function to be specified. It is ** even more experimental than the rest of the virtual tables API. */ @@ -5429,24 +5845,28 @@ SQLITE_API int sqlite3_create_module_v2( ); /* -** CAPI3REF: Virtual Table Instance Object {F18010} +** CAPI3REF: Virtual Table Instance Object {H18010} <S20400> ** KEYWORDS: sqlite3_vtab +** EXPERIMENTAL ** ** Every module implementation uses a subclass of the following structure ** to describe a particular instance of the module. Each subclass will -** be tailored to the specific needs of the module implementation. The -** purpose of this superclass is to define certain fields that are common -** to all module implementations. +** be tailored to the specific needs of the module implementation. +** The purpose of this superclass is to define certain fields that are +** common to all module implementations. ** ** Virtual tables methods can set an error message by assigning a -** string obtained from sqlite3_mprintf() to zErrMsg. The method should -** take care that any prior string is freed by a call to sqlite3_free() +** string obtained from [sqlite3_mprintf()] to zErrMsg. The method should +** take care that any prior string is freed by a call to [sqlite3_free()] ** prior to assigning a new string to zErrMsg. After the error message ** is delivered up to the client application, the string will be automatically ** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note ** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field ** since virtual tables are commonly implemented in loadable extensions which ** do not have access to sqlite3MPrintf() or sqlite3Free(). +** +** This interface is experimental and is subject to change or +** removal in future releases of SQLite. */ struct sqlite3_vtab { const sqlite3_module *pModule; /* The module for this virtual table */ @@ -5456,8 +5876,9 @@ struct sqlite3_vtab { }; /* -** CAPI3REF: Virtual Table Cursor Object {F18020} +** CAPI3REF: Virtual Table Cursor Object {H18020} <S20400> ** KEYWORDS: sqlite3_vtab_cursor +** EXPERIMENTAL ** ** Every module implementation uses a subclass of the following structure ** to describe cursors that point into the virtual table and are used @@ -5467,6 +5888,9 @@ struct sqlite3_vtab { ** ** This superclass exists in order to define fields of the cursor that ** are common to all implementations. +** +** This interface is experimental and is subject to change or +** removal in future releases of SQLite. */ struct sqlite3_vtab_cursor { sqlite3_vtab *pVtab; /* Virtual table of this cursor */ @@ -5474,16 +5898,21 @@ struct sqlite3_vtab_cursor { }; /* -** CAPI3REF: Declare The Schema Of A Virtual Table {F18280} +** CAPI3REF: Declare The Schema Of A Virtual Table {H18280} <S20400> +** EXPERIMENTAL ** ** The xCreate and xConnect methods of a module use the following API ** to declare the format (the names and datatypes of the columns) of ** the virtual tables they implement. +** +** This interface is experimental and is subject to change or +** removal in future releases of SQLite. */ SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); /* -** CAPI3REF: Overload A Function For A Virtual Table {F18300} +** CAPI3REF: Overload A Function For A Virtual Table {H18300} <S20400> +** EXPERIMENTAL ** ** Virtual tables can provide alternative implementations of functions ** using the xFindFunction method. But global versions of those functions @@ -5494,7 +5923,7 @@ SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); ** before this API is called, a new function is created. The implementation ** of the new function always causes an exception to be thrown. So ** the new function is not good for anything by itself. Its only -** purpose is to be a place-holder function that can be overloaded +** purpose is to be a placeholder function that can be overloaded ** by virtual tables. ** ** This API should be considered part of the virtual table interface, @@ -5515,68 +5944,83 @@ SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nA */ /* -** CAPI3REF: A Handle To An Open BLOB {F17800} +** CAPI3REF: A Handle To An Open BLOB {H17800} <S30230> +** KEYWORDS: {BLOB handle} {BLOB handles} ** ** An instance of this object represents an open BLOB on which -** incremental I/O can be preformed. -** Objects of this type are created by -** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()]. +** [sqlite3_blob_open | incremental BLOB I/O] can be performed. +** Objects of this type are created by [sqlite3_blob_open()] +** and destroyed by [sqlite3_blob_close()]. ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces -** can be used to read or write small subsections of the blob. -** The [sqlite3_blob_bytes()] interface returns the size of the -** blob in bytes. +** can be used to read or write small subsections of the BLOB. +** The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes. */ typedef struct sqlite3_blob sqlite3_blob; /* -** CAPI3REF: Open A BLOB For Incremental I/O {F17810} +** CAPI3REF: Open A BLOB For Incremental I/O {H17810} <S30230> ** -** This interfaces opens a handle to the blob located +** This interfaces opens a [BLOB handle | handle] to the BLOB located ** in row iRow, column zColumn, table zTable in database zDb; -** in other words, the same blob that would be selected by: +** in other words, the same BLOB that would be selected by: ** ** <pre> ** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow; ** </pre> {END} ** -** If the flags parameter is non-zero, the blob is opened for -** read and write access. If it is zero, the blob is opened for read -** access. +** If the flags parameter is non-zero, the the BLOB is opened for read +** and write access. If it is zero, the BLOB is opened for read access. ** ** Note that the database name is not the filename that contains ** the database but rather the symbolic name of the database that ** is assigned when the database is connected using [ATTACH]. -** For the main database file, the database name is "main". For -** TEMP tables, the database name is "temp". -** -** On success, [SQLITE_OK] is returned and the new -** [sqlite3_blob | blob handle] is written to *ppBlob. -** Otherwise an error code is returned and -** any value written to *ppBlob should not be used by the caller. -** This function sets the database-handle error code and message +** For the main database file, the database name is "main". +** For TEMP tables, the database name is "temp". +** +** On success, [SQLITE_OK] is returned and the new [BLOB handle] is written +** to *ppBlob. Otherwise an [error code] is returned and any value written +** to *ppBlob should not be used by the caller. +** This function sets the [database connection] error code and message ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()]. -** +** +** If the row that a BLOB handle points to is modified by an +** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects +** then the BLOB handle is marked as "expired". +** This is true if any column of the row is changed, even a column +** other than the one the BLOB handle is open on. +** Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for +** a expired BLOB handle fail with an return code of [SQLITE_ABORT]. +** Changes written into a BLOB prior to the BLOB expiring are not +** rollback by the expiration of the BLOB. Such changes will eventually +** commit if the transaction continues to completion. +** ** INVARIANTS: ** -** {F17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)] -** interface opens an [sqlite3_blob] object P on the blob -** in column C of table T in database B on [database connection] D. +** {H17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)] +** interface shall open an [sqlite3_blob] object P on the BLOB +** in column C of the table T in the database B on +** the [database connection] D. ** -** {F17814} A successful invocation of [sqlite3_blob_open(D,...)] starts -** a new transaction on [database connection] D if that connection -** is not already in a transaction. +** {H17814} A successful invocation of [sqlite3_blob_open(D,...)] shall start +** a new transaction on the [database connection] D if that +** connection is not already in a transaction. ** -** {F17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface opens the blob -** for read and write access if and only if the F parameter -** is non-zero. +** {H17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface shall open +** the BLOB for read and write access if and only if the F +** parameter is non-zero. ** -** {F17819} The [sqlite3_blob_open()] interface returns [SQLITE_OK] on +** {H17819} The [sqlite3_blob_open()] interface shall return [SQLITE_OK] on ** success and an appropriate [error code] on failure. ** -** {F17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)] +** {H17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)] ** then subsequent calls to [sqlite3_errcode(D)], -** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return -** information approprate for that error. +** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return +** information appropriate for that error. +** +** {H17824} If any column in the row that a [sqlite3_blob] has open is +** changed by a separate [UPDATE] or [DELETE] statement or by +** an [ON CONFLICT] side effect, then the [sqlite3_blob] shall +** be marked as invalid. */ SQLITE_API int sqlite3_blob_open( sqlite3*, @@ -5589,18 +6033,19 @@ SQLITE_API int sqlite3_blob_open( ); /* -** CAPI3REF: Close A BLOB Handle {F17830} +** CAPI3REF: Close A BLOB Handle {H17830} <S30230> ** -** Close an open [sqlite3_blob | blob handle]. +** Closes an open [BLOB handle]. ** ** Closing a BLOB shall cause the current transaction to commit ** if there are no other BLOBs, no pending prepared statements, and the -** database connection is in autocommit mode. +** database connection is in [autocommit mode]. ** If any writes were made to the BLOB, they might be held in cache ** until the close operation if they will fit. {END} +** ** Closing the BLOB often forces the changes ** out to disk and so if any I/O errors occur, they will likely occur -** at the time when the BLOB is closed. {F17833} Any errors that occur during +** at the time when the BLOB is closed. {H17833} Any errors that occur during ** closing are reported as a non-zero return value. ** ** The BLOB is closed unconditionally. Even if this routine returns @@ -5608,139 +6053,156 @@ SQLITE_API int sqlite3_blob_open( ** ** INVARIANTS: ** -** {F17833} The [sqlite3_blob_close(P)] interface closes an -** [sqlite3_blob] object P previously opened using -** [sqlite3_blob_open()]. +** {H17833} The [sqlite3_blob_close(P)] interface closes an [sqlite3_blob] +** object P previously opened using [sqlite3_blob_open()]. ** -** {F17836} Closing an [sqlite3_blob] object using +** {H17836} Closing an [sqlite3_blob] object using ** [sqlite3_blob_close()] shall cause the current transaction to ** commit if there are no other open [sqlite3_blob] objects ** or [prepared statements] on the same [database connection] and -** the [database connection] is in -** [sqlite3_get_autocommit | autocommit mode]. +** the database connection is in [autocommit mode]. ** -** {F17839} The [sqlite3_blob_close(P)] interfaces closes the +** {H17839} The [sqlite3_blob_close(P)] interfaces shall close the ** [sqlite3_blob] object P unconditionally, even if ** [sqlite3_blob_close(P)] returns something other than [SQLITE_OK]. -** */ SQLITE_API int sqlite3_blob_close(sqlite3_blob *); /* -** CAPI3REF: Return The Size Of An Open BLOB {F17840} +** CAPI3REF: Return The Size Of An Open BLOB {H17840} <S30230> ** -** Return the size in bytes of the blob accessible via the open -** [sqlite3_blob] object in its only argument. +** Returns the size in bytes of the BLOB accessible via the open +** []BLOB handle] in its only argument. ** ** INVARIANTS: ** -** {F17843} The [sqlite3_blob_bytes(P)] interface returns the size +** {H17843} The [sqlite3_blob_bytes(P)] interface returns the size ** in bytes of the BLOB that the [sqlite3_blob] object P ** refers to. */ SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *); /* -** CAPI3REF: Read Data From A BLOB Incrementally {F17850} +** CAPI3REF: Read Data From A BLOB Incrementally {H17850} <S30230> ** -** This function is used to read data from an open -** [sqlite3_blob | blob-handle] into a caller supplied buffer. -** N bytes of data are copied into buffer -** Z from the open blob, starting at offset iOffset. +** This function is used to read data from an open [BLOB handle] into a +** caller-supplied buffer. N bytes of data are copied into buffer Z +** from the open BLOB, starting at offset iOffset. ** -** If offset iOffset is less than N bytes from the end of the blob, +** If offset iOffset is less than N bytes from the end of the BLOB, ** [SQLITE_ERROR] is returned and no data is read. If N or iOffset is -** less than zero [SQLITE_ERROR] is returned and no data is read. +** less than zero, [SQLITE_ERROR] is returned and no data is read. ** -** On success, SQLITE_OK is returned. Otherwise, an -** [error code] or an [extended error code] is returned. +** An attempt to read from an expired [BLOB handle] fails with an +** error code of [SQLITE_ABORT]. +** +** On success, SQLITE_OK is returned. +** Otherwise, an [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** -** {F17853} The [sqlite3_blob_read(P,Z,N,X)] interface reads N bytes -** beginning at offset X from -** the blob that [sqlite3_blob] object P refers to -** and writes those N bytes into buffer Z. +** {H17853} A successful invocation of [sqlite3_blob_read(P,Z,N,X)] +** shall reads N bytes of data out of the BLOB referenced by +** [BLOB handle] P beginning at offset X and store those bytes +** into buffer Z. +** +** {H17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the BLOB +** is less than N+X bytes, then the function shall leave the +** Z buffer unchanged and return [SQLITE_ERROR]. ** -** {F17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the blob -** is less than N+X bytes, then the function returns [SQLITE_ERROR] -** and nothing is read from the blob. +** {H17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero +** then the function shall leave the Z buffer unchanged +** and return [SQLITE_ERROR]. ** -** {F17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero -** then the function returns [SQLITE_ERROR] -** and nothing is read from the blob. +** {H17862} The [sqlite3_blob_read(P,Z,N,X)] interface shall return [SQLITE_OK] +** if N bytes are successfully read into buffer Z. ** -** {F17862} The [sqlite3_blob_read(P,Z,N,X)] interface returns [SQLITE_OK] -** if N bytes where successfully read into buffer Z. +** {H17863} If the [BLOB handle] P is expired and X and N are within bounds +** then [sqlite3_blob_read(P,Z,N,X)] shall leave the Z buffer +** unchanged and return [SQLITE_ABORT]. ** -** {F17865} If the requested read could not be completed, -** the [sqlite3_blob_read(P,Z,N,X)] interface returns an +** {H17865} If the requested read could not be completed, +** the [sqlite3_blob_read(P,Z,N,X)] interface shall return an ** appropriate [error code] or [extended error code]. ** -** {F17868} If an error occurs during evaluation of [sqlite3_blob_read(P,...)] +** {H17868} If an error occurs during evaluation of [sqlite3_blob_read(P,...)] ** then subsequent calls to [sqlite3_errcode(D)], -** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return -** information approprate for that error, where D is the -** database handle that was used to open blob handle P. +** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return +** information appropriate for that error, where D is the +** [database connection] that was used to open the [BLOB handle] P. */ SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); /* -** CAPI3REF: Write Data Into A BLOB Incrementally {F17870} +** CAPI3REF: Write Data Into A BLOB Incrementally {H17870} <S30230> ** -** This function is used to write data into an open -** [sqlite3_blob | blob-handle] from a user supplied buffer. -** n bytes of data are copied from the buffer -** pointed to by z into the open blob, starting at offset iOffset. +** This function is used to write data into an open [BLOB handle] from a +** caller-supplied buffer. N bytes of data are copied from the buffer Z +** into the open BLOB, starting at offset iOffset. ** -** If the [sqlite3_blob | blob-handle] passed as the first argument -** was not opened for writing (the flags parameter to [sqlite3_blob_open()] -*** was zero), this function returns [SQLITE_READONLY]. +** If the [BLOB handle] passed as the first argument was not opened for +** writing (the flags parameter to [sqlite3_blob_open()] was zero), +** this function returns [SQLITE_READONLY]. ** -** This function may only modify the contents of the blob; it is -** not possible to increase the size of a blob using this API. -** If offset iOffset is less than n bytes from the end of the blob, -** [SQLITE_ERROR] is returned and no data is written. If n is +** This function may only modify the contents of the BLOB; it is +** not possible to increase the size of a BLOB using this API. +** If offset iOffset is less than N bytes from the end of the BLOB, +** [SQLITE_ERROR] is returned and no data is written. If N is ** less than zero [SQLITE_ERROR] is returned and no data is written. ** -** On success, SQLITE_OK is returned. Otherwise, an -** [error code] or an [extended error code] is returned. +** An attempt to write to an expired [BLOB handle] fails with an +** error code of [SQLITE_ABORT]. Writes to the BLOB that occurred +** before the [BLOB handle] expired are not rolled back by the +** expiration of the handle, though of course those changes might +** have been overwritten by the statement that expired the BLOB handle +** or by other independent statements. +** +** On success, SQLITE_OK is returned. +** Otherwise, an [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** -** {F17873} The [sqlite3_blob_write(P,Z,N,X)] interface writes N bytes -** from buffer Z into -** the blob that [sqlite3_blob] object P refers to -** beginning at an offset of X into the blob. +** {H17873} A successful invocation of [sqlite3_blob_write(P,Z,N,X)] +** shall write N bytes of data from buffer Z into the BLOB +** referenced by [BLOB handle] P beginning at offset X into +** the BLOB. ** -** {F17875} The [sqlite3_blob_write(P,Z,N,X)] interface returns -** [SQLITE_READONLY] if the [sqlite3_blob] object P was -** [sqlite3_blob_open | opened] for reading only. +** {H17874} In the absence of other overridding changes, the changes +** written to a BLOB by [sqlite3_blob_write()] shall +** remain in effect after the associated [BLOB handle] expires. ** -** {F17876} In [sqlite3_blob_write(P,Z,N,X)] if the size of the blob -** is less than N+X bytes, then the function returns [SQLITE_ERROR] -** and nothing is written into the blob. +** {H17875} If the [BLOB handle] P was opened for reading only then +** an invocation of [sqlite3_blob_write(P,Z,N,X)] shall leave +** the referenced BLOB unchanged and return [SQLITE_READONLY]. ** -** {F17879} In [sqlite3_blob_write(P,Z,N,X)] if X or N is less than zero -** then the function returns [SQLITE_ERROR] -** and nothing is written into the blob. +** {H17876} If the size of the BLOB referenced by [BLOB handle] P is +** less than N+X bytes then [sqlite3_blob_write(P,Z,N,X)] shall +** leave the BLOB unchanged and return [SQLITE_ERROR]. ** -** {F17882} The [sqlite3_blob_write(P,Z,N,X)] interface returns [SQLITE_OK] -** if N bytes where successfully written into blob. +** {H17877} If the [BLOB handle] P is expired and X and N are within bounds +** then [sqlite3_blob_read(P,Z,N,X)] shall leave the BLOB +** unchanged and return [SQLITE_ABORT]. ** -** {F17885} If the requested write could not be completed, -** the [sqlite3_blob_write(P,Z,N,X)] interface returns an +** {H17879} If X or N are less than zero then [sqlite3_blob_write(P,Z,N,X)] +** shall leave the BLOB referenced by [BLOB handle] P unchanged +** and return [SQLITE_ERROR]. +** +** {H17882} The [sqlite3_blob_write(P,Z,N,X)] interface shall return +** [SQLITE_OK] if N bytes where successfully written into the BLOB. +** +** {H17885} If the requested write could not be completed, +** the [sqlite3_blob_write(P,Z,N,X)] interface shall return an ** appropriate [error code] or [extended error code]. ** -** {F17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)] +** {H17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)] ** then subsequent calls to [sqlite3_errcode(D)], -** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return -** information approprate for that error. +** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return +** information appropriate for that error. */ SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); /* -** CAPI3REF: Virtual File System Objects {F11200} +** CAPI3REF: Virtual File System Objects {H11200} <S20100> ** ** A virtual filesystem (VFS) is an [sqlite3_vfs] object ** that SQLite uses to interact @@ -5749,12 +6211,11 @@ SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOff ** New VFSes can be registered and existing VFSes can be unregistered. ** The following interfaces are provided. ** -** The sqlite3_vfs_find() interface returns a pointer to -** a VFS given its name. Names are case sensitive. +** The sqlite3_vfs_find() interface returns a pointer to a VFS given its name. +** Names are case sensitive. ** Names are zero-terminated UTF-8 strings. -** If there is no match, a NULL -** pointer is returned. If zVfsName is NULL then the default -** VFS is returned. +** If there is no match, a NULL pointer is returned. +** If zVfsName is NULL then the default VFS is returned. ** ** New VFSes are registered with sqlite3_vfs_register(). ** Each new VFS becomes the default VFS if the makeDflt flag is set. @@ -5764,35 +6225,34 @@ SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOff ** same name are registered, the behavior is undefined. If a ** VFS is registered with a name that is NULL or an empty string, ** then the behavior is undefined. -** +** ** Unregister a VFS with the sqlite3_vfs_unregister() interface. ** If the default VFS is unregistered, another VFS is chosen as ** the default. The choice for the new VFS is arbitrary. ** ** INVARIANTS: ** -** {F11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the +** {H11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the ** registered [sqlite3_vfs] object whose name exactly matches ** the zero-terminated UTF-8 string N, or it returns NULL if ** there is no match. ** -** {F11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then +** {H11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then ** the function returns a pointer to the default [sqlite3_vfs] -** object if there is one, or NULL if there is no default +** object if there is one, or NULL if there is no default ** [sqlite3_vfs] object. ** -** {F11209} The [sqlite3_vfs_register(P,F)] interface registers the +** {H11209} The [sqlite3_vfs_register(P,F)] interface registers the ** well-formed [sqlite3_vfs] object P using the name given ** by the zName field of the object. ** -** {F11212} Using the [sqlite3_vfs_register(P,F)] interface to register +** {H11212} Using the [sqlite3_vfs_register(P,F)] interface to register ** the same [sqlite3_vfs] object multiple times is a harmless no-op. ** -** {F11215} The [sqlite3_vfs_register(P,F)] interface makes the -** the [sqlite3_vfs] object P the default [sqlite3_vfs] object -** if F is non-zero. +** {H11215} The [sqlite3_vfs_register(P,F)] interface makes the [sqlite3_vfs] +** object P the default [sqlite3_vfs] object if F is non-zero. ** -** {F11218} The [sqlite3_vfs_unregister(P)] interface unregisters the +** {H11218} The [sqlite3_vfs_unregister(P)] interface unregisters the ** [sqlite3_vfs] object P so that it is no longer returned by ** subsequent calls to [sqlite3_vfs_find()]. */ @@ -5801,14 +6261,14 @@ SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*); /* -** CAPI3REF: Mutexes {F17000} +** CAPI3REF: Mutexes {H17000} <S20000> ** ** The SQLite core uses these routines for thread -** synchronization. Though they are intended for internal +** synchronization. Though they are intended for internal ** use by SQLite, code that links against SQLite is ** permitted to use any of these routines. ** -** The SQLite source code contains multiple implementations +** The SQLite source code contains multiple implementations ** of these mutex routines. An appropriate implementation ** is selected automatically at compile-time. The following ** implementations are available in the SQLite core: @@ -5820,25 +6280,24 @@ SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*); ** <li> SQLITE_MUTEX_NOOP ** </ul> ** -** The SQLITE_MUTEX_NOOP implementation is a set of routines -** that does no real locking and is appropriate for use in +** The SQLITE_MUTEX_NOOP implementation is a set of routines +** that does no real locking and is appropriate for use in ** a single-threaded application. The SQLITE_MUTEX_OS2, ** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations -** are appropriate for use on os/2, unix, and windows. -** +** are appropriate for use on OS/2, Unix, and Windows. +** ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex -** implementation is included with the library. The -** mutex interface routines defined here become external -** references in the SQLite library for which implementations -** must be provided by the application. This facility allows an -** application that links against SQLite to provide its own mutex -** implementation without having to modify the SQLite core. -** -** {F17011} The sqlite3_mutex_alloc() routine allocates a new -** mutex and returns a pointer to it. {F17012} If it returns NULL -** that means that a mutex could not be allocated. {F17013} SQLite -** will unwind its stack and return an error. {F17014} The argument +** implementation is included with the library. In this case the +** application must supply a custom mutex implementation using the +** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function +** before calling sqlite3_initialize() or any other public sqlite3_ +** function that calls sqlite3_initialize(). +** +** {H17011} The sqlite3_mutex_alloc() routine allocates a new +** mutex and returns a pointer to it. {H17012} If it returns NULL +** that means that a mutex could not be allocated. {H17013} SQLite +** will unwind its stack and return an error. {H17014} The argument ** to sqlite3_mutex_alloc() is one of these integer constants: ** ** <ul> @@ -5850,19 +6309,19 @@ SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*); ** <li> SQLITE_MUTEX_STATIC_PRNG ** <li> SQLITE_MUTEX_STATIC_LRU ** <li> SQLITE_MUTEX_STATIC_LRU2 -** </ul> {END} +** </ul> ** -** {F17015} The first two constants cause sqlite3_mutex_alloc() to create +** {H17015} The first two constants cause sqlite3_mutex_alloc() to create ** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE ** is used but not necessarily so when SQLITE_MUTEX_FAST is used. {END} ** The mutex implementation does not need to make a distinction ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does -** not want to. {F17016} But SQLite will only request a recursive mutex in +** not want to. {H17016} But SQLite will only request a recursive mutex in ** cases where it really needs one. {END} If a faster non-recursive mutex ** implementation is available on the host platform, the mutex subsystem ** might return such a mutex in response to SQLITE_MUTEX_FAST. ** -** {F17017} The other allowed parameters to sqlite3_mutex_alloc() each return +** {H17017} The other allowed parameters to sqlite3_mutex_alloc() each return ** a pointer to a static preexisting mutex. {END} Four static mutexes are ** used by the current version of SQLite. Future versions of SQLite ** may add additional static mutexes. Static mutexes are for internal @@ -5870,43 +6329,47 @@ SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*); ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or ** SQLITE_MUTEX_RECURSIVE. ** -** {F17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST +** {H17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() -** returns a different mutex on every call. {F17034} But for the static +** returns a different mutex on every call. {H17034} But for the static ** mutex types, the same mutex is returned on every call that has -** the same type number. {END} +** the same type number. ** -** {F17019} The sqlite3_mutex_free() routine deallocates a previously -** allocated dynamic mutex. {F17020} SQLite is careful to deallocate every -** dynamic mutex that it allocates. {U17021} The dynamic mutexes must not be in -** use when they are deallocated. {U17022} Attempting to deallocate a static -** mutex results in undefined behavior. {F17023} SQLite never deallocates +** {H17019} The sqlite3_mutex_free() routine deallocates a previously +** allocated dynamic mutex. {H17020} SQLite is careful to deallocate every +** dynamic mutex that it allocates. {A17021} The dynamic mutexes must not be in +** use when they are deallocated. {A17022} Attempting to deallocate a static +** mutex results in undefined behavior. {H17023} SQLite never deallocates ** a static mutex. {END} ** ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt -** to enter a mutex. {F17024} If another thread is already within the mutex, +** to enter a mutex. {H17024} If another thread is already within the mutex, ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return -** SQLITE_BUSY. {F17025} The sqlite3_mutex_try() interface returns SQLITE_OK -** upon successful entry. {F17026} Mutexes created using +** SQLITE_BUSY. {H17025} The sqlite3_mutex_try() interface returns [SQLITE_OK] +** upon successful entry. {H17026} Mutexes created using ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread. -** {F17027} In such cases the, +** {H17027} In such cases the, ** mutex must be exited an equal number of times before another thread -** can enter. {U17028} If the same thread tries to enter any other +** can enter. {A17028} If the same thread tries to enter any other ** kind of mutex more than once, the behavior is undefined. -** {F17029} SQLite will never exhibit -** such behavior in its own use of mutexes. {END} +** {H17029} SQLite will never exhibit +** such behavior in its own use of mutexes. ** -** Some systems (ex: windows95) do not the operation implemented by -** sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() will -** always return SQLITE_BUSY. {F17030} The SQLite core only ever uses -** sqlite3_mutex_try() as an optimization so this is acceptable behavior. {END} +** Some systems (for example, Windows 95) do not support the operation +** implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() +** will always return SQLITE_BUSY. {H17030} The SQLite core only ever uses +** sqlite3_mutex_try() as an optimization so this is acceptable behavior. ** -** {F17031} The sqlite3_mutex_leave() routine exits a mutex that was -** previously entered by the same thread. {U17032} The behavior +** {H17031} The sqlite3_mutex_leave() routine exits a mutex that was +** previously entered by the same thread. {A17032} The behavior ** is undefined if the mutex is not currently entered by the -** calling thread or is not currently allocated. {F17033} SQLite will +** calling thread or is not currently allocated. {H17033} SQLite will ** never do either. {END} ** +** If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or +** sqlite3_mutex_leave() is a NULL pointer, then all three routines +** behave as no-ops. +** ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()]. */ SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int); @@ -5916,44 +6379,110 @@ SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*); SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*); /* -** CAPI3REF: Mutex Verifcation Routines {F17080} +** CAPI3REF: Mutex Methods Object {H17120} <S20130> +** EXPERIMENTAL +** +** An instance of this structure defines the low-level routines +** used to allocate and use mutexes. +** +** Usually, the default mutex implementations provided by SQLite are +** sufficient, however the user has the option of substituting a custom +** implementation for specialized deployments or systems for which SQLite +** does not provide a suitable implementation. In this case, the user +** creates and populates an instance of this structure to pass +** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option. +** Additionally, an instance of this structure can be used as an +** output variable when querying the system for the current mutex +** implementation, using the [SQLITE_CONFIG_GETMUTEX] option. +** +** The xMutexInit method defined by this structure is invoked as +** part of system initialization by the sqlite3_initialize() function. +** {H17001} The xMutexInit routine shall be called by SQLite once for each +** effective call to [sqlite3_initialize()]. +** +** The xMutexEnd method defined by this structure is invoked as +** part of system shutdown by the sqlite3_shutdown() function. The +** implementation of this method is expected to release all outstanding +** resources obtained by the mutex methods implementation, especially +** those obtained by the xMutexInit method. {H17003} The xMutexEnd() +** interface shall be invoked once for each call to [sqlite3_shutdown()]. +** +** The remaining seven methods defined by this structure (xMutexAlloc, +** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and +** xMutexNotheld) implement the following interfaces (respectively): +** +** <ul> +** <li> [sqlite3_mutex_alloc()] </li> +** <li> [sqlite3_mutex_free()] </li> +** <li> [sqlite3_mutex_enter()] </li> +** <li> [sqlite3_mutex_try()] </li> +** <li> [sqlite3_mutex_leave()] </li> +** <li> [sqlite3_mutex_held()] </li> +** <li> [sqlite3_mutex_notheld()] </li> +** </ul> +** +** The only difference is that the public sqlite3_XXX functions enumerated +** above silently ignore any invocations that pass a NULL pointer instead +** of a valid mutex handle. The implementations of the methods defined +** by this structure are not required to handle this case, the results +** of passing a NULL pointer instead of a valid mutex handle are undefined +** (i.e. it is acceptable to provide an implementation that segfaults if +** it is passed a NULL pointer). +*/ +typedef struct sqlite3_mutex_methods sqlite3_mutex_methods; +struct sqlite3_mutex_methods { + int (*xMutexInit)(void); + int (*xMutexEnd)(void); + sqlite3_mutex *(*xMutexAlloc)(int); + void (*xMutexFree)(sqlite3_mutex *); + void (*xMutexEnter)(sqlite3_mutex *); + int (*xMutexTry)(sqlite3_mutex *); + void (*xMutexLeave)(sqlite3_mutex *); + int (*xMutexHeld)(sqlite3_mutex *); + int (*xMutexNotheld)(sqlite3_mutex *); +}; + +/* +** CAPI3REF: Mutex Verification Routines {H17080} <S20130> <S30800> ** ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines -** are intended for use inside assert() statements. {F17081} The SQLite core +** are intended for use inside assert() statements. {H17081} The SQLite core ** never uses these routines except inside an assert() and applications -** are advised to follow the lead of the core. {F17082} The core only +** are advised to follow the lead of the core. {H17082} The core only ** provides implementations for these routines when it is compiled -** with the SQLITE_DEBUG flag. {U17087} External mutex implementations +** with the SQLITE_DEBUG flag. {A17087} External mutex implementations ** are only required to provide these routines if SQLITE_DEBUG is ** defined and if NDEBUG is not defined. ** -** {F17083} These routines should return true if the mutex in their argument -** is held or not held, respectively, by the calling thread. {END} +** {H17083} These routines should return true if the mutex in their argument +** is held or not held, respectively, by the calling thread. ** ** {X17084} The implementation is not required to provided versions of these -** routines that actually work. -** If the implementation does not provide working -** versions of these routines, it should at least provide stubs -** that always return true so that one does not get spurious -** assertion failures. {END} +** routines that actually work. If the implementation does not provide working +** versions of these routines, it should at least provide stubs that always +** return true so that one does not get spurious assertion failures. ** -** {F17085} If the argument to sqlite3_mutex_held() is a NULL pointer then +** {H17085} If the argument to sqlite3_mutex_held() is a NULL pointer then ** the routine should return 1. {END} This seems counter-intuitive since ** clearly the mutex cannot be held if it does not exist. But the ** the reason the mutex does not exist is because the build is not ** using mutexes. And we do not want the assert() containing the ** call to sqlite3_mutex_held() to fail, so a non-zero return is -** the appropriate thing to do. {F17086} The sqlite3_mutex_notheld() +** the appropriate thing to do. {H17086} The sqlite3_mutex_notheld() ** interface should also return 1 when given a NULL pointer. */ SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*); SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*); /* -** CAPI3REF: Mutex Types {F17001} +** CAPI3REF: Mutex Types {H17001} <H17000> ** -** {F17002} The [sqlite3_mutex_alloc()] interface takes a single argument -** which is one of these integer constants. {END} +** The [sqlite3_mutex_alloc()] interface takes a single argument +** which is one of these integer constants. +** +** The set of static mutexes may change from one SQLite release to the +** next. Applications that override the built-in mutex logic must be +** prepared to accommodate additional static mutexes. */ #define SQLITE_MUTEX_FAST 0 #define SQLITE_MUTEX_RECURSIVE 1 @@ -5965,24 +6494,24 @@ SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*); #define SQLITE_MUTEX_STATIC_LRU2 7 /* lru page list */ /* -** CAPI3REF: Low-Level Control Of Database Files {F11300} +** CAPI3REF: Low-Level Control Of Database Files {H11300} <S30800> ** -** {F11301} The [sqlite3_file_control()] interface makes a direct call to the +** {H11301} The [sqlite3_file_control()] interface makes a direct call to the ** xFileControl method for the [sqlite3_io_methods] object associated -** with a particular database identified by the second argument. {F11302} The +** with a particular database identified by the second argument. {H11302} The ** name of the database is the name assigned to the database by the ** <a href="lang_attach.html">ATTACH</a> SQL command that opened the -** database. {F11303} To control the main database file, use the name "main" -** or a NULL pointer. {F11304} The third and fourth parameters to this routine +** database. {H11303} To control the main database file, use the name "main" +** or a NULL pointer. {H11304} The third and fourth parameters to this routine ** are passed directly through to the second and third parameters of -** the xFileControl method. {F11305} The return value of the xFileControl +** the xFileControl method. {H11305} The return value of the xFileControl ** method becomes the return value of this routine. ** -** {F11306} If the second parameter (zDbName) does not match the name of any -** open database file, then SQLITE_ERROR is returned. {F11307} This error +** {H11306} If the second parameter (zDbName) does not match the name of any +** open database file, then SQLITE_ERROR is returned. {H11307} This error ** code is not remembered and will not be recalled by [sqlite3_errcode()] -** or [sqlite3_errmsg()]. {U11308} The underlying xFileControl method might -** also return SQLITE_ERROR. {U11309} There is no way to distinguish between +** or [sqlite3_errmsg()]. {A11308} The underlying xFileControl method might +** also return SQLITE_ERROR. {A11309} There is no way to distinguish between ** an incorrect zDbName and an SQLITE_ERROR return from the underlying ** xFileControl method. {END} ** @@ -5991,11 +6520,11 @@ SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*); SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); /* -** CAPI3REF: Testing Interface {F11400} +** CAPI3REF: Testing Interface {H11400} <S30800> ** ** The sqlite3_test_control() interface is used to read out internal ** state of SQLite and to inject faults into SQLite for testing -** purposes. The first parameter a operation code that determines +** purposes. The first parameter is an operation code that determines ** the number, meaning, and operation of all subsequent parameters. ** ** This interface is not for use by applications. It exists solely @@ -6010,25 +6539,175 @@ SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void* SQLITE_API int sqlite3_test_control(int op, ...); /* -** CAPI3REF: Testing Interface Operation Codes {F11410} +** CAPI3REF: Testing Interface Operation Codes {H11410} <H11400> ** ** These constants are the valid operation code parameters used ** as the first argument to [sqlite3_test_control()]. ** -** These parameters and their meansing are subject to change +** These parameters and their meanings are subject to change ** without notice. These values are for testing purposes only. ** Applications should not use any of these parameters or the ** [sqlite3_test_control()] interface. */ -#define SQLITE_TESTCTRL_FAULT_CONFIG 1 -#define SQLITE_TESTCTRL_FAULT_FAILURES 2 -#define SQLITE_TESTCTRL_FAULT_BENIGN_FAILURES 3 -#define SQLITE_TESTCTRL_FAULT_PENDING 4 #define SQLITE_TESTCTRL_PRNG_SAVE 5 #define SQLITE_TESTCTRL_PRNG_RESTORE 6 #define SQLITE_TESTCTRL_PRNG_RESET 7 #define SQLITE_TESTCTRL_BITVEC_TEST 8 +#define SQLITE_TESTCTRL_FAULT_INSTALL 9 +#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 +/* +** CAPI3REF: SQLite Runtime Status {H17200} <S60200> +** EXPERIMENTAL +** +** This interface is used to retrieve runtime status information +** about the preformance of SQLite, and optionally to reset various +** highwater marks. The first argument is an integer code for +** the specific parameter to measure. Recognized integer codes +** are of the form [SQLITE_STATUS_MEMORY_USED | SQLITE_STATUS_...]. +** The current value of the parameter is returned into *pCurrent. +** The highest recorded value is returned in *pHighwater. If the +** resetFlag is true, then the highest record value is reset after +** *pHighwater is written. Some parameters do not record the highest +** value. For those parameters +** nothing is written into *pHighwater and the resetFlag is ignored. +** Other parameters record only the highwater mark and not the current +** value. For these latter parameters nothing is written into *pCurrent. +** +** This routine returns SQLITE_OK on success and a non-zero +** [error code] on failure. +** +** This routine is threadsafe but is not atomic. This routine can +** called while other threads are running the same or different SQLite +** interfaces. However the values returned in *pCurrent and +** *pHighwater reflect the status of SQLite at different points in time +** and it is possible that another thread might change the parameter +** in between the times when *pCurrent and *pHighwater are written. +** +** See also: [sqlite3_db_status()] +*/ +SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag); + +/* +** CAPI3REF: Database Connection Status {H17201} <S60200> +** EXPERIMENTAL +** +** This interface is used to retrieve runtime status information +** about a single [database connection]. The first argument is the +** database connection object to be interrogated. The second argument +** is the parameter to interrogate. Currently, the only allowed value +** for the second parameter is [SQLITE_DBSTATUS_LOOKASIDE_USED]. +** Additional options will likely appear in future releases of SQLite. +** +** The current value of the request parameter is written into *pCur +** and the highest instantaneous value is written into *pHiwtr. If +** the resetFlg is true, then the highest instantaneous value is +** reset back down to the current value. +** +** See also: [sqlite3_status()]. +*/ +SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg); + +/* +** CAPI3REF: Status Parameters {H17250} <H17200> +** EXPERIMENTAL +** +** These integer constants designate various run-time status parameters +** that can be returned by [sqlite3_status()]. +** +** <dl> +** <dt>SQLITE_STATUS_MEMORY_USED</dt> +** <dd>This parameter is the current amount of memory checked out +** using [sqlite3_malloc()], either directly or indirectly. The +** figure includes calls made to [sqlite3_malloc()] by the application +** and internal memory usage by the SQLite library. Scratch memory +** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache +** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in +** this parameter. The amount returned is the sum of the allocation +** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd> +** +** <dt>SQLITE_STATUS_MALLOC_SIZE</dt> +** <dd>This parameter records the largest memory allocation request +** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their +** internal equivalents). Only the value returned in the +** *pHighwater parameter to [sqlite3_status()] is of interest. +** The value written into the *pCurrent parameter is undefined.</dd> +** +** <dt>SQLITE_STATUS_PAGECACHE_USED</dt> +** <dd>This parameter returns the number of pages used out of the +** [pagecache memory allocator] that was configured using +** [SQLITE_CONFIG_PAGECACHE]. The +** value returned is in pages, not in bytes.</dd> +** +** <dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt> +** <dd>This parameter returns the number of bytes of page cache +** allocation which could not be statisfied by the [SQLITE_CONFIG_PAGECACHE] +** buffer and where forced to overflow to [sqlite3_malloc()]. The +** returned value includes allocations that overflowed because they +** where too large (they were larger than the "sz" parameter to +** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because +** no space was left in the page cache.</dd> +** +** <dt>SQLITE_STATUS_PAGECACHE_SIZE</dt> +** <dd>This parameter records the largest memory allocation request +** handed to [pagecache memory allocator]. Only the value returned in the +** *pHighwater parameter to [sqlite3_status()] is of interest. +** The value written into the *pCurrent parameter is undefined.</dd> +** +** <dt>SQLITE_STATUS_SCRATCH_USED</dt> +** <dd>This parameter returns the number of allocations used out of the +** [scratch memory allocator] configured using +** [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not +** in bytes. Since a single thread may only have one scratch allocation +** outstanding at time, this parameter also reports the number of threads +** using scratch memory at the same time.</dd> +** +** <dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt> +** <dd>This parameter returns the number of bytes of scratch memory +** allocation which could not be statisfied by the [SQLITE_CONFIG_SCRATCH] +** buffer and where forced to overflow to [sqlite3_malloc()]. The values +** returned include overflows because the requested allocation was too +** larger (that is, because the requested allocation was larger than the +** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer +** slots were available. +** </dd> +** +** <dt>SQLITE_STATUS_SCRATCH_SIZE</dt> +** <dd>This parameter records the largest memory allocation request +** handed to [scratch memory allocator]. Only the value returned in the +** *pHighwater parameter to [sqlite3_status()] is of interest. +** The value written into the *pCurrent parameter is undefined.</dd> +** +** <dt>SQLITE_STATUS_PARSER_STACK</dt> +** <dd>This parameter records the deepest parser stack. It is only +** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd> +** </dl> +** +** New status parameters may be added from time to time. +*/ +#define SQLITE_STATUS_MEMORY_USED 0 +#define SQLITE_STATUS_PAGECACHE_USED 1 +#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2 +#define SQLITE_STATUS_SCRATCH_USED 3 +#define SQLITE_STATUS_SCRATCH_OVERFLOW 4 +#define SQLITE_STATUS_MALLOC_SIZE 5 +#define SQLITE_STATUS_PARSER_STACK 6 +#define SQLITE_STATUS_PAGECACHE_SIZE 7 +#define SQLITE_STATUS_SCRATCH_SIZE 8 + +/* +** CAPI3REF: Status Parameters for database connections {H17275} <H17200> +** EXPERIMENTAL +** +** Status verbs for [sqlite3_db_status()]. +** +** <dl> +** <dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt> +** <dd>This parameter returns the number of lookaside memory slots currently +** checked out.</dd> +** </dl> +*/ +#define SQLITE_DBSTATUS_LOOKASIDE_USED 0 /* ** Undo the hack that converts floating point types to integer for @@ -6378,11 +7057,11 @@ SQLITE_PRIVATE void sqlite3HashClear(Hash*); #endif /* -** Provide a default value for TEMP_STORE in case it is not specified +** Provide a default value for SQLITE_TEMP_STORE in case it is not specified ** on the command-line */ -#ifndef TEMP_STORE -# define TEMP_STORE 1 +#ifndef SQLITE_TEMP_STORE +# define SQLITE_TEMP_STORE 1 #endif /* @@ -6524,6 +7203,12 @@ struct BusyHandler { #define ArraySize(X) (sizeof(X)/sizeof(X[0])) /* +** The following value as a destructor means to use sqlite3DbFree(). +** This is an internal extension to SQLITE_STATIC and SQLITE_TRANSIENT. +*/ +#define SQLITE_DYNAMIC ((sqlite3_destructor_type)sqlite3DbFree) + +/* ** Forward references to structures */ typedef struct AggInfo AggInfo; @@ -6541,6 +7226,8 @@ typedef struct IdList IdList; typedef struct Index Index; typedef struct KeyClass KeyClass; typedef struct KeyInfo KeyInfo; +typedef struct Lookaside Lookaside; +typedef struct LookasideSlot LookasideSlot; typedef struct Module Module; typedef struct NameContext NameContext; typedef struct Parse Parse; @@ -6641,11 +7328,6 @@ SQLITE_PRIVATE int sqlite3BtreeOpen( #define BTREE_READWRITE 16 /* Open for both reading and writing */ #define BTREE_CREATE 32 /* Create the database if it does not exist */ -/* Additional values for the 4th argument of sqlite3BtreeOpen that -** are not associated with PAGER_ values. -*/ -#define BTREE_PRIVATE 64 /* Never share with other connections */ - SQLITE_PRIVATE int sqlite3BtreeClose(Btree*); SQLITE_PRIVATE int sqlite3BtreeSetCacheSize(Btree*,int); SQLITE_PRIVATE int sqlite3BtreeSetSafetyLevel(Btree*,int,int); @@ -6712,6 +7394,7 @@ SQLITE_PRIVATE int sqlite3BtreeMoveto( int bias, int *pRes ); +SQLITE_PRIVATE int sqlite3BtreeCursorHasMoved(BtCursor*, int*); SQLITE_PRIVATE int sqlite3BtreeDelete(BtCursor*); SQLITE_PRIVATE int sqlite3BtreeInsert(BtCursor*, const void *pKey, i64 nKey, const void *pData, int nData, @@ -6739,7 +7422,6 @@ SQLITE_PRIVATE void sqlite3BtreeCacheOverflow(BtCursor *); #ifdef SQLITE_TEST SQLITE_PRIVATE int sqlite3BtreeCursorInfo(BtCursor*, int*, int); SQLITE_PRIVATE void sqlite3BtreeCursorList(Btree*); -SQLITE_PRIVATE int sqlite3BtreePageDump(Btree*, int, int recursive); #endif /* @@ -6750,24 +7432,36 @@ SQLITE_PRIVATE int sqlite3BtreePageDump(Btree*, int, int recursive); #if !defined(SQLITE_OMIT_SHARED_CACHE) && SQLITE_THREADSAFE SQLITE_PRIVATE void sqlite3BtreeEnter(Btree*); SQLITE_PRIVATE void sqlite3BtreeLeave(Btree*); +#ifndef NDEBUG + /* This routine is used inside assert() statements only. */ SQLITE_PRIVATE int sqlite3BtreeHoldsMutex(Btree*); +#endif SQLITE_PRIVATE void sqlite3BtreeEnterCursor(BtCursor*); SQLITE_PRIVATE void sqlite3BtreeLeaveCursor(BtCursor*); SQLITE_PRIVATE void sqlite3BtreeEnterAll(sqlite3*); SQLITE_PRIVATE void sqlite3BtreeLeaveAll(sqlite3*); +#ifndef NDEBUG + /* This routine is used inside assert() statements only. */ SQLITE_PRIVATE int sqlite3BtreeHoldsAllMutexes(sqlite3*); +#endif SQLITE_PRIVATE void sqlite3BtreeMutexArrayEnter(BtreeMutexArray*); SQLITE_PRIVATE void sqlite3BtreeMutexArrayLeave(BtreeMutexArray*); SQLITE_PRIVATE void sqlite3BtreeMutexArrayInsert(BtreeMutexArray*, Btree*); #else # define sqlite3BtreeEnter(X) # define sqlite3BtreeLeave(X) +#ifndef NDEBUG + /* This routine is used inside assert() statements only. */ # define sqlite3BtreeHoldsMutex(X) 1 +#endif # define sqlite3BtreeEnterCursor(X) # define sqlite3BtreeLeaveCursor(X) # define sqlite3BtreeEnterAll(X) # define sqlite3BtreeLeaveAll(X) +#ifndef NDEBUG + /* This routine is used inside assert() statements only. */ # define sqlite3BtreeHoldsAllMutexes(X) 1 +#endif # define sqlite3BtreeMutexArrayEnter(X) # define sqlite3BtreeMutexArrayLeave(X) # define sqlite3BtreeMutexArrayInsert(X,Y) @@ -6842,13 +7536,14 @@ struct VdbeOp { Mem *pMem; /* Used when p4type is P4_MEM */ sqlite3_vtab *pVtab; /* Used when p4type is P4_VTAB */ KeyInfo *pKeyInfo; /* Used when p4type is P4_KEYINFO */ + int *ai; /* Used when p4type is P4_INTARRAY */ } p4; #ifdef SQLITE_DEBUG - char *zComment; /* Comment to improve readability */ + char *zComment; /* Comment to improve readability */ #endif #ifdef VDBE_PROFILE - int cnt; /* Number of times this instruction was executed */ - long long cycles; /* Total time spend executing this instruction */ + int cnt; /* Number of times this instruction was executed */ + u64 cycles; /* Total time spent executing this instruction */ #endif }; typedef struct VdbeOp VdbeOp; @@ -6882,6 +7577,7 @@ typedef struct VdbeOpList VdbeOpList; #define P4_REAL (-12) /* P4 is a 64-bit floating point value */ #define P4_INT64 (-13) /* P4 is a 64-bit signed integer */ #define P4_INT32 (-14) /* P4 is a 32-bit signed integer */ +#define P4_INTARRAY (-15) /* P4 is a vector of 32-bit integers */ /* When adding a P4 argument using P4_KEYINFO, a copy of the KeyInfo structure ** is made. That copy is freed when the Vdbe is finalized. But if the @@ -6890,7 +7586,8 @@ typedef struct VdbeOpList VdbeOpList; ** from a single sqliteMalloc(). But no copy is made and the calling ** function should *not* try to free the KeyInfo. */ -#define P4_KEYINFO_HANDOFF (-9) +#define P4_KEYINFO_HANDOFF (-16) +#define P4_KEYINFO_STATIC (-17) /* ** The Vdbe.aColName array contains 5n Mem structures, where n is the @@ -6949,121 +7646,121 @@ typedef struct VdbeOpList VdbeOpList; #define OP_Expire 14 #define OP_AutoCommit 15 #define OP_Gt 69 /* same as TK_GT */ -#define OP_IntegrityCk 17 -#define OP_Sort 18 -#define OP_Copy 19 -#define OP_Trace 20 -#define OP_Function 21 -#define OP_IfNeg 22 +#define OP_Pagecount 17 +#define OP_IntegrityCk 18 +#define OP_Sort 19 +#define OP_Copy 20 +#define OP_Trace 21 +#define OP_Function 22 +#define OP_IfNeg 23 #define OP_And 61 /* same as TK_AND */ #define OP_Subtract 79 /* same as TK_MINUS */ -#define OP_Noop 23 -#define OP_Return 24 +#define OP_Noop 24 +#define OP_Return 25 #define OP_Remainder 82 /* same as TK_REM */ -#define OP_NewRowid 25 +#define OP_NewRowid 26 #define OP_Multiply 80 /* same as TK_STAR */ -#define OP_Variable 26 -#define OP_String 27 -#define OP_RealAffinity 28 -#define OP_VRename 29 -#define OP_ParseSchema 30 -#define OP_VOpen 31 -#define OP_Close 32 -#define OP_CreateIndex 33 -#define OP_IsUnique 34 -#define OP_NotFound 35 -#define OP_Int64 36 -#define OP_MustBeInt 37 -#define OP_Halt 38 -#define OP_Rowid 39 -#define OP_IdxLT 40 -#define OP_AddImm 41 -#define OP_Statement 42 -#define OP_RowData 43 -#define OP_MemMax 44 +#define OP_Variable 27 +#define OP_String 28 +#define OP_RealAffinity 29 +#define OP_VRename 30 +#define OP_ParseSchema 31 +#define OP_VOpen 32 +#define OP_Close 33 +#define OP_CreateIndex 34 +#define OP_IsUnique 35 +#define OP_NotFound 36 +#define OP_Int64 37 +#define OP_MustBeInt 38 +#define OP_Halt 39 +#define OP_Rowid 40 +#define OP_IdxLT 41 +#define OP_AddImm 42 +#define OP_Statement 43 +#define OP_RowData 44 +#define OP_MemMax 45 #define OP_Or 60 /* same as TK_OR */ -#define OP_NotExists 45 -#define OP_Gosub 46 +#define OP_NotExists 46 +#define OP_Gosub 47 #define OP_Divide 81 /* same as TK_SLASH */ -#define OP_Integer 47 +#define OP_Integer 48 #define OP_ToNumeric 140 /* same as TK_TO_NUMERIC*/ -#define OP_Prev 48 +#define OP_Prev 49 #define OP_Concat 83 /* same as TK_CONCAT */ #define OP_BitAnd 74 /* same as TK_BITAND */ -#define OP_VColumn 49 -#define OP_CreateTable 50 -#define OP_Last 51 +#define OP_VColumn 50 +#define OP_CreateTable 51 +#define OP_Last 52 #define OP_IsNull 65 /* same as TK_ISNULL */ -#define OP_IncrVacuum 52 -#define OP_IdxRowid 53 +#define OP_IncrVacuum 53 +#define OP_IdxRowid 54 #define OP_ShiftRight 77 /* same as TK_RSHIFT */ -#define OP_ResetCount 54 -#define OP_FifoWrite 55 -#define OP_ContextPush 56 -#define OP_DropTrigger 57 -#define OP_DropIndex 58 -#define OP_IdxGE 59 -#define OP_IdxDelete 62 -#define OP_Vacuum 63 -#define OP_MoveLe 64 -#define OP_IfNot 73 -#define OP_DropTable 84 -#define OP_MakeRecord 85 +#define OP_ResetCount 55 +#define OP_FifoWrite 56 +#define OP_ContextPush 57 +#define OP_Yield 58 +#define OP_DropTrigger 59 +#define OP_DropIndex 62 +#define OP_IdxGE 63 +#define OP_IdxDelete 64 +#define OP_Vacuum 73 +#define OP_MoveLe 84 +#define OP_IfNot 85 +#define OP_DropTable 86 +#define OP_MakeRecord 89 #define OP_ToBlob 139 /* same as TK_TO_BLOB */ -#define OP_ResultRow 86 -#define OP_Delete 89 -#define OP_AggFinal 90 +#define OP_ResultRow 90 +#define OP_Delete 91 +#define OP_AggFinal 92 +#define OP_Compare 93 #define OP_ShiftLeft 76 /* same as TK_LSHIFT */ -#define OP_Goto 91 -#define OP_TableLock 92 -#define OP_FifoRead 93 -#define OP_Clear 94 -#define OP_MoveLt 95 +#define OP_Goto 94 +#define OP_TableLock 95 +#define OP_FifoRead 96 +#define OP_Clear 97 +#define OP_MoveLt 98 #define OP_Le 70 /* same as TK_LE */ -#define OP_VerifyCookie 96 -#define OP_AggStep 97 +#define OP_VerifyCookie 99 +#define OP_AggStep 100 #define OP_ToText 138 /* same as TK_TO_TEXT */ #define OP_Not 16 /* same as TK_NOT */ #define OP_ToReal 142 /* same as TK_TO_REAL */ -#define OP_SetNumColumns 98 -#define OP_Transaction 99 -#define OP_VFilter 100 +#define OP_SetNumColumns 101 +#define OP_Transaction 102 +#define OP_VFilter 103 #define OP_Ne 67 /* same as TK_NE */ -#define OP_VDestroy 101 -#define OP_ContextPop 102 +#define OP_VDestroy 104 +#define OP_ContextPop 105 #define OP_BitOr 75 /* same as TK_BITOR */ -#define OP_Next 103 -#define OP_IdxInsert 104 +#define OP_Next 106 +#define OP_IdxInsert 107 #define OP_Lt 71 /* same as TK_LT */ -#define OP_Insert 105 -#define OP_Destroy 106 -#define OP_ReadCookie 107 -#define OP_ForceInt 108 -#define OP_LoadAnalysis 109 -#define OP_Explain 110 -#define OP_OpenPseudo 111 -#define OP_OpenEphemeral 112 -#define OP_Null 113 -#define OP_Move 114 -#define OP_Blob 115 +#define OP_Insert 108 +#define OP_Destroy 109 +#define OP_ReadCookie 110 +#define OP_ForceInt 111 +#define OP_LoadAnalysis 112 +#define OP_Explain 113 +#define OP_OpenPseudo 114 +#define OP_OpenEphemeral 115 +#define OP_Null 116 +#define OP_Move 117 +#define OP_Blob 118 #define OP_Add 78 /* same as TK_PLUS */ -#define OP_Rewind 116 -#define OP_MoveGe 117 -#define OP_VBegin 118 -#define OP_VUpdate 119 -#define OP_IfZero 120 +#define OP_Rewind 119 +#define OP_MoveGe 120 +#define OP_VBegin 121 +#define OP_VUpdate 122 +#define OP_IfZero 123 #define OP_BitNot 87 /* same as TK_BITNOT */ -#define OP_VCreate 121 -#define OP_Found 122 -#define OP_IfPos 123 -#define OP_NullRow 124 +#define OP_VCreate 124 +#define OP_Found 126 +#define OP_IfPos 127 +#define OP_NullRow 128 +#define OP_Jump 129 +#define OP_Permutation 130 /* The following opcode values are never used */ -#define OP_NotUsed_126 126 -#define OP_NotUsed_127 127 -#define OP_NotUsed_128 128 -#define OP_NotUsed_129 129 -#define OP_NotUsed_130 130 #define OP_NotUsed_131 131 #define OP_NotUsed_132 132 #define OP_NotUsed_133 133 @@ -7086,21 +7783,21 @@ typedef struct VdbeOpList VdbeOpList; #define OPFLG_INITIALIZER {\ /* 0 */ 0x00, 0x01, 0x00, 0x00, 0x10, 0x02, 0x11, 0x00,\ /* 8 */ 0x00, 0x00, 0x05, 0x02, 0x00, 0x00, 0x00, 0x00,\ -/* 16 */ 0x04, 0x00, 0x01, 0x00, 0x00, 0x00, 0x05, 0x00,\ -/* 24 */ 0x00, 0x02, 0x02, 0x02, 0x04, 0x00, 0x00, 0x00,\ -/* 32 */ 0x00, 0x02, 0x11, 0x11, 0x02, 0x05, 0x00, 0x02,\ -/* 40 */ 0x11, 0x04, 0x00, 0x00, 0x0c, 0x11, 0x01, 0x02,\ -/* 48 */ 0x01, 0x00, 0x02, 0x01, 0x01, 0x02, 0x00, 0x04,\ -/* 56 */ 0x00, 0x00, 0x00, 0x11, 0x2c, 0x2c, 0x00, 0x00,\ -/* 64 */ 0x11, 0x05, 0x05, 0x15, 0x15, 0x15, 0x15, 0x15,\ -/* 72 */ 0x15, 0x05, 0x2c, 0x2c, 0x2c, 0x2c, 0x2c, 0x2c,\ -/* 80 */ 0x2c, 0x2c, 0x2c, 0x2c, 0x00, 0x00, 0x00, 0x04,\ -/* 88 */ 0x02, 0x00, 0x00, 0x01, 0x00, 0x01, 0x00, 0x11,\ -/* 96 */ 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x01,\ -/* 104 */ 0x08, 0x00, 0x02, 0x02, 0x05, 0x00, 0x00, 0x00,\ -/* 112 */ 0x00, 0x02, 0x00, 0x02, 0x01, 0x11, 0x00, 0x00,\ -/* 120 */ 0x05, 0x00, 0x11, 0x05, 0x00, 0x02, 0x00, 0x00,\ -/* 128 */ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,\ +/* 16 */ 0x04, 0x02, 0x00, 0x01, 0x00, 0x00, 0x00, 0x05,\ +/* 24 */ 0x00, 0x04, 0x02, 0x02, 0x02, 0x04, 0x00, 0x00,\ +/* 32 */ 0x00, 0x00, 0x02, 0x11, 0x11, 0x02, 0x05, 0x00,\ +/* 40 */ 0x02, 0x11, 0x04, 0x00, 0x00, 0x0c, 0x11, 0x01,\ +/* 48 */ 0x02, 0x01, 0x00, 0x02, 0x01, 0x01, 0x02, 0x00,\ +/* 56 */ 0x04, 0x00, 0x00, 0x00, 0x2c, 0x2c, 0x00, 0x11,\ +/* 64 */ 0x00, 0x05, 0x05, 0x15, 0x15, 0x15, 0x15, 0x15,\ +/* 72 */ 0x15, 0x00, 0x2c, 0x2c, 0x2c, 0x2c, 0x2c, 0x2c,\ +/* 80 */ 0x2c, 0x2c, 0x2c, 0x2c, 0x11, 0x05, 0x00, 0x04,\ +/* 88 */ 0x02, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00,\ +/* 96 */ 0x01, 0x00, 0x11, 0x00, 0x00, 0x00, 0x00, 0x01,\ +/* 104 */ 0x00, 0x00, 0x01, 0x08, 0x00, 0x02, 0x02, 0x05,\ +/* 112 */ 0x00, 0x00, 0x00, 0x00, 0x02, 0x00, 0x02, 0x01,\ +/* 120 */ 0x11, 0x00, 0x00, 0x05, 0x00, 0x02, 0x11, 0x05,\ +/* 128 */ 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,\ /* 136 */ 0x00, 0x00, 0x04, 0x04, 0x04, 0x04, 0x04,} /************** End of opcodes.h *********************************************/ @@ -7136,7 +7833,7 @@ SQLITE_PRIVATE int sqlite3VdbeCurrentAddr(Vdbe*); SQLITE_PRIVATE void sqlite3VdbeTrace(Vdbe*,FILE*); #endif SQLITE_PRIVATE void sqlite3VdbeResetStepResult(Vdbe*); -SQLITE_PRIVATE int sqlite3VdbeReset(Vdbe*, int); +SQLITE_PRIVATE int sqlite3VdbeReset(Vdbe*); SQLITE_PRIVATE void sqlite3VdbeSetNumCols(Vdbe*,int); SQLITE_PRIVATE int sqlite3VdbeSetColName(Vdbe*, int, int, const char *, int); SQLITE_PRIVATE void sqlite3VdbeCountChanges(Vdbe*); @@ -7155,8 +7852,11 @@ SQLITE_PRIVATE int sqlite3VdbeRecordCompare(int,const void*,UnpackedRecord*); #ifndef NDEBUG SQLITE_PRIVATE void sqlite3VdbeComment(Vdbe*, const char*, ...); # define VdbeComment(X) sqlite3VdbeComment X +SQLITE_PRIVATE void sqlite3VdbeNoopComment(Vdbe*, const char*, ...); +# define VdbeNoopComment(X) sqlite3VdbeNoopComment X #else # define VdbeComment(X) +# define VdbeNoopComment(X) #endif #endif @@ -7187,10 +7887,18 @@ SQLITE_PRIVATE void sqlite3VdbeComment(Vdbe*, const char*, ...); #define _PAGER_H_ /* +** If defined as non-zero, auto-vacuum is enabled by default. Otherwise +** it must be turned on for each database using "PRAGMA auto_vacuum = 1". +*/ +#ifndef SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT + #define SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT -1 +#endif + +/* ** The type used to represent a page number. The first page in a file ** is called page 1. 0 is used to represent "not a page". */ -typedef unsigned int Pgno; +typedef u32 Pgno; /* ** Each open file is managed by a separate instance of the "Pager" structure. @@ -7244,7 +7952,7 @@ SQLITE_PRIVATE DbPage *sqlite3PagerLookup(Pager *pPager, Pgno pgno); SQLITE_PRIVATE int sqlite3PagerRef(DbPage*); SQLITE_PRIVATE int sqlite3PagerUnref(DbPage*); SQLITE_PRIVATE int sqlite3PagerWrite(DbPage*); -SQLITE_PRIVATE int sqlite3PagerPagecount(Pager*); +SQLITE_PRIVATE int sqlite3PagerPagecount(Pager*, int*); SQLITE_PRIVATE int sqlite3PagerTruncate(Pager*,Pgno); SQLITE_PRIVATE int sqlite3PagerBegin(DbPage*, int exFlag); SQLITE_PRIVATE int sqlite3PagerCommitPhaseOne(Pager*,const char *zMaster, Pgno, int); @@ -7264,11 +7972,12 @@ SQLITE_PRIVATE sqlite3_file *sqlite3PagerFile(Pager*); SQLITE_PRIVATE const char *sqlite3PagerDirname(Pager*); SQLITE_PRIVATE const char *sqlite3PagerJournalname(Pager*); SQLITE_PRIVATE int sqlite3PagerNosync(Pager*); -SQLITE_PRIVATE int sqlite3PagerMovepage(Pager*,DbPage*,Pgno); +SQLITE_PRIVATE int sqlite3PagerMovepage(Pager*,DbPage*,Pgno,int); SQLITE_PRIVATE void *sqlite3PagerGetData(DbPage *); SQLITE_PRIVATE void *sqlite3PagerGetExtra(DbPage *); SQLITE_PRIVATE int sqlite3PagerLockingMode(Pager *, int); SQLITE_PRIVATE int sqlite3PagerJournalMode(Pager *, int); +SQLITE_PRIVATE i64 sqlite3PagerJournalSizeLimit(Pager *, i64); SQLITE_PRIVATE void *sqlite3PagerTempSpace(Pager*); SQLITE_PRIVATE int sqlite3PagerSync(Pager *pPager); @@ -7288,6 +7997,7 @@ SQLITE_PRIVATE int sqlite3PagerIswriteable(DbPage*); #ifdef SQLITE_TEST SQLITE_PRIVATE int *sqlite3PagerStats(Pager*); SQLITE_PRIVATE void sqlite3PagerRefdump(Pager*); +SQLITE_PRIVATE int sqlite3PagerIsMemdb(Pager*); #endif #ifdef SQLITE_TEST @@ -7323,6 +8033,8 @@ void enable_simulated_io_errors(void); ** ** This header file is #include-ed by sqliteInt.h and thus ends up ** being included by every source file. +** +** $Id$ */ #ifndef _SQLITE_OS_H_ #define _SQLITE_OS_H_ @@ -7330,56 +8042,66 @@ void enable_simulated_io_errors(void); /* ** Figure out if we are dealing with Unix, Windows, or some other ** operating system. After the following block of preprocess macros, -** all of OS_UNIX, OS_WIN, OS_OS2, and OS_OTHER will defined to either -** 1 or 0. One of the four will be 1. The other three will be 0. -*/ -#if defined(OS_OTHER) -# if OS_OTHER==1 -# undef OS_UNIX -# define OS_UNIX 0 -# undef OS_WIN -# define OS_WIN 0 -# undef OS_OS2 -# define OS_OS2 0 +** all of SQLITE_OS_UNIX, SQLITE_OS_WIN, SQLITE_OS_OS2, and SQLITE_OS_OTHER +** will defined to either 1 or 0. One of the four will be 1. The other +** three will be 0. +*/ +#if defined(SQLITE_OS_OTHER) +# if SQLITE_OS_OTHER==1 +# undef SQLITE_OS_UNIX +# define SQLITE_OS_UNIX 0 +# undef SQLITE_OS_WIN +# define SQLITE_OS_WIN 0 +# undef SQLITE_OS_OS2 +# define SQLITE_OS_OS2 0 # else -# undef OS_OTHER +# undef SQLITE_OS_OTHER # endif #endif -#if !defined(OS_UNIX) && !defined(OS_OTHER) -# define OS_OTHER 0 -# ifndef OS_WIN +#if !defined(SQLITE_OS_UNIX) && !defined(SQLITE_OS_OTHER) +# define SQLITE_OS_OTHER 0 +# ifndef SQLITE_OS_WIN # if defined(_WIN32) || defined(WIN32) || defined(__CYGWIN__) || defined(__MINGW32__) || defined(__BORLANDC__) -# define OS_WIN 1 -# define OS_UNIX 0 -# define OS_OS2 0 +# define SQLITE_OS_WIN 1 +# define SQLITE_OS_UNIX 0 +# define SQLITE_OS_OS2 0 # elif defined(__EMX__) || defined(_OS2) || defined(OS2) || defined(_OS2_) || defined(__OS2__) -# define OS_WIN 0 -# define OS_UNIX 0 -# define OS_OS2 1 +# define SQLITE_OS_WIN 0 +# define SQLITE_OS_UNIX 0 +# define SQLITE_OS_OS2 1 # else -# define OS_WIN 0 -# define OS_UNIX 1 -# define OS_OS2 0 +# define SQLITE_OS_WIN 0 +# define SQLITE_OS_UNIX 1 +# define SQLITE_OS_OS2 0 # endif # else -# define OS_UNIX 0 -# define OS_OS2 0 +# define SQLITE_OS_UNIX 0 +# define SQLITE_OS_OS2 0 # endif #else -# ifndef OS_WIN -# define OS_WIN 0 +# ifndef SQLITE_OS_WIN +# define SQLITE_OS_WIN 0 # endif #endif +/* +** Determine if we are dealing with WindowsCE - which has a much +** reduced API. +*/ +#if defined(_WIN32_WCE) +# define SQLITE_OS_WINCE 1 +#else +# define SQLITE_OS_WINCE 0 +#endif /* ** Define the maximum size of a temporary filename */ -#if OS_WIN +#if SQLITE_OS_WIN # include <windows.h> # define SQLITE_TEMPNAME_SIZE (MAX_PATH+50) -#elif OS_OS2 +#elif SQLITE_OS_OS2 # if (__GNUC__ > 3 || __GNUC__ == 3 && __GNUC_MINOR__ >= 3) && defined(OS2_HIGH_MEMORY) # include <os2safe.h> /* has to be included before os2.h for linking to work */ # endif @@ -7538,7 +8260,7 @@ SQLITE_PRIVATE int sqlite3OsSync(sqlite3_file*, int); SQLITE_PRIVATE int sqlite3OsFileSize(sqlite3_file*, i64 *pSize); SQLITE_PRIVATE int sqlite3OsLock(sqlite3_file*, int); SQLITE_PRIVATE int sqlite3OsUnlock(sqlite3_file*, int); -SQLITE_PRIVATE int sqlite3OsCheckReservedLock(sqlite3_file *id); +SQLITE_PRIVATE int sqlite3OsCheckReservedLock(sqlite3_file *id, int *pResOut); SQLITE_PRIVATE int sqlite3OsFileControl(sqlite3_file*,int,void*); SQLITE_PRIVATE int sqlite3OsSectorSize(sqlite3_file *id); SQLITE_PRIVATE int sqlite3OsDeviceCharacteristics(sqlite3_file *id); @@ -7548,13 +8270,14 @@ SQLITE_PRIVATE int sqlite3OsDeviceCharacteristics(sqlite3_file *id); */ SQLITE_PRIVATE int sqlite3OsOpen(sqlite3_vfs *, const char *, sqlite3_file*, int, int *); SQLITE_PRIVATE int sqlite3OsDelete(sqlite3_vfs *, const char *, int); -SQLITE_PRIVATE int sqlite3OsAccess(sqlite3_vfs *, const char *, int); -SQLITE_PRIVATE int sqlite3OsGetTempname(sqlite3_vfs *, int, char *); +SQLITE_PRIVATE int sqlite3OsAccess(sqlite3_vfs *, const char *, int, int *pResOut); SQLITE_PRIVATE int sqlite3OsFullPathname(sqlite3_vfs *, const char *, int, char *); +#ifndef SQLITE_OMIT_LOAD_EXTENSION SQLITE_PRIVATE void *sqlite3OsDlOpen(sqlite3_vfs *, const char *); SQLITE_PRIVATE void sqlite3OsDlError(sqlite3_vfs *, int, char *); SQLITE_PRIVATE void *sqlite3OsDlSym(sqlite3_vfs *, void *, const char *); SQLITE_PRIVATE void sqlite3OsDlClose(sqlite3_vfs *, void *); +#endif /* SQLITE_OMIT_LOAD_EXTENSION */ SQLITE_PRIVATE int sqlite3OsRandomness(sqlite3_vfs *, int, char *); SQLITE_PRIVATE int sqlite3OsSleep(sqlite3_vfs *, int); SQLITE_PRIVATE int sqlite3OsCurrentTime(sqlite3_vfs *, double*); @@ -7566,16 +8289,6 @@ SQLITE_PRIVATE int sqlite3OsCurrentTime(sqlite3_vfs *, double*); SQLITE_PRIVATE int sqlite3OsOpenMalloc(sqlite3_vfs *, const char *, sqlite3_file **, int,int*); SQLITE_PRIVATE int sqlite3OsCloseFree(sqlite3_file *); -/* -** Each OS-specific backend defines an instance of the following -** structure for returning a pointer to its sqlite3_vfs. If OS_OTHER -** is defined (meaning that the application-defined OS interface layer -** is used) then there is no default VFS. The application must -** register one or more VFS structures using sqlite3_vfs_register() -** before attempting to use SQLite. -*/ -SQLITE_PRIVATE sqlite3_vfs *sqlite3OsDefaultVfs(void); - #endif /* _SQLITE_OS_H_ */ /************** End of os.h **************************************************/ @@ -7637,15 +8350,15 @@ SQLITE_PRIVATE sqlite3_vfs *sqlite3OsDefaultVfs(void); # undef SQLITE_MUTEX_NOOP # define SQLITE_MUTEX_NOOP_DEBUG #endif -#if defined(SQLITE_MUTEX_NOOP) && SQLITE_THREADSAFE && OS_UNIX +#if defined(SQLITE_MUTEX_NOOP) && SQLITE_THREADSAFE && SQLITE_OS_UNIX # undef SQLITE_MUTEX_NOOP # define SQLITE_MUTEX_PTHREADS #endif -#if defined(SQLITE_MUTEX_NOOP) && SQLITE_THREADSAFE && OS_WIN +#if defined(SQLITE_MUTEX_NOOP) && SQLITE_THREADSAFE && SQLITE_OS_WIN # undef SQLITE_MUTEX_NOOP # define SQLITE_MUTEX_W32 #endif -#if defined(SQLITE_MUTEX_NOOP) && SQLITE_THREADSAFE && OS_OS2 +#if defined(SQLITE_MUTEX_NOOP) && SQLITE_THREADSAFE && SQLITE_OS_OS2 # undef SQLITE_MUTEX_NOOP # define SQLITE_MUTEX_OS2 #endif @@ -7661,6 +8374,9 @@ SQLITE_PRIVATE sqlite3_vfs *sqlite3OsDefaultVfs(void); #define sqlite3_mutex_leave(X) #define sqlite3_mutex_held(X) 1 #define sqlite3_mutex_notheld(X) 1 +#define sqlite3MutexAlloc(X) ((sqlite3_mutex*)8) +#define sqlite3MutexInit() SQLITE_OK +#define sqlite3MutexEnd() #endif #endif /* SQLITE_MUTEX_APPDEF */ @@ -7743,6 +8459,33 @@ struct Schema { #define SQLITE_N_LIMIT (SQLITE_LIMIT_VARIABLE_NUMBER+1) /* +** Lookaside malloc is a set of fixed-size buffers that can be used +** to satisify small transient memory allocation requests for objects +** associated with a particular database connection. The use of +** lookaside malloc provides a significant performance enhancement +** (approx 10%) by avoiding numerous malloc/free requests while parsing +** SQL statements. +** +** The Lookaside structure holds configuration information about the +** lookaside malloc subsystem. Each available memory allocation in +** the lookaside subsystem is stored on a linked list of LookasideSlot +** objects. +*/ +struct Lookaside { + u16 sz; /* Size of each buffer in bytes */ + u8 bEnabled; /* True if use lookaside. False to ignore it */ + u8 bMalloced; /* True if pStart obtained from sqlite3_malloc() */ + int nOut; /* Number of buffers currently checked out */ + int mxOut; /* Highwater mark for nOut */ + LookasideSlot *pFree; /* List if available buffers */ + void *pStart; /* First byte of available memory space */ + void *pEnd; /* First byte past end of available space */ +}; +struct LookasideSlot { + LookasideSlot *pNext; /* Next buffer in the list of free buffers */ +}; + +/* ** Each database is an instance of the following structure. ** ** The sqlite.lastRowid records the last insert rowid generated by an @@ -7821,6 +8564,7 @@ struct sqlite3 { int isInterrupted; /* True if sqlite3_interrupt has been called */ double notUsed1; /* Spacer */ } u1; + Lookaside lookaside; /* Lookaside malloc configuration */ #ifndef SQLITE_OMIT_AUTHORIZATION int (*xAuth)(void*,int,const char*,const char*,const char*,const char*); /* Access authorization function */ @@ -8027,8 +8771,7 @@ struct CollSeq { ** changing the affinity. */ #define SQLITE_JUMPIFNULL 0x08 /* jumps if either operand is NULL */ -#define SQLITE_NULLEQUAL 0x10 /* compare NULLs equal */ -#define SQLITE_STOREP2 0x80 /* Store result in reg[P2] rather than jump */ +#define SQLITE_STOREP2 0x10 /* Store result in reg[P2] rather than jump */ /* ** Each SQL table is represented in memory by an instance of the @@ -8061,6 +8804,7 @@ struct CollSeq { ** of a SELECT statement. */ struct Table { + sqlite3 *db; /* Associated database connection. Might be NULL. */ char *zName; /* Name of the table */ int nCol; /* Number of columns in this table */ Column *aCol; /* Information about each column */ @@ -8371,8 +9115,7 @@ struct Expr { Select *pSelect; /* When the expression is a sub-select. Also the ** right side of "<expr> IN (<select>)" */ Table *pTab; /* Table for OP_Column expressions. */ -/* Schema *pSchema; */ -#if defined(SQLITE_TEST) || SQLITE_MAX_EXPR_DEPTH>0 +#if SQLITE_MAX_EXPR_DEPTH>0 int nHeight; /* Height of the tree headed by this node */ #endif }; @@ -8391,7 +9134,7 @@ struct Expr { #define EP_ExpCollate 0x0100 /* Collating sequence specified explicitly */ #define EP_AnyAff 0x0200 /* Can take a cached column of any affinity */ #define EP_FixedDest 0x0400 /* Result needed in a specific register */ - +#define EP_IntValue 0x0800 /* Integer value contained in iTable */ /* ** These macros can be used to test, set, or clear bits in the ** Expr.flags field. @@ -8665,10 +9408,10 @@ struct Select { #define SRT_Callback 5 /* Invoke a callback with each row of result */ #define SRT_Mem 6 /* Store result in a memory cell */ -#define SRT_Set 7 /* Store non-null results as keys in an index */ +#define SRT_Set 7 /* Store results as keys in an index */ #define SRT_Table 8 /* Store result as data with an automatic rowid */ #define SRT_EphemTab 9 /* Create transient tab and store like SRT_Table */ -#define SRT_Subroutine 10 /* Call a subroutine to handle results */ +#define SRT_Coroutine 10 /* Generate a single row of result */ /* ** A structure used to customize the behaviour of sqlite3Select(). See @@ -8762,9 +9505,7 @@ struct Parse { int nVtabLock; /* Number of virtual tables to lock */ Table **apVtabLock; /* Pointer to virtual tables needing locking */ #endif -#if defined(SQLITE_TEST) || SQLITE_MAX_EXPR_DEPTH>0 int nHeight; /* Expression tree height of current sub-select */ -#endif }; #ifdef SQLITE_OMIT_VIRTUALTABLE @@ -8941,10 +9682,11 @@ struct DbFixer { ** do not necessarily know how big the string will be in the end. */ struct StrAccum { - char *zBase; /* A base allocation. Not from malloc. */ - char *zText; /* The string collected so far */ - int nChar; /* Length of the string so far */ - int nAlloc; /* Amount of space allocated in zText */ + sqlite3 *db; /* Optional database for lookaside. Can be NULL */ + char *zBase; /* A base allocation. Not from malloc. */ + char *zText; /* The string collected so far */ + int nChar; /* Length of the string so far */ + int nAlloc; /* Amount of space allocated in zText */ int mxAlloc; /* Maximum allowed string length */ u8 mallocFailed; /* Becomes true if any memory allocation fails */ u8 useMalloc; /* True if zText is enlargable using realloc */ @@ -8963,6 +9705,36 @@ typedef struct { } InitData; /* +** Structure containing global configuration data for the SQLite library. +** +** This structure also contains some state information. +*/ +struct Sqlite3Config { + int bMemstat; /* True to enable memory status */ + int bCoreMutex; /* True to enable core mutexing */ + int bFullMutex; /* True to enable full mutexing */ + int mxStrlen; /* Maximum string length */ + int szLookaside; /* Default lookaside buffer size */ + int nLookaside; /* Default lookaside buffer count */ + sqlite3_mem_methods m; /* Low-level memory allocation interface */ + sqlite3_mutex_methods mutex; /* Low-level mutex interface */ + void *pHeap; /* Heap storage space */ + int nHeap; /* Size of pHeap[] */ + int mnReq, mxReq; /* Min and max heap requests sizes */ + void *pScratch; /* Scratch memory */ + int szScratch; /* Size of each scratch buffer */ + int nScratch; /* Number of scratch buffers */ + void *pPage; /* Page cache memory */ + int szPage; /* Size of each page in pPage[] */ + int nPage; /* Number of pages in pPage[] */ + int isInit; /* True after initialization has finished */ + int isMallocInit; /* True after malloc is initialized */ + sqlite3_mutex *pInitMutex; /* Mutex used by sqlite3_initialize() */ + int nSmall; /* alloc size threshold used by mem6.c */ + int mxParserStack; /* maximum depth of the parser stack */ +}; + +/* ** Assuming zIn points to the first byte of a UTF-8 character, ** advance zIn to point to the first byte of the next UTF-8 character. */ @@ -8981,10 +9753,8 @@ typedef struct { #ifdef SQLITE_DEBUG SQLITE_PRIVATE int sqlite3Corrupt(void); # define SQLITE_CORRUPT_BKPT sqlite3Corrupt() -# define DEBUGONLY(X) X #else # define SQLITE_CORRUPT_BKPT SQLITE_CORRUPT -# define DEBUGONLY(X) #endif /* @@ -8993,29 +9763,58 @@ SQLITE_PRIVATE int sqlite3Corrupt(void); SQLITE_PRIVATE int sqlite3StrICmp(const char *, const char *); SQLITE_PRIVATE int sqlite3StrNICmp(const char *, const char *, int); SQLITE_PRIVATE int sqlite3IsNumber(const char*, int*, u8); - -SQLITE_PRIVATE void *sqlite3MallocZero(unsigned); -SQLITE_PRIVATE void *sqlite3DbMallocZero(sqlite3*, unsigned); -SQLITE_PRIVATE void *sqlite3DbMallocRaw(sqlite3*, unsigned); -SQLITE_PRIVATE char *sqlite3StrDup(const char*); -SQLITE_PRIVATE char *sqlite3StrNDup(const char*, int); +SQLITE_PRIVATE int sqlite3Strlen(sqlite3*, const char*); + +SQLITE_PRIVATE int sqlite3MallocInit(void); +SQLITE_PRIVATE void sqlite3MallocEnd(void); +SQLITE_PRIVATE void *sqlite3Malloc(int); +SQLITE_PRIVATE void *sqlite3MallocZero(int); +SQLITE_PRIVATE void *sqlite3DbMallocZero(sqlite3*, int); +SQLITE_PRIVATE void *sqlite3DbMallocRaw(sqlite3*, int); SQLITE_PRIVATE char *sqlite3DbStrDup(sqlite3*,const char*); SQLITE_PRIVATE char *sqlite3DbStrNDup(sqlite3*,const char*, int); +SQLITE_PRIVATE void *sqlite3Realloc(void*, int); SQLITE_PRIVATE void *sqlite3DbReallocOrFree(sqlite3 *, void *, int); SQLITE_PRIVATE void *sqlite3DbRealloc(sqlite3 *, void *, int); -SQLITE_PRIVATE int sqlite3MallocSize(void *); +SQLITE_PRIVATE void sqlite3DbFree(sqlite3*, void*); +SQLITE_PRIVATE int sqlite3MallocSize(void*); +SQLITE_PRIVATE int sqlite3DbMallocSize(sqlite3*, void*); +SQLITE_PRIVATE void *sqlite3ScratchMalloc(int); +SQLITE_PRIVATE void sqlite3ScratchFree(void*); +SQLITE_PRIVATE void *sqlite3PageMalloc(int); +SQLITE_PRIVATE void sqlite3PageFree(void*); +SQLITE_PRIVATE void sqlite3MemSetDefault(void); +SQLITE_PRIVATE const sqlite3_mem_methods *sqlite3MemGetDefault(void); +SQLITE_PRIVATE const sqlite3_mem_methods *sqlite3MemGetMemsys5(void); +SQLITE_PRIVATE const sqlite3_mem_methods *sqlite3MemGetMemsys3(void); +SQLITE_PRIVATE const sqlite3_mem_methods *sqlite3MemGetMemsys6(void); +SQLITE_PRIVATE void sqlite3BenignMallocHooks(void (*)(void), void (*)(void)); + +#ifndef SQLITE_MUTEX_NOOP +SQLITE_PRIVATE sqlite3_mutex_methods *sqlite3DefaultMutex(void); +SQLITE_PRIVATE sqlite3_mutex *sqlite3MutexAlloc(int); +SQLITE_PRIVATE int sqlite3MutexInit(void); +SQLITE_PRIVATE int sqlite3MutexEnd(void); +#endif + +SQLITE_PRIVATE void sqlite3StatusReset(void); +SQLITE_PRIVATE int sqlite3StatusValue(int); +SQLITE_PRIVATE void sqlite3StatusAdd(int, int); +SQLITE_PRIVATE void sqlite3StatusSet(int, int); SQLITE_PRIVATE int sqlite3IsNaN(double); +SQLITE_PRIVATE void sqlite3VXPrintf(StrAccum*, int, const char*, va_list); SQLITE_PRIVATE char *sqlite3MPrintf(sqlite3*,const char*, ...); SQLITE_PRIVATE char *sqlite3VMPrintf(sqlite3*,const char*, va_list); +SQLITE_PRIVATE char *sqlite3MAppendf(sqlite3*,char*,const char*,...); #if defined(SQLITE_TEST) || defined(SQLITE_DEBUG) SQLITE_PRIVATE void sqlite3DebugPrintf(const char*, ...); #endif #if defined(SQLITE_TEST) -SQLITE_PRIVATE void *sqlite3TextToPtr(const char*); +SQLITE_PRIVATE void *sqlite3TestTextToPtr(const char*); #endif -SQLITE_PRIVATE void sqlite3SetString(char **, ...); +SQLITE_PRIVATE void sqlite3SetString(char **, sqlite3*, const char*, ...); SQLITE_PRIVATE void sqlite3ErrorMsg(Parse*, const char*, ...); SQLITE_PRIVATE void sqlite3ErrorClear(Parse*); SQLITE_PRIVATE void sqlite3Dequote(char*); @@ -9034,9 +9833,9 @@ SQLITE_PRIVATE Expr *sqlite3ExprAnd(sqlite3*,Expr*, Expr*); SQLITE_PRIVATE void sqlite3ExprSpan(Expr*,Token*,Token*); SQLITE_PRIVATE Expr *sqlite3ExprFunction(Parse*,ExprList*, Token*); SQLITE_PRIVATE void sqlite3ExprAssignVarNumber(Parse*, Expr*); -SQLITE_PRIVATE void sqlite3ExprDelete(Expr*); +SQLITE_PRIVATE void sqlite3ExprDelete(sqlite3*, Expr*); SQLITE_PRIVATE ExprList *sqlite3ExprListAppend(Parse*,ExprList*,Expr*,Token*); -SQLITE_PRIVATE void sqlite3ExprListDelete(ExprList*); +SQLITE_PRIVATE void sqlite3ExprListDelete(sqlite3*, ExprList*); SQLITE_PRIVATE int sqlite3Init(sqlite3*, char**); SQLITE_PRIVATE int sqlite3InitCallback(void*, int, char**, char**); SQLITE_PRIVATE void sqlite3Pragma(Parse*,Token*,Token*,Token*,int); @@ -9081,15 +9880,15 @@ SQLITE_PRIVATE SrcList *sqlite3SrcListAppendFromTerm(Parse*, SrcList*, Token*, T Select*, Expr*, IdList*); SQLITE_PRIVATE void sqlite3SrcListShiftJoinType(SrcList*); SQLITE_PRIVATE void sqlite3SrcListAssignCursors(Parse*, SrcList*); -SQLITE_PRIVATE void sqlite3IdListDelete(IdList*); -SQLITE_PRIVATE void sqlite3SrcListDelete(SrcList*); +SQLITE_PRIVATE void sqlite3IdListDelete(sqlite3*, IdList*); +SQLITE_PRIVATE void sqlite3SrcListDelete(sqlite3*, SrcList*); SQLITE_PRIVATE void sqlite3CreateIndex(Parse*,Token*,Token*,SrcList*,ExprList*,int,Token*, Token*, int, int); SQLITE_PRIVATE void sqlite3DropIndex(Parse*, SrcList*, int); -SQLITE_PRIVATE int sqlite3Select(Parse*, Select*, SelectDest*, Select*, int, int*, char *aff); +SQLITE_PRIVATE int sqlite3Select(Parse*, Select*, SelectDest*, Select*, int, int*); SQLITE_PRIVATE Select *sqlite3SelectNew(Parse*,ExprList*,SrcList*,Expr*,ExprList*, Expr*,ExprList*,int,Expr*,Expr*); -SQLITE_PRIVATE void sqlite3SelectDelete(Select*); +SQLITE_PRIVATE void sqlite3SelectDelete(sqlite3*, Select*); SQLITE_PRIVATE Table *sqlite3SrcListLookup(Parse*, SrcList*); SQLITE_PRIVATE int sqlite3IsReadOnly(Parse*, Table*, int); SQLITE_PRIVATE void sqlite3OpenTable(Parse*, int iCur, int iDb, Table*, int); @@ -9098,7 +9897,8 @@ SQLITE_PRIVATE void sqlite3Update(Parse*, SrcList*, ExprList*, Expr*, int); SQLITE_PRIVATE WhereInfo *sqlite3WhereBegin(Parse*, SrcList*, Expr*, ExprList**, u8); SQLITE_PRIVATE void sqlite3WhereEnd(WhereInfo*); SQLITE_PRIVATE int sqlite3ExprCodeGetColumn(Parse*, Table*, int, int, int, int); -SQLITE_PRIVATE void sqlite3ExprCodeMove(Parse*, int, int); +SQLITE_PRIVATE void sqlite3ExprCodeMove(Parse*, int, int, int); +SQLITE_PRIVATE void sqlite3ExprCodeCopy(Parse*, int, int, int); SQLITE_PRIVATE void sqlite3ExprClearColumnCache(Parse*, int); SQLITE_PRIVATE void sqlite3ExprCacheAffinityChange(Parse*, int, int); SQLITE_PRIVATE int sqlite3ExprWritableRegister(Parse*,int,int); @@ -9177,17 +9977,17 @@ SQLITE_PRIVATE int sqlite3TriggersExist(Parse*, Table*, int, ExprList*); SQLITE_PRIVATE int sqlite3CodeRowTrigger(Parse*, int, ExprList*, int, Table *, int, int, int, int, u32*, u32*); void sqliteViewTriggers(Parse*, Table*, Expr*, int, ExprList*); -SQLITE_PRIVATE void sqlite3DeleteTriggerStep(TriggerStep*); +SQLITE_PRIVATE void sqlite3DeleteTriggerStep(sqlite3*, TriggerStep*); SQLITE_PRIVATE TriggerStep *sqlite3TriggerSelectStep(sqlite3*,Select*); SQLITE_PRIVATE TriggerStep *sqlite3TriggerInsertStep(sqlite3*,Token*, IdList*, ExprList*,Select*,int); SQLITE_PRIVATE TriggerStep *sqlite3TriggerUpdateStep(sqlite3*,Token*,ExprList*, Expr*, int); SQLITE_PRIVATE TriggerStep *sqlite3TriggerDeleteStep(sqlite3*,Token*, Expr*); -SQLITE_PRIVATE void sqlite3DeleteTrigger(Trigger*); +SQLITE_PRIVATE void sqlite3DeleteTrigger(sqlite3*, Trigger*); SQLITE_PRIVATE void sqlite3UnlinkAndDeleteTrigger(sqlite3*,int,const char*); #else # define sqlite3TriggersExist(A,B,C,D,E,F) 0 -# define sqlite3DeleteTrigger(A) +# define sqlite3DeleteTrigger(A,B) # define sqlite3DropTriggerPtr(A,B) # define sqlite3UnlinkAndDeleteTrigger(A,B,C) # define sqlite3CodeRowTrigger(A,B,C,D,E,F,G,H,I,J,K) 0 @@ -9291,6 +10091,7 @@ SQLITE_PRIVATE int sqlite3ValueFromExpr(sqlite3 *, Expr *, u8, u8, sqlite3_value SQLITE_PRIVATE void sqlite3ValueApplyAffinity(sqlite3_value *, u8, u8); #ifndef SQLITE_AMALGAMATION SQLITE_PRIVATE const unsigned char sqlite3UpperToLower[]; +SQLITE_PRIVATE struct Sqlite3Config sqlite3Config; #endif SQLITE_PRIVATE void sqlite3RootPageMoved(Db*, int, int); SQLITE_PRIVATE void sqlite3Reindex(Parse*, Token*, Token*); @@ -9299,7 +10100,7 @@ SQLITE_PRIVATE void sqlite3AlterRenameTable(Parse*, SrcList*, Token*); SQLITE_PRIVATE int sqlite3GetToken(const unsigned char *, int *); SQLITE_PRIVATE void sqlite3NestedParse(Parse*, const char*, ...); SQLITE_PRIVATE void sqlite3ExpirePreparedStatements(sqlite3*); -SQLITE_PRIVATE void sqlite3CodeSubselect(Parse *, Expr *); +SQLITE_PRIVATE void sqlite3CodeSubselect(Parse *, Expr *, int); SQLITE_PRIVATE int sqlite3SelectResolve(Parse *, Select *, NameContext *); SQLITE_PRIVATE void sqlite3ColumnDefault(Vdbe *, Table *, int); SQLITE_PRIVATE void sqlite3AlterFinishAddColumn(Parse *, Token *); @@ -9325,6 +10126,7 @@ SQLITE_PRIVATE int sqlite3CreateFunc(sqlite3 *, const char *, int, int, void *, SQLITE_PRIVATE int sqlite3ApiExit(sqlite3 *db, int); SQLITE_PRIVATE int sqlite3OpenTempDatabase(Parse *); +SQLITE_PRIVATE void sqlite3StrAccumInit(StrAccum*, char*, int, int); SQLITE_PRIVATE void sqlite3StrAccumAppend(StrAccum*,const char*,int); SQLITE_PRIVATE char *sqlite3StrAccumFinish(StrAccum*); SQLITE_PRIVATE void sqlite3StrAccumReset(StrAccum*); @@ -9336,6 +10138,9 @@ SQLITE_PRIVATE void sqlite3SelectDestInit(SelectDest*,int,int); SQLITE_PRIVATE void *sqlite3ParserAlloc(void*(*)(size_t)); SQLITE_PRIVATE void sqlite3ParserFree(void*, void(*)(void*)); SQLITE_PRIVATE void sqlite3Parser(void*, int, Token, Parse*); +#ifdef YYTRACKMAXSTACKDEPTH +SQLITE_PRIVATE int sqlite3ParserStackPeak(void*); +#endif SQLITE_PRIVATE int sqlite3AutoLoadExtensions(sqlite3*); #ifndef SQLITE_OMIT_LOAD_EXTENSION @@ -9356,12 +10161,12 @@ SQLITE_PRIVATE int sqlite3Utf8To8(unsigned char*); #ifdef SQLITE_OMIT_VIRTUALTABLE # define sqlite3VtabClear(X) -# define sqlite3VtabSync(X,Y) (Y) +# define sqlite3VtabSync(X,Y) SQLITE_OK # define sqlite3VtabRollback(X) # define sqlite3VtabCommit(X) #else SQLITE_PRIVATE void sqlite3VtabClear(Table*); -SQLITE_PRIVATE int sqlite3VtabSync(sqlite3 *db, int rc); +SQLITE_PRIVATE int sqlite3VtabSync(sqlite3 *db, char **); SQLITE_PRIVATE int sqlite3VtabRollback(sqlite3 *db); SQLITE_PRIVATE int sqlite3VtabCommit(sqlite3 *db); #endif @@ -9390,34 +10195,22 @@ SQLITE_PRIVATE CollSeq *sqlite3BinaryCompareCollSeq(Parse *, Expr *, Expr *); #define SQLITE_FAULTINJECTOR_COUNT 1 /* -** The interface to the fault injector subsystem. If the fault injector -** mechanism is disabled at compile-time then set up macros so that no -** unnecessary code is generated. +** The interface to the code in fault.c used for identifying "benign" +** malloc failures. This is only present if SQLITE_OMIT_BUILTIN_TEST +** is not defined. */ #ifndef SQLITE_OMIT_BUILTIN_TEST -SQLITE_PRIVATE void sqlite3FaultConfig(int,int,int); -SQLITE_PRIVATE int sqlite3FaultFailures(int); -SQLITE_PRIVATE int sqlite3FaultBenignFailures(int); -SQLITE_PRIVATE int sqlite3FaultPending(int); -SQLITE_PRIVATE void sqlite3FaultBeginBenign(int); -SQLITE_PRIVATE void sqlite3FaultEndBenign(int); -SQLITE_PRIVATE int sqlite3FaultStep(int); +SQLITE_PRIVATE void sqlite3BeginBenignMalloc(void); +SQLITE_PRIVATE void sqlite3EndBenignMalloc(void); #else -# define sqlite3FaultConfig(A,B,C) -# define sqlite3FaultFailures(A) 0 -# define sqlite3FaultBenignFailures(A) 0 -# define sqlite3FaultPending(A) (-1) -# define sqlite3FaultBeginBenign(A) -# define sqlite3FaultEndBenign(A) -# define sqlite3FaultStep(A) 0 + #define sqlite3BeginBenignMalloc() + #define sqlite3EndBenignMalloc() #endif - - #define IN_INDEX_ROWID 1 #define IN_INDEX_EPH 2 #define IN_INDEX_INDEX 3 -SQLITE_PRIVATE int sqlite3FindInIndex(Parse *, Expr *, int); +SQLITE_PRIVATE int sqlite3FindInIndex(Parse *, Expr *, int*); #ifdef SQLITE_ENABLE_ATOMIC_WRITE SQLITE_PRIVATE int sqlite3JournalOpen(sqlite3_vfs *, const char *, sqlite3_file *, int, int); @@ -9427,11 +10220,12 @@ SQLITE_PRIVATE int sqlite3JournalCreate(sqlite3_file *); #define sqlite3JournalSize(pVfs) ((pVfs)->szOsFile) #endif -#if defined(SQLITE_TEST) || SQLITE_MAX_EXPR_DEPTH>0 -SQLITE_PRIVATE void sqlite3ExprSetHeight(Expr *); +#if SQLITE_MAX_EXPR_DEPTH>0 +SQLITE_PRIVATE void sqlite3ExprSetHeight(Parse *pParse, Expr *p); SQLITE_PRIVATE int sqlite3SelectExprHeight(Select *); #else - #define sqlite3ExprSetHeight(x) + #define sqlite3ExprSetHeight(x,y) + #define sqlite3SelectExprHeight(x) 0 #endif SQLITE_PRIVATE u32 sqlite3Get4byte(const u8*); @@ -9462,6 +10256,198 @@ SQLITE_PRIVATE void (*sqlite3IoTrace)(const char*,...); #endif /************** End of sqliteInt.h *******************************************/ +/************** Begin file global.c ******************************************/ +/* +** 2008 June 13 +** +** The author disclaims copyright to this source code. In place of +** a legal notice, here is a blessing: +** +** May you do good and not evil. +** May you find forgiveness for yourself and forgive others. +** May you share freely, never taking more than you give. +** +************************************************************************* +** +** This file contains definitions of global variables and contants. +** +** $Id$ +*/ + + +/* An array to map all upper-case characters into their corresponding +** lower-case character. +** +** SQLite only considers US-ASCII (or EBCDIC) characters. We do not +** handle case conversions for the UTF character set since the tables +** involved are nearly as big or bigger than SQLite itself. +*/ +SQLITE_PRIVATE const unsigned char sqlite3UpperToLower[] = { +#ifdef SQLITE_ASCII + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, + 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, + 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, + 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 97, 98, 99,100,101,102,103, + 104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121, + 122, 91, 92, 93, 94, 95, 96, 97, 98, 99,100,101,102,103,104,105,106,107, + 108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125, + 126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143, + 144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161, + 162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179, + 180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197, + 198,199,200,201,202,203,204,205,206,207,208,209,210,211,212,213,214,215, + 216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233, + 234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251, + 252,253,254,255 +#endif +#ifdef SQLITE_EBCDIC + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, /* 0x */ + 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, /* 1x */ + 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, /* 2x */ + 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, /* 3x */ + 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, /* 4x */ + 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, /* 5x */ + 96, 97, 66, 67, 68, 69, 70, 71, 72, 73,106,107,108,109,110,111, /* 6x */ + 112, 81, 82, 83, 84, 85, 86, 87, 88, 89,122,123,124,125,126,127, /* 7x */ + 128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143, /* 8x */ + 144,145,146,147,148,149,150,151,152,153,154,155,156,157,156,159, /* 9x */ + 160,161,162,163,164,165,166,167,168,169,170,171,140,141,142,175, /* Ax */ + 176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191, /* Bx */ + 192,129,130,131,132,133,134,135,136,137,202,203,204,205,206,207, /* Cx */ + 208,145,146,147,148,149,150,151,152,153,218,219,220,221,222,223, /* Dx */ + 224,225,162,163,164,165,166,167,168,169,232,203,204,205,206,207, /* Ex */ + 239,240,241,242,243,244,245,246,247,248,249,219,220,221,222,255, /* Fx */ +#endif +}; + +/* +** The following singleton contains the global configuration for +** the SQLite library. +*/ +SQLITE_PRIVATE struct Sqlite3Config sqlite3Config = { + 1, /* bMemstat */ + 1, /* bCoreMutex */ + 1, /* bFullMutex */ + 0x7ffffffe, /* mxStrlen */ + 100, /* szLookaside */ + 500, /* nLookaside */ + /* Other fields all default to zero */ +}; + +/************** End of global.c **********************************************/ +/************** Begin file status.c ******************************************/ +/* +** 2008 June 18 +** +** The author disclaims copyright to this source code. In place of +** a legal notice, here is a blessing: +** +** May you do good and not evil. +** May you find forgiveness for yourself and forgive others. +** May you share freely, never taking more than you give. +** +************************************************************************* +** +** This module implements the sqlite3_status() interface and related +** functionality. +** +** $Id$ +*/ + +/* +** Variables in which to record status information. +*/ +static struct { + int nowValue[9]; /* Current value */ + int mxValue[9]; /* Maximum value */ +} sqlite3Stat; + + +/* +** Reset the status records. This routine is called by +** sqlite3_initialize(). +*/ +SQLITE_PRIVATE void sqlite3StatusReset(void){ + memset(&sqlite3Stat, 0, sizeof(sqlite3Stat)); +} + +/* +** Return the current value of a status parameter. +*/ +SQLITE_PRIVATE int sqlite3StatusValue(int op){ + assert( op>=0 && op<ArraySize(sqlite3Stat.nowValue) ); + return sqlite3Stat.nowValue[op]; +} + +/* +** Add N to the value of a status record. It is assumed that the +** caller holds appropriate locks. +*/ +SQLITE_PRIVATE void sqlite3StatusAdd(int op, int N){ + assert( op>=0 && op<ArraySize(sqlite3Stat.nowValue) ); + sqlite3Stat.nowValue[op] += N; + if( sqlite3Stat.nowValue[op]>sqlite3Stat.mxValue[op] ){ + sqlite3Stat.mxValue[op] = sqlite3Stat.nowValue[op]; + } +} + +/* +** Set the value of a status to X. +*/ +SQLITE_PRIVATE void sqlite3StatusSet(int op, int X){ + assert( op>=0 && op<ArraySize(sqlite3Stat.nowValue) ); + sqlite3Stat.nowValue[op] = X; + if( sqlite3Stat.nowValue[op]>sqlite3Stat.mxValue[op] ){ + sqlite3Stat.mxValue[op] = sqlite3Stat.nowValue[op]; + } +} + +/* +** Query status information. +** +** This implementation assumes that reading or writing an aligned +** 32-bit integer is an atomic operation. If that assumption is not true, +** then this routine is not threadsafe. +*/ +SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag){ + if( op<0 || op>=ArraySize(sqlite3Stat.nowValue) ){ + return SQLITE_MISUSE; + } + *pCurrent = sqlite3Stat.nowValue[op]; + *pHighwater = sqlite3Stat.mxValue[op]; + if( resetFlag ){ + sqlite3Stat.mxValue[op] = sqlite3Stat.nowValue[op]; + } + return SQLITE_OK; +} + +/* +** Query status information for a single database connection +*/ +SQLITE_API int sqlite3_db_status( + sqlite3 *db, /* The database connection whose status is desired */ + int op, /* Status verb */ + int *pCurrent, /* Write current value here */ + int *pHighwater, /* Write high-water mark here */ + int resetFlag /* Reset high-water mark if true */ +){ + switch( op ){ + case SQLITE_DBSTATUS_LOOKASIDE_USED: { + *pCurrent = db->lookaside.nOut; + *pHighwater = db->lookaside.mxOut; + if( resetFlag ){ + db->lookaside.mxOut = db->lookaside.nOut; + } + break; + } + default: { + return SQLITE_ERROR; + } + } + return SQLITE_OK; +} + +/************** End of status.c **********************************************/ /************** Begin file date.c ********************************************/ /* ** 2003 October 31 @@ -9516,19 +10502,36 @@ SQLITE_PRIVATE void (*sqlite3IoTrace)(const char*,...); #ifndef SQLITE_OMIT_DATETIME_FUNCS /* +** On recent Windows platforms, the localtime_s() function is available +** as part of the "Secure CRT". It is essentially equivalent to +** localtime_r() available under most POSIX platforms, except that the +** order of the parameters is reversed. +** +** See http://msdn.microsoft.com/en-us/library/a442x3ye(VS.80).aspx. +** +** If the user has not indicated to use localtime_r() or localtime_s() +** already, check for an MSVC build environment that provides +** localtime_s(). +*/ +#if !defined(HAVE_LOCALTIME_R) && !defined(HAVE_LOCALTIME_S) && \ + defined(_MSC_VER) && defined(_CRT_INSECURE_DEPRECATE) +#define HAVE_LOCALTIME_S 1 +#endif + +/* ** A structure for holding a single date and time. */ typedef struct DateTime DateTime; struct DateTime { - double rJD; /* The julian day number */ - int Y, M, D; /* Year, month, and day */ - int h, m; /* Hour and minutes */ - int tz; /* Timezone offset in minutes */ - double s; /* Seconds */ - char validYMD; /* True if Y,M,D are valid */ - char validHMS; /* True if h,m,s are valid */ - char validJD; /* True if rJD is valid */ - char validTZ; /* True if tz is valid */ + sqlite3_int64 iJD; /* The julian day number times 86400000 */ + int Y, M, D; /* Year, month, and day */ + int h, m; /* Hour and minutes */ + int tz; /* Timezone offset in minutes */ + double s; /* Seconds */ + char validYMD; /* True if Y,M,D are valid */ + char validHMS; /* True if h,m,s are valid */ + char validJD; /* True if iJD is valid */ + char validTZ; /* True if tz is valid */ }; @@ -9701,12 +10704,12 @@ static void computeJD(DateTime *p){ B = 2 - A + (A/4); X1 = 365.25*(Y+4716); X2 = 30.6001*(M+1); - p->rJD = X1 + X2 + D + B - 1524.5; + p->iJD = (X1 + X2 + D + B - 1524.5)*86400000; p->validJD = 1; if( p->validHMS ){ - p->rJD += (p->h*3600.0 + p->m*60.0 + p->s)/86400.0; + p->iJD += p->h*3600000 + p->m*60000 + p->s*1000; if( p->validTZ ){ - p->rJD -= p->tz*60/86400.0; + p->iJD -= p->tz*60000; p->validYMD = 0; p->validHMS = 0; p->validTZ = 0; @@ -9759,6 +10762,17 @@ static int parseYyyyMmDd(const char *zDate, DateTime *p){ } /* +** Set the time to the current time reported by the VFS +*/ +static void setDateTimeToCurrent(sqlite3_context *context, DateTime *p){ + double r; + sqlite3 *db = sqlite3_context_db_handle(context); + sqlite3OsCurrentTime(db->pVfs, &r); + p->iJD = (sqlite3_int64)(r*86400000.0 + 0.5); + p->validJD = 1; +} + +/* ** Attempt to parse the given string into a Julian Day Number. Return ** the number of errors. ** @@ -9779,20 +10793,17 @@ static int parseDateOrTime( const char *zDate, DateTime *p ){ - memset(p, 0, sizeof(*p)); if( parseYyyyMmDd(zDate,p)==0 ){ return 0; }else if( parseHhMmSs(zDate, p)==0 ){ return 0; }else if( sqlite3StrICmp(zDate,"now")==0){ - double r; - sqlite3 *db = sqlite3_context_db_handle(context); - sqlite3OsCurrentTime(db->pVfs, &r); - p->rJD = r; - p->validJD = 1; + setDateTimeToCurrent(context, p); return 0; }else if( sqlite3IsNumber(zDate, 0, SQLITE_UTF8) ){ - getValue(zDate, &p->rJD); + double r; + getValue(zDate, &r); + p->iJD = (sqlite3_int64)(r*86400000.0 + 0.5); p->validJD = 1; return 0; } @@ -9810,7 +10821,7 @@ static void computeYMD(DateTime *p){ p->M = 1; p->D = 1; }else{ - Z = p->rJD + 0.5; + Z = (p->iJD + 43200000)/86400000; A = (Z - 1867216.25)/36524.25; A = Z + 1 + A - (A/4); B = A + 1524; @@ -9829,12 +10840,11 @@ static void computeYMD(DateTime *p){ ** Compute the Hour, Minute, and Seconds from the julian day number. */ static void computeHMS(DateTime *p){ - int Z, s; + int s; if( p->validHMS ) return; computeJD(p); - Z = p->rJD + 0.5; - s = (p->rJD + 0.5 - Z)*86400000.0 + 0.5; - p->s = 0.001*s; + s = (p->iJD + 43200000) % 86400000; + p->s = s/1000.0; s = p->s; p->s -= s; p->h = s/3600; @@ -9861,11 +10871,13 @@ static void clearYMD_HMS_TZ(DateTime *p){ p->validTZ = 0; } +#ifndef SQLITE_OMIT_LOCALTIME /* -** Compute the difference (in days) between localtime and UTC (a.k.a. GMT) +** Compute the difference (in milliseconds) +** between localtime and UTC (a.k.a. GMT) ** for the time value p where p is in UTC. */ -static double localtimeOffset(DateTime *p){ +static int localtimeOffset(DateTime *p){ DateTime x, y; time_t t; x = *p; @@ -9884,7 +10896,7 @@ static double localtimeOffset(DateTime *p){ x.tz = 0; x.validJD = 0; computeJD(&x); - t = (x.rJD-2440587.5)*86400.0 + 0.5; + t = x.iJD/1000 - 2440587.5*86400.0; #ifdef HAVE_LOCALTIME_R { struct tm sLocal; @@ -9896,10 +10908,21 @@ static double localtimeOffset(DateTime *p){ y.m = sLocal.tm_min; y.s = sLocal.tm_sec; } +#elif defined(HAVE_LOCALTIME_S) + { + struct tm sLocal; + localtime_s(&sLocal, &t); + y.Y = sLocal.tm_year + 1900; + y.M = sLocal.tm_mon + 1; + y.D = sLocal.tm_mday; + y.h = sLocal.tm_hour; + y.m = sLocal.tm_min; + y.s = sLocal.tm_sec; + } #else { struct tm *pTm; - sqlite3_mutex_enter(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MASTER)); + sqlite3_mutex_enter(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER)); pTm = localtime(&t); y.Y = pTm->tm_year + 1900; y.M = pTm->tm_mon + 1; @@ -9907,7 +10930,7 @@ static double localtimeOffset(DateTime *p){ y.h = pTm->tm_hour; y.m = pTm->tm_min; y.s = pTm->tm_sec; - sqlite3_mutex_leave(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MASTER)); + sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER)); } #endif y.validYMD = 1; @@ -9915,8 +10938,9 @@ static double localtimeOffset(DateTime *p){ y.validJD = 0; y.validTZ = 0; computeJD(&y); - return y.rJD - x.rJD; + return y.iJD - x.iJD; } +#endif /* SQLITE_OMIT_LOCALTIME */ /* ** Process a modifier to a date-time stamp. The modifiers are @@ -9950,6 +10974,7 @@ static int parseModifier(const char *zMod, DateTime *p){ } z[n] = 0; switch( z[0] ){ +#ifndef SQLITE_OMIT_LOCALTIME case 'l': { /* localtime ** @@ -9958,32 +10983,36 @@ static int parseModifier(const char *zMod, DateTime *p){ */ if( strcmp(z, "localtime")==0 ){ computeJD(p); - p->rJD += localtimeOffset(p); + p->iJD += localtimeOffset(p); clearYMD_HMS_TZ(p); rc = 0; } break; } +#endif case 'u': { /* ** unixepoch ** - ** Treat the current value of p->rJD as the number of + ** Treat the current value of p->iJD as the number of ** seconds since 1970. Convert to a real julian day number. */ if( strcmp(z, "unixepoch")==0 && p->validJD ){ - p->rJD = p->rJD/86400.0 + 2440587.5; + p->iJD = p->iJD/86400.0 + 2440587.5*86400000.0; clearYMD_HMS_TZ(p); rc = 0; - }else if( strcmp(z, "utc")==0 ){ + } +#ifndef SQLITE_OMIT_LOCALTIME + else if( strcmp(z, "utc")==0 ){ double c1; computeJD(p); c1 = localtimeOffset(p); - p->rJD -= c1; + p->iJD -= c1; clearYMD_HMS_TZ(p); - p->rJD += c1 - localtimeOffset(p); + p->iJD += c1 - localtimeOffset(p); rc = 0; } +#endif break; } case 'w': { @@ -9996,15 +11025,14 @@ static int parseModifier(const char *zMod, DateTime *p){ */ if( strncmp(z, "weekday ", 8)==0 && getValue(&z[8],&r)>0 && (n=r)==r && n>=0 && r<7 ){ - int Z; + sqlite3_int64 Z; computeYMD_HMS(p); p->validTZ = 0; p->validJD = 0; computeJD(p); - Z = p->rJD + 1.5; - Z %= 7; + Z = ((p->iJD + 129600000)/86400000) % 7; if( Z>n ) Z -= 7; - p->rJD += n - Z; + p->iJD += (n - Z)*86400000; clearYMD_HMS_TZ(p); rc = 0; } @@ -10060,18 +11088,18 @@ static int parseModifier(const char *zMod, DateTime *p){ */ const char *z2 = z; DateTime tx; - int day; + sqlite3_int64 day; if( !isdigit(*(u8*)z2) ) z2++; memset(&tx, 0, sizeof(tx)); if( parseHhMmSs(z2, &tx) ) break; computeJD(&tx); - tx.rJD -= 0.5; - day = (int)tx.rJD; - tx.rJD -= day; - if( z[0]=='-' ) tx.rJD = -tx.rJD; + tx.iJD -= 43200000; + day = tx.iJD/86400000; + tx.iJD -= day*86400000; + if( z[0]=='-' ) tx.iJD = -tx.iJD; computeJD(p); clearYMD_HMS_TZ(p); - p->rJD += tx.rJD; + p->iJD += tx.iJD; rc = 0; break; } @@ -10083,13 +11111,13 @@ static int parseModifier(const char *zMod, DateTime *p){ computeJD(p); rc = 0; if( n==3 && strcmp(z,"day")==0 ){ - p->rJD += r; + p->iJD += r*86400000.0 + 0.5; }else if( n==4 && strcmp(z,"hour")==0 ){ - p->rJD += r/24.0; + p->iJD += r*(86400000.0/24.0) + 0.5; }else if( n==6 && strcmp(z,"minute")==0 ){ - p->rJD += r/(24.0*60.0); + p->iJD += r*(86400000.0/(24.0*60.0)) + 0.5; }else if( n==6 && strcmp(z,"second")==0 ){ - p->rJD += r/(24.0*60.0*60.0); + p->iJD += r*(86400000.0/(24.0*60.0*60.0)) + 0.5; }else if( n==5 && strcmp(z,"month")==0 ){ int x, y; computeYMD_HMS(p); @@ -10101,7 +11129,7 @@ static int parseModifier(const char *zMod, DateTime *p){ computeJD(p); y = r; if( y!=r ){ - p->rJD += (r - y)*30.0; + p->iJD += (r - y)*30.0*86400000.0 + 0.5; } }else if( n==4 && strcmp(z,"year")==0 ){ computeYMD_HMS(p); @@ -10138,14 +11166,19 @@ static int isDate( ){ int i; const unsigned char *z; - static const unsigned char zDflt[] = "now"; + int eType; + memset(p, 0, sizeof(*p)); if( argc==0 ){ - z = zDflt; + setDateTimeToCurrent(context, p); + }else if( (eType = sqlite3_value_type(argv[0]))==SQLITE_FLOAT + || eType==SQLITE_INTEGER ){ + p->iJD = sqlite3_value_double(argv[0])*86400000.0 + 0.5; + p->validJD = 1; }else{ z = sqlite3_value_text(argv[0]); - } - if( !z || parseDateOrTime(context, (char*)z, p) ){ - return 1; + if( !z || parseDateOrTime(context, (char*)z, p) ){ + return 1; + } } for(i=1; i<argc; i++){ if( (z = sqlite3_value_text(argv[i]))==0 || parseModifier((char*)z, p) ){ @@ -10174,7 +11207,7 @@ static void juliandayFunc( DateTime x; if( isDate(context, argc, argv, &x)==0 ){ computeJD(&x); - sqlite3_result_double(context, x.rJD); + sqlite3_result_double(context, x.iJD/86400000.0); } } @@ -10264,9 +11297,11 @@ static void strftimeFunc( u64 n; int i, j; char *z; + sqlite3 *db; const char *zFmt = (const char*)sqlite3_value_text(argv[0]); char zBuf[100]; if( zFmt==0 || isDate(context, argc-1, argv+1, &x) ) return; + db = sqlite3_context_db_handle(context); for(i=0, n=1; zFmt[i]; i++, n++){ if( zFmt[i]=='%' ){ switch( zFmt[i+1] ){ @@ -10302,11 +11337,11 @@ static void strftimeFunc( } if( n<sizeof(zBuf) ){ z = zBuf; - }else if( n>sqlite3_context_db_handle(context)->aLimit[SQLITE_LIMIT_LENGTH] ){ + }else if( n>db->aLimit[SQLITE_LIMIT_LENGTH] ){ sqlite3_result_error_toobig(context); return; }else{ - z = sqlite3_malloc( n ); + z = sqlite3DbMallocRaw(db, n); if( z==0 ){ sqlite3_result_error_nomem(context); return; @@ -10337,10 +11372,10 @@ static void strftimeFunc( y.M = 1; y.D = 1; computeJD(&y); - nDay = x.rJD - y.rJD + 0.5; + nDay = (x.iJD - y.iJD)/86400000.0 + 0.5; if( zFmt[i]=='W' ){ int wd; /* 0=Monday, 1=Tuesday, ... 6=Sunday */ - wd = ((int)(x.rJD+0.5)) % 7; + wd = ((x.iJD+43200000)/86400000) % 7; sqlite3_snprintf(3, &z[j],"%02d",(nDay+7-wd)/7); j += 2; }else{ @@ -10350,7 +11385,7 @@ static void strftimeFunc( break; } case 'J': { - sqlite3_snprintf(20, &z[j],"%.16g",x.rJD); + sqlite3_snprintf(20, &z[j],"%.16g",x.iJD/86400000.0); j+=strlen(&z[j]); break; } @@ -10358,12 +11393,12 @@ static void strftimeFunc( case 'M': sqlite3_snprintf(3, &z[j],"%02d",x.m); j+=2; break; case 's': { sqlite3_snprintf(30,&z[j],"%d", - (int)((x.rJD-2440587.5)*86400.0 + 0.5)); + (int)(x.iJD/1000.0 - 210866760000.0)); j += strlen(&z[j]); break; } case 'S': sqlite3_snprintf(3,&z[j],"%02d",(int)x.s); j+=2; break; - case 'w': z[j++] = (((int)(x.rJD+1.5)) % 7) + '0'; break; + case 'w': z[j++] = (((x.iJD+129600000)/86400000) % 7) + '0'; break; case 'Y': sqlite3_snprintf(5,&z[j],"%04d",x.Y); j+=strlen(&z[j]);break; default: z[j++] = '%'; break; } @@ -10371,7 +11406,7 @@ static void strftimeFunc( } z[j] = 0; sqlite3_result_text(context, z, -1, - z==zBuf ? SQLITE_TRANSIENT : sqlite3_free); + z==zBuf ? SQLITE_TRANSIENT : SQLITE_DYNAMIC); } /* @@ -10449,10 +11484,10 @@ static void currentTimeFunc( #else { struct tm *pTm; - sqlite3_mutex_enter(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MASTER)); + sqlite3_mutex_enter(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER)); pTm = gmtime(&t); strftime(zBuf, 20, zFormat, pTm); - sqlite3_mutex_leave(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MASTER)); + sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER)); } #endif @@ -10521,6 +11556,8 @@ SQLITE_PRIVATE void sqlite3RegisterDateTimeFunctions(sqlite3 *db){ ** ** This file contains OS interface code that is common to all ** architectures. +** +** $Id$ */ #define _SQLITE_OS_C_ 1 #undef _SQLITE_OS_C_ @@ -10542,9 +11579,9 @@ SQLITE_PRIVATE void sqlite3RegisterDateTimeFunctions(sqlite3 *db){ ** sqlite3OsLock() ** */ -#if defined(SQLITE_TEST) && (OS_WIN==0) +#if defined(SQLITE_TEST) && (SQLITE_OS_WIN==0) && 0 #define DO_OS_MALLOC_TEST if (1) { \ - void *pTstAlloc = sqlite3_malloc(10); \ + void *pTstAlloc = sqlite3Malloc(10); \ if (!pTstAlloc) return SQLITE_IOERR_NOMEM; \ sqlite3_free(pTstAlloc); \ } @@ -10582,6 +11619,7 @@ SQLITE_PRIVATE int sqlite3OsSync(sqlite3_file *id, int flags){ return id->pMethods->xSync(id, flags); } SQLITE_PRIVATE int sqlite3OsFileSize(sqlite3_file *id, i64 *pSize){ + DO_OS_MALLOC_TEST; return id->pMethods->xFileSize(id, pSize); } SQLITE_PRIVATE int sqlite3OsLock(sqlite3_file *id, int lockType){ @@ -10591,11 +11629,12 @@ SQLITE_PRIVATE int sqlite3OsLock(sqlite3_file *id, int lockType){ SQLITE_PRIVATE int sqlite3OsUnlock(sqlite3_file *id, int lockType){ return id->pMethods->xUnlock(id, lockType); } -SQLITE_PRIVATE int sqlite3OsCheckReservedLock(sqlite3_file *id){ - return id->pMethods->xCheckReservedLock(id); +SQLITE_PRIVATE int sqlite3OsCheckReservedLock(sqlite3_file *id, int *pResOut){ + DO_OS_MALLOC_TEST; + return id->pMethods->xCheckReservedLock(id, pResOut); } SQLITE_PRIVATE int sqlite3OsFileControl(sqlite3_file *id, int op, void *pArg){ - return id->pMethods->xFileControl(id,op,pArg); + return id->pMethods->xFileControl(id, op, pArg); } SQLITE_PRIVATE int sqlite3OsSectorSize(sqlite3_file *id){ int (*xSectorSize)(sqlite3_file*) = id->pMethods->xSectorSize; @@ -10622,18 +11661,14 @@ SQLITE_PRIVATE int sqlite3OsOpen( SQLITE_PRIVATE int sqlite3OsDelete(sqlite3_vfs *pVfs, const char *zPath, int dirSync){ return pVfs->xDelete(pVfs, zPath, dirSync); } -SQLITE_PRIVATE int sqlite3OsAccess(sqlite3_vfs *pVfs, const char *zPath, int flags){ - int rc; -#ifdef SQLITE_TEST - void *pTstAlloc = sqlite3_malloc(10); - if (!pTstAlloc) return -1; - sqlite3_free(pTstAlloc); -#endif - rc = pVfs->xAccess(pVfs, zPath, flags); - return rc; -} -SQLITE_PRIVATE int sqlite3OsGetTempname(sqlite3_vfs *pVfs, int nBufOut, char *zBufOut){ - return pVfs->xGetTempname(pVfs, nBufOut, zBufOut); +SQLITE_PRIVATE int sqlite3OsAccess( + sqlite3_vfs *pVfs, + const char *zPath, + int flags, + int *pResOut +){ + DO_OS_MALLOC_TEST; + return pVfs->xAccess(pVfs, zPath, flags, pResOut); } SQLITE_PRIVATE int sqlite3OsFullPathname( sqlite3_vfs *pVfs, @@ -10643,6 +11678,7 @@ SQLITE_PRIVATE int sqlite3OsFullPathname( ){ return pVfs->xFullPathname(pVfs, zPath, nPathOut, zPathOut); } +#ifndef SQLITE_OMIT_LOAD_EXTENSION SQLITE_PRIVATE void *sqlite3OsDlOpen(sqlite3_vfs *pVfs, const char *zPath){ return pVfs->xDlOpen(pVfs, zPath); } @@ -10655,6 +11691,7 @@ SQLITE_PRIVATE void *sqlite3OsDlSym(sqlite3_vfs *pVfs, void *pHandle, const char SQLITE_PRIVATE void sqlite3OsDlClose(sqlite3_vfs *pVfs, void *pHandle){ pVfs->xDlClose(pVfs, pHandle); } +#endif /* SQLITE_OMIT_LOAD_EXTENSION */ SQLITE_PRIVATE int sqlite3OsRandomness(sqlite3_vfs *pVfs, int nByte, char *zBufOut){ return pVfs->xRandomness(pVfs, nByte, zBufOut); } @@ -10674,7 +11711,7 @@ SQLITE_PRIVATE int sqlite3OsOpenMalloc( ){ int rc = SQLITE_NOMEM; sqlite3_file *pFile; - pFile = (sqlite3_file *)sqlite3_malloc(pVfs->szOsFile); + pFile = (sqlite3_file *)sqlite3Malloc(pVfs->szOsFile); if( pFile ){ rc = sqlite3OsOpen(pVfs, zFile, pFile, flags, pOutFlags); if( rc!=SQLITE_OK ){ @@ -10694,9 +11731,7 @@ SQLITE_PRIVATE int sqlite3OsCloseFree(sqlite3_file *pFile){ } /* -** The list of all registered VFS implementations. This list is -** initialized to the single VFS returned by sqlite3OsDefaultVfs() -** upon the first call to sqlite3_vfs_find(). +** The list of all registered VFS implementations. */ static sqlite3_vfs *vfsList = 0; @@ -10705,16 +11740,18 @@ static sqlite3_vfs *vfsList = 0; ** first VFS on the list. */ SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfs){ + sqlite3_vfs *pVfs = 0; #ifndef SQLITE_MUTEX_NOOP - sqlite3_mutex *mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MASTER); + sqlite3_mutex *mutex; +#endif +#ifndef SQLITE_OMIT_AUTOINIT + int rc = sqlite3_initialize(); + if( rc ) return 0; +#endif +#ifndef SQLITE_MUTEX_NOOP + mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER); #endif - sqlite3_vfs *pVfs = 0; - static int isInit = 0; sqlite3_mutex_enter(mutex); - if( !isInit ){ - vfsList = sqlite3OsDefaultVfs(); - isInit = 1; - } for(pVfs = vfsList; pVfs; pVfs=pVfs->pNext){ if( zVfs==0 ) break; if( strcmp(zVfs, pVfs->zName)==0 ) break; @@ -10727,7 +11764,7 @@ SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfs){ ** Unlink a VFS from the linked list */ static void vfsUnlink(sqlite3_vfs *pVfs){ - assert( sqlite3_mutex_held(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MASTER)) ); + assert( sqlite3_mutex_held(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER)) ); if( pVfs==0 ){ /* No-op */ }else if( vfsList==pVfs ){ @@ -10749,10 +11786,12 @@ static void vfsUnlink(sqlite3_vfs *pVfs){ ** true. */ SQLITE_API int sqlite3_vfs_register(sqlite3_vfs *pVfs, int makeDflt){ -#ifndef SQLITE_MUTEX_NOOP - sqlite3_mutex *mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MASTER); + sqlite3_mutex *mutex = 0; +#ifndef SQLITE_OMIT_AUTOINIT + int rc = sqlite3_initialize(); + if( rc ) return rc; #endif - sqlite3_vfs_find(0); /* Make sure we are initialized */ + mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER); sqlite3_mutex_enter(mutex); vfsUnlink(pVfs); if( makeDflt || vfsList==0 ){ @@ -10772,7 +11811,7 @@ SQLITE_API int sqlite3_vfs_register(sqlite3_vfs *pVfs, int makeDflt){ */ SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs *pVfs){ #ifndef SQLITE_MUTEX_NOOP - sqlite3_mutex *mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MASTER); + sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER); #endif sqlite3_mutex_enter(mutex); vfsUnlink(pVfs); @@ -10780,14 +11819,6 @@ SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs *pVfs){ return SQLITE_OK; } -/* -** Provide a default sqlite3OsDefaultVfs() implementation in the -** cases where none of the standard backends are used. -*/ -#if !OS_UNIX && !OS_WIN && !OS_OS2 -SQLITE_PRIVATE sqlite3_vfs *sqlite3OsDefaultVfs(void){ return 0; } -#endif - /************** End of os.c **************************************************/ /************** Begin file fault.c *******************************************/ /* @@ -10801,159 +11832,65 @@ SQLITE_PRIVATE sqlite3_vfs *sqlite3OsDefaultVfs(void){ return 0; } ** May you share freely, never taking more than you give. ** ************************************************************************* -** This file contains code to implement a fault-injector used for -** testing and verification of SQLite. -** -** Subsystems within SQLite can call sqlite3FaultStep() to see if -** they should simulate a fault. sqlite3FaultStep() normally returns -** zero but will return non-zero if a fault should be simulated. -** Fault injectors can be used, for example, to simulate memory -** allocation failures or I/O errors. ** -** The fault injector is omitted from the code if SQLite is -** compiled with -DSQLITE_OMIT_BUILTIN_TEST=1. There is a very -** small performance hit for leaving the fault injector in the code. -** Commerical products will probably want to omit the fault injector -** from production builds. But safety-critical systems who work -** under the motto "fly what you test and test what you fly" may -** choose to leave the fault injector enabled even in production. -*/ - -#ifndef SQLITE_OMIT_BUILTIN_TEST - -/* -** There can be various kinds of faults. For example, there can be -** a memory allocation failure. Or an I/O failure. For each different -** fault type, there is a separate FaultInjector structure to keep track -** of the status of that fault. +** $Id$ */ -static struct FaultInjector { - int iCountdown; /* Number of pending successes before we hit a failure */ - int nRepeat; /* Number of times to repeat the failure */ - int nBenign; /* Number of benign failures seen since last config */ - int nFail; /* Number of failures seen since last config */ - u8 enable; /* True if enabled */ - i16 benign; /* Positive if next failure will be benign */ -} aFault[SQLITE_FAULTINJECTOR_COUNT]; /* -** This routine configures and enables a fault injector. After -** calling this routine, aFaultStep() will return false (zero) -** nDelay times, then it will return true nRepeat times, -** then it will again begin returning false. +** This file contains code to support the concept of "benign" +** malloc failures (when the xMalloc() or xRealloc() method of the +** sqlite3_mem_methods structure fails to allocate a block of memory +** and returns 0). +** +** Most malloc failures are non-benign. After they occur, SQLite +** abandons the current operation and returns an error code (usually +** SQLITE_NOMEM) to the user. However, sometimes a fault is not necessarily +** fatal. For example, if a malloc fails while resizing a hash table, this +** is completely recoverable simply by not carrying out the resize. The +** hash table will continue to function normally. So a malloc failure +** during a hash table resize is a benign fault. */ -SQLITE_PRIVATE void sqlite3FaultConfig(int id, int nDelay, int nRepeat){ - assert( id>=0 && id<SQLITE_FAULTINJECTOR_COUNT ); - aFault[id].iCountdown = nDelay; - aFault[id].nRepeat = nRepeat; - aFault[id].nBenign = 0; - aFault[id].nFail = 0; - aFault[id].enable = nDelay>=0; - aFault[id].benign = 0; -} -/* -** Return the number of faults (both hard and benign faults) that have -** occurred since the injector was last configured. -*/ -SQLITE_PRIVATE int sqlite3FaultFailures(int id){ - assert( id>=0 && id<SQLITE_FAULTINJECTOR_COUNT ); - return aFault[id].nFail; -} -/* -** Return the number of benign faults that have occurred since the -** injector was last configured. -*/ -SQLITE_PRIVATE int sqlite3FaultBenignFailures(int id){ - assert( id>=0 && id<SQLITE_FAULTINJECTOR_COUNT ); - return aFault[id].nBenign; -} +#ifndef SQLITE_OMIT_BUILTIN_TEST /* -** Return the number of successes that will occur before the next failure. -** If no failures are scheduled, return -1. +** Global variables. */ -SQLITE_PRIVATE int sqlite3FaultPending(int id){ - assert( id>=0 && id<SQLITE_FAULTINJECTOR_COUNT ); - if( aFault[id].enable ){ - return aFault[id].iCountdown; - }else{ - return -1; - } -} - -/* -** After this routine causes subsequent faults to be either benign -** or hard (not benign), according to the "enable" parameter. -** -** Most faults are hard. In other words, most faults cause -** an error to be propagated back up to the application interface. -** However, sometimes a fault is easily recoverable. For example, -** if a malloc fails while resizing a hash table, this is completely -** recoverable simply by not carrying out the resize. The hash table -** will continue to function normally. So a malloc failure during -** a hash table resize is a benign fault. -*/ -SQLITE_PRIVATE void sqlite3FaultBeginBenign(int id){ - if( id<0 ){ - for(id=0; id<SQLITE_FAULTINJECTOR_COUNT; id++){ - aFault[id].benign++; - } - }else{ - assert( id>=0 && id<SQLITE_FAULTINJECTOR_COUNT ); - aFault[id].benign++; - } -} -SQLITE_PRIVATE void sqlite3FaultEndBenign(int id){ - if( id<0 ){ - for(id=0; id<SQLITE_FAULTINJECTOR_COUNT; id++){ - assert( aFault[id].benign>0 ); - aFault[id].benign--; - } - }else{ - assert( id>=0 && id<SQLITE_FAULTINJECTOR_COUNT ); - assert( aFault[id].benign>0 ); - aFault[id].benign--; - } -} +static struct BenignMallocHooks { + void (*xBenignBegin)(void); + void (*xBenignEnd)(void); +} hooks; /* -** This routine exists as a place to set a breakpoint that will -** fire on any simulated fault. +** Register hooks to call when sqlite3BeginBenignMalloc() and +** sqlite3EndBenignMalloc() are called, respectively. */ -static void sqlite3Fault(void){ - static int cnt = 0; - cnt++; +SQLITE_PRIVATE void sqlite3BenignMallocHooks( + void (*xBenignBegin)(void), + void (*xBenignEnd)(void) +){ + hooks.xBenignBegin = xBenignBegin; + hooks.xBenignEnd = xBenignEnd; } - /* -** Check to see if a fault should be simulated. Return true to simulate -** the fault. Return false if the fault should not be simulated. +** This (sqlite3EndBenignMalloc()) is called by SQLite code to indicate that +** subsequent malloc failures are benign. A call to sqlite3EndBenignMalloc() +** indicates that subsequent malloc failures are non-benign. */ -SQLITE_PRIVATE int sqlite3FaultStep(int id){ - assert( id>=0 && id<SQLITE_FAULTINJECTOR_COUNT ); - if( likely(!aFault[id].enable) ){ - return 0; - } - if( aFault[id].iCountdown>0 ){ - aFault[id].iCountdown--; - return 0; +SQLITE_PRIVATE void sqlite3BeginBenignMalloc(void){ + if( hooks.xBenignBegin ){ + hooks.xBenignBegin(); } - sqlite3Fault(); - aFault[id].nFail++; - if( aFault[id].benign>0 ){ - aFault[id].nBenign++; - } - aFault[id].nRepeat--; - if( aFault[id].nRepeat<=0 ){ - aFault[id].enable = 0; +} +SQLITE_PRIVATE void sqlite3EndBenignMalloc(void){ + if( hooks.xBenignEnd ){ + hooks.xBenignEnd(); } - return 1; } -#endif /* SQLITE_OMIT_BUILTIN_TEST */ +#endif /* #ifndef SQLITE_OMIT_BUILTIN_TEST */ /************** End of fault.c ***********************************************/ /************** Begin file mem1.c ********************************************/ @@ -10968,8 +11905,13 @@ SQLITE_PRIVATE int sqlite3FaultStep(int id){ ** May you share freely, never taking more than you give. ** ************************************************************************* -** This file contains the C functions that implement a memory -** allocation subsystem for use by SQLite. +** +** This file contains low-level memory allocation drivers for when +** SQLite will use the standard C-library malloc/realloc/free interface +** to obtain the memory it needs. +** +** This file contains implementations of the low-level memory allocation +** routines specified in the sqlite3_mem_methods object. ** ** $Id$ */ @@ -10982,212 +11924,119 @@ SQLITE_PRIVATE int sqlite3FaultStep(int id){ #ifdef SQLITE_SYSTEM_MALLOC /* -** All of the static variables used by this module are collected -** into a single structure named "mem". This is to keep the -** static variables organized and to reduce namespace pollution -** when this module is combined with other in the amalgamation. -*/ -static struct { - /* - ** The alarm callback and its arguments. The mem.mutex lock will - ** be held while the callback is running. Recursive calls into - ** the memory subsystem are allowed, but no new callbacks will be - ** issued. The alarmBusy variable is set to prevent recursive - ** callbacks. - */ - sqlite3_int64 alarmThreshold; - void (*alarmCallback)(void*, sqlite3_int64,int); - void *alarmArg; - int alarmBusy; - - /* - ** Mutex to control access to the memory allocation subsystem. - */ - sqlite3_mutex *mutex; - - /* - ** Current allocation and high-water mark. - */ - sqlite3_int64 nowUsed; - sqlite3_int64 mxUsed; - - -} mem; - -/* -** Enter the mutex mem.mutex. Allocate it if it is not already allocated. +** Like malloc(), but remember the size of the allocation +** so that we can find it later using sqlite3MemSize(). +** +** For this low-level routine, we are guaranteed that nByte>0 because +** cases of nByte<=0 will be intercepted and dealt with by higher level +** routines. */ -static void enterMem(void){ - if( mem.mutex==0 ){ - mem.mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MEM); +static void *sqlite3MemMalloc(int nByte){ + sqlite3_int64 *p; + assert( nByte>0 ); + nByte = (nByte+7)&~7; + p = malloc( nByte+8 ); + if( p ){ + p[0] = nByte; + p++; } - sqlite3_mutex_enter(mem.mutex); + return (void *)p; } /* -** Return the amount of memory currently checked out. +** Like free() but works for allocations obtained from sqlite3MemMalloc() +** or sqlite3MemRealloc(). +** +** For this low-level routine, we already know that pPrior!=0 since +** cases where pPrior==0 will have been intecepted and dealt with +** by higher-level routines. */ -SQLITE_API sqlite3_int64 sqlite3_memory_used(void){ - sqlite3_int64 n; - enterMem(); - n = mem.nowUsed; - sqlite3_mutex_leave(mem.mutex); - return n; +static void sqlite3MemFree(void *pPrior){ + sqlite3_int64 *p = (sqlite3_int64*)pPrior; + assert( pPrior!=0 ); + p--; + free(p); } /* -** Return the maximum amount of memory that has ever been -** checked out since either the beginning of this process -** or since the most recent reset. +** Like realloc(). Resize an allocation previously obtained from +** sqlite3MemMalloc(). +** +** For this low-level interface, we know that pPrior!=0. Cases where +** pPrior==0 while have been intercepted by higher-level routine and +** redirected to xMalloc. Similarly, we know that nByte>0 becauses +** cases where nByte<=0 will have been intercepted by higher-level +** routines and redirected to xFree. */ -SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag){ - sqlite3_int64 n; - enterMem(); - n = mem.mxUsed; - if( resetFlag ){ - mem.mxUsed = mem.nowUsed; +static void *sqlite3MemRealloc(void *pPrior, int nByte){ + sqlite3_int64 *p = (sqlite3_int64*)pPrior; + assert( pPrior!=0 && nByte>0 ); + nByte = (nByte+7)&~7; + p = (sqlite3_int64*)pPrior; + p--; + p = realloc(p, nByte+8 ); + if( p ){ + p[0] = nByte; + p++; } - sqlite3_mutex_leave(mem.mutex); - return n; + return (void*)p; } /* -** Change the alarm callback +** Report the allocated size of a prior return from xMalloc() +** or xRealloc(). */ -SQLITE_API int sqlite3_memory_alarm( - void(*xCallback)(void *pArg, sqlite3_int64 used,int N), - void *pArg, - sqlite3_int64 iThreshold -){ - enterMem(); - mem.alarmCallback = xCallback; - mem.alarmArg = pArg; - mem.alarmThreshold = iThreshold; - sqlite3_mutex_leave(mem.mutex); - return SQLITE_OK; +static int sqlite3MemSize(void *pPrior){ + sqlite3_int64 *p; + if( pPrior==0 ) return 0; + p = (sqlite3_int64*)pPrior; + p--; + return p[0]; } /* -** Trigger the alarm +** Round up a request size to the next valid allocation size. */ -static void sqlite3MemsysAlarm(int nByte){ - void (*xCallback)(void*,sqlite3_int64,int); - sqlite3_int64 nowUsed; - void *pArg; - if( mem.alarmCallback==0 || mem.alarmBusy ) return; - mem.alarmBusy = 1; - xCallback = mem.alarmCallback; - nowUsed = mem.nowUsed; - pArg = mem.alarmArg; - sqlite3_mutex_leave(mem.mutex); - xCallback(pArg, nowUsed, nByte); - sqlite3_mutex_enter(mem.mutex); - mem.alarmBusy = 0; +static int sqlite3MemRoundup(int n){ + return (n+7) & ~7; } /* -** Allocate nBytes of memory +** Initialize this module. */ -SQLITE_API void *sqlite3_malloc(int nBytes){ - sqlite3_int64 *p = 0; - if( nBytes>0 ){ - enterMem(); - if( mem.alarmCallback!=0 && mem.nowUsed+nBytes>=mem.alarmThreshold ){ - sqlite3MemsysAlarm(nBytes); - } - if( sqlite3FaultStep(SQLITE_FAULTINJECTOR_MALLOC) ){ - p = 0; - }else{ - p = malloc(nBytes+8); - if( p==0 ){ - sqlite3MemsysAlarm(nBytes); - p = malloc(nBytes+8); - } - } - if( p ){ - p[0] = nBytes; - p++; - mem.nowUsed += nBytes; - if( mem.nowUsed>mem.mxUsed ){ - mem.mxUsed = mem.nowUsed; - } - } - sqlite3_mutex_leave(mem.mutex); - } - return (void*)p; +static int sqlite3MemInit(void *NotUsed){ + return SQLITE_OK; } /* -** Free memory. +** Deinitialize this module. */ -SQLITE_API void sqlite3_free(void *pPrior){ - sqlite3_int64 *p; - int nByte; - if( pPrior==0 ){ - return; - } - assert( mem.mutex!=0 ); - p = pPrior; - p--; - nByte = (int)*p; - sqlite3_mutex_enter(mem.mutex); - mem.nowUsed -= nByte; - free(p); - sqlite3_mutex_leave(mem.mutex); +static void sqlite3MemShutdown(void *NotUsed){ + return; } -/* -** Return the number of bytes allocated at p. -*/ -SQLITE_PRIVATE int sqlite3MallocSize(void *p){ - sqlite3_int64 *pInt; - if( !p ) return 0; - pInt = p; - return pInt[-1]; +SQLITE_PRIVATE const sqlite3_mem_methods *sqlite3MemGetDefault(void){ + static const sqlite3_mem_methods defaultMethods = { + sqlite3MemMalloc, + sqlite3MemFree, + sqlite3MemRealloc, + sqlite3MemSize, + sqlite3MemRoundup, + sqlite3MemInit, + sqlite3MemShutdown, + 0 + }; + return &defaultMethods; } /* -** Change the size of an existing memory allocation +** This routine is the only routine in this file with external linkage. +** +** Populate the low-level memory allocation function pointers in +** sqlite3Config.m with pointers to the routines in this file. */ -SQLITE_API void *sqlite3_realloc(void *pPrior, int nBytes){ - int nOld; - sqlite3_int64 *p; - if( pPrior==0 ){ - return sqlite3_malloc(nBytes); - } - if( nBytes<=0 ){ - sqlite3_free(pPrior); - return 0; - } - p = pPrior; - p--; - nOld = (int)p[0]; - assert( mem.mutex!=0 ); - sqlite3_mutex_enter(mem.mutex); - if( mem.nowUsed+nBytes-nOld>=mem.alarmThreshold ){ - sqlite3MemsysAlarm(nBytes-nOld); - } - if( sqlite3FaultStep(SQLITE_FAULTINJECTOR_MALLOC) ){ - p = 0; - }else{ - p = realloc(p, nBytes+8); - if( p==0 ){ - sqlite3MemsysAlarm(nBytes); - p = pPrior; - p--; - p = realloc(p, nBytes+8); - } - } - if( p ){ - p[0] = nBytes; - p++; - mem.nowUsed += nBytes-nOld; - if( mem.nowUsed>mem.mxUsed ){ - mem.mxUsed = mem.nowUsed; - } - } - sqlite3_mutex_leave(mem.mutex); - return (void*)p; +SQLITE_PRIVATE void sqlite3MemSetDefault(void){ + sqlite3_config(SQLITE_CONFIG_MALLOC, sqlite3MemGetDefault()); } #endif /* SQLITE_SYSTEM_MALLOC */ @@ -11205,8 +12054,15 @@ SQLITE_API void *sqlite3_realloc(void *pPrior, int nBytes){ ** May you share freely, never taking more than you give. ** ************************************************************************* -** This file contains the C functions that implement a memory -** allocation subsystem for use by SQLite. +** +** This file contains low-level memory allocation drivers for when +** SQLite will use the standard C-library malloc/realloc/free interface +** to obtain the memory it needs while adding lots of additional debugging +** information to each allocation in order to help detect and fix memory +** leaks and memory usage errors. +** +** This file contains implementations of the low-level memory allocation +** routines specified in the sqlite3_mem_methods object. ** ** $Id$ */ @@ -11268,29 +12124,12 @@ struct MemBlockHdr { ** when this module is combined with other in the amalgamation. */ static struct { - /* - ** The alarm callback and its arguments. The mem.mutex lock will - ** be held while the callback is running. Recursive calls into - ** the memory subsystem are allowed, but no new callbacks will be - ** issued. The alarmBusy variable is set to prevent recursive - ** callbacks. - */ - sqlite3_int64 alarmThreshold; - void (*alarmCallback)(void*, sqlite3_int64, int); - void *alarmArg; - int alarmBusy; /* ** Mutex to control access to the memory allocation subsystem. */ sqlite3_mutex *mutex; - - /* - ** Current allocation and high-water mark. - */ - sqlite3_int64 nowUsed; - sqlite3_int64 mxUsed; - + /* ** Head and tail of a linked list of all outstanding allocations */ @@ -11317,84 +12156,35 @@ static struct { /* ** Gather statistics on the sizes of memory allocations. - ** sizeCnt[i] is the number of allocation attempts of i*8 + ** nAlloc[i] is the number of allocation attempts of i*8 ** bytes. i==NCSIZE is the number of allocation attempts for ** sizes more than NCSIZE*8 bytes. */ - int sizeCnt[NCSIZE]; + int nAlloc[NCSIZE]; /* Total number of allocations */ + int nCurrent[NCSIZE]; /* Current number of allocations */ + int mxCurrent[NCSIZE]; /* Highwater mark for nCurrent */ } mem; /* -** Enter the mutex mem.mutex. Allocate it if it is not already allocated. +** Adjust memory usage statistics */ -static void enterMem(void){ - if( mem.mutex==0 ){ - mem.mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MEM); +static void adjustStats(int iSize, int increment){ + int i = ((iSize+7)&~7)/8; + if( i>NCSIZE-1 ){ + i = NCSIZE - 1; } - sqlite3_mutex_enter(mem.mutex); -} - -/* -** Return the amount of memory currently checked out. -*/ -SQLITE_API sqlite3_int64 sqlite3_memory_used(void){ - sqlite3_int64 n; - enterMem(); - n = mem.nowUsed; - sqlite3_mutex_leave(mem.mutex); - return n; -} - -/* -** Return the maximum amount of memory that has ever been -** checked out since either the beginning of this process -** or since the most recent reset. -*/ -SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag){ - sqlite3_int64 n; - enterMem(); - n = mem.mxUsed; - if( resetFlag ){ - mem.mxUsed = mem.nowUsed; + if( increment>0 ){ + mem.nAlloc[i]++; + mem.nCurrent[i]++; + if( mem.nCurrent[i]>mem.mxCurrent[i] ){ + mem.mxCurrent[i] = mem.nCurrent[i]; + } + }else{ + mem.nCurrent[i]--; + assert( mem.nCurrent[i]>=0 ); } - sqlite3_mutex_leave(mem.mutex); - return n; -} - -/* -** Change the alarm callback -*/ -SQLITE_API int sqlite3_memory_alarm( - void(*xCallback)(void *pArg, sqlite3_int64 used, int N), - void *pArg, - sqlite3_int64 iThreshold -){ - enterMem(); - mem.alarmCallback = xCallback; - mem.alarmArg = pArg; - mem.alarmThreshold = iThreshold; - sqlite3_mutex_leave(mem.mutex); - return SQLITE_OK; -} - -/* -** Trigger the alarm -*/ -static void sqlite3MemsysAlarm(int nByte){ - void (*xCallback)(void*,sqlite3_int64,int); - sqlite3_int64 nowUsed; - void *pArg; - if( mem.alarmCallback==0 || mem.alarmBusy ) return; - mem.alarmBusy = 1; - xCallback = mem.alarmCallback; - nowUsed = mem.nowUsed; - pArg = mem.alarmArg; - sqlite3_mutex_leave(mem.mutex); - xCallback(pArg, nowUsed, nByte); - sqlite3_mutex_enter(mem.mutex); - mem.alarmBusy = 0; } /* @@ -11425,7 +12215,7 @@ static struct MemBlockHdr *sqlite3MemsysGetHeader(void *pAllocation){ /* ** Return the number of bytes currently allocated at address p. */ -SQLITE_PRIVATE int sqlite3MallocSize(void *p){ +static int sqlite3MemSize(void *p){ struct MemBlockHdr *pHdr; if( !p ){ return 0; @@ -11435,99 +12225,99 @@ SQLITE_PRIVATE int sqlite3MallocSize(void *p){ } /* +** Initialize the memory allocation subsystem. +*/ +static int sqlite3MemInit(void *NotUsed){ + if( !sqlite3Config.bMemstat ){ + /* If memory status is enabled, then the malloc.c wrapper will already + ** hold the STATIC_MEM mutex when the routines here are invoked. */ + mem.mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM); + } + return SQLITE_OK; +} + +/* +** Deinitialize the memory allocation subsystem. +*/ +static void sqlite3MemShutdown(void *NotUsed){ + mem.mutex = 0; +} + +/* +** Round up a request size to the next valid allocation size. +*/ +static int sqlite3MemRoundup(int n){ + return (n+7) & ~7; +} + +/* ** Allocate nByte bytes of memory. */ -SQLITE_API void *sqlite3_malloc(int nByte){ +static void *sqlite3MemMalloc(int nByte){ struct MemBlockHdr *pHdr; void **pBt; char *z; int *pInt; void *p = 0; int totalSize; - - if( nByte>0 ){ - int nReserve; - enterMem(); - assert( mem.disallow==0 ); - if( mem.alarmCallback!=0 && mem.nowUsed+nByte>=mem.alarmThreshold ){ - sqlite3MemsysAlarm(nByte); - } - nReserve = (nByte+7)&~7; - if( nReserve/8>NCSIZE-1 ){ - mem.sizeCnt[NCSIZE-1]++; - }else{ - mem.sizeCnt[nReserve/8]++; - } - totalSize = nReserve + sizeof(*pHdr) + sizeof(int) + - mem.nBacktrace*sizeof(void*) + mem.nTitle; - if( sqlite3FaultStep(SQLITE_FAULTINJECTOR_MALLOC) ){ - p = 0; + int nReserve; + sqlite3_mutex_enter(mem.mutex); + assert( mem.disallow==0 ); + nReserve = (nByte+7)&~7; + totalSize = nReserve + sizeof(*pHdr) + sizeof(int) + + mem.nBacktrace*sizeof(void*) + mem.nTitle; + p = malloc(totalSize); + if( p ){ + z = p; + pBt = (void**)&z[mem.nTitle]; + pHdr = (struct MemBlockHdr*)&pBt[mem.nBacktrace]; + pHdr->pNext = 0; + pHdr->pPrev = mem.pLast; + if( mem.pLast ){ + mem.pLast->pNext = pHdr; }else{ - p = malloc(totalSize); - if( p==0 ){ - sqlite3MemsysAlarm(nByte); - p = malloc(totalSize); + mem.pFirst = pHdr; + } + mem.pLast = pHdr; + pHdr->iForeGuard = FOREGUARD; + pHdr->nBacktraceSlots = mem.nBacktrace; + pHdr->nTitle = mem.nTitle; + if( mem.nBacktrace ){ + void *aAddr[40]; + pHdr->nBacktrace = backtrace(aAddr, mem.nBacktrace+1)-1; + memcpy(pBt, &aAddr[1], pHdr->nBacktrace*sizeof(void*)); + if( mem.xBacktrace ){ + mem.xBacktrace(nByte, pHdr->nBacktrace-1, &aAddr[1]); } + }else{ + pHdr->nBacktrace = 0; } - if( p ){ - z = p; - pBt = (void**)&z[mem.nTitle]; - pHdr = (struct MemBlockHdr*)&pBt[mem.nBacktrace]; - pHdr->pNext = 0; - pHdr->pPrev = mem.pLast; - if( mem.pLast ){ - mem.pLast->pNext = pHdr; - }else{ - mem.pFirst = pHdr; - } - mem.pLast = pHdr; - pHdr->iForeGuard = FOREGUARD; - pHdr->nBacktraceSlots = mem.nBacktrace; - pHdr->nTitle = mem.nTitle; - if( mem.nBacktrace ){ - void *aAddr[40]; - pHdr->nBacktrace = backtrace(aAddr, mem.nBacktrace+1)-1; - memcpy(pBt, &aAddr[1], pHdr->nBacktrace*sizeof(void*)); - if( mem.xBacktrace ){ - mem.xBacktrace(nByte, pHdr->nBacktrace-1, &aAddr[1]); - } - }else{ - pHdr->nBacktrace = 0; - } - if( mem.nTitle ){ - memcpy(z, mem.zTitle, mem.nTitle); - } - pHdr->iSize = nByte; - pInt = (int*)&pHdr[1]; - pInt[nReserve/sizeof(int)] = REARGUARD; - memset(pInt, 0x65, nReserve); - mem.nowUsed += nByte; - if( mem.nowUsed>mem.mxUsed ){ - mem.mxUsed = mem.nowUsed; - } - p = (void*)pInt; + if( mem.nTitle ){ + memcpy(z, mem.zTitle, mem.nTitle); } - sqlite3_mutex_leave(mem.mutex); + pHdr->iSize = nByte; + adjustStats(nByte, +1); + pInt = (int*)&pHdr[1]; + pInt[nReserve/sizeof(int)] = REARGUARD; + memset(pInt, 0x65, nReserve); + p = (void*)pInt; } + sqlite3_mutex_leave(mem.mutex); return p; } /* ** Free memory. */ -SQLITE_API void sqlite3_free(void *pPrior){ +static void sqlite3MemFree(void *pPrior){ struct MemBlockHdr *pHdr; void **pBt; char *z; - if( pPrior==0 ){ - return; - } - assert( mem.mutex!=0 ); + assert( sqlite3Config.bMemstat || mem.mutex!=0 ); pHdr = sqlite3MemsysGetHeader(pPrior); pBt = (void**)pHdr; pBt -= pHdr->nBacktraceSlots; sqlite3_mutex_enter(mem.mutex); - mem.nowUsed -= pHdr->iSize; if( pHdr->pPrev ){ assert( pHdr->pPrev->pNext==pHdr ); pHdr->pPrev->pNext = pHdr->pNext; @@ -11544,6 +12334,7 @@ SQLITE_API void sqlite3_free(void *pPrior){ } z = (char*)pBt; z -= pHdr->nTitle; + adjustStats(pHdr->iSize, -1); memset(z, 0x2b, sizeof(void*)*pHdr->nBacktraceSlots + sizeof(*pHdr) + pHdr->iSize + sizeof(int) + pHdr->nTitle); free(z); @@ -11559,32 +12350,48 @@ SQLITE_API void sqlite3_free(void *pPrior){ ** much more likely to break and we are much more liking to find ** the error. */ -SQLITE_API void *sqlite3_realloc(void *pPrior, int nByte){ +static void *sqlite3MemRealloc(void *pPrior, int nByte){ struct MemBlockHdr *pOldHdr; void *pNew; - if( pPrior==0 ){ - return sqlite3_malloc(nByte); - } - if( nByte<=0 ){ - sqlite3_free(pPrior); - return 0; - } assert( mem.disallow==0 ); pOldHdr = sqlite3MemsysGetHeader(pPrior); - pNew = sqlite3_malloc(nByte); + pNew = sqlite3MemMalloc(nByte); if( pNew ){ memcpy(pNew, pPrior, nByte<pOldHdr->iSize ? nByte : pOldHdr->iSize); if( nByte>pOldHdr->iSize ){ memset(&((char*)pNew)[pOldHdr->iSize], 0x2b, nByte - pOldHdr->iSize); } - sqlite3_free(pPrior); + sqlite3MemFree(pPrior); } return pNew; } + +SQLITE_PRIVATE const sqlite3_mem_methods *sqlite3MemGetDefault(void){ + static const sqlite3_mem_methods defaultMethods = { + sqlite3MemMalloc, + sqlite3MemFree, + sqlite3MemRealloc, + sqlite3MemSize, + sqlite3MemRoundup, + sqlite3MemInit, + sqlite3MemShutdown, + 0 + }; + return &defaultMethods; +} + +/* +** Populate the low-level memory allocation function pointers in +** sqlite3Config.m with pointers to the routines in this file. +*/ +SQLITE_PRIVATE void sqlite3MemSetDefault(void){ + sqlite3_config(SQLITE_CONFIG_MALLOC, sqlite3MemGetDefault()); +} + /* ** Set the number of backtrace levels kept for each allocation. -** A value of zero turns of backtracing. The number is always rounded +** A value of zero turns off backtracing. The number is always rounded ** up to a multiple of 2. */ SQLITE_PRIVATE void sqlite3MemdebugBacktrace(int depth){ @@ -11603,7 +12410,7 @@ SQLITE_PRIVATE void sqlite3MemdebugBacktraceCallback(void (*xBacktrace)(int, int */ SQLITE_PRIVATE void sqlite3MemdebugSettitle(const char *zTitle){ int n = strlen(zTitle) + 1; - enterMem(); + sqlite3_mutex_enter(mem.mutex); if( n>=sizeof(mem.zTitle) ) n = sizeof(mem.zTitle)-1; memcpy(mem.zTitle, zTitle, n); mem.zTitle[n] = 0; @@ -11650,24 +12457,27 @@ SQLITE_PRIVATE void sqlite3MemdebugDump(const char *zFilename){ } fprintf(out, "COUNTS:\n"); for(i=0; i<NCSIZE-1; i++){ - if( mem.sizeCnt[i] ){ - fprintf(out, " %3d: %d\n", i*8+8, mem.sizeCnt[i]); + if( mem.nAlloc[i] ){ + fprintf(out, " %5d: %10d %10d %10d\n", + i*8, mem.nAlloc[i], mem.nCurrent[i], mem.mxCurrent[i]); } } - if( mem.sizeCnt[NCSIZE-1] ){ - fprintf(out, " >%3d: %d\n", NCSIZE*8, mem.sizeCnt[NCSIZE-1]); + if( mem.nAlloc[NCSIZE-1] ){ + fprintf(out, " %5d: %10d %10d %10d\n", + NCSIZE*8-8, mem.nAlloc[NCSIZE-1], + mem.nCurrent[NCSIZE-1], mem.mxCurrent[NCSIZE-1]); } fclose(out); } /* -** Return the number of times sqlite3_malloc() has been called. +** Return the number of times sqlite3MemMalloc() has been called. */ SQLITE_PRIVATE int sqlite3MemdebugMallocCount(){ int i; int nTotal = 0; for(i=0; i<NCSIZE; i++){ - nTotal += mem.sizeCnt[i]; + nTotal += mem.nAlloc[i]; } return nTotal; } @@ -11692,21 +12502,27 @@ SQLITE_PRIVATE int sqlite3MemdebugMallocCount(){ ** allocation subsystem for use by SQLite. ** ** This version of the memory allocation subsystem omits all -** use of malloc(). All dynamically allocatable memory is -** contained in a static array, mem.aPool[]. The size of this -** fixed memory pool is SQLITE_MEMORY_SIZE bytes. +** use of malloc(). The SQLite user supplies a block of memory +** before calling sqlite3_initialize() from which allocations +** are made and returned by the xMalloc() and xRealloc() +** implementations. Once sqlite3_initialize() has been called, +** the amount of memory available to SQLite is fixed and cannot +** be changed. ** -** This version of the memory allocation subsystem is used if -** and only if SQLITE_MEMORY_SIZE is defined. +** This version of the memory allocation subsystem is included +** in the build only if SQLITE_ENABLE_MEMSYS3 is defined. ** ** $Id$ */ /* -** This version of the memory allocator is used only when -** SQLITE_MEMORY_SIZE is defined. +** This version of the memory allocator is only built into the library +** SQLITE_ENABLE_MEMSYS3 is defined. Defining this symbol does not +** mean that the library will use a memory-pool by default, just that +** it is available. The mempool allocator is activated by calling +** sqlite3_config(). */ -#ifdef SQLITE_MEMORY_SIZE +#ifdef SQLITE_ENABLE_MEMSYS3 /* ** Maximum size (in Mem3Blocks) of a "small" chunk. @@ -11736,7 +12552,7 @@ SQLITE_PRIVATE int sqlite3MemdebugMallocCount(){ ** u.hdr.prevSize can be part of the data for that chunk and should ** not be read or written. ** -** We often identify a chunk by its index in mem.aPool[]. When +** We often identify a chunk by its index in mem3.aPool[]. When ** this is done, the chunk index refers to the second block of ** the chunk. In this way, the first chunk has an index of 1. ** A chunk index of 0 means "no such chunk" and is the equivalent @@ -11744,8 +12560,8 @@ SQLITE_PRIVATE int sqlite3MemdebugMallocCount(){ ** ** The second block of free chunks is of the form u.list. The ** two fields form a double-linked list of chunks of related sizes. -** Pointers to the head of the list are stored in mem.aiSmall[] -** for smaller chunks and mem.aiHash[] for larger chunks. +** Pointers to the head of the list are stored in mem3.aiSmall[] +** for smaller chunks and mem3.aiHash[] for larger chunks. ** ** The second block of a chunk is user data if the chunk is checked ** out. If a chunk is checked out, the user data may extend into @@ -11759,15 +12575,15 @@ struct Mem3Block { u32 size4x; /* 4x the size of current chunk in Mem3Block elements */ } hdr; struct { - u32 next; /* Index in mem.aPool[] of next free chunk */ - u32 prev; /* Index in mem.aPool[] of previous free chunk */ + u32 next; /* Index in mem3.aPool[] of next free chunk */ + u32 prev; /* Index in mem3.aPool[] of previous free chunk */ } list; } u; }; /* ** All of the static variables used by this module are collected -** into a single structure named "mem". This is to keep the +** into a single structure named "mem3". This is to keep the ** static variables organized and to reduce namespace pollution ** when this module is combined with other in the amalgamation. */ @@ -11805,29 +12621,31 @@ static struct { u32 aiHash[N_HASH]; /* For sizes MX_SMALL+1 and larger */ /* - ** Memory available for allocation + ** Memory available for allocation. nPool is the size of the array + ** (in Mem3Blocks) pointed to by aPool less 2. */ - Mem3Block aPool[SQLITE_MEMORY_SIZE/sizeof(Mem3Block)+2]; -} mem; + u32 nPool; + Mem3Block *aPool; +} mem3; /* -** Unlink the chunk at mem.aPool[i] from list it is currently +** Unlink the chunk at mem3.aPool[i] from list it is currently ** on. *pRoot is the list that i is a member of. */ static void memsys3UnlinkFromList(u32 i, u32 *pRoot){ - u32 next = mem.aPool[i].u.list.next; - u32 prev = mem.aPool[i].u.list.prev; - assert( sqlite3_mutex_held(mem.mutex) ); + u32 next = mem3.aPool[i].u.list.next; + u32 prev = mem3.aPool[i].u.list.prev; + assert( sqlite3_mutex_held(mem3.mutex) ); if( prev==0 ){ *pRoot = next; }else{ - mem.aPool[prev].u.list.next = next; + mem3.aPool[prev].u.list.next = next; } if( next ){ - mem.aPool[next].u.list.prev = prev; + mem3.aPool[next].u.list.prev = prev; } - mem.aPool[i].u.list.next = 0; - mem.aPool[i].u.list.prev = 0; + mem3.aPool[i].u.list.next = 0; + mem3.aPool[i].u.list.prev = 0; } /* @@ -11836,30 +12654,30 @@ static void memsys3UnlinkFromList(u32 i, u32 *pRoot){ */ static void memsys3Unlink(u32 i){ u32 size, hash; - assert( sqlite3_mutex_held(mem.mutex) ); - assert( (mem.aPool[i-1].u.hdr.size4x & 1)==0 ); + assert( sqlite3_mutex_held(mem3.mutex) ); + assert( (mem3.aPool[i-1].u.hdr.size4x & 1)==0 ); assert( i>=1 ); - size = mem.aPool[i-1].u.hdr.size4x/4; - assert( size==mem.aPool[i+size-1].u.hdr.prevSize ); + size = mem3.aPool[i-1].u.hdr.size4x/4; + assert( size==mem3.aPool[i+size-1].u.hdr.prevSize ); assert( size>=2 ); if( size <= MX_SMALL ){ - memsys3UnlinkFromList(i, &mem.aiSmall[size-2]); + memsys3UnlinkFromList(i, &mem3.aiSmall[size-2]); }else{ hash = size % N_HASH; - memsys3UnlinkFromList(i, &mem.aiHash[hash]); + memsys3UnlinkFromList(i, &mem3.aiHash[hash]); } } /* -** Link the chunk at mem.aPool[i] so that is on the list rooted +** Link the chunk at mem3.aPool[i] so that is on the list rooted ** at *pRoot. */ static void memsys3LinkIntoList(u32 i, u32 *pRoot){ - assert( sqlite3_mutex_held(mem.mutex) ); - mem.aPool[i].u.list.next = *pRoot; - mem.aPool[i].u.list.prev = 0; + assert( sqlite3_mutex_held(mem3.mutex) ); + mem3.aPool[i].u.list.next = *pRoot; + mem3.aPool[i].u.list.prev = 0; if( *pRoot ){ - mem.aPool[*pRoot].u.list.prev = i; + mem3.aPool[*pRoot].u.list.prev = i; } *pRoot = i; } @@ -11870,110 +12688,49 @@ static void memsys3LinkIntoList(u32 i, u32 *pRoot){ */ static void memsys3Link(u32 i){ u32 size, hash; - assert( sqlite3_mutex_held(mem.mutex) ); + assert( sqlite3_mutex_held(mem3.mutex) ); assert( i>=1 ); - assert( (mem.aPool[i-1].u.hdr.size4x & 1)==0 ); - size = mem.aPool[i-1].u.hdr.size4x/4; - assert( size==mem.aPool[i+size-1].u.hdr.prevSize ); + assert( (mem3.aPool[i-1].u.hdr.size4x & 1)==0 ); + size = mem3.aPool[i-1].u.hdr.size4x/4; + assert( size==mem3.aPool[i+size-1].u.hdr.prevSize ); assert( size>=2 ); if( size <= MX_SMALL ){ - memsys3LinkIntoList(i, &mem.aiSmall[size-2]); + memsys3LinkIntoList(i, &mem3.aiSmall[size-2]); }else{ hash = size % N_HASH; - memsys3LinkIntoList(i, &mem.aiHash[hash]); + memsys3LinkIntoList(i, &mem3.aiHash[hash]); } } /* -** Enter the mutex mem.mutex. Allocate it if it is not already allocated. -** -** Also: Initialize the memory allocation subsystem the first time -** this routine is called. +** If the STATIC_MEM mutex is not already held, obtain it now. The mutex +** will already be held (obtained by code in malloc.c) if +** sqlite3Config.bMemStat is true. */ static void memsys3Enter(void){ - if( mem.mutex==0 ){ - mem.mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MEM); - mem.aPool[0].u.hdr.size4x = SQLITE_MEMORY_SIZE/2 + 2; - mem.aPool[SQLITE_MEMORY_SIZE/8].u.hdr.prevSize = SQLITE_MEMORY_SIZE/8; - mem.aPool[SQLITE_MEMORY_SIZE/8].u.hdr.size4x = 1; - mem.iMaster = 1; - mem.szMaster = SQLITE_MEMORY_SIZE/8; - mem.mnMaster = mem.szMaster; - } - sqlite3_mutex_enter(mem.mutex); -} - -/* -** Return the amount of memory currently checked out. -*/ -SQLITE_API sqlite3_int64 sqlite3_memory_used(void){ - sqlite3_int64 n; - memsys3Enter(); - n = SQLITE_MEMORY_SIZE - mem.szMaster*8; - sqlite3_mutex_leave(mem.mutex); - return n; -} - -/* -** Return the maximum amount of memory that has ever been -** checked out since either the beginning of this process -** or since the most recent reset. -*/ -SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag){ - sqlite3_int64 n; - memsys3Enter(); - n = SQLITE_MEMORY_SIZE - mem.mnMaster*8; - if( resetFlag ){ - mem.mnMaster = mem.szMaster; + if( sqlite3Config.bMemstat==0 && mem3.mutex==0 ){ + mem3.mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM); } - sqlite3_mutex_leave(mem.mutex); - return n; + sqlite3_mutex_enter(mem3.mutex); } - -/* -** Change the alarm callback. -** -** This is a no-op for the static memory allocator. The purpose -** of the memory alarm is to support sqlite3_soft_heap_limit(). -** But with this memory allocator, the soft_heap_limit is really -** a hard limit that is fixed at SQLITE_MEMORY_SIZE. -*/ -SQLITE_API int sqlite3_memory_alarm( - void(*xCallback)(void *pArg, sqlite3_int64 used,int N), - void *pArg, - sqlite3_int64 iThreshold -){ - return SQLITE_OK; +static void memsys3Leave(void){ + sqlite3_mutex_leave(mem3.mutex); } /* ** Called when we are unable to satisfy an allocation of nBytes. */ static void memsys3OutOfMemory(int nByte){ - if( !mem.alarmBusy ){ - mem.alarmBusy = 1; - assert( sqlite3_mutex_held(mem.mutex) ); - sqlite3_mutex_leave(mem.mutex); + if( !mem3.alarmBusy ){ + mem3.alarmBusy = 1; + assert( sqlite3_mutex_held(mem3.mutex) ); + sqlite3_mutex_leave(mem3.mutex); sqlite3_release_memory(nByte); - sqlite3_mutex_enter(mem.mutex); - mem.alarmBusy = 0; + sqlite3_mutex_enter(mem3.mutex); + mem3.alarmBusy = 0; } } -/* -** Return the size of an outstanding allocation, in bytes. The -** size returned omits the 8-byte header overhead. This only -** works for chunks that are currently checked out. -*/ -SQLITE_PRIVATE int sqlite3MallocSize(void *p){ - int iSize = 0; - if( p ){ - Mem3Block *pBlock = (Mem3Block*)p; - assert( (pBlock[-1].u.hdr.size4x&1)!=0 ); - iSize = (pBlock[-1].u.hdr.size4x&~3)*2 - 4; - } - return iSize; -} /* ** Chunk i is a free chunk that has been unlinked. Adjust its @@ -11982,62 +12739,62 @@ SQLITE_PRIVATE int sqlite3MallocSize(void *p){ */ static void *memsys3Checkout(u32 i, int nBlock){ u32 x; - assert( sqlite3_mutex_held(mem.mutex) ); + assert( sqlite3_mutex_held(mem3.mutex) ); assert( i>=1 ); - assert( mem.aPool[i-1].u.hdr.size4x/4==nBlock ); - assert( mem.aPool[i+nBlock-1].u.hdr.prevSize==nBlock ); - x = mem.aPool[i-1].u.hdr.size4x; - mem.aPool[i-1].u.hdr.size4x = nBlock*4 | 1 | (x&2); - mem.aPool[i+nBlock-1].u.hdr.prevSize = nBlock; - mem.aPool[i+nBlock-1].u.hdr.size4x |= 2; - return &mem.aPool[i]; + assert( mem3.aPool[i-1].u.hdr.size4x/4==nBlock ); + assert( mem3.aPool[i+nBlock-1].u.hdr.prevSize==nBlock ); + x = mem3.aPool[i-1].u.hdr.size4x; + mem3.aPool[i-1].u.hdr.size4x = nBlock*4 | 1 | (x&2); + mem3.aPool[i+nBlock-1].u.hdr.prevSize = nBlock; + mem3.aPool[i+nBlock-1].u.hdr.size4x |= 2; + return &mem3.aPool[i]; } /* -** Carve a piece off of the end of the mem.iMaster free chunk. +** Carve a piece off of the end of the mem3.iMaster free chunk. ** Return a pointer to the new allocation. Or, if the master chunk ** is not large enough, return 0. */ static void *memsys3FromMaster(int nBlock){ - assert( sqlite3_mutex_held(mem.mutex) ); - assert( mem.szMaster>=nBlock ); - if( nBlock>=mem.szMaster-1 ){ + assert( sqlite3_mutex_held(mem3.mutex) ); + assert( mem3.szMaster>=nBlock ); + if( nBlock>=mem3.szMaster-1 ){ /* Use the entire master */ - void *p = memsys3Checkout(mem.iMaster, mem.szMaster); - mem.iMaster = 0; - mem.szMaster = 0; - mem.mnMaster = 0; + void *p = memsys3Checkout(mem3.iMaster, mem3.szMaster); + mem3.iMaster = 0; + mem3.szMaster = 0; + mem3.mnMaster = 0; return p; }else{ /* Split the master block. Return the tail. */ u32 newi, x; - newi = mem.iMaster + mem.szMaster - nBlock; - assert( newi > mem.iMaster+1 ); - mem.aPool[mem.iMaster+mem.szMaster-1].u.hdr.prevSize = nBlock; - mem.aPool[mem.iMaster+mem.szMaster-1].u.hdr.size4x |= 2; - mem.aPool[newi-1].u.hdr.size4x = nBlock*4 + 1; - mem.szMaster -= nBlock; - mem.aPool[newi-1].u.hdr.prevSize = mem.szMaster; - x = mem.aPool[mem.iMaster-1].u.hdr.size4x & 2; - mem.aPool[mem.iMaster-1].u.hdr.size4x = mem.szMaster*4 | x; - if( mem.szMaster < mem.mnMaster ){ - mem.mnMaster = mem.szMaster; + newi = mem3.iMaster + mem3.szMaster - nBlock; + assert( newi > mem3.iMaster+1 ); + mem3.aPool[mem3.iMaster+mem3.szMaster-1].u.hdr.prevSize = nBlock; + mem3.aPool[mem3.iMaster+mem3.szMaster-1].u.hdr.size4x |= 2; + mem3.aPool[newi-1].u.hdr.size4x = nBlock*4 + 1; + mem3.szMaster -= nBlock; + mem3.aPool[newi-1].u.hdr.prevSize = mem3.szMaster; + x = mem3.aPool[mem3.iMaster-1].u.hdr.size4x & 2; + mem3.aPool[mem3.iMaster-1].u.hdr.size4x = mem3.szMaster*4 | x; + if( mem3.szMaster < mem3.mnMaster ){ + mem3.mnMaster = mem3.szMaster; } - return (void*)&mem.aPool[newi]; + return (void*)&mem3.aPool[newi]; } } /* ** *pRoot is the head of a list of free chunks of the same size ** or same size hash. In other words, *pRoot is an entry in either -** mem.aiSmall[] or mem.aiHash[]. +** mem3.aiSmall[] or mem3.aiHash[]. ** ** This routine examines all entries on the given list and tries ** to coalesce each entries with adjacent free chunks. ** -** If it sees a chunk that is larger than mem.iMaster, it replaces -** the current mem.iMaster with the new larger chunk. In order for -** this mem.iMaster replacement to work, the master chunk must be +** If it sees a chunk that is larger than mem3.iMaster, it replaces +** the current mem3.iMaster with the new larger chunk. In order for +** this mem3.iMaster replacement to work, the master chunk must be ** linked into the hash tables. That is not the normal state of ** affairs, of course. The calling routine must link the master ** chunk before invoking this routine, then must unlink the (possibly @@ -12046,31 +12803,31 @@ static void *memsys3FromMaster(int nBlock){ static void memsys3Merge(u32 *pRoot){ u32 iNext, prev, size, i, x; - assert( sqlite3_mutex_held(mem.mutex) ); + assert( sqlite3_mutex_held(mem3.mutex) ); for(i=*pRoot; i>0; i=iNext){ - iNext = mem.aPool[i].u.list.next; - size = mem.aPool[i-1].u.hdr.size4x; + iNext = mem3.aPool[i].u.list.next; + size = mem3.aPool[i-1].u.hdr.size4x; assert( (size&1)==0 ); if( (size&2)==0 ){ memsys3UnlinkFromList(i, pRoot); - assert( i > mem.aPool[i-1].u.hdr.prevSize ); - prev = i - mem.aPool[i-1].u.hdr.prevSize; + assert( i > mem3.aPool[i-1].u.hdr.prevSize ); + prev = i - mem3.aPool[i-1].u.hdr.prevSize; if( prev==iNext ){ - iNext = mem.aPool[prev].u.list.next; + iNext = mem3.aPool[prev].u.list.next; } memsys3Unlink(prev); size = i + size/4 - prev; - x = mem.aPool[prev-1].u.hdr.size4x & 2; - mem.aPool[prev-1].u.hdr.size4x = size*4 | x; - mem.aPool[prev+size-1].u.hdr.prevSize = size; + x = mem3.aPool[prev-1].u.hdr.size4x & 2; + mem3.aPool[prev-1].u.hdr.size4x = size*4 | x; + mem3.aPool[prev+size-1].u.hdr.prevSize = size; memsys3Link(prev); i = prev; }else{ size /= 4; } - if( size>mem.szMaster ){ - mem.iMaster = i; - mem.szMaster = size; + if( size>mem3.szMaster ){ + mem3.iMaster = i; + mem3.szMaster = size; } } } @@ -12078,20 +12835,23 @@ static void memsys3Merge(u32 *pRoot){ /* ** Return a block of memory of at least nBytes in size. ** Return NULL if unable. +** +** This function assumes that the necessary mutexes, if any, are +** already held by the caller. Hence "Unsafe". */ -static void *memsys3Malloc(int nByte){ +static void *memsys3MallocUnsafe(int nByte){ u32 i; int nBlock; int toFree; - assert( sqlite3_mutex_held(mem.mutex) ); + assert( sqlite3_mutex_held(mem3.mutex) ); assert( sizeof(Mem3Block)==8 ); if( nByte<=12 ){ nBlock = 2; }else{ nBlock = (nByte + 11)/8; } - assert( nBlock >= 2 ); + assert( nBlock>=2 ); /* STEP 1: ** Look for an entry of the correct size in either the small @@ -12099,16 +12859,16 @@ static void *memsys3Malloc(int nByte){ ** successful most of the time (about 9 times out of 10). */ if( nBlock <= MX_SMALL ){ - i = mem.aiSmall[nBlock-2]; + i = mem3.aiSmall[nBlock-2]; if( i>0 ){ - memsys3UnlinkFromList(i, &mem.aiSmall[nBlock-2]); + memsys3UnlinkFromList(i, &mem3.aiSmall[nBlock-2]); return memsys3Checkout(i, nBlock); } }else{ int hash = nBlock % N_HASH; - for(i=mem.aiHash[hash]; i>0; i=mem.aPool[i].u.list.next){ - if( mem.aPool[i-1].u.hdr.size4x/4==nBlock ){ - memsys3UnlinkFromList(i, &mem.aiHash[hash]); + for(i=mem3.aiHash[hash]; i>0; i=mem3.aPool[i].u.list.next){ + if( mem3.aPool[i-1].u.hdr.size4x/4==nBlock ){ + memsys3UnlinkFromList(i, &mem3.aiHash[hash]); return memsys3Checkout(i, nBlock); } } @@ -12118,7 +12878,7 @@ static void *memsys3Malloc(int nByte){ ** Try to satisfy the allocation by carving a piece off of the end ** of the master chunk. This step usually works if step 1 fails. */ - if( mem.szMaster>=nBlock ){ + if( mem3.szMaster>=nBlock ){ return memsys3FromMaster(nBlock); } @@ -12130,22 +12890,22 @@ static void *memsys3Malloc(int nByte){ ** of the end of the master chunk. This step happens very ** rarely (we hope!) */ - for(toFree=nBlock*16; toFree<SQLITE_MEMORY_SIZE*2; toFree *= 2){ + for(toFree=nBlock*16; toFree<(mem3.nPool*16); toFree *= 2){ memsys3OutOfMemory(toFree); - if( mem.iMaster ){ - memsys3Link(mem.iMaster); - mem.iMaster = 0; - mem.szMaster = 0; + if( mem3.iMaster ){ + memsys3Link(mem3.iMaster); + mem3.iMaster = 0; + mem3.szMaster = 0; } for(i=0; i<N_HASH; i++){ - memsys3Merge(&mem.aiHash[i]); + memsys3Merge(&mem3.aiHash[i]); } for(i=0; i<MX_SMALL-1; i++){ - memsys3Merge(&mem.aiSmall[i]); + memsys3Merge(&mem3.aiSmall[i]); } - if( mem.szMaster ){ - memsys3Unlink(mem.iMaster); - if( mem.szMaster>=nBlock ){ + if( mem3.szMaster ){ + memsys3Unlink(mem3.iMaster); + if( mem3.szMaster>=nBlock ){ return memsys3FromMaster(nBlock); } } @@ -12157,73 +12917,96 @@ static void *memsys3Malloc(int nByte){ /* ** Free an outstanding memory allocation. +** +** This function assumes that the necessary mutexes, if any, are +** already held by the caller. Hence "Unsafe". */ -void memsys3Free(void *pOld){ +void memsys3FreeUnsafe(void *pOld){ Mem3Block *p = (Mem3Block*)pOld; int i; u32 size, x; - assert( sqlite3_mutex_held(mem.mutex) ); - assert( p>mem.aPool && p<&mem.aPool[SQLITE_MEMORY_SIZE/8] ); - i = p - mem.aPool; - assert( (mem.aPool[i-1].u.hdr.size4x&1)==1 ); - size = mem.aPool[i-1].u.hdr.size4x/4; - assert( i+size<=SQLITE_MEMORY_SIZE/8+1 ); - mem.aPool[i-1].u.hdr.size4x &= ~1; - mem.aPool[i+size-1].u.hdr.prevSize = size; - mem.aPool[i+size-1].u.hdr.size4x &= ~2; + assert( sqlite3_mutex_held(mem3.mutex) ); + assert( p>mem3.aPool && p<&mem3.aPool[mem3.nPool] ); + i = p - mem3.aPool; + assert( (mem3.aPool[i-1].u.hdr.size4x&1)==1 ); + size = mem3.aPool[i-1].u.hdr.size4x/4; + assert( i+size<=mem3.nPool+1 ); + mem3.aPool[i-1].u.hdr.size4x &= ~1; + mem3.aPool[i+size-1].u.hdr.prevSize = size; + mem3.aPool[i+size-1].u.hdr.size4x &= ~2; memsys3Link(i); /* Try to expand the master using the newly freed chunk */ - if( mem.iMaster ){ - while( (mem.aPool[mem.iMaster-1].u.hdr.size4x&2)==0 ){ - size = mem.aPool[mem.iMaster-1].u.hdr.prevSize; - mem.iMaster -= size; - mem.szMaster += size; - memsys3Unlink(mem.iMaster); - x = mem.aPool[mem.iMaster-1].u.hdr.size4x & 2; - mem.aPool[mem.iMaster-1].u.hdr.size4x = mem.szMaster*4 | x; - mem.aPool[mem.iMaster+mem.szMaster-1].u.hdr.prevSize = mem.szMaster; + if( mem3.iMaster ){ + while( (mem3.aPool[mem3.iMaster-1].u.hdr.size4x&2)==0 ){ + size = mem3.aPool[mem3.iMaster-1].u.hdr.prevSize; + mem3.iMaster -= size; + mem3.szMaster += size; + memsys3Unlink(mem3.iMaster); + x = mem3.aPool[mem3.iMaster-1].u.hdr.size4x & 2; + mem3.aPool[mem3.iMaster-1].u.hdr.size4x = mem3.szMaster*4 | x; + mem3.aPool[mem3.iMaster+mem3.szMaster-1].u.hdr.prevSize = mem3.szMaster; } - x = mem.aPool[mem.iMaster-1].u.hdr.size4x & 2; - while( (mem.aPool[mem.iMaster+mem.szMaster-1].u.hdr.size4x&1)==0 ){ - memsys3Unlink(mem.iMaster+mem.szMaster); - mem.szMaster += mem.aPool[mem.iMaster+mem.szMaster-1].u.hdr.size4x/4; - mem.aPool[mem.iMaster-1].u.hdr.size4x = mem.szMaster*4 | x; - mem.aPool[mem.iMaster+mem.szMaster-1].u.hdr.prevSize = mem.szMaster; + x = mem3.aPool[mem3.iMaster-1].u.hdr.size4x & 2; + while( (mem3.aPool[mem3.iMaster+mem3.szMaster-1].u.hdr.size4x&1)==0 ){ + memsys3Unlink(mem3.iMaster+mem3.szMaster); + mem3.szMaster += mem3.aPool[mem3.iMaster+mem3.szMaster-1].u.hdr.size4x/4; + mem3.aPool[mem3.iMaster-1].u.hdr.size4x = mem3.szMaster*4 | x; + mem3.aPool[mem3.iMaster+mem3.szMaster-1].u.hdr.prevSize = mem3.szMaster; } } } /* -** Allocate nBytes of memory +** Return the size of an outstanding allocation, in bytes. The +** size returned omits the 8-byte header overhead. This only +** works for chunks that are currently checked out. */ -SQLITE_API void *sqlite3_malloc(int nBytes){ - sqlite3_int64 *p = 0; - if( nBytes>0 ){ - memsys3Enter(); - p = memsys3Malloc(nBytes); - sqlite3_mutex_leave(mem.mutex); +static int memsys3Size(void *p){ + Mem3Block *pBlock; + if( p==0 ) return 0; + pBlock = (Mem3Block*)p; + assert( (pBlock[-1].u.hdr.size4x&1)!=0 ); + return (pBlock[-1].u.hdr.size4x&~3)*2 - 4; +} + +/* +** Round up a request size to the next valid allocation size. +*/ +static int memsys3Roundup(int n){ + if( n<=12 ){ + return 12; + }else{ + return ((n+11)&~7) - 4; } +} + +/* +** Allocate nBytes of memory. +*/ +static void *memsys3Malloc(int nBytes){ + sqlite3_int64 *p; + assert( nBytes>0 ); /* malloc.c filters out 0 byte requests */ + memsys3Enter(); + p = memsys3MallocUnsafe(nBytes); + memsys3Leave(); return (void*)p; } /* ** Free memory. */ -SQLITE_API void sqlite3_free(void *pPrior){ - if( pPrior==0 ){ - return; - } - assert( mem.mutex!=0 ); - sqlite3_mutex_enter(mem.mutex); - memsys3Free(pPrior); - sqlite3_mutex_leave(mem.mutex); +void memsys3Free(void *pPrior){ + assert( pPrior ); + memsys3Enter(); + memsys3FreeUnsafe(pPrior); + memsys3Leave(); } /* ** Change the size of an existing memory allocation */ -SQLITE_API void *sqlite3_realloc(void *pPrior, int nBytes){ +void *memsys3Realloc(void *pPrior, int nBytes){ int nOld; void *p; if( pPrior==0 ){ @@ -12233,31 +13016,63 @@ SQLITE_API void *sqlite3_realloc(void *pPrior, int nBytes){ sqlite3_free(pPrior); return 0; } - assert( mem.mutex!=0 ); - nOld = sqlite3MallocSize(pPrior); + nOld = memsys3Size(pPrior); if( nBytes<=nOld && nBytes>=nOld-128 ){ return pPrior; } - sqlite3_mutex_enter(mem.mutex); - p = memsys3Malloc(nBytes); + memsys3Enter(); + p = memsys3MallocUnsafe(nBytes); if( p ){ if( nOld<nBytes ){ memcpy(p, pPrior, nOld); }else{ memcpy(p, pPrior, nBytes); } - memsys3Free(pPrior); + memsys3FreeUnsafe(pPrior); } - sqlite3_mutex_leave(mem.mutex); + memsys3Leave(); return p; } /* +** Initialize this module. +*/ +static int memsys3Init(void *NotUsed){ + if( !sqlite3Config.pHeap ){ + return SQLITE_ERROR; + } + + /* Store a pointer to the memory block in global structure mem3. */ + assert( sizeof(Mem3Block)==8 ); + mem3.aPool = (Mem3Block *)sqlite3Config.pHeap; + mem3.nPool = (sqlite3Config.nHeap / sizeof(Mem3Block)) - 2; + + /* Initialize the master block. */ + mem3.szMaster = mem3.nPool; + mem3.mnMaster = mem3.szMaster; + mem3.iMaster = 1; + mem3.aPool[0].u.hdr.size4x = (mem3.szMaster<<2) + 2; + mem3.aPool[mem3.nPool].u.hdr.prevSize = mem3.nPool; + mem3.aPool[mem3.nPool].u.hdr.size4x = 1; + + return SQLITE_OK; +} + +/* +** Deinitialize this module. +*/ +static void memsys3Shutdown(void *NotUsed){ + return; +} + + + +/* ** Open the file indicated and write a log of all unfreed memory ** allocations into that log. */ -SQLITE_PRIVATE void sqlite3MemdebugDump(const char *zFilename){ #ifdef SQLITE_DEBUG +SQLITE_PRIVATE void sqlite3Memsys3Dump(const char *zFilename){ FILE *out; int i, j; u32 size; @@ -12273,62 +13088,86 @@ SQLITE_PRIVATE void sqlite3MemdebugDump(const char *zFilename){ } memsys3Enter(); fprintf(out, "CHUNKS:\n"); - for(i=1; i<=SQLITE_MEMORY_SIZE/8; i+=size/4){ - size = mem.aPool[i-1].u.hdr.size4x; + for(i=1; i<=mem3.nPool; i+=size/4){ + size = mem3.aPool[i-1].u.hdr.size4x; if( size/4<=1 ){ - fprintf(out, "%p size error\n", &mem.aPool[i]); + fprintf(out, "%p size error\n", &mem3.aPool[i]); assert( 0 ); break; } - if( (size&1)==0 && mem.aPool[i+size/4-1].u.hdr.prevSize!=size/4 ){ - fprintf(out, "%p tail size does not match\n", &mem.aPool[i]); + if( (size&1)==0 && mem3.aPool[i+size/4-1].u.hdr.prevSize!=size/4 ){ + fprintf(out, "%p tail size does not match\n", &mem3.aPool[i]); assert( 0 ); break; } - if( ((mem.aPool[i+size/4-1].u.hdr.size4x&2)>>1)!=(size&1) ){ - fprintf(out, "%p tail checkout bit is incorrect\n", &mem.aPool[i]); + if( ((mem3.aPool[i+size/4-1].u.hdr.size4x&2)>>1)!=(size&1) ){ + fprintf(out, "%p tail checkout bit is incorrect\n", &mem3.aPool[i]); assert( 0 ); break; } if( size&1 ){ - fprintf(out, "%p %6d bytes checked out\n", &mem.aPool[i], (size/4)*8-8); + fprintf(out, "%p %6d bytes checked out\n", &mem3.aPool[i], (size/4)*8-8); }else{ - fprintf(out, "%p %6d bytes free%s\n", &mem.aPool[i], (size/4)*8-8, - i==mem.iMaster ? " **master**" : ""); + fprintf(out, "%p %6d bytes free%s\n", &mem3.aPool[i], (size/4)*8-8, + i==mem3.iMaster ? " **master**" : ""); } } for(i=0; i<MX_SMALL-1; i++){ - if( mem.aiSmall[i]==0 ) continue; + if( mem3.aiSmall[i]==0 ) continue; fprintf(out, "small(%2d):", i); - for(j = mem.aiSmall[i]; j>0; j=mem.aPool[j].u.list.next){ - fprintf(out, " %p(%d)", &mem.aPool[j], - (mem.aPool[j-1].u.hdr.size4x/4)*8-8); + for(j = mem3.aiSmall[i]; j>0; j=mem3.aPool[j].u.list.next){ + fprintf(out, " %p(%d)", &mem3.aPool[j], + (mem3.aPool[j-1].u.hdr.size4x/4)*8-8); } fprintf(out, "\n"); } for(i=0; i<N_HASH; i++){ - if( mem.aiHash[i]==0 ) continue; + if( mem3.aiHash[i]==0 ) continue; fprintf(out, "hash(%2d):", i); - for(j = mem.aiHash[i]; j>0; j=mem.aPool[j].u.list.next){ - fprintf(out, " %p(%d)", &mem.aPool[j], - (mem.aPool[j-1].u.hdr.size4x/4)*8-8); + for(j = mem3.aiHash[i]; j>0; j=mem3.aPool[j].u.list.next){ + fprintf(out, " %p(%d)", &mem3.aPool[j], + (mem3.aPool[j-1].u.hdr.size4x/4)*8-8); } fprintf(out, "\n"); } - fprintf(out, "master=%d\n", mem.iMaster); - fprintf(out, "nowUsed=%d\n", SQLITE_MEMORY_SIZE - mem.szMaster*8); - fprintf(out, "mxUsed=%d\n", SQLITE_MEMORY_SIZE - mem.mnMaster*8); - sqlite3_mutex_leave(mem.mutex); + fprintf(out, "master=%d\n", mem3.iMaster); + fprintf(out, "nowUsed=%d\n", mem3.nPool*8 - mem3.szMaster*8); + fprintf(out, "mxUsed=%d\n", mem3.nPool*8 - mem3.mnMaster*8); + sqlite3_mutex_leave(mem3.mutex); if( out==stdout ){ fflush(stdout); }else{ fclose(out); } -#endif } +#endif +/* +** This routine is the only routine in this file with external +** linkage. +** +** Populate the low-level memory allocation function pointers in +** sqlite3Config.m with pointers to the routines in this file. The +** arguments specify the block of memory to manage. +** +** This routine is only called by sqlite3_config(), and therefore +** is not required to be threadsafe (it is not). +*/ +SQLITE_PRIVATE const sqlite3_mem_methods *sqlite3MemGetMemsys3(void){ + static const sqlite3_mem_methods mempoolMethods = { + memsys3Malloc, + memsys3Free, + memsys3Realloc, + memsys3Size, + memsys3Roundup, + memsys3Init, + memsys3Shutdown, + 0 + }; + return &mempoolMethods; +} -#endif /* !SQLITE_MEMORY_SIZE */ +#endif /* SQLITE_ENABLE_MEMSYS3 */ /************** End of mem3.c ************************************************/ /************** Begin file mem5.c ********************************************/ @@ -12347,12 +13186,15 @@ SQLITE_PRIVATE void sqlite3MemdebugDump(const char *zFilename){ ** allocation subsystem for use by SQLite. ** ** This version of the memory allocation subsystem omits all -** use of malloc(). All dynamically allocatable memory is -** contained in a static array, mem.aPool[]. The size of this -** fixed memory pool is SQLITE_POW2_MEMORY_SIZE bytes. +** use of malloc(). The SQLite user supplies a block of memory +** before calling sqlite3_initialize() from which allocations +** are made and returned by the xMalloc() and xRealloc() +** implementations. Once sqlite3_initialize() has been called, +** the amount of memory available to SQLite is fixed and cannot +** be changed. ** -** This version of the memory allocation subsystem is used if -** and only if SQLITE_POW2_MEMORY_SIZE is defined. +** This version of the memory allocation subsystem is included +** in the build only if SQLITE_ENABLE_MEMSYS5 is defined. ** ** $Id$ */ @@ -12361,7 +13203,7 @@ SQLITE_PRIVATE void sqlite3MemdebugDump(const char *zFilename){ ** This version of the memory allocator is used only when ** SQLITE_POW2_MEMORY_SIZE is defined. */ -#ifdef SQLITE_POW2_MEMORY_SIZE +#ifdef SQLITE_ENABLE_MEMSYS5 /* ** Log2 of the minimum size of an allocation. For example, if @@ -12371,13 +13213,12 @@ SQLITE_PRIVATE void sqlite3MemdebugDump(const char *zFilename){ #ifndef SQLITE_POW2_LOGMIN # define SQLITE_POW2_LOGMIN 6 #endif -#define POW2_MIN (1<<SQLITE_POW2_LOGMIN) /* ** Log2 of the maximum size of an allocation. */ #ifndef SQLITE_POW2_LOGMAX -# define SQLITE_POW2_LOGMAX 18 +# define SQLITE_POW2_LOGMAX 20 #endif #define POW2_MAX (((unsigned int)1)<<SQLITE_POW2_LOGMAX) @@ -12391,42 +13232,34 @@ SQLITE_PRIVATE void sqlite3MemdebugDump(const char *zFilename){ ** Larger allocations are an array of these structures where the ** size of the array is a power of 2. */ -typedef struct Mem5Block Mem5Block; -struct Mem5Block { - union { - char aData[POW2_MIN]; - struct { - int next; /* Index in mem.aPool[] of next free chunk */ - int prev; /* Index in mem.aPool[] of previous free chunk */ - } list; - } u; +typedef struct Mem5Link Mem5Link; +struct Mem5Link { + int next; /* Index of next free chunk */ + int prev; /* Index of previous free chunk */ }; /* -** Number of blocks of memory available for allocation. +** Maximum size of any allocation is ((1<<LOGMAX)*mem5.nAtom). Since +** mem5.nAtom is always at least 8, this is not really a practical +** limitation. */ -#define NBLOCK (SQLITE_POW2_MEMORY_SIZE/POW2_MIN) +#define LOGMAX 30 /* -** The size in blocks of an POW2_MAX allocation -*/ -#define SZ_MAX (1<<(NSIZE-1)) - -/* -** Masks used for mem.aCtrl[] elements. +** Masks used for mem5.aCtrl[] elements. */ #define CTRL_LOGSIZE 0x1f /* Log2 Size of this block relative to POW2_MIN */ #define CTRL_FREE 0x20 /* True if not checked out */ /* ** All of the static variables used by this module are collected -** into a single structure named "mem". This is to keep the +** into a single structure named "mem5". This is to keep the ** static variables organized and to reduce namespace pollution ** when this module is combined with other in the amalgamation. */ static struct { /* - ** The alarm callback and its arguments. The mem.mutex lock will + ** The alarm callback and its arguments. The mem5.mutex lock will ** be held while the callback is running. Recursive calls into ** the memory subsystem are allowed, but no new callbacks will be ** issued. The alarmBusy variable is set to prevent recursive @@ -12457,148 +13290,79 @@ static struct { /* ** Lists of free blocks of various sizes. */ - int aiFreelist[NSIZE]; + int aiFreelist[LOGMAX+1]; /* ** Space for tracking which blocks are checked out and the size ** of each block. One byte per block. */ - u8 aCtrl[NBLOCK]; + u8 *aCtrl; /* ** Memory available for allocation */ - Mem5Block aPool[NBLOCK]; -} mem; + int nAtom; /* Smallest possible allocation in bytes */ + int nBlock; /* Number of nAtom sized blocks in zPool */ + u8 *zPool; +} mem5; + +#define MEM5LINK(idx) ((Mem5Link *)(&mem5.zPool[(idx)*mem5.nAtom])) /* -** Unlink the chunk at mem.aPool[i] from list it is currently -** on. It should be found on mem.aiFreelist[iLogsize]. +** Unlink the chunk at mem5.aPool[i] from list it is currently +** on. It should be found on mem5.aiFreelist[iLogsize]. */ static void memsys5Unlink(int i, int iLogsize){ int next, prev; - assert( i>=0 && i<NBLOCK ); - assert( iLogsize>=0 && iLogsize<NSIZE ); - assert( (mem.aCtrl[i] & CTRL_LOGSIZE)==iLogsize ); - assert( sqlite3_mutex_held(mem.mutex) ); + assert( i>=0 && i<mem5.nBlock ); + assert( iLogsize>=0 && iLogsize<=LOGMAX ); + assert( (mem5.aCtrl[i] & CTRL_LOGSIZE)==iLogsize ); - next = mem.aPool[i].u.list.next; - prev = mem.aPool[i].u.list.prev; + next = MEM5LINK(i)->next; + prev = MEM5LINK(i)->prev; if( prev<0 ){ - mem.aiFreelist[iLogsize] = next; + mem5.aiFreelist[iLogsize] = next; }else{ - mem.aPool[prev].u.list.next = next; + MEM5LINK(prev)->next = next; } if( next>=0 ){ - mem.aPool[next].u.list.prev = prev; + MEM5LINK(next)->prev = prev; } } /* -** Link the chunk at mem.aPool[i] so that is on the iLogsize +** Link the chunk at mem5.aPool[i] so that is on the iLogsize ** free list. */ static void memsys5Link(int i, int iLogsize){ int x; - assert( sqlite3_mutex_held(mem.mutex) ); - assert( i>=0 && i<NBLOCK ); - assert( iLogsize>=0 && iLogsize<NSIZE ); - assert( (mem.aCtrl[i] & CTRL_LOGSIZE)==iLogsize ); + assert( sqlite3_mutex_held(mem5.mutex) ); + assert( i>=0 && i<mem5.nBlock ); + assert( iLogsize>=0 && iLogsize<=LOGMAX ); + assert( (mem5.aCtrl[i] & CTRL_LOGSIZE)==iLogsize ); - mem.aPool[i].u.list.next = x = mem.aiFreelist[iLogsize]; - mem.aPool[i].u.list.prev = -1; + x = MEM5LINK(i)->next = mem5.aiFreelist[iLogsize]; + MEM5LINK(i)->prev = -1; if( x>=0 ){ - assert( x<NBLOCK ); - mem.aPool[x].u.list.prev = i; + assert( x<mem5.nBlock ); + MEM5LINK(x)->prev = i; } - mem.aiFreelist[iLogsize] = i; + mem5.aiFreelist[iLogsize] = i; } /* -** Enter the mutex mem.mutex. Allocate it if it is not already allocated. -** -** Also: Initialize the memory allocation subsystem the first time -** this routine is called. +** If the STATIC_MEM mutex is not already held, obtain it now. The mutex +** will already be held (obtained by code in malloc.c) if +** sqlite3Config.bMemStat is true. */ static void memsys5Enter(void){ - if( mem.mutex==0 ){ - int i; - assert( sizeof(Mem5Block)==POW2_MIN ); - assert( (SQLITE_POW2_MEMORY_SIZE % POW2_MAX)==0 ); - assert( SQLITE_POW2_MEMORY_SIZE>=POW2_MAX ); - mem.mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MEM); - sqlite3_mutex_enter(mem.mutex); - for(i=0; i<NSIZE; i++) mem.aiFreelist[i] = -1; - for(i=0; i<=NBLOCK-SZ_MAX; i += SZ_MAX){ - mem.aCtrl[i] = (NSIZE-1) | CTRL_FREE; - memsys5Link(i, NSIZE-1); - } - }else{ - sqlite3_mutex_enter(mem.mutex); + if( sqlite3Config.bMemstat==0 && mem5.mutex==0 ){ + mem5.mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM); } + sqlite3_mutex_enter(mem5.mutex); } - -/* -** Return the amount of memory currently checked out. -*/ -SQLITE_API sqlite3_int64 sqlite3_memory_used(void){ - return mem.currentOut; -} - -/* -** Return the maximum amount of memory that has ever been -** checked out since either the beginning of this process -** or since the most recent reset. -*/ -SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag){ - sqlite3_int64 n; - memsys5Enter(); - n = mem.maxOut; - if( resetFlag ){ - mem.maxOut = mem.currentOut; - } - sqlite3_mutex_leave(mem.mutex); - return n; -} - - -/* -** Trigger the alarm -*/ -static void memsys5Alarm(int nByte){ - void (*xCallback)(void*,sqlite3_int64,int); - sqlite3_int64 nowUsed; - void *pArg; - if( mem.alarmCallback==0 || mem.alarmBusy ) return; - mem.alarmBusy = 1; - xCallback = mem.alarmCallback; - nowUsed = mem.currentOut; - pArg = mem.alarmArg; - sqlite3_mutex_leave(mem.mutex); - xCallback(pArg, nowUsed, nByte); - sqlite3_mutex_enter(mem.mutex); - mem.alarmBusy = 0; -} - -/* -** Change the alarm callback. -** -** This is a no-op for the static memory allocator. The purpose -** of the memory alarm is to support sqlite3_soft_heap_limit(). -** But with this memory allocator, the soft_heap_limit is really -** a hard limit that is fixed at SQLITE_POW2_MEMORY_SIZE. -*/ -SQLITE_API int sqlite3_memory_alarm( - void(*xCallback)(void *pArg, sqlite3_int64 used,int N), - void *pArg, - sqlite3_int64 iThreshold -){ - memsys5Enter(); - mem.alarmCallback = xCallback; - mem.alarmArg = pArg; - mem.alarmThreshold = iThreshold; - sqlite3_mutex_leave(mem.mutex); - return SQLITE_OK; +static void memsys5Leave(void){ + sqlite3_mutex_leave(mem5.mutex); } /* @@ -12606,12 +13370,12 @@ SQLITE_API int sqlite3_memory_alarm( ** size returned omits the 8-byte header overhead. This only ** works for chunks that are currently checked out. */ -SQLITE_PRIVATE int sqlite3MallocSize(void *p){ +static int memsys5Size(void *p){ int iSize = 0; if( p ){ - int i = ((Mem5Block*)p) - mem.aPool; - assert( i>=0 && i<NBLOCK ); - iSize = 1 << ((mem.aCtrl[i]&CTRL_LOGSIZE) + SQLITE_POW2_LOGMIN); + int i = ((u8 *)p-mem5.zPool)/mem5.nAtom; + assert( i>=0 && i<mem5.nBlock ); + iSize = mem5.nAtom * (1 << (mem5.aCtrl[i]&CTRL_LOGSIZE)); } return iSize; } @@ -12624,12 +13388,12 @@ static int memsys5UnlinkFirst(int iLogsize){ int i; int iFirst; - assert( iLogsize>=0 && iLogsize<NSIZE ); - i = iFirst = mem.aiFreelist[iLogsize]; + assert( iLogsize>=0 && iLogsize<=LOGMAX ); + i = iFirst = mem5.aiFreelist[iLogsize]; assert( iFirst>=0 ); while( i>0 ){ if( i<iFirst ) iFirst = i; - i = mem.aPool[i].u.list.next; + i = MEM5LINK(i)->next; } memsys5Unlink(iFirst, iLogsize); return iFirst; @@ -12639,121 +13403,117 @@ static int memsys5UnlinkFirst(int iLogsize){ ** Return a block of memory of at least nBytes in size. ** Return NULL if unable. */ -static void *memsys5Malloc(int nByte){ - int i; /* Index of a mem.aPool[] slot */ - int iBin; /* Index into mem.aiFreelist[] */ +static void *memsys5MallocUnsafe(int nByte){ + int i; /* Index of a mem5.aPool[] slot */ + int iBin; /* Index into mem5.aiFreelist[] */ int iFullSz; /* Size of allocation rounded up to power of 2 */ int iLogsize; /* Log2 of iFullSz/POW2_MIN */ - assert( sqlite3_mutex_held(mem.mutex) ); - /* Keep track of the maximum allocation request. Even unfulfilled ** requests are counted */ - if( nByte>mem.maxRequest ){ - mem.maxRequest = nByte; + if( nByte>mem5.maxRequest ){ + mem5.maxRequest = nByte; } - /* Simulate a memory allocation fault */ - if( sqlite3FaultStep(SQLITE_FAULTINJECTOR_MALLOC) ) return 0; - /* Round nByte up to the next valid power of two */ if( nByte>POW2_MAX ) return 0; - for(iFullSz=POW2_MIN, iLogsize=0; iFullSz<nByte; iFullSz *= 2, iLogsize++){} - - /* If we will be over the memory alarm threshold after this allocation, - ** then trigger the memory overflow alarm */ - if( mem.alarmCallback!=0 && mem.currentOut+iFullSz>=mem.alarmThreshold ){ - memsys5Alarm(iFullSz); - } + for(iFullSz=mem5.nAtom, iLogsize=0; iFullSz<nByte; iFullSz *= 2, iLogsize++){} - /* Make sure mem.aiFreelist[iLogsize] contains at least one free + /* Make sure mem5.aiFreelist[iLogsize] contains at least one free ** block. If not, then split a block of the next larger power of ** two in order to create a new free block of size iLogsize. */ - for(iBin=iLogsize; mem.aiFreelist[iBin]<0 && iBin<NSIZE; iBin++){} - if( iBin>=NSIZE ) return 0; + for(iBin=iLogsize; mem5.aiFreelist[iBin]<0 && iBin<=LOGMAX; iBin++){} + if( iBin>LOGMAX ) return 0; i = memsys5UnlinkFirst(iBin); while( iBin>iLogsize ){ int newSize; iBin--; newSize = 1 << iBin; - mem.aCtrl[i+newSize] = CTRL_FREE | iBin; + mem5.aCtrl[i+newSize] = CTRL_FREE | iBin; memsys5Link(i+newSize, iBin); } - mem.aCtrl[i] = iLogsize; + mem5.aCtrl[i] = iLogsize; /* Update allocator performance statistics. */ - mem.nAlloc++; - mem.totalAlloc += iFullSz; - mem.totalExcess += iFullSz - nByte; - mem.currentCount++; - mem.currentOut += iFullSz; - if( mem.maxCount<mem.currentCount ) mem.maxCount = mem.currentCount; - if( mem.maxOut<mem.currentOut ) mem.maxOut = mem.currentOut; + mem5.nAlloc++; + mem5.totalAlloc += iFullSz; + mem5.totalExcess += iFullSz - nByte; + mem5.currentCount++; + mem5.currentOut += iFullSz; + if( mem5.maxCount<mem5.currentCount ) mem5.maxCount = mem5.currentCount; + if( mem5.maxOut<mem5.currentOut ) mem5.maxOut = mem5.currentOut; /* Return a pointer to the allocated memory. */ - return (void*)&mem.aPool[i]; + return (void*)&mem5.zPool[i*mem5.nAtom]; } /* ** Free an outstanding memory allocation. */ -void memsys5Free(void *pOld){ +static void memsys5FreeUnsafe(void *pOld){ u32 size, iLogsize; - int i; + int iBlock; + + /* Set iBlock to the index of the block pointed to by pOld in + ** the array of mem5.nAtom byte blocks pointed to by mem5.zPool. + */ + iBlock = ((u8 *)pOld-mem5.zPool)/mem5.nAtom; + + /* Check that the pointer pOld points to a valid, non-free block. */ + assert( iBlock>=0 && iBlock<mem5.nBlock ); + assert( ((u8 *)pOld-mem5.zPool)%mem5.nAtom==0 ); + assert( (mem5.aCtrl[iBlock] & CTRL_FREE)==0 ); - i = ((Mem5Block*)pOld) - mem.aPool; - assert( sqlite3_mutex_held(mem.mutex) ); - assert( i>=0 && i<NBLOCK ); - assert( (mem.aCtrl[i] & CTRL_FREE)==0 ); - iLogsize = mem.aCtrl[i] & CTRL_LOGSIZE; + iLogsize = mem5.aCtrl[iBlock] & CTRL_LOGSIZE; size = 1<<iLogsize; - assert( i+size-1<NBLOCK ); - mem.aCtrl[i] |= CTRL_FREE; - mem.aCtrl[i+size-1] |= CTRL_FREE; - assert( mem.currentCount>0 ); - assert( mem.currentOut>=0 ); - mem.currentCount--; - mem.currentOut -= size*POW2_MIN; - assert( mem.currentOut>0 || mem.currentCount==0 ); - assert( mem.currentCount>0 || mem.currentOut==0 ); - - mem.aCtrl[i] = CTRL_FREE | iLogsize; - while( iLogsize<NSIZE-1 ){ + assert( iBlock+size-1<mem5.nBlock ); + + mem5.aCtrl[iBlock] |= CTRL_FREE; + mem5.aCtrl[iBlock+size-1] |= CTRL_FREE; + assert( mem5.currentCount>0 ); + assert( mem5.currentOut>=0 ); + mem5.currentCount--; + mem5.currentOut -= size*mem5.nAtom; + assert( mem5.currentOut>0 || mem5.currentCount==0 ); + assert( mem5.currentCount>0 || mem5.currentOut==0 ); + + mem5.aCtrl[iBlock] = CTRL_FREE | iLogsize; + while( iLogsize<LOGMAX ){ int iBuddy; - - if( (i>>iLogsize) & 1 ){ - iBuddy = i - size; + if( (iBlock>>iLogsize) & 1 ){ + iBuddy = iBlock - size; }else{ - iBuddy = i + size; + iBuddy = iBlock + size; } - assert( iBuddy>=0 && iBuddy<NBLOCK ); - if( mem.aCtrl[iBuddy]!=(CTRL_FREE | iLogsize) ) break; + assert( iBuddy>=0 ); + if( (iBuddy+(1<<iLogsize))>mem5.nBlock ) break; + if( mem5.aCtrl[iBuddy]!=(CTRL_FREE | iLogsize) ) break; memsys5Unlink(iBuddy, iLogsize); iLogsize++; - if( iBuddy<i ){ - mem.aCtrl[iBuddy] = CTRL_FREE | iLogsize; - mem.aCtrl[i] = 0; - i = iBuddy; + if( iBuddy<iBlock ){ + mem5.aCtrl[iBuddy] = CTRL_FREE | iLogsize; + mem5.aCtrl[iBlock] = 0; + iBlock = iBuddy; }else{ - mem.aCtrl[i] = CTRL_FREE | iLogsize; - mem.aCtrl[iBuddy] = 0; + mem5.aCtrl[iBlock] = CTRL_FREE | iLogsize; + mem5.aCtrl[iBuddy] = 0; } size *= 2; } - memsys5Link(i, iLogsize); + memsys5Link(iBlock, iLogsize); } /* ** Allocate nBytes of memory */ -SQLITE_API void *sqlite3_malloc(int nBytes){ +static void *memsys5Malloc(int nBytes){ sqlite3_int64 *p = 0; if( nBytes>0 ){ memsys5Enter(); - p = memsys5Malloc(nBytes); - sqlite3_mutex_leave(mem.mutex); + p = memsys5MallocUnsafe(nBytes); + memsys5Leave(); } return (void*)p; } @@ -12761,52 +13521,116 @@ SQLITE_API void *sqlite3_malloc(int nBytes){ /* ** Free memory. */ -SQLITE_API void sqlite3_free(void *pPrior){ +static void memsys5Free(void *pPrior){ if( pPrior==0 ){ +assert(0); return; } - assert( mem.mutex!=0 ); - sqlite3_mutex_enter(mem.mutex); - memsys5Free(pPrior); - sqlite3_mutex_leave(mem.mutex); + memsys5Enter(); + memsys5FreeUnsafe(pPrior); + memsys5Leave(); } /* ** Change the size of an existing memory allocation */ -SQLITE_API void *sqlite3_realloc(void *pPrior, int nBytes){ +static void *memsys5Realloc(void *pPrior, int nBytes){ int nOld; void *p; if( pPrior==0 ){ - return sqlite3_malloc(nBytes); + return memsys5Malloc(nBytes); } if( nBytes<=0 ){ - sqlite3_free(pPrior); + memsys5Free(pPrior); return 0; } - assert( mem.mutex!=0 ); - nOld = sqlite3MallocSize(pPrior); + nOld = memsys5Size(pPrior); if( nBytes<=nOld ){ return pPrior; } - sqlite3_mutex_enter(mem.mutex); - p = memsys5Malloc(nBytes); + memsys5Enter(); + p = memsys5MallocUnsafe(nBytes); if( p ){ memcpy(p, pPrior, nOld); - memsys5Free(pPrior); + memsys5FreeUnsafe(pPrior); } - sqlite3_mutex_leave(mem.mutex); + memsys5Leave(); return p; } /* +** Round up a request size to the next valid allocation size. +*/ +static int memsys5Roundup(int n){ + int iFullSz; + for(iFullSz=mem5.nAtom; iFullSz<n; iFullSz *= 2); + return iFullSz; +} + +static int memsys5Log(int iValue){ + int iLog; + for(iLog=0; (1<<iLog)<iValue; iLog++); + return iLog; +} + +/* +** Initialize this module. +*/ +static int memsys5Init(void *NotUsed){ + int ii; + int nByte = sqlite3Config.nHeap; + u8 *zByte = (u8 *)sqlite3Config.pHeap; + int nMinLog; /* Log of minimum allocation size in bytes*/ + int iOffset; + + if( !zByte ){ + return SQLITE_ERROR; + } + + nMinLog = memsys5Log(sqlite3Config.mnReq); + mem5.nAtom = (1<<nMinLog); + while( sizeof(Mem5Link)>mem5.nAtom ){ + mem5.nAtom = mem5.nAtom << 1; + } + + mem5.nBlock = (nByte / (mem5.nAtom+sizeof(u8))); + mem5.zPool = zByte; + mem5.aCtrl = (u8 *)&mem5.zPool[mem5.nBlock*mem5.nAtom]; + + for(ii=0; ii<=LOGMAX; ii++){ + mem5.aiFreelist[ii] = -1; + } + + iOffset = 0; + for(ii=LOGMAX; ii>=0; ii--){ + int nAlloc = (1<<ii); + if( (iOffset+nAlloc)<=mem5.nBlock ){ + mem5.aCtrl[iOffset] = ii | CTRL_FREE; + memsys5Link(iOffset, ii); + iOffset += nAlloc; + } + assert((iOffset+nAlloc)>mem5.nBlock); + } + + return SQLITE_OK; +} + +/* +** Deinitialize this module. +*/ +static void memsys5Shutdown(void *NotUsed){ + return; +} + +/* ** Open the file indicated and write a log of all unfreed memory ** allocations into that log. */ -SQLITE_PRIVATE void sqlite3MemdebugDump(const char *zFilename){ +SQLITE_PRIVATE void sqlite3Memsys5Dump(const char *zFilename){ #ifdef SQLITE_DEBUG FILE *out; int i, j, n; + int nMinLog; if( zFilename==0 || zFilename[0]==0 ){ out = stdout; @@ -12819,19 +13643,20 @@ SQLITE_PRIVATE void sqlite3MemdebugDump(const char *zFilename){ } } memsys5Enter(); - for(i=0; i<NSIZE; i++){ - for(n=0, j=mem.aiFreelist[i]; j>=0; j = mem.aPool[j].u.list.next, n++){} - fprintf(out, "freelist items of size %d: %d\n", POW2_MIN << i, n); - } - fprintf(out, "mem.nAlloc = %llu\n", mem.nAlloc); - fprintf(out, "mem.totalAlloc = %llu\n", mem.totalAlloc); - fprintf(out, "mem.totalExcess = %llu\n", mem.totalExcess); - fprintf(out, "mem.currentOut = %u\n", mem.currentOut); - fprintf(out, "mem.currentCount = %u\n", mem.currentCount); - fprintf(out, "mem.maxOut = %u\n", mem.maxOut); - fprintf(out, "mem.maxCount = %u\n", mem.maxCount); - fprintf(out, "mem.maxRequest = %u\n", mem.maxRequest); - sqlite3_mutex_leave(mem.mutex); + nMinLog = memsys5Log(mem5.nAtom); + for(i=0; i<=LOGMAX && i+nMinLog<32; i++){ + for(n=0, j=mem5.aiFreelist[i]; j>=0; j = MEM5LINK(j)->next, n++){} + fprintf(out, "freelist items of size %d: %d\n", mem5.nAtom << i, n); + } + fprintf(out, "mem5.nAlloc = %llu\n", mem5.nAlloc); + fprintf(out, "mem5.totalAlloc = %llu\n", mem5.totalAlloc); + fprintf(out, "mem5.totalExcess = %llu\n", mem5.totalExcess); + fprintf(out, "mem5.currentOut = %u\n", mem5.currentOut); + fprintf(out, "mem5.currentCount = %u\n", mem5.currentCount); + fprintf(out, "mem5.maxOut = %u\n", mem5.maxOut); + fprintf(out, "mem5.maxCount = %u\n", mem5.maxCount); + fprintf(out, "mem5.maxRequest = %u\n", mem5.maxRequest); + memsys5Leave(); if( out==stdout ){ fflush(stdout); }else{ @@ -12840,10 +13665,526 @@ SQLITE_PRIVATE void sqlite3MemdebugDump(const char *zFilename){ #endif } +/* +** This routine is the only routine in this file with external +** linkage. It returns a pointer to a static sqlite3_mem_methods +** struct populated with the memsys5 methods. +*/ +SQLITE_PRIVATE const sqlite3_mem_methods *sqlite3MemGetMemsys5(void){ + static const sqlite3_mem_methods memsys5Methods = { + memsys5Malloc, + memsys5Free, + memsys5Realloc, + memsys5Size, + memsys5Roundup, + memsys5Init, + memsys5Shutdown, + 0 + }; + return &memsys5Methods; +} -#endif /* !SQLITE_POW2_MEMORY_SIZE */ +#endif /* SQLITE_ENABLE_MEMSYS5 */ /************** End of mem5.c ************************************************/ +/************** Begin file mem6.c ********************************************/ +/* +** 2008 July 24 +** +** The author disclaims copyright to this source code. In place of +** a legal notice, here is a blessing: +** +** May you do good and not evil. +** May you find forgiveness for yourself and forgive others. +** May you share freely, never taking more than you give. +** +************************************************************************* +** +** This file contains an alternative memory allocation system for SQLite. +** This system is implemented as a wrapper around the system provided +** by the operating system - vanilla malloc(), realloc() and free(). +** +** This system differentiates between requests for "small" allocations +** (by default those of 128 bytes or less) and "large" allocations (all +** others). The 256 byte threshhold is configurable at runtime. +** +** All requests for large allocations are passed through to the +** default system. +** +** Requests for small allocations are met by allocating space within +** one or more larger "chunks" of memory obtained from the default +** memory allocation system. Chunks of memory are usually 64KB or +** larger. The algorithm used to manage space within each chunk is +** the same as that used by mem5.c. +** +** This strategy is designed to prevent the default memory allocation +** system (usually the system malloc) from suffering from heap +** fragmentation. On some systems, heap fragmentation can cause a +** significant real-time slowdown. +** +** $Id$ +*/ + +#ifdef SQLITE_ENABLE_MEMSYS6 + + +/* +** Maximum size of any "small" allocation is ((1<<LOGMAX)*Mem6Chunk.nAtom). +** Mem6Chunk.nAtom is always at least 8, so this is not a practical +** limitation +*/ +#define LOGMAX 30 + +/* +** Default value for the "small" allocation size threshold. +*/ +#define SMALL_MALLOC_DEFAULT_THRESHOLD 256 + +/* +** Minimum size for a memory chunk. +*/ +#define MIN_CHUNKSIZE (1<<16) + +#define LOG2_MINALLOC 4 + + +typedef struct Mem6Chunk Mem6Chunk; +typedef struct Mem6Link Mem6Link; + +/* +** A minimum allocation is an instance of the following structure. +** Larger allocations are an array of these structures where the +** size of the array is a power of 2. +*/ +struct Mem6Link { + int next; /* Index of next free chunk */ + int prev; /* Index of previous free chunk */ +}; + +/* +** Masks used for mem5.aCtrl[] elements. +*/ +#define CTRL_LOGSIZE 0x1f /* Log2 Size of this block relative to POW2_MIN */ +#define CTRL_FREE 0x20 /* True if not checked out */ + +struct Mem6Chunk { + Mem6Chunk *pNext; + + /* + ** Lists of free blocks of various sizes. + */ + int aiFreelist[LOGMAX+1]; + + int nCheckedOut; /* Number of currently outstanding allocations */ + + /* + ** Space for tracking which blocks are checked out and the size + ** of each block. One byte per block. + */ + u8 *aCtrl; + + /* + ** Memory available for allocation + */ + int nAtom; /* Smallest possible allocation in bytes */ + int nBlock; /* Number of nAtom sized blocks in zPool */ + u8 *zPool; /* Pointer to memory chunk from which allocations are made */ +}; + +#define MEM6LINK(idx) ((Mem6Link *)(&pChunk->zPool[(idx)*pChunk->nAtom])) + +struct Mem6Global { + int nMinAlloc; /* Minimum allowed allocation size */ + int nThreshold; /* Allocs larger than this go to malloc() */ + int nLogThreshold; /* log2 of (nThreshold/nMinAlloc) */ + sqlite3_mutex *mutex; + Mem6Chunk *pChunk; /* Singly linked list of all memory chunks */ +} mem6; + +/* +** Unlink the chunk at pChunk->aPool[i] from list it is currently +** on. It should be found on pChunk->aiFreelist[iLogsize]. +*/ +static void memsys6Unlink(Mem6Chunk *pChunk, int i, int iLogsize){ + int next, prev; + assert( i>=0 && i<pChunk->nBlock ); + assert( iLogsize>=0 && iLogsize<=mem6.nLogThreshold ); + assert( (pChunk->aCtrl[i] & CTRL_LOGSIZE)==iLogsize ); + + next = MEM6LINK(i)->next; + prev = MEM6LINK(i)->prev; + if( prev<0 ){ + pChunk->aiFreelist[iLogsize] = next; + }else{ + MEM6LINK(prev)->next = next; + } + if( next>=0 ){ + MEM6LINK(next)->prev = prev; + } +} + +/* +** Link the chunk at mem5.aPool[i] so that is on the iLogsize +** free list. +*/ +static void memsys6Link(Mem6Chunk *pChunk, int i, int iLogsize){ + int x; + assert( i>=0 && i<pChunk->nBlock ); + assert( iLogsize>=0 && iLogsize<=mem6.nLogThreshold ); + assert( (pChunk->aCtrl[i] & CTRL_LOGSIZE)==iLogsize ); + + x = MEM6LINK(i)->next = pChunk->aiFreelist[iLogsize]; + MEM6LINK(i)->prev = -1; + if( x>=0 ){ + assert( x<pChunk->nBlock ); + MEM6LINK(x)->prev = i; + } + pChunk->aiFreelist[iLogsize] = i; +} + + +/* +** Find the first entry on the freelist iLogsize. Unlink that +** entry and return its index. +*/ +static int memsys6UnlinkFirst(Mem6Chunk *pChunk, int iLogsize){ + int i; + int iFirst; + + assert( iLogsize>=0 && iLogsize<=mem6.nLogThreshold ); + i = iFirst = pChunk->aiFreelist[iLogsize]; + assert( iFirst>=0 ); + memsys6Unlink(pChunk, iFirst, iLogsize); + return iFirst; +} + +static int roundupLog2(int n){ + static const char LogTable256[256] = { + 0, /* 1 */ + 1, /* 2 */ + 2, 2, /* 3..4 */ + 3, 3, 3, 3, /* 5..8 */ + 4, 4, 4, 4, 4, 4, 4, 4, /* 9..16 */ + 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, /* 17..32 */ + 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, + 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, /* 33..64 */ + 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, + 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, + 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, + 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, /* 65..128 */ + 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, + 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, + 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, + 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, + 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, + 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, + 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, + 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, /* 129..256 */ + }; + + assert(n<=(1<<16) && n>0); + if( n<=256 ) return LogTable256[n-1]; + return LogTable256[(n>>8) - ((n&0xFF)?0:1)] + 8; +} + +/* +** Allocate and return a block of (pChunk->nAtom << iLogsize) bytes from chunk +** pChunk. If the allocation request cannot be satisfied, return 0. +*/ +static void *chunkMalloc(Mem6Chunk *pChunk, int iLogsize){ + int i; /* Index of a mem5.aPool[] slot */ + int iBin; /* Index into mem5.aiFreelist[] */ + + /* Make sure mem5.aiFreelist[iLogsize] contains at least one free + ** block. If not, then split a block of the next larger power of + ** two in order to create a new free block of size iLogsize. + */ + for(iBin=iLogsize; pChunk->aiFreelist[iBin]<0 && iBin<=mem6.nLogThreshold; iBin++){} + if( iBin>mem6.nLogThreshold ) return 0; + i = memsys6UnlinkFirst(pChunk, iBin); + while( iBin>iLogsize ){ + int newSize; + iBin--; + newSize = 1 << iBin; + pChunk->aCtrl[i+newSize] = CTRL_FREE | iBin; + memsys6Link(pChunk, i+newSize, iBin); + } + pChunk->aCtrl[i] = iLogsize; + + /* Return a pointer to the allocated memory. */ + pChunk->nCheckedOut++; + return (void*)&pChunk->zPool[i*pChunk->nAtom]; +} + +/* +** Free the allocation pointed to by p, which is guaranteed to be non-zero +** and a part of chunk object pChunk. +*/ +static void chunkFree(Mem6Chunk *pChunk, void *pOld){ + u32 size, iLogsize; + int iBlock; + + /* Set iBlock to the index of the block pointed to by pOld in + ** the array of pChunk->nAtom byte blocks pointed to by pChunk->zPool. + */ + iBlock = ((u8 *)pOld-pChunk->zPool)/pChunk->nAtom; + + /* Check that the pointer pOld points to a valid, non-free block. */ + assert( iBlock>=0 && iBlock<pChunk->nBlock ); + assert( ((u8 *)pOld-pChunk->zPool)%pChunk->nAtom==0 ); + assert( (pChunk->aCtrl[iBlock] & CTRL_FREE)==0 ); + + iLogsize = pChunk->aCtrl[iBlock] & CTRL_LOGSIZE; + size = 1<<iLogsize; + assert( iBlock+size-1<pChunk->nBlock ); + + pChunk->aCtrl[iBlock] |= CTRL_FREE; + pChunk->aCtrl[iBlock+size-1] |= CTRL_FREE; + + pChunk->aCtrl[iBlock] = CTRL_FREE | iLogsize; + while( iLogsize<mem6.nLogThreshold ){ + int iBuddy; + if( (iBlock>>iLogsize) & 1 ){ + iBuddy = iBlock - size; + }else{ + iBuddy = iBlock + size; + } + assert( iBuddy>=0 ); + if( (iBuddy+(1<<iLogsize))>pChunk->nBlock ) break; + if( pChunk->aCtrl[iBuddy]!=(CTRL_FREE | iLogsize) ) break; + memsys6Unlink(pChunk, iBuddy, iLogsize); + iLogsize++; + if( iBuddy<iBlock ){ + pChunk->aCtrl[iBuddy] = CTRL_FREE | iLogsize; + pChunk->aCtrl[iBlock] = 0; + iBlock = iBuddy; + }else{ + pChunk->aCtrl[iBlock] = CTRL_FREE | iLogsize; + pChunk->aCtrl[iBuddy] = 0; + } + size *= 2; + } + pChunk->nCheckedOut--; + memsys6Link(pChunk, iBlock, iLogsize); +} + +/* +** Return the actual size of the block pointed to by p, which is guaranteed +** to have been allocated from chunk pChunk. +*/ +static int chunkSize(Mem6Chunk *pChunk, void *p){ + int iSize = 0; + if( p ){ + int i = ((u8 *)p-pChunk->zPool)/pChunk->nAtom; + assert( i>=0 && i<pChunk->nBlock ); + iSize = pChunk->nAtom * (1 << (pChunk->aCtrl[i]&CTRL_LOGSIZE)); + } + return iSize; +} + +/* +** Return true if there are currently no outstanding allocations. +*/ +static int chunkIsEmpty(Mem6Chunk *pChunk){ + return (pChunk->nCheckedOut==0); +} + +/* +** Initialize the buffer zChunk, which is nChunk bytes in size, as +** an Mem6Chunk object. Return a copy of the zChunk pointer. +*/ +static Mem6Chunk *chunkInit(u8 *zChunk, int nChunk, int nMinAlloc){ + int ii; + int iOffset; + Mem6Chunk *pChunk = (Mem6Chunk *)zChunk; + + assert( nChunk>sizeof(Mem6Chunk) ); + assert( nMinAlloc>sizeof(Mem6Link) ); + + memset(pChunk, 0, sizeof(Mem6Chunk)); + pChunk->nAtom = nMinAlloc; + pChunk->nBlock = ((nChunk-sizeof(Mem6Chunk)) / (pChunk->nAtom+sizeof(u8))); + + pChunk->zPool = (u8 *)&pChunk[1]; + pChunk->aCtrl = &pChunk->zPool[pChunk->nBlock*pChunk->nAtom]; + + for(ii=0; ii<=mem6.nLogThreshold; ii++){ + pChunk->aiFreelist[ii] = -1; + } + + iOffset = 0; + for(ii=mem6.nLogThreshold; ii>=0; ii--){ + int nAlloc = (1<<ii); + while( (iOffset+nAlloc)<=pChunk->nBlock ){ + pChunk->aCtrl[iOffset] = ii | CTRL_FREE; + memsys6Link(pChunk, iOffset, ii); + iOffset += nAlloc; + } + } + + return pChunk; +} + + +static void mem6Enter(void){ + sqlite3_mutex_enter(mem6.mutex); +} + +static void mem6Leave(void){ + sqlite3_mutex_leave(mem6.mutex); +} + +/* +** Based on the number and size of the currently allocated chunks, return +** the size of the next chunk to allocate, in bytes. +*/ +static int nextChunkSize(void){ + int iTotal = MIN_CHUNKSIZE; + Mem6Chunk *p; + for(p=mem6.pChunk; p; p=p->pNext){ + iTotal = iTotal*2; + } + return iTotal; +} + +static void freeChunk(Mem6Chunk *pChunk){ + Mem6Chunk **pp = &mem6.pChunk; + for( pp=&mem6.pChunk; *pp!=pChunk; pp = &(*pp)->pNext ); + *pp = (*pp)->pNext; + free(pChunk); +} + +static void *memsys6Malloc(int nByte){ + Mem6Chunk *pChunk; + void *p = 0; + int nTotal = nByte+8; + int iOffset = 0; + + if( nTotal>mem6.nThreshold ){ + p = malloc(nTotal); + }else{ + int iLogsize = 0; + if( nTotal>(1<<LOG2_MINALLOC) ){ + iLogsize = roundupLog2(nTotal) - LOG2_MINALLOC; + } + mem6Enter(); + for(pChunk=mem6.pChunk; pChunk; pChunk=pChunk->pNext){ + p = chunkMalloc(pChunk, iLogsize); + if( p ){ + break; + } + } + if( !p ){ + int iSize = nextChunkSize(); + p = malloc(iSize); + if( p ){ + pChunk = chunkInit((u8 *)p, iSize, mem6.nMinAlloc); + pChunk->pNext = mem6.pChunk; + mem6.pChunk = pChunk; + p = chunkMalloc(pChunk, iLogsize); + assert(p); + } + } + iOffset = ((u8*)p - (u8*)pChunk); + mem6Leave(); + } + + if( !p ){ + return 0; + } + ((u32 *)p)[0] = iOffset; + ((u32 *)p)[1] = nByte; + return &((u32 *)p)[2]; +} + +static int memsys6Size(void *pPrior){ + if( pPrior==0 ) return 0; + return ((u32*)pPrior)[-1]; +} + +static void memsys6Free(void *pPrior){ + int iSlot; + void *p = &((u32 *)pPrior)[-2]; + iSlot = ((u32 *)p)[0]; + if( iSlot ){ + Mem6Chunk *pChunk; + mem6Enter(); + pChunk = (Mem6Chunk *)(&((u8 *)p)[-1 * iSlot]); + chunkFree(pChunk, p); + if( chunkIsEmpty(pChunk) ){ + freeChunk(pChunk); + } + mem6Leave(); + }else{ + free(p); + } +} + +static void *memsys6Realloc(void *p, int nByte){ + void *p2; + + if( p && nByte<=memsys6Size(p) ){ + p2 = p; + }else{ + p2 = memsys6Malloc(nByte); + if( p && p2 ){ + memcpy(p2, p, memsys6Size(p)); + memsys6Free(p); + } + } + + return p2; +} + +static int memsys6Roundup(int n){ + if( n>mem6.nThreshold ){ + return n; + }else{ + return (1<<roundupLog2(n)); + } +} + +static int memsys6Init(void *pCtx){ + u8 bMemstat = sqlite3Config.bMemstat; + mem6.nMinAlloc = (1 << LOG2_MINALLOC); + mem6.pChunk = 0; + mem6.nThreshold = sqlite3Config.nSmall; + if( mem6.nThreshold<=0 ){ + mem6.nThreshold = SMALL_MALLOC_DEFAULT_THRESHOLD; + } + mem6.nLogThreshold = roundupLog2(mem6.nThreshold) - LOG2_MINALLOC; + if( !bMemstat ){ + mem6.mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM); + } + return SQLITE_OK; +} + +static void memsys6Shutdown(void *pCtx){ + memset(&mem6, 0, sizeof(mem6)); +} + +/* +** This routine is the only routine in this file with external +** linkage. It returns a pointer to a static sqlite3_mem_methods +** struct populated with the memsys6 methods. +*/ +SQLITE_PRIVATE const sqlite3_mem_methods *sqlite3MemGetMemsys6(void){ + static const sqlite3_mem_methods memsys6Methods = { + memsys6Malloc, + memsys6Free, + memsys6Realloc, + memsys6Size, + memsys6Roundup, + memsys6Init, + memsys6Shutdown, + 0 + }; + return &memsys6Methods; +} + +#endif + +/************** End of mem6.c ************************************************/ /************** Begin file mutex.c *******************************************/ /* ** 2007 August 14 @@ -12869,6 +14210,134 @@ SQLITE_PRIVATE void sqlite3MemdebugDump(const char *zFilename){ ** $Id$ */ +#ifndef SQLITE_MUTEX_NOOP +/* +** Initialize the mutex system. +*/ +SQLITE_PRIVATE int sqlite3MutexInit(void){ + int rc = SQLITE_OK; + if( sqlite3Config.bCoreMutex ){ + if( !sqlite3Config.mutex.xMutexAlloc ){ + /* If the xMutexAlloc method has not been set, then the user did not + ** install a mutex implementation via sqlite3_config() prior to + ** sqlite3_initialize() being called. This block copies pointers to + ** the default implementation into the sqlite3Config structure. + ** + ** The danger is that although sqlite3_config() is not a threadsafe + ** API, sqlite3_initialize() is, and so multiple threads may be + ** attempting to run this function simultaneously. To guard write + ** access to the sqlite3Config structure, the 'MASTER' static mutex + ** is obtained before modifying it. + */ + sqlite3_mutex_methods *p = sqlite3DefaultMutex(); + sqlite3_mutex *pMaster = 0; + + rc = p->xMutexInit(); + if( rc==SQLITE_OK ){ + pMaster = p->xMutexAlloc(SQLITE_MUTEX_STATIC_MASTER); + assert(pMaster); + p->xMutexEnter(pMaster); + assert( sqlite3Config.mutex.xMutexAlloc==0 + || sqlite3Config.mutex.xMutexAlloc==p->xMutexAlloc + ); + if( !sqlite3Config.mutex.xMutexAlloc ){ + sqlite3Config.mutex = *p; + } + p->xMutexLeave(pMaster); + } + }else{ + rc = sqlite3Config.mutex.xMutexInit(); + } + } + + return rc; +} + +/* +** Shutdown the mutex system. This call frees resources allocated by +** sqlite3MutexInit(). +*/ +SQLITE_PRIVATE int sqlite3MutexEnd(void){ + int rc = SQLITE_OK; + rc = sqlite3Config.mutex.xMutexEnd(); + return rc; +} + +/* +** Retrieve a pointer to a static mutex or allocate a new dynamic one. +*/ +SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int id){ +#ifndef SQLITE_OMIT_AUTOINIT + if( sqlite3_initialize() ) return 0; +#endif + return sqlite3Config.mutex.xMutexAlloc(id); +} + +SQLITE_PRIVATE sqlite3_mutex *sqlite3MutexAlloc(int id){ + if( !sqlite3Config.bCoreMutex ){ + return 0; + } + return sqlite3Config.mutex.xMutexAlloc(id); +} + +/* +** Free a dynamic mutex. +*/ +SQLITE_API void sqlite3_mutex_free(sqlite3_mutex *p){ + if( p ){ + sqlite3Config.mutex.xMutexFree(p); + } +} + +/* +** Obtain the mutex p. If some other thread already has the mutex, block +** until it can be obtained. +*/ +SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex *p){ + if( p ){ + sqlite3Config.mutex.xMutexEnter(p); + } +} + +/* +** Obtain the mutex p. If successful, return SQLITE_OK. Otherwise, if another +** thread holds the mutex and it cannot be obtained, return SQLITE_BUSY. +*/ +SQLITE_API int sqlite3_mutex_try(sqlite3_mutex *p){ + int rc = SQLITE_OK; + if( p ){ + return sqlite3Config.mutex.xMutexTry(p); + } + return rc; +} + +/* +** The sqlite3_mutex_leave() routine exits a mutex that was previously +** entered by the same thread. The behavior is undefined if the mutex +** is not currently entered. If a NULL pointer is passed as an argument +** this function is a no-op. +*/ +SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex *p){ + if( p ){ + sqlite3Config.mutex.xMutexLeave(p); + } +} + +#ifndef NDEBUG +/* +** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are +** intended for use inside assert() statements. +*/ +SQLITE_API int sqlite3_mutex_held(sqlite3_mutex *p){ + return p==0 || sqlite3Config.mutex.xMutexHeld(p); +} +SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex *p){ + return p==0 || sqlite3Config.mutex.xMutexNotheld(p); +} +#endif + +#endif + #ifdef SQLITE_MUTEX_NOOP_DEBUG /* ** In this implementation, mutexes do not provide any mutual exclusion. @@ -12885,17 +14354,34 @@ struct sqlite3_mutex { }; /* +** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are +** intended for use inside assert() statements. +*/ +static int noopMutexHeld(sqlite3_mutex *p){ + return p==0 || p->cnt>0; +} +static int noopMutexNotheld(sqlite3_mutex *p){ + return p==0 || p->cnt==0; +} + +/* +** Initialize and deinitialize the mutex subsystem. +*/ +static int noopMutexInit(void){ return SQLITE_OK; } +static int noopMutexEnd(void){ return SQLITE_OK; } + +/* ** The sqlite3_mutex_alloc() routine allocates a new ** mutex and returns a pointer to it. If it returns NULL ** that means that a mutex could not be allocated. */ -SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int id){ +static sqlite3_mutex *noopMutexAlloc(int id){ static sqlite3_mutex aStatic[6]; sqlite3_mutex *pNew = 0; switch( id ){ case SQLITE_MUTEX_FAST: case SQLITE_MUTEX_RECURSIVE: { - pNew = sqlite3_malloc(sizeof(*pNew)); + pNew = sqlite3Malloc(sizeof(*pNew)); if( pNew ){ pNew->id = id; pNew->cnt = 0; @@ -12916,8 +14402,7 @@ SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int id){ /* ** This routine deallocates a previously allocated mutex. */ -SQLITE_API void sqlite3_mutex_free(sqlite3_mutex *p){ - assert( p ); +static void noopMutexFree(sqlite3_mutex *p){ assert( p->cnt==0 ); assert( p->id==SQLITE_MUTEX_FAST || p->id==SQLITE_MUTEX_RECURSIVE ); sqlite3_free(p); @@ -12934,14 +14419,12 @@ SQLITE_API void sqlite3_mutex_free(sqlite3_mutex *p){ ** can enter. If the same thread tries to enter any other kind of mutex ** more than once, the behavior is undefined. */ -SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex *p){ - assert( p ); - assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) ); +static void noopMutexEnter(sqlite3_mutex *p){ + assert( p->id==SQLITE_MUTEX_RECURSIVE || noopMutexNotheld(p) ); p->cnt++; } -SQLITE_API int sqlite3_mutex_try(sqlite3_mutex *p){ - assert( p ); - assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) ); +static int noopMutexTry(sqlite3_mutex *p){ + assert( p->id==SQLITE_MUTEX_RECURSIVE || noopMutexNotheld(p) ); p->cnt++; return SQLITE_OK; } @@ -12952,22 +14435,27 @@ SQLITE_API int sqlite3_mutex_try(sqlite3_mutex *p){ ** is undefined if the mutex is not currently entered or ** is not currently allocated. SQLite will never do either. */ -SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex *p){ - assert( p ); - assert( sqlite3_mutex_held(p) ); +static void noopMutexLeave(sqlite3_mutex *p){ + assert( noopMutexHeld(p) ); p->cnt--; - assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) ); + assert( p->id==SQLITE_MUTEX_RECURSIVE || noopMutexNotheld(p) ); } -/* -** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are -** intended for use inside assert() statements. -*/ -SQLITE_API int sqlite3_mutex_held(sqlite3_mutex *p){ - return p==0 || p->cnt>0; -} -SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex *p){ - return p==0 || p->cnt==0; +SQLITE_PRIVATE sqlite3_mutex_methods *sqlite3DefaultMutex(void){ + static sqlite3_mutex_methods sMutex = { + noopMutexInit, + noopMutexEnd, + noopMutexAlloc, + noopMutexFree, + noopMutexEnter, + noopMutexTry, + noopMutexLeave, + + noopMutexHeld, + noopMutexNotheld + }; + + return &sMutex; } #endif /* SQLITE_MUTEX_NOOP_DEBUG */ @@ -13014,6 +14502,12 @@ struct sqlite3_mutex { #define OS2_MUTEX_INITIALIZER 0,0,0,0 /* +** Initialize and deinitialize the mutex subsystem. +*/ +static int os2MutexInit(void){ return SQLITE_OK; } +static int os2MutexEnd(void){ return SQLITE_OK; } + +/* ** The sqlite3_mutex_alloc() routine allocates a new ** mutex and returns a pointer to it. If it returns NULL ** that means that a mutex could not be allocated. @@ -13052,7 +14546,7 @@ struct sqlite3_mutex { ** mutex types, the same mutex is returned on every call that has ** the same type number. */ -SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int iType){ +static sqlite3_mutex *os2MutexAlloc(int iType){ sqlite3_mutex *p = NULL; switch( iType ){ case SQLITE_MUTEX_FAST: @@ -13120,8 +14614,8 @@ SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int iType){ ** This routine deallocates a previously allocated mutex. ** SQLite is careful to deallocate every mutex that it allocates. */ -SQLITE_API void sqlite3_mutex_free(sqlite3_mutex *p){ - assert( p ); +static void os2MutexFree(sqlite3_mutex *p){ + if( p==0 ) return; assert( p->nRef==0 ); assert( p->id==SQLITE_MUTEX_FAST || p->id==SQLITE_MUTEX_RECURSIVE ); DosCloseMutexSem( p->mutex ); @@ -13139,24 +14633,24 @@ SQLITE_API void sqlite3_mutex_free(sqlite3_mutex *p){ ** can enter. If the same thread tries to enter any other kind of mutex ** more than once, the behavior is undefined. */ -SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex *p){ +static void os2MutexEnter(sqlite3_mutex *p){ TID tid; PID holder1; ULONG holder2; - assert( p ); - assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) ); + if( p==0 ) return; + assert( p->id==SQLITE_MUTEX_RECURSIVE || os2MutexNotheld(p) ); DosRequestMutexSem(p->mutex, SEM_INDEFINITE_WAIT); DosQueryMutexSem(p->mutex, &holder1, &tid, &holder2); p->owner = tid; p->nRef++; } -SQLITE_API int sqlite3_mutex_try(sqlite3_mutex *p){ +static int os2MutexTry(sqlite3_mutex *p){ int rc; TID tid; PID holder1; ULONG holder2; - assert( p ); - assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) ); + if( p==0 ) return SQLITE_OK; + assert( p->id==SQLITE_MUTEX_RECURSIVE || os2MutexNotheld(p) ); if( DosRequestMutexSem(p->mutex, SEM_IMMEDIATE_RETURN) == NO_ERROR) { DosQueryMutexSem(p->mutex, &holder1, &tid, &holder2); p->owner = tid; @@ -13175,10 +14669,11 @@ SQLITE_API int sqlite3_mutex_try(sqlite3_mutex *p){ ** is undefined if the mutex is not currently entered or ** is not currently allocated. SQLite will never do either. */ -SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex *p){ +static void os2MutexLeave(sqlite3_mutex *p){ TID tid; PID holder1; ULONG holder2; + if( p==0 ) return; assert( p->nRef>0 ); DosQueryMutexSem(p->mutex, &holder1, &tid, &holder2); assert( p->owner==tid ); @@ -13187,11 +14682,12 @@ SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex *p){ DosReleaseMutexSem(p->mutex); } +#ifdef SQLITE_DEBUG /* ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are ** intended for use inside assert() statements. */ -SQLITE_API int sqlite3_mutex_held(sqlite3_mutex *p){ +static int os2MutexHeld(sqlite3_mutex *p){ TID tid; PID pid; ULONG ulCount; @@ -13204,7 +14700,7 @@ SQLITE_API int sqlite3_mutex_held(sqlite3_mutex *p){ } return p==0 || (p->nRef!=0 && p->owner==tid); } -SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex *p){ +static int os2MutexNotheld(sqlite3_mutex *p){ TID tid; PID pid; ULONG ulCount; @@ -13217,6 +14713,25 @@ SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex *p){ } return p==0 || p->nRef==0 || p->owner!=tid; } +#endif + +SQLITE_PRIVATE sqlite3_mutex_methods *sqlite3DefaultMutex(void){ + static sqlite3_mutex_methods sMutex = { + os2MutexInit, + os2MutexEnd, + os2MutexAlloc, + os2MutexFree, + os2MutexEnter, + os2MutexTry, + os2MutexLeave, +#ifdef SQLITE_DEBUG + os2MutexHeld, + os2MutexNotheld +#endif + }; + + return &sMutex; +} #endif /* SQLITE_MUTEX_OS2 */ /************** End of mutex_os2.c *******************************************/ @@ -13268,6 +14783,37 @@ struct sqlite3_mutex { #endif /* +** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are +** intended for use only inside assert() statements. On some platforms, +** there might be race conditions that can cause these routines to +** deliver incorrect results. In particular, if pthread_equal() is +** not an atomic operation, then these routines might delivery +** incorrect results. On most platforms, pthread_equal() is a +** comparison of two integers and is therefore atomic. But we are +** told that HPUX is not such a platform. If so, then these routines +** will not always work correctly on HPUX. +** +** On those platforms where pthread_equal() is not atomic, SQLite +** should be compiled without -DSQLITE_DEBUG and with -DNDEBUG to +** make sure no assert() statements are evaluated and hence these +** routines are never called. +*/ +#ifndef NDEBUG +static int pthreadMutexHeld(sqlite3_mutex *p){ + return (p->nRef!=0 && pthread_equal(p->owner, pthread_self())); +} +static int pthreadMutexNotheld(sqlite3_mutex *p){ + return p->nRef==0 || pthread_equal(p->owner, pthread_self())==0; +} +#endif + +/* +** Initialize and deinitialize the mutex subsystem. +*/ +static int pthreadMutexInit(void){ return SQLITE_OK; } +static int pthreadMutexEnd(void){ return SQLITE_OK; } + +/* ** The sqlite3_mutex_alloc() routine allocates a new ** mutex and returns a pointer to it. If it returns NULL ** that means that a mutex could not be allocated. SQLite @@ -13308,7 +14854,7 @@ struct sqlite3_mutex { ** mutex types, the same mutex is returned on every call that has ** the same type number. */ -SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int iType){ +static sqlite3_mutex *pthreadMutexAlloc(int iType){ static sqlite3_mutex staticMutexes[] = { SQLITE3_MUTEX_INITIALIZER, SQLITE3_MUTEX_INITIALIZER, @@ -13363,8 +14909,7 @@ SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int iType){ ** allocated mutex. SQLite is careful to deallocate every ** mutex that it allocates. */ -SQLITE_API void sqlite3_mutex_free(sqlite3_mutex *p){ - assert( p ); +static void pthreadMutexFree(sqlite3_mutex *p){ assert( p->nRef==0 ); assert( p->id==SQLITE_MUTEX_FAST || p->id==SQLITE_MUTEX_RECURSIVE ); pthread_mutex_destroy(&p->mutex); @@ -13382,9 +14927,8 @@ SQLITE_API void sqlite3_mutex_free(sqlite3_mutex *p){ ** can enter. If the same thread tries to enter any other kind of mutex ** more than once, the behavior is undefined. */ -SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex *p){ - assert( p ); - assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) ); +static void pthreadMutexEnter(sqlite3_mutex *p){ + assert( p->id==SQLITE_MUTEX_RECURSIVE || pthreadMutexNotheld(p) ); #ifdef SQLITE_HOMEGROWN_RECURSIVE_MUTEX /* If recursive mutexes are not available, then we have to grow @@ -13422,10 +14966,9 @@ SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex *p){ } #endif } -SQLITE_API int sqlite3_mutex_try(sqlite3_mutex *p){ +static int pthreadMutexTry(sqlite3_mutex *p){ int rc; - assert( p ); - assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) ); + assert( p->id==SQLITE_MUTEX_RECURSIVE || pthreadMutexNotheld(p) ); #ifdef SQLITE_HOMEGROWN_RECURSIVE_MUTEX /* If recursive mutexes are not available, then we have to grow @@ -13443,7 +14986,7 @@ SQLITE_API int sqlite3_mutex_try(sqlite3_mutex *p){ if( p->nRef>0 && pthread_equal(p->owner, self) ){ p->nRef++; rc = SQLITE_OK; - }else if( pthread_mutex_lock(&p->mutex)==0 ){ + }else if( pthread_mutex_trylock(&p->mutex)==0 ){ assert( p->nRef==0 ); p->owner = self; p->nRef = 1; @@ -13478,9 +15021,8 @@ SQLITE_API int sqlite3_mutex_try(sqlite3_mutex *p){ ** is undefined if the mutex is not currently entered or ** is not currently allocated. SQLite will never do either. */ -SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex *p){ - assert( p ); - assert( sqlite3_mutex_held(p) ); +static void pthreadMutexLeave(sqlite3_mutex *p){ + assert( pthreadMutexHeld(p) ); p->nRef--; assert( p->nRef==0 || p->id==SQLITE_MUTEX_RECURSIVE ); @@ -13499,30 +15041,24 @@ SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex *p){ #endif } -/* -** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are -** intended for use only inside assert() statements. On some platforms, -** there might be race conditions that can cause these routines to -** deliver incorrect results. In particular, if pthread_equal() is -** not an atomic operation, then these routines might delivery -** incorrect results. On most platforms, pthread_equal() is a -** comparison of two integers and is therefore atomic. But we are -** told that HPUX is not such a platform. If so, then these routines -** will not always work correctly on HPUX. -** -** On those platforms where pthread_equal() is not atomic, SQLite -** should be compiled without -DSQLITE_DEBUG and with -DNDEBUG to -** make sure no assert() statements are evaluated and hence these -** routines are never called. -*/ -#ifndef NDEBUG -SQLITE_API int sqlite3_mutex_held(sqlite3_mutex *p){ - return p==0 || (p->nRef!=0 && pthread_equal(p->owner, pthread_self())); -} -SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex *p){ - return p==0 || p->nRef==0 || pthread_equal(p->owner, pthread_self())==0; -} +SQLITE_PRIVATE sqlite3_mutex_methods *sqlite3DefaultMutex(void){ + static sqlite3_mutex_methods sMutex = { + pthreadMutexInit, + pthreadMutexEnd, + pthreadMutexAlloc, + pthreadMutexFree, + pthreadMutexEnter, + pthreadMutexTry, + pthreadMutexLeave, +#ifdef SQLITE_DEBUG + pthreadMutexHeld, + pthreadMutexNotheld #endif + }; + + return &sMutex; +} + #endif /* SQLITE_MUTEX_PTHREAD */ /************** End of mutex_unix.c ******************************************/ @@ -13570,7 +15106,7 @@ struct sqlite3_mutex { ** WinNT/2K/XP so that we will know whether or not we can safely call ** the LockFileEx() API. */ -#if OS_WINCE +#if SQLITE_OS_WINCE # define mutexIsNT() (1) #else static int mutexIsNT(void){ @@ -13583,10 +15119,30 @@ struct sqlite3_mutex { } return osType==2; } -#endif /* OS_WINCE */ +#endif /* SQLITE_OS_WINCE */ + + +#ifdef SQLITE_DEBUG +/* +** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are +** intended for use only inside assert() statements. +*/ +static int winMutexHeld(sqlite3_mutex *p){ + return p->nRef!=0 && p->owner==GetCurrentThreadId(); +} +static int winMutexNotheld(sqlite3_mutex *p){ + return p->nRef==0 || p->owner!=GetCurrentThreadId(); +} +#endif /* +** Initialize and deinitialize the mutex subsystem. +*/ +static int winMutexInit(void){ return SQLITE_OK; } +static int winMutexEnd(void){ return SQLITE_OK; } + +/* ** The sqlite3_mutex_alloc() routine allocates a new ** mutex and returns a pointer to it. If it returns NULL ** that means that a mutex could not be allocated. SQLite @@ -13625,7 +15181,7 @@ struct sqlite3_mutex { ** mutex types, the same mutex is returned on every call that has ** the same type number. */ -SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int iType){ +static sqlite3_mutex *winMutexAlloc(int iType){ sqlite3_mutex *p; switch( iType ){ @@ -13669,7 +15225,7 @@ SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int iType){ ** allocated mutex. SQLite is careful to deallocate every ** mutex that it allocates. */ -SQLITE_API void sqlite3_mutex_free(sqlite3_mutex *p){ +static void winMutexFree(sqlite3_mutex *p){ assert( p ); assert( p->nRef==0 ); assert( p->id==SQLITE_MUTEX_FAST || p->id==SQLITE_MUTEX_RECURSIVE ); @@ -13688,17 +15244,15 @@ SQLITE_API void sqlite3_mutex_free(sqlite3_mutex *p){ ** can enter. If the same thread tries to enter any other kind of mutex ** more than once, the behavior is undefined. */ -SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex *p){ - assert( p ); - assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) ); +static void winMutexEnter(sqlite3_mutex *p){ + assert( p->id==SQLITE_MUTEX_RECURSIVE || winMutexNotheld(p) ); EnterCriticalSection(&p->mutex); p->owner = GetCurrentThreadId(); p->nRef++; } -SQLITE_API int sqlite3_mutex_try(sqlite3_mutex *p){ +static int winMutexTry(sqlite3_mutex *p){ int rc = SQLITE_BUSY; - assert( p ); - assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) ); + assert( p->id==SQLITE_MUTEX_RECURSIVE || winMutexNotheld(p) ); /* ** The sqlite3_mutex_try() routine is very rarely used, and when it ** is used it is merely an optimization. So it is OK for it to always @@ -13726,7 +15280,7 @@ SQLITE_API int sqlite3_mutex_try(sqlite3_mutex *p){ ** is undefined if the mutex is not currently entered or ** is not currently allocated. SQLite will never do either. */ -SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex *p){ +static void winMutexLeave(sqlite3_mutex *p){ assert( p->nRef>0 ); assert( p->owner==GetCurrentThreadId() ); p->nRef--; @@ -13734,15 +15288,22 @@ SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex *p){ LeaveCriticalSection(&p->mutex); } -/* -** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are -** intended for use only inside assert() statements. -*/ -SQLITE_API int sqlite3_mutex_held(sqlite3_mutex *p){ - return p==0 || (p->nRef!=0 && p->owner==GetCurrentThreadId()); -} -SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex *p){ - return p==0 || p->nRef==0 || p->owner!=GetCurrentThreadId(); +SQLITE_PRIVATE sqlite3_mutex_methods *sqlite3DefaultMutex(void){ + static sqlite3_mutex_methods sMutex = { + winMutexInit, + winMutexEnd, + winMutexAlloc, + winMutexFree, + winMutexEnter, + winMutexTry, + winMutexLeave, +#ifdef SQLITE_DEBUG + winMutexHeld, + winMutexNotheld +#endif + }; + + return &sMutex; } #endif /* SQLITE_MUTEX_W32 */ @@ -13759,8 +15320,8 @@ SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex *p){ ** May you share freely, never taking more than you give. ** ************************************************************************* -** Memory allocation functions used throughout sqlite. ** +** Memory allocation functions used throughout sqlite. ** ** $Id$ */ @@ -13779,8 +15340,8 @@ static void softHeapLimitEnforcer( } /* -** Set the soft heap-size limit for the current thread. Passing a -** zero or negative value indicates no limit. +** Set the soft heap-size limit for the library. Passing a zero or +** negative value indicates no limit. */ SQLITE_API void sqlite3_soft_heap_limit(int n){ sqlite3_uint64 iLimit; @@ -13790,6 +15351,7 @@ SQLITE_API void sqlite3_soft_heap_limit(int n){ }else{ iLimit = n; } + sqlite3_initialize(); if( iLimit>0 ){ sqlite3_memory_alarm(softHeapLimitEnforcer, 0, iLimit); }else{ @@ -13802,7 +15364,9 @@ SQLITE_API void sqlite3_soft_heap_limit(int n){ } /* -** Release memory held by SQLite instances created by the current thread. +** Attempt to release up to n bytes of non-essential memory currently +** held by SQLite. An example of non-essential memory is memory used to +** cache database pages that are not currently in use. */ SQLITE_API int sqlite3_release_memory(int n){ #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT @@ -13814,12 +15378,510 @@ SQLITE_API int sqlite3_release_memory(int n){ #endif } +/* +** State information local to the memory allocation subsystem. +*/ +static struct { + sqlite3_mutex *mutex; /* Mutex to serialize access */ + + /* + ** The alarm callback and its arguments. The mem0.mutex lock will + ** be held while the callback is running. Recursive calls into + ** the memory subsystem are allowed, but no new callbacks will be + ** issued. The alarmBusy variable is set to prevent recursive + ** callbacks. + */ + sqlite3_int64 alarmThreshold; + void (*alarmCallback)(void*, sqlite3_int64,int); + void *alarmArg; + int alarmBusy; + + /* + ** Pointers to the end of sqlite3Config.pScratch and + ** sqlite3Config.pPage to a block of memory that records + ** which pages are available. + */ + u32 *aScratchFree; + u32 *aPageFree; + + /* Number of free pages for scratch and page-cache memory */ + u32 nScratchFree; + u32 nPageFree; +} mem0; + +/* +** Initialize the memory allocation subsystem. +*/ +SQLITE_PRIVATE int sqlite3MallocInit(void){ + if( sqlite3Config.m.xMalloc==0 ){ + sqlite3MemSetDefault(); + } + memset(&mem0, 0, sizeof(mem0)); + if( sqlite3Config.bCoreMutex ){ + mem0.mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM); + } + if( sqlite3Config.pScratch && sqlite3Config.szScratch>=100 + && sqlite3Config.nScratch>=0 ){ + int i; + sqlite3Config.szScratch -= 4; + mem0.aScratchFree = (u32*)&((char*)sqlite3Config.pScratch) + [sqlite3Config.szScratch*sqlite3Config.nScratch]; + for(i=0; i<sqlite3Config.nScratch; i++){ mem0.aScratchFree[i] = i; } + mem0.nScratchFree = sqlite3Config.nScratch; + }else{ + sqlite3Config.pScratch = 0; + sqlite3Config.szScratch = 0; + } + if( sqlite3Config.pPage && sqlite3Config.szPage>=512 + && sqlite3Config.nPage>=1 ){ + int i; + int overhead; + int sz = sqlite3Config.szPage; + int n = sqlite3Config.nPage; + overhead = (4*n + sz - 1)/sz; + sqlite3Config.nPage -= overhead; + mem0.aPageFree = (u32*)&((char*)sqlite3Config.pPage) + [sqlite3Config.szPage*sqlite3Config.nPage]; + for(i=0; i<sqlite3Config.nPage; i++){ mem0.aPageFree[i] = i; } + mem0.nPageFree = sqlite3Config.nPage; + }else{ + sqlite3Config.pPage = 0; + sqlite3Config.szPage = 0; + } + return sqlite3Config.m.xInit(sqlite3Config.m.pAppData); +} + +/* +** Deinitialize the memory allocation subsystem. +*/ +SQLITE_PRIVATE void sqlite3MallocEnd(void){ + sqlite3Config.m.xShutdown(sqlite3Config.m.pAppData); + memset(&mem0, 0, sizeof(mem0)); +} + +/* +** Return the amount of memory currently checked out. +*/ +SQLITE_API sqlite3_int64 sqlite3_memory_used(void){ + int n, mx; + sqlite3_int64 res; + sqlite3_status(SQLITE_STATUS_MEMORY_USED, &n, &mx, 0); + res = (sqlite3_int64)n; /* Work around bug in Borland C. Ticket #3216 */ + return res; +} + +/* +** Return the maximum amount of memory that has ever been +** checked out since either the beginning of this process +** or since the most recent reset. +*/ +SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag){ + int n, mx; + sqlite3_int64 res; + sqlite3_status(SQLITE_STATUS_MEMORY_USED, &n, &mx, resetFlag); + res = (sqlite3_int64)mx; /* Work around bug in Borland C. Ticket #3216 */ + return res; +} + +/* +** Change the alarm callback +*/ +SQLITE_API int sqlite3_memory_alarm( + void(*xCallback)(void *pArg, sqlite3_int64 used,int N), + void *pArg, + sqlite3_int64 iThreshold +){ + sqlite3_mutex_enter(mem0.mutex); + mem0.alarmCallback = xCallback; + mem0.alarmArg = pArg; + mem0.alarmThreshold = iThreshold; + sqlite3_mutex_leave(mem0.mutex); + return SQLITE_OK; +} + +/* +** Trigger the alarm +*/ +static void sqlite3MallocAlarm(int nByte){ + void (*xCallback)(void*,sqlite3_int64,int); + sqlite3_int64 nowUsed; + void *pArg; + if( mem0.alarmCallback==0 || mem0.alarmBusy ) return; + mem0.alarmBusy = 1; + xCallback = mem0.alarmCallback; + nowUsed = sqlite3StatusValue(SQLITE_STATUS_MEMORY_USED); + pArg = mem0.alarmArg; + sqlite3_mutex_leave(mem0.mutex); + xCallback(pArg, nowUsed, nByte); + sqlite3_mutex_enter(mem0.mutex); + mem0.alarmBusy = 0; +} + +/* +** Do a memory allocation with statistics and alarms. Assume the +** lock is already held. +*/ +static int mallocWithAlarm(int n, void **pp){ + int nFull; + void *p; + assert( sqlite3_mutex_held(mem0.mutex) ); + nFull = sqlite3Config.m.xRoundup(n); + sqlite3StatusSet(SQLITE_STATUS_MALLOC_SIZE, n); + if( mem0.alarmCallback!=0 ){ + int nUsed = sqlite3StatusValue(SQLITE_STATUS_MEMORY_USED); + if( nUsed+nFull >= mem0.alarmThreshold ){ + sqlite3MallocAlarm(nFull); + } + } + p = sqlite3Config.m.xMalloc(nFull); + if( p==0 && mem0.alarmCallback ){ + sqlite3MallocAlarm(nFull); + p = sqlite3Config.m.xMalloc(nFull); + } + if( p ){ + nFull = sqlite3MallocSize(p); + sqlite3StatusAdd(SQLITE_STATUS_MEMORY_USED, nFull); + } + *pp = p; + return nFull; +} + +/* +** Allocate memory. This routine is like sqlite3_malloc() except that it +** assumes the memory subsystem has already been initialized. +*/ +SQLITE_PRIVATE void *sqlite3Malloc(int n){ + void *p; + if( n<=0 ){ + p = 0; + }else if( sqlite3Config.bMemstat ){ + sqlite3_mutex_enter(mem0.mutex); + mallocWithAlarm(n, &p); + sqlite3_mutex_leave(mem0.mutex); + }else{ + p = sqlite3Config.m.xMalloc(n); + } + return p; +} + +/* +** This version of the memory allocation is for use by the application. +** First make sure the memory subsystem is initialized, then do the +** allocation. +*/ +SQLITE_API void *sqlite3_malloc(int n){ +#ifndef SQLITE_OMIT_AUTOINIT + if( sqlite3_initialize() ) return 0; +#endif + return sqlite3Malloc(n); +} + +/* +** Each thread may only have a single outstanding allocation from +** xScratchMalloc(). We verify this constraint in the single-threaded +** case by setting scratchAllocOut to 1 when an allocation +** is outstanding clearing it when the allocation is freed. +*/ +#if SQLITE_THREADSAFE==0 && !defined(NDEBUG) +static int scratchAllocOut = 0; +#endif + + +/* +** Allocate memory that is to be used and released right away. +** This routine is similar to alloca() in that it is not intended +** for situations where the memory might be held long-term. This +** routine is intended to get memory to old large transient data +** structures that would not normally fit on the stack of an +** embedded processor. +*/ +SQLITE_PRIVATE void *sqlite3ScratchMalloc(int n){ + void *p; + assert( n>0 ); + +#if SQLITE_THREADSAFE==0 && !defined(NDEBUG) + /* Verify that no more than one scratch allocation per thread + ** is outstanding at one time. (This is only checked in the + ** single-threaded case since checking in the multi-threaded case + ** would be much more complicated.) */ + assert( scratchAllocOut==0 ); +#endif + + if( sqlite3Config.szScratch<n ){ + goto scratch_overflow; + }else{ + sqlite3_mutex_enter(mem0.mutex); + if( mem0.nScratchFree==0 ){ + sqlite3_mutex_leave(mem0.mutex); + goto scratch_overflow; + }else{ + int i; + i = mem0.aScratchFree[--mem0.nScratchFree]; + sqlite3_mutex_leave(mem0.mutex); + i *= sqlite3Config.szScratch; + sqlite3StatusAdd(SQLITE_STATUS_SCRATCH_USED, 1); + sqlite3StatusSet(SQLITE_STATUS_SCRATCH_SIZE, n); + p = (void*)&((char*)sqlite3Config.pScratch)[i]; + } + } +#if SQLITE_THREADSAFE==0 && !defined(NDEBUG) + scratchAllocOut = p!=0; +#endif + + return p; + +scratch_overflow: + if( sqlite3Config.bMemstat ){ + sqlite3_mutex_enter(mem0.mutex); + sqlite3StatusSet(SQLITE_STATUS_SCRATCH_SIZE, n); + n = mallocWithAlarm(n, &p); + if( p ) sqlite3StatusAdd(SQLITE_STATUS_SCRATCH_OVERFLOW, n); + sqlite3_mutex_leave(mem0.mutex); + }else{ + p = sqlite3Config.m.xMalloc(n); + } +#if SQLITE_THREADSAFE==0 && !defined(NDEBUG) + scratchAllocOut = p!=0; +#endif + return p; +} +SQLITE_PRIVATE void sqlite3ScratchFree(void *p){ + if( p ){ + +#if SQLITE_THREADSAFE==0 && !defined(NDEBUG) + /* Verify that no more than one scratch allocation per thread + ** is outstanding at one time. (This is only checked in the + ** single-threaded case since checking in the multi-threaded case + ** would be much more complicated.) */ + assert( scratchAllocOut==1 ); + scratchAllocOut = 0; +#endif + + if( sqlite3Config.pScratch==0 + || p<sqlite3Config.pScratch + || p>=(void*)mem0.aScratchFree ){ + if( sqlite3Config.bMemstat ){ + int iSize = sqlite3MallocSize(p); + sqlite3_mutex_enter(mem0.mutex); + sqlite3StatusAdd(SQLITE_STATUS_SCRATCH_OVERFLOW, -iSize); + sqlite3StatusAdd(SQLITE_STATUS_MEMORY_USED, -iSize); + sqlite3Config.m.xFree(p); + sqlite3_mutex_leave(mem0.mutex); + }else{ + sqlite3Config.m.xFree(p); + } + }else{ + int i; + i = (u8 *)p - (u8 *)sqlite3Config.pScratch; + i /= sqlite3Config.szScratch; + assert( i>=0 && i<sqlite3Config.nScratch ); + sqlite3_mutex_enter(mem0.mutex); + assert( mem0.nScratchFree<sqlite3Config.nScratch ); + mem0.aScratchFree[mem0.nScratchFree++] = i; + sqlite3StatusAdd(SQLITE_STATUS_SCRATCH_USED, -1); + sqlite3_mutex_leave(mem0.mutex); + } + } +} + +/* +** Allocate memory to be used by the page cache. Make use of the +** memory buffer provided by SQLITE_CONFIG_PAGECACHE if there is one +** and that memory is of the right size and is not completely +** consumed. Otherwise, failover to sqlite3Malloc(). +*/ +SQLITE_PRIVATE void *sqlite3PageMalloc(int n){ + void *p; + assert( n>0 ); + assert( (n & (n-1))==0 ); + assert( n>=512 && n<=32768 ); + + if( sqlite3Config.szPage<n ){ + goto page_overflow; + }else{ + sqlite3_mutex_enter(mem0.mutex); + if( mem0.nPageFree==0 ){ + sqlite3_mutex_leave(mem0.mutex); + goto page_overflow; + }else{ + int i; + i = mem0.aPageFree[--mem0.nPageFree]; + sqlite3_mutex_leave(mem0.mutex); + i *= sqlite3Config.szPage; + sqlite3StatusSet(SQLITE_STATUS_PAGECACHE_SIZE, n); + sqlite3StatusAdd(SQLITE_STATUS_PAGECACHE_USED, 1); + p = (void*)&((char*)sqlite3Config.pPage)[i]; + } + } + return p; + +page_overflow: + if( sqlite3Config.bMemstat ){ + sqlite3_mutex_enter(mem0.mutex); + sqlite3StatusSet(SQLITE_STATUS_PAGECACHE_SIZE, n); + n = mallocWithAlarm(n, &p); + if( p ) sqlite3StatusAdd(SQLITE_STATUS_PAGECACHE_OVERFLOW, n); + sqlite3_mutex_leave(mem0.mutex); + }else{ + p = sqlite3Config.m.xMalloc(n); + } + return p; +} +SQLITE_PRIVATE void sqlite3PageFree(void *p){ + if( p ){ + if( sqlite3Config.pPage==0 + || p<sqlite3Config.pPage + || p>=(void*)mem0.aPageFree ){ + /* In this case, the page allocation was obtained from a regular + ** call to sqlite3_mem_methods.xMalloc() (a page-cache-memory + ** "overflow"). Free the block with sqlite3_mem_methods.xFree(). + */ + if( sqlite3Config.bMemstat ){ + int iSize = sqlite3MallocSize(p); + sqlite3_mutex_enter(mem0.mutex); + sqlite3StatusAdd(SQLITE_STATUS_PAGECACHE_OVERFLOW, -iSize); + sqlite3StatusAdd(SQLITE_STATUS_MEMORY_USED, -iSize); + sqlite3Config.m.xFree(p); + sqlite3_mutex_leave(mem0.mutex); + }else{ + sqlite3Config.m.xFree(p); + } + }else{ + /* The page allocation was allocated from the sqlite3Config.pPage + ** buffer. In this case all that is add the index of the page in + ** the sqlite3Config.pPage array to the set of free indexes stored + ** in the mem0.aPageFree[] array. + */ + int i; + i = (u8 *)p - (u8 *)sqlite3Config.pPage; + i /= sqlite3Config.szPage; + assert( i>=0 && i<sqlite3Config.nPage ); + sqlite3_mutex_enter(mem0.mutex); + assert( mem0.nPageFree<sqlite3Config.nPage ); + mem0.aPageFree[mem0.nPageFree++] = i; + sqlite3StatusAdd(SQLITE_STATUS_PAGECACHE_USED, -1); + sqlite3_mutex_leave(mem0.mutex); +#if !defined(NDEBUG) && 0 + /* Assert that a duplicate was not just inserted into aPageFree[]. */ + for(i=0; i<mem0.nPageFree-1; i++){ + assert( mem0.aPageFree[i]!=mem0.aPageFree[mem0.nPageFree-1] ); + } +#endif + } + } +} + +/* +** TRUE if p is a lookaside memory allocation from db +*/ +static int isLookaside(sqlite3 *db, void *p){ + return db && p && p>=db->lookaside.pStart && p<db->lookaside.pEnd; +} + +/* +** Return the size of a memory allocation previously obtained from +** sqlite3Malloc() or sqlite3_malloc(). +*/ +SQLITE_PRIVATE int sqlite3MallocSize(void *p){ + return sqlite3Config.m.xSize(p); +} +SQLITE_PRIVATE int sqlite3DbMallocSize(sqlite3 *db, void *p){ + if( isLookaside(db, p) ){ + return db->lookaside.sz; + }else{ + return sqlite3Config.m.xSize(p); + } +} + +/* +** Free memory previously obtained from sqlite3Malloc(). +*/ +SQLITE_API void sqlite3_free(void *p){ + if( p==0 ) return; + if( sqlite3Config.bMemstat ){ + sqlite3_mutex_enter(mem0.mutex); + sqlite3StatusAdd(SQLITE_STATUS_MEMORY_USED, -sqlite3MallocSize(p)); + sqlite3Config.m.xFree(p); + sqlite3_mutex_leave(mem0.mutex); + }else{ + sqlite3Config.m.xFree(p); + } +} + +/* +** Free memory that might be associated with a particular database +** connection. +*/ +SQLITE_PRIVATE void sqlite3DbFree(sqlite3 *db, void *p){ + if( isLookaside(db, p) ){ + LookasideSlot *pBuf = (LookasideSlot*)p; + pBuf->pNext = db->lookaside.pFree; + db->lookaside.pFree = pBuf; + db->lookaside.nOut--; + }else{ + sqlite3_free(p); + } +} + +/* +** Change the size of an existing memory allocation +*/ +SQLITE_PRIVATE void *sqlite3Realloc(void *pOld, int nBytes){ + int nOld, nNew; + void *pNew; + if( pOld==0 ){ + return sqlite3Malloc(nBytes); + } + if( nBytes<=0 ){ + sqlite3_free(pOld); + return 0; + } + nOld = sqlite3MallocSize(pOld); + if( sqlite3Config.bMemstat ){ + sqlite3_mutex_enter(mem0.mutex); + sqlite3StatusSet(SQLITE_STATUS_MALLOC_SIZE, nBytes); + nNew = sqlite3Config.m.xRoundup(nBytes); + if( nOld==nNew ){ + pNew = pOld; + }else{ + if( sqlite3StatusValue(SQLITE_STATUS_MEMORY_USED)+nNew-nOld >= + mem0.alarmThreshold ){ + sqlite3MallocAlarm(nNew-nOld); + } + pNew = sqlite3Config.m.xRealloc(pOld, nNew); + if( pNew==0 && mem0.alarmCallback ){ + sqlite3MallocAlarm(nBytes); + pNew = sqlite3Config.m.xRealloc(pOld, nNew); + } + if( pNew ){ + nNew = sqlite3MallocSize(pNew); + sqlite3StatusAdd(SQLITE_STATUS_MEMORY_USED, nNew-nOld); + } + } + sqlite3_mutex_leave(mem0.mutex); + }else{ + pNew = sqlite3Config.m.xRealloc(pOld, nBytes); + } + return pNew; +} + +/* +** The public interface to sqlite3Realloc. Make sure that the memory +** subsystem is initialized prior to invoking sqliteRealloc. +*/ +SQLITE_API void *sqlite3_realloc(void *pOld, int n){ +#ifndef SQLITE_OMIT_AUTOINIT + if( sqlite3_initialize() ) return 0; +#endif + return sqlite3Realloc(pOld, n); +} + /* ** Allocate and zero memory. */ -SQLITE_PRIVATE void *sqlite3MallocZero(unsigned n){ - void *p = sqlite3_malloc(n); +SQLITE_PRIVATE void *sqlite3MallocZero(int n){ + void *p = sqlite3Malloc(n); if( p ){ memset(p, 0, n); } @@ -13830,7 +15892,7 @@ SQLITE_PRIVATE void *sqlite3MallocZero(unsigned n){ ** Allocate and zero memory. If the allocation fails, make ** the mallocFailed flag in the connection pointer. */ -SQLITE_PRIVATE void *sqlite3DbMallocZero(sqlite3 *db, unsigned n){ +SQLITE_PRIVATE void *sqlite3DbMallocZero(sqlite3 *db, int n){ void *p = sqlite3DbMallocRaw(db, n); if( p ){ memset(p, 0, n); @@ -13842,27 +15904,54 @@ SQLITE_PRIVATE void *sqlite3DbMallocZero(sqlite3 *db, unsigned n){ ** Allocate and zero memory. If the allocation fails, make ** the mallocFailed flag in the connection pointer. */ -SQLITE_PRIVATE void *sqlite3DbMallocRaw(sqlite3 *db, unsigned n){ - void *p = 0; - if( !db || db->mallocFailed==0 ){ - p = sqlite3_malloc(n); - if( !p && db ){ - db->mallocFailed = 1; +SQLITE_PRIVATE void *sqlite3DbMallocRaw(sqlite3 *db, int n){ + void *p; + if( db ){ + LookasideSlot *pBuf; + if( db->mallocFailed ){ + return 0; + } + if( db->lookaside.bEnabled && n<=db->lookaside.sz + && (pBuf = db->lookaside.pFree)!=0 ){ + db->lookaside.pFree = pBuf->pNext; + db->lookaside.nOut++; + if( db->lookaside.nOut>db->lookaside.mxOut ){ + db->lookaside.mxOut = db->lookaside.nOut; + } + return (void*)pBuf; } } + p = sqlite3Malloc(n); + if( !p && db ){ + db->mallocFailed = 1; + } return p; } /* ** Resize the block of memory pointed to by p to n bytes. If the -** resize fails, set the mallocFailed flag inthe connection object. +** resize fails, set the mallocFailed flag in the connection object. */ SQLITE_PRIVATE void *sqlite3DbRealloc(sqlite3 *db, void *p, int n){ void *pNew = 0; if( db->mallocFailed==0 ){ - pNew = sqlite3_realloc(p, n); - if( !pNew ){ - db->mallocFailed = 1; + if( p==0 ){ + return sqlite3DbMallocRaw(db, n); + } + if( isLookaside(db, p) ){ + if( n<=db->lookaside.sz ){ + return p; + } + pNew = sqlite3DbMallocRaw(db, n); + if( pNew ){ + memcpy(pNew, p, db->lookaside.sz); + sqlite3DbFree(db, p); + } + }else{ + pNew = sqlite3_realloc(p, n); + if( !pNew ){ + db->mallocFailed = 1; + } } } return pNew; @@ -13876,7 +15965,7 @@ SQLITE_PRIVATE void *sqlite3DbReallocOrFree(sqlite3 *db, void *p, int n){ void *pNew; pNew = sqlite3DbRealloc(db, p, n); if( !pNew ){ - sqlite3_free(p); + sqlite3DbFree(db, p); } return pNew; } @@ -13888,75 +15977,48 @@ SQLITE_PRIVATE void *sqlite3DbReallocOrFree(sqlite3 *db, void *p, int n){ ** called via macros that record the current file and line number in the ** ThreadData structure. */ -SQLITE_PRIVATE char *sqlite3StrDup(const char *z){ +SQLITE_PRIVATE char *sqlite3DbStrDup(sqlite3 *db, const char *z){ char *zNew; - int n; - if( z==0 ) return 0; + size_t n; + if( z==0 ){ + return 0; + } n = strlen(z)+1; - zNew = sqlite3_malloc(n); - if( zNew ) memcpy(zNew, z, n); - return zNew; -} -SQLITE_PRIVATE char *sqlite3StrNDup(const char *z, int n){ - char *zNew; - if( z==0 ) return 0; - zNew = sqlite3_malloc(n+1); + assert( (n&0x7fffffff)==n ); + zNew = sqlite3DbMallocRaw(db, (int)n); if( zNew ){ memcpy(zNew, z, n); - zNew[n] = 0; - } - return zNew; -} - -SQLITE_PRIVATE char *sqlite3DbStrDup(sqlite3 *db, const char *z){ - char *zNew = sqlite3StrDup(z); - if( z && !zNew ){ - db->mallocFailed = 1; } return zNew; } SQLITE_PRIVATE char *sqlite3DbStrNDup(sqlite3 *db, const char *z, int n){ - char *zNew = sqlite3StrNDup(z, n); - if( z && !zNew ){ - db->mallocFailed = 1; + char *zNew; + if( z==0 ){ + return 0; + } + assert( (n&0x7fffffff)==n ); + zNew = sqlite3DbMallocRaw(db, n+1); + if( zNew ){ + memcpy(zNew, z, n); + zNew[n] = 0; } return zNew; } /* -** Create a string from the 2nd and subsequent arguments (up to the -** first NULL argument), store the string in memory obtained from -** sqliteMalloc() and make the pointer indicated by the 1st argument -** point to that string. The 1st argument must either be NULL or -** point to memory obtained from sqliteMalloc(). +** Create a string from the zFromat argument and the va_list that follows. +** Store the string in memory obtained from sqliteMalloc() and make *pz +** point to that string. */ -SQLITE_PRIVATE void sqlite3SetString(char **pz, ...){ +SQLITE_PRIVATE void sqlite3SetString(char **pz, sqlite3 *db, const char *zFormat, ...){ va_list ap; - int nByte; - const char *z; - char *zResult; + char *z; - assert( pz!=0 ); - nByte = 1; - va_start(ap, pz); - while( (z = va_arg(ap, const char*))!=0 ){ - nByte += strlen(z); - } - va_end(ap); - sqlite3_free(*pz); - *pz = zResult = sqlite3_malloc(nByte); - if( zResult==0 ){ - return; - } - *zResult = 0; - va_start(ap, pz); - while( (z = va_arg(ap, const char*))!=0 ){ - int n = strlen(z); - memcpy(zResult, z, n); - zResult += n; - } - zResult[0] = 0; + va_start(ap, zFormat); + z = sqlite3VMPrintf(db, zFormat, ap); va_end(ap); + sqlite3DbFree(db, *pz); + *pz = z; } @@ -13996,6 +16058,8 @@ SQLITE_PRIVATE int sqlite3ApiExit(sqlite3* db, int rc){ ** an historical reference. Most of the "enhancements" have been backed ** out so that the functionality is now the same as standard printf(). ** +** $Id$ +** ************************************************************************** ** ** The following modules is an enhanced replacement for the "printf" subroutines @@ -14056,15 +16120,14 @@ SQLITE_PRIVATE int sqlite3ApiExit(sqlite3* db, int rc){ #define etPERCENT 8 /* Percent symbol. %% */ #define etCHARX 9 /* Characters. %c */ /* The rest are extensions, not normally found in printf() */ -#define etCHARLIT 10 /* Literal characters. %' */ -#define etSQLESCAPE 11 /* Strings with '\'' doubled. %q */ -#define etSQLESCAPE2 12 /* Strings with '\'' doubled and enclosed in '', +#define etSQLESCAPE 10 /* Strings with '\'' doubled. %q */ +#define etSQLESCAPE2 11 /* Strings with '\'' doubled and enclosed in '', NULL pointers replaced by SQL NULL. %Q */ -#define etTOKEN 13 /* a pointer to a Token structure */ -#define etSRCLIST 14 /* a pointer to a SrcList */ -#define etPOINTER 15 /* The %p conversion */ -#define etSQLESCAPE3 16 /* %w -> Strings with '\"' doubled */ -#define etORDINAL 17 /* %r -> 1st, 2nd, 3rd, 4th, etc. English only */ +#define etTOKEN 12 /* a pointer to a Token structure */ +#define etSRCLIST 13 /* a pointer to a SrcList */ +#define etPOINTER 14 /* The %p conversion */ +#define etSQLESCAPE3 15 /* %w -> Strings with '\"' doubled */ +#define etORDINAL 16 /* %r -> 1st, 2nd, 3rd, 4th, etc. English only */ /* @@ -14209,7 +16272,7 @@ static void appendSpace(StrAccum *pAccum, int N){ ** seems to make a big difference in determining how fast this beast ** will run. */ -static void vxprintf( +SQLITE_PRIVATE void sqlite3VXPrintf( StrAccum *pAccum, /* Accumulate results here */ int useExtended, /* Allow extended %-conversions */ const char *fmt, /* Format string */ @@ -14432,9 +16495,7 @@ static void vxprintf( const char *pre; char x; pre = &aPrefix[infop->prefix]; - if( *bufpt!=pre[0] ){ - for(; (x=(*pre))!=0; pre++) *(--bufpt) = x; - } + for(; (x=(*pre))!=0; pre++) *(--bufpt) = x; } length = &buf[etBUFSIZE-1]-bufpt; break; @@ -14473,9 +16534,9 @@ static void vxprintf( while( realvalue>=1e32 && exp<=350 ){ realvalue *= 1e-32; exp+=32; } while( realvalue>=1e8 && exp<=350 ){ realvalue *= 1e-8; exp+=8; } while( realvalue>=10.0 && exp<=350 ){ realvalue *= 0.1; exp++; } - while( realvalue<1e-8 && exp>=-350 ){ realvalue *= 1e8; exp-=8; } - while( realvalue<1.0 && exp>=-350 ){ realvalue *= 10.0; exp--; } - if( exp>350 || exp<-350 ){ + while( realvalue<1e-8 ){ realvalue *= 1e8; exp-=8; } + while( realvalue<1.0 ){ realvalue *= 10.0; exp--; } + if( exp>350 ){ if( prefix=='-' ){ bufpt = "-Inf"; }else if( prefix=='+' ){ @@ -14533,7 +16594,8 @@ static void vxprintf( } /* "0" digits after the decimal point but before the first ** significant digit of the number */ - for(e2++; e2<0 && precision>0; precision--, e2++){ + for(e2++; e2<0; precision--, e2++){ + assert( precision>0 ); *(bufpt++) = '0'; } /* Significant digits after the decimal point */ @@ -14553,7 +16615,7 @@ static void vxprintf( } } /* Add the "eNNN" suffix */ - if( flag_exp || (xtype==etEXP && exp) ){ + if( flag_exp || xtype==etEXP ){ *(bufpt++) = aDigits[infop->charset]; if( exp<0 ){ *(bufpt++) = '-'; exp = -exp; @@ -14598,9 +16660,8 @@ static void vxprintf( bufpt = buf; length = 1; break; - case etCHARLIT: case etCHARX: - c = buf[0] = (xtype==etCHARX ? va_arg(ap,int) : *++fmt); + c = buf[0] = va_arg(ap,int); if( precision>=0 ){ for(idx=1; idx<precision; idx++) buf[idx] = c; length = precision; @@ -14638,7 +16699,7 @@ static void vxprintf( needQuote = !isnull && xtype==etSQLESCAPE2; n += i + 1 + needQuote*2; if( n>etBUFSIZE ){ - bufpt = zExtra = sqlite3_malloc( n ); + bufpt = zExtra = sqlite3Malloc( n ); if( bufpt==0 ) return; }else{ bufpt = buf; @@ -14658,7 +16719,7 @@ static void vxprintf( } case etTOKEN: { Token *pToken = va_arg(ap, Token*); - if( pToken && pToken->z ){ + if( pToken ){ sqlite3StrAccumAppend(pAccum, (const char*)pToken->z, pToken->n); } length = width = 0; @@ -14669,7 +16730,7 @@ static void vxprintf( int k = va_arg(ap, int); struct SrcList_item *pItem = &pSrc->a[k]; assert( k>=0 && k<pSrc->nSrc ); - if( pItem->zDatabase && pItem->zDatabase[0] ){ + if( pItem->zDatabase ){ sqlite3StrAccumAppend(pAccum, pItem->zDatabase, -1); sqlite3StrAccumAppend(pAccum, ".", 1); } @@ -14728,19 +16789,16 @@ SQLITE_PRIVATE void sqlite3StrAccumAppend(StrAccum *p, const char *z, int N){ return; } }else{ - i64 szNew = p->nAlloc; + i64 szNew = p->nChar; szNew += N + 1; if( szNew > p->mxAlloc ){ - p->nAlloc = p->mxAlloc; - if( ((i64)p->nChar)+((i64)N) >= p->nAlloc ){ - sqlite3StrAccumReset(p); - p->tooBig = 1; - return; - } + sqlite3StrAccumReset(p); + p->tooBig = 1; + return; }else{ p->nAlloc = szNew; } - zNew = sqlite3_malloc( p->nAlloc ); + zNew = sqlite3DbMallocRaw(p->db, p->nAlloc ); if( zNew ){ memcpy(zNew, p->zText, p->nChar); sqlite3StrAccumReset(p); @@ -14765,7 +16823,7 @@ SQLITE_PRIVATE char *sqlite3StrAccumFinish(StrAccum *p){ if( p->zText ){ p->zText[p->nChar] = 0; if( p->useMalloc && p->zText==p->zBase ){ - p->zText = sqlite3_malloc( p->nChar+1 ); + p->zText = sqlite3DbMallocRaw(p->db, p->nChar+1 ); if( p->zText ){ memcpy(p->zText, p->zBase, p->nChar+1); }else{ @@ -14781,16 +16839,17 @@ SQLITE_PRIVATE char *sqlite3StrAccumFinish(StrAccum *p){ */ SQLITE_PRIVATE void sqlite3StrAccumReset(StrAccum *p){ if( p->zText!=p->zBase ){ - sqlite3_free(p->zText); - p->zText = 0; + sqlite3DbFree(p->db, p->zText); } + p->zText = 0; } /* ** Initialize a string accumulator */ -static void sqlite3StrAccumInit(StrAccum *p, char *zBase, int n, int mx){ +SQLITE_PRIVATE void sqlite3StrAccumInit(StrAccum *p, char *zBase, int n, int mx){ p->zText = p->zBase = zBase; + p->db = 0; p->nChar = 0; p->nAlloc = n; p->mxAlloc = mx; @@ -14809,7 +16868,8 @@ SQLITE_PRIVATE char *sqlite3VMPrintf(sqlite3 *db, const char *zFormat, va_list a StrAccum acc; sqlite3StrAccumInit(&acc, zBase, sizeof(zBase), db ? db->aLimit[SQLITE_LIMIT_LENGTH] : SQLITE_MAX_LENGTH); - vxprintf(&acc, 1, zFormat, ap); + acc.db = db; + sqlite3VXPrintf(&acc, 1, zFormat, ap); z = sqlite3StrAccumFinish(&acc); if( acc.mallocFailed && db ){ db->mallocFailed = 1; @@ -14831,6 +16891,24 @@ SQLITE_PRIVATE char *sqlite3MPrintf(sqlite3 *db, const char *zFormat, ...){ } /* +** Like sqlite3MPrintf(), but call sqlite3DbFree() on zStr after formatting +** the string and before returnning. This routine is intended to be used +** to modify an existing string. For example: +** +** x = sqlite3MPrintf(db, x, "prefix %s suffix", x); +** +*/ +SQLITE_PRIVATE char *sqlite3MAppendf(sqlite3 *db, char *zStr, const char *zFormat, ...){ + va_list ap; + char *z; + va_start(ap, zFormat); + z = sqlite3VMPrintf(db, zFormat, ap); + va_end(ap); + sqlite3DbFree(db, zStr); + return z; +} + +/* ** Print into memory obtained from sqlite3_malloc(). Omit the internal ** %-conversion extensions. */ @@ -14838,8 +16916,11 @@ SQLITE_API char *sqlite3_vmprintf(const char *zFormat, va_list ap){ char *z; char zBase[SQLITE_PRINT_BUF_SIZE]; StrAccum acc; +#ifndef SQLITE_OMIT_AUTOINIT + if( sqlite3_initialize() ) return 0; +#endif sqlite3StrAccumInit(&acc, zBase, sizeof(zBase), SQLITE_MAX_LENGTH); - vxprintf(&acc, 0, zFormat, ap); + sqlite3VXPrintf(&acc, 0, zFormat, ap); z = sqlite3StrAccumFinish(&acc); return z; } @@ -14851,6 +16932,9 @@ SQLITE_API char *sqlite3_vmprintf(const char *zFormat, va_list ap){ SQLITE_API char *sqlite3_mprintf(const char *zFormat, ...){ va_list ap; char *z; +#ifndef SQLITE_OMIT_AUTOINIT + if( sqlite3_initialize() ) return 0; +#endif va_start(ap, zFormat); z = sqlite3_vmprintf(zFormat, ap); va_end(ap); @@ -14874,13 +16958,13 @@ SQLITE_API char *sqlite3_snprintf(int n, char *zBuf, const char *zFormat, ...){ sqlite3StrAccumInit(&acc, zBuf, n, 0); acc.useMalloc = 0; va_start(ap,zFormat); - vxprintf(&acc, 0, zFormat, ap); + sqlite3VXPrintf(&acc, 0, zFormat, ap); va_end(ap); z = sqlite3StrAccumFinish(&acc); return z; } -#if defined(SQLITE_TEST) || defined(SQLITE_DEBUG) || defined(SQLITE_MEMDEBUG) +#if defined(SQLITE_DEBUG) /* ** A version of printf() that understands %lld. Used for debugging. ** The printf() built into some versions of windows does not understand %lld @@ -14893,7 +16977,7 @@ SQLITE_PRIVATE void sqlite3DebugPrintf(const char *zFormat, ...){ sqlite3StrAccumInit(&acc, zBuf, sizeof(zBuf), 0); acc.useMalloc = 0; va_start(ap,zFormat); - vxprintf(&acc, 0, zFormat, ap); + sqlite3VXPrintf(&acc, 0, zFormat, ap); va_end(ap); sqlite3StrAccumFinish(&acc); fprintf(stdout,"%s", zBuf); @@ -14996,10 +17080,9 @@ static int randomByte(void){ */ SQLITE_API void sqlite3_randomness(int N, void *pBuf){ unsigned char *zBuf = pBuf; - static sqlite3_mutex *mutex = 0; - if( mutex==0 ){ - mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_PRNG); - } +#ifndef SQLITE_MUTEX_NOOP + sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_PRNG); +#endif sqlite3_mutex_enter(mutex); while( N-- ){ *(zBuf++) = randomByte(); @@ -15083,6 +17166,8 @@ SQLITE_PRIVATE void sqlite3PrngResetState(void){ ** source code file "vdbe.c". When that file became too big (over ** 6000 lines long) it was split up into several smaller files and ** this header information was factored out. +** +** $Id$ */ #ifndef _VDBEINT_H_ #define _VDBEINT_H_ @@ -15312,6 +17397,7 @@ struct FifoPage { typedef struct Fifo Fifo; struct Fifo { int nEntry; /* Total number of entries */ + sqlite3 *db; /* The associated database connection */ FifoPage *pFirst; /* First page on the list */ FifoPage *pLast; /* Last page on the list */ }; @@ -15378,15 +17464,12 @@ struct Vdbe { unsigned uniqueCnt; /* Used by OP_MakeRecord when P2!=0 */ int errorAction; /* Recovery action to do in case of an error */ int inTempTrans; /* True if temp database is transactioned */ - int returnStack[25]; /* Return address stack for OP_Gosub & OP_Return */ - int returnDepth; /* Next unused element in returnStack[] */ int nResColumn; /* Number of columns in one row of the result set */ char **azResColumn; /* Values for one row of result */ char *zErrMsg; /* Error message written here */ Mem *pResultSet; /* Pointer to an array of results */ u8 explain; /* True if EXPLAIN present on SQL command */ u8 changeCntOn; /* True to update the change-counter */ - u8 aborted; /* True if ROLLBACK in another VM causes an abort */ u8 expired; /* True if the VM needs to be recompiled */ u8 minWriteFileFormat; /* Minimum file format for writable database files */ u8 inVtabMethod; /* See comments above */ @@ -15459,7 +17542,7 @@ int sqlite2BtreeKeyCompare(BtCursor *, const void *, int, int, int *); SQLITE_PRIVATE int sqlite3VdbeIdxKeyCompare(Cursor*,UnpackedRecord *,int,const unsigned char*,int*); SQLITE_PRIVATE int sqlite3VdbeIdxRowid(BtCursor *, i64 *); SQLITE_PRIVATE int sqlite3MemCompare(const Mem*, const Mem*, const CollSeq*); -SQLITE_PRIVATE int sqlite3VdbeIdxRowidLen(const u8*); +SQLITE_PRIVATE int sqlite3VdbeIdxRowidLen(const u8*, int, int*); SQLITE_PRIVATE int sqlite3VdbeExec(Vdbe*); SQLITE_PRIVATE int sqlite3VdbeList(Vdbe*); SQLITE_PRIVATE int sqlite3VdbeHalt(Vdbe*); @@ -15475,7 +17558,6 @@ SQLITE_PRIVATE void sqlite3VdbeMemSetDouble(Mem*, double); SQLITE_PRIVATE void sqlite3VdbeMemSetNull(Mem*); SQLITE_PRIVATE void sqlite3VdbeMemSetZeroBlob(Mem*,int); SQLITE_PRIVATE int sqlite3VdbeMemMakeWriteable(Mem*); -SQLITE_PRIVATE int sqlite3VdbeMemDynamicify(Mem*); SQLITE_PRIVATE int sqlite3VdbeMemStringify(Mem*, int); SQLITE_PRIVATE i64 sqlite3VdbeIntValue(Mem*); SQLITE_PRIVATE int sqlite3VdbeMemIntegerify(Mem*); @@ -15503,7 +17585,7 @@ SQLITE_PRIVATE void sqlite3VdbePrintSql(Vdbe*); SQLITE_PRIVATE void sqlite3VdbeMemPrettyPrint(Mem *pMem, char *zBuf); #endif SQLITE_PRIVATE int sqlite3VdbeMemHandleBom(Mem *pMem); -SQLITE_PRIVATE void sqlite3VdbeFifoInit(Fifo*); +SQLITE_PRIVATE void sqlite3VdbeFifoInit(Fifo*, sqlite3*); SQLITE_PRIVATE int sqlite3VdbeFifoPush(Fifo*, i64); SQLITE_PRIVATE int sqlite3VdbeFifoPop(Fifo*, i64*); SQLITE_PRIVATE void sqlite3VdbeFifoClear(Fifo*); @@ -15634,27 +17716,31 @@ static const unsigned char sqlite3UtfTrans1[] = { ** for unicode values 0x80 and greater. It do not change over-length ** encodings to 0xfffd as some systems recommend. */ +#define READ_UTF8(zIn, zTerm, c) \ + c = *(zIn++); \ + if( c>=0xc0 ){ \ + c = sqlite3UtfTrans1[c-0xc0]; \ + while( zIn!=zTerm && (*zIn & 0xc0)==0x80 ){ \ + c = (c<<6) + (0x3f & *(zIn++)); \ + } \ + if( c<0x80 \ + || (c&0xFFFFF800)==0xD800 \ + || (c&0xFFFFFFFE)==0xFFFE ){ c = 0xFFFD; } \ + } SQLITE_PRIVATE int sqlite3Utf8Read( const unsigned char *z, /* First byte of UTF-8 character */ const unsigned char *zTerm, /* Pretend this byte is 0x00 */ const unsigned char **pzNext /* Write first byte past UTF-8 char here */ ){ - int c = *(z++); - if( c>=0xc0 ){ - c = sqlite3UtfTrans1[c-0xc0]; - while( z!=zTerm && (*z & 0xc0)==0x80 ){ - c = (c<<6) + (0x3f & *(z++)); - } - if( c<0x80 - || (c&0xFFFFF800)==0xD800 - || (c&0xFFFFFFFE)==0xFFFE ){ c = 0xFFFD; } - } + int c; + READ_UTF8(z, zTerm, c); *pzNext = z; return c; } + /* ** If the TRANSLATE_TRACE macro is defined, the value of each Mem is ** printed on stderr on the way into and out of sqlite3VdbeMemTranslate(). @@ -15748,14 +17834,16 @@ SQLITE_PRIVATE int sqlite3VdbeMemTranslate(Mem *pMem, u8 desiredEnc){ if( desiredEnc==SQLITE_UTF16LE ){ /* UTF-8 -> UTF-16 Little-endian */ while( zIn<zTerm ){ - c = sqlite3Utf8Read(zIn, zTerm, (const u8**)&zIn); + /* c = sqlite3Utf8Read(zIn, zTerm, (const u8**)&zIn); */ + READ_UTF8(zIn, zTerm, c); WRITE_UTF16LE(z, c); } }else{ assert( desiredEnc==SQLITE_UTF16BE ); /* UTF-8 -> UTF-16 Big-endian */ while( zIn<zTerm ){ - c = sqlite3Utf8Read(zIn, zTerm, (const u8**)&zIn); + /* c = sqlite3Utf8Read(zIn, zTerm, (const u8**)&zIn); */ + READ_UTF8(zIn, zTerm, c); WRITE_UTF16BE(z, c); } } @@ -15770,7 +17858,7 @@ SQLITE_PRIVATE int sqlite3VdbeMemTranslate(Mem *pMem, u8 desiredEnc){ WRITE_UTF8(z, c); } }else{ - /* UTF-16 Little-endian -> UTF-8 */ + /* UTF-16 Big-endian -> UTF-8 */ while( zIn<zTerm ){ READ_UTF16BE(zIn, c); WRITE_UTF8(z, c); @@ -16026,7 +18114,7 @@ SQLITE_PRIVATE void sqlite3UtfSelfTest(){ /* -** Return true if the floating point value is Not a Number. +** Return true if the floating point value is Not a Number (NaN). */ SQLITE_PRIVATE int sqlite3IsNaN(double x){ /* This NaN test sometimes fails if compiled on GCC with -ffast-math. @@ -16037,9 +18125,39 @@ SQLITE_PRIVATE int sqlite3IsNaN(double x){ ** -O option since it can result in incorrect output for programs ** which depend on an exact implementation of IEEE or ISO ** rules/specifications for math functions. + ** + ** Under MSVC, this NaN test may fail if compiled with a floating- + ** point precision mode other than /fp:precise. From the MSDN + ** documentation: + ** + ** The compiler [with /fp:precise] will properly handle comparisons + ** involving NaN. For example, x != x evaluates to true if x is NaN + ** ... */ +#ifdef __FAST_MATH__ +# error SQLite will not work correctly with the -ffast-math option of GCC. +#endif volatile double y = x; - return x!=y; + volatile double z = y; + return y!=z; +} + +/* +** Return the length of a string, except do not allow the string length +** to exceed the SQLITE_LIMIT_LENGTH setting. +*/ +SQLITE_PRIVATE int sqlite3Strlen(sqlite3 *db, const char *z){ + const char *z2 = z; + int len; + size_t x; + while( *z2 ){ z2++; } + x = z2 - z; + len = 0x7fffffff & x; + if( len!=x || len > db->aLimit[SQLITE_LIMIT_LENGTH] ){ + return db->aLimit[SQLITE_LIMIT_LENGTH]; + }else{ + return len; + } } /* @@ -16072,7 +18190,7 @@ SQLITE_PRIVATE void sqlite3Error(sqlite3 *db, int err_code, const char *zFormat, va_start(ap, zFormat); z = sqlite3VMPrintf(db, zFormat, ap); va_end(ap); - sqlite3ValueSetStr(db->pErr, -1, z, SQLITE_UTF8, sqlite3_free); + sqlite3ValueSetStr(db->pErr, -1, z, SQLITE_UTF8, SQLITE_DYNAMIC); }else{ sqlite3ValueSetStr(db->pErr, 0, 0, SQLITE_UTF8, SQLITE_STATIC); } @@ -16098,10 +18216,11 @@ SQLITE_PRIVATE void sqlite3Error(sqlite3 *db, int err_code, const char *zFormat, */ SQLITE_PRIVATE void sqlite3ErrorMsg(Parse *pParse, const char *zFormat, ...){ va_list ap; + sqlite3 *db = pParse->db; pParse->nErr++; - sqlite3_free(pParse->zErrMsg); + sqlite3DbFree(db, pParse->zErrMsg); va_start(ap, zFormat); - pParse->zErrMsg = sqlite3VMPrintf(pParse->db, zFormat, ap); + pParse->zErrMsg = sqlite3VMPrintf(db, zFormat, ap); va_end(ap); if( pParse->rc==SQLITE_OK ){ pParse->rc = SQLITE_ERROR; @@ -16112,7 +18231,7 @@ SQLITE_PRIVATE void sqlite3ErrorMsg(Parse *pParse, const char *zFormat, ...){ ** Clear the error message in pParse, if any */ SQLITE_PRIVATE void sqlite3ErrorClear(Parse *pParse){ - sqlite3_free(pParse->zErrMsg); + sqlite3DbFree(pParse->db, pParse->zErrMsg); pParse->zErrMsg = 0; pParse->nErr = 0; } @@ -16154,46 +18273,7 @@ SQLITE_PRIVATE void sqlite3Dequote(char *z){ } } -/* An array to map all upper-case characters into their corresponding -** lower-case character. -*/ -SQLITE_PRIVATE const unsigned char sqlite3UpperToLower[] = { -#ifdef SQLITE_ASCII - 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, - 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, - 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, - 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 97, 98, 99,100,101,102,103, - 104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121, - 122, 91, 92, 93, 94, 95, 96, 97, 98, 99,100,101,102,103,104,105,106,107, - 108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125, - 126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143, - 144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161, - 162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179, - 180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197, - 198,199,200,201,202,203,204,205,206,207,208,209,210,211,212,213,214,215, - 216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233, - 234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251, - 252,253,254,255 -#endif -#ifdef SQLITE_EBCDIC - 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, /* 0x */ - 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, /* 1x */ - 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, /* 2x */ - 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, /* 3x */ - 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, /* 4x */ - 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, /* 5x */ - 96, 97, 66, 67, 68, 69, 70, 71, 72, 73,106,107,108,109,110,111, /* 6x */ - 112, 81, 82, 83, 84, 85, 86, 87, 88, 89,122,123,124,125,126,127, /* 7x */ - 128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143, /* 8x */ - 144,145,146,147,148,149,150,151,152,153,154,155,156,157,156,159, /* 9x */ - 160,161,162,163,164,165,166,167,168,169,170,171,140,141,142,175, /* Ax */ - 176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191, /* Bx */ - 192,129,130,131,132,133,134,135,136,137,202,203,204,205,206,207, /* Cx */ - 208,145,146,147,148,149,150,151,152,153,218,219,220,221,222,223, /* Dx */ - 224,225,162,163,164,165,166,167,168,169,232,203,204,205,206,207, /* Ex */ - 239,240,241,242,243,244,245,246,247,248,249,219,220,221,222,255, /* Fx */ -#endif -}; +/* Convenient short-hand */ #define UpperToLower sqlite3UpperToLower /* @@ -16370,6 +18450,7 @@ SQLITE_PRIVATE int sqlite3Atoi64(const char *zNum, i64 *pNum){ i64 v = 0; int neg; int i, c; + const char *zStart; while( isspace(*(u8*)zNum) ) zNum++; if( *zNum=='-' ){ neg = 1; @@ -16380,12 +18461,13 @@ SQLITE_PRIVATE int sqlite3Atoi64(const char *zNum, i64 *pNum){ }else{ neg = 0; } + zStart = zNum; while( zNum[0]=='0' ){ zNum++; } /* Skip over leading zeros. Ticket #2454 */ for(i=0; (c=zNum[i])>='0' && c<='9'; i++){ v = v*10 + c - '0'; } *pNum = neg ? -v : v; - if( c!=0 || i==0 || i>19 ){ + if( c!=0 || (i==0 && zStart==zNum) || i>19 ){ /* zNum is empty or contains non-numeric text or is longer ** than 19 digits (thus guaranting that it is too large) */ return 0; @@ -17196,9 +19278,9 @@ static void rehash(Hash *pH, int new_size){ ** is benign (since failing to resize a hash table is a performance ** hit only, not a fatal error). */ - if( pH->htsize>0 ) sqlite3FaultBeginBenign(SQLITE_FAULTINJECTOR_MALLOC); + if( pH->htsize>0 ) sqlite3BeginBenignMalloc(); new_ht = (struct _ht *)sqlite3MallocZero( new_size*sizeof(struct _ht) ); - if( pH->htsize>0 ) sqlite3FaultEndBenign(SQLITE_FAULTINJECTOR_MALLOC); + if( pH->htsize>0 ) sqlite3EndBenignMalloc(); if( new_ht==0 ) return; sqlite3_free(pH->ht); @@ -17350,10 +19432,10 @@ SQLITE_PRIVATE void *sqlite3HashInsert(Hash *pH, const void *pKey, int nKey, voi } } if( data==0 ) return 0; - new_elem = (HashElem*)sqlite3_malloc( sizeof(HashElem) ); + new_elem = (HashElem*)sqlite3Malloc( sizeof(HashElem) ); if( new_elem==0 ) return data; if( pH->copyKey && pKey!=0 ){ - new_elem->pKey = sqlite3_malloc( nKey ); + new_elem->pKey = sqlite3Malloc( nKey ); if( new_elem->pKey==0 ){ sqlite3_free(new_elem); return data; @@ -17408,54 +19490,54 @@ SQLITE_PRIVATE const char *sqlite3OpcodeName(int i){ /* 14 */ "Expire", /* 15 */ "AutoCommit", /* 16 */ "Not", - /* 17 */ "IntegrityCk", - /* 18 */ "Sort", - /* 19 */ "Copy", - /* 20 */ "Trace", - /* 21 */ "Function", - /* 22 */ "IfNeg", - /* 23 */ "Noop", - /* 24 */ "Return", - /* 25 */ "NewRowid", - /* 26 */ "Variable", - /* 27 */ "String", - /* 28 */ "RealAffinity", - /* 29 */ "VRename", - /* 30 */ "ParseSchema", - /* 31 */ "VOpen", - /* 32 */ "Close", - /* 33 */ "CreateIndex", - /* 34 */ "IsUnique", - /* 35 */ "NotFound", - /* 36 */ "Int64", - /* 37 */ "MustBeInt", - /* 38 */ "Halt", - /* 39 */ "Rowid", - /* 40 */ "IdxLT", - /* 41 */ "AddImm", - /* 42 */ "Statement", - /* 43 */ "RowData", - /* 44 */ "MemMax", - /* 45 */ "NotExists", - /* 46 */ "Gosub", - /* 47 */ "Integer", - /* 48 */ "Prev", - /* 49 */ "VColumn", - /* 50 */ "CreateTable", - /* 51 */ "Last", - /* 52 */ "IncrVacuum", - /* 53 */ "IdxRowid", - /* 54 */ "ResetCount", - /* 55 */ "FifoWrite", - /* 56 */ "ContextPush", - /* 57 */ "DropTrigger", - /* 58 */ "DropIndex", - /* 59 */ "IdxGE", + /* 17 */ "Pagecount", + /* 18 */ "IntegrityCk", + /* 19 */ "Sort", + /* 20 */ "Copy", + /* 21 */ "Trace", + /* 22 */ "Function", + /* 23 */ "IfNeg", + /* 24 */ "Noop", + /* 25 */ "Return", + /* 26 */ "NewRowid", + /* 27 */ "Variable", + /* 28 */ "String", + /* 29 */ "RealAffinity", + /* 30 */ "VRename", + /* 31 */ "ParseSchema", + /* 32 */ "VOpen", + /* 33 */ "Close", + /* 34 */ "CreateIndex", + /* 35 */ "IsUnique", + /* 36 */ "NotFound", + /* 37 */ "Int64", + /* 38 */ "MustBeInt", + /* 39 */ "Halt", + /* 40 */ "Rowid", + /* 41 */ "IdxLT", + /* 42 */ "AddImm", + /* 43 */ "Statement", + /* 44 */ "RowData", + /* 45 */ "MemMax", + /* 46 */ "NotExists", + /* 47 */ "Gosub", + /* 48 */ "Integer", + /* 49 */ "Prev", + /* 50 */ "VColumn", + /* 51 */ "CreateTable", + /* 52 */ "Last", + /* 53 */ "IncrVacuum", + /* 54 */ "IdxRowid", + /* 55 */ "ResetCount", + /* 56 */ "FifoWrite", + /* 57 */ "ContextPush", + /* 58 */ "Yield", + /* 59 */ "DropTrigger", /* 60 */ "Or", /* 61 */ "And", - /* 62 */ "IdxDelete", - /* 63 */ "Vacuum", - /* 64 */ "MoveLe", + /* 62 */ "DropIndex", + /* 63 */ "IdxGE", + /* 64 */ "IdxDelete", /* 65 */ "IsNull", /* 66 */ "NotNull", /* 67 */ "Ne", @@ -17464,7 +19546,7 @@ SQLITE_PRIVATE const char *sqlite3OpcodeName(int i){ /* 70 */ "Le", /* 71 */ "Lt", /* 72 */ "Ge", - /* 73 */ "IfNot", + /* 73 */ "Vacuum", /* 74 */ "BitAnd", /* 75 */ "BitOr", /* 76 */ "ShiftLeft", @@ -17475,53 +19557,53 @@ SQLITE_PRIVATE const char *sqlite3OpcodeName(int i){ /* 81 */ "Divide", /* 82 */ "Remainder", /* 83 */ "Concat", - /* 84 */ "DropTable", - /* 85 */ "MakeRecord", - /* 86 */ "ResultRow", + /* 84 */ "MoveLe", + /* 85 */ "IfNot", + /* 86 */ "DropTable", /* 87 */ "BitNot", /* 88 */ "String8", - /* 89 */ "Delete", - /* 90 */ "AggFinal", - /* 91 */ "Goto", - /* 92 */ "TableLock", - /* 93 */ "FifoRead", - /* 94 */ "Clear", - /* 95 */ "MoveLt", - /* 96 */ "VerifyCookie", - /* 97 */ "AggStep", - /* 98 */ "SetNumColumns", - /* 99 */ "Transaction", - /* 100 */ "VFilter", - /* 101 */ "VDestroy", - /* 102 */ "ContextPop", - /* 103 */ "Next", - /* 104 */ "IdxInsert", - /* 105 */ "Insert", - /* 106 */ "Destroy", - /* 107 */ "ReadCookie", - /* 108 */ "ForceInt", - /* 109 */ "LoadAnalysis", - /* 110 */ "Explain", - /* 111 */ "OpenPseudo", - /* 112 */ "OpenEphemeral", - /* 113 */ "Null", - /* 114 */ "Move", - /* 115 */ "Blob", - /* 116 */ "Rewind", - /* 117 */ "MoveGe", - /* 118 */ "VBegin", - /* 119 */ "VUpdate", - /* 120 */ "IfZero", - /* 121 */ "VCreate", - /* 122 */ "Found", - /* 123 */ "IfPos", - /* 124 */ "NullRow", + /* 89 */ "MakeRecord", + /* 90 */ "ResultRow", + /* 91 */ "Delete", + /* 92 */ "AggFinal", + /* 93 */ "Compare", + /* 94 */ "Goto", + /* 95 */ "TableLock", + /* 96 */ "FifoRead", + /* 97 */ "Clear", + /* 98 */ "MoveLt", + /* 99 */ "VerifyCookie", + /* 100 */ "AggStep", + /* 101 */ "SetNumColumns", + /* 102 */ "Transaction", + /* 103 */ "VFilter", + /* 104 */ "VDestroy", + /* 105 */ "ContextPop", + /* 106 */ "Next", + /* 107 */ "IdxInsert", + /* 108 */ "Insert", + /* 109 */ "Destroy", + /* 110 */ "ReadCookie", + /* 111 */ "ForceInt", + /* 112 */ "LoadAnalysis", + /* 113 */ "Explain", + /* 114 */ "OpenPseudo", + /* 115 */ "OpenEphemeral", + /* 116 */ "Null", + /* 117 */ "Move", + /* 118 */ "Blob", + /* 119 */ "Rewind", + /* 120 */ "MoveGe", + /* 121 */ "VBegin", + /* 122 */ "VUpdate", + /* 123 */ "IfZero", + /* 124 */ "VCreate", /* 125 */ "Real", - /* 126 */ "NotUsed_126", - /* 127 */ "NotUsed_127", - /* 128 */ "NotUsed_128", - /* 129 */ "NotUsed_129", - /* 130 */ "NotUsed_130", + /* 126 */ "Found", + /* 127 */ "IfPos", + /* 128 */ "NullRow", + /* 129 */ "Jump", + /* 130 */ "Permutation", /* 131 */ "NotUsed_131", /* 132 */ "NotUsed_132", /* 133 */ "NotUsed_133", @@ -17554,10 +19636,12 @@ SQLITE_PRIVATE const char *sqlite3OpcodeName(int i){ ****************************************************************************** ** ** This file contains code that is specific to OS/2. +** +** $Id$ */ -#if OS_OS2 +#if SQLITE_OS_OS2 /* ** A Note About Memory Allocation: @@ -17615,7 +19699,11 @@ SQLITE_PRIVATE const char *sqlite3OpcodeName(int i){ ** ** This file should be #included by the os_*.c files only. It is not a ** general purpose header file. +** +** $Id$ */ +#ifndef _OS_COMMON_H_ +#define _OS_COMMON_H_ /* ** At least two bugs have slipped in because we changed the MEMORY_DEBUG @@ -17661,22 +19749,113 @@ SQLITE_PRIVATE int sqlite3OSTrace = 0; ** on i486 hardware. */ #ifdef SQLITE_PERFORMANCE_TRACE -__inline__ unsigned long long int hwtime(void){ - unsigned long long int x; - __asm__("rdtsc\n\t" - "mov %%edx, %%ecx\n\t" - :"=A" (x)); - return x; -} -static unsigned long long int g_start; -static unsigned int elapse; -#define TIMER_START g_start=hwtime() -#define TIMER_END elapse=hwtime()-g_start -#define TIMER_ELAPSED elapse + +/* +** hwtime.h contains inline assembler code for implementing +** high-performance timing routines. +*/ +/************** Include hwtime.h in the middle of os_common.h ****************/ +/************** Begin file hwtime.h ******************************************/ +/* +** 2008 May 27 +** +** The author disclaims copyright to this source code. In place of +** a legal notice, here is a blessing: +** +** May you do good and not evil. +** May you find forgiveness for yourself and forgive others. +** May you share freely, never taking more than you give. +** +****************************************************************************** +** +** This file contains inline asm code for retrieving "high-performance" +** counters for x86 class CPUs. +** +** $Id$ +*/ +#ifndef _HWTIME_H_ +#define _HWTIME_H_ + +/* +** The following routine only works on pentium-class (or newer) processors. +** It uses the RDTSC opcode to read the cycle count value out of the +** processor and returns that value. This can be used for high-res +** profiling. +*/ +#if (defined(__GNUC__) || defined(_MSC_VER)) && \ + (defined(i386) || defined(__i386__) || defined(_M_IX86)) + + #if defined(__GNUC__) + + __inline__ sqlite_uint64 sqlite3Hwtime(void){ + unsigned int lo, hi; + __asm__ __volatile__ ("rdtsc" : "=a" (lo), "=d" (hi)); + return (sqlite_uint64)hi << 32 | lo; + } + + #elif defined(_MSC_VER) + + __declspec(naked) __inline sqlite_uint64 __cdecl sqlite3Hwtime(void){ + __asm { + rdtsc + ret ; return value at EDX:EAX + } + } + + #endif + +#elif (defined(__GNUC__) && defined(__x86_64__)) + + __inline__ sqlite_uint64 sqlite3Hwtime(void){ + unsigned long val; + __asm__ __volatile__ ("rdtsc" : "=A" (val)); + return val; + } + +#elif (defined(__GNUC__) && defined(__ppc__)) + + __inline__ sqlite_uint64 sqlite3Hwtime(void){ + unsigned long long retval; + unsigned long junk; + __asm__ __volatile__ ("\n\ + 1: mftbu %1\n\ + mftb %L0\n\ + mftbu %0\n\ + cmpw %0,%1\n\ + bne 1b" + : "=r" (retval), "=r" (junk)); + return retval; + } + +#else + + #error Need implementation of sqlite3Hwtime() for your platform. + + /* + ** To compile without implementing sqlite3Hwtime() for your platform, + ** you can remove the above #error and use the following + ** stub function. You will lose timing support for many + ** of the debugging and testing utilities, but it should at + ** least compile and run. + */ +SQLITE_PRIVATE sqlite_uint64 sqlite3Hwtime(void){ return ((sqlite_uint64)0); } + +#endif + +#endif /* !defined(_HWTIME_H_) */ + +/************** End of hwtime.h **********************************************/ +/************** Continuing where we left off in os_common.h ******************/ + +static sqlite_uint64 g_start; +static sqlite_uint64 g_elapsed; +#define TIMER_START g_start=sqlite3Hwtime() +#define TIMER_END g_elapsed=sqlite3Hwtime()-g_start +#define TIMER_ELAPSED g_elapsed #else #define TIMER_START #define TIMER_END -#define TIMER_ELAPSED 0 +#define TIMER_ELAPSED ((sqlite_uint64)0) #endif /* @@ -17729,6 +19908,8 @@ SQLITE_API int sqlite3_open_file_count = 0; #define OpenCounter(X) #endif +#endif /* !defined(_OS_COMMON_H_) */ + /************** End of os_common.h *******************************************/ /************** Continuing where we left off in os_os2.c *********************/ @@ -17754,7 +19935,7 @@ struct os2File { /* ** Close a file. */ -int os2Close( sqlite3_file *id ){ +static int os2Close( sqlite3_file *id ){ APIRET rc = NO_ERROR; os2File *pFile; if( id && (pFile = (os2File*)id) != 0 ){ @@ -17778,7 +19959,7 @@ int os2Close( sqlite3_file *id ){ ** bytes were read successfully and SQLITE_IOERR if anything goes ** wrong. */ -int os2Read( +static int os2Read( sqlite3_file *id, /* File to read from */ void *pBuf, /* Write content into this buffer */ int amt, /* Number of bytes to read */ @@ -17808,7 +19989,7 @@ int os2Read( ** Write data from a buffer into a file. Return SQLITE_OK on success ** or some other error code on failure. */ -int os2Write( +static int os2Write( sqlite3_file *id, /* File to write into */ const void *pBuf, /* The bytes to be written */ int amt, /* Number of bytes to write */ @@ -17840,7 +20021,7 @@ int os2Write( /* ** Truncate an open file to a specified size */ -int os2Truncate( sqlite3_file *id, i64 nByte ){ +static int os2Truncate( sqlite3_file *id, i64 nByte ){ APIRET rc = NO_ERROR; os2File *pFile = (os2File*)id; OSTRACE3( "TRUNCATE %d %lld\n", pFile->h, nByte ); @@ -17861,7 +20042,7 @@ SQLITE_API int sqlite3_fullsync_count = 0; /* ** Make sure all writes to a particular file are committed to disk. */ -int os2Sync( sqlite3_file *id, int flags ){ +static int os2Sync( sqlite3_file *id, int flags ){ os2File *pFile = (os2File*)id; OSTRACE3( "SYNC %d lock=%d\n", pFile->h, pFile->locktype ); #ifdef SQLITE_TEST @@ -17876,7 +20057,7 @@ int os2Sync( sqlite3_file *id, int flags ){ /* ** Determine the current size of a file in bytes */ -int os2FileSize( sqlite3_file *id, sqlite3_int64 *pSize ){ +static int os2FileSize( sqlite3_file *id, sqlite3_int64 *pSize ){ APIRET rc = NO_ERROR; FILESTATUS3 fsts3FileInfo; memset(&fsts3FileInfo, 0, sizeof(fsts3FileInfo)); @@ -17953,7 +20134,7 @@ static int unlockReadLock( os2File *id ){ ** It is not possible to lower the locking level one step at a time. You ** must go straight to locking level 0. */ -int os2Lock( sqlite3_file *id, int locktype ){ +static int os2Lock( sqlite3_file *id, int locktype ){ int rc = SQLITE_OK; /* Return code from subroutines */ APIRET res = NO_ERROR; /* Result of an OS/2 lock call */ int newLocktype; /* Set pFile->locktype to this value before exiting */ @@ -18089,7 +20270,7 @@ int os2Lock( sqlite3_file *id, int locktype ){ ** file by this or any other process. If such a lock is held, return ** non-zero, otherwise zero. */ -int os2CheckReservedLock( sqlite3_file *id ){ +static int os2CheckReservedLock( sqlite3_file *id, int *pOut ){ int r = 0; os2File *pFile = (os2File*)id; assert( pFile!=0 ); @@ -18120,7 +20301,8 @@ int os2CheckReservedLock( sqlite3_file *id ){ r = !(rc == NO_ERROR); OSTRACE3( "TEST WR-LOCK %d %d (remote)\n", pFile->h, r ); } - return r; + *pOut = r; + return SQLITE_OK; } /* @@ -18134,7 +20316,7 @@ int os2CheckReservedLock( sqlite3_file *id ){ ** is NO_LOCK. If the second argument is SHARED_LOCK then this routine ** might return SQLITE_IOERR; */ -int os2Unlock( sqlite3_file *id, int locktype ){ +static int os2Unlock( sqlite3_file *id, int locktype ){ int type; os2File *pFile = (os2File*)id; APIRET rc = SQLITE_OK; @@ -18221,32 +20403,57 @@ static int os2DeviceCharacteristics(sqlite3_file *id){ return 0; } + +/* +** Character set conversion objects used by conversion routines. +*/ +static UconvObject ucUtf8 = NULL; /* convert between UTF-8 and UCS-2 */ +static UconvObject uclCp = NULL; /* convert between local codepage and UCS-2 */ + +/* +** Helper function to initialize the conversion objects from and to UTF-8. +*/ +static void initUconvObjects( void ){ + if( UniCreateUconvObject( UTF_8, &ucUtf8 ) != ULS_SUCCESS ) + ucUtf8 = NULL; + if ( UniCreateUconvObject( (UniChar *)L"@path=yes", &uclCp ) != ULS_SUCCESS ) + uclCp = NULL; +} + +/* +** Helper function to free the conversion objects from and to UTF-8. +*/ +static void freeUconvObjects( void ){ + if ( ucUtf8 ) + UniFreeUconvObject( ucUtf8 ); + if ( uclCp ) + UniFreeUconvObject( uclCp ); + ucUtf8 = NULL; + uclCp = NULL; +} + /* ** Helper function to convert UTF-8 filenames to local OS/2 codepage. ** The two-step process: first convert the incoming UTF-8 string ** into UCS-2 and then from UCS-2 to the current codepage. ** The returned char pointer has to be freed. */ -char *convertUtf8PathToCp(const char *in) -{ - UconvObject uconv; - UniChar ucsUtf8Cp[12], - tempPath[CCHMAXPATH]; - char *out; - int rc = 0; +static char *convertUtf8PathToCp( const char *in ){ + UniChar tempPath[CCHMAXPATH]; + char *out = (char *)calloc( CCHMAXPATH, 1 ); + + if( !out ) + return NULL; - out = (char *)calloc(CCHMAXPATH, 1); + if( !ucUtf8 || !uclCp ) + initUconvObjects(); /* determine string for the conversion of UTF-8 which is CP1208 */ - rc = UniMapCpToUcsCp(1208, ucsUtf8Cp, 12); - rc = UniCreateUconvObject(ucsUtf8Cp, &uconv); - rc = UniStrToUcs(uconv, tempPath, (char *)in, CCHMAXPATH); - rc = UniFreeUconvObject(uconv); + if( UniStrToUcs( ucUtf8, tempPath, (char *)in, CCHMAXPATH ) != ULS_SUCCESS ) + return out; /* if conversion fails, return the empty string */ /* conversion for current codepage which can be used for paths */ - rc = UniCreateUconvObject((UniChar *)L"@path=yes", &uconv); - rc = UniStrFromUcs(uconv, out, tempPath, CCHMAXPATH); - rc = UniFreeUconvObject(uconv); + UniStrFromUcs( uclCp, out, tempPath, CCHMAXPATH ); return out; } @@ -18256,27 +20463,26 @@ char *convertUtf8PathToCp(const char *in) ** The two-step process: first convert the incoming codepage-specific ** string into UCS-2 and then from UCS-2 to the codepage of UTF-8. ** The returned char pointer has to be freed. +** +** This function is non-static to be able to use this in shell.c and +** similar applications that take command line arguments. */ -char *convertCpPathToUtf8(const char *in) -{ - UconvObject uconv; - UniChar ucsUtf8Cp[12], - tempPath[CCHMAXPATH]; - char *out; - int rc = 0; +char *convertCpPathToUtf8( const char *in ){ + UniChar tempPath[CCHMAXPATH]; + char *out = (char *)calloc( CCHMAXPATH, 1 ); - out = (char *)calloc(CCHMAXPATH, 1); + if( !out ) + return NULL; + + if( !ucUtf8 || !uclCp ) + initUconvObjects(); /* conversion for current codepage which can be used for paths */ - rc = UniCreateUconvObject((UniChar *)L"@path=yes", &uconv); - rc = UniStrToUcs(uconv, tempPath, (char *)in, CCHMAXPATH); - rc = UniFreeUconvObject(uconv); + if( UniStrToUcs( uclCp, tempPath, (char *)in, CCHMAXPATH ) != ULS_SUCCESS ) + return out; /* if conversion fails, return the empty string */ /* determine string for the conversion of UTF-8 which is CP1208 */ - rc = UniMapCpToUcsCp(1208, ucsUtf8Cp, 12); - rc = UniCreateUconvObject(ucsUtf8Cp, &uconv); - rc = UniStrFromUcs(uconv, out, tempPath, CCHMAXPATH); - rc = UniFreeUconvObject(uconv); + UniStrFromUcs( ucUtf8, out, tempPath, CCHMAXPATH ); return out; } @@ -18308,6 +20514,84 @@ static const sqlite3_io_methods os2IoMethod = { ****************************************************************************/ /* +** Create a temporary file name in zBuf. zBuf must be big enough to +** hold at pVfs->mxPathname characters. +*/ +static int getTempname(int nBuf, char *zBuf ){ + static const unsigned char zChars[] = + "abcdefghijklmnopqrstuvwxyz" + "ABCDEFGHIJKLMNOPQRSTUVWXYZ" + "0123456789"; + int i, j; + char zTempPathBuf[3]; + PSZ zTempPath = (PSZ)&zTempPathBuf; + if( sqlite3_temp_directory ){ + zTempPath = sqlite3_temp_directory; + }else{ + if( DosScanEnv( (PSZ)"TEMP", &zTempPath ) ){ + if( DosScanEnv( (PSZ)"TMP", &zTempPath ) ){ + if( DosScanEnv( (PSZ)"TMPDIR", &zTempPath ) ){ + ULONG ulDriveNum = 0, ulDriveMap = 0; + DosQueryCurrentDisk( &ulDriveNum, &ulDriveMap ); + sprintf( (char*)zTempPath, "%c:", (char)( 'A' + ulDriveNum - 1 ) ); + } + } + } + } + /* Strip off a trailing slashes or backslashes, otherwise we would get * + * multiple (back)slashes which causes DosOpen() to fail. * + * Trailing spaces are not allowed, either. */ + j = strlen(zTempPath); + while( j > 0 && ( zTempPath[j-1] == '\\' || zTempPath[j-1] == '/' + || zTempPath[j-1] == ' ' ) ){ + j--; + } + zTempPath[j] = '\0'; + if( !sqlite3_temp_directory ){ + char *zTempPathUTF = convertCpPathToUtf8( zTempPath ); + sqlite3_snprintf( nBuf-30, zBuf, + "%s\\"SQLITE_TEMP_FILE_PREFIX, zTempPathUTF ); + free( zTempPathUTF ); + }else{ + sqlite3_snprintf( nBuf-30, zBuf, + "%s\\"SQLITE_TEMP_FILE_PREFIX, zTempPath ); + } + j = strlen( zBuf ); + sqlite3_randomness( 20, &zBuf[j] ); + for( i = 0; i < 20; i++, j++ ){ + zBuf[j] = (char)zChars[ ((unsigned char)zBuf[j])%(sizeof(zChars)-1) ]; + } + zBuf[j] = 0; + OSTRACE2( "TEMP FILENAME: %s\n", zBuf ); + return SQLITE_OK; +} + + +/* +** Turn a relative pathname into a full pathname. Write the full +** pathname into zFull[]. zFull[] will be at least pVfs->mxPathname +** bytes in size. +*/ +static int os2FullPathname( + sqlite3_vfs *pVfs, /* Pointer to vfs object */ + const char *zRelative, /* Possibly relative input path */ + int nFull, /* Size of output buffer in bytes */ + char *zFull /* Output buffer */ +){ + char *zRelativeCp = convertUtf8PathToCp( zRelative ); + char zFullCp[CCHMAXPATH] = "\0"; + char *zFullUTF; + APIRET rc = DosQueryPathInfo( zRelativeCp, FIL_QUERYFULLNAME, zFullCp, + CCHMAXPATH ); + free( zRelativeCp ); + zFullUTF = convertCpPathToUtf8( zFullCp ); + sqlite3_snprintf( nFull, zFull, zFullUTF ); + free( zFullUTF ); + return rc == NO_ERROR ? SQLITE_OK : SQLITE_IOERR; +} + + +/* ** Open a file. */ static int os2Open( @@ -18324,12 +20608,26 @@ static int os2Open( os2File *pFile = (os2File*)id; APIRET rc = NO_ERROR; ULONG ulAction; + char *zNameCp; + char zTmpname[CCHMAXPATH+1]; /* Buffer to hold name of temp file */ + + /* If the second argument to this function is NULL, generate a + ** temporary file name to use + */ + if( !zName ){ + int rc = getTempname(CCHMAXPATH+1, zTmpname); + if( rc!=SQLITE_OK ){ + return rc; + } + zName = zTmpname; + } + memset( pFile, 0, sizeof(*pFile) ); OSTRACE2( "OPEN want %d\n", flags ); - /* ulOpenMode = flags & SQLITE_OPEN_READWRITE ? OPEN_ACCESS_READWRITE : OPEN_ACCESS_READONLY; */ + /*ulOpenMode = flags & SQLITE_OPEN_READWRITE ? OPEN_ACCESS_READWRITE : OPEN_ACCESS_READONLY;*/ if( flags & SQLITE_OPEN_READWRITE ){ ulOpenMode |= OPEN_ACCESS_READWRITE; OSTRACE1( "OPEN read/write\n" ); @@ -18338,7 +20636,7 @@ static int os2Open( OSTRACE1( "OPEN read only\n" ); } - /* ulOpenFlags = flags & SQLITE_OPEN_CREATE ? OPEN_ACTION_CREATE_IF_NEW : OPEN_ACTION_FAIL_IF_NEW; */ + /*ulOpenFlags = flags & SQLITE_OPEN_CREATE ? OPEN_ACTION_CREATE_IF_NEW : OPEN_ACTION_FAIL_IF_NEW;*/ if( flags & SQLITE_OPEN_CREATE ){ ulOpenFlags |= OPEN_ACTION_OPEN_IF_EXISTS | OPEN_ACTION_CREATE_IF_NEW; OSTRACE1( "OPEN open new/create\n" ); @@ -18347,7 +20645,7 @@ static int os2Open( OSTRACE1( "OPEN open existing\n" ); } - /* ulOpenMode |= flags & SQLITE_OPEN_MAIN_DB ? OPEN_SHARE_DENYNONE : OPEN_SHARE_DENYWRITE; */ + /*ulOpenMode |= flags & SQLITE_OPEN_MAIN_DB ? OPEN_SHARE_DENYNONE : OPEN_SHARE_DENYWRITE;*/ if( flags & SQLITE_OPEN_MAIN_DB ){ ulOpenMode |= OPEN_SHARE_DENYNONE; OSTRACE1( "OPEN share read/write\n" ); @@ -18359,9 +20657,11 @@ static int os2Open( if( flags & (SQLITE_OPEN_TEMP_DB | SQLITE_OPEN_TEMP_JOURNAL | SQLITE_OPEN_SUBJOURNAL) ){ char pathUtf8[CCHMAXPATH]; - /* ulFileAttribute = FILE_HIDDEN; //for debugging, we want to make sure it is deleted */ +#ifdef NDEBUG /* when debugging we want to make sure it is deleted */ + ulFileAttribute = FILE_HIDDEN; +#endif ulFileAttribute = FILE_NORMAL; - sqlite3OsFullPathname( pVfs, zName, CCHMAXPATH, pathUtf8 ); + os2FullPathname( pVfs, zName, CCHMAXPATH, pathUtf8 ); pFile->pathToDel = convertUtf8PathToCp( pathUtf8 ); OSTRACE1( "OPEN hidden/delete on close file attributes\n" ); }else{ @@ -18375,7 +20675,7 @@ static int os2Open( ulOpenMode |= OPEN_FLAGS_FAIL_ON_ERROR; ulOpenMode |= OPEN_FLAGS_NOINHERIT; - char *zNameCp = convertUtf8PathToCp( zName ); + zNameCp = convertUtf8PathToCp( zName ); rc = DosOpen( (PSZ)zNameCp, &h, &ulAction, @@ -18388,11 +20688,12 @@ static int os2Open( if( rc != NO_ERROR ){ OSTRACE7( "OPEN Invalid handle rc=%d: zName=%s, ulAction=%#lx, ulAttr=%#lx, ulFlags=%#lx, ulMode=%#lx\n", rc, zName, ulAction, ulFileAttribute, ulOpenFlags, ulOpenMode ); - free( pFile->pathToDel ); + if( pFile->pathToDel ) + free( pFile->pathToDel ); pFile->pathToDel = NULL; if( flags & SQLITE_OPEN_READWRITE ){ OSTRACE2( "OPEN %d Invalid handle\n", ((flags | SQLITE_OPEN_READONLY) & ~SQLITE_OPEN_READWRITE) ); - return os2Open( 0, zName, id, + return os2Open( pVfs, zName, id, ((flags | SQLITE_OPEN_READONLY) & ~SQLITE_OPEN_READWRITE), pOutFlags ); }else{ @@ -18414,14 +20715,14 @@ static int os2Open( /* ** Delete the named file. */ -int os2Delete( +static int os2Delete( sqlite3_vfs *pVfs, /* Not used on os2 */ const char *zFilename, /* Name of file to delete */ int syncDir /* Not used on os2 */ ){ APIRET rc = NO_ERROR; - SimulateIOError(return SQLITE_IOERR_DELETE); char *zFilenameCp = convertUtf8PathToCp( zFilename ); + SimulateIOError( return SQLITE_IOERR_DELETE ); rc = DosDelete( (PSZ)zFilenameCp ); free( zFilenameCp ); OSTRACE2( "DELETE \"%s\"\n", zFilename ); @@ -18434,13 +20735,14 @@ int os2Delete( static int os2Access( sqlite3_vfs *pVfs, /* Not used on os2 */ const char *zFilename, /* Name of file to check */ - int flags /* Type of test to make on this file */ + int flags, /* Type of test to make on this file */ + int *pOut /* Write results here */ ){ FILESTATUS3 fsts3ConfigInfo; APIRET rc = NO_ERROR; + char *zFilenameCp = convertUtf8PathToCp( zFilename ); memset( &fsts3ConfigInfo, 0, sizeof(fsts3ConfigInfo) ); - char *zFilenameCp = convertUtf8PathToCp( zFilename ); rc = DosQueryPathInfo( (PSZ)zFilenameCp, FIL_STANDARD, &fsts3ConfigInfo, sizeof(FILESTATUS3) ); free( zFilenameCp ); @@ -18453,83 +20755,17 @@ static int os2Access( OSTRACE3( "ACCESS %s access of read and exists rc=%d\n", zFilename, rc ); break; case SQLITE_ACCESS_READWRITE: - rc = (fsts3ConfigInfo.attrFile & FILE_READONLY) == 0; + rc = (rc == NO_ERROR) && ( (fsts3ConfigInfo.attrFile & FILE_READONLY) == 0 ); OSTRACE3( "ACCESS %s access of read/write rc=%d\n", zFilename, rc ); break; default: assert( !"Invalid flags argument" ); } - return rc; -} - - -/* -** Create a temporary file name in zBuf. zBuf must be big enough to -** hold at pVfs->mxPathname characters. -*/ -static int os2GetTempname( sqlite3_vfs *pVfs, int nBuf, char *zBuf ){ - static const unsigned char zChars[] = - "abcdefghijklmnopqrstuvwxyz" - "ABCDEFGHIJKLMNOPQRSTUVWXYZ" - "0123456789"; - int i, j; - char zTempPathBuf[3]; - PSZ zTempPath = (PSZ)&zTempPathBuf; - char *zTempPathUTF; - if( DosScanEnv( (PSZ)"TEMP", &zTempPath ) ){ - if( DosScanEnv( (PSZ)"TMP", &zTempPath ) ){ - if( DosScanEnv( (PSZ)"TMPDIR", &zTempPath ) ){ - ULONG ulDriveNum = 0, ulDriveMap = 0; - DosQueryCurrentDisk( &ulDriveNum, &ulDriveMap ); - sprintf( (char*)zTempPath, "%c:", (char)( 'A' + ulDriveNum - 1 ) ); - } - } - } - /* strip off a trailing slashes or backslashes, otherwise we would get * - * multiple (back)slashes which causes DosOpen() to fail */ - j = strlen(zTempPath); - while( j > 0 && ( zTempPath[j-1] == '\\' || zTempPath[j-1] == '/' ) ){ - j--; - } - zTempPath[j] = '\0'; - zTempPathUTF = convertCpPathToUtf8( zTempPath ); - sqlite3_snprintf( nBuf-30, zBuf, - "%s\\"SQLITE_TEMP_FILE_PREFIX, zTempPathUTF ); - free( zTempPathUTF ); - j = strlen( zBuf ); - sqlite3_randomness( 20, &zBuf[j] ); - for( i = 0; i < 20; i++, j++ ){ - zBuf[j] = (char)zChars[ ((unsigned char)zBuf[j])%(sizeof(zChars)-1) ]; - } - zBuf[j] = 0; - OSTRACE2( "TEMP FILENAME: %s\n", zBuf ); + *pOut = rc; return SQLITE_OK; } -/* -** Turn a relative pathname into a full pathname. Write the full -** pathname into zFull[]. zFull[] will be at least pVfs->mxPathname -** bytes in size. -*/ -static int os2FullPathname( - sqlite3_vfs *pVfs, /* Pointer to vfs object */ - const char *zRelative, /* Possibly relative input path */ - int nFull, /* Size of output buffer in bytes */ - char *zFull /* Output buffer */ -){ - char *zRelativeCp = convertUtf8PathToCp( zRelative ); - char zFullCp[CCHMAXPATH]; - char *zFullUTF; - APIRET rc = DosQueryPathInfo( zRelativeCp, FIL_QUERYFULLNAME, zFullCp, - CCHMAXPATH ); - free( zRelativeCp ); - zFullUTF = convertCpPathToUtf8( zFullCp ); - sqlite3_snprintf( nFull, zFull, zFullUTF ); - free( zFullUTF ); - return rc == NO_ERROR ? SQLITE_OK : SQLITE_IOERR; -} - #ifndef SQLITE_OMIT_LOAD_EXTENSION /* ** Interfaces for opening a shared library, finding entry points @@ -18555,7 +20791,7 @@ static void *os2DlOpen(sqlite3_vfs *pVfs, const char *zFilename){ static void os2DlError(sqlite3_vfs *pVfs, int nBuf, char *zBufOut){ /* no-op */ } -void *os2DlSym(sqlite3_vfs *pVfs, void *pHandle, const char *zSymbol){ +static void *os2DlSym(sqlite3_vfs *pVfs, void *pHandle, const char *zSymbol){ PFN pfn; APIRET rc; rc = DosQueryProcAddr((HMODULE)pHandle, 0L, zSymbol, &pfn); @@ -18569,7 +20805,7 @@ void *os2DlSym(sqlite3_vfs *pVfs, void *pHandle, const char *zSymbol){ } return rc != NO_ERROR ? 0 : (void*)pfn; } -void os2DlClose(sqlite3_vfs *pVfs, void *pHandle){ +static void os2DlClose(sqlite3_vfs *pVfs, void *pHandle){ DosFreeModule((HMODULE)pHandle); } #else /* if SQLITE_OMIT_LOAD_EXTENSION is defined: */ @@ -18698,13 +20934,14 @@ int os2CurrentTime( sqlite3_vfs *pVfs, double *prNow ){ return 0; } +static int os2GetLastError(sqlite3_vfs *pVfs, int nBuf, char *zBuf){ + return 0; +} + /* -** Return a pointer to the sqlite3DefaultVfs structure. We use -** a function rather than give the structure global scope because -** some compilers (MSVC) do not allow forward declarations of -** initialized structures. +** Initialize and deinitialize the operating system interface. */ -SQLITE_PRIVATE sqlite3_vfs *sqlite3OsDefaultVfs(void){ +SQLITE_API int sqlite3_os_init(void){ static sqlite3_vfs os2Vfs = { 1, /* iVersion */ sizeof(os2File), /* szOsFile */ @@ -18716,7 +20953,6 @@ SQLITE_PRIVATE sqlite3_vfs *sqlite3OsDefaultVfs(void){ os2Open, /* xOpen */ os2Delete, /* xDelete */ os2Access, /* xAccess */ - os2GetTempname, /* xGetTempname */ os2FullPathname, /* xFullPathname */ os2DlOpen, /* xDlOpen */ os2DlError, /* xDlError */ @@ -18724,13 +20960,19 @@ SQLITE_PRIVATE sqlite3_vfs *sqlite3OsDefaultVfs(void){ os2DlClose, /* xDlClose */ os2Randomness, /* xRandomness */ os2Sleep, /* xSleep */ - os2CurrentTime /* xCurrentTime */ + os2CurrentTime, /* xCurrentTime */ + os2GetLastError /* xGetLastError */ }; - - return &os2Vfs; + sqlite3_vfs_register(&os2Vfs, 1); + initUconvObjects(); + return SQLITE_OK; +} +SQLITE_API int sqlite3_os_end(void){ + freeUconvObjects(); + return SQLITE_OK; } -#endif /* OS_OS2 */ +#endif /* SQLITE_OS_OS2 */ /************** End of os_os2.c **********************************************/ /************** Begin file os_unix.c *****************************************/ @@ -18747,9 +20989,21 @@ SQLITE_PRIVATE sqlite3_vfs *sqlite3OsDefaultVfs(void){ ****************************************************************************** ** ** This file contains code that is specific to Unix systems. +** +** $Id$ */ -#if OS_UNIX /* This file is used on unix only */ +#if SQLITE_OS_UNIX /* This file is used on unix only */ +/* +** If SQLITE_ENABLE_LOCKING_STYLE is defined, then several different +** locking implementations are provided: +** +** * POSIX locking (the default), +** * No locking, +** * Dot-file locking, +** * flock() locking, +** * AFP locking (OSX only). +*/ /* #define SQLITE_ENABLE_LOCKING_STYLE 0 */ /* @@ -18782,6 +21036,7 @@ SQLITE_PRIVATE sqlite3_vfs *sqlite3OsDefaultVfs(void){ #include <unistd.h> #include <sys/time.h> #include <errno.h> + #ifdef SQLITE_ENABLE_LOCKING_STYLE #include <sys/ioctl.h> #include <sys/param.h> @@ -18826,7 +21081,7 @@ struct unixFile { struct lockInfo *pLock; /* Info about locks on this inode */ #ifdef SQLITE_ENABLE_LOCKING_STYLE void *lockingContext; /* Locking style specific state */ -#endif /* SQLITE_ENABLE_LOCKING_STYLE */ +#endif int h; /* The file descriptor */ unsigned char locktype; /* The type of lock held on this fd */ int dirfd; /* File descriptor for the directory */ @@ -18858,7 +21113,11 @@ struct unixFile { ** ** This file should be #included by the os_*.c files only. It is not a ** general purpose header file. +** +** $Id$ */ +#ifndef _OS_COMMON_H_ +#define _OS_COMMON_H_ /* ** At least two bugs have slipped in because we changed the MEMORY_DEBUG @@ -18904,22 +21163,113 @@ SQLITE_PRIVATE int sqlite3OSTrace = 0; ** on i486 hardware. */ #ifdef SQLITE_PERFORMANCE_TRACE -__inline__ unsigned long long int hwtime(void){ - unsigned long long int x; - __asm__("rdtsc\n\t" - "mov %%edx, %%ecx\n\t" - :"=A" (x)); - return x; -} -static unsigned long long int g_start; -static unsigned int elapse; -#define TIMER_START g_start=hwtime() -#define TIMER_END elapse=hwtime()-g_start -#define TIMER_ELAPSED elapse + +/* +** hwtime.h contains inline assembler code for implementing +** high-performance timing routines. +*/ +/************** Include hwtime.h in the middle of os_common.h ****************/ +/************** Begin file hwtime.h ******************************************/ +/* +** 2008 May 27 +** +** The author disclaims copyright to this source code. In place of +** a legal notice, here is a blessing: +** +** May you do good and not evil. +** May you find forgiveness for yourself and forgive others. +** May you share freely, never taking more than you give. +** +****************************************************************************** +** +** This file contains inline asm code for retrieving "high-performance" +** counters for x86 class CPUs. +** +** $Id$ +*/ +#ifndef _HWTIME_H_ +#define _HWTIME_H_ + +/* +** The following routine only works on pentium-class (or newer) processors. +** It uses the RDTSC opcode to read the cycle count value out of the +** processor and returns that value. This can be used for high-res +** profiling. +*/ +#if (defined(__GNUC__) || defined(_MSC_VER)) && \ + (defined(i386) || defined(__i386__) || defined(_M_IX86)) + + #if defined(__GNUC__) + + __inline__ sqlite_uint64 sqlite3Hwtime(void){ + unsigned int lo, hi; + __asm__ __volatile__ ("rdtsc" : "=a" (lo), "=d" (hi)); + return (sqlite_uint64)hi << 32 | lo; + } + + #elif defined(_MSC_VER) + + __declspec(naked) __inline sqlite_uint64 __cdecl sqlite3Hwtime(void){ + __asm { + rdtsc + ret ; return value at EDX:EAX + } + } + + #endif + +#elif (defined(__GNUC__) && defined(__x86_64__)) + + __inline__ sqlite_uint64 sqlite3Hwtime(void){ + unsigned long val; + __asm__ __volatile__ ("rdtsc" : "=A" (val)); + return val; + } + +#elif (defined(__GNUC__) && defined(__ppc__)) + + __inline__ sqlite_uint64 sqlite3Hwtime(void){ + unsigned long long retval; + unsigned long junk; + __asm__ __volatile__ ("\n\ + 1: mftbu %1\n\ + mftb %L0\n\ + mftbu %0\n\ + cmpw %0,%1\n\ + bne 1b" + : "=r" (retval), "=r" (junk)); + return retval; + } + +#else + + #error Need implementation of sqlite3Hwtime() for your platform. + + /* + ** To compile without implementing sqlite3Hwtime() for your platform, + ** you can remove the above #error and use the following + ** stub function. You will lose timing support for many + ** of the debugging and testing utilities, but it should at + ** least compile and run. + */ +SQLITE_PRIVATE sqlite_uint64 sqlite3Hwtime(void){ return ((sqlite_uint64)0); } + +#endif + +#endif /* !defined(_HWTIME_H_) */ + +/************** End of hwtime.h **********************************************/ +/************** Continuing where we left off in os_common.h ******************/ + +static sqlite_uint64 g_start; +static sqlite_uint64 g_elapsed; +#define TIMER_START g_start=sqlite3Hwtime() +#define TIMER_END g_elapsed=sqlite3Hwtime()-g_start +#define TIMER_ELAPSED g_elapsed #else #define TIMER_START #define TIMER_END -#define TIMER_ELAPSED 0 +#define TIMER_ELAPSED ((sqlite_uint64)0) #endif /* @@ -18972,6 +21322,8 @@ SQLITE_API int sqlite3_open_file_count = 0; #define OpenCounter(X) #endif +#endif /* !defined(_OS_COMMON_H_) */ + /************** End of os_common.h *******************************************/ /************** Continuing where we left off in os_unix.c ********************/ @@ -19044,8 +21396,6 @@ SQLITE_API int sqlite3_open_file_count = 0; ** by the same process. It does not explicitly say so, but this implies ** that it overrides locks set by the same process using a different ** file descriptor. Consider this test case: -** -** int fd1 = open("./file1", O_RDWR|O_CREAT, 0644); ** int fd2 = open("./file2", O_RDWR|O_CREAT, 0644); ** ** Suppose ./file1 and ./file2 are really the same file (because @@ -19168,6 +21518,7 @@ struct lockInfo { int cnt; /* Number of SHARED locks held */ int locktype; /* One of SHARED_LOCK, RESERVED_LOCK etc. */ int nRef; /* Number of pointers to this structure */ + struct lockInfo *pNext, *pPrev; /* List of all lockInfo objects */ }; /* @@ -19193,23 +21544,24 @@ struct openCnt { int nLock; /* Number of outstanding locks */ int nPending; /* Number of pending close() operations */ int *aPending; /* Malloced space holding fd's awaiting a close() */ + struct openCnt *pNext, *pPrev; /* List of all openCnt objects */ }; -/* -** These hash tables map inodes and file descriptors (really, lockKey and -** openKey structures) into lockInfo and openCnt structures. Access to -** these hash tables must be protected by a mutex. +/* +** List of all lockInfo and openCnt objects. This used to be a hash +** table. But the number of objects is rarely more than a dozen and +** never exceeds a few thousand. And lookup is not on a critical +** path oo a simple linked list will suffice. */ -static Hash lockHash = {SQLITE_HASH_BINARY, 0, 0, 0, 0, 0}; -static Hash openHash = {SQLITE_HASH_BINARY, 0, 0, 0, 0, 0}; +static struct lockInfo *lockList = 0; +static struct openCnt *openList = 0; -#ifdef SQLITE_ENABLE_LOCKING_STYLE /* ** The locking styles are associated with the different file locking ** capabilities supported by different file systems. ** ** POSIX locking style fully supports shared and exclusive byte-range locks -** ADP locking only supports exclusive byte-range locks +** AFP locking only supports exclusive byte-range locks ** FLOCK only supports a single file-global exclusive lock ** DOTLOCK isn't a true locking style, it refers to the use of a special ** file named the same as the database file with a '.lock' extension, this @@ -19219,24 +21571,20 @@ static Hash openHash = {SQLITE_HASH_BINARY, 0, 0, 0, 0, 0}; ** UNSUPPORTED means that no locking will be attempted, this is only used for ** file systems that are known to be unsupported */ -typedef enum { - posixLockingStyle = 0, /* standard posix-advisory locks */ - afpLockingStyle, /* use afp locks */ - flockLockingStyle, /* use flock() */ - dotlockLockingStyle, /* use <file>.lock files */ - noLockingStyle, /* useful for read-only file system */ - unsupportedLockingStyle /* indicates unsupported file system */ -} sqlite3LockingStyle; -#endif /* SQLITE_ENABLE_LOCKING_STYLE */ +#define LOCKING_STYLE_POSIX 1 +#define LOCKING_STYLE_NONE 2 +#define LOCKING_STYLE_DOTFILE 3 +#define LOCKING_STYLE_FLOCK 4 +#define LOCKING_STYLE_AFP 5 /* ** Helper functions to obtain and relinquish the global mutex. */ static void enterMutex(){ - sqlite3_mutex_enter(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MASTER)); + sqlite3_mutex_enter(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER)); } static void leaveMutex(){ - sqlite3_mutex_leave(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MASTER)); + sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER)); } #if SQLITE_THREADSAFE @@ -19382,12 +21730,22 @@ static void testThreadLockingBehavior(int fd_orig){ ** Release a lockInfo structure previously allocated by findLockInfo(). */ static void releaseLockInfo(struct lockInfo *pLock){ - if (pLock == NULL) - return; - pLock->nRef--; - if( pLock->nRef==0 ){ - sqlite3HashInsert(&lockHash, &pLock->key, sizeof(pLock->key), 0); - sqlite3_free(pLock); + if( pLock ){ + pLock->nRef--; + if( pLock->nRef==0 ){ + if( pLock->pPrev ){ + assert( pLock->pPrev->pNext==pLock ); + pLock->pPrev->pNext = pLock->pNext; + }else{ + assert( lockList==pLock ); + lockList = pLock->pNext; + } + if( pLock->pNext ){ + assert( pLock->pNext->pPrev==pLock ); + pLock->pNext->pPrev = pLock->pPrev; + } + sqlite3_free(pLock); + } } } @@ -19395,13 +21753,23 @@ static void releaseLockInfo(struct lockInfo *pLock){ ** Release a openCnt structure previously allocated by findLockInfo(). */ static void releaseOpenCnt(struct openCnt *pOpen){ - if (pOpen == NULL) - return; - pOpen->nRef--; - if( pOpen->nRef==0 ){ - sqlite3HashInsert(&openHash, &pOpen->key, sizeof(pOpen->key), 0); - free(pOpen->aPending); - sqlite3_free(pOpen); + if( pOpen ){ + pOpen->nRef--; + if( pOpen->nRef==0 ){ + if( pOpen->pPrev ){ + assert( pOpen->pPrev->pNext==pOpen ); + pOpen->pPrev->pNext = pOpen->pNext; + }else{ + assert( openList==pOpen ); + openList = pOpen->pNext; + } + if( pOpen->pNext ){ + assert( pOpen->pNext->pPrev==pOpen ); + pOpen->pNext->pPrev = pOpen->pPrev; + } + sqlite3_free(pOpen->aPending); + sqlite3_free(pOpen); + } } } @@ -19410,75 +21778,82 @@ static void releaseOpenCnt(struct openCnt *pOpen){ ** Tests a byte-range locking query to see if byte range locks are ** supported, if not we fall back to dotlockLockingStyle. */ -static sqlite3LockingStyle sqlite3TestLockingStyle( - const char *filePath, - int fd -){ - /* test byte-range lock using fcntl */ +static int testLockingStyle(int fd){ struct flock lockInfo; - + + /* Test byte-range lock using fcntl(). If the call succeeds, + ** assume that the file-system supports POSIX style locks. + */ lockInfo.l_len = 1; lockInfo.l_start = 0; lockInfo.l_whence = SEEK_SET; lockInfo.l_type = F_RDLCK; - if( fcntl(fd, F_GETLK, &lockInfo)!=-1 ) { - return posixLockingStyle; - } + return LOCKING_STYLE_POSIX; + } - /* testing for flock can give false positives. So if if the above test - ** fails, then we fall back to using dot-lock style locking. + /* Testing for flock() can give false positives. So if if the above + ** test fails, then we fall back to using dot-file style locking. */ - return dotlockLockingStyle; + return LOCKING_STYLE_DOTFILE; } +#endif /* -** Examines the f_fstypename entry in the statfs structure as returned by -** stat() for the file system hosting the database file, assigns the -** appropriate locking style based on its value. These values and -** assignments are based on Darwin/OSX behavior and have not been tested on +** If SQLITE_ENABLE_LOCKING_STYLE is defined, this function Examines the +** f_fstypename entry in the statfs structure as returned by stat() for +** the file system hosting the database file and selects the appropriate +** locking style based on its value. These values and assignments are +** based on Darwin/OSX behavior and have not been thoroughly tested on ** other systems. +** +** If SQLITE_ENABLE_LOCKING_STYLE is not defined, this function always +** returns LOCKING_STYLE_POSIX. */ -static sqlite3LockingStyle sqlite3DetectLockingStyle( +static int detectLockingStyle( + sqlite3_vfs *pVfs, const char *filePath, int fd ){ - -#ifdef SQLITE_FIXED_LOCKING_STYLE - return (sqlite3LockingStyle)SQLITE_FIXED_LOCKING_STYLE; -#else +#ifdef SQLITE_ENABLE_LOCKING_STYLE + struct Mapping { + const char *zFilesystem; + int eLockingStyle; + } aMap[] = { + { "hfs", LOCKING_STYLE_POSIX }, + { "ufs", LOCKING_STYLE_POSIX }, + { "afpfs", LOCKING_STYLE_AFP }, + { "smbfs", LOCKING_STYLE_FLOCK }, + { "msdos", LOCKING_STYLE_DOTFILE }, + { "webdav", LOCKING_STYLE_NONE }, + { 0, 0 } + }; + int i; struct statfs fsInfo; - if( statfs(filePath, &fsInfo) == -1 ){ - return sqlite3TestLockingStyle(filePath, fd); + if( !filePath ){ + return LOCKING_STYLE_NONE; } - if( fsInfo.f_flags & MNT_RDONLY ){ - return noLockingStyle; + if( pVfs->pAppData ){ + return (int)pVfs->pAppData; } - if( strcmp(fsInfo.f_fstypename, "hfs")==0 || - strcmp(fsInfo.f_fstypename, "ufs")==0 ){ - return posixLockingStyle; - } - if( strcmp(fsInfo.f_fstypename, "afpfs")==0 ){ - return afpLockingStyle; - } - if( strcmp(fsInfo.f_fstypename, "nfs")==0 ){ - return sqlite3TestLockingStyle(filePath, fd); - } - if( strcmp(fsInfo.f_fstypename, "smbfs")==0 ){ - return flockLockingStyle; - } - if( strcmp(fsInfo.f_fstypename, "msdos")==0 ){ - return dotlockLockingStyle; - } - if( strcmp(fsInfo.f_fstypename, "webdav")==0 ){ - return unsupportedLockingStyle; + + if( statfs(filePath, &fsInfo) != -1 ){ + if( fsInfo.f_flags & MNT_RDONLY ){ + return LOCKING_STYLE_NONE; + } + for(i=0; aMap[i].zFilesystem; i++){ + if( strcmp(fsInfo.f_fstypename, aMap[i].zFilesystem)==0 ){ + return aMap[i].eLockingStyle; + } + } } - return sqlite3TestLockingStyle(filePath, fd); -#endif /* SQLITE_FIXED_LOCKING_STYLE */ -} -#endif /* SQLITE_ENABLE_LOCKING_STYLE */ + /* Default case. Handles, amongst others, "nfs". */ + return testLockingStyle(fd); +#endif + return LOCKING_STYLE_POSIX; +} /* ** Given a file descriptor, locate lockInfo and openCnt structures that @@ -19506,6 +21881,24 @@ static int findLockInfo( return SQLITE_IOERR; } + /* On OS X on an msdos filesystem, the inode number is reported + ** incorrectly for zero-size files. See ticket #3260. To work + ** around this problem (we consider it a bug in OS X, not SQLite) + ** we always increase the file size to 1 by writing a single byte + ** prior to accessing the inode number. The one byte written is + ** an ASCII 'S' character which also happens to be the first byte + ** in the header of every SQLite database. In this way, if there + ** is a race condition such that another thread has already populated + ** the first page of the database, no damage is done. + */ + if( statbuf.st_size==0 ){ + write(fd, "S", 1); + rc = fstat(fd, &statbuf); + if( rc!=0 ){ + return SQLITE_IOERR; + } + } + memset(&key1, 0, sizeof(key1)); key1.dev = statbuf.st_dev; key1.ino = statbuf.st_ino; @@ -19518,9 +21911,11 @@ static int findLockInfo( memset(&key2, 0, sizeof(key2)); key2.dev = statbuf.st_dev; key2.ino = statbuf.st_ino; - pLock = (struct lockInfo*)sqlite3HashFind(&lockHash, &key1, sizeof(key1)); + pLock = lockList; + while( pLock && memcmp(&key1, &pLock->key, sizeof(key1)) ){ + pLock = pLock->pNext; + } if( pLock==0 ){ - struct lockInfo *pOld; pLock = sqlite3_malloc( sizeof(*pLock) ); if( pLock==0 ){ rc = SQLITE_NOMEM; @@ -19530,21 +21925,20 @@ static int findLockInfo( pLock->nRef = 1; pLock->cnt = 0; pLock->locktype = 0; - pOld = sqlite3HashInsert(&lockHash, &pLock->key, sizeof(key1), pLock); - if( pOld!=0 ){ - assert( pOld==pLock ); - sqlite3_free(pLock); - rc = SQLITE_NOMEM; - goto exit_findlockinfo; - } + pLock->pNext = lockList; + pLock->pPrev = 0; + if( lockList ) lockList->pPrev = pLock; + lockList = pLock; }else{ pLock->nRef++; } *ppLock = pLock; if( ppOpen!=0 ){ - pOpen = (struct openCnt*)sqlite3HashFind(&openHash, &key2, sizeof(key2)); + pOpen = openList; + while( pOpen && memcmp(&key2, &pOpen->key, sizeof(key2)) ){ + pOpen = pOpen->pNext; + } if( pOpen==0 ){ - struct openCnt *pOld; pOpen = sqlite3_malloc( sizeof(*pOpen) ); if( pOpen==0 ){ releaseLockInfo(pLock); @@ -19556,14 +21950,10 @@ static int findLockInfo( pOpen->nLock = 0; pOpen->nPending = 0; pOpen->aPending = 0; - pOld = sqlite3HashInsert(&openHash, &pOpen->key, sizeof(key2), pOpen); - if( pOld!=0 ){ - assert( pOld==pOpen ); - sqlite3_free(pOpen); - releaseLockInfo(pLock); - rc = SQLITE_NOMEM; - goto exit_findlockinfo; - } + pOpen->pNext = openList; + pOpen->pPrev = 0; + if( openList ) openList->pPrev = pOpen; + openList = pOpen; }else{ pOpen->nRef++; } @@ -19671,7 +22061,7 @@ static int seekAndRead(unixFile *id, sqlite3_int64 offset, void *pBuf, int cnt){ got = read(id->h, pBuf, cnt); #endif TIMER_END; - OSTRACE5("READ %-3d %5d %7lld %d\n", id->h, got, offset, TIMER_ELAPSED); + OSTRACE5("READ %-3d %5d %7lld %llu\n", id->h, got, offset, TIMER_ELAPSED); return got; } @@ -19719,7 +22109,7 @@ static int seekAndWrite(unixFile *id, i64 offset, const void *pBuf, int cnt){ got = write(id->h, pBuf, cnt); #endif TIMER_END; - OSTRACE5("WRITE %-3d %5d %7lld %d\n", id->h, got, offset, TIMER_ELAPSED); + OSTRACE5("WRITE %-3d %5d %7lld %llu\n", id->h, got, offset, TIMER_ELAPSED); return got; } @@ -19927,6 +22317,16 @@ static int unixFileSize(sqlite3_file *id, i64 *pSize){ return SQLITE_IOERR_FSTAT; } *pSize = buf.st_size; + + /* When opening a zero-size database, the findLockInfo() procedure + ** writes a single byte into that file in order to work around a bug + ** in the OS-X msdos filesystem. In order to avoid problems with upper + ** layers, we need to report this file size as zero even though it is + ** really 1. Ticket #3260. + */ + if( *pSize==1 ) *pSize = 0; + + return SQLITE_OK; } @@ -19936,10 +22336,12 @@ static int unixFileSize(sqlite3_file *id, i64 *pSize){ ** non-zero. If the file is unlocked or holds only SHARED locks, then ** return zero. */ -static int unixCheckReservedLock(sqlite3_file *id){ +static int unixCheckReservedLock(sqlite3_file *id, int *pResOut){ int r = 0; unixFile *pFile = (unixFile*)id; + SimulateIOError( return SQLITE_IOERR_CHECKRESERVEDLOCK; ); + assert( pFile ); enterMutex(); /* Because pFile->pLock is shared across threads */ @@ -19965,7 +22367,8 @@ static int unixCheckReservedLock(sqlite3_file *id){ leaveMutex(); OSTRACE3("TEST WR-LOCK %d %d\n", pFile->h, r); - return r; + *pResOut = r; + return SQLITE_OK; } /* @@ -20276,7 +22679,7 @@ static int unixUnlock(sqlite3_file *id, int locktype){ for(i=0; i<pOpen->nPending; i++){ close(pOpen->aPending[i]); } - free(pOpen->aPending); + sqlite3_free(pOpen->aPending); pOpen->nPending = 0; pOpen->aPending = 0; } @@ -20288,43 +22691,58 @@ static int unixUnlock(sqlite3_file *id, int locktype){ } /* +** This function performs the parts of the "close file" operation +** common to all locking schemes. It closes the directory and file +** handles, if they are valid, and sets all fields of the unixFile +** structure to 0. +*/ +static int closeUnixFile(sqlite3_file *id){ + unixFile *pFile = (unixFile*)id; + if( pFile ){ + if( pFile->dirfd>=0 ){ + close(pFile->dirfd); + } + if( pFile->h>=0 ){ + close(pFile->h); + } + OSTRACE2("CLOSE %-3d\n", pFile->h); + OpenCounter(-1); + memset(pFile, 0, sizeof(unixFile)); + } + return SQLITE_OK; +} + +/* ** Close a file. */ static int unixClose(sqlite3_file *id){ - unixFile *pFile = (unixFile *)id; - if( !pFile ) return SQLITE_OK; - unixUnlock(id, NO_LOCK); - if( pFile->dirfd>=0 ) close(pFile->dirfd); - pFile->dirfd = -1; - enterMutex(); - - if( pFile->pOpen->nLock ){ - /* If there are outstanding locks, do not actually close the file just - ** yet because that would clear those locks. Instead, add the file - ** descriptor to pOpen->aPending. It will be automatically closed when - ** the last lock is cleared. - */ - int *aNew; - struct openCnt *pOpen = pFile->pOpen; - aNew = realloc( pOpen->aPending, (pOpen->nPending+1)*sizeof(int) ); - if( aNew==0 ){ - /* If a malloc fails, just leak the file descriptor */ - }else{ - pOpen->aPending = aNew; - pOpen->aPending[pOpen->nPending] = pFile->h; - pOpen->nPending++; + if( id ){ + unixFile *pFile = (unixFile *)id; + unixUnlock(id, NO_LOCK); + enterMutex(); + if( pFile->pOpen && pFile->pOpen->nLock ){ + /* If there are outstanding locks, do not actually close the file just + ** yet because that would clear those locks. Instead, add the file + ** descriptor to pOpen->aPending. It will be automatically closed when + ** the last lock is cleared. + */ + int *aNew; + struct openCnt *pOpen = pFile->pOpen; + aNew = sqlite3_realloc(pOpen->aPending, (pOpen->nPending+1)*sizeof(int) ); + if( aNew==0 ){ + /* If a malloc fails, just leak the file descriptor */ + }else{ + pOpen->aPending = aNew; + pOpen->aPending[pOpen->nPending] = pFile->h; + pOpen->nPending++; + pFile->h = -1; + } } - }else{ - /* There are no outstanding locks so we can close the file immediately */ - close(pFile->h); + releaseLockInfo(pFile->pLock); + releaseOpenCnt(pFile->pOpen); + closeUnixFile(id); + leaveMutex(); } - releaseLockInfo(pFile->pLock); - releaseOpenCnt(pFile->pOpen); - - leaveMutex(); - OSTRACE2("CLOSE %-3d\n", pFile->h); - OpenCounter(-1); - memset(pFile, 0, sizeof(unixFile)); return SQLITE_OK; } @@ -20392,7 +22810,7 @@ static int _AFPFSSetLock( ** non-zero. If the file is unlocked or holds only SHARED locks, then ** return zero. */ -static int afpUnixCheckReservedLock(sqlite3_file *id){ +static int afpCheckReservedLock(sqlite3_file *id, int *pResOut){ int r = 0; unixFile *pFile = (unixFile*)id; @@ -20420,16 +22838,16 @@ static int afpUnixCheckReservedLock(sqlite3_file *id){ } OSTRACE3("TEST WR-LOCK %d %d\n", pFile->h, r); - return r; + *pResOut = r; + return SQLITE_OK; } /* AFP-style locking following the behavior of unixLock, see the unixLock ** function comments for details of lock management. */ -static int afpUnixLock(sqlite3_file *id, int locktype){ +static int afpLock(sqlite3_file *id, int locktype){ int rc = SQLITE_OK; unixFile *pFile = (unixFile*)id; afpLockingContext *context = (afpLockingContext *) pFile->lockingContext; - int gotPendingLock = 0; assert( pFile ); OSTRACE5("LOCK %d %s was %s pid=%d\n", pFile->h, @@ -20483,7 +22901,6 @@ static int afpUnixLock(sqlite3_file *id, int locktype){ */ if( locktype==SHARED_LOCK ){ int lk, failed; - int tries = 0; /* Now get the read-lock */ /* note that the quality of the randomness doesn't matter that much */ @@ -20518,7 +22935,7 @@ static int afpUnixLock(sqlite3_file *id, int locktype){ /* Acquire an EXCLUSIVE lock */ /* Remove the shared lock before trying the range. we'll need to - ** reestablish the shared lock if we can't get the afpUnixUnlock + ** reestablish the shared lock if we can't get the afpUnlock */ if (!_AFPFSSetLock(context->filePath, pFile->h, SHARED_FIRST + context->sharedLockByte, 1, 0)) { @@ -20559,8 +22976,7 @@ afp_end_lock: ** If the locking level of the file descriptor is already at or below ** the requested locking level, this routine is a no-op. */ -static int afpUnixUnlock(sqlite3_file *id, int locktype) { - struct flock lock; +static int afpUnlock(sqlite3_file *id, int locktype) { int rc = SQLITE_OK; unixFile *pFile = (unixFile*)id; afpLockingContext *context = (afpLockingContext *) pFile->lockingContext; @@ -20627,21 +23043,13 @@ static int afpUnixUnlock(sqlite3_file *id, int locktype) { /* ** Close a file & cleanup AFP specific locking context */ -static int afpUnixClose(sqlite3_file *id) { - unixFile *pFile = (unixFile*)id; - - if( !pFile ) return SQLITE_OK; - afpUnixUnlock(id, NO_LOCK); - sqlite3_free(pFile->lockingContext); - if( pFile->dirfd>=0 ) close(pFile->dirfd); - pFile->dirfd = -1; - enterMutex(); - close(pFile->h); - leaveMutex(); - OSTRACE2("CLOSE %-3d\n", pFile->h); - OpenCounter(-1); - memset(pFile, 0, sizeof(unixFile)); - return SQLITE_OK; +static int afpClose(sqlite3_file *id) { + if( id ){ + unixFile *pFile = (unixFile*)id; + afpUnlock(id, NO_LOCK); + sqlite3_free(pFile->lockingContext); + } + return closeUnixFile(id); } @@ -20652,24 +23060,25 @@ static int afpUnixClose(sqlite3_file *id) { */ typedef void flockLockingContext; -static int flockUnixCheckReservedLock(sqlite3_file *id){ +static int flockCheckReservedLock(sqlite3_file *id, int *pResOut){ + int r = 1; unixFile *pFile = (unixFile*)id; - if (pFile->locktype == RESERVED_LOCK) { - return 1; /* already have a reserved lock */ - } else { + if (pFile->locktype != RESERVED_LOCK) { /* attempt to get the lock */ int rc = flock(pFile->h, LOCK_EX | LOCK_NB); if (!rc) { /* got the lock, unlock it */ flock(pFile->h, LOCK_UN); - return 0; /* no one has it reserved */ + r = 0; /* no one has it reserved */ } - return 1; /* someone else might have it reserved */ } + + *pResOut = r; + return SQLITE_OK; } -static int flockUnixLock(sqlite3_file *id, int locktype) { +static int flockLock(sqlite3_file *id, int locktype) { unixFile *pFile = (unixFile*)id; /* if we already have a lock, it is exclusive. @@ -20691,7 +23100,7 @@ static int flockUnixLock(sqlite3_file *id, int locktype) { } } -static int flockUnixUnlock(sqlite3_file *id, int locktype) { +static int flockUnlock(sqlite3_file *id, int locktype) { unixFile *pFile = (unixFile*)id; assert( locktype<=SHARED_LOCK ); @@ -20720,80 +23129,55 @@ static int flockUnixUnlock(sqlite3_file *id, int locktype) { /* ** Close a file. */ -static int flockUnixClose(sqlite3_file *id) { - unixFile *pFile = (unixFile*)id; - - if( !pFile ) return SQLITE_OK; - flockUnixUnlock(id, NO_LOCK); - - if( pFile->dirfd>=0 ) close(pFile->dirfd); - pFile->dirfd = -1; - - enterMutex(); - close(pFile->h); - leaveMutex(); - OSTRACE2("CLOSE %-3d\n", pFile->h); - OpenCounter(-1); - memset(pFile, 0, sizeof(unixFile)); - return SQLITE_OK; +static int flockClose(sqlite3_file *id) { + if( id ){ + flockUnlock(id, NO_LOCK); + } + return closeUnixFile(id); } #pragma mark Old-School .lock file based locking -/* -** The dotlockLockingContext structure contains all dotlock (.lock) lock -** specific state -*/ -typedef struct dotlockLockingContext dotlockLockingContext; -struct dotlockLockingContext { - char *lockPath; -}; - - -static int dotlockUnixCheckReservedLock(sqlite3_file *id) { +static int dotlockCheckReservedLock(sqlite3_file *id, int *pResOut) { + int r = 1; unixFile *pFile = (unixFile*)id; - dotlockLockingContext *context; + char *zLockFile = (char *)pFile->lockingContext; - context = (dotlockLockingContext*)pFile->lockingContext; - if (pFile->locktype == RESERVED_LOCK) { - return 1; /* already have a reserved lock */ - } else { + if (pFile->locktype != RESERVED_LOCK) { struct stat statBuf; - if (lstat(context->lockPath,&statBuf) == 0){ - /* file exists, someone else has the lock */ - return 1; - }else{ + if (lstat(zLockFile, &statBuf) != 0){ /* file does not exist, we could have it if we want it */ - return 0; + r = 0; } } + + *pResOut = r; + return SQLITE_OK; } -static int dotlockUnixLock(sqlite3_file *id, int locktype) { +static int dotlockLock(sqlite3_file *id, int locktype) { unixFile *pFile = (unixFile*)id; - dotlockLockingContext *context; int fd; + char *zLockFile = (char *)pFile->lockingContext; - context = (dotlockLockingContext*)pFile->lockingContext; - /* if we already have a lock, it is exclusive. ** Just adjust level and punt on outta here. */ if (pFile->locktype > NO_LOCK) { pFile->locktype = locktype; /* Always update the timestamp on the old file */ - utimes(context->lockPath,NULL); + utimes(zLockFile, NULL); return SQLITE_OK; } /* check to see if lock file already exists */ struct stat statBuf; - if (lstat(context->lockPath,&statBuf) == 0){ + if (lstat(zLockFile,&statBuf) == 0){ return SQLITE_BUSY; /* it does, busy */ } /* grab an exclusive lock */ - fd = open(context->lockPath,O_RDONLY|O_CREAT|O_EXCL,0600); + fd = open(zLockFile,O_RDONLY|O_CREAT|O_EXCL,0600); if( fd<0 ){ /* failed to open/create the file, someone else may have stolen the lock */ return SQLITE_BUSY; @@ -20805,12 +23189,10 @@ static int dotlockUnixLock(sqlite3_file *id, int locktype) { return SQLITE_OK; } -static int dotlockUnixUnlock(sqlite3_file *id, int locktype) { +static int dotlockUnlock(sqlite3_file *id, int locktype) { unixFile *pFile = (unixFile*)id; - dotlockLockingContext *context; + char *zLockFile = (char *)pFile->lockingContext; - context = (dotlockLockingContext*)pFile->lockingContext; - assert( locktype<=SHARED_LOCK ); /* no-op if possible */ @@ -20825,7 +23207,7 @@ static int dotlockUnixUnlock(sqlite3_file *id, int locktype) { } /* no, really, unlock. */ - unlink(context->lockPath); + unlink(zLockFile); pFile->locktype = NO_LOCK; return SQLITE_OK; } @@ -20833,63 +23215,43 @@ static int dotlockUnixUnlock(sqlite3_file *id, int locktype) { /* ** Close a file. */ -static int dotlockUnixClose(sqlite3_file *id) { - unixFile *pFile = (unixFile*)id; - - if( !pFile ) return SQLITE_OK; - dotlockUnixUnlock(id, NO_LOCK); - sqlite3_free(pFile->lockingContext); - if( pFile->dirfd>=0 ) close(pFile->dirfd); - pFile->dirfd = -1; - enterMutex(); - close(pFile->h); - leaveMutex(); - OSTRACE2("CLOSE %-3d\n", pFile->h); - OpenCounter(-1); - memset(pFile, 0, sizeof(unixFile)); - return SQLITE_OK; +static int dotlockClose(sqlite3_file *id) { + if( id ){ + unixFile *pFile = (unixFile*)id; + dotlockUnlock(id, NO_LOCK); + sqlite3_free(pFile->lockingContext); + } + return closeUnixFile(id); } -#pragma mark No locking +#endif /* SQLITE_ENABLE_LOCKING_STYLE */ /* ** The nolockLockingContext is void */ typedef void nolockLockingContext; -static int nolockUnixCheckReservedLock(sqlite3_file *id) { - return 0; +static int nolockCheckReservedLock(sqlite3_file *id, int *pResOut) { + *pResOut = 0; + return SQLITE_OK; } -static int nolockUnixLock(sqlite3_file *id, int locktype) { +static int nolockLock(sqlite3_file *id, int locktype) { return SQLITE_OK; } -static int nolockUnixUnlock(sqlite3_file *id, int locktype) { +static int nolockUnlock(sqlite3_file *id, int locktype) { return SQLITE_OK; } /* ** Close a file. */ -static int nolockUnixClose(sqlite3_file *id) { - unixFile *pFile = (unixFile*)id; - - if( !pFile ) return SQLITE_OK; - if( pFile->dirfd>=0 ) close(pFile->dirfd); - pFile->dirfd = -1; - enterMutex(); - close(pFile->h); - leaveMutex(); - OSTRACE2("CLOSE %-3d\n", pFile->h); - OpenCounter(-1); - memset(pFile, 0, sizeof(unixFile)); - return SQLITE_OK; +static int nolockClose(sqlite3_file *id) { + return closeUnixFile(id); } -#endif /* SQLITE_ENABLE_LOCKING_STYLE */ - /* ** Information and control of an open file handle. @@ -20926,245 +23288,137 @@ static int unixDeviceCharacteristics(sqlite3_file *id){ } /* -** This vector defines all the methods that can operate on an sqlite3_file -** for unix. -*/ -static const sqlite3_io_methods sqlite3UnixIoMethod = { - 1, /* iVersion */ - unixClose, - unixRead, - unixWrite, - unixTruncate, - unixSync, - unixFileSize, - unixLock, - unixUnlock, - unixCheckReservedLock, - unixFileControl, - unixSectorSize, - unixDeviceCharacteristics -}; - -#ifdef SQLITE_ENABLE_LOCKING_STYLE -/* -** This vector defines all the methods that can operate on an sqlite3_file -** for unix with AFP style file locking. -*/ -static const sqlite3_io_methods sqlite3AFPLockingUnixIoMethod = { - 1, /* iVersion */ - afpUnixClose, - unixRead, - unixWrite, - unixTruncate, - unixSync, - unixFileSize, - afpUnixLock, - afpUnixUnlock, - afpUnixCheckReservedLock, - unixFileControl, - unixSectorSize, - unixDeviceCharacteristics -}; - -/* -** This vector defines all the methods that can operate on an sqlite3_file -** for unix with flock() style file locking. -*/ -static const sqlite3_io_methods sqlite3FlockLockingUnixIoMethod = { - 1, /* iVersion */ - flockUnixClose, - unixRead, - unixWrite, - unixTruncate, - unixSync, - unixFileSize, - flockUnixLock, - flockUnixUnlock, - flockUnixCheckReservedLock, - unixFileControl, - unixSectorSize, - unixDeviceCharacteristics -}; - -/* -** This vector defines all the methods that can operate on an sqlite3_file -** for unix with dotlock style file locking. -*/ -static const sqlite3_io_methods sqlite3DotlockLockingUnixIoMethod = { - 1, /* iVersion */ - dotlockUnixClose, - unixRead, - unixWrite, - unixTruncate, - unixSync, - unixFileSize, - dotlockUnixLock, - dotlockUnixUnlock, - dotlockUnixCheckReservedLock, - unixFileControl, - unixSectorSize, - unixDeviceCharacteristics -}; - -/* -** This vector defines all the methods that can operate on an sqlite3_file -** for unix with nolock style file locking. -*/ -static const sqlite3_io_methods sqlite3NolockLockingUnixIoMethod = { - 1, /* iVersion */ - nolockUnixClose, - unixRead, - unixWrite, - unixTruncate, - unixSync, - unixFileSize, - nolockUnixLock, - nolockUnixUnlock, - nolockUnixCheckReservedLock, - unixFileControl, - unixSectorSize, - unixDeviceCharacteristics -}; - -#endif /* SQLITE_ENABLE_LOCKING_STYLE */ - -/* -** Allocate memory for a new unixFile and initialize that unixFile. -** Write a pointer to the new unixFile into *pId. -** If we run out of memory, close the file and return an error. -*/ -#ifdef SQLITE_ENABLE_LOCKING_STYLE -/* +** Initialize the contents of the unixFile structure pointed to by pId. +** ** When locking extensions are enabled, the filepath and locking style ** are needed to determine the unixFile pMethod to use for locking operations. ** The locking-style specific lockingContext data structure is created ** and assigned here also. */ static int fillInUnixFile( + sqlite3_vfs *pVfs, /* Pointer to vfs object */ int h, /* Open file descriptor of file being opened */ int dirfd, /* Directory file descriptor */ sqlite3_file *pId, /* Write to the unixFile structure here */ - const char *zFilename /* Name of the file being opened */ + const char *zFilename, /* Name of the file being opened */ + int noLock /* Omit locking if true */ ){ - sqlite3LockingStyle lockingStyle; + int eLockingStyle; unixFile *pNew = (unixFile *)pId; - int rc; + int rc = SQLITE_OK; -#ifdef FD_CLOEXEC - fcntl(h, F_SETFD, fcntl(h, F_GETFD, 0) | FD_CLOEXEC); + /* Macro to define the static contents of an sqlite3_io_methods + ** structure for a unix backend file. Different locking methods + ** require different functions for the xClose, xLock, xUnlock and + ** xCheckReservedLock methods. + */ + #define IOMETHODS(xClose, xLock, xUnlock, xCheckReservedLock) { \ + 1, /* iVersion */ \ + xClose, /* xClose */ \ + unixRead, /* xRead */ \ + unixWrite, /* xWrite */ \ + unixTruncate, /* xTruncate */ \ + unixSync, /* xSync */ \ + unixFileSize, /* xFileSize */ \ + xLock, /* xLock */ \ + xUnlock, /* xUnlock */ \ + xCheckReservedLock, /* xCheckReservedLock */ \ + unixFileControl, /* xFileControl */ \ + unixSectorSize, /* xSectorSize */ \ + unixDeviceCharacteristics /* xDeviceCapabilities */ \ + } + static sqlite3_io_methods aIoMethod[] = { + IOMETHODS(unixClose, unixLock, unixUnlock, unixCheckReservedLock) + ,IOMETHODS(nolockClose, nolockLock, nolockUnlock, nolockCheckReservedLock) +#ifdef SQLITE_ENABLE_LOCKING_STYLE + ,IOMETHODS(dotlockClose, dotlockLock, dotlockUnlock,dotlockCheckReservedLock) + ,IOMETHODS(flockClose, flockLock, flockUnlock, flockCheckReservedLock) + ,IOMETHODS(afpClose, afpLock, afpUnlock, afpCheckReservedLock) #endif + }; + /* The order of the IOMETHODS macros above is important. It must be the + ** same order as the LOCKING_STYLE numbers + */ + assert(LOCKING_STYLE_POSIX==1); + assert(LOCKING_STYLE_NONE==2); + assert(LOCKING_STYLE_DOTFILE==3); + assert(LOCKING_STYLE_FLOCK==4); + assert(LOCKING_STYLE_AFP==5); - lockingStyle = sqlite3DetectLockingStyle(zFilename, h); - if ( lockingStyle==posixLockingStyle ){ - enterMutex(); - rc = findLockInfo(h, &pNew->pLock, &pNew->pOpen); - leaveMutex(); - if( rc ){ - if( dirfd>=0 ) close(dirfd); - close(h); - return rc; - } - } else { - /* pLock and pOpen are only used for posix advisory locking */ - pNew->pLock = NULL; - pNew->pOpen = NULL; - } + assert( pNew->pLock==NULL ); + assert( pNew->pOpen==NULL ); OSTRACE3("OPEN %-3d %s\n", h, zFilename); - pNew->dirfd = -1; pNew->h = h; pNew->dirfd = dirfd; SET_THREADID(pNew); - - switch(lockingStyle) { - case afpLockingStyle: { - /* afp locking uses the file path so it needs to be included in - ** the afpLockingContext */ - afpLockingContext *context; - pNew->pMethod = &sqlite3AFPLockingUnixIoMethod; - pNew->lockingContext = context = sqlite3_malloc( sizeof(*context) ); - if( context==0 ){ - close(h); - if( dirfd>=0 ) close(dirfd); - return SQLITE_NOMEM; - } - /* NB: zFilename exists and remains valid until the file is closed - ** according to requirement F11141. So we do not need to make a - ** copy of the filename. */ - context->filePath = zFilename; - srandomdev(); + if( noLock ){ + eLockingStyle = LOCKING_STYLE_NONE; + }else{ + eLockingStyle = detectLockingStyle(pVfs, zFilename, h); + } + + switch( eLockingStyle ){ + + case LOCKING_STYLE_POSIX: { + enterMutex(); + rc = findLockInfo(h, &pNew->pLock, &pNew->pOpen); + leaveMutex(); break; } - case flockLockingStyle: - /* flock locking doesn't need additional lockingContext information */ - pNew->pMethod = &sqlite3FlockLockingUnixIoMethod; + +#ifdef SQLITE_ENABLE_LOCKING_STYLE + case LOCKING_STYLE_AFP: { + /* AFP locking uses the file path so it needs to be included in + ** the afpLockingContext. + */ + afpLockingContext *pCtx; + pNew->lockingContext = pCtx = sqlite3_malloc( sizeof(*pCtx) ); + if( pCtx==0 ){ + rc = SQLITE_NOMEM; + }else{ + /* NB: zFilename exists and remains valid until the file is closed + ** according to requirement F11141. So we do not need to make a + ** copy of the filename. */ + pCtx->filePath = zFilename; + srandomdev(); + } break; - case dotlockLockingStyle: { - /* dotlock locking uses the file path so it needs to be included in - ** the dotlockLockingContext */ - dotlockLockingContext *context; + } + + case LOCKING_STYLE_DOTFILE: { + /* Dotfile locking uses the file path so it needs to be included in + ** the dotlockLockingContext + */ + char *zLockFile; int nFilename; - nFilename = strlen(zFilename); - pNew->pMethod = &sqlite3DotlockLockingUnixIoMethod; - pNew->lockingContext = context = - sqlite3_malloc( sizeof(*context) + nFilename + 6 ); - if( context==0 ){ - close(h); - if( dirfd>=0 ) close(dirfd); - return SQLITE_NOMEM; + nFilename = strlen(zFilename) + 6; + zLockFile = (char *)sqlite3_malloc(nFilename); + if( zLockFile==0 ){ + rc = SQLITE_NOMEM; + }else{ + sqlite3_snprintf(nFilename, zLockFile, "%s.lock", zFilename); } - context->lockPath = (char*)&context[1]; - sqlite3_snprintf(nFilename, context->lockPath, - "%s.lock", zFilename); + pNew->lockingContext = zLockFile; break; } - case posixLockingStyle: - /* posix locking doesn't need additional lockingContext information */ - pNew->pMethod = &sqlite3UnixIoMethod; - break; - case noLockingStyle: - case unsupportedLockingStyle: - default: - pNew->pMethod = &sqlite3NolockLockingUnixIoMethod; - } - OpenCounter(+1); - return SQLITE_OK; -} -#else /* SQLITE_ENABLE_LOCKING_STYLE */ -static int fillInUnixFile( - int h, /* Open file descriptor on file being opened */ - int dirfd, - sqlite3_file *pId, /* Write to the unixFile structure here */ - const char *zFilename /* Name of the file being opened */ -){ - unixFile *pNew = (unixFile *)pId; - int rc; -#ifdef FD_CLOEXEC - fcntl(h, F_SETFD, fcntl(h, F_GETFD, 0) | FD_CLOEXEC); + case LOCKING_STYLE_FLOCK: + case LOCKING_STYLE_NONE: + break; #endif + } - enterMutex(); - rc = findLockInfo(h, &pNew->pLock, &pNew->pOpen); - leaveMutex(); - if( rc ){ + if( rc!=SQLITE_OK ){ if( dirfd>=0 ) close(dirfd); close(h); - return rc; + }else{ + pNew->pMethod = &aIoMethod[eLockingStyle-1]; + OpenCounter(+1); } - - OSTRACE3("OPEN %-3d %s\n", h, zFilename); - pNew->dirfd = -1; - pNew->h = h; - pNew->dirfd = dirfd; - SET_THREADID(pNew); - - pNew->pMethod = &sqlite3UnixIoMethod; - OpenCounter(+1); - return SQLITE_OK; + return rc; } -#endif /* SQLITE_ENABLE_LOCKING_STYLE */ /* ** Open a file descriptor to the directory containing file zFilename. @@ -21198,6 +23452,63 @@ static int openDirectory(const char *zFilename, int *pFd){ } /* +** Create a temporary file name in zBuf. zBuf must be allocated +** by the calling process and must be big enough to hold at least +** pVfs->mxPathname bytes. +*/ +static int getTempname(int nBuf, char *zBuf){ + static const char *azDirs[] = { + 0, + "/var/tmp", + "/usr/tmp", + "/tmp", + ".", + }; + static const unsigned char zChars[] = + "abcdefghijklmnopqrstuvwxyz" + "ABCDEFGHIJKLMNOPQRSTUVWXYZ" + "0123456789"; + int i, j; + struct stat buf; + const char *zDir = "."; + + /* It's odd to simulate an io-error here, but really this is just + ** using the io-error infrastructure to test that SQLite handles this + ** function failing. + */ + SimulateIOError( return SQLITE_IOERR ); + + azDirs[0] = sqlite3_temp_directory; + for(i=0; i<sizeof(azDirs)/sizeof(azDirs[0]); i++){ + if( azDirs[i]==0 ) continue; + if( stat(azDirs[i], &buf) ) continue; + if( !S_ISDIR(buf.st_mode) ) continue; + if( access(azDirs[i], 07) ) continue; + zDir = azDirs[i]; + break; + } + + /* Check that the output buffer is large enough for the temporary file + ** name. If it is not, return SQLITE_ERROR. + */ + if( (strlen(zDir) + strlen(SQLITE_TEMP_FILE_PREFIX) + 17) >= nBuf ){ + return SQLITE_ERROR; + } + + do{ + sqlite3_snprintf(nBuf-17, zBuf, "%s/"SQLITE_TEMP_FILE_PREFIX, zDir); + j = strlen(zBuf); + sqlite3_randomness(15, &zBuf[j]); + for(i=0; i<15; i++, j++){ + zBuf[j] = (char)zChars[ ((unsigned char)zBuf[j])%(sizeof(zChars)-1) ]; + } + zBuf[j] = 0; + }while( access(zBuf,0)==0 ); + return SQLITE_OK; +} + + +/* ** Open the file zPath. ** ** Previously, the SQLite OS layer used three functions in place of this @@ -21230,6 +23541,7 @@ static int unixOpen( int dirfd = -1; /* Directory file descriptor */ int oflags = 0; /* Flags to pass to open() */ int eType = flags&0xFFFFFF00; /* Type of file to open */ + int noLock; /* True to omit locking primitives */ int isExclusive = (flags & SQLITE_OPEN_EXCLUSIVE); int isDelete = (flags & SQLITE_OPEN_DELETEONCLOSE); @@ -21245,6 +23557,12 @@ static int unixOpen( (eType==SQLITE_OPEN_MASTER_JOURNAL || eType==SQLITE_OPEN_MAIN_JOURNAL) ); + /* If argument zPath is a NULL pointer, this function is required to open + ** a temporary file. Use this buffer to store the file name in. + */ + char zTmpname[MAX_PATHNAME+1]; + const char *zName = zPath; + /* Check the following statements are true: ** ** (a) Exactly one of the READWRITE and READONLY flags must be set, and @@ -21257,7 +23575,6 @@ static int unixOpen( assert(isExclusive==0 || isCreate); assert(isDelete==0 || isCreate); - /* The main DB, main journal, and master journal are never automatically ** deleted */ @@ -21272,14 +23589,25 @@ static int unixOpen( || eType==SQLITE_OPEN_TRANSIENT_DB ); + memset(pFile, 0, sizeof(unixFile)); + + if( !zName ){ + int rc; + assert(isDelete && !isOpenDirectory); + rc = getTempname(MAX_PATHNAME+1, zTmpname); + if( rc!=SQLITE_OK ){ + return rc; + } + zName = zTmpname; + } + if( isReadonly ) oflags |= O_RDONLY; if( isReadWrite ) oflags |= O_RDWR; if( isCreate ) oflags |= O_CREAT; if( isExclusive ) oflags |= (O_EXCL|O_NOFOLLOW); oflags |= (O_LARGEFILE|O_BINARY); - memset(pFile, 0, sizeof(unixFile)); - fd = open(zPath, oflags, isDelete?0600:SQLITE_DEFAULT_FILE_PERMISSIONS); + fd = open(zName, oflags, isDelete?0600:SQLITE_DEFAULT_FILE_PERMISSIONS); if( fd<0 && errno!=EISDIR && isReadWrite && !isExclusive ){ /* Failed to open the file for read/write access. Try read-only. */ flags &= ~(SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE); @@ -21290,7 +23618,7 @@ static int unixOpen( return SQLITE_CANTOPEN; } if( isDelete ){ - unlink(zPath); + unlink(zName); } if( pOutFlags ){ *pOutFlags = flags; @@ -21304,7 +23632,13 @@ static int unixOpen( return rc; } } - return fillInUnixFile(fd, dirfd, pFile, zPath); + +#ifdef FD_CLOEXEC + fcntl(fd, F_SETFD, fcntl(fd, F_GETFD, 0) | FD_CLOEXEC); +#endif + + noLock = eType!=SQLITE_OPEN_MAIN_DB; + return fillInUnixFile(pVfs, fd, dirfd, pFile, zPath, noLock); } /* @@ -21338,8 +23672,14 @@ static int unixDelete(sqlite3_vfs *pVfs, const char *zPath, int dirSync){ ** ** Otherwise return 0. */ -static int unixAccess(sqlite3_vfs *pVfs, const char *zPath, int flags){ +static int unixAccess( + sqlite3_vfs *pVfs, + const char *zPath, + int flags, + int *pResOut +){ int amode = 0; + SimulateIOError( return SQLITE_IOERR_ACCESS; ); switch( flags ){ case SQLITE_ACCESS_EXISTS: amode = F_OK; @@ -21354,63 +23694,7 @@ static int unixAccess(sqlite3_vfs *pVfs, const char *zPath, int flags){ default: assert(!"Invalid flags argument"); } - return (access(zPath, amode)==0); -} - -/* -** Create a temporary file name in zBuf. zBuf must be allocated -** by the calling process and must be big enough to hold at least -** pVfs->mxPathname bytes. -*/ -static int unixGetTempname(sqlite3_vfs *pVfs, int nBuf, char *zBuf){ - static const char *azDirs[] = { - 0, - "/var/tmp", - "/usr/tmp", - "/tmp", - ".", - }; - static const unsigned char zChars[] = - "abcdefghijklmnopqrstuvwxyz" - "ABCDEFGHIJKLMNOPQRSTUVWXYZ" - "0123456789"; - int i, j; - struct stat buf; - const char *zDir = "."; - - /* It's odd to simulate an io-error here, but really this is just - ** using the io-error infrastructure to test that SQLite handles this - ** function failing. - */ - SimulateIOError( return SQLITE_ERROR ); - - azDirs[0] = sqlite3_temp_directory; - for(i=0; i<sizeof(azDirs)/sizeof(azDirs[0]); i++){ - if( azDirs[i]==0 ) continue; - if( stat(azDirs[i], &buf) ) continue; - if( !S_ISDIR(buf.st_mode) ) continue; - if( access(azDirs[i], 07) ) continue; - zDir = azDirs[i]; - break; - } - - /* Check that the output buffer is large enough for the temporary file - ** name. If it is not, return SQLITE_ERROR. - */ - if( (strlen(zDir) + strlen(SQLITE_TEMP_FILE_PREFIX) + 17) >= nBuf ){ - return SQLITE_ERROR; - } - - do{ - assert( pVfs->mxPathname==MAX_PATHNAME ); - sqlite3_snprintf(nBuf-17, zBuf, "%s/"SQLITE_TEMP_FILE_PREFIX, zDir); - j = strlen(zBuf); - sqlite3_randomness(15, &zBuf[j]); - for(i=0; i<15; i++, j++){ - zBuf[j] = (char)zChars[ ((unsigned char)zBuf[j])%(sizeof(zChars)-1) ]; - } - zBuf[j] = 0; - }while( access(zBuf,0)==0 ); + *pResOut = (access(zPath, amode)==0); return SQLITE_OK; } @@ -21609,39 +23893,68 @@ static int unixCurrentTime(sqlite3_vfs *pVfs, double *prNow){ return 0; } +static int unixGetLastError(sqlite3_vfs *pVfs, int nBuf, char *zBuf){ + return 0; +} + /* -** Return a pointer to the sqlite3DefaultVfs structure. We use -** a function rather than give the structure global scope because -** some compilers (MSVC) do not allow forward declarations of -** initialized structures. +** Initialize the operating system interface. */ -SQLITE_PRIVATE sqlite3_vfs *sqlite3OsDefaultVfs(void){ - static sqlite3_vfs unixVfs = { - 1, /* iVersion */ - sizeof(unixFile), /* szOsFile */ - MAX_PATHNAME, /* mxPathname */ - 0, /* pNext */ - "unix", /* zName */ - 0, /* pAppData */ - - unixOpen, /* xOpen */ - unixDelete, /* xDelete */ - unixAccess, /* xAccess */ - unixGetTempname, /* xGetTempName */ - unixFullPathname, /* xFullPathname */ - unixDlOpen, /* xDlOpen */ - unixDlError, /* xDlError */ - unixDlSym, /* xDlSym */ - unixDlClose, /* xDlClose */ - unixRandomness, /* xRandomness */ - unixSleep, /* xSleep */ - unixCurrentTime /* xCurrentTime */ +SQLITE_API int sqlite3_os_init(void){ + /* Macro to define the static contents of an sqlite3_vfs structure for + ** the unix backend. The two parameters are the values to use for + ** the sqlite3_vfs.zName and sqlite3_vfs.pAppData fields, respectively. + ** + */ + #define UNIXVFS(zVfsName, pVfsAppData) { \ + 1, /* iVersion */ \ + sizeof(unixFile), /* szOsFile */ \ + MAX_PATHNAME, /* mxPathname */ \ + 0, /* pNext */ \ + zVfsName, /* zName */ \ + (void *)pVfsAppData, /* pAppData */ \ + unixOpen, /* xOpen */ \ + unixDelete, /* xDelete */ \ + unixAccess, /* xAccess */ \ + unixFullPathname, /* xFullPathname */ \ + unixDlOpen, /* xDlOpen */ \ + unixDlError, /* xDlError */ \ + unixDlSym, /* xDlSym */ \ + unixDlClose, /* xDlClose */ \ + unixRandomness, /* xRandomness */ \ + unixSleep, /* xSleep */ \ + unixCurrentTime, /* xCurrentTime */ \ + unixGetLastError /* xGetLastError */ \ + } + + static sqlite3_vfs unixVfs = UNIXVFS("unix", 0); +#ifdef SQLITE_ENABLE_LOCKING_STYLE +#if 0 + int i; + static sqlite3_vfs aVfs[] = { + UNIXVFS("unix-posix", LOCKING_STYLE_POSIX), + UNIXVFS("unix-afp", LOCKING_STYLE_AFP), + UNIXVFS("unix-flock", LOCKING_STYLE_FLOCK), + UNIXVFS("unix-dotfile", LOCKING_STYLE_DOTFILE), + UNIXVFS("unix-none", LOCKING_STYLE_NONE) }; - - return &unixVfs; + for(i=0; i<(sizeof(aVfs)/sizeof(sqlite3_vfs)); i++){ + sqlite3_vfs_register(&aVfs[i], 0); + } +#endif +#endif + sqlite3_vfs_register(&unixVfs, 1); + return SQLITE_OK; +} + +/* +** Shutdown the operating system interface. This is a no-op for unix. +*/ +SQLITE_API int sqlite3_os_end(void){ + return SQLITE_OK; } -#endif /* OS_UNIX */ +#endif /* SQLITE_OS_UNIX */ /************** End of os_unix.c *********************************************/ /************** Begin file os_win.c ******************************************/ @@ -21658,8 +23971,10 @@ SQLITE_PRIVATE sqlite3_vfs *sqlite3OsDefaultVfs(void){ ****************************************************************************** ** ** This file contains code that is specific to windows. +** +** $Id$ */ -#if OS_WIN /* This file is used for windows only */ +#if SQLITE_OS_WIN /* This file is used for windows only */ /* @@ -21724,7 +24039,11 @@ SQLITE_PRIVATE sqlite3_vfs *sqlite3OsDefaultVfs(void){ ** ** This file should be #included by the os_*.c files only. It is not a ** general purpose header file. +** +** $Id$ */ +#ifndef _OS_COMMON_H_ +#define _OS_COMMON_H_ /* ** At least two bugs have slipped in because we changed the MEMORY_DEBUG @@ -21770,22 +24089,113 @@ SQLITE_PRIVATE int sqlite3OSTrace = 0; ** on i486 hardware. */ #ifdef SQLITE_PERFORMANCE_TRACE -__inline__ unsigned long long int hwtime(void){ - unsigned long long int x; - __asm__("rdtsc\n\t" - "mov %%edx, %%ecx\n\t" - :"=A" (x)); - return x; -} -static unsigned long long int g_start; -static unsigned int elapse; -#define TIMER_START g_start=hwtime() -#define TIMER_END elapse=hwtime()-g_start -#define TIMER_ELAPSED elapse + +/* +** hwtime.h contains inline assembler code for implementing +** high-performance timing routines. +*/ +/************** Include hwtime.h in the middle of os_common.h ****************/ +/************** Begin file hwtime.h ******************************************/ +/* +** 2008 May 27 +** +** The author disclaims copyright to this source code. In place of +** a legal notice, here is a blessing: +** +** May you do good and not evil. +** May you find forgiveness for yourself and forgive others. +** May you share freely, never taking more than you give. +** +****************************************************************************** +** +** This file contains inline asm code for retrieving "high-performance" +** counters for x86 class CPUs. +** +** $Id$ +*/ +#ifndef _HWTIME_H_ +#define _HWTIME_H_ + +/* +** The following routine only works on pentium-class (or newer) processors. +** It uses the RDTSC opcode to read the cycle count value out of the +** processor and returns that value. This can be used for high-res +** profiling. +*/ +#if (defined(__GNUC__) || defined(_MSC_VER)) && \ + (defined(i386) || defined(__i386__) || defined(_M_IX86)) + + #if defined(__GNUC__) + + __inline__ sqlite_uint64 sqlite3Hwtime(void){ + unsigned int lo, hi; + __asm__ __volatile__ ("rdtsc" : "=a" (lo), "=d" (hi)); + return (sqlite_uint64)hi << 32 | lo; + } + + #elif defined(_MSC_VER) + + __declspec(naked) __inline sqlite_uint64 __cdecl sqlite3Hwtime(void){ + __asm { + rdtsc + ret ; return value at EDX:EAX + } + } + + #endif + +#elif (defined(__GNUC__) && defined(__x86_64__)) + + __inline__ sqlite_uint64 sqlite3Hwtime(void){ + unsigned long val; + __asm__ __volatile__ ("rdtsc" : "=A" (val)); + return val; + } + +#elif (defined(__GNUC__) && defined(__ppc__)) + + __inline__ sqlite_uint64 sqlite3Hwtime(void){ + unsigned long long retval; + unsigned long junk; + __asm__ __volatile__ ("\n\ + 1: mftbu %1\n\ + mftb %L0\n\ + mftbu %0\n\ + cmpw %0,%1\n\ + bne 1b" + : "=r" (retval), "=r" (junk)); + return retval; + } + +#else + + #error Need implementation of sqlite3Hwtime() for your platform. + + /* + ** To compile without implementing sqlite3Hwtime() for your platform, + ** you can remove the above #error and use the following + ** stub function. You will lose timing support for many + ** of the debugging and testing utilities, but it should at + ** least compile and run. + */ +SQLITE_PRIVATE sqlite_uint64 sqlite3Hwtime(void){ return ((sqlite_uint64)0); } + +#endif + +#endif /* !defined(_HWTIME_H_) */ + +/************** End of hwtime.h **********************************************/ +/************** Continuing where we left off in os_common.h ******************/ + +static sqlite_uint64 g_start; +static sqlite_uint64 g_elapsed; +#define TIMER_START g_start=sqlite3Hwtime() +#define TIMER_END g_elapsed=sqlite3Hwtime()-g_start +#define TIMER_ELAPSED g_elapsed #else #define TIMER_START #define TIMER_END -#define TIMER_ELAPSED 0 +#define TIMER_ELAPSED ((sqlite_uint64)0) #endif /* @@ -21838,6 +24248,8 @@ SQLITE_API int sqlite3_open_file_count = 0; #define OpenCounter(X) #endif +#endif /* !defined(_OS_COMMON_H_) */ + /************** End of os_common.h *******************************************/ /************** Continuing where we left off in os_win.c *********************/ @@ -21845,18 +24257,15 @@ SQLITE_API int sqlite3_open_file_count = 0; ** Determine if we are dealing with WindowsCE - which has a much ** reduced API. */ -#if defined(_WIN32_WCE) -# define OS_WINCE 1 +#if defined(SQLITE_OS_WINCE) # define AreFileApisANSI() 1 -#else -# define OS_WINCE 0 #endif /* ** WinCE lacks native support for file locking so we have to fake it ** with some code of our own. */ -#if OS_WINCE +#if SQLITE_OS_WINCE typedef struct winceLock { int nReaders; /* Number of reader locks obtained */ BOOL bPending; /* Indicates a pending lock has been obtained */ @@ -21875,7 +24284,7 @@ struct winFile { HANDLE h; /* Handle for accessing the file */ unsigned char locktype; /* Type of lock currently held on this file */ short sharedLockByte; /* Randomly chosen byte used as a shared lock */ -#if OS_WINCE +#if SQLITE_OS_WINCE WCHAR *zDeleteOnClose; /* Name of file to delete when closing */ HANDLE hMutex; /* Mutex used to control access to shared lock */ HANDLE hShared; /* Shared memory segment used for locking */ @@ -21914,7 +24323,7 @@ static int sqlite3_os_type = 0; ** WinNT/2K/XP so that we will know whether or not we can safely call ** the LockFileEx() API. */ -#if OS_WINCE +#if SQLITE_OS_WINCE # define isNT() (1) #else static int isNT(void){ @@ -21926,7 +24335,7 @@ static int sqlite3_os_type = 0; } return sqlite3_os_type==2; } -#endif /* OS_WINCE */ +#endif /* SQLITE_OS_WINCE */ /* ** Convert a UTF-8 string to microsoft unicode (UTF-16?). @@ -22057,7 +24466,7 @@ static char *utf8ToMbcs(const char *zFilename){ return zFilenameMbcs; } -#if OS_WINCE +#if SQLITE_OS_WINCE /************************************************************************* ** This section contains code for WinCE only. */ @@ -22360,7 +24769,7 @@ static BOOL winceLockFileEx( /* ** End of the special code for wince *****************************************************************************/ -#endif /* OS_WINCE */ +#endif /* SQLITE_OS_WINCE */ /***************************************************************************** ** The next group of routines implement the I/O methods specified @@ -22385,7 +24794,7 @@ static int winClose(sqlite3_file *id){ do{ rc = CloseHandle(pFile->h); }while( rc==0 && cnt++ < MX_CLOSE_ATTEMPT && (Sleep(100), 1) ); -#if OS_WINCE +#if SQLITE_OS_WINCE #define WINCE_DELETION_ATTEMPTS 3 winceDestroyLock(pFile); if( pFile->zDeleteOnClose ){ @@ -22718,7 +25127,7 @@ static int winLock(sqlite3_file *id, int locktype){ ** file by this or any other process. If such a lock is held, return ** non-zero, otherwise zero. */ -static int winCheckReservedLock(sqlite3_file *id){ +static int winCheckReservedLock(sqlite3_file *id, int *pResOut){ int rc; winFile *pFile = (winFile*)id; assert( pFile!=0 ); @@ -22733,7 +25142,8 @@ static int winCheckReservedLock(sqlite3_file *id){ rc = !rc; OSTRACE3("TEST WR-LOCK %d %d (remote)\n", pFile->h, rc); } - return rc; + *pResOut = rc; + return SQLITE_OK; } /* @@ -22855,6 +25265,87 @@ static void *convertUtf8Filename(const char *zFilename){ } /* +** Create a temporary file name in zBuf. zBuf must be big enough to +** hold at pVfs->mxPathname characters. +*/ +static int getTempname(int nBuf, char *zBuf){ + static char zChars[] = + "abcdefghijklmnopqrstuvwxyz" + "ABCDEFGHIJKLMNOPQRSTUVWXYZ" + "0123456789"; + size_t i, j; + char zTempPath[MAX_PATH+1]; + if( sqlite3_temp_directory ){ + sqlite3_snprintf(MAX_PATH-30, zTempPath, "%s", sqlite3_temp_directory); + }else if( isNT() ){ + char *zMulti; + WCHAR zWidePath[MAX_PATH]; + GetTempPathW(MAX_PATH-30, zWidePath); + zMulti = unicodeToUtf8(zWidePath); + if( zMulti ){ + sqlite3_snprintf(MAX_PATH-30, zTempPath, "%s", zMulti); + free(zMulti); + }else{ + return SQLITE_NOMEM; + } + }else{ + char *zUtf8; + char zMbcsPath[MAX_PATH]; + GetTempPathA(MAX_PATH-30, zMbcsPath); + zUtf8 = mbcsToUtf8(zMbcsPath); + if( zUtf8 ){ + sqlite3_snprintf(MAX_PATH-30, zTempPath, "%s", zUtf8); + free(zUtf8); + }else{ + return SQLITE_NOMEM; + } + } + for(i=strlen(zTempPath); i>0 && zTempPath[i-1]=='\\'; i--){} + zTempPath[i] = 0; + sqlite3_snprintf(nBuf-30, zBuf, + "%s\\"SQLITE_TEMP_FILE_PREFIX, zTempPath); + j = strlen(zBuf); + sqlite3_randomness(20, &zBuf[j]); + for(i=0; i<20; i++, j++){ + zBuf[j] = (char)zChars[ ((unsigned char)zBuf[j])%(sizeof(zChars)-1) ]; + } + zBuf[j] = 0; + OSTRACE2("TEMP FILENAME: %s\n", zBuf); + return SQLITE_OK; +} + +/* +** The return value of getLastErrorMsg +** is zero if the error message fits in the buffer, or non-zero +** otherwise (if the message was truncated). +*/ +static int getLastErrorMsg(int nBuf, char *zBuf){ + DWORD error = GetLastError(); + +#if SQLITE_OS_WINCE + sqlite3_snprintf(nBuf, zBuf, "OsError 0x%x (%u)", error, error); +#else + /* FormatMessage returns 0 on failure. Otherwise it + ** returns the number of TCHARs written to the output + ** buffer, excluding the terminating null char. + */ + if (!FormatMessageA(FORMAT_MESSAGE_FROM_SYSTEM, + NULL, + error, + 0, + zBuf, + nBuf-1, + 0)) + { + sqlite3_snprintf(nBuf, zBuf, "OsError 0x%x (%u)", error, error); + } +#endif + + return 0; +} + + +/* ** Open a file. */ static int winOpen( @@ -22871,7 +25362,23 @@ static int winOpen( DWORD dwFlagsAndAttributes = 0; int isTemp; winFile *pFile = (winFile*)id; - void *zConverted = convertUtf8Filename(zName); + void *zConverted; /* Filename in OS encoding */ + const char *zUtf8Name = zName; /* Filename in UTF-8 encoding */ + char zTmpname[MAX_PATH+1]; /* Buffer used to create temp filename */ + + /* If the second argument to this function is NULL, generate a + ** temporary file name to use + */ + if( !zUtf8Name ){ + int rc = getTempname(MAX_PATH+1, zTmpname); + if( rc!=SQLITE_OK ){ + return rc; + } + zUtf8Name = zTmpname; + } + + /* Convert the filename to the system encoding. */ + zConverted = convertUtf8Filename(zUtf8Name); if( zConverted==0 ){ return SQLITE_NOMEM; } @@ -22892,7 +25399,7 @@ static int winOpen( dwShareMode = 0; } if( flags & SQLITE_OPEN_DELETEONCLOSE ){ -#if OS_WINCE +#if SQLITE_OS_WINCE dwFlagsAndAttributes = FILE_ATTRIBUTE_HIDDEN; #else dwFlagsAndAttributes = FILE_ATTRIBUTE_TEMPORARY @@ -22917,9 +25424,6 @@ static int winOpen( NULL ); }else{ -#if OS_WINCE - return SQLITE_NOMEM; -#else h = CreateFileA((char*)zConverted, dwDesiredAccess, dwShareMode, @@ -22928,7 +25432,6 @@ static int winOpen( dwFlagsAndAttributes, NULL ); -#endif } if( h==INVALID_HANDLE_VALUE ){ free(zConverted); @@ -22949,7 +25452,7 @@ static int winOpen( memset(pFile, 0, sizeof(*pFile)); pFile->pMethod = &winIoMethod; pFile->h = h; -#if OS_WINCE +#if SQLITE_OS_WINCE if( (flags & (SQLITE_OPEN_READWRITE|SQLITE_OPEN_MAIN_DB)) == (SQLITE_OPEN_READWRITE|SQLITE_OPEN_MAIN_DB) && !winceCreateLock(zName, pFile) @@ -22975,7 +25478,7 @@ static int winOpen( ** Note that windows does not allow a file to be deleted if some other ** process has it open. Sometimes a virus scanner or indexing program ** will open a journal file shortly after it is created in order to do -** whatever does. While this other process is holding the +** whatever it does. While this other process is holding the ** file open, we will be unable to delete it. To work around this ** problem, we delay 100 milliseconds and try to delete again. Up ** to MX_DELETION_ATTEMPTs deletion attempts are run before giving @@ -22989,6 +25492,7 @@ static int winDelete( ){ int cnt = 0; int rc; + DWORD error; void *zConverted = convertUtf8Filename(zFilename); if( zConverted==0 ){ return SQLITE_NOMEM; @@ -22997,21 +25501,22 @@ static int winDelete( if( isNT() ){ do{ DeleteFileW(zConverted); - }while( (rc = GetFileAttributesW(zConverted))!=0xffffffff - && cnt++ < MX_DELETION_ATTEMPTS && (Sleep(100), 1) ); + }while( ( ((rc = GetFileAttributesW(zConverted)) != INVALID_FILE_ATTRIBUTES) + || ((error = GetLastError()) == ERROR_ACCESS_DENIED)) + && (cnt++ < MX_DELETION_ATTEMPTS) + && (Sleep(100), 1) ); }else{ -#if OS_WINCE - return SQLITE_NOMEM; -#else do{ DeleteFileA(zConverted); - }while( (rc = GetFileAttributesA(zConverted))!=0xffffffff - && cnt++ < MX_DELETION_ATTEMPTS && (Sleep(100), 1) ); -#endif + }while( ( ((rc = GetFileAttributesA(zConverted)) != INVALID_FILE_ATTRIBUTES) + || ((error = GetLastError()) == ERROR_ACCESS_DENIED)) + && (cnt++ < MX_DELETION_ATTEMPTS) + && (Sleep(100), 1) ); } free(zConverted); OSTRACE2("DELETE \"%s\"\n", zFilename); - return rc==0xffffffff ? SQLITE_OK : SQLITE_IOERR_DELETE; + return ( (rc==INVALID_FILE_ATTRIBUTES) + && (error == ERROR_FILE_NOT_FOUND)) ? SQLITE_OK : SQLITE_IOERR_DELETE; } /* @@ -23020,7 +25525,8 @@ static int winDelete( static int winAccess( sqlite3_vfs *pVfs, /* Not used on win32 */ const char *zFilename, /* Name of file to check */ - int flags /* Type of test to make on this file */ + int flags, /* Type of test to make on this file */ + int *pResOut /* OUT: Result */ ){ DWORD attr; int rc; @@ -23031,17 +25537,13 @@ static int winAccess( if( isNT() ){ attr = GetFileAttributesW((WCHAR*)zConverted); }else{ -#if OS_WINCE - return SQLITE_NOMEM; -#else attr = GetFileAttributesA((char*)zConverted); -#endif } free(zConverted); switch( flags ){ case SQLITE_ACCESS_READ: case SQLITE_ACCESS_EXISTS: - rc = attr!=0xffffffff; + rc = attr!=INVALID_FILE_ATTRIBUTES; break; case SQLITE_ACCESS_READWRITE: rc = (attr & FILE_ATTRIBUTE_READONLY)==0; @@ -23049,61 +25551,12 @@ static int winAccess( default: assert(!"Invalid flags argument"); } - return rc; + *pResOut = rc; + return SQLITE_OK; } /* -** Create a temporary file name in zBuf. zBuf must be big enough to -** hold at pVfs->mxPathname characters. -*/ -static int winGetTempname(sqlite3_vfs *pVfs, int nBuf, char *zBuf){ - static char zChars[] = - "abcdefghijklmnopqrstuvwxyz" - "ABCDEFGHIJKLMNOPQRSTUVWXYZ" - "0123456789"; - int i, j; - char zTempPath[MAX_PATH+1]; - if( sqlite3_temp_directory ){ - sqlite3_snprintf(MAX_PATH-30, zTempPath, "%s", sqlite3_temp_directory); - }else if( isNT() ){ - char *zMulti; - WCHAR zWidePath[MAX_PATH]; - GetTempPathW(MAX_PATH-30, zWidePath); - zMulti = unicodeToUtf8(zWidePath); - if( zMulti ){ - sqlite3_snprintf(MAX_PATH-30, zTempPath, "%s", zMulti); - free(zMulti); - }else{ - return SQLITE_NOMEM; - } - }else{ - char *zUtf8; - char zMbcsPath[MAX_PATH]; - GetTempPathA(MAX_PATH-30, zMbcsPath); - zUtf8 = mbcsToUtf8(zMbcsPath); - if( zUtf8 ){ - sqlite3_snprintf(MAX_PATH-30, zTempPath, "%s", zUtf8); - free(zUtf8); - }else{ - return SQLITE_NOMEM; - } - } - for(i=strlen(zTempPath); i>0 && zTempPath[i-1]=='\\'; i--){} - zTempPath[i] = 0; - sqlite3_snprintf(nBuf-30, zBuf, - "%s\\"SQLITE_TEMP_FILE_PREFIX, zTempPath); - j = strlen(zBuf); - sqlite3_randomness(20, &zBuf[j]); - for(i=0; i<20; i++, j++){ - zBuf[j] = (char)zChars[ ((unsigned char)zBuf[j])%(sizeof(zChars)-1) ]; - } - zBuf[j] = 0; - OSTRACE2("TEMP FILENAME: %s\n", zBuf); - return SQLITE_OK; -} - -/* ** Turn a relative pathname into a full pathname. Write the full ** pathname into zOut[]. zOut[] will be at least pVfs->mxPathname ** bytes in size. @@ -23120,13 +25573,13 @@ static int winFullPathname( return SQLITE_OK; #endif -#if OS_WINCE +#if SQLITE_OS_WINCE /* WinCE has no concept of a relative pathname, or so I am told. */ sqlite3_snprintf(pVfs->mxPathname, zFull, "%s", zRelative); return SQLITE_OK; #endif -#if !OS_WINCE && !defined(__CYGWIN__) +#if !SQLITE_OS_WINCE && !defined(__CYGWIN__) int nByte; void *zConverted; char *zOut; @@ -23184,37 +25637,16 @@ static void *winDlOpen(sqlite3_vfs *pVfs, const char *zFilename){ if( isNT() ){ h = LoadLibraryW((WCHAR*)zConverted); }else{ -#if OS_WINCE - return 0; -#else h = LoadLibraryA((char*)zConverted); -#endif } free(zConverted); return (void*)h; } static void winDlError(sqlite3_vfs *pVfs, int nBuf, char *zBufOut){ -#if OS_WINCE - int error = GetLastError(); - if( error>0x7FFFFFF ){ - sqlite3_snprintf(nBuf, zBufOut, "OsError 0x%x", error); - }else{ - sqlite3_snprintf(nBuf, zBufOut, "OsError %d", error); - } -#else - FormatMessageA( - FORMAT_MESSAGE_FROM_SYSTEM, - NULL, - GetLastError(), - 0, - zBufOut, - nBuf-1, - 0 - ); -#endif + getLastErrorMsg(nBuf, zBufOut); } void *winDlSym(sqlite3_vfs *pVfs, void *pHandle, const char *zSymbol){ -#if OS_WINCE +#if SQLITE_OS_WINCE /* The GetProcAddressA() routine is only available on wince. */ return GetProcAddressA((HANDLE)pHandle, zSymbol); #else @@ -23292,10 +25724,13 @@ int winCurrentTime(sqlite3_vfs *pVfs, double *prNow){ 100-nanosecond intervals since January 1, 1601 (= JD 2305813.5). */ double now; -#if OS_WINCE +#if SQLITE_OS_WINCE SYSTEMTIME time; GetSystemTime(&time); - SystemTimeToFileTime(&time,&ft); + /* if SystemTimeToFileTime() fails, it returns zero. */ + if (!SystemTimeToFileTime(&time,&ft)){ + return 1; + } #else GetSystemTimeAsFileTime( &ft ); #endif @@ -23309,14 +25744,44 @@ int winCurrentTime(sqlite3_vfs *pVfs, double *prNow){ return 0; } +/* +** The idea is that this function works like a combination of +** GetLastError() and FormatMessage() on windows (or errno and +** strerror_r() on unix). After an error is returned by an OS +** function, SQLite calls this function with zBuf pointing to +** a buffer of nBuf bytes. The OS layer should populate the +** buffer with a nul-terminated UTF-8 encoded error message +** describing the last IO error to have occured within the calling +** thread. +** +** If the error message is too large for the supplied buffer, +** it should be truncated. The return value of xGetLastError +** is zero if the error message fits in the buffer, or non-zero +** otherwise (if the message was truncated). If non-zero is returned, +** then it is not necessary to include the nul-terminator character +** in the output buffer. +** +** Not supplying an error message will have no adverse effect +** on SQLite. It is fine to have an implementation that never +** returns an error message: +** +** int xGetLastError(sqlite3_vfs *pVfs, int nBuf, char *zBuf){ +** assert(zBuf[0]=='\0'); +** return 0; +** } +** +** However if an error message is supplied, it will be incorporated +** by sqlite into the error message available to the user using +** sqlite3_errmsg(), possibly making IO errors easier to debug. +*/ +static int winGetLastError(sqlite3_vfs *pVfs, int nBuf, char *zBuf){ + return getLastErrorMsg(nBuf, zBuf); +} /* -** Return a pointer to the sqlite3DefaultVfs structure. We use -** a function rather than give the structure global scope because -** some compilers (MSVC) do not allow forward declarations of -** initialized structures. +** Initialize and deinitialize the operating system interface. */ -SQLITE_PRIVATE sqlite3_vfs *sqlite3OsDefaultVfs(void){ +SQLITE_API int sqlite3_os_init(void){ static sqlite3_vfs winVfs = { 1, /* iVersion */ sizeof(winFile), /* szOsFile */ @@ -23324,11 +25789,10 @@ SQLITE_PRIVATE sqlite3_vfs *sqlite3OsDefaultVfs(void){ 0, /* pNext */ "win32", /* zName */ 0, /* pAppData */ - + winOpen, /* xOpen */ winDelete, /* xDelete */ winAccess, /* xAccess */ - winGetTempname, /* xGetTempName */ winFullPathname, /* xFullPathname */ winDlOpen, /* xDlOpen */ winDlError, /* xDlError */ @@ -23336,13 +25800,17 @@ SQLITE_PRIVATE sqlite3_vfs *sqlite3OsDefaultVfs(void){ winDlClose, /* xDlClose */ winRandomness, /* xRandomness */ winSleep, /* xSleep */ - winCurrentTime /* xCurrentTime */ + winCurrentTime, /* xCurrentTime */ + winGetLastError /* xGetLastError */ }; - - return &winVfs; + sqlite3_vfs_register(&winVfs, 1); + return SQLITE_OK; +} +SQLITE_API int sqlite3_os_end(void){ + return SQLITE_OK; } -#endif /* OS_WIN */ +#endif /* SQLITE_OS_WIN */ /************** End of os_win.c **********************************************/ /************** Begin file bitvec.c ******************************************/ @@ -23487,9 +25955,9 @@ SQLITE_PRIVATE int sqlite3BitvecSet(Bitvec *p, u32 i){ u32 bin = (i-1)/p->iDivisor; i = (i-1)%p->iDivisor + 1; if( p->u.apSub[bin]==0 ){ - sqlite3FaultBeginBenign(SQLITE_FAULTINJECTOR_MALLOC); + sqlite3BeginBenignMalloc(); p->u.apSub[bin] = sqlite3BitvecCreate( p->iDivisor ); - sqlite3FaultEndBenign(SQLITE_FAULTINJECTOR_MALLOC); + sqlite3EndBenignMalloc(); if( p->u.apSub[bin]==0 ) return SQLITE_NOMEM; } return sqlite3BitvecSet(p->u.apSub[bin], i); @@ -23941,6 +26409,7 @@ struct PgHdr { short int nRef; /* Number of users of this page */ PgHdr *pDirty, *pPrevDirty; /* Dirty pages */ #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT + PgHdr *pPrevAll; /* A list of all pages */ PagerLruLink gfree; /* Global list of nRef==0 pages */ #endif #ifdef SQLITE_CHECK_PAGES @@ -24044,7 +26513,6 @@ struct Pager { char *zFilename; /* Name of the database file */ char *zJournal; /* Name of the journal file */ char *zDirectory; /* Directory hold database and journal files */ - char *zStmtJrnl; /* Name of the statement journal file */ sqlite3_file *fd, *jfd; /* File descriptors for database and journal */ sqlite3_file *stfd; /* File descriptor for the statement subjournal*/ BusyHandler *pBusyHandler; /* Pointer to sqlite.busyHandler */ @@ -24073,11 +26541,12 @@ struct Pager { #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT Pager *pNext; /* Doubly linked list of pagers on which */ Pager *pPrev; /* sqlite3_release_memory() will work */ - int iInUseMM; /* Non-zero if unavailable to MM */ - int iInUseDB; /* Non-zero if in sqlite3_release_memory() */ + volatile int iInUseMM; /* Non-zero if unavailable to MM */ + volatile int iInUseDB; /* Non-zero if in sqlite3_release_memory() */ #endif char *pTmpSpace; /* Pager.pageSize bytes of space for tmp use */ char dbFileVers[16]; /* Changes whenever database file changes */ + i64 journalSizeLimit; /* Size limit for persistent journal files */ }; /* @@ -24190,7 +26659,7 @@ static const unsigned char aJournalMagic[] = { if( p->iInUseMM && p->iInUseDB==1 ){ #ifndef SQLITE_MUTEX_NOOP sqlite3_mutex *mutex; - mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MEM2); + mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM2); #endif p->iInUseDB = 0; sqlite3_mutex_enter(mutex); @@ -24288,9 +26757,9 @@ static void lruListAdd(PgHdr *pPg){ listAdd(&pPg->pPager->lru, &pPg->free, pPg); #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT if( !pPg->pPager->memDb ){ - sqlite3_mutex_enter(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_LRU)); + sqlite3_mutex_enter(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_LRU)); listAdd(&sqlite3LruPageList, &pPg->gfree, pPg); - sqlite3_mutex_leave(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_LRU)); + sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_LRU)); } #endif } @@ -24304,9 +26773,9 @@ static void lruListRemove(PgHdr *pPg){ listRemove(&pPg->pPager->lru, &pPg->free, pPg); #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT if( !pPg->pPager->memDb ){ - sqlite3_mutex_enter(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_LRU)); + sqlite3_mutex_enter(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_LRU)); listRemove(&sqlite3LruPageList, &pPg->gfree, pPg); - sqlite3_mutex_leave(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_LRU)); + sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_LRU)); } #endif } @@ -24323,11 +26792,11 @@ static void lruListSetFirstSynced(Pager *pPager){ #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT if( !pPager->memDb ){ PgHdr *p; - sqlite3_mutex_enter(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_LRU)); + sqlite3_mutex_enter(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_LRU)); for(p=sqlite3LruPageList.pFirst; p && p->needSync; p=p->gfree.pNext); assert(p==pPager->lru.pFirstSynced || p==sqlite3LruPageList.pFirstSynced); sqlite3LruPageList.pFirstSynced = p; - sqlite3_mutex_leave(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_LRU)); + sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_LRU)); } #endif } @@ -24360,9 +26829,9 @@ static void pager_resize_hash_table(Pager *pPager, int N){ if( N==pPager->nHash ) return; #endif pagerLeave(pPager); - if( pPager->aHash!=0 ) sqlite3FaultBeginBenign(SQLITE_FAULTINJECTOR_MALLOC); + if( pPager->aHash!=0 ) sqlite3BeginBenignMalloc(); aHash = sqlite3MallocZero( sizeof(aHash[0])*N ); - if( pPager->aHash!=0 ) sqlite3FaultEndBenign(SQLITE_FAULTINJECTOR_MALLOC); + if( pPager->aHash!=0 ) sqlite3EndBenignMalloc(); pagerEnter(pPager); if( aHash==0 ){ /* Failure to rehash is not an error. It is only a performance hit. */ @@ -24445,19 +26914,20 @@ static int osUnlock(sqlite3_file *pFd, int eLock){ static int jrnlBufferSize(Pager *pPager){ int dc; /* Device characteristics */ int nSector; /* Sector size */ - int nPage; /* Page size */ + int szPage; /* Page size */ sqlite3_file *fd = pPager->fd; if( fd->pMethods ){ dc = sqlite3OsDeviceCharacteristics(fd); nSector = sqlite3OsSectorSize(fd); - nPage = pPager->pageSize; + szPage = pPager->pageSize; } assert(SQLITE_IOCAP_ATOMIC512==(512>>8)); assert(SQLITE_IOCAP_ATOMIC64K==(65536>>8)); - if( !fd->pMethods || (dc&(SQLITE_IOCAP_ATOMIC|(nPage>>8))&&nSector<=nPage) ){ + if( !fd->pMethods || + (dc & (SQLITE_IOCAP_ATOMIC|(szPage>>8)) && nSector<=szPage) ){ return JOURNAL_HDR_SZ(pPager) + JOURNAL_PG_SZ(pPager); } return 0; @@ -24566,7 +27036,7 @@ static int readMasterJournal(sqlite3_file *pJrnl, char *zMaster, int nMaster){ u32 len; i64 szJ; u32 cksum; - int i; + u32 u; /* Unsigned loop counter */ unsigned char aMagic[8]; /* A buffer to hold the magic header */ zMaster[0] = '\0'; @@ -24594,8 +27064,8 @@ static int readMasterJournal(sqlite3_file *pJrnl, char *zMaster, int nMaster){ zMaster[len] = '\0'; /* See if the checksum matches the master journal name */ - for(i=0; i<len; i++){ - cksum -= zMaster[i]; + for(u=0; u<len; u++){ + cksum -= zMaster[u]; } if( cksum ){ /* If the checksum doesn't add up, then one or more of the disk sectors @@ -24646,15 +27116,31 @@ static int zeroJournalHdr(Pager *pPager, int doTruncate){ static const char zeroHdr[28]; if( pPager->journalOff ){ + i64 iLimit = pPager->journalSizeLimit; + IOTRACE(("JZEROHDR %p\n", pPager)) - if( doTruncate ){ + if( doTruncate || iLimit==0 ){ rc = sqlite3OsTruncate(pPager->jfd, 0); }else{ rc = sqlite3OsWrite(pPager->jfd, zeroHdr, sizeof(zeroHdr), 0); } - if( rc==SQLITE_OK ){ + if( rc==SQLITE_OK && !pPager->noSync ){ rc = sqlite3OsSync(pPager->jfd, SQLITE_SYNC_DATAONLY|pPager->sync_flags); } + + /* At this point the transaction is committed but the write lock + ** is still held on the file. If there is a size limit configured for + ** the persistent journal and the journal file currently consumes more + ** space than that limit allows for, truncate it now. There is no need + ** to sync the file following this operation. + */ + if( rc==SQLITE_OK && iLimit>0 ){ + i64 sz; + rc = sqlite3OsFileSize(pPager->jfd, &sz); + if( rc==SQLITE_OK && sz>iLimit ){ + rc = sqlite3OsTruncate(pPager->jfd, iLimit); + } + } } return rc; } @@ -24950,7 +27436,7 @@ static void pager_reset(Pager *pPager){ PAGER_INCR(sqlite3_pager_pgfree_count); pNext = pPg->pNextAll; lruListRemove(pPg); - sqlite3_free(pPg->pData); + sqlite3PageFree(pPg->pData); sqlite3_free(pPg); } assert(pPager->lru.pFirst==0); @@ -25030,9 +27516,9 @@ static void pager_unlock(Pager *pPager){ static void pagerUnlockAndRollback(Pager *p){ /* assert( p->state>=PAGER_RESERVED || p->journalOpen==0 ); */ if( p->errCode==SQLITE_OK && p->state>=PAGER_RESERVED ){ - sqlite3FaultBeginBenign(-1); + sqlite3BeginBenignMalloc(); sqlite3PagerRollback(p); - sqlite3FaultEndBenign(-1); + sqlite3EndBenignMalloc(); } pager_unlock(p); #if 0 @@ -25082,7 +27568,7 @@ static int pager_end_transaction(Pager *pPager, int hasMaster){ }else{ sqlite3OsClose(pPager->jfd); pPager->journalOpen = 0; - if( rc==SQLITE_OK ){ + if( rc==SQLITE_OK && !pPager->tempFile ){ rc = sqlite3OsDelete(pPager->pVfs, pPager->zJournal, 0); } } @@ -25306,7 +27792,7 @@ static int pager_delmaster(Pager *pPager, const char *zMaster){ /* Open the master journal file exclusively in case some other process ** is running this routine also. Not that it makes too much difference. */ - pMaster = (sqlite3_file *)sqlite3_malloc(pVfs->szOsFile * 2); + pMaster = (sqlite3_file *)sqlite3Malloc(pVfs->szOsFile * 2); pJournal = (sqlite3_file *)(((u8 *)pMaster) + pVfs->szOsFile); if( !pMaster ){ rc = SQLITE_NOMEM; @@ -25328,7 +27814,7 @@ static int pager_delmaster(Pager *pPager, const char *zMaster){ /* Load the entire master journal file into space obtained from ** sqlite3_malloc() and pointed to by zMasterJournal. */ - zMasterJournal = (char *)sqlite3_malloc(nMasterJournal + nMasterPtr); + zMasterJournal = (char *)sqlite3Malloc(nMasterJournal + nMasterPtr); if( !zMasterJournal ){ rc = SQLITE_NOMEM; goto delmaster_out; @@ -25339,12 +27825,12 @@ static int pager_delmaster(Pager *pPager, const char *zMaster){ zJournal = zMasterJournal; while( (zJournal-zMasterJournal)<nMasterJournal ){ - rc = sqlite3OsAccess(pVfs, zJournal, SQLITE_ACCESS_EXISTS); - if( rc!=0 && rc!=1 ){ - rc = SQLITE_IOERR_NOMEM; + int exists; + rc = sqlite3OsAccess(pVfs, zJournal, SQLITE_ACCESS_EXISTS, &exists); + if( rc!=SQLITE_OK ){ goto delmaster_out; } - if( rc==1 ){ + if( exists ){ /* One of the journals pointed to by the master journal exists. ** Open it and check if it points at the master journal. If ** so, return without deleting the master journal file. @@ -25502,10 +27988,10 @@ static int pager_playback(Pager *pPager, int isHot){ sqlite3_vfs *pVfs = pPager->pVfs; i64 szJ; /* Size of the journal file in bytes */ u32 nRec; /* Number of Records in the journal */ - int i; /* Loop counter */ + u32 u; /* Unsigned loop counter */ Pgno mxPg = 0; /* Size of the original file in pages */ int rc; /* Result code of a subroutine */ - int res = 0; /* Value returned by sqlite3OsAccess() */ + int res = 1; /* Value returned by sqlite3OsAccess() */ char *zMaster = 0; /* Name of master journal file if any */ /* Figure out how many records are in the journal. Abort early if @@ -25524,15 +28010,11 @@ static int pager_playback(Pager *pPager, int isHot){ */ zMaster = pPager->pTmpSpace; rc = readMasterJournal(pPager->jfd, zMaster, pPager->pVfs->mxPathname+1); - if( rc!=SQLITE_OK || (zMaster[0] - && (res=sqlite3OsAccess(pVfs, zMaster, SQLITE_ACCESS_EXISTS))==0 ) - ){ - zMaster = 0; - goto end_playback; + if( rc==SQLITE_OK && zMaster[0] ){ + rc = sqlite3OsAccess(pVfs, zMaster, SQLITE_ACCESS_EXISTS, &res); } zMaster = 0; - if( res<0 ){ - rc = SQLITE_IOERR_NOMEM; + if( rc!=SQLITE_OK || !res ){ goto end_playback; } pPager->journalOff = 0; @@ -25589,7 +28071,7 @@ static int pager_playback(Pager *pPager, int isHot){ /* Copy original pages out of the journal and back into the database file. */ - for(i=0; i<nRec; i++){ + for(u=0; u<nRec; u++){ rc = pager_playback_one_page(pPager, pPager->jfd, pPager->journalOff, 1); if( rc!=SQLITE_OK ){ if( rc==SQLITE_DONE ){ @@ -25791,13 +28273,11 @@ SQLITE_API int sqlite3_opentemp_count = 0; ** file when it is closed. */ static int sqlite3PagerOpentemp( - sqlite3_vfs *pVfs, /* The virtual file system layer */ + Pager *pPager, /* The pager object */ sqlite3_file *pFile, /* Write the file descriptor here */ - char *zFilename, /* Name of the file. Might be NULL */ int vfsFlags /* Flags passed through to the VFS */ ){ int rc; - assert( zFilename!=0 ); #ifdef SQLITE_TEST sqlite3_opentemp_count++; /* Used for testing and analysis only */ @@ -25805,7 +28285,7 @@ static int sqlite3PagerOpentemp( vfsFlags |= SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | SQLITE_OPEN_EXCLUSIVE | SQLITE_OPEN_DELETEONCLOSE; - rc = sqlite3OsOpen(pVfs, zFilename, pFile, vfsFlags, 0); + rc = sqlite3OsOpen(pPager->pVfs, 0, pFile, vfsFlags, 0); assert( rc!=SQLITE_OK || pFile->pMethods ); return rc; } @@ -25842,22 +28322,23 @@ SQLITE_PRIVATE int sqlite3PagerOpen( int useJournal = (flags & PAGER_OMIT_JOURNAL)==0; int noReadlock = (flags & PAGER_NO_READLOCK)!=0; int journalFileSize = sqlite3JournalSize(pVfs); - int nDefaultPage = SQLITE_DEFAULT_PAGE_SIZE; - char *zPathname; - int nPathname; - char *zStmtJrnl; - int nStmtJrnl; + int szPageDflt = SQLITE_DEFAULT_PAGE_SIZE; + char *zPathname = 0; + int nPathname = 0; /* The default return is a NULL pointer */ *ppPager = 0; - /* Compute the full pathname */ - nPathname = pVfs->mxPathname+1; - zPathname = sqlite3_malloc(nPathname*2); - if( zPathname==0 ){ - return SQLITE_NOMEM; - } + /* Compute and store the full pathname in an allocated buffer pointed + ** to by zPathname, length nPathname. Or, if this is a temporary file, + ** leave both nPathname and zPathname set to 0. + */ if( zFilename && zFilename[0] ){ + nPathname = pVfs->mxPathname+1; + zPathname = sqlite3Malloc(nPathname*2); + if( zPathname==0 ){ + return SQLITE_NOMEM; + } #ifndef SQLITE_OMIT_MEMORYDB if( strcmp(zFilename,":memory:")==0 ){ memDb = 1; @@ -25867,35 +28348,19 @@ SQLITE_PRIVATE int sqlite3PagerOpen( { rc = sqlite3OsFullPathname(pVfs, zFilename, nPathname, zPathname); } - }else{ - rc = sqlite3OsGetTempname(pVfs, nPathname, zPathname); - } - if( rc!=SQLITE_OK ){ - sqlite3_free(zPathname); - return rc; - } - nPathname = strlen(zPathname); - - /* Put the statement journal in temporary disk space since this is - ** sometimes RAM disk or other optimized storage. Unlikely the main - ** main journal file, the statement journal does not need to be - ** colocated with the database nor does it need to be persistent. - */ - zStmtJrnl = &zPathname[nPathname+1]; - rc = sqlite3OsGetTempname(pVfs, pVfs->mxPathname+1, zStmtJrnl); - if( rc!=SQLITE_OK ){ - sqlite3_free(zPathname); - return rc; + if( rc!=SQLITE_OK ){ + sqlite3_free(zPathname); + return rc; + } + nPathname = strlen(zPathname); } - nStmtJrnl = strlen(zStmtJrnl); /* Allocate memory for the pager structure */ pPager = sqlite3MallocZero( sizeof(*pPager) + /* Pager structure */ journalFileSize + /* The journal file structure */ pVfs->szOsFile * 3 + /* The main db and two journal files */ - 3*nPathname + 40 + /* zFilename, zDirectory, zJournal */ - nStmtJrnl /* zStmtJrnl */ + 3*nPathname + 40 /* zFilename, zDirectory, zJournal */ ); if( !pPager ){ sqlite3_free(zPathname); @@ -25909,11 +28374,11 @@ SQLITE_PRIVATE int sqlite3PagerOpen( pPager->zFilename = (char*)&pPtr[pVfs->szOsFile*2+journalFileSize]; pPager->zDirectory = &pPager->zFilename[nPathname+1]; pPager->zJournal = &pPager->zDirectory[nPathname+1]; - pPager->zStmtJrnl = &pPager->zJournal[nPathname+10]; pPager->pVfs = pVfs; - memcpy(pPager->zFilename, zPathname, nPathname+1); - memcpy(pPager->zStmtJrnl, zStmtJrnl, nStmtJrnl+1); - sqlite3_free(zPathname); + if( zPathname ){ + memcpy(pPager->zFilename, zPathname, nPathname+1); + sqlite3_free(zPathname); + } /* Open the pager file. */ @@ -25936,8 +28401,8 @@ SQLITE_PRIVATE int sqlite3PagerOpen( */ if( rc==SQLITE_OK && !readOnly ){ int iSectorSize = sqlite3OsSectorSize(pPager->fd); - if( nDefaultPage<iSectorSize ){ - nDefaultPage = iSectorSize; + if( szPageDflt<iSectorSize ){ + szPageDflt = iSectorSize; } #ifdef SQLITE_ENABLE_ATOMIC_WRITE { @@ -25946,13 +28411,13 @@ SQLITE_PRIVATE int sqlite3PagerOpen( assert(SQLITE_IOCAP_ATOMIC512==(512>>8)); assert(SQLITE_IOCAP_ATOMIC64K==(65536>>8)); assert(SQLITE_MAX_DEFAULT_PAGE_SIZE<=65536); - for(ii=nDefaultPage; ii<=SQLITE_MAX_DEFAULT_PAGE_SIZE; ii=ii*2){ - if( iDc&(SQLITE_IOCAP_ATOMIC|(ii>>8)) ) nDefaultPage = ii; + for(ii=szPageDflt; ii<=SQLITE_MAX_DEFAULT_PAGE_SIZE; ii=ii*2){ + if( iDc&(SQLITE_IOCAP_ATOMIC|(ii>>8)) ) szPageDflt = ii; } } #endif - if( nDefaultPage>SQLITE_MAX_DEFAULT_PAGE_SIZE ){ - nDefaultPage = SQLITE_MAX_DEFAULT_PAGE_SIZE; + if( szPageDflt>SQLITE_MAX_DEFAULT_PAGE_SIZE ){ + szPageDflt = SQLITE_MAX_DEFAULT_PAGE_SIZE; } } } @@ -25966,7 +28431,7 @@ SQLITE_PRIVATE int sqlite3PagerOpen( } if( pPager && rc==SQLITE_OK ){ - pPager->pTmpSpace = sqlite3MallocZero(nDefaultPage); + pPager->pTmpSpace = sqlite3PageMalloc(szPageDflt); } /* If an error occured in either of the blocks above. @@ -25989,8 +28454,12 @@ SQLITE_PRIVATE int sqlite3PagerOpen( if( i>0 ) pPager->zDirectory[i-1] = 0; /* Fill in Pager.zJournal[] */ - memcpy(pPager->zJournal, pPager->zFilename, nPathname); - memcpy(&pPager->zJournal[nPathname], "-journal", 9); + if( zPathname ){ + memcpy(pPager->zJournal, pPager->zFilename, nPathname); + memcpy(&pPager->zJournal[nPathname], "-journal", 9); + }else{ + pPager->zJournal = 0; + } /* pPager->journalOpen = 0; */ pPager->useJournal = useJournal && !memDb; @@ -25999,7 +28468,7 @@ SQLITE_PRIVATE int sqlite3PagerOpen( /* pPager->stmtInUse = 0; */ /* pPager->nRef = 0; */ pPager->dbSize = memDb-1; - pPager->pageSize = nDefaultPage; + pPager->pageSize = szPageDflt; /* pPager->stmtSize = 0; */ /* pPager->stmtJSize = 0; */ /* pPager->nPage = 0; */ @@ -26023,6 +28492,7 @@ SQLITE_PRIVATE int sqlite3PagerOpen( /* pPager->pFirstSynced = 0; */ /* pPager->pLast = 0; */ pPager->nExtra = FORCE_ALIGNMENT(nExtra); + pPager->journalSizeLimit = SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT; assert(pPager->fd->pMethods||memDb||tempFile); if( !memDb ){ setSectorSize(pPager); @@ -26035,7 +28505,7 @@ SQLITE_PRIVATE int sqlite3PagerOpen( pPager->iInUseDB = 0; if( !memDb ){ #ifndef SQLITE_MUTEX_NOOP - sqlite3_mutex *mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MEM2); + sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM2); #endif sqlite3_mutex_enter(mutex); pPager->pNext = sqlite3PagerList; @@ -26093,7 +28563,7 @@ SQLITE_PRIVATE int sqlite3PagerSetPagesize(Pager *pPager, u16 *pPageSize){ if( pageSize && pageSize!=pPager->pageSize && !pPager->memDb && pPager->nRef==0 ){ - char *pNew = (char *)sqlite3_malloc(pageSize); + char *pNew = (char *)sqlite3PageMalloc(pageSize); if( !pNew ){ rc = SQLITE_NOMEM; }else{ @@ -26101,7 +28571,7 @@ SQLITE_PRIVATE int sqlite3PagerSetPagesize(Pager *pPager, u16 *pPageSize){ pager_reset(pPager); pPager->pageSize = pageSize; setSectorSize(pPager); - sqlite3_free(pPager->pTmpSpace); + sqlite3PageFree(pPager->pTmpSpace); pPager->pTmpSpace = pNew; pagerLeave(pPager); } @@ -26133,7 +28603,7 @@ SQLITE_PRIVATE int sqlite3PagerMaxPageCount(Pager *pPager, int mxPage){ if( mxPage>0 ){ pPager->mxPgno = mxPage; } - sqlite3PagerPagecount(pPager); + sqlite3PagerPagecount(pPager, 0); return pPager->mxPgno; } @@ -26194,12 +28664,12 @@ SQLITE_PRIVATE int sqlite3PagerReadFileheader(Pager *pPager, int N, unsigned cha ** PENDING_BYTE is byte 4096 (the first byte of page 5) and the size of the ** file is 4096 bytes, 5 is returned instead of 4. */ -SQLITE_PRIVATE int sqlite3PagerPagecount(Pager *pPager){ +SQLITE_PRIVATE int sqlite3PagerPagecount(Pager *pPager, int *pnPage){ i64 n = 0; int rc; assert( pPager!=0 ); if( pPager->errCode ){ - return -1; + return pPager->errCode; } if( pPager->dbSize>=0 ){ n = pPager->dbSize; @@ -26210,7 +28680,7 @@ SQLITE_PRIVATE int sqlite3PagerPagecount(Pager *pPager){ pPager->nRef++; pager_error(pPager, rc); pPager->nRef--; - return -1; + return rc; } if( n>0 && n<pPager->pageSize ){ n = 1; @@ -26227,7 +28697,10 @@ SQLITE_PRIVATE int sqlite3PagerPagecount(Pager *pPager){ if( n>pPager->mxPgno ){ pPager->mxPgno = n; } - return n; + if( pnPage ){ + *pnPage = n; + } + return SQLITE_OK; } @@ -26236,8 +28709,8 @@ SQLITE_PRIVATE int sqlite3PagerPagecount(Pager *pPager){ ** Clear a PgHistory block */ static void clearHistory(PgHistory *pHist){ - sqlite3_free(pHist->pOrig); - sqlite3_free(pHist->pStmt); + sqlite3PageFree(pHist->pOrig); + sqlite3PageFree(pHist->pStmt); pHist->pOrig = 0; pHist->pStmt = 0; } @@ -26318,11 +28791,16 @@ static void pager_truncate_cache(Pager *pPager){ ppPg = &pPg->pNextAll; }else{ *ppPg = pPg->pNextAll; +#ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT + if( *ppPg ){ + (*ppPg)->pPrevAll = pPg->pPrevAll; + } +#endif IOTRACE(("PGFREE %p %d\n", pPager, pPg->pgno)); PAGER_INCR(sqlite3_pager_pgfree_count); unlinkPage(pPg); makeClean(pPg); - sqlite3_free(pPg->pData); + sqlite3PageFree(pPg->pData); sqlite3_free(pPg); pPager->nPage--; } @@ -26369,7 +28847,7 @@ static int pager_wait_on_lock(Pager *pPager, int locktype){ SQLITE_PRIVATE int sqlite3PagerTruncate(Pager *pPager, Pgno nPage){ int rc; assert( pPager->state>=PAGER_SHARED || MEMDB ); - sqlite3PagerPagecount(pPager); + sqlite3PagerPagecount(pPager, 0); if( pPager->errCode ){ rc = pPager->errCode; return rc; @@ -26419,7 +28897,7 @@ SQLITE_PRIVATE int sqlite3PagerClose(Pager *pPager){ #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT if( !MEMDB ){ #ifndef SQLITE_MUTEX_NOOP - sqlite3_mutex *mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MEM2); + sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM2); #endif sqlite3_mutex_enter(mutex); if( pPager->pPrev ){ @@ -26435,13 +28913,13 @@ SQLITE_PRIVATE int sqlite3PagerClose(Pager *pPager){ #endif disable_simulated_io_errors(); - sqlite3FaultBeginBenign(-1); + sqlite3BeginBenignMalloc(); pPager->errCode = 0; pPager->exclusiveMode = 0; pager_reset(pPager); pagerUnlockAndRollback(pPager); enable_simulated_io_errors(); - sqlite3FaultEndBenign(-1); + sqlite3EndBenignMalloc(); PAGERTRACE2("CLOSE %d\n", PAGERID(pPager)); IOTRACE(("CLOSE %p\n", pPager)) if( pPager->journalOpen ){ @@ -26459,7 +28937,7 @@ SQLITE_PRIVATE int sqlite3PagerClose(Pager *pPager){ */ sqlite3_free(pPager->aHash); - sqlite3_free(pPager->pTmpSpace); + sqlite3PageFree(pPager->pTmpSpace); sqlite3_free(pPager); return SQLITE_OK; } @@ -26542,7 +29020,6 @@ static int syncJournal(Pager *pPager){ PgHdr *pPg; int rc = SQLITE_OK; - /* Sync the journal before modifying the main database ** (assuming there is a journal and it needs to be synced.) */ @@ -26730,8 +29207,7 @@ static int pager_write_pagelist(PgHdr *pList){ /* If the file has not yet been opened, open it now. */ if( !pPager->fd->pMethods ){ assert(pPager->tempFile); - rc = sqlite3PagerOpentemp(pPager->pVfs, pPager->fd, pPager->zFilename, - pPager->vfsFlags); + rc = sqlite3PagerOpentemp(pPager, pPager->fd, pPager->vfsFlags); if( rc ) return rc; } @@ -26808,24 +29284,33 @@ static PgHdr *pager_get_all_dirty_pages(Pager *pPager){ ** is hot. The pager_playback() routine will discover that the ** journal file is not really hot and will no-op. */ -static int hasHotJournal(Pager *pPager){ +static int hasHotJournal(Pager *pPager, int *pExists){ sqlite3_vfs *pVfs = pPager->pVfs; - int rc; - if( !pPager->useJournal ) return 0; - if( !pPager->fd->pMethods ) return 0; - rc = sqlite3OsAccess(pVfs, pPager->zJournal, SQLITE_ACCESS_EXISTS); - if( rc<=0 ){ - return rc; - } - if( sqlite3OsCheckReservedLock(pPager->fd) ){ - return 0; - } - if( sqlite3PagerPagecount(pPager)==0 ){ - sqlite3OsDelete(pVfs, pPager->zJournal, 0); - return 0; - }else{ - return 1; + int rc = SQLITE_OK; + *pExists = 0; + if( pPager->useJournal && pPager->fd->pMethods ){ + int exists; + int locked; + + rc = sqlite3OsAccess(pVfs, pPager->zJournal, SQLITE_ACCESS_EXISTS, &exists); + if( rc==SQLITE_OK && exists ){ + rc = sqlite3OsCheckReservedLock(pPager->fd, &locked); + } + + if( rc==SQLITE_OK && exists && !locked ){ + int nPage; + rc = sqlite3PagerPagecount(pPager, &nPage); + if( rc==SQLITE_OK ){ + if( nPage==0 ){ + sqlite3OsDelete(pVfs, pPager->zJournal, 0); + }else{ + *pExists = 1; + } + } + } } + + return rc; } /* @@ -26854,26 +29339,28 @@ static int pager_recycle(Pager *pPager, PgHdr **ppPg){ ** very slow operation, so we work hard to avoid it. But sometimes ** it can't be helped. */ - if( pPg==0 && pPager->lru.pFirst){ - int iDc = sqlite3OsDeviceCharacteristics(pPager->fd); - int rc = syncJournal(pPager); - if( rc!=0 ){ - return rc; - } - if( pPager->fullSync && 0==(iDc&SQLITE_IOCAP_SAFE_APPEND) ){ - /* If in full-sync mode, write a new journal header into the - ** journal file. This is done to avoid ever modifying a journal - ** header that is involved in the rollback of pages that have - ** already been written to the database (in case the header is - ** trashed when the nRec field is updated). - */ - pPager->nRec = 0; - assert( pPager->journalOff > 0 ); - assert( pPager->doNotSync==0 ); - rc = writeJournalHdr(pPager); + if( pPg==0 && pPager->lru.pFirst ){ + if( !pPager->errCode ){ + int iDc = sqlite3OsDeviceCharacteristics(pPager->fd); + int rc = syncJournal(pPager); if( rc!=0 ){ return rc; } + if( pPager->fullSync && 0==(iDc&SQLITE_IOCAP_SAFE_APPEND) ){ + /* If in full-sync mode, write a new journal header into the + ** journal file. This is done to avoid ever modifying a journal + ** header that is involved in the rollback of pages that have + ** already been written to the database (in case the header is + ** trashed when the nRec field is updated). + */ + pPager->nRec = 0; + assert( pPager->journalOff > 0 ); + assert( pPager->doNotSync==0 ); + rc = writeJournalHdr(pPager); + if( rc!=0 ){ + return rc; + } + } } pPg = pPager->lru.pFirst; } @@ -26882,7 +29369,7 @@ static int pager_recycle(Pager *pPager, PgHdr **ppPg){ /* Write the page to the database file if it is dirty. */ - if( pPg->dirty ){ + if( pPg->dirty && !pPager->errCode ){ int rc; assert( pPg->needSync==0 ); makeClean(pPg); @@ -26894,7 +29381,7 @@ static int pager_recycle(Pager *pPager, PgHdr **ppPg){ return rc; } } - assert( pPg->dirty==0 ); + assert( pPg->dirty==0 || pPager->errCode ); /* If the page we are recycling is marked as alwaysRollback, then ** set the global alwaysRollback flag, thus disabling the @@ -26938,7 +29425,7 @@ SQLITE_PRIVATE int sqlite3PagerReleaseMemory(int nReq){ */ #ifndef SQLITE_MUTEX_NOOP sqlite3_mutex *mutex; /* The MEM2 mutex */ - mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MEM2); + mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM2); #endif sqlite3_mutex_enter(mutex); @@ -26956,7 +29443,7 @@ SQLITE_PRIVATE int sqlite3PagerReleaseMemory(int nReq){ /* Try to find a page to recycle that does not require a sync(). If ** this is not possible, find one that does require a sync(). */ - sqlite3_mutex_enter(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_LRU)); + sqlite3_mutex_enter(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_LRU)); pPg = sqlite3LruPageList.pFirstSynced; while( pPg && (pPg->needSync || pPg->pPager->iInUseDB) ){ pPg = pPg->gfree.pNext; @@ -26967,7 +29454,7 @@ SQLITE_PRIVATE int sqlite3PagerReleaseMemory(int nReq){ pPg = pPg->gfree.pNext; } } - sqlite3_mutex_leave(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_LRU)); + sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_LRU)); /* If pPg==0, then the block above has failed to find a page to ** recycle. In this case return early - no further memory will @@ -26996,10 +29483,20 @@ SQLITE_PRIVATE int sqlite3PagerReleaseMemory(int nReq){ PgHdr *pTmp; assert( pPg ); if( pPg==pPager->pAll ){ + assert(pPg->pPrevAll==0); + assert(pPg->pNextAll==0 || pPg->pNextAll->pPrevAll==pPg); pPager->pAll = pPg->pNextAll; + if( pPager->pAll ){ + pPager->pAll->pPrevAll = 0; + } }else{ - for( pTmp=pPager->pAll; pTmp->pNextAll!=pPg; pTmp=pTmp->pNextAll ){} - pTmp->pNextAll = pPg->pNextAll; + assert(pPg->pPrevAll); + assert(pPg->pPrevAll->pNextAll==pPg); + pTmp = pPg->pPrevAll; + pTmp->pNextAll = pPg->pNextAll; + if( pTmp->pNextAll ){ + pTmp->pNextAll->pPrevAll = pTmp; + } } nReleased += ( sizeof(*pPg) + pPager->pageSize @@ -27008,7 +29505,7 @@ SQLITE_PRIVATE int sqlite3PagerReleaseMemory(int nReq){ ); IOTRACE(("PGFREE %p %d *\n", pPager, pPg->pgno)); PAGER_INCR(sqlite3_pager_pgfree_count); - sqlite3_free(pPg->pData); + sqlite3PageFree(pPg->pData); sqlite3_free(pPg); pPager->nPage--; }else{ @@ -27079,7 +29576,7 @@ static int readDbPage(Pager *pPager, PgHdr *pPg, Pgno pgno){ */ static int pagerSharedLock(Pager *pPager){ int rc = SQLITE_OK; - int isHot = 0; + int isErrorReset = 0; /* If this database is opened for exclusive access, has no outstanding ** page references and is in an error-state, now is the chance to clear @@ -27088,7 +29585,7 @@ static int pagerSharedLock(Pager *pPager){ */ if( !MEMDB && pPager->exclusiveMode && pPager->nRef==0 && pPager->errCode ){ if( pPager->journalOpen ){ - isHot = 1; + isErrorReset = 1; } pPager->errCode = SQLITE_OK; pager_reset(pPager); @@ -27102,9 +29599,10 @@ static int pagerSharedLock(Pager *pPager){ return pPager->errCode; } - if( pPager->state==PAGER_UNLOCK || isHot ){ + if( pPager->state==PAGER_UNLOCK || isErrorReset ){ sqlite3_vfs *pVfs = pPager->pVfs; if( !MEMDB ){ + int isHotJournal; assert( pPager->nRef==0 ); if( !pPager->noReadlock ){ rc = pager_wait_on_lock(pPager, SHARED_LOCK); @@ -27118,12 +29616,13 @@ static int pagerSharedLock(Pager *pPager){ /* If a journal file exists, and there is no RESERVED lock on the ** database file, then it either needs to be played back or deleted. */ - rc = hasHotJournal(pPager); - if( rc<0 ){ - rc = SQLITE_IOERR_NOMEM; - goto failed; + if( !isErrorReset ){ + rc = hasHotJournal(pPager, &isHotJournal); + if( rc!=SQLITE_OK ){ + goto failed; + } } - if( rc==1 || isHot ){ + if( isErrorReset || isHotJournal ){ /* Get an EXCLUSIVE lock on the database file. At this point it is ** important that a RESERVED lock is not obtained on the way to the ** EXCLUSIVE lock. If it were, another process might open the @@ -27150,26 +29649,25 @@ static int pagerSharedLock(Pager *pPager){ ** OsTruncate() call used in exclusive-access mode also requires ** a read/write file handle. */ - if( !isHot && pPager->journalOpen==0 ){ - int res = sqlite3OsAccess(pVfs,pPager->zJournal,SQLITE_ACCESS_EXISTS); - if( res==1 ){ - int fout = 0; - int f = SQLITE_OPEN_READWRITE|SQLITE_OPEN_MAIN_JOURNAL; - assert( !pPager->tempFile ); - rc = sqlite3OsOpen(pVfs, pPager->zJournal, pPager->jfd, f, &fout); - assert( rc!=SQLITE_OK || pPager->jfd->pMethods ); - if( fout&SQLITE_OPEN_READONLY ){ + if( !isErrorReset && pPager->journalOpen==0 ){ + int res; + rc = sqlite3OsAccess(pVfs,pPager->zJournal,SQLITE_ACCESS_EXISTS,&res); + if( rc==SQLITE_OK ){ + if( res ){ + int fout = 0; + int f = SQLITE_OPEN_READWRITE|SQLITE_OPEN_MAIN_JOURNAL; + assert( !pPager->tempFile ); + rc = sqlite3OsOpen(pVfs, pPager->zJournal, pPager->jfd, f, &fout); + assert( rc!=SQLITE_OK || pPager->jfd->pMethods ); + if( fout&SQLITE_OPEN_READONLY ){ + rc = SQLITE_BUSY; + sqlite3OsClose(pPager->jfd); + } + }else{ + /* If the journal does not exist, that means some other process + ** has already rolled it back */ rc = SQLITE_BUSY; - sqlite3OsClose(pPager->jfd); } - }else if( res==0 ){ - /* If the journal does not exist, that means some other process - ** has already rolled it back */ - rc = SQLITE_BUSY; - }else{ - /* If sqlite3OsAccess() returns a negative value, that means it - ** failed a memory allocation */ - rc = SQLITE_IOERR_NOMEM; } } if( rc!=SQLITE_OK ){ @@ -27217,7 +29715,7 @@ static int pagerSharedLock(Pager *pPager){ ** it can be neglected. */ char dbFileVers[sizeof(pPager->dbFileVers)]; - sqlite3PagerPagecount(pPager); + sqlite3PagerPagecount(pPager, 0); if( pPager->errCode ){ rc = pPager->errCode; @@ -27309,9 +29807,9 @@ static int pagerAllocatePage(Pager *pPager, PgHdr **ppPg){ pagerLeave(pPager); nByteHdr = sizeof(*pPg) + sizeof(u32) + pPager->nExtra + MEMDB*sizeof(PgHistory); - pPg = sqlite3_malloc( nByteHdr ); + pPg = sqlite3Malloc( nByteHdr ); if( pPg ){ - pData = sqlite3_malloc( pPager->pageSize ); + pData = sqlite3PageMalloc( pPager->pageSize ); if( pData==0 ){ sqlite3_free(pPg); pPg = 0; @@ -27326,6 +29824,11 @@ static int pagerAllocatePage(Pager *pPager, PgHdr **ppPg){ pPg->pData = pData; pPg->pPager = pPager; pPg->pNextAll = pPager->pAll; +#ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT + if( pPg->pNextAll ){ + pPg->pNextAll->pPrevAll = pPg; + } +#endif pPager->pAll = pPg; pPager->nPage++; }else{ @@ -27453,9 +29956,8 @@ static int pagerAcquire( if( pPager->nExtra>0 ){ memset(PGHDR_TO_EXTRA(pPg, pPager), 0, pPager->nExtra); } - nMax = sqlite3PagerPagecount(pPager); - if( pPager->errCode ){ - rc = pPager->errCode; + rc = sqlite3PagerPagecount(pPager, &nMax); + if( rc!=SQLITE_OK ){ sqlite3PagerUnref(pPg); return rc; } @@ -27613,7 +30115,7 @@ static int pager_open_journal(Pager *pPager){ assert( pPager->state>=PAGER_RESERVED ); assert( pPager->useJournal ); assert( pPager->pInJournal==0 ); - sqlite3PagerPagecount(pPager); + sqlite3PagerPagecount(pPager, 0); pagerLeave(pPager); pPager->pInJournal = sqlite3BitvecCreate(pPager->dbSize); pagerEnter(pPager); @@ -27743,7 +30245,7 @@ SQLITE_PRIVATE int sqlite3PagerBegin(DbPage *pPg, int exFlag){ assert( pPager->nRec==0 ); assert( pPager->origDbSize==0 ); assert( pPager->pInJournal==0 ); - sqlite3PagerPagecount(pPager); + sqlite3PagerPagecount(pPager, 0); pagerLeave(pPager); pPager->pInJournal = sqlite3BitvecCreate( pPager->dbSize ); pagerEnter(pPager); @@ -27886,7 +30388,7 @@ static int pager_write(PgHdr *pPg){ PgHistory *pHist = PGHDR_TO_HIST(pPg, pPager); PAGERTRACE3("JOURNAL %d page %d\n", PAGERID(pPager), pPg->pgno); assert( pHist->pOrig==0 ); - pHist->pOrig = sqlite3_malloc( pPager->pageSize ); + pHist->pOrig = sqlite3PageMalloc( pPager->pageSize ); if( !pHist->pOrig ){ return SQLITE_NOMEM; } @@ -27956,7 +30458,7 @@ static int pager_write(PgHdr *pPg){ if( MEMDB ){ PgHistory *pHist = PGHDR_TO_HIST(pPg, pPager); assert( pHist->pStmt==0 ); - pHist->pStmt = sqlite3_malloc( pPager->pageSize ); + pHist->pStmt = sqlite3PageMalloc( pPager->pageSize ); if( pHist->pStmt ){ memcpy(pHist->pStmt, PGHDR_TO_DATA(pPg), pPager->pageSize); } @@ -28029,7 +30531,7 @@ SQLITE_PRIVATE int sqlite3PagerWrite(DbPage *pDbPage){ */ pg1 = ((pPg->pgno-1) & ~(nPagePerSector-1)) + 1; - nPageCount = sqlite3PagerPagecount(pPager); + sqlite3PagerPagecount(pPager, (int *)&nPageCount); if( pPg->pgno>nPageCount ){ nPage = (pPg->pgno - pg1)+1; }else if( (pg1+nPagePerSector-1)>nPageCount ){ @@ -28188,8 +30690,12 @@ SQLITE_PRIVATE void sqlite3PagerDontRollback(DbPage *pPg){ ** has not been previously called during the same transaction. ** And if DontWrite() has previously been called, the following ** conditions must be met. + ** + ** (Later:) Not true. If the database is corrupted by having duplicate + ** pages on the freelist (ex: corrupt9.test) then the following is not + ** necessarily true: */ - assert( !pPg->inJournal && (int)pPg->pgno <= pPager->origDbSize ); + /* assert( !pPg->inJournal && (int)pPg->pgno <= pPager->origDbSize ); */ assert( pPager->pInJournal!=0 ); sqlite3BitvecSet(pPager->pInJournal, pPg->pgno); @@ -28214,6 +30720,9 @@ static int pager_incr_changecounter(Pager *pPager, int isDirect){ u32 change_counter; int rc = SQLITE_OK; +#ifndef SQLITE_ENABLE_ATOMIC_WRITE + assert( isDirect==0 ); /* isDirect is only true for atomic writes */ +#endif if( !pPager->changeCountDone ){ /* Open page 1 of the file for writing. */ rc = sqlite3PagerGet(pPager, 1, &pPgHdr); @@ -28232,10 +30741,12 @@ static int pager_incr_changecounter(Pager *pPager, int isDirect){ change_counter++; put32bits(((char*)PGHDR_TO_DATA(pPgHdr))+24, change_counter); +#ifdef SQLITE_ENABLE_ATOMIC_WRITE if( isDirect && pPager->fd->pMethods ){ const void *zBuf = PGHDR_TO_DATA(pPgHdr); rc = sqlite3OsWrite(pPager->fd, zBuf, pPager->pageSize, 0); } +#endif /* Release the page reference. */ sqlite3PagerUnref(pPgHdr); @@ -28285,6 +30796,10 @@ SQLITE_PRIVATE int sqlite3PagerCommitPhaseOne( ){ int rc = SQLITE_OK; + if( pPager->errCode ){ + return pPager->errCode; + } + /* If no changes have been made, we can leave the transaction early. */ if( pPager->dbModified==0 && @@ -28355,28 +30870,30 @@ SQLITE_PRIVATE int sqlite3PagerCommitPhaseOne( if( !pPager->setMaster ){ rc = pager_incr_changecounter(pPager, 0); if( rc!=SQLITE_OK ) goto sync_exit; + if( pPager->journalMode!=PAGER_JOURNALMODE_OFF ){ #ifndef SQLITE_OMIT_AUTOVACUUM - if( nTrunc!=0 ){ - /* If this transaction has made the database smaller, then all pages - ** being discarded by the truncation must be written to the journal - ** file. - */ - Pgno i; - int iSkip = PAGER_MJ_PGNO(pPager); - for( i=nTrunc+1; i<=pPager->origDbSize; i++ ){ - if( !sqlite3BitvecTest(pPager->pInJournal, i) && i!=iSkip ){ - rc = sqlite3PagerGet(pPager, i, &pPg); - if( rc!=SQLITE_OK ) goto sync_exit; - rc = sqlite3PagerWrite(pPg); - sqlite3PagerUnref(pPg); - if( rc!=SQLITE_OK ) goto sync_exit; - } - } - } + if( nTrunc!=0 ){ + /* If this transaction has made the database smaller, then all pages + ** being discarded by the truncation must be written to the journal + ** file. + */ + Pgno i; + int iSkip = PAGER_MJ_PGNO(pPager); + for( i=nTrunc+1; i<=pPager->origDbSize; i++ ){ + if( !sqlite3BitvecTest(pPager->pInJournal, i) && i!=iSkip ){ + rc = sqlite3PagerGet(pPager, i, &pPg); + if( rc!=SQLITE_OK ) goto sync_exit; + rc = sqlite3PagerWrite(pPg); + sqlite3PagerUnref(pPg); + if( rc!=SQLITE_OK ) goto sync_exit; + } + } + } #endif - rc = writeMasterJournal(pPager, zMaster); - if( rc!=SQLITE_OK ) goto sync_exit; - rc = syncJournal(pPager); + rc = writeMasterJournal(pPager, zMaster); + if( rc!=SQLITE_OK ) goto sync_exit; + rc = syncJournal(pPager); + } } if( rc!=SQLITE_OK ) goto sync_exit; @@ -28607,6 +31124,9 @@ SQLITE_PRIVATE int *sqlite3PagerStats(Pager *pPager){ a[10] = pPager->nWrite; return a; } +SQLITE_PRIVATE int sqlite3PagerIsMemdb(Pager *pPager){ + return MEMDB; +} #endif /* @@ -28645,8 +31165,7 @@ static int pagerStmtBegin(Pager *pPager){ pPager->stmtHdrOff = 0; pPager->stmtCksum = pPager->cksumInit; if( !pPager->stmtOpen ){ - rc = sqlite3PagerOpentemp(pPager->pVfs, pPager->stfd, pPager->zStmtJrnl, - SQLITE_OPEN_SUBJOURNAL); + rc = sqlite3PagerOpentemp(pPager, pPager->stfd, SQLITE_OPEN_SUBJOURNAL); if( rc ){ goto stmt_begin_failed; } @@ -28690,7 +31209,7 @@ SQLITE_PRIVATE int sqlite3PagerStmtCommit(Pager *pPager){ assert( pHist->inStmt ); pHist->inStmt = 0; pHist->pPrevStmt = pHist->pNextStmt = 0; - sqlite3_free(pHist->pStmt); + sqlite3PageFree(pHist->pStmt); pHist->pStmt = 0; } } @@ -28718,7 +31237,7 @@ SQLITE_PRIVATE int sqlite3PagerStmtRollback(Pager *pPager){ pHist = PGHDR_TO_HIST(pPg, pPager); if( pHist->pStmt ){ memcpy(PGHDR_TO_DATA(pPg), pHist->pStmt, pPager->pageSize); - sqlite3_free(pHist->pStmt); + sqlite3PageFree(pHist->pStmt); pHist->pStmt = 0; } } @@ -28813,8 +31332,13 @@ SQLITE_PRIVATE void sqlite3PagerSetCodec( ** required that a statement transaction was not active, but this restriction ** has been removed (CREATE INDEX needs to move a page when a statement ** transaction is active). +** +** If the fourth argument, isCommit, is non-zero, then this page is being +** moved as part of a database reorganization just before the transaction +** is being committed. In this case, it is guaranteed that the database page +** pPg refers to will not be written to again within this transaction. */ -SQLITE_PRIVATE int sqlite3PagerMovepage(Pager *pPager, DbPage *pPg, Pgno pgno){ +SQLITE_PRIVATE int sqlite3PagerMovepage(Pager *pPager, DbPage *pPg, Pgno pgno, int isCommit){ PgHdr *pPgOld; /* The page being overwritten. */ int h; Pgno needSyncPgno = 0; @@ -28827,7 +31351,15 @@ SQLITE_PRIVATE int sqlite3PagerMovepage(Pager *pPager, DbPage *pPg, Pgno pgno){ IOTRACE(("MOVE %p %d %d\n", pPager, pPg->pgno, pgno)) pager_get_content(pPg); - if( pPg->needSync ){ + + /* If the journal needs to be sync()ed before page pPg->pgno can + ** be written to, store pPg->pgno in local variable needSyncPgno. + ** + ** If the isCommit flag is set, there is no need to remember that + ** the journal needs to be sync()ed before database page pPg->pgno + ** can be written to. The caller has already promised not to write to it. + */ + if( pPg->needSync && !isCommit ){ needSyncPgno = pPg->pgno; assert( pPg->inJournal || (int)pgno>pPager->origDbSize ); assert( pPg->dirty ); @@ -28874,8 +31406,9 @@ SQLITE_PRIVATE int sqlite3PagerMovepage(Pager *pPager, DbPage *pPg, Pgno pgno){ /* If needSyncPgno is non-zero, then the journal file needs to be ** sync()ed before any data is written to database file page needSyncPgno. ** Currently, no such page exists in the page-cache and the - ** Pager.pInJournal bit has been set. This needs to be remedied by loading - ** the page into the pager-cache and setting the PgHdr.needSync flag. + ** "is journaled" bitvec flag has been set. This needs to be remedied by + ** loading the page into the pager-cache and setting the PgHdr.needSync + ** flag. ** ** If the attempt to load the page into the page-cache fails, (due ** to a malloc() or IO failure), clear the bit in the pInJournal[] @@ -28971,19 +31504,15 @@ SQLITE_PRIVATE int sqlite3PagerJournalMode(Pager *pPager, int eMode){ return (int)pPager->journalMode; } -#ifdef SQLITE_TEST /* -** Print a listing of all referenced pages and their ref count. +** Get/set the size-limit used for persistent journal files. */ -SQLITE_PRIVATE void sqlite3PagerRefdump(Pager *pPager){ - PgHdr *pPg; - for(pPg=pPager->pAll; pPg; pPg=pPg->pNextAll){ - if( pPg->nRef<=0 ) continue; - sqlite3DebugPrintf("PAGE %3d addr=%p nRef=%d\n", - pPg->pgno, PGHDR_TO_DATA(pPg), pPg->nRef); +SQLITE_PRIVATE i64 sqlite3PagerJournalSizeLimit(Pager *pPager, i64 iLimit){ + if( iLimit>=-1 ){ + pPager->journalSizeLimit = iLimit; } + return pPager->journalSizeLimit; } -#endif #endif /* SQLITE_OMIT_DISKIO */ @@ -29282,8 +31811,6 @@ struct MemPage { u8 nOverflow; /* Number of overflow cell bodies in aCell[] */ u8 intKey; /* True if intkey flag is set */ u8 leaf; /* True if leaf flag is set */ - u8 zeroData; /* True if table stores keys only */ - u8 leafData; /* True if tables stores data on leaves only */ u8 hasData; /* True if this page stores data */ u8 hdrOffset; /* 100 for page 1. 0 otherwise */ u8 childPtrSize; /* 0 if leaf==1. 4 if leaf==0 */ @@ -29293,6 +31820,7 @@ struct MemPage { u16 idxParent; /* Index in parent of this node */ u16 nFree; /* Number of free bytes on the page */ u16 nCell; /* Number of cells on this page, local and ovfl */ + u16 maskPage; /* Mask for page offset */ struct _OvflCell { /* Cells that will not fit on aData[] */ u8 *pCell; /* Pointers to the body of the overflow cell */ u16 idx; /* Insert this cell before idx-th non-overflow cell */ @@ -29378,9 +31906,6 @@ struct BtShared { MemPage *pPage1; /* First page of the database */ u8 inStmt; /* True if we are in a statement subtransaction */ u8 readOnly; /* True if the underlying file is readonly */ - u8 maxEmbedFrac; /* Maximum payload as % of total page size */ - u8 minEmbedFrac; /* Minimum payload as % of total page size */ - u8 minLeafFrac; /* Minimum leaf payload as % of total page size */ u8 pageSizeFixed; /* True if the page size can no longer be changed */ #ifndef SQLITE_OMIT_AUTOVACUUM u8 autoVacuum; /* True if auto-vacuum is enabled */ @@ -29476,7 +32001,7 @@ struct BtCursor { ** The table that this cursor was opened on still exists, but has been ** modified since the cursor was last used. The cursor position is saved ** in variables BtCursor.pKey and BtCursor.nKey. When a cursor is in -** this state, restoreOrClearCursorPosition() can be called to attempt to +** this state, restoreCursorPosition() can be called to attempt to ** seek the cursor to the saved position. ** ** CURSOR_FAULT: @@ -29491,17 +32016,6 @@ struct BtCursor { #define CURSOR_REQUIRESEEK 2 #define CURSOR_FAULT 3 -/* -** The TRACE macro will print high-level status information about the -** btree operation when the global variable sqlite3BtreeTrace is -** enabled. -*/ -#if SQLITE_TEST -# define TRACE(X) if( sqlite3BtreeTrace ){ printf X; fflush(stdout); } -#else -# define TRACE(X) -#endif - /* The database page the PENDING_BYTE occupies. This page is never used. ** TODO: This macro is very similary to PAGER_MJ_PGNO() in pager.c. They ** should possibly be consolidated (presumably in pager.h). @@ -29549,7 +32063,7 @@ struct BtLock { ** this test. */ #define PTRMAP_PAGENO(pBt, pgno) ptrmapPageno(pBt, pgno) -#define PTRMAP_PTROFFSET(pBt, pgno) (5*(pgno-ptrmapPageno(pBt, pgno)-1)) +#define PTRMAP_PTROFFSET(pgptrmap, pgno) (5*(pgno-pgptrmap-1)) #define PTRMAP_ISPAGE(pBt, pgno) (PTRMAP_PAGENO((pBt),(pgno))==(pgno)) /* @@ -29622,8 +32136,9 @@ struct IntegrityCk { int nPage; /* Number of pages in the database */ int *anRef; /* Number of times each page is referenced */ int mxErr; /* Stop accumulating errors when this reaches zero */ - char *zErrMsg; /* An error message. NULL if no errors seen. */ int nErr; /* Number of messages written to zErrMsg so far */ + int mallocFailed; /* A memory allocation error has occurred */ + StrAccum errMsg; /* Accumulate the error message text here */ }; /* @@ -29641,10 +32156,7 @@ SQLITE_PRIVATE int sqlite3BtreeGetPage(BtShared*, Pgno, MemPage**, int); SQLITE_PRIVATE int sqlite3BtreeInitPage(MemPage *pPage, MemPage *pParent); SQLITE_PRIVATE void sqlite3BtreeParseCellPtr(MemPage*, u8*, CellInfo*); SQLITE_PRIVATE void sqlite3BtreeParseCell(MemPage*, int, CellInfo*); -#ifdef SQLITE_TEST -SQLITE_PRIVATE u8 *sqlite3BtreeFindCell(MemPage *pPage, int iCell); -#endif -SQLITE_PRIVATE int sqlite3BtreeRestoreOrClearCursorPosition(BtCursor *pCur); +SQLITE_PRIVATE int sqlite3BtreeRestoreCursorPosition(BtCursor *pCur); SQLITE_PRIVATE void sqlite3BtreeGetTempCursor(BtCursor *pCur, BtCursor *pTempCur); SQLITE_PRIVATE void sqlite3BtreeReleaseTempCursor(BtCursor *pCur); SQLITE_PRIVATE int sqlite3BtreeIsRootPage(MemPage *pPage); @@ -29860,11 +32372,11 @@ SQLITE_PRIVATE int sqlite3BtreeHoldsAllMutexes(sqlite3 *db){ #endif /* NDEBUG */ /* -** Potentially dd a new Btree pointer to a BtreeMutexArray. -** Really only add the Btree if it can possibly be shared with +** Add a new Btree pointer to a BtreeMutexArray. +** if the pointer can possibly be shared with ** another database connection. ** -** The Btrees are kept in sorted order by pBtree->pBt. That +** The pointers are kept in sorted order by pBtree->pBt. That ** way when we go to enter all the mutexes, we can enter them ** in order without every having to backup and retry and without ** worrying about deadlock. @@ -29980,8 +32492,11 @@ static const char zMagicHeader[] = SQLITE_FILE_HEADER; ** Set this global variable to 1 to enable tracing using the TRACE ** macro. */ -#if SQLITE_TEST +#if 0 int sqlite3BtreeTrace=0; /* True to enable tracing */ +# define TRACE(X) if(sqlite3BtreeTrace){printf X;fflush(stdout);} +#else +# define TRACE(X) #endif @@ -30021,7 +32536,7 @@ SQLITE_API int sqlite3_enable_shared_cache(int enable){ /* ** Forward declaration */ -static int checkReadLocks(Btree*,Pgno,BtCursor*); +static int checkReadLocks(Btree*, Pgno, BtCursor*, i64); #ifdef SQLITE_OMIT_SHARED_CACHE @@ -30050,6 +32565,8 @@ static int queryTableLock(Btree *p, Pgno iTab, u8 eLock){ BtLock *pIter; assert( sqlite3BtreeHoldsMutex(p) ); + assert( eLock==READ_LOCK || eLock==WRITE_LOCK ); + assert( p->db!=0 ); /* This is a no-op if the shared-cache is not enabled */ if( !p->sharable ){ @@ -30078,7 +32595,6 @@ static int queryTableLock(Btree *p, Pgno iTab, u8 eLock){ ** write-cursor does not change. */ if( - !p->db || 0==(p->db->flags&SQLITE_ReadUncommitted) || eLock==WRITE_LOCK || iTab==MASTER_ROOT @@ -30109,6 +32625,8 @@ static int lockTable(Btree *p, Pgno iTable, u8 eLock){ BtLock *pIter; assert( sqlite3BtreeHoldsMutex(p) ); + assert( eLock==READ_LOCK || eLock==WRITE_LOCK ); + assert( p->db!=0 ); /* This is a no-op if the shared-cache is not enabled */ if( !p->sharable ){ @@ -30123,7 +32641,6 @@ static int lockTable(Btree *p, Pgno iTable, u8 eLock){ ** the ReadUncommitted flag. */ if( - (p->db) && (p->db->flags&SQLITE_ReadUncommitted) && (eLock==READ_LOCK) && iTable!=MASTER_ROOT @@ -30253,7 +32770,7 @@ static int saveCursorPosition(BtCursor *pCur){ ** data. */ if( rc==SQLITE_OK && 0==pCur->pPage->intKey){ - void *pKey = sqlite3_malloc(pCur->nKey); + void *pKey = sqlite3Malloc(pCur->nKey); if( pKey ){ rc = sqlite3BtreeKey(pCur, 0, pCur->nKey, pKey); if( rc==SQLITE_OK ){ @@ -30312,25 +32829,16 @@ static void clearCursorPosition(BtCursor *pCur){ ** Restore the cursor to the position it was in (or as close to as possible) ** when saveCursorPosition() was called. Note that this call deletes the ** saved position info stored by saveCursorPosition(), so there can be -** at most one effective restoreOrClearCursorPosition() call after each +** at most one effective restoreCursorPosition() call after each ** saveCursorPosition(). -** -** If the second argument argument - doSeek - is false, then instead of -** returning the cursor to its saved position, any saved position is deleted -** and the cursor state set to CURSOR_INVALID. */ -SQLITE_PRIVATE int sqlite3BtreeRestoreOrClearCursorPosition(BtCursor *pCur){ +SQLITE_PRIVATE int sqlite3BtreeRestoreCursorPosition(BtCursor *pCur){ int rc; assert( cursorHoldsMutex(pCur) ); assert( pCur->eState>=CURSOR_REQUIRESEEK ); if( pCur->eState==CURSOR_FAULT ){ return pCur->skip; } -#ifndef SQLITE_OMIT_INCRBLOB - if( pCur->isIncrblobHandle ){ - return SQLITE_ABORT; - } -#endif pCur->eState = CURSOR_INVALID; rc = sqlite3BtreeMoveto(pCur, pCur->pKey, 0, pCur->nKey, 0, &pCur->skip); if( rc==SQLITE_OK ){ @@ -30341,11 +32849,35 @@ SQLITE_PRIVATE int sqlite3BtreeRestoreOrClearCursorPosition(BtCursor *pCur){ return rc; } -#define restoreOrClearCursorPosition(p) \ +#define restoreCursorPosition(p) \ (p->eState>=CURSOR_REQUIRESEEK ? \ - sqlite3BtreeRestoreOrClearCursorPosition(p) : \ + sqlite3BtreeRestoreCursorPosition(p) : \ SQLITE_OK) +/* +** Determine whether or not a cursor has moved from the position it +** was last placed at. Cursor can move when the row they are pointing +** at is deleted out from under them. +** +** This routine returns an error code if something goes wrong. The +** integer *pHasMoved is set to one if the cursor has moved and 0 if not. +*/ +SQLITE_PRIVATE int sqlite3BtreeCursorHasMoved(BtCursor *pCur, int *pHasMoved){ + int rc; + + rc = restoreCursorPosition(pCur); + if( rc ){ + *pHasMoved = 1; + return rc; + } + if( pCur->eState!=CURSOR_VALID || pCur->skip!=0 ){ + *pHasMoved = 1; + }else{ + *pHasMoved = 0; + } + return SQLITE_OK; +} + #ifndef SQLITE_OMIT_AUTOVACUUM /* ** Given a page number of a regular database page, return the page @@ -30391,7 +32923,7 @@ static int ptrmapPut(BtShared *pBt, Pgno key, u8 eType, Pgno parent){ if( rc!=SQLITE_OK ){ return rc; } - offset = PTRMAP_PTROFFSET(pBt, key); + offset = PTRMAP_PTROFFSET(iPtrmap, key); pPtrmap = (u8 *)sqlite3PagerGetData(pDbPage); if( eType!=pPtrmap[offset] || get4byte(&pPtrmap[offset+1])!=parent ){ @@ -30430,7 +32962,7 @@ static int ptrmapGet(BtShared *pBt, Pgno key, u8 *pEType, Pgno *pPgno){ } pPtrmap = (u8 *)sqlite3PagerGetData(pDbPage); - offset = PTRMAP_PTROFFSET(pBt, key); + offset = PTRMAP_PTROFFSET(iPtrmap, key); assert( pEType!=0 ); *pEType = pPtrmap[offset]; if( pPgno ) *pPgno = get4byte(&pPtrmap[offset+1]); @@ -30440,7 +32972,11 @@ static int ptrmapGet(BtShared *pBt, Pgno key, u8 *pEType, Pgno *pPgno){ return SQLITE_OK; } -#endif /* SQLITE_OMIT_AUTOVACUUM */ +#else /* if defined SQLITE_OMIT_AUTOVACUUM */ + #define ptrmapPut(w,x,y,z) SQLITE_OK + #define ptrmapGet(w,x,y,z) SQLITE_OK + #define ptrmapPutOvfl(y,z) SQLITE_OK +#endif /* ** Given a btree page and a cell index (0 means the first cell on @@ -30449,18 +32985,11 @@ static int ptrmapGet(BtShared *pBt, Pgno key, u8 *pEType, Pgno *pPgno){ ** ** This routine works only for pages that do not contain overflow cells. */ -#define findCell(pPage, iCell) \ - ((pPage)->aData + get2byte(&(pPage)->aData[(pPage)->cellOffset+2*(iCell)])) -#ifdef SQLITE_TEST -SQLITE_PRIVATE u8 *sqlite3BtreeFindCell(MemPage *pPage, int iCell){ - assert( iCell>=0 ); - assert( iCell<get2byte(&pPage->aData[pPage->hdrOffset+3]) ); - return findCell(pPage, iCell); -} -#endif +#define findCell(P,I) \ + ((P)->aData + ((P)->maskPage & get2byte(&(P)->aData[(P)->cellOffset+2*(I)]))) /* -** This a more complex version of sqlite3BtreeFindCell() that works for +** This a more complex version of findCell() that works for ** pages that do contain overflow cells. See insert */ static u8 *findOverflowCell(MemPage *pPage, int iCell){ @@ -30504,31 +33033,30 @@ SQLITE_PRIVATE void sqlite3BtreeParseCellPtr( assert( pPage->leaf==0 || pPage->leaf==1 ); n = pPage->childPtrSize; assert( n==4-4*pPage->leaf ); - if( pPage->hasData ){ - n += getVarint32(&pCell[n], nPayload); - }else{ - nPayload = 0; - } - pInfo->nData = nPayload; if( pPage->intKey ){ - n += getVarint(&pCell[n], (u64 *)&pInfo->nKey); + if( pPage->hasData ){ + n += getVarint32(&pCell[n], nPayload); + }else{ + nPayload = 0; + } + n += getVarint(&pCell[n], (u64*)&pInfo->nKey); + pInfo->nData = nPayload; }else{ - u32 x; - n += getVarint32(&pCell[n], x); - pInfo->nKey = x; - nPayload += x; + pInfo->nData = 0; + n += getVarint32(&pCell[n], nPayload); + pInfo->nKey = nPayload; } pInfo->nPayload = nPayload; pInfo->nHeader = n; - if( nPayload<=pPage->maxLocal ){ + if( likely(nPayload<=pPage->maxLocal) ){ /* This is the (easy) common case where the entire payload fits ** on the local page. No overflow is required. */ int nSize; /* Total size of cell content in bytes */ + nSize = nPayload + n; pInfo->nLocal = nPayload; pInfo->iOverflow = 0; - nSize = nPayload + n; - if( nSize<4 ){ + if( (nSize & ~3)==0 ){ nSize = 4; /* Minimum cell size is 4 */ } pInfo->nSize = nSize; @@ -30594,14 +33122,13 @@ static u16 cellSizePtr(MemPage *pPage, u8 *pCell){ ** for the overflow page. */ static int ptrmapPutOvflPtr(MemPage *pPage, u8 *pCell){ - if( pCell ){ - CellInfo info; - sqlite3BtreeParseCellPtr(pPage, pCell, &info); - assert( (info.nData+(pPage->intKey?0:info.nKey))==info.nPayload ); - if( (info.nData+(pPage->intKey?0:info.nKey))>info.nLocal ){ - Pgno ovfl = get4byte(&pCell[info.iOverflow]); - return ptrmapPut(pPage->pBt, ovfl, PTRMAP_OVERFLOW1, pPage->pgno); - } + CellInfo info; + assert( pCell!=0 ); + sqlite3BtreeParseCellPtr(pPage, pCell, &info); + assert( (info.nData+(pPage->intKey?0:info.nKey))==info.nPayload ); + if( (info.nData+(pPage->intKey?0:info.nKey))>info.nLocal ){ + Pgno ovfl = get4byte(&pCell[info.iOverflow]); + return ptrmapPut(pPage->pBt, ovfl, PTRMAP_OVERFLOW1, pPage->pgno); } return SQLITE_OK; } @@ -30625,7 +33152,7 @@ static int ptrmapPutOvfl(MemPage *pPage, int iCell){ ** big FreeBlk that occurs in between the header and cell ** pointer array and the cell content area. */ -static int defragmentPage(MemPage *pPage){ +static void defragmentPage(MemPage *pPage){ int i; /* Loop counter */ int pc; /* Address of a i-th cell */ int addr; /* Offset of first byte after cell pointer array */ @@ -30670,15 +33197,14 @@ static int defragmentPage(MemPage *pPage){ data[hdr+7] = 0; addr = cellOffset+2*nCell; memset(&data[addr], 0, brk-addr); - return SQLITE_OK; } /* ** Allocate nByte bytes of space on a page. ** ** Return the index into pPage->aData[] of the first byte of -** the new allocation. Or return 0 if there is not enough free -** space on the page to satisfy the allocation request. +** the new allocation. The caller guarantees that there is enough +** space. This routine will never fail. ** ** If the page contains nBytes of free space but does not contain ** nBytes of contiguous free space, then this routine automatically @@ -30698,8 +33224,9 @@ static int allocateSpace(MemPage *pPage, int nByte){ assert( sqlite3PagerIswriteable(pPage->pDbPage) ); assert( pPage->pBt ); assert( sqlite3_mutex_held(pPage->pBt->mutex) ); - if( nByte<4 ) nByte = 4; - if( pPage->nFree<nByte || pPage->nOverflow>0 ) return 0; + assert( nByte>=0 ); /* Minimum cell size is 4 */ + assert( pPage->nFree>=nByte ); + assert( pPage->nOverflow==0 ); pPage->nFree -= nByte; hdr = pPage->hdrOffset; @@ -30731,7 +33258,7 @@ static int allocateSpace(MemPage *pPage, int nByte){ nCell = get2byte(&data[hdr+3]); cellOffset = pPage->cellOffset; if( nFrag>=60 || cellOffset + 2*nCell > top - nByte ){ - if( defragmentPage(pPage) ) return 0; + defragmentPage(pPage); top = get2byte(&data[hdr+5]); } top -= nByte; @@ -30757,7 +33284,7 @@ static void freeSpace(MemPage *pPage, int start, int size){ assert( start>=pPage->hdrOffset+6+(pPage->leaf?0:4) ); assert( (start + size)<=pPage->pBt->usableSize ); assert( sqlite3_mutex_held(pPage->pBt->mutex) ); - if( size<4 ) size = 4; + assert( size>=0 ); /* Minimum cell size is 4 */ #ifdef SQLITE_SECURE_DELETE /* Overwrite deleted information with zeros when the SECURE_DELETE @@ -30812,27 +33339,38 @@ static void freeSpace(MemPage *pPage, int start, int size){ /* ** Decode the flags byte (the first byte of the header) for a page ** and initialize fields of the MemPage structure accordingly. +** +** Only the following combinations are supported. Anything different +** indicates a corrupt database files: +** +** PTF_ZERODATA +** PTF_ZERODATA | PTF_LEAF +** PTF_LEAFDATA | PTF_INTKEY +** PTF_LEAFDATA | PTF_INTKEY | PTF_LEAF */ -static void decodeFlags(MemPage *pPage, int flagByte){ +static int decodeFlags(MemPage *pPage, int flagByte){ BtShared *pBt; /* A copy of pPage->pBt */ assert( pPage->hdrOffset==(pPage->pgno==1 ? 100 : 0) ); assert( sqlite3_mutex_held(pPage->pBt->mutex) ); - pPage->intKey = (flagByte & (PTF_INTKEY|PTF_LEAFDATA))!=0; - pPage->zeroData = (flagByte & PTF_ZERODATA)!=0; - pPage->leaf = (flagByte & PTF_LEAF)!=0; - pPage->childPtrSize = 4*(pPage->leaf==0); + pPage->leaf = flagByte>>3; assert( PTF_LEAF == 1<<3 ); + flagByte &= ~PTF_LEAF; + pPage->childPtrSize = 4-4*pPage->leaf; pBt = pPage->pBt; - if( flagByte & PTF_LEAFDATA ){ - pPage->leafData = 1; + if( flagByte==(PTF_LEAFDATA | PTF_INTKEY) ){ + pPage->intKey = 1; + pPage->hasData = pPage->leaf; pPage->maxLocal = pBt->maxLeaf; pPage->minLocal = pBt->minLeaf; - }else{ - pPage->leafData = 0; + }else if( flagByte==PTF_ZERODATA ){ + pPage->intKey = 0; + pPage->hasData = 0; pPage->maxLocal = pBt->maxLocal; pPage->minLocal = pBt->minLocal; + }else{ + return SQLITE_CORRUPT_BKPT; } - pPage->hasData = !(pPage->zeroData || (!pPage->leaf && pPage->leafData)); + return SQLITE_OK; } /* @@ -30879,7 +33417,9 @@ SQLITE_PRIVATE int sqlite3BtreeInitPage( } hdr = pPage->hdrOffset; data = pPage->aData; - decodeFlags(pPage, data[hdr]); + if( decodeFlags(pPage, data[hdr]) ) return SQLITE_CORRUPT_BKPT; + assert( pBt->pageSize>=512 && pBt->pageSize<=32768 ); + pPage->maskPage = pBt->pageSize - 1; pPage->nOverflow = 0; pPage->idxShift = 0; usableSize = pBt->usableSize; @@ -30919,6 +33459,26 @@ SQLITE_PRIVATE int sqlite3BtreeInitPage( return SQLITE_CORRUPT_BKPT; } +#if 0 + /* Check that all the offsets in the cell offset array are within range. + ** + ** Omitting this consistency check and using the pPage->maskPage mask + ** to prevent overrunning the page buffer in findCell() results in a + ** 2.5% performance gain. + */ + { + u8 *pOff; /* Iterator used to check all cell offsets are in range */ + u8 *pEnd; /* Pointer to end of cell offset array */ + u8 mask; /* Mask of bits that must be zero in MSB of cell offsets */ + mask = ~(((u8)(pBt->pageSize>>8))-1); + pEnd = &data[cellOffset + pPage->nCell*2]; + for(pOff=&data[cellOffset]; pOff!=pEnd && !((*pOff)&mask); pOff+=2); + if( pOff!=pEnd ){ + return SQLITE_CORRUPT_BKPT; + } + } +#endif + pPage->isInit = 1; return SQLITE_OK; } @@ -30938,7 +33498,7 @@ static void zeroPage(MemPage *pPage, int flags){ assert( sqlite3PagerGetData(pPage->pDbPage) == data ); assert( sqlite3PagerIswriteable(pPage->pDbPage) ); assert( sqlite3_mutex_held(pBt->mutex) ); - memset(&data[hdr], 0, pBt->usableSize - hdr); + /*memset(&data[hdr], 0, pBt->usableSize - hdr);*/ data[hdr] = flags; first = hdr + 8 + 4*((flags&PTF_LEAF)==0); memset(&data[hdr+1], 0, 4); @@ -30949,6 +33509,8 @@ static void zeroPage(MemPage *pPage, int flags){ pPage->hdrOffset = hdr; pPage->cellOffset = first; pPage->nOverflow = 0; + assert( pBt->pageSize>=512 && pBt->pageSize<=32768 ); + pPage->maskPage = pBt->pageSize - 1; pPage->idxShift = 0; pPage->nCell = 0; pPage->isInit = 1; @@ -31130,25 +33692,22 @@ SQLITE_PRIVATE int sqlite3BtreeOpen( ** If this Btree is a candidate for shared cache, try to find an ** existing BtShared object that we can share with */ - if( (flags & BTREE_PRIVATE)==0 - && isMemdb==0 + if( isMemdb==0 && (db->flags & SQLITE_Vtab)==0 && zFilename && zFilename[0] ){ if( sqlite3SharedCacheEnabled ){ int nFullPathname = pVfs->mxPathname+1; - char *zFullPathname = (char *)sqlite3_malloc(nFullPathname); + char *zFullPathname = sqlite3Malloc(nFullPathname); sqlite3_mutex *mutexShared; p->sharable = 1; - if( db ){ - db->flags |= SQLITE_SharedCache; - } + db->flags |= SQLITE_SharedCache; if( !zFullPathname ){ sqlite3_free(p); return SQLITE_NOMEM; } sqlite3OsFullPathname(pVfs, zFilename, nFullPathname, zFullPathname); - mutexShared = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MASTER); + mutexShared = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER); sqlite3_mutex_enter(mutexShared); for(pBt=sqlite3SharedCacheList; pBt; pBt=pBt->pNext){ assert( pBt->nRef>0 ); @@ -31214,9 +33773,6 @@ SQLITE_PRIVATE int sqlite3BtreeOpen( || ((pBt->pageSize-1)&pBt->pageSize)!=0 ){ pBt->pageSize = 0; sqlite3PagerSetPagesize(pBt->pPager, &pBt->pageSize); - pBt->maxEmbedFrac = 64; /* 25% */ - pBt->minEmbedFrac = 32; /* 12.5% */ - pBt->minLeafFrac = 32; /* 12.5% */ #ifndef SQLITE_OMIT_AUTOVACUUM /* If the magic name ":memory:" will create an in-memory database, then ** leave the autoVacuum mode at 0 (do not auto-vacuum), even if @@ -31232,9 +33788,6 @@ SQLITE_PRIVATE int sqlite3BtreeOpen( nReserve = 0; }else{ nReserve = zDbHeader[20]; - pBt->maxEmbedFrac = zDbHeader[21]; - pBt->minEmbedFrac = zDbHeader[22]; - pBt->minLeafFrac = zDbHeader[23]; pBt->pageSizeFixed = 1; #ifndef SQLITE_OMIT_AUTOVACUUM pBt->autoVacuum = (get4byte(&zDbHeader[36 + 4*4])?1:0); @@ -31251,9 +33804,9 @@ SQLITE_PRIVATE int sqlite3BtreeOpen( if( p->sharable ){ sqlite3_mutex *mutexShared; pBt->nRef = 1; - mutexShared = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MASTER); - if( SQLITE_THREADSAFE ){ - pBt->mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_FAST); + mutexShared = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER); + if( SQLITE_THREADSAFE && sqlite3Config.bCoreMutex ){ + pBt->mutex = sqlite3MutexAlloc(SQLITE_MUTEX_FAST); if( pBt->mutex==0 ){ rc = SQLITE_NOMEM; db->mallocFailed = 0; @@ -31326,7 +33879,7 @@ static int removeFromSharingList(BtShared *pBt){ int removed = 0; assert( sqlite3_mutex_notheld(pBt->mutex) ); - pMaster = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MASTER); + pMaster = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER); sqlite3_mutex_enter(pMaster); pBt->nRef--; if( pBt->nRef<=0 ){ @@ -31334,10 +33887,10 @@ static int removeFromSharingList(BtShared *pBt){ sqlite3SharedCacheList = pBt->pNext; }else{ pList = sqlite3SharedCacheList; - while( pList && pList->pNext!=pBt ){ + while( ALWAYS(pList) && pList->pNext!=pBt ){ pList=pList->pNext; } - if( pList ){ + if( ALWAYS(pList) ){ pList->pNext = pBt->pNext; } } @@ -31354,6 +33907,24 @@ static int removeFromSharingList(BtShared *pBt){ } /* +** Make sure pBt->pTmpSpace points to an allocation of +** MX_CELL_SIZE(pBt) bytes. +*/ +static void allocateTempSpace(BtShared *pBt){ + if( !pBt->pTmpSpace ){ + pBt->pTmpSpace = sqlite3PageMalloc( pBt->pageSize ); + } +} + +/* +** Free the pBt->pTmpSpace allocation +*/ +static void freeTempSpace(BtShared *pBt){ + sqlite3PageFree( pBt->pTmpSpace); + pBt->pTmpSpace = 0; +} + +/* ** Close an open database and invalidate all cursors. */ SQLITE_PRIVATE int sqlite3BtreeClose(Btree *p){ @@ -31397,7 +33968,7 @@ SQLITE_PRIVATE int sqlite3BtreeClose(Btree *p){ pBt->xFreeSchema(pBt->pSchema); } sqlite3_free(pBt->pSchema); - sqlite3_free(pBt->pTmpSpace); + freeTempSpace(pBt); sqlite3_free(pBt); } @@ -31502,8 +34073,7 @@ SQLITE_PRIVATE int sqlite3BtreeSetPageSize(Btree *p, int pageSize, int nReserve) assert( (pageSize & 7)==0 ); assert( !pBt->pPage1 && !pBt->pCursor ); pBt->pageSize = pageSize; - sqlite3_free(pBt->pTmpSpace); - pBt->pTmpSpace = 0; + freeTempSpace(pBt); rc = sqlite3PagerSetPagesize(pBt->pPager, &pBt->pageSize); } pBt->usableSize = pBt->pageSize - nReserve; @@ -31607,15 +34177,14 @@ static int lockBtree(BtShared *pBt){ /* Do some checking to help insure the file we opened really is ** a valid database file. */ - rc = SQLITE_NOTADB; - nPage = sqlite3PagerPagecount(pBt->pPager); - if( nPage<0 ){ - rc = SQLITE_IOERR; + rc = sqlite3PagerPagecount(pBt->pPager, &nPage); + if( rc!=SQLITE_OK ){ goto page1_init_failed; }else if( nPage>0 ){ int pageSize; int usableSize; u8 *page1 = pPage1->aData; + rc = SQLITE_NOTADB; if( memcmp(page1, zMagicHeader, 16)!=0 ){ goto page1_init_failed; } @@ -31625,6 +34194,15 @@ static int lockBtree(BtShared *pBt){ if( page1[19]>1 ){ goto page1_init_failed; } + + /* The maximum embedded fraction must be exactly 25%. And the minimum + ** embedded fraction must be 12.5% for both leaf-data and non-leaf-data. + ** The original design allowed these amounts to vary, but as of + ** version 3.6.0, we require them to be fixed. + */ + if( memcmp(&page1[21], "\100\040\040",3)!=0 ){ + goto page1_init_failed; + } pageSize = get2byte(&page1[16]); if( ((pageSize-1)&pageSize)!=0 || pageSize<512 || (SQLITE_MAX_PAGE_SIZE<32768 && pageSize>SQLITE_MAX_PAGE_SIZE) @@ -31643,8 +34221,7 @@ static int lockBtree(BtShared *pBt){ releasePage(pPage1); pBt->usableSize = usableSize; pBt->pageSize = pageSize; - sqlite3_free(pBt->pTmpSpace); - pBt->pTmpSpace = 0; + freeTempSpace(pBt); sqlite3PagerSetPagesize(pBt->pPager, &pBt->pageSize); return SQLITE_OK; } @@ -31653,9 +34230,6 @@ static int lockBtree(BtShared *pBt){ } pBt->pageSize = pageSize; pBt->usableSize = usableSize; - pBt->maxEmbedFrac = page1[21]; - pBt->minEmbedFrac = page1[22]; - pBt->minLeafFrac = page1[23]; #ifndef SQLITE_OMIT_AUTOVACUUM pBt->autoVacuum = (get4byte(&page1[36 + 4*4])?1:0); pBt->incrVacuum = (get4byte(&page1[36 + 7*4])?1:0); @@ -31675,13 +34249,10 @@ static int lockBtree(BtShared *pBt){ ** 17 bytes long, 0 to N bytes of payload, and an optional 4 byte overflow ** page pointer. */ - pBt->maxLocal = (pBt->usableSize-12)*pBt->maxEmbedFrac/255 - 23; - pBt->minLocal = (pBt->usableSize-12)*pBt->minEmbedFrac/255 - 23; + pBt->maxLocal = (pBt->usableSize-12)*64/255 - 23; + pBt->minLocal = (pBt->usableSize-12)*32/255 - 23; pBt->maxLeaf = pBt->usableSize - 35; - pBt->minLeaf = (pBt->usableSize-12)*pBt->minLeafFrac/255 - 23; - if( pBt->minLocal>pBt->maxLocal || pBt->maxLocal<0 ){ - goto page1_init_failed; - } + pBt->minLeaf = (pBt->usableSize-12)*32/255 - 23; assert( pBt->maxLeaf + 23 <= MX_CELL_SIZE(pBt) ); pBt->pPage1 = pPage1; return SQLITE_OK; @@ -31753,9 +34324,13 @@ static int newDatabase(BtShared *pBt){ MemPage *pP1; unsigned char *data; int rc; + int nPage; assert( sqlite3_mutex_held(pBt->mutex) ); - if( sqlite3PagerPagecount(pBt->pPager)>0 ) return SQLITE_OK; + rc = sqlite3PagerPagecount(pBt->pPager, &nPage); + if( rc!=SQLITE_OK || nPage>0 ){ + return rc; + } pP1 = pBt->pPage1; assert( pP1!=0 ); data = pP1->aData; @@ -31767,9 +34342,9 @@ static int newDatabase(BtShared *pBt){ data[18] = 1; data[19] = 1; data[20] = pBt->pageSize - pBt->usableSize; - data[21] = pBt->maxEmbedFrac; - data[22] = pBt->minEmbedFrac; - data[23] = pBt->minLeafFrac; + data[21] = 64; + data[22] = 32; + data[23] = 32; memset(&data[24], 0, 100-24); zeroPage(pP1, PTF_INTKEY|PTF_LEAF|PTF_LEAFDATA ); pBt->pageSizeFixed = 1; @@ -31909,6 +34484,18 @@ trans_begun: return rc; } +/* +** Return the size of the database file in pages. Or return -1 if +** there is any kind of error. +*/ +static int pagerPagecount(Pager *pPager){ + int rc; + int nPage; + rc = sqlite3PagerPagecount(pPager, &nPage); + return (rc==SQLITE_OK?nPage:-1); +} + + #ifndef SQLITE_OMIT_AUTOVACUUM /* @@ -31942,7 +34529,7 @@ static int setChildPtrmaps(MemPage *pPage){ if( !pPage->leaf ){ Pgno childPgno = get4byte(pCell); rc = ptrmapPut(pBt, childPgno, PTRMAP_BTREE, pgno); - if( rc!=SQLITE_OK ) goto set_child_ptrmaps_out; + if( rc!=SQLITE_OK ) goto set_child_ptrmaps_out; } } @@ -32029,7 +34616,8 @@ static int relocatePage( MemPage *pDbPage, /* Open page to move */ u8 eType, /* Pointer map 'type' entry for pDbPage */ Pgno iPtrPage, /* Pointer map 'page-no' entry for pDbPage */ - Pgno iFreePage /* The location to move pDbPage to */ + Pgno iFreePage, /* The location to move pDbPage to */ + int isCommit ){ MemPage *pPtrPage; /* The page that contains a pointer to pDbPage */ Pgno iDbPage = pDbPage->pgno; @@ -32044,7 +34632,7 @@ static int relocatePage( /* Move page iDbPage from its current location to page number iFreePage */ TRACE(("AUTOVACUUM: Moving %d to free page %d (ptr page %d type %d)\n", iDbPage, iFreePage, iPtrPage, eType)); - rc = sqlite3PagerMovepage(pPager, pDbPage->pDbPage, iFreePage); + rc = sqlite3PagerMovepage(pPager, pDbPage->pDbPage, iFreePage, isCommit); if( rc!=SQLITE_OK ){ return rc; } @@ -32121,7 +34709,7 @@ static int incrVacuumStep(BtShared *pBt, Pgno nFin){ assert( sqlite3_mutex_held(pBt->mutex) ); iLastPg = pBt->nTrunc; if( iLastPg==0 ){ - iLastPg = sqlite3PagerPagecount(pBt->pPager); + iLastPg = pagerPagecount(pBt->pPager); } if( !PTRMAP_ISPAGE(pBt, iLastPg) && iLastPg!=PENDING_BYTE_PAGE(pBt) ){ @@ -32187,7 +34775,7 @@ static int incrVacuumStep(BtShared *pBt, Pgno nFin){ rc = sqlite3PagerWrite(pLastPg->pDbPage); if( rc==SQLITE_OK ){ - rc = relocatePage(pBt, pLastPg, eType, iPtrPage, iFreePg); + rc = relocatePage(pBt, pLastPg, eType, iPtrPage, iFreePg, nFin!=0); } releasePage(pLastPg); if( rc!=SQLITE_OK ){ @@ -32254,7 +34842,7 @@ static int autoVacuumCommit(BtShared *pBt, Pgno *pnTrunc){ Pgno nFree; Pgno nPtrmap; const int pgsz = pBt->pageSize; - Pgno nOrig = sqlite3PagerPagecount(pBt->pPager); + int nOrig = pagerPagecount(pBt->pPager); if( PTRMAP_ISPAGE(pBt, nOrig) ){ return SQLITE_CORRUPT_BKPT; @@ -32611,7 +35199,6 @@ SQLITE_PRIVATE int sqlite3BtreeRollbackStmt(Btree *p){ pBt->db = p->db; if( pBt->inStmt && !pBt->readOnly ){ rc = sqlite3PagerStmtRollback(pBt->pPager); - assert( countWriteCursors(pBt)==0 ); pBt->inStmt = 0; } sqlite3BtreeLeave(p); @@ -32660,7 +35247,7 @@ static int btreeCursor( if( pBt->readOnly ){ return SQLITE_READONLY; } - if( checkReadLocks(p, iTable, 0) ){ + if( checkReadLocks(p, iTable, 0, 0) ){ return SQLITE_LOCKED; } } @@ -32675,7 +35262,7 @@ static int btreeCursor( } } pCur->pgnoRoot = (Pgno)iTable; - if( iTable==1 && sqlite3PagerPagecount(pBt->pPager)==0 ){ + if( iTable==1 && pagerPagecount(pBt->pPager)==0 ){ rc = SQLITE_EMPTY; goto create_cursor_exception; } @@ -32702,9 +35289,7 @@ static int btreeCursor( return SQLITE_OK; create_cursor_exception: - if( pCur ){ - releasePage(pCur->pPage); - } + releasePage(pCur->pPage); unlockBtreeIfUnused(pBt); return rc; } @@ -32839,7 +35424,7 @@ SQLITE_PRIVATE int sqlite3BtreeKeySize(BtCursor *pCur, i64 *pSize){ int rc; assert( cursorHoldsMutex(pCur) ); - rc = restoreOrClearCursorPosition(pCur); + rc = restoreCursorPosition(pCur); if( rc==SQLITE_OK ){ assert( pCur->eState==CURSOR_INVALID || pCur->eState==CURSOR_VALID ); if( pCur->eState==CURSOR_INVALID ){ @@ -32863,7 +35448,7 @@ SQLITE_PRIVATE int sqlite3BtreeDataSize(BtCursor *pCur, u32 *pSize){ int rc; assert( cursorHoldsMutex(pCur) ); - rc = restoreOrClearCursorPosition(pCur); + rc = restoreCursorPosition(pCur); if( rc==SQLITE_OK ){ assert( pCur->eState==CURSOR_INVALID || pCur->eState==CURSOR_VALID ); if( pCur->eState==CURSOR_INVALID ){ @@ -32930,7 +35515,7 @@ static int getOverflowPage( iGuess++; } - if( iGuess<=sqlite3PagerPagecount(pBt->pPager) ){ + if( iGuess<=pagerPagecount(pBt->pPager) ){ rc = ptrmapGet(pBt, iGuess, &eType, &pgno); if( rc!=SQLITE_OK ){ return rc; @@ -33171,7 +35756,7 @@ SQLITE_PRIVATE int sqlite3BtreeKey(BtCursor *pCur, u32 offset, u32 amt, void *pB int rc; assert( cursorHoldsMutex(pCur) ); - rc = restoreOrClearCursorPosition(pCur); + rc = restoreCursorPosition(pCur); if( rc==SQLITE_OK ){ assert( pCur->eState==CURSOR_VALID ); assert( pCur->pPage!=0 ); @@ -33197,8 +35782,14 @@ SQLITE_PRIVATE int sqlite3BtreeKey(BtCursor *pCur, u32 offset, u32 amt, void *pB SQLITE_PRIVATE int sqlite3BtreeData(BtCursor *pCur, u32 offset, u32 amt, void *pBuf){ int rc; +#ifndef SQLITE_OMIT_INCRBLOB + if ( pCur->eState==CURSOR_INVALID ){ + return SQLITE_ABORT; + } +#endif + assert( cursorHoldsMutex(pCur) ); - rc = restoreOrClearCursorPosition(pCur); + rc = restoreCursorPosition(pCur); if( rc==SQLITE_OK ){ assert( pCur->eState==CURSOR_VALID ); assert( pCur->pPage!=0 ); @@ -33650,7 +36241,7 @@ SQLITE_PRIVATE int sqlite3BtreeMoveto( if( available>=nCellKey ){ c = sqlite3VdbeRecordCompare(nCellKey, pCellKey, pUnKey); }else{ - pCellKey = sqlite3_malloc( nCellKey ); + pCellKey = sqlite3Malloc( nCellKey ); if( pCellKey==0 ){ rc = SQLITE_NOMEM; goto moveto_finish; @@ -33663,7 +36254,7 @@ SQLITE_PRIVATE int sqlite3BtreeMoveto( } if( c==0 ){ pCur->info.nKey = nCellKey; - if( pPage->leafData && !pPage->leaf ){ + if( pPage->intKey && !pPage->leaf ){ lwr = pCur->idx; upr = lwr - 1; break; @@ -33749,7 +36340,7 @@ SQLITE_PRIVATE int sqlite3BtreeNext(BtCursor *pCur, int *pRes){ MemPage *pPage; assert( cursorHoldsMutex(pCur) ); - rc = restoreOrClearCursorPosition(pCur); + rc = restoreCursorPosition(pCur); if( rc!=SQLITE_OK ){ return rc; } @@ -33790,7 +36381,7 @@ SQLITE_PRIVATE int sqlite3BtreeNext(BtCursor *pCur, int *pRes){ pPage = pCur->pPage; }while( pCur->idx>=pPage->nCell ); *pRes = 0; - if( pPage->leafData ){ + if( pPage->intKey ){ rc = sqlite3BtreeNext(pCur, pRes); }else{ rc = SQLITE_OK; @@ -33818,7 +36409,7 @@ SQLITE_PRIVATE int sqlite3BtreePrevious(BtCursor *pCur, int *pRes){ MemPage *pPage; assert( cursorHoldsMutex(pCur) ); - rc = restoreOrClearCursorPosition(pCur); + rc = restoreCursorPosition(pCur); if( rc!=SQLITE_OK ){ return rc; } @@ -33857,7 +36448,7 @@ SQLITE_PRIVATE int sqlite3BtreePrevious(BtCursor *pCur, int *pRes){ pCur->idx--; pCur->info.nSize = 0; pCur->validNKey = 0; - if( pPage->leafData && !pPage->leaf ){ + if( pPage->intKey && !pPage->leaf ){ rc = sqlite3BtreePrevious(pCur, pRes); }else{ rc = SQLITE_OK; @@ -33915,7 +36506,7 @@ static int allocateBtreePage( ** the entire-list will be searched for that page. */ #ifndef SQLITE_OMIT_AUTOVACUUM - if( exact && nearby<=sqlite3PagerPagecount(pBt->pPager) ){ + if( exact && nearby<=pagerPagecount(pBt->pPager) ){ u8 eType; assert( nearby>0 ); assert( pBt->autoVacuum ); @@ -33967,7 +36558,7 @@ static int allocateBtreePage( *ppPage = pTrunk; pTrunk = 0; TRACE(("ALLOCATE: %d trunk - %d free pages left\n", *pPgno, n-1)); - }else if( k>pBt->usableSize/4 - 8 ){ + }else if( k>pBt->usableSize/4 - 2 ){ /* Value of k is out of range. Database corruption */ rc = SQLITE_CORRUPT_BKPT; goto end_allocate_page; @@ -34050,8 +36641,10 @@ static int allocateBtreePage( iPage = get4byte(&aData[8+closest*4]); if( !searchList || iPage==nearby ){ + int nPage; *pPgno = iPage; - if( *pPgno>sqlite3PagerPagecount(pBt->pPager) ){ + nPage = pagerPagecount(pBt->pPager); + if( *pPgno>nPage ){ /* Free page off the end of the file */ rc = SQLITE_CORRUPT_BKPT; goto end_allocate_page; @@ -34080,7 +36673,8 @@ static int allocateBtreePage( }else{ /* There are no pages on the freelist, so create a new page at the ** end of the file */ - *pPgno = sqlite3PagerPagecount(pBt->pPager) + 1; + int nPage = pagerPagecount(pBt->pPager); + *pPgno = nPage + 1; #ifndef SQLITE_OMIT_AUTOVACUUM if( pBt->nTrunc ){ @@ -34158,15 +36752,13 @@ static int freePage(MemPage *pPage){ memset(pPage->aData, 0, pPage->pBt->pageSize); #endif -#ifndef SQLITE_OMIT_AUTOVACUUM /* If the database supports auto-vacuum, write an entry in the pointer-map ** to indicate that the page is free. */ - if( pBt->autoVacuum ){ + if( ISAUTOVACUUM ){ rc = ptrmapPut(pBt, pPage->pgno, PTRMAP_FREEPAGE, 0); if( rc ) return rc; } -#endif if( n==0 ){ /* This is the first free page */ @@ -34184,7 +36776,19 @@ static int freePage(MemPage *pPage){ k = get4byte(&pTrunk->aData[4]); if( k>=pBt->usableSize/4 - 8 ){ /* The trunk is full. Turn the page being freed into a new - ** trunk page with no leaves. */ + ** trunk page with no leaves. + ** + ** Note that the trunk page is not really full until it contains + ** usableSize/4 - 2 entries, not usableSize/4 - 8 entries as we have + ** coded. But due to a coding error in versions of SQLite prior to + ** 3.6.0, databases with freelist trunk pages holding more than + ** usableSize/4 - 8 entries will be reported as corrupt. In order + ** to maintain backwards compatibility with older versions of SQLite, + ** we will contain to restrict the number of entries to usableSize/4 - 8 + ** for now. At some point in the future (once everyone has upgraded + ** to 3.6.0 or later) we should consider fixing the conditional above + ** to read "usableSize/4-2" instead of "usableSize/4-8". + */ rc = sqlite3PagerWrite(pPage->pDbPage); if( rc==SQLITE_OK ){ put4byte(pPage->aData, pTrunk->pgno); @@ -34234,7 +36838,7 @@ static int clearCell(MemPage *pPage, unsigned char *pCell){ assert( ovflPgno==0 || nOvfl>0 ); while( nOvfl-- ){ MemPage *pOvfl; - if( ovflPgno==0 || ovflPgno>sqlite3PagerPagecount(pBt->pPager) ){ + if( ovflPgno==0 || ovflPgno>pagerPagecount(pBt->pPager) ){ return SQLITE_CORRUPT_BKPT; } @@ -34385,12 +36989,23 @@ static int fillInCell( return SQLITE_OK; } + /* ** Change the MemPage.pParent pointer on the page whose number is ** given in the second argument so that MemPage.pParent holds the ** pointer in the third argument. +** +** If the final argument, updatePtrmap, is non-zero and the database +** is an auto-vacuum database, then the pointer-map entry for pgno +** is updated. */ -static int reparentPage(BtShared *pBt, Pgno pgno, MemPage *pNewParent, int idx){ +static int reparentPage( + BtShared *pBt, /* B-Tree structure */ + Pgno pgno, /* Page number of child being adopted */ + MemPage *pNewParent, /* New parent of pgno */ + int idx, /* Index of child page pgno in pNewParent */ + int updatePtrmap /* If true, update pointer-map for pgno */ +){ MemPage *pThis; DbPage *pDbPage; @@ -34413,11 +37028,26 @@ static int reparentPage(BtShared *pBt, Pgno pgno, MemPage *pNewParent, int idx){ sqlite3PagerUnref(pDbPage); } -#ifndef SQLITE_OMIT_AUTOVACUUM - if( pBt->autoVacuum ){ + if( ISAUTOVACUUM && updatePtrmap ){ return ptrmapPut(pBt, pgno, PTRMAP_BTREE, pNewParent->pgno); } + +#ifndef NDEBUG + /* If the updatePtrmap flag was clear, assert that the entry in the + ** pointer-map is already correct. + */ + if( ISAUTOVACUUM ){ + pDbPage = sqlite3PagerLookup(pBt->pPager,PTRMAP_PAGENO(pBt,pgno)); + if( pDbPage ){ + u8 eType; + Pgno ii; + int rc = ptrmapGet(pBt, pgno, &eType, &ii); + assert( rc==SQLITE_OK && ii==pNewParent->pgno && eType==PTRMAP_BTREE ); + sqlite3PagerUnref(pDbPage); + } + } #endif + return SQLITE_OK; } @@ -34432,23 +37062,26 @@ static int reparentPage(BtShared *pBt, Pgno pgno, MemPage *pNewParent, int idx){ ** ** This routine gets called after you memcpy() one page into ** another. +** +** If updatePtrmap is true, then the pointer-map entries for all child +** pages of pPage are updated. */ -static int reparentChildPages(MemPage *pPage){ - int i; - BtShared *pBt = pPage->pBt; +static int reparentChildPages(MemPage *pPage, int updatePtrmap){ int rc = SQLITE_OK; - assert( sqlite3_mutex_held(pPage->pBt->mutex) ); - if( pPage->leaf ) return SQLITE_OK; + if( !pPage->leaf ){ + int i; + BtShared *pBt = pPage->pBt; + Pgno iRight = get4byte(&pPage->aData[pPage->hdrOffset+8]); - for(i=0; i<pPage->nCell; i++){ - u8 *pCell = findCell(pPage, i); - rc = reparentPage(pBt, get4byte(pCell), pPage, i); - if( rc!=SQLITE_OK ) return rc; + for(i=0; i<pPage->nCell; i++){ + u8 *pCell = findCell(pPage, i); + rc = reparentPage(pBt, get4byte(pCell), pPage, i, updatePtrmap); + if( rc!=SQLITE_OK ) return rc; + } + rc = reparentPage(pBt, iRight, pPage, i, updatePtrmap); + pPage->idxShift = 0; } - rc = reparentPage(pBt, get4byte(&pPage->aData[pPage->hdrOffset+8]), - pPage, i); - pPage->idxShift = 0; return rc; } @@ -34546,8 +37179,7 @@ static int insertCell( end = cellOffset + 2*pPage->nCell + 2; ins = cellOffset + 2*i; if( end > top - sz ){ - rc = defragmentPage(pPage); - if( rc!=SQLITE_OK ) return rc; + defragmentPage(pPage); top = get2byte(&data[hdr+5]); assert( end + sz <= top ); } @@ -34699,28 +37331,32 @@ static int balance_quick(MemPage *pPage, MemPage *pParent){ /* pPage is currently the right-child of pParent. Change this ** so that the right-child is the new page allocated above and ** pPage is the next-to-right child. + ** + ** Ignore the return value of the call to fillInCell(). fillInCell() + ** may only return other than SQLITE_OK if it is required to allocate + ** one or more overflow pages. Since an internal table B-Tree cell + ** may never spill over onto an overflow page (it is a maximum of + ** 13 bytes in size), it is not neccessary to check the return code. + ** + ** Similarly, the insertCell() function cannot fail if the page + ** being inserted into is already writable and the cell does not + ** contain an overflow pointer. So ignore this return code too. */ assert( pPage->nCell>0 ); pCell = findCell(pPage, pPage->nCell-1); sqlite3BtreeParseCellPtr(pPage, pCell, &info); - rc = fillInCell(pParent, parentCell, 0, info.nKey, 0, 0, 0, &parentSize); - if( rc!=SQLITE_OK ){ - return rc; - } + fillInCell(pParent, parentCell, 0, info.nKey, 0, 0, 0, &parentSize); assert( parentSize<64 ); - rc = insertCell(pParent, parentIdx, parentCell, parentSize, 0, 4); - if( rc!=SQLITE_OK ){ - return rc; - } + assert( sqlite3PagerIswriteable(pParent->pDbPage) ); + insertCell(pParent, parentIdx, parentCell, parentSize, 0, 4); put4byte(findOverflowCell(pParent,parentIdx), pPage->pgno); put4byte(&pParent->aData[pParent->hdrOffset+8], pgnoNew); -#ifndef SQLITE_OMIT_AUTOVACUUM /* If this is an auto-vacuum database, update the pointer map ** with entries for the new page, and any pointer from the ** cell on the page to an overflow page. */ - if( pBt->autoVacuum ){ + if( ISAUTOVACUUM ){ rc = ptrmapPut(pBt, pgnoNew, PTRMAP_BTREE, pParent->pgno); if( rc==SQLITE_OK ){ rc = ptrmapPutOvfl(pNew, 0); @@ -34730,7 +37366,6 @@ static int balance_quick(MemPage *pPage, MemPage *pParent){ return rc; } } -#endif /* Release the reference to the new page and balance the parent page, ** in case the divider cell inserted caused it to become overfull. @@ -34786,7 +37421,9 @@ static int balance_nonroot(MemPage *pPage){ int usableSpace; /* Bytes in pPage beyond the header */ int pageFlags; /* Value of pPage->aData[0] */ int subtotal; /* Subtotal of bytes in cells on one page */ - int iSpace = 0; /* First unused byte of aSpace[] */ + int iSpace1 = 0; /* First unused byte of aSpace1[] */ + int iSpace2 = 0; /* First unused byte of aSpace2[] */ + int szScratch; /* Size of scratch memory requested */ MemPage *apOld[NB]; /* pPage and up to two siblings */ Pgno pgnoOld[NB]; /* Page numbers for each page in apOld[] */ MemPage *apCopy[NB]; /* Private copies of apOld[] pages */ @@ -34797,11 +37434,10 @@ static int balance_nonroot(MemPage *pPage){ int szNew[NB+2]; /* Combined size of cells place on i-th page */ u8 **apCell = 0; /* All cells begin balanced */ u16 *szCell; /* Local size of all cells in apCell[] */ - u8 *aCopy[NB]; /* Space for holding data of apCopy[] */ - u8 *aSpace; /* Space to hold copies of dividers cells */ -#ifndef SQLITE_OMIT_AUTOVACUUM + u8 *aCopy[NB]; /* Space for holding data of apCopy[] */ + u8 *aSpace1; /* Space for copies of dividers cells before balance */ + u8 *aSpace2 = 0; /* Space for overflow dividers cells after balance */ u8 *aFrom = 0; -#endif assert( sqlite3_mutex_held(pPage->pBt->mutex) ); @@ -34816,6 +37452,7 @@ static int balance_nonroot(MemPage *pPage){ if( SQLITE_OK!=(rc = sqlite3PagerWrite(pParent->pDbPage)) ){ return rc; } + TRACE(("BALANCE: begin page %d child of %d\n", pPage->pgno, pParent->pgno)); #ifndef SQLITE_OMIT_QUICKBALANCE @@ -34829,12 +37466,12 @@ static int balance_nonroot(MemPage *pPage){ */ if( pPage->leaf && pPage->intKey && - pPage->leafData && pPage->nOverflow==1 && pPage->aOvfl[0].idx==pPage->nCell && pPage->pParent->pgno!=1 && get4byte(&pParent->aData[pParent->hdrOffset+8])==pPage->pgno ){ + assert( pPage->intKey ); /* ** TODO: Check the siblings to the left of pPage. It may be that ** they are not full and no new page is required. @@ -34916,13 +37553,13 @@ static int balance_nonroot(MemPage *pPage){ /* ** Allocate space for memory structures */ - apCell = sqlite3_malloc( + szScratch = nMaxCells*sizeof(u8*) /* apCell */ + nMaxCells*sizeof(u16) /* szCell */ + (ROUND8(sizeof(MemPage))+pBt->pageSize)*NB /* aCopy */ - + pBt->pageSize*5 /* aSpace */ - + (ISAUTOVACUUM ? nMaxCells : 0) /* aFrom */ - ); + + pBt->pageSize /* aSpace1 */ + + (ISAUTOVACUUM ? nMaxCells : 0); /* aFrom */ + apCell = sqlite3ScratchMalloc( szScratch ); if( apCell==0 ){ rc = SQLITE_NOMEM; goto balance_cleanup; @@ -34934,13 +37571,16 @@ static int balance_nonroot(MemPage *pPage){ aCopy[i] = &aCopy[i-1][pBt->pageSize+ROUND8(sizeof(MemPage))]; assert( ((aCopy[i] - (u8*)apCell) & 7)==0 ); /* 8-byte alignment required */ } - aSpace = &aCopy[NB-1][pBt->pageSize+ROUND8(sizeof(MemPage))]; - assert( ((aSpace - (u8*)apCell) & 7)==0 ); /* 8-byte alignment required */ -#ifndef SQLITE_OMIT_AUTOVACUUM - if( pBt->autoVacuum ){ - aFrom = &aSpace[5*pBt->pageSize]; + aSpace1 = &aCopy[NB-1][pBt->pageSize+ROUND8(sizeof(MemPage))]; + assert( ((aSpace1 - (u8*)apCell) & 7)==0 ); /* 8-byte alignment required */ + if( ISAUTOVACUUM ){ + aFrom = &aSpace1[pBt->pageSize]; + } + aSpace2 = sqlite3PageMalloc(pBt->pageSize); + if( aSpace2==0 ){ + rc = SQLITE_NOMEM; + goto balance_cleanup; } -#endif /* ** Make copies of the content of pPage and its siblings into aOld[]. @@ -34958,12 +37598,12 @@ static int balance_nonroot(MemPage *pPage){ /* ** Load pointers to all cells on sibling pages and the divider cells ** into the local apCell[] array. Make copies of the divider cells - ** into space obtained form aSpace[] and remove the the divider Cells + ** into space obtained form aSpace1[] and remove the the divider Cells ** from pParent. ** ** If the siblings are on leaf pages, then the child pointers of the ** divider cells are stripped from the cells before they are copied - ** into aSpace[]. In this way, all cells in apCell[] are without + ** into aSpace1[]. In this way, all cells in apCell[] are without ** child pointers. If siblings are not leaves, then all cell in ** apCell[] include child pointers. Either way, all cells in apCell[] ** are alike. @@ -34973,7 +37613,7 @@ static int balance_nonroot(MemPage *pPage){ */ nCell = 0; leafCorrection = pPage->leaf*4; - leafData = pPage->leafData && pPage->leaf; + leafData = pPage->hasData; for(i=0; i<nOld; i++){ MemPage *pOld = apCopy[i]; int limit = pOld->nCell+pOld->nOverflow; @@ -34981,8 +37621,7 @@ static int balance_nonroot(MemPage *pPage){ assert( nCell<nMaxCells ); apCell[nCell] = findOverflowCell(pOld, j); szCell[nCell] = cellSizePtr(pOld, apCell[nCell]); -#ifndef SQLITE_OMIT_AUTOVACUUM - if( pBt->autoVacuum ){ + if( ISAUTOVACUUM ){ int a; aFrom[nCell] = i; for(a=0; a<pOld->nOverflow; a++){ @@ -34992,7 +37631,6 @@ static int balance_nonroot(MemPage *pPage){ } } } -#endif nCell++; } if( i<nOld-1 ){ @@ -35008,16 +37646,15 @@ static int balance_nonroot(MemPage *pPage){ u8 *pTemp; assert( nCell<nMaxCells ); szCell[nCell] = sz; - pTemp = &aSpace[iSpace]; - iSpace += sz; - assert( iSpace<=pBt->pageSize*5 ); + pTemp = &aSpace1[iSpace1]; + iSpace1 += sz; + assert( sz<=pBt->pageSize/4 ); + assert( iSpace1<=pBt->pageSize ); memcpy(pTemp, apDiv[i], sz); apCell[nCell] = pTemp+leafCorrection; -#ifndef SQLITE_OMIT_AUTOVACUUM - if( pBt->autoVacuum ){ + if( ISAUTOVACUUM ){ aFrom[nCell] = 0xFF; } -#endif dropCell(pParent, nxDiv, sz); szCell[nCell] -= leafCorrection; assert( get4byte(pTemp)==pgnoOld[i] ); @@ -35128,7 +37765,6 @@ static int balance_nonroot(MemPage *pPage){ apNew[i] = pNew; nNew++; } - zeroPage(pNew, pageFlags); } /* Free any old pages that were not reused as new pages. @@ -35195,28 +37831,30 @@ static int balance_nonroot(MemPage *pPage){ MemPage *pNew = apNew[i]; assert( j<nMaxCells ); assert( pNew->pgno==pgnoNew[i] ); + zeroPage(pNew, pageFlags); assemblePage(pNew, cntNew[i]-j, &apCell[j], &szCell[j]); assert( pNew->nCell>0 || (nNew==1 && cntNew[0]==0) ); assert( pNew->nOverflow==0 ); -#ifndef SQLITE_OMIT_AUTOVACUUM /* If this is an auto-vacuum database, update the pointer map entries ** that point to the siblings that were rearranged. These can be: left ** children of cells, the right-child of the page, or overflow pages ** pointed to by cells. */ - if( pBt->autoVacuum ){ + if( ISAUTOVACUUM ){ for(k=j; k<cntNew[i]; k++){ assert( k<nMaxCells ); if( aFrom[k]==0xFF || apCopy[aFrom[k]]->pgno!=pNew->pgno ){ rc = ptrmapPutOvfl(pNew, k-j); + if( rc==SQLITE_OK && leafCorrection==0 ){ + rc = ptrmapPut(pBt, get4byte(apCell[k]), PTRMAP_BTREE, pNew->pgno); + } if( rc!=SQLITE_OK ){ goto balance_cleanup; } } } } -#endif j = cntNew[i]; @@ -35231,9 +37869,17 @@ static int balance_nonroot(MemPage *pPage){ assert( j<nMaxCells ); pCell = apCell[j]; sz = szCell[j] + leafCorrection; + pTemp = &aSpace2[iSpace2]; if( !pNew->leaf ){ memcpy(&pNew->aData[8], pCell, 4); - pTemp = 0; + if( ISAUTOVACUUM + && (aFrom[j]==0xFF || apCopy[aFrom[j]]->pgno!=pNew->pgno) + ){ + rc = ptrmapPut(pBt, get4byte(pCell), PTRMAP_BTREE, pNew->pgno); + if( rc!=SQLITE_OK ){ + goto balance_cleanup; + } + } }else if( leafData ){ /* If the tree is a leaf-data tree, and the siblings are leaves, ** then there is no divider cell in apCell[]. Instead, the divider @@ -35243,16 +37889,11 @@ static int balance_nonroot(MemPage *pPage){ CellInfo info; j--; sqlite3BtreeParseCellPtr(pNew, apCell[j], &info); - pCell = &aSpace[iSpace]; + pCell = pTemp; fillInCell(pParent, pCell, 0, info.nKey, 0, 0, 0, &sz); - iSpace += sz; - assert( iSpace<=pBt->pageSize*5 ); pTemp = 0; }else{ pCell -= 4; - pTemp = &aSpace[iSpace]; - iSpace += sz; - assert( iSpace<=pBt->pageSize*5 ); /* Obscure case for non-leaf-data trees: If the cell at pCell was ** previously stored on a leaf node, and its reported size was 4 ** bytes, then it may actually be smaller than this @@ -35269,30 +37910,47 @@ static int balance_nonroot(MemPage *pPage){ sz = cellSizePtr(pParent, pCell); } } + iSpace2 += sz; + assert( sz<=pBt->pageSize/4 ); + assert( iSpace2<=pBt->pageSize ); rc = insertCell(pParent, nxDiv, pCell, sz, pTemp, 4); if( rc!=SQLITE_OK ) goto balance_cleanup; put4byte(findOverflowCell(pParent,nxDiv), pNew->pgno); -#ifndef SQLITE_OMIT_AUTOVACUUM + /* If this is an auto-vacuum database, and not a leaf-data tree, ** then update the pointer map with an entry for the overflow page ** that the cell just inserted points to (if any). */ - if( pBt->autoVacuum && !leafData ){ + if( ISAUTOVACUUM && !leafData ){ rc = ptrmapPutOvfl(pParent, nxDiv); if( rc!=SQLITE_OK ){ goto balance_cleanup; } } -#endif j++; nxDiv++; } + + /* Set the pointer-map entry for the new sibling page. */ + if( ISAUTOVACUUM ){ + rc = ptrmapPut(pBt, pNew->pgno, PTRMAP_BTREE, pParent->pgno); + if( rc!=SQLITE_OK ){ + goto balance_cleanup; + } + } } assert( j==nCell ); assert( nOld>0 ); assert( nNew>0 ); if( (pageFlags & PTF_LEAF)==0 ){ - memcpy(&apNew[nNew-1]->aData[8], &apCopy[nOld-1]->aData[8], 4); + u8 *zChild = &apCopy[nOld-1]->aData[8]; + memcpy(&apNew[nNew-1]->aData[8], zChild, 4); + if( ISAUTOVACUUM ){ + rc = ptrmapPut(pBt, get4byte(zChild), PTRMAP_BTREE, apNew[nNew-1]->pgno); + if( rc!=SQLITE_OK ){ + goto balance_cleanup; + } + } } if( nxDiv==pParent->nCell+pParent->nOverflow ){ /* Right-most sibling is the right-most child of pParent */ @@ -35307,10 +37965,10 @@ static int balance_nonroot(MemPage *pPage){ ** Reparent children of all cells. */ for(i=0; i<nNew; i++){ - rc = reparentChildPages(apNew[i]); + rc = reparentChildPages(apNew[i], 0); if( rc!=SQLITE_OK ) goto balance_cleanup; } - rc = reparentChildPages(pParent); + rc = reparentChildPages(pParent, 0); if( rc!=SQLITE_OK ) goto balance_cleanup; /* @@ -35319,13 +37977,16 @@ static int balance_nonroot(MemPage *pPage){ ** But the parent page will always be initialized. */ assert( pParent->isInit ); + sqlite3ScratchFree(apCell); + apCell = 0; rc = balance(pParent, 0); /* ** Cleanup before returning. */ balance_cleanup: - sqlite3_free(apCell); + sqlite3PageFree(aSpace2); + sqlite3ScratchFree(apCell); for(i=0; i<nOld; i++){ releasePage(apOld[i]); } @@ -35357,7 +38018,7 @@ static int balance_shallower(MemPage *pPage){ assert( sqlite3_mutex_held(pPage->pBt->mutex) ); pBt = pPage->pBt; mxCellPerPage = MX_CELL(pBt); - apCell = sqlite3_malloc( mxCellPerPage*(sizeof(u8*)+sizeof(u16)) ); + apCell = sqlite3Malloc( mxCellPerPage*(sizeof(u8*)+sizeof(u16)) ); if( apCell==0 ) return SQLITE_NOMEM; szCell = (u16*)&apCell[mxCellPerPage]; if( pPage->leaf ){ @@ -35378,7 +38039,7 @@ static int balance_shallower(MemPage *pPage){ */ pgnoChild = get4byte(&pPage->aData[pPage->hdrOffset+8]); assert( pgnoChild>0 ); - assert( pgnoChild<=sqlite3PagerPagecount(pPage->pBt->pPager) ); + assert( pgnoChild<=pagerPagecount(pPage->pBt->pPager) ); rc = sqlite3BtreeGetPage(pPage->pBt, pgnoChild, &pChild, 0); if( rc ) goto end_shallow_balance; if( pPage->pgno==1 ){ @@ -35415,10 +38076,9 @@ static int balance_shallower(MemPage *pPage){ TRACE(("BALANCE: transfer child %d into root %d\n", pChild->pgno, pPage->pgno)); } - rc = reparentChildPages(pPage); + rc = reparentChildPages(pPage, 1); assert( pPage->nOverflow==0 ); -#ifndef SQLITE_OMIT_AUTOVACUUM - if( pBt->autoVacuum ){ + if( ISAUTOVACUUM ){ int i; for(i=0; i<pPage->nCell; i++){ rc = ptrmapPutOvfl(pPage, i); @@ -35427,7 +38087,6 @@ static int balance_shallower(MemPage *pPage){ } } } -#endif releasePage(pChild); } end_shallow_balance: @@ -35470,7 +38129,7 @@ static int balance_deeper(MemPage *pPage){ cdata = pChild->aData; memcpy(cdata, &data[hdr], pPage->cellOffset+2*pPage->nCell-hdr); memcpy(&cdata[brk], &data[brk], usableSize-brk); - assert( pChild->isInit==0 ); + if( pChild->isInit ) return SQLITE_CORRUPT; rc = sqlite3BtreeInitPage(pChild, pPage); if( rc ) goto balancedeeper_out; memcpy(pChild->aOvfl, pPage->aOvfl, pPage->nOverflow*sizeof(pPage->aOvfl[0])); @@ -35482,20 +38141,21 @@ static int balance_deeper(MemPage *pPage){ zeroPage(pPage, pChild->aData[0] & ~PTF_LEAF); put4byte(&pPage->aData[pPage->hdrOffset+8], pgnoChild); TRACE(("BALANCE: copy root %d into %d\n", pPage->pgno, pChild->pgno)); -#ifndef SQLITE_OMIT_AUTOVACUUM - if( pBt->autoVacuum ){ + if( ISAUTOVACUUM ){ int i; rc = ptrmapPut(pBt, pChild->pgno, PTRMAP_BTREE, pPage->pgno); if( rc ) goto balancedeeper_out; for(i=0; i<pChild->nCell; i++){ rc = ptrmapPutOvfl(pChild, i); if( rc!=SQLITE_OK ){ - return rc; + goto balancedeeper_out; } } + rc = reparentChildPages(pChild, 1); + } + if( rc==SQLITE_OK ){ + rc = balance_nonroot(pChild); } -#endif - rc = balance_nonroot(pChild); balancedeeper_out: releasePage(pChild); @@ -35534,47 +38194,68 @@ static int balance(MemPage *pPage, int insert){ ** is not in the ReadUncommmitted state, then this routine returns ** SQLITE_LOCKED. ** -** In addition to checking for read-locks (where a read-lock -** means a cursor opened with wrFlag==0) this routine also moves -** all write cursors so that they are pointing to the -** first Cell on the root page. This is necessary because an insert -** or delete might change the number of cells on a page or delete -** a page entirely and we do not want to leave any cursors -** pointing to non-existant pages or cells. -*/ -static int checkReadLocks(Btree *pBtree, Pgno pgnoRoot, BtCursor *pExclude){ +** As well as cursors with wrFlag==0, cursors with wrFlag==1 and +** isIncrblobHandle==1 are also considered 'read' cursors. Incremental +** blob cursors are used for both reading and writing. +** +** When pgnoRoot is the root page of an intkey table, this function is also +** responsible for invalidating incremental blob cursors when the table row +** on which they are opened is deleted or modified. Cursors are invalidated +** according to the following rules: +** +** 1) When BtreeClearTable() is called to completely delete the contents +** of a B-Tree table, pExclude is set to zero and parameter iRow is +** set to non-zero. In this case all incremental blob cursors open +** on the table rooted at pgnoRoot are invalidated. +** +** 2) When BtreeInsert(), BtreeDelete() or BtreePutData() is called to +** modify a table row via an SQL statement, pExclude is set to the +** write cursor used to do the modification and parameter iRow is set +** to the integer row id of the B-Tree entry being modified. Unless +** pExclude is itself an incremental blob cursor, then all incremental +** blob cursors open on row iRow of the B-Tree are invalidated. +** +** 3) If both pExclude and iRow are set to zero, no incremental blob +** cursors are invalidated. +*/ +static int checkReadLocks( + Btree *pBtree, + Pgno pgnoRoot, + BtCursor *pExclude, + i64 iRow +){ BtCursor *p; BtShared *pBt = pBtree->pBt; sqlite3 *db = pBtree->db; assert( sqlite3BtreeHoldsMutex(pBtree) ); for(p=pBt->pCursor; p; p=p->pNext){ if( p==pExclude ) continue; - if( p->eState!=CURSOR_VALID ) continue; if( p->pgnoRoot!=pgnoRoot ) continue; - if( p->wrFlag==0 ){ +#ifndef SQLITE_OMIT_INCRBLOB + if( p->isIncrblobHandle && ( + (!pExclude && iRow) + || (pExclude && !pExclude->isIncrblobHandle && p->info.nKey==iRow) + )){ + p->eState = CURSOR_INVALID; + } +#endif + if( p->eState!=CURSOR_VALID ) continue; + if( p->wrFlag==0 +#ifndef SQLITE_OMIT_INCRBLOB + || p->isIncrblobHandle +#endif + ){ sqlite3 *dbOther = p->pBtree->db; if( dbOther==0 || (dbOther!=db && (dbOther->flags & SQLITE_ReadUncommitted)==0) ){ return SQLITE_LOCKED; } - }else if( p->pPage->pgno!=p->pgnoRoot ){ - moveToRoot(p); } } return SQLITE_OK; } /* -** Make sure pBt->pTmpSpace points to an allocation of -** MX_CELL_SIZE(pBt) bytes. -*/ -static void allocateTempSpace(BtShared *pBt){ - if( !pBt->pTmpSpace ){ - pBt->pTmpSpace = sqlite3_malloc(MX_CELL_SIZE(pBt)); - } -} - -/* ** Insert a new record into the BTree. The key is given by (pKey,nKey) ** and the data is given by (pData,nData). The cursor is used only to ** define what table the record should be inserted into. The cursor @@ -35609,7 +38290,7 @@ SQLITE_PRIVATE int sqlite3BtreeInsert( if( !pCur->wrFlag ){ return SQLITE_PERM; /* Cursor not open for writing */ } - if( checkReadLocks(pCur->pBtree, pCur->pgnoRoot, pCur) ){ + if( checkReadLocks(pCur->pBtree, pCur->pgnoRoot, pCur, nKey) ){ return SQLITE_LOCKED; /* The table pCur points to has a read lock */ } if( pCur->eState==CURSOR_FAULT ){ @@ -35627,7 +38308,7 @@ SQLITE_PRIVATE int sqlite3BtreeInsert( pPage = pCur->pPage; assert( pPage->intKey || nKey>=0 ); - assert( pPage->leaf || !pPage->leafData ); + assert( pPage->leaf || !pPage->intKey ); TRACE(("INSERT: table=%d nkey=%lld ndata=%d page=%d %s\n", pCur->pgnoRoot, nKey, nData, pPage->pgno, loc==0 ? "overwrite" : "new entry")); @@ -35665,8 +38346,6 @@ SQLITE_PRIVATE int sqlite3BtreeInsert( rc = insertCell(pPage, pCur->idx, newCell, szNew, 0, 0); if( rc!=SQLITE_OK ) goto end_insert; rc = balance(pPage, 1); - /* sqlite3BtreePageDump(pCur->pBt, pCur->pgnoRoot, 1); */ - /* fflush(stdout); */ if( rc==SQLITE_OK ){ moveToRoot(pCur); } @@ -35703,7 +38382,7 @@ SQLITE_PRIVATE int sqlite3BtreeDelete(BtCursor *pCur){ if( !pCur->wrFlag ){ return SQLITE_PERM; /* Did not open this cursor for writing */ } - if( checkReadLocks(pCur->pBtree, pCur->pgnoRoot, pCur) ){ + if( checkReadLocks(pCur->pBtree, pCur->pgnoRoot, pCur, pCur->info.nKey) ){ return SQLITE_LOCKED; /* The table pCur points to has a read lock */ } @@ -35713,7 +38392,7 @@ SQLITE_PRIVATE int sqlite3BtreeDelete(BtCursor *pCur){ ** that the entry will be deleted from. */ if( - (rc = restoreOrClearCursorPosition(pCur))!=0 || + (rc = restoreCursorPosition(pCur))!=0 || (rc = saveAllCursors(pBt, pCur->pgnoRoot, pCur))!=0 || (rc = sqlite3PagerWrite(pPage->pDbPage))!=0 ){ @@ -35745,7 +38424,7 @@ SQLITE_PRIVATE int sqlite3BtreeDelete(BtCursor *pCur){ unsigned char *pNext; int notUsed; unsigned char *tempCell = 0; - assert( !pPage->leafData ); + assert( !pPage->intKey ); sqlite3BtreeGetTempCursor(pCur, &leafCur); rc = sqlite3BtreeNext(&leafCur, ¬Used); if( rc==SQLITE_OK ){ @@ -35888,7 +38567,7 @@ static int btreeCreateTable(Btree *p, int *piTable, int flags){ releasePage(pRoot); return rc; } - rc = relocatePage(pBt, pRoot, eType, iPtrPage, pgnoMove); + rc = relocatePage(pBt, pRoot, eType, iPtrPage, pgnoMove, 0); releasePage(pRoot); /* Obtain the page at pgnoRoot */ @@ -35956,7 +38635,7 @@ static int clearDatabasePage( int i; assert( sqlite3_mutex_held(pBt->mutex) ); - if( pgno>sqlite3PagerPagecount(pBt->pPager) ){ + if( pgno>pagerPagecount(pBt->pPager) ){ return SQLITE_CORRUPT_BKPT; } @@ -36002,7 +38681,7 @@ SQLITE_PRIVATE int sqlite3BtreeClearTable(Btree *p, int iTable){ pBt->db = p->db; if( p->inTrans!=TRANS_WRITE ){ rc = pBt->readOnly ? SQLITE_READONLY : SQLITE_ERROR; - }else if( (rc = checkReadLocks(p, iTable, 0))!=SQLITE_OK ){ + }else if( (rc = checkReadLocks(p, iTable, 0, 1))!=SQLITE_OK ){ /* nothing to do */ }else if( SQLITE_OK!=(rc = saveAllCursors(pBt, iTable, 0)) ){ /* nothing to do */ @@ -36096,7 +38775,7 @@ static int btreeDropTable(Btree *p, int iTable, int *piMoved){ if( rc!=SQLITE_OK ){ return rc; } - rc = relocatePage(pBt, pMove, PTRMAP_ROOTPAGE, 0, iTable); + rc = relocatePage(pBt, pMove, PTRMAP_ROOTPAGE, 0, iTable, 0); releasePage(pMove); if( rc!=SQLITE_OK ){ return rc; @@ -36241,10 +38920,10 @@ SQLITE_PRIVATE int sqlite3BtreeUpdateMeta(Btree *p, int idx, u32 iMeta){ */ SQLITE_PRIVATE int sqlite3BtreeFlags(BtCursor *pCur){ /* TODO: What about CURSOR_REQUIRESEEK state? Probably need to call - ** restoreOrClearCursorPosition() here. + ** restoreCursorPosition() here. */ MemPage *pPage; - restoreOrClearCursorPosition(pCur); + restoreCursorPosition(pCur); pPage = pCur->pPage; assert( cursorHoldsMutex(pCur) ); assert( pPage->pBt==pCur->pBt ); @@ -36271,23 +38950,21 @@ static void checkAppendMsg( ... ){ va_list ap; - char *zMsg2; if( !pCheck->mxErr ) return; pCheck->mxErr--; pCheck->nErr++; va_start(ap, zFormat); - zMsg2 = sqlite3VMPrintf(0, zFormat, ap); + if( pCheck->errMsg.nChar ){ + sqlite3StrAccumAppend(&pCheck->errMsg, "\n", 1); + } + if( zMsg1 ){ + sqlite3StrAccumAppend(&pCheck->errMsg, zMsg1, -1); + } + sqlite3VXPrintf(&pCheck->errMsg, 1, zFormat, ap); va_end(ap); - if( zMsg1==0 ) zMsg1 = ""; - if( pCheck->zErrMsg ){ - char *zOld = pCheck->zErrMsg; - pCheck->zErrMsg = 0; - sqlite3SetString(&pCheck->zErrMsg, zOld, "\n", zMsg1, zMsg2, (char*)0); - sqlite3_free(zOld); - }else{ - sqlite3SetString(&pCheck->zErrMsg, zMsg1, zMsg2, (char*)0); + if( pCheck->errMsg.mallocFailed ){ + pCheck->mallocFailed = 1; } - sqlite3_free(zMsg2); } #endif /* SQLITE_OMIT_INTEGRITY_CHECK */ @@ -36380,7 +39057,7 @@ static void checkList( checkPtrmap(pCheck, iPage, PTRMAP_FREEPAGE, 0, zContext); } #endif - if( n>pCheck->pBt->usableSize/4-8 ){ + if( n>pCheck->pBt->usableSize/4-2 ){ checkAppendMsg(pCheck, zContext, "freelist leaf count too big on page %d", iPage); N--; @@ -36530,8 +39207,11 @@ static int checkTreePage( */ data = pPage->aData; hdr = pPage->hdrOffset; - hit = sqlite3MallocZero( usableSize ); - if( hit ){ + hit = sqlite3PageMalloc( pBt->pageSize ); + if( hit==0 ){ + pCheck->mallocFailed = 1; + }else{ + memset(hit, 0, usableSize ); memset(hit, 1, get2byte(&data[hdr+5])); nCell = get2byte(&data[hdr+3]); cellStart = hdr + 12 - 4*pPage->leaf; @@ -36573,7 +39253,7 @@ static int checkTreePage( cnt, data[hdr+7], iPage); } } - sqlite3_free(hit); + sqlite3PageFree(hit); releasePage(pPage); return depth+1; @@ -36586,10 +39266,10 @@ static int checkTreePage( ** an array of pages numbers were each page number is the root page of ** a table. nRoot is the number of entries in aRoot. ** -** If everything checks out, this routine returns NULL. If something is -** amiss, an error message is written into memory obtained from malloc() -** and a pointer to that error message is returned. The calling function -** is responsible for freeing the error message when it is done. +** Write the number of error seen in *pnErr. Except for some memory +** allocation errors, nn error message is held in memory obtained from +** malloc is returned if *pnErr is non-zero. If *pnErr==0 then NULL is +** returned. */ SQLITE_PRIVATE char *sqlite3BtreeIntegrityCheck( Btree *p, /* The btree to be checked */ @@ -36602,19 +39282,22 @@ SQLITE_PRIVATE char *sqlite3BtreeIntegrityCheck( int nRef; IntegrityCk sCheck; BtShared *pBt = p->pBt; + char zErr[100]; sqlite3BtreeEnter(p); pBt->db = p->db; nRef = sqlite3PagerRefcount(pBt->pPager); if( lockBtreeWithRetry(p)!=SQLITE_OK ){ + *pnErr = 1; sqlite3BtreeLeave(p); - return sqlite3StrDup("Unable to acquire a read lock on the database"); + return sqlite3DbStrDup(0, "cannot acquire a read lock on the database"); } sCheck.pBt = pBt; sCheck.pPager = pBt->pPager; - sCheck.nPage = sqlite3PagerPagecount(sCheck.pPager); + sCheck.nPage = pagerPagecount(sCheck.pPager); sCheck.mxErr = mxErr; sCheck.nErr = 0; + sCheck.mallocFailed = 0; *pnErr = 0; #ifndef SQLITE_OMIT_AUTOVACUUM if( pBt->nTrunc!=0 ){ @@ -36626,20 +39309,19 @@ SQLITE_PRIVATE char *sqlite3BtreeIntegrityCheck( sqlite3BtreeLeave(p); return 0; } - sCheck.anRef = sqlite3_malloc( (sCheck.nPage+1)*sizeof(sCheck.anRef[0]) ); + sCheck.anRef = sqlite3Malloc( (sCheck.nPage+1)*sizeof(sCheck.anRef[0]) ); if( !sCheck.anRef ){ unlockBtreeIfUnused(pBt); *pnErr = 1; sqlite3BtreeLeave(p); - return sqlite3MPrintf(p->db, "Unable to malloc %d bytes", - (sCheck.nPage+1)*sizeof(sCheck.anRef[0])); + return 0; } for(i=0; i<=sCheck.nPage; i++){ sCheck.anRef[i] = 0; } i = PENDING_BYTE_PAGE(pBt); if( i<=sCheck.nPage ){ sCheck.anRef[i] = 1; } - sCheck.zErrMsg = 0; + sqlite3StrAccumInit(&sCheck.errMsg, zErr, sizeof(zErr), 20000); /* Check the integrity of the freelist */ @@ -36694,8 +39376,14 @@ SQLITE_PRIVATE char *sqlite3BtreeIntegrityCheck( */ sqlite3BtreeLeave(p); sqlite3_free(sCheck.anRef); + if( sCheck.mallocFailed ){ + sqlite3StrAccumReset(&sCheck.errMsg); + *pnErr = sCheck.nErr+1; + return 0; + } *pnErr = sCheck.nErr; - return sCheck.zErrMsg; + if( sCheck.nErr==0 ) sqlite3StrAccumReset(&sCheck.errMsg); + return sqlite3StrAccumFinish(&sCheck.errMsg); } #endif /* SQLITE_OMIT_INTEGRITY_CHECK */ @@ -36773,8 +39461,8 @@ static int btreeCopyFile(Btree *pTo, Btree *pFrom){ return SQLITE_BUSY; } - nToPage = sqlite3PagerPagecount(pBtTo->pPager); - nFromPage = sqlite3PagerPagecount(pBtFrom->pPager); + nToPage = pagerPagecount(pBtTo->pPager); + nFromPage = pagerPagecount(pBtFrom->pPager); iSkip = PENDING_BYTE_PAGE(pBtTo); /* Variable nNewPage is the number of pages required to store the @@ -36987,6 +39675,10 @@ SQLITE_PRIVATE int sqlite3BtreeIsInReadTrans(Btree *p){ ** call the nBytes parameter is ignored and a pointer to the same blob ** of memory returned. ** +** If the nBytes parameter is 0 and the blob of memory has not yet been +** allocated, a null pointer is returned. If the blob has already been +** allocated, it is returned as normal. +** ** Just before the shared-btree is closed, the function passed as the ** xFree argument when the memory allocation was made is invoked on the ** blob of allocated memory. This function should not call sqlite3_free() @@ -36995,7 +39687,7 @@ SQLITE_PRIVATE int sqlite3BtreeIsInReadTrans(Btree *p){ SQLITE_PRIVATE void *sqlite3BtreeSchema(Btree *p, int nBytes, void(*xFree)(void *)){ BtShared *pBt = p->pBt; sqlite3BtreeEnter(p); - if( !pBt->pSchema ){ + if( !pBt->pSchema && nBytes ){ pBt->pSchema = sqlite3MallocZero(nBytes); pBt->xFreeSchema = xFree; } @@ -37052,12 +39744,11 @@ SQLITE_PRIVATE int sqlite3BtreePutData(BtCursor *pCsr, u32 offset, u32 amt, void assert( cursorHoldsMutex(pCsr) ); assert( sqlite3_mutex_held(pCsr->pBtree->db->mutex) ); assert(pCsr->isIncrblobHandle); - if( pCsr->eState>=CURSOR_REQUIRESEEK ){ - if( pCsr->eState==CURSOR_FAULT ){ - return pCsr->skip; - }else{ - return SQLITE_ABORT; - } + + restoreCursorPosition(pCsr); + assert( pCsr->eState!=CURSOR_REQUIRESEEK ); + if( pCsr->eState!=CURSOR_VALID ){ + return SQLITE_ABORT; } /* Check some preconditions: @@ -37070,7 +39761,7 @@ SQLITE_PRIVATE int sqlite3BtreePutData(BtCursor *pCsr, u32 offset, u32 amt, void } assert( !pCsr->pBt->readOnly && pCsr->pBt->inTransaction==TRANS_WRITE ); - if( checkReadLocks(pCsr->pBtree, pCsr->pgnoRoot, pCsr) ){ + if( checkReadLocks(pCsr->pBtree, pCsr->pgnoRoot, pCsr, 0) ){ return SQLITE_LOCKED; /* The table pCur points to has a read lock */ } if( pCsr->eState==CURSOR_INVALID || !pCsr->pPage->intKey ){ @@ -37114,6 +39805,8 @@ SQLITE_PRIVATE void sqlite3BtreeCacheOverflow(BtCursor *pCur){ ************************************************************************* ** This file implements a FIFO queue of rowids used for processing ** UPDATE and DELETE statements. +** +** $Id$ */ /* @@ -37132,12 +39825,12 @@ SQLITE_PRIVATE void sqlite3BtreeCacheOverflow(BtCursor *pCur){ ** Allocate a new FifoPage and return a pointer to it. Return NULL if ** we run out of memory. Leave space on the page for nEntry entries. */ -static FifoPage *allocateFifoPage(int nEntry){ +static FifoPage *allocateFifoPage(sqlite3 *db, int nEntry){ FifoPage *pPage; if( nEntry>FIFOSIZE_MAX ){ nEntry = FIFOSIZE_MAX; } - pPage = sqlite3_malloc( sizeof(FifoPage) + sizeof(i64)*(nEntry-1) ); + pPage = sqlite3DbMallocRaw(db, sizeof(FifoPage) + sizeof(i64)*(nEntry-1) ); if( pPage ){ pPage->nSlot = nEntry; pPage->iWrite = 0; @@ -37150,8 +39843,9 @@ static FifoPage *allocateFifoPage(int nEntry){ /* ** Initialize a Fifo structure. */ -SQLITE_PRIVATE void sqlite3VdbeFifoInit(Fifo *pFifo){ +SQLITE_PRIVATE void sqlite3VdbeFifoInit(Fifo *pFifo, sqlite3 *db){ memset(pFifo, 0, sizeof(*pFifo)); + pFifo->db = db; } /* @@ -37163,12 +39857,13 @@ SQLITE_PRIVATE int sqlite3VdbeFifoPush(Fifo *pFifo, i64 val){ FifoPage *pPage; pPage = pFifo->pLast; if( pPage==0 ){ - pPage = pFifo->pLast = pFifo->pFirst = allocateFifoPage(FIFOSIZE_FIRST); + pPage = pFifo->pLast = pFifo->pFirst = + allocateFifoPage(pFifo->db, FIFOSIZE_FIRST); if( pPage==0 ){ return SQLITE_NOMEM; } }else if( pPage->iWrite>=pPage->nSlot ){ - pPage->pNext = allocateFifoPage(pFifo->nEntry); + pPage->pNext = allocateFifoPage(pFifo->db, pFifo->nEntry); if( pPage->pNext==0 ){ return SQLITE_NOMEM; } @@ -37200,7 +39895,7 @@ SQLITE_PRIVATE int sqlite3VdbeFifoPop(Fifo *pFifo, i64 *pVal){ pFifo->nEntry--; if( pPage->iRead>=pPage->iWrite ){ pFifo->pFirst = pPage->pNext; - sqlite3_free(pPage); + sqlite3DbFree(pFifo->db, pPage); if( pFifo->nEntry==0 ){ assert( pFifo->pLast==pPage ); pFifo->pLast = 0; @@ -37221,9 +39916,9 @@ SQLITE_PRIVATE void sqlite3VdbeFifoClear(Fifo *pFifo){ FifoPage *pPage, *pNextPage; for(pPage=pFifo->pFirst; pPage; pPage=pNextPage){ pNextPage = pPage->pNext; - sqlite3_free(pPage); + sqlite3DbFree(pFifo->db, pPage); } - sqlite3VdbeFifoInit(pFifo); + sqlite3VdbeFifoInit(pFifo, pFifo->db); } /************** End of vdbefifo.c ********************************************/ @@ -37244,6 +39939,8 @@ SQLITE_PRIVATE void sqlite3VdbeFifoClear(Fifo *pFifo){ ** stores a single value in the VDBE. Mem is an opaque structure visible ** only within the VDBE. Interface routines refer to a Mem using the ** name sqlite_value +** +** $Id$ */ /* @@ -37307,8 +40004,8 @@ SQLITE_PRIVATE int sqlite3VdbeMemGrow(Mem *pMem, int n, int preserve){ ((pMem->flags&MEM_Static) ? 1 : 0) ); - if( !pMem->zMalloc || sqlite3MallocSize(pMem->zMalloc)<n ){ - n = (n>32?n:32); + if( n<32 ) n = 32; + if( sqlite3DbMallocSize(pMem->db, pMem->zMalloc)<n ){ if( preserve && pMem->z==pMem->zMalloc ){ pMem->z = pMem->zMalloc = sqlite3DbReallocOrFree(pMem->db, pMem->z, n); if( !pMem->z ){ @@ -37316,7 +40013,7 @@ SQLITE_PRIVATE int sqlite3VdbeMemGrow(Mem *pMem, int n, int preserve){ } preserve = 0; }else{ - sqlite3_free(pMem->zMalloc); + sqlite3DbFree(pMem->db, pMem->zMalloc); pMem->zMalloc = sqlite3DbMallocRaw(pMem->db, n); } } @@ -37335,11 +40032,14 @@ SQLITE_PRIVATE int sqlite3VdbeMemGrow(Mem *pMem, int n, int preserve){ } /* -** Make the given Mem object MEM_Dyn. +** Make the given Mem object MEM_Dyn. In other words, make it so +** that any TEXT or BLOB content is stored in memory obtained from +** malloc(). In this way, we know that the memory is safe to be +** overwritten or altered. ** ** Return SQLITE_OK on success or SQLITE_NOMEM if malloc fails. */ -SQLITE_PRIVATE int sqlite3VdbeMemDynamicify(Mem *pMem){ +SQLITE_PRIVATE int sqlite3VdbeMemMakeWriteable(Mem *pMem){ int f; assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) ); expandBlob(pMem); @@ -37386,16 +40086,6 @@ SQLITE_PRIVATE int sqlite3VdbeMemExpandBlob(Mem *pMem){ /* -** Make the given Mem object either MEM_Short or MEM_Dyn so that bytes -** of the Mem.z[] array can be modified. -** -** Return SQLITE_OK on success or SQLITE_NOMEM if malloc fails. -*/ -SQLITE_PRIVATE int sqlite3VdbeMemMakeWriteable(Mem *pMem){ - return sqlite3VdbeMemDynamicify(pMem); -} - -/* ** Make sure the given Mem is \u0000 terminated. */ SQLITE_PRIVATE int sqlite3VdbeMemNulTerminate(Mem *pMem){ @@ -37480,7 +40170,7 @@ SQLITE_PRIVATE int sqlite3VdbeMemFinalize(Mem *pMem, FuncDef *pFunc){ ctx.isError = 0; pFunc->xFinalize(&ctx); assert( 0==(pMem->flags&MEM_Dyn) && !pMem->xDel ); - sqlite3_free(pMem->zMalloc); + sqlite3DbFree(pMem->db, pMem->zMalloc); *pMem = ctx.s; rc = (ctx.isError?SQLITE_ERROR:SQLITE_OK); } @@ -37511,7 +40201,7 @@ SQLITE_PRIVATE void sqlite3VdbeMemReleaseExternal(Mem *p){ */ SQLITE_PRIVATE void sqlite3VdbeMemRelease(Mem *p){ sqlite3VdbeMemReleaseExternal(p); - sqlite3_free(p->zMalloc); + sqlite3DbFree(p->db, p->zMalloc); p->z = 0; p->zMalloc = 0; p->xDel = 0; @@ -37813,6 +40503,7 @@ SQLITE_PRIVATE int sqlite3VdbeMemSetStr( void (*xDel)(void*) /* Destructor function */ ){ int nByte = n; /* New value for pMem->n */ + int iLimit; /* Maximum allowed string or blob size */ int flags = 0; /* New value for pMem->flags */ assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) ); @@ -37823,16 +40514,24 @@ SQLITE_PRIVATE int sqlite3VdbeMemSetStr( return SQLITE_OK; } + if( pMem->db ){ + iLimit = pMem->db->aLimit[SQLITE_LIMIT_LENGTH]; + }else{ + iLimit = SQLITE_MAX_LENGTH; + } flags = (enc==0?MEM_Blob:MEM_Str); if( nByte<0 ){ assert( enc!=0 ); if( enc==SQLITE_UTF8 ){ - for(nByte=0; z[nByte]; nByte++){} + for(nByte=0; nByte<=iLimit && z[nByte]; nByte++){} }else{ - for(nByte=0; z[nByte] | z[nByte+1]; nByte+=2){} + for(nByte=0; nByte<=iLimit && (z[nByte] | z[nByte+1]); nByte+=2){} } flags |= MEM_Term; } + if( nByte>iLimit ){ + return SQLITE_TOOBIG; + } /* The following block sets the new values of Mem.z and Mem.xDel. It ** also sets a flag in local variable "flags" to indicate the memory @@ -37847,6 +40546,10 @@ SQLITE_PRIVATE int sqlite3VdbeMemSetStr( return SQLITE_NOMEM; } memcpy(pMem->z, z, nAlloc); + }else if( xDel==SQLITE_DYNAMIC ){ + sqlite3VdbeMemRelease(pMem); + pMem->zMalloc = pMem->z = (char *)z; + pMem->xDel = 0; }else{ sqlite3VdbeMemRelease(pMem); pMem->z = (char *)z; @@ -38120,7 +40823,7 @@ SQLITE_PRIVATE const void *sqlite3ValueText(sqlite3_value* pVal, u8 enc){ expandBlob(pVal); if( pVal->flags&MEM_Str ){ sqlite3VdbeChangeEncoding(pVal, enc & ~SQLITE_UTF16_ALIGNED); - if( (enc & SQLITE_UTF16_ALIGNED)!=0 && 1==(1&(int)pVal->z) ){ + if( (enc & SQLITE_UTF16_ALIGNED)!=0 && 1==(1&SQLITE_PTR_TO_INT(pVal->z)) ){ assert( (pVal->flags & (MEM_Ephem|MEM_Static))!=0 ); if( sqlite3VdbeMemMakeWriteable(pVal)!=SQLITE_OK ){ return 0; @@ -38182,11 +40885,11 @@ SQLITE_PRIVATE int sqlite3ValueFromExpr( op = pExpr->op; if( op==TK_STRING || op==TK_FLOAT || op==TK_INTEGER ){ - zVal = sqlite3StrNDup((char*)pExpr->token.z, pExpr->token.n); + zVal = sqlite3DbStrNDup(db, (char*)pExpr->token.z, pExpr->token.n); pVal = sqlite3ValueNew(db); if( !zVal || !pVal ) goto no_mem; sqlite3Dequote(zVal); - sqlite3ValueSetStr(pVal, -1, zVal, SQLITE_UTF8, sqlite3_free); + sqlite3ValueSetStr(pVal, -1, zVal, SQLITE_UTF8, SQLITE_DYNAMIC); if( (op==TK_INTEGER || op==TK_FLOAT ) && affinity==SQLITE_AFF_NONE ){ sqlite3ValueApplyAffinity(pVal, SQLITE_AFF_NUMERIC, enc); }else{ @@ -38209,7 +40912,7 @@ SQLITE_PRIVATE int sqlite3ValueFromExpr( nVal = pExpr->token.n - 3; zVal = (char*)pExpr->token.z + 2; sqlite3VdbeMemSetStr(pVal, sqlite3HexToBlob(db, zVal, nVal), nVal/2, - 0, sqlite3_free); + 0, SQLITE_DYNAMIC); } #endif @@ -38218,7 +40921,7 @@ SQLITE_PRIVATE int sqlite3ValueFromExpr( no_mem: db->mallocFailed = 1; - sqlite3_free(zVal); + sqlite3DbFree(db, zVal); sqlite3ValueFree(pVal); *ppVal = 0; return SQLITE_NOMEM; @@ -38243,7 +40946,7 @@ SQLITE_PRIVATE void sqlite3ValueSetStr( SQLITE_PRIVATE void sqlite3ValueFree(sqlite3_value *v){ if( !v ) return; sqlite3VdbeMemRelease((Mem *)v); - sqlite3_free(v); + sqlite3DbFree(((Mem*)v)->db, v); } /* @@ -38533,14 +41236,12 @@ static void resolveP2Values(Vdbe *p, int *pMaxFuncArgs){ for(pOp=p->aOp, i=p->nOp-1; i>=0; i--, pOp++){ u8 opcode = pOp->opcode; - if( opcode==OP_Function ){ + if( opcode==OP_Function || opcode==OP_AggStep ){ if( pOp->p5>nMaxArgs ) nMaxArgs = pOp->p5; - }else if( opcode==OP_AggStep #ifndef SQLITE_OMIT_VIRTUALTABLE - || opcode==OP_VUpdate -#endif - ){ + }else if( opcode==OP_VUpdate ){ if( pOp->p2>nMaxArgs ) nMaxArgs = pOp->p2; +#endif } if( opcode==OP_Halt ){ if( pOp->p1==SQLITE_CONSTRAINT && pOp->p2==OE_Abort ){ @@ -38567,7 +41268,7 @@ static void resolveP2Values(Vdbe *p, int *pMaxFuncArgs){ pOp->p2 = aLabel[-1-pOp->p2]; } } - sqlite3_free(p->aLabel); + sqlite3DbFree(p->db, p->aLabel); p->aLabel = 0; *pMaxFuncArgs = nMaxArgs; @@ -38697,40 +41398,41 @@ SQLITE_PRIVATE void sqlite3VdbeJumpHere(Vdbe *p, int addr){ ** If the input FuncDef structure is ephemeral, then free it. If ** the FuncDef is not ephermal, then do nothing. */ -static void freeEphemeralFunction(FuncDef *pDef){ +static void freeEphemeralFunction(sqlite3 *db, FuncDef *pDef){ if( pDef && (pDef->flags & SQLITE_FUNC_EPHEM)!=0 ){ - sqlite3_free(pDef); + sqlite3DbFree(db, pDef); } } /* ** Delete a P4 value if necessary. */ -static void freeP4(int p4type, void *p3){ - if( p3 ){ +static void freeP4(sqlite3 *db, int p4type, void *p4){ + if( p4 ){ switch( p4type ){ case P4_REAL: case P4_INT64: case P4_MPRINTF: case P4_DYNAMIC: case P4_KEYINFO: + case P4_INTARRAY: case P4_KEYINFO_HANDOFF: { - sqlite3_free(p3); + sqlite3DbFree(db, p4); break; } case P4_VDBEFUNC: { - VdbeFunc *pVdbeFunc = (VdbeFunc *)p3; - freeEphemeralFunction(pVdbeFunc->pFunc); + VdbeFunc *pVdbeFunc = (VdbeFunc *)p4; + freeEphemeralFunction(db, pVdbeFunc->pFunc); sqlite3VdbeDeleteAuxData(pVdbeFunc, 0); - sqlite3_free(pVdbeFunc); + sqlite3DbFree(db, pVdbeFunc); break; } case P4_FUNCDEF: { - freeEphemeralFunction((FuncDef*)p3); + freeEphemeralFunction(db, (FuncDef*)p4); break; } case P4_MEM: { - sqlite3ValueFree((sqlite3_value*)p3); + sqlite3ValueFree((sqlite3_value*)p4); break; } } @@ -38744,8 +41446,9 @@ static void freeP4(int p4type, void *p3){ SQLITE_PRIVATE void sqlite3VdbeChangeToNoop(Vdbe *p, int addr, int N){ if( p && p->aOp ){ VdbeOp *pOp = &p->aOp[addr]; + sqlite3 *db = p->db; while( N-- ){ - freeP4(pOp->p4type, pOp->p4.p); + freeP4(db, pOp->p4type, pOp->p4.p); memset(pOp, 0, sizeof(pOp[0])); pOp->opcode = OP_Noop; pOp++; @@ -38780,11 +41483,13 @@ SQLITE_PRIVATE void sqlite3VdbeChangeToNoop(Vdbe *p, int addr, int N){ */ SQLITE_PRIVATE void sqlite3VdbeChangeP4(Vdbe *p, int addr, const char *zP4, int n){ Op *pOp; + sqlite3 *db; assert( p!=0 ); + db = p->db; assert( p->magic==VDBE_MAGIC_INIT ); - if( p->aOp==0 || p->db->mallocFailed ){ + if( p->aOp==0 || db->mallocFailed ){ if (n != P4_KEYINFO) { - freeP4(n, (void*)*(char**)&zP4); + freeP4(db, n, (void*)*(char**)&zP4); } return; } @@ -38794,12 +41499,12 @@ SQLITE_PRIVATE void sqlite3VdbeChangeP4(Vdbe *p, int addr, const char *zP4, int if( addr<0 ) return; } pOp = &p->aOp[addr]; - freeP4(pOp->p4type, pOp->p4.p); + freeP4(db, pOp->p4type, pOp->p4.p); pOp->p4.p = 0; if( n==P4_INT32 ){ /* Note: this cast is safe, because the origin data point was an int ** that was cast to a (const char *). */ - pOp->p4.i = (int)zP4; + pOp->p4.i = SQLITE_PTR_TO_INT(zP4); pOp->p4type = n; }else if( zP4==0 ){ pOp->p4.p = 0; @@ -38810,22 +41515,16 @@ SQLITE_PRIVATE void sqlite3VdbeChangeP4(Vdbe *p, int addr, const char *zP4, int nField = ((KeyInfo*)zP4)->nField; nByte = sizeof(*pKeyInfo) + (nField-1)*sizeof(pKeyInfo->aColl[0]) + nField; - pKeyInfo = sqlite3_malloc( nByte ); + pKeyInfo = sqlite3Malloc( nByte ); pOp->p4.pKeyInfo = pKeyInfo; if( pKeyInfo ){ + u8 *aSortOrder; memcpy(pKeyInfo, zP4, nByte); - /* In the current implementation, P4_KEYINFO is only ever used on - ** KeyInfo structures that have no aSortOrder component. Elements - ** with an aSortOrder always use P4_KEYINFO_HANDOFF. So we do not - ** need to bother with duplicating the aSortOrder. */ - assert( pKeyInfo->aSortOrder==0 ); -#if 0 aSortOrder = pKeyInfo->aSortOrder; if( aSortOrder ){ pKeyInfo->aSortOrder = (unsigned char*)&pKeyInfo->aColl[nField]; memcpy(pKeyInfo->aSortOrder, aSortOrder, nField); } -#endif pOp->p4type = P4_KEYINFO; }else{ p->db->mallocFailed = 1; @@ -38846,7 +41545,10 @@ SQLITE_PRIVATE void sqlite3VdbeChangeP4(Vdbe *p, int addr, const char *zP4, int #ifndef NDEBUG /* -** Change the comment on the the most recently coded instruction. +** Change the comment on the the most recently coded instruction. Or +** insert a No-op and add the comment to that new instruction. This +** makes the code easier to read during debugging. None of this happens +** in a production build. */ SQLITE_PRIVATE void sqlite3VdbeComment(Vdbe *p, const char *zFormat, ...){ va_list ap; @@ -38855,12 +41557,25 @@ SQLITE_PRIVATE void sqlite3VdbeComment(Vdbe *p, const char *zFormat, ...){ if( p->nOp ){ char **pz = &p->aOp[p->nOp-1].zComment; va_start(ap, zFormat); - sqlite3_free(*pz); + sqlite3DbFree(p->db, *pz); *pz = sqlite3VMPrintf(p->db, zFormat, ap); va_end(ap); } } -#endif +SQLITE_PRIVATE void sqlite3VdbeNoopComment(Vdbe *p, const char *zFormat, ...){ + va_list ap; + sqlite3VdbeAddOp0(p, OP_Noop); + assert( p->nOp>0 || p->aOp==0 ); + assert( p->aOp==0 || p->aOp[p->nOp-1].zComment==0 || p->db->mallocFailed ); + if( p->nOp ){ + char **pz = &p->aOp[p->nOp-1].zComment; + va_start(ap, zFormat); + sqlite3DbFree(p->db, *pz); + *pz = sqlite3VMPrintf(p->db, zFormat, ap); + va_end(ap); + } +} +#endif /* NDEBUG */ /* ** Return the opcode for a given address. @@ -38881,6 +41596,7 @@ static char *displayP4(Op *pOp, char *zTemp, int nTemp){ char *zP4 = zTemp; assert( nTemp>=20 ); switch( pOp->p4type ){ + case P4_KEYINFO_STATIC: case P4_KEYINFO: { int i, j; KeyInfo *pKeyInfo = pOp->p4.pKeyInfo; @@ -38951,6 +41667,10 @@ static char *displayP4(Op *pOp, char *zTemp, int nTemp){ break; } #endif + case P4_INTARRAY: { + sqlite3_snprintf(nTemp, zTemp, "intarray"); + break; + } default: { zP4 = pOp->p4.z; if( zP4==0 ){ @@ -39005,17 +41725,13 @@ SQLITE_PRIVATE void sqlite3VdbePrintOp(FILE *pOut, int pc, Op *pOp){ /* ** Release an array of N Mem elements */ -static void releaseMemArray(Mem *p, int N, int freebuffers){ +static void releaseMemArray(Mem *p, int N){ if( p && N ){ sqlite3 *db = p->db; int malloc_failed = db->mallocFailed; while( N-->0 ){ assert( N<2 || p[0].db==p[1].db ); - if( freebuffers ){ - sqlite3VdbeMemRelease(p); - }else{ - sqlite3VdbeMemReleaseExternal(p); - } + sqlite3VdbeMemRelease(p); p->flags = MEM_Null; p++; } @@ -39032,7 +41748,7 @@ SQLITE_PRIVATE int sqlite3VdbeReleaseBuffers(Vdbe *p){ Mem *pMem = &p->aMem[ii]; if( pMem->z && pMem->flags&MEM_Dyn ){ assert( !pMem->xDel ); - nFree += sqlite3MallocSize(pMem->z); + nFree += sqlite3DbMallocSize(pMem->db, pMem->z); sqlite3VdbeMemRelease(pMem); } } @@ -39070,7 +41786,7 @@ SQLITE_PRIVATE int sqlite3VdbeList( ** the result, result columns may become dynamic if the user calls ** sqlite3_column_text16(), causing a translation to UTF-16 encoding. */ - releaseMemArray(pMem, p->nMem, 1); + releaseMemArray(pMem, p->nMem); do{ i = p->pc++; @@ -39081,7 +41797,7 @@ SQLITE_PRIVATE int sqlite3VdbeList( }else if( db->u1.isInterrupted ){ p->rc = SQLITE_INTERRUPT; rc = SQLITE_ERROR; - sqlite3SetString(&p->zErrMsg, sqlite3ErrStr(p->rc), (char*)0); + sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3ErrStr(p->rc)); }else{ char *z; Op *pOp = &p->aOp[i]; @@ -39306,7 +42022,6 @@ SQLITE_PRIVATE void sqlite3VdbeMakeReady( p->pc = -1; p->rc = SQLITE_OK; p->uniqueCnt = 0; - p->returnDepth = 0; p->errorAction = OE_Abort; p->explain |= isExplain; p->magic = VDBE_MAGIC_RUN; @@ -39333,11 +42048,12 @@ SQLITE_PRIVATE void sqlite3VdbeFreeCursor(Vdbe *p, Cursor *pCx){ if( pCx==0 ){ return; } - if( pCx->pCursor ){ - sqlite3BtreeCloseCursor(pCx->pCursor); - } if( pCx->pBt ){ sqlite3BtreeClose(pCx->pBt); + /* The pCx->pCursor will be close automatically, if it exists, by + ** the call above. */ + }else if( pCx->pCursor ){ + sqlite3BtreeCloseCursor(pCx->pCursor); } #ifndef SQLITE_OMIT_VIRTUALTABLE if( pCx->pVtabCursor ){ @@ -39351,11 +42067,8 @@ SQLITE_PRIVATE void sqlite3VdbeFreeCursor(Vdbe *p, Cursor *pCx){ } #endif if( !pCx->ephemPseudoTable ){ - sqlite3_free(pCx->pData); + sqlite3DbFree(p->db, pCx->pData); } - /* memset(pCx, 0, sizeof(Cursor)); */ - /* sqlite3_free(pCx->aType); */ - /* sqlite3_free(pCx); */ } /* @@ -39381,24 +42094,25 @@ static void closeAllCursorsExceptActiveVtabs(Vdbe *p){ ** sorters that were left open. It also deletes the values of ** variables in the aVar[] array. */ -static void Cleanup(Vdbe *p, int freebuffers){ +static void Cleanup(Vdbe *p){ int i; + sqlite3 *db = p->db; closeAllCursorsExceptActiveVtabs(p); for(i=1; i<=p->nMem; i++){ MemSetTypeFlag(&p->aMem[i], MEM_Null); } - releaseMemArray(&p->aMem[1], p->nMem, freebuffers); + releaseMemArray(&p->aMem[1], p->nMem); sqlite3VdbeFifoClear(&p->sFifo); if( p->contextStack ){ for(i=0; i<p->contextStackTop; i++){ sqlite3VdbeFifoClear(&p->contextStack[i].sFifo); } - sqlite3_free(p->contextStack); + sqlite3DbFree(db, p->contextStack); } p->contextStack = 0; p->contextStackDepth = 0; p->contextStackTop = 0; - sqlite3_free(p->zErrMsg); + sqlite3DbFree(db, p->zErrMsg); p->zErrMsg = 0; p->pResultSet = 0; } @@ -39412,12 +42126,13 @@ static void Cleanup(Vdbe *p, int freebuffers){ SQLITE_PRIVATE void sqlite3VdbeSetNumCols(Vdbe *p, int nResColumn){ Mem *pColName; int n; + sqlite3 *db = p->db; - releaseMemArray(p->aColName, p->nResColumn*COLNAME_N, 1); - sqlite3_free(p->aColName); + releaseMemArray(p->aColName, p->nResColumn*COLNAME_N); + sqlite3DbFree(db, p->aColName); n = nResColumn*COLNAME_N; p->nResColumn = nResColumn; - p->aColName = pColName = (Mem*)sqlite3DbMallocZero(p->db, sizeof(Mem)*n ); + p->aColName = pColName = (Mem*)sqlite3DbMallocZero(db, sizeof(Mem)*n ); if( p->aColName==0 ) return; while( n-- > 0 ){ pColName->flags = MEM_Null; @@ -39434,7 +42149,7 @@ SQLITE_PRIVATE void sqlite3VdbeSetNumCols(Vdbe *p, int nResColumn){ ** ** If N==P4_STATIC it means that zName is a pointer to a constant static ** string and we can just copy the pointer. If it is P4_DYNAMIC, then -** the string is freed using sqlite3_free() when the vdbe is finished with +** the string is freed using sqlite3DbFree(db, ) when the vdbe is finished with ** it. Otherwise, N bytes of zName are copied. */ SQLITE_PRIVATE int sqlite3VdbeSetColName(Vdbe *p, int idx, int var, const char *zName, int N){ @@ -39463,7 +42178,7 @@ SQLITE_PRIVATE int sqlite3VdbeSetColName(Vdbe *p, int idx, int var, const char * ** write-transaction spanning more than one database file, this routine ** takes care of the master journal trickery. */ -static int vdbeCommit(sqlite3 *db){ +static int vdbeCommit(sqlite3 *db, Vdbe *p){ int i; int nTrans = 0; /* Number of databases with an active write-transaction */ int rc = SQLITE_OK; @@ -39475,7 +42190,7 @@ static int vdbeCommit(sqlite3 *db){ ** required, as an xSync() callback may add an attached database ** to the transaction. */ - rc = sqlite3VtabSync(db, rc); + rc = sqlite3VtabSync(db, &p->zErrMsg); if( rc!=SQLITE_OK ){ return rc; } @@ -39509,9 +42224,9 @@ static int vdbeCommit(sqlite3 *db){ ** master-journal. ** ** If the return value of sqlite3BtreeGetFilename() is a zero length - ** string, it means the main database is :memory:. In that case we do - ** not support atomic multi-file commits, so use the simple case then - ** too. + ** string, it means the main database is :memory: or a temp file. In + ** that case we do not support atomic multi-file commits, so use the + ** simple case then too. */ if( 0==strlen(sqlite3BtreeGetFilename(db->aDb[0].pBt)) || nTrans<=1 ){ for(i=0; rc==SQLITE_OK && i<db->nDb; i++){ @@ -39549,21 +42264,20 @@ static int vdbeCommit(sqlite3 *db){ char const *zMainFile = sqlite3BtreeGetFilename(db->aDb[0].pBt); sqlite3_file *pMaster = 0; i64 offset = 0; + int res; /* Select a master journal file name */ do { u32 random; - sqlite3_free(zMaster); + sqlite3DbFree(db, zMaster); sqlite3_randomness(sizeof(random), &random); zMaster = sqlite3MPrintf(db, "%s-mj%08X", zMainFile, random&0x7fffffff); if( !zMaster ){ return SQLITE_NOMEM; } - rc = sqlite3OsAccess(pVfs, zMaster, SQLITE_ACCESS_EXISTS); - }while( rc==1 ); - if( rc!=0 ){ - rc = SQLITE_IOERR_NOMEM; - }else{ + rc = sqlite3OsAccess(pVfs, zMaster, SQLITE_ACCESS_EXISTS, &res); + }while( rc==SQLITE_OK && res ); + if( rc==SQLITE_OK ){ /* Open the master journal. */ rc = sqlite3OsOpenMalloc(pVfs, zMaster, &pMaster, SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE| @@ -39571,7 +42285,7 @@ static int vdbeCommit(sqlite3 *db){ ); } if( rc!=SQLITE_OK ){ - sqlite3_free(zMaster); + sqlite3DbFree(db, zMaster); return rc; } @@ -39595,7 +42309,7 @@ static int vdbeCommit(sqlite3 *db){ if( rc!=SQLITE_OK ){ sqlite3OsCloseFree(pMaster); sqlite3OsDelete(pVfs, zMaster, 0); - sqlite3_free(zMaster); + sqlite3DbFree(db, zMaster); return rc; } } @@ -39610,7 +42324,7 @@ static int vdbeCommit(sqlite3 *db){ && (rc=sqlite3OsSync(pMaster, SQLITE_SYNC_NORMAL))!=SQLITE_OK) ){ sqlite3OsCloseFree(pMaster); sqlite3OsDelete(pVfs, zMaster, 0); - sqlite3_free(zMaster); + sqlite3DbFree(db, zMaster); return rc; } @@ -39632,7 +42346,7 @@ static int vdbeCommit(sqlite3 *db){ } sqlite3OsCloseFree(pMaster); if( rc!=SQLITE_OK ){ - sqlite3_free(zMaster); + sqlite3DbFree(db, zMaster); return rc; } @@ -39641,7 +42355,7 @@ static int vdbeCommit(sqlite3 *db){ ** transaction files are deleted. */ rc = sqlite3OsDelete(pVfs, zMaster, 1); - sqlite3_free(zMaster); + sqlite3DbFree(db, zMaster); zMaster = 0; if( rc ){ return rc; @@ -39655,14 +42369,14 @@ static int vdbeCommit(sqlite3 *db){ ** may be lying around. Returning an error code won't help matters. */ disable_simulated_io_errors(); - sqlite3FaultBeginBenign(SQLITE_FAULTINJECTOR_MALLOC); + sqlite3BeginBenignMalloc(); for(i=0; i<db->nDb; i++){ Btree *pBt = db->aDb[i].pBt; if( pBt ){ sqlite3BtreeCommitPhaseTwo(pBt); } } - sqlite3FaultEndBenign(SQLITE_FAULTINJECTOR_MALLOC); + sqlite3EndBenignMalloc(); enable_simulated_io_errors(); sqlite3VtabCommit(db); @@ -39840,7 +42554,7 @@ SQLITE_PRIVATE int sqlite3VdbeHalt(Vdbe *p){ ** successful or hit an 'OR FAIL' constraint. This means a commit ** is required. */ - int rc = vdbeCommit(db); + int rc = vdbeCommit(db, p); if( rc==SQLITE_BUSY ){ sqlite3BtreeMutexArrayLeave(&p->aMutex); return SQLITE_BUSY; @@ -39883,7 +42597,8 @@ SQLITE_PRIVATE int sqlite3VdbeHalt(Vdbe *p){ rc = xFunc(pBt); if( rc && (p->rc==SQLITE_OK || p->rc==SQLITE_CONSTRAINT) ){ p->rc = rc; - sqlite3SetString(&p->zErrMsg, 0); + sqlite3DbFree(db, p->zErrMsg); + p->zErrMsg = 0; } } } @@ -39943,7 +42658,7 @@ SQLITE_PRIVATE void sqlite3VdbeResetStepResult(Vdbe *p){ ** virtual machine from VDBE_MAGIC_RUN or VDBE_MAGIC_HALT back to ** VDBE_MAGIC_INIT. */ -SQLITE_PRIVATE int sqlite3VdbeReset(Vdbe *p, int freebuffers){ +SQLITE_PRIVATE int sqlite3VdbeReset(Vdbe *p){ sqlite3 *db; db = p->db; @@ -39962,8 +42677,9 @@ SQLITE_PRIVATE int sqlite3VdbeReset(Vdbe *p, int freebuffers){ */ if( p->pc>=0 ){ if( p->zErrMsg ){ - sqlite3ValueSetStr(db->pErr,-1,p->zErrMsg,SQLITE_UTF8,sqlite3_free); + sqlite3ValueSetStr(db->pErr,-1,p->zErrMsg,SQLITE_UTF8,SQLITE_TRANSIENT); db->errCode = p->rc; + sqlite3DbFree(db, p->zErrMsg); p->zErrMsg = 0; }else if( p->rc ){ sqlite3Error(db, p->rc, 0); @@ -39976,13 +42692,14 @@ SQLITE_PRIVATE int sqlite3VdbeReset(Vdbe *p, int freebuffers){ ** called), set the database error in this case as well. */ sqlite3Error(db, p->rc, 0); - sqlite3ValueSetStr(db->pErr, -1, p->zErrMsg, SQLITE_UTF8, sqlite3_free); + sqlite3ValueSetStr(db->pErr, -1, p->zErrMsg, SQLITE_UTF8, SQLITE_TRANSIENT); + sqlite3DbFree(db, p->zErrMsg); p->zErrMsg = 0; } /* Reclaim all memory used by the VDBE */ - Cleanup(p, freebuffers); + Cleanup(p); /* Save profiling information from this VDBE run. */ @@ -40009,7 +42726,6 @@ SQLITE_PRIVATE int sqlite3VdbeReset(Vdbe *p, int freebuffers){ } #endif p->magic = VDBE_MAGIC_INIT; - p->aborted = 0; return p->rc & db->errMask; } @@ -40020,12 +42736,11 @@ SQLITE_PRIVATE int sqlite3VdbeReset(Vdbe *p, int freebuffers){ SQLITE_PRIVATE int sqlite3VdbeFinalize(Vdbe *p){ int rc = SQLITE_OK; if( p->magic==VDBE_MAGIC_RUN || p->magic==VDBE_MAGIC_HALT ){ - rc = sqlite3VdbeReset(p, 1); + rc = sqlite3VdbeReset(p); assert( (rc & p->db->errMask)==rc ); }else if( p->magic!=VDBE_MAGIC_INIT ){ return SQLITE_MISUSE; } - releaseMemArray(&p->aMem[1], p->nMem, 1); sqlite3VdbeDelete(p); return rc; } @@ -40054,13 +42769,15 @@ SQLITE_PRIVATE void sqlite3VdbeDeleteAuxData(VdbeFunc *pVdbeFunc, int mask){ */ SQLITE_PRIVATE void sqlite3VdbeDelete(Vdbe *p){ int i; + sqlite3 *db; + if( p==0 ) return; - Cleanup(p, 1); + db = p->db; if( p->pPrev ){ p->pPrev->pNext = p->pNext; }else{ - assert( p->db->pVdbe==p ); - p->db->pVdbe = p->pNext; + assert( db->pVdbe==p ); + db->pVdbe = p->pNext; } if( p->pNext ){ p->pNext->pPrev = p->pPrev; @@ -40068,23 +42785,23 @@ SQLITE_PRIVATE void sqlite3VdbeDelete(Vdbe *p){ if( p->aOp ){ Op *pOp = p->aOp; for(i=0; i<p->nOp; i++, pOp++){ - freeP4(pOp->p4type, pOp->p4.p); + freeP4(db, pOp->p4type, pOp->p4.p); #ifdef SQLITE_DEBUG - sqlite3_free(pOp->zComment); + sqlite3DbFree(db, pOp->zComment); #endif } - sqlite3_free(p->aOp); + sqlite3DbFree(db, p->aOp); } - releaseMemArray(p->aVar, p->nVar, 1); - sqlite3_free(p->aLabel); + releaseMemArray(p->aVar, p->nVar); + sqlite3DbFree(db, p->aLabel); if( p->aMem ){ - sqlite3_free(&p->aMem[1]); + sqlite3DbFree(db, &p->aMem[1]); } - releaseMemArray(p->aColName, p->nResColumn*COLNAME_N, 1); - sqlite3_free(p->aColName); - sqlite3_free(p->zSql); + releaseMemArray(p->aColName, p->nResColumn*COLNAME_N); + sqlite3DbFree(db, p->aColName); + sqlite3DbFree(db, p->zSql); p->magic = VDBE_MAGIC_DEAD; - sqlite3_free(p); + sqlite3DbFree(db, p); } /* @@ -40113,6 +42830,14 @@ SQLITE_PRIVATE int sqlite3VdbeCursorMoveto(Cursor *p){ #endif p->deferredMoveto = 0; p->cacheStatus = CACHE_STALE; + }else if( p->pCursor ){ + int hasMoved; + int rc = sqlite3BtreeCursorHasMoved(p->pCursor, &hasMoved); + if( rc ) return rc; + if( hasMoved ){ + p->cacheStatus = CACHE_STALE; + p->nullRow = 1; + } } return SQLITE_OK; } @@ -40122,9 +42847,9 @@ SQLITE_PRIVATE int sqlite3VdbeCursorMoveto(Cursor *p){ ** ** sqlite3VdbeSerialType() ** sqlite3VdbeSerialTypeLen() -** sqlite3VdbeSerialRead() ** sqlite3VdbeSerialLen() -** sqlite3VdbeSerialWrite() +** sqlite3VdbeSerialPut() +** sqlite3VdbeSerialGet() ** ** encapsulate the code that serializes values for storage in SQLite ** data and index records. Each serialized value consists of a @@ -40446,7 +43171,8 @@ SQLITE_PRIVATE UnpackedRecord *sqlite3VdbeRecordUnpack( const unsigned char *aKey = (const unsigned char *)pKey; UnpackedRecord *p; int nByte; - int i, idx, d; + int idx, d; + u16 u; /* Unsigned loop counter */ u32 szHdr; Mem *pMem; @@ -40466,8 +43192,8 @@ SQLITE_PRIVATE UnpackedRecord *sqlite3VdbeRecordUnpack( p->aMem = pMem = &((Mem*)p)[1]; idx = getVarint32(aKey, szHdr); d = szHdr; - i = 0; - while( idx<szHdr && i<p->nField ){ + u = 0; + while( idx<szHdr && u<p->nField ){ u32 serial_type; idx += getVarint32( aKey+idx, serial_type); @@ -40478,9 +43204,9 @@ SQLITE_PRIVATE UnpackedRecord *sqlite3VdbeRecordUnpack( pMem->zMalloc = 0; d += sqlite3VdbeSerialGet(&aKey[d], serial_type, pMem); pMem++; - i++; + u++; } - p->nField = i; + p->nField = u; return (void*)p; } @@ -40499,7 +43225,7 @@ SQLITE_PRIVATE void sqlite3VdbeDeleteUnpackedRecord(UnpackedRecord *p){ } } if( p->needFree ){ - sqlite3_free(p); + sqlite3DbFree(p->pKeyInfo->db, p); } } } @@ -40594,13 +43320,17 @@ SQLITE_PRIVATE int sqlite3VdbeRecordCompare( ** an integer rowid). This routine returns the number of bytes in ** that integer. */ -SQLITE_PRIVATE int sqlite3VdbeIdxRowidLen(const u8 *aKey){ +SQLITE_PRIVATE int sqlite3VdbeIdxRowidLen(const u8 *aKey, int nKey, int *pRowidLen){ u32 szHdr; /* Size of the header */ u32 typeRowid; /* Serial type of the rowid */ (void)getVarint32(aKey, szHdr); + if( szHdr>nKey ){ + return SQLITE_CORRUPT_BKPT; + } (void)getVarint32(&aKey[szHdr-1], typeRowid); - return sqlite3VdbeSerialTypeLen(typeRowid); + *pRowidLen = sqlite3VdbeSerialTypeLen(typeRowid); + return SQLITE_OK; } @@ -40669,11 +43399,11 @@ SQLITE_PRIVATE int sqlite3VdbeIdxKeyCompare( m.db = 0; m.flags = 0; m.zMalloc = 0; - rc = sqlite3VdbeMemFromBtree(pC->pCursor, 0, nCellKey, 1, &m); - if( rc ){ + if( (rc = sqlite3VdbeMemFromBtree(pC->pCursor, 0, nCellKey, 1, &m)) + || (rc = sqlite3VdbeIdxRowidLen((u8*)m.z, m.n, &lenRowid)) + ){ return rc; } - lenRowid = sqlite3VdbeIdxRowidLen((u8*)m.z); if( !pUnpacked ){ pRec = sqlite3VdbeRecordUnpack(pC->pKeyInfo, nKey, pKey, zSpace, sizeof(zSpace)); @@ -40749,6 +43479,8 @@ SQLITE_PRIVATE sqlite3 *sqlite3VdbeDb(Vdbe *v){ ** ** This file contains code use to implement APIs that are part of the ** VDBE. +** +** $Id$ */ #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT @@ -40801,10 +43533,10 @@ static int stmtLruCheck(){ ** is protected by the SQLITE_MUTEX_STATIC_LRU mutex. */ static void stmtLruAdd(Vdbe *p){ - sqlite3_mutex_enter(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_LRU2)); + sqlite3_mutex_enter(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_LRU2)); if( p->pLruPrev || p->pLruNext || sqlite3LruStatements.pFirst==p ){ - sqlite3_mutex_leave(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_LRU2)); + sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_LRU2)); return; } @@ -40823,7 +43555,7 @@ static void stmtLruAdd(Vdbe *p){ assert( stmtLruCheck() ); - sqlite3_mutex_leave(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_LRU2)); + sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_LRU2)); } /* @@ -40856,9 +43588,9 @@ static void stmtLruRemoveNomutex(Vdbe *p){ ** statement is not currently part of the list, this call is a no-op. */ static void stmtLruRemove(Vdbe *p){ - sqlite3_mutex_enter(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_LRU2)); + sqlite3_mutex_enter(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_LRU2)); stmtLruRemoveNomutex(p); - sqlite3_mutex_leave(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_LRU2)); + sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_LRU2)); } /* @@ -40870,7 +43602,7 @@ SQLITE_PRIVATE int sqlite3VdbeReleaseMemory(int n){ Vdbe *pNext; int nFree = 0; - sqlite3_mutex_enter(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_LRU2)); + sqlite3_mutex_enter(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_LRU2)); for(p=sqlite3LruStatements.pFirst; p && nFree<n; p=pNext){ pNext = p->pLruNext; @@ -40885,7 +43617,7 @@ SQLITE_PRIVATE int sqlite3VdbeReleaseMemory(int n){ sqlite3_mutex_leave(p->db->mutex); } } - sqlite3_mutex_leave(sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_LRU2)); + sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_LRU2)); return nFree; } @@ -40961,7 +43693,7 @@ SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt){ }else{ Vdbe *v = (Vdbe*)pStmt; sqlite3_mutex_enter(v->db->mutex); - rc = sqlite3VdbeReset(v, 1); + rc = sqlite3VdbeReset(v); stmtLruAdd(v); sqlite3VdbeMakeReady(v, -1, 0, 0, 0); assert( (rc & (v->db->errMask))==rc ); @@ -41168,9 +43900,6 @@ static int sqlite3Step(Vdbe *p){ db = p->db; assert( !db->mallocFailed ); - if( p->aborted ){ - return SQLITE_ABORT; - } if( p->pc<=0 && p->expired ){ if( p->rc==SQLITE_OK ){ p->rc = SQLITE_SCHEMA; @@ -41230,14 +43959,16 @@ static int sqlite3Step(Vdbe *p){ } #endif - sqlite3Error(p->db, rc, 0); + db->errCode = rc; + /*sqlite3Error(p->db, rc, 0);*/ p->rc = sqlite3ApiExit(p->db, p->rc); end_of_step: assert( (rc&0xff)==rc ); if( p->zSql && (rc&0xff)<SQLITE_ROW ){ /* This behavior occurs if sqlite3_prepare_v2() was used to build ** the prepared statement. Return error codes directly */ - sqlite3Error(p->db, p->rc, 0); + p->db->errCode = p->rc; + /* sqlite3Error(p->db, p->rc, 0); */ return p->rc; }else{ /* This is for legacy sqlite3_prepare() builds and when the code @@ -41287,7 +44018,7 @@ SQLITE_API int sqlite3_step(sqlite3_stmt *pStmt){ ** sqlite3_errmsg() and sqlite3_errcode(). */ const char *zErr = (const char *)sqlite3_value_text(db->pErr); - sqlite3_free(v->zErrMsg); + sqlite3DbFree(db, v->zErrMsg); if( !db->mallocFailed ){ v->zErrMsg = sqlite3DbStrDup(db, zErr); } else { @@ -41864,6 +44595,9 @@ SQLITE_API int sqlite3_bind_value(sqlite3_stmt *pStmt, int i, const sqlite3_valu rc = vdbeUnbind(p, i); if( rc==SQLITE_OK ){ rc = sqlite3VdbeMemCopy(&p->aVar[i-1], pValue); + if( rc==SQLITE_OK ){ + rc = sqlite3VdbeChangeEncoding(&p->aVar[i-1], ENC(p->db)); + } } rc = sqlite3ApiExit(p->db, rc); sqlite3_mutex_leave(p->db->mutex); @@ -41987,6 +44721,24 @@ SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt *pStmt){ return pStmt ? ((Vdbe*)pStmt)->db : 0; } +/* +** Return a pointer to the next prepared statement after pStmt associated +** with database connection pDb. If pStmt is NULL, return the first +** prepared statement for the database connection. Return NULL if there +** are no more. +*/ +SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt){ + sqlite3_stmt *pNext; + sqlite3_mutex_enter(pDb->mutex); + if( pStmt==0 ){ + pNext = (sqlite3_stmt*)pDb->pVdbe; + }else{ + pNext = (sqlite3_stmt*)((Vdbe*)pStmt)->pNext; + } + sqlite3_mutex_leave(pDb->mutex); + return pNext; +} + /************** End of vdbeapi.c *********************************************/ /************** Begin file vdbe.c ********************************************/ /* @@ -42020,7 +44772,7 @@ SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt *pStmt){ ** Computation results are stored on a set of registers numbered beginning ** with 1 and going up to Vdbe.nMem. Each register can store ** either an integer, a null-terminated string, a floating point -** number, or the SQL "NULL" value. An inplicit conversion from one +** number, or the SQL "NULL" value. An implicit conversion from one ** type to the other occurs as necessary. ** ** Most of the code in this file is taken up by the sqlite3VdbeExec() @@ -42063,7 +44815,7 @@ SQLITE_API int sqlite3_interrupt_count = 0; /* ** The next global variable is incremented each type the OP_Sort opcode ** is executed. The test procedures use this information to make sure that -** sorting is occurring or not occuring at appropriate times. This variable +** sorting is occurring or not occurring at appropriate times. This variable ** has no function other than to help verify the correct operation of the ** library. */ @@ -42133,7 +44885,7 @@ static void updateMaxBlobsize(Mem *p){ #define ExpandBlob(P) (((P)->flags&MEM_Zero)?sqlite3VdbeMemExpandBlob(P):0) /* -** Argument pMem points at a regiser that will be passed to a +** Argument pMem points at a register that will be passed to a ** user-defined function or returned to the user as the result of a query. ** The second argument, 'db_enc' is the text encoding used by the vdbe for ** register variables. This routine sets the pMem->enc and pMem->type @@ -42446,25 +45198,111 @@ static void registerTrace(FILE *out, int iReg, Mem *p){ #endif #ifdef SQLITE_DEBUG -# define REGISTER_TRACE(R,M) if(p->trace&&R>0)registerTrace(p->trace,R,M) +# define REGISTER_TRACE(R,M) if(p->trace)registerTrace(p->trace,R,M) #else # define REGISTER_TRACE(R,M) #endif #ifdef VDBE_PROFILE + +/* +** hwtime.h contains inline assembler code for implementing +** high-performance timing routines. +*/ +/************** Include hwtime.h in the middle of vdbe.c *********************/ +/************** Begin file hwtime.h ******************************************/ +/* +** 2008 May 27 +** +** The author disclaims copyright to this source code. In place of +** a legal notice, here is a blessing: +** +** May you do good and not evil. +** May you find forgiveness for yourself and forgive others. +** May you share freely, never taking more than you give. +** +****************************************************************************** +** +** This file contains inline asm code for retrieving "high-performance" +** counters for x86 class CPUs. +** +** $Id$ +*/ +#ifndef _HWTIME_H_ +#define _HWTIME_H_ + /* -** The following routine only works on pentium-class processors. +** The following routine only works on pentium-class (or newer) processors. ** It uses the RDTSC opcode to read the cycle count value out of the ** processor and returns that value. This can be used for high-res ** profiling. */ -__inline__ unsigned long long int hwtime(void){ - unsigned int lo, hi; - /* We cannot use "=A", since this would use %rax on x86_64 */ - __asm__ __volatile__ ("rdtsc" : "=a" (lo), "=d" (hi)); - return (unsigned long long int)hi << 32 | lo; -} +#if (defined(__GNUC__) || defined(_MSC_VER)) && \ + (defined(i386) || defined(__i386__) || defined(_M_IX86)) + + #if defined(__GNUC__) + + __inline__ sqlite_uint64 sqlite3Hwtime(void){ + unsigned int lo, hi; + __asm__ __volatile__ ("rdtsc" : "=a" (lo), "=d" (hi)); + return (sqlite_uint64)hi << 32 | lo; + } + + #elif defined(_MSC_VER) + + __declspec(naked) __inline sqlite_uint64 __cdecl sqlite3Hwtime(void){ + __asm { + rdtsc + ret ; return value at EDX:EAX + } + } + + #endif + +#elif (defined(__GNUC__) && defined(__x86_64__)) + + __inline__ sqlite_uint64 sqlite3Hwtime(void){ + unsigned long val; + __asm__ __volatile__ ("rdtsc" : "=A" (val)); + return val; + } + +#elif (defined(__GNUC__) && defined(__ppc__)) + + __inline__ sqlite_uint64 sqlite3Hwtime(void){ + unsigned long long retval; + unsigned long junk; + __asm__ __volatile__ ("\n\ + 1: mftbu %1\n\ + mftb %L0\n\ + mftbu %0\n\ + cmpw %0,%1\n\ + bne 1b" + : "=r" (retval), "=r" (junk)); + return retval; + } + +#else + + #error Need implementation of sqlite3Hwtime() for your platform. + + /* + ** To compile without implementing sqlite3Hwtime() for your platform, + ** you can remove the above #error and use the following + ** stub function. You will lose timing support for many + ** of the debugging and testing utilities, but it should at + ** least compile and run. + */ +SQLITE_PRIVATE sqlite_uint64 sqlite3Hwtime(void){ return ((sqlite_uint64)0); } + +#endif + +#endif /* !defined(_HWTIME_H_) */ + +/************** End of hwtime.h **********************************************/ +/************** Continuing where we left off in vdbe.c ***********************/ + #endif /* @@ -42480,6 +45318,22 @@ __inline__ unsigned long long int hwtime(void){ #define CHECK_FOR_INTERRUPT \ if( db->u1.isInterrupted ) goto abort_due_to_interrupt; +#ifdef SQLITE_DEBUG +static int fileExists(sqlite3 *db, const char *zFile){ + int res = 0; + int rc = SQLITE_OK; +#ifdef SQLITE_TEST + /* If we are currently testing IO errors, then do not call OsAccess() to + ** test for the presence of zFile. This is because any IO error that + ** occurs here will not be reported, causing the test to fail. + */ + extern int sqlite3_io_error_pending; + if( sqlite3_io_error_pending<=0 ) +#endif + rc = sqlite3OsAccess(db->pVfs, zFile, SQLITE_ACCESS_EXISTS, &res); + return (res && rc==SQLITE_OK); +} +#endif /* ** Execute as much of a VDBE program as we can then return. @@ -42523,8 +45377,10 @@ SQLITE_PRIVATE int sqlite3VdbeExec( Mem *pIn1, *pIn2, *pIn3; /* Input operands */ Mem *pOut; /* Output operand */ u8 opProperty; + int iCompare = 0; /* Result of last OP_Compare operation */ + int *aPermute = 0; /* Permuation of columns for OP_Compare */ #ifdef VDBE_PROFILE - unsigned long long start; /* CPU clock count at start of opcode */ + u64 start; /* CPU clock count at start of opcode */ int origPc; /* Program counter at start of opcode */ #endif #ifndef SQLITE_OMIT_PROGRESS_CALLBACK @@ -42547,9 +45403,9 @@ SQLITE_PRIVATE int sqlite3VdbeExec( CHECK_FOR_INTERRUPT; sqlite3VdbeIOTraceSql(p); #ifdef SQLITE_DEBUG - sqlite3FaultBeginBenign(-1); - if( p->pc==0 && ((p->db->flags & SQLITE_VdbeListing)!=0 - || sqlite3OsAccess(db->pVfs, "vdbe_explain", SQLITE_ACCESS_EXISTS)==1 ) + sqlite3BeginBenignMalloc(); + if( p->pc==0 + && ((p->db->flags & SQLITE_VdbeListing) || fileExists(db, "vdbe_explain")) ){ int i; printf("VDBE Program Listing:\n"); @@ -42558,17 +45414,17 @@ SQLITE_PRIVATE int sqlite3VdbeExec( sqlite3VdbePrintOp(stdout, i, &p->aOp[i]); } } - if( sqlite3OsAccess(db->pVfs, "vdbe_trace", SQLITE_ACCESS_EXISTS)==1 ){ + if( fileExists(db, "vdbe_trace") ){ p->trace = stdout; } - sqlite3FaultEndBenign(-1); + sqlite3EndBenignMalloc(); #endif for(pc=p->pc; rc==SQLITE_OK; pc++){ assert( pc>=0 && pc<p->nOp ); if( db->mallocFailed ) goto no_mem; #ifdef VDBE_PROFILE origPc = pc; - start = hwtime(); + start = sqlite3Hwtime(); #endif pOp = &p->aOp[pc]; @@ -42583,11 +45439,11 @@ SQLITE_PRIVATE int sqlite3VdbeExec( sqlite3VdbePrintOp(p->trace, pc, pOp); } if( p->trace==0 && pc==0 ){ - sqlite3FaultBeginBenign(-1); - if( sqlite3OsAccess(db->pVfs, "vdbe_sqltrace", SQLITE_ACCESS_EXISTS)==1 ){ + sqlite3BeginBenignMalloc(); + if( fileExists(db, "vdbe_sqltrace") ){ sqlite3VdbePrintSql(p); } - sqlite3FaultEndBenign(-1); + sqlite3EndBenignMalloc(); } #endif @@ -42735,36 +45591,52 @@ case OP_Goto: { /* jump */ break; } -/* Opcode: Gosub * P2 * * * +/* Opcode: Gosub P1 P2 * * * ** -** Push the current address plus 1 onto the return address stack +** Write the current address onto register P1 ** and then jump to address P2. -** -** The return address stack is of limited depth. If too many -** OP_Gosub operations occur without intervening OP_Returns, then -** the return address stack will fill up and processing will abort -** with a fatal error. */ case OP_Gosub: { /* jump */ - assert( p->returnDepth<sizeof(p->returnStack)/sizeof(p->returnStack[0]) ); - p->returnStack[p->returnDepth++] = pc+1; + assert( pOp->p1>0 ); + assert( pOp->p1<=p->nMem ); + pIn1 = &p->aMem[pOp->p1]; + assert( (pIn1->flags & MEM_Dyn)==0 ); + pIn1->flags = MEM_Int; + pIn1->u.i = pc; + REGISTER_TRACE(pOp->p1, pIn1); pc = pOp->p2 - 1; break; } -/* Opcode: Return * * * * * +/* Opcode: Return P1 * * * * +** +** Jump to the next instruction after the address in register P1. +*/ +case OP_Return: { /* in1 */ + assert( pIn1->flags & MEM_Int ); + pc = pIn1->u.i; + break; +} + +/* Opcode: Yield P1 * * * * ** -** Jump immediately to the next instruction after the last unreturned -** OP_Gosub. If an OP_Return has occurred for all OP_Gosubs, then -** processing aborts with a fatal error. +** Swap the program counter with the value in register P1. */ -case OP_Return: { - assert( p->returnDepth>0 ); - p->returnDepth--; - pc = p->returnStack[p->returnDepth] - 1; +case OP_Yield: { + int pcDest; + assert( pOp->p1>0 ); + assert( pOp->p1<=p->nMem ); + pIn1 = &p->aMem[pOp->p1]; + assert( (pIn1->flags & MEM_Dyn)==0 ); + pIn1->flags = MEM_Int; + pcDest = pIn1->u.i; + pIn1->u.i = pc; + REGISTER_TRACE(pOp->p1, pIn1); + pc = pcDest; break; } + /* Opcode: Halt P1 P2 * P4 * ** ** Exit immediately. All open cursors, Fifos, etc are closed @@ -42789,7 +45661,7 @@ case OP_Halt: { p->pc = pc; p->errorAction = pOp->p2; if( pOp->p4.z ){ - sqlite3SetString(&p->zErrMsg, pOp->p4.z, (char*)0); + sqlite3SetString(&p->zErrMsg, db, "%s", pOp->p4.z); } rc = sqlite3VdbeHalt(p); assert( rc==SQLITE_BUSY || rc==SQLITE_OK ); @@ -42849,12 +45721,12 @@ case OP_String8: { /* same as TK_STRING, out2-prerelease */ if( encoding!=SQLITE_UTF8 ){ sqlite3VdbeMemSetStr(pOut, pOp->p4.z, -1, SQLITE_UTF8, SQLITE_STATIC); if( SQLITE_OK!=sqlite3VdbeChangeEncoding(pOut, encoding) ) goto no_mem; - if( SQLITE_OK!=sqlite3VdbeMemDynamicify(pOut) ) goto no_mem; + if( SQLITE_OK!=sqlite3VdbeMemMakeWriteable(pOut) ) goto no_mem; pOut->zMalloc = 0; pOut->flags |= MEM_Static; pOut->flags &= ~MEM_Dyn; if( pOp->p4type==P4_DYNAMIC ){ - sqlite3_free(pOp->p4.z); + sqlite3DbFree(db, pOp->p4.z); } pOp->p4type = P4_DYNAMIC; pOp->p4.z = pOut->z; @@ -42918,7 +45790,7 @@ case OP_Blob: { /* out2-prerelease */ ** ** The value of variable P1 is written into register P2. A variable is ** an unknown in the original SQL string as handed to sqlite3_compile(). -** Any occurance of the '?' character in the original SQL is considered +** Any occurrence of the '?' character in the original SQL is considered ** a variable. Variables in the SQL string are number from left to ** right beginning with 1. The values of variables are set using the ** sqlite3_bind() API. @@ -42937,27 +45809,35 @@ case OP_Variable: { /* out2-prerelease */ break; } -/* Opcode: Move P1 P2 * * * +/* Opcode: Move P1 P2 P3 * * ** -** Move the value in register P1 over into register P2. Register P1 -** is left holding a NULL. It is an error for P1 and P2 to be the -** same register. +** Move the values in register P1..P1+P3-1 over into +** registers P2..P2+P3-1. Registers P1..P1+P1-1 are +** left holding a NULL. It is an error for register ranges +** P1..P1+P3-1 and P2..P2+P3-1 to overlap. */ case OP_Move: { char *zMalloc; - assert( pOp->p1>0 ); - assert( pOp->p1<=p->nMem ); - pIn1 = &p->aMem[pOp->p1]; - REGISTER_TRACE(pOp->p1, pIn1); - assert( pOp->p2>0 ); - assert( pOp->p2<=p->nMem ); - pOut = &p->aMem[pOp->p2]; - assert( pOut!=pIn1 ); - zMalloc = pOut->zMalloc; - pOut->zMalloc = 0; - sqlite3VdbeMemMove(pOut, pIn1); - pIn1->zMalloc = zMalloc; - REGISTER_TRACE(pOp->p2, pOut); + int n = pOp->p3; + int p1 = pOp->p1; + int p2 = pOp->p2; + assert( n>0 ); + assert( p1>0 ); + assert( p1+n<p->nMem ); + pIn1 = &p->aMem[p1]; + assert( p2>0 ); + assert( p2+n<p->nMem ); + pOut = &p->aMem[p2]; + assert( p1+n<=p2 || p2+n<=p1 ); + while( n-- ){ + zMalloc = pOut->zMalloc; + pOut->zMalloc = 0; + sqlite3VdbeMemMove(pOut, pIn1); + pIn1->zMalloc = zMalloc; + REGISTER_TRACE(p2++, pOut); + pIn1++; + pOut++; + } break; } @@ -42972,7 +45852,6 @@ case OP_Copy: { assert( pOp->p1>0 ); assert( pOp->p1<=p->nMem ); pIn1 = &p->aMem[pOp->p1]; - REGISTER_TRACE(pOp->p1, pIn1); assert( pOp->p2>0 ); assert( pOp->p2<=p->nMem ); pOut = &p->aMem[pOp->p2]; @@ -43011,7 +45890,7 @@ case OP_SCopy: { /* Opcode: ResultRow P1 P2 * * * ** -** The registers P1 throught P1+P2-1 contain a single row of +** The registers P1 through P1+P2-1 contain a single row of ** results. This opcode causes the sqlite3_step() call to terminate ** with an SQLITE_ROW return code and it sets up the sqlite3_stmt ** structure to provide access to the top P1 values as the result @@ -43028,13 +45907,14 @@ case OP_ResultRow: { p->cacheCtr = (p->cacheCtr + 2)|1; /* Make sure the results of the current row are \000 terminated - ** and have an assigned type. The results are deephemeralized as + ** and have an assigned type. The results are de-ephemeralized as ** as side effect. */ pMem = p->pResultSet = &p->aMem[pOp->p1]; for(i=0; i<pOp->p2; i++){ sqlite3VdbeMemNulTerminate(&pMem[i]); storeTypeInfo(&pMem[i], encoding); + REGISTER_TRACE(pOp->p1+i, &pMem[i]); } if( db->mallocFailed ) goto no_mem; @@ -43094,13 +45974,13 @@ case OP_Concat: { /* same as TK_CONCAT, in1, in2, out3 */ /* Opcode: Add P1 P2 P3 * * ** ** Add the value in register P1 to the value in register P2 -** and store the result in regiser P3. +** and store the result in register P3. ** If either input is NULL, the result is NULL. */ /* Opcode: Multiply P1 P2 P3 * * ** ** -** Multiply the value in regiser P1 by the value in regiser P2 +** Multiply the value in register P1 by the value in register P2 ** and store the result in register P3. ** If either input is NULL, the result is NULL. */ @@ -43130,6 +46010,8 @@ case OP_Multiply: /* same as TK_STAR, in1, in2, out3 */ case OP_Divide: /* same as TK_SLASH, in1, in2, out3 */ case OP_Remainder: { /* same as TK_REM, in1, in2, out3 */ int flags; + applyNumericAffinity(pIn1); + applyNumericAffinity(pIn2); flags = pIn1->flags | pIn2->flags; if( (flags & MEM_Null)!=0 ) goto arithmetic_result_is_null; if( (pIn1->flags & pIn2->flags & MEM_Int)==MEM_Int ){ @@ -43146,8 +46028,8 @@ case OP_Remainder: { /* same as TK_REM, in1, in2, out3 */ ** -1 returns an integer too large to store in a 64-bit data-type. On ** some architectures, the value overflows to (1<<63). On others, ** a SIGFPE is issued. The following statement normalizes this - ** behaviour so that all architectures behave as if integer - ** overflow occured. + ** behavior so that all architectures behave as if integer + ** overflow occurred. */ if( a==-1 && b==SMALLEST_INT64 ) a = 1; b /= a; @@ -43301,7 +46183,7 @@ case OP_Function: { goto no_mem; } - /* If any auxilary data functions have been called by this user function, + /* If any auxiliary data functions have been called by this user function, ** immediately call the destructor for any non-static values. */ if( ctx.pVdbeFunc ){ @@ -43312,7 +46194,7 @@ case OP_Function: { /* If the function returned an error, throw an exception */ if( ctx.isError ){ - sqlite3SetString(&p->zErrMsg, sqlite3_value_text(&ctx.s), (char*)0); + sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3_value_text(&ctx.s)); rc = ctx.isError; } @@ -43379,7 +46261,7 @@ case OP_ShiftRight: { /* same as TK_RSHIFT, in1, in2, out3 */ /* Opcode: AddImm P1 P2 * * * ** -** Add the constant P2 the value in register P1. +** Add the constant P2 to the value in register P1. ** The result is always an integer. ** ** To force any register to be an integer, just add 0. @@ -43561,10 +46443,6 @@ case OP_ToReal: { /* same as TK_TO_REAL, in1 */ ** reg(P3) is NULL then take the jump. If the SQLITE_JUMPIFNULL ** bit is clear then fall thru if either operand is NULL. ** -** If the SQLITE_NULLEQUAL bit of P5 is set then treat NULL operands -** as being equal to one another. Normally NULLs are not equal to -** anything including other NULLs. -** ** The SQLITE_AFF_MASK portion of P5 must be an affinity character - ** SQLITE_AFF_TEXT, SQLITE_AFF_INTEGER, and so forth. An attempt is made ** to coerce both inputs according to this affinity before the @@ -43625,41 +46503,21 @@ case OP_Ge: { /* same as TK_GE, jump, in1, in3 */ int flags; int res; char affinity; - Mem x1, x3; flags = pIn1->flags|pIn3->flags; if( flags&MEM_Null ){ - if( (pOp->p5 & SQLITE_NULLEQUAL)!=0 ){ - /* - ** When SQLITE_NULLEQUAL set and either operand is NULL - ** then both operands are converted to integers prior to being - ** passed down into the normal comparison logic below. - ** NULL operands are converted to zero and non-NULL operands - ** are converted to 1. Thus, for example, with SQLITE_NULLEQUAL - ** set, NULL==NULL is true whereas it would normally NULL. - ** Similarly, NULL!=123 is true. - */ - x1.flags = MEM_Int; - x1.u.i = (pIn1->flags & MEM_Null)==0; - pIn1 = &x1; - x3.flags = MEM_Int; - x3.u.i = (pIn3->flags & MEM_Null)==0; - pIn3 = &x3; - }else{ - /* If the SQLITE_NULLEQUAL bit is clear and either operand is NULL then - ** the result is always NULL. The jump is taken if the - ** SQLITE_JUMPIFNULL bit is set. - */ - if( pOp->p5 & SQLITE_STOREP2 ){ - pOut = &p->aMem[pOp->p2]; - MemSetTypeFlag(pOut, MEM_Null); - REGISTER_TRACE(pOp->p2, pOut); - }else if( pOp->p5 & SQLITE_JUMPIFNULL ){ - pc = pOp->p2-1; - } - break; + /* If either operand is NULL then the result is always NULL. + ** The jump is taken if the SQLITE_JUMPIFNULL bit is set. + */ + if( pOp->p5 & SQLITE_STOREP2 ){ + pOut = &p->aMem[pOp->p2]; + MemSetTypeFlag(pOut, MEM_Null); + REGISTER_TRACE(pOp->p2, pOut); + }else if( pOp->p5 & SQLITE_JUMPIFNULL ){ + pc = pOp->p2-1; } + break; } affinity = pOp->p5 & SQLITE_AFF_MASK; @@ -43692,6 +46550,82 @@ case OP_Ge: { /* same as TK_GE, jump, in1, in3 */ break; } +/* Opcode: Permutation * * * P4 * +** +** Set the permuation used by the OP_Compare operator to be the array +** of integers in P4. +** +** The permutation is only valid until the next OP_Permutation, OP_Compare, +** OP_Halt, or OP_ResultRow. Typically the OP_Permutation should occur +** immediately prior to the OP_Compare. +*/ +case OP_Permutation: { + assert( pOp->p4type==P4_INTARRAY ); + assert( pOp->p4.ai ); + aPermute = pOp->p4.ai; + break; +} + +/* Opcode: Compare P1 P2 P3 P4 * +** +** Compare to vectors of registers in reg(P1)..reg(P1+P3-1) (all this +** one "A") and in reg(P2)..reg(P2+P3-1) ("B"). Save the result of +** the comparison for use by the next OP_Jump instruct. +** +** P4 is a KeyInfo structure that defines collating sequences and sort +** orders for the comparison. The permutation applies to registers +** only. The KeyInfo elements are used sequentially. +** +** The comparison is a sort comparison, so NULLs compare equal, +** NULLs are less than numbers, numbers are less than strings, +** and strings are less than blobs. +*/ +case OP_Compare: { + int n = pOp->p3; + int i, p1, p2; + const KeyInfo *pKeyInfo = pOp->p4.pKeyInfo; + assert( n>0 ); + assert( pKeyInfo!=0 ); + p1 = pOp->p1; + assert( p1>0 && p1+n-1<p->nMem ); + p2 = pOp->p2; + assert( p2>0 && p2+n-1<p->nMem ); + for(i=0; i<n; i++){ + int idx = aPermute ? aPermute[i] : i; + CollSeq *pColl; /* Collating sequence to use on this term */ + int bRev; /* True for DESCENDING sort order */ + REGISTER_TRACE(p1+idx, &p->aMem[p1+idx]); + REGISTER_TRACE(p2+idx, &p->aMem[p2+idx]); + assert( i<pKeyInfo->nField ); + pColl = pKeyInfo->aColl[i]; + bRev = pKeyInfo->aSortOrder[i]; + iCompare = sqlite3MemCompare(&p->aMem[p1+idx], &p->aMem[p2+idx], pColl); + if( iCompare ){ + if( bRev ) iCompare = -iCompare; + break; + } + } + aPermute = 0; + break; +} + +/* Opcode: Jump P1 P2 P3 * * +** +** Jump to the instruction at address P1, P2, or P3 depending on whether +** in the most recent OP_Compare instruction the P1 vector was less than +** equal to, or greater than the P2 vector, respectively. +*/ +case OP_Jump: { /* jump */ + if( iCompare<0 ){ + pc = pOp->p1 - 1; + }else if( iCompare==0 ){ + pc = pOp->p2 - 1; + }else{ + pc = pOp->p3 - 1; + } + break; +} + /* Opcode: And P1 P2 P3 * * ** ** Take the logical AND of the values in registers P1 and P2 and @@ -44054,17 +46988,8 @@ case OP_Column: { if( aOffset[p2] ){ assert( rc==SQLITE_OK ); if( zRec ){ - if( pDest->flags&MEM_Dyn ){ - sqlite3VdbeSerialGet((u8 *)&zRec[aOffset[p2]], aType[p2], &sMem); - sMem.db = db; - rc = sqlite3VdbeMemCopy(pDest, &sMem); - assert( !(sMem.flags&MEM_Dyn) ); - if( rc!=SQLITE_OK ){ - goto op_column_out; - } - }else{ - sqlite3VdbeSerialGet((u8 *)&zRec[aOffset[p2]], aType[p2], pDest); - } + sqlite3VdbeMemReleaseExternal(pDest); + sqlite3VdbeSerialGet((u8 *)&zRec[aOffset[p2]], aType[p2], pDest); }else{ len = sqlite3VdbeSerialTypeLen(aType[p2]); sqlite3VdbeMemMove(&sMem, pDest); @@ -44132,7 +47057,7 @@ case OP_Affinity: { ** ** Convert P2 registers beginning with P1 into a single entry ** suitable for use as a data record in a database table or as a key -** in an index. The details of the format are irrelavant as long as +** in an index. The details of the format are irrelevant as long as ** the OP_Column opcode can decode the record later. ** Refer to source code comments for the details of the record ** format. @@ -44317,8 +47242,9 @@ case OP_AutoCommit: { ** still running, and a transaction is active, return an error indicating ** that the other VMs must complete first. */ - sqlite3SetString(&p->zErrMsg, "cannot ", rollback?"rollback":"commit", - " transaction - SQL statements in progress", (char*)0); + sqlite3SetString(&p->zErrMsg, db, "cannot %s transaction - " + "SQL statements in progress", + rollback ? "rollback" : "commit"); rc = SQLITE_ERROR; }else if( i!=db->autoCommit ){ if( pOp->p2 ){ @@ -44341,10 +47267,10 @@ case OP_AutoCommit: { } goto vdbe_return; }else{ - sqlite3SetString(&p->zErrMsg, + sqlite3SetString(&p->zErrMsg, db, (!i)?"cannot start a transaction within a transaction":( (rollback)?"cannot rollback - no transaction is active": - "cannot commit - no transaction is active"), (char*)0); + "cannot commit - no transaction is active")); rc = SQLITE_ERROR; } @@ -44503,13 +47429,13 @@ case OP_VerifyCookie: { iMeta = 0; } if( rc==SQLITE_OK && iMeta!=pOp->p2 ){ - sqlite3_free(p->zErrMsg); + sqlite3DbFree(db, p->zErrMsg); p->zErrMsg = sqlite3DbStrDup(db, "database schema has changed"); /* If the schema-cookie from the database file matches the cookie ** stored with the in-memory representation of the schema, do ** not reload the schema from the database file. ** - ** If virtual-tables are in use, this is not just an optimisation. + ** If virtual-tables are in use, this is not just an optimization. ** Often, v-tables store their data in other SQLite tables, which ** are queried from within xNext() and other v-table methods using ** prepared queries. If such a query is out-of-date, we do not want to @@ -44625,7 +47551,7 @@ case OP_OpenWrite: { case SQLITE_OK: { int flags = sqlite3BtreeFlags(pCur->pCursor); /* Sanity checking. Only the lower four bits of the flags byte should - ** be used. Bit 3 (mask 0x08) is unpreditable. The lower 3 bits + ** be used. Bit 3 (mask 0x08) is unpredictable. The lower 3 bits ** (mask 0x07) should be either 5 (intkey+leafdata for tables) or ** 2 (zerodata for indices). If these conditions are not met it can ** only mean that we are dealing with a corrupt database file @@ -44911,6 +47837,12 @@ case OP_MoveGt: { /* jump, in3 */ if( res ){ pc = pOp->p2 - 1; } + }else if( !pC->pseudoTable ){ + /* This happens when attempting to open the sqlite3_master table + ** for read access returns SQLITE_EMPTY. In this case always + ** take the jump (since there are no records in the table). + */ + pc = pOp->p2 - 1; } break; } @@ -44930,7 +47862,7 @@ case OP_MoveGt: { /* jump, in3 */ ** DISTINCT keyword in SELECT statements. ** ** This instruction checks if index P1 contains a record for which -** the first N serialised values exactly match the N serialised values +** the first N serialized values exactly match the N serialized values ** in the record in register P3, where N is the total number of values in ** the P3 record (the P3 record is a prefix of the P1 record). ** @@ -45028,7 +47960,14 @@ case OP_IsUnique: { /* jump, in3 */ zKey = pK->z; nKey = pK->n; - szRowid = sqlite3VdbeIdxRowidLen((u8*)zKey); + /* sqlite3VdbeIdxRowidLen() only returns other than SQLITE_OK when the + ** record passed as an argument corrupt. Since the record in this case + ** has just been created by an OP_MakeRecord instruction, and not loaded + ** from the database file, it is not possible for it to be corrupt. + ** Therefore, assert(rc==SQLITE_OK). + */ + rc = sqlite3VdbeIdxRowidLen((u8*)zKey, nKey, &szRowid); + assert(rc==SQLITE_OK); len = nKey-szRowid; /* Search for an entry in P1 where all but the last four bytes match K. @@ -45118,6 +48057,13 @@ case OP_NotExists: { /* jump, in3 */ pc = pOp->p2 - 1; assert( pC->rowidIsValid==0 ); } + }else if( !pC->pseudoTable ){ + /* This happens when an attempt to open a read cursor on the + ** sqlite_master table returns SQLITE_EMPTY. + */ + assert( pC->isTable ); + pc = pOp->p2 - 1; + assert( pC->rowidIsValid==0 ); } break; } @@ -45189,7 +48135,7 @@ case OP_NewRowid: { /* out2-prerelease */ ** random number generator based on the RC4 algorithm. ** ** To promote locality of reference for repetitive inserts, the - ** first few attempts at chosing a random rowid pick values just a little + ** first few attempts at choosing a random rowid pick values just a little ** larger than the previous rowid. This has been shown experimentally ** to double the speed of the COPY operation. */ @@ -45348,7 +48294,7 @@ case OP_Insert: { } if( pC->pseudoTable ){ if( !pC->ephemPseudoTable ){ - sqlite3_free(pC->pData); + sqlite3DbFree(db, pC->pData); } pC->iKey = iKey; pC->nData = pData->n; @@ -45360,7 +48306,7 @@ case OP_Insert: { pData->zMalloc = 0; } }else{ - pC->pData = sqlite3_malloc( pC->nData+2 ); + pC->pData = sqlite3Malloc( pC->nData+2 ); if( !pC->pData ) goto no_mem; memcpy(pC->pData, pData->z, pC->nData); pC->pData[pC->nData] = 0; @@ -45539,7 +48485,7 @@ case OP_RowData: { /* Opcode: Rowid P1 P2 * * * ** ** Store in register P2 an integer which is the key of the table entry that -** P1 is currently point to. If p2==0 then push the integer. +** P1 is currently point to. */ case OP_Rowid: { /* out2-prerelease */ int i = pOp->p1; @@ -45692,6 +48638,7 @@ case OP_Prev: /* jump */ case OP_Next: { /* jump */ Cursor *pC; BtCursor *pCrsr; + int res; CHECK_FOR_INTERRUPT; assert( pOp->p1>=0 && pOp->p1<p->nCursor ); @@ -45701,19 +48648,17 @@ case OP_Next: { /* jump */ } pCrsr = pC->pCursor; assert( pCrsr ); - if( pC->nullRow==0 ){ - int res = 1; - assert( pC->deferredMoveto==0 ); - rc = pOp->opcode==OP_Next ? sqlite3BtreeNext(pCrsr, &res) : - sqlite3BtreePrevious(pCrsr, &res); - pC->nullRow = res; - pC->cacheStatus = CACHE_STALE; - if( res==0 ){ - pc = pOp->p2 - 1; + res = 1; + assert( pC->deferredMoveto==0 ); + rc = pOp->opcode==OP_Next ? sqlite3BtreeNext(pCrsr, &res) : + sqlite3BtreePrevious(pCrsr, &res); + pC->nullRow = res; + pC->cacheStatus = CACHE_STALE; + if( res==0 ){ + pc = pOp->p2 - 1; #ifdef SQLITE_TEST - sqlite3_search_count++; + sqlite3_search_count++; #endif - } } pC->rowidIsValid = 0; break; @@ -46002,7 +48947,7 @@ case OP_CreateTable: { /* out2-prerelease */ ** schema is already loaded into the symbol table. ** ** This opcode invokes the parser to create a new virtual machine, -** then runs the new virtual machine. It is thus a reentrant opcode. +** then runs the new virtual machine. It is thus a re-entrant opcode. */ case OP_ParseSchema: { char *zSql; @@ -46028,7 +48973,7 @@ case OP_ParseSchema: { assert( !db->mallocFailed ); rc = sqlite3_exec(db, zSql, sqlite3InitCallback, &initData, 0); if( rc==SQLITE_ABORT ) rc = initData.rc; - sqlite3_free(zSql); + sqlite3DbFree(db, zSql); db->init.busy = 0; (void)sqlite3SafetyOn(db); if( rc==SQLITE_NOMEM ){ @@ -46120,7 +49065,7 @@ case OP_IntegrityCk: { nRoot = pOp->p2; assert( nRoot>0 ); - aRoot = sqlite3_malloc( sizeof(int)*(nRoot+1) ); + aRoot = sqlite3DbMallocRaw(db, sizeof(int)*(nRoot+1) ); if( aRoot==0 ) goto no_mem; assert( pOp->p3>0 && pOp->p3<=p->nMem ); pnErr = &p->aMem[pOp->p3]; @@ -46135,16 +49080,18 @@ case OP_IntegrityCk: { assert( (p->btreeMask & (1<<pOp->p5))!=0 ); z = sqlite3BtreeIntegrityCheck(db->aDb[pOp->p5].pBt, aRoot, nRoot, pnErr->u.i, &nErr); + sqlite3DbFree(db, aRoot); pnErr->u.i -= nErr; sqlite3VdbeMemSetNull(pIn1); if( nErr==0 ){ assert( z==0 ); + }else if( z==0 ){ + goto no_mem; }else{ sqlite3VdbeMemSetStr(pIn1, z, -1, SQLITE_UTF8, sqlite3_free); } UPDATE_MAX_BLOBSIZE(pIn1); sqlite3VdbeChangeEncoding(pIn1, encoding); - sqlite3_free(aRoot); break; } #endif /* SQLITE_OMIT_INTEGRITY_CHECK */ @@ -46154,6 +49101,7 @@ case OP_IntegrityCk: { ** Write the integer from register P1 into the Fifo. */ case OP_FifoWrite: { /* in1 */ + p->sFifo.db = db; if( sqlite3VdbeFifoPush(&p->sFifo, sqlite3VdbeIntValue(pIn1))==SQLITE_NOMEM ){ goto no_mem; } @@ -46201,7 +49149,7 @@ case OP_ContextPush: { pContext->lastRowid = db->lastRowid; pContext->nChange = p->nChange; pContext->sFifo = p->sFifo; - sqlite3VdbeFifoInit(&p->sFifo); + sqlite3VdbeFifoInit(&p->sFifo, db); break; } @@ -46330,7 +49278,7 @@ case OP_AggStep: { } (ctx.pFunc->xStep)(&ctx, n, apVal); if( ctx.isError ){ - sqlite3SetString(&p->zErrMsg, sqlite3_value_text(&ctx.s), (char*)0); + sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3_value_text(&ctx.s)); rc = ctx.isError; } sqlite3VdbeMemRelease(&ctx.s); @@ -46356,7 +49304,7 @@ case OP_AggFinal: { assert( (pMem->flags & ~(MEM_Null|MEM_Agg))==0 ); rc = sqlite3VdbeMemFinalize(pMem, pOp->p4.pFunc); if( rc==SQLITE_ERROR ){ - sqlite3SetString(&p->zErrMsg, sqlite3_value_text(pMem), (char*)0); + sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3_value_text(pMem)); } sqlite3VdbeChangeEncoding(pMem, encoding); UPDATE_MAX_BLOBSIZE(pMem); @@ -46446,7 +49394,7 @@ case OP_TableLock: { rc = sqlite3BtreeLockTable(db->aDb[p1].pBt, pOp->p2, isWriteLock); if( rc==SQLITE_LOCKED ){ const char *z = pOp->p4.z; - sqlite3SetString(&p->zErrMsg, "database table is locked: ", z, (char*)0); + sqlite3SetString(&p->zErrMsg, db, "database table is locked: %s", z); } break; } @@ -46455,11 +49403,21 @@ case OP_TableLock: { #ifndef SQLITE_OMIT_VIRTUALTABLE /* Opcode: VBegin * * * P4 * ** -** P4 a pointer to an sqlite3_vtab structure. Call the xBegin method -** for that table. +** P4 may be a pointer to an sqlite3_vtab structure. If so, call the +** xBegin method for that table. +** +** Also, whether or not P4 is set, check that this is not being called from +** within a callback to a virtual table xSync() method. If it is, set the +** error code to SQLITE_LOCKED. */ case OP_VBegin: { - rc = sqlite3VtabBegin(db, pOp->p4.pVtab); + sqlite3_vtab *pVtab = pOp->p4.pVtab; + rc = sqlite3VtabBegin(db, pVtab); + if( pVtab ){ + sqlite3DbFree(db, p->zErrMsg); + p->zErrMsg = pVtab->zErrMsg; + pVtab->zErrMsg = 0; + } break; } #endif /* SQLITE_OMIT_VIRTUALTABLE */ @@ -46507,9 +49465,12 @@ case OP_VOpen: { assert(pVtab && pModule); if( sqlite3SafetyOff(db) ) goto abort_due_to_misuse; rc = pModule->xOpen(pVtab, &pVtabCursor); + sqlite3DbFree(db, p->zErrMsg); + p->zErrMsg = pVtab->zErrMsg; + pVtab->zErrMsg = 0; if( sqlite3SafetyOn(db) ) goto abort_due_to_misuse; if( SQLITE_OK==rc ){ - /* Initialise sqlite3_vtab_cursor base class */ + /* Initialize sqlite3_vtab_cursor base class */ pVtabCursor->pVtab = pVtab; /* Initialise vdbe cursor object */ @@ -46539,8 +49500,8 @@ case OP_VOpen: { ** This opcode invokes the xFilter method on the virtual table specified ** by P1. The integer query plan parameter to xFilter is stored in register ** P3. Register P3+1 stores the argc parameter to be passed to the -** xFilter method. Registers P3+2..P3+1+argc are the argc additional -** parametersneath additional parameters which are passed to +** xFilter method. Registers P3+2..P3+1+argc are the argc +** additional parameters which are passed to ** xFilter as argv. Register P3+2 becomes argv[0] when passed to xFilter. ** ** A jump is made to P2 if the result set after filtering would be empty. @@ -46551,12 +49512,16 @@ case OP_VFilter: { /* jump */ const sqlite3_module *pModule; Mem *pQuery = &p->aMem[pOp->p3]; Mem *pArgc = &pQuery[1]; + sqlite3_vtab_cursor *pVtabCursor; + sqlite3_vtab *pVtab; Cursor *pCur = p->apCsr[pOp->p1]; REGISTER_TRACE(pOp->p3, pQuery); assert( pCur->pVtabCursor ); - pModule = pCur->pVtabCursor->pVtab->pModule; + pVtabCursor = pCur->pVtabCursor; + pVtab = pVtabCursor->pVtab; + pModule = pVtab->pModule; /* Grab the index number and argc parameters */ assert( (pQuery->flags&MEM_Int)!=0 && pArgc->flags==MEM_Int ); @@ -46574,11 +49539,16 @@ case OP_VFilter: { /* jump */ } if( sqlite3SafetyOff(db) ) goto abort_due_to_misuse; + sqlite3VtabLock(pVtab); p->inVtabMethod = 1; - rc = pModule->xFilter(pCur->pVtabCursor, iQuery, pOp->p4.z, nArg, apArg); + rc = pModule->xFilter(pVtabCursor, iQuery, pOp->p4.z, nArg, apArg); p->inVtabMethod = 0; + sqlite3DbFree(db, p->zErrMsg); + p->zErrMsg = pVtab->zErrMsg; + pVtab->zErrMsg = 0; + sqlite3VtabUnlock(db, pVtab); if( rc==SQLITE_OK ){ - res = pModule->xEof(pCur->pVtabCursor); + res = pModule->xEof(pVtabCursor); } if( sqlite3SafetyOn(db) ) goto abort_due_to_misuse; @@ -46599,6 +49569,7 @@ case OP_VFilter: { /* jump */ ** the virtual-table that the P1 cursor is pointing to. */ case OP_VRowid: { /* out2-prerelease */ + sqlite3_vtab *pVtab; const sqlite3_module *pModule; sqlite_int64 iRow; Cursor *pCur = p->apCsr[pOp->p1]; @@ -46607,10 +49578,14 @@ case OP_VRowid: { /* out2-prerelease */ if( pCur->nullRow ){ break; } - pModule = pCur->pVtabCursor->pVtab->pModule; + pVtab = pCur->pVtabCursor->pVtab; + pModule = pVtab->pModule; assert( pModule->xRowid ); if( sqlite3SafetyOff(db) ) goto abort_due_to_misuse; rc = pModule->xRowid(pCur->pVtabCursor, &iRow); + sqlite3DbFree(db, p->zErrMsg); + p->zErrMsg = pVtab->zErrMsg; + pVtab->zErrMsg = 0; if( sqlite3SafetyOn(db) ) goto abort_due_to_misuse; MemSetTypeFlag(pOut, MEM_Int); pOut->u.i = iRow; @@ -46626,6 +49601,7 @@ case OP_VRowid: { /* out2-prerelease */ ** P1 cursor is pointing to into register P3. */ case OP_VColumn: { + sqlite3_vtab *pVtab; const sqlite3_module *pModule; Mem *pDest; sqlite3_context sContext; @@ -46638,7 +49614,8 @@ case OP_VColumn: { sqlite3VdbeMemSetNull(pDest); break; } - pModule = pCur->pVtabCursor->pVtab->pModule; + pVtab = pCur->pVtabCursor->pVtab; + pModule = pVtab->pModule; assert( pModule->xColumn ); memset(&sContext, 0, sizeof(sContext)); @@ -46652,6 +49629,9 @@ case OP_VColumn: { if( sqlite3SafetyOff(db) ) goto abort_due_to_misuse; rc = pModule->xColumn(pCur->pVtabCursor, &sContext, pOp->p2); + sqlite3DbFree(db, p->zErrMsg); + p->zErrMsg = pVtab->zErrMsg; + pVtab->zErrMsg = 0; /* Copy the result of the function to the P3 register. We ** do this regardless of whether or not an error occured to ensure any @@ -46680,6 +49660,7 @@ case OP_VColumn: { ** the end of its result set, then fall through to the next instruction. */ case OP_VNext: { /* jump */ + sqlite3_vtab *pVtab; const sqlite3_module *pModule; int res = 0; @@ -46688,7 +49669,8 @@ case OP_VNext: { /* jump */ if( pCur->nullRow ){ break; } - pModule = pCur->pVtabCursor->pVtab->pModule; + pVtab = pCur->pVtabCursor->pVtab; + pModule = pVtab->pModule; assert( pModule->xNext ); /* Invoke the xNext() method of the module. There is no way for the @@ -46698,9 +49680,14 @@ case OP_VNext: { /* jump */ ** some other method is next invoked on the save virtual table cursor. */ if( sqlite3SafetyOff(db) ) goto abort_due_to_misuse; + sqlite3VtabLock(pVtab); p->inVtabMethod = 1; rc = pModule->xNext(pCur->pVtabCursor); p->inVtabMethod = 0; + sqlite3DbFree(db, p->zErrMsg); + p->zErrMsg = pVtab->zErrMsg; + pVtab->zErrMsg = 0; + sqlite3VtabUnlock(db, pVtab); if( rc==SQLITE_OK ){ res = pModule->xEof(pCur->pVtabCursor); } @@ -46732,6 +49719,9 @@ case OP_VRename: { if( sqlite3SafetyOff(db) ) goto abort_due_to_misuse; sqlite3VtabLock(pVtab); rc = pVtab->pModule->xRename(pVtab, pName->z); + sqlite3DbFree(db, p->zErrMsg); + p->zErrMsg = pVtab->zErrMsg; + pVtab->zErrMsg = 0; sqlite3VtabUnlock(db, pVtab); if( sqlite3SafetyOn(db) ) goto abort_due_to_misuse; @@ -46769,7 +49759,7 @@ case OP_VUpdate: { int nArg = pOp->p2; assert( pOp->p4type==P4_VTAB ); if( pModule->xUpdate==0 ){ - sqlite3SetString(&p->zErrMsg, "read-only table", 0); + sqlite3SetString(&p->zErrMsg, db, "read-only table"); rc = SQLITE_ERROR; }else{ int i; @@ -46784,6 +49774,9 @@ case OP_VUpdate: { if( sqlite3SafetyOff(db) ) goto abort_due_to_misuse; sqlite3VtabLock(pVtab); rc = pModule->xUpdate(pVtab, nArg, apArg, &rowid); + sqlite3DbFree(db, p->zErrMsg); + p->zErrMsg = pVtab->zErrMsg; + pVtab->zErrMsg = 0; sqlite3VtabUnlock(db, pVtab); if( sqlite3SafetyOn(db) ) goto abort_due_to_misuse; if( pOp->p1 && rc==SQLITE_OK ){ @@ -46796,6 +49789,25 @@ case OP_VUpdate: { } #endif /* SQLITE_OMIT_VIRTUALTABLE */ +#ifndef SQLITE_OMIT_PAGER_PRAGMAS +/* Opcode: Pagecount P1 P2 * * * +** +** Write the current number of pages in database P1 to memory cell P2. +*/ +case OP_Pagecount: { /* out2-prerelease */ + int p1 = pOp->p1; + int nPage; + Pager *pPager = sqlite3BtreePager(db->aDb[p1].pBt); + + rc = sqlite3PagerPagecount(pPager, &nPage); + if( rc==SQLITE_OK ){ + pOut->flags = MEM_Int; + pOut->u.i = nPage; + } + break; +} +#endif + #ifndef SQLITE_OMIT_TRACE /* Opcode: Trace * * * P4 * ** @@ -46843,11 +49855,11 @@ default: { /* This is really OP_Noop and OP_Explain */ #ifdef VDBE_PROFILE { - long long elapse = hwtime() - start; - pOp->cycles += elapse; + u64 elapsed = sqlite3Hwtime() - start; + pOp->cycles += elapsed; pOp->cnt++; #if 0 - fprintf(stdout, "%10lld ", elapse); + fprintf(stdout, "%10llu ", elapsed); sqlite3VdbePrintOp(stdout, origPc, &p->aOp[origPc]); #endif } @@ -46881,8 +49893,9 @@ default: { /* This is really OP_Noop and OP_Explain */ vdbe_error_halt: assert( rc ); p->rc = rc; - rc = SQLITE_ERROR; sqlite3VdbeHalt(p); + if( rc==SQLITE_IOERR_NOMEM ) db->mallocFailed = 1; + rc = SQLITE_ERROR; /* This is the only way out of this procedure. We have to ** release the mutexes on btrees that were acquired at the @@ -46895,7 +49908,7 @@ vdbe_return: ** is encountered. */ too_big: - sqlite3SetString(&p->zErrMsg, "string or blob too big", (char*)0); + sqlite3SetString(&p->zErrMsg, db, "string or blob too big"); rc = SQLITE_TOOBIG; goto vdbe_error_halt; @@ -46903,7 +49916,7 @@ too_big: */ no_mem: db->mallocFailed = 1; - sqlite3SetString(&p->zErrMsg, "out of memory", (char*)0); + sqlite3SetString(&p->zErrMsg, db, "out of memory"); rc = SQLITE_NOMEM; goto vdbe_error_halt; @@ -46919,7 +49932,9 @@ abort_due_to_misuse: abort_due_to_error: assert( p->zErrMsg==0 ); if( db->mallocFailed ) rc = SQLITE_NOMEM; - sqlite3SetString(&p->zErrMsg, sqlite3ErrStr(rc), (char*)0); + if( rc!=SQLITE_IOERR_NOMEM ){ + sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3ErrStr(rc)); + } goto vdbe_error_halt; /* Jump to here if the sqlite3_interrupt() API sets the interrupt @@ -46929,7 +49944,7 @@ abort_due_to_interrupt: assert( db->u1.isInterrupted ); rc = SQLITE_INTERRUPT; p->rc = rc; - sqlite3SetString(&p->zErrMsg, sqlite3ErrStr(rc), (char*)0); + sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3ErrStr(rc)); goto vdbe_error_halt; } @@ -47031,10 +50046,9 @@ SQLITE_API int sqlite3_blob_open( memset(&sParse, 0, sizeof(Parse)); sParse.db = db; - rc = sqlite3SafetyOn(db); - if( rc!=SQLITE_OK ){ + if( sqlite3SafetyOn(db) ){ sqlite3_mutex_leave(db->mutex); - return rc; + return SQLITE_MISUSE; } sqlite3BtreeEnterAll(db); @@ -47053,7 +50067,7 @@ SQLITE_API int sqlite3_blob_open( if( sParse.zErrMsg ){ sqlite3_snprintf(sizeof(zErr), zErr, "%s", sParse.zErrMsg); } - sqlite3_free(sParse.zErrMsg); + sqlite3DbFree(db, sParse.zErrMsg); rc = SQLITE_ERROR; (void)sqlite3SafetyOff(db); sqlite3BtreeLeaveAll(db); @@ -47126,6 +50140,7 @@ SQLITE_API int sqlite3_blob_open( ** and offset cache without causing any IO. */ sqlite3VdbeChangeP2(v, flags ? 4 : 2, pTab->nCol+1); + sqlite3VdbeChangeP2(v, 8, pTab->nCol); if( !db->mallocFailed ){ sqlite3VdbeMakeReady(v, 1, 1, 1, 0); } @@ -47164,7 +50179,7 @@ SQLITE_API int sqlite3_blob_open( } pBlob = (Incrblob *)sqlite3DbMallocZero(db, sizeof(Incrblob)); if( db->mallocFailed ){ - sqlite3_free(pBlob); + sqlite3DbFree(db, pBlob); goto blob_open_out; } pBlob->flags = flags; @@ -47203,7 +50218,7 @@ SQLITE_API int sqlite3_blob_close(sqlite3_blob *pBlob){ int rc; rc = sqlite3_finalize(p->pStmt); - sqlite3_free(p); + sqlite3DbFree(p->db, p); return rc; } @@ -47581,7 +50596,8 @@ SQLITE_PRIVATE char sqlite3ExprAffinity(Expr *pExpr){ SQLITE_PRIVATE Expr *sqlite3ExprSetColl(Parse *pParse, Expr *pExpr, Token *pName){ char *zColl = 0; /* Dequoted name of collation sequence */ CollSeq *pColl; - zColl = sqlite3NameFromToken(pParse->db, pName); + sqlite3 *db = pParse->db; + zColl = sqlite3NameFromToken(db, pName); if( pExpr && zColl ){ pColl = sqlite3LocateCollSeq(pParse, zColl, -1); if( pColl ){ @@ -47589,7 +50605,7 @@ SQLITE_PRIVATE Expr *sqlite3ExprSetColl(Parse *pParse, Expr *pExpr, Token *pName pExpr->flags |= EP_ExpCollate; } } - sqlite3_free(zColl); + sqlite3DbFree(db, zColl); return pExpr; } @@ -47771,13 +50787,108 @@ static int codeCompare( addr = sqlite3VdbeAddOp4(pParse->pVdbe, opcode, in2, dest, in1, (void*)p4, P4_COLLSEQ); sqlite3VdbeChangeP5(pParse->pVdbe, p5); - if( p5 & SQLITE_AFF_MASK ){ + if( (p5 & SQLITE_AFF_MASK)!=SQLITE_AFF_NONE ){ sqlite3ExprCacheAffinityChange(pParse, in1, 1); sqlite3ExprCacheAffinityChange(pParse, in2, 1); } return addr; } +#if SQLITE_MAX_EXPR_DEPTH>0 +/* +** Check that argument nHeight is less than or equal to the maximum +** expression depth allowed. If it is not, leave an error message in +** pParse. +*/ +static int checkExprHeight(Parse *pParse, int nHeight){ + int rc = SQLITE_OK; + int mxHeight = pParse->db->aLimit[SQLITE_LIMIT_EXPR_DEPTH]; + if( nHeight>mxHeight ){ + sqlite3ErrorMsg(pParse, + "Expression tree is too large (maximum depth %d)", mxHeight + ); + rc = SQLITE_ERROR; + } + return rc; +} + +/* The following three functions, heightOfExpr(), heightOfExprList() +** and heightOfSelect(), are used to determine the maximum height +** of any expression tree referenced by the structure passed as the +** first argument. +** +** If this maximum height is greater than the current value pointed +** to by pnHeight, the second parameter, then set *pnHeight to that +** value. +*/ +static void heightOfExpr(Expr *p, int *pnHeight){ + if( p ){ + if( p->nHeight>*pnHeight ){ + *pnHeight = p->nHeight; + } + } +} +static void heightOfExprList(ExprList *p, int *pnHeight){ + if( p ){ + int i; + for(i=0; i<p->nExpr; i++){ + heightOfExpr(p->a[i].pExpr, pnHeight); + } + } +} +static void heightOfSelect(Select *p, int *pnHeight){ + if( p ){ + heightOfExpr(p->pWhere, pnHeight); + heightOfExpr(p->pHaving, pnHeight); + heightOfExpr(p->pLimit, pnHeight); + heightOfExpr(p->pOffset, pnHeight); + heightOfExprList(p->pEList, pnHeight); + heightOfExprList(p->pGroupBy, pnHeight); + heightOfExprList(p->pOrderBy, pnHeight); + heightOfSelect(p->pPrior, pnHeight); + } +} + +/* +** Set the Expr.nHeight variable in the structure passed as an +** argument. An expression with no children, Expr.pList or +** Expr.pSelect member has a height of 1. Any other expression +** has a height equal to the maximum height of any other +** referenced Expr plus one. +*/ +static void exprSetHeight(Expr *p){ + int nHeight = 0; + heightOfExpr(p->pLeft, &nHeight); + heightOfExpr(p->pRight, &nHeight); + heightOfExprList(p->pList, &nHeight); + heightOfSelect(p->pSelect, &nHeight); + p->nHeight = nHeight + 1; +} + +/* +** Set the Expr.nHeight variable using the exprSetHeight() function. If +** the height is greater than the maximum allowed expression depth, +** leave an error in pParse. +*/ +SQLITE_PRIVATE void sqlite3ExprSetHeight(Parse *pParse, Expr *p){ + exprSetHeight(p); + checkExprHeight(pParse, p->nHeight); +} + +/* +** Return the maximum height of any expression tree referenced +** by the select statement passed as an argument. +*/ +SQLITE_PRIVATE int sqlite3SelectExprHeight(Select *p){ + int nHeight = 0; + heightOfSelect(p, &nHeight); + return nHeight; +} +#else + #define checkExprHeight(x,y) + #define exprSetHeight(y) +#endif /* SQLITE_MAX_EXPR_DEPTH>0 */ + /* ** Construct a new expression node and return a pointer to it. Memory ** for this node is obtained from sqlite3_malloc(). The calling function @@ -47797,20 +50908,23 @@ SQLITE_PRIVATE Expr *sqlite3Expr( ** this function must always be allocated with sqlite3Expr() for this ** reason. */ - sqlite3ExprDelete(pLeft); - sqlite3ExprDelete(pRight); + sqlite3ExprDelete(db, pLeft); + sqlite3ExprDelete(db, pRight); return 0; } pNew->op = op; pNew->pLeft = pLeft; pNew->pRight = pRight; pNew->iAgg = -1; + pNew->span.z = (u8*)""; if( pToken ){ assert( pToken->dyn==0 ); pNew->span = pNew->token = *pToken; }else if( pLeft ){ if( pRight ){ - sqlite3ExprSpan(pNew, &pLeft->span, &pRight->span); + if( pRight->span.dyn==0 && pLeft->span.dyn==0 ){ + sqlite3ExprSpan(pNew, &pLeft->span, &pRight->span); + } if( pRight->flags & EP_ExpCollate ){ pNew->flags |= EP_ExpCollate; pNew->pColl = pRight->pColl; @@ -47822,7 +50936,7 @@ SQLITE_PRIVATE Expr *sqlite3Expr( } } - sqlite3ExprSetHeight(pNew); + exprSetHeight(pNew); return pNew; } @@ -47837,7 +50951,11 @@ SQLITE_PRIVATE Expr *sqlite3PExpr( Expr *pRight, /* Right operand */ const Token *pToken /* Argument token */ ){ - return sqlite3Expr(pParse->db, op, pLeft, pRight, pToken); + Expr *p = sqlite3Expr(pParse->db, op, pLeft, pRight, pToken); + if( p ){ + checkExprHeight(pParse, p->nHeight); + } + return p; } /* @@ -47882,19 +51000,15 @@ SQLITE_PRIVATE Expr *sqlite3ExprAnd(sqlite3 *db, Expr *pLeft, Expr *pRight){ /* ** Set the Expr.span field of the given expression to span all -** text between the two given tokens. +** text between the two given tokens. Both tokens must be pointing +** at the same string. */ SQLITE_PRIVATE void sqlite3ExprSpan(Expr *pExpr, Token *pLeft, Token *pRight){ assert( pRight!=0 ); assert( pLeft!=0 ); - if( pExpr && pRight->z && pLeft->z ){ - assert( pLeft->dyn==0 || pLeft->z[pLeft->n]==0 ); - if( pLeft->dyn==0 && pRight->dyn==0 ){ - pExpr->span.z = pLeft->z; - pExpr->span.n = pRight->n + (pRight->z - pLeft->z); - }else{ - pExpr->span.z = 0; - } + if( pExpr ){ + pExpr->span.z = pLeft->z; + pExpr->span.n = pRight->n + (pRight->z - pLeft->z); } } @@ -47904,10 +51018,11 @@ SQLITE_PRIVATE void sqlite3ExprSpan(Expr *pExpr, Token *pLeft, Token *pRight){ */ SQLITE_PRIVATE Expr *sqlite3ExprFunction(Parse *pParse, ExprList *pList, Token *pToken){ Expr *pNew; + sqlite3 *db = pParse->db; assert( pToken ); - pNew = sqlite3DbMallocZero(pParse->db, sizeof(Expr) ); + pNew = sqlite3DbMallocZero(db, sizeof(Expr) ); if( pNew==0 ){ - sqlite3ExprListDelete(pList); /* Avoid leaking memory when malloc fails */ + sqlite3ExprListDelete(db, pList); /* Avoid leaking memory when malloc fails */ return 0; } pNew->op = TK_FUNCTION; @@ -47916,7 +51031,7 @@ SQLITE_PRIVATE Expr *sqlite3ExprFunction(Parse *pParse, ExprList *pList, Token * pNew->token = *pToken; pNew->span = pNew->token; - sqlite3ExprSetHeight(pNew); + sqlite3ExprSetHeight(pParse, pNew); return pNew; } @@ -48005,15 +51120,15 @@ SQLITE_PRIVATE void sqlite3ExprAssignVarNumber(Parse *pParse, Expr *pExpr){ /* ** Recursively delete an expression tree. */ -SQLITE_PRIVATE void sqlite3ExprDelete(Expr *p){ +SQLITE_PRIVATE void sqlite3ExprDelete(sqlite3 *db, Expr *p){ if( p==0 ) return; - if( p->span.dyn ) sqlite3_free((char*)p->span.z); - if( p->token.dyn ) sqlite3_free((char*)p->token.z); - sqlite3ExprDelete(p->pLeft); - sqlite3ExprDelete(p->pRight); - sqlite3ExprListDelete(p->pList); - sqlite3SelectDelete(p->pSelect); - sqlite3_free(p); + if( p->span.dyn ) sqlite3DbFree(db, (char*)p->span.z); + if( p->token.dyn ) sqlite3DbFree(db, (char*)p->token.z); + sqlite3ExprDelete(db, p->pLeft); + sqlite3ExprDelete(db, p->pRight); + sqlite3ExprListDelete(db, p->pList); + sqlite3SelectDelete(db, p->pSelect); + sqlite3DbFree(db, p); } /* @@ -48064,7 +51179,7 @@ SQLITE_PRIVATE Expr *sqlite3ExprDup(sqlite3 *db, Expr *p){ return pNew; } SQLITE_PRIVATE void sqlite3TokenCopy(sqlite3 *db, Token *pTo, Token *pFrom){ - if( pTo->dyn ) sqlite3_free((char*)pTo->z); + if( pTo->dyn ) sqlite3DbFree(db, (char*)pTo->z); if( pFrom->z ){ pTo->n = pFrom->n; pTo->z = (u8*)sqlite3DbStrNDup(db, (char*)pFrom->z, pFrom->n); @@ -48084,7 +51199,7 @@ SQLITE_PRIVATE ExprList *sqlite3ExprListDup(sqlite3 *db, ExprList *p){ pNew->nExpr = pNew->nAlloc = p->nExpr; pNew->a = pItem = sqlite3DbMallocRaw(db, p->nExpr*sizeof(p->a[0]) ); if( pItem==0 ){ - sqlite3_free(pNew); + sqlite3DbFree(db, pNew); return 0; } pOldItem = p->a; @@ -48155,7 +51270,7 @@ SQLITE_PRIVATE IdList *sqlite3IdListDup(sqlite3 *db, IdList *p){ pNew->nId = pNew->nAlloc = p->nId; pNew->a = sqlite3DbMallocRaw(db, p->nId*sizeof(p->a[0]) ); if( pNew->a==0 ){ - sqlite3_free(pNew); + sqlite3DbFree(db, pNew); return 0; } for(i=0; i<p->nId; i++){ @@ -48182,8 +51297,8 @@ SQLITE_PRIVATE Select *sqlite3SelectDup(sqlite3 *db, Select *p){ pNew->pPrior = sqlite3SelectDup(db, p->pPrior); pNew->pLimit = sqlite3ExprDup(db, p->pLimit); pNew->pOffset = sqlite3ExprDup(db, p->pOffset); - pNew->iLimit = -1; - pNew->iOffset = -1; + pNew->iLimit = 0; + pNew->iOffset = 0; pNew->isResolved = p->isResolved; pNew->isAgg = p->isAgg; pNew->usesEphm = 0; @@ -48241,8 +51356,8 @@ SQLITE_PRIVATE ExprList *sqlite3ExprListAppend( no_mem: /* Avoid leaking memory if malloc has failed. */ - sqlite3ExprDelete(pExpr); - sqlite3ExprListDelete(pList); + sqlite3ExprDelete(db, pExpr); + sqlite3ExprListDelete(db, pList); return 0; } @@ -48263,85 +51378,21 @@ SQLITE_PRIVATE void sqlite3ExprListCheckLength( } } - -/* The following three functions, heightOfExpr(), heightOfExprList() -** and heightOfSelect(), are used to determine the maximum height -** of any expression tree referenced by the structure passed as the -** first argument. -** -** If this maximum height is greater than the current value pointed -** to by pnHeight, the second parameter, then set *pnHeight to that -** value. -*/ -static void heightOfExpr(Expr *p, int *pnHeight){ - if( p ){ - if( p->nHeight>*pnHeight ){ - *pnHeight = p->nHeight; - } - } -} -static void heightOfExprList(ExprList *p, int *pnHeight){ - if( p ){ - int i; - for(i=0; i<p->nExpr; i++){ - heightOfExpr(p->a[i].pExpr, pnHeight); - } - } -} -static void heightOfSelect(Select *p, int *pnHeight){ - if( p ){ - heightOfExpr(p->pWhere, pnHeight); - heightOfExpr(p->pHaving, pnHeight); - heightOfExpr(p->pLimit, pnHeight); - heightOfExpr(p->pOffset, pnHeight); - heightOfExprList(p->pEList, pnHeight); - heightOfExprList(p->pGroupBy, pnHeight); - heightOfExprList(p->pOrderBy, pnHeight); - heightOfSelect(p->pPrior, pnHeight); - } -} - -/* -** Set the Expr.nHeight variable in the structure passed as an -** argument. An expression with no children, Expr.pList or -** Expr.pSelect member has a height of 1. Any other expression -** has a height equal to the maximum height of any other -** referenced Expr plus one. -*/ -SQLITE_PRIVATE void sqlite3ExprSetHeight(Expr *p){ - int nHeight = 0; - heightOfExpr(p->pLeft, &nHeight); - heightOfExpr(p->pRight, &nHeight); - heightOfExprList(p->pList, &nHeight); - heightOfSelect(p->pSelect, &nHeight); - p->nHeight = nHeight + 1; -} - -/* -** Return the maximum height of any expression tree referenced -** by the select statement passed as an argument. -*/ -SQLITE_PRIVATE int sqlite3SelectExprHeight(Select *p){ - int nHeight = 0; - heightOfSelect(p, &nHeight); - return nHeight; -} - /* ** Delete an entire expression list. */ -SQLITE_PRIVATE void sqlite3ExprListDelete(ExprList *pList){ +SQLITE_PRIVATE void sqlite3ExprListDelete(sqlite3 *db, ExprList *pList){ int i; struct ExprList_item *pItem; if( pList==0 ) return; assert( pList->a!=0 || (pList->nExpr==0 && pList->nAlloc==0) ); assert( pList->nExpr<=pList->nAlloc ); for(pItem=pList->a, i=0; i<pList->nExpr; i++, pItem++){ - sqlite3ExprDelete(pItem->pExpr); - sqlite3_free(pItem->zName); + sqlite3ExprDelete(db, pItem->pExpr); + sqlite3DbFree(db, pItem->zName); } - sqlite3_free(pList->a); - sqlite3_free(pList); + sqlite3DbFree(db, pList->a); + sqlite3DbFree(db, pList); } /* @@ -48508,27 +51559,36 @@ SQLITE_PRIVATE int sqlite3ExprIsConstantOrFunction(Expr *p){ ** to fit in a signed 32-bit integer, return 0 and leave *pValue unchanged. */ SQLITE_PRIVATE int sqlite3ExprIsInteger(Expr *p, int *pValue){ + int rc = 0; + if( p->flags & EP_IntValue ){ + *pValue = p->iTable; + return 1; + } switch( p->op ){ case TK_INTEGER: { - if( sqlite3GetInt32((char*)p->token.z, pValue) ){ - return 1; - } + rc = sqlite3GetInt32((char*)p->token.z, pValue); break; } case TK_UPLUS: { - return sqlite3ExprIsInteger(p->pLeft, pValue); + rc = sqlite3ExprIsInteger(p->pLeft, pValue); + break; } case TK_UMINUS: { int v; if( sqlite3ExprIsInteger(p->pLeft, &v) ){ *pValue = -v; - return 1; + rc = 1; } break; } default: break; } - return 0; + if( rc ){ + p->op = TK_INTEGER; + p->flags |= EP_IntValue; + p->iTable = *pValue; + } + return rc; } /* @@ -48746,7 +51806,7 @@ static int lookupName( pOrig = pEList->a[j].pExpr; if( !pNC->allowAgg && ExprHasProperty(pOrig, EP_Agg) ){ sqlite3ErrorMsg(pParse, "misuse of aliased aggregate %s", zAs); - sqlite3_free(zCol); + sqlite3DbFree(db, zCol); return 2; } pDup = sqlite3ExprDup(db, pOrig); @@ -48754,10 +51814,10 @@ static int lookupName( pDup->pColl = pExpr->pColl; pDup->flags |= EP_ExpCollate; } - if( pExpr->span.dyn ) sqlite3_free((char*)pExpr->span.z); - if( pExpr->token.dyn ) sqlite3_free((char*)pExpr->token.z); + if( pExpr->span.dyn ) sqlite3DbFree(db, (char*)pExpr->span.z); + if( pExpr->token.dyn ) sqlite3DbFree(db, (char*)pExpr->token.z); memcpy(pExpr, pDup, sizeof(*pExpr)); - sqlite3_free(pDup); + sqlite3DbFree(db, pDup); cnt = 1; pMatch = 0; assert( zTab==0 && zDb==0 ); @@ -48785,7 +51845,7 @@ static int lookupName( ** fields are not changed in any context. */ if( cnt==0 && zTab==0 && pColumnToken->z[0]=='"' ){ - sqlite3_free(zCol); + sqlite3DbFree(db, zCol); return 0; } @@ -48825,15 +51885,15 @@ static int lookupName( lookupname_end: /* Clean up and return */ - sqlite3_free(zDb); - sqlite3_free(zTab); - sqlite3ExprDelete(pExpr->pLeft); + sqlite3DbFree(db, zDb); + sqlite3DbFree(db, zTab); + sqlite3ExprDelete(db, pExpr->pLeft); pExpr->pLeft = 0; - sqlite3ExprDelete(pExpr->pRight); + sqlite3ExprDelete(db, pExpr->pRight); pExpr->pRight = 0; pExpr->op = TK_COLUMN; lookupname_end_2: - sqlite3_free(zCol); + sqlite3DbFree(db, zCol); if( cnt==1 ){ assert( pNC!=0 ); sqlite3AuthRead(pParse, pExpr, pSchema, pNC->pSrcList); @@ -49056,11 +52116,7 @@ SQLITE_PRIVATE int sqlite3ExprResolveNames( if( pExpr==0 ) return 0; #if SQLITE_MAX_EXPR_DEPTH>0 { - int mxDepth = pNC->pParse->db->aLimit[SQLITE_LIMIT_EXPR_DEPTH]; - if( (pExpr->nHeight+pNC->pParse->nHeight)>mxDepth ){ - sqlite3ErrorMsg(pNC->pParse, - "Expression tree is too large (maximum depth %d)", mxDepth - ); + if( checkExprHeight(pNC->pParse, pExpr->nHeight + pNC->pParse->nHeight) ){ return 1; } pNC->pParse->nHeight += pExpr->nHeight; @@ -49158,22 +52214,46 @@ static int isCandidateForInOpt(Select *p){ ** ** SELECT <column> FROM <table> ** -** If the mustBeUnique parameter is false, the structure will be used -** for fast set membership tests. In this case an epheremal table must -** be used unless <column> is an INTEGER PRIMARY KEY or an index can -** be found with <column> as its left-most column. -** -** If mustBeUnique is true, then the structure will be used to iterate +** If prNotFound parameter is 0, then the structure will be used to iterate ** through the set members, skipping any duplicates. In this case an ** epheremal table must be used unless the selected <column> is guaranteed ** to be unique - either because it is an INTEGER PRIMARY KEY or it ** is unique by virtue of a constraint or implicit index. +** +** If the prNotFound parameter is not 0, then the structure will be used +** for fast set membership tests. In this case an epheremal table must +** be used unless <column> is an INTEGER PRIMARY KEY or an index can +** be found with <column> as its left-most column. +** +** When the structure is being used for set membership tests, the user +** needs to know whether or not the structure contains an SQL NULL +** value in order to correctly evaluate expressions like "X IN (Y, Z)". +** If there is a chance that the structure may contain a NULL value at +** runtime, then a register is allocated and the register number written +** to *prNotFound. If there is no chance that the structure contains a +** NULL value, then *prNotFound is left unchanged. +** +** If a register is allocated and its location stored in *prNotFound, then +** its initial value is NULL. If the structure does not remain constant +** for the duration of the query (i.e. the set is a correlated sub-select), +** the value of the allocated register is reset to NULL each time the +** structure is repopulated. This allows the caller to use vdbe code +** equivalent to the following: +** +** if( register==NULL ){ +** has_null = <test if data structure contains null> +** register = 1 +** } +** +** in order to avoid running the <test if data structure contains null> +** test more often than is necessary. */ #ifndef SQLITE_OMIT_SUBQUERY -SQLITE_PRIVATE int sqlite3FindInIndex(Parse *pParse, Expr *pX, int mustBeUnique){ +SQLITE_PRIVATE int sqlite3FindInIndex(Parse *pParse, Expr *pX, int *prNotFound){ Select *p; int eType = 0; int iTab = pParse->nTab++; + int mustBeUnique = !prNotFound; /* The follwing if(...) expression is true if the SELECT is of the ** simple form: @@ -49249,13 +52329,20 @@ SQLITE_PRIVATE int sqlite3FindInIndex(Parse *pParse, Expr *pX, int mustBeUnique) eType = IN_INDEX_INDEX; sqlite3VdbeJumpHere(v, iAddr); + if( prNotFound && !pTab->aCol[iCol].notNull ){ + *prNotFound = ++pParse->nMem; + } } } } } if( eType==0 ){ - sqlite3CodeSubselect(pParse, pX); + int rMayHaveNull = 0; + if( prNotFound ){ + *prNotFound = rMayHaveNull = ++pParse->nMem; + } + sqlite3CodeSubselect(pParse, pX, rMayHaveNull); eType = IN_INDEX_EPH; }else{ pX->iTable = iTab; @@ -49277,7 +52364,7 @@ SQLITE_PRIVATE int sqlite3FindInIndex(Parse *pParse, Expr *pX, int mustBeUnique) ** operator or subquery. */ #ifndef SQLITE_OMIT_SUBQUERY -SQLITE_PRIVATE void sqlite3CodeSubselect(Parse *pParse, Expr *pExpr){ +SQLITE_PRIVATE void sqlite3CodeSubselect(Parse *pParse, Expr *pExpr, int rMayHaveNull){ int testAddr = 0; /* One-time test address */ Vdbe *v = sqlite3GetVdbe(pParse); if( v==0 ) return; @@ -49306,6 +52393,10 @@ SQLITE_PRIVATE void sqlite3CodeSubselect(Parse *pParse, Expr *pExpr){ KeyInfo keyInfo; int addr; /* Address of OP_OpenEphemeral instruction */ + if( rMayHaveNull ){ + sqlite3VdbeAddOp2(v, OP_Null, 0, rMayHaveNull); + } + affinity = sqlite3ExprAffinity(pExpr->pLeft); /* Whether this is an 'x IN(SELECT...)' or an 'x IN(<exprlist>)' @@ -49338,7 +52429,7 @@ SQLITE_PRIVATE void sqlite3CodeSubselect(Parse *pParse, Expr *pExpr){ sqlite3SelectDestInit(&dest, SRT_Set, pExpr->iTable); dest.affinity = (int)affinity; assert( (pExpr->iTable&0x0000FFFF)==pExpr->iTable ); - if( sqlite3Select(pParse, pExpr->pSelect, &dest, 0, 0, 0, 0) ){ + if( sqlite3Select(pParse, pExpr->pSelect, &dest, 0, 0, 0) ){ return; } pEList = pExpr->pSelect->pEList; @@ -49357,7 +52448,7 @@ SQLITE_PRIVATE void sqlite3CodeSubselect(Parse *pParse, Expr *pExpr){ int i; ExprList *pList = pExpr->pList; struct ExprList_item *pItem; - int r1, r2; + int r1, r2, r3; if( !affinity ){ affinity = SQLITE_AFF_NONE; @@ -49382,11 +52473,11 @@ SQLITE_PRIVATE void sqlite3CodeSubselect(Parse *pParse, Expr *pExpr){ /* Evaluate the expression and insert it into the temp table */ pParse->disableColCache++; - sqlite3ExprCode(pParse, pE2, r1); + r3 = sqlite3ExprCodeTarget(pParse, pE2, r1); assert( pParse->disableColCache>0 ); pParse->disableColCache--; - sqlite3VdbeAddOp4(v, OP_MakeRecord, r1, 1, r2, &affinity, 1); - sqlite3ExprCacheAffinityChange(pParse, r1, 1); + sqlite3VdbeAddOp4(v, OP_MakeRecord, r3, 1, r2, &affinity, 1); + sqlite3ExprCacheAffinityChange(pParse, r3, 1); sqlite3VdbeAddOp2(v, OP_IdxInsert, pExpr->iTable, r2); } sqlite3ReleaseTempReg(pParse, r1); @@ -49417,9 +52508,9 @@ SQLITE_PRIVATE void sqlite3CodeSubselect(Parse *pParse, Expr *pExpr){ sqlite3VdbeAddOp2(v, OP_Integer, 0, dest.iParm); VdbeComment((v, "Init EXISTS result")); } - sqlite3ExprDelete(pSel->pLimit); + sqlite3ExprDelete(pParse->db, pSel->pLimit); pSel->pLimit = sqlite3PExpr(pParse, TK_INTEGER, 0, 0, &one); - if( sqlite3Select(pParse, pSel, &dest, 0, 0, 0, 0) ){ + if( sqlite3Select(pParse, pSel, &dest, 0, 0, 0) ){ return; } pExpr->iColumn = dest.iParm; @@ -49480,10 +52571,15 @@ static void codeReal(Vdbe *v, const char *z, int n, int negateFlag, int iMem){ ** z[n] character is guaranteed to be something that does not look ** like the continuation of the number. */ -static void codeInteger(Vdbe *v, const char *z, int n, int negFlag, int iMem){ - assert( z || v==0 || sqlite3VdbeDb(v)->mallocFailed ); - if( z ){ +static void codeInteger(Vdbe *v, Expr *pExpr, int negFlag, int iMem){ + const char *z; + if( pExpr->flags & EP_IntValue ){ + int i = pExpr->iTable; + if( negFlag ) i = -i; + sqlite3VdbeAddOp2(v, OP_Integer, i, iMem); + }else if( (z = (char*)pExpr->token.z)!=0 ){ int i; + int n = pExpr->token.n; assert( !isdigit(z[n]) ); if( sqlite3GetInt32(z, &i) ){ if( negFlag ) i = -i; @@ -49606,21 +52702,34 @@ SQLITE_PRIVATE void sqlite3ExprCacheAffinityChange(Parse *pParse, int iStart, in } /* -** Generate code to moves content from one register to another. -** Keep the column cache up-to-date. +** Generate code to move content from registers iFrom...iFrom+nReg-1 +** over to iTo..iTo+nReg-1. Keep the column cache up-to-date. */ -SQLITE_PRIVATE void sqlite3ExprCodeMove(Parse *pParse, int iFrom, int iTo){ +SQLITE_PRIVATE void sqlite3ExprCodeMove(Parse *pParse, int iFrom, int iTo, int nReg){ int i; if( iFrom==iTo ) return; - sqlite3VdbeAddOp2(pParse->pVdbe, OP_Move, iFrom, iTo); + sqlite3VdbeAddOp3(pParse->pVdbe, OP_Move, iFrom, iTo, nReg); for(i=0; i<pParse->nColCache; i++){ - if( pParse->aColCache[i].iReg==iFrom ){ - pParse->aColCache[i].iReg = iTo; + int x = pParse->aColCache[i].iReg; + if( x>=iFrom && x<iFrom+nReg ){ + pParse->aColCache[i].iReg += iTo-iFrom; } } } /* +** Generate code to copy content from registers iFrom...iFrom+nReg-1 +** over to iTo..iTo+nReg-1. +*/ +SQLITE_PRIVATE void sqlite3ExprCodeCopy(Parse *pParse, int iFrom, int iTo, int nReg){ + int i; + if( iFrom==iTo ) return; + for(i=0; i<nReg; i++){ + sqlite3VdbeAddOp2(pParse->pVdbe, OP_Copy, iFrom+i, iTo+i); + } +} + +/* ** Return true if any register in the range iFrom..iTo (inclusive) ** is used as part of the column cache. */ @@ -49739,7 +52848,7 @@ SQLITE_PRIVATE int sqlite3ExprCodeTarget(Parse *pParse, Expr *pExpr, int target) break; } case TK_INTEGER: { - codeInteger(v, (char*)pExpr->token.z, pExpr->token.n, 0, target); + codeInteger(v, pExpr, 0, target); break; } case TK_FLOAT: { @@ -49877,11 +52986,10 @@ SQLITE_PRIVATE int sqlite3ExprCodeTarget(Parse *pParse, Expr *pExpr, int target) Expr *pLeft = pExpr->pLeft; assert( pLeft ); if( pLeft->op==TK_FLOAT || pLeft->op==TK_INTEGER ){ - Token *p = &pLeft->token; if( pLeft->op==TK_FLOAT ){ - codeReal(v, (char*)p->z, p->n, 1, target); + codeReal(v, (char*)pLeft->token.z, pLeft->token.n, 1, target); }else{ - codeInteger(v, (char*)p->z, p->n, 1, target); + codeInteger(v, pLeft, 1, target); } }else{ regFree1 = r1 = sqlite3GetTempReg(pParse); @@ -50003,17 +53111,23 @@ SQLITE_PRIVATE int sqlite3ExprCodeTarget(Parse *pParse, Expr *pExpr, int target) testcase( op==TK_EXISTS ); testcase( op==TK_SELECT ); if( pExpr->iColumn==0 ){ - sqlite3CodeSubselect(pParse, pExpr); + sqlite3CodeSubselect(pParse, pExpr, 0); } inReg = pExpr->iColumn; break; } case TK_IN: { - int j1, j2, j3, j4, j5; + int rNotFound = 0; + int rMayHaveNull = 0; + int j2, j3, j4, j5; char affinity; int eType; - eType = sqlite3FindInIndex(pParse, pExpr, 0); + VdbeNoopComment((v, "begin IN expr r%d", target)); + eType = sqlite3FindInIndex(pParse, pExpr, &rMayHaveNull); + if( rMayHaveNull ){ + rNotFound = ++pParse->nMem; + } /* Figure out the affinity to use to create a key from the results ** of the expression. affinityStr stores a static string suitable for @@ -50021,32 +53135,74 @@ SQLITE_PRIVATE int sqlite3ExprCodeTarget(Parse *pParse, Expr *pExpr, int target) */ affinity = comparisonAffinity(pExpr); - sqlite3VdbeAddOp2(v, OP_Integer, 1, target); /* Code the <expr> from "<expr> IN (...)". The temporary table ** pExpr->iTable contains the values that make up the (...) set. */ - r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, ®Free1); - testcase( regFree1==0 ); - j1 = sqlite3VdbeAddOp1(v, OP_NotNull, r1); - sqlite3VdbeAddOp2(v, OP_Null, 0, target); - j2 = sqlite3VdbeAddOp0(v, OP_Goto); - sqlite3VdbeJumpHere(v, j1); + pParse->disableColCache++; + sqlite3ExprCode(pParse, pExpr->pLeft, target); + pParse->disableColCache--; + j2 = sqlite3VdbeAddOp1(v, OP_IsNull, target); if( eType==IN_INDEX_ROWID ){ - j3 = sqlite3VdbeAddOp1(v, OP_MustBeInt, r1); - j4 = sqlite3VdbeAddOp3(v, OP_NotExists, pExpr->iTable, 0, r1); + j3 = sqlite3VdbeAddOp1(v, OP_MustBeInt, target); + j4 = sqlite3VdbeAddOp3(v, OP_NotExists, pExpr->iTable, 0, target); + sqlite3VdbeAddOp2(v, OP_Integer, 1, target); j5 = sqlite3VdbeAddOp0(v, OP_Goto); sqlite3VdbeJumpHere(v, j3); sqlite3VdbeJumpHere(v, j4); + sqlite3VdbeAddOp2(v, OP_Integer, 0, target); }else{ r2 = regFree2 = sqlite3GetTempReg(pParse); - sqlite3VdbeAddOp4(v, OP_MakeRecord, r1, 1, r2, &affinity, 1); - sqlite3ExprCacheAffinityChange(pParse, r1, 1); + + /* Create a record and test for set membership. If the set contains + ** the value, then jump to the end of the test code. The target + ** register still contains the true (1) value written to it earlier. + */ + sqlite3VdbeAddOp4(v, OP_MakeRecord, target, 1, r2, &affinity, 1); + sqlite3VdbeAddOp2(v, OP_Integer, 1, target); j5 = sqlite3VdbeAddOp3(v, OP_Found, pExpr->iTable, 0, r2); + + /* If the set membership test fails, then the result of the + ** "x IN (...)" expression must be either 0 or NULL. If the set + ** contains no NULL values, then the result is 0. If the set + ** contains one or more NULL values, then the result of the + ** expression is also NULL. + */ + if( rNotFound==0 ){ + /* This branch runs if it is known at compile time (now) that + ** the set contains no NULL values. This happens as the result + ** of a "NOT NULL" constraint in the database schema. No need + ** to test the data structure at runtime in this case. + */ + sqlite3VdbeAddOp2(v, OP_Integer, 0, target); + }else{ + /* This block populates the rNotFound register with either NULL + ** or 0 (an integer value). If the data structure contains one + ** or more NULLs, then set rNotFound to NULL. Otherwise, set it + ** to 0. If register rMayHaveNull is already set to some value + ** other than NULL, then the test has already been run and + ** rNotFound is already populated. + */ + static const char nullRecord[] = { 0x02, 0x00 }; + j3 = sqlite3VdbeAddOp1(v, OP_NotNull, rMayHaveNull); + sqlite3VdbeAddOp2(v, OP_Null, 0, rNotFound); + sqlite3VdbeAddOp4(v, OP_Blob, 2, rMayHaveNull, 0, + nullRecord, P4_STATIC); + j4 = sqlite3VdbeAddOp3(v, OP_Found, pExpr->iTable, 0, rMayHaveNull); + sqlite3VdbeAddOp2(v, OP_Integer, 0, rNotFound); + sqlite3VdbeJumpHere(v, j4); + sqlite3VdbeJumpHere(v, j3); + + /* Copy the value of register rNotFound (which is either NULL or 0) + ** into the target register. This will be the result of the + ** expression. + */ + sqlite3VdbeAddOp2(v, OP_Copy, rNotFound, target); + } } - sqlite3VdbeAddOp2(v, OP_AddImm, target, -1); sqlite3VdbeJumpHere(v, j2); sqlite3VdbeJumpHere(v, j5); + VdbeComment((v, "end IN expr r%d", target)); break; } #endif @@ -50934,25 +54090,14 @@ SQLITE_PRIVATE void sqlite3ExprAnalyzeAggList(NameContext *pNC, ExprList *pList) ** Allocate or deallocate temporary use registers during code generation. */ SQLITE_PRIVATE int sqlite3GetTempReg(Parse *pParse){ - int i, r; if( pParse->nTempReg==0 ){ return ++pParse->nMem; } - for(i=0; i<pParse->nTempReg; i++){ - r = pParse->aTempReg[i]; - if( usedAsColumnCache(pParse, r, r) ) continue; - } - if( i>=pParse->nTempReg ){ - return ++pParse->nMem; - } - while( i<pParse->nTempReg-1 ){ - pParse->aTempReg[i] = pParse->aTempReg[i+1]; - } - pParse->nTempReg--; - return r; + return pParse->aTempReg[--pParse->nTempReg]; } SQLITE_PRIVATE void sqlite3ReleaseTempReg(Parse *pParse, int iReg){ if( iReg && pParse->nTempReg<ArraySize(pParse->aTempReg) ){ + sqlite3ExprWritableRegister(pParse, iReg, iReg); pParse->aTempReg[pParse->nTempReg++] = iReg; } } @@ -51037,7 +54182,7 @@ static void renameTableFunc( /* The principle used to locate the table name in the CREATE TABLE ** statement is that the table name is the first non-space token that - ** is immediately followed by a left parenthesis - TK_LP - or "USING" TK_USING. + ** is immediately followed by a TK_LP or TK_USING token. */ if( zSql ){ do { @@ -51062,7 +54207,7 @@ static void renameTableFunc( zRet = sqlite3MPrintf(db, "%.*s\"%w\"%s", tname.z - zSql, zSql, zTableName, tname.z+tname.n); - sqlite3_result_text(context, zRet, -1, sqlite3_free); + sqlite3_result_text(context, zRet, -1, SQLITE_DYNAMIC); } } @@ -51137,7 +54282,7 @@ static void renameTriggerFunc( */ zRet = sqlite3MPrintf(db, "%.*s\"%w\"%s", tname.z - zSql, zSql, zTableName, tname.z+tname.n); - sqlite3_result_text(context, zRet, -1, sqlite3_free); + sqlite3_result_text(context, zRet, -1, SQLITE_DYNAMIC); } } #endif /* !SQLITE_OMIT_TRIGGER */ @@ -51146,22 +54291,12 @@ static void renameTriggerFunc( ** Register built-in functions used to help implement ALTER TABLE */ SQLITE_PRIVATE void sqlite3AlterFunctions(sqlite3 *db){ - static const struct { - char *zName; - signed char nArg; - void (*xFunc)(sqlite3_context*,int,sqlite3_value **); - } aFuncs[] = { - { "sqlite_rename_table", 2, renameTableFunc}, + sqlite3CreateFunc(db, "sqlite_rename_table", 2, SQLITE_UTF8, 0, + renameTableFunc, 0, 0); #ifndef SQLITE_OMIT_TRIGGER - { "sqlite_rename_trigger", 2, renameTriggerFunc}, + sqlite3CreateFunc(db, "sqlite_rename_trigger", 2, SQLITE_UTF8, 0, + renameTriggerFunc, 0, 0); #endif - }; - int i; - - for(i=0; i<sizeof(aFuncs)/sizeof(aFuncs[0]); i++){ - sqlite3CreateFunc(db, aFuncs[i].zName, aFuncs[i].nArg, - SQLITE_UTF8, 0, aFuncs[i].xFunc, 0, 0); - } } /* @@ -51190,7 +54325,7 @@ static char *whereTempTriggers(Parse *pParse, Table *pTab){ }else{ tmp = zWhere; zWhere = sqlite3MPrintf(db, "%s OR name=%Q", zWhere, pTrig->name); - sqlite3_free(tmp); + sqlite3DbFree(db, tmp); } } } @@ -51401,7 +54536,7 @@ SQLITE_PRIVATE void sqlite3AlterRenameTable( "sql = sqlite_rename_trigger(sql, %Q), " "tbl_name = %Q " "WHERE %s;", zName, zName, zWhere); - sqlite3_free(zWhere); + sqlite3DbFree(db, zWhere); } #endif @@ -51409,8 +54544,8 @@ SQLITE_PRIVATE void sqlite3AlterRenameTable( reloadTableSchema(pParse, pTab, zName); exit_rename_table: - sqlite3SrcListDelete(pSrc); - sqlite3_free(zName); + sqlite3SrcListDelete(db, pSrc); + sqlite3DbFree(db, zName); } @@ -51510,7 +54645,7 @@ SQLITE_PRIVATE void sqlite3AlterFinishAddColumn(Parse *pParse, Token *pColDef){ zDb, SCHEMA_TABLE(iDb), pNew->addColOffset, zCol, pNew->addColOffset+1, zTab ); - sqlite3_free(zCol); + sqlite3DbFree(db, zCol); } /* If the default value of the new column is NULL, then set the file @@ -51577,6 +54712,7 @@ SQLITE_PRIVATE void sqlite3AlterBeginAddColumn(Parse *pParse, SrcList *pSrc){ if( !pNew ) goto exit_begin_add_column; pParse->pNewTable = pNew; pNew->nRef = 1; + pNew->db = db; pNew->nCol = pTab->nCol; assert( pNew->nCol>0 ); nAlloc = (((pNew->nCol-1)/8)*8)+8; @@ -51606,7 +54742,7 @@ SQLITE_PRIVATE void sqlite3AlterBeginAddColumn(Parse *pParse, SrcList *pSrc){ sqlite3ChangeCookie(pParse, iDb); exit_begin_add_column: - sqlite3SrcListDelete(pSrc); + sqlite3SrcListDelete(db, pSrc); return; } #endif /* SQLITE_ALTER_TABLE */ @@ -51930,7 +55066,7 @@ SQLITE_PRIVATE void sqlite3Analyze(Parse *pParse, Token *pName1, Token *pName2){ z = sqlite3NameFromToken(db, pName1); if( z ){ pTab = sqlite3LocateTable(pParse, 0, z, 0); - sqlite3_free(z); + sqlite3DbFree(db, z); if( pTab ){ analyzeTable(pParse, pTab); } @@ -51944,7 +55080,7 @@ SQLITE_PRIVATE void sqlite3Analyze(Parse *pParse, Token *pName1, Token *pName2){ z = sqlite3NameFromToken(db, pTableName); if( z ){ pTab = sqlite3LocateTable(pParse, 0, z, zDb); - sqlite3_free(z); + sqlite3DbFree(db, z); if( pTab ){ analyzeTable(pParse, pTab); } @@ -52031,7 +55167,7 @@ SQLITE_PRIVATE int sqlite3AnalysisLoad(sqlite3 *db, int iDb){ (void)sqlite3SafetyOff(db); rc = sqlite3_exec(db, zSql, analysisLoader, &sInfo, 0); (void)sqlite3SafetyOn(db); - sqlite3_free(zSql); + sqlite3DbFree(db, zSql); return rc; } @@ -52153,18 +55289,12 @@ static void attachFunc( ** hash tables. */ if( db->aDb==db->aDbStatic ){ - aNew = sqlite3_malloc( sizeof(db->aDb[0])*3 ); - if( aNew==0 ){ - db->mallocFailed = 1; - return; - } + aNew = sqlite3DbMallocRaw(db, sizeof(db->aDb[0])*3 ); + if( aNew==0 ) return; memcpy(aNew, db->aDb, sizeof(db->aDb[0])*2); }else{ - aNew = sqlite3_realloc(db->aDb, sizeof(db->aDb[0])*(db->nDb+1) ); - if( aNew==0 ){ - db->mallocFailed = 1; - return; - } + aNew = sqlite3DbRealloc(db, db->aDb, sizeof(db->aDb[0])*(db->nDb+1) ); + if( aNew==0 ) return; } db->aDb = aNew; aNew = &db->aDb[db->nDb++]; @@ -52261,7 +55391,7 @@ attach_error: /* Return an error if we get here */ if( zErrDyn ){ sqlite3_result_error(context, zErrDyn, -1); - sqlite3_free(zErrDyn); + sqlite3DbFree(db, zErrDyn); }else{ zErr[sizeof(zErr)-1] = 0; sqlite3_result_error(context, zErr, -1); @@ -52352,7 +55482,7 @@ static void codeAttach( goto attach_end; } rc = sqlite3AuthCheck(pParse, type, zAuthArg, 0, 0); - sqlite3_free(zAuthArg); + sqlite3DbFree(db, zAuthArg); if(rc!=SQLITE_OK ){ goto attach_end; } @@ -52392,9 +55522,9 @@ static void codeAttach( } attach_end: - sqlite3ExprDelete(pFilename); - sqlite3ExprDelete(pDbname); - sqlite3ExprDelete(pKey); + sqlite3ExprDelete(db, pFilename); + sqlite3ExprDelete(db, pDbname); + sqlite3ExprDelete(db, pKey); } /* @@ -52945,12 +56075,6 @@ SQLITE_PRIVATE void sqlite3FinishCoding(Parse *pParse){ if( db->mallocFailed ) return; if( pParse->nested ) return; if( pParse->nErr ) return; - if( !pParse->pVdbe ){ - if( pParse->rc==SQLITE_OK && pParse->nErr ){ - pParse->rc = SQLITE_ERROR; - return; - } - } /* Begin by generating some termination code at the end of the ** vdbe program @@ -53046,23 +56170,25 @@ SQLITE_PRIVATE void sqlite3FinishCoding(Parse *pParse){ SQLITE_PRIVATE void sqlite3NestedParse(Parse *pParse, const char *zFormat, ...){ va_list ap; char *zSql; + char *zErrMsg = 0; + sqlite3 *db = pParse->db; # define SAVE_SZ (sizeof(Parse) - offsetof(Parse,nVar)) char saveBuf[SAVE_SZ]; if( pParse->nErr ) return; assert( pParse->nested<10 ); /* Nesting should only be of limited depth */ va_start(ap, zFormat); - zSql = sqlite3VMPrintf(pParse->db, zFormat, ap); + zSql = sqlite3VMPrintf(db, zFormat, ap); va_end(ap); if( zSql==0 ){ - pParse->db->mallocFailed = 1; return; /* A malloc must have failed */ } pParse->nested++; memcpy(saveBuf, &pParse->nVar, SAVE_SZ); memset(&pParse->nVar, 0, SAVE_SZ); - sqlite3RunParser(pParse, zSql, 0); - sqlite3_free(zSql); + sqlite3RunParser(pParse, zSql, &zErrMsg); + sqlite3DbFree(db, zErrMsg); + sqlite3DbFree(db, zSql); memcpy(&pParse->nVar, saveBuf, SAVE_SZ); pParse->nested--; } @@ -53082,11 +56208,13 @@ SQLITE_PRIVATE void sqlite3NestedParse(Parse *pParse, const char *zFormat, ...){ SQLITE_PRIVATE Table *sqlite3FindTable(sqlite3 *db, const char *zName, const char *zDatabase){ Table *p = 0; int i; + int nName; assert( zName!=0 ); + nName = sqlite3Strlen(db, zName) + 1; for(i=OMIT_TEMPDB; i<db->nDb; i++){ int j = (i<2) ? i^1 : i; /* Search TEMP before MAIN */ if( zDatabase!=0 && sqlite3StrICmp(zDatabase, db->aDb[j].zName) ) continue; - p = sqlite3HashFind(&db->aDb[j].pSchema->tblHash, zName, strlen(zName)+1); + p = sqlite3HashFind(&db->aDb[j].pSchema->tblHash, zName, nName); if( p ) break; } return p; @@ -53144,13 +56272,14 @@ SQLITE_PRIVATE Table *sqlite3LocateTable( SQLITE_PRIVATE Index *sqlite3FindIndex(sqlite3 *db, const char *zName, const char *zDb){ Index *p = 0; int i; + int nName = sqlite3Strlen(db, zName)+1; for(i=OMIT_TEMPDB; i<db->nDb; i++){ int j = (i<2) ? i^1 : i; /* Search TEMP before MAIN */ Schema *pSchema = db->aDb[j].pSchema; if( zDb && sqlite3StrICmp(zDb, db->aDb[j].zName) ) continue; assert( pSchema || (j==1 && !db->aDb[1].pBt) ); if( pSchema ){ - p = sqlite3HashFind(&pSchema->idxHash, zName, strlen(zName)+1); + p = sqlite3HashFind(&pSchema->idxHash, zName, nName); } if( p ) break; } @@ -53161,8 +56290,9 @@ SQLITE_PRIVATE Index *sqlite3FindIndex(sqlite3 *db, const char *zName, const cha ** Reclaim the memory used by an index */ static void freeIndex(Index *p){ - sqlite3_free(p->zColAff); - sqlite3_free(p); + sqlite3 *db = p->pTable->db; + sqlite3DbFree(db, p->zColAff); + sqlite3DbFree(db, p); } /* @@ -53177,7 +56307,7 @@ static void sqliteDeleteIndex(Index *p){ Index *pOld; const char *zName = p->zName; - pOld = sqlite3HashInsert(&p->pSchema->idxHash, zName, strlen( zName)+1, 0); + pOld = sqlite3HashInsert(&p->pSchema->idxHash, zName, strlen(zName)+1, 0); assert( pOld==0 || pOld==p ); freeIndex(p); } @@ -53193,7 +56323,7 @@ SQLITE_PRIVATE void sqlite3UnlinkAndDeleteIndex(sqlite3 *db, int iDb, const char int len; Hash *pHash = &db->aDb[iDb].pSchema->idxHash; - len = strlen(zIdxName); + len = sqlite3Strlen(db, zIdxName); pIndex = sqlite3HashInsert(pHash, zIdxName, len+1, 0); if( pIndex ){ if( pIndex->pTable->pIndex==pIndex ){ @@ -53256,7 +56386,7 @@ SQLITE_PRIVATE void sqlite3ResetInternalSchema(sqlite3 *db, int iDb){ for(i=j=2; i<db->nDb; i++){ struct Db *pDb = &db->aDb[i]; if( pDb->pBt==0 ){ - sqlite3_free(pDb->zName); + sqlite3DbFree(db, pDb->zName); pDb->zName = 0; continue; } @@ -53269,7 +56399,7 @@ SQLITE_PRIVATE void sqlite3ResetInternalSchema(sqlite3 *db, int iDb){ db->nDb = j; if( db->nDb<=2 && db->aDb!=db->aDbStatic ){ memcpy(db->aDbStatic, db->aDb, 2*sizeof(db->aDb[0])); - sqlite3_free(db->aDb); + sqlite3DbFree(db, db->aDb); db->aDb = db->aDbStatic; } } @@ -53287,15 +56417,16 @@ SQLITE_PRIVATE void sqlite3CommitInternalChanges(sqlite3 *db){ static void sqliteResetColumnNames(Table *pTable){ int i; Column *pCol; + sqlite3 *db = pTable->db; assert( pTable!=0 ); if( (pCol = pTable->aCol)!=0 ){ for(i=0; i<pTable->nCol; i++, pCol++){ - sqlite3_free(pCol->zName); - sqlite3ExprDelete(pCol->pDflt); - sqlite3_free(pCol->zType); - sqlite3_free(pCol->zColl); + sqlite3DbFree(db, pCol->zName); + sqlite3ExprDelete(db, pCol->pDflt); + sqlite3DbFree(db, pCol->zType); + sqlite3DbFree(db, pCol->zColl); } - sqlite3_free(pTable->aCol); + sqlite3DbFree(db, pTable->aCol); } pTable->aCol = 0; pTable->nCol = 0; @@ -53314,8 +56445,10 @@ static void sqliteResetColumnNames(Table *pTable){ SQLITE_PRIVATE void sqlite3DeleteTable(Table *pTable){ Index *pIndex, *pNext; FKey *pFKey, *pNextFKey; + sqlite3 *db; if( pTable==0 ) return; + db = pTable->db; /* Do not delete the table until the reference count reaches zero. */ pTable->nRef--; @@ -53340,21 +56473,21 @@ SQLITE_PRIVATE void sqlite3DeleteTable(Table *pTable){ pNextFKey = pFKey->pNextFrom; assert( sqlite3HashFind(&pTable->pSchema->aFKey, pFKey->zTo, strlen(pFKey->zTo)+1)!=pFKey ); - sqlite3_free(pFKey); + sqlite3DbFree(db, pFKey); } #endif /* Delete the Table structure itself. */ sqliteResetColumnNames(pTable); - sqlite3_free(pTable->zName); - sqlite3_free(pTable->zColAff); - sqlite3SelectDelete(pTable->pSelect); + sqlite3DbFree(db, pTable->zName); + sqlite3DbFree(db, pTable->zColAff); + sqlite3SelectDelete(db, pTable->pSelect); #ifndef SQLITE_OMIT_CHECK - sqlite3ExprDelete(pTable->pCheck); + sqlite3ExprDelete(db, pTable->pCheck); #endif sqlite3VtabClear(pTable); - sqlite3_free(pTable); + sqlite3DbFree(db, pTable); } /* @@ -53444,7 +56577,7 @@ SQLITE_PRIVATE int sqlite3FindDb(sqlite3 *db, Token *pName){ break; } } - sqlite3_free(zName); + sqlite3DbFree(db, zName); } return i; } @@ -53635,6 +56768,7 @@ SQLITE_PRIVATE void sqlite3StartTable( pTable->iPKey = -1; pTable->pSchema = db->aDb[iDb].pSchema; pTable->nRef = 1; + pTable->db = db; if( pParse->pNewTable ) sqlite3DeleteTable(pParse->pNewTable); pParse->pNewTable = pTable; @@ -53714,7 +56848,7 @@ SQLITE_PRIVATE void sqlite3StartTable( /* If an error occurs, we jump here */ begin_table_error: - sqlite3_free(zName); + sqlite3DbFree(db, zName); return; } @@ -53757,7 +56891,7 @@ SQLITE_PRIVATE void sqlite3AddColumn(Parse *pParse, Token *pName){ for(i=0; i<p->nCol; i++){ if( STRICMP(z, p->aCol[i].zName) ){ sqlite3ErrorMsg(pParse, "duplicate column name: %s", z); - sqlite3_free(z); + sqlite3DbFree(db, z); return; } } @@ -53765,7 +56899,7 @@ SQLITE_PRIVATE void sqlite3AddColumn(Parse *pParse, Token *pName){ Column *aNew; aNew = sqlite3DbRealloc(pParse->db,p->aCol,(p->nCol+8)*sizeof(p->aCol[0])); if( aNew==0 ){ - sqlite3_free(z); + sqlite3DbFree(db, z); return; } p->aCol = aNew; @@ -53872,13 +57006,15 @@ SQLITE_PRIVATE void sqlite3AddColumnType(Parse *pParse, Token *pType){ Table *p; int i; Column *pCol; + sqlite3 *db; if( (p = pParse->pNewTable)==0 ) return; i = p->nCol-1; if( i<0 ) return; pCol = &p->aCol[i]; - sqlite3_free(pCol->zType); - pCol->zType = sqlite3NameFromToken(pParse->db, pType); + db = pParse->db; + sqlite3DbFree(db, pCol->zType); + pCol->zType = sqlite3NameFromToken(db, pType); pCol->affinity = sqlite3AffinityType(pType); } @@ -53895,6 +57031,7 @@ SQLITE_PRIVATE void sqlite3AddColumnType(Parse *pParse, Token *pType){ SQLITE_PRIVATE void sqlite3AddDefaultValue(Parse *pParse, Expr *pExpr){ Table *p; Column *pCol; + sqlite3 *db = pParse->db; if( (p = pParse->pNewTable)!=0 ){ pCol = &(p->aCol[p->nCol-1]); if( !sqlite3ExprIsConstantOrFunction(pExpr) ){ @@ -53902,15 +57039,14 @@ SQLITE_PRIVATE void sqlite3AddDefaultValue(Parse *pParse, Expr *pExpr){ pCol->zName); }else{ Expr *pCopy; - sqlite3 *db = pParse->db; - sqlite3ExprDelete(pCol->pDflt); + sqlite3ExprDelete(db, pCol->pDflt); pCol->pDflt = pCopy = sqlite3ExprDup(db, pExpr); if( pCopy ){ sqlite3TokenCopy(db, &pCopy->span, &pExpr->span); } } } - sqlite3ExprDelete(pExpr); + sqlite3ExprDelete(db, pExpr); } /* @@ -53983,7 +57119,7 @@ SQLITE_PRIVATE void sqlite3AddPrimaryKey( } primary_key_exit: - sqlite3ExprListDelete(pList); + sqlite3ExprListDelete(pParse->db, pList); return; } @@ -53994,9 +57130,9 @@ SQLITE_PRIVATE void sqlite3AddCheckConstraint( Parse *pParse, /* Parsing context */ Expr *pCheckExpr /* The check expression */ ){ + sqlite3 *db = pParse->db; #ifndef SQLITE_OMIT_CHECK Table *pTab = pParse->pNewTable; - sqlite3 *db = pParse->db; if( pTab && !IN_DECLARE_VTAB ){ /* The CHECK expression must be duplicated so that tokens refer ** to malloced space and not the (ephemeral) text of the CREATE TABLE @@ -54005,7 +57141,7 @@ SQLITE_PRIVATE void sqlite3AddCheckConstraint( sqlite3ExprDup(db, pCheckExpr)); } #endif - sqlite3ExprDelete(pCheckExpr); + sqlite3ExprDelete(db, pCheckExpr); } /* @@ -54016,11 +57152,12 @@ SQLITE_PRIVATE void sqlite3AddCollateType(Parse *pParse, Token *pToken){ Table *p; int i; char *zColl; /* Dequoted name of collation sequence */ + sqlite3 *db; if( (p = pParse->pNewTable)==0 ) return; i = p->nCol-1; - - zColl = sqlite3NameFromToken(pParse->db, pToken); + db = pParse->db; + zColl = sqlite3NameFromToken(db, pToken); if( !zColl ) return; if( sqlite3LocateCollSeq(pParse, zColl, -1) ){ @@ -54038,7 +57175,7 @@ SQLITE_PRIVATE void sqlite3AddCollateType(Parse *pParse, Token *pToken){ } } }else{ - sqlite3_free(zColl); + sqlite3DbFree(db, zColl); } } @@ -54071,7 +57208,7 @@ SQLITE_PRIVATE CollSeq *sqlite3LocateCollSeq(Parse *pParse, const char *zName, i pColl = sqlite3GetCollSeq(db, pColl, zName, nName); if( !pColl ){ if( nName<0 ){ - nName = strlen(zName); + nName = sqlite3Strlen(db, zName); } sqlite3ErrorMsg(pParse, "no such collation sequence: %.*s", nName, zName); pColl = 0; @@ -54175,7 +57312,7 @@ static char *createTableStmt(sqlite3 *db, Table *p, int isTemp){ zEnd = "\n)"; } n += 35 + 6*p->nCol; - zStmt = sqlite3_malloc( n ); + zStmt = sqlite3Malloc( n ); if( zStmt==0 ){ db->mallocFailed = 1; return 0; @@ -54325,11 +57462,12 @@ SQLITE_PRIVATE void sqlite3EndTable( SelectDest dest; Table *pSelTab; + assert(pParse->nTab==0); sqlite3VdbeAddOp3(v, OP_OpenWrite, 1, pParse->regRoot, iDb); sqlite3VdbeChangeP5(v, 1); pParse->nTab = 2; sqlite3SelectDestInit(&dest, SRT_Table, 1); - sqlite3Select(pParse, pSelect, &dest, 0, 0, 0, 0); + sqlite3Select(pParse, pSelect, &dest, 0, 0, 0); sqlite3VdbeAddOp1(v, OP_Close, 1); if( pParse->nErr==0 ){ pSelTab = sqlite3ResultSetOfSelect(pParse, 0, pSelect); @@ -54371,7 +57509,7 @@ SQLITE_PRIVATE void sqlite3EndTable( zStmt, pParse->regRowid ); - sqlite3_free(zStmt); + sqlite3DbFree(db, zStmt); sqlite3ChangeCookie(pParse, iDb); #ifndef SQLITE_OMIT_AUTOINCREMENT @@ -54461,13 +57599,13 @@ SQLITE_PRIVATE void sqlite3CreateView( if( pParse->nVar>0 ){ sqlite3ErrorMsg(pParse, "parameters are not allowed in views"); - sqlite3SelectDelete(pSelect); + sqlite3SelectDelete(db, pSelect); return; } sqlite3StartTable(pParse, pName1, pName2, isTemp, 1, 0, noErr); p = pParse->pNewTable; if( p==0 || pParse->nErr ){ - sqlite3SelectDelete(pSelect); + sqlite3SelectDelete(db, pSelect); return; } sqlite3TwoPartName(pParse, pName1, pName2, &pName); @@ -54475,7 +57613,7 @@ SQLITE_PRIVATE void sqlite3CreateView( if( sqlite3FixInit(&sFix, pParse, iDb, "view", pName) && sqlite3FixSelect(&sFix, pSelect) ){ - sqlite3SelectDelete(pSelect); + sqlite3SelectDelete(db, pSelect); return; } @@ -54485,7 +57623,7 @@ SQLITE_PRIVATE void sqlite3CreateView( ** they will persist after the current sqlite3_exec() call returns. */ p->pSelect = sqlite3SelectDup(db, pSelect); - sqlite3SelectDelete(pSelect); + sqlite3SelectDelete(db, pSelect); if( db->mallocFailed ){ return; } @@ -54592,7 +57730,7 @@ SQLITE_PRIVATE int sqlite3ViewGetColumnNames(Parse *pParse, Table *pTable){ pTable->nCol = 0; nErr++; } - sqlite3SelectDelete(pSel); + sqlite3SelectDelete(db, pSel); } else { nErr++; } @@ -54908,7 +58046,7 @@ SQLITE_PRIVATE void sqlite3DropTable(Parse *pParse, SrcList *pName, int isView, sqliteViewResetAll(db, iDb); exit_drop_table: - sqlite3SrcListDelete(pName); + sqlite3SrcListDelete(db, pName); } /* @@ -54943,8 +58081,10 @@ SQLITE_PRIVATE void sqlite3CreateForeignKey( int i; int nCol; char *z; + sqlite3 *db; assert( pTo!=0 ); + db = pParse->db; if( p==0 || pParse->nErr || IN_DECLARE_VTAB ) goto fk_end; if( pFromCol==0 ){ int iCol = p->nCol-1; @@ -54970,7 +58110,7 @@ SQLITE_PRIVATE void sqlite3CreateForeignKey( nByte += strlen(pToCol->a[i].zName) + 1; } } - pFKey = sqlite3DbMallocZero(pParse->db, nByte ); + pFKey = sqlite3DbMallocZero(db, nByte ); if( pFKey==0 ){ goto fk_end; } @@ -55024,10 +58164,10 @@ SQLITE_PRIVATE void sqlite3CreateForeignKey( pFKey = 0; fk_end: - sqlite3_free(pFKey); + sqlite3DbFree(db, pFKey); #endif /* !defined(SQLITE_OMIT_FOREIGN_KEY) */ - sqlite3ExprListDelete(pFromCol); - sqlite3ExprListDelete(pToCol); + sqlite3ExprListDelete(db, pFromCol); + sqlite3ExprListDelete(db, pToCol); } /* @@ -55105,7 +58245,7 @@ static void sqlite3RefillIndex(Parse *pParse, Index *pIndex, int memRootPage){ regRowid = regIdxKey + pIndex->nColumn; j1 = sqlite3VdbeAddOp3(v, OP_IsNull, regIdxKey, 0, pIndex->nColumn); j2 = sqlite3VdbeAddOp4(v, OP_IsUnique, iIdx, - 0, regRowid, (char*)regRecord, P4_INT32); + 0, regRowid, SQLITE_INT_TO_PTR(regRecord), P4_INT32); sqlite3VdbeAddOp4(v, OP_Halt, SQLITE_CONSTRAINT, OE_Abort, 0, "indexed columns are not unique", P4_STATIC); sqlite3VdbeJumpHere(v, j1); @@ -55261,15 +58401,11 @@ SQLITE_PRIVATE void sqlite3CreateIndex( goto exit_create_index; } }else{ - char zBuf[30]; int n; Index *pLoop; for(pLoop=pTab->pIndex, n=1; pLoop; pLoop=pLoop->pNext, n++){} - sqlite3_snprintf(sizeof(zBuf),zBuf,"_%d",n); - zName = 0; - sqlite3SetString(&zName, "sqlite_autoindex_", pTab->zName, zBuf, (char*)0); + zName = sqlite3MPrintf(db, "sqlite_autoindex_%s_%d", pTab->zName, n); if( zName==0 ){ - db->mallocFailed = 1; goto exit_create_index; } } @@ -55518,7 +58654,7 @@ SQLITE_PRIVATE void sqlite3CreateIndex( iMem, zStmt ); - sqlite3_free(zStmt); + sqlite3DbFree(db, zStmt); /* Fill the index with data and reparse the schema. Code an OP_Expire ** to invalidate all pre-compiled statements. @@ -55558,9 +58694,9 @@ exit_create_index: if( pIndex ){ freeIndex(pIndex); } - sqlite3ExprListDelete(pList); - sqlite3SrcListDelete(pTblName); - sqlite3_free(zName); + sqlite3ExprListDelete(db, pList); + sqlite3SrcListDelete(db, pTblName); + sqlite3DbFree(db, zName); return; } @@ -55689,7 +58825,7 @@ SQLITE_PRIVATE void sqlite3DropIndex(Parse *pParse, SrcList *pName, int ifExists } exit_drop_index: - sqlite3SrcListDelete(pName); + sqlite3SrcListDelete(db, pName); } /* @@ -55759,7 +58895,7 @@ SQLITE_PRIVATE IdList *sqlite3IdListAppend(sqlite3 *db, IdList *pList, Token *pT &i ); if( i<0 ){ - sqlite3IdListDelete(pList); + sqlite3IdListDelete(db, pList); return 0; } pList->a[i].zName = sqlite3NameFromToken(db, pToken); @@ -55769,14 +58905,14 @@ SQLITE_PRIVATE IdList *sqlite3IdListAppend(sqlite3 *db, IdList *pList, Token *pT /* ** Delete an IdList. */ -SQLITE_PRIVATE void sqlite3IdListDelete(IdList *pList){ +SQLITE_PRIVATE void sqlite3IdListDelete(sqlite3 *db, IdList *pList){ int i; if( pList==0 ) return; for(i=0; i<pList->nId; i++){ - sqlite3_free(pList->a[i].zName); + sqlite3DbFree(db, pList->a[i].zName); } - sqlite3_free(pList->a); - sqlite3_free(pList); + sqlite3DbFree(db, pList->a); + sqlite3DbFree(db, pList); } /* @@ -55835,7 +58971,7 @@ SQLITE_PRIVATE SrcList *sqlite3SrcListAppend( pNew = sqlite3DbRealloc(db, pList, sizeof(*pList) + (pList->nAlloc-1)*sizeof(pList->a[0]) ); if( pNew==0 ){ - sqlite3SrcListDelete(pList); + sqlite3SrcListDelete(db, pList); return 0; } pList = pNew; @@ -55879,20 +59015,20 @@ SQLITE_PRIVATE void sqlite3SrcListAssignCursors(Parse *pParse, SrcList *pList){ /* ** Delete an entire SrcList including all its substructure. */ -SQLITE_PRIVATE void sqlite3SrcListDelete(SrcList *pList){ +SQLITE_PRIVATE void sqlite3SrcListDelete(sqlite3 *db, SrcList *pList){ int i; struct SrcList_item *pItem; if( pList==0 ) return; for(pItem=pList->a, i=0; i<pList->nSrc; i++, pItem++){ - sqlite3_free(pItem->zDatabase); - sqlite3_free(pItem->zName); - sqlite3_free(pItem->zAlias); + sqlite3DbFree(db, pItem->zDatabase); + sqlite3DbFree(db, pItem->zName); + sqlite3DbFree(db, pItem->zAlias); sqlite3DeleteTable(pItem->pTab); - sqlite3SelectDelete(pItem->pSelect); - sqlite3ExprDelete(pItem->pOn); - sqlite3IdListDelete(pItem->pUsing); + sqlite3SelectDelete(db, pItem->pSelect); + sqlite3ExprDelete(db, pItem->pOn); + sqlite3IdListDelete(db, pItem->pUsing); } - sqlite3_free(pList); + sqlite3DbFree(db, pList); } /* @@ -55925,9 +59061,9 @@ SQLITE_PRIVATE SrcList *sqlite3SrcListAppendFromTerm( sqlite3 *db = pParse->db; p = sqlite3SrcListAppend(db, p, pTable, pDatabase); if( p==0 || p->nSrc==0 ){ - sqlite3ExprDelete(pOn); - sqlite3IdListDelete(pUsing); - sqlite3SelectDelete(pSubquery); + sqlite3ExprDelete(db, pOn); + sqlite3IdListDelete(db, pUsing); + sqlite3SelectDelete(db, pSubquery); return p; } pItem = &p->a[p->nSrc-1]; @@ -56232,11 +59368,11 @@ SQLITE_PRIVATE void sqlite3Reindex(Parse *pParse, Token *pName1, Token *pName2){ if( pColl ){ if( zColl ){ reindexDatabases(pParse, zColl); - sqlite3_free(zColl); + sqlite3DbFree(db, zColl); } return; } - sqlite3_free(zColl); + sqlite3DbFree(db, zColl); } iDb = sqlite3TwoPartName(pParse, pName1, pName2, &pObjName); if( iDb<0 ) return; @@ -56246,11 +59382,11 @@ SQLITE_PRIVATE void sqlite3Reindex(Parse *pParse, Token *pName1, Token *pName2){ pTab = sqlite3FindTable(db, z, zDb); if( pTab ){ reindexTable(pParse, pTab, 0); - sqlite3_free(z); + sqlite3DbFree(db, z); return; } pIndex = sqlite3FindIndex(db, z, zDb); - sqlite3_free(z); + sqlite3DbFree(db, z); if( pIndex ){ sqlite3BeginWriteOperation(pParse, 0, iDb); sqlite3RefillIndex(pParse, pIndex, -1); @@ -56265,7 +59401,7 @@ SQLITE_PRIVATE void sqlite3Reindex(Parse *pParse, Token *pName1, Token *pName2){ ** with OP_OpenRead or OP_OpenWrite to access database index pIdx. ** ** If successful, a pointer to the new structure is returned. In this case -** the caller is responsible for calling sqlite3_free() on the returned +** the caller is responsible for calling sqlite3DbFree(db, ) on the returned ** pointer. If an error occurs (out of memory or missing collation ** sequence), NULL is returned and the state of pParse updated to reflect ** the error. @@ -56274,7 +59410,8 @@ SQLITE_PRIVATE KeyInfo *sqlite3IndexKeyinfo(Parse *pParse, Index *pIdx){ int i; int nCol = pIdx->nColumn; int nBytes = sizeof(KeyInfo) + (nCol-1)*sizeof(CollSeq*) + nCol; - KeyInfo *pKey = (KeyInfo *)sqlite3DbMallocZero(pParse->db, nBytes); + sqlite3 *db = pParse->db; + KeyInfo *pKey = (KeyInfo *)sqlite3DbMallocZero(db, nBytes); if( pKey ){ pKey->db = pParse->db; @@ -56290,7 +59427,7 @@ SQLITE_PRIVATE KeyInfo *sqlite3IndexKeyinfo(Parse *pParse, Index *pIdx){ } if( pParse->nErr ){ - sqlite3_free(pKey); + sqlite3DbFree(db, pKey); pKey = 0; } return pKey; @@ -56324,12 +59461,12 @@ SQLITE_PRIVATE KeyInfo *sqlite3IndexKeyinfo(Parse *pParse, Index *pIdx){ */ static void callCollNeeded(sqlite3 *db, const char *zName, int nName){ assert( !db->xCollNeeded || !db->xCollNeeded16 ); - if( nName<0 ) nName = strlen(zName); + if( nName<0 ) nName = sqlite3Strlen(db, zName); if( db->xCollNeeded ){ char *zExternal = sqlite3DbStrNDup(db, zName, nName); if( !zExternal ) return; db->xCollNeeded(db->pCollNeededArg, db, (int)ENC(db), zExternal); - sqlite3_free(zExternal); + sqlite3DbFree(db, zExternal); } #ifndef SQLITE_OMIT_UTF16 if( db->xCollNeeded16 ){ @@ -56457,7 +59594,7 @@ static CollSeq *findCollSeqEntry( int create ){ CollSeq *pColl; - if( nName<0 ) nName = strlen(zName); + if( nName<0 ) nName = sqlite3Strlen(db, zName); pColl = sqlite3HashFind(&db->aCollSeq, zName, nName); if( 0==pColl && create ){ @@ -56481,7 +59618,7 @@ static CollSeq *findCollSeqEntry( assert( pDel==0 || pDel==pColl ); if( pDel!=0 ){ db->mallocFailed = 1; - sqlite3_free(pDel); + sqlite3DbFree(db, pDel); pColl = 0; } } @@ -56611,7 +59748,7 @@ SQLITE_PRIVATE FuncDef *sqlite3FindFunction( pBest->zName[nName] = 0; if( pBest==sqlite3HashInsert(&db->aFunc,pBest->zName,nName,(void*)pBest) ){ db->mallocFailed = 1; - sqlite3_free(pBest); + sqlite3DbFree(db, pBest); return 0; } } @@ -56624,9 +59761,11 @@ SQLITE_PRIVATE FuncDef *sqlite3FindFunction( /* ** Free all resources held by the schema structure. The void* argument points -** at a Schema struct. This function does not call sqlite3_free() on the +** at a Schema struct. This function does not call sqlite3DbFree(db, ) on the ** pointer itself, it just cleans up subsiduary resources (i.e. the contents ** of the schema hash tables). +** +** The Schema.cache_size variable is not cleared. */ SQLITE_PRIVATE void sqlite3SchemaFree(void *p){ Hash temp1; @@ -56640,7 +59779,7 @@ SQLITE_PRIVATE void sqlite3SchemaFree(void *p){ sqlite3HashClear(&pSchema->aFKey); sqlite3HashClear(&pSchema->idxHash); for(pElem=sqliteHashFirst(&temp2); pElem; pElem=sqliteHashNext(pElem)){ - sqlite3DeleteTrigger((Trigger*)sqliteHashData(pElem)); + sqlite3DeleteTrigger(0, (Trigger*)sqliteHashData(pElem)); } sqlite3HashClear(&temp2); sqlite3HashInit(&pSchema->tblHash, SQLITE_HASH_STRING, 0); @@ -56785,8 +59924,8 @@ SQLITE_PRIVATE void sqlite3MaterializeView( pDup = sqlite3SelectNew(pParse, 0, pFrom, pWhere, 0, 0, 0, 0, 0, 0); } sqlite3SelectDestInit(&dest, SRT_EphemTab, iCur); - sqlite3Select(pParse, pDup, &dest, 0, 0, 0, 0); - sqlite3SelectDelete(pDup); + sqlite3Select(pParse, pDup, &dest, 0, 0, 0); + sqlite3SelectDelete(db, pDup); } #endif /* !defined(SQLITE_OMIT_VIEW) && !defined(SQLITE_OMIT_TRIGGER) */ @@ -57094,8 +60233,8 @@ SQLITE_PRIVATE void sqlite3DeleteFrom( delete_from_cleanup: sqlite3AuthContextPop(&sContext); - sqlite3SrcListDelete(pTabList); - sqlite3ExprDelete(pWhere); + sqlite3SrcListDelete(db, pTabList); + sqlite3ExprDelete(db, pWhere); return; } @@ -57470,7 +60609,7 @@ static void *contextMalloc(sqlite3_context *context, i64 nByte){ sqlite3_result_error_toobig(context); z = 0; }else{ - z = sqlite3_malloc(nByte); + z = sqlite3Malloc(nByte); if( !z && nByte>0 ){ sqlite3_result_error_nomem(context); } @@ -58053,14 +61192,14 @@ static void replaceFunc( nOut += nRep - nPattern; if( nOut>=db->aLimit[SQLITE_LIMIT_LENGTH] ){ sqlite3_result_error_toobig(context); - sqlite3_free(zOut); + sqlite3DbFree(db, zOut); return; } zOld = zOut; zOut = sqlite3_realloc(zOut, (int)nOut); if( zOut==0 ){ sqlite3_result_error_nomem(context); - sqlite3_free(zOld); + sqlite3DbFree(db, zOld); return; } memcpy(&zOut[j], zRep, nRep); @@ -58129,7 +61268,7 @@ static void trimFunc( } } if( nChar>0 ){ - flags = (int)sqlite3_user_data(context); + flags = SQLITE_PTR_TO_INT(sqlite3_user_data(context)); if( flags & 1 ){ while( nIn>0 ){ int len; @@ -58387,8 +61526,8 @@ static void groupConcatStep( const char *zVal; StrAccum *pAccum; const char *zSep; - int nVal, nSep; - if( sqlite3_value_type(argv[0])==SQLITE_NULL ) return; + int nVal, nSep, i; + if( argc==0 || sqlite3_value_type(argv[0])==SQLITE_NULL ) return; pAccum = (StrAccum*)sqlite3_aggregate_context(context, sizeof(*pAccum)); if( pAccum ){ @@ -58396,18 +61535,22 @@ static void groupConcatStep( pAccum->useMalloc = 1; pAccum->mxAlloc = db->aLimit[SQLITE_LIMIT_LENGTH]; if( pAccum->nChar ){ - if( argc==2 ){ - zSep = (char*)sqlite3_value_text(argv[1]); - nSep = sqlite3_value_bytes(argv[1]); + if( argc>1 ){ + zSep = (char*)sqlite3_value_text(argv[argc-1]); + nSep = sqlite3_value_bytes(argv[argc-1]); }else{ zSep = ","; nSep = 1; } sqlite3StrAccumAppend(pAccum, zSep, nSep); } - zVal = (char*)sqlite3_value_text(argv[0]); - nVal = sqlite3_value_bytes(argv[0]); - sqlite3StrAccumAppend(pAccum, zVal, nVal); + i = 0; + do{ + zVal = (char*)sqlite3_value_text(argv[i]); + nVal = sqlite3_value_bytes(argv[i]); + sqlite3StrAccumAppend(pAccum, zVal, nVal); + i++; + }while( i<argc-1 ); } } static void groupConcatFinalize(sqlite3_context *context){ @@ -58496,15 +61639,14 @@ SQLITE_PRIVATE void sqlite3RegisterBuiltinFunctions(sqlite3 *db){ { "avg", 1, 0, 0, sumStep, avgFinalize }, { "count", 0, 0, 0, countStep, countFinalize }, { "count", 1, 0, 0, countStep, countFinalize }, - { "group_concat", 1, 0, 0, groupConcatStep, groupConcatFinalize }, - { "group_concat", 2, 0, 0, groupConcatStep, groupConcatFinalize }, + { "group_concat", -1, 0, 0, groupConcatStep, groupConcatFinalize }, }; int i; for(i=0; i<sizeof(aFuncs)/sizeof(aFuncs[0]); i++){ void *pArg; u8 argType = aFuncs[i].argType; - pArg = (void*)(int)argType; + pArg = SQLITE_INT_TO_PTR(argType); sqlite3CreateFunc(db, aFuncs[i].zName, aFuncs[i].nArg, aFuncs[i].eTextRep, pArg, aFuncs[i].xFunc, 0, 0); if( aFuncs[i].needCollSeq ){ @@ -58522,7 +61664,7 @@ SQLITE_PRIVATE void sqlite3RegisterBuiltinFunctions(sqlite3 *db){ sqlite3AttachFunctions(db); #endif for(i=0; i<sizeof(aAggs)/sizeof(aAggs[0]); i++){ - void *pArg = (void*)(int)aAggs[i].argType; + void *pArg = SQLITE_INT_TO_PTR(aAggs[i].argType); sqlite3CreateFunc(db, aAggs[i].zName, aAggs[i].nArg, SQLITE_UTF8, pArg, 0, aAggs[i].xStep, aAggs[i].xFinalize); if( aAggs[i].needCollSeq ){ @@ -58664,8 +61806,9 @@ SQLITE_PRIVATE void sqlite3IndexAffinityStr(Vdbe *v, Index *pIdx){ int n; Table *pTab = pIdx->pTable; sqlite3 *db = sqlite3VdbeDb(v); - pIdx->zColAff = (char *)sqlite3DbMallocRaw(db, pIdx->nColumn+2); + pIdx->zColAff = (char *)sqlite3Malloc(pIdx->nColumn+2); if( !pIdx->zColAff ){ + db->mallocFailed = 1; return; } for(n=0; n<pIdx->nColumn; n++){ @@ -58705,8 +61848,9 @@ SQLITE_PRIVATE void sqlite3TableAffinityStr(Vdbe *v, Table *pTab){ int i; sqlite3 *db = sqlite3VdbeDb(v); - zColAff = (char *)sqlite3DbMallocRaw(db, pTab->nCol+1); + zColAff = (char *)sqlite3Malloc(pTab->nCol+1); if( !zColAff ){ + db->mallocFailed = 1; return; } @@ -58794,14 +61938,15 @@ static int autoIncBegin( sqlite3OpenTable(pParse, iCur, iDb, pDb->pSchema->pSeqTab, OP_OpenRead); addr = sqlite3VdbeCurrentAddr(v); sqlite3VdbeAddOp4(v, OP_String8, 0, memId-1, 0, pTab->zName, 0); - sqlite3VdbeAddOp2(v, OP_Rewind, iCur, addr+8); + sqlite3VdbeAddOp2(v, OP_Rewind, iCur, addr+9); sqlite3VdbeAddOp3(v, OP_Column, iCur, 0, memId); sqlite3VdbeAddOp3(v, OP_Ne, memId-1, addr+7, memId); sqlite3VdbeChangeP5(v, SQLITE_JUMPIFNULL); sqlite3VdbeAddOp2(v, OP_Rowid, iCur, memId+1); sqlite3VdbeAddOp3(v, OP_Column, iCur, 1, memId); - sqlite3VdbeAddOp2(v, OP_Goto, 0, addr+8); + sqlite3VdbeAddOp2(v, OP_Goto, 0, addr+9); sqlite3VdbeAddOp2(v, OP_Next, iCur, addr+2); + sqlite3VdbeAddOp2(v, OP_Integer, 0, memId); sqlite3VdbeAddOp2(v, OP_Close, iCur, 0); } return memId; @@ -58887,7 +62032,8 @@ static int xferOptimization( ** ** The code generated follows one of four templates. For a simple ** select with data coming from a VALUES clause, the code executes -** once straight down through. The template looks like this: +** once straight down through. Pseudo-code follows (we call this +** the "1st template"): ** ** open write cursor to <table> and its indices ** puts VALUES clause expressions onto the stack @@ -58905,7 +62051,7 @@ static int xferOptimization( ** schemas, including all the same indices, then a special optimization ** is invoked that copies raw records from <table2> over to <table1>. ** See the xferOptimization() function for the implementation of this -** template. This is the second template. +** template. This is the 2nd template. ** ** open a write cursor to <table> ** open read cursor on <table2> @@ -58918,45 +62064,58 @@ static int xferOptimization( ** close cursors ** end foreach ** -** The third template is for when the second template does not apply +** The 3rd template is for when the second template does not apply ** and the SELECT clause does not read from <table> at any time. ** The generated code follows this template: ** +** EOF <- 0 +** X <- A ** goto B ** A: setup for the SELECT ** loop over the rows in the SELECT -** gosub C +** load values into registers R..R+n +** yield X ** end loop ** cleanup after the SELECT -** goto D -** B: open write cursor to <table> and its indices +** EOF <- 1 +** yield X ** goto A -** C: insert the select result into <table> -** return +** B: open write cursor to <table> and its indices +** C: yield X +** if EOF goto D +** insert the select result into <table> from R..R+n +** goto C ** D: cleanup ** -** The fourth template is used if the insert statement takes its +** The 4th template is used if the insert statement takes its ** values from a SELECT but the data is being inserted into a table ** that is also read as part of the SELECT. In the third form, ** we have to use a intermediate table to store the results of ** the select. The template is like this: ** +** EOF <- 0 +** X <- A ** goto B ** A: setup for the SELECT ** loop over the tables in the SELECT -** gosub C +** load value into register R..R+n +** yield X ** end loop ** cleanup after the SELECT -** goto D -** C: insert the select result into the intermediate table -** return -** B: open a cursor to an intermediate table -** goto A -** D: open write cursor to <table> and its indices -** loop over the intermediate table +** EOF <- 1 +** yield X +** halt-error +** B: open temp table +** L: yield X +** if EOF goto M +** insert row from R..R+n into temp table +** goto L +** M: open write cursor to <table> and its indices +** rewind temp table +** C: loop over rows of intermediate table ** transfer values form intermediate table into <table> -** end the loop -** cleanup +** end loop +** D: cleanup */ SQLITE_PRIVATE void sqlite3Insert( Parse *pParse, /* Parser context */ @@ -58980,10 +62139,10 @@ SQLITE_PRIVATE void sqlite3Insert( int endOfLoop; /* Label for the end of the insertion loop */ int useTempTable = 0; /* Store SELECT results in intermediate table */ int srcTab = 0; /* Data comes from this temporary cursor if >=0 */ - int iCont=0,iBreak=0; /* Beginning and end of the loop over srcTab */ - int iSelectLoop = 0; /* Address of code that implements the SELECT */ - int iCleanup = 0; /* Address of the cleanup code */ - int iInsertBlock = 0; /* Address of the subroutine used to insert data */ + int addrInsTop = 0; /* Jump to label "D" */ + int addrCont = 0; /* Top of insert loop. Label "C" in templates 3 and 4 */ + int addrSelect = 0; /* Address of coroutine that implements the SELECT */ + SelectDest dest; /* Destination for SELECT on rhs of INSERT */ int newIdx = -1; /* Cursor for the NEW pseudo-table */ int iDb; /* Index of database holding TABLE */ Db *pDb; /* The database containing table being inserted into */ @@ -58997,6 +62156,7 @@ SQLITE_PRIVATE void sqlite3Insert( int regRowid; /* registers holding insert rowid */ int regData; /* register holding first column to insert */ int regRecord; /* Holds the assemblied row record */ + int regEof; /* Register recording end of SELECT data */ int *aRegIdx = 0; /* One register allocated to each index */ @@ -59078,6 +62238,8 @@ SQLITE_PRIVATE void sqlite3Insert( ** ** Then special optimizations can be applied that make the transfer ** very fast and which reduce fragmentation of indices. + ** + ** This is the 2nd template. */ if( pColumn==0 && xferOptimization(pParse, pTab, pSelect, onError, iDb) ){ assert( !triggers_exist ); @@ -59092,75 +62254,103 @@ SQLITE_PRIVATE void sqlite3Insert( regAutoinc = autoIncBegin(pParse, iDb, pTab); /* Figure out how many columns of data are supplied. If the data - ** is coming from a SELECT statement, then this step also generates - ** all the code to implement the SELECT statement and invoke a subroutine - ** to process each row of the result. (Template 2.) If the SELECT - ** statement uses the the table that is being inserted into, then the - ** subroutine is also coded here. That subroutine stores the SELECT - ** results in a temporary table. (Template 3.) + ** is coming from a SELECT statement, then generate a co-routine that + ** produces a single row of the SELECT on each invocation. The + ** co-routine is the common header to the 3rd and 4th templates. */ if( pSelect ){ /* Data is coming from a SELECT. Generate code to implement that SELECT + ** as a co-routine. The code is common to both the 3rd and 4th + ** templates: + ** + ** EOF <- 0 + ** X <- A + ** goto B + ** A: setup for the SELECT + ** loop over the tables in the SELECT + ** load value into register R..R+n + ** yield X + ** end loop + ** cleanup after the SELECT + ** EOF <- 1 + ** yield X + ** halt-error + ** + ** On each invocation of the co-routine, it puts a single row of the + ** SELECT result into registers dest.iMem...dest.iMem+dest.nMem-1. + ** (These output registers are allocated by sqlite3Select().) When + ** the SELECT completes, it sets the EOF flag stored in regEof. */ - SelectDest dest; - int rc, iInitCode; + int rc, j1; - iInitCode = sqlite3VdbeAddOp2(v, OP_Goto, 0, 0); - iSelectLoop = sqlite3VdbeCurrentAddr(v); - iInsertBlock = sqlite3VdbeMakeLabel(v); - sqlite3SelectDestInit(&dest, SRT_Subroutine, iInsertBlock); + regEof = ++pParse->nMem; + sqlite3VdbeAddOp2(v, OP_Integer, 0, regEof); /* EOF <- 0 */ + VdbeComment((v, "SELECT eof flag")); + sqlite3SelectDestInit(&dest, SRT_Coroutine, ++pParse->nMem); + addrSelect = sqlite3VdbeCurrentAddr(v)+2; + sqlite3VdbeAddOp2(v, OP_Integer, addrSelect-1, dest.iParm); + j1 = sqlite3VdbeAddOp2(v, OP_Goto, 0, 0); + VdbeComment((v, "Jump over SELECT coroutine")); /* Resolve the expressions in the SELECT statement and execute it. */ - rc = sqlite3Select(pParse, pSelect, &dest, 0, 0, 0, 0); + rc = sqlite3Select(pParse, pSelect, &dest, 0, 0, 0); if( rc || pParse->nErr || db->mallocFailed ){ goto insert_cleanup; } + sqlite3VdbeAddOp2(v, OP_Integer, 1, regEof); /* EOF <- 1 */ + sqlite3VdbeAddOp1(v, OP_Yield, dest.iParm); /* yield X */ + sqlite3VdbeAddOp2(v, OP_Halt, SQLITE_INTERNAL, OE_Abort); + VdbeComment((v, "End of SELECT coroutine")); + sqlite3VdbeJumpHere(v, j1); /* label B: */ regFromSelect = dest.iMem; - iCleanup = sqlite3VdbeMakeLabel(v); - sqlite3VdbeAddOp2(v, OP_Goto, 0, iCleanup); assert( pSelect->pEList ); nColumn = pSelect->pEList->nExpr; + assert( dest.nMem==nColumn ); /* Set useTempTable to TRUE if the result of the SELECT statement - ** should be written into a temporary table. Set to FALSE if each - ** row of the SELECT can be written directly into the result table. + ** should be written into a temporary table (template 4). Set to + ** FALSE if each* row of the SELECT can be written directly into + ** the destination table (template 3). ** ** A temp table must be used if the table being updated is also one ** of the tables being read by the SELECT statement. Also use a ** temp table in the case of row triggers. */ - if( triggers_exist || readsTable(v, iSelectLoop, iDb, pTab) ){ + if( triggers_exist || readsTable(v, addrSelect, iDb, pTab) ){ useTempTable = 1; } if( useTempTable ){ - /* Generate the subroutine that SELECT calls to process each row of - ** the result. Store the result in a temporary table + /* Invoke the coroutine to extract information from the SELECT + ** and add it to a transient table srcTab. The code generated + ** here is from the 4th template: + ** + ** B: open temp table + ** L: yield X + ** if EOF goto M + ** insert row from R..R+n into temp table + ** goto L + ** M: ... */ - int regRec, regRowid; + int regRec; /* Register to hold packed record */ + int regRowid; /* Register to hold temp table ROWID */ + int addrTop; /* Label "L" */ + int addrIf; /* Address of jump to M */ srcTab = pParse->nTab++; regRec = sqlite3GetTempReg(pParse); regRowid = sqlite3GetTempReg(pParse); - sqlite3VdbeResolveLabel(v, iInsertBlock); + sqlite3VdbeAddOp2(v, OP_OpenEphemeral, srcTab, nColumn); + addrTop = sqlite3VdbeAddOp1(v, OP_Yield, dest.iParm); + addrIf = sqlite3VdbeAddOp1(v, OP_If, regEof); sqlite3VdbeAddOp3(v, OP_MakeRecord, regFromSelect, nColumn, regRec); sqlite3VdbeAddOp2(v, OP_NewRowid, srcTab, regRowid); sqlite3VdbeAddOp3(v, OP_Insert, srcTab, regRec, regRowid); - sqlite3VdbeAddOp2(v, OP_Return, 0, 0); + sqlite3VdbeAddOp2(v, OP_Goto, 0, addrTop); + sqlite3VdbeJumpHere(v, addrIf); sqlite3ReleaseTempReg(pParse, regRec); sqlite3ReleaseTempReg(pParse, regRowid); - - /* The following code runs first because the GOTO at the very top - ** of the program jumps to it. Create the temporary table, then jump - ** back up and execute the SELECT code above. - */ - sqlite3VdbeJumpHere(v, iInitCode); - sqlite3VdbeAddOp2(v, OP_OpenEphemeral, srcTab, nColumn); - sqlite3VdbeAddOp2(v, OP_Goto, 0, iSelectLoop); - sqlite3VdbeResolveLabel(v, iCleanup); - }else{ - sqlite3VdbeJumpHere(v, iInitCode); } }else{ /* This is the case if the data for the INSERT is coming from a VALUES @@ -59274,18 +62464,31 @@ SQLITE_PRIVATE void sqlite3Insert( } } - /* If the data source is a temporary table, then we have to create - ** a loop because there might be multiple rows of data. If the data - ** source is a subroutine call from the SELECT statement, then we need - ** to launch the SELECT statement processing. - */ + /* This is the top of the main insertion loop */ if( useTempTable ){ - iBreak = sqlite3VdbeMakeLabel(v); - sqlite3VdbeAddOp2(v, OP_Rewind, srcTab, iBreak); - iCont = sqlite3VdbeCurrentAddr(v); + /* This block codes the top of loop only. The complete loop is the + ** following pseudocode (template 4): + ** + ** rewind temp table + ** C: loop over rows of intermediate table + ** transfer values form intermediate table into <table> + ** end loop + ** D: ... + */ + addrInsTop = sqlite3VdbeAddOp1(v, OP_Rewind, srcTab); + addrCont = sqlite3VdbeCurrentAddr(v); }else if( pSelect ){ - sqlite3VdbeAddOp2(v, OP_Goto, 0, iSelectLoop); - sqlite3VdbeResolveLabel(v, iInsertBlock); + /* This block codes the top of loop only. The complete loop is the + ** following pseudocode (template 3): + ** + ** C: yield X + ** if EOF goto D + ** insert the select result into <table> from R..R+n + ** goto C + ** D: ... + */ + addrCont = sqlite3VdbeAddOp1(v, OP_Yield, dest.iParm); + addrInsTop = sqlite3VdbeAddOp1(v, OP_If, regEof); } /* Allocate registers for holding the rowid of the new row, @@ -59396,7 +62599,7 @@ SQLITE_PRIVATE void sqlite3Insert( VdbeOp *pOp; sqlite3ExprCode(pParse, pList->a[keyColumn].pExpr, regRowid); pOp = sqlite3VdbeGetOp(v, sqlite3VdbeCurrentAddr(v) - 1); - if( pOp && pOp->opcode==OP_Null ){ + if( pOp && pOp->opcode==OP_Null && !IsVirtual(pTab) ){ appendFlag = 1; pOp->opcode = OP_NewRowid; pOp->p1 = baseCur; @@ -59409,9 +62612,14 @@ SQLITE_PRIVATE void sqlite3Insert( */ if( !appendFlag ){ int j1; - j1 = sqlite3VdbeAddOp1(v, OP_NotNull, regRowid); - sqlite3VdbeAddOp3(v, OP_NewRowid, baseCur, regRowid, regAutoinc); - sqlite3VdbeJumpHere(v, j1); + if( !IsVirtual(pTab) ){ + j1 = sqlite3VdbeAddOp1(v, OP_NotNull, regRowid); + sqlite3VdbeAddOp3(v, OP_NewRowid, baseCur, regRowid, regAutoinc); + sqlite3VdbeJumpHere(v, j1); + }else{ + j1 = sqlite3VdbeCurrentAddr(v); + sqlite3VdbeAddOp2(v, OP_IsNull, regRowid, j1+2); + } sqlite3VdbeAddOp1(v, OP_MustBeInt, regRowid); } }else if( IsVirtual(pTab) ){ @@ -59510,23 +62718,24 @@ SQLITE_PRIVATE void sqlite3Insert( } } - /* The bottom of the loop, if the data source is a SELECT statement + /* The bottom of the main insertion loop, if the data source + ** is a SELECT statement. */ sqlite3VdbeResolveLabel(v, endOfLoop); if( useTempTable ){ - sqlite3VdbeAddOp2(v, OP_Next, srcTab, iCont); - sqlite3VdbeResolveLabel(v, iBreak); - sqlite3VdbeAddOp2(v, OP_Close, srcTab, 0); + sqlite3VdbeAddOp2(v, OP_Next, srcTab, addrCont); + sqlite3VdbeJumpHere(v, addrInsTop); + sqlite3VdbeAddOp1(v, OP_Close, srcTab); }else if( pSelect ){ - sqlite3VdbeAddOp2(v, OP_Return, 0, 0); - sqlite3VdbeResolveLabel(v, iCleanup); + sqlite3VdbeAddOp2(v, OP_Goto, 0, addrCont); + sqlite3VdbeJumpHere(v, addrInsTop); } if( !IsVirtual(pTab) && !isView ){ /* Close all tables opened */ - sqlite3VdbeAddOp2(v, OP_Close, baseCur, 0); + sqlite3VdbeAddOp1(v, OP_Close, baseCur); for(idx=1, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, idx++){ - sqlite3VdbeAddOp2(v, OP_Close, idx+baseCur, 0); + sqlite3VdbeAddOp1(v, OP_Close, idx+baseCur); } } @@ -59548,11 +62757,11 @@ SQLITE_PRIVATE void sqlite3Insert( } insert_cleanup: - sqlite3SrcListDelete(pTabList); - sqlite3ExprListDelete(pList); - sqlite3SelectDelete(pSelect); - sqlite3IdListDelete(pColumn); - sqlite3_free(aRegIdx); + sqlite3SrcListDelete(db, pTabList); + sqlite3ExprListDelete(db, pList); + sqlite3SelectDelete(db, pSelect); + sqlite3IdListDelete(db, pColumn); + sqlite3DbFree(db, aRegIdx); } /* @@ -59684,10 +62893,10 @@ SQLITE_PRIVATE void sqlite3GenerateConstraintChecks( case OE_Rollback: case OE_Abort: case OE_Fail: { - char *zMsg = 0; + char *zMsg; sqlite3VdbeAddOp2(v, OP_Halt, SQLITE_CONSTRAINT, onError); - sqlite3SetString(&zMsg, pTab->zName, ".", pTab->aCol[i].zName, - " may not be NULL", (char*)0); + zMsg = sqlite3MPrintf(pParse->db, "%s.%s may not be NULL", + pTab->zName, pTab->aCol[i].zName); sqlite3VdbeChangeP4(v, -1, zMsg, P4_DYNAMIC); break; } @@ -59812,7 +63021,7 @@ SQLITE_PRIVATE void sqlite3GenerateConstraintChecks( regR = sqlite3GetTempReg(pParse); sqlite3VdbeAddOp2(v, OP_SCopy, regRowid-hasTwoRowids, regR); j3 = sqlite3VdbeAddOp4(v, OP_IsUnique, baseCur+iCur+1, 0, - regR, (char*)aRegIdx[iCur], + regR, SQLITE_INT_TO_PTR(aRegIdx[iCur]), P4_INT32); /* Generate code that executes if the new index entry is not unique */ @@ -60336,9 +63545,10 @@ SQLITE_API int sqlite3_exec( int nRetry = 0; int nCallback; - if( zSql==0 ) return SQLITE_OK; + if( zSql==0 ) zSql = ""; sqlite3_mutex_enter(db->mutex); + sqlite3Error(db, SQLITE_OK, 0); while( (rc==SQLITE_OK || (rc==SQLITE_SCHEMA && (++nRetry)<2)) && zSql[0] ){ int nCol; char **azVals = 0; @@ -60374,10 +63584,9 @@ SQLITE_API int sqlite3_exec( } for(i=0; i<nCol; i++){ azCols[i] = (char *)sqlite3_column_name(pStmt, i); - if( !azCols[i] ){ - db->mallocFailed = 1; - goto exec_out; - } + /* sqlite3VdbeSetColName() installs column names as UTF8 + ** strings so there is no way for sqlite3_column_name() to fail. */ + assert( azCols[i]!=0 ); } nCallback++; } @@ -60393,6 +63602,9 @@ SQLITE_API int sqlite3_exec( } if( xCallback(pArg, nCol, azVals, azCols) ){ rc = SQLITE_ABORT; + sqlite3_finalize(pStmt); + pStmt = 0; + sqlite3Error(db, SQLITE_ABORT, 0); goto exec_out; } } @@ -60409,18 +63621,18 @@ SQLITE_API int sqlite3_exec( } } - sqlite3_free(azCols); + sqlite3DbFree(db, azCols); azCols = 0; } exec_out: if( pStmt ) sqlite3_finalize(pStmt); - if( azCols ) sqlite3_free(azCols); + sqlite3DbFree(db, azCols); rc = sqlite3ApiExit(db, rc); if( rc!=SQLITE_OK && rc==sqlite3_errcode(db) && pzErrMsg ){ int nErrMsg = 1 + strlen(sqlite3_errmsg(db)); - *pzErrMsg = sqlite3_malloc(nErrMsg); + *pzErrMsg = sqlite3Malloc(nErrMsg); if( *pzErrMsg ){ memcpy(*pzErrMsg, sqlite3_errmsg(db), nErrMsg); } @@ -60448,6 +63660,8 @@ exec_out: ************************************************************************* ** This file contains code used to dynamically load extensions into ** the SQLite library. +** +** $Id$ */ #ifndef SQLITE_CORE @@ -60534,7 +63748,7 @@ struct sqlite3_api_routines { int (*complete)(const char*sql); int (*complete16)(const void*sql); int (*create_collation)(sqlite3*,const char*,int,void*,int(*)(void*,int,const void*,int,const void*)); - int (*create_collation16)(sqlite3*,const char*,int,void*,int(*)(void*,int,const void*,int,const void*)); + int (*create_collation16)(sqlite3*,const void*,int,void*,int(*)(void*,int,const void*,int,const void*)); int (*create_function)(sqlite3*,const char*,int,int,void*,void (*xFunc)(sqlite3_context*,int,sqlite3_value**),void (*xStep)(sqlite3_context*,int,sqlite3_value**),void (*xFinal)(sqlite3_context*)); int (*create_function16)(sqlite3*,const void*,int,int,void*,void (*xFunc)(sqlite3_context*,int,sqlite3_value**),void (*xStep)(sqlite3_context*,int,sqlite3_value**),void (*xFinal)(sqlite3_context*)); int (*create_module)(sqlite3*,const char*,const sqlite3_module*,void*); @@ -60644,6 +63858,11 @@ struct sqlite3_api_routines { int (*test_control)(int, ...); void (*randomness)(int,void*); sqlite3 *(*context_db_handle)(sqlite3_context*); + int (*extended_result_codes)(sqlite3*,int); + int (*limit)(sqlite3*,int,int); + sqlite3_stmt *(*next_stmt)(sqlite3*,sqlite3_stmt*); + const char *(*sql)(sqlite3_stmt*); + int (*status)(int,int*,int*,int); }; /* @@ -60810,9 +64029,14 @@ struct sqlite3_api_routines { #define sqlite3_test_control sqlite3_api->test_control #define sqlite3_randomness sqlite3_api->randomness #define sqlite3_context_db_handle sqlite3_api->context_db_handle +#define sqlite3_extended_result_codes sqlite3_api->extended_result_codes +#define sqlite3_limit sqlite3_api->limit +#define sqlite3_next_stmt sqlite3_api->next_stmt +#define sqlite3_sql sqlite3_api->sql +#define sqlite3_status sqlite3_api->status #endif /* SQLITE_CORE */ -#define SQLITE_EXTENSION_INIT1 const sqlite3_api_routines *sqlite3_api; +#define SQLITE_EXTENSION_INIT1 const sqlite3_api_routines *sqlite3_api = 0; #define SQLITE_EXTENSION_INIT2(v) sqlite3_api = v; #endif /* _SQLITE3EXT_H_ */ @@ -61102,6 +64326,15 @@ static const sqlite3_api_routines sqlite3Apis = { sqlite3_test_control, sqlite3_randomness, sqlite3_context_db_handle, + + /* + ** Added for 3.6.0 + */ + sqlite3_extended_result_codes, + sqlite3_limit, + sqlite3_next_stmt, + sqlite3_sql, + sqlite3_status, }; /* @@ -61114,7 +64347,7 @@ static const sqlite3_api_routines sqlite3Apis = { ** ** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with ** error message text. The calling function should free this memory -** by calling sqlite3_free(). +** by calling sqlite3DbFree(db, ). */ static int sqlite3LoadExtension( sqlite3 *db, /* Load the extension into this database connection */ @@ -61153,7 +64386,7 @@ static int sqlite3LoadExtension( sqlite3_snprintf(sizeof(zErr)-1, zErr, "unable to open shared library [%s]", zFile); sqlite3OsDlError(pVfs, sizeof(zErr)-1, zErr); - *pzErrMsg = sqlite3DbStrDup(db, zErr); + *pzErrMsg = sqlite3DbStrDup(0, zErr); } return SQLITE_ERROR; } @@ -61166,7 +64399,7 @@ static int sqlite3LoadExtension( sqlite3_snprintf(sizeof(zErr)-1, zErr, "no entry point [%s] in shared library [%s]", zProc,zFile); sqlite3OsDlError(pVfs, sizeof(zErr)-1, zErr); - *pzErrMsg = sqlite3DbStrDup(db, zErr); + *pzErrMsg = sqlite3DbStrDup(0, zErr); sqlite3OsDlClose(pVfs, handle); } return SQLITE_ERROR; @@ -61180,18 +64413,17 @@ static int sqlite3LoadExtension( } /* Append the new shared library handle to the db->aExtension array. */ - db->nExtension++; - aHandle = sqlite3DbMallocZero(db, sizeof(handle)*db->nExtension); + aHandle = sqlite3DbMallocZero(db, sizeof(handle)*(db->nExtension+1)); if( aHandle==0 ){ return SQLITE_NOMEM; } if( db->nExtension>0 ){ - memcpy(aHandle, db->aExtension, sizeof(handle)*(db->nExtension-1)); + memcpy(aHandle, db->aExtension, sizeof(handle)*db->nExtension); } - sqlite3_free(db->aExtension); + sqlite3DbFree(db, db->aExtension); db->aExtension = aHandle; - db->aExtension[db->nExtension-1] = handle; + db->aExtension[db->nExtension++] = handle; return SQLITE_OK; } SQLITE_API int sqlite3_load_extension( @@ -61217,7 +64449,7 @@ SQLITE_PRIVATE void sqlite3CloseExtensions(sqlite3 *db){ for(i=0; i<db->nExtension; i++){ sqlite3OsDlClose(db->pVfs, db->aExtension[i]); } - sqlite3_free(db->aExtension); + sqlite3DbFree(db, db->aExtension); } /* @@ -61266,44 +64498,57 @@ static struct { ** loaded by every new database connection. */ SQLITE_API int sqlite3_auto_extension(void *xInit){ - int i; int rc = SQLITE_OK; +#ifndef SQLITE_OMIT_AUTOINIT + rc = sqlite3_initialize(); + if( rc ){ + return rc; + }else +#endif + { + int i; #ifndef SQLITE_MUTEX_NOOP - sqlite3_mutex *mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MASTER); + sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER); #endif - sqlite3_mutex_enter(mutex); - for(i=0; i<autoext.nExt; i++){ - if( autoext.aExt[i]==xInit ) break; - } - if( i==autoext.nExt ){ - int nByte = (autoext.nExt+1)*sizeof(autoext.aExt[0]); - void **aNew; - aNew = sqlite3_realloc(autoext.aExt, nByte); - if( aNew==0 ){ - rc = SQLITE_NOMEM; - }else{ - autoext.aExt = aNew; - autoext.aExt[autoext.nExt] = xInit; - autoext.nExt++; + sqlite3_mutex_enter(mutex); + for(i=0; i<autoext.nExt; i++){ + if( autoext.aExt[i]==xInit ) break; + } + if( i==autoext.nExt ){ + int nByte = (autoext.nExt+1)*sizeof(autoext.aExt[0]); + void **aNew; + aNew = sqlite3_realloc(autoext.aExt, nByte); + if( aNew==0 ){ + rc = SQLITE_NOMEM; + }else{ + autoext.aExt = aNew; + autoext.aExt[autoext.nExt] = xInit; + autoext.nExt++; + } } + sqlite3_mutex_leave(mutex); + assert( (rc&0xff)==rc ); + return rc; } - sqlite3_mutex_leave(mutex); - assert( (rc&0xff)==rc ); - return rc; } /* ** Reset the automatic extension loading mechanism. */ SQLITE_API void sqlite3_reset_auto_extension(void){ +#ifndef SQLITE_OMIT_AUTOINIT + if( sqlite3_initialize()==SQLITE_OK ) +#endif + { #ifndef SQLITE_MUTEX_NOOP - sqlite3_mutex *mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MASTER); + sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER); #endif - sqlite3_mutex_enter(mutex); - sqlite3_free(autoext.aExt); - autoext.aExt = 0; - autoext.nExt = 0; - sqlite3_mutex_leave(mutex); + sqlite3_mutex_enter(mutex); + sqlite3_free(autoext.aExt); + autoext.aExt = 0; + autoext.nExt = 0; + sqlite3_mutex_leave(mutex); + } } /* @@ -61322,7 +64567,7 @@ SQLITE_PRIVATE int sqlite3AutoLoadExtensions(sqlite3 *db){ for(i=0; go; i++){ char *zErrmsg = 0; #ifndef SQLITE_MUTEX_NOOP - sqlite3_mutex *mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_MASTER); + sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER); #endif sqlite3_mutex_enter(mutex); if( i>=autoext.nExt ){ @@ -61457,7 +64702,7 @@ static int getTempStore(const char *z){ static int invalidateTempStorage(Parse *pParse){ sqlite3 *db = pParse->db; if( db->aDb[1].pBt!=0 ){ - if( !db->autoCommit ){ + if( !db->autoCommit || sqlite3BtreeIsInReadTrans(db->aDb[1].pBt) ){ sqlite3ErrorMsg(pParse, "temporary storage cannot be changed " "from within a transaction"); return SQLITE_ERROR; @@ -61473,7 +64718,7 @@ static int invalidateTempStorage(Parse *pParse){ #ifndef SQLITE_OMIT_PAGER_PRAGMAS /* ** If the TEMP database is open, close it and mark the database schema -** as needing reloading. This must be done when using the TEMP_STORE +** as needing reloading. This must be done when using the SQLITE_TEMP_STORE ** or DEFAULT_TEMP_STORE pragmas. */ static int changeTempStorage(Parse *pParse, const char *zStorageType){ @@ -61725,6 +64970,24 @@ SQLITE_PRIVATE void sqlite3Pragma( }else /* + ** PRAGMA [database.]page_count + ** + ** Return the number of pages in the specified database. + */ + if( sqlite3StrICmp(zLeft,"page_count")==0 ){ + Vdbe *v; + int iReg; + v = sqlite3GetVdbe(pParse); + if( !v || sqlite3ReadSchema(pParse) ) goto pragma_out; + sqlite3CodeVerifySchema(pParse, iDb); + iReg = ++pParse->nMem; + sqlite3VdbeAddOp2(v, OP_Pagecount, iDb, iReg); + sqlite3VdbeAddOp2(v, OP_ResultRow, iReg, 1); + sqlite3VdbeSetNumCols(v, 1); + sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "page_count", P4_STATIC); + }else + + /* ** PRAGMA [database.]locking_mode ** PRAGMA [database.]locking_mode = (normal|exclusive) */ @@ -61789,7 +65052,7 @@ SQLITE_PRIVATE void sqlite3Pragma( } } if( pId2->n==0 && eMode==PAGER_JOURNALMODE_QUERY ){ - /* Simple "PRAGMA persistent_journal;" statement. This is a query for + /* Simple "PRAGMA journal_mode;" statement. This is a query for ** the current default journal mode (which may be different to ** the journal-mode of the main database). */ @@ -61827,6 +65090,27 @@ SQLITE_PRIVATE void sqlite3Pragma( azModeName[eMode], P4_STATIC); sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 1); }else + + /* + ** PRAGMA [database.]journal_size_limit + ** PRAGMA [database.]journal_size_limit=N + ** + ** Get or set the (boolean) value of the database 'auto-vacuum' parameter. + */ + if( sqlite3StrICmp(zLeft,"journal_size_limit")==0 ){ + Pager *pPager = sqlite3BtreePager(pDb->pBt); + i64 iLimit = -2; + if( zRight ){ + int iLimit32 = atoi(zRight); + if( iLimit32<-1 ){ + iLimit32 = -1; + } + iLimit = iLimit32; + } + iLimit = sqlite3PagerJournalSizeLimit(pPager, iLimit); + returnSingleInt(pParse, "journal_size_limit", (int)iLimit); + }else + #endif /* SQLITE_OMIT_PAGER_PRAGMAS */ /* @@ -61973,22 +65257,23 @@ SQLITE_PRIVATE void sqlite3Pragma( sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 1); } }else{ - if( zRight[0] - && sqlite3OsAccess(db->pVfs, zRight, SQLITE_ACCESS_READWRITE)==0 - ){ - sqlite3ErrorMsg(pParse, "not a writable directory"); - goto pragma_out; + if( zRight[0] ){ + int res; + sqlite3OsAccess(db->pVfs, zRight, SQLITE_ACCESS_READWRITE, &res); + if( res==0 ){ + sqlite3ErrorMsg(pParse, "not a writable directory"); + goto pragma_out; + } } - if( TEMP_STORE==0 - || (TEMP_STORE==1 && db->temp_store<=1) - || (TEMP_STORE==2 && db->temp_store==1) + if( SQLITE_TEMP_STORE==0 + || (SQLITE_TEMP_STORE==1 && db->temp_store<=1) + || (SQLITE_TEMP_STORE==2 && db->temp_store==1) ){ invalidateTempStorage(pParse); } sqlite3_free(sqlite3_temp_directory); if( zRight[0] ){ - sqlite3_temp_directory = zRight; - zRight = 0; + sqlite3_temp_directory = sqlite3DbStrDup(0, zRight); }else{ sqlite3_temp_directory = 0; } @@ -62309,7 +65594,7 @@ SQLITE_PRIVATE void sqlite3Pragma( sqlite3VdbeAddOp4(v, OP_String8, 0, 3, 0, sqlite3MPrintf(db, "*** in database %s ***\n", db->aDb[i].zName), P4_DYNAMIC); - sqlite3VdbeAddOp2(v, OP_Move, 2, 4); + sqlite3VdbeAddOp3(v, OP_Move, 2, 4, 1); sqlite3VdbeAddOp3(v, OP_Concat, 4, 3, 2); sqlite3VdbeAddOp2(v, OP_ResultRow, 2, 1); sqlite3VdbeJumpHere(v, addr); @@ -62628,8 +65913,8 @@ SQLITE_PRIVATE void sqlite3Pragma( #endif } pragma_out: - sqlite3_free(zLeft); - sqlite3_free(zRight); + sqlite3DbFree(db, zLeft); + sqlite3DbFree(db, zRight); } #endif /* SQLITE_OMIT_PRAGMA || SQLITE_OMIT_PARSER */ @@ -62665,8 +65950,12 @@ static void corruptSchema( ){ if( !pData->db->mallocFailed ){ if( zObj==0 ) zObj = "?"; - sqlite3SetString(pData->pzErrMsg, "malformed database schema (", zObj, ")", - zExtra!=0 && zExtra[0]!=0 ? " - " : (char*)0, zExtra, (char*)0); + sqlite3SetString(pData->pzErrMsg, pData->db, + "malformed database schema (%s)", zObj); + if( zExtra && zExtra[0] ){ + *pData->pzErrMsg = sqlite3MAppendf(pData->db, *pData->pzErrMsg, "%s - %s", + *pData->pzErrMsg, zExtra); + } } pData->rc = SQLITE_CORRUPT; } @@ -62711,11 +66000,15 @@ SQLITE_PRIVATE int sqlite3InitCallback(void *pInit, int argc, char **argv, char */ char *zErr; int rc; + u8 lookasideEnabled; assert( db->init.busy ); db->init.iDb = iDb; db->init.newTnum = atoi(argv[1]); + lookasideEnabled = db->lookaside.bEnabled; + db->lookaside.bEnabled = 0; rc = sqlite3_exec(db, argv[2], 0, 0, &zErr); db->init.iDb = 0; + db->lookaside.bEnabled = lookasideEnabled; assert( rc!=SQLITE_OK || zErr==0 ); if( SQLITE_OK!=rc ){ pData->rc = rc; @@ -62724,7 +66017,7 @@ SQLITE_PRIVATE int sqlite3InitCallback(void *pInit, int argc, char **argv, char }else if( rc!=SQLITE_INTERRUPT ){ corruptSchema(pData, argv[0], zErr); } - sqlite3_free(zErr); + sqlite3DbFree(db, zErr); return 1; } }else if( argv[0]==0 ){ @@ -62851,8 +66144,8 @@ static int sqlite3InitOne(sqlite3 *db, int iDb, char **pzErrMsg){ sqlite3BtreeEnter(pDb->pBt); rc = sqlite3BtreeCursor(pDb->pBt, MASTER_ROOT, 0, 0, curMain); if( rc!=SQLITE_OK && rc!=SQLITE_EMPTY ){ - sqlite3SetString(pzErrMsg, sqlite3ErrStr(rc), (char*)0); - goto leave_error_out; + sqlite3SetString(pzErrMsg, db, "%s", sqlite3ErrStr(rc)); + goto initone_error_out; } /* Get the database meta information. @@ -62874,12 +66167,12 @@ static int sqlite3InitOne(sqlite3 *db, int iDb, char **pzErrMsg){ */ if( rc==SQLITE_OK ){ int i; - for(i=0; rc==SQLITE_OK && i<sizeof(meta)/sizeof(meta[0]); i++){ + for(i=0; i<sizeof(meta)/sizeof(meta[0]); i++){ rc = sqlite3BtreeGetMeta(pDb->pBt, i+1, (u32 *)&meta[i]); - } - if( rc ){ - sqlite3SetString(pzErrMsg, sqlite3ErrStr(rc), (char*)0); - goto leave_error_out; + if( rc ){ + sqlite3SetString(pzErrMsg, db, "%s", sqlite3ErrStr(rc)); + goto initone_error_out; + } } }else{ memset(meta, 0, sizeof(meta)); @@ -62899,10 +66192,10 @@ static int sqlite3InitOne(sqlite3 *db, int iDb, char **pzErrMsg){ }else{ /* If opening an attached database, the encoding much match ENC(db) */ if( meta[4]!=ENC(db) ){ - sqlite3SetString(pzErrMsg, "attached databases must use the same" - " text encoding as main database", (char*)0); + sqlite3SetString(pzErrMsg, db, "attached databases must use the same" + " text encoding as main database"); rc = SQLITE_ERROR; - goto leave_error_out; + goto initone_error_out; } } }else{ @@ -62910,11 +66203,13 @@ static int sqlite3InitOne(sqlite3 *db, int iDb, char **pzErrMsg){ } pDb->pSchema->enc = ENC(db); - size = meta[2]; - if( size==0 ){ size = SQLITE_DEFAULT_CACHE_SIZE; } - if( size<0 ) size = -size; - pDb->pSchema->cache_size = size; - sqlite3BtreeSetCacheSize(pDb->pBt, pDb->pSchema->cache_size); + if( pDb->pSchema->cache_size==0 ){ + size = meta[2]; + if( size==0 ){ size = SQLITE_DEFAULT_CACHE_SIZE; } + if( size<0 ) size = -size; + pDb->pSchema->cache_size = size; + sqlite3BtreeSetCacheSize(pDb->pBt, pDb->pSchema->cache_size); + } /* ** file_format==1 Version 3.0.0. @@ -62927,9 +66222,9 @@ static int sqlite3InitOne(sqlite3 *db, int iDb, char **pzErrMsg){ pDb->pSchema->file_format = 1; } if( pDb->pSchema->file_format>SQLITE_MAX_FILE_FORMAT ){ - sqlite3SetString(pzErrMsg, "unsupported file format", (char*)0); + sqlite3SetString(pzErrMsg, db, "unsupported file format"); rc = SQLITE_ERROR; - goto leave_error_out; + goto initone_error_out; } /* Ticket #2804: When we open a database in the newer file format, @@ -62966,7 +66261,7 @@ static int sqlite3InitOne(sqlite3 *db, int iDb, char **pzErrMsg){ #endif if( rc==SQLITE_ABORT ) rc = initData.rc; (void)sqlite3SafetyOn(db); - sqlite3_free(zSql); + sqlite3DbFree(db, zSql); #ifndef SQLITE_OMIT_ANALYZE if( rc==SQLITE_OK ){ sqlite3AnalysisLoad(db, iDb); @@ -62974,7 +66269,6 @@ static int sqlite3InitOne(sqlite3 *db, int iDb, char **pzErrMsg){ #endif } if( db->mallocFailed ){ - /* sqlite3SetString(pzErrMsg, "out of memory", (char*)0); */ rc = SQLITE_NOMEM; sqlite3ResetInternalSchema(db, 0); } @@ -62995,7 +66289,7 @@ static int sqlite3InitOne(sqlite3 *db, int iDb, char **pzErrMsg){ ** curMain and calling sqlite3BtreeEnter(). For an error that occurs ** before that point, jump to error_out. */ -leave_error_out: +initone_error_out: sqlite3BtreeCloseCursor(curMain); sqlite3_free(curMain); sqlite3BtreeLeave(pDb->pBt); @@ -63084,7 +66378,7 @@ static int schemaIsValid(sqlite3 *db){ int cookie; int allOk = 1; - curTemp = (BtCursor *)sqlite3_malloc(sqlite3BtreeCursorSize()); + curTemp = (BtCursor *)sqlite3Malloc(sqlite3BtreeCursorSize()); if( curTemp ){ assert( sqlite3_mutex_held(db->mutex) ); for(iDb=0; allOk && iDb<db->nDb; iDb++){ @@ -63181,25 +66475,25 @@ static int sqlite3Prepare( const char *zDb = db->aDb[i].zName; sqlite3Error(db, SQLITE_LOCKED, "database schema is locked: %s", zDb); (void)sqlite3SafetyOff(db); - return SQLITE_LOCKED; + return sqlite3ApiExit(db, SQLITE_LOCKED); } } } memset(&sParse, 0, sizeof(sParse)); sParse.db = db; - if( nBytes>=0 && zSql[nBytes-1]!=0 ){ + if( nBytes>=0 && (nBytes==0 || zSql[nBytes-1]!=0) ){ char *zSqlCopy; int mxLen = db->aLimit[SQLITE_LIMIT_SQL_LENGTH]; if( nBytes>mxLen ){ sqlite3Error(db, SQLITE_TOOBIG, "statement too long"); (void)sqlite3SafetyOff(db); - return SQLITE_TOOBIG; + return sqlite3ApiExit(db, SQLITE_TOOBIG); } zSqlCopy = sqlite3DbStrNDup(db, zSql, nBytes); if( zSqlCopy ){ sqlite3RunParser(&sParse, zSqlCopy, &zErrMsg); - sqlite3_free(zSqlCopy); + sqlite3DbFree(db, zSqlCopy); sParse.zTail = &zSql[sParse.zTail-zSqlCopy]; }else{ sParse.zTail = &zSql[nBytes]; @@ -63263,7 +66557,7 @@ static int sqlite3Prepare( if( zErrMsg ){ sqlite3Error(db, rc, "%s", zErrMsg); - sqlite3_free(zErrMsg); + sqlite3DbFree(db, zErrMsg); }else{ sqlite3Error(db, rc, 0); } @@ -63398,7 +66692,7 @@ static int sqlite3Prepare16( int chars_parsed = sqlite3Utf8CharLen(zSql8, zTail8-zSql8); *pzTail = (u8 *)zSql + sqlite3Utf16ByteLen(zSql, chars_parsed); } - sqlite3_free(zSql8); + sqlite3DbFree(db, zSql8); rc = sqlite3ApiExit(db, rc); sqlite3_mutex_leave(db->mutex); return rc; @@ -63463,16 +66757,16 @@ SQLITE_API int sqlite3_prepare16_v2( ** Delete all the content of a Select structure but do not deallocate ** the select structure itself. */ -static void clearSelect(Select *p){ - sqlite3ExprListDelete(p->pEList); - sqlite3SrcListDelete(p->pSrc); - sqlite3ExprDelete(p->pWhere); - sqlite3ExprListDelete(p->pGroupBy); - sqlite3ExprDelete(p->pHaving); - sqlite3ExprListDelete(p->pOrderBy); - sqlite3SelectDelete(p->pPrior); - sqlite3ExprDelete(p->pLimit); - sqlite3ExprDelete(p->pOffset); +static void clearSelect(sqlite3 *db, Select *p){ + sqlite3ExprListDelete(db, p->pEList); + sqlite3SrcListDelete(db, p->pSrc); + sqlite3ExprDelete(db, p->pWhere); + sqlite3ExprListDelete(db, p->pGroupBy); + sqlite3ExprDelete(db, p->pHaving); + sqlite3ExprListDelete(db, p->pOrderBy); + sqlite3SelectDelete(db, p->pPrior); + sqlite3ExprDelete(db, p->pLimit); + sqlite3ExprDelete(db, p->pOffset); } /* @@ -63526,13 +66820,11 @@ SQLITE_PRIVATE Select *sqlite3SelectNew( assert( pOffset==0 || pLimit!=0 ); pNew->pLimit = pLimit; pNew->pOffset = pOffset; - pNew->iLimit = -1; - pNew->iOffset = -1; pNew->addrOpenEphm[0] = -1; pNew->addrOpenEphm[1] = -1; pNew->addrOpenEphm[2] = -1; if( pNew==&standin) { - clearSelect(pNew); + clearSelect(db, pNew); pNew = 0; } return pNew; @@ -63541,10 +66833,10 @@ SQLITE_PRIVATE Select *sqlite3SelectNew( /* ** Delete the given Select structure and all of its substructures. */ -SQLITE_PRIVATE void sqlite3SelectDelete(Select *p){ +SQLITE_PRIVATE void sqlite3SelectDelete(sqlite3 *db, Select *p){ if( p ){ - clearSelect(p); - sqlite3_free(p); + clearSelect(db, p); + sqlite3DbFree(db, p); } } @@ -63604,12 +66896,11 @@ SQLITE_PRIVATE int sqlite3JoinType(Parse *pParse, Token *pA, Token *pB, Token *p (jointype & (JT_INNER|JT_OUTER))==(JT_INNER|JT_OUTER) || (jointype & JT_ERROR)!=0 ){ - const char *zSp1 = " "; - const char *zSp2 = " "; - if( pB==0 ){ zSp1++; } - if( pC==0 ){ zSp2++; } + const char *zSp = " "; + assert( pB!=0 ); + if( pC==0 ){ zSp++; } sqlite3ErrorMsg(pParse, "unknown or unsupported join type: " - "%T%s%T%s%T", pA, zSp1, pB, zSp2, pC); + "%T %T%s%T", pA, pB, zSp, pC); jointype = JT_INNER; }else if( jointype & JT_RIGHT ){ sqlite3ErrorMsg(pParse, @@ -63866,15 +67157,15 @@ static void pushOntoSorter( int regRecord = sqlite3GetTempReg(pParse); sqlite3ExprCodeExprList(pParse, pOrderBy, regBase, 0); sqlite3VdbeAddOp2(v, OP_Sequence, pOrderBy->iECursor, regBase+nExpr); - sqlite3ExprCodeMove(pParse, regData, regBase+nExpr+1); + sqlite3ExprCodeMove(pParse, regData, regBase+nExpr+1, 1); sqlite3VdbeAddOp3(v, OP_MakeRecord, regBase, nExpr + 2, regRecord); sqlite3VdbeAddOp2(v, OP_IdxInsert, pOrderBy->iECursor, regRecord); sqlite3ReleaseTempReg(pParse, regRecord); sqlite3ReleaseTempRange(pParse, regBase, nExpr+2); - if( pSelect->iLimit>=0 ){ + if( pSelect->iLimit ){ int addr1, addr2; int iLimit; - if( pSelect->pOffset ){ + if( pSelect->iOffset ){ iLimit = pSelect->iOffset+1; }else{ iLimit = pSelect->iLimit; @@ -63886,7 +67177,7 @@ static void pushOntoSorter( sqlite3VdbeAddOp1(v, OP_Last, pOrderBy->iECursor); sqlite3VdbeAddOp1(v, OP_Delete, pOrderBy->iECursor); sqlite3VdbeJumpHere(v, addr2); - pSelect->iLimit = -1; + pSelect->iLimit = 0; } } @@ -63898,7 +67189,7 @@ static void codeOffset( Select *p, /* The SELECT statement being coded */ int iContinue /* Jump here to skip the current record */ ){ - if( p->iOffset>=0 && iContinue!=0 ){ + if( p->iOffset && iContinue!=0 ){ int addr; sqlite3VdbeAddOp2(v, OP_AddImm, p->iOffset, -1); addr = sqlite3VdbeAddOp1(v, OP_IfNeg, p->iOffset); @@ -63975,8 +67266,7 @@ static void selectInnerLoop( int distinct, /* If >=0, make sure results are distinct */ SelectDest *pDest, /* How to dispose of the results */ int iContinue, /* Jump here to continue with next row */ - int iBreak, /* Jump here to break out of the inner loop */ - char *aff /* affinity string if eDest is SRT_Union */ + int iBreak /* Jump here to break out of the inner loop */ ){ Vdbe *v = pParse->pVdbe; int i; @@ -63988,11 +67278,7 @@ static void selectInnerLoop( if( v==0 ) return; assert( pEList!=0 ); - - /* If there was a LIMIT clause on the SELECT statement, then do the check - ** to see if this row should be output. - */ - hasDistinct = distinct>=0 && pEList->nExpr>0; + hasDistinct = distinct>=0; if( pOrderBy==0 && !hasDistinct ){ codeOffset(v, p, iContinue); } @@ -64005,8 +67291,9 @@ static void selectInnerLoop( nResultCol = pEList->nExpr; } if( pDest->iMem==0 ){ - pDest->iMem = sqlite3GetTempRange(pParse, nResultCol); + pDest->iMem = pParse->nMem+1; pDest->nMem = nResultCol; + pParse->nMem += nResultCol; }else if( pDest->nMem!=nResultCol ){ /* This happens when two SELECTs of a compound SELECT have differing ** numbers of result columns. The error message will be generated by @@ -64052,9 +67339,6 @@ static void selectInnerLoop( int r1; r1 = sqlite3GetTempReg(pParse); sqlite3VdbeAddOp3(v, OP_MakeRecord, regResult, nColumn, r1); - if( aff ){ - sqlite3VdbeChangeP4(v, -1, aff, P4_STATIC); - } sqlite3VdbeAddOp2(v, OP_IdxInsert, iParm, r1); sqlite3ReleaseTempReg(pParse, r1); break; @@ -64095,10 +67379,7 @@ static void selectInnerLoop( ** item into the set table with bogus data. */ case SRT_Set: { - int addr2; - assert( nColumn==1 ); - addr2 = sqlite3VdbeAddOp1(v, OP_IsNull, regResult); p->affinity = sqlite3CompareAffinity(pEList->a[0].pExpr, pDest->affinity); if( pOrderBy ){ /* At first glance you would think we could optimize out the @@ -64113,7 +67394,6 @@ static void selectInnerLoop( sqlite3VdbeAddOp2(v, OP_IdxInsert, iParm, r1); sqlite3ReleaseTempReg(pParse, r1); } - sqlite3VdbeJumpHere(v, addr2); break; } @@ -64134,7 +67414,7 @@ static void selectInnerLoop( if( pOrderBy ){ pushOntoSorter(pParse, pOrderBy, p, regResult); }else{ - sqlite3ExprCodeMove(pParse, regResult, iParm); + sqlite3ExprCodeMove(pParse, regResult, iParm, 1); /* The LIMIT clause will jump out of the loop for us */ } break; @@ -64145,15 +67425,15 @@ static void selectInnerLoop( ** case of a subroutine, the subroutine itself is responsible for ** popping the data from the stack. */ - case SRT_Subroutine: + case SRT_Coroutine: case SRT_Callback: { if( pOrderBy ){ int r1 = sqlite3GetTempReg(pParse); sqlite3VdbeAddOp3(v, OP_MakeRecord, regResult, nColumn, r1); pushOntoSorter(pParse, pOrderBy, p, r1); sqlite3ReleaseTempReg(pParse, r1); - }else if( eDest==SRT_Subroutine ){ - sqlite3VdbeAddOp2(v, OP_Gosub, 0, iParm); + }else if( eDest==SRT_Coroutine ){ + sqlite3VdbeAddOp1(v, OP_Yield, pDest->iParm); }else{ sqlite3VdbeAddOp2(v, OP_ResultRow, regResult, nColumn); sqlite3ExprCacheAffinityChange(pParse, regResult, nColumn); @@ -64176,7 +67456,9 @@ static void selectInnerLoop( /* Jump to the end of the loop if the LIMIT is reached. */ - if( p->iLimit>=0 && pOrderBy==0 ){ + if( p->iLimit ){ + assert( pOrderBy==0 ); /* If there is an ORDER BY, the call to + ** pushOntoSorter() would have cleared p->iLimit */ sqlite3VdbeAddOp2(v, OP_AddImm, p->iLimit, -1); sqlite3VdbeAddOp2(v, OP_IfZero, p->iLimit, iBreak); } @@ -64251,7 +67533,7 @@ static void generateSortTail( int regRowid; iTab = pOrderBy->iECursor; - if( eDest==SRT_Callback || eDest==SRT_Subroutine ){ + if( eDest==SRT_Callback || eDest==SRT_Coroutine ){ pseudoTab = pParse->nTab++; sqlite3VdbeAddOp2(v, OP_SetNumColumns, 0, nColumn); sqlite3VdbeAddOp2(v, OP_OpenPseudo, pseudoTab, eDest==SRT_Callback); @@ -64271,24 +67553,21 @@ static void generateSortTail( } #ifndef SQLITE_OMIT_SUBQUERY case SRT_Set: { - int j1; assert( nColumn==1 ); - j1 = sqlite3VdbeAddOp1(v, OP_IsNull, regRow); sqlite3VdbeAddOp4(v, OP_MakeRecord, regRow, 1, regRowid, &p->affinity, 1); sqlite3ExprCacheAffinityChange(pParse, regRow, 1); sqlite3VdbeAddOp2(v, OP_IdxInsert, iParm, regRowid); - sqlite3VdbeJumpHere(v, j1); break; } case SRT_Mem: { assert( nColumn==1 ); - sqlite3ExprCodeMove(pParse, regRow, iParm); + sqlite3ExprCodeMove(pParse, regRow, iParm, 1); /* The LIMIT clause will terminate the loop for us */ break; } #endif case SRT_Callback: - case SRT_Subroutine: { + case SRT_Coroutine: { int i; sqlite3VdbeAddOp2(v, OP_Integer, 1, regRowid); sqlite3VdbeAddOp3(v, OP_Insert, pseudoTab, regRow, regRowid); @@ -64300,7 +67579,7 @@ static void generateSortTail( sqlite3VdbeAddOp2(v, OP_ResultRow, pDest->iMem, nColumn); sqlite3ExprCacheAffinityChange(pParse, pDest->iMem, nColumn); }else{ - sqlite3VdbeAddOp2(v, OP_Gosub, 0, iParm); + sqlite3VdbeAddOp1(v, OP_Yield, pDest->iParm); } break; } @@ -64312,19 +67591,16 @@ static void generateSortTail( sqlite3ReleaseTempReg(pParse, regRow); sqlite3ReleaseTempReg(pParse, regRowid); - /* Jump to the end of the loop when the LIMIT is reached + /* LIMIT has been implemented by the pushOntoSorter() routine. */ - if( p->iLimit>=0 ){ - sqlite3VdbeAddOp2(v, OP_AddImm, p->iLimit, -1); - sqlite3VdbeAddOp2(v, OP_IfZero, p->iLimit, brk); - } + assert( p->iLimit==0 ); /* The bottom of the loop */ sqlite3VdbeResolveLabel(v, cont); sqlite3VdbeAddOp2(v, OP_Next, iTab, addr); sqlite3VdbeResolveLabel(v, brk); - if( eDest==SRT_Callback || eDest==SRT_Subroutine ){ + if( eDest==SRT_Callback || eDest==SRT_Coroutine ){ sqlite3VdbeAddOp2(v, OP_Close, pseudoTab, 0); } @@ -64537,9 +67813,7 @@ static void generateColumnNames( if( pEList->a[i].zName ){ char *zName = pEList->a[i].zName; sqlite3VdbeSetColName(v, i, COLNAME_NAME, zName, strlen(zName)); - continue; - } - if( p->op==TK_COLUMN && pTabList ){ + }else if( p->op==TK_COLUMN && pTabList ){ Table *pTab; char *zCol; int iCol = p->iColumn; @@ -64553,7 +67827,7 @@ static void generateColumnNames( }else{ zCol = pTab->aCol[iCol].zName; } - if( !shortNames && !fullNames && p->span.z && p->span.z[0] ){ + if( !shortNames && !fullNames ){ sqlite3VdbeSetColName(v, i, COLNAME_NAME, (char*)p->span.z, p->span.n); }else if( fullNames || (!shortNames && pTabList->nSrc>1) ){ char *zName = 0; @@ -64561,19 +67835,13 @@ static void generateColumnNames( zTab = pTabList->a[j].zAlias; if( fullNames || zTab==0 ) zTab = pTab->zName; - sqlite3SetString(&zName, zTab, ".", zCol, (char*)0); + zName = sqlite3MPrintf(db, "%s.%s", zTab, zCol); sqlite3VdbeSetColName(v, i, COLNAME_NAME, zName, P4_DYNAMIC); }else{ sqlite3VdbeSetColName(v, i, COLNAME_NAME, zCol, strlen(zCol)); } - }else if( p->span.z && p->span.z[0] ){ - sqlite3VdbeSetColName(v, i, COLNAME_NAME, (char*)p->span.z, p->span.n); - /* sqlite3VdbeCompressSpace(v, addr); */ }else{ - char zName[30]; - assert( p->op!=TK_COLUMN || pTabList==0 ); - sqlite3_snprintf(sizeof(zName), zName, "column%d", i+1); - sqlite3VdbeSetColName(v, i, COLNAME_NAME, zName, 0); + sqlite3VdbeSetColName(v, i, COLNAME_NAME, (char*)p->span.z, p->span.n); } } generateColumnTypes(pParse, pTabList, pEList); @@ -64606,30 +67874,41 @@ static int prepSelectStmt(Parse*, Select*); */ SQLITE_PRIVATE Table *sqlite3ResultSetOfSelect(Parse *pParse, char *zTabName, Select *pSelect){ Table *pTab; - int i, j; + int i, j, rc; ExprList *pEList; Column *aCol, *pCol; sqlite3 *db = pParse->db; + int savedFlags; - while( pSelect->pPrior ) pSelect = pSelect->pPrior; - if( prepSelectStmt(pParse, pSelect) ){ - return 0; + savedFlags = db->flags; + db->flags &= ~SQLITE_FullColNames; + db->flags |= SQLITE_ShortColNames; + rc = sqlite3SelectResolve(pParse, pSelect, 0); + if( rc==SQLITE_OK ){ + while( pSelect->pPrior ) pSelect = pSelect->pPrior; + rc = prepSelectStmt(pParse, pSelect); + if( rc==SQLITE_OK ){ + rc = sqlite3SelectResolve(pParse, pSelect, 0); + } } - if( sqlite3SelectResolve(pParse, pSelect, 0) ){ + db->flags = savedFlags; + if( rc ){ return 0; } pTab = sqlite3DbMallocZero(db, sizeof(Table) ); if( pTab==0 ){ return 0; } + pTab->db = db; pTab->nRef = 1; pTab->zName = zTabName ? sqlite3DbStrDup(db, zTabName) : 0; pEList = pSelect->pEList; pTab->nCol = pEList->nExpr; assert( pTab->nCol>0 ); pTab->aCol = aCol = sqlite3DbMallocZero(db, sizeof(pTab->aCol[0])*pTab->nCol); + testcase( aCol==0 ); for(i=0, pCol=aCol; i<pTab->nCol; i++, pCol++){ - Expr *p, *pR; + Expr *p; char *zType; char *zName; int nName; @@ -64644,22 +67923,18 @@ SQLITE_PRIVATE Table *sqlite3ResultSetOfSelect(Parse *pParse, char *zTabName, Se if( (zName = pEList->a[i].zName)!=0 ){ /* If the column contains an "AS <name>" phrase, use <name> as the name */ zName = sqlite3DbStrDup(db, zName); - }else if( p->op==TK_DOT - && (pR=p->pRight)!=0 && pR->token.z && pR->token.z[0] ){ - /* For columns of the from A.B use B as the name */ - zName = sqlite3MPrintf(db, "%T", &pR->token); - }else if( p->span.z && p->span.z[0] ){ + }else if( p->op==TK_COLUMN && p->pTab ){ + /* For columns use the column name name */ + int iCol = p->iColumn; + if( iCol<0 ) iCol = p->pTab->iPKey; + zName = sqlite3MPrintf(db, "%s", p->pTab->aCol[iCol].zName); + }else{ /* Use the original text of the column expression as its name */ zName = sqlite3MPrintf(db, "%T", &p->span); - }else{ - /* If all else fails, make up a name */ - zName = sqlite3MPrintf(db, "column%d", i+1); } - if( !zName || db->mallocFailed ){ - db->mallocFailed = 1; - sqlite3_free(zName); - sqlite3DeleteTable(pTab); - return 0; + if( db->mallocFailed ){ + sqlite3DbFree(db, zName); + break; } sqlite3Dequote(zName); @@ -64669,8 +67944,11 @@ SQLITE_PRIVATE Table *sqlite3ResultSetOfSelect(Parse *pParse, char *zTabName, Se nName = strlen(zName); for(j=cnt=0; j<i; j++){ if( sqlite3StrICmp(aCol[j].zName, zName)==0 ){ + char *zNewName; zName[nName] = 0; - zName = sqlite3MPrintf(db, "%z:%d", zName, ++cnt); + zNewName = sqlite3MPrintf(db, "%s:%d", zName, ++cnt); + sqlite3DbFree(db, zName); + zName = zNewName; j = -1; if( zName==0 ) break; } @@ -64691,6 +67969,10 @@ SQLITE_PRIVATE Table *sqlite3ResultSetOfSelect(Parse *pParse, char *zTabName, Se } } pTab->iPKey = -1; + if( db->mallocFailed ){ + sqlite3DeleteTable(pTab); + return 0; + } return pTab; } @@ -64828,8 +68110,8 @@ static int prepSelectStmt(Parse *pParse, Select *p){ struct ExprList_item *a = pEList->a; ExprList *pNew = 0; int flags = pParse->db->flags; - int longNames = (flags & SQLITE_FullColNames)!=0 && - (flags & SQLITE_ShortColNames)==0; + int longNames = (flags & SQLITE_FullColNames)!=0 + && (flags & SQLITE_ShortColNames)==0; for(k=0; k<pEList->nExpr; k++){ Expr *pE = a[k].pExpr; @@ -64861,8 +68143,8 @@ static int prepSelectStmt(Parse *pParse, Select *p){ if( zTabName==0 || zTabName[0]==0 ){ zTabName = pTab->zName; } - if( zTName && (zTabName==0 || zTabName[0]==0 || - sqlite3StrICmp(zTName, zTabName)!=0) ){ + assert( zTabName ); + if( zTName && sqlite3StrICmp(zTName, zTabName)!=0 ){ continue; } tableSeen = 1; @@ -64896,14 +68178,19 @@ static int prepSelectStmt(Parse *pParse, Select *p){ pRight = sqlite3PExpr(pParse, TK_ID, 0, 0, 0); if( pRight==0 ) break; setQuotedToken(pParse, &pRight->token, zName); - if( zTabName && (longNames || pTabList->nSrc>1) ){ + if( longNames || pTabList->nSrc>1 ){ Expr *pLeft = sqlite3PExpr(pParse, TK_ID, 0, 0, 0); pExpr = sqlite3PExpr(pParse, TK_DOT, pLeft, pRight, 0); if( pExpr==0 ) break; setQuotedToken(pParse, &pLeft->token, zTabName); +#if 1 setToken(&pExpr->span, sqlite3MPrintf(db, "%s.%s", zTabName, zName)); pExpr->span.dyn = 1; +#else + pExpr->span = pRight->token; + pExpr->span.dyn = 0; +#endif pExpr->token.z = 0; pExpr->token.n = 0; pExpr->token.dyn = 0; @@ -64927,10 +68214,10 @@ static int prepSelectStmt(Parse *pParse, Select *p){ } rc = 1; } - sqlite3_free(zTName); + sqlite3DbFree(db, zTName); } } - sqlite3ExprListDelete(pEList); + sqlite3ExprListDelete(db, pEList); p->pEList = pNew; } #if SQLITE_MAX_COLUMN @@ -64949,9 +68236,9 @@ static int prepSelectStmt(Parse *pParse, Select *p){ ** pE is a pointer to an expression which is a single term in ** ORDER BY or GROUP BY clause. ** -** If pE evaluates to an integer constant i, then return i. -** This is an indication to the caller that it should sort -** by the i-th column of the result set. +** At the point this routine is called, we already know that the +** ORDER BY term is not an integer index into the result set. That +** casee is handled by the calling routine. ** ** If pE is a well-formed expression and the SELECT statement ** is not compound, then return 0. This indicates to the @@ -64976,20 +68263,8 @@ static int matchOrderByTermToExprList( ExprList *pEList; /* The columns of the result set */ NameContext nc; /* Name context for resolving pE */ - - /* If the term is an integer constant, return the value of that - ** constant */ + assert( sqlite3ExprIsInteger(pE, &i)==0 ); pEList = pSelect->pEList; - if( sqlite3ExprIsInteger(pE, &i) ){ - if( i<=0 ){ - /* If i is too small, make it too big. That way the calling - ** function still sees a value that is out of range, but does - ** not confuse the column number with 0 or -1 result code. - */ - i = pEList->nExpr+1; - } - return i; - } /* If the term is a simple identifier that try to match that identifier ** against a column name in the result set. @@ -65003,11 +68278,11 @@ static int matchOrderByTermToExprList( for(i=0; i<pEList->nExpr; i++){ char *zAs = pEList->a[i].zName; if( zAs!=0 && sqlite3StrICmp(zAs, zCol)==0 ){ - sqlite3_free(zCol); + sqlite3DbFree(db, zCol); return i+1; } } - sqlite3_free(zCol); + sqlite3DbFree(db, zCol); } /* Resolve all names in the ORDER BY term expression @@ -65079,21 +68354,24 @@ static int processOrderGroupBy( for(i=0; i<pOrderBy->nExpr; i++){ int iCol; Expr *pE = pOrderBy->a[i].pExpr; - iCol = matchOrderByTermToExprList(pParse, pSelect, pE, i+1, 0, pHasAgg); - if( iCol<0 ){ - return 1; - } - if( iCol>pEList->nExpr ){ - const char *zType = isOrder ? "ORDER" : "GROUP"; - sqlite3ErrorMsg(pParse, - "%r %s BY term out of range - should be " - "between 1 and %d", i+1, zType, pEList->nExpr); - return 1; + if( sqlite3ExprIsInteger(pE, &iCol) ){ + if( iCol<=0 || iCol>pEList->nExpr ){ + const char *zType = isOrder ? "ORDER" : "GROUP"; + sqlite3ErrorMsg(pParse, + "%r %s BY term out of range - should be " + "between 1 and %d", i+1, zType, pEList->nExpr); + return 1; + } + }else{ + iCol = matchOrderByTermToExprList(pParse, pSelect, pE, i+1, 0, pHasAgg); + if( iCol<0 ){ + return 1; + } } if( iCol>0 ){ CollSeq *pColl = pE->pColl; int flags = pE->flags & EP_ExpCollate; - sqlite3ExprDelete(pE); + sqlite3ExprDelete(db, pE); pE = sqlite3ExprDup(db, pEList->a[iCol-1].pExpr); pOrderBy->a[i].pExpr = pE; if( pE && pColl && flags ){ @@ -65109,22 +68387,15 @@ static int processOrderGroupBy( ** Analyze and ORDER BY or GROUP BY clause in a SELECT statement. Return ** the number of errors seen. ** -** The processing depends on whether the SELECT is simple or compound. -** For a simple SELECT statement, evry term of the ORDER BY or GROUP BY -** clause needs to be an expression. If any expression is an integer -** constant, then that expression is replaced by the corresponding -** expression from the result set. +** If iTable>0 then make the N-th term of the ORDER BY clause refer to +** the N-th column of table iTable. ** -** For compound SELECT statements, every expression needs to be of -** type TK_COLUMN with a iTable value as given in the 4th parameter. -** If any expression is an integer, that becomes the column number. -** Otherwise, match the expression against result set columns from -** the left-most SELECT. +** If iTable==0 then transform each term of the ORDER BY clause to refer +** to a column of the result set by number. */ static int processCompoundOrderBy( Parse *pParse, /* Parsing context. Leave error messages here */ - Select *pSelect, /* The SELECT statement containing the ORDER BY */ - int iTable /* Output table for compound SELECT statements */ + Select *pSelect /* The SELECT statement containing the ORDER BY */ ){ int i; ExprList *pOrderBy; @@ -65149,36 +68420,37 @@ static int processCompoundOrderBy( } while( pSelect && moreToDo ){ moreToDo = 0; + pEList = pSelect->pEList; + if( pEList==0 ){ + return 1; + } for(i=0; i<pOrderBy->nExpr; i++){ int iCol = -1; Expr *pE, *pDup; if( pOrderBy->a[i].done ) continue; pE = pOrderBy->a[i].pExpr; - pDup = sqlite3ExprDup(db, pE); - if( !db->mallocFailed ){ - assert(pDup); - iCol = matchOrderByTermToExprList(pParse, pSelect, pDup, i+1, 1, 0); - } - sqlite3ExprDelete(pDup); - if( iCol<0 ){ - return 1; - } - pEList = pSelect->pEList; - if( pEList==0 ){ - return 1; - } - if( iCol>pEList->nExpr ){ - sqlite3ErrorMsg(pParse, - "%r ORDER BY term out of range - should be " - "between 1 and %d", i+1, pEList->nExpr); - return 1; + if( sqlite3ExprIsInteger(pE, &iCol) ){ + if( iCol<0 || iCol>pEList->nExpr ){ + sqlite3ErrorMsg(pParse, + "%r ORDER BY term out of range - should be " + "between 1 and %d", i+1, pEList->nExpr); + return 1; + } + }else{ + pDup = sqlite3ExprDup(db, pE); + if( !db->mallocFailed ){ + assert(pDup); + iCol = matchOrderByTermToExprList(pParse, pSelect, pDup, i+1, 1, 0); + } + sqlite3ExprDelete(db, pDup); + if( iCol<0 ){ + return 1; + } } if( iCol>0 ){ - pE->op = TK_COLUMN; - pE->iTable = iTable; - pE->iAgg = -1; - pE->iColumn = iCol-1; - pE->pTab = 0; + pE->op = TK_INTEGER; + pE->flags |= EP_IntValue; + pE->iTable = iCol; pOrderBy->a[i].done = 1; }else{ moreToDo = 1; @@ -65237,6 +68509,7 @@ static void computeLimitRegisters(Parse *pParse, Select *p, int iBreak){ int iLimit = 0; int iOffset; int addr1; + if( p->iLimit ) return; /* ** "LIMIT -1" always shows all rows. There is some @@ -65276,21 +68549,6 @@ static void computeLimitRegisters(Parse *pParse, Select *p, int iBreak){ } } -/* -** Allocate a virtual index to use for sorting. -*/ -static void createSortingIndex(Parse *pParse, Select *p, ExprList *pOrderBy){ - if( pOrderBy ){ - int addr; - assert( pOrderBy->iECursor==0 ); - pOrderBy->iECursor = pParse->nTab++; - addr = sqlite3VdbeAddOp2(pParse->pVdbe, OP_OpenEphemeral, - pOrderBy->iECursor, pOrderBy->nExpr+1); - assert( p->addrOpenEphm[2] == -1 ); - p->addrOpenEphm[2] = addr; - } -} - #ifndef SQLITE_OMIT_COMPOUND_SELECT /* ** Return the appropriate collating sequence for the iCol-th column of @@ -65314,10 +68572,19 @@ static CollSeq *multiSelectCollSeq(Parse *pParse, Select *p, int iCol){ } #endif /* SQLITE_OMIT_COMPOUND_SELECT */ +/* Forward reference */ +static int multiSelectOrderBy( + Parse *pParse, /* Parsing context */ + Select *p, /* The right-most of SELECTs to be coded */ + SelectDest *pDest /* What to do with query results */ +); + + #ifndef SQLITE_OMIT_COMPOUND_SELECT /* -** This routine is called to process a query that is really the union -** or intersection of two or more separate queries. +** This routine is called to process a compound query form from +** two or more separate queries using UNION, UNION ALL, EXCEPT, or +** INTERSECT ** ** "p" points to the right-most of the two queries. the query on the ** left is p->pPrior. The left query could also be a compound query @@ -65348,27 +68615,20 @@ static CollSeq *multiSelectCollSeq(Parse *pParse, Select *p, int iCol){ static int multiSelect( Parse *pParse, /* Parsing context */ Select *p, /* The right-most of SELECTs to be coded */ - SelectDest *pDest, /* What to do with query results */ - char *aff /* If eDest is SRT_Union, the affinity string */ + SelectDest *pDest /* What to do with query results */ ){ int rc = SQLITE_OK; /* Success code from a subroutine */ Select *pPrior; /* Another SELECT immediately to our left */ Vdbe *v; /* Generate code to this VDBE */ - int nCol; /* Number of columns in the result set */ - ExprList *pOrderBy; /* The ORDER BY clause on p */ - int aSetP2[2]; /* Set P2 value of these op to number of columns */ - int nSetP2 = 0; /* Number of slots in aSetP2[] used */ SelectDest dest; /* Alternative data destination */ - - dest = *pDest; + Select *pDelete = 0; /* Chain of simple selects to delete */ + sqlite3 *db; /* Database connection */ /* Make sure there is no ORDER BY or LIMIT clause on prior SELECTs. Only ** the last (right-most) SELECT in the series may have an ORDER BY or LIMIT. */ - if( p==0 || p->pPrior==0 ){ - rc = 1; - goto multi_select_end; - } + assert( p && p->pPrior ); /* Calling function guarantees this much */ + db = pParse->db; pPrior = p->pPrior; assert( pPrior->pRightmost!=pPrior ); assert( pPrior->pRightmost==p->pRightmost ); @@ -65385,57 +68645,66 @@ static int multiSelect( goto multi_select_end; } - /* Make sure we have a valid query engine. If not, create a new one. - */ v = sqlite3GetVdbe(pParse); - if( v==0 ){ - rc = 1; - goto multi_select_end; - } + assert( v!=0 ); /* The VDBE already created by calling function */ /* Create the destination temporary table if necessary */ + dest = *pDest; if( dest.eDest==SRT_EphemTab ){ assert( p->pEList ); - assert( nSetP2<sizeof(aSetP2)/sizeof(aSetP2[0]) ); - aSetP2[nSetP2++] = sqlite3VdbeAddOp2(v, OP_OpenEphemeral, dest.iParm, 0); + sqlite3VdbeAddOp2(v, OP_OpenEphemeral, dest.iParm, p->pEList->nExpr); dest.eDest = SRT_Table; } + /* Make sure all SELECTs in the statement have the same number of elements + ** in their result sets. + */ + assert( p->pEList && pPrior->pEList ); + if( p->pEList->nExpr!=pPrior->pEList->nExpr ){ + sqlite3ErrorMsg(pParse, "SELECTs to the left and right of %s" + " do not have the same number of result columns", selectOpName(p->op)); + rc = 1; + goto multi_select_end; + } + + /* Compound SELECTs that have an ORDER BY clause are handled separately. + */ + if( p->pOrderBy ){ + return multiSelectOrderBy(pParse, p, pDest); + } + /* Generate code for the left and right SELECT statements. */ - pOrderBy = p->pOrderBy; switch( p->op ){ case TK_ALL: { - if( pOrderBy==0 ){ - int addr = 0; - assert( !pPrior->pLimit ); - pPrior->pLimit = p->pLimit; - pPrior->pOffset = p->pOffset; - rc = sqlite3Select(pParse, pPrior, &dest, 0, 0, 0, aff); - p->pLimit = 0; - p->pOffset = 0; - if( rc ){ - goto multi_select_end; - } - p->pPrior = 0; - p->iLimit = pPrior->iLimit; - p->iOffset = pPrior->iOffset; - if( p->iLimit>=0 ){ - addr = sqlite3VdbeAddOp1(v, OP_IfZero, p->iLimit); - VdbeComment((v, "Jump ahead if LIMIT reached")); - } - rc = sqlite3Select(pParse, p, &dest, 0, 0, 0, aff); - p->pPrior = pPrior; - if( rc ){ - goto multi_select_end; - } - if( addr ){ - sqlite3VdbeJumpHere(v, addr); - } - break; + int addr = 0; + assert( !pPrior->pLimit ); + pPrior->pLimit = p->pLimit; + pPrior->pOffset = p->pOffset; + rc = sqlite3Select(pParse, pPrior, &dest, 0, 0, 0); + p->pLimit = 0; + p->pOffset = 0; + if( rc ){ + goto multi_select_end; } - /* For UNION ALL ... ORDER BY fall through to the next case */ + p->pPrior = 0; + p->iLimit = pPrior->iLimit; + p->iOffset = pPrior->iOffset; + if( p->iLimit ){ + addr = sqlite3VdbeAddOp1(v, OP_IfZero, p->iLimit); + VdbeComment((v, "Jump ahead if LIMIT reached")); + } + rc = sqlite3Select(pParse, p, &dest, 0, 0, 0); + pDelete = p->pPrior; + p->pPrior = pPrior; + if( rc ){ + goto multi_select_end; + } + if( addr ){ + sqlite3VdbeJumpHere(v, addr); + } + break; } case TK_EXCEPT: case TK_UNION: { @@ -65446,8 +68715,8 @@ static int multiSelect( int addr; SelectDest uniondest; - priorOp = p->op==TK_ALL ? SRT_Table : SRT_Union; - if( dest.eDest==priorOp && pOrderBy==0 && !p->pLimit && !p->pOffset ){ + priorOp = SRT_Union; + if( dest.eDest==priorOp && !p->pLimit && !p->pOffset ){ /* We can reuse a temporary table generated by a SELECT to our ** right. */ @@ -65457,20 +68726,11 @@ static int multiSelect( ** intermediate results. */ unionTab = pParse->nTab++; - if( processCompoundOrderBy(pParse, p, unionTab) ){ - rc = 1; - goto multi_select_end; - } + assert( p->pOrderBy==0 ); addr = sqlite3VdbeAddOp2(v, OP_OpenEphemeral, unionTab, 0); - if( priorOp==SRT_Table ){ - assert( nSetP2<sizeof(aSetP2)/sizeof(aSetP2[0]) ); - aSetP2[nSetP2++] = addr; - }else{ - assert( p->addrOpenEphm[0] == -1 ); - p->addrOpenEphm[0] = addr; - p->pRightmost->usesEphm = 1; - } - createSortingIndex(pParse, p, pOrderBy); + assert( p->addrOpenEphm[0] == -1 ); + p->addrOpenEphm[0] = addr; + p->pRightmost->usesEphm = 1; assert( p->pEList ); } @@ -65478,37 +68738,38 @@ static int multiSelect( */ assert( !pPrior->pOrderBy ); sqlite3SelectDestInit(&uniondest, priorOp, unionTab); - rc = sqlite3Select(pParse, pPrior, &uniondest, 0, 0, 0, aff); + rc = sqlite3Select(pParse, pPrior, &uniondest, 0, 0, 0); if( rc ){ goto multi_select_end; } /* Code the current SELECT statement */ - switch( p->op ){ - case TK_EXCEPT: op = SRT_Except; break; - case TK_UNION: op = SRT_Union; break; - case TK_ALL: op = SRT_Table; break; + if( p->op==TK_EXCEPT ){ + op = SRT_Except; + }else{ + assert( p->op==TK_UNION ); + op = SRT_Union; } p->pPrior = 0; - p->pOrderBy = 0; - p->disallowOrderBy = pOrderBy!=0; + p->disallowOrderBy = 0; pLimit = p->pLimit; p->pLimit = 0; pOffset = p->pOffset; p->pOffset = 0; uniondest.eDest = op; - rc = sqlite3Select(pParse, p, &uniondest, 0, 0, 0, aff); + rc = sqlite3Select(pParse, p, &uniondest, 0, 0, 0); /* Query flattening in sqlite3Select() might refill p->pOrderBy. ** Be sure to delete p->pOrderBy, therefore, to avoid a memory leak. */ - sqlite3ExprListDelete(p->pOrderBy); + sqlite3ExprListDelete(db, p->pOrderBy); + pDelete = p->pPrior; p->pPrior = pPrior; - p->pOrderBy = pOrderBy; - sqlite3ExprDelete(p->pLimit); + p->pOrderBy = 0; + sqlite3ExprDelete(db, p->pLimit); p->pLimit = pLimit; p->pOffset = pOffset; - p->iLimit = -1; - p->iOffset = -1; + p->iLimit = 0; + p->iOffset = 0; if( rc ){ goto multi_select_end; } @@ -65531,7 +68792,7 @@ static int multiSelect( sqlite3VdbeAddOp2(v, OP_Rewind, unionTab, iBreak); iStart = sqlite3VdbeCurrentAddr(v); selectInnerLoop(pParse, p, p->pEList, unionTab, p->pEList->nExpr, - pOrderBy, -1, &dest, iCont, iBreak, 0); + 0, -1, &dest, iCont, iBreak); sqlite3VdbeResolveLabel(v, iCont); sqlite3VdbeAddOp2(v, OP_Next, unionTab, iStart); sqlite3VdbeResolveLabel(v, iBreak); @@ -65553,11 +68814,7 @@ static int multiSelect( */ tab1 = pParse->nTab++; tab2 = pParse->nTab++; - if( processCompoundOrderBy(pParse, p, tab1) ){ - rc = 1; - goto multi_select_end; - } - createSortingIndex(pParse, p, pOrderBy); + assert( p->pOrderBy==0 ); addr = sqlite3VdbeAddOp2(v, OP_OpenEphemeral, tab1, 0); assert( p->addrOpenEphm[0] == -1 ); @@ -65568,7 +68825,7 @@ static int multiSelect( /* Code the SELECTs to our left into temporary table "tab1". */ sqlite3SelectDestInit(&intersectdest, SRT_Union, tab1); - rc = sqlite3Select(pParse, pPrior, &intersectdest, 0, 0, 0, aff); + rc = sqlite3Select(pParse, pPrior, &intersectdest, 0, 0, 0); if( rc ){ goto multi_select_end; } @@ -65584,9 +68841,10 @@ static int multiSelect( pOffset = p->pOffset; p->pOffset = 0; intersectdest.iParm = tab2; - rc = sqlite3Select(pParse, p, &intersectdest, 0, 0, 0, aff); + rc = sqlite3Select(pParse, p, &intersectdest, 0, 0, 0); + pDelete = p->pPrior; p->pPrior = pPrior; - sqlite3ExprDelete(p->pLimit); + sqlite3ExprDelete(db, p->pLimit); p->pLimit = pLimit; p->pOffset = pOffset; if( rc ){ @@ -65611,7 +68869,7 @@ static int multiSelect( sqlite3VdbeAddOp3(v, OP_NotFound, tab2, iCont, r1); sqlite3ReleaseTempReg(pParse, r1); selectInnerLoop(pParse, p, p->pEList, tab1, p->pEList->nExpr, - pOrderBy, -1, &dest, iCont, iBreak, 0); + 0, -1, &dest, iCont, iBreak); sqlite3VdbeResolveLabel(v, iCont); sqlite3VdbeAddOp2(v, OP_Next, tab1, iStart); sqlite3VdbeResolveLabel(v, iBreak); @@ -65621,58 +68879,38 @@ static int multiSelect( } } - /* Make sure all SELECTs in the statement have the same number of elements - ** in their result sets. - */ - assert( p->pEList && pPrior->pEList ); - if( p->pEList->nExpr!=pPrior->pEList->nExpr ){ - sqlite3ErrorMsg(pParse, "SELECTs to the left and right of %s" - " do not have the same number of result columns", selectOpName(p->op)); - rc = 1; - goto multi_select_end; - } - - /* Set the number of columns in temporary tables - */ - nCol = p->pEList->nExpr; - while( nSetP2 ){ - sqlite3VdbeChangeP2(v, aSetP2[--nSetP2], nCol); - } - - /* Compute collating sequences used by either the ORDER BY clause or - ** by any temporary tables needed to implement the compound select. - ** Attach the KeyInfo structure to all temporary tables. Invoke the - ** ORDER BY processing if there is an ORDER BY clause. + /* Compute collating sequences used by + ** temporary tables needed to implement the compound select. + ** Attach the KeyInfo structure to all temporary tables. ** ** This section is run by the right-most SELECT statement only. ** SELECT statements to the left always skip this part. The right-most ** SELECT might also skip this part if it has no ORDER BY clause and ** no temp tables are required. */ - if( pOrderBy || p->usesEphm ){ + if( p->usesEphm ){ int i; /* Loop counter */ KeyInfo *pKeyInfo; /* Collating sequence for the result set */ Select *pLoop; /* For looping through SELECT statements */ - int nKeyCol; /* Number of entries in pKeyInfo->aCol[] */ CollSeq **apColl; /* For looping through pKeyInfo->aColl[] */ - CollSeq **aCopy; /* A copy of pKeyInfo->aColl[] */ + int nCol; /* Number of columns in result set */ assert( p->pRightmost==p ); - nKeyCol = nCol + (pOrderBy ? pOrderBy->nExpr : 0); - pKeyInfo = sqlite3DbMallocZero(pParse->db, - sizeof(*pKeyInfo)+nKeyCol*(sizeof(CollSeq*) + 1)); + nCol = p->pEList->nExpr; + pKeyInfo = sqlite3DbMallocZero(db, + sizeof(*pKeyInfo)+nCol*(sizeof(CollSeq*) + 1)); if( !pKeyInfo ){ rc = SQLITE_NOMEM; goto multi_select_end; } - pKeyInfo->enc = ENC(pParse->db); + pKeyInfo->enc = ENC(db); pKeyInfo->nField = nCol; for(i=0, apColl=pKeyInfo->aColl; i<nCol; i++, apColl++){ *apColl = multiSelectCollSeq(pParse, p, i); if( 0==*apColl ){ - *apColl = pParse->db->pDfltColl; + *apColl = db->pDfltColl; } } @@ -65690,62 +68928,611 @@ static int multiSelect( pLoop->addrOpenEphm[i] = -1; } } + sqlite3DbFree(db, pKeyInfo); + } - if( pOrderBy ){ - struct ExprList_item *pOTerm = pOrderBy->a; - int nOrderByExpr = pOrderBy->nExpr; - int addr; - u8 *pSortOrder; - - /* Reuse the same pKeyInfo for the ORDER BY as was used above for - ** the compound select statements. Except we have to change out the - ** pKeyInfo->aColl[] values. Some of the aColl[] values will be - ** reused when constructing the pKeyInfo for the ORDER BY, so make - ** a copy. Sufficient space to hold both the nCol entries for - ** the compound select and the nOrderbyExpr entries for the ORDER BY - ** was allocated above. But we need to move the compound select - ** entries out of the way before constructing the ORDER BY entries. - ** Move the compound select entries into aCopy[] where they can be - ** accessed and reused when constructing the ORDER BY entries. - ** Because nCol might be greater than or less than nOrderByExpr - ** we have to use memmove() when doing the copy. - */ - aCopy = &pKeyInfo->aColl[nOrderByExpr]; - pSortOrder = pKeyInfo->aSortOrder = (u8*)&aCopy[nCol]; - memmove(aCopy, pKeyInfo->aColl, nCol*sizeof(CollSeq*)); - - apColl = pKeyInfo->aColl; - for(i=0; i<nOrderByExpr; i++, pOTerm++, apColl++, pSortOrder++){ - Expr *pExpr = pOTerm->pExpr; - if( (pExpr->flags & EP_ExpCollate) ){ - assert( pExpr->pColl!=0 ); - *apColl = pExpr->pColl; +multi_select_end: + pDest->iMem = dest.iMem; + pDest->nMem = dest.nMem; + sqlite3SelectDelete(db, pDelete); + return rc; +} +#endif /* SQLITE_OMIT_COMPOUND_SELECT */ + +/* +** Code an output subroutine for a coroutine implementation of a +** SELECT statment. +** +** The data to be output is contained in pIn->iMem. There are +** pIn->nMem columns to be output. pDest is where the output should +** be sent. +** +** regReturn is the number of the register holding the subroutine +** return address. +** +** If regPrev>0 then it is a the first register in a vector that +** records the previous output. mem[regPrev] is a flag that is false +** if there has been no previous output. If regPrev>0 then code is +** generated to suppress duplicates. pKeyInfo is used for comparing +** keys. +** +** If the LIMIT found in p->iLimit is reached, jump immediately to +** iBreak. +*/ +static int generateOutputSubroutine( + Parse *pParse, /* Parsing context */ + Select *p, /* The SELECT statement */ + SelectDest *pIn, /* Coroutine supplying data */ + SelectDest *pDest, /* Where to send the data */ + int regReturn, /* The return address register */ + int regPrev, /* Previous result register. No uniqueness if 0 */ + KeyInfo *pKeyInfo, /* For comparing with previous entry */ + int p4type, /* The p4 type for pKeyInfo */ + int iBreak /* Jump here if we hit the LIMIT */ +){ + Vdbe *v = pParse->pVdbe; + int iContinue; + int addr; + + addr = sqlite3VdbeCurrentAddr(v); + iContinue = sqlite3VdbeMakeLabel(v); + + /* Suppress duplicates for UNION, EXCEPT, and INTERSECT + */ + if( regPrev ){ + int j1, j2; + j1 = sqlite3VdbeAddOp1(v, OP_IfNot, regPrev); + j2 = sqlite3VdbeAddOp4(v, OP_Compare, pIn->iMem, regPrev+1, pIn->nMem, + (char*)pKeyInfo, p4type); + sqlite3VdbeAddOp3(v, OP_Jump, j2+2, iContinue, j2+2); + sqlite3VdbeJumpHere(v, j1); + sqlite3ExprCodeCopy(pParse, pIn->iMem, regPrev+1, pIn->nMem); + sqlite3VdbeAddOp2(v, OP_Integer, 1, regPrev); + } + if( pParse->db->mallocFailed ) return 0; + + /* Suppress the the first OFFSET entries if there is an OFFSET clause + */ + codeOffset(v, p, iContinue); + + switch( pDest->eDest ){ + /* Store the result as data using a unique key. + */ + case SRT_Table: + case SRT_EphemTab: { + int r1 = sqlite3GetTempReg(pParse); + int r2 = sqlite3GetTempReg(pParse); + sqlite3VdbeAddOp3(v, OP_MakeRecord, pIn->iMem, pIn->nMem, r1); + sqlite3VdbeAddOp2(v, OP_NewRowid, pDest->iParm, r2); + sqlite3VdbeAddOp3(v, OP_Insert, pDest->iParm, r1, r2); + sqlite3VdbeChangeP5(v, OPFLAG_APPEND); + sqlite3ReleaseTempReg(pParse, r2); + sqlite3ReleaseTempReg(pParse, r1); + break; + } + +#ifndef SQLITE_OMIT_SUBQUERY + /* If we are creating a set for an "expr IN (SELECT ...)" construct, + ** then there should be a single item on the stack. Write this + ** item into the set table with bogus data. + */ + case SRT_Set: { + int r1; + assert( pIn->nMem==1 ); + p->affinity = + sqlite3CompareAffinity(p->pEList->a[0].pExpr, pDest->affinity); + r1 = sqlite3GetTempReg(pParse); + sqlite3VdbeAddOp4(v, OP_MakeRecord, pIn->iMem, 1, r1, &p->affinity, 1); + sqlite3ExprCacheAffinityChange(pParse, pIn->iMem, 1); + sqlite3VdbeAddOp2(v, OP_IdxInsert, pDest->iParm, r1); + sqlite3ReleaseTempReg(pParse, r1); + break; + } + +#if 0 /* Never occurs on an ORDER BY query */ + /* If any row exist in the result set, record that fact and abort. + */ + case SRT_Exists: { + sqlite3VdbeAddOp2(v, OP_Integer, 1, pDest->iParm); + /* The LIMIT clause will terminate the loop for us */ + break; + } +#endif + + /* If this is a scalar select that is part of an expression, then + ** store the results in the appropriate memory cell and break out + ** of the scan loop. + */ + case SRT_Mem: { + assert( pIn->nMem==1 ); + sqlite3ExprCodeMove(pParse, pIn->iMem, pDest->iParm, 1); + /* The LIMIT clause will jump out of the loop for us */ + break; + } +#endif /* #ifndef SQLITE_OMIT_SUBQUERY */ + + /* Send the data to the callback function or to a subroutine. In the + ** case of a subroutine, the subroutine itself is responsible for + ** popping the data from the stack. + */ + case SRT_Coroutine: { + if( pDest->iMem==0 ){ + pDest->iMem = sqlite3GetTempRange(pParse, pIn->nMem); + pDest->nMem = pIn->nMem; + } + sqlite3ExprCodeMove(pParse, pIn->iMem, pDest->iMem, pDest->nMem); + sqlite3VdbeAddOp1(v, OP_Yield, pDest->iParm); + break; + } + + case SRT_Callback: { + sqlite3VdbeAddOp2(v, OP_ResultRow, pIn->iMem, pIn->nMem); + sqlite3ExprCacheAffinityChange(pParse, pIn->iMem, pIn->nMem); + break; + } + +#if !defined(SQLITE_OMIT_TRIGGER) + /* Discard the results. This is used for SELECT statements inside + ** the body of a TRIGGER. The purpose of such selects is to call + ** user-defined functions that have side effects. We do not care + ** about the actual results of the select. + */ + default: { + break; + } +#endif + } + + /* Jump to the end of the loop if the LIMIT is reached. + */ + if( p->iLimit ){ + sqlite3VdbeAddOp2(v, OP_AddImm, p->iLimit, -1); + sqlite3VdbeAddOp2(v, OP_IfZero, p->iLimit, iBreak); + } + + /* Generate the subroutine return + */ + sqlite3VdbeResolveLabel(v, iContinue); + sqlite3VdbeAddOp1(v, OP_Return, regReturn); + + return addr; +} + +/* +** Alternative compound select code generator for cases when there +** is an ORDER BY clause. +** +** We assume a query of the following form: +** +** <selectA> <operator> <selectB> ORDER BY <orderbylist> +** +** <operator> is one of UNION ALL, UNION, EXCEPT, or INTERSECT. The idea +** is to code both <selectA> and <selectB> with the ORDER BY clause as +** co-routines. Then run the co-routines in parallel and merge the results +** into the output. In addition to the two coroutines (called selectA and +** selectB) there are 7 subroutines: +** +** outA: Move the output of the selectA coroutine into the output +** of the compound query. +** +** outB: Move the output of the selectB coroutine into the output +** of the compound query. (Only generated for UNION and +** UNION ALL. EXCEPT and INSERTSECT never output a row that +** appears only in B.) +** +** AltB: Called when there is data from both coroutines and A<B. +** +** AeqB: Called when there is data from both coroutines and A==B. +** +** AgtB: Called when there is data from both coroutines and A>B. +** +** EofA: Called when data is exhausted from selectA. +** +** EofB: Called when data is exhausted from selectB. +** +** The implementation of the latter five subroutines depend on which +** <operator> is used: +** +** +** UNION ALL UNION EXCEPT INTERSECT +** ------------- ----------------- -------------- ----------------- +** AltB: outA, nextA outA, nextA outA, nextA nextA +** +** AeqB: outA, nextA nextA nextA outA, nextA +** +** AgtB: outB, nextB outB, nextB nextB nextB +** +** EofA: outB, nextB outB, nextB halt halt +** +** EofB: outA, nextA outA, nextA outA, nextA halt +** +** In the AltB, AeqB, and AgtB subroutines, an EOF on A following nextA +** causes an immediate jump to EofA and an EOF on B following nextB causes +** an immediate jump to EofB. Within EofA and EofB, and EOF on entry or +** following nextX causes a jump to the end of the select processing. +** +** Duplicate removal in the UNION, EXCEPT, and INTERSECT cases is handled +** within the output subroutine. The regPrev register set holds the previously +** output value. A comparison is made against this value and the output +** is skipped if the next results would be the same as the previous. +** +** The implementation plan is to implement the two coroutines and seven +** subroutines first, then put the control logic at the bottom. Like this: +** +** goto Init +** coA: coroutine for left query (A) +** coB: coroutine for right query (B) +** outA: output one row of A +** outB: output one row of B (UNION and UNION ALL only) +** EofA: ... +** EofB: ... +** AltB: ... +** AeqB: ... +** AgtB: ... +** Init: initialize coroutine registers +** yield coA +** if eof(A) goto EofA +** yield coB +** if eof(B) goto EofB +** Cmpr: Compare A, B +** Jump AltB, AeqB, AgtB +** End: ... +** +** We call AltB, AeqB, AgtB, EofA, and EofB "subroutines" but they are not +** actually called using Gosub and they do not Return. EofA and EofB loop +** until all data is exhausted then jump to the "end" labe. AltB, AeqB, +** and AgtB jump to either L2 or to one of EofA or EofB. +*/ +#ifndef SQLITE_OMIT_COMPOUND_SELECT +static int multiSelectOrderBy( + Parse *pParse, /* Parsing context */ + Select *p, /* The right-most of SELECTs to be coded */ + SelectDest *pDest /* What to do with query results */ +){ + int i, j; /* Loop counters */ + Select *pPrior; /* Another SELECT immediately to our left */ + Vdbe *v; /* Generate code to this VDBE */ + SelectDest destA; /* Destination for coroutine A */ + SelectDest destB; /* Destination for coroutine B */ + int regAddrA; /* Address register for select-A coroutine */ + int regEofA; /* Flag to indicate when select-A is complete */ + int regAddrB; /* Address register for select-B coroutine */ + int regEofB; /* Flag to indicate when select-B is complete */ + int addrSelectA; /* Address of the select-A coroutine */ + int addrSelectB; /* Address of the select-B coroutine */ + int regOutA; /* Address register for the output-A subroutine */ + int regOutB; /* Address register for the output-B subroutine */ + int addrOutA; /* Address of the output-A subroutine */ + int addrOutB; /* Address of the output-B subroutine */ + int addrEofA; /* Address of the select-A-exhausted subroutine */ + int addrEofB; /* Address of the select-B-exhausted subroutine */ + int addrAltB; /* Address of the A<B subroutine */ + int addrAeqB; /* Address of the A==B subroutine */ + int addrAgtB; /* Address of the A>B subroutine */ + int regLimitA; /* Limit register for select-A */ + int regLimitB; /* Limit register for select-A */ + int regPrev; /* A range of registers to hold previous output */ + int savedLimit; /* Saved value of p->iLimit */ + int savedOffset; /* Saved value of p->iOffset */ + int labelCmpr; /* Label for the start of the merge algorithm */ + int labelEnd; /* Label for the end of the overall SELECT stmt */ + int j1; /* Jump instructions that get retargetted */ + int op; /* One of TK_ALL, TK_UNION, TK_EXCEPT, TK_INTERSECT */ + KeyInfo *pKeyDup; /* Comparison information for duplicate removal */ + KeyInfo *pKeyMerge; /* Comparison information for merging rows */ + sqlite3 *db; /* Database connection */ + ExprList *pOrderBy; /* The ORDER BY clause */ + int nOrderBy; /* Number of terms in the ORDER BY clause */ + int *aPermute; /* Mapping from ORDER BY terms to result set columns */ + u8 NotUsed; /* Dummy variables */ + + assert( p->pOrderBy!=0 ); + db = pParse->db; + v = pParse->pVdbe; + if( v==0 ) return SQLITE_NOMEM; + labelEnd = sqlite3VdbeMakeLabel(v); + labelCmpr = sqlite3VdbeMakeLabel(v); + + + /* Patch up the ORDER BY clause + */ + op = p->op; + pPrior = p->pPrior; + assert( pPrior->pOrderBy==0 ); + pOrderBy = p->pOrderBy; + assert( pOrderBy ); + if( processCompoundOrderBy(pParse, p) ){ + return SQLITE_ERROR; + } + nOrderBy = pOrderBy->nExpr; + + /* For operators other than UNION ALL we have to make sure that + ** the ORDER BY clause covers every term of the result set. Add + ** terms to the ORDER BY clause as necessary. + */ + if( op!=TK_ALL ){ + for(i=1; db->mallocFailed==0 && i<=p->pEList->nExpr; i++){ + for(j=0; j<nOrderBy; j++){ + Expr *pTerm = pOrderBy->a[j].pExpr; + assert( pTerm->op==TK_INTEGER ); + assert( (pTerm->flags & EP_IntValue)!=0 ); + if( pTerm->iTable==i ) break; + } + if( j==nOrderBy ){ + Expr *pNew = sqlite3PExpr(pParse, TK_INTEGER, 0, 0, 0); + if( pNew==0 ) return SQLITE_NOMEM; + pNew->flags |= EP_IntValue; + pNew->iTable = i; + pOrderBy = sqlite3ExprListAppend(pParse, pOrderBy, pNew, 0); + nOrderBy++; + } + } + } + + /* Compute the comparison permutation and keyinfo that is used with + ** the permutation in order to comparisons to determine if the next + ** row of results comes from selectA or selectB. Also add explicit + ** collations to the ORDER BY clause terms so that when the subqueries + ** to the right and the left are evaluated, they use the correct + ** collation. + */ + aPermute = sqlite3DbMallocRaw(db, sizeof(int)*nOrderBy); + if( aPermute ){ + for(i=0; i<nOrderBy; i++){ + Expr *pTerm = pOrderBy->a[i].pExpr; + assert( pTerm->op==TK_INTEGER ); + assert( (pTerm->flags & EP_IntValue)!=0 ); + aPermute[i] = pTerm->iTable-1; + assert( aPermute[i]>=0 && aPermute[i]<p->pEList->nExpr ); + } + pKeyMerge = + sqlite3DbMallocRaw(db, sizeof(*pKeyMerge)+nOrderBy*(sizeof(CollSeq*)+1)); + if( pKeyMerge ){ + pKeyMerge->aSortOrder = (u8*)&pKeyMerge->aColl[nOrderBy]; + pKeyMerge->nField = nOrderBy; + pKeyMerge->enc = ENC(db); + for(i=0; i<nOrderBy; i++){ + CollSeq *pColl; + Expr *pTerm = pOrderBy->a[i].pExpr; + if( pTerm->flags & EP_ExpCollate ){ + pColl = pTerm->pColl; }else{ - *apColl = aCopy[pExpr->iColumn]; + pColl = multiSelectCollSeq(pParse, p, aPermute[i]); + pTerm->flags |= EP_ExpCollate; + pTerm->pColl = pColl; } - *pSortOrder = pOTerm->sortOrder; + pKeyMerge->aColl[i] = pColl; + pKeyMerge->aSortOrder[i] = pOrderBy->a[i].sortOrder; } - assert( p->pRightmost==p ); - assert( p->addrOpenEphm[2]>=0 ); - addr = p->addrOpenEphm[2]; - sqlite3VdbeChangeP2(v, addr, p->pOrderBy->nExpr+2); - pKeyInfo->nField = nOrderByExpr; - sqlite3VdbeChangeP4(v, addr, (char*)pKeyInfo, P4_KEYINFO_HANDOFF); - pKeyInfo = 0; - generateSortTail(pParse, p, v, p->pEList->nExpr, &dest); } + }else{ + pKeyMerge = 0; + } + + /* Reattach the ORDER BY clause to the query. + */ + p->pOrderBy = pOrderBy; + pPrior->pOrderBy = sqlite3ExprListDup(pParse->db, pOrderBy); - sqlite3_free(pKeyInfo); + /* Allocate a range of temporary registers and the KeyInfo needed + ** for the logic that removes duplicate result rows when the + ** operator is UNION, EXCEPT, or INTERSECT (but not UNION ALL). + */ + if( op==TK_ALL ){ + regPrev = 0; + }else{ + int nExpr = p->pEList->nExpr; + assert( nOrderBy>=nExpr ); + regPrev = sqlite3GetTempRange(pParse, nExpr+1); + sqlite3VdbeAddOp2(v, OP_Integer, 0, regPrev); + pKeyDup = sqlite3DbMallocZero(db, + sizeof(*pKeyDup) + nExpr*(sizeof(CollSeq*)+1) ); + if( pKeyDup ){ + pKeyDup->aSortOrder = (u8*)&pKeyDup->aColl[nExpr]; + pKeyDup->nField = nExpr; + pKeyDup->enc = ENC(db); + for(i=0; i<nExpr; i++){ + pKeyDup->aColl[i] = multiSelectCollSeq(pParse, p, i); + pKeyDup->aSortOrder[i] = 0; + } + } + } + + /* Separate the left and the right query from one another + */ + p->pPrior = 0; + pPrior->pRightmost = 0; + processOrderGroupBy(pParse, p, p->pOrderBy, 1, &NotUsed); + if( pPrior->pPrior==0 ){ + processOrderGroupBy(pParse, pPrior, pPrior->pOrderBy, 1, &NotUsed); + } + + /* Compute the limit registers */ + computeLimitRegisters(pParse, p, labelEnd); + if( p->iLimit && op==TK_ALL ){ + regLimitA = ++pParse->nMem; + regLimitB = ++pParse->nMem; + sqlite3VdbeAddOp2(v, OP_Copy, p->iOffset ? p->iOffset+1 : p->iLimit, + regLimitA); + sqlite3VdbeAddOp2(v, OP_Copy, regLimitA, regLimitB); + }else{ + regLimitA = regLimitB = 0; + } + sqlite3ExprDelete(db, p->pLimit); + p->pLimit = 0; + sqlite3ExprDelete(db, p->pOffset); + p->pOffset = 0; + + regAddrA = ++pParse->nMem; + regEofA = ++pParse->nMem; + regAddrB = ++pParse->nMem; + regEofB = ++pParse->nMem; + regOutA = ++pParse->nMem; + regOutB = ++pParse->nMem; + sqlite3SelectDestInit(&destA, SRT_Coroutine, regAddrA); + sqlite3SelectDestInit(&destB, SRT_Coroutine, regAddrB); + + /* Jump past the various subroutines and coroutines to the main + ** merge loop + */ + j1 = sqlite3VdbeAddOp0(v, OP_Goto); + addrSelectA = sqlite3VdbeCurrentAddr(v); + + + /* Generate a coroutine to evaluate the SELECT statement to the + ** left of the compound operator - the "A" select. + */ + VdbeNoopComment((v, "Begin coroutine for left SELECT")); + pPrior->iLimit = regLimitA; + sqlite3Select(pParse, pPrior, &destA, 0, 0, 0); + sqlite3VdbeAddOp2(v, OP_Integer, 1, regEofA); + sqlite3VdbeAddOp1(v, OP_Yield, regAddrA); + VdbeNoopComment((v, "End coroutine for left SELECT")); + + /* Generate a coroutine to evaluate the SELECT statement on + ** the right - the "B" select + */ + addrSelectB = sqlite3VdbeCurrentAddr(v); + VdbeNoopComment((v, "Begin coroutine for right SELECT")); + savedLimit = p->iLimit; + savedOffset = p->iOffset; + p->iLimit = regLimitB; + p->iOffset = 0; + sqlite3Select(pParse, p, &destB, 0, 0, 0); + p->iLimit = savedLimit; + p->iOffset = savedOffset; + sqlite3VdbeAddOp2(v, OP_Integer, 1, regEofB); + sqlite3VdbeAddOp1(v, OP_Yield, regAddrB); + VdbeNoopComment((v, "End coroutine for right SELECT")); + + /* Generate a subroutine that outputs the current row of the A + ** select as the next output row of the compound select. + */ + VdbeNoopComment((v, "Output routine for A")); + addrOutA = generateOutputSubroutine(pParse, + p, &destA, pDest, regOutA, + regPrev, pKeyDup, P4_KEYINFO_HANDOFF, labelEnd); + + /* Generate a subroutine that outputs the current row of the B + ** select as the next output row of the compound select. + */ + if( op==TK_ALL || op==TK_UNION ){ + VdbeNoopComment((v, "Output routine for B")); + addrOutB = generateOutputSubroutine(pParse, + p, &destB, pDest, regOutB, + regPrev, pKeyDup, P4_KEYINFO_STATIC, labelEnd); } -multi_select_end: - pDest->iMem = dest.iMem; - pDest->nMem = dest.nMem; - return rc; + /* Generate a subroutine to run when the results from select A + ** are exhausted and only data in select B remains. + */ + VdbeNoopComment((v, "eof-A subroutine")); + if( op==TK_EXCEPT || op==TK_INTERSECT ){ + addrEofA = sqlite3VdbeAddOp2(v, OP_Goto, 0, labelEnd); + }else{ + addrEofA = sqlite3VdbeAddOp2(v, OP_If, regEofB, labelEnd); + sqlite3VdbeAddOp2(v, OP_Gosub, regOutB, addrOutB); + sqlite3VdbeAddOp1(v, OP_Yield, regAddrB); + sqlite3VdbeAddOp2(v, OP_Goto, 0, addrEofA); + } + + /* Generate a subroutine to run when the results from select B + ** are exhausted and only data in select A remains. + */ + if( op==TK_INTERSECT ){ + addrEofB = addrEofA; + }else{ + VdbeNoopComment((v, "eof-B subroutine")); + addrEofB = sqlite3VdbeAddOp2(v, OP_If, regEofA, labelEnd); + sqlite3VdbeAddOp2(v, OP_Gosub, regOutA, addrOutA); + sqlite3VdbeAddOp1(v, OP_Yield, regAddrA); + sqlite3VdbeAddOp2(v, OP_Goto, 0, addrEofB); + } + + /* Generate code to handle the case of A<B + */ + VdbeNoopComment((v, "A-lt-B subroutine")); + addrAltB = sqlite3VdbeAddOp2(v, OP_Gosub, regOutA, addrOutA); + sqlite3VdbeAddOp1(v, OP_Yield, regAddrA); + sqlite3VdbeAddOp2(v, OP_If, regEofA, addrEofA); + sqlite3VdbeAddOp2(v, OP_Goto, 0, labelCmpr); + + /* Generate code to handle the case of A==B + */ + if( op==TK_ALL ){ + addrAeqB = addrAltB; + }else if( op==TK_INTERSECT ){ + addrAeqB = addrAltB; + addrAltB++; + }else{ + VdbeNoopComment((v, "A-eq-B subroutine")); + addrAeqB = + sqlite3VdbeAddOp1(v, OP_Yield, regAddrA); + sqlite3VdbeAddOp2(v, OP_If, regEofA, addrEofA); + sqlite3VdbeAddOp2(v, OP_Goto, 0, labelCmpr); + } + + /* Generate code to handle the case of A>B + */ + VdbeNoopComment((v, "A-gt-B subroutine")); + addrAgtB = sqlite3VdbeCurrentAddr(v); + if( op==TK_ALL || op==TK_UNION ){ + sqlite3VdbeAddOp2(v, OP_Gosub, regOutB, addrOutB); + } + sqlite3VdbeAddOp1(v, OP_Yield, regAddrB); + sqlite3VdbeAddOp2(v, OP_If, regEofB, addrEofB); + sqlite3VdbeAddOp2(v, OP_Goto, 0, labelCmpr); + + /* This code runs once to initialize everything. + */ + sqlite3VdbeJumpHere(v, j1); + sqlite3VdbeAddOp2(v, OP_Integer, 0, regEofA); + sqlite3VdbeAddOp2(v, OP_Integer, 0, regEofB); + sqlite3VdbeAddOp2(v, OP_Gosub, regAddrA, addrSelectA); + sqlite3VdbeAddOp2(v, OP_Gosub, regAddrB, addrSelectB); + sqlite3VdbeAddOp2(v, OP_If, regEofA, addrEofA); + sqlite3VdbeAddOp2(v, OP_If, regEofB, addrEofB); + + /* Implement the main merge loop + */ + sqlite3VdbeResolveLabel(v, labelCmpr); + sqlite3VdbeAddOp4(v, OP_Permutation, 0, 0, 0, (char*)aPermute, P4_INTARRAY); + sqlite3VdbeAddOp4(v, OP_Compare, destA.iMem, destB.iMem, nOrderBy, + (char*)pKeyMerge, P4_KEYINFO_HANDOFF); + sqlite3VdbeAddOp3(v, OP_Jump, addrAltB, addrAeqB, addrAgtB); + + /* Release temporary registers + */ + if( regPrev ){ + sqlite3ReleaseTempRange(pParse, regPrev, nOrderBy+1); + } + + /* Jump to the this point in order to terminate the query. + */ + sqlite3VdbeResolveLabel(v, labelEnd); + + /* Set the number of output columns + */ + if( pDest->eDest==SRT_Callback ){ + Select *pFirst = pPrior; + while( pFirst->pPrior ) pFirst = pFirst->pPrior; + generateColumnNames(pParse, 0, pFirst->pEList); + } + + /* Reassembly the compound query so that it will be freed correctly + ** by the calling function */ + if( p->pPrior ){ + sqlite3SelectDelete(db, p->pPrior); + } + p->pPrior = pPrior; + + /*** TBD: Insert subroutine calls to close cursors on incomplete + **** subqueries ****/ + return SQLITE_OK; } -#endif /* SQLITE_OMIT_COMPOUND_SELECT */ +#endif -#ifndef SQLITE_OMIT_VIEW +#if !defined(SQLITE_OMIT_SUBQUERY) || !defined(SQLITE_OMIT_VIEW) /* Forward Declarations */ static void substExprList(sqlite3*, ExprList*, int, ExprList*); static void substSelect(sqlite3*, Select *, int, ExprList *); @@ -65828,9 +69615,9 @@ static void substSelect( substExpr(db, p->pWhere, iTable, pEList); substSelect(db, p->pPrior, iTable, pEList); } -#endif /* !defined(SQLITE_OMIT_VIEW) */ +#endif /* !defined(SQLITE_OMIT_SUBQUERY) || !defined(SQLITE_OMIT_VIEW) */ -#ifndef SQLITE_OMIT_VIEW +#if !defined(SQLITE_OMIT_SUBQUERY) || !defined(SQLITE_OMIT_VIEW) /* ** This routine attempts to flatten subqueries in order to speed ** execution. It returns 1 if it makes changes and 0 if no flattening @@ -65902,6 +69689,22 @@ static void substSelect( ** not contain ORDER BY. (Ticket #2942) This used to not matter ** until we introduced the group_concat() function. ** +** (17) The sub-query is not a compound select, or it is a UNION ALL +** compound clause made up entirely of non-aggregate queries, and +** the parent query: +** +** * is not itself part of a compound select, +** * is not an aggregate or DISTINCT query, and +** * has no other tables or sub-selects in the FROM clause. +** +** The parent and sub-query may contain WHERE clauses. Subject to +** rules (11), (13) and (14), they may also contain ORDER BY, +** LIMIT and OFFSET clauses. +** +** (18) If the sub-query is a compound select, then all terms of the +** ORDER by clause of the parent must be simple references to +** columns of the sub-query. +** ** In this routine, the "p" parameter is a pointer to the outer query. ** The subquery is p->pSrc->a[iFrom]. isAgg is true if the outer query ** uses aggregates and subqueryIsAgg is true if the subquery uses aggregates. @@ -65913,13 +69716,16 @@ static void substSelect( ** the subquery before this routine runs. */ static int flattenSubquery( - sqlite3 *db, /* Database connection */ + Parse *pParse, /* Parsing context */ Select *p, /* The parent or outer SELECT statement */ int iFrom, /* Index in p->pSrc->a[] of the inner subquery */ int isAgg, /* True if outer SELECT uses aggregate functions */ int subqueryIsAgg /* True if the subquery uses aggregate functions */ ){ + const char *zSavedAuthContext = pParse->zAuthContext; + Select *pParent; Select *pSub; /* The inner query or "subquery" */ + Select *pSub1; /* Pointer to the rightmost select in sub-query */ SrcList *pSrc; /* The FROM clause of the outer query */ SrcList *pSubSrc; /* The FROM clause of the subquery */ ExprList *pList; /* The result set of the outer query */ @@ -65927,6 +69733,7 @@ static int flattenSubquery( int i; /* Loop counter */ Expr *pWhere; /* The WHERE clause */ struct SrcList_item *pSubitem; /* The subquery */ + sqlite3 *db = pParse->db; /* Check to see if flattening is permitted. Return 0 if not. */ @@ -65934,6 +69741,7 @@ static int flattenSubquery( pSrc = p->pSrc; assert( pSrc && iFrom>=0 && iFrom<pSrc->nSrc ); pSubitem = &pSrc->a[iFrom]; + iParent = pSubitem->iCursor; pSub = pSubitem->pSelect; assert( pSub!=0 ); if( isAgg && subqueryIsAgg ) return 0; /* Restriction (1) */ @@ -65994,41 +69802,114 @@ static int flattenSubquery( return 0; } - /* If we reach this point, it means flattening is permitted for the - ** iFrom-th entry of the FROM clause in the outer query. + /* Restriction 17: If the sub-query is a compound SELECT, then it must + ** use only the UNION ALL operator. And none of the simple select queries + ** that make up the compound SELECT are allowed to be aggregate or distinct + ** queries. */ + if( pSub->pPrior ){ + if( p->pPrior || isAgg || p->isDistinct || pSrc->nSrc!=1 ){ + return 0; + } + for(pSub1=pSub; pSub1; pSub1=pSub1->pPrior){ + if( pSub1->isAgg || pSub1->isDistinct + || (pSub1->pPrior && pSub1->op!=TK_ALL) + || !pSub1->pSrc || pSub1->pSrc->nSrc!=1 + ){ + return 0; + } + } + + /* Restriction 18. */ + if( p->pOrderBy ){ + int ii; + for(ii=0; ii<p->pOrderBy->nExpr; ii++){ + Expr *pExpr = p->pOrderBy->a[ii].pExpr; + if( pExpr->op!=TK_COLUMN || pExpr->iTable!=iParent ){ + return 0; + } + } + } + } + + pParse->zAuthContext = pSubitem->zName; + sqlite3AuthCheck(pParse, SQLITE_SELECT, 0, 0, 0); + pParse->zAuthContext = zSavedAuthContext; + + /* If the sub-query is a compound SELECT statement, then it must be + ** a UNION ALL and the parent query must be of the form: + ** + ** SELECT <expr-list> FROM (<sub-query>) <where-clause> + ** + ** followed by any ORDER BY, LIMIT and/or OFFSET clauses. This block + ** creates N copies of the parent query without any ORDER BY, LIMIT or + ** OFFSET clauses and joins them to the left-hand-side of the original + ** using UNION ALL operators. In this case N is the number of simple + ** select statements in the compound sub-query. + */ + for(pSub=pSub->pPrior; pSub; pSub=pSub->pPrior){ + Select *pNew; + ExprList *pOrderBy = p->pOrderBy; + Expr *pLimit = p->pLimit; + Expr *pOffset = p->pOffset; + Select *pPrior = p->pPrior; + p->pOrderBy = 0; + p->pSrc = 0; + p->pPrior = 0; + p->pLimit = 0; + pNew = sqlite3SelectDup(db, p); + pNew->pPrior = pPrior; + p->pPrior = pNew; + p->pOrderBy = pOrderBy; + p->op = TK_ALL; + p->pSrc = pSrc; + p->pLimit = pLimit; + p->pOffset = pOffset; + p->pRightmost = 0; + pNew->pRightmost = 0; + } - /* Move all of the FROM elements of the subquery into the - ** the FROM clause of the outer query. Before doing this, remember - ** the cursor number for the original outer query FROM element in - ** iParent. The iParent cursor will never be used. Subsequent code - ** will scan expressions looking for iParent references and replace - ** those references with expressions that resolve to the subquery FROM - ** elements we are now copying in. + /* If we reach this point, it means flattening is permitted for the + ** iFrom-th entry of the FROM clause in the outer query. */ - iParent = pSubitem->iCursor; - { + pSub = pSub1 = pSubitem->pSelect; + for(pParent=p; pParent; pParent=pParent->pPrior, pSub=pSub->pPrior){ int nSubSrc = pSubSrc->nSrc; - int jointype = pSubitem->jointype; - - sqlite3DeleteTable(pSubitem->pTab); - sqlite3_free(pSubitem->zDatabase); - sqlite3_free(pSubitem->zName); - sqlite3_free(pSubitem->zAlias); - pSubitem->pTab = 0; - pSubitem->zDatabase = 0; - pSubitem->zName = 0; - pSubitem->zAlias = 0; - if( nSubSrc>1 ){ + int jointype = 0; + pSubSrc = pSub->pSrc; + pSrc = pParent->pSrc; + + /* Move all of the FROM elements of the subquery into the + ** the FROM clause of the outer query. Before doing this, remember + ** the cursor number for the original outer query FROM element in + ** iParent. The iParent cursor will never be used. Subsequent code + ** will scan expressions looking for iParent references and replace + ** those references with expressions that resolve to the subquery FROM + ** elements we are now copying in. + */ + if( pSrc ){ + pSubitem = &pSrc->a[iFrom]; + nSubSrc = pSubSrc->nSrc; + jointype = pSubitem->jointype; + sqlite3DeleteTable(pSubitem->pTab); + sqlite3DbFree(db, pSubitem->zDatabase); + sqlite3DbFree(db, pSubitem->zName); + sqlite3DbFree(db, pSubitem->zAlias); + pSubitem->pTab = 0; + pSubitem->zDatabase = 0; + pSubitem->zName = 0; + pSubitem->zAlias = 0; + } + if( nSubSrc!=1 || !pSrc ){ int extra = nSubSrc - 1; - for(i=1; i<nSubSrc; i++){ + for(i=(pSrc?1:0); i<nSubSrc; i++){ pSrc = sqlite3SrcListAppend(db, pSrc, 0, 0); if( pSrc==0 ){ - p->pSrc = 0; + pParent->pSrc = 0; return 1; } } - p->pSrc = pSrc; + pParent->pSrc = pSrc; for(i=pSrc->nSrc-1; i-extra>=iFrom; i--){ pSrc->a[i] = pSrc->a[i-extra]; } @@ -66038,82 +69919,83 @@ static int flattenSubquery( memset(&pSubSrc->a[i], 0, sizeof(pSubSrc->a[i])); } pSrc->a[iFrom].jointype = jointype; - } - - /* Now begin substituting subquery result set expressions for - ** references to the iParent in the outer query. - ** - ** Example: - ** - ** SELECT a+5, b*10 FROM (SELECT x*3 AS a, y+10 AS b FROM t1) WHERE a>b; - ** \ \_____________ subquery __________/ / - ** \_____________________ outer query ______________________________/ - ** - ** We look at every expression in the outer query and every place we see - ** "a" we substitute "x*3" and every place we see "b" we substitute "y+10". - */ - pList = p->pEList; - for(i=0; i<pList->nExpr; i++){ - Expr *pExpr; - if( pList->a[i].zName==0 && (pExpr = pList->a[i].pExpr)->span.z!=0 ){ - pList->a[i].zName = - sqlite3DbStrNDup(db, (char*)pExpr->span.z, pExpr->span.n); + + /* Now begin substituting subquery result set expressions for + ** references to the iParent in the outer query. + ** + ** Example: + ** + ** SELECT a+5, b*10 FROM (SELECT x*3 AS a, y+10 AS b FROM t1) WHERE a>b; + ** \ \_____________ subquery __________/ / + ** \_____________________ outer query ______________________________/ + ** + ** We look at every expression in the outer query and every place we see + ** "a" we substitute "x*3" and every place we see "b" we substitute "y+10". + */ + pList = pParent->pEList; + for(i=0; i<pList->nExpr; i++){ + Expr *pExpr; + if( pList->a[i].zName==0 && (pExpr = pList->a[i].pExpr)->span.z!=0 ){ + pList->a[i].zName = + sqlite3DbStrNDup(db, (char*)pExpr->span.z, pExpr->span.n); + } + } + substExprList(db, pParent->pEList, iParent, pSub->pEList); + if( isAgg ){ + substExprList(db, pParent->pGroupBy, iParent, pSub->pEList); + substExpr(db, pParent->pHaving, iParent, pSub->pEList); + } + if( pSub->pOrderBy ){ + assert( pParent->pOrderBy==0 ); + pParent->pOrderBy = pSub->pOrderBy; + pSub->pOrderBy = 0; + }else if( pParent->pOrderBy ){ + substExprList(db, pParent->pOrderBy, iParent, pSub->pEList); + } + if( pSub->pWhere ){ + pWhere = sqlite3ExprDup(db, pSub->pWhere); + }else{ + pWhere = 0; + } + if( subqueryIsAgg ){ + assert( pParent->pHaving==0 ); + pParent->pHaving = pParent->pWhere; + pParent->pWhere = pWhere; + substExpr(db, pParent->pHaving, iParent, pSub->pEList); + pParent->pHaving = sqlite3ExprAnd(db, pParent->pHaving, + sqlite3ExprDup(db, pSub->pHaving)); + assert( pParent->pGroupBy==0 ); + pParent->pGroupBy = sqlite3ExprListDup(db, pSub->pGroupBy); + }else{ + substExpr(db, pParent->pWhere, iParent, pSub->pEList); + pParent->pWhere = sqlite3ExprAnd(db, pParent->pWhere, pWhere); + } + + /* The flattened query is distinct if either the inner or the + ** outer query is distinct. + */ + pParent->isDistinct = pParent->isDistinct || pSub->isDistinct; + + /* + ** SELECT ... FROM (SELECT ... LIMIT a OFFSET b) LIMIT x OFFSET y; + ** + ** One is tempted to try to add a and b to combine the limits. But this + ** does not work if either limit is negative. + */ + if( pSub->pLimit ){ + pParent->pLimit = pSub->pLimit; + pSub->pLimit = 0; } - } - substExprList(db, p->pEList, iParent, pSub->pEList); - if( isAgg ){ - substExprList(db, p->pGroupBy, iParent, pSub->pEList); - substExpr(db, p->pHaving, iParent, pSub->pEList); - } - if( pSub->pOrderBy ){ - assert( p->pOrderBy==0 ); - p->pOrderBy = pSub->pOrderBy; - pSub->pOrderBy = 0; - }else if( p->pOrderBy ){ - substExprList(db, p->pOrderBy, iParent, pSub->pEList); - } - if( pSub->pWhere ){ - pWhere = sqlite3ExprDup(db, pSub->pWhere); - }else{ - pWhere = 0; - } - if( subqueryIsAgg ){ - assert( p->pHaving==0 ); - p->pHaving = p->pWhere; - p->pWhere = pWhere; - substExpr(db, p->pHaving, iParent, pSub->pEList); - p->pHaving = sqlite3ExprAnd(db, p->pHaving, - sqlite3ExprDup(db, pSub->pHaving)); - assert( p->pGroupBy==0 ); - p->pGroupBy = sqlite3ExprListDup(db, pSub->pGroupBy); - }else{ - substExpr(db, p->pWhere, iParent, pSub->pEList); - p->pWhere = sqlite3ExprAnd(db, p->pWhere, pWhere); - } - - /* The flattened query is distinct if either the inner or the - ** outer query is distinct. - */ - p->isDistinct = p->isDistinct || pSub->isDistinct; - - /* - ** SELECT ... FROM (SELECT ... LIMIT a OFFSET b) LIMIT x OFFSET y; - ** - ** One is tempted to try to add a and b to combine the limits. But this - ** does not work if either limit is negative. - */ - if( pSub->pLimit ){ - p->pLimit = pSub->pLimit; - pSub->pLimit = 0; } /* Finially, delete what is left of the subquery and return ** success. */ - sqlite3SelectDelete(pSub); + sqlite3SelectDelete(db, pSub1); + return 1; } -#endif /* SQLITE_OMIT_VIEW */ +#endif /* !defined(SQLITE_OMIT_SUBQUERY) || !defined(SQLITE_OMIT_VIEW) */ /* ** Analyze the SELECT statement passed as an argument to see if it @@ -66380,33 +70262,6 @@ static void updateAccumulator(Parse *pParse, AggInfo *pAggInfo){ pAggInfo->directMode = 0; } -#if 0 -/* -** This function is used when a SELECT statement is used to create a -** temporary table for iterating through when running an INSTEAD OF -** UPDATE or INSTEAD OF DELETE trigger. -** -** If possible, the SELECT statement is modified so that NULL values -** are stored in the temporary table for all columns for which the -** corresponding bit in argument mask is not set. If mask takes the -** special value 0xffffffff, then all columns are populated. -*/ -SQLITE_PRIVATE void sqlite3SelectMask(Parse *pParse, Select *p, u32 mask){ - if( p && !p->pPrior && !p->isDistinct && mask!=0xffffffff ){ - ExprList *pEList; - int i; - sqlite3SelectResolve(pParse, p, 0); - pEList = p->pEList; - for(i=0; pEList && i<pEList->nExpr && i<32; i++){ - if( !(mask&((u32)1<<i)) ){ - sqlite3ExprDelete(pEList->a[i].pExpr); - pEList->a[i].pExpr = sqlite3Expr(pParse->db, TK_NULL, 0, 0, 0); - } - } - } -} -#endif - /* ** Generate code for the given SELECT statement. ** @@ -66420,7 +70275,7 @@ SQLITE_PRIVATE void sqlite3SelectMask(Parse *pParse, Select *p, u32 mask){ ** ** SRT_Mem Store first result in memory cell pDest->iParm ** -** SRT_Set Store non-null results as keys of table pDest->iParm. +** SRT_Set Store results as keys of table pDest->iParm. ** Apply the affinity pDest->affinity before storing them. ** ** SRT_Union Store results as a key in a temporary table pDest->iParm. @@ -66433,9 +70288,8 @@ SQLITE_PRIVATE void sqlite3SelectMask(Parse *pParse, Select *p, u32 mask){ ** the result there. The cursor is left open after ** returning. ** -** SRT_Subroutine For each row returned, push the results onto the -** vdbe stack and call the subroutine (via OP_Gosub) -** at address pDest->iParm. +** SRT_Coroutine Invoke a co-routine to compute a single row of +** the result ** ** SRT_Exists Store a 1 in memory cell pDest->iParm if the result ** set is not empty. @@ -66479,8 +70333,7 @@ SQLITE_PRIVATE int sqlite3Select( SelectDest *pDest, /* What to do with the query results */ Select *pParent, /* Another SELECT for which this is a sub-query */ int parentTab, /* Index in pParent->pSrc of this query */ - int *pParentAgg, /* True if pParent uses aggregate functions */ - char *aff /* If eDest is SRT_Union, the affinity string */ + int *pParentAgg /* True if pParent uses aggregate functions */ ){ int i, j; /* Loop counters */ WhereInfo *pWInfo; /* Return from sqlite3WhereBegin() */ @@ -66523,37 +70376,11 @@ SQLITE_PRIVATE int sqlite3Select( } p->pOrderBy = pOrderBy; -#ifndef SQLITE_OMIT_COMPOUND_SELECT - /* If there is are a sequence of queries, do the earlier ones first. - */ - if( p->pPrior ){ - if( p->pRightmost==0 ){ - Select *pLoop, *pRight = 0; - int cnt = 0; - int mxSelect; - for(pLoop=p; pLoop; pLoop=pLoop->pPrior, cnt++){ - pLoop->pRightmost = p; - pLoop->pNext = pRight; - pRight = pLoop; - } - mxSelect = db->aLimit[SQLITE_LIMIT_COMPOUND_SELECT]; - if( mxSelect && cnt>mxSelect ){ - sqlite3ErrorMsg(pParse, "too many terms in compound SELECT"); - return 1; - } - } - return multiSelect(pParse, p, pDest, aff); - } -#endif /* Make local copies of the parameters for this query. */ pTabList = p->pSrc; - pWhere = p->pWhere; - pGroupBy = p->pGroupBy; - pHaving = p->pHaving; isAgg = p->isAgg; - isDistinct = p->isDistinct; pEList = p->pEList; if( pEList==0 ) goto select_end; @@ -66563,15 +70390,6 @@ SQLITE_PRIVATE int sqlite3Select( */ if( pParse->nErr>0 ) goto select_end; - /* If writing to memory or generating a set - ** only a single column may be output. - */ -#ifndef SQLITE_OMIT_SUBQUERY - if( checkForMultiColumnSelectError(pParse, pDest, pEList->nExpr) ){ - goto select_end; - } -#endif - /* ORDER BY is ignored for some destinations. */ if( IgnorableOrderby(pDest) ){ @@ -66586,20 +70404,24 @@ SQLITE_PRIVATE int sqlite3Select( /* Generate code for all sub-queries in the FROM clause */ #if !defined(SQLITE_OMIT_SUBQUERY) || !defined(SQLITE_OMIT_VIEW) - for(i=0; i<pTabList->nSrc; i++){ - const char *zSavedAuthContext = 0; - int needRestoreContext; + for(i=0; !p->pPrior && i<pTabList->nSrc; i++){ struct SrcList_item *pItem = &pTabList->a[i]; SelectDest dest; - - if( pItem->pSelect==0 || pItem->isPopulated ) continue; - if( pItem->zName!=0 ){ - zSavedAuthContext = pParse->zAuthContext; - pParse->zAuthContext = pItem->zName; - needRestoreContext = 1; - }else{ - needRestoreContext = 0; + Select *pSub = pItem->pSelect; + int isAggSub; + char *zName = pItem->zName; + + if( pSub==0 || pItem->isPopulated ) continue; + if( zName!=0 ){ /* An sql view */ + const char *zSavedAuthContext = pParse->zAuthContext; + pParse->zAuthContext = zName; + rc = sqlite3SelectResolve(pParse, pSub, 0); + pParse->zAuthContext = zSavedAuthContext; + if( rc ){ + goto select_end; + } } + /* Increment Parse.nHeight by the height of the largest expression ** tree refered to by this, the parent select. The child select ** may contain expression trees of at most @@ -66608,33 +70430,62 @@ SQLITE_PRIVATE int sqlite3Select( ** an exact limit. */ pParse->nHeight += sqlite3SelectExprHeight(p); - sqlite3SelectDestInit(&dest, SRT_EphemTab, pItem->iCursor); - sqlite3Select(pParse, pItem->pSelect, &dest, p, i, &isAgg, 0); - if( db->mallocFailed ){ + + /* Check to see if the subquery can be absorbed into the parent. */ + isAggSub = pSub->isAgg; + if( flattenSubquery(pParse, p, i, isAgg, isAggSub) ){ + if( isAggSub ){ + p->isAgg = isAgg = 1; + } + i = -1; + }else{ + sqlite3SelectDestInit(&dest, SRT_EphemTab, pItem->iCursor); + sqlite3Select(pParse, pSub, &dest, p, i, &isAgg); + } + if( pParse->nErr || db->mallocFailed ){ goto select_end; } pParse->nHeight -= sqlite3SelectExprHeight(p); - if( needRestoreContext ){ - pParse->zAuthContext = zSavedAuthContext; - } pTabList = p->pSrc; - pWhere = p->pWhere; if( !IgnorableOrderby(pDest) ){ pOrderBy = p->pOrderBy; } - pGroupBy = p->pGroupBy; - pHaving = p->pHaving; - isDistinct = p->isDistinct; + } + pEList = p->pEList; +#endif + pWhere = p->pWhere; + pGroupBy = p->pGroupBy; + pHaving = p->pHaving; + isDistinct = p->isDistinct; + +#ifndef SQLITE_OMIT_COMPOUND_SELECT + /* If there is are a sequence of queries, do the earlier ones first. + */ + if( p->pPrior ){ + if( p->pRightmost==0 ){ + Select *pLoop, *pRight = 0; + int cnt = 0; + int mxSelect; + for(pLoop=p; pLoop; pLoop=pLoop->pPrior, cnt++){ + pLoop->pRightmost = p; + pLoop->pNext = pRight; + pRight = pLoop; + } + mxSelect = db->aLimit[SQLITE_LIMIT_COMPOUND_SELECT]; + if( mxSelect && cnt>mxSelect ){ + sqlite3ErrorMsg(pParse, "too many terms in compound SELECT"); + return 1; + } + } + return multiSelect(pParse, p, pDest); } #endif - /* Check to see if this is a subquery that can be "flattened" into its parent. - ** If flattening is a possiblity, do so and return immediately. + /* If writing to memory or generating a set + ** only a single column may be output. */ -#ifndef SQLITE_OMIT_VIEW - if( pParent && pParentAgg && - flattenSubquery(db, pParent, parentTab, *pParentAgg, isAgg) ){ - if( isAgg ) *pParentAgg = 1; +#ifndef SQLITE_OMIT_SUBQUERY + if( checkForMultiColumnSelectError(pParse, pDest, pEList->nExpr) ){ goto select_end; } #endif @@ -66713,7 +70564,7 @@ SQLITE_PRIVATE int sqlite3Select( */ assert(!isDistinct); selectInnerLoop(pParse, p, pEList, 0, 0, pOrderBy, -1, pDest, - pWInfo->iContinue, pWInfo->iBreak, aff); + pWInfo->iContinue, pWInfo->iBreak); /* End the database scan loop. */ @@ -66733,14 +70584,14 @@ SQLITE_PRIVATE int sqlite3Select( /* The following variables hold addresses or labels for parts of the ** virtual machine program we are putting together */ int addrOutputRow; /* Start of subroutine that outputs a result row */ + int regOutputRow; /* Return address register for output subroutine */ int addrSetAbort; /* Set the abort flag and return */ int addrInitializeLoop; /* Start of code that initializes the input loop */ int addrTopOfLoop; /* Top of the input loop */ - int addrGroupByChange; /* Code that runs when any GROUP BY term changes */ - int addrProcessRow; /* Code to process a single input row */ int addrEnd; /* End of all processing */ int addrSortingIdx; /* The OP_OpenEphemeral for the sorting index */ int addrReset; /* Subroutine for resetting the accumulator */ + int regReset; /* Return address register for reset subroutine */ addrEnd = sqlite3VdbeMakeLabel(v); @@ -66770,13 +70621,11 @@ SQLITE_PRIVATE int sqlite3Select( */ if( pGroupBy ){ KeyInfo *pKeyInfo; /* Keying information for the group by clause */ + int j1; /* Create labels that we will be needing */ - addrInitializeLoop = sqlite3VdbeMakeLabel(v); - addrGroupByChange = sqlite3VdbeMakeLabel(v); - addrProcessRow = sqlite3VdbeMakeLabel(v); /* If there is a GROUP BY clause we might need a sorting index to ** implement it. Allocate that sorting index now. If it turns out @@ -66813,26 +70662,28 @@ SQLITE_PRIVATE int sqlite3Select( addrSetAbort = sqlite3VdbeCurrentAddr(v); sqlite3VdbeAddOp2(v, OP_Integer, 1, iAbortFlag); VdbeComment((v, "set abort flag")); - sqlite3VdbeAddOp2(v, OP_Return, 0, 0); + regOutputRow = ++pParse->nMem; + sqlite3VdbeAddOp1(v, OP_Return, regOutputRow); addrOutputRow = sqlite3VdbeCurrentAddr(v); sqlite3VdbeAddOp2(v, OP_IfPos, iUseFlag, addrOutputRow+2); VdbeComment((v, "Groupby result generator entry point")); - sqlite3VdbeAddOp2(v, OP_Return, 0, 0); + sqlite3VdbeAddOp1(v, OP_Return, regOutputRow); finalizeAggFunctions(pParse, &sAggInfo); if( pHaving ){ sqlite3ExprIfFalse(pParse, pHaving, addrOutputRow+1, SQLITE_JUMPIFNULL); } selectInnerLoop(pParse, p, p->pEList, 0, 0, pOrderBy, distinct, pDest, - addrOutputRow+1, addrSetAbort, aff); - sqlite3VdbeAddOp2(v, OP_Return, 0, 0); + addrOutputRow+1, addrSetAbort); + sqlite3VdbeAddOp1(v, OP_Return, regOutputRow); VdbeComment((v, "end groupby result generator")); /* Generate a subroutine that will reset the group-by accumulator */ addrReset = sqlite3VdbeCurrentAddr(v); + regReset = ++pParse->nMem; resetAccumulator(pParse, &sAggInfo); - sqlite3VdbeAddOp2(v, OP_Return, 0, 0); + sqlite3VdbeAddOp1(v, OP_Return, regReset); /* Begin a loop that will extract all source rows in GROUP BY order. ** This might involve two separate loops with an OP_Sort in between, or @@ -66840,7 +70691,7 @@ SQLITE_PRIVATE int sqlite3Select( ** in the right order to begin with. */ sqlite3VdbeResolveLabel(v, addrInitializeLoop); - sqlite3VdbeAddOp2(v, OP_Gosub, 0, addrReset); + sqlite3VdbeAddOp2(v, OP_Gosub, regReset, addrReset); pWInfo = sqlite3WhereBegin(pParse, pTabList, pWhere, &pGroupBy, 0); if( pWInfo==0 ) goto select_end; if( pGroupBy==0 ){ @@ -66879,12 +70730,20 @@ SQLITE_PRIVATE int sqlite3Select( struct AggInfo_col *pCol = &sAggInfo.aCol[i]; if( pCol->iSorterColumn>=j ){ int r1 = j + regBase; - int r2 = sqlite3ExprCodeGetColumn(pParse, +#ifndef NDEBUG + int r2 = +#endif + sqlite3ExprCodeGetColumn(pParse, pCol->pTab, pCol->iColumn, pCol->iTable, r1, 0); - if( r1!=r2 ){ - sqlite3VdbeAddOp2(v, OP_SCopy, r2, r1); - } j++; + + /* sAggInfo.aCol[] only contains one entry per column. So + ** The reference to pCol->iColumn,pCol->iTable must have been + ** the first reference to that column. Hence, + ** sqliteExprCodeGetColumn is guaranteed to put the result in + ** the column requested. + */ + assert( r1==r2 ); } } regRecord = sqlite3GetTempReg(pParse); @@ -66912,18 +70771,13 @@ SQLITE_PRIVATE int sqlite3Select( sqlite3ExprCode(pParse, pGroupBy->a[j].pExpr, iBMem+j); } } - for(j=pGroupBy->nExpr-1; j>=0; j--){ - if( j==0 ){ - sqlite3VdbeAddOp3(v, OP_Eq, iAMem+j, addrProcessRow, iBMem+j); - }else{ - sqlite3VdbeAddOp3(v, OP_Ne, iAMem+j, addrGroupByChange, iBMem+j); - } - sqlite3VdbeChangeP4(v, -1, (void*)pKeyInfo->aColl[j], P4_COLLSEQ); - sqlite3VdbeChangeP5(v, SQLITE_NULLEQUAL); - } + sqlite3VdbeAddOp4(v, OP_Compare, iAMem, iBMem, pGroupBy->nExpr, + (char*)pKeyInfo, P4_KEYINFO); + j1 = sqlite3VdbeCurrentAddr(v); + sqlite3VdbeAddOp3(v, OP_Jump, j1+1, 0, j1+1); /* Generate code that runs whenever the GROUP BY changes. - ** Change in the GROUP BY are detected by the previous code + ** Changes in the GROUP BY are detected by the previous code ** block. If there were no changes, this block is skipped. ** ** This code copies current group by terms in b0,b1,b2,... @@ -66931,21 +70785,18 @@ SQLITE_PRIVATE int sqlite3Select( ** and resets the aggregate accumulator registers in preparation ** for the next GROUP BY batch. */ - sqlite3VdbeResolveLabel(v, addrGroupByChange); - for(j=0; j<pGroupBy->nExpr; j++){ - sqlite3ExprCodeMove(pParse, iBMem+j, iAMem+j); - } - sqlite3VdbeAddOp2(v, OP_Gosub, 0, addrOutputRow); + sqlite3ExprCodeMove(pParse, iBMem, iAMem, pGroupBy->nExpr); + sqlite3VdbeAddOp2(v, OP_Gosub, regOutputRow, addrOutputRow); VdbeComment((v, "output one row")); sqlite3VdbeAddOp2(v, OP_IfPos, iAbortFlag, addrEnd); VdbeComment((v, "check abort flag")); - sqlite3VdbeAddOp2(v, OP_Gosub, 0, addrReset); + sqlite3VdbeAddOp2(v, OP_Gosub, regReset, addrReset); VdbeComment((v, "reset accumulator")); /* Update the aggregate accumulators based on the content of ** the current row */ - sqlite3VdbeResolveLabel(v, addrProcessRow); + sqlite3VdbeJumpHere(v, j1); updateAccumulator(pParse, &sAggInfo); sqlite3VdbeAddOp2(v, OP_Integer, 1, iUseFlag); VdbeComment((v, "indicate data in accumulator")); @@ -66961,7 +70812,7 @@ SQLITE_PRIVATE int sqlite3Select( /* Output the final row of result */ - sqlite3VdbeAddOp2(v, OP_Gosub, 0, addrOutputRow); + sqlite3VdbeAddOp2(v, OP_Gosub, regOutputRow, addrOutputRow); VdbeComment((v, "output final row")); } /* endif pGroupBy */ @@ -66999,7 +70850,7 @@ SQLITE_PRIVATE int sqlite3Select( if( flag ){ pDel = pMinMax = sqlite3ExprListDup(db, p->pEList->a[0].pExpr->pList); if( pMinMax && !db->mallocFailed ){ - pMinMax->a[0].sortOrder = ((flag==WHERE_ORDERBY_MIN)?0:1); + pMinMax->a[0].sortOrder = flag!=WHERE_ORDERBY_MIN; pMinMax->a[0].pExpr->op = TK_COLUMN; } } @@ -67011,13 +70862,13 @@ SQLITE_PRIVATE int sqlite3Select( resetAccumulator(pParse, &sAggInfo); pWInfo = sqlite3WhereBegin(pParse, pTabList, pWhere, &pMinMax, flag); if( pWInfo==0 ){ - sqlite3ExprListDelete(pDel); + sqlite3ExprListDelete(db, pDel); goto select_end; } updateAccumulator(pParse, &sAggInfo); if( !pMinMax && flag ){ sqlite3VdbeAddOp2(v, OP_Goto, 0, pWInfo->iBreak); - VdbeComment((v, "%s() by index", (flag==WHERE_ORDERBY_MIN?"min":"max"))); + VdbeComment((v, "%s() by index",(flag==WHERE_ORDERBY_MIN?"min":"max"))); } sqlite3WhereEnd(pWInfo); finalizeAggFunctions(pParse, &sAggInfo); @@ -67026,9 +70877,9 @@ SQLITE_PRIVATE int sqlite3Select( sqlite3ExprIfFalse(pParse, pHaving, addrEnd, SQLITE_JUMPIFNULL); } selectInnerLoop(pParse, p, p->pEList, 0, 0, 0, -1, - pDest, addrEnd, addrEnd, aff); + pDest, addrEnd, addrEnd); - sqlite3ExprListDelete(pDel); + sqlite3ExprListDelete(db, pDel); } sqlite3VdbeResolveLabel(v, addrEnd); @@ -67075,8 +70926,8 @@ select_end: generateColumnNames(pParse, pTabList, pEList); } - sqlite3_free(sAggInfo.aCol); - sqlite3_free(sAggInfo.aFunc); + sqlite3DbFree(db, sAggInfo.aCol); + sqlite3DbFree(db, sAggInfo.aFunc); return rc; } @@ -67195,6 +71046,8 @@ SQLITE_PRIVATE void sqlite3PrintSelect(Select *p, int indent){ ** ** These routines are in a separate files so that they will not be linked ** if they are not used. +** +** $Id$ */ #ifndef SQLITE_OMIT_GET_TABLE @@ -67322,7 +71175,7 @@ SQLITE_API int sqlite3_get_table( res.azResult[0] = 0; rc = sqlite3_exec(db, zSql, sqlite3_get_table_cb, &res, pzErrMsg); assert( sizeof(res.azResult[0])>= sizeof(res.nData) ); - res.azResult[0] = (char*)res.nData; + res.azResult[0] = SQLITE_INT_TO_PTR(res.nData); if( (rc&0xff)==SQLITE_ABORT ){ sqlite3_free_table(&res.azResult[1]); if( res.zErrMsg ){ @@ -67367,7 +71220,7 @@ SQLITE_API void sqlite3_free_table( int i, n; azResult--; assert( azResult!=0 ); - n = (int)azResult[0]; + n = SQLITE_PTR_TO_INT(azResult[0]); for(i=1; i<n; i++){ if( azResult[i] ) sqlite3_free(azResult[i]); } sqlite3_free(azResult); } @@ -67387,25 +71240,27 @@ SQLITE_API void sqlite3_free_table( ** May you share freely, never taking more than you give. ** ************************************************************************* -* +** +** +** $Id$ */ #ifndef SQLITE_OMIT_TRIGGER /* ** Delete a linked list of TriggerStep structures. */ -SQLITE_PRIVATE void sqlite3DeleteTriggerStep(TriggerStep *pTriggerStep){ +SQLITE_PRIVATE void sqlite3DeleteTriggerStep(sqlite3 *db, TriggerStep *pTriggerStep){ while( pTriggerStep ){ TriggerStep * pTmp = pTriggerStep; pTriggerStep = pTriggerStep->pNext; - if( pTmp->target.dyn ) sqlite3_free((char*)pTmp->target.z); - sqlite3ExprDelete(pTmp->pWhere); - sqlite3ExprListDelete(pTmp->pExprList); - sqlite3SelectDelete(pTmp->pSelect); - sqlite3IdListDelete(pTmp->pIdList); + if( pTmp->target.dyn ) sqlite3DbFree(db, (char*)pTmp->target.z); + sqlite3ExprDelete(db, pTmp->pWhere); + sqlite3ExprListDelete(db, pTmp->pExprList); + sqlite3SelectDelete(db, pTmp->pSelect); + sqlite3IdListDelete(db, pTmp->pIdList); - sqlite3_free(pTmp); + sqlite3DbFree(db, pTmp); } } @@ -67562,12 +71417,12 @@ SQLITE_PRIVATE void sqlite3BeginTrigger( pParse->pNewTrigger = pTrigger; trigger_cleanup: - sqlite3_free(zName); - sqlite3SrcListDelete(pTableName); - sqlite3IdListDelete(pColumns); - sqlite3ExprDelete(pWhen); + sqlite3DbFree(db, zName); + sqlite3SrcListDelete(db, pTableName); + sqlite3IdListDelete(db, pColumns); + sqlite3ExprDelete(db, pWhen); if( !pParse->pNewTrigger ){ - sqlite3DeleteTrigger(pTrigger); + sqlite3DeleteTrigger(db, pTrigger); }else{ assert( pParse->pNewTrigger==pTrigger ); } @@ -67617,7 +71472,7 @@ SQLITE_PRIVATE void sqlite3FinishTrigger( "INSERT INTO %Q.%s VALUES('trigger',%Q,%Q,0,'CREATE TRIGGER %q')", db->aDb[iDb].zName, SCHEMA_TABLE(iDb), pTrig->name, pTrig->table, z); - sqlite3_free(z); + sqlite3DbFree(db, z); sqlite3ChangeCookie(pParse, iDb); sqlite3VdbeAddOp4(v, OP_ParseSchema, iDb, 0, 0, sqlite3MPrintf( db, "type='trigger' AND name='%q'", pTrig->name), P4_DYNAMIC @@ -67644,9 +71499,9 @@ SQLITE_PRIVATE void sqlite3FinishTrigger( } triggerfinish_cleanup: - sqlite3DeleteTrigger(pTrig); + sqlite3DeleteTrigger(db, pTrig); assert( !pParse->pNewTrigger ); - sqlite3DeleteTriggerStep(pStepList); + sqlite3DeleteTriggerStep(db, pStepList); } /* @@ -67666,22 +71521,22 @@ static void sqlitePersistTriggerStep(sqlite3 *db, TriggerStep *p){ } if( p->pSelect ){ Select *pNew = sqlite3SelectDup(db, p->pSelect); - sqlite3SelectDelete(p->pSelect); + sqlite3SelectDelete(db, p->pSelect); p->pSelect = pNew; } if( p->pWhere ){ Expr *pNew = sqlite3ExprDup(db, p->pWhere); - sqlite3ExprDelete(p->pWhere); + sqlite3ExprDelete(db, p->pWhere); p->pWhere = pNew; } if( p->pExprList ){ ExprList *pNew = sqlite3ExprListDup(db, p->pExprList); - sqlite3ExprListDelete(p->pExprList); + sqlite3ExprListDelete(db, p->pExprList); p->pExprList = pNew; } if( p->pIdList ){ IdList *pNew = sqlite3IdListDup(db, p->pIdList); - sqlite3IdListDelete(p->pIdList); + sqlite3IdListDelete(db, p->pIdList); p->pIdList = pNew; } } @@ -67696,7 +71551,7 @@ static void sqlitePersistTriggerStep(sqlite3 *db, TriggerStep *p){ SQLITE_PRIVATE TriggerStep *sqlite3TriggerSelectStep(sqlite3 *db, Select *pSelect){ TriggerStep *pTriggerStep = sqlite3DbMallocZero(db, sizeof(TriggerStep)); if( pTriggerStep==0 ) { - sqlite3SelectDelete(pSelect); + sqlite3SelectDelete(db, pSelect); return 0; } @@ -67738,9 +71593,9 @@ SQLITE_PRIVATE TriggerStep *sqlite3TriggerInsertStep( pTriggerStep->orconf = orconf; sqlitePersistTriggerStep(db, pTriggerStep); }else{ - sqlite3IdListDelete(pColumn); - sqlite3ExprListDelete(pEList); - sqlite3SelectDelete(pSelect); + sqlite3IdListDelete(db, pColumn); + sqlite3ExprListDelete(db, pEList); + sqlite3SelectDelete(db, pSelect); } return pTriggerStep; @@ -67760,8 +71615,8 @@ SQLITE_PRIVATE TriggerStep *sqlite3TriggerUpdateStep( ){ TriggerStep *pTriggerStep = sqlite3DbMallocZero(db, sizeof(TriggerStep)); if( pTriggerStep==0 ){ - sqlite3ExprListDelete(pEList); - sqlite3ExprDelete(pWhere); + sqlite3ExprListDelete(db, pEList); + sqlite3ExprDelete(db, pWhere); return 0; } @@ -67787,7 +71642,7 @@ SQLITE_PRIVATE TriggerStep *sqlite3TriggerDeleteStep( ){ TriggerStep *pTriggerStep = sqlite3DbMallocZero(db, sizeof(TriggerStep)); if( pTriggerStep==0 ){ - sqlite3ExprDelete(pWhere); + sqlite3ExprDelete(db, pWhere); return 0; } @@ -67803,15 +71658,15 @@ SQLITE_PRIVATE TriggerStep *sqlite3TriggerDeleteStep( /* ** Recursively delete a Trigger structure */ -SQLITE_PRIVATE void sqlite3DeleteTrigger(Trigger *pTrigger){ +SQLITE_PRIVATE void sqlite3DeleteTrigger(sqlite3 *db, Trigger *pTrigger){ if( pTrigger==0 ) return; - sqlite3DeleteTriggerStep(pTrigger->step_list); - sqlite3_free(pTrigger->name); - sqlite3_free(pTrigger->table); - sqlite3ExprDelete(pTrigger->pWhen); - sqlite3IdListDelete(pTrigger->pColumns); - if( pTrigger->nameToken.dyn ) sqlite3_free((char*)pTrigger->nameToken.z); - sqlite3_free(pTrigger); + sqlite3DeleteTriggerStep(db, pTrigger->step_list); + sqlite3DbFree(db, pTrigger->name); + sqlite3DbFree(db, pTrigger->table); + sqlite3ExprDelete(db, pTrigger->pWhen); + sqlite3IdListDelete(db, pTrigger->pColumns); + if( pTrigger->nameToken.dyn ) sqlite3DbFree(db, (char*)pTrigger->nameToken.z); + sqlite3DbFree(db, pTrigger); } /* @@ -67854,7 +71709,7 @@ SQLITE_PRIVATE void sqlite3DropTrigger(Parse *pParse, SrcList *pName, int noErr) sqlite3DropTriggerPtr(pParse, pTrigger); drop_trigger_cleanup: - sqlite3SrcListDelete(pName); + sqlite3SrcListDelete(db, pName); } /* @@ -67946,7 +71801,7 @@ SQLITE_PRIVATE void sqlite3UnlinkAndDeleteTrigger(sqlite3 *db, int iDb, const ch } assert(cc); } - sqlite3DeleteTrigger(pTrigger); + sqlite3DeleteTrigger(db, pTrigger); db->flags |= SQLITE_InternChanges; } } @@ -68056,8 +71911,8 @@ static int codeTriggerProgram( sqlite3SelectDestInit(&dest, SRT_Discard, 0); sqlite3SelectResolve(pParse, ss, 0); - sqlite3Select(pParse, ss, &dest, 0, 0, 0, 0); - sqlite3SelectDelete(ss); + sqlite3Select(pParse, ss, &dest, 0, 0, 0); + sqlite3SelectDelete(db, ss); } break; } @@ -68207,11 +72062,11 @@ SQLITE_PRIVATE int sqlite3CodeRowTrigger( whenExpr = sqlite3ExprDup(db, p->pWhen); if( db->mallocFailed || sqlite3ExprResolveNames(&sNC, whenExpr) ){ pParse->trigStack = trigStackEntry.pNext; - sqlite3ExprDelete(whenExpr); + sqlite3ExprDelete(db, whenExpr); return 1; } sqlite3ExprIfFalse(pParse, whenExpr, endTrigger, SQLITE_JUMPIFNULL); - sqlite3ExprDelete(whenExpr); + sqlite3ExprDelete(db, whenExpr); codeTriggerProgram(pParse, p->step_list, orconf); @@ -68689,7 +72544,7 @@ SQLITE_PRIVATE void sqlite3Update( sqlite3ExprCacheAffinityChange(pParse, regCols, pTab->nCol); } sqlite3ReleaseTempRange(pParse, regCols, pTab->nCol); - if( pParse->nErr ) goto update_cleanup; + /* if( pParse->nErr ) goto update_cleanup; */ sqlite3VdbeAddOp3(v, OP_Insert, newIdx, regRow, regRowid); sqlite3ReleaseTempReg(pParse, regRowid); sqlite3ReleaseTempReg(pParse, regRow); @@ -68801,11 +72656,11 @@ SQLITE_PRIVATE void sqlite3Update( update_cleanup: sqlite3AuthContextPop(&sContext); - sqlite3_free(aRegIdx); - sqlite3_free(aXRef); - sqlite3SrcListDelete(pTabList); - sqlite3ExprListDelete(pChanges); - sqlite3ExprDelete(pWhere); + sqlite3DbFree(db, aRegIdx); + sqlite3DbFree(db, aXRef); + sqlite3SrcListDelete(db, pTabList); + sqlite3ExprListDelete(db, pChanges); + sqlite3ExprDelete(db, pWhere); return; } @@ -68880,7 +72735,7 @@ static void updateVirtualTable( /* fill the ephemeral table */ sqlite3SelectDestInit(&dest, SRT_Table, ephemTab); - sqlite3Select(pParse, pSelect, &dest, 0, 0, 0, 0); + sqlite3Select(pParse, pSelect, &dest, 0, 0, 0); /* Generate code to scan the ephemeral table and call VUpdate. */ iReg = ++pParse->nMem; @@ -68899,7 +72754,7 @@ static void updateVirtualTable( sqlite3VdbeAddOp2(v, OP_Close, ephemTab, 0); /* Cleanup */ - sqlite3SelectDelete(pSelect); + sqlite3SelectDelete(db, pSelect); } #endif /* SQLITE_OMIT_VIRTUALTABLE */ @@ -68994,16 +72849,19 @@ SQLITE_PRIVATE int sqlite3RunVacuum(char **pzErrMsg, sqlite3 *db){ Btree *pTemp; /* The temporary database we vacuum into */ char *zSql = 0; /* SQL statements */ int saved_flags; /* Saved value of the db->flags */ + int saved_nChange; /* Saved value of db->nChange */ + int saved_nTotalChange; /* Saved value of db->nTotalChange */ Db *pDb = 0; /* Database to detach at end of vacuum */ int nRes; /* Save the current value of the write-schema flag before setting it. */ saved_flags = db->flags; + saved_nChange = db->nChange; + saved_nTotalChange = db->nTotalChange; db->flags |= SQLITE_WriteSchema | SQLITE_IgnoreChecks; if( !db->autoCommit ){ - sqlite3SetString(pzErrMsg, "cannot VACUUM from within a transaction", - (char*)0); + sqlite3SetString(pzErrMsg, db, "cannot VACUUM from within a transaction"); rc = SQLITE_ERROR; goto end_of_vacuum; } @@ -69031,6 +72889,18 @@ SQLITE_PRIVATE int sqlite3RunVacuum(char **pzErrMsg, sqlite3 *db){ pTemp = db->aDb[db->nDb-1].pBt; nRes = sqlite3BtreeGetReserve(pMain); + + /* A VACUUM cannot change the pagesize of an encrypted database. */ +#ifdef SQLITE_HAS_CODEC + if( db->nextPagesize ){ + extern void sqlite3CodecGetKey(sqlite3*, int, void**, int*); + int nKey; + char *zKey; + sqlite3CodecGetKey(db, 0, (void**)&zKey, &nKey); + if( nKey ) db->nextPagesize = 0; + } +#endif + if( sqlite3BtreeSetPageSize(pTemp, sqlite3BtreeGetPageSize(pMain), nRes) || sqlite3BtreeSetPageSize(pTemp, db->nextPagesize, nRes) || db->mallocFailed @@ -69163,6 +73033,8 @@ SQLITE_PRIVATE int sqlite3RunVacuum(char **pzErrMsg, sqlite3 *db){ end_of_vacuum: /* Restore the original value of db->flags */ db->flags = saved_flags; + db->nChange = saved_nChange; + db->nTotalChange = saved_nTotalChange; /* Currently there is an SQL level transaction open on the vacuum ** database. No locks are held on any other files (since the main file @@ -69218,17 +73090,21 @@ static int createModule( nName = strlen(zName); pMod = (Module *)sqlite3DbMallocRaw(db, sizeof(Module) + nName + 1); if( pMod ){ + Module *pDel; char *zCopy = (char *)(&pMod[1]); memcpy(zCopy, zName, nName+1); pMod->zName = zCopy; pMod->pModule = pModule; pMod->pAux = pAux; pMod->xDestroy = xDestroy; - pMod = (Module *)sqlite3HashInsert(&db->aModule, zCopy, nName, (void*)pMod); - if( pMod && pMod->xDestroy ){ - pMod->xDestroy(pMod->pAux); + pDel = (Module *)sqlite3HashInsert(&db->aModule, zCopy, nName, (void*)pMod); + if( pDel && pDel->xDestroy ){ + pDel->xDestroy(pDel->pAux); + } + sqlite3DbFree(db, pDel); + if( pDel==pMod ){ + db->mallocFailed = 1; } - sqlite3_free(pMod); sqlite3ResetInternalSchema(db, 0); } rc = sqlite3ApiExit(db, SQLITE_OK); @@ -69300,17 +73176,18 @@ SQLITE_PRIVATE void sqlite3VtabUnlock(sqlite3 *db, sqlite3_vtab *pVtab){ */ SQLITE_PRIVATE void sqlite3VtabClear(Table *p){ sqlite3_vtab *pVtab = p->pVtab; + sqlite3 *db = p->db; if( pVtab ){ assert( p->pMod && p->pMod->pModule ); - sqlite3VtabUnlock(p->pSchema->db, pVtab); + sqlite3VtabUnlock(db, pVtab); p->pVtab = 0; } if( p->azModuleArg ){ int i; for(i=0; i<p->nModuleArg; i++){ - sqlite3_free(p->azModuleArg[i]); + sqlite3DbFree(db, p->azModuleArg[i]); } - sqlite3_free(p->azModuleArg); + sqlite3DbFree(db, p->azModuleArg); } } @@ -69328,10 +73205,10 @@ static void addModuleArgument(sqlite3 *db, Table *pTable, char *zArg){ if( azModuleArg==0 ){ int j; for(j=0; j<i; j++){ - sqlite3_free(pTable->azModuleArg[j]); + sqlite3DbFree(db, pTable->azModuleArg[j]); } - sqlite3_free(zArg); - sqlite3_free(pTable->azModuleArg); + sqlite3DbFree(db, zArg); + sqlite3DbFree(db, pTable->azModuleArg); pTable->nModuleArg = 0; }else{ azModuleArg[i] = zArg; @@ -69462,7 +73339,7 @@ SQLITE_PRIVATE void sqlite3VtabFinishParse(Parse *pParse, Token *pEnd){ zStmt, pParse->regRowid ); - sqlite3_free(zStmt); + sqlite3DbFree(db, zStmt); v = sqlite3GetVdbe(pParse); sqlite3ChangeCookie(pParse, iDb); @@ -69561,7 +73438,7 @@ static int vtabCallConstructor( *pzErr = sqlite3MPrintf(db, "vtable constructor failed: %s", zModuleName); }else { *pzErr = sqlite3MPrintf(db, "%s", zErr); - sqlite3_free(zErr); + sqlite3DbFree(db, zErr); } }else if( db->pVTab ){ const char *zFormat = "vtable constructor did not declare schema: %s"; @@ -69572,7 +73449,7 @@ static int vtabCallConstructor( rc = rc2; } db->pVTab = 0; - sqlite3_free(zModuleName); + sqlite3DbFree(db, zModuleName); /* If everything went according to plan, loop through the columns ** of the table to see if any of them contain the token "hidden". @@ -69641,7 +73518,7 @@ SQLITE_PRIVATE int sqlite3VtabCallConnect(Parse *pParse, Table *pTab){ if( rc!=SQLITE_OK ){ sqlite3ErrorMsg(pParse, "%s", zErr); } - sqlite3_free(zErr); + sqlite3DbFree(db, zErr); } return rc; @@ -69677,7 +73554,7 @@ static int addToVTrans(sqlite3 *db, sqlite3_vtab *pVtab){ ** ** If an error occurs, *pzErr is set to point an an English language ** description of the error and an SQLITE_XXX error code is returned. -** In this case the caller must call sqlite3_free() on *pzErr. +** In this case the caller must call sqlite3DbFree(db, ) on *pzErr. */ SQLITE_PRIVATE int sqlite3VtabCallCreate(sqlite3 *db, int iDb, const char *zTab, char **pzErr){ int rc = SQLITE_OK; @@ -69746,7 +73623,7 @@ SQLITE_API int sqlite3_declare_vtab(sqlite3 *db, const char *zCreateTable){ db->pVTab = 0; } else { sqlite3Error(db, SQLITE_ERROR, zErr); - sqlite3_free(zErr); + sqlite3DbFree(db, zErr); rc = SQLITE_ERROR; } sParse.declareVtab = 0; @@ -69816,24 +73693,25 @@ static void callFinaliser(sqlite3 *db, int offset){ if( x ) x(pVtab); sqlite3VtabUnlock(db, pVtab); } - sqlite3_free(db->aVTrans); + sqlite3DbFree(db, db->aVTrans); db->nVTrans = 0; db->aVTrans = 0; } } /* -** If argument rc2 is not SQLITE_OK, then return it and do nothing. -** Otherwise, invoke the xSync method of all virtual tables in the -** sqlite3.aVTrans array. Return the error code for the first error -** that occurs, or SQLITE_OK if all xSync operations are successful. +** Invoke the xSync method of all virtual tables in the sqlite3.aVTrans +** array. Return the error code for the first error that occurs, or +** SQLITE_OK if all xSync operations are successful. +** +** Set *pzErrmsg to point to a buffer that should be released using +** sqlite3DbFree() containing an error message, if one is available. */ -SQLITE_PRIVATE int sqlite3VtabSync(sqlite3 *db, int rc2){ +SQLITE_PRIVATE int sqlite3VtabSync(sqlite3 *db, char **pzErrmsg){ int i; int rc = SQLITE_OK; int rcsafety; sqlite3_vtab **aVTrans = db->aVTrans; - if( rc2!=SQLITE_OK ) return rc2; rc = sqlite3SafetyOff(db); db->aVTrans = 0; @@ -69843,6 +73721,9 @@ SQLITE_PRIVATE int sqlite3VtabSync(sqlite3 *db, int rc2){ x = pVtab->pModule->xSync; if( x ){ rc = x(pVtab); + sqlite3DbFree(db, *pzErrmsg); + *pzErrmsg = pVtab->zErrMsg; + pVtab->zErrMsg = 0; } } db->aVTrans = aVTrans; @@ -69910,11 +73791,9 @@ SQLITE_PRIVATE int sqlite3VtabBegin(sqlite3 *db, sqlite3_vtab *pVtab){ /* Invoke the xBegin method */ rc = pModule->xBegin(pVtab); - if( rc!=SQLITE_OK ){ - return rc; + if( rc==SQLITE_OK ){ + rc = addToVTrans(db, pVtab); } - - rc = addToVTrans(db, pVtab); } return rc; } @@ -69970,7 +73849,12 @@ SQLITE_PRIVATE FuncDef *sqlite3VtabOverloadFunction( *z = sqlite3UpperToLower[*z]; } rc = pMod->xFindFunction(pVtab, nArg, zLowerName, &xFunc, &pArg); - sqlite3_free(zLowerName); + sqlite3DbFree(db, zLowerName); + if( pVtab->zErrMsg ){ + sqlite3Error(db, rc, "%s", pVtab->zErrMsg); + sqlite3DbFree(db, pVtab->zErrMsg); + pVtab->zErrMsg = 0; + } } if( rc==0 ){ return pDef; @@ -70027,7 +73911,7 @@ SQLITE_PRIVATE void sqlite3VtabMakeWritable(Parse *pParse, Table *pTab){ ** ************************************************************************* ** This module contains C code that generates VDBE code used to process -** the WHERE clause of SQL statements. This module is reponsible for +** the WHERE clause of SQL statements. This module is responsible for ** generating the code that loops through a table looking for applicable ** rows. Indices are selected and used to speed the search when doing ** so is applicable. Because this module is responsible for selecting @@ -70046,6 +73930,8 @@ SQLITE_PRIVATE void sqlite3VtabMakeWritable(Parse *pParse, Table *pTab){ */ #if defined(SQLITE_TEST) || defined(SQLITE_DEBUG) SQLITE_PRIVATE int sqlite3WhereTrace = 0; +#endif +#if 0 # define WHERETRACE(X) if(sqlite3WhereTrace) sqlite3DebugPrintf X #else # define WHERETRACE(X) @@ -70106,7 +73992,7 @@ struct WhereTerm { /* ** Allowed values of WhereTerm.flags */ -#define TERM_DYNAMIC 0x01 /* Need to call sqlite3ExprDelete(pExpr) */ +#define TERM_DYNAMIC 0x01 /* Need to call sqlite3ExprDelete(db, pExpr) */ #define TERM_VIRTUAL 0x02 /* Added by the optimizer. Do not code */ #define TERM_CODED 0x04 /* This term is already coded */ #define TERM_COPIED 0x08 /* Has a child */ @@ -70217,13 +74103,14 @@ static void whereClauseInit( static void whereClauseClear(WhereClause *pWC){ int i; WhereTerm *a; + sqlite3 *db = pWC->pParse->db; for(i=pWC->nTerm-1, a=pWC->a; i>=0; i--, a++){ if( a->flags & TERM_DYNAMIC ){ - sqlite3ExprDelete(a->pExpr); + sqlite3ExprDelete(db, a->pExpr); } } if( pWC->a!=pWC->aStatic ){ - sqlite3_free(pWC->a); + sqlite3DbFree(db, pWC->a); } } @@ -70235,7 +74122,7 @@ static void whereClauseClear(WhereClause *pWC){ ** for freeing the expression p is assumed by the WhereClause object. ** ** WARNING: This routine might reallocate the space used to store -** WhereTerms. All pointers to WhereTerms should be invalided after +** WhereTerms. All pointers to WhereTerms should be invalidated after ** calling this routine. Such pointers may be reinitialized by referencing ** the pWC->a[] array. */ @@ -70244,18 +74131,18 @@ static int whereClauseInsert(WhereClause *pWC, Expr *p, int flags){ int idx; if( pWC->nTerm>=pWC->nSlot ){ WhereTerm *pOld = pWC->a; - pWC->a = sqlite3_malloc( sizeof(pWC->a[0])*pWC->nSlot*2 ); + sqlite3 *db = pWC->pParse->db; + pWC->a = sqlite3DbMallocRaw(db, sizeof(pWC->a[0])*pWC->nSlot*2 ); if( pWC->a==0 ){ - pWC->pParse->db->mallocFailed = 1; if( flags & TERM_DYNAMIC ){ - sqlite3ExprDelete(p); + sqlite3ExprDelete(db, p); } pWC->a = pOld; return 0; } memcpy(pWC->a, pOld, sizeof(pWC->a[0])*pWC->nTerm); if( pOld!=pWC->aStatic ){ - sqlite3_free(pOld); + sqlite3DbFree(db, pOld); } pWC->nSlot *= 2; } @@ -70398,7 +74285,7 @@ static int allowedOp(int op){ #define SWAP(TYPE,A,B) {TYPE t=A; A=B; B=t;} /* -** Commute a comparision operator. Expressions of the form "X op Y" +** Commute a comparison operator. Expressions of the form "X op Y" ** are converted into "Y op X". ** ** If a collation sequence is associated with either the left or right @@ -70466,13 +74353,14 @@ static WhereTerm *findTerm( ){ WhereTerm *pTerm; int k; + assert( iCur>=0 ); for(pTerm=pWC->a, k=pWC->nTerm; k; k--, pTerm++){ if( pTerm->leftCursor==iCur && (pTerm->prereqRight & notReady)==0 && pTerm->leftColumn==iColumn && (pTerm->eOperator & op)!=0 ){ - if( iCur>=0 && pIdx && pTerm->eOperator!=WO_ISNULL ){ + if( pIdx && pTerm->eOperator!=WO_ISNULL ){ Expr *pX = pTerm->pExpr; CollSeq *pColl; char idxaff; @@ -70492,8 +74380,9 @@ static WhereTerm *findTerm( pColl = pParse->db->pDfltColl; } - for(j=0; j<pIdx->nColumn && pIdx->aiColumn[j]!=iColumn; j++){} - assert( j<pIdx->nColumn ); + for(j=0; pIdx->aiColumn[j]!=iColumn; j++){ + if( NEVER(j>=pIdx->nColumn) ) return 0; + } if( sqlite3StrICmp(pColl->zName, pIdx->azColl[j]) ) continue; } return pTerm; @@ -70637,7 +74526,7 @@ static void transferJoinMarkings(Expr *pDerived, Expr *pBase){ ** a=<expr1> OR a=<expr2> OR b=<expr3> OR ... ** ** The pOrTerm input to this routine corresponds to a single term of -** this OR clause. In order for the term to be a condidate for +** this OR clause. In order for the term to be a candidate for ** conversion to an IN operator, the following must be true: ** ** * The left-hand side of the term must be the column which @@ -70692,7 +74581,7 @@ static int orTermIsOptCandidate(WhereTerm *pOrTerm, int iCursor, int iColumn){ ** This routine merely checks to see if pOrTerm has a duplicate that ** might qualify. If there is a duplicate that has not yet been ** disqualified, then return true. If there are no duplicates, or -** the duplicate has also been disqualifed, return false. +** the duplicate has also been disqualified, return false. */ static int orTermHasOkDuplicate(WhereClause *pOr, WhereTerm *pOrTerm){ if( pOrTerm->flags & TERM_COPIED ){ @@ -70785,7 +74674,7 @@ static void exprAnalyze( int idxNew; pDup = sqlite3ExprDup(db, pExpr); if( db->mallocFailed ){ - sqlite3ExprDelete(pDup); + sqlite3ExprDelete(db, pDup); return; } idxNew = whereClauseInsert(pWC, pDup, TERM_VIRTUAL|TERM_DYNAMIC); @@ -70882,7 +74771,7 @@ static void exprAnalyze( ExprList *pList = 0; Expr *pNew, *pDup; Expr *pLeft = 0; - for(i=sOr.nTerm-1, pOrTerm=sOr.a; i>=0 && ok; i--, pOrTerm++){ + for(i=sOr.nTerm-1, pOrTerm=sOr.a; i>=0; i--, pOrTerm++){ if( (pOrTerm->flags & TERM_OR_OK)==0 ) continue; pDup = sqlite3ExprDup(db, pOrTerm->pExpr->pRight); pList = sqlite3ExprListAppend(pWC->pParse, pList, pDup, 0); @@ -70901,7 +74790,7 @@ static void exprAnalyze( pWC->a[idxNew].iParent = idxTerm; pTerm->nChild = 1; }else{ - sqlite3ExprListDelete(pList); + sqlite3ExprListDelete(db, pList); } } or_not_possible: @@ -70918,8 +74807,7 @@ or_not_possible: ** x>='abc' AND x<'abd' AND x LIKE 'abc%' ** ** The last character of the prefix "abc" is incremented to form the - ** termination condidtion "abd". This trick of incrementing the last - ** is not 255 and if the character set is not EBCDIC. + ** termination condition "abd". */ if( isLikeOrGlob(db, pExpr, &nPattern, &isComplete, &noCase) ){ Expr *pLeft, *pRight; @@ -70941,7 +74829,10 @@ or_not_possible: assert( pStr2->token.dyn ); pC = (u8*)&pStr2->token.z[nPattern-1]; c = *pC; - if( noCase ) c = sqlite3UpperToLower[c]; + if( noCase ){ + if( c=='@' ) isComplete = 0; + c = sqlite3UpperToLower[c]; + } *pC = c + 1; } pNewExpr1 = sqlite3PExpr(pParse, TK_GE, sqlite3ExprDup(db,pLeft), pStr1, 0); @@ -71103,6 +74994,9 @@ static int isSortingIndex( ** ORDER BY term, that is OK. Just ignore that column of the index */ continue; + }else if( i==pIdx->nColumn ){ + /* Index column i is the rowid. All other terms match. */ + break; }else{ /* If an index column fails to match and is not constrained by == ** then the index cannot satisfy the ORDER BY constraint. @@ -71180,7 +75074,7 @@ static int sortableByRowid( /* ** Prepare a crude estimate of the logarithm of the input value. ** The results need not be exact. This is only used for estimating -** the total cost of performing operatings with O(logN) or O(NlogN) +** the total cost of performing operations with O(logN) or O(NlogN) ** complexity. Because N is just a guess, it is no great tragedy if ** logN is a little off. */ @@ -71265,6 +75159,7 @@ static double bestVirtualIndex( sqlite3_index_info **ppIdxInfo /* Index information passed to xBestIndex */ ){ Table *pTab = pSrc->pTab; + sqlite3_vtab *pVtab = pTab->pVtab; sqlite3_index_info *pIdxInfo; struct sqlite3_index_constraint *pIdxCons; struct sqlite3_index_orderby *pIdxOrderBy; @@ -71376,7 +75271,7 @@ static double bestVirtualIndex( ** sqlite3ViewGetColumnNames() would have picked up the error. */ assert( pTab->azModuleArg && pTab->azModuleArg[0] ); - assert( pTab->pVtab ); + assert( pVtab ); #if 0 if( pTab->pVtab==0 ){ sqlite3ErrorMsg(pParse, "undefined module %s for table %s", @@ -71429,10 +75324,22 @@ static double bestVirtualIndex( (void)sqlite3SafetyOff(pParse->db); WHERETRACE(("xBestIndex for %s\n", pTab->zName)); TRACE_IDX_INPUTS(pIdxInfo); - rc = pTab->pVtab->pModule->xBestIndex(pTab->pVtab, pIdxInfo); + rc = pVtab->pModule->xBestIndex(pVtab, pIdxInfo); TRACE_IDX_OUTPUTS(pIdxInfo); (void)sqlite3SafetyOn(pParse->db); + if( rc!=SQLITE_OK ){ + if( rc==SQLITE_NOMEM ){ + pParse->db->mallocFailed = 1; + }else if( !pVtab->zErrMsg ){ + sqlite3ErrorMsg(pParse, "%s", sqlite3ErrStr(rc)); + }else{ + sqlite3ErrorMsg(pParse, "%s", pVtab->zErrMsg); + } + } + sqlite3DbFree(pParse->db, pVtab->zErrMsg); + pVtab->zErrMsg = 0; + for(i=0; i<pIdxInfo->nConstraint; i++){ if( !pIdxInfo->aConstraint[i].usable && pUsage[i].argvIndex>0 ){ sqlite3ErrorMsg(pParse, @@ -71441,15 +75348,7 @@ static double bestVirtualIndex( } } - if( rc!=SQLITE_OK ){ - if( rc==SQLITE_NOMEM ){ - pParse->db->mallocFailed = 1; - }else { - sqlite3ErrorMsg(pParse, "%s", sqlite3ErrStr(rc)); - } - } *(int*)&pIdxInfo->nOrderBy = nOrderBy; - return pIdxInfo->estimatedCost; } #endif /* SQLITE_OMIT_VIRTUALTABLE */ @@ -71495,7 +75394,7 @@ static double bestIndex( int eqTermMask; /* Mask of valid equality operators */ double cost; /* Cost of using pProbe */ - WHERETRACE(("bestIndex: tbl=%s notReady=%x\n", pSrc->pTab->zName, notReady)); + WHERETRACE(("bestIndex: tbl=%s notReady=%llx\n", pSrc->pTab->zName, notReady)); lowestCost = SQLITE_BIG_DBL; pProbe = pSrc->pTab->pIndex; @@ -71617,7 +75516,7 @@ static double bestIndex( flags |= WHERE_COLUMN_IN; if( pExpr->pSelect!=0 ){ inMultiplier *= 25; - }else if( pExpr->pList!=0 ){ + }else if( ALWAYS(pExpr->pList) ){ inMultiplier *= pExpr->pList->nExpr + 1; } } @@ -71733,7 +75632,7 @@ static double bestIndex( */ static void disableTerm(WhereLevel *pLevel, WhereTerm *pTerm){ if( pTerm - && (pTerm->flags & TERM_CODED)==0 + && ALWAYS((pTerm->flags & TERM_CODED)==0) && (pLevel->iLeftJoin==0 || ExprHasProperty(pTerm->pExpr, EP_FromJoin)) ){ pTerm->flags |= TERM_CODED; @@ -71798,7 +75697,7 @@ static int codeEqualityTerm( assert( pX->op==TK_IN ); iReg = iTarget; - eType = sqlite3FindInIndex(pParse, pX, 1); + eType = sqlite3FindInIndex(pParse, pX, 0); iTab = pX->iTable; sqlite3VdbeAddOp2(v, OP_Rewind, iTab, 0); VdbeComment((v, "%.*s", pX->span.n, pX->span.z)); @@ -71881,7 +75780,7 @@ static int codeAllEqualityTerms( int r1; int k = pIdx->aiColumn[j]; pTerm = findTerm(pWC, iCur, k, notReady, pLevel->flags, pIdx); - if( pTerm==0 ) break; + if( NEVER(pTerm==0) ) break; assert( (pTerm->flags & TERM_CODED)==0 ); r1 = codeEqualityTerm(pParse, pTerm, pLevel, regBase+j); if( r1!=regBase+j ){ @@ -71915,14 +75814,15 @@ static int nQPlan = 0; /* Next free slow in _query_plan[] */ static void whereInfoFree(WhereInfo *pWInfo){ if( pWInfo ){ int i; + sqlite3 *db = pWInfo->pParse->db; for(i=0; i<pWInfo->nLevel; i++){ sqlite3_index_info *pInfo = pWInfo->a[i].pIdxInfo; if( pInfo ){ assert( pInfo->needToFreeIdxStr==0 ); - sqlite3_free(pInfo); + sqlite3DbFree(db, pInfo); } } - sqlite3_free(pWInfo); + sqlite3DbFree(db, pWInfo); } } @@ -72200,7 +76100,7 @@ SQLITE_PRIVATE WhereInfo *sqlite3WhereBegin( } if( doNotReorder ) break; } - WHERETRACE(("*** Optimizer choose table %d for loop %d\n", bestJ, + WHERETRACE(("*** Optimizer selects table %d for loop %d\n", bestJ, pLevel-pWInfo->a)); if( (bestFlags & WHERE_ORDERBY)!=0 ){ *ppOrderBy = 0; @@ -72255,22 +76155,22 @@ SQLITE_PRIVATE WhereInfo *sqlite3WhereBegin( struct SrcList_item *pItem = &pTabList->a[pLevel->iFrom]; zMsg = sqlite3MPrintf(db, "TABLE %s", pItem->zName); if( pItem->zAlias ){ - zMsg = sqlite3MPrintf(db, "%z AS %s", zMsg, pItem->zAlias); + zMsg = sqlite3MAppendf(db, zMsg, "%s AS %s", zMsg, pItem->zAlias); } if( (pIx = pLevel->pIdx)!=0 ){ - zMsg = sqlite3MPrintf(db, "%z WITH INDEX %s", zMsg, pIx->zName); + zMsg = sqlite3MAppendf(db, zMsg, "%s WITH INDEX %s", zMsg, pIx->zName); }else if( pLevel->flags & (WHERE_ROWID_EQ|WHERE_ROWID_RANGE) ){ - zMsg = sqlite3MPrintf(db, "%z USING PRIMARY KEY", zMsg); + zMsg = sqlite3MAppendf(db, zMsg, "%s USING PRIMARY KEY", zMsg); } #ifndef SQLITE_OMIT_VIRTUALTABLE else if( pLevel->pBestIdx ){ sqlite3_index_info *pBestIdx = pLevel->pBestIdx; - zMsg = sqlite3MPrintf(db, "%z VIRTUAL TABLE INDEX %d:%s", zMsg, + zMsg = sqlite3MAppendf(db, zMsg, "%s VIRTUAL TABLE INDEX %d:%s", zMsg, pBestIdx->idxNum, pBestIdx->idxStr); } #endif if( pLevel->flags & WHERE_ORDERBY ){ - zMsg = sqlite3MPrintf(db, "%z ORDER BY", zMsg); + zMsg = sqlite3MAppendf(db, zMsg, "%s ORDER BY", zMsg); } sqlite3VdbeAddOp4(v, OP_Explain, i, pLevel->iFrom, 0, zMsg, P4_DYNAMIC); } @@ -72371,24 +76271,28 @@ SQLITE_PRIVATE WhereInfo *sqlite3WhereBegin( pBestIdx->aConstraint; iReg = sqlite3GetTempRange(pParse, nConstraint+2); + pParse->disableColCache++; for(j=1; j<=nConstraint; j++){ int k; for(k=0; k<nConstraint; k++){ if( aUsage[k].argvIndex==j ){ int iTerm = aConstraint[k].iTermOffset; + assert( pParse->disableColCache ); sqlite3ExprCode(pParse, wc.a[iTerm].pExpr->pRight, iReg+j+1); break; } } if( k==nConstraint ) break; } + assert( pParse->disableColCache ); + pParse->disableColCache--; sqlite3VdbeAddOp2(v, OP_Integer, pBestIdx->idxNum, iReg); sqlite3VdbeAddOp2(v, OP_Integer, j-1, iReg+1); sqlite3VdbeAddOp4(v, OP_VFilter, iCur, brk, iReg, pBestIdx->idxStr, pBestIdx->needToFreeIdxStr ? P4_MPRINTF : P4_STATIC); sqlite3ReleaseTempRange(pParse, iReg, nConstraint+2); pBestIdx->needToFreeIdxStr = 0; - for(j=0; j<pBestIdx->nConstraint; j++){ + for(j=0; j<nConstraint; j++){ if( aUsage[j].omit ){ int iTerm = aConstraint[j].iTermOffset; disableTerm(pLevel, &wc.a[iTerm]); @@ -72553,8 +76457,9 @@ SQLITE_PRIVATE WhereInfo *sqlite3WhereBegin( if( (wflags&WHERE_ORDERBY_MIN)!=0 && (pLevel->flags&WHERE_ORDERBY) && (pIdx->nColumn>nEq) - && (pOrderBy->a[0].pExpr->iColumn==pIdx->aiColumn[nEq]) ){ + assert( pOrderBy->nExpr==1 ); + assert( pOrderBy->a[0].pExpr->iColumn==pIdx->aiColumn[nEq] ); isMinQuery = 1; } @@ -72589,7 +76494,7 @@ SQLITE_PRIVATE WhereInfo *sqlite3WhereBegin( if( pRangeStart ){ int dcc = pParse->disableColCache; if( pRangeEnd ){ - pParse->disableColCache = 1; + pParse->disableColCache++; } sqlite3ExprCode(pParse, pRangeStart->pExpr->pRight, regBase+nEq); pParse->disableColCache = dcc; @@ -72611,7 +76516,7 @@ SQLITE_PRIVATE WhereInfo *sqlite3WhereBegin( testcase( op==OP_MoveLe ); testcase( op==OP_MoveLt ); sqlite3VdbeAddOp4(v, op, iIdxCur, nxt, regBase, - (char*)nConstraint, P4_INT32); + SQLITE_INT_TO_PTR(nConstraint), P4_INT32); /* Load the value for the inequality constraint at the end of the ** range (if any). @@ -72633,7 +76538,7 @@ SQLITE_PRIVATE WhereInfo *sqlite3WhereBegin( testcase( op==OP_IdxGE ); testcase( op==OP_IdxLT ); sqlite3VdbeAddOp4(v, op, iIdxCur, nxt, regBase, - (char*)nConstraint, P4_INT32); + SQLITE_INT_TO_PTR(nConstraint), P4_INT32); sqlite3VdbeChangeP5(v, endEq!=bRev); /* If there are inequality constraints, check that the value @@ -72781,14 +76686,16 @@ whereBeginNoMem: ** sqlite3WhereBegin() for additional information. */ SQLITE_PRIVATE void sqlite3WhereEnd(WhereInfo *pWInfo){ - Vdbe *v = pWInfo->pParse->pVdbe; + Parse *pParse = pWInfo->pParse; + Vdbe *v = pParse->pVdbe; int i; WhereLevel *pLevel; SrcList *pTabList = pWInfo->pTabList; + sqlite3 *db = pParse->db; /* Generate loop termination code. */ - sqlite3ExprClearColumnCache(pWInfo->pParse, -1); + sqlite3ExprClearColumnCache(pParse, -1); for(i=pTabList->nSrc-1; i>=0; i--){ pLevel = &pWInfo->a[i]; sqlite3VdbeResolveLabel(v, pLevel->cont); @@ -72804,7 +76711,7 @@ SQLITE_PRIVATE void sqlite3WhereEnd(WhereInfo *pWInfo){ sqlite3VdbeAddOp2(v, OP_Next, pIn->iCur, pIn->topAddr); sqlite3VdbeJumpHere(v, pIn->topAddr-1); } - sqlite3_free(pLevel->aInLoop); + sqlite3DbFree(db, pLevel->aInLoop); } sqlite3VdbeResolveLabel(v, pLevel->brk); if( pLevel->iLeftJoin ){ @@ -72892,8 +76799,8 @@ SQLITE_PRIVATE void sqlite3WhereEnd(WhereInfo *pWInfo){ /* Driver template for the LEMON parser generator. ** The author disclaims copyright to this source code. */ -/* First off, code is include which follows the "include" declaration -** in the input file. */ +/* First off, code is included that follows the "include" declaration +** in the input grammar file. */ /* @@ -72996,7 +76903,6 @@ typedef union { struct TrigEvent yy370; SrcList* yy373; struct {int value; int mask;} yy405; - Token yy410; IdList* yy432; } YYMINORTYPE; #ifndef YYSTACKDEPTH @@ -73017,7 +76923,7 @@ typedef union { ** YYMINORTYPE objects to zero. */ static const YYMINORTYPE yyzerominor; -/* Next are that tables used to determine what action to take based on the +/* Next are the tables used to determine what action to take based on the ** current state and lookahead token. These tables are used to implement ** functions that take a state number and lookahead value and return an ** action integer. @@ -73483,7 +77389,7 @@ static const YYACTIONTYPE yy_default[] = { ** ** %fallback ID X Y Z. ** -** appears in the grammer, then ID becomes a fallback token for X, Y, +** appears in the grammar, then ID becomes a fallback token for X, Y, ** and Z. Whenever one of the tokens X, Y, or Z is input to the parser ** but it does not parse, the type of the token is changed to ID and ** the parse is retried before an error is thrown. @@ -73644,11 +77550,11 @@ static const YYCODETYPE yyFallback[] = { ** It is sometimes called the "minor" token. */ struct yyStackEntry { - int stateno; /* The state-number */ - int major; /* The major token value. This is the code - ** number for the token at this stack level */ - YYMINORTYPE minor; /* The user-supplied minor token value. This - ** is the value of the token */ + YYACTIONTYPE stateno; /* The state-number */ + YYCODETYPE major; /* The major token value. This is the code + ** number for the token at this stack level */ + YYMINORTYPE minor; /* The user-supplied minor token value. This + ** is the value of the token */ }; typedef struct yyStackEntry yyStackEntry; @@ -73656,6 +77562,9 @@ typedef struct yyStackEntry yyStackEntry; ** the following structure */ struct yyParser { int yyidx; /* Index of top element in stack */ +#ifdef YYTRACKMAXSTACKDEPTH + int yyidxMax; /* Maximum value of yyidx */ +#endif int yyerrcnt; /* Shifts left before out of the error */ sqlite3ParserARG_SDECL /* A place to hold %extra_argument */ #if YYSTACKDEPTH<=0 @@ -74128,6 +78037,9 @@ SQLITE_PRIVATE void *sqlite3ParserAlloc(void *(*mallocProc)(size_t)){ pParser = (yyParser*)(*mallocProc)( (size_t)sizeof(yyParser) ); if( pParser ){ pParser->yyidx = -1; +#ifdef YYTRACKMAXSTACKDEPTH + pParser->yyidxMax = 0; +#endif #if YYSTACKDEPTH<=0 yyGrowStack(pParser); #endif @@ -74140,7 +78052,12 @@ SQLITE_PRIVATE void *sqlite3ParserAlloc(void *(*mallocProc)(size_t)){ ** "yymajor" is the symbol code, and "yypminor" is a pointer to ** the value. */ -static void yy_destructor(YYCODETYPE yymajor, YYMINORTYPE *yypminor){ +static void yy_destructor( + yyParser *yypParser, /* The parser */ + YYCODETYPE yymajor, /* Type code for object to destroy */ + YYMINORTYPE *yypminor /* The object to be destroyed */ +){ + sqlite3ParserARG_FETCH; switch( yymajor ){ /* Here is inserted the actions which take place when a ** terminal or non-terminal is destroyed. This can happen @@ -74153,183 +78070,67 @@ static void yy_destructor(YYCODETYPE yymajor, YYMINORTYPE *yypminor){ ** inside the C code. */ case 155: /* select */ + case 189: /* oneselect */ + case 206: /* seltablist_paren */ { -sqlite3SelectDelete((yypminor->yy219)); +sqlite3SelectDelete(pParse->db, (yypminor->yy219)); } break; case 169: /* term */ -{ -sqlite3ExprDelete((yypminor->yy172)); -} - break; case 170: /* expr */ + case 194: /* where_opt */ + case 196: /* having_opt */ + case 204: /* on_opt */ + case 210: /* sortitem */ + case 218: /* escape */ + case 221: /* case_operand */ + case 223: /* case_else */ + case 235: /* when_clause */ + case 238: /* key_opt */ { -sqlite3ExprDelete((yypminor->yy172)); +sqlite3ExprDelete(pParse->db, (yypminor->yy172)); } break; case 174: /* idxlist_opt */ -{ -sqlite3ExprListDelete((yypminor->yy174)); -} - break; case 182: /* idxlist */ -{ -sqlite3ExprListDelete((yypminor->yy174)); -} - break; - case 188: /* fullname */ -{ -sqlite3SrcListDelete((yypminor->yy373)); -} - break; - case 189: /* oneselect */ -{ -sqlite3SelectDelete((yypminor->yy219)); -} - break; case 192: /* selcollist */ -{ -sqlite3ExprListDelete((yypminor->yy174)); -} - break; - case 193: /* from */ -{ -sqlite3SrcListDelete((yypminor->yy373)); -} - break; - case 194: /* where_opt */ -{ -sqlite3ExprDelete((yypminor->yy172)); -} - break; case 195: /* groupby_opt */ -{ -sqlite3ExprListDelete((yypminor->yy174)); -} - break; - case 196: /* having_opt */ -{ -sqlite3ExprDelete((yypminor->yy172)); -} - break; case 197: /* orderby_opt */ -{ -sqlite3ExprListDelete((yypminor->yy174)); -} - break; case 199: /* sclp */ -{ -sqlite3ExprListDelete((yypminor->yy174)); -} - break; - case 201: /* seltablist */ -{ -sqlite3SrcListDelete((yypminor->yy373)); -} - break; - case 202: /* stl_prefix */ -{ -sqlite3SrcListDelete((yypminor->yy373)); -} - break; - case 204: /* on_opt */ -{ -sqlite3ExprDelete((yypminor->yy172)); -} - break; - case 205: /* using_opt */ -{ -sqlite3IdListDelete((yypminor->yy432)); -} - break; - case 206: /* seltablist_paren */ -{ -sqlite3SelectDelete((yypminor->yy219)); -} - break; - case 208: /* inscollist */ -{ -sqlite3IdListDelete((yypminor->yy432)); -} - break; case 209: /* sortlist */ -{ -sqlite3ExprListDelete((yypminor->yy174)); -} - break; - case 210: /* sortitem */ -{ -sqlite3ExprDelete((yypminor->yy172)); -} - break; case 211: /* nexprlist */ -{ -sqlite3ExprListDelete((yypminor->yy174)); -} - break; case 212: /* setlist */ -{ -sqlite3ExprListDelete((yypminor->yy174)); -} - break; - case 214: /* inscollist_opt */ -{ -sqlite3IdListDelete((yypminor->yy432)); -} - break; case 215: /* itemlist */ -{ -sqlite3ExprListDelete((yypminor->yy174)); -} - break; case 216: /* exprlist */ -{ -sqlite3ExprListDelete((yypminor->yy174)); -} - break; - case 218: /* escape */ -{ -sqlite3ExprDelete((yypminor->yy172)); -} - break; - case 221: /* case_operand */ -{ -sqlite3ExprDelete((yypminor->yy172)); -} - break; case 222: /* case_exprlist */ { -sqlite3ExprListDelete((yypminor->yy174)); -} - break; - case 223: /* case_else */ -{ -sqlite3ExprDelete((yypminor->yy172)); +sqlite3ExprListDelete(pParse->db, (yypminor->yy174)); } break; - case 231: /* trigger_cmd_list */ -{ -sqlite3DeleteTriggerStep((yypminor->yy243)); -} - break; - case 233: /* trigger_event */ + case 188: /* fullname */ + case 193: /* from */ + case 201: /* seltablist */ + case 202: /* stl_prefix */ { -sqlite3IdListDelete((yypminor->yy370).b); +sqlite3SrcListDelete(pParse->db, (yypminor->yy373)); } break; - case 235: /* when_clause */ + case 205: /* using_opt */ + case 208: /* inscollist */ + case 214: /* inscollist_opt */ { -sqlite3ExprDelete((yypminor->yy172)); +sqlite3IdListDelete(pParse->db, (yypminor->yy432)); } break; + case 231: /* trigger_cmd_list */ case 236: /* trigger_cmd */ { -sqlite3DeleteTriggerStep((yypminor->yy243)); +sqlite3DeleteTriggerStep(pParse->db, (yypminor->yy243)); } break; - case 238: /* key_opt */ + case 233: /* trigger_event */ { -sqlite3ExprDelete((yypminor->yy172)); +sqlite3IdListDelete(pParse->db, (yypminor->yy370).b); } break; default: break; /* If no destructor action specified: do nothing */ @@ -74357,7 +78158,7 @@ static int yy_pop_parser_stack(yyParser *pParser){ } #endif yymajor = yytos->major; - yy_destructor( yymajor, &yytos->minor); + yy_destructor(pParser, yymajor, &yytos->minor); pParser->yyidx--; return yymajor; } @@ -74388,6 +78189,16 @@ SQLITE_PRIVATE void sqlite3ParserFree( } /* +** Return the peak depth of the stack for a parser. +*/ +#ifdef YYTRACKMAXSTACKDEPTH +SQLITE_PRIVATE int sqlite3ParserStackPeak(void *p){ + yyParser *pParser = (yyParser*)p; + return pParser->yyidxMax; +} +#endif + +/* ** Find the appropriate action for a parser given the terminal ** look-ahead token iLookAhead. ** @@ -74505,10 +78316,15 @@ static void yy_shift( yyParser *yypParser, /* The parser to be shifted */ int yyNewState, /* The new state to shift in */ int yyMajor, /* The major token to shift in */ - YYMINORTYPE *yypMinor /* Pointer ot the minor token to shift in */ + YYMINORTYPE *yypMinor /* Pointer to the minor token to shift in */ ){ yyStackEntry *yytos; yypParser->yyidx++; +#ifdef YYTRACKMAXSTACKDEPTH + if( yypParser->yyidx>yypParser->yyidxMax ){ + yypParser->yyidxMax = yypParser->yyidx; + } +#endif #if YYSTACKDEPTH>0 if( yypParser->yyidx>=YYSTACKDEPTH ){ yyStackOverflow(yypParser, yypMinor); @@ -74985,7 +78801,7 @@ static void yy_reduce( break; case 21: /* create_table ::= CREATE temp TABLE ifnotexists nm dbnm */ { - sqlite3StartTable(pParse,&yymsp[-1].minor.yy410,&yymsp[0].minor.yy410,yymsp[-4].minor.yy46,0,0,yymsp[-2].minor.yy46); + sqlite3StartTable(pParse,&yymsp[-1].minor.yy0,&yymsp[0].minor.yy0,yymsp[-4].minor.yy46,0,0,yymsp[-2].minor.yy46); } break; case 22: /* ifnotexists ::= */ @@ -75013,25 +78829,25 @@ static void yy_reduce( break; case 26: /* create_table_args ::= LP columnlist conslist_opt RP */ { - sqlite3EndTable(pParse,&yymsp[-1].minor.yy410,&yymsp[0].minor.yy0,0); + sqlite3EndTable(pParse,&yymsp[-1].minor.yy0,&yymsp[0].minor.yy0,0); } break; case 27: /* create_table_args ::= AS select */ { sqlite3EndTable(pParse,0,0,yymsp[0].minor.yy219); - sqlite3SelectDelete(yymsp[0].minor.yy219); + sqlite3SelectDelete(pParse->db, yymsp[0].minor.yy219); } break; case 30: /* column ::= columnid type carglist */ { - yygotominor.yy410.z = yymsp[-2].minor.yy410.z; - yygotominor.yy410.n = (pParse->sLastToken.z-yymsp[-2].minor.yy410.z) + pParse->sLastToken.n; + yygotominor.yy0.z = yymsp[-2].minor.yy0.z; + yygotominor.yy0.n = (pParse->sLastToken.z-yymsp[-2].minor.yy0.z) + pParse->sLastToken.n; } break; case 31: /* columnid ::= nm */ { - sqlite3AddColumn(pParse,&yymsp[0].minor.yy410); - yygotominor.yy410 = yymsp[0].minor.yy410; + sqlite3AddColumn(pParse,&yymsp[0].minor.yy0); + yygotominor.yy0 = yymsp[0].minor.yy0; } break; case 32: /* id ::= ID */ @@ -75039,12 +78855,6 @@ static void yy_reduce( case 34: /* nm ::= ID */ case 35: /* nm ::= STRING */ case 36: /* nm ::= JOIN_KW */ - case 257: /* number ::= INTEGER|FLOAT */ -{yygotominor.yy410 = yymsp[0].minor.yy0;} - break; - case 38: /* type ::= typetoken */ -{sqlite3AddColumnType(pParse,&yymsp[0].minor.yy410);} - break; case 39: /* typetoken ::= typename */ case 42: /* typename ::= ids */ case 119: /* as ::= AS nm */ @@ -75056,22 +78866,26 @@ static void yy_reduce( case 254: /* nmnum ::= nm */ case 255: /* plus_num ::= plus_opt number */ case 256: /* minus_num ::= MINUS number */ -{yygotominor.yy410 = yymsp[0].minor.yy410;} + case 257: /* number ::= INTEGER|FLOAT */ +{yygotominor.yy0 = yymsp[0].minor.yy0;} + break; + case 38: /* type ::= typetoken */ +{sqlite3AddColumnType(pParse,&yymsp[0].minor.yy0);} break; case 40: /* typetoken ::= typename LP signed RP */ { - yygotominor.yy410.z = yymsp[-3].minor.yy410.z; - yygotominor.yy410.n = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n] - yymsp[-3].minor.yy410.z; + yygotominor.yy0.z = yymsp[-3].minor.yy0.z; + yygotominor.yy0.n = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n] - yymsp[-3].minor.yy0.z; } break; case 41: /* typetoken ::= typename LP signed COMMA signed RP */ { - yygotominor.yy410.z = yymsp[-5].minor.yy410.z; - yygotominor.yy410.n = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n] - yymsp[-5].minor.yy410.z; + yygotominor.yy0.z = yymsp[-5].minor.yy0.z; + yygotominor.yy0.n = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n] - yymsp[-5].minor.yy0.z; } break; case 43: /* typename ::= typename ids */ -{yygotominor.yy410.z=yymsp[-1].minor.yy410.z; yygotominor.yy410.n=yymsp[0].minor.yy410.n+(yymsp[0].minor.yy410.z-yymsp[-1].minor.yy410.z);} +{yygotominor.yy0.z=yymsp[-1].minor.yy0.z; yygotominor.yy0.n=yymsp[0].minor.yy0.n+(yymsp[0].minor.yy0.z-yymsp[-1].minor.yy0.z);} break; case 50: /* ccons ::= DEFAULT term */ case 52: /* ccons ::= DEFAULT PLUS term */ @@ -75088,7 +78902,7 @@ static void yy_reduce( break; case 54: /* ccons ::= DEFAULT id */ { - Expr *p = sqlite3PExpr(pParse, TK_STRING, 0, 0, &yymsp[0].minor.yy410); + Expr *p = sqlite3PExpr(pParse, TK_STRING, 0, 0, &yymsp[0].minor.yy0); sqlite3AddDefaultValue(pParse,p); } break; @@ -75105,13 +78919,13 @@ static void yy_reduce( {sqlite3AddCheckConstraint(pParse,yymsp[-1].minor.yy172);} break; case 60: /* ccons ::= REFERENCES nm idxlist_opt refargs */ -{sqlite3CreateForeignKey(pParse,0,&yymsp[-2].minor.yy410,yymsp[-1].minor.yy174,yymsp[0].minor.yy46);} +{sqlite3CreateForeignKey(pParse,0,&yymsp[-2].minor.yy0,yymsp[-1].minor.yy174,yymsp[0].minor.yy46);} break; case 61: /* ccons ::= defer_subclause */ {sqlite3DeferForeignKey(pParse,yymsp[0].minor.yy46);} break; case 62: /* ccons ::= COLLATE ids */ -{sqlite3AddCollateType(pParse, &yymsp[0].minor.yy410);} +{sqlite3AddCollateType(pParse, &yymsp[0].minor.yy0);} break; case 65: /* refargs ::= */ { yygotominor.yy46 = OE_Restrict * 0x010101; } @@ -75153,10 +78967,10 @@ static void yy_reduce( {yygotominor.yy46 = yymsp[0].minor.yy46;} break; case 80: /* conslist_opt ::= */ -{yygotominor.yy410.n = 0; yygotominor.yy410.z = 0;} +{yygotominor.yy0.n = 0; yygotominor.yy0.z = 0;} break; case 81: /* conslist_opt ::= COMMA conslist */ -{yygotominor.yy410 = yymsp[-1].minor.yy0;} +{yygotominor.yy0 = yymsp[-1].minor.yy0;} break; case 86: /* tcons ::= PRIMARY KEY LP idxlist autoinc RP onconf */ {sqlite3AddPrimaryKey(pParse,yymsp[-3].minor.yy174,yymsp[0].minor.yy46,yymsp[-2].minor.yy46,0);} @@ -75169,7 +78983,7 @@ static void yy_reduce( break; case 89: /* tcons ::= FOREIGN KEY LP idxlist RP REFERENCES nm idxlist_opt refargs defer_subclause_opt */ { - sqlite3CreateForeignKey(pParse, yymsp[-6].minor.yy174, &yymsp[-3].minor.yy410, yymsp[-2].minor.yy174, yymsp[-1].minor.yy46); + sqlite3CreateForeignKey(pParse, yymsp[-6].minor.yy174, &yymsp[-3].minor.yy0, yymsp[-2].minor.yy174, yymsp[-1].minor.yy46); sqlite3DeferForeignKey(pParse, yymsp[0].minor.yy46); } break; @@ -75191,7 +79005,7 @@ static void yy_reduce( break; case 102: /* cmd ::= CREATE temp VIEW ifnotexists nm dbnm AS select */ { - sqlite3CreateView(pParse, &yymsp[-7].minor.yy0, &yymsp[-3].minor.yy410, &yymsp[-2].minor.yy410, yymsp[0].minor.yy219, yymsp[-6].minor.yy46, yymsp[-4].minor.yy46); + sqlite3CreateView(pParse, &yymsp[-7].minor.yy0, &yymsp[-3].minor.yy0, &yymsp[-2].minor.yy0, yymsp[0].minor.yy219, yymsp[-6].minor.yy46, yymsp[-4].minor.yy46); } break; case 103: /* cmd ::= DROP VIEW ifexists fullname */ @@ -75202,8 +79016,8 @@ static void yy_reduce( case 104: /* cmd ::= select */ { SelectDest dest = {SRT_Callback, 0, 0, 0, 0}; - sqlite3Select(pParse, yymsp[0].minor.yy219, &dest, 0, 0, 0, 0); - sqlite3SelectDelete(yymsp[0].minor.yy219); + sqlite3Select(pParse, yymsp[0].minor.yy219, &dest, 0, 0, 0); + sqlite3SelectDelete(pParse->db, yymsp[0].minor.yy219); } break; case 105: /* select ::= oneselect */ @@ -75216,7 +79030,7 @@ static void yy_reduce( yymsp[0].minor.yy219->op = yymsp[-1].minor.yy46; yymsp[0].minor.yy219->pPrior = yymsp[-2].minor.yy219; }else{ - sqlite3SelectDelete(yymsp[-2].minor.yy219); + sqlite3SelectDelete(pParse->db, yymsp[-2].minor.yy219); } yygotominor.yy219 = yymsp[0].minor.yy219; } @@ -75242,7 +79056,7 @@ static void yy_reduce( break; case 116: /* selcollist ::= sclp expr as */ { - yygotominor.yy174 = sqlite3ExprListAppend(pParse,yymsp[-2].minor.yy174,yymsp[-1].minor.yy172,yymsp[0].minor.yy410.n?&yymsp[0].minor.yy410:0); + yygotominor.yy174 = sqlite3ExprListAppend(pParse,yymsp[-2].minor.yy174,yymsp[-1].minor.yy172,yymsp[0].minor.yy0.n?&yymsp[0].minor.yy0:0); } break; case 117: /* selcollist ::= sclp STAR */ @@ -75253,14 +79067,14 @@ static void yy_reduce( break; case 118: /* selcollist ::= sclp nm DOT STAR */ { - Expr *pRight = sqlite3PExpr(pParse, TK_ALL, 0, 0, 0); - Expr *pLeft = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[-2].minor.yy410); + Expr *pRight = sqlite3PExpr(pParse, TK_ALL, 0, 0, &yymsp[0].minor.yy0); + Expr *pLeft = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[-2].minor.yy0); Expr *pDot = sqlite3PExpr(pParse, TK_DOT, pLeft, pRight, 0); yygotominor.yy174 = sqlite3ExprListAppend(pParse,yymsp[-3].minor.yy174, pDot, 0); } break; case 121: /* as ::= */ -{yygotominor.yy410.n = 0;} +{yygotominor.yy0.n = 0;} break; case 122: /* from ::= */ {yygotominor.yy373 = sqlite3DbMallocZero(pParse->db, sizeof(*yygotominor.yy373));} @@ -75282,12 +79096,12 @@ static void yy_reduce( break; case 126: /* seltablist ::= stl_prefix nm dbnm as on_opt using_opt */ { - yygotominor.yy373 = sqlite3SrcListAppendFromTerm(pParse,yymsp[-5].minor.yy373,&yymsp[-4].minor.yy410,&yymsp[-3].minor.yy410,&yymsp[-2].minor.yy410,0,yymsp[-1].minor.yy172,yymsp[0].minor.yy432); + yygotominor.yy373 = sqlite3SrcListAppendFromTerm(pParse,yymsp[-5].minor.yy373,&yymsp[-4].minor.yy0,&yymsp[-3].minor.yy0,&yymsp[-2].minor.yy0,0,yymsp[-1].minor.yy172,yymsp[0].minor.yy432); } break; case 127: /* seltablist ::= stl_prefix LP seltablist_paren RP as on_opt using_opt */ { - yygotominor.yy373 = sqlite3SrcListAppendFromTerm(pParse,yymsp[-6].minor.yy373,0,0,&yymsp[-2].minor.yy410,yymsp[-4].minor.yy219,yymsp[-1].minor.yy172,yymsp[0].minor.yy432); + yygotominor.yy373 = sqlite3SrcListAppendFromTerm(pParse,yymsp[-6].minor.yy373,0,0,&yymsp[-2].minor.yy0,yymsp[-4].minor.yy219,yymsp[-1].minor.yy172,yymsp[0].minor.yy432); } break; case 129: /* seltablist_paren ::= seltablist */ @@ -75297,10 +79111,10 @@ static void yy_reduce( } break; case 130: /* dbnm ::= */ -{yygotominor.yy410.z=0; yygotominor.yy410.n=0;} +{yygotominor.yy0.z=0; yygotominor.yy0.n=0;} break; case 132: /* fullname ::= nm dbnm */ -{yygotominor.yy373 = sqlite3SrcListAppend(pParse->db,0,&yymsp[-1].minor.yy410,&yymsp[0].minor.yy410);} +{yygotominor.yy373 = sqlite3SrcListAppend(pParse->db,0,&yymsp[-1].minor.yy0,&yymsp[0].minor.yy0);} break; case 133: /* joinop ::= COMMA|JOIN */ { yygotominor.yy46 = JT_INNER; } @@ -75309,10 +79123,10 @@ static void yy_reduce( { yygotominor.yy46 = sqlite3JoinType(pParse,&yymsp[-1].minor.yy0,0,0); } break; case 135: /* joinop ::= JOIN_KW nm JOIN */ -{ yygotominor.yy46 = sqlite3JoinType(pParse,&yymsp[-2].minor.yy0,&yymsp[-1].minor.yy410,0); } +{ yygotominor.yy46 = sqlite3JoinType(pParse,&yymsp[-2].minor.yy0,&yymsp[-1].minor.yy0,0); } break; case 136: /* joinop ::= JOIN_KW nm nm JOIN */ -{ yygotominor.yy46 = sqlite3JoinType(pParse,&yymsp[-3].minor.yy0,&yymsp[-2].minor.yy410,&yymsp[-1].minor.yy410); } +{ yygotominor.yy46 = sqlite3JoinType(pParse,&yymsp[-3].minor.yy0,&yymsp[-2].minor.yy0,&yymsp[-1].minor.yy0); } break; case 137: /* on_opt ::= ON expr */ case 145: /* sortitem ::= expr */ @@ -75386,10 +79200,10 @@ static void yy_reduce( } break; case 161: /* setlist ::= setlist COMMA nm EQ expr */ -{yygotominor.yy174 = sqlite3ExprListAppend(pParse,yymsp[-4].minor.yy174,yymsp[0].minor.yy172,&yymsp[-2].minor.yy410);} +{yygotominor.yy174 = sqlite3ExprListAppend(pParse,yymsp[-4].minor.yy174,yymsp[0].minor.yy172,&yymsp[-2].minor.yy0);} break; case 162: /* setlist ::= nm EQ expr */ -{yygotominor.yy174 = sqlite3ExprListAppend(pParse,0,yymsp[0].minor.yy172,&yymsp[-2].minor.yy410);} +{yygotominor.yy174 = sqlite3ExprListAppend(pParse,0,yymsp[0].minor.yy172,&yymsp[-2].minor.yy0);} break; case 163: /* cmd ::= insert_cmd INTO fullname inscollist_opt VALUES LP itemlist RP */ {sqlite3Insert(pParse, yymsp[-5].minor.yy373, yymsp[-1].minor.yy174, 0, yymsp[-4].minor.yy432, yymsp[-7].minor.yy46);} @@ -75409,10 +79223,10 @@ static void yy_reduce( {yygotominor.yy174 = sqlite3ExprListAppend(pParse,0,yymsp[0].minor.yy172,0);} break; case 172: /* inscollist ::= inscollist COMMA nm */ -{yygotominor.yy432 = sqlite3IdListAppend(pParse->db,yymsp[-2].minor.yy432,&yymsp[0].minor.yy410);} +{yygotominor.yy432 = sqlite3IdListAppend(pParse->db,yymsp[-2].minor.yy432,&yymsp[0].minor.yy0);} break; case 173: /* inscollist ::= nm */ -{yygotominor.yy432 = sqlite3IdListAppend(pParse->db,0,&yymsp[0].minor.yy410);} +{yygotominor.yy432 = sqlite3IdListAppend(pParse->db,0,&yymsp[0].minor.yy0);} break; case 175: /* expr ::= LP expr RP */ {yygotominor.yy172 = yymsp[-1].minor.yy172; sqlite3ExprSpan(yygotominor.yy172,&yymsp[-2].minor.yy0,&yymsp[0].minor.yy0); } @@ -75428,16 +79242,16 @@ static void yy_reduce( break; case 179: /* expr ::= nm DOT nm */ { - Expr *temp1 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[-2].minor.yy410); - Expr *temp2 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[0].minor.yy410); + Expr *temp1 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[-2].minor.yy0); + Expr *temp2 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[0].minor.yy0); yygotominor.yy172 = sqlite3PExpr(pParse, TK_DOT, temp1, temp2, 0); } break; case 180: /* expr ::= nm DOT nm DOT nm */ { - Expr *temp1 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[-4].minor.yy410); - Expr *temp2 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[-2].minor.yy410); - Expr *temp3 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[0].minor.yy410); + Expr *temp1 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[-4].minor.yy0); + Expr *temp2 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[-2].minor.yy0); + Expr *temp3 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[0].minor.yy0); Expr *temp4 = sqlite3PExpr(pParse, TK_DOT, temp2, temp3, 0); yygotominor.yy172 = sqlite3PExpr(pParse, TK_DOT, temp1, temp4, 0); } @@ -75454,12 +79268,12 @@ static void yy_reduce( break; case 185: /* expr ::= expr COLLATE ids */ { - yygotominor.yy172 = sqlite3ExprSetColl(pParse, yymsp[-2].minor.yy172, &yymsp[0].minor.yy410); + yygotominor.yy172 = sqlite3ExprSetColl(pParse, yymsp[-2].minor.yy172, &yymsp[0].minor.yy0); } break; case 186: /* expr ::= CAST LP expr AS typetoken RP */ { - yygotominor.yy172 = sqlite3PExpr(pParse, TK_CAST, yymsp[-3].minor.yy172, 0, &yymsp[-1].minor.yy410); + yygotominor.yy172 = sqlite3PExpr(pParse, TK_CAST, yymsp[-3].minor.yy172, 0, &yymsp[-1].minor.yy0); sqlite3ExprSpan(yygotominor.yy172,&yymsp[-5].minor.yy0,&yymsp[0].minor.yy0); } break; @@ -75575,7 +79389,7 @@ static void yy_reduce( if( yygotominor.yy172 ){ yygotominor.yy172->pList = pList; }else{ - sqlite3ExprListDelete(pList); + sqlite3ExprListDelete(pParse->db, pList); } if( yymsp[-3].minor.yy46 ) yygotominor.yy172 = sqlite3PExpr(pParse, TK_NOT, yygotominor.yy172, 0, 0); sqlite3ExprSpan(yygotominor.yy172,&yymsp[-4].minor.yy172->span,&yymsp[0].minor.yy172->span); @@ -75586,9 +79400,9 @@ static void yy_reduce( yygotominor.yy172 = sqlite3PExpr(pParse, TK_IN, yymsp[-4].minor.yy172, 0, 0); if( yygotominor.yy172 ){ yygotominor.yy172->pList = yymsp[-1].minor.yy174; - sqlite3ExprSetHeight(yygotominor.yy172); + sqlite3ExprSetHeight(pParse, yygotominor.yy172); }else{ - sqlite3ExprListDelete(yymsp[-1].minor.yy174); + sqlite3ExprListDelete(pParse->db, yymsp[-1].minor.yy174); } if( yymsp[-3].minor.yy46 ) yygotominor.yy172 = sqlite3PExpr(pParse, TK_NOT, yygotominor.yy172, 0, 0); sqlite3ExprSpan(yygotominor.yy172,&yymsp[-4].minor.yy172->span,&yymsp[0].minor.yy0); @@ -75599,9 +79413,9 @@ static void yy_reduce( yygotominor.yy172 = sqlite3PExpr(pParse, TK_SELECT, 0, 0, 0); if( yygotominor.yy172 ){ yygotominor.yy172->pSelect = yymsp[-1].minor.yy219; - sqlite3ExprSetHeight(yygotominor.yy172); + sqlite3ExprSetHeight(pParse, yygotominor.yy172); }else{ - sqlite3SelectDelete(yymsp[-1].minor.yy219); + sqlite3SelectDelete(pParse->db, yymsp[-1].minor.yy219); } sqlite3ExprSpan(yygotominor.yy172,&yymsp[-2].minor.yy0,&yymsp[0].minor.yy0); } @@ -75611,9 +79425,9 @@ static void yy_reduce( yygotominor.yy172 = sqlite3PExpr(pParse, TK_IN, yymsp[-4].minor.yy172, 0, 0); if( yygotominor.yy172 ){ yygotominor.yy172->pSelect = yymsp[-1].minor.yy219; - sqlite3ExprSetHeight(yygotominor.yy172); + sqlite3ExprSetHeight(pParse, yygotominor.yy172); }else{ - sqlite3SelectDelete(yymsp[-1].minor.yy219); + sqlite3SelectDelete(pParse->db, yymsp[-1].minor.yy219); } if( yymsp[-3].minor.yy46 ) yygotominor.yy172 = sqlite3PExpr(pParse, TK_NOT, yygotominor.yy172, 0, 0); sqlite3ExprSpan(yygotominor.yy172,&yymsp[-4].minor.yy172->span,&yymsp[0].minor.yy0); @@ -75621,16 +79435,16 @@ static void yy_reduce( break; case 221: /* expr ::= expr in_op nm dbnm */ { - SrcList *pSrc = sqlite3SrcListAppend(pParse->db, 0,&yymsp[-1].minor.yy410,&yymsp[0].minor.yy410); + SrcList *pSrc = sqlite3SrcListAppend(pParse->db, 0,&yymsp[-1].minor.yy0,&yymsp[0].minor.yy0); yygotominor.yy172 = sqlite3PExpr(pParse, TK_IN, yymsp[-3].minor.yy172, 0, 0); if( yygotominor.yy172 ){ yygotominor.yy172->pSelect = sqlite3SelectNew(pParse, 0,pSrc,0,0,0,0,0,0,0); - sqlite3ExprSetHeight(yygotominor.yy172); + sqlite3ExprSetHeight(pParse, yygotominor.yy172); }else{ - sqlite3SrcListDelete(pSrc); + sqlite3SrcListDelete(pParse->db, pSrc); } if( yymsp[-2].minor.yy46 ) yygotominor.yy172 = sqlite3PExpr(pParse, TK_NOT, yygotominor.yy172, 0, 0); - sqlite3ExprSpan(yygotominor.yy172,&yymsp[-3].minor.yy172->span,yymsp[0].minor.yy410.z?&yymsp[0].minor.yy410:&yymsp[-1].minor.yy410); + sqlite3ExprSpan(yygotominor.yy172,&yymsp[-3].minor.yy172->span,yymsp[0].minor.yy0.z?&yymsp[0].minor.yy0:&yymsp[-1].minor.yy0); } break; case 222: /* expr ::= EXISTS LP select RP */ @@ -75639,9 +79453,9 @@ static void yy_reduce( if( p ){ p->pSelect = yymsp[-1].minor.yy219; sqlite3ExprSpan(p,&yymsp[-3].minor.yy0,&yymsp[0].minor.yy0); - sqlite3ExprSetHeight(yygotominor.yy172); + sqlite3ExprSetHeight(pParse, yygotominor.yy172); }else{ - sqlite3SelectDelete(yymsp[-1].minor.yy219); + sqlite3SelectDelete(pParse->db, yymsp[-1].minor.yy219); } } break; @@ -75650,9 +79464,9 @@ static void yy_reduce( yygotominor.yy172 = sqlite3PExpr(pParse, TK_CASE, yymsp[-3].minor.yy172, yymsp[-1].minor.yy172, 0); if( yygotominor.yy172 ){ yygotominor.yy172->pList = yymsp[-2].minor.yy174; - sqlite3ExprSetHeight(yygotominor.yy172); + sqlite3ExprSetHeight(pParse, yygotominor.yy172); }else{ - sqlite3ExprListDelete(yymsp[-2].minor.yy174); + sqlite3ExprListDelete(pParse->db, yymsp[-2].minor.yy174); } sqlite3ExprSpan(yygotominor.yy172, &yymsp[-4].minor.yy0, &yymsp[0].minor.yy0); } @@ -75671,8 +79485,8 @@ static void yy_reduce( break; case 234: /* cmd ::= CREATE uniqueflag INDEX ifnotexists nm dbnm ON nm LP idxlist RP */ { - sqlite3CreateIndex(pParse, &yymsp[-6].minor.yy410, &yymsp[-5].minor.yy410, - sqlite3SrcListAppend(pParse->db,0,&yymsp[-3].minor.yy410,0), yymsp[-1].minor.yy174, yymsp[-9].minor.yy46, + sqlite3CreateIndex(pParse, &yymsp[-6].minor.yy0, &yymsp[-5].minor.yy0, + sqlite3SrcListAppend(pParse->db,0,&yymsp[-3].minor.yy0,0), yymsp[-1].minor.yy174, yymsp[-9].minor.yy46, &yymsp[-10].minor.yy0, &yymsp[0].minor.yy0, SQLITE_SO_ASC, yymsp[-7].minor.yy46); } break; @@ -75686,11 +79500,11 @@ static void yy_reduce( case 239: /* idxlist ::= idxlist COMMA idxitem collate sortorder */ { Expr *p = 0; - if( yymsp[-1].minor.yy410.n>0 ){ + if( yymsp[-1].minor.yy0.n>0 ){ p = sqlite3PExpr(pParse, TK_COLUMN, 0, 0, 0); - sqlite3ExprSetColl(pParse, p, &yymsp[-1].minor.yy410); + sqlite3ExprSetColl(pParse, p, &yymsp[-1].minor.yy0); } - yygotominor.yy174 = sqlite3ExprListAppend(pParse,yymsp[-4].minor.yy174, p, &yymsp[-2].minor.yy410); + yygotominor.yy174 = sqlite3ExprListAppend(pParse,yymsp[-4].minor.yy174, p, &yymsp[-2].minor.yy0); sqlite3ExprListCheckLength(pParse, yygotominor.yy174, "index"); if( yygotominor.yy174 ) yygotominor.yy174->a[yygotominor.yy174->nExpr-1].sortOrder = yymsp[0].minor.yy46; } @@ -75698,17 +79512,17 @@ static void yy_reduce( case 240: /* idxlist ::= idxitem collate sortorder */ { Expr *p = 0; - if( yymsp[-1].minor.yy410.n>0 ){ + if( yymsp[-1].minor.yy0.n>0 ){ p = sqlite3PExpr(pParse, TK_COLUMN, 0, 0, 0); - sqlite3ExprSetColl(pParse, p, &yymsp[-1].minor.yy410); + sqlite3ExprSetColl(pParse, p, &yymsp[-1].minor.yy0); } - yygotominor.yy174 = sqlite3ExprListAppend(pParse,0, p, &yymsp[-2].minor.yy410); + yygotominor.yy174 = sqlite3ExprListAppend(pParse,0, p, &yymsp[-2].minor.yy0); sqlite3ExprListCheckLength(pParse, yygotominor.yy174, "index"); if( yygotominor.yy174 ) yygotominor.yy174->a[yygotominor.yy174->nExpr-1].sortOrder = yymsp[0].minor.yy46; } break; case 242: /* collate ::= */ -{yygotominor.yy410.z = 0; yygotominor.yy410.n = 0;} +{yygotominor.yy0.z = 0; yygotominor.yy0.n = 0;} break; case 244: /* cmd ::= DROP INDEX ifexists fullname */ {sqlite3DropIndex(pParse, yymsp[0].minor.yy373, yymsp[-1].minor.yy46);} @@ -75718,35 +79532,33 @@ static void yy_reduce( {sqlite3Vacuum(pParse);} break; case 247: /* cmd ::= PRAGMA nm dbnm EQ nmnum */ -{sqlite3Pragma(pParse,&yymsp[-3].minor.yy410,&yymsp[-2].minor.yy410,&yymsp[0].minor.yy410,0);} - break; case 248: /* cmd ::= PRAGMA nm dbnm EQ ON */ case 249: /* cmd ::= PRAGMA nm dbnm EQ DELETE */ -{sqlite3Pragma(pParse,&yymsp[-3].minor.yy410,&yymsp[-2].minor.yy410,&yymsp[0].minor.yy0,0);} +{sqlite3Pragma(pParse,&yymsp[-3].minor.yy0,&yymsp[-2].minor.yy0,&yymsp[0].minor.yy0,0);} break; case 250: /* cmd ::= PRAGMA nm dbnm EQ minus_num */ { - sqlite3Pragma(pParse,&yymsp[-3].minor.yy410,&yymsp[-2].minor.yy410,&yymsp[0].minor.yy410,1); + sqlite3Pragma(pParse,&yymsp[-3].minor.yy0,&yymsp[-2].minor.yy0,&yymsp[0].minor.yy0,1); } break; case 251: /* cmd ::= PRAGMA nm dbnm LP nmnum RP */ -{sqlite3Pragma(pParse,&yymsp[-4].minor.yy410,&yymsp[-3].minor.yy410,&yymsp[-1].minor.yy410,0);} +{sqlite3Pragma(pParse,&yymsp[-4].minor.yy0,&yymsp[-3].minor.yy0,&yymsp[-1].minor.yy0,0);} break; case 252: /* cmd ::= PRAGMA nm dbnm */ -{sqlite3Pragma(pParse,&yymsp[-1].minor.yy410,&yymsp[0].minor.yy410,0,0);} +{sqlite3Pragma(pParse,&yymsp[-1].minor.yy0,&yymsp[0].minor.yy0,0,0);} break; case 260: /* cmd ::= CREATE trigger_decl BEGIN trigger_cmd_list END */ { Token all; - all.z = yymsp[-3].minor.yy410.z; - all.n = (yymsp[0].minor.yy0.z - yymsp[-3].minor.yy410.z) + yymsp[0].minor.yy0.n; + all.z = yymsp[-3].minor.yy0.z; + all.n = (yymsp[0].minor.yy0.z - yymsp[-3].minor.yy0.z) + yymsp[0].minor.yy0.n; sqlite3FinishTrigger(pParse, yymsp[-1].minor.yy243, &all); } break; case 261: /* trigger_decl ::= temp TRIGGER ifnotexists nm dbnm trigger_time trigger_event ON fullname foreach_clause when_clause */ { - sqlite3BeginTrigger(pParse, &yymsp[-7].minor.yy410, &yymsp[-6].minor.yy410, yymsp[-5].minor.yy46, yymsp[-4].minor.yy370.a, yymsp[-4].minor.yy370.b, yymsp[-2].minor.yy373, yymsp[0].minor.yy172, yymsp[-10].minor.yy46, yymsp[-8].minor.yy46); - yygotominor.yy410 = (yymsp[-6].minor.yy410.n==0?yymsp[-7].minor.yy410:yymsp[-6].minor.yy410); + sqlite3BeginTrigger(pParse, &yymsp[-7].minor.yy0, &yymsp[-6].minor.yy0, yymsp[-5].minor.yy46, yymsp[-4].minor.yy370.a, yymsp[-4].minor.yy370.b, yymsp[-2].minor.yy373, yymsp[0].minor.yy172, yymsp[-10].minor.yy46, yymsp[-8].minor.yy46); + yygotominor.yy0 = (yymsp[-6].minor.yy0.n==0?yymsp[-7].minor.yy0:yymsp[-6].minor.yy0); } break; case 262: /* trigger_time ::= BEFORE */ @@ -75789,16 +79601,16 @@ static void yy_reduce( { yygotominor.yy243 = 0; } break; case 275: /* trigger_cmd ::= UPDATE orconf nm SET setlist where_opt */ -{ yygotominor.yy243 = sqlite3TriggerUpdateStep(pParse->db, &yymsp[-3].minor.yy410, yymsp[-1].minor.yy174, yymsp[0].minor.yy172, yymsp[-4].minor.yy46); } +{ yygotominor.yy243 = sqlite3TriggerUpdateStep(pParse->db, &yymsp[-3].minor.yy0, yymsp[-1].minor.yy174, yymsp[0].minor.yy172, yymsp[-4].minor.yy46); } break; case 276: /* trigger_cmd ::= insert_cmd INTO nm inscollist_opt VALUES LP itemlist RP */ -{yygotominor.yy243 = sqlite3TriggerInsertStep(pParse->db, &yymsp[-5].minor.yy410, yymsp[-4].minor.yy432, yymsp[-1].minor.yy174, 0, yymsp[-7].minor.yy46);} +{yygotominor.yy243 = sqlite3TriggerInsertStep(pParse->db, &yymsp[-5].minor.yy0, yymsp[-4].minor.yy432, yymsp[-1].minor.yy174, 0, yymsp[-7].minor.yy46);} break; case 277: /* trigger_cmd ::= insert_cmd INTO nm inscollist_opt select */ -{yygotominor.yy243 = sqlite3TriggerInsertStep(pParse->db, &yymsp[-2].minor.yy410, yymsp[-1].minor.yy432, 0, yymsp[0].minor.yy219, yymsp[-4].minor.yy46);} +{yygotominor.yy243 = sqlite3TriggerInsertStep(pParse->db, &yymsp[-2].minor.yy0, yymsp[-1].minor.yy432, 0, yymsp[0].minor.yy219, yymsp[-4].minor.yy46);} break; case 278: /* trigger_cmd ::= DELETE FROM nm where_opt */ -{yygotominor.yy243 = sqlite3TriggerDeleteStep(pParse->db, &yymsp[-1].minor.yy410, yymsp[0].minor.yy172);} +{yygotominor.yy243 = sqlite3TriggerDeleteStep(pParse->db, &yymsp[-1].minor.yy0, yymsp[0].minor.yy172);} break; case 279: /* trigger_cmd ::= select */ {yygotominor.yy243 = sqlite3TriggerSelectStep(pParse->db, yymsp[0].minor.yy219); } @@ -75814,7 +79626,7 @@ static void yy_reduce( break; case 281: /* expr ::= RAISE LP raisetype COMMA nm RP */ { - yygotominor.yy172 = sqlite3PExpr(pParse, TK_RAISE, 0, 0, &yymsp[-1].minor.yy410); + yygotominor.yy172 = sqlite3PExpr(pParse, TK_RAISE, 0, 0, &yymsp[-1].minor.yy0); if( yygotominor.yy172 ) { yygotominor.yy172->iColumn = yymsp[-3].minor.yy46; sqlite3ExprSpan(yygotominor.yy172, &yymsp[-5].minor.yy0, &yymsp[0].minor.yy0); @@ -75846,22 +79658,22 @@ static void yy_reduce( {sqlite3Reindex(pParse, 0, 0);} break; case 293: /* cmd ::= REINDEX nm dbnm */ -{sqlite3Reindex(pParse, &yymsp[-1].minor.yy410, &yymsp[0].minor.yy410);} +{sqlite3Reindex(pParse, &yymsp[-1].minor.yy0, &yymsp[0].minor.yy0);} break; case 294: /* cmd ::= ANALYZE */ {sqlite3Analyze(pParse, 0, 0);} break; case 295: /* cmd ::= ANALYZE nm dbnm */ -{sqlite3Analyze(pParse, &yymsp[-1].minor.yy410, &yymsp[0].minor.yy410);} +{sqlite3Analyze(pParse, &yymsp[-1].minor.yy0, &yymsp[0].minor.yy0);} break; case 296: /* cmd ::= ALTER TABLE fullname RENAME TO nm */ { - sqlite3AlterRenameTable(pParse,yymsp[-3].minor.yy373,&yymsp[0].minor.yy410); + sqlite3AlterRenameTable(pParse,yymsp[-3].minor.yy373,&yymsp[0].minor.yy0); } break; case 297: /* cmd ::= ALTER TABLE add_column_fullname ADD kwcolumn_opt column */ { - sqlite3AlterFinishAddColumn(pParse, &yymsp[0].minor.yy410); + sqlite3AlterFinishAddColumn(pParse, &yymsp[0].minor.yy0); } break; case 298: /* add_column_fullname ::= fullname */ @@ -75877,7 +79689,7 @@ static void yy_reduce( break; case 303: /* create_vtab ::= CREATE VIRTUAL TABLE nm dbnm USING nm */ { - sqlite3VtabBeginParse(pParse, &yymsp[-3].minor.yy410, &yymsp[-2].minor.yy410, &yymsp[0].minor.yy410); + sqlite3VtabBeginParse(pParse, &yymsp[-3].minor.yy0, &yymsp[-2].minor.yy0, &yymsp[0].minor.yy0); } break; case 306: /* vtabarg ::= */ @@ -76079,7 +79891,7 @@ SQLITE_PRIVATE void sqlite3Parser( yyTracePrompt,yyTokenName[yymajor]); } #endif - yy_destructor(yymajor,&yyminorunion); + yy_destructor(yypParser, yymajor,&yyminorunion); yymajor = YYNOCODE; }else{ while( @@ -76092,7 +79904,7 @@ SQLITE_PRIVATE void sqlite3Parser( yy_pop_parser_stack(yypParser); } if( yypParser->yyidx < 0 || yymajor==0 ){ - yy_destructor(yymajor,&yyminorunion); + yy_destructor(yypParser,yymajor,&yyminorunion); yy_parse_failed(yypParser); yymajor = YYNOCODE; }else if( yymx!=YYERRORSYMBOL ){ @@ -76117,7 +79929,7 @@ SQLITE_PRIVATE void sqlite3Parser( yy_syntax_error(yypParser,yymajor,yyminorunion); } yypParser->yyerrcnt = 3; - yy_destructor(yymajor,&yyminorunion); + yy_destructor(yypParser,yymajor,&yyminorunion); if( yyendofinput ){ yy_parse_failed(yypParser); } @@ -76619,9 +80431,9 @@ SQLITE_PRIVATE int sqlite3GetToken(const unsigned char *z, int *tokenType){ /* ** Run the parser on the given SQL string. The parser structure is ** passed in. An SQLITE_ status code is returned. If an error occurs -** and pzErrMsg!=NULL then an error message might be written into -** memory obtained from sqlite3_malloc() and *pzErrMsg made to point to that -** error message. Or maybe not. +** then an and attempt is made to write an error message into +** memory obtained from sqlite3_malloc() and to make *pzErrMsg point to that +** error message. */ SQLITE_PRIVATE int sqlite3RunParser(Parse *pParse, const char *zSql, char **pzErrMsg){ int nErr = 0; @@ -76638,7 +80450,8 @@ SQLITE_PRIVATE int sqlite3RunParser(Parse *pParse, const char *zSql, char **pzEr pParse->rc = SQLITE_OK; pParse->zTail = pParse->zSql = zSql; i = 0; - pEngine = sqlite3ParserAlloc((void*(*)(size_t))sqlite3_malloc); + assert( pzErrMsg!=0 ); + pEngine = sqlite3ParserAlloc((void*(*)(size_t))sqlite3Malloc); if( pEngine==0 ){ db->mallocFailed = 1; return SQLITE_NOMEM; @@ -76665,17 +80478,15 @@ SQLITE_PRIVATE int sqlite3RunParser(Parse *pParse, const char *zSql, char **pzEr case TK_COMMENT: { if( db->u1.isInterrupted ){ pParse->rc = SQLITE_INTERRUPT; - sqlite3SetString(pzErrMsg, "interrupt", (char*)0); + sqlite3SetString(pzErrMsg, db, "interrupt"); goto abort_parse; } break; } case TK_ILLEGAL: { - if( pzErrMsg ){ - sqlite3_free(*pzErrMsg); - *pzErrMsg = sqlite3MPrintf(db, "unrecognized token: \"%T\"", - &pParse->sLastToken); - } + sqlite3DbFree(db, *pzErrMsg); + *pzErrMsg = sqlite3MPrintf(db, "unrecognized token: \"%T\"", + &pParse->sLastToken); nErr++; goto abort_parse; } @@ -76701,18 +80512,23 @@ abort_parse: } sqlite3Parser(pEngine, 0, pParse->sLastToken, pParse); } +#ifdef YYTRACKMAXSTACKDEPTH + sqlite3StatusSet(SQLITE_STATUS_PARSER_STACK, + sqlite3ParserStackPeak(pEngine) + ); +#endif /* YYDEBUG */ sqlite3ParserFree(pEngine, sqlite3_free); if( db->mallocFailed ){ pParse->rc = SQLITE_NOMEM; } if( pParse->rc!=SQLITE_OK && pParse->rc!=SQLITE_DONE && pParse->zErrMsg==0 ){ - sqlite3SetString(&pParse->zErrMsg, sqlite3ErrStr(pParse->rc), (char*)0); + sqlite3SetString(&pParse->zErrMsg, db, "%s", sqlite3ErrStr(pParse->rc)); } if( pParse->zErrMsg ){ - if( pzErrMsg && *pzErrMsg==0 ){ + if( *pzErrMsg==0 ){ *pzErrMsg = pParse->zErrMsg; }else{ - sqlite3_free(pParse->zErrMsg); + sqlite3DbFree(db, pParse->zErrMsg); } pParse->zErrMsg = 0; nErr++; @@ -76723,13 +80539,13 @@ abort_parse: } #ifndef SQLITE_OMIT_SHARED_CACHE if( pParse->nested==0 ){ - sqlite3_free(pParse->aTableLock); + sqlite3DbFree(db, pParse->aTableLock); pParse->aTableLock = 0; pParse->nTableLock = 0; } #endif #ifndef SQLITE_OMIT_VIRTUALTABLE - sqlite3_free(pParse->apVtabLock); + sqlite3DbFree(db, pParse->apVtabLock); #endif if( !IN_DECLARE_VTAB ){ @@ -76740,8 +80556,8 @@ abort_parse: sqlite3DeleteTable(pParse->pNewTable); } - sqlite3DeleteTrigger(pParse->pNewTrigger); - sqlite3_free(pParse->apVarExpr); + sqlite3DeleteTrigger(db, pParse->pNewTrigger); + sqlite3DbFree(db, pParse->apVarExpr); if( nErr>0 && (pParse->rc==SQLITE_OK || pParse->rc==SQLITE_DONE) ){ pParse->rc = SQLITE_ERROR; } @@ -77009,11 +80825,17 @@ SQLITE_API int sqlite3_complete16(const void *zSql){ char const *zSql8; int rc = SQLITE_NOMEM; +#ifndef SQLITE_OMIT_AUTOINIT + rc = sqlite3_initialize(); + if( rc ) return rc; +#endif pVal = sqlite3ValueNew(0); sqlite3ValueSetStr(pVal, -1, zSql, SQLITE_UTF16NATIVE, SQLITE_STATIC); zSql8 = sqlite3ValueText(pVal, SQLITE_UTF8); if( zSql8 ){ rc = sqlite3_complete(zSql8); + }else{ + rc = SQLITE_NOMEM; } sqlite3ValueFree(pVal); return sqlite3ApiExit(0, rc); @@ -77041,6 +80863,7 @@ SQLITE_API int sqlite3_complete16(const void *zSql){ ** ** $Id$ */ + #ifdef SQLITE_ENABLE_FTS3 /************** Include fts3.h in the middle of main.c ***********************/ /************** Begin file fts3.h ********************************************/ @@ -77073,6 +80896,38 @@ SQLITE_PRIVATE int sqlite3Fts3Init(sqlite3 *db); /************** End of fts3.h ************************************************/ /************** Continuing where we left off in main.c ***********************/ #endif +#ifdef SQLITE_ENABLE_RTREE +/************** Include rtree.h in the middle of main.c **********************/ +/************** Begin file rtree.h *******************************************/ +/* +** 2008 May 26 +** +** The author disclaims copyright to this source code. In place of +** a legal notice, here is a blessing: +** +** May you do good and not evil. +** May you find forgiveness for yourself and forgive others. +** May you share freely, never taking more than you give. +** +****************************************************************************** +** +** This header file is used by programs that want to link against the +** RTREE library. All it does is declare the sqlite3RtreeInit() interface. +*/ + +#if 0 +extern "C" { +#endif /* __cplusplus */ + +SQLITE_PRIVATE int sqlite3RtreeInit(sqlite3 *db); + +#if 0 +} /* extern "C" */ +#endif /* __cplusplus */ + +/************** End of rtree.h ***********************************************/ +/************** Continuing where we left off in main.c ***********************/ +#endif /* ** The version of the library @@ -77102,6 +80957,318 @@ SQLITE_PRIVATE void (*sqlite3IoTrace)(const char*, ...) = 0; SQLITE_API char *sqlite3_temp_directory = 0; /* +** Initialize SQLite. +** +** This routine must be called to initialize the memory allocation, +** VFS, and mutex subsystesms prior to doing any serious work with +** SQLite. But as long as you do not compile with SQLITE_OMIT_AUTOINIT +** this routine will be called automatically by key routines such as +** sqlite3_open(). +** +** This routine is a no-op except on its very first call for the process, +** or for the first call after a call to sqlite3_shutdown. +*/ +SQLITE_API int sqlite3_initialize(void){ + static int inProgress = 0; + int rc; + + /* If SQLite is already initialized, this call is a no-op. */ + if( sqlite3Config.isInit ) return SQLITE_OK; + + /* Make sure the mutex system is initialized. */ + rc = sqlite3MutexInit(); + + if( rc==SQLITE_OK ){ + + /* Initialize the malloc() system and the recursive pInitMutex mutex. + ** This operation is protected by the STATIC_MASTER mutex. + */ + sqlite3_mutex *pMaster = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER); + sqlite3_mutex_enter(pMaster); + if( !sqlite3Config.isMallocInit ){ + rc = sqlite3MallocInit(); + } + if( rc==SQLITE_OK ){ + sqlite3Config.isMallocInit = 1; + if( !sqlite3Config.pInitMutex ){ + sqlite3Config.pInitMutex = sqlite3MutexAlloc(SQLITE_MUTEX_RECURSIVE); + if( sqlite3Config.bCoreMutex && !sqlite3Config.pInitMutex ){ + rc = SQLITE_NOMEM; + } + } + } + sqlite3_mutex_leave(pMaster); + if( rc!=SQLITE_OK ){ + return rc; + } + + /* Enter the recursive pInitMutex mutex. After doing so, if the + ** sqlite3Config.isInit flag is true, then some other thread has + ** finished doing the initialization. If the inProgress flag is + ** true, then this function is being called recursively from within + ** the sqlite3_os_init() call below. In either case, exit early. + */ + sqlite3_mutex_enter(sqlite3Config.pInitMutex); + if( sqlite3Config.isInit || inProgress ){ + sqlite3_mutex_leave(sqlite3Config.pInitMutex); + return SQLITE_OK; + } + sqlite3StatusReset(); + inProgress = 1; + rc = sqlite3_os_init(); + inProgress = 0; + sqlite3Config.isInit = (rc==SQLITE_OK ? 1 : 0); + sqlite3_mutex_leave(sqlite3Config.pInitMutex); + } + + /* Check NaN support. */ +#ifndef NDEBUG + /* This section of code's only "output" is via assert() statements. */ + if ( rc==SQLITE_OK ){ + u64 x = (((u64)1)<<63)-1; + double y; + assert(sizeof(x)==8); + assert(sizeof(x)==sizeof(y)); + memcpy(&y, &x, 8); + assert( sqlite3IsNaN(y) ); + } +#endif + + return rc; +} + +/* +** Undo the effects of sqlite3_initialize(). Must not be called while +** there are outstanding database connections or memory allocations or +** while any part of SQLite is otherwise in use in any thread. This +** routine is not threadsafe. Not by a long shot. +*/ +SQLITE_API int sqlite3_shutdown(void){ + sqlite3_mutex_free(sqlite3Config.pInitMutex); + sqlite3Config.pInitMutex = 0; + sqlite3Config.isMallocInit = 0; + if( sqlite3Config.isInit ){ + sqlite3_os_end(); + } + if( sqlite3Config.m.xShutdown ){ + sqlite3MallocEnd(); + } + if( sqlite3Config.mutex.xMutexEnd ){ + sqlite3MutexEnd(); + } + sqlite3Config.isInit = 0; + return SQLITE_OK; +} + +/* +** This API allows applications to modify the global configuration of +** the SQLite library at run-time. +** +** This routine should only be called when there are no outstanding +** database connections or memory allocations. This routine is not +** threadsafe. Failure to heed these warnings can lead to unpredictable +** behavior. +*/ +SQLITE_API int sqlite3_config(int op, ...){ + va_list ap; + int rc = SQLITE_OK; + + /* sqlite3_config() shall return SQLITE_MISUSE if it is invoked while + ** the SQLite library is in use. */ + if( sqlite3Config.isInit ) return SQLITE_MISUSE; + + va_start(ap, op); + switch( op ){ + case SQLITE_CONFIG_SINGLETHREAD: { + /* Disable all mutexing */ + sqlite3Config.bCoreMutex = 0; + sqlite3Config.bFullMutex = 0; + break; + } + case SQLITE_CONFIG_MULTITHREAD: { + /* Disable mutexing of database connections */ + /* Enable mutexing of core data structures */ + sqlite3Config.bCoreMutex = 1; + sqlite3Config.bFullMutex = 0; + break; + } + case SQLITE_CONFIG_SERIALIZED: { + /* Enable all mutexing */ + sqlite3Config.bCoreMutex = 1; + sqlite3Config.bFullMutex = 1; + break; + } + case SQLITE_CONFIG_MALLOC: { + /* Specify an alternative malloc implementation */ + sqlite3Config.m = *va_arg(ap, sqlite3_mem_methods*); + break; + } + case SQLITE_CONFIG_GETMALLOC: { + /* Retrieve the current malloc() implementation */ + if( sqlite3Config.m.xMalloc==0 ) sqlite3MemSetDefault(); + *va_arg(ap, sqlite3_mem_methods*) = sqlite3Config.m; + break; + } + case SQLITE_CONFIG_MUTEX: { + /* Specify an alternative mutex implementation */ + sqlite3Config.mutex = *va_arg(ap, sqlite3_mutex_methods*); + break; + } + case SQLITE_CONFIG_GETMUTEX: { + /* Retrieve the current mutex implementation */ + *va_arg(ap, sqlite3_mutex_methods*) = sqlite3Config.mutex; + break; + } + case SQLITE_CONFIG_MEMSTATUS: { + /* Enable or disable the malloc status collection */ + sqlite3Config.bMemstat = va_arg(ap, int); + break; + } + case SQLITE_CONFIG_SCRATCH: { + /* Designate a buffer for scratch memory space */ + sqlite3Config.pScratch = va_arg(ap, void*); + sqlite3Config.szScratch = va_arg(ap, int); + sqlite3Config.nScratch = va_arg(ap, int); + break; + } + case SQLITE_CONFIG_PAGECACHE: { + /* Designate a buffer for scratch memory space */ + sqlite3Config.pPage = va_arg(ap, void*); + sqlite3Config.szPage = va_arg(ap, int); + sqlite3Config.nPage = va_arg(ap, int); + break; + } + +#if defined(SQLITE_ENABLE_MEMSYS3) || defined(SQLITE_ENABLE_MEMSYS5) + case SQLITE_CONFIG_HEAP: { + /* Designate a buffer for heap memory space */ + sqlite3Config.pHeap = va_arg(ap, void*); + sqlite3Config.nHeap = va_arg(ap, int); + sqlite3Config.mnReq = va_arg(ap, int); + + if( sqlite3Config.pHeap==0 ){ + /* If the heap pointer is NULL, then restore the malloc implementation + ** back to NULL pointers too. This will cause the malloc to go + ** back to its default implementation when sqlite3_initialize() is + ** run. + */ + memset(&sqlite3Config.m, 0, sizeof(sqlite3Config.m)); + }else{ + /* The heap pointer is not NULL, then install one of the + ** mem5.c/mem3.c methods. If neither ENABLE_MEMSYS3 nor + ** ENABLE_MEMSYS5 is defined, return an error. + ** the default case and return an error. + */ +#ifdef SQLITE_ENABLE_MEMSYS3 + sqlite3Config.m = *sqlite3MemGetMemsys3(); +#endif +#ifdef SQLITE_ENABLE_MEMSYS5 + sqlite3Config.m = *sqlite3MemGetMemsys5(); +#endif + } + break; + } +#endif + +#if defined(SQLITE_ENABLE_MEMSYS6) + case SQLITE_CONFIG_CHUNKALLOC: { + sqlite3Config.nSmall = va_arg(ap, int); + sqlite3Config.m = *sqlite3MemGetMemsys6(); + break; + } +#endif + + case SQLITE_CONFIG_LOOKASIDE: { + sqlite3Config.szLookaside = va_arg(ap, int); + sqlite3Config.nLookaside = va_arg(ap, int); + break; + } + + default: { + rc = SQLITE_ERROR; + break; + } + } + va_end(ap); + return rc; +} + +/* +** Set up the lookaside buffers for a database connection. +** Return SQLITE_OK on success. +** If lookaside is already active, return SQLITE_BUSY. +** +** The sz parameter is the number of bytes in each lookaside slot. +** The cnt parameter is the number of slots. If pStart is NULL the +** space for the lookaside memory is obtained from sqlite3_malloc(). +** If pStart is not NULL then it is sz*cnt bytes of memory to use for +** the lookaside memory. +*/ +static int setupLookaside(sqlite3 *db, void *pBuf, int sz, int cnt){ + void *pStart; + if( db->lookaside.nOut ){ + return SQLITE_BUSY; + } + if( sz<0 ) sz = 0; + if( cnt<0 ) cnt = 0; + sz = (sz+7)&~7; + if( pBuf==0 ){ + sqlite3BeginBenignMalloc(); + pStart = sqlite3Malloc( sz*cnt ); + sqlite3EndBenignMalloc(); + }else{ + pStart = pBuf; + } + if( db->lookaside.bMalloced ){ + sqlite3_free(db->lookaside.pStart); + } + db->lookaside.pStart = pStart; + db->lookaside.pFree = 0; + db->lookaside.sz = sz; + db->lookaside.bMalloced = pBuf==0; + if( pStart ){ + int i; + LookasideSlot *p; + p = (LookasideSlot*)pStart; + for(i=cnt-1; i>=0; i--){ + p->pNext = db->lookaside.pFree; + db->lookaside.pFree = p; + p = (LookasideSlot*)&((u8*)p)[sz]; + } + db->lookaside.pEnd = p; + db->lookaside.bEnabled = 1; + }else{ + db->lookaside.pEnd = 0; + db->lookaside.bEnabled = 0; + } + return SQLITE_OK; +} + +/* +** Configuration settings for an individual database connection +*/ +SQLITE_API int sqlite3_db_config(sqlite3 *db, int op, ...){ + va_list ap; + int rc; + va_start(ap, op); + switch( op ){ + case SQLITE_DBCONFIG_LOOKASIDE: { + void *pBuf = va_arg(ap, void*); + int sz = va_arg(ap, int); + int cnt = va_arg(ap, int); + rc = setupLookaside(db, pBuf, sz, cnt); + break; + } + default: { + rc = SQLITE_ERROR; + break; + } + } + va_end(ap); + return rc; +} + +/* ** Routine needed to support the testcase() macro. */ #ifdef SQLITE_COVERAGE_TEST @@ -77250,7 +81417,7 @@ SQLITE_API int sqlite3_close(sqlite3 *db){ FuncDef *pFunc, *pNext; for(pFunc = (FuncDef*)sqliteHashData(i); pFunc; pFunc=pNext){ pNext = pFunc->pNext; - sqlite3_free(pFunc); + sqlite3DbFree(db, pFunc); } } @@ -77262,7 +81429,7 @@ SQLITE_API int sqlite3_close(sqlite3 *db){ pColl[j].xDel(pColl[j].pUser); } } - sqlite3_free(pColl); + sqlite3DbFree(db, pColl); } sqlite3HashClear(&db->aCollSeq); #ifndef SQLITE_OMIT_VIRTUALTABLE @@ -77271,7 +81438,7 @@ SQLITE_API int sqlite3_close(sqlite3 *db){ if( pMod->xDestroy ){ pMod->xDestroy(pMod->pAux); } - sqlite3_free(pMod); + sqlite3DbFree(db, pMod); } sqlite3HashClear(&db->aModule); #endif @@ -77291,10 +81458,13 @@ SQLITE_API int sqlite3_close(sqlite3 *db){ ** the same sqliteMalloc() as the one that allocates the database ** structure? */ - sqlite3_free(db->aDb[1].pSchema); + sqlite3DbFree(db, db->aDb[1].pSchema); sqlite3_mutex_leave(db->mutex); db->magic = SQLITE_MAGIC_CLOSED; sqlite3_mutex_free(db->mutex); + if( db->lookaside.bMalloced ){ + sqlite3_free(db->lookaside.pStart); + } sqlite3_free(db); return SQLITE_OK; } @@ -77306,7 +81476,7 @@ SQLITE_PRIVATE void sqlite3RollbackAll(sqlite3 *db){ int i; int inTrans = 0; assert( sqlite3_mutex_held(db->mutex) ); - sqlite3FaultBeginBenign(SQLITE_FAULTINJECTOR_MALLOC); + sqlite3BeginBenignMalloc(); for(i=0; i<db->nDb; i++){ if( db->aDb[i].pBt ){ if( sqlite3BtreeIsInTrans(db->aDb[i].pBt) ){ @@ -77317,7 +81487,7 @@ SQLITE_PRIVATE void sqlite3RollbackAll(sqlite3 *db){ } } sqlite3VtabRollback(db); - sqlite3FaultEndBenign(SQLITE_FAULTINJECTOR_MALLOC); + sqlite3EndBenignMalloc(); if( db->flags&SQLITE_InternChanges ){ sqlite3ExpirePreparedStatements(db); @@ -77378,7 +81548,7 @@ static int sqliteDefaultBusyCallback( void *ptr, /* Database connection */ int count /* Number of times table has been busy */ ){ -#if OS_WIN || (defined(HAVE_USLEEP) && HAVE_USLEEP) +#if SQLITE_OS_WIN || (defined(HAVE_USLEEP) && HAVE_USLEEP) static const u8 delays[] = { 1, 2, 5, 10, 15, 20, 25, 25, 25, 50, 50, 100 }; static const u8 totals[] = @@ -77422,7 +81592,7 @@ static int sqliteDefaultBusyCallback( */ SQLITE_PRIVATE int sqlite3InvokeBusyHandler(BusyHandler *p){ int rc; - if( p==0 || p->xFunc==0 || p->nBusy<0 ) return 0; + if( NEVER(p==0) || p->xFunc==0 || p->nBusy<0 ) return 0; rc = p->xFunc(p->pArg, p->nBusy); if( rc==0 ){ p->nBusy = -1; @@ -77461,19 +81631,17 @@ SQLITE_API void sqlite3_progress_handler( int (*xProgress)(void*), void *pArg ){ - if( sqlite3SafetyCheckOk(db) ){ - sqlite3_mutex_enter(db->mutex); - if( nOps>0 ){ - db->xProgress = xProgress; - db->nProgressOps = nOps; - db->pProgressArg = pArg; - }else{ - db->xProgress = 0; - db->nProgressOps = 0; - db->pProgressArg = 0; - } - sqlite3_mutex_leave(db->mutex); + sqlite3_mutex_enter(db->mutex); + if( nOps>0 ){ + db->xProgress = xProgress; + db->nProgressOps = nOps; + db->pProgressArg = pArg; + }else{ + db->xProgress = 0; + db->nProgressOps = 0; + db->pProgressArg = 0; } + sqlite3_mutex_leave(db->mutex); } #endif @@ -77496,9 +81664,7 @@ SQLITE_API int sqlite3_busy_timeout(sqlite3 *db, int ms){ ** Cause any pending operation to stop at its earliest opportunity. */ SQLITE_API void sqlite3_interrupt(sqlite3 *db){ - if( sqlite3SafetyCheckOk(db) ){ - db->u1.isInterrupted = 1; - } + db->u1.isInterrupted = 1; } @@ -77526,8 +81692,8 @@ SQLITE_PRIVATE int sqlite3CreateFunc( (xFunc && (xFinal || xStep)) || (!xFunc && (xFinal && !xStep)) || (!xFunc && (!xFinal && xStep)) || - (nArg<-1 || nArg>127) || - (255<(nName = strlen(zFunctionName))) ){ + (nArg<-1 || nArg>SQLITE_MAX_FUNCTION_ARG) || + (255<(nName = sqlite3Strlen(db, zFunctionName))) ){ sqlite3Error(db, SQLITE_ERROR, "bad parameters"); return SQLITE_ERROR; } @@ -77628,7 +81794,7 @@ SQLITE_API int sqlite3_create_function16( assert( !db->mallocFailed ); zFunc8 = sqlite3Utf16to8(db, zFunctionName, -1); rc = sqlite3CreateFunc(db, zFunc8, nArg, eTextRep, p, xFunc, xStep, xFinal); - sqlite3_free(zFunc8); + sqlite3DbFree(db, zFunc8); rc = sqlite3ApiExit(db, rc); sqlite3_mutex_leave(db->mutex); return rc; @@ -77653,7 +81819,7 @@ SQLITE_API int sqlite3_overload_function( const char *zName, int nArg ){ - int nName = strlen(zName); + int nName = sqlite3Strlen(db, zName); int rc; sqlite3_mutex_enter(db->mutex); if( sqlite3FindFunction(db, zName, nName, nArg, SQLITE_UTF8, 0)==0 ){ @@ -77773,19 +81939,19 @@ SQLITE_API void *sqlite3_rollback_hook( ** ** A virtual database can be either a disk file (that is automatically ** deleted when the file is closed) or it an be held entirely in memory, -** depending on the values of the TEMP_STORE compile-time macro and the +** depending on the values of the SQLITE_TEMP_STORE compile-time macro and the ** db->temp_store variable, according to the following chart: ** -** TEMP_STORE db->temp_store Location of temporary database -** ---------- -------------- ------------------------------ -** 0 any file -** 1 1 file -** 1 2 memory -** 1 0 file -** 2 1 file -** 2 2 memory -** 2 0 memory -** 3 any memory +** SQLITE_TEMP_STORE db->temp_store Location of temporary database +** ----------------- -------------- ------------------------------ +** 0 any file +** 1 1 file +** 1 2 memory +** 1 0 file +** 2 1 file +** 2 2 memory +** 2 0 memory +** 3 any memory */ SQLITE_PRIVATE int sqlite3BtreeFactory( const sqlite3 *db, /* Main database when opening aux otherwise 0 */ @@ -77807,17 +81973,17 @@ SQLITE_PRIVATE int sqlite3BtreeFactory( btFlags |= BTREE_NO_READLOCK; } if( zFilename==0 ){ -#if TEMP_STORE==0 +#if SQLITE_TEMP_STORE==0 /* Do nothing */ #endif #ifndef SQLITE_OMIT_MEMORYDB -#if TEMP_STORE==1 +#if SQLITE_TEMP_STORE==1 if( db->temp_store==2 ) zFilename = ":memory:"; #endif -#if TEMP_STORE==2 +#if SQLITE_TEMP_STORE==2 if( db->temp_store!=1 ) zFilename = ":memory:"; #endif -#if TEMP_STORE==3 +#if SQLITE_TEMP_STORE==3 zFilename = ":memory:"; #endif #endif /* SQLITE_OMIT_MEMORYDB */ @@ -77827,7 +81993,13 @@ SQLITE_PRIVATE int sqlite3BtreeFactory( vfsFlags = (vfsFlags & ~SQLITE_OPEN_MAIN_DB) | SQLITE_OPEN_TEMP_DB; } rc = sqlite3BtreeOpen(zFilename, (sqlite3 *)db, ppBtree, btFlags, vfsFlags); - if( rc==SQLITE_OK ){ + + /* If the B-Tree was successfully opened, set the pager-cache size to the + ** default value. Except, if the call to BtreeOpen() returned a handle + ** open on an existing shared pager-cache, do not change the pager-cache + ** size. + */ + if( rc==SQLITE_OK && 0==sqlite3BtreeSchema(*ppBtree, 0, 0) ){ sqlite3BtreeSetCacheSize(*ppBtree, nCache); } return rc; @@ -77842,12 +82014,13 @@ SQLITE_API const char *sqlite3_errmsg(sqlite3 *db){ if( !db ){ return sqlite3ErrStr(SQLITE_NOMEM); } - if( !sqlite3SafetyCheckSickOrOk(db) || db->errCode==SQLITE_MISUSE ){ + if( !sqlite3SafetyCheckSickOrOk(db) ){ return sqlite3ErrStr(SQLITE_MISUSE); } sqlite3_mutex_enter(db->mutex); assert( !db->mallocFailed ); z = (char*)sqlite3_value_text(db->pErr); + assert( !db->mallocFailed ); if( z==0 ){ z = sqlite3ErrStr(db->errCode); } @@ -77884,7 +82057,7 @@ SQLITE_API const void *sqlite3_errmsg16(sqlite3 *db){ if( !db ){ return (void *)(&outOfMemBe[SQLITE_UTF16NATIVE==SQLITE_UTF16LE?1:0]); } - if( !sqlite3SafetyCheckSickOrOk(db) || db->errCode==SQLITE_MISUSE ){ + if( !sqlite3SafetyCheckSickOrOk(db) ){ return (void *)(&misuseBe[SQLITE_UTF16NATIVE==SQLITE_UTF16LE?1:0]); } sqlite3_mutex_enter(db->mutex); @@ -77895,7 +82068,12 @@ SQLITE_API const void *sqlite3_errmsg16(sqlite3 *db){ SQLITE_UTF8, SQLITE_STATIC); z = sqlite3_value_text16(db->pErr); } - sqlite3ApiExit(0, 0); + /* A malloc() may have failed within the call to sqlite3_value_text16() + ** above. If this is the case, then the db->mallocFailed flag needs to + ** be cleared before returning. Do this directly, instead of via + ** sqlite3ApiExit(), to avoid setting the database handle error message. + */ + db->mallocFailed = 0; sqlite3_mutex_leave(db->mutex); return z; } @@ -77929,6 +82107,7 @@ static int createCollation( ){ CollSeq *pColl; int enc2; + int nName; assert( sqlite3_mutex_held(db->mutex) ); @@ -77940,17 +82119,16 @@ static int createCollation( if( enc2==SQLITE_UTF16 ){ enc2 = SQLITE_UTF16NATIVE; } - if( (enc2&~3)!=0 ){ - sqlite3Error(db, SQLITE_ERROR, "unknown encoding"); - return SQLITE_ERROR; + return SQLITE_MISUSE; } /* Check if this call is removing or replacing an existing collation ** sequence. If so, and there are active VMs, return busy. If there ** are no active VMs, invalidate any pre-compiled statements. */ - pColl = sqlite3FindCollSeq(db, (u8)enc2, zName, strlen(zName), 0); + nName = sqlite3Strlen(db, zName); + pColl = sqlite3FindCollSeq(db, (u8)enc2, zName, nName, 0); if( pColl && pColl->xCmp ){ if( db->activeVdbeCnt ){ sqlite3Error(db, SQLITE_BUSY, @@ -77966,7 +82144,7 @@ static int createCollation( ** to be called. */ if( (pColl->enc & ~SQLITE_UTF16_ALIGNED)==enc2 ){ - CollSeq *aColl = sqlite3HashFind(&db->aCollSeq, zName, strlen(zName)); + CollSeq *aColl = sqlite3HashFind(&db->aCollSeq, zName, nName); int j; for(j=0; j<3; j++){ CollSeq *p = &aColl[j]; @@ -77980,7 +82158,7 @@ static int createCollation( } } - pColl = sqlite3FindCollSeq(db, (u8)enc2, zName, strlen(zName), 1); + pColl = sqlite3FindCollSeq(db, (u8)enc2, zName, nName, 1); if( pColl ){ pColl->xCmp = xCompare; pColl->pUser = pCtx; @@ -78028,8 +82206,8 @@ static const int aHardLimit[] = { #if SQLITE_MAX_VDBE_OP<40 # error SQLITE_MAX_VDBE_OP must be at least 40 #endif -#if SQLITE_MAX_FUNCTION_ARG<0 || SQLITE_MAX_FUNCTION_ARG>255 -# error SQLITE_MAX_FUNCTION_ARG must be between 0 and 255 +#if SQLITE_MAX_FUNCTION_ARG<0 || SQLITE_MAX_FUNCTION_ARG>127 +# error SQLITE_MAX_FUNCTION_ARG must be between 0 and 127 #endif #if SQLITE_MAX_ATTACH<0 || SQLITE_MAX_ATTACH>30 # error SQLITE_MAX_ATTACH must be between 0 and 30 @@ -78081,6 +82259,16 @@ static int openDatabase( sqlite3 *db; int rc; CollSeq *pColl; + int isThreadsafe = 1; + +#ifndef SQLITE_OMIT_AUTOINIT + rc = sqlite3_initialize(); + if( rc ) return rc; +#endif + + if( flags&SQLITE_OPEN_NOMUTEX ){ + isThreadsafe = 0; + } /* Remove harmful bits from the flags parameter */ flags &= ~( SQLITE_OPEN_DELETEONCLOSE | @@ -78090,17 +82278,20 @@ static int openDatabase( SQLITE_OPEN_MAIN_JOURNAL | SQLITE_OPEN_TEMP_JOURNAL | SQLITE_OPEN_SUBJOURNAL | - SQLITE_OPEN_MASTER_JOURNAL + SQLITE_OPEN_MASTER_JOURNAL | + SQLITE_OPEN_NOMUTEX ); /* Allocate the sqlite data structure */ db = sqlite3MallocZero( sizeof(sqlite3) ); if( db==0 ) goto opendb_out; - db->mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_RECURSIVE); - if( db->mutex==0 ){ - sqlite3_free(db); - db = 0; - goto opendb_out; + if( sqlite3Config.bFullMutex && isThreadsafe ){ + db->mutex = sqlite3MutexAlloc(SQLITE_MUTEX_RECURSIVE); + if( db->mutex==0 ){ + sqlite3_free(db); + db = 0; + goto opendb_out; + } } sqlite3_mutex_enter(db->mutex); db->errMask = 0xff; @@ -78108,6 +82299,7 @@ static int openDatabase( db->nDb = 2; db->magic = SQLITE_MAGIC_BUSY; db->aDb = db->aDbStatic; + assert( sizeof(db->aLimit)==sizeof(aHardLimit) ); memcpy(db->aLimit, aHardLimit, sizeof(db->aLimit)); db->autoCommit = 1; @@ -78230,6 +82422,13 @@ static int openDatabase( rc = sqlite3IcuInit(db); } #endif + +#ifdef SQLITE_ENABLE_RTREE + if( !db->mallocFailed && rc==SQLITE_OK){ + rc = sqlite3RtreeInit(db); + } +#endif + sqlite3Error(db, rc, 0); /* -DSQLITE_DEFAULT_LOCKING_MODE=1 makes EXCLUSIVE the default locking @@ -78242,9 +82441,12 @@ static int openDatabase( SQLITE_DEFAULT_LOCKING_MODE); #endif + /* Enable the lookaside-malloc subsystem */ + setupLookaside(db, 0, sqlite3Config.szLookaside, sqlite3Config.nLookaside); + opendb_out: if( db ){ - assert( db->mutex!=0 ); + assert( db->mutex!=0 || isThreadsafe==0 || sqlite3Config.bFullMutex==0 ); sqlite3_mutex_leave(db->mutex); } if( SQLITE_NOMEM==(rc = sqlite3_errcode(db)) ){ @@ -78284,11 +82486,15 @@ SQLITE_API int sqlite3_open16( ){ char const *zFilename8; /* zFilename encoded in UTF-8 instead of UTF-16 */ sqlite3_value *pVal; - int rc = SQLITE_NOMEM; + int rc; assert( zFilename ); assert( ppDb ); *ppDb = 0; +#ifndef SQLITE_OMIT_AUTOINIT + rc = sqlite3_initialize(); + if( rc ) return rc; +#endif pVal = sqlite3ValueNew(0); sqlite3ValueSetStr(pVal, -1, zFilename, SQLITE_UTF16NATIVE, SQLITE_STATIC); zFilename8 = sqlite3ValueText(pVal, SQLITE_UTF8); @@ -78299,6 +82505,8 @@ SQLITE_API int sqlite3_open16( if( rc==SQLITE_OK && !DbHasProperty(*ppDb, 0, DB_SchemaLoaded) ){ ENC(*ppDb) = SQLITE_UTF16NATIVE; } + }else{ + rc = SQLITE_NOMEM; } sqlite3ValueFree(pVal); @@ -78351,7 +82559,7 @@ SQLITE_API int sqlite3_create_collation_v2( */ SQLITE_API int sqlite3_create_collation16( sqlite3* db, - const char *zName, + const void *zName, int enc, void* pCtx, int(*xCompare)(void*,int,const void*,int,const void*) @@ -78363,7 +82571,7 @@ SQLITE_API int sqlite3_create_collation16( zName8 = sqlite3Utf16to8(db, zName, -1); if( zName8 ){ rc = createCollation(db, zName8, enc, pCtx, xCompare, 0); - sqlite3_free(zName8); + sqlite3DbFree(db, zName8); } rc = sqlite3ApiExit(db, rc); sqlite3_mutex_leave(db->mutex); @@ -78464,7 +82672,7 @@ SQLITE_API int sqlite3_table_column_metadata( char const **pzCollSeq, /* OUTPUT: Collation sequence name */ int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ int *pPrimaryKey, /* OUTPUT: True if column part of PK */ - int *pAutoinc /* OUTPUT: True if colums is auto-increment */ + int *pAutoinc /* OUTPUT: True if column is auto-increment */ ){ int rc; char *zErrMsg = 0; @@ -78527,9 +82735,9 @@ SQLITE_API int sqlite3_table_column_metadata( if( pCol ){ zDataType = pCol->zType; zCollSeq = pCol->zColl; - notnull = (pCol->notNull?1:0); - primarykey = (pCol->isPrimKey?1:0); - autoinc = ((pTab->iPKey==iCol && pTab->autoInc)?1:0); + notnull = pCol->notNull!=0; + primarykey = pCol->isPrimKey!=0; + autoinc = pTab->iPKey==iCol && pTab->autoInc; }else{ zDataType = "INTEGER"; primarykey = 1; @@ -78552,12 +82760,13 @@ error_out: if( pAutoinc ) *pAutoinc = autoinc; if( SQLITE_OK==rc && !pTab ){ - sqlite3SetString(&zErrMsg, "no such table column: ", zTableName, ".", - zColumnName, 0); + sqlite3DbFree(db, zErrMsg); + zErrMsg = sqlite3MPrintf(db, "no such table column: %s.%s", zTableName, + zColumnName); rc = SQLITE_ERROR; } sqlite3Error(db, rc, (zErrMsg?"%s":0), zErrMsg); - sqlite3_free(zErrMsg); + sqlite3DbFree(db, zErrMsg); rc = sqlite3ApiExit(db, rc); sqlite3_mutex_leave(db->mutex); return rc; @@ -78571,6 +82780,7 @@ SQLITE_API int sqlite3_sleep(int ms){ sqlite3_vfs *pVfs; int rc; pVfs = sqlite3_vfs_find(0); + if( pVfs==0 ) return 0; /* This function works in milliseconds, but the underlying OsSleep() ** API uses microseconds. Hence the 1000's. @@ -78632,58 +82842,6 @@ SQLITE_API int sqlite3_test_control(int op, ...){ va_list ap; va_start(ap, op); switch( op ){ - /* - ** sqlite3_test_control(FAULT_CONFIG, fault_id, nDelay, nRepeat) - ** - ** Configure a fault injector. The specific fault injector is - ** identified by the fault_id argument. (ex: SQLITE_FAULTINJECTOR_MALLOC) - ** The fault will occur after a delay of nDelay calls. The fault - ** will repeat nRepeat times. - */ - case SQLITE_TESTCTRL_FAULT_CONFIG: { - int id = va_arg(ap, int); - int nDelay = va_arg(ap, int); - int nRepeat = va_arg(ap, int); - sqlite3FaultConfig(id, nDelay, nRepeat); - break; - } - - /* - ** sqlite3_test_control(FAULT_FAILURES, fault_id) - ** - ** Return the number of faults (both hard and benign faults) that have - ** occurred since the injector identified by fault_id) was last configured. - */ - case SQLITE_TESTCTRL_FAULT_FAILURES: { - int id = va_arg(ap, int); - rc = sqlite3FaultFailures(id); - break; - } - - /* - ** sqlite3_test_control(FAULT_BENIGN_FAILURES, fault_id) - ** - ** Return the number of benign faults that have occurred since the - ** injector identified by fault_id was last configured. - */ - case SQLITE_TESTCTRL_FAULT_BENIGN_FAILURES: { - int id = va_arg(ap, int); - rc = sqlite3FaultBenignFailures(id); - break; - } - - /* - ** sqlite3_test_control(FAULT_PENDING, fault_id) - ** - ** Return the number of successes that will occur before the next - ** scheduled failure on fault injector fault_id. - ** If no failures are scheduled, return -1. - */ - case SQLITE_TESTCTRL_FAULT_PENDING: { - int id = va_arg(ap, int); - rc = sqlite3FaultPending(id); - break; - } /* ** Save the current state of the PRNG. @@ -78727,6 +82885,22 @@ SQLITE_API int sqlite3_test_control(int op, ...){ rc = sqlite3BitvecBuiltinTest(sz, aProg); break; } + + /* + ** sqlite3_test_control(BENIGN_MALLOC_HOOKS, xBegin, xEnd) + ** + ** Register hooks to call to indicate which malloc() failures + ** are benign. + */ + case SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS: { + typedef void (*void_function)(void); + void_function xBenignBegin; + void_function xBenignEnd; + xBenignBegin = va_arg(ap, void_function); + xBenignEnd = va_arg(ap, void_function); + sqlite3BenignMallocHooks(xBenignBegin, xBenignEnd); + break; + } } va_end(ap); #endif /* SQLITE_OMIT_BUILTIN_TEST */ @@ -80897,17 +85071,22 @@ typedef enum fulltext_statement { CONTENT_SELECT_STMT, CONTENT_UPDATE_STMT, CONTENT_DELETE_STMT, + CONTENT_EXISTS_STMT, BLOCK_INSERT_STMT, BLOCK_SELECT_STMT, BLOCK_DELETE_STMT, + BLOCK_DELETE_ALL_STMT, SEGDIR_MAX_INDEX_STMT, SEGDIR_SET_STMT, - SEGDIR_SELECT_STMT, + SEGDIR_SELECT_LEVEL_STMT, SEGDIR_SPAN_STMT, SEGDIR_DELETE_STMT, + SEGDIR_SELECT_SEGMENT_STMT, SEGDIR_SELECT_ALL_STMT, + SEGDIR_DELETE_ALL_STMT, + SEGDIR_COUNT_STMT, MAX_STMT /* Always at end! */ } fulltext_statement; @@ -80922,23 +85101,35 @@ static const char *const fulltext_zStatement[MAX_STMT] = { /* CONTENT_SELECT */ NULL, /* generated in contentSelectStatement() */ /* CONTENT_UPDATE */ NULL, /* generated in contentUpdateStatement() */ /* CONTENT_DELETE */ "delete from %_content where docid = ?", + /* CONTENT_EXISTS */ "select docid from %_content limit 1", /* BLOCK_INSERT */ "insert into %_segments (blockid, block) values (null, ?)", /* BLOCK_SELECT */ "select block from %_segments where blockid = ?", /* BLOCK_DELETE */ "delete from %_segments where blockid between ? and ?", + /* BLOCK_DELETE_ALL */ "delete from %_segments", /* SEGDIR_MAX_INDEX */ "select max(idx) from %_segdir where level = ?", /* SEGDIR_SET */ "insert into %_segdir values (?, ?, ?, ?, ?, ?)", - /* SEGDIR_SELECT */ + /* SEGDIR_SELECT_LEVEL */ "select start_block, leaves_end_block, root from %_segdir " " where level = ? order by idx", /* SEGDIR_SPAN */ "select min(start_block), max(end_block) from %_segdir " " where level = ? and start_block <> 0", /* SEGDIR_DELETE */ "delete from %_segdir where level = ?", + + /* NOTE(shess): The first three results of the following two + ** statements must match. + */ + /* SEGDIR_SELECT_SEGMENT */ + "select start_block, leaves_end_block, root from %_segdir " + " where level = ? and idx = ?", /* SEGDIR_SELECT_ALL */ - "select root, leaves_end_block from %_segdir order by level desc, idx", + "select start_block, leaves_end_block, root from %_segdir " + " order by level desc, idx asc", + /* SEGDIR_DELETE_ALL */ "delete from %_segdir", + /* SEGDIR_COUNT */ "select count(*), ifnull(max(level),0) from %_segdir", }; /* @@ -81103,15 +85294,18 @@ static int sql_single_step(sqlite3_stmt *s){ } /* Like sql_get_statement(), but for special replicated LEAF_SELECT -** statements. +** statements. idx -1 is a special case for an uncached version of +** the statement (used in the optimize implementation). */ /* TODO(shess) Write version for generic statements and then share ** that between the cached-statement functions. */ static int sql_get_leaf_statement(fulltext_vtab *v, int idx, sqlite3_stmt **ppStmt){ - assert( idx>=0 && idx<MERGE_COUNT ); - if( v->pLeafSelectStmts[idx]==NULL ){ + assert( idx>=-1 && idx<MERGE_COUNT ); + if( idx==-1 ){ + return sql_prepare(v->db, v->zDb, v->zName, ppStmt, LEAF_SELECT); + }else if( v->pLeafSelectStmts[idx]==NULL ){ int rc = sql_prepare(v->db, v->zDb, v->zName, &v->pLeafSelectStmts[idx], LEAF_SELECT); if( rc!=SQLITE_OK ) return rc; @@ -81232,6 +85426,25 @@ static int content_delete(fulltext_vtab *v, sqlite_int64 iDocid){ return sql_single_step(s); } +/* Returns SQLITE_ROW if any rows exist in %_content, SQLITE_DONE if +** no rows exist, and any error in case of failure. +*/ +static int content_exists(fulltext_vtab *v){ + sqlite3_stmt *s; + int rc = sql_get_statement(v, CONTENT_EXISTS_STMT, &s); + if( rc!=SQLITE_OK ) return rc; + + rc = sqlite3_step(s); + if( rc!=SQLITE_ROW ) return rc; + + /* We expect only one row. We must execute another sqlite3_step() + * to complete the iteration; otherwise the table will remain locked. */ + rc = sqlite3_step(s); + if( rc==SQLITE_DONE ) return SQLITE_ROW; + if( rc==SQLITE_ROW ) return SQLITE_ERROR; + return rc; +} + /* insert into %_segments values ([pData]) ** returns assigned blockid in *piBlockid */ @@ -81406,6 +85619,54 @@ static int segdir_delete(fulltext_vtab *v, int iLevel){ return sql_single_step(s); } +/* Delete entire fts index, SQLITE_OK on success, relevant error on +** failure. +*/ +static int segdir_delete_all(fulltext_vtab *v){ + sqlite3_stmt *s; + int rc = sql_get_statement(v, SEGDIR_DELETE_ALL_STMT, &s); + if( rc!=SQLITE_OK ) return rc; + + rc = sql_single_step(s); + if( rc!=SQLITE_OK ) return rc; + + rc = sql_get_statement(v, BLOCK_DELETE_ALL_STMT, &s); + if( rc!=SQLITE_OK ) return rc; + + return sql_single_step(s); +} + +/* Returns SQLITE_OK with *pnSegments set to the number of entries in +** %_segdir and *piMaxLevel set to the highest level which has a +** segment. Otherwise returns the SQLite error which caused failure. +*/ +static int segdir_count(fulltext_vtab *v, int *pnSegments, int *piMaxLevel){ + sqlite3_stmt *s; + int rc = sql_get_statement(v, SEGDIR_COUNT_STMT, &s); + if( rc!=SQLITE_OK ) return rc; + + rc = sqlite3_step(s); + /* TODO(shess): This case should not be possible? Should stronger + ** measures be taken if it happens? + */ + if( rc==SQLITE_DONE ){ + *pnSegments = 0; + *piMaxLevel = 0; + return SQLITE_OK; + } + if( rc!=SQLITE_ROW ) return rc; + + *pnSegments = sqlite3_column_int(s, 0); + *piMaxLevel = sqlite3_column_int(s, 1); + + /* We expect only one row. We must execute another sqlite3_step() + * to complete the iteration; otherwise the table will remain locked. */ + rc = sqlite3_step(s); + if( rc==SQLITE_DONE ) return SQLITE_OK; + if( rc==SQLITE_ROW ) return SQLITE_ERROR; + return rc; +} + /* TODO(shess) clearPendingTerms() is far down the file because ** writeZeroSegment() is far down the file because LeafWriter is far ** down the file. Consider refactoring the code to move the non-vtab @@ -83007,21 +87268,43 @@ static int fulltextFilter( fulltext_cursor *c = (fulltext_cursor *) pCursor; fulltext_vtab *v = cursor_vtab(c); int rc; - StringBuffer sb; FTSTRACE(("FTS3 Filter %p\n",pCursor)); - initStringBuffer(&sb); - append(&sb, "SELECT docid, "); - appendList(&sb, v->nColumn, v->azContentColumn); - append(&sb, " FROM %_content"); - if( idxNum!=QUERY_GENERIC ) append(&sb, " WHERE docid = ?"); - sqlite3_finalize(c->pStmt); - rc = sql_prepare(v->db, v->zDb, v->zName, &c->pStmt, stringBufferData(&sb)); - stringBufferDestroy(&sb); - if( rc!=SQLITE_OK ) return rc; + /* If the cursor has a statement that was not prepared according to + ** idxNum, clear it. I believe all calls to fulltextFilter with a + ** given cursor will have the same idxNum , but in this case it's + ** easy to be safe. + */ + if( c->pStmt && c->iCursorType!=idxNum ){ + sqlite3_finalize(c->pStmt); + c->pStmt = NULL; + } + + /* Get a fresh statement appropriate to idxNum. */ + /* TODO(shess): Add a prepared-statement cache in the vt structure. + ** The cache must handle multiple open cursors. Easier to cache the + ** statement variants at the vt to reduce malloc/realloc/free here. + ** Or we could have a StringBuffer variant which allowed stack + ** construction for small values. + */ + if( !c->pStmt ){ + StringBuffer sb; + initStringBuffer(&sb); + append(&sb, "SELECT docid, "); + appendList(&sb, v->nColumn, v->azContentColumn); + append(&sb, " FROM %_content"); + if( idxNum!=QUERY_GENERIC ) append(&sb, " WHERE docid = ?"); + rc = sql_prepare(v->db, v->zDb, v->zName, &c->pStmt, + stringBufferData(&sb)); + stringBufferDestroy(&sb); + if( rc!=SQLITE_OK ) return rc; + c->iCursorType = idxNum; + }else{ + sqlite3_reset(c->pStmt); + assert( c->iCursorType==idxNum ); + } - c->iCursorType = idxNum; switch( idxNum ){ case QUERY_GENERIC: break; @@ -84281,6 +88564,12 @@ static int leavesReaderReset(LeavesReader *pReader){ } static void leavesReaderDestroy(LeavesReader *pReader){ + /* If idx is -1, that means we're using a non-cached statement + ** handle in the optimize() case, so we need to release it. + */ + if( pReader->pStmt!=NULL && pReader->idx==-1 ){ + sqlite3_finalize(pReader->pStmt); + } leafReaderDestroy(&pReader->leafReader); dataBufferDestroy(&pReader->rootData); SCRAMBLE(pReader); @@ -84401,7 +88690,7 @@ static void leavesReaderReorder(LeavesReader *pLr, int nLr){ static int leavesReadersInit(fulltext_vtab *v, int iLevel, LeavesReader *pReaders, int *piReaders){ sqlite3_stmt *s; - int i, rc = sql_get_statement(v, SEGDIR_SELECT_STMT, &s); + int i, rc = sql_get_statement(v, SEGDIR_SELECT_LEVEL_STMT, &s); if( rc!=SQLITE_OK ) return rc; rc = sqlite3_bind_int(s, 1, iLevel); @@ -84939,8 +89228,8 @@ static int termSelect(fulltext_vtab *v, int iColumn, ** elements for given docids overwrite older elements. */ while( (rc = sqlite3_step(s))==SQLITE_ROW ){ - const char *pData = sqlite3_column_blob(s, 0); - const int nData = sqlite3_column_bytes(s, 0); + const char *pData = sqlite3_column_blob(s, 2); + const int nData = sqlite3_column_bytes(s, 2); const sqlite_int64 iLeavesEnd = sqlite3_column_int64(s, 1); rc = loadSegment(v, pData, nData, iLeavesEnd, pTerm, nTerm, isPrefix, &doclist); @@ -85094,6 +89383,23 @@ static int fulltextUpdate(sqlite3_vtab *pVtab, int nArg, sqlite3_value **ppArg, if( nArg<2 ){ rc = index_delete(v, sqlite3_value_int64(ppArg[0])); + if( rc==SQLITE_OK ){ + /* If we just deleted the last row in the table, clear out the + ** index data. + */ + rc = content_exists(v); + if( rc==SQLITE_ROW ){ + rc = SQLITE_OK; + }else if( rc==SQLITE_DONE ){ + /* Clear the pending terms so we don't flush a useless level-0 + ** segment when the transaction closes. + */ + rc = clearPendingTerms(v); + if( rc==SQLITE_OK ){ + rc = segdir_delete_all(v); + } + } + } } else if( sqlite3_value_type(ppArg[0]) != SQLITE_NULL ){ /* An update: * ppArg[0] = old rowid @@ -85230,6 +89536,665 @@ static void snippetOffsetsFunc( } } +/* OptLeavesReader is nearly identical to LeavesReader, except that +** where LeavesReader is geared towards the merging of complete +** segment levels (with exactly MERGE_COUNT segments), OptLeavesReader +** is geared towards implementation of the optimize() function, and +** can merge all segments simultaneously. This version may be +** somewhat less efficient than LeavesReader because it merges into an +** accumulator rather than doing an N-way merge, but since segment +** size grows exponentially (so segment count logrithmically) this is +** probably not an immediate problem. +*/ +/* TODO(shess): Prove that assertion, or extend the merge code to +** merge tree fashion (like the prefix-searching code does). +*/ +/* TODO(shess): OptLeavesReader and LeavesReader could probably be +** merged with little or no loss of performance for LeavesReader. The +** merged code would need to handle >MERGE_COUNT segments, and would +** also need to be able to optionally optimize away deletes. +*/ +typedef struct OptLeavesReader { + /* Segment number, to order readers by age. */ + int segment; + LeavesReader reader; +} OptLeavesReader; + +static int optLeavesReaderAtEnd(OptLeavesReader *pReader){ + return leavesReaderAtEnd(&pReader->reader); +} +static int optLeavesReaderTermBytes(OptLeavesReader *pReader){ + return leavesReaderTermBytes(&pReader->reader); +} +static const char *optLeavesReaderData(OptLeavesReader *pReader){ + return leavesReaderData(&pReader->reader); +} +static int optLeavesReaderDataBytes(OptLeavesReader *pReader){ + return leavesReaderDataBytes(&pReader->reader); +} +static const char *optLeavesReaderTerm(OptLeavesReader *pReader){ + return leavesReaderTerm(&pReader->reader); +} +static int optLeavesReaderStep(fulltext_vtab *v, OptLeavesReader *pReader){ + return leavesReaderStep(v, &pReader->reader); +} +static int optLeavesReaderTermCmp(OptLeavesReader *lr1, OptLeavesReader *lr2){ + return leavesReaderTermCmp(&lr1->reader, &lr2->reader); +} +/* Order by term ascending, segment ascending (oldest to newest), with +** exhausted readers to the end. +*/ +static int optLeavesReaderCmp(OptLeavesReader *lr1, OptLeavesReader *lr2){ + int c = optLeavesReaderTermCmp(lr1, lr2); + if( c!=0 ) return c; + return lr1->segment-lr2->segment; +} +/* Bubble pLr[0] to appropriate place in pLr[1..nLr-1]. Assumes that +** pLr[1..nLr-1] is already sorted. +*/ +static void optLeavesReaderReorder(OptLeavesReader *pLr, int nLr){ + while( nLr>1 && optLeavesReaderCmp(pLr, pLr+1)>0 ){ + OptLeavesReader tmp = pLr[0]; + pLr[0] = pLr[1]; + pLr[1] = tmp; + nLr--; + pLr++; + } +} + +/* optimize() helper function. Put the readers in order and iterate +** through them, merging doclists for matching terms into pWriter. +** Returns SQLITE_OK on success, or the SQLite error code which +** prevented success. +*/ +static int optimizeInternal(fulltext_vtab *v, + OptLeavesReader *readers, int nReaders, + LeafWriter *pWriter){ + int i, rc = SQLITE_OK; + DataBuffer doclist, merged, tmp; + + /* Order the readers. */ + i = nReaders; + while( i-- > 0 ){ + optLeavesReaderReorder(&readers[i], nReaders-i); + } + + dataBufferInit(&doclist, LEAF_MAX); + dataBufferInit(&merged, LEAF_MAX); + + /* Exhausted readers bubble to the end, so when the first reader is + ** at eof, all are at eof. + */ + while( !optLeavesReaderAtEnd(&readers[0]) ){ + + /* Figure out how many readers share the next term. */ + for(i=1; i<nReaders && !optLeavesReaderAtEnd(&readers[i]); i++){ + if( 0!=optLeavesReaderTermCmp(&readers[0], &readers[i]) ) break; + } + + /* Special-case for no merge. */ + if( i==1 ){ + /* Trim deletions from the doclist. */ + dataBufferReset(&merged); + docListTrim(DL_DEFAULT, + optLeavesReaderData(&readers[0]), + optLeavesReaderDataBytes(&readers[0]), + -1, DL_DEFAULT, &merged); + }else{ + DLReader dlReaders[MERGE_COUNT]; + int iReader, nReaders; + + /* Prime the pipeline with the first reader's doclist. After + ** one pass index 0 will reference the accumulated doclist. + */ + dlrInit(&dlReaders[0], DL_DEFAULT, + optLeavesReaderData(&readers[0]), + optLeavesReaderDataBytes(&readers[0])); + iReader = 1; + + assert( iReader<i ); /* Must execute the loop at least once. */ + while( iReader<i ){ + /* Merge 16 inputs per pass. */ + for( nReaders=1; iReader<i && nReaders<MERGE_COUNT; + iReader++, nReaders++ ){ + dlrInit(&dlReaders[nReaders], DL_DEFAULT, + optLeavesReaderData(&readers[iReader]), + optLeavesReaderDataBytes(&readers[iReader])); + } + + /* Merge doclists and swap result into accumulator. */ + dataBufferReset(&merged); + docListMerge(&merged, dlReaders, nReaders); + tmp = merged; + merged = doclist; + doclist = tmp; + + while( nReaders-- > 0 ){ + dlrDestroy(&dlReaders[nReaders]); + } + + /* Accumulated doclist to reader 0 for next pass. */ + dlrInit(&dlReaders[0], DL_DEFAULT, doclist.pData, doclist.nData); + } + + /* Destroy reader that was left in the pipeline. */ + dlrDestroy(&dlReaders[0]); + + /* Trim deletions from the doclist. */ + dataBufferReset(&merged); + docListTrim(DL_DEFAULT, doclist.pData, doclist.nData, + -1, DL_DEFAULT, &merged); + } + + /* Only pass doclists with hits (skip if all hits deleted). */ + if( merged.nData>0 ){ + rc = leafWriterStep(v, pWriter, + optLeavesReaderTerm(&readers[0]), + optLeavesReaderTermBytes(&readers[0]), + merged.pData, merged.nData); + if( rc!=SQLITE_OK ) goto err; + } + + /* Step merged readers to next term and reorder. */ + while( i-- > 0 ){ + rc = optLeavesReaderStep(v, &readers[i]); + if( rc!=SQLITE_OK ) goto err; + + optLeavesReaderReorder(&readers[i], nReaders-i); + } + } + + err: + dataBufferDestroy(&doclist); + dataBufferDestroy(&merged); + return rc; +} + +/* Implement optimize() function for FTS3. optimize(t) merges all +** segments in the fts index into a single segment. 't' is the magic +** table-named column. +*/ +static void optimizeFunc(sqlite3_context *pContext, + int argc, sqlite3_value **argv){ + fulltext_cursor *pCursor; + if( argc>1 ){ + sqlite3_result_error(pContext, "excess arguments to optimize()",-1); + }else if( sqlite3_value_type(argv[0])!=SQLITE_BLOB || + sqlite3_value_bytes(argv[0])!=sizeof(pCursor) ){ + sqlite3_result_error(pContext, "illegal first argument to optimize",-1); + }else{ + fulltext_vtab *v; + int i, rc, iMaxLevel; + OptLeavesReader *readers; + int nReaders; + LeafWriter writer; + sqlite3_stmt *s; + + memcpy(&pCursor, sqlite3_value_blob(argv[0]), sizeof(pCursor)); + v = cursor_vtab(pCursor); + + /* Flush any buffered updates before optimizing. */ + rc = flushPendingTerms(v); + if( rc!=SQLITE_OK ) goto err; + + rc = segdir_count(v, &nReaders, &iMaxLevel); + if( rc!=SQLITE_OK ) goto err; + if( nReaders==0 || nReaders==1 ){ + sqlite3_result_text(pContext, "Index already optimal", -1, + SQLITE_STATIC); + return; + } + + rc = sql_get_statement(v, SEGDIR_SELECT_ALL_STMT, &s); + if( rc!=SQLITE_OK ) goto err; + + readers = sqlite3_malloc(nReaders*sizeof(readers[0])); + if( readers==NULL ) goto err; + + /* Note that there will already be a segment at this position + ** until we call segdir_delete() on iMaxLevel. + */ + leafWriterInit(iMaxLevel, 0, &writer); + + i = 0; + while( (rc = sqlite3_step(s))==SQLITE_ROW ){ + sqlite_int64 iStart = sqlite3_column_int64(s, 0); + sqlite_int64 iEnd = sqlite3_column_int64(s, 1); + const char *pRootData = sqlite3_column_blob(s, 2); + int nRootData = sqlite3_column_bytes(s, 2); + + assert( i<nReaders ); + rc = leavesReaderInit(v, -1, iStart, iEnd, pRootData, nRootData, + &readers[i].reader); + if( rc!=SQLITE_OK ) break; + + readers[i].segment = i; + i++; + } + + /* If we managed to succesfully read them all, optimize them. */ + if( rc==SQLITE_DONE ){ + assert( i==nReaders ); + rc = optimizeInternal(v, readers, nReaders, &writer); + } + + while( i-- > 0 ){ + leavesReaderDestroy(&readers[i].reader); + } + sqlite3_free(readers); + + /* If we've successfully gotten to here, delete the old segments + ** and flush the interior structure of the new segment. + */ + if( rc==SQLITE_OK ){ + for( i=0; i<=iMaxLevel; i++ ){ + rc = segdir_delete(v, i); + if( rc!=SQLITE_OK ) break; + } + + if( rc==SQLITE_OK ) rc = leafWriterFinalize(v, &writer); + } + + leafWriterDestroy(&writer); + + if( rc!=SQLITE_OK ) goto err; + + sqlite3_result_text(pContext, "Index optimized", -1, SQLITE_STATIC); + return; + + /* TODO(shess): Error-handling needs to be improved along the + ** lines of the dump_ functions. + */ + err: + { + char buf[512]; + sqlite3_snprintf(sizeof(buf), buf, "Error in optimize: %s", + sqlite3_errmsg(sqlite3_context_db_handle(pContext))); + sqlite3_result_error(pContext, buf, -1); + } + } +} + +#ifdef SQLITE_TEST +/* Generate an error of the form "<prefix>: <msg>". If msg is NULL, +** pull the error from the context's db handle. +*/ +static void generateError(sqlite3_context *pContext, + const char *prefix, const char *msg){ + char buf[512]; + if( msg==NULL ) msg = sqlite3_errmsg(sqlite3_context_db_handle(pContext)); + sqlite3_snprintf(sizeof(buf), buf, "%s: %s", prefix, msg); + sqlite3_result_error(pContext, buf, -1); +} + +/* Helper function to collect the set of terms in the segment into +** pTerms. The segment is defined by the leaf nodes between +** iStartBlockid and iEndBlockid, inclusive, or by the contents of +** pRootData if iStartBlockid is 0 (in which case the entire segment +** fit in a leaf). +*/ +static int collectSegmentTerms(fulltext_vtab *v, sqlite3_stmt *s, + fts3Hash *pTerms){ + const sqlite_int64 iStartBlockid = sqlite3_column_int64(s, 0); + const sqlite_int64 iEndBlockid = sqlite3_column_int64(s, 1); + const char *pRootData = sqlite3_column_blob(s, 2); + const int nRootData = sqlite3_column_bytes(s, 2); + LeavesReader reader; + int rc = leavesReaderInit(v, 0, iStartBlockid, iEndBlockid, + pRootData, nRootData, &reader); + if( rc!=SQLITE_OK ) return rc; + + while( rc==SQLITE_OK && !leavesReaderAtEnd(&reader) ){ + const char *pTerm = leavesReaderTerm(&reader); + const int nTerm = leavesReaderTermBytes(&reader); + void *oldValue = sqlite3Fts3HashFind(pTerms, pTerm, nTerm); + void *newValue = (void *)((char *)oldValue+1); + + /* From the comment before sqlite3Fts3HashInsert in fts3_hash.c, + ** the data value passed is returned in case of malloc failure. + */ + if( newValue==sqlite3Fts3HashInsert(pTerms, pTerm, nTerm, newValue) ){ + rc = SQLITE_NOMEM; + }else{ + rc = leavesReaderStep(v, &reader); + } + } + + leavesReaderDestroy(&reader); + return rc; +} + +/* Helper function to build the result string for dump_terms(). */ +static int generateTermsResult(sqlite3_context *pContext, fts3Hash *pTerms){ + int iTerm, nTerms, nResultBytes, iByte; + char *result; + TermData *pData; + fts3HashElem *e; + + /* Iterate pTerms to generate an array of terms in pData for + ** sorting. + */ + nTerms = fts3HashCount(pTerms); + assert( nTerms>0 ); + pData = sqlite3_malloc(nTerms*sizeof(TermData)); + if( pData==NULL ) return SQLITE_NOMEM; + + nResultBytes = 0; + for(iTerm = 0, e = fts3HashFirst(pTerms); e; iTerm++, e = fts3HashNext(e)){ + nResultBytes += fts3HashKeysize(e)+1; /* Term plus trailing space */ + assert( iTerm<nTerms ); + pData[iTerm].pTerm = fts3HashKey(e); + pData[iTerm].nTerm = fts3HashKeysize(e); + pData[iTerm].pCollector = fts3HashData(e); /* unused */ + } + assert( iTerm==nTerms ); + + assert( nResultBytes>0 ); /* nTerms>0, nResultsBytes must be, too. */ + result = sqlite3_malloc(nResultBytes); + if( result==NULL ){ + sqlite3_free(pData); + return SQLITE_NOMEM; + } + + if( nTerms>1 ) qsort(pData, nTerms, sizeof(*pData), termDataCmp); + + /* Read the terms in order to build the result. */ + iByte = 0; + for(iTerm=0; iTerm<nTerms; ++iTerm){ + memcpy(result+iByte, pData[iTerm].pTerm, pData[iTerm].nTerm); + iByte += pData[iTerm].nTerm; + result[iByte++] = ' '; + } + assert( iByte==nResultBytes ); + assert( result[nResultBytes-1]==' ' ); + result[nResultBytes-1] = '\0'; + + /* Passes away ownership of result. */ + sqlite3_result_text(pContext, result, nResultBytes-1, sqlite3_free); + sqlite3_free(pData); + return SQLITE_OK; +} + +/* Implements dump_terms() for use in inspecting the fts3 index from +** tests. TEXT result containing the ordered list of terms joined by +** spaces. dump_terms(t, level, idx) dumps the terms for the segment +** specified by level, idx (in %_segdir), while dump_terms(t) dumps +** all terms in the index. In both cases t is the fts table's magic +** table-named column. +*/ +static void dumpTermsFunc( + sqlite3_context *pContext, + int argc, sqlite3_value **argv +){ + fulltext_cursor *pCursor; + if( argc!=3 && argc!=1 ){ + generateError(pContext, "dump_terms", "incorrect arguments"); + }else if( sqlite3_value_type(argv[0])!=SQLITE_BLOB || + sqlite3_value_bytes(argv[0])!=sizeof(pCursor) ){ + generateError(pContext, "dump_terms", "illegal first argument"); + }else{ + fulltext_vtab *v; + fts3Hash terms; + sqlite3_stmt *s = NULL; + int rc; + + memcpy(&pCursor, sqlite3_value_blob(argv[0]), sizeof(pCursor)); + v = cursor_vtab(pCursor); + + /* If passed only the cursor column, get all segments. Otherwise + ** get the segment described by the following two arguments. + */ + if( argc==1 ){ + rc = sql_get_statement(v, SEGDIR_SELECT_ALL_STMT, &s); + }else{ + rc = sql_get_statement(v, SEGDIR_SELECT_SEGMENT_STMT, &s); + if( rc==SQLITE_OK ){ + rc = sqlite3_bind_int(s, 1, sqlite3_value_int(argv[1])); + if( rc==SQLITE_OK ){ + rc = sqlite3_bind_int(s, 2, sqlite3_value_int(argv[2])); + } + } + } + + if( rc!=SQLITE_OK ){ + generateError(pContext, "dump_terms", NULL); + return; + } + + /* Collect the terms for each segment. */ + sqlite3Fts3HashInit(&terms, FTS3_HASH_STRING, 1); + while( (rc = sqlite3_step(s))==SQLITE_ROW ){ + rc = collectSegmentTerms(v, s, &terms); + if( rc!=SQLITE_OK ) break; + } + + if( rc!=SQLITE_DONE ){ + sqlite3_reset(s); + generateError(pContext, "dump_terms", NULL); + }else{ + const int nTerms = fts3HashCount(&terms); + if( nTerms>0 ){ + rc = generateTermsResult(pContext, &terms); + if( rc==SQLITE_NOMEM ){ + generateError(pContext, "dump_terms", "out of memory"); + }else{ + assert( rc==SQLITE_OK ); + } + }else if( argc==3 ){ + /* The specific segment asked for could not be found. */ + generateError(pContext, "dump_terms", "segment not found"); + }else{ + /* No segments found. */ + /* TODO(shess): It should be impossible to reach this. This + ** case can only happen for an empty table, in which case + ** SQLite has no rows to call this function on. + */ + sqlite3_result_null(pContext); + } + } + sqlite3Fts3HashClear(&terms); + } +} + +/* Expand the DL_DEFAULT doclist in pData into a text result in +** pContext. +*/ +static void createDoclistResult(sqlite3_context *pContext, + const char *pData, int nData){ + DataBuffer dump; + DLReader dlReader; + + assert( pData!=NULL && nData>0 ); + + dataBufferInit(&dump, 0); + dlrInit(&dlReader, DL_DEFAULT, pData, nData); + for( ; !dlrAtEnd(&dlReader); dlrStep(&dlReader) ){ + char buf[256]; + PLReader plReader; + + plrInit(&plReader, &dlReader); + if( DL_DEFAULT==DL_DOCIDS || plrAtEnd(&plReader) ){ + sqlite3_snprintf(sizeof(buf), buf, "[%lld] ", dlrDocid(&dlReader)); + dataBufferAppend(&dump, buf, strlen(buf)); + }else{ + int iColumn = plrColumn(&plReader); + + sqlite3_snprintf(sizeof(buf), buf, "[%lld %d[", + dlrDocid(&dlReader), iColumn); + dataBufferAppend(&dump, buf, strlen(buf)); + + for( ; !plrAtEnd(&plReader); plrStep(&plReader) ){ + if( plrColumn(&plReader)!=iColumn ){ + iColumn = plrColumn(&plReader); + sqlite3_snprintf(sizeof(buf), buf, "] %d[", iColumn); + assert( dump.nData>0 ); + dump.nData--; /* Overwrite trailing space. */ + assert( dump.pData[dump.nData]==' '); + dataBufferAppend(&dump, buf, strlen(buf)); + } + if( DL_DEFAULT==DL_POSITIONS_OFFSETS ){ + sqlite3_snprintf(sizeof(buf), buf, "%d,%d,%d ", + plrPosition(&plReader), + plrStartOffset(&plReader), plrEndOffset(&plReader)); + }else if( DL_DEFAULT==DL_POSITIONS ){ + sqlite3_snprintf(sizeof(buf), buf, "%d ", plrPosition(&plReader)); + }else{ + assert( NULL=="Unhandled DL_DEFAULT value"); + } + dataBufferAppend(&dump, buf, strlen(buf)); + } + plrDestroy(&plReader); + + assert( dump.nData>0 ); + dump.nData--; /* Overwrite trailing space. */ + assert( dump.pData[dump.nData]==' '); + dataBufferAppend(&dump, "]] ", 3); + } + } + dlrDestroy(&dlReader); + + assert( dump.nData>0 ); + dump.nData--; /* Overwrite trailing space. */ + assert( dump.pData[dump.nData]==' '); + dump.pData[dump.nData] = '\0'; + assert( dump.nData>0 ); + + /* Passes ownership of dump's buffer to pContext. */ + sqlite3_result_text(pContext, dump.pData, dump.nData, sqlite3_free); + dump.pData = NULL; + dump.nData = dump.nCapacity = 0; +} + +/* Implements dump_doclist() for use in inspecting the fts3 index from +** tests. TEXT result containing a string representation of the +** doclist for the indicated term. dump_doclist(t, term, level, idx) +** dumps the doclist for term from the segment specified by level, idx +** (in %_segdir), while dump_doclist(t, term) dumps the logical +** doclist for the term across all segments. The per-segment doclist +** can contain deletions, while the full-index doclist will not +** (deletions are omitted). +** +** Result formats differ with the setting of DL_DEFAULTS. Examples: +** +** DL_DOCIDS: [1] [3] [7] +** DL_POSITIONS: [1 0[0 4] 1[17]] [3 1[5]] +** DL_POSITIONS_OFFSETS: [1 0[0,0,3 4,23,26] 1[17,102,105]] [3 1[5,20,23]] +** +** In each case the number after the outer '[' is the docid. In the +** latter two cases, the number before the inner '[' is the column +** associated with the values within. For DL_POSITIONS the numbers +** within are the positions, for DL_POSITIONS_OFFSETS they are the +** position, the start offset, and the end offset. +*/ +static void dumpDoclistFunc( + sqlite3_context *pContext, + int argc, sqlite3_value **argv +){ + fulltext_cursor *pCursor; + if( argc!=2 && argc!=4 ){ + generateError(pContext, "dump_doclist", "incorrect arguments"); + }else if( sqlite3_value_type(argv[0])!=SQLITE_BLOB || + sqlite3_value_bytes(argv[0])!=sizeof(pCursor) ){ + generateError(pContext, "dump_doclist", "illegal first argument"); + }else if( sqlite3_value_text(argv[1])==NULL || + sqlite3_value_text(argv[1])[0]=='\0' ){ + generateError(pContext, "dump_doclist", "empty second argument"); + }else{ + const char *pTerm = (const char *)sqlite3_value_text(argv[1]); + const int nTerm = strlen(pTerm); + fulltext_vtab *v; + int rc; + DataBuffer doclist; + + memcpy(&pCursor, sqlite3_value_blob(argv[0]), sizeof(pCursor)); + v = cursor_vtab(pCursor); + + dataBufferInit(&doclist, 0); + + /* termSelect() yields the same logical doclist that queries are + ** run against. + */ + if( argc==2 ){ + rc = termSelect(v, v->nColumn, pTerm, nTerm, 0, DL_DEFAULT, &doclist); + }else{ + sqlite3_stmt *s = NULL; + + /* Get our specific segment's information. */ + rc = sql_get_statement(v, SEGDIR_SELECT_SEGMENT_STMT, &s); + if( rc==SQLITE_OK ){ + rc = sqlite3_bind_int(s, 1, sqlite3_value_int(argv[2])); + if( rc==SQLITE_OK ){ + rc = sqlite3_bind_int(s, 2, sqlite3_value_int(argv[3])); + } + } + + if( rc==SQLITE_OK ){ + rc = sqlite3_step(s); + + if( rc==SQLITE_DONE ){ + dataBufferDestroy(&doclist); + generateError(pContext, "dump_doclist", "segment not found"); + return; + } + + /* Found a segment, load it into doclist. */ + if( rc==SQLITE_ROW ){ + const sqlite_int64 iLeavesEnd = sqlite3_column_int64(s, 1); + const char *pData = sqlite3_column_blob(s, 2); + const int nData = sqlite3_column_bytes(s, 2); + + /* loadSegment() is used by termSelect() to load each + ** segment's data. + */ + rc = loadSegment(v, pData, nData, iLeavesEnd, pTerm, nTerm, 0, + &doclist); + if( rc==SQLITE_OK ){ + rc = sqlite3_step(s); + + /* Should not have more than one matching segment. */ + if( rc!=SQLITE_DONE ){ + sqlite3_reset(s); + dataBufferDestroy(&doclist); + generateError(pContext, "dump_doclist", "invalid segdir"); + return; + } + rc = SQLITE_OK; + } + } + } + + sqlite3_reset(s); + } + + if( rc==SQLITE_OK ){ + if( doclist.nData>0 ){ + createDoclistResult(pContext, doclist.pData, doclist.nData); + }else{ + /* TODO(shess): This can happen if the term is not present, or + ** if all instances of the term have been deleted and this is + ** an all-index dump. It may be interesting to distinguish + ** these cases. + */ + sqlite3_result_text(pContext, "", 0, SQLITE_STATIC); + } + }else if( rc==SQLITE_NOMEM ){ + /* Handle out-of-memory cases specially because if they are + ** generated in fts3 code they may not be reflected in the db + ** handle. + */ + /* TODO(shess): Handle this more comprehensively. + ** sqlite3ErrStr() has what I need, but is internal. + */ + generateError(pContext, "dump_doclist", "out of memory"); + }else{ + generateError(pContext, "dump_doclist", NULL); + } + + dataBufferDestroy(&doclist); + } +} +#endif + /* ** This routine implements the xFindFunction method for the FTS3 ** virtual table. @@ -85247,6 +90212,23 @@ static int fulltextFindFunction( }else if( strcmp(zName,"offsets")==0 ){ *pxFunc = snippetOffsetsFunc; return 1; + }else if( strcmp(zName,"optimize")==0 ){ + *pxFunc = optimizeFunc; + return 1; +#ifdef SQLITE_TEST + /* NOTE(shess): These functions are present only for testing + ** purposes. No particular effort is made to optimize their + ** execution or how they build their results. + */ + }else if( strcmp(zName,"dump_terms")==0 ){ + /* fprintf(stderr, "Found dump_terms\n"); */ + *pxFunc = dumpTermsFunc; + return 1; + }else if( strcmp(zName,"dump_doclist")==0 ){ + /* fprintf(stderr, "Found dump_doclist\n"); */ + *pxFunc = dumpDoclistFunc; + return 1; +#endif } return 0; } @@ -85366,6 +90348,11 @@ SQLITE_PRIVATE int sqlite3Fts3Init(sqlite3 *db){ && SQLITE_OK==(rc = sqlite3Fts3InitHashTable(db, pHash, "fts3_tokenizer")) && SQLITE_OK==(rc = sqlite3_overload_function(db, "snippet", -1)) && SQLITE_OK==(rc = sqlite3_overload_function(db, "offsets", -1)) + && SQLITE_OK==(rc = sqlite3_overload_function(db, "optimize", -1)) +#ifdef SQLITE_TEST + && SQLITE_OK==(rc = sqlite3_overload_function(db, "dump_terms", -1)) + && SQLITE_OK==(rc = sqlite3_overload_function(db, "dump_doclist", -1)) +#endif ){ return sqlite3_create_module_v2( db, "fts3", &fts3Module, (void *)pHash, hashDestroy @@ -87001,3 +91988,3331 @@ SQLITE_PRIVATE void sqlite3Fts3SimpleTokenizerModule( #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */ /************** End of fts3_tokenizer1.c *************************************/ +/************** Begin file rtree.c *******************************************/ +/* +** 2001 September 15 +** +** The author disclaims copyright to this source code. In place of +** a legal notice, here is a blessing: +** +** May you do good and not evil. +** May you find forgiveness for yourself and forgive others. +** May you share freely, never taking more than you give. +** +************************************************************************* +** This file contains code for implementations of the r-tree and r*-tree +** algorithms packaged as an SQLite virtual table module. +** +** $Id$ +*/ + +#if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_RTREE) + +/* +** This file contains an implementation of a couple of different variants +** of the r-tree algorithm. See the README file for further details. The +** same data-structure is used for all, but the algorithms for insert and +** delete operations vary. The variants used are selected at compile time +** by defining the following symbols: +*/ + +/* Either, both or none of the following may be set to activate +** r*tree variant algorithms. +*/ +#define VARIANT_RSTARTREE_CHOOSESUBTREE 0 +#define VARIANT_RSTARTREE_REINSERT 1 + +/* +** Exactly one of the following must be set to 1. +*/ +#define VARIANT_GUTTMAN_QUADRATIC_SPLIT 0 +#define VARIANT_GUTTMAN_LINEAR_SPLIT 0 +#define VARIANT_RSTARTREE_SPLIT 1 + +#define VARIANT_GUTTMAN_SPLIT \ + (VARIANT_GUTTMAN_LINEAR_SPLIT||VARIANT_GUTTMAN_QUADRATIC_SPLIT) + +#if VARIANT_GUTTMAN_QUADRATIC_SPLIT + #define PickNext QuadraticPickNext + #define PickSeeds QuadraticPickSeeds + #define AssignCells splitNodeGuttman +#endif +#if VARIANT_GUTTMAN_LINEAR_SPLIT + #define PickNext LinearPickNext + #define PickSeeds LinearPickSeeds + #define AssignCells splitNodeGuttman +#endif +#if VARIANT_RSTARTREE_SPLIT + #define AssignCells splitNodeStartree +#endif + + +#ifndef SQLITE_CORE + #include "sqlite3ext.h" + SQLITE_EXTENSION_INIT1 +#else + #include "sqlite3.h" +#endif + + +#ifndef SQLITE_AMALGAMATION +typedef sqlite3_int64 i64; +typedef unsigned char u8; +typedef unsigned int u32; +#endif + +typedef struct Rtree Rtree; +typedef struct RtreeCursor RtreeCursor; +typedef struct RtreeNode RtreeNode; +typedef struct RtreeCell RtreeCell; +typedef struct RtreeConstraint RtreeConstraint; +typedef union RtreeCoord RtreeCoord; + +/* The rtree may have between 1 and RTREE_MAX_DIMENSIONS dimensions. */ +#define RTREE_MAX_DIMENSIONS 5 + +/* Size of hash table Rtree.aHash. This hash table is not expected to +** ever contain very many entries, so a fixed number of buckets is +** used. +*/ +#define HASHSIZE 128 + +/* +** An rtree virtual-table object. +*/ +struct Rtree { + sqlite3_vtab base; + sqlite3 *db; /* Host database connection */ + int iNodeSize; /* Size in bytes of each node in the node table */ + int nDim; /* Number of dimensions */ + int nBytesPerCell; /* Bytes consumed per cell */ + int iDepth; /* Current depth of the r-tree structure */ + char *zDb; /* Name of database containing r-tree table */ + char *zName; /* Name of r-tree table */ + RtreeNode *aHash[HASHSIZE]; /* Hash table of in-memory nodes. */ + int nBusy; /* Current number of users of this structure */ + + /* List of nodes removed during a CondenseTree operation. List is + ** linked together via the pointer normally used for hash chains - + ** RtreeNode.pNext. RtreeNode.iNode stores the depth of the sub-tree + ** headed by the node (leaf nodes have RtreeNode.iNode==0). + */ + RtreeNode *pDeleted; + int iReinsertHeight; /* Height of sub-trees Reinsert() has run on */ + + /* Statements to read/write/delete a record from xxx_node */ + sqlite3_stmt *pReadNode; + sqlite3_stmt *pWriteNode; + sqlite3_stmt *pDeleteNode; + + /* Statements to read/write/delete a record from xxx_rowid */ + sqlite3_stmt *pReadRowid; + sqlite3_stmt *pWriteRowid; + sqlite3_stmt *pDeleteRowid; + + /* Statements to read/write/delete a record from xxx_parent */ + sqlite3_stmt *pReadParent; + sqlite3_stmt *pWriteParent; + sqlite3_stmt *pDeleteParent; + + int eCoordType; +}; + +/* Possible values for eCoordType: */ +#define RTREE_COORD_REAL32 0 +#define RTREE_COORD_INT32 1 + +/* +** The minimum number of cells allowed for a node is a third of the +** maximum. In Gutman's notation: +** +** m = M/3 +** +** If an R*-tree "Reinsert" operation is required, the same number of +** cells are removed from the overfull node and reinserted into the tree. +*/ +#define RTREE_MINCELLS(p) ((((p)->iNodeSize-4)/(p)->nBytesPerCell)/3) +#define RTREE_REINSERT(p) RTREE_MINCELLS(p) +#define RTREE_MAXCELLS 51 + +/* +** An rtree cursor object. +*/ +struct RtreeCursor { + sqlite3_vtab_cursor base; + RtreeNode *pNode; /* Node cursor is currently pointing at */ + int iCell; /* Index of current cell in pNode */ + int iStrategy; /* Copy of idxNum search parameter */ + int nConstraint; /* Number of entries in aConstraint */ + RtreeConstraint *aConstraint; /* Search constraints. */ +}; + +union RtreeCoord { + float f; + int i; +}; + +/* +** The argument is an RtreeCoord. Return the value stored within the RtreeCoord +** formatted as a double. This macro assumes that local variable pRtree points +** to the Rtree structure associated with the RtreeCoord. +*/ +#define DCOORD(coord) ( \ + (pRtree->eCoordType==RTREE_COORD_REAL32) ? \ + ((double)coord.f) : \ + ((double)coord.i) \ +) + +/* +** A search constraint. +*/ +struct RtreeConstraint { + int iCoord; /* Index of constrained coordinate */ + int op; /* Constraining operation */ + double rValue; /* Constraint value. */ +}; + +/* Possible values for RtreeConstraint.op */ +#define RTREE_EQ 0x41 +#define RTREE_LE 0x42 +#define RTREE_LT 0x43 +#define RTREE_GE 0x44 +#define RTREE_GT 0x45 + +/* +** An rtree structure node. +** +** Data format (RtreeNode.zData): +** +** 1. If the node is the root node (node 1), then the first 2 bytes +** of the node contain the tree depth as a big-endian integer. +** For non-root nodes, the first 2 bytes are left unused. +** +** 2. The next 2 bytes contain the number of entries currently +** stored in the node. +** +** 3. The remainder of the node contains the node entries. Each entry +** consists of a single 8-byte integer followed by an even number +** of 4-byte coordinates. For leaf nodes the integer is the rowid +** of a record. For internal nodes it is the node number of a +** child page. +*/ +struct RtreeNode { + RtreeNode *pParent; /* Parent node */ + i64 iNode; + int nRef; + int isDirty; + u8 *zData; + RtreeNode *pNext; /* Next node in this hash chain */ +}; +#define NCELL(pNode) readInt16(&(pNode)->zData[2]) + +/* +** Structure to store a deserialized rtree record. +*/ +struct RtreeCell { + i64 iRowid; + RtreeCoord aCoord[RTREE_MAX_DIMENSIONS*2]; +}; + +#define MAX(x,y) ((x) < (y) ? (y) : (x)) +#define MIN(x,y) ((x) > (y) ? (y) : (x)) + +/* +** Functions to deserialize a 16 bit integer, 32 bit real number and +** 64 bit integer. The deserialized value is returned. +*/ +static int readInt16(u8 *p){ + return (p[0]<<8) + p[1]; +} +static void readCoord(u8 *p, RtreeCoord *pCoord){ + u32 i = ( + (((u32)p[0]) << 24) + + (((u32)p[1]) << 16) + + (((u32)p[2]) << 8) + + (((u32)p[3]) << 0) + ); + *(u32 *)pCoord = i; +} +static i64 readInt64(u8 *p){ + return ( + (((i64)p[0]) << 56) + + (((i64)p[1]) << 48) + + (((i64)p[2]) << 40) + + (((i64)p[3]) << 32) + + (((i64)p[4]) << 24) + + (((i64)p[5]) << 16) + + (((i64)p[6]) << 8) + + (((i64)p[7]) << 0) + ); +} + +/* +** Functions to serialize a 16 bit integer, 32 bit real number and +** 64 bit integer. The value returned is the number of bytes written +** to the argument buffer (always 2, 4 and 8 respectively). +*/ +static int writeInt16(u8 *p, int i){ + p[0] = (i>> 8)&0xFF; + p[1] = (i>> 0)&0xFF; + return 2; +} +static int writeCoord(u8 *p, RtreeCoord *pCoord){ + u32 i; + assert( sizeof(RtreeCoord)==4 ); + assert( sizeof(u32)==4 ); + i = *(u32 *)pCoord; + p[0] = (i>>24)&0xFF; + p[1] = (i>>16)&0xFF; + p[2] = (i>> 8)&0xFF; + p[3] = (i>> 0)&0xFF; + return 4; +} +static int writeInt64(u8 *p, i64 i){ + p[0] = (i>>56)&0xFF; + p[1] = (i>>48)&0xFF; + p[2] = (i>>40)&0xFF; + p[3] = (i>>32)&0xFF; + p[4] = (i>>24)&0xFF; + p[5] = (i>>16)&0xFF; + p[6] = (i>> 8)&0xFF; + p[7] = (i>> 0)&0xFF; + return 8; +} + +/* +** Increment the reference count of node p. +*/ +static void nodeReference(RtreeNode *p){ + if( p ){ + p->nRef++; + } +} + +/* +** Clear the content of node p (set all bytes to 0x00). +*/ +static void nodeZero(Rtree *pRtree, RtreeNode *p){ + if( p ){ + memset(&p->zData[2], 0, pRtree->iNodeSize-2); + p->isDirty = 1; + } +} + +/* +** Given a node number iNode, return the corresponding key to use +** in the Rtree.aHash table. +*/ +static int nodeHash(i64 iNode){ + return ( + (iNode>>56) ^ (iNode>>48) ^ (iNode>>40) ^ (iNode>>32) ^ + (iNode>>24) ^ (iNode>>16) ^ (iNode>> 8) ^ (iNode>> 0) + ) % HASHSIZE; +} + +/* +** Search the node hash table for node iNode. If found, return a pointer +** to it. Otherwise, return 0. +*/ +static RtreeNode *nodeHashLookup(Rtree *pRtree, i64 iNode){ + RtreeNode *p; + assert( iNode!=0 ); + for(p=pRtree->aHash[nodeHash(iNode)]; p && p->iNode!=iNode; p=p->pNext); + return p; +} + +/* +** Add node pNode to the node hash table. +*/ +static void nodeHashInsert(Rtree *pRtree, RtreeNode *pNode){ + if( pNode ){ + int iHash; + assert( pNode->pNext==0 ); + iHash = nodeHash(pNode->iNode); + pNode->pNext = pRtree->aHash[iHash]; + pRtree->aHash[iHash] = pNode; + } +} + +/* +** Remove node pNode from the node hash table. +*/ +static void nodeHashDelete(Rtree *pRtree, RtreeNode *pNode){ + RtreeNode **pp; + if( pNode->iNode!=0 ){ + pp = &pRtree->aHash[nodeHash(pNode->iNode)]; + for( ; (*pp)!=pNode; pp = &(*pp)->pNext){ assert(*pp); } + *pp = pNode->pNext; + pNode->pNext = 0; + } +} + +/* +** Allocate and return new r-tree node. Initially, (RtreeNode.iNode==0), +** indicating that node has not yet been assigned a node number. It is +** assigned a node number when nodeWrite() is called to write the +** node contents out to the database. +*/ +static RtreeNode *nodeNew(Rtree *pRtree, RtreeNode *pParent, int zero){ + RtreeNode *pNode; + pNode = (RtreeNode *)sqlite3_malloc(sizeof(RtreeNode) + pRtree->iNodeSize); + if( pNode ){ + memset(pNode, 0, sizeof(RtreeNode) + (zero?pRtree->iNodeSize:0)); + pNode->zData = (u8 *)&pNode[1]; + pNode->nRef = 1; + pNode->pParent = pParent; + pNode->isDirty = 1; + nodeReference(pParent); + } + return pNode; +} + +/* +** Obtain a reference to an r-tree node. +*/ +static int +nodeAcquire( + Rtree *pRtree, /* R-tree structure */ + i64 iNode, /* Node number to load */ + RtreeNode *pParent, /* Either the parent node or NULL */ + RtreeNode **ppNode /* OUT: Acquired node */ +){ + int rc; + RtreeNode *pNode; + + /* Check if the requested node is already in the hash table. If so, + ** increase its reference count and return it. + */ + if( (pNode = nodeHashLookup(pRtree, iNode)) ){ + assert( !pParent || !pNode->pParent || pNode->pParent==pParent ); + if( pParent ){ + pNode->pParent = pParent; + } + pNode->nRef++; + *ppNode = pNode; + return SQLITE_OK; + } + + pNode = (RtreeNode *)sqlite3_malloc(sizeof(RtreeNode) + pRtree->iNodeSize); + if( !pNode ){ + *ppNode = 0; + return SQLITE_NOMEM; + } + pNode->pParent = pParent; + pNode->zData = (u8 *)&pNode[1]; + pNode->nRef = 1; + pNode->iNode = iNode; + pNode->isDirty = 0; + pNode->pNext = 0; + + sqlite3_bind_int64(pRtree->pReadNode, 1, iNode); + rc = sqlite3_step(pRtree->pReadNode); + if( rc==SQLITE_ROW ){ + const u8 *zBlob = sqlite3_column_blob(pRtree->pReadNode, 0); + memcpy(pNode->zData, zBlob, pRtree->iNodeSize); + nodeReference(pParent); + }else{ + sqlite3_free(pNode); + pNode = 0; + } + + *ppNode = pNode; + rc = sqlite3_reset(pRtree->pReadNode); + + if( rc==SQLITE_OK && iNode==1 ){ + pRtree->iDepth = readInt16(pNode->zData); + } + + assert( (rc==SQLITE_OK && pNode) || (pNode==0 && rc!=SQLITE_OK) ); + nodeHashInsert(pRtree, pNode); + + return rc; +} + +/* +** Overwrite cell iCell of node pNode with the contents of pCell. +*/ +static void nodeOverwriteCell( + Rtree *pRtree, + RtreeNode *pNode, + RtreeCell *pCell, + int iCell +){ + int ii; + u8 *p = &pNode->zData[4 + pRtree->nBytesPerCell*iCell]; + p += writeInt64(p, pCell->iRowid); + for(ii=0; ii<(pRtree->nDim*2); ii++){ + p += writeCoord(p, &pCell->aCoord[ii]); + } + pNode->isDirty = 1; +} + +/* +** Remove cell the cell with index iCell from node pNode. +*/ +static void nodeDeleteCell(Rtree *pRtree, RtreeNode *pNode, int iCell){ + u8 *pDst = &pNode->zData[4 + pRtree->nBytesPerCell*iCell]; + u8 *pSrc = &pDst[pRtree->nBytesPerCell]; + int nByte = (NCELL(pNode) - iCell - 1) * pRtree->nBytesPerCell; + memmove(pDst, pSrc, nByte); + writeInt16(&pNode->zData[2], NCELL(pNode)-1); + pNode->isDirty = 1; +} + +/* +** Insert the contents of cell pCell into node pNode. If the insert +** is successful, return SQLITE_OK. +** +** If there is not enough free space in pNode, return SQLITE_FULL. +*/ +static int +nodeInsertCell( + Rtree *pRtree, + RtreeNode *pNode, + RtreeCell *pCell +){ + int nCell; /* Current number of cells in pNode */ + int nMaxCell; /* Maximum number of cells for pNode */ + + nMaxCell = (pRtree->iNodeSize-4)/pRtree->nBytesPerCell; + nCell = NCELL(pNode); + + assert(nCell<=nMaxCell); + + if( nCell<nMaxCell ){ + nodeOverwriteCell(pRtree, pNode, pCell, nCell); + writeInt16(&pNode->zData[2], nCell+1); + pNode->isDirty = 1; + } + + return (nCell==nMaxCell); +} + +/* +** If the node is dirty, write it out to the database. +*/ +static int +nodeWrite(Rtree *pRtree, RtreeNode *pNode){ + int rc = SQLITE_OK; + if( pNode->isDirty ){ + sqlite3_stmt *p = pRtree->pWriteNode; + if( pNode->iNode ){ + sqlite3_bind_int64(p, 1, pNode->iNode); + }else{ + sqlite3_bind_null(p, 1); + } + sqlite3_bind_blob(p, 2, pNode->zData, pRtree->iNodeSize, SQLITE_STATIC); + sqlite3_step(p); + pNode->isDirty = 0; + rc = sqlite3_reset(p); + if( pNode->iNode==0 && rc==SQLITE_OK ){ + pNode->iNode = sqlite3_last_insert_rowid(pRtree->db); + nodeHashInsert(pRtree, pNode); + } + } + return rc; +} + +/* +** Release a reference to a node. If the node is dirty and the reference +** count drops to zero, the node data is written to the database. +*/ +static int +nodeRelease(Rtree *pRtree, RtreeNode *pNode){ + int rc = SQLITE_OK; + if( pNode ){ + assert( pNode->nRef>0 ); + pNode->nRef--; + if( pNode->nRef==0 ){ + if( pNode->iNode==1 ){ + pRtree->iDepth = -1; + } + if( pNode->pParent ){ + rc = nodeRelease(pRtree, pNode->pParent); + } + if( rc==SQLITE_OK ){ + rc = nodeWrite(pRtree, pNode); + } + nodeHashDelete(pRtree, pNode); + sqlite3_free(pNode); + } + } + return rc; +} + +/* +** Return the 64-bit integer value associated with cell iCell of +** node pNode. If pNode is a leaf node, this is a rowid. If it is +** an internal node, then the 64-bit integer is a child page number. +*/ +static i64 nodeGetRowid( + Rtree *pRtree, + RtreeNode *pNode, + int iCell +){ + assert( iCell<NCELL(pNode) ); + return readInt64(&pNode->zData[4 + pRtree->nBytesPerCell*iCell]); +} + +/* +** Return coordinate iCoord from cell iCell in node pNode. +*/ +static void nodeGetCoord( + Rtree *pRtree, + RtreeNode *pNode, + int iCell, + int iCoord, + RtreeCoord *pCoord /* Space to write result to */ +){ + readCoord(&pNode->zData[12 + pRtree->nBytesPerCell*iCell + 4*iCoord], pCoord); +} + +/* +** Deserialize cell iCell of node pNode. Populate the structure pointed +** to by pCell with the results. +*/ +static void nodeGetCell( + Rtree *pRtree, + RtreeNode *pNode, + int iCell, + RtreeCell *pCell +){ + int ii; + pCell->iRowid = nodeGetRowid(pRtree, pNode, iCell); + for(ii=0; ii<pRtree->nDim*2; ii++){ + nodeGetCoord(pRtree, pNode, iCell, ii, &pCell->aCoord[ii]); + } +} + + +/* Forward declaration for the function that does the work of +** the virtual table module xCreate() and xConnect() methods. +*/ +static int rtreeInit( + sqlite3 *, void *, int, const char *const*, sqlite3_vtab **, char **, int, int +); + +/* +** Rtree virtual table module xCreate method. +*/ +static int rtreeCreate( + sqlite3 *db, + void *pAux, + int argc, const char *const*argv, + sqlite3_vtab **ppVtab, + char **pzErr +){ + return rtreeInit(db, pAux, argc, argv, ppVtab, pzErr, 1, (int)pAux); +} + +/* +** Rtree virtual table module xConnect method. +*/ +static int rtreeConnect( + sqlite3 *db, + void *pAux, + int argc, const char *const*argv, + sqlite3_vtab **ppVtab, + char **pzErr +){ + return rtreeInit(db, pAux, argc, argv, ppVtab, pzErr, 0, (int)pAux); +} + +/* +** Increment the r-tree reference count. +*/ +static void rtreeReference(Rtree *pRtree){ + pRtree->nBusy++; +} + +/* +** Decrement the r-tree reference count. When the reference count reaches +** zero the structure is deleted. +*/ +static void rtreeRelease(Rtree *pRtree){ + pRtree->nBusy--; + if( pRtree->nBusy==0 ){ + sqlite3_finalize(pRtree->pReadNode); + sqlite3_finalize(pRtree->pWriteNode); + sqlite3_finalize(pRtree->pDeleteNode); + sqlite3_finalize(pRtree->pReadRowid); + sqlite3_finalize(pRtree->pWriteRowid); + sqlite3_finalize(pRtree->pDeleteRowid); + sqlite3_finalize(pRtree->pReadParent); + sqlite3_finalize(pRtree->pWriteParent); + sqlite3_finalize(pRtree->pDeleteParent); + sqlite3_free(pRtree); + } +} + +/* +** Rtree virtual table module xDisconnect method. +*/ +static int rtreeDisconnect(sqlite3_vtab *pVtab){ + rtreeRelease((Rtree *)pVtab); + return SQLITE_OK; +} + +/* +** Rtree virtual table module xDestroy method. +*/ +static int rtreeDestroy(sqlite3_vtab *pVtab){ + Rtree *pRtree = (Rtree *)pVtab; + int rc; + char *zCreate = sqlite3_mprintf( + "DROP TABLE '%q'.'%q_node';" + "DROP TABLE '%q'.'%q_rowid';" + "DROP TABLE '%q'.'%q_parent';", + pRtree->zDb, pRtree->zName, + pRtree->zDb, pRtree->zName, + pRtree->zDb, pRtree->zName + ); + if( !zCreate ){ + rc = SQLITE_NOMEM; + }else{ + rc = sqlite3_exec(pRtree->db, zCreate, 0, 0, 0); + sqlite3_free(zCreate); + } + if( rc==SQLITE_OK ){ + rtreeRelease(pRtree); + } + + return rc; +} + +/* +** Rtree virtual table module xOpen method. +*/ +static int rtreeOpen(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor){ + int rc = SQLITE_NOMEM; + RtreeCursor *pCsr; + + pCsr = (RtreeCursor *)sqlite3_malloc(sizeof(RtreeCursor)); + if( pCsr ){ + memset(pCsr, 0, sizeof(RtreeCursor)); + pCsr->base.pVtab = pVTab; + rc = SQLITE_OK; + } + *ppCursor = (sqlite3_vtab_cursor *)pCsr; + + return rc; +} + +/* +** Rtree virtual table module xClose method. +*/ +static int rtreeClose(sqlite3_vtab_cursor *cur){ + Rtree *pRtree = (Rtree *)(cur->pVtab); + int rc; + RtreeCursor *pCsr = (RtreeCursor *)cur; + sqlite3_free(pCsr->aConstraint); + rc = nodeRelease(pRtree, pCsr->pNode); + sqlite3_free(pCsr); + return rc; +} + +/* +** Rtree virtual table module xEof method. +** +** Return non-zero if the cursor does not currently point to a valid +** record (i.e if the scan has finished), or zero otherwise. +*/ +static int rtreeEof(sqlite3_vtab_cursor *cur){ + RtreeCursor *pCsr = (RtreeCursor *)cur; + return (pCsr->pNode==0); +} + +/* +** Cursor pCursor currently points to a cell in a non-leaf page. +** Return true if the sub-tree headed by the cell is filtered +** (excluded) by the constraints in the pCursor->aConstraint[] +** array, or false otherwise. +*/ +static int testRtreeCell(Rtree *pRtree, RtreeCursor *pCursor){ + RtreeCell cell; + int ii; + int bRes = 0; + + nodeGetCell(pRtree, pCursor->pNode, pCursor->iCell, &cell); + for(ii=0; bRes==0 && ii<pCursor->nConstraint; ii++){ + RtreeConstraint *p = &pCursor->aConstraint[ii]; + double cell_min = DCOORD(cell.aCoord[(p->iCoord>>1)*2]); + double cell_max = DCOORD(cell.aCoord[(p->iCoord>>1)*2+1]); + + assert(p->op==RTREE_LE || p->op==RTREE_LT || p->op==RTREE_GE + || p->op==RTREE_GT || p->op==RTREE_EQ + ); + + switch( p->op ){ + case RTREE_LE: case RTREE_LT: bRes = p->rValue<cell_min; break; + case RTREE_GE: case RTREE_GT: bRes = p->rValue>cell_max; break; + case RTREE_EQ: + bRes = (p->rValue>cell_max || p->rValue<cell_min); + break; + } + } + + return bRes; +} + +/* +** Return true if the cell that cursor pCursor currently points to +** would be filtered (excluded) by the constraints in the +** pCursor->aConstraint[] array, or false otherwise. +** +** This function assumes that the cell is part of a leaf node. +*/ +static int testRtreeEntry(Rtree *pRtree, RtreeCursor *pCursor){ + RtreeCell cell; + int ii; + + nodeGetCell(pRtree, pCursor->pNode, pCursor->iCell, &cell); + for(ii=0; ii<pCursor->nConstraint; ii++){ + RtreeConstraint *p = &pCursor->aConstraint[ii]; + double coord = DCOORD(cell.aCoord[p->iCoord]); + int res; + assert(p->op==RTREE_LE || p->op==RTREE_LT || p->op==RTREE_GE + || p->op==RTREE_GT || p->op==RTREE_EQ + ); + switch( p->op ){ + case RTREE_LE: res = (coord<=p->rValue); break; + case RTREE_LT: res = (coord<p->rValue); break; + case RTREE_GE: res = (coord>=p->rValue); break; + case RTREE_GT: res = (coord>p->rValue); break; + case RTREE_EQ: res = (coord==p->rValue); break; + } + + if( !res ) return 1; + } + + return 0; +} + +/* +** Cursor pCursor currently points at a node that heads a sub-tree of +** height iHeight (if iHeight==0, then the node is a leaf). Descend +** to point to the left-most cell of the sub-tree that matches the +** configured constraints. +*/ +static int descendToCell( + Rtree *pRtree, + RtreeCursor *pCursor, + int iHeight, + int *pEof /* OUT: Set to true if cannot descend */ +){ + int isEof; + int rc; + int ii; + RtreeNode *pChild; + sqlite3_int64 iRowid; + + RtreeNode *pSavedNode = pCursor->pNode; + int iSavedCell = pCursor->iCell; + + assert( iHeight>=0 ); + + if( iHeight==0 ){ + isEof = testRtreeEntry(pRtree, pCursor); + }else{ + isEof = testRtreeCell(pRtree, pCursor); + } + if( isEof || iHeight==0 ){ + *pEof = isEof; + return SQLITE_OK; + } + + iRowid = nodeGetRowid(pRtree, pCursor->pNode, pCursor->iCell); + rc = nodeAcquire(pRtree, iRowid, pCursor->pNode, &pChild); + if( rc!=SQLITE_OK ){ + return rc; + } + + nodeRelease(pRtree, pCursor->pNode); + pCursor->pNode = pChild; + isEof = 1; + for(ii=0; isEof && ii<NCELL(pChild); ii++){ + pCursor->iCell = ii; + rc = descendToCell(pRtree, pCursor, iHeight-1, &isEof); + if( rc!=SQLITE_OK ){ + return rc; + } + } + + if( isEof ){ + assert( pCursor->pNode==pChild ); + nodeReference(pSavedNode); + nodeRelease(pRtree, pChild); + pCursor->pNode = pSavedNode; + pCursor->iCell = iSavedCell; + } + + *pEof = isEof; + return SQLITE_OK; +} + +/* +** One of the cells in node pNode is guaranteed to have a 64-bit +** integer value equal to iRowid. Return the index of this cell. +*/ +static int nodeRowidIndex(Rtree *pRtree, RtreeNode *pNode, i64 iRowid){ + int ii; + for(ii=0; nodeGetRowid(pRtree, pNode, ii)!=iRowid; ii++){ + assert( ii<(NCELL(pNode)-1) ); + } + return ii; +} + +/* +** Return the index of the cell containing a pointer to node pNode +** in its parent. If pNode is the root node, return -1. +*/ +static int nodeParentIndex(Rtree *pRtree, RtreeNode *pNode){ + RtreeNode *pParent = pNode->pParent; + if( pParent ){ + return nodeRowidIndex(pRtree, pParent, pNode->iNode); + } + return -1; +} + +/* +** Rtree virtual table module xNext method. +*/ +static int rtreeNext(sqlite3_vtab_cursor *pVtabCursor){ + Rtree *pRtree = (Rtree *)(pVtabCursor->pVtab); + RtreeCursor *pCsr = (RtreeCursor *)pVtabCursor; + int rc = SQLITE_OK; + + if( pCsr->iStrategy==1 ){ + /* This "scan" is a direct lookup by rowid. There is no next entry. */ + nodeRelease(pRtree, pCsr->pNode); + pCsr->pNode = 0; + } + + else if( pCsr->pNode ){ + /* Move to the next entry that matches the configured constraints. */ + int iHeight = 0; + while( pCsr->pNode ){ + RtreeNode *pNode = pCsr->pNode; + int nCell = NCELL(pNode); + for(pCsr->iCell++; pCsr->iCell<nCell; pCsr->iCell++){ + int isEof; + rc = descendToCell(pRtree, pCsr, iHeight, &isEof); + if( rc!=SQLITE_OK || !isEof ){ + return rc; + } + } + pCsr->pNode = pNode->pParent; + pCsr->iCell = nodeParentIndex(pRtree, pNode); + nodeReference(pCsr->pNode); + nodeRelease(pRtree, pNode); + iHeight++; + } + } + + return rc; +} + +/* +** Rtree virtual table module xRowid method. +*/ +static int rtreeRowid(sqlite3_vtab_cursor *pVtabCursor, sqlite_int64 *pRowid){ + Rtree *pRtree = (Rtree *)pVtabCursor->pVtab; + RtreeCursor *pCsr = (RtreeCursor *)pVtabCursor; + + assert(pCsr->pNode); + *pRowid = nodeGetRowid(pRtree, pCsr->pNode, pCsr->iCell); + + return SQLITE_OK; +} + +/* +** Rtree virtual table module xColumn method. +*/ +static int rtreeColumn(sqlite3_vtab_cursor *cur, sqlite3_context *ctx, int i){ + Rtree *pRtree = (Rtree *)cur->pVtab; + RtreeCursor *pCsr = (RtreeCursor *)cur; + + if( i==0 ){ + i64 iRowid = nodeGetRowid(pRtree, pCsr->pNode, pCsr->iCell); + sqlite3_result_int64(ctx, iRowid); + }else{ + RtreeCoord c; + nodeGetCoord(pRtree, pCsr->pNode, pCsr->iCell, i-1, &c); + if( pRtree->eCoordType==RTREE_COORD_REAL32 ){ + sqlite3_result_double(ctx, c.f); + }else{ + assert( pRtree->eCoordType==RTREE_COORD_INT32 ); + sqlite3_result_int(ctx, c.i); + } + } + + return SQLITE_OK; +} + +/* +** Use nodeAcquire() to obtain the leaf node containing the record with +** rowid iRowid. If successful, set *ppLeaf to point to the node and +** return SQLITE_OK. If there is no such record in the table, set +** *ppLeaf to 0 and return SQLITE_OK. If an error occurs, set *ppLeaf +** to zero and return an SQLite error code. +*/ +static int findLeafNode(Rtree *pRtree, i64 iRowid, RtreeNode **ppLeaf){ + int rc; + *ppLeaf = 0; + sqlite3_bind_int64(pRtree->pReadRowid, 1, iRowid); + if( sqlite3_step(pRtree->pReadRowid)==SQLITE_ROW ){ + i64 iNode = sqlite3_column_int64(pRtree->pReadRowid, 0); + rc = nodeAcquire(pRtree, iNode, 0, ppLeaf); + sqlite3_reset(pRtree->pReadRowid); + }else{ + rc = sqlite3_reset(pRtree->pReadRowid); + } + return rc; +} + + +/* +** Rtree virtual table module xFilter method. +*/ +static int rtreeFilter( + sqlite3_vtab_cursor *pVtabCursor, + int idxNum, const char *idxStr, + int argc, sqlite3_value **argv +){ + Rtree *pRtree = (Rtree *)pVtabCursor->pVtab; + RtreeCursor *pCsr = (RtreeCursor *)pVtabCursor; + + RtreeNode *pRoot = 0; + int ii; + int rc = SQLITE_OK; + + rtreeReference(pRtree); + + sqlite3_free(pCsr->aConstraint); + pCsr->aConstraint = 0; + pCsr->iStrategy = idxNum; + + if( idxNum==1 ){ + /* Special case - lookup by rowid. */ + RtreeNode *pLeaf; /* Leaf on which the required cell resides */ + i64 iRowid = sqlite3_value_int64(argv[0]); + rc = findLeafNode(pRtree, iRowid, &pLeaf); + pCsr->pNode = pLeaf; + if( pLeaf && rc==SQLITE_OK ){ + pCsr->iCell = nodeRowidIndex(pRtree, pLeaf, iRowid); + } + }else{ + /* Normal case - r-tree scan. Set up the RtreeCursor.aConstraint array + ** with the configured constraints. + */ + if( argc>0 ){ + pCsr->aConstraint = sqlite3_malloc(sizeof(RtreeConstraint)*argc); + pCsr->nConstraint = argc; + if( !pCsr->aConstraint ){ + rc = SQLITE_NOMEM; + }else{ + assert( (idxStr==0 && argc==0) || strlen(idxStr)==argc*2 ); + for(ii=0; ii<argc; ii++){ + RtreeConstraint *p = &pCsr->aConstraint[ii]; + p->op = idxStr[ii*2]; + p->iCoord = idxStr[ii*2+1]-'a'; + p->rValue = sqlite3_value_double(argv[ii]); + } + } + } + + if( rc==SQLITE_OK ){ + pCsr->pNode = 0; + rc = nodeAcquire(pRtree, 1, 0, &pRoot); + } + if( rc==SQLITE_OK ){ + int isEof = 1; + int nCell = NCELL(pRoot); + pCsr->pNode = pRoot; + for(pCsr->iCell=0; rc==SQLITE_OK && pCsr->iCell<nCell; pCsr->iCell++){ + assert( pCsr->pNode==pRoot ); + rc = descendToCell(pRtree, pCsr, pRtree->iDepth, &isEof); + if( !isEof ){ + break; + } + } + if( rc==SQLITE_OK && isEof ){ + assert( pCsr->pNode==pRoot ); + nodeRelease(pRtree, pRoot); + pCsr->pNode = 0; + } + assert( rc!=SQLITE_OK || !pCsr->pNode || pCsr->iCell<NCELL(pCsr->pNode) ); + } + } + + rtreeRelease(pRtree); + return rc; +} + +/* +** Rtree virtual table module xBestIndex method. There are three +** table scan strategies to choose from (in order from most to +** least desirable): +** +** idxNum idxStr Strategy +** ------------------------------------------------ +** 1 Unused Direct lookup by rowid. +** 2 See below R-tree query. +** 3 Unused Full table scan. +** ------------------------------------------------ +** +** If strategy 1 or 3 is used, then idxStr is not meaningful. If strategy +** 2 is used, idxStr is formatted to contain 2 bytes for each +** constraint used. The first two bytes of idxStr correspond to +** the constraint in sqlite3_index_info.aConstraintUsage[] with +** (argvIndex==1) etc. +** +** The first of each pair of bytes in idxStr identifies the constraint +** operator as follows: +** +** Operator Byte Value +** ---------------------- +** = 0x41 ('A') +** <= 0x42 ('B') +** < 0x43 ('C') +** >= 0x44 ('D') +** > 0x45 ('E') +** ---------------------- +** +** The second of each pair of bytes identifies the coordinate column +** to which the constraint applies. The leftmost coordinate column +** is 'a', the second from the left 'b' etc. +*/ +static int rtreeBestIndex(sqlite3_vtab *tab, sqlite3_index_info *pIdxInfo){ + int rc = SQLITE_OK; + int ii, cCol; + + int iIdx = 0; + char zIdxStr[RTREE_MAX_DIMENSIONS*8+1]; + memset(zIdxStr, 0, sizeof(zIdxStr)); + + assert( pIdxInfo->idxStr==0 ); + for(ii=0; ii<pIdxInfo->nConstraint; ii++){ + struct sqlite3_index_constraint *p = &pIdxInfo->aConstraint[ii]; + + if( p->usable && p->iColumn==0 && p->op==SQLITE_INDEX_CONSTRAINT_EQ ){ + /* We have an equality constraint on the rowid. Use strategy 1. */ + int jj; + for(jj=0; jj<ii; jj++){ + pIdxInfo->aConstraintUsage[jj].argvIndex = 0; + pIdxInfo->aConstraintUsage[jj].omit = 0; + } + pIdxInfo->idxNum = 1; + pIdxInfo->aConstraintUsage[ii].argvIndex = 1; + pIdxInfo->aConstraintUsage[jj].omit = 1; + return SQLITE_OK; + } + + if( p->usable && p->iColumn>0 ){ + u8 op = 0; + switch( p->op ){ + case SQLITE_INDEX_CONSTRAINT_EQ: op = RTREE_EQ; break; + case SQLITE_INDEX_CONSTRAINT_GT: op = RTREE_GT; break; + case SQLITE_INDEX_CONSTRAINT_LE: op = RTREE_LE; break; + case SQLITE_INDEX_CONSTRAINT_LT: op = RTREE_LT; break; + case SQLITE_INDEX_CONSTRAINT_GE: op = RTREE_GE; break; + } + if( op ){ + /* Make sure this particular constraint has not been used before. + ** If it has been used before, ignore it. + ** + ** A <= or < can be used if there is a prior >= or >. + ** A >= or > can be used if there is a prior < or <=. + ** A <= or < is disqualified if there is a prior <=, <, or ==. + ** A >= or > is disqualified if there is a prior >=, >, or ==. + ** A == is disqualifed if there is any prior constraint. + */ + int j, opmsk; + static const unsigned char compatible[] = { 0, 0, 1, 1, 2, 2 }; + assert( compatible[RTREE_EQ & 7]==0 ); + assert( compatible[RTREE_LT & 7]==1 ); + assert( compatible[RTREE_LE & 7]==1 ); + assert( compatible[RTREE_GT & 7]==2 ); + assert( compatible[RTREE_GE & 7]==2 ); + cCol = p->iColumn - 1 + 'a'; + opmsk = compatible[op & 7]; + for(j=0; j<iIdx; j+=2){ + if( zIdxStr[j+1]==cCol && (compatible[zIdxStr[j] & 7] & opmsk)!=0 ){ + op = 0; + break; + } + } + } + if( op ){ + assert( iIdx<sizeof(zIdxStr)-1 ); + zIdxStr[iIdx++] = op; + zIdxStr[iIdx++] = cCol; + pIdxInfo->aConstraintUsage[ii].argvIndex = (iIdx/2); + pIdxInfo->aConstraintUsage[ii].omit = 1; + } + } + } + + pIdxInfo->idxNum = 2; + pIdxInfo->needToFreeIdxStr = 1; + if( iIdx>0 && 0==(pIdxInfo->idxStr = sqlite3_mprintf("%s", zIdxStr)) ){ + return SQLITE_NOMEM; + } + return rc; +} + +/* +** Return the N-dimensional volumn of the cell stored in *p. +*/ +static float cellArea(Rtree *pRtree, RtreeCell *p){ + float area = 1.0; + int ii; + for(ii=0; ii<(pRtree->nDim*2); ii+=2){ + area = area * (DCOORD(p->aCoord[ii+1]) - DCOORD(p->aCoord[ii])); + } + return area; +} + +/* +** Return the margin length of cell p. The margin length is the sum +** of the objects size in each dimension. +*/ +static float cellMargin(Rtree *pRtree, RtreeCell *p){ + float margin = 0.0; + int ii; + for(ii=0; ii<(pRtree->nDim*2); ii+=2){ + margin += (DCOORD(p->aCoord[ii+1]) - DCOORD(p->aCoord[ii])); + } + return margin; +} + +/* +** Store the union of cells p1 and p2 in p1. +*/ +static void cellUnion(Rtree *pRtree, RtreeCell *p1, RtreeCell *p2){ + int ii; + if( pRtree->eCoordType==RTREE_COORD_REAL32 ){ + for(ii=0; ii<(pRtree->nDim*2); ii+=2){ + p1->aCoord[ii].f = MIN(p1->aCoord[ii].f, p2->aCoord[ii].f); + p1->aCoord[ii+1].f = MAX(p1->aCoord[ii+1].f, p2->aCoord[ii+1].f); + } + }else{ + for(ii=0; ii<(pRtree->nDim*2); ii+=2){ + p1->aCoord[ii].i = MIN(p1->aCoord[ii].i, p2->aCoord[ii].i); + p1->aCoord[ii+1].i = MAX(p1->aCoord[ii+1].i, p2->aCoord[ii+1].i); + } + } +} + +/* +** Return the amount cell p would grow by if it were unioned with pCell. +*/ +static float cellGrowth(Rtree *pRtree, RtreeCell *p, RtreeCell *pCell){ + float area; + RtreeCell cell; + memcpy(&cell, p, sizeof(RtreeCell)); + area = cellArea(pRtree, &cell); + cellUnion(pRtree, &cell, pCell); + return (cellArea(pRtree, &cell)-area); +} + +#if VARIANT_RSTARTREE_CHOOSESUBTREE || VARIANT_RSTARTREE_SPLIT +static float cellOverlap( + Rtree *pRtree, + RtreeCell *p, + RtreeCell *aCell, + int nCell, + int iExclude +){ + int ii; + float overlap = 0.0; + for(ii=0; ii<nCell; ii++){ + if( ii!=iExclude ){ + int jj; + float o = 1.0; + for(jj=0; jj<(pRtree->nDim*2); jj+=2){ + double x1; + double x2; + + x1 = MAX(DCOORD(p->aCoord[jj]), DCOORD(aCell[ii].aCoord[jj])); + x2 = MIN(DCOORD(p->aCoord[jj+1]), DCOORD(aCell[ii].aCoord[jj+1])); + + if( x2<x1 ){ + o = 0.0; + break; + }else{ + o = o * (x2-x1); + } + } + overlap += o; + } + } + return overlap; +} +#endif + +#if VARIANT_RSTARTREE_CHOOSESUBTREE +static float cellOverlapEnlargement( + Rtree *pRtree, + RtreeCell *p, + RtreeCell *pInsert, + RtreeCell *aCell, + int nCell, + int iExclude +){ + float before; + float after; + before = cellOverlap(pRtree, p, aCell, nCell, iExclude); + cellUnion(pRtree, p, pInsert); + after = cellOverlap(pRtree, p, aCell, nCell, iExclude); + return after-before; +} +#endif + + +/* +** This function implements the ChooseLeaf algorithm from Gutman[84]. +** ChooseSubTree in r*tree terminology. +*/ +static int ChooseLeaf( + Rtree *pRtree, /* Rtree table */ + RtreeCell *pCell, /* Cell to insert into rtree */ + int iHeight, /* Height of sub-tree rooted at pCell */ + RtreeNode **ppLeaf /* OUT: Selected leaf page */ +){ + int rc; + int ii; + RtreeNode *pNode; + rc = nodeAcquire(pRtree, 1, 0, &pNode); + + for(ii=0; rc==SQLITE_OK && ii<(pRtree->iDepth-iHeight); ii++){ + int iCell; + sqlite3_int64 iBest; + + float fMinGrowth; + float fMinArea; + float fMinOverlap; + + int nCell = NCELL(pNode); + RtreeCell cell; + RtreeNode *pChild; + + RtreeCell *aCell = 0; + +#if VARIANT_RSTARTREE_CHOOSESUBTREE + if( ii==(pRtree->iDepth-1) ){ + int jj; + aCell = sqlite3_malloc(sizeof(RtreeCell)*nCell); + if( !aCell ){ + rc = SQLITE_NOMEM; + nodeRelease(pRtree, pNode); + pNode = 0; + continue; + } + for(jj=0; jj<nCell; jj++){ + nodeGetCell(pRtree, pNode, jj, &aCell[jj]); + } + } +#endif + + /* Select the child node which will be enlarged the least if pCell + ** is inserted into it. Resolve ties by choosing the entry with + ** the smallest area. + */ + for(iCell=0; iCell<nCell; iCell++){ + float growth; + float area; + float overlap = 0.0; + nodeGetCell(pRtree, pNode, iCell, &cell); + growth = cellGrowth(pRtree, &cell, pCell); + area = cellArea(pRtree, &cell); +#if VARIANT_RSTARTREE_CHOOSESUBTREE + if( ii==(pRtree->iDepth-1) ){ + overlap = cellOverlapEnlargement(pRtree,&cell,pCell,aCell,nCell,iCell); + } +#endif + if( (iCell==0) + || (overlap<fMinOverlap) + || (overlap==fMinOverlap && growth<fMinGrowth) + || (overlap==fMinOverlap && growth==fMinGrowth && area<fMinArea) + ){ + fMinOverlap = overlap; + fMinGrowth = growth; + fMinArea = area; + iBest = cell.iRowid; + } + } + + sqlite3_free(aCell); + rc = nodeAcquire(pRtree, iBest, pNode, &pChild); + nodeRelease(pRtree, pNode); + pNode = pChild; + } + + *ppLeaf = pNode; + return rc; +} + +/* +** A cell with the same content as pCell has just been inserted into +** the node pNode. This function updates the bounding box cells in +** all ancestor elements. +*/ +static void AdjustTree( + Rtree *pRtree, /* Rtree table */ + RtreeNode *pNode, /* Adjust ancestry of this node. */ + RtreeCell *pCell /* This cell was just inserted */ +){ + RtreeNode *p = pNode; + while( p->pParent ){ + RtreeCell cell; + RtreeNode *pParent = p->pParent; + int iCell = nodeParentIndex(pRtree, p); + + nodeGetCell(pRtree, pParent, iCell, &cell); + if( cellGrowth(pRtree, &cell, pCell)>0.0 ){ + cellUnion(pRtree, &cell, pCell); + nodeOverwriteCell(pRtree, pParent, &cell, iCell); + } + + p = pParent; + } +} + +/* +** Write mapping (iRowid->iNode) to the <rtree>_rowid table. +*/ +static int rowidWrite(Rtree *pRtree, sqlite3_int64 iRowid, sqlite3_int64 iNode){ + sqlite3_bind_int64(pRtree->pWriteRowid, 1, iRowid); + sqlite3_bind_int64(pRtree->pWriteRowid, 2, iNode); + sqlite3_step(pRtree->pWriteRowid); + return sqlite3_reset(pRtree->pWriteRowid); +} + +/* +** Write mapping (iNode->iPar) to the <rtree>_parent table. +*/ +static int parentWrite(Rtree *pRtree, sqlite3_int64 iNode, sqlite3_int64 iPar){ + sqlite3_bind_int64(pRtree->pWriteParent, 1, iNode); + sqlite3_bind_int64(pRtree->pWriteParent, 2, iPar); + sqlite3_step(pRtree->pWriteParent); + return sqlite3_reset(pRtree->pWriteParent); +} + +static int rtreeInsertCell(Rtree *, RtreeNode *, RtreeCell *, int); + +#if VARIANT_GUTTMAN_LINEAR_SPLIT +/* +** Implementation of the linear variant of the PickNext() function from +** Guttman[84]. +*/ +static RtreeCell *LinearPickNext( + Rtree *pRtree, + RtreeCell *aCell, + int nCell, + RtreeCell *pLeftBox, + RtreeCell *pRightBox, + int *aiUsed +){ + int ii; + for(ii=0; aiUsed[ii]; ii++); + aiUsed[ii] = 1; + return &aCell[ii]; +} + +/* +** Implementation of the linear variant of the PickSeeds() function from +** Guttman[84]. +*/ +static void LinearPickSeeds( + Rtree *pRtree, + RtreeCell *aCell, + int nCell, + int *piLeftSeed, + int *piRightSeed +){ + int i; + int iLeftSeed = 0; + int iRightSeed = 1; + float maxNormalInnerWidth = 0.0; + + /* Pick two "seed" cells from the array of cells. The algorithm used + ** here is the LinearPickSeeds algorithm from Gutman[1984]. The + ** indices of the two seed cells in the array are stored in local + ** variables iLeftSeek and iRightSeed. + */ + for(i=0; i<pRtree->nDim; i++){ + float x1 = aCell[0].aCoord[i*2]; + float x2 = aCell[0].aCoord[i*2+1]; + float x3 = x1; + float x4 = x2; + int jj; + + int iCellLeft = 0; + int iCellRight = 0; + + for(jj=1; jj<nCell; jj++){ + float left = aCell[jj].aCoord[i*2]; + float right = aCell[jj].aCoord[i*2+1]; + + if( left<x1 ) x1 = left; + if( right>x4 ) x4 = right; + if( left>x3 ){ + x3 = left; + iCellRight = jj; + } + if( right<x2 ){ + x2 = right; + iCellLeft = jj; + } + } + + if( x4!=x1 ){ + float normalwidth = (x3 - x2) / (x4 - x1); + if( normalwidth>maxNormalInnerWidth ){ + iLeftSeed = iCellLeft; + iRightSeed = iCellRight; + } + } + } + + *piLeftSeed = iLeftSeed; + *piRightSeed = iRightSeed; +} +#endif /* VARIANT_GUTTMAN_LINEAR_SPLIT */ + +#if VARIANT_GUTTMAN_QUADRATIC_SPLIT +/* +** Implementation of the quadratic variant of the PickNext() function from +** Guttman[84]. +*/ +static RtreeCell *QuadraticPickNext( + Rtree *pRtree, + RtreeCell *aCell, + int nCell, + RtreeCell *pLeftBox, + RtreeCell *pRightBox, + int *aiUsed +){ + #define FABS(a) ((a)<0.0?-1.0*(a):(a)) + + int iSelect = -1; + float fDiff; + int ii; + for(ii=0; ii<nCell; ii++){ + if( aiUsed[ii]==0 ){ + float left = cellGrowth(pRtree, pLeftBox, &aCell[ii]); + float right = cellGrowth(pRtree, pLeftBox, &aCell[ii]); + float diff = FABS(right-left); + if( iSelect<0 || diff>fDiff ){ + fDiff = diff; + iSelect = ii; + } + } + } + aiUsed[iSelect] = 1; + return &aCell[iSelect]; +} + +/* +** Implementation of the quadratic variant of the PickSeeds() function from +** Guttman[84]. +*/ +static void QuadraticPickSeeds( + Rtree *pRtree, + RtreeCell *aCell, + int nCell, + int *piLeftSeed, + int *piRightSeed +){ + int ii; + int jj; + + int iLeftSeed = 0; + int iRightSeed = 1; + float fWaste = 0.0; + + for(ii=0; ii<nCell; ii++){ + for(jj=ii+1; jj<nCell; jj++){ + float right = cellArea(pRtree, &aCell[jj]); + float growth = cellGrowth(pRtree, &aCell[ii], &aCell[jj]); + float waste = growth - right; + + if( waste>fWaste ){ + iLeftSeed = ii; + iRightSeed = jj; + fWaste = waste; + } + } + } + + *piLeftSeed = iLeftSeed; + *piRightSeed = iRightSeed; +} +#endif /* VARIANT_GUTTMAN_QUADRATIC_SPLIT */ + +/* +** Arguments aIdx, aDistance and aSpare all point to arrays of size +** nIdx. The aIdx array contains the set of integers from 0 to +** (nIdx-1) in no particular order. This function sorts the values +** in aIdx according to the indexed values in aDistance. For +** example, assuming the inputs: +** +** aIdx = { 0, 1, 2, 3 } +** aDistance = { 5.0, 2.0, 7.0, 6.0 } +** +** this function sets the aIdx array to contain: +** +** aIdx = { 0, 1, 2, 3 } +** +** The aSpare array is used as temporary working space by the +** sorting algorithm. +*/ +static void SortByDistance( + int *aIdx, + int nIdx, + float *aDistance, + int *aSpare +){ + if( nIdx>1 ){ + int iLeft = 0; + int iRight = 0; + + int nLeft = nIdx/2; + int nRight = nIdx-nLeft; + int *aLeft = aIdx; + int *aRight = &aIdx[nLeft]; + + SortByDistance(aLeft, nLeft, aDistance, aSpare); + SortByDistance(aRight, nRight, aDistance, aSpare); + + memcpy(aSpare, aLeft, sizeof(int)*nLeft); + aLeft = aSpare; + + while( iLeft<nLeft || iRight<nRight ){ + if( iLeft==nLeft ){ + aIdx[iLeft+iRight] = aRight[iRight]; + iRight++; + }else if( iRight==nRight ){ + aIdx[iLeft+iRight] = aLeft[iLeft]; + iLeft++; + }else{ + float fLeft = aDistance[aLeft[iLeft]]; + float fRight = aDistance[aRight[iRight]]; + if( fLeft<fRight ){ + aIdx[iLeft+iRight] = aLeft[iLeft]; + iLeft++; + }else{ + aIdx[iLeft+iRight] = aRight[iRight]; + iRight++; + } + } + } + +#if 0 + /* Check that the sort worked */ + { + int jj; + for(jj=1; jj<nIdx; jj++){ + float left = aDistance[aIdx[jj-1]]; + float right = aDistance[aIdx[jj]]; + assert( left<=right ); + } + } +#endif + } +} + +/* +** Arguments aIdx, aCell and aSpare all point to arrays of size +** nIdx. The aIdx array contains the set of integers from 0 to +** (nIdx-1) in no particular order. This function sorts the values +** in aIdx according to dimension iDim of the cells in aCell. The +** minimum value of dimension iDim is considered first, the +** maximum used to break ties. +** +** The aSpare array is used as temporary working space by the +** sorting algorithm. +*/ +static void SortByDimension( + Rtree *pRtree, + int *aIdx, + int nIdx, + int iDim, + RtreeCell *aCell, + int *aSpare +){ + if( nIdx>1 ){ + + int iLeft = 0; + int iRight = 0; + + int nLeft = nIdx/2; + int nRight = nIdx-nLeft; + int *aLeft = aIdx; + int *aRight = &aIdx[nLeft]; + + SortByDimension(pRtree, aLeft, nLeft, iDim, aCell, aSpare); + SortByDimension(pRtree, aRight, nRight, iDim, aCell, aSpare); + + memcpy(aSpare, aLeft, sizeof(int)*nLeft); + aLeft = aSpare; + while( iLeft<nLeft || iRight<nRight ){ + double xleft1 = DCOORD(aCell[aLeft[iLeft]].aCoord[iDim*2]); + double xleft2 = DCOORD(aCell[aLeft[iLeft]].aCoord[iDim*2+1]); + double xright1 = DCOORD(aCell[aRight[iRight]].aCoord[iDim*2]); + double xright2 = DCOORD(aCell[aRight[iRight]].aCoord[iDim*2+1]); + if( (iLeft!=nLeft) && ((iRight==nRight) + || (xleft1<xright1) + || (xleft1==xright1 && xleft2<xright2) + )){ + aIdx[iLeft+iRight] = aLeft[iLeft]; + iLeft++; + }else{ + aIdx[iLeft+iRight] = aRight[iRight]; + iRight++; + } + } + +#if 0 + /* Check that the sort worked */ + { + int jj; + for(jj=1; jj<nIdx; jj++){ + float xleft1 = aCell[aIdx[jj-1]].aCoord[iDim*2]; + float xleft2 = aCell[aIdx[jj-1]].aCoord[iDim*2+1]; + float xright1 = aCell[aIdx[jj]].aCoord[iDim*2]; + float xright2 = aCell[aIdx[jj]].aCoord[iDim*2+1]; + assert( xleft1<=xright1 && (xleft1<xright1 || xleft2<=xright2) ); + } + } +#endif + } +} + +#if VARIANT_RSTARTREE_SPLIT +/* +** Implementation of the R*-tree variant of SplitNode from Beckman[1990]. +*/ +static int splitNodeStartree( + Rtree *pRtree, + RtreeCell *aCell, + int nCell, + RtreeNode *pLeft, + RtreeNode *pRight, + RtreeCell *pBboxLeft, + RtreeCell *pBboxRight +){ + int **aaSorted; + int *aSpare; + int ii; + + int iBestDim; + int iBestSplit; + float fBestMargin; + + int nByte = (pRtree->nDim+1)*(sizeof(int*)+nCell*sizeof(int)); + + aaSorted = (int **)sqlite3_malloc(nByte); + if( !aaSorted ){ + return SQLITE_NOMEM; + } + + aSpare = &((int *)&aaSorted[pRtree->nDim])[pRtree->nDim*nCell]; + memset(aaSorted, 0, nByte); + for(ii=0; ii<pRtree->nDim; ii++){ + int jj; + aaSorted[ii] = &((int *)&aaSorted[pRtree->nDim])[ii*nCell]; + for(jj=0; jj<nCell; jj++){ + aaSorted[ii][jj] = jj; + } + SortByDimension(pRtree, aaSorted[ii], nCell, ii, aCell, aSpare); + } + + for(ii=0; ii<pRtree->nDim; ii++){ + float margin = 0.0; + float fBestOverlap; + float fBestArea; + int iBestLeft; + int nLeft; + + for( + nLeft=RTREE_MINCELLS(pRtree); + nLeft<=(nCell-RTREE_MINCELLS(pRtree)); + nLeft++ + ){ + RtreeCell left; + RtreeCell right; + int kk; + float overlap; + float area; + + memcpy(&left, &aCell[aaSorted[ii][0]], sizeof(RtreeCell)); + memcpy(&right, &aCell[aaSorted[ii][nCell-1]], sizeof(RtreeCell)); + for(kk=1; kk<(nCell-1); kk++){ + if( kk<nLeft ){ + cellUnion(pRtree, &left, &aCell[aaSorted[ii][kk]]); + }else{ + cellUnion(pRtree, &right, &aCell[aaSorted[ii][kk]]); + } + } + margin += cellMargin(pRtree, &left); + margin += cellMargin(pRtree, &right); + overlap = cellOverlap(pRtree, &left, &right, 1, -1); + area = cellArea(pRtree, &left) + cellArea(pRtree, &right); + if( (nLeft==RTREE_MINCELLS(pRtree)) + || (overlap<fBestOverlap) + || (overlap==fBestOverlap && area<fBestArea) + ){ + iBestLeft = nLeft; + fBestOverlap = overlap; + fBestArea = area; + } + } + + if( ii==0 || margin<fBestMargin ){ + iBestDim = ii; + fBestMargin = margin; + iBestSplit = iBestLeft; + } + } + + memcpy(pBboxLeft, &aCell[aaSorted[iBestDim][0]], sizeof(RtreeCell)); + memcpy(pBboxRight, &aCell[aaSorted[iBestDim][iBestSplit]], sizeof(RtreeCell)); + for(ii=0; ii<nCell; ii++){ + RtreeNode *pTarget = (ii<iBestSplit)?pLeft:pRight; + RtreeCell *pBbox = (ii<iBestSplit)?pBboxLeft:pBboxRight; + RtreeCell *pCell = &aCell[aaSorted[iBestDim][ii]]; + nodeInsertCell(pRtree, pTarget, pCell); + cellUnion(pRtree, pBbox, pCell); + } + + sqlite3_free(aaSorted); + return SQLITE_OK; +} +#endif + +#if VARIANT_GUTTMAN_SPLIT +/* +** Implementation of the regular R-tree SplitNode from Guttman[1984]. +*/ +static int splitNodeGuttman( + Rtree *pRtree, + RtreeCell *aCell, + int nCell, + RtreeNode *pLeft, + RtreeNode *pRight, + RtreeCell *pBboxLeft, + RtreeCell *pBboxRight +){ + int iLeftSeed = 0; + int iRightSeed = 1; + int *aiUsed; + int i; + + aiUsed = sqlite3_malloc(sizeof(int)*nCell); + memset(aiUsed, 0, sizeof(int)*nCell); + + PickSeeds(pRtree, aCell, nCell, &iLeftSeed, &iRightSeed); + + memcpy(pBboxLeft, &aCell[iLeftSeed], sizeof(RtreeCell)); + memcpy(pBboxRight, &aCell[iRightSeed], sizeof(RtreeCell)); + nodeInsertCell(pRtree, pLeft, &aCell[iLeftSeed]); + nodeInsertCell(pRtree, pRight, &aCell[iRightSeed]); + aiUsed[iLeftSeed] = 1; + aiUsed[iRightSeed] = 1; + + for(i=nCell-2; i>0; i--){ + RtreeCell *pNext; + pNext = PickNext(pRtree, aCell, nCell, pBboxLeft, pBboxRight, aiUsed); + float diff = + cellGrowth(pRtree, pBboxLeft, pNext) - + cellGrowth(pRtree, pBboxRight, pNext) + ; + if( (RTREE_MINCELLS(pRtree)-NCELL(pRight)==i) + || (diff>0.0 && (RTREE_MINCELLS(pRtree)-NCELL(pLeft)!=i)) + ){ + nodeInsertCell(pRtree, pRight, pNext); + cellUnion(pRtree, pBboxRight, pNext); + }else{ + nodeInsertCell(pRtree, pLeft, pNext); + cellUnion(pRtree, pBboxLeft, pNext); + } + } + + sqlite3_free(aiUsed); + return SQLITE_OK; +} +#endif + +static int updateMapping( + Rtree *pRtree, + i64 iRowid, + RtreeNode *pNode, + int iHeight +){ + int (*xSetMapping)(Rtree *, sqlite3_int64, sqlite3_int64); + xSetMapping = ((iHeight==0)?rowidWrite:parentWrite); + if( iHeight>0 ){ + RtreeNode *pChild = nodeHashLookup(pRtree, iRowid); + if( pChild ){ + nodeRelease(pRtree, pChild->pParent); + nodeReference(pNode); + pChild->pParent = pNode; + } + } + return xSetMapping(pRtree, iRowid, pNode->iNode); +} + +static int SplitNode( + Rtree *pRtree, + RtreeNode *pNode, + RtreeCell *pCell, + int iHeight +){ + int i; + int newCellIsRight = 0; + + int rc = SQLITE_OK; + int nCell = NCELL(pNode); + RtreeCell *aCell; + int *aiUsed; + + RtreeNode *pLeft = 0; + RtreeNode *pRight = 0; + + RtreeCell leftbbox; + RtreeCell rightbbox; + + /* Allocate an array and populate it with a copy of pCell and + ** all cells from node pLeft. Then zero the original node. + */ + aCell = sqlite3_malloc((sizeof(RtreeCell)+sizeof(int))*(nCell+1)); + if( !aCell ){ + rc = SQLITE_NOMEM; + goto splitnode_out; + } + aiUsed = (int *)&aCell[nCell+1]; + memset(aiUsed, 0, sizeof(int)*(nCell+1)); + for(i=0; i<nCell; i++){ + nodeGetCell(pRtree, pNode, i, &aCell[i]); + } + nodeZero(pRtree, pNode); + memcpy(&aCell[nCell], pCell, sizeof(RtreeCell)); + nCell++; + + if( pNode->iNode==1 ){ + pRight = nodeNew(pRtree, pNode, 1); + pLeft = nodeNew(pRtree, pNode, 1); + pRtree->iDepth++; + pNode->isDirty = 1; + writeInt16(pNode->zData, pRtree->iDepth); + }else{ + pLeft = pNode; + pRight = nodeNew(pRtree, pLeft->pParent, 1); + nodeReference(pLeft); + } + + if( !pLeft || !pRight ){ + rc = SQLITE_NOMEM; + goto splitnode_out; + } + + memset(pLeft->zData, 0, pRtree->iNodeSize); + memset(pRight->zData, 0, pRtree->iNodeSize); + + rc = AssignCells(pRtree, aCell, nCell, pLeft, pRight, &leftbbox, &rightbbox); + if( rc!=SQLITE_OK ){ + goto splitnode_out; + } + + /* Ensure both child nodes have node numbers assigned to them. */ + if( (0==pRight->iNode && SQLITE_OK!=(rc = nodeWrite(pRtree, pRight))) + || (0==pLeft->iNode && SQLITE_OK!=(rc = nodeWrite(pRtree, pLeft))) + ){ + goto splitnode_out; + } + + rightbbox.iRowid = pRight->iNode; + leftbbox.iRowid = pLeft->iNode; + + if( pNode->iNode==1 ){ + rc = rtreeInsertCell(pRtree, pLeft->pParent, &leftbbox, iHeight+1); + if( rc!=SQLITE_OK ){ + goto splitnode_out; + } + }else{ + RtreeNode *pParent = pLeft->pParent; + int iCell = nodeParentIndex(pRtree, pLeft); + nodeOverwriteCell(pRtree, pParent, &leftbbox, iCell); + AdjustTree(pRtree, pParent, &leftbbox); + } + if( (rc = rtreeInsertCell(pRtree, pRight->pParent, &rightbbox, iHeight+1)) ){ + goto splitnode_out; + } + + for(i=0; i<NCELL(pRight); i++){ + i64 iRowid = nodeGetRowid(pRtree, pRight, i); + rc = updateMapping(pRtree, iRowid, pRight, iHeight); + if( iRowid==pCell->iRowid ){ + newCellIsRight = 1; + } + if( rc!=SQLITE_OK ){ + goto splitnode_out; + } + } + if( pNode->iNode==1 ){ + for(i=0; i<NCELL(pLeft); i++){ + i64 iRowid = nodeGetRowid(pRtree, pLeft, i); + rc = updateMapping(pRtree, iRowid, pLeft, iHeight); + if( rc!=SQLITE_OK ){ + goto splitnode_out; + } + } + }else if( newCellIsRight==0 ){ + rc = updateMapping(pRtree, pCell->iRowid, pLeft, iHeight); + } + + if( rc==SQLITE_OK ){ + rc = nodeRelease(pRtree, pRight); + pRight = 0; + } + if( rc==SQLITE_OK ){ + rc = nodeRelease(pRtree, pLeft); + pLeft = 0; + } + +splitnode_out: + nodeRelease(pRtree, pRight); + nodeRelease(pRtree, pLeft); + sqlite3_free(aCell); + return rc; +} + +static int fixLeafParent(Rtree *pRtree, RtreeNode *pLeaf){ + int rc = SQLITE_OK; + if( pLeaf->iNode!=1 && pLeaf->pParent==0 ){ + sqlite3_bind_int64(pRtree->pReadParent, 1, pLeaf->iNode); + if( sqlite3_step(pRtree->pReadParent)==SQLITE_ROW ){ + i64 iNode = sqlite3_column_int64(pRtree->pReadParent, 0); + rc = nodeAcquire(pRtree, iNode, 0, &pLeaf->pParent); + }else{ + rc = SQLITE_ERROR; + } + sqlite3_reset(pRtree->pReadParent); + if( rc==SQLITE_OK ){ + rc = fixLeafParent(pRtree, pLeaf->pParent); + } + } + return rc; +} + +static int deleteCell(Rtree *, RtreeNode *, int, int); + +static int removeNode(Rtree *pRtree, RtreeNode *pNode, int iHeight){ + int rc; + RtreeNode *pParent; + int iCell; + + assert( pNode->nRef==1 ); + + /* Remove the entry in the parent cell. */ + iCell = nodeParentIndex(pRtree, pNode); + pParent = pNode->pParent; + pNode->pParent = 0; + if( SQLITE_OK!=(rc = deleteCell(pRtree, pParent, iCell, iHeight+1)) + || SQLITE_OK!=(rc = nodeRelease(pRtree, pParent)) + ){ + return rc; + } + + /* Remove the xxx_node entry. */ + sqlite3_bind_int64(pRtree->pDeleteNode, 1, pNode->iNode); + sqlite3_step(pRtree->pDeleteNode); + if( SQLITE_OK!=(rc = sqlite3_reset(pRtree->pDeleteNode)) ){ + return rc; + } + + /* Remove the xxx_parent entry. */ + sqlite3_bind_int64(pRtree->pDeleteParent, 1, pNode->iNode); + sqlite3_step(pRtree->pDeleteParent); + if( SQLITE_OK!=(rc = sqlite3_reset(pRtree->pDeleteParent)) ){ + return rc; + } + + /* Remove the node from the in-memory hash table and link it into + ** the Rtree.pDeleted list. Its contents will be re-inserted later on. + */ + nodeHashDelete(pRtree, pNode); + pNode->iNode = iHeight; + pNode->pNext = pRtree->pDeleted; + pNode->nRef++; + pRtree->pDeleted = pNode; + + return SQLITE_OK; +} + +static void fixBoundingBox(Rtree *pRtree, RtreeNode *pNode){ + RtreeNode *pParent = pNode->pParent; + if( pParent ){ + int ii; + int nCell = NCELL(pNode); + RtreeCell box; /* Bounding box for pNode */ + nodeGetCell(pRtree, pNode, 0, &box); + for(ii=1; ii<nCell; ii++){ + RtreeCell cell; + nodeGetCell(pRtree, pNode, ii, &cell); + cellUnion(pRtree, &box, &cell); + } + box.iRowid = pNode->iNode; + ii = nodeParentIndex(pRtree, pNode); + nodeOverwriteCell(pRtree, pParent, &box, ii); + fixBoundingBox(pRtree, pParent); + } +} + +/* +** Delete the cell at index iCell of node pNode. After removing the +** cell, adjust the r-tree data structure if required. +*/ +static int deleteCell(Rtree *pRtree, RtreeNode *pNode, int iCell, int iHeight){ + int rc; + + if( SQLITE_OK!=(rc = fixLeafParent(pRtree, pNode)) ){ + return rc; + } + + /* Remove the cell from the node. This call just moves bytes around + ** the in-memory node image, so it cannot fail. + */ + nodeDeleteCell(pRtree, pNode, iCell); + + /* If the node is not the tree root and now has less than the minimum + ** number of cells, remove it from the tree. Otherwise, update the + ** cell in the parent node so that it tightly contains the updated + ** node. + */ + if( pNode->iNode!=1 ){ + RtreeNode *pParent = pNode->pParent; + if( (pParent->iNode!=1 || NCELL(pParent)!=1) + && (NCELL(pNode)<RTREE_MINCELLS(pRtree)) + ){ + rc = removeNode(pRtree, pNode, iHeight); + }else{ + fixBoundingBox(pRtree, pNode); + } + } + + return rc; +} + +static int Reinsert( + Rtree *pRtree, + RtreeNode *pNode, + RtreeCell *pCell, + int iHeight +){ + int *aOrder; + int *aSpare; + RtreeCell *aCell; + float *aDistance; + int nCell; + float aCenterCoord[RTREE_MAX_DIMENSIONS]; + int iDim; + int ii; + int rc = SQLITE_OK; + + memset(aCenterCoord, 0, sizeof(float)*RTREE_MAX_DIMENSIONS); + + nCell = NCELL(pNode)+1; + + /* Allocate the buffers used by this operation. The allocation is + ** relinquished before this function returns. + */ + aCell = (RtreeCell *)sqlite3_malloc(nCell * ( + sizeof(RtreeCell) + /* aCell array */ + sizeof(int) + /* aOrder array */ + sizeof(int) + /* aSpare array */ + sizeof(float) /* aDistance array */ + )); + if( !aCell ){ + return SQLITE_NOMEM; + } + aOrder = (int *)&aCell[nCell]; + aSpare = (int *)&aOrder[nCell]; + aDistance = (float *)&aSpare[nCell]; + + for(ii=0; ii<nCell; ii++){ + if( ii==(nCell-1) ){ + memcpy(&aCell[ii], pCell, sizeof(RtreeCell)); + }else{ + nodeGetCell(pRtree, pNode, ii, &aCell[ii]); + } + aOrder[ii] = ii; + for(iDim=0; iDim<pRtree->nDim; iDim++){ + aCenterCoord[iDim] += DCOORD(aCell[ii].aCoord[iDim*2]); + aCenterCoord[iDim] += DCOORD(aCell[ii].aCoord[iDim*2+1]); + } + } + for(iDim=0; iDim<pRtree->nDim; iDim++){ + aCenterCoord[iDim] = aCenterCoord[iDim]/((float)nCell*2.0); + } + + for(ii=0; ii<nCell; ii++){ + aDistance[ii] = 0.0; + for(iDim=0; iDim<pRtree->nDim; iDim++){ + float coord = DCOORD(aCell[ii].aCoord[iDim*2+1]) - + DCOORD(aCell[ii].aCoord[iDim*2]); + aDistance[ii] += (coord-aCenterCoord[iDim])*(coord-aCenterCoord[iDim]); + } + } + + SortByDistance(aOrder, nCell, aDistance, aSpare); + nodeZero(pRtree, pNode); + + for(ii=0; rc==SQLITE_OK && ii<(nCell-(RTREE_MINCELLS(pRtree)+1)); ii++){ + RtreeCell *p = &aCell[aOrder[ii]]; + nodeInsertCell(pRtree, pNode, p); + if( p->iRowid==pCell->iRowid ){ + if( iHeight==0 ){ + rc = rowidWrite(pRtree, p->iRowid, pNode->iNode); + }else{ + rc = parentWrite(pRtree, p->iRowid, pNode->iNode); + } + } + } + if( rc==SQLITE_OK ){ + fixBoundingBox(pRtree, pNode); + } + for(; rc==SQLITE_OK && ii<nCell; ii++){ + /* Find a node to store this cell in. pNode->iNode currently contains + ** the height of the sub-tree headed by the cell. + */ + RtreeNode *pInsert; + RtreeCell *p = &aCell[aOrder[ii]]; + rc = ChooseLeaf(pRtree, p, iHeight, &pInsert); + if( rc==SQLITE_OK ){ + int rc2; + rc = rtreeInsertCell(pRtree, pInsert, p, iHeight); + rc2 = nodeRelease(pRtree, pInsert); + if( rc==SQLITE_OK ){ + rc = rc2; + } + } + } + + sqlite3_free(aCell); + return rc; +} + +/* +** Insert cell pCell into node pNode. Node pNode is the head of a +** subtree iHeight high (leaf nodes have iHeight==0). +*/ +static int rtreeInsertCell( + Rtree *pRtree, + RtreeNode *pNode, + RtreeCell *pCell, + int iHeight +){ + int rc = SQLITE_OK; + if( iHeight>0 ){ + RtreeNode *pChild = nodeHashLookup(pRtree, pCell->iRowid); + if( pChild ){ + nodeRelease(pRtree, pChild->pParent); + nodeReference(pNode); + pChild->pParent = pNode; + } + } + if( nodeInsertCell(pRtree, pNode, pCell) ){ +#if VARIANT_RSTARTREE_REINSERT + if( iHeight<=pRtree->iReinsertHeight || pNode->iNode==1){ + rc = SplitNode(pRtree, pNode, pCell, iHeight); + }else{ + pRtree->iReinsertHeight = iHeight; + rc = Reinsert(pRtree, pNode, pCell, iHeight); + } +#else + rc = SplitNode(pRtree, pNode, pCell, iHeight); +#endif + }else{ + AdjustTree(pRtree, pNode, pCell); + if( iHeight==0 ){ + rc = rowidWrite(pRtree, pCell->iRowid, pNode->iNode); + }else{ + rc = parentWrite(pRtree, pCell->iRowid, pNode->iNode); + } + } + return rc; +} + +static int reinsertNodeContent(Rtree *pRtree, RtreeNode *pNode){ + int ii; + int rc = SQLITE_OK; + int nCell = NCELL(pNode); + + for(ii=0; rc==SQLITE_OK && ii<nCell; ii++){ + RtreeNode *pInsert; + RtreeCell cell; + nodeGetCell(pRtree, pNode, ii, &cell); + + /* Find a node to store this cell in. pNode->iNode currently contains + ** the height of the sub-tree headed by the cell. + */ + rc = ChooseLeaf(pRtree, &cell, pNode->iNode, &pInsert); + if( rc==SQLITE_OK ){ + int rc2; + rc = rtreeInsertCell(pRtree, pInsert, &cell, pNode->iNode); + rc2 = nodeRelease(pRtree, pInsert); + if( rc==SQLITE_OK ){ + rc = rc2; + } + } + } + return rc; +} + +/* +** Select a currently unused rowid for a new r-tree record. +*/ +static int newRowid(Rtree *pRtree, i64 *piRowid){ + int rc; + sqlite3_bind_null(pRtree->pWriteRowid, 1); + sqlite3_bind_null(pRtree->pWriteRowid, 2); + sqlite3_step(pRtree->pWriteRowid); + rc = sqlite3_reset(pRtree->pWriteRowid); + *piRowid = sqlite3_last_insert_rowid(pRtree->db); + return rc; +} + +#ifndef NDEBUG +static int hashIsEmpty(Rtree *pRtree){ + int ii; + for(ii=0; ii<HASHSIZE; ii++){ + assert( !pRtree->aHash[ii] ); + } + return 1; +} +#endif + +/* +** The xUpdate method for rtree module virtual tables. +*/ +int rtreeUpdate( + sqlite3_vtab *pVtab, + int nData, + sqlite3_value **azData, + sqlite_int64 *pRowid +){ + Rtree *pRtree = (Rtree *)pVtab; + int rc = SQLITE_OK; + + rtreeReference(pRtree); + + assert(nData>=1); + assert(hashIsEmpty(pRtree)); + + /* If azData[0] is not an SQL NULL value, it is the rowid of a + ** record to delete from the r-tree table. The following block does + ** just that. + */ + if( sqlite3_value_type(azData[0])!=SQLITE_NULL ){ + i64 iDelete; /* The rowid to delete */ + RtreeNode *pLeaf; /* Leaf node containing record iDelete */ + int iCell; /* Index of iDelete cell in pLeaf */ + RtreeNode *pRoot; + + /* Obtain a reference to the root node to initialise Rtree.iDepth */ + rc = nodeAcquire(pRtree, 1, 0, &pRoot); + + /* Obtain a reference to the leaf node that contains the entry + ** about to be deleted. + */ + if( rc==SQLITE_OK ){ + iDelete = sqlite3_value_int64(azData[0]); + rc = findLeafNode(pRtree, iDelete, &pLeaf); + } + + /* Delete the cell in question from the leaf node. */ + if( rc==SQLITE_OK ){ + int rc2; + iCell = nodeRowidIndex(pRtree, pLeaf, iDelete); + rc = deleteCell(pRtree, pLeaf, iCell, 0); + rc2 = nodeRelease(pRtree, pLeaf); + if( rc==SQLITE_OK ){ + rc = rc2; + } + } + + /* Delete the corresponding entry in the <rtree>_rowid table. */ + if( rc==SQLITE_OK ){ + sqlite3_bind_int64(pRtree->pDeleteRowid, 1, iDelete); + sqlite3_step(pRtree->pDeleteRowid); + rc = sqlite3_reset(pRtree->pDeleteRowid); + } + + /* Check if the root node now has exactly one child. If so, remove + ** it, schedule the contents of the child for reinsertion and + ** reduce the tree height by one. + ** + ** This is equivalent to copying the contents of the child into + ** the root node (the operation that Gutman's paper says to perform + ** in this scenario). + */ + if( rc==SQLITE_OK && pRtree->iDepth>0 ){ + if( rc==SQLITE_OK && NCELL(pRoot)==1 ){ + RtreeNode *pChild; + i64 iChild = nodeGetRowid(pRtree, pRoot, 0); + rc = nodeAcquire(pRtree, iChild, pRoot, &pChild); + if( rc==SQLITE_OK ){ + rc = removeNode(pRtree, pChild, pRtree->iDepth-1); + } + if( rc==SQLITE_OK ){ + pRtree->iDepth--; + writeInt16(pRoot->zData, pRtree->iDepth); + pRoot->isDirty = 1; + } + } + } + + /* Re-insert the contents of any underfull nodes removed from the tree. */ + for(pLeaf=pRtree->pDeleted; pLeaf; pLeaf=pRtree->pDeleted){ + if( rc==SQLITE_OK ){ + rc = reinsertNodeContent(pRtree, pLeaf); + } + pRtree->pDeleted = pLeaf->pNext; + sqlite3_free(pLeaf); + } + + /* Release the reference to the root node. */ + if( rc==SQLITE_OK ){ + rc = nodeRelease(pRtree, pRoot); + }else{ + nodeRelease(pRtree, pRoot); + } + } + + /* If the azData[] array contains more than one element, elements + ** (azData[2]..azData[argc-1]) contain a new record to insert into + ** the r-tree structure. + */ + if( rc==SQLITE_OK && nData>1 ){ + /* Insert a new record into the r-tree */ + RtreeCell cell; + int ii; + RtreeNode *pLeaf; + + /* Populate the cell.aCoord[] array. The first coordinate is azData[3]. */ + assert( nData==(pRtree->nDim*2 + 3) ); + if( pRtree->eCoordType==RTREE_COORD_REAL32 ){ + for(ii=0; ii<(pRtree->nDim*2); ii+=2){ + cell.aCoord[ii].f = (float)sqlite3_value_double(azData[ii+3]); + cell.aCoord[ii+1].f = (float)sqlite3_value_double(azData[ii+4]); + if( cell.aCoord[ii].f>cell.aCoord[ii+1].f ){ + rc = SQLITE_CONSTRAINT; + goto constraint; + } + } + }else{ + for(ii=0; ii<(pRtree->nDim*2); ii+=2){ + cell.aCoord[ii].i = sqlite3_value_int(azData[ii+3]); + cell.aCoord[ii+1].i = sqlite3_value_int(azData[ii+4]); + if( cell.aCoord[ii].i>cell.aCoord[ii+1].i ){ + rc = SQLITE_CONSTRAINT; + goto constraint; + } + } + } + + /* Figure out the rowid of the new row. */ + if( sqlite3_value_type(azData[2])==SQLITE_NULL ){ + rc = newRowid(pRtree, &cell.iRowid); + }else{ + cell.iRowid = sqlite3_value_int64(azData[2]); + sqlite3_bind_int64(pRtree->pReadRowid, 1, cell.iRowid); + if( SQLITE_ROW==sqlite3_step(pRtree->pReadRowid) ){ + sqlite3_reset(pRtree->pReadRowid); + rc = SQLITE_CONSTRAINT; + goto constraint; + } + rc = sqlite3_reset(pRtree->pReadRowid); + } + + if( rc==SQLITE_OK ){ + rc = ChooseLeaf(pRtree, &cell, 0, &pLeaf); + } + if( rc==SQLITE_OK ){ + int rc2; + pRtree->iReinsertHeight = -1; + rc = rtreeInsertCell(pRtree, pLeaf, &cell, 0); + rc2 = nodeRelease(pRtree, pLeaf); + if( rc==SQLITE_OK ){ + rc = rc2; + } + } + } + +constraint: + rtreeRelease(pRtree); + return rc; +} + +/* +** The xRename method for rtree module virtual tables. +*/ +static int rtreeRename(sqlite3_vtab *pVtab, const char *zNewName){ + Rtree *pRtree = (Rtree *)pVtab; + int rc = SQLITE_NOMEM; + char *zSql = sqlite3_mprintf( + "ALTER TABLE %Q.'%q_node' RENAME TO \"%w_node\";" + "ALTER TABLE %Q.'%q_parent' RENAME TO \"%w_parent\";" + "ALTER TABLE %Q.'%q_rowid' RENAME TO \"%w_rowid\";" + , pRtree->zDb, pRtree->zName, zNewName + , pRtree->zDb, pRtree->zName, zNewName + , pRtree->zDb, pRtree->zName, zNewName + ); + if( zSql ){ + rc = sqlite3_exec(pRtree->db, zSql, 0, 0, 0); + sqlite3_free(zSql); + } + return rc; +} + +static sqlite3_module rtreeModule = { + 0, /* iVersion */ + rtreeCreate, /* xCreate - create a table */ + rtreeConnect, /* xConnect - connect to an existing table */ + rtreeBestIndex, /* xBestIndex - Determine search strategy */ + rtreeDisconnect, /* xDisconnect - Disconnect from a table */ + rtreeDestroy, /* xDestroy - Drop a table */ + rtreeOpen, /* xOpen - open a cursor */ + rtreeClose, /* xClose - close a cursor */ + rtreeFilter, /* xFilter - configure scan constraints */ + rtreeNext, /* xNext - advance a cursor */ + rtreeEof, /* xEof */ + rtreeColumn, /* xColumn - read data */ + rtreeRowid, /* xRowid - read data */ + rtreeUpdate, /* xUpdate - write data */ + 0, /* xBegin - begin transaction */ + 0, /* xSync - sync transaction */ + 0, /* xCommit - commit transaction */ + 0, /* xRollback - rollback transaction */ + 0, /* xFindFunction - function overloading */ + rtreeRename /* xRename - rename the table */ +}; + +static int rtreeSqlInit( + Rtree *pRtree, + sqlite3 *db, + const char *zDb, + const char *zPrefix, + int isCreate +){ + int rc = SQLITE_OK; + + #define N_STATEMENT 9 + static const char *azSql[N_STATEMENT] = { + /* Read and write the xxx_node table */ + "SELECT data FROM '%q'.'%q_node' WHERE nodeno = :1", + "INSERT OR REPLACE INTO '%q'.'%q_node' VALUES(:1, :2)", + "DELETE FROM '%q'.'%q_node' WHERE nodeno = :1", + + /* Read and write the xxx_rowid table */ + "SELECT nodeno FROM '%q'.'%q_rowid' WHERE rowid = :1", + "INSERT OR REPLACE INTO '%q'.'%q_rowid' VALUES(:1, :2)", + "DELETE FROM '%q'.'%q_rowid' WHERE rowid = :1", + + /* Read and write the xxx_parent table */ + "SELECT parentnode FROM '%q'.'%q_parent' WHERE nodeno = :1", + "INSERT OR REPLACE INTO '%q'.'%q_parent' VALUES(:1, :2)", + "DELETE FROM '%q'.'%q_parent' WHERE nodeno = :1" + }; + sqlite3_stmt **appStmt[N_STATEMENT]; + int i; + + pRtree->db = db; + + if( isCreate ){ + char *zCreate = sqlite3_mprintf( +"CREATE TABLE \"%w\".\"%w_node\"(nodeno INTEGER PRIMARY KEY, data BLOB);" +"CREATE TABLE \"%w\".\"%w_rowid\"(rowid INTEGER PRIMARY KEY, nodeno INTEGER);" +"CREATE TABLE \"%w\".\"%w_parent\"(nodeno INTEGER PRIMARY KEY, parentnode INTEGER);" +"INSERT INTO '%q'.'%q_node' VALUES(1, zeroblob(%d))", + zDb, zPrefix, zDb, zPrefix, zDb, zPrefix, zDb, zPrefix, pRtree->iNodeSize + ); + if( !zCreate ){ + return SQLITE_NOMEM; + } + rc = sqlite3_exec(db, zCreate, 0, 0, 0); + sqlite3_free(zCreate); + if( rc!=SQLITE_OK ){ + return rc; + } + } + + appStmt[0] = &pRtree->pReadNode; + appStmt[1] = &pRtree->pWriteNode; + appStmt[2] = &pRtree->pDeleteNode; + appStmt[3] = &pRtree->pReadRowid; + appStmt[4] = &pRtree->pWriteRowid; + appStmt[5] = &pRtree->pDeleteRowid; + appStmt[6] = &pRtree->pReadParent; + appStmt[7] = &pRtree->pWriteParent; + appStmt[8] = &pRtree->pDeleteParent; + + for(i=0; i<N_STATEMENT && rc==SQLITE_OK; i++){ + char *zSql = sqlite3_mprintf(azSql[i], zDb, zPrefix); + if( zSql ){ + rc = sqlite3_prepare_v2(db, zSql, -1, appStmt[i], 0); + }else{ + rc = SQLITE_NOMEM; + } + sqlite3_free(zSql); + } + + return rc; +} + +/* +** This routine queries database handle db for the page-size used by +** database zDb. If successful, the page-size in bytes is written to +** *piPageSize and SQLITE_OK returned. Otherwise, and an SQLite error +** code is returned. +*/ +static int getPageSize(sqlite3 *db, const char *zDb, int *piPageSize){ + int rc = SQLITE_NOMEM; + char *zSql; + sqlite3_stmt *pStmt = 0; + + zSql = sqlite3_mprintf("PRAGMA %Q.page_size", zDb); + if( !zSql ){ + return SQLITE_NOMEM; + } + + rc = sqlite3_prepare_v2(db, zSql, -1, &pStmt, 0); + sqlite3_free(zSql); + if( rc!=SQLITE_OK ){ + return rc; + } + + if( SQLITE_ROW==sqlite3_step(pStmt) ){ + *piPageSize = sqlite3_column_int(pStmt, 0); + } + return sqlite3_finalize(pStmt); +} + +/* +** This function is the implementation of both the xConnect and xCreate +** methods of the r-tree virtual table. +** +** argv[0] -> module name +** argv[1] -> database name +** argv[2] -> table name +** argv[...] -> column names... +*/ +static int rtreeInit( + sqlite3 *db, /* Database connection */ + void *pAux, /* Pointer to head of rtree list */ + int argc, const char *const*argv, /* Parameters to CREATE TABLE statement */ + sqlite3_vtab **ppVtab, /* OUT: New virtual table */ + char **pzErr, /* OUT: Error message, if any */ + int isCreate, /* True for xCreate, false for xConnect */ + int eCoordType /* One of the RTREE_COORD_* constants */ +){ + int rc = SQLITE_OK; + int iPageSize = 0; + Rtree *pRtree; + int nDb; /* Length of string argv[1] */ + int nName; /* Length of string argv[2] */ + + const char *aErrMsg[] = { + 0, /* 0 */ + "Wrong number of columns for an rtree table", /* 1 */ + "Too few columns for an rtree table", /* 2 */ + "Too many columns for an rtree table" /* 3 */ + }; + + int iErr = (argc<6) ? 2 : argc>(RTREE_MAX_DIMENSIONS*2+4) ? 3 : argc%2; + if( aErrMsg[iErr] ){ + *pzErr = sqlite3_mprintf("%s", aErrMsg[iErr]); + return SQLITE_ERROR; + } + + rc = getPageSize(db, argv[1], &iPageSize); + if( rc!=SQLITE_OK ){ + return rc; + } + + /* Allocate the sqlite3_vtab structure */ + nDb = strlen(argv[1]); + nName = strlen(argv[2]); + pRtree = (Rtree *)sqlite3_malloc(sizeof(Rtree)+nDb+nName+2); + if( !pRtree ){ + return SQLITE_NOMEM; + } + memset(pRtree, 0, sizeof(Rtree)+nDb+nName+2); + pRtree->nBusy = 1; + pRtree->base.pModule = &rtreeModule; + pRtree->zDb = (char *)&pRtree[1]; + pRtree->zName = &pRtree->zDb[nDb+1]; + pRtree->nDim = (argc-4)/2; + pRtree->nBytesPerCell = 8 + pRtree->nDim*4*2; + pRtree->eCoordType = eCoordType; + memcpy(pRtree->zDb, argv[1], nDb); + memcpy(pRtree->zName, argv[2], nName); + + /* Figure out the node size to use. By default, use 64 bytes less than + ** the database page-size. This ensures that each node is stored on + ** a single database page. + ** + ** If the databasd page-size is so large that more than RTREE_MAXCELLS + ** entries would fit in a single node, use a smaller node-size. + */ + pRtree->iNodeSize = iPageSize-64; + if( (4+pRtree->nBytesPerCell*RTREE_MAXCELLS)<pRtree->iNodeSize ){ + pRtree->iNodeSize = 4+pRtree->nBytesPerCell*RTREE_MAXCELLS; + } + + /* Create/Connect to the underlying relational database schema. If + ** that is successful, call sqlite3_declare_vtab() to configure + ** the r-tree table schema. + */ + if( (rc = rtreeSqlInit(pRtree, db, argv[1], argv[2], isCreate)) ){ + *pzErr = sqlite3_mprintf("%s", sqlite3_errmsg(db)); + }else{ + char *zSql = sqlite3_mprintf("CREATE TABLE x(%s", argv[3]); + char *zTmp; + int ii; + for(ii=4; zSql && ii<argc; ii++){ + zTmp = zSql; + zSql = sqlite3_mprintf("%s, %s", zTmp, argv[ii]); + sqlite3_free(zTmp); + } + if( zSql ){ + zTmp = zSql; + zSql = sqlite3_mprintf("%s);", zTmp); + sqlite3_free(zTmp); + } + if( !zSql || sqlite3_declare_vtab(db, zSql) ){ + rc = SQLITE_NOMEM; + } + sqlite3_free(zSql); + } + + if( rc==SQLITE_OK ){ + *ppVtab = (sqlite3_vtab *)pRtree; + }else{ + rtreeRelease(pRtree); + } + return rc; +} + + +/* +** Implementation of a scalar function that decodes r-tree nodes to +** human readable strings. This can be used for debugging and analysis. +** +** The scalar function takes two arguments, a blob of data containing +** an r-tree node, and the number of dimensions the r-tree indexes. +** For a two-dimensional r-tree structure called "rt", to deserialize +** all nodes, a statement like: +** +** SELECT rtreenode(2, data) FROM rt_node; +** +** The human readable string takes the form of a Tcl list with one +** entry for each cell in the r-tree node. Each entry is itself a +** list, containing the 8-byte rowid/pageno followed by the +** <num-dimension>*2 coordinates. +*/ +static void rtreenode(sqlite3_context *ctx, int nArg, sqlite3_value **apArg){ + char *zText = 0; + RtreeNode node; + Rtree tree; + int ii; + + memset(&node, 0, sizeof(RtreeNode)); + memset(&tree, 0, sizeof(Rtree)); + tree.nDim = sqlite3_value_int(apArg[0]); + tree.nBytesPerCell = 8 + 8 * tree.nDim; + node.zData = (u8 *)sqlite3_value_blob(apArg[1]); + + for(ii=0; ii<NCELL(&node); ii++){ + char zCell[512]; + int nCell = 0; + RtreeCell cell; + int jj; + + nodeGetCell(&tree, &node, ii, &cell); + sqlite3_snprintf(512-nCell,&zCell[nCell],"%d", cell.iRowid); + nCell = strlen(zCell); + for(jj=0; jj<tree.nDim*2; jj++){ + sqlite3_snprintf(512-nCell,&zCell[nCell]," %f",(double)cell.aCoord[jj].f); + nCell = strlen(zCell); + } + + if( zText ){ + char *zTextNew = sqlite3_mprintf("%s {%s}", zText, zCell); + sqlite3_free(zText); + zText = zTextNew; + }else{ + zText = sqlite3_mprintf("{%s}", zCell); + } + } + + sqlite3_result_text(ctx, zText, -1, sqlite3_free); +} + +static void rtreedepth(sqlite3_context *ctx, int nArg, sqlite3_value **apArg){ + if( sqlite3_value_type(apArg[0])!=SQLITE_BLOB + || sqlite3_value_bytes(apArg[0])<2 + ){ + sqlite3_result_error(ctx, "Invalid argument to rtreedepth()", -1); + }else{ + u8 *zBlob = (u8 *)sqlite3_value_blob(apArg[0]); + sqlite3_result_int(ctx, readInt16(zBlob)); + } +} + +/* +** Register the r-tree module with database handle db. This creates the +** virtual table module "rtree" and the debugging/analysis scalar +** function "rtreenode". +*/ +SQLITE_PRIVATE int sqlite3RtreeInit(sqlite3 *db){ + int rc = SQLITE_OK; + + if( rc==SQLITE_OK ){ + int utf8 = SQLITE_UTF8; + rc = sqlite3_create_function(db, "rtreenode", 2, utf8, 0, rtreenode, 0, 0); + } + if( rc==SQLITE_OK ){ + int utf8 = SQLITE_UTF8; + rc = sqlite3_create_function(db, "rtreedepth", 1, utf8, 0,rtreedepth, 0, 0); + } + if( rc==SQLITE_OK ){ + void *c = (void *)RTREE_COORD_REAL32; + rc = sqlite3_create_module_v2(db, "rtree", &rtreeModule, c, 0); + } + if( rc==SQLITE_OK ){ + void *c = (void *)RTREE_COORD_INT32; + rc = sqlite3_create_module_v2(db, "rtree_i32", &rtreeModule, c, 0); + } + + return rc; +} + +#if !SQLITE_CORE +SQLITE_API int sqlite3_extension_init( + sqlite3 *db, + char **pzErrMsg, + const sqlite3_api_routines *pApi +){ + SQLITE_EXTENSION_INIT2(pApi) + return sqlite3RtreeInit(db); +} +#endif + +#endif + +/************** End of rtree.c ***********************************************/ +/************** Begin file icu.c *********************************************/ +/* +** 2007 May 6 +** +** The author disclaims copyright to this source code. In place of +** a legal notice, here is a blessing: +** +** May you do good and not evil. +** May you find forgiveness for yourself and forgive others. +** May you share freely, never taking more than you give. +** +************************************************************************* +** $Id$ +** +** This file implements an integration between the ICU library +** ("International Components for Unicode", an open-source library +** for handling unicode data) and SQLite. The integration uses +** ICU to provide the following to SQLite: +** +** * An implementation of the SQL regexp() function (and hence REGEXP +** operator) using the ICU uregex_XX() APIs. +** +** * Implementations of the SQL scalar upper() and lower() functions +** for case mapping. +** +** * Integration of ICU and SQLite collation seqences. +** +** * An implementation of the LIKE operator that uses ICU to +** provide case-independent matching. +*/ + +#if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_ICU) + +/* Include ICU headers */ +#include <unicode/utypes.h> +#include <unicode/uregex.h> +#include <unicode/ustring.h> +#include <unicode/ucol.h> + + +#ifndef SQLITE_CORE + #include "sqlite3ext.h" + SQLITE_EXTENSION_INIT1 +#else + #include "sqlite3.h" +#endif + +/* +** Maximum length (in bytes) of the pattern in a LIKE or GLOB +** operator. +*/ +#ifndef SQLITE_MAX_LIKE_PATTERN_LENGTH +# define SQLITE_MAX_LIKE_PATTERN_LENGTH 50000 +#endif + +/* +** Version of sqlite3_free() that is always a function, never a macro. +*/ +static void xFree(void *p){ + sqlite3_free(p); +} + +/* +** Compare two UTF-8 strings for equality where the first string is +** a "LIKE" expression. Return true (1) if they are the same and +** false (0) if they are different. +*/ +static int icuLikeCompare( + const uint8_t *zPattern, /* LIKE pattern */ + const uint8_t *zString, /* The UTF-8 string to compare against */ + const UChar32 uEsc /* The escape character */ +){ + static const int MATCH_ONE = (UChar32)'_'; + static const int MATCH_ALL = (UChar32)'%'; + + int iPattern = 0; /* Current byte index in zPattern */ + int iString = 0; /* Current byte index in zString */ + + int prevEscape = 0; /* True if the previous character was uEsc */ + + while( zPattern[iPattern]!=0 ){ + + /* Read (and consume) the next character from the input pattern. */ + UChar32 uPattern; + U8_NEXT_UNSAFE(zPattern, iPattern, uPattern); + assert(uPattern!=0); + + /* There are now 4 possibilities: + ** + ** 1. uPattern is an unescaped match-all character "%", + ** 2. uPattern is an unescaped match-one character "_", + ** 3. uPattern is an unescaped escape character, or + ** 4. uPattern is to be handled as an ordinary character + */ + if( !prevEscape && uPattern==MATCH_ALL ){ + /* Case 1. */ + uint8_t c; + + /* Skip any MATCH_ALL or MATCH_ONE characters that follow a + ** MATCH_ALL. For each MATCH_ONE, skip one character in the + ** test string. + */ + while( (c=zPattern[iPattern]) == MATCH_ALL || c == MATCH_ONE ){ + if( c==MATCH_ONE ){ + if( zString[iString]==0 ) return 0; + U8_FWD_1_UNSAFE(zString, iString); + } + iPattern++; + } + + if( zPattern[iPattern]==0 ) return 1; + + while( zString[iString] ){ + if( icuLikeCompare(&zPattern[iPattern], &zString[iString], uEsc) ){ + return 1; + } + U8_FWD_1_UNSAFE(zString, iString); + } + return 0; + + }else if( !prevEscape && uPattern==MATCH_ONE ){ + /* Case 2. */ + if( zString[iString]==0 ) return 0; + U8_FWD_1_UNSAFE(zString, iString); + + }else if( !prevEscape && uPattern==uEsc){ + /* Case 3. */ + prevEscape = 1; + + }else{ + /* Case 4. */ + UChar32 uString; + U8_NEXT_UNSAFE(zString, iString, uString); + uString = u_foldCase(uString, U_FOLD_CASE_DEFAULT); + uPattern = u_foldCase(uPattern, U_FOLD_CASE_DEFAULT); + if( uString!=uPattern ){ + return 0; + } + prevEscape = 0; + } + } + + return zString[iString]==0; +} + +/* +** Implementation of the like() SQL function. This function implements +** the build-in LIKE operator. The first argument to the function is the +** pattern and the second argument is the string. So, the SQL statements: +** +** A LIKE B +** +** is implemented as like(B, A). If there is an escape character E, +** +** A LIKE B ESCAPE E +** +** is mapped to like(B, A, E). +*/ +static void icuLikeFunc( + sqlite3_context *context, + int argc, + sqlite3_value **argv +){ + const unsigned char *zA = sqlite3_value_text(argv[0]); + const unsigned char *zB = sqlite3_value_text(argv[1]); + UChar32 uEsc = 0; + + /* Limit the length of the LIKE or GLOB pattern to avoid problems + ** of deep recursion and N*N behavior in patternCompare(). + */ + if( sqlite3_value_bytes(argv[0])>SQLITE_MAX_LIKE_PATTERN_LENGTH ){ + sqlite3_result_error(context, "LIKE or GLOB pattern too complex", -1); + return; + } + + + if( argc==3 ){ + /* The escape character string must consist of a single UTF-8 character. + ** Otherwise, return an error. + */ + int nE= sqlite3_value_bytes(argv[2]); + const unsigned char *zE = sqlite3_value_text(argv[2]); + int i = 0; + if( zE==0 ) return; + U8_NEXT(zE, i, nE, uEsc); + if( i!=nE){ + sqlite3_result_error(context, + "ESCAPE expression must be a single character", -1); + return; + } + } + + if( zA && zB ){ + sqlite3_result_int(context, icuLikeCompare(zA, zB, uEsc)); + } +} + +/* +** This function is called when an ICU function called from within +** the implementation of an SQL scalar function returns an error. +** +** The scalar function context passed as the first argument is +** loaded with an error message based on the following two args. +*/ +static void icuFunctionError( + sqlite3_context *pCtx, /* SQLite scalar function context */ + const char *zName, /* Name of ICU function that failed */ + UErrorCode e /* Error code returned by ICU function */ +){ + char zBuf[128]; + sqlite3_snprintf(128, zBuf, "ICU error: %s(): %s", zName, u_errorName(e)); + zBuf[127] = '\0'; + sqlite3_result_error(pCtx, zBuf, -1); +} + +/* +** Function to delete compiled regexp objects. Registered as +** a destructor function with sqlite3_set_auxdata(). +*/ +static void icuRegexpDelete(void *p){ + URegularExpression *pExpr = (URegularExpression *)p; + uregex_close(pExpr); +} + +/* +** Implementation of SQLite REGEXP operator. This scalar function takes +** two arguments. The first is a regular expression pattern to compile +** the second is a string to match against that pattern. If either +** argument is an SQL NULL, then NULL Is returned. Otherwise, the result +** is 1 if the string matches the pattern, or 0 otherwise. +** +** SQLite maps the regexp() function to the regexp() operator such +** that the following two are equivalent: +** +** zString REGEXP zPattern +** regexp(zPattern, zString) +** +** Uses the following ICU regexp APIs: +** +** uregex_open() +** uregex_matches() +** uregex_close() +*/ +static void icuRegexpFunc(sqlite3_context *p, int nArg, sqlite3_value **apArg){ + UErrorCode status = U_ZERO_ERROR; + URegularExpression *pExpr; + UBool res; + const UChar *zString = sqlite3_value_text16(apArg[1]); + + /* If the left hand side of the regexp operator is NULL, + ** then the result is also NULL. + */ + if( !zString ){ + return; + } + + pExpr = sqlite3_get_auxdata(p, 0); + if( !pExpr ){ + const UChar *zPattern = sqlite3_value_text16(apArg[0]); + if( !zPattern ){ + return; + } + pExpr = uregex_open(zPattern, -1, 0, 0, &status); + + if( U_SUCCESS(status) ){ + sqlite3_set_auxdata(p, 0, pExpr, icuRegexpDelete); + }else{ + assert(!pExpr); + icuFunctionError(p, "uregex_open", status); + return; + } + } + + /* Configure the text that the regular expression operates on. */ + uregex_setText(pExpr, zString, -1, &status); + if( !U_SUCCESS(status) ){ + icuFunctionError(p, "uregex_setText", status); + return; + } + + /* Attempt the match */ + res = uregex_matches(pExpr, 0, &status); + if( !U_SUCCESS(status) ){ + icuFunctionError(p, "uregex_matches", status); + return; + } + + /* Set the text that the regular expression operates on to a NULL + ** pointer. This is not really necessary, but it is tidier than + ** leaving the regular expression object configured with an invalid + ** pointer after this function returns. + */ + uregex_setText(pExpr, 0, 0, &status); + + /* Return 1 or 0. */ + sqlite3_result_int(p, res ? 1 : 0); +} + +/* +** Implementations of scalar functions for case mapping - upper() and +** lower(). Function upper() converts its input to upper-case (ABC). +** Function lower() converts to lower-case (abc). +** +** ICU provides two types of case mapping, "general" case mapping and +** "language specific". Refer to ICU documentation for the differences +** between the two. +** +** To utilise "general" case mapping, the upper() or lower() scalar +** functions are invoked with one argument: +** +** upper('ABC') -> 'abc' +** lower('abc') -> 'ABC' +** +** To access ICU "language specific" case mapping, upper() or lower() +** should be invoked with two arguments. The second argument is the name +** of the locale to use. Passing an empty string ("") or SQL NULL value +** as the second argument is the same as invoking the 1 argument version +** of upper() or lower(). +** +** lower('I', 'en_us') -> 'i' +** lower('I', 'tr_tr') -> 'ı' (small dotless i) +** +** http://www.icu-project.org/userguide/posix.html#case_mappings +*/ +static void icuCaseFunc16(sqlite3_context *p, int nArg, sqlite3_value **apArg){ + const UChar *zInput; + UChar *zOutput; + int nInput; + int nOutput; + + UErrorCode status = U_ZERO_ERROR; + const char *zLocale = 0; + + assert(nArg==1 || nArg==2); + if( nArg==2 ){ + zLocale = (const char *)sqlite3_value_text(apArg[1]); + } + + zInput = sqlite3_value_text16(apArg[0]); + if( !zInput ){ + return; + } + nInput = sqlite3_value_bytes16(apArg[0]); + + nOutput = nInput * 2 + 2; + zOutput = sqlite3_malloc(nOutput); + if( !zOutput ){ + return; + } + + if( sqlite3_user_data(p) ){ + u_strToUpper(zOutput, nOutput/2, zInput, nInput/2, zLocale, &status); + }else{ + u_strToLower(zOutput, nOutput/2, zInput, nInput/2, zLocale, &status); + } + + if( !U_SUCCESS(status) ){ + icuFunctionError(p, "u_strToLower()/u_strToUpper", status); + return; + } + + sqlite3_result_text16(p, zOutput, -1, xFree); +} + +/* +** Collation sequence destructor function. The pCtx argument points to +** a UCollator structure previously allocated using ucol_open(). +*/ +static void icuCollationDel(void *pCtx){ + UCollator *p = (UCollator *)pCtx; + ucol_close(p); +} + +/* +** Collation sequence comparison function. The pCtx argument points to +** a UCollator structure previously allocated using ucol_open(). +*/ +static int icuCollationColl( + void *pCtx, + int nLeft, + const void *zLeft, + int nRight, + const void *zRight +){ + UCollationResult res; + UCollator *p = (UCollator *)pCtx; + res = ucol_strcoll(p, (UChar *)zLeft, nLeft/2, (UChar *)zRight, nRight/2); + switch( res ){ + case UCOL_LESS: return -1; + case UCOL_GREATER: return +1; + case UCOL_EQUAL: return 0; + } + assert(!"Unexpected return value from ucol_strcoll()"); + return 0; +} + +/* +** Implementation of the scalar function icu_load_collation(). +** +** This scalar function is used to add ICU collation based collation +** types to an SQLite database connection. It is intended to be called +** as follows: +** +** SELECT icu_load_collation(<locale>, <collation-name>); +** +** Where <locale> is a string containing an ICU locale identifier (i.e. +** "en_AU", "tr_TR" etc.) and <collation-name> is the name of the +** collation sequence to create. +*/ +static void icuLoadCollation( + sqlite3_context *p, + int nArg, + sqlite3_value **apArg +){ + sqlite3 *db = (sqlite3 *)sqlite3_user_data(p); + UErrorCode status = U_ZERO_ERROR; + const char *zLocale; /* Locale identifier - (eg. "jp_JP") */ + const char *zName; /* SQL Collation sequence name (eg. "japanese") */ + UCollator *pUCollator; /* ICU library collation object */ + int rc; /* Return code from sqlite3_create_collation_x() */ + + assert(nArg==2); + zLocale = (const char *)sqlite3_value_text(apArg[0]); + zName = (const char *)sqlite3_value_text(apArg[1]); + + if( !zLocale || !zName ){ + return; + } + + pUCollator = ucol_open(zLocale, &status); + if( !U_SUCCESS(status) ){ + icuFunctionError(p, "ucol_open", status); + return; + } + assert(p); + + rc = sqlite3_create_collation_v2(db, zName, SQLITE_UTF16, (void *)pUCollator, + icuCollationColl, icuCollationDel + ); + if( rc!=SQLITE_OK ){ + ucol_close(pUCollator); + sqlite3_result_error(p, "Error registering collation function", -1); + } +} + +/* +** Register the ICU extension functions with database db. +*/ +SQLITE_PRIVATE int sqlite3IcuInit(sqlite3 *db){ + struct IcuScalar { + const char *zName; /* Function name */ + int nArg; /* Number of arguments */ + int enc; /* Optimal text encoding */ + void *pContext; /* sqlite3_user_data() context */ + void (*xFunc)(sqlite3_context*,int,sqlite3_value**); + } scalars[] = { + {"regexp",-1, SQLITE_ANY, 0, icuRegexpFunc}, + + {"lower", 1, SQLITE_UTF16, 0, icuCaseFunc16}, + {"lower", 2, SQLITE_UTF16, 0, icuCaseFunc16}, + {"upper", 1, SQLITE_UTF16, (void*)1, icuCaseFunc16}, + {"upper", 2, SQLITE_UTF16, (void*)1, icuCaseFunc16}, + + {"lower", 1, SQLITE_UTF8, 0, icuCaseFunc16}, + {"lower", 2, SQLITE_UTF8, 0, icuCaseFunc16}, + {"upper", 1, SQLITE_UTF8, (void*)1, icuCaseFunc16}, + {"upper", 2, SQLITE_UTF8, (void*)1, icuCaseFunc16}, + + {"like", 2, SQLITE_UTF8, 0, icuLikeFunc}, + {"like", 3, SQLITE_UTF8, 0, icuLikeFunc}, + + {"icu_load_collation", 2, SQLITE_UTF8, (void*)db, icuLoadCollation}, + }; + + int rc = SQLITE_OK; + int i; + + for(i=0; rc==SQLITE_OK && i<(sizeof(scalars)/sizeof(struct IcuScalar)); i++){ + struct IcuScalar *p = &scalars[i]; + rc = sqlite3_create_function( + db, p->zName, p->nArg, p->enc, p->pContext, p->xFunc, 0, 0 + ); + } + + return rc; +} + +#if !SQLITE_CORE +SQLITE_API int sqlite3_extension_init( + sqlite3 *db, + char **pzErrMsg, + const sqlite3_api_routines *pApi +){ + SQLITE_EXTENSION_INIT2(pApi) + return sqlite3IcuInit(db); +} +#endif + +#endif + +/************** End of icu.c *************************************************/ diff --git a/ext/sqlite3/libsqlite/sqlite3.h b/ext/sqlite3/libsqlite/sqlite3.h index 7498b24d64..f43b7ac8b9 100644 --- a/ext/sqlite3/libsqlite/sqlite3.h +++ b/ext/sqlite3/libsqlite/sqlite3.h @@ -17,7 +17,7 @@ ** ** Some of the definitions that are in this file are marked as ** "experimental". Experimental interfaces are normally new -** features recently added to SQLite. We do not anticipate changes +** features recently added to SQLite. We do not anticipate changes ** to experimental interfaces but reserve to make minor changes if ** experience from use "in the wild" suggest such changes are prudent. ** @@ -52,8 +52,7 @@ extern "C" { #endif /* -** Make sure these symbols where not defined by some previous header -** file. +** Ensure these symbols were not defined by some previous header file. */ #ifdef SQLITE_VERSION # undef SQLITE_VERSION @@ -63,7 +62,7 @@ extern "C" { #endif /* -** CAPI3REF: Compile-Time Library Version Numbers {F10010} +** CAPI3REF: Compile-Time Library Version Numbers {H10010} <S60100> ** ** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in ** the sqlite3.h file specify the version of SQLite with which @@ -72,39 +71,38 @@ extern "C" { ** The "version" of SQLite is a string of the form "X.Y.Z". ** The phrase "alpha" or "beta" might be appended after the Z. ** The X value is major version number always 3 in SQLite3. -** The X value only changes when backwards compatibility is -** broken and we intend to never break -** backwards compatibility. The Y value is the minor version -** number and only changes when +** The X value only changes when backwards compatibility is +** broken and we intend to never break backwards compatibility. +** The Y value is the minor version number and only changes when ** there are major feature enhancements that are forwards compatible -** but not backwards compatible. The Z value is release number -** and is incremented with -** each release but resets back to 0 when Y is incremented. +** but not backwards compatible. +** The Z value is the release number and is incremented with +** each release but resets back to 0 whenever Y is incremented. ** ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()]. ** ** INVARIANTS: ** -** {F10011} The SQLITE_VERSION #define in the sqlite3.h header file -** evaluates to a string literal that is the SQLite version +** {H10011} The SQLITE_VERSION #define in the sqlite3.h header file shall +** evaluate to a string literal that is the SQLite version ** with which the header file is associated. ** -** {F10014} The SQLITE_VERSION_NUMBER #define resolves to an integer -** with the value (X*1000000 + Y*1000 + Z) where X, Y, and -** Z are the major version, minor version, and release number. +** {H10014} The SQLITE_VERSION_NUMBER #define shall resolve to an integer +** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z +** are the major version, minor version, and release number. */ -#define SQLITE_VERSION "3.5.9" -#define SQLITE_VERSION_NUMBER 3005009 +#define SQLITE_VERSION "3.6.1" +#define SQLITE_VERSION_NUMBER 3006001 /* -** CAPI3REF: Run-Time Library Version Numbers {F10020} +** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100> ** KEYWORDS: sqlite3_version ** ** These features provide the same information as the [SQLITE_VERSION] ** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated ** with the library instead of the header file. Cautious programmers might -** include a check in their application to verify that -** sqlite3_libversion_number() always returns the value +** include a check in their application to verify that +** sqlite3_libversion_number() always returns the value ** [SQLITE_VERSION_NUMBER]. ** ** The sqlite3_libversion() function returns the same information as is @@ -114,13 +112,13 @@ extern "C" { ** ** INVARIANTS: ** -** {F10021} The [sqlite3_libversion_number()] interface returns an integer -** equal to [SQLITE_VERSION_NUMBER]. +** {H10021} The [sqlite3_libversion_number()] interface shall return +** an integer equal to [SQLITE_VERSION_NUMBER]. ** -** {F10022} The [sqlite3_version] string constant contains the text of the -** [SQLITE_VERSION] string. +** {H10022} The [sqlite3_version] string constant shall contain +** the text of the [SQLITE_VERSION] string. ** -** {F10023} The [sqlite3_libversion()] function returns +** {H10023} The [sqlite3_libversion()] function shall return ** a pointer to the [sqlite3_version] string constant. */ SQLITE_EXTERN const char sqlite3_version[]; @@ -128,64 +126,80 @@ const char *sqlite3_libversion(void); int sqlite3_libversion_number(void); /* -** CAPI3REF: Test To See If The Library Is Threadsafe {F10100} +** CAPI3REF: Test To See If The Library Is Threadsafe {H10100} <S60100> ** ** SQLite can be compiled with or without mutexes. When -** the SQLITE_THREADSAFE C preprocessor macro is true, mutexes +** the [SQLITE_THREADSAFE] C preprocessor macro is true, mutexes ** are enabled and SQLite is threadsafe. When that macro is false, ** the mutexes are omitted. Without the mutexes, it is not safe -** to use SQLite from more than one thread. +** to use SQLite concurrently from more than one thread. ** -** There is a measurable performance penalty for enabling mutexes. +** Enabling mutexes incurs a measurable performance penalty. ** So if speed is of utmost importance, it makes sense to disable ** the mutexes. But for maximum safety, mutexes should be enabled. ** The default behavior is for mutexes to be enabled. ** ** This interface can be used by a program to make sure that the ** version of SQLite that it is linking against was compiled with -** the desired setting of the SQLITE_THREADSAFE macro. +** the desired setting of the [SQLITE_THREADSAFE] macro. +** +** This interface only reports on the compile-time mutex setting +** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with +** SQLITE_THREADSAFE=1 then mutexes are enabled by default but +** can be fully or partially disabled using a call to [sqlite3_config()] +** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD], +** or [SQLITE_CONFIG_MUTEX]. The return value of this function shows +** only the default compile-time setting, not any run-time changes +** to that setting. ** ** INVARIANTS: ** -** {F10101} The [sqlite3_threadsafe()] function returns nonzero if -** SQLite was compiled with its mutexes enabled or zero -** if SQLite was compiled with mutexes disabled. +** {H10101} The [sqlite3_threadsafe()] function shall return nonzero if +** SQLite was compiled with the its mutexes enabled by default +** or zero if SQLite was compiled such that mutexes are +** permanently disabled. +** +** {H10102} The value returned by the [sqlite3_threadsafe()] function +** shall not change when mutex setting are modified at +** runtime using the [sqlite3_config()] interface and +** especially the [SQLITE_CONFIG_SINGLETHREAD], +** [SQLITE_CONFIG_MULTITHREAD], [SQLITE_CONFIG_SERIALIZED], +** and [SQLITE_CONFIG_MUTEX] verbs. */ int sqlite3_threadsafe(void); /* -** CAPI3REF: Database Connection Handle {F12000} +** CAPI3REF: Database Connection Handle {H12000} <S40200> ** KEYWORDS: {database connection} {database connections} ** -** Each open SQLite database is represented by pointer to an instance of the -** opaque structure named "sqlite3". It is useful to think of an sqlite3 +** Each open SQLite database is represented by a pointer to an instance of +** the opaque structure named "sqlite3". It is useful to think of an sqlite3 ** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and -** [sqlite3_open_v2()] interfaces are its constructors -** and [sqlite3_close()] is its destructor. There are many other interfaces -** (such as [sqlite3_prepare_v2()], [sqlite3_create_function()], and -** [sqlite3_busy_timeout()] to name but three) that are methods on this -** object. +** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()] +** is its destructor. There are many other interfaces (such as +** [sqlite3_prepare_v2()], [sqlite3_create_function()], and +** [sqlite3_busy_timeout()] to name but three) that are methods on an +** sqlite3 object. */ typedef struct sqlite3 sqlite3; - /* -** CAPI3REF: 64-Bit Integer Types {F10200} +** CAPI3REF: 64-Bit Integer Types {H10200} <S10110> ** KEYWORDS: sqlite_int64 sqlite_uint64 ** ** Because there is no cross-platform way to specify 64-bit integer types ** SQLite includes typedefs for 64-bit signed and unsigned integers. ** -** The sqlite3_int64 and sqlite3_uint64 are the preferred type -** definitions. The sqlite_int64 and sqlite_uint64 types are -** supported for backwards compatibility only. +** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions. +** The sqlite_int64 and sqlite_uint64 types are supported for backwards +** compatibility only. ** ** INVARIANTS: ** -** {F10201} The [sqlite_int64] and [sqlite3_int64] types specify a -** 64-bit signed integer. +** {H10201} The [sqlite_int64] and [sqlite3_int64] type shall specify +** a 64-bit signed integer. ** -** {F10202} The [sqlite_uint64] and [sqlite3_uint64] types specify +** {H10202} The [sqlite_uint64] and [sqlite3_uint64] type shall specify ** a 64-bit unsigned integer. */ #ifdef SQLITE_INT64_TYPE @@ -203,50 +217,62 @@ typedef sqlite_uint64 sqlite3_uint64; /* ** If compiling for a processor that lacks floating point support, -** substitute integer for floating-point +** substitute integer for floating-point. */ #ifdef SQLITE_OMIT_FLOATING_POINT # define double sqlite3_int64 #endif /* -** CAPI3REF: Closing A Database Connection {F12010} +** CAPI3REF: Closing A Database Connection {H12010} <S30100><S40200> ** -** This routine is the destructor for the [sqlite3] object. +** This routine is the destructor for the [sqlite3] object. ** -** Applications should [sqlite3_finalize | finalize] all -** [prepared statements] and -** [sqlite3_blob_close | close] all [sqlite3_blob | BLOBs] -** associated with the [sqlite3] object prior -** to attempting to close the [sqlite3] object. +** Applications should [sqlite3_finalize | finalize] all [prepared statements] +** and [sqlite3_blob_close | close] all [BLOB handles] associated with +** the [sqlite3] object prior to attempting to close the object. +** The [sqlite3_next_stmt()] interface can be used to locate all +** [prepared statements] associated with a [database connection] if desired. +** Typical code might look like this: +** +** <blockquote><pre> +** sqlite3_stmt *pStmt; +** while( (pStmt = sqlite3_next_stmt(db, 0))!=0 ){ +** sqlite3_finalize(pStmt); +** } +** </pre></blockquote> ** -** <todo>What happens to pending transactions? Are they -** rolled back, or abandoned?</todo> +** If [sqlite3_close()] is invoked while a transaction is open, +** the transaction is automatically rolled back. ** ** INVARIANTS: ** -** {F12011} The [sqlite3_close()] interface destroys an [sqlite3] object -** allocated by a prior call to [sqlite3_open()], -** [sqlite3_open16()], or [sqlite3_open_v2()]. +** {H12011} A successful call to [sqlite3_close(C)] shall destroy the +** [database connection] object C. +** +** {H12012} A successful call to [sqlite3_close(C)] shall return SQLITE_OK. ** -** {F12012} The [sqlite3_close()] function releases all memory used by the -** connection and closes all open files. +** {H12013} A successful call to [sqlite3_close(C)] shall release all +** memory and system resources associated with [database connection] +** C. ** -** {F12013} If the database connection contains -** [prepared statements] that have not been -** finalized by [sqlite3_finalize()], then [sqlite3_close()] -** returns [SQLITE_BUSY] and leaves the connection open. +** {H12014} A call to [sqlite3_close(C)] on a [database connection] C that +** has one or more open [prepared statements] shall fail with +** an [SQLITE_BUSY] error code. ** -** {F12014} Giving sqlite3_close() a NULL pointer is a harmless no-op. +** {H12015} A call to [sqlite3_close(C)] where C is a NULL pointer shall +** return SQLITE_OK. ** -** LIMITATIONS: +** {H12019} When [sqlite3_close(C)] is invoked on a [database connection] C +** that has a pending transaction, the transaction shall be +** rolled back. ** -** {U12015} The parameter to [sqlite3_close()] must be an [sqlite3] object -** pointer previously obtained from [sqlite3_open()] or the -** equivalent, or NULL. +** ASSUMPTIONS: ** -** {U12016} The parameter to [sqlite3_close()] must not have been previously -** closed. +** {A12016} The C parameter to [sqlite3_close(C)] must be either a NULL +** pointer or an [sqlite3] object pointer obtained +** from [sqlite3_open()], [sqlite3_open16()], or +** [sqlite3_open_v2()], and not previously closed. */ int sqlite3_close(sqlite3 *); @@ -258,115 +284,129 @@ int sqlite3_close(sqlite3 *); typedef int (*sqlite3_callback)(void*,int,char**, char**); /* -** CAPI3REF: One-Step Query Execution Interface {F12100} -** -** The sqlite3_exec() interface is a convenient way of running -** one or more SQL statements without a lot of C code. The -** SQL statements are passed in as the second parameter to -** sqlite3_exec(). The statements are evaluated one by one -** until either an error or an interrupt is encountered or -** until they are all done. The 3rd parameter is an optional -** callback that is invoked once for each row of any query results -** produced by the SQL statements. The 5th parameter tells where +** CAPI3REF: One-Step Query Execution Interface {H12100} <S10000> +** +** The sqlite3_exec() interface is a convenient way of running one or more +** SQL statements without having to write a lot of C code. The UTF-8 encoded +** SQL statements are passed in as the second parameter to sqlite3_exec(). +** The statements are evaluated one by one until either an error or +** an interrupt is encountered, or until they are all done. The 3rd parameter +** is an optional callback that is invoked once for each row of any query +** results produced by the SQL statements. The 5th parameter tells where ** to write any error messages. ** +** The error message passed back through the 5th parameter is held +** in memory obtained from [sqlite3_malloc()]. To avoid a memory leak, +** the calling application should call [sqlite3_free()] on any error +** message returned through the 5th parameter when it has finished using +** the error message. +** +** If the SQL statement in the 2nd parameter is NULL or an empty string +** or a string containing only whitespace and comments, then no SQL +** statements are evaluated and the database is not changed. +** ** The sqlite3_exec() interface is implemented in terms of ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]. -** The sqlite3_exec() routine does nothing that cannot be done +** The sqlite3_exec() routine does nothing to the database that cannot be done ** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]. -** The sqlite3_exec() is just a convenient wrapper. ** ** INVARIANTS: -** -** {F12101} The [sqlite3_exec()] interface evaluates zero or more UTF-8 -** encoded, semicolon-separated, SQL statements in the -** zero-terminated string of its 2nd parameter within the -** context of the [sqlite3] object given in the 1st parameter. ** -** {F12104} The return value of [sqlite3_exec()] is SQLITE_OK if all -** SQL statements run successfully. +** {H12101} A successful invocation of [sqlite3_exec(D,S,C,A,E)] +** shall sequentially evaluate all of the UTF-8 encoded, +** semicolon-separated SQL statements in the zero-terminated +** string S within the context of the [database connection] D. +** +** {H12102} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL then +** the actions of the interface shall be the same as if the +** S parameter were an empty string. +** +** {H12104} The return value of [sqlite3_exec()] shall be [SQLITE_OK] if all +** SQL statements run successfully and to completion. ** -** {F12105} The return value of [sqlite3_exec()] is an appropriate -** non-zero error code if any SQL statement fails. +** {H12105} The return value of [sqlite3_exec()] shall be an appropriate +** non-zero [error code] if any SQL statement fails. ** -** {F12107} If one or more of the SQL statements handed to [sqlite3_exec()] +** {H12107} If one or more of the SQL statements handed to [sqlite3_exec()] ** return results and the 3rd parameter is not NULL, then -** the callback function specified by the 3rd parameter is +** the callback function specified by the 3rd parameter shall be ** invoked once for each row of result. ** -** {F12110} If the callback returns a non-zero value then [sqlite3_exec()] -** will aborted the SQL statement it is currently evaluating, +** {H12110} If the callback returns a non-zero value then [sqlite3_exec()] +** shall abort the SQL statement it is currently evaluating, ** skip all subsequent SQL statements, and return [SQLITE_ABORT]. -** <todo>What happens to *errmsg here? Does the result code for -** sqlite3_errcode() get set?</todo> ** -** {F12113} The [sqlite3_exec()] routine will pass its 4th parameter through +** {H12113} The [sqlite3_exec()] routine shall pass its 4th parameter through ** as the 1st parameter of the callback. ** -** {F12116} The [sqlite3_exec()] routine sets the 2nd parameter of its +** {H12116} The [sqlite3_exec()] routine shall set the 2nd parameter of its ** callback to be the number of columns in the current row of ** result. ** -** {F12119} The [sqlite3_exec()] routine sets the 3rd parameter of its +** {H12119} The [sqlite3_exec()] routine shall set the 3rd parameter of its ** callback to be an array of pointers to strings holding the ** values for each column in the current result set row as ** obtained from [sqlite3_column_text()]. ** -** {F12122} The [sqlite3_exec()] routine sets the 4th parameter of its +** {H12122} The [sqlite3_exec()] routine shall set the 4th parameter of its ** callback to be an array of pointers to strings holding the ** names of result columns as obtained from [sqlite3_column_name()]. ** -** {F12125} If the 3rd parameter to [sqlite3_exec()] is NULL then -** [sqlite3_exec()] never invokes a callback. All query -** results are silently discarded. +** {H12125} If the 3rd parameter to [sqlite3_exec()] is NULL then +** [sqlite3_exec()] shall silently discard query results. ** -** {F12128} If an error occurs while parsing or evaluating any of the SQL -** statements handed to [sqlite3_exec()] then [sqlite3_exec()] will -** return an [error code] other than [SQLITE_OK]. +** {H12131} If an error occurs while parsing or evaluating any of the SQL +** statements in the S parameter of [sqlite3_exec(D,S,C,A,E)] and if +** the E parameter is not NULL, then [sqlite3_exec()] shall store +** in *E an appropriate error message written into memory obtained +** from [sqlite3_malloc()]. ** -** {F12131} If an error occurs while parsing or evaluating any of the SQL -** handed to [sqlite3_exec()] and if the 5th parameter (errmsg) -** to [sqlite3_exec()] is not NULL, then an error message is -** allocated using the equivalent of [sqlite3_mprintf()] and -** *errmsg is made to point to that message. +** {H12134} The [sqlite3_exec(D,S,C,A,E)] routine shall set the value of +** *E to NULL if E is not NULL and there are no errors. ** -** {F12134} The [sqlite3_exec()] routine does not change the value of -** *errmsg if errmsg is NULL or if there are no errors. +** {H12137} The [sqlite3_exec(D,S,C,A,E)] function shall set the [error code] +** and message accessible via [sqlite3_errcode()], +** [sqlite3_errmsg()], and [sqlite3_errmsg16()]. ** -** {F12137} The [sqlite3_exec()] function sets the error code and message -** accessible via [sqlite3_errcode()], [sqlite3_errmsg()], and -** [sqlite3_errmsg16()]. +** {H12138} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL or an +** empty string or contains nothing other than whitespace, comments, +** and/or semicolons, then results of [sqlite3_errcode()], +** [sqlite3_errmsg()], and [sqlite3_errmsg16()] +** shall reset to indicate no errors. ** -** LIMITATIONS: +** ASSUMPTIONS: ** -** {U12141} The first parameter to [sqlite3_exec()] must be an valid and open +** {A12141} The first parameter to [sqlite3_exec()] must be an valid and open ** [database connection]. ** -** {U12142} The database connection must not be closed while +** {A12142} The database connection must not be closed while ** [sqlite3_exec()] is running. -** -** {U12143} The calling function is should use [sqlite3_free()] to free +** +** {A12143} The calling function should use [sqlite3_free()] to free ** the memory that *errmsg is left pointing at once the error ** message is no longer needed. ** -** {U12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()] +** {A12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()] ** must remain unchanged while [sqlite3_exec()] is running. */ int sqlite3_exec( sqlite3*, /* An open database */ - const char *sql, /* SQL to be evaluted */ + const char *sql, /* SQL to be evaluated */ int (*callback)(void*,int,char**,char**), /* Callback function */ void *, /* 1st argument to callback */ char **errmsg /* Error msg written here */ ); /* -** CAPI3REF: Result Codes {F10210} +** CAPI3REF: Result Codes {H10210} <S10700> ** KEYWORDS: SQLITE_OK {error code} {error codes} +** KEYWORDS: {result code} {result codes} ** ** Many SQLite functions return an integer result code from the set shown ** here in order to indicates success or failure. ** +** New error codes may be added in future versions of SQLite. +** ** See also: [SQLITE_IOERR_READ | extended result codes] */ #define SQLITE_OK 0 /* Successful result */ @@ -402,20 +442,20 @@ int sqlite3_exec( /* end-of-error-codes */ /* -** CAPI3REF: Extended Result Codes {F10220} +** CAPI3REF: Extended Result Codes {H10220} <S10700> ** KEYWORDS: {extended error code} {extended error codes} -** KEYWORDS: {extended result codes} +** KEYWORDS: {extended result code} {extended result codes} ** ** In its default configuration, SQLite API routines return one of 26 integer -** [SQLITE_OK | result codes]. However, experience has shown that -** many of these result codes are too course-grained. They do not provide as +** [SQLITE_OK | result codes]. However, experience has shown that many of +** these result codes are too coarse-grained. They do not provide as ** much information about problems as programmers might like. In an effort to ** address this, newer versions of SQLite (version 3.3.8 and later) include ** support for additional result codes that provide more detailed information ** about errors. The extended result codes are enabled or disabled -** for each database connection using the [sqlite3_extended_result_codes()] -** API. -** +** on a per database connection basis using the +** [sqlite3_extended_result_codes()] API. +** ** Some of the available extended result codes are listed here. ** One may expect the number of extended result codes will be expand ** over time. Software that uses extended result codes should expect @@ -423,35 +463,37 @@ int sqlite3_exec( ** ** The SQLITE_OK result code will never be extended. It will always ** be exactly zero. -** +** ** INVARIANTS: ** -** {F10223} The symbolic name for an extended result code always contains +** {H10223} The symbolic name for an extended result code shall contains ** a related primary result code as a prefix. ** -** {F10224} Primary result code names contain a single "_" character. +** {H10224} Primary result code names shall contain a single "_" character. ** -** {F10225} Extended result code names contain two or more "_" characters. +** {H10225} Extended result code names shall contain two or more "_" characters. ** -** {F10226} The numeric value of an extended result code contains the +** {H10226} The numeric value of an extended result code shall contain the ** numeric value of its corresponding primary result code in ** its least significant 8 bits. */ -#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) -#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) -#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) -#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) -#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) -#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) -#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) -#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) -#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) -#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) -#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) -#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8)) +#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) +#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) +#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) +#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) +#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) +#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) +#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) +#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) +#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) +#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) +#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) +#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8)) +#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8)) +#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8)) /* -** CAPI3REF: Flags For File Open Operations {F10230} +** CAPI3REF: Flags For File Open Operations {H10230} <H11120> <H12700> ** ** These bit values are intended for use in the ** 3rd parameter to the [sqlite3_open_v2()] interface and @@ -470,9 +512,10 @@ int sqlite3_exec( #define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 #define SQLITE_OPEN_SUBJOURNAL 0x00002000 #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 +#define SQLITE_OPEN_NOMUTEX 0x00008000 /* -** CAPI3REF: Device Characteristics {F10240} +** CAPI3REF: Device Characteristics {H10240} <H11120> ** ** The xDeviceCapabilities method of the [sqlite3_io_methods] ** object returns an integer which is a vector of the these @@ -504,7 +547,7 @@ int sqlite3_exec( #define SQLITE_IOCAP_SEQUENTIAL 0x00000400 /* -** CAPI3REF: File Locking Levels {F10250} +** CAPI3REF: File Locking Levels {H10250} <H11120> <H11310> ** ** SQLite uses one of these integer values as the second ** argument to calls it makes to the xLock() and xUnlock() methods @@ -517,7 +560,7 @@ int sqlite3_exec( #define SQLITE_LOCK_EXCLUSIVE 4 /* -** CAPI3REF: Synchronization Type Flags {F10260} +** CAPI3REF: Synchronization Type Flags {H10260} <H11120> ** ** When SQLite invokes the xSync() method of an ** [sqlite3_io_methods] object it uses a combination of @@ -525,17 +568,16 @@ int sqlite3_exec( ** ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the ** sync operation only needs to flush data to mass storage. Inode -** information need not be flushed. The SQLITE_SYNC_NORMAL flag means -** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means +** information need not be flushed. The SQLITE_SYNC_NORMAL flag means +** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means ** to use Mac OS-X style fullsync instead of fsync(). */ #define SQLITE_SYNC_NORMAL 0x00002 #define SQLITE_SYNC_FULL 0x00003 #define SQLITE_SYNC_DATAONLY 0x00010 - /* -** CAPI3REF: OS Interface Open File Handle {F11110} +** CAPI3REF: OS Interface Open File Handle {H11110} <S20110> ** ** An [sqlite3_file] object represents an open file in the OS ** interface layer. Individual OS interface implementations will @@ -550,19 +592,20 @@ struct sqlite3_file { }; /* -** CAPI3REF: OS Interface File Virtual Methods Object {F11120} +** CAPI3REF: OS Interface File Virtual Methods Object {H11120} <S20110> ** -** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to -** an instance of this object. This object defines the -** methods used to perform various operations against the open file. +** Every file opened by the [sqlite3_vfs] xOpen method populates an +** [sqlite3_file] object (or, more commonly, a subclass of the +** [sqlite3_file] object) with a pointer to an instance of this object. +** This object defines the methods used to perform various operations +** against the open file represented by the [sqlite3_file] object. ** ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync(). -* The second choice is an -** OS-X style fullsync. The SQLITE_SYNC_DATA flag may be ORed in to -** indicate that only the data of the file and not its inode needs to be -** synced. -** +** The second choice is a Mac OS-X style fullsync. The [SQLITE_SYNC_DATAONLY] +** flag may be ORed in to indicate that only the data of the file +** and not its inode needs to be synced. +** ** The integer values to xLock() and xUnlock() are one of ** <ul> ** <li> [SQLITE_LOCK_NONE], @@ -571,26 +614,24 @@ struct sqlite3_file { ** <li> [SQLITE_LOCK_PENDING], or ** <li> [SQLITE_LOCK_EXCLUSIVE]. ** </ul> -** xLock() increases the lock. xUnlock() decreases the lock. -** The xCheckReservedLock() method looks -** to see if any database connection, either in this -** process or in some other process, is holding an RESERVED, +** xLock() increases the lock. xUnlock() decreases the lock. +** The xCheckReservedLock() method checks whether any database connection, +** either in this process or in some other process, is holding a RESERVED, ** PENDING, or EXCLUSIVE lock on the file. It returns true -** if such a lock exists and false if not. -** +** if such a lock exists and false otherwise. +** ** The xFileControl() method is a generic interface that allows custom ** VFS implementations to directly control an open file using the -** [sqlite3_file_control()] interface. The second "op" argument -** is an integer opcode. The third -** argument is a generic pointer which is intended to be a pointer -** to a structure that may contain arguments or space in which to +** [sqlite3_file_control()] interface. The second "op" argument is an +** integer opcode. The third argument is a generic pointer intended to +** point to a structure that may contain arguments or space in which to ** write return values. Potential uses for xFileControl() might be ** functions to enable blocking locks with timeouts, to change the ** locking strategy (for example to use dot-file locks), to inquire ** about the status of a lock, or to break stale locks. The SQLite -** core reserves opcodes less than 100 for its own use. +** core reserves all opcodes less than 100 for its own use. ** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available. -** Applications that define a custom xFileControl method should use opcodes +** Applications that define a custom xFileControl method should use opcodes ** greater than 100 to avoid conflicts. ** ** The xSectorSize() method returns the sector size of the @@ -636,7 +677,7 @@ struct sqlite3_io_methods { int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize); int (*xLock)(sqlite3_file*, int); int (*xUnlock)(sqlite3_file*, int); - int (*xCheckReservedLock)(sqlite3_file*); + int (*xCheckReservedLock)(sqlite3_file*, int *pResOut); int (*xFileControl)(sqlite3_file*, int op, void *pArg); int (*xSectorSize)(sqlite3_file*); int (*xDeviceCharacteristics)(sqlite3_file*); @@ -644,10 +685,10 @@ struct sqlite3_io_methods { }; /* -** CAPI3REF: Standard File Control Opcodes {F11310} +** CAPI3REF: Standard File Control Opcodes {H11310} <S30800> ** ** These integer constants are opcodes for the xFileControl method -** of the [sqlite3_io_methods] object and to the [sqlite3_file_control()] +** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()] ** interface. ** ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This @@ -661,7 +702,7 @@ struct sqlite3_io_methods { #define SQLITE_FCNTL_LOCKSTATE 1 /* -** CAPI3REF: Mutex Handle {F17110} +** CAPI3REF: Mutex Handle {H17110} <S20130> ** ** The mutex module within SQLite defines [sqlite3_mutex] to be an ** abstract type for a mutex object. The SQLite core never looks @@ -673,15 +714,18 @@ struct sqlite3_io_methods { typedef struct sqlite3_mutex sqlite3_mutex; /* -** CAPI3REF: OS Interface Object {F11140} +** CAPI3REF: OS Interface Object {H11140} <S20100> ** -** An instance of this object defines the interface between the -** SQLite core and the underlying operating system. The "vfs" +** An instance of the sqlite3_vfs object defines the interface between +** the SQLite core and the underlying operating system. The "vfs" ** in the name of the object stands for "virtual file system". ** -** The iVersion field is initially 1 but may be larger for future -** versions of SQLite. Additional fields may be appended to this -** object when the iVersion value is increased. +** The value of the iVersion field is initially 1 but may be larger in +** future versions of SQLite. Additional fields may be appended to this +** object when the iVersion value is increased. Note that the structure +** of the sqlite3_vfs object changes in the transaction between +** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not +** modified. ** ** The szOsFile field is the size of the subclassed [sqlite3_file] ** structure used by this VFS. mxPathname is the maximum length of @@ -691,9 +735,10 @@ typedef struct sqlite3_mutex sqlite3_mutex; ** the pNext pointer. The [sqlite3_vfs_register()] ** and [sqlite3_vfs_unregister()] interfaces manage this list ** in a thread-safe way. The [sqlite3_vfs_find()] interface -** searches the list. +** searches the list. Neither the application code nor the VFS +** implementation should use the pNext pointer. ** -** The pNext field is the only field in the sqlite3_vfs +** The pNext field is the only field in the sqlite3_vfs ** structure that SQLite will ever modify. SQLite will only access ** or modify this field while holding a particular static mutex. ** The application should never modify anything within the sqlite3_vfs @@ -702,23 +747,28 @@ typedef struct sqlite3_mutex sqlite3_mutex; ** The zName field holds the name of the VFS module. The name must ** be unique across all VFS modules. ** -** {F11141} SQLite will guarantee that the zFilename string passed to -** xOpen() is a full pathname as generated by xFullPathname() and -** that the string will be valid and unchanged until xClose() is -** called. {END} So the [sqlite3_file] can store a pointer to the +** {H11141} SQLite will guarantee that the zFilename parameter to xOpen +** is either a NULL pointer or string obtained +** from xFullPathname(). SQLite further guarantees that +** the string will be valid and unchanged until xClose() is +** called. {END} Because of the previous sentense, +** the [sqlite3_file] can safely store a pointer to the ** filename if it needs to remember the filename for some reason. +** If the zFilename parameter is xOpen is a NULL pointer then xOpen +** must invite its own temporary name for the file. Whenever the +** xFilename parameter is NULL it will also be the case that the +** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE]. ** -** {F11142} The flags argument to xOpen() includes all bits set in +** {H11142} The flags argument to xOpen() includes all bits set in ** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()] ** or [sqlite3_open16()] is used, then flags includes at least ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. {END} ** If xOpen() opens a file read-only then it sets *pOutFlags to -** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be -** set. -** -** {F11143} SQLite will also add one of the following flags to the xOpen() +** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set. +** +** {H11143} SQLite will also add one of the following flags to the xOpen() ** call, depending on the object being opened: -** +** ** <ul> ** <li> [SQLITE_OPEN_MAIN_DB] ** <li> [SQLITE_OPEN_MAIN_JOURNAL] @@ -730,59 +780,56 @@ typedef struct sqlite3_mutex sqlite3_mutex; ** </ul> {END} ** ** The file I/O implementation can use the object type flags to -** changes the way it deals with files. For example, an application +** change the way it deals with files. For example, an application ** that does not care about crash recovery or rollback might make ** the open of a journal file a no-op. Writes to this journal would -** also be no-ops, and any attempt to read the journal would return -** SQLITE_IOERR. Or the implementation might recognize that a database -** file will be doing page-aligned sector reads and writes in a random +** also be no-ops, and any attempt to read the journal would return +** SQLITE_IOERR. Or the implementation might recognize that a database +** file will be doing page-aligned sector reads and writes in a random ** order and set up its I/O subsystem accordingly. -** -** SQLite might also add one of the following flags to the xOpen -** method: -** +** +** SQLite might also add one of the following flags to the xOpen method: +** ** <ul> ** <li> [SQLITE_OPEN_DELETEONCLOSE] ** <li> [SQLITE_OPEN_EXCLUSIVE] ** </ul> -** -** {F11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be -** deleted when it is closed. {F11146} The [SQLITE_OPEN_DELETEONCLOSE] -** will be set for TEMP databases, journals and for subjournals. -** {F11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened +** +** {H11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be +** deleted when it is closed. {H11146} The [SQLITE_OPEN_DELETEONCLOSE] +** will be set for TEMP databases, journals and for subjournals. +** +** {H11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened ** for exclusive access. This flag is set for all files except -** for the main database file. {END} -** -** {F11148} At least szOsFile bytes of memory are allocated by SQLite -** to hold the [sqlite3_file] structure passed as the third -** argument to xOpen. {END} The xOpen method does not have to +** for the main database file. +** +** {H11148} At least szOsFile bytes of memory are allocated by SQLite +** to hold the [sqlite3_file] structure passed as the third +** argument to xOpen. {END} The xOpen method does not have to ** allocate the structure; it should just fill it in. -** -** {F11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] -** to test for the existance of a file, -** or [SQLITE_ACCESS_READWRITE] to test to see -** if a file is readable and writable, or [SQLITE_ACCESS_READ] -** to test to see if a file is at least readable. {END} The file can be a +** +** {H11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] +** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to +** test whether a file is readable and writable, or [SQLITE_ACCESS_READ] +** to test whether a file is at least readable. {END} The file can be a ** directory. -** -** {F11150} SQLite will always allocate at least mxPathname+1 bytes for -** the output buffers for xGetTempname and xFullPathname. {F11151} The exact -** size of the output buffer is also passed as a parameter to both -** methods. {END} If the output buffer is not large enough, SQLITE_CANTOPEN -** should be returned. As this is handled as a fatal error by SQLite, -** vfs implementations should endeavor to prevent this by setting -** mxPathname to a sufficiently large value. -** +** +** {H11150} SQLite will always allocate at least mxPathname+1 bytes for the +** output buffer xFullPathname. {H11151} The exact size of the output buffer +** is also passed as a parameter to both methods. {END} If the output buffer +** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is +** handled as a fatal error by SQLite, vfs implementations should endeavor +** to prevent this by setting mxPathname to a sufficiently large value. +** ** The xRandomness(), xSleep(), and xCurrentTime() interfaces ** are not strictly a part of the filesystem, but they are ** included in the VFS structure for completeness. ** The xRandomness() function attempts to return nBytes bytes ** of good-quality randomness into zOut. The return value is -** the actual number of bytes of randomness obtained. The -** xSleep() method causes the calling thread to sleep for at +** the actual number of bytes of randomness obtained. +** The xSleep() method causes the calling thread to sleep for at ** least the number of microseconds given. The xCurrentTime() -** method returns a Julian Day Number for the current date and -** time. +** method returns a Julian Day Number for the current date and time. */ typedef struct sqlite3_vfs sqlite3_vfs; struct sqlite3_vfs { @@ -795,8 +842,7 @@ struct sqlite3_vfs { int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*, int flags, int *pOutFlags); int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir); - int (*xAccess)(sqlite3_vfs*, const char *zName, int flags); - int (*xGetTempname)(sqlite3_vfs*, int nOut, char *zOut); + int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut); int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut); void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename); void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg); @@ -805,50 +851,399 @@ struct sqlite3_vfs { int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut); int (*xSleep)(sqlite3_vfs*, int microseconds); int (*xCurrentTime)(sqlite3_vfs*, double*); + int (*xGetLastError)(sqlite3_vfs*, int, char *); /* New fields may be appended in figure versions. The iVersion ** value will increment whenever this happens. */ }; /* -** CAPI3REF: Flags for the xAccess VFS method {F11190} +** CAPI3REF: Flags for the xAccess VFS method {H11190} <H11140> ** -** {F11191} These integer constants can be used as the third parameter to +** {H11191} These integer constants can be used as the third parameter to ** the xAccess method of an [sqlite3_vfs] object. {END} They determine -** what kind of permissions the xAccess method is -** looking for. {F11192} With SQLITE_ACCESS_EXISTS, the xAccess method -** simply checks to see if the file exists. {F11193} With -** SQLITE_ACCESS_READWRITE, the xAccess method checks to see -** if the file is both readable and writable. {F11194} With -** SQLITE_ACCESS_READ the xAccess method -** checks to see if the file is readable. +** what kind of permissions the xAccess method is looking for. +** {H11192} With SQLITE_ACCESS_EXISTS, the xAccess method +** simply checks whether the file exists. +** {H11193} With SQLITE_ACCESS_READWRITE, the xAccess method +** checks whether the file is both readable and writable. +** {H11194} With SQLITE_ACCESS_READ, the xAccess method +** checks whether the file is readable. */ #define SQLITE_ACCESS_EXISTS 0 #define SQLITE_ACCESS_READWRITE 1 #define SQLITE_ACCESS_READ 2 /* -** CAPI3REF: Enable Or Disable Extended Result Codes {F12200} +** CAPI3REF: Initialize The SQLite Library {H10130} <S20000><S30100> +** +** The sqlite3_initialize() routine initializes the +** SQLite library. The sqlite3_shutdown() routine +** deallocates any resources that were allocated by sqlite3_initialize(). +** +** A call to sqlite3_initialize() is an "effective" call if it is +** the first time sqlite3_initialize() is invoked during the lifetime of +** the process, or if it is the first time sqlite3_initialize() is invoked +** following a call to sqlite3_shutdown(). Only an effective call +** of sqlite3_initialize() does any initialization. All other calls +** are harmless no-ops. +** +** Among other things, sqlite3_initialize() shall invoke +** sqlite3_os_init(). Similarly, sqlite3_shutdown() +** shall invoke sqlite3_os_end(). +** +** The sqlite3_initialize() routine returns SQLITE_OK on success. +** If for some reason, sqlite3_initialize() is unable to initialize +** the library (perhaps it is unable to allocate a needed resource such +** as a mutex) it returns an [error code] other than SQLITE_OK. +** +** The sqlite3_initialize() routine is called internally by many other +** SQLite interfaces so that an application usually does not need to +** invoke sqlite3_initialize() directly. For example, [sqlite3_open()] +** calls sqlite3_initialize() so the SQLite library will be automatically +** initialized when [sqlite3_open()] is called if it has not be initialized +** already. However, if SQLite is compiled with the SQLITE_OMIT_AUTOINIT +** compile-time option, then the automatic calls to sqlite3_initialize() +** are omitted and the application must call sqlite3_initialize() directly +** prior to using any other SQLite interface. For maximum portability, +** it is recommended that applications always invoke sqlite3_initialize() +** directly prior to using any other SQLite interface. Future releases +** of SQLite may require this. In other words, the behavior exhibited +** when SQLite is compiled with SQLITE_OMIT_AUTOINIT might become the +** default behavior in some future release of SQLite. +** +** The sqlite3_os_init() routine does operating-system specific +** initialization of the SQLite library. The sqlite3_os_end() +** routine undoes the effect of sqlite3_os_init(). Typical tasks +** performed by these routines include allocation or deallocation +** of static resources, initialization of global variables, +** setting up a default [sqlite3_vfs] module, or setting up +** a default configuration using [sqlite3_config()]. +** +** The application should never invoke either sqlite3_os_init() +** or sqlite3_os_end() directly. The application should only invoke +** sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init() +** interface is called automatically by sqlite3_initialize() and +** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate +** implementations for sqlite3_os_init() and sqlite3_os_end() +** are built into SQLite when it is compiled for unix, windows, or os/2. +** When built for other platforms (using the SQLITE_OS_OTHER=1 compile-time +** option) the application must supply a suitable implementation for +** sqlite3_os_init() and sqlite3_os_end(). An application-supplied +** implementation of sqlite3_os_init() or sqlite3_os_end() +** must return SQLITE_OK on success and some other [error code] upon +** failure. +*/ +int sqlite3_initialize(void); +int sqlite3_shutdown(void); +int sqlite3_os_init(void); +int sqlite3_os_end(void); + +/* +** CAPI3REF: Configuring The SQLite Library {H10145} <S20000><S30200> +** EXPERIMENTAL +** +** The sqlite3_config() interface is used to make global configuration +** changes to SQLite in order to tune SQLite to the specific needs of +** the application. The default configuration is recommended for most +** applications and so this routine is usually not necessary. It is +** provided to support rare applications with unusual needs. +** +** The sqlite3_config() interface is not threadsafe. The application +** must insure that no other SQLite interfaces are invoked by other +** threads while sqlite3_config() is running. Furthermore, sqlite3_config() +** may only be invoked prior to library initialization using +** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()]. +** Note, however, that sqlite3_config() can be called as part of the +** implementation of an application-defined [sqlite3_os_init()]. +** +** The first argument to sqlite3_config() is an integer +** [SQLITE_CONFIG_SINGLETHREAD | configuration option] that determines +** what property of SQLite is to be configured. Subsequent arguments +** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option] +** in the first argument. +** +** When a configuration option is set, sqlite3_config() returns SQLITE_OK. +** If the option is unknown or SQLite is unable to set the option +** then this routine returns a non-zero [error code]. +*/ +int sqlite3_config(int, ...); + +/* +** CAPI3REF: Configure database connections {H10180} <S20000> +** EXPERIMENTAL +** +** The sqlite3_db_config() interface is used to make configuration +** changes to a [database connection]. The interface is similar to +** [sqlite3_config()] except that the changes apply to a single +** [database connection] (specified in the first argument). The +** sqlite3_db_config() interface can only be used immediately after +** the database connection is created using [sqlite3_open()], +** [sqlite3_open16()], or [sqlite3_open_v2()]. +** +** The second argument to sqlite3_db_config(D,V,...) is the +** configuration verb - an integer code that indicates what +** aspect of the [database connection] is being configured. +** The only choice for this value is [SQLITE_DBCONFIG_LOOKASIDE]. +** New verbs are likely to be added in future releases of SQLite. +** Additional arguments depend on the verb. +*/ +int sqlite3_db_config(sqlite3*, int op, ...); + +/* +** CAPI3REF: Memory Allocation Routines {H10155} <S20120> +** EXPERIMENTAL +** +** An instance of this object defines the interface between SQLite +** and low-level memory allocation routines. +** +** This object is used in only one place in the SQLite interface. +** A pointer to an instance of this object is the argument to +** [sqlite3_config()] when the configuration option is +** [SQLITE_CONFIG_MALLOC]. By creating an instance of this object +** and passing it to [sqlite3_config()] during configuration, an +** application can specify an alternative memory allocation subsystem +** for SQLite to use for all of its dynamic memory needs. +** +** Note that SQLite comes with a built-in memory allocator that is +** perfectly adequate for the overwhelming majority of applications +** and that this object is only useful to a tiny minority of applications +** with specialized memory allocation requirements. This object is +** also used during testing of SQLite in order to specify an alternative +** memory allocator that simulates memory out-of-memory conditions in +** order to verify that SQLite recovers gracefully from such +** conditions. +** +** The xMalloc, xFree, and xRealloc methods must work like the +** malloc(), free(), and realloc() functions from the standard library. +** +** xSize should return the allocated size of a memory allocation +** previously obtained from xMalloc or xRealloc. The allocated size +** is always at least as big as the requested size but may be larger. +** +** The xRoundup method returns what would be the allocated size of +** a memory allocation given a particular requested size. Most memory +** allocators round up memory allocations at least to the next multiple +** of 8. Some allocators round up to a larger multiple or to a power of 2. +** +** The xInit method initializes the memory allocator. (For example, +** it might allocate any require mutexes or initialize internal data +** structures. The xShutdown method is invoked (indirectly) by +** [sqlite3_shutdown()] and should deallocate any resources acquired +** by xInit. The pAppData pointer is used as the only parameter to +** xInit and xShutdown. +*/ +typedef struct sqlite3_mem_methods sqlite3_mem_methods; +struct sqlite3_mem_methods { + void *(*xMalloc)(int); /* Memory allocation function */ + void (*xFree)(void*); /* Free a prior allocation */ + void *(*xRealloc)(void*,int); /* Resize an allocation */ + int (*xSize)(void*); /* Return the size of an allocation */ + int (*xRoundup)(int); /* Round up request size to allocation size */ + int (*xInit)(void*); /* Initialize the memory allocator */ + void (*xShutdown)(void*); /* Deinitialize the memory allocator */ + void *pAppData; /* Argument to xInit() and xShutdown() */ +}; + +/* +** CAPI3REF: Configuration Options {H10160} <S20000> +** EXPERIMENTAL +** +** These constants are the available integer configuration options that +** can be passed as the first argument to the [sqlite3_config()] interface. +** +** New configuration options may be added in future releases of SQLite. +** Existing configuration options might be discontinued. Applications +** should check the return code from [sqlite3_config()] to make sure that +** the call worked. The [sqlite3_config()] interface will return a +** non-zero [error code] if a discontinued or unsupported configuration option +** is invoked. +** +** <dl> +** <dt>SQLITE_CONFIG_SINGLETHREAD</dt> +** <dd>There are no arguments to this option. This option disables +** all mutexing and puts SQLite into a mode where it can only be used +** by a single thread.</dd> +** +** <dt>SQLITE_CONFIG_MULTITHREAD</dt> +** <dd>There are no arguments to this option. This option disables +** mutexing on [database connection] and [prepared statement] objects. +** The application is responsible for serializing access to +** [database connections] and [prepared statements]. But other mutexes +** are enabled so that SQLite will be safe to use in a multi-threaded +** environment.</dd> +** +** <dt>SQLITE_CONFIG_SERIALIZED</dt> +** <dd>There are no arguments to this option. This option enables +** all mutexes including the recursive +** mutexes on [database connection] and [prepared statement] objects. +** In this mode (which is the default when SQLite is compiled with +** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access +** to [database connections] and [prepared statements] so that the +** application is free to use the same [database connection] or the +** same [prepared statement] in different threads at the same time. +** +** <p>This configuration option merely sets the default mutex +** behavior to serialize access to [database connections]. Individual +** [database connections] can override this setting +** using the [SQLITE_OPEN_NOMUTEX] flag to [sqlite3_open_v2()].</p></dd> +** +** <dt>SQLITE_CONFIG_MALLOC</dt> +** <dd>This option takes a single argument which is a pointer to an +** instance of the [sqlite3_mem_methods] structure. The argument specifies +** alternative low-level memory allocation routines to be used in place of +** the memory allocation routines built into SQLite.</dd> +** +** <dt>SQLITE_CONFIG_GETMALLOC</dt> +** <dd>This option takes a single argument which is a pointer to an +** instance of the [sqlite3_mem_methods] structure. The [sqlite3_mem_methods] +** structure is filled with the currently defined memory allocation routines. +** This option can be used to overload the default memory allocation +** routines with a wrapper that simulations memory allocation failure or +** tracks memory usage, for example.</dd> +** +** <dt>SQLITE_CONFIG_MEMSTATUS</dt> +** <dd>This option takes single argument of type int, interpreted as a +** boolean, which enables or disables the collection of memory allocation +** statistics. When disabled, the following SQLite interfaces become +** non-operational: +** <ul> +** <li> [sqlite3_memory_used()] +** <li> [sqlite3_memory_highwater()] +** <li> [sqlite3_soft_heap_limit()] +** <li> [sqlite3_status()] +** </ul> +** </dd> +** +** <dt>SQLITE_CONFIG_SCRATCH</dt> +** <dd>This option specifies a static memory buffer that SQLite can use for +** scratch memory. There are three arguments: A pointer to the memory, the +** size of each scratch buffer (sz), and the number of buffers (N). The sz +** argument must be a multiple of 16. The sz parameter should be a few bytes +** larger than the actual scratch space required due internal overhead. +** The first +** argument should point to an allocation of at least sz*N bytes of memory. +** SQLite will use no more than one scratch buffer at once per thread, so +** N should be set to the expected maximum number of threads. The sz +** parameter should be 6 times the size of the largest database page size. +** Scratch buffers are used as part of the btree balance operation. If +** The btree balancer needs additional memory beyond what is provided by +** scratch buffers or if no scratch buffer space is specified, then SQLite +** goes to [sqlite3_malloc()] to obtain the memory it needs.</dd> +** +** <dt>SQLITE_CONFIG_PAGECACHE</dt> +** <dd>This option specifies a static memory buffer that SQLite can use for +** the database page cache. There are three arguments: A pointer to the +** memory, the size of each page buffer (sz), and the number of pages (N). +** The sz argument must be a power of two between 512 and 32768. The first +** argument should point to an allocation of at least sz*N bytes of memory. +** SQLite will use the memory provided by the first argument to satisfy its +** memory needs for the first N pages that it adds to cache. If additional +** page cache memory is needed beyond what is provided by this option, then +** SQLite goes to [sqlite3_malloc()] for the additional storage space. +** The implementation might use one or more of the N buffers to hold +** memory accounting information. </dd> +** +** <dt>SQLITE_CONFIG_HEAP</dt> +** <dd>This option specifies a static memory buffer that SQLite will use +** for all of its dynamic memory allocation needs beyond those provided +** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE]. +** There are three arguments: A pointer to the memory, the number of +** bytes in the memory buffer, and the minimum allocation size. If +** the first pointer (the memory pointer) is NULL, then SQLite reverts +** to using its default memory allocator (the system malloc() implementation), +** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. If the +** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or +** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory +** allocator is engaged to handle all of SQLites memory allocation needs.</dd> +** +** <dt>SQLITE_CONFIG_MUTEX</dt> +** <dd>This option takes a single argument which is a pointer to an +** instance of the [sqlite3_mutex_methods] structure. The argument specifies +** alternative low-level mutex routines to be used in place +** the mutex routines built into SQLite.</dd> +** +** <dt>SQLITE_CONFIG_GETMUTEX</dt> +** <dd>This option takes a single argument which is a pointer to an +** instance of the [sqlite3_mutex_methods] structure. The +** [sqlite3_mutex_methods] +** structure is filled with the currently defined mutex routines. +** This option can be used to overload the default mutex allocation +** routines with a wrapper used to track mutex usage for performance +** profiling or testing, for example.</dd> +** +** <dt>SQLITE_CONFIG_LOOKASIDE</dt> +** <dd>This option takes two arguments that determine the default +** memory allcation lookaside optimization. The first argument is the +** size of each lookaside buffer slot and the second is the number of +** slots allocated to each database connection.</dd> +** +** </dl> +*/ +#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ +#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ +#define SQLITE_CONFIG_SERIALIZED 3 /* nil */ +#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */ +#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */ +#define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */ +#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ +#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ +#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ +#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ +#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ +#define SQLITE_CONFIG_CHUNKALLOC 12 /* int threshold */ +#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */ + +/* +** CAPI3REF: Configuration Options {H10170} <S20000> +** EXPERIMENTAL +** +** These constants are the available integer configuration options that +** can be passed as the second argument to the [sqlite3_db_config()] interface. +** +** New configuration options may be added in future releases of SQLite. +** Existing configuration options might be discontinued. Applications +** should check the return code from [sqlite3_db_config()] to make sure that +** the call worked. The [sqlite3_db_config()] interface will return a +** non-zero [error code] if a discontinued or unsupported configuration option +** is invoked. +** +** <dl> +** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt> +** <dd>This option takes three additional arguments that determine the +** [lookaside memory allocator] configuration for the [database connection]. +** The first argument (the third parameter to [sqlite3_db_config()] is a +** pointer to a memory buffer to use for lookaside memory. The first +** argument may be NULL in which case SQLite will allocate the lookaside +** buffer itself using [sqlite3_malloc()]. The second argument is the +** size of each lookaside buffer slot and the third argument is the number of +** slots. The size of the buffer in the first argument must be greater than +** or equal to the product of the second and third arguments.</dd> +** +** </dl> +*/ +#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ + + +/* +** CAPI3REF: Enable Or Disable Extended Result Codes {H12200} <S10700> ** ** The sqlite3_extended_result_codes() routine enables or disables the -** [SQLITE_IOERR_READ | extended result codes] feature of SQLite. -** The extended result codes are disabled by default for historical -** compatibility. +** [extended result codes] feature of SQLite. The extended result +** codes are disabled by default for historical compatibility considerations. ** ** INVARIANTS: ** -** {F12201} Each new [database connection] has the -** [extended result codes] feature -** disabled by default. +** {H12201} Each new [database connection] shall have the +** [extended result codes] feature disabled by default. ** -** {F12202} The [sqlite3_extended_result_codes(D,F)] interface will enable -** [extended result codes] for the -** [database connection] D if the F parameter -** is true, or disable them if F is false. +** {H12202} The [sqlite3_extended_result_codes(D,F)] interface shall enable +** [extended result codes] for the [database connection] D +** if the F parameter is true, or disable them if F is false. */ int sqlite3_extended_result_codes(sqlite3*, int onoff); /* -** CAPI3REF: Last Insert Rowid {F12220} +** CAPI3REF: Last Insert Rowid {H12220} <S10700> ** ** Each entry in an SQLite table has a unique 64-bit signed ** integer key called the "rowid". The rowid is always available @@ -858,44 +1253,42 @@ int sqlite3_extended_result_codes(sqlite3*, int onoff); ** is another alias for the rowid. ** ** This routine returns the rowid of the most recent -** successful INSERT into the database from the database connection -** shown in the first argument. If no successful inserts -** have ever occurred on this database connection, zero is returned. +** successful INSERT into the database from the [database connection] +** in the first argument. If no successful INSERTs +** have ever occurred on that database connection, zero is returned. ** -** If an INSERT occurs within a trigger, then the rowid of the -** inserted row is returned by this routine as long as the trigger -** is running. But once the trigger terminates, the value returned -** by this routine reverts to the last value inserted before the -** trigger fired. +** If an INSERT occurs within a trigger, then the rowid of the inserted +** row is returned by this routine as long as the trigger is running. +** But once the trigger terminates, the value returned by this routine +** reverts to the last value inserted before the trigger fired. ** ** An INSERT that fails due to a constraint violation is not a -** successful insert and does not change the value returned by this +** successful INSERT and does not change the value returned by this ** routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK, ** and INSERT OR ABORT make no changes to the return value of this -** routine when their insertion fails. When INSERT OR REPLACE +** routine when their insertion fails. When INSERT OR REPLACE ** encounters a constraint violation, it does not fail. The ** INSERT continues to completion after deleting rows that caused ** the constraint problem so INSERT OR REPLACE will always change -** the return value of this interface. +** the return value of this interface. ** -** For the purposes of this routine, an insert is considered to +** For the purposes of this routine, an INSERT is considered to ** be successful even if it is subsequently rolled back. ** ** INVARIANTS: ** -** {F12221} The [sqlite3_last_insert_rowid()] function returns the -** rowid of the most recent successful insert done -** on the same database connection and within the same -** trigger context, or zero if there have -** been no qualifying inserts on that connection. +** {H12221} The [sqlite3_last_insert_rowid()] function returns the rowid +** of the most recent successful INSERT performed on the same +** [database connection] and within the same or higher level +** trigger context, or zero if there have been no qualifying inserts. ** -** {F12223} The [sqlite3_last_insert_rowid()] function returns +** {H12223} The [sqlite3_last_insert_rowid()] function returns the ** same value when called from the same trigger context ** immediately before and after a ROLLBACK. ** -** LIMITATIONS: +** ASSUMPTIONS: ** -** {U12232} If a separate thread does a new insert on the same +** {A12232} If a separate thread performs a new INSERT on the same ** database connection while the [sqlite3_last_insert_rowid()] ** function is running and thus changes the last insert rowid, ** then the value returned by [sqlite3_last_insert_rowid()] is @@ -905,13 +1298,13 @@ int sqlite3_extended_result_codes(sqlite3*, int onoff); sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); /* -** CAPI3REF: Count The Number Of Rows Modified {F12240} +** CAPI3REF: Count The Number Of Rows Modified {H12240} <S10600> ** ** This function returns the number of database rows that were changed ** or inserted or deleted by the most recently completed SQL statement -** on the connection specified by the first parameter. Only -** changes that are directly specified by the INSERT, UPDATE, or -** DELETE statement are counted. Auxiliary changes caused by +** on the [database connection] specified by the first parameter. +** Only changes that are directly specified by the INSERT, UPDATE, +** or DELETE statement are counted. Auxiliary changes caused by ** triggers are not counted. Use the [sqlite3_total_changes()] function ** to find the total number of changes including changes caused by triggers. ** @@ -935,84 +1328,89 @@ sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); ** most recent INSERT, UPDATE, or DELETE statement within the same ** trigger context. ** -** So when called from the top level, this function returns the +** Thus, when called from the top level, this function returns the ** number of changes in the most recent INSERT, UPDATE, or DELETE -** that also occurred at the top level. -** Within the body of a trigger, the sqlite3_changes() interface -** can be called to find the number of +** that also occurred at the top level. Within the body of a trigger, +** the sqlite3_changes() interface can be called to find the number of ** changes in the most recently completed INSERT, UPDATE, or DELETE ** statement within the body of the same trigger. -** However, the number returned does not include in changes -** caused by subtriggers since they have their own context. -** -** SQLite implements the command "DELETE FROM table" without -** a WHERE clause by dropping and recreating the table. (This is much -** faster than going through and deleting individual elements from the -** table.) Because of this optimization, the deletions in -** "DELETE FROM table" are not row changes and will not be counted -** by the sqlite3_changes() or [sqlite3_total_changes()] functions. -** To get an accurate count of the number of rows deleted, use +** However, the number returned does not include changes +** caused by subtriggers since those have their own context. +** +** SQLite implements the command "DELETE FROM table" without a WHERE clause +** by dropping and recreating the table. (This is much faster than going +** through and deleting individual elements from the table.) Because of this +** optimization, the deletions in "DELETE FROM table" are not row changes and +** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()] +** functions, regardless of the number of elements that were originally +** in the table. To get an accurate count of the number of rows deleted, use ** "DELETE FROM table WHERE 1" instead. ** ** INVARIANTS: ** -** {F12241} The [sqlite3_changes()] function returns the number of +** {H12241} The [sqlite3_changes()] function shall return the number of ** row changes caused by the most recent INSERT, UPDATE, ** or DELETE statement on the same database connection and -** within the same trigger context, or zero if there have +** within the same or higher trigger context, or zero if there have ** not been any qualifying row changes. ** -** LIMITATIONS: +** {H12243} Statements of the form "DELETE FROM tablename" with no +** WHERE clause shall cause subsequent calls to +** [sqlite3_changes()] to return zero, regardless of the +** number of rows originally in the table. +** +** ASSUMPTIONS: ** -** {U12252} If a separate thread makes changes on the same database connection +** {A12252} If a separate thread makes changes on the same database connection ** while [sqlite3_changes()] is running then the value returned -** is unpredictable and unmeaningful. +** is unpredictable and not meaningful. */ int sqlite3_changes(sqlite3*); /* -** CAPI3REF: Total Number Of Rows Modified {F12260} -*** -** This function returns the number of row changes caused -** by INSERT, UPDATE or DELETE statements since the database handle -** was opened. The count includes all changes from all trigger -** contexts. But the count does not include changes used to -** implement REPLACE constraints, do rollbacks or ABORT processing, -** or DROP table processing. -** The changes -** are counted as soon as the statement that makes them is completed -** (when the statement handle is passed to [sqlite3_reset()] or +** CAPI3REF: Total Number Of Rows Modified {H12260} <S10600> +** +** This function returns the number of row changes caused by INSERT, +** UPDATE or DELETE statements since the [database connection] was opened. +** The count includes all changes from all trigger contexts. However, +** the count does not include changes used to implement REPLACE constraints, +** do rollbacks or ABORT processing, or DROP table processing. +** The changes are counted as soon as the statement that makes them is +** completed (when the statement handle is passed to [sqlite3_reset()] or ** [sqlite3_finalize()]). ** -** SQLite implements the command "DELETE FROM table" without -** a WHERE clause by dropping and recreating the table. (This is much -** faster than going -** through and deleting individual elements from the table.) Because of -** this optimization, the change count for "DELETE FROM table" will be -** zero regardless of the number of elements that were originally in the -** table. To get an accurate count of the number of rows deleted, use +** SQLite implements the command "DELETE FROM table" without a WHERE clause +** by dropping and recreating the table. (This is much faster than going +** through and deleting individual elements from the table.) Because of this +** optimization, the deletions in "DELETE FROM table" are not row changes and +** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()] +** functions, regardless of the number of elements that were originally +** in the table. To get an accurate count of the number of rows deleted, use ** "DELETE FROM table WHERE 1" instead. ** ** See also the [sqlite3_changes()] interface. ** ** INVARIANTS: -** -** {F12261} The [sqlite3_total_changes()] returns the total number +** +** {H12261} The [sqlite3_total_changes()] returns the total number ** of row changes caused by INSERT, UPDATE, and/or DELETE ** statements on the same [database connection], in any -** trigger context, since the database connection was -** created. +** trigger context, since the database connection was created. +** +** {H12263} Statements of the form "DELETE FROM tablename" with no +** WHERE clause shall not change the value returned +** by [sqlite3_total_changes()]. ** -** LIMITATIONS: +** ASSUMPTIONS: ** -** {U12264} If a separate thread makes changes on the same database connection -** while [sqlite3_total_changes()] is running then the value -** returned is unpredictable and unmeaningful. +** {A12264} If a separate thread makes changes on the same database connection +** while [sqlite3_total_changes()] is running then the value +** returned is unpredictable and not meaningful. */ int sqlite3_total_changes(sqlite3*); /* -** CAPI3REF: Interrupt A Long-Running Query {F12270} +** CAPI3REF: Interrupt A Long-Running Query {H12270} <S30500> ** ** This function causes any pending database operation to abort and ** return at its earliest opportunity. This routine is typically @@ -1022,38 +1420,39 @@ int sqlite3_total_changes(sqlite3*); ** ** It is safe to call this routine from a thread different from the ** thread that is currently running the database operation. But it -** is not safe to call this routine with a database connection that +** is not safe to call this routine with a [database connection] that ** is closed or might close before sqlite3_interrupt() returns. ** -** If an SQL is very nearly finished at the time when sqlite3_interrupt() -** is called, then it might not have an opportunity to be interrupted. -** It might continue to completion. -** An SQL operation that is interrupted will return -** [SQLITE_INTERRUPT]. If the interrupted SQL operation is an -** INSERT, UPDATE, or DELETE that is inside an explicit transaction, -** then the entire transaction will be rolled back automatically. +** If an SQL operation is very nearly finished at the time when +** sqlite3_interrupt() is called, then it might not have an opportunity +** to be interrupted and might continue to completion. +** +** An SQL operation that is interrupted will return [SQLITE_INTERRUPT]. +** If the interrupted SQL operation is an INSERT, UPDATE, or DELETE +** that is inside an explicit transaction, then the entire transaction +** will be rolled back automatically. +** ** A call to sqlite3_interrupt() has no effect on SQL statements ** that are started after sqlite3_interrupt() returns. ** ** INVARIANTS: ** -** {F12271} The [sqlite3_interrupt()] interface will force all running +** {H12271} The [sqlite3_interrupt()] interface will force all running ** SQL statements associated with the same database connection -** to halt after processing at most one additional row of -** data. +** to halt after processing at most one additional row of data. ** -** {F12272} Any SQL statement that is interrupted by [sqlite3_interrupt()] +** {H12272} Any SQL statement that is interrupted by [sqlite3_interrupt()] ** will return [SQLITE_INTERRUPT]. ** -** LIMITATIONS: +** ASSUMPTIONS: ** -** {U12279} If the database connection closes while [sqlite3_interrupt()] +** {A12279} If the database connection closes while [sqlite3_interrupt()] ** is running then bad things will likely happen. */ void sqlite3_interrupt(sqlite3*); /* -** CAPI3REF: Determine If An SQL Statement Is Complete {F10510} +** CAPI3REF: Determine If An SQL Statement Is Complete {H10510} <S70200> ** ** These routines are useful for command-line input to determine if the ** currently entered text seems to form complete a SQL statement or @@ -1066,54 +1465,56 @@ void sqlite3_interrupt(sqlite3*); ** independent tokens (they are part of the token in which they are ** embedded) and thus do not count as a statement terminator. ** -** These routines do not parse the SQL and -** so will not detect syntactically incorrect SQL. +** These routines do not parse the SQL statements thus +** will not detect syntactically incorrect SQL. ** ** INVARIANTS: ** -** {F10511} The sqlite3_complete() and sqlite3_complete16() functions -** return true (non-zero) if and only if the last -** non-whitespace token in their input is a semicolon that -** is not in between the BEGIN and END of a CREATE TRIGGER -** statement. +** {H10511} A successful evaluation of [sqlite3_complete()] or +** [sqlite3_complete16()] functions shall +** return a numeric 1 if and only if the last non-whitespace +** token in their input is a semicolon that is not in between +** the BEGIN and END of a CREATE TRIGGER statement. +** +** {H10512} If a memory allocation error occurs during an invocation +** of [sqlite3_complete()] or [sqlite3_complete16()] then the +** routine shall return [SQLITE_NOMEM]. ** -** LIMITATIONS: +** ASSUMPTIONS: ** -** {U10512} The input to sqlite3_complete() must be a zero-terminated +** {A10512} The input to [sqlite3_complete()] must be a zero-terminated ** UTF-8 string. ** -** {U10513} The input to sqlite3_complete16() must be a zero-terminated +** {A10513} The input to [sqlite3_complete16()] must be a zero-terminated ** UTF-16 string in native byte order. */ int sqlite3_complete(const char *sql); int sqlite3_complete16(const void *sql); /* -** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {F12310} -** -** This routine identifies a callback function that might be -** invoked whenever an attempt is made to open a database table -** that another thread or process has locked. -** If the busy callback is NULL, then [SQLITE_BUSY] -** or [SQLITE_IOERR_BLOCKED] -** is returned immediately upon encountering the lock. -** If the busy callback is not NULL, then the -** callback will be invoked with two arguments. The -** first argument to the handler is a copy of the void* pointer which -** is the third argument to this routine. The second argument to -** the handler is the number of times that the busy handler has -** been invoked for this locking event. If the +** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {H12310} <S40400> +** +** This routine sets a callback function that might be invoked whenever +** an attempt is made to open a database table that another thread +** or process has locked. +** +** If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] +** is returned immediately upon encountering the lock. If the busy callback +** is not NULL, then the callback will be invoked with two arguments. +** +** The first argument to the handler is a copy of the void* pointer which +** is the third argument to sqlite3_busy_handler(). The second argument to +** the handler callback is the number of times that the busy handler has +** been invoked for this locking event. If the ** busy callback returns 0, then no additional attempts are made to ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned. ** If the callback returns non-zero, then another attempt ** is made to open the database for reading and the cycle repeats. ** -** The presence of a busy handler does not guarantee that -** it will be invoked when there is lock contention. -** If SQLite determines that invoking the busy handler could result in -** a deadlock, it will go ahead and return [SQLITE_BUSY] or -** [SQLITE_IOERR_BLOCKED] instead of invoking the -** busy handler. +** The presence of a busy handler does not guarantee that it will be invoked +** when there is lock contention. If SQLite determines that invoking the busy +** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY] +** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler. ** Consider a scenario where one process is holding a read lock that ** it is trying to promote to a reserved lock and ** a second process is holding a reserved lock that it is trying @@ -1138,82 +1539,82 @@ int sqlite3_complete16(const void *sql); ** code is promoted from the relatively benign [SQLITE_BUSY] to ** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion ** forces an automatic rollback of the changes. See the -** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError"> +** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError"> ** CorruptionFollowingBusyError</a> wiki page for a discussion of why ** this is important. -** -** There can only be a single busy handler defined for each database -** connection. Setting a new busy handler clears any previous one. -** Note that calling [sqlite3_busy_timeout()] will also set or clear -** the busy handler. +** +** There can only be a single busy handler defined for each +** [database connection]. Setting a new busy handler clears any +** previously set handler. Note that calling [sqlite3_busy_timeout()] +** will also set or clear the busy handler. ** ** INVARIANTS: ** -** {F12311} The [sqlite3_busy_handler()] function replaces the busy handler -** callback in the database connection identified by the 1st -** parameter with a new busy handler identified by the 2nd and 3rd -** parameters. +** {H12311} The [sqlite3_busy_handler(D,C,A)] function shall replace +** busy callback in the [database connection] D with a new +** a new busy handler C and application data pointer A. ** -** {F12312} The default busy handler for new database connections is NULL. +** {H12312} Newly created [database connections] shall have a busy +** handler of NULL. ** -** {F12314} When two or more database connection share a common cache, +** {H12314} When two or more [database connections] share a +** [sqlite3_enable_shared_cache | common cache], ** the busy handler for the database connection currently using -** the cache is invoked when the cache encounters a lock. +** the cache shall be invoked when the cache encounters a lock. ** -** {F12316} If a busy handler callback returns zero, then the SQLite -** interface that provoked the locking event will return -** [SQLITE_BUSY]. +** {H12316} If a busy handler callback returns zero, then the SQLite interface +** that provoked the locking event shall return [SQLITE_BUSY]. ** -** {F12318} SQLite will invokes the busy handler with two argument which +** {H12318} SQLite shall invokes the busy handler with two arguments which ** are a copy of the pointer supplied by the 3rd parameter to ** [sqlite3_busy_handler()] and a count of the number of prior ** invocations of the busy handler for the same locking event. ** -** LIMITATIONS: +** ASSUMPTIONS: ** -** {U12319} A busy handler should not call close the database connection -** or prepared statement that invoked the busy handler. +** {A12319} A busy handler must not close the database connection +** or [prepared statement] that invoked the busy handler. */ int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); /* -** CAPI3REF: Set A Busy Timeout {F12340} +** CAPI3REF: Set A Busy Timeout {H12340} <S40410> ** -** This routine sets a [sqlite3_busy_handler | busy handler] -** that sleeps for a while when a -** table is locked. The handler will sleep multiple times until -** at least "ms" milliseconds of sleeping have been done. {F12343} After -** "ms" milliseconds of sleeping, the handler returns 0 which -** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. +** This routine sets a [sqlite3_busy_handler | busy handler] that sleeps +** for a specified amount of time when a table is locked. The handler +** will sleep multiple times until at least "ms" milliseconds of sleeping +** have accumulated. {H12343} After "ms" milliseconds of sleeping, +** the handler returns 0 which causes [sqlite3_step()] to return +** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. ** ** Calling this routine with an argument less than or equal to zero ** turns off all busy handlers. ** -** There can only be a single busy handler for a particular database -** connection. If another busy handler was defined -** (using [sqlite3_busy_handler()]) prior to calling +** There can only be a single busy handler for a particular +** [database connection] any any given moment. If another busy handler +** was defined (using [sqlite3_busy_handler()]) prior to calling ** this routine, that other busy handler is cleared. ** ** INVARIANTS: ** -** {F12341} The [sqlite3_busy_timeout()] function overrides any prior +** {H12341} The [sqlite3_busy_timeout()] function shall override any prior ** [sqlite3_busy_timeout()] or [sqlite3_busy_handler()] setting -** on the same database connection. +** on the same [database connection]. ** -** {F12343} If the 2nd parameter to [sqlite3_busy_timeout()] is less than -** or equal to zero, then the busy handler is cleared so that +** {H12343} If the 2nd parameter to [sqlite3_busy_timeout()] is less than +** or equal to zero, then the busy handler shall be cleared so that ** all subsequent locking events immediately return [SQLITE_BUSY]. ** -** {F12344} If the 2nd parameter to [sqlite3_busy_timeout()] is a positive -** number N, then a busy handler is set that repeatedly calls -** the xSleep() method in the VFS interface until either the -** lock clears or until the cumulative sleep time reported back -** by xSleep() exceeds N milliseconds. +** {H12344} If the 2nd parameter to [sqlite3_busy_timeout()] is a positive +** number N, then a busy handler shall be set that repeatedly calls +** the xSleep() method in the [sqlite3_vfs | VFS interface] until +** either the lock clears or until the cumulative sleep time +** reported back by xSleep() exceeds N milliseconds. */ int sqlite3_busy_timeout(sqlite3*, int ms); /* -** CAPI3REF: Convenience Routines For Running Queries {F12370} +** CAPI3REF: Convenience Routines For Running Queries {H12370} <S10000> ** ** Definition: A <b>result table</b> is memory data structure created by the ** [sqlite3_get_table()] interface. A result table records the @@ -1224,16 +1625,14 @@ int sqlite3_busy_timeout(sqlite3*, int ms); ** numbers are obtained separately. Let N be the number of rows ** and M be the number of columns. ** -** A result table is an array of pointers to zero-terminated -** UTF-8 strings. There are (N+1)*M elements in the array. -** The first M pointers point to zero-terminated strings that -** contain the names of the columns. -** The remaining entries all point to query results. NULL -** values are give a NULL pointer. All other values are in -** their UTF-8 zero-terminated string representation as returned by -** [sqlite3_column_text()]. +** A result table is an array of pointers to zero-terminated UTF-8 strings. +** There are (N+1)*M elements in the array. The first M pointers point +** to zero-terminated strings that contain the names of the columns. +** The remaining entries all point to query results. NULL values result +** in NULL pointers. All other values are in their UTF-8 zero-terminated +** string representation as returned by [sqlite3_column_text()]. ** -** A result table might consists of one or more memory allocations. +** A result table might consist of one or more memory allocations. ** It is not safe to pass a result table directly to [sqlite3_free()]. ** A result table should be deallocated using [sqlite3_free_table()]. ** @@ -1268,11 +1667,11 @@ int sqlite3_busy_timeout(sqlite3*, int ms); ** string of its 2nd parameter. It returns a result table to the ** pointer given in its 3rd parameter. ** -** After the calling function has finished using the result, it should -** pass the pointer to the result table to sqlite3_free_table() in order to -** release the memory that was malloc-ed. Because of the way the +** After the calling function has finished using the result, it should +** pass the pointer to the result table to sqlite3_free_table() in order to +** release the memory that was malloced. Because of the way the ** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling -** function must not try to call [sqlite3_free()] directly. Only +** function must not try to call [sqlite3_free()] directly. Only ** [sqlite3_free_table()] is able to release the memory properly and safely. ** ** The sqlite3_get_table() interface is implemented as a wrapper around @@ -1280,43 +1679,53 @@ int sqlite3_busy_timeout(sqlite3*, int ms); ** to any internal data structures of SQLite. It uses only the public ** interface defined here. As a consequence, errors that occur in the ** wrapper layer outside of the internal [sqlite3_exec()] call are not -** reflected in subsequent calls to [sqlite3_errcode()] or -** [sqlite3_errmsg()]. +** reflected in subsequent calls to [sqlite3_errcode()] or [sqlite3_errmsg()]. ** ** INVARIANTS: ** -** {F12371} If a [sqlite3_get_table()] fails a memory allocation, then -** it frees the result table under construction, aborts the -** query in process, skips any subsequent queries, sets the -** *resultp output pointer to NULL and returns [SQLITE_NOMEM]. -** -** {F12373} If the ncolumn parameter to [sqlite3_get_table()] is not NULL -** then [sqlite3_get_table()] write the number of columns in the -** result set of the query into *ncolumn if the query is -** successful (if the function returns SQLITE_OK). +** {H12371} If a [sqlite3_get_table()] fails a memory allocation, then +** it shall free the result table under construction, abort the +** query in process, skip any subsequent queries, set the +** *pazResult output pointer to NULL and return [SQLITE_NOMEM]. +** +** {H12373} If the pnColumn parameter to [sqlite3_get_table()] is not NULL +** then a successful invocation of [sqlite3_get_table()] shall +** write the number of columns in the +** result set of the query into *pnColumn. +** +** {H12374} If the pnRow parameter to [sqlite3_get_table()] is not NULL +** then a successful invocation of [sqlite3_get_table()] shall +** writes the number of rows in the +** result set of the query into *pnRow. +** +** {H12376} A successful invocation of [sqlite3_get_table()] that computes +** N rows of result with C columns per row shall make *pazResult +** point to an array of pointers to (N+1)*C strings where the first +** C strings are column names as obtained from +** [sqlite3_column_name()] and the rest are column result values +** obtained from [sqlite3_column_text()]. ** -** {F12374} If the nrow parameter to [sqlite3_get_table()] is not NULL -** then [sqlite3_get_table()] write the number of rows in the -** result set of the query into *nrow if the query is -** successful (if the function returns SQLITE_OK). +** {H12379} The values in the pazResult array returned by [sqlite3_get_table()] +** shall remain valid until cleared by [sqlite3_free_table()]. ** -** {F12376} The [sqlite3_get_table()] function sets its *ncolumn value -** to the number of columns in the result set of the query in the -** sql parameter, or to zero if the query in sql has an empty -** result set. +** {H12382} When an error occurs during evaluation of [sqlite3_get_table()] +** the function shall set *pazResult to NULL, write an error message +** into memory obtained from [sqlite3_malloc()], make +** **pzErrmsg point to that error message, and return a +** appropriate [error code]. */ int sqlite3_get_table( - sqlite3*, /* An open database */ - const char *sql, /* SQL to be evaluated */ - char ***pResult, /* Results of the query */ - int *nrow, /* Number of result rows written here */ - int *ncolumn, /* Number of result columns written here */ - char **errmsg /* Error msg written here */ + sqlite3 *db, /* An open database */ + const char *zSql, /* SQL to be evaluated */ + char ***pazResult, /* Results of the query */ + int *pnRow, /* Number of result rows written here */ + int *pnColumn, /* Number of result columns written here */ + char **pzErrmsg /* Error msg written here */ ); void sqlite3_free_table(char **result); /* -** CAPI3REF: Formatted String Printing Functions {F17400} +** CAPI3REF: Formatted String Printing Functions {H17400} <S70000><S20000> ** ** These routines are workalikes of the "printf()" family of functions ** from the standard C library. @@ -1324,7 +1733,7 @@ void sqlite3_free_table(char **result); ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their ** results into memory obtained from [sqlite3_malloc()]. ** The strings returned by these two routines should be -** released by [sqlite3_free()]. Both routines return a +** released by [sqlite3_free()]. Both routines return a ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough ** memory to hold the resulting string. ** @@ -1349,7 +1758,7 @@ void sqlite3_free_table(char **result); ** ** These routines all implement some additional formatting ** options that are useful for constructing SQL statements. -** All of the usual printf formatting options apply. In addition, there +** All of the usual printf() formatting options apply. In addition, there ** is are "%q", "%Q", and "%z" options. ** ** The %q option works like %s in that it substitutes a null-terminated @@ -1358,7 +1767,7 @@ void sqlite3_free_table(char **result); ** character it escapes that character and allows it to be inserted into ** the string. ** -** For example, so some string variable contains text as follows: +** For example, assume the string variable zText contains text as follows: ** ** <blockquote><pre> ** char *zText = "It's a happy day!"; @@ -1386,14 +1795,13 @@ void sqlite3_free_table(char **result); ** INSERT INTO table1 VALUES('It's a happy day!'); ** </pre></blockquote> ** -** This second example is an SQL syntax error. As a general rule you -** should always use %q instead of %s when inserting text into a string -** literal. +** This second example is an SQL syntax error. As a general rule you should +** always use %q instead of %s when inserting text into a string literal. ** ** The %Q option works like %q except it also adds single quotes around -** the outside of the total string. Or if the parameter in the argument -** list is a NULL pointer, %Q substitutes the text "NULL" (without single -** quotes) in place of the %Q option. {END} So, for example, one could say: +** the outside of the total string. Additionally, if the parameter in the +** argument list is a NULL pointer, %Q substitutes the text "NULL" (without +** single quotes) in place of the %Q option. So, for example, one could say: ** ** <blockquote><pre> ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText); @@ -1410,33 +1818,32 @@ void sqlite3_free_table(char **result); ** ** INVARIANTS: ** -** {F17403} The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces +** {H17403} The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces ** return either pointers to zero-terminated UTF-8 strings held in ** memory obtained from [sqlite3_malloc()] or NULL pointers if ** a call to [sqlite3_malloc()] fails. ** -** {F17406} The [sqlite3_snprintf()] interface writes a zero-terminated +** {H17406} The [sqlite3_snprintf()] interface writes a zero-terminated ** UTF-8 string into the buffer pointed to by the second parameter ** provided that the first parameter is greater than zero. ** -** {F17407} The [sqlite3_snprintf()] interface does not writes slots of +** {H17407} The [sqlite3_snprintf()] interface does not write slots of ** its output buffer (the second parameter) outside the range ** of 0 through N-1 (where N is the first parameter) ** regardless of the length of the string ** requested by the format specification. -** */ char *sqlite3_mprintf(const char*,...); char *sqlite3_vmprintf(const char*, va_list); char *sqlite3_snprintf(int,char*,const char*, ...); /* -** CAPI3REF: Memory Allocation Subsystem {F17300} +** CAPI3REF: Memory Allocation Subsystem {H17300} <S20000> ** ** The SQLite core uses these three routines for all of its own ** internal memory allocation needs. "Core" in the previous sentence ** does not include operating-system specific VFS implementation. The -** windows VFS uses native malloc and free for some operations. +** Windows VFS uses native malloc() and free() for some operations. ** ** The sqlite3_malloc() routine returns a pointer to a block ** of memory at least N bytes in length, where N is the parameter. @@ -1465,7 +1872,7 @@ char *sqlite3_snprintf(int,char*,const char*, ...); ** If the second parameter to sqlite3_realloc() is zero or ** negative then the behavior is exactly the same as calling ** sqlite3_free(P) where P is the first parameter to sqlite3_realloc(). -** Sqlite3_realloc() returns a pointer to a memory allocation +** sqlite3_realloc() returns a pointer to a memory allocation ** of at least N bytes in size or NULL if sufficient memory is unavailable. ** If M is the size of the prior allocation, then min(N,M) bytes ** of the prior allocation are copied into the beginning of buffer returned @@ -1476,128 +1883,123 @@ char *sqlite3_snprintf(int,char*,const char*, ...); ** The memory returned by sqlite3_malloc() and sqlite3_realloc() ** is always aligned to at least an 8 byte boundary. {END} ** -** The default implementation -** of the memory allocation subsystem uses the malloc(), realloc() -** and free() provided by the standard C library. {F17382} However, if -** SQLite is compiled with the following C preprocessor macro -** -** <blockquote> SQLITE_MEMORY_SIZE=<i>NNN</i> </blockquote> -** -** where <i>NNN</i> is an integer, then SQLite create a static -** array of at least <i>NNN</i> bytes in size and use that array -** for all of its dynamic memory allocation needs. {END} Additional -** memory allocator options may be added in future releases. +** The default implementation of the memory allocation subsystem uses +** the malloc(), realloc() and free() provided by the standard C library. +** {H17382} However, if SQLite is compiled with the +** SQLITE_MEMORY_SIZE=<i>NNN</i> C preprocessor macro (where <i>NNN</i> +** is an integer), then SQLite create a static array of at least +** <i>NNN</i> bytes in size and uses that array for all of its dynamic +** memory allocation needs. {END} Additional memory allocator options +** may be added in future releases. ** ** In SQLite version 3.5.0 and 3.5.1, it was possible to define ** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in ** implementation of these routines to be omitted. That capability -** is no longer provided. Only built-in memory allocators can be -** used. +** is no longer provided. Only built-in memory allocators can be used. ** -** The windows OS interface layer calls +** The Windows OS interface layer calls ** the system malloc() and free() directly when converting ** filenames between the UTF-8 encoding used by SQLite -** and whatever filename encoding is used by the particular windows +** and whatever filename encoding is used by the particular Windows ** installation. Memory allocation errors are detected, but ** they are reported back as [SQLITE_CANTOPEN] or ** [SQLITE_IOERR] rather than [SQLITE_NOMEM]. ** ** INVARIANTS: ** -** {F17303} The [sqlite3_malloc(N)] interface returns either a pointer to -** newly checked-out block of at least N bytes of memory -** that is 8-byte aligned, -** or it returns NULL if it is unable to fulfill the request. +** {H17303} The [sqlite3_malloc(N)] interface returns either a pointer to +** a newly checked-out block of at least N bytes of memory +** that is 8-byte aligned, or it returns NULL if it is unable +** to fulfill the request. ** -** {F17304} The [sqlite3_malloc(N)] interface returns a NULL pointer if +** {H17304} The [sqlite3_malloc(N)] interface returns a NULL pointer if ** N is less than or equal to zero. ** -** {F17305} The [sqlite3_free(P)] interface releases memory previously +** {H17305} The [sqlite3_free(P)] interface releases memory previously ** returned from [sqlite3_malloc()] or [sqlite3_realloc()], ** making it available for reuse. ** -** {F17306} A call to [sqlite3_free(NULL)] is a harmless no-op. +** {H17306} A call to [sqlite3_free(NULL)] is a harmless no-op. ** -** {F17310} A call to [sqlite3_realloc(0,N)] is equivalent to a call +** {H17310} A call to [sqlite3_realloc(0,N)] is equivalent to a call ** to [sqlite3_malloc(N)]. ** -** {F17312} A call to [sqlite3_realloc(P,0)] is equivalent to a call +** {H17312} A call to [sqlite3_realloc(P,0)] is equivalent to a call ** to [sqlite3_free(P)]. ** -** {F17315} The SQLite core uses [sqlite3_malloc()], [sqlite3_realloc()], +** {H17315} The SQLite core uses [sqlite3_malloc()], [sqlite3_realloc()], ** and [sqlite3_free()] for all of its memory allocation and ** deallocation needs. ** -** {F17318} The [sqlite3_realloc(P,N)] interface returns either a pointer +** {H17318} The [sqlite3_realloc(P,N)] interface returns either a pointer ** to a block of checked-out memory of at least N bytes in size ** that is 8-byte aligned, or a NULL pointer. ** -** {F17321} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first -** copies the first K bytes of content from P into the newly allocated -** where K is the lessor of N and the size of the buffer P. +** {H17321} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first +** copies the first K bytes of content from P into the newly +** allocated block, where K is the lesser of N and the size of +** the buffer P. ** -** {F17322} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first +** {H17322} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first ** releases the buffer P. ** -** {F17323} When [sqlite3_realloc(P,N)] returns NULL, the buffer P is +** {H17323} When [sqlite3_realloc(P,N)] returns NULL, the buffer P is ** not modified or released. ** -** LIMITATIONS: +** ASSUMPTIONS: ** -** {U17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] -** must be either NULL or else a pointer obtained from a prior -** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that has -** not been released. +** {A17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] +** must be either NULL or else pointers obtained from a prior +** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have +** not yet been released. ** -** {U17351} The application must not read or write any part of +** {A17351} The application must not read or write any part of ** a block of memory after it has been released using ** [sqlite3_free()] or [sqlite3_realloc()]. -** */ void *sqlite3_malloc(int); void *sqlite3_realloc(void*, int); void sqlite3_free(void*); /* -** CAPI3REF: Memory Allocator Statistics {F17370} +** CAPI3REF: Memory Allocator Statistics {H17370} <S30210> ** ** SQLite provides these two interfaces for reporting on the status ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()] -** the memory allocation subsystem included within the SQLite. +** routines, which form the built-in memory allocation subsystem. ** ** INVARIANTS: ** -** {F17371} The [sqlite3_memory_used()] routine returns the -** number of bytes of memory currently outstanding -** (malloced but not freed). +** {H17371} The [sqlite3_memory_used()] routine returns the number of bytes +** of memory currently outstanding (malloced but not freed). ** -** {F17373} The [sqlite3_memory_highwater()] routine returns the maximum -** value of [sqlite3_memory_used()] -** since the highwater mark was last reset. +** {H17373} The [sqlite3_memory_highwater()] routine returns the maximum +** value of [sqlite3_memory_used()] since the high-water mark +** was last reset. ** -** {F17374} The values returned by [sqlite3_memory_used()] and +** {H17374} The values returned by [sqlite3_memory_used()] and ** [sqlite3_memory_highwater()] include any overhead ** added by SQLite in its implementation of [sqlite3_malloc()], ** but not overhead added by the any underlying system library ** routines that [sqlite3_malloc()] may call. -** -** {F17375} The memory highwater mark is reset to the current value of +** +** {H17375} The memory high-water mark is reset to the current value of ** [sqlite3_memory_used()] if and only if the parameter to ** [sqlite3_memory_highwater()] is true. The value returned -** by [sqlite3_memory_highwater(1)] is the highwater mark +** by [sqlite3_memory_highwater(1)] is the high-water mark ** prior to the reset. */ sqlite3_int64 sqlite3_memory_used(void); sqlite3_int64 sqlite3_memory_highwater(int resetFlag); /* -** CAPI3REF: Pseudo-Random Number Generator {F17390} +** CAPI3REF: Pseudo-Random Number Generator {H17390} <S20000> ** ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to ** select random ROWIDs when inserting new records into a table that ** already uses the largest possible ROWID. The PRNG is also used for ** the build-in random() and randomblob() SQL functions. This interface allows -** appliations to access the same PRNG for other purposes. +** applications to access the same PRNG for other purposes. ** ** A call to this routine stores N bytes of randomness into buffer P. ** @@ -1610,13 +2012,13 @@ sqlite3_int64 sqlite3_memory_highwater(int resetFlag); ** ** INVARIANTS: ** -** {F17392} The [sqlite3_randomness(N,P)] interface writes N bytes of +** {H17392} The [sqlite3_randomness(N,P)] interface writes N bytes of ** high-quality pseudo-randomness into buffer P. */ void sqlite3_randomness(int N, void *P); /* -** CAPI3REF: Compile-Time Authorization Callbacks {F12500} +** CAPI3REF: Compile-Time Authorization Callbacks {H12500} <S70100> ** ** This routine registers a authorizer callback with a particular ** [database connection], supplied in the first argument. @@ -1629,9 +2031,9 @@ void sqlite3_randomness(int N, void *P); ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the ** specific action but allow the SQL statement to continue to be ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be -** rejected with an error. If the authorizer callback returns +** rejected with an error. If the authorizer callback returns ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] -** then [sqlite3_prepare_v2()] or equivalent call that triggered +** then the [sqlite3_prepare_v2()] or equivalent call that triggered ** the authorizer will fail with an error message. ** ** When the callback returns [SQLITE_OK], that means the operation @@ -1646,19 +2048,17 @@ void sqlite3_randomness(int N, void *P); ** return can be used to deny an untrusted user access to individual ** columns of a table. ** -** The first parameter to the authorizer callback is a copy of -** the third parameter to the sqlite3_set_authorizer() interface. -** The second parameter to the callback is an integer -** [SQLITE_COPY | action code] that specifies the particular action -** to be authorized. The third through sixth -** parameters to the callback are zero-terminated strings that contain -** additional details about the action to be authorized. +** The first parameter to the authorizer callback is a copy of the third +** parameter to the sqlite3_set_authorizer() interface. The second parameter +** to the callback is an integer [SQLITE_COPY | action code] that specifies +** the particular action to be authorized. The third through sixth parameters +** to the callback are zero-terminated strings that contain additional +** details about the action to be authorized. ** ** An authorizer is used when [sqlite3_prepare | preparing] -** SQL statements from an untrusted -** source, to ensure that the SQL statements do not try to access data -** that they are not allowed to see, or that they do not try to -** execute malicious statements that damage the database. For +** SQL statements from an untrusted source, to ensure that the SQL statements +** do not try to access data they are not allowed to see, or that they do not +** try to execute malicious statements that damage the database. For ** example, an application may allow a user to enter arbitrary ** SQL queries for evaluation by a database. But the application does ** not want the user to be able to make arbitrary changes to the @@ -1676,61 +2076,61 @@ void sqlite3_randomness(int N, void *P); ** previous call. Disable the authorizer by installing a NULL callback. ** The authorizer is disabled by default. ** -** Note that the authorizer callback is invoked only during +** Note that the authorizer callback is invoked only during ** [sqlite3_prepare()] or its variants. Authorization is not ** performed during statement evaluation in [sqlite3_step()]. ** ** INVARIANTS: ** -** {F12501} The [sqlite3_set_authorizer(D,...)] interface registers a +** {H12501} The [sqlite3_set_authorizer(D,...)] interface registers a ** authorizer callback with database connection D. ** -** {F12502} The authorizer callback is invoked as SQL statements are -** being compiled +** {H12502} The authorizer callback is invoked as SQL statements are +** being compiled. ** -** {F12503} If the authorizer callback returns any value other than -** [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] then +** {H12503} If the authorizer callback returns any value other than +** [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY], then ** the [sqlite3_prepare_v2()] or equivalent call that caused ** the authorizer callback to run shall fail with an ** [SQLITE_ERROR] error code and an appropriate error message. ** -** {F12504} When the authorizer callback returns [SQLITE_OK], the operation -** described is coded normally. +** {H12504} When the authorizer callback returns [SQLITE_OK], the operation +** described is processed normally. ** -** {F12505} When the authorizer callback returns [SQLITE_DENY], the +** {H12505} When the authorizer callback returns [SQLITE_DENY], the ** [sqlite3_prepare_v2()] or equivalent call that caused the ** authorizer callback to run shall fail ** with an [SQLITE_ERROR] error code and an error message ** explaining that access is denied. ** -** {F12506} If the authorizer code (the 2nd parameter to the authorizer +** {H12506} If the authorizer code (the 2nd parameter to the authorizer ** callback) is [SQLITE_READ] and the authorizer callback returns -** [SQLITE_IGNORE] then the prepared statement is constructed to +** [SQLITE_IGNORE], then the prepared statement is constructed to ** insert a NULL value in place of the table column that would have ** been read if [SQLITE_OK] had been returned. ** -** {F12507} If the authorizer code (the 2nd parameter to the authorizer +** {H12507} If the authorizer code (the 2nd parameter to the authorizer ** callback) is anything other than [SQLITE_READ], then -** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY]. +** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY]. ** -** {F12510} The first parameter to the authorizer callback is a copy of +** {H12510} The first parameter to the authorizer callback is a copy of ** the third parameter to the [sqlite3_set_authorizer()] interface. ** -** {F12511} The second parameter to the callback is an integer +** {H12511} The second parameter to the callback is an integer ** [SQLITE_COPY | action code] that specifies the particular action ** to be authorized. ** -** {F12512} The third through sixth parameters to the callback are -** zero-terminated strings that contain +** {H12512} The third through sixth parameters to the callback are +** zero-terminated strings that contain ** additional details about the action to be authorized. ** -** {F12520} Each call to [sqlite3_set_authorizer()] overrides the +** {H12520} Each call to [sqlite3_set_authorizer()] overrides ** any previously installed authorizer. ** -** {F12521} A NULL authorizer means that no authorization +** {H12521} A NULL authorizer means that no authorization ** callback is invoked. ** -** {F12522} The default authorizer is NULL. +** {H12522} The default authorizer is NULL. */ int sqlite3_set_authorizer( sqlite3*, @@ -1739,7 +2139,7 @@ int sqlite3_set_authorizer( ); /* -** CAPI3REF: Authorizer Return Codes {F12590} +** CAPI3REF: Authorizer Return Codes {H12590} <H12500> ** ** The [sqlite3_set_authorizer | authorizer callback function] must ** return either [SQLITE_OK] or one of these two constants in order @@ -1751,44 +2151,44 @@ int sqlite3_set_authorizer( #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ /* -** CAPI3REF: Authorizer Action Codes {F12550} +** CAPI3REF: Authorizer Action Codes {H12550} <H12500> ** ** The [sqlite3_set_authorizer()] interface registers a callback function -** that is invoked to authorizer certain SQL statement actions. The +** that is invoked to authorize certain SQL statement actions. The ** second parameter to the callback is an integer code that specifies ** what action is being authorized. These are the integer action codes that ** the authorizer callback may be passed. ** -** These action code values signify what kind of operation is to be +** These action code values signify what kind of operation is to be ** authorized. The 3rd and 4th parameters to the authorization ** callback function will be parameters or NULL depending on which of these ** codes is used as the second parameter. The 5th parameter to the -** authorizer callback is the name of the database ("main", "temp", +** authorizer callback is the name of the database ("main", "temp", ** etc.) if applicable. The 6th parameter to the authorizer callback ** is the name of the inner-most trigger or view that is responsible for -** the access attempt or NULL if this access attempt is directly from +** the access attempt or NULL if this access attempt is directly from ** top-level SQL code. ** ** INVARIANTS: ** -** {F12551} The second parameter to an -** [sqlite3_set_authorizer | authorizer callback is always an integer +** {H12551} The second parameter to an +** [sqlite3_set_authorizer | authorizer callback] is always an integer ** [SQLITE_COPY | authorizer code] that specifies what action ** is being authorized. ** -** {F12552} The 3rd and 4th parameters to the -** [sqlite3_set_authorizer | authorization callback function] -** will be parameters or NULL depending on which +** {H12552} The 3rd and 4th parameters to the +** [sqlite3_set_authorizer | authorization callback] +** will be parameters or NULL depending on which ** [SQLITE_COPY | authorizer code] is used as the second parameter. ** -** {F12553} The 5th parameter to the +** {H12553} The 5th parameter to the ** [sqlite3_set_authorizer | authorizer callback] is the name ** of the database (example: "main", "temp", etc.) if applicable. ** -** {F12554} The 6th parameter to the +** {H12554} The 6th parameter to the ** [sqlite3_set_authorizer | authorizer callback] is the name ** of the inner-most trigger or view that is responsible for -** the access attempt or NULL if this access attempt is directly from +** the access attempt or NULL if this access attempt is directly from ** top-level SQL code. */ /******************************************* 3rd ************ 4th ***********/ @@ -1826,7 +2226,8 @@ int sqlite3_set_authorizer( #define SQLITE_COPY 0 /* No longer used */ /* -** CAPI3REF: Tracing And Profiling Functions {F12280} +** CAPI3REF: Tracing And Profiling Functions {H12280} <S60400> +** EXPERIMENTAL ** ** These routines register callback functions that can be used for ** tracing and profiling the execution of SQL statements. @@ -1835,54 +2236,46 @@ int sqlite3_set_authorizer( ** various times when an SQL statement is being run by [sqlite3_step()]. ** The callback returns a UTF-8 rendering of the SQL statement text ** as the statement first begins executing. Additional callbacks occur -** as each triggersubprogram is entered. The callbacks for triggers +** as each triggered subprogram is entered. The callbacks for triggers ** contain a UTF-8 SQL comment that identifies the trigger. -** +** ** The callback function registered by sqlite3_profile() is invoked ** as each SQL statement finishes. The profile callback contains ** the original statement text and an estimate of wall-clock time ** of how long that statement took to run. ** -** The sqlite3_profile() API is currently considered experimental and -** is subject to change or removal in a future release. -** -** The trigger reporting feature of the trace callback is considered -** experimental and is subject to change or removal in future releases. -** Future versions of SQLite might also add new trace callback -** invocations. -** ** INVARIANTS: ** -** {F12281} The callback function registered by [sqlite3_trace()] is +** {H12281} The callback function registered by [sqlite3_trace()] is ** whenever an SQL statement first begins to execute and ** whenever a trigger subprogram first begins to run. ** -** {F12282} Each call to [sqlite3_trace()] overrides the previously +** {H12282} Each call to [sqlite3_trace()] overrides the previously ** registered trace callback. ** -** {F12283} A NULL trace callback disables tracing. +** {H12283} A NULL trace callback disables tracing. ** -** {F12284} The first argument to the trace callback is a copy of +** {H12284} The first argument to the trace callback is a copy of ** the pointer which was the 3rd argument to [sqlite3_trace()]. ** -** {F12285} The second argument to the trace callback is a -** zero-terminated UTF8 string containing the original text +** {H12285} The second argument to the trace callback is a +** zero-terminated UTF-8 string containing the original text ** of the SQL statement as it was passed into [sqlite3_prepare_v2()] ** or the equivalent, or an SQL comment indicating the beginning ** of a trigger subprogram. ** -** {F12287} The callback function registered by [sqlite3_profile()] is invoked +** {H12287} The callback function registered by [sqlite3_profile()] is invoked ** as each SQL statement finishes. ** -** {F12288} The first parameter to the profile callback is a copy of +** {H12288} The first parameter to the profile callback is a copy of ** the 3rd parameter to [sqlite3_profile()]. ** -** {F12289} The second parameter to the profile callback is a +** {H12289} The second parameter to the profile callback is a ** zero-terminated UTF-8 string that contains the complete text of ** the SQL statement as it was processed by [sqlite3_prepare_v2()] ** or the equivalent. ** -** {F12290} The third parameter to the profile callback is an estimate +** {H12290} The third parameter to the profile callback is an estimate ** of the number of nanoseconds of wall-clock time required to ** run the SQL statement from start to finish. */ @@ -1891,189 +2284,199 @@ void *sqlite3_profile(sqlite3*, void(*xProfile)(void*,const char*,sqlite3_uint64), void*); /* -** CAPI3REF: Query Progress Callbacks {F12910} +** CAPI3REF: Query Progress Callbacks {H12910} <S60400> ** ** This routine configures a callback function - the ** progress callback - that is invoked periodically during long ** running calls to [sqlite3_exec()], [sqlite3_step()] and -** [sqlite3_get_table()]. An example use for this +** [sqlite3_get_table()]. An example use for this ** interface is to keep a GUI updated during a large query. ** -** If the progress callback returns non-zero, the opertion is +** If the progress callback returns non-zero, the operation is ** interrupted. This feature can be used to implement a ** "Cancel" button on a GUI dialog box. ** ** INVARIANTS: ** -** {F12911} The callback function registered by [sqlite3_progress_handler()] +** {H12911} The callback function registered by sqlite3_progress_handler() ** is invoked periodically during long running calls to ** [sqlite3_step()]. ** -** {F12912} The progress callback is invoked once for every N virtual -** machine opcodes, where N is the second argument to +** {H12912} The progress callback is invoked once for every N virtual +** machine opcodes, where N is the second argument to ** the [sqlite3_progress_handler()] call that registered -** the callback. <todo>What if N is less than 1?</todo> +** the callback. If N is less than 1, sqlite3_progress_handler() +** acts as if a NULL progress handler had been specified. ** -** {F12913} The progress callback itself is identified by the third -** argument to [sqlite3_progress_handler()]. +** {H12913} The progress callback itself is identified by the third +** argument to sqlite3_progress_handler(). ** -** {F12914} The fourth argument [sqlite3_progress_handler()] is a -*** void pointer passed to the progress callback +** {H12914} The fourth argument to sqlite3_progress_handler() is a +** void pointer passed to the progress callback ** function each time it is invoked. ** -** {F12915} If a call to [sqlite3_step()] results in fewer than -** N opcodes being executed, -** then the progress callback is never invoked. {END} -** -** {F12916} Every call to [sqlite3_progress_handler()] -** overwrites any previously registere progress handler. +** {H12915} If a call to [sqlite3_step()] results in fewer than N opcodes +** being executed, then the progress callback is never invoked. ** -** {F12917} If the progress handler callback is NULL then no progress +** {H12916} Every call to [sqlite3_progress_handler()] +** overwrites any previously registered progress handler. +** +** {H12917} If the progress handler callback is NULL then no progress ** handler is invoked. ** -** {F12918} If the progress callback returns a result other than 0, then +** {H12918} If the progress callback returns a result other than 0, then ** the behavior is a if [sqlite3_interrupt()] had been called. +** <S30500> */ void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); /* -** CAPI3REF: Opening A New Database Connection {F12700} -** -** These routines open an SQLite database file whose name -** is given by the filename argument. -** The filename argument is interpreted as UTF-8 -** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16 -** in the native byte order for [sqlite3_open16()]. -** An [sqlite3*] handle is usually returned in *ppDb, even -** if an error occurs. The only exception is if SQLite is unable -** to allocate memory to hold the [sqlite3] object, a NULL will -** be written into *ppDb instead of a pointer to the [sqlite3] object. -** If the database is opened (and/or created) -** successfully, then [SQLITE_OK] is returned. Otherwise an -** error code is returned. The -** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain +** CAPI3REF: Opening A New Database Connection {H12700} <S40200> +** +** These routines open an SQLite database file whose name is given by the +** filename argument. The filename argument is interpreted as UTF-8 for +** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte +** order for sqlite3_open16(). A [database connection] handle is usually +** returned in *ppDb, even if an error occurs. The only exception is that +** if SQLite is unable to allocate memory to hold the [sqlite3] object, +** a NULL will be written into *ppDb instead of a pointer to the [sqlite3] +** object. If the database is opened (and/or created) successfully, then +** [SQLITE_OK] is returned. Otherwise an [error code] is returned. The +** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain ** an English language description of the error. ** ** The default encoding for the database will be UTF-8 if -** [sqlite3_open()] or [sqlite3_open_v2()] is called and -** UTF-16 in the native byte order if [sqlite3_open16()] is used. +** sqlite3_open() or sqlite3_open_v2() is called and +** UTF-16 in the native byte order if sqlite3_open16() is used. ** ** Whether or not an error occurs when it is opened, resources -** associated with the [sqlite3*] handle should be released by passing it -** to [sqlite3_close()] when it is no longer required. +** associated with the [database connection] handle should be released by +** passing it to [sqlite3_close()] when it is no longer required. ** -** The [sqlite3_open_v2()] interface works like [sqlite3_open()] -** except that it acccepts two additional parameters for additional control -** over the new database connection. The flags parameter can be -** one of: +** The sqlite3_open_v2() interface works like sqlite3_open() +** except that it accepts two additional parameters for additional control +** over the new database connection. The flags parameter can take one of +** the following three values, optionally combined with the +** [SQLITE_OPEN_NOMUTEX] flag: ** -** <ol> -** <li> [SQLITE_OPEN_READONLY] -** <li> [SQLITE_OPEN_READWRITE] -** <li> [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE] -** </ol> +** <dl> +** <dt>[SQLITE_OPEN_READONLY]</dt> +** <dd>The database is opened in read-only mode. If the database does not +** already exist, an error is returned.</dd> +** +** <dt>[SQLITE_OPEN_READWRITE]</dt> +** <dd>The database is opened for reading and writing if possible, or reading +** only if the file is write protected by the operating system. In either +** case the database must already exist, otherwise an error is returned.</dd> +** +** <dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt> +** <dd>The database is opened for reading and writing, and is creates it if +** it does not already exist. This is the behavior that is always used for +** sqlite3_open() and sqlite3_open16().</dd> +** </dl> ** -** The first value opens the database read-only. -** If the database does not previously exist, an error is returned. -** The second option opens -** the database for reading and writing if possible, or reading only if -** if the file is write protected. In either case the database -** must already exist or an error is returned. The third option -** opens the database for reading and writing and creates it if it does -** not already exist. -** The third options is behavior that is always used for [sqlite3_open()] -** and [sqlite3_open16()]. -** -** If the 3rd parameter to [sqlite3_open_v2()] is not one of the -** combinations shown above then the behavior is undefined. -** -** If the filename is ":memory:", then an private -** in-memory database is created for the connection. This in-memory -** database will vanish when the database connection is closed. Future -** version of SQLite might make use of additional special filenames -** that begin with the ":" character. It is recommended that -** when a database filename really does begin with -** ":" that you prefix the filename with a pathname like "./" to -** avoid ambiguity. -** -** If the filename is an empty string, then a private temporary +** If the 3rd parameter to sqlite3_open_v2() is not one of the +** combinations shown above or one of the combinations shown above combined +** with the [SQLITE_OPEN_NOMUTEX] flag, then the behavior is undefined. +** +** If the [SQLITE_OPEN_NOMUTEX] flag is set, then mutexes on the +** opened [database connection] are disabled and the appliation must +** insure that access to the [database connection] and its associated +** [prepared statements] is serialized. The [SQLITE_OPEN_NOMUTEX] flag +** is the default behavior is SQLite is configured using the +** [SQLITE_CONFIG_MULTITHREAD] or [SQLITE_CONFIG_SINGLETHREAD] options +** to [sqlite3_config()]. The [SQLITE_OPEN_NOMUTEX] flag only makes a +** difference when SQLite is in its default [SQLITE_CONFIG_SERIALIZED] mode. +** +** If the filename is ":memory:", then a private, temporary in-memory database +** is created for the connection. This in-memory database will vanish when +** the database connection is closed. Future versions of SQLite might +** make use of additional special filenames that begin with the ":" character. +** It is recommended that when a database filename actually does begin with +** a ":" character you should prefix the filename with a pathname such as +** "./" to avoid ambiguity. +** +** If the filename is an empty string, then a private, temporary ** on-disk database will be created. This private database will be ** automatically deleted as soon as the database connection is closed. ** ** The fourth parameter to sqlite3_open_v2() is the name of the -** [sqlite3_vfs] object that defines the operating system -** interface that the new database connection should use. If the -** fourth parameter is a NULL pointer then the default [sqlite3_vfs] -** object is used. +** [sqlite3_vfs] object that defines the operating system interface that +** the new database connection should use. If the fourth parameter is +** a NULL pointer then the default [sqlite3_vfs] object is used. ** -** <b>Note to windows users:</b> The encoding used for the filename argument -** of [sqlite3_open()] and [sqlite3_open_v2()] must be UTF-8, not whatever +** <b>Note to Windows users:</b> The encoding used for the filename argument +** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever ** codepage is currently defined. Filenames containing international ** characters must be converted to UTF-8 prior to passing them into -** [sqlite3_open()] or [sqlite3_open_v2()]. +** sqlite3_open() or sqlite3_open_v2(). ** ** INVARIANTS: ** -** {F12701} The [sqlite3_open()], [sqlite3_open16()], and +** {H12701} The [sqlite3_open()], [sqlite3_open16()], and ** [sqlite3_open_v2()] interfaces create a new ** [database connection] associated with ** the database file given in their first parameter. ** -** {F12702} The filename argument is interpreted as UTF-8 +** {H12702} The filename argument is interpreted as UTF-8 ** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16 ** in the native byte order for [sqlite3_open16()]. ** -** {F12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()], +** {H12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()], ** or [sqlite3_open_v2()] writes a pointer to a new ** [database connection] into *ppDb. ** -** {F12704} The [sqlite3_open()], [sqlite3_open16()], and +** {H12704} The [sqlite3_open()], [sqlite3_open16()], and ** [sqlite3_open_v2()] interfaces return [SQLITE_OK] upon success, ** or an appropriate [error code] on failure. ** -** {F12706} The default text encoding for a new database created using +** {H12706} The default text encoding for a new database created using ** [sqlite3_open()] or [sqlite3_open_v2()] will be UTF-8. ** -** {F12707} The default text encoding for a new database created using +** {H12707} The default text encoding for a new database created using ** [sqlite3_open16()] will be UTF-16. ** -** {F12709} The [sqlite3_open(F,D)] interface is equivalent to +** {H12709} The [sqlite3_open(F,D)] interface is equivalent to ** [sqlite3_open_v2(F,D,G,0)] where the G parameter is ** [SQLITE_OPEN_READWRITE]|[SQLITE_OPEN_CREATE]. ** -** {F12711} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the +** {H12711} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the ** bit value [SQLITE_OPEN_READONLY] then the database is opened ** for reading only. ** -** {F12712} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the +** {H12712} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the ** bit value [SQLITE_OPEN_READWRITE] then the database is opened ** reading and writing if possible, or for reading only if the ** file is write protected by the operating system. ** -** {F12713} If the G parameter to [sqlite3_open(v2(F,D,G,V)] omits the +** {H12713} If the G parameter to [sqlite3_open(v2(F,D,G,V)] omits the ** bit value [SQLITE_OPEN_CREATE] and the database does not ** previously exist, an error is returned. ** -** {F12714} If the G parameter to [sqlite3_open(v2(F,D,G,V)] contains the +** {H12714} If the G parameter to [sqlite3_open(v2(F,D,G,V)] contains the ** bit value [SQLITE_OPEN_CREATE] and the database does not ** previously exist, then an attempt is made to create and ** initialize the database. ** -** {F12717} If the filename argument to [sqlite3_open()], [sqlite3_open16()], +** {H12717} If the filename argument to [sqlite3_open()], [sqlite3_open16()], ** or [sqlite3_open_v2()] is ":memory:", then an private, ** ephemeral, in-memory database is created for the connection. ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required ** in sqlite3_open_v2()?</todo> ** -** {F12719} If the filename is NULL or an empty string, then a private, -** ephermeral on-disk database will be created. +** {H12719} If the filename is NULL or an empty string, then a private, +** ephemeral on-disk database will be created. ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required ** in sqlite3_open_v2()?</todo> ** -** {F12721} The [database connection] created by -** [sqlite3_open_v2(F,D,G,V)] will use the -** [sqlite3_vfs] object identified by the V parameter, or -** the default [sqlite3_vfs] object is V is a NULL pointer. +** {H12721} The [database connection] created by [sqlite3_open_v2(F,D,G,V)] +** will use the [sqlite3_vfs] object identified by the V parameter, +** or the default [sqlite3_vfs] object if V is a NULL pointer. +** +** {H12723} Two [database connections] will share a common cache if both were +** opened with the same VFS while [shared cache mode] was enabled and +** if both filenames compare equal using memcmp() after having been +** processed by the [sqlite3_vfs | xFullPathname] method of the VFS. */ int sqlite3_open( const char *filename, /* Database filename (UTF-8) */ @@ -2091,44 +2494,45 @@ int sqlite3_open_v2( ); /* -** CAPI3REF: Error Codes And Messages {F12800} +** CAPI3REF: Error Codes And Messages {H12800} <S60200> ** -** The sqlite3_errcode() interface returns the numeric -** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code] -** for the most recent failed sqlite3_* API call associated -** with [sqlite3] handle 'db'. If a prior API call failed but the -** most recent API call succeeded, the return value from sqlite3_errcode() -** is undefined. +** The sqlite3_errcode() interface returns the numeric [result code] or +** [extended result code] for the most recent failed sqlite3_* API call +** associated with a [database connection]. If a prior API call failed +** but the most recent API call succeeded, the return value from +** sqlite3_errcode() is undefined. ** ** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language -** text that describes the error, as either UTF8 or UTF16 respectively. +** text that describes the error, as either UTF-8 or UTF-16 respectively. ** Memory to hold the error message string is managed internally. -** The application does not need to worry with freeing the result. +** The application does not need to worry about freeing the result. ** However, the error string might be overwritten or deallocated by ** subsequent calls to other SQLite interface functions. ** +** If an interface fails with SQLITE_MISUSE, that means the interface +** was invoked incorrectly by the application. In that case, the +** error code and message may or may not be set. +** ** INVARIANTS: ** -** {F12801} The [sqlite3_errcode(D)] interface returns the numeric -** [SQLITE_OK | result code] or -** [SQLITE_IOERR_READ | extended result code] -** for the most recently failed interface call associated -** with [database connection] D. +** {H12801} The [sqlite3_errcode(D)] interface returns the numeric +** [result code] or [extended result code] for the most recently +** failed interface call associated with the [database connection] D. ** -** {F12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)] +** {H12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)] ** interfaces return English-language text that describes ** the error in the mostly recently failed interface call, -** encoded as either UTF8 or UTF16 respectively. +** encoded as either UTF-8 or UTF-16 respectively. ** -** {F12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()] +** {H12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()] ** are valid until the next SQLite interface call. ** -** {F12808} Calls to API routines that do not return an error code +** {H12808} Calls to API routines that do not return an error code ** (example: [sqlite3_data_count()]) do not ** change the error code or message returned by ** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()]. ** -** {F12809} Interfaces that are not associated with a specific +** {H12809} Interfaces that are not associated with a specific ** [database connection] (examples: ** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()] ** do not change the values returned by @@ -2139,20 +2543,20 @@ const char *sqlite3_errmsg(sqlite3*); const void *sqlite3_errmsg16(sqlite3*); /* -** CAPI3REF: SQL Statement Object {F13000} +** CAPI3REF: SQL Statement Object {H13000} <H13010> ** KEYWORDS: {prepared statement} {prepared statements} ** -** An instance of this object represent single SQL statements. This -** object is variously known as a "prepared statement" or a +** An instance of this object represents a single SQL statement. +** This object is variously known as a "prepared statement" or a ** "compiled SQL statement" or simply as a "statement". -** +** ** The life of a statement object goes something like this: ** ** <ol> ** <li> Create the object using [sqlite3_prepare_v2()] or a related ** function. -** <li> Bind values to host parameters using -** [sqlite3_bind_blob | sqlite3_bind_* interfaces]. +** <li> Bind values to [host parameters] using the sqlite3_bind_*() +** interfaces. ** <li> Run the SQL by calling [sqlite3_step()] one or more times. ** <li> Reset the statement using [sqlite3_reset()] then go back ** to step 2. Do this zero or more times. @@ -2165,7 +2569,7 @@ const void *sqlite3_errmsg16(sqlite3*); typedef struct sqlite3_stmt sqlite3_stmt; /* -** CAPI3REF: Run-time Limits {F12760} +** CAPI3REF: Run-time Limits {H12760} <S20600> ** ** This interface allows the size of various constructs to be limited ** on a connection by connection basis. The first parameter is the @@ -2176,7 +2580,7 @@ typedef struct sqlite3_stmt sqlite3_stmt; ** ** If the new limit is a negative number, the limit is unchanged. ** For the limit category of SQLITE_LIMIT_XYZ there is a hard upper -** bound set by a compile-time C-preprocess macro named SQLITE_MAX_XYZ. +** bound set by a compile-time C preprocessor macro named SQLITE_MAX_XYZ. ** (The "_LIMIT_" in the name is changed to "_MAX_".) ** Attempts to increase a limit above its hard upper bound are ** silently truncated to the hard upper limit. @@ -2185,47 +2589,44 @@ typedef struct sqlite3_stmt sqlite3_stmt; ** both their own internal database and also databases that are controlled ** by untrusted external sources. An example application might be a ** webbrowser that has its own databases for storing history and -** separate databases controlled by javascript applications downloaded -** off the internet. The internal databases can be given the +** separate databases controlled by JavaScript applications downloaded +** off the Internet. The internal databases can be given the ** large, default limits. Databases managed by external sources can ** be given much smaller limits designed to prevent a denial of service -** attach. Developers might also want to use the [sqlite3_set_authorizer()] +** attack. Developers might also want to use the [sqlite3_set_authorizer()] ** interface to further control untrusted SQL. The size of the database ** created by an untrusted script can be contained using the ** [max_page_count] [PRAGMA]. ** -** This interface is currently considered experimental and is subject -** to change or removal without prior notice. +** New run-time limit categories may be added in future releases. ** ** INVARIANTS: ** -** {F12762} A successful call to [sqlite3_limit(D,C,V)] where V is -** positive changes the -** limit on the size of construct C in [database connection] D -** to the lessor of V and the hard upper bound on the size -** of C that is set at compile-time. +** {H12762} A successful call to [sqlite3_limit(D,C,V)] where V is +** positive changes the limit on the size of construct C in the +** [database connection] D to the lesser of V and the hard upper +** bound on the size of C that is set at compile-time. ** -** {F12766} A successful call to [sqlite3_limit(D,C,V)] where V is negative -** leaves the state of [database connection] D unchanged. +** {H12766} A successful call to [sqlite3_limit(D,C,V)] where V is negative +** leaves the state of the [database connection] D unchanged. ** -** {F12769} A successful call to [sqlite3_limit(D,C,V)] returns the -** value of the limit on the size of construct C in -** in [database connection] D as it was prior to the call. +** {H12769} A successful call to [sqlite3_limit(D,C,V)] returns the +** value of the limit on the size of construct C in the +** [database connection] D as it was prior to the call. */ int sqlite3_limit(sqlite3*, int id, int newVal); /* -** CAPI3REF: Run-Time Limit Categories {F12790} +** CAPI3REF: Run-Time Limit Categories {H12790} <H12760> ** KEYWORDS: {limit category} {limit categories} -** +** ** These constants define various aspects of a [database connection] ** that can be limited in size by calls to [sqlite3_limit()]. ** The meanings of the various limits are as follows: ** ** <dl> ** <dt>SQLITE_LIMIT_LENGTH</dt> -** <dd>The maximum size of any -** string or blob or table row.<dd> +** <dd>The maximum size of any string or BLOB or table row.<dd> ** ** <dt>SQLITE_LIMIT_SQL_LENGTH</dt> ** <dd>The maximum length of an SQL statement.</dd> @@ -2272,52 +2673,50 @@ int sqlite3_limit(sqlite3*, int id, int newVal); #define SQLITE_LIMIT_VARIABLE_NUMBER 9 /* -** CAPI3REF: Compiling An SQL Statement {F13010} +** CAPI3REF: Compiling An SQL Statement {H13010} <S10000> +** KEYWORDS: {SQL statement compiler} ** ** To execute an SQL query, it must first be compiled into a byte-code -** program using one of these routines. +** program using one of these routines. ** -** The first argument "db" is an [database connection] -** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()] -** or [sqlite3_open16()]. -** The second argument "zSql" is the statement to be compiled, encoded +** The first argument, "db", is a [database connection] obtained from a +** prior call to [sqlite3_open()], [sqlite3_open_v2()] or [sqlite3_open16()]. +** +** The second argument, "zSql", is the statement to be compiled, encoded ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() -** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2() -** use UTF-16. {END} -** -** If the nByte argument is less -** than zero, then zSql is read up to the first zero terminator. -** If nByte is non-negative, then it is the maximum number of -** bytes read from zSql. When nByte is non-negative, the -** zSql string ends at either the first '\000' or '\u0000' character or +** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2() +** use UTF-16. +** +** If the nByte argument is less than zero, then zSql is read up to the +** first zero terminator. If nByte is non-negative, then it is the maximum +** number of bytes read from zSql. When nByte is non-negative, the +** zSql string ends at either the first '\000' or '\u0000' character or ** the nByte-th byte, whichever comes first. If the caller knows ** that the supplied string is nul-terminated, then there is a small -** performance advantage to be had by passing an nByte parameter that -** is equal to the number of bytes in the input string <i>including</i> -** the nul-terminator bytes.{END} +** performance advantage to be gained by passing an nByte parameter that +** is equal to the number of bytes in the input string <i>including</i> +** the nul-terminator bytes. ** ** *pzTail is made to point to the first byte past the end of the -** first SQL statement in zSql. These routines only compiles the first +** first SQL statement in zSql. These routines only compile the first ** statement in zSql, so *pzTail is left pointing to what remains ** uncompiled. ** ** *ppStmt is left pointing to a compiled [prepared statement] that can be -** executed using [sqlite3_step()]. Or if there is an error, *ppStmt is -** set to NULL. If the input text contains no SQL (if the input -** is and empty string or a comment) then *ppStmt is set to NULL. -** {U13018} The calling procedure is responsible for deleting the -** compiled SQL statement -** using [sqlite3_finalize()] after it has finished with it. +** executed using [sqlite3_step()]. If there is an error, *ppStmt is set +** to NULL. If the input text contains no SQL (if the input is an empty +** string or a comment) then *ppStmt is set to NULL. +** {A13018} The calling procedure is responsible for deleting the compiled +** SQL statement using [sqlite3_finalize()] after it has finished with it. ** -** On success, [SQLITE_OK] is returned. Otherwise an -** [error code] is returned. +** On success, [SQLITE_OK] is returned, otherwise an [error code] is returned. ** ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are ** recommended for all new programs. The two older interfaces are retained ** for backwards compatibility, but their use is discouraged. ** In the "v2" interfaces, the prepared statement -** that is returned (the [sqlite3_stmt] object) contains a copy of the -** original SQL text. {END} This causes the [sqlite3_step()] interface to +** that is returned (the [sqlite3_stmt] object) contains a copy of the +** original SQL text. This causes the [sqlite3_step()] interface to ** behave a differently in two ways: ** ** <ol> @@ -2326,60 +2725,57 @@ int sqlite3_limit(sqlite3*, int id, int newVal); ** always used to do, [sqlite3_step()] will automatically recompile the SQL ** statement and try to run it again. If the schema has changed in ** a way that makes the statement no longer valid, [sqlite3_step()] will still -** return [SQLITE_SCHEMA]. But unlike the legacy behavior, -** [SQLITE_SCHEMA] is now a fatal error. Calling -** [sqlite3_prepare_v2()] again will not make the +** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is +** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the ** error go away. Note: use [sqlite3_errmsg()] to find the text -** of the parsing error that results in an [SQLITE_SCHEMA] return. {END} +** of the parsing error that results in an [SQLITE_SCHEMA] return. ** </li> ** ** <li> -** When an error occurs, -** [sqlite3_step()] will return one of the detailed -** [error codes] or [extended error codes]. -** The legacy behavior was that [sqlite3_step()] would only return a generic -** [SQLITE_ERROR] result code and you would have to make a second call to -** [sqlite3_reset()] in order to find the underlying cause of the problem. -** With the "v2" prepare interfaces, the underlying reason for the error is -** returned immediately. +** When an error occurs, [sqlite3_step()] will return one of the detailed +** [error codes] or [extended error codes]. The legacy behavior was that +** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code +** and you would have to make a second call to [sqlite3_reset()] in order +** to find the underlying cause of the problem. With the "v2" prepare +** interfaces, the underlying reason for the error is returned immediately. ** </li> ** </ol> ** ** INVARIANTS: ** -** {F13011} The [sqlite3_prepare(db,zSql,...)] and +** {H13011} The [sqlite3_prepare(db,zSql,...)] and ** [sqlite3_prepare_v2(db,zSql,...)] interfaces interpret the ** text in their zSql parameter as UTF-8. ** -** {F13012} The [sqlite3_prepare16(db,zSql,...)] and +** {H13012} The [sqlite3_prepare16(db,zSql,...)] and ** [sqlite3_prepare16_v2(db,zSql,...)] interfaces interpret the ** text in their zSql parameter as UTF-16 in the native byte order. ** -** {F13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] -** and its variants is less than zero, then SQL text is +** {H13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] +** and its variants is less than zero, the SQL text is ** read from zSql is read up to the first zero terminator. ** -** {F13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] -** and its variants is non-negative, then at most nBytes bytes +** {H13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] +** and its variants is non-negative, then at most nBytes bytes of ** SQL text is read from zSql. ** -** {F13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants +** {H13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants ** if the zSql input text contains more than one SQL statement ** and pzTail is not NULL, then *pzTail is made to point to the ** first byte past the end of the first SQL statement in zSql. ** <todo>What does *pzTail point to if there is one statement?</todo> ** -** {F13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)] +** {H13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)] ** or one of its variants writes into *ppStmt a pointer to a new -** [prepared statement] or a pointer to NULL -** if zSql contains nothing other than whitespace or comments. +** [prepared statement] or a pointer to NULL if zSql contains +** nothing other than whitespace or comments. ** -** {F13019} The [sqlite3_prepare_v2()] interface and its variants return +** {H13019} The [sqlite3_prepare_v2()] interface and its variants return ** [SQLITE_OK] or an appropriate [error code] upon failure. ** -** {F13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its -** variants returns an error (any value other than [SQLITE_OK]) -** it first sets *ppStmt to NULL. +** {H13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its +** variants returns an error (any value other than [SQLITE_OK]), +** they first set *ppStmt to NULL. */ int sqlite3_prepare( sqlite3 *db, /* Database handle */ @@ -2411,85 +2807,89 @@ int sqlite3_prepare16_v2( ); /* -** CAPIREF: Retrieving Statement SQL {F13100} +** CAPIREF: Retrieving Statement SQL {H13100} <H13000> ** -** This intereface can be used to retrieve a saved copy of the original -** SQL text used to create a [prepared statement]. +** This interface can be used to retrieve a saved copy of the original +** SQL text used to create a [prepared statement] if that statement was +** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()]. ** ** INVARIANTS: ** -** {F13101} If the [prepared statement] passed as -** the an argument to [sqlite3_sql()] was compiled -** compiled using either [sqlite3_prepare_v2()] or -** [sqlite3_prepare16_v2()], -** then [sqlite3_sql()] function returns a pointer to a -** zero-terminated string containing a UTF-8 rendering +** {H13101} If the [prepared statement] passed as the argument to +** [sqlite3_sql()] was compiled using either [sqlite3_prepare_v2()] or +** [sqlite3_prepare16_v2()], then [sqlite3_sql()] returns +** a pointer to a zero-terminated string containing a UTF-8 rendering ** of the original SQL statement. ** -** {F13102} If the [prepared statement] passed as -** the an argument to [sqlite3_sql()] was compiled -** compiled using either [sqlite3_prepare()] or -** [sqlite3_prepare16()], -** then [sqlite3_sql()] function returns a NULL pointer. +** {H13102} If the [prepared statement] passed as the argument to +** [sqlite3_sql()] was compiled using either [sqlite3_prepare()] or +** [sqlite3_prepare16()], then [sqlite3_sql()] returns a NULL pointer. ** -** {F13103} The string returned by [sqlite3_sql(S)] is valid until the +** {H13103} The string returned by [sqlite3_sql(S)] is valid until the ** [prepared statement] S is deleted using [sqlite3_finalize(S)]. */ const char *sqlite3_sql(sqlite3_stmt *pStmt); /* -** CAPI3REF: Dynamically Typed Value Object {F15000} +** CAPI3REF: Dynamically Typed Value Object {H15000} <S20200> ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value} ** ** SQLite uses the sqlite3_value object to represent all values -** that can be stored in a database table. -** SQLite uses dynamic typing for the values it stores. -** Values stored in sqlite3_value objects can be -** be integers, floating point values, strings, BLOBs, or NULL. +** that can be stored in a database table. SQLite uses dynamic typing +** for the values it stores. Values stored in sqlite3_value objects +** can be integers, floating point values, strings, BLOBs, or NULL. ** ** An sqlite3_value object may be either "protected" or "unprotected". ** Some interfaces require a protected sqlite3_value. Other interfaces ** will accept either a protected or an unprotected sqlite3_value. -** Every interface that accepts sqlite3_value arguments specifies +** Every interface that accepts sqlite3_value arguments specifies ** whether or not it requires a protected sqlite3_value. ** ** The terms "protected" and "unprotected" refer to whether or not ** a mutex is held. A internal mutex is held for a protected ** sqlite3_value object but no mutex is held for an unprotected ** sqlite3_value object. If SQLite is compiled to be single-threaded -** (with SQLITE_THREADSAFE=0 and with [sqlite3_threadsafe()] returning 0) -** then there is no distinction between -** protected and unprotected sqlite3_value objects and they can be -** used interchangable. However, for maximum code portability it -** is recommended that applications make the distinction between -** between protected and unprotected sqlite3_value objects even if -** they are single threaded. +** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0) +** or if SQLite is run in one of reduced mutex modes +** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD] +** then there is no distinction between protected and unprotected +** sqlite3_value objects and they can be used interchangeably. However, +** for maximum code portability it is recommended that applications +** still make the distinction between between protected and unprotected +** sqlite3_value objects even when not strictly required. ** ** The sqlite3_value objects that are passed as parameters into the -** implementation of application-defined SQL functions are protected. +** implementation of [application-defined SQL functions] are protected. ** The sqlite3_value object returned by ** [sqlite3_column_value()] is unprotected. ** Unprotected sqlite3_value objects may only be used with -** [sqlite3_result_value()] and [sqlite3_bind_value()]. All other -** interfaces that use sqlite3_value require protected sqlite3_value objects. +** [sqlite3_result_value()] and [sqlite3_bind_value()]. +** The [sqlite3_value_blob | sqlite3_value_type()] family of +** interfaces require protected sqlite3_value objects. */ typedef struct Mem sqlite3_value; /* -** CAPI3REF: SQL Function Context Object {F16001} +** CAPI3REF: SQL Function Context Object {H16001} <S20200> ** ** The context in which an SQL function executes is stored in an -** sqlite3_context object. A pointer to an sqlite3_context -** object is always first parameter to application-defined SQL functions. +** sqlite3_context object. A pointer to an sqlite3_context object +** is always first parameter to [application-defined SQL functions]. +** The application-defined SQL function implementation will pass this +** pointer through into calls to [sqlite3_result_int | sqlite3_result()], +** [sqlite3_aggregate_context()], [sqlite3_user_data()], +** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()], +** and/or [sqlite3_set_auxdata()]. */ typedef struct sqlite3_context sqlite3_context; /* -** CAPI3REF: Binding Values To Prepared Statements {F13500} +** CAPI3REF: Binding Values To Prepared Statements {H13500} <S70300> +** KEYWORDS: {host parameter} {host parameters} {host parameter name} +** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding} ** -** In the SQL strings input to [sqlite3_prepare_v2()] and its -** variants, literals may be replace by a parameter in one -** of these forms: +** In the SQL strings input to [sqlite3_prepare_v2()] and its variants, +** literals may be replaced by a parameter in one of these forms: ** ** <ul> ** <li> ? @@ -2500,32 +2900,31 @@ typedef struct sqlite3_context sqlite3_context; ** </ul> ** ** In the parameter forms shown above NNN is an integer literal, -** VVV alpha-numeric parameter name. -** The values of these parameters (also called "host parameter names" -** or "SQL parameters") +** and VVV is an alpha-numeric parameter name. The values of these +** parameters (also called "host parameter names" or "SQL parameters") ** can be set using the sqlite3_bind_*() routines defined here. ** -** The first argument to the sqlite3_bind_*() routines always -** is a pointer to the [sqlite3_stmt] object returned from -** [sqlite3_prepare_v2()] or its variants. The second -** argument is the index of the parameter to be set. The -** first parameter has an index of 1. When the same named -** parameter is used more than once, second and subsequent -** occurrences have the same index as the first occurrence. +** The first argument to the sqlite3_bind_*() routines is always +** a pointer to the [sqlite3_stmt] object returned from +** [sqlite3_prepare_v2()] or its variants. +** +** The second argument is the index of the SQL parameter to be set. +** The leftmost SQL parameter has an index of 1. When the same named +** SQL parameter is used more than once, second and subsequent +** occurrences have the same index as the first occurrence. ** The index for named parameters can be looked up using the -** [sqlite3_bind_parameter_name()] API if desired. The index +** [sqlite3_bind_parameter_index()] API if desired. The index ** for "?NNN" parameters is the value of NNN. -** The NNN value must be between 1 and the compile-time -** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999). +** The NNN value must be between 1 and the [sqlite3_limit()] +** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999). ** ** The third argument is the value to bind to the parameter. ** -** In those -** routines that have a fourth argument, its value is the number of bytes -** in the parameter. To be clear: the value is the number of <u>bytes</u> -** in the value, not the number of characters. +** In those routines that have a fourth argument, its value is the +** number of bytes in the parameter. To be clear: the value is the +** number of <u>bytes</u> in the value, not the number of characters. ** If the fourth parameter is negative, the length of the string is -** number of bytes up to the first zero terminator. +** the number of bytes up to the first zero terminator. ** ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or @@ -2537,12 +2936,12 @@ typedef struct sqlite3_context sqlite3_context; ** the sqlite3_bind_*() routine returns. ** ** The sqlite3_bind_zeroblob() routine binds a BLOB of length N that -** is filled with zeros. A zeroblob uses a fixed amount of memory -** (just an integer to hold it size) while it is being processed. -** Zeroblobs are intended to serve as place-holders for BLOBs whose -** content is later written using -** [sqlite3_blob_open | increment BLOB I/O] routines. A negative -** value for the zeroblob results in a zero-length BLOB. +** is filled with zeroes. A zeroblob uses a fixed amount of memory +** (just an integer to hold its size) while it is being processed. +** Zeroblobs are intended to serve as placeholders for BLOBs whose +** content is later written using +** [sqlite3_blob_open | incremental BLOB I/O] routines. +** A negative value for the zeroblob results in a zero-length BLOB. ** ** The sqlite3_bind_*() routines must be called after ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and @@ -2552,7 +2951,7 @@ typedef struct sqlite3_context sqlite3_context; ** ** These routines return [SQLITE_OK] on success or an error code if ** anything goes wrong. [SQLITE_RANGE] is returned if the parameter -** index is out of range. [SQLITE_NOMEM] is returned if malloc fails. +** index is out of range. [SQLITE_NOMEM] is returned if malloc() fails. ** [SQLITE_MISUSE] might be returned if these routines are called on a ** virtual machine that is the wrong state or which has already been finalized. ** Detection of misuse is unreliable. Applications should not depend @@ -2561,79 +2960,79 @@ typedef struct sqlite3_context sqlite3_context; ** panic rather than return SQLITE_MISUSE. ** ** See also: [sqlite3_bind_parameter_count()], -** [sqlite3_bind_parameter_name()], and -** [sqlite3_bind_parameter_index()]. +** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()]. ** ** INVARIANTS: ** -** {F13506} The [sqlite3_prepare | SQL statement compiler] recognizes -** tokens of the forms "?", "?NNN", "$VVV", ":VVV", and "@VVV" -** as SQL parameters, where NNN is any sequence of one or more -** digits and where VVV is any sequence of one or more -** alphanumeric characters or "::" optionally followed by -** a string containing no spaces and contained within parentheses. +** {H13506} The [SQL statement compiler] recognizes tokens of the forms +** "?", "?NNN", "$VVV", ":VVV", and "@VVV" as SQL parameters, +** where NNN is any sequence of one or more digits +** and where VVV is any sequence of one or more alphanumeric +** characters or "::" optionally followed by a string containing +** no spaces and contained within parentheses. ** -** {F13509} The initial value of an SQL parameter is NULL. +** {H13509} The initial value of an SQL parameter is NULL. ** -** {F13512} The index of an "?" SQL parameter is one larger than the +** {H13512} The index of an "?" SQL parameter is one larger than the ** largest index of SQL parameter to the left, or 1 if ** the "?" is the leftmost SQL parameter. ** -** {F13515} The index of an "?NNN" SQL parameter is the integer NNN. +** {H13515} The index of an "?NNN" SQL parameter is the integer NNN. ** -** {F13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is -** the same as the index of leftmost occurances of the same +** {H13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is +** the same as the index of leftmost occurrences of the same ** parameter, or one more than the largest index over all -** parameters to the left if this is the first occurrance +** parameters to the left if this is the first occurrence ** of this parameter, or 1 if this is the leftmost parameter. ** -** {F13521} The [sqlite3_prepare | SQL statement compiler] fail with -** an [SQLITE_RANGE] error if the index of an SQL parameter -** is less than 1 or greater than SQLITE_MAX_VARIABLE_NUMBER. +** {H13521} The [SQL statement compiler] fails with an [SQLITE_RANGE] +** error if the index of an SQL parameter is less than 1 +** or greater than the compile-time SQLITE_MAX_VARIABLE_NUMBER +** parameter. ** -** {F13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)] +** {H13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)] ** associate the value V with all SQL parameters having an ** index of N in the [prepared statement] S. ** -** {F13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)] +** {H13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)] ** override prior calls with the same values of S and N. ** -** {F13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)] +** {H13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)] ** persist across calls to [sqlite3_reset(S)]. ** -** {F13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)], +** {H13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)], ** [sqlite3_bind_text(S,N,V,L,D)], or ** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds the first L -** bytes of the blob or string pointed to by V, when L +** bytes of the BLOB or string pointed to by V, when L ** is non-negative. ** -** {F13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or +** {H13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or ** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds characters ** from V through the first zero character when L is negative. ** -** {F13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)], +** {H13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)], ** [sqlite3_bind_text(S,N,V,L,D)], or ** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special ** constant [SQLITE_STATIC], SQLite assumes that the value V ** is held in static unmanaged space that will not change ** during the lifetime of the binding. ** -** {F13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)], +** {H13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)], ** [sqlite3_bind_text(S,N,V,L,D)], or ** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special -** constant [SQLITE_TRANSIENT], the routine makes a -** private copy of V value before it returns. +** constant [SQLITE_TRANSIENT], the routine makes a +** private copy of the value V before it returns. ** -** {F13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)], +** {H13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)], ** [sqlite3_bind_text(S,N,V,L,D)], or ** [sqlite3_bind_text16(S,N,V,L,D)] when D is a pointer to ** a function, SQLite invokes that function to destroy the -** V value after it has finished using the V value. +** value V after it has finished using the value V. ** -** {F13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound -** is a blob of L bytes, or a zero-length blob if L is negative. +** {H13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound +** is a BLOB of L bytes, or a zero-length BLOB if L is negative. ** -** {F13551} In calls to [sqlite3_bind_value(S,N,V)] the V argument may +** {H13551} In calls to [sqlite3_bind_value(S,N,V)] the V argument may ** be either a [protected sqlite3_value] object or an ** [unprotected sqlite3_value] object. */ @@ -2648,18 +3047,18 @@ int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); /* -** CAPI3REF: Number Of SQL Parameters {F13600} +** CAPI3REF: Number Of SQL Parameters {H13600} <S70300> ** -** This routine can be used to find the number of SQL parameters -** in a prepared statement. SQL parameters are tokens of the +** This routine can be used to find the number of [SQL parameters] +** in a [prepared statement]. SQL parameters are tokens of the ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as -** place-holders for values that are [sqlite3_bind_blob | bound] +** placeholders for values that are [sqlite3_bind_blob | bound] ** to the parameters at a later time. ** -** This routine actually returns the index of the largest parameter. -** For all forms except ?NNN, this will correspond to the number of -** unique parameters. If parameters of the ?NNN are used, there may -** be gaps in the list. +** This routine actually returns the index of the largest (rightmost) +** parameter. For all forms except ?NNN, this will correspond to the +** number of unique parameters. If parameters of the ?NNN are used, +** there may be gaps in the list. ** ** See also: [sqlite3_bind_blob|sqlite3_bind()], ** [sqlite3_bind_parameter_name()], and @@ -2667,30 +3066,30 @@ int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); ** ** INVARIANTS: ** -** {F13601} The [sqlite3_bind_parameter_count(S)] interface returns +** {H13601} The [sqlite3_bind_parameter_count(S)] interface returns ** the largest index of all SQL parameters in the -** [prepared statement] S, or 0 if S -** contains no SQL parameters. +** [prepared statement] S, or 0 if S contains no SQL parameters. */ int sqlite3_bind_parameter_count(sqlite3_stmt*); /* -** CAPI3REF: Name Of A Host Parameter {F13620} +** CAPI3REF: Name Of A Host Parameter {H13620} <S70300> ** ** This routine returns a pointer to the name of the n-th -** SQL parameter in a [prepared statement]. +** [SQL parameter] in a [prepared statement]. ** SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA" ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA" ** respectively. ** In other words, the initial ":" or "$" or "@" or "?" ** is included as part of the name. -** Parameters of the form "?" without a following integer have no name. +** Parameters of the form "?" without a following integer have no name +** and are also referred to as "anonymous parameters". ** ** The first host parameter has an index of 1, not 0. ** ** If the value n is out of range or if the n-th parameter is ** nameless, then NULL is returned. The returned string is -** always in the UTF-8 encoding even if the named parameter was +** always in UTF-8 encoding even if the named parameter was ** originally specified as UTF-16 in [sqlite3_prepare16()] or ** [sqlite3_prepare16_v2()]. ** @@ -2700,16 +3099,16 @@ int sqlite3_bind_parameter_count(sqlite3_stmt*); ** ** INVARIANTS: ** -** {F13621} The [sqlite3_bind_parameter_name(S,N)] interface returns +** {H13621} The [sqlite3_bind_parameter_name(S,N)] interface returns ** a UTF-8 rendering of the name of the SQL parameter in -** [prepared statement] S having index N, or +** the [prepared statement] S having index N, or ** NULL if there is no SQL parameter with index N or if the ** parameter with index N is an anonymous parameter "?". */ const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); /* -** CAPI3REF: Index Of A Parameter With A Given Name {F13640} +** CAPI3REF: Index Of A Parameter With A Given Name {H13640} <S70300> ** ** Return the index of an SQL parameter given its name. The ** index value returned is suitable for use as the second @@ -2724,62 +3123,56 @@ const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); ** ** INVARIANTS: ** -** {F13641} The [sqlite3_bind_parameter_index(S,N)] interface returns -** the index of SQL parameter in [prepared statement] +** {H13641} The [sqlite3_bind_parameter_index(S,N)] interface returns +** the index of SQL parameter in the [prepared statement] ** S whose name matches the UTF-8 string N, or 0 if there is ** no match. */ int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); /* -** CAPI3REF: Reset All Bindings On A Prepared Statement {F13660} +** CAPI3REF: Reset All Bindings On A Prepared Statement {H13660} <S70300> ** -** Contrary to the intuition of many, [sqlite3_reset()] does not -** reset the [sqlite3_bind_blob | bindings] on a -** [prepared statement]. Use this routine to -** reset all host parameters to NULL. +** Contrary to the intuition of many, [sqlite3_reset()] does not reset +** the [sqlite3_bind_blob | bindings] on a [prepared statement]. +** Use this routine to reset all host parameters to NULL. ** ** INVARIANTS: ** -** {F13661} The [sqlite3_clear_bindings(S)] interface resets all -** SQL parameter bindings in [prepared statement] S -** back to NULL. +** {H13661} The [sqlite3_clear_bindings(S)] interface resets all SQL +** parameter bindings in the [prepared statement] S back to NULL. */ int sqlite3_clear_bindings(sqlite3_stmt*); /* -** CAPI3REF: Number Of Columns In A Result Set {F13710} +** CAPI3REF: Number Of Columns In A Result Set {H13710} <S10700> ** -** Return the number of columns in the result set returned by the -** [prepared statement]. This routine returns 0 -** if pStmt is an SQL statement that does not return data (for -** example an UPDATE). +** Return the number of columns in the result set returned by the +** [prepared statement]. This routine returns 0 if pStmt is an SQL +** statement that does not return data (for example an [UPDATE]). ** ** INVARIANTS: ** -** {F13711} The [sqlite3_column_count(S)] interface returns the number of -** columns in the result set generated by the -** [prepared statement] S, or 0 if S does not generate -** a result set. +** {H13711} The [sqlite3_column_count(S)] interface returns the number of +** columns in the result set generated by the [prepared statement] S, +** or 0 if S does not generate a result set. */ int sqlite3_column_count(sqlite3_stmt *pStmt); /* -** CAPI3REF: Column Names In A Result Set {F13720} +** CAPI3REF: Column Names In A Result Set {H13720} <S10700> ** ** These routines return the name assigned to a particular column -** in the result set of a SELECT statement. The sqlite3_column_name() -** interface returns a pointer to a zero-terminated UTF8 string +** in the result set of a [SELECT] statement. The sqlite3_column_name() +** interface returns a pointer to a zero-terminated UTF-8 string ** and sqlite3_column_name16() returns a pointer to a zero-terminated -** UTF16 string. The first parameter is the -** [prepared statement] that implements the SELECT statement. -** The second parameter is the column number. The left-most column is -** number 0. +** UTF-16 string. The first parameter is the [prepared statement] +** that implements the [SELECT] statement. The second parameter is the +** column number. The leftmost column is number 0. ** -** The returned string pointer is valid until either the -** [prepared statement] is destroyed by [sqlite3_finalize()] -** or until the next call sqlite3_column_name() or sqlite3_column_name16() -** on the same column. +** The returned string pointer is valid until either the [prepared statement] +** is destroyed by [sqlite3_finalize()] or until the next call to +** sqlite3_column_name() or sqlite3_column_name16() on the same column. ** ** If sqlite3_malloc() fails during the processing of either routine ** (for example during a conversion from UTF-8 to UTF-16) then a @@ -2792,136 +3185,124 @@ int sqlite3_column_count(sqlite3_stmt *pStmt); ** ** INVARIANTS: ** -** {F13721} A successful invocation of the [sqlite3_column_name(S,N)] -** interface returns the name -** of the Nth column (where 0 is the left-most column) for the -** result set of [prepared statement] S as a -** zero-terminated UTF-8 string. +** {H13721} A successful invocation of the [sqlite3_column_name(S,N)] +** interface returns the name of the Nth column (where 0 is +** the leftmost column) for the result set of the +** [prepared statement] S as a zero-terminated UTF-8 string. ** -** {F13723} A successful invocation of the [sqlite3_column_name16(S,N)] -** interface returns the name -** of the Nth column (where 0 is the left-most column) for the -** result set of [prepared statement] S as a -** zero-terminated UTF-16 string in the native byte order. +** {H13723} A successful invocation of the [sqlite3_column_name16(S,N)] +** interface returns the name of the Nth column (where 0 is +** the leftmost column) for the result set of the +** [prepared statement] S as a zero-terminated UTF-16 string +** in the native byte order. ** -** {F13724} The [sqlite3_column_name()] and [sqlite3_column_name16()] +** {H13724} The [sqlite3_column_name()] and [sqlite3_column_name16()] ** interfaces return a NULL pointer if they are unable to -** allocate memory memory to hold there normal return strings. +** allocate memory to hold their normal return strings. ** -** {F13725} If the N parameter to [sqlite3_column_name(S,N)] or +** {H13725} If the N parameter to [sqlite3_column_name(S,N)] or ** [sqlite3_column_name16(S,N)] is out of range, then the -** interfaces returns a NULL pointer. -** -** {F13726} The strings returned by [sqlite3_column_name(S,N)] and +** interfaces return a NULL pointer. +** +** {H13726} The strings returned by [sqlite3_column_name(S,N)] and ** [sqlite3_column_name16(S,N)] are valid until the next ** call to either routine with the same S and N parameters ** or until [sqlite3_finalize(S)] is called. ** -** {F13727} When a result column of a [SELECT] statement contains -** an AS clause, the name of that column is the indentifier +** {H13727} When a result column of a [SELECT] statement contains +** an AS clause, the name of that column is the identifier ** to the right of the AS keyword. */ const char *sqlite3_column_name(sqlite3_stmt*, int N); const void *sqlite3_column_name16(sqlite3_stmt*, int N); /* -** CAPI3REF: Source Of Data In A Query Result {F13740} +** CAPI3REF: Source Of Data In A Query Result {H13740} <S10700> ** ** These routines provide a means to determine what column of what -** table in which database a result of a SELECT statement comes from. +** table in which database a result of a [SELECT] statement comes from. ** The name of the database or table or column can be returned as -** either a UTF8 or UTF16 string. The _database_ routines return +** either a UTF-8 or UTF-16 string. The _database_ routines return ** the database name, the _table_ routines return the table name, and ** the origin_ routines return the column name. -** The returned string is valid until -** the [prepared statement] is destroyed using -** [sqlite3_finalize()] or until the same information is requested +** The returned string is valid until the [prepared statement] is destroyed +** using [sqlite3_finalize()] or until the same information is requested ** again in a different encoding. ** ** The names returned are the original un-aliased names of the ** database, table, and column. ** ** The first argument to the following calls is a [prepared statement]. -** These functions return information about the Nth column returned by +** These functions return information about the Nth column returned by ** the statement, where N is the second function argument. ** -** If the Nth column returned by the statement is an expression -** or subquery and is not a column value, then all of these functions -** return NULL. These routine might also return NULL if a memory -** allocation error occurs. Otherwise, they return the -** name of the attached database, table and column that query result -** column was extracted from. +** If the Nth column returned by the statement is an expression or +** subquery and is not a column value, then all of these functions return +** NULL. These routine might also return NULL if a memory allocation error +** occurs. Otherwise, they return the name of the attached database, table +** and column that query result column was extracted from. ** ** As with all other SQLite APIs, those postfixed with "16" return ** UTF-16 encoded strings, the other functions return UTF-8. {END} ** -** These APIs are only available if the library was compiled with the -** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. +** These APIs are only available if the library was compiled with the +** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined. ** -** {U13751} +** {A13751} ** If two or more threads call one or more of these routines against the same ** prepared statement and column at the same time then the results are ** undefined. ** ** INVARIANTS: ** -** {F13741} The [sqlite3_column_database_name(S,N)] interface returns either -** the UTF-8 zero-terminated name of the database from which the -** Nth result column of [prepared statement] S -** is extracted, or NULL if the the Nth column of S is a -** general expression or if unable to allocate memory -** to store the name. -** -** {F13742} The [sqlite3_column_database_name16(S,N)] interface returns either -** the UTF-16 native byte order -** zero-terminated name of the database from which the -** Nth result column of [prepared statement] S -** is extracted, or NULL if the the Nth column of S is a -** general expression or if unable to allocate memory -** to store the name. -** -** {F13743} The [sqlite3_column_table_name(S,N)] interface returns either -** the UTF-8 zero-terminated name of the table from which the -** Nth result column of [prepared statement] S -** is extracted, or NULL if the the Nth column of S is a -** general expression or if unable to allocate memory +** {H13741} The [sqlite3_column_database_name(S,N)] interface returns either +** the UTF-8 zero-terminated name of the database from which the +** Nth result column of the [prepared statement] S is extracted, +** or NULL if the Nth column of S is a general expression +** or if unable to allocate memory to store the name. +** +** {H13742} The [sqlite3_column_database_name16(S,N)] interface returns either +** the UTF-16 native byte order zero-terminated name of the database +** from which the Nth result column of the [prepared statement] S is +** extracted, or NULL if the Nth column of S is a general expression +** or if unable to allocate memory to store the name. +** +** {H13743} The [sqlite3_column_table_name(S,N)] interface returns either +** the UTF-8 zero-terminated name of the table from which the +** Nth result column of the [prepared statement] S is extracted, +** or NULL if the Nth column of S is a general expression +** or if unable to allocate memory to store the name. +** +** {H13744} The [sqlite3_column_table_name16(S,N)] interface returns either +** the UTF-16 native byte order zero-terminated name of the table +** from which the Nth result column of the [prepared statement] S is +** extracted, or NULL if the Nth column of S is a general expression +** or if unable to allocate memory to store the name. +** +** {H13745} The [sqlite3_column_origin_name(S,N)] interface returns either +** the UTF-8 zero-terminated name of the table column from which the +** Nth result column of the [prepared statement] S is extracted, +** or NULL if the Nth column of S is a general expression +** or if unable to allocate memory to store the name. +** +** {H13746} The [sqlite3_column_origin_name16(S,N)] interface returns either +** the UTF-16 native byte order zero-terminated name of the table +** column from which the Nth result column of the +** [prepared statement] S is extracted, or NULL if the Nth column +** of S is a general expression or if unable to allocate memory ** to store the name. -** -** {F13744} The [sqlite3_column_table_name16(S,N)] interface returns either -** the UTF-16 native byte order -** zero-terminated name of the table from which the -** Nth result column of [prepared statement] S -** is extracted, or NULL if the the Nth column of S is a -** general expression or if unable to allocate memory -** to store the name. -** -** {F13745} The [sqlite3_column_origin_name(S,N)] interface returns either -** the UTF-8 zero-terminated name of the table column from which the -** Nth result column of [prepared statement] S -** is extracted, or NULL if the the Nth column of S is a -** general expression or if unable to allocate memory -** to store the name. -** -** {F13746} The [sqlite3_column_origin_name16(S,N)] interface returns either -** the UTF-16 native byte order -** zero-terminated name of the table column from which the -** Nth result column of [prepared statement] S -** is extracted, or NULL if the the Nth column of S is a -** general expression or if unable to allocate memory -** to store the name. -** -** {F13748} The return values from -** [sqlite3_column_database_name|column metadata interfaces] -** are valid -** for the lifetime of the [prepared statement] +** +** {H13748} The return values from +** [sqlite3_column_database_name | column metadata interfaces] +** are valid for the lifetime of the [prepared statement] ** or until the encoding is changed by another metadata ** interface call for the same prepared statement and column. ** -** LIMITATIONS: +** ASSUMPTIONS: ** -** {U13751} If two or more threads call one or more -** [sqlite3_column_database_name|column metadata interfaces] -** the same [prepared statement] and result column +** {A13751} If two or more threads call one or more +** [sqlite3_column_database_name | column metadata interfaces] +** for the same [prepared statement] and result column ** at the same time then the results are undefined. */ const char *sqlite3_column_database_name(sqlite3_stmt*,int); @@ -2932,26 +3313,26 @@ const char *sqlite3_column_origin_name(sqlite3_stmt*,int); const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); /* -** CAPI3REF: Declared Datatype Of A Query Result {F13760} +** CAPI3REF: Declared Datatype Of A Query Result {H13760} <S10700> ** -** The first parameter is a [prepared statement]. -** If this statement is a SELECT statement and the Nth column of the -** returned result set of that SELECT is a table column (not an +** The first parameter is a [prepared statement]. +** If this statement is a [SELECT] statement and the Nth column of the +** returned result set of that [SELECT] is a table column (not an ** expression or subquery) then the declared type of the table ** column is returned. If the Nth column of the result set is an ** expression or subquery, then a NULL pointer is returned. -** The returned string is always UTF-8 encoded. {END} -** For example, in the database schema: +** The returned string is always UTF-8 encoded. {END} +** +** For example, given the database schema: ** ** CREATE TABLE t1(c1 VARIANT); ** -** And the following statement compiled: +** and the following statement to be compiled: ** ** SELECT c1 + 1, c1 FROM t1; ** -** Then this routine would return the string "VARIANT" for the second -** result column (i==1), and a NULL pointer for the first result column -** (i==0). +** this routine would return the string "VARIANT" for the second result +** column (i==1), and a NULL pointer for the first result column (i==0). ** ** SQLite uses dynamic run-time typing. So just because a column ** is declared to contain a particular type does not mean that the @@ -2962,22 +3343,21 @@ const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); ** ** INVARIANTS: ** -** {F13761} A successful call to [sqlite3_column_decltype(S,N)] -** returns a zero-terminated UTF-8 string containing the -** the declared datatype of the table column that appears -** as the Nth column (numbered from 0) of the result set to the -** [prepared statement] S. +** {H13761} A successful call to [sqlite3_column_decltype(S,N)] returns a +** zero-terminated UTF-8 string containing the declared datatype +** of the table column that appears as the Nth column (numbered +** from 0) of the result set to the [prepared statement] S. ** -** {F13762} A successful call to [sqlite3_column_decltype16(S,N)] +** {H13762} A successful call to [sqlite3_column_decltype16(S,N)] ** returns a zero-terminated UTF-16 native byte order string ** containing the declared datatype of the table column that appears ** as the Nth column (numbered from 0) of the result set to the ** [prepared statement] S. ** -** {F13763} If N is less than 0 or N is greater than or equal to -** the number of columns in [prepared statement] S +** {H13763} If N is less than 0 or N is greater than or equal to +** the number of columns in the [prepared statement] S, ** or if the Nth column of S is an expression or subquery rather -** than a table column or if a memory allocation failure +** than a table column, or if a memory allocation failure ** occurs during encoding conversions, then ** calls to [sqlite3_column_decltype(S,N)] or ** [sqlite3_column_decltype16(S,N)] return NULL. @@ -2985,32 +3365,30 @@ const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); const char *sqlite3_column_decltype(sqlite3_stmt*,int); const void *sqlite3_column_decltype16(sqlite3_stmt*,int); -/* -** CAPI3REF: Evaluate An SQL Statement {F13200} +/* +** CAPI3REF: Evaluate An SQL Statement {H13200} <S10000> ** -** After an [prepared statement] has been prepared with a call -** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of -** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], -** then this function must be called one or more times to evaluate the -** statement. +** After a [prepared statement] has been prepared using either +** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy +** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function +** must be called one or more times to evaluate the statement. ** -** The details of the behavior of this sqlite3_step() interface depend +** The details of the behavior of the sqlite3_step() interface depend ** on whether the statement was prepared using the newer "v2" interface ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy ** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the ** new "v2" interface is recommended for new applications but the legacy ** interface will continue to be supported. ** -** In the legacy interface, the return value will be either [SQLITE_BUSY], +** In the legacy interface, the return value will be either [SQLITE_BUSY], ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE]. -** With the "v2" interface, any of the other [SQLITE_OK | result code] -** or [SQLITE_IOERR_READ | extended result code] might be returned as -** well. +** With the "v2" interface, any of the other [result codes] or +** [extended result codes] might be returned as well. ** ** [SQLITE_BUSY] means that the database engine was unable to acquire the -** database locks it needs to do its job. If the statement is a COMMIT +** database locks it needs to do its job. If the statement is a [COMMIT] ** or occurs outside of an explicit transaction, then you can retry the -** statement. If the statement is not a COMMIT and occurs within a +** statement. If the statement is not a [COMMIT] and occurs within a ** explicit transaction then you should rollback the transaction before ** continuing. ** @@ -3019,16 +3397,15 @@ const void *sqlite3_column_decltype16(sqlite3_stmt*,int); ** machine without first calling [sqlite3_reset()] to reset the virtual ** machine back to its initial state. ** -** If the SQL statement being executed returns any data, then -** [SQLITE_ROW] is returned each time a new row of data is ready -** for processing by the caller. The values may be accessed using -** the [sqlite3_column_int | column access functions]. +** If the SQL statement being executed returns any data, then [SQLITE_ROW] +** is returned each time a new row of data is ready for processing by the +** caller. The values may be accessed using the [column access functions]. ** sqlite3_step() is called again to retrieve the next row of data. -** +** ** [SQLITE_ERROR] means that a run-time error (such as a constraint ** violation) has occurred. sqlite3_step() should not be called again on ** the VM. More information may be found by calling [sqlite3_errmsg()]. -** With the legacy interface, a more specific error code (example: +** With the legacy interface, a more specific error code (for example, ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth) ** can be obtained by calling [sqlite3_reset()] on the ** [prepared statement]. In the "v2" interface, @@ -3036,80 +3413,75 @@ const void *sqlite3_column_decltype16(sqlite3_stmt*,int); ** ** [SQLITE_MISUSE] means that the this routine was called inappropriately. ** Perhaps it was called on a [prepared statement] that has -** already been [sqlite3_finalize | finalized] or on one that had +** already been [sqlite3_finalize | finalized] or on one that had ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could ** be the case that the same database connection is being used by two or ** more threads at the same moment in time. ** -** <b>Goofy Interface Alert:</b> -** In the legacy interface, -** the sqlite3_step() API always returns a generic error code, -** [SQLITE_ERROR], following any error other than [SQLITE_BUSY] -** and [SQLITE_MISUSE]. You must call [sqlite3_reset()] or -** [sqlite3_finalize()] in order to find one of the specific -** [error codes] that better describes the error. +** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step() +** API always returns a generic error code, [SQLITE_ERROR], following any +** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call +** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the +** specific [error codes] that better describes the error. ** We admit that this is a goofy design. The problem has been fixed ** with the "v2" interface. If you prepare all of your SQL statements ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead -** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the -** more specific [error codes] are returned directly +** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces, +** then the more specific [error codes] are returned directly ** by sqlite3_step(). The use of the "v2" interface is recommended. ** ** INVARIANTS: ** -** {F13202} If [prepared statement] S is ready to be -** run, then [sqlite3_step(S)] advances that prepared statement -** until to completion or until it is ready to return another -** row of the result set or an interrupt or run-time error occurs. +** {H13202} If the [prepared statement] S is ready to be run, then +** [sqlite3_step(S)] advances that prepared statement until +** completion or until it is ready to return another row of the +** result set, or until an [sqlite3_interrupt | interrupt] +** or a run-time error occurs. ** -** {F15304} When a call to [sqlite3_step(S)] causes the -** [prepared statement] S to run to completion, -** the function returns [SQLITE_DONE]. +** {H15304} When a call to [sqlite3_step(S)] causes the [prepared statement] +** S to run to completion, the function returns [SQLITE_DONE]. ** -** {F15306} When a call to [sqlite3_step(S)] stops because it is ready -** to return another row of the result set, it returns -** [SQLITE_ROW]. +** {H15306} When a call to [sqlite3_step(S)] stops because it is ready to +** return another row of the result set, it returns [SQLITE_ROW]. ** -** {F15308} If a call to [sqlite3_step(S)] encounters an -** [sqlite3_interrupt|interrupt] or a run-time error, -** it returns an appropraite error code that is not one of +** {H15308} If a call to [sqlite3_step(S)] encounters an +** [sqlite3_interrupt | interrupt] or a run-time error, +** it returns an appropriate error code that is not one of ** [SQLITE_OK], [SQLITE_ROW], or [SQLITE_DONE]. ** -** {F15310} If an [sqlite3_interrupt|interrupt] or run-time error +** {H15310} If an [sqlite3_interrupt | interrupt] or a run-time error ** occurs during a call to [sqlite3_step(S)] ** for a [prepared statement] S created using ** legacy interfaces [sqlite3_prepare()] or -** [sqlite3_prepare16()] then the function returns either +** [sqlite3_prepare16()], then the function returns either ** [SQLITE_ERROR], [SQLITE_BUSY], or [SQLITE_MISUSE]. */ int sqlite3_step(sqlite3_stmt*); /* -** CAPI3REF: Number of columns in a result set {F13770} +** CAPI3REF: Number of columns in a result set {H13770} <S10700> ** -** Return the number of values in the current row of the result set. +** Returns the number of values in the current row of the result set. ** ** INVARIANTS: ** -** {F13771} After a call to [sqlite3_step(S)] that returns -** [SQLITE_ROW], the [sqlite3_data_count(S)] routine -** will return the same value as the -** [sqlite3_column_count(S)] function. +** {H13771} After a call to [sqlite3_step(S)] that returns [SQLITE_ROW], +** the [sqlite3_data_count(S)] routine will return the same value +** as the [sqlite3_column_count(S)] function. ** -** {F13772} After [sqlite3_step(S)] has returned any value other than -** [SQLITE_ROW] or before [sqlite3_step(S)] has been -** called on the [prepared statement] for -** the first time since it was [sqlite3_prepare|prepared] -** or [sqlite3_reset|reset], the [sqlite3_data_count(S)] -** routine returns zero. +** {H13772} After [sqlite3_step(S)] has returned any value other than +** [SQLITE_ROW] or before [sqlite3_step(S)] has been called on the +** [prepared statement] for the first time since it was +** [sqlite3_prepare | prepared] or [sqlite3_reset | reset], +** the [sqlite3_data_count(S)] routine returns zero. */ int sqlite3_data_count(sqlite3_stmt *pStmt); /* -** CAPI3REF: Fundamental Datatypes {F10265} +** CAPI3REF: Fundamental Datatypes {H10265} <S10110><S10120> ** KEYWORDS: SQLITE_TEXT ** -** {F10266}Every value in SQLite has one of five fundamental datatypes: +** {H10266} Every value in SQLite has one of five fundamental datatypes: ** ** <ul> ** <li> 64-bit signed integer @@ -3123,7 +3495,7 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); ** ** Note that the SQLITE_TEXT constant was also used in SQLite version 2 ** for a completely different meaning. Software that links against both -** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not +** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not ** SQLITE_TEXT. */ #define SQLITE_INTEGER 1 @@ -3138,33 +3510,31 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); #define SQLITE3_TEXT 3 /* -** CAPI3REF: Results Values From A Query {F13800} +** CAPI3REF: Result Values From A Query {H13800} <S10700> +** KEYWORDS: {column access functions} ** ** These routines form the "result set query" interface. ** -** These routines return information about -** a single column of the current result row of a query. In every -** case the first argument is a pointer to the -** [prepared statement] that is being -** evaluated (the [sqlite3_stmt*] that was returned from -** [sqlite3_prepare_v2()] or one of its variants) and -** the second argument is the index of the column for which information -** should be returned. The left-most column of the result set -** has an index of 0. -** -** If the SQL statement is not currently point to a valid row, or if the -** the column index is out of range, the result is undefined. +** These routines return information about a single column of the current +** result row of a query. In every case the first argument is a pointer +** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*] +** that was returned from [sqlite3_prepare_v2()] or one of its variants) +** and the second argument is the index of the column for which information +** should be returned. The leftmost column of the result set has the index 0. +** +** If the SQL statement does not currently point to a valid row, or if the +** column index is out of range, the result is undefined. ** These routines may only be called when the most recent call to ** [sqlite3_step()] has returned [SQLITE_ROW] and neither -** [sqlite3_reset()] nor [sqlite3_finalize()] has been call subsequently. +** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently. ** If any of these routines are called after [sqlite3_reset()] or ** [sqlite3_finalize()] or after [sqlite3_step()] has returned ** something other than [SQLITE_ROW], the results are undefined. ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()] ** are called from a different thread while any of these routines -** are pending, then the results are undefined. +** are pending, then the results are undefined. ** -** The sqlite3_column_type() routine returns +** The sqlite3_column_type() routine returns the ** [SQLITE_INTEGER | datatype code] for the initial data type ** of the result column. The returned value is one of [SQLITE_INTEGER], ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value @@ -3174,7 +3544,7 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); ** versions of SQLite may change the behavior of sqlite3_column_type() ** following a type conversion. ** -** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() +** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() ** routine returns the number of bytes in that BLOB or string. ** If the result is a UTF-16 string, then sqlite3_column_bytes() converts ** the string to UTF-8 and then returns the number of bytes. @@ -3187,11 +3557,11 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); ** ** Strings returned by sqlite3_column_text() and sqlite3_column_text16(), ** even empty strings, are always zero terminated. The return -** value from sqlite3_column_blob() for a zero-length blob is an arbitrary +** value from sqlite3_column_blob() for a zero-length BLOB is an arbitrary ** pointer, possibly even a NULL pointer. ** ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes() -** but leaves the result in UTF-16 in native byte order instead of UTF-8. +** but leaves the result in UTF-16 in native byte order instead of UTF-8. ** The zero terminator is not included in this count. ** ** The object returned by [sqlite3_column_value()] is an @@ -3199,15 +3569,14 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); ** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()]. ** If the [unprotected sqlite3_value] object returned by ** [sqlite3_column_value()] is used in any other way, including calls -** to routines like -** [sqlite3_value_int()], [sqlite3_value_text()], or [sqlite3_value_bytes()], -** then the behavior is undefined. +** to routines like [sqlite3_value_int()], [sqlite3_value_text()], +** or [sqlite3_value_bytes()], then the behavior is undefined. ** ** These routines attempt to convert the value where appropriate. For ** example, if the internal representation is FLOAT and a text result -** is requested, [sqlite3_snprintf()] is used internally to do the conversion -** automatically. The following table details the conversions that -** are applied: +** is requested, [sqlite3_snprintf()] is used internally to perform the +** conversion automatically. The following table details the conversions +** that are applied: ** ** <blockquote> ** <table border="1"> @@ -3219,7 +3588,7 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); ** <tr><td> NULL <td> BLOB <td> Result is NULL pointer ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer -** <tr><td> INTEGER <td> BLOB <td> Same as for INTEGER->TEXT +** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT ** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer ** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float ** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT @@ -3234,57 +3603,56 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); ** ** The table above makes reference to standard C library functions atoi() ** and atof(). SQLite does not really use these functions. It has its -** on equavalent internal routines. The atoi() and atof() names are +** own equivalent internal routines. The atoi() and atof() names are ** used in the table for brevity and because they are familiar to most ** C programmers. ** ** Note that when type conversions occur, pointers returned by prior ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or -** sqlite3_column_text16() may be invalidated. +** sqlite3_column_text16() may be invalidated. ** Type conversions and pointer invalidations might occur ** in the following cases: ** ** <ul> -** <li><p> The initial content is a BLOB and sqlite3_column_text() -** or sqlite3_column_text16() is called. A zero-terminator might -** need to be added to the string.</p></li> -** -** <li><p> The initial content is UTF-8 text and sqlite3_column_bytes16() or -** sqlite3_column_text16() is called. The content must be converted -** to UTF-16.</p></li> -** -** <li><p> The initial content is UTF-16 text and sqlite3_column_bytes() or -** sqlite3_column_text() is called. The content must be converted -** to UTF-8.</p></li> +** <li> The initial content is a BLOB and sqlite3_column_text() or +** sqlite3_column_text16() is called. A zero-terminator might +** need to be added to the string.</li> +** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or +** sqlite3_column_text16() is called. The content must be converted +** to UTF-16.</li> +** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or +** sqlite3_column_text() is called. The content must be converted +** to UTF-8.</li> ** </ul> ** ** Conversions between UTF-16be and UTF-16le are always done in place and do ** not invalidate a prior pointer, though of course the content of the buffer ** that the prior pointer points to will have been modified. Other kinds -** of conversion are done in place when it is possible, but sometime it is -** not possible and in those cases prior pointers are invalidated. +** of conversion are done in place when it is possible, but sometimes they +** are not possible and in those cases prior pointers are invalidated. ** ** The safest and easiest to remember policy is to invoke these routines ** in one of the following ways: ** -** <ul> +** <ul> ** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li> ** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li> ** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li> -** </ul> +** </ul> ** -** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(), -** or sqlite3_column_text16() first to force the result into the desired -** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to -** find the size of the result. Do not mix call to sqlite3_column_text() or -** sqlite3_column_blob() with calls to sqlite3_column_bytes16(). And do not -** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes(). +** In other words, you should call sqlite3_column_text(), +** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result +** into the desired format, then invoke sqlite3_column_bytes() or +** sqlite3_column_bytes16() to find the size of the result. Do not mix calls +** to sqlite3_column_text() or sqlite3_column_blob() with calls to +** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() +** with calls to sqlite3_column_bytes(). ** ** The pointers returned are valid until a type conversion occurs as ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or ** [sqlite3_finalize()] is called. The memory space used to hold strings -** and blobs is freed automatically. Do <b>not</b> pass the pointers returned -** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into +** and BLOBs is freed automatically. Do <b>not</b> pass the pointers returned +** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into ** [sqlite3_free()]. ** ** If a memory allocation error occurs during the evaluation of any @@ -3295,58 +3663,58 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); ** ** INVARIANTS: ** -** {F13803} The [sqlite3_column_blob(S,N)] interface converts the +** {H13803} The [sqlite3_column_blob(S,N)] interface converts the ** Nth column in the current row of the result set for -** [prepared statement] S into a blob and then returns a +** the [prepared statement] S into a BLOB and then returns a ** pointer to the converted value. ** -** {F13806} The [sqlite3_column_bytes(S,N)] interface returns the -** number of bytes in the blob or string (exclusive of the +** {H13806} The [sqlite3_column_bytes(S,N)] interface returns the +** number of bytes in the BLOB or string (exclusive of the ** zero terminator on the string) that was returned by the ** most recent call to [sqlite3_column_blob(S,N)] or ** [sqlite3_column_text(S,N)]. ** -** {F13809} The [sqlite3_column_bytes16(S,N)] interface returns the +** {H13809} The [sqlite3_column_bytes16(S,N)] interface returns the ** number of bytes in the string (exclusive of the ** zero terminator on the string) that was returned by the ** most recent call to [sqlite3_column_text16(S,N)]. ** -** {F13812} The [sqlite3_column_double(S,N)] interface converts the -** Nth column in the current row of the result set for +** {H13812} The [sqlite3_column_double(S,N)] interface converts the +** Nth column in the current row of the result set for the ** [prepared statement] S into a floating point value and ** returns a copy of that value. ** -** {F13815} The [sqlite3_column_int(S,N)] interface converts the -** Nth column in the current row of the result set for +** {H13815} The [sqlite3_column_int(S,N)] interface converts the +** Nth column in the current row of the result set for the ** [prepared statement] S into a 64-bit signed integer and ** returns the lower 32 bits of that integer. ** -** {F13818} The [sqlite3_column_int64(S,N)] interface converts the -** Nth column in the current row of the result set for +** {H13818} The [sqlite3_column_int64(S,N)] interface converts the +** Nth column in the current row of the result set for the ** [prepared statement] S into a 64-bit signed integer and ** returns a copy of that integer. ** -** {F13821} The [sqlite3_column_text(S,N)] interface converts the +** {H13821} The [sqlite3_column_text(S,N)] interface converts the ** Nth column in the current row of the result set for -** [prepared statement] S into a zero-terminated UTF-8 +** the [prepared statement] S into a zero-terminated UTF-8 ** string and returns a pointer to that string. ** -** {F13824} The [sqlite3_column_text16(S,N)] interface converts the -** Nth column in the current row of the result set for +** {H13824} The [sqlite3_column_text16(S,N)] interface converts the +** Nth column in the current row of the result set for the ** [prepared statement] S into a zero-terminated 2-byte -** aligned UTF-16 native byte order -** string and returns a pointer to that string. +** aligned UTF-16 native byte order string and returns +** a pointer to that string. ** -** {F13827} The [sqlite3_column_type(S,N)] interface returns +** {H13827} The [sqlite3_column_type(S,N)] interface returns ** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT], ** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for ** the Nth column in the current row of the result set for -** [prepared statement] S. +** the [prepared statement] S. ** -** {F13830} The [sqlite3_column_value(S,N)] interface returns a +** {H13830} The [sqlite3_column_value(S,N)] interface returns a ** pointer to an [unprotected sqlite3_value] object for the ** Nth column in the current row of the result set for -** [prepared statement] S. +** the [prepared statement] S. */ const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); int sqlite3_column_bytes(sqlite3_stmt*, int iCol); @@ -3360,90 +3728,88 @@ int sqlite3_column_type(sqlite3_stmt*, int iCol); sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); /* -** CAPI3REF: Destroy A Prepared Statement Object {F13300} +** CAPI3REF: Destroy A Prepared Statement Object {H13300} <S70300><S30100> ** -** The sqlite3_finalize() function is called to delete a -** [prepared statement]. If the statement was -** executed successfully, or not executed at all, then SQLITE_OK is returned. -** If execution of the statement failed then an -** [error code] or [extended error code] -** is returned. +** The sqlite3_finalize() function is called to delete a [prepared statement]. +** If the statement was executed successfully or not executed at all, then +** SQLITE_OK is returned. If execution of the statement failed then an +** [error code] or [extended error code] is returned. ** ** This routine can be called at any point during the execution of the -** [prepared statement]. If the virtual machine has not +** [prepared statement]. If the virtual machine has not ** completed execution when this routine is called, that is like -** encountering an error or an interrupt. (See [sqlite3_interrupt()].) -** Incomplete updates may be rolled back and transactions cancelled, -** depending on the circumstances, and the +** encountering an error or an [sqlite3_interrupt | interrupt]. +** Incomplete updates may be rolled back and transactions canceled, +** depending on the circumstances, and the ** [error code] returned will be [SQLITE_ABORT]. ** ** INVARIANTS: ** -** {F11302} The [sqlite3_finalize(S)] interface destroys the +** {H11302} The [sqlite3_finalize(S)] interface destroys the ** [prepared statement] S and releases all ** memory and file resources held by that object. ** -** {F11304} If the most recent call to [sqlite3_step(S)] for the +** {H11304} If the most recent call to [sqlite3_step(S)] for the ** [prepared statement] S returned an error, ** then [sqlite3_finalize(S)] returns that same error. */ int sqlite3_finalize(sqlite3_stmt *pStmt); /* -** CAPI3REF: Reset A Prepared Statement Object {F13330} +** CAPI3REF: Reset A Prepared Statement Object {H13330} <S70300> ** -** The sqlite3_reset() function is called to reset a -** [prepared statement] object. -** back to its initial state, ready to be re-executed. +** The sqlite3_reset() function is called to reset a [prepared statement] +** object back to its initial state, ready to be re-executed. ** Any SQL statement variables that had values bound to them using ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values. ** Use [sqlite3_clear_bindings()] to reset the bindings. ** -** {F11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S +** {H11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S ** back to the beginning of its program. ** -** {F11334} If the most recent call to [sqlite3_step(S)] for +** {H11334} If the most recent call to [sqlite3_step(S)] for the ** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE], ** or if [sqlite3_step(S)] has never before been called on S, ** then [sqlite3_reset(S)] returns [SQLITE_OK]. ** -** {F11336} If the most recent call to [sqlite3_step(S)] for +** {H11336} If the most recent call to [sqlite3_step(S)] for the ** [prepared statement] S indicated an error, then ** [sqlite3_reset(S)] returns an appropriate [error code]. ** -** {F11338} The [sqlite3_reset(S)] interface does not change the values -** of any [sqlite3_bind_blob|bindings] on [prepared statement] S. +** {H11338} The [sqlite3_reset(S)] interface does not change the values +** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S. */ int sqlite3_reset(sqlite3_stmt *pStmt); /* -** CAPI3REF: Create Or Redefine SQL Functions {F16100} -** KEYWORDS: {function creation routines} -** -** These two functions (collectively known as -** "function creation routines") are used to add SQL functions or aggregates -** or to redefine the behavior of existing SQL functions or aggregates. The -** difference only between the two is that the second parameter, the -** name of the (scalar) function or aggregate, is encoded in UTF-8 for -** sqlite3_create_function() and UTF-16 for sqlite3_create_function16(). +** CAPI3REF: Create Or Redefine SQL Functions {H16100} <S20200> +** KEYWORDS: {function creation routines} +** KEYWORDS: {application-defined SQL function} +** KEYWORDS: {application-defined SQL functions} +** +** These two functions (collectively known as "function creation routines") +** are used to add SQL functions or aggregates or to redefine the behavior +** of existing SQL functions or aggregates. The only difference between the +** two is that the second parameter, the name of the (scalar) function or +** aggregate, is encoded in UTF-8 for sqlite3_create_function() and UTF-16 +** for sqlite3_create_function16(). ** ** The first parameter is the [database connection] to which the SQL -** function is to be added. If a single -** program uses more than one [database connection] internally, then SQL -** functions must be added individually to each [database connection]. -** -** The second parameter is the name of the SQL function to be created -** or redefined. -** The length of the name is limited to 255 bytes, exclusive of the -** zero-terminator. Note that the name length limit is in bytes, not +** function is to be added. If a single program uses more than one database +** connection internally, then SQL functions must be added individually to +** each database connection. +** +** The second parameter is the name of the SQL function to be created or +** redefined. The length of the name is limited to 255 bytes, exclusive of +** the zero-terminator. Note that the name length limit is in bytes, not ** characters. Any attempt to create a function with a longer name -** will result in an SQLITE_ERROR error. +** will result in [SQLITE_ERROR] being returned. ** ** The third parameter is the number of arguments that the SQL function or ** aggregate takes. If this parameter is negative, then the SQL function or ** aggregate may take any number of arguments. ** -** The fourth parameter, eTextRep, specifies what +** The fourth parameter, eTextRep, specifies what ** [SQLITE_UTF8 | text encoding] this SQL function prefers for ** its parameters. Any SQL function implementation should be able to work ** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be @@ -3452,90 +3818,86 @@ int sqlite3_reset(sqlite3_stmt *pStmt); ** times with the same function but with different values of eTextRep. ** When multiple implementations of the same function are available, SQLite ** will pick the one that involves the least amount of data conversion. -** If there is only a single implementation which does not care what -** text encoding is used, then the fourth argument should be -** [SQLITE_ANY]. +** If there is only a single implementation which does not care what text +** encoding is used, then the fourth argument should be [SQLITE_ANY]. ** -** The fifth parameter is an arbitrary pointer. The implementation -** of the function can gain access to this pointer using -** [sqlite3_user_data()]. +** The fifth parameter is an arbitrary pointer. The implementation of the +** function can gain access to this pointer using [sqlite3_user_data()]. ** ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are -** pointers to C-language functions that implement the SQL -** function or aggregate. A scalar SQL function requires an implementation of -** the xFunc callback only, NULL pointers should be passed as the xStep -** and xFinal parameters. An aggregate SQL function requires an implementation -** of xStep and xFinal and NULL should be passed for xFunc. To delete an -** existing SQL function or aggregate, pass NULL for all three function -** callback. +** pointers to C-language functions that implement the SQL function or +** aggregate. A scalar SQL function requires an implementation of the xFunc +** callback only, NULL pointers should be passed as the xStep and xFinal +** parameters. An aggregate SQL function requires an implementation of xStep +** and xFinal and NULL should be passed for xFunc. To delete an existing +** SQL function or aggregate, pass NULL for all three function callbacks. ** ** It is permitted to register multiple implementations of the same ** functions with the same name but with either differing numbers of -** arguments or differing perferred text encodings. SQLite will use +** arguments or differing preferred text encodings. SQLite will use ** the implementation most closely matches the way in which the ** SQL function is used. ** ** INVARIANTS: ** -** {F16103} The [sqlite3_create_function16()] interface behaves exactly +** {H16103} The [sqlite3_create_function16()] interface behaves exactly ** like [sqlite3_create_function()] in every way except that it -** interprets the zFunctionName argument as -** zero-terminated UTF-16 native byte order instead of as a -** zero-terminated UTF-8. +** interprets the zFunctionName argument as zero-terminated UTF-16 +** native byte order instead of as zero-terminated UTF-8. ** -** {F16106} A successful invocation of +** {H16106} A successful invocation of ** the [sqlite3_create_function(D,X,N,E,...)] interface registers -** or replaces callback functions in [database connection] D +** or replaces callback functions in the [database connection] D ** used to implement the SQL function named X with N parameters -** and having a perferred text encoding of E. +** and having a preferred text encoding of E. ** -** {F16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)] +** {H16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)] ** replaces the P, F, S, and L values from any prior calls with ** the same D, X, N, and E values. ** -** {F16112} The [sqlite3_create_function(D,X,...)] interface fails with +** {H16112} The [sqlite3_create_function(D,X,...)] interface fails with ** a return code of [SQLITE_ERROR] if the SQL function name X is ** longer than 255 bytes exclusive of the zero terminator. ** -** {F16118} Either F must be NULL and S and L are non-NULL or else F +** {H16118} Either F must be NULL and S and L are non-NULL or else F ** is non-NULL and S and L are NULL, otherwise ** [sqlite3_create_function(D,X,N,E,P,F,S,L)] returns [SQLITE_ERROR]. ** -** {F16121} The [sqlite3_create_function(D,...)] interface fails with an +** {H16121} The [sqlite3_create_function(D,...)] interface fails with an ** error code of [SQLITE_BUSY] if there exist [prepared statements] ** associated with the [database connection] D. ** -** {F16124} The [sqlite3_create_function(D,X,N,...)] interface fails with an +** {H16124} The [sqlite3_create_function(D,X,N,...)] interface fails with an ** error code of [SQLITE_ERROR] if parameter N (specifying the number ** of arguments to the SQL function being registered) is less ** than -1 or greater than 127. ** -** {F16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)] +** {H16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)] ** interface causes callbacks to be invoked for the SQL function ** named X when the number of arguments to the SQL function is ** exactly N. ** -** {F16130} When N is -1, the [sqlite3_create_function(D,X,N,...)] +** {H16130} When N is -1, the [sqlite3_create_function(D,X,N,...)] ** interface causes callbacks to be invoked for the SQL function ** named X with any number of arguments. ** -** {F16133} When calls to [sqlite3_create_function(D,X,N,...)] +** {H16133} When calls to [sqlite3_create_function(D,X,N,...)] ** specify multiple implementations of the same function X ** and when one implementation has N>=0 and the other has N=(-1) ** the implementation with a non-zero N is preferred. ** -** {F16136} When calls to [sqlite3_create_function(D,X,N,E,...)] +** {H16136} When calls to [sqlite3_create_function(D,X,N,E,...)] ** specify multiple implementations of the same function X with ** the same number of arguments N but with different ** encodings E, then the implementation where E matches the ** database encoding is preferred. ** -** {F16139} For an aggregate SQL function created using -** [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finializer +** {H16139} For an aggregate SQL function created using +** [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finalizer ** function L will always be invoked exactly once if the ** step function S is called one or more times. ** -** {F16142} When SQLite invokes either the xFunc or xStep function of +** {H16142} When SQLite invokes either the xFunc or xStep function of ** an application-defined SQL function or aggregate created ** by [sqlite3_create_function()] or [sqlite3_create_function16()], ** then the array of [sqlite3_value] objects passed as the @@ -3563,7 +3925,7 @@ int sqlite3_create_function16( ); /* -** CAPI3REF: Text Encodings {F10267} +** CAPI3REF: Text Encodings {H10267} <S50200> <H16100> ** ** These constant define integer codes that represent the various ** text encodings supported by SQLite. @@ -3576,11 +3938,12 @@ int sqlite3_create_function16( #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ /* -** CAPI3REF: Obsolete Functions +** CAPI3REF: Deprecated Functions +** DEPRECATED ** -** These functions are all now obsolete. In order to maintain -** backwards compatibility with older code, we continue to support -** these functions. However, new development projects should avoid +** These functions are [deprecated]. In order to maintain +** backwards compatibility with older code, these functions continue +** to be supported. However, new applications should avoid ** the use of these functions. To help encourage people to avoid ** using these functions, we are not going to tell you want they do. */ @@ -3592,7 +3955,7 @@ void sqlite3_thread_cleanup(void); int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64); /* -** CAPI3REF: Obtaining SQL Function Parameter Values {F15100} +** CAPI3REF: Obtaining SQL Function Parameter Values {H15100} <S20200> ** ** The C-language implementation of SQL functions and aggregates uses ** this set of interface routines to access the parameter values on @@ -3610,95 +3973,93 @@ int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64); ** Any attempt to use these routines on an [unprotected sqlite3_value] ** object results in undefined behavior. ** -** These routines work just like the corresponding -** [sqlite3_column_blob | sqlite3_column_* routines] except that -** these routines take a single [protected sqlite3_value] object pointer -** instead of an [sqlite3_stmt*] pointer and an integer column number. +** These routines work just like the corresponding [column access functions] +** except that these routines take a single [protected sqlite3_value] object +** pointer instead of a [sqlite3_stmt*] pointer and an integer column number. ** -** The sqlite3_value_text16() interface extracts a UTF16 string +** The sqlite3_value_text16() interface extracts a UTF-16 string ** in the native byte-order of the host machine. The ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces -** extract UTF16 strings as big-endian and little-endian respectively. +** extract UTF-16 strings as big-endian and little-endian respectively. ** ** The sqlite3_value_numeric_type() interface attempts to apply ** numeric affinity to the value. This means that an attempt is ** made to convert the value to an integer or floating point. If ** such a conversion is possible without loss of information (in other -** words if the value is a string that looks like a number) -** then the conversion is done. Otherwise no conversion occurs. The -** [SQLITE_INTEGER | datatype] after conversion is returned. +** words, if the value is a string that looks like a number) +** then the conversion is performed. Otherwise no conversion occurs. +** The [SQLITE_INTEGER | datatype] after conversion is returned. ** -** Please pay particular attention to the fact that the pointer that -** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or +** Please pay particular attention to the fact that the pointer returned +** from [sqlite3_value_blob()], [sqlite3_value_text()], or ** [sqlite3_value_text16()] can be invalidated by a subsequent call to ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], -** or [sqlite3_value_text16()]. +** or [sqlite3_value_text16()]. ** ** These routines must be called from the same thread as ** the SQL function that supplied the [sqlite3_value*] parameters. ** -** ** INVARIANTS: ** -** {F15103} The [sqlite3_value_blob(V)] interface converts the -** [protected sqlite3_value] object V into a blob and then returns a -** pointer to the converted value. +** {H15103} The [sqlite3_value_blob(V)] interface converts the +** [protected sqlite3_value] object V into a BLOB and then +** returns a pointer to the converted value. ** -** {F15106} The [sqlite3_value_bytes(V)] interface returns the -** number of bytes in the blob or string (exclusive of the +** {H15106} The [sqlite3_value_bytes(V)] interface returns the +** number of bytes in the BLOB or string (exclusive of the ** zero terminator on the string) that was returned by the ** most recent call to [sqlite3_value_blob(V)] or ** [sqlite3_value_text(V)]. ** -** {F15109} The [sqlite3_value_bytes16(V)] interface returns the +** {H15109} The [sqlite3_value_bytes16(V)] interface returns the ** number of bytes in the string (exclusive of the ** zero terminator on the string) that was returned by the ** most recent call to [sqlite3_value_text16(V)], ** [sqlite3_value_text16be(V)], or [sqlite3_value_text16le(V)]. ** -** {F15112} The [sqlite3_value_double(V)] interface converts the +** {H15112} The [sqlite3_value_double(V)] interface converts the ** [protected sqlite3_value] object V into a floating point value and ** returns a copy of that value. ** -** {F15115} The [sqlite3_value_int(V)] interface converts the +** {H15115} The [sqlite3_value_int(V)] interface converts the ** [protected sqlite3_value] object V into a 64-bit signed integer and ** returns the lower 32 bits of that integer. ** -** {F15118} The [sqlite3_value_int64(V)] interface converts the +** {H15118} The [sqlite3_value_int64(V)] interface converts the ** [protected sqlite3_value] object V into a 64-bit signed integer and ** returns a copy of that integer. ** -** {F15121} The [sqlite3_value_text(V)] interface converts the -** [protected sqlite3_value] object V into a zero-terminated UTF-8 +** {H15121} The [sqlite3_value_text(V)] interface converts the +** [protected sqlite3_value] object V into a zero-terminated UTF-8 ** string and returns a pointer to that string. ** -** {F15124} The [sqlite3_value_text16(V)] interface converts the +** {H15124} The [sqlite3_value_text16(V)] interface converts the ** [protected sqlite3_value] object V into a zero-terminated 2-byte ** aligned UTF-16 native byte order ** string and returns a pointer to that string. ** -** {F15127} The [sqlite3_value_text16be(V)] interface converts the +** {H15127} The [sqlite3_value_text16be(V)] interface converts the ** [protected sqlite3_value] object V into a zero-terminated 2-byte ** aligned UTF-16 big-endian ** string and returns a pointer to that string. ** -** {F15130} The [sqlite3_value_text16le(V)] interface converts the +** {H15130} The [sqlite3_value_text16le(V)] interface converts the ** [protected sqlite3_value] object V into a zero-terminated 2-byte ** aligned UTF-16 little-endian ** string and returns a pointer to that string. ** -** {F15133} The [sqlite3_value_type(V)] interface returns +** {H15133} The [sqlite3_value_type(V)] interface returns ** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT], ** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for ** the [sqlite3_value] object V. ** -** {F15136} The [sqlite3_value_numeric_type(V)] interface converts +** {H15136} The [sqlite3_value_numeric_type(V)] interface converts ** the [protected sqlite3_value] object V into either an integer or ** a floating point value if it can do so without loss of ** information, and returns one of [SQLITE_NULL], ** [SQLITE_INTEGER], [SQLITE_FLOAT], [SQLITE_TEXT], or -** [SQLITE_BLOB] as appropriate for -** the [protected sqlite3_value] object V after the conversion attempt. +** [SQLITE_BLOB] as appropriate for the +** [protected sqlite3_value] object V after the conversion attempt. */ const void *sqlite3_value_blob(sqlite3_value*); int sqlite3_value_bytes(sqlite3_value*); @@ -3714,46 +4075,44 @@ int sqlite3_value_type(sqlite3_value*); int sqlite3_value_numeric_type(sqlite3_value*); /* -** CAPI3REF: Obtain Aggregate Function Context {F16210} +** CAPI3REF: Obtain Aggregate Function Context {H16210} <S20200> ** ** The implementation of aggregate SQL functions use this routine to allocate -** a structure for storing their state. -** The first time the sqlite3_aggregate_context() routine is -** is called for a particular aggregate, SQLite allocates nBytes of memory -** zeros that memory, and returns a pointer to it. -** On second and subsequent calls to sqlite3_aggregate_context() -** for the same aggregate function index, the same buffer is returned. -** The implementation -** of the aggregate can use the returned buffer to accumulate data. +** a structure for storing their state. +** +** The first time the sqlite3_aggregate_context() routine is called for a +** particular aggregate, SQLite allocates nBytes of memory, zeroes out that +** memory, and returns a pointer to it. On second and subsequent calls to +** sqlite3_aggregate_context() for the same aggregate function index, +** the same buffer is returned. The implementation of the aggregate can use +** the returned buffer to accumulate data. ** ** SQLite automatically frees the allocated buffer when the aggregate ** query concludes. ** -** The first parameter should be a copy of the -** [sqlite3_context | SQL function context] that is the first -** parameter to the callback routine that implements the aggregate -** function. +** The first parameter should be a copy of the +** [sqlite3_context | SQL function context] that is the first parameter +** to the callback routine that implements the aggregate function. ** ** This routine must be called from the same thread in which ** the aggregate SQL function is running. ** ** INVARIANTS: ** -** {F16211} The first invocation of [sqlite3_aggregate_context(C,N)] for +** {H16211} The first invocation of [sqlite3_aggregate_context(C,N)] for ** a particular instance of an aggregate function (for a particular -** context C) causes SQLite to allocation N bytes of memory, -** zero that memory, and return a pointer to the allocationed -** memory. +** context C) causes SQLite to allocate N bytes of memory, +** zero that memory, and return a pointer to the allocated memory. ** -** {F16213} If a memory allocation error occurs during +** {H16213} If a memory allocation error occurs during ** [sqlite3_aggregate_context(C,N)] then the function returns 0. ** -** {F16215} Second and subsequent invocations of +** {H16215} Second and subsequent invocations of ** [sqlite3_aggregate_context(C,N)] for the same context pointer C ** ignore the N parameter and return a pointer to the same ** block of memory returned by the first invocation. ** -** {F16217} The memory allocated by [sqlite3_aggregate_context(C,N)] is +** {H16217} The memory allocated by [sqlite3_aggregate_context(C,N)] is ** automatically freed on the next call to [sqlite3_reset()] ** or [sqlite3_finalize()] for the [prepared statement] containing ** the aggregate function associated with context C. @@ -3761,11 +4120,11 @@ int sqlite3_value_numeric_type(sqlite3_value*); void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); /* -** CAPI3REF: User Data For Functions {F16240} +** CAPI3REF: User Data For Functions {H16240} <S20200> ** ** The sqlite3_user_data() interface returns a copy of ** the pointer that was the pUserData parameter (the 5th parameter) -** of the the [sqlite3_create_function()] +** of the [sqlite3_create_function()] ** and [sqlite3_create_function16()] routines that originally ** registered the application defined function. {END} ** @@ -3774,71 +4133,67 @@ void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); ** ** INVARIANTS: ** -** {F16243} The [sqlite3_user_data(C)] interface returns a copy of the +** {H16243} The [sqlite3_user_data(C)] interface returns a copy of the ** P pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)] ** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that -** registered the SQL function associated with -** [sqlite3_context] C. +** registered the SQL function associated with [sqlite3_context] C. */ void *sqlite3_user_data(sqlite3_context*); /* -** CAPI3REF: Database Connection For Functions {F16250} +** CAPI3REF: Database Connection For Functions {H16250} <S60600><S20200> ** ** The sqlite3_context_db_handle() interface returns a copy of ** the pointer to the [database connection] (the 1st parameter) -** of the the [sqlite3_create_function()] +** of the [sqlite3_create_function()] ** and [sqlite3_create_function16()] routines that originally ** registered the application defined function. ** ** INVARIANTS: ** -** {F16253} The [sqlite3_context_db_handle(C)] interface returns a copy of the +** {H16253} The [sqlite3_context_db_handle(C)] interface returns a copy of the ** D pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)] ** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that -** registered the SQL function associated with -** [sqlite3_context] C. +** registered the SQL function associated with [sqlite3_context] C. */ sqlite3 *sqlite3_context_db_handle(sqlite3_context*); /* -** CAPI3REF: Function Auxiliary Data {F16270} +** CAPI3REF: Function Auxiliary Data {H16270} <S20200> ** ** The following two functions may be used by scalar SQL functions to -** associate meta-data with argument values. If the same value is passed to +** associate metadata with argument values. If the same value is passed to ** multiple invocations of the same SQL function during query execution, under -** some circumstances the associated meta-data may be preserved. This may +** some circumstances the associated metadata may be preserved. This may ** be used, for example, to add a regular-expression matching scalar ** function. The compiled version of the regular expression is stored as -** meta-data associated with the SQL value passed as the regular expression +** metadata associated with the SQL value passed as the regular expression ** pattern. The compiled regular expression can be reused on multiple ** invocations of the same function so that the original pattern string ** does not need to be recompiled on each invocation. ** -** The sqlite3_get_auxdata() interface returns a pointer to the meta-data +** The sqlite3_get_auxdata() interface returns a pointer to the metadata ** associated by the sqlite3_set_auxdata() function with the Nth argument -** value to the application-defined function. -** If no meta-data has been ever been set for the Nth -** argument of the function, or if the cooresponding function parameter -** has changed since the meta-data was set, then sqlite3_get_auxdata() -** returns a NULL pointer. -** -** The sqlite3_set_auxdata() interface saves the meta-data -** pointed to by its 3rd parameter as the meta-data for the N-th +** value to the application-defined function. If no metadata has been ever +** been set for the Nth argument of the function, or if the corresponding +** function parameter has changed since the meta-data was set, +** then sqlite3_get_auxdata() returns a NULL pointer. +** +** The sqlite3_set_auxdata() interface saves the metadata +** pointed to by its 3rd parameter as the metadata for the N-th ** argument of the application-defined function. Subsequent ** calls to sqlite3_get_auxdata() might return this data, if it has -** not been destroyed. -** If it is not NULL, SQLite will invoke the destructor +** not been destroyed. +** If it is not NULL, SQLite will invoke the destructor ** function given by the 4th parameter to sqlite3_set_auxdata() on -** the meta-data when the corresponding function parameter changes +** the metadata when the corresponding function parameter changes ** or when the SQL statement completes, whichever comes first. ** -** SQLite is free to call the destructor and drop meta-data on -** any parameter of any function at any time. The only guarantee -** is that the destructor will be called before the metadata is -** dropped. +** SQLite is free to call the destructor and drop metadata on any +** parameter of any function at any time. The only guarantee is that +** the destructor will be called before the metadata is dropped. ** -** In practice, meta-data is preserved between function calls for +** In practice, metadata is preserved between function calls for ** expressions that are constant at compile time. This includes literal ** values and SQL variables. ** @@ -3847,28 +4202,27 @@ sqlite3 *sqlite3_context_db_handle(sqlite3_context*); ** ** INVARIANTS: ** -** {F16272} The [sqlite3_get_auxdata(C,N)] interface returns a pointer +** {H16272} The [sqlite3_get_auxdata(C,N)] interface returns a pointer ** to metadata associated with the Nth parameter of the SQL function ** whose context is C, or NULL if there is no metadata associated ** with that parameter. ** -** {F16274} The [sqlite3_set_auxdata(C,N,P,D)] interface assigns a metadata -** pointer P to the Nth parameter of the SQL function with context -** C. +** {H16274} The [sqlite3_set_auxdata(C,N,P,D)] interface assigns a metadata +** pointer P to the Nth parameter of the SQL function with context C. ** -** {F16276} SQLite will invoke the destructor D with a single argument +** {H16276} SQLite will invoke the destructor D with a single argument ** which is the metadata pointer P following a call to ** [sqlite3_set_auxdata(C,N,P,D)] when SQLite ceases to hold ** the metadata. ** -** {F16277} SQLite ceases to hold metadata for an SQL function parameter +** {H16277} SQLite ceases to hold metadata for an SQL function parameter ** when the value of that parameter changes. ** -** {F16278} When [sqlite3_set_auxdata(C,N,P,D)] is invoked, the destructor +** {H16278} When [sqlite3_set_auxdata(C,N,P,D)] is invoked, the destructor ** is called for any prior metadata associated with the same function ** context C and parameter N. ** -** {F16279} SQLite will call destructors for any metadata it is holding +** {H16279} SQLite will call destructors for any metadata it is holding ** in a particular [prepared statement] S when either ** [sqlite3_reset(S)] or [sqlite3_finalize(S)] is called. */ @@ -3877,12 +4231,12 @@ void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*)); /* -** CAPI3REF: Constants Defining Special Destructor Behavior {F10280} +** CAPI3REF: Constants Defining Special Destructor Behavior {H10280} <S30100> ** -** These are special value for the destructor that is passed in as the +** These are special values for the destructor that is passed in as the ** final argument to routines like [sqlite3_result_blob()]. If the destructor ** argument is SQLITE_STATIC, it means that the content pointer is constant -** and will never change. It does not need to be destroyed. The +** and will never change. It does not need to be destroyed. The ** SQLITE_TRANSIENT value means that the content will likely change in ** the near future and that SQLite should make its own private copy of ** the content before returning. @@ -3895,30 +4249,28 @@ typedef void (*sqlite3_destructor_type)(void*); #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) /* -** CAPI3REF: Setting The Result Of An SQL Function {F16400} +** CAPI3REF: Setting The Result Of An SQL Function {H16400} <S20200> ** ** These routines are used by the xFunc or xFinal callbacks that ** implement SQL functions and aggregates. See ** [sqlite3_create_function()] and [sqlite3_create_function16()] ** for additional information. ** -** These functions work very much like the -** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used -** to bind values to host parameters in prepared statements. -** Refer to the -** [sqlite3_bind_blob | sqlite3_bind_* documentation] for -** additional information. +** These functions work very much like the [parameter binding] family of +** functions used to bind values to host parameters in prepared statements. +** Refer to the [SQL parameter] documentation for additional information. ** ** The sqlite3_result_blob() interface sets the result from -** an application defined function to be the BLOB whose content is pointed +** an application-defined function to be the BLOB whose content is pointed ** to by the second parameter and which is N bytes long where N is the -** third parameter. -** The sqlite3_result_zeroblob() inerfaces set the result of -** the application defined function to be a BLOB containing all zero +** third parameter. +** +** The sqlite3_result_zeroblob() interfaces set the result of +** the application-defined function to be a BLOB containing all zero ** bytes and N bytes in size, where N is the value of the 2nd parameter. ** ** The sqlite3_result_double() interface sets the result from -** an application defined function to be a floating point value specified +** an application-defined function to be a floating point value specified ** by its 2nd argument. ** ** The sqlite3_result_error() and sqlite3_result_error16() functions @@ -3926,8 +4278,8 @@ typedef void (*sqlite3_destructor_type)(void*); ** SQLite uses the string pointed to by the ** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16() ** as the text of an error message. SQLite interprets the error -** message string from sqlite3_result_error() as UTF8. SQLite -** interprets the string from sqlite3_result_error16() as UTF16 in native +** message string from sqlite3_result_error() as UTF-8. SQLite +** interprets the string from sqlite3_result_error16() as UTF-16 in native ** byte order. If the third parameter to sqlite3_result_error() ** or sqlite3_result_error16() is negative then SQLite takes as the error ** message all text up through the first zero character. @@ -3935,7 +4287,7 @@ typedef void (*sqlite3_destructor_type)(void*); ** sqlite3_result_error16() is non-negative then SQLite takes that many ** bytes (not characters) from the 2nd parameter as the error message. ** The sqlite3_result_error() and sqlite3_result_error16() -** routines make a copy private copy of the error message text before +** routines make a private copy of the error message text before ** they return. Hence, the calling function can deallocate or ** modify the text after they return without harm. ** The sqlite3_result_error_code() function changes the error code @@ -3943,11 +4295,11 @@ typedef void (*sqlite3_destructor_type)(void*); ** the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error() ** or sqlite3_result_error16() resets the error code to SQLITE_ERROR. ** -** The sqlite3_result_toobig() interface causes SQLite -** to throw an error indicating that a string or BLOB is to long -** to represent. The sqlite3_result_nomem() interface -** causes SQLite to throw an exception indicating that the a -** memory allocation failed. +** The sqlite3_result_toobig() interface causes SQLite to throw an error +** indicating that a string or BLOB is to long to represent. +** +** The sqlite3_result_nomem() interface causes SQLite to throw an error +** indicating that a memory allocation failed. ** ** The sqlite3_result_int() interface sets the return value ** of the application-defined function to be the 32-bit signed integer @@ -3959,7 +4311,7 @@ typedef void (*sqlite3_destructor_type)(void*); ** The sqlite3_result_null() interface sets the return value ** of the application-defined function to be NULL. ** -** The sqlite3_result_text(), sqlite3_result_text16(), +** The sqlite3_result_text(), sqlite3_result_text16(), ** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces ** set the return value of the application-defined function to be ** a text string which is represented as UTF-8, UTF-16 native byte order, @@ -3967,7 +4319,7 @@ typedef void (*sqlite3_destructor_type)(void*); ** SQLite takes the text result from the application from ** the 2nd parameter of the sqlite3_result_text* interfaces. ** If the 3rd parameter to the sqlite3_result_text* interfaces -** is negative, then SQLite takes result text from the 2nd parameter +** is negative, then SQLite takes result text from the 2nd parameter ** through the first zero character. ** If the 3rd parameter to the sqlite3_result_text* interfaces ** is non-negative, then as many bytes (not characters) of the text @@ -3975,13 +4327,12 @@ typedef void (*sqlite3_destructor_type)(void*); ** function result. ** If the 4th parameter to the sqlite3_result_text* interfaces ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that -** function as the destructor on the text or blob result when it has -** finished using that result. -** If the 4th parameter to the sqlite3_result_text* interfaces -** or sqlite3_result_blob is the special constant SQLITE_STATIC, then -** SQLite assumes that the text or blob result is constant space and -** does not copy the space or call a destructor when it has +** function as the destructor on the text or BLOB result when it has ** finished using that result. +** If the 4th parameter to the sqlite3_result_text* interfaces or +** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite +** assumes that the text or BLOB result is in constant space and does not +** copy the it or call a destructor when it has finished using that result. ** If the 4th parameter to the sqlite3_result_text* interfaces ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT ** then SQLite makes a copy of the result into space obtained from @@ -3991,109 +4342,109 @@ typedef void (*sqlite3_destructor_type)(void*); ** the application-defined function to be a copy the ** [unprotected sqlite3_value] object specified by the 2nd parameter. The ** sqlite3_result_value() interface makes a copy of the [sqlite3_value] -** so that [sqlite3_value] specified in the parameter may change or +** so that the [sqlite3_value] specified in the parameter may change or ** be deallocated after sqlite3_result_value() returns without harm. ** A [protected sqlite3_value] object may always be used where an ** [unprotected sqlite3_value] object is required, so either ** kind of [sqlite3_value] object can be used with this interface. ** -** If these routines are called from within the different thread -** than the one containing the application-defined function that recieved +** If these routines are called from within the different thread +** than the one containing the application-defined function that received ** the [sqlite3_context] pointer, the results are undefined. ** ** INVARIANTS: ** -** {F16403} The default return value from any SQL function is NULL. +** {H16403} The default return value from any SQL function is NULL. ** -** {F16406} The [sqlite3_result_blob(C,V,N,D)] interface changes the -** return value of function C to be a blob that is N bytes +** {H16406} The [sqlite3_result_blob(C,V,N,D)] interface changes the +** return value of function C to be a BLOB that is N bytes ** in length and with content pointed to by V. ** -** {F16409} The [sqlite3_result_double(C,V)] interface changes the +** {H16409} The [sqlite3_result_double(C,V)] interface changes the ** return value of function C to be the floating point value V. ** -** {F16412} The [sqlite3_result_error(C,V,N)] interface changes the return +** {H16412} The [sqlite3_result_error(C,V,N)] interface changes the return ** value of function C to be an exception with error code -** [SQLITE_ERROR] and a UTF8 error message copied from V up to the +** [SQLITE_ERROR] and a UTF-8 error message copied from V up to the ** first zero byte or until N bytes are read if N is positive. ** -** {F16415} The [sqlite3_result_error16(C,V,N)] interface changes the return +** {H16415} The [sqlite3_result_error16(C,V,N)] interface changes the return ** value of function C to be an exception with error code -** [SQLITE_ERROR] and a UTF16 native byte order error message +** [SQLITE_ERROR] and a UTF-16 native byte order error message ** copied from V up to the first zero terminator or until N bytes ** are read if N is positive. ** -** {F16418} The [sqlite3_result_error_toobig(C)] interface changes the return +** {H16418} The [sqlite3_result_error_toobig(C)] interface changes the return ** value of the function C to be an exception with error code ** [SQLITE_TOOBIG] and an appropriate error message. ** -** {F16421} The [sqlite3_result_error_nomem(C)] interface changes the return +** {H16421} The [sqlite3_result_error_nomem(C)] interface changes the return ** value of the function C to be an exception with error code ** [SQLITE_NOMEM] and an appropriate error message. ** -** {F16424} The [sqlite3_result_error_code(C,E)] interface changes the return +** {H16424} The [sqlite3_result_error_code(C,E)] interface changes the return ** value of the function C to be an exception with error code E. ** The error message text is unchanged. ** -** {F16427} The [sqlite3_result_int(C,V)] interface changes the +** {H16427} The [sqlite3_result_int(C,V)] interface changes the ** return value of function C to be the 32-bit integer value V. ** -** {F16430} The [sqlite3_result_int64(C,V)] interface changes the +** {H16430} The [sqlite3_result_int64(C,V)] interface changes the ** return value of function C to be the 64-bit integer value V. ** -** {F16433} The [sqlite3_result_null(C)] interface changes the +** {H16433} The [sqlite3_result_null(C)] interface changes the ** return value of function C to be NULL. ** -** {F16436} The [sqlite3_result_text(C,V,N,D)] interface changes the -** return value of function C to be the UTF8 string +** {H16436} The [sqlite3_result_text(C,V,N,D)] interface changes the +** return value of function C to be the UTF-8 string ** V up to the first zero if N is negative ** or the first N bytes of V if N is non-negative. ** -** {F16439} The [sqlite3_result_text16(C,V,N,D)] interface changes the -** return value of function C to be the UTF16 native byte order -** string V up to the first zero if N is -** negative or the first N bytes of V if N is non-negative. +** {H16439} The [sqlite3_result_text16(C,V,N,D)] interface changes the +** return value of function C to be the UTF-16 native byte order +** string V up to the first zero if N is negative +** or the first N bytes of V if N is non-negative. ** -** {F16442} The [sqlite3_result_text16be(C,V,N,D)] interface changes the -** return value of function C to be the UTF16 big-endian -** string V up to the first zero if N is -** is negative or the first N bytes or V if N is non-negative. +** {H16442} The [sqlite3_result_text16be(C,V,N,D)] interface changes the +** return value of function C to be the UTF-16 big-endian +** string V up to the first zero if N is negative +** or the first N bytes or V if N is non-negative. ** -** {F16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the -** return value of function C to be the UTF16 little-endian -** string V up to the first zero if N is -** negative or the first N bytes of V if N is non-negative. +** {H16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the +** return value of function C to be the UTF-16 little-endian +** string V up to the first zero if N is negative +** or the first N bytes of V if N is non-negative. ** -** {F16448} The [sqlite3_result_value(C,V)] interface changes the -** return value of function C to be [unprotected sqlite3_value] +** {H16448} The [sqlite3_result_value(C,V)] interface changes the +** return value of function C to be the [unprotected sqlite3_value] ** object V. ** -** {F16451} The [sqlite3_result_zeroblob(C,N)] interface changes the -** return value of function C to be an N-byte blob of all zeros. +** {H16451} The [sqlite3_result_zeroblob(C,N)] interface changes the +** return value of function C to be an N-byte BLOB of all zeros. ** -** {F16454} The [sqlite3_result_error()] and [sqlite3_result_error16()] +** {H16454} The [sqlite3_result_error()] and [sqlite3_result_error16()] ** interfaces make a copy of their error message strings before ** returning. ** -** {F16457} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], +** {H16457} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)], ** [sqlite3_result_text16be(C,V,N,D)], or ** [sqlite3_result_text16le(C,V,N,D)] is the constant [SQLITE_STATIC] ** then no destructor is ever called on the pointer V and SQLite ** assumes that V is immutable. ** -** {F16460} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], +** {H16460} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)], ** [sqlite3_result_text16be(C,V,N,D)], or ** [sqlite3_result_text16le(C,V,N,D)] is the constant ** [SQLITE_TRANSIENT] then the interfaces makes a copy of the ** content of V and retains the copy. ** -** {F16463} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], +** {H16463} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)], ** [sqlite3_result_text16be(C,V,N,D)], or ** [sqlite3_result_text16le(C,V,N,D)] is some value other than -** the constants [SQLITE_STATIC] and [SQLITE_TRANSIENT] then +** the constants [SQLITE_STATIC] and [SQLITE_TRANSIENT] then ** SQLite will invoke the destructor D with V as its only argument ** when it has finished with the V value. */ @@ -4115,10 +4466,10 @@ void sqlite3_result_value(sqlite3_context*, sqlite3_value*); void sqlite3_result_zeroblob(sqlite3_context*, int n); /* -** CAPI3REF: Define New Collating Sequences {F16600} +** CAPI3REF: Define New Collating Sequences {H16600} <S20300> ** ** These functions are used to add new collation sequences to the -** [sqlite3*] handle specified as the first argument. +** [database connection] specified as the first argument. ** ** The name of the new collation sequence is specified as a UTF-8 string ** for sqlite3_create_collation() and sqlite3_create_collation_v2() @@ -4128,81 +4479,79 @@ void sqlite3_result_zeroblob(sqlite3_context*, int n); ** The third argument may be one of the constants [SQLITE_UTF8], ** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied ** routine expects to be passed pointers to strings encoded using UTF-8, -** UTF-16 little-endian or UTF-16 big-endian respectively. The +** UTF-16 little-endian, or UTF-16 big-endian, respectively. The ** third argument might also be [SQLITE_UTF16_ALIGNED] to indicate that ** the routine expects pointers to 16-bit word aligned strings -** of UTF16 in the native byte order of the host computer. +** of UTF-16 in the native byte order of the host computer. ** ** A pointer to the user supplied routine must be passed as the fifth ** argument. If it is NULL, this is the same as deleting the collation ** sequence (so that SQLite cannot call it anymore). -** Each time the application -** supplied function is invoked, it is passed a copy of the void* passed as -** the fourth argument to sqlite3_create_collation() or -** sqlite3_create_collation16() as its first parameter. +** Each time the application supplied function is invoked, it is passed +** as its first parameter a copy of the void* passed as the fourth argument +** to sqlite3_create_collation() or sqlite3_create_collation16(). ** ** The remaining arguments to the application-supplied routine are two strings, ** each represented by a (length, data) pair and encoded in the encoding ** that was passed as the third argument when the collation sequence was -** registered. {END} The application defined collation routine should -** return negative, zero or positive if -** the first string is less than, equal to, or greater than the second -** string. i.e. (STRING1 - STRING2). +** registered. {END} The application defined collation routine should +** return negative, zero or positive if the first string is less than, +** equal to, or greater than the second string. i.e. (STRING1 - STRING2). ** ** The sqlite3_create_collation_v2() works like sqlite3_create_collation() -** excapt that it takes an extra argument which is a destructor for +** except that it takes an extra argument which is a destructor for ** the collation. The destructor is called when the collation is ** destroyed and is passed a copy of the fourth parameter void* pointer ** of the sqlite3_create_collation_v2(). -** Collations are destroyed when -** they are overridden by later calls to the collation creation functions -** or when the [sqlite3*] database handle is closed using [sqlite3_close()]. +** Collations are destroyed when they are overridden by later calls to the +** collation creation functions or when the [database connection] is closed +** using [sqlite3_close()]. ** ** INVARIANTS: ** -** {F16603} A successful call to the +** {H16603} A successful call to the ** [sqlite3_create_collation_v2(B,X,E,P,F,D)] interface ** registers function F as the comparison function used to -** implement collation X on [database connection] B for +** implement collation X on the [database connection] B for ** databases having encoding E. ** -** {F16604} SQLite understands the X parameter to +** {H16604} SQLite understands the X parameter to ** [sqlite3_create_collation_v2(B,X,E,P,F,D)] as a zero-terminated ** UTF-8 string in which case is ignored for ASCII characters and ** is significant for non-ASCII characters. ** -** {F16606} Successive calls to [sqlite3_create_collation_v2(B,X,E,P,F,D)] +** {H16606} Successive calls to [sqlite3_create_collation_v2(B,X,E,P,F,D)] ** with the same values for B, X, and E, override prior values ** of P, F, and D. ** -** {F16609} The destructor D in [sqlite3_create_collation_v2(B,X,E,P,F,D)] +** {H16609} If the destructor D in [sqlite3_create_collation_v2(B,X,E,P,F,D)] ** is not NULL then it is called with argument P when the ** collating function is dropped by SQLite. ** -** {F16612} A collating function is dropped when it is overloaded. +** {H16612} A collating function is dropped when it is overloaded. ** -** {F16615} A collating function is dropped when the database connection +** {H16615} A collating function is dropped when the database connection ** is closed using [sqlite3_close()]. ** -** {F16618} The pointer P in [sqlite3_create_collation_v2(B,X,E,P,F,D)] +** {H16618} The pointer P in [sqlite3_create_collation_v2(B,X,E,P,F,D)] ** is passed through as the first parameter to the comparison ** function F for all subsequent invocations of F. ** -** {F16621} A call to [sqlite3_create_collation(B,X,E,P,F)] is exactly +** {H16621} A call to [sqlite3_create_collation(B,X,E,P,F)] is exactly ** the same as a call to [sqlite3_create_collation_v2()] with ** the same parameters and a NULL destructor. ** -** {F16624} Following a [sqlite3_create_collation_v2(B,X,E,P,F,D)], +** {H16624} Following a [sqlite3_create_collation_v2(B,X,E,P,F,D)], ** SQLite uses the comparison function F for all text comparison -** operations on [database connection] B on text values that -** use the collating sequence name X. +** operations on the [database connection] B on text values that +** use the collating sequence named X. ** -** {F16627} The [sqlite3_create_collation16(B,X,E,P,F)] works the same +** {H16627} The [sqlite3_create_collation16(B,X,E,P,F)] works the same ** as [sqlite3_create_collation(B,X,E,P,F)] except that the ** collation name X is understood as UTF-16 in native byte order ** instead of UTF-8. ** -** {F16630} When multiple comparison functions are available for the same +** {H16630} When multiple comparison functions are available for the same ** collating sequence, SQLite chooses the one whose text encoding ** requires the least amount of conversion from the default ** text encoding of the database. @@ -4224,33 +4573,32 @@ int sqlite3_create_collation_v2( ); int sqlite3_create_collation16( sqlite3*, - const char *zName, + const void *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*) ); /* -** CAPI3REF: Collation Needed Callbacks {F16700} +** CAPI3REF: Collation Needed Callbacks {H16700} <S20300> ** ** To avoid having to register all collation sequences before a database ** can be used, a single callback function may be registered with the -** database handle to be called whenever an undefined collation sequence is -** required. +** [database connection] to be called whenever an undefined collation +** sequence is required. ** ** If the function is registered using the sqlite3_collation_needed() API, ** then it is passed the names of undefined collation sequences as strings -** encoded in UTF-8. {F16703} If sqlite3_collation_needed16() is used, the names -** are passed as UTF-16 in machine native byte order. A call to either -** function replaces any existing callback. +** encoded in UTF-8. {H16703} If sqlite3_collation_needed16() is used, +** the names are passed as UTF-16 in machine native byte order. +** A call to either function replaces any existing callback. ** ** When the callback is invoked, the first argument passed is a copy ** of the second argument to sqlite3_collation_needed() or ** sqlite3_collation_needed16(). The second argument is the database -** handle. The third argument is one of [SQLITE_UTF8], -** [SQLITE_UTF16BE], or [SQLITE_UTF16LE], indicating the most -** desirable form of the collation sequence function required. -** The fourth parameter is the name of the +** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], +** or [SQLITE_UTF16LE], indicating the most desirable form of the collation +** sequence function required. The fourth parameter is the name of the ** required collation sequence. ** ** The callback function should register the desired collation using @@ -4259,24 +4607,22 @@ int sqlite3_create_collation16( ** ** INVARIANTS: ** -** {F16702} A successful call to [sqlite3_collation_needed(D,P,F)] +** {H16702} A successful call to [sqlite3_collation_needed(D,P,F)] ** or [sqlite3_collation_needed16(D,P,F)] causes ** the [database connection] D to invoke callback F with first ** parameter P whenever it needs a comparison function for a ** collating sequence that it does not know about. ** -** {F16704} Each successful call to [sqlite3_collation_needed()] or +** {H16704} Each successful call to [sqlite3_collation_needed()] or ** [sqlite3_collation_needed16()] overrides the callback registered ** on the same [database connection] by prior calls to either ** interface. ** -** {F16706} The name of the requested collating function passed in the +** {H16706} The name of the requested collating function passed in the ** 4th parameter to the callback is in UTF-8 if the callback ** was registered using [sqlite3_collation_needed()] and ** is in UTF-16 native byte order if the callback was ** registered using [sqlite3_collation_needed16()]. -** -** */ int sqlite3_collation_needed( sqlite3*, @@ -4315,15 +4661,14 @@ int sqlite3_rekey( ); /* -** CAPI3REF: Suspend Execution For A Short Time {F10530} +** CAPI3REF: Suspend Execution For A Short Time {H10530} <S40410> ** -** The sqlite3_sleep() function -** causes the current thread to suspend execution +** The sqlite3_sleep() function causes the current thread to suspend execution ** for at least a number of milliseconds specified in its parameter. ** -** If the operating system does not support sleep requests with -** millisecond time resolution, then the time will be rounded up to -** the nearest second. The number of milliseconds of sleep actually +** If the operating system does not support sleep requests with +** millisecond time resolution, then the time will be rounded up to +** the nearest second. The number of milliseconds of sleep actually ** requested from the operating system is returned. ** ** SQLite implements this interface by calling the xSleep() @@ -4331,27 +4676,27 @@ int sqlite3_rekey( ** ** INVARIANTS: ** -** {F10533} The [sqlite3_sleep(M)] interface invokes the xSleep +** {H10533} The [sqlite3_sleep(M)] interface invokes the xSleep ** method of the default [sqlite3_vfs|VFS] in order to ** suspend execution of the current thread for at least ** M milliseconds. ** -** {F10536} The [sqlite3_sleep(M)] interface returns the number of +** {H10536} The [sqlite3_sleep(M)] interface returns the number of ** milliseconds of sleep actually requested of the operating ** system, which might be larger than the parameter M. */ int sqlite3_sleep(int); /* -** CAPI3REF: Name Of The Folder Holding Temporary Files {F10310} +** CAPI3REF: Name Of The Folder Holding Temporary Files {H10310} <S20000> ** ** If this global variable is made to point to a string which is -** the name of a folder (a.ka. directory), then all temporary files +** the name of a folder (a.k.a. directory), then all temporary files ** created by SQLite will be placed in that directory. If this variable -** is NULL pointer, then SQLite does a search for an appropriate temporary -** file directory. +** is a NULL pointer, then SQLite performs a search for an appropriate +** temporary file directory. ** -** It is not safe to modify this variable once a database connection +** It is not safe to modify this variable once a [database connection] ** has been opened. It is intended that this variable be set once ** as part of process initialization and before any SQLite interface ** routines have been call and remain unchanged thereafter. @@ -4359,65 +4704,99 @@ int sqlite3_sleep(int); SQLITE_EXTERN char *sqlite3_temp_directory; /* -** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode {F12930} +** CAPI3REF: Test For Auto-Commit Mode {H12930} <S60200> +** KEYWORDS: {autocommit mode} ** -** The sqlite3_get_autocommit() interfaces returns non-zero or +** The sqlite3_get_autocommit() interface returns non-zero or ** zero if the given database connection is or is not in autocommit mode, -** respectively. Autocommit mode is on -** by default. Autocommit mode is disabled by a [BEGIN] statement. -** Autocommit mode is reenabled by a [COMMIT] or [ROLLBACK]. +** respectively. Autocommit mode is on by default. +** Autocommit mode is disabled by a [BEGIN] statement. +** Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK]. ** ** If certain kinds of errors occur on a statement within a multi-statement -** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR], +** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR], ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the ** transaction might be rolled back automatically. The only way to -** find out if SQLite automatically rolled back the transaction after +** find out whether SQLite automatically rolled back the transaction after ** an error is to use this function. ** ** INVARIANTS: ** -** {F12931} The [sqlite3_get_autocommit(D)] interface returns non-zero or +** {H12931} The [sqlite3_get_autocommit(D)] interface returns non-zero or ** zero if the [database connection] D is or is not in autocommit ** mode, respectively. ** -** {F12932} Autocommit mode is on by default. +** {H12932} Autocommit mode is on by default. ** -** {F12933} Autocommit mode is disabled by a successful [BEGIN] statement. +** {H12933} Autocommit mode is disabled by a successful [BEGIN] statement. ** -** {F12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK] +** {H12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK] ** statement. -** ** -** LIMITATIONS: -*** -** {U12936} If another thread changes the autocommit status of the database +** ASSUMPTIONS: +** +** {A12936} If another thread changes the autocommit status of the database ** connection while this routine is running, then the return value ** is undefined. */ int sqlite3_get_autocommit(sqlite3*); /* -** CAPI3REF: Find The Database Handle Of A Prepared Statement {F13120} +** CAPI3REF: Find The Database Handle Of A Prepared Statement {H13120} <S60600> ** -** The sqlite3_db_handle interface -** returns the [sqlite3*] database handle to which a -** [prepared statement] belongs. -** The database handle returned by sqlite3_db_handle -** is the same database handle that was -** the first argument to the [sqlite3_prepare_v2()] or its variants -** that was used to create the statement in the first place. +** The sqlite3_db_handle interface returns the [database connection] handle +** to which a [prepared statement] belongs. The database handle returned by +** sqlite3_db_handle is the same database handle that was the first argument +** to the [sqlite3_prepare_v2()] call (or its variants) that was used to +** create the statement in the first place. ** ** INVARIANTS: ** -** {F13123} The [sqlite3_db_handle(S)] interface returns a pointer -** to the [database connection] associated with +** {H13123} The [sqlite3_db_handle(S)] interface returns a pointer +** to the [database connection] associated with the ** [prepared statement] S. */ sqlite3 *sqlite3_db_handle(sqlite3_stmt*); +/* +** CAPI3REF: Find the next prepared statement {H13140} <S60600> +** +** This interface returns a pointer to the next [prepared statement] after +** pStmt associated with the [database connection] pDb. If pStmt is NULL +** then this interface returns a pointer to the first prepared statement +** associated with the database connection pDb. If no prepared statement +** satisfies the conditions of this routine, it returns NULL. +** +** INVARIANTS: +** +** {H13143} If D is a [database connection] that holds one or more +** unfinalized [prepared statements] and S is a NULL pointer, +** then [sqlite3_next_stmt(D, S)] routine shall return a pointer +** to one of the prepared statements associated with D. +** +** {H13146} If D is a [database connection] that holds no unfinalized +** [prepared statements] and S is a NULL pointer, then +** [sqlite3_next_stmt(D, S)] routine shall return a NULL pointer. +** +** {H13149} If S is a [prepared statement] in the [database connection] D +** and S is not the last prepared statement in D, then +** [sqlite3_next_stmt(D, S)] routine shall return a pointer +** to the next prepared statement in D after S. +** +** {H13152} If S is the last [prepared statement] in the +** [database connection] D then the [sqlite3_next_stmt(D, S)] +** routine shall return a NULL pointer. +** +** ASSUMPTIONS: +** +** {A13154} The [database connection] pointer D in a call to +** [sqlite3_next_stmt(D,S)] must refer to an open database +** connection and in particular must not be a NULL pointer. +*/ +sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt); /* -** CAPI3REF: Commit And Rollback Notification Callbacks {F12950} +** CAPI3REF: Commit And Rollback Notification Callbacks {H12950} <S60400> ** ** The sqlite3_commit_hook() interface registers a callback ** function to be invoked whenever a transaction is committed. @@ -4427,16 +4806,16 @@ sqlite3 *sqlite3_db_handle(sqlite3_stmt*); ** function to be invoked whenever a transaction is committed. ** Any callback set by a previous call to sqlite3_commit_hook() ** for the same database connection is overridden. -** The pArg argument is passed through -** to the callback. If the callback on a commit hook function -** returns non-zero, then the commit is converted into a rollback. +** The pArg argument is passed through to the callback. +** If the callback on a commit hook function returns non-zero, +** then the commit is converted into a rollback. ** ** If another function was previously registered, its ** pArg value is returned. Otherwise NULL is returned. ** ** Registering a NULL function disables the callback. ** -** For the purposes of this API, a transaction is said to have been +** For the purposes of this API, a transaction is said to have been ** rolled back if an explicit "ROLLBACK" statement is executed, or ** an error or constraint causes an implicit rollback to occur. ** The rollback callback is not invoked if a transaction is @@ -4445,71 +4824,65 @@ sqlite3 *sqlite3_db_handle(sqlite3_stmt*); ** rolled back because a commit callback returned non-zero. ** <todo> Check on this </todo> ** -** These are experimental interfaces and are subject to change. -** ** INVARIANTS: ** -** {F12951} The [sqlite3_commit_hook(D,F,P)] interface registers the +** {H12951} The [sqlite3_commit_hook(D,F,P)] interface registers the ** callback function F to be invoked with argument P whenever -** a transaction commits on [database connection] D. +** a transaction commits on the [database connection] D. ** -** {F12952} The [sqlite3_commit_hook(D,F,P)] interface returns the P -** argument from the previous call with the same -** [database connection ] D , or NULL on the first call -** for a particular [database connection] D. +** {H12952} The [sqlite3_commit_hook(D,F,P)] interface returns the P argument +** from the previous call with the same [database connection] D, +** or NULL on the first call for a particular database connection D. ** -** {F12953} Each call to [sqlite3_commit_hook()] overwrites the callback +** {H12953} Each call to [sqlite3_commit_hook()] overwrites the callback ** registered by prior calls. ** -** {F12954} If the F argument to [sqlite3_commit_hook(D,F,P)] is NULL -** then the commit hook callback is cancelled and no callback +** {H12954} If the F argument to [sqlite3_commit_hook(D,F,P)] is NULL +** then the commit hook callback is canceled and no callback ** is invoked when a transaction commits. ** -** {F12955} If the commit callback returns non-zero then the commit is +** {H12955} If the commit callback returns non-zero then the commit is ** converted into a rollback. ** -** {F12961} The [sqlite3_rollback_hook(D,F,P)] interface registers the +** {H12961} The [sqlite3_rollback_hook(D,F,P)] interface registers the ** callback function F to be invoked with argument P whenever -** a transaction rolls back on [database connection] D. +** a transaction rolls back on the [database connection] D. ** -** {F12962} The [sqlite3_rollback_hook(D,F,P)] interface returns the P -** argument from the previous call with the same -** [database connection ] D , or NULL on the first call -** for a particular [database connection] D. +** {H12962} The [sqlite3_rollback_hook(D,F,P)] interface returns the P +** argument from the previous call with the same +** [database connection] D, or NULL on the first call +** for a particular database connection D. ** -** {F12963} Each call to [sqlite3_rollback_hook()] overwrites the callback +** {H12963} Each call to [sqlite3_rollback_hook()] overwrites the callback ** registered by prior calls. ** -** {F12964} If the F argument to [sqlite3_rollback_hook(D,F,P)] is NULL -** then the rollback hook callback is cancelled and no callback +** {H12964} If the F argument to [sqlite3_rollback_hook(D,F,P)] is NULL +** then the rollback hook callback is canceled and no callback ** is invoked when a transaction rolls back. */ void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); /* -** CAPI3REF: Data Change Notification Callbacks {F12970} -** -** The sqlite3_update_hook() interface -** registers a callback function with the database connection identified by the -** first argument to be invoked whenever a row is updated, inserted or deleted. -** Any callback set by a previous call to this function for the same -** database connection is overridden. -** -** The second argument is a pointer to the function to invoke when a -** row is updated, inserted or deleted. -** The first argument to the callback is -** a copy of the third argument to sqlite3_update_hook(). -** The second callback -** argument is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], -** depending on the operation that caused the callback to be invoked. -** The third and -** fourth arguments to the callback contain pointers to the database and -** table name containing the affected row. -** The final callback parameter is -** the rowid of the row. -** In the case of an update, this is the rowid after -** the update takes place. +** CAPI3REF: Data Change Notification Callbacks {H12970} <S60400> +** +** The sqlite3_update_hook() interface registers a callback function +** with the [database connection] identified by the first argument +** to be invoked whenever a row is updated, inserted or deleted. +** Any callback set by a previous call to this function +** for the same database connection is overridden. +** +** The second argument is a pointer to the function to invoke when a +** row is updated, inserted or deleted. +** The first argument to the callback is a copy of the third argument +** to sqlite3_update_hook(). +** The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE], +** or [SQLITE_UPDATE], depending on the operation that caused the callback +** to be invoked. +** The third and fourth arguments to the callback contain pointers to the +** database and table name containing the affected row. +** The final callback parameter is the rowid of the row. In the case of +** an update, this is the rowid after the update takes place. ** ** The update hook is not invoked when internal system tables are ** modified (i.e. sqlite_master and sqlite_sequence). @@ -4519,33 +4892,33 @@ void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); ** ** INVARIANTS: ** -** {F12971} The [sqlite3_update_hook(D,F,P)] interface causes callback +** {H12971} The [sqlite3_update_hook(D,F,P)] interface causes the callback ** function F to be invoked with first parameter P whenever ** a table row is modified, inserted, or deleted on -** [database connection] D. +** the [database connection] D. ** -** {F12973} The [sqlite3_update_hook(D,F,P)] interface returns the value +** {H12973} The [sqlite3_update_hook(D,F,P)] interface returns the value ** of P for the previous call on the same [database connection] D, ** or NULL for the first call. ** -** {F12975} If the update hook callback F in [sqlite3_update_hook(D,F,P)] +** {H12975} If the update hook callback F in [sqlite3_update_hook(D,F,P)] ** is NULL then the no update callbacks are made. ** -** {F12977} Each call to [sqlite3_update_hook(D,F,P)] overrides prior calls +** {H12977} Each call to [sqlite3_update_hook(D,F,P)] overrides prior calls ** to the same interface on the same [database connection] D. ** -** {F12979} The update hook callback is not invoked when internal system +** {H12979} The update hook callback is not invoked when internal system ** tables such as sqlite_master and sqlite_sequence are modified. ** -** {F12981} The second parameter to the update callback +** {H12981} The second parameter to the update callback ** is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], ** depending on the operation that caused the callback to be invoked. ** -** {F12983} The third and fourth arguments to the callback contain pointers +** {H12983} The third and fourth arguments to the callback contain pointers ** to zero-terminated UTF-8 strings which are the names of the ** database and table that is being updated. -** {F12985} The final callback parameter is the rowid of the row after +** {H12985} The final callback parameter is the rowid of the row after ** the change occurs. */ void *sqlite3_update_hook( @@ -4555,96 +4928,92 @@ void *sqlite3_update_hook( ); /* -** CAPI3REF: Enable Or Disable Shared Pager Cache {F10330} +** CAPI3REF: Enable Or Disable Shared Pager Cache {H10330} <S30900> +** KEYWORDS: {shared cache} {shared cache mode} ** ** This routine enables or disables the sharing of the database cache -** and schema data structures between connections to the same database. -** Sharing is enabled if the argument is true and disabled if the argument -** is false. +** and schema data structures between [database connection | connections] +** to the same database. Sharing is enabled if the argument is true +** and disabled if the argument is false. ** -** Cache sharing is enabled and disabled -** for an entire process. {END} This is a change as of SQLite version 3.5.0. -** In prior versions of SQLite, sharing was -** enabled or disabled for each thread separately. +** Cache sharing is enabled and disabled for an entire process. {END} +** This is a change as of SQLite version 3.5.0. In prior versions of SQLite, +** sharing was enabled or disabled for each thread separately. ** ** The cache sharing mode set by this interface effects all subsequent ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. ** Existing database connections continue use the sharing mode ** that was in effect at the time they were opened. ** -** Virtual tables cannot be used with a shared cache. When shared +** Virtual tables cannot be used with a shared cache. When shared ** cache is enabled, the [sqlite3_create_module()] API used to register ** virtual tables will always return an error. ** -** This routine returns [SQLITE_OK] if shared cache was -** enabled or disabled successfully. An [error code] -** is returned otherwise. +** This routine returns [SQLITE_OK] if shared cache was enabled or disabled +** successfully. An [error code] is returned otherwise. ** ** Shared cache is disabled by default. But this might change in ** future releases of SQLite. Applications that care about shared ** cache setting should set it explicitly. ** ** INVARIANTS: -** -** {F10331} A successful invocation of [sqlite3_enable_shared_cache(B)] +** +** {H10331} A successful invocation of [sqlite3_enable_shared_cache(B)] ** will enable or disable shared cache mode for any subsequently ** created [database connection] in the same process. ** -** {F10336} When shared cache is enabled, the [sqlite3_create_module()] +** {H10336} When shared cache is enabled, the [sqlite3_create_module()] ** interface will always return an error. ** -** {F10337} The [sqlite3_enable_shared_cache(B)] interface returns +** {H10337} The [sqlite3_enable_shared_cache(B)] interface returns ** [SQLITE_OK] if shared cache was enabled or disabled successfully. ** -** {F10339} Shared cache is disabled by default. +** {H10339} Shared cache is disabled by default. */ int sqlite3_enable_shared_cache(int); /* -** CAPI3REF: Attempt To Free Heap Memory {F17340} +** CAPI3REF: Attempt To Free Heap Memory {H17340} <S30220> ** -** The sqlite3_release_memory() interface attempts to -** free N bytes of heap memory by deallocating non-essential memory -** allocations held by the database labrary. {END} Memory used -** to cache database pages to improve performance is an example of -** non-essential memory. Sqlite3_release_memory() returns -** the number of bytes actually freed, which might be more or less -** than the amount requested. +** The sqlite3_release_memory() interface attempts to free N bytes +** of heap memory by deallocating non-essential memory allocations +** held by the database library. {END} Memory used to cache database +** pages to improve performance is an example of non-essential memory. +** sqlite3_release_memory() returns the number of bytes actually freed, +** which might be more or less than the amount requested. ** ** INVARIANTS: ** -** {F17341} The [sqlite3_release_memory(N)] interface attempts to +** {H17341} The [sqlite3_release_memory(N)] interface attempts to ** free N bytes of heap memory by deallocating non-essential -** memory allocations held by the database labrary. +** memory allocations held by the database library. ** -** {F16342} The [sqlite3_release_memory(N)] returns the number +** {H16342} The [sqlite3_release_memory(N)] returns the number ** of bytes actually freed, which might be more or less ** than the amount requested. */ int sqlite3_release_memory(int); /* -** CAPI3REF: Impose A Limit On Heap Size {F17350} +** CAPI3REF: Impose A Limit On Heap Size {H17350} <S30220> ** -** The sqlite3_soft_heap_limit() interface -** places a "soft" limit on the amount of heap memory that may be allocated -** by SQLite. If an internal allocation is requested -** that would exceed the soft heap limit, [sqlite3_release_memory()] is -** invoked one or more times to free up some space before the allocation -** is made. +** The sqlite3_soft_heap_limit() interface places a "soft" limit +** on the amount of heap memory that may be allocated by SQLite. +** If an internal allocation is requested that would exceed the +** soft heap limit, [sqlite3_release_memory()] is invoked one or +** more times to free up some space before the allocation is performed. ** -** The limit is called "soft", because if -** [sqlite3_release_memory()] cannot -** free sufficient memory to prevent the limit from being exceeded, +** The limit is called "soft", because if [sqlite3_release_memory()] +** cannot free sufficient memory to prevent the limit from being exceeded, ** the memory is allocated anyway and the current operation proceeds. ** ** A negative or zero value for N means that there is no soft heap limit and ** [sqlite3_release_memory()] will only be called when memory is exhausted. ** The default value for the soft heap limit is zero. ** -** SQLite makes a best effort to honor the soft heap limit. -** But if the soft heap limit cannot honored, execution will -** continue without error or notification. This is why the limit is +** SQLite makes a best effort to honor the soft heap limit. +** But if the soft heap limit cannot be honored, execution will +** continue without error or notification. This is why the limit is ** called a "soft" limit. It is advisory only. ** ** Prior to SQLite version 3.5.0, this routine only constrained the memory @@ -4657,81 +5026,79 @@ int sqlite3_release_memory(int); ** ** INVARIANTS: ** -** {F16351} The [sqlite3_soft_heap_limit(N)] interface places a soft limit +** {H16351} The [sqlite3_soft_heap_limit(N)] interface places a soft limit ** of N bytes on the amount of heap memory that may be allocated ** using [sqlite3_malloc()] or [sqlite3_realloc()] at any point ** in time. ** -** {F16352} If a call to [sqlite3_malloc()] or [sqlite3_realloc()] would +** {H16352} If a call to [sqlite3_malloc()] or [sqlite3_realloc()] would ** cause the total amount of allocated memory to exceed the ** soft heap limit, then [sqlite3_release_memory()] is invoked ** in an attempt to reduce the memory usage prior to proceeding ** with the memory allocation attempt. ** -** {F16353} Calls to [sqlite3_malloc()] or [sqlite3_realloc()] that trigger +** {H16353} Calls to [sqlite3_malloc()] or [sqlite3_realloc()] that trigger ** attempts to reduce memory usage through the soft heap limit ** mechanism continue even if the attempt to reduce memory ** usage is unsuccessful. ** -** {F16354} A negative or zero value for N in a call to +** {H16354} A negative or zero value for N in a call to ** [sqlite3_soft_heap_limit(N)] means that there is no soft ** heap limit and [sqlite3_release_memory()] will only be ** called when memory is completely exhausted. ** -** {F16355} The default value for the soft heap limit is zero. +** {H16355} The default value for the soft heap limit is zero. ** -** {F16358} Each call to [sqlite3_soft_heap_limit(N)] overrides the +** {H16358} Each call to [sqlite3_soft_heap_limit(N)] overrides the ** values set by all prior calls. */ void sqlite3_soft_heap_limit(int); /* -** CAPI3REF: Extract Metadata About A Column Of A Table {F12850} +** CAPI3REF: Extract Metadata About A Column Of A Table {H12850} <S60300> ** -** This routine -** returns meta-data about a specific column of a specific database -** table accessible using the connection handle passed as the first function -** argument. +** This routine returns metadata about a specific column of a specific +** database table accessible using the [database connection] handle +** passed as the first function argument. ** -** The column is identified by the second, third and fourth parameters to +** The column is identified by the second, third and fourth parameters to ** this function. The second parameter is either the name of the database ** (i.e. "main", "temp" or an attached database) containing the specified ** table or NULL. If it is NULL, then all attached databases are searched -** for the table using the same algorithm as the database engine uses to +** for the table using the same algorithm used by the database engine to ** resolve unqualified table references. ** -** The third and fourth parameters to this function are the table and column -** name of the desired column, respectively. Neither of these parameters +** The third and fourth parameters to this function are the table and column +** name of the desired column, respectively. Neither of these parameters ** may be NULL. ** -** Meta information is returned by writing to the memory locations passed as -** the 5th and subsequent parameters to this function. Any of these -** arguments may be NULL, in which case the corresponding element of meta -** information is ommitted. +** Metadata is returned by writing to the memory locations passed as the 5th +** and subsequent parameters to this function. Any of these arguments may be +** NULL, in which case the corresponding element of metadata is omitted. ** -** <pre> -** Parameter Output Type Description -** ----------------------------------- -** -** 5th const char* Data type -** 6th const char* Name of the default collation sequence -** 7th int True if the column has a NOT NULL constraint -** 8th int True if the column is part of the PRIMARY KEY -** 9th int True if the column is AUTOINCREMENT -** </pre> +** <blockquote> +** <table border="1"> +** <tr><th> Parameter <th> Output<br>Type <th> Description ** +** <tr><td> 5th <td> const char* <td> Data type +** <tr><td> 6th <td> const char* <td> Name of default collation sequence +** <tr><td> 7th <td> int <td> True if column has a NOT NULL constraint +** <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY +** <tr><td> 9th <td> int <td> True if column is AUTOINCREMENT +** </table> +** </blockquote> ** -** The memory pointed to by the character pointers returned for the -** declaration type and collation sequence is valid only until the next -** call to any sqlite API function. +** The memory pointed to by the character pointers returned for the +** declaration type and collation sequence is valid only until the next +** call to any SQLite API function. ** -** If the specified table is actually a view, then an error is returned. +** If the specified table is actually a view, an [error code] is returned. ** -** If the specified column is "rowid", "oid" or "_rowid_" and an -** INTEGER PRIMARY KEY column has been explicitly declared, then the output +** If the specified column is "rowid", "oid" or "_rowid_" and an +** INTEGER PRIMARY KEY column has been explicitly declared, then the output ** parameters are set for the explicitly declared column. If there is no -** explicitly declared IPK column, then the output parameters are set as -** follows: +** explicitly declared INTEGER PRIMARY KEY column, then the output +** parameters are set as follows: ** ** <pre> ** data type: "INTEGER" @@ -4743,11 +5110,11 @@ void sqlite3_soft_heap_limit(int); ** ** This function may load one or more schemas from database files. If an ** error occurs during this process, or if the requested table or column -** cannot be found, an SQLITE error code is returned and an error message -** left in the database handle (to be retrieved using sqlite3_errmsg()). +** cannot be found, an [error code] is returned and an error message left +** in the [database connection] (to be retrieved using sqlite3_errmsg()). ** ** This API is only available if the library was compiled with the -** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. +** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined. */ int sqlite3_table_column_metadata( sqlite3 *db, /* Connection handle */ @@ -4762,27 +5129,30 @@ int sqlite3_table_column_metadata( ); /* -** CAPI3REF: Load An Extension {F12600} +** CAPI3REF: Load An Extension {H12600} <S20500> +** +** This interface loads an SQLite extension library from the named file. +** +** {H12601} The sqlite3_load_extension() interface attempts to load an +** SQLite extension library contained in the file zFile. ** -** {F12601} The sqlite3_load_extension() interface -** attempts to load an SQLite extension library contained in the file -** zFile. {F12602} The entry point is zProc. {F12603} zProc may be 0 -** in which case the name of the entry point defaults -** to "sqlite3_extension_init". +** {H12602} The entry point is zProc. ** -** {F12604} The sqlite3_load_extension() interface shall -** return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. +** {H12603} zProc may be 0, in which case the name of the entry point +** defaults to "sqlite3_extension_init". ** -** {F12605} -** If an error occurs and pzErrMsg is not 0, then the -** sqlite3_load_extension() interface shall attempt to fill *pzErrMsg with -** error message text stored in memory obtained from [sqlite3_malloc()]. -** {END} The calling function should free this memory -** by calling [sqlite3_free()]. +** {H12604} The sqlite3_load_extension() interface shall return +** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. ** -** {F12606} -** Extension loading must be enabled using [sqlite3_enable_load_extension()] -** prior to calling this API or an error will be returned. +** {H12605} If an error occurs and pzErrMsg is not 0, then the +** [sqlite3_load_extension()] interface shall attempt to +** fill *pzErrMsg with error message text stored in memory +** obtained from [sqlite3_malloc()]. {END} The calling function +** should free this memory by calling [sqlite3_free()]. +** +** {H12606} Extension loading must be enabled using +** [sqlite3_enable_load_extension()] prior to calling this API, +** otherwise an error will be returned. */ int sqlite3_load_extension( sqlite3 *db, /* Load the extension into this database connection */ @@ -4792,65 +5162,64 @@ int sqlite3_load_extension( ); /* -** CAPI3REF: Enable Or Disable Extension Loading {F12620} +** CAPI3REF: Enable Or Disable Extension Loading {H12620} <S20500> ** ** So as not to open security holes in older applications that are ** unprepared to deal with extension loading, and as a means of disabling -** extension loading while evaluating user-entered SQL, the following -** API is provided to turn the [sqlite3_load_extension()] mechanism on and -** off. {F12622} It is off by default. {END} See ticket #1863. +** extension loading while evaluating user-entered SQL, the following API +** is provided to turn the [sqlite3_load_extension()] mechanism on and off. +** +** Extension loading is off by default. See ticket #1863. +** +** {H12621} Call the sqlite3_enable_load_extension() routine with onoff==1 +** to turn extension loading on and call it with onoff==0 to turn +** it back off again. ** -** {F12621} Call the sqlite3_enable_load_extension() routine -** with onoff==1 to turn extension loading on -** and call it with onoff==0 to turn it back off again. {END} +** {H12622} Extension loading is off by default. */ int sqlite3_enable_load_extension(sqlite3 *db, int onoff); /* -** CAPI3REF: Make Arrangements To Automatically Load An Extension {F12640} -** -** {F12641} This function -** registers an extension entry point that is automatically invoked -** whenever a new database connection is opened using -** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()]. {END} +** CAPI3REF: Automatically Load An Extensions {H12640} <S20500> ** ** This API can be invoked at program startup in order to register ** one or more statically linked extensions that will be available -** to all new database connections. +** to all new [database connections]. {END} ** -** {F12642} Duplicate extensions are detected so calling this routine multiple -** times with the same extension is harmless. +** This routine stores a pointer to the extension in an array that is +** obtained from [sqlite3_malloc()]. If you run a memory leak checker +** on your program and it reports a leak because of this array, invoke +** [sqlite3_reset_auto_extension()] prior to shutdown to free the memory. ** -** {F12643} This routine stores a pointer to the extension in an array -** that is obtained from sqlite_malloc(). {END} If you run a memory leak -** checker on your program and it reports a leak because of this -** array, then invoke [sqlite3_reset_auto_extension()] prior -** to shutdown to free the memory. +** {H12641} This function registers an extension entry point that is +** automatically invoked whenever a new [database connection] +** is opened using [sqlite3_open()], [sqlite3_open16()], +** or [sqlite3_open_v2()]. ** -** {F12644} Automatic extensions apply across all threads. {END} +** {H12642} Duplicate extensions are detected so calling this routine +** multiple times with the same extension is harmless. ** -** This interface is experimental and is subject to change or -** removal in future releases of SQLite. +** {H12643} This routine stores a pointer to the extension in an array +** that is obtained from [sqlite3_malloc()]. +** +** {H12644} Automatic extensions apply across all threads. */ int sqlite3_auto_extension(void *xEntryPoint); - /* -** CAPI3REF: Reset Automatic Extension Loading {F12660} +** CAPI3REF: Reset Automatic Extension Loading {H12660} <S20500> ** -** {F12661} This function disables all previously registered -** automatic extensions. {END} This -** routine undoes the effect of all prior [sqlite3_auto_extension()] -** calls. +** This function disables all previously registered automatic +** extensions. {END} It undoes the effect of all prior +** [sqlite3_auto_extension()] calls. ** -** {F12662} This call disabled automatic extensions in all threads. {END} +** {H12661} This function disables all previously registered +** automatic extensions. ** -** This interface is experimental and is subject to change or -** removal in future releases of SQLite. +** {H12662} This function disables automatic extensions in all threads. */ void sqlite3_reset_auto_extension(void); - /* ****** EXPERIMENTAL - subject to change without notice ************** ** @@ -4858,7 +5227,7 @@ void sqlite3_reset_auto_extension(void); ** to be experimental. The interface might change in incompatible ways. ** If this is a problem for you, do not use the interface at this time. ** -** When the virtual-table mechanism stablizes, we will declare the +** When the virtual-table mechanism stabilizes, we will declare the ** interface fixed, support it indefinitely, and remove this comment. */ @@ -4871,12 +5240,16 @@ typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; typedef struct sqlite3_module sqlite3_module; /* -** CAPI3REF: Virtual Table Object {F18000} +** CAPI3REF: Virtual Table Object {H18000} <S20400> ** KEYWORDS: sqlite3_module +** EXPERIMENTAL ** ** A module is a class of virtual tables. Each module is defined ** by an instance of the following structure. This structure consists ** mostly of methods for the module. +** +** This interface is experimental and is subject to change or +** removal in future releases of SQLite. */ struct sqlite3_module { int iVersion; @@ -4905,13 +5278,13 @@ struct sqlite3_module { int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), void **ppArg); - int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); }; /* -** CAPI3REF: Virtual Table Indexing Information {F18100} +** CAPI3REF: Virtual Table Indexing Information {H18100} <S20400> ** KEYWORDS: sqlite3_index_info +** EXPERIMENTAL ** ** The sqlite3_index_info structure and its substructures is used to ** pass information into and receive the reply from the xBestIndex @@ -4919,14 +5292,12 @@ struct sqlite3_module { ** inputs to xBestIndex and are read-only. xBestIndex inserts its ** results into the **Outputs** fields. ** -** The aConstraint[] array records WHERE clause constraints of the -** form: +** The aConstraint[] array records WHERE clause constraints of the form: ** -** column OP expr +** <pre>column OP expr</pre> ** -** Where OP is =, <, <=, >, or >=. -** The particular operator is stored -** in aConstraint[].op. The index of the column is stored in +** where OP is =, <, <=, >, or >=. The particular operator is +** stored in aConstraint[].op. The index of the column is stored in ** aConstraint[].iColumn. aConstraint[].usable is TRUE if the ** expr on the right-hand side can be evaluated (and thus the constraint ** is usable) and false if it cannot. @@ -4958,6 +5329,9 @@ struct sqlite3_module { ** particular lookup. A full scan of a table with N entries should have ** a cost of N. A binary search of a table of N entries should have a ** cost of approximately log(N). +** +** This interface is experimental and is subject to change or +** removal in future releases of SQLite. */ struct sqlite3_index_info { /* Inputs */ @@ -4973,7 +5347,6 @@ struct sqlite3_index_info { int iColumn; /* Column number */ unsigned char desc; /* True for DESC. False for ASC. */ } *aOrderBy; /* The ORDER BY clause */ - /* Outputs */ struct sqlite3_index_constraint_usage { int argvIndex; /* if >0, constraint is part of argv to xFilter */ @@ -4993,12 +5366,16 @@ struct sqlite3_index_info { #define SQLITE_INDEX_CONSTRAINT_MATCH 64 /* -** CAPI3REF: Register A Virtual Table Implementation {F18200} +** CAPI3REF: Register A Virtual Table Implementation {H18200} <S20400> +** EXPERIMENTAL +** +** This routine is used to register a new module name with a +** [database connection]. Module names must be registered before +** creating new virtual tables on the module, or before using +** preexisting virtual tables of the module. ** -** This routine is used to register a new module name with an SQLite -** connection. Module names must be registered before creating new -** virtual tables on the module, or before using preexisting virtual -** tables of the module. +** This interface is experimental and is subject to change or +** removal in future releases of SQLite. */ int sqlite3_create_module( sqlite3 *db, /* SQLite connection to register module with */ @@ -5008,9 +5385,10 @@ int sqlite3_create_module( ); /* -** CAPI3REF: Register A Virtual Table Implementation {F18210} +** CAPI3REF: Register A Virtual Table Implementation {H18210} <S20400> +** EXPERIMENTAL ** -** This routine is identical to the sqlite3_create_module() method above, +** This routine is identical to the [sqlite3_create_module()] method above, ** except that it allows a destructor function to be specified. It is ** even more experimental than the rest of the virtual tables API. */ @@ -5023,24 +5401,28 @@ int sqlite3_create_module_v2( ); /* -** CAPI3REF: Virtual Table Instance Object {F18010} +** CAPI3REF: Virtual Table Instance Object {H18010} <S20400> ** KEYWORDS: sqlite3_vtab +** EXPERIMENTAL ** ** Every module implementation uses a subclass of the following structure ** to describe a particular instance of the module. Each subclass will -** be tailored to the specific needs of the module implementation. The -** purpose of this superclass is to define certain fields that are common -** to all module implementations. +** be tailored to the specific needs of the module implementation. +** The purpose of this superclass is to define certain fields that are +** common to all module implementations. ** ** Virtual tables methods can set an error message by assigning a -** string obtained from sqlite3_mprintf() to zErrMsg. The method should -** take care that any prior string is freed by a call to sqlite3_free() +** string obtained from [sqlite3_mprintf()] to zErrMsg. The method should +** take care that any prior string is freed by a call to [sqlite3_free()] ** prior to assigning a new string to zErrMsg. After the error message ** is delivered up to the client application, the string will be automatically ** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note ** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field ** since virtual tables are commonly implemented in loadable extensions which ** do not have access to sqlite3MPrintf() or sqlite3Free(). +** +** This interface is experimental and is subject to change or +** removal in future releases of SQLite. */ struct sqlite3_vtab { const sqlite3_module *pModule; /* The module for this virtual table */ @@ -5050,8 +5432,9 @@ struct sqlite3_vtab { }; /* -** CAPI3REF: Virtual Table Cursor Object {F18020} +** CAPI3REF: Virtual Table Cursor Object {H18020} <S20400> ** KEYWORDS: sqlite3_vtab_cursor +** EXPERIMENTAL ** ** Every module implementation uses a subclass of the following structure ** to describe cursors that point into the virtual table and are used @@ -5061,6 +5444,9 @@ struct sqlite3_vtab { ** ** This superclass exists in order to define fields of the cursor that ** are common to all implementations. +** +** This interface is experimental and is subject to change or +** removal in future releases of SQLite. */ struct sqlite3_vtab_cursor { sqlite3_vtab *pVtab; /* Virtual table of this cursor */ @@ -5068,16 +5454,21 @@ struct sqlite3_vtab_cursor { }; /* -** CAPI3REF: Declare The Schema Of A Virtual Table {F18280} +** CAPI3REF: Declare The Schema Of A Virtual Table {H18280} <S20400> +** EXPERIMENTAL ** ** The xCreate and xConnect methods of a module use the following API ** to declare the format (the names and datatypes of the columns) of ** the virtual tables they implement. +** +** This interface is experimental and is subject to change or +** removal in future releases of SQLite. */ int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); /* -** CAPI3REF: Overload A Function For A Virtual Table {F18300} +** CAPI3REF: Overload A Function For A Virtual Table {H18300} <S20400> +** EXPERIMENTAL ** ** Virtual tables can provide alternative implementations of functions ** using the xFindFunction method. But global versions of those functions @@ -5088,7 +5479,7 @@ int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); ** before this API is called, a new function is created. The implementation ** of the new function always causes an exception to be thrown. So ** the new function is not good for anything by itself. Its only -** purpose is to be a place-holder function that can be overloaded +** purpose is to be a placeholder function that can be overloaded ** by virtual tables. ** ** This API should be considered part of the virtual table interface, @@ -5109,68 +5500,83 @@ int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); */ /* -** CAPI3REF: A Handle To An Open BLOB {F17800} +** CAPI3REF: A Handle To An Open BLOB {H17800} <S30230> +** KEYWORDS: {BLOB handle} {BLOB handles} ** ** An instance of this object represents an open BLOB on which -** incremental I/O can be preformed. -** Objects of this type are created by -** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()]. +** [sqlite3_blob_open | incremental BLOB I/O] can be performed. +** Objects of this type are created by [sqlite3_blob_open()] +** and destroyed by [sqlite3_blob_close()]. ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces -** can be used to read or write small subsections of the blob. -** The [sqlite3_blob_bytes()] interface returns the size of the -** blob in bytes. +** can be used to read or write small subsections of the BLOB. +** The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes. */ typedef struct sqlite3_blob sqlite3_blob; /* -** CAPI3REF: Open A BLOB For Incremental I/O {F17810} +** CAPI3REF: Open A BLOB For Incremental I/O {H17810} <S30230> ** -** This interfaces opens a handle to the blob located +** This interfaces opens a [BLOB handle | handle] to the BLOB located ** in row iRow, column zColumn, table zTable in database zDb; -** in other words, the same blob that would be selected by: +** in other words, the same BLOB that would be selected by: ** ** <pre> ** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow; ** </pre> {END} ** -** If the flags parameter is non-zero, the blob is opened for -** read and write access. If it is zero, the blob is opened for read -** access. +** If the flags parameter is non-zero, the the BLOB is opened for read +** and write access. If it is zero, the BLOB is opened for read access. ** ** Note that the database name is not the filename that contains ** the database but rather the symbolic name of the database that ** is assigned when the database is connected using [ATTACH]. -** For the main database file, the database name is "main". For -** TEMP tables, the database name is "temp". -** -** On success, [SQLITE_OK] is returned and the new -** [sqlite3_blob | blob handle] is written to *ppBlob. -** Otherwise an error code is returned and -** any value written to *ppBlob should not be used by the caller. -** This function sets the database-handle error code and message +** For the main database file, the database name is "main". +** For TEMP tables, the database name is "temp". +** +** On success, [SQLITE_OK] is returned and the new [BLOB handle] is written +** to *ppBlob. Otherwise an [error code] is returned and any value written +** to *ppBlob should not be used by the caller. +** This function sets the [database connection] error code and message ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()]. -** +** +** If the row that a BLOB handle points to is modified by an +** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects +** then the BLOB handle is marked as "expired". +** This is true if any column of the row is changed, even a column +** other than the one the BLOB handle is open on. +** Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for +** a expired BLOB handle fail with an return code of [SQLITE_ABORT]. +** Changes written into a BLOB prior to the BLOB expiring are not +** rollback by the expiration of the BLOB. Such changes will eventually +** commit if the transaction continues to completion. +** ** INVARIANTS: ** -** {F17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)] -** interface opens an [sqlite3_blob] object P on the blob -** in column C of table T in database B on [database connection] D. +** {H17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)] +** interface shall open an [sqlite3_blob] object P on the BLOB +** in column C of the table T in the database B on +** the [database connection] D. ** -** {F17814} A successful invocation of [sqlite3_blob_open(D,...)] starts -** a new transaction on [database connection] D if that connection -** is not already in a transaction. +** {H17814} A successful invocation of [sqlite3_blob_open(D,...)] shall start +** a new transaction on the [database connection] D if that +** connection is not already in a transaction. ** -** {F17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface opens the blob -** for read and write access if and only if the F parameter -** is non-zero. +** {H17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface shall open +** the BLOB for read and write access if and only if the F +** parameter is non-zero. ** -** {F17819} The [sqlite3_blob_open()] interface returns [SQLITE_OK] on +** {H17819} The [sqlite3_blob_open()] interface shall return [SQLITE_OK] on ** success and an appropriate [error code] on failure. ** -** {F17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)] +** {H17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)] ** then subsequent calls to [sqlite3_errcode(D)], -** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return -** information approprate for that error. +** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return +** information appropriate for that error. +** +** {H17824} If any column in the row that a [sqlite3_blob] has open is +** changed by a separate [UPDATE] or [DELETE] statement or by +** an [ON CONFLICT] side effect, then the [sqlite3_blob] shall +** be marked as invalid. */ int sqlite3_blob_open( sqlite3*, @@ -5183,18 +5589,19 @@ int sqlite3_blob_open( ); /* -** CAPI3REF: Close A BLOB Handle {F17830} +** CAPI3REF: Close A BLOB Handle {H17830} <S30230> ** -** Close an open [sqlite3_blob | blob handle]. +** Closes an open [BLOB handle]. ** ** Closing a BLOB shall cause the current transaction to commit ** if there are no other BLOBs, no pending prepared statements, and the -** database connection is in autocommit mode. +** database connection is in [autocommit mode]. ** If any writes were made to the BLOB, they might be held in cache ** until the close operation if they will fit. {END} +** ** Closing the BLOB often forces the changes ** out to disk and so if any I/O errors occur, they will likely occur -** at the time when the BLOB is closed. {F17833} Any errors that occur during +** at the time when the BLOB is closed. {H17833} Any errors that occur during ** closing are reported as a non-zero return value. ** ** The BLOB is closed unconditionally. Even if this routine returns @@ -5202,139 +5609,156 @@ int sqlite3_blob_open( ** ** INVARIANTS: ** -** {F17833} The [sqlite3_blob_close(P)] interface closes an -** [sqlite3_blob] object P previously opened using -** [sqlite3_blob_open()]. +** {H17833} The [sqlite3_blob_close(P)] interface closes an [sqlite3_blob] +** object P previously opened using [sqlite3_blob_open()]. ** -** {F17836} Closing an [sqlite3_blob] object using +** {H17836} Closing an [sqlite3_blob] object using ** [sqlite3_blob_close()] shall cause the current transaction to ** commit if there are no other open [sqlite3_blob] objects ** or [prepared statements] on the same [database connection] and -** the [database connection] is in -** [sqlite3_get_autocommit | autocommit mode]. +** the database connection is in [autocommit mode]. ** -** {F17839} The [sqlite3_blob_close(P)] interfaces closes the +** {H17839} The [sqlite3_blob_close(P)] interfaces shall close the ** [sqlite3_blob] object P unconditionally, even if ** [sqlite3_blob_close(P)] returns something other than [SQLITE_OK]. -** */ int sqlite3_blob_close(sqlite3_blob *); /* -** CAPI3REF: Return The Size Of An Open BLOB {F17840} +** CAPI3REF: Return The Size Of An Open BLOB {H17840} <S30230> ** -** Return the size in bytes of the blob accessible via the open -** [sqlite3_blob] object in its only argument. +** Returns the size in bytes of the BLOB accessible via the open +** []BLOB handle] in its only argument. ** ** INVARIANTS: ** -** {F17843} The [sqlite3_blob_bytes(P)] interface returns the size +** {H17843} The [sqlite3_blob_bytes(P)] interface returns the size ** in bytes of the BLOB that the [sqlite3_blob] object P ** refers to. */ int sqlite3_blob_bytes(sqlite3_blob *); /* -** CAPI3REF: Read Data From A BLOB Incrementally {F17850} +** CAPI3REF: Read Data From A BLOB Incrementally {H17850} <S30230> ** -** This function is used to read data from an open -** [sqlite3_blob | blob-handle] into a caller supplied buffer. -** N bytes of data are copied into buffer -** Z from the open blob, starting at offset iOffset. +** This function is used to read data from an open [BLOB handle] into a +** caller-supplied buffer. N bytes of data are copied into buffer Z +** from the open BLOB, starting at offset iOffset. ** -** If offset iOffset is less than N bytes from the end of the blob, +** If offset iOffset is less than N bytes from the end of the BLOB, ** [SQLITE_ERROR] is returned and no data is read. If N or iOffset is -** less than zero [SQLITE_ERROR] is returned and no data is read. +** less than zero, [SQLITE_ERROR] is returned and no data is read. +** +** An attempt to read from an expired [BLOB handle] fails with an +** error code of [SQLITE_ABORT]. ** -** On success, SQLITE_OK is returned. Otherwise, an -** [error code] or an [extended error code] is returned. +** On success, SQLITE_OK is returned. +** Otherwise, an [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** -** {F17853} The [sqlite3_blob_read(P,Z,N,X)] interface reads N bytes -** beginning at offset X from -** the blob that [sqlite3_blob] object P refers to -** and writes those N bytes into buffer Z. +** {H17853} A successful invocation of [sqlite3_blob_read(P,Z,N,X)] +** shall reads N bytes of data out of the BLOB referenced by +** [BLOB handle] P beginning at offset X and store those bytes +** into buffer Z. ** -** {F17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the blob -** is less than N+X bytes, then the function returns [SQLITE_ERROR] -** and nothing is read from the blob. +** {H17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the BLOB +** is less than N+X bytes, then the function shall leave the +** Z buffer unchanged and return [SQLITE_ERROR]. ** -** {F17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero -** then the function returns [SQLITE_ERROR] -** and nothing is read from the blob. +** {H17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero +** then the function shall leave the Z buffer unchanged +** and return [SQLITE_ERROR]. ** -** {F17862} The [sqlite3_blob_read(P,Z,N,X)] interface returns [SQLITE_OK] -** if N bytes where successfully read into buffer Z. +** {H17862} The [sqlite3_blob_read(P,Z,N,X)] interface shall return [SQLITE_OK] +** if N bytes are successfully read into buffer Z. ** -** {F17865} If the requested read could not be completed, -** the [sqlite3_blob_read(P,Z,N,X)] interface returns an +** {H17863} If the [BLOB handle] P is expired and X and N are within bounds +** then [sqlite3_blob_read(P,Z,N,X)] shall leave the Z buffer +** unchanged and return [SQLITE_ABORT]. +** +** {H17865} If the requested read could not be completed, +** the [sqlite3_blob_read(P,Z,N,X)] interface shall return an ** appropriate [error code] or [extended error code]. ** -** {F17868} If an error occurs during evaluation of [sqlite3_blob_read(P,...)] +** {H17868} If an error occurs during evaluation of [sqlite3_blob_read(P,...)] ** then subsequent calls to [sqlite3_errcode(D)], -** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return -** information approprate for that error, where D is the -** database handle that was used to open blob handle P. +** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return +** information appropriate for that error, where D is the +** [database connection] that was used to open the [BLOB handle] P. */ int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); /* -** CAPI3REF: Write Data Into A BLOB Incrementally {F17870} +** CAPI3REF: Write Data Into A BLOB Incrementally {H17870} <S30230> ** -** This function is used to write data into an open -** [sqlite3_blob | blob-handle] from a user supplied buffer. -** n bytes of data are copied from the buffer -** pointed to by z into the open blob, starting at offset iOffset. +** This function is used to write data into an open [BLOB handle] from a +** caller-supplied buffer. N bytes of data are copied from the buffer Z +** into the open BLOB, starting at offset iOffset. ** -** If the [sqlite3_blob | blob-handle] passed as the first argument -** was not opened for writing (the flags parameter to [sqlite3_blob_open()] -*** was zero), this function returns [SQLITE_READONLY]. +** If the [BLOB handle] passed as the first argument was not opened for +** writing (the flags parameter to [sqlite3_blob_open()] was zero), +** this function returns [SQLITE_READONLY]. ** -** This function may only modify the contents of the blob; it is -** not possible to increase the size of a blob using this API. -** If offset iOffset is less than n bytes from the end of the blob, -** [SQLITE_ERROR] is returned and no data is written. If n is +** This function may only modify the contents of the BLOB; it is +** not possible to increase the size of a BLOB using this API. +** If offset iOffset is less than N bytes from the end of the BLOB, +** [SQLITE_ERROR] is returned and no data is written. If N is ** less than zero [SQLITE_ERROR] is returned and no data is written. ** -** On success, SQLITE_OK is returned. Otherwise, an -** [error code] or an [extended error code] is returned. +** An attempt to write to an expired [BLOB handle] fails with an +** error code of [SQLITE_ABORT]. Writes to the BLOB that occurred +** before the [BLOB handle] expired are not rolled back by the +** expiration of the handle, though of course those changes might +** have been overwritten by the statement that expired the BLOB handle +** or by other independent statements. +** +** On success, SQLITE_OK is returned. +** Otherwise, an [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** -** {F17873} The [sqlite3_blob_write(P,Z,N,X)] interface writes N bytes -** from buffer Z into -** the blob that [sqlite3_blob] object P refers to -** beginning at an offset of X into the blob. +** {H17873} A successful invocation of [sqlite3_blob_write(P,Z,N,X)] +** shall write N bytes of data from buffer Z into the BLOB +** referenced by [BLOB handle] P beginning at offset X into +** the BLOB. ** -** {F17875} The [sqlite3_blob_write(P,Z,N,X)] interface returns -** [SQLITE_READONLY] if the [sqlite3_blob] object P was -** [sqlite3_blob_open | opened] for reading only. +** {H17874} In the absence of other overridding changes, the changes +** written to a BLOB by [sqlite3_blob_write()] shall +** remain in effect after the associated [BLOB handle] expires. ** -** {F17876} In [sqlite3_blob_write(P,Z,N,X)] if the size of the blob -** is less than N+X bytes, then the function returns [SQLITE_ERROR] -** and nothing is written into the blob. +** {H17875} If the [BLOB handle] P was opened for reading only then +** an invocation of [sqlite3_blob_write(P,Z,N,X)] shall leave +** the referenced BLOB unchanged and return [SQLITE_READONLY]. ** -** {F17879} In [sqlite3_blob_write(P,Z,N,X)] if X or N is less than zero -** then the function returns [SQLITE_ERROR] -** and nothing is written into the blob. +** {H17876} If the size of the BLOB referenced by [BLOB handle] P is +** less than N+X bytes then [sqlite3_blob_write(P,Z,N,X)] shall +** leave the BLOB unchanged and return [SQLITE_ERROR]. ** -** {F17882} The [sqlite3_blob_write(P,Z,N,X)] interface returns [SQLITE_OK] -** if N bytes where successfully written into blob. +** {H17877} If the [BLOB handle] P is expired and X and N are within bounds +** then [sqlite3_blob_read(P,Z,N,X)] shall leave the BLOB +** unchanged and return [SQLITE_ABORT]. ** -** {F17885} If the requested write could not be completed, -** the [sqlite3_blob_write(P,Z,N,X)] interface returns an +** {H17879} If X or N are less than zero then [sqlite3_blob_write(P,Z,N,X)] +** shall leave the BLOB referenced by [BLOB handle] P unchanged +** and return [SQLITE_ERROR]. +** +** {H17882} The [sqlite3_blob_write(P,Z,N,X)] interface shall return +** [SQLITE_OK] if N bytes where successfully written into the BLOB. +** +** {H17885} If the requested write could not be completed, +** the [sqlite3_blob_write(P,Z,N,X)] interface shall return an ** appropriate [error code] or [extended error code]. ** -** {F17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)] +** {H17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)] ** then subsequent calls to [sqlite3_errcode(D)], -** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return -** information approprate for that error. +** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return +** information appropriate for that error. */ int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); /* -** CAPI3REF: Virtual File System Objects {F11200} +** CAPI3REF: Virtual File System Objects {H11200} <S20100> ** ** A virtual filesystem (VFS) is an [sqlite3_vfs] object ** that SQLite uses to interact @@ -5343,12 +5767,11 @@ int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); ** New VFSes can be registered and existing VFSes can be unregistered. ** The following interfaces are provided. ** -** The sqlite3_vfs_find() interface returns a pointer to -** a VFS given its name. Names are case sensitive. +** The sqlite3_vfs_find() interface returns a pointer to a VFS given its name. +** Names are case sensitive. ** Names are zero-terminated UTF-8 strings. -** If there is no match, a NULL -** pointer is returned. If zVfsName is NULL then the default -** VFS is returned. +** If there is no match, a NULL pointer is returned. +** If zVfsName is NULL then the default VFS is returned. ** ** New VFSes are registered with sqlite3_vfs_register(). ** Each new VFS becomes the default VFS if the makeDflt flag is set. @@ -5358,35 +5781,34 @@ int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); ** same name are registered, the behavior is undefined. If a ** VFS is registered with a name that is NULL or an empty string, ** then the behavior is undefined. -** +** ** Unregister a VFS with the sqlite3_vfs_unregister() interface. ** If the default VFS is unregistered, another VFS is chosen as ** the default. The choice for the new VFS is arbitrary. ** ** INVARIANTS: ** -** {F11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the +** {H11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the ** registered [sqlite3_vfs] object whose name exactly matches ** the zero-terminated UTF-8 string N, or it returns NULL if ** there is no match. ** -** {F11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then +** {H11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then ** the function returns a pointer to the default [sqlite3_vfs] -** object if there is one, or NULL if there is no default +** object if there is one, or NULL if there is no default ** [sqlite3_vfs] object. ** -** {F11209} The [sqlite3_vfs_register(P,F)] interface registers the +** {H11209} The [sqlite3_vfs_register(P,F)] interface registers the ** well-formed [sqlite3_vfs] object P using the name given ** by the zName field of the object. ** -** {F11212} Using the [sqlite3_vfs_register(P,F)] interface to register +** {H11212} Using the [sqlite3_vfs_register(P,F)] interface to register ** the same [sqlite3_vfs] object multiple times is a harmless no-op. ** -** {F11215} The [sqlite3_vfs_register(P,F)] interface makes the -** the [sqlite3_vfs] object P the default [sqlite3_vfs] object -** if F is non-zero. +** {H11215} The [sqlite3_vfs_register(P,F)] interface makes the [sqlite3_vfs] +** object P the default [sqlite3_vfs] object if F is non-zero. ** -** {F11218} The [sqlite3_vfs_unregister(P)] interface unregisters the +** {H11218} The [sqlite3_vfs_unregister(P)] interface unregisters the ** [sqlite3_vfs] object P so that it is no longer returned by ** subsequent calls to [sqlite3_vfs_find()]. */ @@ -5395,14 +5817,14 @@ int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); int sqlite3_vfs_unregister(sqlite3_vfs*); /* -** CAPI3REF: Mutexes {F17000} +** CAPI3REF: Mutexes {H17000} <S20000> ** ** The SQLite core uses these routines for thread -** synchronization. Though they are intended for internal +** synchronization. Though they are intended for internal ** use by SQLite, code that links against SQLite is ** permitted to use any of these routines. ** -** The SQLite source code contains multiple implementations +** The SQLite source code contains multiple implementations ** of these mutex routines. An appropriate implementation ** is selected automatically at compile-time. The following ** implementations are available in the SQLite core: @@ -5414,25 +5836,24 @@ int sqlite3_vfs_unregister(sqlite3_vfs*); ** <li> SQLITE_MUTEX_NOOP ** </ul> ** -** The SQLITE_MUTEX_NOOP implementation is a set of routines -** that does no real locking and is appropriate for use in +** The SQLITE_MUTEX_NOOP implementation is a set of routines +** that does no real locking and is appropriate for use in ** a single-threaded application. The SQLITE_MUTEX_OS2, ** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations -** are appropriate for use on os/2, unix, and windows. -** +** are appropriate for use on OS/2, Unix, and Windows. +** ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex -** implementation is included with the library. The -** mutex interface routines defined here become external -** references in the SQLite library for which implementations -** must be provided by the application. This facility allows an -** application that links against SQLite to provide its own mutex -** implementation without having to modify the SQLite core. -** -** {F17011} The sqlite3_mutex_alloc() routine allocates a new -** mutex and returns a pointer to it. {F17012} If it returns NULL -** that means that a mutex could not be allocated. {F17013} SQLite -** will unwind its stack and return an error. {F17014} The argument +** implementation is included with the library. In this case the +** application must supply a custom mutex implementation using the +** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function +** before calling sqlite3_initialize() or any other public sqlite3_ +** function that calls sqlite3_initialize(). +** +** {H17011} The sqlite3_mutex_alloc() routine allocates a new +** mutex and returns a pointer to it. {H17012} If it returns NULL +** that means that a mutex could not be allocated. {H17013} SQLite +** will unwind its stack and return an error. {H17014} The argument ** to sqlite3_mutex_alloc() is one of these integer constants: ** ** <ul> @@ -5444,19 +5865,19 @@ int sqlite3_vfs_unregister(sqlite3_vfs*); ** <li> SQLITE_MUTEX_STATIC_PRNG ** <li> SQLITE_MUTEX_STATIC_LRU ** <li> SQLITE_MUTEX_STATIC_LRU2 -** </ul> {END} +** </ul> ** -** {F17015} The first two constants cause sqlite3_mutex_alloc() to create +** {H17015} The first two constants cause sqlite3_mutex_alloc() to create ** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE ** is used but not necessarily so when SQLITE_MUTEX_FAST is used. {END} ** The mutex implementation does not need to make a distinction ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does -** not want to. {F17016} But SQLite will only request a recursive mutex in +** not want to. {H17016} But SQLite will only request a recursive mutex in ** cases where it really needs one. {END} If a faster non-recursive mutex ** implementation is available on the host platform, the mutex subsystem ** might return such a mutex in response to SQLITE_MUTEX_FAST. ** -** {F17017} The other allowed parameters to sqlite3_mutex_alloc() each return +** {H17017} The other allowed parameters to sqlite3_mutex_alloc() each return ** a pointer to a static preexisting mutex. {END} Four static mutexes are ** used by the current version of SQLite. Future versions of SQLite ** may add additional static mutexes. Static mutexes are for internal @@ -5464,43 +5885,47 @@ int sqlite3_vfs_unregister(sqlite3_vfs*); ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or ** SQLITE_MUTEX_RECURSIVE. ** -** {F17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST +** {H17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() -** returns a different mutex on every call. {F17034} But for the static +** returns a different mutex on every call. {H17034} But for the static ** mutex types, the same mutex is returned on every call that has -** the same type number. {END} +** the same type number. ** -** {F17019} The sqlite3_mutex_free() routine deallocates a previously -** allocated dynamic mutex. {F17020} SQLite is careful to deallocate every -** dynamic mutex that it allocates. {U17021} The dynamic mutexes must not be in -** use when they are deallocated. {U17022} Attempting to deallocate a static -** mutex results in undefined behavior. {F17023} SQLite never deallocates +** {H17019} The sqlite3_mutex_free() routine deallocates a previously +** allocated dynamic mutex. {H17020} SQLite is careful to deallocate every +** dynamic mutex that it allocates. {A17021} The dynamic mutexes must not be in +** use when they are deallocated. {A17022} Attempting to deallocate a static +** mutex results in undefined behavior. {H17023} SQLite never deallocates ** a static mutex. {END} ** ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt -** to enter a mutex. {F17024} If another thread is already within the mutex, +** to enter a mutex. {H17024} If another thread is already within the mutex, ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return -** SQLITE_BUSY. {F17025} The sqlite3_mutex_try() interface returns SQLITE_OK -** upon successful entry. {F17026} Mutexes created using +** SQLITE_BUSY. {H17025} The sqlite3_mutex_try() interface returns [SQLITE_OK] +** upon successful entry. {H17026} Mutexes created using ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread. -** {F17027} In such cases the, +** {H17027} In such cases the, ** mutex must be exited an equal number of times before another thread -** can enter. {U17028} If the same thread tries to enter any other +** can enter. {A17028} If the same thread tries to enter any other ** kind of mutex more than once, the behavior is undefined. -** {F17029} SQLite will never exhibit -** such behavior in its own use of mutexes. {END} +** {H17029} SQLite will never exhibit +** such behavior in its own use of mutexes. ** -** Some systems (ex: windows95) do not the operation implemented by -** sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() will -** always return SQLITE_BUSY. {F17030} The SQLite core only ever uses -** sqlite3_mutex_try() as an optimization so this is acceptable behavior. {END} +** Some systems (for example, Windows 95) do not support the operation +** implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() +** will always return SQLITE_BUSY. {H17030} The SQLite core only ever uses +** sqlite3_mutex_try() as an optimization so this is acceptable behavior. ** -** {F17031} The sqlite3_mutex_leave() routine exits a mutex that was -** previously entered by the same thread. {U17032} The behavior +** {H17031} The sqlite3_mutex_leave() routine exits a mutex that was +** previously entered by the same thread. {A17032} The behavior ** is undefined if the mutex is not currently entered by the -** calling thread or is not currently allocated. {F17033} SQLite will +** calling thread or is not currently allocated. {H17033} SQLite will ** never do either. {END} ** +** If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or +** sqlite3_mutex_leave() is a NULL pointer, then all three routines +** behave as no-ops. +** ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()]. */ sqlite3_mutex *sqlite3_mutex_alloc(int); @@ -5510,44 +5935,110 @@ int sqlite3_mutex_try(sqlite3_mutex*); void sqlite3_mutex_leave(sqlite3_mutex*); /* -** CAPI3REF: Mutex Verifcation Routines {F17080} +** CAPI3REF: Mutex Methods Object {H17120} <S20130> +** EXPERIMENTAL +** +** An instance of this structure defines the low-level routines +** used to allocate and use mutexes. +** +** Usually, the default mutex implementations provided by SQLite are +** sufficient, however the user has the option of substituting a custom +** implementation for specialized deployments or systems for which SQLite +** does not provide a suitable implementation. In this case, the user +** creates and populates an instance of this structure to pass +** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option. +** Additionally, an instance of this structure can be used as an +** output variable when querying the system for the current mutex +** implementation, using the [SQLITE_CONFIG_GETMUTEX] option. +** +** The xMutexInit method defined by this structure is invoked as +** part of system initialization by the sqlite3_initialize() function. +** {H17001} The xMutexInit routine shall be called by SQLite once for each +** effective call to [sqlite3_initialize()]. +** +** The xMutexEnd method defined by this structure is invoked as +** part of system shutdown by the sqlite3_shutdown() function. The +** implementation of this method is expected to release all outstanding +** resources obtained by the mutex methods implementation, especially +** those obtained by the xMutexInit method. {H17003} The xMutexEnd() +** interface shall be invoked once for each call to [sqlite3_shutdown()]. +** +** The remaining seven methods defined by this structure (xMutexAlloc, +** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and +** xMutexNotheld) implement the following interfaces (respectively): +** +** <ul> +** <li> [sqlite3_mutex_alloc()] </li> +** <li> [sqlite3_mutex_free()] </li> +** <li> [sqlite3_mutex_enter()] </li> +** <li> [sqlite3_mutex_try()] </li> +** <li> [sqlite3_mutex_leave()] </li> +** <li> [sqlite3_mutex_held()] </li> +** <li> [sqlite3_mutex_notheld()] </li> +** </ul> +** +** The only difference is that the public sqlite3_XXX functions enumerated +** above silently ignore any invocations that pass a NULL pointer instead +** of a valid mutex handle. The implementations of the methods defined +** by this structure are not required to handle this case, the results +** of passing a NULL pointer instead of a valid mutex handle are undefined +** (i.e. it is acceptable to provide an implementation that segfaults if +** it is passed a NULL pointer). +*/ +typedef struct sqlite3_mutex_methods sqlite3_mutex_methods; +struct sqlite3_mutex_methods { + int (*xMutexInit)(void); + int (*xMutexEnd)(void); + sqlite3_mutex *(*xMutexAlloc)(int); + void (*xMutexFree)(sqlite3_mutex *); + void (*xMutexEnter)(sqlite3_mutex *); + int (*xMutexTry)(sqlite3_mutex *); + void (*xMutexLeave)(sqlite3_mutex *); + int (*xMutexHeld)(sqlite3_mutex *); + int (*xMutexNotheld)(sqlite3_mutex *); +}; + +/* +** CAPI3REF: Mutex Verification Routines {H17080} <S20130> <S30800> ** ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines -** are intended for use inside assert() statements. {F17081} The SQLite core +** are intended for use inside assert() statements. {H17081} The SQLite core ** never uses these routines except inside an assert() and applications -** are advised to follow the lead of the core. {F17082} The core only +** are advised to follow the lead of the core. {H17082} The core only ** provides implementations for these routines when it is compiled -** with the SQLITE_DEBUG flag. {U17087} External mutex implementations +** with the SQLITE_DEBUG flag. {A17087} External mutex implementations ** are only required to provide these routines if SQLITE_DEBUG is ** defined and if NDEBUG is not defined. ** -** {F17083} These routines should return true if the mutex in their argument -** is held or not held, respectively, by the calling thread. {END} +** {H17083} These routines should return true if the mutex in their argument +** is held or not held, respectively, by the calling thread. ** ** {X17084} The implementation is not required to provided versions of these -** routines that actually work. -** If the implementation does not provide working -** versions of these routines, it should at least provide stubs -** that always return true so that one does not get spurious -** assertion failures. {END} +** routines that actually work. If the implementation does not provide working +** versions of these routines, it should at least provide stubs that always +** return true so that one does not get spurious assertion failures. ** -** {F17085} If the argument to sqlite3_mutex_held() is a NULL pointer then +** {H17085} If the argument to sqlite3_mutex_held() is a NULL pointer then ** the routine should return 1. {END} This seems counter-intuitive since ** clearly the mutex cannot be held if it does not exist. But the ** the reason the mutex does not exist is because the build is not ** using mutexes. And we do not want the assert() containing the ** call to sqlite3_mutex_held() to fail, so a non-zero return is -** the appropriate thing to do. {F17086} The sqlite3_mutex_notheld() +** the appropriate thing to do. {H17086} The sqlite3_mutex_notheld() ** interface should also return 1 when given a NULL pointer. */ int sqlite3_mutex_held(sqlite3_mutex*); int sqlite3_mutex_notheld(sqlite3_mutex*); /* -** CAPI3REF: Mutex Types {F17001} +** CAPI3REF: Mutex Types {H17001} <H17000> ** -** {F17002} The [sqlite3_mutex_alloc()] interface takes a single argument -** which is one of these integer constants. {END} +** The [sqlite3_mutex_alloc()] interface takes a single argument +** which is one of these integer constants. +** +** The set of static mutexes may change from one SQLite release to the +** next. Applications that override the built-in mutex logic must be +** prepared to accommodate additional static mutexes. */ #define SQLITE_MUTEX_FAST 0 #define SQLITE_MUTEX_RECURSIVE 1 @@ -5559,24 +6050,24 @@ int sqlite3_mutex_notheld(sqlite3_mutex*); #define SQLITE_MUTEX_STATIC_LRU2 7 /* lru page list */ /* -** CAPI3REF: Low-Level Control Of Database Files {F11300} +** CAPI3REF: Low-Level Control Of Database Files {H11300} <S30800> ** -** {F11301} The [sqlite3_file_control()] interface makes a direct call to the +** {H11301} The [sqlite3_file_control()] interface makes a direct call to the ** xFileControl method for the [sqlite3_io_methods] object associated -** with a particular database identified by the second argument. {F11302} The +** with a particular database identified by the second argument. {H11302} The ** name of the database is the name assigned to the database by the ** <a href="lang_attach.html">ATTACH</a> SQL command that opened the -** database. {F11303} To control the main database file, use the name "main" -** or a NULL pointer. {F11304} The third and fourth parameters to this routine +** database. {H11303} To control the main database file, use the name "main" +** or a NULL pointer. {H11304} The third and fourth parameters to this routine ** are passed directly through to the second and third parameters of -** the xFileControl method. {F11305} The return value of the xFileControl +** the xFileControl method. {H11305} The return value of the xFileControl ** method becomes the return value of this routine. ** -** {F11306} If the second parameter (zDbName) does not match the name of any -** open database file, then SQLITE_ERROR is returned. {F11307} This error +** {H11306} If the second parameter (zDbName) does not match the name of any +** open database file, then SQLITE_ERROR is returned. {H11307} This error ** code is not remembered and will not be recalled by [sqlite3_errcode()] -** or [sqlite3_errmsg()]. {U11308} The underlying xFileControl method might -** also return SQLITE_ERROR. {U11309} There is no way to distinguish between +** or [sqlite3_errmsg()]. {A11308} The underlying xFileControl method might +** also return SQLITE_ERROR. {A11309} There is no way to distinguish between ** an incorrect zDbName and an SQLITE_ERROR return from the underlying ** xFileControl method. {END} ** @@ -5585,11 +6076,11 @@ int sqlite3_mutex_notheld(sqlite3_mutex*); int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); /* -** CAPI3REF: Testing Interface {F11400} +** CAPI3REF: Testing Interface {H11400} <S30800> ** ** The sqlite3_test_control() interface is used to read out internal ** state of SQLite and to inject faults into SQLite for testing -** purposes. The first parameter a operation code that determines +** purposes. The first parameter is an operation code that determines ** the number, meaning, and operation of all subsequent parameters. ** ** This interface is not for use by applications. It exists solely @@ -5604,25 +6095,175 @@ int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); int sqlite3_test_control(int op, ...); /* -** CAPI3REF: Testing Interface Operation Codes {F11410} +** CAPI3REF: Testing Interface Operation Codes {H11410} <H11400> ** ** These constants are the valid operation code parameters used ** as the first argument to [sqlite3_test_control()]. ** -** These parameters and their meansing are subject to change +** These parameters and their meanings are subject to change ** without notice. These values are for testing purposes only. ** Applications should not use any of these parameters or the ** [sqlite3_test_control()] interface. */ -#define SQLITE_TESTCTRL_FAULT_CONFIG 1 -#define SQLITE_TESTCTRL_FAULT_FAILURES 2 -#define SQLITE_TESTCTRL_FAULT_BENIGN_FAILURES 3 -#define SQLITE_TESTCTRL_FAULT_PENDING 4 #define SQLITE_TESTCTRL_PRNG_SAVE 5 #define SQLITE_TESTCTRL_PRNG_RESTORE 6 #define SQLITE_TESTCTRL_PRNG_RESET 7 #define SQLITE_TESTCTRL_BITVEC_TEST 8 +#define SQLITE_TESTCTRL_FAULT_INSTALL 9 +#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 + +/* +** CAPI3REF: SQLite Runtime Status {H17200} <S60200> +** EXPERIMENTAL +** +** This interface is used to retrieve runtime status information +** about the preformance of SQLite, and optionally to reset various +** highwater marks. The first argument is an integer code for +** the specific parameter to measure. Recognized integer codes +** are of the form [SQLITE_STATUS_MEMORY_USED | SQLITE_STATUS_...]. +** The current value of the parameter is returned into *pCurrent. +** The highest recorded value is returned in *pHighwater. If the +** resetFlag is true, then the highest record value is reset after +** *pHighwater is written. Some parameters do not record the highest +** value. For those parameters +** nothing is written into *pHighwater and the resetFlag is ignored. +** Other parameters record only the highwater mark and not the current +** value. For these latter parameters nothing is written into *pCurrent. +** +** This routine returns SQLITE_OK on success and a non-zero +** [error code] on failure. +** +** This routine is threadsafe but is not atomic. This routine can +** called while other threads are running the same or different SQLite +** interfaces. However the values returned in *pCurrent and +** *pHighwater reflect the status of SQLite at different points in time +** and it is possible that another thread might change the parameter +** in between the times when *pCurrent and *pHighwater are written. +** +** See also: [sqlite3_db_status()] +*/ +int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag); + +/* +** CAPI3REF: Database Connection Status {H17201} <S60200> +** EXPERIMENTAL +** +** This interface is used to retrieve runtime status information +** about a single [database connection]. The first argument is the +** database connection object to be interrogated. The second argument +** is the parameter to interrogate. Currently, the only allowed value +** for the second parameter is [SQLITE_DBSTATUS_LOOKASIDE_USED]. +** Additional options will likely appear in future releases of SQLite. +** +** The current value of the request parameter is written into *pCur +** and the highest instantaneous value is written into *pHiwtr. If +** the resetFlg is true, then the highest instantaneous value is +** reset back down to the current value. +** +** See also: [sqlite3_status()]. +*/ +int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg); +/* +** CAPI3REF: Status Parameters {H17250} <H17200> +** EXPERIMENTAL +** +** These integer constants designate various run-time status parameters +** that can be returned by [sqlite3_status()]. +** +** <dl> +** <dt>SQLITE_STATUS_MEMORY_USED</dt> +** <dd>This parameter is the current amount of memory checked out +** using [sqlite3_malloc()], either directly or indirectly. The +** figure includes calls made to [sqlite3_malloc()] by the application +** and internal memory usage by the SQLite library. Scratch memory +** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache +** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in +** this parameter. The amount returned is the sum of the allocation +** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd> +** +** <dt>SQLITE_STATUS_MALLOC_SIZE</dt> +** <dd>This parameter records the largest memory allocation request +** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their +** internal equivalents). Only the value returned in the +** *pHighwater parameter to [sqlite3_status()] is of interest. +** The value written into the *pCurrent parameter is undefined.</dd> +** +** <dt>SQLITE_STATUS_PAGECACHE_USED</dt> +** <dd>This parameter returns the number of pages used out of the +** [pagecache memory allocator] that was configured using +** [SQLITE_CONFIG_PAGECACHE]. The +** value returned is in pages, not in bytes.</dd> +** +** <dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt> +** <dd>This parameter returns the number of bytes of page cache +** allocation which could not be statisfied by the [SQLITE_CONFIG_PAGECACHE] +** buffer and where forced to overflow to [sqlite3_malloc()]. The +** returned value includes allocations that overflowed because they +** where too large (they were larger than the "sz" parameter to +** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because +** no space was left in the page cache.</dd> +** +** <dt>SQLITE_STATUS_PAGECACHE_SIZE</dt> +** <dd>This parameter records the largest memory allocation request +** handed to [pagecache memory allocator]. Only the value returned in the +** *pHighwater parameter to [sqlite3_status()] is of interest. +** The value written into the *pCurrent parameter is undefined.</dd> +** +** <dt>SQLITE_STATUS_SCRATCH_USED</dt> +** <dd>This parameter returns the number of allocations used out of the +** [scratch memory allocator] configured using +** [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not +** in bytes. Since a single thread may only have one scratch allocation +** outstanding at time, this parameter also reports the number of threads +** using scratch memory at the same time.</dd> +** +** <dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt> +** <dd>This parameter returns the number of bytes of scratch memory +** allocation which could not be statisfied by the [SQLITE_CONFIG_SCRATCH] +** buffer and where forced to overflow to [sqlite3_malloc()]. The values +** returned include overflows because the requested allocation was too +** larger (that is, because the requested allocation was larger than the +** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer +** slots were available. +** </dd> +** +** <dt>SQLITE_STATUS_SCRATCH_SIZE</dt> +** <dd>This parameter records the largest memory allocation request +** handed to [scratch memory allocator]. Only the value returned in the +** *pHighwater parameter to [sqlite3_status()] is of interest. +** The value written into the *pCurrent parameter is undefined.</dd> +** +** <dt>SQLITE_STATUS_PARSER_STACK</dt> +** <dd>This parameter records the deepest parser stack. It is only +** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd> +** </dl> +** +** New status parameters may be added from time to time. +*/ +#define SQLITE_STATUS_MEMORY_USED 0 +#define SQLITE_STATUS_PAGECACHE_USED 1 +#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2 +#define SQLITE_STATUS_SCRATCH_USED 3 +#define SQLITE_STATUS_SCRATCH_OVERFLOW 4 +#define SQLITE_STATUS_MALLOC_SIZE 5 +#define SQLITE_STATUS_PARSER_STACK 6 +#define SQLITE_STATUS_PAGECACHE_SIZE 7 +#define SQLITE_STATUS_SCRATCH_SIZE 8 + +/* +** CAPI3REF: Status Parameters for database connections {H17275} <H17200> +** EXPERIMENTAL +** +** Status verbs for [sqlite3_db_status()]. +** +** <dl> +** <dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt> +** <dd>This parameter returns the number of lookaside memory slots currently +** checked out.</dd> +** </dl> +*/ +#define SQLITE_DBSTATUS_LOOKASIDE_USED 0 /* ** Undo the hack that converts floating point types to integer for diff --git a/ext/sqlite3/libsqlite/sqlite3ext.h b/ext/sqlite3/libsqlite/sqlite3ext.h index 0aadb5fe81..5a59ce7450 100644 --- a/ext/sqlite3/libsqlite/sqlite3ext.h +++ b/ext/sqlite3/libsqlite/sqlite3ext.h @@ -78,7 +78,7 @@ struct sqlite3_api_routines { int (*complete)(const char*sql); int (*complete16)(const void*sql); int (*create_collation)(sqlite3*,const char*,int,void*,int(*)(void*,int,const void*,int,const void*)); - int (*create_collation16)(sqlite3*,const char*,int,void*,int(*)(void*,int,const void*,int,const void*)); + int (*create_collation16)(sqlite3*,const void*,int,void*,int(*)(void*,int,const void*,int,const void*)); int (*create_function)(sqlite3*,const char*,int,int,void*,void (*xFunc)(sqlite3_context*,int,sqlite3_value**),void (*xStep)(sqlite3_context*,int,sqlite3_value**),void (*xFinal)(sqlite3_context*)); int (*create_function16)(sqlite3*,const void*,int,int,void*,void (*xFunc)(sqlite3_context*,int,sqlite3_value**),void (*xStep)(sqlite3_context*,int,sqlite3_value**),void (*xFinal)(sqlite3_context*)); int (*create_module)(sqlite3*,const char*,const sqlite3_module*,void*); @@ -188,6 +188,11 @@ struct sqlite3_api_routines { int (*test_control)(int, ...); void (*randomness)(int,void*); sqlite3 *(*context_db_handle)(sqlite3_context*); + int (*extended_result_codes)(sqlite3*,int); + int (*limit)(sqlite3*,int,int); + sqlite3_stmt *(*next_stmt)(sqlite3*,sqlite3_stmt*); + const char *(*sql)(sqlite3_stmt*); + int (*status)(int,int*,int*,int); }; /* @@ -354,9 +359,14 @@ struct sqlite3_api_routines { #define sqlite3_test_control sqlite3_api->test_control #define sqlite3_randomness sqlite3_api->randomness #define sqlite3_context_db_handle sqlite3_api->context_db_handle +#define sqlite3_extended_result_codes sqlite3_api->extended_result_codes +#define sqlite3_limit sqlite3_api->limit +#define sqlite3_next_stmt sqlite3_api->next_stmt +#define sqlite3_sql sqlite3_api->sql +#define sqlite3_status sqlite3_api->status #endif /* SQLITE_CORE */ -#define SQLITE_EXTENSION_INIT1 const sqlite3_api_routines *sqlite3_api; +#define SQLITE_EXTENSION_INIT1 const sqlite3_api_routines *sqlite3_api = 0; #define SQLITE_EXTENSION_INIT2(v) sqlite3_api = v; #endif /* _SQLITE3EXT_H_ */ |