clones/php-src
1
0
Fork 0
mirror of https://github.com/php/php-src.git synced 2024-09-22 10:27:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

Sync libsqlite to 3.6.5

Browse Source
This commit is contained in:
Scott MacVicar 2008-11-17 17:13:11 +00:00
parent 9aa93cc8d3
commit b7d28c4815
3 changed files with 6272 additions and 4811 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10548
ext/sqlite3/libsqlite/sqlite3.c
View File

File diff suppressed because it is too large Load Diff

527
ext/sqlite3/libsqlite/sqlite3.h
View File

@ -52,29 +52,20 @@ extern "C" {
#endif
/*
** Add the ability to mark interfaces as deprecated.
** These no-op macros are used in front of interfaces to mark those
** interfaces as either deprecated or experimental. New applications
** should not use deprecated intrfaces - they are support for backwards
** compatibility only. Application writers should be aware that
** experimental interfaces are subject to change in point releases.
**
** These macros used to resolve to various kinds of compiler magic that
** would generate warning messages when they were used. But that
** compiler magic ended up generating such a flurry of bug reports
** that we have taken it all out and gone back to using simple
** noop macros.
*/
#if (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1))
/* GCC added the deprecated attribute in version 3.1 */
#define SQLITE_DEPRECATED __attribute__ ((deprecated))
#elif defined(_MSC_VER) && _MSC_VER >= 1300
#define SQLITE_DEPRECATED __declspec(deprecated)
#else
#define SQLITE_DEPRECATED
#endif
/*
** Add the ability to mark interfaces as experimental.
*/
#if (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3))
/* I can confirm that it does not work on version 4.1.0... */
/* First appears in GCC docs for version 4.3.0 */
#define SQLITE_EXPERIMENTAL __attribute__ ((warning ("is experimental")))
#elif defined(_MSC_VER) && _MSC_VER >= 1500
#define SQLITE_EXPERIMENTAL __declspec(deprecated("was declared experimental"))
#else
#define SQLITE_EXPERIMENTAL
#endif
#define SQLITE_DEPRECATED
#define SQLITE_EXPERIMENTAL
/*
** Ensure these symbols were not defined by some previous header file.
@ -116,8 +107,8 @@ extern "C" {
** 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.6.2"
#define SQLITE_VERSION_NUMBER 3006002
#define SQLITE_VERSION "3.6.5"
#define SQLITE_VERSION_NUMBER 3006005
/*
** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100>
@ -154,8 +145,9 @@ int sqlite3_libversion_number(void);
** 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
** are enabled and SQLite is threadsafe. When that macro is false,
** the [SQLITE_THREADSAFE] C preprocessor macro 1 or 2, mutexes
** are enabled and SQLite is threadsafe. When the
** [SQLITE_THREADSAFE] macro is 0,
** the mutexes are omitted. Without the mutexes, it is not safe
** to use SQLite concurrently from more than one thread.
**
@ -177,19 +169,15 @@ int sqlite3_libversion_number(void);
** only the default compile-time setting, not any run-time changes
** to that setting.
**
** See the [threading mode] documentation for additional information.
**
** INVARIANTS:
**
** {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.
** {H10101} The [sqlite3_threadsafe()] function shall return zero if
** and only if SQLite was compiled with mutexing code omitted.
**
** {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.
** shall remain the same across calls to [sqlite3_config()].
*/
int sqlite3_threadsafe(void);
@ -286,7 +274,7 @@ typedef sqlite_uint64 sqlite3_uint64;
** an [SQLITE_BUSY] error code.
**
** {H12015} A call to [sqlite3_close(C)] where C is a NULL pointer shall
** return SQLITE_OK.
** be a harmless no-op returning SQLITE_OK.
**
** {H12019} When [sqlite3_close(C)] is invoked on a [database connection] C
** that has a pending transaction, the transaction shall be
@ -390,12 +378,14 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**);
** *E to NULL if E is not NULL and 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()],
** and message accessible via [sqlite3_errcode()],
** [sqlite3_extended_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_extended_errcode()],
** [sqlite3_errmsg()], and [sqlite3_errmsg16()]
** shall reset to indicate no errors.
**
@ -597,7 +587,7 @@ int sqlite3_exec(
** 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
** to use Mac OS-X style fullsync instead of fsync().
** to use Mac OS X style fullsync instead of fsync().
*/
#define SQLITE_SYNC_NORMAL 0x00002
#define SQLITE_SYNC_FULL 0x00003
@ -629,7 +619,7 @@ struct sqlite3_file {
**
** 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 a Mac OS-X style fullsync. The [SQLITE_SYNC_DATAONLY]
** 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.
**
@ -692,6 +682,12 @@ struct sqlite3_file {
** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
** information is written to disk in the same order as calls
** to xWrite().
**
** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
** in the unread portions of the buffer with zeros. A VFS that
** fails to zero-fill short reads might seem to work. However,
** failure to zero-fill short reads will eventually lead to
** database corruption.
*/
typedef struct sqlite3_io_methods sqlite3_io_methods;
struct sqlite3_io_methods {
@ -918,24 +914,24 @@ struct sqlite3_vfs {
** sqlite3_os_init(). Similarly, sqlite3_shutdown()
** shall invoke sqlite3_os_end().
**
** The sqlite3_initialize() routine returns SQLITE_OK on success.
** 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.
** 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
** 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
** 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
@ -953,11 +949,11 @@ struct sqlite3_vfs {
** 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
** 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
** must return [SQLITE_OK] on success and some other [error code] upon
** failure.
*/
int sqlite3_initialize(void);
@ -966,7 +962,7 @@ int sqlite3_os_init(void);
int sqlite3_os_end(void);
/*
** CAPI3REF: Configuring The SQLite Library {H10145} <S20000><S30200>
** CAPI3REF: Configuring The SQLite Library {H14100} <S20000><S30200>
** EXPERIMENTAL
**
** The sqlite3_config() interface is used to make global configuration
@ -989,14 +985,103 @@ int sqlite3_os_end(void);
** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option]
** in the first argument.
**
** When a configuration option is set, sqlite3_config() returns SQLITE_OK.
** 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].
**
** INVARIANTS:
**
** {H14103} A successful invocation of [sqlite3_config()] shall return
** [SQLITE_OK].
**
** {H14106} The [sqlite3_config()] interface shall return [SQLITE_MISUSE]
** if it is invoked in between calls to [sqlite3_initialize()] and
** [sqlite3_shutdown()].
**
** {H14120} A successful call to [sqlite3_config]([SQLITE_CONFIG_SINGLETHREAD])
** shall set the default [threading mode] to Single-thread.
**
** {H14123} A successful call to [sqlite3_config]([SQLITE_CONFIG_MULTITHREAD])
** shall set the default [threading mode] to Multi-thread.
**
** {H14126} A successful call to [sqlite3_config]([SQLITE_CONFIG_SERIALIZED])
** shall set the default [threading mode] to Serialized.
**
** {H14129} A successful call to [sqlite3_config]([SQLITE_CONFIG_MUTEX],X)
** where X is a pointer to an initialized [sqlite3_mutex_methods]
** object shall cause all subsequent mutex operations performed
** by SQLite to use the mutex methods that were present in X
** during the call to [sqlite3_config()].
**
** {H14132} A successful call to [sqlite3_config]([SQLITE_CONFIG_GETMUTEX],X)
** where X is a pointer to an [sqlite3_mutex_methods] object
** shall overwrite the content of [sqlite3_mutex_methods] object
** with the mutex methods currently in use by SQLite.
**
** {H14135} A successful call to [sqlite3_config]([SQLITE_CONFIG_MALLOC],M)
** where M is a pointer to an initialized [sqlite3_mem_methods]
** object shall cause all subsequent memory allocation operations
** performed by SQLite to use the methods that were present in
** M during the call to [sqlite3_config()].
**
** {H14138} A successful call to [sqlite3_config]([SQLITE_CONFIG_GETMALLOC],M)
** where M is a pointer to an [sqlite3_mem_methods] object shall
** overwrite the content of [sqlite3_mem_methods] object with
** the memory allocation methods currently in use by
** SQLite.
**
** {H14141} A successful call to [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],1)
** shall enable the memory allocation status collection logic.
**
** {H14144} A successful call to [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],0)
** shall disable the memory allocation status collection logic.
**
** {H14147} The memory allocation status collection logic shall be
** enabled by default.
**
** {H14150} A successful call to [sqlite3_config]([SQLITE_CONFIG_SCRATCH],S,Z,N)
** where Z and N are non-negative integers and
** S is a pointer to an aligned memory buffer not less than
** Z*N bytes in size shall cause S to be used by the
** [scratch memory allocator] for as many as N simulataneous
** allocations each of size Z.
**
** {H14153} A successful call to [sqlite3_config]([SQLITE_CONFIG_SCRATCH],S,Z,N)
** where S is a NULL pointer shall disable the
** [scratch memory allocator].
**
** {H14156} A successful call to
** [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],S,Z,N)
** where Z and N are non-negative integers and
** S is a pointer to an aligned memory buffer not less than
** Z*N bytes in size shall cause S to be used by the
** [pagecache memory allocator] for as many as N simulataneous
** allocations each of size Z.
**
** {H14159} A successful call to
** [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],S,Z,N)
** where S is a NULL pointer shall disable the
** [pagecache memory allocator].
**
** {H14162} A successful call to [sqlite3_config]([SQLITE_CONFIG_HEAP],H,Z,N)
** where Z and N are non-negative integers and
** H is a pointer to an aligned memory buffer not less than
** Z bytes in size shall enable the [memsys5] memory allocator
** and cause it to use buffer S as its memory source and to use
** a minimum allocation size of N.
**
** {H14165} A successful call to [sqlite3_config]([SQLITE_CONFIG_HEAP],H,Z,N)
** where H is a NULL pointer shall disable the
** [memsys5] memory allocator.
**
** {H14168} A successful call to [sqlite3_config]([SQLITE_CONFIG_LOOKASIDE],Z,N)
** shall cause the default [lookaside memory allocator] configuration
** for new [database connections] to be N slots of Z bytes each.
*/
SQLITE_EXPERIMENTAL int sqlite3_config(int, ...);
/*
** CAPI3REF: Configure database connections {H10180} <S20000>
** CAPI3REF: Configure database connections {H14200} <S20000>
** EXPERIMENTAL
**
** The sqlite3_db_config() interface is used to make configuration
@ -1013,6 +1098,38 @@ SQLITE_EXPERIMENTAL int sqlite3_config(int, ...);
** 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.
**
** INVARIANTS:
**
** {H14203} A call to [sqlite3_db_config(D,V,...)] shall return [SQLITE_OK]
** if and only if the call is successful.
**
** {H14206} If one or more slots of the [lookaside memory allocator] for
** [database connection] D are in use, then a call to
** [sqlite3_db_config](D,[SQLITE_DBCONFIG_LOOKASIDE],...) shall
** fail with an [SQLITE_BUSY] return code.
**
** {H14209} A successful call to
** [sqlite3_db_config](D,[SQLITE_DBCONFIG_LOOKASIDE],B,Z,N) where
** D is an open [database connection] and Z and N are positive
** integers and B is an aligned buffer at least Z*N bytes in size
** shall cause the [lookaside memory allocator] for D to use buffer B
** with N slots of Z bytes each.
**
** {H14212} A successful call to
** [sqlite3_db_config](D,[SQLITE_DBCONFIG_LOOKASIDE],B,Z,N) where
** D is an open [database connection] and Z and N are positive
** integers and B is NULL pointer shall cause the
** [lookaside memory allocator] for D to a obtain Z*N byte buffer
** from the primary memory allocator and use that buffer
** with N lookaside slots of Z bytes each.
**
** {H14215} A successful call to
** [sqlite3_db_config](D,[SQLITE_DBCONFIG_LOOKASIDE],B,Z,N) where
** D is an open [database connection] and Z and N are zero shall
** disable the [lookaside memory allocator] for D.
**
**
*/
SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...);
@ -1097,7 +1214,9 @@ struct sqlite3_mem_methods {
** 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>
** environment as long as no two threads attempt to use the same
** [database connection] at the same time. See the [threading mode]
** documentation for additional information.</dd>
**
** <dt>SQLITE_CONFIG_SERIALIZED</dt>
** <dd>There are no arguments to this option. This option enables
@ -1108,11 +1227,7 @@ struct sqlite3_mem_methods {
** 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>
** See the [threading mode] documentation for additional information.</dd>
**
** <dt>SQLITE_CONFIG_MALLOC</dt>
** <dd>This option takes a single argument which is a pointer to an
@ -1217,7 +1332,7 @@ struct sqlite3_mem_methods {
#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 */
/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
/*
@ -1280,17 +1395,17 @@ 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]
** in the first argument. If no successful INSERTs
** successful [INSERT] into the database from the [database connection]
** in the first argument. If no successful [INSERT]s
** have ever occurred on that database connection, zero is returned.
**
** If an INSERT occurs within a trigger, then the rowid of the inserted
** 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
** An [INSERT] that fails due to a constraint violation is not a
** 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
@ -1299,23 +1414,24 @@ int sqlite3_extended_result_codes(sqlite3*, int onoff);
** the constraint problem so INSERT OR REPLACE will always change
** 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:
**
** {H12221} The [sqlite3_last_insert_rowid()] function returns the rowid
** of the most recent successful INSERT performed on the same
** {H12221} The [sqlite3_last_insert_rowid()] function shall return 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.
** trigger context, or zero if there have been no qualifying
** [INSERT] statements.
**
** {H12223} The [sqlite3_last_insert_rowid()] function returns the
** {H12223} The [sqlite3_last_insert_rowid()] function shall return the
** same value when called from the same trigger context
** immediately before and after a ROLLBACK.
** immediately before and after a [ROLLBACK].
**
** ASSUMPTIONS:
**
** {A12232} If a separate thread performs 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
@ -1330,8 +1446,8 @@ sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
** This function returns the number of database rows that were changed
** or inserted or deleted by the most recently completed SQL statement
** 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
** 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.
**
@ -1365,13 +1481,15 @@ sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
** 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
** by dropping and recreating the table. Doing so 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.
** "DELETE FROM table WHERE 1" instead. Or recompile using the
** [SQLITE_OMIT_TRUNCATE_OPTIMIZATION] compile-time option to disable the
** optimization on all queries.
**
** INVARIANTS:
**
@ -1413,7 +1531,9 @@ int sqlite3_changes(sqlite3*);
** 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.
** "DELETE FROM table WHERE 1" instead. Or recompile using the
** [SQLITE_OMIT_TRUNCATE_OPTIMIZATION] compile-time option to disable the
** optimization on all queries.
**
** See also the [sqlite3_changes()] interface.
**
@ -1575,6 +1695,10 @@ int sqlite3_complete16(const void *sql);
** previously set handler. Note that calling [sqlite3_busy_timeout()]
** will also set or clear the busy handler.
**
** The busy callback should not take any actions which modify the
** database connection that invoked the busy handler. Any such actions
** result in undefined behavior.
**
** INVARIANTS:
**
** {H12311} The [sqlite3_busy_handler(D,C,A)] function shall replace
@ -1888,7 +2012,7 @@ char *sqlite3_snprintf(int,char*,const char*, ...);
** memory might result in a segmentation fault or other severe error.
** Memory corruption, a segmentation fault, or other severe error
** might result if sqlite3_free() is called with a non-NULL pointer that
** was not obtained from sqlite3_malloc() or sqlite3_free().
** was not obtained from sqlite3_malloc() or sqlite3_realloc().
**
** The sqlite3_realloc() interface attempts to resize a
** prior memory allocation to be at least N bytes, where N is the
@ -2103,6 +2227,11 @@ void sqlite3_randomness(int N, void *P);
** previous call. Disable the authorizer by installing a NULL callback.
** The authorizer is disabled by default.
**
** The authorizer callback must not do anything that will modify
** the database connection that invoked the authorizer callback.
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
** database connections for the meaning of "modify" in this paragraph.
**
** When [sqlite3_prepare_v2()] is used to prepare a statement, the
** statement might be reprepared during [sqlite3_step()] due to a
** schema change. Hence, the application should ensure that the
@ -2254,7 +2383,7 @@ int sqlite3_set_authorizer(
#define SQLITE_ANALYZE 28 /* Table Name NULL */
#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
#define SQLITE_FUNCTION 31 /* Function Name NULL */
#define SQLITE_FUNCTION 31 /* NULL Function Name */
#define SQLITE_COPY 0 /* No longer used */
/*
@ -2327,7 +2456,12 @@ SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
**
** 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.
** "Cancel" button on a GUI progress dialog box.
**
** The progress handler must not do anything that will modify
** the database connection that invoked the progress handler.
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
** database connections for the meaning of "modify" in this paragraph.
**
** INVARIANTS:
**
@ -2390,7 +2524,7 @@ void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
** 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:
** [SQLITE_OPEN_NOMUTEX] or [SQLITE_OPEN_FULLMUTEX] flags:
**
** <dl>
** <dt>[SQLITE_OPEN_READONLY]</dt>
@ -2410,16 +2544,15 @@ void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
**
** 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.
** with the [SQLITE_OPEN_NOMUTEX] or [SQLITE_OPEN_FULLMUTEX] flags,
** 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 [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
** opens in the multi-thread [threading mode] as long as the single-thread
** mode has not been set at compile-time or start-time. If the
** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
** in the serialized [threading mode] unless single-thread was
** previously selected at compile-time or start-time.
**
** If the filename is ":memory:", then a private, temporary in-memory database
** is created for the connection. This in-memory database will vanish when
@ -2533,7 +2666,10 @@ int sqlite3_open_v2(
** [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.
** sqlite3_errcode() is undefined. The sqlite3_extended_errcode()
** interface is the same except that it always returns the
** [extended result code] even when extended result codes are
** disabled.
**
** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
** text that describes the error, as either UTF-8 or UTF-16 respectively.
@ -2542,6 +2678,16 @@ int sqlite3_open_v2(
** However, the error string might be overwritten or deallocated by
** subsequent calls to other SQLite interface functions.
**
** When the serialized [threading mode] is in use, it might be the
** case that a second error occurs on a separate thread in between
** the time of the first error and the call to these interfaces.
** When that happens, the second error will be reported since these
** interfaces always report the most recent result. To avoid
** this, each thread can obtain exclusive use of the [database connection] D
** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
** all calls to the interfaces listed here are completed.
**
** 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.
@ -2552,6 +2698,10 @@ int sqlite3_open_v2(
** [result code] or [extended result code] for the most recently
** failed interface call associated with the [database connection] D.
**
** {H12802} The [sqlite3_extended_errcode(D)] interface returns the numeric
** [extended result code] for the most recently
** failed interface call associated with the [database connection] 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,
@ -2563,15 +2713,18 @@ int sqlite3_open_v2(
** {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()].
** [sqlite3_errcode()], [sqlite3_extended_errcode()],
** [sqlite3_errmsg()], or [sqlite3_errmsg16()].
**
** {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
** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].
** [sqlite3_errcode()], [sqlite3_extended_errcode()],
** [sqlite3_errmsg()], or [sqlite3_errmsg16()].
*/
int sqlite3_errcode(sqlite3 *db);
int sqlite3_extended_errcode(sqlite3 *db);
const char *sqlite3_errmsg(sqlite3*);
const void *sqlite3_errmsg16(sqlite3*);
@ -2840,7 +2993,7 @@ int sqlite3_prepare16_v2(
);
/*
** CAPIREF: Retrieving Statement SQL {H13100} <H13000>
** CAPI3REF: Retrieving Statement SQL {H13100} <H13000>
**
** 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
@ -3838,7 +3991,8 @@ int sqlite3_reset(sqlite3_stmt *pStmt);
** characters. Any attempt to create a function with a longer name
** will result in [SQLITE_ERROR] being returned.
**
** The third parameter is the number of arguments that the SQL function or
** The third parameter (nArg)
** 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.
**
@ -3869,72 +4023,91 @@ int sqlite3_reset(sqlite3_stmt *pStmt);
** functions with the same name but with either differing numbers of
** arguments or differing preferred text encodings. SQLite will use
** the implementation most closely matches the way in which the
** SQL function is used.
** SQL function is used. A function implementation with a non-negative
** nArg parameter is a better match than a function implementation with
** a negative nArg. A function where the preferred text encoding
** matches the database encoding is a better
** match than a function where the encoding is different.
** A function where the encoding difference is between UTF16le and UTF16be
** is a closer match than a function where the encoding difference is
** between UTF8 and UTF16.
**
** Built-in functions may be overloaded by new application-defined functions.
** The first application-defined function with a given name overrides all
** built-in functions in the same [database connection] with the same name.
** Subsequent application-defined functions of the same name only override
** prior application-defined functions that are an exact match for the
** number of parameters and preferred encoding.
**
** An application-defined function is permitted to call other
** SQLite interfaces. However, such calls must not
** close the database connection nor finalize or reset the prepared
** statement in which the function is running.
**
** INVARIANTS:
**
** {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
** {H16103} The [sqlite3_create_function16(D,X,...)] interface shall behave
** as [sqlite3_create_function(D,X,...)] in every way except that it
** interprets the X argument as zero-terminated UTF-16
** native byte order instead of as zero-terminated UTF-8.
**
** {H16106} A successful invocation of
** the [sqlite3_create_function(D,X,N,E,...)] interface registers
** {H16106} A successful invocation of the
** [sqlite3_create_function(D,X,N,E,...)] interface shall register
** or replaces callback functions in the [database connection] D
** used to implement the SQL function named X with N parameters
** and having a preferred text encoding of E.
**
** {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
** shall replace the P, F, S, and L values from any prior calls with
** the same D, X, N, and E values.
**
** {H16112} The [sqlite3_create_function(D,X,...)] interface fails with
** a return code of [SQLITE_ERROR] if the SQL function name X is
** {H16112} The [sqlite3_create_function(D,X,...)] interface shall fail
** if the SQL function name X is
** longer than 255 bytes exclusive of the zero terminator.
**
** {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].
** {H16118} The [sqlite3_create_function(D,X,N,E,P,F,S,L)] interface
** shall fail unless either F is NULL and S and L are non-NULL or
*** F is non-NULL and S and L are NULL.
**
** {H16121} The [sqlite3_create_function(D,...)] interface fails with an
** {H16121} The [sqlite3_create_function(D,...)] interface shall fails with an
** error code of [SQLITE_BUSY] if there exist [prepared statements]
** associated with the [database connection] D.
**
** {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
** {H16124} The [sqlite3_create_function(D,X,N,...)] interface shall fail with
** an error code of [SQLITE_ERROR] if parameter N is less
** than -1 or greater than 127.
**
** {H16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)]
** interface causes callbacks to be invoked for the SQL function
** interface shall register callbacks to be invoked for the
** SQL function
** named X when the number of arguments to the SQL function is
** exactly 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.
** interface shall register callbacks to be invoked for the SQL
** function named X with any number of arguments.
**
** {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.
** the implementation with a non-zero N shall be preferred.
**
** {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.
** database encoding shall preferred.
**
** {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
** function L shall always be invoked exactly once if the
** step function S is called one or more times.
**
** {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
** third parameter are always [protected sqlite3_value] objects.
** third parameter shall be [protected sqlite3_value] objects.
*/
int sqlite3_create_function(
sqlite3 *db,
@ -3978,14 +4151,16 @@ int sqlite3_create_function16(
** 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.
** using these functions, we are not going to tell you what they do.
*/
#ifndef SQLITE_OMIT_DEPRECATED
SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
SQLITE_DEPRECATED int sqlite3_global_recover(void);
SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);
#endif
/*
** CAPI3REF: Obtaining SQL Function Parameter Values {H15100} <S20200>
@ -4846,6 +5021,14 @@ sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
** If another function was previously registered, its
** pArg value is returned. Otherwise NULL is returned.
**
** The callback implementation must not do anything that will modify
** the database connection that invoked the callback. Any actions
** to modify the database connection must be deferred until after the
** completion of the [sqlite3_step()] call that triggered the commit
** or rollback hook in the first place.
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
** database connections for the meaning of "modify" in this paragraph.
**
** Registering a NULL function disables the callback.
**
** For the purposes of this API, a transaction is said to have been
@ -4920,6 +5103,13 @@ void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
** The update hook is not invoked when internal system tables are
** modified (i.e. sqlite_master and sqlite_sequence).
**
** The update hook implementation must not do anything that will modify
** the database connection that invoked the update hook. Any actions
** to modify the database connection must be deferred until after the
** completion of the [sqlite3_step()] call that triggered the update hook.
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
** database connections for the meaning of "modify" in this paragraph.
**
** If another function was previously registered, its pArg value
** is returned. Otherwise NULL is returned.
**
@ -5603,6 +5793,7 @@ typedef struct sqlite3_blob sqlite3_blob;
**
** {H17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)]
** then subsequent calls to [sqlite3_errcode(D)],
** [sqlite3_extended_errcode()],
** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return
** information appropriate for that error.
**
@ -5716,6 +5907,7 @@ int sqlite3_blob_bytes(sqlite3_blob *);
**
** {H17868} If an error occurs during evaluation of [sqlite3_blob_read(P,...)]
** then subsequent calls to [sqlite3_errcode(D)],
** [sqlite3_extended_errcode()],
** [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.
@ -5785,6 +5977,7 @@ int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
**
** {H17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)]
** then subsequent calls to [sqlite3_errcode(D)],
** [sqlite3_extended_errcode()],
** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return
** information appropriate for that error.
*/
@ -6082,6 +6275,17 @@ int sqlite3_mutex_notheld(sqlite3_mutex*);
#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
#define SQLITE_MUTEX_STATIC_LRU2 7 /* lru page list */
/*
** CAPI3REF: Retrieve the mutex for a database connection {H17002} <H17000>
**
** This interface returns a pointer the [sqlite3_mutex] object that
** serializes access to the [database connection] given in the argument
** when the [threading mode] is Serialized.
** If the [threading mode] is Single-thread or Multi-thread then this
** routine returns a NULL pointer.
*/
sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
/*
** CAPI3REF: Low-Level Control Of Database Files {H11300} <S30800>
**
@ -6177,25 +6381,6 @@ int sqlite3_test_control(int op, ...);
*/
SQLITE_EXPERIMENTAL 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_EXPERIMENTAL int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
/*
** CAPI3REF: Status Parameters {H17250} <H17200>
@ -6285,7 +6470,27 @@ SQLITE_EXPERIMENTAL int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiw
#define SQLITE_STATUS_SCRATCH_SIZE 8
/*
** CAPI3REF: Status Parameters for database connections {H17275} <H17200>
** CAPI3REF: Database Connection Status {H17500} <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 requested 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()] and [sqlite3_stmt_status()].
*/
SQLITE_EXPERIMENTAL int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
/*
** CAPI3REF: Status Parameters for database connections {H17520} <H17500>
** EXPERIMENTAL
**
** Status verbs for [sqlite3_db_status()].
@ -6298,6 +6503,58 @@ SQLITE_EXPERIMENTAL int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiw
*/
#define SQLITE_DBSTATUS_LOOKASIDE_USED 0
/*
** CAPI3REF: Prepared Statement Status {H17550} <S60200>
** EXPERIMENTAL
**
** Each prepared statement maintains various
** [SQLITE_STMTSTATUS_SORT | counters] that measure the number
** of times it has performed specific operations. These counters can
** be used to monitor the performance characteristics of the prepared
** statements. For example, if the number of table steps greatly exceeds
** the number of table searches or result rows, that would tend to indicate
** that the prepared statement is using a full table scan rather than
** an index.
**
** This interface is used to retrieve and reset counter values from
** a [prepared statement]. The first argument is the prepared statement
** object to be interrogated. The second argument
** is an integer code for a specific [SQLITE_STMTSTATUS_SORT | counter]
** to be interrogated.
** The current value of the requested counter is returned.
** If the resetFlg is true, then the counter is reset to zero after this
** interface call returns.
**
** See also: [sqlite3_status()] and [sqlite3_db_status()].
*/
SQLITE_EXPERIMENTAL int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
/*
** CAPI3REF: Status Parameters for prepared statements {H17570} <H17550>
** EXPERIMENTAL
**
** These preprocessor macros define integer codes that name counter
** values associated with the [sqlite3_stmt_status()] interface.
** The meanings of the various counters are as follows:
**
** <dl>
** <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt>
** <dd>This is the number of times that SQLite has stepped forward in
** a table as part of a full table scan. Large numbers for this counter
** may indicate opportunities for performance improvement through
** careful use of indices.</dd>
**
** <dt>SQLITE_STMTSTATUS_SORT</dt>
** <dd>This is the number of sort operations that have occurred.
** A non-zero value in this counter may indicate an opportunity to
** improvement performance through careful use of indices.</dd>
**
** </dl>
*/
#define SQLITE_STMTSTATUS_FULLSCAN_STEP 1
#define SQLITE_STMTSTATUS_SORT 2
/*
** Undo the hack that converts floating point types to integer for
** builds on processors without floating point support.

8
ext/sqlite3/libsqlite/sqlite3ext.h
View File

@ -208,7 +208,9 @@ struct sqlite3_api_routines {
*/
#ifndef SQLITE_CORE
#define sqlite3_aggregate_context sqlite3_api->aggregate_context
#ifndef SQLITE_OMIT_DEPRECATED
#define sqlite3_aggregate_count sqlite3_api->aggregate_count
#endif
#define sqlite3_bind_blob sqlite3_api->bind_blob
#define sqlite3_bind_double sqlite3_api->bind_double
#define sqlite3_bind_int sqlite3_api->bind_int
@ -264,14 +266,18 @@ struct sqlite3_api_routines {
#define sqlite3_errmsg sqlite3_api->errmsg
#define sqlite3_errmsg16 sqlite3_api->errmsg16
#define sqlite3_exec sqlite3_api->exec
#ifndef SQLITE_OMIT_DEPRECATED
#define sqlite3_expired sqlite3_api->expired
#endif
#define sqlite3_finalize sqlite3_api->finalize
#define sqlite3_free sqlite3_api->free
#define sqlite3_free_table sqlite3_api->free_table
#define sqlite3_get_autocommit sqlite3_api->get_autocommit
#define sqlite3_get_auxdata sqlite3_api->get_auxdata
#define sqlite3_get_table sqlite3_api->get_table
#ifndef SQLITE_OMIT_DEPRECATED
#define sqlite3_global_recover sqlite3_api->global_recover
#endif
#define sqlite3_interrupt sqlite3_api->interruptx
#define sqlite3_last_insert_rowid sqlite3_api->last_insert_rowid
#define sqlite3_libversion sqlite3_api->libversion
@ -309,7 +315,9 @@ struct sqlite3_api_routines {
#define sqlite3_thread_cleanup sqlite3_api->thread_cleanup
#define sqlite3_total_changes sqlite3_api->total_changes
#define sqlite3_trace sqlite3_api->trace
#ifndef SQLITE_OMIT_DEPRECATED
#define sqlite3_transfer_bindings sqlite3_api->transfer_bindings
#endif
#define sqlite3_update_hook sqlite3_api->update_hook
#define sqlite3_user_data sqlite3_api->user_data
#define sqlite3_value_blob sqlite3_api->value_blob